# docs/site stub-lockfile regenerate — kill the divergence trap

Every dependabot bump touching `docs/site` failed CI because the committed `package-lock.stub.json` was older than the bumped lockfile, and the workflow's fallback overwrote the new lockfile with the stale stub. Switching to on-the-fly regeneration removes 10k lines and the trap.

## The trap recurring failure

1. Dependabot opens PR bumping `docs/site/package.json` + `package-lock.json` (e.g., postcss 8.5.10 → 8.5.11).
2. CI: `npm ci` hits 401 on `@yonatan-hq/analytics` (Dependabot's reduced-scope token can't reach the private registry).
3. Workflow's fallback: `cp package-lock.stub.json package-lock.json` → overwrites the bumped lockfile with the committed stub (still pinned to 8.5.10).
4. `npm ci` retry: "Invalid: lock file's postcss@8.5.10 does not satisfy postcss@8.5.11".
5. PR blocked. Stub never auto-updates. Permanent divergence.

## Why the obvious fix was rejected (and how we got past it)

PR #1426 documented that `npm install --package-lock-only` "was tried and fails — this repo's `.npmrc` routes `@yonatan-hq` to a private registry that still 401s during resolution." That was true — but only when analytics was still pointing at the registry version. After we swap analytics to the local `file:` stub, no `@yonatan-hq` registry calls happen. Regeneration succeeds without NPM_TOKEN. Verified locally with `env NPM_TOKEN= npm install --package-lock-only --ignore-scripts`.

## Before vs. after

### Before (workflow + test)

    npm pkg set '...analytics=file:../stubs/analytics-stub'
    cp package-lock.stub.json package-lock.json
    npm ci --no-audit --no-fund

- Static stub diverges on every dep version
- Maintainer must manually regenerate stub for each bump
- 10,222-line lockfile committed to repo
- Trap fires silently — stub looks valid until npm ci compares

### After

    npm pkg set '...analytics=file:../stubs/analytics-stub'
    rm -f package-lock.json
    npm install --package-lock-only --ignore-scripts
    npm ci --no-audit --no-fund

- Lockfile regenerated fresh from current package.json
- No registry calls (analytics is file:; rest is public registry)
- `--ignore-scripts` prevents fumadocs-mdx postinstall from running before node_modules exists
- Dependabot bumps "just work" — no maintainer intervention

## Files changed

Path | Change
--- | ---
.github/workflows/docs.yml | Replace static cp + npm ci with regen + npm ci. Add explanatory comment block.
tests/unit/test-mdx-compile.sh | Same pattern: replace cp with regen, mirror the workflow.
docs/site/package-lock.stub.json | Deleted — 10,222 lines of obsolete state.

Net: +31 -10,239 — mostly the deleted stub

## Verification

- ✅ `env NPM_TOKEN= npm install --package-lock-only --ignore-scripts` in `docs/site/` after analytics swap → succeeds, regenerates clean lockfile resolving postcss 8.5.14 (latest)
- ✅ `bash tests/unit/test-mdx-compile.sh` on patched worktree → 256/256 mdx files compile cleanly
- ✅ `actionlint .github/workflows/docs.yml` → only pre-existing SC2086 info-level finding on unmodified lines
- 🔄 Post-merge: `@dependabot rebase` on #1630 → its CI should green for the first time, unblocking the chain

Unblocks PR #1630 (npm_and_yarn group bumps for non-root workspaces). Once #1630 lands, the rest of the dep chain (#1623 floor bump, #1628 cron snapshot refresh) can proceed.