Hierarchical autodoc + documentation for multi-package repos

[tsavo-at-pieces]

Context

Multi-package repositories (e.g., dart_custom_lint with 5 sub-packages) now have hierarchical support for changelogs and release notes — the compose and release-notes commands call SubPackageUtils.enrichPromptWithSubPackages() to inject per-package diff context and formatting instructions into the Gemini prompt, producing output like:

## [0.8.3] - 2026-02-24
### Summary
High-level summary covering ALL packages...
### custom_lint
#### Added
- ...
### custom_lint_core
#### Fixed
- ...

However, autodoc (module documentation) and documentation (README.md generation) remain single-package-aware. This issue tracks adding hierarchical sub-package support to both.

Current State

Artifact	Command	Sub-Package Support	Hierarchical Format
CHANGELOG.md	compose	Full	Yes — per-package sections
Release Notes	release-notes	Full	Yes — per-package sections
Module Autodocs	autodoc	None	None
README.md	documentation	None	None

Problem

1. Autodoc (lib/src/cli/commands/autodoc_command.dart)

The autodoc command generates per-module documentation via autodoc.json configuration. Each module is documented independently with Gemini Pass 1 (Author) and Pass 2 (Reviewer). For multi-package repos:

• No sub-package grouping — modules from different sub-packages are documented in a flat list without knowing which package they belong to
• No cross-package awareness — Gemini can't describe how modules in custom_lint_core relate to modules in custom_lint_builder
• No hierarchical output structure — generated docs don't organize by sub-package
• No call to enrichPromptWithSubPackages() — the prompt lacks multi-package context entirely

2. Documentation (lib/src/cli/commands/documentation_command.dart)

The documentation command updates README.md using Gemini with commit_analysis.json and the current README as context:

• Treats repo as monolithic — no awareness of sub-package structure
• No per-package README generation — each sub-package may want its own README section or file
• No call to enrichPromptWithSubPackages() — Gemini doesn't know which changes belong to which package

Implementation Plan

Phase 1: Autodoc Sub-Package Awareness

1. Extend autodoc.json schema to support optional sub_package field per module entry

   • When present, associates the module with a specific sub-package for grouping
   • Example:

     {
       "modules": [
         {
           "name": "custom_lint_core/analyzer",
           "sub_package": "custom_lint_core",
           "paths": ["packages/custom_lint_core/lib/src/analyzer/"],
           "description": "Core analyzer integration"
         }
       ]
     }

2. Enrich autodoc prompts with sub-package context

   • Before running Gemini for each module, inject SubPackageUtils.buildSubPackageDiffContext() context
   • Include which sub-package the module belongs to in the prompt
   • Add cross-references: "This module is part of custom_lint_core, which is used by custom_lint and custom_lint_builder"

3. Organize generated docs hierarchically

   • Group output files under docs/{sub_package}/ directories
   • Generate a top-level docs/README.md index that links to per-package doc directories
   • Maintain backward compatibility: repos without sub-packages keep flat docs/ structure

4. Update autodoc hashing to include sub-package metadata

   • Incremental rebuild should detect when a module's sub-package assignment changes

Phase 2: Documentation Sub-Package Awareness

1. Call enrichPromptWithSubPackages() in DocumentationCommand

   • Inject per-package diff context into the README generation prompt
   • Add buildHierarchicalDocumentationInstructions() to SubPackageUtils (new method, modeled after the existing changelog/release-notes instruction builders)

2. Hierarchical README structure

   • Top-level summary covering the entire repo
   • Per-package sections with package-specific details
   • Example output:

     # dart_custom_lint
     
     > A powerful custom lint framework for Dart and Flutter.
     
     ## Packages
     
     ### custom_lint
     The main CLI and plugin host...
     
     ### custom_lint_core
     Shared data models and utilities...
     
     ### custom_lint_builder
     Analyzer plugin integration...

3. Optional per-package README files

   • Generate/update {sub_package_path}/README.md for each sub-package
   • Cross-link between root README and per-package READMEs

Phase 3: Pipeline Integration

1. Update release template to pass sub-package info through to autodoc and documentation stages

   • The commands already receive --repo-root, so loadSubPackages() can discover config automatically
   • No workflow template changes needed if commands self-discover

2. Update step summaries to show per-package doc generation stats

Files to Modify

Autodoc

• lib/src/cli/commands/autodoc_command.dart — add enrichPromptWithSubPackages() call, organize output by sub-package
• lib/src/cli/utils/sub_package_utils.dart — possibly add buildHierarchicalAutodocInstructions()
• Autodoc prompt templates (if they exist as separate files)

Documentation

• lib/src/cli/commands/documentation_command.dart — add enrichPromptWithSubPackages() call
• lib/src/cli/utils/sub_package_utils.dart — add buildHierarchicalDocumentationInstructions()

Shared

• Possibly lib/src/cli/utils/sub_package_utils.dart — new instruction builder methods

Acceptance Criteria

• autodoc command generates docs grouped by sub-package when sub_packages config exists
• autodoc Gemini prompts include which sub-package a module belongs to
• documentation command generates hierarchical README with per-package sections
• Both commands gracefully fall back to current behavior for single-package repos
• dart analyze passes with zero issues
• Generated docs render correctly in GitHub markdown preview

Related Work

• PR feat: multi-package support for CLI commands #18 — feat/multi-package-support (merged, added SubPackageUtils and hierarchical changelog/release-notes)
• feat/audit-commands branch — added pubspec audit infrastructure + sibling dep conversion
• configs/external_workspace_packages.yaml — all 5 dart_custom_lint sub-packages registered with tag_pattern and git_path