octwin-cli 0.8.16 → 0.8.17

package/CHANGELOG.md

@@ -1,1028 +1,1109 @@
-# Changelog — octwin-cli
-
-All notable changes to the `octwin` CLI (npm package [`octwin-cli`](https://www.npmjs.com/package/octwin-cli)).
-Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucketed into
-**Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
-repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
-
-## [Unreleased]
-
-## [0.8.16] - 2026-10-07
-
-### Changed
-- **`octwin performance --channel` marks a figure that is not narrowed.** Capacity has no channel, so a
-  band narrowed to one prints the capacity tile with `(all channels)` rather than letting it pass as the
-  channel's own.
-- **`octwin performance` prints a rate's change in points.** The platform
-  replaced each indicator's `delta_pct` with `change` (one rule for the console, the server and the CLI): a conversion rate going
-  42.9% → 57.1% now reads `+14.2 pts vs prev`, not `+33.1%`, and an NPS from −25 to +40 reads `+65`,
-  not `-260%`. A count still reads as a percent; growth from zero reads `new`.
-
-## [0.8.15] - 2026-10-06
-
-### Fixed
-- **`octwin records` said nothing useful for a pack with no record types of its own.** Its message read
-  `has_xrm`, which the platform never sent, so it could not show. The platform sends it now; the CLI
-  says the pack declares no record types and that platform records still read by name
-  (`octwin records order | product | case`). `records create` and `records tasks` read `has_data` —
-  "no AI Agent is loaded in this project" — instead of the same unsent field.
-
-## [0.8.14] - 2026-10-06
-
-### Added
-- **`octwin seed --reset`** — archive every row the pack's demo loaded, then load it again. Needed
-  once for demo rows seeded before 2026-10-05 (the seed says so), and a clean slate on demand; records
-  a customer made are never touched.
-- **`octwin records <entity> --search "<words>"`** — the entity's ranked search (fuzzy, plus semantic
-  when the entity declares it), best match first, each row printed with its score. The platform has
-  served it to the console for months; the CLI never asked. `--json` returns the rows with their scores.
-- **`press:<label>` in `octwin chat --script`, and `--press <label>`.** Taps the button of the reply just
-  received by its label — exactly, or the same words without emoji or case, or the one label containing
-  them. A form or checkout button's tap id carries its run id (`t:resume:…:run_id=…`), which exists only
-  once the reply arrives, so a script could not get past the first form step: `tap:` needs an id nobody
-  can write in advance. No match, or several buttons, stops the script and lists the buttons. A lone
-  `--press` picks from the reply the conversation is waiting on. The rules are the AI Author's `press`,
-  byte for byte (`src/lib/press.ts`). An older CLI sends a `press:` line as a typed message.
-
-### Fixed
-- **`octwin chat` prints a card's link buttons and its forms.** A button that opens a link prints as
-  `[link] title → url` (a card may now carry links beside its reply buttons), and a form prints as
-  `[flow form] …` — it compared the hint type `'flow'`, which the wire never sends (`form_flow`).
-- **`--json` output always parses.** `records --json` and `projects create --json` printed a
-  `→ Reading …` line in front of their JSON, and `logs --json` with no conversations printed a sentence
-  and no JSON at all (reported 2026-10-01). Under `--json`, stdout now carries the result and nothing
-  else — progress, tables and hints go to stderr — and every write verb of a JSON command (`records
-  create`, `work note`, `agents set`, `catalog stock`, `scheduling rule add`, `projects rm --yes`, …)
-  returns what the platform answered. A test runs every JSON command and parses its stdout.
-- **`octwin chat` prints the pictures, files, voice notes and map pins a reply carries.** Only a reply's
-  text and buttons were printed, so a reply that sent a picture read as a caption with nothing under it.
-  Now `[image] <path>` (without the signed query), `[file] <name> → <url>`, `[voice note] 12s → <url>`,
-  `[location] <name> (lat, long)`, and `(image)` on a carousel card that has a picture
-  (`src/lib/media-lines.ts`).
-
-### Changed
-- **`--json` on a command that has no JSON output is refused by name** (`whoami`, `deploy`, `validate`,
-  …), with the list of commands that have it. It used to print the prose to stderr and leave stdout
-  empty. `chat --json` and `login --json` print one JSON object per line, as before.
-- **Under `--json`, the progress lines move from stdout to stderr.** A script that read them from stdout
-  reads them from stderr now; human output (no `--json`) is unchanged.
-- **`octwin pull` can pull an Octwin (first-party) pack.** The platform now lets a workspace read the
-  source of its own packs and of Octwin's — never another workspace's — and the 403 hint says so. A
-  platform change: an older CLI pulls first-party packs too, it only prints the older hint.
-
-## [0.8.13] - 2026-09-27
-
-### Added
-- **`octwin records archive <id>` / `restore <id>`.** Archive is how a record leaves use — test data
-  included: it drops out of every list, count and report and fires the entity's `on.archived`
-  reactions, exactly like the console's Archive; `restore` undoes it. There is no delete, on the
-  platform or here, and `octwin records --help` now says so.
-
-### Fixed
-- **`octwin chat` said the AI Agent wrote every message.** A reminder that fired mid `--script` (a
-  `schedule_notify`, a reaction) printed as `← <body>`, was taken for the turn's reply, and ended
-  the turn on it — so the real reply looked lost while `octwin logs` showed the flow had worked.
-  Each line now says who sent it: `← [notify] …` (not the turn's answer — the wait for the real
-  reply goes on), `← [operator: Name] …` (a person in Live chat), `← [platform] …` (a handoff
-  joining or returning); plain `← …` is the AI Agent. After the last turn the stream stays open
-  3 s more, so a late message prints (marked "after the last turn") instead of reaching a closed
-  connection. Needs a platform that stamps `source: 'notify'` on web renders; an older one just
-  prints notifies unlabelled, as before.
-- **The "no such template" hint named a file the platform never loads.** It said
-  `templates/<name>.yaml`; pack templates load only as `templates/<name>.template.yaml`, so a
-  template saved as the hint said was silently ignored.
-
-### Changed
-- **`octwin validate` runs the platform's FULL check by default — and needs no login for it.** The
-  offline checks are a subset, and a subset that passes read as "deploy will pass": it passed a pack
-  the full check refused (a scaffold flow left behind with Arabic copy only, in a pack that ships
-  English). Now `validate` runs the offline checks, then the full one: through your workspace when you
-  have a token AND a `--project` (which also confirms the project exists), otherwise through the
-  platform's public validate route with no credential. When it cannot reach the full check — no url,
-  offline, rate-limited, an older platform — the LAST line says *"only the OFFLINE check ran — a
-  PARTIAL check"* and why, and it exits 0 as before. `--remote` now means "the full check is
-  required" (not reaching it is an error); the new `--offline` runs only the subset.
-- **The scaffold's example `browse` flow says it is an example.** Its header, its copy file and its
-  `manifest.yaml` line now say to replace it, or delete the flow, every `browse.locale.*.yaml` and the
-  `flows:` line together — a leftover never loads, but a second language makes it fail validation.
-
-## [0.8.12] - 2026-09-25
-
-### Changed
-- **The package pointed its `homepage` at npm — the page it is rendered on.** It is
-  <https://octwin.ai> now, and the README's Links section gains the platform, the guides and the
-  marketplace. The README describes Octwin at length and linked only to npm and nodejs.org.
-- **`octwin usage` with a project-pinned token reports that project.** The platform now treats a
-  token's project pin as a ceiling on every route, so a pinned token is refused on the
-  workspace-wide rollup. `usage` asks `whoami` for the pin and reads the project view instead of
-  printing a 403 — which is what its help text (`project if pinned, else workspace`) always said.
-
-### Fixed
-- **`octwin chat` sat out its whole 45-second wait on every message during a live handoff, and
-  read as hung.** While a person holds the conversation (or one has been asked for) the AI Agent
-  deliberately answers nothing, and the CLI could not tell that from a slow pack. The platform now
-  says so with a `held` event on the web stream; `chat` prints
-  *"⏸ a person is holding this conversation — the AI Agent will not reply…"* (or *"waiting for a
-  person to join…"*), still collects any operator line replayed by that message, and returns. A
-  held turn is not a failure: it exits 0, and `--script` carries on to the next line, so the
-  customer's side of a handoff can be scripted. Needs a platform that sends `held`; an older one
-  behaves as before. Reported in `xpeng-egypt/FEEDBACK.md`, session 3.
-
-## [0.8.11] - 2026-09-07
-
-### Fixed
-- **`octwin login` erased your own tooling report — the CLI was blanking what it had just
-  told the platform.** Two calls built their `authorization` header by hand instead of going
-  through `authHeaders`: `login`'s post-save "here's what your token reaches" echo, and
-  `chat`'s tenant/project derivation. Both authenticate, so both stamp the token's client
-  report (added in 0.8.9) — and a hand-built header stamps **NULL**, wiping the CLI version
-  and reference hash the platform had recorded.
-
-  Caught within an hour of 0.8.9 reaching staging: a workspace reported `0.8.9 · reference
-  current` at 12:16 and read `not reported` at 12:34. That looked exactly like the documented
-  "the column holds what ran LAST" behaviour and was really the CLI erasing its own row.
-  `cli-routes.test.ts` now fails on any hand-built bearer header, with a non-vacuity floor —
-  this package sits outside the repo's eslint scope, so a text guard is the only rung available.
-
-## [0.8.10] - 2026-09-07
-
-### Fixed
-- **`octwin memos` failed with `400 project required` for a tenant-wide token — the exact
-  command the nudge tells you to run.** Every networked command can end with
-  *"✉ N memos from the platform — read them: `octwin memos`"*, and running precisely that with
-  an unpinned token answered a 400. Measured on staging: the nudge fired during a
-  `deploy --project …` (which supplied a project) and then named a command that could not run.
-
-  A memo has no project dimension to scope by — neither `pack_memos` nor `pack_memo_reads`
-  carries a `project_id`, and the read ledger is keyed by tenant — so the three call sites now
-  use `/api/self/t/memos`. Passing `--project` still works and is no longer needed.
-
-## [0.8.9] - 2026-09-07
-
-### Added
-- **Every authenticated request now says which CLI and which capability reference you are on.**
-  Two headers off `authHeaders` — `x-octwin-cli` and `x-octwin-kb` (the `content_hash` of your
-  pulled reference) — so `deploy`, `validate --remote`, `status`, `chat`, `logs` and `memos` all
-  carry them, from one place. The platform stores them against your deploy token and shows them in
-  the console (Settings → API tokens, and Platform → Packs → Feedback → Author tooling for us).
-
-  **Why the platform needs this from you.** Almost every field report so far turned out to be
-  either already fixed in a newer CLI or written against a stale reference — three very different
-  answers that look identical without these two facts. They were captured on `octwin feedback`
-  only, so an author who never filed a report was invisible. Nothing here affects auth: a request
-  that sends neither header authenticates exactly as before, and a value that could not travel as
-  a header (a corrupt `package.json`, an interrupted pull) is dropped rather than sent.
-
-### Fixed
-- **The upgrade notice was skipped under `npx` — silencing the population most likely to be
-  stale.** The premise was that "`@latest` already resolves the newest", which holds for
-  `npx octwin-cli@latest` and is false for the bare `npx octwin-cli` the docs put in front of
-  external developers: npm serves that from its **cache**, so it can be arbitrarily old. Under
-  `@latest` the check is self-silencing anyway (you are already newest), so keeping it costs
-  nothing — only the advice line differs, because there is no global install to reinstall.
-
-## [0.8.8] - 2026-09-06
-
-### Added
-- **`octwin login` can sign you in through a browser — no token is pasted anywhere.** Run it with
-  no `--token` and it prints an approval link:
-
-  ```
-    Open this link to approve:  https://app.octwin.ai/cli-login?code=WDJB-MJHT
-    Code shown on that page:    WDJB-MJHT
-  ```
-
-  A workspace admin opens it, checks which machine is asking, and clicks Approve; the CLI collects a
-  30-day token by itself and saves it exactly where `--token` would have. `octwin login --token oct_…`
-  is unchanged, and CI should still skip login entirely and set `PACK_PLATFORM_URL` + `PACK_TOKEN`.
-
-  **The wait is bounded and resumable, because this CLI is mostly driven by an agent.** An agent's
-  shell call is killed after about two minutes, and a wait that outlives its caller is worse than a
-  short one — the process dies mid-handshake and the code the human is still typing belongs to
-  nothing. So `login` waits 90 seconds, then exits **75** (`EX_TEMPFAIL`) with the handshake kept in
-  `~/.octwin/pending-login.json`; running it again resumes the **same** code, which the platform
-  keeps alive for ten minutes. `0` still means signed in and `1` still means failed, so an agent
-  branches on the exit code instead of parsing prose. `--wait <seconds>` overrides the 90 (`--wait 0`
-  prints the code and returns at once), and `--json` prints the same facts as an object.
-
-  **Approve only a link you opened because you ran the command.** The link carries the code
-  (RFC 8628 `verification_uri_complete`), so the click *is* the consent: approving a link somebody
-  sent you would connect their machine to your workspace. The console says so on the page. The code
-  is printed here too, and shown there, so you can always tell one request from another.
-
-  The pending handshake gets its own file rather than a new key in `credentials.json`: every value
-  in that file is a token, and its one reserved key (`default_url`) is collision-free only because a
-  platform url always contains `://`. A second value shape there would end that argument.
-
-- **A 401 now points at `octwin login`, not at the console.** With a 30-day browser token, renewing is
-  one command; the old hint sent people to mint a replacement by hand. Mint a token yourself if you
-  want a different lifetime — the console offers 30 / 90 days / a year / never.
-
-## [0.8.7] - 2026-09-06
-
-### Added
-- **`validate` now reads a map's KEYS, not only its values.** The declaration walker reported four
-  things — an unknown key, a missing `required` key, a wrong scalar type, a value outside a closed
-  `enum` — and every one of them is about a VALUE. But a map's keys carry meaning in several
-  declarations (`roles.yaml` grant resources and verbs, `xrm.yaml` entity names), and those keys had
-  no check at all. Rule 5 replays `propertyNames` — both the `enum` and the `pattern` form.
-
-  This is why publishing the RBAC vocabulary was worth doing. A pack author wrote `case:` where the
-  grant key is `record.case`, passed offline `validate` clean, and learned the truth one bad guess at
-  a time from `--remote` round-trips. They gave up on custom RBAC over it. The check now says
-  `not a valid key here — must be one of "record.case", …` before a deploy is attempted.
-
-  It stays inside the file's false-positive rule because it is a **faithful replay**: the same `enum`
-  membership and the same JS regex engine Zod itself runs, over a pattern the platform generated. A
-  pattern this engine cannot compile is treated like a combinator — walk away, do not guess.
-
-  Verified 2026-09-06 against the shipped binary: across all 23 marketplace packs rule 5 reports
-  **nothing**, with 10 of the 12 pulled declaration schemas carrying `propertyNames` (so the silence
-  is a result, not an unexercised branch). A deliberately broken key is caught on both branches — a
-  role named `Regional-Agent` against `^[a-z][a-z0-9_]*$`, and a grant key `case:` against an enum
-  vocabulary — each naming the file, the path and the rule it broke.
-
-### Fixed
-- **`deploy` had stopped printing its seed counts entirely.** `printDeploySuccess` read
-  `r.summary.records` / `.updated` / `.images` / `.rules` / `.failed`, but the deploy route's
-  `summary` is a run-log **string** (`"clinic v1.2.0 — {…}"`), not an object. So every field was
-  `undefined`, `parts` stayed empty, and the `if (parts.length)` guard turned *"I am reading the
-  wrong field"* into *"there was nothing to say"* — the block printed nothing and looked like a
-  deploy that simply seeded no rows. The counts have been on `r.seeded`, keyed by seed kind, and
-  `printSeedCounts` already renders them (filtering zeros, which is what makes a partial seed
-  legible). The dead block is gone and `printSeedCounts` is called instead.
-
-  Same shape as the bug 0.8.6 fixed in `validate`: *no data* and *no problem* rendering identically.
-  Two independent places in this CLI reached it within one week.
-
-## [0.8.6] - 2026-09-04
-
-### Changed
-- **`validate` can no longer print a `✓` for a check that did not run.** Each of the eight
-  checks now RETURNS an `Outcome` — `passed`, `findings`, or `not-run` — and a single printer
-  renders all of them, groups the skips by reason, and computes the exit code. Previously each
-  check printed its own `✓` inside the `if` that held its data, with a `skipped[]` array and a
-  `skipReasons` Map maintained alongside; it was correct because someone was careful, and the
-  next check added was one `if` away from lying again.
-
-  It had lied twice, in the same shape: the KB-dependent block once printed ONE `✓` above six
-  checks whose own `✓`s lived inside their `if`s (so a run with no pulled KB read as "one check,
-  passed", and an entire backlog batch reached production that way), and `yamlDocs()` once
-  dropped an unparseable file so `validate` printed all-green over a pack the platform's importer
-  then refused. **An unparseable file is not "no findings", it is "no idea", and those must never
-  print the same** — a check that returns nothing now cannot reach the `passed` branch at all.
-
-  Output is unchanged for a normal run. `passed` carries its own line, so the reserved-entity
-  check keeps the narrower wording it uses when the catalog rules are absent from an older pull.
-  `--require-kb` is now one line over the returned skip list.
-
-  Verified 2026-09-04: all 23 marketplace packs exit 0 with no findings; a pack with no pulled KB
-  prints zero `✓` for the six KB-dependent checks plus one grouped ⚠ naming all six, and
-  `--require-kb` exits 1; a duplicate YAML key still exits 1 naming the file.
-
-## [0.8.5] - 2026-09-02
-
-### Added
-- **`octwin work --unrouted`** — the inbox filtered to items in NO queue. The route has always
-  supported the filter; the CLI never passed it, so `--queues` could tell you a count and not
-  show you the items behind it.
-
-### Changed
-- **`octwin work --queues` leads with the unrouted count.** It was already printed, as
-  `(unrouted: N open)` tucked under the queue list. A routed item sits in a list someone works;
-  an unrouted one sits in nobody's, so it is the only line on that screen that means "these are
-  lost". It is now a warning block that names the likely cause and points at `--unrouted`. Still
-  silent at zero — a clean project stays quiet, or the warning stops meaning anything.
-
-## [0.8.4] - 2026-09-02
-
-### Fixed
-- **A deploy whose seed failed still led with `✓ Deployed`.** The step errors were never
-  missing — `readDeployProgress` has collected every `status:'error'` frame into `stepErrors`
-  since 0.1.14, printed them, and exited non-zero. They were printed *after* `printDeploySuccess`,
-  so the first and largest line said `✓ Deployed` and the ⚠ came underneath. A pack author
-  reported their deploy as a clean success while its demo seed had failed; they were reading the
-  transcript exactly as written. The count now goes INTO the headline, which reads
-  `⚠ Deployed <id>@<v> onto <target> WITH n failure(s) — data may be incomplete`. `octwin seed`
-  gets the same treatment. *A signal that arrives after the verdict is not a signal.*
-- **The non-streaming deploy and seed paths had no step-error check at all.** With no SSE frames
-  to read, a failed seed printed a clean `✓` on that path even after the streaming one was fixed
-  in 0.1.14. Both now read `seed_failed` from the response body (new in the platform alongside
-  this release), print each failed kind with its reason, and exit non-zero.
-- **A partial demo seed is now reported as partial.** The platform no longer abandons the rest of
-  the seed when one demo row throws, so `Seeded:` gains an `n row(s) FAILED` part — without it a
-  partial seed reads as a complete one that simply had fewer records than the author wrote.
-
-## [0.8.3] - 2026-09-02
-
-### Fixed
-- **`validate` printed all-green over a pack the platform could not import.** Every YAML file was
-  parsed inside a `try { … } catch { return [] }`, so a file that failed to parse was silently
-  DROPPED from the list and every later check skipped it. The `catch` was justified in a comment —
-  "a syntax error is the structural gate's to report" — and that was not true: the structural gate
-  (`validatePackBundle`) checks paths, extensions and traversal, and never parses YAML.
-
-  Measured 2026-09-02: a duplicate `s_header:` key in a locale file passed `octwin validate` twice
-  and was then refused by the platform importer with `Map keys must be unique at line 24,
-  column 3` — the same message, from the same `yaml` version the CLI already had. The author's only
-  clue was a red box in the console naming no file.
-
-  YAML syntax is now its own announced gate that FAILS: it names each unparseable file with the
-  parser's own message and exits non-zero, before any check reads a document. An unparseable file is
-  not "no findings", it is "no idea", and the two must never print the same.
-
-- **Three more readers that turned "I could not read this" into a normal answer.** Swept every
-  discarding `catch` in the CLI after the above; three collapsed a real fault into an ordinary state:
-  - `readCreds` returned `{}` for a CORRUPT `credentials.json` as well as an absent one, so a token
-    the author knows they saved simply stopped being found and the advice was "log in" with no
-    mention of why. Now names the file and the parse error, once per process (it has three call
-    sites and one broken file is one problem).
-  - `readLocalKb` returned null for a half-written `.octwin/platform-kb/index.json` as well as a
-    never-pulled one — so an interrupted pull read as "you have not pulled yet" and the author
-    re-ran the command that left it that way. [`kb-path.ts`](src/lib/kb-path.ts) states this rule
-    for the DIRECTORY lookup; the index read beside it kept collapsing anyway. It now says which.
-  - The deploy progress stream discarded unparseable SSE frames silently. Skipping one is right;
-    skipping ALL of them left `terminal: null`, reported as "the stream ended without a terminal
-    event" — true, and indistinguishable from a dropped connection. The count is now named when
-    (and only when) no terminal frame arrived, pointing at a CLI older than its platform.
-
-  The other five discarding catches were read and LEFT: each returns a documented fallback for a
-  state that is genuinely ordinary (no update-check network, a heartbeat SSE frame with no `data:`).
-  `scripts/` was swept too and is clean by design — `kb-dataflow.mjs` skips a fence it cannot parse,
-  and `check-kb-examples.mjs` holds a non-vacuity FLOOR of 130 parsed fences so the skip cannot go
-  quiet. That is the better pattern where a skip is legitimate.
-
-## [0.8.1] - 2026-08-27
-
-### Fixed
-- **Logging in made `platform-kb pull` WORSE.** The command preferred the tenant-scoped route
-  whenever a token was saved, and that route is guarded by `pack:deploy` — so a developer holding a
-  token without that scope got a **403 on a pull that succeeds with no token at all**. It is the
-  likeliest token a new developer holds: no console preset could even reach `pack:deploy` before
-  2026-08-26. `platform-kb` now always uses the anonymous route and never sends a credential.
-  `--token` is accepted and ignored so existing scripts keep working.
-
-  The platform serves the *same* bundle from all three of its views — its route file states the
-  payload is identical and tenant-independent — so the authed route returned nothing extra and the
-  credential could only ever subtract. The two reasons the old code gave did not survive checking:
-  "keeps the author's own instance the source of truth" is vacuous (both routes are the same
-  instance), and "works against platforms that predate the public rung" is a backward-compatibility
-  shim this codebase does not carry.
-- **The drift nudge now works without a token.** It polled through the same authed route, so an
-  author inspecting data with a narrow token was told, every time, that it *could not* check —
-  advice in place of the signal. Both the poll and the apology are gone: the poll is anonymous, so
-  it simply works.
-
-## [0.8.0] - 2026-08-27
-
-### Added
-- **Five new command families, closing the gap between what a token reaches and what the CLI can
-  ask.** A **Full CLI access** token spans the whole scope registry, and four of those domains had
-  no command at all — so the reach existed and there was nothing to type.
-  - `octwin automation [campaigns]` — every job the pack's declaration produced, with status,
-    interval and last result (matched / acted / errors), under a health line whose counts come from
-    SQL rather than from filtering the page (the job list is capped server-side, so a client-side
-    count would depend on the cap). Writes: `run` · `pause` · `resume` · `send <campaignId>`.
-  - `octwin integrations` — what the pack **declares** beside what is actually **configured**, in
-    one view, because a connection declared and never configured is the commonest reason an
-    integration silently never fires and neither list alone can show it. Plus
-    `preflight <key>` (diagnosis, no outbound call, `integrations:read`), `test <key>` (a live call,
-    `integrations:write`, exits 1 on failure), `deliveries [id]`, `retry|cancel|send-now <id>`,
-    and `events` for what arrived inbound.
-  - `octwin journeys [id] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]`
-    — the declared journeys, measured. Same flag grammar as `octwin analytics` on purpose: a journey
-    funnel and an entity funnel are the same question about different subjects. `--definition` is
-    the one view that works with no traffic.
-  - `octwin performance [--detail]` — the project's business indicators, each with its delta against
-    the previous window and the `why` naming the declaration it came from. Needs `records:read`, not
-    a `performance:*` scope (there is none), so a read-only token already reaches it.
-  - `octwin usage` — model calls, tokens and cost, by model / kind / agent / channel; project when
-    one is pinned, workspace otherwise. Needs no particular scope. **Model spend only** —
-    WhatsApp/Meta message billing is operator-only and outside the token scope registry, which the
-    output says rather than leaving as an absence.
-- **`octwin automation run|pause|resume|send` accept the declaration KEY.** The routes take a UUID
-  and answer a bare *"Malformed identifier in the URL"* 400 for anything else — but the key
-  (`cart_recovery_nudge`) is what the list prints and what the author wrote in their own YAML. The
-  key is now resolved against the list route, and an unknown one fails naming the keys that exist.
-
-### Fixed
-- **A body-less write sent `content-type: application/json` and no body, so Fastify answered a bare
-  `400 Bad Request`.** `apiSend` set the header unconditionally; every caller until now passed an
-  object, so the branch was dead and the bug latent. The first body-less POST (`automation run`) hit
-  it immediately. The header is now omitted when there is no body — rather than each caller learning
-  to pass `{}`, which is the per-site divergence that helper exists to prevent.
-- **Four URLs were exempt from the route guard.** `cli-routes.test.ts` reads a template literal in
-  the first argument position, so `apiGet(base, t)` — a bare identifier — was never checked. That
-  covered the `scheduling` engine-state and `agents` roster calls, and would have covered the new
-  `journeys`, `performance` and `usage` ones. All now spelled as literals: the guard checks **62**
-  URLs, up from 45.
-
-## [0.7.3] - 2026-08-26
-
-### Changed
-- **A marketplace listing request is now OPT-IN: `octwin deploy --request-listing`.** A plain
-  `octwin deploy` says nothing about the public marketplace — it neither asks for a listing nor
-  gives one up. `--withdraw-listing` retracts, including an approved listing.
-  **Why:** the request was read from the manifest's `listing.public` on every deploy, and deploying
-  is how you *test*. 17 of the 23 published packs carry that key, so an edit-deploy-chat loop filed
-  a review request every time round. Worse, the *absence* of the key meant **retract** — so an
-  ordinary deploy of a pack whose manifest you had not yet annotated could wipe a listing you
-  already had. `--request-listing` still requires `listing.public: true` in the manifest (the
-  manifest states that the pack is a product; the flag is you choosing to ask), and the flag
-  without the key is a clean error rather than a silent no-op.
-- **The listing verdict distinguishes "you submitted this" from "your approval expired".** They are
-  both `pending` and they mean opposite things to an author. A deploy that changes the content of an
-  approved pack now says so in those words — an approval covers only the content it was made
-  against, so it cannot survive an edit.
-
-### Added
-- **A one-line nudge when your manifest asks and your deploy did not.** A pack carrying
-  `listing.public: true` that has never been submitted now prints the flag to use, so an opt-in
-  default cannot turn into waiting for a review nobody requested.
-
-### Fixed
-- **The "newer CLI" and "KB drifted" notices now print when a command FAILS.** All three nudges
-  (CLI upgrade · KB drift · unread memos) were awaited at the very end of `main()`, which silently
-  meant *only on success* — `die()` is a hard exit, so a failed deploy, an auth error or a bad
-  manifest printed none of them. That is backwards: a stale capability reference is a leading cause
-  of the failure an author is staring at, so the run that most needed the nudge was the only one
-  that never got it. They are now computed before the command and printed however it ends.
-- **The CLI-upgrade notice is no longer hidden from piped output.** It began with
-  `if (!process.stdout.isTTY) return`, so every agent-driven and CI run — the readers that cannot
-  notice an outdated CLI on their own — was the one audience never told. Its two siblings had
-  already dropped that gate for exactly this reason; now all three agree. Still skipped under
-  `npx`, where there is nothing to upgrade.
-- **`octwin login` now reports KB drift too.** It is networked and usually the first command of a
-  session, i.e. the best possible moment to say the reference moved, and it was excluded.
-- **A memo poll can no longer fail the command it was annotating.** It went through `apiGet` →
-  `fetchOrDie`, whose job is to `die` on a network failure — so an unreachable platform turned an
-  observer into a command failure. It now uses a plain, timed, fail-silent fetch.
-- **A failing command reports its real exit code again on Windows.** Moving the polls before the
-  command made `process.exit()` abort with `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`
-  and return **127** instead of 1 — so CI saw neither success nor the documented failure code. The
-  CLI now unwinds through a `CliExit` and lets the event loop drain, which is the only teardown
-  that is clean once the polls have opened sockets. `--check`'s exit 2 and the streaming commands
-  were re-verified.
-
-## [0.7.2] - 2026-08-20
-
-### Fixed
-- **`octwin feedback` now tells you what is already waiting, on stdout.** It discarded the submit
-  response entirely — destructuring `{ status, json }`, checking the status and never reading the
-  body — then printed *"a reply arrives as a memo, this CLI will tell you when one is waiting"*. The
-  platform started returning the unread counts on that response (2026-08-20), so the answer was
-  there to print and was being thrown away.
-  **Why it matters more than it sounds:** `notifyIfMemosWaiting` already covers this command and was
-  firing correctly — but it writes to **stderr**, and the authors driving this CLI are agents reading
-  stdout. The one signal that mattered was addressed to a channel nobody was listening on. On
-  2026-08-19 an author submitted two reports two hours after three replies were published and
-  re-reported five findings those replies had already closed. Now the count prints in the same block
-  as the acknowledgement, naming the command, and says outright when a reply may already answer what
-  you just sent. Against an older platform the field is absent and the previous line stands.
-
-## [0.7.1] - 2026-08-19
-
-### Fixed
-- **`work decide` now says when an action moves nothing.** `to_stage` is optional — an action may
-  record a decision without a transition — but both outputs communicated that by omission: `--dry-run`
-  left `to_stage: null` sitting among twenty other keys, and a real apply printed a bare
-  `✓ Applied '<action>'`. An author read both, shipped `request_more_info` with no `to_stage`, and
-  lost the `awaiting_customer` their whole customer-reply capture branched on — their words: *"Nothing
-  about this failed loudly; it just quietly never did the one thing the whole feature depends on."*
-  The preview now states `→ does NOT change the status (this action only records a decision)` and the
-  apply says `status unchanged (the action declares no to_stage)`. The console's decision panel got the
-  same sentence in the same change.
-
-## [0.7.0] - 2026-08-18
-
-### Added
-- **`octwin memos` — the channel answers now.** `octwin feedback` was one-way: an author reported and
-  heard nothing, ever. Two kinds arrive here, both printed in full — a **reply** to a report you sent,
-  and a **notice** published to every author (a new capability, a deprecation, a breaking change) —
-  each carrying `info` / `action_required` / `breaking`. Reading marks them read; `--all` re-reads
-  history and acks nothing (also the escape hatch if a piped `--json` consumer died halfway).
-- **Every networked command now says when a memo is waiting**, one line to stderr, always naming the
-  command to run. It rides work that was already networked, never throws, and is **deliberately not
-  TTY-gated** — the same reasoning as the KB drift nudge, whose docblock says it plainly: the primary
-  reader of this CLI is an authoring agent whose output is piped, and gating on `isTTY` means the one
-  reader that cannot notice on its own is the only one never told. Unlike that check there is no local
-  marker file: read state is per-workspace on the platform, so an agent in a fresh container still
-  learns about an unread reply.
-
-  Why it matters, measured: in August 2026 four reports sat unread for nine days, and one author
-  replaced every `$t()` call with hardcoded English across all 16 flows of a production pack to work
-  around a bug that had been fixed two days earlier. Nothing could tell them.
-
-## [0.6.1] - 2026-08-18
-
-### Fixed
-- **`octwin status` worked for no pack at all, and had not since 2026-08-01.** It sent the manifest's
-  **bare** id (`clinic`) to a route that requires the qualified `<owner>.<name>` — and a manifest
-  cannot legally declare the qualified form, because the owner segment is attached at publish time
-  from the authenticated publisher (both the platform and this CLI reject a `.` in it). So the route
-  answered 404 for every pack, every time. It now resolves the owner from `whoami`'s `tenant_slug`,
-  and takes an explicit `octwin status <packId>` when you already know it (from `octwin agents` or
-  `octwin projects`, both of which print qualified ids). Reported by two pack authors, who lost time
-  to a command that said their pack was missing seconds after a deploy the platform had accepted.
-- **A 404 from `octwin status` no longer always reads "not installed".** That one branch covered four
-  different failures — a malformed pack id, an unknown tenant, an unknown/pinned-elsewhere project,
-  and the genuine no-active-install — so the message named the *least* likely cause and sent an author
-  chasing a deploy that had already succeeded. The route says which; the CLI now relays it, and adds
-  the "run `octwin deploy` first" hint only to the case it fits.
-- **`octwin logs` always reported "No conversations"**, including immediately after an `octwin chat`
-  that had plainly worked. It read `conversations` off the response; the platform moved that endpoint
-  to the shared page envelope on 2026-08-09 and answers `rows`, which every other list command here
-  already reads. Both authors filed this as replica lag or a cache gap — nothing lagged, the payload
-  was simply never read. `octwin logs <conversationId>` was unaffected.
-
-## [0.6.0] - 2026-08-09
-
-### Changed
-- **`octwin cases` is now `octwin work`, and it works again.** The platform's work-inbox
-  consolidation (2026-08-08) replaced the case-only surface with `/work` over every entity a pack
-  declares worked, and renamed the scopes to `work:read`/`work:write` — which left every `octwin
-  cases` call a silent 404 in a published CLI. The command family is renamed to match the platform:
-  `octwin work [recordId] [--queues]`, with writes `assign` / `note` / `decide` (the declared
-  operator actions, `--dry-run` previews) and `stage <id> --to <s>` riding the one platform-wide
-  stage verb (`POST …/xrm/records/:id/stage`, needs `records:write`). `transition` is gone with the
-  route it called.
-- **`octwin orders transition` rides the same stage verb.** `POST …/orders/:ref/transition` was
-  retired server-side in the same consolidation; the CLI now resolves the order's record id from the
-  detail read and moves the stage through `…/xrm/records/:id/stage` (scope: `records:write`).
-
-### Added
-- **A route guard so this cannot rot silently again**: `src/lib/cli-routes.test.ts` extracts every
-  `/api/self/**` URL the CLI builds and asserts it (method included) against the platform's dumped
-  route table — the gap that let both breakages above ship.
-
-## [0.5.1] - 2026-08-01
-
-### Fixed
-- **`validate --remote` blamed the platform's version for a bad `--project`.** Every 404 from
-  `POST /api/self/p/packs/validate` printed *"this platform has no /packs/validate endpoint yet
-  (older version)"*. That was accurate when the route resolved nothing, but it now resolves the
-  tenant and project **before** validating — and an unknown project, or one outside a token's pin,
-  answers 404 by design. So a typo in `--project` sent you looking for a version mismatch instead of
-  at the flag. The two cases are now told apart by the response **body**, not the status: a missing
-  route is Fastify's `error: 'Not Found'` and keeps the old wording, while the platform's own
-  `project '<slug>' not found under tenant` is printed as-is, with the flags to check.
-
-## [0.5.0] - 2026-08-01
-
-### Added
-- **`octwin seed [--pack <packId>]`** — apply the pack's demo/reference data to the project it is
-  installed on, without redeploying: `xrm.yaml` `demo:` records + scheduling availability, the
-  commerce catalog, and the demo operator topology. Reports what **each kind** produced.
-  Previously seeding was reachable only as `deploy --seed`, because the platform's seed endpoint was
-  keyed on an install id, guarded platform-admin, and carried no tenant/project segments — so the
-  `/api/self/**` surface could not reach it and a `pack:deploy` token never could. Re-seeding meant
-  a full redeploy or asking an operator. Idempotent and cheap to re-run: records upsert, and
-  existing media is REUSED rather than regenerated, so a second pass reports zero images.
-
-## [0.4.0] - 2026-08-01
-
-### Added
-- **`octwin projects create` / `octwin projects rm`** — a **disposable end-to-end environment** from
-  the CLI, which is what marketplace developers have been missing. `octwin deploy` has always needed
-  a project that already existed and the CLI could only *list* them, so standing up a throwaway
-  full deployment meant opening the console or asking an operator. Now:
-  ```bash
-  octwin projects create "Scratch"          # → slug `scratch`
-  octwin deploy --project scratch --seed    # publish + install + demo data
-  octwin chat "hi" --project scratch        # talk to it (--script for a whole conversation)
-  octwin projects rm scratch --yes          # throw it away
-  ```
-  A throwaway environment is deliberately **not a special kind of thing** — it is an ordinary
-  project in your own workspace, so it inherits your plan, entitlements, RBAC and teardown with no
-  separate lifecycle. `create` derives the URL slug from the name (`--slug` pins one, `--pack`
-  installs an already-published pack). `rm` is a HARD delete — the project and everything cascading
-  from it, no undo, not the same as archiving — so **without `--yes` it only prints what would be
-  destroyed**, making the dry run the default; the impact list is derived from `pg_constraint`, the
-  same payload the console's confirm dialog renders. Both need `projects:write`, which a
-  `pack:deploy` token does **not** confer — the CLI names that scope in the 403 hint.
-
-## [0.3.0] - 2026-07-31
-
-### Added
-- **`octwin projects`** — the `--project <slug>` values your token can actually name, with the plan's
-  project cap. Every project-scoped command takes that flag and nothing printed the list, so an
-  author whose token was not pinned had to guess, and a wrong guess 404s identically to a project
-  that exists but has no install. `--archived` includes archived projects; `--json` for raw.
-  A `pack:deploy` token reaches it: the platform route was widened to accept `pack:deploy` alongside
-  `projects:read`, because `pack:deploy` is `access: 'special'` and confers nothing else — the
-  command would have 403ed for exactly the person it exists for.
-- **`octwin validate --require-kb`** — turn a skipped KB-driven check into a failure, for CI.
-
-### Fixed
-- **`octwin validate` printed ✓ with two of its three checks switched off.** The render-intent and
-  primitive-argument checks read `<packDir>/.octwin/platform-kb/`, joined onto the pack directory
-  EXACTLY — so an author who pulled once at a repo root and then worked in `packs/<name>/` had both
-  checks silently disabled, and the ✓ printed above them unconditionally while the per-check ✓s lived
-  inside the `if`s. An entire batch of platform-backlog entries reached production through that hole.
-  Three fixes: the KB is now found by **walking up** (one pull at a repo root covers every pack under
-  it, `src/lib/kb-path.ts`); the readers report **three states** — absent, malformed, ok — so a
-  half-written pull no longer reads as "you haven't pulled yet"; and a skip is **announced on the
-  last line printed**, because a caveat above a ✓ does not reach a reader who stopped at the ✓.
-  Warn-and-exit-0 stays the default (the KB is a gitignored cache and `platform-kb pull` needs
-  `pack:deploy`, so a hard failure would break a fresh clone) — the defect was the silence, not the skip.
-- **`octwin status` said "live and current" for a pack that could not receive a message.** Every field
-  it printed was process-global: `registered` is true for a pack ANY project on that instance loaded.
-  Dispatch is per-project and takes the oldest ACTIVE install, ignoring the rest. The route now
-  filters `status = 'active'` (an archived install used to report live) and compares against the real
-  dispatch target, so status can say plainly that another pack owns this project's messages.
-- **`octwin validate --remote --project does-not-exist` answered `{ ok: true }`** while `deploy` with
-  the same flag 404ed. The platform route resolves tenant and project before validating now.
-
-### Changed
-- **`octwin validate --remote` also runs the platform's flow LINT.** It used to run only at pack load,
-  so a finding of severity `error` — an `assign:` whose value is a quoted literal, a `$t()` key with
-  no namespace — passed validate and failed the deploy. Offline `validate` cannot do this: the lint
-  needs a template-expanded `FlowDef`, which only the server builds.
-- **`record_aggregate` / `record_group` now REQUIRE a scope** (`contact_id` or `all: true`) — a
-  platform contract change the offline arg check replays from the KB. Re-pull after upgrading.
-
-## [0.2.0] - 2026-07-30
-
-### Fixed
-- **`records`, `cases`, `orders` and `catalog` printed a correct total and ZERO rows.** The platform
-  collapsed its eight per-domain list envelopes into one `Page<T>` whose collection key is `rows`;
-  the CLI still read `json.records` / `.cases` / `.orders` / `.products` behind a `?? []`, so the
-  fallback turned a key rename into an empty list instead of an error. `octwin records doctor`
-  reported *"5 record(s)"* and then *"(none — mint a `records:read` token …)"*, blaming the user's
-  credentials. All five readers now go through one `readPage` helper
-  (`src/lib/page.ts`) with a test pinned to the real envelope — a hand-copied key name in an
-  untested CLI is what shipped this, so the fix is the single reader, not five edits.
-- **`--flag=value` silently did nothing.** `--limit=5` became the key `limit=5` and the command ran
-  with its default. Now parsed; `--set`/`--param` also accept repetition.
-- **`octwin catalog` always printed `Products: 0`** — it counted the page, and the route's `total`
-  had never been read.
-
-### Added
-- **Write commands — a pack author can now exercise the state their pack creates, not just read it.**
-  Every one needs the matching `:write` scope; a leading verb (`create`/`note`/`transition`/…) is
-  what distinguishes a write from the read that shares its command.
-  - `records create|patch|stage|note`, `records tasks`, `records task complete`
-  - `cases assign|note|transition|decide` — `decide --dry-run` previews the customer-facing copy and
-    resulting status **without committing** (that route needs only `cases:read`)
-  - `orders transition|refund` · `catalog availability|stock` · `agents set`
-  - `scheduling rules|rule add|rule rm|exception add|exception rm`
-- **`octwin feedback`** submits the pack's `FEEDBACK.md` to the platform team, attaching the pack
-  version, this CLI's version and the `content_hash` of the capability reference you pulled — the two
-  facts that separate a real platform gap from something already fixed or a stale KB. Replaces
-  "hand the file to the platform team".
-- **`--offset` on every list**, and a line saying when a list was truncated and what to run next.
-  `has_more` was on every response and no command surfaced it, so a partial list looked complete.
-
-### Changed
-- `orders refund` **exits non-zero when the payment gateway refuses.** The route answers `200` with
-  the verdict in `gateway`, so reporting the HTTP status would tell an operator money moved when it
-  did not.
-- A 403 on a record or case write now says it may be an **RBAC grant gap** rather than a missing
-  scope: the scope is checked on the token, then the verb is re-checked against that specific row.
-
-## [0.1.21] - 2026-07-30
-
-> **Never published to npm.** Bumped in-repo, then superseded hours later by 0.2.0 — everything
-> below ships as part of that release. Kept as its own section because the changes are distinct.
-
-### Added
-- **`deploy` and `status` report the marketplace-listing verdict.** A manifest carrying
-  `listing.public: true` put the pack into an operator review queue, and the state existed only in
-  the console — so an author working from the CLI got no acknowledgement that the request had
-  registered, and never saw a rejection note (which the platform *requires* precisely because it is
-  their only feedback). Both commands now print it via `printPublicListing`, and stay silent for a
-  pack that never asked. `status` also distinguishes *approved* from *actually public*: an approval
-  pins the content sha it reviewed, so any edit returns the pack to the queue on its own.
-- **`octwin pull` is discoverable.** It was implemented and answered `--help`, but appeared in
-  neither `octwin help` nor the README — the one command that recovers a deployed pack's only source
-  copy was invisible unless you already knew its name. Also added to the scope-requirement table, so
-  a 403 names `pack:deploy` instead of printing the generic hint.
-
-### Fixed
-- **The capability-reference drift check no longer fails silently on a narrow token.** The `?meta=1`
-  poll needs `pack:deploy`, but it rides on every networked command — so an author inspecting data
-  with a `records:read`-only token got no drift signal at all, and a stale reference is exactly what
-  leads to inventing a primitive from memory. A 401/403 there now says so once.
-- **README: casework is declared in `worklist.yaml`, not a `cases.yaml`.** That grammar was retired;
-  following the README produced a pack whose casework silently never loaded. `octwin media generate`
-  was also missing from the command table.
-- **`records` no longer blames the plan for a route the plan does not gate.** `GET /xrm/entities`
-  carries only the scope guard, so a 403 on the entity list wrongly cited the `records` plan feature.
-
-### Removed
-- **Unreachable rename branches in `init`.** The agent-id and `main`-flow renames sat behind
-  `--agent` / `--flow` options the CLI never parsed, against a template that ships no `main` flow —
-  both branches could never fire, and their patterns would have matched nothing if they had.
-
-## [0.1.20] - 2026-07-29
-
-### Added
-- **`octwin validate` catches primitive arguments the platform would drop — offline, no token.** A
-  primitive takes the arguments it declares and silently ignored the rest, so an invented or
-  misspelled `args:` key deployed clean, ran clean, and simply did nothing: `record_list args: {
-  order: … }` (the argument is `sort`) never ordered, and `booking_cancel args: { booking_record_id:
-  … }` meant the REQUIRED `record_id` never arrived, so cancelling just failed. Validate now replays
-  the platform's contract from the pulled KB (`primitives/*.json` → `inputSchema`) and names the bad
-  argument, what the primitive takes, and any required argument that is missing. Scanning the 21
-  shipped marketplace packs found **ten** such errors across five packs. Keys are checked, values are
-  not — an `args:` value is normally an expression string resolved at runtime.
-  [`args-check.ts`](src/lib/args-check.ts).
-  - Silently skipped when the KB has not been pulled yet, like the render-intent check beside it.
-  - It cannot see inside a `use:` template body (expanding one is the platform's job) — `octwin
-    validate --remote` covers that case, and now also reports unreachable `$bind.<path>` reads and
-    `outputs:` port typos, which have no offline equivalent.
-
-## [0.1.19] - 2026-07-29
-
-### Added
-- **`octwin validate` catches render-intent fields the platform would drop — offline, no token.** Each
-  render intent takes a fixed field set; a key outside it used to be swallowed at load and dropped at
-  render, with no error anywhere — just a card missing what the author wrote. Validate now replays the
-  platform's own contract from the pulled KB (`render-intents/*.json` → `allowed_keys`) and names the
-  bad field, the intent, and what is allowed. Scanning the 21 shipped marketplace packs found two real
-  instances in 223 intents: a `text_card` carrying `buttons` (the fallback's only escape button never
-  rendered) and a `list_picker` carrying a non-existent `group_by` (a whole mapper step feeding a
-  fabricated parameter). Silently skipped when the KB has not been pulled yet.
-
-### Changed
-- **`octwin platform-kb pull` now explodes the reference and writes an `INDEX.md`.** A pull used to
-  write ~787 KB across 34 flat files — about 225k tokens, more than the pack being authored — so
-  finding one primitive meant reading a 122 KB catalog. Catalogs the platform describes as
-  enumerable are now written **one file per entry** (`primitives/record_list.json`,
-  `render-intents/carousel.json`, `declarations/xrm.json`, …), with `INDEX.md` mapping every doc and
-  all 171 entries to its file with a one-line summary. Reading one primitive went from ~38k tokens to
-  ~700. The layout comes from the platform (an `entries` descriptor on the bundle index) rather than
-  being hardcoded here, so this CLI keeps working against any platform version and a platform that
-  adds a catalog needs no CLI release. The pulled directory is cleared each pull, so a withdrawn
-  capability cannot linger as a file the authoring agent reads as current — its *contents* are
-  cleared rather than the directory itself, since on Windows a directory that is any shell's working
-  directory cannot be removed.
-
-## [0.1.18] - 2026-07-29
-
-### Fixed
-- **The bundle collector and the platform's repo import disagreed about what a pack directory
-  contains.** `collectBundleFiles` had its own rule and kept three things the operator's GitHub
-  import drops: `*.ts`/`*.tsx`, `__snapshots__/` and `*.example`. Because the server rejects a
-  `.ts` outright, the same directory imported cleanly from GitHub and failed to deploy from
-  disk with `'…': executable code is not allowed` — an error blaming a file that was never
-  meant to ship (a snapshot test beside a flow, or the documented `xrm.yaml.example` template).
-  The rule now lives in a vendored `lib/pack-source.ts` beside the vendored validator, and a
-  parity test in the platform drives both copies over one table.
-
-### Removed
-- **`pack.json` is gone — the saved login IS the deploy target.** The file had eroded to a single
-  field, `platform_url`, which `octwin login --url … --token …` already states; `tenant`/`project`
-  became optional overrides once deploy tokens started carrying their own tenant and project pin.
-  So it was a second home for a fact `login` knew, and it cost real things: a machine-specific file
-  committed into every pack repo, a four-link config-precedence chain to document, and an
-  exclusion rule duplicated in the bundler and the server (which had already drifted apart).
-  `octwin init` and `octwin pull` no longer write one, and nothing reads one. **A pack directory is
-  now pack content and nothing else** — the same repo deploys from any machine, and a pulled pack
-  redeploys with no flags.
-
-### Changed
-- **`octwin login` now sets the default deploy target**, not just the token: it writes a
-  `default_url` key alongside the token in `~/.octwin/credentials.json`. Every command resolves
-  **flags → env (`PACK_PLATFORM_URL`/`PACK_TENANT`/`PACK_PROJECT`/`PACK_TOKEN`) → saved login**.
-  An existing credentials file simply has no `default_url` until the next `octwin login` — which is
-  exactly what the "no platform url" error now tells you to run. CI is unaffected (it passes
-  `PACK_PLATFORM_URL` + `PACK_TOKEN` as env and never had a `pack.json` — that file is retired).
-
-## [0.1.17] - 2026-07-27
-
-### Added
-- **`octwin pull <packId>` — write a DEPLOYED pack's source back to disk.** The inverse of
-  `deploy`. A pack pushed with the CLI lived on the platform as an artifact the runtime served
-  but nothing could hand back, so its only source copy was the machine that pushed it. Pull it,
-  fix it, redeploy it. Writes a `pack.json` (retired in 0.1.18 — the saved login is now the
-  target) so the pulled directory redeploys where it came from; `--version` picks a version,
-  `--force` overwrites a non-empty dir. You may pull a pack
-  your tenant OWNS (an operator token pulls any) — a pack you merely installed is not yours to
-  read.
-- **`octwin chat --script <file>` — drive a whole conversation from one invocation.** One turn per
-  line, in order, in a single process over a single SSE connection, waiting for each turn to settle
-  before sending the next. Blank lines and `#` comments are skipped; `tap:<id>` presses a rendered
-  row/button (the rest of the line is kept verbatim, since a tap id is itself colon-delimited),
-  `media:<path>` uploads a file, and `media:<path> | caption` attaches one.
-
-  This exists because **chaining invocations races the agent loop.** A turn ends on a quiet gap
-  (`TURN_SETTLE_MS`), which can arrive while the server-side loop is still running — so
-  `chat A && chat B` lets B's inbound land mid-turn, and the agent fills required fields with
-  placeholder text (`service_id: "service-id"`) or starts a second workflow run. Those look exactly
-  like flow bugs and cost a field author three separate investigations. The one-turn-per-invocation
-  rule is now stated in `chat --help` and the header usage as well.
-
-### Changed
-- **`octwin deploy` reports the suspended runs it invalidated.** A redeploy rebuilds the pack's
-  tools, and in-flight flow runs live in those tools — so every suspended conversation is dropped.
-  The deploy prints `ⓘ N suspended run(s) invalidated` when N > 0, instead of leaving the author to
-  discover it as a `workflow_resume_stale` on the next tap.
-
-## [0.1.16] - 2026-07-26
-
-### Added
-- **A pack can ship committed images.** `jpg`/`jpeg`/`png`/`webp`/`gif`/`pdf` files in your pack
-  directory now travel as a separate `blobs` half of the bundle (base64 on the wire, `bytea` in
-  storage) instead of being rejected as "not an allowed pack file type". Declare each one under the
-  manifest's `static_assets: [{ file, key }]` and reference it from `config:` with the
-  `$pack_asset:<key>` sentinel — the platform uploads it to the media system at install and the
-  sentinel resolves to the served URL. `octwin validate` reports the image count alongside the file
-  count.
-- **The size ceilings fail locally, before upload** — 2 MB per file, 32 MB of binary per pack,
-  mirroring the server. `svg` stays rejected: it is script-capable and these assets are served to
-  browsers.
-
-### Fixed
-- **Committed images were silently corrupted.** `collectBundleFiles` read *every* file with
-  `readFileSync(full, 'utf8')`, so a JPEG went through a lossy UTF-8 decode and arrived mangled
-  server-side — a deploy that "succeeded" and rendered a broken image. Binary files now split off
-  into `blobs` and keep their bytes.
-- **`octwin status` reported `loaded=(none)` for every pack, always.** It printed a `loaded_version`
-  field that stopped existing when reload moved to content-sha keying, which also meant the
-  version-drift warning underneath it could never fire. It now prints the **content sha** the
-  instance has loaded and the one the catalog holds (with the artifact's `origin`), and warns off the
-  platform's own `up_to_date` flag. The sha is the more useful fact anyway: re-publishing the *same*
-  version changes it, which is exactly the author's inner loop. A pack that is live and current but
-  **withdrawn** from the catalog now says so, rather than reporting a clean bill of health.
-
-## [0.1.15] - 2026-07-25
-
-### Added
-- **`octwin agents [packId::agentId] [--prompt]` — see what your agent actually runs as.** The platform
-  gained *governed* agent settings: an operator platform default can override the `default_model`
-  (and history window / working-memory toggle) your manifest declares, and that override is invisible
-  from the pack source. The command prints each governed setting's **effective** value, **which layer
-  won** (project override → platform default → pack manifest), and warns explicitly when your pack's
-  declared value is *not* in force. `--prompt` prints the exact system prompt the LLM sees for this
-  project (pack instructions + platform protocol + any project overlay).
-- **`octwin orders [reference_id]` — the commerce a conversation produced.** The list (number,
-  status/payment, total, contact) or one order with its line items, the
-  subtotal/tax/shipping/discount/total breakdown, `payment_ref`, and the allowed transitions. On a
-  `pending`/`none` payment it explains *why that's expected*: the forward payment lifecycle is
-  **webhook-owned** (not patchable), and the default gateway-less `manual` driver makes
-  `payment_request` take its `empty` port — so the flow should confirm pay-on-delivery, not error.
-- **`octwin analytics [entity]` — stage conversion for any pipelined entity.** The funnel engine that
-  powered journeys is now generic, so any entity declared with a `pipeline:` charts conversion +
-  drop-off (`--overview` / `--milestones` / `--trends` / `--cost`, and `--stage <id>` for the records
-  currently at a stage). An empty result names **both** causes the platform folds into one response —
-  no `pipeline:`, or no `view` grant on `record.<entity>`.
-- **`octwin catalog [--readiness]`** — commerce products with price, availability and stock
-  (`untracked` when the SKU isn't inventory-tracked), plus the WhatsApp catalog binding.
-  `--readiness` runs the Meta Graph checklist with each failing item's suggested fix.
-- **`octwin scheduling [--slots <resourceRecordId>]`** — the engine state (bookable resource types,
-  upcoming slots, booked seats) or the computed slots for one resource. This is how you verify the
-  availability rules a `deploy --seed` created, which 0.1.14 could create but not read back.
-
-### Changed
-- **Auth failures now name the scope the command needs.** Every 401/403 appends the required scope
-  (and the plan feature, where the route is entitlement-gated) from one client-side mirror of the
-  platform's scope registry — replacing the per-command hardcoded strings, several of which named no
-  scope at all. It also spells out that `pack:deploy` / `media:generate` are direct-grant only, so a
-  `tenant:admin` preset token does **not** confer them (the most common "but my token is admin" dead end).
-
-## [0.1.14] - 2026-07-23
-
-### Fixed
-- **A failed demo seed no longer reports a clean `✓`.** `deploy` softens non-fatal
-  install steps (e.g. a demo-seed row) to warning frames, but the summary still printed
-  `✓ Deployed` and exited 0 — so a deploy that seeded ZERO records read as success (the
-  false-✓ trap). `deploy` now collects those step errors, prints `⚠ Deployed with N
-  warning(s) — data may be incomplete` with each message, and exits non-zero so CI /
-  a `deploy && chat` chain catches it.
-
-### Added
-- **`login` echoes what the token reaches.** After saving, `octwin login` calls
-  `/api/self/t/whoami` and prints the workspace, project pin, and scopes — so a fresh
-  token self-identifies without a second `octwin whoami` (best-effort; a network failure
-  never fails the save).
-- **`validate --remote` surfaces warnings + the data-store trap.** The remote validate now
-  renders advisory `⚠` warnings (which don't block deploy) and, for a pack declaring
-  `required_adapters: [data-store]`, reports the missing-data-store error the deploy would
-  have 409'd on — plus a warning that an `xrm.yaml` pack usually shouldn't declare that
-  adapter at all. It also now catches (offline) a list-form `entities:` block and a
-  `localized: true` field seeded with a bare string — traps that previously surfaced only
-  mid-seed at deploy.
-
-## [0.1.13] - 2026-07-22
-
-### Added
-- **A headless media loop — produce + send.** Two paired additions close the coverage hole where any
-  media-collect flow (e.g. `activate-app`'s registration / ID uploads) stalled at the upload prompt
-  because the CLI could neither *make* nor *send* an image:
-  - `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]` — AI-generates an
-    image on the platform (needs a `media:generate`-scoped token), stores it as a public asset, and prints
-    its `MEDIA-` handle + serve URL. `--out` downloads the bytes to a file (WhatsApp renders only
-    `.png`/`.jpg`); `--json` emits `{ media_id, url, mime, width, height, bytes }`.
-  - `octwin chat --media <file|media-id>` — uploads a local file (or a media id from
-    `media generate --json`) as an image/document/audio inbound; any accompanying `"message"` rides as
-    its caption. The platform's media pipeline folds the upload into a running collect, so media flows
-    are now fully drivable headlessly.
-
-### Changed
-- **The KB-drift nudge now names what changed.** With the platform serving per-entry content hashes, the
-  post-command nudge appends a `(N changed · M added · K removed)` summary instead of a bare hash pair.
-- **`octwin platform-kb` prints a changelog on pull.** Instead of only a doc/catalog count, the pull now
-  diffs the fresh index against your last pull and lists exactly which docs/catalogs were added (`+`),
-  changed (`~`), or removed (`-`) — so a replaced schema shape is visible, not silent.
-
-## [0.1.12] - 2026-07-22
-
-### Fixed
-- **The KB-drift nudge now fires after `chat` too.** `chat` — the command a debugging session runs most —
-  was missing from the networked-command list, so a chat-heavy session never noticed the platform's
-  capability reference had moved. The nudge also now shows the concrete drift
-  (`old-hash → new-hash`) so you can see it's real, not a heuristic.
-
-### Changed
-- **Every networked command announces what it's doing before it does it.** `chat` prints
-  `→ Connecting to <tenant>/<project> as '<handle>' …` before opening the stream and
-  `… delivered — waiting for the reply (up to Ns)` after the send; `status` / `whoami` /
-  `platform-kb` / `records` / `logs` / `cases` each print a one-line `→ …` header naming the
-  action and target before the first network call — no more silent seconds followed by a result
-  (or a hang with no clue what was being attempted). JSON modes (`--json`) stay clean for piping.
-
-## [0.1.11] - 2026-07-21
-
-### Fixed
-- **Auth-failure hint on every command, not just the inspect family** (author-feedback A7). `validate`,
-  `deploy`, `status`, and the single-record read now print the scope/transient explanation on a 401/403
-  (the shared `authFailureHint`), instead of a bare `HTTP 401` that left it ambiguous whether the token
-  lacked a scope or the platform hiccupped.
-
-## [0.1.10] - 2026-07-21
-
-The capability reference is now **pulled, never bundled** — the authoring skill dropped its committed KB
-snapshot, so `octwin platform-kb pull` is the single source of truth, and the CLI watches it for drift.
-
-### Added
-- **KB-drift nudge** — after any command that already talks to the platform (`deploy` / `status` /
-  `test` / `validate --remote` / `records` / `cases` / `logs` / `whoami`), the CLI does one tiny
-  `octwin-platform-kb?meta=1` GET and prints a one-line "the platform capability reference changed —
-  `octwin platform-kb pull`" when the platform's `content_hash` no longer matches your last pull.
-  Fail-silent + TTY-only + no-op until you've pulled once — the sibling of the existing CLI-upgrade notice.
-
-### Changed
-- **`octwin platform-kb pull`** now records the reference's `content_hash` in `.octwin/platform-kb/index.json`
-  (the fingerprint the drift check compares against).
-
-The conversation-debugging release — driven by the second author-feedback round (xpeng-egypt),
-which found the author→validate→deploy loop solid but multi-turn debugging impossible from the CLI.
-
-### Added
-- **`octwin chat --tap "<tap-id>"`** — press a rendered button / list row (sends the web channel's
-  `type:'interactive'` inbound). Paired with full render printing, any tap-driven flow is now drivable headlessly.
-- **Full render printing** — every reply prints its complete interactive content: list sections/rows,
-  buttons, and carousel cards, each with its **tap id**; header/footer/list-button text included.
-- **`--json` on `chat` / `logs` / `cases`** — raw SSE envelopes (chat) or raw event/case payloads.
-- **`octwin cases [caseId] [--queues]`** — inspect casework (support tickets): the inbox, one case +
-  timeline + applicable decisions, or queue keys with open counts. Casework packs previously had zero
-  data-inspection path (`records case` was a dead end).
-- **Per-subcommand `--help`/`-h`** — intercepted before any network or auth work (previously
-  `octwin logs --help` made a network call and could die with a 401).
-- Multi-message turns: `chat` now collects **all** of a turn's renders (quiet-gap detection) instead
-  of cutting at the first one.
-
-### Changed
-- **`octwin logs`**: the conversation list shows contact handle + last activity and filters with
-  `--as <handle>`; the timeline prints **full** event text (no more 240-char truncation) plus the
-  renders each turn actually sent; footer points at `--json` / `mastra-messages` for verbatim payloads.
-- **Network failures name the target URL** (`platform unreachable at <url>`), and 401s explain
-  invalid-token vs one-off transient instead of a bare status code.
-- `octwin records` on an unknown entity now surfaces the server's error body, and for `case`/`cases`
-  points at `octwin cases`.
-
-### Fixed
-- **Multi-turn chat actually works.** Two bugs made consecutive `octwin chat` calls look like "every
-  call starts fresh": (1) the idempotency `local_id` was a **constant** per handle, so the platform's
-  5-minute inbound dedup silently dropped the second message — a fresh id is now minted per call;
-  (2) a fresh SSE connect **replays** recent history and the CLI printed the first render frame — i.e.
-  the *previous* turn's greeting — as the reply; the CLI now drains the replay and only accepts frames
-  newer than the connect boundary. The platform always kept one open conversation per `--as` handle —
-  the same handle genuinely continues the same conversation now.
-
-## [0.1.8] - 2026-07-21
-- Global-first install guidance (`npm i -g octwin-cli`); upgrade notice suppressed under `npx`.
-
-## [0.1.7] - 2026-07-21
-- `--version`/`-v` flag; daily fail-silent, TTY-only "newer version available" notice.
-
-## [0.1.6] - 2026-07-21
-- `octwin init` scaffolds a home-hub menu (`home` list_picker + example `browse` tool) instead of a bare greeting.
-
-## [0.1.5] - 2026-07-20
-- `octwin validate --remote` (the platform's FULL manifest + flow-DSL check, all errors at once);
-  headless debugging commands `octwin records` / `octwin logs` / `octwin chat`; `octwin test` became
-  an alias for `validate --remote`. First author-feedback round.
-
-## [0.1.4] - 2026-07-20
-- Authoring reliability + DX fixes from the first end-to-end external-pack test.
-
-## [0.1.3] - 2026-07-20
-- `octwin platform-kb pull` — pull the platform capability reference for the authoring skill.
-
-## [0.1.2] - 2026-07-20
-- Proper npm README.
-
-## [0.1.1] - 2026-07-20
-- Initial npm publish: `init` / `validate` / `login` / `whoami` / `deploy` / `status`, `oct_` deploy tokens.
+# Changelog — octwin-cli
+
+All notable changes to the `octwin` CLI (npm package [`octwin-cli`](https://www.npmjs.com/package/octwin-cli)).
+Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucketed into
+**Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
+repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
+
+## [Unreleased]
+
+## [0.8.17] - 2026-10-12
+
+### Added
+- **A deploy the checks refuse says what keeps running, then what to fix.** "✗ Not deployed — your live
+  version 2.1.0 keeps running, unchanged", then each problem once, grouped by what customers feel (`!`
+  now, `·` tidy-up) with your own messages under it. It printed the raw JSON body. `src/lib/refusal.ts`.
+- **A deploy says which copy it was made from, and is refused when someone published since.** `octwin pull`
+  and every successful `octwin deploy` write `.octwin-base.json` in the pack folder (commit it; it is
+  never deployed). The deploy sends it, and when the live version changed after your copy — Tavi in the
+  console, another deploy, a repo import — or your copy is a LOWER version, the platform refuses and
+  nothing changes; the message says who published and how to continue. `--force` deploys anyway.
+  `octwin status` shows whether your copy is still the live content. Rules: `src/lib/base.ts`.
+
+- **`octwin recipe <module>` names the other recipes it needs.** A recipe's buttons can open a flow
+  another recipe ships, and its `track:` can name a journey id another declares — booking's "no free
+  time" card opens handoff's `reception`, whose own buttons open casework's `ticket`. The command now
+  prints each recipe the pack still lacks (`octwin recipe handoff` …), worked out from the recipes' own
+  files (`recipeNeeds`, `src/lib/recipe.ts`), instead of the author meeting the chain as one validate
+  error after another.
+- **`octwin charts [<key>]`, `octwin surveys [<key>]` and `octwin handoff [<id>]`** — read-only views over
+  routes a token already reaches: the pack's own `charts:` (one chart's figure, parts or points, with
+  `--from` / `--to`), the surveys with their headline score (one survey's questions, rollup and answers),
+  and the Live chat desk (one handoff with its transcript). Accepting, answering and returning a handoff
+  stay in the console — those routes need a signed-in person, and a token is not one.
+- **`octwin performance --range <days> --channel <whatsapp|web>`** — the console's two controls, passed to
+  the route as `?range=` / `?channel=`.
+- **`octwin platform-kb pull` records the platform version that published the KB** (in `index.json`) and
+  prints it, so a FEEDBACK.md finding can cite the build it was read against.
+- **`octwin recipe [<module>]`** lists the recipes in the pulled KB, or writes one into the pack. It reads
+  the recipe's starter files from the pulled guide — no second copy to drift — and never overwrites: a file
+  you already have is named, a declaration you already have (your `xrm.yaml`) gets the recipe's part
+  printed to merge, and it prints the `flows:` / `tools:` lines to add (`src/lib/recipe.ts`).
+- **INDEX.md routes you: "Add per capability", "Start from a recipe", "When something is already
+  wrong".** `octwin platform-kb pull` prints the KB's route, its recipes and every guide's symptom rows
+  from the index the KB publishes — the tables `craft-capabilities` carries, from the same renderers
+  (`src/lib/kb-index.ts`).
+- **`octwin validate` checks journey ids offline.** Every literal id a flow names in `track:` or
+  `do: track_event` (`event`, `stage_enter`, `goal_reached`) must be declared by one of the pack's own
+  `journeys/*.journey.yaml`, each against its own list — a stage id does not satisfy `event:`. A pack
+  with no `journeys/` is told every such id is dead. Until now only the platform's full check caught
+  this, so an offline pass could ship a `track:` that fails mid-conversation, or a `track_event` that
+  takes its `failed` port on every run. Needs no pulled KB, so it never skips (`src/lib/journey-check.ts`).
+
+### Changed
+- **`octwin pull` updates the pack folder you are in, and never overwrites your own edits.** Run inside
+  the pack's folder it writes there (else `./<packId>`; `--dir` overrides). It replaces only files that
+  still match your last pull or deploy, removes files the live version dropped, and stops — listing them —
+  on a file you changed since, so you can save it first; `--force` overwrites. It used to refuse ANY
+  non-empty folder, and with `--force` it kept files the live version had deleted, which the next deploy
+  put back.
+- **A flag a command does not take is refused, naming the command's real flags.** It was ignored, so a
+  typo — or `performance --channel`, which the command never read — ran with the default and printed an
+  answer to another question. One table drives it: each command's `flags:` row plus `GLOBAL_FLAGS`
+  (`--url --tenant --project --token --json --help --dir`), and `cli.flags.test.ts` holds that table to the
+  code that reads the flags (a scan that fails closed), to `octwin help` / `--help`, and to the README.
+- **`octwin help` and the README now list every command and flag** — `seed`, `memos`, `projects create |
+  rm`, `chat --script` / `--press`, `validate --require-kb` / `--strict-primitives`, `agents set --enabled`
+  / `--overlay`, the paging flags. The README asks for Node ≥ 22 (as `engines` does), says `work stage`
+  and that `work decide --dry-run` needs only `work:read`, and `pull --help` says a first-party (Octwin)
+  pack can be pulled too.
+- **`octwin init` writes a bilingual starter that passes the platform's full check with no warning** —
+  Arabic and English, a home menu (its footer says `/clear` exists, and it marks the journey's first
+  stage), a visit request that is the KB's collect recipe byte for byte, `xrm.yaml` with demo rows, a
+  journey whose goal the record's own hook reaches, and `commands.yaml` answered in each customer's
+  language. The platform's KB test holds it to the full check alone and with every recipe added (it is the
+  cookbook's base). Its next steps and README point at `platform-kb pull`, `recipe` and `validate`.
+
+### Fixed
+- **`octwin init ./clinic` names the pack `clinic`.** The id is the directory's own name; `init` stripped
+  the slashes out of the whole path, so `./clinic` became `-clinic` (refused) and `packs/clinic` became
+  `packsclinic` (`src/lib/init-id.ts`).
+- **`octwin automation campaigns` prints each campaign** — its number, name, stage, delivery progress and id
+  — and says when one can be finished; it read fields the route never returns, so every row showed its uuid
+  and a dash. `octwin automation send` finishes a campaign stuck at `sending` and reports how many contacts
+  already had it.
+- **`octwin orders` explains the payment state it shows:** `none` is an order no payment was opened for (no
+  gateway), `pending` one whose checkout the gateway has not confirmed yet. It called `pending` expected
+  without a gateway.
+- **`octwin automation campaigns` with none says how one is made** — a flow's `campaign_create` step. It named a
+  `campaigns:` block in the automation declaration, which does not exist.
+
+## [0.8.16] - 2026-10-07
+
+### Changed
+- **`octwin performance --channel` marks a figure that is not narrowed.** Capacity has no channel, so a
+  band narrowed to one prints the capacity tile with `(all channels)` rather than letting it pass as the
+  channel's own.
+- **`octwin performance` prints a rate's change in points.** The platform
+  replaced each indicator's `delta_pct` with `change` (one rule for the console, the server and the CLI): a conversion rate going
+  42.9% → 57.1% now reads `+14.2 pts vs prev`, not `+33.1%`, and an NPS from −25 to +40 reads `+65`,
+  not `-260%`. A count still reads as a percent; growth from zero reads `new`.
+
+## [0.8.15] - 2026-10-06
+
+### Fixed
+- **`octwin records` said nothing useful for a pack with no record types of its own.** Its message read
+  `has_xrm`, which the platform never sent, so it could not show. The platform sends it now; the CLI
+  says the pack declares no record types and that platform records still read by name
+  (`octwin records order | product | case`). `records create` and `records tasks` read `has_data` —
+  "no AI Agent is loaded in this project" — instead of the same unsent field.
+
+## [0.8.14] - 2026-10-06
+
+### Added
+- **`octwin seed --reset`** — archive every row the pack's demo loaded, then load it again. Needed
+  once for demo rows seeded before 2026-10-05 (the seed says so), and a clean slate on demand; records
+  a customer made are never touched.
+- **`octwin records <entity> --search "<words>"`** — the entity's ranked search (fuzzy, plus semantic
+  when the entity declares it), best match first, each row printed with its score. The platform has
+  served it to the console for months; the CLI never asked. `--json` returns the rows with their scores.
+- **`press:<label>` in `octwin chat --script`, and `--press <label>`.** Taps the button of the reply just
+  received by its label — exactly, or the same words without emoji or case, or the one label containing
+  them. A form or checkout button's tap id carries its run id (`t:resume:…:run_id=…`), which exists only
+  once the reply arrives, so a script could not get past the first form step: `tap:` needs an id nobody
+  can write in advance. No match, or several buttons, stops the script and lists the buttons. A lone
+  `--press` picks from the reply the conversation is waiting on. The rules are the AI Author's `press`,
+  byte for byte (`src/lib/press.ts`). An older CLI sends a `press:` line as a typed message.
+
+### Fixed
+- **`octwin chat` prints a card's link buttons and its forms.** A button that opens a link prints as
+  `[link] title → url` (a card may now carry links beside its reply buttons), and a form prints as
+  `[flow form] …` — it compared the hint type `'flow'`, which the wire never sends (`form_flow`).
+- **`--json` output always parses.** `records --json` and `projects create --json` printed a
+  `→ Reading …` line in front of their JSON, and `logs --json` with no conversations printed a sentence
+  and no JSON at all (reported 2026-10-01). Under `--json`, stdout now carries the result and nothing
+  else — progress, tables and hints go to stderr — and every write verb of a JSON command (`records
+  create`, `work note`, `agents set`, `catalog stock`, `scheduling rule add`, `projects rm --yes`, …)
+  returns what the platform answered. A test runs every JSON command and parses its stdout.
+- **`octwin chat` prints the pictures, files, voice notes and map pins a reply carries.** Only a reply's
+  text and buttons were printed, so a reply that sent a picture read as a caption with nothing under it.
+  Now `[image] <path>` (without the signed query), `[file] <name> → <url>`, `[voice note] 12s → <url>`,
+  `[location] <name> (lat, long)`, and `(image)` on a carousel card that has a picture
+  (`src/lib/media-lines.ts`).
+
+### Changed
+- **`--json` on a command that has no JSON output is refused by name** (`whoami`, `deploy`, `validate`,
+  …), with the list of commands that have it. It used to print the prose to stderr and leave stdout
+  empty. `chat --json` and `login --json` print one JSON object per line, as before.
+- **Under `--json`, the progress lines move from stdout to stderr.** A script that read them from stdout
+  reads them from stderr now; human output (no `--json`) is unchanged.
+- **`octwin pull` can pull an Octwin (first-party) pack.** The platform now lets a workspace read the
+  source of its own packs and of Octwin's — never another workspace's — and the 403 hint says so. A
+  platform change: an older CLI pulls first-party packs too, it only prints the older hint.
+
+## [0.8.13] - 2026-09-27
+
+### Added
+- **`octwin records archive <id>` / `restore <id>`.** Archive is how a record leaves use — test data
+  included: it drops out of every list, count and report and fires the entity's `on.archived`
+  reactions, exactly like the console's Archive; `restore` undoes it. There is no delete, on the
+  platform or here, and `octwin records --help` now says so.
+
+### Fixed
+- **`octwin chat` said the AI Agent wrote every message.** A reminder that fired mid `--script` (a
+  `schedule_notify`, a reaction) printed as `← <body>`, was taken for the turn's reply, and ended
+  the turn on it — so the real reply looked lost while `octwin logs` showed the flow had worked.
+  Each line now says who sent it: `← [notify] …` (not the turn's answer — the wait for the real
+  reply goes on), `← [operator: Name] …` (a person in Live chat), `← [platform] …` (a handoff
+  joining or returning); plain `← …` is the AI Agent. After the last turn the stream stays open
+  3 s more, so a late message prints (marked "after the last turn") instead of reaching a closed
+  connection. Needs a platform that stamps `source: 'notify'` on web renders; an older one just
+  prints notifies unlabelled, as before.
+- **The "no such template" hint named a file the platform never loads.** It said
+  `templates/<name>.yaml`; pack templates load only as `templates/<name>.template.yaml`, so a
+  template saved as the hint said was silently ignored.
+
+### Changed
+- **`octwin validate` runs the platform's FULL check by default — and needs no login for it.** The
+  offline checks are a subset, and a subset that passes read as "deploy will pass": it passed a pack
+  the full check refused (a scaffold flow left behind with Arabic copy only, in a pack that ships
+  English). Now `validate` runs the offline checks, then the full one: through your workspace when you
+  have a token AND a `--project` (which also confirms the project exists), otherwise through the
+  platform's public validate route with no credential. When it cannot reach the full check — no url,
+  offline, rate-limited, an older platform — the LAST line says *"only the OFFLINE check ran — a
+  PARTIAL check"* and why, and it exits 0 as before. `--remote` now means "the full check is
+  required" (not reaching it is an error); the new `--offline` runs only the subset.
+- **The scaffold's example `browse` flow says it is an example.** Its header, its copy file and its
+  `manifest.yaml` line now say to replace it, or delete the flow, every `browse.locale.*.yaml` and the
+  `flows:` line together — a leftover never loads, but a second language makes it fail validation.
+
+## [0.8.12] - 2026-09-25
+
+### Changed
+- **The package pointed its `homepage` at npm — the page it is rendered on.** It is
+  <https://octwin.ai> now, and the README's Links section gains the platform, the guides and the
+  marketplace. The README describes Octwin at length and linked only to npm and nodejs.org.
+- **`octwin usage` with a project-pinned token reports that project.** The platform now treats a
+  token's project pin as a ceiling on every route, so a pinned token is refused on the
+  workspace-wide rollup. `usage` asks `whoami` for the pin and reads the project view instead of
+  printing a 403 — which is what its help text (`project if pinned, else workspace`) always said.
+
+### Fixed
+- **`octwin chat` sat out its whole 45-second wait on every message during a live handoff, and
+  read as hung.** While a person holds the conversation (or one has been asked for) the AI Agent
+  deliberately answers nothing, and the CLI could not tell that from a slow pack. The platform now
+  says so with a `held` event on the web stream; `chat` prints
+  *"⏸ a person is holding this conversation — the AI Agent will not reply…"* (or *"waiting for a
+  person to join…"*), still collects any operator line replayed by that message, and returns. A
+  held turn is not a failure: it exits 0, and `--script` carries on to the next line, so the
+  customer's side of a handoff can be scripted. Needs a platform that sends `held`; an older one
+  behaves as before. Reported in `xpeng-egypt/FEEDBACK.md`, session 3.
+
+## [0.8.11] - 2026-09-07
+
+### Fixed
+- **`octwin login` erased your own tooling report — the CLI was blanking what it had just
+  told the platform.** Two calls built their `authorization` header by hand instead of going
+  through `authHeaders`: `login`'s post-save "here's what your token reaches" echo, and
+  `chat`'s tenant/project derivation. Both authenticate, so both stamp the token's client
+  report (added in 0.8.9) — and a hand-built header stamps **NULL**, wiping the CLI version
+  and reference hash the platform had recorded.
+
+  Caught within an hour of 0.8.9 reaching staging: a workspace reported `0.8.9 · reference
+  current` at 12:16 and read `not reported` at 12:34. That looked exactly like the documented
+  "the column holds what ran LAST" behaviour and was really the CLI erasing its own row.
+  `cli-routes.test.ts` now fails on any hand-built bearer header, with a non-vacuity floor —
+  this package sits outside the repo's eslint scope, so a text guard is the only rung available.
+
+## [0.8.10] - 2026-09-07
+
+### Fixed
+- **`octwin memos` failed with `400 project required` for a tenant-wide token — the exact
+  command the nudge tells you to run.** Every networked command can end with
+  *"✉ N memos from the platform — read them: `octwin memos`"*, and running precisely that with
+  an unpinned token answered a 400. Measured on staging: the nudge fired during a
+  `deploy --project …` (which supplied a project) and then named a command that could not run.
+
+  A memo has no project dimension to scope by — neither `pack_memos` nor `pack_memo_reads`
+  carries a `project_id`, and the read ledger is keyed by tenant — so the three call sites now
+  use `/api/self/t/memos`. Passing `--project` still works and is no longer needed.
+
+## [0.8.9] - 2026-09-07
+
+### Added
+- **Every authenticated request now says which CLI and which capability reference you are on.**
+  Two headers off `authHeaders` — `x-octwin-cli` and `x-octwin-kb` (the `content_hash` of your
+  pulled reference) — so `deploy`, `validate --remote`, `status`, `chat`, `logs` and `memos` all
+  carry them, from one place. The platform stores them against your deploy token and shows them in
+  the console (Settings → API tokens, and Platform → Packs → Feedback → Author tooling for us).
+
+  **Why the platform needs this from you.** Almost every field report so far turned out to be
+  either already fixed in a newer CLI or written against a stale reference — three very different
+  answers that look identical without these two facts. They were captured on `octwin feedback`
+  only, so an author who never filed a report was invisible. Nothing here affects auth: a request
+  that sends neither header authenticates exactly as before, and a value that could not travel as
+  a header (a corrupt `package.json`, an interrupted pull) is dropped rather than sent.
+
+### Fixed
+- **The upgrade notice was skipped under `npx` — silencing the population most likely to be
+  stale.** The premise was that "`@latest` already resolves the newest", which holds for
+  `npx octwin-cli@latest` and is false for the bare `npx octwin-cli` the docs put in front of
+  external developers: npm serves that from its **cache**, so it can be arbitrarily old. Under
+  `@latest` the check is self-silencing anyway (you are already newest), so keeping it costs
+  nothing — only the advice line differs, because there is no global install to reinstall.
+
+## [0.8.8] - 2026-09-06
+
+### Added
+- **`octwin login` can sign you in through a browser — no token is pasted anywhere.** Run it with
+  no `--token` and it prints an approval link:
+
+  ```
+    Open this link to approve:  https://app.octwin.ai/cli-login?code=WDJB-MJHT
+    Code shown on that page:    WDJB-MJHT
+  ```
+
+  A workspace admin opens it, checks which machine is asking, and clicks Approve; the CLI collects a
+  30-day token by itself and saves it exactly where `--token` would have. `octwin login --token oct_…`
+  is unchanged, and CI should still skip login entirely and set `PACK_PLATFORM_URL` + `PACK_TOKEN`.
+
+  **The wait is bounded and resumable, because this CLI is mostly driven by an agent.** An agent's
+  shell call is killed after about two minutes, and a wait that outlives its caller is worse than a
+  short one — the process dies mid-handshake and the code the human is still typing belongs to
+  nothing. So `login` waits 90 seconds, then exits **75** (`EX_TEMPFAIL`) with the handshake kept in
+  `~/.octwin/pending-login.json`; running it again resumes the **same** code, which the platform
+  keeps alive for ten minutes. `0` still means signed in and `1` still means failed, so an agent
+  branches on the exit code instead of parsing prose. `--wait <seconds>` overrides the 90 (`--wait 0`
+  prints the code and returns at once), and `--json` prints the same facts as an object.
+
+  **Approve only a link you opened because you ran the command.** The link carries the code
+  (RFC 8628 `verification_uri_complete`), so the click *is* the consent: approving a link somebody
+  sent you would connect their machine to your workspace. The console says so on the page. The code
+  is printed here too, and shown there, so you can always tell one request from another.
+
+  The pending handshake gets its own file rather than a new key in `credentials.json`: every value
+  in that file is a token, and its one reserved key (`default_url`) is collision-free only because a
+  platform url always contains `://`. A second value shape there would end that argument.
+
+- **A 401 now points at `octwin login`, not at the console.** With a 30-day browser token, renewing is
+  one command; the old hint sent people to mint a replacement by hand. Mint a token yourself if you
+  want a different lifetime — the console offers 30 / 90 days / a year / never.
+
+## [0.8.7] - 2026-09-06
+
+### Added
+- **`validate` now reads a map's KEYS, not only its values.** The declaration walker reported four
+  things — an unknown key, a missing `required` key, a wrong scalar type, a value outside a closed
+  `enum` — and every one of them is about a VALUE. But a map's keys carry meaning in several
+  declarations (`roles.yaml` grant resources and verbs, `xrm.yaml` entity names), and those keys had
+  no check at all. Rule 5 replays `propertyNames` — both the `enum` and the `pattern` form.
+
+  This is why publishing the RBAC vocabulary was worth doing. A pack author wrote `case:` where the
+  grant key is `record.case`, passed offline `validate` clean, and learned the truth one bad guess at
+  a time from `--remote` round-trips. They gave up on custom RBAC over it. The check now says
+  `not a valid key here — must be one of "record.case", …` before a deploy is attempted.
+
+  It stays inside the file's false-positive rule because it is a **faithful replay**: the same `enum`
+  membership and the same JS regex engine Zod itself runs, over a pattern the platform generated. A
+  pattern this engine cannot compile is treated like a combinator — walk away, do not guess.
+
+  Verified 2026-09-06 against the shipped binary: across all 23 marketplace packs rule 5 reports
+  **nothing**, with 10 of the 12 pulled declaration schemas carrying `propertyNames` (so the silence
+  is a result, not an unexercised branch). A deliberately broken key is caught on both branches — a
+  role named `Regional-Agent` against `^[a-z][a-z0-9_]*$`, and a grant key `case:` against an enum
+  vocabulary — each naming the file, the path and the rule it broke.
+
+### Fixed
+- **`deploy` had stopped printing its seed counts entirely.** `printDeploySuccess` read
+  `r.summary.records` / `.updated` / `.images` / `.rules` / `.failed`, but the deploy route's
+  `summary` is a run-log **string** (`"clinic v1.2.0 — {…}"`), not an object. So every field was
+  `undefined`, `parts` stayed empty, and the `if (parts.length)` guard turned *"I am reading the
+  wrong field"* into *"there was nothing to say"* — the block printed nothing and looked like a
+  deploy that simply seeded no rows. The counts have been on `r.seeded`, keyed by seed kind, and
+  `printSeedCounts` already renders them (filtering zeros, which is what makes a partial seed
+  legible). The dead block is gone and `printSeedCounts` is called instead.
+
+  Same shape as the bug 0.8.6 fixed in `validate`: *no data* and *no problem* rendering identically.
+  Two independent places in this CLI reached it within one week.
+
+## [0.8.6] - 2026-09-04
+
+### Changed
+- **`validate` can no longer print a `✓` for a check that did not run.** Each of the eight
+  checks now RETURNS an `Outcome` — `passed`, `findings`, or `not-run` — and a single printer
+  renders all of them, groups the skips by reason, and computes the exit code. Previously each
+  check printed its own `✓` inside the `if` that held its data, with a `skipped[]` array and a
+  `skipReasons` Map maintained alongside; it was correct because someone was careful, and the
+  next check added was one `if` away from lying again.
+
+  It had lied twice, in the same shape: the KB-dependent block once printed ONE `✓` above six
+  checks whose own `✓`s lived inside their `if`s (so a run with no pulled KB read as "one check,
+  passed", and an entire backlog batch reached production that way), and `yamlDocs()` once
+  dropped an unparseable file so `validate` printed all-green over a pack the platform's importer
+  then refused. **An unparseable file is not "no findings", it is "no idea", and those must never
+  print the same** — a check that returns nothing now cannot reach the `passed` branch at all.
+
+  Output is unchanged for a normal run. `passed` carries its own line, so the reserved-entity
+  check keeps the narrower wording it uses when the catalog rules are absent from an older pull.
+  `--require-kb` is now one line over the returned skip list.
+
+  Verified 2026-09-04: all 23 marketplace packs exit 0 with no findings; a pack with no pulled KB
+  prints zero `✓` for the six KB-dependent checks plus one grouped ⚠ naming all six, and
+  `--require-kb` exits 1; a duplicate YAML key still exits 1 naming the file.
+
+## [0.8.5] - 2026-09-02
+
+### Added
+- **`octwin work --unrouted`** — the inbox filtered to items in NO queue. The route has always
+  supported the filter; the CLI never passed it, so `--queues` could tell you a count and not
+  show you the items behind it.
+
+### Changed
+- **`octwin work --queues` leads with the unrouted count.** It was already printed, as
+  `(unrouted: N open)` tucked under the queue list. A routed item sits in a list someone works;
+  an unrouted one sits in nobody's, so it is the only line on that screen that means "these are
+  lost". It is now a warning block that names the likely cause and points at `--unrouted`. Still
+  silent at zero — a clean project stays quiet, or the warning stops meaning anything.
+
+## [0.8.4] - 2026-09-02
+
+### Fixed
+- **A deploy whose seed failed still led with `✓ Deployed`.** The step errors were never
+  missing — `readDeployProgress` has collected every `status:'error'` frame into `stepErrors`
+  since 0.1.14, printed them, and exited non-zero. They were printed *after* `printDeploySuccess`,
+  so the first and largest line said `✓ Deployed` and the ⚠ came underneath. A pack author
+  reported their deploy as a clean success while its demo seed had failed; they were reading the
+  transcript exactly as written. The count now goes INTO the headline, which reads
+  `⚠ Deployed <id>@<v> onto <target> WITH n failure(s) — data may be incomplete`. `octwin seed`
+  gets the same treatment. *A signal that arrives after the verdict is not a signal.*
+- **The non-streaming deploy and seed paths had no step-error check at all.** With no SSE frames
+  to read, a failed seed printed a clean `✓` on that path even after the streaming one was fixed
+  in 0.1.14. Both now read `seed_failed` from the response body (new in the platform alongside
+  this release), print each failed kind with its reason, and exit non-zero.
+- **A partial demo seed is now reported as partial.** The platform no longer abandons the rest of
+  the seed when one demo row throws, so `Seeded:` gains an `n row(s) FAILED` part — without it a
+  partial seed reads as a complete one that simply had fewer records than the author wrote.
+
+## [0.8.3] - 2026-09-02
+
+### Fixed
+- **`validate` printed all-green over a pack the platform could not import.** Every YAML file was
+  parsed inside a `try { … } catch { return [] }`, so a file that failed to parse was silently
+  DROPPED from the list and every later check skipped it. The `catch` was justified in a comment —
+  "a syntax error is the structural gate's to report" — and that was not true: the structural gate
+  (`validatePackBundle`) checks paths, extensions and traversal, and never parses YAML.
+
+  Measured 2026-09-02: a duplicate `s_header:` key in a locale file passed `octwin validate` twice
+  and was then refused by the platform importer with `Map keys must be unique at line 24,
+  column 3` — the same message, from the same `yaml` version the CLI already had. The author's only
+  clue was a red box in the console naming no file.
+
+  YAML syntax is now its own announced gate that FAILS: it names each unparseable file with the
+  parser's own message and exits non-zero, before any check reads a document. An unparseable file is
+  not "no findings", it is "no idea", and the two must never print the same.
+
+- **Three more readers that turned "I could not read this" into a normal answer.** Swept every
+  discarding `catch` in the CLI after the above; three collapsed a real fault into an ordinary state:
+  - `readCreds` returned `{}` for a CORRUPT `credentials.json` as well as an absent one, so a token
+    the author knows they saved simply stopped being found and the advice was "log in" with no
+    mention of why. Now names the file and the parse error, once per process (it has three call
+    sites and one broken file is one problem).
+  - `readLocalKb` returned null for a half-written `.octwin/platform-kb/index.json` as well as a
+    never-pulled one — so an interrupted pull read as "you have not pulled yet" and the author
+    re-ran the command that left it that way. [`kb-path.ts`](src/lib/kb-path.ts) states this rule
+    for the DIRECTORY lookup; the index read beside it kept collapsing anyway. It now says which.
+  - The deploy progress stream discarded unparseable SSE frames silently. Skipping one is right;
+    skipping ALL of them left `terminal: null`, reported as "the stream ended without a terminal
+    event" — true, and indistinguishable from a dropped connection. The count is now named when
+    (and only when) no terminal frame arrived, pointing at a CLI older than its platform.
+
+  The other five discarding catches were read and LEFT: each returns a documented fallback for a
+  state that is genuinely ordinary (no update-check network, a heartbeat SSE frame with no `data:`).
+  `scripts/` was swept too and is clean by design — `kb-dataflow.mjs` skips a fence it cannot parse,
+  and `check-kb-examples.mjs` holds a non-vacuity FLOOR of 130 parsed fences so the skip cannot go
+  quiet. That is the better pattern where a skip is legitimate.
+
+## [0.8.1] - 2026-08-27
+
+### Fixed
+- **Logging in made `platform-kb pull` WORSE.** The command preferred the tenant-scoped route
+  whenever a token was saved, and that route is guarded by `pack:deploy` — so a developer holding a
+  token without that scope got a **403 on a pull that succeeds with no token at all**. It is the
+  likeliest token a new developer holds: no console preset could even reach `pack:deploy` before
+  2026-08-26. `platform-kb` now always uses the anonymous route and never sends a credential.
+  `--token` is accepted and ignored so existing scripts keep working.
+
+  The platform serves the *same* bundle from all three of its views — its route file states the
+  payload is identical and tenant-independent — so the authed route returned nothing extra and the
+  credential could only ever subtract. The two reasons the old code gave did not survive checking:
+  "keeps the author's own instance the source of truth" is vacuous (both routes are the same
+  instance), and "works against platforms that predate the public rung" is a backward-compatibility
+  shim this codebase does not carry.
+- **The drift nudge now works without a token.** It polled through the same authed route, so an
+  author inspecting data with a narrow token was told, every time, that it *could not* check —
+  advice in place of the signal. Both the poll and the apology are gone: the poll is anonymous, so
+  it simply works.
+
+## [0.8.0] - 2026-08-27
+
+### Added
+- **Five new command families, closing the gap between what a token reaches and what the CLI can
+  ask.** A **Full CLI access** token spans the whole scope registry, and four of those domains had
+  no command at all — so the reach existed and there was nothing to type.
+  - `octwin automation [campaigns]` — every job the pack's declaration produced, with status,
+    interval and last result (matched / acted / errors), under a health line whose counts come from
+    SQL rather than from filtering the page (the job list is capped server-side, so a client-side
+    count would depend on the cap). Writes: `run` · `pause` · `resume` · `send <campaignId>`.
+  - `octwin integrations` — what the pack **declares** beside what is actually **configured**, in
+    one view, because a connection declared and never configured is the commonest reason an
+    integration silently never fires and neither list alone can show it. Plus
+    `preflight <key>` (diagnosis, no outbound call, `integrations:read`), `test <key>` (a live call,
+    `integrations:write`, exits 1 on failure), `deliveries [id]`, `retry|cancel|send-now <id>`,
+    and `events` for what arrived inbound.
+  - `octwin journeys [id] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]`
+    — the declared journeys, measured. Same flag grammar as `octwin analytics` on purpose: a journey
+    funnel and an entity funnel are the same question about different subjects. `--definition` is
+    the one view that works with no traffic.
+  - `octwin performance [--detail]` — the project's business indicators, each with its delta against
+    the previous window and the `why` naming the declaration it came from. Needs `records:read`, not
+    a `performance:*` scope (there is none), so a read-only token already reaches it.
+  - `octwin usage` — model calls, tokens and cost, by model / kind / agent / channel; project when
+    one is pinned, workspace otherwise. Needs no particular scope. **Model spend only** —
+    WhatsApp/Meta message billing is operator-only and outside the token scope registry, which the
+    output says rather than leaving as an absence.
+- **`octwin automation run|pause|resume|send` accept the declaration KEY.** The routes take a UUID
+  and answer a bare *"Malformed identifier in the URL"* 400 for anything else — but the key
+  (`cart_recovery_nudge`) is what the list prints and what the author wrote in their own YAML. The
+  key is now resolved against the list route, and an unknown one fails naming the keys that exist.
+
+### Fixed
+- **A body-less write sent `content-type: application/json` and no body, so Fastify answered a bare
+  `400 Bad Request`.** `apiSend` set the header unconditionally; every caller until now passed an
+  object, so the branch was dead and the bug latent. The first body-less POST (`automation run`) hit
+  it immediately. The header is now omitted when there is no body — rather than each caller learning
+  to pass `{}`, which is the per-site divergence that helper exists to prevent.
+- **Four URLs were exempt from the route guard.** `cli-routes.test.ts` reads a template literal in
+  the first argument position, so `apiGet(base, t)` — a bare identifier — was never checked. That
+  covered the `scheduling` engine-state and `agents` roster calls, and would have covered the new
+  `journeys`, `performance` and `usage` ones. All now spelled as literals: the guard checks **62**
+  URLs, up from 45.
+
+## [0.7.3] - 2026-08-26
+
+### Changed
+- **A marketplace listing request is now OPT-IN: `octwin deploy --request-listing`.** A plain
+  `octwin deploy` says nothing about the public marketplace — it neither asks for a listing nor
+  gives one up. `--withdraw-listing` retracts, including an approved listing.
+  **Why:** the request was read from the manifest's `listing.public` on every deploy, and deploying
+  is how you *test*. 17 of the 23 published packs carry that key, so an edit-deploy-chat loop filed
+  a review request every time round. Worse, the *absence* of the key meant **retract** — so an
+  ordinary deploy of a pack whose manifest you had not yet annotated could wipe a listing you
+  already had. `--request-listing` still requires `listing.public: true` in the manifest (the
+  manifest states that the pack is a product; the flag is you choosing to ask), and the flag
+  without the key is a clean error rather than a silent no-op.
+- **The listing verdict distinguishes "you submitted this" from "your approval expired".** They are
+  both `pending` and they mean opposite things to an author. A deploy that changes the content of an
+  approved pack now says so in those words — an approval covers only the content it was made
+  against, so it cannot survive an edit.
+
+### Added
+- **A one-line nudge when your manifest asks and your deploy did not.** A pack carrying
+  `listing.public: true` that has never been submitted now prints the flag to use, so an opt-in
+  default cannot turn into waiting for a review nobody requested.
+
+### Fixed
+- **The "newer CLI" and "KB drifted" notices now print when a command FAILS.** All three nudges
+  (CLI upgrade · KB drift · unread memos) were awaited at the very end of `main()`, which silently
+  meant *only on success* — `die()` is a hard exit, so a failed deploy, an auth error or a bad
+  manifest printed none of them. That is backwards: a stale capability reference is a leading cause
+  of the failure an author is staring at, so the run that most needed the nudge was the only one
+  that never got it. They are now computed before the command and printed however it ends.
+- **The CLI-upgrade notice is no longer hidden from piped output.** It began with
+  `if (!process.stdout.isTTY) return`, so every agent-driven and CI run — the readers that cannot
+  notice an outdated CLI on their own — was the one audience never told. Its two siblings had
+  already dropped that gate for exactly this reason; now all three agree. Still skipped under
+  `npx`, where there is nothing to upgrade.
+- **`octwin login` now reports KB drift too.** It is networked and usually the first command of a
+  session, i.e. the best possible moment to say the reference moved, and it was excluded.
+- **A memo poll can no longer fail the command it was annotating.** It went through `apiGet` →
+  `fetchOrDie`, whose job is to `die` on a network failure — so an unreachable platform turned an
+  observer into a command failure. It now uses a plain, timed, fail-silent fetch.
+- **A failing command reports its real exit code again on Windows.** Moving the polls before the
+  command made `process.exit()` abort with `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`
+  and return **127** instead of 1 — so CI saw neither success nor the documented failure code. The
+  CLI now unwinds through a `CliExit` and lets the event loop drain, which is the only teardown
+  that is clean once the polls have opened sockets. `--check`'s exit 2 and the streaming commands
+  were re-verified.
+
+## [0.7.2] - 2026-08-20
+
+### Fixed
+- **`octwin feedback` now tells you what is already waiting, on stdout.** It discarded the submit
+  response entirely — destructuring `{ status, json }`, checking the status and never reading the
+  body — then printed *"a reply arrives as a memo, this CLI will tell you when one is waiting"*. The
+  platform started returning the unread counts on that response (2026-08-20), so the answer was
+  there to print and was being thrown away.
+  **Why it matters more than it sounds:** `notifyIfMemosWaiting` already covers this command and was
+  firing correctly — but it writes to **stderr**, and the authors driving this CLI are agents reading
+  stdout. The one signal that mattered was addressed to a channel nobody was listening on. On
+  2026-08-19 an author submitted two reports two hours after three replies were published and
+  re-reported five findings those replies had already closed. Now the count prints in the same block
+  as the acknowledgement, naming the command, and says outright when a reply may already answer what
+  you just sent. Against an older platform the field is absent and the previous line stands.
+
+## [0.7.1] - 2026-08-19
+
+### Fixed
+- **`work decide` now says when an action moves nothing.** `to_stage` is optional — an action may
+  record a decision without a transition — but both outputs communicated that by omission: `--dry-run`
+  left `to_stage: null` sitting among twenty other keys, and a real apply printed a bare
+  `✓ Applied '<action>'`. An author read both, shipped `request_more_info` with no `to_stage`, and
+  lost the `awaiting_customer` their whole customer-reply capture branched on — their words: *"Nothing
+  about this failed loudly; it just quietly never did the one thing the whole feature depends on."*
+  The preview now states `→ does NOT change the status (this action only records a decision)` and the
+  apply says `status unchanged (the action declares no to_stage)`. The console's decision panel got the
+  same sentence in the same change.
+
+## [0.7.0] - 2026-08-18
+
+### Added
+- **`octwin memos` — the channel answers now.** `octwin feedback` was one-way: an author reported and
+  heard nothing, ever. Two kinds arrive here, both printed in full — a **reply** to a report you sent,
+  and a **notice** published to every author (a new capability, a deprecation, a breaking change) —
+  each carrying `info` / `action_required` / `breaking`. Reading marks them read; `--all` re-reads
+  history and acks nothing (also the escape hatch if a piped `--json` consumer died halfway).
+- **Every networked command now says when a memo is waiting**, one line to stderr, always naming the
+  command to run. It rides work that was already networked, never throws, and is **deliberately not
+  TTY-gated** — the same reasoning as the KB drift nudge, whose docblock says it plainly: the primary
+  reader of this CLI is an authoring agent whose output is piped, and gating on `isTTY` means the one
+  reader that cannot notice on its own is the only one never told. Unlike that check there is no local
+  marker file: read state is per-workspace on the platform, so an agent in a fresh container still
+  learns about an unread reply.
+
+  Why it matters, measured: in August 2026 four reports sat unread for nine days, and one author
+  replaced every `$t()` call with hardcoded English across all 16 flows of a production pack to work
+  around a bug that had been fixed two days earlier. Nothing could tell them.
+
+## [0.6.1] - 2026-08-18
+
+### Fixed
+- **`octwin status` worked for no pack at all, and had not since 2026-08-01.** It sent the manifest's
+  **bare** id (`clinic`) to a route that requires the qualified `<owner>.<name>` — and a manifest
+  cannot legally declare the qualified form, because the owner segment is attached at publish time
+  from the authenticated publisher (both the platform and this CLI reject a `.` in it). So the route
+  answered 404 for every pack, every time. It now resolves the owner from `whoami`'s `tenant_slug`,
+  and takes an explicit `octwin status <packId>` when you already know it (from `octwin agents` or
+  `octwin projects`, both of which print qualified ids). Reported by two pack authors, who lost time
+  to a command that said their pack was missing seconds after a deploy the platform had accepted.
+- **A 404 from `octwin status` no longer always reads "not installed".** That one branch covered four
+  different failures — a malformed pack id, an unknown tenant, an unknown/pinned-elsewhere project,
+  and the genuine no-active-install — so the message named the *least* likely cause and sent an author
+  chasing a deploy that had already succeeded. The route says which; the CLI now relays it, and adds
+  the "run `octwin deploy` first" hint only to the case it fits.
+- **`octwin logs` always reported "No conversations"**, including immediately after an `octwin chat`
+  that had plainly worked. It read `conversations` off the response; the platform moved that endpoint
+  to the shared page envelope on 2026-08-09 and answers `rows`, which every other list command here
+  already reads. Both authors filed this as replica lag or a cache gap — nothing lagged, the payload
+  was simply never read. `octwin logs <conversationId>` was unaffected.
+
+## [0.6.0] - 2026-08-09
+
+### Changed
+- **`octwin cases` is now `octwin work`, and it works again.** The platform's work-inbox
+  consolidation (2026-08-08) replaced the case-only surface with `/work` over every entity a pack
+  declares worked, and renamed the scopes to `work:read`/`work:write` — which left every `octwin
+  cases` call a silent 404 in a published CLI. The command family is renamed to match the platform:
+  `octwin work [recordId] [--queues]`, with writes `assign` / `note` / `decide` (the declared
+  operator actions, `--dry-run` previews) and `stage <id> --to <s>` riding the one platform-wide
+  stage verb (`POST …/xrm/records/:id/stage`, needs `records:write`). `transition` is gone with the
+  route it called.
+- **`octwin orders transition` rides the same stage verb.** `POST …/orders/:ref/transition` was
+  retired server-side in the same consolidation; the CLI now resolves the order's record id from the
+  detail read and moves the stage through `…/xrm/records/:id/stage` (scope: `records:write`).
+
+### Added
+- **A route guard so this cannot rot silently again**: `src/lib/cli-routes.test.ts` extracts every
+  `/api/self/**` URL the CLI builds and asserts it (method included) against the platform's dumped
+  route table — the gap that let both breakages above ship.
+
+## [0.5.1] - 2026-08-01
+
+### Fixed
+- **`validate --remote` blamed the platform's version for a bad `--project`.** Every 404 from
+  `POST /api/self/p/packs/validate` printed *"this platform has no /packs/validate endpoint yet
+  (older version)"*. That was accurate when the route resolved nothing, but it now resolves the
+  tenant and project **before** validating — and an unknown project, or one outside a token's pin,
+  answers 404 by design. So a typo in `--project` sent you looking for a version mismatch instead of
+  at the flag. The two cases are now told apart by the response **body**, not the status: a missing
+  route is Fastify's `error: 'Not Found'` and keeps the old wording, while the platform's own
+  `project '<slug>' not found under tenant` is printed as-is, with the flags to check.
+
+## [0.5.0] - 2026-08-01
+
+### Added
+- **`octwin seed [--pack <packId>]`** — apply the pack's demo/reference data to the project it is
+  installed on, without redeploying: `xrm.yaml` `demo:` records + scheduling availability, the
+  commerce catalog, and the demo operator topology. Reports what **each kind** produced.
+  Previously seeding was reachable only as `deploy --seed`, because the platform's seed endpoint was
+  keyed on an install id, guarded platform-admin, and carried no tenant/project segments — so the
+  `/api/self/**` surface could not reach it and a `pack:deploy` token never could. Re-seeding meant
+  a full redeploy or asking an operator. Idempotent and cheap to re-run: records upsert, and
+  existing media is REUSED rather than regenerated, so a second pass reports zero images.
+
+## [0.4.0] - 2026-08-01
+
+### Added
+- **`octwin projects create` / `octwin projects rm`** — a **disposable end-to-end environment** from
+  the CLI, which is what marketplace developers have been missing. `octwin deploy` has always needed
+  a project that already existed and the CLI could only *list* them, so standing up a throwaway
+  full deployment meant opening the console or asking an operator. Now:
+  ```bash
+  octwin projects create "Scratch"          # → slug `scratch`
+  octwin deploy --project scratch --seed    # publish + install + demo data
+  octwin chat "hi" --project scratch        # talk to it (--script for a whole conversation)
+  octwin projects rm scratch --yes          # throw it away
+  ```
+  A throwaway environment is deliberately **not a special kind of thing** — it is an ordinary
+  project in your own workspace, so it inherits your plan, entitlements, RBAC and teardown with no
+  separate lifecycle. `create` derives the URL slug from the name (`--slug` pins one, `--pack`
+  installs an already-published pack). `rm` is a HARD delete — the project and everything cascading
+  from it, no undo, not the same as archiving — so **without `--yes` it only prints what would be
+  destroyed**, making the dry run the default; the impact list is derived from `pg_constraint`, the
+  same payload the console's confirm dialog renders. Both need `projects:write`, which a
+  `pack:deploy` token does **not** confer — the CLI names that scope in the 403 hint.
+
+## [0.3.0] - 2026-07-31
+
+### Added
+- **`octwin projects`** — the `--project <slug>` values your token can actually name, with the plan's
+  project cap. Every project-scoped command takes that flag and nothing printed the list, so an
+  author whose token was not pinned had to guess, and a wrong guess 404s identically to a project
+  that exists but has no install. `--archived` includes archived projects; `--json` for raw.
+  A `pack:deploy` token reaches it: the platform route was widened to accept `pack:deploy` alongside
+  `projects:read`, because `pack:deploy` is `access: 'special'` and confers nothing else — the
+  command would have 403ed for exactly the person it exists for.
+- **`octwin validate --require-kb`** — turn a skipped KB-driven check into a failure, for CI.
+
+### Fixed
+- **`octwin validate` printed ✓ with two of its three checks switched off.** The render-intent and
+  primitive-argument checks read `<packDir>/.octwin/platform-kb/`, joined onto the pack directory
+  EXACTLY — so an author who pulled once at a repo root and then worked in `packs/<name>/` had both
+  checks silently disabled, and the ✓ printed above them unconditionally while the per-check ✓s lived
+  inside the `if`s. An entire batch of platform-backlog entries reached production through that hole.
+  Three fixes: the KB is now found by **walking up** (one pull at a repo root covers every pack under
+  it, `src/lib/kb-path.ts`); the readers report **three states** — absent, malformed, ok — so a
+  half-written pull no longer reads as "you haven't pulled yet"; and a skip is **announced on the
+  last line printed**, because a caveat above a ✓ does not reach a reader who stopped at the ✓.
+  Warn-and-exit-0 stays the default (the KB is a gitignored cache and `platform-kb pull` needs
+  `pack:deploy`, so a hard failure would break a fresh clone) — the defect was the silence, not the skip.
+- **`octwin status` said "live and current" for a pack that could not receive a message.** Every field
+  it printed was process-global: `registered` is true for a pack ANY project on that instance loaded.
+  Dispatch is per-project and takes the oldest ACTIVE install, ignoring the rest. The route now
+  filters `status = 'active'` (an archived install used to report live) and compares against the real
+  dispatch target, so status can say plainly that another pack owns this project's messages.
+- **`octwin validate --remote --project does-not-exist` answered `{ ok: true }`** while `deploy` with
+  the same flag 404ed. The platform route resolves tenant and project before validating now.
+
+### Changed
+- **`octwin validate --remote` also runs the platform's flow LINT.** It used to run only at pack load,
+  so a finding of severity `error` — an `assign:` whose value is a quoted literal, a `$t()` key with
+  no namespace — passed validate and failed the deploy. Offline `validate` cannot do this: the lint
+  needs a template-expanded `FlowDef`, which only the server builds.
+- **`record_aggregate` / `record_group` now REQUIRE a scope** (`contact_id` or `all: true`) — a
+  platform contract change the offline arg check replays from the KB. Re-pull after upgrading.
+
+## [0.2.0] - 2026-07-30
+
+### Fixed
+- **`records`, `cases`, `orders` and `catalog` printed a correct total and ZERO rows.** The platform
+  collapsed its eight per-domain list envelopes into one `Page<T>` whose collection key is `rows`;
+  the CLI still read `json.records` / `.cases` / `.orders` / `.products` behind a `?? []`, so the
+  fallback turned a key rename into an empty list instead of an error. `octwin records doctor`
+  reported *"5 record(s)"* and then *"(none — mint a `records:read` token …)"*, blaming the user's
+  credentials. All five readers now go through one `readPage` helper
+  (`src/lib/page.ts`) with a test pinned to the real envelope — a hand-copied key name in an
+  untested CLI is what shipped this, so the fix is the single reader, not five edits.
+- **`--flag=value` silently did nothing.** `--limit=5` became the key `limit=5` and the command ran
+  with its default. Now parsed; `--set`/`--param` also accept repetition.
+- **`octwin catalog` always printed `Products: 0`** — it counted the page, and the route's `total`
+  had never been read.
+
+### Added
+- **Write commands — a pack author can now exercise the state their pack creates, not just read it.**
+  Every one needs the matching `:write` scope; a leading verb (`create`/`note`/`transition`/…) is
+  what distinguishes a write from the read that shares its command.
+  - `records create|patch|stage|note`, `records tasks`, `records task complete`
+  - `cases assign|note|transition|decide` — `decide --dry-run` previews the customer-facing copy and
+    resulting status **without committing** (that route needs only `cases:read`)
+  - `orders transition|refund` · `catalog availability|stock` · `agents set`
+  - `scheduling rules|rule add|rule rm|exception add|exception rm`
+- **`octwin feedback`** submits the pack's `FEEDBACK.md` to the platform team, attaching the pack
+  version, this CLI's version and the `content_hash` of the capability reference you pulled — the two
+  facts that separate a real platform gap from something already fixed or a stale KB. Replaces
+  "hand the file to the platform team".
+- **`--offset` on every list**, and a line saying when a list was truncated and what to run next.
+  `has_more` was on every response and no command surfaced it, so a partial list looked complete.
+
+### Changed
+- `orders refund` **exits non-zero when the payment gateway refuses.** The route answers `200` with
+  the verdict in `gateway`, so reporting the HTTP status would tell an operator money moved when it
+  did not.
+- A 403 on a record or case write now says it may be an **RBAC grant gap** rather than a missing
+  scope: the scope is checked on the token, then the verb is re-checked against that specific row.
+
+## [0.1.21] - 2026-07-30
+
+> **Never published to npm.** Bumped in-repo, then superseded hours later by 0.2.0 — everything
+> below ships as part of that release. Kept as its own section because the changes are distinct.
+
+### Added
+- **`deploy` and `status` report the marketplace-listing verdict.** A manifest carrying
+  `listing.public: true` put the pack into an operator review queue, and the state existed only in
+  the console — so an author working from the CLI got no acknowledgement that the request had
+  registered, and never saw a rejection note (which the platform *requires* precisely because it is
+  their only feedback). Both commands now print it via `printPublicListing`, and stay silent for a
+  pack that never asked. `status` also distinguishes *approved* from *actually public*: an approval
+  pins the content sha it reviewed, so any edit returns the pack to the queue on its own.
+- **`octwin pull` is discoverable.** It was implemented and answered `--help`, but appeared in
+  neither `octwin help` nor the README — the one command that recovers a deployed pack's only source
+  copy was invisible unless you already knew its name. Also added to the scope-requirement table, so
+  a 403 names `pack:deploy` instead of printing the generic hint.
+
+### Fixed
+- **The capability-reference drift check no longer fails silently on a narrow token.** The `?meta=1`
+  poll needs `pack:deploy`, but it rides on every networked command — so an author inspecting data
+  with a `records:read`-only token got no drift signal at all, and a stale reference is exactly what
+  leads to inventing a primitive from memory. A 401/403 there now says so once.
+- **README: casework is declared in `worklist.yaml`, not a `cases.yaml`.** That grammar was retired;
+  following the README produced a pack whose casework silently never loaded. `octwin media generate`
+  was also missing from the command table.
+- **`records` no longer blames the plan for a route the plan does not gate.** `GET /xrm/entities`
+  carries only the scope guard, so a 403 on the entity list wrongly cited the `records` plan feature.
+
+### Removed
+- **Unreachable rename branches in `init`.** The agent-id and `main`-flow renames sat behind
+  `--agent` / `--flow` options the CLI never parsed, against a template that ships no `main` flow —
+  both branches could never fire, and their patterns would have matched nothing if they had.
+
+## [0.1.20] - 2026-07-29
+
+### Added
+- **`octwin validate` catches primitive arguments the platform would drop — offline, no token.** A
+  primitive takes the arguments it declares and silently ignored the rest, so an invented or
+  misspelled `args:` key deployed clean, ran clean, and simply did nothing: `record_list args: {
+  order: … }` (the argument is `sort`) never ordered, and `booking_cancel args: { booking_record_id:
+  … }` meant the REQUIRED `record_id` never arrived, so cancelling just failed. Validate now replays
+  the platform's contract from the pulled KB (`primitives/*.json` → `inputSchema`) and names the bad
+  argument, what the primitive takes, and any required argument that is missing. Scanning the 21
+  shipped marketplace packs found **ten** such errors across five packs. Keys are checked, values are
+  not — an `args:` value is normally an expression string resolved at runtime.
+  [`args-check.ts`](src/lib/args-check.ts).
+  - Silently skipped when the KB has not been pulled yet, like the render-intent check beside it.
+  - It cannot see inside a `use:` template body (expanding one is the platform's job) — `octwin
+    validate --remote` covers that case, and now also reports unreachable `$bind.<path>` reads and
+    `outputs:` port typos, which have no offline equivalent.
+
+## [0.1.19] - 2026-07-29
+
+### Added
+- **`octwin validate` catches render-intent fields the platform would drop — offline, no token.** Each
+  render intent takes a fixed field set; a key outside it used to be swallowed at load and dropped at
+  render, with no error anywhere — just a card missing what the author wrote. Validate now replays the
+  platform's own contract from the pulled KB (`render-intents/*.json` → `allowed_keys`) and names the
+  bad field, the intent, and what is allowed. Scanning the 21 shipped marketplace packs found two real
+  instances in 223 intents: a `text_card` carrying `buttons` (the fallback's only escape button never
+  rendered) and a `list_picker` carrying a non-existent `group_by` (a whole mapper step feeding a
+  fabricated parameter). Silently skipped when the KB has not been pulled yet.
+
+### Changed
+- **`octwin platform-kb pull` now explodes the reference and writes an `INDEX.md`.** A pull used to
+  write ~787 KB across 34 flat files — about 225k tokens, more than the pack being authored — so
+  finding one primitive meant reading a 122 KB catalog. Catalogs the platform describes as
+  enumerable are now written **one file per entry** (`primitives/record_list.json`,
+  `render-intents/carousel.json`, `declarations/xrm.json`, …), with `INDEX.md` mapping every doc and
+  all 171 entries to its file with a one-line summary. Reading one primitive went from ~38k tokens to
+  ~700. The layout comes from the platform (an `entries` descriptor on the bundle index) rather than
+  being hardcoded here, so this CLI keeps working against any platform version and a platform that
+  adds a catalog needs no CLI release. The pulled directory is cleared each pull, so a withdrawn
+  capability cannot linger as a file the authoring agent reads as current — its *contents* are
+  cleared rather than the directory itself, since on Windows a directory that is any shell's working
+  directory cannot be removed.
+
+## [0.1.18] - 2026-07-29
+
+### Fixed
+- **The bundle collector and the platform's repo import disagreed about what a pack directory
+  contains.** `collectBundleFiles` had its own rule and kept three things the operator's GitHub
+  import drops: `*.ts`/`*.tsx`, `__snapshots__/` and `*.example`. Because the server rejects a
+  `.ts` outright, the same directory imported cleanly from GitHub and failed to deploy from
+  disk with `'…': executable code is not allowed` — an error blaming a file that was never
+  meant to ship (a snapshot test beside a flow, or the documented `xrm.yaml.example` template).
+  The rule now lives in a vendored `lib/pack-source.ts` beside the vendored validator, and a
+  parity test in the platform drives both copies over one table.
+
+### Removed
+- **`pack.json` is gone — the saved login IS the deploy target.** The file had eroded to a single
+  field, `platform_url`, which `octwin login --url … --token …` already states; `tenant`/`project`
+  became optional overrides once deploy tokens started carrying their own tenant and project pin.
+  So it was a second home for a fact `login` knew, and it cost real things: a machine-specific file
+  committed into every pack repo, a four-link config-precedence chain to document, and an
+  exclusion rule duplicated in the bundler and the server (which had already drifted apart).
+  `octwin init` and `octwin pull` no longer write one, and nothing reads one. **A pack directory is
+  now pack content and nothing else** — the same repo deploys from any machine, and a pulled pack
+  redeploys with no flags.
+
+### Changed
+- **`octwin login` now sets the default deploy target**, not just the token: it writes a
+  `default_url` key alongside the token in `~/.octwin/credentials.json`. Every command resolves
+  **flags → env (`PACK_PLATFORM_URL`/`PACK_TENANT`/`PACK_PROJECT`/`PACK_TOKEN`) → saved login**.
+  An existing credentials file simply has no `default_url` until the next `octwin login` — which is
+  exactly what the "no platform url" error now tells you to run. CI is unaffected (it passes
+  `PACK_PLATFORM_URL` + `PACK_TOKEN` as env and never had a `pack.json` — that file is retired).
+
+## [0.1.17] - 2026-07-27
+
+### Added
+- **`octwin pull <packId>` — write a DEPLOYED pack's source back to disk.** The inverse of
+  `deploy`. A pack pushed with the CLI lived on the platform as an artifact the runtime served
+  but nothing could hand back, so its only source copy was the machine that pushed it. Pull it,
+  fix it, redeploy it. Writes a `pack.json` (retired in 0.1.18 — the saved login is now the
+  target) so the pulled directory redeploys where it came from; `--version` picks a version,
+  `--force` overwrites a non-empty dir. You may pull a pack
+  your tenant OWNS (an operator token pulls any) — a pack you merely installed is not yours to
+  read.
+- **`octwin chat --script <file>` — drive a whole conversation from one invocation.** One turn per
+  line, in order, in a single process over a single SSE connection, waiting for each turn to settle
+  before sending the next. Blank lines and `#` comments are skipped; `tap:<id>` presses a rendered
+  row/button (the rest of the line is kept verbatim, since a tap id is itself colon-delimited),
+  `media:<path>` uploads a file, and `media:<path> | caption` attaches one.
+
+  This exists because **chaining invocations races the agent loop.** A turn ends on a quiet gap
+  (`TURN_SETTLE_MS`), which can arrive while the server-side loop is still running — so
+  `chat A && chat B` lets B's inbound land mid-turn, and the agent fills required fields with
+  placeholder text (`service_id: "service-id"`) or starts a second workflow run. Those look exactly
+  like flow bugs and cost a field author three separate investigations. The one-turn-per-invocation
+  rule is now stated in `chat --help` and the header usage as well.
+
+### Changed
+- **`octwin deploy` reports the suspended runs it invalidated.** A redeploy rebuilds the pack's
+  tools, and in-flight flow runs live in those tools — so every suspended conversation is dropped.
+  The deploy prints `ⓘ N suspended run(s) invalidated` when N > 0, instead of leaving the author to
+  discover it as a `workflow_resume_stale` on the next tap.
+
+## [0.1.16] - 2026-07-26
+
+### Added
+- **A pack can ship committed images.** `jpg`/`jpeg`/`png`/`webp`/`gif`/`pdf` files in your pack
+  directory now travel as a separate `blobs` half of the bundle (base64 on the wire, `bytea` in
+  storage) instead of being rejected as "not an allowed pack file type". Declare each one under the
+  manifest's `static_assets: [{ file, key }]` and reference it from `config:` with the
+  `$pack_asset:<key>` sentinel — the platform uploads it to the media system at install and the
+  sentinel resolves to the served URL. `octwin validate` reports the image count alongside the file
+  count.
+- **The size ceilings fail locally, before upload** — 2 MB per file, 32 MB of binary per pack,
+  mirroring the server. `svg` stays rejected: it is script-capable and these assets are served to
+  browsers.
+
+### Fixed
+- **Committed images were silently corrupted.** `collectBundleFiles` read *every* file with
+  `readFileSync(full, 'utf8')`, so a JPEG went through a lossy UTF-8 decode and arrived mangled
+  server-side — a deploy that "succeeded" and rendered a broken image. Binary files now split off
+  into `blobs` and keep their bytes.
+- **`octwin status` reported `loaded=(none)` for every pack, always.** It printed a `loaded_version`
+  field that stopped existing when reload moved to content-sha keying, which also meant the
+  version-drift warning underneath it could never fire. It now prints the **content sha** the
+  instance has loaded and the one the catalog holds (with the artifact's `origin`), and warns off the
+  platform's own `up_to_date` flag. The sha is the more useful fact anyway: re-publishing the *same*
+  version changes it, which is exactly the author's inner loop. A pack that is live and current but
+  **withdrawn** from the catalog now says so, rather than reporting a clean bill of health.
+
+## [0.1.15] - 2026-07-25
+
+### Added
+- **`octwin agents [packId::agentId] [--prompt]` — see what your agent actually runs as.** The platform
+  gained *governed* agent settings: an operator platform default can override the `default_model`
+  (and history window / working-memory toggle) your manifest declares, and that override is invisible
+  from the pack source. The command prints each governed setting's **effective** value, **which layer
+  won** (project override → platform default → pack manifest), and warns explicitly when your pack's
+  declared value is *not* in force. `--prompt` prints the exact system prompt the LLM sees for this
+  project (pack instructions + platform protocol + any project overlay).
+- **`octwin orders [reference_id]` — the commerce a conversation produced.** The list (number,
+  status/payment, total, contact) or one order with its line items, the
+  subtotal/tax/shipping/discount/total breakdown, `payment_ref`, and the allowed transitions. On a
+  `pending`/`none` payment it explains *why that's expected*: the forward payment lifecycle is
+  **webhook-owned** (not patchable), and the default gateway-less `manual` driver makes
+  `payment_request` take its `empty` port — so the flow should confirm pay-on-delivery, not error.
+- **`octwin analytics [entity]` — stage conversion for any pipelined entity.** The funnel engine that
+  powered journeys is now generic, so any entity declared with a `pipeline:` charts conversion +
+  drop-off (`--overview` / `--milestones` / `--trends` / `--cost`, and `--stage <id>` for the records
+  currently at a stage). An empty result names **both** causes the platform folds into one response —
+  no `pipeline:`, or no `view` grant on `record.<entity>`.
+- **`octwin catalog [--readiness]`** — commerce products with price, availability and stock
+  (`untracked` when the SKU isn't inventory-tracked), plus the WhatsApp catalog binding.
+  `--readiness` runs the Meta Graph checklist with each failing item's suggested fix.
+- **`octwin scheduling [--slots <resourceRecordId>]`** — the engine state (bookable resource types,
+  upcoming slots, booked seats) or the computed slots for one resource. This is how you verify the
+  availability rules a `deploy --seed` created, which 0.1.14 could create but not read back.
+
+### Changed
+- **Auth failures now name the scope the command needs.** Every 401/403 appends the required scope
+  (and the plan feature, where the route is entitlement-gated) from one client-side mirror of the
+  platform's scope registry — replacing the per-command hardcoded strings, several of which named no
+  scope at all. It also spells out that `pack:deploy` / `media:generate` are direct-grant only, so a
+  `tenant:admin` preset token does **not** confer them (the most common "but my token is admin" dead end).
+
+## [0.1.14] - 2026-07-23
+
+### Fixed
+- **A failed demo seed no longer reports a clean `✓`.** `deploy` softens non-fatal
+  install steps (e.g. a demo-seed row) to warning frames, but the summary still printed
+  `✓ Deployed` and exited 0 — so a deploy that seeded ZERO records read as success (the
+  false-✓ trap). `deploy` now collects those step errors, prints `⚠ Deployed with N
+  warning(s) — data may be incomplete` with each message, and exits non-zero so CI /
+  a `deploy && chat` chain catches it.
+
+### Added
+- **`login` echoes what the token reaches.** After saving, `octwin login` calls
+  `/api/self/t/whoami` and prints the workspace, project pin, and scopes — so a fresh
+  token self-identifies without a second `octwin whoami` (best-effort; a network failure
+  never fails the save).
+- **`validate --remote` surfaces warnings + the data-store trap.** The remote validate now
+  renders advisory `⚠` warnings (which don't block deploy) and, for a pack declaring
+  `required_adapters: [data-store]`, reports the missing-data-store error the deploy would
+  have 409'd on — plus a warning that an `xrm.yaml` pack usually shouldn't declare that
+  adapter at all. It also now catches (offline) a list-form `entities:` block and a
+  `localized: true` field seeded with a bare string — traps that previously surfaced only
+  mid-seed at deploy.
+
+## [0.1.13] - 2026-07-22
+
+### Added
+- **A headless media loop — produce + send.** Two paired additions close the coverage hole where any
+  media-collect flow (e.g. `activate-app`'s registration / ID uploads) stalled at the upload prompt
+  because the CLI could neither *make* nor *send* an image:
+  - `octwin media generate "<prompt>" [--out <file.png>] [--size 1024x1024] [--json]` — AI-generates an
+    image on the platform (needs a `media:generate`-scoped token), stores it as a public asset, and prints
+    its `MEDIA-` handle + serve URL. `--out` downloads the bytes to a file (WhatsApp renders only
+    `.png`/`.jpg`); `--json` emits `{ media_id, url, mime, width, height, bytes }`.
+  - `octwin chat --media <file|media-id>` — uploads a local file (or a media id from
+    `media generate --json`) as an image/document/audio inbound; any accompanying `"message"` rides as
+    its caption. The platform's media pipeline folds the upload into a running collect, so media flows
+    are now fully drivable headlessly.
+
+### Changed
+- **The KB-drift nudge now names what changed.** With the platform serving per-entry content hashes, the
+  post-command nudge appends a `(N changed · M added · K removed)` summary instead of a bare hash pair.
+- **`octwin platform-kb` prints a changelog on pull.** Instead of only a doc/catalog count, the pull now
+  diffs the fresh index against your last pull and lists exactly which docs/catalogs were added (`+`),
+  changed (`~`), or removed (`-`) — so a replaced schema shape is visible, not silent.
+
+## [0.1.12] - 2026-07-22
+
+### Fixed
+- **The KB-drift nudge now fires after `chat` too.** `chat` — the command a debugging session runs most —
+  was missing from the networked-command list, so a chat-heavy session never noticed the platform's
+  capability reference had moved. The nudge also now shows the concrete drift
+  (`old-hash → new-hash`) so you can see it's real, not a heuristic.
+
+### Changed
+- **Every networked command announces what it's doing before it does it.** `chat` prints
+  `→ Connecting to <tenant>/<project> as '<handle>' …` before opening the stream and
+  `… delivered — waiting for the reply (up to Ns)` after the send; `status` / `whoami` /
+  `platform-kb` / `records` / `logs` / `cases` each print a one-line `→ …` header naming the
+  action and target before the first network call — no more silent seconds followed by a result
+  (or a hang with no clue what was being attempted). JSON modes (`--json`) stay clean for piping.
+
+## [0.1.11] - 2026-07-21
+
+### Fixed
+- **Auth-failure hint on every command, not just the inspect family** (author-feedback A7). `validate`,
+  `deploy`, `status`, and the single-record read now print the scope/transient explanation on a 401/403
+  (the shared `authFailureHint`), instead of a bare `HTTP 401` that left it ambiguous whether the token
+  lacked a scope or the platform hiccupped.
+
+## [0.1.10] - 2026-07-21
+
+The capability reference is now **pulled, never bundled** — the authoring skill dropped its committed KB
+snapshot, so `octwin platform-kb pull` is the single source of truth, and the CLI watches it for drift.
+
+### Added
+- **KB-drift nudge** — after any command that already talks to the platform (`deploy` / `status` /
+  `test` / `validate --remote` / `records` / `cases` / `logs` / `whoami`), the CLI does one tiny
+  `octwin-platform-kb?meta=1` GET and prints a one-line "the platform capability reference changed —
+  `octwin platform-kb pull`" when the platform's `content_hash` no longer matches your last pull.
+  Fail-silent + TTY-only + no-op until you've pulled once — the sibling of the existing CLI-upgrade notice.
+
+### Changed
+- **`octwin platform-kb pull`** now records the reference's `content_hash` in `.octwin/platform-kb/index.json`
+  (the fingerprint the drift check compares against).
+
+The conversation-debugging release — driven by the second author-feedback round (xpeng-egypt),
+which found the author→validate→deploy loop solid but multi-turn debugging impossible from the CLI.
+
+### Added
+- **`octwin chat --tap "<tap-id>"`** — press a rendered button / list row (sends the web channel's
+  `type:'interactive'` inbound). Paired with full render printing, any tap-driven flow is now drivable headlessly.
+- **Full render printing** — every reply prints its complete interactive content: list sections/rows,
+  buttons, and carousel cards, each with its **tap id**; header/footer/list-button text included.
+- **`--json` on `chat` / `logs` / `cases`** — raw SSE envelopes (chat) or raw event/case payloads.
+- **`octwin cases [caseId] [--queues]`** — inspect casework (support tickets): the inbox, one case +
+  timeline + applicable decisions, or queue keys with open counts. Casework packs previously had zero
+  data-inspection path (`records case` was a dead end).
+- **Per-subcommand `--help`/`-h`** — intercepted before any network or auth work (previously
+  `octwin logs --help` made a network call and could die with a 401).
+- Multi-message turns: `chat` now collects **all** of a turn's renders (quiet-gap detection) instead
+  of cutting at the first one.
+
+### Changed
+- **`octwin logs`**: the conversation list shows contact handle + last activity and filters with
+  `--as <handle>`; the timeline prints **full** event text (no more 240-char truncation) plus the
+  renders each turn actually sent; footer points at `--json` / `mastra-messages` for verbatim payloads.
+- **Network failures name the target URL** (`platform unreachable at <url>`), and 401s explain
+  invalid-token vs one-off transient instead of a bare status code.
+- `octwin records` on an unknown entity now surfaces the server's error body, and for `case`/`cases`
+  points at `octwin cases`.
+
+### Fixed
+- **Multi-turn chat actually works.** Two bugs made consecutive `octwin chat` calls look like "every
+  call starts fresh": (1) the idempotency `local_id` was a **constant** per handle, so the platform's
+  5-minute inbound dedup silently dropped the second message — a fresh id is now minted per call;
+  (2) a fresh SSE connect **replays** recent history and the CLI printed the first render frame — i.e.
+  the *previous* turn's greeting — as the reply; the CLI now drains the replay and only accepts frames
+  newer than the connect boundary. The platform always kept one open conversation per `--as` handle —
+  the same handle genuinely continues the same conversation now.
+
+## [0.1.8] - 2026-07-21
+- Global-first install guidance (`npm i -g octwin-cli`); upgrade notice suppressed under `npx`.
+
+## [0.1.7] - 2026-07-21
+- `--version`/`-v` flag; daily fail-silent, TTY-only "newer version available" notice.
+
+## [0.1.6] - 2026-07-21
+- `octwin init` scaffolds a home-hub menu (`home` list_picker + example `browse` tool) instead of a bare greeting.
+
+## [0.1.5] - 2026-07-20
+- `octwin validate --remote` (the platform's FULL manifest + flow-DSL check, all errors at once);
+  headless debugging commands `octwin records` / `octwin logs` / `octwin chat`; `octwin test` became
+  an alias for `validate --remote`. First author-feedback round.
+
+## [0.1.4] - 2026-07-20
+- Authoring reliability + DX fixes from the first end-to-end external-pack test.
+
+## [0.1.3] - 2026-07-20
+- `octwin platform-kb pull` — pull the platform capability reference for the authoring skill.
+
+## [0.1.2] - 2026-07-20
+- Proper npm README.
+
+## [0.1.1] - 2026-07-20
+- Initial npm publish: `init` / `validate` / `login` / `whoami` / `deploy` / `status`, `oct_` deploy tokens.