docs: Refine documentation for workflow recovery and tool alignment

.gitignore

@@ -23,4 +23,5 @@ yarn-error.log*
 # others
 .env*.local
 .vercel
-next-env.d.ts
+next-env.d.ts
+.env*

API-REFERENCE-REVIEW.md

@@ -0,0 +1,28 @@
+# REST API reference review — September 28, 2026
+
+## Scope and evidence
+
+Extended the existing Fumadocs API section with authentication/workspace guidance, workflows, executions, authoring, errors/retries, a complete endpoint index, endpoint pages, and a downloadable OpenAPI reference snapshot. Preserved existing introduction and CLI URLs.
+
+Reviewed application source at `3782e045` in `/Users/julianpatrick/Developer/innflow`: all customer-facing `/api/v1` route handlers, shared API contracts, bearer/workspace authentication, proxy limits, response replay, and authoring operation receipts. Coverage is 25 HTTP operations. The portal event service-ingestion route and non-public application routes are outside customer API coverage.
+
+Live read-only checks found the application OpenAPI endpoint reachable and serving the core subset. This is not an authenticated end-to-end test of every endpoint or proof that gated authoring is enabled in production.
+
+## Corrections
+
+- Explicit workspace selection: `personal` restricts personal resources; omission retains legacy user-owned scope.
+- Core create/import/duplicate/execute response replay is distinct from authoring transaction receipts. Deploy/undeploy do not have API-key response replay.
+- Execution dispatch is not completion; use the returned execution ID.
+- Read graph connections differ from import index-based edges.
+- Rate-limit proxy errors differ from application error envelopes.
+
+## Validation
+
+- `npm run api:source-check`: passed, all 25 operations and recorded source fingerprints.
+- `npm run check`: passed.
+- `npm run build`: passed.
+- `npm run verify`: passed, 91 content pages and 113 local targets, navigation, search, and 404 behavior.
+- `git diff --check`: passed.
+- `npm run docs:check`: existing generated integration-tool reference/snapshot drift against current app source. The REST reference does not change that catalog; no unrelated tool catalog regeneration was included.
+
+Public MDX is not an input to the app's current Copilot retrieval corpus. No Qdrant update or application deployment is required for these documentation changes.

content/docs/api-reference/authentication.mdx

@@ -0,0 +1,80 @@
+---
+title: 'Authentication and errors'
+description: 'API keys, workspace permissions, retries, pagination and rate limits'
+---
+
+## API keys
+
+Create an API key under **Settings → API Keys**. Send it with every authenticated REST request:
+
+```http
+Authorization: Bearer inf_sk_your_key
+```
+
+Keep keys on your server. Do not embed them in browser JavaScript, commit them to a repository or include them in public URLs. [Manage API keys](/features/api-keys).
+
+The CLI can also use a browser-login session token. MCP OAuth uses the same routes with its own scopes and contract behavior; see [authoring](/api-reference/authoring).
+
+## Workspaces and permissions
+
+Select a workspace explicitly. `X-Innflow-Workspace: personal` restricts resource reads to your personal workspace. Omitting the header uses legacy user-owned resource scope, which can also include organization resources you created. To select an organization you belong to, pass its ID:
+
+```http
+X-Innflow-Workspace: organization_id
+```
+
+Use [List workspaces](/api-reference/endpoints/list-workspaces) to discover IDs and roles. Permission checks are endpoint-specific: workflows use read/write/execute actions; execution reads use `executions:read`; workspace discovery uses `workspaces:read`. Organization members with read-only roles cannot mutate or execute workflows. A key does not grant access to another user's resources.
+
+## Request and response format
+
+Send `Content-Type: application/json` with JSON bodies. Most successful responses wrap results in `data`. List workflows and List executions also return `pagination` with `page`, `pageSize`, `totalCount` and `totalPages`. Their default page size is 20 and maximum is 100.
+
+Catalog and log endpoints use `data.items` with `nextPage`; field options and payloads use `nextCursor`. Follow the endpoint-specific format rather than assuming one pagination envelope for every route.
+
+## Idempotency and retries
+
+| Operations | API-key behavior |
+| --- | --- |
+| Create, import, duplicate, execute | Optional `Idempotency-Key`; matching requests replay saved responses for 24 hours |
+| Graph patch, trigger configuration | Required operation key; receipts are transactional |
+| Update, delete, deploy, undeploy | No generic idempotency replay guarantee |
+
+Optional keys have a maximum length of 200 characters. Required authoring keys must contain 1–200 letters, digits, dots, colons, underscores or hyphens. Reusing a key with a different request body returns `409`. Replays include `X-Idempotent-Replayed: true`. Keys are scoped to the authenticated principal, workspace and route.
+
+For ordinary optional-key writes, expired receipts can be replaced after 24 hours. For transactional authoring, an expired receipt returns `IDEMPOTENCY_EXPIRED`; inspect the workflow before starting another operation.
+
+Optional-key response replay is not an exactly-once guarantee: concurrent first requests or a failure before receipt persistence can repeat work. Serialize retries and inspect ambiguous outcomes.
+
+On a network failure, retry eligible writes with the same key and the exact same body. Use backoff for reads and honor `Retry-After` on rate limits. Inspect resource state before repeating a write without idempotency support.
+
+## Errors
+
+Application handler errors generally include:
+
+```json
+{
+  "error": "Workflow not found",
+  "code": "NOT_FOUND",
+  "requestId": "request_identifier"
+}
+```
+
+Some errors include `details`. Handler responses include `X-Request-Id`; retain it when asking support about a request. Proxy failures can have a different envelope.
+
+| Status | Meaning and action |
+| --- | --- |
+| 400 | Invalid JSON, parameters, cursor or missing required idempotency key; correct the request |
+| 401 | Missing/invalid credentials or unavailable workspace; check key and workspace |
+| 403 | Insufficient permission or workspace role |
+| 404 | Resource not found or not accessible to this principal |
+| 409 | Idempotency or revision conflict; inspect state before retrying |
+| 422 | Configuration or workflow state does not allow the operation |
+| 429 | Rate limited; wait for `Retry-After` |
+| 500 | Unexpected server failure; retain request ID and retry only when safe |
+| 503 | Authoring unavailable when code is `AUTHORING_DISABLED` |
+
+## Rate limits
+
+The application proxy currently applies 60 requests per minute per client IP and route pathname to `/api/v1`. This is a process-local guard, not a guaranteed account-wide quota. Additional credential or infrastructure limits may apply.
+
+Proxy responses expose `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix milliseconds). A proxy `429` also includes `Retry-After` in seconds. Build clients around response headers rather than a fixed request rate.

content/docs/api-reference/authoring.mdx

@@ -0,0 +1,45 @@
+---
+title: 'Workflow authoring'
+description: 'Discover schemas, edit graphs safely and configure triggers through REST'
+---
+
+## Check availability
+
+Read [Get authoring context](/api-reference/endpoints/authoring-context). Graph patching and trigger configuration require `authoringEnabled: true`; unavailable authoring returns `503 AUTHORING_DISABLED`. This documentation release does not enable authoring on your deployment.
+
+## Build from the node catalog
+
+1. [Search node types](/api-reference/endpoints/list-node-types) to find a type and its operations.
+2. [Get its schema](/api-reference/endpoints/get-node-type) for field definitions, outputs and connection handles.
+3. [List connections](/api-reference/endpoints/list-connections) using the provider ID returned by the schema. Connect new accounts through Innflow's UI.
+4. [Create a workflow](/api-reference/endpoints/create-workflow) or [import a complete graph](/api-reference/endpoints/import-workflow).
+5. [Get the workflow](/api-reference/endpoints/get-workflow) and retain `graphRevision` as `expectedRevision`.
+6. [Patch the graph](/api-reference/endpoints/patch-graph) with a unique `Idempotency-Key` and up to 25 operations.
+7. [Configure triggers](/api-reference/endpoints/configure-trigger), then [validate](/api-reference/endpoints/validate-workflow) before deploying.
+
+## Graph operations
+
+| Operation | Required fields beyond operation |
+| --- | --- |
+| `addNode` | `ref`, `type`; optional `name`, `position`, `data` |
+| `configureNode` | `nodeId`, `data` |
+| `removeNode` | `nodeId` |
+| `moveNode` | `nodeId`, `position` |
+| `connect` | `source`, `target`; optional `sourceHandle`, `targetHandle` (default `main`) |
+| `disconnect` | `source`, `target`; optional `sourceHandle`, `targetHandle` (default `main`) |
+
+Temporary `ref` values identify added nodes within a patch; the response's `nodeIds` maps them to saved IDs. Read the full [graph request schema](/api-reference/endpoints/patch-graph) for constraints. Use handles returned by the node schema.
+
+A revision conflict means another edit occurred. Refetch the graph, reconcile the intended change and submit with the new revision and a new operation key. Do not blindly overwrite another editor's work.
+
+## Provider setup and execution
+
+A trigger response can report `needs_input`, `provider_handoff` or `pending` rather than `configured`. Inspect `persisted`, `missing` and `instructions` before treating setup as complete. Dynamic field selectors may return `handoffUrl` for editor-only setup.
+
+Execution is asynchronous. Use the execution ID to read progress and the operation ID, when returned, to inspect its dispatch receipt.
+
+## MCP OAuth contract
+
+MCP clients authenticate with OAuth and send `X-Innflow-MCP-Contract: 1`. On that authenticated contract, create, deploy, undeploy and execute use transactional operation receipts with a required idempotency key. Setting the header on a normal API-key request does not switch it into the MCP OAuth contract.
+
+MCP deploy/undeploy accept an optional nonnegative `expectedRevision`. MCP execution and deferred deployment work can return `202`, with `operationId` and `idempotencyKey` alongside `data`. Poll [Get operation receipt](/api-reference/endpoints/get-operation). These semantics differ from the normal API-key endpoints; see the [MCP reference](/mcp) for client setup.

content/docs/api-reference/endpoints/authoring-context.mdx

@@ -0,0 +1,34 @@
+---
+title: 'Get authoring context'
+description: 'GET /mcp/context'
+---
+
+Inspect the authenticated principal and authoring availability.
+
+
+```http
+GET /api/v1/mcp/context
+```
+
+**Permission:** `workflows:read`. Write endpoints also require a workspace role that permits changes. See [authentication](/api-reference/authentication) and [errors](/api-reference/errors).
+
+## Request
+
+```bash
+curl --request GET 'https://app.innflow.ai/api/v1/mcp/context' \
+  --header "Authorization: Bearer $INNFLOW_API_KEY"
+```
+
+Examples use placeholder IDs. Set `INNFLOW_API_KEY` in your shell and replace IDs with your own before sending a request.
+
+## Parameters
+
+| Name | In | Required | Details |
+| --- | --- | --- | --- |
+| `X-Innflow-Workspace` | header | No | Organization ID, or personal. Set explicitly; omission uses legacy user-owned resource scope. |
+
+## Response
+
+**HTTP 200** — Returns data with workspace, userId, role, permissions, authoringEnabled and contractVersion. Check authoringEnabled before graph or trigger mutations.
+
+See [OpenAPI download](/openapi.json) for the machine-readable request contract and [errors](/api-reference/errors) for errors and retry behavior.

content/docs/api-reference/endpoints/configure-trigger.mdx

@@ -0,0 +1,78 @@
+---
+title: 'Configure trigger'
+description: 'POST /workflows/{workflowId}/trigger'
+---
+
+Configure a trigger on a saved graph using its nodeId and expectedRevision. Requires authoring to be enabled. Configuration fields depend on the trigger type; obtain its node schema first.
+
+
+```http
+POST /api/v1/workflows/{workflowId}/trigger
+```
+
+**Permission:** `workflows:write`. Write endpoints also require a workspace role that permits changes. See [authentication](/api-reference/authentication) and [errors](/api-reference/errors).
+
+## Request
+
+```bash
+curl --request POST 'https://app.innflow.ai/api/v1/workflows/workflow_id/trigger' \
+  --header "Authorization: Bearer $INNFLOW_API_KEY" \
+  --header "Idempotency-Key: unique-request-001" \
+  --header "Content-Type: application/json" \
+  --data '{
+  "nodeId": "node_id",
+  "expectedRevision": 0,
+  "config": {}
+}'
+```
+
+Examples use placeholder IDs. Set `INNFLOW_API_KEY` in your shell and replace IDs with your own before sending a request.
+
+## Parameters
+
+| Name | In | Required | Details |
+| --- | --- | --- | --- |
+| `workflowId` | path | Yes | Resource identifier. |
+| `X-Innflow-Workspace` | header | No | Organization ID, or personal. Set explicitly; omission uses legacy user-owned resource scope. |
+| `Idempotency-Key` | header | Yes | Required operation key: 1–200 letters, digits, dots, colons, underscores or hyphens. |
+
+## JSON body
+
+Required JSON body.
+```json
+{
+  "type": "object",
+  "properties": {
+    "nodeId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "pattern": "^[A-Za-z0-9_-]+$"
+    },
+    "expectedRevision": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "config": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    }
+  },
+  "required": [
+    "nodeId",
+    "expectedRevision",
+    "config"
+  ],
+  "additionalProperties": false
+}
+```
+
+## Response
+
+**HTTP 200** — Returns data with status (configured, needs_input, provider_handoff or pending), persisted, revision, nodePatch and optional missing/instructions. The envelope includes operationId and idempotencyKey. Follow handoff instructions if provider setup is needed.
+
+See [OpenAPI download](/openapi.json) for the machine-readable request contract and [errors](/api-reference/errors) for errors and retry behavior.

content/docs/api-reference/endpoints/create-workflow.mdx

@@ -0,0 +1,54 @@
+---
+title: 'Create workflow'
+description: 'POST /workflows'
+---
+
+Create a draft workflow with an initial node. An omitted or empty name uses the default untitled name.
+
+
+```http
+POST /api/v1/workflows
+```
+
+**Permission:** `workflows:write`. Write endpoints also require a workspace role that permits changes. See [authentication](/api-reference/authentication) and [errors](/api-reference/errors).
+
+## Request
+
+```bash
+curl --request POST 'https://app.innflow.ai/api/v1/workflows' \
+  --header "Authorization: Bearer $INNFLOW_API_KEY" \
+  --header "Idempotency-Key: unique-request-001" \
+  --header "Content-Type: application/json" \
+  --data '{
+  "name": "Customer onboarding"
+}'
+```
+
+Examples use placeholder IDs. Set `INNFLOW_API_KEY` in your shell and replace IDs with your own before sending a request.
+
+## Parameters
+
+| Name | In | Required | Details |
+| --- | --- | --- | --- |
+| `X-Innflow-Workspace` | header | No | Organization ID, or personal. Set explicitly; omission uses legacy user-owned resource scope. |
+| `Idempotency-Key` | header | No | Optional replay key, at most 200 characters. Same request and key replay for 24 hours. |
+
+## JSON body
+
+Optional JSON body.
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string"
+    }
+  }
+}
+```
+
+## Response
+
+**HTTP 201** — Returns data with id, name, icon, iconColor, deploymentStatus, deployedAt, createdAt and updatedAt.
+
+See [OpenAPI download](/openapi.json) for the machine-readable request contract and [errors](/api-reference/errors) for errors and retry behavior.

content/docs/api-reference/endpoints/delete-workflow.mdx

@@ -0,0 +1,35 @@
+---
+title: 'Delete workflow'
+description: 'DELETE /workflows/{workflowId}'
+---
+
+Delete a workflow and its execution history. This is destructive.
+
+
+```http
+DELETE /api/v1/workflows/{workflowId}
+```
+
+**Permission:** `workflows:write`. Write endpoints also require a workspace role that permits changes. See [authentication](/api-reference/authentication) and [errors](/api-reference/errors).
+
+## Request
+
+```bash
+curl --request DELETE 'https://app.innflow.ai/api/v1/workflows/workflow_id' \
+  --header "Authorization: Bearer $INNFLOW_API_KEY"
+```
+
+Examples use placeholder IDs. Set `INNFLOW_API_KEY` in your shell and replace IDs with your own before sending a request.
+
+## Parameters
+
+| Name | In | Required | Details |
+| --- | --- | --- | --- |
+| `workflowId` | path | Yes | Resource identifier. |
+| `X-Innflow-Workspace` | header | No | Organization ID, or personal. Set explicitly; omission uses legacy user-owned resource scope. |
+
+## Response
+
+**HTTP 200** — Returns data with id and deleted: true.
+
+See [OpenAPI download](/openapi.json) for the machine-readable request contract and [errors](/api-reference/errors) for errors and retry behavior.