Handbook

Docs Health overlays

Forge Studio exposes three JSON feeds for documentation hygiene:

Topic · Updated

What it is

Forge Studio exposes three JSON feeds for documentation hygiene:

Docs Health overlay flow

How operators inspect documentation hygiene through read-only JSON feeds before opening mutation tooling.

  1. What it isStudio exposes three GET feeds for documentation hygiene signals.
  2. StartOperators open Docs Health when policy or handbook drift is suspected.
  3. Core steps (see walkthrough below)Verify each endpoint with GET-only checks from localhost.
  4. OutcomeConfirmed hygiene state without invoking mutation tooling.
Docs Health stays read-only until operators explicitly open mutation tooling
Method Path Purpose
GET /api/docs-health/summary Roll-up signal for dashboards (counts, repos in trouble).
GET /api/docs-health/work-items Queue of remediation issues with stable ids for agents.
GET /api/docs-health/live-sessions Who currently runs verification jobs vs which repo/checkout.

When to open the panel

  • After branching policy changes (docs-health-git-branch-policy.html in maintainer handbook).
  • When Cursor agents report divergent handbook copies — cross-check work-items payload before editing submodules blindly.

How to verify

  1. Hit each endpoint curl-style from 127.0.0.1 (matching server bind).
  2. Ensure summary counts reconcile with work-items → total (Studio cards already do this; duplicate check when customizing).
  3. For live audits, correlate live-sessions[].repo entries with Forge Fleet nodes if proxies are enabled.

Steps

Execute the numbered checks under How to verify above whenever you change branching policy or suspect stale caches.

Remediation tips live primarily in 12-troubleshooting.html; operator deep dives stay in the forge-lenses GitHub tree under docs/maintainer/ (not mirrored to the lightweight public handbook build).

Recover

If summaries disagree with work-items, restart Lenses after clearing stale caches — see Troubleshooting for Docs Health remediation loops.

What to do next