docs(user-guide): correct workflow authoring reference against the engine

[8nevil8]

Summary

The workflow configuration guide was audited line by line against the execution engine, using a production workflow (MR Compliance Review, 25 states) as ground truth. This PR corrects the places where the guide described behaviour the platform does not have, and documents behaviour it does have but never described.

The largest gap was conditional transitions. A condition or switch expression is evaluated only against the parsed output of the state that declares it — the context store is not in scope. When a referenced name is undefined the expression does not fail loudly: it evaluates to false, the otherwise branch is taken, and the execution reports success. A misspelled variable therefore produces a workflow that runs green and routes the wrong way every time. Neither the scope rule nor the swallowed-failure behaviour was documented.

Changes

• Conditional transitions — added the scope rule with a worked counter-example, and an "Every Failure Routes to otherwise" table covering undefined names, typos, missing methods, type mismatches and rejected constructs, with the log lines to grep for. Corrected the syntax reference: the evaluator is an AST allowlist, not Python's eval(); .contains() is not a string method; comprehensions and lambdas are rejected. Added the Python True/False literal rule.
• Iteration properties — documented finish_iteration, override_task and include_in_iterator_context, none of which appeared anywhere in the docs. The last is the only escape hatch when copying the whole context store into N parallel branches overruns the execution checkpoint size limit.
• output_schema — documented that it accepts two different things with two very different guarantees: a real JSON Schema switches the assistant into enforced structured output, while an example shape is prompt guidance only. Added result_as_human_message. Corrected an example claiming failed validation triggers an automatic re-prompt.
• Custom nodes — replaced the partial type list with the accepted custom_node_id values, and added a warning that the key means the node type inside custom_nodes but a reference to custom_nodes[].id inside a state. Added default_output to the Transform Node parameter table.
• Editor layout keys — documented meta_states and next.meta_next_state_id, and the rule that external tooling (API, SDK, CLI, IaC) must carry them through unchanged.
• FAQ — rewrote the AI generation entry, which described an "AutoYaml Assistant" and UI controls that were never built, against the Generate and Refine features that shipped, including the limitation that both emit assistant states only. Added a new entry for the always-takes-otherwise symptom.
• Fixed the assistant property listed as skills; the field is skill_ids, as the YAML example on the same page already showed.

Testing

• Tested locally with npm start
• All pages render correctly
• Images display properly
• Internal links work
• Sidebar navigation works

Verified by serving the production build and fetching each changed page (all HTTP 200), confirming the new sections are present in the rendered HTML, and confirming the three new cross-page anchors resolve to real heading ids: #84-transform-node, #iteration-properties, #two-modes-of-output_schema.

Quality Checks

• npm run check passes (typecheck + lint + commitlint)
• No MDX compilation errors
• No raw angle brackets (<text> must be `<text>`)
• Sidebar references document IDs (not filenames)
• Images stored locally next to content (not in static/img/)
• Commit messages follow Conventional Commits
• No secrets or credentials in documentation

npm run build also passes, which is what validates the internal links. Gitleaks ran clean via the pre-commit hook.

Additional Notes

No new pages or images, so no sidebars.ts changes were needed. Workflows are not part of the Enterprise package — confirmed by the absence of <EnterpriseFeature /> anywhere in the section and by the Enterprise features catalog — so no Enterprise markers were added.

Written to the tech-writer skill standards, including impersonal voice throughout docs/. The two faq/ files keep the second person, matching the existing FAQ corpus.

Two related defects are deliberately left undocumented, because documenting them would describe controls that do nothing. Both are accepted by config and silently ignored by the engine:

• input_source: combined on the Transform Node — the constant is defined but _extract_source_data has no branch for it, so it yields an empty source.
• max_iteration_key_output_limit — declared on the config model, defaulted to 200, read from YAML in three code paths, consumed nowhere.

Each should be either wired up or removed; they are tracked separately and are out of scope here.

[github-actions]

PR Preview Ready!

Your preview documentation is ready! Visit it here:

Preview URL: http://codemie-docs-pr-previews.s3-website.eu-central-1.amazonaws.com/pr-428/

Note: This preview URL is accessible only while connected to the company VPN.

---

This preview will be automatically updated when you push new commits to this PR.
Preview files will be deleted when the PR is closed or merged.