docs(relayflows): audit against flows v2.0.16 — corrections and missing hosted verbs
Audit of web/content/docs/relayflows/* (plus the onboarding generator comment and the /flows marketing samples) against AgentWorkforce/flows fe8d7606 (v2.0.16). Method: every claim checked against the CLI USAGE block, the surface types, SURFACE.md/CLOUD.md/BUDGET.md; every code sample (11 doc samples + 12 marketing samples) extracted and run through tsc and flows check against a built 2.0.16 surface — all typecheck, all pass check except the two noted at the bottom.
Audit table
| Location | Claim | Verdict | Fix / lands in |
|---|---|---|---|
cli.mdx:7,25, quickstart.mdx:80 | flows check takes only flow.yaml/spec.json | wrong | accepts .flow.ts and --watch; rewritten |
cli.mdx:6-15 | command surface (8 lines) | missing | full 2.0.16 USAGE: --sync-code, sync, deploy <flow.ts>, deployments, undeploy, replay, build, digest deploy, add, serve-webhook, --reuse-from, --allow-human-influenced, resume --local-agent |
cli.mdx:66 | --json only on check/run/resume | wrong | also replay, build, sync, deploy, deployments, undeploy |
cloud.mdx:51 | --cloud refuses authored .flow.ts | wrong | accepted with --input since 2.0.16 (#440) |
cloud.mdx:32 | "the flows CLI never logs in for you" | wrong | falls back to the agent-relay cloud login store, bound to its issuing URL |
cloud.mdx | --sync-code, flows sync, listener deploy verbs, submission_aborted | missing | added |
cloud.mdx:28-29 | finished.completionReason | wrong (type error: union) | narrowed with 'completionReason' in finished |
introduction.mdx:55, build.mdx:90, multi-agent.mdx:64, 5 marketing samples | f.done('canceled') / budget_exceeded as authored verdicts | wrong | refused unsupported_completion at runtime; verdicts are success/step_failed/needs_human/declined (declined shipped in 2.0.16, #439) |
introduction.mdx:57 | missing CLI → REFUSED [invalid_spec] | wrong | cli_unresolved (verified with flows check) |
introduction.mdx:57 | omitted model "runs whatever the CLI defaults to" | wrong | Claude adapter default is claude-opus-5; Codex has none |
introduction.mdx, build.mdx | flows.json models allowlist | missing | with a models list every declared model must be on it (model_unknown) |
build.mdx:73-79 | budget is YAML-only | wrong | TS header: "$5/run", "$20/day", { tokens, dollars, wallclock } |
build.mdx:133 | budget = maxTokensIn/maxTokensOut/maxDollars | wrong (legacy envelope) | current forms + Codex-unmetered rule (#421, 2.0.13) |
build.mdx:84-91 | Ctx interface | wrong/incomplete | run timeout option, llm(prompt, {output}) overload, helpers/memory/mcp, verdict set |
build.mdx:100-101 | verification = output_contains + json_schema | missing | exit_code, four named gates, postfix .gate(config), vacuous_gate |
build.mdx, marketing samples (20 uses) | .gate((r) => r.artifacts.includes(…)), r.artifacts | not shipped | refused unsupported_gate / always [] in 2.0.16; marked "lands in flows#449"; sample shape kept |
| marketing samples (3 uses) | workspace: "review/: readwrite" | not shipped | refused unsupported_workspace_permission; noted in build.mdx, samples left for product decision |
introduction.mdx:19, build.mdx:99, multi-agent.mdx:88-96, 5 marketing samples (support-triage, content-pipeline, voicemail-follow-up, redacted-summary, issue-routing) | f.human(...), f.dispatch(...) presented as working | not shipped | typed + preflighted, refused unsupported_verb at runtime (authored-flow-executor.ts:409); implementing on flows feat/f-human, lands in the release after 2.0.17. Note added where each is introduced naming f.done('needs_human') + flows resume as the shipped human gate; sample shapes kept (ced4c27) |
marketing repo-migration | f.agent({ cwd }) | not shipped | in the surface type, rejected by the 2.0.16 kernel spec (unknown field "cwd"); flagged only |
marketing software-factory | f.github.createPullRequest({ repo, head, base, bodyPath }) | wrong (type error) | { owner, repo, title, head, base, body } |
memory-and-integrations.mdx:12-24 | recall/why interpolated as strings; learn(string) | wrong | arrays of entries (e.prompt), learn(finding) refuses in 2.0.16; memory: { script: true } header shown |
memory-and-integrations.mdx:28-35 | "shipped provider is a fixed stub" | wrong | reads the local ai-hist SQLite DB; learn/agent memory refuse |
memory-and-integrations.mdx:41-48 | f.slack.post with no header/mount note | incomplete | tools: { slack: true }, helper_slack.mount_required locally, RELAYFLOWS_SLACK_MOCK=1 |
multi-agent.mdx:14 | claude-opus-4-6 | unverified | not in the frozen price table; changed to claude-opus-5 (adapter default, priced) |
reliability.mdx:10-15,23-28 | exit codes / vocabulary | incomplete | run_not_found → 2, declined → 0, authored verdict list |
cli.mdx:64 | "tick … durable schedule" | correct, but implied hosted | clarified: local process; hosted v2 schedules not shipped |
web/lib/flow-onboarding.ts:100 | dollar budget refuses model-less Codex | wrong (stale since 2.0.13) | comment rewritten; { wallclock } kept with the current reason |
quickstart, introduction samples, YAML samples, reliability daemon/lock text, exit-code semantics, three rules | — | correct | unchanged |
Counts: wrong 16 · missing 6 · not-yet-shipped 5 (marked, not rewritten) · correct 8 · unverified 2.
Language convention (second commit, 556c0ac)
Every flow example is shown in TypeScript; YAML is reached only through the docs' Language dropdown (<CodeGroup>, first fence typescript TypeScript, second yaml YAML). Audited all 8 relayflows pages and the 9 factory pages (the factory pages contain no flow samples).
Samples converted (bare YAML → TS-first CodeGroup, TS twin written and verified with tsc + flows check):
introduction.mdx§Verification —hello-agent(TS uses postfix.gate({ type: 'regex_match' }))multi-agent.mdx§Named agents —ship-feature(TS spreads per-agent{ cli, model }objects; Note rewritten around flows#300)build.mdx§Permissions and recovery — YAML step fragment expanded to a full flow with a TS twin stating the TS defaults
YAML-first CodeGroups to reorder: none (all existing groups were already TS-first). Prose: quickstart.mdx §2 and build.mdx §Two ways no longer open with "YAML is canonical" / "YAML describes…"; the canonical-data statement stays, after TypeScript.
Not fixed here / needs a product decision
web/lib/flow-local.tspinsRELAYFLOWS_VERSION = '2.0.15'with a deliberate tripwire test and generatesf.done("needs_human")guards "until a pin containsdeclined". 2.0.16 contains it. Bumping the pin and switching the generated guards todeclinedchanges what users get from onboarding — left for the owner.- Marketing samples'
.gate(fn)/r.artifacts(20) andworkspace: "…: readwrite"(3): kept as marketing shape; they run only after flows#449 lands and Cloud's runtime pin moves.repo-migration'scwdis rejected by the kernel today. - Marketing samples'
f.human(5) and the docs'f.dispatch: kept as shape; they run only after flowsfeat/f-humanships (release after 2.0.17) and Cloud's runtime pin moves. gpt-5.6-codex(multi-agent.mdx) fails the Codex model probe on my machine; may be my credential. Left as is.web/content/blog/promptgramming.mdxuses$5/run/$8/runbudgets — correct, out of scope.- The pre-existing
flow-workflows.test.tsfailure ("lockfile needs a package manager that cannot be provisioned") reproduces onorigin/mainwith my changes stashed; it depends onpnpm/corepackpresence on the host.
Verification: tsc --noEmit clean for web/; vitest: 145 passed, 1 failed (pre-existing, above).
🤖 Generated with Claude Code
[!NOTE]
Low Risk
Changes are limited to documentation, example strings, and static assets; no production auth, billing, or runtime code paths are modified.
Overview
This PR re-audits Relayflows documentation and on-site flow samples against relayflows 2.0.16, fixing inaccurate CLI/API claims and documenting what is not runnable yet.
Documentation across web/content/docs/relayflows/* now reflects the real command surface (including --sync-code, sync, listener deploy, replay, build, webhooks), TypeScript-first examples with YAML behind the language switch, and corrected runtime behavior: authored f.done verdicts (declined, needs_human), cli_unresolved, flows check on .flow.ts, Cloud --input for authored flows, credential resolution via agent-relay cloud login, verification via named/postfix gates, memory/integration return shapes, and explicit notes that f.human / f.dispatch, callback .gate(fn), and empty artifacts are refused in 2.0.16 (with f.done('needs_human') + flows resume as the shipped human gate). A new Cookbook page, nav entry, deploy-flow_small.svg, and cloud quick paths were added; flow-onboarding.ts comments were updated for Codex budget metering.
Marketing carousel samples in flow-examples.ts swap artifact callback gates for subprocess_gate, fix createPullRequest args, use declined instead of canceled, and annotate f.human as not yet executed by the SDK.
Next.js agent boilerplate (web/AGENTS.md, web/CLAUDE.md) was added for local dev tooling.
Reviewed by Cursor Bugbot for commit b3b8da7498abc8913220ac80805e45a0497e7a19. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by cubic
Audits the Relayflows docs and marketing flow samples against flows v2.0.16/2.0.17, correcting wrong CLI and API claims, documenting the hosted surface, and marking features that typecheck but don't run yet.
Docs corrections
flows checkaccepts.flow.tsand--watch;flows run --cloudaccepts authored flows with--input, and the 2.0.16 HTTP 400 bug is documented as fixed in 2.0.17.- Authored verdicts are
success,step_failed,needs_human,declined;canceledandbudget_exceededare kernel-only, and a missing CLI refuses withcli_unresolved. - Documented the hosted surface:
--sync-code,flows sync,deploy/deployments/undeploy,replay,build,serve-webhook,--reuse-from,--allow-human-influenced, plus cloud credential fallback and exit-code semantics. f.human/f.dispatchand callback.gate(fn)refuse at runtime in 2.0.16; each is marked as landing later, withf.done('needs_human')+flows resumeas the shipped human gate.- Marketing flow examples now use
subprocess_gateconfigs and thedeclinedverdict;f.humancalls are annotated as not yet executable. - Added a Cookbook page linking verified recipes with Deploy Flow badges, and agentrelay.com/cloud as the no-install path.
Agent Relay sessions
claudesessiona921b252· opened viagh pr create· last active 2026-09-17