Build full-coverage WordPress docs generation system

[chubes4]

Goal

Build a full-coverage WordPress documentation generation system that starts as an internal Automattic site and can later generate high-quality docs for WordPress Core, canonical plugins, and other products.

This is not a one-off generated page. The system should inventory source material, plan documentation coverage, generate source-backed pages through docs-agent, track provenance/review state, and publish a modern docs experience comparable to Next.js, shadcn/ui, Astro, and Laravel.

Canonical plan

Tracked in PR #3 and docs/full-coverage-generation-plan.md.

Architecture

Source repos
  -> source inventory extractor
  -> coverage map
  -> page specs
  -> docs-agent generation
  -> review and publish

Runtime path:

WP Docs runtime
  -> Data Machine / Data Machine Code
  -> DMC source checkouts such as wordpress-develop
  -> Automattic/docs-agent technical/user bundles
  -> GitSync checkout of chubes4/wp-docs
  -> generated content + provenance
  -> PR

Coverage dimensions

• Public PHP functions, classes, interfaces, traits, methods, and constants.
• Hooks, including actions, filters, dynamic hook families, parameters, and call sites.
• Blocks, block supports, block metadata, and editor behavior.
• REST API routes, controllers, schemas, permissions, and examples.
• Script Modules and classic asset APIs.
• Interactivity API and related packages.
• Options, constants, configuration files, and filesystem conventions.
• WP-CLI commands where applicable.
• Core subsystems: bootstrap, query, rewrite, users, roles/caps, cron, updates, media, editor, themes, plugins, HTTP, filesystem, database, and multisite.
• Tests and fixtures as behavioral evidence.
• Dev notes, make/core posts, handbooks, and existing docs as explanatory context.
• Deprecations, version history, and migration notes.

Milestones

• Merge the initial source/recipe/plan skeleton.
• Define content/_meta/page-spec.schema.json.
• Define content/_meta/ia.json for the initial WordPress docs IA.
• Build a WordPress Core coverage inventory from wordpress-develop.
• Generate page specs for the Script Modules vertical slice.
• Run docs-agent through the WP Docs runtime to generate Script Modules pages and provenance metadata.
• Submit generated output through GitSync as a reviewable PR.
• Add coverage dashboard/reporting so gaps are visible.
• Expand from Script Modules to one complete Core subsystem at a time.
• Add Gutenberg and canonical plugin source inventories.
• Generalize the same bundle model for other product documentation sets.

Success criteria

• Every source entity is documented, intentionally excluded, or mapped to a future page spec.
• Generated pages include source-backed claims and useful examples.
• Review status is visible at page and coverage-map levels.
• The internal WordPress site provides useful navigation and search before public publishing.
• The process can regenerate docs after upstream source changes without losing reviewed status.
• The architecture can be reused for WooCommerce, Jetpack, Studio, Playground, WP-CLI, Data Machine, and other products.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Drafting this tracking issue from the project discussion and committed full-coverage plan.

[chubes4]

Added focused follow-up issues for the untracked site/product work:

• Build Next.js-style docs shell #12 Build Next.js-style docs shell
• Add docs navigation, TOC, and Command-K search #11 Add docs navigation, TOC, and Command-K search
• Polish docs content rendering components #10 Polish docs content rendering components
• Generate first polished docs pilot section #13 Generate first polished docs pilot section
• Prove the Studio-to-Spacefast headless WP Docs workflow #14 Make wp-docs-runtime production-ready for prototype review

These split the previously untracked Next.js-docs-quality site work out from the broader generation-system umbrella.

[chubes4]

Architecture and tracking update (July 2026)

The WP Docs implementation is now split into two explicit lanes:

1. WordPress reference runtime and native generation path: Prove the Studio-to-Spacefast headless WP Docs workflow #14
2. Optional WPGraphQL headless web frontend: Prove replaceable headless docs frontends, starting with Blume #17

Upstream foundations are merged:

• Automattic/docs-agent#136 removes the legacy Data Machine package envelopes and makes the five Agents API-native packages the sole Docs Agent execution format.
• Extra-Chill/homeboy#8089 isolates executor attempts, propagates the authoritative workspace through the real provider boundary, preserves failed-attempt evidence, and repairs provider-boundary replay.

The resulting architecture is:

Docs Agent native package
  -> Agents API contract
  -> WP Codebox isolated execution
  -> Git documentation PR
  -> Markdown Database Integration
  -> WordPress
       -> wp-docs block theme
       -> WPGraphQL -> optional headless frontend

Data Machine is not a WP Docs runtime dependency. It remains a higher-level automation product that consumes Agents API when durable flows, schedules, queues, jobs, and retries are required.

The next proof gate is a clean Homeboy Lab cook linked to #14 with reviewer-resolvable commands and outcomes. Once the WordPress reference runtime is reproducible, #17 can add the headless renderer without changing generation, provenance, or review ownership.

[chubes4]

Product-direction correction after reviewing the latest Rich Tabor DMs

The authoritative goal is a focused, demonstrable product story: give an agent one prompt and receive a headless WordPress documentation site where humans and agents collaborate on the same canonical content.

The updated architecture is:

Source corpus
  -> Docs Agent
  -> WP Codebox
  -> Push MD Git remote and preview branch
  -> WordPress canonical content
       -> WPGraphQL -> Blume first, then other replaceable docs frontends
       -> MCP/Abilities -> agent actions
       -> wp-admin -> human editing and publishing

Corrections to the previous update:

• Push MD replaces Markdown Database Integration as the Git/Markdown boundary.
• Headless is the primary product direction, not an optional adapter after a block-theme reference implementation.
• The custom wp-docs block theme is planned for retirement after the headless acceptance gate is met.
• Blume is the first reference frontend; additional popular open-source docs providers follow over the same WPGraphQL contract.
• WP Docs is the proving fixture. The reusable output is the one-prompt setup recipe and frontend-neutral backend contract.

Updated trackers:

• Prove the Studio-to-Spacefast headless WP Docs workflow #14: one-prompt Push MD and WPGraphQL backend
• Prove replaceable headless docs frontends, starting with Blume #17: replaceable headless docs frontends, starting with Blume

Source context:

• One-prompt headless setup
• Tell an agent to set up a docs site
• Agents and humans work on the same content
• Core concept to prove
• Headless rebuild with open-source docs technology