# Contributing to IniClaw Documentation This guide covers how to write, edit, and review documentation for IniClaw. If you change code that affects user-facing behavior, update the relevant docs in the same PR. ## Use the Agent Skills If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch. | Skill | What it does | When to use | |---|---|---| | `update-docs-from-commits` | Scans recent commits for user-facing changes and drafts doc updates. | After landing features, before a release, or to find doc gaps. | The skills live in `.agents/skills/` and follow the style guide below automatically. To use one, ask your agent to run it. For example, ask it to "catch up the docs for everything merged since v0.2.0". ## When to Update Docs Update documentation when your change: - Adds, removes, or renames a CLI command or flag. - Changes default behavior or configuration. - Adds a new feature that users interact with. - Fixes a bug that the docs describe incorrectly. - Changes an API, protocol, or policy schema. ## Building Docs Locally Verify the docs are built correctly by building them and checking the output. To build the docs, run: ```bash make docs ``` To serve the docs locally and automatically rebuild on changes, run: ```bash make docs-live ``` ## Writing Conventions ### Format - Docs use [MyST Markdown](https://myst-parser.readthedocs.io/), a Sphinx-compatible superset of CommonMark. - Every page starts with YAML frontmatter (title, description, topics, tags, content type). - Include the SPDX license header after frontmatter: ``` ``` ### Frontmatter Template ```yaml --- title: page: "IniClaw Page Title — Subtitle with Context" nav: "Short Nav Title" description: "One-sentence summary of the page." keywords: ["primary keyword", "secondary keyword phrase"] topics: ["generative_ai", "ai_agents"] tags: ["openclaw", "openshell", "relevant", "tags"] content: type: concept | how_to | get_started | tutorial | reference difficulty: technical_beginner | technical_intermediate | technical_advanced audience: ["developer", "engineer"] status: published --- ``` ### Page Structure 1. H1 heading matching the `title.page` value. 2. A one- or two-sentence introduction stating what the page covers. 3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader. 4. A "Next Steps" section at the bottom linking to related pages. ## Style Guide Write like you are explaining something to a colleague. Be direct, specific, and concise. ### Voice and Tone - Use active voice. "The CLI creates a gateway" not "A gateway is created by the CLI." - Use second person ("you") when addressing the reader. - Use present tense. "The command returns an error" not "The command will return an error." - State facts. Do not hedge with "simply," "just," "easily," or "of course." ### Things to Avoid These patterns are common in LLM-generated text and erode trust with technical readers. Remove them during review. | Pattern | Problem | Fix | |---|---|---| | Unnecessary bold | "This is a **critical** step" on routine instructions. | Reserve bold for UI labels, parameter names, and genuine warnings. | | Em dashes everywhere | "The gateway — which runs in Docker — creates sandboxes." | Use commas or split into two sentences. Em dashes are fine sparingly but should not appear multiple times per paragraph. | | Superlatives | "OpenShell provides a powerful, robust, seamless experience." | Say what it does, not how great it is. | | Hedge words | "Simply run the command" or "You can easily configure..." | Drop the adverb. "Run the command." | | Emoji in prose | "Let's get started!" | No emoji in documentation prose. | | Rhetorical questions | "Want to secure your agents? Look no further!" | State the purpose directly. | ### Formatting Rules - End every sentence with a period. - One sentence per line in the source file (makes diffs readable). - Use `code` formatting for CLI commands, file paths, flags, parameter names, and values. - Use code blocks with the `console` language for CLI examples. Prefix commands with `$`: ```console $ iniclaw onboard ``` - Use tables for structured comparisons. Keep tables simple (no nested formatting). - Use MyST admonitions (`:::{tip}`, `:::{note}`, `:::{warning}`) for callouts, not bold text. - Avoid nested admonitions. - Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify." - Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage." - Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses. ### Word List Use these consistently: | Use | Do not use | |---|---| | gateway | Gateway (unless starting a sentence) | | sandbox | Sandbox (unless starting a sentence) | | CLI | cli, Cli | | API key | api key, API Key | | NVIDIA | Nvidia, nvidia | | IniClaw | iniclaw (in prose), Nemoclaw | | OpenClaw | openclaw (in prose), Openclaw | | OpenShell | Open Shell, openShell, Openshell, openshell | | mTLS | MTLS, mtls | | YAML | yaml, Yaml | ## Submitting Doc Changes 1. Create a branch following the project convention. 2. Make your changes. 3. Build locally with `make docs` and verify the output. 4. Open a PR with `docs:` as the conventional commit type. ``` docs: update quickstart for new onboard wizard ``` If your doc change accompanies a code change, include both in the same PR and use the code change's commit type: ``` feat(cli): add policy-add command ``` ## Reviewing Doc PRs When reviewing documentation: - Check that the style guide rules above are followed. - Watch for LLM-generated patterns (excessive bold, em dashes, filler). - Verify code examples are accurate and runnable. - Confirm cross-references and links are not broken. - Build locally to check rendering.