feat(cli): blueprints — dawn add for served integration guides (item 1)

[blove]

Summary

Adds flue's highest-leverage distribution idea to Dawn: integration blueprints — Markdown guides served from dawnai.org that a coding agent applies to a user's project. Ships the mechanism + four exemplars.

• dawn add <name> fetches dawnai.org/blueprints/<name>.md and prints the guide for your coding agent to apply (dawn add lists the catalog; dawn add <url> applies a third-party guide). Override the host with DAWN_BLUEPRINTS_URL.
• Flat-name addressing (research-backed — 6/7 analogous registries drop kind from the address): identity = filename, category = directory, never in the address/URL.
• Served, not bundled — the deliberate counterpart to the bundled docs in feat(cli): bundle version-matched docs + SKILL.md, add 'dawn docs' (item 2) #263: docs are version-coupled (bundle), blueprints want freshness + release-free growth (serve).
• Shared loader (apps/web/lib/blueprints.ts, gray-matter) feeds two routes (/blueprints/[name].md + /blueprints/index.json) and a catalog-integrity test.
• Four exemplars across 3 categories / 3 shapes: retrieval/pgvector + retrieval/pinecone (tools), observability/opentelemetry (instrumentation), deploy/docker (artifact). Each carries a // dawn-blueprint: <name>@1 marker for a future dawn update.
• Docs: a blueprints.mdx page (auto-ships in the bundled CLI docs) + cli.mdx entries (also fills a dawn docs doc gap from feat(cli): bundle version-matched docs + SKILL.md, add 'dawn docs' (item 2) #263).

Design: docs/superpowers/specs/2026-06-24-blueprints-design.md · Plan: docs/superpowers/plans/2026-06-24-blueprints.md

Test Plan

• pnpm --filter web exec vitest run app/blueprints (11) — loader, routes, catalog integrity over the real four
• pnpm --filter @dawn-ai/cli exec vitest run test/add-command.test.ts (5)
• pnpm build / typecheck / lint clean; changeset gate passes
• Holistic review: flow/identity/marker/frontmatter-strip coherent; OTel guide uses the current v2 resourceFromAttributes API
• Smoke DAWN_BLUEPRINTS_URL=<preview> dawn add + dawn add pgvector against a deploy preview

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dawnai	Ready	Preview, Comment	Jun 27, 2026 5:03pm

[github-actions]

Claude finished @blove's task in 2m 59s —— View job

---

PR Review: feat(cli): blueprints — dawn add for served integration guides

• Gathered context (CLAUDE.md, PR diff, key files)
• Reviewed correctness bugs
• Reviewed security issues
• Reviewed TypeScript type-safety
• Reviewed test coverage
• Posted findings as inline comments

---

Summary

The architecture is clean and well-structured: the shared loader in apps/web/lib/blueprints.ts powers both the web routes and catalog-integrity tests, the flat-name addressing is consistent end-to-end, and the four exemplar blueprints are well-written. The overall design is solid.

Four issues worth addressing before merge, all in packages/cli/src/commands/add.ts:

Severity	Location	Issue
Medium	add.ts:92	No validation on args.target — path traversal chars (../, ?, #) produce unexpected URLs
Medium	add.ts:47	JSON.parse(text) as CatalogEntry[] is an unchecked cast — malformed/null response throws a cryptic TypeError
Low	add.ts:25-38	No fetch timeout — CLI can hang indefinitely on a slow/hung server
Low	add.ts:83-89	Third-party URLs print raw frontmatter (inconsistent with official routes that strip it)

Three missing test cases are also flagged on add-command.test.ts: the non-200/non-404 error path, malformed catalog JSON, and the DAWN_BLUEPRINTS_URL env var branch.

Everything else looks good: the web routes are correct, generateStaticParams uses the right .md-suffixed params, the validateBlueprints logic is thorough, and all four blueprints carry valid frontmatter and dawn-blueprint markers.

[github-actions]

Claude finished @blove's task in 2m 35s —— View job

---

PR Review: feat(cli): blueprints — dawn add for served integration guides

• Gathered PR context
• Read current diff and key files
• Checked prior review issues
• Posted inline findings
• Posted summary

---

Summary

The new commit (e4cfe19) fixes the blueprints directory resolution for the CI test runner — the defaultDir() fallback using import.meta.url is the right call and works correctly. Everything in apps/web/ looks good.

All four issues flagged in the 2026-06-25 review remain open in packages/cli/src/commands/add.ts:

Severity	Location	Status	Issue
Medium	add.ts:92	Still open	No validation on args.target — path traversal chars accepted
Medium	add.ts:46	Still open	Array.isArray check missing — valid non-array JSON (e.g. null) throws unhandled TypeError
Low	add.ts:25-38	Still open	No fetch timeout — CLI hangs on slow/hung server
Low	add.ts:88	Still open	Third-party URL prints raw frontmatter (inconsistent with server-stripped official blueprints)

Note on issue #2: the try/catch added around JSON.parse does handle the invalid-syntax case now, but the missing Array.isArray guard means a server returning null still breaks silently with a cryptic runtime error.

Three test gaps from the prior review also remain (non-200/non-404 path, non-array catalog JSON, DAWN_BLUEPRINTS_URL env var) — see inline comment on add-command.test.ts:87.

[github-actions]

Claude finished @blove's task in 1m 53s —— View job

---

PR Review: feat(cli): blueprints — dawn add for served integration guides

• Gathered PR context
• Read current state of key files
• Checked prior review issues (commit 5fe6adb resolves 3 of 4 flagged items)
• Posted inline findings
• Posted summary

---

Summary

The latest commit (5fe6adb fix(cli): harden dawn add — validate names, guard catalog shape, fetch timeout) closes the two medium-severity issues from prior reviews and adds the corresponding tests. The code is in good shape.

Resolved since last review:

Severity	Issue	Status
Medium	Input validation on args.target — isValidName() guard + test	✅ Fixed
Medium	Array.isArray check in loadCatalog — full shape validation + test	✅ Fixed
Low	Fetch timeout — AbortSignal.timeout(15000) with descriptive errors	✅ Fixed
Low	Non-200/non-404 test case	✅ Fixed
Low	Non-array valid JSON catalog test case	✅ Fixed

Still open (low severity):

Location	Issue
add.ts:110	Third-party URL output is verbatim — frontmatter (if any) leaks into agent context
add-command.test.ts:113	DAWN_BLUEPRINTS_URL env var branch has no test coverage
add-command.test.ts:113	Malformed catalog JSON (JSON.parse catch at line 54–58) untested

The remaining issues are all low severity — the third-party frontmatter inconsistency is the most visible one. Everything else (web routes, blueprint content, catalog structure, loader logic) looks correct.