Add project-aware chat startup defaults

Make repo-root chat startup native by letting MCP servers carry a default project source for workspace creation. When a chat host starts from a Git checkout, workspace_create can now omit seed_path and inherit the server startup source; explicit --project-path and clean-clone --repo-url/--repo-ref paths are supported as fallbacks.

Add project startup resolution and materialization, surface origin_kind/origin_ref in workspace_seed, update chat-host docs and the repro/fix smoke to use project-aware workspace creation, and switch dist-check to uv run pyro so verification stays stable after uv reinstalls.

Validated with uv lock, focused startup/server/CLI pytest coverage, UV_CACHE_DIR=.uv-cache make check, UV_CACHE_DIR=.uv-cache make dist-check, and real guest-backed smokes for both explicit project_path and bare repo-root auto-detection.

docs/first-run.md

@@ -27,7 +27,7 @@ Networking: tun=yes ip_forward=yes
 
 ```bash
 $ uvx --from pyro-mcp pyro env list
-Catalog version: 4.0.0
+Catalog version: 4.1.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -71,13 +71,26 @@ streams, so they may appear in either order in terminals or capture tools. Use
 
 ## 5. Start the MCP server
 
-Bare `pyro mcp serve` now starts `workspace-core`, which is the intended chat
-path:
+Bare `pyro mcp serve` now starts `workspace-core`. From a repo root, it also
+auto-detects the current Git checkout so the first `workspace_create` can omit
+`seed_path`:
 
 ```bash
 $ uvx --from pyro-mcp pyro mcp serve
 ```
 
+If the host does not preserve the server working directory:
+
+```bash
+$ uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
+```
+
+If you are outside a local checkout:
+
+```bash
+$ uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
+```
+
 ## 6. Connect a chat host
 
 Claude Code:

docs/install.md

@@ -92,7 +92,7 @@ uvx --from pyro-mcp pyro env list
 Expected output:
 
 ```bash
-Catalog version: 4.0.0
+Catalog version: 4.1.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -140,13 +140,26 @@ deterministic structured result.
 
 ## 5. Connect a chat host
 
-Bare `pyro mcp serve` now starts `workspace-core`, which is the default
-product path.
+Bare `pyro mcp serve` now starts `workspace-core`. From a repo root, it also
+auto-detects the current Git checkout so the first `workspace_create` can omit
+`seed_path`.
 
 ```bash
 uvx --from pyro-mcp pyro mcp serve
 ```
 
+If the host does not preserve the server working directory, use:
+
+```bash
+uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
+```
+
+If you are starting outside a local checkout, use a clean clone source:
+
+```bash
+uvx --from pyro-mcp pyro mcp serve --repo-url https://github.com/example/project.git
+```
+
 Copy-paste host-specific starts:
 
 - Claude Code setup: [claude_code_mcp.md](../examples/claude_code_mcp.md)
@@ -182,7 +195,8 @@ The intended user journey is:
 1. validate the host with `pyro doctor`
 2. pull `debian:12`
 3. prove guest execution with `pyro run debian:12 -- git --version`
-4. connect Claude Code, Codex, or OpenCode with `pyro mcp serve`
+4. connect Claude Code, Codex, or OpenCode with `pyro mcp serve` from a repo
+   root, or use `--project-path` / `--repo-url` when needed
 5. start with one use-case recipe from [use-cases/README.md](use-cases/README.md)
 6. trust but verify with `make smoke-use-cases`
 

docs/integrations.md

@@ -15,12 +15,26 @@ through [install.md](install.md) or [first-run.md](first-run.md).
 
 ## Recommended Default
 
-Bare `pyro mcp serve` starts `workspace-core`. That is the product path.
+Bare `pyro mcp serve` starts `workspace-core`. From a repo root, it also
+auto-detects the current Git checkout so the first `workspace_create` can omit
+`seed_path`. That is the product path.
 
 ```bash
 pyro mcp serve
 ```
 
+If the host does not preserve cwd, fall back to:
+
+```bash
+pyro mcp serve --project-path /abs/path/to/repo
+```
+
+If you are outside a repo checkout entirely, start from a clean clone source:
+
+```bash
+pyro mcp serve --repo-url https://github.com/example/project.git
+```
+
 Use `--profile workspace-full` only when the chat truly needs shells, services,
 snapshots, secrets, network policy, or disk tools.
 
@@ -33,6 +47,12 @@ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
 claude mcp list
 ```
 
+If Claude Code launches the server from an unexpected cwd, use:
+
+```bash
+claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
+```
+
 Already installed:
 
 ```bash
@@ -53,6 +73,12 @@ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
 codex mcp list
 ```
 
+If Codex launches the server from an unexpected cwd, use:
+
+```bash
+codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo
+```
+
 Already installed:
 
 ```bash
@@ -87,6 +113,10 @@ Minimal `opencode.json` snippet:
 If `pyro-mcp` is already installed, replace `uvx --from pyro-mcp pyro` with
 `pyro` in the same config shape.
 
+If OpenCode launches the server from an unexpected cwd, add
+`"--project-path", "/abs/path/to/repo"` after `"serve"` in the same command
+array.
+
 ## Generic MCP Fallback
 
 Use this only when the host expects a plain `mcpServers` JSON config and does

docs/public-contract.md

@@ -76,10 +76,16 @@ pyro mcp serve
 What to expect:
 
 - bare `pyro mcp serve` starts `workspace-core`
+- from a repo root, bare `pyro mcp serve` also auto-detects the current Git
+  checkout so `workspace_create` can omit `seed_path`
 - `workspace-core` is the default product path for chat hosts
 - `pyro mcp serve --profile workspace-full` explicitly opts into the larger
   tool surface
 - `pyro mcp serve --profile vm-run` exposes the smallest one-shot-only surface
+- `pyro mcp serve --project-path /abs/path/to/repo` is the fallback when the
+  host does not preserve cwd
+- `pyro mcp serve --repo-url ... [--repo-ref ...]` starts from a clean clone
+  source instead of a local checkout
 
 Host-specific setup docs:
 
@@ -111,7 +117,8 @@ Host-specific setup docs:
 
 That is enough for the normal persistent editing loop:
 
-- create one workspace
+- create one workspace, often without `seed_path` when the server already has a
+  project source
 - sync or seed repo content
 - inspect and edit files without shell quoting
 - run commands repeatedly in one sandbox

docs/roadmap/llm-chat-ergonomics.md

@@ -6,7 +6,7 @@ goal:
 make the core agent-workspace use cases feel trivial from a chat-driven LLM
 interface.
 
-Current baseline is `4.0.0`:
+Current baseline is `4.1.0`:
 
 - `pyro mcp serve` is now the default product entrypoint
 - `workspace-core` is now the default MCP profile
@@ -79,7 +79,7 @@ capability gaps:
 9. [`3.10.0` Use-Case Smoke Trust And Recipe Fidelity](llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md) - Done
 10. [`3.11.0` Host-Specific MCP Onramps](llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md) - Done
 11. [`4.0.0` Workspace-Core Default Profile](llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md) - Done
-12. [`4.1.0` Project-Aware Chat Startup](llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md) - Planned
+12. [`4.1.0` Project-Aware Chat Startup](llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md) - Done
 13. [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md) - Planned
 14. [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md) - Planned
 15. [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md) - Planned
@@ -114,10 +114,12 @@ Completed so far:
   config manually.
 - `4.0.0` flipped the default MCP/server profile to `workspace-core`, so the bare entrypoint now
   matches the recommended narrow chat-host profile across CLI, SDK, and package-level factories.
+- `4.1.0` made repo-root startup native for chat hosts, so bare `pyro mcp serve` can auto-detect
+  the current Git checkout and let the first `workspace_create` omit `seed_path`, with explicit
+  `--project-path` and `--repo-url` fallbacks when cwd is not the source of truth.
 
 Planned next:
 
-- [`4.1.0` Project-Aware Chat Startup](llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md)
 - [`4.2.0` Host Bootstrap And Repair](llm-chat-ergonomics/4.2.0-host-bootstrap-and-repair.md)
 - [`4.3.0` Reviewable Agent Output](llm-chat-ergonomics/4.3.0-reviewable-agent-output.md)
 - [`4.4.0` Opinionated Use-Case Modes](llm-chat-ergonomics/4.4.0-opinionated-use-case-modes.md)

docs/roadmap/llm-chat-ergonomics/4.1.0-project-aware-chat-startup.md

@@ -1,6 +1,6 @@
 # `4.1.0` Project-Aware Chat Startup
 
-Status: Planned
+Status: Done
 
 ## Goal
 

docs/use-cases/repro-fix-loop.md

@@ -14,13 +14,16 @@ reset back to baseline.
 
 Chat-host recipe:
 
-1. Create one workspace from the broken repro seed.
-2. Run the failing command.
-3. Inspect the broken file with structured file reads.
-4. Apply the fix with `workspace_patch_apply`.
-5. Rerun the failing command in the same workspace.
-6. Diff and export the changed result.
-7. Reset to baseline and delete the workspace.
+1. Start the server from the repo root with bare `pyro mcp serve`, or use
+   `--project-path` if the host does not preserve cwd.
+2. Create one workspace from that project-aware server without manually passing
+   `seed_path`.
+3. Run the failing command.
+4. Inspect the broken file with structured file reads.
+5. Apply the fix with `workspace_patch_apply`.
+6. Rerun the failing command in the same workspace.
+7. Diff and export the changed result.
+8. Reset to baseline and delete the workspace.
 
 This is the main `workspace-core` story: model-native file ops, repeatable exec,
 structured diff, explicit export, and reset-over-repair.