Doc HTML
Doc HTML is one intake-form row that folds in two action-layer backend types behind an Upkeep / Create toggle. Upkeep (→ doc_upkeep) validates and updates an existing HTML documentation folder against both the live code and the documentation UI kit. Create (→ doc_create) generates new HTML documentation for a section or the full application using that same kit. Both are HTML-documentation-only actions, each its own standalone mini-orchestrator.
The form anchors this row on the real doc_upkeep code (relabelled “Doc HTML”) and adds a doc_mode sub-toggle: Upkeep (update existing) by default, switchable to Create (generate new). An effectiveType() resolver maps upkeep → doc_upkeep and create → doc_create; the two modes’ differing fields live inside the always-visible action-config section.
doc_revalidate type, which discovers and re-syncs a project’s whole documentation landscape across all formats (markdown prose, HTML sites, prompt/schema/config files) through the staged lifecycle. Reach for Doc HTML when the target is one HTML docs folder (Upkeep) or a new HTML docs set (Create); reach for doc_revalidate when you want the entire multi-format landscape re-validated at once.
The flow
Each mode runs its own action-layer mini-orchestrator outside the stage pipeline. Both first resolve and analyze the documentation UI kit from the committed pointer, then diverge: Upkeep surveys an existing folder before applying confined edits; Create plans an information architecture before fanning out page authors.
Upkeep — doc_upkeep
Upkeep reads the ## Action config, runs the read-only webkit analysis, validates the target is an HTML docs folder, then runs a read-only managed-loop survey (drift on two axes + page-structure logic). In apply mode it applies confined updates inside the target folder, validates, and writes the report; in report_only mode it skips the apply pass.
Create — doc_create
Create reads the ## Action config, runs the same webkit analysis, resolves the target plus CreationScope / SourceScope, plans the page/nav information architecture (an internal pass for full_app), fans out one page-author sub-agent per page, assembles the shared shell itself, validates, and writes the report.
What it is for
Pick the mode by whether the docs already exist:
- Upkeep when an HTML docs folder already exists and has drifted — from the code it describes, from the current UI kit, or both. It surveys the folder and (in
applymode) brings it back into agreement: fixing stale claims, adopting newly-recommended kit patterns, dropping deprecated usage, and correcting page structure. It produces updated HTML in place plus a findings report. - Create when there are no docs yet (or you want a fresh set) for a specific area (
section) or the whole application (full_app). It plans the structure, generates new HTML pages against the current kit, assembles a coherent shared shell, and produces the new files plus a run report.
Upkeep produces confined edits to an existing folder; Create produces new files in a target folder. Both always write 09_action/action-report.md.
audit Kind: doc_drift. The read-only audit sweep reports doc↔code drift without writing. Upkeep reuses that framing and adds the second (docs↔webkit) axis and a confined apply pass — it surveys, then fixes. See audit.
The logic
After pickup, the orchestrator reads JOB.md → Type and looks the row up in the registry. Both backend types are layer action, shape orchestrator: the orchestrator’s top-level route (orchestrator.prompt.md → §C.route) hands the job off to the matching action prompt and does not enter the stage pipeline. There is no clarify step — each action is defined entirely by its ## Action config. The job subfolder is 09_action/, and the orchestrator stays the sole PROGRESS.md writer and sole 4_done mover.
The intake form resolves the sub-toggle to a backend type before emitting the intake: Upkeep → doc_upkeep, Create → doc_create (the shared effectiveType() resolver in interface/intake-generator.js). Both remain distinct registry / closed-vocabulary types with their own prompts and routing — the merge is presentation-only.
The committed webkit pointer (D-55). Both actions resolve the documentation UI kit (name / agent_guide / manifest) from the doc agents’ own committed, gate-excluded pointer _processes/03_action/_shared/documentation-webkit.json — never from app.md. The kit is intrinsic to the doc HTML agents (the same kit whatever host app is being documented). A dedicated read-only webkit-analysis sub-agent fetches the live guide + manifest fresh each run and returns a reference packet that the orchestrator injects verbatim into every survey / apply / page-author sub-agent. Upkeep’s second mandate axis — docs↔current-webkit drift — is powered by that packet’s What changed / current best practice section.
The fields
Both modes carry no ## Stages, ## Approval gates, or ## Per-stage config — they are routed by layer/shape. Each JOB.md carries the header, an ## Action block, ## Git, and an optional mandate (free-prose notes/specs for the page authors). Git defaults off in both presets.
Upkeep — doc_upkeep
| Block | Field | Default | Notes |
|---|---|---|---|
## Action | TargetFolder | (required) | Repo-relative path to the HTML docs folder to govern. The agent refuses if blank — there is no “blank = whole app” default. |
| UpdateMode | apply | apply validates and applies confined updates; report_only is a dry run that writes findings without editing. | |
| Agents | claude | Selects the survey/write sub-agent runtime(s); add codex only when config.json → runtimes.codex is true. | |
| Depth | standard | quick | standard | deep — tunes how deep the survey reads. | |
| Consolidator | claude | Synthesises the per-section reports into 09_action/action-report.md. | |
## Git | Create branch | no | Off by default — edits sit in the working tree. Flip on per-job to land updates on a branch / commit / PR. |
| Validate against main | no | ||
| Commit | no | ||
| Push | no | ||
| PR | no | ||
| PR target branch | (blank) | Blank resolves to production. | |
| before_commit | no | Renders inside the Git section. | |
| before_pr | no | Renders inside the Git section. | |
# Mandate | Notes / specs | (optional) | Free prose flowing into the page authors’ guidance; empty is fine. |
Create — doc_create
| Block | Field | Default | Notes |
|---|---|---|---|
## Action | TargetFolder | (required) | Repo-relative destination. A brand-new docs-root is created only when CreationScope: full_app requests it and the parent folder exists; otherwise it must already exist. |
| CreationScope | section | section (default) documents one area; full_app documents the whole application. | |
| SourceScope | (free-form) | Which application area to document — required for section; the whole app for full_app. | |
| Agents | claude | Selects the page-author runtime(s); add codex only when config.json → runtimes.codex is true. | |
| Consolidator | claude | Synthesises the run report. | |
## Git | Create branch | no | Off by default — new docs sit in the working tree. Flip on per-job to land them on a branch / commit / PR. |
| Validate against main | no | ||
| Commit | no | ||
| Push | no | ||
| PR | no | ||
| PR target branch | (blank) | Blank resolves to production. | |
| before_commit | no | Renders inside the Git section. | |
| before_pr | no | Renders inside the Git section. | |
# Mandate | Notes / specs | (optional) | Free prose for the page authors (e.g. “preserve this existing set’s structure, re-render it in the kit”); empty is fine. |
How to run it
In the intake form, pick Doc HTML, set the doc_mode sub-toggle (Upkeep or Create), fill the mandatory target folder and the mode’s fields, and submit — that drops a contract-valid intake in jobs/0_new/. Then start the orchestrator by sending it the prompt path:
_processes/02_orchestrator/orchestrator.prompt.mdThe orchestrator bootstraps the intake, routes it as an action job, and runs the matching action prompt inline. To run an action prompt directly (when a job already exists in 2_ready/ / 3_ongoing/), send its path instead:
_processes/03_action/doc_upkeep/doc_upkeep.prompt.md_processes/03_action/doc_create/doc_create.prompt.mdThe run’s output lands in the target folder — updated HTML in place (Upkeep, apply mode) or new HTML files (Create) — with a summary at 09_action/action-report.md. With Git off (the preset default) the changes sit in the working tree for review.