Make README and documentation generation configurable

[leobrival]

Context

While integrating StackWarden into prsnl_app, the current stackwarden generate workspaces command successfully centralizes README workspace sections from .stackwarden/workspaces.yml, and stackwarden check workspaces catches drift.

However, the generator is still mostly fixed-shape: it always emits the same root workspace table and per-workspace governance block. For teams that already have richer documentation governance, this is not enough to progressively replace local scripts.

Expected capability

Make README/documentation generation more configurable so StackWarden can replace project-specific documentation governance scripts, not only the current workspace README section generator.

Desired outcomes:

• Keep .stackwarden/ as the source of truth.
• Allow teams to declare which README sections are generated, where they are inserted, and which template/renderer is used.
• Support check/write modes for generated sections.
• Detect handwritten Markdown drift separately from generated projections.
• Support advisory pre-commit warnings for handwritten docs, without blocking by default.
• Keep generated output marked with generated-from: markers so stackwarden check projections can validate provenance.

Prior art / examples to study

In another repo, these scripts implement useful patterns that StackWarden could absorb:

sync-readme-tree-sections.mjs

Path:

/Users/leobrival/Developer/website/family-and-love/packages/shared/scripts/sync-readme-tree-sections.mjs

Useful behavior:

• Finds README files automatically.
• Updates only marked sections:

<!-- repo-tree:start path="." depth="2" -->
...
<!-- repo-tree:end -->

• Supports --check and --write.
• Renders configurable directory trees from marker attributes:
  • path
  • depth
  • files
  • ignore

Potential StackWarden equivalent:

stackwarden generate docs
stackwarden check docs

or an extension of:

stackwarden generate projections
stackwarden check projections

With config such as:

projections:
  - id: readme-tree
    source: .stackwarden/documentation.yml
    targets:
      - README.md
    marker: repo-tree
    renderer: directory-tree
    options:
      depth: 2
      files: true
      ignore:
        - node_modules
        - dist

audit-documentation.mjs

Path:

/Users/leobrival/Developer/website/family-and-love/packages/shared/scripts/audit-documentation.mjs

Useful behavior:

• Loads a documentation governance config.
• Finds all .md / .mdx files.
• Enforces allowed extensions and ignored paths.
• Distinguishes generated Markdown paths from handwritten Markdown.
• Requires generated files to contain configured markers.
• Flags untracked handwritten Markdown unless explicitly allowlisted or marked legacy.

Potential StackWarden equivalent:

stackwarden check docs-governance

or extend existing:

stackwarden check docs-drift

With config like:

documentation:
  ignoredPaths:
    - node_modules/**
    - .git/**
  allowedExtensions:
    - .md
    - .mdx
  generatedMarkdown:
    paths:
      - README.md
      - docs/generated/**
  requiredGeneratedMarkers:
    - generated-from:
    - repo-tree:start
  allowedHandwrittenGlobs:
    - docs/guides/**
  legacyHandwrittenPaths:
    - README.old.md

warn-handwritten-docs.mjs

Path:

/Users/leobrival/Developer/website/family-and-love/packages/shared/scripts/warn-handwritten-docs.mjs

Useful behavior:

• Pre-commit advisory warnings for staged Markdown.
• Reads documentation governance config.
• Ignores generated projections and managed README files.
• Warns when staged handwritten docs are not governed or are legacy.
• Does not block by default.

Potential StackWarden equivalent:

stackwarden hook pre-commit

should include advisory handwritten-doc warnings when configured, or expose:

stackwarden check handwritten-docs

Proposed implementation direction

Add a .stackwarden/documentation.yml or extend .stackwarden/projections.yml to support:

1. Section-based README generators.
2. Marker-based replacement (start / end markers).
3. Built-in renderers, initially:
   • workspace-table
   • workspace-governance
   • directory-tree
   • markdown-list
4. --check / write behavior through existing stackwarden check ... and stackwarden generate ... commands.
5. Handwritten Markdown governance:
   • generated path marker enforcement,
   • allowlisted handwritten globs,
   • legacy handwritten warnings,
   • staged-file advisory mode.

Acceptance criteria

• stackwarden generate workspaces remains backward compatible.
• A repo can configure README tree sections without a custom script.
• A repo can run a blocking documentation audit equivalent to audit-documentation.mjs.
• stackwarden hook pre-commit can emit non-blocking handwritten-doc warnings equivalent to warn-handwritten-docs.mjs.
• stackwarden check governance includes documentation/projection drift in the aggregate result.
• Generated docs include provenance markers compatible with stackwarden check projections.