lib/docs/RESEARCH_COMPANY_CATALOG_CLIENT.md

# Research company catalog client

This slice synchronizes the full Research provider specification from PR #57
source commit `c3127f32872051b842c74ae7139b1c6ef71e2c53`, merged to Research `main`
as `cc7bf6191dc105969c804e123823186f1ea26cc3`. The pinned internal spec
SHA-256 is `1e5b34b5c7b4230cfd507995ab1f837aabc7b4dcdf61b114f37012167afdf224`;
the external copy differs only by Lib's conventional scheme, host, and base
path rewrite.

The generated CompanyProduct surface contains:

- shared list/detail through `GET /companyproducts`;
- safe tenant-attributed create through `POST /companyproducts`; and
- optimistic-concurrency update of unpublished Products through
  `PUT /companyproducts`; and
- no delete.

The generated CompanyService surface contains:

- shared list/detail through `GET /companyservices`;
- safe tenant-owned create through `POST /companyservices`;
- optimistic-concurrency update through `PUT /companyservices`; and
- no delete.

Every operation retains one compound security alternative containing both
`ApiKeyAuth` and `kvSessionCookie`. Callers supply one
`runtime.ClientAuthInfoWriter` that writes the native service credential and
forwards only the `kvSession` cookie. Credential values do not enter the
generated models, source, tests, or logs.

Published Product update remains intentionally proposal-only. The separate
generated proposal client records, submits, and independently reviews Product
changes; review does not itself apply or publish the authoritative Product.
Discovery reconciliation may update an unpublished Product, but legacy
governed-update candidates remain fail-closed and must be rerun rather than
silently converted. The Product PUT contract preserves immutable Account
binding, publication state, enrichment audit, and media ownership. This Lib
slice does not invent application, publication, bulk, media-ownership, or
delete operations.

## Dependency and release gate

This Lib PR may be reviewed while the Research Product-update change is open,
but it must not be released until:

1. Research merge `cc7bf6191dc105969c804e123823186f1ea26cc3` is
   released and deployed;
2. the KV Studio native service principal has the exact governed scopes
   `research:company-product:read`, `research:company-product:create`,
   `research:company-product:update`,
   `research:company-service:read`, `research:company-service:create`, and
   `research:company-service:update`;
3. Research production smoke tests prove the native catalog paths and zero
   Salesforce reads or writes; and
4. KV Studio is ready to pin the new Lib tag, preserve the Product proposal
   workflow for governed and published changes, and run its Playwright
   list/detail/create/Product-edit/Service-edit coverage.

There is no database migration in this client slice. Research remains
responsible for proving ownership through the existing
`research.companyproduct`, `research.companyservice`, and
`crm.account.tenantid` contracts. Any future schema change must use the
governed database runner and its own recovery plan.

This slice grants no scope, changes no credential, creates no Lib release, and
performs no deployment.