Phase B: mechanical plugin sync (structure source-of-truth + coherence check + version discipline)

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "nexus",
       "description": "The session ritual (/done, /status, /idea), failure logging, session pre-flight, branch verification, and a KB-root foundations bootstrap (/nexus-init). Works in Claude Code and Cowork. Companion to The Coherence Problem field guide.",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "source": "./",
       "author": {
         "name": "CrowCreation",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Operational discipline for Claude Code and Cowork: the session ritual (/done, /status, /idea), failure logging with the three-occurrence rule, session pre-flight, branch verification, and a KB-root foundations bootstrap (/nexus-init). Companion to The Coherence Problem field guide.",
   "author": {
     "name": "CrowCreation",

.github/workflows/coherence.yml

@@ -0,0 +1,21 @@
+name: coherence
+
+# Asserts the plugin agrees with its own single source of structural truth
+# (nexus.structure.json). nexus-public is a separate repo, so this CI is a clean
+# add. The check is zero-dependency stdlib Python — no install step needed.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Run plugin coherence check
+        run: python scripts/check_plugin_coherence.py

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+# Pre-commit hooks for the Nexus plugin.
+#
+# Install once:
+#   pip install pre-commit
+#   pre-commit install
+#
+# The coherence check is zero-dependency stdlib Python, so it runs against the
+# system interpreter with no environment to build.
+repos:
+  - repo: local
+    hooks:
+      - id: nexus-plugin-coherence
+        name: Nexus plugin coherence
+        description: Assert every consumer agrees with nexus.structure.json
+        entry: python scripts/check_plugin_coherence.py
+        language: system
+        pass_filenames: false
+        always_run: true

CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to the Nexus plugin are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+the plugin aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The version here matches `.claude-plugin/plugin.json` and
+`.claude-plugin/marketplace.json`. Every command, hook, or structure change bumps
+the version and adds an entry below.
+
+## [0.7.0] - 2026-06-20
+
+Phase B: mechanical sync so the plugin cannot silently drift from its own source
+again — on the plugin-to-repo axis and the plugin-to-user axis.
+
+### Added
+
+- `nexus.structure.json` — single machine-readable source of structural truth
+  (failure-log path, session-state dir, universe path, PARA folders, frontmatter
+  fields, command set, optional drift vocabulary), narrated by a thin
+  `STRUCTURE.md`.
+- `scripts/check_plugin_coherence.py` — zero-dependency coherence check that
+  asserts every consumer agrees with `nexus.structure.json`: no stale state paths
+  under an old `.nexus` directory, one failure-log path everywhere, the command
+  set matching, and the drift vocabulary consistent wherever it appears.
+- `.pre-commit-config.yaml` and `.github/workflows/coherence.yml` — run the
+  coherence check on commit and in CI.
+- `CHANGELOG.md` (this file) and a contributing rule: every command, hook, or
+  structure change bumps the version and adds a changelog entry.
+- `docs/updating.md` — how to keep an installed plugin current (CLI update versus
+  desktop Customize panel; remove-and-re-add when greyed), linked from the README.
+- Offline staleness surface: `session_preflight.py` prints the installed plugin
+  version (read from the plugin manifest). No network call.
+
+### Changed
+
+- Drift categories are now consistently an **optional, emergent vocabulary**,
+  never imposed on a day-one log. The seed template (`templates/failure-log.md`)
+  is category-free; `/nexus-init` now seeds the same category-free log the setup
+  prompt does; the seven codes remain only as an opt-in reference in the
+  failure-logging skill, CLAUDE-lite, and `/failure`. This resolves the earlier
+  inconsistency where a `/nexus-init` repo got a categorised log and a
+  setup-prompt repo got a category-free one.
+
+## [0.6.0] - 2026-06-20
+
+Phase A: reconcile the plugin onto the KB-root state model, so install, scaffold,
+and the session ritual all operate on one structure.
+
+### Changed
+
+- `/failure`, `/field-report`, and the three hooks now read and write the root
+  `failure-log.md` and `.claude/session-state/`, replacing the old `.nexus`
+  directory model. `/failure` is format-tolerant — it matches the log shape
+  already in use rather than imposing one.
+- `/nexus-init` repurposed to scaffold the KB-root foundations (root
+  `failure-log.md`, the `KB/` PARA skeleton, day-one hygiene files), idempotently.
+- README, ROADMAP, manifests, and `templates/universe.md` updated to the
+  reconciled command set and KB-root framing.
+
+### Removed
+
+- `/nexus-onboard` — the one-shot universe-mapping interview. Universe mapping is
+  now seeded by the setup prompt and kept living by `/done` and the weekly review.
+- `templates/config.json` — dead under the KB-root model (nothing read it).
+
+### Added
+
+- `docs/cowork-setup.md` — the single desktop story (no-terminal install via the
+  Customize panel, namespaced `nexus:` commands, refreshing a stale plugin).

CONTRIBUTING.md

@@ -35,6 +35,25 @@ Concrete incidents are more valuable than abstract opinions.
 
 Nexus is intentionally narrow.
 
+## Keeping the plugin coherent
+
+Two rules keep the plugin honest with itself and current for the people who
+install it:
+
+- **Structure lives in one place.** Paths, the command set, and the drift
+  vocabulary are declared once in [`nexus.structure.json`](./nexus.structure.json).
+  Every consumer restates them in its own prose or code, so when you change one,
+  change it everywhere and run `python scripts/check_plugin_coherence.py`. The
+  check runs on commit (pre-commit) and in CI; it fails with a precise diff if a
+  consumer drifts.
+- **Every command, hook, or structure change bumps the version and adds a
+  changelog entry.** Update `version` in both `.claude-plugin/plugin.json` and
+  `.claude-plugin/marketplace.json`, and add an entry to
+  [`CHANGELOG.md`](./CHANGELOG.md). This is how an installed plugin can tell it is
+  behind its source.
+
+---
+
 The goal is not to build the biggest system.
 The goal is to understand how coherence degrades in real workflows,
 and which disciplines prevent it.

GETTING-STARTED.md

@@ -0,0 +1,60 @@
+# Getting started
+
+A greenfield setup, from an empty terminal to a running Nexus, in about ten minutes. This is the terminal path, which is the reliable one today. Prefer the desktop app? See [Using Nexus in Cowork](./docs/cowork-setup.md).
+
+## What you need first
+
+- **Git** - version control ([install](https://git-scm.com/downloads)).
+- **Claude Code** - the AI tool that runs in your terminal ([install](https://claude.ai/code)).
+- A **GitHub account** - so your work is backed up ([sign up](https://github.com)).
+
+## Steps
+
+1. **Open a terminal.**
+
+2. **Make a folder for your Nexus and go into it.**
+   ```
+   mkdir my-nexus
+   cd my-nexus
+   ```
+
+3. **Turn it into a Git repository.**
+   ```
+   git init
+   ```
+
+4. **Start Claude Code.**
+   ```
+   claude
+   ```
+
+5. **Install the Nexus plugin** (this is what gives you the commands). Type these in the Claude session:
+   ```
+   /plugin marketplace add crowcreation/nexus
+   /plugin install nexus@nexus
+   ```
+
+6. **Scaffold your Nexus.** Type:
+   ```
+   /nexus-init
+   ```
+   This creates your `failure-log.md`, the `KB/` folders, and the day-one hygiene files. It is safe to run again later; it only adds what is missing.
+
+   *Prefer a guided setup that also captures your goal and maps your world?* Instead of `/nexus-init`, paste the [setup prompt](./setup-prompt.md) and answer its few questions.
+
+7. **Back it up to GitHub.** Ask Claude: *"back this up to a new private GitHub repo"*. It will run the steps for you. The first time, it may ask you to sign in once with `gh auth login` (choose GitHub.com and log in through the browser).
+
+8. **You are running.** From now on a session has a shape:
+   - `/status` to start - what should I focus on?
+   - `/idea` as you go - capture a thought.
+   - `/done` to close - every time. Two minutes: what happened, what broke.
+
+   Once a week, take about an hour for the weekly review: read your failure log, look for anything that has happened three times, and tidy your projects.
+
+> The commands may show in the menu with a `nexus:` prefix (for example `nexus:done`). That is the same command.
+
+## Where next
+
+- [Your First Hour](./learn/00-your-first-hour.md) - what these five things are, and why.
+- [The Disciplines](./learn/04-the-disciplines.md) - the habits that make it compound.
+- [The course](./learn/) - the full picture.

README.md

@@ -8,6 +8,8 @@ Operational coherence for persistent AI systems. When AI becomes a long-running
 
 **This is for** developers running persistent AI workflows (Claude Code, Cursor, Aider) where operational state survives across sessions, repositories evolve over time, and instructions outlive the conversation that created them. If your AI usage is mostly isolated conversations, many of these pathologies never emerge.
 
+**Just want to set it up?** [Getting Started](./GETTING-STARTED.md) takes you from an empty terminal to a running Nexus in about ten minutes.
+
 ---
 
 ## Start here: the discipline
@@ -64,6 +66,8 @@ Privacy: no telemetry, no network calls, no data leaves your machine. [Full sour
 
 **Requirements**: [Claude Code](https://claude.ai/code), Python 3.8+, Git.
 
+**Keeping it current**: the plugin gets updates; an installed copy can fall behind. [Keeping Nexus updated](./docs/updating.md) covers the CLI and desktop routes. (The paste layer above never has this problem — you own your copy.)
+
 ### Using Nexus in Cowork
 
 Cowork (the desktop app) loads plugin commands, not the command files sitting in your project folder, and the commands appear namespaced (`nexus:done`, `nexus:status`). The full desktop story — installing with no terminal, the namespaced commands, and refreshing a stale plugin — lives in one place: [Using Nexus in Cowork](./docs/cowork-setup.md).
@@ -73,6 +77,7 @@ Cowork (the desktop app) loads plugin commands, not the command files sitting in
 ## Go deeper
 
 - [ROADMAP.md](./ROADMAP.md) - what's built today versus what's planned, honestly
+- [STRUCTURE.md](./STRUCTURE.md) - the one structural shape, the coherence check that keeps the plugin honest with itself, and the two-layer sync trade-off
 - [The Coherence Problem](./docs/the-coherence-problem.md) - the full field guide: why persistent AI systems degrade and the five drift modes
 - [The Operator Stack](./docs/the-operator-stack.md) - five layers, from substrate to shared intelligence
 - [Patterns](./patterns/) - five steal-this patterns with implementation details

ROADMAP.md

@@ -6,7 +6,7 @@ Nexus is an experimental, evolving field manual, not a finished product. This pa
 
 - **The failure log** - the core primitive. Append-only record of what broke and why.
 - **`/done`** - the day-one session-close command: daily note, failure-log entry with three-occurrence check, project state nudge, optional knowledge capture.
-- **`/failure`** - plugin command for structured failure-log entries with drift categories.
+- **`/failure`** - plugin command for failure-log entries. Format-tolerant: matches the shape your log already uses, with drift categories as an optional vocabulary rather than an imposed one.
 - **`/field-report`** - formats and redacts a log entry for sharing with other operators. Nothing sent automatically.
 - **`/nexus-init`** - one idempotent command to bootstrap the KB-root foundations (root `failure-log.md`, the `KB/` PARA skeleton, day-one hygiene files). The one-command alternative to the setup prompt.
 - **The three hooks** - session pre-flight, branch verification before commit, and session save.

STRUCTURE.md

@@ -0,0 +1,67 @@
+# Structure
+
+Nexus has one structural shape, and it is written down once, in
+[`nexus.structure.json`](./nexus.structure.json). That file is the single source
+of truth for where state lives and what the plugin ships:
+
+- the failure log is the root `failure-log.md`
+- session state lives under `.claude/session-state/`
+- the living map is the root `universe.md`
+- the knowledge base is PARA: `KB/Projects`, `KB/Areas`, `KB/Knowledge`,
+  `KB/Goals`, `KB/Daily`, `KB/Archive`, `KB/_Admin`
+- day-one frontmatter is four fields: `title`, `status`, `tags`, `updated`
+- the commands are `done`, `status`, `idea`, `failure`, `field-report`,
+  `nexus-init`
+- drift categories are an optional, emergent vocabulary, never imposed on a
+  day-one log
+
+## Why a JSON file nothing imports
+
+The markdown commands and the Python hooks each restate these paths in their own
+prose and code. Editing `nexus.structure.json` does not magically rewrite them —
+there is no build step, and a markdown command cannot import a JSON value.
+
+So the JSON is canonical for a different reason: a check makes deviation fail.
+[`scripts/check_plugin_coherence.py`](./scripts/check_plugin_coherence.py) loads
+`nexus.structure.json` and asserts that every consumer agrees with it — the same
+failure-log path everywhere, the command set matching, no stale state paths under
+an old `.nexus` directory left behind, the drift vocabulary consistent wherever
+it appears. The check
+runs as a pre-commit hook and a GitHub Action. If a command drifts from the
+declared structure, the commit fails with a precise diff.
+
+This is the plugin practising what Nexus preaches. The whole project exists
+because a distribution artefact can silently drift from its own source. The
+0.5.0 to 0.6.0 reconciliation happened because two state models (an old `.nexus`
+directory and KB-root) had been living in one plugin for weeks without anyone
+noticing. The
+check is the rule written so it cannot happen a third time.
+
+## The two scaffolders are thin emitters of one structure
+
+`/nexus-init` and the setup prompt both build the same KB-root foundations. They
+are two ways to emit the one structure in `nexus.structure.json`, kept in
+agreement by the check. `/field-report` is the human backstop for the drift a
+check cannot see — the semantic, "this got sloppy" kind — by formatting failure
+entries for sharing with other operators.
+
+## Two layers, two sync stories
+
+Nexus ships its discipline on two layers, and they trade off differently:
+
+- **The paste layer** — [CLAUDE-lite](./templates/CLAUDE-lite.md) and the
+  [setup prompt](./setup-prompt.md). You copy it into your own repo and own the
+  copy outright. There is **no user-sync problem**: nothing of ours sits in your
+  repo waiting to go stale. The cost is the other side of the same coin — you get
+  no automatic updates. When the patterns improve, your pasted copy does not.
+
+- **The plugin** — installed from the marketplace. It **does** get updates: a new
+  version is one `/plugin marketplace update` (or a Customize-panel reinstall)
+  away. The cost is update friction — the plugin can fall behind its source, and
+  keeping it current is a real step (see [docs/updating.md](./docs/updating.md)).
+
+The conclusion we build around, on purpose: the **discipline** lives in the paste
+layer, where it can never go stale on the user, and the **enforcement
+automation** lives in the plugin, where the update cost buys you hooks and checks
+that a paste cannot provide. Discipline first; the plugin is the graduation step,
+not the entry point.

docs/updating.md

@@ -0,0 +1,59 @@
+# Keeping Nexus updated
+
+The plugin gets better over time. Unlike the paste layer (CLAUDE-lite and the
+setup prompt, which you own outright once copied), an installed plugin can fall
+behind its source. This is how you pull the latest version. Nothing here phones
+home — updating is always something you do, never something that happens to you.
+
+> First install is a different thing and lives elsewhere. The terminal install is
+> in the [README](../README.md#going-further-the-plugin); the desktop, no-terminal
+> install is in [Using Nexus in Cowork](./cowork-setup.md). This page is only
+> about moving an already-installed plugin to a newer version.
+
+## Am I behind?
+
+At session start the pre-flight prints the installed version, for example
+`Nexus plugin v0.7.0`. Compare it against the latest entry in
+[CHANGELOG.md](../CHANGELOG.md). If yours is older, update with one of the routes
+below. The check is deliberately offline — the plugin does not reach out to a
+marketplace to compare, so this manual glance is the surface.
+
+## Terminal (CLI)
+
+Two steps, because refreshing the marketplace listing and reinstalling the plugin
+are separate:
+
+```
+/plugin marketplace update
+/plugin install nexus@nexus
+```
+
+The first pulls the latest marketplace metadata for `crowcreation/nexus`; the
+second reinstalls the plugin at the version the marketplace now points to. Run
+both. Updating the marketplace alone does not move an installed plugin.
+
+## Desktop app (Cowork)
+
+The desktop app has no `/plugin` command — it is CLI-only and does nothing in the
+Chat, Cowork, or Code tabs. Plugins are managed through the **Customize panel**.
+
+- Open the Customize panel and find the Nexus plugin under its plugins or
+  marketplace section.
+- If an update control is offered, use it.
+- **If the plugin looks greyed out or stale, or an update control is missing,
+  remove the plugin and re-add it.** A clean remove-and-re-add picks up the latest
+  version. This is the reliable desktop refresh today.
+
+Remember the desktop commands are namespaced: `nexus:done`, `nexus:status`,
+`nexus:idea`, `nexus:failure`. After an update, type `/` and confirm they still
+appear before relying on them.
+
+## A note on the two layers
+
+If update friction ever gets in your way, remember the discipline does not depend
+on the plugin. The five patterns live in [CLAUDE-lite](../templates/CLAUDE-lite.md),
+which you paste and own — it never goes stale on you because nothing of ours sits
+in your repo. The plugin is the enforcement and graduation layer on top. Keep the
+discipline in the paste layer; treat the plugin update as the cost of the
+automation it buys you. See [STRUCTURE.md](../STRUCTURE.md#two-layers-two-sync-stories)
+for the full trade-off.