Merge pull request #108 from CodeWithJuber/claude/loop-goal-worktree-issues-il3uk9

docs: sync code ↔ docs ↔ Mintlify site, add a Mintlify drift guard

Author: CodeWithJuber

ARCHITECTURE.md

@@ -242,7 +242,11 @@ every intra-repo Markdown anchor (`#x` and `path.md#x`) against the target's rea
 version; and `checkCrosswalk` resolves every `.js`/`.sh` binding the research paper's
 crosswalk (`research/formal-synthesis/crosswalk.json`) claims for this repo against the
 files that actually exist in `src/`, `global/guards/`, and `hooks/` (kit-only names opt
-out with a `kit:` prefix), so the paper's stated bindings can no longer trail the code. The two public pages
+out with a `kit:` prefix), so the paper's stated bindings can no longer trail the code; and
+`checkMintlify` extends the reconcile to the hand-maintained Mintlify site (`mintlify/`,
+previously unchecked and prone to drift) — 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). The two public pages
 (`landing/index.html` + the `build-pages.mjs` status page) derive from ONE color source —
 `brand.json.colors` (full dark + light palettes), emitted as CSS by `src/brand.js`
 (`rootTokensCss()`). `test/pages.test.js` enforces full-palette parity: every hex in
@@ -363,6 +367,11 @@ self-correction` (rules) · project-layer template.
   **`forge init`** (one-command bootstrap) · **`cost-budget` guard** ·
   **Start-Here catalog** · **`recall`** unified memory subsystem.
 
+**Bundled skills (model-invoked, shipped in `global/tools/`):** beyond the reuse skills
+above, `problem-solver` (a framework-driven Clarify → Classify → Diagnose → Generate →
+Decide → Act cycle) and `catchup` (session re-orientation, pairs with `forge decide`) ship
+as native skills through the plugin's `skills` directory.
+
 ## `atlas` — the code graph
 
 `forge atlas build [path]` walks the tree and writes a **portable JSON artifact**,

CHANGELOG.md

@@ -6,6 +6,20 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changed
+
+- **Synced the docs with the code and added a Mintlify drift guard.** `docs check` now has
+  a `checkMintlify` reconciler that reconciles the hand-maintained Mintlify site
+  (`mintlify/`) against the code the same way it already does README/GUIDE — 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). The site had drifted (it was outside the
+  reconciler) and is now brought current: the `FORGE_LEDGER_ONLY` default flip, the
+  `problem-solver` skill, the `forge dash` write guard, the `Labs (experimental)` command
+  group, and version-neutral wording (was "new in v0.19"). Top-level docs updated too —
+  `ROADMAP.md` (legacy-store retirement now shipped), a stale `forge cortex` sample in
+  `docs/GUIDE.md`, and the `ARCHITECTURE.md` tool map (adds `problem-solver`/`catchup`).
+  `mintlify/docs.json` locale code `zh` aligned with its `zh-CN/` directory.
+
 ## [0.27.1] - 2026-07-21
 
 ### Security

ROADMAP.md

@@ -60,12 +60,14 @@ confidence only from independent oracles, and merges across teammates conflict-f
 
 ## Next
 
-- **Legacy store retirement** — the read-path flip has shipped: every read surface
-  (cortex injection/status, the substrate advisory, routing, `recall list`, brain's
-  AGENTS.md index) is now a merged view (legacy ∪ ledger) via `src/ledger_read.js`,
-  so teammate knowledge from `forge ledger merge` reaches injection. The legacy
-  formats (`lessons/*.md`, recall/brain fact files) are still written as the canonical
-  local state; the remaining step is retiring them so the ledger is the only store.
+- **Legacy store retirement** — mostly shipped. The read-path flip (every read surface —
+  cortex injection/status, the substrate advisory, routing, `recall list`, brain's
+  AGENTS.md index — is a merged view (legacy ∪ ledger) via `src/ledger_read.js`) landed
+  first, and the **write default has now flipped too**: `FORGE_LEDGER_ONLY` defaults on, so
+  the legacy formats (`lessons/*.md`, recall/brain fact files) are no longer written and the
+  ledger is the sole store. `FORGE_LEDGER_ONLY=0` is a one-release escape hatch that restores
+  the file store. The only remaining step is deleting the now-dormant legacy write/read code
+  once that escape hatch is removed in a later release.
 - **OpenAI + Gemini provider detection** — extend `autoDetectProvider()` beyond
   Anthropic/OpenRouter/LiteLLM (`OPENAI_API_KEY`, `GEMINI_API_KEY`) with the same
   guided, low-configuration auto-detect contract.

docs/GUIDE.md

@@ -653,7 +653,7 @@ Forge cortex — self-correcting project memory
 
   (no active lessons yet — Cortex learns from corrections as you work)
 
-  stored in .forge/lessons/ (git-committable, auditable)
+  stored in the .forge/ ledger (content-addressed, git-mergeable)
 ```
 
 `forge cortex why <symbol>` shows the lessons that would be injected when you touch it.
@@ -1040,7 +1040,7 @@ Plain `forge cost` remains the per-day spend view via `ccusage`.
 | `forge init`                     | Emit every tool's native config from one source.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `forge sync`                     | Recompile `source/` → each tool's files (idempotent).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `forge doctor`                   | Health check: layers, install, drift, cortex. `forge doctor --fix` auto-repairs the safely fixable findings (missing settings hooks/permissions, ledger union-merge rule, stale `AGENTS.md`, non-executable guards) by reusing the same idempotent functions `forge init`/`forge sync` use, then re-checks.                                                                                                                                                                                                                                                                                             |
-| `forge docs check`               | Docs↔code drift: commands, env vars, MCP tools, CHANGELOG reconciled against the code (CI-gated on the forge repo itself).                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `forge docs check`               | Docs↔code drift: commands, env vars, MCP tools, CHANGELOG, and the Mintlify site (`mintlify/`) reconciled against the code (CI-gated on the forge repo itself).                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `forge docs sync`                | Diff-driven stale-docs sweep: UPDATED / STALE (file:line hits) / VERIFIED-UNAFFECTED per artifact (see the full section above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `forge docs impact`              | Documentation-reference graph: extract typed entities (commands/flags/env/MCP/symbols/version), index every doc surface, and report which docs reference the entities THIS diff changed — ranked by confidence (see the full section above).                                                                                                                                                                                                                                                                                                                                                            |
 | `forge catalog`                  | Start-Here index of every tool / crew / guard.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

mintlify/ar/cli/config.mdx

@@ -34,7 +34,7 @@ forge cost --stages        # measured per-stage cost factors
 لوحة معلومات محلية فوق السجل والقياسات ونصف قطر الانفجار.
 
 ```bash
-forge dash                 # localhost-only, read-only (default port 4242)
+forge dash                 # localhost-only (default port 4242)
 ```
 
 ## `forge brand`
@@ -72,7 +72,7 @@ forge stack
 وأُطر العمل، ومديري الحِزم، وأوامر الاختبار **الفعلية** للمستودع — التي تُغذّي قائمة
 تحقق الركيزة.
 
-## `forge report` <sub>v0.19+</sub>
+## `forge report`
 
 توليد تقرير HTML ثابت عن حالة Forge للمستودع — السجل والقياسات ونصف قطر الانفجار
 مُصيَّرة في ملف مكتفٍ ذاتيًا يمكنك مشاركته أو أرشفته.
@@ -81,7 +81,7 @@ forge stack
 forge report
 ```
 
-## `forge tools` <sub>v0.19+</sub>
+## `forge tools`
 
 اختَر أداة الترميز الأساسية بالذكاء الاصطناعي لهذا المستودع، ووصِّل مدخلات `.gitignore`
 المطابقة، ليتم تجاهل الإعدادات المُولَّدة وقطع `.forge/` تجاهلًا صحيحًا لإعدادك.

mintlify/ar/cli/core.mdx

@@ -107,7 +107,7 @@ forge docs sync      # diff-driven stale-docs sweep
 ```bash
 forge update              # apply the update (git checkout or npm/copy install)
 forge update --check      # report whether a newer version is available
-forge update --to <version>   # pin or downgrade to a specific version (v0.19+)
+forge update --to <version>   # pin or downgrade to a specific version
 ```
 
 كل مسار يفشل بلطف — دون اتصال أو منبع أو رأس منفصل يُرجَع "غير معروف"، لا خطأ.

mintlify/ar/cli/memory.mdx

@@ -56,7 +56,7 @@ forge ledger query "<text>"        # retrieve by relevance
 forge ledger ratify <id>           # human accept
 forge ledger retract <id>          # tombstone a claim
 forge ledger merge <path>          # fold a teammate's ledger in, conflict-free
-forge ledger import                # bridge legacy stores into the ledger
+forge ledger import                # back-fill pre-ledger history into the ledger
 ```
 
 أضف `--personal` للحصول على سجل خاص بالمستخدم.
@@ -88,7 +88,7 @@ forge decide "<decision> — <reason>"
 forge decide                 # read the log before re-deciding
 ```
 
-## `forge know` <sub>v0.19+</sub>
+## `forge know`
 
 توجيه حقيقة إلى موطن تخزينها الصحيح — يقرر ما إذا كانت المعرفة تنتمي إلى
 `recall`، أو `remember`/`brain`، أو قرار، أو درس cortex، ويودعها هناك.
@@ -97,7 +97,7 @@ forge decide                 # read the log before re-deciding
 forge know "<fact>"
 ```
 
-## `forge deja` <sub>v0.19+</sub>
+## `forge deja`
 
 بحث عن أعمال سابقة مماثلة — يُظهر الأعمال السابقة في السجل التي تشبه ما توشك على
 عمله، لتعيد استخدام الإثبات بدلًا من التوليد من جديد.

mintlify/ar/cli/overview.mdx

@@ -49,15 +49,16 @@ description: "كل أمر من أوامر forge مُصنَّف حسب المجم
 | `FORGE_NO_HINT=1`         | كتم تلميح init المُعروض لمرة واحدة الذي يدفعك إلى تشغيل `forge init`.                                                                                                                       |
 | `FORGE_VERBOSE=1`         | إظهار عنوان الأمر (`Forge <cmd> — …`) المخفي افتراضيًا.                                                                                                                                     |
 | `FORGE_EMBED=1`           | تفعيل طبقة التضمينات لاسترجاع الذاكرة (يبقى MinHash افتراضًا بدون تبعيات).                                                                                                                  |
+| `FORGE_LEDGER_ONLY=0`     | منفذ هروب. وضع «السجل فقط» هو الافتراضي — تعيش الذاكرة في `.forge/ledger` فقط، ولم تعد ملفات `lessons/*.md` وملفات الحقائق القديمة تُكتب. اضبطه على `0` لاستعادة مخزن الملفات القديم. |
 
 <Note>
   شغّل `forge --help` للقائمة المحدَّثة دائمًا، أو `forge catalog` لفهرس البدء لكل
   أداة وطاقم وحاجز مع سبب موجز.
 </Note>
 
-## جديد في v0.19+
+## أوامر وعلامات أحدث
 
-عدة أوامر وعلامات تصل في خط v0.19. موثقة في صفحات مجموعاتها وموسومة داخل النص:
+هذه الأوامر والعلامات متاحة. موثقة في صفحات مجموعاتها وموسومة داخل النص:
 
 | الأمر / العلامة        | المجموعة | ماذا يفعل                                        |
 | ---------------------- | -------- | ----------------------------------------------- |

mintlify/ar/cli/quality.mdx

@@ -1,6 +1,6 @@
 ---
 title: "أوامر Quality"
-description: "التحقق والسلامة: verify وscan وspec وtaste وuicheck وharden — إضافةً إلى بوّابتَي precommit وradar في الإصدار v0.19+."
+description: "التحقق والسلامة: verify وscan وspec وtaste وuicheck وharden — إضافةً إلى بوّابتَي precommit وradar."
 ---
 
 مجموعة Quality هي سطح التحقق والسلامة. راجع
@@ -12,7 +12,7 @@ description: "التحقق والسلامة: verify وscan وspec وtaste وuich
 
 ```bash
 forge verify
-forge verify --deep       # multi-lens consensus (v0.19+)
+forge verify --deep       # multi-lens consensus
 ```
 
 يُبلِّغ `forge verify --deep` عن `status` رباعي الحالات بدلًا من نجاح/إخفاق ثنائي:
@@ -76,7 +76,7 @@ forge uicheck visual <file-or-url>   # Playwright-rendered check (opt-in tier)
 forge harden
 ```
 
-## `forge precommit` <sub>v0.19+</sub>
+## `forge precommit`
 
 بوّابة على مستوى الالتزام — تُشغّل الحد الأدنى للتحقق عند وقت الالتزام، فيُلتقط
 العمل الجزئي أو غير المُتحقَّق منه قبل أن يستقر.
@@ -85,7 +85,7 @@ forge harden
 forge precommit
 ```
 
-## `forge radar` <sub>v0.19+</sub>
+## `forge radar`
 
 حلقات حداثة التبعيات — تُجمِّع تبعيات المشروع بحسب مدى حداثتها، ليظهر ما هو بائت أو
 منحرف قبل أن يعضّ.

mintlify/ar/concepts/verification-gates.mdx

@@ -24,7 +24,7 @@ forge verify --deep       # multi-lens consensus — several independent checks
 ```
 
 <Note>
-  يُصعّد `--deep` (v0.19+) إلى إجماع متعدد العدسات: يجب أن يجتاز التغيير عدة عدسات
+  يُصعّد `--deep` إلى إجماع متعدد العدسات: يجب أن يجتاز التغيير عدة عدسات
   تحقق مستقلة، لا عدسة واحدة فقط.
 </Note>
 
@@ -92,7 +92,7 @@ forge harden               # gitleaks pre-commit + sandbox settings
 ## بوابة على مستوى الالتزام — `forge precommit`
 
 <Note>
-  `forge precommit` (v0.19+) هي بوابة على مستوى الالتزام (commit) — تُشغّل الحد الأدنى للتحقق
+  `forge precommit` هي بوابة على مستوى الالتزام (commit) — تُشغّل الحد الأدنى للتحقق
   وقت الالتزام حتى يُصطاد العمل الجزئي أو غير المُتحقَق منه قبل أن يهبط.
 </Note>