Documentation Index

Fetch the complete documentation index at: https://paper.brimble.io/llms.txt

Use this file to discover all available pages before exploring further.

​

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
index.mdx                  Docs home page (cards grid)
README.md                  Human-facing repo readme (mintlify dev, conventions)
ASSISTANT.md               This file
fonts/                     ABC Marfa woff2 files (referenced from docs.json)
images/<area>/             Screenshots, organized by doc area

getting-started/           First-deploy flow
projects/                  Project lifecycle, builds, deployments, service types, scaling
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.

​

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 runners, 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.”

​

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.

​

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