/walkeros-writing-documentation

name: walkeros-writing-documentation
description:
  Use when writing or updating walkerOS documentation - README, website docs, or
  skills. Covers quality standards, example validation, and DRY patterns.

Writing Documentation

When to Use This Skill

• Creating a new package README
• Writing website documentation (MDX)
• Creating or updating skills
• Reviewing documentation for quality
• Documenting Phase 7 of create-destination or create-source

Prerequisites

• [understanding-flow](../walkeros-understanding-flow/SKILL.md) - Architecture

context

• [understanding-events](../walkeros-understanding-events/SKILL.md) - Event

naming rules

---

Documentation Types

Where Content Belongs

| Type | Purpose | Audience | | ------------------ | --------------------------------------------- | --------------------------- | | **Package README** | Installation, basic usage, API reference | Package users | | **Website docs** | Guides, integration examples, detailed config | Integrators | | **Skills** | Process knowledge, workflows | AI assistants, contributors |

Divio Documentation Types

Keep these separate - don't mix tutorials with reference:

| Type | Purpose | User State | | ---------------- | ------------------ | ----------------------------- | | **Tutorial** | Learning | Studying, beginner | | **How-To Guide** | Problem-solving | Working, knows what they need | | **Reference** | Information lookup | Working, needs facts | | **Explanation** | Understanding | Studying, needs context |

---

Example Validation (CRITICAL)

The Problem

AI-generated examples can be:

• Syntactically correct but use non-existent APIs
• Plausible-looking but don't match actual exports
• Outdated, referencing deprecated patterns

Source of Truth Hierarchy

TIER 1: apps/quickstart/
  ✓ Tested  ✓ Compiled  ✓ CI-validated
  → USE FOR: All code examples

TIER 2: packages/core/src/eventGenerator.ts
  ✓ Canonical events  ✓ Real data structures
  → USE FOR: Event examples

TIER 3: packages/*/src/index.ts exports
  ✓ Actual public API
  → USE FOR: Verifying API names exist

TIER 4: Package READMEs & Website docs
  ⚠ May contain errors
  → VERIFY against Tier 1-3 before trusting

Pinned onboarding examples

Getting-started and onboarding code examples are sourced from Tier-1 `apps/quickstart/src/*.ts` (CI-validated) first, then the docs source them. The current canonical examples:

• `first-event.ts`, the zero-to-first-event console example used by the

quickstart and integrated-mode pages and the README.

• `ga4-ecommerce.ts`, the `product add` to GA4 `add_to_cart` mapping used by the

GA4 reference page and the GA4 ecommerce tutorial.

These are pinned against drift by the doc-lint at `apps/scripts/validate-docs.ts` (run `npx tsx apps/scripts/validate-docs.ts`). It extracts canonical tokens from the Tier-1 source and asserts the docs snippets contain them, tolerating intentional doc simplifications (dropping the `seen` capture, arrow `push` instead of a method). `first-event.ts` is pinned on the quickstart, integrated-mode, and README pages, plus the GA4 ecommerce page; `react.mdx` is pinned shape-only (it pushes no `page view`).

The doc-lint also runs these structural and coherence checks:

• **elb event form** (docs, skills, READMEs): every event is pushed as a partial

event, `elb({ name: 'entity action', data })`. A quoted `"entity action"` string as the first `elb` argument is an error; `walker` commands keep their string name (`elb('walker consent', ...)`).

• **Bundled-snippet platform guard**: every JSON flow with `bundle` carries

`config.platform` (getting-started, README, flow reference).

• **Docker env guard**: quickstart Docker snippets use `BUNDLE`, not `FLOW`.
• **Forbidden CLI verbs**: no `walkeros serve` or standalone `walkeros simulate`

in getting-started, guides, or the gtag page.

• **Same-page simulate-key resolution** (getting-started): every

`push --simulate <type>.<key>` must resolve to a step key declared in a flow.json on the SAME page; a simulate command on a page with no flow.json fails. This is what catches an integrated page showing a bundled push loop.

• **Flow.json schema validation** (all docs): every full `version: 4` flow

snippet is run through `schemas.validateFlowConfig` from `@walkeros/core/dev`; fragments and `version: 3` migration "before" snippets are out of scope.

• **Boundary register** (getting-started + MCP page): no prices, tier names, or

upgrade language. **No `:::cloud`** (all docs): there is no walkerOS Cloud, and the callout type no longer exists.

The rule: when you edit a pinned example, edit the Tier-1 `.ts` source and re-run the doc-lint. If the docs snippet must change too, update both so the lint passes.

Getting-started editorial rules

Three rules govern the getting-started surface (decided 2026-07-06, encoded in the doc-lint):

**See your event, per mode.** Integrated-mode pages (quickstart, react, nextjs, modes/integrated, ga4-ecommerce) verify via their own console output; they must never show `walkeros push --simulate`. Only bundled-mode pages may show it, and only targeting a `<type>.<key>` that a flow.json on the SAME page defines.

**Open/paid boundary (Self-Host Sufficiency Rule).** Every getting-started task must reach a working result with MIT packages, the CLI, and reader-controlled infrastructure only. There is no walkerOS Cloud: never write "Cloud" as a walkerOS product, and never add a "What Cloud adds" pointer. Where docs describe commands or tools that talk to the hosted app (`auth`, `projects`, `flows`, `deploy`), call it "the walkerOS app". Never prices, tier names, or upgrade language anywhere in open docs. Self-host is always listed first.