@odla-ai/cli 0.17.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "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/SKILL.md

@@ -9,6 +9,7 @@ description: >
 runbookOrder:
   - references/build.md
   - references/sdks.md
+  - references/pm.md
   - references/co-owners.md
 ---
 
@@ -41,6 +42,13 @@ State which path you're taking and what you'll build in one line; get a nod.
    A fresh odla device request also needs the existing account email via
    `--email` or `ODLA_USER_EMAIL`; email is a non-secret identifier. Never ask
    for an odla password, Clerk token, or browser session.
+   **That is the human's odla ACCOUNT email — never infer it from `git config
+   user.email`, `gh`, or a commit author.** A git identity is frequently a
+   different address (a `+alias`, a `users.noreply.github.com`), and the
+   registry matches the exact string. An address that is not a registered
+   account does NOT error: it mints an indistinguishable decoy, so the CLI
+   prints a normal approval URL that can never be approved by anyone. Ask the
+   human, or reuse the address already in `.odla/handshake.local.json`.
 2. **Sandbox before live.** Every app has two databases on production odla.ai:
    a sandbox (env `dev`, tenant `<appId>--dev`) and a live one (env `prod`,
    tenant `<appId>`). "prod" names the app's live DATABASE, never a different
@@ -129,6 +137,109 @@ guessing which platform/credential steps need manual work. Then:
    show the human, then `npx @odla-ai/cli provision --yes --push-secrets` and
    `npx wrangler deploy`.
 
+## Track the work in PM, as you go
+
+odla has a project manager for agents — conformance goals, a kanban board, a
+decision log, and bugs, shared with the human and with every other agent working
+on the app. It is platform-side: nothing to install or provision. Start a session
+by reading it, and keep it current while you build:
+
+```cmd
+npx @odla-ai/cli pm task list --app <appId> --column doing
+```
+
+Record a **decision** the moment you make one (with what it rules out), file a
+**bug** the moment you notice one, and move a **task** when the work moves. A
+decision you don't record is one the next agent re-litigates. Full command set,
+conventions, and the read-first session opener: `references/pm.md`.
+
+## Operational runbooks live in the database, not in this bundle
+
+This bundle covers **setup**, pinned to the CLI version you installed. Operational
+procedures — releasing, backups, database and code-runtime operations — are stored
+in odla and change without a CLI release. Read one at the moment you follow it:
+
+```cmd
+npx @odla-ai/cli runbook list
+```
+
+```cmd
+npx @odla-ai/cli runbook get release
+```
+
+`runbook get` prints raw markdown, so pipe it or read it directly. Do not follow a
+multi-step platform procedure from memory, and never scrape odla.ai for one — the
+CLI reads the same content authenticated and current.
+
+Answering a question rather than following a procedure? `ask` returns a written,
+cited answer; `search` returns the **sections** behind it, each with its source
+and the command to pull the rest:
+
+```cmd
+npx @odla-ai/cli runbook ask "how do I roll back a bad publish?"
+```
+
+```cmd
+npx @odla-ai/cli runbook search "roll back a bad publish"
+```
+
+Cite what you quote — `release#rolling-back-a-bad-publish (v3)` — so the reader
+can check it. An agent holding the PM skill has the same reach as tools:
+`search_runbooks` (question in, cited sections out), `read_runbook` (whole
+runbook, or one `section`), and `amend_runbook` for this project's own.
+
+**A runbook is half the answer.** It carries the procedure — the order, the
+gates, the commands. What an export takes, returns, and guarantees is the JSDoc
+on that symbol: shipped in the installed package's `dist/*.d.ts` and rendered at
+`https://odla.ai/docs/packages/<pkg>`. When a step calls an odla API, take the
+step from the runbook and the arguments from the JSDoc. Never fill in a
+signature, a default, or a return shape from memory — you do not have the
+installed version in front of you, and the runbook is not claiming to describe it.
+
+### After you change something, ask what you invalidated
+
+```cmd
+npx @odla-ai/cli runbook impact
+```
+
+It diffs your working tree against `origin/main` (`--base <ref>` for anything
+else, uncommitted work included), works out which surfaces moved — the package,
+the exports whose declaration or **JSDoc** changed, the console area — and names
+the runbooks whose steps describe them, with the command to read each one.
+
+Run it after touching an exported API, a doc comment, a package version, or a
+Studio surface. Editing a JSDoc block is exactly the moment a procedure that
+quotes that API can go stale, and nothing else will catch it: a runbook lives in
+the database, so no build, test, or CI gate in the repository can see it drift
+from your code. Reread what it names and fix any step your change made wrong,
+in the same piece of work.
+
+The other direction — are the runbooks themselves still true?
+
+```cmd
+npx @odla-ai/cli runbook lint
+```
+
+Every `odla-ai …` command the runbooks name is held against this CLI's real
+command surface, and against the minimum versions each runbook declares. Because
+a runbook is edited without a release, its text can name a command only a newer
+package has; a runbook records that as `requires` (`@odla-ai/cli@0.18.0`), and
+`runbook get` warns on stderr when yours is older. If you add a command and then
+tell a runbook to use it, set `requires` in the same edit — otherwise the first
+reader on an older CLI gets an "unknown action" error instead of an explanation.
+
+Found a wrong step? Fix an app runbook directly. For a platform runbook,
+`runbook edit` requests an admin-approved capability — a plain handshake token is
+never admin, and `npx @odla-ai/cli whoami` tells you what you hold.
+
+⏸ That request prints an approval block with a URL on its own line. **Relay that
+URL to the human verbatim, immediately, before you wait on anything.** You cannot
+approve it yourself — the grant is issued to you, not by you — and the command
+blocks until a signed-in admin approves it. The browser launch is best-effort and
+often shows no tab, so the printed URL is the only thing the human can rely on.
+If approval is not available, comment on the runbook instead so an admin can fix
+it later.
+
 `npx @odla-ai/cli doctor` is an offline config check anytime;
 `npx @odla-ai/cli smoke --env dev` verifies a live deployment.
 Use `calendar status --json` for safe connection state (`bookable`, booking
@@ -163,6 +274,9 @@ code, paste a publishable key, run a command) — and wait for a nod.
   exported TypeScript declarations/JSDoc (resolve entry points through its
   `package.json` `exports`). Rendered references are also public at
   `https://odla.ai/docs/packages/<pkg>`.
+- `references/pm.md` — the project manager for agents: goals, board, decisions,
+  bugs. What to file where, the `pm` command set, and how to open and close a
+  session against it.
 - `references/co-owners.md` — sharing one app's db and tooling across a team:
   `app owners add/list/remove`, and how each co-owner self-provisions their own
   credentials (dev and the shared prod database) without any secret handoff.

package/skills/odla/references/pm.md

@@ -0,0 +1,109 @@
+# PM — the project's memory, for agents
+
+odla ships a project manager built for the agents doing the work:
+**conformance goals**, a kanban **board**, a **decision** log, and **bugs**. It is
+not a status report for a human to read later — it is your working memory across
+sessions, and the place another agent (or the human) picks up what you learned.
+
+Use it. A decision you don't record is one the next agent re-litigates; a bug you
+only mention in chat is a bug nobody fixes.
+
+## What it is, mechanically
+
+- PM data lives on the **platform**, in odla's own shared store — *not* in the
+  app's database. There is nothing to install, schema, or provision, and no
+  entry in `odla.config.mjs`.
+- Every item is tagged with an **appId**, and access rides **app co-ownership**:
+  you see and write PM items for exactly the apps you co-own
+  (`references/co-owners.md`). Co-own three apps and one `pm bug list` spans all
+  three.
+- Auth is the same developer device grant the rest of the CLI uses. The first
+  `pm` command in a fresh checkout may print an approval code — relay it to the
+  human verbatim, same as `provision`.
+- The human's view of the same data is **https://odla.ai/studio/pm** (and each
+  app's **Project** tab in Studio): the board is drag-and-drop there, and every
+  section filters by project.
+
+## The four things, and when each one is right
+
+| You have | File it as | Because |
+| --- | --- | --- |
+| an outcome that must be true, plus the test that proves it | **goal** | it carries `--proof`; `pm goal done` means the proof passed, not "I think it works" |
+| a specific unit of work | **task** | it has a board column, so the human can see what is moving |
+| a choice that closes off alternatives | **decision** | the log is full-text searchable, so the *next* agent finds the why |
+| something that is broken | **bug** | it has a severity and survives the session that noticed it |
+
+Do not file a task per keystroke. One task per thing a human would recognise as a
+piece of work; one decision per choice you would otherwise bury in a commit
+message; one bug per defect.
+
+## The commands
+
+Entity is `goal | task | decision | bug`; every command takes `--json` for
+machine-readable output.
+
+```cmd
+npx @odla-ai/cli pm bug add --app <appId> --title "Checkout 500s on retry" --severity high --desc "…"
+```
+
+```cmd
+npx @odla-ai/cli pm bug list --app <appId> --status open
+```
+
+```cmd
+npx @odla-ai/cli pm task set <id> --column doing
+```
+
+```cmd
+npx @odla-ai/cli pm decision list --q "stripe"
+```
+
+- `add` needs `--app <appId>` and `--title`; it takes the entity's own fields
+  (`--proof`, `--target` for goals; `--column`, `--goal`, `--assignee`, `--due`
+  for tasks; `--body` for decisions; `--severity`, `--desc` for bugs).
+- `list` filters with `--status`, `--severity`, `--column`, `--assignee`,
+  `--goal`, full-text `--q`, and pages with `--limit` / `--offset`. **With no
+  `--app` it spans every project you co-own** — that is the cross-project view,
+  and it is usually the one you want when you start a session.
+- `get <id>` prints one item; `set <id> --<field> <value>` patches it
+  (`--no-<field>` clears an optional field); `done <id>` is the shortcut for the
+  terminal state (goal → met, task → done, decision → accepted, bug → fixed).
+- `comment <id> --body "…"` and `comments <id>` are the item's discussion thread.
+  Status and column changes post there automatically, so the thread is the audit
+  trail — the human sees what you did without asking.
+- `rm <id>` deletes. Prefer `done` or a status change; deletion loses the thread.
+
+## Working with it
+
+**At the start of a session**, read before you write:
+
+```cmd
+npx @odla-ai/cli pm task list --app <appId> --column doing
+```
+
+then `pm bug list --app <appId> --status open` and
+`pm decision list --app <appId> --limit 10`. That is the state of the project in
+three commands — including anything a *different* agent left behind.
+
+**While you build:**
+
+- Move the card when the work moves — `pm task set <id> --column doing` when you
+  start, `pm task done <id>` when it is really done (tests green, not "written").
+- Record a decision the moment you make it, with what it rules out:
+  `pm decision add --app <appId> --title "Bun over tsx for the worker build"
+  --body "…"`. This is the single highest-value thing you can do here.
+- File a bug the moment you notice it, even mid-task, even if it is not yours.
+  `--severity critical|high|medium|low`. Then keep going — the bug is captured,
+  so it does not have to derail what you are doing.
+- A goal is how you say what "done" means before you start:
+  `pm goal add --app <appId> --title "Checkout survives a retry storm" --proof
+  "test/checkout-retry.test.ts"`. Mark it met only when that proof passes.
+
+**Never** put a secret, a token, or a credential in a title, body, description,
+or comment. PM items are shared with every co-owner of the app.
+
+## Checkpoints
+
+PM writes are not destructive and need no approval — file freely. Deleting an
+item (`pm … rm`) and closing something you did not open are the two calls to
+put to the human first.

package/skills/odla/references/sdks.md

@@ -12,6 +12,7 @@ default-deny `src/odla/rules.mjs`. Isomorphic (browser + Worker).
 
 ```ts
 // browser client — token from your IdP (Clerk):
+import { OdlaProvider, useQuery, useTransact } from "@odla-ai/db/preact";
 const db = init({ appId, endpoint, getToken });
 const { data } = useQuery({ notes: { $: { order: { createdAt: "asc" } } } });
 transact(db.tx.notes[crypto.randomUUID()].update({ text, createdAt: Date.now() }));
@@ -20,7 +21,7 @@ transact(db.tx.notes[crypto.randomUUID()].update({ text, createdAt: Date.now() }
 Worker/admin side: `init({ appId: tenantId, adminToken: env.ODLA_API_KEY, endpoint })`
 — the admin key bypasses rules, so a worker-mediated backend needs none.
 
-## @odla-ai/auth-clerk — sign-in (Clerk; runs on Preact or React)
+## @odla-ai/auth-clerk — native Preact sign-in (Clerk)
 
 ```tsx
 <ClerkGate publishableKey={pk} appearance={clerkAppearanceFromTokens()}>
@@ -158,10 +159,12 @@ injected isolated executor and never falls back to the host shell.
 - **@odla-ai/chapter** — membership sites from one `defineChapter()` config:
   generates the odla-db schema + deny-all rules + group seed + provisioning
   integration, and ships the worker (join/apply, Stripe membership, Google
-  booking, member area, exactly-once lifecycle email, CRM projection) plus a UI
-  kit. Composable: `chapterWorker({ chapter, routes })` runs host routes before
-  the built-ins and shares its auth context, and `./ui/member` is react-only
-  (no Clerk SDK) while `./ui/admin` is the gated console. **If a migration target
+  booking, member area, exactly-once lifecycle email, CRM projection, and
+  leader → follower record delivery) plus a UI kit. Composable:
+  `chapterWorker({ chapter, routes })` runs host routes before the built-ins and
+  shares its auth context; `<ChapterAdmin chapter={chapter}/>` derives the
+  familiar brand/section shell and uses host-independent `?tab=` routing;
+  `./ui/member` is Preact-only (no Clerk SDK). **If a migration target
   is a membership site, start here instead of hand-authoring schema** — see
   `odla-migrate/references/phase-2-chapter.md`.
 - **@odla-ai/ui** — design system: CSS tokens, five themes, component styles,

package/skills/odla-migrate/SKILL.md

@@ -42,7 +42,10 @@ installed skill at `../odla/SKILL.md` instead.
    references/secrets-map.md BEFORE any command that touches a credential.
    A fresh device request requires the existing odla account email via
    `--email` or `ODLA_USER_EMAIL`; email is a non-secret identifier. Never ask
-   for an odla password, Clerk token, or browser session.
+   for an odla password, Clerk token, or browser session. That is the human's
+   odla ACCOUNT email — never infer it from `git config user.email`, `gh`, or a
+   commit author; a wrong address silently mints an unapprovable request. See
+   references/troubleshooting.md.
 4. Never `git add -A` without reading `git status` first.
 5. Never widen a db rule to silence a 403 — default-deny is the design.
    Any rules change is a human checkpoint.

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

@@ -36,8 +36,14 @@ hand-author only the namespaces it does not.
    hands each the same context (`ctx.verifyUser`, `ctx.makeDb`, `ctx.roleFor`,
    `ctx.isAdmin`), so you never verify a JWT twice. Do NOT hand routes over to
    chapter in the same change as the framework swap.
-5. **Override rather than inherit wherever local behavior was a decision.**
-6. `npx @odla-ai/cli doctor` → `provision --dry-run` (show the human) → provision.
+5. **Adopt the host-independent console shell.** Import
+   `@odla-ai/ui/themes/salt/app.css` once, then render
+   `<ChapterAdmin chapter={chapter}/>` at the existing `/admin/` mount. The
+   config supplies brand tokens and the standard sections. Navigation uses
+   `?tab=` by default, so do not add `/admin/*` SPA rewrites to an ordinary
+   static site. Legacy path links remain readable.
+6. **Override rather than inherit wherever local behavior was a decision.**
+7. `npx @odla-ai/cli doctor` → `provision --dry-run` (show the human) → provision.
 
 The same parity-before-deletion pattern works for UI: render the packaged
 component beside yours, assert byte-identical markup, then delete yours and keep
@@ -64,18 +70,23 @@ These bite silently; no smoke test catches them.
   invitation**. Swapping in chapter's route while expecting server-side create
   loses it silently unless you set `account: "create"` — the applicant finds out
   when they cannot sign in.
-- **CRM projection points.** chapter projects on application submit, not on
-  booking or webhook status change. Mirroring pipeline stage into the CRM means
-  keeping those routes.
+- **CRM authority.** `applications` remains authoritative for member lifecycle;
+  `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.
+- **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
+  leader.
 
 ## Install notes
 
 - **A worker-only adoption does not need `@odla-ai/auth-clerk`.** The worker
   verifies Clerk JWTs with `jose` via `ctx.verifyUser`. Install auth-clerk only
   for `@odla-ai/chapter/ui/admin` (the Clerk-gated console) or the themed sign-in
-  components; `@odla-ai/chapter/ui/member` needs nothing but react.
+  components; `@odla-ai/chapter/ui/member` needs only Preact.
 - **`--legacy-peer-deps` is a diagnostic, not a setting.** It suppresses exactly
   the peer error that tells you a pair is unsupported. If an install errors, read
   it. A site that left the flag on ran an unsupported ui/crm pair for a day with

package/skills/odla-migrate/references/phase-2b-calendar.md

@@ -108,10 +108,10 @@ this app's own Worker endpoints and may import pure helpers from
 7. Frontend. Two supported shapes:
    - **`@odla-ai/ui` SlotPicker** — renders the slots response directly
      (`{ slots, timezone, onSelect }`). On a non-framework static site use a
-     Preact island: a small entry that mounts `<SlotPicker>` into a div,
-     bundled with esbuild as an IIFE with `react`/`react-dom` aliased to
-     `preact/compat`, committed as a static asset next to the site's other
-     assets.
+     native Preact island: a small entry that imports `render` from `preact`,
+     mounts `<SlotPicker>` into an empty div, and bundles with
+     `jsxImportSource: "preact"` as an IIFE committed next to the site's other
+     assets. Do not install React or add compatibility aliases.
    - **Plain fetch + buttons** — `fetch("/api/booking/slots")`, render times
      with `formatBookingRange` from `@odla-ai/calendar/client`, POST the
      chosen slot.

package/skills/odla-migrate/references/phase-3-auth.md

@@ -52,10 +52,10 @@ authoritative for commands and flags.
      `{"email": "{{user.primary_email_address}}"}`
 4. Gate at least one `/api/*` route on a verified user; return 401
    otherwise.
-5. Add Clerk sign-in to the site pages. For a React/Preact site, use
+5. Add Clerk sign-in to the site pages. For a Preact site, use
    `@odla-ai/auth-clerk`: wrap the app in `<ClerkGate publishableKey>`
    (key from public-config) and drop in `<SignIn />`. It runs on vanilla
-   clerk-js (no clerk-react), loads clerk-js as a lazy chunk, and themes
+   clerk-js (no React wrapper), loads clerk-js as a lazy chunk, and themes
    to odla-ui via `clerkAppearanceFromTokens()`. Otherwise drive ClerkJS
    directly with the publishable key from public-config, or use Clerk's
    hosted pages. For a **vanilla/static site**, load Clerk's browser bundle

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

@@ -46,6 +46,29 @@ appearing), wait for them to approve, then re-run the same command; it
 resumes the same code and collects the token. Do not loop unattended
 retries; each handshake lives ~10 minutes.
 
+## The approval URL says no request matches, or is never approvable
+
+Symptom: the human opens the printed `/studio?code=XXXX-XXXX` link and Studio
+says "No request for your account matches …", or they approve nothing because
+no request card appears — while the CLI polls until the handshake expires.
+
+Cause: `--email` / `ODLA_USER_EMAIL` was not the human's odla **account**
+email. The registry matches the exact normalized string (`trim` + `lowercase`
+only), so a `+alias`, a `users.noreply.github.com` address, or a second
+personal address is a different identity. An address that resolves to no
+account is **not** an error — to keep anyone from discovering which emails are
+registered, the request is recorded as an inert decoy bound to no owner, which
+no one can preview or approve. Every surface therefore looks normal: the CLI
+prints a URL, polls, and times out.
+
+Fix: confirm the address with the human and re-run. **Never derive it from
+`git config user.email`, `gh`, or a commit author** — that is the usual source
+of this, because a git identity is routinely a different address from the odla
+account. If `.odla/handshake.local.json` exists, the address it records is
+known-good; reuse that. Repeated failures with the same address mean it is not
+registered — the human must add it to their account (or use the registered
+one), and no amount of retrying will help.
+
 ## `smoke` fails: missing credentials
 
 Cause: `.odla/credentials.local.json` absent, for a different app id,

package/skills/odla-o11y-debug/SKILL.md

@@ -95,3 +95,17 @@ suggest one (metric + threshold + window).
 - **Say what you couldn't see.** Arbitrary custom attributes live in the trace
   payload, not the group-by dimensions; if the cohort is defined by a custom
   field, note that you inferred it from individual traces, not an aggregate.
+
+## Land the finding
+
+A triage that ends in chat is lost by the next session. File what you found as a
+bug against the app, with the cohort in the description and the trace id in a
+comment:
+
+```cmd
+npx @odla-ai/cli pm bug add --app <appId> --title "POST /pay 503s under retry" --severity high --desc "…"
+```
+
+Severity follows the blast radius, not your confidence. The conventions and the
+rest of the `pm` command set are in `.agents/skills/odla/references/pm.md`
+(installed alongside this skill).