docs: global sync before 2.0.0 — components, slash table, profiles, GSD 3.0.0, migration guide, package-install guard

ARCHITECTURE.md

@@ -9,20 +9,26 @@ Repo layout and structural principles. Command workflows live in
 claude-config/
 ├── CLAUDE.global.md       # Global coding preferences — deployed as ~/.claude/CLAUDE.md
 ├── CLAUDE.md              # Project-scope instructions (this repo only)
-├── settings.json          # Global permissions (deny / ask / allow rules)
+├── README.md / USAGE.md / ARCHITECTURE.md / CHANGELOG.md / MIGRATION.md
+├── version.txt            # Current release version
+├── .env.example           # Placeholder template for ~/.claude/.env (secrets never committed)
+├── settings.json          # Global permissions (deny / ask / allow) + autoMode classifier tiers
 ├── install.sh             # Bootstrap: Claude Code CLI + auth + submodules + link + plugins
-├── install-plugins.sh     # One-shot installer: prerequisites + all plugins
-├── link.sh                # Symlinks this repo into ~/.claude/
+├── install-plugins.sh     # One-shot installer: prerequisites + all plugins + default profile
+├── link.sh                # Symlinks this repo into ~/.claude/, sets git's global core.hooksPath
 ├── doctor.sh              # Setup diagnostic
 ├── update-all.sh          # One-command update for all components
-├── Makefile               # Unified entry point: make install / doctor / update
-├── plugins.lock.json      # Version pinning for non-marketplace dependencies
-├── hooks/                 # Session start, statusline, RTK rewrite + ctx7 + design-toolchain reminders
+├── Makefile               # Unified entry point: make install / doctor / update / test (make help)
+├── plugins.lock.json      # Version pinning for non-marketplace dependencies and vendored skills
+├── hooks/                 # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard
+├── githooks/              # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath
+├── .githooks/             # This repo's own copy of the same hooks
+├── rules/                 # Rule files deployed to ~/.claude/rules (path-scoped or always-on)
 ├── agents/                # Execution units called by skills (never invoked directly)
 ├── skills/                # Entry points invoked via /skill-name
-├── skills-external/       # Vendored skill packs (gstack submodule + installer-fetched design packs)
+├── skills-external/       # Vendored skill packs: gstack submodule, design skills, superpowers, agent-skills, MengTo scroll skills, 21st and Higgsfield packs (machine-owned copies gitignored)
 ├── templates/             # Per-project templates (CLAUDE.md, settings, memory registries, deploy runbook, gitignore)
-└── lib/                   # Shared shell libs (gitflow, profiles, commit helpers, archetypes, tests)
+└── lib/                   # Shared libs: gitflow, profiles, vendoring, effort pins, gates, archetypes, tests
 ```
 
 ## Architecture principles
@@ -30,4 +36,4 @@ claude-config/
 - `skills/` = entry points you invoke via `/skill-name`
 - `agents/` = execution units called by skills (never invoked directly by user)
 - `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually
-- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly.
+- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go.

CHANGELOG.md

@@ -2,10 +2,12 @@
 
 All notable changes to claude-config will be documented in this file.
 
-Format follows [Keep a Changelog](https://keepachangelog.com/).
+Format follows [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+Upgrading from 1.x: see [MIGRATION.md](./MIGRATION.md#upgrading-an-existing-machine-to-200).
+
 ### Added
 - **Higgsfield pack, off by default**: `make plugin` installs the `@higgsfield/cli` CLI (Step 8.6) and clones the skills of higgsfield-ai/skills into `skills-external/higgsfield-*` through the new `lib/higgsfield-skills.sh`; `make update` refreshes the skills, and the CLI when npm installed it; `make doctor` reports the CLI and its session without ever warning. The pack belongs to no profile: `lib/toggle-external.sh enable higgsfield` links the seven allowlisted media skills, `enable higgsfield-websites` the landing-page aid, and no `profile set` or `make link` re-enables either. `CLAUDE.global.md` routes explicit media-generation asks to it. Hermetic suite `lib/tests/higgsfield.test.sh`.
 - **Effort round (BDR-108)**: every skill carries an entry level next to its model pin. `lib/effort-pins.txt` (map) + `lib/effort-pins.sh` (idempotent re-apply after the last vendoring step of `install-plugins.sh` and `update-all.sh`) replace the hardcoded brainstorming/writing-plans loop and extend the pins to the design stack (high, one level per stack since the last loaded wins), superpowers, agent-skills and the 21st pack; `skills-perso` low, `pdf-translate` medium, `site-motion` high; doctrine: the design stack loads paired with the first Read (a lone Skill call applies nothing). Model pins stay tier aliases: the latest version of a tier is also the cheapest or same-priced, so the quality/price trade-off is tier × effort, never version. `lib/effort-audit.py` prints thinking coverage per scope (sub-agent records carry no thinking count on ~90 % of requests: EVAL-037's "executors stay cheap" was a measurement gap, not a finding).
@@ -220,6 +222,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
   seeded like a real tree (gstack off, nothing linked).
 
 ### Changed
+- Default session model `claude-fable-5-1` (settings.json `model`).
 - **`full` = everything the other profiles carry** (user rule: full does
   what every specialized profile does), minus the 9 removed gstack
   skills, the 21st generation/review trio and one named exception

MIGRATION.md

@@ -1,4 +1,6 @@
-# Migration guide — `.claude/` restructure (2026-04-23)
+# Migration guides
+
+## `.claude/` restructure (2026-04-23)
 
 The claude-config layout moved task tracking, memory registries, and audit
 reports out of scattered roots (`tasks/`, `SEO.md`, `HARDEN.md`, etc.) into
@@ -9,7 +11,7 @@ claude-config skills and were onboarded before this change.
 
 ---
 
-## TL;DR — full migration in one block
+### TL;DR — full migration in one block
 
 Run from the project root. Inspect the output before committing.
 
@@ -62,6 +64,8 @@ done
 #    .claude/memory/learnings.md (LRN-XXX format) then delete LESSONS.legacy.md
 
 # 6. Update .gitignore - see "Gitignore patch" section below
+#    (`bash ~/.claude/lib/gitflow.sh reconcile` appends only the missing
+#    template lines and never rewrites project rules.)
 
 # 7. Update CLAUDE.md - see "CLAUDE.md patch" section below
 
@@ -72,7 +76,7 @@ git check-ignore -v .claude/memory/decisions.md .claude/tasks/TODO.md 2>&1
 
 ---
 
-## Gitignore patch
+### Gitignore patch
 
 If your project's `.gitignore` contains a bare `.claude/` rule, it will ignore
 every memory/tasks/audit file you just created. Replace that line with:
@@ -84,9 +88,13 @@ every memory/tasks/audit file you just created. Replace that line with:
 !.claude/memory/
 !.claude/audits/
 !.claude/settings.json
+!.claude/deploy/
 # These stay ignored (per-machine state)
 .claude/settings.local.json
 .claude/agent-memory/
+.claude/gstack/
+.claude/deploy/PENDING.json
+.claude/deploy/NEXT.sh
 ```
 
 Verify after edit:
@@ -101,7 +109,7 @@ git check-ignore .claude/settings.local.json .claude/agent-memory/
 
 ---
 
-## CLAUDE.md patch
+### CLAUDE.md patch
 
 If your project's `CLAUDE.md` references `tasks/LESSONS.md` / `tasks/TODO.md`,
 update the `## Session start`, `## Workflow`, `## After code changes`, and
@@ -126,7 +134,7 @@ Add a new section referencing the registries (full template in
 
 ---
 
-## What gets committed vs ignored
+### What gets committed vs ignored
 
 | Path | Committed? | Reason |
 |------|-----------|--------|
@@ -134,12 +142,14 @@ Add a new section referencing the registries (full template in
 | `.claude/memory/*.md` | ✅ yes | Shared decisions/learnings/blockers |
 | `.claude/audits/*.md` | ✅ yes | Snapshot of project state — version-able |
 | `.claude/settings.json` | ✅ yes | Shared project config |
+| `.claude/deploy/*.md` | ✅ yes | Deploy runbook + incidents |
 | `.claude/settings.local.json` | 🚫 no | Per-machine overrides |
 | `.claude/agent-memory/` | 🚫 no | Per-session agent state |
+| `.claude/deploy/PENDING.json`, `NEXT.sh` | 🚫 no | Per-deploy transient state |
 
 ---
 
-## Post-migration sanity check
+### Post-migration sanity check
 
 ```bash
 # 1. No legacy tasks/ dir left
@@ -161,10 +171,29 @@ All four checks should be clean before committing the migration.
 
 ---
 
-## If anything goes wrong
+### If anything goes wrong
 
 - The migration block only uses `mv`, not `rm` — nothing is deleted.
 - Old `LESSONS.md` is preserved as `LESSONS.legacy.md` — review it, copy
   meaningful entries into `.claude/memory/learnings.md` (with `LRN-XXX` IDs),
   then delete.
 - To undo: `git checkout .` before commit.
+
+---
+
+## Upgrading an existing machine to 2.0.0
+
+2.0.0 removes components that 1.x installed. `make plugin` installs their replacements; the leftovers go by hand.
+
+```bash
+git pull --recurse-submodules
+make plugin     # vendors the 7 superpowers skills (Step 8e), installs the Higgsfield and 21st CLIs (8.6, 8.7), re-runs link.sh (10), applies the default profile (11)
+claude plugin uninstall superpowers@superpowers-marketplace   # once, if the plugin is still cached
+make doctor
+```
+
+- **Superpowers**: the plugin is gone. Its 7 wired skills are vendored at v6.4.1 and always on. The 8 other skills and the session-start injection are not replaced.
+- **Magic MCP**: replaced by the `21st` CLI (`21st login`, no API key). If 1.x registered the `magic` server, remove it from `~/.claude.json` and drop `MAGIC_API_KEY` from `~/.claude/.env`. Nothing reads them any more.
+- **Git hooks in every repo**: `link.sh` sets git's global `core.hooksPath` to `~/.claude/githooks`. Every repo on the machine now gets the gitflow pre-commit guard and pushes each commit as it lands. For a foreign clone: `git config gitflow.protect false` and `git config gitflow.autopush false`.
+- **Default profile**: a machine with no profile selected now runs `full`. Check with `make profile-current`. Nine gstack skills (`ship`, `land-and-deploy`, `setup-deploy`, `autoplan`, `context-save`, `learn`, `careful`, `guard`, `design-shotgun`) left every profile and are denylisted.
+- **Higgsfield**: installed, off by default. Nothing to do until you enable it.

Makefile

@@ -1,7 +1,7 @@
 .PHONY: help install plugin link doctor update new-skill profile profile-list profile-current profile-reset onboard test scan-secrets seo-connect
 
 help: ## Show available commands
-	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  make %-14s %s\n", $$1, $$2}'
+	@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  make %-16s %s\n", $$1, $$2}'
 
 install: ## First-time setup: install Claude Code + auth + symlinks + plugins
 	bash install.sh
@@ -41,7 +41,7 @@ test: ## Run deterministic tests hermetically (one: make test suite=lib/tests/x.
 			*) bash "$$t" || fail=1 ;; \
 		esac; done; exit $$fail
 
-scan-secrets: ## Gitleaks sweep: this repo's history + ~/.claude (job7 backstop). Extra repos: make scan-secrets repos="path1 path2"
+scan-secrets: ## Gitleaks sweep: this repo's history + ~/.claude. Extra repos: make scan-secrets repos="path1 path2"
 	@command -v gitleaks >/dev/null 2>&1 || { echo "gitleaks not installed — https://github.com/gitleaks/gitleaks"; exit 1; }
 	@mkdir -p .audit
 	@fail=0; \
@@ -59,7 +59,7 @@ scan-secrets: ## Gitleaks sweep: this repo's history + ~/.claude (job7 backstop)
 profile: ## Run profile.sh (usage: make profile cmd="set design")
 	@bash lib/profile.sh $(cmd)
 
-profile-list: ## List skill profiles (design, dev, qa, audit, minimal)
+profile-list: ## List skill profiles (audit, backend, design, dev, full, max, minimal, qa, seo, web, web-full)
 	@bash lib/profile.sh list
 
 profile-current: ## Show the active profile (label + match)

README.md

@@ -16,18 +16,19 @@ Not a collection of prompts — an operating layer on top of Claude Code:
   the cheapest model that can do the job (haiku collects, sonnet executes,
   opus judges, the session model only reflects).
 - **Hooks and permissions** are deterministic guardrails: gitflow enforced
-  by a pre-commit hook, every commit pushed by post-commit and post-merge
-  hooks, `main`/`develop` undeletable by a reference-transaction hook,
+  by a pre-commit hook in every repo (`make link` points git's global
+  `core.hooksPath` at `~/.claude/githooks`), every commit pushed by
+  post-commit and post-merge hooks, `main`/`develop` undeletable by a reference-transaction hook,
   deny-first permission rules, secrets kept in `~/.claude/.env` and
   never in config files.
 - **Templates and memory** seed every project with persistent registries
-  (decisions, learnings, blockers) — what a session learns, the next
-  session knows.
+  (decisions, learnings, blockers, journal, evals) — what a session
+  learns, the next session knows.
 
 ## How it works
 
 ```bash
-git clone --recurse-submodules https://github.com/bchanot/claude
+git clone --recurse-submodules https://git.bchanot.fr/bchanot/claude
 cd claude
 make install     # CLI + auth + symlinks + plugins (pinned in plugins.lock.json)
 make doctor      # verify everything
@@ -39,7 +40,7 @@ Day to day:
 
 ```bash
 /onboard            # bring an existing repo into the framework
-/ship-feature "…"   # brainstorm → plan → adversarial challenge → TDD → review → merge
+/ship-feature "…"   # brainstorm → plan → adversarial challenge → TDD → verify + security gates → review → merge on your go
 /feat "…"           # same idea, 1-5 files, no ceremony
 /close              # flush decisions and learnings to memory before quitting
 make update         # keep CLI, plugins, and submodules current
@@ -51,8 +52,9 @@ make update         # keep CLI, plugins, and submodules current
   locked, `make doctor` proves it works.
 - **Cost-shaped.** Model tiering routes reflection to the big model and
   execution to cheap ones — the expensive context does only what it must.
-- **Safe by default.** Protected branches, ask-before-run on risky tools,
-  parameterized secrets: the guardrails are code, not good intentions.
+- **Safe by default.** Protected branches, deny rules and auto-mode soft/hard blocks on
+  risky tools, transfer and mirror tools denied outright, parameterized
+  secrets: the guardrails are code, not good intentions.
 - **It compounds.** Memory registries, audit skills, and doc-sync keep every
   project's knowledge growing across sessions instead of evaporating.
 
@@ -68,7 +70,7 @@ commands, settings, secrets, maintenance.
 Doctrine: the session model (Fable) does main-loop reflection ONLY —
 brainstorm, plan, contract, audit judgment, gates, loop decisions — enforced
 by a blocking gate (`lib/model-gate.md` + `lib/model-check.sh`) at the entry
-of the 13 reflection orchestrators. Nothing dispatched inherits silently:
+of the 15 reflection skills (the orchestrators plus `/analyze`). Nothing dispatched inherits silently:
 typed agents carry a frontmatter pin, built-ins get an explicit `model=` at
 every call site.
 
@@ -90,7 +92,7 @@ The pure-execution skills `/doc`, `/status`, `/commit-change`,
 `/release-candidate` **dispatch** their agent (instead of inline-loading it)
 so the pin takes effect and the work leaves the big session model; `/hotfix`
 was split like `/feat` (reflection inline + gate, `hotfixer` executor) and so
-joins the gated group (13th); `/client-handover`'s nested skill-runner
+joins the gated group; `/client-handover`'s nested skill-runner
 children are dispatched `model:"fable"` (they carry reflection).
 
 ## Effort routing (BDR-107, BDR-108)
@@ -100,7 +102,7 @@ Second axis of the same table: how hard each phase thinks. Session default
 appliers, medium executors, high judgment, xhigh challengers and gates; none
 on haiku, which rejects the parameter). Every user-invoked skill carries an
 entry level (`/status` low … `/ship-feature` xhigh); the vendored externals
-(design stack, superpowers, agent-skills, 21st) get theirs from
+(design stack, superpowers, agent-skills, MengTo scroll skills, 21st) get theirs from
 `lib/effort-pins.txt`, re-applied by `lib/effort-pins.sh` after every
 vendoring step. Orchestrators shift per phase through the `effort-low` …
 `effort-max` skills (`lib/effort-shift.md`, always sent with another tool
@@ -116,6 +118,7 @@ never version. Census `lib/tests/effort-routing.test.sh`; transcript audit
 
 All scripts use their own location to find the repo — run them from anywhere.
 The plugins step logs to `install-YYYYMMDD-HHMMSS.log`.
+The last step applies the default profile, `full`, when none is selected, and re-applies an existing selection.
 
 **Optional — Context7** (fast doc lookup for React / Next.js / Prisma…): the plugins
 step installs the `ctx7` CLI and wires it into Claude Code. The doc-fetch surface is
@@ -136,14 +139,21 @@ ctx7 login                 # optional: OAuth / API key for higher rate limits
 | Component | Type | Description | Docs |
 |---|---|---|---|
 | **Superpowers skills** | Vendored (7, always on) | brainstorming, writing-plans, subagent-driven development, TDD, code review request, git worktrees, writing-skills — pinned v6.4.1 in plugins.lock.json, no plugin, no session injection | [obra/superpowers](https://github.com/obra/superpowers) |
-| **GStack** | Plugin (toggle) | Full-product workflow: UI + design + deploy + browser QA. Skip for backend/CLI projects. | [garrytan/gstack](https://github.com/garrytan/gstack) |
+| **GStack** | Git submodule (per profile) | Product workflow skills: plan reviews, design, browser QA, security (`cso`), `health`. Linked per profile; 9 broken or doctrine-breaking skills are denylisted in `lib/gstack-removed.sh`. | [garrytan/gstack](https://github.com/garrytan/gstack) |
 | **GSD v2** | External CLI | Multi-session orchestration: crash recovery, cost tracking, parallel workers, context-fresh execution. | [gsd-build/gsd-2](https://github.com/gsd-build/gsd-2) |
-| **RTK** | Plugin (always on) | Code rewrite hook. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) |
-| **security-guidance** | Plugin (always on) | Security hook. Zero passive cost. | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
+| **RTK** | CLI + hook (always on) | Rust Token Killer: the `hooks/rtk-rewrite.sh` PreToolUse hook rewrites Bash commands through `rtk` to cut output tokens. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) |
+| **security-guidance** | Plugin (always on) | Security hook. Regex layer and commit/push review on; the Stop-time diff review is off (`ENABLE_STOP_REVIEW=0`). | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
 | **ui-ux-pro-max** | Plugin (toggle) | Design system, color/typography choices. Enable for design-heavy projects. | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
-| **Context7** | Plugin (toggle) | Fast-evolving libs doc lookup (Next.js, React, Prisma...). Works anonymously; optional `ctx7 login` raises rate limits. | [context7.com](https://context7.com/) |
+| **Context7** | CLI (`ctx7`) | Doc lookup for fast-evolving libs (Next.js, React, Prisma...), used through the `find-docs` skill. Works anonymously; optional `ctx7 login` raises rate limits. | [context7.com](https://context7.com/) |
 | **pr-review-toolkit** | Plugin (toggle) | Multi-agent PR review. | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
 | **Graphify** | Python CLI | Codebase → knowledge graph → navigable wiki. Helps Claude map and search projects efficiently. | [pypi: graphifyy](https://pypi.org/project/graphifyy/) |
+| **21st.dev** | External CLI + skill pack | Component catalog and UI generation (`21st`), browser login, no API key. 7 skills in `skills-external/21st-*`, linked per profile (see the 21st.dev CLI section). | [npm: @21st-dev/cli](https://www.npmjs.com/package/@21st-dev/cli) |
+| **Higgsfield** | External CLI + skill pack (off by default) | Image, video, audio and brand media generation, metered credits (see the Higgsfield CLI section). | [higgsfield-ai/skills](https://github.com/higgsfield-ai/skills) |
+| **Semgrep** | Python CLI (pinned) | SAST engine behind the security gate (`security-auditor`). | [pypi: semgrep](https://pypi.org/project/semgrep/) |
+| **Impeccable** | npm CLI + skill (pinned) | Deterministic anti-slop detector (`npx impeccable detect`, 45 rules) and the `/impeccable` design verbs. | [npm: impeccable](https://www.npmjs.com/package/impeccable) |
+| **Design skills** | Vendored | `emil-design-eng`, `frontend-design` (Anthropic example-skills), `design-motion-principles`: UI polish, anti-slop build, motion. | [emilkowalski/skill](https://github.com/emilkowalski/skill) · [kylezantos/design-motion-principles](https://github.com/kylezantos/design-motion-principles) |
+| **agent-skills** | Vendored (commit-pinned) | `observability-and-instrumentation`, `deprecation-and-migration`, `ci-cd-and-automation`. | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) |
+| **MengTo scroll skills** | Vendored (commit-pinned) | Five scroll-choreography skills: `scroll-world-storytelling`, `build-threejs-scroll-worlds`, `scroll-scrubbed-visual-sequence`, `scroll-scrubbed-word-reveal`, `scroll-progress-timeline`. | [MengTo/Skills](https://github.com/MengTo/Skills) |
 
 Versions are pinned in `plugins.lock.json`. To update: edit the file, then re-run `install-plugins.sh`.
 
@@ -160,7 +170,7 @@ a different package, ships its own conflicting `graphify` bin) — see
 |---|---|
 | `/init-project` | Initialize a complete project from scratch (full orchestrator, 12+ steps) |
 | `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
-| `/onboard` | Onboard an existing project — generate CLAUDE.md, settings, .claudeignore |
+| `/onboard` | Onboard an existing project: CLAUDE.md, settings, .claudeignore, archetype audits, report and a sequenced TODO backlog |
 | `/feat` | Small feature implementation (1-5 files, lightweight) |
 | `/bugfix` | Structured bug fix with root cause investigation |
 | `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) |
@@ -173,7 +183,7 @@ a different package, ships its own conflicting `graphify` bin) — see
 | `/commit-change` | Smart commit grouping from staged/unstaged changes |
 | `/gitflow` | Gitflow branch operations — bootstrap main+develop, start a typed branch, directed merge |
 | `/release-candidate` | Cut a versioned release — finalize version.txt + CHANGELOG, merge develop→main, tag, push |
-| `/deploy` | Run a project's deploy from its committed runbook — instantiate the delta, resume cold |
+| `/deploy` | Compose the deploy checklist from a project's committed runbook (delta only); you run it, the skill resumes cold on your report |
 | `/graphify` | Codebase knowledge graph — navigation for large-scope tasks |
 | `/plugin-check` | Check active plugins vs project needs — recommend enable/disable |
 | `/health` | Code quality dashboard (gstack) — setup diagnostic is `make doctor` |
@@ -191,6 +201,8 @@ a different package, ships its own conflicting `graphify` bin) — see
 | `/client-handover` | Final project delivery — audits + branded deliverable (Markdown / HTML / PDF) |
 | `/profile` | Activate a skill profile (web / seo / web-full / full / max / backend / design / dev / qa / audit / minimal) (default: full) |
 | `/tour` | Grouped all-axes sweep — cleanup + security + reconcile + doc, fix and loop until clean |
+| `/site-motion` | Site-level motion: scroll engine choice, page transitions, pin/scrub sequencing across a page or Astro route (design stack) |
+| `/effort-low` … `/effort-max` | Effort shifters the orchestrators send per phase; type `/effort-max` to re-run a stuck turn at maximum |
 
 > This table lists personal skills. Gstack skills (investigate, review, retro,
 > office-hours, cso…) and marketplace plugins add many more — run
@@ -221,13 +233,15 @@ cd my-existing-project/
 
 ```
 /ship-feature "feature description"
-# → STEP 0: plugin check
-# → STEP 1-2: brainstorm + plan (superpowers)
+# → STEP 0: plugin check, project context, contract
+# → STEP 1-2: brainstorm + plan (vendored superpowers skills)
 # → STEP 2b: adversarial plan-challenge (3 lenses, report-only)
 # → STEP 3: validation gate — user approval required
-# → STEP 4-7: implement (TDD) → review → capitalize (memory)
-# → STEP 8: sync README (doc-sync)
-# → STEP 9: finish (merge / PR)
+# → STEP 4: implement (TDD)
+# → STEP 5: verify + secure (fresh verifier and security-auditor gates)
+# → STEP 6-7: review → capitalize (memory)
+# → STEP 8: doc sync (public docs, committed before finish)
+# → STEP 9: finish, `gitflow finish` into develop on your explicit go
 ```
 
 For small features (1-5 files), use `/feat` instead — no orchestration overhead.
@@ -241,7 +255,7 @@ Settings follow a hierarchy (highest priority first):
 ```
 managed-settings.json   → enterprise (cannot be overridden)
 CLI flags               → session only
-.claude/settings.local  → personal machine overrides (gitignored)
+.claude/settings.local.json → personal machine overrides (gitignored)
 .claude/settings.json   → project rules (committed)
 ~/.claude/settings.json → global user rules (this repo)
 ```
@@ -326,9 +340,10 @@ npm i -g @21st-dev/cli
 `make plugin` does both (Step 8.7 installs the CLI, then offers the login in
 an interactive terminal) and installs the skill pack that drives it:
 `21st-ui-build`, `-ui-explore`, `-ui-review`, `-cli-use`, `-ai`, plus the two
-publishing skills `-registry` and `-design-sync`. The five design skills
-follow the active profile: they are on under `full`, the default profile,
-and under `design`, `web` and `web-full`. The two publishing skills,
+publishing skills `-registry` and `-design-sync`. Of the five design skills, `21st-ui-build` and
+`21st-cli-use` follow the active profile: on under `full`, the default profile, and under `design`,
+`web` and `web-full`. The other three, `-ui-explore`, `-ui-review` and
+`-ai`, are on under `max` only. The two publishing skills,
 `-registry` and `-design-sync`, are in no profile and stay parked until
 `bash lib/toggle-external.sh enable 21st` turns on all seven.
 
@@ -413,7 +428,7 @@ bash doctor.sh              # full diagnostic (symlinks, plugins, permissions, t
 bash update-all.sh          # update all components (CLI, plugins, submodules, symlinks)
 
 # Claude Code
-/health                     # gstack code-quality dashboard (doctor.sh -> make doctor)
+/health                     # gstack code-quality dashboard (setup diagnostic: make doctor)
 /status                     # project snapshot (plugins, git, GSD milestone)
 /plugin-check "description" # audit plugin config vs project needs
 
@@ -423,7 +438,9 @@ make plugin                 # install plugins only
 make link                   # create/update symlinks into ~/.claude/
 make doctor                 # diagnostic
 make update                 # update Claude Code, config, submodules, plugins, and verify
-make test                   # run deterministic tests (lib/tests/*.test.sh + lib/seo-data/*.test.sh + lib/gitflow-test.sh + lib/tests/run-*.sh)
+make test [suite=lib/tests/x.test.sh]  # hermetic deterministic tests: every suite, or one
+make scan-secrets [repos="…"]  # gitleaks sweep of this repo's history and ~/.claude, reports in .audit/ (never committed)
+make help                   # list make targets
 make onboard                # onboard an existing project (run from its dir)
 make seo-connect            # connect a Google account for /seo FULL (OAuth consent)
 make profile cmd="set X"    # activate a skill profile (web/seo/web-full/full/max/backend/design/dev/qa/audit/minimal)
@@ -433,7 +450,7 @@ make profile-reset          # go to the default profile (full)
 make new-skill name=myskill # scaffold agent + skill files
 ```
 
-`doctor.sh` checks: symlinks, GStack submodule, vendored skills (curl-pinned externals in `plugins.lock.json` + `link.sh`'s `EXTERNAL_SKILLS`, per the active profile), Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency.
+`doctor.sh` checks: symlinks, GStack submodule, vendored skills (curl-pinned externals in `plugins.lock.json` + `link.sh`'s `EXTERNAL_SKILLS`, per the active profile), Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency, git hooks (global core.hooksPath + generated githooks/), scratchpad (TMPDIR quota), Higgsfield CLI and session, seo-data layer.
 
 ---
 
@@ -441,4 +458,6 @@ make new-skill name=myskill # scaffold agent + skill files
 
 [`USAGE.md`](./USAGE.md) — workflows and skill decision tree ·
 [`ARCHITECTURE.md`](./ARCHITECTURE.md) — layout and principles ·
-[`CHANGELOG.md`](./CHANGELOG.md) — version history.
+[`CHANGELOG.md`](./CHANGELOG.md) — version history ·
+[`MIGRATION.md`](./MIGRATION.md): upgrade guides ·
+[`templates/settings/SETTINGS.md`](templates/settings/SETTINGS.md): permission tiers and guardrails

USAGE.md

@@ -83,7 +83,7 @@ Tu veux...
 │    → /prune-memory           ← curer / compresser les registres .claude/memory/
 │
 └─ Quelque chose ne marche pas ?
-     → /health    ← diagnostic complet (symlinks, plugins, permissions, token budget)
+     → make doctor   ← diagnostic d'installation (symlinks, plugins, permissions, hooks, token budget)
 ```
 
 ### Règle de décision simplifiée
@@ -122,7 +122,7 @@ Tu veux...
 | Changer profil skills | `/profile` |
 | Audit/polish design (anti-slop) | `/impeccable` |
 | Sweep groupé tous axes (nettoyage + sécu + reconcile + doc) | `/tour` |
-| Rien ne marche | `/health` |
+| Rien ne marche | `make doctor` (terminal) |
 
 ---
 
@@ -147,10 +147,10 @@ Tu veux...
 | `/commit-change` | Commits bien structurés | Groupe les changements par unité logique |
 | `/gitflow` | Opérations de branches gitflow | Bootstrap main+develop, branche typée, merge dirigé |
 | `/release-candidate` | Couper une release versionnée (develop en avance sur main) | Finalise version.txt + CHANGELOG, merge develop→main, tag, push |
-| `/deploy` | Déployer via le runbook du projet | Instancie le delta depuis le dernier deploy, reprend à froid |
+| `/deploy` | Déployer via le runbook du projet | Instancie le delta depuis le dernier deploy, reprend à froid ; tu exécutes la checklist, Claude ne déploie jamais |
 | `/graphify` | Navigation codebase large-scope | Knowledge graph, pour tâches multi-fichiers |
 | `/skills-perso` | Lister ses skills personnels | Skills créés dans ~/.claude/skills/ |
-| `/health` | Quand quelque chose ne fonctionne pas | Lance doctor.sh |
+| `/health` | Tableau de bord qualité du code (gstack) | Le diagnostic d'installation est `make doctor` |
 | `/status` | Reprendre après une pause | Snapshot : plugins, git, GSD milestone |
 | `/audit-delta` | Audit récurrent du delta depuis le dernier run | Axes : conformité / bugs / dead code / sécurité |
 | `/capitalize` | Avant /clear ou /compact | Flush contexte non capitalisé + réconcilie .claude/tasks/TODO.md |
@@ -181,7 +181,7 @@ audits avec fix), xhigh pour l'architecture et l'audit avant validation
 (`/ship-feature`, `/onboard`, `/analyze`). Les orchestrateurs décalent
 ensuite le niveau par phase (`lib/effort-shift.md`), et `/effort-max` tapé à
 la main relance un tour bloqué au maximum. Les skills externes vendorés
-(pile design, superpowers, 21st) reçoivent leur niveau de
+(pile design, superpowers, agent-skills, skills scroll MengTo, 21st) reçoivent leur niveau de
 `lib/effort-pins.txt`. Un skill chargé seul par Claude n'applique pas son
 niveau : il doit partir avec un autre appel d'outil dans le même message.
 
@@ -220,9 +220,9 @@ Hotfix/quick fix          → tout OFF (skills superpowers vendorisés, toujours
 # → STEP 1  : interview (skip si prompt complet)
 # → STEP 4  : ★ GATE — valider l'architecture
 # → STEP 7  : ★ GATE — valider le plan d'implémentation
-# → STEP 8-10 : implémentation TDD + review
-# → STEP 10b-c: capitalize mémoire + sync README (avant finish)
-# → STEP 11   : finish (merge / commit initial)
+# → STEP 8-10 : implémentation TDD + gates verify/sécurité + review
+# → STEP 10b-c: capitalize mémoire + sync docs publiques (avant finish)
+# → STEP 11   : finish, `gitflow finish` vers develop sur ton feu vert explicite
 
 # 3. Features suivantes
 /ship-feature "description de la feature"
@@ -240,7 +240,7 @@ Hotfix/quick fix          → tout OFF (skills superpowers vendorisés, toujours
 
 # Dans un terminal (depuis le dossier projet) :
 gsd                  # démarrer une session
-/gsd init            # initialise .gsd/ + ROADMAP (une fois, à la demande)
+/gsd init            # initialise .gsd/ + milestones (une fois, à la demande)
 /gsd auto            # mode autonome, walk away
 
 # Pour suivre :
@@ -274,9 +274,12 @@ cd mon-projet-existant/
 | 1  | Archetype detection (scan ~/.claude/lib/project-archetypes/*.md) | archétype SELECTED + implications auto |
 | 1b | Gate monorepo (A/B/C si détecté) | mode choisi |
 | 2  | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ |
+| 2.5| Lib d'animation (`motion`), proposée, opt-in | dépendance si acceptée |
+| 2.6| Gitflow init (main + develop, hooks) | branches + .githooks/ |
 | 3  | Interview deep = business minimum (users, deadlines, équipe, légal, perfs) + adaptative par archétype | brief enrichi |
 | 3.5| ctx7 doc audit — fast-libs détectées, cache pré-fetché si besoin | .ctx7-cache/ |
 | 4  | Graphify (proposé dès 200 fichiers code, l'utilisateur décide) | graphify-out/GRAPH_REPORT.md |
+| 4.5| Espace d'audit + contexte archétype | .onboard-audit/archetype-context.md |
 | 5  | Analyze read-only (analyzer agent) | .onboard-audit/analyze.md |
 | 6  | Audits parallèles selon archétype : | .onboard-audit/*.md (9 fichiers max) |
 |    |   — dette tech (general-purpose, audit read-only) |
@@ -287,6 +290,7 @@ cd mon-projet-existant/
 |    |   — performance (Lighthouse ou static bundle audit) |
 |    |   — accessibilité (axe ou static a11y audit) |
 | 7  | Synthèse structurée dans .claude/audits/ | ONBOARD_REPORT, AUDIT_GOOD, AUDIT_ISSUES, AUDIT_PROPOSALS |
+| 7b | Challenge adversarial des propositions avant la gate | AUDIT_PROPOSALS.md challengé |
 | 8  | Validation gate utilisateur | choix A/B/C/D/E |
 | 9  | Backlog .claude/tasks/TODO.md séquencé avec /skill recommandé par tâche | .claude/tasks/TODO.md |
 
@@ -308,7 +312,7 @@ cat .claude/audits/ONBOARD_REPORT.md
 # Multi-session (GSD) : gsd init à la main — voir docs gsd-pi
 ```
 
-**Archétypes supportés (P1)** : static-html, wordpress, nextjs-app-router, astro-static, react-spa, rest-api-node, rest-api-python, cli-tool, library, dotfiles-meta.
+**Archétypes supportés** : astro-static, cli-tool, data-notebook, desktop-electron, docker-compose-infra, dotfiles-meta, drupal, firmware-embedded, game-engine-native, ghost, library, mobile-expo, mobile-flutter, nextjs-app-router, react-spa, rest-api-node, rest-api-python, shopify, static-html, strapi, terraform-infra, web-game, woocommerce, wordpress.
 Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voir `_TEMPLATE.md`).
 
 ### Pattern D — Hotfix / bugfix · ~200-800t
@@ -340,7 +344,7 @@ Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voi
 ```
 # Feature simple, pas d'orchestration lourde
 /feat "ajouter un endpoint GET /api/v1/users/:id/stats"
-# → planning léger, implémentation directe, tests
+# → plan + challenge, exécuteur `feater`, gates fraîches verifier + sécurité
 # Pas de brainstorming superpowers, pas de gate de validation
 ```
 
@@ -351,7 +355,7 @@ Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voi
 | Scope | Feature complète, multi-fichiers | 1-5 fichiers max |
 | Orchestration | Pipeline superpowers complet | Planning léger, direct |
 | Gate de validation | Oui | Non |
-| Code review auto | Oui (superpowers) | Non |
+| Code review auto | Oui (superpowers) | Gates verifier + security-auditor |
 | Tokens estimés | ~1500-3000t | ~300-600t |
 
 ---
@@ -530,7 +534,7 @@ Convention: snake_case Python, camelCase TypeScript."
 **Workflow long avec GSD v2 :**
 ```
 # Après /init-project, on initialise GSD à la demande (plus auto-bootstrappé).
-# Le ROADMAP.md généré par `gsd init` contiendra :
+# Les roadmaps de milestone (`.gsd/milestones/<ID>/<ID>-ROADMAP.md`) contiendront :
 #   Milestone 1: Boutique in-app + Stripe
 #   Milestone 2: PvP + matchmaking
 #   Milestone 3: Leaderboard + saisons
@@ -538,7 +542,7 @@ Convention: snake_case Python, camelCase TypeScript."
 # Dans un terminal :
 cd cardforge/
 gsd                  # démarre session GSD
-/gsd init            # crée .gsd/ + ROADMAP (à la demande — plus auto à l'init)
+/gsd init            # crée .gsd/ + milestones (à la demande — plus auto à l'init)
 /gsd auto            # GSD travaille sur Milestone 1 de façon autonome
 # → research Stripe API + docs
 # → plan décomposé en tâches
@@ -556,7 +560,7 @@ gsd                  # démarre session GSD
 gsd
 /gsd quick "Implémenter la boutique in-app avec Stripe"
 # ou
-/gsd auto  # si ROADMAP.md est déjà à jour
+/gsd auto  # si la roadmap du milestone est à jour
 ```
 
 ---
@@ -876,7 +880,7 @@ PROJECT STATUS
 CONFIG
   Version   : v2.5.0
   Plugins ON: context7 (~200t), skills superpowers vendorisés (toujours actifs, 0 t passif)
-  GSD v2    : installed (2.64.0)
+  GSD v2    : installed (3.0.0)
 
 PROJECT
   CLAUDE.md : found
@@ -951,13 +955,13 @@ Updated: Slice 4 plan — Payment Element instead of CardElement
 Continue? (yes)
 ```
 
-GSD v2 met à jour le plan dans `.gsd/ROADMAP.md` sans perdre le travail déjà fait.
+GSD v2 met à jour le plan dans la base GSD (`.gsd/gsd.db`) sans perdre le travail déjà fait.
 
 #### Ce que ce workflow démontre
 
 - **`/status`** est le point d'entrée naturel après une pause — snapshot complet en 1 commande.
 - **GSD v2 `step mode`** est préférable à `auto` après une longue pause — permet de vérifier que les décisions sont toujours valides.
-- **`.gsd/ROADMAP.md`** est la source de vérité du progress — parsé par `/status` et par GSD lui-même.
+- **La base GSD (`.gsd/gsd.db`)** est la source de vérité du progress; `/status` la lit via `gsd headless query`.
 - **`/gsd discuss`** permet de modifier l'architecture en cours de route sans recommencer depuis zéro.
 ---
 

templates/settings/SETTINGS.md

@@ -112,6 +112,10 @@ arbitrary code execution (`Bash(*)`, wildcarded interpreters such as
 `permissions.allow` says. `awk` and `echo` pass through a static rule; `node`
 cannot.
 
+### Package installs
+
+Global npm installs run their install scripts with your rights on the whole machine. `npm install -g`, `npm i -g` and their `--global` spellings are in `permissions.deny`. An `autoMode.soft_deny` entry catches every other spelling (a flag after the package name, `npm add -g`) and holds the install until you name the package in the current turn, after Claude states its publisher, age, download volume, install scripts and known advisories. A second `soft_deny` entry covers `npx`, `pnpm dlx` and `yarn dlx` of a package absent from the manifest and lockfile. Project-local scripts and declared packages pass through `autoMode.allow`.
+
 ### Scope of intent
 
 A `soft_deny` clears on the user's instruction, and this config scopes that to
@@ -124,7 +128,7 @@ no separate setting for this.
 - `Read(**/.env)` only blocks the Read tool. `Bash(cat .env)` bypasses it unless separately denied.
   → Use `.claudeignore` for hard file exclusion regardless of tool.
 - `disableBypassPermissionsMode: "disable"` prevents switching to bypass mode mid-session.
-- Prefer `ask` over `allow` for anything touching external systems.
+- Prefer `autoMode.soft_deny` over `allow` for anything touching external systems.
 - `deny` in `~/.claude/settings.json` cannot be overridden by project-level `allow` — deny always wins.
 - Under `defaultMode: auto`, `ask` does not raise a prompt (see above). A destructive
   command belongs in `deny` or in `autoMode.soft_deny`, not in `ask`.