v0.1.1: nucleus + learnings refactor — both fully user-owned, ~/.atom/ namespace

Architectural refactor of the cross-project knowledge story. Locks the
mental model into two distinct, both 100%-user-owned layers:

  nucleus     = your MEMORY of every session (raw, low bar, project-tagged)
              → ~/.atom/nucleus/projects/<slug>/learnings.jsonl

  learnings   = your PLAYBOOK of patterns to carry forward (curated, high bar)
              → ~/.atom/learnings/<type>/<key>.md
              → auto-copied into every new project you bootstrap

Both are the user's data. Nothing leaves their machine without explicit
action. Optional sync goes to *their own* private GitHub repos.

Storage rename: ~/.nucleus/ → ~/.atom/nucleus/ (one-shot migration runs
on first nucleus invocation; mv the directory if the new location is
empty and the legacy one exists).

Promote target rename: nucleus promote <id> now writes into the user's
~/.atom/learnings/, NOT into the atom repo's learnings/ directory.
That maintainer-curated `learnings/` directory is gone — it conflated
maintainer wisdom with user data and broke the privacy model.

New CLIs:

  bin/learnings/   Mirror of nucleus shape: init / list / show /
                   remove / sync. Stores at ~/.atom/learnings/.
                   The promote target for `nucleus promote`.

  bin/atom/        Top-level help dispatcher. `atom --help` (or
                   `atom`) prints the unified command table for
                   every CLI in the system. No subcommand routing;
                   pure discovery surface.

./atom-setup now installs 5 CLIs globally (was 3): atom, atom-setup,
nucleus, learnings, model-race. Cheatsheet at end nudges the user
to run `nucleus init && learnings init` once per machine.

scripts/copy-learnings.mjs sources from ~/.atom/learnings/ by default
(was ./learnings). atom-setup writer.js does the same.

scaffold/AGENTS.md Tooling section rewritten with the nucleus-vs-
learnings distinction unmissable. Two clearly labeled sections, the
generalization test framed at the promotion bridge, setup nudge
documented for AI tools.

scaffold/.claude/skills/nucleus/SKILL.md updated with the same two-
layer framing and a setup-nudge instruction for first-session
detection.

README.md gets a nucleus-vs-learnings comparison table at the top of
the "What is nucleus" section, replacing the metaphor-first prose.

All package versions bumped to 0.1.1.

CHANGELOG.md gains a [0.1.1] entry covering the rename, the user-
owned shift, the two new CLIs, and the cheatsheet nudges.

Regression suite (scripts/test-atom-setup.sh) version assertion
bumped to 0.1.1; all 57 assertions still pass locally.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: machbuilds

CHANGELOG.md

@@ -6,14 +6,41 @@ All notable changes to atom land here. Format: [Keep a Changelog](https://keepac
 
 Tracking work targeting v0.2. See `docs/planning/` for in-flight build plans.
 
+## [0.1.1] — 2026-05-06
+
+Architectural refactor of the nucleus + learnings story. **No new features**, but the conceptual model is now coherent and the storage layout is namespaced under `~/.atom/`.
+
+### Changed
+
+- **`learnings` is now user-owned, not maintainer-curated.** Previously, `learnings/` was a directory in the atom repo where the maintainer's curated wisdom lived; new projects inherited it at clone time. That conflated maintainer content with user data and confused the privacy story. Now `learnings` is the user's *own* playbook, lives at `~/.atom/learnings/` on their machine, and follows them across every new project they bootstrap. atom ships the system; the content is theirs alone. Optional sync to *their* private GitHub repo (separate from the nucleus sync repo).
+- **Storage moved from `~/.nucleus/` to `~/.atom/nucleus/`.** Namespace consistency with `~/.atom/learnings/` and any future per-machine atom state (config, cache, etc.). Migration is one-shot: `nucleus` detects `~/.nucleus/` on first run and renames it to `~/.atom/nucleus/`.
+- **`nucleus promote <id>`** now writes into `~/.atom/learnings/<type>/<key>.md` (the user's playbook) instead of the atom repo's `learnings/`.
+- **`scripts/copy-learnings.mjs`** sources from `~/.atom/learnings/` by default (was `./learnings`).
+- **`atom-setup` writer** copies learnings from the user's `~/.atom/learnings/` into the new project, filtered by stack tags. No-op when the user hasn't run `learnings init` or hasn't promoted anything yet.
+- **README, AGENTS.md, planning docs** rewritten to make the nucleus-vs-learnings distinction unmissable. Both layers framed as "100% yours."
+
+### Added
+
+- **`learnings` CLI** at `bin/learnings/` — `init`, `list`, `show`, `remove`, `sync`. Mirrors the nucleus CLI's shape. Promote target for `nucleus promote`.
+- **`atom` CLI** at `bin/atom/` — top-level help dispatcher. `atom --help` (or `atom`) prints the unified command table for every CLI in the atom system. No subcommand routing; pure discovery surface.
+- **Setup nudges** in the post-`atom-setup` cheatsheet and Claude nucleus skill: prompt the user to run `nucleus init && learnings init` once per machine.
+
+### Removed
+
+- **`atom/learnings/`** (the maintainer-curated directory) — removed from the repo. The system (taxonomy doc, copy script, promote flow) stays; the content is no longer atom's.
+
+### CLI count
+
+`./atom-setup` now installs **5 CLIs** globally: `atom`, `atom-setup`, `nucleus`, `learnings`, `model-race`.
+
 ## [0.1.0] — 2026-05-05
 
 First feature-complete release. atom is a project-starter template with cross-project memory, multi-tool AI support, and an opinionated dev workflow.
 
 ### Added
 
 - **`atom-setup`** — interactive wizard (Node + clack). Four modes: `--bare`, `--minimal`, default, `--full`. Ten sections cover project basics, stack, license, Docker tier, CI/CD, git. Pre-flight detection, smart defaults from environment, resumable state, dry-run, final confirmation screen.
-- **`nucleus`** — cross-project learning store CLI. Subcommands: `init`, `add`, `search`, `sync`, `promote`, `slug`. JSONL storage at `~/.nucleus/projects/<slug>/`, optional GitHub sync, keyword + structured filter search, three capture modes (claude-managed, auto-timer, manual).
+- **`nucleus`** — cross-project learning store CLI. Subcommands: `init`, `add`, `search`, `sync`, `promote`, `slug`. JSONL storage at `~/.atom/nucleus/projects/<slug>/`, optional GitHub sync, keyword + structured filter search, three capture modes (claude-managed, auto-timer, manual).
 - **`learnings/`** — graduation layer for nucleus entries that pass the generalisation test. Files inherit into bootstrapped projects via `scripts/copy-learnings.mjs`, filtered by stack tags from `docs/LEARNINGS_TAXONOMY.md`.
 - **`model-race`** — parallel AI model comparison via Git worktrees. Subcommands: `start`, `status`, `spec`, `launch`, `score`, `judge`, `merge`, `abort`. Weighted scorecard (pass-fail and numeric-min metrics), opt-in LLM judge, configurable per-project via `model-race.config.json`.
 - **Docker** — four optional tiers in `extras/docker/`: None, Dockerfile only, + compose, + devcontainer. Smart-defaulted from stack and deploy target. Production-grade defaults: multi-stage build, non-root user, healthcheck, pinned base image, BuildKit cache mounts, multi-arch CI workflow.
@@ -30,5 +57,6 @@ First feature-complete release. atom is a project-starter template with cross-pr
 - Stack presets currently include `nextjs` only. Other stacks fall back to the generic scaffold and will land per-stack in v0.2.
 - Constitution generation is a TODO marker in the cheatsheet; v0.2 will wire `speckit-constitution` automatically.
 
-[Unreleased]: https://github.com/machbuilds/atom/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/machbuilds/atom/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/machbuilds/atom/releases/tag/v0.1.1
 [0.1.0]: https://github.com/machbuilds/atom/releases/tag/v0.1.0

INSTALL.md

@@ -48,7 +48,7 @@ If `./atom-setup` fails with `EACCES`, use `sudo ./atom-setup` or set up an npm
 
 ### 2. nucleus init
 
-Run once on each machine to set up `~/.nucleus`:
+Run once on each machine to set up `~/.atom/nucleus`:
 
 ```bash
 nucleus init
@@ -65,7 +65,7 @@ nucleus add "test entry" --type pattern --confidence low
 nucleus search "test"
 ```
 
-The first command appends an entry; the second should find it. Once verified you can delete the test entry by editing `~/.nucleus/projects/<slug>/learnings.jsonl` directly.
+The first command appends an entry; the second should find it. Once verified you can delete the test entry by editing `~/.atom/nucleus/projects/<slug>/learnings.jsonl` directly.
 
 ### 3. AI CLI of your choice
 

README.md

@@ -92,8 +92,8 @@ Plus `--resume` (pick up an interrupted setup), `--dry-run` (preview without wri
 | Feature | What it does |
 |---|---|
 | **`atom-setup`** | Interactive wizard (Node + clack). 4 modes: `--bare` / `--minimal` / default / `--full`. 10 sections cover project basics, stack, license, Docker tier, CI, git. Pre-flight detection, smart defaults, resumable state. |
-| **`nucleus`** | Cross-project learning store at `~/.nucleus`. Captures durable lessons mid-session; surfaces them in any future project. JSONL storage, optional GitHub sync, keyword + structured filter search. |
-| **`learnings/`** | Graduation layer for `nucleus` entries that prove generalizable. Files inherit into every bootstrapped project, filtered by stack tags. |
+| **`nucleus`** | Your **memory** — raw notes from every session, project-tagged, captured fast. Lives at `~/.atom/nucleus/`. JSONL storage, keyword + structured filter search. Optionally synced to your own private GitHub repo. |
+| **`learnings`** | Your **playbook** — patterns you've decided to carry forward. Lives at `~/.atom/learnings/`. Auto-copied into every new project you bootstrap (filtered by stack tags). Optionally synced to your own private GitHub repo. |
 | **`model-race`** | Parallel AI model comparison via Git worktrees. Race the same spec through claude/codex/gemini, score with weighted metrics, optional LLM judge, merge the winner. |
 | **Docker, optional** | Four tiers: None / Dockerfile / + compose / + devcontainer. Smart-defaulted from your stack. Production-grade out of the box (multi-stage, non-root, healthcheck, multi-arch CI). |
 | **Multi-AI tool support** | `AGENTS.md` is the canonical spec; `CLAUDE.md` / `GEMINI.md` / `.cursorrules` / `.github/copilot-instructions.md` are forwarders. Claude, Codex CLI, Gemini CLI, Cursor, and Copilot all read the same instructions. |
@@ -104,32 +104,41 @@ Plus `--resume` (pick up an interrupted setup), `--dry-run` (preview without wri
 
 ## What is nucleus?
 
-**nucleus is atom's cross-project learning store.** It's a CLI (`nucleus add`, `nucleus search`, `nucleus promote`, `nucleus sync`) backed by a JSONL file at `~/.nucleus/projects/<slug>/learnings.jsonl` on your machine. You capture durable lessons mid-session — pitfalls, patterns, architecture decisions with rationale — and they surface in any future session, in any project, with `nucleus search`.
+atom ships with two layers of cross-project knowledge. They're easy to confuse, so the distinction matters:
 
-Think of it as **the brain of your project work that travels across every clone.** Every atom has a nucleus at its center holding its identity; `nucleus` does the same for your projects: the core knowledge that makes each project what it is.
+| | **nucleus** | **learnings** |
+|---|---|---|
+| What it is | Your **memory** of every session | Your **playbook** of patterns to carry forward |
+| Bar to capture | Low — "worth noting" | High — "worth carrying into every future project" |
+| Granularity | Raw, project-tagged | Curated, generalized, per-type |
+| Lives where | `~/.atom/nucleus/` | `~/.atom/learnings/` |
+| Auto-copied to new projects? | No | Yes (filtered by stack tags) |
+| Optional sync | Your own private GitHub repo | Your own private GitHub repo (separate from nucleus) |
+
+**Both are 100% yours.** Nothing leaves your machine without your explicit action. atom is the system; the content is yours.
 
 ### Why it exists
 
 Code can be rewritten. The lessons you learned writing it are harder to recover. They sit in your head, get half-remembered, and quietly disappear when you start the next project. Most coding sessions teach you something — a pitfall, a pattern, an architecture decision with rationale. Without a capture system, that learning evaporates the moment the session ends.
 
-`nucleus` catches those lessons mid-session and lets future sessions, in any project, benefit from them. Together with atom's structure, you get more than a starter template: code you can rewrite, plus knowledge you can't.
+`nucleus` catches those lessons mid-session, low bar, project-tagged. `learnings` is the curated subset you've decided to carry forward — auto-copied into every new project you bootstrap. Together they give you code you can rewrite **plus knowledge you can't**.
 
 ### The flow
 
 ```
        session
           │
-          ▼  nucleus add  (raw, project-tagged)
-   ~/.nucleus/projects/<slug>/learnings.jsonl
+          ▼  nucleus add  (raw, project-tagged, low bar)
+   ~/.atom/nucleus/projects/<slug>/learnings.jsonl
           │
           ▼  nucleus promote <id>  (passes generalization test)
-   atom/learnings/<type>/<slug>.md  (curated, ships to new projects)
+   ~/.atom/learnings/<type>/<key>.md  (your local playbook)
           │
-          ▼  refine into prose
-   atom/docs/LESSONS_LEARNED.md  (essay form)
+          ▼  atom-setup new project  (filtered by stack)
+   <new-project>/learnings/<type>/<key>.md  (carried forward)
 ```
 
-The first arrow is automated when Claude is your AI (claude-managed capture mode is the default). The second is human-in-the-loop — `nucleus promote` opens `$EDITOR` so you can refine the draft before it lands. The third is rare and intentional.
+The first arrow is automated when Claude is your AI (`claude-managed` capture mode is the default). The second is human-in-the-loop — `nucleus promote` opens `$EDITOR` so you can refine the draft before it lands. The third runs every time you bootstrap a project from atom — your playbook follows you.
 
 ### Capture modes
 
@@ -139,7 +148,7 @@ The first arrow is automated when Claude is your AI (claude-managed capture mode
 | **`auto-timer`** | A background process drains a session log every N minutes (5/15/30/60). For users who don't want to think about it. |
 | **`manual`** | Claude surfaces "worth capturing?" suggestions; you run `nucleus add` yourself. For users who want full control. |
 
-Picked at `atom-setup` time, configurable later via `~/.nucleus/config.json`.
+Picked at `atom-setup` time, configurable later via `~/.atom/nucleus/config.json`.
 
 ---
 
@@ -151,7 +160,7 @@ Picked at `atom-setup` time, configurable later via `~/.nucleus/config.json`.
 | Interactive wizard | yes (4 modes) | yes | yes | no |
 | Stack presets | yes | partial | yes | no |
 | AI-tool integration | yes (multi-tool via AGENTS.md) | no | no | no |
-| Cross-project learning store | yes (nucleus) | no | no | no |
+| Cross-project memory + playbook | yes (nucleus + learnings) | no | no | no |
 | Parallel-model workflow | yes (model-race) | no | no | no |
 | Constitution / principles | yes | no | no | no |
 | Production Docker defaults | yes (4 tiers, opt-in) | partial | no | no |
@@ -209,14 +218,14 @@ atom/
 │   ├── .claude/       Claude-specific skills (nucleus + agent skills)
 │   └── package.json   Baseline scripts
 │
-├── learnings/         Generalised, structured learnings (graduation layer)
-│
 ├── bin/               Global CLIs (install once per machine)
+│   ├── atom/          Top-level help dispatcher (`atom --help`)
 │   ├── atom-setup/    Interactive wizard
-│   ├── nucleus/       Cross-project learning store CLI
+│   ├── nucleus/       Your session memory CLI
+│   ├── learnings/     Your playbook CLI
 │   └── model-race/    Parallel AI model comparison via Git worktrees
 │
-├── scripts/           Maintenance scripts (e.g. copy-learnings.mjs)
+├── scripts/           Maintenance scripts (e.g. copy-learnings.mjs, test-atom-setup.sh)
 │
 └── extras/            Opt-in stack presets, copied based on user choice
     ├── docker/                Dockerfile, compose, devcontainer, CI
@@ -300,7 +309,7 @@ atom/
 atom evolves with every project that's shipped from it. The flow:
 
 1. **During the project**, capture learnings via `nucleus add` (or `docs/INBOX.md` if you prefer manual).
-2. **At the end of the project**, run `nucleus promote <id>` for entries that pass the generalization test. Files land in `atom/learnings/<type>/<slug>.md`.
+2. **At the end of the project**, run `nucleus promote <id>` for entries that pass the generalization test. Files land in your local playbook at `~/.atom/learnings/<type>/<slug>.md` and ride forward into every new project you bootstrap.
 3. **Periodically**, refine those into prose for `docs/LESSONS_LEARNED.md`.
 
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the rules and the generalization test.

atom-setup

@@ -38,7 +38,7 @@ if [ "$NODE_MAJOR" -lt 18 ]; then
   exit 1
 fi
 
-CLIS=(atom-setup nucleus model-race)
+CLIS=(atom atom-setup nucleus learnings model-race)
 
 # Find the GLOBAL atom-setup (skip cwd in PATH so we don't recurse into
 # this script). Used both for "already installed?" detection and for the

bin/atom-setup/bin/atom-setup.js

@@ -257,7 +257,9 @@ function printCheatsheet(state, preflight) {
   const tasks = [];
 
   if (a.nucleusEnabled) {
-    tasks.push(`${color.cyan('•')} Initialize nucleus on this machine: ${color.cyan('nucleus init')}`);
+    tasks.push(`${color.cyan('•')} Initialize nucleus (your session memory): ${color.cyan('nucleus init')}`);
+    tasks.push(`${color.cyan('•')} Initialize learnings (your local playbook): ${color.cyan('learnings init')}`);
+    tasks.push(`  ${color.dim('Both are 100% yours. Optional GitHub sync to your private repo.')}`);
   }
   if (a.mem0) {
     tasks.push(`${color.cyan('•')} Set up mem0 MCP: see ${color.cyan('docs/INSTALL.md')} (or wherever it lives in scaffold)`);
@@ -275,6 +277,8 @@ function printCheatsheet(state, preflight) {
     tasks.push(`${color.cyan('•')} Push to your remote when ready: ${color.cyan(`git remote add origin ${a.gitRemote} && git push -u origin main`)}`);
   }
 
+  tasks.push(`${color.cyan('•')} See every atom command in one place: ${color.cyan('atom --help')}`);
+
   if (tasks.length > 0) {
     note(tasks.join('\n'), `What's next`);
   }

bin/atom-setup/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atom/atom-setup",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Interactive wizard that transforms a cloned atom checkout into a personalized project.",
   "type": "module",
   "bin": {

bin/atom-setup/src/lib/writer.js

@@ -5,6 +5,7 @@ import {
   existsSync, readdirSync, statSync, copyFileSync, mkdirSync,
   writeFileSync, rmSync, renameSync, readFileSync,
 } from 'node:fs';
+import { homedir } from 'node:os';
 import { join, dirname, relative } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import {
@@ -13,6 +14,9 @@ import {
 } from './manifest.js';
 import { renderLicense } from './licenses.js';
 
+const ATOM_HOME = process.env.ATOM_HOME || join(homedir(), '.atom');
+const USER_LEARNINGS_DIR = process.env.ATOM_LEARNINGS_HOME || join(ATOM_HOME, 'learnings');
+
 export async function applyState(state, cwd, opts = {}) {
   const log = opts.log || (() => {});
   const dryRun = opts.dryRun === true;
@@ -36,8 +40,11 @@ export async function applyState(state, cwd, opts = {}) {
     copyDockerTier(root, answers.dockerTier, log, dryRun);
   }
 
-  // 5. Filter and copy learnings (from learnings/ source dir).
-  if (existsSync(join(root, 'learnings'))) {
+  // 5. Filter and copy learnings (from the user's local playbook at
+  //    ~/.atom/learnings/, NOT from anything in the atom repo).
+  //    No-op if the user has not yet promoted any learnings or hasn't
+  //    run `learnings init`.
+  if (existsSync(USER_LEARNINGS_DIR)) {
     copyLearnings(root, answers.stack, log, dryRun);
   }
 
@@ -96,13 +103,15 @@ function copyDockerTier(root, tier, log, dryRun) {
 }
 
 function copyLearnings(root, stack, log, dryRun) {
-  const src = join(root, 'learnings');
+  const src = USER_LEARNINGS_DIR;
   const tags = new Set(STACK_TAGS[stack] || ['universal']);
 
   function walk(dir) {
     for (const entry of readdirSync(dir)) {
       const p = join(dir, entry);
-      if (statSync(p).isDirectory()) {
+      let s;
+      try { s = statSync(p); } catch { continue; }
+      if (s.isDirectory()) {
         walk(p);
       } else if (entry.endsWith('.md') && entry !== 'README.md') {
         const rel = relative(src, p);
@@ -114,13 +123,12 @@ function copyLearnings(root, stack, log, dryRun) {
         if (!matches(appliesTo, tags)) continue;
 
         if (dryRun) {
-          log(`(dry-run) learning copy: ${rel}`);
+          log(`(dry-run) learning copy from playbook: ${rel}`);
           continue;
         }
-        if (dst === p) continue;
         mkdirSync(dirname(dst), { recursive: true });
         copyFileSync(p, dst);
-        log(`learning copy: ${rel}`);
+        log(`learning copy from playbook: ${rel}`);
       }
     }
   }