README

1. Step 1 detects the project’s stack + dependencies.
2. The recommender heuristics infer an application profile (best guess from frameworks + dep signals).
3. The matching playbook(s) are included in the recommender’s context.
4. Recommendations are shaped: ordering tilts toward the profile’s priority list; phrasing nods to profile-specific concerns.

Profile detection (best-effort heuristics)

ai-application is checked first — AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set (provider failover, sandbox reuse, OIDC keyless) belong to this profile.

When detection is uncertain, no playbook is applied. The recommender works fine without one — the playbook is a tilt, not a requirement.

Playbook schema

Each playbook is a Markdown file with a fixed shape so the recommender can parse it reliably. Required sections:

Contributing a new playbook

1. Identify a clear application profile and one or two representative project profiles that exemplify it.
2. Create references/playbooks/<profile>.md matching the schema.
3. Add detection signals to the table above (the heuristics live in the recommender code; document them here).
4. Update the playbook selection matrix in references/scoring.md.
5. Run node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs. No tests directly cover playbooks (they’re content), but the schema validator runs in CI.