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

Core Workflow Model

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 source/capability refs and structural graph/local/state path JSON.
schema_validation.md: JSON Schema validation seam and current payload validation limits.
workflow_artifacts.md: saved workflow artifacts, deployments, dependency compatibility, and interrupt limitations.
durable_run_operations.md: run_deployment, inspect_run, bounded trace reads, and resume_run behavior.
workflow_drafts.md: LLM/human draft authoring format above raw workflow plans.

Authoring

authoring_sketch.md: authoring layer direction, NodeSpec, builder API, and catalog goals.
wf_authoring_control_flow.md: when to use branch, handle, match, when, and choose.

CLI

wf_cli.md: workflow platform CLI commands, output formats, lifecycle flow, and common diagnostics.
runbooks/rpc-cli-smoke.md: bounded end-to-end smoke test for wf-rpc-server plus remote wf CLI.
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: start here for the MCP-facing workflow lifecycle and tool families.
wf_mcp_end_to_end_runbook.md: concrete tool-call runbook from capability discovery through deployment, run, resume, and cleanup.
wf_mcp_troubleshooting.md: diagnostics and repair steps for source, deployment, run, and resume failures.
durable_run_operations.md: durable run records, compact inspection, bounded traces, and resume semantics.
wf_mcp_capability_sources.md: source model for raw capabilities, workflow-ready node specs, admin tools, and docs.
workflow_capabilities.md: distinction between raw capabilities, workflow capabilities, wrappers, artifacts, and deployments.
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 surface inventory for proxy support.
mcp_stateful_runtime_plan.md: stateful MCP runtime planning notes.
FastMCP issue notes: fastmcp_resource_link_issue_guide.md, fastmcp_resource_link_issue_lda_tries.md, fastmcp_notification_forwarding_issue_lda_tries.md.

Historical Material

historical/scratchpad.md: older graph/model design notes.
historical/path_mapping_scratch.md: older path and mapping design thread.
superpowers/plans/: active executable handoff plans only. Completed or stale plans are archived under historical/superpowers/plans/.
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: active implementation status and next-work list.
adr/0001-scheduler-foundation-before-concurrent-foreach.md: scheduler foundation decision.
adr/0002-concurrent-foreach-policy-and-barrier-commits.md: concurrent foreach policy and barrier commit semantics.
superpowers/specs/2026-05-24-native-subgraphs-design.md: native subgraph design.
superpowers/specs/2026-05-26-durable-workflow-runs-and-resume-design.md: durable run/checkpoint design.