pyro-mcp/docs/roadmap/llm-chat-ergonomics/4.7.0-project-source-diagnostics-and-recovery.md

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