Writing Mecatl user documentation

Public documentation for Mecatl lives here. Keep site infrastructure in website/; see website/AGENTS.md for Docusaurus mechanics.

Before editing a page, read the repository's style guide and this authoring contract. Coding agents must use the tech-writer skill when editing user documentation. The style guide owns prose, voice, and terminology; this file owns information architecture, content ownership, links, and verification.

Document what readers need but cannot reasonably infer from the interface. Omit routine navigation, self-evident actions, and instructions already shown in UI hints or help. Keep non-obvious behavior, prerequisites, consequences, and limitations that affect the reader's task. A UI change does not require another walkthrough of its controls.

Find the right place

Start with the reader's task. The autogenerated sidebar follows these directories; do not create a manual sidebar to express this structure.

The top-level navigation follows three journeys: Use Mecatl, deploy and operate Mecatl, or build with Mecatl. features/ is the canonical capability spine rather than a fourth persona journey. Persona-specific pages briefly introduce shared behavior, then link to the capability page that owns it.

mecatui is a terminal client over an embedded or connected server, not a separate agent implementation. building/ is for application builders and embedders. operating/ is for people who own a deployed service.

Keep shared behavior in features/. Put differences among mecated, mecak8s, and embedded mecatui in operating/ and the capability matrix.

Keep one canonical page

One page owns the complete reader-facing treatment of a topic. Other pages may briefly introduce it for their audience, then link to the canonical page. A page can separately describe an embedding interface or a deployment-specific operation when that is the reader's task; it must not repeat the canonical feature guide.

When adding a page that appears to overlap an existing page, identify its canonical page in the pull request description. If the two pages need the same complete treatment, extend the canonical page instead. URL moves are separate changes and must follow the published URL policy in website/AGENTS.md.

Extend an existing page when it already answers the reader's question. Add a page only for a distinct user task or concept that has no suitable home. New section directories need an entry page and _category_.json so the autogenerated sidebar has an entry point and label. Use index.md for a new section; when splitting an existing guide into workflow pages, the category can link to that guide as its entry point. Keep its published URL and avoid adding a second overview that answers the same question.

Write a page

Use front matter on every documentation page. At minimum, provide a sentence-case title and a reader-focused description; add sidebar_position when the page's order matters. Add an explicit Markdown H1 immediately after the front matter that matches title. Docusaurus uses the explicit H1 in the rendered page and uses title for page metadata, while the H1 keeps the file readable on GitHub.

Use sidebar_label only when a shorter sidebar label materially improves navigation. It changes the autogenerated sidebar label without changing the page title or H1.

---
title: Page title
description: State the reader outcome or topic in one sentence.
sidebar_position: 1
---

# Page title

Write about current behavior in clear technical prose. Keep roadmap discussion explicitly separated in cloud-native-harness.md; public task guides and reference must describe delivered surfaces. Contributor qualification commands and test receipts belong in the owning internal documentation. Preserve verified operator limitations when trimming that material.

Use sentence-case headings, descriptive links, and examples that help readers complete a task. Style Mecatl as a proper noun, and write the component and binary names mecatui, mecated, and mecak8s in code font. For deeper guidance, see Diataxis and the Google developer documentation style guide.

End a tutorial or task-oriented guide with ## Next steps when readers have a clear next action. Reference, explanation, index, and narrow troubleshooting pages do not need that section.

Terminology

Use lowercase, hyphenated cloud-native harness except at the start of a sentence, heading, or navigation label, where Cloud-native harness follows ordinary sentence case. Use cloud-native for ordinary adjectives, such as "cloud-native deployment" or "cloud-native workload." Use cloud-native agent harness as a generic description. Do not use "cloud-native kit" in public documentation.

Use content-root-relative Markdown paths for links across sections, including the .md extension:

[Run mecated standalone](/operating/mecated.md)

For a sibling in the same directory, use a relative .md path. Do not use a /docs/ prefix. The link rules and their Docusaurus rationale live in website/AGENTS.md.

Verify behavior

Start with the applicable implementation source:

• docs/architecture/*.md for subsystem behavior
• contracts/proto/ for gRPC messages and services
• command flag registration, configuration schemas, handlers, and adapters for deployed behavior

Generated reference pages are exceptions to direct editing:

• For reference/server-cli.md, change flag registration/help or scripts/server-cli-reference.py, then run task docs:server-cli. Never edit the generated output by hand.
• For reference/configuration.md, change the configuration schema or generator, then run task docs:configref.
• For reference/typescript-sdk-api/core.md, node.md, and deno.md, change the TSDoc in sdk/typescript/src/ or the SDK documentation generator, then run task sdk:docs. Use task sdk:docs:check to verify that the committed output is current without changing it.

Confirm availability and defaults against the shipped public surface: flags or configuration, composition, capability advertisement, handlers, and deployed adapters. A port, proto, or constructor alone does not prove that a feature ships. Do not write from AGENTS.md or CLAUDE.md directly. They are internal contracts with implementation detail, not user documentation.

For a feature page, lead with the outcome, then cover prerequisites, a short happy-path example, configuration or permissions, and relevant deployment limits. Report uncertainty when the available evidence does not establish a claim.

Preview and check

Run these commands from the repository root:

task site:dev    # preview at http://localhost:3001
task site:build  # production build and broken-link check
task site:format # prettier normalization pass (optional, not CI-enforced)

task site:build is required for a documentation change. It fails on broken links. task site:format is optional prose/list/table normalization; nothing in CI checks formatting. It skips the generated reference pages listed above (user-docs/.prettierignore) so it never fights their own generators. Do not put working plans, authoring ledgers, or internal implementation queues in user-docs/; keep them in issues or pull request descriptions.