[Improvement] Scope headers + generated files to .xdocs.md only, require explicit user approval rules, validate frontmatter #21

Summary

Field review from real usage of XDocs. Right now XDocs is too aggressive and too unsafe in how it touches Markdown files and in what it generates. This issue proposes tightening that behavior: fewer files, narrower header scope, explicit user approval, and frontmatter validation.

Problem 1: XDocs adds headers to every Markdown file it finds

Current behavior: XDocs adds headers to every single .md file it encounters while scanning, including files it should never touch such as README.md.

Why this is bad:

• README.md (and similar user-owned docs like CHANGELOG.md, AGENTS.md, etc.) get modified without being asked for.
• It is annoying and erodes trust — the user can no longer tell which edits are theirs and which are XDocs'.
• It creates noisy diffs and unexpected side effects in repos.

Problem 2: XDocs generates unnecessary files (two files in the same directory)

Current behavior: XDocs adds unnecessary files — e.g. one "overview" file plus another "specific" file in the same directory.

Why this is bad:

• Two files per directory is clutter. In most cases one file is enough.
• It fragments documentation instead of centralizing it.

Proposal

1. Only one generated file per directory: .xdocs.md

• Each documented directory should contain at most one XDocs-owned file: .xdocs.md.
• Remove the overview + specific two-file pattern. Consolidate into the single .xdocs.md.

2. Only add headers to .xdocs.md files

• XDocs must only inject/update headers (frontmatter) in .xdocs.md files — never in README.md or any other user-owned Markdown file.
• Default rule: hands off everything except .xdocs.md.

3. Explicit user approval for any header edits outside .xdocs.md

• If the user ever wants XDocs to manage headers on specific directories or specific files outside the default scope, that must be:
  1. Explicitly requested/approved by the user, and
  2. Defined by user-authored rules (e.g. in xdocs.yaml — include paths / globs per directory or per file).
• Without such a rule, XDocs must not edit headers anywhere else. No implicit behavior, no silent expansion of scope.

4. Validate headers (frontmatter) before writing

• Currently XDocs does not validate the headers it writes. The frontmatter is sometimes wrong / contains errors, and that actually breaks Markdown rendering of the files.
• Required:
  • Validate frontmatter schema before writing (required keys, types, allowed values).
  • Reject or auto-repair invalid frontmatter instead of writing broken output.
  • Add a validation command or check (e.g. xdocs doctor / xdocs lint) that reports malformed frontmatter in existing .xdocs.md files.
  • Never write output that breaks rendering — a written file with invalid frontmatter should be treated as a bug, not user cleanup work.

Acceptance criteria

• Running XDocs never modifies headers in README.md or other non-.xdocs.md files by default.
• One directory → one .xdocs.md file (no overview + specific duplication).
• Any header management outside .xdocs.md requires an explicit user-defined rule (opt-in per directory or per file).
• Frontmatter written by XDocs is schema-validated; invalid output is blocked or repaired.
• There is a way to detect/repair already-broken frontmatter from previous runs.

Context

• Reported from real product usage (field review).
• Related: File exclusion via ignore.rules and scan.exclude does not prevent doctor from flagging AGENTS.md/CHANGELOG.md/README.md as undocumented #20 (exclusion rules not respected by doctor) — this issue goes further by making .xdocs.md-only the default scope plus explicit opt-in rules and validation.