# Documentation Index

Start here when orienting to the project. Top-level docs are the current
reference unless marked otherwise. Historical scratch notes and completed
implementation plans are kept for context, not as active instructions.

## Current Overview

- [`project_map.md`](project_map.md): package map, entrypoints, examples, tests,
  and verification commands.
- [`add/2026-06-workflow-platform-presentation.md`](add/2026-06-workflow-platform-presentation.md):
  concise presentation narrative for the current product shape and demo flow.
- [`thesis/system-design-implementation.md`](thesis/system-design-implementation.md):
  maintained thesis/report document.
- [`thesis/evidence-index.md`](thesis/evidence-index.md): claim-to-code and
  claim-to-test evidence map for the thesis.
- [`current_roadmap.md`](current_roadmap.md): active next-work list after the
  core type-shape cleanup.
- [`wf_core_architecture.md`](wf_core_architecture.md): kernel package
  boundaries, runtime flow, validation flow, and known runtime gaps.
- [`wf_api_architecture.md`](wf_api_architecture.md): workflow application API,
  server/transport boundaries, and source package split.
- [`source_architecture.md`](source_architecture.md): source provider package
  map and terminology for sources, tools, workflow capabilities, resources,
  prompts, and logical source refs.
- [`wf_mcp_architecture.md`](wf_mcp_architecture.md): MCP package boundaries,
  dependency rules, reload/proxy behavior, and extraction seams.

## Core Workflow Model

- [`core_state_mapping_and_merge.md`](core_state_mapping_and_merge.md):
  canonical `input` / `output` bindings, interrupt `request` / `resume`
  bindings, state patch rules, reducers, and merge semantics.
- [`structural_refs.md`](structural_refs.md): structural source/capability refs
  and structural graph/local/state path JSON.
- [`schema_validation.md`](schema_validation.md): JSON Schema validation seam
  and current payload validation limits.
- [`workflow_artifacts.md`](workflow_artifacts.md): saved workflow artifacts,
  deployments, dependency compatibility, and interrupt limitations.
- [`durable_run_operations.md`](durable_run_operations.md): `run_deployment`,
  `inspect_run`, bounded trace reads, and `resume_run` behavior.
- [`workflow_drafts.md`](workflow_drafts.md): LLM/human draft authoring format
  above raw workflow plans.

## Authoring

- [`authoring_sketch.md`](authoring_sketch.md): authoring layer direction,
  `NodeSpec`, builder API, and catalog goals.
- [`wf_authoring_control_flow.md`](wf_authoring_control_flow.md): when to use
  `branch`, `handle`, `match`, `when`, and `choose`.

## CLI

- [`wf_cli.md`](wf_cli.md): workflow platform CLI commands, output formats,
  lifecycle flow, and common diagnostics.
- [`runbooks/rpc-cli-smoke.md`](runbooks/rpc-cli-smoke.md): bounded
  end-to-end smoke test for `wf-rpc-server` plus remote `wf` CLI.
- [`runbooks/python-source.md`](runbooks/python-source.md): configure trusted
  project-local Python `NodeSpec` registries, validate them, and run them
  through `wf-rpc-server`.

## MCP Platform

- [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md): start here for
  the MCP-facing workflow lifecycle and tool families.
- [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md): concrete
  tool-call runbook from capability discovery through deployment, run, resume,
  and cleanup.
- [`wf_mcp_troubleshooting.md`](wf_mcp_troubleshooting.md): diagnostics and
  repair steps for source, deployment, run, and resume failures.
- [`durable_run_operations.md`](durable_run_operations.md): durable run
  records, compact inspection, bounded traces, and resume semantics.
- [`wf_mcp_capability_sources.md`](wf_mcp_capability_sources.md): source model
  for raw capabilities, workflow-ready node specs, admin tools, and docs.
- [`workflow_capabilities.md`](workflow_capabilities.md): distinction between
  raw capabilities, workflow capabilities, wrappers, artifacts, and deployments.
- [`wf_mcp_proxy_reality_and_roadmap.md`](wf_mcp_proxy_reality_and_roadmap.md):
  practical proxy behavior, FastMCP gaps, and local workaround boundaries.

## Protocol Notes

- [`mcp_protocol_proxy_inventory.md`](mcp_protocol_proxy_inventory.md): MCP
  protocol surface inventory for proxy support.
- [`mcp_stateful_runtime_plan.md`](mcp_stateful_runtime_plan.md): stateful MCP
  runtime planning notes.
- FastMCP issue notes:
  [`fastmcp_resource_link_issue_guide.md`](fastmcp_resource_link_issue_guide.md),
  [`fastmcp_resource_link_issue_lda_tries.md`](fastmcp_resource_link_issue_lda_tries.md),
  [`fastmcp_notification_forwarding_issue_lda_tries.md`](fastmcp_notification_forwarding_issue_lda_tries.md).

## Historical Material

- [`historical/scratchpad.md`](historical/scratchpad.md): older graph/model
  design notes.
- [`historical/path_mapping_scratch.md`](historical/path_mapping_scratch.md):
  older path and mapping design thread.
- [`superpowers/plans/`](superpowers/plans/): active executable handoff plans
  only. Completed or stale plans are archived under
  [`historical/superpowers/plans/`](historical/superpowers/plans/).
- [`superpowers/specs/`](superpowers/specs/): design specs produced during
  planning sessions.

## Runtime References

Native subgraphs, concurrent foreach, lineage state, and durable stopped-run
resume now have implemented foundations. Use the current roadmap and ADR/spec
docs as the active references:

- [`current_roadmap.md`](current_roadmap.md): active implementation status and
  next-work list.
- [`adr/0001-scheduler-foundation-before-concurrent-foreach.md`](adr/0001-scheduler-foundation-before-concurrent-foreach.md):
  scheduler foundation decision.
- [`adr/0002-concurrent-foreach-policy-and-barrier-commits.md`](adr/0002-concurrent-foreach-policy-and-barrier-commits.md):
  concurrent foreach policy and barrier commit semantics.
- [`adr/0006-explicit-fork-and-topology-driven-gather.md`](adr/0006-explicit-fork-and-topology-driven-gather.md):
  proposed explicit fork, gather-slot, and activation-token semantics.
- [`superpowers/specs/2026-05-24-native-subgraphs-design.md`](superpowers/specs/2026-05-24-native-subgraphs-design.md):
  native subgraph design.
- [`superpowers/specs/2026-05-26-durable-workflow-runs-and-resume-design.md`](superpowers/specs/2026-05-26-durable-workflow-runs-and-resume-design.md):
  durable run/checkpoint design.