Integration-backed playbook app happy path

Use this guide after integration_bootstrap proves the integration already works, or when integration and secret state are already clear enough to verify quickly.

Recommended sequence

1. Discover integration and secret state.
   • Use search to inspect saved integrations and secret references.
   • Read full integration metadata only when you need the exact names, hosts, or API base URL.
2. Verify the required integration exists.
   • For OAuth: confirm the integration name, required hosts, and API base URL match the app you are about to build (tokens live on the connection).
   • For secret-backed auth: confirm the secret names and allowed hosts match.
3. Run one cheap authenticated smoke test in execute.
   • Prefer a small read-only request such as GET /me, GET /viewer, or GET /v1/me.
4. If the smoke test passes, proceed directly to building the playbook app.
   • Prefer a saved playbook with package.json#kody.app.entry.
   • Load guide: "playbook_authoring" and keep human README.md (including ## Intent) and agent AGENTS.md aligned with the user's goal. Load guide: "playbook_apps" for session handoff, playbookAppFetch, and mount-prefixed asset URLs.
   • Keep provider API calls and durable coordination in playbook-owned backend modules or internal Worker/DO implementation details.
5. Open the hosted playbook app and iterate.
   • Save with playbookSave.
   • Reopen with the hosted playbook URL.
   • Iterate on the hosted playbook app instead of repeatedly pasting large inline HTML blobs back into model context.

Default playbook app shape

For non-trivial or integration-backed playbook apps, prefer this split:

• playbook app entry: Worker-style fetch surface declared by package.json#kody.app.entry
• playbook exports: reusable modules and callable default exports declared in package.json.exports
• durable data: playbookStorage() for the shared playbook bucket
• internal backend modules / Durable Objects / facets: app-internal realtime and coordination details (integration lookups, provider API calls, validation, mutations) — not the persistence mechanism
• inline HTML/code renders: acceptable for quick prototypes or one-off experiments, not the default playbook app pattern

Avoid this detour

If the integration state, hosts, secret names (when applicable), and provider contract are already clear enough, do not spend extra time spelunking the local repo before building the app.

Inspect local source only when you specifically need repo conventions, shared helpers, or an existing playbook to extend.