Lingtai Tui Anatomy

LingTai Go Anatomy — navigation guide

Canonical owner

The repository-root ANATOMY.md is both the normative anatomy-of-anatomy and the top of the distributed code-navigation graph. Per-folder ANATOMY.md files are the content. This bundled skill is the discoverable navigation aid: when it and the repository root disagree, the repository root governs.

An Anatomy file maps structure, connections, composition, and state beside the code it describes. It is not a user manual, behavior contract, design history, or test specification. The paired root CONTRACT.md owns interfaces and expected behavior; the repository-local dev guide owns contribution workflow.

How to navigate

1. Open the repository-root ANATOMY.md and read Components plus Composition.
2. Choose tui/ANATOMY.md for terminal UI, subprocess launch, agent inventory, lifecycle controls, and /viz; choose portal/ANATOMY.md for the web server, embedded frontend, topology, and replay.
3. Descend to the named package Anatomy and open the cited file:line range.
4. Treat code as structural truth. If a citation or ownership claim drifted, update the relevant Anatomy in the same change.
5. Use search for enumeration only (every callsite/file); use Anatomy for structural ownership and data-flow questions.

Runtime-boundary route

For questions such as “Does closing the TUI stop my agent?”, “How do I attach again?”, “Who owns lifecycle?”, or “Should I add launchd?”:

1. Start at root ANATOMY.md → tui/ANATOMY.md, section Runtime/control-surface boundary.
2. Follow its same-repo anchors for normal Bubble Tea quit, kernel subprocess launch and duplicate-process prevention, startup attachment, explicit /sleep//suspend//cpr//refresh, inventory, and Portal process release.
3. Use portal/ANATOMY.md for Portal's own process and shutdown boundary.
4. Load lingtai-kernel-anatomy for exact kernel heartbeat, listener, signal, and lifecycle internals. Do not cite sibling-repo files from TUI Anatomy.

Expected conclusion: TUI and Portal are control/presentation processes, not the kernel agent runtime. Normal UI exit is not an agent lifecycle action. Ordinary agent persistence therefore does not require launchd; an extra supervisor can instead race the existing duplicate-launch guard.

Question-to-node map

Citation discipline

The root Anatomy owns the full schema and maintenance contract. Keep these working rules resident:

• Cite repo-root-relative same-repo paths with verified line ranges, for example tui/internal/tui/app.go:640-670.
• Never put sibling lingtai-kernel file citations in this repo's Anatomy; route there narratively.
• Keep parent/child Anatomy links reciprocal where the root convention requires them, and do not create empty leaf stubs.
• Update Anatomy only for real structural ownership/state/navigation facts; do not paste user guidance or duplicate well-named code.
• After edits, run the repository's architecture smoke tests, citation/graph checks, focused package tests, and git diff --check; then open every changed citation to verify semantics, not only path/range existence.

Finding local agents

For “which agents are alive?”, “where is that agent?”, or “which channel handles are advertised?”, start with lingtai-tui list --detailed; add --admin when admin fields matter, or use /projects for the interactive view. Only then descend to tui/ANATOMY.md and the inventory/processscan nodes for source.

Cross-repo boundary

This Go repository and the Python kernel are separate source trees. TUI Anatomy may say that the kernel writes a file the TUI reads, but exact Python paths, heartbeat loops, channel listeners, signal handling, and agent lifecycle belong in the kernel's own Anatomy graph. Use lingtai-kernel-anatomy rather than copying or citing that implementation here.

Found a bug or issue? If you encounter a problem in this navigation route, load lingtai-issue-report, assemble source evidence, and obtain the required human authorization before filing.