feat(catalog): add Super Carl search tools and key provider

[mdale]

Add Super Carl to the tool catalog: six search tools and two free account-usage tools, authenticated with X-API-Key. Reuses the existing people, company, job, post, and account capabilities.

Contact: support@supercarl.ai

Please contact us there to arrange an independent test credential and live verification. We created a dedicated search-only review account with a 1,000-credit complimentary allowance; 993 credits remain after our self-tests. The credential is ready but has not been submitted to Treg. Please contact us with your preferred private delivery channel; no key is included in this PR.

Billing and shared-key support

• Public credit policy; authenticated machine-readable rate card: GET https://api.supercarl.ai/api/v1/credits.
• We offer Treg our existing enterprise usage-invoice rate of $0.099 per credit. Each completed search request/page costs one credit ($0.099). V2 people, company, and job searches return up to 25 rows per call; each additional page is another billable request. Post search supports up to 50 posts, and the joined post-to-people endpoint supports up to 100 matched people. The legacy people-preview documentation does not specify a numeric maximum; use a bounded page size. Completed empty searches still cost one credit. Account usage/status reads are free.
• The catalog uses per_success, unit: call, and expect: {json_path: success, equals: true}. Success means a completed API search. An HTTP-200 success:false clarification is free; a completed success:true empty search is still billable. This uses Treg's existing response-envelope settlement rule, with regression tests and no provider-specific runtime logic.
• Six search tools are platform-eligible. Both account tools are own_account metadata and platform-ineligible, so a shared key cannot expose Treg's balance/account identity.
• Adds the empty TREG_PLATFORM_KEY_SUPERCARL setting, web/worker deployment wiring, and the offered USD-per-credit rate. Treg's maintainers control provisioning/allow-list activation. There is no paid account, cash payment, invoice receipt, or agreed revenue-share arrangement to claim yet; the review grant is complimentary.
• Keep a shared Treg account free of personal networks/inboxes. Graph annotations are relative to the API-key owner, not automatically Treg's end user. Our isolated review account has no connected personal sources.

What agents can do with Super Carl

Super Carl connects professional profiles with career history, employer hiring activity, company data, indexed posts, and the account owner's available relationship graph. This listing exposes those signals as searchable criteria and cross-search pivots.

• Career patterns: filter people by average role tenure, current-role tenure, role, employer and experience. For example, find engineering leaders with at least two years in their current role. Tenure fields are optional where underlying history is unavailable.
• Hiring signals → people: find people working at companies hiring for a specified role, with posting-location and recency filters. For example, find relevant employees at employers advertising SRE roles. This does not identify the requisition owner or prove who was hired.
• Shared work history and profile intersections: find shared-employer cohorts around one or more people; multiple anchors intersect the cohorts, and an optional date-verified mode requires overlapping employment dates. Useful for finding potential reference contacts; employment overlap alone does not prove a personal relationship.
• Company → people: qualify companies by funding, technology or hiring criteria, then use the returned company search reference to find people within that company cohort.
• Posts and engagement → people: discover professional posts by topic, author, date or engagement, then return deduplicated people from matching posts/comments/reactions. These are observed activity signals; they do not establish purchase intent.
• Social proximity with BYOK: use the authenticated owner's/delegate's available network to prioritize people and see first/second-degree employer-network summaries on job results. A shared platform key does not inherit the end user's personal network.

The catalog publishes these as separate entry points, rather than requiring every request to begin as a people search:

Agent task	Catalog tool
Natural-language people search and social proximity	supercarl.people.search
Structured tenure, hiring and shared-work-history filters	supercarl.people.search.preview
Company search and company cohorts	supercarl.companies.search
Standalone job postings	supercarl.companies.jobs.search
Standalone professional posts/activity	supercarl.linkedin.search.posts
People discovered through posts/activity	supercarl.people.search.from_posts

These additional filter capabilities are documented in the public filter schema; the live ledger below verifies the bounded core requests, not every signal combination. Named contacts grouped with job postings (/jobs/with-people) and relationship-detail enrichment remain outside this initial catalog scope.

Self-verification ledger — 2026-09-09 UTC

All eight final catalog test_requests returned HTTP 200. Each search returned one real result and charged one credit. The meter is GET /api/v1/credits/status → remaining, measured immediately before/after each isolated call with no other account activity. These are vendor observations, not maintainer verification stamps.

Endpoint	HTTP / result	Test target	Observed credits	Catalog price	Matches?	Meter evidence
supercarl.people.search	200 / 1 person	Software engineers at Microsoft; limit 1; network ignored	1	1 credit/completed call	Yes	remaining 1000 → 999
supercarl.people.search.preview	200 / 1 person	Structured current Software Engineer filter; limit 1; network ignored	1	1 credit/completed call	Yes	remaining 995 → 994
supercarl.companies.search	200 / 1 company	Microsoft; preview mode; limit 1	1	1 credit/completed call	Yes	remaining 999 → 998
supercarl.companies.jobs.search	200 / 1 job	Software engineer jobs; limit 1	1	1 credit/completed call	Yes	remaining 994 → 993
supercarl.linkedin.search.posts	200 / 1 post	Microsoft; recent; limit 1	1	1 credit/completed call	Yes	remaining 998 → 997
supercarl.people.search.from_posts	200 / 1 person	Microsoft; post limit 1; people limit 1	1	1 credit/completed call	Yes	remaining 997 → 996
supercarl.account.usage	200 / usage and rate card	range=today	0	Free	Yes	remaining 996 → 996
supercarl.account.usage.status	200 / credit status	no parameters	0	Free	Yes	remaining 996 → 996

Additional observations:

• Company result_mode=detailed, Microsoft, limit 1: HTTP 200, one company, 1 credit, remaining 996 → 995. Both supported company modes were metered.
• Initial people-preview and job queries naming Microsoft returned HTTP 200 with success:false and entity-resolution choices; both charged 0 credits (999 → 999 and 998 → 998). The final test targets avoid that ambiguity. The expect rules ensure these free clarification envelopes do not settle at the one-credit estimate.
• Reconciliation: 6 catalog search hits + 1 detailed-company hit + 2 free account reads + 2 free clarifications = 7 credits, balance 1,000 → 993, during 04:13–04:18 UTC. Meter pre/post reads were also free.
• current_key_usage.credits_used rose only 0 → 4: company/job activity was absent from that counter. It is not a complete meter for these six search tools. The account balance and cumulative used counter reconciled all seven debits. Do not treat X-Carl-Credits-Used as a per-request charge.
• USD conversion is the vendor-offered $0.099 rate, not a claim that the complimentary account paid an invoice. Seven credits correspond to $0.693 at that offered rate.

Bogus-key verification, observed live 2026-09-09:

• Direct GET https://api.supercarl.ai/api/v1/credits/status: HTTP 401, exact body {"error":"Invalid API key"}.
• Isolated local Treg POST /connections/token against that real probe: HTTP 422, exact body {"detail":"Super Carl rejected that token (Invalid API key)"}. Follow-up GET /connections returned 200 []; no invalid credential was saved. The throwaway database/org was deleted and the local server stopped.

Validation

• uv run --frozen python scripts/catalog_validate.py: 95 provider files, 3,226 endpoints, 0 errors, 0 warnings after rebasing on upstream 8f1a71ba (2026-09-09).
• uv run --frozen python scripts/build_plugin.py --check: all five generated copies match.
• TZ=UTC uv run --with pytest-xdist pytest -n auto -q: 3,223 passed, 5 skipped (116.70 seconds) after the rebase. UTC matches service accounting; local-date tests otherwise straddle UTC midnight.
• uv run --frozen lint-imports: 14 contracts kept, 0 broken. The rebase preserves both provider additions in shared lists; Super Carl endpoint definitions, live targets, and settlement tests are unchanged. No additional live credits used.
• New settlement regression suite: 18 passed, covering all six search endpoints with free clarification, two-row hit, and paid empty-result responses through the real reservation/settlement ledger.
• Catalog/provider/settlement checks after the capability-copy and page-limit update: 184 passed. Local catalog search finds the tools for average tenure, shared work history, hiring, social proximity, job postings, and professional posts. No additional live credits were used.
• git diff --check: passed. Context fragments and generated source map updated.
• Public diff/PR checked for the actual review credential and private account identifiers: none present.

Full REST surface map

Source: https://supercarl.ai/docs/endpoints.json; 48 operations fetched 2026-09-09. The custom JSON schema is not OpenAPI, so source.openapi is null. Stable full schema: https://supercarl.ai/docs/schema.json. MCP tools are a separately documented transport at https://supercarl.ai/docs/mcp and are excluded from this REST catalog proposal. The overview also mentions /api/v1/network/summary; it is excluded as private graph readiness metadata and is absent from the focused endpoint schema.

Documented operation	Scope decision
GET /api/v1/credits	Catalogued
GET /api/v1/credits/status	Catalogued
GET /api/v1/contacts/reconciliation/schema	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/delegate-resolve	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/runs	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/runs/:runId/batches/preview	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/runs/:runId/batches	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
GET /api/v1/contacts/reconciliation/runs/:runId	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/runs/:runId/finalize	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
GET /api/v1/contacts/reconciliation/review	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/review/bulk	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
GET /api/v1/contacts/reconciliation/review/:entityId/candidates	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/review/:entityId/confirm	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v1/contacts/reconciliation/review/:entityId/:action	Excluded: contact import, reconciliation, or personal-contact workflow; outside search scope.
POST /api/v2/search/people/query	Catalogued
POST /api/v1/search/people	Excluded: legacy full-search/direct-lookup surface can enrich automatically; v2 rows and the preview tier cover initial search use cases.
POST /api/v1/communications/capabilities	Excluded: account-specific communications, message content, or send/cancel lifecycle.
POST /api/v1/communications	Excluded: account-specific communications, message content, or send/cancel lifecycle.
GET /api/v1/communications/:communicationId	Excluded: account-specific communications, message content, or send/cancel lifecycle.
POST /api/v1/communications/history	Excluded: account-specific communications, message content, or send/cancel lifecycle.
POST /api/v1/communications/:communicationId/cancel	Excluded: account-specific communications, message content, or send/cancel lifecycle.
GET /api/v1/communications/:communicationId/events	Excluded: account-specific communications, message content, or send/cancel lifecycle.
GET /api/v1/communications/:communicationId/stream	Excluded: account-specific communications, message content, or send/cancel lifecycle.
GET /api/v1/communications/:communicationId/artifacts/:filename	Excluded: account-specific communications, message content, or send/cancel lifecycle.
GET /api/v1/projects	Excluded: account-specific project, draft, or activation lifecycle.
GET /api/v1/projects/:projectId	Excluded: account-specific project, draft, or activation lifecycle.
GET /api/v1/projects/:projectId/targets	Excluded: account-specific project, draft, or activation lifecycle.
POST /api/v1/projects/:projectId/targets	Excluded: account-specific project, draft, or activation lifecycle.
DELETE /api/v1/projects/:projectId/targets	Excluded: account-specific project, draft, or activation lifecycle.
GET /api/v1/projects/:projectId/metrics	Excluded: account-specific project, draft, or activation lifecycle.
PATCH /api/v1/projects/:projectId	Excluded: account-specific project, draft, or activation lifecycle.
PUT /api/v1/projects/:projectId/templates	Excluded: account-specific project, draft, or activation lifecycle.
POST /api/v1/projects/:projectId/templates/generate	Excluded: account-specific project, draft, or activation lifecycle.
POST /api/v1/projects/:projectId/messages/generate	Excluded: account-specific project, draft, or activation lifecycle.
PUT /api/v1/projects/:projectId/target-users/:targetUserId/message	Excluded: account-specific project, draft, or activation lifecycle.
PUT /api/v1/projects/:projectId/targets/:targetId/message	Excluded: account-specific project, draft, or activation lifecycle.
GET /api/v1/projects/:projectId/send-readiness	Excluded: account-specific project, draft, or activation lifecycle.
POST /api/v1/projects/:projectId/activate	Excluded: account-specific project, draft, or activation lifecycle.
POST /api/v1/search/people/preview	Catalogued
POST /api/v1/search/people/enrich	Excluded: requires a prior full-search ID and enrich scope; separate provider/enrichment billing needs verification.
POST /api/v1/companies/search/preview	Catalogued
POST /api/v1/search/jobs/preview	Catalogued
POST /api/v1/search/jobs/with-people	Excluded: caller-specific network paths require the key owner's connected graph, which a shared Treg account must not imply.
POST /api/v1/search/posts/preview	Catalogued
POST /api/v1/search/posts/with-people	Catalogued
GET /api/v1/profiles/:id/chunks	Excluded: cached profile reads require an acquired person ID and additional scopes; avoid fixed private-person fixtures.
GET /api/v1/profiles/:id/text	Excluded: cached profile reads require an acquired person ID and additional scopes; avoid fixed private-person fixtures.
GET /api/v1/profiles/:id	Excluded: cached profile reads require an acquired person ID and additional scopes; avoid fixed private-person fixtures.

Curation and maintainer handoff

• Includes the preview tier without enrichment and free balance/rate-card preflight. Search previews cost one credit.
• Existing capabilities reused: people.search, companies.search, companies.jobs.search, linkedin.search.posts, account.usage. No taxonomy expansion.
• No messaging, contact mutation, billing administration, or background-job tool is included. The review key needs only the search scope.
• No endpoint verified: stamps, example responses, secret values, or private profile payloads are committed. Cost provenance records the observed debit; maintainers still need their independent run.
• No routed adapter is included. Joining treg.people.search needs separately verified response fixtures/adapter work. Any adapter must preserve paid empty-search semantics instead of treating a completed empty result as a free billing miss.
• Context fragments and source maps are updated alongside the listing. Front-door counts and generated plugin content remain the maintainer's finalization step per the vendor guide.