bigpowers 2.86.5 → 2.86.7

package/.pi/prompts/validate-contracts.md

@@ -86,12 +86,21 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–24 | Integration |
-| 26–35 | Configuration |
-| 37–46 | Verification |
-| 48–170 | Reference blocks + Examples 1–6 |
-| 172–190 | Integration (duplicate) + Configuration + Verification |
+| 3–23 | Navigation |
+| 24–32 | Integration |
+| 33–44 | Configuration |
+| 45–54 | Verification |
+| 55–71 | Reference block 1 |
+| 72–92 | Reference block 2 |
+| 93–104 | Example 1 |
+| 105–121 | Example 2 |
+| 122–133 | Example 3 |
+| 134–144 | Example 4 |
+| 145–165 | Example 5 |
+| 166–176 | Example 6 |
+| 177–185 | Integration |
+| 186–197 | Configuration |
+| 198–204 | Verification |
 
 ## Integration
 

package/.pi/prompts/wire-ci.md

@@ -117,11 +117,18 @@ See [REFERENCE.md](REFERENCE.md).
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–38 | Examples |
-| 40–52 | Options |
-| 54–62 | Integration with build-epic |
-| 64–270 | Reference blocks 1–8 |
+| 3–20 | Navigation |
+| 21–22 | Examples |
+| 23–39 | Create CI for a Go project (TBR + optional deploy) |
+| 40–49 | Create CI for a CLI tool (TBR only, no deploy) |
+| 50–57 | Validate existing workflows (no generation) |
+| 58–70 | Options |
+| 71–79 | Integration with build-epic |
+| 80–154 | Reference block 1 — test-build-release.yml (Go, excerpt) |
+| 155–204 | Reference block 2 — deploy.yml (generic web app, excerpt) |
+| 205–232 | Reference block 3 — CLI dogfood (big-release pattern) |
+| 233–257 | Reference block 4 — validate script |
+| 258–268 | Reference block 5 — dry-run |
 
 ## Examples
 

package/.pi/prompts/write-document.md

@@ -85,10 +85,36 @@ Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 5–16 | Navigation |
-| 18–24 | Sections intro |
-| 26–178 | README section templates (1–15) |
-| 180–183 | Verify |
+| 5–40 | Navigation |
+| 41–42 | Sections |
+| 43–54 | 1. Title + Badges |
+| 55–60 | 2. Tagline |
+| 61–64 | 3. Description |
+| 65–67 | 4. Prerequisites |
+| 68–75 | Prerequisites |
+| 76–78 | 5. Installation |
+| 79–89 | Installation |
+| 90–92 | 6. Usage |
+| 93–102 | Usage |
+| 103–105 | 7. Features |
+| 106–113 | Features |
+| 114–116 | 8. Configuration |
+| 117–125 | Configuration |
+| 126–128 | 9. Development Setup |
+| 129–139 | Development |
+| 140–142 | 10. Running Tests |
+| 143–152 | Tests |
+| 153–155 | 11. Contributing |
+| 156–164 | Contributing |
+| 165–167 | 12. Changelog |
+| 168–172 | Changelog |
+| 173–175 | 13. Links |
+| 176–181 | Links |
+| 182–184 | 14. License |
+| 185–191 | License |
+| 192–194 | 15. Credits (optional) |
+| 195–199 | Credits |
+| 200–202 | Verify |
 
 ## Sections
 
@@ -246,7 +272,7 @@ Detect from CLAUDE.md or project LICENSE file.
 ```markdown
 ## Credits
 
-Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
 ```
 
 ## Verify

package/.pi/skills/commit-message/SKILL.md

@@ -137,4 +137,4 @@ This table reflects the **out-of-the-box** behavior of `semantic-release` using
 
 - [Conventional Commits — specification](https://www.conventionalcommits.org/en/v1.0.0/#specification)
 - [semantic-release — README (commit format & flow)](https://github.com/semantic-release/semantic-release#commit-message-format)
-- Fork pointer: [semantic-release-baby](https://github.com/danielvm-git/semantic-release-baby) (automation and docs align with upstream semantic-release)
+- Automation and docs align with [semantic-release](https://github.com/semantic-release/semantic-release) upstream; a fork may be substituted without changing this guidance.

package/.pi/skills/evolve-skill/SKILL.md

@@ -52,4 +52,4 @@ See [REFERENCE.md](../../../skills/evolve-skill/REFERENCE.md) for ADR template.
 **Evidence:** path/to/benchmark-report.md
 ```
 
-Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path.
+Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine; clone it from wherever your fork lives if absent. Never assume a hard-coded absolute path or a specific owner.

package/.pi/skills/guard-git/SKILL.md

@@ -56,14 +56,14 @@ Full JSON examples, merge rules, Antigravity deny-list entries, and test command
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–24 | Secret patterns |
-| 26–44 | Copy layout |
-| 46–72 | Claude Code |
-| 74–92 | Cursor and Cursor CLI |
-| 94–120 | Gemini CLI |
-| 122–135 | Google Antigravity |
-| 137–178 | Verify (local tests) |
+| 3–16 | Navigation |
+| 17–28 | Secret patterns (audit + pre-commit) |
+| 29–46 | Copy layout |
+| 47–72 | Claude Code |
+| 73–94 | Cursor and Cursor CLI |
+| 95–122 | Gemini CLI |
+| 123–137 | Google Antigravity |
+| 138–180 | Verify (local tests) |
 
 ## Secret patterns (audit + pre-commit)
 

package/.pi/skills/kickoff-branch/SKILL.md

@@ -81,7 +81,7 @@ git worktree list | grep "<task-slug>"
 **Handling Conflicts:**
 - **Directory exists:** If `../<task-slug>` already exists, ask the user if they want to use it or delete it.
 - **Branch exists:** If the branch exists but no worktree is attached, ask to use the existing branch (`git worktree add ../<task-slug> <task-slug>`) or delete it.
-- **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata.
+- **Ghost worktree:** If `git worktree list` shows the path but the directory is missing, run `git worktree prune` to clear the stale metadata. `bash scripts/cleanup-worktrees.sh` does this plus reports any worktree whose branch is already merged or deleted — advisory only, it prints the `git worktree remove`/`git branch -d` commands rather than running them, so review before acting.
 
 ### 4. Create worktree + branch
 

package/.pi/skills/migrate-spec/SKILL.md

@@ -253,12 +253,58 @@ These GSD artifacts are not migrated — they are execution records, not plannin
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–22 | Navigation |
-| 24–62 | spec-kit → bigpowers Mapping |
-| 64–130 | BMAD → bigpowers Mapping |
-| 132–154 | Learnings to Adopt |
-| 156–350 | Output Formats + state.yaml template |
-| 352–620 | Reference blocks 1–2 + extended mappings |
+| 3–68 | Navigation |
+| 69–70 | spec-kit → bigpowers Mapping |
+| 71–84 | Artifact Locations |
+| 85–94 | `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md` |
+| 95–105 | `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/` |
+| 106–114 | `tasks.md` → `specs/epics/` (via slice-tasks) |
+| 115–120 | `.specify/` state |
+| 121–122 | BMAD → bigpowers Mapping |
+| 123–141 | Artifact Locations |
+| 142–148 | `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml` |
+| 149–160 | `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml` |
+| 161–167 | `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md` |
+| 168–174 | `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/` |
+| 175–178 | `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml` |
+| 179–182 | `story-*.md` → `specs/epics/` stories |
+| 183–188 | `project-context.md` → `CLAUDE.md` |
+| 189–192 | Learnings to Adopt |
+| 193–198 | From GSD |
+| 199–204 | From spec-kit |
+| 205–212 | From BMAD |
+| 213–214 | Output Formats |
+| 215–224 | ADR format (bigpowers) |
+| 225–227 | Context |
+| 228–230 | Decision |
+| 231–234 | Consequences |
+| 235–246 | DECISION-LOG.md format |
+| 247–257 | MIGRATION-AUDIT.md format |
+| 258–264 | Summary |
+| 265–274 | High Priority Findings |
+| 275–278 | Information |
+| 279–285 | Next Steps |
+| 286–306 | in_scope format with ID tracking |
+| 307–341 | REQUIREMENTS_TRACE.yaml format |
+| 342–397 | `specs/state.yaml` template format |
+| 398–416 | Reference block 1 |
+| 417–432 | Reference block 2 |
+| 433–451 | Reference block 3 |
+| 452–474 | Reference block 4 |
+| 475–482 | Reference block 5 |
+| 483–484 | Findings |
+| 485–489 | High Priority |
+| 490–495 | Information |
+| 496–509 | Reference block 6 |
+| 510–542 | Step 7 — Post-migration: Optional two-pass spec writing gate |
+| 543–574 | Step 8 — Post-migration: Optional methodology doc template |
+| 575–600 | Artifact Mapping Summary |
+| 601–610 | Rules |
+| 611–621 | Step 5 — Surface learnings (optional) |
+| 622–644 | Step 6 — Adversarial review (optional) |
+| 645–646 | Findings |
+| 647–651 | High Priority |
+| 652–660 | Information |
 
 # migrate-spec Reference — spec-kit, BMAD, Learnings
 

package/.pi/skills/plan-work/SKILL.md

@@ -108,11 +108,23 @@ Writes: state.yaml handoff.next_skill = kickoff-branch
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–38 | Output file formats |
-| 40–71 | Plan template |
-| 73–91 | Verify step format rules |
-| 93–131 | Sub-operations (risk, define-success, zoom-out, slopcheck, delta tags) |
+| 3–25 | Navigation |
+| 26–27 | Output file formats |
+| 28–31 | Story spec: `specs/epics/<capsule>/eNNsYY-<slug>.md` |
+| 32–61 | Task checklist: `specs/epics/<capsule>/eNNsYY-tasks.yaml` |
+| 62–64 | Plan template |
+| 65–71 | Story [X.Y]: [title] — Implementation Steps |
+| 72–77 | Steps |
+| 78–85 | Verification Script (Step-by-Step) |
+| 86–89 | Out of scope |
+| 90–94 | Risks |
+| 95–114 | Verify step format rules |
+| 115–116 | Sub-operations |
+| 117–127 | Risk Assignment Heuristics |
+| 128–143 | Requirement delta tags (e45s29) |
+| 144–152 | Define Success |
+| 153–161 | Zoom-Out Check |
+| 162–169 | Slopcheck |
 
 ## Output file formats
 

package/.pi/skills/publish-package/SKILL.md

@@ -83,11 +83,21 @@ See [REFERENCE.md](../../../skills/publish-package/REFERENCE.md)
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–18 | Navigation |
-| 20–28 | Options |
-| 30–60 | Examples |
-| 62–72 | Integration with release-branch |
-| 74–252 | Reference blocks 1–8 |
+| 3–23 | Navigation |
+| 24–35 | Options |
+| 36–37 | Examples |
+| 38–51 | Publish an npm package |
+| 52–59 | Publish a Rust crate |
+| 60–69 | Missing token scenario |
+| 70–80 | Integration with release-branch |
+| 81–121 | Reference block 1 |
+| 122–143 | Reference block 2 |
+| 144–162 | Reference block 3 |
+| 163–180 | Reference block 4 |
+| 181–195 | Reference block 5 |
+| 196–230 | Reference block 6 |
+| 231–248 | Reference block 7 |
+| 249–260 | Reference block 8 |
 
 ## Options
 

package/.pi/skills/release-branch/SKILL.md

@@ -147,15 +147,19 @@ Report: "Branch released."
 
 | Lines | Section |
 |-------|---------|
-| 1–3 | Title |
-| 5–16 | Navigation |
-| 18–41 | PR body template |
-| 43–54 | Worktree cleanup |
-| 56–96 | Cycle-time recording |
-| 98–119 | CI verification |
-| 121–126 | Solo-local fallback |
+| 1 | Title |
+| 3–22 | Navigation |
+| 23–31 | PR body template (team-pr mode) |
+| 32–35 | Summary |
+| 36–41 | Verify |
+| 42–47 | specs/ artifacts |
+| 48–58 | Worktree cleanup details |
+| 59–81 | Cycle-time recording |
+| 82–100 | Why not story_start minus story_end? |
+| 101–121 | CI verification |
+| 122–127 | Solo-local fallback detail |
 | 128–134 | Handoff |
-| 136–155 | Reference block 1 (manual squash) |
+| 135–159 | Reference block 1 |
 
 # Release Branch — Reference
 

package/.pi/skills/seed-conventions/SKILL.md

@@ -128,16 +128,26 @@ Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/
 
 | Lines | Section |
 |-------|---------|
-| 1–4 | Title + story tags |
-| 6–22 | Navigation (this table) |
-| 24–35 | AGENTS.md spine |
-| 37–76 | Agent config template |
-| 78–85 | opencode.json template |
-| 87–96 | Aider bridge |
-| 98–108 | Codex CLI wiring |
-| 110–118 | CONVENTIONS.md |
-| 120–122 | Stack profile fragments |
-| 124–153 | Local tool wiring |
+| 1 | Title |
+| 5–29 | Navigation |
+| 30–53 | Fenced markers (e45s21) |
+| 54–65 | AGENTS.md spine (Reach Template — e37s01) |
+| 66–77 | Agent config template (legacy — prefer AGENTS.md spine) |
+| 78–81 | Project |
+| 82–91 | Commands |
+| 92–94 | Architecture |
+| 95–98 | Conventions |
+| 99–104 | Never |
+| 105–114 | Agent Rules |
+| 115–123 | opencode.json template |
+| 124–133 | Aider — `.aider.conf.yml` bridge (e37s03) |
+| 134–146 | Codex CLI — project-local `.codex/config.toml` + AGENTS.md (e37s14) |
+| 147–156 | CONVENTIONS.md |
+| 157–160 | Stack profile fragments |
+| 161–164 | Local tool wiring (optional interview step 8) |
+| 165–173 | Cursor — project-local `.cursor/rules` symlink |
+| 174–187 | OpenCode — project-local `opencode.json` + `AGENTS.md` |
+| 188–190 | When to offer |
 
 ## Fenced markers (e45s21)
 

package/.pi/skills/smoke-test/SKILL.md

@@ -89,11 +89,15 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–12 | Navigation |
-| 14–31 | Runner script |
-| 33–42 | Configuration reference |
-| 44–53 | Verification |
-| 55–160 | Reference blocks 1–5 |
+| 3–17 | Navigation |
+| 18–34 | Runner script |
+| 35–46 | Configuration reference |
+| 47–55 | Verification |
+| 56–89 | Reference block 1 |
+| 90–107 | Reference block 2 |
+| 108–122 | Reference block 3 |
+| 123–159 | Reference block 4 |
+| 160–177 | Reference block 5 |
 
 ## Runner script
 

package/.pi/skills/validate-contracts/SKILL.md

@@ -87,12 +87,21 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–24 | Integration |
-| 26–35 | Configuration |
-| 37–46 | Verification |
-| 48–170 | Reference blocks + Examples 1–6 |
-| 172–190 | Integration (duplicate) + Configuration + Verification |
+| 3–23 | Navigation |
+| 24–32 | Integration |
+| 33–44 | Configuration |
+| 45–54 | Verification |
+| 55–71 | Reference block 1 |
+| 72–92 | Reference block 2 |
+| 93–104 | Example 1 |
+| 105–121 | Example 2 |
+| 122–133 | Example 3 |
+| 134–144 | Example 4 |
+| 145–165 | Example 5 |
+| 166–176 | Example 6 |
+| 177–185 | Integration |
+| 186–197 | Configuration |
+| 198–204 | Verification |
 
 ## Integration
 

package/.pi/skills/wire-ci/SKILL.md

@@ -118,11 +118,18 @@ See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md).
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–38 | Examples |
-| 40–52 | Options |
-| 54–62 | Integration with build-epic |
-| 64–270 | Reference blocks 1–8 |
+| 3–20 | Navigation |
+| 21–22 | Examples |
+| 23–39 | Create CI for a Go project (TBR + optional deploy) |
+| 40–49 | Create CI for a CLI tool (TBR only, no deploy) |
+| 50–57 | Validate existing workflows (no generation) |
+| 58–70 | Options |
+| 71–79 | Integration with build-epic |
+| 80–154 | Reference block 1 — test-build-release.yml (Go, excerpt) |
+| 155–204 | Reference block 2 — deploy.yml (generic web app, excerpt) |
+| 205–232 | Reference block 3 — CLI dogfood (big-release pattern) |
+| 233–257 | Reference block 4 — validate script |
+| 258–268 | Reference block 5 — dry-run |
 
 ## Examples
 

package/.pi/skills/write-document/SKILL.md

@@ -86,10 +86,36 @@ Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 5–16 | Navigation |
-| 18–24 | Sections intro |
-| 26–178 | README section templates (1–15) |
-| 180–183 | Verify |
+| 5–40 | Navigation |
+| 41–42 | Sections |
+| 43–54 | 1. Title + Badges |
+| 55–60 | 2. Tagline |
+| 61–64 | 3. Description |
+| 65–67 | 4. Prerequisites |
+| 68–75 | Prerequisites |
+| 76–78 | 5. Installation |
+| 79–89 | Installation |
+| 90–92 | 6. Usage |
+| 93–102 | Usage |
+| 103–105 | 7. Features |
+| 106–113 | Features |
+| 114–116 | 8. Configuration |
+| 117–125 | Configuration |
+| 126–128 | 9. Development Setup |
+| 129–139 | Development |
+| 140–142 | 10. Running Tests |
+| 143–152 | Tests |
+| 153–155 | 11. Contributing |
+| 156–164 | Contributing |
+| 165–167 | 12. Changelog |
+| 168–172 | Changelog |
+| 173–175 | 13. Links |
+| 176–181 | Links |
+| 182–184 | 14. License |
+| 185–191 | License |
+| 192–194 | 15. Credits (optional) |
+| 195–199 | Credits |
+| 200–202 | Verify |
 
 ## Sections
 
@@ -247,7 +273,7 @@ Detect from CLAUDE.md or project LICENSE file.
 ```markdown
 ## Credits
 
-Built with [bigpowers](https://github.com/danielvm-git/bigpowers).
+Built with [bigpowers](https://www.npmjs.com/package/bigpowers).
 ```
 
 ## Verify

package/.qwen/skills/align-grid/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: align-grid
+model: sonnet
+description: "Build editorial/magazine/report webpages on a GENUINE Müller-Brockmann modular grid (International Typographic Style) — not a decorative one. Encodes the discipline (columns + modules + baseline, grotesque type, flush-left, restrained black/white/red palette) AND the hard-won front-end engineering to make the grid real, visible, and verified: one CSS-variable source of truth, an interactive grid-toggle overlay that lives in the SAME content box as the content, subgrid \"bands\" so every element snaps to a column line, an 8px baseline lock, and runtime OPTICAL ALIGNMENT that puts display type's ink (not its box) on the line. Ships with a scaffold generator and a Puppeteer verification harness that proves 0px adherence."
+---
+
+# Müller-Brockmann Grid Systems — built real, visible, and verified
+
+Josef Müller-Brockmann (1914–1996), Zurich; *Grid Systems in Graphic Design* (1981) is the corpus. The grid is treated as an ethic, not decoration: **"The grid system is an aid, not a guarantee. It permits a number of possible uses and each designer can look for a solution appropriate to his personal style. But one must learn how to use the grid; it is an art that requires practice."** This skill encodes that discipline AND — the part most attempts get wrong — the front-end engineering to make the grid genuinely load-bearing on the web, plus a harness that PROVES it.
+
+> **HARD GATE** — Do NOT ship a grid page without running `verify_grid.js` first. A visually plausible layout is not evidence of grid adherence — the harness is. Zero failing assertions is the only passing bar.
+
+> Two real review notes this skill exists to prevent:
+> 1. *"the grid is just slapped on top and misaligned"* → the overlay wasn't in the same content box as the content (see §2.2).
+> 2. *"the H in the headline is off the grid"* → the headline's BOX was on the grid but its INK wasn't; large glyphs carry a side-bearing (see §2.6). **Box-on-grid ≠ ink-on-grid.**
+
+---
+
+## PART 1 — THE DISCIPLINE (decide before drawing)
+- **Objective order.** The grid brings "constructive thought," legibility, and "objective and functional" design. Restraint is the point; the system, not the ego, organizes the page.
+- **Modular grid.** Divide the type area into a field of **modules** — columns AND rows — separated by consistent **gutters**, inside defined **margins**. Text and images occupy whole modules. Müller-Brockmann specimens common field counts (8 / 20 / 32 fields). For the web, a **12-column grid + 8px baseline** is a robust general default; a **6×6 or 4×8 modular field grid** when you want visible rows too.
+- **Baseline grid.** Vertical rhythm is sacred: **leading = a whole multiple of the baseline unit**, and every element snaps to it. This is what makes facing columns and images line up across the page.
+- **Typography.** A **grotesque sans** (Akzidenz-Grotesk / Helvetica; on the web Inter, Helvetica Now, Archivo). **Flush-left, ragged-right.** Few sizes, large jumps in **scale** for hierarchy; objective, not expressive. Big **numerals/data set large** is a signature move.
+- **Palette.** Pure white paper, near-black ink, **one accent — red is canonical**. Avoid the warm-cream "Claude look"; **never blue/purple gradients** (hard house rule).
+- **White space + asymmetry.** Generous margins; asymmetric compositions held in tension by the grid.
+
+---
+
+## PART 2 — MAKE THE GRID REAL ON THE WEB (the load-bearing engineering)
+`grid_tokens.py` emits this whole scaffold correctly; the rules below are why it's built the way it is.
+
+### 2.1 One source of truth
+Put every grid parameter in `:root` CSS variables — `--cols, --gutter, --margin, --bl (baseline), --lh (leading=3×bl), --maxw`. **Content and the overlay both read these same variables.** Never hand-author the overlay separately or it will drift.
+
+### 2.2 The overlay MUST live in the SAME content box as the content  ← #1 bug
+Failure mode: content sits in a centered `max-width` container while the overlay is a **full-width sibling** of the section. On any viewport wider than `--maxw`, the centered content and the full-width overlay no longer share column positions → "slapped on top / misaligned."
+**Fix:** put `.guides` *inside* the same `.wrap`, and draw the column guides with `left/right = var(--margin)` and the **same** `repeat(var(--cols),1fr)` + `column-gap:var(--gutter)`. Then the overlay columns **are** the content columns at every width. Add left/right margin lines at `var(--margin)`.
+
+### 2.3 Place every element by column LINE via subgrid bands
+Don't eyeball spans. Each horizontal **band** spans all columns and re-exposes them:
+```css
+.band{grid-column:1 / -1; display:grid; grid-template-columns:subgrid; column-gap:var(--gutter); align-items:start;}
+@supports not (grid-template-columns:subgrid){ .band{grid-template-columns:repeat(var(--cols),1fr);} }
+```
+Children place with `grid-column: <startline> / <endline>` (e.g. `1 / 6`, `6 / 13`). Every headline, paragraph, photo, caption now snaps to identical lines.
+
+### 2.4 Lock vertical rhythm to the baseline
+- Leading = `--lh` (e.g. 24px = 3×8). **Every line-height a multiple of the baseline, in px (not unitless) for display type** — unitless line-heights on large type push the box off the grid.
+- Every margin/padding a multiple of the baseline. Spread top/bottom padding a multiple too, so content starts on a line.
+- **Media heights = multiples of the leading** (e.g. 240/360/432/480px) so a photo's top AND bottom both land on lines.
+- Hairline rules sit inside a baseline-height band, not free-floating.
+
+### 2.5 The toggle (sizzle within the sizzle)
+A control (button **+ `G` key**) toggles `body.grid-on`; overlay fades 0→1. Overlay draws: translucent **numbered column fields**, the **baseline** (major line every `--lh`, faint minor every `--bl`), and **margin lines**. Showing the real grid the page is built on IS the demo.
+
+### 2.6 OPTICAL ALIGNMENT — display ink, not its box  ← the subtle bug
+A 180px headline whose layout box is exactly on line 1 still looks misaligned against body text, because the letterform's **ink** is inset by its **left side-bearing**. Cure at runtime:
+```js
+// after document.fonts.ready and on resize:
+var cvs=document.createElement('canvas'),ctx=cvs.getContext('2d');
+document.querySelectorAll('.masthead,.numeral,.shead h2,.h2b').forEach(function(el){
+  el.style.marginLeft='0px';
+  var cs=getComputedStyle(el),ch=(el.textContent||'').trim()[0]; if(!ch) return;
+  if(cs.textTransform==='uppercase') ch=ch.toUpperCase();
+  ctx.font=cs.fontStyle+' '+cs.fontWeight+' '+cs.fontSize+' '+cs.fontFamily; ctx.textAlign='left';
+  var abl=ctx.measureText(ch).actualBoundingBoxLeft;     // +ve = ink overhangs left of box
+  if(isFinite(abl)) el.style.marginLeft=abl.toFixed(2)+'px'; // shift box so INK lands on the line
+});
+```
+Apply to the masthead, big numerals, and section headlines. It scales with fluid type (re-runs on resize) and uses the **actually-loaded** font, so it's correct in the user's browser.
+**CRITICAL measurement caveat:** side-bearing is **font-specific**. If you measure with the wrong font you get the wrong nudge. Headless/sandbox Chrome usually lacks the webfont, so canvas falls back to a different grotesque (measured **−16px on the fallback vs −7px on real Inter** for the same `H`). To verify optics offline you must **embed the real webfont** via `@font-face` (local TTF). In production the runtime JS measures the loaded font and is correct.
+
+---
+
+## PART 3 — VERIFY (don't trust, measure)  → `verify_grid.js`
+Render with headless Chrome (Puppeteer) and assert, at **several widths including > and < `--maxw`** (to catch centered-container drift, e.g. 1440 / 1180 / 900):
+1. **Column adherence** — every placed `.band > *` left snaps to a column START and right to a column END (~0px). **Exclude the optically-aligned display elements** from this box check (their box is intentionally side-bearing-offset; they're validated in step 4). **Gotcha:** build BOTH the column-start set and the column-end set — a grid item spanning "to line N" ends at the *far* side of the gutter, so single-edge math falsely reports a one-gutter error.
+2. **Overlay match** — each `.guides .col` rect equals the computed column rect (~0px).
+3. **Baseline** — text tops modulo the baseline ≈ 0 (tolerance ≈ half a baseline; the box-top is a proxy — the leading does the real work).
+4. **Optical ink** — each display element's ink-left (box − `actualBoundingBoxLeft`, real font) equals **its own** column line (nearest column-start to its box), not always line 1.
+
+Sandbox Chrome flags that work: `--headless=new --no-sandbox --disable-gpu --disable-dbus --use-gl=angle --use-angle=swiftshader`. `file://` works for non-ES-module pages; the CLI `--screenshot` can hang on tall pages — drive via Puppeteer and screenshot per viewport. Read PNGs back with the image-capable Read tool to eyeball a **zoom crop of the top-left corner** (masthead vs body vs column line) — the fastest human check.
+
+A clean run looks like: `col=0px overlay=0px baseline≤4px ink=0px` → `GRID VERIFY: PASS`.
+
+---
+
+## PART 4 — CRAFT DEFAULTS (so it looks excellent, not just aligned)
+- **Palette:** white `#fff`, ink `#111`, one accent (Swiss red `#e4002b`). No warm-cream Claude look; no blue/purple gradients.
+- **Type:** a real grotesque webfont (Inter / Helvetica Now / Archivo) for display + body; a **mono** (Space Mono / IBM Plex Mono) for folios, captions, grid annotations — reinforces the technical register. Non-Latin via Noto Sans JP etc.
+- **Hierarchy** through scale + weight + white space, not color. Treat key data as **large numerals**. Kicker labels in mono caps. Per-spread folios.
+- **Real photography.** Ground real subjects in real photos (`SearchImages`). **Host each image via `PublishFilePublicly` and embed the `pub.hyperagent.com` URL** — a `PublishWebpage` artifact runs in a sandboxed iframe that can't authenticate thread-scoped `/api/files/...` URLs (broken-image trap).
+- **Type fidelity if you ever rasterize art** (cairosvg / headless screenshots / image-gen reference): a `Helvetica`/`Arial` CSS stack silently falls back to **Noto Sans** (reads like Calibri). Render in **Liberation Sans** or an embedded Helvetica/Arimo TTF before trusting it. (Same trap as the optical-measurement caveat: wrong font in → wrong result out.)
+- **Spread model:** full-width sections, each its own per-spread `.grid` + `.guides`, consistent margins/folios.
+
+---
+
+## PART 5 — WORKFLOW
+1. Pick the subject; gather real photos; host them publicly.
+2. Generate the scaffold: `python3 grid_tokens.py` (or `--scaffold` for a full page; `--cols/--baseline/--gutter/--margin/--maxw/--accent` to taste; it warns if gutter/margin aren't baseline multiples).
+3. Build spreads as **subgrid bands**; place everything by **column line**; lock spacing/line-heights/media heights to the **baseline**.
+4. Add the overlay (same content box) + toggle + optical-alignment JS (already in the scaffold; point its selector list at your display elements).
+5. Publish, then **verify**: `CHROME=… PUP=… node verify_grid.js <file-or-url> --widths=1440,1180,900`. Eyeball a top-left zoom crop. Fix, republish.
+
+## SCRIPTS
+- **`grid_tokens.py`** — deterministic scaffold generator. Emits the `:root` tokens, `.grid`/`.band` (subgrid) scaffold, `.guides` overlay CSS, toggle JS, and the optical-alignment JS — all wired to one source of truth. `--scaffold` emits a full minimal HTML page. No network/credentials.
+- **`verify_grid.js`** — Puppeteer harness implementing all four checks above with the corrected both-edges column math, the optical-exclusion, per-element column-line ink targeting, and PASS/FAIL output at multiple widths. Env: `CHROME` (chrome binary), `PUP` (puppeteer-core module path).
+
+## CREED
+A grid you can't toggle on and measure is a mood board, not a system. Build it from one source of truth, prove it at 0px, and align the **ink**.