Guides

Start with source docs

Use the Playbook model to decide where source guidance belongs before generated AI Channel files exist.

Core model

Write for Playbook, not for one AI tool.

The public model is Project → Catalog → Resource → AI Channel. A channel renderer can change without rewriting the source docs.

Project

The repo or app using Playbook. It owns sumr.yaml and the local source docs.

Catalog

A reusable group of Resources, such as SUMR engineering standards or org guidance.

Resource

A typed artifact: Document, Topic, Reference, team-member, command, workflow, or lifecycle.

AI Channel

A target runtime such as Codex, Claude Code, Cursor, Copilot, Gemini, or OpenCode.

Source first

Keep the source readable.

Put durable guidance under docs/. A normal Markdown file can start as a Document. Add Playbook frontmatter when the guidance should become a Topic and render into AI Channels.

source tree

docs/
├── frontend/
│   ├── overview.md                 # Topic: short, durable guidance
│   ├── accessibility.rf.md          # Reference: deeper rules and examples
│   └── copywriter.tm.md             # Team member: delegated specialist
└── lifecycle/
    └── protect-generated-output.md  # Lifecycle: automatic guardrail

Guide map

Choose the decision you are making.

Resource types

Choose Document, Topic, Reference, team-member, command, workflow, or lifecycle by what Playbook should render next.

Portable intent

Declare model tier, effort, access, and tools once so each AI Channel can map the Resource into its native format.

Agent instructions

Extract durable rules with agents-md markers instead of hand-editing generated Codex, Claude, or Cursor files.

Channels and sync

Enable AI Channels in sumr.yaml, validate source docs, preview generated files, then write outputs.