docs: inventory operator contracts

[brokemac79]

Summary

• Publish a checked inventory of unauthenticated dashboard observer routes.
• Document the source-verified dashboard variables and workflow credential names identified by CSW-122, without exposing values.
• Extend documentation checks to prompts and repository agent skills.
• Add Bay-impact and documentation-lifecycle prompts to PR scaffolding and declare the repository's agent-instruction discovery strategy.

What Problem This Solves

The CSW-122 audit found implemented observer routes and deployed configuration names with no current operator inventory. It also found that prompts and .agents instruction surfaces were outside documentation checks, while mandatory Bay-impact and documentation-lifecycle evidence was absent from the pull-request template.

Why This Change Was Made

The operator manifest ties the public route list and methods to executable Worker routing, and ties the deliberately scoped audited configuration names to Wrangler and workflow usage. The two active references state their ownership and compatibility boundaries. Checker coverage and contributor scaffolding cover the remaining source-verified governance gaps without adding unverified aliases or claiming that observer routes are versioned APIs.

User Impact

Operators can find the current observer routes and audited configuration ownership in one place. Contributors receive the existing Bay and lifecycle requirements in the PR template, and drift in these checked contracts fails check:docs.

Reconciliation

• PR 1, docs: enforce current documentation lifecycle #1107, merged first as 2b5b345063efe1690e1d802fb1a738aa6a408707.
• This second-layer diff was replayed again as one commit onto current main f9a2f9493c2d96c1ef808484924e048386284d1c after feat(dashboard): prioritize operational telemetry #1113 merged.
• Current head: 4a7b547136a7e047aa0fcda531de410054ad2dc8.
• Open feat(scheduler): add adaptive scheduled hot-review allocation #1110, fix(queue): reconcile parked review items #1111, and feat(dashboard): make /bay canonical and clarify handoff telemetry #1112 were rechecked; merged feat(dashboard): prioritize operational telemetry #1113 touched only dashboard presentation/tests. None touches this PR's nine-file scope. Limits, scheduler, target-dispatcher, dashboard/runtime, and proof changes remain excluded.

Validation

• node --test test/check-docs.test.ts test/docs-site-theme.test.ts — 33/33 passed
• pnpm run check:docs — passed
• pnpm run check:limits — passed
• pnpm run build:all — passed
• pnpm run lint — passed
• pnpm run check:active-surface — passed
• pnpm run check:dashboard-queue-boundary — passed
• git diff --check origin/main...HEAD — passed
• Linux Crabbox oxfmt --check over the repository's complete configured surface — 650 files passed
• dirty-patch Codex review after current-main replay — clean after accepted fixes
• committed Codex review against origin/main — no actionable defect
• local ClawSweeper review --local-range --target-repo openclaw/clawsweeper --base origin/main at the current head — keep_open, medium confidence, no GitHub mutation

Review findings resolved

Accepted findings added deterministic coverage for method-aware routes, route/method pairing on one Markdown row, multiline and reordered guards, ignoring comments/templates, exact workflow-secret names, stale API table rows, multiple methods or paths in one condition, route-specific methods across Boolean branches, identical or conflicting duplicate manifest/table rows, workflow-secret extraction from executable GitHub expressions rather than inert YAML text, and method guards inherited by nested route conditions. One suggestion to require every repository workflow secret in this inventory was rejected as scope-expanding: this page intentionally covers the source-verified CSW-122 ownership gaps, while existing auth/runbook surfaces remain authoritative for other credentials.

Real Behavior Proof

Claim: The exact rebased head builds a 61-page documentation site containing both active operator references, and deterministic checks detect route/configuration/instruction drift without exposing non-current evidence as canonical.

Exercised surface: Exact pushed head 4a7b547136a7e047aa0fcda531de410054ad2dc8; production docs generator; generated llms.txt, sitemap, public API and configuration pages; TypeScript builds; all lint lanes; active-surface/dashboard-boundary/format/docs/limits checks; focused checker/site tests.

Scenario: A clean GitHub clone of the pushed branch was built in Docker-backed Crabbox. The proof asserted both new active pages are in canonical discovery, representative route/configuration names render, all focused positive/negative tests pass, and the repository-wide deterministic surfaces are clean.

Command/environment: Crabbox 0.40.0, required provider=local-container, image node:24-bookworm, --fresh-pr openclaw/clawsweeper#1108 --no-hydrate; the harness cloned and asserted the exact pushed branch. Docker Server 29.5.2.

Observed result: CSW122_PR2_HEAD=4a7b547136a7e047aa0fcda531de410054ad2dc8, 33/33 tests passed, 650-file format check passed, Documentation checks passed, CSW122_PR2_PROOF=PASS, exit 0.

Artifact/trace: Lease cbx_885ca7f11dfc (harbor-barnacle), provider local-container, image node:24-bookworm, runStatus=succeeded, command 25.218s, total 38.394s, lease stopped. Local harness: C:\clawsweeper-work\notes\csw-122-pr2-proof.sh.

Limits: This proves exact-head generation and deterministic contract checks in Linux. It does not deploy, probe authenticated or internal routes, validate secret values, or promise compatibility for diagnostic response schemas.

OpenClaw Bay Impact

No Bay runtime, data contract, artwork, or controls change. This PR documents existing observer projections and adds the existing Bay-impact requirement to contributor scaffolding.

Documentation Lifecycle

docs/public-api.md and docs/operator-configuration.md are active operator references with role owner, source, verified revision, update triggers, and checker. No proposed or historical page changes lifecycle.

Risks and Rollback

• New literal observer routes or removed audited names fail documentation checks until intentionally classified.
• The dependency-free route parser covers current executable equality guards plus tested Boolean combinations; a future routing abstraction should update the manifest/checker together.
• The Crabbox skill is link/path checked but exempt from repository package-script validation because it is a cross-repository wrapper with generic examples; the repository-local review skill remains fully checked.
• Rollback is a single revert; there is no runtime, deployment, queue, or data migration.

Non-goals

• No internal mutation route is documented as public.
• No secret value is read or recorded.
• No claim that the audited configuration list contains every repository credential.
• No Claude/Cursor alias or duplicated policy file is added; AGENTS.md explicitly documents the current strategy.
• No limits, scheduler, target-dispatcher, workflow, runtime, deployment, gate, queue, or state behavior changes.
• fix: keep branchless reviews durable during GitHub limits #1105's merged runtime/workflow/docs changes remain deliberately excluded.

Stack / Order

PR 1, #1107, is merged. This PR is now directly based on current main and contains only the intended CSW-122 second-layer operator/governance diff.

Related

• docs: enforce current documentation lifecycle #1107
• CSW-122 audit ledger: local maintainer artifact, not part of this repository

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[brokemac79]

@clawsweeper review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31421804097
• Updated: 2026-08-10T18:59:11.646Z

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 10, 2026, 5:50 PM ET / 21:50 UTC.

ClawSweeper review

What this changes

Adds checked operator documentation for dashboard observer routes and selected configuration names, extends documentation validation, and updates contributor guidance.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep this PR open for normal maintainer review. Current main does not contain its operator-documentation contract, and the current head resolves the previous executable-workflow-secret parsing blocker with focused coverage and exact-head proof.

Priority: P3
Reviewed head: 4a7b547136a7e047aa0fcda531de410054ad2dc8

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Strong exact-head proof and focused coverage support a normal maintainer review, with the parser's deliberately narrow routing grammar remaining the main bounded risk.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (live_output): The PR body provides a current-head fresh Crabbox local-container trace showing generated documentation and deterministic checks succeeding, with stated limits and no deployment claim.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (live_output): The PR body provides a current-head fresh Crabbox local-container trace showing generated documentation and deterministic checks succeeding, with stated limits and no deployment claim.
Evidence reviewed	5 items	Current branch remains distinct from main: The nine-file operator-documentation and checker change is absent from current main, so the PR still has a meaningful contribution. Prior parsing blocker resolved: Workflow credentials are now collected from parsed YAML string values and only from GitHub expression blocks; inert YAML comments are omitted by parsing, and a fixture covers comments plus ordinary literals. Regression coverage: The current head includes a focused fixture that requires an audited secret to become stale when it appears only in a workflow comment or inert literal.
Findings	None	None.
Security	None	None.

How this fits together

The documentation checker compares active operator references and a manifest with dashboard routing, deployment configuration, workflows, and repository instruction surfaces. It turns source/documentation drift into check failures while leaving runtime behavior unchanged.

flowchart LR
  A[Dashboard routes] --> D[Operator manifest]
  B[Deployment and workflow settings] --> D
  C[Agent and prompt docs] --> E[Documentation checker]
  D --> E
  E --> F[Operator reference pages]
  E --> G[Documentation check result]

Loading

Before merge

• Resolve merge risk (P1) - The route scanner intentionally understands the current literal equality-based Worker routing; a future routing abstraction must update the manifest, scanner, and focused fixtures together to avoid false documentation drift.
• Complete next step (P2) - No repair-lane work is needed: this is a coherent contributor PR awaiting ordinary maintainer review.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Checker coverage	production +372, tests +476 lines	The custom documentation-contract parsing is accompanied by larger focused regression coverage.
Patch scope	9 files affected	The change spans operator references, discovery configuration, contributor guidance, and their enforcing checker.

Merge-risk options

Maintainer options:

1. Accept the documented checker boundary (recommended)
   Merge with the current literal-routing parser boundary, requiring future routing abstractions to update the manifest and focused tests in the same change.

Technical review

Best possible solution:

Land the source-derived operator inventory with its narrow parser boundary and keep future route or workflow-expression changes paired with manifest and fixture updates.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is documentation and deterministic-check work; the PR supplies an exact-head generated-site and checker run as behavior proof.

Is this the best way to solve the issue?

Yes. A manifest backed by source checks and focused drift fixtures is a narrow maintainable way to keep these operator references current without changing Worker behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against f9a2f9493c2d.

Labels

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body provides a current-head fresh Crabbox local-container trace showing generated documentation and deterministic checks succeeding, with stated limits and no deployment claim.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is documentation and contributor-process infrastructure, not a runtime behavior change.
• merge-risk: 🚨 automation: The PR changes deterministic documentation-check behavior used by contributor and CI workflows.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body provides a current-head fresh Crabbox local-container trace showing generated documentation and deterministic checks succeeding, with stated limits and no deployment claim.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body provides a current-head fresh Crabbox local-container trace showing generated documentation and deterministic checks succeeding, with stated limits and no deployment claim.

Evidence

What I checked:

• Current branch remains distinct from main: The nine-file operator-documentation and checker change is absent from current main, so the PR still has a meaningful contribution. (scripts/check-docs.mjs:111, 4a7b547136a7)
• Prior parsing blocker resolved: Workflow credentials are now collected from parsed YAML string values and only from GitHub expression blocks; inert YAML comments are omitted by parsing, and a fixture covers comments plus ordinary literals. (scripts/check-docs.mjs:200, 4a7b547136a7)
• Regression coverage: The current head includes a focused fixture that requires an audited secret to become stale when it appears only in a workflow comment or inert literal. (test/check-docs.test.ts:758, 4a7b547136a7)
• Current-head behavior proof: The PR body records a fresh Crabbox local-container run for head 4a7b547: generated documentation, focused tests, documentation checks, and repository checks passed. (4a7b547136a7)
• Adjacent documentation-check ownership: The existing lifecycle/checker surface on main appears to date to the merged documentation-lifecycle work, providing a routing contact for this follow-up. (scripts/check-docs.mjs:86, 2b5b345063ef)

Likely related people:

• Martin Cleary: Authored the merged documentation-lifecycle change that established the current main documentation-check surface adjacent to this PR. (role: recent area contributor; confidence: medium; commits: 2b5b345063ef; files: scripts/check-docs.mjs, docs/README.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (5 earlier review cycles)

• reviewed 2026-08-10T18:57:35.019Z sha 825b847 :: needs maintainer review before merge. :: none
• reviewed 2026-08-10T19:52:50.352Z sha 825b847 :: found issues before merge. :: [P2] Retain the operational-health field-contract check
• reviewed 2026-08-10T20:48:54.203Z sha 5c539e6 :: needs changes before merge. :: [P2] Reject duplicate observer-route rows
• reviewed 2026-08-10T21:06:57.713Z sha f5361ed :: needs changes before merge. :: [P2] Parse only executable workflow secret references
• reviewed 2026-08-10T21:23:58.259Z sha fe71c87 :: needs changes before merge. :: [P2] Parse only executable workflow secret references

[brokemac79]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31430961115
• Updated: 2026-08-10T20:50:33.335Z

[brokemac79]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31432024141
• Updated: 2026-08-10T21:04:50.381Z

[brokemac79]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31433745728
• Updated: 2026-08-10T21:25:23.765Z

[brokemac79]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The item is closed; no stale verdict was published.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31436575204
• Updated: 2026-08-10T22:02:46.446Z

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: docs: inventory operator contracts This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.