Add lightweight AsciiDoc validation for agent and CI use

[fullsend-ai-retro]

What happened

PR #238 (#238) onboarded the fullsend agent infrastructure. The CLAUDE.md was added with repo structure guidance and mentions make ec-docs-preview as the documentation preview command. However, this command requires cloning an external repository (conforma/conforma.github.io) and its full Antora build dependencies, making it unusable in agent sandboxes or lightweight CI environments. There is no alternative validation step — no AsciiDoc linting, no cross-reference checking, and no link validation. Agents making documentation changes currently have no way to verify their work beyond reading the raw AsciiDoc.

What could go better

Future agent-authored documentation PRs risk introducing broken cross-references (xref), invalid AsciiDoc syntax, or dead links that won't be caught until a human previews the built site. For a docs-only repo where agents will primarily be editing .adoc files, having a fast validation step is important for both review quality (the review agent can flag build errors) and rework rate (the code agent can catch its own mistakes before pushing).

Confidence: Medium-high. This is a structural gap observable from the repo configuration. The actual impact depends on how frequently agents will make documentation changes, which I cannot determine from this single onboarding PR.

Proposed change

1. Add a lightweight AsciiDoc validation target to the Makefile (e.g., make validate-docs) that can run without external dependencies. Options include:

   • asciidoctor with --failure-level=WARN to catch syntax errors
   • A script that validates all xref: targets resolve to existing .adoc files in the pages/ directory
   • antora-xref-validator for cross-reference checking

2. Update CLAUDE.md to document the new validation command under "Common Commands" so agents discover and use it.

3. Optionally add a CI workflow step that runs this validation on PRs touching modules/** paths, providing automated feedback before human review.

Validation criteria

1. A make validate-docs (or similar) target exists and completes successfully on the current repo content without requiring external repos or network access.
2. The command catches at least: (a) invalid AsciiDoc syntax that would cause Asciidoctor warnings, and (b) broken xref: references to non-existent pages.
3. CLAUDE.md documents the validation command.
4. An agent editing a .adoc file can run the validation command in its sandbox and get pass/fail feedback.

---

Generated by retro agent from #238

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 10:20 AM UTC · Completed 10:23 AM UTC
Commit: 87c4a29 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Feature request

Problem

The repository lacks lightweight documentation validation. The existing make ec-docs-preview target requires cloning conforma/conforma.github.io and running a full Antora build, making it unusable in agent sandboxes or CI environments. There is currently no way for agents to verify that their .adoc edits produce valid AsciiDoc or correct cross-references.

Recommended Approach

1. Add a make validate-docs target that runs asciidoctor --failure-level=WARN across all .adoc files in modules/ROOT/pages/ to catch syntax errors without external dependencies.
2. Add xref validation — either a shell script that checks xref: targets resolve to existing files, or use antora-xref-validator.
3. Update CLAUDE.md to document the new validation command under "Common Commands."
4. Optionally add CI — a workflow step that runs validation on PRs touching modules/** paths.

Proposed Test Case

1. Run `make validate-docs` on current repo — should pass cleanly.
2. Introduce a syntax error (e.g., unclosed block delimiter) — should fail.
3. Add a broken xref (e.g., xref:nonexistent-page.adoc[]) — should report it.
4. Verify the command works offline with no external repo dependencies.

The issue is well-specified with clear validation criteria and is ready for implementation.

---

Labels: This is a new feature request for adding documentation validation tooling, matching the 'enhancement' label.