Skip to content

docs/emitters: manage the README as blocks the user can edit around #705

Closed

Description

@OmarAlJarrah

Problem

The keep regions of docs/emitters/write-integrate.md protect hand-written islands in generated code. A README is the opposite case: mostly hand-written, with generated sections (installation, authentication, per-feature examples, a table of contents). Overwriting it loses the user's text; not generating it leaves it stale.

Proposal

The docs emitter returns README sections with stable IDs; the engine's integrate step merges them into the existing README between markers, keeps everything outside the markers, respects sections the user froze, and rebuilds the table of contents.

Activity

  1. added
    priority:P4Refactors, tests, CI, hostile-input hardening, cosmetic diagnostics, other formats
    on Oct 19, 2026
  2. changed the title [-]docs/emitter-design: manage the README as blocks the user can edit around[/-] [+]docs/emitters: manage the README as blocks the user can edit around[/+] on Nov 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P4Refactors, tests, CI, hostile-input hardening, cosmetic diagnostics, other formatstype:featureNew capability or enhancement

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions