​

Assistant guide

​

1. What this repo is

• Pages are .mdx files organized by feature area (projects/, domains/, environments/, etc.).
• Navigation, theming, fonts, and brand colors live in docs.json at the root.
• Run locally with mintlify dev.

​

2. The single hardest rule

​

3. Document only what users can do

• What the user sees and does in the dashboard.
• Behaviors that the user observes from outside (URLs, headers, response codes, webhook payload shapes after the factory transforms them).
• The CLI and webhook configuration, anything users wire into their own systems.

​

4. Files and structure

docs.json                  Mintlify config: nav, theme, fonts, colors, navbar links, SEO
index.mdx                  Docs home page (cards grid)
README.md                  Human-facing repo readme (mintlify dev, conventions)
ASSISTANT.md               This file
style.css                  Custom CSS (orphaned, see §16)
fonts/                     ABC Marfa woff2 files (referenced from docs.json)
images/<area>/             Screenshots, organized by doc area
api-reference/             OpenAPI YAML specs (rendered as their own tab in the nav)

getting-started/           First-deploy flow
projects/                  Project lifecycle, builds, deployments, service types, scaling
sandboxes/                 Brimble Sandboxes (overview, quickstart, snapshots, internals)
domains/                   Custom domains, buying, transfer, DNS
environments/              Environments, env vars, references
networking/                Edge, request lifecycle, internal services, rate limits
scaling/                   Scaling groups
observability/             Metrics, logs
analytics/                 Web analytics
workspaces-and-teams/      Workspaces, team management
security/                  2FA, passkeys
billing/                   Plans, build minutes
notifications/             Notification preferences
webhooks/                  Webhook setup + events reference
troubleshooting/           Symptom-indexed debugging
glossary.mdx               Term reference

​

5. Page conventions

---
title: "Page title"
description: "One-line summary, used as meta-description and previewed in search."
---

See [Builds](/projects/builds) or [Plans and pricing](../billing/plans).

​

6. Mintlify components

<Info>
  Database backups run every hour on the hour.
</Info>

<Frame caption="The Add Domain dialog with the CNAME record to copy.">
  <img src="/images/domains/add-cname-record.jpeg" alt="Add Domain dialog showing the CNAME record" />
</Frame>

<Info>
  **Image needed:** description of exactly what to capture, in enough detail that someone else can take the screenshot without asking.
</Info>

<CardGroup cols={3}>
  <Card title="Quickstart" href="/getting-started/quickstart">
    Deploy your first project in under 10 minutes.
  </Card>
</CardGroup>

​

7. Code blocks

• The opener can carry a language tag: ```bash, ```typescript, ```text.
• The closer must be bare ``` with no language. A closer with a tag (```bash at the bottom of a block) is not recognized as a closer; the parser keeps reading until it finds a bare fence, which collapses subsequent prose into one giant code block. This produces 404s in production and rendering chaos in preview. Always check that closers are bare.

​

8. Two MDX gotchas you will hit

{/* this is a comment */}

Reference a shared variable with `{{shared.NAME}}`.

​

9. Hard editorial rules

• No API endpoint references outside the webhook docs. Don’t write curl https://api.brimble.io/v1/... in any user guide. The webhook configuration page (and only that page) gets exceptions. For everything else, point at the dashboard.
• No <curl> | sh install commands unless the user explicitly asks.
• No invented numbers. If you don’t have a value (rate limit, retry count, plan price), find it in the codebase or omit. The core/src/services/v1/compute.service.ts has the real metering math. dashboard/src/utils/default-pricing.ts has the real plan defaults. brimble-payment/COMPUTE_PRICING_GUIDE.md is internal but accurate.
• No bullets that just describe what’s not there. “What’s not shown” sections, “What you can’t do” lists, defensive “the dashboard surfaces but you can’t change in place” notes — fold the real point into the relevant section, drop the negation.
• No “Verification” section just to add one. A curl -I https://your-app.brimble.app and “you should see HTTP/2 200” doesn’t help anyone. Keep Verification only when the verification step is non-obvious (the right tools/list JSON-RPC payload for an MCP server, the wrk invocation that actually exercises autoscaling, the dig @1.1.1.1 for DNS troubleshooting).
• No multi-language code triplets for trivial things. Don’t write the same process.env.X example in Node, Python, Ruby, and Go. Devs know how to read env vars in their language.
• No worked-example math whiteboard for pricing. The (0.5 - 0.5) × $4 / 720h style is alienating. State the rule, point at the dashboard view that shows the running cost, move on.
• No fabricated “Discriminated union for handlers” / pattern-matching examples. Webhook payload schemas are the doc; how the user dispatches on event is their business.
• No competitor name-drops. Don’t reference Vercel, Railway, Render, Heroku, Fly, Cloudflare Workers, AWS, or any other PaaS by name in user-facing docs, even when comparing architectures. Use neutral framing like “A common alternative is X” and let the reader connect the dots. The build-system and sandbox-system deep-dives use this pattern explicitly.
• No Kubernetes references. Brimble runs on bare metal with the HashiCorp stack; positioning against K8s reads as defensive and dates badly. If you’d be tempted to write “without Kubernetes” or “instead of Kubernetes”, drop the comparison entirely.
• No troubleshooting items that are pure semantics or beyond user control. Every troubleshooting bullet should be a concrete diagnostic plus a fix the user can run. “‘Add a payment method’ → add a payment method” is reading the error message back at the user. “Region out of capacity” is something the user can’t act on. Cut both.

​

10. OPSEC

• Cloudflare sits in front of every request (the user can see this themselves from response headers).
• Brimble uses HashiCorp’s stack, gVisor, BuildKit, Railpack at a high level.
• User-facing hostnames like gateway.brimble.app, ns1.brimble.io, ns2.brimble.io, the internal DNS suffix *.service.brimble.internal (which is what users wire into their own configs).
• Public response headers like X-Brimble-Id, X-Brimble-Project-Version.
• What the build does, what the runner does, what the cache does.

• The names of third-party infrastructure providers Brimble runs on (referred to as “bare metal” or “Brimble’s regions”).
• Specific versions of any internal component.
• Internal config: ACL setup, sandbox/seccomp rules, network egress rules from builders, internal hostnames, default ports, ports on internal services, agent configs.
• Recovery, bootstrap, or admin procedures.
• Token, cookie, or session formats for internal auth between platform components.
• Internal API endpoints that aren’t exposed to customers.
• How tenant isolation is enforced beyond “tenants are isolated.”
• Internal storage backends by name (MongoDB, Redis, RabbitMQ, Ably, Loki). Say “the sandbox record”, not “the Mongo document”. Say “the dashboard updates”, not “the Ably channel pushes an event”.
• Internal event names (sandbox:provision:failed, sandbox:ready, sandbox:expired, anything that looks like <service>:<noun>:<verb>). Frame as status transitions the user can observe: “the sandbox flips to ready”.
• Internal queue / bus references: “message bus”, “RabbitMQ”, “Bull queue”, “Redis pub/sub”. Users don’t see these. Talk about the user-visible side effect.
• Internal namespace / task / pool names: Nomad job names (sandbox-<id>, sbx, run), node pool names, Consul namespace names. Say “scheduled on a sandbox host” without leaking the labels.
• CNI / CSI plugin names: s3, geesefs, the specific bridge/no-egress CNI plugin name. Say “CSI-backed persistent volume” or “outbound network blocked” without naming the implementation.
• Specific defense mechanisms that map to attacker tools. Don’t write “cloud-metadata endpoints at 169.254.169.254 are spoofed to localhost”, that’s a recipe for someone to test whether your mitigation is in place. Say “the container can’t reach the host’s identity or credentials surface”. Same idea: don’t enumerate cap_drop lists, seccomp filters, or pid limits with their exact values.
• Internal timing constants (provision-poll timeout, stuck-starting threshold, reaper intervals). Say “a few minutes” or “hourly”.

​

11. Brand

​

12. Things that have already burned me

• _id on the wire. The webhook payload uses id, not _id. The dashboard backend strips Mongo’s _id before sending. Don’t expose ObjectId as a TypeScript type in docs; it’s string.
• Dashboard label vs runtime behavior. The database overview card says “Backup frequency: Daily” but heracle/internal/service/cron.go:42-43 cron is 0 0 * * * * — every hour. The cron is the truth.
• Hacker price. $5/month, not$7. Pro is $15, not$19. Sourced from dashboard/src/utils/default-pricing.ts (the live config). Older internal docs have $7/$19; ignore them.
• Plan free CPU/memory baseline. Free is 0.25 vCPU / 0.25 GB. The compute slider’s smallest stop is 0.5 — meaning Free-plan projects pick up metered overage as soon as they create a project. Document this honestly.
• Persistent disk default. 10 GB minimum, not 1. Sizes go 10–150 GB in 10 GB steps (disk-size-options.ts).
• Password protection uses a session cookie + form login (x-brimble-session), not HTTP Basic Auth. curl -u user:pass is wrong. There’s no self-serve toggle in the dashboard yet.
• MCP auth header is x-brimble-key, not Authorization: Bearer.
• subscription_id in webhook envelope is in the internal RabbitMQ payload, but brimble-email/src/factory/webhook.factory.ts strips it before sending to the user. The user-visible envelope is {event, data}.
• Webhook signing. Real events (factory → Hookdeck → user) are unsigned. The X-Brimble-Webhook HMAC and X-Brimble-Test header only apply to the one-off test endpoint, not production deliveries. Don’t claim users should verify HMAC.
• Env var values are not in webhook payloads. Only the variable name (envData.name). The data.value field doesn’t exist in the factory output.
• Region defaults are read at runtime from the PlanConfiguration Mongo collection, not hardcoded. The internal COMPUTE_PRICING_GUIDE.md documents the values; the dashboard’s default-pricing.ts mirrors them as fallbacks.
• Hugging Face git integration was removed. Don’t reintroduce it without confirmation.
• Builder, not Runner. The build worker is called the Builder everywhere user-facing. The codebase still uses “runner” in file names and class names, but the docs are renamed. Don’t backslide.
• Build pipeline step 7 is “Launch”, not “Orchestrate”. That’s the step where the artifact goes live on the Nomad cluster. Same applies in projects/builds.mdx and projects/build-system.mdx.
• Free plan can only deploy static sites + 1 free-tier database. core/src/services/v1/verify-payment.service.ts:58-59 rejects every non-static project on Free at deploy time. So there’s no path where a Free user picks a slider position that meters compute, don’t write callouts about “quiet overage” on Free; it’s impossible. Static sites have no compute allocation.
• Free databases are deleted after 15 days, not paused. core/src/services/v1/database.service.ts reapExpiredFreeTierDatabases calls projectService.deleteProject(project). The dashboard’s “paused” copy is softer than the reality.
• Rate limiting is Cloudflare, not the proxy middleware. The proxy has a rate-limit.ts middleware that defaults to “500 req / 10 min / IP / domain”, but it’s not wired into the live request path. Cloudflare handles it with adaptive rules. Don’t quote the 500 number.
• MCP x-brimble-key is account-level, not per-project. The key lives in the user profile drawer under API key, paid plans only. Action is Reroll key (not “Rotate”). One key authenticates every MCP server in the account.
• Apex A record IP is 157.90.225.125 at @. Don’t say “see the dashboard for the IP”; write the value, sourced from dns/lb/keepalived-backup.conf.
• Workspace pricing: $5/seat +$8/build, min 2 builds. Sourced from dashboard/src/config/index.ts:36-37. 3 seats + 2 builds = $31/mo. Don't write$7.50/build or 0/1 minimum builds.
• Payment retry copy avoids Stripe by name. The user-facing retry flow describes what users see (warnings, builds disabled at attempt 3, projects suspended when retries exhaust, canceled at 30 days unpaid). It doesn’t mention Stripe, Smart Retries, or webhook event names. The internal payment service handles the “how”; the user only needs the “what”.
• Header strip + Header inject sections were removed from networking/request-lifecycle.mdx. The numbered spine goes 1-10 now; don’t reintroduce header-injection or header-strip explanations without confirmation.
• Next.js / Nuxt SSR-vs-static gotcha. A Next.js or Nuxt repo deployed as a static site (the only option on Free) needs explicit static-export config (output: "export" for Next, nitro.preset: "static" for Nuxt), otherwise the build emits SSR artifacts the static deploy can’t serve, and the deployed site loads blank. Warning lives in projects/service-types.mdx Static site section.
• Database backups are rolling latest, not retained. heracle/internal/service/storage.go:752-755 deletes prior snapshots before each upload, so only one snapshot per project per backup type survives. Hourly schedule from BackupCronSchedule envDefault:"0 0 * * * *". Don’t claim a multi-day retention window.

​

13. Workflow for adding or editing a page

1. Read the relevant codebase paths to ground the claims.
2. Write or edit the .mdx file.
3. If new, add it to docs.json under the right group.
4. Run mintlify dev and visually verify on http://localhost:3000. Check:
   • The page renders (no 404).
   • Code blocks have syntax highlighting where expected.
   • Internal links resolve.
   • No JSX parse errors in the terminal.
5. Sweep the file for em-dashes, fabrications, em-dash-y “Verification” sections, and HTML comments.
6. Commit. Reasonable message format:

Short summary (imperative, ≤72 chars)

Sourced from <repo>/<path>:<lines>.

- bullet of what changed
- bullet of what was removed
- bullet of any constraints (e.g. "kept ABC stays as <code> until UI ships")

​

14. When the user pushes back

1. Look at the code first. Before defending or extending what’s there, search the codebase for the actual behavior. The user’s instinct that something is wrong is usually right.
2. Cut, don’t decorate. When in doubt, less is better. The user has repeatedly pulled out filler (“Verification” sections that just curl the URL, multi-language env-var examples, math-whiteboard pricing, “Why use X” sales sections, “Discriminated union” patterns). Those are high-likelihood removal candidates.
3. Acknowledge the specific mistake. Don’t generalize. If the FAQ had six fabricated entries, name the six and what was wrong about each.
4. Don’t propose to keep “less sure about” items in the user’s court while doing the rest unilaterally. When the user says “go ahead,” do all the cuts you flagged.

​

15. If you have to invent something to keep going

​

16. Mintlify config quirks

• background.color, singular, not colors. The schema field is background.color.{light, dark}. Writing background.colors fails validation with a misleading “Property colors is not allowed” error. Same shape as the colors block at the top of docs.json (which IS plural), so the inconsistency catches everyone.
• No custom-CSS hook in the mint theme schema. The styling block accepts eyebrows and codeblocks enums only, not a css path. A style.css at repo root will exist but Mintlify won’t auto-load it on deploy (https://<site>/style.css returns 404). For now we don’t have a working path for custom CSS; the orphaned style.css is intentional, kept around as a parking spot in case Mintlify ships a hook or we move to a different platform.
• There are 9 themes. mint (default), maple, palm, willow, linden, almond, aspen, luma, sequoia. Switching is a one-line "theme": "..." change in docs.json; the schema is identical across all 9 (zero theme-unique fields), so existing config keeps working.
• OpenAPI tab integration. Pass the spec path as a bare string at the tab level: { "tab": "Sandbox API", "openapi": "/api-reference/sandboxes.openapi.yaml" }. Mintlify auto-generates one page per endpoint. The object form { source, directory } is also valid but isn’t required and the directory field doesn’t change behavior here.
• SEO block shape: seo.indexing: "all" to index every page (default is "navigable", which only indexes nav-listed pages). seo.metatags is an arbitrary key→value object that becomes <meta> tags on every page (OG, Twitter Card, robots, verification tokens).
• metadata.timestamp: true shows last-modified date at the bottom of every page. Useful for trust signals.
• contextual.options controls the Copy page dropdown. Valid values include copy, view, chatgpt, claude, perplexity, grok, aistudio, devin, windsurf, cursor, vscode, mcp, add-mcp, devin-mcp. We ship ["copy", "view", "chatgpt", "claude", "perplexity"].
• Fonts: two slots, heading and body. Only heading is currently wired to Marfa (weight 700). The body font falls back to Mintlify’s default, which means bold runs in body copy also fall back to system bold. Wiring body to Marfa fixes the bold-in-paragraph appearance but also Marfa-fies all paragraph text. Choose accordingly.
• OG images: 1200×630, public URL, paired with twitter:card: summary_large_image. og:image in seo.metatags is currently a placeholder pointing at brimble.io/og.png; ensure the URL actually serves a 1200×630 image before deploy. Without one, link previews on Slack/X/Discord render text-only.
• mint dev config-level changes don’t always hot-reload. Tab additions, theme switches, seo.* and metadata.* changes often need a restart. Page content (MDX) hot-reloads fine.

​

17. The sandbox-system / build-system voice

• Title: “Inside the Brimble [thing]” or “A deep dive into [thing]”.
• First paragraph declares the audience: “This page is for the curious: developers who want to understand the system they’re trusting their workloads to.”
• Pointer to the user-facing companion doc immediately after the intro: “If you’re looking for the user-facing documentation, see …”
• H2 sections, flat (no H3 nesting unless absolutely necessary):
  1. Inside [thing], name the components, one bullet each, what they own.
  2. How the pieces fit together, Mermaid flowchart TB diagram + 1-2 callouts highlighting what’s structurally interesting.
  3. Life of a [thing], chronological walkthrough from request to terminal state. Number the steps as ### 1. ....
  4. The decisions behind the architecture, 2-3 deliberate trade-offs in “a common alternative is X; we chose Y because Z” form. No competitor names.
  5. What it means for you, measured outcomes / what the architecture buys the user.
• Voice: present-tense, declarative, no marketing words, no apology. Lift the same tonal register as Vercel’s Hive post (you can read it for cadence, but don’t quote, link, or name them).

​

18. Adding a new API tab from an OpenAPI spec

1. Drop the spec file under api-reference/[feature].openapi.yaml. Copy from the source-of-truth repo, don’t write from scratch.
2. Strip operations Brimble doesn’t expose publicly. Sweep for any description: or summary: fields that reference internal services (e.g., “Loki-backed log query”) and rewrite them user-side.
3. Confirm the spec has a servers: block with the user-facing URL (https://sandbox.brimble.io, https://api.brimble.io, etc.). Without a server URL, Mintlify renders pages with the heading but no method/path/playground.
4. Add to docs.json navigation.tabs[]:
   {
     "tab": "<Feature> API",
     "openapi": "/api-reference/[feature].openapi.yaml"
   }
   
5. Restart mint dev.
6. Verify each endpoint page renders the method+path block, request schema, response schemas, and the Try it playground. If the page is empty below the heading, the YAML probably has a broken $ref, a missing servers: block, or an OpenAPI version Mintlify doesn’t support (use 3.0.x).