@cairnkeep/cli 2.9.0 → 2.11.0

package/docs/learning/README.md

@@ -52,6 +52,8 @@ expanded only after their labs are executable.
 | L19 | [Validated skill improvement](lessons/L19-validated-skill-improvement.md) | Ready | 50 min |
 | L20 | [Least-authority MCP tool profiles](lessons/L20-mcp-tool-profiles.md) | Ready | 25 min |
 | L21 | [Immutable context packs and skill approval](lessons/L21-context-packs.md) | Ready | 40 min |
+| L22 | [Operate Cairnkeep on native Windows](lessons/L22-native-windows.md) | Ready | 30 min |
+| L23 | [Guided setup and Pi memory](lessons/L23-guided-setup.md) | Ready | 35 min |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.9.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.9.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.9.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.11.0
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.9.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.11.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.9.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -41,7 +41,7 @@ machine-level steps.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.9.0
+   npm install --global @cairnkeep/cli@2.11.0
    cairn --version
    ```
 
@@ -72,6 +72,15 @@ machine-level steps.
    Use `cairn completion zsh` or `cairn completion fish` for those shells.
    Completion is a convenience and is not another runtime component.
 
+   On native Windows PowerShell, use:
+
+   ```powershell
+   Invoke-Expression (& cairn completion powershell | Out-String)
+   ```
+
+   Bootstrap emits `.cmd` launchers on Windows; use
+   `.\.ai\start-claude.cmd` instead of the Unix `.sh` launcher.
+
 ## Verify
 
 Run both checks:

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.9.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.9.0
+**Tested with:** Cairnkeep 2.11.0
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.9.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.9.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.11.0 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

package/docs/learning/lessons/L22-native-windows.md

@@ -0,0 +1,83 @@
+# L22 - Operate Cairnkeep on native Windows
+
+**Status:** Ready
+**Track:** Operator
+**Time:** 30 minutes
+**Tested with:** Cairnkeep 2.11.0, Windows x64, and Node.js 22 or newer
+
+## Outcome
+
+You can prove that Cairnkeep is running natively from PowerShell, bootstrap a
+path containing spaces, inspect its security boundary, and perform a reversible
+uninstall without relying on WSL or Git Bash.
+
+## Exercise
+
+From PowerShell:
+
+```powershell
+npm install --global @cairnkeep/cli@2.11.0
+cairn version
+
+$Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'
+New-Item -ItemType Directory -Force -Path $Lab | Out-Null
+cairn bootstrap $Lab
+cairn sync --apply --live-root (Join-Path $Lab '.claude-test')
+cairn sync --check --live-root (Join-Path $Lab '.claude-test')
+Push-Location $Lab
+cairn doctor
+Pop-Location
+```
+
+Verify that `.ai/start-claude.cmd`, `.ai/start-harness.ps1`, and the managed
+Claude assets exist. `cairn doctor` must identify native Windows x64 and complete
+an MCP stdio handshake.
+
+## Permission check
+
+```powershell
+Get-Acl (Join-Path $Lab '.ai\capabilities.json') | Format-List
+```
+
+Managed private files remove inherited broad access and retain only the current
+identity, Local System, and Administrators. Do not replace this with a Unix-mode
+check; Windows authorization is an ACL contract.
+
+## Recovery exercise
+
+```powershell
+cairn uninstall --dry-run --live-root (Join-Path $Lab '.claude-test') $Lab
+cairn uninstall --yes --live-root (Join-Path $Lab '.claude-test') $Lab
+```
+
+The command prints the timestamped backup location. Inspect `manifest.json` and
+`revert.ps1`; run the revert script only if you intentionally want to restore
+the removed managed assets.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| `cairn.cmd` is not found | npm's global directory is not on `PATH` | Run `npm prefix -g`, add the resulting directory to the user `PATH`, then open a new PowerShell session |
+| Hook registration reports drift | Managed `.cmd` hook or settings entry is absent | Run `cairn sync --apply`, then repeat `cairn sync --check` |
+| Memory export fails | `sqlite3.exe` is absent | Install SQLite and confirm `Get-Command sqlite3.exe`; runtime and import remain available |
+| A private-state check fails | The file inherited a broader ACL | Preserve the file, inspect it with `Get-Acl`, and recreate it through the owning Cairnkeep command |
+
+## Privacy and trust boundary
+
+Native support changes process, path, and permission mechanics; it does not
+enable a network, model, capture, artifact, context-pack, or capability flag.
+The Windows ACL is a local-host access boundary, while pack digests establish
+content integrity rather than publisher authenticity. Task Scheduler and purge
+operations remain separate explicit actions.
+
+## Boundaries
+
+- Windows x64 is native; Windows ARM64 is currently x64 emulation.
+- `sqlite3.exe` is optional for runtime and import, but required for a WAL-safe
+  memory export.
+- WSL is a separate Linux topology. Git Bash is not native-Windows evidence.
+- Task Scheduler changes remain opt-in through `cairn audit-timer`.
+
+See [Native Windows operation](../../native-windows.md) for the complete
+platform contract.

package/docs/learning/lessons/L23-guided-setup.md

@@ -0,0 +1,138 @@
+# L23 - Guided setup and Pi memory
+
+**Status:** Ready
+**Track:** Quickstart and Operator
+**Time:** 35 minutes
+**Tested with:** Cairnkeep 2.11.0; Pi 0.84.1; Node.js 22, 24, and 26
+
+## Outcome
+
+You can classify a missing or empty target, replay setup without a TTY, explain
+the limitations of Git-less mode, verify Pi's local stdio memory bridge, and
+recover or uninstall every managed asset without hidden machine changes.
+
+## Prerequisites
+
+- Node.js 22 or newer, npm, and Git for the main exercise.
+- Pi 0.84.1 or newer.
+- A disposable parent directory containing no credentials, secrets, private
+  state, or identifying project data.
+
+## Exercise
+
+Start with a missing target. The explicit flags make this deterministic and
+safe to replay from a non-interactive or non-TTY process:
+
+```bash
+lab=/tmp/cairnkeep-guided-setup-lab
+cairn setup "$lab" --git init --harness pi --memory local --yes
+cd "$lab"
+cairn doctor
+```
+
+Setup performs its classification before it creates `.ai`, `.planning`, or
+`.agentfs`. It initializes Git only because `--git init` authorizes that action,
+records the selected Pi harness in private `.ai/cairnkeep.json`, and reports
+created, updated, unchanged, and skipped assets. Repeating the same `cairn
+setup` command should report the managed files as unchanged.
+
+Project setup never changes the Pi installation. Apply and check machine assets
+explicitly, then diagnose the project again:
+
+```bash
+cairn sync-pi --apply
+cairn sync-pi --check
+cairn doctor
+./.ai/start-pi.sh
+```
+
+In the disposable Pi session, list the registered Cairnkeep tools and make one
+harmless read-only memory call. The extension starts `cairn memory-server` as a
+local stdio child in this project; it does not select HTTP or a remote server.
+Cancel one in-flight call and confirm a later read still works. Exit Pi normally
+and confirm shutdown completes rather than leaving a memory-server child
+running. Cancellation is per call and an awaited session shutdown owns child
+termination.
+
+The bridge discovers the effective server catalog. Full, read-only, and custom
+MCP profiles therefore expose only the tools allowed by the server. It preserves
+tool names, stable order, input and output schemas, original content,
+`structuredContent`, `_meta`, and the exact Phase 21 annotations in trusted
+bridge metadata and result `details`. Pi 0.84.1 has no native annotations field
+in its public tool API: do not interpret this preservation as native
+model-facing annotation propagation and do not invent such a field.
+
+To see the intentional Git-less boundary in another empty disposable target:
+
+```bash
+limited=/tmp/cairnkeep-guided-setup-limited
+cairn setup "$limited" --git none --harness pi --memory local --yes
+cd "$limited"
+cairn doctor
+```
+
+The result is `limited`, not `complete`. Launchers and local stdio memory remain
+available, but repository-identity and Git-dependent features do not. An
+existing non-Git tree is never initialized without explicit `--git init`.
+
+## Recovery exercise
+
+Delete one setup-owned launcher only in the disposable project, diagnose it,
+then replay the exact recovery command:
+
+```bash
+cd /tmp/cairnkeep-guided-setup-lab
+rm .ai/start-pi.sh
+cairn doctor
+cairn setup . --git init --harness pi --memory local --yes
+cairn sync-pi --apply
+cairn sync-pi --check
+cairn doctor
+```
+
+Doctor reports project-state drift separately from missing or drifted Pi
+machine assets. Setup repairs only recorded project assets; `cairn sync-pi
+--apply` repairs only the package-owned Pi extension and prompt paths.
+
+Preview backup-first removal before confirming it:
+
+```bash
+cairn uninstall --dry-run /tmp/cairnkeep-guided-setup-lab
+cairn uninstall --yes /tmp/cairnkeep-guided-setup-lab
+```
+
+Inspect the printed backup bundle and generated revert script. Durable memory
+and context packs remain unless their separate purge flags are supplied.
+
+## Common failures
+
+| Symptom | Cause | Recovery |
+|---|---|---|
+| Setup refuses a missing target | The non-interactive command omitted an explicit choice or `--yes` | Supply the target, `--git`, `--harness`, `--memory`, and `--yes` together |
+| Setup refuses `--git existing` | The target is not inside a Git work tree | Choose an existing repository, or explicitly authorize `--git init`; use `--git none` only when limited mode is intended |
+| Doctor reports missing or drifted Pi assets | Project setup selected Pi but machine sync is incomplete | Run `cairn sync-pi --apply`, then `cairn sync-pi --check` and `cairn doctor` |
+| A cancelled call ends the session | The Pi/bridge version does not satisfy the per-call cancellation contract | Preserve sanitized diagnostics, close the session, and do not claim release readiness |
+| Pi exits but a child process remains | Shutdown did not complete or the tested extension drifted | Preserve process-state evidence, run the sync check, and treat the release gate as failed |
+| A client expects native annotation hints | Pi's public tool API has no annotations field | Inspect trusted bridge metadata/result `details`; never claim native propagation |
+
+## Privacy and trust boundary
+
+`.ai/cairnkeep.json` is private setup state. It records selected modes,
+harnesses, and setup-owned asset digests—not credentials, secrets, endpoints, or
+absolute paths. The Pi bridge is a local child-process boundary: it inherits the
+operator environment needed by the local server, retains only bounded stderr
+for failure diagnostics, and does not log tool arguments or results.
+
+Use only synthetic values in exercises and evidence. Do not publish executable
+paths, usernames, hostnames, repository names, environment values, child output,
+memory content, or private state. The bridge adds tools only; it does not run
+prompts, approve skills, create an autonomous loop, or add remote access.
+
+## Release boundary
+
+Ready means this lesson and its deterministic contracts pass against v2.11.0.
+Release readiness requires a non-skipping acceptance run
+against separate Pi 0.84.1 minimum and explicitly versioned registry-current
+installations, plus the documented Node.js, Bash 3.2, and native Windows matrix.
+Those executable paths must differ, but both may report 0.84.1 while that is the
+current release; a future registry advance requires its new exact version.

package/docs/learning/tracks/operator.md

@@ -2,7 +2,7 @@
 
 **Audience:** advanced users and platform maintainers
 **Prerequisite:** Practitioner track; L13 before operating captured evidence
-**Total time:** about 5 hours
+**Total time:** about 5 hours 35 minutes
 
 1. [L09 - Domain knowledge with RAG](../lessons/L09-domain-knowledge.md)
 2. [L10 - Faster context exploration](../lessons/L10-context-exploration.md)
@@ -12,11 +12,16 @@
 6. [L16 - Evaluation and ablation](../lessons/L16-evaluation.md)
 7. [L20 - Least-authority MCP tool profiles](../lessons/L20-mcp-tool-profiles.md)
 8. [L21 - Immutable context packs and skill approval](../lessons/L21-context-packs.md)
+9. [L22 - Operate Cairnkeep on native Windows](../lessons/L22-native-windows.md)
+10. [L23 - Guided setup and Pi memory](../lessons/L23-guided-setup.md)
 
 All modules are optional. The track is complete when the operator can add and
 remove each integration without breaking the standalone local workflow and can
-explain its storage, network, credential, and rollback boundaries.
+explain its storage, network, credential, and rollback boundaries. L23 adds the
+v2.11 setup/Pi lifecycle only after the earlier storage, governance, trust, and
+native-platform boundaries.
 
 Hands-on spine: `course-04-operation`, `course-06-governance`, and
-`course-07-evaluation`, and `course-10-trust-context` in the public
+`course-07-evaluation`, `course-10-trust-context`, and
+`course-12-guided-setup` in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/learning/tracks/quickstart.md

@@ -1,17 +1,21 @@
 # Quickstart Track
 
 **Audience:** developers evaluating Cairnkeep
-**Total time:** about 75 minutes
+**Total time:** about 110 minutes
 **Infrastructure:** local machine; Podman is optional
 
 1. [L00 - Why Cairnkeep?](../lessons/L00-why-cairnkeep.md)
 2. [L01 - Try it safely](../lessons/L01-safe-trial.md)
 3. [L02 - Install the local workflow](../lessons/L02-installation.md)
 4. [L03 - Bootstrap the first project](../lessons/L03-first-project.md)
+5. [L23 - Guided setup and Pi memory](../lessons/L23-guided-setup.md)
 
 The track is complete when a learner can start a new harness session, retrieve
 a previously accepted fact, and explain that default stdio memory is stored on
-the local machine rather than a discovered remote service.
+the local machine rather than a discovered remote service. L23 then shows how
+the recommended guided entry point preserves deterministic automation and keeps
+Pi machine sync explicit. This guided surface ships in v2.11.
 
-Hands-on spine: `course-00-app` through `course-01-bootstrap` in the public
+Hands-on spine: `course-00-app` through `course-01-bootstrap`, followed by
+`course-12-guided-setup`, in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/native-windows.md

@@ -0,0 +1,122 @@
+# Native Windows operation
+
+Cairnkeep supports Windows x64 directly from PowerShell and Command Prompt.
+The supported path does not invoke WSL, Git Bash, or a POSIX shell. Windows
+ARM64 may use Windows x64 emulation, but it is not a native ARM64 support claim
+until the database dependency publishes and passes an ARM64 Windows binding.
+
+## Install and guided setup
+
+Prerequisites are Node.js 22 or newer, npm, and the harness you intend to use.
+Git is required for `--git init`, `--git existing`, Git-backed context packs,
+and `--untracked` bootstrap. Explicit `--git none` provides the same documented
+limited mode as POSIX setup.
+The optional `sqlite3.exe` command enables WAL-safe `cairn memory export`.
+
+```powershell
+npm install --global @cairnkeep/cli
+cairn version
+$Project = 'C:\src\my-project'
+cairn setup $Project --git init --harness claude,pi --memory local --yes
+cairn sync --apply
+cairn sync-pi --apply
+cairn sync-pi --check
+Set-Location $Project
+cairn doctor
+.\.ai\start-claude.cmd
+```
+
+Guided setup exposes the same target classification, confirmation, Git,
+harness, memory, reconciliation, counts, JSON result, diagnostics, launch, and
+recovery contract as POSIX. It writes a restricted `.ai/cairnkeep.json` setup
+record and never syncs machine assets automatically. `cairn bootstrap` remains
+the deterministic compatibility primitive for existing scripts.
+
+Setup and bootstrap write both the established Unix launchers and native Windows
+launchers. Each `.cmd` file enters `start-harness.ps1`, loads `.ai/.env`, changes
+to the project root, and forwards arguments without shell interpolation.
+Optional `.ai/pre-launch.ps1` and `.ai/post-exit.ps1` seams run in the same
+PowerShell process, so exported environment changes reach the harness. The post
+hook receives `$env:CAIRN_EXIT_STATUS`.
+
+## MCP and operating assets
+
+Register the stdio server exactly as on other platforms:
+
+```powershell
+claude mcp add cairn-memory -s user -- cairn memory-server
+cairn sync --check
+```
+
+`cairn sync --apply` installs native `.cmd` hook transports and registers them
+in the harness settings. The hook logic itself is Node and remains fail-open
+except for capability admission, which preserves its fail-closed contract.
+`cairn sync-pi` and `cairn sync-kimi` use native filesystem operations. Pi sync
+installs the maintained local stdio memory extension explicitly; setup does not
+start it or add remote access. Pi 0.84.1 is the validated minimum; the v2.11
+release matrix also exercised a separate installation of the exact
+registry-current Pi release. The two executable paths were distinct, while
+both reported 0.84.1 because that was also the current release.
+
+## PowerShell completion
+
+Load completion for the current session:
+
+```powershell
+Invoke-Expression (& cairn completion powershell | Out-String)
+```
+
+Place the same expression in `$PROFILE` to load it in future sessions.
+
+## Storage and permissions
+
+Cairnkeep retains the same storage paths and formats. `~` resolves to the
+Windows user profile. Sensitive managed JSON files do not rely on meaningless
+Unix mode bits: Cairnkeep removes inherited ACLs and grants access only to the
+current SID, Local System, and built-in Administrators. Context-pack content is
+digest-verified before receiving restricted ACLs and a read-only attribute.
+The guided setup state uses this same private ACL and contains no credentials,
+endpoints, or absolute paths.
+
+The embedded AgentFS database driver retains Windows file handles until its
+Node process exits. Cairnkeep therefore runs artifact-store operations in
+short-lived local Node helpers on Windows. Hard deletion and pruning build a
+compacted replacement, release all handles when the helper exits, and only then
+atomically replace the live database. This does not add a daemon, network
+access, or background synchronization.
+
+`cairn memory import` uses an internal path-validating tar/gzip reader. Export
+uses `sqlite3.exe` `.backup` for a consistent snapshot of each live WAL database
+and then writes the same portable `.tgz` format used on Unix.
+
+## Scheduling and process cleanup
+
+`cairn audit-timer` registers the opt-in `Cairnkeep Memory Audit` task through
+Windows Task Scheduler. `--render-only DIR` writes the command without changing
+the scheduler. Evaluation cancellation targets the exact child PID and its
+descendant tree through `taskkill.exe /T`, then escalates through `/F` after the
+configured grace period.
+
+## Uninstall and recovery
+
+Preview first, then confirm explicitly:
+
+```powershell
+cairn uninstall --dry-run C:\src\my-project
+cairn uninstall --yes C:\src\my-project
+```
+
+Uninstall removes only managed assets and their hook registrations. Before
+mutation it creates a timestamped bundle under
+`~/cairnkeep-uninstall-backups/` containing exact files, a strict manifest, and
+`revert.ps1`. Durable memory and context packs remain unless their separate
+purge flags are supplied.
+
+## Verification boundary
+
+The release gate runs from `windows-latest` using PowerShell for Node 22, 24,
+and 26. It builds the TypeScript server, runs its Node tests, exercises guided
+setup and bootstrap, sync/check (including Pi), native hooks, safe archive
+import, backup-first uninstall, spaces and Unicode paths, packs the npm artifact,
+installs it globally, invokes `cairn.cmd`, and runs `cairn doctor`. Git Bash is
+never selected as the job shell.