# Ralphy docs style guide

> **Read this first. Every page in `docs-mintlify/` must follow these rules.**

The reference quality bar is **Hono docs + Vercel docs**: tight, declarative, code-heavy, no fluff. We are "OSS-by-humans" friendly — short asides are fine, but no marketing voice and no AI-slop fillers.

## Tone

- Lead with the **fact**, not the meta. Don't write "This page covers…" — just cover it.
- Friendly, direct, second person ("you"). Imperative for instructions ("Run `ralphy doctor`. If it complains, set the missing key.").
- Brevity beats completeness on every sentence. A 6-word sentence beats a 16-word one if both communicate the same thing.
- **Banned phrases:** "It is important to note", "In conclusion", "powerful", "robust", "seamlessly", "leverage" (as a verb), "out of the box", "best-in-class", "industry-leading", "easy to use", "simply", "just".
- **Banned structures:** Three-paragraph intros. Bullet lists where prose would be 1 sentence. Headers without a sentence under them.
- All prose, examples, code, and comments are English. Cyrillic is banned repo-wide.

## Page shape

Every page follows the same shape:

```mdx
---
title: "Short title (≤ 6 words)"
description: "One sentence, ≤ 160 chars, plain text. Renders in nav + SEO."
---

One-paragraph lede. What this page is, who needs it, the one thing they'll
walk away with. No headers above this paragraph.

## First real section

Body. Code. Examples.

## Related

- [Other page](/section/page) — one-line hook
- [Source playbook](https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/x.md)
```

- **No emoji** in prose. The TUI screenshots can include the icons that the CLI itself prints (`✓`, `→`, etc.), but body text stays clean.
- **Every page ends with a `## Related` section** — 2-5 cross-links to other docs pages or canonical repo files.
- **Frontmatter `description`** must be one sentence, ≤ 160 chars, plain text. No backticks, no angle brackets.

## Length

| Page type | Target words | When to deviate |
|---|---|---|
| Concept (architecture, workspace, model) | 800–2000 | Go longer if the concept has 3+ moving parts |
| Quickstart | 400–1200 | Keep tight |
| Working-with guide (how-to) | 600–1500 | Add an "Edge cases" expandable if needed |
| Prompting guide | 1200–3000 | Per-modality goes deep |
| CLI narrative page | 500–1200 | Defer flag detail to auto-gen `reference/cli/<verb>` |
| Cookbook recipe | 600–1500 | One recipe = one page, full end-to-end |
| Format spec | 500–1500 | Tables of fields, no fluff |

## Code blocks

- **Always specify the language** (` ```bash`, ` ```ts`, ` ```json`, ` ```yaml`, ` ```mdx`).
- Bash commands use `$` only in mixed-input examples; if the block is pure commands, no `$`.
- **Show the output when it's non-trivial.** Use a comment line: `# → final.mp4 (4.2 MB)`.
- **Inline comments are encouraged** (Hono style). Don't over-explain, but a one-line comment that anchors the *why* is fine:
  ```ts
  // Reference is required because the brief names "Old Spice" (real brand).
  const refs = await refsFor(project);
  ```
- For multi-step CLI flows, prefer `<Steps>` over a single fenced block.

## Mintlify components

Use these freely. Don't invent new ones.

- **`<Steps>`** — multi-step procedures. Each `<Step title="…">` is one step. Use for install, "your first project", batch creation.
- **`<CardGroup cols={2}>` + `<Card>`** — landing-style page nav (use on section index pages).
- **`<Tabs>` + `<Tab title="…">`** — alternate paths (e.g. `<Tab title="macOS">` vs `<Tab title="Linux">`, or `<Tab title="JSON">` vs `<Tab title="Pretty">`).
- **`<Note>`** — useful aside, doesn't block the reader.
- **`<Tip>`** — power-user move, optional.
- **`<Warning>`** — they will lose work / money / time if they ignore this.
- **`<Frame>`** — wrap an image (we have none in v1).
- **`<Expandable title="…">`** — long edge-case content that most readers skip. Hide here.
- **`<ParamField path="--flag" type="string" required>`** — CLI flag reference rows. Body is the description.
- **`<CodeGroup>`** — show the same action in multiple tools (e.g. `ralphy` vs raw API).
- **`<AccordionGroup>` + `<Accordion title="…">`** — FAQ-style stacks.

## Angle brackets in MDX

**MDX parses `<word>` as a JSX tag**, which crashes the page. To write placeholders:

- **In code (backticks or fenced blocks):** angle brackets are literal. Safe.
  - Inline: `` `ralphy project show <id>` `` — fine.
  - Fenced: ` ```bash\nralphy project show <id>\n``` ` — fine.
- **In prose:** wrap in backticks, e.g. `Pass the project ID as` `` `<id>` ``.
- **Inside table cells:** the auto-gen reference uses `&lt;`/`&gt;` for plain-prose angle brackets — follow the same pattern if hand-writing tables.
- **Never** write a naked `<id>` or `<brand>` in prose.

## Cross-link conventions

- Internal links use absolute paths from docs root: `[label](/concepts/workspace)`. Mintlify resolves these.
- External canonical source (a playbook, MODELS.md, etc.) uses the GitHub URL: `[playbook](https://github.com/alecs5am/ralphy/blob/main/docs/playbooks/intake.md)`. This survives doc-site moves.
- Don't link from one page to itself. Don't deep-link inside the same section unless the linked page is genuinely the next read.

## Source-of-truth pointers

When you write a page, **read these first** if relevant. Don't paraphrase — quote behaviour, then link.

| Topic | Source |
|---|---|
| Routing / playbook discipline / invariants | `AGENTS.md` (repo root) |
| All models, lifecycle, parameters | `MODELS.md` (repo root) |
| CLI shape, conventions, exit codes | `CLAUDE.md`, `cli/index.ts`, `cli/commands/<verb>.ts` |
| Error codes, classes, exits | `cli/lib/errors/catalog.ts`, `tests/unit/errors-catalog.test.ts` |
| Project memory schemas | `cli/lib/project-log.ts`, `cli/lib/user-profile.ts` |
| Ref-required gate | `cli/lib/eval/refs.ts` + AGENTS invariant #3 |
| Template format | `cli/lib/schemas/template.ts`, `cli/lib/templater/loader.ts`, the public Library (https://www.alecs5am.com/library) |
| Skill format | `docs/skills-format.md`, `cli/lib/skill/wizard.ts`, `.agents/skills/*/SKILL.md` |
| Playbooks | `docs/playbooks/*.md` |
| Asset catalog | `docs/assets-catalog.md`, ralphy-assets companion repo |

## Naming things

- The product is **Ralphy** (proper noun, capitalized). The CLI binary is `ralphy` (lowercase, monospace).
- "Project" / "Brand" / "Persona" / "Reference" / "Template" — the canonical entity names. Always singular when referring to the concept.
- Slugs are `kebab-case`. Project IDs are `{context}-{NNN}`.
- Models go by their full path: `kwaivgi/kling-v3.0-pro`, `bytedance/seedance-2.0`, `gpt-5.4-image-2`. Don't shorten to "Kling" in code blocks; in prose "Kling" is fine.

## What not to write

- **No tutorials that paraphrase what `ralphy --help` already prints** — link to the auto-gen verb page.
- **No "tips and tricks" sections** — every tip is either a `<Tip>` callout next to the thing it applies to, or part of a cookbook recipe.
- **No "best practices" pages** that aren't grounded in a specific source-of-truth doc. If a behaviour comes from `MODELS.md` or `AGENTS.md`, write it as "Ralphy does X because Y" and link the source.
- **No screenshots or images in v1.** We add visuals in a follow-up pass once nav is stable.
- **No mermaid in v1** either. ASCII flow-arrows OK if the page genuinely needs them, but most don't.

## Self-check before you ship a page

1. Does the lede say what the page is in one paragraph?
2. Is every header followed by a sentence (not a bullet list)?
3. Does every code block specify a language?
4. Are all `<placeholder>` tokens inside backticks or fenced blocks?
5. Is there a `## Related` section with 2–5 links?
6. Did you read the source-of-truth doc and link it?
7. Did you skip every banned phrase?

If any answer is "no," fix it before saving.
