documentation

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!