docs: split the docs bundle into actors, general, and integrations (#5784)

- Split docs/ into three independently synced bundles: docs/actors,
  docs/general (the product-agnostic docs at rivet.dev/docs), and
  docs/integrations.
- Move twelve pages about running workloads rather than writing actors into
  docs/general: cli, container-runner, statuses, versions, endpoints,
  environment-variables, pool-configuration, runtime-modes, skill, tracing,
  regions (was general/edge), and the management and runner half of debugging.
- Split debugging and environment-variables in two, keeping the actor inspector
  and RivetKit SDK halves in the actors bundle.
- Flatten the actors bundle's general/ subdirectory into its docs root.
- Add an Architecture page defining control plane, runner, pool, namespace,
  datacenter, and gateway.
- Adopt the site-wide docs overview and Rivet MCP pages from the website repo,
  alongside the mcp example snippets they embed.
- Drop four dead pages: the actors and learn index stubs the website overrides,
  the empty use-cases stub, and the fetch-and-websocket-handler redirect page.
- Move the radically-simpler-architecture essay to the website repo.
- Add the kv page to the sidebar; it had content but no navigation entry.
- Replace docs-sync.yml with one workflow per bundle.


Amp-Thread-ID: https://ampcode.com/threads/T-01a0d0b9-c9fd-719f-9572-e08f7f1ad1c7

Co-authored-by: Amp <amp@ampcode.com>
Co-authored-by: Nathaneil Flurry <nathan@rivet.gg>

Author: 3 people

.github/workflows/docs-sync.yml .github/workflows/docs-sync-actors.yml.github/workflows/docs-sync.yml renamed to .github/workflows/docs-sync-actors.yml

@@ -1,12 +1,17 @@
-name: Sync docs
+name: Sync docs (actors)
 
 # 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.
+# docs/actors 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/**"]
+    paths:
+      - "docs/actors/**"
+      - "examples/docs/**"
+      - "examples/workflow-sdk/**"
+      - "rivetkit-typescript/artifacts/**"
+      - "rivetkit-typescript/packages/rivetkit/package.json"
   workflow_dispatch:
 
 jobs:
@@ -17,13 +22,10 @@ jobs:
       - uses: rivet-dev/rivet-website/.github/actions/sync-docs@main
         with:
           product: actors
+          source: docs/actors
           token: ${{ secrets.RIVET_WEBSITE_TOKEN }}
           extra-paths: >-
             examples/docs
             examples/workflow-sdk
-            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/docs-sync-general.yml

@@ -0,0 +1,33 @@
+name: Sync docs (general)
+
+# The product-agnostic docs published at rivet.dev/docs. They live here rather
+# than in the website repo because their snippets and generated schemas are
+# built in this repo.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/general/**"
+      - "examples/docs/**"
+      - "self-host/workers/**"
+      - "self-host/control-plane/**"
+      - "engine/artifacts/**"
+      - "rivetkit-openapi/**"
+  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: docs
+          source: docs/general
+          token: ${{ secrets.RIVET_WEBSITE_TOKEN }}
+          extra-paths: >-
+            examples/docs
+            self-host/workers
+            self-host/control-plane
+            engine/artifacts/config-schema.json
+            rivetkit-openapi/openapi.json

.github/workflows/docs-sync-integrations.yml

@@ -0,0 +1,25 @@
+name: Sync docs (integrations)
+
+# The site-wide Integrations section at rivet.dev/integrations.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/integrations/**"
+      - "examples/docs/**"
+      - "examples/workflow-sdk/**"
+  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: integrations
+          source: docs/integrations
+          token: ${{ secrets.RIVET_WEBSITE_TOKEN }}
+          extra-paths: >-
+            examples/docs
+            examples/workflow-sdk

.github/workflows/mirror-swift.yml

@@ -11,7 +11,7 @@ on:
 
 jobs:
   mirror:
-    if: github.repository == 'rivet-dev/actors'
+    if: github.repository == 'rivet-dev/rivet'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

docs-internal/engine/inspector-protocol.md

@@ -8,7 +8,7 @@ Wire-level and integration rules for the RivetKit actor inspector (WebSocket + H
 - When updating the WebSocket inspector, also update the HTTP endpoints.
 - When adding or modifying inspector endpoints, also update:
   - Relevant tests in `rivetkit-typescript/packages/rivetkit/tests/` to cover all inspector HTTP endpoints.
-  - Docs in `website/src/metadata/skill-base-rivetkit.md` and `website/src/content/docs/actors/debugging.mdx`.
+  - Docs in `website/src/metadata/skill-base-rivetkit.md` and `docs/actors/content/docs/debugging.mdx`.
 
 ## Version negotiation
 

docs/CLAUDE.md

@@ -8,17 +8,43 @@ correctly there.
 
 ## Layout
 
+Three bundles live here. Each is synced to the website independently by its own
+workflow in `.github/workflows/docs-sync-*.yml`.
+
 ```
 docs/
-  sidebar.json            navigation for the two tabs
-  content/
-    docs/**.mdx           -> /{product}/docs/...
-    tutorials/**.mdx      -> /{product}/tutorials/...
+  actors/                 -> /actors/docs/... and /guides/...
+    sidebar.json
+    content/
+      docs/**.mdx         -> /actors/docs/...
+      learn/**.mdx        -> /guides/...          (re-rooted by the website)
+  general/                -> /docs/...
+    sidebar.json
+    content/**.mdx        -> /docs/...
+  integrations/           -> /integrations/...
+    sidebar.json
+    content/
+      docs/**.mdx         -> /integrations/...
 ```
 
-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.
+The website links each bundle's `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.
+
+### Which bundle does a page belong in?
+
+Ask whether the page would change if you swapped out the actor programming
+model. If no, it is `general`: it describes the control plane that schedules,
+routes, versions, and observes workloads. If yes, it is `actors`: it describes
+the RivetKit SDK surface you write code against.
+
+`general` is flat, with no subdirectories, because `/docs/` has no tab
+dimension the way a product vertical does. `content/cli.mdx` renders at
+`/docs/cli`.
+
+`integrations` covers third-party frameworks and SDKs. Its `sidebar.json` is
+intentionally empty: the website builds that navigation from
+`src/data/integrations.ts` so it can carry vendor logos and category groups.
 
 ## Frontmatter
 
@@ -34,9 +60,8 @@ 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.
+Navigation for the bundle's tabs. Icons travel as Font Awesome **export names**,
+not objects, so this repo needs no dependency on the website's icon package.
 
 ```json
 {
@@ -45,13 +70,19 @@ the website's icon package.
       { "title": "Introduction", "href": "/actors/docs", "icon": "faSquareInfo" }
     ]}
   ],
-  "tutorials": []
+  "learn": []
 }
 ```
 
-- `href` is the full site path, including the product segment.
+- One key per content directory. `docs/actors` uses `docs` and `learn`; the other
+  two bundles use `docs` alone.
+- `href` is the full site path the page renders at, so it differs per bundle:
+  `/actors/docs/...`, `/docs/...`, `/integrations/...`. The `learn` section is the
+  exception: author it as `/actors/learn/...` and the website re-roots it onto
+  `/guides/...`.
 - 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.
+- The Deploy and Self-Host sections are **not** in these files. They are
+  website-owned and generated there.
 
 ## Code
 
@@ -116,10 +147,15 @@ git clone https://github.com/rivet-dev/website
 cd rivet-website && pnpm install && pnpm dev
 ```
 
+The website resolves this repo as the sibling `../rivet`, and reads all three
+bundles from it.
+
 `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>
+ln -sfn /path/to/this/repo/docs/actors/content       src/content/docs/actors
+ln -sfn /path/to/this/repo/docs/general/content      src/content/docs/docs
+ln -sfn /path/to/this/repo/docs/integrations/content src/content/docs/integrations
 ```

docs/content/docs/access-control.mdx …s/actors/content/docs/access-control.mdxdocs/content/docs/access-control.mdx renamed to docs/actors/content/docs/access-control.mdx docs/content/docs/access-control.mdx renamed to docs/actors/content/docs/access-control.mdx

@@ -6,7 +6,7 @@ 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()`](/actors/docs/connections).
 
-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).
+For advanced use cases that require direct access to HTTP requests or WebSocket connections, see [Low-Level HTTP Handler](/actors/docs/request-handler) and [Low-Level WebSocket Handler](/actors/docs/websocket-handler).
 
 By default, actions run in parallel. If you need advanced control over concurrency, use [queues](/actors/docs/queues).
 

docs/content/docs/actions.mdx docs/actors/content/docs/actions.mdxdocs/content/docs/actions.mdx renamed to docs/actors/content/docs/actions.mdx

@@ -18,7 +18,7 @@ import ActorConfigSchema from "@/components/docs/ActorConfigSchemaClient.astro";
 
 ## Related
 
-- [Registry Configuration](/actors/docs/general/registry-configuration): Configure the RivetKit registry
+- [Registry Configuration](/actors/docs/registry-configuration): Configure the RivetKit registry
 - [State](/actors/docs/state): Managing actor state
 - [Actions](/actors/docs/actions): Defining actor actions
 - [Lifecycle](/actors/docs/lifecycle): Actor lifecycle hooks