update-docs

Generate Markdown documentation for the project and write it to the output directory.

The output directory is $ARGUMENTS if provided, otherwise default to docs/.

Steps

1. Check for existing docs: Glob <output-dir>/**/*.md to find any existing documentation files. Read each one so its hand-written content can be preserved and updated rather than replaced.

2. Understand the project:

   • Read build.gradle.kts, settings.gradle.kts, package.json, Cargo.toml, go.mod, pyproject.toml, or whatever build/manifest file exists to identify the project name, language, and module layout.
   • Glob source files (src/**/*, lib/**/*, cmd/**/*, etc.) to discover every module and public file.
   • Read each source file to understand its purpose, public API (exported functions, classes, interfaces, types), and how it relates to other modules.

3. Plan the doc structure: Group source files into logical sections — one doc file per module or top-level package is a good default. If the project is small enough (≤ 5 source files), a single <output-dir>/api.md is fine. Propose a sensible file layout before writing.

4. Write a doc file for each module/package:

   Each file should follow this structure (omit sections that don't apply):

   # ModuleName
   
   One-sentence description of what this module does and why it exists.
   
   ## Overview
   
   2–4 sentence explanation of the module's responsibilities and where it fits in the larger system.
   
   ## Public API
   
   ### FunctionOrClassName
   
   Signature (in the project's language) followed by a plain-English description of what it does, its parameters,
   return value, and any notable edge cases or errors.
   
   (Repeat for each exported symbol.)
   
   ## Usage examples
   
   Fenced code block showing the most common usage pattern.
   
   ## Dependencies
   
   Bullet list of other modules or external libraries this module depends on, if non-obvious.
   

5. Write or update <output-dir>/index.md: Create a table of contents that lists every doc file with a one-line description and a relative link.

6. Preserve hand-written content: Any section in an existing doc file that is not derivable from source code (e.g., design rationale, migration guides, diagrams) must be carried over verbatim.

7. Report: List every file written or updated, and note any public symbols that were undocumented in the source and lacked enough context to document accurately (so the user can fill them in).

Formatting rules

• Use # for the module name, ## for sections, ### for individual symbols.
• Use fenced code blocks with the correct language identifier for all signatures and examples.
• Keep descriptions precise and technical — avoid marketing language.
• Do not document private, internal, or implementation-detail symbols unless they are explicitly exported.
• Use relative links between doc files.

Important

• Never invent behavior. If a function's purpose is unclear from its name, signature, and surrounding code, say "Purpose unclear — needs documentation from author." rather than guessing.
• Do not overwrite an existing file wholesale if it contains hand-written sections — merge instead.
• Do not add a "Generated by AI" notice or any similar disclaimer.
• If the project has no source files, create a minimal <output-dir>/index.md with a placeholder and tell the user.