feat(api): author feature-explanation markdown bundle (#84)

[thomasluizon]

Summary

Authors eight grounded markdown explainer files so the in-app AI can answer how Orbit features work with concrete, code-accurate content instead of guesses:

• streaks.md, frequencies.md, gamification.md, paygate.md, schedule-math.md, freezes.md, notifications.md, ai-memory.md

Each file carries a 6-key YAML frontmatter (key, display_name, related_capabilities, related_surfaces, version, derived_from) and a body whose numbers are copied verbatim from the backend source of truth (AppConstants, LevelDefinitions, and the streak / schedule / paygate / reminder services). All related_capabilities and related_surfaces ids are drawn from the real agent catalog (AgentCapabilityIds / AgentCatalogService.BuildSurfaces).

The bundle ships inside the API binary via the repo's first <EmbeddedResource> glob in Orbit.Application.csproj. Resources embed as:

Orbit.Application.Chat.Content.FeatureExplanations.<key>.md

This manifest prefix is the documented loader contract for the downstream consumer (#90).

Pure content: no .cs behavior changes (one csproj glob + the markdown bundle).

Tests

Adds FeatureExplanationResourceTests (xUnit) which locks the embedding contract: exactly the 8 expected resources are present with the documented manifest names, and each stream loads with a frontmatter key matching its filename stem.

Validation

• dotnet build src/Orbit.Application/Orbit.Application.csproj -c Release — succeeds, 0 warnings.
• dotnet build Orbit.slnx -c Release — succeeds, 0 errors (pre-existing warnings only).
• dotnet test (FeatureExplanationResourceTests) — 9 passed, 0 failed.
• Reflection check confirms exactly 8 embedded resources with the documented prefix.

Refs thomasluizon/orbit-ui-mobile#84

[claude]

Solid content PR. Eight grounded markdown explainer files ship as embedded resources with a clean glob in Orbit.Application.csproj, and the xUnit contract tests lock both the manifest naming scheme and frontmatter key convention. Spot-checked all numeric constants against AppConstants (MaxUserFacts=50, habit cap=10, AI messages 20/500, streak-freeze limits, overdue window=7, lookback=365), XP formula (10+streak / +100 goal) against GamificationService, and level table against LevelDefinitions — every value is verbatim accurate. No behaviour changes, no auth/API surface touched, tests are well-structured and appropriate for an embedding contract.

[claude]

The first commit (approved) is solid — eight grounded explainer files with accurate constants, clean embedding glob, and a tight xUnit contract test.

The second commit introduces one correctness bug in freezes.md: it describes freezes as automatic with nothing to tap, but freeze activation is fully explicit in the backend (POST /api/Gamification/streak/freeze → ActivateStreakFreezeCommand). UserStreakService reads existing freeze records but never creates them, and there is no background job that auto-applies a freeze when a day is missed. The AI will tell Pro users their streaks are protected automatically; users who don't open the AI chat after a missed day will find their streak broken and the explanation wrong.

See the inline comment on line 24 of freezes.md for a concrete replacement and a note about the follow-on sentence on line 26.

[claude]

The prior REQUEST_CHANGES finding (auto-activation of streak freezes) is still unresolved. The third commit repointed derived_from to StreakFreezeAutoActivationService.cs ProcessUserAsync, but this file does not exist in the repo — the only freeze-activation code is the explicit ActivateStreakFreezeCommand behind POST /api/Gamification/streak/freeze. The body text of freezes.md lines 24–26 still describes freezes as fully automatic, which is incorrect given the current backend. Please either (a) revert the body to describe explicit activation, or (b) land the auto-activation service before merging this doc.

[thomasluizon]

Rebased onto issue-108 and retargeted the base from main to issue-108.

Why: the claude[bot] CHANGES_REQUESTED finding was correct. freezes.md documents the auto-activation model (derived_from: StreakFreezeAutoActivationService.cs ProcessUserAsync, body: "Freezes are automatic, there is nothing to tap"), but on this branch old base that service did not exist yet and the manual ActivateStreakFreezeCommand was still present, so the doc was inaccurate for that base.

Stacking on #108 fixes it at the root rather than rewording the doc:

• src/Orbit.Infrastructure/Services/StreakFreezeAutoActivationService.cs is now present (added by chore: remove missions and tours dead code #108).
• ActivateStreakFreezeCommand.cs plus its validator/handler are removed by chore: remove missions and tours dead code #108.
• freezes.md body and derived_from are now accurate against the branch.

Rebase was conflict-free (disjoint file sets: #84 adds markdown plus an embed test; #108 adds the service / removes the manual command). Validated: dotnet build clean (0 errors), FeatureExplanationResourceTests green (9/9).

Merge order: #108 (issue-108, PR #179) first, then this PR.

[claude]

The prior CHANGES_REQUESTED finding (auto-activation service missing) is fully resolved: StreakFreezeAutoActivationService.cs is present on the rebased branch, ActivateStreakFreezeCommand is gone, and freezes.md's body and derived_from are accurate. Eight grounded explainer files embed cleanly via the csproj glob, all numeric constants (habit cap, AI message limits, freeze limits, overdue window, streak lookback, XP formula, level thresholds) match the backend source of truth, and the xUnit embedding contract tests (9/9) lock both manifest naming and frontmatter key convention. Solid content PR — approved.