workspai 0.46.0 → 0.48.0

package/docs/README.md

@@ -27,6 +27,7 @@ instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
 
 ## Table of contents
 
+- [Choose a guide by goal](#choose-a-guide-by-goal)
 - [User documentation](#user-documentation)
 - [Operations & security](#operations--security)
 - [AI module recommendations](#ai-module-recommendations)
@@ -34,23 +35,48 @@ instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
 - [Contributor documentation](#contributor-documentation)
 - [Validation commands](#validation-commands)
 
+## Choose a guide by goal
+
+| I want to…                                        | Start here                                                                  | Expected outcome                                                      |
+| ------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Create a workspace or project                     | [Creating workspaces and projects](./creating-workspaces-and-projects.md)   | A registered project with canonical `.workspai` metadata              |
+| Bring an existing repository under governance     | [Workspace operations](./workspace-operations.md#import-and-adoption)       | Source stays in place with `adopt`, or is copied/cloned with `import` |
+| Run the complete intelligence loop                | [Unified runner](./workspace-intelligence-runner.md)                        | One ordered run report with durable stage evidence                    |
+| Ask an architecture or dependency question        | [Workspace Knowledge Graph](./workspace-knowledge-graph.md)                 | A bounded answer with proof references rather than the whole graph    |
+| Measure agent token, cost, and outcome efficiency | [Workspace Intelligence Evaluation](./workspace-intelligence-evaluation.md) | A live, provenance-aware report suitable for CLI, IDE, and CI         |
+| Integrate CI or release gates                     | [CI workflows](./ci-workflows.md)                                           | Machine-readable exit codes and uploadable evidence                   |
+| Find the writer, schema, or path for an output    | [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md)                         | One canonical source instead of path guessing                         |
+| Understand Workspai terminology                   | [Glossary](./GLOSSARY.md)                                                   | Shared meanings for model, graph, evidence, gate, and artifacts       |
+| Review or change the main product README          | [README content contract](./README_CONTENT_CONTRACT.md)                     | Stable narrative, claim boundaries, and machine-enforced drift rules  |
+| Contribute to the CLI                             | [Development](./DEVELOPMENT.md)                                             | Local build, test, contract, and documentation gates                  |
+
+There are two different AI-facing features. Workspace Intelligence is
+deterministic, proof-backed, and does not require an AI API key. The optional
+module recommender uses embeddings to suggest FastAPI or NestJS modules; start
+with [AI Quickstart](./AI_QUICKSTART.md) only when that is your goal.
+
 ## User documentation
 
-| Document | Description |
-| --- | --- |
-| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md) | Plain-language guide to every workspace and project creation scenario |
-| [commands-reference.md](./commands-reference.md) | Full CLI syntax, profiles, and policy keys |
-| [workspace-operations.md](./workspace-operations.md) | Import, adopt, snapshots, archives, contracts, infra |
-| [workspace-run.md](./workspace-run.md) | Polyglot fleet orchestration (`workspace run`) |
-| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md) | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption |
-| [create-planner-capabilities.md](./create-planner-capabilities.md) | Native create, official, and existing lanes |
-| [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered |
-| [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md) | GitHub-rendered Workspace Intelligence diagram |
-| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md) | Role-based workflows (junior → enterprise) |
-| [doctor-command.md](./doctor-command.md) | Doctor scopes, CI exit codes, JSON evidence |
-| [config-file-guide.md](./config-file-guide.md) | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks) |
-| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md) | Workspace marker format |
-| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md) | npm-only policy for this repository |
+| Document                                                                                       | Description                                                                                                        |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [creating-workspaces-and-projects.md](./creating-workspaces-and-projects.md)                   | Plain-language guide to every workspace and project creation scenario                                              |
+| [commands-reference.md](./commands-reference.md)                                               | Full CLI syntax, profiles, and policy keys                                                                         |
+| [workspace-operations.md](./workspace-operations.md)                                           | Import, adopt, snapshots, archives, contracts, infra                                                               |
+| [workspace-run.md](./workspace-run.md)                                                         | Polyglot fleet orchestration (`workspace run`)                                                                     |
+| [workspace-intelligence-runner.md](./workspace-intelligence-runner.md)                         | Canonical unified runner, execution envelope, report schema, exit codes, failure propagation, and CI consumption   |
+| [workspace-knowledge-graph.md](./workspace-knowledge-graph.md)                                 | Two-minute graph quickstart, proof model, AI/MCP consumption, performance, and honest token-efficiency measurement |
+| [graph-benchmark-methodology.md](./graph-benchmark-methodology.md)                             | Reproducible payload-reduction benchmark, formulas, claim boundaries, and publication rules                        |
+| [workspace-intelligence-evaluation.md](./workspace-intelligence-evaluation.md)                 | Provider usage, cost provenance, verified outcomes, comparison, and extension consumption                          |
+| [GLOSSARY.md](./GLOSSARY.md)                                                                   | Plain-language definitions for workspace, model, graph, evidence, gates, and AI integrations                       |
+| [README_CONTENT_CONTRACT.md](./README_CONTENT_CONTRACT.md)                                     | Required root README journey, architecture statements, claim policy, and drift guard                               |
+| [create-planner-capabilities.md](./create-planner-capabilities.md)                             | Native create, official, and existing lanes                                                                        |
+| [../contracts/project-entry-capability.v1.json](../contracts/project-entry-capability.v1.json) | Contract: any readable project can enter through adopt/import when it can be registered                            |
+| [from-code-to-shared-understanding.md](./from-code-to-shared-understanding.md)                 | GitHub-rendered Workspace Intelligence diagram                                                                     |
+| [OPEN_SOURCE_USER_SCENARIOS.md](./OPEN_SOURCE_USER_SCENARIOS.md)                               | Role-based workflows (junior → enterprise)                                                                         |
+| [doctor-command.md](./doctor-command.md)                                                       | Doctor scopes, CI exit codes, JSON evidence                                                                        |
+| [config-file-guide.md](./config-file-guide.md)                                                 | User config file (`~/.workspairc.json`, `workspai.config.*`, with legacy fallbacks)                                |
+| [WORKSPACE_MARKER_SPEC.md](./WORKSPACE_MARKER_SPEC.md)                                         | Workspace marker format                                                                                            |
+| [PACKAGE_MANAGER_POLICY.md](./PACKAGE_MANAGER_POLICY.md)                                       | npm-only policy for this repository                                                                                |
 
 **Common tasks**
 
@@ -63,35 +89,35 @@ instructions; see the [Artifact Catalog](./contracts/ARTIFACT_CATALOG.md).
 
 ## Operations & security
 
-| Document | Description |
-| --- | --- |
-| [SECURITY.md](./SECURITY.md) | Vulnerability reporting and supported versions |
-| [policies.workspace.example.yml](./policies.workspace.example.yml) | Workspace policy template |
-| [governance-policy.enterprise.example.json](./governance-policy.enterprise.example.json) | Sigstore governance allowlist template |
-| [mirror-config.enterprise.example.json](./mirror-config.enterprise.example.json) | Mirror + evidence export template |
+| Document                                                                                 | Description                                    |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [SECURITY.md](./SECURITY.md)                                                             | Vulnerability reporting and supported versions |
+| [policies.workspace.example.yml](./policies.workspace.example.yml)                       | Workspace policy template                      |
+| [governance-policy.enterprise.example.json](./governance-policy.enterprise.example.json) | Sigstore governance allowlist template         |
+| [mirror-config.enterprise.example.json](./mirror-config.enterprise.example.json)         | Mirror + evidence export template              |
 
 ## AI module recommendations
 
 FastAPI/NestJS module suggestions via OpenAI embeddings (optional).
 
-| Document | Description |
-| --- | --- |
-| [AI_QUICKSTART.md](./AI_QUICKSTART.md) | 60-second setup |
-| [AI_FEATURES.md](./AI_FEATURES.md) | Complete feature reference |
-| [AI_EXAMPLES.md](./AI_EXAMPLES.md) | Use-case examples |
-| [AI_DYNAMIC_INTEGRATION.md](./AI_DYNAMIC_INTEGRATION.md) | Integration architecture |
+| Document                                                 | Description                |
+| -------------------------------------------------------- | -------------------------- |
+| [AI_QUICKSTART.md](./AI_QUICKSTART.md)                   | 60-second setup            |
+| [AI_FEATURES.md](./AI_FEATURES.md)                       | Complete feature reference |
+| [AI_EXAMPLES.md](./AI_EXAMPLES.md)                       | Use-case examples          |
+| [AI_DYNAMIC_INTEGRATION.md](./AI_DYNAMIC_INTEGRATION.md) | Integration architecture   |
 
 ## Technical contracts
 
 JSON schemas and ownership rules for tooling parity.
 
-| Location | Description |
-| --- | --- |
-| [contracts/README.md](./contracts/README.md) | Core CLI JSON contracts + generator scripts |
-| [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md) | npm wrapper vs Core command ownership |
-| [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md) | Scaffold/import/lifecycle support tiers |
-| [contracts/RUNTIME_ACCEPTANCE_MATRIX.md](./contracts/RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance test expectations |
-| [../contracts/](../contracts/) | Canonical JSON schemas (published in npm tarball) |
+| Location                                                                           | Description                                       |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------- |
+| [contracts/README.md](./contracts/README.md)                                       | Core CLI JSON contracts + generator scripts       |
+| [contracts/COMMAND_OWNERSHIP_MATRIX.md](./contracts/COMMAND_OWNERSHIP_MATRIX.md)   | npm wrapper vs Core command ownership             |
+| [contracts/RUNTIME_SUPPORT_MATRIX.md](./contracts/RUNTIME_SUPPORT_MATRIX.md)       | Scaffold/import/lifecycle support tiers           |
+| [contracts/RUNTIME_ACCEPTANCE_MATRIX.md](./contracts/RUNTIME_ACCEPTANCE_MATRIX.md) | Runtime acceptance test expectations              |
+| [../contracts/](../contracts/)                                                     | Canonical JSON schemas (published in npm tarball) |
 
 Regenerate and verify:
 
@@ -103,13 +129,13 @@ npm run contracts:validate
 
 ## Contributor documentation
 
-| Document | Description |
-| --- | --- |
-| [DEVELOPMENT.md](./DEVELOPMENT.md) | Local dev, testing, debugging |
-| [SETUP.md](./SETUP.md) | Build gates, smoke flows, release hygiene |
-| [ci-workflows.md](./ci-workflows.md) | GitHub Actions workflow map |
-| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes |
-| [UTILITIES.md](./UTILITIES.md) | Internal cache and metrics helpers |
+| Document                                         | Description                               |
+| ------------------------------------------------ | ----------------------------------------- |
+| [DEVELOPMENT.md](./DEVELOPMENT.md)               | Local dev, testing, debugging             |
+| [SETUP.md](./SETUP.md)                           | Build gates, smoke flows, release hygiene |
+| [ci-workflows.md](./ci-workflows.md)             | GitHub Actions workflow map               |
+| [OPTIMIZATION_GUIDE.md](./OPTIMIZATION_GUIDE.md) | Performance and improvement notes         |
+| [UTILITIES.md](./UTILITIES.md)                   | Internal cache and metrics helpers        |
 
 Also see [../CONTRIBUTING.md](../CONTRIBUTING.md) and [../CHANGELOG.md](../CHANGELOG.md).
 
@@ -136,7 +162,10 @@ workspai/
         ├── releases/         # Per-version release notes
         └── docs/
             ├── README.md     # This index
+            ├── README_CONTENT_CONTRACT.md
             ├── commands-reference.md
+            ├── workspace-knowledge-graph.md
+            ├── workspace-intelligence-evaluation.md
             ├── workspace-operations.md
             ├── workspace-run.md
             ├── ci-workflows.md

package/docs/README_CONTENT_CONTRACT.md

@@ -0,0 +1,154 @@
+# README Content Contract
+
+The repository README is Workspai's primary product entry point. It must help a
+new user understand the problem, see a concrete result, run a safe quickstart,
+and choose the next document without first learning the internal architecture.
+
+This contract keeps that experience aligned with the CLI's machine-readable
+contracts. It applies to the root `README.md`; the package README may add detail
+but must not contradict it.
+
+The npm package README at `packages/cli/README.md` is the operational product
+entry point. It follows the same truth boundaries but adds beginner definitions,
+a copyable workspace onboarding path, exact exit semantics, command families,
+durable outputs, requirements, and troubleshooting.
+
+## Required reader journey
+
+The root README keeps these sections in this order:
+
+1. `Workspace Intelligence for software systems` — the category, slogan, and
+   three user outcomes;
+2. `See your workspace as a system` — a concrete before/after mental model;
+3. `Start in two minutes` — install, connect software, run the canonical chain;
+4. `What Workspai gives you` — user questions mapped to product outcomes;
+5. `How Workspace Intelligence works` — sources, facts, model, graph, decisions,
+   and consumers;
+6. `Evidence, not guesses` — identity, proof, bounded retrieval, and unknown
+   relationships;
+7. `Measure context honestly` — reproducible numbers and claim boundaries;
+8. `One contract-backed intelligence chain` — the canonical runner and its
+   distinction from `pipeline`;
+9. `Choose your workflow` — goal-oriented routing;
+10. `Open outputs for every consumer` — human, CI, agent, MCP, IDE, and graph
+    interoperability surfaces;
+11. documentation, packages, contributor, community, and license routes.
+
+Do not move package internals, exhaustive flags, troubleshooting, or contributor
+implementation details above the user value and quickstart.
+
+## CLI package README journey
+
+The CLI README keeps these sections in order:
+
+1. product category and the `See / Ask with proof / Act with confidence` value;
+2. plain-language definitions of Workspace, Project, Model, Graph, Evidence,
+   and Artifact;
+3. a copyable two-minute path that creates a minimal workspace, adopts source,
+   and runs the canonical chain;
+4. the Model → derived Graph architecture and its unknown-relationship rule;
+5. the exact intelligence chain, evidence, and bounded measurement semantics;
+6. grouped commands, outputs, onboarding choices, integrations, requirements,
+   documentation, and troubleshooting.
+
+Measurement tables must not precede installation or the first successful run.
+Advanced command inventories must be grouped by user goal instead of appearing
+as one undifferentiated command wall.
+
+## Architectural statements that must remain true
+
+- The **Workspace Model is the canonical source of truth**.
+- The Knowledge Graph is a **derived, revision-bound representation** of
+  governed workspace knowledge.
+- Providers emit facts and proofs; they do not independently own the canonical
+  graph.
+- Missing relationships mean **not proven**, not independent.
+- The graph is broader than a code graph, but it is not the entire product.
+- The canonical runner is
+  `npx workspai workspace intelligence run --for-agent codex --strict --json`.
+- `pipeline` is a broader governance/release orchestrator and must not be taught
+  as a replacement for the intelligence chain.
+- The integrated CLI already exposes current capabilities. Future standalone
+  packages are extraction boundaries, not promises to add currently missing CLI
+  features.
+
+Normative machine sources:
+
+| Statement                      | Source of truth                                         |
+| ------------------------------ | ------------------------------------------------------- |
+| Ordered intelligence chain     | `contracts/workspace-intelligence-chain.v1.json`        |
+| Runtime commands and flags     | `contracts/runtime-command-surface.v1.json`             |
+| Published schemas and paths    | `contracts/published-contract-catalog.v1.json`          |
+| Architecture boundaries        | `contracts/workspace-intelligence-architecture.v1.json` |
+| Artifact writers and consumers | `docs/contracts/ARTIFACT_CATALOG.md`                    |
+
+Markdown summarizes these contracts; it does not redefine them.
+
+## Claim policy
+
+Every performance or token statement must identify:
+
+- the workspace or pinned corpus;
+- the query and result limit;
+- whether token counts are estimated, tokenizer-counted, or provider-reported;
+- the baseline;
+- the date or revision;
+- what the measurement does not prove.
+
+The current fixture may be used only with wording equivalent to:
+
+> On the current 16-project development fixture, one bounded query reduced the
+> estimated retrieval payload by 97.9%; results vary by workspace and query.
+
+Never turn a retrieval-payload result into a universal model-cost, answer-quality,
+or task-success claim. Use `workspace eval` and a verified outcome before making
+execution-efficiency comparisons.
+
+## Command policy
+
+- Quickstarts must be copyable and use the canonical `workspai` package.
+- `wspai` is described only as an optional short alias.
+- A partial sequence such as `model → context` must not be taught as a replacement
+  for the canonical intelligence chain.
+- Every documented command must exist in the runtime command surface or be an
+  ordinary shell command such as `cd` or `npm install`.
+- Durable filenames must come from published contracts or the Artifact Catalog.
+
+## Information hierarchy
+
+Write for three reading depths:
+
+1. **Ten seconds:** category, user problem, three outcomes.
+2. **Two minutes:** quickstart, concrete artifacts, architecture, proof example.
+3. **Deep evaluation:** measurements, contracts, guides, boundaries, contributor
+   material.
+
+Prefer user questions and outcomes over internal phase names. Define unavoidable
+terms in plain language and link to the glossary.
+
+## Validation
+
+Run from `packages/cli`:
+
+```bash
+npm run validate:docs
+npm run check:generated-contracts
+npm run check:contracts
+```
+
+`docs-drift-guard.mjs` enforces the required root headings, their order,
+canonical runner, Model/Graph truth boundary, honest measurement language,
+documentation routes, and package-status semantics. `smoke-readme-commands.mjs`
+executes representative documented CLI help surfaces.
+
+## Review checklist
+
+Before merging a README change, confirm:
+
+- a new user can explain Workspai without saying “chatbot” or “code generator”;
+- the first quickstart reaches a durable evidence artifact;
+- every architecture statement agrees with the generated contracts;
+- every number is reproducible and bounded;
+- every promised output exists today or is explicitly labelled as future work;
+- links route users by goal rather than exposing the documentation tree;
+- the package table cannot be read as a list of missing product capabilities.

package/docs/commands-reference.md

@@ -65,7 +65,8 @@ npx workspai workspace snapshot [--workspace <path>] [--json] [--include-paths]
 npx workspai workspace diff --from <snapshot-or-report|git[:ref]> [--workspace <path>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace impact --from <workspace-diff-report> [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>] [--strict]
 npx workspai workspace verify [--from-impact <file>] [--workspace <path>] [--scope project:<name>] [--strict] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
-npx workspai workspace graph [emit|explain|dot|mermaid] [key] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
+npx workspai workspace graph [emit|explain|search|benchmark|entities|evidence|path|overlay|dot|mermaid|jsonld|graphml|gexf] [key] [value] [--from <graph.json>] [--output <file>] [--limit <1..100>] [--workspace <path>] [--scope project:<name>] [--json] [--include-paths] [--include-evidence] [--scan-depth <count>]
+npx workspai workspace eval [init <task> [strategy]|record|status|report|compare --from <report>] [--workspace <path>] [--output <file>] [--json]
 npx workspai workspace watch [--workspace <path>] [--json] [--once] [--scan-depth <count>]
 npx workspai workspace explain|why <target> [--workspace <path>] [--json] [--write]
 npx workspai workspace trace --from <workspace-diff-report> [--workspace <path>] [--json] [--write]
@@ -94,6 +95,17 @@ npx workspai infra down [--workspace <path>] [--volumes]
 npx workspai infra status [--workspace <path>] [--json] [--strict]
 ```
 
+The contract graph includes its backward-compatible service projection, the
+canonical `workspace-dependency-graph.v1` project topology, and the portable
+`workspace-knowledge-graph.v1` evidence graph. The knowledge projection covers
+workspace/project structure, packages and dependencies, source files, modules,
+symbols, HTTP endpoints, OpenAPI/GraphQL/Protocol Buffers/AsyncAPI contracts,
+Compose/Kubernetes/Dockerfile/Terraform/Helm infrastructure, CI workflows,
+documentation, ADRs, tests, owners, environments, databases, and queues.
+Every entity and relation has stable identity and portable proof paths; proof
+taxonomy separates authored, extracted, and inferred facts and records trust,
+confidence, and freshness. Environment and secret values are never emitted.
+
 `workspace intelligence run` writes
 `.workspai/reports/workspace-intelligence-run-last-run.json`. Its `preflight`
 contains exactly `sync` and `baseline`, while `stages` contains exactly the 11
@@ -114,9 +126,57 @@ records are appended to
 `.workspai/reports/workspace-intelligence-history.json`; no separate feedback
 artifact is created.
 
-`workspace graph dot` and `workspace graph mermaid` intentionally emit raw DOT
-and Mermaid text for direct piping to renderers. Use `workspace graph emit
---json` or `workspace graph explain <project> --json` for structured JSON.
+`workspace graph emit --json` returns both the compatibility project graph and
+the knowledge graph. Use `workspace graph entities [kind]`, `workspace graph
+evidence <id-or-unique-label>`, and `workspace graph path <from> <to>` for
+indexed queries. `workspace graph overlay --from <prior-graph.json>` produces a
+portable change/PR overlay with additions, removals, changed fields, proof
+artifacts, proof additions/removals/content changes, bounded one-hop impact,
+and a risk summary. Observation timestamps and freshness alone do not create
+false change noise. Query indexes are cached
+per immutable graph object and invalidated automatically when a new graph is
+built. `dot` and `mermaid` intentionally remain project-topology renderers and
+emit raw text for direct piping.
+
+`workspace graph search <query> --limit <n> --json` returns bounded entities,
+one-hop relations, related entity summaries, and portable proofs instead of the
+complete graph. `workspace graph benchmark <query> --limit <n> --json` compares
+that retrieval payload with the readable proof-indexed corpus using a labelled
+`characters / 4` estimate. It measures payload reduction only; it does not
+assert equivalent answer quality or model-specific billing savings.
+
+`workspace graph jsonld|graphml|gexf` exports the current derived,
+evidence-backed Knowledge Graph for semantic, graph-analysis, and interactive
+2D/3D consumers.
+Use `--output <file>` for a durable export; Mermaid and DOT remain the compact
+documentation-oriented renderings.
+
+`workspace eval` records provider/tokenizer/estimate provenance, tool activity,
+cost, latency, and verified task outcome. `eval record` accepts a
+`model-usage-event.v1` JSON document on stdin. The live and finalized artifacts
+are suitable for IDE dashboards and conform to
+`workspace-intelligence-evaluation.v1`.
+
+`workspace model --write` also materializes the derived, contract-validated
+knowledge graph at `.workspai/reports/workspace-knowledge-graph.json`. The
+unified intelligence runner treats that artifact as a required output of the
+Model step, so CI, IDE adapters, agent grounding, and MCP all observe the same
+revision. Agent contexts carry its reference, quality counts, and bounded query
+commands instead of copying the entire graph into every prompt. MCP exposes
+`getWorkspaceKnowledgeGraph`, `searchWorkspaceGraph`, `queryWorkspaceEntities`,
+`getWorkspaceGraphEvidence`, and `findWorkspaceGraphPath`.
+
+Source extraction is bounded and language-neutral by contract. It recognizes
+the primary source formats for TypeScript/JavaScript, Python, Go, Java/Kotlin,
+.NET/F#, Rust, Ruby, PHP, Swift, Dart, Elixir, Scala, Clojure, Lua, R, C/C++,
+Vue, and Svelte. Package baselines also recognize npm/Deno, Python, Go, Cargo,
+Maven/Gradle, NuGet, Composer, Ruby, Elixir, Dart, SwiftPM, CMake, Bazel, and SBT.
+Regex-backed
+source facts are marked `observed` with medium confidence; authored manifests
+and interface/infrastructure specifications remain authoritative. This avoids
+presenting heuristic symbol discovery as compiler-grade truth while keeping the
+current CLI useful until deeper language providers move into the standalone
+graph package.
 
 See [workspace-run.md](./workspace-run.md) for fleet orchestration semantics.
 

package/docs/config-file-guide.md

@@ -14,7 +14,7 @@ Supported fields include:
 {
   "defaultKit": "fastapi.standard",
   "defaultInstallMethod": "poetry",
-  "pythonVersion": "3.11",
+  "pythonVersion": "3.10",
   "author": "Platform Team",
   "license": "MIT",
   "skipGit": false,
@@ -56,7 +56,7 @@ Example:
 module.exports = {
   workspace: {
     defaultAuthor: 'Platform Team',
-    pythonVersion: '3.11',
+    pythonVersion: '3.10',
     installMethod: 'poetry',
   },
   projects: {
@@ -66,6 +66,10 @@ module.exports = {
 };
 ```
 
+Python-backed workflows require Python 3.10 or newer. `pythonVersion` selects a
+project target; it does not make Python a dependency for Node-only or other
+Python-free Workspai workflows.
+
 ## Command coverage
 
 Directory configuration is currently consumed by the legacy top-level creation