@odla-ai/cli 0.20.1 → 0.20.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.20.1",
+  "version": "0.20.2",
   "description": "Agent-operable CLI for odla provisioning, calendar consent and sync lifecycle, System AI administration, Worker secrets, security jobs, and smoke checks.",
   "license": "MIT",
   "homepage": "https://odla.ai/docs/packages/cli",

package/skills/odla-migrate/SKILL.md

@@ -105,8 +105,11 @@ so this is a natural first step.
 - `npx @odla-ai/cli smoke --env dev` — live, read-only: public-config, live
   schema diff, a count aggregate. Run after every provision.
 - `wrangler dev` + curl — exercise routes locally before deploying.
-- Parity curls — compare the old and new site on representative paths
-  (Phase 1, again from the public domain in Phase 5).
+- Contract probes — compare old and new method/auth/request/response schemas,
+  status and relevant headers, not just paths or equal values (Phase 1, again
+  from the public domain in Phase 5). Record source commit and immutable
+  deployment version separately; an unversioned live response does not prove
+  what the current branch implements.
 
 ## Phase files
 

package/skills/odla-migrate/references/phase-0-preflight.md

@@ -16,6 +16,11 @@ Human obligation: none.
      `.github/workflows/*` using deploy-pages.
    - Dynamic wishes: forms posting to third parties, `mailto:` contact,
      localStorage used as a database, TODOs mentioning login/db.
+   - Every route's method/path, current consumer, owning source file, request and
+     response contract, auth/cache behavior, and evidence. Source evidence is a
+     path + commit; deployed evidence is an origin + immutable deployment
+     version. Never infer current-branch ownership from an unversioned deployed
+     response, an old branch, or git history.
 2. Ensure the build outputs to a DEDICATED directory (`dist/`, `_site/`,
    `build/`). If the site is served from the repo root, restructure so a
    build step (even a copy script) produces a clean output dir first.

package/skills/odla-migrate/references/phase-2-chapter.md

@@ -22,12 +22,15 @@ hand-author only the namespaces it does not.
    });
    ```
    Then diff `chapter.schema` against the site's existing schema **in a test** and
-   require equality. That single assertion is what makes the deletion safe rather
-   than hopeful.
-2. **Freeze the old schema as a fixture, don't just delete it.** Move it to
-   `test/fixtures/legacy-schema.mjs` and keep asserting against it, so an upstream
-   default change fails a test instead of a live `provision`. It costs nothing and
-   is the only durable guard against drift in a generated schema.
+   require equality.
+2. **Prove the comparator is independent.** Anchor the reviewed legacy side to
+   an exact checked-in source path + commit + digest, or copy it to a literal
+   `test/fixtures/legacy-schema.mjs`. It must not import Chapter, the active
+   schema/descriptor alias, or another generated candidate, and the migration
+   change must not silently update both sides. Deliberately remove or alter one
+   known field/rule and prove the test fails before trusting a green result.
+   Keep this guard after deletion so an upstream default change fails a test
+   instead of a live `provision`.
 3. **Swap provisioning** — `createChapterIntegration(chapter)` in
    `odla.config.mjs` `integrations: [...]`. Inert until the next provision run. It
    supplies schema + rules + seeds, so the `db` block goes away entirely.
@@ -74,8 +77,16 @@ These bite silently; no smoke test catches them.
   `crm_record` mirrors identity, stage, billing, and Clerk linkage. Leader →
   follower delivery intentionally copies allowlisted record fields only, not
   another site's pipeline/account/billing authority.
-- **Route names.** chapter serves `/api/config`, `/api/join-config`. Alias legacy
-  names in ~4 lines as host routes rather than rewriting pages.
+- **Route contracts.** Chapter owns `/api/config` and the group-scoped
+  `/api/join-config`, but a matching path or matching monetary values do not
+  make it a drop-in replacement. Compare method, auth, request body, response
+  status, keys/types/nesting, units, null/omission semantics, and relevant
+  headers. Chapter 0.25's join-config returns raw cents, policy copy, and
+  readiness; it does not supply a legacy route's prebuilt Stripe line items or
+  publishable key. Adopt `JoinIsland` end to end or keep a tested adapter.
+  `PaymentStep` gets `clientSecret`, `publishableKey`, and `lineItems` from
+  `POST /api/payments/subscription` after the application is submitted and the
+  refund policy is acknowledged.
 - **Follower record types.** A follower rejects a pushed business/deal if its own
   CRM does not declare that type and fields. Add the type to the follower config
   and expose it through the standard console before enabling the target in the
@@ -95,7 +106,9 @@ These bite silently; no smoke test catches them.
 ## Verify the surface from the types
 
 Docs lag at this release cadence. **Read `dist/*.d.ts` and grep the built bundle
-for route strings; treat prose as intent.** When verifying live routes, note that
-Clerk session tokens expire in ~60s — a script that mints a JWT then runs a batch
-of curls must re-mint per batch (`clerk api /sessions`, then
-`/sessions/<id>/tokens`).
+for route strings; treat prose as intent.** A deployed response proves only the
+immutable deployment version you actually probed, not the route owner or
+contract of the branch in front of you. Record source path + commit and deployed
+Worker version separately. When verifying live routes, note that Clerk session
+tokens expire in ~60s — a script that mints a JWT then runs a batch of curls must
+re-mint per batch (`clerk api /sessions`, then `/sessions/<id>/tokens`).

package/skills/odla-migrate/references/phase-5-cutover.md

@@ -41,8 +41,11 @@ instance, never a second Clerk app per env; final go/no-go at each step.
    --env prod --plan-digest <digest-from-security-plan>
    --ack-redacted-source`. Never request a PAT; GitHub read approval is not
    snippet-disclosure consent.
-4. `npx wrangler deploy` (first prod deploy). Verify
-   `/api/health` and the parity paths on the prod workers.dev URL.
+4. `npx wrangler deploy` (first prod deploy). Record the immutable Worker
+   version and source commit, then verify `/api/health` and the full
+   request/response contracts on the prod workers.dev URL. Equal payload values
+   with different keys, nesting, types, units, or omission behavior are not
+   parity.
 5. `npx @odla-ai/cli smoke --env prod`.
 6. Human: add the domain to Cloudflare, then attach it to the prod
    worker (Workers & Pages → the worker → Domains & Routes). Supply
@@ -50,7 +53,9 @@ instance, never a second Clerk app per env; final go/no-go at each step.
 7. Cut DNS. GitHub Pages STAYS PUBLISHED — if anything looks wrong,
    the rollback is pointing DNS back at Pages.
 8. Verify from the public domain: parity paths, the gated route (signed
-   in and out), `/api/*` routes, the AI route if present.
+   in and out), `/api/*` routes, the AI route if present. Use a unique
+   non-secret query value and capture cache/version headers so an earlier
+   edge-cached response cannot masquerade as the deployed build.
 9. Update MIGRATION.md: cutover timestamp, verification results, and a
    dated reminder ≥ 72 hours out to decommission Pages.
 10. After ≥ 72 hours of clean parallel-run and explicit human

package/skills/odla-migrate/references/troubleshooting.md

@@ -100,6 +100,21 @@ Cause: the Clerk session token doesn't include an email claim.
 Fix: Clerk dashboard → session token customization → add the email
 claim, then re-test. The worker only forwards what the JWT carries.
 
+## A newly deployed route still returns 404
+
+Cause: the request may be reaching an older Worker/deployment, or an edge cache
+may still hold a response from before the route, configuration, or credential
+became ready. A deployed URL is also not proof that the checked-out branch owns
+that route.
+
+Fix: first identify the checked-in owner from the exact source path and commit.
+Confirm the deployed immutable Worker version matches that commit. Probe both
+the direct workers.dev candidate and the public domain with a unique non-secret
+query value; capture `Age`, `Cache-Control`, `CF-Cache-Status`, `ETag`, and the
+Worker version marker. Re-test after the documented propagation/cache window.
+File a route bug only if the intended version reproduces with fresh evidence.
+Never rotate a key or rewrite the route merely to defeat a cached response.
+
 ## Re-running provision — is it safe?
 
 Yes: plain re-runs are idempotent (existing app registration and configured db