Documentation Rulebook

This rulebook defines how Caracal documentation is written, split, linked, and maintained.

Audience: Documentation maintainers, contributors, and reviewers.

Context: Apply these rules before writing or editing any page in the Caracal docs system.

Writing Principles

1. Write from the codebase, not from assumptions.
2. Explain what exists, why it exists, how it works, and when to use it.
3. Keep one canonical explanation for each concept.
4. Prefer exact behavior over conceptual hand-waving.
5. Use repository terminology exactly as the code and UI use it.
6. Separate operator guidance from contributor guidance.
7. Document system boundaries, not just happy-path tasks.
8. Treat missing detail as a documentation defect.

Page Structure Standard

Every content page must follow this order unless a section is genuinely not applicable:

1. Title
2. One-line summary
3. Audience
4. Context
5. Core explanation
6. Internal behavior
7. Practical usage
8. Edge cases and constraints
9. Related concepts

Use short introductory metadata lines near the top of the page:

• Audience: user | developer | both
• Context: where this page fits in the system

Terminology Consistency Rules

• Use host command for the outer caracal command that orchestrates Docker Compose.
• Use in-container CLI for the interactive Click CLI that runs inside the runtime container.
• Use Flow for the terminal UI implemented under caracal/flow.
• Use workspace for the directory rooted under CARACAL_HOME/workspaces/<name>.
• Use principal for any identity that can hold authority.
• Use authority policy for issuance constraints.
• Use execution mandate or mandate for signed, time-bound authorization.
• Use delegation edge for graph relationships between mandates.
• Use authority ledger for mandate issuance, validation, and revocation events.
• Use ledger for metering and resource-usage events.
• Use provider-scoped scope for provider:<provider>:resource:<id> and provider:<provider>:action:<id> values.
• Do not alternate between synonyms such as agent identity and principal, or token and mandate, unless the code defines them as different objects.

Linking Rules

• Define a concept once on its canonical page and link back to it elsewhere.
• Link to the narrowest page that fully answers the next question.
• Use internal links heavily when a page depends on another concept.
• Do not duplicate definitions just to avoid linking.
• Use related-links sections to connect adjacent concepts, not to compensate for weak structure.

Diagram Rules

• Use diagrams only when a flow is easier to understand visually than textually.
• Keep diagrams small and system-level.
• Prefer text diagrams or simple mermaid diagrams.
• Each diagram must explain an actual code path or user flow.
• Do not add decorative diagrams.

Valid example:

Host caracal command
  -> Docker Compose runtime
  -> mcp service / cli session / flow session
  -> PostgreSQL + Redis + workspace state

Example Rules

• Avoid code snippets by default.
• Include code only when a reader must copy a command, config fragment, or exact invocation.
• Every example must match the current codebase and command surface.
• Prefer the smallest successful example first.
• Put extended or advanced examples in collapsible sections when they would break the main flow.
• Never add illustrative code that is not needed to operate or understand the system.

Formatting Rules

• Use short paragraphs and descriptive headings.
• Use tables when comparing commands, modules, or behaviors.
• Use callouts only when they clarify risk, constraints, or failure modes.
• Use monospace for commands, file paths, environment variables, identifiers, and config keys.
• Keep lists flat unless nesting is essential to correctness.
• Keep prose technical, precise, and direct.

Separation Rules

• Open-source docs must stay split between End Users and Developers.
• End-user pages explain installation, operation, workflows, configuration, troubleshooting, and public security behavior.
• Developer pages explain architecture, module boundaries, internal flows, test strategy, release surfaces, and contributor workflow.
• Enterprise pages remain user-facing placeholders only in the public docs.
• SDK pages may define structure now, but SDK content stays deferred until the SDK content phase.
• The only enterprise-adjacent public developer page is Enterprise Connector, and it must describe public connector boundaries only.

Anti-Patterns

Do not do any of the following:

• Do not use emojis anywhere.
• Do not use vague explanations.
• Do not repeat explanations across pages.
• Do not write shallow summaries that omit system behavior.
• Do not add unnecessary code snippets.
• Do not use decorative writing.
• Do not mix user guidance and contributor internals on the same page.
• Do not describe enterprise internals in public documentation.
• Do not hide critical constraints inside long paragraphs.
• Do not write around missing understanding of the code.

Strict Content Rules

• No emojis anywhere.
• No vague explanations.
• No repeated explanations across pages.
• No shallow summaries.
• No unnecessary code snippets.
• No decorative writing.
• No marketing tone.
• No filler text.

Review Checklist

Before a page is complete, confirm all of the following:

• The intended audience is explicit.
• The page has one clear purpose.
• The canonical definition lives on exactly one page.
• Commands and config examples match the current implementation.
• Internal behavior is explained where it matters.
• Constraints and failure modes are explicit.
• Related pages point to the canonical concept source.
• The page does not depend on undocumented prerequisite behavior.