Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

.agents/skills/technical-documentation/references/agent-and-contributing.md

@@ -0,0 +1,145 @@
+# AGENT and CONTRIBUTING Principles
+
+This reference consolidates the core rules for agent-policy and contributor-governance docs.
+
+You must:
+
+1. Discover repo-level and nested instruction files with:
+   `rg --files -g 'AGENTS.md' -g 'CONTRIBUTING.md' -g 'CLAUDE.md' -g 'AGENT.md' -g '.cursor/rules/*' -g '.cursorrules' -g '.agent/**' -g '.agents/**' -g '.pi/**' -g 'AGENTS.*.md'`
+2. Read the root and nearest-scope `AGENTS.md`/`CONTRIBUTING.md` pair before editing.
+3. If alias files exist, normalize to one canonical source (`AGENTS.md` preferred when present; otherwise nearest alias), plus compatibility pointers or explicit symlink notes.
+4. Document conflicting instructions and precedence decisions.
+
+## GitHub + AGENTS baseline
+
+Source: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
+Source: https://agents.md/
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+Source: https://cobusgreyling.substack.com/p/what-is-agentsmd
+Source: https://www.infoq.com/news/2025/08/agents-md/
+
+Use these as default operating principles:
+
+1. Keep `CONTRIBUTING.md` discoverable and actionable (`.github`, root, or `docs`).
+2. Keep agent instructions concrete: real commands, real paths, clear boundaries.
+3. Use explicit behavior boundaries for agents: `Always`, `Ask first`, `Never`.
+4. Keep contributor and agent rules aligned with actual repository workflows.
+5. Ensure clear guidance is provided to agents on if, when and how to raise issues and pull requests.
+
+## Canonical and alias policy
+
+Source: https://agents.md/
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+
+1. Treat `AGENTS.md` as canonical when present.
+2. If `AGENTS.md` is absent, treat the nearest alias file as canonical.
+3. Keep compatibility surfaces explicit: `AGENTS.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`.
+4. If aliases are used, document how they map back to canonical policy (or symlink when supported).
+5. When repos use `.agents/` as canonical rule storage, keep `.cursor` as a compatibility symlink to `.agents` for Cursor rule auto-loading.
+6. Keep policy DRY: store one shared policy core and expose it via aliases/symlinks instead of duplicating rule text.
+
+## Context-awareness by agent platform
+
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+
+1. For Cursor and Claude-style glob consumers, keep rule files narrow and bounded.
+2. Avoid over-referencing large path sets that inflate context for glob-based agents.
+3. For Codex-style workflows, prefer explicit file references and deterministic commands.
+4. Keep long runbooks outside top-level policy files; link to scoped docs.
+5. Ensure all agents have a happy path regardless so ensuring everything works across Codex, Claude and other coding agents.
+
+## Symlink and compatibility operations
+
+1. Preferred layout for multi-agent compatibility:
+   - canonical rule directory: `.agents/`
+   - Cursor compatibility path: `.cursor -> .agents` symlink
+   - canonical policy doc: `AGENTS.md` pointing to `.agents` paths where relevant
+2. Validate symlink state before finalizing changes:
+   - if `.agents/` exists and `.cursor` is missing, create `.cursor` symlink to `.agents`
+   - if `.cursor` is a symlink to another target, fix target or document why it must differ
+   - if `.cursor` is a real directory/file, treat as migration conflict and ask before replacement
+3. Validate rule payload through the canonical directory:
+   - rules: `.agents/rules/*.mdc` with valid frontmatter (`description`, `globs`, `alwaysApply` as needed)
+   - commands: `.agents/commands/*.md` when command routing is used
+   - MCP config: `.agents/mcp.json` when MCP is in scope
+4. Keep Codex behavior explicit:
+   - `AGENTS.md` is primary for Codex repository instructions
+   - `.cursor` compatibility is for Cursor auto-loading and does not replace canonical AGENTS policy
+5. Record applied symlink fixes and unresolved compatibility gaps in validation notes.
+
+## Dual-mode and deliverable standards
+
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+Source: https://agents.md/
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+
+1. Author one shared policy core (same commands, boundaries, and precedence) for all agents.
+2. For Cursor/Claude-style agents, expose that core through glob-driven and bounded files (small `AGENTS.md`/rule surface).
+3. For Codex, expose that same core through explicit file references with precise scope.
+4. Where styles diverge, prefer the smallest common structure that satisfies both and avoid duplicating policy text.
+5. Treat AGENTS/CONTRIBUTING as first-class deliverables when in scope.
+6. Preserve required structure, constraints, and examples from existing files.
+7. Align wording and commands with active repository instructions.
+
+## Proactive issue discovery and remediation
+
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+
+1. Run a conflict matrix review across AGENTS/aliases/CONTRIBUTING and related command/rule docs before finalizing.
+2. Treat the following as high-priority defects: missing referenced files, non-existent setup commands, command scope mismatches, and branch/commit policy conflicts.
+3. Do not stop at caveat-only notes when a low-risk fix is clear; apply the fix in the same pass.
+4. If a canonical entry file is missing (for example a directory `README.md` that docs depend on), create a minimal actionable file and update references.
+5. Long-running investigations are acceptable when needed to uncover cross-file drift, especially in agent-instruction ecosystems.
+
+## Discovery
+
+1. Agents prefer simple terminal commands so having a well defined `make *` or `npm run *` is ideal
+2. Agents can discover terminal commands through shell completion so providing shell completion helps
+
+## CONTRIBUTING size and scope control
+
+Source: https://contributing.md/how-to-build-contributing-md/
+Source: https://blog.codacy.com/best-practices-to-manage-an-open-source-project
+Source: https://mozillascience.github.io/working-open-workshop/contributing/
+Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md
+
+1. Keep root `CONTRIBUTING.md` focused on setup, issue flow, PR flow, testing, and review gates.
+2. Use issue/PR template links instead of embedding every process detail inline.
+3. When the file grows too large, split by domain and link from root.
+4. Move any large content into docs if avalible (for example Mintlify/Fern/Sphinx workflows) to avoid large contributor guide.
+5. Optimize for agent/machine readability as well as humans.
+
+## Example repos to emulate
+
+Source: https://github.com/openclaw/openclaw/blob/main/AGENTS.md
+Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md
+Source: https://github.com/openclaw/openclaw/blob/main/VISION.md
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+Source: https://github.com/processing/p5.js/blob/main/AGENTS.md
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+Source: https://github.com/agentsmd/agents.md/blob/main/AGENTS.md
+Source: https://github.com/rails/rails/blob/main/CONTRIBUTING.md
+Source: https://github.com/kubernetes/kubernetes/blob/master/CONTRIBUTING.md
+Source: https://github.com/atom/atom/blob/master/CONTRIBUTING.md
+Source: https://github.com/github/docs/blob/main/CONTRIBUTING.md
+Source: https://github.com/facebook/react/blob/main/CONTRIBUTING.md
+
+1. OpenClaw: strong real-world alias policy and AGENTS/CONTRIBUTING/VISION cohesion.
+2. OpenAI Codex: strict command discipline and explicit scope control.
+3. p5.js: explicit AI-policy guardrails in agent instructions.
+4. Vercel + agentsmd spec: compact, context-efficient AGENTS patterns.
+5. Rails/Kubernetes/Atom/GitHub Docs/React: contributor guidance patterns at different project scales.
+
+## Practical merge policy
+
+When these rules conflict:
+
+1. Preserve contributor and reader task success first.
+2. Preserve instruction clarity and unambiguous boundaries second.
+3. Preserve long-term maintainability and context-efficiency third.
+4. Add extra agent optimization only if it does not reduce human clarity or there is explict need.
+5. Use your judgement as the expert.

.agents/skills/technical-documentation/references/build.md

@@ -0,0 +1,116 @@
+# Build Docs Playbook
+
+Read `principles.md` first, then follow this execution flow.
+
+## 1. Detect and align agent instruction and governance instructions
+
+- Use `references/agent-and-contributing.md` as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling.
+- Apply the symlink compatibility policy when in scope (`.agents` canonical directory with `.cursor` compatibility symlink when required by tooling).
+- Long-running and extensive build investigations are acceptable when needed to resolve ambiguous or conflicting documentation sources.
+- When available, use sub-agents for bounded parallel inventory/cross-check tasks and merge results into one canonical decision set.
+- Capture required constraints before writing:
+  - nested-agent rules, command/test requirements, PR workflow, and style checks.
+- Use the same command and validation expectations in proposed snippets and examples.
+
+## 2. Inventory product documentation surfaces (not governance only)
+
+- For repo-wide builds, include docs content surfaces in addition to AGENTS/CONTRIBUTING.
+- Inventory docs files and frameworks in scope (examples): `README*.md`, `docs/**`, `**/*.md`, `**/*.mdx`, `**/*.mdc`, `**/*.rst`, `**/*.rsc`, Fern/Mintlify config, Sphinx `conf.py`.
+- Build a coverage map before drafting so governance and product docs are both represented.
+- If scope is ambiguous, default to broader docs discovery first, then narrow intentionally.
+
+## 3. Framework config and path mapping rules
+
+- Detect framework/config first (for example Fern config, Sphinx `conf.py`, Mintlify config, or equivalent).
+- Resolve every referenced path relative to the file/config that declares it, not assumed repo root.
+- Treat filesystem paths and published URL routes as separate mappings; do not infer one from the other without config evidence.
+- Validate both layers:
+  - config -> file exists on disk
+  - config/nav/routing -> URL path is consistent and reachable
+- Record path-mapping assumptions and mismatches in handoff (`missing file`, `stale route`, `wrong base path`).
+
+## 4. Define intent and success
+
+- Audience, prerequisites, and job-to-be-done.
+- Expected reader outcome immediately after completion.
+- Doc type: tutorial, how-to, reference, explanation.
+- Success criteria: what must be true after publish.
+
+## 5. Build structure before prose
+
+- Follow the funnel: what/why, quickstart, next steps.
+- Keep headings informative and scannable.
+- Open each section with the takeaway sentence.
+- Add decision points with concrete branch guidance.
+- For OpenClaw docs work, choose a page type from `references/openclaw.md` before drafting.
+- Keep task-critical OpenClaw configuration inline; link exhaustive defaults, enums, schemas, generated references, and rare debugging workflows.
+
+## 6. Build AGENTS.md and CONTRIBUTING.md intentionally
+
+- Keep AGENTS.md structure consistent with `agents.md` ecosystem patterns:
+  - include YAML frontmatter when present in repo style (`name`, `description`).
+  - state persona scope and explicit instruction boundaries: `Always`, `Ask first`, `Never`.
+  - include concrete commands and representative code examples.
+- For CONTRIBUTING.md, prioritize issue triage flow, PR expectations, setup/test commands, and review gates.
+- Add `Code of Conduct`, `Testing`, `Local checks`, and `PR expectations` sections when missing but required by the repo.
+- If CONTRIBUTING.md is becoming too large, split by scope into linked docs (for example, framework/tool-specific setup and release workflows) and keep the root file as a concise entry point.
+- Keep cross-file consistency: links from CONTRIBUTING.md to AGENTS.md (and vice versa) should be accurate and non-circular.
+- If multiple AGENTS.md files exist, document the directory-level scope and avoid conflicting advice.
+- If a required canonical entry file is missing (for example referenced `README.md` under a major directory), create the file in the same pass instead of adding a caveat-only note.
+- For new entry files, keep them minimal and actionable: purpose, prerequisites, concrete run commands, and pointers to deeper docs.
+
+## 7. Keep agent context tight
+
+- Author once, expose twice:
+  - keep one shared policy core and avoid duplicating guidance in separate agent-specific files.
+  - publish that core through bounded glob-friendly files for Cursor/Claude plus explicit path references for Codex.
+- For Cursor and Claude-style agents, avoid broad references. Use minimal globbing and narrow rule files that each serve one concern (for example, repo-wide setup, test rules, security checks).
+- Keep AGENTS and alias files short-to-medium; move detailed runbooks to linked docs.
+- For Codex, prefer explicit file references and concrete paths for exact reuse.
+- Avoid adding unrelated historical or process details to avoid token/context drift during future tool reads.
+
+## 8. Brownfield build mode
+
+- Match existing terminology, navigation, and component patterns.
+- Preserve existing IA unless there is a documented migration plan.
+- For rewrites, include a migration note from old to new paths.
+- Prefer smallest safe change set that improves utility.
+
+## 9. Evergreen build mode
+
+- Prefer stable concepts over release-tied narrative.
+- Isolate volatile details under clearly marked version sections.
+- Include maintenance signals: owners, refresh triggers, stale criteria.
+- Include lifecycle notes: deprecation and replacement paths.
+
+## 10. Writing constraints
+
+- Use precise language and short, imperative instructions.
+- Keep code examples copy-ready and self-contained.
+- Include common failure modes and safe defaults.
+- Avoid placeholder guidance that cannot be executed.
+
+## 11. Agent and automation readiness
+
+- Keep key facts in text (not image-only).
+- Prefer structured lists/tables when choices matter.
+- Add links and anchors that allow deterministic navigation.
+- Document what can be checked automatically in CI.
+
+## 12. Build validation
+
+- Validate commands and snippets where possible.
+- Verify links and references in changed sections.
+- Run a reference existence sweep for every path/command you introduced.
+- Verify docs-framework consistency when in scope (for example Sphinx/Fern config and referenced doc paths).
+- For OpenClaw docs work, apply the validation checklist in `references/openclaw.md`.
+
+## 13. Multilingual parity mode (when applicable)
+
+- Pick one source-of-truth language for technical accuracy and release timing.
+- Define parity target: full parity, staged parity, or intentional divergence per section.
+- Keep structure aligned across locales (headings, anchors, section order) when possible.
+- Preserve command/code correctness first; localize explanatory text second.
+- If parity is not feasible, add a visible note with missing scope and expected sync window.
+- Run a locale parity check for changed sections (added/removed steps, warnings, prerequisites).
+- Record unresolved checks explicitly in handoff.

.agents/skills/technical-documentation/references/openclaw.md

@@ -0,0 +1,128 @@
+# OpenClaw Documentation Overlay
+
+Use this reference only for OpenClaw docs work. It layers OpenClaw-specific page
+types, navigation, preservation, and validation rules on top of the general
+technical-documentation skill.
+
+## Reader Model
+
+- Lead with the task the reader is trying to complete.
+- Give one recommended path before alternatives.
+- Keep main docs focused on the common path; move dense contracts and rare
+  debugging detail to linked reference or troubleshooting pages.
+- Explain production risks exactly where the reader can make the mistake.
+- Link concepts, guides, references, CLI pages, SDK docs, testing, and
+  troubleshooting so readers can continue without rereading.
+
+## Page Types
+
+Choose the page type before writing or reviewing:
+
+- Overview: route readers to the right product area, integration path, or guide.
+- Quickstart: get a new user to a working result with the fewest safe steps.
+- Topic page: explain a major OpenClaw entity or surface end to end.
+- Guide: walk through one workflow from prerequisites to production readiness.
+- API/SDK/CLI reference: define every object, method, command, option, response,
+  error, enum, default, and version rule in scope.
+- Testing guide: show sandbox setup, fixtures, simulated failures, and live-mode
+  differences.
+- Troubleshooting guide: map observable symptoms to checks, causes, and fixes.
+- Governance file: keep agent/contributor policy concrete, scoped, and aligned
+  with current OpenClaw repo behavior.
+
+## Topic Pages
+
+Use this shape for major-entity pages:
+
+1. Title naming the entity or surface.
+2. Unheaded opening that says what it is, what it owns, and what it does not own.
+3. Requirements, only when setup needs accounts, versions, permissions, plugins,
+   operating systems, or credentials.
+4. Quickstart with the recommended path and smallest reliable verification.
+5. Configuration with task-critical options inline and exhaustive details linked
+   to reference docs.
+6. Major subtopics organized by reader intent, not under a generic "Subtopics"
+   heading.
+7. Troubleshooting with observable failures and concrete checks.
+8. Related links to guides, references, commands, concepts, and adjacent topics.
+
+## Guides
+
+Use this shape for workflow pages:
+
+1. Title naming the outcome, not the implementation detail.
+2. Opening that states what the reader can accomplish.
+3. Before you begin: accounts, keys, permissions, versions, tools, and
+   assumptions.
+4. Choose a path, only when the reader must decide.
+5. Steps with verb-led headings, commands, expected output, and checks.
+6. Test with the smallest reliable proof that the workflow works.
+7. Production readiness: security, retries, limits, observability, migrations,
+   and cleanup.
+8. Troubleshooting near the workflow that causes the failures.
+9. See also links to concepts, references, SDK docs, and adjacent guides.
+
+## Docs IA And Navigation
+
+- Read `docs/docs.json` before navigation changes.
+- Keep topic pages and common workflows on the main reader path.
+- Put exhaustive contracts, generated references, maintainer-only detail, and
+  support material under `Reference` or another clearly scoped support page.
+- Keep generated `plugins/reference/*` children and redirect-only pages out of
+  visible navigation unless explicitly required.
+- For moved pages, include a keep/drop/move/destination matrix in the handoff.
+- Add "Read when" hints for docs-list routing when creating or changing pages
+  that participate in the docs index.
+
+## Source-Backed Content
+
+- CLI docs must match current flags, output, errors, and examples.
+- API/SDK docs must include fields, defaults, enum values, constraints, nullable
+  behavior, lifecycle states, errors, and recovery guidance.
+- Config docs must align exported types, schema/help output, metadata, baselines,
+  and current docs.
+- Dependency-backed behavior must be verified from upstream docs, source, or
+  types before documenting defaults, timing, errors, or API behavior.
+- Separate current behavior, shipped behavior, planned behavior, and maintainer
+  intent.
+
+## Examples
+
+- Prefer complete copy-pasteable commands and snippets.
+- Use realistic variable names and values.
+- Mark placeholders with angle-bracket names such as `<API_KEY>`.
+- Show expected success output when it helps verification.
+- Keep one conceptual unit per code block and use language-specific fences.
+- Avoid examples that hide setup, auth, error handling, or cleanup.
+- Never expose real secrets, live config, phone numbers, private videos, or
+  credentials.
+
+## Preservation Reviews
+
+For rewrites or splits:
+
+- Identify source units before rewriting: headings, paragraphs, tables, examples,
+  CLI/API contracts, warnings, and troubleshooting facts.
+- Map each retained unit to a destination page or section.
+- Do not treat a broad "covered" row as proof for dense source material; use
+  line- or claim-level evidence when the source unit is dense.
+- For dropped content, state whether it is obsolete, duplicated elsewhere,
+  unsupported, or moved to a reference/support page.
+- When a docs-audit artifact is used, verify it is mapped audit data with
+  non-empty `mappings[]`, not only inventory or reindexed JSON.
+
+## Validation
+
+Choose the narrowest proof that covers the touched surface:
+
+- `pnpm docs:list`
+- `pnpm docs:check-mdx`
+- `pnpm docs:check-links`
+- `pnpm docs:check-i18n-glossary`
+- `pnpm format:docs:check` or `pnpm lint:docs`
+- `git diff --check`
+- generated-doc or inventory checks when generated references, plugin catalogs,
+  labeler, or docs scripts changed
+- behavior tests or command probes when docs claim runtime behavior
+
+If proof is blocked, say exactly which command was not run and why.

.agents/skills/technical-documentation/references/principles.md

@@ -0,0 +1,54 @@
+# Documentation Principles
+
+This reference consolidates the core rules used by this skill.
+
+## Matt Palmer: 8 rules for better docs
+
+Source: https://mattpalmer.io/posts/2025/10/8-rules-for-better-docs/
+
+Use these as default operating principles:
+
+1. Write for humans, optimize for agents.
+2. Start with a funnel: what/why, quickstart, next steps.
+3. Use Diataxis to scaffold content.
+4. Write with AI, but structure for agents.
+5. Offload routine docs operations to background agents.
+6. Automate quality with CI.
+7. Automate scaffolding and repetitive workflow tasks.
+8. Make contribution easy and visible.
+
+## OpenAI cookbook: what makes documentation good
+
+Source: https://cookbook.openai.com/articles/what_makes_documentation_good
+
+Key quality constraints:
+
+- Prefer specific and accurate terminology over niche jargon.
+- Keep examples self-contained and minimize dependencies.
+- Prioritize high-value topics over edge-case depth.
+- Do not teach unsafe patterns (for example, exposed secrets).
+- Open with context that helps readers orient quickly.
+- Apply empathy and override rigid rules when it clearly improves outcomes.
+
+## Practical merge policy
+
+When these rules conflict:
+
+1. Preserve reader task success first.
+2. Preserve structural clarity second.
+3. Preserve long-term maintainability third.
+4. Add agent optimization only if it does not reduce human clarity.
+
+For agent-instructions and contributor-governance specifics (AGENTS/aliases/CONTRIBUTING), use `references/agent-and-contributing.md` as the detailed additional source of truth.
+
+When the target repo or request is OpenClaw-specific, layer `references/openclaw.md` on top of these general rules. Otherwise ignore that repo-specific overlay.
+
+## Execution policy for this skill
+
+- Long-running and extensive investigations are allowed for both build and review work when needed to resolve ambiguity or cross-file drift.
+- Use sub-agents when available for bounded parallel discovery, verification, or cross-source comparison.
+- Keep one merged outcome: sub-agent outputs must be normalized into a single consistent recommendation/fix set.
+
+## Multilingual parity rule
+
+When docs exist in multiple languages, target cross-locale parity for task-critical content (steps, warnings, prerequisites, and limits). If full parity is not possible, publish explicit parity status and sync intent.

.agents/skills/technical-documentation/references/review.md

@@ -0,0 +1,121 @@
+# Review Docs Playbook
+
+Read `principles.md` first, then apply this checklist.
+
+## 1. Scope and classification
+
+- Identify doc type and target audience.
+- Confirm brownfield vs evergreen intent.
+- Confirm expected outcome for the reader.
+- For full-repo reviews, explicitly include both governance surfaces and product-doc surfaces (`docs/`, README trees, `.md/.mdx/.mdc`, `.rst/.rsc`, framework docs configs).
+- For OpenClaw docs reviews, apply `references/openclaw.md` for page type, docs IA, preservation, examples, and validation checks.
+
+## 2. Investigation behavior
+
+- Proactively find issues and risks without waiting for repeated prompts.
+- If there are signals of deeper problems, continue investigation beyond the first pass.
+- Long-running and extensive investigations are acceptable when needed for confidence and correctness.
+- When available, use sub-agents for bounded parallel discovery (for example file-inventory, command validation, or cross-doc consistency checks), then merge to one final issue set.
+- When no issues are found, state that explicitly and call out residual risks or validation gaps.
+- Default to `apply-fixes` for high-confidence documentation defects unless the user explicitly requests `report-only`.
+- Do not stop at AGENTS/CONTRIBUTING checks when the task is documentation-wide; continue into docs-content and docs-framework surfaces.
+
+## 3. Governance surface review
+
+- Use `references/agent-and-contributing.md` as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling.
+  For AGENTS.md:
+
+- confirm persona intent, scope, and command/tool boundaries are explicit.
+- check frontmatter style matches repo conventions when present.
+- ensure `Always`, `Ask first`, and `Never` boundaries are present when expected.
+- require concrete command examples and repo-specific paths to avoid ambiguity.
+
+For CONTRIBUTING.md:
+
+- verify issue/PR workflow is complete and actionable.
+- ensure local setup, lint/test commands, and review criteria are accurate.
+- ensure governance does not conflict with nested AGENTS instructions.
+- flag oversized files that should be split into linked section docs (for example tool-specific setup and release docs).
+
+For agent-platform awareness:
+
+- confirm references are minimal and scoped for Cursor/Claude glob behavior.
+- confirm Codex-facing guidance uses explicit file references.
+- confirm both surfaces represent the same shared policy core (commands, boundaries, and precedence), not divergent guidance.
+- audit `.agents`/`.cursor` compatibility behavior:
+  - verify canonical rule directory and symlink state match repo policy
+  - verify symlink target integrity and platform/tooling expectations
+  - verify AGENTS policy references remain canonical for Codex even when `.cursor` compatibility exists
+- check for context bloat from duplicated policy statements across agent and contributor files.
+- check for conflicting rules, skills and agent instructions
+- check for conflicting information in agent instructions vs codebase
+- check for broken or missing referenced files (for example README/index files named as canonical entry points).
+- check for setup/command drift (for example non-existent install commands, root-level commands that should be module-scoped).
+
+## 4. Product documentation surface review
+
+- Verify docs IA coverage across root/module `README*` files and `docs/**` trees.
+- Review framework-native docs sources in scope (for example Fern, Mintlify, Sphinx, MkDocs) and ensure guidance matches actual source-of-truth files.
+- Check `.md/.mdx/.mdc/.rst/.rsc` for stale commands, missing prerequisites, and broken cross-links.
+- Confirm referenced doc paths and anchors exist.
+- Flag docs that should be split/merged to improve discoverability and maintenance.
+- For OpenClaw docs, check `docs/docs.json`, docs-list routing hints, main path versus `Reference` placement, and generated-reference visibility.
+- For OpenClaw rewrites or page splits, require source-backed keep/drop/move/destination coverage for important claims, warnings, examples, commands, fields, and troubleshooting facts.
+
+## 5. Framework config and path mapping checks
+
+- Detect and read framework config first (for example Fern config, Sphinx `conf.py`, Mintlify config, or equivalent).
+- Resolve path references relative to the declaring file/config.
+- Treat filesystem paths and published URL routes as separate maps; verify both.
+- Flag path-map drift explicitly (`missing file`, `stale route`, `wrong base path`).
+
+## 6. Structural review
+
+- Funnel check: what/why, quickstart, next steps.
+- Validate heading flow and navigation discoverability.
+- Flag critical content trapped in images or buried sections.
+- Check Diataxis alignment and split mixed-purpose sections.
+- For OpenClaw docs, confirm the content matches an explicit page type from `references/openclaw.md`.
+
+## 7. Writing quality review
+
+- Check for concise, scannable paragraphs.
+- Remove ambiguous pronouns and undefined terms.
+- Verify examples are executable and scoped correctly.
+- Verify tone is directive, technical, and non-hand-wavy.
+
+## 8. Brownfield review mode
+
+- Verify compatibility with existing docs IA and conventions.
+- Verify anchors, redirects, and cross-doc links remain valid.
+- Flag regressions in onboarding and task completion paths.
+- Ensure changed terminology is intentionally propagated.
+
+## 9. Evergreen review mode
+
+- Flag date-stamped or brittle wording without version scope.
+- Check ownership and refresh signals are present.
+- Ensure recommendations remain valid after routine product evolution.
+- Flag missing deprecation/migration guidance.
+
+## 10. Tooling and platform review
+
+Read `tooling.md` if platform fit is uncertain.
+
+- Check whether content uses platform primitives effectively.
+- Flag structure that fights the chosen docs platform.
+- Recommend targeted platform-aware improvements.
+
+## 11. Multilingual parity review (when applicable)
+
+- Confirm declared source-of-truth language and expected parity policy.
+- Compare changed sections across locales for step/order/warning drift.
+- Flag missing updates to prerequisites, version notes, limits, and safety guidance.
+- Allow intentional divergence only when rationale is explicit and user-impact is low.
+- Require a reader-visible status note when locale parity is partial.
+
+## 12. Output format
+
+1. Blocking issues (file + required fix)
+2. Non-blocking improvements
+3. Validation notes (done vs pending)

.agents/skills/technical-documentation/references/tooling.md

@@ -0,0 +1,32 @@
+# Documentation Tooling Guide
+
+Source: https://www.mintlify.com/blog/top-7-api-documentation-tools-of-2025
+
+Use this file when deciding build/review expectations for doc platforms.
+
+## Tool-selection checkpoints
+
+- Existing stack lock-in: do not force migration for minor gains.
+- API workflow depth: generated references, OpenAPI support, testability.
+- Collaboration model: docs-as-code, review workflow, versioning.
+- Runtime quality: search, navigation, and copy-ready code snippets.
+- AI readiness: structured content, stable URLs, machine-friendly layout yet human readable.
+- Human readiness: reading complexity, reading UX, navigation depth, minimize jargon.
+
+## Apply in brownfield mode
+
+- Prioritize compatibility with the current platform.
+- Use available components and style conventions before introducing new patterns.
+- Propose migration only when current constraints block critical outcomes.
+
+## Apply in evergreen mode
+
+- Favor platforms and templates that make routine updates low-friction.
+- Standardize section templates to reduce drift.
+- Capture ownership, update cadence, and stale-content detection rules.
+
+## Review implications
+
+- Check whether content uses platform primitives correctly (tabs, callouts, endpoint blocks).
+- Flag docs that are technically correct but hard to scan in the chosen platform.
+- Recommend platform-specific improvements only when they reduce cognitive load.