@cairnkeep/cli 2.2.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +6 -3
  3. package/bin/cairn +5 -0
  4. package/containers/workspace-entrypoint.sh +4 -0
  5. package/docs/containers.md +8 -2
  6. package/docs/learning/PRODUCTION-PLAN.md +122 -0
  7. package/docs/learning/README.md +58 -0
  8. package/docs/learning/instructor-guide.md +60 -0
  9. package/docs/learning/lessons/L00-why-cairnkeep.md +87 -0
  10. package/docs/learning/lessons/L01-safe-trial.md +96 -0
  11. package/docs/learning/lessons/L02-installation.md +115 -0
  12. package/docs/learning/lessons/L03-first-project.md +116 -0
  13. package/docs/learning/lessons/L04-memory-fundamentals.md +44 -0
  14. package/docs/learning/lessons/L05-daily-workflow.md +43 -0
  15. package/docs/learning/lessons/L06-repository-quality.md +45 -0
  16. package/docs/learning/lessons/L07-privacy-and-storage.md +42 -0
  17. package/docs/learning/lessons/L08-multiple-machines.md +41 -0
  18. package/docs/learning/lessons/L09-domain-knowledge.md +42 -0
  19. package/docs/learning/lessons/L10-context-exploration.md +42 -0
  20. package/docs/learning/lessons/L11-containers.md +42 -0
  21. package/docs/learning/lessons/L12-managed-overlays.md +43 -0
  22. package/docs/learning/templates/lesson-template.md +61 -0
  23. package/docs/learning/templates/video-script-template.md +50 -0
  24. package/docs/learning/tracks/operator.md +14 -0
  25. package/docs/learning/tracks/practitioner.md +15 -0
  26. package/docs/learning/tracks/quickstart.md +14 -0
  27. package/docs/learning/video-scripts/L00-why-cairnkeep.md +76 -0
  28. package/docs/learning/video-scripts/L01-safe-trial.md +78 -0
  29. package/docs/learning/video-scripts/L02-installation.md +90 -0
  30. package/docs/learning/video-scripts/L03-first-project.md +96 -0
  31. package/docs/operating.md +14 -0
  32. package/package.json +1 -1
  33. package/scripts/cairn-container +2 -1
  34. package/scripts/completion.sh +80 -0
  35. package/scripts/test-completion.sh +24 -0
  36. package/scripts/test-container-runner.sh +4 -0
  37. package/scripts/test-container.sh +32 -1
  38. package/scripts/test-learning-docs.sh +78 -0
package/CHANGELOG.md CHANGED
@@ -3,6 +3,27 @@
3
3
  All notable user-facing changes are documented here. This project follows
4
4
  [Semantic Versioning](https://semver.org/).
5
5
 
6
+ ## [2.3.0] - 2026-07-25
7
+
8
+ ### Added
9
+
10
+ - Add `cairn completion bash|zsh|fish` for generating completion definitions
11
+ that distributions or users can install through each shell's standard
12
+ mechanism.
13
+ - Exercise every generated definition and reject unsupported shell names in
14
+ the repository test suite.
15
+
16
+ ## [2.2.1] - 2026-07-20
17
+
18
+ ### Fixed
19
+
20
+ - Make default sandbox-volume names path-specific so same-named repositories
21
+ cannot share a workspace accidentally.
22
+ - Refuse to merge repository content into a non-empty unmarked workspace
23
+ volume.
24
+ - Document that sandbox copies include untracked files and must be treated as
25
+ sensitive persistent data.
26
+
6
27
  ## [2.2.0] - 2026-07-20
7
28
 
8
29
  ### Added
@@ -100,6 +121,8 @@ stored memories.
100
121
  - Preserve executable permissions and Bash 3.2 portability on macOS.
101
122
  - Add backup-first uninstall and SQLite-safe memory export/import guidance.
102
123
 
124
+ [2.3.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.1...v2.3.0
125
+ [2.2.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.0...v2.2.1
103
126
  [2.2.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.1.0...v2.2.0
104
127
  [2.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.0.0...v2.1.0
105
128
  [2.0.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.3...v2.0.0
package/README.md CHANGED
@@ -14,7 +14,8 @@ across sessions, projects, and harnesses (Claude Code, OpenCode, …).
14
14
  ## Status
15
15
 
16
16
  Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`,
17
- `doctor`, `memory`, `audit-timer`, `uninstall`) installable via `npm i -g @cairnkeep/cli`, and the
17
+ `doctor`, `memory`, `audit-timer`, `completion`, `uninstall`) installable via
18
+ `npm i -g @cairnkeep/cli`, and the
18
19
  operating layer (commands,
19
20
  agents, hooks) installed on both Claude Code and OpenCode. The generic launchers
20
21
  expose wrapper seams (`.ai/pre-launch.sh`, `CAIRN_EXTRA_SETTINGS`,
@@ -68,8 +69,9 @@ storage paths, secrets, and private derived images, see
68
69
  `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
69
70
  `cairn memory export|import` relocates the durable store between machines
70
71
  (`export` requires the optional `sqlite3` CLI);
71
- `cairn audit-timer` installs the scheduled memory+wiki audit; `cairn uninstall`
72
- reverses the install (backup-first, revertible).
72
+ `cairn audit-timer` installs the scheduled memory+wiki audit;
73
+ `cairn completion bash|zsh|fish` generates shell completion definitions; and
74
+ `cairn uninstall` reverses the install (backup-first, revertible).
73
75
  - **`templates/`** — project scaffolding (generic launchers, env) plus the
74
76
  derived-knowledge layer (wiki, alignment, graph, security, planning).
75
77
  - **`scripts/`** — asset-sync and maintenance utilities.
@@ -203,6 +205,7 @@ enabling them.
203
205
 
204
206
  ## More
205
207
 
208
+ - **Guided learning paths and video scripts** — [docs/learning/README.md](docs/learning/README.md)
206
209
  - **Optional document RAG** (`domain_knowledge_*` via AnythingLLM) — [docs/domain-knowledge.md](docs/domain-knowledge.md)
207
210
  - **Building a private overlay** (wrap cairnkeep for your org/provider) — [docs/building-an-overlay.md](docs/building-an-overlay.md)
208
211
  - **Managed overlay distributions** (wrapper CLI, policy lock, private registry, rollback) — [docs/overlay-distributions.md](docs/overlay-distributions.md)
package/bin/cairn CHANGED
@@ -47,6 +47,8 @@ Usage:
47
47
  timer, and any given projects' bootstrap scaffold).
48
48
  Backs everything up first with a revert.sh; keeps the
49
49
  durable memory store unless --purge-memory is given.
50
+ cairn completion bash|zsh|fish
51
+ Generate completion definitions for a major shell.
50
52
  cairn version Print version
51
53
  cairn help Show this help
52
54
  USAGE
@@ -76,6 +78,9 @@ case "$cmd" in
76
78
  audit-timer)
77
79
  exec "$CAIRN_ROOT/scripts/install-audit-timer.sh" "$@"
78
80
  ;;
81
+ completion)
82
+ exec "$CAIRN_ROOT/scripts/completion.sh" "$@"
83
+ ;;
79
84
  version | --version | -v)
80
85
  v=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$CAIRN_ROOT/package.json" 2>/dev/null | head -1)
81
86
  echo "cairnkeep ${v:-unknown}"
@@ -11,6 +11,10 @@ case "$mode" in
11
11
  exit 66
12
12
  fi
13
13
  if [ ! -e /workspace/.cairnkeep-sandbox-ready ]; then
14
+ if find /workspace -mindepth 1 -maxdepth 1 -print -quit | grep -q .; then
15
+ echo "cairnkeep: refusing to initialize a non-empty unmarked workspace volume" >&2
16
+ exit 65
17
+ fi
14
18
  cp -a /source/. /workspace/
15
19
  : > /workspace/.cairnkeep-sandbox-ready
16
20
  fi
@@ -154,8 +154,14 @@ cairn-container workspace --repo /path/to/repository
154
154
  ```
155
155
 
156
156
  Rerunning the command with the same workspace volume resumes the copy. Use
157
- `--workspace-volume` when repositories have the same basename or when an
158
- explicit lifecycle is preferable.
157
+ `--workspace-volume` when an explicit lifecycle is preferable. Default volume
158
+ names include both the repository basename and a checksum of its absolute path,
159
+ so same-named repositories do not share a sandbox accidentally.
160
+
161
+ The initial copy includes tracked and untracked files. Treat the workspace
162
+ volume as sensitive local data and remove it when it is no longer needed.
163
+ Cairnkeep refuses to initialize a non-empty volume that lacks its sandbox
164
+ marker rather than merging unrelated content.
159
165
 
160
166
  `shared` mode is opt-in and bind-mounts the checkout read/write:
161
167
 
@@ -0,0 +1,122 @@
1
+ # Learning Path Production Plan
2
+
3
+ This plan grows the course in small publishable waves. Each wave produces a
4
+ useful learner outcome on its own and leaves the public material in a coherent
5
+ state.
6
+
7
+ ## Guiding principles
8
+
9
+ - Demonstrate value before architecture.
10
+ - Keep public lessons provider-neutral and free of private configuration.
11
+ - Teach local storage first; remote storage must always be an explicit choice.
12
+ - Write the canonical lesson before recording the video.
13
+ - Use short videos that can be replaced independently after product changes.
14
+ - Treat commands, expected output, and recovery instructions as tested product
15
+ surfaces rather than informal prose.
16
+
17
+ ## Wave 0 - Course foundation
18
+
19
+ **Deliverables**
20
+
21
+ - Stable lesson IDs L00-L12.
22
+ - Quickstart, practitioner, and operator tracks.
23
+ - Lesson, video, and instructor templates.
24
+ - Complete L00-L03 lesson and recording scripts.
25
+ - Briefs and acceptance criteria for L04-L12.
26
+
27
+ **Exit gate**
28
+
29
+ - A new learner can follow L00-L03 on a clean machine or stop safely after the
30
+ container trial.
31
+ - Every command is current and no optional service is presented as mandatory.
32
+
33
+ ## Wave 1 - Pilot the quickstart
34
+
35
+ 1. Rehearse L00-L03 without recording and log confusing steps.
36
+ 2. Run the lessons on one clean Linux environment and one macOS environment.
37
+ 3. Record the four short videos from the supplied scripts.
38
+ 4. Ask two learners to complete the track without live assistance.
39
+ 5. Fix every repeated point of confusion before public promotion.
40
+
41
+ **Artifacts:** four videos, four blog-ready lessons, one learner feedback form.
42
+
43
+ **Exit gate:** both pilot learners reach a successful `/remember` and `/recall`
44
+ round trip and can explain where their memory is stored.
45
+
46
+ ## Wave 2 - Daily practitioner value
47
+
48
+ Expand L04-L06 in this order:
49
+
50
+ 1. L04 memory keys, scopes, search, history, and review.
51
+ 2. L05 wiki, alignment, session hooks, and derived-knowledge boundaries.
52
+ 3. L06 `/repo-review` and `/security-audit` against a deliberately vulnerable
53
+ toy repository.
54
+
55
+ Create the public `cairnkeep-course-labs` repository during this wave, not
56
+ before. It must contain synthetic code only, prominent safety warnings, tagged
57
+ starter states, and solution branches.
58
+
59
+ **Exit gate:** a learner can complete all labs from a fresh clone, and CI resets
60
+ and verifies every starter state.
61
+
62
+ ## Wave 3 - Safe operation
63
+
64
+ Expand L07-L08 and add a backup/restore lab:
65
+
66
+ - Draw the local stdio and explicit remote HTTP data flows.
67
+ - Demonstrate `cairn memory path`, export, import, and rollback.
68
+ - Explain identity, project, and global routing without using real credentials.
69
+ - Test the multiple-machine procedure with disposable stores before recording.
70
+
71
+ **Exit gate:** the learner can predict the storage destination before starting
72
+ a session and can restore a snapshot without losing the pre-existing store.
73
+
74
+ ## Wave 4 - Optional accelerators
75
+
76
+ Expand L09-L10 as independent modules:
77
+
78
+ - Optional document RAG, workspace selection, query, and sync.
79
+ - token-miser/FastContext exploration, citations, caching, and failure modes.
80
+
81
+ Each lesson begins and ends with the reminder that Cairnkeep works without the
82
+ optional component.
83
+
84
+ **Exit gate:** disabling either integration returns the learner to a healthy
85
+ standalone Cairnkeep workflow.
86
+
87
+ ## Wave 5 - Operators and platform teams
88
+
89
+ Expand L11-L12:
90
+
91
+ - Rootless containers, persistent volumes, authenticated HTTP, and isolation.
92
+ - Overlay manifests, private package delivery, bootstrap policy, fleet updates,
93
+ rollback, and release gates.
94
+
95
+ **Exit gate:** the operator can explain every host mount, network boundary,
96
+ credential source, storage destination, and rollback action.
97
+
98
+ ## Wave 6 - Publication and maintenance
99
+
100
+ 1. Publish a landing article linking to the three tracks.
101
+ 2. Publish videos as a playlist with lesson IDs in every title.
102
+ 3. Add release compatibility metadata to each completed lesson.
103
+ 4. Run a command-verification pass for every Cairnkeep minor release.
104
+ 5. Review learner feedback monthly during the pilot, then quarterly.
105
+
106
+ ## How we will work together
107
+
108
+ For each lesson, follow this loop:
109
+
110
+ 1. **Select:** choose the next lesson from the current wave.
111
+ 2. **Discover:** collect real learner questions and one convincing use case.
112
+ 3. **Draft:** complete the lesson using the template.
113
+ 4. **Verify:** execute every command from a clean starting state.
114
+ 5. **Script:** derive the video script from the verified lesson.
115
+ 6. **Rehearse:** read it aloud while performing the demo once without recording.
116
+ 7. **Record:** capture the short lesson in sections, not one continuous take.
117
+ 8. **Pilot:** give the written lesson to a learner before publishing the video.
118
+ 9. **Improve:** incorporate observed failures and publish both formats together.
119
+
120
+ The immediate next step after merging Wave 0 is the unrecorded L00-L03
121
+ rehearsal. Use the checklist in the [instructor guide](instructor-guide.md) and
122
+ record questions rather than polishing video production prematurely.
@@ -0,0 +1,58 @@
1
+ # Learn Cairnkeep
2
+
3
+ This learning path teaches Cairnkeep through small, verifiable outcomes. The
4
+ canonical lesson is written once and can be reused as a guide, blog post,
5
+ workshop handout, or video script.
6
+
7
+ ## Start here
8
+
9
+ Choose the shortest track that matches your goal:
10
+
11
+ - [Quickstart](tracks/quickstart.md) - prove the core value in about 75 minutes.
12
+ - [Practitioner](tracks/practitioner.md) - adopt Cairnkeep in daily project work.
13
+ - [Operator](tracks/operator.md) - storage, optional services, containers, and
14
+ managed distributions.
15
+
16
+ Lessons marked **Ready** include a complete exercise and presenter script.
17
+ Lessons marked **Brief** define outcomes and acceptance criteria and will be
18
+ expanded according to the [production plan](PRODUCTION-PLAN.md).
19
+
20
+ ## Curriculum
21
+
22
+ | ID | Lesson | Status | Typical time |
23
+ |---|---|---|---:|
24
+ | L00 | [Why Cairnkeep?](lessons/L00-why-cairnkeep.md) | Ready | 10 min |
25
+ | L01 | [Try it safely](lessons/L01-safe-trial.md) | Ready | 15 min |
26
+ | L02 | [Install the local workflow](lessons/L02-installation.md) | Ready | 25 min |
27
+ | L03 | [Bootstrap the first project](lessons/L03-first-project.md) | Ready | 25 min |
28
+ | L04 | [Memory fundamentals](lessons/L04-memory-fundamentals.md) | Brief | 35 min |
29
+ | L05 | [The daily workflow](lessons/L05-daily-workflow.md) | Brief | 40 min |
30
+ | L06 | [Repository review and security](lessons/L06-repository-quality.md) | Brief | 45 min |
31
+ | L07 | [Privacy and storage](lessons/L07-privacy-and-storage.md) | Brief | 30 min |
32
+ | L08 | [Multiple machines](lessons/L08-multiple-machines.md) | Brief | 40 min |
33
+ | L09 | [Domain knowledge with RAG](lessons/L09-domain-knowledge.md) | Brief | 35 min |
34
+ | L10 | [Faster context exploration](lessons/L10-context-exploration.md) | Brief | 30 min |
35
+ | L11 | [Containers and isolation](lessons/L11-containers.md) | Brief | 40 min |
36
+ | L12 | [Managed overlays](lessons/L12-managed-overlays.md) | Brief | 45 min |
37
+
38
+ ## Teaching contract
39
+
40
+ Every complete lesson contains:
41
+
42
+ 1. A practical problem and observable outcome.
43
+ 2. Prerequisites and a clean starting state.
44
+ 3. A hands-on exercise using non-sensitive sample data.
45
+ 4. Verification and recovery steps.
46
+ 5. A privacy or security boundary.
47
+ 6. A presenter-ready video script.
48
+
49
+ The learner should never need optional infrastructure to complete L00-L06.
50
+ Remote memory, RAG, routing, and containers are separate opt-in modules.
51
+
52
+ ## For contributors
53
+
54
+ Use [the lesson template](templates/lesson-template.md) and
55
+ [the video template](templates/video-script-template.md). The
56
+ [instructor guide](instructor-guide.md) defines rehearsal, recording, and
57
+ publication checks. Commands in finished lessons must be tested against the
58
+ current release before publication.
@@ -0,0 +1,60 @@
1
+ # Instructor Guide
2
+
3
+ ## Before each lesson
4
+
5
+ - Confirm the lesson is marked **Ready**, not **Brief**.
6
+ - Run every command against the current Cairnkeep release.
7
+ - Use a disposable repository and synthetic names, URLs, tokens, and data.
8
+ - Hide notifications, shell history, credentials, bookmarks, and unrelated
9
+ repositories before screen recording.
10
+ - Increase terminal font size and keep one command per visible line.
11
+ - Prepare a clean start snapshot and a known-good completed snapshot.
12
+ - Rehearse the failure-recovery section, not only the happy path.
13
+
14
+ ## Recommended recording format
15
+
16
+ Record each video as independent segments:
17
+
18
+ 1. **Hook:** the concrete problem in 20-40 seconds.
19
+ 2. **Outcome:** what the learner will be able to verify.
20
+ 3. **Concept:** only the mental model required for the exercise.
21
+ 4. **Demo:** commands and observable results.
22
+ 5. **Boundary:** storage, privacy, or trust implication.
23
+ 6. **Recap:** result and next lesson.
24
+
25
+ Aim for 8-15 minutes. If a script exceeds 15 minutes, split the lesson rather
26
+ than speaking faster.
27
+
28
+ ## Recording conventions
29
+
30
+ - Say command intent before typing the command.
31
+ - Pause after important output so it can be read.
32
+ - Never paste a real token, cookie, endpoint, email, or repository name.
33
+ - Describe output rather than claiming every learner will see identical text.
34
+ - Keep mistakes that teach a recovery step; remove unrelated typing mistakes.
35
+ - Refer to lessons by stable ID, for example “L02”, so links survive title edits.
36
+
37
+ ## Pilot feedback
38
+
39
+ Ask each pilot learner:
40
+
41
+ 1. Where did you first become uncertain?
42
+ 2. Which command did you run without understanding its effect?
43
+ 3. Where do you believe memory is stored?
44
+ 4. What would prevent you from using this in a real project tomorrow?
45
+ 5. Which result made the value clear?
46
+
47
+ Record observations without collecting project content, prompts, credentials,
48
+ or memory values.
49
+
50
+ ## Definition of done
51
+
52
+ A lesson is **Ready** only when:
53
+
54
+ - prerequisites and cleanup are explicit;
55
+ - all commands were executed from the documented starting state;
56
+ - verification distinguishes success from partial installation;
57
+ - common failures have actionable recovery steps;
58
+ - storage and privacy implications are stated;
59
+ - the video script matches the verified lesson;
60
+ - a learner other than the author completed it without hidden instructions.
@@ -0,0 +1,87 @@
1
+ # L00 - Why Cairnkeep?
2
+
3
+ **Status:** Ready
4
+ **Track:** Quickstart
5
+ **Time:** 10 minutes
6
+ **Tested with:** Cairnkeep 2.3.0
7
+
8
+ ## Outcome
9
+
10
+ You can explain what Cairnkeep remembers, what remains canonical in the
11
+ repository, and how it differs from chat history and document retrieval.
12
+
13
+ ## Why this matters
14
+
15
+ Coding harnesses are effective inside one session but important decisions,
16
+ pitfalls, and conventions are easily lost between sessions or tools. Copying an
17
+ entire transcript into the next prompt is expensive and preserves noise along
18
+ with useful facts.
19
+
20
+ Cairnkeep stores small, reviewed operational facts and retrieves them when they
21
+ are relevant. It also provides a derived wiki and governed review workflows,
22
+ without replacing source code, tests, issue trackers, or canonical documents.
23
+
24
+ ## Mental model
25
+
26
+ Keep four layers distinct:
27
+
28
+ | Layer | Example | Role |
29
+ |---|---|---|
30
+ | Harness history | The current conversation | Temporary working context |
31
+ | Cairnkeep memory | “Use transactional migrations” | Durable operational fact |
32
+ | Project wiki | A cited architecture summary | Derived, reviewable knowledge |
33
+ | Canonical source | Code, tests, ADR, issue | Authority when layers disagree |
34
+
35
+ Document RAG is an optional fifth layer for retrieving larger documents. It is
36
+ not required for Cairnkeep memory.
37
+
38
+ ## Exercise
39
+
40
+ For each statement, choose the appropriate destination:
41
+
42
+ 1. “The payment API retries only idempotent operations.”
43
+ 2. “Here is the complete API specification.”
44
+ 3. “The current debugging hypothesis is a race in the cache.”
45
+ 4. “Never run the production migration from a developer laptop.”
46
+
47
+ Suggested answer:
48
+
49
+ - 1 can become memory after validation and should cite the canonical code or
50
+ specification in derived knowledge.
51
+ - 2 stays a canonical document and may optionally be indexed for RAG.
52
+ - 3 remains session context until confirmed.
53
+ - 4 is a durable constraint after it is verified against policy.
54
+
55
+ ## Verify
56
+
57
+ You are ready for L01 if you can answer these questions:
58
+
59
+ - Does Cairnkeep replace the repository or its documentation? **No.**
60
+ - Does the default installation discover a remote memory server? **No.**
61
+ - Should every sentence in a session become durable memory? **No.**
62
+
63
+ ## Common failures
64
+
65
+ | Misconception | Correction |
66
+ |---|---|
67
+ | Memory is another transcript store | Store concise, durable facts rather than complete prompts |
68
+ | RAG and memory are the same | RAG retrieves documents; memory preserves reviewed operational facts |
69
+ | Derived knowledge is authoritative | Code, tests, policies, and canonical documents win conflicts |
70
+
71
+ ## Privacy and trust boundary
72
+
73
+ The default stdio topology stores memory on the local machine. Remote storage,
74
+ model-backed extraction, embeddings, and document RAG require explicit
75
+ configuration and are taught separately.
76
+
77
+ ## Recap
78
+
79
+ - Memory is selective and durable.
80
+ - Derived knowledge remains subordinate to canonical sources.
81
+ - Optional services are not prerequisites.
82
+
83
+ Next: [L01 - Try it safely](L01-safe-trial.md).
84
+
85
+ ## Video
86
+
87
+ Use [the L00 presenter script](../video-scripts/L00-why-cairnkeep.md).
@@ -0,0 +1,96 @@
1
+ # L01 - Try it safely
2
+
3
+ **Status:** Ready
4
+ **Track:** Quickstart
5
+ **Time:** 15 minutes
6
+ **Tested with:** Cairnkeep 2.3.0
7
+
8
+ ## Outcome
9
+
10
+ You can launch the published memory-server image as an unprivileged,
11
+ read-only container and identify the only persistent resource it creates.
12
+
13
+ ## Prerequisites
14
+
15
+ - Podman installed and able to run rootless containers.
16
+ - No Cairnkeep installation or coding harness is required.
17
+
18
+ ## Mental model
19
+
20
+ This is a packaging and isolation trial, not the complete harness workflow.
21
+ The server communicates over stdio and waits for an MCP client. The container is
22
+ ephemeral; the named course volume is persistent.
23
+
24
+ ## Exercise
25
+
26
+ 1. Pull the public image:
27
+
28
+ ```bash
29
+ podman pull ghcr.io/cairnkeep/cairnkeep:2.3.0
30
+ ```
31
+
32
+ 2. Start the stdio server with a read-only root filesystem and no Linux
33
+ capabilities:
34
+
35
+ ```bash
36
+ podman run --rm -i \
37
+ --userns=keep-id:uid=10001,gid=10001 \
38
+ --read-only --cap-drop=all --security-opt=no-new-privileges \
39
+ --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
40
+ --volume cairnkeep-course-data:/data:Z,U \
41
+ ghcr.io/cairnkeep/cairnkeep:2.3.0 stdio
42
+ ```
43
+
44
+ 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it
45
+ remains running.
46
+
47
+ 4. Inspect the persistent resource:
48
+
49
+ ```bash
50
+ podman volume inspect cairnkeep-course-data
51
+ ```
52
+
53
+ ## Verify
54
+
55
+ ```bash
56
+ podman volume exists cairnkeep-course-data
57
+ echo $?
58
+ ```
59
+
60
+ Exit status `0` confirms that the named volume exists. No listener was exposed
61
+ on the network by this lesson.
62
+
63
+ ## Common failures
64
+
65
+ | Symptom | Cause | Recovery |
66
+ |---|---|---|
67
+ | `podman: command not found` | Podman is not installed | Skip L01 and continue with host installation in L02 |
68
+ | Image pull is denied | Registry or network policy blocks GHCR | Use the npm installation in L02 |
69
+ | SELinux mount error | Unsupported volume labelling mode | Confirm the documented Podman/SELinux setup before changing flags |
70
+
71
+ ## Privacy and trust boundary
72
+
73
+ The command publishes no port and mounts no project directory, home directory,
74
+ or credential. Only the named volume is persistent. Do not infer that a
75
+ container automatically provides remote memory or a containerized harness.
76
+
77
+ ## Clean up
78
+
79
+ This deletes only the empty course volume. Do not reuse this command for a
80
+ volume containing real memory.
81
+
82
+ ```bash
83
+ podman volume rm cairnkeep-course-data
84
+ ```
85
+
86
+ ## Recap
87
+
88
+ - The server image runs unprivileged and read-only.
89
+ - Stdio does not expose a network listener.
90
+ - Persistence belongs to an explicitly named volume.
91
+
92
+ Next: [L02 - Install the local workflow](L02-installation.md).
93
+
94
+ ## Video
95
+
96
+ Use [the L01 presenter script](../video-scripts/L01-safe-trial.md).
@@ -0,0 +1,115 @@
1
+ # L02 - Install the local workflow
2
+
3
+ **Status:** Ready
4
+ **Track:** Quickstart
5
+ **Time:** 25 minutes
6
+ **Tested with:** Cairnkeep 2.3.0 and Node.js 22 or newer
7
+
8
+ ## Outcome
9
+
10
+ You can install the CLI, register the local memory server, install the operating
11
+ layer, and distinguish a complete installation from a partial one.
12
+
13
+ ## Prerequisites
14
+
15
+ - Node.js 22 or newer and npm.
16
+ - Claude Code installed for the commands below. OpenCode users should follow
17
+ the equivalent setup in [the operating guide](../../operating.md).
18
+ - Permission to install an npm package globally for your user.
19
+
20
+ ## Mental model
21
+
22
+ A complete setup has three independent parts:
23
+
24
+ 1. the `cairn` CLI and memory server;
25
+ 2. the MCP registration used by the harness;
26
+ 3. the operating layer containing commands, agents, hooks, and templates.
27
+
28
+ `cairn bootstrap` configures a project later; it does not perform the first two
29
+ machine-level steps.
30
+
31
+ ## Exercise
32
+
33
+ 1. Confirm the runtime:
34
+
35
+ ```bash
36
+ node --version
37
+ npm --version
38
+ ```
39
+
40
+ 2. Install Cairnkeep:
41
+
42
+ ```bash
43
+ npm install --global @cairnkeep/cli@2.3.0
44
+ cairn --version
45
+ ```
46
+
47
+ 3. Register the local stdio server under the stable name `cairn-memory`:
48
+
49
+ ```bash
50
+ claude mcp add cairn-memory -s user -- cairn memory-server
51
+ ```
52
+
53
+ 4. Install the operating layer:
54
+
55
+ ```bash
56
+ cairn sync --apply
57
+ ```
58
+
59
+ 5. Check for drift without modifying anything:
60
+
61
+ ```bash
62
+ cairn sync --check
63
+ ```
64
+
65
+ ## Verify
66
+
67
+ Run both checks:
68
+
69
+ ```bash
70
+ claude mcp get cairn-memory
71
+ cairn sync --check
72
+ ```
73
+
74
+ The MCP entry must invoke `cairn memory-server`, and the sync check must report
75
+ no operating-layer drift. Having only one of these results is a partial
76
+ installation.
77
+
78
+ ## Common failures
79
+
80
+ | Symptom | Cause | Recovery |
81
+ |---|---|---|
82
+ | `cairn` is not found | npm global bin directory is absent from `PATH` | Run `npm prefix -g`, locate its bin directory, and update `PATH` |
83
+ | MCP exists but slash commands do not | Operating layer was not applied | Run `cairn sync --apply`, then restart the harness |
84
+ | MCP starts but stores somewhere unexpected | A memory environment override is active | Inspect the effective environment and read L07 before continuing |
85
+ | Existing managed files differ | Local customization conflicts with sync | Run `cairn sync --check`, review the diff, and back up before applying |
86
+
87
+ ## Privacy and trust boundary
88
+
89
+ This registration starts `cairn memory-server` locally as a stdio child. It
90
+ does not discover a server, send memory to a remote host, configure embeddings,
91
+ or enable an optional document-RAG integration.
92
+
93
+ ## Clean up if you stop the evaluation
94
+
95
+ Continue directly to L03 if you are completing the quickstart. If you stop here,
96
+ remove the MCP registration and review the non-writing uninstall plan:
97
+
98
+ ```bash
99
+ claude mcp remove -s user cairn-memory
100
+ cairn uninstall --dry-run
101
+ ```
102
+
103
+ Do not delete memory stores as part of a course cleanup.
104
+
105
+ ## Recap
106
+
107
+ - CLI installation, MCP registration, and operating-layer sync are distinct.
108
+ - `sync --check` is the non-writing drift check.
109
+ - Default stdio memory is local.
110
+
111
+ Next: [L03 - Bootstrap the first project](L03-first-project.md).
112
+
113
+ ## Video
114
+
115
+ Use [the L02 presenter script](../video-scripts/L02-installation.md).