Comment by divbzero

Instead of the proposed /src/md convention:

  src/
    md/
      README.md          # index of all md, entry point for agents
      TODO.md            # a list of general TODOs open for this module
      OVERVIEW.md        # a technical overview of this module
      features/FEATURE_1.md       # a set of feature-specific documents
      data/DATAMODEL_1.md         # descriptions of data models in the module
      api/API_1.md                # descriptions of APIs the module provides
      infrastructure/INFRASTRUCTURE_1.md   # descriptions of infrastructure used by the module

What if we standardized on README.md in each subdirectory alongside the code?

  src/
    README.md    # entry point for humans and agents
    TODO.md      # list of general TODOs open for this module
    INFRA.md     # descriptions of infrastructure used by the module
    api/
      README.md  # descriptions of APIs the module provides
    models/
      README.md  # descriptions of data models in this module

README.md in each subdirectory seems to align better with OP’s objective “that Markdown should be checked in to /src, next to the code it produces”. It is also a convention already in use in many code repositories.