docs: sync code ↔ docs ↔ Mintlify site, add a Mintlify drift guard#108
Merged
Conversation
…uard The Mintlify site (mintlify/) is hand-maintained MDX that lived OUTSIDE the `docs check` reconciler, so it drifted several releases behind the code. This: - Adds `checkMintlify` to src/docs_check.js — every command must be documented on the English site as `forge <name>`, and any env var the site names must be one the code reads (no phantom vars). CI now catches Mintlify drift, the same way it already does for README/GUIDE. (Scoped to the English default locale; the site is a curated quickstart, so it is deliberately not a full env-parity check.) - Brings the English Mintlify site current: FORGE_LEDGER_ONLY default flip (env table + concepts), the problem-solver skill, the forge dash write guard (was "read-only"), the Labs (experimental) command group + corrected group memberships, the ledger-import framing, and version-neutral wording (was "new in v0.19"). - Fixes mintlify/docs.json: locale code `zh` aligned with its `zh-CN/` directory. - Updates top-level docs: ROADMAP (legacy-store retirement shipped), a stale `forge cortex` sample in GUIDE, and the ARCHITECTURE tool map + docs_check description. Full suite 1072 pass; biome/tsc green; `docs check` green including the new mintlify reconciler (verified it bites on an injected phantom var). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01C7htTiesXKLvAUtv6ET2jz
…ocales
Mirrors the English content corrections into ar/hi/cn/zh-CN/zh-Hans so the
translated sites stop stating things the code no longer does:
- Removed the stale "new in v0.19" framing (headings, inline tags, "landing in
the v0.19 line", quality descriptions) — commands are documented as available.
- Corrected the `forge dash` code comment (was "read-only"; the dashboard has two
guarded human writes).
- Fixed the `forge ledger import` comment ("bridge legacy stores" -> back-fill
pre-ledger history).
- Added the `FORGE_LEDGER_ONLY` row to every locale's environment-variable table
(ledger-only is the default; `=0` restores the legacy file store).
Identifiers (env vars, command names, code) stay literal; only prose is localized.
docs check stays green (the mintlify reconciler is English-scoped).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C7htTiesXKLvAUtv6ET2jz
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
CodeWithJuber
marked this pull request as ready for review
July 21, 2026 06:49
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The code, the top-level docs, and the Mintlify site (
mintlify/) had drifted apart.Root cause:
node src/cli.js docs checkreconciled README/GUIDE/ARCHITECTURE/ROADMAPagainst the code but had zero coverage of the hand-maintained Mintlify site, so it lagged
several releases behind.
Recurrence guard (the durable fix)
checkMintlifyreconciler insrc/docs_check.js: every command must be documented onthe English site as
forge <name>, and any env var the site names must be one the codereads (no phantom vars). CI now catches Mintlify drift the same way it does README/GUIDE.
Scoped to the English default locale (the site is a curated quickstart, so it is
deliberately not a full env-parity check — that exhaustive surface is GUIDE's job).
Verified it bites on an injected phantom var.
Content brought current (English + all translated locales: ar, hi, cn, zh-CN, zh-Hans)
FORGE_LEDGER_ONLYdefault flip — added to every locale's env table; theproof-carrying-memory / cross-session concepts now say the ledger is the default & sole
store (legacy
.md/fact files no longer written).forge dash— was labelled "read-only"; corrected (it has two guarded human writes),and the English page documents the CSRF/DNS-rebinding guard.
problem-solverskill — surfaced on the English site and inARCHITECTURE.md.Labs (experimental)command group + corrected group memberships to matchsrc/commands.js(English overview).forge ledger import"bridge legacy stores" comment.Top-level docs
ROADMAP.md(legacy-store retirement now shipped), a staleforge cortexsample indocs/GUIDE.md, theARCHITECTURE.mdtool map + docs_check description, andmintlify/docs.json(locale codezhaligned with itszh-CN/directory).Scope note
Identifiers stay literal in translations; only prose is localized. The deeper
explanatory-prose translation (e.g. a full dash-guard paragraph, the group-card restructure)
is left English-only for now — the factually-wrong content is corrected in every locale.
Checklist
npm testpasses (1072 pass / 0 fail / 2 gated skips)npm run checkpasses (Biome — 0 errors)CHANGELOG.mdupdated under## [Unreleased](also restores a dropped[0.27.1]header)node src/cli.js docs checkgreen, now including themintlifyreconcilerRisk & rollback
🤖 Generated with Claude Code
https://claude.ai/code/session_01C7htTiesXKLvAUtv6ET2jz
Generated by Claude Code