understand

Understand analyzes a codebase and produces a knowledge-graph.json file that powers an interactive dashboard for exploring the project's architecture, components, and their relationships. Invoked as /understand, it writes into the project's data directory, either .ua/ or the legacy .understand-anything/ when that already exists, and supports both full rebuilds and incremental updates. Command options include --full to force a complete rebuild ignoring any existing graph, --auto-update and --no-auto-update to toggle automatic graph updates on commit, --review to run a full LLM graph-reviewer instead of inline deterministic validation, --language to generate all textual content such as summaries, descriptions, tags, titles, and language notes in a chosen language via ISO 639-1 codes or friendly names, and an optional directory path to analyze a project other than the current working directory.

Execution is organized into seven phases with progress reporting at each transition and during batch processing, which keeps users informed on large codebases where analysis can take a long time. Phase 0 handles pre-flight setup: resolving the project root from arguments or the working directory, and redirecting output to the main repository root when the target is an ephemeral git worktree, detected by comparing the git dir against the git common dir, so the generated graph is not destroyed when the session ends. It also ensures the plugin is built, because later phases run Node scripts that import the core package; on a fresh install it locates the plugin root across several candidate paths, accounting for symlinked installations, and builds the core package with pnpm, requiring Node.js 22 or later and pnpm 10 or later.

Finally it resolves the data directory once for reuse across every read and write in later phases, preserving any existing legacy directory so established projects keep working without migration. The chosen language preference is stored in config.json for consistency across incremental updates, as is the auto-update setting. The overall aim is to give developers a navigable, always-refreshable map of an unfamiliar or large project rather than a static document, with deterministic validation by default and an optional deeper LLM review pass.