feat(tui): explore the purpose-aware repository graph as a Ratatui network

[styler-ai]

Why

ProjectAtlas already knows the purposes and typed relationships of repository folders, files, and symbols. Humans should be able to explore that atlas as a real terminal-native network: start from one selected node, see direct relationships nearby, and understand progressively more distant connections without opening a browser or creating another graph authority.

This is post-v0.4.0 work. It must not delay, change, or expand the v0.4.0 release.

What Changes

• Add a separate projectatlas graph --view tui command implemented with Ratatui.
• Render a purpose-aware 2D network on a Ratatui Canvas: the focused file, folder, or symbol is central; direct neighbors are closest; additional bounded hops appear progressively farther away.
• Distinguish node kinds and typed edges such as containment, imports, calls, dependencies, and ownership without relying on color alone.
• Support keyboard focus movement, pan, zoom, search, depth changes, relation filters, and bounded expand/collapse.
• Show the selected node's path, reviewed purpose, concise summary, type, and visible relation counts in a readable details panel.
• Reuse one bounded service-owned projection over the existing ProjectAtlas SQLite graph. Do not build or persist a second graph.
• Keep node and edge budgets explicit, start from a focused local view, and use stable positioning so the network does not jump unnecessarily between interactions.
• Support the same dark, light, and terminal-background theme choices as the token TUI where practical.

Capabilities

• Focused repository-network exploration for folders, files, and symbols.
• Purpose-aware node inspection and typed relationship navigation.
• Progressive one-hop, two-hop, and three-hop expansion under hard node and edge budgets.
• Terminal-native operation on supported ProjectAtlas platforms without a browser or hosted service.

Architecture Diagrams

• Existing graph authority and bounded projection: Bounded Graph Read With Purpose Projection
• The implementation OpenSpec must update the owning architecture document with the terminal command, projection, interaction, cancellation, and failure flow before implementation is checked complete.

Release Scope

• Target: post-v0.4.0 backlog.
• This issue is not a v0.4.0 release blocker.
• The first releasable slice is the useful focused 1–3 hop network, not an unbounded whole-repository visualization.

Non-Goals

• No browser UI, 3D renderer, cloud service, remote assets, telemetry, or code upload.
• No second database, graph engine, persisted layout authority, or duplicated traversal implementation.
• No attempt to render an entire large repository by default.
• No replacement for agent-facing graph queries, summaries, slices, or Mermaid architecture documentation.
• No pixel-for-pixel copy of Obsidian or another product's visual identity.

Pre-Mortem

• Large graphs become a dense, unreadable hairball. Mitigate with a focused starting node, hard budgets, progressive hop expansion, relation filters, and deterministic overflow messaging.
• Layout movement destroys the user's mental map. Mitigate with deterministic initial placement, stable retained positions, and bounded local relaxation after expansion.
• The TUI invents a second graph contract that drifts from CLI/MCP behavior. Mitigate by owning traversal and projection in the existing service boundary and making Ratatui a rendering/input adapter only.
• Color or terminal differences make relations ambiguous. Mitigate with labels, symbols, line styles, contrast checks, terminal-background support, and real Windows/Linux/macOS visual review.
• Interaction stalls on a huge repository. Mitigate with bounded queries, cancellation, no full-graph default, and representative scale benchmarks before release.

Implementation Checklist

• Create and validate the implementation OpenSpec; map its exact tasks to this issue before coding.
• Specify the user journey, keyboard contract, spatial meaning, graph budgets, stable-layout rules, empty/error states, and accessibility behavior.
• Implement one bounded service-owned graph projection over the existing SQLite entities, purposes, and typed relations.
• Implement projectatlas graph --view tui as a Ratatui adapter with focus, pan, zoom, search, depth, filters, expand/collapse, and a selected-node details panel.
• Cover positive, empty, partial, oversized, cyclic, adversarial, cancellation, multi-project isolation, and compatibility behavior with focused unit/integration tests.
• Add real CLI smoke coverage and platform-appropriate terminal E2E coverage.
• Benchmark projection latency, redraw latency, CPU, memory, and bounded output on small and representative large repositories.
• Visually review wide and narrow terminals in dark, light, and terminal-background themes on supported platforms.
• Update command help, user documentation, and the owning versioned architecture diagrams.