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 — 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/. The repo 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.

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.

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.
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 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.
• 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.

---
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 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" 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:

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 (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. 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.

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/, 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 carries the page-acceptance checklist verbatim for any PR touching 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.