octwin-cli 0.8.11 → 0.8.13

package/CHANGELOG.md

@@ -5,6 +5,66 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [Unreleased]
+
+## [0.8.13] - 2026-09-27
+
+### Added
+- **`octwin records archive <id>` / `restore <id>`.** Archive is how a record leaves use — test data
+  included: it drops out of every list, count and report and fires the entity's `on.archived`
+  reactions, exactly like the console's Archive; `restore` undoes it. There is no delete, on the
+  platform or here, and `octwin records --help` now says so.
+
+### Fixed
+- **`octwin chat` said the AI Agent wrote every message.** A reminder that fired mid `--script` (a
+  `schedule_notify`, a reaction) printed as `← <body>`, was taken for the turn's reply, and ended
+  the turn on it — so the real reply looked lost while `octwin logs` showed the flow had worked.
+  Each line now says who sent it: `← [notify] …` (not the turn's answer — the wait for the real
+  reply goes on), `← [operator: Name] …` (a person in Live chat), `← [platform] …` (a handoff
+  joining or returning); plain `← …` is the AI Agent. After the last turn the stream stays open
+  3 s more, so a late message prints (marked "after the last turn") instead of reaching a closed
+  connection. Needs a platform that stamps `source: 'notify'` on web renders; an older one just
+  prints notifies unlabelled, as before.
+- **The "no such template" hint named a file the platform never loads.** It said
+  `templates/<name>.yaml`; pack templates load only as `templates/<name>.template.yaml`, so a
+  template saved as the hint said was silently ignored.
+
+### Changed
+- **`octwin validate` runs the platform's FULL check by default — and needs no login for it.** The
+  offline checks are a subset, and a subset that passes read as "deploy will pass": it passed a pack
+  the full check refused (a scaffold flow left behind with Arabic copy only, in a pack that ships
+  English). Now `validate` runs the offline checks, then the full one: through your workspace when you
+  have a token AND a `--project` (which also confirms the project exists), otherwise through the
+  platform's public validate route with no credential. When it cannot reach the full check — no url,
+  offline, rate-limited, an older platform — the LAST line says *"only the OFFLINE check ran — a
+  PARTIAL check"* and why, and it exits 0 as before. `--remote` now means "the full check is
+  required" (not reaching it is an error); the new `--offline` runs only the subset.
+- **The scaffold's example `browse` flow says it is an example.** Its header, its copy file and its
+  `manifest.yaml` line now say to replace it, or delete the flow, every `browse.locale.*.yaml` and the
+  `flows:` line together — a leftover never loads, but a second language makes it fail validation.
+
+## [0.8.12] - 2026-09-25
+
+### Changed
+- **The package pointed its `homepage` at npm — the page it is rendered on.** It is
+  <https://octwin.ai> now, and the README's Links section gains the platform, the guides and the
+  marketplace. The README describes Octwin at length and linked only to npm and nodejs.org.
+- **`octwin usage` with a project-pinned token reports that project.** The platform now treats a
+  token's project pin as a ceiling on every route, so a pinned token is refused on the
+  workspace-wide rollup. `usage` asks `whoami` for the pin and reads the project view instead of
+  printing a 403 — which is what its help text (`project if pinned, else workspace`) always said.
+
+### Fixed
+- **`octwin chat` sat out its whole 45-second wait on every message during a live handoff, and
+  read as hung.** While a person holds the conversation (or one has been asked for) the AI Agent
+  deliberately answers nothing, and the CLI could not tell that from a slow pack. The platform now
+  says so with a `held` event on the web stream; `chat` prints
+  *"⏸ a person is holding this conversation — the AI Agent will not reply…"* (or *"waiting for a
+  person to join…"*), still collects any operator line replayed by that message, and returns. A
+  held turn is not a failure: it exits 0, and `--script` carries on to the next line, so the
+  customer's side of a handoff can be scripted. Needs a platform that sends `held`; an older one
+  behaves as before. Reported in `xpeng-egypt/FEEDBACK.md`, session 3.
+
 ## [0.8.11] - 2026-09-07
 
 ### Fixed

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/npm/l/octwin-cli.svg)](https://www.npmjs.com/package/octwin-cli)
 [![node](https://img.shields.io/node/v/octwin-cli.svg)](https://nodejs.org)
 
-Octwin is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
+[Octwin](https://octwin.ai) is a pack-pluggable conversational-agent platform for WhatsApp and web. A **pack** is a
 self-contained bot domain — its agent, conversation flows, prompts, and data model — declared
 entirely in YAML. `octwin-cli` lets you build a **pure-YAML pack** in your own repo and deploy it
 to a running Octwin platform to test live on your own tenant: no platform checkout, no build step,
@@ -65,15 +65,15 @@ octwin status               # "✓ live and current" once it's warm
 | Command | What it does |
 | --- | --- |
 | `octwin init <dir>` | Scaffold a new pure-YAML pack into `<dir>` (writes a starter `manifest.yaml`, flow, prompt, `.gitignore` and `README.md` — pack content only). Options: `--id`, `--description`, `--display-name`. |
-| `octwin validate` | Check the pack locally (structure + pure-YAML rules). `--remote` runs **the same validation the platform runs to load your pack** — every declaration file (`xrm.yaml`, `scheduling.yaml`, `worklist.yaml`, `roles.yaml`, `automation.yaml`, `integrations.yaml`, `surveys.yaml`, `taps.yaml`, `commands.yaml`, `journeys/`, `messages.<lang>.yaml`), the cross-file checks between them, and the **flow lint** — conventions the schema can't express, like an `assign:` whose value is a quoted literal or a `$t()` key with no namespace. These need template expansion and the platform's own schemas, which only the server has, so a local ✓ does not cover them. A `--remote` ✓ and a successful deploy are now the same answer by construction, not by convention. |
+| `octwin validate` | Fast offline checks (structure + pure-YAML rules + the checks the pulled KB drives), then — **by default, with no login needed** — **the same validation the platform runs to load your pack**. Without a token and a `--project` it asks the platform's public validate route; with both it goes through your workspace and also confirms the project exists. When it cannot reach the platform, the LAST line says *"only the OFFLINE check ran — a PARTIAL check"* and why. `--remote` makes the full check required (not reaching it is an error); `--offline` runs only the subset. The full check covers every declaration file (`xrm.yaml`, `scheduling.yaml`, `worklist.yaml`, `roles.yaml`, `automation.yaml`, `integrations.yaml`, `surveys.yaml`, `taps.yaml`, `commands.yaml`, `journeys/`, `messages.<lang>.yaml`), the cross-file checks between them, and the **flow lint** — conventions the schema can't express, like an `assign:` whose value is a quoted literal or a `$t()` key with no namespace. These need template expansion and the platform's own schemas, which only the server has, so an offline ✓ does not cover them. A full-check ✓ and a successful deploy are the same answer by construction, not by convention. |
 | `octwin login` | Sign in to a platform URL **and make it the default target** (both stored in `~/.octwin/credentials.json`). With no `--token` it prints a link to approve in the console, then collects a 30-day token itself — nothing is pasted. The wait is bounded and resumable: run it again to keep waiting on the same request. `--url`, `--token`, `--wait <seconds>`, `--json`. |
 | `octwin whoami` | Verify the saved/passed token is valid for a tenant. `--url`, `--tenant`. |
 | `octwin deploy` | Upload + install the pack onto your tenant's project. `--seed` also runs the pack's demo seed. Says **nothing** about the public marketplace unless asked: `--request-listing` submits the pack for operator review (needs `listing.public: true` in the manifest too), `--withdraw-listing` retracts. Reports the **listing verdict** whenever one exists. |
 | `octwin status` | Report what the platform has live for this pack — installed version, the **content sha** the instance loaded vs. the one the catalog holds (a redeploy of the *same* version changes it), its flows, and whether it is live on the public marketplace. |
 | `octwin pull <packId>` | Write a **deployed** pack's source back to disk — the inverse of `deploy`, and how a pack pushed from one machine is recovered. Defaults to the version installed on the target project; `--version` overrides, `--dir` defaults to `./<packId>`, a non-empty dir needs `--force`. You may pull a pack your tenant **owns**. |
-| `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. |
+| `octwin chat "msg"` | Drive a turn through the dev web channel and print **every render with its tap ids**. `--as <handle>` picks the test user; `--tap "<tap-id>"` presses a rendered button/list row; `--json` dumps the raw envelopes. Each reply line says who sent it: plain `← …` is the AI Agent, `← [notify] …` a reminder or notification (never taken for the turn's reply), `← [operator: Name] …` a person in Live chat, `← [platform] …` a handoff line. |
 | `octwin logs` | List recent conversations (handle, status, last activity; `--as` filters), or show one conversation's full event timeline — including what each turn rendered. `--json` for raw payloads. |
-| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. |
+| `octwin records` | Inspect the pack's XRM data (needs a `records:read` token). No args = list entities. Writes (`records:write`): `create`, `patch`, `stage`, `note`, and `archive <id>` / `restore <id>` — there is no delete; archive takes a record (test data too) out of every list and count, and restore brings it back. |
 | `octwin work` | The work inbox: worked records across queues, one item + its timeline and decisions, or `--queues` for queue keys + open counts. Casework is one shape of it — the command spans every entity a pack works. |
 | `octwin projects` | The `--project <slug>` values this token can name, with the plan's project cap. `--archived` includes archived ones. A `pack:deploy` token reaches it — it names a project in every other command, so this turns "guess the slug" into "read the list". |
 | `octwin agents` | The agent roster with each agent's **effective** model / history window and **which layer set it** (project override → platform default → pack manifest) — an operator platform default can override what your manifest declares. `--prompt` prints the exact system prompt the LLM sees. Needs `agents:read`. |
@@ -88,7 +88,7 @@ octwin status               # "✓ live and current" once it's warm
 | `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 no API token can read it. |
 | `octwin media generate "<prompt>"` | AI-generate an image, store it as a public asset, and print its `MEDIA-` handle + serve URL. `--out` downloads the bytes (WhatsApp renders only `.png`/`.jpg`); `--json`. Pairs with `octwin chat --media` to drive media-collect flows. Needs `media:generate`. |
 | `octwin platform-kb pull` | Pull the platform's capability reference into `.octwin/platform-kb/` for the **`octwin-pack`** Claude Code authoring plugin: guides as markdown, plus **one JSON file per capability** (`primitives/record_list.json`, `render-intents/carousel.json`, `declarations/xrm.json`, …) and **three maps** — `INDEX.md` (the corpus, by family and size), `SYMBOLS.md` (every name → its exact file; grep this), `OUTLINE.md` (every heading with its line number). **No token needed** — the reference is served anonymously. `--if-stale` skips the download when your copy is current (cheap enough for every session); `--check` writes nothing and exits 0 current / 2 stale / 1 could-not-tell. |
-| `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
+| `octwin test` | Alias for `octwin validate --remote` — the platform's full check, required (a skipped full check is an error). |
 | `octwin feedback` | Submit this pack's `FEEDBACK.md` to the platform team, with the pack version, your CLI 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. |
 | `octwin help` | Show usage. Every subcommand also answers `--help`. |
 
@@ -238,6 +238,9 @@ declaration files — read its `INDEX.md` rather than this paragraph.)
 
 ## Links
 
+- **Octwin:** <https://octwin.ai> — the platform this CLI deploys to
+- **Guides & playbooks:** <https://octwin.ai/artifacts> — how each capability works, end to end
+- **Marketplace:** <https://octwin.ai/packs> — published packs you can read before writing your own
 - **npm:** <https://www.npmjs.com/package/octwin-cli>
 - **Command help:** `octwin help` (each subcommand also answers `--help`)
 - **Changelog:** [CHANGELOG.md](./CHANGELOG.md)