Generated vs Manual Content

Generated vs Manual Content

XrmGhost documentation is divided into two categories: manual content and generated content.

Manual Content

Manual content is authored directly by humans in this repository (xrmghost-docs). It includes narrative explanations, guides, and conceptual documentation that requires human judgment to write.

All content currently in this repository is manual content:

File / Path	Type	Notes
src/content/docs/getting-started.mdx	Manual	Narrative first-run guide
src/content/docs/cli/index.mdx	Manual	Narrative CLI overview
src/content/docs/cli/getting-started.mdx	Manual	Narrative CLI getting-started guide
src/content/docs/attributes/index.mdx	Manual	Narrative attributes overview
src/content/docs/architecture/	Manual	Architecture and governance docs
src/content/docs/contributing/index.mdx	Manual	Contribution guidelines

Manual content is version-controlled here and reviewed through pull requests before publication.

Generated Content

Generated content is produced programmatically from source artifacts in other repositories (e.g., parsing --help output from the CLI, or reading attribute schema files). It is not authored by hand.

Current State

No generated content exists yet. All documentation is currently manual.

Future Insertion Points

The following locations are reserved for generated content once the relevant pipelines are built:

CLI Reference (src/content/docs/cli/reference/)

TODO (ADO-1175): Implement per-command reference page generation once the generator is built in xrmghost-cli.

CLI Generation Contract:

The following terms govern how future CLI reference content is sourced, placed, and maintained. These rules apply once the generation pipeline is active; they are stated now to prevent scope ambiguity during implementation.

Contract Term	Value
Source repository	xrmghost-cli
Source artifact	Structured command manifest or --help output exposed by the CLI tool
Destination path	src/content/docs/cli/reference/ within xrmghost-docs
File naming	src/content/docs/cli/reference/<command>.mdx (one file per top-level or sub-command)
Generation trigger	CI pipeline or automation run against a tagged xrmghost-cli release
Do not hand-edit	Files under src/content/docs/cli/reference/ must not be manually edited once generation is active
Review authority	Changes to CLI reference output are reviewed in xrmghost-cli at the source; ad hoc edits to generated files in xrmghost-docs are not accepted
Conflict resolution	If a generated file needs correction, fix the source in xrmghost-cli and re-run the generator

Attribute Schema Reference (src/content/docs/attributes/schema/)

TODO: Auto-generate attribute schema reference from the JSON/YAML schemas in xrmghost-attributes. Files will land at src/content/docs/attributes/schema/<attribute>.mdx. Same rule applies: do not manually edit generated files.

Rules

1. Do not mix manual and generated content in the same file. If a page has both human narrative and machine output, split them into separate files.
2. Generated files must be clearly marked. Add a frontmatter field generated: true and a comment at the top of the file indicating the source and generation timestamp.
3. Generated files are not reviewed through PR in this repo. The review gate is in the source repo (xrmghost-cli for CLI reference). Generated files land via an automated pipeline commit, not a manual PR.
4. Do not delete generated files manually. Run the generation pipeline with an empty/removed source to remove them.
5. Narrative CLI pages are never generated. src/content/docs/cli/index.mdx and src/content/docs/cli/getting-started.mdx remain manual content regardless of whether CLI reference generation is active.

Example Frontmatter for a Generated File

---
title: "xrmghost run — CLI Reference"
description: "Auto-generated reference for the `xrmghost run` command."
generated: true
generated_from: "xrmghost-cli v1.2.3 --help"
generated_at: "2026-05-05T00:00:00Z"
---