validate-docs

name	validate-docs
description	Validate documentation pages against project conventions. Use when checking if doc pages are correctly set up, debugging broken navigation, or before committing doc changes. Checks all three registration points, TOC consistency, section IDs, and YAML schema compliance.
argument-hint	["page-slug"]
allowed-tools	Read, Grep, Glob, Bash(npx tsc --noEmit)

Validate Documentation Pages

Validate that documentation pages follow all project conventions. If $ARGUMENTS is provided, validate only the specified page slug. Otherwise, validate all pages.

Validation checklist

Run each check below and report results as PASS/FAIL with details.

Check 1: Four-file registration

For each page being validated, confirm it exists in all four locations:

1. lib/docs-data.ts — slug appears in docSections items array
2. lib/docs-data.ts — slug has entries in tocByPage
3. components/docs/page-content.tsx — slug has an import and entry in pageComponents
4. components/docs/pages/<slug>.tsx — component file exists
5. docs/<section-slug>/<slug>.md — markdown backup file exists

Report any pages that are missing from one or more locations.

Check 2: TOC-to-section ID consistency

For each page:

1. Read the TOC entries from tocByPage in lib/docs-data.ts
2. Read the page component file
3. Extract all id="..." attributes on elements with scroll-mt-20
4. Verify every TOC id has a matching element id in the component
5. Verify the first TOC entry is { title: "Overview", id: "overview" }

Report any mismatches (TOC IDs without matching sections, or sections without TOC entries).

Check 3: Section structure

For each page component, verify:

1. Every <section> tag has both an id attribute AND className containing scroll-mt-20
2. The header element uses id="overview" and scroll-mt-20
3. Sections are separated by <Separator className="my-8" />

Check 4: Import consistency

In components/docs/page-content.tsx, verify:

1. Every slug in pageComponents has a corresponding import statement
2. The import path matches @/components/docs/pages/<expected-filename>
3. The export name follows PascalCase-of-slug + "Page" convention

Check 5: YAML schema compliance

Search all page component files for CodeBlock usage with language="yaml". For any YAML that appears to be Harness pipeline configuration, verify it follows v1 schema:

• NO projectIdentifier, orgIdentifier, or identifier fields
• NO type: Deployment (should be type: deploy)
• NO spec: blocks inside steps (should use with:)
• NO <+expression> syntax (should use ${{ expression }})
• NO serviceRef or environmentRef (should be service and environment)

Check 6: TypeScript compilation

Run npx tsc --noEmit and report any type errors.

Output format

Documentation Validation Report
================================

Page: <slug>
  [PASS] Registered in docSections
  [PASS] Registered in tocByPage
  [PASS] Registered in pageComponents
  [PASS] Component file exists
  [PASS] Markdown backup exists
  [PASS] TOC IDs match section IDs
  [FAIL] Missing scroll-mt-20 on section "foo-section"
  ...

Summary: X pages checked, Y passed all checks, Z have issues

If all checks pass, congratulate the user. If there are failures, provide specific fix instructions for each issue.