Documentation hydration agent

Use it when a chat transcript, field note, certification prep artifact, or strategy memo contains material that may become a ForgeSDLC post, Platform architecture note, Blueprints methodology update, product guide, or knowledge primer.

Design reference: Documentation hydration and rehydration design — seed Markdown shape, routing policy, promotion, and rehydration workflow.

Executive capsule

One CLI turns a single Markdown idea into per-surface documentation drafts, routing rationale, candidate claims, and a promotion checklist — all review-only. Nothing reaches a public site without a named human decision recorded in a reviewer decision manifest.

The problem this solves

Good material arrives as transcripts, memos, and analysis packs that never fit one repository. Manually splitting it across blog, architecture, methodology, and product docs is slow and inconsistent, so the material either duplicates or disappears. The agent does the splitting and routing deterministically; humans keep the judgment.

How it works

The agent parses seed frontmatter and body, scores each documentation surface by keyword and intent match, then renders per-surface drafts plus review artifacts (brief, checklist, claim inventory, route confidence). Everything lands under docs/hydration-runs/<slug>/ for review; promotion is a separate, manifest-gated step.

How it fits the ecosystem

The agent is the v1 deterministic core of the hydration pipeline. Around it: docs-governance/ registries track sources, content, and claims; scripts/detect_drift.py feeds the rehydration backlog; LCDL tasks may refine claim classification; forge-workcells hosts the workcell wrapper; Lenses is the review surface. See the design reference above for the full v2 layer.

What it produces

For each seed, the agent creates:

Generated drafts are marked with status: generated-draft. They are not canonical docs until a human copies an approved draft into the owning repository and runs that repository's normal build.

Run it locally

From the forge-platform repo:

python3 scripts/doc_hydration_agent.py samples/doc_hydration_seed.sample.md

By default, output goes to:

docs/hydration-runs/<seed-slug>/

To write somewhere else:

python3 scripts/doc_hydration_agent.py path/to/seed.md --out-dir /tmp/forge-doc-hydration

Seed shape

The input is Markdown with optional YAML-like frontmatter:

---
title: "Governed Delivery Control Plane, Not Generic Agent Orchestration"
status: "content-seed"
intended_uses:
  - article creation
  - blog post drafting
  - architecture documentation hydration
tags: [agentic-sdlc, governance, control-plane, positioning]
---

Seed body goes here.

The v1 parser supports the simple frontmatter forms used in Forge content seeds: quoted strings, inline lists, and indented string lists.

Routing policy

The agent follows Forge's source-of-truth split:

The deterministic router scores tags, intended uses, title text, and body excerpt. It proposes likely destinations; it does not prove that a destination is correct.

Human-oriented draft pattern

Every generated brief and draft follows this order:

1. User problem
2. Outcome
3. Forge mechanism
4. Trust boundary
5. Next action

This keeps drafts readable for human-facing documentation before they reveal deeper architecture or product mechanics.

Trust boundary

The hydration agent never promotes drafts automatically. Human review is required before copying content into canonical repositories because generated material may:

• overstate implementation readiness,
• route process guidance into a product narrative surface,
• route product-specific claims into Blueprints,
• omit required cross-links or build steps,
• invent claims that are not present in the source seed.

Before promotion, review promotion-checklist.md, verify source ownership, and run the affected site build.

Workcell path (v2, shipped)

The v1 CLI still works unchanged; the governed workcell path now exists alongside it:

1. An operator (or Lenses) creates a forge.workcell_request.v1 for doc_hydration_worker with the seed path in launch_pack.
2. forge-workcells runs the pipeline: deterministic claim extraction by default, or the governed forge-lcdl tasks (doc_claim_extraction, doc_risk_classification, doc_draft_expansion) with use_llm — outputs always stay candidate / review-only.
3. The worker returns a forge.workcell_result.v1 (ForgeRun frun_* id, status: needs_approval) plus hydration-brief.md and claim-inventory.json.
4. forge-lenses presents the review pack read-only (GET /api/doc-hydration/review-packs); the reviewer decision manifest is the approval record. Approval writeback from Lenses is a later increment (vision).
5. Promotion runs scripts/promote_hydration_pack.py --dry-run first and hard-fails without a valid manifest.

Envelope contracts and gates: workcell catalog.

Who this is for

Architects and platform engineers evaluating Forge (evaluate stage). Executives can stop after the core thesis; agents should honor the agent contract in the page frontmatter.

Evidence and maturity

Maturity: defined — this page records design intent captured from the Agentic SDLC standout analysis and reviewed for the platform handbook. Where behavior is shipped and observable it is called out explicitly; everything else should be read as direction, not commitment. Evidence trail: the hydration pack seed, the content registry entry for this content_id, and the claim registry entries linked via claim_ids.

How to use this page

• Evaluating Forge? Read the core thesis and ecosystem hooks, then continue with the standout index.
• Designing against the platform? Verify boundaries in the platform reference architecture before implementation.
• Automating? Use the frontmatter agent_contract and cite content_id in generated output.

Related

• Documentation hydration and rehydration design
• Workcell contracts
• Workcell catalog
• Platform reference architecture
• Autonomy levels

Agent contract

Allowed actions

• summarize this page for evaluation questions
• cross-reference claims via claim_ids and source_refs

Safe to infer

• the architectural boundary described here is the intended design

Do not infer

• production readiness beyond the stated maturity level
• specific vendor, customer, or benchmark commitments

Key artifacts

• forge-platform/docs-governance/content_registry.yaml

Machine-readable guidance from this page's frontmatter: what automated consumers may do, infer, and must not infer.