octwin-cli 0.1.21 → 0.5.1

package/README.md

@@ -61,7 +61,7 @@ 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). The platform re-validates the full manifest/flow schema on deploy. |
+| `octwin validate` | Check the pack locally (structure + pure-YAML rules). `--remote` additionally runs the platform's **flow lint** — conventions the schema can't express, like an `assign:` whose value is a quoted literal, or a `$t()` key with no namespace. The lint needs a template-expanded `FlowDef`, which only the server builds, so it is a `--remote`-only check; a local ✓ does not cover it. |
 | `octwin login` | Save a deploy token for a platform URL **and make that URL the default target** (both stored in `~/.octwin/credentials.json`). `--url`, `--token`. |
 | `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. Reports the **marketplace-listing verdict** when the manifest carries `listing.public: true`. |
@@ -71,6 +71,7 @@ octwin status               # "✓ live and current" once it's warm
 | `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 cases` | Inspect casework (support tickets): the inbox, one case + its timeline and decisions, or `--queues` for queue keys + open counts. |
+| `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`. |
 | `octwin orders` | The orders a conversation produced. No args = the list; with a `reference_id` = line items, the subtotal/tax/shipping/discount/total breakdown, `payment_ref`, and the allowed transitions. Needs `orders:read` + the `orders` plan feature. |
 | `octwin analytics` | Stage-by-stage conversion for **any** entity declared with a `pipeline:` (`--overview` / `--milestones` / `--trends` / `--cost`; `--stage <id>` lists the records currently at a stage). Needs `records:read`. |
@@ -79,8 +80,29 @@ octwin status               # "✓ live and current" once it's warm
 | `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`); `--size`; `--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 an **`INDEX.md`** mapping every entry to its file — so a lookup is a small targeted read, not a whole catalog. |
 | `octwin test` | Alias for `octwin validate --remote` — the platform's full manifest + flow-DSL check. |
+| `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`. |
 
+### Writing, not just reading
+
+Every read command above has a write half behind a **leading verb**, so `octwin cases` reads and
+`octwin cases note <id> "…"` writes. Each needs the matching `:write` scope — `octwin <cmd> --help`
+lists the verbs and their exact flags.
+
+| Command | Verbs |
+| --- | --- |
+| `octwin records` | `create <entity> --set k=v` · `patch <id> --entity <e>` · `stage <id> --to <s>` · `note <id> "…"` · `tasks` · `task complete <id>` |
+| `octwin cases` | `assign <id> --to user:<uuid>\|none` · `note` · `transition <id> --to <status>` · `decide <id> --action <a> [--dry-run]` |
+| `octwin orders` | `transition <ref> --to <status>` · `refund <ref> --force` |
+| `octwin catalog` | `availability <sku> --to "in stock"` · `stock <sku> [--set-on-hand n]` |
+| `octwin scheduling` | `rules --resource <id>` · `rule add\|rm` · `exception add\|rm` |
+| `octwin agents` | `set <ref> [--model m] [--enable-tool t] [--disable-tool t]` |
+
+`--set k=v` coerces JSON scalars (`--set rating=4.5` sends a number); `--fields-json` takes anything
+nested. Destructive verbs want `--force` rather than a prompt — the CLI is non-interactive by
+design. `cases decide --dry-run` previews the customer-facing copy and the resulting status without
+committing, and needs only `cases:read`.
+
 Every command that talks to the platform accepts `--dir <path>` (the pack directory; defaults to
 the current directory) plus the target overrides `--url` / `--tenant` / `--project` / `--token`.
 
@@ -168,9 +190,10 @@ text only.
 
 ## What a pack may contain
 
-A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.sql` / `.json` only. Executable
-code (`.ts`/`.js`), HTTP routes, DB clients, and custom primitives are **not** allowed (this is what
-makes an external pack safe to run on a shared platform; the server enforces it on deploy). For
+A pack is **pure declarative data** — `.yaml` / `.yml` / `.md` / `.json` only. Executable
+code (`.ts`/`.js`), HTTP routes, DB clients, custom primitives and **`.sql`** are **not** allowed
+(this is what makes an external pack safe to run on a shared platform; the server enforces it on
+deploy, and so does `octwin validate`). For
 domain records, use Octwin's first-class storage modules — **XRM** (records with stage pipelines),
 **catalog** (products), or **casework** (tickets) — declared in `xrm.yaml` and `worklist.yaml`, so a
 pack needs **no database of its own**. (Casework rides `worklist.yaml`'s `work.<entity>` block;