> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UPSTREAM FINDINGS

# Upstream findings from the docs verification pass (2026-08-31)

Everything below was found while grounding docs.stateset.com in each server's source and live
behaviour, and is **already worked around in the docs** (spec overlays in `spec/overlays/`,
generated pages, or corrected prose). Fixing it upstream lets the overlays shrink to zero and
keeps the published contracts honest at the source. One section per repo — each item is
paste-ready for an issue.

## stateset-sync-server

* **`src/openapi.rs` references 67 component schemas it does not export** (`JobQueuedResponse`,
  `WebhookResponse`, `PaginatedResponse`, `Order`, `ScheduleInfo`, …): 67 operations' responses
  dangle, and 28 request bodies with them. The docs type them from the handler structs
  (`spec/overlays/sync.json`) — the fix is registering the types in `components(schemas(...))`.
* `docs/SHOPIFY_NETSUITE_GETTING_STARTED.md` predates `POST /sync/netsuite` and says there is no
  built-in Shopify→NetSuite job; the code has one. The doc points at ACP instead.

## next-temporal-rs

* **`GET /v1/workflows/order-fulfillment/{id}/status` returns `Json<String>`**
  (`"<status>:<phase>"`), while `docs/openapi.yaml` declares `WorkflowStatusResponse`.
* **`BRANDED_WORKFLOW_PREFIXES` in `events.rs` omits `order-fulfillment-`**, so a brand-scoped
  key gets 400 on the event stream for its own workflow; the docs tell readers to use a global
  key as a workaround.
* \~137 operations are `GenericObject` in the exported spec, and 33 signal/cancel routes list a
  `200` they never return (they answer `202`; api-key revoke answers `204`).

## stateset-phone-server (rust-phone-server)

* **utoipa declares bare arrays for four list endpoints** (`/callback-tasks`, `/operator-queues`,
  `/operator-queues/stats`, `/supervisor-actions`) whose handlers wrap in
  `{ok, tenant, count, …}` envelopes.
* The published spec covers 61 tenant paths but not the agent-management plane
  (`/voice/agents`, `/voice/phone-numbers`, `/voice/web-calls`, `/voice/calls`, `/api-keys`)
  that `VOICE_ENGINE_API.md` documents and the server serves.

## stateset-sandbox

* **The live `/openapi.json` (43 ops) omits six routes the server serves behind auth**
  (tunnels ×3, inference, files/list, files/download, create-from-template — all verified 401).
* **Registered paths vs express routers disagree in the checkout**: OpenAPI registers
  `/files/write` and `/files/read`; the routers in the current source serve those operations at
  `POST/GET /sandbox/:id/files`. The live deploy answers both styles — the build and the
  checkout have drifted.
* `POST /api/v1/webhooks` returns `200`; its own spec declares `201`.

## stateset-nsr

* `POST /api/v1/model/export` is an always-`501` (`model_handlers.rs`); `ExportModelResponse`
  is dead code. The docs document the 501 honestly.
* The spec's `/v1/decisions` responses do not list the `503` fail-closed path that
  `errors.rs` implements and the product story depends on.
* Several NSR spec parameters are declared `in: path` for what the handlers read as query.

## stateset-computer-use-agent

* The approval gate (`ApprovalPolicy`/`ApprovalRequest`, `awaiting_approval`) is fully specified
  in the API models and routes, but nothing in `worker.py`/`agent/` constructs an
  `ApprovalRequest` — the pause may not be wired in the deployed worker.
* `api.computer.stateset.app` answers 503 on every path (docs mark it "being provisioned").

## stateset-agents

* `spec/sdk-surface.json` in the docs pins `@stateset/cli` 1.28.0; source is 1.28.1 (surface
  identical). The skill's `stateset heartbeat …` example is accepted as natural language but no
  heartbeat tool exists in `src/tools`.
* The API's own spec `servers` list names `api.stateset.io` / `staging-api.stateset.io`,
  neither of which serves this API.

## stateset-edi

* `stateset-edi/overview.mdx` (docs, fixed) showed a JSON response for outbound 810; the
  handler returns wire-ready X12 (`application/edi-x12`). Upstream: the utoipa annotation for
  `GET /v1/usage` claims bare `UsageSummary`; the handler wraps it in `{success, data, period}`.

## response-chat-widget

* `package.json` says `response-chat-widget` / the admin docs imply `@stateset/…` naming; the
  package is unpublished either way. The widget's `docs/ADMIN-API.md` route table is accurate
  (verified against `src/server/admin`).

## Packages referenced by docs but not on npm (\~16)

`@stateset/icommerce-skills` (repo name `icommerce-skills` — align before publishing),
`@stateset/cctp-sdk`, `stateset-cctp`, `@stateset/client`, `@stateset/agent-sdk`,
`@stateset/acp`, `@stateset/types`, `ss-onboard-agent`, and friends. Every referencing page
carries a "not yet published" note; this list is the publish checklist.

## Platform

* `status.stateset.com` is a 404 (docs now link the probed
  [host-status page](https://docs.stateset.com/api-reference/hosts) instead).
* `prod-api.stateset.cloud.stateset.app` (another session pointed `api-reference/v1/*` at it)
  answers 503 — when it goes live, the docs adopt it (see `memory: prod-api-host-candidate`).
* `kb.stateset.com` serves 401 on every path including `/openapi.json` — a real service with
  no public contract; decide whether it is integrator-facing.