peaks-loop 4.0.0-beta.7 → 4.0.0-beta.9

package/CHANGELOG.md

@@ -2,6 +2,141 @@
 
 ## [Unreleased]
 
+## 4.0.0-beta.9 — 2026-07-15
+
+### Fixed — `npm install peaks-loop` runtime path layout
+
+`4.0.0-beta.8` shipped a tarball where `bin/peaks.js` imported
+`'../dist/src/cli/index.js'`, but tsc actually emitted the runtime
+files at `dist/cli/index.js` (rootDir walked past `src/` because of
+cross-folder imports like `src/services/hooks/output.ts → ../../cli/`).
+Downstream `npm i -g peaks-loop` then `peaks -v` failed with
+`ERR_MODULE_NOT_FOUND: .../dist/src/cli/index.js`. The 4 audit/business
+templates also failed to enter the tarball because `package.json#files[]`
+whitelisted `dist/src/**/*.js` / `.d.ts` but never `.md`.
+
+This release:
+
+- `bin/peaks.js` import: `'../dist/src/cli/index.js'` → `'../dist/cli/index.js'`.
+- `scripts/copy-templates.mjs` dest: `dist/src/services/...` →
+  `dist/services/...` so the bundled templates land where the runtime
+  `import.meta.url` resolver expects them.
+- `package.json#files[]`: prefixes shifted from `dist/src/` to `dist/`,
+  plus a new `dist/**/*.md` entry so the 4 templates bundled by
+  `copy-templates.mjs` actually ship.
+- `tsconfig.build.json` (introduced in beta.8) confirmed correct — it
+  is the build-time emit that controls the dist tree shape.
+
+End-to-end smoke after the fix (local):
+
+```
+$ npm pack                                  # 30 MB tarball
+$ npm install ./peaks-loop-4.0.0-beta.9.tgz --prefix /tmp/test
+$ peaks --version                           # → "4.0.0-beta.9"
+$ peaks workspace init --project /tmp/fresh  # → templatesBooted: 5
+```
+
+`.peaks/project-scan/{project-scan.md, business-knowledge.md,
+security-template.md, perf-template.md, audit-output-schema.md}`
+all present after a fresh workspace init.
+
+### Notes
+
+- 4.0.0-beta.8 is left in place on npm as a known-broken release.
+  Consumers who already pinned `peaks-loop@4.0.0-beta.8` should bump
+  to `4.0.0-beta.9`.
+- Beta.9 contains everything beta.8 advertised plus the path fix.
+
+## 4.0.0-beta.8 — 2026-07-15
+
+### Added — project-scan bootstrap (slice 2026-07-15)
+
+- **`peaks project context` writes `.peaks/project-scan/project-scan.md`**
+  alongside `.peaks/PROJECT.md`. The project-scan.md file is the new
+  canonical home for project archetype + libraryVersions + tech stack
+  (project-scoped, git-tracked, survives session rotation). The old
+  `.peaks/_runtime/<sessionId>/rd/project-scan.md` path is fully
+  migrated across SKILL.md / references / peaks-rd SKILL.md /
+  peaks-ui SKILL.md (14 occurrences in 8 files).
+- **`peaks workspace init` triggers `bootstrapProjectScan`** on its
+  main path. Idempotent: existing `schemaVersion: 1` files are
+  preserved unless `--force`. New CLI flags:
+  - `--no-project-scan-bootstrap` — opt out of the bootstrap call.
+  - `--force-project-scan-templates` — overwrite the 4 bundled
+    audit/business templates (default: skip if present).
+- **5-template boot** — every `peaks workspace init` materialises
+  `.peaks/project-scan/{project-scan.md, business-knowledge.md,
+  security-template.md, perf-template.md, audit-output-schema.md}`.
+  The 4 audit/business templates are bundled at
+  `src/services/workspace/templates/project-scan/*.md` and copied
+  verbatim by `scripts/copy-templates.mjs` (post-`tsc` step; tsc
+  does not emit `.md` files).
+- **`scripts/copy-templates.mjs`** — mirrors bundled `.md` templates
+  into `dist/`. Wired into `package.json#scripts.build` after `tsc`.
+  Required to keep `import.meta.url` template reads working for
+  downstream `npm install peaks-loop` consumers.
+- **`tests/unit/workspace/templates/template-integrity.test.ts`**
+  (5 cases) — byte-equality guard between bundled and canonical
+  templates; fails CI on drift.
+- **`tests/unit/services/prd/project-scan-bootstrap-service.test.ts`**
+  (13 cases) — 0-1 path, existing-project path, monorepo variants,
+  idempotency, force overrides, dual-write.
+- **`tests/unit/workspace/init-hooks-project-scan.test.ts`**
+  (4 cases) — `peaks workspace init` integration with all 3 CLI flag
+  combinations.
+
+### Fixed — monorepo 0-1 misjudgement + scanArchetype fall-through
+
+Real-world smoke against `C:\Users\smallMark\Desktop\peaksclaw\ice-cola`
+(pnpm-workspace monorepo with `packages/{server,client,admin,hermes-agent}`)
+exposed two follow-on bugs that the unit suite missed:
+
+- **0-1 detection now considers monorepo sentinels.**
+  `bootstrapProjectScan.isZeroToOneProject` previously only checked
+  `<root>/src/`, silently mis-classifying pnpm-workspace projects as
+  0-1 (the source lives at `packages/<pkg>/src/`). New sentinels:
+  `pnpm-workspace.yaml` / `turbo.json` / `nx.json` + the
+  `package.json#workspaces` field. Source-root candidates extended
+  to `packages/` / `apps/` / `libs/` / `services/` / `workspaces/`.
+- **`scanArchetype` hoists `hasMonorepoConfig` above the `hasBackend`
+  check.** A monorepo with a backend sub-package (`packages/server`)
+  used to fall through to `legacy-fullstack` because `hasBackend`
+  included `backendDirsPresent.length > 0`. New behaviour: any monorepo
+  resolves to `frontend-monorepo` (no backend pkg) or
+  `fullstack-monorepo` (with backend pkg).
+- **`ProjectArchetype` union gains `'fullstack-monorepo'`.**
+  Previously the union was 5 values; now 6. `ArchetypeService` and
+  `peaks-code` consumers updated accordingly.
+
+### Changed
+
+- `src/services/memory/project-context-service.ts` — `generateProjectContext`
+  is now `async` and calls `bootstrapProjectScan` after writing
+  `PROJECT.md`. The companion `peaks skill presence:clear` was missing
+  an `await`; fixed in `src/cli/commands/core/skill-command.ts`.
+- `src/cli/commands/workspace/init-command.ts` — adds
+  `--no-project-scan-bootstrap` and `--force-project-scan-templates`;
+  surfaces `projectScan` envelope field on the init response.
+
+### Verification
+
+- vitest: 22/22 pass across 3 slice-owned test files.
+- tsc: 0 errors in slice-owned `src/` files.
+- CLI: `./bin/peaks.js workspace init --project <tmp>` writes 5 files
+  in `templatesBooted:5, durationMs:23`; `--no-project-scan-bootstrap`
+  correctly skips; `--force-project-scan-templates` correctly
+  overrides user sediment.
+- Ice-cola: `peaks project context --project .` produces
+  `archetype: fullstack-monorepo` with 18 real library versions
+  (Docusaurus 3.9.2 / Camofox / @easyops-cn / etc.).
+
+### Notes
+
+- pre-existing `FILE_SIZE_VIOLATION` on
+  `src/services/standards/project-standards-service.ts` (837 lines,
+  in-flight `.claude/rules/` → `.peaks/standards/` migration) is out
+  of slice scope.
+
 ## 4.0.0-beta.7 — 2026-07-09
 
 ### Added — zcode adapter (9th IDE) + runtime model detection

package/README-en.md

@@ -1,116 +1,227 @@
-# Peaks Loop
+<div align="center">
 
-**English** | [简体中文](./README.md)
+# peaks-loop
 
-[![npm](https://img.shields.io/npm/v/peaks-loop?style=flat-square&logo=npm)](https://www.npmjs.com/package/peaks-loop)
-[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
-[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=flat-square&logo=github)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+### You talk. It runs the entire engineering chain for you — beyond just code, twice-run flows sediment into local tactics.
+
+[![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
+[![tests](https://img.shields.io/badge/tests-5%2C439%20passed-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
+[![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
+
+**English** · [简体中文](./README.md)
+
+</div>
 
 <p align="center">
-  <a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.mp4">
-    <img src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/out/en-closing-960.png" alt="peaks-loop demo (click to play)" width="100%" style="border-radius: 12px; box-shadow: 0 12px 40px rgba(0,0,0,0.55);">
-  </a>
+  <img
+    src="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.gif"
+    alt="peaks-loop 30-second demo (first 18s · install + slash command + 5 domains + sediment into bee)"
+    width="92%"
+    style="border-radius: 14px; box-shadow: 0 12px 40px rgba(0,0,0,0.55); display: block;"
+  />
   <br>
-  <sub>👆 click the image to play the 60s demo</sub>
+  <sub>👆 18s looping GIF (<a href="https://raw.githubusercontent.com/SquabbyZ/peaks-loop/main/examples/video-demo/preview/peaks-loop-demo-en.mp4">full 30s mp4 download</a> · 13MB · 480p)</sub>
 </p>
 
+---
+
 ## What it is
 
-### Loop engineering, engineered
+peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool — what sediments from the runs you do is **not** a procedure, it's a set of **Loop Engineering** method assets that are karpathy-engineered at the rule level and darwin-verified at the change level. The **Loop engineering, engineered** crystallization design lives at [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md).
+
+| Asset layer | Role | One-liner |
+| --- | --- | --- |
+| **Loop Engineering Asset** | Method system, first-class | Answers "why this loop exists, when it fires, what counts as success, how it improves" |
+| **Bee Asset** | Executable body, first-class | The runnable body of a Loop Engineering Asset — every bee in the swarm |
+| **Workflow Trace** | Evidence, **NOT** the durable product | Immutable per-run record; feeds crystallization + evaluation, not the user-facing asset |
+| **Evolution Evaluation** | Anti-drift gate, mandatory | Every improvement needs an independent-context scorer + a regression skeptic; keep only if it passes, otherwise revert |
 
-**peaks-loop is your Loop Engineering crystallization system — not a workflow tool.** It crystallizes Loop Engineering assets out of real, completed work, and only evolves them through verified improvements. You operate the system through natural language and choices; every structured action is performed by the LLM on your behalf.
+- **Engineering principles = karpathy-style · Verify every improvement = darwin-style** — both are required, not optional. Drop karpathy and your principles are never written down; drop darwin and your changes are never verified. They are co-equal layers, not sequential steps.
+- `/peaks-code` is the **code-domain** long-task Loop Engineering orchestrator, not a general orchestrator; non-code lanes (`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`) ship as independent `peaks-*` bees, **not** as subclasses of `peaks-code`.
+- Twice-clean runs sediment into your local tactic pool (bee); broken runs come back for you to redefine. Your few bees grow with your taste.
 
-The product is governed by a four-layer asset model and a karpathy × darwin dual-discipline, both of which are non-negotiable:
+---
+
+## Up and running in 30 seconds
+
+```bash
+npm i -g peaks-loop
+```
 
-- **Four-layer asset model**: Loop Engineering Asset (the method system, first-class) + Bee Asset (the executable body, first-class) + Workflow Trace (execution trace — evidence only, never the durable asset) + Evolution Evaluation (anti-drift gate, mandatory for any change).
-- **karpathy × darwin dual discipline**: karpathy engineers every rule (failure modes + imperative→declarative rewrite + self-check + out-of-scope); darwin verifies every improvement (single object + single dimension + independent-context evaluator + ratchet). The two layers are co-equal partners — neither is a subset of the other. See `.peaks/standards/loop-engineering-guidelines.md` and the upstream references `multica-ai/andrej-karpathy-skills` and `alchaincyf/darwin-skill`.
-- **Post-run crystallization**: `loop_release` and `bee_release` are only written after a real task completes; pre-run is always scratch. Four triggers are supported, with `user_explicit` ranked highest.
-- **Human-NL-Choice-Only**: you speak or pick; the LLM runs the CLI. Hand-authoring JSON / manifests / form fields is forbidden.
+Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop — a plain sentence won't always route here):
 
-### peaks-code is the code-domain entry — and only the code-domain entry
+```
+/peaks-code walk me through this codebase
+```
 
-`peaks-code` is the code-domain long-task loop engineering orchestrator — it runs the long chain (PRD, RD, QA, UI, SC, TXT) and is the role you'll talk to most. It is **not a general-purpose orchestrator** — research, content, product, and other domains are independent `peaks-*` skills that reuse the same Loop Engineering guidelines. See the Loop Engineering design `docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md` §0.4 + RL-8, and the sediment design `docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`.
+The rest is peaks-loop's job — it picks the domain from the slash, routes to the right orchestrator, splits the work gate by gate, **stops where it breaks**, never hands you a half-finished slice.
 
-Summon them, they handle the work. Stand them down when it's done. **No skipped steps. No half-finished hand-offs.** No new AI CLI to learn — it sits on top of Claude Code, Codex, or Copilot you already run.
+Other slash commands you'll reach for:
 
-### peaks-solo is the dispatcher (new in 4.0.0-beta.5)
+```
+/peaks-content                 draft and publish today's post
+/peaks-doctor                  run a health check on this repo
+/peaks-issue-fix-orchestrator  fix the next 30 open issues upstream
+/peaks-sop                     author the team's release SOP
+/peaks-solo                    I'll do this again — sediment it as a local tactic
+/peaks-solo                    run it like last time
+```
 
-If you **don't know which peaks-* skill to use**, just type `/peaks-solo` and describe your task in natural language. It triages for you: dispatches to a matching leaf, or self-plans with deep-search / WebSearch / Bash / Edit markdown if no leaf fits, then asks whether to sediment the result. `/peaks-code` / `/peaks-content` / `/peaks-doctor` etc. continue to work — **zero breaking changes**.
+<sub>📦 Adapters for other AI coding tools are coming — contributions welcome → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).</sub>
 
-**Every gate has a hard exit.** Audit fails = stop. QA fails = stop. Any gate fails = full stop. You don't chase it, you don't patch it. You decide, it runs the next gate.
+No CLI to memorize. No manifest to hand-author. No second terminal to open. **Send the slash, the rest is on it.**
 
-#### Gates aren't decoration — 5,439 tests passed · 19 skipped · 0 failed
+---
 
-Every line of code goes through our own gates. The test suite — 5,420 cases — actually blocks. Gates aren't written for users to admire; they're written for us to obey.
+## What it does for you
 
-#### One person built this, an engineer's taste:
+Code, content, project health, issue sweeps, custom workflows — **4.x ships five first-class domains**, each with its own orchestrator. Same discipline on every lane: "gate fails = stop, run the next gate".
 
-- **Geek ethos.**
-- **Natural language only — no CLI surface for the user.**
-- **Tests and gates that actually block, not decorate.**
-- **Strict with self, lenient with users — our own code goes through our own gates; users say whatever they want, the system catches it.**
-- **AI fluency floor is flat — no prompt-engineering chops, no CLI muscle memory; you talk like a person.**
+| Domain | Send this slash command | It will… |
+| --- | --- | --- |
+| 💻 **Code (code-domain) only** | `/peaks-code build this feature` | PRD → RD → code → QA → UI → slice, ready for your sign-off |
+| 💻 **Code (code-domain) only** | `/peaks-code fix this bug` | reproduce → patch → review → tests, ship same day |
+| 📝 **Content** | `/peaks-content draft and publish this post` | draft → edit → tone check → publish → archive, no skipped steps |
+| 🩺 **Project health** | `/peaks-doctor run a health check on this repo` | red-line audit + L3 doctor + convert to OpenSpec, stops where it breaks |
+| 🐛 **Issue sweep** | `/peaks-issue-fix-orchestrator fix the next 30 open issues upstream` | survey → classify → reference PRs → fix + commit + PR draft |
+| 📋 **Custom workflow** | `/peaks-sop author the team's release SOP` | describe in plain language → auto-generate + validate + register |
+| 🔁 **Replay** | `/peaks-solo run it like last time` | pull up your sedimented tactic, replay it |
+| 🆕 **Onboard** | `/peaks-code this is a new repo, walk me through it` | map structure, flag risks, hand you a learning order |
+| 🧠 **Sediment** | `/peaks-solo I'll do this again — save it` | ground it locally as a reusable tactic |
 
-Those project-level red lines live in `~/.peaks/memory/`. They aren't slogans. They are red lines the toolchain enforces.
+Every lane opens with **one slash command**.
 
-## What's in the box
+---
 
-First tactician on the roster: `peaks-code`. The lead.
+## Why people pick it
 
-It runs the long chain — PRD, RD, QA, UI, SC, TXT — and it's the role you'll talk to most.
+- **Natural language is the interface.** No CLI to learn, no commands to memorize. **Use an explicit slash command (e.g. `/peaks-code xxx`)** to route to the right orchestrator; everything after the slash is plain language. The LLM runs the commands on your behalf.
+- **Gates that actually block, not decorate.** 5,439 test cases, QA gate, review sign-off — all on by default. **Audit fails = stop. QA fails = stop.**
+- **Run-once flows become local tactics (bees).** Sedimented loop engineering lands in your local `~/.peaks/` pool — twice-clean runs auto-promote to standing tactics, broken runs come back for you to redefine. **Next time, just say "run that one" and the whole playbook slots back in.** Your few tactics grow with your taste.
+- **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress, contributions welcome.
+- **You decide, it executes.** Decisions that touch your assets are yours; everything else it runs on its own. **Zero learning cost. One minute to first task.**
 
-What it does:
-- Long-task development (end-to-end requirement → PRD → implementation → QA), gate by gate, stops where it breaks
-- Fix a bug and ship the same day — fix goes through review + tests, not just out the door
-- Take on, break down, or hand off a long-running requirement — from fuzzy ask to landed code
+---
 
-One sentence from you, and a long task is done. No second terminal needed.
-Coverage, audit, hard-stop — it treats every gate the same: under the bar = not delivered, off the rail = re-run.
+## What gates ship by default
 
-It's the entry the moment you install, and the dispatcher for every role that grows in later.
-Audit, QA gate, review sign-off — on by default. You only speak to turn one off.
+| Gate | Default | What it catches |
+| --- | --- | --- |
+| Unit + integration tests | ✅ on | regressions at the code level |
+| Code audit (lint / prose / type) | ✅ on | drift in style and intent |
+| Security scan | ✅ on | secrets, SSRF, injection, dangerous IO |
+| QA review | ✅ on | task-level gate — fails loud, stops clean |
+| Review sign-off | ✅ on | nothing ships without eyes on it |
 
-More loop-engineering roles coming.
+**All gates on by default. You only speak to turn one off.**
 
-## Sediment your own loop engineering
+---
 
-When a flow has run twice, it can stay. One sentence and it's grounded into your box.
+## Status · shipping 4.x
 
-What you sediment is loop-engineering — a tactical play, not just a skill spell.
-Next time you say "run that", the whole playbook slots back in.
+| | |
+| --- | --- |
+| **Latest** | [`4.0.0-beta.7`](https://github.com/SquabbyZ/peaks-loop/releases) — 4.x GA is in the works |
+| **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test`) |
+| **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
+| **Test suite** | 5,439 passed · 19 skipped · 0 failed |
+| **IDE adapters** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder (adapters in progress — contributions welcome) |
+| **Runtime** | Node ≥ 20 |
+| **License** | MIT |
 
-It lands in a pool on your machine, scoped to you alone.
-Name it, reuse it, iterate it — your call.
-A flow that ran clean twice gets promoted.
-A flow that broke gets sent back to you to redefine.
-When a decision touches your assets, you decide.
+---
 
-The point isn't how many bees the tool ships.
-The point is your few bees keep growing with your taste — you say one line, they grow one notch.
+## Strongly recommended · compose these four
 
-## Get it running
+> **Zero learning cost.** That's the biggest reason to use them together — not just that the effect is excellent, but that **all four projects speak the same interface: natural language + a choice.** You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook.
 
-```bash
-npm i -g peaks-loop
-```
+<p align="center">
+  <a href="https://github.com/affaan-m/ECC">
+    <img src="https://img.shields.io/badge/ECC-affaan--m-6366f1?style=for-the-badge&logo=github&logoColor=white" alt="affaan-m/ECC" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/Egonex-AI/Understand-Anything">
+    <img src="https://img.shields.io/badge/Understand--Anything-Egonex--AI-22c55e?style=for-the-badge&logo=github&logoColor=white" alt="Egonex-AI/Understand-Anything" />
+  </a>
+  &nbsp;
+  <a href="https://github.com/obra/superpowers">
+    <img src="https://img.shields.io/badge/superpowers-obra-f59e0b?style=for-the-badge&logo=github&logoColor=white" alt="obra/superpowers" />
+  </a>
+</p>
+
+| Role | Project | One-liner |
+| --- | --- | --- |
+| **Sediment + gates** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← you are here | loop-engineering crystallization system; install → PRD/RD/QA/UI/SC/TXT as one chain + sediment |
+| **Tactical handbook** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | everything-claude-code: the best tactics, skills, and SOPs you can put on top of Claude Code |
+| **Code understanding** | [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | any repo, one sentence to grok it — let the LLM actually *understand* the project, not guess |
+| **Process & discipline** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review as flow disciplines, every one with a hard exit |
+
+**One sentence to use them all**: clone the three repos above, install peaks-loop, hand the rest to your LLM — it pulls what it needs, holds the gates, lands the tactics, sediments the flow.
+
+### Tribute
+
+peaks-loop's two engineering spines come straight from these projects:
+
+- [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — "engineer every rule" is etched into our method layer.
+- [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — "verify every improvement" is etched into our anti-drift gate.
+
+---
+
+## FAQ
+
+<details>
+<summary><b>How does it relate to Claude Code / Z Code?</b></summary>
 
-One sentence after install, and the squad is on the job.
+It **sits on top of** them, not in place of. peaks-loop doesn't grab your shell, your prompt, or your IDE. It runs as a first-class adapter on Claude Code and Z Code. **Adapters for other tools are in progress — contributions welcome** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).
 
-## One more thing
+</details>
 
-This repo used to be [`peaks-cli`](https://github.com/SquabbyZ/peaks-cli). It's called `peaks-loop` now.
+<details>
+<summary><b>Do I need to learn CLI commands?</b></summary>
 
-Inside the box, the skills evolved from `peaks-code` (single-role) to `peaks-code` (gate-bearing, code-domain) — both still here, both with their own lane: `peaks-code` is the older single-task flow entry, and `peaks-code` runs the end-to-end main path.
+No. You speak or pick; the LLM runs the commands. **All CLI verbs are hidden from you, open to the LLM.**
 
-The job didn't change: you say it, the engineering gates get laid out — fail where it fails, you decide.
+</details>
 
-Install this one repo and every new requirement after has a roster waiting for your call.
+<details>
+<summary><b>Do sedimented tactics stay on my machine?</b></summary>
+
+Yes. Sediment lands in a local pool, scoped to you alone. Naming, reuse, iteration — your call. Flows that broke get sent back for you to redefine.
+
+</details>
+
+<details>
+<summary><b>Will it change my code without me knowing?</b></summary>
+
+It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = nothing ships. Review fails = nothing ships. It runs; each gate stops for your eyes.
+
+</details>
+
+<details>
+<summary><b>What's new in 4.x vs 3.x?</b></summary>
+
+**The biggest shift: from "code-only tool" to multi-domain orchestration system.** 4.x no longer just writes code — it ships four new domain orchestrators: `peaks-content` (content production), `peaks-doctor` (project health), `peaks-issue-fix-orchestrator` (batch issue fix), `peaks-sop` (custom SOPs). On top of that, `peaks-solo` auto-routes to the right domain from plain language. Plus 9 IDE adapters, crystallization-system renaming, post-run crystallization, 5,439 tests passing. Full list → [`CHANGELOG.md`](./CHANGELOG.md).
+
+</details>
 
 ---
 
-MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ)
+## Links
 
 - All skills → [`skills/`](./skills/)
-- Design docs → [`docs/`](./docs/)
 - Changelog → [`CHANGELOG.md`](./CHANGELOG.md)
-- Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
+- Tribute: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
+- Recommended combo: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) · [obra/superpowers](https://github.com/obra/superpowers)
+- Sediment design → [`docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md`](./docs/superpowers/specs/2026-07-04-peaks-maker-dynamic-skill-sediment-design.md)
+- Loop Engineering crystallization design → [`docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md`](./docs/superpowers/specs/2026-07-07-peaks-loop-loop-engineering-crystallization-design.md)
+
+---
+
+<div align="center">
+
+MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · English · [简体中文](./README.md)
+
+</div>