more docs changes

docs/README.md

@@ -0,0 +1,86 @@
+# 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.
+- [`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_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.
+- [`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`.
+
+## MCP Platform
+
+- [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md): operator/client
+  guide for connections, catalog discovery, drafts, artifacts, deployments, and
+  troubleshooting flow.
+- [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md): full run from
+  connection setup to capability discovery to deployment execution.
+- [`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.
+- [`wf_mcp_troubleshooting.md`](wf_mcp_troubleshooting.md): common MCP/server
+  failure modes.
+
+## 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/): mostly completed implementation
+  plans and execution records. Use them for context, not as the primary source
+  of truth.
+- [`superpowers/specs/`](superpowers/specs/): design specs produced during
+  planning sessions.
+
+## Future Runtime Work
+
+Two runtime features may come back after the platform/DX roadmap advances:
+
+- Native subgraph execution with child run state, interrupt bubbling, and resume
+  back into the child workflow.
+- Async parallel foreach with explicit scheduling, reducer/merge semantics, and
+  failure policy. Do not implement this as plain `asyncio.gather` over sync
+  handlers.

docs/current_roadmap.md

@@ -0,0 +1,44 @@
+# Current Roadmap
+
+This is the short active roadmap after the core type-shape cleanup. It is based
+on both the current docs and the implementation state.
+
+## Next Work
+
+1. **Docs index and prune**
+   - Add/maintain a clear docs entry point.
+   - Keep current architecture docs separate from historical plans and scratch
+     notes.
+
+2. **MCP workflow authoring UX**
+   - Make the LLM/client path progressive: inspect sources, create a draft,
+     patch, validate, compile, save, run.
+   - Prefer smaller discovery/inspection responses over one huge payload.
+
+3. **Wrapper creation ergonomics**
+   - Help create workflow-ready wrappers from raw capabilities.
+   - Suggest state schema, input bindings, output bindings, default `ok` /
+     `error` handling, and missing decisions.
+
+4. **Run and deployment story**
+   - Tighten list/inspect/run/debug for artifacts and deployments.
+   - Keep dependency validation and trace/error output compact and actionable.
+
+5. **Source inventory polish**
+   - Make `list_sources` / `inspect_source` clearly show raw capabilities,
+     workflow-ready node specs, admin-only tools, docs/resources, enabled state,
+     and changes after reload.
+
+## Runtime Work To Revisit Later
+
+- **Native subgraphs**: add child run state, child trace preservation, interrupt
+  bubbling, and resume back into the child workflow.
+- **Async parallel foreach**: add explicit scheduling, reducer/merge semantics,
+  and failure policy. Do not model this as plain parallel calls over sync
+  handlers.
+
+## Why This Order
+
+`wf_core` is now coherent enough for the next bottleneck to be platform and DX:
+how a human or LLM discovers capabilities, turns them into workflow-ready
+pieces, saves them, and runs them again.

readme.md

@@ -2,8 +2,10 @@
 
 ## Related docs
 
+- [docs/README.md](docs/README.md): documentation index; start here for current vs historical docs.
 - [docs/authoring_sketch.md](docs/authoring_sketch.md): `wf_authoring` direction, including `@node`, `NodeSpec`, builder ergonomics, async registry seams, and subgraph-as-node.
 - [docs/project_map.md](docs/project_map.md): current package map, entrypoints, examples, tests, and verification commands.
+- [docs/current_roadmap.md](docs/current_roadmap.md): short active next-work list after the core type-shape cleanup.
 - [docs/wf_core_architecture.md](docs/wf_core_architecture.md): current `wf_core` package boundaries, runtime flow, validation flow, and remaining cleanup seams.
 - [docs/schema_validation.md](docs/schema_validation.md): current payload schema validation limits and intended validation seam.
 - [docs/wf_mcp_plan.md](docs/wf_mcp_plan.md): `wf_mcp` direction as a namespaced MCP capability broker plus workflow build/run layer.