docs: Update workflow and Copilot documentation for clarity and recov…

CONTENT-ALIGNMENT.md

@@ -77,3 +77,56 @@ The snapshot uses standard picker availability (AI Decision disabled), not produ
 - `git diff --check` passed.
 - 28 existing content pages changed and one complete reference page was added. The audit contains 37 implemented changes plus the 53-section operation change inventory.
 - No deployment, provider execution, database change, or vector indexing was performed. These are local documentation and rendered-site results, not production verification.
+
+## Scoped follow-up — September 24, 2026
+
+This review used the Innflow working tree on top of `af96607d`, including staged
+save/service repairs, horizontal layout, and Copilot documentation changes, plus
+the latest merged product-index changes. It is a local documentation update, not
+an assertion that the pending application changes are deployed. Existing staged
+application edits were preserved. Historical findings above remain unchanged.
+
+### Change-to-document review
+
+| Behavior | Documentation result | Implementation evidence in Innflow |
+| --- | --- | --- |
+| Completed Copilot work can fail its final workflow save | Added separate Retry save/manual-save recovery, per-workflow state, conflict protection, and reload limitations to the Copilot page and lesson; aligned prompt, runtime/Markdown guide, and edit playbook | `src/features/copilot/hooks/use-copilot-chat-go.ts`, `src/features/copilot/components/copilot-chat.tsx` |
+| Saves acknowledge submitted changes while newer edits remain dirty | Replaced the unconditional autosave claim and added saving/conflict guidance to workflow essentials and lesson | `src/features/editor/components/workflow-toolbar.tsx`, `src/features/workflows/lib/save-coordinator.ts` |
+| Left-to-right layout and one-time conversion | Documented handles, branch labels, undo, retry, and read-only behavior; added the stable architecture boundary | `src/features/editor/hooks/use-horizontal-layout-migration.ts`, `src/features/workflows/server/horizontal-layout.ts` |
+| Layout metadata survives API/CLI round trips | Added canvasLayoutVersion guidance to API introduction and CLI reference | `packages/api-contracts/src/index.ts`, `packages/cli/src/program.ts`, workflow API handlers |
+| Indexing builds a candidate; promotion is separate | Removed the contradictory activation claim in ARCHITECTURE.md and clarified that public MDX is not indexed by the current product corpus | `src/features/copilot/server/product-docs/corpus.ts`, `src/features/copilot/server/product-docs/indexer.ts`, `scripts/copilot/index-product-docs.mts` |
+| Scheduler receipt cleanup and bounded Go telemetry | Existing internal repair report and architecture already describe these contracts; no new customer-facing procedure is needed | `project-checklists/observability/2026-09-24-1321-save-and-service-errors.md`, scheduler callback, Go telemetry handlers |
+| Tool operations and multiple-trigger guidance | Existing generated reference, mapped operation lists, and trigger instructions remain current; no regeneration of real outputs | `scripts/check-tool-docs.mjs` plus focused application guidance tests |
+| Authentication layout styling | No setup or authentication capability change requiring documentation in this scoped review | Current auth layout diff |
+
+Six public pages were updated. Five application documentation/guidance files
+were updated. The public routes and navigation structure are unchanged.
+
+### Release dependencies
+
+Keep the public save-recovery and layout instructions coordinated with their
+application release. Horizontal layout requires its additive database migration
+and application/outbox rollout; use the existing layout checklist. Save/service
+repairs require their existing coordinated rollout and browser/production
+acceptance. This documentation run did not apply migrations or release services.
+
+Copilot corpus inputs changed. The local dry run moved from corpus version
+`0813bbc4f0e2bedf966b7bf1d6d6a8b30fd62150a7d5446ba0b9f277d502715a`
+to `c9da98b749450dcd8288485a2c665745bf2ecf4d38d9a1505b9f379aaa9531c8`
+(177 documents, 217 chunks). Prior candidate receipts are not acceptance evidence
+for this content. After the app and Go manifest references are aligned, use the
+current `scripts/copilot/README.md` build/evaluate/promote procedure with fresh,
+uniquely named candidate/report artifacts. No remote embedding, Qdrant write,
+alias promotion, feature-flag change, commit, push, or publication was performed.
+
+### Local validation
+
+- Documentation drift check passed: 94 node entries, 309 exact operation IDs, and 53 guide operation lists/regression checks.
+- Documentation type checking and production build passed.
+- 33 focused application tests passed across trigger guidance, corpus behavior, query policy, Copilot completion/retry, and horizontal-layout migration hooks.
+- Biome passed for the two modified TypeScript guidance files.
+- Local keyword retrieval returned the new layout/save-recovery guide first for both save-failure and horizontal-layout queries. This does not measure remote hybrid retrieval or model behavior.
+- A temporary fixture deliberately made the generated reference stale: check mode rejected it, the existing generator repaired it, and check mode then passed. The real generated reference and snapshot were left unchanged.
+- The new local docs skill passed its validator and reference-link checks. This run exercised affected public/Copilot guidance, internal-only handling, already-correct documents, and preservation of overlapping staged work. It was not an independent agent evaluation.
+- Built-site verification passed for 60 content pages, navigation, 81 local targets, search, and the unknown-route 404 response.
+- Whitespace checks passed in both repositories. No full application build or production/browser acceptance run was used as documentation validation.

content/docs/academy/copilot.mdx

@@ -22,6 +22,12 @@ Ask Copilot to explain the current workflow, add a step, or help repair a specif
 
 Confirm the chosen destination, the data sent to each service, and what happens when a step fails. A helpful generated graph still needs a controlled test.
 
+## Separate completion from saving
+
+A completed Copilot response does not by itself prove that the workflow was saved. If **Workflow not saved** appears, keep the editor open and choose **Retry save**, or save from the workflow toolbar. This retries the save without asking Copilot to repeat completed actions.
+
+If saving still conflicts, preserve your edits and review the latest workflow. Reloading can discard unsaved work. See [save recovery](/features/copilot#recovering-a-failed-workflow-save) before retrying the original prompt.
+
 ## Try it
 
 Ask Copilot to explain a workflow you already understand. Then request one small change and compare the graph and configuration before running it.

content/docs/academy/workflows.mdx

@@ -23,6 +23,12 @@ A good first workflow answers a small question or transforms a sample input. Avo
 
 A connection tells the workflow which node can run next. The output of a completed node becomes available to downstream steps. A branch or loop changes the path, so test each path your process depends on.
 
+## Arrange and save
+
+Follow the canvas from left to right, connecting an output on the right of one node to an input on the left of the next. Branch labels identify the path; visual position alone does not determine execution.
+
+Before closing the editor, check that the toolbar reports **All changes saved**. Changes made during an earlier save may still need another save. If a conflict appears, preserve your work and reconcile it with the latest workflow before reloading. See [saving and conflicts](/essentials/workflows#saving-and-conflicts).
+
 ## Try it
 
 Build a Manual trigger connected to an AI node. Ask it to summarize a short sample message. Check whether the actual output matches what the next step needs before connecting an email or messaging action.

content/docs/api-reference/cli.mdx

@@ -32,6 +32,10 @@ printf '%s' "$INNFLOW_API_KEY" | npx @innflow/cli auth login --api-key-stdin
 
 Every command supports `--json` for machine-readable output. Destructive commands require confirmation unless `--yes` is provided.
 
+## Preserve workflow layout on round trips
+
+Workflow export and import preserve `canvasLayoutVersion` when present. Keep this field in a pulled definition when importing it again; an older definition without it is eligible for the editor's one-time horizontal arrangement. See [workflow layout metadata](/api-reference/introduction#workflow-layout-metadata).
+
 ## Profiles and environment variables
 
 - `INNFLOW_API_KEY` authenticates non-interactive requests.

content/docs/api-reference/introduction.mdx

@@ -57,6 +57,12 @@ Create, import, duplicate, deploy, undeploy, and execute requests support an `Id
 | `GET` | `/executions` | List executions |
 | `GET` | `/executions/{executionId}` | Read execution details and node logs |
 
+## Workflow layout metadata
+
+Workflow definitions can carry `canvasLayoutVersion` alongside their nodes and connections. Version `0` identifies a definition eligible for the editor's one-time horizontal arrangement; version `1` identifies one already using that layout version. Imports without the field default to `0`, while newly created workflows start at `1`. Duplicating a workflow preserves its value.
+
+Preserve this field when exporting and reimporting a definition. It tracks canvas arrangement separately from execution version or deployment state; importing an older definition does not rearrange it until it is opened in an editable editor. Use the current OpenAPI schema for endpoint-specific input fields.
+
 ## Execute a Workflow
 
 Workflows must be deployed before they can be executed through the API.

content/docs/essentials/workflows.mdx

@@ -30,7 +30,21 @@ The editor is a canvas where you build workflows by placing and connecting nodes
 - **Lock the canvas** — Prevent accidental movement while reviewing
 - **Add sticky notes** — Document the workflow directly on the canvas
 
-Changes autosave while you work. Use Copilot when you want to add, configure, explain, test, or repair a workflow through conversation.
+Node settings and canvas changes can save while you work. Check the toolbar's save state before leaving; use **Save workflow** when changes remain. Use Copilot to add, configure, explain, test, or repair a workflow through conversation.
+
+### Canvas layout
+
+Workflows flow left to right: inputs are on the left of each node card, and outputs are on the right. Branching nodes show separate output rows. Follow the labeled connection for the intended branch; moving a node does not change execution order.
+
+Older workflows are arranged once when first opened in an editable canvas. This changes positions, not configuration, connections, or deployment state. You can undo the arrangement as one change and continue positioning nodes yourself. Read-only previews do not initiate this conversion. If arranging fails, the editor releases the canvas and offers **Retry**; wait for pending edits or connection problems to clear before retrying.
+
+### Saving and conflicts
+
+A successful save covers the changes submitted with that save. New edits made while saving can still leave the workflow marked unsaved. Saving a draft is separate from deploying or running it.
+
+If saving reports that the workflow changed, preserve your unsaved work before reloading. Another tab or collaborator may have changed the stored workflow; repeating the same save does not merge conflicting edits. Review the latest version and reconcile your changes instead of overwriting it.
+
+If Copilot finishes but the workflow cannot be saved, use the separate [save recovery controls](/features/copilot#recovering-a-failed-workflow-save).
 
 ## Execution Flow
 

content/docs/features/copilot.mdx

@@ -61,6 +61,17 @@ Copilot supports:
 
 Live workflow state takes precedence over saved conversation memory.
 
+## Recovering a failed workflow save
+
+If Copilot finishes its work but the final workflow save fails, **Workflow not saved** appears with a **Retry save** button. The completed response and canvas edits remain available in the open editor.
+
+- Choose **Retry save** to retry persistence without rerunning your message or its tools.
+- You can also use the workflow toolbar to save. A successful manual save clears the Copilot save warning.
+- If you switch workflow tabs, return to the affected workflow to recover its save. Each workflow keeps its own recovery state.
+- A revision conflict still needs reconciliation; retrying does not overwrite another editor's changes.
+
+Keep the editor open until saving succeeds. The browser warns when leaving with a pending Copilot save failure, but that warning is not a backup: ignoring it and reloading can discard unsaved edits. This recovery applies to workflow saving; generation failures and conversation-history save failures have their own error controls.
+
 ## Test & Repair
 
 When Test & Repair is enabled for the deployment, Copilot can start a real workflow execution after you approve the warning. A session can make up to three real attempts and can automatically change only explicitly safe configuration fields.