/gaia-merge-docs

user-facing

Category:: Documentation & Editorial
Lifecycle phase:: Any
Arguments:: [source-dir-or-file-list] [output-path]

What it does

/gaia-merge-docs merges multiple Markdown files into a single document -- the inverse of /gaia-shard-doc. It reassembles files in correct order, preserves section numbering, resolves cross-references to in-document anchors, and adds a table of contents.

When to use it

You sharded a document for parallel editing and now want to merge the parts back.
You have multiple related Markdown files you want to combine into one document.

Prerequisites

Source files must exist. Provide a directory of shards or a list of file paths.

How to invoke

/gaia-merge-docs .gaia/artifacts/planning-artifacts/architecture/
/gaia-merge-docs file1.md,file2.md,file3.md output.md

What it does step by step

Identify source files Resolves the input (directory or file list) and determines the correct ordering.
Validate structure Checks heading consistency and identifies cross-references between files.
Merge Reassembles in order, fixes cross-references to use section anchors instead of file links, and adds a table of contents.
Output Asks for confirmation of the output path, then writes the merged document.

Inputs

Input	Source	Description
`source`	Command argument	Directory of shards or comma-separated list of file paths.
`output-path`	Command argument (optional)	Where to write the merged document. Defaults to `{source-dir}/merged.md`.

Outputs

Output	Location	Description
Merged document	Output path	Single document with all content, fixed cross-references, and a table of contents.

Example session

> /gaia-merge-docs .gaia/artifacts/planning-artifacts/architecture/

Merging 4 files...
  _preamble.md (12 lines)
  01-system-overview.md (48 lines)
  02-components.md (94 lines)
  03-data-arch.md (67 lines)

Output path: .gaia/artifacts/planning-artifacts/architecture/merged.md
Proceed? [y/n] > y

4 files merged. 221 total lines.

What to run next

Review the merged document for consistency.

Troubleshooting

Empty input list

No source files were provided. Provide a directory or file list.

Heading level mismatch

Files start at different heading levels. The merge report will flag the inconsistency.