---
name: documentation
description: Documentation deep-dive for the poku website covering Docusaurus setup, language policy, feature-to-docs mapping, conventions, JSDoc, and the changelog. Use when editing or adding docs or mapping a feature to its page.
---

Documentation conventions and where to look. Read the actual `website/` tree and config to confirm details, since pages and versions change over time.

### 1. Framework & Config

- Docusaurus 3.x at `website/`. For the exact version, read `website/package.json`
- Config: `website/docusaurus.config.ts`. Sidebar: `website/sidebars.ts` (top-level items are manual, the docs/tutorials/examples categories are autogenerated from their directories)
- Versioning: the `current` docs are the active version, older majors are kept but marked unmaintained. Read the `versions` block in `website/docusaurus.config.ts` and `website/versions.json` for the live set of versions and their labels

### 2. Language Policy

- English is mandatory. Use i18n (`website/i18n/`) only on explicit user request

### 3. Documentation Structure

The docs live under `website/docs/`:

- Root pages cover the homepage, philosophy, and the comparison with other runners
- `documentation/` is the API reference, organized by area: assertions, helper APIs (under `helpers/`), and the `poku` runner with its CLI options (under `poku/`)
- `tutorials/` holds guided walkthroughs and `examples/` holds runnable examples

Read the `website/docs/` tree to discover the current pages rather than relying on a fixed list here, since pages are added and reorganized.

### 4. Feature-to-Docs Mapping

There is a close (not strictly 1:1) mapping between helper APIs in `src/modules/helpers/` and pages under `website/docs/documentation/helpers/`. Conventions to expect:

- Most helpers have a matching page of the same name
- Related helpers are sometimes grouped into a subdirectory (for example, process-related helpers)
- A single source helper can be split across multiple pages, and a single page can cover more than one export
- The config option types inform the `poku/options/` pages
- The public surface is whatever `package.json` `exports` define, not the internal file layout

To find the doc for a feature, read the helpers directory and the docs directory and match by responsibility, rather than trusting a fixed table.

### 5. Documentation Conventions

When reading or writing docs, follow these patterns:

- **Front matter**: YAML with `sidebar_position` and `tags`
- **Page structure**: function signature (`> fn(params)`) then Basic Usage then Advanced then FAQ
- **Components**: reusable MDX components live in `website/src/components/` (for example `FAQ`, and `History` to document when a feature became available or had breaking changes across versions). Docusaurus components like `Tabs`/`TabItem` are also available
- **Category organization**: `_category_.json` files
- **Punctuation**: Use proper punctuation. Never use any kind of substitute as a crutch
- **Consistency**: Match the writing style, tone, and structure of the related existing docs

### 6. Inline Documentation (JSDoc)

- Type definitions live in `src/@types/`
- Pattern: description plus an `@default` tag
- These inform the documentation content

### 7. LLM Docs (Context7)

- `website/llms/` holds docs written for LLMs and indexed by Context7, separate from the human-facing pages in `website/docs/`
- Current files: `llms.md` (the llms.txt entry point, symlinked to `website/static/llms.txt`), `comparing.md`, and `philosophy.md`
- `context7.json` at the repo root controls what Context7 indexes and how it guides the agent through the `folders` allowlist (which includes `website/llms`), the `description`, and the `rules`
- The `description` and `rules` have Context7 length limits, validated by `test/unit/context7-rules.test.ts`

### 8. Changelog

- `CHANGELOG.md` is auto-generated: **NEVER** edit it!