docs: document SDK v1 routes, app bundle export, and JS script run

[claude]

Eight HTTP routes had no user-facing documentation. Each is now in the
docs/api-reference.md endpoint matrix with a worked section, and the two
environment flags that switch them off are in the docs/configuration.md
index.

Every request and response in this PR was captured from a running server
(packages/websocket/dist/server.js), not read off the handlers and
written up. Where the code and the server disagreed with my first draft,
the server won — see Corrections below.

Gaps filled

Gap	Where it went	Read from
GET /api/sdk/v1/capabilities	api-reference.md § What This Server Supports	sdk/sdk-capabilities-service.ts, server.ts:1096-1119
GET /api/sdk/v1/node-types	api-reference.md § The Node Type Inventory	http-api.ts:handleSdkNodeTypeInventory, node-sdk/src/node-type-inventory.ts
GET /api/workflows/{id}/interface	api-reference.md § A Workflow's Input and Output Pins	http-api.ts:handleWorkflowInterface
POST /api/sdk/v1/workflow-interfaces	same section	http-api.ts:handleWorkflowInterfaces, protocol/api-schemas/workflows.ts
GET /api/sdk/v1/workflows	same section	http-api.ts:handleSdkWorkflowSummaries
POST /api/sdk/v1/preflight	api-reference.md § Checking a Workflow Before Running It	sdk/sdk-preflight-*.ts, protocol/api-schemas/sdk-lifecycle-v1.ts
POST /api/sdk/v1/assets/temporary	api-reference.md § Uploading an Execution Input	sdk/sdk-temporary-asset-upload-http-handler.ts
GET /api/applications/{id}/export-bundle	api-reference.md § Exporting an App as a Bundle	routes/applications.ts:242, app-runtime/src/bundle.ts
POST /api/js-scripts/{id}/run	api-reference.md § Running a Saved JS Script	routes/js-scripts.ts, protocol/api-schemas/js-scripts.ts

Plus three env vars in docs/configuration.md, because they gate the routes
above and explain the 503s: NODETOOL_DISABLE_SDK_LIFECYCLE_V1,
NODETOOL_DISABLE_SDK_WORKFLOW_INTERFACE_V1, NODETOOL_REQUIRE_SDK_AUTH_V1
(sdk/sdk-feature-flags.ts, sdk/sdk-route-policy.ts, server.ts:889-901).

Corrections the server forced

Four things I would have documented wrongly from reading the code alone:

• profiles does not track the disable flags. It is a hard-coded literal
  in server.ts that always reports available. A server with
  NODETOOL_DISABLE_SDK_WORKFLOW_INTERFACE_V1=1 still advertises
  discovery: "available" and then answers 503. The doc now says to handle
  the 503 rather than gate on profiles.
• The two flags cover different route sets. I first wrote that the
  lifecycle flag gates everything under /api/sdk/v1/*. Running each flag
  alone showed node-types and workflows are gated by the interface flag,
  and node-types reports its own code (SDK_NODE_TYPE_INVENTORY_DISABLED).
• python_bridge never reports unavailable. The schema allows it, but
  the server only ever emits ready/starting — a box with no Python sits at
  starting forever.
• Only max_upload_bytes in limits is enforced. Nothing reads
  max_rpc_batch or request_timeout_seconds; the zeros are "no bound
  stated", not a limit of zero.

Also verified rather than assumed: ?version=1 is required on the interface
route (a 400, not a default); one bad id in a workflow-interfaces batch
lands in errors without failing the rest; a stale workflow_etag is a 200
with runnable: false, not an error; export-bundle?released=1 is a 404 on
an unpublished app where released-document is a 200 with null; and a JS
script that throws is a 200 with ok: false.

Skipped, with reasons

The four docs-facts/ lists over-report heavily. What I dropped:

• 8 of 9 "undocumented" routes were already covered under another spelling —
  released-document, extract-audio, assets/packages/*, dsl-export,
  examples/thumbnails, workflows/public/* are all in the api-reference
  matrix; /api/debug/sessions/:id/:action is documented as its concrete
  /verdict and /cancel forms. /apps/index.html is static asset serving.
• /api/integrations/:provider/* — real, but already documented in
  docs/telegram-bot-design.md §5 (spelled /api/integrations/telegram/…,
  which is why the grep missed it) and its env var is in configuration.md.
  Adding matrix rows is worth doing; it did not fit under the 8-gap cap.
• 11 of 13 "undocumented" env vars are not env vars — NODETOOL_API_GLOBALS,
  NODETOOL_DATA_TYPES, NODETOOL_MCP_BEGIN/END, NODETOOL_PRELUDE,
  NODETOOL_PROVIDER_ID, NODETOOL_API_SECTION_HEADER and friends are
  TypeScript constants the grep matched by name. NODETOOL_TEST_CHROME and
  NODETOOL_TEST_BYTE_LIMIT are test hooks; NODETOOL_FETCH_ALL_NODE_RUNTIMES
  is a build script flag; NODETOOL_SERVER_MODE is written by
  packages/deploy and read by nothing in this repo.
• The only CLI "gap" was help, which is not a command.
• packages/app-runtime has no README — real, but a package README ranks
  below routes per the brief.

Verification

• Every curl shown was executed against a local server; the JSON bodies are
  its responses, trimmed only where noted.
• Flag behavior proven by inverting it: servers booted with each flag alone
  and with both, confirming which routes turn 503 and with which code.
• CLI cross-reference checked against nodetool apps export-bundle --help.
• All 45 JSON blocks in the page parse; tables and code fences balance.
• Markdown only — no code changed, no CI workflow touched, docs-facts/ not
  committed.

🤖 Generated with Claude Code