From e0d4194869c8e93744ef38b9a20eb571f2cf02d4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 22 Feb 2026 20:44:31 +0100 Subject: [PATCH] docs: add missing summary/read_when metadata --- docs/experiments/plans/browser-evaluate-cdp-refactor.md | 3 +++ docs/experiments/plans/cron-add-hardening.md | 3 +++ docs/experiments/plans/openresponses-gateway.md | 3 +++ docs/experiments/plans/pty-process-supervision.md | 3 +++ docs/experiments/plans/session-binding-channel-agnostic.md | 3 +++ docs/gateway/configuration-reference.md | 4 ++++ docs/help/faq.md | 3 +++ docs/install/fly.md | 4 ++++ docs/pi-dev.md | 4 ++++ docs/pi.md | 4 ++++ docs/refactor/outbound-session-mirroring.md | 4 ++++ docs/security/formal-verification.md | 3 +++ docs/start/showcase.md | 3 +++ docs/tools/loop-detection.md | 1 + 14 files changed, 45 insertions(+) diff --git a/docs/experiments/plans/browser-evaluate-cdp-refactor.md b/docs/experiments/plans/browser-evaluate-cdp-refactor.md index 553437d62ee..5832c8a65e6 100644 --- a/docs/experiments/plans/browser-evaluate-cdp-refactor.md +++ b/docs/experiments/plans/browser-evaluate-cdp-refactor.md @@ -1,5 +1,8 @@ --- summary: "Plan: isolate browser act:evaluate from Playwright queue using CDP, with end-to-end deadlines and safer ref resolution" +read_when: + - Working on browser `act:evaluate` timeout, abort, or queue blocking issues + - Planning CDP based isolation for evaluate execution owner: "openclaw" status: "draft" last_updated: "2026-02-10" diff --git a/docs/experiments/plans/cron-add-hardening.md b/docs/experiments/plans/cron-add-hardening.md index 0ef55fda173..ec01a1574fa 100644 --- a/docs/experiments/plans/cron-add-hardening.md +++ b/docs/experiments/plans/cron-add-hardening.md @@ -1,5 +1,8 @@ --- summary: "Harden cron.add input handling, align schemas, and improve cron UI/agent tooling" +read_when: + - Debugging invalid `cron.add` payloads + - Aligning cron schemas across gateway, CLI, and UI owner: "openclaw" status: "complete" last_updated: "2026-01-05" diff --git a/docs/experiments/plans/openresponses-gateway.md b/docs/experiments/plans/openresponses-gateway.md index 4133940bdb4..7053c99846c 100644 --- a/docs/experiments/plans/openresponses-gateway.md +++ b/docs/experiments/plans/openresponses-gateway.md @@ -1,5 +1,8 @@ --- summary: "Plan: Add OpenResponses /v1/responses endpoint and deprecate chat completions cleanly" +read_when: + - Designing or implementing `/v1/responses` gateway support + - Planning migration from Chat Completions compatibility owner: "openclaw" status: "draft" last_updated: "2026-01-19" diff --git a/docs/experiments/plans/pty-process-supervision.md b/docs/experiments/plans/pty-process-supervision.md index 5f1c6534567..56bde263225 100644 --- a/docs/experiments/plans/pty-process-supervision.md +++ b/docs/experiments/plans/pty-process-supervision.md @@ -1,5 +1,8 @@ --- summary: "Production plan for reliable interactive process supervision (PTY + non-PTY) with explicit ownership, unified lifecycle, and deterministic cleanup" +read_when: + - Working on exec/process lifecycle ownership and cleanup + - Debugging PTY and non-PTY supervision behavior owner: "openclaw" status: "in-progress" last_updated: "2026-02-15" diff --git a/docs/experiments/plans/session-binding-channel-agnostic.md b/docs/experiments/plans/session-binding-channel-agnostic.md index 8804d8aea5c..aa1f926b36b 100644 --- a/docs/experiments/plans/session-binding-channel-agnostic.md +++ b/docs/experiments/plans/session-binding-channel-agnostic.md @@ -1,5 +1,8 @@ --- summary: "Channel agnostic session binding architecture and iteration 1 delivery scope" +read_when: + - Refactoring channel-agnostic session routing and bindings + - Investigating duplicate, stale, or missing session delivery across channels owner: "onutc" status: "in-progress" last_updated: "2026-02-21" diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index f9de696e8f6..50f40998ca1 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -1,6 +1,10 @@ --- title: "Configuration Reference" description: "Complete field-by-field reference for ~/.openclaw/openclaw.json" +summary: "Complete reference for every OpenClaw config key, defaults, and channel settings" +read_when: + - You need exact field-level config semantics or defaults + - You are validating channel, model, gateway, or tool config blocks --- # Configuration Reference diff --git a/docs/help/faq.md b/docs/help/faq.md index e60329e86c6..5c674258bf5 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1,5 +1,8 @@ --- summary: "Frequently asked questions about OpenClaw setup, configuration, and usage" +read_when: + - Answering common setup, install, onboarding, or runtime support questions + - Triaging user-reported issues before deeper debugging title: "FAQ" --- diff --git a/docs/install/fly.md b/docs/install/fly.md index 0e0745c1260..3b2ad9d9205 100644 --- a/docs/install/fly.md +++ b/docs/install/fly.md @@ -1,6 +1,10 @@ --- title: Fly.io description: Deploy OpenClaw on Fly.io +summary: "Step-by-step Fly.io deployment for OpenClaw with persistent storage and HTTPS" +read_when: + - Deploying OpenClaw on Fly.io + - Setting up Fly volumes, secrets, and first-run config --- # Fly.io Deployment diff --git a/docs/pi-dev.md b/docs/pi-dev.md index 2eeebdcc289..be95ead80cc 100644 --- a/docs/pi-dev.md +++ b/docs/pi-dev.md @@ -1,5 +1,9 @@ --- title: "Pi Development Workflow" +summary: "Developer workflow for Pi integration: build, test, and live validation" +read_when: + - Working on Pi integration code or tests + - Running Pi-specific lint, typecheck, and live test flows --- # Pi Development Workflow diff --git a/docs/pi.md b/docs/pi.md index 71eafb661fe..805f5e9eb45 100644 --- a/docs/pi.md +++ b/docs/pi.md @@ -1,5 +1,9 @@ --- title: "Pi Integration Architecture" +summary: "Architecture of OpenClaw's embedded Pi agent integration and session lifecycle" +read_when: + - Understanding Pi SDK integration design in OpenClaw + - Modifying agent session lifecycle, tooling, or provider wiring for Pi --- # Pi Integration Architecture diff --git a/docs/refactor/outbound-session-mirroring.md b/docs/refactor/outbound-session-mirroring.md index d30e9683eb1..1b8bdfcb186 100644 --- a/docs/refactor/outbound-session-mirroring.md +++ b/docs/refactor/outbound-session-mirroring.md @@ -1,6 +1,10 @@ --- title: Outbound Session Mirroring Refactor (Issue #1520) description: Track outbound session mirroring refactor notes, decisions, tests, and open items. +summary: "Refactor notes for mirroring outbound sends into target channel sessions" +read_when: + - Working on outbound transcript/session mirroring behavior + - Debugging sessionKey derivation for send/message tool paths --- # Outbound Session Mirroring Refactor (Issue #1520) diff --git a/docs/security/formal-verification.md b/docs/security/formal-verification.md index a45e63f3c11..ae650b5b7c2 100644 --- a/docs/security/formal-verification.md +++ b/docs/security/formal-verification.md @@ -1,6 +1,9 @@ --- title: Formal Verification (Security Models) summary: Machine-checked security models for OpenClaw’s highest-risk paths. +read_when: + - Reviewing formal security model guarantees or limits + - Reproducing or updating TLA+/TLC security model checks permalink: /security/formal-verification/ --- diff --git a/docs/start/showcase.md b/docs/start/showcase.md index f84c17fb876..347d8214cef 100644 --- a/docs/start/showcase.md +++ b/docs/start/showcase.md @@ -2,6 +2,9 @@ title: "Showcase" description: "Real-world OpenClaw projects from the community" summary: "Community-built projects and integrations powered by OpenClaw" +read_when: + - Looking for real OpenClaw usage examples + - Updating community project highlights --- # Showcase diff --git a/docs/tools/loop-detection.md b/docs/tools/loop-detection.md index 440047e8aa6..f41eeb0851b 100644 --- a/docs/tools/loop-detection.md +++ b/docs/tools/loop-detection.md @@ -1,6 +1,7 @@ --- title: "Tool-loop detection" description: "Configure optional guardrails for preventing repetitive or stalled tool-call loops" +summary: "How to enable and tune guardrails that detect repetitive tool-call loops" read_when: - A user reports agents getting stuck repeating tool calls - You need to tune repetitive-call protection