cinna-cli 0.2.6__tar.gz → 0.4.0__tar.gz

{cinna_cli-0.2.6 → cinna_cli-0.4.0}/.gitignore

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

{cinna_cli-0.2.6 → cinna_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.2.6
+Version: 0.4.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
@@ -63,7 +63,11 @@ Your Editor / Claude Code
 ## Prerequisites
 
 - **Python 3.10+**
-- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install)
+- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install; set `CINNA_MUTAGEN_BIN=/abs/path/mutagen` to use a specific binary instead of the one on PATH)
+
+### Cinna Desktop
+
+[Cinna Desktop](https://github.com/opencinna/cinna-desktop) installs its **own pinned copy** of cinna-cli (with `uv` and Mutagen alongside, inside its data folder) and drives it as a child process to create and keep alive an account workspace under `<AgentsHome>/Cloud/<host>/` right after you sign in — no `cinna login`, no token to paste. That private copy is not on your `PATH` unless you opt in from the desktop's settings; installing cinna-cli yourself (`uv tool install cinna-cli`) for terminal use is fine and both operate on the same workspace. The version the platform pins is reported by `cinna account status` / `cinna doctor`.
 
 ## Getting Started
 
@@ -135,7 +139,7 @@ cinna login app.example.com --dir my-cinna             # always into a named sub
 #   ✓ Account workspace ready.
 ```
 
-Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account setup` paste fallback.
+Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account set-token` paste fallback.
 
 ### `cinna account setup <token_or_url>`
 
@@ -145,7 +149,7 @@ Initialize an **account workspace** — a multi-agent root from which you can di
 curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -
 ```
 
-Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates `my-cinna/` (override with `--dir`) containing:
+Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates a folder named after the platform domain (override with `--dir`: an absolute path is used as is with parents created, a relative one lands under the current directory; an existing account workspace there is refused before the token is spent) containing:
 
 ```
 my-cinna/
@@ -159,6 +163,17 @@ Setup also downloads the **context package** into `context/` — curated platfor
 
 The account token is only used for the account-level endpoints (listing agents, minting per-agent tokens, the context package). Per-agent work always runs on each child workspace's own token. Revoking the account session in Settings disconnects every agent synced from it.
 
+`account setup`, `account set-token` and `account status` take `--no-input` (never prompt: defaults, or fail with code `needs_input`; also `CINNA_NO_INPUT=1`, accepted before or after the subcommand) and `--json` (one JSON object per line on stdout — progress `{"step","total","status","message"}` lines, then a final `{"result":"ok"|"error",…}`; implies `--no-input`). Exit codes are stable for every command: `0` ok, `10` setup token invalid/expired/used, `11` token for another account, `12` platform unreachable or 5xx, `1` anything else (the JSON `code` says what), `2` usage.
+
+### `cinna account set-token <token_or_url>`
+
+Refresh the **account** token in place from a fresh account setup token — the account counterpart of `cinna set-token`, and the paste alternative to `cinna login`. Run inside the account workspace; it re-exchanges under the stored machine name and rewrites only `account_token` (plus a refreshed platform/frontend URL) in `.cinna/account.json`. The active user workspace, machine name, `context/` and every synced child under `agents/` are untouched; run `cinna doctor` afterwards to re-mint expired child tokens. A token for a different account is refused (exit `11`) and nothing is written. Bare tokens reuse the stored platform URL.
+
+```bash
+cd my-cinna/
+cinna account set-token 'curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -'
+```
+
 ### `cinna account agents`
 
 List the agents your account can access (run from inside the account workspace). For each agent: display name + ID, building rights (`✓ can build`, `view-only`, or `foreign install` — installed bundles are publisher-managed and can't be synced), whether a remote environment is active, and whether a local workspace already exists under `agents/`.
@@ -167,7 +182,9 @@ List the agents your account can access (run from inside the account workspace).
 
 One-shot summary of the account workspace: platform/frontend URLs, machine name, synced-agent count, and an account-token probe (`valid token` / `expired token` / `no connection`) — the account-level counterpart of `cinna status`.
 
-Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there.
+Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there. Likewise it compares the installed **cinna-cli version** with the one the platform pins (its `/.well-known/cinna-desktop` discovery document) and suggests `uv tool install cinna-cli==<pin>` when behind; no pin means "unknown", not an error.
+
+With `--json` it prints a single line: `{"result":"ok","workspace",…,"token":"valid|expired|unreachable","synced_agents":N,"agents":[…],"context_package":{"local","remote","state"},"cli":{"installed","required","state"}}`.
 
 ### `cinna account refresh-context`
 
@@ -259,6 +276,25 @@ works exactly as for a manually set-up agent. Synced agents also appear in `cinn
 
 Detach a synced workspace: stop its sync session, revoke the minted CLI token server-side (via the account-scoped revoke endpoint, authenticated with the account token; idempotent), then perform the equivalent of `cinna disconnect`: remove `.cinna/`, generated files, and the registry entry. Workspace files under `agents/<slug>/workspace/` are preserved. The revoke degrades gracefully — if it fails (no connection, or a workspace synced before token-id tracking), a warning is printed and the local teardown still completes; the token then expires on its own or can be revoked from the agent's Integrations tab.
 
+### `cinna agent import <path> [--name TEXT] [--workspace REF] [--update] [--dry-run] [--no-push] [--yes]`
+
+Import an agent that was built **locally** with the [Local Agent Kit](docs/features/local_agent_import/local_agent_import.md) — a folder holding a `cinna-agent.json` manifest, typically `../Local/<slug>` next to this account workspace. Run it from the account workspace root (or any folder inside it).
+
+Nine idempotent steps, each printed as `[n/9]`: read and validate the manifest → create (or resolve) the cloud agent → write its description, router trigger, example prompts and the three document prompts in one bulk write, plus the status refresh command → attach a local workspace (`cinna agent sync`) → copy the tree into `agents/<slug>/workspace/` honouring the contract's exclude list and secret rules, generating `workspace_requirements.txt` from `pyproject.toml` when the agent doesn't ship one → `cinna sync push` → create the credential drafts and attach them → create the schedules → record the publication in `publications.json` and print the summary.
+
+```bash
+cinna agent import ../Local/invoice-watcher --dry-run   # see the plan, touch nothing
+cinna agent import ../Local/invoice-watcher --yes
+cinna chat --agent invoice-watcher "check invoices from last week"
+
+# after more local work:
+cinna agent import ../Local/invoice-watcher --update --yes
+```
+
+The folder rules come from the kit's versioned contract, `.cinna-kit/layout.json` — the same file Cinna Desktop reads — so a correction published there reaches this command on the next kit refresh rather than waiting for a new cinna-cli. `credentials/` and `app-data/` are **never** copied, not even if the contract drops them, and on top of the exclude list the contract's `secret_files` rules withhold every dotenv shape (`.env`, `.env.prod`, `staging.env`) wherever it sits, while `.env.example` still travels. No secret value is ever read, sent, or printed: credentials are created as empty drafts and the command prints the URLs the user opens to fill them in the browser.
+
+Where the folder has been published is recorded in `publications.json`, a **sibling** of `cinna-agent.json` holding one entry per Cinna instance — it cannot live inside the manifest, because each entry records a hash of the exported tree and the manifest is part of that tree. Every step is idempotent (agent by the entry whose `platform_url` matches the instance you are logged into, credentials by name, schedules by name), so a partial import is resumed with `--update` instead of duplicating anything. The publication is recorded **only after the push settled** — `--no-push`, a failed flush, or remaining conflicts leave it unrecorded, and the next run is a plain `--update`. A legacy `cloud` block is migrated into the ledger on the first write and is still read until then, so an older folder's `--update` never creates a second agent. `--dry-run` makes no platform call and writes nothing.
+
 ### `cinna connect agent-api --producer <agent> --consumer <agent> [--label TEXT] [--read-only]`
 
 Wire one agent to another's REST API from the account workspace. Resolves both agents (name, slug, or ID), mints a producer API token, and attaches it to the consumer as a credential — which rides the consumer's normal credential sync into its remote environment, so no key ever touches your machine. Prints the credential ID, token prefix, base URL, and spec URL. `--read-only` restricts the consumer to read-only access; `--label` names the credential. Backend errors surface verbatim: 400 if the producer's REST API is disabled, 403/404 for ownership violations.

{cinna_cli-0.2.6 → cinna_cli-0.4.0}/README.md

@@ -26,7 +26,11 @@ Your Editor / Claude Code
 ## Prerequisites
 
 - **Python 3.10+**
-- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install)
+- **[Mutagen](https://mutagen.io)** (version pinned by the platform — `cinna setup` checks and prompts to install; set `CINNA_MUTAGEN_BIN=/abs/path/mutagen` to use a specific binary instead of the one on PATH)
+
+### Cinna Desktop
+
+[Cinna Desktop](https://github.com/opencinna/cinna-desktop) installs its **own pinned copy** of cinna-cli (with `uv` and Mutagen alongside, inside its data folder) and drives it as a child process to create and keep alive an account workspace under `<AgentsHome>/Cloud/<host>/` right after you sign in — no `cinna login`, no token to paste. That private copy is not on your `PATH` unless you opt in from the desktop's settings; installing cinna-cli yourself (`uv tool install cinna-cli`) for terminal use is fine and both operate on the same workspace. The version the platform pins is reported by `cinna account status` / `cinna doctor`.
 
 ## Getting Started
 
@@ -98,7 +102,7 @@ cinna login app.example.com --dir my-cinna             # always into a named sub
 #   ✓ Account workspace ready.
 ```
 
-Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account setup` paste fallback.
+Use it when `cinna account status` or `cinna doctor` reports the account token has expired. Because the per-agent tokens minted from an account (`cinna agent sync`) can only be re-minted while the account token is valid, the flow is: `cinna login` (refresh the account), then `cinna doctor` (re-mint the dependent sub-agent tokens). If the platform doesn't expose the device-login endpoints yet, `cinna login` says so and points you at the `cinna account set-token` paste fallback.
 
 ### `cinna account setup <token_or_url>`
 
@@ -108,7 +112,7 @@ Initialize an **account workspace** — a multi-agent root from which you can di
 curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -
 ```
 
-Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates `my-cinna/` (override with `--dir`) containing:
+Accepts the same input forms as `cinna setup` (full curl command, URL, or bare token — bare tokens need `CINNA_PLATFORM_URL`). Creates a folder named after the platform domain (override with `--dir`: an absolute path is used as is with parents created, a relative one lands under the current directory; an existing account workspace there is refused before the token is spent) containing:
 
 ```
 my-cinna/
@@ -122,6 +126,17 @@ Setup also downloads the **context package** into `context/` — curated platfor
 
 The account token is only used for the account-level endpoints (listing agents, minting per-agent tokens, the context package). Per-agent work always runs on each child workspace's own token. Revoking the account session in Settings disconnects every agent synced from it.
 
+`account setup`, `account set-token` and `account status` take `--no-input` (never prompt: defaults, or fail with code `needs_input`; also `CINNA_NO_INPUT=1`, accepted before or after the subcommand) and `--json` (one JSON object per line on stdout — progress `{"step","total","status","message"}` lines, then a final `{"result":"ok"|"error",…}`; implies `--no-input`). Exit codes are stable for every command: `0` ok, `10` setup token invalid/expired/used, `11` token for another account, `12` platform unreachable or 5xx, `1` anything else (the JSON `code` says what), `2` usage.
+
+### `cinna account set-token <token_or_url>`
+
+Refresh the **account** token in place from a fresh account setup token — the account counterpart of `cinna set-token`, and the paste alternative to `cinna login`. Run inside the account workspace; it re-exchanges under the stored machine name and rewrites only `account_token` (plus a refreshed platform/frontend URL) in `.cinna/account.json`. The active user workspace, machine name, `context/` and every synced child under `agents/` are untouched; run `cinna doctor` afterwards to re-mint expired child tokens. A token for a different account is refused (exit `11`) and nothing is written. Bare tokens reuse the stored platform URL.
+
+```bash
+cd my-cinna/
+cinna account set-token 'curl -sL https://your-platform.com/api/cli-setup/account/TOKEN | python3 -'
+```
+
 ### `cinna account agents`
 
 List the agents your account can access (run from inside the account workspace). For each agent: display name + ID, building rights (`✓ can build`, `view-only`, or `foreign install` — installed bundles are publisher-managed and can't be synced), whether a remote environment is active, and whether a local workspace already exists under `agents/`.
@@ -130,7 +145,9 @@ List the agents your account can access (run from inside the account workspace).
 
 One-shot summary of the account workspace: platform/frontend URLs, machine name, synced-agent count, and an account-token probe (`valid token` / `expired token` / `no connection`) — the account-level counterpart of `cinna status`.
 
-Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there.
+Also reports the workspace's **context package version** against the platform's current one — the orchestrator guides ship in that tree, so a workspace set up before a guide existed silently lacks it. When it is behind, the command says so and points at `cinna account refresh-context`; `cinna improve list` prints the same nudge, since its playbook lives there. Likewise it compares the installed **cinna-cli version** with the one the platform pins (its `/.well-known/cinna-desktop` discovery document) and suggests `uv tool install cinna-cli==<pin>` when behind; no pin means "unknown", not an error.
+
+With `--json` it prints a single line: `{"result":"ok","workspace",…,"token":"valid|expired|unreachable","synced_agents":N,"agents":[…],"context_package":{"local","remote","state"},"cli":{"installed","required","state"}}`.
 
 ### `cinna account refresh-context`
 
@@ -222,6 +239,25 @@ works exactly as for a manually set-up agent. Synced agents also appear in `cinn
 
 Detach a synced workspace: stop its sync session, revoke the minted CLI token server-side (via the account-scoped revoke endpoint, authenticated with the account token; idempotent), then perform the equivalent of `cinna disconnect`: remove `.cinna/`, generated files, and the registry entry. Workspace files under `agents/<slug>/workspace/` are preserved. The revoke degrades gracefully — if it fails (no connection, or a workspace synced before token-id tracking), a warning is printed and the local teardown still completes; the token then expires on its own or can be revoked from the agent's Integrations tab.
 
+### `cinna agent import <path> [--name TEXT] [--workspace REF] [--update] [--dry-run] [--no-push] [--yes]`
+
+Import an agent that was built **locally** with the [Local Agent Kit](docs/features/local_agent_import/local_agent_import.md) — a folder holding a `cinna-agent.json` manifest, typically `../Local/<slug>` next to this account workspace. Run it from the account workspace root (or any folder inside it).
+
+Nine idempotent steps, each printed as `[n/9]`: read and validate the manifest → create (or resolve) the cloud agent → write its description, router trigger, example prompts and the three document prompts in one bulk write, plus the status refresh command → attach a local workspace (`cinna agent sync`) → copy the tree into `agents/<slug>/workspace/` honouring the contract's exclude list and secret rules, generating `workspace_requirements.txt` from `pyproject.toml` when the agent doesn't ship one → `cinna sync push` → create the credential drafts and attach them → create the schedules → record the publication in `publications.json` and print the summary.
+
+```bash
+cinna agent import ../Local/invoice-watcher --dry-run   # see the plan, touch nothing
+cinna agent import ../Local/invoice-watcher --yes
+cinna chat --agent invoice-watcher "check invoices from last week"
+
+# after more local work:
+cinna agent import ../Local/invoice-watcher --update --yes
+```
+
+The folder rules come from the kit's versioned contract, `.cinna-kit/layout.json` — the same file Cinna Desktop reads — so a correction published there reaches this command on the next kit refresh rather than waiting for a new cinna-cli. `credentials/` and `app-data/` are **never** copied, not even if the contract drops them, and on top of the exclude list the contract's `secret_files` rules withhold every dotenv shape (`.env`, `.env.prod`, `staging.env`) wherever it sits, while `.env.example` still travels. No secret value is ever read, sent, or printed: credentials are created as empty drafts and the command prints the URLs the user opens to fill them in the browser.
+
+Where the folder has been published is recorded in `publications.json`, a **sibling** of `cinna-agent.json` holding one entry per Cinna instance — it cannot live inside the manifest, because each entry records a hash of the exported tree and the manifest is part of that tree. Every step is idempotent (agent by the entry whose `platform_url` matches the instance you are logged into, credentials by name, schedules by name), so a partial import is resumed with `--update` instead of duplicating anything. The publication is recorded **only after the push settled** — `--no-push`, a failed flush, or remaining conflicts leave it unrecorded, and the next run is a plain `--update`. A legacy `cloud` block is migrated into the ledger on the first write and is still read until then, so an older folder's `--update` never creates a second agent. `--dry-run` makes no platform call and writes nothing.
+
 ### `cinna connect agent-api --producer <agent> --consumer <agent> [--label TEXT] [--read-only]`
 
 Wire one agent to another's REST API from the account workspace. Resolves both agents (name, slug, or ID), mints a producer API token, and attaches it to the consumer as a credential — which rides the consumer's normal credential sync into its remote environment, so no key ever touches your machine. Prints the credential ID, token prefix, base URL, and spec URL. `--read-only` restricts the consumer to read-only access; `--label` names the credential. Backend errors surface verbatim: 400 if the producer's REST API is disabled, 403/404 for ownership violations.

{cinna_cli-0.2.6 → cinna_cli-0.4.0}/docs/README.md

@@ -137,6 +137,7 @@ Key properties:
 A second token type (`token_type="cli-account"`) issued to an **account workspace** (`.cinna/account.json`). Scoped only to the `/account/*` routes — it discovers agents and mints per-agent CLI tokens (`cinna agent sync`), but cannot itself sync or exec. Same 7-day rolling expiry as a CLI token.
 
 - **Refreshable without a paste** — `cinna login` runs an RFC 8628 device-authorization flow: the CLI prints a short code + URL, the user clicks **Authorize** in the browser (already signed in), and the CLI swaps the fresh token into `.cinna/account.json` in place. Run from an empty/new folder, the same command instead bootstraps a brand-new account workspace.
+- **Refreshable from a setup token** — `cinna account set-token <token_or_url>` re-exchanges a fresh *account* setup token under the stored machine name and rewrites only `account_token` (same in-place swap). Bound to the same account: a different platform origin or token subject aborts with exit `11`. This is the path Cinna Desktop drives (`--no-input --json`) so the user never runs `cinna login`.
 - **Mints child tokens** — per-agent tokens minted from it carry its id as provenance and are re-mintable via `POST /account/agents/{id}/mint` (used by `cinna agent sync` and `cinna doctor`).
 
 ### Knowledge Source
@@ -201,19 +202,24 @@ main.py  (CLI commands — Click)
   ├── doctor.py          — `cinna doctor`: reconcile registry ↔ Mutagen, delete stalled / terminate active sessions, refresh tokens
   ├── chat.py            — `cinna chat`: session-backed conversation testing (poll + NDJSON) over the api-proxy
   ├── improve.py         — `cinna improve`: improvement requests users shared about your agents (list/show/download/status)
+  ├── local_import.py    — `cinna agent import`: the Local Agent Kit go-cloud step
+  ├── kit_contract.py    — the Local Agent Kit contract as data (`.cinna-kit/layout.json`):
+  │                        exclude patterns, secret-file rules, export walk, content_hash,
+  │                        publications.json ledger, contract-version gate
   ├── config.py          — .cinna/config.json: load/save/find
   ├── auth.py            — JWT storage, Authorization headers
   ├── client.py          — PlatformClient: HTTP + SSE stream_exec
-  ├── mutagen_runtime.py — detect/install Mutagen; gate on version match
+  ├── mutagen_runtime.py — detect/install Mutagen; gate on version match; `CINNA_MUTAGEN_BIN` override
+  ├── cli_version.py     — installed vs platform-pinned cinna-cli version
   ├── sync_session.py    — wrap the `mutagen` CLI (start/stop/status/conflicts)
   ├── sync_tui.py        — live Textual TUI shown by `cinna dev` (Sync/Details/Conflicts tabs)
   ├── sync_ssh_shim.py   — `cinna-sync-ssh` entry point (WebSocket transport)
   ├── sync.py            — tarball/zip extraction helpers (initial clone only)
   ├── context.py         — CLAUDE.md, BUILDING_AGENT.md, .mcp.json, opencode.json
   ├── mcp_proxy.py       — MCP stdio server for knowledge_query
-  ├── console.py         — Rich helpers
+  ├── console.py         — Rich helpers + the `--json` / `--no-input` switches (prompt/confirm wrappers, JSON lines)
   ├── logging.py         — cinna.log (rotating file handler)
-  └── errors.py          — exception hierarchy
+  └── errors.py          — exception hierarchy; `CinnaExit` = stable exit code + machine code
 ```
 
 ### Local Directory Layout
@@ -278,8 +284,8 @@ authoring convention.
 
 | Feature | Command surface | Docs |
 |---|---|---|
-| **Bootstrap & onboarding** | `cinna setup` / `set-token` / `login` / `list` / `status` / `disconnect[-all]` / `completion` / `dev` / `redev` | [business](features/bootstrap_onboarding/bootstrap_onboarding.md) · [tech](features/bootstrap_onboarding/bootstrap_onboarding_tech.md) · [acceptance](features/bootstrap_onboarding/bootstrap_onboarding_acceptance.md) |
-| **Account workspace** | `cinna account` (setup, agents, status, refresh-context, user-workspace, credentials) | [business](features/account_workspace/account_workspace.md) · [tech](features/account_workspace/account_workspace_tech.md) · [acceptance](features/account_workspace/account_workspace_acceptance.md) |
+| **Bootstrap & onboarding** | `cinna setup` / `set-token` / `login` / `list` / `status` / `disconnect[-all]` / `completion` / `dev` / `redev`; the no-TTY contract (`--no-input`, `--json`, exit codes, `CINNA_MUTAGEN_BIN`) | [business](features/bootstrap_onboarding/bootstrap_onboarding.md) · [tech](features/bootstrap_onboarding/bootstrap_onboarding_tech.md) · [acceptance](features/bootstrap_onboarding/bootstrap_onboarding_acceptance.md) |
+| **Account workspace** | `cinna account` (setup, set-token, agents, status, refresh-context, user-workspace, credentials); desktop-managed workspaces | [business](features/account_workspace/account_workspace.md) · [tech](features/account_workspace/account_workspace_tech.md) · [acceptance](features/account_workspace/account_workspace_acceptance.md) |
 | **Agent management** | `cinna agent` (sync, unsync, create, restart-env, show, status) | [business](features/agent_management/agent_management.md) · [tech](features/agent_management/agent_management_tech.md) · [acceptance](features/agent_management/agent_management_acceptance.md) |
 | **Agent schedules** | `cinna agent schedule` (list, generate, create, update, run, logs, delete) | [business](features/agent_schedules/agent_schedules.md) · [tech](features/agent_schedules/agent_schedules_tech.md) · [acceptance](features/agent_schedules/agent_schedules_acceptance.md) |
 | **Live sync** | `cinna sync` (status, conflicts, push, pull, resolve) + Mutagen transport | [business](features/live_sync/live_sync.md) · [tech](features/live_sync/live_sync_tech.md) · [acceptance](features/live_sync/live_sync_acceptance.md) |
@@ -289,6 +295,7 @@ 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) | [business](features/git_versioning/git_versioning.md) · [tech](features/git_versioning/git_versioning_tech.md) · [acceptance](features/git_versioning/git_versioning_acceptance.md) |
 | **Improvement requests** | `cinna improve` (list, show, download, status) | [business](features/improvement_requests/improvement_requests.md) · [tech](features/improvement_requests/improvement_requests_tech.md) · [acceptance](features/improvement_requests/improvement_requests_acceptance.md) |
+| **Local agent import** | `cinna agent import` (Local Agent Kit → cloud agent), incl. the versioned folder contract (`.cinna-kit/layout.json`), `publications.json` and `content_hash` | [business](features/local_agent_import/local_agent_import.md) · [tech](features/local_agent_import/local_agent_import_tech.md) · [acceptance](features/local_agent_import/local_agent_import_acceptance.md) |
 
 The sections below (Git Versioning, Sync Transport, Remote Exec, Remote Chat,
 Bootstrap Flow) remain as in-README quick references and backend contracts; the
@@ -600,6 +607,8 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 | Method | Route | Auth | Purpose |
 |--------|-------|------|---------|
 | POST | `/api/cli-setup/{token}` | Token | Exchange setup token for CLI token |
+| POST | `/api/cli-setup/account/{token}` | Token | Exchange an **account** setup token (`cinna account setup` / `cinna account set-token`); 4xx ⇒ exit 10, 5xx ⇒ exit 12 |
+| GET  | `/.well-known/cinna-desktop` | None | Desktop discovery document; `local_dev.cinna_cli_version` is the cinna-cli pin `cinna account status` / `cinna doctor` compare against (absent ⇒ "unknown") |
 | GET  | `/api/v1/cli/agents/{id}/workspace` | CLI JWT | One-shot tarball for initial clone |
 | GET  | `/api/v1/cli/agents/{id}/building-context` | CLI JWT | Assembled building prompt |
 | POST | `/api/v1/cli/agents/{id}/knowledge/search` | CLI JWT | Knowledge base search (via MCP proxy) |
@@ -640,6 +649,8 @@ uv run ruff format --check src/
 
 The CLI is published to [PyPI](https://pypi.org/project/cinna-cli/) by `.github/workflows/publish.yml`, which runs on any pushed tag matching `v*` (and via manual `workflow_dispatch`). It builds the sdist + wheel with `uv build`, runs `twine check`, then publishes through PyPI **Trusted Publishing** (OIDC — no stored API token) from the GitHub `pypi` environment.
 
+Cinna Desktop installs a **pinned** version (`uv tool install cinna-cli==<version>`) — the version each cinna-core instance advertises as `local_dev.cinna_cli_version` in its discovery document (`CINNA_CLI_VERSION` setting). A release that changes the driver contract (exit codes, `--json` shapes, the three desktop-driven verbs) must be published to PyPI **before** cinna-core's pin moves to it.
+
 ### Cutting a release
 
 Versioning is SemVer (`MAJOR.MINOR.PATCH`); a patch release is the common case. From a clean `main` with the changes you want to ship already merged:

{cinna_cli-0.2.6 → cinna_cli-0.4.0}/docs/features/account_workspace/account_workspace.md

@@ -43,7 +43,16 @@ each with its own token, registry entry, and Mutagen session.
 
 - **Account CLI token** — `cli-account` JWT in `.cinna/account.json`. Same 7-day
   rolling expiry as a per-agent token. Refreshed in place by `cinna login` (a
-  browser device-authorization flow — no paste). Mints child tokens; never syncs.
+  browser device-authorization flow — no paste) or by `cinna account set-token`
+  (paste / hand over a fresh account setup token). Mints child tokens; never
+  syncs.
+- **Desktop-managed workspace** — an account workspace that Cinna Desktop
+  created and keeps alive by driving `cinna` as a child process with no
+  terminal: `account setup` once (into `<AgentsHome>/Cloud/<host>/`), then
+  `account set-token` whenever it mints a new setup token with its own
+  session, and `account status --json` to reconcile. The user never runs
+  `cinna login`, yet the workspace is byte-identical to a terminal-made one —
+  the user's own terminal can `cd` in and use every command.
 - **`agents/` directory** — where `cinna agent sync` materializes per-agent
   checkouts. Account commands that touch local state (`status`, `agents`,
   `refresh-context`) walk this tree to find synced children.
@@ -74,11 +83,52 @@ each with its own token, registry entry, and Mutagen session.
    `agents/`, the orchestrator `CLAUDE.md` + `.claude/settings.json`, the
    knowledge MCP wiring, and the `context/` package. The folder name defaults to
    the platform domain (e.g. `demo-core_opencinna_io`); `--dir` or the prompt
-   overrides it.
+   overrides it. `--dir` is a contract: an **absolute** path is used exactly as
+   given (missing parents are created), a relative one lands under the current
+   directory. Either way an existing `.cinna/account.json` at the target is
+   refused before the token is spent.
 3. Alternatively, `cinna login <domain>` from an empty folder bootstraps the same
    workspace via the browser device flow (no paste); run inside an existing
    account workspace it refreshes the token in place.
 
+### Refresh the token from a setup token — `cinna account set-token`
+1. Mint a fresh **account** setup token (Settings → Local Development, or Cinna
+   Desktop does it with its own session).
+2. Inside the account workspace, `cinna account set-token <token-or-url>`
+   re-exchanges it under the **stored** machine name and swaps only
+   `account_token` (plus a server-refreshed platform / frontend URL) into
+   `.cinna/account.json`. The active user workspace, machine name, `context/`
+   and every child under `agents/` are untouched — the same in-place contract
+   `cinna login` gives, minus the browser. A bare token reuses the stored
+   platform URL.
+3. The new token must be for the **same account**: a different platform origin,
+   or a different `sub` on the token, is refused (exit 11) and nothing is written.
+4. Child tokens are not touched; `cinna doctor` re-mints expired ones as usual.
+
+### Driven by Cinna Desktop (no terminal)
+1. The desktop obtains a setup token from the platform with its own session and
+   spawns `cinna account setup "<setup_command>" --dir <absolute> --name <machine>
+   --no-input --json`.
+2. `--no-input` guarantees the process never waits for a human: every prompt
+   takes its default (machine name, folder), or fails with the machine code
+   `needs_input`. `CINNA_NO_INPUT=1` does the same for any command. `--json`
+   implies it.
+3. `--json` turns the output into one JSON object per line on stdout: progress
+   lines `{step, total, status: start|ok|warn|fail, message}` mirroring the
+   numbered steps, then exactly one final line — `{"result": "ok", …}` with the
+   workspace path, platform / frontend URLs, machine name and context-package
+   outcome, or `{"result": "error", "code", "detail"}`. Nothing else touches
+   stdout; logs stay in `cinna.log`.
+4. The process exit code is stable: `0` ok · `10` setup token invalid / expired /
+   already used · `11` the token is for another account · `12` the platform is
+   unreachable or answered 5xx · `1` anything else, with a specific `code`
+   (`workspace_exists`, `needs_input`, `mutagen_missing`, `mutagen_mismatch`,
+   `not_an_account_workspace`, …) · `2` bad invocation.
+5. Later the desktop runs `cinna account set-token "<setup_command>" --no-input
+   --json` to refresh silently, and `cinna account status --json` to read token
+   validity, synced agents, context-package freshness and whether the installed
+   cinna-cli matches the version the platform pins.
+
 ### Discover and attach agents
 1. `cinna account agents` lists the agents the account can access — name + id,
    build rights (foreign bundle installs are view-only), whether the remote env
@@ -126,7 +176,25 @@ each with its own token, registry entry, and Mutagen session.
   sync/exec always use the per-agent child token via the per-agent client.
 - **Single-use setup token is guarded before it's burned.** `cinna account setup`
   refuses an existing-workspace target *before* exchanging the token, so a doomed
-  run never wastes the one-time token.
+  run never wastes the one-time token (exit 1, code `workspace_exists`).
+- **`set-token` is account-bound, fail-loud.** The refreshed token must match
+  the workspace's platform origin and (when both tokens carry one) the same
+  subject; otherwise nothing is written and the command exits 11
+  (`account_mismatch`). It never rebinds a workspace to another account.
+- **Never hang without a terminal.** Under `--no-input` (or `CINNA_NO_INPUT=1`,
+  or `--json`) no command blocks on stdin: prompts take their default or fail
+  with `needs_input`; confirmations take their default (usually "No", which
+  aborts). The `/dev/tty` fallback the `curl | python3` bootstrap uses for the
+  folder prompt is skipped too.
+- **`--json` is a pure stream.** Rich output is suppressed entirely; each stdout
+  line is one JSON object and the last one is always the `result` line, on
+  success and on failure alike. Human output is unchanged when the flag is off.
+- **Exit codes are a contract.** 0 / 10 / 11 / 12 / 1 (+ `code`) / 2 as listed
+  in the desktop flow; every error the CLI raises on purpose maps onto it, so a
+  driver switches on the number, not on message text.
+- **Version pin is advisory.** `account status` compares the running cinna-cli
+  with the version the platform publishes in its discovery document; a missing
+  pin is `unknown`, never an error.
 - **Fail-loud on backend errors.** Token exchange, mint, and every account call
   surface the backend's `detail` verbatim (expired/used token, foreign-install
   403, ambiguous agent). The CLI does not pre-judge build rights client-side —
@@ -173,7 +241,11 @@ cinna account setup ────────────────────
       ▼
 .cinna/account.json  (account CLI token, cli-account scope)
       │
+      ├── cinna account set-token <token> ───────────────────► POST /cli-setup/account/<token>
+      │       (stored machine name; same-account check; rewrites account_token only)
+      ├── cinna login (device flow) ─────────────────────────► /api/v1/cli/account/login/*
       ├── cinna account agents / status / refresh-context ─► AccountClient ─► /api/v1/cli/account/*
+      │       (status: + GET /.well-known/cinna-desktop for the cinna-cli pin)
       ├── cinna account user-workspace … (client-side active selection)
       ├── cinna account credentials … (metadata-only drafts)
       │
@@ -205,11 +277,17 @@ cinna account setup ────────────────────
   publisher-install flag its ownership step depends on. See
   [improvement_requests](../improvement_requests/improvement_requests.md).
 - **Doctor / login** — `cinna doctor` re-mints expired per-agent tokens through
-  the account token, and groups blocked agents under a single `cinna login` hint
-  when the account token itself has expired.
+  the account token, and groups blocked agents under a single `cinna login` /
+  `cinna account set-token` hint when the account token itself has expired. It
+  also reports a cinna-cli that differs from the platform's pin.
+- **Bootstrap / onboarding** — the no-terminal contract (`--no-input`, `--json`,
+  exit codes, `CINNA_MUTAGEN_BIN`) is CLI-wide and described in
+  [Bootstrap & Onboarding](../bootstrap_onboarding/bootstrap_onboarding.md);
+  this doc covers how the account verbs use it.
+- **Cinna Desktop** — installs its own pinned cinna-cli (with uv and Mutagen) and
+  drives the three verbs above; the desktop-side plan lives in the cinna-desktop
+  repo (`plans/one-click-onboarding-desktop.md`). <!-- nocheck: cross-repo path -->
 
 Implementation: see [account_workspace_tech.md](account_workspace_tech.md).
 Real-usage e2e test scenarios: see
 [account_workspace_acceptance.md](account_workspace_acceptance.md).
-</content>
-</invoke>

{cinna_cli-0.2.6 → cinna_cli-0.4.0}/docs/features/account_workspace/account_workspace_acceptance.md

@@ -26,8 +26,10 @@ the silent-secret and scope-drift bugs live.
 - **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 account --help` lists `setup / agents / status / refresh-context /
-  user-workspace / credentials`.
+  `cinna account --help` lists `setup / set-token / agents / status /
+  refresh-context / user-workspace / credentials`.
+- For the no-terminal scenarios (15–18): `jq` to inspect the JSON lines, and a
+  second **account** setup token per run (every exchange burns one).
 - `git` and `mutagen` on `PATH` (needed once a child agent is synced and
   exercised).
 
@@ -253,8 +255,114 @@ the silent-secret and scope-drift bugs live.
 - **Watch for:** user files deleted; the registry entry surviving; a revoke error
   aborting the command.
 
+### 15. Desktop-style setup: absolute `--dir`, `--no-input`, `--json`, no TTY
+
+- **Goal:** Cinna Desktop creates the account workspace as a child process with
+  no terminal and parses the result.
+- **Setup:** a fresh account setup token; note the `setup_command` string the
+  platform returns (`curl -sL …/api/cli-setup/account/<TOKEN> | python3 -`).
+- **Steps:**
+  ```
+  TARGET="$HOME/CinnaAgents/Cloud/localhost"          # parents must not exist yet
+  cinna account setup 'curl -sL http://localhost:8000/api/cli-setup/account/<TOKEN> | python3 -' \
+      --dir "$TARGET" --name desktop-test --no-input --json < /dev/null > out.jsonl; echo "exit $?"
+  cat out.jsonl | jq -c .
+  ls -a "$TARGET"; cat "$TARGET/.cinna/account.json"
+  ```
+- **Expected:** exit `0`. Every line of `out.jsonl` parses; the first three are
+  `{"step":1..3,"total":3,"status":"start",…}`, the last is `{"result":"ok",
+  "workspace":"<TARGET>","platform_url":…,"frontend_url":…,"machine_name":
+  "desktop-test","context_package":"ok"}`. The workspace sits exactly at
+  `$TARGET` (dots in the host kept, parents created), with the same files as
+  scenario 1. No table, hint or spinner text on stdout.
+- **Watch for:** the workspace landing under cwd instead of the absolute path;
+  a non-JSON line on stdout (Rich leaking); the process waiting on stdin
+  (folder / machine-name prompt); `context_package` not reflecting a failed
+  download (should be `failed` with a preceding `"status":"warn"` line, exit
+  still 0).
+
+### 16. Desktop-style refresh: `account set-token` in place, same account only
+
+- **Goal:** the desktop refreshes an expiring account token silently; a token
+  for another account can never be swapped in.
+- **Setup:** scenario 15's workspace; `cinna account user-workspace activate
+  <name>` so a client-side selection exists; one synced child (scenario 5).
+  Mint two fresh account setup tokens: one as the **same** user, one as a
+  **different** user on the same platform.
+- **Steps:**
+  ```
+  cd "$TARGET"; cp .cinna/account.json /tmp/before.json
+  cinna account set-token 'curl -sL http://localhost:8000/api/cli-setup/account/<SAME_USER_TOKEN> | python3 -' \
+      --no-input --json < /dev/null; echo "exit $?"
+  diff <(jq 'del(.account_token)' /tmp/before.json) <(jq 'del(.account_token)' .cinna/account.json)
+  cat agents/<slug>/.cinna/config.json | jq .cli_token       # unchanged
+  cinna account set-token 'curl -sL http://localhost:8000/api/cli-setup/account/<OTHER_USER_TOKEN> | python3 -' \
+      --no-input --json < /dev/null; echo "exit $?"
+  cinna account set-token '<SAME_USER_TOKEN again>' --json; echo "exit $?"
+  ```
+- **Expected:** first call exits `0`, prints two `start` steps, an `ok` line
+  and `{"result":"ok",…,"context_package":"skipped"}`; only `account_token`
+  changed (the `diff` is empty), the child token is untouched, and the exchange
+  was made with the **stored** machine name (check the CLI token list in
+  Settings — no new machine). The other-user call exits `11` with
+  `{"result":"error","code":"account_mismatch",…}` and `account.json` is
+  unchanged. The reused (already burned) token exits `10` with
+  `code: "setup_token_invalid"` and the backend detail.
+- **Watch for:** the mismatch being detected only after the file was written;
+  `user_workspace_id` or `machine_name` reset; a new machine appearing in the
+  platform's token list; exit `1` where `10` / `11` is required.
+
+### 17. Exit-code contract
+
+- **Goal:** a driver can act on the exit code alone.
+- **Steps:** run each from a scratch dir with `--no-input --json < /dev/null`
+  and record `$?` plus the final line's `code`:
+  ```
+  cinna account setup '<ALREADY_USED_TOKEN_URL>' --dir /tmp/x1        # 10 setup_token_invalid
+  cinna account setup '<VALID_URL>' --dir "$TARGET"                    # 1  workspace_exists (token NOT burned)
+  cinna account setup 'http://127.0.0.1:1/api/cli-setup/account/X' --dir /tmp/x2   # 12 network
+  cinna account status                                                 # 1  not_an_account_workspace
+  cinna --no-input login                                               # 1  needs_input (no domain, human text)
+  cinna account setup                                                  # 2  usage
+  ```
+  Then, with the backend stopped: `cinna account set-token '<URL>' --json` → `12`.
+- **Expected:** the codes in the comments. For the `workspace_exists` case,
+  re-use the same valid token afterwards in a fresh dir — it must still work.
+- **Watch for:** any of these coming back as a bare `1`; a traceback instead of
+  a JSON error line; the guard case burning the token.
+
+### 18. `account status --json` and the cinna-cli version pin
+
+- **Goal:** the desktop reconciles from one status line, including whether to
+  reinstall cinna-cli.
+- **Steps:**
+  ```
+  cd "$TARGET"; cinna account status --json | jq .
+  curl -s http://localhost:8000/.well-known/cinna-desktop | jq .local_dev
+  cinna account status | tail -20
+  cinna doctor --dry-run
+  ```
+- **Expected:** exactly one JSON line with `result`, `workspace`,
+  `platform_url`, `frontend_url`, `machine_name`, `active_workspace`
+  (`{id,name}` or `null`), `token` (`valid|expired|unreachable`),
+  `synced_agents`, `agents[]`, `context_package{local,remote,state}` and
+  `cli{installed,required,state}`. When the platform publishes
+  `local_dev.cinna_cli_version`, `cli.required` equals it and `state` is
+  `current` / `behind` / `ahead`; on an older platform `required` is `null`
+  and `state` is `unknown` — still exit 0. The human `status` shows the same
+  as a `cinna-cli` table row and a `uv tool install cinna-cli==<pin>` hint when
+  behind; `doctor` lists the platform under "manual action needed" only when
+  the pin differs.
+- **Watch for:** a missing discovery document turning into an error; `doctor`
+  nagging when no pin is published; the JSON line missing `cli`.
+
 ## Cross-cutting invariants (must hold across all scenarios)
 
+- **`--json` stdout is JSON only, last line is the verdict** — every stdout line
+  parses; exactly one `result` line; human hints never leak.
+- **Never wait for a human without a terminal** — with `--no-input` / `--json`
+  / `CINNA_NO_INPUT=1` every command either proceeds or fails with
+  `needs_input`; nothing reads stdin or `/dev/tty`.
 - **No secret ever sent** — credential create/update bodies carry only metadata;
   the CLI cannot read or write a credential's secret value.
 - **Account token stays account-scoped** — it is used only on `/account/*`; every
@@ -284,4 +392,3 @@ the silent-secret and scope-drift bugs live.
 - Verify `~/.cinna/agents.json` has no leftover entries for the test children —
   especially if any helper ran **outside** pytest's global-state isolation (it
   would write the real registry).
-</content>