Require explicit documentation authorization and show complete trees

AGENTS.md

@@ -83,14 +83,16 @@ architecture, planning, execution, review, validation, and release work.
   idempotently bootstraps both global skill targets and the current
   repository's bounded instruction block; other agent-resource changes use
   explicit `xdocs agent` actions.
-- `xdocs scan` walks the project tree while respecting `scan.exclude`, root and nested `.gitignore` files when enabled, and explicit frontmatter opt-outs; it reports named `*.xdocs.md` descriptor coverage plus same-directory Markdown companion-document coverage.
+- `xdocs scan` walks the project tree while respecting `scan.exclude`, root and nested `.gitignore` files when enabled, and explicit descriptor candidates; it reports complete named `*.xdocs.md` coverage plus same-directory Markdown companion-document coverage without granting write permission.
 - `xdocs generate [path]` generates documentation for a specific directory or the entire project.
 - `xdocs merge [path]` merges xdocs descriptors from a directory into a single consolidated document.
-- `xdocs tree` builds and displays the project hierarchy from xdocs metadata.
+- `xdocs tree` walks the complete non-excluded filesystem and displays every
+  descriptor by directory containment; metadata relationships are diagnosed
+  separately by `doctor`.
 - `xdocs list [path]` lists files in a scope with descriptions from xdocs metadata.
-- `xdocs meta [path]` scans top-down and reads only YAML frontmatter from named `*.xdocs.md` descriptors; `--documents` also reads required companion `.md` frontmatter and reports configured opt-outs with `frontmatterRequired: false`, while `--owner`, `--tag`, and `--keyword` filter metadata before agents read full files.
+- `xdocs meta [path]` scans top-down and reads only YAML frontmatter from named `*.xdocs.md` descriptors; `--documents` reports ordinary companions with explicit `frontmatterRequired: false` unless `documentation.frontmatter` opts them in within `documentation.directories`; `--existing-frontmatter` audits existing headers read-only, while `--owner`, `--tag`, and `--keyword` filter metadata before agents read full files.
 - `xdocs context <query> [path]` recommends a minimal reading set for a task from descriptor, file, and companion-document metadata; use `--documents`, `--files`, `--limit`, and `--explain` for agent workflows.
-- `xdocs doctor [path]` runs CI-friendly health checks for descriptor validity, required companion-document metadata, tree integrity, and documented file existence.
+- `xdocs doctor [path]` runs CI-friendly health checks for descriptor validity, explicitly required companion-document metadata, tree integrity, and documented file existence; `--existing-frontmatter` audits legacy headers without authorizing writes.
 - `xdocs agent skill install|uninstall|update|list|show`, `agent instruction apply|remove|update|show`, and `agent prompt list|show` implement explicit RFC 0034 agent integration.
 - Skill mutations default global, use `--local` for project scope, and always target both `.agents/skills` and `.claude/skills`.
 - A bare xdocs invocation bootstraps shared agent resources, then prints the
@@ -122,10 +124,13 @@ architecture, planning, execution, review, validation, and release work.
 
 ## Key Concepts
 
-- xdocs descriptors use Markdown with YAML frontmatter and must be named `*.xdocs.md`; `.docs.md` is not supported and `.xdocs.md` by itself is invalid. Same-directory non-excluded plain `*.md` files are companion documents listed in the descriptor's `documents` metadata. Companion frontmatter is required unless a matching `ignore.rules` file or directory rule sets `frontmatter: false`; those documents remain tracked and must not be modified to add frontmatter. The root file is always `XDOCS.md` (uppercase, no prefix, no frontmatter). Use `xdocs meta [path] --documents --format json` when an agent needs descriptor and companion-document policy without reading full Markdown bodies.
+- xdocs descriptors use Markdown with YAML frontmatter and must be named `*.xdocs.md`; `.docs.md` and `.xdocs.md` by themselves are invalid candidates. Same-directory non-excluded plain `*.md` files are companion documents listed in the descriptor's `documents` metadata. Ordinary Markdown frontmatter is not required or written unless a matching `documentation.frontmatter` rule is explicitly authorized inside `documentation.directories`; legacy `ignore.rules` denials always win. The root file is always `XDOCS.md` (uppercase, no prefix, no frontmatter). Use `xdocs meta [path] --documents --format json` when an agent needs descriptor and companion-document policy without reading full Markdown bodies.
 - Metadata fields: `subject`, `description`, `parent`, `children`, `files`, `documents`, `tags`, `keywords`, `flags`, and optional `status`.
-- The tree is a parent-child containment hierarchy, not a dependency graph. Built from `subject`/`parent`/`children` fields.
-- Configuration lives in `xdocs.yaml`. Sections: `extensions`, `ai`, `ignore`, `scan`, and `project`. `ignore.gitignore` defaults to `true`; strict `ignore.rules` objects use `pattern`, `kind`, and `frontmatter: false`.
+- The displayed tree is a directory-containment hierarchy, not a dependency
+  graph. It uses the nearest ancestor descriptor so malformed, orphaned, and
+  duplicate metadata cannot hide a discovered file; `doctor` validates
+  `subject`/`parent`/`children` relationships separately.
+- Configuration lives in `xdocs.yaml`. Sections: `extensions`, `ai`, `documentation`, `ignore`, `scan`, and `project`. `documentation.directories` defaults to `[]` and grants descriptor maintenance only within listed repository-relative directories and descendants; `documentation.frontmatter` defaults to `[]` and grants companion metadata only for matching files or directories inside those grants. `ignore.gitignore` defaults to `true`; strict `ignore.rules` objects use `pattern`, `kind`, and `frontmatter: false`.
 - Agent resource operations are not configuration-driven. The plain root
   bootstrap and `init` setup are the only implicit/setup boundaries; other
   mutations are explicit.
@@ -217,7 +222,8 @@ companion documents, repository scanning, metadata discovery, or validation.
 
 The project configuration is `xdocs.yaml`. Respect `ai.mode`:
 `prompt` requires confirmation before documentation writes, while
-`auto` permits immediate descriptor maintenance. Also respect
+`auto` permits immediate descriptor maintenance only inside explicitly
+authorized documentation directories. Also respect
 `ignore.gitignore` and every `ignore.rules` entry: excluded paths are
 outside the xdocs corpus, while `frontmatter: false` keeps matching documents
 tracked without adding or requiring YAML frontmatter. Use `xdocs scan`,

DOCS.md

@@ -16,13 +16,16 @@ keywords:
   - agent resources
 ---
 
+#### © 2026 [GUIHO](https://guiho.co) as represented by [Cristóvão GUIHO](https://guiho.co/cguiho) All Rights Reserved.
+
 # xdocs Documentation
 
 ## Purpose
 
 xdocs gives humans and agents a deterministic map of a repository through one
-root `XDOCS.md`, one named `*.xdocs.md` descriptor per documented module, and
-declared companion Markdown documents.
+root `XDOCS.md`, one named `*.xdocs.md` descriptor per documented directory, and
+declared companion Markdown documents. Discovery is read-only and complete;
+descriptor and ordinary Markdown writes require explicit project policy.
 
 The active implementation is a native Go CLI. The historical TypeScript tree
 is retained as migration reference only and is not used by the executable,
@@ -83,6 +86,10 @@ multiple YAML documents, and then validates:
 - `schema` is `1`;
 - the only descriptor extension is `.xdocs.md`;
 - `ai.mode` defaults to `auto` and accepts only `auto` or `prompt`;
+- `documentation.directories` defaults to an empty list and contains only
+  repository-relative literal directory paths;
+- `documentation.frontmatter` defaults to an empty list and each rule contains
+  a repository-relative `pattern` and `kind` of `file` or `directory`;
 - `ignore.gitignore` defaults to `true`;
 - each `ignore.rules` entry has a non-empty, syntactically valid,
   repository-relative forward-slash glob, `kind` set to `file` or `directory`,
@@ -92,9 +99,23 @@ multiple YAML documents, and then validates:
 
 Global state and update cache live under `~/.guiho/xdocs/`.
 
-In `auto` mode, agents make relevant documentation changes in the same work
-unit. In `prompt` mode, agents announce the needed documentation changes and
-wait for confirmation.
+In `auto` mode, agents make already-authorized documentation changes in the
+same work unit. In `prompt` mode, agents announce those changes and wait for
+confirmation. `ai.mode` controls timing only and never expands authorization.
+
+`documentation.directories` grants descriptor maintenance for each listed
+directory and its non-excluded descendants. `.` grants the complete
+non-excluded project; `[]` grants none. `xdocs init` writes the empty defaults
+and does not populate this allowlist. Discovery, metadata reads, tree output,
+and health checks remain available for every non-excluded directory regardless
+of the allowlist.
+
+`documentation.frontmatter` grants ordinary Markdown frontmatter only when a
+rule's `pattern` and `kind` match a document and the document is below an
+authorized directory. A matching legacy `ignore.rules` entry with
+`frontmatter: false` is an explicit denial and always wins. A plain Markdown
+file can therefore remain listed in its descriptor's `documents` map without
+frontmatter; missing headers are valid unless both opt-ins match.
 
 The default ignore contract is:
 
@@ -155,16 +176,23 @@ Descriptors require:
 - `tags`, `keywords`, and `flags`: string arrays;
 - optional `status`.
 
-The root `XDOCS.md` has no frontmatter. A bare `.xdocs.md` filename is invalid.
-Multiple descriptors in one directory are invalid. Every plain sibling
-Markdown document not excluded by `.gitignore` must be declared, and every
-declared non-excluded document must exist.
+The root `XDOCS.md` has no frontmatter and is the single special project index.
+A new directory descriptor should use the directory name, such as
+`technologies/technologies.xdocs.md`. A bare `.xdocs.md` filename and legacy
+`.docs.md` files are invalid. Multiple named descriptors in one directory are
+invalid. The descriptor body carries useful directory context; xdocs does not
+create a separate summary or detail file for it. Every plain sibling Markdown
+document not excluded by `.gitignore` must be declared, and every declared
+non-excluded document must exist.
 
 Companion documents require `name`, `purpose`, `description`, `created`
-(`YYYY-MM-DD`), `owner`, `flags`, `tags`, and `keywords` unless a matching
-ignore rule sets `frontmatter: false`. `owner` must equal the owning descriptor
-subject when frontmatter is required. Opted-out documents remain associated
-with that descriptor subject without xdocs modifying their content.
+(`YYYY-MM-DD`), `owner`, `flags`, `tags`, and `keywords` only when an explicit
+`documentation.frontmatter` rule and an authorized directory match. The
+`owner` must equal the owning descriptor subject when frontmatter is required.
+Missing frontmatter is valid otherwise. The default legacy `ignore.rules`
+denials protect `AGENTS.md`, `README.md`, and `CLAUDE.md`; XDocs leaves those and
+other ordinary Markdown bodies and headers unchanged unless the project has
+explicitly authorized the exact scope.
 
 ## Command catalog
 
@@ -173,22 +201,32 @@ with that descriptor subject without xdocs modifying their content.
 - `init [--local]` creates missing root files and installs the embedded skill.
 - `scan` reports non-excluded descriptor and companion-document coverage and,
   in verbose output, identifies documents whose frontmatter is not required.
-- `doctor [path]` validates descriptors, required companion metadata, tree
-  links, and documented files. `--warnings-as-errors` promotes warnings.
+- `doctor [path]` validates descriptors, authorized companion metadata, tree
+  links, and documented files. `--existing-frontmatter` audits malformed
+  headers that already exist on otherwise non-required Markdown without
+  requiring ownership or writing repairs. `--warnings-as-errors` promotes
+  warnings.
 
 ### Documentation views
 
-- `generate [path]` renders a project or module document.
+- `generate [path]` renders a project or module report.
 - `merge [path]` combines descriptors with source markers.
-- `tree` renders containment hierarchy as text, Markdown, or JSON.
+- `tree` renders the complete deepest containment hierarchy as text, Markdown,
+  or JSON, including the special root index and diagnostically available
+  descriptor paths.
 - `list [path]` lists documented files and companion documents.
 
 ### Agent context
 
-- `meta [path]` reads frontmatter only. `--documents` includes required
-  companion frontmatter and tracks opted-out documents with
-  `frontmatterRequired: false`; `--owner`, `--tag`, and `--keyword` filter
-  before full reads.
+- `meta [path]` reads frontmatter only. `--documents` reads companion
+  frontmatter when it is required and tracks ordinary Markdown with
+  `frontmatterRequired: false`; `--existing-frontmatter` implies
+  `--documents`, audits every discovered ordinary Markdown file in scope
+  (including unlisted and descriptorless files), and returns those audited
+  documents in the top-level `documents` JSON array and matching text/Markdown
+  sections. Missing headers remain valid; existing headers are checked for
+  generic YAML object structure without imposing the companion owner schema.
+  `--owner`, `--tag`, and `--keyword` filter before full reads.
 - `context <query> [path]` tokenizes a query, applies stable weighted ranking,
   and returns the smallest useful descriptor/file/document reading set.
   `--explain` includes match reasons.
@@ -204,7 +242,8 @@ paths. `--local` chooses project scope. Instruction apply/update/remove is
 idempotent, preserves unmanaged content and line endings, and refuses malformed
 managed markers. The plain-invocation bootstrap uses the same embedded sources
 and mutation services; explicit agent commands remain available for deliberate
-management.
+management. These setup operations do not grant permission to edit the
+documentation corpus or add frontmatter to agent instruction files.
 
 ### Upgrade and uninstall
 
@@ -218,6 +257,14 @@ pagination, defaults to eight entries, and retains full machine-readable
 metadata in JSON. Direct upgrade uses the linker-embedded build target so ARMv6
 and ARMv7 remain distinct.
 
+All scan, meta, context, and doctor operations are read-only. Without
+`--output`, tree discovery is also read-only. `generate`, `merge`, and `tree`
+write nothing unless the user supplies one exact `--output` path. That path authorizes only the requested report; it cannot
+authorize descriptor or companion metadata changes, and a descriptor-shaped
+destination is rejected. Output validation runs before replacement so a rejected
+destination retains its original bytes. No command creates extra summary,
+companion, or index files as a side effect.
+
 ## Help and output
 
 Every command supports: