@odla-ai/cli 0.27.3 → 0.27.5

package/dist/index.d.cts

@@ -501,6 +501,8 @@ interface OdlaProjectConfig {
         publicRead?: string[];
     };
     ai?: {
+        /** Hosted is the default when omitted; provider-only legacy configs are BYOK. */
+        mode?: "hosted" | "byok";
         provider?: string;
         model?: string;
         /** Env var containing the provider key to store in the platform vault. */
@@ -829,7 +831,7 @@ interface DoctorOptions {
  * It then collects warnings for the mistakes provision can't fix silently: a
  * schema with no entities, a rules namespace with no matching entity, an
  * integration with incomplete rules or a seed targeting an unknown namespace, the `ai`
- * service enabled without an `ai.provider`, `auth.clerk` entries that reference
+ * BYOK service enabled without an `ai.provider`, `auth.clerk` entries that reference
  * an unset env var (`$FOO`), an `ai.keyEnv` that isn't set (provider key upload
  * will be skipped), and — when `o11y` is enabled — any env whose local
  * credentials lack an ingest token. It also folds in the shared rule linter,
@@ -864,9 +866,9 @@ interface InitOptions {
  * written when it doesn't already exist unless `force` is set (otherwise it
  * throws); the schema/rules files are written only when missing (never
  * overwritten, even with `force`). `appId` must match `^[a-z0-9][a-z0-9-]*$` or
- * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`,
- * `aiProvider` → `"anthropic"` (which also picks the `keyEnv`, e.g.
- * `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`/`GOOGLE_API_KEY`).
+ * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`, and
+ * platform-hosted AI. Passing `aiProvider` explicitly opts into BYOK and also
+ * picks its `keyEnv`.
  *
  * @param options.appId Slug for the app (lowercase alphanumerics and hyphens).
  * @param options.name Human-readable app name embedded in the config.
@@ -874,7 +876,7 @@ interface InitOptions {
  * @param options.configPath Config filename relative to root (default `odla.config.mjs`).
  * @param options.envs Environment names (default `["dev"]`; production is an explicit opt-in).
  * @param options.services Enabled services (default `["db","ai"]`).
- * @param options.aiProvider AI provider slug (default `"anthropic"`).
+ * @param options.aiProvider Optional provider slug; supplying it opts into BYOK.
  * @param options.force Overwrite an existing config file instead of throwing.
  * @param options.stdout Optional console-like sink (defaults to `console`).
  */

package/dist/index.d.ts

@@ -501,6 +501,8 @@ interface OdlaProjectConfig {
         publicRead?: string[];
     };
     ai?: {
+        /** Hosted is the default when omitted; provider-only legacy configs are BYOK. */
+        mode?: "hosted" | "byok";
         provider?: string;
         model?: string;
         /** Env var containing the provider key to store in the platform vault. */
@@ -829,7 +831,7 @@ interface DoctorOptions {
  * It then collects warnings for the mistakes provision can't fix silently: a
  * schema with no entities, a rules namespace with no matching entity, an
  * integration with incomplete rules or a seed targeting an unknown namespace, the `ai`
- * service enabled without an `ai.provider`, `auth.clerk` entries that reference
+ * BYOK service enabled without an `ai.provider`, `auth.clerk` entries that reference
  * an unset env var (`$FOO`), an `ai.keyEnv` that isn't set (provider key upload
  * will be skipped), and — when `o11y` is enabled — any env whose local
  * credentials lack an ingest token. It also folds in the shared rule linter,
@@ -864,9 +866,9 @@ interface InitOptions {
  * written when it doesn't already exist unless `force` is set (otherwise it
  * throws); the schema/rules files are written only when missing (never
  * overwritten, even with `force`). `appId` must match `^[a-z0-9][a-z0-9-]*$` or
- * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`,
- * `aiProvider` → `"anthropic"` (which also picks the `keyEnv`, e.g.
- * `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`/`GOOGLE_API_KEY`).
+ * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`, and
+ * platform-hosted AI. Passing `aiProvider` explicitly opts into BYOK and also
+ * picks its `keyEnv`.
  *
  * @param options.appId Slug for the app (lowercase alphanumerics and hyphens).
  * @param options.name Human-readable app name embedded in the config.
@@ -874,7 +876,7 @@ interface InitOptions {
  * @param options.configPath Config filename relative to root (default `odla.config.mjs`).
  * @param options.envs Environment names (default `["dev"]`; production is an explicit opt-in).
  * @param options.services Enabled services (default `["db","ai"]`).
- * @param options.aiProvider AI provider slug (default `"anthropic"`).
+ * @param options.aiProvider Optional provider slug; supplying it opts into BYOK.
  * @param options.force Overwrite an existing config file instead of throwing.
  * @param options.stdout Optional console-like sink (defaults to `console`).
  */

package/dist/index.js

@@ -57,7 +57,7 @@ import {
   startHostedSecurityJob,
   surfacePaths,
   validateInvocation
-} from "./chunk-JWEBGIBR.js";
+} from "./chunk-DQOJ4S6H.js";
 export {
   AGENT_HARNESSES,
   CAPABILITIES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odla-ai/cli",
-  "version": "0.27.3",
+  "version": "0.27.5",
   "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

@@ -10,6 +10,7 @@ runbookOrder:
   - references/build.md
   - references/sdks.md
   - references/pm.md
+  - references/agent-identity.md
   - references/co-owners.md
 ---
 
@@ -151,19 +152,39 @@ on the app. It is platform-side: there is nothing PM-specific 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
+npx @odla-ai/cli pm next --app <appId>
 ```
 
+For a durable supervisor loop, establish and persist an exact-project PM cursor:
+
+```cmd
+npx @odla-ai/cli pm watch --app <appId> --entity task --jsonl
+```
+
+A Ready event is a wake-up signal, not permission: reload the task and linked
+goal and win the current revision's atomic claim before starting. PM-attached
+comments use the same cursor (`--action comment.created`); general Discussion
+topics and mentions still use `discuss watch`.
+
 The app must already be registered for ownership-scoped PM access. On a new
 project, use a focused commit/checkpoint only until the first provision, then
 initialize PM and backfill the approved early evidence immediately. Across
 several efforts, list without `--app` first, then scope every write to the exact
 project id.
 
-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`.
+Before project-mutating work, confirm the request aligns to an open goal and
+propose/refine a **task** in Backlog. Ready is a planner handoff: an ordinary
+managed-agent grant has `pm.execute`, so a human owner or `pm.plan` agent must
+approve the Ready contract before the executor claims its reviewed revision.
+Record a **decision** the moment you make one (with what it rules out), and file
+a **bug** the moment you notice one. A decision you don't record is one the next
+agent re-litigates. Full command set, conventions, and recovery procedure:
+`references/pm.md` and `references/pm-work-intake.md`.
+
+For an agent that spans linked worktrees or customer repositories, follow
+`references/agent-identity.md`: select a named context and verify the same
+immutable, project-derived handle is requested and human-approved when
+reconnecting an expired credential.
 
 ## Operational runbooks live in the database, not in this bundle
 
@@ -289,6 +310,9 @@ code, paste a publishable key, run a command) — and wait for a nod.
 - `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/agent-identity.md` — preserve one attributable agent principal
+  across credential expiry, linked worktrees, and non-odla-ai projects without
+  copying a token or widening project authority.
 - `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/agent-identity.md

@@ -0,0 +1,125 @@
+# Reconnect an agent across worktrees and projects
+
+Use this procedure when an agent must keep the same attributable identity while
+its short-lived device credential expires, or when it operates outside the
+checkout that first obtained the credential.
+
+## Preconditions
+
+- The human approving the request owns or co-owns every selected project.
+- The handshake contains one deliberate handle suffix, such as `customer-app`
+  or `release-reviewer`. The Registry places it under the approving human's
+  verified namespace (for example, `@cory/customer-app`). The CLI derives this
+  suffix deterministically from the exact project; SDK callers may explicitly
+  request a different stable `agentHandle` for a cross-project agent.
+- No token, credential file, or browser session is copied between worktrees,
+  machines, people, or chat messages.
+
+## 1. Save non-secret context outside the checkout
+
+```cmd
+npx @odla-ai/cli context save delivery --platform https://odla.ai --app <appId> --env prod
+npx @odla-ai/cli context show --context delivery --json
+```
+
+The context stores only platform/app/environment metadata. Its private token
+cache lives under `~/.odla/profiles/delivery/`, independently of any repository
+or linked worktree. Select it explicitly with `--context delivery` or
+`ODLA_CONTEXT=delivery`; there is no ambient current context.
+
+## 2. Establish the durable principal
+
+Run the intended command with the named context. If no valid cached credential
+exists, the CLI starts the normal email-bound device handshake and prints the
+exact Studio approval URL.
+
+```cmd
+npx @odla-ai/cli whoami --context delivery --email <account-email> --json
+```
+
+In Studio, review the exact code, requested handle, projects, and capabilities.
+The request is immutable: approval cannot edit its identity or grants. The
+handle—not the request label or local context name—is the durable agent identity
+key. Record the full verified handle in the agent handoff; never record the
+token. A normal CLI handshake derives the same handle from the configured
+project in every checkout and worktree.
+
+After approval and collection, verify the selected identity and context:
+
+```cmd
+npx @odla-ai/cli whoami --context delivery --json
+npx @odla-ai/cli pm next --context delivery --json
+```
+
+If the agent request omits the handle, Registry deliberately creates a new
+principal for that handshake. An untrusted request label can therefore never
+select an existing agent.
+
+## 3. Reconnect after expiry
+
+Re-run the command with the same named context and project. The cache keeps the
+approved account identifier and starts a fresh handshake when the token is
+expired. During human review:
+
+1. verify the immutable request contains the expected existing handle suffix;
+2. verify every exact requested project should receive access now;
+3. review optional capabilities again; and
+4. approve the request unchanged, or decline it with corrective feedback.
+
+Registry binds the new credential to the existing managed-agent principal and
+stores the human's reviewed exact-project set without activating it yet. The
+existing principal's authoritative name and purpose are retained; reusing its
+handle is not a profile-edit operation. Approval alone leaves the current
+credential and its project grants usable. When the replacement plaintext is
+successfully collected, Registry atomically clears that plaintext, retires
+older collected ordinary-handshake credentials, and replaces the principal's
+manager-issued project grants with the reviewed set. Newly selected projects
+are unavailable before collection, and omitted projects are revoked during the
+switch. If collection never succeeds, the working credential and grants are not
+stranded by the approval.
+
+Verify `whoami` reports the same principal/handle before resuming work. Ordinary
+reviewed project access includes `pm.execute` but not `pm.plan`: re-read `pm
+next` and claim the current Ready task revision, while leaving Ready approval to
+a human owner or explicit planner. Identity continuity alone does not preserve
+a stale claim or imply authority outside the newly reviewed grants.
+
+## 4. Review remaining credentials
+
+Successful collection automatically retires the preceding collected ordinary
+handshake credential for that principal. Verify the old row in Studio's
+agent-credential inventory has a `system:handshake-reconnect:<handshake-id>`
+revocation reason. Do not delete a local cache as a substitute for this
+server-side evidence.
+
+The rotation set deliberately excludes manually minted credentials and
+separately scoped handshakes: those may represent another deliberate runtime,
+not a stale copy of this context. Review and revoke them explicitly when they
+are no longer intended.
+
+Project grants are still time-bounded. Collection makes the newly reviewed
+selection authoritative for the principal: selected projects receive new
+revisions and every live manager-issued project omitted from that selection is
+revoked. There is not yet a non-interactive `auth rotate` command or OS
+credential-store integration. The named context plus stable handle solves
+worktree/project portability and principal continuity, but it is not ambient or
+permanent authority.
+
+## Recovery and audit evidence
+
+- `handshake_pending`: approve the existing code and rerun the same command; do
+  not create a substitute request.
+- Wrong handle requested: decline it and correct the project/SDK request before
+  starting a fresh handshake. If already approved, revoke the new credential in
+  Studio; do not rename or merge principals by editing local metadata.
+- Missing project after reconnect: start a new reviewed handshake and select the
+  exact project; never widen to all projects.
+- Project ownership/lifecycle changed after approval: collection expires the
+  unusable replacement while preserving the current credential and grant set.
+  Restore the intended project state, then start and review a fresh handshake.
+- Lost local cache: save/select the same non-secret context, complete a new
+  handshake with the same handle, verify `whoami`, then revoke the lost
+  credential from Studio.
+
+Audit evidence is the stable principal id/handle, the new credential id, and the
+monotonic project-grant revision shown by Registry—not possession of a token.

package/skills/odla/references/pm-work-intake.md

@@ -0,0 +1,131 @@
+# PM work intake — align, ready, claim, and recover
+
+Use this runbook whenever an agent is about to begin project-mutating work.
+PM goals and tasks are the durable records. Discussion is the communication
+channel. A Codex Goal, when the harness supports it, is the execution objective
+for the current chat and should name the PM goal and task references.
+
+## Preconditions
+
+- Resolve the exact `appId`; do not infer it from the repository name.
+- Use a task-owned worktree and branch before editing.
+- Never put a credential, token, or secret in PM or Discussion.
+- A question, investigation, or alignment conversation may proceed without a
+  claim. Implementation may not.
+
+## 1. Resolve context and read authoritative state
+
+```cmd
+npx @odla-ai/cli context show --context <profile>
+npx @odla-ai/cli pm next --app <appId> --json
+npx @odla-ai/cli pm handoff --app <appId> --json
+```
+
+Read any existing Doing task before selecting another. For each candidate, read
+the task, its goal, and their comments. If the current chat has a Codex Goal,
+confirm that its objective and verification still match these records.
+
+## 2. Check alignment
+
+Match the requested outcome to an open PM goal. If none fits:
+
+1. explain the mismatch to the user in Discussion/chat;
+2. ask whether to refine or create a PM goal, defer the request, or accept a
+   narrowly scoped exception;
+3. record an approved exception as an accepted PM decision and link its id from
+   the task;
+4. do not begin implementation while the choice is unresolved.
+
+An agent must not create a convenient goal merely to authorize itself.
+
+## 3. Refine Backlog work and mark it Ready
+
+Ready is a durable planner-to-executor handoff. A human project owner or an
+agent holding `pm.plan` may refine the task and mark it Ready. Ordinary managed
+agent handshakes receive `pm.execute`, not `pm.plan`: they may create a Backlog
+proposal or file a bug, but must ask the user/planner to review the contract and
+perform the Ready transition. Do not treat a 403 as a reason to widen or bypass
+the grant.
+
+Create/refine the task with one alignment source, an actionable description,
+acceptance criteria, and execution mode:
+
+```cmd
+npx @odla-ai/cli pm task add --app <appId> --title "<work>" --goal <goal-id> --description "<bounded work>" --acceptance "<observable proof>" --execution agent
+npx @odla-ai/cli pm task get <task-id> --json
+npx @odla-ai/cli pm task ready <task-id> --expected-revision <revision>
+```
+
+Use `--alignment-decision <decision-id>` instead of `--goal` only for an
+accepted exception. Ready is stored as `column: "todo"` for wire compatibility.
+The server rejects Ready when the goal/decision belongs to another project, the
+goal is not open, the decision is not accepted, or the contract is incomplete.
+
+## 4. Claim, then create the execution workspace
+
+Claim and release require `pm.execute`. Planning authority alone is
+intentionally insufficient, so the principal that approves a task does not
+silently become its executor.
+
+Review the latest task revision immediately before claiming:
+
+```cmd
+npx @odla-ai/cli pm task get <task-id> --json
+npx @odla-ai/cli pm task claim <task-id> --expected-revision <revision>
+```
+
+Only one concurrent caller can win. On conflict, reload `pm next` and the task;
+do not retry with a guessed revision. Once claimed, use the repository's
+worktree procedure and mention the PM references in the execution chat:
+
+```text
+@[Task title](pm:task/<task-id>)
+@[Goal title](pm:goal/<goal-id>)
+```
+
+## 5. Execute, review, and complete
+
+- Keep the task description/acceptance criteria current under its revision.
+- Record decisions when the implementation closes off an alternative.
+- File defects as bugs rather than burying them in progress prose.
+- Comment with verification commands, evidence, commit/candidate identity, and
+  remaining risk.
+- Move Doing to Review when the acceptance evidence is ready.
+- Mark Done only after review and proof; mark the goal met only when all linked
+  work is resolved and the goal proof passes.
+
+## 6. Release or recover
+
+If the claimant must stop:
+
+```cmd
+npx @odla-ai/cli pm task release <task-id> --expected-revision <revision>
+```
+
+Comment with the branch/worktree, last verified commit, unfinished step, and
+safe next action. An agent may release only its own claim; a human project
+operator may recover an abandoned claim. Claims do not yet have automatic
+leases, so never leave one active as a substitute for a handoff.
+
+## 7. Resume safely
+
+Establish a checkpoint before waiting for PM lifecycle changes, persist every
+checkpoint record, and resume with its opaque cursor:
+
+```cmd
+npx @odla-ai/cli pm watch --app <appId> --entity task --jsonl
+npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --state ready --self <principal-id> --jsonl
+npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --action comment.created --self <principal-id> --jsonl
+```
+
+Delivery is at least once. Deduplicate by `eventId`; advance durable consumer
+state only on a `checkpoint` record. Filters consume nonmatching events and
+still advance the checkpoint, so do not reuse a filtered consumer cursor for a
+different policy. If the command reports `checkpoint_required` (exit 3), discard
+the stale cursor, run `pm next` and reload any active task, then establish a new
+checkpoint without `--cursor`.
+
+A Ready event or PM-attached comment is only a wake-up signal. Before acting,
+re-run `pm next`, reload the task revision, re-check its goal, and win `task
+claim`. General Discussion topics and mentions stay on `discuss watch`; a chat
+message still does not prove a task is Ready or grant execution authority.

package/skills/odla/references/pm.md

@@ -57,7 +57,11 @@ npx @odla-ai/cli pm bug list --app <appId> --status open
 ```
 
 ```cmd
-npx @odla-ai/cli pm task set <id> --column doing
+npx @odla-ai/cli pm next --app <appId>
+```
+
+```cmd
+npx @odla-ai/cli pm task claim <id> --expected-revision <n>
 ```
 
 ```cmd
@@ -66,7 +70,9 @@ 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).
+  for tasks; `--body` for decisions; `--severity`, `--desc` for bugs). A task
+  created directly in `todo` (Ready) also needs an open goal or accepted
+  alignment decision, a description, and `--acceptance`.
 - `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,
@@ -77,21 +83,49 @@ npx @odla-ai/cli pm decision list --q "stripe"
 - `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.
+- `rm <id>` deletes the current row. Prefer `done` or a status change: the
+  authorized immutable event log retains the deletion snapshot for recovery and
+  audit until the exact project lifetime is purged.
+- `next --app <appId>` is the read-only intake view: open goals, current Doing
+  work, and Ready candidates. It never claims or mutates work.
+- `watch --app <appId> --jsonl` establishes and resumes an exact-project PM
+  lifecycle cursor. Persist checkpoint records, deduplicate at-least-once
+  delivery by `eventId`, and use `--entity`, `--state`, `--by`, or `--self` for
+  one stable consumer policy.
+- `task ready <id> --expected-revision <n>` validates and records the Ready
+  contract. `task claim` atomically moves the reviewed Ready revision to Doing;
+  `task release` explicitly returns an active claim to Ready. A stale revision
+  or concurrent claim is a conflict, so reload instead of overwriting it.
+
+Task authority has an intentional handshake boundary. `pm.plan` may refine,
+delete, or mark tasks Ready but cannot claim them. `pm.execute` may create
+Backlog proposals and findings, claim/release, and move its claimed work through
+Review and Done, but cannot approve Ready or change the task contract. Ordinary
+managed-agent approval includes `pm.execute`; it does not include `pm.plan`.
+Human project owners retain planning authority through ownership. Legacy
+`pm.write` grants remain executable so existing claims are not stranded, but do
+not gain planning authority.
 
 ## Working with it
 
-**At the start of a session**, read before you write:
+**At the start of a session**, resolve the exact project and read before you
+write:
 
 ```cmd
-npx @odla-ai/cli pm task list --app <appId> --column doing
+npx @odla-ai/cli context show --context <profile>
+npx @odla-ai/cli pm next --app <appId>
 ```
 
-then `pm bug list --app <appId> --status open` and
+Then read `pm bug list --app <appId> --status open` and
 `pm decision list --app <appId> --limit 10`, plus
-`pm goal list --app <appId> --status open`. Read the active task, linked goal,
-and their comments. That is the state of the project—including anything a
-*different* agent left behind.
+the selected task, linked goal, and their comments. That is the state of the
+project—including anything a *different* agent left behind.
+
+Before project-mutating work, decide whether the request aligns to an existing
+open goal. If it does not, stop at conversation: explain the mismatch and ask
+the human whether to refine/create a goal or accept a scoped exception as a PM
+decision. Do not silently invent the outcome or begin implementation. Questions,
+investigation, and that alignment conversation do not need a task claim.
 
 When coordinating several efforts, begin without `--app` to see doing tasks and
 open bugs across every co-owned project, then scope each write to the exact
@@ -101,8 +135,18 @@ goal links and comments rather than sharing a working tree or status document.
 
 **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").
+- Propose work in Backlog. A human owner or `pm.plan` agent reviews/refines it,
+  links it to an open same-project goal (or accepted alignment decision), adds
+  an actionable description and acceptance criteria, then runs `pm task ready
+  <id> --expected-revision <n>`. The stored column is still `todo` for API
+  compatibility, but every product surface calls it Ready.
+- An agent starts only with `pm task claim <id> --expected-revision <n>`. The
+  compare-and-set claim assigns the authenticated principal and moves the task
+  to Doing. Never use `pm task set --column doing` to bypass it.
+- Use one claimed task and one owned worktree/branch. If you must stop before
+  review, run `pm task release <id> --expected-revision <n>` and comment with
+  the recovery point. Move to Review when evidence is ready; mark Done only
+  after the acceptance criteria pass.
 - 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.
@@ -113,6 +157,90 @@ goal links and comments rather than sharing a working tree or status document.
   `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.
 
+## Referencing PM records in Discussion
+
+Discussion markup uses stable typed references. Prefer it over pasting a title
+that can be renamed:
+
+```cmd
+npx @odla-ai/cli pm task ref <task-id>
+```
+
+Paste the returned markup into `--markup`, alongside other references:
+
+```cmd
+npx @odla-ai/cli discuss post --app <appId> --subject "Ready for review" --markup "Review @[Checkout retries](pm:task/<task-id>) for @[Retry safety](pm:goal/<goal-id>)."
+```
+
+The same copied `pm:*` markup works in an item's own PM comment. It is stored as
+a structured reference, rendered as a PM chip, and printed as markup again by
+the `comments` command:
+
+```cmd
+npx @odla-ai/cli pm task comment <task-id> --body "Blocked by @[Retry safety](pm:goal/<goal-id>)."
+npx @odla-ai/cli pm task comments <task-id>
+```
+
+Use `pm:task`, `pm:goal`, `pm:decision`, `pm:bug`, and `pm:runbook`. The message
+is communication; the referenced PM row remains the lifecycle authority.
+
+In Studio, open any PM item and choose **Discuss** to open the owning project's
+Discussion composer with the same stable reference already inserted. The draft
+is retained in the URL across reload/back navigation but is not a write: review,
+edit, and explicitly post it, or cancel to discard the route draft. This bridge
+does not create a canonical one-topic-per-item stream; PM-attached comments and
+general project Discussion still have independent capability checks and watches.
+
+## Credentials and worktrees
+
+A repository-local `.odla/dev-token.json` is not shared by linked worktrees.
+For work that must run from several worktrees or another project, save a named,
+non-secret operator context and select it explicitly:
+
+```cmd
+npx @odla-ai/cli context save delivery --platform https://odla.ai --app <appId>
+npx @odla-ai/cli context show --context delivery
+npx @odla-ai/cli pm next --context delivery
+```
+
+The selected profile uses a user-level private credential cache instead of the
+checkout-local cache. Credentials still expire. During the next handshake,
+reusing the same immutable, human-approved project handle reconnects the new
+credential to the existing agent principal. Follow
+[`agent-identity.md`](./agent-identity.md): collection atomically retires the
+older collected ordinary-handshake credential and replaces the principal's
+manager-issued grants with the newly reviewed exact-project set. Approval alone
+does neither, so a failed collection leaves current access intact. Deliberate
+manual/scoped credentials still require explicit inventory review.
+
+## State-change delivery
+
+Every goal/task/decision/bug create/update/delete appends an immutable event
+snapshot in the same transaction. Consume the exact-project stream with:
+
+```cmd
+npx @odla-ai/cli pm watch --app <appId> --jsonl
+npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --state ready --self <principal-id> --jsonl
+npx @odla-ai/cli pm watch --app <appId> --cursor <cursor> --entity task --action comment.created --self <principal-id> --jsonl
+```
+
+The first call establishes a checkpoint and intentionally does not replay old
+activity. Persist `checkpoint` records; delivery is at least once, so deduplicate
+by stable `eventId`. A `checkpoint_required` status means retention/restore made
+the cursor stale: re-read `pm next` and the active task, then establish a fresh
+checkpoint. Filters consume nonmatching events, so a saved cursor belongs to one
+filter policy.
+
+`pm watch` covers PM lifecycle rows plus comments attached to active goals,
+tasks, decisions, and bugs. It deliberately does not copy general project chat:
+`discuss watch` still carries ordinary topics and mentions under the independent
+Discussion capability. They are not yet one canonical topic/stream. Never infer
+authority to start from either notification alone: re-read the Ready row and win
+the atomic claim at its current revision.
+
+The focused start/claim/recovery procedure is also available in
+[`pm-work-intake.md`](./pm-work-intake.md).
+
 **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.
 

package/skills/odla/references/sdks.md

@@ -79,12 +79,13 @@ re-run `calendar connect`.
 ## @odla-ai/ai — inference (Claude / GPT / Gemini)
 
 ```ts
-const { ai } = await initFromPlatform({ platform, appId, env, db });
-await ai.chat({ messages }); // provider/model + key resolved from the platform vault
+const { ai } = await initFromPlatform({ platform, appId, env, appKey, db });
+await ai.chat({ messages, maxTokens: 512 }); // approved hosted model; db supports BYOK fallback
 ```
 
-No API key in your code or env — it lives in the tenant vault; `provision`
-stores it when the configured `ai.keyEnv` is set at provision time.
+No provider key in your code or env. Hosted AI uses the app's existing backend
+key and central cost attribution; `--ai-provider` explicitly opts a new config
+into BYOK.
 
 ## @odla-ai/crm — records, pipelines, follow-ups, and contactability
 

package/skills/odla-migrate/references/project-state.md

@@ -51,7 +51,7 @@ Resolve `appId` from `odla.config.mjs`; do not guess it from a repository name,
 deployment, old branch, or conversation.
 
 ```cmd
-npx @odla-ai/cli pm task list --app <appId> --column doing
+npx @odla-ai/cli pm next --app <appId>
 npx @odla-ai/cli pm bug list --app <appId> --status open
 npx @odla-ai/cli pm decision list --app <appId> --limit 20
 npx @odla-ai/cli pm goal list --app <appId> --status open
@@ -63,9 +63,15 @@ being tested. If PM and the working tree disagree, stop, investigate, and
 record the resolution as a decision or comment; do not silently pick whichever
 is more convenient.
 
+If the requested migration work does not align to an open goal, discuss it with
+the human before implementing. Refine the phase task with a concrete
+description and acceptance criteria, mark the reviewed revision Ready, and use
+the atomic claim operation before creating its worktree. On interruption,
+release the claim with the latest revision and comment with the recovery point.
+
 ## Update at every gate
 
-- Move the phase/track task when work starts.
+- Mark the refined phase/track Ready, then atomically claim it when work starts.
 - Comment with the exact verification command, result, source commit, candidate
   deployment version, and rollback checkpoint.
 - Record an intentional contract or product delta as a decision.