bigpowers 2.83.4 → 2.84.1

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

@@ -10,12 +10,12 @@ description: "CI pipeline setup with pre-built templates and local validation. G
 >
 > **HARD GATE** — CI that is untestable locally will break every cycle. Always run `--validate` after generating workflows and `--dry-run` before pushing.
 
-Generate, validate, and test CI workflows. Detects your project type, produces platform-appropriate GitHub Actions configurations, and provides local verification to catch auth, permissions, and syntax issues before they reach CI.
+Generate, validate, and test CI workflows. Detects your project type, copies org templates from `danielvm-git/.github/workflow-templates/`, and provides local verification to catch auth, permissions, and syntax issues before they reach CI.
 
 ## What this sets up
 
-1. **CI workflow** — `.github/workflows/ci.yaml` with test, lint, typecheck, build steps
-2. **Release workflow** — `.github/workflows/release.yaml` with semantic-release (if applicable)
+1. **Test Build Release workflow** — `.github/workflows/test-build-release.yml` with lint → test → build → release (single pipeline, `needs:` chain)
+2. **Deploy workflow** — `.github/workflows/deploy.yml` triggered via `workflow_run` (BigBase/Pages stacks only; CLI/library repos omit this)
 3. **`--validate` mode** — checks YAML syntax, workflow permissions, required secrets, and common pitfalls
 4. **`--dry-run` mode** — runs workflows locally via `act` or `gh workflow run` to prove correctness before push
 5. **Failure pattern documentation** — common CI failure categories and their fixes
@@ -24,45 +24,41 @@ Generate, validate, and test CI workflows. Detects your project type, produces p
 
 ### 1. Detect project type
 
-Read the project root for manifest files to determine which template to use:
+Read the project root for manifest files to determine which template pair to copy:
 
-| Manifest | Type | Template |
-|----------|------|----------|
-| `Cargo.toml` | Rust | Rust CI: test, clippy, fmt, build |
-| `package.json` | Node | Node CI: test, lint, typecheck, build |
-| `setup.py` / `pyproject.toml` | Python | Python CI: pytest, ruff/mypy/flake8, build |
-| `go.mod` | Go | Go CI: test, vet, staticcheck, build |
-| `CMakeLists.txt` | C/C++ | C/C++ CI: cmake build, ctest |
-| Multiple detected | Polyglot | Combined workflows or error if ambiguous |
+| Manifest | Type | Template pair (from `.github` repo) |
+|----------|------|-------------------------------------|
+| `Cargo.toml` | Rust | `test-build-release-monorepo.yml` + `deploy-monorepo.yml` (or monorepo subset) |
+| `package.json` | Node | `test-build-release-node.yml` + `deploy-node.yml` |
+| `setup.py` / `pyproject.toml` | Python | `test-build-release-python.yml` + `deploy-python.yml` |
+| `go.mod` | Go | `test-build-release-go.yml` + `deploy-go.yml` |
+| Static site (no server) | Static | `test-build-release-static.yml` + `deploy-static.yml` |
+| `Package.swift` | Swift | `test-build-release-swift.yml` only (no deploy yet) |
+| Multiple detected | Polyglot | `test-build-release-monorepo.yml` + `deploy-monorepo.yml` |
 
-If no manifest is found, prompt the user to specify the type or pass `--type <rust|node|python|go|cpp>`.
+**CLI/library repos** (no hosted target): copy only `test-build-release-<stack>.yml` → `test-build-release.yml`. The `release` job is terminal; skip `deploy.yml`. See `docs/how-to/migrate-ci-cd/migration-plan.md` § CLI and library repos.
 
-### 2. Generate CI workflow
+If no manifest is found, prompt the user to specify the type or pass `--type <rust|node|python|go|static|swift>`.
 
-Create `.github/workflows/ci.yaml` with standard steps derived from the project type and its manifest:
+### 2. Copy test-build-release template
 
-**Rust template (`Cargo.toml`):**
-See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md)
-
-**Node template (`package.json`):**
-See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md)
+Copy the matching template from `~/Developer/.github/workflow-templates/` to `.github/workflows/test-build-release.yml`. **Do not rename the workflow `name:` field** — deploy listens for `"Test Build Release"`.
 
-**Python template (`setup.py` / `pyproject.toml`):**
-See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md)
+Edit placeholders: `APP_TYPE`, `SITE_URL`, language versions.
 
-**Go template (`go.mod`):**
-See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md)
+See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md) for stack-specific job shapes.
 
-**C/C++ template (`CMakeLists.txt`):**
-See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md)
+### 3. Copy deploy template (hosted stacks only)
 
-### 3. Generate release workflow (if semantic-release detected)
+If the project deploys to BigBase or GitHub Pages:
 
-If the project has semantic-release configured (in `package.json`, `.releaserc`, or `release.config.js`), also generate `.github/workflows/release.yaml`:
+```bash
+cp ~/Developer/.github/workflow-templates/deploy-${STACK}.yml .github/workflows/deploy.yml
+```
 
-See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md)
+Configure `BIGBASE_SITE_ID`, `BIGBASE_DEPLOY_TOKEN`, and matching `SITE_URL`. Deploy runs via `workflow_run` after TBR succeeds on `main` with `cancel-in-progress: false`.
 
-> **NPM_TOKEN is required** for publishing to npm. Without it, semantic-release will fail at the publish step. See `--validate` to check this.
+Skip this step for CLI/library repos.
 
 ### 4. Validate workflows (`--validate`)
 
@@ -97,6 +93,8 @@ Add the following to the project's documentation or CLAUDE.md after setup:
 | `cargo clippy` errors | New lints in Rust nightly | `cargo clippy --fix` or allow specific lints |
 | `act` not found | Docker not running or act not installed | `brew install act` / `docker ps` to verify Docker |
 | Hardcoded Node version stale | `.nvmrc` exists but workflow uses hardcoded version | Use `node-version-file: .nvmrc` instead |
+| Deploy never runs | TBR workflow renamed | Keep `name: Test Build Release` in test-build-release.yml |
+| Release rebuilds binary | Artifact not downloaded | `release` job must `download-artifact` from `build` |
 
 ## Verify
 
@@ -120,26 +118,24 @@ Add the following to the project's documentation or CLAUDE.md after setup:
 
 ## Examples
 
-### Create CI for a Rust project
+### Create CI for a Go project (TBR + optional deploy)
 
 ```bash
-# Detect from Cargo.toml, generate workflows
-wire-ci
+# Copy org templates
+cp ~/Developer/.github/workflow-templates/test-build-release-go.yml .github/workflows/test-build-release.yml
+cp ~/Developer/.github/workflow-templates/deploy-go.yml .github/workflows/deploy.yml
 
-# Validate generated workflows
 wire-ci --validate
-
-# Run locally with act
 wire-ci --dry-run
 ```
 
-### Create CI for a Node project with semantic-release
+### Create CI for a CLI tool (TBR only, no deploy)
 
 ```bash
-wire-ci
+cp ~/Developer/.github/workflow-templates/test-build-release-go.yml .github/workflows/test-build-release.yml
+# Edit release job to download build artifact — see big-release dogfood
+
 wire-ci --validate
-# Expect warning: "npm publish step found but no NPM_TOKEN in secrets"
-# Fix: add NPM_TOKEN to repo secrets
 ```
 
 ### Validate existing workflows (no generation)
@@ -148,7 +144,6 @@ wire-ci --validate
 wire-ci --validate --check-only
 ```
 
-
 ---
 
 ## Options
@@ -160,8 +155,7 @@ wire-ci --validate --check-only
 | `--check-only` | Only validate, do not generate new files |
 | `--type <type>` | Force project type (skip auto-detection) |
 | `--force` | Overwrite existing workflow files |
-| `--no-release` | Skip release workflow generation even if semantic-release detected |
-
+| `--no-deploy` | Skip deploy.yml even for hosted stacks |
 
 ---
 
@@ -174,202 +168,191 @@ When `wire-ci` is used as part of `build-epic`:
 
 ---
 
-## Reference block 1
+## Reference block 1 — test-build-release.yml (Go, excerpt)
 
 ```yaml
-name: CI
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions-rust/toolchain@v1
-        with:
-          toolchain: stable
-          components: clippy, rustfmt
-      - run: cargo fmt --all -- --check
-      - run: cargo clippy -- -D warnings
-      - run: cargo test
-      - run: cargo build --release
-```
+name: Test Build Release
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
 
----
+permissions:
+  contents: read
 
-## Reference block 2
+concurrency:
+  group: pipeline-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
-```yaml
-name: CI
-on: [push, pull_request]
 jobs:
-  test:
-    runs-on: ubuntu-latest
+  lint:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
         with:
-          node-version: 20
-          cache: npm
-      - run: npm ci
-      - run: npm test
-      - run: npm run lint 2>/dev/null || true
-      - run: npm run typecheck 2>/dev/null || true
-      - run: npm run build 2>/dev/null || true
-```
-
----
-
-## Reference block 3
+          go-version: '1.22'
+          cache: true
+      - uses: golangci/golangci-lint-action@55c2c1448f86e01eaae002a5a3a9624417608d84  # v6.5.2
+        with:
+          version: v1.64.8
 
-```yaml
-name: CI
-on: [push, pull_request]
-jobs:
   test:
-    runs-on: ubuntu-latest
+    needs: [lint]
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
         with:
-          python-version: "3.12"
-          cache: pip
-      - run: pip install -e ".[dev]" || pip install -e .
-      - run: pip install pytest ruff mypy
-      - run: ruff check .
-      - run: mypy . 2>/dev/null || true
-      - run: pytest
-```
-
----
-
-## Reference block 4
+          go-version: '1.22'
+          cache: true
+      - run: go vet ./...
+      - run: go test ./... -count=1
 
-```yaml
-name: CI
-on: [push, pull_request]
-jobs:
-  test:
-    runs-on: ubuntu-latest
+  build:
+    needs: [test]
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
         with:
-          go-version: stable
+          go-version: '1.22'
           cache: true
-      - run: go vet ./...
-      - run: go test ./...
       - run: go build ./...
+      - run: jq -n --arg sha "${{ github.sha }}" '{sha: $sha}' > deploy-meta.json
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: deploy-meta
+          path: deploy-meta.json
+
+  release:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: [build]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        with:
+          fetch-depth: 0
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
 ---
 
-## Reference block 5
+## Reference block 2 — deploy.yml (BigBase, excerpt)
 
 ```yaml
-name: CI
-on: [push, pull_request]
+name: Deploy
+on:
+  workflow_run:
+    workflows: ["Test Build Release"]
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: deploy-production
+  cancel-in-progress: false
+
+env:
+  SITE_URL: "https://CHANGE-ME.bigbase.click"
+
 jobs:
-  test:
-    runs-on: ubuntu-latest
+  deploy:
+    if: >
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-22.04
+    environment: production
     steps:
-      - uses: actions/checkout@v4
-      - run: cmake -B build
-      - run: cmake --build build
-      - run: ctest --test-dir build
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: deploy-meta
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+          path: deploy-meta
+      - uses: danielvm-git/.github/actions/bigbase-deploy@9c56ac10c629f3baa110ddb19136579e3c90d690  # v1
+        with:
+          site_id: ${{ secrets.BIGBASE_SITE_ID }}
+          app_type: go
+          site_url: ${{ env.SITE_URL }}
+          deploy_token: ${{ secrets.BIGBASE_DEPLOY_TOKEN }}
+          ref: ${{ steps.meta.outputs.ref }}
+          skip_health_check: true
+      - name: Health check
+        run: |
+          curl -sf "${{ env.SITE_URL }}" || exit 1
 ```
 
 ---
 
-## Reference block 6
+## Reference block 3 — CLI dogfood (big-release pattern)
 
 ```yaml
-name: Release
-on:
-  push:
-    branches: [main]
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      issues: write
-      pull-requests: write
-      id-token: write
+  build:
+    needs: [test]
     steps:
-      - uses: actions/checkout@v4
+      - run: make build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v4
+          name: big-release-${{ github.sha }}
+          path: bin/big-release
+
+  release:
+    needs: [build]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
-          node-version: 20
-          cache: npm
-      - run: npm ci
-      - run: npm run build 2>/dev/null || true
-      - run: npx semantic-release
-        env:
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: \${{ secrets.NPM_TOKEN }}
+          name: big-release-${{ github.sha }}
+          path: bin
+      - run: make release   # cross-compile assets only; host binary from artifact
+      - run: big-release release --verbose
 ```
 
+No `deploy.yml` — CLI publishes via the release job.
+
 ---
 
-## Reference block 7
+## Reference block 4 — validate script
 
 ```bash
-# Validate YAML syntax
-for f in .github/workflows/*.yaml; do
+for f in .github/workflows/*.yml .github/workflows/*.yaml; do
+  [ -f "$f" ] || continue
   python3 -c "import yaml; yaml.safe_load(open('$f'))" || echo "FAIL: $f has YAML syntax errors"
 done
 
-# Check permissions block presence
-for f in .github/workflows/*.yaml; do
+for f in .github/workflows/test-build-release.yml; do
   if grep -q "permissions:" "$f"; then
     echo "OK: $f has permissions block"
   else
-    echo "WARNING: $f missing permissions block — add one for security"
-  fi
-done
-
-# Check for npm publish without NPM_TOKEN
-for f in .github/workflows/*.yaml; do
-  if grep -q "npm publish\|npx semantic-release" "$f"; then
-    if ! grep -q "NPM_TOKEN" "$f"; then
-      echo "WARNING: $f has npm publish/semantic-release but no NPM_TOKEN secret"
-    fi
+    echo "WARNING: $f missing permissions block"
   fi
 done
 
-# Check for hardcoded Node versions
-for f in .github/workflows/*.yaml; do
-  if grep -q "node-version: [0-9]" "$f" && grep -qv "node-version-file\|\.nvmrc" "$f"; then
-    echo "NOTE: $f has hardcoded Node version — consider using .nvmrc instead"
+if grep -q 'workflows: \["Test Build Release"\]' .github/workflows/deploy.yml 2>/dev/null; then
+  if ! grep -q 'name: Test Build Release' .github/workflows/test-build-release.yml; then
+    echo "WARNING: deploy.yml listens for Test Build Release but TBR name may differ"
   fi
-done
-
-# Check for common secrets reference errors
-for f in .github/workflows/*.yaml; do
-  # Secrets referencing something that doesn't exist in the workflow
-  grep -oP 'secrets\.\w+' "$f" | sort -u | while read -r secret; do
-    echo "REF: $f references $secret"
-  done
-done
+fi
 ```
 
 ---
 
-## Reference block 8
+## Reference block 5 — dry-run
 
 ```bash
-# Option A: Use act (recommended)
 if command -v act &>/dev/null; then
-  act push --dry-run
-  echo "OK: act dry-run completed"
+  act push --dry-run -W .github/workflows/test-build-release.yml
 elif command -v gh &>/dev/null; then
-  # Option B: Use gh workflow run (remote test, no local docker)
-  gh workflow run ci.yaml --ref "$(git branch --show-current)"
-  echo "OK: CI workflow dispatched. Check status: gh run list"
+  gh workflow run test-build-release.yml --ref "$(git branch --show-current)"
 else
-  echo "NOTE: Install act (https://github.com/nektos/act) for full local dry-run"
-  echo "      Install gh CLI for remote dry-run"
+  echo "Install act or gh for dry-run"
 fi
 ```

package/.trae/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**.