Docs Bundle CLAUDE.md

Rules for the docs in this repo. These pages are not rendered here — they are published on rivet.dev by the rivet-website repo, which symlinks this directory in. Everything below exists so a page written here renders correctly there.

Layout

docs/
  sidebar.json            navigation for the two tabs
  content/
    docs/**.mdx           -> /{product}/docs/...
    tutorials/**.mdx      -> /{product}/tutorials/...

The website links docs/content into its content collection, so only real pages belong under content/. Anything else (scripts, fixtures, notes) goes elsewhere in the repo or it will be published as a docs page.

Frontmatter

Every page needs title and description. Both are used for SEO and the sidebar falls back to title when a sidebar entry omits one.

---
title: "In-Memory State"
description: "Actors store state in memory for instant reads and writes."
---

sidebar.json

Navigation for this product's Documentation and Tutorials tabs. Icons travel as Font Awesome export names, not objects, so this repo needs no dependency on the website's icon package.

{
  "docs": [
    { "title": "General", "pages": [
      { "title": "Introduction", "href": "/actors/docs", "icon": "faSquareInfo" }
    ]}
  ],
  "tutorials": []
}

• href is the full site path, including the product segment.
• Adding a page to content/ does not add it to the nav. Add it here too.
• The Self-Host tab is not in this file. It is generated by the website.

Code

• Never inline a fenced TypeScript block. Real examples live in examples/ and are embedded with <CodeSnippet>, so they are type-checked and cannot rot. A snippet that fails to compile fails the website build.
• Snippet paths are relative to this repo's root, so the same path works both here and on rivet.dev:

  <CodeSnippet file="examples/docs/actors-state/durable-basic.ts" />

• Embed part of a file with region="name", delimited in the source by // docs:start name / // docs:end name.
• Shell commands, YAML, Dockerfiles, and terminal output may be inline fenced blocks. The no-inline rule exists for type checking, which only applies to TypeScript.
• Every TypeScript snippet must include its imports and define everything it references. Use @nocheck only for API that does not exist on this branch yet.
• Use <CodeGroup workspace> for examples spanning multiple files, with each file as its own <CodeSnippet>.

What does not belong here

• Marketing pages. They live in the website repo.
• Deploy and self-hosting guides. They are written once in the website repo and templated across every product. Do not write a per-product copy.
• Website components. Do not import from the website by relative path or alias; a page must render from the components the site already provides.

Terminology

Applies to everything published on the website.

• The service that routes, schedules, and persists is the control plane. Never "engine", "server", or "orchestrator".
• A process running user code with the Rivet SDK is a worker. Never "envoy", "runner", "node", "compute", or "data plane".
• Never use "agent" as a deployment noun. Rivet ships agentOS and Actors is "where agents live"; the collision is unrecoverable.
• "envoy" never appears in docs. Envoy Proxy is a top-tier CNCF project. Internal code keeps its own names.
• "Rivet Compute" is retired. Where prose must name the managed offering it is Rivet Cloud, and it links to https://dashboard.rivet.dev.
• Spell the product agentOS, never AgentOS. Capitalize Rivet Actor as a proper noun, lowercase generic "actor".
• Always rivet.dev, never rivet.gg.

Writing

• Write comments and prose as complete sentences. Never use em dashes; use periods instead.
• Do not document deltas. A reader who never saw the old version gains nothing from "this was renamed".
• Every agentOS docs page ends with a concise ## Embedded API section. Prefer checked <CodeSnippet> examples over prose. End with: Read more in the [embedded API quickstart](/agentos/docs/quickstart-embedded).

Previewing locally

Clone the website next to this repo and run it. It detects the sibling automatically and serves this directory's pages live:

git clone https://github.com/rivet-dev/website
cd rivet-website && pnpm install && pnpm dev

pnpm assemble prints which checkout each product resolved to. To point at a different checkout, repoint the symlink; it is gitignored and assemble leaves an existing one alone:

ln -sfn /path/to/this/repo/docs/content src/content/docs/<product>