Document company_onboarding brief purpose in Context reference

Draft
SI
5d ago
+10-6

Superseded by recoupable/docs#360 — marked draft; do not merge both. docs#360 (ticket #2130, "Document company_onboarding briefs and evidence freshness") makes the same purpose enum change in the same hunks, adds a purpose description, the assessment_scope/next_steps response text and a company_onboarding example, and is the more complete PR. recoupable/docs#358 (draft, ticket #2118) also adds the enum value. The three conflict with each other (git merge-tree), so only one can land unchanged. Recommendation: merge docs#360 and close this PR unmerged. Kept open as a draft only so a reviewer can compare the wording; the one caveat this PR states that docs#360 does not ("missing topics are review prompts, not proof that evidence does not exist") can be carried over there if wanted.

Summary

Brings the public Context reference in line with shipped behavior for the company_onboarding brief purpose, which merged and went live via database#96 → api#992 → app#2178 but is still missing from api-reference/openapi/context.json on docs main. Adds company_onboarding to the purpose enum of the brief and save_brief request branches, documents what that purpose adds to the response (assessment_scope: "selected_saved_context_requests" and per-request next_steps with review_assessment_coverage / review_available_evidence), states that missing topics are coverage prompts rather than proof evidence does not exist and that submitted names/metadata do not establish rights or ownership, and notes that only saving (save_brief) needs migration 20261010010000_context_company_assessment.sql; the read-only brief action compiles the purpose in api code. This advances #2134's Done-when item "Public docs and MCP match shipped behavior". The MCP input schema is shared with the API Zod schema, but the human-readable MCP tool descriptions (context, compile_music_context_brief, save_music_context_brief) also still name only creative direction and playlist pitch, so the docs are not the only surface that lags (documented in the api runbook, recoupable/api#1012, section 2.2). Additive, anchored JSON edits only: no path, example or existing enum value removed; no new MDX page; no docs.json change.

Refs recoupable/app#2134 (child of epic recoupable/app#2116).

Merge sequencing

docs → database → api → app. Superseded by recoupable/docs#360 (see the note above). No code dependency: the behavior described is already merged and released (database#96, api#992, app#2178). Sibling PR for this ticket: recoupable/api#1012 (release runbook + guard test), which does not depend on this PR and references docs#360 as the preferred docs change. No database or app PR for this ticket.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" — parses.
  • Ran: assertion script — brief and save_brief purpose enums both contain company_onboarding; the brief purpose description no longer claims the migration is required; the save_brief purpose description does; the 200 response description contains assessment_scope — ok.
  • Ran: additive check against origin/main — all previous paths and every previous enum value retained (10 insertions, 6 deletions; the deletions are the replaced description strings and the two enum closers, each replaced by a superset).
  • Ran: git merge-tree against the docs#358 and docs#360 branches — both conflict with this PR (same hunks).
  • Red → green: not applicable (documentation-only change; the matching api guard test lives in recoupable/api#1012).
  • Not verified: hosted deployment (docs.recoupable.dev render of the updated enum/description), live providers, production database. No deployment, migration or provider call was performed.

Out of scope / known gaps

  • The remaining shared actions (plan, read_execution, release-case and release-track actions, name/brief/text intake) are still documented only in api/lib/context/README.md and the MCP tool schema.
  • MCP tool description lag (see Summary) is not fixed here.
  • Cost reconciliation (#2123/#2105), Sites quality (#2094/#2133), the live pilot and broad release remain gated and untouched.

🤖 Generated with Claude Code