Skip to main content
Thirty-one PRs, seven phases, one week. Forge docs caught up to Forge.

Hero

Summary

Forge docs had drifted six months behind the platform. The strategy plan from 2026-05-02 — IA reorganization, frontmatter contract, four CI gates, a fourteen-component visual library, eleven Tier 1 content deliverables — shipped end-to-end across thirty-one PRs in seven phases. Phases 2 and 3 were structural keystones and shipped solo to keep merge friction at zero; the rest parallelized. By Friday, the new sidebar spine renders, every page carries lastUpdated and appliesToVersion, and docs-coverage fails any public-surface PR that doesn’t update docs in the same change.

Highlights

Phase 1 — Surgical foundations (4 PRs)

  • Sync script: include snippets/
  • Voice guide
  • forge-docs-diagrams skill
  • docs-links CI

Phase 2 — IA reorganization (1 PR, solo)

  • Reorganize Forge platform + Console IA. Twenty-five file moves; nav.json full rewrites; placeholder index.mdx for every new directory.

Phase 3 — Frontmatter migration (1 PR, solo)

  • Frontmatter contract + migration. All 103 pages stamped with lastUpdated, appliesToVersion, audience, docType.

Phase 4 — CI infrastructure + component library base (4 PRs)

  • docs-coverage workflow
  • apps-docs-freshness workflow
  • Component library base + Forge palette
  • docs-lint workflow for inline-styled diagrams

Phase 5 — Advanced components, patterns guide, worldview (3 PRs)

  • Diagram patterns guide
  • Component library: advanced + Console components
  • How Forge Thinks worldview page

Phase 6 — Tier 1 content (18 PRs)

Architecture and concept pages:
  • Console and API architecture page
  • Workflow Architect authoring guide
  • Sandbox-as-Substrate architecture + build guide
  • Composable Capabilities concept + build guide
  • Tool Registry concept + Tool Sets reference
  • Console function reference (retired)
Console section Why + Tour pages:
  • Production (The Flame)
  • Observe (The Watchtower)
  • Trust Fabric (The Covenant)
  • Analytics (The Ledger)
  • Workforce (The Guild)
  • Chat (The Bell)
  • Platform (The Foundry)
Foundry sub-trees:
  • Tools sub-tree
  • Skills sub-tree
  • Agents sub-tree
  • Models sub-tree
  • Workflows sub-tree

What this means

The visual language is now a library — fourteen components covering every diagram pattern in the canonical four pages plus the Console-specific <ConsoleTour>, <ConsoleAnnotation>, and <ConsoleTaskCard>. New pages compose from the library; new patterns mean adding a component, not inventing one inline. The diagram-lint CI enforces this.The IA spine is the new shape — Start Here, Concepts, Build, Run, Architecture, Reference, Knowledge Base, Changelog, Troubleshooting, Contributing on the Forge platform side; the seven forge-themed sections plus Working With on the Console side.

What’s next

Phase 6 still has thirteen Console “Why” + “Tour” follow-ups (the ones that didn’t ship this week) and a handful of Tier 1 items that are code-driven and will land alongside their feature PRs. Phase 7 — Tier 2 polish — is open-ended and bandwidth-elastic; this changelog redesign is the third item on that list.
Plan tag: Forge Documentation Strategy — Phases 1–6 Tier 1.See also: Voice guide | Frontmatter contract | Diagram patterns | How Forge Thinks