# Kitaru Documentation

This directory contains the [FumaDocs](https://fumadocs.dev/) documentation site
for Kitaru, served at [kitaru.ai/docs](https://kitaru.ai/docs).

## Prerequisites

- Node.js 22+ (pinned in `.node-version`)
- [pnpm](https://pnpm.io/) package manager

## Setup

```bash
cd docs
pnpm install
```

> **Note:** SDK reference generation requires `fumapy` (bundled in the
> `fumadocs-python` npm package). `just generate-docs` auto-installs it from
> `docs/node_modules/fumadocs-python` — no manual step needed.

## Development

From the **repo root** (recommended):

```bash
just docs           # Start dev server at localhost:3000
just docs-build     # Full static build (output in docs/out/)
just docs-validate  # Validate the static export as served under /docs
just generate-docs  # Generate CLI reference + changelog + SDK reference
```

Or from the `docs/` directory:

```bash
pnpm run dev        # Dev server with hot reload
pnpm run build      # Static export build
```

## Content Authoring

Documentation content lives in `content/docs/` as `.mdx` files (Markdown with
optional JSX components).

1. Create or edit an `.mdx` file in the appropriate directory
2. Add frontmatter with `title` and `description`
3. Update `meta.json` if adding a new page
4. Preview with `just docs`

See `CLAUDE.md` in this directory for detailed conventions and available
components.

## CI / Deployment

The docs site is deployed from this repository to
[kitaru.ai/docs](https://kitaru.ai/docs). The `.github/workflows/docs.yml`
workflow builds the static export in `docs/out/` and deploys it with a
docs-only Cloudflare Worker.

- **Production deploy:** Automatically on every push to `main`, and by manual workflow dispatch from `main`.
- **PR previews:** Same-repo PRs that touch docs-related deployment inputs — docs content, docs generation scripts, SDK source that feeds generated reference pages, workflow config, `wrangler.toml`, or dependency lockfiles — get a Cloudflare Worker preview. Fork PRs still build the docs, but do not receive deploy previews because Cloudflare secrets are unavailable.

CI runs doc generation automatically before building. Locally, you must run
`just generate-docs` yourself before `just docs-build` when generated content
(CLI reference, changelog, SDK reference) may have changed.

To build and validate the docs locally: `just generate-docs && just docs-build && just docs-validate`

## What's Generated vs Hand-Written

| File / Directory | Source | Committed? |
|---|---|---|
| `content/docs/getting-started/` | Hand-written | Yes |
| `content/docs/contributing.mdx` | Hand-written | Yes |
| `content/docs/index.mdx` | Hand-written | Yes |
| `content/docs/cli.mdx` or `cli/` | Generated by `scripts/generate_cli_docs.py` | No (gitignored) |
| `content/docs/changelog.mdx` | Generated by `scripts/generate_changelog_docs.py` | No (gitignored) |
| `content/docs/reference/python/` | Generated by `scripts/generate_sdk_docs.py` + `docs/scripts/convert-sdk-docs.mjs` | No (gitignored) |

If generated CLI syntax is wrong, fix `scripts/generate_cli_docs.py` and/or
`src/kitaru/cli.py`, then regenerate the docs. Do not hand-edit the generated
CLI pages.
