cinna-cli 0.2.2__tar.gz → 0.2.4__tar.gz

cinna_cli-0.2.4/.claude/commands/cinna-cli.feature.doc.md

@@ -0,0 +1,174 @@
+---
+description: Create or update cinna-cli feature documentation (business / tech / acceptance).
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+Feature name, description, or existing doc path to create/refactor.
+
+## Task
+
+Create or refactor feature documentation under `docs/features/` following the
+layered structure below. cinna-cli is a **Python CLI** (source in `src/cinna/`,
+tests in `tests/`) that drives local agent development against a remote platform
+API — there is no frontend/backend split to document. Keep that in mind: file
+references point into `src/cinna/…` and `tests/…`, not `backend/`/`frontend/`.
+
+**If given an existing doc path** — refactor it into the correct structure (split
+into business / tech / acceptance files as needed, move under
+`docs/features/{feature}/`).
+**If given a feature name** — create new documentation by exploring the codebase
+first (`src/cinna/`, the `cinna <group>` command surface in `src/cinna/main.py`,
+relevant tests).
+
+## Documentation Architecture
+
+### Layer 1 — Project index (`docs/README.md`)
+
+The single concise entry point: project purpose, glossary, architecture, command
+surface, and a **Feature Registry** linking each documented feature to its folder.
+When you create/update a feature doc, add/update its row in the registry.
+
+### Layer 2 — Feature folders (`docs/features/{feature}/`)
+
+```
+docs/
+├── README.md                          # Layer 1 — project index + feature registry
+└── features/
+    └── {feature}/                     # one folder per feature (snake_case)
+        ├── {feature}.md               # Layer 3a — business logic / reasoning (required)
+        ├── {feature}_tech.md          # Layer 3b — implementation, file refs (optional)
+        └── {feature}_acceptance.md    # Layer 3c — real-usage e2e scenarios (optional)
+```
+
+Feature-folder naming: snake_case, descriptive (`git_versioning`, `live_sync`,
+`remote_exec`, `account_workspace`, `remote_chat`).
+
+### Layer 3 — Feature documentation files
+
+#### 3a. Business logic: `{feature}.md`
+
+Explains **WHAT** the feature does and **WHY**, from a product/user perspective.
+A reader should understand purpose, flows, and rules without reading code.
+
+Required sections:
+1. **Purpose** — 1–2 sentences: what it does for the user.
+2. **Mental model / core concepts** — key terms and the model the user must hold
+   (for cinna-cli, almost always: how local files, the remote container, and any
+   external system relate; what is local vs remote vs on-demand).
+3. **User flows** — numbered steps for the main ways users interact (commands run,
+   what happens, what they see).
+4. **Business rules** — constraints, state/lifecycle rules, guardrails, failure
+   semantics (what is *fail-loud*, what is auto vs manual, direction guards…).
+5. **Architecture overview** — a simple text diagram of the component flow, e.g.
+   `cinna git <verb> → git_versioning.py → real git → remote`.
+6. **Integration points** — how it connects to other features (link their docs).
+
+Style: concise bullets, no code blocks, focus on behavior and reasoning.
+
+#### 3b. Technical details: `{feature}_tech.md`
+
+Deep-dive for developers: **HOW** it's implemented, with file references.
+
+Required sections:
+1. **File locations** — every `src/cinna/…` module + the tests that cover it.
+2. **Command surface** — `cinna <group> <verb>` → the function in
+   `src/cinna/main.py` that implements it, one line each.
+3. **Key functions & flow** — module path + function names with a brief purpose
+   (e.g. `src/cinna/git_versioning.py:link()` — the link sequence).
+4. **Config & registry** — fields written to `.cinna/config.json` and
+   `~/.cinna/agents.json` (the latter referenced as a path, it's runtime state).
+5. **External contracts** — platform API endpoints consumed, and any external
+   tool invoked (git, mutagen) with the exact invariants relied on.
+6. **Edge cases & guardrails** — the non-obvious behaviors a maintainer must
+   preserve, each tied to the code that enforces it.
+
+Style: heavy use of `src/cinna/file.py:function()` references. <!-- nocheck --> **No
+code blocks** — only file/function references.
+
+#### 3c. Acceptance scenarios: `{feature}_acceptance.md` — **the e2e test catalog**
+
+The catalog of **real-usage scenarios** a testing agent executes against a *live*
+environment (a real backend + real container + real external systems) — **not**
+unit tests. This is what catches the bugs unit tests miss: conflicting pushes,
+multi-agent layout collisions, registry drift across commands, tarball/commit
+divergence, stale state across command sequences.
+
+Write it so an autonomous agent can pick it up and run each scenario end-to-end.
+
+Required sections:
+1. **Preconditions** — what the agent needs: a live platform URL, an account
+   workspace or setup token, at least one (ideally two) agents configured for the
+   feature, any external accounts/credentials, and the editable install
+   (`which cinna` → repo `src/cinna`).
+2. **Scenario catalog** — a numbered list. Each scenario has:
+   - **Goal** — the real user intent being exercised.
+   - **Setup** — starting state.
+   - **Steps** — the exact `cinna …` (and supporting `git`/`cinna exec`) commands.
+   - **Expected** — observable outcome (output text, file/remote/registry/env
+     state). Be specific enough to assert.
+   - **Watch for** — the failure modes / regressions this scenario is designed to
+     surface (the "why this scenario exists").
+3. **Cross-cutting invariants** — properties that must hold across *all* scenarios
+   (e.g. credentials never committed; a command that re-writes the registry must
+   not drop another command's state; fail-loud, never silent-clobber).
+4. **Cleanup** — how to leave the live environment tidy afterward.
+
+Style: imperative, runnable. Real commands in fenced blocks are encouraged here
+(unlike the other layers). Prefer scenarios grounded in actual runs — when a real
+test discovers a defect, **add the scenario that reproduces it** so it becomes a
+permanent regression check.
+
+### Minimal documentation
+
+Not every feature needs all three files. Start with `{feature}.md`. Add `_tech.md`
+when implementation detail would clutter the business doc or spans many modules.
+Add `_acceptance.md` when the feature has **real-environment behavior worth
+exercising e2e** (anything touching sync, git, the container, schedules, or
+multi-agent/multi-command state — i.e. most non-trivial cinna-cli features).
+
+## Style rules
+
+**DO**
+- Use file refs: `src/cinna/git_versioning.py:link()`, `tests/test_git_versioning.py`
+- Use command refs: `cinna git push` — push the agent branch (ff-only)
+- Use endpoint refs: `GET /api/v1/cli/git-coordinates`
+- Link related docs: `See [Live Sync](../live_sync/live_sync.md)` <!-- nocheck -->
+- Concise bullets; simple text architecture diagrams
+- In `_acceptance.md`, write real runnable commands
+
+**DON'T**
+- Put code snippets in `{feature}.md` / `{feature}_tech.md`
+- Duplicate content between the business and tech files
+- Reference container/home paths (`/app/workspace/…`, `~/.cinna/…`) as if repo
+  files — they are illustrative; the checker skips them, but be intentional
+
+## Process
+
+1. **Scope** — new feature doc or refactor of an existing one?
+2. **Folder** — map to `docs/features/{feature}/`.
+3. **Explore** — read the relevant `src/cinna/` modules, the `cinna` command
+   surface, and the covering tests.
+4. **Write** — always `{feature}.md`; add `_tech.md` / `_acceptance.md` per the
+   rules above.
+5. **Update `docs/README.md`** — add/refresh the Feature Registry entry.
+6. **Validate references** — run the checker on the files you touched:
+   ```
+   python3 scripts/check_docs_references.py --files docs/features/{feature}/{feature}.md docs/features/{feature}/{feature}_tech.md docs/features/{feature}/{feature}_acceptance.md
+   ```
+   Fix every broken reference before finishing. For *illustrative* paths that are
+   not real repo files (container/home/convention paths), append `<!-- nocheck -->`
+   to that line.
+7. **Run the test suite** — `pytest -q` must stay green (the docs describe shipped
+   behavior; if a doc claims behavior the tests don't cover, add or point to the
+   test).
+
+## Output
+
+Write to `docs/features/{feature}/`. Report what was created/updated, any old
+files replaced (don't delete automatically — report them), the reference-check
+result, and the test-suite status.

{cinna_cli-0.2.2 → cinna_cli-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cinna-cli
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -255,6 +255,30 @@ cinna api PATCH agents/3fa85f64-5717-4562-b3fc-2c963f66afa6 --json '{"descriptio
 cinna api POST tasks --data @task.json
 ```
 
+### `cinna chat [--agent <ref>] [--resume <session_id>] [--file PATH ...] [MESSAGE...]`
+
+Talk to an agent through a **real platform session** — the same conversation pipeline production uses (permission checks, agent-env calls, the model/SDK the platform selects), not a local mock. Built for a local coding agent to test the agent it is building: it can prepare a prompt, attach files, and read the reply back as structured data.
+
+Run it from the account workspace (or any synced agent folder under it). The reply is observed by **polling** the backend rather than reading a live stream, so it is robust to streaming/transport quirks.
+
+- `--agent <name|slug|id>` picks the agent; omit it inside a synced agent workspace to infer it. `--resume <session_id>` continues an existing conversation instead of opening a new one (default mode for a new session is `conversation`; `--mode building` opens a building session).
+- The message is the positional argument; if omitted it is read from stdin, or you are prompted for it interactively in a TTY.
+- `--file PATH` (repeatable) uploads a local file and attaches it to the message.
+- Output is **NDJSON** by default — one JSON event per line (`session`, `upload`, `message`, `status`, `done`), trivially parseable by another agent. `--pretty` switches to a human-readable transcript.
+- Each `message` carries the agent's reasoning/tool trace under **`events`** — an ordered list of the `thinking` blocks, `tool` calls (with their full `tool_input` payload) and tool results behind the reply, so you see *what the agent did*, not just its final `content`. Pass `--no-events` to drop the trace and keep only the final text.
+- Files the agent attaches to its replies are downloaded under `./cinna-chat-files/<session_id>/` (override with `--download-dir`, or skip with `--no-download` to just report the file ids). Downloads are bounded by the api-proxy's 8 MiB response cap.
+- `--interval` / `--timeout` tune the poll cadence and the maximum wait for a turn. Ctrl-C interrupts the agent's turn and exits.
+
+```bash
+cinna chat --agent crm-agent "Summarize today's leads"
+cinna chat --agent crm-agent --file report.csv "Validate this export"
+cinna chat --resume 3fa85f64-5717-4562-b3fc-2c963f66afa6 "Now break it down by region"
+echo "ping" | cinna chat --agent crm-agent          # message from stdin
+cinna chat --agent crm-agent "hi" | jq -c 'select(.event=="message")'
+```
+
+The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`.
+
 ### `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`.
@@ -320,16 +344,25 @@ It detects and fixes:
 - **Halted sessions** — sessions stopped on `halted-on-root-deletion` (the local `workspace/` root was deleted) while the agent dir is otherwise intact. Terminated; `cinna dev` recreates a clean one.
 - **Dead-remote sessions** — sessions stuck retrying a remote env that no longer exists (`connecting-beta` / beta polling error). Mutagen has **no** "give up after N failures" option — a session retries forever until paused or terminated — so `doctor` is the cleanup path for these. Terminated.
 - **Orphaned sessions** — `cinna-*` sessions with no registry entry at all. Terminated.
+- **Active sessions** — the healthy, still-watching sessions left over from past `cinna dev` runs. They are not broken, but they keep the shared Mutagen daemon busy and are recreated on demand, so doctor offers to clear them as a separate step.
 - **Expired tokens** — for **account-managed** workspaces (those under an account root), the CLI token is re-minted automatically through the parent account token, no pasting required. **Standalone** workspaces (set up via `cinna setup`) can only be refreshed with a pasted setup token, so they are reported with a `cinna set-token` hint rather than changed.
 - **Expired account token** — a sub-agent token can only be re-minted while the **account** token that mints it is still valid. When the account token has itself expired, doctor probes it once and surfaces a single _"renew the account token — run `cinna login`"_ finding (listing the blocked sub-agents) instead of a pile of re-mints that would all fail with 401. Run `cinna login`, then re-run `cinna doctor` to re-mint the dependents.
 
 ```bash
-cinna doctor              # diagnose, then apply all fixes behind one confirmation
+cinna doctor              # diagnose, then walk the repair steps (each defaults to Yes)
 cinna doctor --dry-run    # report problems only; change nothing
-cinna doctor --yes        # apply every fix non-interactively
+cinna doctor --yes        # accept every step non-interactively
 ```
 
-The diagnosis is split into two tables: **Will fix** (everything doctor can repair — deleted-workspace cleanup, halted/dead/orphaned session termination, account token re-mints) and **No automatic fix — manual action needed** (standalone expired tokens, which need a pasted setup token and are never touched). Everything actionable is applied together behind a single `Apply N fix(es)?` confirmation, so the count always matches the "Will fix" table.
+`doctor` first prints the live `cinna-*` session inventory — each session tagged with the **agent** and **folder** it serves — so you can see what's running before deciding anything. Findings it can't fix itself (standalone expired tokens) are listed under **No automatic fix — manual action needed** and never touched.
+
+The repair then runs as three ordered, independently-confirmed steps, each defaulting to **Yes**:
+
+1. **Delete stalled sessions** — deleted-workspace cleanup plus halted / dead / orphaned session termination.
+2. **Terminate active sessions** — clear the healthy leftovers from the inventory above (recreated on the next `cinna dev`).
+3. **Refresh tokens** — re-mint expired account-managed tokens.
+
+`--yes` accepts all three; `--dry-run` shows the tables and changes nothing.
 
 ### `cinna disconnect`
 

{cinna_cli-0.2.2 → cinna_cli-0.2.4}/README.md

@@ -218,6 +218,30 @@ cinna api PATCH agents/3fa85f64-5717-4562-b3fc-2c963f66afa6 --json '{"descriptio
 cinna api POST tasks --data @task.json
 ```
 
+### `cinna chat [--agent <ref>] [--resume <session_id>] [--file PATH ...] [MESSAGE...]`
+
+Talk to an agent through a **real platform session** — the same conversation pipeline production uses (permission checks, agent-env calls, the model/SDK the platform selects), not a local mock. Built for a local coding agent to test the agent it is building: it can prepare a prompt, attach files, and read the reply back as structured data.
+
+Run it from the account workspace (or any synced agent folder under it). The reply is observed by **polling** the backend rather than reading a live stream, so it is robust to streaming/transport quirks.
+
+- `--agent <name|slug|id>` picks the agent; omit it inside a synced agent workspace to infer it. `--resume <session_id>` continues an existing conversation instead of opening a new one (default mode for a new session is `conversation`; `--mode building` opens a building session).
+- The message is the positional argument; if omitted it is read from stdin, or you are prompted for it interactively in a TTY.
+- `--file PATH` (repeatable) uploads a local file and attaches it to the message.
+- Output is **NDJSON** by default — one JSON event per line (`session`, `upload`, `message`, `status`, `done`), trivially parseable by another agent. `--pretty` switches to a human-readable transcript.
+- Each `message` carries the agent's reasoning/tool trace under **`events`** — an ordered list of the `thinking` blocks, `tool` calls (with their full `tool_input` payload) and tool results behind the reply, so you see *what the agent did*, not just its final `content`. Pass `--no-events` to drop the trace and keep only the final text.
+- Files the agent attaches to its replies are downloaded under `./cinna-chat-files/<session_id>/` (override with `--download-dir`, or skip with `--no-download` to just report the file ids). Downloads are bounded by the api-proxy's 8 MiB response cap.
+- `--interval` / `--timeout` tune the poll cadence and the maximum wait for a turn. Ctrl-C interrupts the agent's turn and exits.
+
+```bash
+cinna chat --agent crm-agent "Summarize today's leads"
+cinna chat --agent crm-agent --file report.csv "Validate this export"
+cinna chat --resume 3fa85f64-5717-4562-b3fc-2c963f66afa6 "Now break it down by region"
+echo "ping" | cinna chat --agent crm-agent          # message from stdin
+cinna chat --agent crm-agent "hi" | jq -c 'select(.event=="message")'
+```
+
+The session id is printed in the first `session` event — capture it to drive a multi-turn conversation with `--resume`.
+
 ### `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`.
@@ -283,16 +307,25 @@ It detects and fixes:
 - **Halted sessions** — sessions stopped on `halted-on-root-deletion` (the local `workspace/` root was deleted) while the agent dir is otherwise intact. Terminated; `cinna dev` recreates a clean one.
 - **Dead-remote sessions** — sessions stuck retrying a remote env that no longer exists (`connecting-beta` / beta polling error). Mutagen has **no** "give up after N failures" option — a session retries forever until paused or terminated — so `doctor` is the cleanup path for these. Terminated.
 - **Orphaned sessions** — `cinna-*` sessions with no registry entry at all. Terminated.
+- **Active sessions** — the healthy, still-watching sessions left over from past `cinna dev` runs. They are not broken, but they keep the shared Mutagen daemon busy and are recreated on demand, so doctor offers to clear them as a separate step.
 - **Expired tokens** — for **account-managed** workspaces (those under an account root), the CLI token is re-minted automatically through the parent account token, no pasting required. **Standalone** workspaces (set up via `cinna setup`) can only be refreshed with a pasted setup token, so they are reported with a `cinna set-token` hint rather than changed.
 - **Expired account token** — a sub-agent token can only be re-minted while the **account** token that mints it is still valid. When the account token has itself expired, doctor probes it once and surfaces a single _"renew the account token — run `cinna login`"_ finding (listing the blocked sub-agents) instead of a pile of re-mints that would all fail with 401. Run `cinna login`, then re-run `cinna doctor` to re-mint the dependents.
 
 ```bash
-cinna doctor              # diagnose, then apply all fixes behind one confirmation
+cinna doctor              # diagnose, then walk the repair steps (each defaults to Yes)
 cinna doctor --dry-run    # report problems only; change nothing
-cinna doctor --yes        # apply every fix non-interactively
+cinna doctor --yes        # accept every step non-interactively
 ```
 
-The diagnosis is split into two tables: **Will fix** (everything doctor can repair — deleted-workspace cleanup, halted/dead/orphaned session termination, account token re-mints) and **No automatic fix — manual action needed** (standalone expired tokens, which need a pasted setup token and are never touched). Everything actionable is applied together behind a single `Apply N fix(es)?` confirmation, so the count always matches the "Will fix" table.
+`doctor` first prints the live `cinna-*` session inventory — each session tagged with the **agent** and **folder** it serves — so you can see what's running before deciding anything. Findings it can't fix itself (standalone expired tokens) are listed under **No automatic fix — manual action needed** and never touched.
+
+The repair then runs as three ordered, independently-confirmed steps, each defaulting to **Yes**:
+
+1. **Delete stalled sessions** — deleted-workspace cleanup plus halted / dead / orphaned session termination.
+2. **Terminate active sessions** — clear the healthy leftovers from the inventory above (recreated on the next `cinna dev`).
+3. **Refresh tokens** — re-mint expired account-managed tokens.
+
+`--yes` accepts all three; `--dry-run` shows the tables and changes nothing.
 
 ### `cinna disconnect`
 

{cinna_cli-0.2.2 → cinna_cli-0.2.4}/docs/README.md

@@ -198,7 +198,8 @@ main.py  (CLI commands — Click)
   │
   ├── bootstrap.py       — setup orchestration
   ├── account.py         — account workspace; `cinna login` (device auth), `cinna account`, `cinna agent`
-  ├── doctor.py          — `cinna doctor`: reconcile registry ↔ Mutagen, repair stale state, refresh tokens
+  ├── 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
   ├── config.py          — .cinna/config.json: load/save/find
   ├── auth.py            — JWT storage, Authorization headers
   ├── client.py          — PlatformClient: HTTP + SSE stream_exec
@@ -216,12 +217,21 @@ main.py  (CLI commands — Click)
 
 ### Local Directory Layout
 
-After `cinna setup` (agent name normalized, e.g. "HR Manager Agent" → `hr-manager-agent/`):
+After `cinna setup` (agent name normalized, e.g. "HR Manager Agent" → `hr-manager-agent`),
+every new checkout uses the **Model-A nested layout** (`config.compute_agent_layout`):
+a clone-root dir holds the agent at `<subdir>/`, so the folder is already shaped like
+the agent's git repo whether or not Git Versioning is enabled (see "Git Versioning"
+below). `<subdir>` defaults to the agent slug. If the clone-root dir `<slug>/` is
+already taken by a **different** agent (two names normalizing to the same slug), the
+clone root falls back to `<slug>-<shorthash>/` (the agent id's short hash) so the two
+don't collide; re-running setup for the *same* agent still reports "already set up".
 
 ```
-hr-manager-agent/               (workspace root)
+hr-manager-agent/               (clone root — becomes the git working tree once linked)
+└── hr-manager-agent/           (workspace root == the repo's <subdir>/ node)
   .cinna/
-    config.json                 (agent config, CLI token, mutagen_version pin)
+    config.json                 (agent config, CLI token, mutagen_version pin, git{} layout)
+  cinna.agent.json              (backend-owned manifest; present once git-versioned)
   workspace/                    (continuously synced with remote /app/workspace)
     scripts/                    (bundle-owned — shipped in published revisions)
     docs/                       (bundle-owned)
@@ -249,13 +259,146 @@ Per-user global state (one copy, shared across every agent workspace):
 
 ```
 ~/.cinna/
-  agents.json                   (agent_id → {platform_url, cli_token, workspace_path}; 0600)
+  agents.json                   (agent_id → {platform_url, cli_token, workspace_path,
+                                 git?:{clone_path, subdir, repo_url, ref, …}}; 0600)
   mutagen-ssh/
     ssh                         (bash wrapper — execs cinna-sync-ssh; 0755)
 ```
 
 ---
 
+## Feature Registry
+
+Each feature is documented under `docs/features/{feature}/` as a layered set:
+`{feature}.md` (business logic / reasoning), `{feature}_tech.md` (implementation +
+file refs), and `{feature}_acceptance.md` (live e2e scenarios). See
+[cinna-cli.feature.doc](../.claude/commands/cinna-cli.feature.doc.md) for the
+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) |
+| **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) |
+| **Remote exec** | `cinna exec` | [business](features/remote_exec/remote_exec.md) · [tech](features/remote_exec/remote_exec_tech.md) · [acceptance](features/remote_exec/remote_exec_acceptance.md) |
+| **Remote chat** | `cinna chat` | [business](features/remote_chat/remote_chat.md) · [tech](features/remote_chat/remote_chat_tech.md) · [acceptance](features/remote_chat/remote_chat_acceptance.md) |
+| **Agent API** | `cinna agent-api` (enable, refresh, spec, call) · `cinna api` · `cinna connect agent-api` | [business](features/agent_api/agent_api.md) · [tech](features/agent_api/agent_api_tech.md) · [acceptance](features/agent_api/agent_api_acceptance.md) |
+| **MCP integration** | `cinna connect mcp` · `cinna mcp-proxy` (knowledge stdio server) | [business](features/mcp_integration/mcp_integration.md) · [tech](features/mcp_integration/mcp_integration_tech.md) · [acceptance](features/mcp_integration/mcp_integration_acceptance.md) |
+| **Git versioning** | `cinna git` (link, status, commit, push, pull, log, checkout, unlink) | [business](features/git_versioning/git_versioning.md) · [tech](features/git_versioning/git_versioning_tech.md) · [acceptance](features/git_versioning/git_versioning_acceptance.md) |
+
+The sections below (Git Versioning, Sync Transport, Remote Exec, Remote Chat,
+Bootstrap Flow) remain as in-README quick references and backend contracts; the
+feature folders above are the authoritative deep dives.
+
+---
+
+## Git Versioning
+
+> Full feature docs: [git_versioning](features/git_versioning/git_versioning.md)
+> (business logic), [_tech](features/git_versioning/git_versioning_tech.md)
+> (implementation), [_acceptance](features/git_versioning/git_versioning_acceptance.md)
+> (live e2e scenarios). This section is the quick reference + backend contract.
+
+A git-versioned agent has **two independent sync layers** on the same folder:
+**Mutagen** keeps `workspace/` mirrored to the running container in near-real-time
+(it ignores `.git`), and **git** durably versions the same files against the agent's
+external remote. They meet only at the remote. All git ops are local and run with the
+developer's **own** git/SSH credentials — the platform's deploy key never reaches the
+CLI. (The agent-facing version of this guidance is shipped into each checkout as the
+on-demand `GIT_VERSIONING.md`, referenced conditionally from `CLAUDE.md`.)
+
+Because new checkouts already use the Model-A nested layout, enabling Git Versioning
+later needs no re-download or file move — just a link:
+
+```
+cinna git status      # is this agent git-versioned? linked? working-tree status
+cinna git link        # init the clone, sparse-checkout <subdir>, fetch + reset --mixed
+cinna git commit -m "…" [--push]   # stage the subdir + commit (honors .gitignore)
+cinna git push        # fast-forward only; rejected pushes tell you to pull --rebase
+cinna git pull        # rebase the remote in; Mutagen mirrors it into the running env
+cinna git log         # recent commits touching this agent's subdir
+cinna git checkout <ref> [--reload]   # restore a past version's workspace/ files into
+                       #   the tree (uncommitted) + flush to the running env via Mutagen
+                       #   — debug/rollback without committing
+cinna git unlink      # stop offering git helpers (keeps .git + history)
+```
+
+`cinna setup` / `cinna agent sync` auto-run `git link` when the agent is already
+git-versioned, so the developer gets a working tree from the first checkout.
+`--agent <ref>` targets a synced child from the account root (like `cinna sync`).
+
+Key behaviors: `link` uses `git reset --mixed` (never `--hard`) so the backend's
+in-flight changes survive as ordinary uncommitted edits; pushes are fast-forward-only
+and never auto-forced; a `sync_direction=pull` agent refuses local pushes; and a legacy
+*flat* workspace that becomes git-versioned is **not** auto-converted (link prints a
+disconnect + re-sync instruction).
+
+### Backend contract (cinna-core)
+
+The CLI consumes one discovery endpoint; the agent is derived from the per-agent
+token, so the path has **no `{agent_id}`**:
+
+```
+GET /api/v1/cli/git-coordinates   (Auth: per-agent CLI JWT)
+```
+
+Response (`CliGitCoordinates` — `client.get_git_coordinates`, modelled by
+`git_versioning.GitCoordinates`). `vcs_enabled=false` ⇒ all other fields null; a 404
+(older backend) is treated as `vcs_enabled=false`:
+
+```jsonc
+{
+  "vcs_enabled": true,                 // false ⇒ agent has no git source
+  "repo_url": "git@github.com:acme/agents.git",
+  "subdir": "hr-bot",                  // null ⇒ agent lives at the repo root
+  "ref": "main",
+  "sync_direction": "bidirectional",   // "pull" | "push" | "bidirectional"
+  "last_synced_commit": "a1b2c3…",     // SHA the backend last imported/pushed; may be null
+  "auth_hint": "ssh"                   // "ssh" | "https" — which local cred the DEV needs
+}
+```
+
+The remote repo stores each agent as the `schema_version`-2 bundle snapshot — this is
+the layout `link` reconciles against (`reset --mixed` brings the manifest + `.gitignore`
+from the ref; `workspace/**` stays the live copy):
+
+```
+<repo-root>/<subdir>/
+├── cinna.agent.json   # backend-owned manifest (prompts, SDK config, schedules,
+│                      #   plugin specs, required_credential_specs, content_hash…)
+├── workspace/         # the editable agent files (scripts/, docs/, …)
+└── .gitignore         # auto-generated; excludes credentials/, app-data/, logs/,
+                       #   databases/, uploads/, plugins-derived, __pycache__, *.pyc…
+```
+
+Contract rules the CLI honors:
+
+- **Two-writer, fast-forward-only.** Backend (deploy key) and developer (own creds)
+  push the same ref; both ff-only, no auto-merge. A rejected dev push ⇒ surface
+  `git pull --rebase`, never force.
+- **Backend-owned manifest.** `cinna.agent.json` is regenerated by the backend from
+  the DB on every backend push/connect — the CLI commits it as-is and never invents
+  values (it lacks the DB/env inputs). Editing prompt **files** under
+  `workspace/docs/` flows back into the DB via the platform's prompt-sync.
+- **Never committable** (the committed `.gitignore` + a local `.git/info/exclude`
+  enforce it; the CLI never `git add -f`): `credentials/`, `app-data/`, logs,
+  databases, `uploads/`, plugins-derived files, `__pycache__/`, `*.pyc`, plus the
+  CLI's own `.cinna/` (holds the token) and generated guides.
+- **Deploy key is host-side only** and never leaves the backend; `git-coordinates`
+  deliberately omits all key material — the dev authenticates with their own
+  git/SSH (`auth_hint` only advises which).
+- **Backend adoption of dev pushes.** After a dev push the backend is behind; it
+  adopts the change when the user clicks **Pull** on the agent's Git Versioning card
+  or via the configured GitOps webhook — the CLI cannot trigger it.
+
+The backend half lives in cinna-core — see its `docs/agents/agent_git_versioning/` <!-- nocheck: cross-repo (cinna-core) path -->
+plus `backend/app/api/routes/cli.py` (`CliGitCoordinates` / `_git_auth_hint`),
+`GitSourceService`, and `SSHKeyService`; that repo owns the authoritative spec.
+
+---
+
 ## Sync Transport
 
 ### Wire path
@@ -356,6 +499,31 @@ To run an actual remote shell snippet (pipes, redirects, `&&`), pass it explicit
 
 ---
 
+## Remote Chat (`cinna chat`)
+
+`cinna chat` lets a local coding agent **test the agent it is building** by driving a real platform conversation session — exercising the production path (permission checks, agent-env calls, the model/SDK the platform selects) rather than a local mock. It lives in `chat.py` and runs entirely through the **account workspace's api-proxy** (`AccountClient`), so it needs an account workspace (`.cinna/account.json`) — found by walking up from the cwd, exactly like the other account verbs, so it works from a synced `agents/<slug>/` folder too.
+
+### Why polling, not streaming
+
+The platform's send-message route (`POST /sessions/{id}/messages/stream`) returns a **JSON ack immediately** and runs the agent turn asynchronously; the live events go out over a Socket.IO room *and* are persisted onto each message's `message_metadata.streaming_events`. The api-proxy is a buffered JSON hatch (it rejects `text/event-stream`), so `cinna chat` never reads the stream. Instead it:
+
+1. Creates the session (`POST /sessions/`, mode `conversation` by default) — or resumes the one passed to `--resume`.
+2. Uploads each `--file` and collects the returned file ids.
+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.
+
+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
+
+Agents attach workspace files to replies via `<cinna_attach>` tags; the backend materializes them and both injects an `attachment` streaming event (`metadata.file_id` / `filename` / `mime_type` / `size`) and lists them under the message's `files[]` with `source == "agent_attachment"`. `chat.py` collects attachments from the streaming events (preferred) with the `files[]` list as a replay fallback, dedups by file id, and downloads each via the proxy (`GET /files/{id}/download`) into `./cinna-chat-files/<session_id>/`. Because the proxy buffers the response, downloads are bounded by its **8 MiB** response cap; larger files surface a clear `PlatformError` instead of a partial write.
+
+### File upload — the one dedicated route
+
+The api-proxy is JSON-only and cannot carry a multipart body, and neither the account token nor a per-agent token may call `/files/upload` directly. So uploading a local attachment uses a dedicated account-CLI route, **`POST /api/v1/cli/account/files/upload`** (multipart, account-token auth), added alongside the other `/cli/account/*` routes; it creates a `File` owned by the account user and returns `FileUploadPublic` whose `id` goes into the message's `file_ids`. This is the only part of `cinna chat` that does not ride the api-proxy.
+
+---
+
 ## Bootstrap Flow
 
 ```
@@ -404,7 +572,7 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 
 **Account tokens** refresh without a paste. `cinna login` (run inside an account workspace) drives the platform's RFC 8628 device-authorization flow: `POST /account/login/start` returns a short code + verification URL, the user clicks **Authorize** in the browser (already signed in), and the CLI polls `POST /account/login/poll` until it receives the fresh token, which it writes back into `.cinna/account.json` in place. The poll endpoint always returns HTTP 200 with a `status` field (`authorization_pending` / `slow_down` / `authorized` / `access_denied` / `expired_token`) — a deliberate divergence from RFC 8628's 400+`error` shape. Run from a fresh folder, the same command bootstraps a new account workspace instead of resuming one.
 
-**Bulk repair** is `cinna doctor`. It reconciles the `~/.cinna/agents.json` registry against the Mutagen daemon and heals the state that drifts as agents come and go — registry entries whose workspace was deleted, sessions halted on a deleted local root or stuck retrying a dead remote env, and orphaned sessions (Mutagen has no "stop after N failures" knob, so these retry forever until terminated). Expired **per-agent** tokens under an account workspace are re-minted automatically through the parent account token; when the **account** token has itself expired, doctor groups the blocked agents into a single "run `cinna login`" finding instead of attempting re-mints that would 401. Standalone agents are reported for a manual `cinna set-token`.
+**Bulk repair** is `cinna doctor`. It reconciles the `~/.cinna/agents.json` registry against the Mutagen daemon and heals the state that drifts as agents come and go — registry entries whose workspace was deleted, sessions halted on a deleted local root or stuck retrying a dead remote env, and orphaned sessions (Mutagen has no "stop after N failures" knob, so these retry forever until terminated). It prints the live `cinna-*` session inventory up front — each tagged with the agent and folder it serves — then walks three ordered, separately-confirmed steps (each defaulting to Yes): **delete stalled sessions**, **terminate active sessions** (the healthy leftovers, recreated on the next `cinna dev`), and **refresh tokens**. Expired **per-agent** tokens under an account workspace are re-minted automatically through the parent account token; when the **account** token has itself expired, doctor groups the blocked agents into a single "run `cinna login`" finding instead of attempting re-mints that would 401. Standalone agents are reported for a manual `cinna set-token`.
 
 ### Authorization
 
@@ -434,13 +602,18 @@ When a CLI token expires (or is revoked) the normal remedy is `cinna set-token <
 | 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) |
 | GET  | `/api/v1/cli/agents/{id}/sync-runtime` | CLI JWT | Required Mutagen version + hash (also used by `cinna list` / `cinna status` as a cheap token-validity probe) |
+| GET  | `/api/v1/cli/git-coordinates` | CLI JWT | Agent's git-versioning coordinates — **no `{id}`**, derived from the token (see "Git Versioning"). 404 on older backends ⇒ treated as not-versioned |
 | POST | `/api/v1/cli/agents/{id}/exec` | CLI JWT | Streaming SSE command execution |
 | WSS  | `/api/v1/cli/agents/{id}/sync-stream` | CLI JWT | Mutagen transport tunnel |
 | POST | `/api/v1/cli/account/login/start` | None | Begin a `cinna login` device-authorization request |
 | POST | `/api/v1/cli/account/login/poll` | None | Poll a `cinna login` request — always HTTP 200 + `status` |
 | 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) |
+
+`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`.
 
-The account-workspace surface adds the broader `/api/v1/cli/account/*` route group (login, agents, credentials, connect, schedules, status, api-proxy); only the routes the sync / login / doctor paths use are listed here.
+The account-workspace surface adds the broader `/api/v1/cli/account/*` route group (login, agents, credentials, connect, schedules, status, api-proxy, files/upload); only the routes the sync / login / doctor / chat paths use are listed here.
 
 Endpoints that were part of the old Docker-replica model (`build-context`, `workspace` POST, `workspace/manifest`, `credentials`) have been removed from the backend and from this CLI.
 
@@ -528,6 +701,21 @@ git push origin main && git push origin v0.1.5
 
 ---
 
+## Feature Documentation
+
+Per-feature docs live under `docs/features/{feature}/` in up to three layers:
+`{feature}.md` (business logic / reasoning), `{feature}_tech.md` (implementation +
+file refs), `{feature}_acceptance.md` (live e2e scenarios a testing agent runs
+against a real environment). Author new ones with the `/cinna-cli.feature.doc`
+command (`.claude/commands/cinna-cli.feature.doc.md`) and validate references with
+`scripts/check_docs_references.py`.
+
+| Feature | Docs | Summary |
+|---------|------|---------|
+| Git Versioning (`cinna git`) | [business](features/git_versioning/git_versioning.md) · [tech](features/git_versioning/git_versioning_tech.md) · [acceptance](features/git_versioning/git_versioning_acceptance.md) | Version an agent's workspace with git against its external remote (commit/push/pull/rollback) alongside live Mutagen sync. |
+
+---
+
 ## Related Projects
 
 - **cinna-core** — the platform backend. Hosts the API routes this CLI calls, the agent runtime, env core, building mode, and the web UI. Source plan for this CLI feature: `cinna-core/docs/drafts/cinna-cli-live-sync_plan.md`.