# `4.7.0` Project Source Diagnostics And Recovery

Status: Planned

## Goal

Make project-source selection and startup failures understandable enough that a
chat-host user can recover without reading internals or raw tracebacks.

## Public API Changes

The chat-host path should expose clearer project-source diagnostics:

- `pyro doctor` should report the active project-source kind and its readiness
- `pyro mcp serve` and host helpers should explain whether they are using
  tracked local files, `--project-path`, `--repo-url`, or no project source
- startup failures should recommend the right fallback:
  `--project-path`, `--repo-url`, `--no-project-source`, or explicit
  `seed_path`

## Implementation Boundaries

- keep diagnostics focused on the chat-host path rather than inventing a broad
  source-management subsystem
- prefer actionable recovery guidance over long implementation detail dumps
- make project-source diagnostics visible from the same surfaces users already
  touch: help text, `doctor`, host helpers, and startup errors

## Non-Goals

- no generic repo-health audit product
- no attempt to auto-fix arbitrary local checkout corruption
- no host-specific divergence in project-source behavior

## Acceptance Scenarios

- a user can tell which project source the chat host will use before creating a
  workspace
- a user who hits a project-source failure gets a concrete recovery path instead
  of a raw permission traceback
- host helper doctor and repair flows can explain project-source problems, not
  only MCP config problems

## Required Repo Updates

- docs, help text, and troubleshooting updated with project-source diagnostics
  and fallback guidance
- at least one smoke or targeted CLI test covering the new failure guidance
- host-helper docs updated to show when to prefer `--project-path`,
  `--repo-url`, or `--no-project-source`