CLAUDE.md

Website CLAUDE.md

Terminology

Applies to all user-facing writing on the website (docs, marketing, blog). Internal code names are unaffected.

• The service that routes, schedules, and persists Actors is the control plane. Never "engine", "server", or "orchestrator".
• A process running the user's code with the Rivet SDK is a worker. Never "envoy", "runner", "node", "compute", or "data plane".
• "Actor" is always capitalized in prose: "Rivet Actor", "Actors", "an Actor's state", "per-Actor SQLite". Never "actor" or "actors" in user-facing copy, headings, alt text, or captions. Code identifiers, paths (/actors/docs/), product IDs ("actors"), and CSS classes stay lowercase. Vendored product docs under vendor/* are synced from their own repos, so fix capitalization there upstream, not in the vendored copy.
• Never use "agent" as a deployment noun. Rivet ships agentOS and Actors is "where agents live"; the collision is unrecoverable.
• "envoy" never appears on the website. Envoy Proxy is a top-tier CNCF project. Internal code keeps pegboard-envoy / envoy-client.
• Rivet Compute is a live Rivet Cloud feature, documented at /docs/deploy/cloud/compute/. Where prose must name the managed offering, it is Rivet Cloud. When describing what Rivet Cloud runs for the customer, say "your backend", never "your workers".
• Rivet Cloud docs live in the Deploy section at /docs/deploy/cloud/, BYOC at /docs/deploy/byoc/; the pricing page is /pricing/. Dashboard links point at https://dashboard.rivet.dev.
• Positioning canon: the tagline is "Infrastructure for the agentic era." with the supporting line "Orchestrate agents. Operate their environment. Automate their work. Deploy what they build." The phrase "infrastructure for long-lived software" is retired.
• "Self-Host" names the section; "control plane" names the thing. Pages inside it say "deploy the control plane on Kubernetes".
• Do not rewrite blog or changelog posts to apply this terminology. They are dated records; dead links are handled by redirects.

Docs Routing

• The site-wide docs overview is /docs/; the Guides tab is /guides/ (every product bundle's content/guides/ and guides sidebar key, merged in product order with same-titled groups combined; the website owns only the overview in src/content/guides/index.mdx); the Deploy tab is /docs/deploy/{self-host,byoc,cloud}/. Product documentation stays at /{product}/docs/ and /{product}/integrations/.
• The route prefixes live in src/sitemap/deploy.ts and src/sitemap/guides.ts. Derive hrefs from them; never hand-write /orchestrate/, /{product}/self-host/, or /actors/learn/, which are redirects.

Docs Pages

• A docs page that introduces a feature opens with a ## Quickstart crash course: the shortest end-to-end path to a working result, as <Steps> with minimal code and no options, tradeoffs, or edge cases. Everything else goes below it. Pure reference pages, which a reader arrives at already knowing what they want, skip it.

Self-Host Guides

• There is one shared copy of every guide at /docs/deploy/self-host/, authored in src/content/self-host/. Guides are product-agnostic; do not fork a guide per product or reintroduce per-product slots.
• Prerequisites go in a ## Requirements block above ## Steps, never as Step 1.
• ## Steps is an H2 wrapping <Steps>. Four to six steps maximum, each titled with an imperative verb.
• Every command shows its expected output. This replaces a prose verification step.
• Budget roughly two sentences per step. Anything needing a paragraph of why belongs in ## Options or the concept docs.
• Never restate shared reference. Ports, env vars, and configuration live on one canonical page each; guides link to them.
• Use tabs for variants (Rivet Cloud vs self-hosted, and the product switcher), never a forked page.
• Pin versions in every snippet. No :latest.
• ## Next steps carries at most three links.
• The control plane is stateful, so serverless platforms are worker-only. Adding a platform means updating deployMatrix.ts, which feeds both the sidebar and getStaticPaths.
• Platform support is uniform across every product, including agentOS. agentOS runs inside Actors and the Actor supplies persistence, so it needs nothing extra from the host platform. Do not exclude it from serverless platforms.
• Worker guides inherit one shared architecture diagram from the template. Do not add a per-guide diagram; platform detail belongs in the steps.
• Diagrams are hand-authored inline SVG via the creating-docs-diagrams skill, drawn in the figure accent (highlight, see Theme). Not Mermaid.

Icons

To add or update icons, see frontend/packages/icons/CLAUDE.md.

Product Marks

The product wordmarks in src/images/products/*-logo.svg are white-on-transparent: the alpha channel is the mark, so the file carries no color of its own. They are always painted as a masked element via wordmarkMaskStyle (src/lib/product-accent.ts), never as an <img>.

• Never render a naked mark. A wordmark always rides inside its tile: rounded-[34.375%] at the SVG's inset-ring geometry, filled ink or the product accent. A bare mark dropped on a light surface — an <img> with brightness-0, an invert filter, or a raw mask on paper — is the failure mode this rule exists to prevent. It reads as a black outline box and matches nothing else on the site.
• The mark inside the tile is white, never cream. Cream is for text and fills inside ink panels; on a mark it reads as a dirty off-white against the pure-white Rivet badge in the header.
• Ink tile (bg-ink) is the default: product-page hero lockups (ProductLockup), /docs cards (DocsLanding), inline product mentions, and any product list on a light surface.
• Accent tile (ProductBadge in src/components/ProductBar.tsx) is the colored variant: header dropdowns, mobile sheet, product bar label, talk-to-an-engineer. Every place that lists products renders ProductBadge rather than hand-rolling the geometry, so the lockup cannot drift.
• One sanctioned tile-less case: on the homepage stack plates (StackSection) the mark is painted white directly on the product-accent field. The plate is the background — it is not a naked mark.
• Secure Exec's mark is its own gothic wordmark (secure-exec-logo.svg), filling the tile with no inset ring, because inside the ring it is illegible at product-bar size. It still rides in a tile like every other mark.
• Rivet Cloud has no wordmark. It takes the faCloud glyph — white inside an accent tile where ProductBadge supplies one, otherwise bare in ink, sized down so it sits level with the neighboring tiles rather than outweighing them (its own hero, and the careers grid). Do not invent a wordmark for it.

Registry Integration Icons

Integration entries in website/src/data/registry.ts display icons on the registry page and detail pages. Each entry uses either an image (SVG file path) or an icon (Font Awesome icon).

When to use each

• image (SVG file in website/public/images/registry/): Use for products and companies that have their own logo (e.g. Docker, Vercel, E2B).
• icon (Font Awesome from @rivet-gg/icons): Use for generic/non-product items that don't have a brand logo (e.g. Filesystem, Browser, SQLite).

Fetching product logos

When adding a new product integration:

1. Search for the product's official SVG logo. Try these sources in order:
   • https://simpleicons.org/icons/{name}.svg (then apply the brand color)
   • The product's website favicon or press kit
   • Their GitHub organization avatar
2. Save the SVG to website/public/images/registry/{slug}.svg.
3. Use actual brand colors. Do not convert logos to white/monochrome. Logos display on a dark background, so avoid dark/black logos. If a logo is black-only, find the dark-mode variant.
4. The carousel selector at the top of the registry page applies a monochrome filter automatically. The colored version displays in the main card and detail pages.

Font Awesome icons

Import from @rivet-gg/icons. The full Font Awesome Pro library is available. Common choices for registry items:

• faFloppyDisk - filesystem/storage
• faGlobe - web/browser/network
• faDatabase - database
• faSqlite / faPostgresql - specific databases
• faBrain - AI/memory
• faDesktop - local/desktop
• faCode - code/interpreter

Code Blocks

• Always store docs code examples under examples/docs/ and render them with <CodeSnippet>. Do not add inline fenced code blocks to docs MDX files.
• Type-check all TypeScript code blocks in website/src/content/docs/**/*.mdx before release, because any failing snippet fails the website build.
• Document onStateChange as read-only against c.state; use vars for callback counters or derived runtime-only values.
• Connect page cards and sidebar entries come from frontend/packages/shared-data/src/deploy.ts.

Required for every TypeScript snippet

• Include all required imports.
• Define all referenced variables and types.
• Avoid placeholders or incomplete code that cannot compile.
• Use @nocheck only when a snippet intentionally documents API not available on this branch yet.

Multi-file examples

• Use <CodeGroup workspace> for any example that spans multiple files (for example registry.ts + client.ts).

• Follow these rules for workspace code groups.

• Store every file under examples/docs/ and render each one with <CodeSnippet file="..." title="..." /> inside the group.

• Treat files as real modules in the same directory and use relative imports (for example import type { registry } from "./registry").

• Do not split related multi-file examples into separate non-workspace snippets.

• If any code block fails type checking, the build fails.

Typography

• Marketing headings and card titles use font-medium (h1 heroes, section h2s, h3/h4 card titles, FAQ headings, price figures). Do not introduce font-normal headings.
• font-normal remains correct only for deliberate de-emphasis: table th de-bolding, quiet dt labels, and input-like UI (TypesenseSearch).
• Hero h1s and section h2s use the class constants in src/components/marketing/typography.tsx (tracking-[-0.015em], h1 leading-[1.06]). Do not hand-write tracking-tight on headings at text-2xl or larger; tracking-tight stays acceptable on text-base and smaller card titles.
• Manrope is the only marketing typeface; JetBrains Mono covers code, terminal commands, keyboard keys, and tabular numeric data only — never titles, labels, or captions. No serif headings on marketing pages; the Learn section's serif treatment is the only exception.
• Section labels are quiet sans (EYEBROW_CLASS or editorial/Eyebrow): text-sm font-medium text-ink-faint, sentence case (text-cream/60 inside ink panels). The mono uppercase letter-spaced eyebrow is retired, as are numbered markers ("01/02", "Fig. NN") anywhere in marketing UI. Plate and panel captions use CAPTION_CLASS (sans, sentence case, no figure numbers).

Theme

• Marketing pages and docs are light: cool porcelain (paper, #EFEFEF) with a paper-deep radial pooling bottom-left (.depth-wash) and a fine grain (.paper-grain). Warmth comes from warm-black ink text, classical imagery, and oil-paint textures, never from synthetic color gradients. Do not use the cream mat token as a surface/background design element on light surfaces (panels, dropdowns, badges, plate frames); use paper/paper-mid/white or ink-tint neutrals instead. cream stays valid only as the off-white text/fill inside dark ink panels, and never on a product mark — those are white (see Product Marks). Docs paint the same porcelain field, render prose via Prose surface="paper", and use pine for the active sidebar/TOC selected state; only the Learn section keeps a dark shell, and no other page may introduce a dark base. The one sanctioned exception is the Secure Exec overview (/secure-exec), ported from secureexec.dev with its own dark design: its body is scoped under .secure-exec-page, and it forces the shared header and footer dark with light={false} on Header plus darkChrome on BaseLayout. Its docs tab is normal light docs. Do not reuse darkChrome elsewhere.
• Every page must look right in both light and dark theme. Dark mode is html[data-theme="dark"] (src/components/ThemeScript.astro, src/styles/theme.css, CSS-variable tokens in tailwind.config.ts; the toggle stores rivet-theme in localStorage). Before finishing any change that affects rendered UI, render the affected states in both themes and inspect them — do not sign off on a light-only screenshot. Use the tokens (paper, ink, ink-soft, pine, …) rather than hardcoded hex or white/black so the retint is automatic; hand-drawn SVG diagrams, animations, hardcoded fills, invert/brightness-0 filters, and imagery are the usual dark-mode failures. Assets that cannot retint through tokens are tracked in DARK_MODE_ASSETS.md; add any new one there with how it is handled. node scripts/check-theme.mjs against a dev server checks the CSS-handled cases.
• Dark ink panels (editorial/InkPanel) are reserved for code, terminal, screenshot, and data moments. Code and data plates stay flat ink; the oil-texture backdrop (textureSrc) is for editorial moments only (CTA colophon, 404).
• The brand accent is accent-deep (#AB451F), the rust of the primary CTA — a fill color, chosen to carry white text. Diagrams and figures draw in highlight, not accent-deep: the same hue and chroma with luminance lifted for foreground marks, #B74B23 on light (AA on paper and card for 12px figure labels) and #D36945 on dark (where accent-deep drops to ~3.3:1). It is the --runtime-highlight token in theme.css (183 75 35 / 211 105 69), exposed to Tailwind as highlight (bg-highlight, text-highlight/60, …); canvas figures read the variable from computed style and re-read it on theme-change. Use it for every dot, stroke, chip, and figure label on marketing pages. Do not draw diagrams in pine, sage, or accent-deep.
• Orange stays the spark: at most one accent/ember CTA per page. White text sits only on accent-deep or ink fills, never on accent. Pine (#2E4034) is the structural color for links, eyebrows, and selected states; sage (#93A286) replaces it inside ink panels.
• No drop shadows on marketing cards or imagery; depth comes from border-ink/10..25 hairlines, bg-white/55 card fills, and paper-mid/paper-deep layering (inside ink panels: border-cream/10..15). Shadows stay acceptable on functional overlays (dropdowns, tooltips, modals) and the header's glass inset highlight.
• Buttons use the constants in src/components/marketing/typography.tsx — metric rounded-md px-4 py-2 text-sm font-medium for all. Primary accent = PRODUCT_HERO_PRIMARY_BUTTON_CLASS (accent-deep, the page's one ember); primary ink = PRIMARY_INK_BUTTON_CLASS; the only secondary = PRODUCT_HERO_SECONDARY_BUTTON_CLASS (border-ink/15 bg-white/55, filled — the borderless border-ink/20 ghost is retired); light-on-ink primary = bg-white text-ink hover:bg-white/90. Do not hand-write button class strings.
• ink-faint text is for captions and metadata at 12px+; body copy uses ink-soft or ink.