docs: move public docs into a docs/ bundle for rivet.dev (#5559)

Co-authored-by: NathanFlurry <anthropic@nathanflurry.com>

Author: NathanFlurry

.claude/reference/docs-sync.md

@@ -21,8 +21,8 @@ When making engine or RivetKit changes, keep documentation in sync. Check this t
 | **RivetKit config** (`rivetkit-typescript/packages/rivetkit/src/registry/config/index.ts`, `rivetkit-typescript/packages/rivetkit/src/actor/config.ts`) | `website/src/content/docs/actors/limits.mdx` if they affect limits/timeouts |
 | **Actor errors** (`ActorError` in `engine/packages/types/src/actor/error.rs`, `RunnerPoolError`) | `website/src/content/docs/actors/troubleshooting.mdx` — each error should document the dashboard message (from `frontend/src/components/actors/actor-status-label.tsx`) and the API JSON shape |
 | **Actor statuses** (`frontend/src/components/actors/queries/index.ts` derivation) | `website/src/content/docs/actors/statuses.mdx` + tests in `frontend/src/components/actors/queries/index.test.ts` |
-| **Kubernetes manifests** (`self-host/k8s/engine/`) | `website/src/content/docs/self-hosting/kubernetes.mdx`, `self-host/k8s/README.md`, and `scripts/run/k8s/engine.sh` if file names or deployment steps change |
+| **Kubernetes manifests** (`self-host/control-plane/kubernetes/`) | `website/src/content/docs/self-hosting/kubernetes.mdx`, `self-host/control-plane/kubernetes/README.md`, and `scripts/run/k8s/engine.sh` if file names or deployment steps change |
 | **Landing page** (`website/src/pages/index.astro` + section components in `website/src/components/marketing/sections/`) | `README.md` — reflect the same headlines, features, benchmarks, and talking points where applicable |
 | **Sandbox providers** (`rivetkit-typescript/packages/rivetkit/src/sandbox/providers/`) | `website/src/content/docs/actors/sandbox.mdx` — provider docs, option tables, custom provider guidance |
-| **Inspector endpoints** | `website/src/metadata/skill-base-rivetkit.md` + `website/src/content/docs/actors/debugging.mdx` |
+| **Inspector endpoints** | `docs/content/docs/debugging.mdx` — AI skills are generated from the docs, so there is no separate skill file to update |
 | **rivetkit-core state management** (`request_save`, `save_state`, `persist_state`, `set_state_initial` semantics) | `docs-internal/engine/rivetkit-core-state-management.md` |

.github/workflows/docs-sync.yml

@@ -0,0 +1,29 @@
+name: Sync docs
+
+# Docs live here; rivet.dev publishes them. On merge to main this copies the
+# docs/ bundle into the website's vendor/actors and opens a PR there, which is also
+# what triggers the site rebuild.
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**"]
+  workflow_dispatch:
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rivet-dev/rivet-website/.github/actions/sync-docs@main
+        with:
+          product: actors
+          token: ${{ secrets.RIVET_WEBSITE_TOKEN }}
+          extra-paths: >-
+            examples/docs
+            examples/vercel-workflow
+            self-host/workers
+            self-host/control-plane
+            rivetkit-typescript/artifacts
+            rivetkit-typescript/packages/rivetkit/package.json
+            engine/artifacts/config-schema.json
+            rivetkit-openapi/openapi.json

.github/workflows/frontend.yml

@@ -7,8 +7,6 @@ on:
       - frontend/**
       - engine/sdks/typescript/**
       - rivetkit-typescript/**
-      - website/**
-
 concurrency:
   group: frontend-${{ github.ref }}
   cancel-in-progress: true

.github/workflows/skills.yml

@@ -0,0 +1,125 @@
+# 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".
+
+## 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>
+```

docs

@@ -8,7 +8,7 @@ Use access control to decide what authenticated clients are allowed to do.
 
 This is authorization, not authentication:
 
-- Use [authentication](/docs/actors/authentication) to identify who is calling.
+- Use [authentication](/actors/docs/authentication) to identify who is calling.
 - Use access-control rules to decide what they can do after connecting.
 
 ## Permission Surfaces

website/AGENTS.md docs/AGENTS.mdwebsite/AGENTS.md renamed to docs/AGENTS.md

@@ -4,11 +4,11 @@ description: "Actions are how your backend, frontend, or other actors can commun
 skill: true
 ---
 
-Actions are very lightweight. They can be called thousands of times per second safely. Actions are executed via HTTP requests or via WebSockets if [using `.connect()`](/docs/actors/connections).
+Actions are very lightweight. They can be called thousands of times per second safely. Actions are executed via HTTP requests or via WebSockets if [using `.connect()`](/actors/docs/connections).
 
-For advanced use cases that require direct access to HTTP requests or WebSocket connections, see [raw HTTP and WebSocket handling](/docs/actors/fetch-and-websocket-handler).
+For advanced use cases that require direct access to HTTP requests or WebSocket connections, see [raw HTTP and WebSocket handling](/actors/docs/fetch-and-websocket-handler).
 
-By default, actions run in parallel. If you need advanced control over concurrency, use [queues](/docs/actors/queues).
+By default, actions run in parallel. If you need advanced control over concurrency, use [queues](/actors/docs/queues).
 
 ## Writing Actions
 
@@ -35,21 +35,21 @@ Actions can be called in different ways depending on your use case:
 
 <CodeSnippet file="examples/docs/actors-actions/calling-frontend.ts" title="frontend.ts" />
 
-Learn more about [communicating with actors from the frontend](/docs/actors/communicating-between-actors).
+Learn more about [communicating with actors from the frontend](/actors/docs/communicating-between-actors).
 
 </Tab>
 <Tab title="Backend (registry.handler)">
 
 <CodeSnippet file="examples/docs/actors-actions/calling-backend.ts" title="server.ts" />
 
-Learn more about [communicating with actors from the backend](/docs/actors/communicating-between-actors).
+Learn more about [communicating with actors from the backend](/actors/docs/communicating-between-actors).
 
 </Tab>
 <Tab title="Actor-to-Actor (c.client())">
 
 <CodeSnippet file="examples/docs/actors-actions/calling-actor.ts" title="actor.ts" />
 
-Learn more about [communicating between actors](/docs/actors/communicating-between-actors).
+Learn more about [communicating between actors](/actors/docs/communicating-between-actors).
 
 </Tab>
 </Tabs>
@@ -108,15 +108,15 @@ For example, to validate action parameters:
 
 ## Streaming Data
 
-Actions have a single return value. To stream realtime data in response to an action, use [events](/docs/actors/events).
+Actions have a single return value. To stream realtime data in response to an action, use [events](/actors/docs/events).
 
 ## Canceling Long-Running Actions
 
 For operations that should be cancelable on-demand, create your own `AbortController`. Chain it with `c.abortSignal` so actor shutdown also cancels the operation.
 
 <CodeSnippet file="examples/docs/actors-actions/canceling-actions.ts" />
 
-See [Actor Shutdown Abort Signal](/docs/actors/lifecycle#actor-shutdown-abort-signal) for automatically canceling operations when the actor stops.
+See [Actor Shutdown Abort Signal](/actors/docs/lifecycle#actor-shutdown-abort-signal) for automatically canceling operations when the actor stops.
 
 ## Using `ActionContext` Externally
 
@@ -126,18 +126,10 @@ Rivet provides the `ActionContextOf` utility type for exactly this purpose:
 
 <CodeSnippet file="examples/docs/actors-actions/action-context.ts" />
 
-See [types](/docs/actors/types) for more details on using `ActionContextOf` and other utility types.
+See [types](/actors/docs/types) for more details on using `ActionContextOf` and other utility types.
 
 ## Debugging
 
 - `GET /inspector/rpcs` lists all available actions on an actor.
 - `POST /inspector/action/:name` executes an action with JSON args and returns output.
 - In non-dev mode, inspector endpoints require authorization.
-
-## API Reference
-
-- [`Actions`](/typedoc/interfaces/rivetkit.mod.Actions.html) - Interface for defining actions
-- [`ActionContext`](/typedoc/interfaces/rivetkit.mod.ActionContext.html) - Context available in action handlers
-- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for defining actors with actions
-- [`ActorHandle`](/typedoc/types/rivetkit.client_mod.ActorHandle.html) - Handle for calling actions from client
-- [`ActorActionFunction`](/typedoc/types/rivetkit.client_mod.ActorActionFunction.html) - Type for action functions