octwin-cli 0.8.0 → 0.8.3

package/CHANGELOG.md

@@ -1,660 +1,720 @@
-# 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.
-
-## [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.
+
+## [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.