From ca9a04b271278525f4c328172835f45da95ff368 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Sun, 26 Apr 2026 23:56:53 -0700 Subject: [PATCH] docs: full-page readability pass on 5 worst-offender pages - automation/standing-orders: sentence-case all H2/H3 headings (Why Standing Orders, Anatomy, Execute-Verify-Report Pattern, Multi-Program Architecture, Best Practices, etc.) and clean up Related link styling - platforms/raspberry-pi: sentence-case 10 headings (Hardware Requirements, Performance Optimizations, Cost Comparison, etc.) - install/fly: sentence-case troubleshooting and Private Deployment headings - pi-dev: drop 'this guide summarizes' filler, sentence-case 4 H2 headings, restore brand-cased Pi - concepts/model-providers: sentence-case Kimi Coding (other brand-named providers preserved as-is: Google Gemini, Google Vertex, Kilo Gateway, Volcano Engine) --- docs/automation/standing-orders.md | 44 +++++++++++++++--------------- docs/concepts/model-providers.md | 2 +- docs/install/fly.md | 12 ++++---- docs/pi-dev.md | 10 +++---- docs/platforms/raspberry-pi.md | 20 +++++++------- 5 files changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/automation/standing-orders.md b/docs/automation/standing-orders.md index d5d533ca21d..438b1067604 100644 --- a/docs/automation/standing-orders.md +++ b/docs/automation/standing-orders.md @@ -11,7 +11,7 @@ Standing orders grant your agent **permanent operating authority** for defined p This is the difference between telling your assistant "send the weekly report" every Friday vs. granting standing authority: "You own the weekly report. Compile it every Friday, send it, and only escalate if something looks wrong." -## Why Standing Orders? +## Why standing orders **Without standing orders:** @@ -44,7 +44,7 @@ The agent loads these instructions every session via the workspace bootstrap fil Put standing orders in `AGENTS.md` to guarantee they're loaded every session. The workspace bootstrap automatically injects `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, and `MEMORY.md` — but not arbitrary files in subdirectories. -## Anatomy of a Standing Order +## Anatomy of a standing order ```markdown ## Program: Weekly Status Report @@ -54,7 +54,7 @@ Put standing orders in `AGENTS.md` to guarantee they're loaded every session. Th **Approval gate:** None for standard reports. Flag anomalies for human review. **Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm) -### Execution Steps +### Execution steps 1. Pull metrics from configured sources 2. Compare to prior week and targets @@ -62,14 +62,14 @@ Put standing orders in `AGENTS.md` to guarantee they're loaded every session. Th 4. Deliver summary via configured channel 5. Log completion to Agent/Logs/ -### What NOT to Do +### What NOT to do - Do not send reports to external parties - Do not modify source data - Do not skip delivery if metrics look bad — report accurately ``` -## Standing Orders + Cron Jobs +## Standing orders plus cron jobs Standing orders define **what** the agent is authorized to do. [Cron jobs](/automation/cron-jobs) define **when** it happens. They work together: @@ -97,7 +97,7 @@ openclaw cron add \ ## Examples -### Example 1: Content & Social Media (Weekly Cycle) +### Example 1: content and social media (weekly cycle) ```markdown ## Program: Content & Social Media @@ -106,13 +106,13 @@ openclaw cron add \ **Approval gate:** All posts require owner review for first 30 days, then standing approval **Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief) -### Weekly Cycle +### Weekly cycle - **Monday:** Review platform metrics and audience engagement - **Tuesday–Thursday:** Draft social posts, create blog content - **Friday:** Compile weekly marketing brief → deliver to owner -### Content Rules +### Content rules - Voice must match the brand (see SOUL.md or brand voice guide) - Never identify as AI in public-facing content @@ -120,7 +120,7 @@ openclaw cron add \ - Focus on value to audience, not self-promotion ``` -### Example 2: Finance Operations (Event-Triggered) +### Example 2: finance operations (event-triggered) ```markdown ## Program: Financial Processing @@ -129,7 +129,7 @@ openclaw cron add \ **Approval gate:** None for analysis. Recommendations require owner approval. **Trigger:** New data file detected OR scheduled monthly cycle -### When New Data Arrives +### When new data arrives 1. Detect new file in designated input directory 2. Parse and categorize all transactions @@ -138,7 +138,7 @@ openclaw cron add \ 5. Generate report in designated output directory 6. Deliver summary to owner via configured channel -### Escalation Rules +### Escalation rules - Single item > $500: immediate alert - Category > budget by 20%: flag in report @@ -146,7 +146,7 @@ openclaw cron add \ - Failed processing after 2 retries: report failure, do not guess ``` -### Example 3: Monitoring & Alerts (Continuous) +### Example 3: monitoring and alerts (continuous) ```markdown ## Program: System Monitoring @@ -162,7 +162,7 @@ openclaw cron add \ - Pending tasks not stale (>24 hours) - Delivery channels operational -### Response Matrix +### Response matrix | Condition | Action | Escalate? | | ---------------- | ------------------------ | ------------------------ | @@ -172,7 +172,7 @@ openclaw cron add \ | Channel offline | Log and retry next cycle | If offline > 2 hours | ``` -## The Execute-Verify-Report Pattern +## Execute-verify-report pattern Standing orders work best when combined with strict execution discipline. Every task in a standing order should follow this loop: @@ -181,7 +181,7 @@ Standing orders work best when combined with strict execution discipline. Every 3. **Report** — Tell the owner what was done and what was verified ```markdown -### Execution Rules +### Execution rules - Every task follows Execute-Verify-Report. No exceptions. - "I'll do that" is not execution. Do it, then report. @@ -193,7 +193,7 @@ Standing orders work best when combined with strict execution discipline. Every This pattern prevents the most common agent failure mode: acknowledging a task without completing it. -## Multi-Program Architecture +## Multi-program architecture For agents managing multiple concerns, organize standing orders as separate programs with clear boundaries: @@ -222,7 +222,7 @@ Each program should have: - Its own **approval gates** (some programs need more oversight than others) - Clear **boundaries** (the agent should know where one program ends and another begins) -## Best Practices +## Best practices ### Do @@ -243,8 +243,8 @@ Each program should have: ## Related -- [Automation & Tasks](/automation) — all automation mechanisms at a glance -- [Cron Jobs](/automation/cron-jobs) — schedule enforcement for standing orders -- [Hooks](/automation/hooks) — event-driven scripts for agent lifecycle events -- [Webhooks](/automation/cron-jobs#webhooks) — inbound HTTP event triggers -- [Agent Workspace](/concepts/agent-workspace) — where standing orders live, including the full list of auto-injected bootstrap files (AGENTS.md, SOUL.md, etc.) +- [Automation and tasks](/automation): all automation mechanisms at a glance. +- [Cron jobs](/automation/cron-jobs): schedule enforcement for standing orders. +- [Hooks](/automation/hooks): event-driven scripts for agent lifecycle events. +- [Webhooks](/automation/cron-jobs#webhooks): inbound HTTP event triggers. +- [Agent workspace](/concepts/agent-workspace): where standing orders live, including the full list of auto-injected bootstrap files (`AGENTS.md`, `SOUL.md`, etc.). diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md index f2fe80d9f44..44d1af45acf 100644 --- a/docs/concepts/model-providers.md +++ b/docs/concepts/model-providers.md @@ -367,7 +367,7 @@ Kimi K2 model IDs: } ``` -### Kimi Coding +### Kimi coding Kimi Coding uses Moonshot AI's Anthropic-compatible endpoint: diff --git a/docs/install/fly.md b/docs/install/fly.md index 90fa72d18c6..2c13a73330b 100644 --- a/docs/install/fly.md +++ b/docs/install/fly.md @@ -295,7 +295,7 @@ fly machine update --vm-memory 2048 -y **Note:** 512MB is too small. 1GB may work but can OOM under load or with verbose logging. **2GB is recommended.** -### Gateway Lock Issues +### Gateway lock issues Gateway refuses to start with "already running" errors. @@ -310,7 +310,7 @@ fly machine restart The lock file is at `/data/gateway.*.lock` (not in a subdirectory). -### Config Not Being Read +### Config not being read `--allow-unconfigured` only bypasses the startup guard. It does not create or repair `/data/openclaw.json`, so make sure your real config exists and includes `gateway.mode="local"` when you want a normal local gateway start. @@ -320,7 +320,7 @@ Verify the config exists: fly ssh console --command "cat /data/openclaw.json" ``` -### Writing Config via SSH +### Writing config via SSH The `fly ssh console -C` command doesn't support shell redirection. To write a config file: @@ -339,7 +339,7 @@ fly sftp shell fly ssh console --command "rm /data/openclaw.json" ``` -### State Not Persisting +### State not persisting If you lose auth profiles, channel/provider state, or sessions after a restart, the state dir is writing to the container filesystem. @@ -360,7 +360,7 @@ fly status fly logs ``` -### Updating Machine Command +### Updating machine command If you need to change the startup command without a full redeploy: @@ -377,7 +377,7 @@ fly machine update --vm-memory 2048 --command "node dist/index.js g **Note:** After `fly deploy`, the machine command may reset to what's in `fly.toml`. If you made manual changes, re-apply them after deploy. -## Private Deployment (Hardened) +## Private deployment (hardened) By default, Fly allocates public IPs, making your gateway accessible at `https://your-app.fly.dev`. This is convenient but means your deployment is discoverable by internet scanners (Shodan, Censys, etc.). diff --git a/docs/pi-dev.md b/docs/pi-dev.md index 8bf62bfea9e..d9cf6028d67 100644 --- a/docs/pi-dev.md +++ b/docs/pi-dev.md @@ -6,15 +6,15 @@ read_when: - Running Pi-specific lint, typecheck, and live test flows --- -This guide summarizes a sane workflow for working on the pi integration in OpenClaw. +A sane workflow for working on the Pi integration in OpenClaw. -## Type Checking and Linting +## Type checking and linting - Default local gate: `pnpm check` - Build gate: `pnpm build` when the change can affect build output, packaging, or lazy-loading/module boundaries - Full landing gate for Pi-heavy changes: `pnpm check && pnpm test` -## Running Pi Tests +## Running Pi tests Run the Pi-focused test set directly with Vitest: @@ -43,7 +43,7 @@ This covers the main Pi unit suites: - `src/agents/pi-tool-definition-adapter.test.ts` - `src/agents/pi-hooks/*.test.ts` -## Manual Testing +## Manual testing Recommended flow: @@ -56,7 +56,7 @@ Recommended flow: For tool call behavior, prompt for a `read` or `exec` action so you can see tool streaming and payload handling. -## Clean Slate Reset +## Clean slate reset State lives under the OpenClaw state directory. Default is `~/.openclaw`. If `OPENCLAW_STATE_DIR` is set, use that directory instead. diff --git a/docs/platforms/raspberry-pi.md b/docs/platforms/raspberry-pi.md index 7bd9c2713d6..43a5d5ec948 100644 --- a/docs/platforms/raspberry-pi.md +++ b/docs/platforms/raspberry-pi.md @@ -19,7 +19,7 @@ Perfect for: - Home automation hub - Low-power, always-available Telegram/WhatsApp bot -## Hardware Requirements +## Hardware requirements | Pi Model | RAM | Works? | Notes | | --------------- | ------- | -------- | ---------------------------------- | @@ -109,13 +109,13 @@ sudo sysctl -p ## 6) Install OpenClaw -### Option A: Standard Install (Recommended) +### Option A: standard install (recommended) ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` -### Option B: Hackable Install (For tinkering) +### Option B: hackable install (for tinkering) ```bash git clone https://github.com/openclaw/openclaw.git @@ -183,7 +183,7 @@ For always-on remote access, see [Tailscale](/gateway/tailscale). --- -## Performance Optimizations +## Performance optimizations ### Use a USB SSD (Huge Improvement) @@ -254,7 +254,7 @@ sudo loginctl enable-linger "$(whoami)" How `Restart=` policies help automated recovery: [systemd can automate service recovery](https://www.redhat.com/en/blog/systemd-automate-recovery). -### Reduce Memory Usage +### Reduce memory usage ```bash # Disable GPU memory allocation (headless) @@ -264,7 +264,7 @@ echo 'gpu_mem=16' | sudo tee -a /boot/config.txt sudo systemctl disable bluetooth ``` -### Monitor Resources +### Monitor resources ```bash # Check memory @@ -281,7 +281,7 @@ htop ## ARM-Specific Notes -### Binary Compatibility +### Binary compatibility Most OpenClaw features work on ARM64, but some external binaries may need ARM builds: @@ -306,7 +306,7 @@ uname -m --- -## Recommended Model Setup +## Recommended model setup Since the Pi is just the Gateway (models run in the cloud), use API-based models: @@ -356,7 +356,7 @@ free -h # Or reduce services running on the Pi ``` -### Slow Performance +### Slow performance - Use USB SSD instead of SD card - Disable unused services: `sudo systemctl disable cups bluetooth avahi-daemon` @@ -396,7 +396,7 @@ echo 'wireless-power off' | sudo tee -a /etc/network/interfaces --- -## Cost Comparison +## Cost comparison | Setup | One-Time Cost | Monthly Cost | Notes | | -------------- | ------------- | ------------ | ------------------------- |