@blaaiz/docs-core 0.1.0

package/skills/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: docs-core
+description: Work on a documentation site built with @blaaiz/docs-core. Use whenever a task touches docs.config.ts, content/docs.json, content/docs/**, or an import from @blaaiz/docs-core — adding or reordering doc pages, tabs, and groups; publishing an OpenAPI endpoint with the try-it playground; changing theme colours, the logo, or the favicon; setting up public or workspace authentication; turning on Ask AI, copy-page, search, or SEO; or fixing an error the framework raises.
+---
+
+# docs-core
+
+`@blaaiz/docs-core` is a documentation framework that wraps Fumadocs and adds the
+parts every docs site repeats: navigation, theming, access control, an OpenAPI
+reference with a try-it playground, LLM-ready page export, search, SEO, and Ask
+AI. It has zero runtime dependencies.
+
+**The golden rule: the core owns the logic, the site owns config and content.**
+If a thing is the same for every organization, it is inside the package. If it
+changes per organization, it is in the site.
+
+So: **never edit anything under `node_modules/@blaaiz/docs-core`.** Every change
+you make lands in `docs.config.ts`, `content/docs.json`, a content file, or one
+of the site's own wiring files. A change that seems to need a package edit is
+either a config field you have not found yet, or a framework change that belongs
+in the `docs-core` repository — say so instead of patching the install.
+
+## The files that matter
+
+| File                                | Owned by      | Edit it to                                                                     |
+| ----------------------------------- | ------------- | ------------------------------------------------------------------------------ |
+| `docs.config.ts`                    | the site      | Change the brand, the access mode, the proxy allow-list, features, SEO, Ask AI |
+| `content/docs.json`                 | the site      | Change what is published and in what order: tabs, groups, pages, API endpoints |
+| `content/docs/**/*.mdx`             | the site      | Write or edit prose                                                            |
+| `content/**/*-openapi.json`         | the site      | Add or change an API endpoint's spec                                           |
+| `content/docs/**/meta.json`         | see below     | Sidebar order                                                                  |
+| `content/nav.json`                  | see below     | Top-navigation links, one per tab                                              |
+| `content/api-methods.json`          | the generator | Sidebar method badges — never by hand                                          |
+| `content/docs/api/**`               | the generator | Generated endpoint pages — never by hand                                       |
+| `app/**`, `lib/**`, `middleware.ts` | the site      | Wiring: routes, layouts, the page tree                                         |
+
+`meta.json` and `nav.json` are hand-written on a prose-only site. On a site with
+an API reference the generator writes them from `docs.json` on every run, so
+hand edits are lost — change `docs.json` instead. A site runs the generator when
+its `package.json` has a `predev` / `prebuild` script calling
+`@blaaiz/docs-core/generator`; check that first.
+
+## docs.config.ts
+
+One call to `defineDocsConfig`. It returns its argument unchanged; it exists for
+type-checking and completion.
+
+```ts
+import { defineDocsConfig } from '@blaaiz/docs-core';
+
+export default defineDocsConfig({
+  theme: { name: 'Example Docs', colors: { primary: '#4c63f5' } },
+  auth: 'public',
+  proxy: { allowedOrigins: [] },
+});
+```
+
+`theme`, `auth`, and `proxy` are required. `features`, `seo`, and `ai` are
+optional, and omitting one leaves everything it controls off.
+
+### theme
+
+| Field        | Type              | Default            | Notes                                               |
+| ------------ | ----------------- | ------------------ | --------------------------------------------------- |
+| `name`       | string            | —                  | Required. Display name, and the base for SEO titles |
+| `logo`       | `{ light, dark }` | none               | Image paths the site serves                         |
+| `favicon`    | string            | none               | Path the site serves                                |
+| `colors`     | palette           | framework defaults | Light theme, and the base for dark                  |
+| `darkColors` | palette           | inherits `colors`  | Dark-theme overrides only                           |
+
+A palette accepts `primary`, `background`, `foreground`, `card`, `border`, and
+`muted`. Every token is optional. `buildThemeCss(config.theme)` turns the palette
+into CSS variables; the site's root layout injects the result.
+
+### auth
+
+`'public'` or a workspace block. Public mode needs no middleware, no sign-in
+page, and no auth routes.
+
+| Field               | Type          | Default               | Notes                              |
+| ------------------- | ------------- | --------------------- | ---------------------------------- |
+| `mode`              | `'workspace'` | —                     | Required                           |
+| `allowedDomains`    | string[]      | —                     | Email domains permitted to sign in |
+| `providers`         | object        | —                     | Any combination of the three below |
+| `signInPath`        | string        | `/signin`             | Where the gate redirects           |
+| `sessionSecretEnv`  | string        | `DOCS_SESSION_SECRET` | Env var holding the signing key    |
+| `sessionTtlSeconds` | number        | 8 hours               | Session lifetime                   |
+| `secureCookies`     | boolean       | `true`                | Set `false` only for local http    |
+
+Providers:
+
+| Provider | Shape                                               | Env vars                                   |
+| -------- | --------------------------------------------------- | ------------------------------------------ |
+| `email`  | `true`                                              | —                                          |
+| `secret` | `{ secretEnv? }`                                    | `DOCS_ACCESS_SECRET`                       |
+| `google` | `{ clientIdEnv?, clientSecretEnv?, redirectPath? }` | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |
+
+`secret` supersedes `email` when both are enabled: offering email-only as well
+would let a reader skip the secret. `google`'s `redirectPath` defaults to
+`/api/auth/google/callback`.
+
+### proxy
+
+| Field                | Type     | Notes                                                                                                                |
+| -------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `allowedOrigins`     | string[] | Security-critical. The exhaustive list of upstream origins the try-it playground may reach. Anything else is refused |
+| `rateLimitPerMinute` | number   | Forwards per minute per client IP. Default 60. Enforced by both proxy factories                                      |
+
+The proxy forwards the reader's own credentials and injects none of its own. It
+also refuses loopback, private, and link-local hosts, so it cannot be used as an
+SSRF relay. An empty `allowedOrigins` is correct for a site with no API
+reference.
+
+Pass the limit through when you mount the route, or the default of 60 applies:
+
+```ts
+export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = createTryItProxyRoute({
+  allowedOrigins: config.proxy.allowedOrigins,
+  rateLimitPerMinute: config.proxy.rateLimitPerMinute,
+});
+```
+
+A caller over the limit gets `429`, a `Retry-After` header, and the body
+`{ "error": "Too many requests. Try again in 60 seconds.", "retryAfterSeconds": 60 }`.
+The key is the client IP: the first entry of `x-forwarded-for`, then
+`x-real-ip`, then one shared bucket. The window is in memory per server process.
+
+### features
+
+| Field      | Default | Effect                                                                         |
+| ---------- | ------- | ------------------------------------------------------------------------------ |
+| `copyPage` | `false` | Shows the "Copy page / View as Markdown" control and serves the Markdown route |
+
+### seo
+
+| Field           | Default               | Notes                                                                    |
+| --------------- | --------------------- | ------------------------------------------------------------------------ |
+| `siteUrl`       | none                  | Canonical origin. Without it, canonical and Open Graph URLs are relative |
+| `titleTemplate` | `'%s · <theme.name>'` | `%s` is the page title. The home title is `theme.name` verbatim          |
+| `description`   | none                  | Used where a page declares none                                          |
+| `ogImage`       | none                  | Default sharing image                                                    |
+| `twitter`       | none                  | `@handle` for card attribution                                           |
+| `keywords`      | none                  | Applied site-wide                                                        |
+| `noindex`       | `false`               | Set `true` on a private or pre-launch site                               |
+
+### ai
+
+Naming a provider is a complete setup. Every other field has a default.
+
+| Field                | Default                                | Notes                                        |
+| -------------------- | -------------------------------------- | -------------------------------------------- |
+| `provider`           | —                                      | Required: `'anthropic'` or `'openai'`        |
+| `model`              | `claude-sonnet-5` / `gpt-5-mini`       | Validated against the provider's allow-list  |
+| `apiKeyEnv`          | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | The env var, never the key                   |
+| `rateLimitPerMinute` | `10`                                   | Per client IP, 1–600. Always enforced        |
+| `maxContextPages`    | `6`                                    | Pages retrieved per question, 1–20           |
+| `systemPrompt`       | none                                   | Extra instructions, 4000 characters or fewer |
+
+Allowed models:
+
+- **anthropic** — `claude-sonnet-5`, `claude-haiku-4-5`, `claude-opus-5`,
+  `claude-opus-4-8`, `claude-sonnet-4-6`
+- **openai** — `gpt-5-mini`, `gpt-5`, `gpt-5.2`, `gpt-5-nano`, `gpt-4.1`,
+  `gpt-4.1-mini`, `gpt-4o`, `gpt-4o-mini`
+
+The whole `ai` block is validated when the route is built, so a typo fails the
+build rather than a reader's question. An API key never belongs in this file.
+
+## content/docs.json
+
+The navigation, and the only thing that decides what is published.
+
+```json
+{
+  "name": "Example Docs",
+  "navigation": {
+    "tabs": [
+      { "tab": "Home", "icon": "house", "pages": ["index", "quickstart"] },
+      {
+        "tab": "Guides",
+        "icon": "book",
+        "groups": [
+          { "group": "Getting started", "pages": ["guides/install", "guides/config"] },
+          { "group": "Advanced", "pages": ["guides/webhooks"] }
+        ]
+      },
+      {
+        "tab": "API reference",
+        "icon": "code",
+        "groups": [
+          {
+            "group": "Authentication",
+            "pages": [
+              "api-reference/user/auth/login-openapi.json POST /api/user/login",
+              "api-reference/user/auth/register-openapi.json POST /api/user/register"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Rules the parser enforces:
+
+- A tab needs a string `tab` title. It carries either `pages` or `groups`, never
+  both — `groups` wins if both appear.
+- A group needs a string `group` title and a `pages` array. Groups nest: a
+  `pages` array may hold group objects.
+- A page string is either a content path relative to `content/docs`, without the
+  `.mdx` extension, or an OpenAPI entry shaped `<file> <METHOD> <route>`.
+- `icon` is optional on a tab, and the site resolves the name through `docsIcon`.
+- Order in the file is order in the sidebar.
+
+## Task recipes
+
+### Add a doc page
+
+1. Create `content/docs/<path>.mdx` with a frontmatter `title` and `description`.
+2. Add `"<path>"` to the right `pages` array in `content/docs.json`, in the
+   position you want it.
+3. On a prose-only site, add the same entry to the folder's `meta.json` `pages`
+   array. On an API site, re-run the generator instead.
+4. Run the typecheck and the build.
+
+### Add a tab
+
+1. Add a tab object to `navigation.tabs` in `content/docs.json`, with `tab`,
+   `icon`, and either `pages` or `groups`.
+2. Create every page the tab lists.
+3. Add the tab's folder to the root `content/docs/meta.json` `pages` array, and
+   give the folder its own `meta.json` with `"root": true`, a `title`, and an
+   `icon`. On an API site, re-run the generator instead.
+4. Add the tab to `content/nav.json` — `{ text, url, icon }`, pointing at its
+   first page. The generator writes this file on an API site.
+
+### Add an API endpoint
+
+1. Create one OpenAPI file holding one operation. The name must end in
+   `-openapi.json`. Give the operation an `operationId`: it becomes the page
+   slug. Without one, the slug is derived from `METHOD path`.
+2. Add the entry to `content/docs.json` in the group where it belongs:
+   `"<file> <METHOD> <route>"`, with the file path relative to `content`.
+3. Re-run the generator: `pnpm generate:api`, or whatever script calls
+   `generateDocsTree`. It merges the specs, writes one page per declared
+   endpoint into its group folder, and rewrites `meta.json`, `nav.json`, and
+   `api-methods.json`.
+4. Check the page renders and the try-it panel targets an allow-listed origin.
+
+An operation that exists in a spec but is not declared in `docs.json` gets no
+page. The navigation decides what is published. The API folder is deleted and
+rebuilt on every run, so a removed endpoint leaves no stale page.
+
+### Change theme colours
+
+Edit `theme.colors` and `theme.darkColors` in `docs.config.ts`. Nothing else:
+the site's layout already turns the palette into CSS variables. Set `primary` in
+both palettes — a light-theme accent rarely has enough contrast on a dark
+background.
+
+### Enable Ask AI
+
+1. Add one line to `docs.config.ts`: `ai: { provider: 'anthropic' }`.
+2. Set `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`) in the server environment. Never
+   in `docs.config.ts`, never in a `NEXT_PUBLIC_` variable.
+3. Mount the route. It needs the Node runtime, because the corpus is read from
+   the MDX files on disk:
+
+   ```ts
+   // app/api/ai/route.ts
+   import { createAskAiRoute } from '@blaaiz/docs-core';
+   import config from '@/docs.config';
+   import { askAiDocuments, loadAskAiPageMarkdown } from '@/lib/ask-ai';
+
+   export const runtime = 'nodejs';
+
+   export const { POST } = createAskAiRoute({
+     config: config.ai!,
+     siteName: config.theme.name,
+     documents: askAiDocuments,
+     loadPageMarkdown: loadAskAiPageMarkdown,
+   });
+   ```
+
+4. Mount the panel once in the docs layout, and import its stylesheet in
+   `app/globals.css`:
+
+   ```tsx
+   import { AskAi } from '@blaaiz/docs-core/ui/ask-ai';
+   // <AskAi endpoint="/api/ai" /> — endpoint defaults to /api/ai
+   ```
+
+   ```css
+   @import '@blaaiz/docs-core/styles/ask-ai.css';
+   ```
+
+`AskAi` accepts `endpoint`, `suggestions`, `label`, and `placeholder`, and all
+four have defaults.
+
+### Enable copy page
+
+1. Set `features: { copyPage: true }` in `docs.config.ts`.
+2. Render `CopyPageButton` from `@blaaiz/docs-core/ui/copy-page` in the page
+   component, guarded by `config.features?.copyPage`.
+3. Serve the Markdown: `createMarkdownRoute({ read })` in
+   `app/md/[[...slug]]/route.ts`, where `read` returns a page's raw MDX.
+
+### Set up workspace auth with the shared secret
+
+1. In `docs.config.ts`:
+
+   ```ts
+   auth: {
+     mode: 'workspace',
+     allowedDomains: ['example.com'],
+     providers: { secret: { secretEnv: 'DOCS_ACCESS_SECRET' } },
+   }
+   ```
+
+2. Set `DOCS_SESSION_SECRET` (a long random value — `openssl rand -hex 32`) and
+   `DOCS_ACCESS_SECRET` in the server environment.
+3. Mount `createSecretSignIn` on a route, and `createAuthGate` in
+   `middleware.ts`. Import `@blaaiz/docs-core/styles/auth.css` for `AuthScreen`.
+4. Check the middleware matcher covers every route that must be gated. A matcher
+   that misses a route leaves that route open.
+5. Consider `seo: { noindex: true }` on a gated site.
+
+## Verification habits
+
+- Run the site's `typecheck` and `build` after every change. A config mistake
+  usually fails at build time by design.
+- After an API change, re-run the generator and confirm the page count it
+  reports matches the endpoints you declared.
+- Never hand-edit `content/docs/api/**`, `content/api-methods.json`, or — on a
+  site that runs the generator — `meta.json` and `nav.json`. They are outputs.
+- Check a content change in the browser at `/docs`: sidebar order, the top nav,
+  and search.
+- A palette change needs a look in both light and dark mode.
+
+## Troubleshooting
+
+Each message below is raised verbatim by the framework.
+
+| Message                                                                                    | Cause and fix                                                                                                                        |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `ai.provider must be one of 'anthropic', 'openai', got '…'.`                               | Typo in `docs.config.ts`. Use one of the two names                                                                                   |
+| `ai.model must be one of '…' for provider '…', got '…'.`                                   | The model is not on that provider's allow-list. Use a listed id, or leave `model` out for the default                                |
+| `Ask AI is not configured: set the ANTHROPIC_API_KEY environment variable on the server.`  | The route is mounted but the key is missing. Set the env var named by `ai.apiKeyEnv` where the server runs — not in `docs.config.ts` |
+| `Target origin is not allow-listed: https://api.example.com`                               | The try-it request targets an origin missing from `proxy.allowedOrigins`. Add it, exactly, scheme included                           |
+| `Blocked host: localhost`                                                                  | The proxy refuses loopback, private, and link-local hosts on purpose. Point the playground at a reachable public origin              |
+| `docs.json navigation must have a "tabs" array.`                                           | `content/docs.json` is missing `navigation.tabs`. The older Mintlify `navigation` array form is not supported                        |
+| `Navigation entry at navigation.tabs[N].pages[M] must be a page string or a group object.` | That entry is neither a string nor an object with a `group` key. A common cause is `{ "page": "…" }`                                 |
+| `Group at <path> is missing a string "group" title.`                                       | Add the `group` title, or move a bare string into `pages`                                                                            |
+| `Duplicate operation POST /api/x across inputs.`                                           | Two OpenAPI files define the same method on the same route. The merge refuses to overwrite silently — delete one                     |
+| `Each OpenAPI input must have a "paths" object.`                                           | One spec file is not a real OpenAPI document. Even a one-operation file needs `paths`                                                |
+| `[docs-core] docs.json references POST /api/x, but <file> defines no such operation.`      | The `docs.json` entry and the spec disagree on method or route. Fix whichever is wrong                                               |
+
+Error classes are exported, so a site can branch on them:
+`InvalidNavigationError`, `OpenApiMergeError`, `ProxyTargetError`, and
+`AiConfigError`.
+
+Full documentation: <https://docs-core.blaaiz.dev>