Document company relationship Context actions

SI
5d ago
+184-1

Summary

Documents two new Context actions, record_company_relationship and list_company_relationships, in api-reference/openapi/context.json. They are added as oneOf request variants with one example, and one sentence naming them is appended to the operation description.

The actions let an account record a relationship that a researched company holds toward its workspace, one of its artists or one of its organization professionals:

  • Relationship kinds are frontline_roster, catalog_interest, publishing, distribution, management, services and other, and each is current or former.
  • Frontline roster and catalog interest are separate rows.
  • Rows are never rewritten. When an artist leaves the roster, a former row names the current row it replaces through supersedes_id, and listed rows show superseded_by.
  • ended_on requires status: former, encoded with dependentSchemas.

Each variant states that a record is a workspace-private operator assertion. It grants no access, ownership, rights share or mandate and never confirms the company's identity. The actions stay out of delegated OAuth and return explicit gaps. The variants also state the scope limits: the relationship runs from the company toward the counterparty, and the counterparty must be reachable in the workspace now.

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

Merge sequencing

docs (this PR) ā†’ database recoupable/database#112 ā†’ api recoupable/api#1024. No app change, and no dependency on open PRs. Other open docs PRs append to the same oneOf array, and several also edit the operation description line (#359, #361, #362, #364, #365, #366, #367, #369, #370). A rebase conflict here only means keeping both edits.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))": the file parses.
  • git diff --numstat origin/main: 1 file, 184 insertions and 1 deletion. The deletion is the operation description line, which now ends with one more sentence. The variants listed are ingest, read, brief, save_brief, read_brief, record_company_relationship, list_company_relationships.
  • Review fix: the record variant no longer points readers to ingest_company_name, which this reference does not document. It now describes the company subject as the subjectIds[0] returned when a company name is saved.
  • Red ā†’ green: not applicable to docs. The contract was written before the database and API implementation.
  • Not verified: Mintlify render or preview (mintlify dev and broken-links were not run), including how Mintlify displays dependentSchemas; the hosted docs deployment; hosted API behaviour; live providers; and the production database.

Out of scope / known gaps

  • The operation summary ("Ingest, read, or compile context briefs") and the shared 200 response text are unchanged. Each new variant describes its own response.
  • The rule that ended_on must not precede started_on is stated in the description only, because JSON Schema cannot compare two dates.
  • No new MDX page or docs.json navigation change. The existing Context Engine page renders the POST operation.
  • The company-name ingestion action itself is not documented here.
  • Also not covered: company-to-company relationships outside a workspace anchor, the reverse relationship direction, rights interests, evidence links, and folding relationships into the company baseline read (api#981).

šŸ¤– Generated with Claude Code