docs: a followable demo, npx path, return shape, accurate CONTRIBUTING

[ryandmonk]

From an ecosystem-wide documentation audit. Every claim re-verified by running the code.

• Quick start wrote the versioned example to an unversioned filename — the exact collision CHANGELOG says the rename existed to prevent. Fixed, plus the npx path (verified working), so the local-install route is no longer a dead end.
• The demo walkthrough was unfollowable: it said "download it via the Quick start" then ran a v0.2 file the Quick start never produces (it ships v0.4, with different counts). Now fetches v0.2 explicitly (URL verified 200) and states the version difference.
• CONTRIBUTING described a "pre-alpha repository" with a "planned tool surface" (eleven tools ship) and linked twice to examples/README.md, which does not exist.
• SECURITY said "the dspack 0.3 generation tools"; the code gates on 0.3 and 0.4.
• README now documents the MCP return shape (JSON in a single text block; errors in the same channel, not protocol errors) — the one thing the stated "MCP client authors" audience needs, previously in no doc.

Rebased onto main after #27

This PR originally also rewrote the vendored-core paragraph to state the pin honestly as v0.1.2. #27 superseded that — it moved the pin to v0.5.0 and rewrote the paragraph to the post-re-pin truth. This branch no longer touches those lines, so the rebase was conflict-free and that paragraph now reads as #27 left it.

#27 also corrected two claims this branch originally made, both verified by diffing src/core across the pin commits:

• containment (spec v0.4 §5.1) is a gate-S2 vocabulary check, not an S3 rule family — it lives in vocabulary.ts.
• forbiddenCategories was already evaluated at v0.1.2. Only requiredCategories (§4.3) was genuinely unevaluatable.

This branch was also cut before #25, so its diff previously appeared to remove the adoption-guide link. That link is now correctly preserved.

Verification

On the rebased branch, with #27 in main: npm ci clean, 94/94 tests, scripts/smoke.sh passed, check-sync.mjs exit 0, check-core-pin.mjs "the pin is exactly the latest release tag". The eleven-tool surface, env/CLI vars, and client configs audited clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates project documentation based on an audit, aiming to make the docs accurate and runnable: clarifies the vendored dspack-gen core situation, fixes the Quick start workflow, makes the shadcn demo reproducible, and refreshes repo governance/security wording.

Changes:

• Fix Quick start example filename/versioning and add an npx install note.
• Document MCP tool return shape expectations and clarify the vendored dspack-gen core pin narrative.
• Update demo and contributor/security docs to remove broken links and reflect current tool/version reality.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
SECURITY.md	Clarifies generation tools apply to dspack 0.3/0.4 while preserving the read-only invariant text.
README.md	Fixes Quick start filename collision, documents MCP return shape, and updates vendored-core pin explanation.
docs/demo-shadcn.md	Makes the demo followable by explicitly fetching/running the v0.2 example dspack.
CONTRIBUTING.md	Removes outdated “pre-alpha” language and fixes references to non-existent examples/README.md.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[ryandmonk]

On the two red checks — both pre-existing, neither from this PR. This repo's CI last ran on 2026-07-22 (green); the drift accumulated after, and this docs PR is simply the first run since.

• core-pin-drift: the vendored dspack-gen pin is v0.1.2 while upstream is 0.3.2. This PR documents that honestly rather than silently changing a published tool's validation behavior.
• test → "Copy drift check": examples/shadcn-ui-v04.dspack.json differs from its source of truth in the dspack repo (which gained a requiredCategories rule in 0.4.3).

They are coupled — verified, not assumed. Running node scripts/check-sync.mjs --write alone (refreshing the example without re-pinning the core) takes the suite from 94 pass / 0 fail → 84 pass / 2 fail and breaks scripts/smoke.sh ("Expected at least 3 responses, got 0"). The newer contract needs the newer core, so the fix is one coordinated change: re-pin to v0.3.2's commit, rebuild, re-sync the example, re-verify the goldens — and it changes validate-ui output by design (it should start flagging containment and required-categories). That belongs in its own PR with its own release decision, not folded into documentation.

With the working tree as-is, npm test is 94 pass / 0 fail and scripts/smoke.sh passes; the red is entirely the two drift guards doing their job.