@blaaiz/docs-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blaaiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+<h1 align="center">@blaaiz/docs-core</h1>
+
+<p align="center">
+  A neutral, self-hostable documentation framework.<br>
+  Mintlify-compatible authoring · OpenAPI reference with a try-it playground · a hardened proxy.
+</p>
+
+<p align="center">
+  <a href="#status"><img alt="status" src="https://img.shields.io/badge/status-foundation-blue"></a>
+  <a href="./LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-green"></a>
+</p>
+
+---
+
+## What this is
+
+`@blaaiz/docs-core` is the shared engine for Blaaiz-family documentation sites. It wraps
+[Fumadocs](https://fumadocs.dev) and adds the pieces every docs site needs. The core owns the
+logic. Each docs site installs this package and supplies only its own config and content.
+
+- **Mintlify-compatible** — reads a `docs.json` navigation file and Mintlify-style MDX components.
+- **OpenAPI-native** — renders an API reference and an interactive try-it playground from your
+  OpenAPI files.
+- **Secure by default** — the try-it proxy forwards the caller's own token, injects no secrets, and
+  only reaches the API origins a site allow-lists. Every forward is rate-limited per client IP.
+- **Ask AI built in** — `ai: { provider: 'anthropic' }` in config is a complete setup: a streaming
+  answer panel grounded in the site's own pages, with Anthropic and OpenAI as equals. The API key
+  stays on the server.
+- **A CLI and agent skills** — `npx docs-core init` scaffolds a working site; `npx docs-core agents`
+  installs the docs-core skill for Claude Code and Codex, so an assistant edits the site correctly.
+
+> **Status** — This repository currently contains the project foundation: the toolchain, the
+> standards, and the architecture. Feature code lands next. See `docs/adr/`.
+
+## Who uses it
+
+Blaaiz publishes this as a public npm package. Any organization can install it and keep its own
+config and content private. Each site is config plus content:
+
+```
+your-docs/
+  docs.config.ts          # theme, auth mode, API allow-list
+  docs.json               # navigation
+  guides/**/*.mdx         # prose
+  api-reference/**/*.json # OpenAPI files
+  package.json            # installs @blaaiz/docs-core
+```
+
+## Start a site
+
+```bash
+npx docs-core init      # docs.config.ts, content/docs.json, starter pages, .env example
+npx docs-core agents    # the docs-core skill for Claude Code and Codex, plus AGENTS.md
+```
+
+`init` never overwrites without `--force`, and both commands print exactly what they wrote.
+
+## Wire a site
+
+Three pieces of the API reference live in this package and plug into a site:
+
+```css
+/* app/globals.css — after the fumadocs imports */
+@import '@blaaiz/docs-core/styles/docs.css';
+@import '@blaaiz/docs-core/styles/api-reference.css';
+```
+
+```tsx
+// components/api-page.tsx
+'use client';
+import { apiOperationLayout } from '@blaaiz/docs-core/ui';
+import { createOpenAPIPage } from 'fumadocs-openapi/ui';
+
+export const APIPage = createOpenAPIPage({
+  content: { renderOperationLayout: apiOperationLayout },
+});
+```
+
+Copy `patches/fumadocs-openapi.patch` into the site and register it in
+`pnpm-workspace.yaml` under `patchedDependencies`. It turns the code-sample
+language tabs into a dropdown with the endpoint name as the panel title.
+Re-check the patch on each `fumadocs-openapi` upgrade.
+
+## Design in one rule
+
+**The core owns the logic. Each site owns config and content.** If a thing is the same for every
+organization, it is in this repo. If it changes per organization, it is in the site.
+
+See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
+
+## Develop
+
+```bash
+corepack enable
+pnpm install
+pnpm run verify   # format, lint, types, architecture, tests, build, public API
+```
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full workflow.
+
+## License
+
+[MIT](./LICENSE) © Blaaiz