geneseed 4.9.4 → 4.14.0

package/CHANGELOG.md

@@ -8,6 +8,112 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [4.14.0] — 2026-10-22
+
+Minor: the React kit supports webpack projects as well as Vite.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` to get the new kit text; nothing changes on a machine until something re-emits.
+
+### Changed
+- **The `react` kit supports webpack as well as Vite** (#368). The `react` skill reads the bundler from `package.json` and loads its side file: the new `react/webpack.md` (config, client-side routing with `historyApiFallback` and `publicPath`, `DefinePlugin` env values, a webpack build-failure table) or `react/vite.md`. The kit rules, both agents, the Jest configuration table in `react-testing` and every theme's descriptions now name both bundlers.
+
+## [4.13.0] — 2026-10-21
+
+Minor: sharper ported skills, a wiki that keeps its history, and self-improvement notes that carry their evidence.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` to get the new skill and agent text; nothing changes on a machine until something re-emits. Notes already in `notebook/skill-notes/` and `notebook/agent-notes/` keep working as written; only new lines take the new format.
+
+### Changed
+- **Self-improvement notes carry their evidence and their scope** (#366). A note is now one line, `- [skill|general] <correction> — seen: <what happened, against what was expected> (<date>)`, and an agent's `spec-feedback:` line takes the same shape. `seen:` is what a correction is judged by when `geneseed diff` hands it back for folding into `src/`, and pruning drops the lines without one first. `general` marks a correction that would fix other skills or agents too, so it belongs in a law, doctrine or memory rather than one file. The `geneseed diff` report explains both markers. Agents now share one self-improvement footer (`src/agents/_self-improvement.md`) instead of 29 copies; rendered agents differ only by the new wording.
+- **The wiki writes history, not the present** (#365). Wiki claims are dated, code claims cite `owner/repo@commit`, and a correction supersedes a claim rather than rewriting it. A new report-only lint pass lists contradictions, orphans and overtaken claims without restructuring the wiki. Adapted from mattpocock/skills' chief-of-staff.
+- **The mattpocock ports are sharpened against upstream `5beb35b`** (#365):
+  - `parallel-agents`: each slice branches off the integration tip when it is dispatched and merges the tip back before returning, so a later slice no longer misses its blocker's merged work. A whole-branch review follows.
+  - `codebase-design`: an interface is designed twice, and an ADR is not silently reopened.
+  - `research` and the `researcher` agent: one read in the source that owns a claim stands on its own; any other claim still needs two sources.
+  - `ship`: the docs check moves before the push it gates.
+  - `plan`, `wayfinder`, `prototype`, `develop`, `debug`, `rule`, `brainstorm`, `handoff` and `skill-forge` get smaller fixes: slice sizing, ticket graduation, mocking only at boundaries, checking for an existing guardrail before proposing one, and trigger pruning.
+  - New credits on `parallel-agents`, `skill-forge`, `brainstorm` and `wiki`.
+
+## [4.12.0] — 2026-10-21
+
+Minor: a second opt-in kit, `react`, and the setup wizard asks about each kit on its own.
+
+### Upgrade notes
+- Nothing to rebuild unless you want the new kit. Default installs are unchanged: no kit is on. To turn it on, run `geneseed build --emit <target> --kits react` (or `--kits react,spring-boot` for both), or use **Installs → Kits** in the web console.
+
+### Added
+- **The `react` kit** (#362), for React 18 or 19 apps built with Vite, in TypeScript or JavaScript, tested with Jest and React Testing Library. Skills `react` (with side files for Vite and accessibility) and `react-testing`; agents `react-engineer` and `react-reviewer` (read-only); kit rules, and a banned-API gate that keeps `ReactDOM.render(`, `findDOMNode`, Enzyme, `react-test-renderer` and `@testing-library/react-hooks` out of kit files. Adapted from affaan-m/everything-claude-code (MIT), rewritten and condensed for Vite and Jest, with no Server Components material.
+
+### Changed
+- **The setup wizard asks one yes/no per kit** (#362). A single pick could not turn on two kits at once.
+
+### Repository
+Not in the package; how Geneseed itself is built and checked.
+- CI's golden cells run as two parallel jobs per platform, emit and CLI (#361). On Windows that leg drops from about 7 minutes in sequence to about 4. The unit suite runs at `--test-concurrency=8` on Linux and in the publish job; Windows keeps the default, where the flag bought nothing. If branch protection names the old `node-cells (<os>)` checks, they now report as `node-cells (<os>, emit)` and `node-cells (<os>, cli)`.
+- The unit suite drops three repeated full-cost runs (#363): two update-flow arms use a doctor stand-in (the real rejection and exact rollback stay in `update_git`), the packaging test counts themes in process instead of a second `doctor --all`, and `--no-deletion-gate` replays only the 67 real-loss rows. 151 s to 139 s locally, same 2012 tests.
+
+## [4.11.2] — 2026-10-21
+
+Patch: a clone install on macOS or Linux puts the `geneseed` command on your PATH.
+
+### Upgrade notes
+- Nothing to rebuild. If `geneseed` is not found in a new terminal, run `./geneseed link` from your clone and accept the offer to add `~/.local/bin` to your shell's startup file.
+
+### Fixed
+- **A clone install puts `geneseed` on your PATH on macOS and Linux** (#359). `./install` never linked the command, and `geneseed link` wrote it to `~/.local/bin`, which macOS zsh does not search, so `geneseed` was not found (reported 2026-10). `./install` now runs `link` when `geneseed` is not found yet, and `link` offers, in a terminal, to add the folder to your shell's startup file (`~/.zshrc`, or `~/.bashrc` / `~/.bash_profile` for bash). It appends one marked block, never twice; `geneseed unlink` removes it. Outside a terminal it prints the line to add, as before.
+
+## [4.11.1] — 2026-10-21
+
+Patch: the web console on a machine with only IBM Bob (or any host but OpenCode): it opens on the install you have, the first-deploy form asks a per-repo mode for its folder, and the doctor stops reading a misplaced project install as a broken bundle.
+
+### Upgrade notes
+- Restart the console after updating (`geneseed web restart`) so it serves the rebuilt UI. If a per-repo install landed in `Harness/` inside your Geneseed clone, remove it with `./geneseed uninstall --target Harness --yes`, then delete `Harness/`.
+
+### Fixed
+- **The web console works on a machine without OpenCode** (#357). It always opened on the OpenCode global dir, so with only IBM Bob installed the Overview showed the first-deploy form over a working `~/.bob`, and nothing could re-point it (the harness selector hides itself below two installs). When nothing is deployed where it looks, the console now shows the first active install it finds, a global before a project, and follows a first deploy to where it landed.
+- **The first-deploy form asks a project mode for its folder** (#357). Picking a per-repo mode (`bob`, `claude`, `opencode`, `openclaude`) sent a Build with no folder, so the files landed in `Harness/` inside the Geneseed clone, where the host never looks. The form now asks for the folder (typed or Browse…) and deploys there; Build refuses a per-repo mode it has no folder for; the portable `files` bundle is left to the CLI. To remove an install misplaced this way, run `./geneseed uninstall --target Harness --yes` in the clone, then delete `Harness/`.
+- **The doctor's committed-bundle check no longer reads a Claude, Bob or OpenClaude project install as a broken bundle** (#357). Such a tree has a `.bob/`-style data dir, not the bundle layout, so every file read "missing" (178 lines on the reported machine) and no rebuild could clear them.
+
+## [4.11.0] — 2026-10-21
+
+Minor: the self-improvement loops write to notebook notes instead of the installed skill or agent file, the web console gains a Kits section, and `./install` waits for your answers and finds tools installed for one user.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` once after updating so installed skills, agents and AGENT.md carry the new self-improvement footer. Lessons the loops wrote into installed files before this release are still exported by `upgrade` into `improvements/`, as before.
+
+### Added
+- **Web console: Kits section** (#353). A top-level Kits page between Library and Loops: a list and a detail page per kit (rules, banned APIs, members linked to the Library, upstream pin and compare link, a switch per install that rebuilds through the install job). Installs → Kits shares its staging and Apply control. `GET /api/kits` now carries rules, word budget, banned APIs and credits, and the Library shows a `kit:` badge on kit members.
+
+### Changed
+- **Self-improvement writes to a sidecar, not the skill** (#354). The skill and agent loops used to edit the rendered file in place, which the doctor reported as stale and the next rebuild erased. They now write corrections to `notebook/skill-notes/<name>.md` and `notebook/agent-notes/<name>.md` (seed-once, agent-owned, never overwritten), and read them back before the skill runs or the agent is dispatched. `geneseed diff` lists the notes and `--out` exports them for back-porting into `src/`. AGENT.md names the notes paths, so the carrier ceilings rise by exactly that text (full 62_263, lean 39_156).
+
+### Fixed
+- **Setup's prompts no longer answer themselves in a real terminal** (#356). Reading `process.stdin` puts a terminal's input in non-blocking mode, and the line reader took the resulting `EAGAIN` for end of input: "Continue without one? (y/N)" printed and answered N at once, so `./install` stopped before anyone could type, and every other wizard question silently took its default. The reader now waits for the keypress.
+- **A tool installed for one user is found** (#356). Setup looked only on PATH, so an IBM Bob installed under the user's profile read as missing. It now also checks `~/.local/bin`, `~/bin`, each tool's own installer dir (`~/.opencode/bin`, `~/.claude/local`), the per-user npm prefix on Windows, and Bob's desktop app folder (`%LOCALAPPDATA%\Programs` on Windows, `/Applications` and `~/Applications` on macOS); a tool found there is listed with its path. When nothing is found, setup asks for the tool's path before offering to stop. The double-clickable `install.command` now waits for Enter before its window can close, as `install.cmd` already did.
+
+## [4.10.0] — 2026-10-20
+
+Minor: opt-in kits (and a first one, `spring-boot`), credits for adapted content, a weekly upstream-drift check, and a web Kits tab.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` once after updating. Default installs are unchanged (no kit is on); enable one with `geneseed build --kits spring-boot` or the new **Installs → Kits** tab.
+
+### Added
+- **Kits: opt-in bundles of skills, agents and rules** (#343). `src/kits/<kit>.json` declares a kit; `--kits a,b` turns kits on (`none` turns all off), the install records `Active kits:` and `rebuild-all`, `update`, `migrate` and the web console keep it. A plain build warns before it drops a kit an install has; `status` lists kits and files you edited that were kept from a kit turned off. The doctor gates kit membership, links (kit → core only), registry rows and each kit's rules budget.
+- **The `spring-boot` kit** (#349), adapted from piomin/claude-ai-spring-boot (Apache-2.0) and rewritten for Spring Boot 4: skills `spring-boot`, `spring-data-jpa`, `spring-testing`; agents `spring-boot-engineer`, `spring-reviewer` and `spring-security` (both read-only), `kubernetes-specialist`, `docker-expert`, `devops-engineer`; kit rules. A banned-API gate keeps removed Boot APIs (`@MockBean`, `javax.persistence`, …) out of kit files.
+- **Credits for adapted content** (#342). `src/upstreams.json` records each upstream's repo, commit, author and licence; a `{{CREDIT:key:path}}` token renders an "Adapted from … modified." line and the skill ships the licence beside it. Superpowers, Matt Pocock's skills and vibe-wise ports are now credited; the README gains a Credits section, gated by the doctor.
+- **Weekly upstream-drift check** (#344, #351). A CI job compares every pinned upstream with its HEAD on the files Geneseed uses and keeps one tracking issue per upstream; vendored skills are compared on their folder only, and `"frozen": true` entries are skipped.
+- **Web console: Installs → Kits** (#350). One row per global and project install, a switch per kit, apply through the usual confirm and rebuild job.
+
+### Changed
+- `react-view-transitions` re-vendored at upstream HEAD (Next.js no longer needs the `experimental.viewTransition` flag; back/forward navigation and shared-element guidance updated) (#351).
+- `debug` proves a forced red landed by diffing against a pristine copy; `geneseed-code-review` searches the repo for its standards files (#351).
+
+### Fixed
+- The web install action no longer re-themes an install you are not viewing (#350).
+
 ## [4.9.4] — 2026-10-18
 
 Patch: `git reset --hard` asks only when it would abandon existing commits, not over uncommitted work.

package/README.md

@@ -157,7 +157,7 @@ geneseed web stop            # stop the daemon
 geneseed web status          # is it running, and where
 ```
 
-The sidebar has six pages: **Overview** (what's deployed, health, recent jobs), **Constitution** (the rules and doctrine switches), **Library** (skills, agents, the wiki), **Personal** (your rules, profile, memory, notebook), **Installs** (hosts, local edits, doctor, server) and **Docs** — this documentation, opening on the Understand track, with a map of what Geneseed put on your machine.
+The sidebar has eight pages: **Overview** (what's deployed, health, recent jobs), **Constitution** (the rules and doctrine switches), **Library** (skills, agents, the wiki), **Kits** (opt-in stack bundles), **Loops** (the loop catalogue), **Personal** (your rules, profile, memory, notebook), **Installs** (hosts, local edits, doctor, server) and **Docs** — this documentation, opening on the Understand track, with a map of what Geneseed put on your machine.
 
 It binds to `127.0.0.1` only and runs entirely offline — no npm needed at runtime; the UI build ships in `web/dist/`. Mutating actions run in the background and report back as toasts (fire-and-notify), guarded by a per-session token so other sites can't trigger them. A global **Spotlight** search in the topbar jumps to any agent, skill, rule, doc, or MCP server. Rebuild the UI after changing anything under `web/src/` with `cd web && npm install && npm run build`. If `web/dist/` is missing (fresh clone, never built), `geneseed web` offers to run that build for you — answer `Y` and it installs, builds, and starts the server; in non-interactive shells it prints the manual recipe instead.
 
@@ -334,7 +334,7 @@ geneseed rebuild-all   # re-render every registered install in its own theme + m
 ./geneseed upgrade     # just the content refresh (remembers theme + emit mode)
 ```
 
-**Local edits survive.** If the agent refined its deployed agent/skill files in place, an upgrade exports that drift to an `improvements/` file inside the install before overwriting. Details: [Upgrade](docs/guides/upgrade.md).
+**Local edits survive.** The self-improvement loops write to notes under `notebook/`, which no rebuild touches. If you or the agent edited deployed agent/skill files in place anyway, an upgrade exports that drift to an `improvements/` file inside the install before overwriting. Details: [Upgrade](docs/guides/upgrade.md).
 
 ## 📚 Documentation
 
@@ -367,6 +367,20 @@ Three things that bite when you don't know them:
 - **The version has one owner: `harness.config.json`.** `package.json` mirrors it and a test fails the fork. Never `npm version` — it edits one of the two.
 - **Publishing is deliberate and manual.** `.github/workflows/publish.yml` uses npm trusted publishing (OIDC); there is no `NPM_TOKEN` in this repository and there must not be one. It runs only from Actions → publish → Run workflow, and the npm-side trusted publisher is keyed on that workflow's **filename** — renaming the file breaks publishing with no local symptom, which is why the file names itself in its own header and a test asserts the two agree.
 
+## 🙏 Credits
+
+Some skills and agents are adapted from other open-source skill collections, under the MIT or Apache-2.0 licence (named on each entry below). Each adapted skill names its source in its own text, and ships that upstream's licence beside it. `src/upstreams.json` pins every upstream to a commit.
+
+- `daydream` — [glebis/claude-skills](https://github.com/glebis/claude-skills) by Gleb Kalinin (MIT): the vendored `daydream` skill.
+- `react-view-transitions` — [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) by Vercel Engineering (MIT): the vendored `react-view-transitions` skill.
+- `mattpocock-skills` — [mattpocock/skills](https://github.com/mattpocock/skills) by Matt Pocock (MIT): the vocabulary and procedures behind codebase-design, wayfinder, prototype, develop, handoff and research, the spec pass of geneseed-code-review, the question rounds and questionnaire of brainstorm, the slicing of plan, the reproduction step of debug, the integration-branch rules of parallel-agents, the trigger-pruning of skill-forge, and the dated-history rule of wiki.
+- `mattpocock-skills-frozen` — [mattpocock/skills](https://github.com/mattpocock/skills) by Matt Pocock (MIT), pinned at 391a2701, the last commit carrying `resolving-merge-conflicts` (deleted upstream since): the merge-conflict step of git-history, from a skill upstream has since deleted, so the weekly drift check skips it.
+- `mattpocock-skills-2509` — [mattpocock/skills](https://github.com/mattpocock/skills) by Matt Pocock (MIT), a second key for the same repo, at the same pin as `mattpocock-skills` today (5beb35b0): the PR body of ship and the guardrail clause of rule.
+- `superpowers` — [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (MIT): the core of debug, the size step and builder check of brainstorm, the plan rules of plan, the reviewer brief behind geneseed-code-review and the reviewer agent, the review-handling steps of review-response, and the ruling format of pipeline and parallel-agents.
+- `vibe-wise` — [nykooi1/vibe-wise](https://github.com/nykooi1/vibe-wise) by Noah Kim (MIT): the state file, levels and checkpoints of learn-mode.
+- `piomin-spring-boot` — [piomin/claude-ai-spring-boot](https://github.com/piomin/claude-ai-spring-boot) by Piotr Mińkowski (Apache-2.0): the Spring Boot kit's skills and agents, rewritten and condensed for Boot 4.
+- `everything-claude-code` — [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT): the React kit's skills and agents, rewritten and condensed for Vite and Jest.
+
 ## 📄 License
 
 [MIT](LICENSE) — built by [@Arylmera](https://github.com/Arylmera).

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **4.9.4**.
+> string. Current label: **4.14.0**.
 
 ## Capabilities
 

package/docs/README.md

@@ -42,7 +42,7 @@
 
 **Memory** — [Memory](concepts/memory.md) · [Notebook](concepts/notebook.md)
 
-**Configuration** — [Footprint](concepts/footprint.md) · [Themes](concepts/themes.md) · [Exclusions](concepts/exclusions.md) · [Code intelligence (LSP)](concepts/lsp.md)
+**Configuration** — [Footprint](concepts/footprint.md) · [Themes](concepts/themes.md) · [Exclusions](concepts/exclusions.md) · [Kits](concepts/kits.md) · [Code intelligence (LSP)](concepts/lsp.md)
 
 **Working together** — [Collaboration](concepts/collaboration.md) · [Foreman mode](concepts/foreman-mode.md)
 

package/docs/concepts/collaboration.md

@@ -1,6 +1,6 @@
 ---
 group: concepts
-order: 14
+order: 15
 title: "Collaboration"
 kind: "concept"
 section: "Working together"

package/docs/concepts/enforcement-table.md

@@ -1,6 +1,6 @@
 ---
 group: concepts
-order: 24
+order: 25
 title: "Rule enforcement, by host"
 kind: "concept"
 section: "Harness"

package/docs/concepts/foreman-mode.md

@@ -1,6 +1,6 @@
 ---
 group: concepts
-order: 15
+order: 16
 title: "Foreman mode"
 kind: "concept"
 section: "Working together"

package/docs/concepts/kits.md

@@ -0,0 +1,91 @@
+---
+group: concepts
+order: 13
+title: "Kits"
+kind: "concept"
+section: "Configuration"
+description: "Opt-in bundles of skills, agents and rules for one stack, off unless you name them."
+---
+A **kit** is an opt-in bundle of skills, agents and rules for one stack. Kits are off by default and switched on per install, project or global, on every host. An install without a kit pays nothing for it. Inside an install that has it on, a kit's skills and agents are ordinary: the model picks them as it picks any other.
+
+> **You already know this:** an optional dependency group, like `pip install pkg[postgres]`. The core install stays small, and you opt into the extra parts for your stack.
+
+The first kit is `spring-boot`, for Spring Boot 4 (Spring Framework 7, Java 21+) projects. It adds nine members:
+
+| Member | Kind | What it is for |
+|---|---|---|
+| `spring-boot` | skill | Building a Spring Boot service: web layer, configuration, security, HTTP clients, logging, cloud-native packaging, and a table of Boot 4 pitfalls |
+| `spring-data-jpa` | skill | Spring Data JPA and Hibernate: entities, repositories, transactions, N+1 and fetch problems, migrations |
+| `spring-testing` | skill | Spring Boot tests: slices, `MockMvcTester`, `@MockitoBean`, Testcontainers with `@ServiceConnection` |
+| `spring-boot-engineer` | agent | Implements a Spring Boot feature end to end |
+| `spring-reviewer` | agent | Framework-aware review: layering, transactions, JPA, configuration, test slices |
+| `spring-security` | agent | Security pass on a Spring Security change |
+| `kubernetes-specialist` | agent | Kubernetes manifests, probes, resources and rollout for a Spring Boot service |
+| `docker-expert` | agent | Dockerfile, layered or native image for a Spring Boot service |
+| `devops-engineer` | agent | Build and delivery pipeline, on whatever CI the project already uses |
+
+The kit is adapted from [piomin/claude-ai-spring-boot](https://github.com/piomin/claude-ai-spring-boot) by Piotr Mińkowski (Apache-2.0), rewritten and condensed for Boot 4. Each of its skill folders ships `LICENSE-piomin-spring-boot.txt`, and each agent carries a credit line.
+
+The second kit is `react`, for React 18 or 19 apps built with Vite or webpack, in TypeScript or JavaScript, tested with Jest and React Testing Library. It adds four members:
+
+| Member | Kind | What it is for |
+|---|---|---|
+| `react` | skill | Components, hooks, state placement, data fetching, TypeScript or JavaScript, React security; side files for Vite and for webpack (config, client-side routing, env variables, build failures), read by whichever the project uses, and accessibility |
+| `react-testing` | skill | Jest and Testing Library: role queries, `userEvent`, MSW network mocks, `jest-axe`, and the Jest configuration a Vite or webpack project needs |
+| `react-engineer` | agent | Implements a React feature, or makes a broken Vite or webpack build or Jest run green |
+| `react-reviewer` | agent | Framework-aware review: hooks, state, data fetching, accessibility, React security, tests |
+
+It is adapted from [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) by Affaan Mustafa (MIT), rewritten and condensed for Vite and Jest; the webpack side file is first-party. It has no Server Components material: a client-rendered app has no server render.
+
+### Switching kits on and off
+
+```bash
+geneseed build --emit claude-global --kits spring-boot
+geneseed build --emit claude-global --kits react,spring-boot
+geneseed build --emit claude-global --kits none
+```
+
+`--kits` takes a comma-separated list. `none` and an empty value both mean no kits. An unknown kit name is refused with exit code 2, and the error lists the kits this Geneseed ships. `none` is reserved and can never name a kit. The flag's row is in the [CLI reference](../reference/cli.md), under `build`.
+
+A build does exactly what its flags say. A plain `build` without `--kits` therefore turns off a kit the install has on. Before it does, it warns: `this install has kit <k>; this build turns it off — pass --kits <k> to keep it`.
+
+The setup wizard asks one yes/no question per kit, each defaulting to whether the install has that kit on. It asks them only when at least one kit exists.
+
+### What an install records
+
+An install with a kit on records it in its instructions file, under the skill section: `Active kits: spring-boot`. The line is written only when at least one kit is on. A missing line means no kits, so an install built before kits existed reads as having none.
+
+`geneseed rebuild-all`, `geneseed update` and `geneseed migrate` read the line back and rebuild with the same kits. `geneseed diff` and the web console read it too, so they compare against or rebuild that same set. `geneseed validate` does not read it: pass `--kits` to dry-run a kit build. A plain `build` does not read it; it only warns, as above. If the line names a kit this Geneseed no longer ships, the rebuild drops that kit with a notice and keeps the others. It never fails `rebuild-all`. A retired kit name is never reused for a new kit.
+
+`geneseed status` shows `kits: spring-boot` on the install's row, and `status --json` carries the same list.
+
+In the web console, **Installs → Kits** (`#/installs/kits`) lists every install (disabled ones read-only) with one switch per kit. Toggling stages the set; **Apply** asks for confirmation, then rebuilds that one install with exactly that set as a console job (replace, not replay). Files you edited in a kit that is now off are kept, and the row names them so you can delete them by hand. The top-level **Kits** page (`#/kits`) lists the kits; a kit's page (`#/kits/<kit>`) shows its rules, banned APIs and upstream credits with the same per-install switch, and the Library tags each member skill or agent with a `kit:` badge.
+
+### What a kit adds to an install
+
+- **Its skills and agents.** They are written like any core skill or agent. The members of a kit that is off are not written at all.
+- **A Kits block in the instructions file**, after the doctrine layer. It holds each active kit's rules, the same text at either [footprint](footprint.md).
+- **Its catalogue rows**, as the last rows of the skills table and of the agents table, only where the host does not list that kind natively. The plain bundle (`--emit files`) gets both, Bob gets the agent rows (it lists skills natively), and Claude Code, OpenClaude and OpenCode get none: their instructions file keeps its pointer.
+
+`--exclude-skills` still applies: it can drop one kit skill while the rest of the kit stays on, and the exclusion wins. A kit's links to its own skills do not stop that, but a kit file's link to a core skill still protects that core skill from `--exclude-skills`, as any link from the harness does. Kit agents cannot be left out one by one. See [Exclusions](exclusions.md).
+
+### Turning a kit off
+
+Rebuild with `--kits none`, or with a list that leaves the kit out. The kit's files are removed from the install, its block and catalogue rows go, and the `Active kits:` line goes when no kit is left.
+
+A kit file you edited is kept, as with any file Geneseed wrote and you changed. `geneseed status` names it on a row of its own, `kept from inactive kit <kit>: <files>`, and `status --json` lists it under `keptKitFiles`. Delete it by hand if you no longer want it.
+
+### Kits are not doctrine packs
+
+A [doctrine pack](rules.md) is part of the constitution. Kits are not:
+
+- A kit's rules are plain text. They have no rule ids, cannot be excluded one at a time with `--exclude-rules`, and have no row in the hook ledger. No hook gate enforces them.
+- A kit is not a pack. A missing `Active packs:` line reads as every pack, but a missing `Active kits:` line reads as no kits, so an old install never turns a kit on by accident.
+
+### What a kit costs
+
+- **Hooks:** nothing. The hook binary does not read kits, so a kit adds no time to a tool call.
+- **The instructions file:** the Kits block. Each kit has its own word budget for its rules, set in its manifest and checked by `doctor`, so a kit never eats into the core ceiling.
+- **The skill listing:** one line per kit skill, every session, while the kit is on. That is the same price as a core skill.
+
+The cost of authoring one, file by file, is in [Extending](../extending.md#3bis--adding-a-kit).

package/docs/concepts/loop-branch.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 23
+order: 24
 title: "LOOP.md, trailers and the loop branch"
 description: "The loop's state file, the trailers on every commit, the loop/* branch exemption, and the console's view."
 ---

package/docs/concepts/loop-bricks.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 18
+order: 19
 title: "Bricks and their origins"
 description: "What a brick is, how templates wire bricks, and how project and global bricks override shipped ones."
 ---

package/docs/concepts/loop-contracts.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 22
+order: 23
 title: "Contracts and ignored deletions"
 description: "The contract globs that always raise risk, the deletions a template ignores, and the glob dialect."
 ---

package/docs/concepts/loop-gates.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 21
+order: 22
 title: "Human gates"
 description: "Bricks that hold for a person whatever the score, and how ok, no and amend answer them."
 ---

package/docs/concepts/loop-notes.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 19
+order: 20
 title: "Notes and rules"
 description: "What survives an iteration in LOOP.md's notes, and the rules a template hands every brick."
 ---

package/docs/concepts/loop-risk.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 20
+order: 21
 title: "Risk, trust and validation levels"
 description: "How a loop scores a change, the trust presets, and the silent, soft and blocking levels."
 ---

package/docs/concepts/loop-templates.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 17
+order: 18
 title: "Loop templates"
 description: "Every shipped loop template, what it is for, and the notes that matter when you pick one."
 ---

package/docs/concepts/loops.md

@@ -2,7 +2,7 @@
 group: concepts
 kind: "concept"
 section: "Loops"
-order: 16
+order: 17
 title: "Loops"
 link: {"hash":"#/docs/loop-actions","label":"The geneseed loop actions →"}
 description: "What a loop is, the ring of bricks it runs, and how it differs from foreman mode."

package/docs/concepts/lsp.md

@@ -1,6 +1,6 @@
 ---
 group: concepts
-order: 13
+order: 14
 title: "Code intelligence (LSP, OpenCode)"
 kind: "concept"
 section: "Configuration"

package/docs/concepts/skills.md

@@ -41,7 +41,7 @@ The full list, with each description, is in the catalog.
 
 ### Skills improve themselves
 
-Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent proposes the exact edit to that skill and applies it only with your assent. Most runs end with nothing to change.
+Every skill ends with one beat of reflection: if a step misled or a step was missing, the agent writes the exact correction, with your assent, into that skill's notes file, `notebook/skill-notes/<name>.md`, and reads those notes the next time the skill runs. It never edits the installed skill itself: that file is rendered from `src/`, a rebuild would overwrite the edit, and `doctor` would report it as drift. Agents work the same way through `notebook/agent-notes/`. Each note is one line that carries its evidence, `- [skill|general] <correction> — seen: <what happened, against what was expected> (<date>)`: `seen:` is what you judge the correction by before folding it in, and `general` marks one that belongs in a law, doctrine or memory rather than in that one skill. `geneseed diff` lists the notes so you can fold them back into `src/`. Most runs end with nothing to change.
 
 ### Old names keep working
 

package/docs/extending.md

@@ -389,10 +389,31 @@ emit leaves the prior install intact.
    never fires. Hand-run, spends model calls on your own login, not part of the suite.
 
 **A vendored skill folder** (`src/skills/<name>/SKILL.md`) is a different shape: add it to
-`VENDORED_SKILL_DIRS` (`js/hosts/native.mjs:37` — the literal is frozen in
-`tests/unit/authoring_gates.test.mjs:312`), write a `VENDOR.md` carrying `**Upstream:**`,
-`**Commit:**` (a 40-hex commit, never a moving branch) and `**License:**`, add the registry row —
-and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the top level.
+`VENDORED_SKILL_DIRS` (`js/hosts/native.mjs:48` — the literal is frozen in
+`tests/unit/authoring_gates.test.mjs:421`), add a `src/upstreams.json` entry (`repo`, `commit` —
+a 40-hex commit, never a moving branch — `author`, `license`, and `licenseFile`, a path under
+`src/` or `null`; an optional `"frozen": true` marks text left at its pin on purpose: the weekly drift job skips it, `creditProblems` still validates it), write a `VENDOR.md` carrying `**Upstream key:** <that key>` and a
+`{{CREDIT:<key>:<upstream path>}}` line, which renders the attribution into every install (the
+folder ships its upstream's own LICENSE, so it gets no `LICENSE-<key>.txt` copy; a first-party
+folder writes `**Upstream:** this repository` and a `**License:**` instead, and has no entry),
+add the registry row — and **skip steps 2, 4, 6, 7**: the flat-spec globs only see `*.md` at the
+top level. The doctor (`vendorPinProblems`, `creditProblems`) refuses a key with no entry, an
+entry nothing credits, an entry missing `repo`/`author`/`license`, a bad commit, and a licence
+file that is missing or outside `src/`.
+
+**Porting a flat skill or an agent from another repository** is steps 1–9 plus a
+`{{CREDIT:}}` token. Only an upstream not yet in `src/upstreams.json` needs a new entry, as
+above, with the upstream's licence text at `src/licenses/<key>.txt` as its `licenseFile` (never
+`null` here; two keys from one repo may share a file); a port from a listed upstream reuses its
+key. Put
+`{{CREDIT:<key>:<upstream path>}}` on its own line under the purpose blockquote; the render turns
+it into `` *Adapted from [repo](url) (`path`) by author — license, modified.* ``, and for a skill the
+emit adds `skills/<name>/LICENSE-<key>.txt` (an agent is one file, so it gets the line only). A
+skill drawn from two upstreams carries two tokens, as `debug` does. A new entry also needs a
+`` `<key>` `` bullet under README `## 🙏 Credits` — `proseMirrorProblems` gates that list both
+ways. Do it in
+the commit that brings the text in: no gate can find an unmarked port afterwards, because nothing
+distinguishes it from first-party text.
 
 Two traps worth knowing before you write the spec:
 
@@ -435,6 +456,88 @@ because a code span is not a link. Measured on 2026-10-08, with the neutral them
 footprint: debug's SKILL.md went from 1.64k to 1.18k tokens and rule's from 2.33k to 1.83k
 (chars/4).
 
+---
+
+## 3bis — Adding a KIT
+
+A kit is an opt-in bundle of skills, agents and rules for one stack, off unless an install names
+it with `--kits` ([Kits](concepts/kits.md)). Nothing in the mechanism is specific to one stack.
+
+**The manifest is the sole writer of membership.** `src/kits/<kit>.json`:
+
+```json
+{
+  "description": "One line: what the kit is for.",
+  "skills": ["<skill>"],
+  "agents": ["<agent>"],
+  "rules": "kits/<kit>/rules.md",
+  "rulesWordBudget": 300,
+  "catalogue": {
+    "skills": ["| [<skill>]({{DIR_SKILLS}}/<skill>.md) | when to reach for it |"],
+    "agents": ["| [<agent>]({{DIR_AGENTS}}/<agent>.md) | when to delegate to it |"]
+  }
+}
+```
+
+- `banned` (optional): strings no member file may contain, in the skill and agent specs, a skill's side files (flat, `skills/<m>/*.md`) and the kit's `rules.md`; `doctor` refuses each hit, naming file and line. A line carrying `<!-- banned: ok -->` is exempt (a rule that names the construct in order to forbid it).
+
+`loadKits` (`js/build/source.mjs`) reads every `src/kits/*.json`; `src/kits/` itself never ships
+(`NOT_BUNDLED` in `js/build/render.mjs`). The members stay **flat** in `src/skills/` and
+`src/agents/`, never in a `src/kits/<kit>/skills/` folder: every host's native layer accepts only
+`skills/<x>.md` and `agents/<x>.md` and would drop a nested file silently, and every check that
+enumerates skills would miss it. `src/kits/<kit>/` holds only `rules.md`.
+
+**Per-kit cost:**
+
+1. **Each member is a skill or an agent first.** §3 applies to it, with these differences:
+   - **No row in `AGENT.md.tmpl`.** Its catalogue row, a table row of the same shape, goes in
+     the manifest's `catalogue`. With the kit on, the render inserts the skill rows as the last
+     rows of the §4 skills table (before the folder-skills list) and the agent rows at the end of
+     the §3 agents table, on a host that does not catalogue that kind natively.
+     `countTableProblems` checks the template's links and the kits' catalogue rows together
+     against the flat specs, and `kitProblems` refuses a catalogue row for a non-member.
+   - **No README badge and no `SHIPPED.md` count.** Core counts exclude kit members, so
+     skip §3 steps 6 and 7.
+   - **Still** a `DESC_<NAME>` in every theme, a `SKILL_CLASS` entry for a skill (the members are
+     flat, so `srcStems('skills')` sees them), and a `registry.json` row.
+   - **An agent's web glyph, required:** an entry in `GLYPHS`
+     (`web/src/components/AgentGlyph.jsx`), then rebuild and commit `web/dist`.
+     `web/src/__tests__/agentGlyph.test.jsx` gates every `src/agents/*.md`, kit members included.
+2. **The manifest**, above.
+3. **`src/kits/<kit>/rules.md`**, the kit's rules. The render puts it in the carrier's Kits block,
+   after §2, only while the kit is on. It is plain text, not doctrine machinery: no rule ids, no
+   per-rule exclusion, no hook-ledger row, and the same text at either footprint.
+   `doctor` holds it to the manifest's `rulesWordBudget` (300 when unset).
+4. **Membership and links.** `doctor` (`kitProblems`) refuses a member listed in two kits, a
+   core skill listed in a kit, a member with no file or no registry row, a core file that links
+   to a kit member (it would dangle in an install without the kit), and a kit file that links to
+   another kit's member. Links run kit → core only. A kit's links to its own members do not
+   protect them from `--exclude-skills`; its link to a core skill still protects that skill.
+5. **The setup wizard.** It asks one yes/no per kit, and only when at least one kit exists. Each
+   shipped kit therefore adds one answer line to the stdin strings in `tests/unit/wizard.test.mjs`,
+   and the `wizard-no-kit` job holds that the questions are skipped on a tree with no kit.
+6. **Golden cells**: the matrix (`tests/helpers/matrix/emit.*.json`) carries kit on for `claude` and
+   `opencode`, the kit-off baseline (`kits: []`, spelled `--kits none`), and three deletion cells
+   (kit on to off). One deletion cell sets `edit` (a map of sandbox path to appended text) so a member
+   is the user's own before the kit goes off, and `sovereign` excuses it: the prune keeps it (R6).
+
+**What a kit costs an install** — what to weigh before adding one:
+
+- **Hooks: zero.** The hook binary never reads a kit, so a kit adds no time to any tool call.
+- **The carrier:** the Kits block. Each kit is measured against its own
+  `rulesWordBudget`, not the core carrier ceiling, which stays measured on core alone.
+- **The skill listing:** one description per kit skill, every session, while the kit is on.
+- **An install without the kit: nothing.** Its members are not written, and a default build
+  stays byte-identical, with no `Active kits:` line.
+
+**Retiring a kit** puts its id in `RETIRED_KIT_IDS` (`js/build/source.mjs`), with the reason
+beside it. An install whose `Active kits:` line names it drops it wherever that line is read back
+(`rebuild-all`, `update`, `migrate`, `diff`, the web console), without failing; `rebuild-all`, `update` and `migrate` print a notice. `doctor` refuses a retired id on a new kit. `none` is
+already there: `--kits none` means no kits.
+
+**Kits are not packs.** Never add a kit to `PACK_ORDER`. A missing `Active packs:` line reads as
+every pack, so a kit there would switch itself on in every install built before it existed.
+
 
 ---
 

package/docs/guides/install-scripted.md

@@ -12,7 +12,7 @@ description: "The build command to run in a script, a CI job, or a shell with no
 geneseed build --emit opencode-global --theme neutral
 ```
 
-`geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md).
+`geneseed build` takes the same flags as the generator `geneseed-build`. `--emit` picks the host and its scope: `files`, `opencode`, `opencode-global`, `claude`, `claude-global`, `bob`, `bob-global`, `openclaude` or `openclaude-global`. A `-global` emit writes into the tool's own config directory. A project emit writes into the repo you name with `--out <repo> --root <repo>`. All the other flags (`--theme`, `--footprint`, `--posture`, `--mode`, `--trust`, `--doctrines`, `--exclude-rules`) are covered in [Choose your setup](choose-your-setup.md) and the two pages after it. `--exclude-skills` leaves skills you never use out of the install; see [Exclusions](../concepts/exclusions.md). `--kits <kit>` switches on an opt-in kit, and `--kits none` switches every kit off; see [Kits](../concepts/kits.md).
 
 To test a build before writing anything, use `geneseed validate` with the same flags. See [Verify](verify.md).
 

package/docs/guides/run-anywhere.md

@@ -8,7 +8,7 @@ description: "Put the geneseed command on your PATH from a clone."
 ---
 **Installed from npm? You have nothing to do.** `npm install -g geneseed` already puts `geneseed`, `geneseed-build` and `geneseed-hook` on your `PATH`.
 
-From a clone, you call the launcher inside the clone: `./geneseed` (Windows: `.\geneseed.cmd`). To type plain `geneseed` from any folder, link it.
+From a clone, you call the launcher inside the clone: `./geneseed` (Windows: `.\geneseed.cmd`). To type plain `geneseed` from any folder, link it. On macOS and Linux, `./install` does this for you when `geneseed` is not found yet.
 
 ## macOS and Linux
 
@@ -17,7 +17,7 @@ From a clone, you call the launcher inside the clone: `./geneseed` (Windows: `.\
 ./geneseed link /usr/local/bin     # or another bin folder (may ask for sudo)
 ```
 
-`link` writes a small shell launcher that runs this clone by its absolute path. It also tells you whether the target folder is on your `PATH`, and if it is not, the one line to add to your shell profile. Then:
+`link` writes a small shell launcher that runs this clone by its absolute path. If the target folder is not on your `PATH` (macOS zsh does not search `~/.local/bin`), it offers to add it to your shell's startup file: `~/.zshrc` for zsh, `~/.bashrc` for bash on Linux, `~/.bash_profile` for bash on macOS. It appends one marked block, never twice, and `geneseed unlink` removes it. Outside a terminal, or for another shell, it prints the line to add instead. Open a new terminal, then:
 
 ```
 geneseed            # the web console (or the command list), from any folder

package/docs/guides/upgrade.md

@@ -46,7 +46,7 @@ A rebuild only replaces files the install's manifest says Geneseed owns. It leav
 
 ## Local edits, and the improvements file
 
-The agent can refine its own deployed agent and skill files as it works, and so can you. A rebuild would overwrite those edits, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
+The agent records what it learns about a skill or agent in notes under `notebook/skill-notes/` and `notebook/agent-notes/`, which rebuilds never touch. Edits made to the deployed agent and skill files themselves, by you or by an older harness, are another matter: a rebuild would overwrite those, so **setup, re-theme and upgrade export them first**. When the files they are about to overwrite differ from a fresh render, the differences are written to a markdown **improvements file** in `improvements/`, inside the install's own folder (for the OpenCode global install, `~/.config/opencode/improvements/`). The manifest does not list that folder, so rebuilds never overwrite it and uninstall never removes it.
 
 A rebuild also refuses to overwrite a file you edited. The manifest records a fingerprint of every file Geneseed wrote; when a file no longer matches it, the rebuild leaves it alone and prints `kept your edited <file> — delete it to get Geneseed's copy back`. From then on the file is yours and later rebuilds skip it. A file the new version no longer ships is kept the same way, with `(no longer shipped)`. Line-ending changes from a git checkout do not count as edits. Installs made before fingerprints existed are overwritten as before.
 
@@ -58,7 +58,7 @@ geneseed diff --full                   # with line-level diffs
 geneseed diff --out improvements.md    # write the improvements file
 ```
 
-`diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
+`diff` compares the global OpenCode install by default. Pass `--target <config dir>` to compare another install. A file you replaced with a link to your own copy (a skill folder junctioned or symlinked elsewhere, say) is listed as `linked`: Geneseed never writes through a link, so it is yours and not drift, and it stays out of the improvements file. `diff` also lists every non-empty self-improvement note, and `--out` copies them into the improvements file; the upgrade export does not fire on notes alone, since a rebuild cannot lose them. The improvements file is self-contained. To make the changes permanent, hand it to an agent in a Geneseed clone and ask it to fold them back into `src/`. Then they survive every future build. The web console's **Changes** page exports the same file.
 
 ## Moving from a clone to npm
 

package/docs/reference/glossary.md

@@ -28,6 +28,7 @@ Every word Geneseed uses that you would not find in a general programming glossa
 | Posture | — | the relationship register the agent works in (peer, mentor, expert, assistant, artisan) | pairing style |
 | Mode | — | how work gets executed — direct (the agent works every task itself) or foreman (substantial tasks spawn an isolated pipeline) | solo vs. delegating to a sub-team |
 | Footprint | — | how much of the Rules loads inline each turn (full vs lean) | eager vs. lazy loading |
+| Kit | — | an opt-in bundle of skills, agents and rules for one stack, switched on per install with `--kits`; not a doctrine pack | an optional dependency group (`pkg[extra]`) |
 | Loop | — | a requirement worked as small, validated, committed iterations on their own branch, driven by `geneseed loop` | a state machine over a ticket's steps |
 | Iteration | — | one cycle of a loop back to its head; closes into its own commit | one sprint-of-one through a checklist |
 | Brick | — | one node of a loop graph: a prompt for one agent or skill, reporting one of a declared set of outcomes | a step in a runbook |

package/docs/reference/troubleshoot-install.md

@@ -97,7 +97,7 @@ reports `version "21` or higher.
 .\geneseed.cmd link
 ```
 
-On Windows, `link` writes to `%LOCALAPPDATA%\Geneseed\bin` and adds it to your user PATH — only **new** terminals see it, so close and reopen yours.
+On macOS and Linux, `link` offers to add `~/.local/bin` to your shell's startup file when it is not on your PATH; accept, then open a **new** terminal. On Windows, `link` writes to `%LOCALAPPDATA%\Geneseed\bin` and adds it to your user PATH — only **new** terminals see it, so close and reopen yours.
 
 **Confirm.**