@odla-ai/cli 0.27.3 → 0.27.5

package/README.md

@@ -7,14 +7,14 @@
 
 Project-neutral provisioning CLI for odla apps. It creates and validates an
 `odla.config.mjs`, then uses that config to register an app, enable services,
-push odla-db schema/rules, configure per-app BYOK AI, configure Clerk auth, record
+push odla-db schema/rules, configure hosted app AI (or explicit BYOK), configure Clerk auth, record
 deployment links, compose declared npm capability integrations, connect Google Calendar booking, provision o11y ingest credentials, and transfer local or
 deployed Worker secrets without printing them. It also gives platform admins a
 scoped System AI control surface and gives app owners a provider-key-free
 hosted security command.
 
 Provisioning does not know about any specific app. App identity, environments,
-services, schema, rules, integrations, auth, AI provider, and links all come
+services, schema, rules, integrations, auth, AI mode/model, and links all come
 from config. Operator commands can also receive explicit platform/app/env
 context so remote agents are not forced to manufacture a project checkout.
 
@@ -73,6 +73,12 @@ and reject unknown fields, so credentials cannot be added to
 when no profile is selected. Each cache records its platform audience, and a
 token for another origin is never reused. `context show` reports provenance and
 cache state only; it never returns a credential or starts a device handshake.
+When a cached credential expires, the approving human can reuse the agent's
+exact handle suffix to bind the replacement credential to the same durable
+principal. The approval appends new revisions for the exact projects selected;
+it does not automatically revoke the older credential or renew an omitted
+project. The installed `references/agent-identity.md` runbook gives the full
+cross-worktree recovery procedure.
 
 ```bash
 ODLA_DEV_TOKEN=... npx @odla-ai/cli pm handoff --app <appId>
@@ -86,12 +92,13 @@ npx @odla-ai/cli runbook new deploy --context production --title Deploy --file d
 
 Runbooks tell an agent how to operate; PM tells every agent what this project is
 trying to prove, what is active, what was decided, and what is broken. Once the
-app is registered, start each session by reading its doing tasks, open bugs and
-goals, and recent decisions:
+app is registered, start each session with the read-only aligned-work intake,
+then read open bugs and recent decisions:
 
 ```bash
+npx odla-ai pm next --app <appId>
 npx odla-ai pm handoff --app <appId>
-npx odla-ai pm task list --app <appId> --column doing
+npx odla-ai pm watch --app <appId> --entity task --jsonl
 npx odla-ai pm bug list --app <appId> --status open
 npx odla-ai pm goal list --app <appId> --status open
 npx odla-ai pm decision list --app <appId> --limit 20
@@ -112,6 +119,36 @@ the first provision, use a focused commit/checkpoint, then initialize PM and
 backfill that evidence immediately after registration. Never use a parallel
 status diary or put a secret in PM.
 
+Before project-mutating work, match the request to an open goal. If it is not
+aligned, discuss that with the user before creating an outcome or implementing.
+Refine a Backlog task with `--goal` (or an accepted
+`--alignment-decision`), `--description`, and `--acceptance`, then mark it Ready
+and claim the reviewed revision:
+
+```bash
+npx odla-ai pm task ready <id> --expected-revision <n>
+npx odla-ai pm task claim <id> --expected-revision <n>
+```
+
+Ready is stored as `todo` for API compatibility. Claims are atomic and assign
+the authenticated principal; stale or concurrent claims fail. Use `pm task
+release` for an explicit recovery handoff instead of leaving Doing as a vague
+status. The complete runbook is installed as
+`references/pm-work-intake.md` by `odla-ai skill install`.
+
+`pm watch` is the durable wake-up path for goal/task/decision/bug changes and
+comments attached to those work items. Its first request creates an opaque
+checkpoint; persist later `checkpoint` JSONL records and deduplicate
+at-least-once events by `eventId`. Use `--action comment.created` for comment
+traffic. A Ready event or comment is not a claim: reload the task and goal, then
+claim the current revision. General Discussion topics and mentions remain on
+`discuss watch` until PM topics gain context-aware capability enforcement.
+Use `pm task ref <id>` (or the equivalent goal/decision/bug command) to print
+copy-ready structured markup for Discussion. The same markup may be pasted into
+`pm <entity> comment <id> --body "…"`; PM stores it as a structured reference,
+and `pm <entity> comments <id>` prints copy-ready markup instead of flattening
+the link back to a title.
+
 When diagnosing a deployed app, agents can request one parseable observability
 snapshot instead of scraping Studio or composing collector routes themselves:
 
@@ -426,10 +463,10 @@ shown-once credential.
    `--email <account>` or `ODLA_USER_EMAIL`; the matching existing account must
    sign in, review the exact code, and approve it. Opening the URL alone does
    not claim the request.
-   Studio shows the immutable project and capability request without grant
-   checkboxes. The owner approves that exact request or declines it with an
-   explanation which the CLI returns to the calling agent; different access
-   requires a new request.
+   Studio shows the immutable project-derived agent handle, project, and
+   capability request without mutation controls. The owner approves that exact
+   request or declines it with an explanation which the CLI returns to the
+   calling agent; a different identity or access set requires a new request.
    Every real CLI handshake prints exactly one canonical `/studio?code=…` URL
    and attempts to open it — including from CI, SSH, display-less, scripted,
    and agent-driven shells. Only `--no-open` suppresses the attempt. Browser
@@ -448,8 +485,8 @@ shown-once credential.
 5. Collision-checks and merges declared integration schema/rule fragments,
    pushes the composed database contract, and creates integration seeds only
    when their natural-key rows are absent.
-6. Configures platform AI and stores provider keys in the tenant vault when the
-   configured key env var is set.
+6. Configures hosted app AI by default. An explicit BYOK config stores its
+   provider key in the tenant vault when the configured key env var is set.
 7. For calendar, reads owner-visible connection status and, when needed, asks
    the platform for a state-bound Google authorization URL and opens only the
    exact Google OAuth endpoint (or a same-platform interstitial). The human completes consent there;
@@ -693,7 +730,8 @@ change events with actor attribution; credential values never enter that trail.
 It never returns prompts, repository source, model output, reports, or provider
 credentials. Credential writes accept only
 `--from-env <NAME>` or `--stdin` and never place the value in argv, output, or
-the cache. System AI and each app's BYOK AI are separate vault/funding paths.
+the cache. System AI and hosted app AI have separate routes and accounting;
+explicit BYOK has its own app-tenant vault path.
 Discovery and validation provider/model settings are authoritative server
 policy: a security command has no field that can override either route. Admin
 bounds can only narrow the hard ceilings of 64 calls per role/run and, for each
@@ -792,10 +830,9 @@ export default {
     defaultRules: "deny",
     publicRead: [], // namespaces where a `view: "true"` rule is intentional
   },
-  ai: {
-    provider: process.env.ODLA_AI_PROVIDER ?? "anthropic",
-    keyEnv: "ANTHROPIC_API_KEY",
-  },
+  ai: { mode: "hosted" },
+  // BYOK compatibility instead:
+  // ai: { mode: "byok", provider: "anthropic", keyEnv: "ANTHROPIC_API_KEY" },
   calendar: {
     google: {
       availabilityCalendars: { dev: ["primary"] },