create-snipara 2.1.1 → 2.2.1

package/README.md

@@ -1,11 +1,27 @@
 # create-snipara
 
-**One-command onboarding for Snipara Cloud or self-hosted Snipara Server.**
+**Set up local coding work or connect your project to Snipara context.**
 
 `create-snipara` connects a local project to Snipara so AI agents can start
 with project-owned context, reviewed memory, shared guidance, and optional code
 impact tooling instead of starting cold every session.
 
+## Choose your first step
+
+| Goal | Command | Requirements |
+| --- | --- | --- |
+| Track and verify local coding work | `npx create-snipara@latest init --profile local-work --client codex` | Supported Node.js and Python; no Snipara account |
+| Connect sourced project context | `npx create-snipara@latest` | Authorized Snipara project connection |
+| Connect an existing self-hosted server | Use `--self-hosted` with its endpoint | Running server and operator credentials |
+
+Use `--client claude-code` for Claude Code. Local work prepares compatible
+Companion, Orchestrator and Sandbox tools. It does not install Docker or
+dependency images, run tests or call a model. Hosted context is optional for
+local work; add `--connect-context` when you want to set it up explicitly.
+See [install profiles](#install-profiles) for the full contract.
+
+## Connect project context
+
 The shortest path is three moments: connect the folder your agent already uses,
 let Snipara index its project context, then ask one question that only the
 project can answer.
@@ -24,7 +40,7 @@ npx create-snipara@latest --self-hosted \
   --client claude-code
 ```
 
-Both modes aim to finish with the same visible proof:
+Both context connection modes aim to finish with the same visible proof:
 
 ```text
 ✓ Endpoint connected
@@ -36,7 +52,7 @@ Both modes aim to finish with the same visible proof:
 `create-snipara` is the single activation engine for the agent path. It detects
 or asks where Snipara should run, writes the right MCP config, seeds a small
 README/docs corpus, and automatically verifies a first project-grounded answer.
-The default path is Cloud because it is the fastest first experience; the same
+The default context path is Cloud; the same
 flow works with an existing self-hosted Snipara Server.
 It is also the canonical activation engine behind editor setup docs: VS Code can
 surface activation as a native command, Cursor can pair OpenVSX UI with Hosted
@@ -111,6 +127,60 @@ activation report or JSON summary.
 
 ## Install Profiles
 
+The normal prompt offers **Context** (`hosted-only`) and **Local work**
+(`local-work`). Advanced choices below remain available.
+
+```sh
+npx create-snipara@latest init --profile local-work --client codex
+npx create-snipara@latest doctor
+npx create-snipara@latest repair --profile local-work
+npx create-snipara@latest toolchain status
+npx create-snipara@latest toolchain rollback
+```
+
+Local work runs locally without a Snipara account or cloud subscription. If an
+existing repository connection is authorized, its native broker automatically
+reuses that context. A configured or pending connection alone is not proof of
+authorization; disconnected users continue locally. To explicitly start optional
+context onboarding, add `--connect-context`. This never becomes a prerequisite
+for local tasks or validation, and a global API key does not select a project.
+
+Local work prepares compatible private Companion, Orchestrator and Sandbox
+versions, checks their versions and installed command hashes, then atomically
+selects the completed bundle. It uses the existing Node/npm and Python runtimes;
+Node.js must already be version 18+ and Python version 3.10+; incompatible
+runtimes fail before virtual-environment creation or package installation. It
+does not install an operating-system runtime, Docker, dependency images or a
+model provider. Package preparation uses a private home and no provider keys.
+Preparation failure keeps the prior active bundle and its failure receipt.
+Repeated preparation verifies the current matching bundle; rollback checks the
+previous bundle without resetting tasks, evidence, configuration or secrets.
+Explicit repair can replace a changed owned bundle while retaining its original
+files and a recovery reference. Foreign active pointers are refused. Interrupting
+preparation stops and reaps its child before releasing installation ownership;
+an unobserved cleanup keeps the lock for reconciliation.
+
+The native connection starts the retained Companion `toolchain mcp` bootstrap;
+each new session selects and pins the active bundle. Its configuration contains
+no Snipara or provider keys. Existing source-bound `snipara-repository` connections
+are preserved; local work does not add a direct hosted server alongside that
+binding. Fresh local-work setup adds no hosted server, project binding, API-key
+environment files or automatic upload. Explicit context setup retains the
+existing project/auth flow and makes no automatic repository binding claim.
+Installing components is
+separate from connecting a project and observing a grounded first answer.
+Both Claude's JSON and Codex's complete TOML are inspected before choosing this
+path, with the canonical source helper validating the configured fingerprint
+against the current repository or folder. Existing Codex inspection needs
+Python 3.11+, or Python 3.10 with `tomli`; a missing parser produces an explicit
+setup error. A source mismatch never falls back to another hosted project.
+
+Codex setup validates the complete TOML with the prepared Python parser and
+appends only an absent managed connection. Existing unrelated bytes stay intact.
+Conflicting or malformed configuration is preserved and setup reports incomplete;
+it is never replaced with a guessed configuration. Repair and upgrade remember
+the local-work selection from existing activation/native configuration.
+
 The CLI now works around explicit install profiles:
 
 | Profile            | What it installs                              | Best for                                                                                                            |