cinna-cli 0.4.1__tar.gz → 0.4.3__tar.gz

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.4.1
+Version: 0.4.3
 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
@@ -211,7 +211,9 @@ cinna account credentials types                                   # types + the
 cinna account credentials create --name "Stripe Key" --type api_token \
     --agent billing-agent                                         # create a draft and attach it in one step
 #   → prints required fields (e.g. api_token) + a link to fill them in
-cinna account credentials list                                    # name, type, status (complete / needs setup)
+cinna account credentials list                                    # name, type, slot, status (complete / needs setup), id
+cinna account credentials list --json                             # the raw listing
+cinna account credentials update <cred_id> --service-uri some-token.com   # give it the slot a skill declares
 cinna account credentials share-with-agent <cred_id> --agent crm-agent
 cinna account credentials update <cred_id> --name "Stripe (live)"
 cinna account credentials delete <cred_id> --yes
@@ -263,19 +265,60 @@ cinna agent sync crm-agent
 
 ### `cinna agent sync <agent>`
 
-Mint a per-agent CLI token (no UI interaction) and materialize a standard workspace under `agents/<slug>/`. `<agent>` is the display name, slug, or agent ID from `cinna account agents`. The result is identical to what `cinna setup` produces — own `.cinna/config.json`, registry entry, generated `CLAUDE.md` / `BUILDING_AGENT.md` / MCP configs / `mutagen.yml`, and the initial workspace clone — so afterwards:
+Mint a per-agent CLI token (no UI interaction) and materialize a standard workspace under `agents/<slug>/<subdir>/` (the Model-A nested layout — `<subdir>` is the slug unless the agent is git-versioned with another one; the command prints the exact path). `<agent>` is the display name, slug, or agent ID from `cinna account agents`. The result is identical to what `cinna setup` produces — own `.cinna/config.json`, registry entry, generated `CLAUDE.md` / `BUILDING_AGENT.md` / MCP configs / `mutagen.yml`, and the initial workspace clone — so afterwards:
 
 ```bash
-cd agents/hr-manager-agent/
+cd agents/hr-manager-agent/hr-manager-agent/
 cinna dev
 ```
 
 works exactly as for a manually set-up agent. Synced agents also appear in `cinna list` and in the agent's Integrations-tab session list like any other CLI session. The backend gates minting on building rights: foreign bundle installs and view-only agents are rejected with the server's error message.
 
+It also **starts the sync session and flushes it once**, while local and remote are still the same clone, so edits made afterwards sync as plain changes — a session first created by a later `cinna sync push` has no common starting point and reported the builder's own edits as conflicts. If the session cannot start (Mutagen missing, environment unreachable) the sync still succeeds with a warning to run `cinna sync push --agent <slug>` before editing.
+
 ### `cinna agent unsync <agent>`
 
 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 prompts pull | diff | push <agent> [--dir DIR]`
+
+Edit an agent's prompts as files instead of raw `cinna api` calls (whose inline JSON let the shell command-substitute a prompt's Markdown backticks).
+
+```bash
+cinna agent prompts pull crm-agent        # → prompts/crm-agent/{workflow,entrypoint,refiner,router_trigger,description}.md + example_prompts.json
+cinna agent prompts diff crm-agent        # local edits vs the platform
+cinna agent prompts push crm-agent --dry-run
+cinna agent prompts push crm-agent        # one bulk write, then the doc prompts into the running env
+```
+
+`pull` records what it pulled in `.pulled.json` and refuses to overwrite unpushed edits, files it did not write, or another agent's prompts without `--force`. `push` sends **only the fields edited since the pull**: a field the platform changed meanwhile is left alone when you did not edit it, and refused when you did (`--force` keeps yours; `pull --force` takes the platform's). After the write it calls the env's prompt sync when a workflow/entrypoint/refiner field changed (`--no-sync-env` to skip; a stopped environment picks them up on its next start). Delete a file to leave its field untouched. The agent config is authoritative — hand-editing the synced `workspace/docs/*.md` as well is a last-writer-wins race.
+
+`cinna agent show <agent>` prints each prompt under its `[entrypoint]` / `[workflow]` / `[refiner]` label and each connected credential with its type, slot, setup state and id. `cinna agent rebuild-env <agent>` waits after the rebuild until the environment answers its health check, and says "ready to chat" only then. `cinna agent restart-env` re-runs the same image and does not update the container's core or SDK helpers.
+
+### `cinna agent model show | set <agent>`
+
+The model is a setting of the agent's environment, not of the agent. `show` prints each mode's SDK, model override, effective model and health; `set` changes only what you pass and rebuilds.
+
+```bash
+cinna agent model show crm-agent
+cinna agent model set crm-agent --conversation haiku             # rebuilds, waits for the health check
+cinna agent model set crm-agent --building default --no-rebuild  # clear the override; apply on the next rebuild-env
+```
+
+`default` clears an override, or with `--conversation-credential` / `--building-credential` unpins an AI credential. The other mode and the credential pins keep their values, a setting already in place is a no-op, and `unknown_model` right after a set is usually a typo in the model id. Refused on a foreign install.
+
+### `cinna agent scenarios list | run <agent>`
+
+Re-run the agent's recorded `docs/test_scenarios/*.md` — each file's `## Say | Expect` table — without one `cinna chat` per row.
+
+```bash
+cinna agent scenarios list crm-agent
+cinna agent scenarios run crm-agent --out run.md
+cinna agent scenarios run crm-agent scope_and_pushback --yes --json
+```
+
+Every Say row goes to a fresh session, one after another. Each case reports the reply, the tool calls, the outcome and the session id, under a header naming the conversation model. The run does not judge: mark each row against its Expect. A case that does not complete prints its `cinna chat --attach` command, is not re-sent, and makes the command exit non-zero. The files are read from the synced workspace (`--path DIR` for any other folder) and never pushed.
+
 ### `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).
@@ -328,6 +371,8 @@ before skills carried one, which fills in after the next refresh or publish.
 
 The **Version** column is what the agent carries (`installed_version`), and an installed addon whose catalog has moved since reads `1.0.0 → 1.1.0` with the update command named under the table — an agent sitting two revisions back must not look identical to a current one. `Name` is the engine-facing folder name — the string `cinna skills publish` takes back — with the display name beside it when they differ. `· published` marks a local skill that already has a catalog package, so a re-publish appends a revision instead of creating a second package. The status column carries the server's own code (`secrets`, `oversized`, `shadowed` for warnings; `missing_description`, `name_mismatch`, `source_unavailable`, `orphan` for errors), and the platform's own sentence for each flagged row — with the offending files for `secrets` — follows under the table. Reads the server's cache, so it never wakes a sleeping environment: when the skill half could not be read the plugin rows still list and the reason is printed (`env_not_running`, `adapter_error`, `parse_error`) instead of a short list looking complete. `--json` prints the raw payload (`addons`, `counts`, `skills_error`) for a script or a local coding agent.
 
+When any skill declares credential slots (a `credentials:` block in its `SKILL.md`), a **Credentials** column lists each slot: `✓` filled, `! <reason>` not usable yet, `?` unchecked. Beneath the table each unusable slot gets its fix — e.g. naming the linked `api_token` credential that has no slot with `cinna account credentials update <id> --service-uri <slot>`, or a `credentials create … --service-uri <slot> --agent <agent>` draft when nothing could carry it. For a catalog install the reason is the platform's own (`not_linked`, `not_configured`, `access_revoked`); for a local or bundle skill an older platform computes nothing, so the CLI checks the agent's linked credentials itself (`not_linked`, `not_configured`, `type_mismatch`). A platform that does judge local skills has no `type_mismatch`, so a slot it calls `not_linked` while a linked credential of another type carries it is shown as `type_mismatch` — never as a draft for a second credential on that slot. A slot's value is read from the account credential listing, because the agent's own credential route reports none; a credential shared by someone else whose slot is not visible makes the slot `?`, never `not_linked`. The check is display-only: `--json` stays the raw payload.
+
 ### `cinna skills publish <agent> <name> [--visibility public|private|users] [--grant EMAIL ...] [--version V] [--notes TEXT] [--package-id ID] [--dry-run] [--yes] [--json]`
 
 Publish one of the agent's own skills to the instance skills catalog, where other agents can install it. `<name>` is the folder name from `cinna skills list`. Requires the `agent-developer` role on an agent that is not a foreign install; the skill must be clean (no parse error, no files that look like key material).
@@ -488,6 +533,9 @@ Run it from the account workspace (or any synced agent folder under it). The rep
 - Each `message` carries the agent's reasoning/tool trace under **`events`** — an ordered list of the `thinking` blocks, `tool` calls (with their full `tool_input` payload) and tool results behind the reply, so you see *what the agent did*, not just its final `content`. Pass `--no-events` to drop the trace and keep only the final text.
 - Files the agent attaches to its replies are downloaded under `./cinna-chat-files/<session_id>/` (override with `--download-dir`, or skip with `--no-download` to just report the file ids). Downloads are bounded by the api-proxy's 8 MiB response cap.
 - `--interval` / `--timeout` tune the poll cadence and the maximum wait for a turn. Ctrl-C interrupts the agent's turn and exits.
+- A poll request that fails transiently (a proxy timeout, a 429, a 5xx) is **retried within `--timeout`**, each retry announced as a `warning` event — the turn runs on the platform regardless. If contact is lost for good the command exits `12` with an `error` event carrying `session_id` and `recover`.
+- The closing `done` event always carries `outcome` — `completed`, `timeout` or `not_started` (`in_progress` / `idle` for `--show`) — plus `recover` when the turn may still be running.
+- `--attach <session_id>` sends nothing: it waits for that session's current turn and prints it, the way back into a turn a dead command left running (Ctrl-C only stops watching). `--show <session_id>` prints a session's transcript once and waits for nothing.
 
 ```bash
 cinna chat --agent crm-agent "Summarize today's leads"
@@ -495,9 +543,32 @@ cinna chat --agent crm-agent --file report.csv "Validate this export"
 cinna chat --resume 3fa85f64-5717-4562-b3fc-2c963f66afa6 "Now break it down by region"
 echo "ping" | cinna chat --agent crm-agent          # message from stdin
 cinna chat --agent crm-agent "hi" | jq -c 'select(.event=="message")'
+cinna chat --attach 3fa85f64-5717-4562-b3fc-2c963f66afa6   # recover a turn after a timeout
+cinna chat --show 3fa85f64-5717-4562-b3fc-2c963f66afa6     # read a transcript
+```
+
+The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`, or to re-attach with `--attach`.
+
+### `cinna delegation create | status | report | reply`
+
+Hand work to a remote agent as a **durable delegation** — a platform task with a stable identity that survives retries and carries structured results. Run from the account workspace. Every command first checks the server's delegation capability and refuses with "This server does not support durable delegations." when it is missing or not version 1.
+
+- `create --id KEY --target AGENT_UUID --title T --brief B [--execute]` — the identity is `--target` + `--id`: a retry with the same pair returns the original task (changed title/brief are ignored) and never launches execution twice (the backend deduplicates). Prints the backend **task id** the other commands take, and whether it executes. `--depth 2 --root ROOT` makes a sub-delegation (`--root` is required at depth 2, not allowed at depth 1); `--group` tags related work.
+- `status TASK_ID` — one read: state, latest result, and any open question with its result id. A requester agent should end its turn and let Cinna Desktop deliver the result rather than poll.
+- `report [TASK_ID] --status in_progress|blocked|done|failed --summary S` — `blocked` needs `--question`; `--audience user` when a human must decide (default `requester`). `--artifact` (repeatable) is a JSON object with non-empty `kind` (backend accepts `file` or `link`), `name` and an `http(s)` `ref` — upload local files separately. `--body` adds detail.
+- **Inside a cloud task**, omit `TASK_ID`: the report goes to the current task using `AGENT_AUTH_TOKEN`, `BACKEND_URL`, `ENV_ID` and the session in `CINNA_SESSION_CONTEXT_PATH` (default `./session_context.json`); the backend checks the session belongs to this environment's agent and owner.
+- `reply TASK_ID --result-id ID --message M` — answer a blocked question.
+- `--json` (after the subcommand) prints `{"result": "ok", "delegation": {…}}`.
+
+```bash
+cinna delegation create --id research-1 --target AGENT_UUID --title Research --brief 'Find the facts' --execute
+cinna delegation status TASK_ID
+cinna delegation report TASK_ID --status blocked --summary 'Choose a source' --question 'Which source?' --audience user
+cinna delegation reply TASK_ID --result-id RESULT_ID --message 'Use the primary source'
+cinna delegation report --status done --summary 'Finished'     # inside the cloud task
 ```
 
-The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`.
+Inside cloud tasks, cinna-core's MCP task server also offers a `handover_report` tool for the same report.
 
 ### `cinna dev`
 
@@ -519,8 +590,8 @@ cinna redev    # remote wins the initial conflicts, then a normal dev session
 Inspect and drive the sync session. `status` / `conflicts` are read-only views (safe alongside a live `cinna dev`); `push` / `pull` / `resolve` are for scripted (headless) builders who aren't running the TUI. All accept `--agent <ref>` to target a synced child workspace from the account root.
 
 - `status` — state, pending changes, conflict count. Warns loudly when conflicts mean your edits aren't fully live.
-- `conflicts` — list conflicted paths (sourced from the Mutagen daemon, so it agrees with `status`; two-way-safe writes no `.conflict.*` files on disk).
-- `push [--force]` — ensure a session, then flush and block until settled. `--force` resolves any parked conflicts in favor of **local** first ("my local is the truth"). The session persists in the daemon so later edits keep syncing.
+- `conflicts [--diff]` — list conflicted paths (sourced from the Mutagen daemon, so it agrees with `status`; two-way-safe writes no `.conflict.*` files on disk). `--diff` compares both copies of each path — size, sha256, a unified diff (remote → local) for text, and "identical content" / "only one copy exists" when the facts say so — reading the remote side in one `cinna exec`, and still showing the local side if the environment cannot answer.
+- `push [--force]` — ensure a session, then flush and block until settled. `--force` resolves any parked conflicts in favor of **local** first ("my local is the truth"). The session persists in the daemon so later edits keep syncing. A flush that ends with conflicts never prints "Sync settled": it warns with the count and points at `conflicts --diff`. (`cinna agent sync` already started the session on the fresh clone, so edits made after attaching don't come back as conflicts.)
 - `pull [--force]` — the mirror; `--force` resolves in favor of **remote** (e.g. after the backend regenerates managed files).
 - `resolve --prefer local|remote` — clear parked conflicts in one command. `local` deletes the remote losing copies (your version propagates out); `remote` backs up your local copies under `.cinna/sync/` and takes the container's version. Replaces the manual kill/delete/restart dance.
 
@@ -528,7 +599,7 @@ Inspect and drive the sync session. `status` / `conflicts` are read-only views (
 
 Stream a command through the platform to the remote agent environment. Output streams back live; Ctrl+C aborts. Exit code matches the remote process.
 
-The command runs with the **workspace root (`/app/workspace`) as its working directory**, so relative paths resolve against the synced workspace — e.g. `cinna exec python scripts/main.py` runs `/app/workspace/scripts/main.py` (the same cwd the scheduler uses). No need to prefix paths with `/app/workspace/`.
+The command runs with the **workspace root (`/app/workspace`) as its working directory**, so relative paths resolve against the synced workspace — e.g. `cinna exec python scripts/main.py` runs `/app/workspace/scripts/main.py` (the same cwd the scheduler uses). No need to prefix paths with `/app/workspace/`. `--cwd /app` starts at the container's app root instead. The command must be a program, not a shell builtin — hand pipes, redirects and `&&` to a shell: `cinna exec sh -c 'a | b'`.
 
 Arguments pass through transparently — each token is re-quoted before being sent, so spaces and shell metacharacters inside an argument survive intact. Use ordinary single-level quoting, exactly as for a local command. To run a shell snippet (pipes, redirects, `&&`), pass it to a shell explicitly: `cinna exec bash -c '…'`.
 
@@ -652,7 +723,7 @@ claude        # or: opencode
 
 ## Sync & Conflict Resolution
 
-`cinna sync` drives Mutagen in `two-way-safe` mode with VCS-aware ignores (including the backend-managed `credentials/` directory, so it never conflicts on files you're told not to edit). When the same file changes on both sides, Mutagen parks a conflict (it does **not** pick a winner, and does not write `.conflict.*` files in this mode) — list them with `cinna sync conflicts`, then clear them with `cinna sync resolve --prefer local` (your edits win) or `--prefer remote` (the container's version wins). For a non-interactive flush, `cinna sync push` / `cinna sync pull` settle the session and exit.
+`cinna sync` drives Mutagen in `two-way-safe` mode with VCS-aware ignores (including the backend-managed `credentials/` directory, so it never conflicts on files you're told not to edit). When the same file changes on both sides, Mutagen parks a conflict (it does **not** pick a winner, and does not write `.conflict.*` files in this mode) — list them with `cinna sync conflicts` (add `--diff` to compare the two copies of each), then clear them with `cinna sync resolve --prefer local` (your edits win) or `--prefer remote` (the container's version wins). For a non-interactive flush, `cinna sync push` / `cinna sync pull` settle the session and exit.
 
 Large binary files and build artifacts are ignored by default (see `mutagen.yml`). Add your own ignores there if needed.
 

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/README.md

@@ -174,7 +174,9 @@ cinna account credentials types                                   # types + the
 cinna account credentials create --name "Stripe Key" --type api_token \
     --agent billing-agent                                         # create a draft and attach it in one step
 #   → prints required fields (e.g. api_token) + a link to fill them in
-cinna account credentials list                                    # name, type, status (complete / needs setup)
+cinna account credentials list                                    # name, type, slot, status (complete / needs setup), id
+cinna account credentials list --json                             # the raw listing
+cinna account credentials update <cred_id> --service-uri some-token.com   # give it the slot a skill declares
 cinna account credentials share-with-agent <cred_id> --agent crm-agent
 cinna account credentials update <cred_id> --name "Stripe (live)"
 cinna account credentials delete <cred_id> --yes
@@ -226,19 +228,60 @@ cinna agent sync crm-agent
 
 ### `cinna agent sync <agent>`
 
-Mint a per-agent CLI token (no UI interaction) and materialize a standard workspace under `agents/<slug>/`. `<agent>` is the display name, slug, or agent ID from `cinna account agents`. The result is identical to what `cinna setup` produces — own `.cinna/config.json`, registry entry, generated `CLAUDE.md` / `BUILDING_AGENT.md` / MCP configs / `mutagen.yml`, and the initial workspace clone — so afterwards:
+Mint a per-agent CLI token (no UI interaction) and materialize a standard workspace under `agents/<slug>/<subdir>/` (the Model-A nested layout — `<subdir>` is the slug unless the agent is git-versioned with another one; the command prints the exact path). `<agent>` is the display name, slug, or agent ID from `cinna account agents`. The result is identical to what `cinna setup` produces — own `.cinna/config.json`, registry entry, generated `CLAUDE.md` / `BUILDING_AGENT.md` / MCP configs / `mutagen.yml`, and the initial workspace clone — so afterwards:
 
 ```bash
-cd agents/hr-manager-agent/
+cd agents/hr-manager-agent/hr-manager-agent/
 cinna dev
 ```
 
 works exactly as for a manually set-up agent. Synced agents also appear in `cinna list` and in the agent's Integrations-tab session list like any other CLI session. The backend gates minting on building rights: foreign bundle installs and view-only agents are rejected with the server's error message.
 
+It also **starts the sync session and flushes it once**, while local and remote are still the same clone, so edits made afterwards sync as plain changes — a session first created by a later `cinna sync push` has no common starting point and reported the builder's own edits as conflicts. If the session cannot start (Mutagen missing, environment unreachable) the sync still succeeds with a warning to run `cinna sync push --agent <slug>` before editing.
+
 ### `cinna agent unsync <agent>`
 
 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 prompts pull | diff | push <agent> [--dir DIR]`
+
+Edit an agent's prompts as files instead of raw `cinna api` calls (whose inline JSON let the shell command-substitute a prompt's Markdown backticks).
+
+```bash
+cinna agent prompts pull crm-agent        # → prompts/crm-agent/{workflow,entrypoint,refiner,router_trigger,description}.md + example_prompts.json
+cinna agent prompts diff crm-agent        # local edits vs the platform
+cinna agent prompts push crm-agent --dry-run
+cinna agent prompts push crm-agent        # one bulk write, then the doc prompts into the running env
+```
+
+`pull` records what it pulled in `.pulled.json` and refuses to overwrite unpushed edits, files it did not write, or another agent's prompts without `--force`. `push` sends **only the fields edited since the pull**: a field the platform changed meanwhile is left alone when you did not edit it, and refused when you did (`--force` keeps yours; `pull --force` takes the platform's). After the write it calls the env's prompt sync when a workflow/entrypoint/refiner field changed (`--no-sync-env` to skip; a stopped environment picks them up on its next start). Delete a file to leave its field untouched. The agent config is authoritative — hand-editing the synced `workspace/docs/*.md` as well is a last-writer-wins race.
+
+`cinna agent show <agent>` prints each prompt under its `[entrypoint]` / `[workflow]` / `[refiner]` label and each connected credential with its type, slot, setup state and id. `cinna agent rebuild-env <agent>` waits after the rebuild until the environment answers its health check, and says "ready to chat" only then. `cinna agent restart-env` re-runs the same image and does not update the container's core or SDK helpers.
+
+### `cinna agent model show | set <agent>`
+
+The model is a setting of the agent's environment, not of the agent. `show` prints each mode's SDK, model override, effective model and health; `set` changes only what you pass and rebuilds.
+
+```bash
+cinna agent model show crm-agent
+cinna agent model set crm-agent --conversation haiku             # rebuilds, waits for the health check
+cinna agent model set crm-agent --building default --no-rebuild  # clear the override; apply on the next rebuild-env
+```
+
+`default` clears an override, or with `--conversation-credential` / `--building-credential` unpins an AI credential. The other mode and the credential pins keep their values, a setting already in place is a no-op, and `unknown_model` right after a set is usually a typo in the model id. Refused on a foreign install.
+
+### `cinna agent scenarios list | run <agent>`
+
+Re-run the agent's recorded `docs/test_scenarios/*.md` — each file's `## Say | Expect` table — without one `cinna chat` per row.
+
+```bash
+cinna agent scenarios list crm-agent
+cinna agent scenarios run crm-agent --out run.md
+cinna agent scenarios run crm-agent scope_and_pushback --yes --json
+```
+
+Every Say row goes to a fresh session, one after another. Each case reports the reply, the tool calls, the outcome and the session id, under a header naming the conversation model. The run does not judge: mark each row against its Expect. A case that does not complete prints its `cinna chat --attach` command, is not re-sent, and makes the command exit non-zero. The files are read from the synced workspace (`--path DIR` for any other folder) and never pushed.
+
 ### `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).
@@ -291,6 +334,8 @@ before skills carried one, which fills in after the next refresh or publish.
 
 The **Version** column is what the agent carries (`installed_version`), and an installed addon whose catalog has moved since reads `1.0.0 → 1.1.0` with the update command named under the table — an agent sitting two revisions back must not look identical to a current one. `Name` is the engine-facing folder name — the string `cinna skills publish` takes back — with the display name beside it when they differ. `· published` marks a local skill that already has a catalog package, so a re-publish appends a revision instead of creating a second package. The status column carries the server's own code (`secrets`, `oversized`, `shadowed` for warnings; `missing_description`, `name_mismatch`, `source_unavailable`, `orphan` for errors), and the platform's own sentence for each flagged row — with the offending files for `secrets` — follows under the table. Reads the server's cache, so it never wakes a sleeping environment: when the skill half could not be read the plugin rows still list and the reason is printed (`env_not_running`, `adapter_error`, `parse_error`) instead of a short list looking complete. `--json` prints the raw payload (`addons`, `counts`, `skills_error`) for a script or a local coding agent.
 
+When any skill declares credential slots (a `credentials:` block in its `SKILL.md`), a **Credentials** column lists each slot: `✓` filled, `! <reason>` not usable yet, `?` unchecked. Beneath the table each unusable slot gets its fix — e.g. naming the linked `api_token` credential that has no slot with `cinna account credentials update <id> --service-uri <slot>`, or a `credentials create … --service-uri <slot> --agent <agent>` draft when nothing could carry it. For a catalog install the reason is the platform's own (`not_linked`, `not_configured`, `access_revoked`); for a local or bundle skill an older platform computes nothing, so the CLI checks the agent's linked credentials itself (`not_linked`, `not_configured`, `type_mismatch`). A platform that does judge local skills has no `type_mismatch`, so a slot it calls `not_linked` while a linked credential of another type carries it is shown as `type_mismatch` — never as a draft for a second credential on that slot. A slot's value is read from the account credential listing, because the agent's own credential route reports none; a credential shared by someone else whose slot is not visible makes the slot `?`, never `not_linked`. The check is display-only: `--json` stays the raw payload.
+
 ### `cinna skills publish <agent> <name> [--visibility public|private|users] [--grant EMAIL ...] [--version V] [--notes TEXT] [--package-id ID] [--dry-run] [--yes] [--json]`
 
 Publish one of the agent's own skills to the instance skills catalog, where other agents can install it. `<name>` is the folder name from `cinna skills list`. Requires the `agent-developer` role on an agent that is not a foreign install; the skill must be clean (no parse error, no files that look like key material).
@@ -451,6 +496,9 @@ Run it from the account workspace (or any synced agent folder under it). The rep
 - Each `message` carries the agent's reasoning/tool trace under **`events`** — an ordered list of the `thinking` blocks, `tool` calls (with their full `tool_input` payload) and tool results behind the reply, so you see *what the agent did*, not just its final `content`. Pass `--no-events` to drop the trace and keep only the final text.
 - Files the agent attaches to its replies are downloaded under `./cinna-chat-files/<session_id>/` (override with `--download-dir`, or skip with `--no-download` to just report the file ids). Downloads are bounded by the api-proxy's 8 MiB response cap.
 - `--interval` / `--timeout` tune the poll cadence and the maximum wait for a turn. Ctrl-C interrupts the agent's turn and exits.
+- A poll request that fails transiently (a proxy timeout, a 429, a 5xx) is **retried within `--timeout`**, each retry announced as a `warning` event — the turn runs on the platform regardless. If contact is lost for good the command exits `12` with an `error` event carrying `session_id` and `recover`.
+- The closing `done` event always carries `outcome` — `completed`, `timeout` or `not_started` (`in_progress` / `idle` for `--show`) — plus `recover` when the turn may still be running.
+- `--attach <session_id>` sends nothing: it waits for that session's current turn and prints it, the way back into a turn a dead command left running (Ctrl-C only stops watching). `--show <session_id>` prints a session's transcript once and waits for nothing.
 
 ```bash
 cinna chat --agent crm-agent "Summarize today's leads"
@@ -458,9 +506,32 @@ cinna chat --agent crm-agent --file report.csv "Validate this export"
 cinna chat --resume 3fa85f64-5717-4562-b3fc-2c963f66afa6 "Now break it down by region"
 echo "ping" | cinna chat --agent crm-agent          # message from stdin
 cinna chat --agent crm-agent "hi" | jq -c 'select(.event=="message")'
+cinna chat --attach 3fa85f64-5717-4562-b3fc-2c963f66afa6   # recover a turn after a timeout
+cinna chat --show 3fa85f64-5717-4562-b3fc-2c963f66afa6     # read a transcript
+```
+
+The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`, or to re-attach with `--attach`.
+
+### `cinna delegation create | status | report | reply`
+
+Hand work to a remote agent as a **durable delegation** — a platform task with a stable identity that survives retries and carries structured results. Run from the account workspace. Every command first checks the server's delegation capability and refuses with "This server does not support durable delegations." when it is missing or not version 1.
+
+- `create --id KEY --target AGENT_UUID --title T --brief B [--execute]` — the identity is `--target` + `--id`: a retry with the same pair returns the original task (changed title/brief are ignored) and never launches execution twice (the backend deduplicates). Prints the backend **task id** the other commands take, and whether it executes. `--depth 2 --root ROOT` makes a sub-delegation (`--root` is required at depth 2, not allowed at depth 1); `--group` tags related work.
+- `status TASK_ID` — one read: state, latest result, and any open question with its result id. A requester agent should end its turn and let Cinna Desktop deliver the result rather than poll.
+- `report [TASK_ID] --status in_progress|blocked|done|failed --summary S` — `blocked` needs `--question`; `--audience user` when a human must decide (default `requester`). `--artifact` (repeatable) is a JSON object with non-empty `kind` (backend accepts `file` or `link`), `name` and an `http(s)` `ref` — upload local files separately. `--body` adds detail.
+- **Inside a cloud task**, omit `TASK_ID`: the report goes to the current task using `AGENT_AUTH_TOKEN`, `BACKEND_URL`, `ENV_ID` and the session in `CINNA_SESSION_CONTEXT_PATH` (default `./session_context.json`); the backend checks the session belongs to this environment's agent and owner.
+- `reply TASK_ID --result-id ID --message M` — answer a blocked question.
+- `--json` (after the subcommand) prints `{"result": "ok", "delegation": {…}}`.
+
+```bash
+cinna delegation create --id research-1 --target AGENT_UUID --title Research --brief 'Find the facts' --execute
+cinna delegation status TASK_ID
+cinna delegation report TASK_ID --status blocked --summary 'Choose a source' --question 'Which source?' --audience user
+cinna delegation reply TASK_ID --result-id RESULT_ID --message 'Use the primary source'
+cinna delegation report --status done --summary 'Finished'     # inside the cloud task
 ```
 
-The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`.
+Inside cloud tasks, cinna-core's MCP task server also offers a `handover_report` tool for the same report.
 
 ### `cinna dev`
 
@@ -482,8 +553,8 @@ cinna redev    # remote wins the initial conflicts, then a normal dev session
 Inspect and drive the sync session. `status` / `conflicts` are read-only views (safe alongside a live `cinna dev`); `push` / `pull` / `resolve` are for scripted (headless) builders who aren't running the TUI. All accept `--agent <ref>` to target a synced child workspace from the account root.
 
 - `status` — state, pending changes, conflict count. Warns loudly when conflicts mean your edits aren't fully live.
-- `conflicts` — list conflicted paths (sourced from the Mutagen daemon, so it agrees with `status`; two-way-safe writes no `.conflict.*` files on disk).
-- `push [--force]` — ensure a session, then flush and block until settled. `--force` resolves any parked conflicts in favor of **local** first ("my local is the truth"). The session persists in the daemon so later edits keep syncing.
+- `conflicts [--diff]` — list conflicted paths (sourced from the Mutagen daemon, so it agrees with `status`; two-way-safe writes no `.conflict.*` files on disk). `--diff` compares both copies of each path — size, sha256, a unified diff (remote → local) for text, and "identical content" / "only one copy exists" when the facts say so — reading the remote side in one `cinna exec`, and still showing the local side if the environment cannot answer.
+- `push [--force]` — ensure a session, then flush and block until settled. `--force` resolves any parked conflicts in favor of **local** first ("my local is the truth"). The session persists in the daemon so later edits keep syncing. A flush that ends with conflicts never prints "Sync settled": it warns with the count and points at `conflicts --diff`. (`cinna agent sync` already started the session on the fresh clone, so edits made after attaching don't come back as conflicts.)
 - `pull [--force]` — the mirror; `--force` resolves in favor of **remote** (e.g. after the backend regenerates managed files).
 - `resolve --prefer local|remote` — clear parked conflicts in one command. `local` deletes the remote losing copies (your version propagates out); `remote` backs up your local copies under `.cinna/sync/` and takes the container's version. Replaces the manual kill/delete/restart dance.
 
@@ -491,7 +562,7 @@ Inspect and drive the sync session. `status` / `conflicts` are read-only views (
 
 Stream a command through the platform to the remote agent environment. Output streams back live; Ctrl+C aborts. Exit code matches the remote process.
 
-The command runs with the **workspace root (`/app/workspace`) as its working directory**, so relative paths resolve against the synced workspace — e.g. `cinna exec python scripts/main.py` runs `/app/workspace/scripts/main.py` (the same cwd the scheduler uses). No need to prefix paths with `/app/workspace/`.
+The command runs with the **workspace root (`/app/workspace`) as its working directory**, so relative paths resolve against the synced workspace — e.g. `cinna exec python scripts/main.py` runs `/app/workspace/scripts/main.py` (the same cwd the scheduler uses). No need to prefix paths with `/app/workspace/`. `--cwd /app` starts at the container's app root instead. The command must be a program, not a shell builtin — hand pipes, redirects and `&&` to a shell: `cinna exec sh -c 'a | b'`.
 
 Arguments pass through transparently — each token is re-quoted before being sent, so spaces and shell metacharacters inside an argument survive intact. Use ordinary single-level quoting, exactly as for a local command. To run a shell snippet (pipes, redirects, `&&`), pass it to a shell explicitly: `cinna exec bash -c '…'`.
 
@@ -615,7 +686,7 @@ claude        # or: opencode
 
 ## Sync & Conflict Resolution
 
-`cinna sync` drives Mutagen in `two-way-safe` mode with VCS-aware ignores (including the backend-managed `credentials/` directory, so it never conflicts on files you're told not to edit). When the same file changes on both sides, Mutagen parks a conflict (it does **not** pick a winner, and does not write `.conflict.*` files in this mode) — list them with `cinna sync conflicts`, then clear them with `cinna sync resolve --prefer local` (your edits win) or `--prefer remote` (the container's version wins). For a non-interactive flush, `cinna sync push` / `cinna sync pull` settle the session and exit.
+`cinna sync` drives Mutagen in `two-way-safe` mode with VCS-aware ignores (including the backend-managed `credentials/` directory, so it never conflicts on files you're told not to edit). When the same file changes on both sides, Mutagen parks a conflict (it does **not** pick a winner, and does not write `.conflict.*` files in this mode) — list them with `cinna sync conflicts` (add `--diff` to compare the two copies of each), then clear them with `cinna sync resolve --prefer local` (your edits win) or `--prefer remote` (the container's version wins). For a non-interactive flush, `cinna sync push` / `cinna sync pull` settle the session and exit.
 
 Large binary files and build artifacts are ignored by default (see `mutagen.yml`). Add your own ignores there if needed.
 

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/README.md

@@ -201,6 +201,7 @@ 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
+  ├── scenarios.py       — `cinna agent scenarios`: parse docs/test_scenarios Say | Expect tables, replay each row via chat.py
   ├── 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`):
@@ -285,16 +286,17 @@ authoring convention.
 | Feature | Command surface | Docs |
 |---|---|---|
 | **Bootstrap & onboarding** | `cinna setup` / `set-token` / `login` / `list` / `status` / `disconnect[-all]` / `completion` / `dev` / `redev`; the no-TTY contract (`--no-input`, `--json`, exit codes, `CINNA_MUTAGEN_BIN`) | [business](features/bootstrap_onboarding/bootstrap_onboarding.md) · [tech](features/bootstrap_onboarding/bootstrap_onboarding_tech.md) · [acceptance](features/bootstrap_onboarding/bootstrap_onboarding_acceptance.md) |
-| **Account workspace** | `cinna account` (setup, set-token, agents, status, refresh-context, user-workspace, credentials); desktop-managed workspaces | [business](features/account_workspace/account_workspace.md) · [tech](features/account_workspace/account_workspace_tech.md) · [acceptance](features/account_workspace/account_workspace_acceptance.md) |
-| **Agent management** | `cinna agent` (sync, unsync, create, restart-env, rebuild-env, show, status) | [business](features/agent_management/agent_management.md) · [tech](features/agent_management/agent_management_tech.md) · [acceptance](features/agent_management/agent_management_acceptance.md) |
+| **Account workspace** | `cinna account` (setup, set-token, agents, status, refresh-context, user-workspace, credentials — `list` shows each credential's slot, `--json`); desktop-managed workspaces | [business](features/account_workspace/account_workspace.md) · [tech](features/account_workspace/account_workspace_tech.md) · [acceptance](features/account_workspace/account_workspace_acceptance.md) |
+| **Agent management** | `cinna agent` (sync — which also starts the sync session, unsync, create, restart-env, rebuild-env — which waits for the health check, show — with each credential's slot, prompts pull / diff / push, model show / set — the model per mode, merged client-side and applied by a rebuild, status) | [business](features/agent_management/agent_management.md) · [tech](features/agent_management/agent_management_tech.md) · [acceptance](features/agent_management/agent_management_acceptance.md) |
 | **Agent schedules** | `cinna agent schedule` (list, generate, create, update, run, logs, delete) | [business](features/agent_schedules/agent_schedules.md) · [tech](features/agent_schedules/agent_schedules_tech.md) · [acceptance](features/agent_schedules/agent_schedules_acceptance.md) |
-| **Live sync** | `cinna sync` (status, conflicts, push, pull, resolve) + Mutagen transport | [business](features/live_sync/live_sync.md) · [tech](features/live_sync/live_sync_tech.md) · [acceptance](features/live_sync/live_sync_acceptance.md) |
+| **Live sync** | `cinna sync` (status, conflicts `[--diff]`, push, pull, resolve) + Mutagen transport; the session is started by `cinna agent sync` so the first push has a baseline | [business](features/live_sync/live_sync.md) · [tech](features/live_sync/live_sync_tech.md) · [acceptance](features/live_sync/live_sync_acceptance.md) |
 | **Remote exec** | `cinna exec` | [business](features/remote_exec/remote_exec.md) · [tech](features/remote_exec/remote_exec_tech.md) · [acceptance](features/remote_exec/remote_exec_acceptance.md) |
-| **Remote chat** | `cinna chat` | [business](features/remote_chat/remote_chat.md) · [tech](features/remote_chat/remote_chat_tech.md) · [acceptance](features/remote_chat/remote_chat_acceptance.md) |
+| **Remote chat** | `cinna chat` (incl. `--attach` / `--show` to recover or read an existing session; poll failures retried within `--timeout`) · `cinna agent scenarios list / run` (replay `docs/test_scenarios/` Say rows, one session per row) | <!-- nocheck: agent-workspace path --> [business](features/remote_chat/remote_chat.md) · [tech](features/remote_chat/remote_chat_tech.md) · [acceptance](features/remote_chat/remote_chat_acceptance.md) |
 | **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) |
-| **Agent addons** | `cinna skills` (list, publish, install, uninstall, update, toggle, refresh, catalog, show, revisions, files, grants, grant, revoke, visibility, delist, relist) — the whole skills lifecycle: what an agent carries, publishing one of its `skills/<name>/` folders to the catalog, installing a package on another agent and keeping it current, and sharing after the fact | [business](features/agent_addons/agent_addons.md) · [tech](features/agent_addons/agent_addons_tech.md) · [acceptance](features/agent_addons/agent_addons_acceptance.md) |
+| **Agent addons** | `cinna skills` (list — with each declared credential slot's readiness, publish, install, uninstall, update, toggle, refresh, catalog, show, revisions, files, grants, grant, revoke, visibility, delist, relist) — the whole skills lifecycle: what an agent carries, publishing one of its `skills/<name>/` folders to the catalog, installing a package on another agent and keeping it current, and sharing after the fact | [business](features/agent_addons/agent_addons.md) · [tech](features/agent_addons/agent_addons_tech.md) · [acceptance](features/agent_addons/agent_addons_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) |
+| **Durable delegation** | `cinna delegation` (create — idempotent per target + `--id`, status, report — owner side with a task id or from inside a cloud task, reply), gated on the backend capability version | [business](features/delegation/delegation.md) · [tech](features/delegation/delegation_tech.md) · [acceptance](features/delegation/delegation_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) |
 

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/features/account_workspace/account_workspace.md

@@ -154,8 +154,13 @@ each with its own token, registry entry, and Mutagen session.
   (the CLI sends no secret) in the active workspace and prints exactly which
   fields the user must complete plus the UI link. `--agent` attaches it in one
   step; `--workspace` overrides the target workspace.
-- `cinna account credentials list` shows credentials with their setup status
-  (complete / needs setup) — metadata only.
+- `cinna account credentials list` shows credentials with their type, **slot**,
+  setup status (complete / needs setup, plus a placeholder marker) and full id —
+  metadata only. The slot is the credential's service URI: the non-secret id a
+  skill's `credentials:` block names and a script looks the credential up by, so
+  it is the column that answers "which credential fills this skill's slot". The
+  hint under the table names `cinna account credentials update <id> --service-uri
+  <slot>`. `--json` prints the raw listing.
 - `cinna account credentials update <id>` edits metadata (name/notes/service-uri/
   sharing), never a secret. `cinna account credentials share-with-agent <id>
   --agent <ref>` attaches an existing credential. `cinna account credentials

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/features/account_workspace/account_workspace_acceptance.md

@@ -161,6 +161,17 @@ the silent-secret and scope-drift bugs live.
 - **Watch for:** any secret-bearing field being sent from the CLI; the draft
   showing `complete` before the user fills it; the credential landing in the
   wrong workspace.
+- **Then check the slot surfaces:**
+  ```
+  cinna account credentials update <cred-id> --service-uri stripe.com
+  cinna account credentials list | grep "Stripe Key"
+  cinna account credentials list --json | jq '.data[] | select(.id=="<cred-id>") | .service_uri'
+  ```
+  **Expected:** the table's `Slot` column reads `stripe.com` for that row (and `—`
+  for credentials without one), the full id is unbroken, and a placeholder shows
+  `placeholder`; `--json` prints only JSON and the jq query returns `"stripe.com"`.
+  **Watch for:** the slot missing from the table; `--json` output mixed with a
+  table or hint line; an id wrapped or elided at a narrow width.
 
 ### 9. Credential create `--agent` attaches in one step
 

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/features/account_workspace/account_workspace_tech.md

@@ -216,6 +216,16 @@ Related (documented here as integration points): `cinna agent sync` →
 - `src/cinna/account.py:run_credentials_update()` — refuses an empty update;
   metadata fields only (`name`/`notes`/`service_uri`/`allow_sharing`).
 - `src/cinna/account.py:_credential_status_cell()` — complete / needs setup / —.
+- `src/cinna/account.py:run_credentials_list()` — `--json` echoes the listing
+  untouched; otherwise the table adds a `Slot` column (`_credential_slot_cell()`,
+  the escaped `service_uri` or a dim dash), marks `is_placeholder`, never wraps the
+  id, and prints the `--service-uri` hint. Names and types go through `_esc()`.
+  (`tests/test_account.py:test_credentials_list_shows_each_slot`,
+  `test_credentials_list_json_prints_the_raw_listing`.)
+- The account listing is also the authority for a linked credential's slot
+  elsewhere: `src/cinna/account.py:_fetch_linked_credentials()` overlays its
+  `service_uri` / `is_placeholder` / `status` by id onto the agent credential
+  route, which returns `service_uri: null` (see Agent Management).
 
 ## Config & registry
 

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/features/agent_addons/agent_addons.md

@@ -76,6 +76,29 @@ without `cinna api`, and without anyone typing a UUID.
    gone.
 5. When the skill half could not be read, the plugin rows still list and the
    reason is stated (`env_not_running`, `adapter_error`, `parse_error`).
+6. When any skill declares credential slots, a **Credentials** column lists each
+   slot: `✓` filled, `!` not usable yet with its reason, `?` unchecked. Beneath
+   the table every unusable slot gets its fix, and the note that a skill's
+   credential is checked only when its script asks for it — the agent keeps
+   working, that script fails.
+   - For a **catalog** install the platform already computed readiness
+     (`credential_issues`, one reason per slot: `not_linked`, `not_configured`,
+     `access_revoked`), and the CLI renders it as-is.
+   - For every **other** row an older platform computes nothing — a local skill
+     read `ok` while nothing carried its slot. The CLI checks the agent's linked
+     credentials itself: no credential with that service URI → `not_linked`; one of
+     another type → `type_mismatch`; only a placeholder or an unfilled one →
+     `not_configured`.
+   - A platform that judges local and bundle rows too sends `credential_issues`
+     for them, and its reason wins — except that it has no `type_mismatch`: a slot
+     it calls `not_linked` while a linked credential of another type carries it is
+     shown as `type_mismatch`, because drafting a second credential on a taken
+     slot would be the wrong fix.
+   - The remedy is specific: a linked credential of the declared type with no slot
+     is named with the `credentials update <id> --service-uri <slot>` command;
+     otherwise the `credentials create … --service-uri <slot> --agent <agent>` draft.
+   - A linked credential shared by someone else whose slot this account cannot see
+     makes the slot `?`, never `not_linked` — it may well be the carrier.
 
 ### Publish a skill to the catalog
 

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/features/agent_addons/agent_addons_acceptance.md

@@ -598,6 +598,40 @@ elided, at any terminal width.
 found`; the resolution note landing on stdout and corrupting a JSON pipe; a
 non-agent sub-route under `agents/` being rejected instead of passed through.
 
+### 24. A local skill's credential slot is checked, not assumed
+
+**Goal** — `cinna skills list` says whether a local skill's declared slot is
+actually filled; the platform reports `credential_issues` for catalog installs
+only, so a local skill used to read `● ok` with nothing carrying its slot.
+
+**Setup** — `AGENT` has a linked `api_token` credential with **no** service URI,
+and its workspace holds `skills/acceptance-slot/SKILL.md` declaring
+`credentials:` with `- slot: acceptance-token.example` / `type: api_token`, pushed
+with `cinna sync push --agent <slug>`.
+
+**Steps**
+
+```bash
+cinna skills list <AGENT>
+cinna account credentials update <CRED_ID> --service-uri acceptance-token.example
+cinna skills list <AGENT>
+cinna agent show <AGENT> | sed -n '/Connected credentials/,$p'
+cinna skills list <AGENT> --json | jq '.addons[] | select(.name=="acceptance-slot") | .credential_issues'
+```
+
+**Expected** — the first list shows a `Credentials` column with
+`! acceptance-token.example (not_linked)` and, beneath, the exact command
+`cinna account credentials update <CRED_ID> --service-uri acceptance-token.example`
+naming the linked token. After running it, the row reads `✓ acceptance-token.example`
+with no remedy block, and `agent show` prints `slot: acceptance-token.example` for
+that credential. `--json` is the unmodified payload (`credential_issues` stays `[]`
+for a local skill — the CLI's check never leaks into it).
+
+**Watch for** — `✓` before the slot is set; `not_linked` after it is set (the
+agent credential route returns `service_uri: null`, so the slot must be read from
+the account listing); a `Credentials` column on an agent whose skills declare no
+slot; the readiness lookup running under `--json`.
+
 ## Cross-cutting invariants
 
 - No secret value is ever printed, and a skill folder that holds one cannot be

{cinna_cli-0.4.1 → cinna_cli-0.4.3}/docs/features/agent_addons/agent_addons_tech.md

@@ -65,7 +65,26 @@
   first unpublished skill the caller may share.
 - `src/cinna/account.py:_print_addons()` — one table row per addon; prints the
   `counts` line and warns when `skills_error` is set, so a partial list is never
-  mistaken for a complete one.
+  mistaken for a complete one. Adds the `Credentials` column (and
+  `_print_credential_readiness()` beneath) only when some row declares a slot, so
+  an agent without any keeps its shape.
+- `src/cinna/account.py:run_skills_list()` fetches `_fetch_linked_credentials()`
+  only when `_needs_linked_credentials()` — a **non-catalog** row declares a slot —
+  and never under `--json` (the raw payload stays raw).
+- `src/cinna/account.py:_declared_slots()` — the slots a row's `skills[].credentials`
+  declare (first declaration of a slot wins).
+- `src/cinna/account.py:_slot_readiness()` — `(state, credential)` per slot: a
+  `credential_issues` entry for the slot wins (its `reason`), except a `not_linked`
+  whose slot every linked carrier holds with another type, which reads
+  `type_mismatch` (the platform has no such reason); a catalog row with no
+  entry is `ready` (the platform computed it); otherwise matched against the linked
+  credentials by `service_uri` → `not_linked` / `type_mismatch` / `not_configured` /
+  `ready`, and `unknown` when the listing is `None` or a `_SLOT_UNVERIFIED`
+  credential could be the carrier.
+- `src/cinna/account.py:_addon_credentials_cell()` / `_slot_remedy()` /
+  `_print_credential_readiness()` — the column cell (amber, never red: an unfilled
+  skill slot never blocks the agent), the per-state command, and the block under
+  the table.
 - `src/cinna/account.py:_addon_status_cell()` — colours `ok` / `warning` /
   `error` and puts the server's `status_code` in the column: codes are the
   contract, and a code keeps the row one line.
@@ -193,10 +212,18 @@ uuid}`).
 All four routes are ordinary platform routes reached through the account escape
 hatch, `POST /api/v1/cli/account/api-proxy`:
 
+- `GET /api/v1/agents/{agent_id}/credentials` and the account's
+  `GET /api/v1/cli/account/credentials` — read together by
+  `_fetch_linked_credentials()` for slot readiness: the first says which
+  credentials are linked, the second supplies each one's `service_uri`,
+  `is_placeholder` and `status` by id, because the first returns `service_uri:
+  null` for a credential that has a slot (observed on a live instance).
 - `GET /api/v1/agents/{agent_id}/addons` — the deduplicated projection
   (`AgentAddonsPublic`). Consumed fields: `addons[]` (`AddonPublic`: `key`,
   `kind`, `source`, `name`, `display_name`, `version`, `marketplace_name`,
-  `status`, `status_code`, `orphan`, `can_share`, `published_package_id`, and
+  `status`, `status_code`, `orphan`, `can_share`, `published_package_id`,
+  `credential_issues` (`slot` + `reason`, computed for catalog rows only),
+  `skills[].credentials` (`slot`, `type`, `description`), and
   **`link`**), `counts` (`plugins`, `skills`, `local_skills`), and
   `skills_error`. `link` is an `AgentPluginLinkWithUpdateInfo`: `id`,
   `installed_version`, `latest_version`, `has_update`, `disabled`,