rivetkit

# Docs Bundle CLAUDE.md

Rules for the docs in this repo. These pages are **not** rendered here — they are
published on [rivet.dev](https://rivet.dev) by the
[rivet-website](https://github.com/rivet-dev/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.

```mdx
---
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.

```json
{
  "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:
  ```mdx
  <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:

```sh
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:

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

More agent context in rivet-dev/rivetkit

12 other files this repository gives its agents.

Also found in 2 other repositories

The same file, byte for byte, in the weekly crawl of public GitHub.

• rivet-dev/agent-os4.8k
• rivet-dev/agentos4.8k