cinna-cli 0.2.5__tar.gz → 0.3.0__tar.gz

{cinna_cli-0.2.5 → cinna_cli-0.3.0}/.gitignore

@@ -8,4 +8,5 @@ __pycache__/
 dist/
 build/
 cinna.log
+cinna.log.*
 .claude/settings.local.json

{cinna_cli-0.2.5 → cinna_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.2.5
+Version: 0.3.0
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli
@@ -167,6 +167,8 @@ List the agents your account can access (run from inside the account workspace).
 
 One-shot summary of the account workspace: platform/frontend URLs, machine name, synced-agent count, and an account-token probe (`valid token` / `expired token` / `no connection`) — the account-level counterpart of `cinna status`.
 
+Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there.
+
 ### `cinna account refresh-context`
 
 Re-download the context package and replace the account workspace's `context/` tree (run from inside the account workspace). Use it when the platform ships updated docs or API reference. The existing tree is only removed after a successful download — a failed refresh warns and leaves the previous `context/` intact.
@@ -200,6 +202,39 @@ cinna account credentials delete <cred_id> --yes
 
 A new draft lands in the account's [active user workspace](#cinna-account-user-workspace-list--activate-nameid--clear). Deletes reuse the platform's blast-radius gate (a publisher-provided credential in a published bundle with active installs needs `--force`). All write verbs require the `agent-developer` role.
 
+### `cinna improve list | show | download | status`
+
+Work the **improvement requests** users shared with you about your agents. When someone chatting with an agent hits a bad answer, they can hand the agent's owner a frozen snapshot of that one session — the transcript plus the runtime context that produced it (bundle id + installed version, environment, SDK engine, effective model) — from the session menu or with the `/session-improve` command. These verbs are the receiving half of that loop, and they run from an account workspace so one listing spans every agent you own.
+
+```bash
+cinna improve list --status new                    # unhandled first, then newest
+cinna improve list --agent crm-agent               # narrow to one agent
+cinna improve show 3f2504e0                        # the report + the runtime context block
+cinna improve download 3f2504e0                    # → improvements/3f2504e0/
+cinna improve status 3f2504e0 in_progress          # claim it
+cinna improve status 3f2504e0 completed --note "Fixed in v1.6 — no longer re-asks for the file."
+```
+
+`<id>` is the short id printed by `cinna improve list` (or the full UUID). `download` saves and extracts the archive into `improvements/<short-id>/` under the account root (`--out DIR` to choose another target), using the same safe extractor as the workspace clone:
+
+```
+improvements/3f2504e0/
+├── README.md          # what was reported, by whom, which agent + bundle version, runtime table
+├── metadata.json      # the request row
+├── context.json       # structured runtime context of the install that misbehaved
+├── prompts/           # the install's live prompt docs (WORKFLOW_PROMPT.md, …) + a divergence README
+├── memory/            # the agent's captured personal memory, when it had any
+└── session/
+    ├── messages.md    # human-readable transcript
+    └── messages.json  # the same transcript, structured
+```
+
+`cinna improve show` renders the prompt block as a per-prompt **in sync / diverged** table against the installed bundle revision — the one thing a publisher cannot see from their own copy, since a consumer who owns their install can edit its prompts. A diverged prompt means the session was produced by text that is not yours; read `prompts/` in the archive before assuming otherwise.
+
+The archive deliberately contains **no** container logs, **no** uploaded file contents (descriptors only), and no credential values (snapshot text is scrubbed server-side before it is stored). Statuses are `new` → `in_progress` → `completed` | `declined`; the `--note` on a closing transition is **shown to the requester**. `--json` on `list` / `show` prints the raw payload for scripting.
+
+The archive is another person's conversation: don't copy it into an agent workspace, don't commit it, and delete the local copy when you're done. The end-to-end playbook a local coding agent should follow — including where a fix has to land for a bundle publisher install versus a standalone agent — ships in the account workspace's context package at `context/guides/handling-improvement-requests.md`.
+
 ### `cinna agent create <name> [--description TEXT]`
 
 Create a new agent on the platform from the account workspace — no UI interaction. Thin client: only the name (and optional description) is sent; the backend applies all defaults (default AI credentials, env template, environment creation) exactly as creating from the UI does. The agent is created in the account's [active user workspace](#cinna-account-user-workspace-list--activate-nameid--clear) (if one is set). Prints the created agent's ID and web UI link, plus a hint to attach a local workspace with `cinna agent sync <name>`. Requires the `agent-developer` role (403 otherwise). Template selection is not supported yet — agents always get the server default.
@@ -224,6 +259,25 @@ works exactly as for a manually set-up agent. Synced agents also appear in `cinn
 
 Detach a synced workspace: stop its sync session, revoke the minted CLI token server-side (via the account-scoped revoke endpoint, authenticated with the account token; idempotent), then perform the equivalent of `cinna disconnect`: remove `.cinna/`, generated files, and the registry entry. Workspace files under `agents/<slug>/workspace/` are preserved. The revoke degrades gracefully — if it fails (no connection, or a workspace synced before token-id tracking), a warning is printed and the local teardown still completes; the token then expires on its own or can be revoked from the agent's Integrations tab.
 
+### `cinna agent import <path> [--name TEXT] [--workspace REF] [--update] [--dry-run] [--no-push] [--yes]`
+
+Import an agent that was built **locally** with the [Local Agent Kit](docs/features/local_agent_import/local_agent_import.md) — a folder holding a `cinna-agent.json` manifest, typically `../Local/<slug>` next to this account workspace. Run it from the account workspace root (or any folder inside it).
+
+Nine idempotent steps, each printed as `[n/9]`: read and validate the manifest → create (or resolve) the cloud agent → write its description, router trigger, example prompts and the three document prompts in one bulk write, plus the status refresh command → attach a local workspace (`cinna agent sync`) → copy the tree into `agents/<slug>/workspace/` honouring the contract's exclude list and secret rules, generating `workspace_requirements.txt` from `pyproject.toml` when the agent doesn't ship one → `cinna sync push` → create the credential drafts and attach them → create the schedules → record the publication in `publications.json` and print the summary.
+
+```bash
+cinna agent import ../Local/invoice-watcher --dry-run   # see the plan, touch nothing
+cinna agent import ../Local/invoice-watcher --yes
+cinna chat --agent invoice-watcher "check invoices from last week"
+
+# after more local work:
+cinna agent import ../Local/invoice-watcher --update --yes
+```
+
+The folder rules come from the kit's versioned contract, `.cinna-kit/layout.json` — the same file Cinna Desktop reads — so a correction published there reaches this command on the next kit refresh rather than waiting for a new cinna-cli. `credentials/` and `app-data/` are **never** copied, not even if the contract drops them, and on top of the exclude list the contract's `secret_files` rules withhold every dotenv shape (`.env`, `.env.prod`, `staging.env`) wherever it sits, while `.env.example` still travels. No secret value is ever read, sent, or printed: credentials are created as empty drafts and the command prints the URLs the user opens to fill them in the browser.
+
+Where the folder has been published is recorded in `publications.json`, a **sibling** of `cinna-agent.json` holding one entry per Cinna instance — it cannot live inside the manifest, because each entry records a hash of the exported tree and the manifest is part of that tree. Every step is idempotent (agent by the entry whose `platform_url` matches the instance you are logged into, credentials by name, schedules by name), so a partial import is resumed with `--update` instead of duplicating anything. The publication is recorded **only after the push settled** — `--no-push`, a failed flush, or remaining conflicts leave it unrecorded, and the next run is a plain `--update`. A legacy `cloud` block is migrated into the ledger on the first write and is still read until then, so an older folder's `--update` never creates a second agent. `--dry-run` makes no platform call and writes nothing.
+
 ### `cinna connect agent-api --producer <agent> --consumer <agent> [--label TEXT] [--read-only]`
 
 Wire one agent to another's REST API from the account workspace. Resolves both agents (name, slug, or ID), mints a producer API token, and attaches it to the consumer as a credential — which rides the consumer's normal credential sync into its remote environment, so no key ever touches your machine. Prints the credential ID, token prefix, base URL, and spec URL. `--read-only` restricts the consumer to read-only access; `--label` names the credential. Backend errors surface verbatim: 400 if the producer's REST API is disabled, 403/404 for ownership violations.

{cinna_cli-0.2.5 → cinna_cli-0.3.0}/README.md

@@ -130,6 +130,8 @@ List the agents your account can access (run from inside the account workspace).
 
 One-shot summary of the account workspace: platform/frontend URLs, machine name, synced-agent count, and an account-token probe (`valid token` / `expired token` / `no connection`) — the account-level counterpart of `cinna status`.
 
+Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there.
+
 ### `cinna account refresh-context`
 
 Re-download the context package and replace the account workspace's `context/` tree (run from inside the account workspace). Use it when the platform ships updated docs or API reference. The existing tree is only removed after a successful download — a failed refresh warns and leaves the previous `context/` intact.
@@ -163,6 +165,39 @@ cinna account credentials delete <cred_id> --yes
 
 A new draft lands in the account's [active user workspace](#cinna-account-user-workspace-list--activate-nameid--clear). Deletes reuse the platform's blast-radius gate (a publisher-provided credential in a published bundle with active installs needs `--force`). All write verbs require the `agent-developer` role.
 
+### `cinna improve list | show | download | status`
+
+Work the **improvement requests** users shared with you about your agents. When someone chatting with an agent hits a bad answer, they can hand the agent's owner a frozen snapshot of that one session — the transcript plus the runtime context that produced it (bundle id + installed version, environment, SDK engine, effective model) — from the session menu or with the `/session-improve` command. These verbs are the receiving half of that loop, and they run from an account workspace so one listing spans every agent you own.
+
+```bash
+cinna improve list --status new                    # unhandled first, then newest
+cinna improve list --agent crm-agent               # narrow to one agent
+cinna improve show 3f2504e0                        # the report + the runtime context block
+cinna improve download 3f2504e0                    # → improvements/3f2504e0/
+cinna improve status 3f2504e0 in_progress          # claim it
+cinna improve status 3f2504e0 completed --note "Fixed in v1.6 — no longer re-asks for the file."
+```
+
+`<id>` is the short id printed by `cinna improve list` (or the full UUID). `download` saves and extracts the archive into `improvements/<short-id>/` under the account root (`--out DIR` to choose another target), using the same safe extractor as the workspace clone:
+
+```
+improvements/3f2504e0/
+├── README.md          # what was reported, by whom, which agent + bundle version, runtime table
+├── metadata.json      # the request row
+├── context.json       # structured runtime context of the install that misbehaved
+├── prompts/           # the install's live prompt docs (WORKFLOW_PROMPT.md, …) + a divergence README
+├── memory/            # the agent's captured personal memory, when it had any
+└── session/
+    ├── messages.md    # human-readable transcript
+    └── messages.json  # the same transcript, structured
+```
+
+`cinna improve show` renders the prompt block as a per-prompt **in sync / diverged** table against the installed bundle revision — the one thing a publisher cannot see from their own copy, since a consumer who owns their install can edit its prompts. A diverged prompt means the session was produced by text that is not yours; read `prompts/` in the archive before assuming otherwise.
+
+The archive deliberately contains **no** container logs, **no** uploaded file contents (descriptors only), and no credential values (snapshot text is scrubbed server-side before it is stored). Statuses are `new` → `in_progress` → `completed` | `declined`; the `--note` on a closing transition is **shown to the requester**. `--json` on `list` / `show` prints the raw payload for scripting.
+
+The archive is another person's conversation: don't copy it into an agent workspace, don't commit it, and delete the local copy when you're done. The end-to-end playbook a local coding agent should follow — including where a fix has to land for a bundle publisher install versus a standalone agent — ships in the account workspace's context package at `context/guides/handling-improvement-requests.md`.
+
 ### `cinna agent create <name> [--description TEXT]`
 
 Create a new agent on the platform from the account workspace — no UI interaction. Thin client: only the name (and optional description) is sent; the backend applies all defaults (default AI credentials, env template, environment creation) exactly as creating from the UI does. The agent is created in the account's [active user workspace](#cinna-account-user-workspace-list--activate-nameid--clear) (if one is set). Prints the created agent's ID and web UI link, plus a hint to attach a local workspace with `cinna agent sync <name>`. Requires the `agent-developer` role (403 otherwise). Template selection is not supported yet — agents always get the server default.
@@ -187,6 +222,25 @@ works exactly as for a manually set-up agent. Synced agents also appear in `cinn
 
 Detach a synced workspace: stop its sync session, revoke the minted CLI token server-side (via the account-scoped revoke endpoint, authenticated with the account token; idempotent), then perform the equivalent of `cinna disconnect`: remove `.cinna/`, generated files, and the registry entry. Workspace files under `agents/<slug>/workspace/` are preserved. The revoke degrades gracefully — if it fails (no connection, or a workspace synced before token-id tracking), a warning is printed and the local teardown still completes; the token then expires on its own or can be revoked from the agent's Integrations tab.
 
+### `cinna agent import <path> [--name TEXT] [--workspace REF] [--update] [--dry-run] [--no-push] [--yes]`
+
+Import an agent that was built **locally** with the [Local Agent Kit](docs/features/local_agent_import/local_agent_import.md) — a folder holding a `cinna-agent.json` manifest, typically `../Local/<slug>` next to this account workspace. Run it from the account workspace root (or any folder inside it).
+
+Nine idempotent steps, each printed as `[n/9]`: read and validate the manifest → create (or resolve) the cloud agent → write its description, router trigger, example prompts and the three document prompts in one bulk write, plus the status refresh command → attach a local workspace (`cinna agent sync`) → copy the tree into `agents/<slug>/workspace/` honouring the contract's exclude list and secret rules, generating `workspace_requirements.txt` from `pyproject.toml` when the agent doesn't ship one → `cinna sync push` → create the credential drafts and attach them → create the schedules → record the publication in `publications.json` and print the summary.
+
+```bash
+cinna agent import ../Local/invoice-watcher --dry-run   # see the plan, touch nothing
+cinna agent import ../Local/invoice-watcher --yes
+cinna chat --agent invoice-watcher "check invoices from last week"
+
+# after more local work:
+cinna agent import ../Local/invoice-watcher --update --yes
+```
+
+The folder rules come from the kit's versioned contract, `.cinna-kit/layout.json` — the same file Cinna Desktop reads — so a correction published there reaches this command on the next kit refresh rather than waiting for a new cinna-cli. `credentials/` and `app-data/` are **never** copied, not even if the contract drops them, and on top of the exclude list the contract's `secret_files` rules withhold every dotenv shape (`.env`, `.env.prod`, `staging.env`) wherever it sits, while `.env.example` still travels. No secret value is ever read, sent, or printed: credentials are created as empty drafts and the command prints the URLs the user opens to fill them in the browser.
+
+Where the folder has been published is recorded in `publications.json`, a **sibling** of `cinna-agent.json` holding one entry per Cinna instance — it cannot live inside the manifest, because each entry records a hash of the exported tree and the manifest is part of that tree. Every step is idempotent (agent by the entry whose `platform_url` matches the instance you are logged into, credentials by name, schedules by name), so a partial import is resumed with `--update` instead of duplicating anything. The publication is recorded **only after the push settled** — `--no-push`, a failed flush, or remaining conflicts leave it unrecorded, and the next run is a plain `--update`. A legacy `cloud` block is migrated into the ledger on the first write and is still read until then, so an older folder's `--update` never creates a second agent. `--dry-run` makes no platform call and writes nothing.
+
 ### `cinna connect agent-api --producer <agent> --consumer <agent> [--label TEXT] [--read-only]`
 
 Wire one agent to another's REST API from the account workspace. Resolves both agents (name, slug, or ID), mints a producer API token, and attaches it to the consumer as a credential — which rides the consumer's normal credential sync into its remote environment, so no key ever touches your machine. Prints the credential ID, token prefix, base URL, and spec URL. `--read-only` restricts the consumer to read-only access; `--label` names the credential. Backend errors surface verbatim: 400 if the producer's REST API is disabled, 403/404 for ownership violations.

{cinna_cli-0.2.5 → cinna_cli-0.3.0}/docs/README.md

@@ -200,6 +200,11 @@ main.py  (CLI commands — Click)
   ├── account.py         — account workspace; `cinna login` (device auth), `cinna account`, `cinna agent`
   ├── doctor.py          — `cinna doctor`: reconcile registry ↔ Mutagen, delete stalled / terminate active sessions, refresh tokens
   ├── chat.py            — `cinna chat`: session-backed conversation testing (poll + NDJSON) over the api-proxy
+  ├── improve.py         — `cinna improve`: improvement requests users shared about your agents (list/show/download/status)
+  ├── local_import.py    — `cinna agent import`: the Local Agent Kit go-cloud step
+  ├── kit_contract.py    — the Local Agent Kit contract as data (`.cinna-kit/layout.json`):
+  │                        exclude patterns, secret-file rules, export walk, content_hash,
+  │                        publications.json ledger, contract-version gate
   ├── config.py          — .cinna/config.json: load/save/find
   ├── auth.py            — JWT storage, Authorization headers
   ├── client.py          — PlatformClient: HTTP + SSE stream_exec
@@ -287,6 +292,8 @@ authoring convention.
 | **Agent API** | `cinna agent-api` (enable, refresh, spec, call) · `cinna api` · `cinna connect agent-api` | [business](features/agent_api/agent_api.md) · [tech](features/agent_api/agent_api_tech.md) · [acceptance](features/agent_api/agent_api_acceptance.md) |
 | **MCP integration** | `cinna connect mcp` · `cinna mcp-proxy` (knowledge stdio server) | [business](features/mcp_integration/mcp_integration.md) · [tech](features/mcp_integration/mcp_integration_tech.md) · [acceptance](features/mcp_integration/mcp_integration_acceptance.md) |
 | **Git versioning** | `cinna git` (link, status, commit, push, pull, log, checkout, unlink) | [business](features/git_versioning/git_versioning.md) · [tech](features/git_versioning/git_versioning_tech.md) · [acceptance](features/git_versioning/git_versioning_acceptance.md) |
+| **Improvement requests** | `cinna improve` (list, show, download, status) | [business](features/improvement_requests/improvement_requests.md) · [tech](features/improvement_requests/improvement_requests_tech.md) · [acceptance](features/improvement_requests/improvement_requests_acceptance.md) |
+| **Local agent import** | `cinna agent import` (Local Agent Kit → cloud agent), incl. the versioned folder contract (`.cinna-kit/layout.json`), `publications.json` and `content_hash` | [business](features/local_agent_import/local_agent_import.md) · [tech](features/local_agent_import/local_agent_import_tech.md) · [acceptance](features/local_agent_import/local_agent_import_acceptance.md) |
 
 The sections below (Git Versioning, Sync Transport, Remote Exec, Remote Chat,
 Bootstrap Flow) remain as in-README quick references and backend contracts; the
@@ -610,6 +617,7 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 | POST | `/api/v1/cli/account/agents/{id}/mint` | Account token | Mint a per-agent CLI token (`cinna agent sync`, `cinna doctor` re-mint) |
 | POST | `/api/v1/cli/account/api-proxy` | Account token | Buffered JSON escape hatch — `cinna api`, and the transport for every `cinna chat` session/message call |
 | POST | `/api/v1/cli/account/files/upload` | Account token | Multipart upload for `cinna chat --file` (the proxy can't carry multipart) |
+| GET/PATCH | `/api/v1/cli/account/improvement-requests[/{id}[/archive]]` | Account token | Improvement requests received on the agents the account owns (`cinna improve`); the `/archive` route returns a binary ZIP the JSON-only proxy can't carry |
 
 `cinna chat` reaches the conversation API **through** the api-proxy (so these are inner routes, not CLI routes): `POST /sessions/`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `POST /sessions/{id}/messages/stream`, `GET /sessions/{id}/messages/streaming-status`, `POST /sessions/{id}/messages/interrupt`, and `GET /files/{id}/download`.
 

{cinna_cli-0.2.5 → cinna_cli-0.3.0}/docs/features/account_workspace/account_workspace.md

@@ -196,6 +196,14 @@ cinna account setup ────────────────────
 - **Remote Chat** — `cinna chat` runs through the account workspace's api-proxy
   (`AccountClient`), so it needs an account workspace; it is found by walking up
   from the cwd, exactly like the account verbs.
+- **Context package freshness** — `cinna account status` reports the local
+  `context/VERSION` against the platform's current package version and nudges
+  when it is behind, since guides (not just docs) ship in that tree.
+- **Improvement requests** — `cinna improve` runs on the account token from the
+  same root, so one queue spans every agent the account owns; the orchestrator
+  `CLAUDE.md` written here lists its verbs and `cinna account agents` supplies the
+  publisher-install flag its ownership step depends on. See
+  [improvement_requests](../improvement_requests/improvement_requests.md).
 - **Doctor / login** — `cinna doctor` re-mints expired per-agent tokens through
   the account token, and groups blocked agents under a single `cinna login` hint
   when the account token itself has expired.

cinna_cli-0.3.0/docs/features/improvement_requests/improvement_requests.md

@@ -0,0 +1,140 @@
+# Improvement Requests (`cinna improve`)
+
+## Purpose
+
+Lets an agent owner work, from the account workspace, the **improvement requests**
+users shared with them: a frozen snapshot of one bad session plus the runtime
+context that produced it. `cinna improve` lists what came in, shows one in full,
+downloads the archive for a local coding agent to read, and closes the request
+with a note the requester sees.
+
+## Mental model / core concepts
+
+- **Improvement request** — a consent-gated, one-directional share created on the
+  platform by a *session owner* (from the session menu, or with the
+  `/session-improve` command). It carries a frozen transcript of that one session
+  plus the tuning-relevant runtime context. The CLI never creates one; it only
+  receives.
+- **Frozen at consent** — the snapshot is a copy, not a live view. Continuing the
+  conversation afterwards, or deleting the session, does not change what the
+  archive contains. There is no "refresh" and no withdrawal.
+- **Requester vs. recipient** — the requester is the person who shared the
+  session; the recipient is the owner of the agent it landed on (the bundle
+  publisher, or the owner themselves for a standalone agent). `cinna improve`
+  always speaks as the **recipient**: the listing spans every agent the account
+  owns and never shows requests the account user submitted elsewhere.
+- **Source install vs. target agent** — the archive's `context.json` describes the
+  *requester's* install (the copy that misbehaved); the target agent named in
+  `cinna improve show` is the copy the recipient can actually change. For a
+  bundle they are different rows, which is why "where does the fix go?" is a
+  deliberate step in the workflow, not an assumption.
+- **Account-scoped** — every verb runs against the account CLI token from an
+  account workspace. There is no per-agent-workspace variant: the point is one
+  cross-agent queue.
+- **Short id** — the 8-character prefix printed in the listing (and offered for
+  copy in the web UI) is accepted anywhere a request id is taken, and names the
+  download folder.
+
+## User flows
+
+1. **Discover** — `cinna improve list --status new` prints the requests waiting on
+   every agent the account owns: short id, agent, source session, requester,
+   installed version + bundle id, the reported comment, submission date, status.
+   Requests captured from the *same session* are flagged in the Session column, so
+   a re-submitted report is obvious before anything is downloaded.
+   `--agent <name|slug|id>` narrows to one agent; `--limit` bounds the page;
+   `--json` emits the raw payload. When the workspace's context package is behind
+   the platform's, the listing ends with a one-line nudge to refresh — the queue's
+   playbook ships in that package.
+2. **Claim** — `cinna improve status <id> in_progress` marks it taken, so a
+   parallel session (or the owner watching the platform's Configuration tab)
+   doesn't pick up the same request.
+3. **Read** — `cinna improve show <id>` prints the request row, the reported
+   comment verbatim, and the frozen runtime-context block: bundle id, installed
+   vs. latest version, whether an update was pending, install kind, session mode,
+   SDK engine and effective model, environment name/version/instance, image
+   staleness, plugins, captured personal memory, how many secrets were scrubbed,
+   and who the recipient is. When the context carries a `prompts` block it also
+   prints a per-prompt **in sync / diverged / not compared** table against the
+   installed bundle revision — a consumer who owns their install can edit its prompts, so this is
+   the difference between "my agent misbehaved" and "their edit of my agent
+   misbehaved". Below the table it states **where a fix belongs** — the context
+   describes the requester's install, the request landed on the target agent, and
+   for a bundle those are opposite ownership, so the conclusion is printed rather
+   than left to be derived.
+4. **Download** — `cinna improve download <id>` fetches the ZIP and extracts it
+   into `improvements/<short-id>/` under the account root (`--out DIR` for another
+   target), printing every extracted file plus a reminder that this is another
+   person's conversation. The archive holds `README.md`, `metadata.json`,
+   `context.json`, `session/messages.{md,json}`, and — when the platform captured
+   them — `prompts/` (the install's live prompt docs, named after the workspace
+   files they mirror so they diff straight against the publisher's copy) and
+   `memory/`.
+5. **Fix** — outside this feature: the local coding agent follows the platform's
+   shipped playbook (`context/guides/handling-improvement-requests.md`, installed
+   by `cinna account setup` / `refresh-context`) to establish where the fix must
+   land and how much autonomy it has.
+6. **Close** — `cinna improve status <id> completed --note "…"` (or `declined`
+   with the reason). The note is shown to the requester.
+
+## Business rules
+
+- **Recipient-only mutation.** `status` is refused server-side for anyone who is
+  not the receiving agent's owner (403 for a requester who is party to the row,
+  404 for anyone else — ids the account is not party to never confirm existence).
+  The CLI surfaces the platform's status and message verbatim.
+- **Status vocabulary** — `new` → `in_progress` → `completed` | `declined`. The
+  CLI normalizes case and dashes (`In-Progress` → `in_progress`) and refuses an
+  unknown value *before* the round-trip, naming the valid ones. The backend keeps
+  the vocabulary in a plain column, so a value added later still reaches it.
+- **Short-id resolution is fail-loud.** A full UUID goes straight through. A
+  prefix is resolved against the listing: no match and an ambiguous match are both
+  errors naming the fix, never a silent "first match wins".
+- **Archive extraction is the safe extractor** — the same one used for the
+  workspace clone and the context package: absolute paths, `..` traversal,
+  symlinks, and oversized members are skipped with a warning rather than written.
+- **Re-downloading is idempotent** — extracting again into an existing folder
+  refreshes it in place and says so ("Refreshed" vs. "Extracted").
+- **The archive is somebody else's data.** The download command states it: don't
+  copy it into an agent workspace, don't commit it, delete it when done. What it
+  contains is bounded server-side — descriptors instead of uploaded file contents,
+  no container logs, and credential values scrubbed before storage — so the CLI
+  never has to filter it.
+- **An unchecked comparison is never reported as a match.** A prompt whose
+  divergence is `null` — platform-managed routing metadata, or a row with no
+  baseline — renders as *not compared* with the platform's reason, never as *in
+  sync*. Same rule for the rollup: no baseline prints "no baseline to compare
+  against".
+- **Truncation is disclosed** — a snapshot that hit the platform's size cap
+  dropped its *oldest* messages; `show` flags it next to the message count so the
+  reader doesn't reason as if the whole session is present.
+- **Account workspace required** — every verb resolves the account root first and
+  fails with the standard "Not in a cinna account workspace" error before any
+  network call.
+
+## Architecture overview
+
+```
+cinna improve <verb>
+  → src/cinna/main.py (improve group)
+  → src/cinna/improve.py (resolve short id, render, extract)
+  → src/cinna/client.py AccountClient (account token)
+  → GET/PATCH /api/v1/cli/account/improvement-requests[/{id}[/archive]]
+  → improvements/<short-id>/   (download only; safe extraction)
+```
+
+## Integration points
+
+- [Account workspace](../account_workspace/account_workspace.md) — supplies the
+  account root, the account token, and `_resolve_account_agent` for `--agent`.
+  The orchestrator `CLAUDE.md` written there lists these verbs and points at the
+  platform playbook; `cinna account agents` flags publisher installs, which is
+  the ownership signal the workflow depends on.
+- [Agent management](../agent_management/agent_management.md) — a fix usually
+  continues in a synced per-agent workspace (`cinna agent sync`), then
+  [Live sync](../live_sync/live_sync.md) pushes it and
+  [Remote chat](../remote_chat/remote_chat.md) verifies the behavior actually
+  changed.
+- [Agent API / escape hatch](../agent_api/agent_api.md) — the same JSON endpoints
+  are reachable through `cinna api`; the dedicated verbs exist for ergonomics and
+  because the binary archive cannot ride the JSON-only proxy.

cinna_cli-0.3.0/docs/features/improvement_requests/improvement_requests_acceptance.md

@@ -0,0 +1,256 @@
+# Improvement Requests — Acceptance Scenarios
+
+Real-usage scenarios for `cinna improve`, run against a **live platform** with a
+real account workspace. Unit tests (`tests/test_improve.py`) cover rendering and
+transport; these scenarios cover what only a live backend can show: consent flow
+end-to-end, recipient resolution for a bundle, authorization boundaries, and the
+archive's actual contents.
+
+## Preconditions
+
+- A live platform URL where the Agent Improvement Requests feature is deployed
+  (backend routes `/api/v1/cli/account/improvement-requests*`).
+- An **editable install** of this repo: `which cinna` resolves into the repo's
+  `src/cinna`.
+- An account workspace: `cinna login <domain>` (or `cinna account setup <token>`)
+  in an empty folder, then `cd` into it.
+- **Agent A** — a standalone agent the account owns, with a conversation session
+  containing at least a couple of messages.
+- **Agent B** *(for the bundle scenarios)* — a bundle published from this account
+  (the **publisher install**), plus a **consumer install** of that bundle owned by
+  a *second* user account, with a session on it.
+- Browser access to the platform UI as both users, to submit requests and to check
+  the Configuration-tab card.
+
+## Scenario catalog
+
+### 1. Standalone agent — submit, list, show
+
+**Goal** — the basic loop on an agent the account owns itself.
+**Setup** — Agent A with a session that has ≥ 1 message.
+**Steps**
+
+```bash
+# In the platform UI, as the owner: open the session → ⋮ → Improve Agent,
+# write a comment ("it answered with last month's numbers"), confirm.
+cinna improve list
+cinna improve list --status new
+cinna improve show <short-id>
+```
+
+**Expected** — the request appears with Agent A's name, the owner as requester,
+`standalone` in the Version column, the comment text, and status `new`. `show`
+prints the comment verbatim, the message count, and a runtime-context table
+carrying session mode, engine, effective model, and the environment name.
+**Watch for** — a self-targeted request that fails to resolve a recipient; a
+context block that is empty or missing the effective model (the platform must use
+its own resolver, not a re-implementation); a short id in the table that `show`
+cannot resolve.
+
+### 2. Submission via the `/session-improve` command
+
+**Goal** — the command entry point produces the same row as the menu.
+**Setup** — a second session on Agent A.
+**Steps**
+
+```bash
+cinna chat --agent <agent-a> "give me the quarterly totals"
+# In the platform UI, in that same session: /session-improve it used the wrong quarter
+cinna improve list --agent <agent-a> --json
+```
+
+**Expected** — a second row for Agent A whose `source` is `command` and whose
+`comment` is the text typed after the slash command.
+**Watch for** — `source` reported as `web_ui` for a command submission; the
+command's confirmation naming the wrong recipient.
+
+### 3. Bundle install — the request lands on the publisher
+
+**Goal** — the cross-user path: a consumer's session reaches the publisher.
+**Setup** — the consumer account has an install of the published bundle and a
+session on it.
+**Steps**
+
+```bash
+# As the CONSUMER, in the platform UI: session ⋮ → Improve Agent → confirm.
+# The modal must name the publisher and the bundle version before the button.
+# Then, as the PUBLISHER, in the account workspace:
+cinna improve list --status new
+cinna improve show <short-id>
+```
+
+**Expected** — the row's target agent is the **publisher install**, the requester
+is the consumer, and Version shows the installed version plus the bundle id.
+`show` reports `consumer install`, the installed vs. latest version, and whether
+an update was pending.
+**Watch for** — the request landing on the consumer's own copy instead of the
+publisher's; the publisher seeing the consumer's *other* sessions anywhere; a
+`fallback_reason` set when the publisher install actually exists.
+
+### 4. Download, extract, and read the archive
+
+**Goal** — the archive is a valid, complete, self-describing package.
+**Steps**
+
+```bash
+cinna improve download <short-id>
+ls -R improvements/<short-id>/
+head -40 improvements/<short-id>/README.md
+python3 -c "import json;print(json.load(open('improvements/<short-id>/context.json'))['sdk'])"
+```
+
+**Expected** — `README.md`, `metadata.json`, `context.json`, and
+`session/messages.md` + `session/messages.json` land under
+`improvements/<short-id>/`; the command lists each extracted file, prints the
+"another person's conversation" warning, and `context.json` carries the bundle
+version, installed/latest revision, session mode, SDK engine, and effective model.
+`README.md` states that container logs and uploaded file contents are excluded.
+**Watch for** — a truncated or unreadable ZIP; `session/messages.md` missing the
+tool calls that explain the failure; any uploaded file's *contents* (rather than a
+descriptor) appearing in the archive.
+
+### 5. The snapshot is frozen
+
+**Goal** — post-consent conversation never leaks into an already-shared request.
+**Steps**
+
+```bash
+cinna improve download <short-id> --out /tmp/before-<short-id>
+cinna chat --agent <agent-a> --resume <session_id> "and now add the discounts"
+cinna improve download <short-id>
+diff -r /tmp/before-<short-id> improvements/<short-id>/
+```
+
+**Expected** — the two extractions are identical; the follow-up turn is absent
+from both. The second run reports "Refreshed" rather than "Extracted".
+**Watch for** — the archive growing after the session continues; a re-download
+leaving a mix of old and new files behind.
+
+### 6. Status transitions and the requester-visible note
+
+**Goal** — the loop closes and the requester sees the outcome.
+**Steps**
+
+```bash
+cinna improve status <short-id> in_progress
+cinna improve list --status in_progress
+cinna improve status <short-id> completed --note "Fixed in v1.6 — it no longer re-asks for an uploaded file."
+cinna improve show <short-id>
+```
+
+**Expected** — each transition is confirmed, `show` reports the new status, a
+status-changed timestamp, and the resolution note; the requester sees the note on
+their side in the platform UI.
+**Watch for** — a note silently dropped; `status_changed_at` not moving; the
+Configuration-tab card not updating live (its WebSocket event).
+
+### 7. Refusals — unknown status, unknown id, ambiguous id
+
+**Goal** — fail-loud before the network, and never guess an id.
+**Steps**
+
+```bash
+cinna improve status <short-id> wontfix
+cinna improve show deadbeef
+cinna improve show <2-char-prefix-shared-by-two-requests>
+```
+
+**Expected** — respectively: "Unknown status 'wontfix'" listing the four valid
+values; "No improvement request matching 'deadbeef'" pointing at
+`cinna improve list`; an "ambiguous" error listing the matching short ids. All
+exit non-zero and change nothing.
+**Watch for** — a prefix silently resolving to the first match; a bad status
+reaching the backend as a 400/422 instead of a readable CLI error.
+
+### 8. Authorization boundary — a non-recipient sees nothing
+
+**Goal** — ids the account is not party to do not confirm their own existence.
+**Setup** — the consumer account's own account workspace, and a request id taken
+from the publisher's listing.
+**Steps**
+
+```bash
+# As the CONSUMER (the requester, not the recipient):
+cinna improve list
+cinna improve status <publisher-request-id> completed
+```
+
+**Expected** — the consumer's listing does **not** contain the request (that
+surface is the recipient's queue); the `status` attempt fails with the platform's
+403 for a party requester, and with a 404 for a completely unrelated account.
+**Watch for** — a 403 where a 404 is required for a stranger (existence leak); a
+requester being able to mutate status or delete the row.
+
+### 9. `--agent` filter and cross-agent scope
+
+**Goal** — one queue across every owned agent, narrowable to one.
+**Steps**
+
+```bash
+cinna improve list                      # both agents' requests
+cinna improve list --agent <agent-a>
+cinna improve list --agent "Nonexistent Agent"
+```
+
+**Expected** — the unfiltered listing spans both agents; the filtered one shows
+only Agent A's; an unknown reference fails with the accessible-agent list from
+`cinna account agents`.
+**Watch for** — the filter being applied client-side (it must reach the backend as
+`agent_id`); an agent name resolving to the wrong id when two agents share a slug.
+
+### 10. Session deleted after submission
+
+**Goal** — the payload is the row, not a pointer to a live session.
+**Steps**
+
+```bash
+# Delete the source session in the platform UI, then:
+cinna improve show <short-id>
+cinna improve download <short-id> --out /tmp/after-delete
+```
+
+**Expected** — both still succeed with the same content; the request row survives
+with its provenance link cleared.
+**Watch for** — a 500 or an empty archive after the session is gone; the archive
+degrading to a "snapshot unavailable" README when the snapshot is actually intact.
+
+### 11. Truncated snapshot is disclosed
+
+**Goal** — a capped snapshot is never read as a complete one.
+**Setup** — a session long enough to exceed the platform's snapshot cap.
+**Steps**
+
+```bash
+cinna improve show <short-id>
+grep -i truncat improvements/<short-id>/README.md
+```
+
+**Expected** — `show` flags the message count as truncated (oldest messages
+dropped), and the archive's README says the same.
+**Watch for** — truncation dropping the *newest* messages (defects cluster at the
+end); the flag present in the row but absent from the README.
+
+## Cross-cutting invariants
+
+- Every verb refuses to run outside an account workspace, before any network call.
+- No verb ever creates a request — consent happens only in the platform UI or via
+  `/session-improve`, on the requester's own session.
+- No credential value, container log, or uploaded file's contents appears in any
+  archive; scrubbing and exclusion are server-side and must stay that way.
+- Extraction never writes outside the destination directory, whatever the archive
+  claims.
+- Ids the account is not party to return 404, never 403 — no existence leak.
+- Downloaded archives stay under `improvements/` (or `--out`) — never inside
+  `agents/<slug>/workspace/`, and never committed.
+- The account token is the only credential involved; nothing is persisted to the
+  agent registry.
+
+## Cleanup
+
+```bash
+rm -rf improvements/ /tmp/before-* /tmp/after-delete
+```
+
+Close any request left `in_progress` (`cinna improve status <id> completed --note
+"…"` or `declined`), delete the throwaway sessions in the platform UI, and — if
+the scenarios created a test bundle install on the second account — uninstall it.