> ## Documentation Index > Fetch the complete documentation index at: https://docs.guardway.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLAUDE # CLAUDE.md Guidance for **Claude Code** in this repository. ## What this is Mintlify documentation for **Guardway** — a self-hosted LLM gateway governed from a SaaS dashboard. Published at **docs.guardway.ai**, auto-deployed from `main` by Mintlify's GitHub integration. Theme: `maple`. ## Commands ```bash theme={null} docker compose up dev # local preview, http://localhost:3001 docker compose --profile check run --rm broken-links # what the PR check runs # Or if Node 20 is on the host: mintlify dev mintlify broken-links mintlify build ``` ## Where everything lives * [`docs.json`](./docs.json) — the only config file. Navigation, branding, colors, fonts, anchors, redirects, SEO, contextual menu, 404, OG metadata. * `getting-started/`, `platform/`, `guardway-gateway/`, `discovery/`, `resources/`, `api-reference/`, `changelog/` — MDX content. Folder structure mirrors the `navigation.groups` order in `docs.json`. * `images/logo.png` — 256×256 orange mark (source for the wordmark). * `images/wordmark-{light,dark}.svg` — combined mark + "Guardway Docs" text. What renders as the navbar logo. Regenerate via the HTML+headless-Chrome workflow used in git history if you need to change text or weight. * `images/og.png` — 1200×630 social preview card. Wired through `metadata.og:image`. * `images/icons/mcp.svg` — custom sidebar icon for the MCP page. * `images/providers/-{light,dark}.{svg,png}` — brand logos for the provider grid on `connect-provider`. * `images/screenshots///*.png` — screenshot placeholders mirroring the sidebar tree (`platform/dashboard/`, `platform/configuration/`, `platform/settings/`, `platform/logs/`, `platform/playground/`, `gateway/deployment/`, `discovery/`, `getting-started/`). `.gitkeep` files keep empty folders committed; drop PNGs in directly. * `.github/workflows/pr-checks.yml` — broken-links + build check on every PR. * [`Dockerfile`](./Dockerfile) + [`docker-compose.yml`](./docker-compose.yml) — local dev with Node 20 (Mintlify doesn't support newer Node). ### Sidebar tree (mirrors the dashboard menu) ``` Getting Started introduction · quickstart · sign-up Platform overview Dashboard overview · usage · spend · security logs (tabs Requests / MCP / Guardrails / Traces as ## sections) playground Configuration providers · api-keys · models · security · routing · members Settings organization · members · roles · pricing · notifications · integrations · audit-log · traffic · console Gateway overview · requirements · functionalities Deployment deploy · environment · activate Discovery overview · organizations · repositories · findings Resources faq · privacy-and-security · glossary · limitations · support API Reference coming-soon (placeholder, kept) Changelog (top-right anchor only — not a sidebar group) ``` Page **labels match dashboard menu wording exactly**. Tabs become `##` sections inside one page (e.g. Logs has Requests / MCP / Guardrails / Traces sections; Traffic has Rate Limits / Cache; Configuration → Security has MCP / Guardrails / SLM Guardrails). Don't split tabs into separate pages. ## Design (non-obvious, don't re-derive) * Layout inspiration: [docs.perplexity.ai](https://docs.perplexity.ai). Top-level groups with icons, theme toggle in default Mintlify position. * Brand primary `#EC9322` (light `#F5B04D`, dark `#C97A1A`) — set once in `docs.json`, never override inline. * Font: **Inter** via `docs.json.fonts`. Do not import fonts in MDX or add custom CSS. * Logo is a **combined wordmark SVG** (mark base64-embedded + "Guardway Docs" in Inter 800) because Mintlify's `name` text rendering hits a hard navbar-height cap and longer strings shrink to fit width. The wordmark lets us control the visual weight. * **API reference** is deliberately a **Coming soon** placeholder. Keep the group in the nav. * **Changelog** lives as a top-right *anchor*, not a sidebar group. Entries use ``. * Maple theme caps logo height at \~28 px. Source SVGs are sized for that cap. ## Content rules * **Accuracy over polish.** Route paths (`/dashboard/...`), button labels, and feature lists must match the dashboard in `../guardway-dashboard`. If you're unsure, read the component source under `../guardway-dashboard/src/features/` or run `npm run dev` there before writing. * **Page template.** Every non-landing page starts with `## What this is for` (2–4 sentences: who uses it, what problem it solves, where it lives in the dashboard), followed by `## Options` (bullets/tables mirroring exact field labels), `## How to configure` (numbered ``), and optional `## Permissions` / `## Limits` / `## Related`. One docs page per dashboard menu item; tabs become `##` sections. * **Verbatim labels.** Buttons, fields, status pills, and role names use the exact strings from the dashboard. Roles are **Owner / Admin / Read Only** (never "viewer", "member", or "editor"). * **No-API-surface rule.** Docs must not mention any platform API endpoint, path, or hostname. The platform API is internal to the dashboard and is not part of the customer surface. The **single allowed exception** is the `GUARDWAY_CLOUD_URL` gateway env var, described generically as "the Guardway control plane URL" — never list the actual hostname or any path on customer-facing pages. * **Do not invent version history.** The changelog contains only things that actually shipped. No fake "v2.5 — ML-Powered Threat Detection" entries. * **Screenshots are placeholders.** Use `` with `/images/screenshots///-.png` (lowercase, kebab-case) and an MDX comment: `{/* TODO(screenshot): */}`. Do not fabricate screenshots. * **Audit logs are local-only.** Any page that mentions audit logs must say so (mirrors the workspace-root rule in `../.cursor/rules/audit-logs-local-only.mdc`). Even `platform/settings/audit-log.mdx`, despite living under Platform, reads from the local gateway — the page already explains this; don't regress it. * **Title case** for multi-word page titles ("Audit Log", "API Keys", "Rate Limits"). Lowercase conjunctions (`and`, `of`, `or`). * **Provider grid** on `platform/configuration/providers.mdx` uses an MDX component (defined at the top of that file). New providers: drop logo files + add one `` line. ## Changelog rule Every PR must add **one** dated `` block to [`changelog/whats-new.mdx`](./changelog/whats-new.mdx). Typo-only fixes are exempt. Do not edit older `` blocks to backfill changes. Entries are **customer-facing only.** Do **not** reference PR numbers, commit SHAs, internal ticket IDs, reviewer names, or implementation details. Describe what a reader of the docs will notice changed — a new section, an updated configuration table, a corrected screenshot, a removed/merged page (with redirect note). Pick **exactly one** tag per entry: | Tag | Use when | | --------- | --------------------------------------------------------------------------------- | | `Added` | A new page or section landed. | | `Updated` | An existing page was revised to match current behavior. | | `Fixed` | Wrong info, broken link, or stale caption was corrected. | | `Removed` | A page was deleted or merged. Always paired with a redirect entry in `docs.json`. | Automation from dashboard prod deploys is **not built**. Add entries by hand in the same PR as the content change. ## Adding a new dashboard menu item When a new menu entry ships in the dashboard, mirror it here in one PR: 1. Locate the new entry in `../guardway-dashboard/src/config/nav-config.ts` and note the **exact label**, the parent menu, and the route path. 2. Pick the matching docs sub-group in [`docs.json`](./docs.json) (e.g. `Settings` → `platform/settings/`). Create the MDX file at `//.mdx` using the page template (`## What this is for` first, then `## Options`, `## How to configure`, optional `## Permissions` / `## Limits` / `## Related`). 3. Add the page to `navigation.groups` in `docs.json`, in the same order it appears in the dashboard menu. 4. Insert the `` placeholder under `## How to configure` pointing at `/images/screenshots///-.png` with a `{/* TODO(screenshot): … */}` comment. Create the sub-folder + `.gitkeep` if it doesn't exist yet. 5. Add a one-line `` block to `changelog/whats-new.mdx` with the `Added` tag. 6. If the new menu item replaces an old page, add a permanent redirect to `docs.json.redirects` and tag the changelog entry as `Removed` for the old slug (separate entry). 7. Run `mintlify build` and the broken-links check before opening the PR. ## Redirects Every time you rename, move, or delete a page, add a permanent redirect to `docs.json.redirects`. Current redirects cover: `configuration → environment`, `features → functionalities`, `whats-new` route move, `webhooks` from gateway to platform, old `troubleshooting/*` and `api-reference/glossary` URLs. Don't break bookmarks. ## MDX components available ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``, ``. Icons are Font Awesome or Lucide names, or paths to local SVGs (e.g. `icon: /images/icons/mcp.svg`). ## Deployment Mintlify auto-deploys `main` to `docs.guardway.ai`. Branch pushes get a preview URL from the Mintlify GitHub app. Do not add any other build / deploy configuration. ## Issue creation (read before opening any issue) Issues in this repo follow a structured template at `.github/ISSUE_TEMPLATE/issue.yml` (docs-variant — overrides the org default). The template renders automatically only in GitHub's web UI — `gh issue create` and the API bypass it. So you, Claude, must apply it manually. **Before calling `gh issue create`:** 1. Fetch the template: `gh api repos/guardwayai/guardway-docs/contents/.github/ISSUE_TEMPLATE/issue.yml --jq '.content' | base64 -d` 2. Render the issue body using the template's sections, in this order: * **Context / Why** — the problem, what prompted this, prior context * **Proposed change** — be specific (file paths, function names, expected behavior) * **Acceptance criteria** — checkbox list, each one testable * **Preview link** — Mintlify preview URL (or "N/A" with reason for content-only edits) * **Out of scope** — explicit non-goals * **Related** — cross-repo issues, ADRs, prior PRs 3. Title format: `[type(scope)]: short description` (type ∈ `fix|feat|perf|refactor|chore|docs`). 4. After creating, set the **Issue Type** (Bug / Feature / Performance / Refactor / Chore / Docs) and a **`priority:*`** label. Add `security` / `cross-repo` / `breaking-change` flags only if they apply. Skipping any of Context / Proposed change / Acceptance criteria / Preview link is the most common defect when issues are created via the API. Don't ship an issue missing those sections — better to ask the user for the missing piece than to invent it.