docs(website): add month-end close capstone tutorial

[arantespp]

Summary

Adds Close the Monthly Books, a capstone tutorial that composes an orchestration, a workflow, a trigger, and a human approval into one governed process.

The eight existing graph tutorials each teach a single mechanism, almost all of them in the sonnet/poem domain. Two gaps followed from that: nothing showed the layers working together, and no tutorial used a domain where the branch condition has a right answer — so every assertion could only ever be status == succeeded.

A financial close fixes both. Every routing decision in the graph is JSON Logic arithmetic over ledger figures, so the same books always take the same path and the tutorial can assert the business outcome (bank_variance == 1250) rather than just the plumbing. The single agent node writes a variance memo, declares no output_schema, and nothing downstream parses its text — the model gets the last word on wording, never on control flow.

What it demonstrates

• Three reconciliations as parallel start nodes converging on an activation_group join with activation_condition: "all"
• A condition node routing on computed variance vs. tolerance, with the untaken branch recorded as skipped
• validate-orchestration as a pre-flight check before create
• A workflow with a backward transition (request_rework) — the concrete reason a close period is not a DAG
• One transition carrying both gates: a deterministic guard first, then requires_approval, so a human is only asked about something the arithmetic already accepted
• The same approvals queue serving a workflow transition rather than an orchestration node
• Manual and schedule triggers, and the task transition history as an audit trail

It also documents a contract that was previously only discoverable from the validator source: run input reads as {"var": "input.x"}, while a bare {"var": "x"} reads a state key an upstream node wrote and is never satisfied from run input.

Changes

File	Change
docs/tutorials/close-the-monthly-books.md	New tutorial, 12 steps, CLI/SDK/curl tabs throughout
sidebars.ts	Added to the Orchestration & Multi-Agent category
docs/tutorials/index.md	New capstone routing line
docs/modules/orchestrations.md	Related-tutorial deep link (Step 4)
docs/modules/workflows.md	Related-tutorial deep link (Step 8)
docs/modules/approvals.md	Related-tutorial deep link (Step 11)

No product code changes.

Design decisions

Recorded per the open-questions rule:

Q: New tutorial, or rewrite an existing one?
A: New — resolved by long-term. orchestrate-a-sonnet is a hub with ~12 deep
   step-anchor links from five module pages, so a domain rewrite there breaks
   them. orchestrate-a-sonnet-with-workflows is cheap to rewrite (3 refs, no
   anchors) but is one leg of a deliberate same-domain comparison triple, and
   a four-layer composition doc cannot serve as the minimal workflows entry
   point workflows.md links to. Checked: inbound link graph for both files.

Q: Which domain?
A: Month-end close — resolved by long-term (durability ladder: business rules
   become deterministic JSON Logic assertions rather than prose or LLM
   judgement). Checked: no existing tutorial uses a customer-financial domain,
   and create-an-agent-squad proves role-agent graphs pass CI when no agent
   node declares output_schema.

Q: Include a rendered graph diagram?
A: ASCII, not mermaid — resolved by pareto. Checked: @docusaurus/theme-mermaid
   is not installed and mermaid is unconfigured in docusaurus.config.ts, so a
   ```mermaid fence renders as a plain code block. Adding the dependency is a
   separate change and does not belong in a docs PR.

Verification

• node scripts/docs-lint.mjs — OK, 80 files, no violations
• pnpm --filter @soat/website build — exit 0, no broken links or anchors (it caught one bad anchor, workflows#tasks, now workflows#task)
• Static checks on the extracted CLI blocks: all 8 multi-line JSON payloads parse after shell interpolation; single-quote parity even in every block (this caught an apostrophe in a bash comment — run's — which would have desynced the tutorial runner's line accumulator); all 13 <Tabs> groups carry cli/sdk/curl; every step has an inline doc link; no unbacketed braces that MDX would parse as JSX
• Every command, field name, HTTP verb, and ID prefix cross-checked against src/rest/openapi/v1/*.yaml and PUBLIC_ID_PREFIXES. Three inferences were wrong and were corrected: getTaskHistory returns a bare array (not {data}), the history field is principal_kind (not principal), and updateTask is PATCH (not PUT).

Not verified locally: the Docker daemon is unavailable in this environment, so the tutorial was never executed against a live server. The tutorial is deliberately not added to tests/.tutorialsignore, so the tutorials-test job is the verifier — please treat a red run there as the real signal, and note that qwen2.5:0.5b only touches the exception branch in Step 6.

Example IDs in expected output use the elided orch_run_... form rather than invented literals, matching approval-gate.md.

Follow-ups (not in this PR)

• orchestrate-a-sonnet-with-workflows stays in .tutorialsignore; its async on_enter dispatch needs # → retry N on the forward-progress steps. Separate PR whose only real deliverable is the CI signal.
• That file also uses SOAT_URL in its curl tabs and has no SDK tab, both against .claude/rules/tutorials.md.
• Wiring up @docusaurus/theme-mermaid would let the graph diagrams in this and the other orchestration tutorials render properly.

Related: #872, #873, #877

🤖 Generated with Claude Code

https://claude.ai/code/session_01AjeWpxDqRDtkSv1mCDspf9

---

Generated by Claude Code

[github-actions]

Deploy Outputs

Package	Stack	Output Key	Output Value
@soat/website	SoatWebsite-claude-soat-graphed-system-z169oo	BucketWebsiteURL	http://soatwebsite-claude-soat-graphed-syste-staticbucket-g5l9mzjqlbtg.s3-website-us-east-1.amazonaws.com