cinna-cli 0.5.2__tar.gz → 0.6.0__tar.gz

{cinna_cli-0.5.2 → cinna_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.5.2
+Version: 0.6.0
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli
@@ -405,6 +405,8 @@ At a terminal that preview is shown and confirmed before the press; `--yes`, `--
 
 A re-publish appends a revision to the same package, so `--package-id` (the reverse-DNS id, e.g. `com.acme.report`) is only for a first publish — a mismatch on a later one is refused rather than silently ignored. `--visibility` is likewise honoured on a first publish and on an explicit change; omitting it leaves the package as it is. `--grant` requires `--visibility users` and the CLI refuses the combination otherwise, before anything is written. The server would accept it — it stores the grant either way — but a package that is private or public never consults its grant list, so the publish would report success and share nothing, and a revision cannot be taken back. Within a `users` package `--grant` is strictly **additive**: it adds the addresses it names and never revokes the ones it omits (revoking is `cinna skills revoke`, so a stale publish cannot silently remove access), and an unknown address fails the whole publish rather than half-sharing it. On success the package id, revision and its version, visibility and catalog URL are printed, plus a line saying the version landed in `skills/<name>/SKILL.md` — and a warning instead when it could not be written there, because the header and the catalog have then diverged and the next publish continues from the catalog. A refusal is printed as the platform's own sentence with its code (`not_developer`, `foreign_install`, `no_environment`, `workspace_unavailable`, `package_id_immutable`, `skill_contains_secrets` — which also lists the offending files), and `--json` prints `{revision, package, catalog_url, skill_md_updated}` instead of the human block (`--dry-run --json` prints the preview payload).
 
+**A publish from the CLI is never refused as stale.** It goes through the agent path, which records the package's latest revision as the new one's base (`cinna skills revisions` shows it under **Based on**), so another maintainer's newer version is built on, not checked against. Cinna Desktop's Share instead sends the base its folder holds, and core refuses that share (`stale_base`) when a co-maintainer has shared a newer version since; the CLI never makes that call.
+
 ### `cinna skills catalog [--search Q] [--mine] [--json]`
 
 Browse the instance skills catalog: one row per package this account may see, with its reverse-DNS **package id**, display name, visibility and newest version. The package id — `com.acme.pdf-report`, not a UUID — is the reference every other package verb takes. A delisted package is marked as such beside its visibility.
@@ -417,7 +419,7 @@ One package in full: its display name, visibility, newest version and package UU
 
 ### `cinna skills revisions <package> [--json]`
 
-A package's revisions, **newest first**: number, version, release date, size and the release notes given at publish time. A revision is immutable, so this is the question a publisher has before every publish — what is already out there — and the answer to it no longer requires `cinna api` and a UUID. Pair it with `cinna skills publish <agent> <name> --dry-run`, which says what the *next* one would be.
+A package's revisions, **newest first**: number, version, release date, size, **Shared by** (who published it, `—` once that account is deleted), **Based on** (`Version N`, the revision the sharer's copy held; `—` for a first revision, a share from an older Cinna Desktop, and any revision published before core recorded it) and the release notes given at publish time. A server older than skill co-maintainers sends neither field and both columns read `—`. `--json` passes the server's `published_by` and `base_revision_number` through untouched. A revision is immutable, so this is the question a publisher has before every publish — what is already out there — and the answer to it no longer requires `cinna api` and a UUID. Pair it with `cinna skills publish <agent> <name> --dry-run`, which says what the *next* one would be.
 
 ### `cinna skills files <package> [--revision N] [--json]`
 
@@ -575,7 +577,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": {…}}`.
@@ -590,6 +592,45 @@ 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 dashboards list | show | check | run | ref | boards | board create | add | tiles | tile …`
+
+Build, check, run and place an agent's **dashboard components**: folders in the agent's `dashboards/<name>/` (`component.json` plus endpoint scripts or a page) that the owner keeps as live tiles on a dashboard. Run from the account workspace. `AGENT` is a name, slug, id, or `.` for the agent workspace you are in. Every verb first checks the server's dashboards capability. While an environment wakes, verbs retry for `--timeout` seconds (default 120). Verbs that read the agent's cloud copy push your pending local edits first (`--no-flush` skips that).
+
+- `list AGENT` · `show AGENT NAME [--skill S]` (`--skill` names a component a skill ships, on every verb that takes `NAME`): the components as the environment sees them (checker findings, where each is placed, including "Cinna Desktop") and the **reference** line `cinna://component/bundle:<bundle_id>/<name>` that offers one.
+- `check AGENT [NAME] [--run]`: the owner's card checks; `--run` also runs each source in the environment through `cinna exec` (never locally). Exits 1 on any error.
+- `run AGENT NAME [--endpoint E] [--param k=v]… [--params @file.json]`: run it exactly as a tile would. `--json` prints `{result, value, params_resolved, notice, fetched_at}`, where `value` is exactly what a tile receives.
+- `ref AGENT NAME [--check]`: print only the reference line; `--check` asks core whether it resolves.
+- `boards` · `board create NAME` · `add AGENT NAME --board B [--new-board] [--size s|m|l|wide|tall] [--param k=v] [--title T] [--max-age 15m] [--every 5m|manual] [--after-turn]`: the owner's web dashboards; place a tile (refused for a component with errors or a full dashboard).
+- `tiles BOARD` · `tile data|refresh|params|call|edit|remove BOARD TILE …`: read and drive tiles. `tile params --set/--clear/--reset` sends the whole set; `tile edit` changes title (`''` resets it), size and refresh overrides. Tiles on Cinna Desktop's dashboards are read-only here.
+- `cinna chat --agent AGENT --board B [--focus TILE] [--context @file.json] [--new-chat] "…"`: talk in the agent's dashboard chat, where it has its tile tools.
+
+```bash
+cinna dashboards check crm-agent deals --run
+cinna dashboards run crm-agent deals --param stage=won
+cinna dashboards ref crm-agent deals --check
+cinna dashboards add crm-agent deals --board Sales --size l
+cinna chat --agent crm-agent --board Sales --focus deals "Show only won deals"
+```
+
 ### `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.2 → cinna_cli-0.6.0}/README.md

@@ -368,6 +368,8 @@ At a terminal that preview is shown and confirmed before the press; `--yes`, `--
 
 A re-publish appends a revision to the same package, so `--package-id` (the reverse-DNS id, e.g. `com.acme.report`) is only for a first publish — a mismatch on a later one is refused rather than silently ignored. `--visibility` is likewise honoured on a first publish and on an explicit change; omitting it leaves the package as it is. `--grant` requires `--visibility users` and the CLI refuses the combination otherwise, before anything is written. The server would accept it — it stores the grant either way — but a package that is private or public never consults its grant list, so the publish would report success and share nothing, and a revision cannot be taken back. Within a `users` package `--grant` is strictly **additive**: it adds the addresses it names and never revokes the ones it omits (revoking is `cinna skills revoke`, so a stale publish cannot silently remove access), and an unknown address fails the whole publish rather than half-sharing it. On success the package id, revision and its version, visibility and catalog URL are printed, plus a line saying the version landed in `skills/<name>/SKILL.md` — and a warning instead when it could not be written there, because the header and the catalog have then diverged and the next publish continues from the catalog. A refusal is printed as the platform's own sentence with its code (`not_developer`, `foreign_install`, `no_environment`, `workspace_unavailable`, `package_id_immutable`, `skill_contains_secrets` — which also lists the offending files), and `--json` prints `{revision, package, catalog_url, skill_md_updated}` instead of the human block (`--dry-run --json` prints the preview payload).
 
+**A publish from the CLI is never refused as stale.** It goes through the agent path, which records the package's latest revision as the new one's base (`cinna skills revisions` shows it under **Based on**), so another maintainer's newer version is built on, not checked against. Cinna Desktop's Share instead sends the base its folder holds, and core refuses that share (`stale_base`) when a co-maintainer has shared a newer version since; the CLI never makes that call.
+
 ### `cinna skills catalog [--search Q] [--mine] [--json]`
 
 Browse the instance skills catalog: one row per package this account may see, with its reverse-DNS **package id**, display name, visibility and newest version. The package id — `com.acme.pdf-report`, not a UUID — is the reference every other package verb takes. A delisted package is marked as such beside its visibility.
@@ -380,7 +382,7 @@ One package in full: its display name, visibility, newest version and package UU
 
 ### `cinna skills revisions <package> [--json]`
 
-A package's revisions, **newest first**: number, version, release date, size and the release notes given at publish time. A revision is immutable, so this is the question a publisher has before every publish — what is already out there — and the answer to it no longer requires `cinna api` and a UUID. Pair it with `cinna skills publish <agent> <name> --dry-run`, which says what the *next* one would be.
+A package's revisions, **newest first**: number, version, release date, size, **Shared by** (who published it, `—` once that account is deleted), **Based on** (`Version N`, the revision the sharer's copy held; `—` for a first revision, a share from an older Cinna Desktop, and any revision published before core recorded it) and the release notes given at publish time. A server older than skill co-maintainers sends neither field and both columns read `—`. `--json` passes the server's `published_by` and `base_revision_number` through untouched. A revision is immutable, so this is the question a publisher has before every publish — what is already out there — and the answer to it no longer requires `cinna api` and a UUID. Pair it with `cinna skills publish <agent> <name> --dry-run`, which says what the *next* one would be.
 
 ### `cinna skills files <package> [--revision N] [--json]`
 
@@ -538,7 +540,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": {…}}`.
@@ -553,6 +555,45 @@ 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 dashboards list | show | check | run | ref | boards | board create | add | tiles | tile …`
+
+Build, check, run and place an agent's **dashboard components**: folders in the agent's `dashboards/<name>/` (`component.json` plus endpoint scripts or a page) that the owner keeps as live tiles on a dashboard. Run from the account workspace. `AGENT` is a name, slug, id, or `.` for the agent workspace you are in. Every verb first checks the server's dashboards capability. While an environment wakes, verbs retry for `--timeout` seconds (default 120). Verbs that read the agent's cloud copy push your pending local edits first (`--no-flush` skips that).
+
+- `list AGENT` · `show AGENT NAME [--skill S]` (`--skill` names a component a skill ships, on every verb that takes `NAME`): the components as the environment sees them (checker findings, where each is placed, including "Cinna Desktop") and the **reference** line `cinna://component/bundle:<bundle_id>/<name>` that offers one.
+- `check AGENT [NAME] [--run]`: the owner's card checks; `--run` also runs each source in the environment through `cinna exec` (never locally). Exits 1 on any error.
+- `run AGENT NAME [--endpoint E] [--param k=v]… [--params @file.json]`: run it exactly as a tile would. `--json` prints `{result, value, params_resolved, notice, fetched_at}`, where `value` is exactly what a tile receives.
+- `ref AGENT NAME [--check]`: print only the reference line; `--check` asks core whether it resolves.
+- `boards` · `board create NAME` · `add AGENT NAME --board B [--new-board] [--size s|m|l|wide|tall] [--param k=v] [--title T] [--max-age 15m] [--every 5m|manual] [--after-turn]`: the owner's web dashboards; place a tile (refused for a component with errors or a full dashboard).
+- `tiles BOARD` · `tile data|refresh|params|call|edit|remove BOARD TILE …`: read and drive tiles. `tile params --set/--clear/--reset` sends the whole set; `tile edit` changes title (`''` resets it), size and refresh overrides. Tiles on Cinna Desktop's dashboards are read-only here.
+- `cinna chat --agent AGENT --board B [--focus TILE] [--context @file.json] [--new-chat] "…"`: talk in the agent's dashboard chat, where it has its tile tools.
+
+```bash
+cinna dashboards check crm-agent deals --run
+cinna dashboards run crm-agent deals --param stage=won
+cinna dashboards ref crm-agent deals --check
+cinna dashboards add crm-agent deals --board Sales --size l
+cinna chat --agent crm-agent --board Sales --focus deals "Show only won deals"
+```
+
 ### `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.2 → cinna_cli-0.6.0}/docs/README.md

@@ -25,7 +25,8 @@ The platform also handles scheduling, triggers, email, A2A, MCP serving, and ses
 - Testing credential integrations (keys and tokens stay on the platform, exercised by the remote env)
 - Installing and validating Python / system packages
 - Writing and iterating on prompt files
-- Building webapp dashboards and data endpoints
+- Building the agent's webapp and data endpoints
+- Building dashboard components, checking and running them in the env, placing them as tiles
 - Preparing output files and reports
 
 ### What stays in the cloud
@@ -56,6 +57,10 @@ The live-sync rewrite removes the local container entirely. Mutagen keeps the wo
 
 A self-contained automation unit on the platform. Has a name, template, scripts, prompts, webapp, credentials, and a knowledge base. Identified by `agent_id`.
 
+### Dashboard component
+
+A live view an agent keeps in `dashboards/<name>/` (`component.json` plus endpoint scripts or a page). The owner places it as a **tile** on a dashboard (core's web dashboards, or Cinna Desktop); the agent offers it by printing its reference `cinna://component/bundle:<bundle_id>/<name>`. It runs only in the agent's environment. See [Dashboards](features/dashboards/dashboards.md).
+
 ### Environment
 
 The runtime container configuration for an agent on the platform. Each agent has exactly one environment. Environments may be suspended when idle; opening a sync WebSocket auto-activates them.
@@ -297,6 +302,8 @@ authoring convention.
 | **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) — 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) |
+| **Dashboards** | `cinna dashboards` (list, show, check `[--run]`, run, ref `[--check]` — an agent's components as its environment sees them; boards, board create, add, tiles, tile data / refresh / params / call / edit / remove — tiles on the owner's web dashboards, desktop dashboards read-only) · `cinna chat --board [--focus] [--context] [--new-chat]` (dashboard chat with the tile tools); gated on the server's dashboards capability | [business](features/dashboards/dashboards.md) · [tech](features/dashboards/dashboards_tech.md) · [acceptance](features/dashboards/dashboards_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) |
@@ -525,6 +532,8 @@ The platform's send-message route (`POST /sessions/{id}/messages/stream`) return
 3. Records the current message count as a cursor, then sends the message (`file_ids` carry the attachments).
 4. **Polls** `GET /sessions/{id}/messages?offset=<cursor>` (messages are ordered ascending by `sequence_number`, so `offset` is the cursor) and `GET …/messages/streaming-status` (`{is_streaming}`) until the turn settles — `is_streaming` false with no message flagged `streaming_in_progress`. A start-grace window covers env wake / queueing before the turn begins; an overall `--timeout` bounds the wait.
 
+With `--board`, the session is the agent's **dashboard chat** (`POST /dashboards/{id}/chat`), each message carries `dashboard_context`, and a `tiles` event before `done` reports tiles whose params the turn changed (see [Dashboards](features/dashboards/dashboards.md)).
+
 Each finalized message is emitted as one NDJSON line (`session` / `upload` / `message` / `status` / `done`); the in-progress assistant message is held back (its content is still growing) and emitted once final. Every `message` also carries the agent's reasoning/tool trace under **`events`** — the normalized `streaming_events` (thinking blocks, `tool` calls with their full `tool_input` payloads, tool results), with the bookkeeping/`attachment` entries stripped (attachments are surfaced separately). The final coalesced text stays in `content`; the trace shows *how* the agent got there. `--no-events` drops the trace; `--pretty` swaps NDJSON for a Rich transcript. Ctrl-C calls `POST …/messages/interrupt` and exits 130.
 
 ### Attachments
@@ -625,6 +634,7 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 | POST | `/api/v1/cli/account/agents/{id}/mint` | Account token | Mint a per-agent CLI token (`cinna agent sync`, `cinna doctor` re-mint) |
 | POST | `/api/v1/cli/account/api-proxy` | Account token | Buffered JSON escape hatch — `cinna api`, and the transport for every `cinna chat` session/message call |
 | POST | `/api/v1/cli/account/files/upload` | Account token | Multipart upload for `cinna chat --file` (the proxy can't carry multipart) |
+| (proxy) | `dashboards/capabilities`, `agents/{id}/dashboards/…`, `dashboards/…`, `dashboards/{id}/blocks/{block}/component/…`, `dashboards/{id}/chat`, `dashboards/component-refs/resolve` | Account token | `cinna dashboards` and `cinna chat --board`, all through the api-proxy; never the `…/frame` routes (core's proxy refuses them) |
 | GET/PATCH | `/api/v1/cli/account/improvement-requests[/{id}[/archive]]` | Account token | Improvement requests received on the agents the account owns (`cinna improve`); the `/archive` route returns a binary ZIP the JSON-only proxy can't carry |
 
 `cinna chat` reaches the conversation API **through** the api-proxy (so these are inner routes, not CLI routes): `POST /sessions/`, `GET /sessions/{id}`, `GET /sessions/{id}/messages`, `POST /sessions/{id}/messages/stream`, `GET /sessions/{id}/messages/streaming-status`, `POST /sessions/{id}/messages/interrupt`, and `GET /files/{id}/download`.

{cinna_cli-0.5.2 → cinna_cli-0.6.0}/docs/features/account_workspace/account_workspace.md

@@ -178,7 +178,13 @@ each with its own token, registry entry, and Mutagen session.
 - `cinna account refresh-context` re-downloads `context/` and regenerates the
   orchestrator `CLAUDE.md`, the MCP wiring, and every synced child's per-agent
   `CLAUDE.md` from the bundled templates — so a CLI upgrade's new commands reach
-  existing workspaces without a re-setup.
+  existing workspaces without a re-setup. A child whose config predates the
+  `bundle_id` field gets it filled in first (best effort), so its guide's
+  Dashboard components section carries the agent's own reference prefix.
+- The orchestrator `CLAUDE.md` has a **Dashboards** command table and a
+  "Which one?" note (webapp / dashboard component / artifact). The Artifacts
+  heading says "a frozen copy", and its starter points at
+  `artifact-sqlite-report/`. See [Dashboards](../dashboards/dashboards.md).
 
 ## Business rules / guardrails
 
@@ -219,7 +225,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.2 → cinna_cli-0.6.0}/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.2 → cinna_cli-0.6.0}/docs/features/account_workspace/account_workspace_tech.md

@@ -344,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.2 → cinna_cli-0.6.0}/docs/features/agent_addons/agent_addons.md

@@ -242,6 +242,20 @@ change without cutting a new one:
   it never revokes (revoking is its own verb in the web UI, so a stale
   invocation cannot silently remove access). An unknown address fails the whole
   publish rather than half-sharing it.
+- **A CLI publish is never refused as stale.** It goes through the agent path
+  (`POST /agents/{id}/skills/{name}/publish`), which records the package's
+  latest revision as the new revision's base, so a version a co-maintainer
+  shared in the meantime is built on rather than checked against. Cinna
+  Desktop's Share sends the base its folder holds instead, and core refuses
+  that share (`stale_base`) when a co-maintainer has shared a newer version
+  since. The CLI never calls the desktop upload, so it never sees
+  `stale_base` or `editable_package_exists`.
+- **Each revision names who shared it and what it was based on.**
+  `cinna skills revisions` and `cinna skills show` print **Shared by** (the
+  publisher's display name, `—` once the account is deleted) and **Based on**
+  (`Version N`, the revision the sharer's copy held; `—` for a first revision,
+  a share from an older Cinna Desktop, and any revision published before core
+  recorded it). An older server sends neither field and both read `—`.
 - **Publishing reads the cloud workspace.** The files come from the agent's
   remote workspace on disk — which is why a suspended environment publishes
   normally — so an unsynced local edit is simply not in the revision. Push

{cinna_cli-0.5.2 → cinna_cli-0.6.0}/docs/features/agent_addons/agent_addons_acceptance.md

@@ -516,11 +516,36 @@ cinna skills revisions <PACKAGE_ID>
 ```
 
 **Expected** — one row per revision, newest first, with number, version, release
-date, size and the `release_notes` given at publish time.
+date, size, **Shared by**, **Based on** and the `release_notes` given at publish
+time.
 
 **Watch for** — a permanently blank notes column (the field is `release_notes`,
 not `notes`); ascending order, which buries the answer at the bottom.
 
+### 20a. Each revision names who shared it and what it was based on
+
+**Goal** — the revision table shows the sharer and the base core recorded, and a
+CLI re-publish is recorded as built on the latest revision. Needs core
+d08c10d8 and 465c43c2 (revisions carrying `published_by` and
+`base_revision_number`).
+
+**Steps** — after scenarios 4 and 5 have published `acceptance-demo` twice:
+
+```bash
+cinna skills revisions <PACKAGE_ID>
+cinna skills revisions <PACKAGE_ID> --json
+```
+
+**Expected** — the table has **Shared by** and **Based on** columns. Revision 2
+reads **Based on** `Version 1`; revision 1 reads `—` there (a first revision has
+no base). Both rows name the publisher's display name under **Shared by**.
+`--json` carries the server's `published_by` (`{user_id, display_name}`) and
+`base_revision_number` (`1` on revision 2, `null` on revision 1) as sent.
+
+**Watch for** — revision 2 with no base (the agent publish path did not record
+one); a crash or a blank cell instead of `—` on a revision published before
+core recorded these fields.
+
 ### 21. Sharing changes after the publish
 
 **Steps**

{cinna_cli-0.5.2 → cinna_cli-0.6.0}/docs/features/agent_addons/agent_addons_tech.md

@@ -139,6 +139,10 @@
 - `src/cinna/account.py:_revision_rows()` — revisions sorted newest first. The
   question this list answers is "what is the newest"; a payload that happened to
   be ascending would put the answer at the bottom.
+- `src/cinna/account.py:_revision_shared_by()` / `_revision_based_on()` — the
+  revision table's **Shared by** (`published_by.display_name`) and **Based on**
+  (`Version <base_revision_number>`) cells, each `—` when the field is null or
+  absent.
 - `src/cinna/account.py:_addon_link()` — the row's `link` sub-object. Every
   fact about an *install* rather than a package lives there: `id` (the link id
   the plugin routes address), `installed_version`, `latest_version`,
@@ -242,11 +246,19 @@ hatch, `POST /api/v1/cli/account/api-proxy`:
   `grant_emails`, `package_id`). Returns the new revision; consumed fields are
   `package_id` (the package's UUID), `revision_number`, `version` and
   `frontmatter` (the last one only to tell whether the version reached the
-  workspace's `SKILL.md`).
+  workspace's `SKILL.md`). Core records the package's previous latest revision
+  as the new one's `base_revision_number`; this route never answers
+  `stale_base` or `editable_package_exists` — those come only from the desktop
+  upload (`POST /skills/packages/publish`), which the CLI does not call.
 - `GET /api/v1/skills/packages/{package_id}` — consumed fields are the
   reverse-DNS `package_id` string, `display_name`, `visibility`,
   `latest_version` and `revisions[]` (`revision_number`, `version`,
-  `created_at`, `release_notes` — **not** `notes` — and `size_bytes`).
+  `created_at`, `release_notes` — **not** `notes` — `size_bytes`,
+  `published_by` `{user_id, display_name}` (null once the account is deleted)
+  and `base_revision_number` (int or null)). The last two are absent on a
+  server older than skill co-maintainers; `_revision_shared_by()` and
+  `_revision_based_on()` render a missing or null value as `—`, and `--json`
+  passes both through untouched.
 - `POST /api/v1/agents/{agent_id}/skills/install` — `SkillInstallRequest`:
   `package_id` (the package **UUID**), optional `revision_number`,
   `conversation_mode`, `building_mode`. Answers `PluginSyncResponse`; 409

{cinna_cli-0.5.2 → cinna_cli-0.6.0}/docs/features/agent_management/agent_management.md

@@ -66,10 +66,14 @@ This doc covers the agent **lifecycle** verbs. The CRON automation subgroup
    conflicts against untouched remote originals. A session that cannot start is a
    warning naming `cinna sync push --agent <slug>` to run *before* editing — never
    a failed sync.
-3. Re-running sync for an agent **already synced** in that folder is refused
+3. Sync also records the agent's **bundle id** and the environment's **platform
+   skills** in the workspace config. The per-agent `CLAUDE.md` uses them for its
+   Dashboard components section: the agent's own `cinna://component/bundle:<id>/`
+   prefix, and the path to the account's kit copy of the `cinna-dashboards` skill.
+4. Re-running sync for an agent **already synced** in that folder is refused
    (with a `cinna agent unsync` / `cinna set-token` hint) — it never silently
    re-clones or duplicates.
-4. The workspace lands at `agents/<slug>/<subdir>/` (the Model-A nested layout;
+5. The workspace lands at `agents/<slug>/<subdir>/` (the Model-A nested layout;
    `<subdir>` is the slug unless the agent is git-versioned with another subdir) —
    the command prints the exact path. Afterward `cd` there and `cinna dev`, or stay
    at the account root and use `cinna sync push --agent <slug>` /
@@ -92,6 +96,12 @@ This doc covers the agent **lifecycle** verbs. The CRON automation subgroup
    re-materializes the backend scaffold and can clobber local changes, so the
    builder is told to `cinna sync push` first.
 3. It blocks until the container is back, then prints the post-restart status.
+4. If the agent is synced on this machine, it then **reconnects the sync
+   session** ("Sync session reconnected."). The old container took the remote
+   Mutagen agent with it, and without this the next `cinna sync push` failed
+   until Mutagen's own retry came round. A refused token is re-minted through
+   the account. A session that doesn't come back is a warning naming
+   `cinna sync push` / `cinna doctor`, never a failed restart.
 
 ### Rebuild an environment that predates a feature
 1. `cinna agent rebuild-env <agent_ref> [--yes]` is **not** a louder restart.
@@ -120,6 +130,8 @@ This doc covers the agent **lifecycle** verbs. The CRON automation subgroup
    row states; the server inside can still be starting, and a chat sent into that
    window sat streaming with no reply. It ends with "ready to chat", or a warning
    that the environment has not answered yet.
+7. Like `restart-env`, it then reconnects this machine's sync session for the
+   agent (see [Live Sync](../live_sync/live_sync.md)).
 
 ### Inspect what's live
 1. `cinna agent show <agent_ref>` prints the **effective prompts** (each under its
@@ -132,6 +144,11 @@ This doc covers the agent **lifecycle** verbs. The CRON automation subgroup
      `credentials:` block names. A credential shared by someone else whose slot
      this account cannot see reads `slot: unknown`, never `no slot`. When the
      agent's credential listing cannot be read, it falls back to name + type.
+   - A **Dashboard components** section (count, errors, tiles) when the server
+     has dashboards. It is read only while the environment is running, because
+     listing components would wake a suspended one; otherwise a dim note says the
+     environment's state. It never fails `show`. See
+     [Dashboards](../dashboards/dashboards.md).
 
 ### Choose the model per mode
 1. `cinna agent model show <agent_ref> [--json]` prints, for conversation and

{cinna_cli-0.5.2 → cinna_cli-0.6.0}/docs/features/agent_management/agent_management_tech.md

@@ -66,7 +66,13 @@ The group/subgroup objects are `src/cinna/main.py:agent()` and
 - `src/cinna/account.py:run_agent_restart_env()` — resolve the agent; if a local
   child workspace exists (`resolve_child_workspace()`), read `sync_session.status()`
   and warn+confirm when `pending_to_remote > 0` or `conflict_count > 0`; then
-  `AccountClient.restart_agent_env()` (blocking) and print status.
+  `AccountClient.restart_agent_env()` (blocking) and print status, then
+  `_reconnect_sync_session()`.
+- `src/cinna/account.py:_reconnect_sync_session()` — shared by restart and
+  rebuild: for the child workspace of this agent (`list_child_workspaces()`)
+  whose session exists, `sync_session.heal_session(child_cfg, child)` (a forced
+  reconnect, plus a token re-mint on a 401/403). It prints "Sync session
+  reconnected." or a warning, and never raises.
 - `src/cinna/account.py:run_agent_rebuild_env()` — the same shape as
   `run_agent_restart_env()` plus a second gate: the D2 unsynced-changes
   warn+confirm, then a `Rebuild …?` confirmation (default No) that `--yes`

cinna_cli-0.6.0/docs/features/artifacts/artifacts.md

@@ -0,0 +1,138 @@
+# Artifacts (`cinna artifacts`)
+
+## Purpose
+
+Publish a folder or a file from the user's machine to cinna-core as an
+**artifact** — a frozen, versioned copy people open on a Cinna page — and get a
+link back. The same command group lists, downloads, opens, shares and deletes
+artifacts from a terminal.
+
+## Mental model / core concepts
+
+An artifact lives **in cinna-core**, not on the machine and not in an agent
+environment. The CLI is a publisher and a remote control; once published, the
+artifact outlives the folder, the agent and the session it came from.
+
+- **Artifact** — a stable identity (title, who can see it, its page link) over a
+  sequence of immutable **revisions**. Core renders it: a folder with an
+  `index.html` runs as a small static site in a sandbox; anything else is a file
+  set with viewers (Markdown, CSV, PDF, images, code). Not to be confused with a
+  delegation's `--artifact` — a link attached to a task result (see Integration
+  points).
+- **Revision** — one publish of the files. Republishing adds a revision; the
+  page link stays the same and shows the latest one, so a shared link never
+  breaks when a report is refreshed.
+- **Path memory** — the CLI remembers which artifact each local path was
+  published as, per account workspace (`.cinna/artifacts.json`), and republishes
+  into it. Nothing is ever written into the published folder itself.
+- **Exclusions** — what never leaves the machine: `.git/`, `.env*` and `*.env`,
+  `credentials/`, `credentials.json`, `app-data/`, `.claude/`, `.cinna/` (it
+  holds the account token), `node_modules/`, `__pycache__/`, key and token
+  files (`*.pem`, `*.key`, `*.p12`, `id_rsa*` and the other SSH key names,
+  `.netrc`, `.npmrc`, `.pypirc`), `.DS_Store`, and every symlink. Mandatory, not
+  advisory; core drops its own set again on its side.
+- **Who can see it** — "Only you" (private, the default), plus named people,
+  plus "Everyone on the instance", plus **public links** (anyone holding the
+  link, signed out; optional expiry, optional 4-digit code, revocable,
+  optionally pinned to a revision). The CLI never says "public" for
+  instance-wide.
+- **Agents publish, people share** — an agent in the account workspace may
+  publish (always private) and manage its artifacts, but widening who can see
+  one is the user's call: `share` and `link create` are person-only verbs.
+
+## User flows
+
+### Publish a report and get its link
+1. `cinna artifacts publish ./reports/q3 --title "Q3 churn"` from the account
+   workspace (or any folder below it).
+2. The CLI prints the file count and size, then what it left out
+   (`.git/`, `.env`, …), uploads, and prints the page link and the id.
+3. The artifact is private; the user opens the link (or
+   `cinna artifacts open <id>`) to check it.
+
+### Refresh it later, same link
+4. Run the same `cinna artifacts publish ./reports/q3` again. The CLI says it
+   republished — revision 2, same link — because it remembered the path.
+5. `--update <id>` republishes into a named artifact instead; `--new` publishes
+   a separate artifact even though the path is known (the path then points at
+   the new one).
+
+### Share it with people
+6. In their own terminal the user runs
+   `cinna artifacts share <id> --user bob@example.com` and/or `--instance`;
+   `--private` and `--remove-user` narrow it again. The CLI prints who can see
+   it afterwards.
+7. For someone outside the instance:
+   `cinna artifacts link create <id> [--expires 7d] [--code] [--label …] [--rev N]`
+   prints the link (and code) **once**. `cinna artifacts show <id>` lists links
+   by id and prefix; `cinna artifacts link revoke <id> <link>` kills one.
+
+### Find, fetch, remove
+8. `cinna artifacts list` (yours) or `list --shared` (shared with you);
+   `show <id>` for revisions, people and links.
+9. `cinna artifacts download <id> [--rev N] [-o DIR]` extracts the files
+   (default `artifacts/<short-id>/` under the account root).
+10. `cinna artifacts delete <id>` asks first; the page and every link stop
+    working at once.
+
+## Business rules
+
+- **Server support first** — every verb asks core for its artifacts capability
+  before anything else; a server without it (or with another version) gets
+  "This Cinna server does not support artifacts" and nothing is uploaded.
+- **A secret path named directly is refused** — publishing `.cinna/account.json`,
+  a `credentials/` folder or anything inside an excluded folder stops before
+  any request; the walk alone would only see paths below what was named.
+- **Exclusions are listed, always** — the human output and the `--json` result
+  name every path left out, the CLI's and the server's together.
+- **Refuse what core would refuse, before uploading** — over the file count,
+  per-file size or total size the server advertises, the CLI stops locally.
+- **Republish keeps the title** — on a republish only the flags the user passes
+  change (`--title`, `--description`, `--entry`, `--note`).
+- **A remembered artifact that was deleted** — the CLI says so and publishes a
+  new one; an explicit `--update <id>` that no longer exists fails instead.
+- **Person-only verbs (A8)** — `share` and `link create` refuse under `--json`,
+  `--no-input` / `CINNA_NO_INPUT`, or when stdin is not a terminal, with code
+  `needs_person`. There is no `--yes` bypass: an agent can pass any flag. The
+  generated `.claude/settings.json` also denies `Bash(cinna artifacts share:*)`
+  and `Bash(cinna artifacts link create:*)` to Claude Code. The CLI cannot tell
+  an agent from a person — this is a speed bump; core enforces A8 on its
+  agent-token route.
+- **A script cannot share either** — a script without a terminal is refused the
+  same way. Sharing from automation is deliberately not offered in v1; the web
+  page's Share dialog is the alternative.
+- **Destructive verbs confirm** — `delete` and `link revoke` ask (default No);
+  under `--json` they need `--yes`, under `--no-input` without `--yes` they
+  abort.
+- **The link token is shown once** — core returns it only on creation; the
+  api-proxy never relays it, and `show` lists links by prefix only.
+- **Owner-only writes** — share, link and delete check ownership first and say
+  so plainly rather than relaying a 404.
+
+## Architecture overview
+
+```
+cinna artifacts publish PATH
+  → artifacts.py: walk + exclusions → temp zip (stored entries for very compressible files)
+  → AccountClient → POST /cli/account/artifacts[/{id}/revisions]  (multipart, account token)
+  → .cinna/artifacts.json  (path → artifact id)
+
+cinna artifacts list|show|share|link revoke|delete
+  → AccountClient → api-proxy → /api/v1/artifacts…, /users/search
+
+cinna artifacts link create | download
+  → AccountClient → /cli/account/artifacts/{id}/links | /download
+```
+
+## Integration points
+
+- [Account workspace](../account_workspace/account_workspace.md) — the account
+  token, the active user workspace the artifact lands in, and the generated
+  `.claude/settings.json` that carries the deny rules.
+- [Durable delegation](../delegation/delegation.md) — the page link a publish
+  prints is a valid `link` artifact for
+  `cinna delegation report --artifact '{"kind":"link","name":"…","ref":"<url>"}'`.
+- `cinna api` — the generic api-proxy the JSON verbs ride; it refuses link
+  creation and blanks link codes, which is why `link create` has its own route.
+- cinna-core's kit skill `cinna-artifacts` — how to build a folder that works
+  in the sandbox (bundle libraries, no `localStorage`, relative paths).