From 9b3fabb44ee0f82d3e32f6b512635535c2fa67ff Mon Sep 17 00:00:00 2001
From: Aaron Elijah Mars <61592645+aaronjmars@users.noreply.github.com>
Date: Mon, 20 Jul 2026 12:55:39 -0400
Subject: [PATCH] ci: gate apps/** and catalog/skill-packs.json
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two previously ungated surfaces:

- apps/** had zero CI despite Dependabot opening monthly grouped PRs
  against dashboard, mcp-server, and webhook — nothing ever verified
  those bumps left an app compiling. New ci-apps workflow: dashboard
  (typecheck + its 156 unit tests + `next build`, kept separate per the
  documented TS7/Next16 incompatibility), cli (typecheck, borrowing the
  dashboard's TypeScript since it has none of its own), mcp-server
  (build), webhook (syntax check + `wrangler deploy --dry-run`, no
  Cloudflare creds needed). Also added the missing apps/cli entry to
  dependabot.yml.

- catalog/skill-packs.json is the one file routinely hand-edited by
  outside contributors (every community pack listing), with nothing
  validating it. New scripts/validate-skill-packs.mjs + ci-skill-packs
  gate: registry shape (JSON, owner/repo format, non-empty unique
  skills[], trust_level enum, capabilities against the locked taxonomy
  read out of bin/install-skill-pack, secrets_required shape) and
  README parity (every entry has a matching table row and vice versa,
  skill counts agree, --path flags agree, handles monorepos publishing
  multiple packs, checks the "N community skill packs" counter). Also
  catches a self-declared trust_level: trusted that isn't backed by
  trusted-sources.txt, which is what the installer actually checks.
  30 test cases in scripts/tests/test_validate_skill_packs.sh, wired
  into ci-tests.

Docs (CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md, community-skill-packs.md,
apps/cli/README.md) updated to match.
---
 .github/CONTRIBUTING.md                    |  12 +
 .github/PULL_REQUEST_TEMPLATE.md           |   2 +
 .github/dependabot.yml                     |  16 +
 .github/workflows/ci-apps.yml              | 142 ++++++++
 .github/workflows/ci-skill-packs.yml       |  56 ++++
 .github/workflows/ci-tests.yml             |   2 +
 apps/cli/README.md                         |  12 +
 apps/cli/package.json                      |   3 +
 apps/dashboard/package.json                |   1 +
 apps/mcp-server/package.json               |   1 +
 docs/community-skill-packs.md              |  31 ++
 scripts/tests/test_validate_skill_packs.sh | 289 ++++++++++++++++
 scripts/validate-skill-packs.mjs           | 362 +++++++++++++++++++++
 13 files changed, 929 insertions(+)
 create mode 100644 .github/workflows/ci-apps.yml
 create mode 100644 .github/workflows/ci-skill-packs.yml
 create mode 100755 scripts/tests/test_validate_skill_packs.sh
 create mode 100644 scripts/validate-skill-packs.mjs

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index f5e1045a51..5af9a677c0 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -184,12 +184,24 @@ protect:
 | `ci-packs-json` | `packs.json` matches a fresh `bin/generate-packs-json` |
 | `ci-skill-category` | every `SKILL.md` declares a valid `category:` |
 | `ci-capabilities-parity` | the capabilities taxonomy stays in sync |
+| `ci-skill-packs` | `catalog/skill-packs.json` is well-formed **and** matches the README's Community Packs table |
+| `ci-apps` | each app in `apps/**` typechecks, tests, and builds |
+| `ci-tests` | the `scripts/tests/` suites pass |
+| `ci-okf` | the knowledge bundle stays OKF-conformant |
+| `ci-agents-md` | `AGENTS.md` is regenerated from `STRATEGY.md` |
 
 Run the checks locally before pushing:
 
 ```bash
 bash scripts/check-skill-categories.sh
 bash scripts/check-capabilities-parity.sh
+node scripts/validate-skill-packs.mjs          # listing a community pack
+```
+
+Touching `apps/**`? Run that app's own checks — for the dashboard:
+
+```bash
+cd apps/dashboard && npm ci && npm run typecheck && npm test && npm run build
 ```
 
 If `ci-skills-json`/`ci-packs-json` fails, you changed a generator input without
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 780323d505..4420c2050e 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -38,6 +38,7 @@
 - [ ] Pack has a `skills-pack.json` manifest at its root and a `SKILL.md` per skill
 - [ ] Write / onchain / bet skills are `default_enabled: false`
 - [ ] This PR adds **both** a README table row and a matching `skill-packs.json` entry
+- [ ] `node scripts/validate-skill-packs.mjs` passes (registry shape + README parity, incl. the pack counter)
 - [ ] No monkey-patching of Aeon internals; no private or auth-walled endpoints required to run
 
 ### Core fix (dashboard / scripts / workflows / docs)
@@ -45,6 +46,7 @@
 - [ ] Change is focused — one concern, no unrelated refactor
 - [ ] Touched code follows the existing pattern in the file
 - [ ] Relevant CI gates pass locally (e.g. `bash scripts/check-skill-categories.sh`, `bash scripts/check-capabilities-parity.sh`)
+- [ ] Touched `apps/**`? That app typechecks, tests, and builds (dashboard: `npm run typecheck && npm test && npm run build`)
 
 ---
 
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 569b7fe047..22ee454d8f 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -67,6 +67,22 @@ updates:
         patterns:
           - "*"
 
+  # CLI — non-interactive control of an Aeon repo; shares apps/dashboard/lib.
+  - package-ecosystem: "npm"
+    directory: "/apps/cli"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    assignees:
+      - "aeonfun"
+    commit-message:
+      prefix: "chore(deps)"
+      prefix-development: "chore(deps-dev)"
+    groups:
+      cli:
+        patterns:
+          - "*"
+
   # Cloudflare Worker that relays Telegram messages to a fork.
   - package-ecosystem: "npm"
     directory: "/apps/webhook"
diff --git a/.github/workflows/ci-apps.yml b/.github/workflows/ci-apps.yml
new file mode 100644
index 0000000000..9c188195bc
--- /dev/null
+++ b/.github/workflows/ci-apps.yml
@@ -0,0 +1,142 @@
+name: ci-apps
+
+# apps/** was the largest untested surface in the repo: four shipped apps — the
+# Next.js dashboard, the CLI, the MCP server, and the Telegram Worker — with no
+# gate of any kind. The dashboard alone carries 156 committed unit tests
+# (apps/dashboard/lib/**/*.test.ts) that nothing ran, plus a strict-mode
+# TypeScript config nothing typechecked.
+#
+# That gap is not theoretical. Dependabot opens grouped monthly npm PRs against
+# apps/dashboard, apps/mcp-server, and apps/webhook (.github/dependabot.yml) —
+# every one of them landed with zero automated verification that the app still
+# compiles. The TypeScript-7 pin comment in dependabot.yml records a breakage
+# caught by hand: `next build` crashed while `tsc --noEmit` passed. That is why
+# the dashboard job runs BOTH — a typecheck alone would have missed it.
+#
+# One job per app so a red X names the broken surface, and so a slow dashboard
+# build never masks a fast Worker failure. The workflow-level path filter is
+# `apps/**` rather than per-job filters: keeping it native (no third-party
+# paths-filter action) is worth re-running a 30-second Worker job on a
+# dashboard-only PR.
+#
+# No secrets, no network beyond the registry: `next build` is fully static here
+# (every route is dynamic/server-rendered at request time) and `wrangler
+# --dry-run` bundles the Worker without touching a Cloudflare account, so this
+# workflow runs green on fork PRs.
+#
+# Run locally: see each app's README, or the same commands used below.
+
+on:
+  pull_request:
+    paths:
+      - 'apps/**'
+      - '.github/workflows/ci-apps.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'apps/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# A force-push mid-review shouldn't leave a stale build burning a runner.
+concurrency:
+  group: ci-apps-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  dashboard:
+    name: dashboard — typecheck, test, build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/dashboard
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: apps/dashboard/package-lock.json
+      - name: Install deps
+        run: npm ci
+      - name: Typecheck (strict)
+        run: npm run typecheck
+      - name: Unit tests
+        run: npm test
+      # Kept separate from the typecheck on purpose — see the TS7 note above.
+      - name: Production build
+        run: npm run build
+
+  cli:
+    name: cli — typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: |
+            apps/cli/package-lock.json
+            apps/dashboard/package-lock.json
+      # The CLI deliberately shares one source of truth with the dashboard: its
+      # tsconfig compiles ../dashboard/lib/**/*.ts and borrows that app's
+      # typescript + @types (apps/cli/tsconfig.json `typeRoots`). So the CLI
+      # cannot be typechecked without the dashboard's node_modules — installing
+      # both here is what makes `npm run typecheck` resolve at all.
+      - name: Install dashboard deps (CLI borrows its typescript + @types)
+        run: npm ci
+        working-directory: apps/dashboard
+      - name: Install CLI deps
+        run: npm ci
+        working-directory: apps/cli
+      - name: Typecheck (strict, includes the shared dashboard lib)
+        run: npm run typecheck
+        working-directory: apps/cli
+
+  mcp-server:
+    name: mcp-server — build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/mcp-server
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+      # No package-lock.json is committed for this app, so `npm ci` is not
+      # available and the install floats within the package.json ranges.
+      - name: Install deps
+        run: npm install --no-audit --no-fund
+      # `npm run build` (tsc, emitting to dist/) rather than a bare --noEmit:
+      # dist/index.js is this package's published `bin`, so a build that cannot
+      # emit is a broken install for anyone running `aeon-mcp`.
+      - name: Build
+        run: npm run build
+
+  webhook:
+    name: webhook — worker bundle
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/webhook
+    env:
+      WRANGLER_SEND_METRICS: 'false'
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+      - name: Syntax check the Worker
+        run: node --check src/worker.js
+      # No lockfile committed for this app either — see mcp-server above.
+      - name: Install deps
+        run: npm install --no-audit --no-fund
+      # --dry-run validates wrangler.toml and bundles the Worker without any
+      # Cloudflare credentials, so a broken config or a bad import fails here
+      # instead of at deploy time.
+      - name: Bundle (wrangler --dry-run, no credentials needed)
+        run: npx wrangler deploy --dry-run --outdir "$RUNNER_TEMP/worker-dist"
diff --git a/.github/workflows/ci-skill-packs.yml b/.github/workflows/ci-skill-packs.yml
new file mode 100644
index 0000000000..4627b22b68
--- /dev/null
+++ b/.github/workflows/ci-skill-packs.yml
@@ -0,0 +1,56 @@
+name: ci-skill-packs
+
+# catalog/skill-packs.json is the community pack registry — and the one file in
+# this repo that is routinely hand-edited by people outside it. Every listing
+# arrives as an outside-contributor PR that must touch TWO surfaces in one diff
+# (docs/community-skill-packs.md publishing checklist): a row in the README's
+# Community Packs table and a matching registry entry. Nothing checked either.
+#
+# What shipping a bad edit costs: `bin/install-skill-pack --list` jq's this file
+# directly, and the dashboard's community-packs panel fetches it
+# (apps/dashboard/lib/packs.ts) — so one trailing comma breaks pack discovery for
+# every Aeon fork, not just this repo. A README row with no registry entry is
+# invisible to both. A `--path` flag that disagrees with the registry hands
+# browsers a copy-paste command that installs the wrong subtree.
+#
+# The validator also refuses a self-declared `trust_level: trusted` that is not
+# in skills/security/trusted-sources.txt: `--list` prints its trust badge from
+# the registry but the installer decides the real scan bypass from the trusted
+# file, so an unbacked claim advertises "security scan skipped" without earning
+# it. That check is why bin/install-skill-pack and trusted-sources.txt are
+# trigger paths here — the gate has to re-run when either side moves.
+#
+# Sibling of ci-packs-json.yml (first-party packs) and ci-skills-json.yml
+# (skill catalog); this covers the third, previously ungated, registry.
+#
+# Run locally: node scripts/validate-skill-packs.mjs
+
+on:
+  pull_request:
+    paths:
+      - 'catalog/skill-packs.json'
+      - '.github/README.md'
+      - 'bin/install-skill-pack'
+      - 'skills/security/trusted-sources.txt'
+      - 'scripts/validate-skill-packs.mjs'
+      - '.github/workflows/ci-skill-packs.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'catalog/skill-packs.json'
+      - '.github/README.md'
+      - 'bin/install-skill-pack'
+      - 'skills/security/trusted-sources.txt'
+      - 'scripts/validate-skill-packs.mjs'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Validate the community pack registry and its README parity
+        run: node scripts/validate-skill-packs.mjs
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
index 06f7fb19ab..874e1c0846 100644
--- a/.github/workflows/ci-tests.yml
+++ b/.github/workflows/ci-tests.yml
@@ -42,6 +42,8 @@ jobs:
         run: bash scripts/tests/test_run_actions_summary.sh
       - name: skill-pack manifest validation tests
         run: bash scripts/tests/test_validate_pack.sh
+      - name: community pack registry validation tests
+        run: bash scripts/tests/test_validate_skill_packs.sh
       - name: grok harness runner tests
         run: bash scripts/tests/test_run_grok.sh
       - name: state reducer tests
diff --git a/apps/cli/README.md b/apps/cli/README.md
index 1abbb3300b..3d9ca46c5d 100644
--- a/apps/cli/README.md
+++ b/apps/cli/README.md
@@ -95,3 +95,15 @@ Exit code is non-zero on error.
   (git), `auth.ts` (auth flow), `packs.ts` (pack join). Ten routes now wrap these.
 - `apps/dashboard/lib/gh.ts` honours `AEON_REPO_ROOT` so the shared lib is
   location-independent (unset = the dashboard's original cwd-relative behaviour).
+
+## Typecheck
+
+```bash
+(cd ../dashboard && npm ci)   # the CLI borrows the dashboard's typescript + @types
+npm ci && npm run typecheck   # strict; compiles src/ plus the shared dashboard lib
+```
+
+Because `tsconfig.json` compiles `../dashboard/lib/**/*.ts` and points
+`typeRoots` at that app, the CLI has no `typescript` dependency of its own and
+cannot be typechecked without the dashboard's `node_modules`. CI does exactly
+the two installs above — see `.github/workflows/ci-apps.yml`.
diff --git a/apps/cli/package.json b/apps/cli/package.json
index f6e5fa2d33..0d719110d3 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -8,6 +8,9 @@
   "bin": {
     "aeon": "./aeon"
   },
+  "scripts": {
+    "typecheck": "../dashboard/node_modules/.bin/tsc --noEmit -p tsconfig.json"
+  },
   "dependencies": {
     "yaml": "^2.9.0"
   },
diff --git a/apps/dashboard/package.json b/apps/dashboard/package.json
index 47e955f96f..0eae1269ea 100644
--- a/apps/dashboard/package.json
+++ b/apps/dashboard/package.json
@@ -7,6 +7,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
+    "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test 'lib/**/*.test.mjs' 'lib/**/*.test.ts'"
   },
   "dependencies": {
diff --git a/apps/mcp-server/package.json b/apps/mcp-server/package.json
index 3d9c193fbb..106ff41d9d 100644
--- a/apps/mcp-server/package.json
+++ b/apps/mcp-server/package.json
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "typecheck": "tsc --noEmit",
     "dev": "tsc --watch",
     "start": "node dist/index.js"
   },
diff --git a/docs/community-skill-packs.md b/docs/community-skill-packs.md
index 85c5d7b5ac..ef230ab96a 100644
--- a/docs/community-skill-packs.md
+++ b/docs/community-skill-packs.md
@@ -233,6 +233,37 @@ The operator is always the trust boundary. The install script does not auto-trus
 
 Pack maintainers update both in the same PR so the two surfaces stay in lockstep.
 
+### CI validates both (run it before you open the PR)
+
+`ci-skill-packs` gates every PR that touches the registry or the README:
+
+```bash
+node scripts/validate-skill-packs.mjs
+```
+
+It fails the PR on registry shape (unparseable JSON, a `repo` that isn't
+`owner/repo`, an empty or duplicated `skills[]`, a `trust_level` outside
+`trusted|community`, a capability outside the [locked taxonomy](CAPABILITIES.md),
+a `secrets_required` entry that isn't an env var name) and on README parity (an
+entry with no table row or a row with no entry, a skill count that disagrees with
+`skills[]`, a `--path` flag that disagrees with the registry's `path`, and the
+`N community skill packs` counter in the README's Proof of work section).
+
+Two things to know:
+
+- **`trust_level: trusted` must be earned.** `--list` prints its trust badge from
+  this registry, but the installer decides the real scan bypass from
+  `skills/security/trusted-sources.txt`. A `trusted` entry that isn't in that
+  file advertises "security scan skipped" without ever getting it, so the gate
+  rejects it. Community packs use `trust_level: community`.
+- **A subdirectory pack needs its `--path` in the README row.** If your registry
+  entry sets `path`, the table row has to show the matching
+  (`` `--path <dir>` ``) flag — otherwise the command a reader copies out of the
+  README installs the wrong subtree.
+
+Missing recommended fields (`name`, `description`, `author`) and unrecognised
+fields warn rather than fail.
+
 ---
 
 ## Listed packs
diff --git a/scripts/tests/test_validate_skill_packs.sh b/scripts/tests/test_validate_skill_packs.sh
new file mode 100755
index 0000000000..ff057afd6b
--- /dev/null
+++ b/scripts/tests/test_validate_skill_packs.sh
@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# Unit test for scripts/validate-skill-packs.mjs — registry shape, README parity,
+# and the trust/capability checks. No network, no GitHub auth required. Every
+# case runs against throwaway fixtures under /tmp; the last case runs the real
+# committed registry so a drifted main is caught here too.
+set -uo pipefail
+cd "$(dirname "$0")/../.." || exit 1
+
+V="scripts/validate-skill-packs.mjs"
+fail=0
+pass(){ echo "ok   - $1"; }
+bad(){ echo "FAIL - $1"; fail=1; }
+
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/validate-skill-packs.XXXXXX")"
+trap 'rm -rf "$TMP"' EXIT
+
+# ── Fixture builders ────────────────────────────────────────────────────────
+# A fixture dir holds the four inputs the validator reads. Callers overwrite
+# whichever one the case is about.
+
+# write_registry <dir> <packs-json-array>
+write_registry() {
+  cat > "$1/skill-packs.json" <<EOF
+{
+  "version": "1.0",
+  "updated": "2026-07-20",
+  "description": "Test registry.",
+  "packs": $2
+}
+EOF
+}
+
+# write_readme <dir> <count-claimed> <table-rows>
+write_readme() {
+  cat > "$1/README.md" <<EOF
+# Test README
+
+| **community** | **$2 community skill packs** published to the registry. |
+
+## Community Packs
+
+| Pack | Skills | Description |
+|------|--------|-------------|
+$3
+EOF
+}
+
+# The locked taxonomy is read out of the installer; fixture it so the test
+# doesn't depend on the real bin/install-skill-pack staying put.
+write_installer() {
+  cat > "$1/install-skill-pack" <<'EOF'
+#!/usr/bin/env bash
+ALLOWED_CAPABILITIES=(
+  read_only
+  external_api
+  writes_external_host
+  onchain_writes
+  agent_messaging
+  sends_notifications
+)
+EOF
+}
+
+write_trusted() {
+  cat > "$1/trusted-sources.txt" <<'EOF'
+# comment line
+goodowner/good-pack
+EOF
+}
+
+ONE_PACK='[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","license":"MIT","homepage":"https://example.com","category":"dev","trust_level":"community","skills":["alpha","beta"]}]'
+ONE_ROW='| [Good Pack](https://github.com/goodowner/good-pack) | 2 | A pack. |'
+
+# new_fixture <name> → prints the dir; baseline is valid and passes.
+new_fixture() {
+  local d="$TMP/$1"
+  mkdir -p "$d"
+  write_registry "$d" "$ONE_PACK"
+  write_readme "$d" 1 "$ONE_ROW"
+  write_installer "$d"
+  write_trusted "$d"
+  echo "$d"
+}
+
+run() {
+  node "$V" --registry "$1/skill-packs.json" --readme "$1/README.md" \
+            --installer "$1/install-skill-pack" --trusted "$1/trusted-sources.txt" 2>&1
+}
+
+# expect_ok <fixture> <label>
+expect_ok() {
+  local out; out="$(run "$1")"
+  if [[ $? -eq 0 ]]; then pass "$2"; else bad "$2 — expected exit 0, got:"; echo "$out" | sed 's/^/       /'; fi
+}
+
+# expect_fail <fixture> <expected-substring> <label>
+expect_fail() {
+  local out rc
+  out="$(run "$1")"; rc=$?
+  if [[ $rc -eq 0 ]]; then
+    bad "$3 — expected a failure, got exit 0"
+  elif [[ "$out" != *"$2"* ]]; then
+    bad "$3 — failed as expected but message missing \"$2\":"; echo "$out" | sed 's/^/       /'
+  else
+    pass "$3"
+  fi
+}
+
+# ── Baseline ────────────────────────────────────────────────────────────────
+d=$(new_fixture baseline)
+out="$(run "$d")"; rc=$?
+if [[ $rc -eq 0 ]]; then pass "a valid registry + matching README passes"
+else bad "a valid registry + matching README passes"; echo "$out" | sed 's/^/       /'; fi
+
+# ── Registry shape ──────────────────────────────────────────────────────────
+d=$(new_fixture badjson)
+printf '{ "packs": [ { "repo": "a/b", } ] }\n' > "$d/skill-packs.json"
+expect_fail "$d" "not valid JSON" "malformed JSON is rejected"
+
+d=$(new_fixture nopacks)
+printf '{ "version": "1.0" }\n' > "$d/skill-packs.json"
+expect_fail "$d" "no \`packs\` array" "a registry with no packs array is rejected"
+
+d=$(new_fixture norepo)
+write_registry "$d" '[{"name":"x","skills":["alpha"]}]'
+expect_fail "$d" "missing required \`repo\`" "a pack without \`repo\` is rejected"
+
+d=$(new_fixture repourl)
+write_registry "$d" '[{"repo":"https://github.com/goodowner/good-pack","skills":["alpha"]}]'
+expect_fail "$d" 'must be "owner/repo"' "a \`repo\` given as a URL is rejected"
+
+d=$(new_fixture reposubdir)
+write_registry "$d" '[{"repo":"goodowner/good-pack/aeon-skills","skills":["alpha"]}]'
+expect_fail "$d" 'must be "owner/repo"' "a \`repo\` with a trailing subdirectory is rejected"
+
+d=$(new_fixture dupe)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha"]},{"repo":"goodowner/good-pack","skills":["beta"]}]'
+expect_fail "$d" "duplicate entry" "a repo listed twice is rejected"
+
+d=$(new_fixture noskills)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":[]}]'
+expect_fail "$d" "non-empty array" "an empty \`skills\` array is rejected"
+
+d=$(new_fixture badslug)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["Alpha_One"]}]'
+expect_fail "$d" "lowercase kebab-case" "a non-slug skill name is rejected"
+
+d=$(new_fixture dupslug)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","alpha"]}]'
+expect_fail "$d" "listed twice" "a duplicated skill slug is rejected"
+
+d=$(new_fixture badhomepage)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","beta"],"homepage":"example.com"}]'
+expect_fail "$d" "http(s) URL" "a non-URL \`homepage\` is rejected"
+
+d=$(new_fixture badpath)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","beta"],"path":"/abs/dir"}]'
+expect_fail "$d" "repo-relative subdirectory" "an absolute \`path\` is rejected"
+
+d=$(new_fixture badsecret)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","beta"],"secrets_required":["lowercase_key"]}]'
+expect_fail "$d" "UPPER_SNAKE" "a non-env-var \`secrets_required\` entry is rejected"
+
+# ── Capability taxonomy (locked; read from the installer) ───────────────────
+d=$(new_fixture badcap)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","beta"],"capabilities":["reads_the_vibes"]}]'
+expect_fail "$d" "unknown capability" "a capability outside the locked taxonomy is rejected"
+
+d=$(new_fixture goodcap)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","skills":["alpha","beta"],"capabilities":["read_only","external_api"]}]'
+expect_ok "$d" "capabilities inside the taxonomy pass"
+
+# ── Trust model ─────────────────────────────────────────────────────────────
+d=$(new_fixture untrusted)
+write_registry "$d" '[{"repo":"randomowner/pack","name":"P","description":"d","author":"a","skills":["alpha","beta"],"trust_level":"trusted"}]'
+write_readme "$d" 1 '| [P](https://github.com/randomowner/pack) | 2 | d |'
+expect_fail "$d" "not in skills/security/trusted-sources.txt" "self-declared \`trusted\` without a trusted-sources entry is rejected"
+
+d=$(new_fixture trusted)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","skills":["alpha","beta"],"trust_level":"trusted"}]'
+expect_ok "$d" "\`trusted\` backed by trusted-sources.txt passes"
+
+d=$(new_fixture badtrust)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","beta"],"trust_level":"verified"}]'
+expect_fail "$d" "trust_level\` must be one of" "an unknown \`trust_level\` is rejected"
+
+# ── README parity ───────────────────────────────────────────────────────────
+d=$(new_fixture noreadmerow)
+write_readme "$d" 1 '| [Other](https://github.com/other/pack) | 1 | Other. |'
+expect_fail "$d" "no row in the README" "a registry entry with no README row is rejected"
+
+d=$(new_fixture noregentry)
+write_readme "$d" 1 "$ONE_ROW
+| [Ghost](https://github.com/ghost/pack) | 1 | Not in the registry. |"
+expect_fail "$d" "no entry in catalog/skill-packs.json" "a README row with no registry entry is rejected"
+
+d=$(new_fixture countmismatch)
+write_readme "$d" 1 '| [Good Pack](https://github.com/goodowner/good-pack) | 7 | A pack. |'
+expect_fail "$d" "README says 7 skill(s) but the registry lists 2" "a skill-count mismatch is rejected"
+
+d=$(new_fixture missingpathflag)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","path":"aeon-skills","skills":["alpha","beta"]}]'
+expect_fail "$d" "would install the wrong subtree" "a subdirectory pack whose README row omits \`--path\` is rejected"
+
+d=$(new_fixture pathok)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","path":"aeon-skills","skills":["alpha","beta"]}]'
+write_readme "$d" 1 '| [Good Pack](https://github.com/goodowner/good-pack/tree/main/aeon-skills) (`--path aeon-skills`) | 2 | A pack. |'
+expect_ok "$d" "a subdirectory pack with a matching \`--path\` row passes"
+
+d=$(new_fixture pathmismatch)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","path":"aeon-skills","skills":["alpha","beta"]}]'
+write_readme "$d" 1 '| [Good Pack](https://github.com/goodowner/good-pack) (`--path other-dir`) | 2 | A pack. |'
+expect_fail "$d" "registry \`path\` is" "a \`--path\` that disagrees with the registry is rejected"
+
+# A monorepo may publish two packs from different subdirectories — two registry
+# entries, two rows, matched on repo+path rather than repo alone.
+d=$(new_fixture monorepo)
+write_registry "$d" '[
+  {"repo":"goodowner/good-pack","name":"One","description":"d","author":"a","path":"packs/one","skills":["alpha"]},
+  {"repo":"goodowner/good-pack","name":"Two","description":"d","author":"a","path":"packs/two","skills":["beta","gamma"]}
+]'
+write_readme "$d" 2 '| [One](https://github.com/goodowner/good-pack) (`--path packs/one`) | 1 | d |
+| [Two](https://github.com/goodowner/good-pack) (`--path packs/two`) | 2 | d |'
+expect_ok "$d" "one repo publishing two packs from different paths passes"
+
+d=$(new_fixture monorepo_unlisted)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"One","description":"d","author":"a","path":"packs/one","skills":["alpha"]}]'
+write_readme "$d" 1 '| [One](https://github.com/goodowner/good-pack) (`--path packs/one`) | 1 | d |
+| [Two](https://github.com/goodowner/good-pack) (`--path packs/two`) | 2 | d |'
+expect_fail "$d" "no entry for this repo at path" "a second row from the same repo with no registry entry is rejected"
+
+d=$(new_fixture duperow)
+write_readme "$d" 1 "$ONE_ROW
+$ONE_ROW"
+expect_fail "$d" "listed twice in the README" "the same pack listed twice in the README is rejected"
+
+d=$(new_fixture counter)
+write_readme "$d" 9 "$ONE_ROW"
+expect_fail "$d" "9 community skill packs" "a stale README pack counter is rejected"
+
+# The first-party packs table earlier in the real README is also `| Pack | Skills |`;
+# the parser must anchor on the Community Packs section, not the first match.
+d=$(new_fixture twotables)
+cat > "$d/README.md" <<EOF
+# Test README
+
+| **community** | **1 community skill packs** published to the registry. |
+
+## Packs
+
+| Pack | Skills |
+|------|--------|
+| **Core** (\`core\`, 11) | \`auto-merge\`,\`heartbeat\` |
+
+## Community Packs
+
+| Pack | Skills | Description |
+|------|--------|-------------|
+$ONE_ROW
+EOF
+expect_ok "$d" "the first-party two-column packs table is not mistaken for the registry table"
+
+# ── Warnings do not fail the gate ───────────────────────────────────────────
+d=$(new_fixture unknownfield)
+write_registry "$d" '[{"repo":"goodowner/good-pack","name":"Good Pack","description":"A pack.","author":"goodowner","skills":["alpha","beta"],"secrets_optional":["TUNING_KEY"]}]'
+out="$(run "$d")"; rc=$?
+if [[ $rc -eq 0 && "$out" == *"unknown field \`secrets_optional\`"* ]]; then
+  pass "an unknown field warns but does not fail"
+else
+  bad "an unknown field warns but does not fail (rc=$rc)"; echo "$out" | sed 's/^/       /'
+fi
+
+d=$(new_fixture missingname)
+write_registry "$d" '[{"repo":"goodowner/good-pack","skills":["alpha","beta"]}]'
+out="$(run "$d")"; rc=$?
+if [[ $rc -eq 0 && "$out" == *"no \`description\`"* ]]; then
+  pass "missing recommended fields warn but do not fail"
+else
+  bad "missing recommended fields warn but do not fail (rc=$rc)"; echo "$out" | sed 's/^/       /'
+fi
+
+# ── The committed registry itself ───────────────────────────────────────────
+out="$(node "$V" 2>&1)"; rc=$?
+if [[ $rc -eq 0 ]]; then pass "the committed catalog/skill-packs.json conforms and matches the README"
+else bad "the committed catalog/skill-packs.json conforms and matches the README"; echo "$out" | sed 's/^/       /'; fi
+
+echo ""
+if [[ $fail -eq 0 ]]; then echo "test_validate_skill_packs: ALL PASS"; else echo "test_validate_skill_packs: FAILURES"; fi
+exit "$fail"
diff --git a/scripts/validate-skill-packs.mjs b/scripts/validate-skill-packs.mjs
new file mode 100644
index 0000000000..e551ecfd71
--- /dev/null
+++ b/scripts/validate-skill-packs.mjs
@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+// validate-skill-packs.mjs — conformance checker for catalog/skill-packs.json,
+// the community pack registry, and its parity with the README's Community Packs
+// table.
+//
+// Why this gate exists: skill-packs.json is the ONE file in the repo that is
+// routinely edited by people outside it — every pack listing lands as an
+// outside-contributor PR that hand-edits JSON (see docs/community-skill-packs.md
+// "publishing checklist"). Nothing validated it. A trailing comma, a `skill:`
+// typo, or a README row without a registry entry ships to main and breaks
+// `bin/install-skill-pack --list` (it jq's this file) and the dashboard's
+// community-packs panel (apps/dashboard/lib/packs.ts) for everyone.
+//
+// Two classes of check, both hard failures:
+//
+//   1. REGISTRY SHAPE — the fields `--list` and the dashboard actually read:
+//      parseable JSON, `repo` as owner/repo, a non-empty unique `skills[]`,
+//      `trust_level` in the enum, `capabilities[]` inside the LOCKED taxonomy
+//      (read out of bin/install-skill-pack so it can never drift from the
+//      installer — cf. scripts/check-capabilities-parity.sh, Issue #301).
+//
+//   2. README PARITY — every registry entry has a table row and vice versa,
+//      with matching skill counts and matching `--path` flags. The publishing
+//      checklist asks for both surfaces in one diff; this is what enforces it.
+//      A row whose `--path` is missing hands browsers a copy-paste CLI command
+//      that installs the wrong subtree, so path parity is an error, not a nit.
+//
+// One security-relevant check: `trust_level: trusted` is only honest if the repo
+// is actually in skills/security/trusted-sources.txt. `--list` prints its badge
+// from the registry (install-skill-pack:176) but decides the real scan bypass
+// from the trusted-sources file (install-skill-pack:524) — so a self-declared
+// `trusted` entry advertises "security scan skipped" without ever earning it.
+//
+// Deliberately NOT enforced (over-conformance would fight contributors for no
+// tooling benefit): `category` vocabulary — the registry's is open and already
+// carries values the per-skill list doesn't have (`messaging`, `memory`); prose
+// style; whether `homepage` resolves. Missing recommended fields are warnings.
+//
+// Usage:
+//   node scripts/validate-skill-packs.mjs
+//   node scripts/validate-skill-packs.mjs --registry <path> --readme <path> \
+//        --installer <path> --trusted <path>     # fixture overrides, for tests
+//
+// Exit 1 on any violation; exit 0 (with `validate-skill-packs: OK`) otherwise.
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+// ---- args ----
+const args = process.argv.slice(2)
+const opt = (flag, fallback) => {
+  const i = args.indexOf(flag)
+  return i !== -1 && args[i + 1] ? args[i + 1] : fallback
+}
+const REGISTRY = opt('--registry', resolve(ROOT, 'catalog/skill-packs.json'))
+const README = opt('--readme', resolve(ROOT, '.github/README.md'))
+const INSTALLER = opt('--installer', resolve(ROOT, 'bin/install-skill-pack'))
+const TRUSTED = opt('--trusted', resolve(ROOT, 'skills/security/trusted-sources.txt'))
+
+const errors = []
+const warnings = []
+const err = (m) => errors.push(m)
+const warn = (m) => warnings.push(m)
+
+const done = (summary) => {
+  for (const w of warnings) console.warn(`validate-skill-packs: WARN ${w}`)
+  if (errors.length) {
+    for (const e of errors) console.error(`::error::validate-skill-packs: ${e}`)
+    console.error('')
+    console.error(`validate-skill-packs: FAIL — ${errors.length} violation(s).`)
+    console.error('Registry schema and the publishing checklist: docs/community-skill-packs.md')
+    console.error('Run locally: node scripts/validate-skill-packs.mjs')
+    process.exit(1)
+  }
+  console.log(`validate-skill-packs: OK — ${summary}` + (warnings.length ? ` (${warnings.length} warning(s))` : ''))
+  process.exit(0)
+}
+
+// ---- the locked capability taxonomy, read from the installer ----
+// Source of truth is ALLOWED_CAPABILITIES in bin/install-skill-pack; parsing it
+// here means a taxonomy change lands in one place and this gate follows.
+function loadCapabilities() {
+  if (!existsSync(INSTALLER)) {
+    warn(`installer not found at ${INSTALLER} — capability taxonomy unchecked`)
+    return null
+  }
+  const m = readFileSync(INSTALLER, 'utf8').match(/ALLOWED_CAPABILITIES=\(([^)]*)\)/)
+  if (!m) {
+    warn('could not parse ALLOWED_CAPABILITIES from the installer — capability taxonomy unchecked')
+    return null
+  }
+  const caps = m[1].split(/\s+/).map((s) => s.trim()).filter(Boolean)
+  return caps.length ? caps : null
+}
+
+// ---- trusted sources (owner or owner/repo, one per line) ----
+function loadTrusted() {
+  if (!existsSync(TRUSTED)) return null
+  return new Set(
+    readFileSync(TRUSTED, 'utf8')
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith('#'))
+  )
+}
+const isTrusted = (trusted, repo) => trusted.has(repo) || trusted.has(repo.split('/')[0])
+
+// ---- README Community Packs table ----
+// Rows look like:
+//   | [name](https://github.com/owner/repo) | 2 | Description. |
+//   | [name](https://github.com/owner/repo/tree/main/sub) (`--path sub`) | 3 | … |
+// Anchored to the "## Community Packs" heading and the 3-column header, because
+// the README also carries a 2-column `| Pack | Skills |` table for the
+// first-party packs earlier in the file.
+function parseReadmeTable(text) {
+  const lines = text.split(/\r?\n/)
+  const section = lines.findIndex((l) => /^#+\s+Community Packs\s*$/i.test(l))
+  const from = section === -1 ? 0 : section
+  const found = lines.slice(from).findIndex((l) => /^\|\s*Pack\s*\|\s*Skills\s*\|\s*Description\s*\|/i.test(l))
+  if (found === -1) return null
+  const header = from + found
+
+  const rows = []
+  for (let i = header + 2; i < lines.length; i++) {
+    const line = lines[i]
+    if (!line.startsWith('|')) break
+    const cells = line.split('|').slice(1, -1).map((c) => c.trim())
+    if (cells.length < 3) continue
+
+    const [pack, count] = cells
+    const link = pack.match(/https:\/\/github\.com\/([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)((?:\/tree\/[^/)\s]+\/([^)\s]+))?)/)
+    if (!link) {
+      err(`README: Community Packs row has no github.com/<owner>/<repo> link — "${pack}"`)
+      continue
+    }
+    const flag = pack.match(/--path\s+([^\s`)]+)/)
+    rows.push({
+      repo: link[1],
+      // The copy-paste CLI flag wins; the /tree/ link path is the fallback.
+      path: flag ? flag[1] : link[3] || '',
+      hasFlag: Boolean(flag),
+      treePath: link[3] || '',
+      count: /^\d+$/.test(count) ? Number(count) : null,
+      rawCount: count,
+      line: i + 1,
+    })
+  }
+  return rows
+}
+
+// ---- registry ----
+if (!existsSync(REGISTRY)) {
+  err(`registry not found at ${REGISTRY}`)
+  done('')
+}
+
+let registry
+try {
+  registry = JSON.parse(readFileSync(REGISTRY, 'utf8'))
+} catch (e) {
+  err(`${REGISTRY} is not valid JSON — ${e.message}`)
+  done('')
+}
+
+if (registry === null || typeof registry !== 'object' || Array.isArray(registry)) {
+  err('registry root must be a JSON object')
+  done('')
+}
+if (!Array.isArray(registry.packs)) {
+  err('registry has no `packs` array')
+  done('')
+}
+if (typeof registry.version !== 'string' || !registry.version) warn('registry has no `version` string')
+if (typeof registry.updated !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(registry.updated)) {
+  warn(`registry \`updated\` should be an ISO date (YYYY-MM-DD), got ${JSON.stringify(registry.updated)}`)
+}
+
+const ALLOWED_CAPS = loadCapabilities()
+const trusted = loadTrusted()
+const TRUST_LEVELS = ['trusted', 'community']
+const KNOWN_FIELDS = new Set([
+  'repo', 'path', 'name', 'description', 'author', 'license', 'homepage',
+  'category', 'trust_level', 'skills', 'secrets_required', 'capabilities',
+])
+
+const seen = new Map()
+
+registry.packs.forEach((pack, i) => {
+  const at = `packs[${i}]`
+  if (pack === null || typeof pack !== 'object' || Array.isArray(pack)) {
+    err(`${at}: must be an object`)
+    return
+  }
+  const id = typeof pack.repo === 'string' && pack.repo ? pack.repo : at
+
+  // repo — required, owner/repo only (a URL or trailing path breaks the clone).
+  if (typeof pack.repo !== 'string' || !pack.repo) {
+    err(`${at}: missing required \`repo\` (owner/repo)`)
+  } else if (!/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(pack.repo)) {
+    err(`${id}: \`repo\` must be "owner/repo" — no URL, no trailing slash, no subdirectory (put a subdirectory in \`path\`)`)
+  } else {
+    const key = `${pack.repo}#${pack.path ?? ''}`
+    if (seen.has(key)) err(`${id}: duplicate entry — already listed at packs[${seen.get(key)}]`)
+    else seen.set(key, i)
+  }
+
+  // skills — required, non-empty, unique slugs. `--list` prints the count and
+  // the installer resolves each slug inside the pack repo.
+  if (!Array.isArray(pack.skills) || pack.skills.length === 0) {
+    err(`${id}: \`skills\` must be a non-empty array of slugs`)
+  } else {
+    const slugs = new Set()
+    for (const s of pack.skills) {
+      if (typeof s !== 'string' || !s) err(`${id}: \`skills\` contains a non-string entry (${JSON.stringify(s)})`)
+      else if (!/^[a-z0-9][a-z0-9-]*$/.test(s)) err(`${id}: skill slug "${s}" must be lowercase kebab-case (it is a directory name under skills/)`)
+      else if (slugs.has(s)) err(`${id}: skill slug "${s}" listed twice`)
+      else slugs.add(s)
+    }
+  }
+
+  // Recommended display fields — `--list` and the dashboard card degrade
+  // without them, but nothing breaks.
+  for (const f of ['name', 'description', 'author']) {
+    if (pack[f] === undefined) warn(`${id}: no \`${f}\` — recommended (docs/community-skill-packs.md field reference)`)
+    else if (typeof pack[f] !== 'string' || !pack[f].trim()) err(`${id}: \`${f}\` must be a non-empty string`)
+  }
+  for (const f of ['license', 'category', 'path']) {
+    if (pack[f] !== undefined && (typeof pack[f] !== 'string' || !pack[f].trim())) {
+      err(`${id}: \`${f}\` must be a non-empty string when present`)
+    }
+  }
+  if (pack.path !== undefined && typeof pack.path === 'string' && /^\/|^\.\.|\/$/.test(pack.path)) {
+    err(`${id}: \`path\` must be a repo-relative subdirectory (no leading "/", no "..", no trailing "/")`)
+  }
+  if (pack.homepage !== undefined && !/^https?:\/\/\S+$/.test(String(pack.homepage))) {
+    err(`${id}: \`homepage\` must be an http(s) URL`)
+  }
+
+  // trust_level — enum, and `trusted` must be backed by trusted-sources.txt.
+  if (pack.trust_level !== undefined) {
+    if (!TRUST_LEVELS.includes(pack.trust_level)) {
+      err(`${id}: \`trust_level\` must be one of ${TRUST_LEVELS.join('|')} (got ${JSON.stringify(pack.trust_level)})`)
+    } else if (pack.trust_level === 'trusted' && trusted && typeof pack.repo === 'string' && !isTrusted(trusted, pack.repo)) {
+      err(
+        `${id}: declares \`trust_level: trusted\` but is not in skills/security/trusted-sources.txt — ` +
+          '`--list` would badge it as scan-skipped without the installer ever honouring it'
+      )
+    }
+  }
+
+  // capabilities — the locked taxonomy (docs/CAPABILITIES.md).
+  if (pack.capabilities !== undefined) {
+    if (!Array.isArray(pack.capabilities)) {
+      err(`${id}: \`capabilities\` must be an array`)
+    } else if (ALLOWED_CAPS) {
+      for (const c of pack.capabilities) {
+        if (!ALLOWED_CAPS.includes(c)) {
+          err(`${id}: unknown capability ${JSON.stringify(c)} — allowed: ${ALLOWED_CAPS.join(', ')} (docs/CAPABILITIES.md)`)
+        }
+      }
+    }
+  }
+
+  // secrets_required — env var names; drives `--list --no-secrets`.
+  if (pack.secrets_required !== undefined) {
+    if (!Array.isArray(pack.secrets_required)) {
+      err(`${id}: \`secrets_required\` must be an array`)
+    } else {
+      for (const s of pack.secrets_required) {
+        if (typeof s !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(s)) {
+          err(`${id}: \`secrets_required\` entry ${JSON.stringify(s)} must be an UPPER_SNAKE env var name`)
+        }
+      }
+    }
+  }
+
+  // Unknown fields are almost always typos of a real one (`skill`, `capability`).
+  for (const f of Object.keys(pack)) {
+    if (!KNOWN_FIELDS.has(f)) warn(`${id}: unknown field \`${f}\` — typo? (known: ${[...KNOWN_FIELDS].join(', ')})`)
+  }
+})
+
+// ---- README parity ----
+if (!existsSync(README)) {
+  warn(`README not found at ${README} — parity unchecked`)
+} else {
+  const readmeText = readFileSync(README, 'utf8')
+  const rows = parseReadmeTable(readmeText)
+
+  if (rows === null) {
+    warn('README has no "| Pack | Skills | Description |" table — parity unchecked')
+  } else {
+    // A repo may legitimately appear more than once (a monorepo publishing two
+    // packs from different subdirectories), so rows are matched on repo+path
+    // first and fall back to the repo when it has exactly one row — that
+    // fallback is what lets the path checks below report a useful mismatch
+    // instead of a bare "no README row".
+    const rowsByRepo = new Map()
+    for (const r of rows) {
+      if (!rowsByRepo.has(r.repo)) rowsByRepo.set(r.repo, [])
+      rowsByRepo.get(r.repo).push(r)
+    }
+    for (const [repo, group] of rowsByRepo) {
+      const paths = new Set(group.map((r) => r.path))
+      if (paths.size !== group.length) {
+        err(`${repo}: listed twice in the README Community Packs table with the same path (README:${group.map((r) => r.line).join(', ')})`)
+      }
+    }
+
+    const claimed = new Set()
+    const registryRepos = new Set()
+
+    for (const pack of registry.packs) {
+      if (typeof pack?.repo !== 'string' || !pack.repo) continue
+      registryRepos.add(pack.repo)
+      const group = rowsByRepo.get(pack.repo) ?? []
+      const wantPath = typeof pack.path === 'string' ? pack.path : ''
+      const row = group.find((r) => r.path === wantPath) ?? (group.length === 1 ? group[0] : undefined)
+      if (row) claimed.add(row)
+      if (!row) {
+        err(`${pack.repo}: in the registry but has no row in the README Community Packs table — the publishing checklist asks for both in one diff`)
+        continue
+      }
+      const count = Array.isArray(pack.skills) ? pack.skills.length : null
+      if (row.count === null) {
+        err(`${pack.repo}: README row Skills column is not a number ("${row.rawCount}", README:${row.line})`)
+      } else if (count !== null && row.count !== count) {
+        err(`${pack.repo}: README says ${row.count} skill(s) but the registry lists ${count} (README:${row.line})`)
+      }
+
+      if (wantPath && !row.hasFlag) {
+        err(`${pack.repo}: registry \`path: "${wantPath}"\` but the README row shows no (\`--path ${wantPath}\`) — the copy-paste command would install the wrong subtree (README:${row.line})`)
+      } else if (wantPath !== row.path) {
+        err(`${pack.repo}: registry \`path\` is ${JSON.stringify(wantPath)} but the README row says ${JSON.stringify(row.path)} (README:${row.line})`)
+      } else if (row.treePath && row.treePath !== wantPath) {
+        err(`${pack.repo}: README link points into /tree/…/${row.treePath} but the registry \`path\` is ${JSON.stringify(wantPath)} (README:${row.line})`)
+      }
+    }
+
+    // Matched on the row object, not the repo: a monorepo with two rows and one
+    // registry entry leaves the second row genuinely unlisted.
+    for (const row of rows) {
+      if (claimed.has(row)) continue
+      const hint = registryRepos.has(row.repo) ? ` — the registry has no entry for this repo at path ${JSON.stringify(row.path)}` : ''
+      err(`${row.repo}: has a README Community Packs row but no entry in catalog/skill-packs.json (README:${row.line})${hint} — \`bin/install-skill-pack --list\` and the dashboard would not show it`)
+    }
+
+    // The proof-of-work counter drifts every time a pack lands. Only enforced
+    // when the sentence is present and parseable, so a reword can't false-fail.
+    const counter = readmeText.match(/\*\*(\d+)\s+community skill packs\*\*/)
+    if (!counter) {
+      warn('README has no "**N community skill packs**" counter — count parity unchecked')
+    } else if (Number(counter[1]) !== registry.packs.length) {
+      err(`README claims "${counter[1]} community skill packs" but the registry lists ${registry.packs.length} — update the Proof of work line`)
+    }
+  }
+}
+
+done(`${registry.packs.length} pack(s) in the registry conform and match the README table`)