@odla-ai/cli 0.27.3 → 0.27.4

package/README.md

@@ -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