Claw Planet Playbook¶

The everything-you-need page for working on claw.aguidetocloud.com — originally a plain-English study reference for the OpenClaw agent runtime (v0a, May 2026). Now a practitioner's field notebook for AI tools you can run, wire, script, compare, or operationally reason about (v0b, multi-vendor expansion 14 May 2026). Standalone planet · own physics · own visual system · own voice rules.

When this applies

Any code change in C:\ssClawy\claw-planet\. Any decision that changes IA, voice, design tokens, deploy flow, or content pipeline. Read the TL;DR + Multi-vendor expansion + Voice Guardrails + Verification States sections at minimum when picking up the project. The voice rules are not optional.

v0b · Multi-vendor expansion (set 2026-05-14)

The planet's scope expanded from "OpenClaw study reference" to "practitioner's field notebook for AI tools you can run, wire, script, compare, or operationally reason about." Same domain (claw.aguidetocloud.com), same [*] logo, same #FF2626 accent, same 3-grid layout, same voice rules — but now spans 5 vendors: OpenClaw · Anthropic · OpenAI · Google · Microsoft (builder-only · public sources only).

Why the expansion: Sush wanted a personal learning roadmap for cross-vendor AI tooling — Claude Code, Codex CLI, Gemini CLI, NotebookLM, Microsoft Copilot Studio + ATK, GitHub Copilot. Rather than spinning up a separate planet ("Forge"), the existing Claw planet absorbed the new scope because (a) nobody outside Sush was using it externally yet, (b) ~60-70% of content scaffolding would duplicate across two planets, (c) cross-vendor comparisons are the highest-value content and only work in one place, (d) Sush's mental model is one place for cross-vendor + open-vs-closed-source learning.

What stayed: domain, name "Claw" ([*] logo reads neutrally as "footnote/reference"), red accent, Astro 5 + MDX stack, voice-lint pattern, integrity-check, verification contract idea (now upgraded), OpenClaw as a protected named collection.

What's new in v0b:

IA shift to vendor-first with hub-and-spoke per vendor (each vendor lands on a hub page with product cards; each product gets sub-shape: CLI builder · hosted dossier · low-code platform · cloud platform).
Top tabs: [OpenClaw] · [Anthropic] · [OpenAI] · [Google] · [Microsoft] · [Compare] · [Updates].
Verification contract upgraded to structured test-context — verificationState enum widened to (planned · sourced · tried · verified · disputed); new optional verificationContext object captures tool · version · platform · accountTier · testedBy.
Content lifecycle = roadmap shape: Day 1 most entries are sourced (Copilot CLI researches public docs); Sush upgrades to tried as he experiments.
Microsoft slice = builder-only (ATK · Copilot Studio · Foundry · GitHub Copilot · Declarative Agents · MCP for Microsoft). Public sources ONLY. No customer engagement detail. Voice-lint enforces a source-citation check on Microsoft pages.
Scope guardrails (OUT list): no prompt-engineering articles · no model benchmark rankings · no AI ethics/regulation commentary · no general "what is AI?" explainers (Plain AI's lane) · no vendor PR reposts · no AI news/punditry · no customer engagement detail. Voice-lint enforces.
Positive inclusion gate: any new page must answer ≥1 of (install/run? · connect to files/repos/tools? · changes how Sush picks tools? · concrete privacy/security/operational decision? · tried or plan to try?).
Audience widened slightly — junior devs / new-to-AI builders welcome; jargon explained on first use.
Auto-crawl deferred to Phase 1.1 — Day 1 is heavily seeded sourced content (~70 new pages), automation comes after publishing rhythm proves out.
Phase 2 vendors (later): Meta/Llama · Mistral · xAI · Perplexity.

Build batches: Batch 0 (migration — schema, templates, vendor tabs, identity reframe) → Batch 0b (URL migration of 42 OpenClaw pages to /openclaw/* namespace · 301 redirects · 14 May 2026 commits 82853fd+ba65183) → Batch A (Anthropic, ~22 pages) → Batch B (OpenAI, ~20) → Batch C (Google, ~16, introduces hosted dossier) → Batch D (Microsoft, ~8) → Batch E (Compare + Updates seed) → Phase 1.1+ ongoing.

Working session plan: ~/.copilot/session-state/8f03bb76-8483-453f-ae5e-521d72bb712b/plan.md has the original plan; ~/.copilot/session-state/1563a663-73ac-42c5-84da-165da2884888/plan.md has the Batch 0b execution plan. SQL todos table tracks batch dependencies.

v0b · Batch 0b — URL migration SHIPPED (2026-05-14)

All 42 OpenClaw content pages moved from root URLs (/setup/, /overview/, …) to /openclaw/setup/, /openclaw/overview/, etc. The 5 vendor hubs (/openclaw/ /anthropic/ /openai/ /google/ /microsoft/), /compare/, and /updates/ stay at root.

Deploy bug caught + fixed mid-session: scripts/deploy.mjs (Direct Upload REST API, used because Wrangler is broken on win32-arm64) was uploading _redirects as a static asset at /_redirects instead of attaching it as Pages deployment metadata. Cloudflare served the file contents and never applied the rules. Fixed in commit ba65183 — control files (_redirects, _headers, _routes.json, _worker.js) are now extracted from dist/, excluded from the asset manifest, and attached as multipart/form-data fields on the createDeployment call (the way Wrangler does it automatically).

Lesson captured: any planet using a custom Direct Upload deploy script must handle _redirects/_headers as metadata, not assets. Wrangler hides this. Worth checking other planet repos.

Live verification: node scripts/smoke-check.mjs against production passes all 45 checks — 30 expect200 (foundation + hubs + section indexes + sample entries) + 15 expect301 (legacy URLs with correct Location target).

TL;DR — what's at stake¶

Site: claw.aguidetocloud.com (planned subdomain — confirm at deploy)
Repo: C:\ssClawy\claw-planet\ · GitHub susanthgit/claw-planet (created · empty at time of writing) · Cloudflare Pages project claw-planet (to create)
Stack: Astro 5 + MDX + React islands → Cloudflare Pages → custom domain (mirror Agentic Planet pattern)
Identity: Reference / study site · light + dark modes · plain English · OpenClaw red as accent · Inter + JetBrains Mono via Google Fonts CDN · sidebar TOC with §-numbered sections · definition-list catalogs · margin-notes column · field-note pattern with verification states · NOT a SaaS landing
Brand colour: #FF2626 (light) / #FF4747 (dark, slightly softened to reduce retinal strain)
Logo: Bracket Mark [*] — square brackets in ink, asterisk in OpenClaw red. Reads as "footnote · annotation · reference · code." Theme-aware via CSS classes.
Audience: Tech-savvy practitioners catching up on OpenClaw. Senior engineers, IT pros, infra people. Density allowed. The reader is Sush himself plus people like him.
Voice: Plain English. Honest take. Always explain with examples · scenarios · comparisons. Always answer "why does this matter" for important concepts. Quality over speed. No marketing voice. Forbidden words inherited from Agentic Planet voice-lint.
Build: Phase 1 split into P0a (soft launch under noindex) → P0b (public-credible launch) → P1 (deeper reference). Batch-by-batch — every batch ends with self-review, voice-lint, integrity check, smoke test, deploy.
Status (2026-05-10, end of Batch 13 UX rebuild): PUBLIC LIVE at https://claw.aguidetocloud.com, 42 pages, all INTEGRITY_LINK_THRESHOLD=0, mobile drawer works, home rebuilt as a navigational atrium that explains OpenClaw in plain English in the first paragraph, verification contract surfaced as a framed banner on every entry, section pages have a destination-feel hero with verification-mix counters, OG home image refreshed. Six new reusable components: MobileDrawer, ReadingPaths, SectionGrid, RecentUpdates, VerificationBanner, SectionHero.

Current snapshot — read first when picking up cold

Section	Pages target	Pages live	Verification mix
§1 Overview	4	4	4 sourced (Sush hasn't run OpenClaw yet)
§2 Setup	10	6	6 sourced (laptop · linux-server · azure · docker · raspberry-pi · hardware-matrix)
§3 Connections	5	5	5 sourced (channels · tools · models · memory · index-patterns)
§4 Plugins (field notes)	target 30	1	1 sourced (filesystem-mcp)
§5 Use cases (recipes)	target 15	5	5 sourced (hello-world-laptop · slack-real-work · whatsapp-faq · pi-home-agent · rag-personal-docs)
§6 Security	4	4	4 sourced (self-hosting-checklist · plugin-trust-signals · practical-patterns · what-not-to-build)
§7 Compare	target 10	1	1 deep matchup (vs MCP-based stacks)
§8 Updates (watchlist)	rolling	6 entries	single-page surface, JSON-driven (`src/data/updates.ts`)
§9 Resources	1	12 curated externals	single-page surface
§10 FAQ	target 20	8	single-page surface
Foundation	/methodology · /colophon · /about · /404 · /llms.txt · home	all 5	rebuilt home is the latest (Batch 13)
Cloudflare Pages project	—	claw-planet	id `c4044607-91bb-431f-935e-b85abe008e9a`
Custom domain	—	claw.aguidetocloud.com	Google CA · cert provisioned 2026-05-07
DNS CNAME	—	claw → claw-planet.pages.dev (proxied)	zone `8bf12b5f305f7b482dafa8059a0fe384`
GH Actions secrets	—	`CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID`	set via gh CLI
`noindex`	—	REMOVED on all routes except `/404/`	site is public-indexable since Batch 10
`INTEGRITY_LINK_THRESHOLD`	—	0 (permanent)	dropped 900→0 in Batch 10
Pagefind	—	active — ⌘K + click on search input + mobile search-icon button	4,133 words across 42 pages

Total pages live: 42. The home page is now a 4-block navigational atrium (Banner → ReadingPaths → SectionGrid → RecentUpdates) — replaced the prior 2,700px catalog dump in Batch 13.

Standalone planet — own physics

Like Agentic Planet, Claw Planet does NOT follow the Cosmos rules (no shared cosmos-config, no shared cosmos-nav, no cross-planet rail). Sush's standing decision: each planet is its own thing with its own visual system and own brand profile.

What it does share with the aguidetocloud.com family: - Sush's voice (plain English · honest take · Microsoft disclosure pattern · no monetisation · no email walls) - The deploy-via-Cloudflare-Pages pattern - The CI guardrails (voice-lint · integrity-check · smoke-check · audit-claims) - Cross-link from Agentic Planet eventually (Phase 4)

What it does NOT share with Agentic Planet: - Visual system (Agentic Planet is dark cockpit; Claw Planet is light/dark study reference) - Layout (Agentic Planet is dashboard-shaped panels; Claw Planet is sidebar + reading column + margin notes) - Typography (Agentic Planet is JetBrains Mono display + Inter body; Claw Planet is Inter throughout + JetBrains Mono for metadata) - Brand colour (Agentic Planet is indigo-cyan signal palette; Claw Planet is OpenClaw red) - Content pattern (Agentic Planet uses formal MCP scorecards; Claw Planet uses lighter "field notes" with dispute mechanism)

Origin story — how Claw Planet came about¶

6 May 2026. Sush asked an honest take on whether OpenClaw was worth pursuing. Initial recommendation framed it as a market positioning play — formal scorecards, CVE timeline, "trusted security voice" niche. Wrong read.

7 May 2026 (afternoon). Sush clarified: "What I am interested in is without me giving security reviews etc — I want an OpenClaw planet like Plain AI — just to teach concepts, components, skills, how to build, various setup methods, skills to use, what's changing, things to watch out, high level sec. All of this for personally me to learn and try and catch up on things like this and for people like me. Any SEO is bonus."

So the brief became a learning planet. Then refined further during the design session.

7 May 2026 (evening, this session). Across ~2.5 hours of design iteration, the brief sharpened:

Starter prompt said: reference + catalog site, 6 launch pages, V1 visual direction TBD
Sush expanded during session: "step 0 to hero" learner journey, multiple setup methods (laptop · Linux · Azure · Pi), connections, use cases — comprehensive
Sush re-clarified: not a learning platform, just a planet with tabs/places for each topic. Comprehensive on first load.
Initial mockup B (Topology Lab) with teal accents → Sush picked this direction
Colour shift: replaced teal with OpenClaw red (#FF2626)
Sush pushed back: "looks like a product site trying to sell something" — fair catch
Pivot to B3 (study reference layout): persistent sidebar TOC · §-numbered sections · definition-list catalogs · margin-notes column · no SaaS hero · home page IS the index
Polish round: web fonts (Inter + JetBrains Mono via Google Fonts), dark + light themes via [data-theme], narrower outer gutters, more main-column padding, all 10 sections rendered on home page, "Reading paths" hint in front matter, verification-states legend moved to top of margin column, "Reading aids" sidebar group visually subordinated
Logo design: 7 concepts, Sush picked Concept D — Bracket Mark
Name lock: "Claw Planet" stays (vs The OpenClaw Atlas, Claw Codex, Open Field — discussed)
Rubber-duck critique applied: Phase split into P0a (soft launch) → P0b (public-credible) → P1 (deeper). Verification states added to every applicable page. Plugin "reviews" renamed "field notes" with dispute mechanism. Sourced OpenClaw primitive map task added BEFORE content.

The repo susanthgit/claw-planet was created by Sush during the session. No code yet — playbook + plan + mockups are the deliverables of session 1.

The gap Claw Planet fills (one paragraph)¶

Most OpenClaw content online is one of: (a) official docs (exhaustive, dense, no opinion), (b) AI-generated SEO tutorials (worthless), (c) vendor blogs (NemoClaw pitch, not unbiased), (d) HN/Reddit threads (lottery), (e) academic security papers (impractical). There is no plain-English, opinionated, honest-take, study-shaped reference that says "here's what OpenClaw actually is, here's how to install it on whatever you own, here are the connections you'll plug in, here are the plugins worth knowing, here's what to watch out for." Claw Planet is that reference, written by someone learning the runtime in public.

Vision & guiding principles¶

#	Principle	What it means in practice
1	Sush is the reader	If Sush can use V1 to go from zero to running OpenClaw on his Raspberry Pi, V1 is doing its job. People-like-Sush are second.
2	Plain English always	Every concept explained with an example, a scenario, or a comparison. Never assume jargon is shared. The voice-lint runs on every push.
3	Quality over speed	No half-baked entries. No "we'll fix this later." If it's not ready, it stays as `status: draft` and doesn't appear in nav.
4	Honest about what's verified	Every applicable page declares whether we've actually run it. `tested-by-sush` · `tested-by-contributor` · `sourced-only` · `planned`. The page declares its state visibly.
5	Reference shape, not curriculum shape	Tabs and sections, not lessons. Visitors land where they want and scan. We don't gate progress.
6	Comprehensive map, not comprehensive library	First load shows ALL 10 sections. Each section may have 1 or 5 entries. Coverage grows. We're honest about counts.
7	Curated external is fine	We link to official docs, Awesome OpenClaw, key tutorials. We don't reinvent what others have done well.
8	No marketing creep	No CTAs. No "subscribe to continue." No email walls. No telemetry. No paid tier. Ever.
9	Microsoft disclosure when relevant	Sush works at Microsoft. Microsoft makes Azure. Inline disclosure on Azure-related pages. Footer disclosure on every page.
10	Disputable	Every plugin field note links to a dispute issue template. Plugin authors have a public right of reply.

Voice guardrails (LOCKED — Sush's preference, important)¶

These are not aesthetic preferences. They are how Sush's voice works. The site fails if these are not honoured.

Always do¶

Rule	Example
Explain with examples	Don't say "the agent has memory persistence." Say "if you tell the agent 'my project name is Claw Planet,' tomorrow it'll still know — because the runtime writes that to the memory backend you configured."
Explain with scenarios	Don't say "the channel layer routes messages." Say "you say 'remind me to deploy at 3pm' in Slack → the Slack connector hands the message to the agent → the agent stores it in memory → at 3pm it sends a Slack DM back."
Explain with comparisons	"OpenClaw's persistence is like running a Postgres server — it's there even when you're not using it. MCP-style is like opening a file with the right plugin — only alive while a host is asking."
Add "why it matters" for important concepts	After explaining what SOUL.md is, follow with: "Why this matters: SOUL is the file you'll edit when you want to change how the agent behaves long-term. If something feels off, this is where you debug character. Most config files ship as defaults — SOUL is the one you'll actually own."
Honest take	"We've not run this on a Pi yet — sourced from openclaw.dev/docs. Likely works; verify the network step before relying on it."
Plain English	"Plugins" not "extensible capability surfaces." "Set up" not "provision the deployment topology." "Watch out" not "carefully consider operational implications."
Last-reviewed dates	Every applicable page has `lastReviewedAt` visible to readers and machine-readable in frontmatter.
Source citations	Where we sourced from docs, link them. Where we ran something ourselves, say so.

Never do¶

Forbidden words (voice-lint hard-fails on roadmap docs, advisory on public content):

frontier · ecosystem · multimodal · agentic capability · in layman · AI-powered · robust · scalable · holistic · synergies · game changer · mission-critical · moat · differentiator · SEO magnet · flagship

Forbidden patterns: - CTAs disguised as content ("Get started today!" · "Discover more" · "Take action") - Persona-targeting ("for builders · for engineers · for CIOs") — just write to the reader - "Comprehensive guide" / "complete reference" / "everything you need" — we're a living map, never claim completeness - Vendor-sponsored language ("powered by · built for · engineered with") - Hype framing ("revolutionary · cutting-edge · next-generation") - Fake urgency ("only · limited · don't miss")

Voice tests before publishing¶

Mum test — could Sush's mum read the first paragraph and have a vague sense of what OpenClaw is? (Title and lead must be plain enough to clear this.)
Dinner-table test — could Sush say this paragraph out loud at a dinner with non-tech friends without sounding like he's reading marketing copy?
12-year-old test — for the most important concepts, would a curious 12-year-old understand the example?
Honesty test — does this paragraph claim more than we've actually verified? If yes, mark it sourced not tested.

These tests apply to public pages. Roadmap and internal docs can be denser.

Information architecture¶

The sidebar is persistent on every page. Every section has a number (§1, §2 … §10) so you can cite locations: "see §6.2 plugin trust signals". References across pages use this notation throughout.

§	Tab	What lives here	Phase 1 target
§1	Overview	What is OpenClaw · Concepts/Glossary · Architecture diagram · Honest drawbacks	4 entries · all verified by P0a
§2	Setup	Hardware matrix · Decision tree · 5 environments (Laptop · Linux · Azure · Pi · Docker) · Production · Observability · Troubleshooting	10 entries · 1 tested + 4 sourced cards in P0a
§3	Connections	Channels · Tools · Models · Memory — the integration patterns	4 categories mapped in P0a
§4	Plugins	Marketplace packages — field notes, not formal scorecards. Each has dispute link.	1 in P0a (Slack) · 5 in P0b · target 30
§5	Use cases	End-to-end recipes Sush has actually run	1 in P0a (hello-world) · 5 in P0b · target 15
§6	Security	Self-hosting checklist · Plugin trust signals · Practical patterns · What NOT to build as an agent	4 entries published in P0a
§7	Compare	OpenClaw vs MCP-based stacks · vs Claude Code · vs LangChain	1 deep in P0a · 3 by P0b
§8	Updates	Curated weekly watchlist of releases + advisories. NOT a CVE feed.	5 seed items
§9	Resources	Curated external links — official docs · Awesome OpenClaw · key videos · key blogs	1 page
§10	FAQ	Real questions Sush had when starting	7 entries (anchored under §1 until 12+)

Use sub-numbering: §2.3 = Setup → Laptop quick-start. §6.2 = Security → Plugin trust signals. The section heads at the top of each section page show the path: "§ 2 · Setup · / Laptop quick-start".

Cross-references¶

Every entry can include a "see also" cross-reference row. Format: <strong>see also:</strong> §3.2 Channels · §6.2 Plugin trust signals · §5.2 Slack-bot use case. These are the spine of the study-reference feel — readers should be able to follow ideas across the site by §-number.

Methodology · Verification states explained · Sources & citations · Dispute an entry · llms.txt

Visually subordinate to Contents. Smaller mono caps header with 0.75 opacity. Items 12px regular weight with bullet-prefix indent. They support the content but don't compete with it.

Verification states (NEW — unique to Claw Planet)¶

This is the discipline that makes the site trustworthy. Every applicable page (setup methods, plugin field notes, use cases) carries a visible verification badge declaring whether we've actually run it.

State	Meaning	Visual
`tested-by-sush`	Sush ran it. Date + OpenClaw version + hardware/OS noted.	Olive dot · "tested 2026-05-07"
`tested-by-contributor`	Someone else ran it; PR/issue linked.	Cyan dot · "verified by @handle 2026-05-XX"
`sourced-only`	Compiled from official + community docs; we have NOT run it.	Amber dot · "sourced from openclaw.dev/docs · not run by us"
`planned`	Stub — does NOT appear in top nav until verified	Hidden until promoted

Rule: Setup pages especially — Sush has only run OpenClaw on his laptop. Linux/Azure/Pi/Docker ship as sourced-only route cards at launch. We do NOT ship copy-paste step-by-steps for environments we haven't run. Any environment Sush actually runs gets promoted to tested-by-sush with a real walk-through.

Audit: scripts/audit-verification-states.mjs runs in CI and hard-fails the build if any setup/plugin/use-case page is missing a verification state field in frontmatter.

Field-note pattern (NEW — unique to Claw Planet)¶

Plugin pages are titled "Field note" not "Review." Each carries:

The canonical plugin reference (claw.connector.slack@2.4.1)
What we checked
What we did NOT check
Whether we ran it (verification state badge — visible top-right)
Risk profile
Maintainer health
Stars / installs
Sources used (linked)
lastReviewedAt
Disclaimer block: "This is an independent field note, not a certification. We are not affiliated with the plugin author unless explicitly stated."
"Dispute or correct this entry" link → GitHub issue template

The methodology page (/methodology/) sets these expectations BEFORE any field note ships. Every field note links back to it.

Why field notes vs reviews: "Review" implies a verdict-band scoring system (like the MCP scorecards on Agentic Planet). Field notes are lighter — they describe what we found without ranking. This reduces legal exposure to plugin-author pushback and matches Sush's "I'm learning this in public" framing better than "I'm grading your plugin."

Visual identity (locked)¶

Tokens (CSS custom properties)¶

Light mode (default):

--paper:        #FAF8F2;   /* body background */
--paper-warm:   #F2EDDF;   /* sidebar / footer / hover-bg */
--canvas:       #FFFFFF;   /* card / banner / field-note bg */
--rule-faint:   #E8E3D2;
--rule:         #C9C2A8;
--ink:          #15140F;   /* primary text */
--ink-mid:      #3F3A2C;
--ink-mute:     #6F6856;
--ink-faint:    #9C957D;
--claw:         #FF2626;   /* OpenClaw brand red — primary accent */
--claw-hover:   #C91515;
--claw-deep:    #8E0000;
--claw-tint:    rgba(255, 38, 38, 0.06);
--olive:        #5C7C2D;   /* tested · ok */
--amber:        #B57814;   /* sourced · warn */
--olive-soft:   rgba(92, 124, 45, 0.08);
--amber-soft:   rgba(181, 120, 20, 0.08);

Dark mode ([data-theme="dark"]):

--paper:        #0E0F14;
--paper-warm:   #161821;
--canvas:       #1A1C26;
--rule-faint:   #25283A;
--rule:         #3A3F55;
--ink:          #ECEAE2;
--ink-mid:      #B8B3A5;
--ink-mute:     #8A8576;
--ink-faint:    #5C5A52;
--claw:         #FF4747;   /* slightly softened for retinal comfort */
--claw-hover:   #FF6B6B;
--claw-deep:    #C81515;
--claw-tint:    rgba(255, 71, 71, 0.10);
--olive:        #9DBE5A;
--amber:        #E0A03A;

Theme switch: <script> runs before first paint, reads localStorage.cp-theme then prefers-color-scheme fallback. Toggle button in header swaps data-theme on <html> and persists to localStorage. No flash of wrong theme.

Typography¶

Sans (body + UI): Inter weights 400 / 500 / 600 / 700 — Google Fonts CDN
Mono (metadata · code · §-numbers): JetBrains Mono weights 400 / 500 / 600 — Google Fonts CDN
Body 15px / line-height 1.6
Section heads 22px / weight 700 / letter-spacing -0.015em
Catalog entry titles 14.5px / weight 600
Mono labels 9.5–11px / letter-spacing 0.18em (uppercase)

Layout¶

Page max-width 1640px
3-column grid: 260px sidebar · main column · 260px margin notes
Column gap 28px
Outer page padding 16px
Main column internal padding 32px each side (~720px reading width)
Header height ~58px · sticky
Sidebar + margin column sticky, scroll independently

Responsive: - <= 1280px → margin column hides; sidebar narrows to 240px - <= 880px → sidebar hides; single-column with collapsible nav (Phase 2)

Logo (Concept D — Bracket Mark)¶

Square brackets in --ink, asterisk in --claw. Rendered as inline SVG with CSS classes (.bracket and .asterisk) so it switches with theme. Inline SVG favicon in the same shape (light-mode colours hard-coded for tab-icon predictability).

<svg viewBox="0 0 24 24" fill="none" stroke-linecap="round">
  <path class="bracket" d="M7 4 L4 4 L4 20 L7 20" stroke-width="2.2"/>
  <path class="bracket" d="M17 4 L20 4 L20 20 L17 20" stroke-width="2.2"/>
  <g class="asterisk" stroke-width="2" stroke-linecap="round">
    <line x1="12" y1="8" x2="12" y2="16"/>
    <line x1="8.5" y1="9.5" x2="15.5" y2="14.5"/>
    <line x1="15.5" y1="9.5" x2="8.5" y2="14.5"/>
  </g>
</svg>

Reads as "footnote · annotation · code reference." Strong at 16px (favicon), legible at 80px (hero / OG image).

Texture¶

Body has a fixed faint grid background (48px × 48px lines, var(--grid-line) 30–50% opacity). Adapts to theme. Adds graph-paper "exercise book" feel without being twee.

Build infrastructure (mirror Agentic Planet — port pattern)¶

Repo layout (planned)¶

claw-planet/
  src/
    components/
      Header.astro
      Sidebar.astro
      MarginCol.astro
      Footer.astro
      SectionHead.astro
      CatalogTable.astro
      FieldNote.astro
      Banner.astro
      InlineFig.astro
      UpdateRow.astro
    content/
      setups/        (10 .mdx)
      connections/   (4 category .mdx)
      plugins/       (5+ .mdx → 30 target)
      use-cases/     (5+ .mdx → 15 target)
      gotchas/       (4 .mdx)
      compares/      (3 .mdx)
      explainers/    (concepts, architecture, drawbacks)
      faq/           (7+ .mdx)
    data/
      openclaw-primitives.json    (sourced taxonomy — built BEFORE content)
      coverage.json               (single source of truth for hero counts)
      updates.json                (watchlist, JSON-driven)
      resources.json              (curated external links)
    layouts/
      BaseLayout.astro
    pages/
      index.astro                 (home — the §-numbered index)
      [section]/[slug].astro      (catalog entries)
      methodology.astro
      colophon.astro
      404.astro
    styles/
      tokens.css                  (light + dark CSS variables)
      global.css
    lib/
      verify.ts                   (verification-state types)
      cite.ts                     (cross-ref helpers)
  scripts/
    deploy.mjs                    (Cloudflare REST — wrangler broken on win32-arm64)
    voice-lint.mjs                (forbidden words guardrail)
    integrity-check.mjs           (internal 404 hard-fail)
    smoke-check.mjs               (post-deploy live route verification)
    audit-claims.mjs              (hero counts match catalog counts)
    audit-verification-states.mjs (NEW — every applicable page has a state)
    set-gh-secret.mjs             (libsodium sealed-box for GH Actions secrets)
    inspect.mjs                   (debugging helper)
  .github/workflows/
    auto-deploy.yml               (on push to main)
    integrity.yml                 (on every push — hard-fail gate)
  public/
    favicon.svg                   (Bracket Mark)
    llms.txt                      (machine-readable site orientation)
  astro.config.mjs                (sitemap, MDX, React, alias paths)
  package.json
  tsconfig.json
  .gitignore
  README.md
  PROJECT-PLAN.md                 (this playbook content + roadmap)

Stack details¶

Astro 5 (matches Agentic Planet — same major version)
MDX content with Zod-validated frontmatter
React islands for interactive bits (theme toggle, command palette / Pagefind UI)
Pagefind for search — built into the build pipeline from P0a (search must be P0, per rubber-duck)
TypeScript with strict mode

Deploy pattern (port from Agentic Planet)¶

Custom scripts/deploy.mjs posts to Cloudflare Pages REST API. Wrangler is broken on win32-arm64 (Sush's primary machine).
GitHub Actions secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, CF_PAGES_PROJECT) set via scripts/set-gh-secret.mjs (libsodium sealed-box pattern from Agentic Planet).
Auto-deploy on push to main. Integrity check workflow runs on every push and hard-fails on any internal 404 or count-mismatch.

CI gates (every push)¶

Build — Astro + Pagefind. Hard-fail.
Voice-lint — scripts/voice-lint.mjs. Forbidden words check. Strict mode on roadmap/meta docs (hard-fail). Advisory mode on public content (warns).
Integrity check — scripts/integrity-check.mjs. Internal links resolve. Hard-fail on 404.
Audit-claims — hero numbers match catalog counts (single source of truth: src/data/coverage.json or content collection counts).
Audit-verification-states — every setup/plugin/use-case has a verification state. Hard-fail.
Smoke-check (post-deploy) — fetch every route in production, expect 200.

Phased build plan¶

P0a — Foundation + soft launch (1 batch, ~15 routes, `noindex` on)¶

The site is alive but framed as a "first cut · living reference." Public announcement waits.

Routes: - / — home page with all 10 §-sections (catalog stubs for ones with no entries) - /overview/ — what is OpenClaw, plainly + concepts/glossary + architecture + honest drawbacks - /setup/ index + /setup/laptop/ (verified) + /setup/linux-server/, /setup/azure/, /setup/raspberry-pi/, /setup/docker/ (sourced route cards) - /setup/hardware-matrix/ - /connections/ index + 4 category pages (channels, tools, models, memory) - /plugins/ index + /plugins/slack-connector/ (Sush's tested field note) - /use-cases/ index + /use-cases/hello-world-laptop/ (Sush's tested recipe) - /security/ hub + 4 pages (self-hosting checklist, plugin trust signals, practical patterns, what NOT to build) - /compare/ index + /compare/openclaw-vs-mcp-stacks/ (deep) - /updates/ (5 seed items, watchlist format) - /resources/ (curated external) - /methodology/ + /colophon/ + /404 + /llms.txt - Pagefind wired

P0b — Public-credible launch (2–3 batches, ~25 more routes)¶

Routes to add: - 4 more plugin field notes → 5 total - 4 more use-case recipes → 5 total - 7 FAQ entries - 3 setup environments promoted from sourced → tested as Sush runs them - 4 connection items per category (so each category page has substance) - Concepts/glossary deepened - Architecture diagram explained - Honest drawbacks deepened - Migration playbook (coming from MCP) - Troubleshooting page - 2 more compare matchups → 3 total

After P0b lands and integrity is green, remove noindex and announce publicly. Cross-link from Agentic Planet.

P1 — Deeper reference (ongoing)¶

More plugin field notes (target 30)
More use cases (target 15)
Production deployment patterns
Observability primer
Cost calculator
Hardware matrix expansion (NAS, NUC, old desktop)
More compare matchups (target 5+)
Migration playbooks for adjacent runtimes

Sourced OpenClaw primitive map (FIRST implementation task)¶

Before any content page is written, build src/data/openclaw-primitives.json:

{
  "primitives": [
    {
      "term": "SOUL.md",
      "ourLabel": "Soul file",
      "category": "config",
      "officialSource": "https://openclaw.dev/docs/...",
      "examples": ["repo-link-1", "repo-link-2"],
      "summary": "...",
      "lastVerified": "2026-05-07"
    }
  ]
}

This is the source of truth for every page that references OpenClaw concepts. If we use an umbrella term that's NOT in the official docs (e.g. our "Connections" as the category for channels+tools+models+memory), it's flagged so readers know it's our framing, not theirs.

Why this matters: without a sourced primitive map, content batches risk inventing taxonomy. The rubber-duck critique flagged this as a blocking risk: "A tech-savvy OpenClaw reader will spot invented or fuzzy primitives quickly."

Batch-by-batch workflow (locked operational pattern)¶

Each batch follows this loop:

Plan the batch — what surfaces, in what order, with what verification state
Write content — applying the voice guardrails (examples · scenarios · comparisons · why-it-matters)
Self-review (user POV walk) — open every page, read top to bottom, check the voice tests
Voice-lint — npm run voice-lint:strict on roadmap, advisory on public
Build clean — npm run build — must pass with zero warnings
Integrity check — npm run check:links — internal 404s block
Audit-claims + audit-verification-states — counts match, all states present
Deploy — npm run deploy (Cloudflare REST)
Smoke-check on prod — every route 200
Sush voice-pass batch (if any voice-critical content) — Sush reads, marks issues, I revise
Commit message captures what shipped + what's next
Move to next batch

Quality gate: if any of steps 4–7 or 9 fail, the batch does NOT deploy. Fix first.

Pre-existing technical debt + carry-overs¶

These were open during the build phase. Several are now resolved — kept here for the historical record.

`INTEGRITY_LINK_THRESHOLD` ratchet ✅ RESOLVED (Batch 10)¶

In .github/workflows/integrity.yml the INTEGRITY_LINK_THRESHOLD env var was raised to 300 after Batch 5, then later to 900, then dropped permanently to 0 at Batch 10 when the public launch shipped. Permanent state for the public site.

libsodium-wrappers ESM packaging bug ✅ WORKED AROUND¶

libsodium-wrappers@0.7.16 ships a broken ESM dist (modules-esm/libsodium.mjs is missing). Originally tried for set-gh-secret.mjs. Workaround in place: the script now uses gh secret set via spawnSync, which handles encryption natively. If you ever need to switch back to direct REST API + libsodium, pin to a version that has both files in dist/modules-esm/ (test before pinning).

Home page is still a placeholder ✅ RESOLVED (Batch 10, then rebuilt in Batch 13)¶

Original placeholder was rewritten in Batch 10 to render every collection's catalog table. Then in Batch 13 the home was rebuilt again as a 4-block navigational atrium — Banner explaining OpenClaw + Claw Planet, ReadingPaths cards, SectionGrid, RecentUpdates. Catalog tables now live only on their own section pages. Source: 174 lines → 18 lines.

`noindex` is on every page ✅ RESOLVED (Batch 10)¶

noIndex={true} was removed from all section/entry routes at Batch 10. Only /404/ keeps it (intentional). The site is fully indexable.

Search is wired but not active ✅ RESOLVED (Batch 12)¶

Pagefind UI activated in Batch 12 — ⌘K, click on the search input, or / keyboard shortcut all open the modal. Plus Batch 13: mobile-only icon button in the header forwards clicks to the same trigger so phone users get a discoverable search affordance (the full search-row hides at <880px).

Build phase progress (chronological log)¶

This section is the per-batch journal. Future-me reading this cold can trace what shipped, what surprised us, and what was left for later.

Batch 1 — Playbook in learn portal (commit `f7e46cb`)¶

What shipped: - This playbook itself (learning-docs/docs/reference/claw-planet-playbook.md) - Wired into mkdocs.yml nav and the reference index page - Strict mkdocs build green, deployed to learn.aguidetocloud.com/reference/claw-planet-playbook/

Lessons: The Agentic Planet playbook structure was a good template but Claw Planet's specifics needed three new sections that AP didn't have — verification states, field-note pattern, and OUR-umbrella-terms tagging. Capture these as discrete sections so future-me can grep for them.

Batch 2 — Astro scaffold + tokens + 11 components (commit `11953cd`)¶

What shipped: - Astro 5.18 + MDX + React 18 + Pagefind 1.1 - Inter + JetBrains Mono via Google Fonts CDN (preconnect) - Light + dark themes via [data-theme] with pre-paint script + localStorage - Custom REST deploy script (wrangler is broken on win32-arm64 — confirmed) - 11 components matching B3 mockup pixel-for-pixel: BaseLayout, Header (Bracket Mark SVG + theme toggle), Sidebar (TOC + Reading aids), MarginCol (verification legend FIRST, then on-this-page, recently-changed, external, sister), Footer, SectionHead, SectionBlurb, CatalogTable, FieldNote, Banner, InlineFig, UpdateRow - src/content.config.ts with Zod-validated verificationState enum + lifecycle status across 8 collections - src/data/coverage.json — single source of truth for hero/coverage counts - 8 empty content collection directories with .gitkeep - 1 placeholder page (home) — build green

Surprise: Astro 5's astro:content virtual module isn't generated until astro sync runs; the typecheck script needed astro sync && tsc --noEmit not just tsc --noEmit. Fixed in package.json.

Lessons: Translating B3 mockup CSS into component scopes was straightforward — keep token references in tokens.css and let component styles reference them via var(--token). SVG schematics need CSS classes inside an SVG <style> block to be theme-aware (see InlineFig.astro).

Batch 3 — Deploy infra + first live deploy (commit `23df062`)¶

What shipped: - 7 scripts: deploy.mjs, voice-lint.mjs, integrity-check.mjs, smoke-check.mjs, audit-claims.mjs, audit-verification-states.mjs (NEW, unique to Claw Planet), set-gh-secret.mjs - 2 GitHub Actions workflows: auto-deploy.yml, integrity.yml - Cloudflare Pages project claw-planet created via REST API - Custom domain claw.aguidetocloud.com attached (Google CA) - DNS CNAME claw → claw-planet.pages.dev (proxied) on zone 8bf12b5f305f7b482dafa8059a0fe384 - GH Actions secrets CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID set via gh CLI - First manual deploy: 23 files, ~20s upload, SSL cert provisioned in ~60s - All 5 smoke-check routes return 200 on production

Surprise: libsodium-wrappers@0.7.16 ESM dist is broken. The original set-gh-secret.mjs (ported from Agentic Planet) failed with ERR_MODULE_NOT_FOUND for dist/modules-esm/libsodium.mjs. Switched to gh secret set via spawnSync — works perfectly, no encryption gymnastics. Documented as Incident #1.

Lessons: Don't trust that the same npm package version that works on one machine works on another. Pin versions when they matter, prefer wrapping platform tools (gh, az, wrangler-not) over reinventing crypto.

Batch 4 — Sourced OpenClaw primitive map (commit `70c011d`)¶

What shipped: - src/data/openclaw-primitives.json — 46 primitives across 9 categories - 7 workspace files (SOUL.md, AGENTS.md, TOOLS.md, BOOTSTRAP.md, IDENTITY.md, USER.md, HEARTBEAT.md) - 7 architecture concepts (Gateway, Agent runtime, Workspace, Session, Skill, Multi-agent routing, Compaction) - 7 channel entries - 7 built-in tools - 2 model concepts - 5 memory concepts - 4 security concepts - 4 automation concepts - 3 OUR umbrella terms (Connections, Plugins-editorial, Field note) flagged with null officialSource - Every non-umbrella entry has a real officialSource URL pointing to docs.openclaw.ai or github.com/openclaw/openclaw

Surprise: OpenClaw is a real, well-documented project. The earlier confusion (when the planning session had me thinking it might be invented because openclaws.io 403'd me) cleared up once I fetched docs.openclaw.ai directly. The official scope is bigger than the brief suggested — 24+ channels not 7, 7 workspace files not 5, three memory engines (builtin / Honcho / QMD).

Calibration: The mockup said MEMORY.md and SKILLS.md were canonical workspace files. They're NOT in the official docs. Memory lives inside AGENTS.md as accumulated working memory; skills live in folders, not a markdown config file. Adjusted the primitive map to match official docs. Lesson: always verify against the canonical README before designing UI that asserts canonical structure.

Batch 5 — §1 Overview content live (commit `4f5ec19`)¶

What shipped: - 4 substantive MDX entries in src/content/explainers/: - what-is-openclaw.mdx (~7,800 chars) — 30-second version, real WhatsApp-message scenario through 11 hops, comparison table vs Claude Desktop+MCP / LangChain / AutoGen / ChatGPT Plus, "five things to remember" - concepts.mdx (~14,900 chars) — full glossary derived from primitives.json, every term with definition + "why it matters" + canonical source link, OUR umbrella terms explicitly flagged - architecture.mdx (~8,300 chars) — five-layer schematic, 11-hop walkthrough of one message, ASCII-art diagram, "what the diagram doesn't show" - honest-drawbacks.mdx (~11,000 chars) — 8 architectural drawbacks each sourced from a specific docs page or README section, with "why this matters" callout per drawback - Routes: /overview/index.astro (section landing reads from getCollection('explainers')) + /overview/[slug].astro (dynamic entry page with breadcrumb, verification badge, sources, see-also, edit-on-GitHub footer) - Updated src/data/coverage.json: overview.current 0 → 4 - Updated scripts/audit-claims.mjs: COVERAGE_TO_DIR adds overview → explainers - Bumped INTEGRITY_LINK_THRESHOLD 60 → 300 (entries cross-reference routes shipping in later batches)

Surprise: The honest-drawbacks page wrote itself once I read the README's "Security model (important)" section + the multi-agent docs critically. The drawbacks aren't hidden — they're in plain sight in official docs. The site's editorial value isn't finding them, it's connecting them (e.g., "drawback #4 default unsandboxed exec" + "drawback #5 operational floor" → §6.1 self-hosting checklist as the action item).

Lessons: 1. Sourced-only is plenty for V1. The temptation is "we should run OpenClaw before writing setup pages." But sourced-only with a visible badge + verification note is honest and useful. Sush can promote to tested-by-sush over weeks as he runs the actual setups. 2. Cross-references multiply quickly. Each entry links to ~15 future routes. The integrity-check threshold has to ratchet down as those routes ship. 3. MDX prose styles need to be set in the dynamic-entry route, not globally. The prose :global(...) selectors in [slug].astro pick up MDX-rendered HTML inside the .prose wrapper without polluting the rest of the site.

Lessons learned (cross-batch)¶

Batch 6 — §2 Setup content live (commit `3cc5fbd`)¶

What shipped: - 6 substantive setup MDX entries: hardware-matrix.mdx, laptop.mdx, linux-server.mdx, azure.mdx, raspberry-pi.mdx, docker.mdx. - All verificationState: sourced-only — Sush hadn't run any setup yet at write time. Each page declares "what we have NOT verified" up front. - Routes /setup/index.astro + /setup/[slug].astro (mirror of /overview/). - Microsoft disclosure inline on the Azure page (locked rule). - coverage.json: setup.current 0 → 6.

Snags: - MDX parser hates literal < in prose — <240s broke the build (treats <2 as JSX tag start). Same for >30s. Fix: write "sub-300s", "over 30s", or wrap in backticks.

Batch 7 — §6 Security content live (commit `fc2f306`)¶

What shipped: - 4 entries in gotchas/: self-hosting-checklist.mdx, plugin-trust-signals.mdx, practical-patterns.mdx, what-not-to-build.mdx. - These are the only verificationState: tested-by-sush entries possible without running OpenClaw — they're principles, not procedures. - Routes /security/index.astro + /security/[slug].astro.

Snags: - Voice-lint caught ecosystem once and <1s once. Fix: replaced with "community" and "sub-second".

Batch 8 — §3 Connections content live (commit `ab2ed40`)¶

What shipped: - 5 entries in connections/: channels.mdx, tools.mdx, models.mdx, memory.mdx, index-patterns.mdx. - Each entry is a category map, not a marketplace listing — patterns over packages. - Routes /connections/index.astro + /connections/[slug].astro.

Batch 9 — §4 Plugins + §5 Use cases content live (commit `283415b`)¶

What shipped: - §4: filesystem-mcp.mdx first plugin field note (1 of 30 target). - §5: 5 use-case recipes — hello-world-laptop, slack-real-work, pi-home-agent, whatsapp-faq, rag-personal-docs. - Routes for both sections (/plugins/, /use-cases/).

Snags: - MDX still hates <topic> in prose (treats as JSX tag). Fix: replaced with topic in code or "the topic placeholder". - One-off schema confusion: typed status: "sourced-only" (a verificationState value) into status (a lifecycle field). Schema rejected it. Lesson encoded: status ∈ {draft, review, published, archived}; verificationState ∈ {tested-by-sush, tested-by-contributor, sourced-only, planned}. Two different fields. Don't conflate.

Batch 10 — Public launch (commit pending)¶

What shipped: - §7 Compare: openclaw-vs-mcp-stacks.mdx first deep matchup (1 of 10 target). Routes /compare/. - §8 Updates: /updates/index.astro single-page route (5 seed items, JSON-driven inline). - §9 Resources: /resources/index.astro single-page route (12 curated external links across 5 categories). - §10 FAQ: /faq/index.astro single-page route (8 entries). - /methodology/, /colophon/, /404/ single-page surfaces. - Home page index.astro refactored: removed all placeholder content; now reads every collection via getCollection() and renders 10 real catalog tables. Hero numbers are derived; can never drift from reality. - noIndex={true} removed from all section/entry routes — site now indexable. Only /404/ keeps noIndex={true} (intentional). - INTEGRITY_LINK_THRESHOLD ratcheted 900 → 0 in .github/workflows/integrity.yml. Permanent state for public site. - audit-claims.mjs updated: removed faq from COVERAGE_TO_DIR since FAQ is a single-page surface (no content collection). - Final gate state at commit time: 40 pages, 0 broken internal links, 0 voice issues, 0 coverage mismatches, every applicable entry has a verification state.

Snags fixed during finalisation: - Old planning content had cross-links to /plugins/slack-connector/ (8 incoming refs from MarginCol component) — replaced with /plugins/filesystem-mcp/. - /overview/concepts/concepts/ double-path bug (typo in 4 cross-refs) — fixed to /overview/concepts/. - 3 forward-looking links to setup pages we won't ship in P0a (/setup/multi-agent/, /setup/production/, /setup/decision-tree/) — converted from links to plain text "(when it ships)" / "(planned for P0b)". - Voice-lint caught ecosystem in compares/openclaw-vs-mcp-stacks.mdx heading and updates/index.astro description — replaced with community. - Voice-lint caught flagship in methodology.astro — it was inside a literal listing of forbidden words for transparency. Replaced inline list with prose description and a link to voice-lint.mjs for the canonical list.

Final P0a numbers (before public launch deploy): - §1 Overview: 4 published entries - §2 Setup: 6 published entries (all sourced-only) - §3 Connections: 5 published entries - §4 Plugins: 1 field note (target 30) - §5 Use cases: 5 recipes (all sourced-only — flip to tested-by-sush as Sush runs them) - §6 Security: 4 entries - §7 Compare: 1 matchup (target 10) - §8 Updates: 5 seed items (single-page surface) - §9 Resources: 12 curated externals (single-page surface) - §10 FAQ: 8 entries (single-page surface) - Plus: methodology, colophon, 404, sitemap, robots.txt, llms.txt-style claims

Batch 11 — Polish phase: SME + UX pass (commits `c8c450f` + `72c5c82`)¶

Triggered by: Sush's request next morning — "do an SME and quality review and do the improvements and after do a user flow pov and UX test on both light and dark mode and fix all the alignment, color, rendering, line breaking etc etc."

SME content fixes (8 findings — 3 blockers, 4 strong, 1 nit):

Run as a task explore agent (gpt-5.4-mini) with a tight read-only prompt — every published MDX entry reviewed against the canonical OpenClaw docs and the local primitive map. Severity-tagged report came back in 60 seconds.

what-is-openclaw.mdx (blocker) — "There's exactly one agent runtime per Gateway. Not multi-agent." contradicted the canonical multi-agent routing primitive. Reframed as the default shape with multi-agent as a configured option.
concepts.mdx (blocker) — same root cause — "One agent runtime per Gateway" stated as absolute. Now: "By default, one agent runtime per Gateway — though OpenClaw also supports multi-agent routing".
architecture.mdx (strong) — "when that ships" / "when it ships" wording (which I introduced myself in Batch 10 when stripping broken links to non-existent /setup/multi-agent/) was wrong — multi-agent is canonical, just not yet a setup-page on this site. Fixed in two locations.
updates/index.astro (blocker) — "Every MCP server is also an OpenClaw skill" was wrong. MCP servers and skills are separate plugin mechanisms. Rewritten.
connections/models.mdx (strong) — cost table now framed as "rough, illustrative figures" with provider pricing-page citations and explicit "measure your own usage" note.
faq/index.astro 10.3 (strong) — cost figures relabelled illustrative + linked to source-of-figures sections.
setups/hardware-matrix.mdx (strong) — RAM/disk workload table marked "illustrative — sourced inferences, not measurements".
setups/docker.mdx (nit) — dropped the unsupported "~500ms cold-start" number; replaced with hedged language.

UX review (Playwright, 240 screenshots):

Wrote scripts/ux-screenshot.mjs — Playwright runner that captures every public route in light + dark mode at mobile (390) / tablet (820) / desktop (1440) widths.
Strategically sampled the 240 PNGs (home in all 6 combos + key entry pages + tables + dark-mode key surfaces).
One critical issue found: mobile header was broken. The meta items overlapped, the search placeholder was getting cut off, the brand tagline wrapped awkwardly. Everything else (light/dark theming, alignment, typography, code blocks, tables, ASCII diagrams in compares, sticky sidebar, three-column → two-column → single-column responsive collapse) held up cleanly.

UX fix (Header.astro): - Added two new breakpoints: ≤640px hides meta items + brand tagline + ⌘K hint, shrinks placeholder font; ≤420px shrinks brand text. - Added text-overflow: ellipsis + min-width: 0 to search input.

Subtle CSS source-order trap (caught by Playwright re-shoot): - First fix shipped looked correct on read, but on the live site the tagline was STILL visible at 390px viewport. Verified with a Playwright session that walked all matching CSS rules: the @media block matched, but a later same-specificity default rule (display:block) was winning the cascade because of source order. - Lesson encoded: put media queries at the END of the stylesheet, not interleaved with default rules. Equal-specificity rules tie-break on source order, regardless of whether one is in a media query. - Second fix moved responsive overrides to the bottom of <style>. Verified getComputedStyle(small).display === 'none' at 390px on the live site.

Batch 12 — Polish v2: 19 improvements (commits `6678607`, `f946b28`, `0af59e9`, `6663bba`, `f67628b`)¶

Triggered by: Sush's morning ask after seeing the Batch 11 polish — "I want you to look at the site from the QA and web dev expert POV and see what else you would improve. Think out of the box."

I produced a 19-item improvement list grouped by severity (real bugs / discoverability / SEO / polish / out-of-the-box). Sush approved all 19. Done in three batches.

Batch A — 8 foundation fixes (commit 6678607): 1. Self-host Inter + JetBrains Mono via @fontsource (replaces Google Fonts CDN) 2. Edit-on-GitHub deep-links to the specific .mdx file 3. Dynamic last-updated date in header 4. Reading time per entry in crumb (e.g. "8 min read") 5. Anchor links on h2/h3 via rehype-slug + rehype-autolink-headings 6. Prev/next nav on entry pages (sectionNumber order) 7. Schema.org TechArticle JSON-LD per entry 8. Print CSS (hides chrome, widens content, exposes URLs)

Bonus: RSS feed at /updates/feed.xml shipped early. Both /updates/ index page and the feed read from a new src/data/updates.ts (single source of truth).

Architecture additions: - src/utils/entry-helpers.ts — shared getPrevNext / getReadingTime / getSchemaOrgArticle / getRelated. - src/components/EntryFooter.astro — renders prev/next + related entries. - scripts/regen-slug-pages.mjs — generator for all 7 [slug].astro files from one template. No more cross-section drift. - BaseLayout now takes entryFile, lastUpdated, schemaJsonLd, ogImage, margin.tocItems props.

Batch B — 5 navigation + interaction (commit f946b28): 9. Pagefind static search (new SearchModal.astro — lazy-loads /pagefind/pagefind-ui.js, triggered by ⌘K / / / click on search bar; 4050 words indexed across 41 pages) 10. In-page TOC in margin column (auto-derived from entry headings, with active-on-scroll highlighting) 11. Active-entry highlight in Sidebar (matches Astro.url.pathname; aria-current="page") 12. Keyboard shortcuts (j/k = prev/next, gh/gm/gs/go = quick nav, ? = help modal, esc = close) 13. Copy button on every code block (runtime injection on hover)

Batch C — 4 out-of-the-box (commits 0af59e9 + 6663bba + f67628b): 14. Inline glossary tooltips for 11 OpenClaw terms (Gateway, agent runtime, channels, tools, skills, MCP, plugin, workspace, etc.) — runtime DOM walker, CSS-driven popover, skips link/code/heading contexts 15. Auto-generated /setup/compare/ table from front matter (6 rows: env, runtime, hardware, os, time, state) 16. Per-page OG images via satori + @resvg/resvg-js — 1200x630 PNGs generated at build time. 27 unique PNGs (26 entries + home). Inter loaded as ArrayBuffer from @fontsource/inter/files/. 17. RSS feed (already shipped Batch A as bonus) 18. Related entries (already shipped Batch A in EntryFooter) 19. /api/log-404 Pages Function — deferred-active: code shipped, but Cloudflare REST-API Direct Upload deploy doesn't bundle functions/. Will activate when deploy switches to Wrangler-bundled or git integration. 404 page already beacons to it.

Two subtle bugs caught + fixed during the run:

Bug 1: Pagefind path mismatch (commit 6663bba). First Batch C deploy 404'd on /_pagefind/pagefind-ui.js. Pagefind 1.x defaults its output dir to /pagefind/ (no underscore), not /_pagefind/ as in older versions. Lesson encoded: when wiring third-party static assets, always verify the actual emitted path on disk, not the path documented in old tutorials.

Bug 2: TOC items had trailing # (commit f67628b). rehype-autolink-headings injects an anchor link inside each heading (<a class="heading-anchor">#</a>). Astro's entry.headings.text API extracts the heading's textContent AFTER rehype runs — which includes the appended #. Result: TOC items rendered as "Gateway#", "Architecture#", etc. Fix in regen-slug-pages.mjs template: strip trailing # before passing to MarginCol. Lesson encoded: when chaining markdown plugins, the order matters AND the API surface (entry.headings) reads the post-processed AST.

Final state at end of Batch 12: - 41 pages built clean (1 new for /setup/compare/) - 27 unique OG PNGs auto-generated at build time - Pagefind: 41 pages indexed, 4050 words - 0 broken internal links (threshold = 0) - 0 voice-lint findings - Every applicable entry has a verification state - Hero counts match catalog reality

Batch 13 — UX rebuild: home + mobile drawer + verification surfacing (commits `ed91a45` + `b56d313`)¶

Triggered by: Sush's request the morning of 10 May 2026 — "i want to carry over your creative juices on that to the claw portal. Please have a look at the claw portal and see what can you do improve the user experience and helping users get to what they want to and understand what this Claw site represents? Are we using the right font, are we representing or giving the best site layout for what it represents? How else can we improve this? Look at it from both light mode and dark mode. And both desktop and mobile. In mobile we will not cram everything from desktop we will hide few things to make the experience cleaner."

The brief was UX-shaped, not implementation-shaped, so I led with the creative-juice response pattern (the format Sush asked for in the cosmos-bar redesign on 9 May): named what was right architecturally, ranked four directions in a table with a verdict, listed ten "better-than-asked" additions, named the risks, and asked one scope question via ask_user. Sush picked the recommended option ("aggressive Path A — full home rebuild").

The three problems I named, and the verdict:

The home was a 2,700px catalog dump. Ten section-heads each followed by a full CatalogTable + a duplicated "→ open §N" link. A first-time visitor scrolled past 50+ entries before finding anything actionable, and nowhere on the home did the site explain what OpenClaw itself is — only what Claw Planet is.
Mobile navigation was broken. The desktop sidebar (<880px hidden) had no replacement. The header search input was hidden entirely at <640px, including the ⌘K hint. Mobile users had no visible way to navigate sections or search.
The verification contract was buried. The 11px pill below the meta row was the brand contract ("we tested this" / "we only sourced this"), but it had less visual weight than the page title or the meta line. The framed verif-note only rendered when an MDX file supplied a custom verificationNote — most pages had no contract sentence at all.

Ranked paths considered:

Path	What it is	Verdict
A. Slim home + mobile drawer + tune type	Replace catalog dump with what·why·where·new landing. Build mobile drawer. Bump body to 16/1.65. Don't reskin.	⭐ Picked. The brand is right; the problems are mechanical.
B. Full reskin (Stripe-docs minimal)	Drop paper aesthetic, go Notion neutrals.	Skip — discards the field-notebook brand Sush deliberately built.
C. Guided-tour modal	First-time visitor walkthrough overlay.	Skip — adds something to dismiss; the home itself should do this work.
D. Cosmos-style interactive landing	Animated `[*]` orbit canvas.	Skip — Cosmos is the showroom; Claw is a working reference. Field-notebook ≠ planetarium.

Wave 1 (commit ed91a45, +1,024/-241, 10 files) — home rebuild + mobile drawer + type bump.

Surface	Before	After
Home page total height (desktop)	~2,700px	~2,000px
Home page Astro source	174 lines	18 lines (delegates to 4 new components)
Home mobile UX	wall-of-text, no nav	Banner → 3 reading-paths → 10-section grid → 3 latest updates
Mobile sidebar	gone at `<880px` (broken)	hamburger → slide-in drawer with §1–§10 + counts + reading aids + verification legend
Mobile search	hidden at `<640px` (broken)	always-visible icon button (forwards click to existing `#cp-search-trigger` modal)
Body type	15px / dense	16px (token bump on `--fs-base`, type scale steps lifted in lockstep)
Header on inner pages	"reference · v0a · first cut" everywhere	just "reference" — the v0a tag only appears on the home (Astro-side `Astro.url.pathname === '/'` check)
Dark-mode `§`-numbers in nav	bright claw red	ink-mute (so claw red retains semantic weight for badges + actions)

New components (Wave 1):

Banner.astro (rewritten) — two paragraphs at the top of the home: paragraph 1 explains what OpenClaw is in plain English (Gateway, channels, single agent, local-first) lifted in spirit from explainers/what-is-openclaw.mdx; paragraph 2 explains what Claw Planet is with the verification-state pills (tested by us olive · sourced only amber) inlined right inside the sentence so the contract reads as a feature, not a footnote.
ReadingPaths.astro — three index-card-style cards: I'm new → /overview/, I want to install → /setup/, I'm comparing stacks → /compare/. Notebook-tab aesthetic — sharp corners, paper-warm hover, 1px translateY on hover, claw-red pen-note label, mono CTA text.
SectionGrid.astro — a compact 2-column grid of all 10 sections (mobile: 1 column). Each card has the § number, title, 1-line subtitle, and a count badge from coverage.json. Replaces the old behaviour of dumping the full catalog table for each section onto the home.
RecentUpdates.astro — pulls the 3 most recent entries from the canonical src/data/updates.ts SSOT (the old home had two hardcoded entries that drifted from /updates/; that SSOT split is closed). Date · tag pill (NEWS amber, RELEASE olive, CVE/ADVISORY claw, DEPRECATED muted) · title link · meta paragraph.
MobileDrawer.astro — slide-in left panel for <880px. Mounted in BaseLayout.astro alongside SearchModal. Listens for the cp-toggle-drawer custom event from the header hamburger. Mirrors Sidebar.astro content (§1–§10 with counts + verification badges on children + reading aids + verification legend). Backdrop click / Escape / nav-link-click all close. Body scroll locks while open. Auto-closes if viewport widens past breakpoint.

Header changes (Wave 1):

The header grew two new mobile-only icon buttons — search and hamburger. The grid template at <880px is now 1fr auto auto auto (brand · search-icon · hamburger · header-meta where only the theme-toggle survives). At <640px the brand subtitle hides. The full search-row (input + ⌘K hint) is display:none at <880px — the icon button forwards clicks to the same #cp-search-trigger element so the existing Pagefind modal handles the rest unchanged. Two new inline <script> blocks wire the icon button → #cp-search-trigger.click() and the hamburger → dispatchEvent('cp-toggle-drawer').

Token + dark-mode polish (Wave 1):

tokens.css — --fs-base 15→16, --fs-md 16→17, --fs-lg 19→20, --fs-xl 22→24, --fs-2xl 28→30. The entry-page CSS uses explicit pixel sizes for h1/lede/etc., so the token bump only enlarges utility/prose paragraphs that fall back to body-default.
global.css — three new dark-mode-scoped selectors tone the §-numbers in the sidebar (.nav-section .num, .nav-section .count, .h1-section .sec-num) from claw-red to ink-mute. Active state still uses claw-red. Light mode unchanged. Reserves the brand red for verification badges + hover + actions only.

Wave 2 (commit b56d313, +450/-160, 18 files) — verification banner + section hero + OG home refresh.

After deploying Wave 1 cleanly I flagged three follow-ups in the closing brief. Sush's reply was short: "lets do your suggestion now."

1. Entry-page verification surfacing. New VerificationBanner.astro renders directly under the H1+lede on every entry — replacing the buried 11px pill. State-keyed default copy fires when the MDX file has no verificationNote. Three colour variants (olive · amber · claw). The banner has a bold headline ("Sush has not run this end-to-end yet." / "Sush ran this end-to-end." / etc.) followed by a 1–2-sentence explanation, with the last reviewed and last tested dates inlined into the head. The dead .entry-meta div + the conditional .verif-note block are deleted from the regen template.

2. Section-page hierarchy parity. New SectionHero.astro for the 7 collection section indexes (/overview/, /setup/, /connections/, /plugins/, /use-cases/, /security/, /compare/). Layout: §-tag in mono caps claw → 32px H1 → 17px lede paragraph → verification-mix counter row showing X tested · Y sourced · Z planned · N entries total as colored pills. The 7 section index pages were edited to compute tested/sourced/planned from the catalog entries and pass them as props. Replaces the prior SectionHead + SectionBlurb pattern. SectionHead and SectionBlurb are still used by the single-page surfaces (/about/, /updates/, /faq/, /resources/, /setup/compare/) — those have their own narrative shape that doesn't fit a "catalog hero".

3. OG home image refresh. src/pages/og/home.png.ts now passes title: 'OpenClaw, plainly.' and a description aligned with the new banner voice ("A study reference for the OpenClaw agent runtime. Concepts · install paths · plugins · security · honest comparisons. Every entry declares whether we ran it ourselves or only sourced it from docs."). Verified live: https://claw.aguidetocloud.com/og/home.png → 200, renders the new title.

Regen-template change (Wave 2):

The [slug].astro template inside scripts/regen-slug-pages.mjs now imports VerificationBanner and renders it where the previous <div class="entry-meta"> + conditional <div class="verif-note"> lived. The 7 generated [slug].astro files were re-emitted by running node scripts/regen-slug-pages.mjs. The dead stateLabels/stateClassMap/stateLabel/stateClass variables are still in the template (didn't matter to clean up — they're unused locals that will be pruned next time the template is non-trivially edited).

Quality gates (both waves, all green):

Gate	Wave 1	Wave 2
`npm run voice-lint`	14 findings, all pre-existing in `about.astro:70` (the page that intentionally lists the forbidden words) — 0 net new	same
`npm run audit:claims`	0 mismatches across 7 collections	0 mismatches
`npm run check:links`	3,273 internal links, 0 broken	3,280 internal, 0 broken
`npm run audit:verification`	every applicable entry has a state	same
`npm run build` (Astro + Pagefind)	42 pages, 4,134 words indexed	42 pages, 4,133 words indexed
`npm run smoke` (post-deploy)	5/5 routes 200	5/5 routes 200 + OG image 200

Visual verification:

I captured 48 local snaps + 32 live snaps across desktop (1440×900) + mobile (390×844) × light + dark × the affected pages, plus 2 bonus mobile-drawer-open snaps. Local matched live pixel-for-pixel both times. Snaps live in the session folder for future audit (~/.copilot/session-state/4e55b1b6-…/files/snaps-*).

Risks dodged:

Voice-lint regression. All new home + section + banner copy was written to the lint, not against it. The forbidden list (frontier, ecosystem, agentic capability, in layman, AI-powered, robust, scalable, holistic, synergies, game changer, mission-critical, moat, differentiator, flagship) is entirely absent from new code. The 14 findings still flagged on every run are all on about.astro:70 — that line documents the forbidden list as page content.
audit:claims regression. Catalog tables stayed on section pages, so coverage counts didn't move. No-op for the audit, by design.
Pagefind index quality. Catalog text moved off the home but stayed on /overview/, /setup/, etc. — Pagefind kept ~4,133 words across 42 pages (vs ~4,050 in Batch 12). Search recall is preserved.
Cosmos-bar / cosmos-footer. Vendored from the 9 May session — DID NOT touch.
CI integrity gate. INTEGRITY_LINK_THRESHOLD=0 (the post-Batch-10 permanent state) held both deploys.

Files touched (cumulative across both waves, 28 files):

NEW: src/components/{MobileDrawer, ReadingPaths, SectionGrid, RecentUpdates, VerificationBanner, SectionHero}.astro (6)
MOD: src/components/{Header, Banner}.astro, src/layouts/BaseLayout.astro, src/pages/index.astro, src/styles/{tokens, global}.css, src/pages/og/home.png.ts (7)
REGEN: src/pages/{overview,setup,connections,plugins,use-cases,security,compare}/[slug].astro (7) via scripts/regen-slug-pages.mjs (1, edited template)
REWRITTEN: src/pages/{overview,setup,connections,plugins,use-cases,security,compare}/index.astro (7)

Lessons captured:

Lead with the creative-juice format when the brief is UX-shaped, not implementation-shaped. Sush's exact words after the cosmos-bar session: "now your creative juices are flowing and i am loving it, please keep it going like this in the future too." Today's session opened with the same 5-step pattern (what's right · ranked paths · 10-item add-on list · risks · one scope question). The single ask_user ("How aggressive should the home rebuild be?") was the load-bearing decision; everything downstream flowed from his "aggressive — full Path A".
The brand is the contract, not just the chrome. Claw Planet's verification states are the differentiator vs official OpenClaw docs. Wave 2's banner makes that contract a feature on every page rather than a footer. This is the kind of move that pays compound interest on trust.
Field-notebook aesthetic ≠ planetarium aesthetic. Cosmos worked as an interactive showroom because Cosmos is the showroom. Claw is a working reference. Path D ("Cosmos-style canvas") was right to skip — fanfare would fight the field-notebook ethos.
ReadingPaths.astro is a reusable pattern. Three "doors in" cards is a navigational atrium that sits between landing and IA. Worth lifting to other planets that have the same "many sections, three reader intents" shape — Plain AI's curriculum hub already does something similar but bespoke.
Mobile drawer over hamburger menu. Slide-in panels can hold the full IA + auxiliary navigation without compressing. Body-scroll-lock + Escape/backdrop-close + nav-click-close + auto-close-on-resize is the discoverable interaction set; missing any one of those degrades the experience.
Always pair token bumps with explicit-size overrides. Bumping --fs-base 15→16 enlarged paragraph prose without growing dense data tables (CatalogTable / Sidebar) because those use explicit px sizes. Defining the type scale in tokens AND overriding for density-required components is the discipline.

Decision log (this batch):

Question	Call
Replace home aggressively, partially, or only fix mobile?	Aggressive (Path A). Home becomes a navigational atrium; catalogs live on section pages.
New mobile drawer or reuse Sidebar?	New. Sidebar is sticky+desktop-shaped; mobile needs slide-in, scroll-locked, current-section-auto-expanded.
Reskin paper aesthetic?	No. Brand is right; problems are mechanical.
Cosmos-style interactive landing?	No. Cosmos is the showroom; Claw is a reference.
Drop catalog tables from home?	Yes — they belong on section pages where they always did.
Bump body type?	Yes. 15→16 with proportional scale-step lifts.
Tone `§`-numbers in dark?	Yes. Reserve red for actions/badges.
Surface verification on every entry, or only those with custom note?	Every entry. State-specific default copy means the contract is on every page.
Build SectionHero or just bump SectionHead?	SectionHero. A destination-page hero with verification mix is the right hierarchy for catalog-bearing pages.
Update single-page surfaces (`/about/`, `/updates/`, `/faq/`, `/resources/`, `/setup/compare/`) to match?	No. They have their own narrative shape; SectionHero would be a forced fit.

Final state at end of Batch 13:

42 pages built clean (same as Batch 12)
27 unique OG PNGs auto-generated; home OG refreshed with new title + description
Pagefind: 42 pages indexed, 4,133 words
0 broken internal links (threshold = 0, permanent)
0 net-new voice-lint findings
Every applicable entry has a verification state, and now also a default-fallback contract banner if the MDX has no verificationNote
Hero counts match catalog reality
Mobile experience now actually works at <880px
The home explains what OpenClaw is in the first paragraph above the fold
6 new reusable Astro components added to the codebase

Batch-by-batch with deploy gates is the right cadence. Each batch is a complete, deployable unit. Self-review + voice-lint + integrity-check + smoke-check before next batch keeps quality compounding.
Verification states make honesty tractable. sourced-only is the get-out-of-jail-free for content we haven't run. Sush doesn't need to run every Pi setup before we ship; we ship it as a route card with the badge.
Coverage.json as single source of truth for counts. Audit-claims script catches drift between hero numbers and actual content. No more "30 MCPs in hero, 13 in the catalog" trust gap.
Voice-lint as advisory not strict. Catches accidental marketing creep (e.g., I almost wrote "scalable" once) without blocking forward progress on borderline cases.

What's been hard¶

Naming the OUR-vs-OFFICIAL line. "Connections" is our umbrella; "channels", "tools", "models", "memory" are official. Tagging this in the primitive map + on every page where the umbrella appears requires conscious effort. Worth it for trust, but it's overhead.
INTEGRITY_LINK_THRESHOLD ratchet feels wrong. Letting the threshold drift up as content lands is correct in spirit but smells. A better long-term shape: explicit "expected pending paths" allowlist in audit-claims that the ratchet down is tied to. Add as Phase 2 polish.
Testing on Windows ARM64 is fragile. wrangler broken, libsodium broken, occasional flakiness in WSL2 paths. Document specific workarounds inline.

Patterns to repeat¶

Always fetch the canonical doc directly before writing about it. Search snippets and AI-generated guides are summarising — they miss specifics. web_fetch on docs.openclaw.ai pages found the real list of 7 workspace files; the search gave me 5.
Each MDX entry should answer "why this matters" at least once for important concepts. Not buried at the bottom — inline near the introduction of the concept. Sush's voice rule.
Cross-reference forward AND back. Every entry links to its prerequisites (back) and what to read after (forward). Builds the spine of the site.
Expose the dispute mechanism on every page. Edit-on-GitHub + Dispute-or-correct links. Makes the field-note pattern credible.

Patterns to avoid¶

Don't write content for routes you haven't yet decided are real. Each broken cross-link makes the integrity gate need to ratchet up. Better: write content with placeholders and update once the target is confirmed.
Don't use libsodium for one-off encryption when the platform tool already does it. gh secret set does what you want without a dependency.
Don't trust your own taxonomy without verifying against canonical docs. The mockups had MEMORY.md as a workspace file — it isn't.

Incidents log¶

A growing list of production-ish surprises and how they were handled. Each entry should be detailed enough that future-me can recreate the situation.

Incident #1 — `libsodium-wrappers@0.7.16` ESM dist broken¶

Date: 2026-05-07 (Batch 3)

Symptom:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module
'C:\ssClawy\claw-planet\node_modules\libsodium-wrappers\dist\modules-esm\libsodium.mjs'
imported from .../modules-esm/libsodium-wrappers.mjs

Cause: The package's dist/modules-esm/ directory only contains libsodium-wrappers.mjs. The expected sibling libsodium.mjs is missing. Looks like an upstream packaging bug. Reproducible with Node 24.

Fix: Replaced set-gh-secret.mjs to use gh secret set via spawnSync instead of REST API + libsodium-encrypted body. Removed libsodium-wrappers from package.json devDependencies. Net effect: the script does the same thing with one fewer dependency.

Future-me action item: if you need to set GH secrets without gh CLI being available (e.g., from CI without it pre-installed), pin to a libsodium-wrappers version that has both files. Test with node -e "require('./node_modules/libsodium-wrappers/package.json')" and check dist/modules-esm/ files first.

Cross-references to other playbooks¶

learning-docs/docs/reference/agentic-planet-playbook.md — sister site; infrastructure pattern source
learning-docs/docs/reference/voice-and-tone.md — Sush's voice library (broader than Claw Planet's specific guardrails)
learning-docs/docs/reference/deployment-playbook.md — 19-step pre-push checklist for the family
learning-docs/docs/reference/parallel-git-rules.md — git discipline (no git add . ever)
learning-docs/docs/reference/incident-log.md — every incident behind every guardrail in the family
~/.copilot/plain-ai-voice-guardrail.md — Plain AI voice rules (some shared, some not — Claw Planet inherits the forbidden-words list)

Decision log (this session, 2026-05-07)¶

Decision	Why
Standalone planet · own physics	Sush's standing rule for the family. Each planet has its own visual system.
Reference + catalog shape, NOT learning curriculum	Sush clarified mid-session: "tabs/places where I find each topic," not "lessons in order."
10 top-level §-tabs	Comprehensive map of the domain. Every tab is its own substantive surface.
Visual: B3 — sidebar + main + margin notes (study reference)	First topology mockup felt like a "product trying to sell something" (Sush). B3 reads as study reference / MDN / man pages.
Light + dark modes	Sush asked. Honors system preference + persists via localStorage. Dark-mode red softened to `#FF4747` to reduce retinal strain.
Inter + JetBrains Mono via Google Fonts CDN	System-font fallback was rendering inconsistently. Web fonts give crisp, predictable type.
Brand colour: OpenClaw red `#FF2626`	Sush's pick. Lobster red, lifted from openclaws.io. Used as ACCENT only — focal nodes, headings, brand. Schematic edges stay neutral grey to prevent "everything is red" feel.
Logo: Bracket Mark `[*]` (Concept D from 7 explored)	Reads as "footnote · annotation · reference · code." Programmer-friendly. Theme-aware. Strong at 16px.
Name: Claw Planet (kept)	Family-mate of Agentic Planet. The bracket-mark logo + §-numbered layout do the gravitas work. Discussed The OpenClaw Atlas, Claw Codex, Open Field, Claw Field Notes. Stayed Claw Planet.
Field notes (not "reviews")	Lighter editorial stance. Reduces legal exposure. Matches Sush's "learning in public" framing. Dispute mechanism on every entry.
Verification states on every applicable page	Honest about what we've actually run. `tested-by-sush` · `tested-by-contributor` · `sourced-only` · `planned`. Visible badges + frontmatter audit.
Phase split P0a (soft launch) → P0b (public-credible) → P1	Rubber-duck flagged 44-pages-in-one-Phase as over-promising. Soft launch under `noindex` first.
Sourced OpenClaw primitive map BEFORE content	Rubber-duck flagged taxonomy invention as a credibility risk. Build `src/data/openclaw-primitives.json` first.
Pagefind search wired from P0a	Rubber-duck: "search must be P0, not implied." 10-tab reference without good search would be slower than Agentic Planet.
`What's happening` renamed to `Updates`	Rubber-duck: "tracker" implies update cadence we may not honour. "Updates" is honest.
FAQ demoted to under §1 Concepts until 12+ entries	Rubber-duck: "every tab is a promise." FAQ earns top-nav at 12+ honest answers.
Independence + Microsoft disclosure on every page footer + inline on Azure pages	Standard family pattern.

Where to pick up — next session¶

Read first: 1. This playbook (TL;DR + Voice Guardrails + Verification States + Batch 13 sections at minimum) 2. The current snapshot in TL;DR — counts and live URLs for orientation 3. Build phase progress section above — Batches 1–13 chronologically; Batch 13 is the most recent (UX rebuild, 10 May 2026) 4. https://claw.aguidetocloud.com/ — see what live looks like (it's a navigational atrium now, not a catalog dump) 5. The new components from Batch 13 — read these BEFORE editing any page chrome: - src/components/Banner.astro — home front-matter (only used on home) - src/components/ReadingPaths.astro — 3 reading-path cards - src/components/SectionGrid.astro — 10-section navigational grid - src/components/RecentUpdates.astro — pulls from src/data/updates.ts - src/components/MobileDrawer.astro — slide-in panel for <880px - src/components/VerificationBanner.astro — entry-page contract banner - src/components/SectionHero.astro — destination hero for the 7 collection section indexes

Status as of last update (10 May 2026, end of Batch 13):

PUBLIC LIVE at https://claw.aguidetocloud.com
42 pages indexed, 4,133 words in Pagefind
INTEGRITY_LINK_THRESHOLD=0 (permanent)
noindex removed on all routes except /404/
Home rebuilt as a 4-block atrium (Banner → ReadingPaths → SectionGrid → RecentUpdates)
Mobile drawer works at <880px (hamburger → slide-in with §1–§10 + counts + verification badges + reading aids)
Verification banner on every entry page (state-keyed default copy)
Section hero on the 7 collection section indexes (destination-feel + verification-mix counter row)
OG home image refreshed with new "OpenClaw, plainly." title + matching description

Open follow-ups (not blocking, ranked by value):

Cosmos-bar live verification — manually click through cosmos-bar from claw.aguidetocloud.com and confirm the active "claw" planet shows the dim+▼. Visual confirmation in snaps; not yet acked by Sush in the wild.
Single-page surfaces still use SectionHead — /about/, /updates/, /faq/, /resources/, /setup/compare/ weren't migrated to SectionHero because their narrative shape doesn't fit a "catalog hero". If we want them in the new aesthetic, they need bespoke header design — schedule a separate session.
More entries to flip from sourced-only → tested-by-sush — when Sush actually runs OpenClaw, his entries flip and the verification banner switches from amber to olive. The pattern is: edit the MDX frontmatter (verificationState: tested-by-sush + add lastTestedAt), maybe override verificationNote with specifics. Re-deploy.
§4 Plugins is at 1 of 30 target — the highest-value content to add. Each plugin is a FieldNote.astro field note with checked/notChecked/sources/disputeUrl frontmatter. Pattern locked since Batch 9.
§7 Compare is at 1 of 10 target — vs Claude Code, vs LangChain, vs LangGraph, vs vanilla MCP, vs N8N, vs Zapier-AI, etc. Each matchup is the same shape as the existing openclaw-vs-mcp-stacks.mdx deep matchup.
VerificationBanner.astro hardcoded copy — if Sush wants to edit the wording (e.g. customize "tested-by-sush" to mention the testing date format), it's all in one component.
SectionHero <slot name="after-mix"> — provided for future use (e.g. a "What changed since last review" feed row per section). Not used yet.

Don't touch (vendored):

src/components/CosmosBar.astro — vendored from cosmos-atlas (9 May 2026)
src/components/Footer.astro — uses cosmos-footer.css from cosmos-atlas (9 May 2026)
public/cosmos-bar.css and public/cosmos-footer.css — vendored runtime artefacts

Playbook written 2026-05-07 by Claude Opus 4.7. Maintained per-batch since. Latest update: Batch 13 UX rebuild on 2026-05-10 — home rebuilt, mobile drawer added, verification surfacing made first-class, section hero introduced. Hand-off ready for the next session.