# Workflows

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 27-36 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 37-50 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 51-68 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 69-79 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 80-97 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 98-115 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 116-139 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 140-160 |
| [Parent And Child References](#parent-and-child-references) | Operating guidance and contracts for this section. | 161-172 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 173-186 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 187-199 |
| [Verification](#verification) | Evidence required before reporting success. | 200-211 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 212-223 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 224-243 |
<!-- END GENERATED: guide-map -->

## Purpose

Use this parent guide to classify workflow/play tasks and route to the right
child reference. It answers two questions only: what kind of workflow work is
this, and which guide owns the exact mechanics?

Do not treat this file as the operating manual for every workflow action. Child
references own execution details, SDK function contracts, report rendering,
source checkpointing, and sequence activation.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.play_scaffold.init` | Use to create the canonical generated Workflow Play project root before defining or operating a new Play. | None | `workflow_play_scaffold_result` | [`workflow_scaffold.md`](workflow_scaffold.md) · installed SDK: `verbiflow/play_scaffold.py:28-262` |
| `vf.workflows.define` | Use to define the durable Python workflow and its typed steps, inputs, checkpoints, outputs, and effects. | `name`, `store` | `workflow` | [`workflow_composition.md`](workflow_composition.md) · installed SDK: `verbiflow/workflows.py:407-440` |
| `vf.workflows.validate` | Use before expensive execution to catch provable structural, SDK argument, row-key, and output-registration errors. | `path_or_id` | `workflow_validation_report` | [`workflow_operations.md`](workflow_operations.md) · installed SDK: `verbiflow/workflows.py:849-878` |
| `vf.workflows.operate` | Use to run or resume the authored workflow locally, verify terminal outputs, and synchronize the Play. | `path_or_id` | `workflow_play_operation_result` | [`workflow_operations.md`](workflow_operations.md) · installed SDK: `verbiflow/workflows.py:2417-2623` |
| `vf.workflows.sync` | Use to publish changed executable code and eligible completed outputs without starting another run. | `path_or_id` | `workflow_play_sync_result` | [`workflow_schedules.md`](workflow_schedules.md) · installed SDK: `verbiflow/workflows.py:1390-1497` |
| `vf.plays.schedules.upsert` | Use to create, edit, pause, or resume a server-owned calendar or recurring Play schedule. | `play_id`, `schedule_spec` | `workflow_play_schedule` | [`workflow_schedules.md`](workflow_schedules.md) · installed SDK: `verbiflow/plays.py:534-691` |
| `vf.plays.schedules.run_hosted_workflow` | Use to run an already-synced ready revision in the hosted runtime after explicit deterministic-run intent. | `expected_revision_id`, `idempotency_key`, `play_id`, `schedule_slug` | `hosted_workflow_run_receipt` | [`workflow_schedules.md`](workflow_schedules.md) · installed SDK: `verbiflow/plays.py:1169-1472` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`workflow_composition.md`](workflow_composition.md) | Play step design, data flow, effects, and reproducible composition. | capability |
| [`workflow_operations.md`](workflow_operations.md) | Run, inspect, repair, replay, and synchronize an existing Play. | capability |
| [`workflow_reports.md`](workflow_reports.md) | Editable Play reports, HTML outputs, and reviewable score, rationale, confidence, and evidence presentation. | capability |
| [`workflow_scaffold.md`](workflow_scaffold.md) | Create the canonical generated Workflow Play project root. | capability |
| [`workflow_schedules.md`](workflow_schedules.md) | Create, edit, pause, run now, and inspect calendar or recurring Play schedules. | capability |
| [`workflow_sources.md`](workflow_sources.md) | Checkpointed source windows, freshness, pagination, and stop conditions inside Plays. | capability |
| [`logging.md`](logging.md) | Progress, semantic milestones, lifecycle events, and runtime diagnostics. | policy |
| [`parallelism.md`](parallelism.md) | Bounded consolidation, concurrency, retries, deadlines, and no-progress guards. | policy |
| [`safety.md`](safety.md) | Approval, confirmation, side-effect, purchase, and external-communication boundaries. | policy |
| [`testing.md`](testing.md) | Semantic verification for rows, artifacts, Play outputs, reports, and effects. | policy |


## Use This When

- The user says workflow, Workflow Play, play run, snapshot, report, queue,
  schedule, run every day/hour/week, checkpoint, replay, repair, resume,
  daemon, or sync and the next reference is not obvious.
- The request mixes local workflow state, final Play UI output, backend `/plays`
  history, source freshness, artifacts, and sequence/source side effects.
- You are debugging a workflow failure and need to classify whether the problem
  belongs to identity, source acquisition, local run state, provider jobs,
  report generation, Play sync, queueing, scheduling, or activation.

## Do Not Use This For

- Creating/scaffolding a new generated Workflow Play root. Go to
  `workflow_scaffold.md`.
- Operating an already identified generated workflow root. Go to
  `workflow_operations.md`.
- Designing the steps of a new GTM play. Go to `workflow_composition.md`.
- Source windows, checkpoints, object memory, or cursor semantics. Go to
  `workflow_sources.md`.
- Final local Play UI/report rendering. Go to `workflow_reports.md`.
- Recurring/later Workflow Play schedules, whether local/external or
  workspace-hosted. Go to `workflow_schedules.md`.
- Sequence staging, publish, send, mailbox/domain purchase, or billing actions.
  Go to `sequences.md`, `mailboxes.md`, or `billing.md` and keep the
  approval boundary explicit.
- One-off CRM, enrichment, web, LinkedIn, sender, billing, or host-browser tasks
  that are clearly owned by a narrower provider guide.

## Choose A Path

Choose the narrowest child that owns the user's next decision. Do not read the
entire workflow corpus up front.

| User outcome | Read next | Why |
| --- | --- | --- |
| Create a new Play project | `workflow_scaffold.md` | Owns the generated root, files, checklist, and registration boundary. |
| Design or refactor the GTM process | `workflow_composition.md` | Owns steps, data flow, effects, approval gates, and reproducibility. |
| Run, resume, repair, or inspect a Play | `workflow_operations.md` | Owns execution state, retries, outputs, and final synchronization handoff. |
| Define freshness, cursors, or checkpoints | `workflow_sources.md` | Owns source windows, pagination, object memory, and stop conditions. |
| Build or verify the final review artifact | `workflow_reports.md` | Owns Play reports, HTML, row sidecars, and exact artifact verification. |
| Create, pause, edit, or run a schedule | `workflow_schedules.md` | Owns recurrence, ticks, revision pinning, and hosted progress. |
| Coordinate several local Play roots | `workflow_queues.md` | Owns local multi-root queueing and status. |

If the user has already named an exact SDK callable, skip this routing layer and
retrieve that callable's exact contract and source location.

## Mental Model

A Workflow Play is not one thing. Separate the vocabulary before acting:

| Term | Means | Owner |
| --- | --- | --- |
| Workflow scaffold | Creation of the local root, generated files, `CHECKLIST.md`, and workspace registration. | `workflow_scaffold.md` |
| Workflow root | Local editable project with `workflow.py`, `config.json`, scripts, reports, and `state/workflow.sqlite`. | `workflow_operations.md` |
| Workflow run | One local execution/resume/repair of a root, with step state, rows, outputs, events, and errors. | `workflow_operations.md` |
| Source acquisition | Provider request plus local source checkpoint/object memory for consumed rows and freshness. | `workflow_sources.md` |
| Workflow composition | The planned GTM process: discovery, suppression, enrichment, qualification, reporting, host evidence, and activation gates. | `workflow_composition.md` |
| Report / Play UI | Final local business-facing review app and sidecars. | `workflow_reports.md` |
| Workspace Play sync | Backend `/plays` registration and synced code revision. Local sync may also include eligible completed Local run outputs; Mochi authoring sync is code/declaration-only. | `workflow_schedules.md` |
| Workflow schedule | Local/external scheduled workflow invocation, workspace-owned hosted agent execution, or deterministic hosted workflow execution of latest synced Play code. | `workflow_schedules.md` |
| Sequence activation | Staging/promoting rows, publishing, sending, or buying sender/domain resources. | `sequences.md`, `mailboxes.md` |
| Billing operation | Inspecting credits, plans, checkout, or reconciliation. | `billing.md` |
| Workflow queue | Multi-root local coordination/status index. | `workflow_queues.md` |

The most important boundary: Play sync is not provider execution and not
sequence activation. It writes a changed code revision. Local sync may also
publish eligible completed Local run evidence and artifacts. Mochi authoring
sync never does; its scheduled Hosted execution publishes declared artifacts
after the terminal run. Neither sync path stages, sends, or purchases.

## Preflight

Before opening a child guide, classify the request with these checks:

1. Is the user asking to create or initialize a new play root? Use
   `workflow_scaffold.md`.
2. Is there an existing workflow root? If yes, resolve the exact root path and
   read `workflow_operations.md` before running or repairing anything.
3. Is the user asking what workflow should exist or how steps should be
   arranged? Use `workflow_composition.md`.
4. Is the concern freshness, checkpointing, stale rows, cursor behavior, or
   provider windows? Use `workflow_sources.md`.
5. Is the concern the generated review app, row preview, Svelte/custom views, or
   report sidecars? Use `workflow_reports.md`.
6. Is the concern recurring/later execution, external scheduler setup, run-now
   ticks, or hosted progress for a registered Play? Use `workflow_schedules.md`.
7. Is the concern sequence/source mutation, sends, sender setup, or billing?
   Leave workflow docs and use the activation-specific references.
8. If live workspace state is involved, verify auth/workspace identity before
   provider work, Play sync, schedule creation, or sequence activation.

## Parent And Child References

| Child reference | Owns | Does not own |
| --- | --- | --- |
| `workflow_scaffold.md` | Creating a generated Workflow Play root, stable path selection, `vf.play_scaffold.init(...)`, generated files, `CHECKLIST.md`, local-vs-registration boundary, and handoff to composition/operation/report guides. | Running/repairing an existing root, source checkpoint semantics, final report design, or sequence activation. |
| `workflow_operations.md` | Existing/generated roots, run/resume/repair/replay, workflow-local progress/events, status/export, report build entrypoints, daemon/operate semantics, activation boundaries, and when to hand off for sync. | Play sync mechanics, step design, source cursor theory, final UI design, per-job JSONL telemetry, or sequence publish/send mechanics. |
| `workflow_sources.md` | Source windows, checkpointed acquisition, object memory, artifact collection into local rows, `rows_available` semantics, and freshness assumptions. | Provider implementation, local step design, reports, or activation. |
| `workflow_composition.md` | Designing/refactoring repeatable GTM plays across discovery, CRM, enrichment, qualification, reporting, host evidence, and approval gates. | Running a concrete root or deciding source checkpoint internals. |
| `workflow_queues.md` | Queueing, running, inspecting, and exporting status across several local workflow roots. | One workflow's internal steps or approval decisions. |
| `workflow_reports.md` | Final Play UI/report bundle, row sidecars, built-in views, custom views, and serving the review app. | Local workflow progress monitor or backend `/plays` snapshot storage. |
| `workflow_schedules.md` | Canonical Play sync, Local/external scheduled workflow runs, workspace server schedules, run-now ticks, tick history, hosted progress, and code revision pinning. | Immediate one-off local workflow execution, operating a run, or queueing roots. |

## Risk And Side Effects

| Action | Risk class | Rule |
| --- | --- | --- |
| Inspect root files, local SQLite state, exports, or report sidecars | local read | Safe after resolving the exact root. |
| Build or serve a report/Play UI | local file/server action | Safe after checking report paths and ports. |
| Run preview mode | provider/credit jobs may run; customer-visible mutations should be blocked | Print workspace, source window, budgets, and sample rows. |
| Run batch/production mode | provider/credit jobs plus declared workflow side effects | Verify effects, claims, approvals, and target ids. |
| Sync workspace Play | platform write | Verify workspace identity. This does not stage/publish/send by itself. |
| Create/run a workspace server Play schedule | platform write plus hosted run | Verify workspace identity and `play_id`; choose `hosted_mochi` or `hosted_workflow`; stream the returned hosted-agent `runId` or hosted-workflow `workflowProgressRunId`. |
| Configure a local/external workflow schedule | local scheduler action plus whatever the workflow later does | Verify root path, SDK auth profile, command, cadence/timezone, and Play sync expectation. |
| Stage/promote sequence rows | platform mutation | Verify source/sequence ids, mappings, dedupe, and claims. |
| Publish/send/purchase | customer-visible or billing mutation | Require explicit user confirmation immediately before execution. |

## Canonical Operating Pattern

1. Name the object: root, run, source, report, sync, schedule, queue, or activation.
2. Route to the child guide that owns that object.
3. Preserve the ids that prove continuity: workspace id, workflow root, run id,
   job id, artifact id, report path, sync result/code revision id, schedule id,
   tick id, hosted run id, workflow progress run id, source run id, sequence id, and sender/billing ids
   when relevant.
4. Verify in the owning system: workflow status for runs, source checkpoint state
   for acquisition, report sidecars for Play UI, backend `/plays` for Play sync,
   local scheduler logs or schedule/tick/live pages for scheduled work,
   and sequence diagnostics for activation.

## Verification

Verify the object the user actually requested, not only the last command that
ran. A finished Play must resolve one canonical Play identity, an immutable code
revision, a terminal run, and every declared output. The output bytes must come
from that terminal run's final code execution.

For resumed or scheduled work, also verify continuity through the original run,
schedule, tick, checkpoint, and artifact identifiers. If any required receipt is
missing, describe the durable partial state and the next repair step instead of
calling the Play complete.

## Troubleshooting

| Symptom | First check | Read next |
| --- | --- | --- |
| Agent is unsure which workflow root to run | List plausible roots with path, workflow name, latest run ids, and purpose. | `workflow_operations.md` |
| Rows look stale or a code change did not rerun | Check completed step state, source contract, and whether replay/reset is needed. | `workflow_operations.md`, `workflow_sources.md` |
| Provider fetch did not parallelize | Check whether the code starts jobs serially in a Python loop; `pipelined=True` is not automatic loop parallelism. | `workflow_operations.md`, `artifacts_jobs.md` |
| `/plays` shows old counts or missing outputs | Confirm report build path and Play sync happened after the relevant run/side effect. | `workflow_reports.md`, `workflow_schedules.md` |
| User asked to run a Play on a cadence or later | Confirm the Play is registered, then choose local/external scheduling or workspace server schedule CRUD. | `workflow_schedules.md` |
| Final Play UI is confused with backend Play history | Separate the report artifact from workspace Play sync. | `workflow_reports.md`, `workflow_schedules.md` |
| Sequence audience did not change | Check sequence staging/promotion/source-run diagnostics, not Play sync. | `sequences.md` |

## Related References

| If the task is about | Read | Why |
| --- | --- | --- |
| Auth/profile/workspace identity before any workflow operation | `auth.md` | Workflow roots are workspace-scoped; a wrong profile/org can sync Play evidence or run providers in the wrong workspace. |
| Creating/scaffolding a concrete Workflow Play root | `workflow_scaffold.md` | The SDK entrypoint is `vf.play_scaffold.init(...)`; `verbiflow init` is only the human terminal adapter. |
| Scheduling a registered Play or manually running a scheduled tick | `workflow_schedules.md` | Keeps local/external scheduler semantics and workspace-hosted schedule semantics in one place. |
| Job handles, `job_id`, `artifact_id`, waiting, streaming, batching, and artifact paging | `artifacts_jobs.md` | Workflows should preserve handles, but job lifecycle and durable artifact mechanics live outside the workflow parent guide. |
| Provider/job batching, concurrency, or the belief that `pipelined=True` parallelizes arbitrary Python loops | `parallelism.md`, `artifacts_jobs.md`, `workflow_operations.md` | Parallelism must be explicit at the job/async/chunk boundary; workflow pipelining only changes step readiness semantics. |
| Already-acquired row shaping, coverage, mapping, or local joins | `row_operations.md` | Row operations prepare data for workflows, reports, enrichment, or staging; they do not acquire sources or activate sequences. |
| CRM schemas, properties, associations, and suppression facts | `crm.md` | Workflow code must not guess provider fields such as active-customer flags, deals, ownership, or company-contact associations. |
| Email/domain/profile/company enrichment | `enrichment.md` | Enrichment owns resolver fields, canonical identity outputs, credit behavior, and verification before activation. |
| People/account/source discovery outside a durable root | `audience_discovery.md` | One-off audience discovery can be valid without turning the work into a generated workflow root. |
| Public web search, page extraction, product/news evidence, or static fallback provenance | `web.md` | Web calls are Bridge-backed Growth capabilities with policy, provenance, and credits; host-browser docs are for rendered/session evidence. |
| Rendered/authenticated browser evidence, screenshots, or local provider sessions | `host_browser.md`; use `web.md` for explicit URL page capture | Browser-backed provider work needs SDK host adapters when the evidence should belong to a workflow/report. |
| Sequence source/copy/stage/publish/send | `sequence_authoring.md`, `sequences.md` | Workflow docs can describe an activation boundary; sequence docs own exact source mappings, staging, diagnostics, publish, and send safety. |
| Sender/mailbox/domain readiness or purchases | `mailboxes.md` | Sender operations can become customer-visible or paid mutations and need explicit approval gates. |
| Workflow Play credits, `credits_used`, billing reconciliation, or cost by `play_id` | `billing.md` | Workflow snapshots can record run usage, but authoritative credit totals come from billing/ledger surfaces such as `vf.billing.cost_by_play(...)`. |
| Approval gates, large provider jobs, purchases, or customer-visible risk | `safety.md` | The workflow parent only classifies risk; safety owns confirmation boundaries and what agents may execute without a human. |
| Proving workflow/provider output correctness before activation | `testing.md` | Tests/evals should prove row contracts, provider facts, credits, and side-effect gates rather than rely on final UI screenshots. |
