feat(content): LLM-backed "Why this?" explainer for recommendations

[arberx]

Summary

Phase 1 of the LLM-augmented recommendation engine. The heuristic classifier still produces the structured recommendation; this layer adds an on-demand LLM rationale for each content recommendation card that explains why it surfaced and what to do about it — cached per (project, target_ref, prompt_version) so repeat clicks are free.

• New GET /content/recommendations/:targetRef/analysis (cache-only read) + POST .../analyze (cached or fresh LLM call, with provider / model / forceRefresh overrides).
• LLM wiring stays out of api-routes — the route accepts an injected ExplainContentRecommendationFn. Canonry wires the pi-ai implementation using the new analyze capability tier from feat(agent): LLM capability tiers — per-provider model selection per task #585, so each provider picks an appropriately cheap-but-capable model (Claude → sonnet-4-6, OpenAI → gpt-5-mini, Gemini → 2.5-flash, Zai → glm-5-turbo).
• Missing implementation → 503 PROVIDER_ERROR with operator-friendly message; unknown provider override → 400; configured-but-keyless override → 502.

Frontend "Why this?" UI ships in a follow-up PR (see roadmap below).

Architecture notes

api-routes (LLM-agnostic)
  └── ExplainContentRecommendationFn (injected)
          │
canonry (owns LLM wiring)
  └── createRecommendationExplainer({ config })
        ├── pickExplainProvider  → mirrors Aero's detectAgentProvider
        ├── resolveModelForCapability(provider, 'analyze')  ← PR #585
        └── pi-ai complete()  → dollars → millicents

Cache key is (projectId, targetRef, promptVersion). Bumping RECOMMENDATION_EXPLAIN_PROMPT_VERSION invalidates forward without touching the table.

Test plan

• pnpm -r typecheck — clean
• pnpm run lint — 0 errors (101 pre-existing warnings, none in new files)
• npx vitest run — 259 files, 3114 passed (+29 new tests covering route handlers + helper unit tests with mocked complete(): provider selection, override validation, cache hit/miss, forceRefresh overwrite, dollar→millicent conversion, empty-response guard, missing-explainer 503 path)
• SDK regen — GET/POST endpoints + DTOs flow through @ainyc/canonry-api-client

Roadmap (follow-ups)

• PR C: Frontend "Why this?" button on each content recommendation card → expandable panel calling the new endpoint, with provider dropdown for power users
• Phase 2: LLM page-coverage auto-dismiss (crawl candidate pages, classify if they already address the recommendation)
• Phase 3: Content brief generation as a separate action card

Builds on #585 (capability tiers).

🤖 Generated with Claude Code