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

{cinna_cli-0.2.6 → cinna_cli-0.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cinna-cli
-Version: 0.2.6
+Version: 0.3.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
@@ -259,6 +259,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.3.0}/README.md

@@ -222,6 +222,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.3.0}/docs/README.md

@@ -201,6 +201,10 @@ 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
@@ -289,6 +293,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

cinna_cli-0.3.0/docs/features/local_agent_import/local_agent_import.md

@@ -0,0 +1,181 @@
+# Local Agent Import (`cinna agent import`)
+
+## Purpose
+
+Take an agent that was built **entirely offline** — with any coding assistant,
+by a user who did not yet have a Cinna account — and put it on the platform in
+one verb: the cloud agent is created, its prompts and metadata are written, a
+local workspace is attached, the files are copied and pushed, credential drafts
+and schedules are created, and the local manifest is stamped with the cloud
+link.
+
+This is the "go-cloud" step of the **Local Agent Kit**: the platform serves a
+public, unauthenticated kit (`GET /agent-start`) that teaches an assistant how to
+scaffold `~/Documents/MyAgents/Local/<slug>/` — a folder whose layout is
+byte-compatible with a cloud agent workspace and whose `cinna-agent.json`
+manifest carries the definitional metadata a bundle revision carries. `cinna
+agent import` is the only CLI verb that reads that manifest.
+
+The kit's machine-readable half is a **versioned contract** (`layout.json`,
+`CONTRACT_VERSION`, the JSON schemas), served separately at
+`GET /api/agent-start/contract.tar.gz` with a cheap version poll at
+`GET /api/agent-start/contract/version`. cinna-cli reads the copy installed at
+`.cinna-kit/`; a shipped build should obtain it from those routes rather than
+vendoring one.
+
+Nothing platform-side is new: the import replays the manifest through the
+existing account-scoped verbs (`agent create`, the bulk prompt write, `agent
+sync`, `sync push`, `account credentials create`, `agent schedule create`,
+`agent status set-command`).
+
+## Mental model
+
+- **The manifest is the plan.** `cinna-agent.json` (at the agent folder root)
+  says what the agent *is*: name, slug, description, example prompts, router
+  trigger, which files hold the three prompts, the status refresh command, the
+  credentials it needs, and its schedules. The import writes exactly that and
+  invents nothing.
+- **Two folders, one direction.** `Local/<slug>/` is where the agent was built;
+  `Cloud/` is the account workspace (`cinna login <host> --dir Cloud`). Import
+  runs **from `Cloud/`** and pushes `Local/<slug>/` into
+  `Cloud/agents/<slug>/workspace/`. After a successful import the cloud copy is
+  the live one — keep iterating there with `cinna dev`, or keep experimenting
+  locally and re-import with `--update`.
+- **The contract is the authority.** The folder rules — what may be copied to
+  the cloud, what can hold a credential value — are **data**, not prose:
+  `.cinna-kit/layout.json`, published by cinna-core and read by three hosts
+  (Cinna Desktop, a coding assistant's kit tools, and this CLI). Import reads
+  them from that file rather than re-deriving them, so a correction cinna-core
+  publishes reaches this tool on the next kit refresh instead of waiting for a
+  new cinna-cli. When the contract cannot be found the run falls back to a
+  built-in copy and says so as a **degradation**, not as a mode.
+- **Secrets never travel.** `credentials/` (which holds the local `.env`) and
+  `app-data/` (runtime state) are never copied — not even if the contract is
+  edited to allow them. On top of the exclude list the contract carries rules a
+  glob list cannot express: every dotenv shape (`.env`, `.env.prod`,
+  `staging.env`) is withheld wherever it sits, while `.env.example`,
+  `.env.sample` and `.env.template` still travel. Credentials are created as
+  **empty drafts** and the command prints the URLs the user opens to fill each
+  one in the browser. No secret value is read, sent, or printed at any point.
+- **The ledger is a sibling file, never a manifest key.** Where an agent folder
+  has been published is recorded in `publications.json` beside
+  `cinna-agent.json` — one entry per Cinna instance. It has to be a separate
+  file: each entry records a hash *of the exported tree*, the manifest is a
+  member of that tree, so a hash written into the manifest could never match the
+  tree it describes. The folder would read "1 unpublished change" the instant a
+  publish succeeded, and republishing to clear it would create the next
+  mismatch.
+- **Every step is idempotent.** The agent is matched by the ledger entry for
+  this instance, credentials by name, schedules by name. A run that dies halfway
+  is resumed with `--update`; nothing is duplicated.
+- **The record is the commit point.** `publications.json` is written **only
+  after the workspace push settled**. If the push failed, was skipped
+  (`--no-push`), or left conflicts, nothing is recorded and the re-run is a
+  plain `--update`.
+
+## The nine steps
+
+Each prints as `[n/9]`:
+
+1. **Manifest** — load and validate `cinna-agent.json`; refuse a
+   `schema_version` newer than this CLI understands, a slug that disagrees with
+   the folder name, a malformed cron, a credential without a type. Then the
+   contract: refuse a folder built against a newer **major** contract version,
+   warn on an older one or on a folder that records none, resolve the exclude
+   list and the secret rules, plan the copy and compute the tree's
+   `content_hash`.
+2. **Agent** — resolve by the `publications.json` entry for this instance
+   (requires `--update`) or create a new agent in the active user workspace
+   (`--workspace` overrides).
+3. **Prompts + metadata** — one bulk write carrying `description`,
+   `router_trigger_prompt`, `example_prompts`, and the three document prompts
+   read from the files named in `prompts`; then the status refresh command.
+4. **Workspace** — reuse the synced workspace under `agents/<slug>/` if the
+   agent already has one, otherwise run `cinna agent sync`.
+5. **Copy** — copy the tree into `agents/<slug>/workspace/`, honouring the
+   contract's exclude list and secret rules, and generate
+   `workspace_requirements.txt` from `pyproject.toml` when the agent does not
+   ship one.
+6. **Push** — `cinna sync push` equivalent (skipped by `--no-push`).
+7. **Credentials** — one empty draft per spec, attached to the agent; an
+   existing credential of the same name is attached rather than recreated.
+   Setup URLs are collected for the summary.
+8. **Schedules** — one per spec, name-idempotent; `--update` rewrites an
+   existing schedule in place.
+9. **Record** — add or update this instance's entry in `publications.json`
+   (`platform_url`, `agent_id`, `workspace`, `imported_at`, `updated_at`,
+   `contract_version`, `content_hash`) and print the summary (agent id, web UI
+   link, workspace path, credential setup URLs, and the `cinna chat`
+   verification line).
+
+## User flows
+
+### First import
+
+1. In the kit root: `cinna login <platform> --dir Cloud` (once).
+2. `python3 .cinna-kit/tools/kit.py validate Local/<slug>` — must pass.
+3. `cd Cloud && cinna agent import ../Local/<slug>`.
+4. Confirm the plan (or pass `--yes`), then open the printed credential setup
+   URLs and fill the secrets in the browser.
+5. Verify: `cinna chat --agent <slug> "<first example prompt>"`.
+
+### Look before you leap
+
+`cinna agent import ../Local/<slug> --dry-run` prints the whole plan — every
+file that would be copied, every credential draft, every schedule — and makes
+**zero** platform calls and zero local writes.
+
+### Re-import after more local work
+
+`cinna agent import ../Local/<slug> --update` — resolves the agent by the
+`publications.json` entry whose `platform_url` matches the instance you are
+logged into (not by workspace, and not by position in the list), rewrites
+prompts and metadata, re-copies the tree, pushes, attaches existing credentials,
+and updates the schedules in place.
+
+### Resume a partial import
+
+If the run died before the record was written, `--update` reattaches by a unique
+name match (and refuses when several agents share the name — add the entry to
+`publications.json` manually to disambiguate). Credentials and schedules already
+created are reused, not duplicated.
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--name TEXT` | Override the manifest's display name for the *created* agent |
+| `--workspace REF` | Target user workspace (name or id; `default` for the Default one) for the agent and its credential drafts |
+| `--update` | Re-import into the agent the manifest points at (required for any second run) |
+| `--dry-run` | Print the plan; no platform call, no local write |
+| `--no-push` | Copy the files but skip the sync push (leaves the manifest unstamped) |
+| `--yes` / `-y` | Skip the confirmation prompt |
+
+## Failure modes and what they mean
+
+| Situation | Behaviour |
+|-----------|-----------|
+| Not in an account workspace | The standard "not in a cinna account workspace" error — run `cinna login <host> --dir Cloud` first |
+| `cinna-agent.json` missing | Refused, with the hint that the path must be the agent folder |
+| `schema_version` newer than supported | Refused with an upgrade hint — never half-read |
+| Folder built against a newer **major** contract version | Refused with an upgrade hint — a minor or patch difference is not a compatibility question and passes silently |
+| Folder records no `contract_version` | Warned and imported — every folder created before contract 1.0.0 is in that state |
+| Already imported to this instance, no `--update` | Refused, naming the agent id and where the link was recorded |
+| The recorded agent id is not among your agents | Refused — you are logged into a different platform, or the agent was deleted |
+| `--update` with several name matches | Refused, listing them; add the `publications.json` entry to disambiguate |
+| Push failed or left conflicts | Warned, **nothing recorded**, with the resolve + `--update` hint |
+| `.cinna-kit/layout.json` missing or unreadable | Imported with the built-in contract copy, the `Exclusions:` line marked `DEGRADED`, and **no `content_hash` recorded** — a hash over a file set another host would not select is worse than none |
+| A travelling file or directory cannot be read | Refused — a complete-looking export with a subtree missing from it is the one outcome worth stopping for |
+| `publications.json` unreadable | Refused, and the file is left exactly as it was |
+| Credential/schedule 403 | The platform error surfaces verbatim; earlier steps stay done and `--update` resumes |
+| A file under `credentials/` or `app-data/`, or any dotenv shape, reaches the copy plan | Hard refusal — the exclude list or the secret rules are broken, and that is a bug to report, not to work around |
+
+## Related
+
+- [Agent Management](../agent_management/agent_management.md) — `agent create`,
+  `agent sync`, `agent show`, `agent status set-command`.
+- [Agent Schedules](../agent_schedules/agent_schedules.md) — the schedule verbs
+  the import replays.
+- [Account Workspace](../account_workspace/account_workspace.md) — the `Cloud/`
+  workspace, credential drafts, and the bulk prompt write.
+- [Live Sync](../live_sync/live_sync.md) — what `sync push` actually does.

cinna_cli-0.3.0/docs/features/local_agent_import/local_agent_import_acceptance.md

@@ -0,0 +1,264 @@
+# Local Agent Import — Acceptance Scenarios (live e2e)
+
+Real-usage scenarios for an agent doing *integration* testing of `cinna agent
+import` against a **live** platform: a real backend, a real account workspace,
+and a real local agent folder. These are not unit tests — they exercise agent
+creation, the bulk prompt write through the escape hatch, child-token minting,
+Mutagen sync, credential drafting, and schedule CRUD end to end.
+
+How to use: pick the scenarios relevant to the change, run the **Steps**
+verbatim, assert the **Expected**, and watch for the **Watch for** failure
+modes. Scenarios 3–6 (idempotency and the stamp) are the highest-value ones for
+any change to the orchestrator.
+
+## Preconditions
+
+- A reachable platform with an **account workspace**: `Cloud/.cinna/account.json`
+  (created by `cinna login <platform> --dir Cloud`). Every command below runs
+  from inside `Cloud/`.
+- The account's user can create agents (`agent-developer` role) — otherwise
+  step 2 returns 403.
+- **Editable install** of the CLI under test:
+  `python3 -c "import cinna,os;print(os.path.dirname(cinna.__file__))"` points at
+  this repo's `src/cinna`; `cinna agent import --help` lists all six flags.
+- Mutagen installed (the import pushes through a real sync session).
+- A **local agent folder** at `../Local/<slug>/` holding a valid
+  `cinna-agent.json` — scaffold one with the kit
+  (`python3 .cinna-kit/tools/kit.py new <slug>`), fill the three prompt files,
+  declare one credential and one schedule, and put a throwaway secret in
+  `credentials/.env` so the secret-leak assertions are meaningful.
+
+## Scenario catalog
+
+### 1. Dry run shows the plan and touches nothing
+
+- **Goal:** the user can inspect the import before committing to it.
+- **Steps:**
+  ```
+  cinna agent import ../Local/<slug> --dry-run
+  ```
+- **Expected:** the file list, credential drafts, and schedules are printed;
+  "Dry run — nothing was sent to the platform."; `cinna account agents` shows no
+  new agent; `../Local/<slug>/cinna-agent.json` still has `cloud.agent_id: null`.
+- **Watch for:** any HTTP request in `-v` output; a workspace appearing under
+  `agents/`.
+
+### 2. First import, end to end
+
+- **Steps:**
+  ```
+  cinna agent import ../Local/<slug> --yes
+  ```
+- **Expected:** nine `[n/9]` steps; the agent exists in the UI with the
+  manifest's description, example prompts, and router trigger (`cinna agent show
+  <slug> --prompts` matches the three local prompt files); `agents/<slug>/`
+  exists and `agents/<slug>/workspace/` holds the agent's files;
+  `cinna exec --agent <slug> ls` on the remote env lists the same files; the
+  credential appears as **needs setup** with the printed setup URL; the schedule
+  is listed by `cinna agent schedule list <slug>`; the status refresh command is
+  set (`cinna agent status show <slug>`); the manifest's `cloud` block now
+  carries `platform_url`, `agent_id`, `imported_at`.
+- **Watch for:** `credentials/` or `app-data/` reaching the remote env (check
+  with `cinna exec --agent <slug> ls -a`); any secret value in the terminal
+  output; `workspace_requirements.txt` missing when the agent has a
+  `pyproject.toml`.
+
+### 3. Second import without `--update` is refused
+
+- **Steps:** re-run scenario 2's command.
+- **Expected:** exit ≠ 0, the error names the agent id and tells you to pass
+  `--update`; nothing changed on the platform.
+- **Watch for:** a **second** agent with the same name appearing.
+
+### 4. `--update` re-imports without duplicating
+
+- **Steps:** edit `docs/WORKFLOW_PROMPT.md` and a script locally, then <!-- nocheck: path inside the local agent folder, not this repo -->
+  ```
+  cinna agent import ../Local/<slug> --update --yes
+  ```
+- **Expected:** the same agent id; `cinna agent show <slug> --prompts` shows the
+  edited workflow prompt; the edited script is live in the env; **no** second
+  credential (the existing one is re-attached) and **no** second schedule (it is
+  updated in place); `cinna account credentials list` count unchanged.
+- **Watch for:** a duplicate empty credential draft shadowing the one the user
+  already filled — that would break the running agent.
+
+### 5. The stamp only happens after a successful push
+
+- **Steps:**
+  ```
+  cinna agent import ../Local/<slug2> --no-push --yes
+  ```
+- **Expected:** files are copied into `agents/<slug2>/workspace/`, the manifest
+  is **not** stamped, and the output tells you to `cinna sync push --agent
+  <slug2>` and re-run with `--update`.
+- **Watch for:** a stamped manifest pointing at an agent whose environment never
+  received the files.
+
+### 6. Resume after a mid-run failure
+
+- **Goal:** a partial import is recoverable.
+- **Steps:** cause step 7 to fail (e.g. an unreachable platform, or a credential
+  type the account cannot create), then fix it and re-run with `--update`.
+- **Expected:** the second run reuses the agent (by name when the manifest is
+  unstamped, by id when stamped), skips what already exists, and completes.
+- **Watch for:** a second agent created because the name match was ambiguous —
+  the command must **refuse** with a "set cloud.agent_id" hint, not guess.
+
+### 7. Targeting a user workspace
+
+- **Steps:**
+  ```
+  cinna account user-workspace list
+  cinna agent import ../Local/<slug3> --workspace "<Workspace Name>" --yes
+  ```
+- **Expected:** the agent and its credential drafts land in that workspace
+  (visible in the UI sidebar and in `cinna account agents`).
+- **Watch for:** the agent in the target workspace but the credential in Default
+  — the agent then cannot see its own credential.
+
+### 8. Manifest guards
+
+- **Steps:** in a scratch copy of the agent folder, one at a time: bump
+  `schema_version` to `2`; rename the folder so it disagrees with `slug`; make
+  `cron_string` `"every morning"`; drop a credential's `type`.
+- **Expected:** each is refused *before* any platform call, with a message that
+  names the offending field.
+- **Watch for:** a half-applied import (agent created, then the manifest
+  rejected).
+
+### 9. Secrets never leave the machine
+
+- **Steps:** with a recognizable secret in `credentials/.env`, run a full import
+  with `-v`, then
+  ```
+  cinna exec --agent <slug> "grep -r '<secret>' . | head"
+  ```
+- **Expected:** no match remotely; the secret appears nowhere in the CLI output
+  or logs; `credentials/` does not exist in the remote workspace.
+- **Watch for:** a `.env` copied because it sat outside `credentials/` — the
+  import must refuse the plan outright in that case. Scenario 10b covers the
+  `.env.<suffix>` shapes that used to clear every gate.
+
+### 10. The contract's exclude list is honoured, and it is `layout.json`
+
+- **Goal:** a correction cinna-core publishes reaches this tool on the next kit
+  refresh instead of waiting for a new cinna-cli release.
+- **Setup:** a `.cinna-kit/layout.json` above the agent, and a `notes/` folder
+  inside it.
+- **Steps:** give `layout.json` a `cloud_import_excludes` list that adds
+  `notes/` **and** omits `credentials/`; import into a fresh agent. Then edit
+  the list on disk (add `config/`) and re-run with `--update`.
+- **Expected:** `notes/` is absent remotely; `credentials/` is *still* absent
+  (the mandatory exclusion cannot be removed); the `Exclusions:` line names the
+  `layout.json` path it read and does **not** say `DEGRADED`; the second run
+  drops `config/` without any change to cinna-cli.
+- **Watch for:** the built-in list being used silently when a `layout.json`
+  exists; and a `kit.json` `cloud_import.exclude` still being honoured —
+  decision D6 deleted that key and reading it back would be a second authority
+  for one list.
+
+### 10a. A missing contract is reported as a degradation
+
+- **Goal:** the failure that made the previous regression invisible. The old
+  line read `Exclusions: built-in default list` — it announced a *mode*, so
+  nobody saw an error and the first symptom was a `.env.prod` in a cloud
+  workspace.
+- **Steps:** import an agent with **no** `.cinna-kit/` anywhere above it.
+- **Expected:** the run succeeds; the `Exclusions:` line begins `DEGRADED —`
+  and says why; **no `content_hash` is recorded** in `publications.json` and the
+  run prints `Content hash: WITHHELD`.
+- **Watch for:** a hash recorded anyway. "But the fallback is the same list" is
+  a claim about this build's contract, not about the one in the folder — which
+  is the only one the other host is reading.
+
+### 10b. Dotenv suffixes never travel, examples still do
+
+- **Goal:** the leak the contract's `secret_files` rules close. `.env.prod` and
+  `.env.local` clear every glob in the exclude list *and* the old
+  `endswith(".env")` check, at the agent root and at any depth.
+- **Setup:** in the agent folder, outside `credentials/`, create `.env.prod`,
+  `config/.env.staging`, `staging.env` and `.env.example`, each with a
+  recognizable secret except the example.
+- **Steps:**
+  ```
+  cinna agent import ../Local/<slug> --dry-run
+  cinna agent import ../Local/<slug> --update -y
+  cinna exec --agent <slug> "ls -a; ls -a config 2>/dev/null"
+  ```
+- **Expected:** the dry-run plan lists `.env.example` and none of the others;
+  remotely only `.env.example` exists; the secret string appears nowhere in the
+  output.
+- **Watch for:** `.env.example` being withheld too — that is the `unless` block
+  doing its job, and a fix written as a bare `startswith(".env.")` loses it.
+
+### 10c. A withheld secret does not move the `content_hash`
+
+- **Goal:** "unpublished changes forever" — a path withheld from the upload but
+  counted in the hash makes the hash move for a change that can never be
+  published.
+- **Steps:** import once and note `publications.json`'s `content_hash`. Edit
+  `.env.prod` (a withheld file) and re-run `--update`; then edit
+  the agent's own `docs/WORKFLOW_PROMPT.md` (a travelling file) and re-run <!-- nocheck: a path inside the agent folder, not this repo -->
+  again.
+- **Expected:** the hash is unchanged after the first edit and different after
+  the second. Immediately after any successful import, the recorded hash matches
+  a fresh scan of the folder — the folder is never "behind" the instant a
+  publish succeeds.
+- **Watch for:** a hash that moves on the very first re-run with no edits at
+  all. That means the manifest was written *after* the hash was computed.
+
+### 10d. The ledger is a sibling file, and the legacy `cloud` block migrates
+
+- **Goal:** `publications.json` is written, `cloud` is retired behind it, and no
+  `--update` ever creates a second agent.
+- **Setup:** an agent folder carrying a legacy `cloud` block naming a real
+  `platform_url` and `agent_id`, and no `publications.json`.
+- **Steps:** run `--update` against that instance, then inspect both files, then
+  run `--update` once more.
+- **Expected:** the first run resolves the agent from the `cloud` block and does
+  **not** create a new one; afterwards `cinna-agent.json` has no `cloud` key,
+  `publications.json` holds an entry for that `platform_url`, and
+  `publications.json` is **not** present in the remote workspace. The second run
+  resolves from the ledger and is a no-op on identity.
+- **Watch for:** a second agent appearing on the platform (the deprecated read
+  was dropped too early); a `cloud` block deleted while the ledger recorded
+  nothing (a destination must be reached before the source may be removed); a
+  `publications.json` that travelled.
+
+### 10e. Two instances, resolved by `platform_url`
+
+- **Goal:** the resolution key is part of the contract — not `workspace`, not
+  position in the array.
+- **Setup:** two account workspaces for two different platform hosts.
+- **Steps:** import the same agent folder into instance A, then into instance B,
+  then re-run `--update` against A.
+- **Expected:** `publications.json` holds two entries; the A re-run updates A's
+  agent and leaves B's entry byte-identical; an entry whose `workspace` key is
+  absent entirely still resolves (that is the shape Cinna Desktop writes).
+- **Watch for:** the second import being refused as "already imported", or the
+  A re-run updating B's entry.
+
+### 10f. The `contract_version` gate
+
+- **Steps:** set the manifest's `contract_version` to `2.0.0` and import; then
+  to `1.4.2` and import; then remove the key entirely and import.
+- **Expected:** `2.0.0` is refused before any platform call, naming `2.x`;
+  `1.4.2` passes **silently** (same major — a minor contract change is additive
+  by definition and reaches a non-adopting reader as silence); the missing key
+  warns about a re-stamp and imports anyway.
+- **Watch for:** a warning on the same-major pair. That is the gate's shape, not
+  a bug: anything an old reader must notice needs a major bump.
+
+### 11. Verification loop the guide promises
+
+- **Steps:**
+  ```
+  cinna chat --agent <slug> "<first example prompt>"
+  ```
+- **Expected:** the agent answers using its imported workflow prompt and
+  scripts. With the credential still empty, it should say what it needs rather
+  than crash.
+- **Watch for:** prompts that landed in the DB but not in the env — if the env
+  was already running, `cinna api POST agents/<id>/sync-prompts` is the manual
+  push.