Generate README sections from source-of-truth files like .env.example

[leobrival]

Context

After integrating StackWarden README generation in prsnl_app, the current system can generate:

• repo-tree sections from README markers;
• workspace governance sections from .stackwarden/workspaces.yml;
• projection/governance checks from .stackwarden/*.yml.

The next useful step is to generate richer README sections from existing source-of-truth files, starting with .env.example.

Today, many README files manually document environment variables, required secrets, local setup commands, and service-specific configuration. This creates drift because the same information also exists in .env.example files.

Proposal

Add a configurable README section generation system driven by source-of-truth files.

Initial target: generate README Environment variables / Required environment sections from .env.example files.

Desired user-facing flow

Declare sections in a StackWarden config, for example:

# .stackwarden/readme-sections.yml
version: 1

sections:
  - id: root-env
    source: .env.example
    target: README.md
    marker: env-vars
    renderer: env-example-table
    title: Environment variables

  - id: api-env
    source: services/api/.env.example
    target: services/api/README.md
    marker: env-vars
    renderer: env-example-table
    title: Required environment

  - id: mastra-env
    source: services/mastra/.env.example
    target: services/mastra/README.md
    marker: env-vars
    renderer: env-example-table
    title: Required environment

README markers:

## Required environment

<!-- env-vars:start -->
<!-- env-vars:end -->

Commands:

stackwarden generate readme-sections
stackwarden check readme-sections

Alternative naming if preferred:

stackwarden generate projections
stackwarden check projections

.env.example parsing requirements

The basic parser can extract key/default pairs from standard dotenv lines:

SUPABASE_WORKDIR=packages
RUN_PREPUSH_BUILD=0

But to generate useful docs, StackWarden should support structured comments above each variable, e.g.:

# @required true
# @description Supabase CLI workdir, directory containing packages/supabase.
# @default packages
SUPABASE_WORKDIR=packages

# @required false
# @description Force local pre-push build.
# @default 0
RUN_PREPUSH_BUILD=0

Rendered output:

<!-- env-vars:start generated-from: .env.example -->
| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `SUPABASE_WORKDIR` | yes | `packages` | Supabase CLI workdir, directory containing packages/supabase. |
| `RUN_PREPUSH_BUILD` | no | `0` | Force local pre-push build. |
<!-- env-vars:end -->

Other source-of-truth candidates

This feature should be generic enough to later support:

• package.json scripts → README commands section;
• .stackwarden/pipeline.yml → validation matrix;
• .stackwarden/ownership.yml → ownership/governance section;
• OpenAPI/contract files → API overview;
• Supabase function metadata → request/response docs;
• .stackwarden/readme-profiles.yml → required README profile structure.

Why this matters

This would move StackWarden from “generates some README blocks” to a broader model:

README sections are generated from durable, versioned sources of truth, while manual README prose remains preserved.

Benefits:

• less README/config drift;
• fewer duplicated environment variable lists;
• safer onboarding docs;
• better stackwarden check governance coverage;
• clearer migration path away from repo-local documentation scripts.

Acceptance criteria

• A repo can declare README sections in .stackwarden/readme-sections.yml or equivalent.
• StackWarden can generate a README table from .env.example.
• StackWarden can check whether that generated section is stale.
• Generated output includes provenance markers compatible with projection/governance checks.
• Missing source files produce actionable diagnostics.
• Existing README manual content outside markers is preserved.
• The feature is advisory by default and can be made strict via config.