# 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.