Progressive Discovery ahh

docs/wf_mcp_capability_sources.md

@@ -267,13 +267,12 @@ the same admin/control capabilities.
 
 ## Current Inventory Surface
 
-`list_sources()` is the source inventory:
+`list_sources()` is the compact source-discovery surface:
 
-- returns every source
-- includes visibility, permissions, counts, and owned capability names
-- lets callers answer planner questions by inspecting
-  `visibility.planner` plus `capabilities.node_specs`
+- returns paged source summaries with visibility, permissions, and counts
+- is intentionally compact enough for progressive discovery
+- pairs with `inspect_source(source_id)` for the full owned-capability inventory
 
-Humans and LLM authoring clients should use that one inventory when deciding
-what exists. Planner projection remains a different **use** of source metadata,
-not a second source model.
+Humans and LLM authoring clients should list sources first, then inspect only the
+sources they need. Planner projection remains a different **use** of source
+metadata, not a second source model.

docs/workflow_capabilities.md

@@ -251,7 +251,8 @@ The workflow-facing MCP surface now has dedicated discovery tools for the
 authoring loop:
 
 - `wf.workflow.list_capabilities`
-  - lists enabled planner-visible workflow-ready node specs
+  - lists compact paged enabled planner-visible workflow-ready node spec
+    summaries, with optional query/source filtering
 - `wf.workflow.inspect_capability`
   - returns one full workflow capability contract with schemas and outcomes
 - `wf.workflow.call_capability`