cinna-cli 0.5.1__tar.gz → 0.5.3__tar.gz

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.5.1
+Version: 0.5.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
@@ -486,6 +486,24 @@ Take a package out of the catalog. Agents that already installed it keep what th
 
 Put a delisted package back. `delist` has no inverse route of its own — without this verb the only way back would be `cinna api`, which would make delisting the one door in this group that opens only outwards.
 
+### `cinna agent-api access list | issue | revoke | scopes`
+
+Give people (or your own local agent) API access to a producer, from the account workspace. A key is issued to a **person** and lands in their credentials; **its value never appears in the CLI** — not on self-issue, not in `--json`. Reveal and rotate live on the web credential page, and so does the external-access switch (when it is off, `issue` is refused with the producer's Integrations URL). Writes need the `agent-developer` role.
+
+- `list <producer> [--all] [--json]` — people, their scopes and keys (prefix, status, expiry, last used, linked agents, id). Ended keys (revoked, expired, removed) are hidden unless `--all`; `--json` is always the full listing.
+- `issue <producer> --to <email|me> [--scopes a,b] [--expires-in-days N] [--service-uri SLOT] [--label TEXT] [--read-only] [--json]` — `--to` is required. `me` puts the key in your own credentials and prints the web URL where you reveal it; a local agent in Cinna Desktop calls it with `cinna_credentials.agent_api_session("<slot>")`, a cloud agent is wired with `cinna connect agent-api` instead.
+- `revoke <producer> <key> [--yes] [--json]` — `<key>` is the key id or the exact token prefix (an elided one is refused). Asks first; `--json` needs `--yes`; an already revoked key is reported, exit 0. The person's scopes stay.
+- `scopes <producer> --to <email|me> (--set a,b | --clear) [--json]` — change a grant without touching keys.
+
+```bash
+cinna agent-api access issue orders-agent --to me --service-uri orders-api
+cinna agent-api access issue orders-agent --to ana@example.com --scopes read --expires-in-days 30
+cinna agent-api access list orders-agent --all
+cinna agent-api access revoke orders-agent a1b2c3d4
+```
+
+`cinna account credentials list` shows an issued key's state in its Status column, and a skill slot filled by a revoked or expired key reads as not usable. `cinna agent import` does not draft `agent_api` credentials; it prints the `access issue` / `connect agent-api` command instead.
+
 ### `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.
@@ -508,7 +526,7 @@ Generic escape hatch into the platform API, authenticated with the account token
 
 - `--json '<obj>'` or `--data @file.json` supply a JSON request body (mutually exclusive); repeatable `--query k=v` supplies query parameters (repeating a key builds a list).
 - The inner response is passed through verbatim: the body prints to stdout (pretty-printed for JSON) and the exit code is `0` for 2xx and `1` for an inner 4xx/5xx — so it composes in shell pipelines.
-- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
+- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded, as are routes that would hand out a secret: any method on `agents/*/agent-api/keys…` (issued keys), on `environments/*/workspace/download` and `view-file`, and on `dashboards/*/blocks/*/env-file`; and POST on A2A access-tokens, MCP/ACP connector tokens, agent and task-trigger webhook create/regenerate-token. Paths are matched after percent-decoding. — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
 
 `<path>` accepts the same **agent references** the rest of the CLI does: a segment straight after `agents/` that is not already a UUID is resolved against the account's agent listing, and the substitution is announced on stderr so a `--json` stdout stream stays pure. Resolution is sugar and never breaks the hatch — a reference that does not resolve (or an agent listing that cannot be reached) leaves the path exactly as typed, because `agents/` is a route prefix as well as a collection.
 
@@ -557,7 +575,7 @@ Hand work to a remote agent as a **durable delegation** — a platform task with
 
 - `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.
+- `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 (`cinna artifacts publish` prints such a link). `--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": {…}}`.
@@ -572,6 +590,25 @@ cinna delegation report --status done --summary 'Finished'     # inside the clou
 
 Inside cloud tasks, cinna-core's MCP task server also offers a `handover_report` tool for the same report.
 
+### `cinna artifacts publish | list | show | open | download | share | link | delete`
+
+Publish a folder or a file to Cinna as an **artifact** — a frozen, versioned copy people open on a Cinna page (a folder with `index.html` runs as a sandboxed static site; other files open in viewers). Run from the account workspace. Every verb first checks the server's artifacts capability and refuses with "This Cinna server does not support artifacts" when it is missing.
+
+- `publish PATH [--title T] [--description D] [--entry index.html] [--note N]` — zips the path and prints the page link. `.git/`, `.env*`, `credentials/`, `app-data/`, `.claude/`, `.cinna/`, `node_modules/`, key files and symlinks are never uploaded; the command lists what it left out. Private until shared. Publishing the same path again adds a revision to the same artifact (same link) — the CLI remembers `path → id` in `.cinna/artifacts.json`; `--update ID` names the artifact, `--new` publishes a separate one.
+- `list [--shared]` · `show ID` (revisions, people, links) · `open ID` (browser) · `download ID [--rev N] [-o DIR]` (default `artifacts/<short-id>/`). Ids may be shortened to a unique prefix.
+- `share ID [--instance | --private] [--user EMAIL]… [--remove-user EMAIL]…` and `link create ID [--expires 7d|12h|2w|never] [--code] [--label L] [--rev N]` — **a person runs these, in a terminal**: they refuse under `--json`, `--no-input` or without a TTY (code `needs_person`), and the account workspace's `.claude/settings.json` denies them to Claude Code. `link create` prints the link (and code) once.
+- `link revoke ID LINK` (link id or token prefix, from `show`) · `delete ID` — both confirm; `--yes` is required with `--json`.
+- `--json` (after the subcommand): NDJSON progress lines, then `{"result": "ok", "artifact_id", "action", "revision", "url", "excluded", …}`.
+
+```bash
+cinna artifacts publish ./reports/q3 --title "Q3 churn"
+cinna artifacts publish ./reports/q3            # revision 2, same link
+cinna artifacts share 3fa85f64 --user bob@example.com
+cinna artifacts link create 3fa85f64 --expires 7d --code
+```
+
+The printed page link is a valid `link` artifact for `cinna delegation report --artifact`.
+
 ### `cinna dev`
 
 Start a foreground dev session — creates / resumes the Mutagen sync session for this workspace and attaches the terminal to a two-tab TUI (status + raw Mutagen details). Ctrl-C terminates the session; sync does not outlive the TUI. To observe sync from another terminal without affecting it, use `cinna sync status`.

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/README.md

@@ -449,6 +449,24 @@ Take a package out of the catalog. Agents that already installed it keep what th
 
 Put a delisted package back. `delist` has no inverse route of its own — without this verb the only way back would be `cinna api`, which would make delisting the one door in this group that opens only outwards.
 
+### `cinna agent-api access list | issue | revoke | scopes`
+
+Give people (or your own local agent) API access to a producer, from the account workspace. A key is issued to a **person** and lands in their credentials; **its value never appears in the CLI** — not on self-issue, not in `--json`. Reveal and rotate live on the web credential page, and so does the external-access switch (when it is off, `issue` is refused with the producer's Integrations URL). Writes need the `agent-developer` role.
+
+- `list <producer> [--all] [--json]` — people, their scopes and keys (prefix, status, expiry, last used, linked agents, id). Ended keys (revoked, expired, removed) are hidden unless `--all`; `--json` is always the full listing.
+- `issue <producer> --to <email|me> [--scopes a,b] [--expires-in-days N] [--service-uri SLOT] [--label TEXT] [--read-only] [--json]` — `--to` is required. `me` puts the key in your own credentials and prints the web URL where you reveal it; a local agent in Cinna Desktop calls it with `cinna_credentials.agent_api_session("<slot>")`, a cloud agent is wired with `cinna connect agent-api` instead.
+- `revoke <producer> <key> [--yes] [--json]` — `<key>` is the key id or the exact token prefix (an elided one is refused). Asks first; `--json` needs `--yes`; an already revoked key is reported, exit 0. The person's scopes stay.
+- `scopes <producer> --to <email|me> (--set a,b | --clear) [--json]` — change a grant without touching keys.
+
+```bash
+cinna agent-api access issue orders-agent --to me --service-uri orders-api
+cinna agent-api access issue orders-agent --to ana@example.com --scopes read --expires-in-days 30
+cinna agent-api access list orders-agent --all
+cinna agent-api access revoke orders-agent a1b2c3d4
+```
+
+`cinna account credentials list` shows an issued key's state in its Status column, and a skill slot filled by a revoked or expired key reads as not usable. `cinna agent import` does not draft `agent_api` credentials; it prints the `access issue` / `connect agent-api` command instead.
+
 ### `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.
@@ -471,7 +489,7 @@ Generic escape hatch into the platform API, authenticated with the account token
 
 - `--json '<obj>'` or `--data @file.json` supply a JSON request body (mutually exclusive); repeatable `--query k=v` supplies query parameters (repeating a key builds a list).
 - The inner response is passed through verbatim: the body prints to stdout (pretty-printed for JSON) and the exit code is `0` for 2xx and `1` for an inner 4xx/5xx — so it composes in shell pipelines.
-- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
+- When the escape hatch itself refuses the call, the detail prints to stderr and the exit code is `2`: policy denials (credentials, user management, admin, CLI, MFA/auth, and streaming routes are excluded, as are routes that would hand out a secret: any method on `agents/*/agent-api/keys…` (issued keys), on `environments/*/workspace/download` and `view-file`, and on `dashboards/*/blocks/*/env-file`; and POST on A2A access-tokens, MCP/ACP connector tokens, agent and task-trigger webhook create/regenerate-token. Paths are matched after percent-decoding. — shown as `blocked by platform policy: …`), rate limiting (429, with the Retry-After delay), and request/response size caps (413/502).
 
 `<path>` accepts the same **agent references** the rest of the CLI does: a segment straight after `agents/` that is not already a UUID is resolved against the account's agent listing, and the substitution is announced on stderr so a `--json` stdout stream stays pure. Resolution is sugar and never breaks the hatch — a reference that does not resolve (or an agent listing that cannot be reached) leaves the path exactly as typed, because `agents/` is a route prefix as well as a collection.
 
@@ -520,7 +538,7 @@ Hand work to a remote agent as a **durable delegation** — a platform task with
 
 - `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.
+- `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 (`cinna artifacts publish` prints such a link). `--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": {…}}`.
@@ -535,6 +553,25 @@ cinna delegation report --status done --summary 'Finished'     # inside the clou
 
 Inside cloud tasks, cinna-core's MCP task server also offers a `handover_report` tool for the same report.
 
+### `cinna artifacts publish | list | show | open | download | share | link | delete`
+
+Publish a folder or a file to Cinna as an **artifact** — a frozen, versioned copy people open on a Cinna page (a folder with `index.html` runs as a sandboxed static site; other files open in viewers). Run from the account workspace. Every verb first checks the server's artifacts capability and refuses with "This Cinna server does not support artifacts" when it is missing.
+
+- `publish PATH [--title T] [--description D] [--entry index.html] [--note N]` — zips the path and prints the page link. `.git/`, `.env*`, `credentials/`, `app-data/`, `.claude/`, `.cinna/`, `node_modules/`, key files and symlinks are never uploaded; the command lists what it left out. Private until shared. Publishing the same path again adds a revision to the same artifact (same link) — the CLI remembers `path → id` in `.cinna/artifacts.json`; `--update ID` names the artifact, `--new` publishes a separate one.
+- `list [--shared]` · `show ID` (revisions, people, links) · `open ID` (browser) · `download ID [--rev N] [-o DIR]` (default `artifacts/<short-id>/`). Ids may be shortened to a unique prefix.
+- `share ID [--instance | --private] [--user EMAIL]… [--remove-user EMAIL]…` and `link create ID [--expires 7d|12h|2w|never] [--code] [--label L] [--rev N]` — **a person runs these, in a terminal**: they refuse under `--json`, `--no-input` or without a TTY (code `needs_person`), and the account workspace's `.claude/settings.json` denies them to Claude Code. `link create` prints the link (and code) once.
+- `link revoke ID LINK` (link id or token prefix, from `show`) · `delete ID` — both confirm; `--yes` is required with `--json`.
+- `--json` (after the subcommand): NDJSON progress lines, then `{"result": "ok", "artifact_id", "action", "revision", "url", "excluded", …}`.
+
+```bash
+cinna artifacts publish ./reports/q3 --title "Q3 churn"
+cinna artifacts publish ./reports/q3            # revision 2, same link
+cinna artifacts share 3fa85f64 --user bob@example.com
+cinna artifacts link create 3fa85f64 --expires 7d --code
+```
+
+The printed page link is a valid `link` artifact for `cinna delegation report --artifact`.
+
 ### `cinna dev`
 
 Start a foreground dev session — creates / resumes the Mutagen sync session for this workspace and attaches the terminal to a two-tab TUI (status + raw Mutagen details). Ctrl-C terminates the session; sync does not outlive the TUI. To observe sync from another terminal without affecting it, use `cinna sync status`.

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/docs/README.md

@@ -292,13 +292,15 @@ authoring convention.
 | **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` (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 API** | `cinna agent-api` (enable, refresh, spec, call, access list/issue/revoke/scopes) · `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 — 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) |
+| **Git versioning** | `cinna git` (link, status, commit, push, pull, log, checkout, unlink) — external remotes with your own credentials, `cinna` remotes with the CLI token | [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) |
+| **Artifacts** | `cinna artifacts` (publish — republishes a remembered path, `--new` / `--update`; list, show, open, download, share and link create — person-only, refused without a TTY; link revoke, delete), gated on the server's artifacts capability | [business](features/artifacts/artifacts.md) · [tech](features/artifacts/artifacts_tech.md) · [acceptance](features/artifacts/artifacts_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) |
+| **Team library** | `cinna library` (list, get, share, update, status, grants, suggest) — kit folders in `Local/<slug>/` shared through cinna-core-hosted git with the account token; `cinna agent import --from-library` | [business](features/team_library/team_library.md) · [tech](features/team_library/team_library_tech.md) · [acceptance](features/team_library/team_library_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

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/docs/features/account_workspace/account_workspace.md

@@ -156,7 +156,12 @@ each with its own token, registry entry, and Mutagen session.
   step; `--workspace` overrides the target workspace.
 - `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
+  metadata only. For an issued Agent API key the Status cell shows the key's
+  state instead (Active; API turned off by producer / External access paused;
+  Revoked by issuer / Producer removed / Issuer account removed / Expired), and
+  `agent show` appends it when not active. A draft with `--type agent_api` is
+  refused by the platform: such a credential has no key behind it; use
+  `cinna agent-api access issue` (see [agent_api](../agent_api/agent_api.md)). 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
@@ -214,7 +219,9 @@ each with its own token, registry entry, and Mutagen session.
   orchestrator/child `CLAUDE.md` regeneration is offline and per-workspace, so one
   unreadable child never aborts the rest.
 - **User-edited config is preserved.** `.claude/settings.json` is create-if-absent
-  (never clobbered on refresh); `.mcp.json` / `opencode.json` and the generated
+  (never clobbered on refresh; an existing file only gains the two `deny` rules
+  that keep `cinna artifacts share` / `link create` away from Claude Code — see
+  [Artifacts](../artifacts/artifacts.md)); `.mcp.json` / `opencode.json` and the generated
   `CLAUDE.md` are auto-generated infra and are overwritten.
 - **Child checkouts are standard.** A synced child is identical to a `cinna setup`
   checkout — same Model-A layout, same auto-link when git-versioned, same

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/docs/features/account_workspace/account_workspace_acceptance.md

@@ -53,7 +53,9 @@ the silent-secret and scope-drift bugs live.
   `account_token` / `platform_url` / `frontend_url` / `machine_name`; an empty
   `agents/` dir; an orchestrator `CLAUDE.md` (contains "Account Workspace");
   `.claude/settings.json` with `permissions.allow == ["Bash(cinna:*)",
-  "mcp__platform-knowledge"]` and `enableAllProjectMcpServers: true`; `.mcp.json`
+  "mcp__platform-knowledge"]`, `permissions.deny == ["Bash(cinna artifacts
+  share:*)", "Bash(cinna artifacts link create:*)"]` and
+  `enableAllProjectMcpServers: true`; `.mcp.json`
   + `opencode.json` pointing the proxy at `.cinna/account.json` via
   `CINNA_ACCOUNT_CONFIG`; a `context/` tree; and the next-step hints
   (`cinna account agents`, `cinna agent sync`).
@@ -226,7 +228,8 @@ the silent-secret and scope-drift bugs live.
 - **Expected:** `context/` is replaced (old-only files gone); the orchestrator
   `CLAUDE.md`, `.mcp.json`/`opencode.json`, and **every** synced child's
   per-agent `CLAUDE.md` are regenerated from the bundled templates; a
-  user-edited `.claude/settings.json` is left untouched; the run reports how many
+  user-edited `.claude/settings.json` keeps every entry and only gains the
+  artifact `deny` rules it lacks; the run reports how many
   child workspaces were regenerated.
 - **Watch for (non-destructive rule):** simulate a download failure (point at an
   unreachable platform) and confirm the **old `context/` survives** and the
@@ -388,7 +391,8 @@ the silent-secret and scope-drift bugs live.
 - **Single-use setup token is never burned on a doomed run** — guards precede the
   exchange.
 - **No silent clobber** — `refresh-context` removes the old `context/` only after
-  a successful download; user-edited `.claude/settings.json` is never overwritten.
+  a successful download; user-edited `.claude/settings.json` is never overwritten
+  (only the missing artifact `deny` rules are merged in).
 - **No state drift between commands** — a synced child is a standard per-agent
   workspace (registry + config) indistinguishable from `cinna setup`; the active
   user workspace is the single source for both the listing scope and the create

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/docs/features/account_workspace/account_workspace_tech.md

@@ -216,6 +216,26 @@ 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:_key_status_cell()` / `_KEY_STATUS_LABELS` — an issued
+  key's status as a coloured label; `run_credentials_list()` uses it in place of
+  the complete / needs-setup cell when `agent_api_key_status` is set, and
+  `_credential_summary()` appends it when not `active`.
+  `agent_api_key_status` is in `_ACCOUNT_AUTHORITATIVE_FIELDS`, so linked-credential
+  overlays carry it. (`tests/test_account.py`)
+- Skill slot readiness: `src/cinna/account.py:_slot_readiness()` treats a filled
+  carrier whose key status is not `active` as unusable and returns
+  `key_revoked` (revoked_by_issuer / producer_removed / issuer_removed),
+  `key_expired`, `key_paused` (api_disabled / external_access_paused) or
+  `key_unavailable` (a status this CLI does not know), via
+  `_key_unavailable_state()` / `_dead_key_carrier()` (every filled carrier of the
+  slot, of the declared type, holds a dead or paused key). A newer platform
+  flags such a slot itself as `access_revoked`; the CLI refines that reason to the
+  key state so the remedy fits. An older platform names no issue for catalog rows,
+  so the CLI checks key status there too. `_needs_linked_credentials()` fetches
+  the linked credentials for catalog rows with an `access_revoked` issue or an
+  unflagged declared slot. `_slot_remedy()` words the fix: ask the producer's owner
+  for a new key (`agent_api_issue_hint()`) for revoked/expired, "recovers by
+  itself" for paused, upgrade the CLI for unknown.
 - `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
@@ -324,7 +344,9 @@ All consumed by `src/cinna/client.py:AccountClient` with the account token
   `CLAUDE.md` regeneration is independent of the download.
   (`tests/test_account.py:test_refresh_context_failure_preserves_old_tree`)
 - **Settings is create-if-absent** — `_write_account_claude_settings` never
-  clobbers a user-edited `.claude/settings.json`.
+  clobbers a user-edited `.claude/settings.json`; it only appends the missing
+  `artifacts.person_only_deny_rules()` to `permissions.deny`, and leaves a file
+  that is not a JSON object alone.
   (`tests/test_account.py:test_refresh_context_preserves_user_claude_settings`)
 - **Per-agent URL is rejected** — `parse_account_setup_input` must not silently
   accept a `/cli-setup/<token>` (non-account) URL.

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/docs/features/agent_api/agent_api.md

@@ -5,7 +5,7 @@
 Let an agent **expose its own HTTP/OpenAPI surface** (a "producer" REST API)
 that another agent (a "consumer") can call, and give a coding agent the local
 loop to build, verify, and wire those connections from the account workspace:
-`cinna agent-api` (enable / refresh / spec / call) drives the
+`cinna agent-api` (enable / refresh / spec / call / access) drives the
 **build→verify** loop on a producer; `cinna connect agent-api` does the
 **one-click wiring** of a consumer to it; and `cinna api` is a separate
 **escape hatch** for calling the platform's *own* control-plane API directly.
@@ -67,7 +67,8 @@ to test a producer endpoint — use `cinna agent-api call`.
   consumer authenticates its real calls with it.
 - **Escape hatch** — the account `api-proxy` route `cinna api` rides: a buffered
   JSON pass-through to the platform's own API, with excluded categories
-  (credentials, user management, admin, CLI, MFA/auth, streaming) denied.
+  (credentials, user management, admin, CLI, MFA/auth, streaming, and the
+  secret-minting routes listed under "Escape-hatch deny-list") denied.
 
 ## User flows
 
@@ -97,6 +98,35 @@ to test a producer endpoint — use `cinna agent-api call`.
   appears read-only under `workspace/credentials/` in a synced workspace) —
   no manual key handling.
 
+### Give API access (a person, or a local agent)
+- `cinna agent-api access list <producer>` shows who has access: one row per
+  person with their scopes and keys (prefix, status, expiry, last use, how many
+  agents use it, key id). `--all` also shows ended keys; `--json` is always the
+  full listing. The footer says whether external access is on and which scopes
+  the producer declares.
+- `cinna agent-api access issue <producer> --to <email|me>` issues a key to a
+  person. `--scopes a,b` sets their scopes (`""` = an explicit empty grant),
+  `--expires-in-days N` (1-3650), `--service-uri SLOT` names the credential's
+  slot (default `<producer>-api`), `--label`, `--read-only`.
+  - `--to me`: the key lands in your own credentials; the output names the slot
+    and the web credential page where you reveal the value. A local agent
+    (Cinna Desktop) then calls it by slot; a cloud agent is wired with
+    `cinna connect agent-api` instead.
+  - `--to <email>`: the key lands in that person's credentials; you never see
+    the value. The output prints the revoke command.
+  - Scopes outside the producer's declared catalog are stored anyway, with a
+    warning.
+- `cinna agent-api access revoke <producer> <key>` ends one key (asks first,
+  `--yes` skips). The person's scopes stay, so a new key can be issued without
+  re-granting.
+- `cinna agent-api access scopes <producer> --to <email|me> --set a,b | --clear`
+  changes a person's scopes without touching their keys, so a working key keeps
+  working. `--clear` removes the grant.
+- The result shows up elsewhere: `cinna account credentials list` shows the
+  key's status in the Status column, and a skill slot filled by a dead key
+  reads as not usable (see
+  [account_workspace](../account_workspace/account_workspace.md)).
+
 ### Call the platform's own API (unrelated to producer APIs)
 - `cinna api GET agents`, `cinna api POST agents/<id>/duplicate`,
   `cinna api PATCH agents/<id> --json '{…}'` — `PATH` is relative to the API
@@ -132,7 +162,8 @@ to test a producer endpoint — use `cinna agent-api call`.
   its own refusal from a mirrored inner error by a marker response header.
 - **Escape-hatch deny-list.** `cinna api` cannot reach credentials, user
   management, admin, CLI, MFA/auth, or streaming routes — the platform denies
-  them; don't waste calls.
+  them; don't waste calls. It also refuses routes that would hand out a secret:
+  any method on `agents/*/agent-api/keys…` (issued keys), on `environments/*/workspace/download` and `view-file`, and on `dashboards/*/blocks/*/env-file`; and POST on A2A access-tokens, MCP/ACP connector tokens, agent and task-trigger webhook create/regenerate-token. Paths are matched after percent-decoding. These refuse with 403 `excluded_path` (exit 2). Prefix-only listings stay reachable.
 - **An elided id is refused locally.** A path segment carrying `…` or `...` is
   an id copied out of a table cell too narrow to print it whole. It reaches the
   API as a well-formed path and comes back `404 Agent not found` — a sentence
@@ -150,6 +181,37 @@ to test a producer endpoint — use `cinna agent-api call`.
 - **No secret round-trip.** `connect agent-api` mints the producer token
   server-side and attaches it as a consumer credential; the secret value never
   passes through the CLI as something the user pastes or stores locally.
+- **A key value never crosses the CLI.** The platform sends none on the access
+  routes, the client drops any stray `token` field, and every runner drops it
+  again before printing or `--json`. Self-issue returns a web URL where the
+  person reveals the value; nobody should paste one into the CLI.
+- **Rotate and reveal are web-only.** Rotation replaces a value someone outside
+  the platform holds, which the CLI could not hand over, and a coding agent
+  could otherwise start a countdown that breaks every holder of the old value.
+  There is no verb for either.
+- **The external-access switch is web-only.** It is the deliberate human act
+  that exposes the API outside the platform. When it is off, `issue` is refused
+  with `external_access_disabled` and the producer's Integrations URL is
+  appended to the message (only when the platform's message lacks one); `list`
+  warns and prints the same URL.
+- **Terminal keys are hidden unless `--all`.** Revoked, producer/issuer removed
+  and expired keys drop out of the `access list` table with a footer count;
+  `--json` always carries everything.
+- **`--to` is required on `issue` and `scopes`.** The recipient is always a
+  deliberate choice: an email (resolved server-side, exact case-insensitive
+  match among active users) or `me`. An unknown email is refused, and one that
+  matches several accounts is refused as ambiguous rather than guessed.
+- **A key reference is a key id or the exact token prefix.** A reference
+  carrying an elision marker is refused locally (same rule as other ids); no
+  match or several matches fail with a candidate listing. Revoking an
+  already-revoked key is a no-op that exits 0 ("already revoked"); `--json`
+  requires `--yes`.
+- **Only the producer's owner (or an admin) manages access, and writes need
+  the developer role.** A producer that is missing or not yours reads as not
+  found. `list` is open to any account token.
+- **The generic escape hatch cannot issue keys.** `cinna api POST
+  agents/<id>/agent-api/keys` is refused (exit 2); the `access` verbs are the
+  only CLI way.
 - **Read-only is a connect-time choice.** `--read-only` is applied when the
   connection is created; it scopes the *consumer's* access, not the producer's
   surface.
@@ -169,6 +231,15 @@ build/verify (producer):
         ▼                                                      producer's env)
   agent-api call ─► owner-preview proxy ─► producer endpoint (no consumer token)
 
+people access (issued keys and scopes):
+  cinna agent-api access list/issue/revoke/scopes
+        │  account token
+        ▼
+  /api/v1/cli/account/agent-api/{access,keys,keys/revoke,access/scopes}
+        │ key lands in the recipient's credentials (value never returned)
+        ▼
+  recipient reveals it on the web; a local agent calls it by slot
+
 wiring (consumer):
   cinna connect agent-api --producer A --consumer B
         │  account token
@@ -195,6 +266,14 @@ platform escape hatch (unrelated target):
 - **Remote sync / exec** — authoring a producer API means editing files in the
   producer's synced `workspace/agent_api/` and pushing them to the running env
   (`cinna dev` / `cinna exec`); the spec is harvested from that env.
+- **Account workspace credentials and skill slots** — an issued key is a
+  credential whose listing row carries its key status; skill slot readiness
+  treats a revoked, expired or paused key as not usable. See
+  [account_workspace](../account_workspace/account_workspace.md).
+- **Local agent import** — `cinna agent import` never drafts an `agent_api`
+  credential (it could never be used); it attaches an existing same-name one or
+  prints the `access issue` / `connect agent-api` command. See
+  [local_agent_import](../local_agent_import/local_agent_import.md).
 - **`cinna agent show`** — surfaces a producer's live `agent_api_status`
   alongside its prompts and credentials, reusing the same status renderer.
 

{cinna_cli-0.5.1 → cinna_cli-0.5.3}/docs/features/agent_api/agent_api_acceptance.md

@@ -21,7 +21,7 @@ for** failure modes.
 - **Editable install** of the CLI under test:
   `python3 -c "import cinna,os;print(os.path.dirname(cinna.__file__))"` must
   point at this repo's `src/cinna`. Confirm `which cinna` resolves and
-  `cinna agent-api --help` lists `enable / refresh / spec / call`.
+  `cinna agent-api --help` lists `enable / refresh / spec / call / access`.
 - **A producer agent** you own whose workspace has (or will have) an
   `agent_api/` package + `policy.yaml`. Ideally synced locally
   (`cinna agent sync <producer>`) so you can edit + push the endpoint code.
@@ -196,6 +196,111 @@ for** failure modes.
 - **Watch for:** trying to test a producer endpoint via `cinna api` (wrong
   target — it calls platform routes, not the producer's served API).
 
+### 13. Issue yourself a key: URL, never a value
+
+- **Goal:** a builder gives themselves API access to a producer and never sees
+  the key value.
+- **Setup:** the producer's REST API is enabled; turn **external access** on in
+  the web (Integrations tab of the producer). It is web-only by design.
+- **Steps:**
+  ```
+  cinna agent-api access issue "<Producer>" --to me
+  cinna account credentials list
+  cinna agent-api access list "<Producer>"
+  ```
+- **Expected:** `Key <prefix> is in your credentials as slot <producer>-api …`
+  with a `…/credential/<id>` URL and the `cinna_credentials.agent_api_session`
+  hint; the output contains no key value. `credentials list` shows the new row
+  with Status `Active`; `access list` shows you with that key as Active.
+- **Watch for:** any full key or `token` field in the output (also with
+  `--json`); the credentials row showing `complete` instead of the key status.
+
+### 14. External access off refuses with the URL
+
+- **Goal:** issuing is fail-loud while external access is off.
+- **Setup:** turn external access off in the web.
+- **Steps:**
+  ```
+  cinna agent-api access issue "<Producer>" --to me; echo "exit=$?"
+  cinna agent-api access list "<Producer>"
+  ```
+- **Expected:** non-zero exit; the message says external access is disabled and
+  ends with `…/agent/<id>#integrations` (once, not doubled). `access list`
+  prints `External access: off` and a warning with the same URL. Turn it back on
+  before scenario 15.
+- **Watch for:** a generic error without the URL; any CLI path that switches it
+  on.
+
+### 15. Issue to another person, scopes, and list
+
+- **Goal:** give a colleague a scoped key without ever seeing it.
+- **Steps:**
+  ```
+  cinna agent-api access issue "<Producer>" --to <other-email> --scopes read --expires-in-days 30 --label qa
+  cinna agent-api access scopes "<Producer>" --to <other-email> --set read,write
+  cinna agent-api access list "<Producer>"
+  cinna agent-api access list "<Producer>" --json
+  cinna agent-api access issue "<Producer>" --to nobody@example.invalid; echo "exit=$?"
+  cinna agent-api access issue "<Producer>" --to nobody@example.invalid --json; echo "exit=$?"
+  ```
+- **Expected:** `Issued key <prefix> to <other-email>. It lands in their
+  credentials; you never see its value.` plus the revoke command. The scopes
+  command prints the person's resulting scopes and the key keeps working. The
+  table shows the person, scopes, key prefix, status, expiry, last used, linked
+  agent count and key id; `--json` is the full payload with no `token`
+  anywhere. The unknown recipient is refused and nothing is issued: the plain
+  run prints the server's sentence on stderr, and the `--json` run prints one
+  `{"result": "error", "code": "recipient_not_found", …}` line on stdout. Both
+  exit 1. An undeclared scope prints a warning but is stored.
+- **Watch for:** `--to` omitted not being a usage error; a key value in any
+  output; the scopes change revoking or replacing the key.
+
+### 16. Revoke: hidden by default, visible with `--all`, recipient sees it
+
+- **Goal:** revoking ends one key, keeps the grant, and is visible on both sides.
+- **Steps:**
+  ```
+  cinna agent-api access revoke "<Producer>" <prefix>          # answer n first, then y
+  cinna agent-api access list "<Producer>"
+  cinna agent-api access list "<Producer>" --all
+  cinna agent-api access revoke "<Producer>" <prefix> --yes     # again
+  cinna agent-api access revoke "<Producer>" <prefix> --json    # no --yes
+  ```
+  Then check the recipient's side. A recipient who is a developer can use their
+  own account workspace:
+  ```
+  cinna account credentials list
+  ```
+  An agent-user cannot create an account workspace (setup tokens are
+  developer-only), so for them sign in to the web app as the recipient and open
+  **Credentials**, or call `GET /api/v1/credentials` with their token and read
+  `agent_api_key_status`.
+- **Expected:** declining sends nothing; accepting prints `Revoked key <prefix>
+  issued to <email>. Status: Revoked by issuer`. The default list hides the key
+  with `1 ended key hidden (--all)` while the person's scopes row stays;
+  `--all` shows `Revoked by issuer`. Revoking again prints `already revoked`
+  and exits 0. `--json` without `--yes` is a usage error. The recipient still
+  has the credential, with Status `Revoked by issuer` (`agent_api_key_status:
+  revoked_by_issuer` in the API).
+- **Watch for:** the grant disappearing with the key; an elided prefix
+  (`ab12…`) not being refused locally; the recipient's credential being
+  deleted rather than flagged.
+
+### 17. The escape hatch cannot mint keys
+
+- **Goal:** `cinna api` is not a back door around the no-value rule.
+- **Steps:**
+  ```
+  cinna api POST agents/<producer-id>/agent-api/keys --json '{"label":"x"}'; echo "exit=$?"
+  cinna api GET agents/<producer-id>/agent-api/access; echo "exit=$?"
+  cinna agent-api access list "<Producer>"
+  ```
+- **Expected:** the POST prints `blocked by platform policy: …` on stderr and
+  exits 2; no key was created (the list is unchanged). The `access` GET through
+  the hatch is still reachable. The same refusal (403 `excluded_path`, exit 2)
+  applies to any method on `agents/*/agent-api/keys…`, `environments/*/workspace/download` and `view-file`, `dashboards/*/blocks/*/env-file`, and POST on token-minting routes (A2A access-tokens, MCP/ACP connector tokens, webhook create/regenerate-token), including percent-encoded spellings.
+- **Watch for:** exit 1 instead of 2; a key created by the call.
+
 ## Cross-cutting invariants (must hold across all scenarios)
 
 - **Resolve-before-mutate.** A bad agent ref fails before any enable / refresh /
@@ -209,6 +314,8 @@ for** failure modes.
   both `agent-api call` and `cinna api`; only `cinna api` adds exit 2 for the
   hatch's own refusal (policy / rate limit / size cap), distinguished by the
   marker header — never conflated with an inner 4xx.
+- **No key value in any access output.** Not in the table, not in `--json`,
+  not on self-issue; reveal and rotate are web-only.
 - **Spec is pipeable.** `cinna agent-api spec` emits plain JSON to stdout (or the
   `-o` file), never Rich-decorated.
 
@@ -221,4 +328,8 @@ for** failure modes.
   `cinna agent-api enable "<Producer>" --disable`.
 - Remove any deliberately-broken `agent_api/` edits (revert + sync), then
   `cinna agent-api refresh` to restore a clean harvested spec.
+- Revoke test keys (`cinna agent-api access revoke "<Producer>" <prefix> --yes`),
+  clear test grants (`cinna agent-api access scopes "<Producer>" --to <email>
+  --clear`), delete the revoked credentials in the web, and set external access
+  back to its prior state.
 - Delete scratch files written by `cinna agent-api spec -o spec.json`.