# Integration-backed package 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.
   - Confirm the integration name, token secret names, and API base URL match
     the app you are about to build.
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 package app.
   - Prefer a saved package with `package.json#kody.app.entry`.
   - Load `guide: "package_authoring"` and keep the package README `## Intent`
     section aligned with the user's goal.
   - Keep provider API calls and durable coordination in package-owned backend
     modules or internal Worker/DO implementation details.
5. Open the hosted package app and iterate.
   - Save with `package_save`.
   - Reopen with the hosted package URL.
   - Iterate on the hosted package app instead of repeatedly pasting large
     inline HTML blobs back into model context.

## Default package app shape

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

- package app entry: Worker-style fetch surface declared by
  `package.json#kody.app.entry`
- package exports: reusable modules and callable default exports declared in
  `package.json.exports`
- durable data: `packageStorage()` for the shared package bucket
- long-lived coordination / alarms: a package service
  (`package.json#kody.services`) when the app needs background-managed work
- 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 package app pattern

## Avoid this detour

If the integration state, secret names, allowed hosts, 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 package to extend.