mdx corpus toolchain

authored MDX is the corpus authority. rebuild one disposable SQLite index from its parsed AST, then generate every human and agent delivery artifact from that indexed document set. a frontend may render the result, but it does not re-parse frontmatter or invent a second route model.

when the reader app, the deployment script, and the agent index each parse the corpus their own way, three partial models disagree while each local check still passes. one parsed index with verified source hashes makes every consumer — human page, manifest record, llms.txt entry, raw source — provably derived from the same documents. any defect is repaired at the MDX or generator, then rebuilt — never patched in an artifact the next rebuild overwrites.

the SQLite database is derived evidence, not a publishing authority. generation rebuilds it before every result, verifies each source hash, and fails before publishing partial output when parsing, schema validation, or route uniqueness fails.

data/**/*.mdx
  -> mdxquery.sqlite
  -> corpus manifest
     -> Fumadocs MDX source
     -> /llms.txt directory
     -> /guru/<group>/llms.txt bounded indexes
     -> /guru/<path>/index.md original source
     -> /llms-full.txt bulk corpus

• root llms.txt stays small: immediate documents plus immediate group indexes.
• each group index repeats the rule recursively, so an agent narrows retrieval before loading a document.
• canonical raw URL ends in /index.md; canonical human URL replaces index.md with the directory.

• consumers read the generated manifest or generated files; they never scan the source tree independently.
• path_segments owns URL identity. no consumer derives a slug from a title, filename, or casing transform.
• the manifest records the source path, source hash, human URL, raw URL, parent index, title, description, kind, status, and visibility.
• generated output is replaceable: repair the MDX, parser, schema, or generator, then rebuild; never hand-edit an artifact.
• a deployment is incomplete until representative human pages and the complete agent traversal graph return the expected content types and source text.

• rebuild the index from the current corpus.
• query normalized frontmatter and a parsed MDX component.
• generate the distribution; compare manifest count and hashes with the source set.
• every manifest document appears in exactly one parent llms.txt; every declared group index exists; every raw route returns the original MDX as text/markdown.

bad

the documentation app scans MDX, the deployment script parses YAML again, and
the agent index derives a third URL from filenames.

three partial models disagree while each local check passes. a rendered document may be missing from the agent index; url identity diverges per consumer, so links rot unpredictably; a frontmatter key one consumer ignores silently changes meaning for another. repairs land in one consumer's copy and are overwritten or orphaned by the next — no single provable state, only approximations that drift until retrieval and rendering contradict each other.

good

MDX -> parsed SQLite index -> one corpus manifest -> human and agent outputs

one rebuilt graph proves every consumer sees the same document identity, metadata, and source. a schema or parsing defect fails the build before publishing partial output, so a bad corpus cannot ship quietly. adding a consumer means reading the manifest, not writing another parser; any defect has exactly one repair location — MDX, parser, or generator — after which every artifact agrees again by construction.

mdxquery · MDX as interface · generation pipeline · verification evidence · MDX knowledge loop