Add docs validation script

[autocarl]

Summary

• Adds npm run docs:validate for Repl/MCP documentation invariants.
• Validates copy/paste MCP host JSON snippets, including no-build dotnet run host launches and VS Code servers shape requirements.
• Guards Repl.Mcp wording so docs describe it as the component used to build MCP servers, not as the server users install directly.

Verification

• npm run docs:validate — passed, 37 files checked.
• git diff --check — passed.
• ASTRO_TELEMETRY_DISABLED=1 XDG_CONFIG_HOME=/workspace/.config npm run astro -- build — passed, 36 pages built.

Follow-up needed for CI wiring

I attempted to include the read-only PR workflow and to remove the daily Pages deploy schedule, but the current autocarl token only has the repo scope. GitHub rejected pushes that modify .github/workflows/* without the workflow scope:

refusing to allow a Personal Access Token to create or update workflow `.github/workflows/deploy.yml` without `workflow` scope

So this PR intentionally contains the script only. With a token/account that has the workflow scope, the CI wiring should add this workflow:

name: Validate docs

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout website
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm

      - name: Install npm dependencies
        run: npm ci

      - name: Validate documentation invariants
        run: npm run docs:validate

      - name: Build Astro content
        run: npm run astro -- build
        env:
          ASTRO_TELEMETRY_DISABLED: '1'

Daily deployment note

The daily deployment is caused by .github/workflows/deploy.yml:

schedule:
  - cron: '0 6 * * *'

If daily deploys are not useful, remove that schedule block. Deploys will still happen on push to main, workflow_dispatch, and repository_dispatch from Repl releases.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c7d4909dee

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[carldebilly]

Good idea overall — this encodes the invariants from the recent MCP docs reviews (--no-build, repl-contacts-sample, VS Code servers shape, Repl.Mcp wording) as executable checks. One logic error and a couple of coordination notes below.

Cross-repo note: this validator consecrates --no-build + a prior dotnet build as the canonical host-config form. The yllibed/repl repo (PR #37) currently documents plain dotnet run in the sample README and configs/*.json — those should be aligned to the same form, otherwise the repo and the website will document two different shapes for the same sample.

[autocarl]

Review round addressed.

Changes pushed:

• 362879d — accepts --no-build anywhere before the -- app-argument separator, reports Repl.Mcp wording on the actual line, and fails unterminated ```json fences instead of silently dropping them.
• ccae366 — merged current origin/main so this PR validates against the already-merged PR Add coding-agent guidance and llms.txt decision rules #1 docs.

Verification:

• npm run docs:validate ✅ Documentation validation passed (38 files checked).
• Fixture smoke checks ✅ valid reordered --no-build passes; --no-build after -- fails; Repl.Mcp reports line 4; unclosed JSON fence fails.
• git diff --check ✅
• npm run build ⚠️ blocked before Astro build: No Repl source projects or existing DocFX metadata were found. Check out the Repl source into ./repl-source or run DocFX metadata first.

I replied to each inline review thread individually.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ccae366fa3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".