docs · diff
git:20261102.0255a79 to git:20261102.aeffe55
1 added, 1 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: docs
- description: Ethos docs system. Use when writing, editing or restructuring any Ethos docs: docs/content/ pages, READMEs, llms.txt, personality ETHOS.md. Enforces page kinds, front-matter, voice, anti-patterns, checklist. Not for plan/ docs or audit reports.
+ description: 'Ethos docs system. Use when writing, editing or restructuring any Ethos docs: docs/content/ pages, READMEs, llms.txt, personality ETHOS.md. Enforces page kinds, front-matter, voice, anti-patterns, checklist. Not for plan/ docs or audit reports.'
---
# Ethos · Docs System
**The reader is in a hurry.** Every page earns its existence by serving one of four customer-first needs in the first screen. This system specifies the IA, page templates, voice, and acceptance rules that all Ethos documentation adheres to — across the Docusaurus site, the repo README, in-package READMEs, the agent-readable `llms.txt`, and every `ETHOS.md` shipped with a personality.
> Always read this skill before writing, editing, or restructuring any documentation. All page types, IA decisions, voice rules, and structural patterns live here. Do not deviate without explicit user approval. This is the docs counterpart to [DESIGN.md](../../../DESIGN.md) — same authority, same enforcement, same shape.
## Product context
- **What these docs cover:** Ethos — TypeScript AI agent framework where personality is architecture. CLI, channel adapters, plugin system, multiple LLM providers, persistent sessions.
- **Two audiences (the persona shell):**
- **Using Ethos** — operators running the CLI, deploying personalities, wiring channels, configuring providers. Reads docs to *get something working*.
- **Building on Ethos** — contributors writing tools, providers, personalities, channel adapters, plugins. Reads docs to *extend the framework*.
- **A third reader: AI agents.** Other coding agents (Claude Code, Cursor, OpenClaw, Hermes) consume Ethos docs to scaffold integrations. We ship `llms.txt` as a first-class artifact, not an afterthought.
- **Surface this lives on:** the canonical site is Docusaurus at [docs/](../../../docs/). The repo [README.md](../../../README.md), in-package READMEs, and `llms.txt` are derived surfaces that link back to the canonical pages.
## The four customer-first questions
Every page must serve at least one. A page that serves none gets cut.
| Question | What it means in practice |
|---|---|
| Can the reader **see the bigger picture**? | One-sentence pitch on the landing; "Architecture in 90 seconds" reachable from any page; mental model precedes mechanics. |
| Can the reader **understand the context**? | Why this exists, what problem it solves, which alternatives the reader was likely comparing it against. Linked from every concept page. |
| Can the reader **start using it just from this page**? | Quickstart from zero to first run in under 5 minutes (Using) / 10 minutes (Building). One command before any YAML. |
| Can the reader **get value quickly**? | Worked end-to-end examples that produce a visible win — a Telegram bot that replies, a research agent that summarizes a URL. Not toy snippets. |
These four questions are the **page-acceptance test**. A docs PR is reviewed against them before it is reviewed for prose quality.
## Information architecture
Two-persona shell at the top. Diátaxis four-pillar inside each persona. Shared concerns at the same level as the persona doors. One canonical tree — no parallel `/docs` vs `/kb` split, no orphan content trees.
```
docs/content/
intro.md ← landing: one-sentence pitch + job grid + two doors
getting-started/
what-is-ethos.md ← 90-second mental model (explanation)
architecture-90-seconds.md ← one diagram + three sentences each (explanation)
why-ethos.md ← positioning vs LangChain/CrewAI/OpenClaw/Hermes (explanation)
glossary.md ← every domain term in one place (reference)
using/
quickstart.md ← install → first chat in 5 min (tutorial)
tutorials/ ← learning-oriented walkthroughs
how-to/ ← task-oriented recipes
reference/ ← cli, config-yaml, personality-yaml, slash-commands
explanation/ ← what is a personality, memory model, sessions
building/
quickstart.md ← clone → run tests → ship a tool in 10 min (tutorial)
tutorials/
how-to/
reference/ ← interface specs: AgentEvent, Tool, LLMProvider, etc.
explanation/ ← personality-as-architecture, hook execution models, etc.
platforms/ ← shared: cli, telegram, discord, slack
security/ ← shared: overview, threat-model, controls, disclosure
troubleshooting.md ← error-index reference
changelog.md
docs/static/llms.txt ← agent-readable digest (generated)
```
**Rules of the tree:**
1. **One canonical home per page.** No page lives in two sections. If two audiences need it, it goes in `shared/` (platforms, security, troubleshooting) and both personas link to it.
2. **The persona shell is shallow.** Only the top nav splits by audience. Reference pages that genuinely serve both audiences live in `shared/`; they do *not* get duplicated into both persona trees.
3. **Diátaxis is enforced inside each persona.** Every page is exactly one of `tutorial`, `how-to`, `reference`, `explanation`, or `decision`. Mixed pages are a bug.
4. **Verb-driven section names within each persona.** Use `tutorials/`, `how-to/`, `reference/`, `explanation/` literally — don't rename them. Consistency is more valuable than cleverness. Decision pages sit at the top of a job cluster (or as a category index page), named for the job.
5. **No stub pages.** A page is either complete or doesn't exist. Stubs rot fastest and damage trust most.
6. **Jobs before personas on the landing.** The landing leads with an outcome grid — links phrased as jobs the reader would say out loud ("Ship a Telegram research assistant," "Automate code review," "Run a team on a kanban board") — *above* the persona doors. A newcomer knows their job before they know our vocabulary; the job grid converts job → path without requiring it. Section index pages follow the same rule: one value sentence, then an outcome-phrased directory; mechanics deferred one click.
## Page types
Every page declares `kind` in front-matter. The page must follow its kind's template — no exceptions.
| `kind` | Reader state | Purpose | Length | Required sections | Prohibited |
|---|---|---|---|---|---|
| `tutorial` | At study — learning Ethos for the first time | Acquire basic competence on one path | 300–700 lines | Goal · Prereqs · Estimated time · Numbered steps · **Try it** (observable success + one deliberate failure) · What you learned · Next step | Branching choices, alternative paths, "see also for advanced," design rationale |
| `how-to` | At work — has a real task to ship | Accomplish a specific outcome | 100–300 lines | Task statement (1 line) · Result statement (1 line) · Prereqs · Numbered steps · Verify · Troubleshoot | Concept teaching, "what is X" preambles, narrative arc |
| `reference` | At work — looking up a fact | Authoritative lookup, scannable | 100–500 lines | Synopsis · Parameters/fields table · Examples · Source path link · See also | Step-by-step narrative, opinions, marketing copy, design rationale |
| `explanation` | At study — building mental model | Answer one "why" question | 150–400 lines | Question (as H1) · Context · Discussion · Trade-offs · See also | Numbered steps, "how to" procedures, exhaustive parameter lists |
| `decision` | At a crossroads — knows the job, not the path | Route one job to the right approach tier | 100–250 lines | Job statement (one outcome sentence) · Effort ladder (each option labeled, exactly one "(Recommended)") · Trade-off table · "Choose otherwise when…" · Links into each path's tutorial/how-to | Teaching mechanics, neutral option lists with no recommendation, numbered implementation steps |
**Decision pages (the Stripe pattern).** The same job often has multiple legitimate approaches at different effort tiers — for Ethos, typically *built-in personality (no code)* → *custom personality YAML (low code)* → *plugin/interfaces (full API)*. A decision page presents the ladder with effort labels in the link text itself ("(No code)", "(Recommended)"), a trade-off table (rows = capabilities like memory scoping, custom tools, channel support; columns = the tiers, marking what's built-in vs build-it-yourself), and one opinionated recommendation in prose. Decision pages sit at the top of a job cluster and may serve as category index pages. Diátaxis organizes knowledge; decision pages organize *the choice* — both are needed.
**Tutorial vs. how-to test.** If the reader is *studying Ethos*, it's a tutorial. If the reader is *shipping something with Ethos*, it's a how-to. Pick one. A page that fails this test gets split.
**Explanation guardrails:**
1. **H1 is a "why" question.** "Why are hooks split into three execution models?" "Why is personality a structural component, not a system prompt?" If you can't phrase it as a why, the content belongs in reference or how-to.
2. **No procedures.** If a page has numbered steps, it has migrated to how-to.
3. **Cross-link instead of duplicate.** Explanation links to reference for "what's the signature?" and to how-to for "how do I use this?"
**Reference guardrails:**
1. **Every reference page links to its source-of-truth code path.** A `Tool` interface reference page links to [packages/types/src/index.ts](../../../packages/types/src/index.ts).
2. **Tables, not prose.** Parameters/fields are tables. Prose between tables is one sentence max.
3. **No rationale.** "We did it this way because…" lives in explanation. Cross-link.
## Page-acceptance checklist
A docs PR is not merge-ready until every changed page passes this list. Reviewers paste it into the PR.
- [ ] Front-matter declares `kind`, `audience`, and `updated`; values agree with the directory.
- [ ] Page matches the template for its `kind` (required sections present, prohibited sections absent).
- [ ] Passes the tutorial-vs-how-to test (or the why-question test for explanation).
- [ ] Answers at least one of the four customer-first questions and the answer is visible above the fold.
- [ ] **Opens with user-readable value.** Paragraph 1 is understandable to a reader who hasn't installed Ethos yet. Mechanics come no earlier than paragraph 2 (landing, tutorial, explanation) or after the synopsis (reference / how-to).
- [ ] **Voice mode matches the page's `kind`** per the [Voice mode by page kind](#voice-mode-by-page-kind) table. No marketing voice on reference pages; no mechanics-first opening on landing or tutorial pages; `description` front-matter is always informative, never advocacy.
- [ ] First occurrence of every domain term carries an inline plain-English gloss AND links to [glossary.md](../../../docs/content/getting-started/glossary.md).
- [ ] Every command in a tutorial/how-to is followed by its expected output; tutorials include the "Try it" block with one deliberate failure.
- [ ] Pages presenting multiple approaches name exactly one "(Recommended)"; decision pages carry the trade-off table.
- [ ] Reference pages link to source-of-truth code path; enum values have per-value meanings with the default marked; parameters state constraints in prose.
- [ ] "See also" footer present on reference and explanation pages (≥1, ≤5 links).
- [ ] Code samples are runnable against current `@ethosagent/types`.
- [ ] No anti-patterns from the table above.
- [ ] Docusaurus build passes with `onBrokenLinks: 'throw'`.
- [ ] Page is reachable from at least one other page (no orphans).
## Front-matter contract
Every page starts with this front-matter block. CI will fail the build if any required field is missing or malformed.
```yaml
---
title: <Sentence-case page title>
description: <≤155 chars — what the page is, not advocacy for it>
kind: tutorial | how-to | reference | explanation
audience: user | developer | shared
slug: <optional kebab-case URL slug; defaults from filename>
agent: <optional bool; default true; opt-out from llms.txt + llms-full.txt>
time: <only on tutorials and how-tos — e.g., "5 min", "20 min">
updated: <YYYY-MM-DD, the last meaningful content change>
---
```
- `title` — the H1 derives from this; do not write a separate `# Heading` in the body.
- `description` — the source of truth for `<meta description>`, OG card, Twitter card, AI answer snippets, and sidebar tooltip. States *what the page is*, not *why you should read it*. Marketing voice fails the SEO/AEO scan.
- `kind` — must match the template the page follows. CI grep-checks for required and prohibited sections per kind.
- `audience` — `user` lives under `using/`, `developer` under `building/`, `shared` under `getting-started/`, `platforms/`, `security/`, `troubleshooting.md`, or `glossary.md`. The directory and the field must agree.
- `slug` — kebab-case, ≤4 words, semantically dense. Defaults from filename when omitted. Once published, slugs do not change — if one must, ship a permanent redirect in the same PR.
- `agent` — defaults `true`. Set `false` to exclude the page from `llms.txt` and `llms-full.txt`. Almost no page should opt out; the lever exists for sensitive or in-flux content only.
- `time` — present-tense, conservative estimate. Better to under-promise.
- `updated` — bumped on any content edit. Cosmetic-only edits (typos) do not bump it.
## Voice
The reader is a competent developer in a hurry — *and* a human deciding whether to invest the next five minutes. **Lead with value, then precision.** The mix shifts by page kind (see [Voice mode by page kind](#voice-mode-by-page-kind) below), but every page earns its first paragraph by answering one question: *why should I keep reading?*
This is a deliberate posture for the current product stage. Marketing voice is the key aspect now — readers must see the value before they invest in the mechanics. As Ethos matures and the user base grows, the balance may shift back toward precision-first; until then, value-first is the discipline. The skill itself is the place to rebalance — not individual pages.
Inherits DESIGN.md voice rules where they don't conflict with the rules below.
- **Imperative second person, when giving instructions.** "Run `ethos chat`." Not "We run `ethos chat`" or "You can run `ethos chat`." Landing-page or explanation openings can use other voices ("You wouldn't hire one person to be your engineer and your researcher…") — switch to imperative the moment the page turns procedural.
- **Marketing voice is allowed where it earns its place.** Concrete value claims, light-touch analogies, "you wouldn't X — why pretend Y?" structures, and CTA-shaped paragraph endings are welcome on landing pages, tutorial openers, explanation pages, and READMEs. The rule is *not* "no marketing" — it is "no hollow marketing." `A team of AI specialists that remember you across Slack and Telegram` earns its place. `Unleash the power of next-generation AI` does not. **The test:** replace the marketing word with a concrete fact; if nothing substitutes, the sentence carried no information.
- **Hollow advocacy is still slop.** Banned regardless of page kind: "unleash," "harness the power of," "supercharge," "revolutionary," "world-class," "next-generation," "10x," "AI-powered" as a header by itself, "Welcome to X!", "Get started" as a verb-less header. Buttons are verbs: "Install", "Run", "Configure".
- **No emoji as decoration.** Status indicators (✓ / ✗ / ⏳) only, and only where they convey state. Never in headings.
- **Concrete over abstract.** "API key invalid — re-enter to continue." Not "Authentication failed."
- **Specific identifiers.** In technical sections, reference real file paths, real function names, real config keys. Avoid "the foo system" when "[tool-registry.ts](../../../packages/core/src/tool-registry.ts)" is what you mean. (Landing/value paragraphs may stay abstract — but the body must get specific.)
- **No throat-clearing.** Drop "In this guide, we will…", "Note that…", "It's important to remember that…" Start with the value (landing/tutorial openers) or the goal (how-to/reference).
- **One thought per paragraph.** Paragraphs over six lines get split. The reader is scanning.
- **One instruction per sentence.** "Run `ethos chat`. Then send a message." Not "Run `ethos chat` and then, once it has started and you've confirmed the provider is configured, send a message." Compound instructions hide steps.
- **Condition before instruction.** "If the session was interrupted, re-run `ethos chat --resume`." Not "Re-run `ethos chat --resume` if the session was interrupted." Readers skip inapplicable sentences at the comma instead of after acting.
- **Active over passive.** "AgentLoop emits events." Not "Events are emitted by AgentLoop."
- **Sentence-case headings.** "Add a new LLM provider," not "Add A New LLM Provider."
- **Name the recommended path.** When a page presents more than one way to do the same job, it names exactly one "(Recommended)" and says why in one sentence. Neutral option lists make the reader do our thinking.
## Voice mode by page kind
The right voice depends on what the reader needs from the page. Choose by `kind` and surface:
| Surface or page kind | Lead (~first paragraph) | Body |
|---|---|---|
| Landing pages — `intro.md`, both quickstart entries | **Marketing.** Value-first, analogy-friendly, CTA-shaped. | Marketing tone preserved, with concrete specifics. |
| `tutorial` | **Goal + value.** "In five minutes you'll have a Telegram bot that remembers you." | Precise step-by-step. Imperative. |
| `how-to` | **Task + outcome.** "Add a new LLM provider and verify it streams." | Precise, no narrative. Imperative. |
| `reference` | **Synopsis.** One sentence of *what the thing is*. No advocacy. | **Precision throughout. Marketing voice fails here.** Lookup pages need scannable accuracy, not pitch. |
| `explanation` | **Question + value.** Restate why this matters to the reader before answering the why. | Argumentative, precise. |
| `decision` | **Job + promise.** "Run an agent on Telegram — three ways, pick by how much you want to own." | Opinionated, comparative. One "(Recommended)" named, trade-offs honest. |
| Repo `README.md`, per-package READMEs | **Marketing.** Standalone-readable; assume the reader may never click through to docs. | Marketing tone preserved, with concrete specifics. See [Cross-surface rendering](#cross-surface-rendering). |
| Personality `ETHOS.md` | **First-person identity statement.** A reader should be able to predict the personality's behaviour from the opening line. | Imperative, specific. |
| Front-matter `description` field | **Always informative, never advocacy.** This field surfaces in Google snippets and AI answer cards — marketing voice reads as spam there regardless of how the page body opens. |
The shift between lead and body is a *real* transition. A tutorial's first paragraph can read like landing copy — paragraph two is `npm i -g @ethosagent/cli`. Both belong on the same page.
## Cross-page rules
1. **Glossary-first-use: gloss inline, then link.** The first occurrence of any domain term (`personality`, `skill`, `tool`, `hook`, `mesh`, `session`, `memory scope`, `audience boundary`) on a page gets BOTH a parenthetical plain-English gloss and the glossary link: "every [personality](glossary.md#personality) (a directory of files that decides the agent's tools, memory, and model) declares…". The reader never leaves the sentence to understand it; the link exists for depth, not for comprehension. Glosses are one clause, not a second definition — the glossary stays canonical.
2. **Source-of-truth linking.** Every reference page links to the source file it describes — `Tool` reference → [packages/types/src/index.ts](../../../packages/types/src/index.ts). Code drift is detected when these links break.
3. **"See also" footer is mandatory** on every reference and explanation page. At least one link, no more than five. Curated, not auto-generated.
4. **"Recommended reading order" footer** on architecture and concept-cluster pages — Hermes-style — names the next 2–3 pages to read in order.
5. **Internal links use repo-relative paths**, not absolute URLs. `[Tool reference](../reference/tool.md)`, not the deployed `https://docs.ethos.dev/...` URL.
6. **Code samples are runnable.** Snippets compile against the current version of `@ethosagent/types`. Pseudocode is banned in reference; allowed in explanation only when labeled `// illustration`.
7. **One H1 per page.** Subsections are H2 and H3 only. Never skip levels (no H4 directly under H2).
8. **Tables for ≥3 parallel items.** Lists of properties, parameters, options, or trade-offs go in tables. Prose lists are allowed for ≤2 items.
9. **Every command shows its expected output.** In tutorials and how-tos, a command block is followed by an output block (or the relevant excerpt) showing what success looks like. "It printed something — was that right?" is a question the page must answer, not the reader.
10. **Placeholder grammar.** Values the reader must substitute use `<angle-bracket-kebab>` form (`<your-bot-token>`, `<personality-id>`) — one convention everywhere. Prefer zero-edit blocks over placeholders where possible: have the reader run a generator first (`ethos config print`, `ethos personality init`) so subsequent copy-paste blocks need no edits. A block the reader must hand-edit is where tutorials die.
11. **Tutorials fail on purpose, once.** Every tutorial's "Try it" block includes one deliberate failure the reader triggers and recognizes (a tool call outside the toolset, a `--dry-run`, a missing API key) — so the first real error they meet in production is one they've already seen with a calm explanation next to it.
## Reference schemas
See references/reference-schemas.md
## Anti-patterns
These patterns are slop. Code review checks for them, and so does CI grep where possible.
| Pattern | Why it's slop | Replacement |
|---|---|---|
| "Welcome to Ethos!" / "In this guide, we will…" | Throat-clearing burns the first screen | One-sentence pitch or task statement |
| Mixed-audience page (user + developer in one tree) | Both readers bounce off material for the other | Split by persona; share via `shared/` directory |
| Numbered steps inside an Explanation page | Page is secretly a how-to in costume | Move steps to how-to, cross-link from explanation |
| Rationale paragraphs inside Reference | Page is secretly an explanation | Move "why" to explanation, cross-link from reference |
| Stub pages (under-length, "TODO," placeholders) | Damages trust more than absence | Delete or fold until the page can be complete |
| "Click here" / "Read more" link text | Unscannable; screen-reader hostile | Linkify the noun phrase: "the [Tool reference](#)" |
| Marketing-template hero (3-column grid of icons in colored circles) | Indistinguishable from every AI SaaS | Stacked rows with real sample content |
| Hollow hero copy ("Build powerful agents," "Unleash AI," "World-class platform") | No information density; reader can't tell what the product does or who it's for | Specific value claim with a concrete artifact ("A team of AI specialists that remember you across Slack and Telegram") |
| Page opens with mechanics before value | Reader bounces before reaching the why | Lead with what the reader gets; mechanics in paragraph two. The lead → body transition is *the* shape of a well-written page. |
| Sidebar as primary discovery (no landing card grid) | Long sidebars defeat scanning | Card-grid landing + sidebar as secondary |
| Two parallel doc trees (`/docs` + `/kb`) | Reader searches twice | One canonical tree, types declared in front-matter |
| Auto-generated "See also" link dumps | Untrusted, noisy | Curated, ≤5 links, each one chosen |
| Emoji as decoration in headings (🚀, ✨, 🔥) | Indistinguishable from low-effort AI output | Status indicators in body content only |
| Repeated explanations of the same concept across pages | Drift bait — the second copy will lag | Single canonical page, link to it from everywhere else |
| Code samples with `// ...` placeholder bodies | Reader can't run it | Real, minimal, runnable code |
| "Coming soon" / "WIP" badges | Promises that rot | Ship the page or don't link to it |
| Missing `description` front-matter | Search engines invent a snippet from page body; AI answer cards do the same. Both lose. | Required field. CI fails the build if absent or over 155 chars. |
| Marketing-voice `description` ("Learn how to harness…") | The description is what surfaces in search results and AI answers — advocacy reads as spam | State what the page *is*, not why to read it |
| Auto-generated anchors on reference + glossary pages | Heading-text edits silently break external citations; agents that cited `#tools` lose the link when "Tools" is renamed | Explicit `{#stable-id}` suffix on every H2/H3 in reference + glossary |
| Neutral option lists ("you can use A, B, or C") | The reader came for a decision and got a menu; we made them do our thinking | Name one "(Recommended)" with a one-sentence why; honest trade-off table for the rest |
| Command block with no expected output | Reader can't tell success from failure; "it printed something" is not verification | Follow every command with what success looks like (output block or excerpt) |
| Tutorial that only ever succeeds | The reader's first error arrives in production, alone | "Try it" block includes one deliberate, explained failure |
## Cross-surface rendering
See references/cross-surface.md
## SEO and AEO
See references/seo-aeo.md
## Implementation notes
- **Build gate.** `docs/docusaurus.config.ts` sets `onBrokenLinks: 'throw'` and `onBrokenAnchors: 'throw'`. CI runs `pnpm --filter docs build` on every PR.
- **Front-matter validator.** A script (`pnpm docs:check`) walks [docs/content/](../../../docs/content/), validates required front-matter fields (including `description` ≤155 chars), and grep-checks for kind-specific required/prohibited sections. Fails CI on violation. Accepts all five kinds including `decision` (required: an effort ladder with exactly one "(Recommended)" and a trade-off table).
- **Feedback widget.** Every docs page carries a "Was this page helpful?" footer control; results land in a low-ceremony store the maintainer can scan. Signal, not analytics theater.
- **Anti-pattern scan.** Same `pnpm docs:check` greps for the worst patterns ("Welcome to Ethos", emoji in headings, "click here", stub-length pages, marketing-voice descriptions, missing stable anchors on reference + glossary pages). Easy wins, mechanical.
- **Sitemap, structured data, social cards.** Docusaurus' built-in sitemap plugin emits `sitemap.xml`. A small plugin injects Schema.org JSON-LD per page based on `kind`. A social-card plugin renders OG/Twitter card images from `title` + `description`.
- **Crawler files.** `docs/static/robots.txt` allows all crawlers including AI gateways. `docs/static/ai.txt` declares permissive AI usage with attribution preferred.
- **Agent-readable artifacts.** A build step generates `docs/static/llms.txt` (link-index), `docs/static/llms-full.txt` (full content), and serves `<path>.md` at every page URL. All three from canonical markdown — front-matter stripped, MDX components inlined.
- **PR template.** [.github/pull_request_template.md](../../../.github/pull_request_template.md) carries the page-acceptance checklist verbatim for any PR touching [docs/](../../../docs/).
- **No docs without this skill's review.** Any change that introduces a new page kind, renames a top-level section, or amends a template requires an explicit update to this skill in the same PR.