Feedback: make rust-hybrid fallback diagnostics more actionable

[jununfly]

This was generated by AI during triage.

What happened

While using @jununfly/zcodegraph 0.10.2 on a small repository, the CLI worked successfully but produced fallback-degraded diagnostics that were technically useful yet hard to interpret from an agent/user workflow perspective.

Observed flow:

• npm i -g @jununfly/zcodegraph installed 0.10.2 successfully.
• First zcodegraph --version downloaded and verified the platform bundle, then reported 0.10.2.
• zcodegraph init reported the repo was already initialized.
• zcodegraph index completed successfully: 37 files, 498 nodes, 795 edges, rust-hybrid, 69ms.
• The CLI reported Fallback health: degraded with 24 TypeScript fallback files.
• zcodegraph doctor --engine rust-hybrid --bundle --last-run created a bundle and summarized that the index was usable, but fallback-degraded files/diagnostics needed review.

User feedback

The index was usable, which is good. The main friction is that Fallback health: degraded still leaves the user or agent asking: how serious is this, what capabilities are affected, and what should I do next?

For a coding agent, zcodegraph is most valuable as a codebase map: symbol-aware exploration, caller/callee navigation, impact checks, and reduced context waste compared with plain text search. The more the CLI can translate internal index state into next actions, the easier it is for agents and humans to trust the graph.

Suggested improvements

• Make fallback-degraded status more actionable in default CLI output.
• Distinguish clearly between "index is usable", "some precision may be reduced", and "query results may be incomplete".
• In doctor output, summarize fallback files/reasons directly, not only the bundle path.
• Explain which commands/features are affected: search, explore, callers, callees, impact, etc.
• Consider a confidence signal for natural-language or exploratory results, such as high/medium/low confidence depending on whether a symbol path was found or results were keyword-associated.
• Make stale-index or post-edit guidance more explicit, for example listing changed files and recommending zcodegraph sync.
• Keep internal terms such as rust-owned-parse-gap available in JSON/diagnostic bundles, but translate them in human-facing CLI output.

Acceptance criteria

• When fallback health is degraded, the default CLI output explains whether the index is usable and what the degraded state means operationally.
• doctor --bundle --last-run prints a concise decision-oriented summary: affected files/counts, reason groups, likely impact, and recommended next action.
• User-facing output avoids relying only on internal taxonomy names, while preserving detailed internal diagnostics in machine-readable output or bundle files.
• Documentation or CLI help clarifies when to use init, index, sync, and doctor in the global-install workflow.

Blocked by

None - can start immediately.

[jununfly]

Status update after PR #674:\n\n#674 closes the corrupted-DB diagnostic bundle failure mode, but this issue's main degraded fallback diagnostics goal remains open. The remaining work is to make degraded fallback summaries more actionable across default CLI output, doctor output, and status semantics without relying on internal taxonomy names alone.

[jununfly]

Implemented by PR #675 and merged into main.\n\n#675 makes degraded rust-hybrid fallback diagnostics actionable in the default CLI and machine-readable flows: human zcodegraph status shows graph usability, translated top reason groups, the exact doctor command, and the per-file diagnostic artifact; status --json includes fallbackDiagnostics; and doctor --bundle --last-run now names the artifact and next maintainer handoff step.\n\nVerification was recorded in #675: fallback CLI tests, doctor bundle tests, status-json tests, npm run build, and git diff --check.