# Docs Alignment

> Validate and align a whole documentation corpus against the codebase — broken-link/orphan detection, Diataxis structure, front-matter metadata, Mermaid diagram compliance (ASCII→Mermaid), UK-English spelling, and navigation/index generation — optionally via an agent swarm. Use when auditing or modernising a full /docs corpus, enforcing Diataxis, fixing link coverage, or preparing docs for a release. Not for writing a single README (write markdown directly), LaTeX reports (report-builder), or standalone diagrams (mermaid-diagrams).

- Skill: `dreamlab-ai/docs-alignment` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add dreamlab-ai/docs-alignment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dreamlab-ai/docs-alignment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dreamlab-ai (https://skillmd.com/u/dreamlab-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dreamlab-ai/docs-alignment

---


# Documentation Alignment Skill

Modernise and validate a project's documentation corpus so it stays consistent
with the codebase: links, front matter, diagrams, spelling, Diataxis structure,
navigation, and CI. Runs as standalone scripts or as a 15-agent swarm for
large corpora.

## When to use / not use

Use for whole-corpus work: auditing, modernising, aligning docs to code, or
release/onboarding prep.

Skip in favour of a more direct path when:
- Writing a single markdown file or README — just write markdown.
- Generating a LaTeX report with charts/bibliography — use `report-builder`.
- Creating a diagram from text — use `mermaid-diagrams`.
- Generating API docs from code — use code-level doc tools directly.
- General code quality/testing workflows — use `build-with-quality`.

## Sequencing with prose-sanitiser

`validate-spelling.sh` is a structural, corpus-wide check: file by file, pass or fail,
against a UK-English wordlist. It does not catch AI writing tells such as em-dash
density, hedge padding, or generic phrasing. For a full modernisation, run
`docs-alignment` first to fix links, front matter, diagrams, and spelling, then run
`prose-sanitiser` per file for the prose-quality pass. Skipping the second step leaves
AI-tell removal undone.

## Prerequisites

- `docs-alignment` and sibling `docs-*` binaries (Rust, built from
  `services/skill-tools`) on `PATH`; Python 3.10+ (only for the
  still-Python `archive_working_docs.py`/`scan_stubs.py` steps); Node.js
  18+ (Mermaid validation); Git.
- A git repo with docs in `/docs` and a codebase to validate against.
- Claude Code Task tool (only for swarm orchestration).

## Quick start

Binary path — run the whole alignment in one command:

```bash
npm install -g @mermaid-js/mermaid-cli

docs-alignment \
  --project-root /path/to/project \
  --docs-dir ./docs \
  --codebase-dir ./src \
  --output-dir ./docs/working
```

Individual validators (each supports `--json`):

```bash
./scripts/validate-all.sh          # runs every check below
./scripts/validate-links.sh        # link integrity + orphans
./scripts/validate-frontmatter.sh  # YAML metadata
./scripts/validate-mermaid.sh      # diagram syntax / Git compliance
./scripts/detect-ascii.sh          # ASCII art to convert
./scripts/validate-spelling.sh     # UK English
./scripts/validate-structure.sh    # naming / layout
./scripts/generate-reports.sh      # quality scorecard
```

Full flag set for a strict pass:

```bash
docs-alignment --project-root . --docs-dir ./docs \
  --codebase-dir ./src --output-dir ./docs/working \
  --full-validation --git-compliant --uk-english --diataxis-strict
```

## Swarm path (large corpora)

For a comprehensive modernisation, deploy the 15-agent swarm via the Task tool:

```bash
claude-code << 'EOF'
Task("Documentation Alignment Swarm", `
  Execute documentation alignment using a 15-agent swarm.
  Project: /home/devuser/workspace/project
  Docs: ./docs   Output: ./docs/working
  Waves: inventory → IA design → modernisation → consolidation → QA/CI.
`, "system-architect")
EOF
```

The five-wave agent roster, per-phase execution detail, topology config, and
memory-coordination keys are in [`references/swarm.md`](references/swarm.md).

## References

- [`references/swarm.md`](references/swarm.md) — 15-agent composition, five-wave
  execution phases, topology, memory coordination.
- [`references/standards.md`](references/standards.md) — full validation-standards
  catalog (links, diagrams, front matter, spelling, content, structure,
  coverage), the A–F quality-scoring rubric, all output deliverables, and
  success-metric targets. Treat thresholds as tunable per project.
- [`docs/ADVANCED.md`](docs/ADVANCED.md) — custom topologies, validation-rule
  config, CI/CD (GitHub Actions / GitLab), custom report templates, large-codebase
  performance tuning.
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — install/validation/permission/
  performance/swarm failure modes and fixes.

## Related skills

- `skill-tuning` measures whether a skill's wording raises task success; this skill only checks corpus consistency.