@miruzero/zgpt 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # Zero ChatGPT
 
-`M:\Zero_ChatGPT` is the standalone ChatGPT runtime and the only default owner of ChatGPT state.
+`@miruzero/zgpt` is the standalone ChatGPT SDK and CLI package. `M:\Zero_ChatGPT` is the developer checkout path, **not** a module import path for npm users.
 
 ## Scope
 
@@ -12,9 +12,9 @@ This package contains only ChatGPT-specific runtime code:
 - ChatGPT connector operations
 - ChatGPT Web protocol mechanics
 - direct HTTP/SSE transport
-- ChatGPT mutable state under `M:\Zero_ChatGPT\state`
+- ChatGPT mutable state in the runtime's configurable `state/` directory (`ZERO_CHATGPT_STATE_DIR`)
 
-It contains no Zero Core, MCP, Agent orchestration, CLI adapter, or generic device/task runtime.
+It contains no Zero Core, MCP, Agent orchestration, or generic device/task runtime. The CLI is a thin adapter over the same public SDK exports.
 
 ## CLI
 
@@ -25,32 +25,133 @@ npm install -g @miruzero/zgpt@latest
 zgpt
 ```
 
-For a project-local installation, use `npx`:
+For a project-local installation using the published package name:
 
 ```sh
 npm install @miruzero/zgpt@latest
 npx zgpt
 ```
 
+If you want the **short JavaScript import** `require('zgpt')`, install the published scoped package with an npm alias:
+
+```sh
+npm install zgpt@npm:@miruzero/zgpt@latest
+```
+
+```js
+const chatgpt = require('zgpt');
+```
+
+The two installation forms are alternatives. If you installed `@miruzero/zgpt` under its original name, import it using that same name:
+
+```js
+const chatgpt = require('@miruzero/zgpt');
+```
+
+The npm package name and the CLI binary name are independent; installing **only** `@miruzero/zgpt` does not create a local `node_modules/zgpt` alias.
+
 The package exposes the `zgpt` executable through npm's `bin` field. A local `npm install` does not add `node_modules/.bin` to the parent shell's PATH, so use `npx zgpt` for local installs or install globally for the bare `zgpt` command.
 
+### Hierarchical SDK → CLI automatic command discovery
+
+The CLI discovers top-level public SDK namespaces at runtime, and groups the methods under each namespace. New namespaces and methods appear automatically without a second command registry. Use `zgpt help`, `zgpt help profile`, or `zgpt api families` to browse:
+
+```sh
+zgpt help profile
+zgpt profile getMe
+zgpt profile getAuraIdentity
+zgpt conversation get conversation-id
+zgpt api models
+zgpt api models getModels
+zgpt api invoke "GET /public-api/conversation_limit"
+```
+
+- Preferred: `zgpt <namespace> <method> [arguments...]` dispatches to the same SDK owner function. Use `--args JSON_ARRAY` for structured parameters. Older `zgpt call namespace.function` remains compatible.
+- `zgpt api <family> <methodName>` groups the API catalog by `family` without duplicating routes. `zgpt api invoke "METHOD /route"` remains available, and supports `--path-values`, `--query`, `--options`, and `--body` for JSON input.
+- Explicit non-read operations need `--allow-write` and required arguments. The generic adapter does not invent request payloads or permissions.
+- Results are JSON and credentials in recognized sensitive fields are redacted for CLI output; direct JS callers receive unmodified objects.
+- On this host, `npm link` points to `M:\Zero_ChatGPT`, so source changes take effect in the next CLI process. For a separately installed or published npm package, its installed version must be updated to receive changes.
+
+
 ## Public API
 
+After `npm install zgpt@npm:@miruzero/zgpt@latest`:
+
 ```js
-const chatgpt = require('M:/Zero_ChatGPT');
+const chatgpt = require('zgpt');
 
+async function main() {
+// Configure ZERO_CHATGPT_STATE_DIR and authenticate before these calls.
+// Session acquisition can be requested via chatgpt.session.acquire() if needed.
 await chatgpt.auth.ensure();
-await chatgpt.session.acquire();
-await chatgpt.conversation.get(id);
-await chatgpt.conversation.send(id, message);
-await chatgpt.project.listProjects(options);
-await chatgpt.connector.listConnectors(options);
+const conversation = await chatgpt.conversation.get('YOUR_CONVERSATION_ID');
+const projects = await chatgpt.project.list();
+const connectors = await chatgpt.connector.listConnectors();
+
+// Mutations happen only when explicitly invoked:
+// await chatgpt.conversation.send('YOUR_CONVERSATION_ID', 'Hello');
+// await chatgpt.conversation.create('New conversation');
+// await chatgpt.project.create('My project');
+
+// Profile and Chat settings (only when entitled; writes require explicit bodies)
+await chatgpt.profile.getMe();
+await chatgpt.profile.getCreator();
+// await chatgpt.profile.updateCreator({ body: { display_name: 'Developer' } });
+await chatgpt.settings.getUser();
+await chatgpt.settings.getConsent();
+await chatgpt.settings.getNotifications();
+await chatgpt.profile.getAuraIdentity();  // GET /backend-api/aura/identity
+
+// ChatGPT Web API catalog: saved Web evidence plus verified supplemental routes.
+// Generic routes require appropriate account permissions and exact request contracts.
+console.log(chatgpt.api.summary.total); // 1291 (includes provisional paths)
+const route = chatgpt.api.find({ method: 'GET', route: '/api/auth/session' });
+const authSession = await chatgpt.api.invoke(route.key);
+const limits = await chatgpt.api.invoke('GET /public-api/conversation_limit');
+// Never log authSession: it can contain authentication credentials.
+
+// Parameterized route and explicit one-shot writes (only with a verified payload):
+// await chatgpt.api.invoke('POST /backend-api/hosting/sites/{id}/access',
+//   { pathValues: [siteId], body: verifiedBody });
+}
+
+main().catch(error => {
+  console.error(error.message);
+  process.exitCode = 1;
+});
 ```
 
+Saved web evidence is stored in `src/api/discovered.json`, while the four authenticated Browser Network GET discoveries are in `src/api/browser-observed.json`.
+Historical endpoints remain in `src/api/catalog.json`; the runtime combines all three catalogs. Runtime query contracts are stored separately in `src/api/contracts.json`.
+`api.byKey`, `api.functions` and `api.groups` provide typed route-name dispatch.
+This is an **undocumented Web endpoint catalog**, not a guarantee of API stability,
+authorization, correct mutation payloads, or complete browser-feature parity.
+
 ## Runtime rules
 
 - Direct ChatGPT Web transport is the only conversation transport.
 - Session exchange transport must be supplied explicitly; no browser/CDP transport is implicit.
 - 429 opens shared cooldown and is not amplified by retries.
 - No hardcoded credentials or secret-bearing diagnostics.
-- Default writable state lives only under `M:\Zero_ChatGPT\state`.
+- By default, state is stored in `state/` relative to the installed package. For an npm-installed/global package, configure `ZERO_CHATGPT_STATE_DIR` to a **writable, user-owned directory outside `node_modules`** before authenticating. Never commit or publish this state.
+
+## API verification and request contracts (source checkout)
+
+A catalog entry is **not** a proof of a working API. The local verification report classifies all 1,287 routes, and the bounded auditor uses a known-safe GET allowlist, with no mutations, retries, response bodies, cookies, or credentials persisted.
+
+```powershell
+npm run api:audit
+npm run api:audit:live -- --start 0 --max 32
+npm run api:audit:live -- --start 32 --max 25
+
+zgpt api models getModelsTrailingSlash
+zgpt api images getImagesPromptItems --query surface=sketch_followups
+zgpt api apps getAppsDirectoryBrowse --query category=productivity
+zgpt api composer getComposerItems --query 'entrypoint=chat&limit=10'
+```
+
+The `--query` flag accepts shell-friendly `name=value` or `name=value&name2=value2`, as well as a JSON object. For GET routes requiring query parameters, see `zgpt api show "GET /backend-api/..."` and `src/api/contracts.json`. The auditor and capture scanners are developer scripts in this source checkout and are not bundled in the npm package. Version `0.1.5` includes the release-ready SDK/CLI changes described above once published.
+
+### Custom MCP server CRUD and action refresh
+
+The connector namespace supports MCP server creation, updates, deletion, OAuth metadata discovery, action refresh and `disconnectConnectorLink` (unlink a connected account without deleting the server definition). Discover exact SDK methods with `zgpt help connector`. **Live verified:** tunnel listing, OAuth discovery, and linked-action refresh (4 actions returned). **Mock verified only:** server create/edit/delete and connector unlink (no live destructive actions). Creating an OAuth-enabled connector auto-discovers metadata unless explicitly overridden. Refresh and unlink take a `linkId`, not a server definition ID. See the included `docs/custom-mcp-management-api.md` for request contracts and validation boundaries.

package/docs/architecture.md

@@ -7,7 +7,7 @@
 ## Runtime
 
 ```text
-auth / session / conversation / project / connector / file / memory / settings / share
+auth / session / conversation / project / connector / file / memory / settings / profile / share / api
                     |
                  protocol
 sentinel / proof / conduit / payload / SSE
@@ -43,7 +43,9 @@ The state directory is the only default writer for ChatGPT runtime state.
 - `connector` owns ChatGPT Chat connector discovery, app metadata, system hints, actions, refresh, and mention resolution.
 - `file` owns Chat composer file reservation, file-entry creation, upload processing, and reservation finalization.
 - `memory` owns Chat memory reads used by the normal Chat surface.
-- `settings` owns normal Chat user settings and explicit user-setting mutations.
+- `settings` owns normal Chat user settings, consent, notifications, voice options, locale and explicit model-preference mutations.
+- `profile` owns profile reads including the Chrome extension's Aura identity GET, GPT creator profile writes and explicitly addressed account user profile updates; no implicit account mutation.
+- `api` exposes an evidence-backed route catalog (historical and supplemental), with a shared direct transport and proper `/public-api` routing; it is not a separate independent Core/Agent or a promise that each route is an implemented or supported feature. Work-only candidate routes carry explicit scope/evidence flags.
 - `share` owns normal Chat conversation share lifecycle.
 - `protocol` owns ChatGPT Web payload, Sentinel, conduit, and SSE mechanics.
 - `transport` owns HTTP, headers, retries, cooldown, and session-cookie persistence.
@@ -72,6 +74,4 @@ conversation is the only owner of stream diagnosis and repair. Callers request a
 5. External ChatGPT responses are validated before state mutation.
 6. This package owns only ChatGPT runtime state.
 7. No Zero Core, MCP, Agent, device, task, or adapter implementation lives here.
-8. No background polling or hidden retry loop is allowed; recovery work occurs only on the active demand or an explicit retry demand.
-
-
+8. Loops, pagination, retry, and polling are allowed when required by the flow; they must have a measurable progress/termination condition, an explicit owner, and bounded failure recovery. Repeated writes must not be replayed without an idempotency guarantee. The current ChatGPT stream recovery remains demand-driven; no blanket prohibition on loops is implied.

package/docs/custom-mcp-management-api.md

@@ -0,0 +1,132 @@
+# Custom MCP Server API — Web Client source audit (2026-10-12)
+
+## Status and scope
+
+**Implemented in local source, no remote mutations performed.** The source of truth is existing ChatGPT Web callsites in the captured files `C:\Users\Administrator\Documents\OSSGPT\chatgpt.com\cdn\assets\conversation-small-cyhg2evird2sa17j.js` and `c2675c8c-j30y5ypuebsjl0k8.js`. The `OAI-Product-Sku` header was resolved from an imported constant in `4813494d-k4tqhmof689yx2je.js`; Web sends `OAI-Product-Sku: CONNECTOR_SETTING`.
+
+Browser form fields: name, optional description, HTTPS server URL or `tunnel_<32 lowercase letters/digits>`, optional PNG icon (data URL; max 10 KB), authentication selection. The Web flow builds `auth_request` from supported authentication types and OAuth discovery before creating a connector. OAuth connection/linking is a separate operation after creation.
+
+| Operation | Web route | Body from Web source | Verification |
+| --- | --- | --- | --- |
+| Create | POST `/backend-api/aip/connectors/mcp` | `{name,description,logo_url,mcp_url OR tunnel_id,custom_headers?,auth_request}` | Static callsite; SDK mocked |
+| Read detail | GET `/backend-api/aip/connectors/{id}` | Path `connector_id` | Static callsite; SDK mocked |
+| Rename | PATCH `/backend-api/aip/connectors/{id}/name` | `{name}` | Static callsite; SDK mocked |
+| Description | PATCH `/backend-api/aip/connectors/{id}/description` | `{description}` | Static callsite; SDK mocked |
+| Icon | PATCH `/backend-api/aip/connectors/{id}/logo` | `{logo_url}` | Static callsite; SDK mocked |
+| Delete | DELETE `/backend-api/aip/connectors/{id}` | Path `connector_id` | Static callsite; SDK mocked |
+| Refresh tools | POST `/backend-api/aip/connectors/mcp/refresh_actions` | `{link_id}` **not** connector ID | Static callsite; SDK mocked; previous SDK wrapper exists |
+| OAuth discovery | POST `/backend-api/aip/connectors/mcp/oauth_config` | `{mcp_url OR tunnel_id,custom_headers}` | **Live SDK and CLI verified using `https://mcps.devteam.sc/core`** |
+| List tunnels | GET `/backend-api/aip/connectors/mcp/tunnels` | None | **Live SDK HTTP 200**; CLI Exit 0 |
+
+No confirmed endpoint for editing an existing server's **MCP URL** directly. Do not infer that renaming/reloading edits the transport URL; recreation may be required but was not performed.
+
+## SDK API
+
+The public exports from `src/connector/mcp.js` are automatically exposed under `zgpt.connector` and as CLI commands via the existing dispatch logic:
+
+```js
+const zgpt = require('@miruzero/zgpt');
+
+// Real GET, with authorized local session:
+const {tunnels} = await zgpt.connector.listCustomMcpTunnels();
+
+// Read-only metadata discovery from the authenticated ChatGPT Web backend.
+const discovered = await zgpt.connector.getCustomMcpOAuthConfig(
+  'https://mcps.devteam.sc/core'
+);
+console.log(discovered.oauth_config.type); // OAUTH
+// Only call the next step if you intend to create an actual connector.
+// Default: auto-discover auth and preserve PKCE, scope and registration metadata.
+const created = await zgpt.connector.createCustomMcpServer({
+  name: 'DevTeam MCP',
+  mcpUrl: 'https://mcps.devteam.sc/core'
+});
+// To bypass discovery, supply a fully configured authRequest explicitly,
+// or set authentication:'NONE' only for intentionally unauthenticated servers.
+await zgpt.connector.renameCustomMcpServer({connectorId:created.connector.id,name:'Renamed MCP'});
+// NOTE: use a linkId returned by the connection/link flow, not created.connector.id:
+// await zgpt.connector.reloadCustomMcpServerActions({linkId:'link_...'});
+// Explicit destructive command only when intended:
+// await zgpt.connector.deleteCustomMcpServer({connectorId:created.connector.id});
+```
+
+**The above example includes mutations and was NOT executed on a live account.** Use only against servers you intend to create/change/delete.
+
+## CLI
+
+```powershell
+zgpt help connector
+zgpt connector listCustomMcpTunnels
+zgpt connector getCustomMcpOAuthConfig https://mcps.devteam.sc/core
+zgpt api show "POST /backend-api/aip/connectors/mcp"
+```
+
+All methods also appear under `zgpt connector <methodName>`. JSON object arguments are passed via `--args JSON_ARRAY` and all non-read methods require `--allow-write`. The general `api` dispatcher also uses the same catalog and enforces required body fields.
+
+## Verification and outstanding work
+
+- Unit/contract suite: **196/196 tests passed** (full project tests as of 2026-10-12).
+- Live read: `GET /backend-api/aip/connectors/mcp/tunnels` HTTP 200 and matching CLI operation exited 0.
+- Mutations (POST create, PATCH metadata, DELETE, POST refresh) **not live tested**; their success depends on actual owner permissions, OAuth configuration, valid image input and server capabilities.
+- The create function only creates a connector definition. Completing OAuth and linking a server is a separate browser/client flow. The wrapper deliberately does not invent OAuth registration/scopes or auto-install a connector link.
+- `logo_url` supports HTTPS or a PNG Data URL, matching the browser's FileReader path and 10 KB limit; generated artwork was not uploaded.
+- The source changes are local and **not yet included in published npm 0.1.4**.
+
+## Source paths
+
+- `src/connector/mcp.js`
+- `src/connector/write.js`
+- `src/connector/index.js`
+- `src/api/contracts.json`
+- `src/api/index.js`
+- `test/connector-mcp-management.test.js`
+
+## Live OAuth Discovery evidence (2026-10-12, MiruZero)
+
+- Actual MCP URL supplied by user: `https://mcps.devteam.sc/core`.
+- Used the existing authenticated SDK session to call `POST /backend-api/aip/connectors/mcp/oauth_config` with `{mcp_url:'https://mcps.devteam.sc/core', custom_headers:[]}` and product SKU `CONNECTOR_SETTING`.
+- **Live verified:** response carried `oauth_config.type=OAUTH`, resource matching the supplied URL, authorization/token/registration endpoints, `pkce_required=true`, `pkce_methods=['S256']`, `scopes_supported=['mcp:read']`, and `token_endpoint_auth_methods_supported=['none']`.
+- CLI `zgpt connector getCustomMcpOAuthConfig https://mcps.devteam.sc/core` returned Exit 0 and the same safe metadata. CLI now preserves public OAuth discovery fields without exposing client secrets, credentials, access tokens or state-bearing authorization URLs.
+- The local `createCustomMcpServer({name,mcpUrl})` defaults to automatic metadata discovery, maps the returned OAuth configuration into `auth_request.supported_auth`, and only then issues the create POST. This sequencing was tested using a stubbed transport, **not performed on the live user account**.
+- Discovery failures and malformed/unsupported OAuth metadata fail closed; the SDK does **not** switch to `NONE` automatically. To intentionally skip discovery, pass either `authentication:'NONE'` or a previously configured `authRequest`.
+- Connector creation does **not** mean OAuth authorization completed. Registration, PKCE redirect/callback, connector link creation, and action refresh are separate operations. They remain untested against this MCP server and are not automatically triggered.
+- Local source changes are **not** included in the npm release `@miruzero/zgpt@0.1.4` until a new version is published.
+
+## MCP action refresh: live SDK + CLI verification (2026-10-12)
+
+**VERIFIED for one authorized connection on MiruZero.** A user-supplied cURL trace was treated as evidence of the request shape rather than copied into source or the session store. Existing SDK auth/session logic supplied the access token and cookies; only the `linkId` came from the user's request. Neither bearer token, account ID, device ID nor browser fingerprint headers were hard-coded.
+
+Request contract: `POST /backend-api/aip/connectors/mcp/refresh_actions`, body `{link_id}`, `OAI-Product-Sku: CONNECTOR_SETTING`, authenticated via SDK, no automatic HTTP retry. The SDK's legacy `connector.refreshConnectorActions({linkId})` is the single request implementation; `connector.reloadCustomMcpServerActions({linkId})` delegates to it.
+
+Verified:
+- JavaScript SDK `connector.reloadCustomMcpServerActions({linkId: '<authorized-link-id>'})`: completed successfully and returned an `actions` array.
+- Windows CLI `zgpt connector reloadCustomMcpServerActions <authorized-link-id> --allow-write`: exit code **0**, response had an `actions` array containing **4 actions**.
+- Added string-argument convenience `connector.reloadCustomMcpServerActions('<authorized-link-id>')`, auto-exposed to CLI via grouped SDK dispatch.
+- Tests cover a single, non-retried POST with exact body, product-SKU header, automatic CLI write guard, both options-object and string argument support.
+
+Not verified: automatic OAuth linking, creating a connection link, or behavior for other connector accounts. No secrets were persisted from the sample cURL and no unrelated connectors were modified. The response contents and individual action names were intentionally not logged.
+
+## Connected account unlink — Settings “ยกเลิกการเชื่อมต่อ”
+
+**Implemented in SDK and automatically exposed in CLI. The real account link was NOT deleted.**
+
+The user-provided browser cURL shows a connected-account operation that is *different* from deleting the MCP server definition:
+
+- **Disconnect link:** `DELETE /backend-api/aip/connectors/links/{link_id}` (no JSON body)
+- **Delete MCP definition:** `DELETE /backend-api/aip/connectors/{connector_id}`
+- **Refresh linked actions:** `POST /backend-api/aip/connectors/mcp/refresh_actions` with `{link_id}`
+
+`zgpt.connector.disconnectConnectorLink({linkId})` delegates directly to the existing API catalog dispatcher, which binds Zero's current authorization/session and sends the CONNECTOR_SETTING product SKU. It accepts a positional string `linkId` for CLI convenience. It rejects malformed/non-link IDs before executing any HTTP request, and `retry:false` prevents replay of DELETE.
+
+```js
+const zgpt = require('@miruzero/zgpt');
+// Only run to intentionally disconnect an authorized account:
+await zgpt.connector.disconnectConnectorLink({linkId:'link_YOUR_LINK_ID'});
+```
+
+```powershell
+# Destructive: disconnect a link only when intended:
+zgpt connector disconnectConnectorLink link_YOUR_LINK_ID --allow-write
+```
+
+The CLI refuses the command without `--allow-write`. A 204 No Content response normalizes to `{success:true}`, while non-2xx statuses propagate as errors. Tests verify URL/method/no-body, existing injected auth, missing/wrong ID guards, HTTP 403, one-shot execution and CLI write approval. **Only the request shape and the mock transport behavior are verified; live deletion has deliberately not been attempted.** The supplied Bearer token, cookies, account identifiers and browser fingerprint headers were not inserted into the codebase.

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@miruzero/zgpt",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "commonjs",
   "main": "src/index.js",
   "bin": {
     "zgpt": "src/cli.js"
   },
   "scripts": {
-    "test": "node --test"
+    "start": "src/cli.js",
+    "test": "node --test",
+    "prepublishOnly": "npm test",
+    "api:rescan": "node scripts/collect-web-api.js",
+    "api:reconcile": "node scripts/reconcile-web-api.js",
+    "api:audit": "node scripts/audit-web-api.js",
+    "api:audit:live": "node scripts/audit-web-api.js --live"
   },
   "engines": {
     "node": ">=20"
@@ -21,7 +27,8 @@
   "files": [
     "src",
     "README.md",
-    "docs/architecture.md"
+    "docs/architecture.md",
+    "docs/custom-mcp-management-api.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/api/browser-observed.json

@@ -0,0 +1,82 @@
+{
+  "source": "Agent Browser v0.39.0 attached to logged-in chatgpt.com, captured read-only HTTP status metadata; no auth headers or payloads persisted",
+  "observedAt": "2026-10-12",
+  "entries": [
+    {
+      "key": "GET /backend-api/accounts/check/v4-2023-04-27",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/accounts/check/v4-2023-04-27",
+      "name": "getAccountsCheckV420230427",
+      "family": "accounts",
+      "scope": "CHATGPT_WEB",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    },
+    {
+      "key": "GET /backend-api/ps/plugins/installed",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/ps/plugins/installed",
+      "name": "getPsPluginsInstalled",
+      "family": "ps",
+      "scope": "CHATGPT_WEB_PLUGINS",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    },
+    {
+      "key": "GET /backend-api/wham/accounts/check",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/wham/accounts/check",
+      "name": "getWhamAccountsCheck",
+      "family": "wham",
+      "scope": "WORK_ACCOUNTS",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    },
+    {
+      "key": "GET /backend-api/wham/sites/access",
+      "method": "GET",
+      "client": "Request",
+      "route": "/backend-api/wham/sites/access",
+      "name": "getWhamSitesAccess",
+      "family": "wham",
+      "scope": "WORK_SITES",
+      "evidence": [
+        "AGENT_BROWSER_SESSION_NETWORK"
+      ],
+      "captureCount": 1,
+      "statuses": {
+        "200": 1
+      },
+      "verification": "LIVE_BROWSER_HTTP_200",
+      "liveStatus": 200,
+      "observedAt": "2026-10-12"
+    }
+  ]
+}

package/src/api/contracts.json

@@ -0,0 +1,101 @@
+{
+  "GET /backend-api/models/config": {
+    "requiredQuery": [
+      "slug"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_SLUG",
+    "runtimeNotes": "Frontend supplies a model slug; live GET with current model slugs returned 404 in this session, so availability remains unverified."
+  },
+  "GET /backend-api/gizmos/user_action_settings": {
+    "requiredQuery": [
+      "gizmo_id"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_GIZMO_ID",
+    "runtimeNotes": "Requires a valid GPT identifier. No permitted GPT ID was available in the tested bootstrap response."
+  },
+  "GET /backend-api/apps/directory/browse": {
+    "requiredQuery": [
+      "category"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_CATEGORY; LIVE_200_CATEGORY_PRODUCTIVITY",
+    "runtimeNotes": "Use a category id from GET /backend-api/apps/directory/apps. Productivity returned HTTP 200 in this session."
+  },
+  "GET /backend-api/composer/items": {
+    "requiredQuery": [
+      "entrypoint"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_ENTRYPOINT; LIVE_200_ENTRYPOINT_CHAT",
+    "runtimeNotes": "The saved web callsite also sends limit and sometimes timezone; the server required entrypoint. entrypoint=chat&limit=10 returned HTTP 200."
+  },
+  "GET /backend-api/images/prompt-items": {
+    "requiredQuery": [
+      "surface"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_QUERY; LIVE_422_MISSING_SURFACE; LIVE_200_SURFACE_SKETCH_FOLLOWUPS",
+    "runtimeNotes": "The web source passes surface=sketch_followups; live result was HTTP 200."
+  },
+  "POST /backend-api/aip/connectors/mcp": {
+    "requiredBodyFields": [
+      "name",
+      "auth_request"
+    ],
+    "bodyAnyOf": [
+      "mcp_url",
+      "tunnel_id"
+    ],
+    "contractEvidence": "OSSGPT_WEB_ONSUBMIT_CUSTOM_MCP; STATIC_WEB_SAFEPOST",
+    "runtimeNotes": "Create connector definition; no write-side effects tested. Browser UI sends name, description, logo_url, either mcp_url or tunnel_id, optional custom_headers, and auth_request with supported_auth/oauth_client_params/default_scopes/oidc_enabled/use_cimd. Linking/OAuth occurs in a subsequent flow."
+  },
+  "PATCH /backend-api/aip/connectors/{id}/name": {
+    "requiredBodyFields": [
+      "name"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPATCH",
+    "runtimeNotes": "Path connector_id, requestBody {name}. Not live-tested against user data."
+  },
+  "PATCH /backend-api/aip/connectors/{id}/description": {
+    "requiredBodyFields": [
+      "description"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPATCH",
+    "runtimeNotes": "Path connector_id, requestBody {description}; empty description is permitted for clearing. No live mutation test."
+  },
+  "PATCH /backend-api/aip/connectors/{id}/logo": {
+    "requiredBodyFields": [
+      "logo_url"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPATCH",
+    "runtimeNotes": "Path connector_id, requestBody {logo_url}; actual upload step is separate. No live mutation test."
+  },
+  "DELETE /backend-api/aip/connectors/{id}": {
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEDELETE",
+    "runtimeNotes": "Destructive removal of connector definition; never automatically executed by audit."
+  },
+  "DELETE /backend-api/aip/connectors/links/{id}": {
+    "contractEvidence": "USER_PROVIDED_BROWSER_CURL; SDK_MOCK_TEST",
+    "runtimeNotes": "Unlinks a connected account by link_id from ChatGPT Settings. No request body. Requires authenticated session and CONNECTOR_SETTING product SKU. Distinct from deleting the MCP connector definition. Never run against a live link without an explicit unlink instruction."
+  },
+  "POST /backend-api/aip/connectors/mcp/refresh_actions": {
+    "requiredBodyFields": [
+      "link_id"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPOST; EXISTING_CONNECTOR_TEST",
+    "runtimeNotes": "Refresh action list by link_id, NOT connector_id. Side-effecting command; not executed live."
+  },
+  "POST /backend-api/aip/connectors/mcp/oauth_config": {
+    "bodyAnyOf": [
+      "mcp_url",
+      "tunnel_id"
+    ],
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEPOST",
+    "runtimeNotes": "RequestBody {mcp_url,custom_headers} or {tunnel_id,custom_headers}; response.oauth_config; potentially queries remote server. Not executed live."
+  },
+  "GET /backend-api/aip/connectors/mcp/tunnels": {
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEGET; LIVE_SDK_HTTP_200",
+    "runtimeNotes": "Read-only GET returned HTTP 200 with a tunnels array in this session."
+  },
+  "GET /backend-api/aip/connectors/{id}": {
+    "contractEvidence": "STATIC_OSSGPT_WEB_SAFEGET",
+    "runtimeNotes": "Read connector by id; requires authorized connector_id and may include actions. Not probed with user ID."
+  }
+}