gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md

@@ -0,0 +1,331 @@
+# Connector reference
+
+Per-connector authoring guidance. Revalidate vendor sources and sandbox availability
+before implementation; target labels below are goals, not measured SDK fidelity.
+The previously referenced `connector-fidelity-scope.md` is absent from this checkout.
+Keep pinned sources with each authored template rather than relying on that missing plan.
+
+## Contents
+
+- [Shape, model sources, and surfaces](#shape-model-sources-and-surfaces)
+- [Sandboxes and what they can seed](#sandboxes-and-what-they-can-seed)
+- [Type-mapping notes](#type-mapping-notes)
+- [Status of templates in the SDK](#status-of-templates-in-the-sdk)
+- [Source dossiers and sim strategy](#source-dossiers-and-sim-strategy)
+- [How to use a dossier](#how-to-use-a-dossier)
+
+## Shape, model sources, and surfaces
+
+| Connector | Shape | Model source (importer kind) | Tenant channel (describe) | MCP surface today (optional) | Target label |
+| --- | --- | --- | --- | --- | --- |
+| Slack | base | official Slack docs; pinned emulator as secondary inventory (`docs`) | none | [native structured capture and hosted world tools](../../../documentation/integrations/gateway-tool-access.md), no native live MCP catalog | synthetic for fixtures; subset for captured worlds until measured replay |
+| GitHub | base | `github/rest-api-description` OpenAPI (`openapi`); GraphQL introspection | none | Merge connector; GitHub's official MCP server as a remote mirror | mimic |
+| Salesforce | tenant-shaped | standard objects from `sobjects/describe` as a skeleton (`describe`) | same describe per org: **required** at bind | Merge connector; native passthrough for describe and SOQL | mimic per tenant |
+| Google Workspace | mixed | discovery document `admin.googleapis.com/$discovery/rest?version=directory_v1` (`discovery`) | custom user schemas `customer/{id}/schemas` (optional) | Merge brokers Drive and Calendar | mimic |
+| Okta | mixed | `okta-management-openapi-spec` (`openapi`) | user and group schema API `/api/v1/meta/schemas/user/default` (optional) | none yet; native provider if a live surface is wanted | mimic |
+| Microsoft 365 / Entra ID | mixed | Graph `$metadata` OData CSDL (`odata-csdl`) | directory, schema, open extensions (optional) | none yet | mimic directory; subset licensed workloads |
+| Microsoft Teams | base | authored Graph v1.0 collaboration subset (`docs`, CSDL) | none | none | provisional `subset`; synthetic fixtures, live checks skipped |
+| LDAP / Active Directory | mixed | RFC 4512 subschema; AD `cn=Schema,cn=Configuration` (`ldap-subschema`) | same subschema per directory (optional) | none; non-HTTP provider only if a live surface is wanted | mimic |
+| Jamf Pro | mixed | per-instance OpenAPI at `https://<instance>/api/schema`; Classic API (`openapi`) | extension attributes; per-instance spec (optional) | none yet | mimic records; subset live inventory |
+| Kandji (Iru) | base | docs and Postman collection; community OpenAPI 3.1 conversion; vendor OpenAPI unconfirmed (`docs`) | none | none yet | subset |
+| Apple Business Manager | base | Apple DocC JSON, API 2.4 (`docs`); no downloadable OAS | none | none | subset |
+| Workday | tenant-shaped | public WSDL/XSD per service as a skeleton (`wsdl-xsd`) | tenant WSDL: **required** at bind | check the Merge catalog cache (HRIS) | subset until a tenant exists, then mimic |
+| NetSuite | tenant-shaped | REST `metadata-catalog` in OpenAPI 3.0 and JSON Schema per record type (`describe`) | same catalog per account: **required** at bind | check the Merge catalog cache (accounting) | mimic per tenant |
+
+## Sandboxes and what they can seed
+
+| Connector | Sandbox we can own | Seedable through the write API | Only from the real world |
+| --- | --- | --- | --- |
+| Slack | free workspace | channels, users (invites), messages, files | nothing |
+| GitHub | free test organization plus the Gateway GitHub App | repos, issues, PRs, reviews, check runs | nothing |
+| Salesforce | Developer Edition org; scratch orgs via Dev Hub | any sObject; SOQL reads | nothing |
+| Google Workspace | dedicated test domain (small paid seats) or trial | users, groups, org units, custom schemas, Drive and Calendar content | Chrome and mobile devices |
+| Okta | free developer / integrator org | users, groups, memberships, apps, assignments | system log (generated by seeding) |
+| Microsoft 365 / Entra ID | Entra ID free tenant always; E5 developer sandbox only for eligible accounts (Visual Studio Pro or Enterprise) | users, groups, service principals, directory extensions | licensed workloads without the E5 sandbox |
+| Microsoft Teams | no sandbox used for this schema milestone | not exercised; fixtures are synthetic and loaded through the SDK store | live response fidelity remains unvalidated |
+| LDAP / Active Directory | Docker OpenLDAP or Samba AD DC | everything | nothing |
+| Jamf Pro | Jamf developer sandbox or trial instance | computers and mobile devices via Classic API, groups, policies, extension attributes | inventory detail from a live agent |
+| Kandji (Iru) | sandbox via the account team (docs mention one) | blueprints, library items, users, tags | devices |
+| Apple Business Manager | our own ABM org with Apple devices; no developer sandbox | writes exist since API 2.0, but land in production, so we do not seed | devices, MDM assignments |
+| Workday | commercial or partner tenant only; no public sandbox | workers, positions, organizations once a tenant exists | nothing in principle |
+| NetSuite | partner developer account (SuiteCloud Developer Network); customer sandboxes are paid add-ons | any record the role permits; SuiteQL reads | nothing |
+
+For Jamf, Kandji and ABM, one enrolled test Mac gives the device entities at least one
+real row; captured exports from that tenant become the goldens.
+
+## Type-mapping notes
+
+- Temporal values: vendor `date-time` maps to strict RFC 3339 `format: date-time`; exact calendar dates map to `format: date`; vendor date-times that allow a space separator use `vendor-date-time`. Use `time` only when seconds and an explicit timezone are required.
+- Slack message `ts` remains an exact string; Unix seconds use integers and conversation `updated` uses milliseconds. See the [model guide](../../../gatewaysdk/sdk/src/gatewaysdk/environment/schema/connectors/slack/MODEL.md) for workspace identity and normalization.
+- Regex patterns are unsupported in the current payload and tool-contract dialect. Record the lost constraint and any future mapper obligation explicitly; do not add unsupported keywords.
+- Polymorphic lookups (Salesforce `WhoId`, `WhatId`) are nullable strings without a relationship; note them in the scope file.
+- Vendor enums (picklists, Graph enum types, Okta statuses) become `enum`; tenant-added picklist values arrive through the overlay.
+- Composite keys are declared in order (`repo_id`, `number` for GitHub issues; `calendar_id`, `id` for events).
+- Reserved prefixes (`_`, `sqlite_`, `gateway_`, `benchmark_`) and the `payload` property name cannot appear in entity or field names; prefix entities with the connector (`okta_users`, `sf_accounts`).
+
+## Status of templates in the SDK
+
+| Slug | State | Notes |
+| --- | --- | --- |
+| slack | package 2.1.1 / domain 2.0.0 / mapping 1 | 34 entities, 27 tools; empty init or populated synthetic/selected capture → immutable hosted world; [on-demand fixtures](../../../samples/schema-worlds/README.md#slack-fixtures) |
+| github | spec-derived, wave 1 | base; pinned GitHub REST OpenAPI plus the GraphQL review-state declaration. 8 entities / 1,662 recursive fields / 4 tools. Vendor nesting is retained, including pull-request and review `_links`; route containment and selected relationship projections remain direct fields where the vendor payload does not carry route context. Issue state/state-reason come from declared REST sibling value blocks; review state comes from `PullRequestReviewState`; merged user `type` stays open because not every read form closes it. `subset` until a test-org round trip and synthetic goldens exist. |
+| salesforce | docs-derived, wave 1 (re-import) | tenant-shaped skeleton from seven pinned Winter '27 Object Reference pages: 7 entities / 656 recursive fields / 4 tools. **Describe-on-bind is required** for the org's actual fields, relationships, picklists, custom schema, and permissions. Compound addresses retain vendor nesting; exact dates use `format: date`; sparse `sf_users.Username` uniqueness is enforced without requiring the field on every SOQL projection. Only explicit vendor value blocks become enums; org-controlled picklists remain open strings. Polymorphic `WhoId`/`WhatId` remain unenforced. `subset`: no Developer Edition/scratch-org round trip or goldens. |
+| google-drive, google-calendar | hand-authored (#219) | mixed; re-import from the discovery documents in wave 2 |
+| linear, jira | hand-authored (#219) | base; not in the eleven, kept as samples |
+| microsoft-teams | authored schema-only base | [Usage, artifacts, scope, and pinned evidence](../../../documentation/features/microsoft-teams-schema.md); no tools or live integration |
+| custom | hand-authored (#219) | the blank starting point for any arbitrary connector |
+| workday | hand-authored, wave 3 | tenant-shaped skeleton from pinned public WWS v46.2 WSDL/XSD files for Human Resources, Staffing, Absence Management, and Compensation: 7 entities / 289 recursive fields / 3 tools. **Describe-on-bind is required** for an actual tenant. Workday-namespaced `wd:enumeration` blocks are used only where the selected reference-ID types declare them; tenant business values remain open. `xsd:date` maps to `format: date`; `xsd:time` remains unformatted because the source permits a missing timezone. Nested references remain vendor-shaped; references ending in typed ID arrays or repeated sections are not falsely narrowed to one foreign key. `subset`: no tenant round trip or goldens. |
+| kandji | hand-authored, wave 3 | base; transcribed from the pinned vendor Postman collection rendered by api-docs.iru.com, with the community OpenAPI used only as a cross-check. 8 entities / 85 recursive fields / 3 tools. Device `user` stays as the vendor's nested object-or-empty-string shape; `/user/id` is enforced when assigned and the empty-string sentinel is treated as absent. Blueprint type and library-item status use vendor-declared value blocks; platform values are example-derived and completeness remains unverified. Apple-family app shape only; Windows/Android forms need a polymorphic-key model. `subset`: no account-team sandbox, tenant round trip, or goldens. |
+| jamf | docs-derived, wave 3 | mixed; authored from pinned Jamf Pro 11.31.0 and Classic API 11.28.0 reference pages because no per-instance `/api/schema` was available. 8 entities / 373 recursive fields / 4 tools. Computer inventory retains optional whole `general`/`hardware`/`operatingSystem`/`userAndLocation` sections; policies and profiles preserve nested scope. `ComputerGeneral.initialEntryDate` retains `format: date`. Nested serial-number uniqueness is technically expressible but is not asserted because the pinned OpenAPI does not declare it. Extension-attribute definitions are base schema; collected values remain tenant data. `subset` until a sandbox round trip and goldens exist. |
+| apple-business-manager | docs-derived, wave 3 | base; authored from 96 pinned Apple Business API 2.4 DocC JSON documents. 18 entities / 159 recursive fields / 2 read tools spanning organization devices, AppleCare, MDM device summaries/details, servers and assignments, activities, users, groups, organizational units, blueprints, configurations, and linkage tables. Vendor `attributes` nesting is preserved; nested `enrolledUserId` and user-group `ouId` relationships are enforced, while `roleOuList[].ouId` remains unenforced because it traverses an array. Enums come only from DocC `possibleValues`/`allowedValues`. No write tools are shipped: Apple has no sandbox and writes affect production. `subset`: no tenant round trip or goldens. |
+| netsuite | docs-derived, wave 3 | tenant-shaped skeleton from the exact archived 2023.2 REST API Browser plus supporting Oracle metadata/error docs: 9 entities / 5,259 recursive fields / 3 tools. **Describe-on-bind is required** for role/account-specific records, custom fields, lists, segments, enums, and nullability. Record references and local sublists/subrecords preserve vendor nesting; customer, vendor, and journal-entry `/subsidiary/id` relationships are enforced. Polymorphic references and collection-item paths remain unenforced. Sixty declared date fields use `format: date`; date-times retain `date-time`. No uniqueness is inferred from business prose when the pinned schema does not declare it. `suiteql` is not shipped because the world store has no query surface. `subset`: no account metadata overlay, round trip, or goldens. |
+| spycloud | brief only, wave 5 | base; public per-operation OpenAPI 3.1 at docs.spycloud.com (45 operations confirmed: 20 Investigations, 18 Enterprise, 3 SIP, 3 IDLink, 1 NIST); `x-api-key`; `{cursor, hits, results}` envelope at 1,000/page. Per-key allow-lists, masking and hashing are world config, not an overlay. Starts at `subset`; TRM's captures raise the agent's selectors to `mimic`. |
+| constella | brief only, wave 5 | base; API reference is MNDA-gated, no OpenAPI/SDK public. 14 selector searches named via the vendor's Maltego transform catalog, 0 method/path pairs. Cannot be mocked faithfully without TRM's transport, envelopes and error bodies. |
+| cloudburst | brief only, wave 5 | base; Cloudburst Technologies (`cloudburst.info`). 2 agent-facing operations confirmed from vendor screenshots plus the signal object shape; `GET /api/schema/?format=json` is a credential-gated OpenAPI document, so one authenticated fetch with TRM's key turns this into a real `openapi` import. Vendor timestamps carry no zone offset. |
+| torchlight | dropped | name is ambiguous (Torchlight AI is a defence geospatial platform with no public API; the functional fit is Searchlight Cyber). Parked until TRM confirms the vendor. |
+| okta, microsoft-entra, ldap | none | created through this checklist in waves 2 and 3 |
+
+Slack retains optional join/leave, pins, bookmarks, user groups and presence.
+Scenario grading uses bounded set comparisons; paginated reads assemble selected
+rows with per-call association maps. Capability defaults expand into complete
+published entries and own capture classifications. Exact template/lock pins
+remain required: prior versions retain their bytes and cannot silently refresh
+under the new package. The [scale regressions](../../../gatewaysdk/sdk/tests/environment/test_schema_slack_scale.py)
+exercise synthetic materialization and read/grading behavior, not live replay.
+
+## Source verification
+
+SDK template and native Slack guidance revalidated 2026-09-07 while integrating
+`ba89fe16` with `015d6b25`. Inspected
+`gatewaysdk/sdk/src/gatewaysdk/environment/schema/{scaffold.py,slack.py,_slack_fidelity.py,connectors/}`,
+`gatewaysdk/sdk/tests/environment/test_schema_{scaffold,slack_scale}.py`, and
+`gateway/packages/shared/src/server/services/NativeSlackService.ts`.
+Other vendor rows are guidance to revalidate, not newly tested integrations.
+
+## Source dossiers and sim strategy
+
+One block per connector: where the truth lives, what we can read from the connector itself,
+which event schemas exist (change events are the cheapest fidelity signal), the error
+format the world must reproduce, the sandbox, and the recommended way to build the
+high-fidelity sim. Verified 2026-09-06; "verify" marks a claim to confirm before relying on it.
+Pin every spec by URL and SHA-256 in `provenance.json`.
+
+### Slack (base)
+
+- Docs: https://api.slack.com/methods and https://api.slack.com/docs
+- Machine-readable: `slackapi/slack-api-specs` (archived 2024-03, read-only): Web API as OpenAPI 2.0 `web-api/slack_web_openapi_v2.json`, Events API as AsyncAPI `events-api/`. Treat as a frozen baseline; newer methods come from the docs.
+- Introspection: none. Slack has no per-workspace schema.
+- Events: the AsyncAPI catalog of event payloads (`message`, `member_joined_channel`, `file_shared`).
+- Errors: `{"ok": false, "error": "not_in_channel"}` with a string code per method.
+- Sandbox: a free workspace; seed channels, users, messages, files through the Web API.
+- Sim: import the OpenAPI response objects (`objs_channel`, `objs_user`, `objs_message`, `objs_file`) as entities; keep `ts` as the message key; model `ok`/`error` responses on every tool; goldens from the native provider's captures. Slack's own AsyncAPI event shapes double as ingestion fixtures.
+
+### GitHub (base)
+
+- Docs: https://docs.github.com/en/rest and https://docs.github.com/en/graphql
+- Machine-readable: `github/rest-api-description` (`descriptions/api.github.com/api.github.com.json`, OpenAPI 3.0; `descriptions-next` for 3.1), refreshed continuously; GraphQL public schema via `octokit/graphql-schema` or introspection; webhook payload JSON Schemas via `@octokit/webhooks-schemas` (`schema.json`, daily updated) with example payloads in `@octokit/webhooks-examples`.
+- **Enum values are not in the REST description** (corrected 2026-09-06): issue `state` and user `type` are enumerated only on the `webhooks_issue` / `webhooks_user` schemas in the same document, and review `state` only in the GraphQL `PullRequestReviewState`. Take them from those siblings and record which one.
+- Introspection: GraphQL `__schema` on `api.github.com/graphql`. No per-tenant schema.
+- Events: webhook schemas above cover every entity change; use them as the change-event shape and as ingestion fixtures.
+- Errors: `{"message": ..., "errors": [{"resource", "field", "code"}], "documentation_url"}`; 422 for validation.
+- Sandbox: a free test organization plus the Gateway GitHub App.
+- Sim: import component schemas `repository`, `issue`, `pull-request`, `pull-request-review`, `check-run`, `commit`, `simple-user`, `label` from the REST description; composite keys `(repo_id, number)`; error shape from the docs; goldens from the test org through the app. The webhook example payloads seed `data/records.json` without inventing anything.
+
+### Okta (mixed)
+
+- Docs: https://developer.okta.com/docs/reference/
+- Machine-readable: `okta/okta-management-openapi-spec` (`dist/spec.json`, also npm `@okta/openapi`); the vendor states it is generated from the Management API.
+- Introspection: User schema `GET /api/v1/meta/schemas/user/default` and app user schemas, group schema; these carry the org's custom attributes and are the overlay source. System Log event types catalog at https://developer.okta.com/docs/reference/api/event-types/.
+- Events: Event Hooks deliver `LogEvent` objects (same shape as the System Log API); event-hook-eligible types are a subset of the catalog.
+- Errors: `{"errorCode": "E0000001", "errorSummary": ..., "errorCauses": [...]}`.
+- Sandbox: free developer / integrator org; seed users, groups, memberships, apps, assignments by API. System Log fills itself.
+- Sim: import `User`, `Group`, `Application`, `AppUser`/assignment, `LogEvent` from the OpenAPI; overlay from the schema API; model `errorCode` responses; goldens from the developer org. The System Log is the natural "events" entity and a strong replay source.
+
+### Google Workspace (mixed)
+
+- Docs: https://developers.google.com/workspace/admin/directory/reference/rest, Reports API under the Admin SDK, Drive https://developers.google.com/workspace/drive/api/reference/rest/v3, Calendar v3 reference.
+- Machine-readable: discovery documents, `https://www.googleapis.com/discovery/v1/apis/{api}/{version}/rest` (`admin/directory_v1`, `admin/reports_v1`, `drive/v3`, `calendar/v3`); list all at `https://discovery.googleapis.com/discovery/v1/apis`.
+- Introspection: custom user schemas `GET customer/{customerId}/schemas` (overlay source). Drive and Calendar have no per-tenant schema.
+- Events: Admin SDK Reports API activity events (admin, login, drive, calendar applications) give change records; Drive `changes` and push notifications; Calendar push notifications.
+- Errors: `{"error": {"code": 404, "message": ..., "errors": [{"domain", "reason", "message"}]}}`.
+- Sandbox: a dedicated test domain (small paid seats) or a trial; seed users, groups, org units, custom schemas, Drive and Calendar content.
+- Sim: import `schemas` from each discovery document (`User`, `Group`, `Member`, `OrgUnit`, `Role`, `File`, `Permission`, `Revision`, `Event`, `CalendarListEntry`); overlay from custom schemas; error envelope from the docs; Reports API activity records as the events entity and as replay fixtures.
+
+### Microsoft 365 / Entra ID (mixed)
+
+- Docs: https://learn.microsoft.com/en-us/graph/api/overview
+- Machine-readable: Graph `$metadata` (OData CSDL) live at `https://graph.microsoft.com/v1.0/$metadata`; the same, plus a client-optimized OpenAPI 3.0, in `microsoftgraph/msgraph-metadata` (`openapi/v1.0/openapi.yaml`, `clean_v10_metadata/`).
+- Introspection: directory extensions (`extensionProperties` on applications), schema extensions (`/schemaExtensions`), open extensions on objects; tenant-defined attribute sets and custom security attributes. Overlay source.
+- Events: change notifications (`changeNotification` with `resourceData`, `changeType` created/updated/deleted); `directoryAudit` and `signIn` under `/auditLogs`.
+- Errors: `{"error": {"code": "Request_ResourceNotFound", "message": ..., "innerError": {...}}}`.
+- Sandbox: Entra ID free tenant (directory objects); the E5 developer sandbox only for eligible accounts.
+- Sim: import `user`, `group`, `directoryObject` membership, `servicePrincipal`, `application`, `directoryRole`, `signIn`, `directoryAudit` from CSDL; navigation properties become relationships; overlay from extension properties; error envelope from the docs; audit and sign-in logs as the events entities. Scope the CSDL hard; it is hundreds of types.
+
+### LDAP / Active Directory (mixed)
+
+- Docs: RFC 4511 (protocol), RFC 4512 (directory information models, subschema), RFC 4519 (standard attribute types); AD schema reference https://learn.microsoft.com/en-us/windows/win32/adschema/active-directory-schema and the [MS-ADTS] schema section.
+- Machine-readable: the subschema subentry read over LDAP (`subschemaSubentry` attribute of the root DSE, then `attributeTypes` and `objectClasses`); AD's schema partition `CN=Schema,CN=Configuration,<forest>` with `classSchema` and `attributeSchema` objects.
+- Introspection: the same read against the target directory is the overlay source (AD schema extensions, custom object classes).
+- Events: none over LDAP; AD exposes changes through `uSNChanged`, DirSync control, or Windows event logs. Model `uSNChanged` and `whenChanged` on entries.
+- Errors: LDAP result codes (`noSuchObject` 32, `constraintViolation` 19, `entryAlreadyExists` 68, `objectClassViolation` 65).
+- Sandbox: Docker OpenLDAP (`inetOrgPerson`, `groupOfNames`, `posixAccount`) and Samba AD DC (`user`, `group`, `computer`, `organizationalUnit`). Fully offline.
+- Sim: import object classes for the scope from the subschema (MUST → required, MAY → optional, syntax OID → type); DN is the key, `objectClass` a required array, membership as `member`/`memberOf` join entities; result codes as the error table. Two templates or one with a directory flavor: OpenLDAP vs AD attribute names differ (`cn`/`uid` vs `sAMAccountName`, `userAccountControl`).
+
+### Jamf Pro (mixed)
+
+- Docs: https://developer.jamf.com/jamf-pro/reference/jamf-pro-api and the Classic API reference; `https://developer.jamf.com/jamf-pro/llms.txt` indexes every page and endpoint, and any docs page serves Markdown with `.md` appended.
+- Machine-readable: per-instance OpenAPI 3 at `https://<instance>.jamfcloud.com/api/schema`; Classic API is XML/JSON without a *whole-API* spec. Confirmed 2026-09-05: every `reference/<page>.md` on developer.jamf.com — Classic API pages included — embeds a complete OpenAPI 3.0.1 fragment for that one endpoint, with its `components.schemas` and its documented error responses. That is what the `jamf` template was built from, so an author needs no instance to get real schemas; the pages label themselves Jamf Pro API 11.31.0 and Classic API 11.28.0. Page slugs are not guessable (policies are `findpoliciesbyid`, not `findpolicybyid`) — take them from the section `llms.txt`.
+- Introspection: the per-instance spec plus extension attributes (`/api/v1/computer-extension-attributes`, mobile device equivalents). Overlay source.
+- Events: webhooks with documented payloads per event (`ComputerAdded`, `ComputerInventoryCompleted`, `MobileDeviceEnrolled`, `PushSent`, ...) at https://developer.jamf.com/jamf-pro/docs/webhooks-1.
+- Errors: Jamf Pro API `{"httpStatus": 404, "errors": [{"code", "description", "id", "field"}]}`; Classic API returns HTML/XML status bodies.
+- Sandbox: Jamf developer sandbox or trial instance; computer and mobile device records can be created through the Classic API, inventory detail needs an enrolled device.
+- Sim: import `computer-inventory`, `mobile-device`, `computer-group`, `policy` (Classic), `configuration-profile`, `extension-attribute` from the instance spec; overlay from extension attributes; webhook payloads as change-event fixtures; one enrolled test Mac for real inventory rows.
+
+### Kandji (Iru) (base)
+
+- Docs: https://api-docs.kandji.io/, which **301s to https://api-docs.iru.com/** (Kandji is Iru). The page is a Postman documenter shell; the authoritative artifact is the collection JSON it renders, which is directly fetchable and pinnable (verify `_postman_id` matches the shell's `collectionId`). Tenant URL `https://<subdomain>.api.kandji.io`; EU `.api.eu.kandji.io`.
+- Machine-readable: no vendor-published OpenAPI confirmed; a community OpenAPI 3.1 generated from Kandji's Postman collection at `MScottBlake/kandji-openapi` (verify against the docs before importing).
+- Introspection: none.
+- Events: webhooks documented on the API site (verify event list and payloads).
+- Errors: **not** `detail`/`error` objects (corrected 2026-09-06). Bodies are a JSON string or an array of strings, with a response-code table on the docs index.
+- Sandbox: request through the account team; devices cannot be created by API.
+- Sim: `docs` importer with a transcribed scope (`devices`, `device_details`, `blueprints`, `library_items`, `users`, `tags`, `device_apps`); captured exports from our tenant and one enrolled Mac as goldens; label `subset`.
+
+### Apple Business Manager (base)
+
+- Docs: https://developer.apple.com/documentation/applebusinessapi and https://developer.apple.com/documentation/apple-school-and-business-manager-api; WWDC25 session 258.
+- **Not read-only** (corrected 2026-09-06, API 2.4): 2.0 added `POST /v1/orgDeviceActivities`, 2.1 added mdmServer create/update/delete. The blocker is that we own no sandbox, so writes would land in our production org, not that the surface is read-only. Apple publishes no downloadable OAS URL; the machine-readable form is Apple's own DocC JSON (`developer.apple.com/tutorials/data/documentation/applebusinessapi.json`), which is pinnable.
+- Machine-readable: Apple states the Business API is specified in an OpenAPI-compliant format; locate the spec download on the API documentation page and pin it (verify the exact URL).
+- Introspection: none.
+- Events: none; batch activity status is polled.
+- Errors: JSON:API-style `{"errors": [{"id", "status", "code", "title", "detail"}]}`. Apple publishes no `code` vocabulary; only per-endpoint HTTP statuses are evidenced, so raise the documented status and reason rather than invent codes.
+- Sandbox: none; our own ABM org with real devices; read-only API.
+- Sim: import `OrgDevice`, `MdmServer`, device assignment and `OrgDeviceActivity` from the spec; seed from exports of our org; label `subset`.
+
+### Workday (tenant-shaped)
+
+- Docs: https://community.workday.com/sites/default/files/file-hosting/productionapi/ (WWS directory with WSDL and XSD per service and version; `Human_Resources`, `Staffing`, `Financial_Management`); REST at developer.workday.com behind Community login; RaaS custom reports.
+- Machine-readable: public WSDL/XSD per service and version (e.g. `.../productionapi/Human_Resources/v19/Human_Resources.wsdl`, newer versions under `versions/`).
+- Introspection: the tenant's WSDL at `https://<host>.workday.com/ccx/service/<tenant>/Human_Resources/v44?wsdl` carries the tenant's custom objects and fields; RaaS report definitions describe custom reports. Overlay source, required.
+- Events: no public change feed; integrations use "Get_*" with effective dating and transaction log queries.
+- Errors: SOAP faults with Workday validation messages.
+- Sandbox: customer or partner tenant only.
+- Sim: `wsdl-xsd` importer over the public WSDL for the skeleton (`Worker`, `Position`, `Job_Profile`, `Organization`, `Location`, `Compensation`), effective-dated fields modelled as `effective_date` on rows; overlay from the tenant WSDL when one exists; label `subset` until then.
+
+### Salesforce (tenant-shaped)
+
+- Docs: https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/ (REST), SOQL reference, Metadata and Tooling APIs.
+- Machine-readable: per-org, generated: global describe `GET /services/data/vXX.X/sobjects/`, `GET .../sobjects/{name}/describe` (fields, types, picklist values, `referenceTo`, `nillable`, `createable`, `updateable`); OpenAPI 3 generation for the sObjects REST API (`/services/data/vXX.X/async/specifications/oas3`, beta) which reflects the org's custom objects and fields.
+- Introspection: the same describe; it is the model, not an overlay. The shared template is a skeleton of standard objects.
+- Events: Change Data Capture and Platform Events (event message with `ChangeEventHeader`: `changeType`, `changedFields`, `recordIds`); the Pub/Sub API delivers them.
+- Errors: array of `{"message", "errorCode", "fields"}` with codes such as `REQUIRED_FIELD_MISSING`, `FIELD_CUSTOM_VALIDATION_EXCEPTION`, `INVALID_FIELD`, `NOT_FOUND`.
+- Sandbox: Developer Edition org, scratch orgs via Dev Hub; any sObject seedable; SOQL for reads.
+- Sim: `describe` importer against a Developer Edition org for the skeleton, then against the bound org for the tenant model; picklists to enums, `referenceTo` to relationships, polymorphic lookups as nullable ids; the error array as the error table; CDC messages as change-event fixtures; SOQL subset as the query tool, scoped by the golden set.
+
+### NetSuite (tenant-shaped)
+
+- Docs: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/ (REST web services, SuiteQL, Records Catalog).
+- Machine-readable: per-account `GET /services/rest/record/v1/metadata-catalog` (OpenAPI 3.0 with `Accept: application/swagger+json`, JSON Schema with `application/schema+json`), including custom records and fields; the Records Catalog UI documents record types.
+- Introspection: the same catalog; it is the model.
+- Events: no public change feed; SuiteScript user events and REST `lastModifiedDate` filters.
+- Errors: `{"type", "title", "status", "o:errorDetails": [{"detail", "o:errorCode"}]}`.
+- Sandbox: partner developer account through the SuiteCloud Developer Network; customer sandboxes are paid add-ons.
+- Sim: `describe` importer over the metadata catalog for `customer`, `vendor`, `inventoryItem`, `salesOrder`, `invoice`, `journalEntry`, `account`, `subsidiary`; sublists as child entities; SuiteQL subset as the query tool; error object from the docs.
+
+### Linear (base)
+
+- Docs: https://linear.app/developers/graphql and https://linear.app/developers/webhooks
+- Machine-readable: GraphQL introspection on `https://api.linear.app/graphql` (public schema also browsable on Apollo Studio); the TypeScript SDK is generated from it.
+- Introspection: none per workspace beyond workflow states and labels, which are data, not schema.
+- Events: webhooks for Issue, Comment, Project, ProjectUpdate, Cycle, Label, User, IssueLabel, Document, Reaction, SLA; payload mirrors the GraphQL entity.
+- Errors: GraphQL `errors[]` with `extensions.type` and `userPresentableMessage`.
+- Sandbox: a free workspace; everything seedable through the API.
+- Sim: `graphql` importer (add to the importer list) over introspection for `Team`, `User`, `Project`, `Cycle`, `Issue`, `Comment`, `WorkflowState`, `IssueLabel`; webhook payloads as change-event fixtures.
+
+### Jira Cloud (mixed)
+
+- Docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
+- Machine-readable: OpenAPI at `https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json`.
+- Introspection: `GET /rest/api/3/field` (global custom fields), `GET /rest/api/3/issue/createmeta?expand=projects.issuetypes.fields` (per project and issue type, including team-managed fields), issue types, statuses, workflows. Overlay source.
+- Events: webhooks (`jira:issue_created`, `jira:issue_updated` with `changelog`, comment and worklog events).
+- Errors: `{"errorMessages": [...], "errors": {"field": "message"}}`.
+- Sandbox: a free Jira Cloud site.
+- Sim: import `IssueBean`, `Project`, `User`, `Comment`, `Transition`, `Sprint` (Agile API) from the OpenAPI; custom fields via overlay from `field` and `createmeta`; webhook `changelog` as the change-event fixture.
+
+### Google Drive and Google Calendar (base)
+
+- Covered under Google Workspace above: discovery documents `drive/v3` and `calendar/v3`, push notifications and `changes` for Drive, Reports API activity for both, the Google error envelope, and the test domain sandbox.
+- Sim: import `File`, `Permission`, `Revision`, `Comment`, `Drive`; `Event`, `CalendarListEntry`, `Acl` from discovery; `attendees` stays nested on events.
+
+### Notion (base)
+
+- Docs: https://developers.notion.com/reference
+- Machine-readable: `makenotion/notion-mcp-server/scripts/notion-openapi.json` (OpenAPI 3.1, used by Notion's own MCP server).
+- Introspection: `GET /v1/databases/{id}` returns the database's property schema; treat Notion databases as tenant-defined entities layered over fixed `Page`, `Block`, `Database`, `User`, `Comment`.
+- Events: Notion webhooks for page, database, and comment events (verify current event list).
+- Errors: `{"object": "error", "status", "code": "validation_error", "message"}`.
+- Sandbox: a free workspace with an internal integration.
+- Sim: import the fixed objects from the OpenAPI; a per-database overlay produced from the database schema endpoint; the existing `notion-sim` tasks migrate onto it.
+
+### Zoom (base)
+
+- Docs: https://developers.zoom.us/docs/api/
+- Machine-readable: `zoom/api` repository `openapi.v2.json` (OpenAPI 2); the marketplace also serves per-product OAS files (Meetings, Users, Phone).
+- Introspection: none.
+- Events: webhooks and the Webhook event catalog (`meeting.started`, `meeting.participant_joined`, `recording.completed`).
+- Errors: `{"code": 3001, "message": ...}`.
+- Sandbox: a free developer account with a Server-to-Server OAuth app; meetings and users seedable.
+- Sim: import `User`, `Meeting`, `Participant` (reports), `Recording` from the OAS; webhook events as change-event fixtures.
+
+### Stripe (base)
+
+- Docs: https://docs.stripe.com/api
+- Machine-readable: `stripe/openapi` (`openapi/spec3.json`, public; `spec3.sdk.json` with internal annotations), versioned with the API.
+- Introspection: none.
+- Events: `Event` objects with `data.object` for every resource change; the OpenAPI enumerates event types.
+- Errors: `{"error": {"type": "invalid_request_error", "code", "param", "message"}}`.
+- Sandbox: Stripe test mode plus `stripe/stripe-mock`, a mock server generated from the same OpenAPI that validates request parameters and 404s unknown paths.
+- Sim: import `customer`, `payment_intent`, `charge`, `invoice`, `subscription`, `event` from `spec3.json`; the error object from the spec; `stripe-mock` is the reference for what a spec-generated mock can and cannot do (it validates shapes, holds no state), which is exactly the gap a schema world fills.
+
+### Existing sims (synthetic)
+
+- E-commerce bench, EnterpriseOps HR, ATS sim, Zapier pipeline sim, Google Drive sim, Notion sim: the model source is their committed `seeds/schema.sql` or `db/schema.sql`. Write `world.json` from the DDL (a `ddl` importer once it exists), keep tasks and verifiers, regenerate artifacts, label `synthetic` unless a vendor spec replaces the hand-written model.
+
+### Cloudburst (base)
+
+- Docs: https://burst.cloud/api/ is the only public description (prose plus five response screenshots, 2023 assets still served in 2026); the real developer docs are a password-gated ReadMe site titled "Cloudburst API" at https://docs.cloudburst.info/. The vendor is Cloudburst Technologies, Inc. (burst.cloud), off-chain crypto/financial-crime intelligence from Telegram, Discord, forums, breaches and stealer logs; not `cloudburst.io` (unregistered), not `cloudbursttech.com` (an unrelated Berlin data-recovery firm), not CloudburstMC or hydro-project. No SDK on PyPI, npm or GitHub; no MCP registry listing although the homepage sells an MCP server.
+- Machine-readable: an OpenAPI 3 document exists but needs a credential: `GET https://cloudburst.info/api/schema/` answers `401` with `Content-Type: application/vnd.oai.openapi` (`?format=json` → `+json`), i.e. drf-spectacular on a Django REST Framework service whose root is `https://cloudburst.info/api/v1/` (confirmed 2026-09-08). Until TRM's key fetches it, the model comes from the screenshots (`GET {{api_url}}/users?phone=…`, `GET {{api_url}}/users?first_name=…`, a signal object with nested `channel{entity_id, participants, score{crowd, time}}` and `message{post_id, message_text, post_datetime}`) and from the 2024 marketing bundle (`web.archive.org/web/2024id_/https://burst.cloud/assets/main.a014b33b.js`), which embeds 1,000 vendor-published signal rows `{id, signal_type: buy|sell, signal_datetime, commodity, base_commodity, exchanges[]}`. The screenshots' `{{api_url}}` is a Postman variable: ask for the collection too.
+- Introspection: none per customer; the schema is vendor-defined (base). The vendor's own OpenAPI endpoint is the introspection, credential-gated.
+- Events: none public. "Streaming is on the roadmap" (api page, unchanged since 2023); the Chainalysis OSINT-tab integration (2024-06) advertises "real-time alerts" without a payload; the MCP server's tool list is unpublished. Treat signals as the change-record entity for now.
+- Errors: DRF envelope. Confirmed live: `401 {"detail": "Authentication credentials were not provided."}` (`code: not_authenticated`). DRF defaults to keep until captured: `404 {"detail": "Not found."}`, `403 {"detail": "You do not have permission to perform this action."}`, `400 {"<field>": ["…"]}` / `non_field_errors`, `429 {"detail": "Request was throttled. Expected available in N seconds."}` with `Retry-After`. Rate limits and the auth header scheme (DRF `Token` vs Bearer) are unverified.
+- Sandbox: none; demo by request only (`contact@burst.cloud`), docs password-gated. Live checks are `skipped` unless TRM lends a developer key. No public TRM–Cloudburst integration exists (TRM's published OSINT sources are Google, Chainabuse and Flashpoint, March 2026); which surface TRM's agent uses (REST, MCP, bulk) is knowable only from its logs.
+- Sim: hand-author from `--connector custom`: `cloudburst_channels` (key `entity_id`, Telegram peer id string), `cloudburst_users` (key `id`, `entity_id` unique, nested `phones[]`), `cloudburst_channel_memberships` (`user_id, channel_entity_id`; `flair`, `joined_at`; the vendor inlines these as `users[].channels[]`), `cloudburst_messages` (`channel_entity_id, post_id`; global uniqueness of `post_id` unverified), `cloudburst_signals` (key `id`; `price_data{expected_gain, stop_loss, entry_price_range, target_prices}`, `exchanges[]`); `cloudburst_wallets` and `cloudburst_entities` only as labelled skeletons because no public source shows a field. Vendor timestamps carry no zone (`2023-05-01T01:40:21`): use `vendor-date-time`. Read tools return bare arrays as captured; the DRF error table on every tool; synthetic fixtures shaped from the 1,000 bundle rows; goldens from TRM's sanitized captures; label provisional `subset`. Re-derive as an `openapi` import the day `/api/schema/?format=json` is pinned.
+
+### Constella Intelligence (base)
+
+- Docs: https://constella.ai/data/developer-portal/ and https://constella.ai/data/intelligence-api/. **The API reference is behind an MNDA** ("We offer API documentation to partners and prospective partners who have executed an MNDA with us"); tokens are issued to licensed or evaluating partners via `support@constellaintelligence.com`. Vendor formed 2020-12 from 4iQ + Alto Analytics; products are Hunter (investigator UI at `app.constellaintelligence.com`), Hunter+ DRP (formerly Dome), and the Intelligence API. Legacy site `constellaintelligence.com`.
+- Machine-readable: **none public** (verified 2026-09-08): no OpenAPI, Postman, or SDK repository despite the claim of Python/JavaScript/Go libraries. The best public interface description is the vendor-hosted Maltego transform catalog at https://docs.maltego.com/en/support/solutions/articles/15000053397-constella-intelligence — 14 `search_for_*` selectors (email, username, phone_number, domain, ip, company, brand, ssn, credit_card, tax_id, nid, passport, driver_license, facebook_id) and 18 `extract_*` record attributes (address, company, credit_card, dob, domain, email, name, password, phone_number, source, ssn, username, ip v4/v6, facebook_information, tax_id, national_id, passport, driver_license); auth settings `constella_app_token`, `constella_token`, `constella_username`. Vocabulary for password state (Plaintext / Hashed / No Passwords) and hash algorithms (MD5, MySQL323, SHA-1, Bcrypt, private) from the 2026 Identity Breach Report (`https://constella.ai/wp-content/uploads/2026_Feb_IdentityBreachReport.pdf`, SHA-256 `26ea4e2c…950ec`); operation families (Search API, Monitoring API with bulk registration and callback-URL alerts, Password API per NIST 800-63b) from the 2019 4iQ IDTheft datasheet (`https://ppbw.pl/wp-content/uploads/2019/11/i-LEAD-Industry-Days-4iQ-2.pdf`, SHA-256 `bf71498b…966a`) — historical, verify against TRM's logs.
+- Introspection: none. One fixed lake for every customer ("over 50 record attributes", "over 200 normalized fields"); tenant differences are entitlements (licensed selectors, clear-text vs hashed/masked returns) and monitored populations, which are rows, not schema.
+- Events: no public change feed for the lake. Monitoring alerts to a callback URL (4iQ 2019, verify current form); Dome/Hunter+ findings reach Splunk through `TA-constella-dome-app-for-splunk` v1.0.9 (https://splunkbase.splunk.com/app/6299), whose field mapping lives only in the package. Freshness claim "60-day" for infostealer data.
+- Errors: **not public.** No envelope, code vocabulary, or rate-limit header is documented; pricing is "per-query or per-monitored-identity". Model statuses only (400/403 unlicensed selector, 401 bad token, 429 quota, empty list for no hits) and mark each `unverified` until TRM supplies observed bodies.
+- Sandbox: "Sandbox Environment: Test your implementation with demo data" exists only under the MNDA + evaluation agreement; nothing self-serve. Live checks `skipped` unless TRM lends a dev key.
+- Sim: hand-author from `--connector custom`: `constella_sources` (breach/exposure event; type enum breach|infostealer_log|combolist|paste|forum_registration|marketplace|surface_web; `exposure_date`), `constella_records` (one row per breach record, every Maltego-extractable attribute nullable, `password_state` + `hash_algorithm` enums, `source_id`), `constella_identities` (entity-resolved, `risk_score`), optional `constella_infostealer_logs` + `constella_cookies` (active|expired) and `constella_monitors` + `constella_alerts` per TRM's usage. Index records by every selector column so `search_records{selector_type, value}` returns believable multi-source hits; wholly synthetic fixtures (passwords and government IDs are sensitive by construction); label provisional `subset` with transport, error envelope, and live checks listed as the reasons. The three things only TRM can supply: base URL + method/path + auth header per call; raw hit/miss envelopes per selector with pagination and field names; observed error bodies and limits.
+
+### SpyCloud (base)
+
+- Docs: https://docs.spycloud.com/public-sc (index at https://docs.spycloud.com/public-sc/llms.txt; append `.md` to any page); API guidelines https://docs.spycloud.com/public-sc/docs/api-guidelines; public "Limited Data Schema" https://docs.spycloud.com/public-sc/docs/data-schema (the full 200+ asset schema is at `portal.spycloud.com/docs/sc-full-data-schema`, login required); severity scale in https://docs.spycloud.com/public-sc/docs/faqs.
+- Machine-readable: every reference page under https://docs.spycloud.com/public-sc/reference/ embeds a per-operation OpenAPI 3.1 document (`investigations-api` 1.1 at `https://api.spycloud.io/investigations-v2`, `enterprise-ato-prevention-api` 1.1 at `https://api.spycloud.io/enterprise-v2`, `session-identity-protection-api` at `sip-v1`, `idlink-api` at `idl-v2`); `api-evangelist/spycloud` `openapi/_original/*.yml` bundles the same exports per product (third-party profile). Response schemas are mostly `{}`; entity fields come from `data-schema.md` plus integration fixtures: `demisto/content` `Packs/SpyCloudEnterpriseProtection` (client source, raw `test_data/*.json` envelopes, README context examples), `elastic/integrations` `packages/spycloud` (CEL request programs, `fields.yml`, `sample_event.json`), `eatm-cert-user/spycloud` (watchlist identifier pull).
+- **Tier decides the selector set, not the schema**: Investigations exposes 19 `/breach/data/<selector>/{value}` lookups (email, domain, username, ip, password, phone, email-username, social-handle, log-id, infected-machine-id, cc/bank/drivers-license/national-id/passport/SSN as hashes) with `fuzzy` on username/password/handle/email-username; Enterprise exposes 5 of them plus `/breach/data/watchlist`, `/watchlist/*` identifier CRUD (the only writes), and `/compass/*`. Both share `/breach/catalog` and `/breach/catalog/{id}`, the header `x-api-key`, and the envelope `{"cursor", "hits", "results"}` at a fixed 1,000 per page with a ~2-minute cursor lifetime.
+- Introspection: none; no per-tenant schema. Per-key configuration instead: function allow-list, asset allow-list (masked assets return exactly `********`; `document_id`, `source_id`, `spycloud_publish_date` always shown), optional asset hashing with a `salt` query param, IP allow-list, monthly quota. Model as world config, never as an overlay.
+- Events: none (no webhooks). Change signal is `spycloud_publish_date` and `record_modification_date` with `since`/`until`/`since_modification_date`/`until_modification_date`; the Elastic CEL programs are the reference polling loop over `/breach/catalog`, `/breach/data/watchlist`, `/compass/data`.
+- Errors: JSON on every code; 400 invalid identifier/param, 403 bad key / non-allow-listed IP / function not allowed (header `SpyCloud-Error: Invalid API key|Invalid IP`), 429 rate limit (header `x-amzn-ErrorType: TooManyRequestsException`, "Too many requests") and 429 quota (`LimitExceededException`, "Limit exceeded"; rate limit takes precedence), 500, 504 (Enterprise), 422 (IDLink >2000 matches). Bodies carry `message` or `errorMessage`; exact 4xx bodies are unpublished — verify with a key.
+- Sandbox: none public and no trial; keys are per licence via `portal.spycloud.com`, IP allow-listed, quota'd. Live checks `skipped` unless TRM lends a dev key; synthetic fixtures from the public examples, goldens from TRM's sanitized captures.
+- Sim: import the readme.io OpenAPI (per page or the `_original` bundle) for paths and params; author `spycloud_breaches` (`id` int, `uuid`) and `spycloud_breach_records` (`document_id`, `source_id → id`, `severity` 2|5|20|25|26) from `data-schema.md`, adding the fields only evidenced by Elastic/XSOAR fixtures (`ip_addresses`, `sighting`, `record_*_date`, `breach_title`, `breach_category`, PII, `premium_flag`) with per-field provenance; carry catalog `type` uppercase as observed (`PUBLIC`/`PRIVATE`) and note the docs' lowercase; implement each selector as an indexed filter over records (email lowercased; hash selectors; `type` filter semantics unverified); derive catalog `assets` counts from records; reproduce the envelope, 1,000-row cursor pages with expiry, masking and both 429 headers as config; `spycloud_watchlist_identifiers` (`identifier`, `watchlist_type` email|domain|subdomain|ip, `verified`, `last_discovered`) only for the Enterprise configuration. Label provisional `subset` until TRM supplies the full schema page and captures.
+
+## How to use a dossier
+
+1. Start from the machine-readable source; only fall back to docs where none exists.
+2. Read the connector itself for the overlay wherever an introspection row exists; for tenant-shaped connectors that read is the model.
+3. Use the event or webhook schema as the shape of change records and as ingestion fixtures; they are the cheapest real-world evidence.
+4. Model the error format; a world that never says `REQUIRED_FIELD_MISSING` teaches the wrong reflexes.
+5. Seed the sandbox, pull, ingest, replay; goldens are synthetic-ized before they are committed.

gatewaysdk/environment/schema/skills/connector-schema-authoring/CONVENTIONS.md

@@ -0,0 +1,100 @@
+# Generation conventions
+
+Every connector template, whether hand-authored, imported, or uploaded, follows these
+conventions so worlds look and behave the same across connectors. `test_schema_scaffold.py::test_committed_templates_follow_the_generation_conventions`
+enforces the mechanical ones on every committed template; the rest are review items.
+
+## Contents
+
+- [Identity](#identity)
+- [Entities](#entities)
+- [Fields and types](#fields-and-types)
+- [Tools](#tools)
+- [Data, verifiers, and provenance](#data-verifiers-and-provenance)
+- [Layout](#layout)
+- [Patterns borrowed from prior art (Arga Labs twins)](#patterns-borrowed-from-prior-art-arga-labs-twins)
+
+## Identity
+
+| Thing | Convention | Example |
+| --- | --- | --- |
+| Template slug | lowercase, hyphenated, the vendor's common name | `google-calendar`, `microsoft-entra`, `apple-business-manager` |
+| Domain `$id` | `urn:gateway:connector:<slug>` | `urn:gateway:connector:okta` |
+| Package id | `gateway-connector-<slug>` in the template; `init --name` overrides for a world | `gateway-connector-okta` |
+| `domain_version`, package `version` | semver strings, start at `1.0.0`; bump `domain_version` on any entity change, package `version` on tool or handler change | |
+| Manifest | `[environment] connector = "<slug>"` records the template a world came from | |
+| Shape | recorded in `provenance.json` as `shape: base \| tenant-shaped \| mixed` | |
+
+## Entities
+
+- **One prefix per template**, short and stable, applied to every entity: `slack_`, `github_`, `sf_`, `okta_`, `gws_`, `entra_`, `ldap_`, `jamf_`, `kandji_`, `abm_`, `workday_`, `netsuite_`, `drive_`, `calendar_`, `linear_`, `jira_`, `notion_`, `zoom_`, `stripe_`. The `custom` template uses `records`. The reservation lives in `test_schema_scaffold.py::PREFIXES`; claim a prefix there before authoring. Prefix collisions are refused; two templates never share a prefix.
+- Entity names are plural snake_case nouns after the prefix: `okta_users`, `github_pull_requests`. No abbreviations beyond the prefix.
+- Every entity declares `primary_key`; use the vendor's id (`id`, `Id`, `key`, `account_id`) rather than inventing one. Composite keys follow the vendor's containment order (`repo_id`, `number`; `calendar_id`, `id`).
+- Relationships point at the parent's primary key and are declared on the child; `on_delete` is always `restrict` (the language allows nothing else).
+- Membership and other many-to-many facts are their own entity with a composite key (`slack_memberships`), never arrays of ids on either side.
+- Uniqueness beyond the key is declared where the vendor enforces it (`slack_channels.name`, `okta_users.login`), not where it merely tends to hold.
+
+## Fields and types
+
+- Field names follow the vendor's casing (`Id`, `StageName` for Salesforce; `created_at` for GitHub). Do not normalize casing; fidelity beats uniformity.
+- Reuse `schema/base.json` primitives: `Id`, `Label`, `Text`, `Email`, `Timestamp`. `base.json` is byte-identical across templates; add a primitive to the shared file, never to one template.
+- Nullable versus optional are distinct: a field the vendor always returns but may be null is `type: [..., "null"]` and required; a field the vendor may omit is optional. Never both unless the vendor does both.
+- Timestamps are `Timestamp` (`format: date-time`). Vendor dates without time are 10-character strings until the compiler has a `date` format; note it in `provenance.json`.
+- Enums are the vendor's literal values, in the vendor's order, including their casing (`"Closed Won"`, `needsAction`). Tenant-added values arrive through the overlay.
+- Numbers carry the vendor's bounds where documented (`probability` 0..1, sizes `minimum: 0`).
+- Polymorphic references (Salesforce `WhoId`) are nullable strings without a relationship, listed under `polymorphic` in `scope.toml`.
+- Free-text bodies use `Text`; names and titles use `Label`; identifiers use `Id`.
+
+## Tools
+
+- Tools are optional. When a template ships them, the default set per primary entity is `list_<entities>`, `get_<entity>`, and one write (`create_<entity>` or the vendor's verb such as `post_message`, `transition_issue`, `update_stage`).
+- Names are `verb_noun` in snake_case, vendor verbs preferred where the vendor has a well-known one.
+- Input schemas are closed objects; reads take the parent key (`channel_id`, `repo_id`), writes take a whole entity payload under a singular key (`message`, `issue`, `opportunity`).
+- Every write goes through `gateway_env.store`; handlers raise the vendor's error string for the violations the vendor reports (`not_in_channel`, `invalid_transition`).
+- A template that declares an MCP surface keeps that surface's tool names verbatim and reports parity; it does not rename to fit this convention.
+
+## Data, verifiers, and provenance
+
+- `data/records.json` is synthetic and small (a handful of rows per entity, enough to exercise every relationship). `data/initial.json` is produced from it by the fixture mapper with `coverage: partial`. Never vendor or customer data.
+- One starter verifier, `verifiers/state_present.sql`, scoring 1.0 when the first entity holds a row; real tasks replace it.
+- `schema/provenance.json`: `shape`, `source` (`kind`, `url`, `version`, `sha256`), `importer` (name, version) or `authored_by`, `scope_hash`, `generated_at`. Imported templates must round-trip: re-running the importer reproduces `world.json`.
+- `scope.toml` (imported templates): entity allowlist, key overrides, relationship hints, `polymorphic`, and the reason for every exclusion.
+- Goldens under `tests/golden/<slug>/*.jsonl`, synthetic-ized; never raw captures.
+
+## Layout
+
+```
+<slug>/                   in gatewaysdk/environment/schema/connectors/
+  world.json              authored authority (or importer output)
+  handlers.py             only if the template ships tools
+  provenance.json         source, shape, importer, hashes
+  scope.toml              imported templates only
+  connector.toml          only if the template mirrors a vendor API; init copies it to the world root
+```
+
+A world initialized from a template (`gateway worlds schema init`) adds `gateway-env.toml`,
+`schema/base.json`, `data/`, `verifiers/`, and the generated artifacts, exactly as
+[world-schema.md](../../../documentation/features/world-schema.md) lists them.
+
+## Patterns borrowed from prior art (Arga Labs twins)
+
+Arga Labs (argalabs.com; docs.argalabs.com) ships "stateful replicas" of thirty-plus
+services with API, MCP, CLI and UI surfaces over one state store. Their public docs
+describe patterns worth adopting as conventions here; none require new infrastructure.
+
+| Arga pattern | Our equivalent or adoption |
+| --- | --- |
+| Twins are **behavioural**: same error responses, rate limits, side effects as the real service ("attempting payment to a non-existent customer returns identical error codes") | The error table per template and vendor-shaped errors raised by handlers; never a generic exception where the vendor has a code |
+| **Stub honesty**: partial endpoints return `_twin_stub: true` and `_twin_warning`; GitHub exposes `GET /admin/stub-hits` | A tool the template does not fully model raises `not_modelled` with the vendor operation name instead of fabricating a response; `fidelity.json` counts them; never fake data for an unmodelled operation |
+| **Deterministic seeding** with reproducible ids per scenario; "empty state unless seeded or created through the API" | `data/initial.json` batches with stable ids; worlds start empty by default; `store.ingest` for seeding code |
+| **Scenarios** as saved `seed_config` per twin, resettable ("reseed from the Scenario") | `BenchmarkContainerCondition` states and `World.reset()`; a scenario is a condition plus its initial batch |
+| **Permission enforcement**: OAuth scopes checked per call (`missing_scope`), capability levels (Notion), tier quotas (`insufficient_space`) | Model scopes and tiers as `benchmark_runtime_parameters` conditions the handlers consult; error codes in the error table; a future compiler feature could declare required scopes per tool |
+| **Webhooks with signed delivery and replay** | Event entities (System Log, audit logs, `stripe_events`) and event fixtures; live webhook emission is out of scope for a mock-tools world today |
+| **State inspection and reset endpoints** (`/admin/state`, `/admin/reset`, `/admin/clock`) | `World.state()`, `store.list()`, `World.reset()`; a clock control (`benchmark_runtime_parameters.now`) is a cheap addition for time-dependent fidelity |
+| **Multiple surfaces over one store** (REST, GraphQL, CLI, MCP, UI share state) | The schema is the store; tools, MCP-mapped tools, custom tools, and a future API-kind twin all sit on it |
+| **Production-seeded scenarios** from connected services | `store.ingest` from a bound connection with PII policy (infra plan B3/B4) |
+
+What we deliberately do differently: Arga's twins are code they operate; ours are a
+declarative contract anyone can author or import, measured for fidelity against the
+vendor's own schema, and the same contract serves ingestion, grading, and tools. Their
+per-twin "known limitations" pages are the model for our `fidelity.json` and badge.