umtri-mcp 1.0.0

package/core/resources/system-structure.md

@@ -0,0 +1,229 @@
+# Rule: Nodes Represent Information Structures, Not Code Files
+
+When modelling a project in Umtri, nodes should be **information units** —
+the parts a *user or external tool* can perceive — not implementation files.
+
+## The distinction
+
+- ❌ **Wrong (developer view)**: nodes named after code files
+  — `index.jsx`, `NodeLayer.jsx`, `routes/projects.js`.
+- ✅ **Right (user view)**: nodes named after the information unit
+  — "tree diagram", "header", "node table", "projects API".
+
+A single information unit may be implemented by several files. The mapping
+from concept to code lives in `metadata.implements` (array of file paths),
+not in the node label.
+
+## Completeness — map the whole project, don't summarise
+
+The "information unit, not file" rule is about **labelling grain, not
+coverage.** It tells you *how to name and group* nodes — it does **not** tell
+you to leave parts of the project out. The goal is a **faithful, navigable map
+of the entire codebase**: every meaningful module, screen, endpoint, table,
+external integration, and piece of non-obvious logic should be locatable in the
+tree (a node with `metadata.implements`).
+
+- **Cover everything, at the right grain.** Group files into information units
+  so it's not one node per file — but do not drop whole capabilities. If a
+  maintainer would expect to find feature X in the repo, X must be findable in
+  the tree.
+- **Don't abstract a project down to a sketch.** A handful of trunks with a few
+  leaves each is almost always *under*-captured. Real projects have many leaves;
+  a faithful tree is large. Breadth is expected — `get_graph` slicing (rootId /
+  maxType / descriptions) exists precisely so a big, complete tree stays cheap
+  to read.
+- **The restraint rules are not licence to omit.** "Reserve veins" (vocabulary)
+  means don't turn *every function* into a vein — not skip the logic worth
+  finding. "Bushy is fine, don't over-nest" means don't add empty grouping
+  layers — not prune real branches. Group and pick good grain; keep the coverage.
+- **Completeness pass.** After modelling, walk the repo and check: is there a
+  directory, module, route file, table, or integration with **no** node? If so,
+  it's a gap — add it. Aim for "every real part of the system is represented,"
+  not "the gist is represented."
+- **Completeness has a boundary.** It covers what *runs*, not everything in the
+  repo — documents, build output and inert config stay out. See "What is NOT a
+  node" below before treating an uncovered path as a gap.
+
+## What is NOT a node — the boundary of completeness
+
+Completeness pushes you to cover everything that *runs*. It is not a licence to
+map everything that *exists in the repo*. The tree answers "what is this system
+made of," so anything that only **describes** the system stays out.
+
+**The test: if you deleted it, would the system behave differently?** If no, it
+is not a node.
+
+Keep out:
+
+- **Internal documents** — PRDs, RFCs/ADRs, READMEs, CHANGELOGs, design notes,
+  roadmaps. These are *about* the system. Mixing them in makes the map answer
+  two questions at once ("what runs" and "what we wrote down") and it stops
+  being a reliable map of either.
+- **Build output and vendored code** — `dist/`, `build/`, lockfiles,
+  `node_modules/`.
+- **Tooling config with no runtime behaviour** — linter/formatter configs,
+  editor settings, `.gitignore`.
+
+Point at documents instead of turning them into nodes: put the reference in the
+`description` of the node it explains (e.g. "propagation rules:
+`PRD-impact-analysis.md`"). The document stays findable exactly where someone
+would look for it, without becoming a branch.
+
+**The exception that matters: documentation you ship is a system.** A docs site
+served to users (its pages, its i18n, its shell) is a product surface and
+belongs in the tree. The line is not "markdown vs code" — it is *served to
+users* vs *read by us*.
+
+## Trunk and limb rules
+
+- `trunk` = a big domain (e.g. `www`, `server`, `db`). Pick stable,
+  long-lived names — usually matching a top-level code area.
+- `limb` = a category inside a trunk (e.g. `graph`, `table`, `dashboard`).
+- Do **not** create one limb per time period. Time is expressed through
+  `season` and `created_at`, not by carving the tree into temporal slices.
+- Infrastructure (servers, DNS) is *not* a trunk — it is the environment the
+  system runs in, not a part of the system. For documents, see "What is NOT a
+  node" above.
+
+## Useful metadata keys
+
+These conventions let other tools (including this MCP) answer richer
+questions about a ground.
+
+| Key                  | Applies to                          | Shape                                              |
+| -------------------- | ----------------------------------- | -------------------------------------------------- |
+| `implements`         | all nodes                           | `string[]` — file paths, optionally `path#identifier` |
+| `created_by_commit`  | all nodes                           | `string` — git short hash                          |
+| `replaces`           | follow-up node                      | `string[]` — node ids that were absorbed           |
+| `replaced_by`        | deprecated node                     | `string[]` — node ids that took over               |
+| `endpoints`          | API-domain twigs                    | `{method, path, summary}[]`                        |
+| `columns`            | DB-domain twigs                     | `{name, type, pk?, fk?}[]`                         |
+| `represents`         | UI twigs reflecting data            | `string` — corresponding DB twig id                |
+| `reparented_at`      | reparented nodes                    | `string` — ISO date when the parent changed        |
+| `reparented_from`    | reparented nodes                    | `string` — prior parent id                         |
+| `reparented_to`      | reparented nodes                    | `string` — new parent id                           |
+| `extracted_from`     | nodes decomposed from a parent file | `string` — original node id                        |
+| `role_change_at`     | type-changed nodes                  | `string` — ISO date                                |
+| `role_change_reason` | type-changed nodes                  | `string` — short prose explaining the shift        |
+| `placeholder`        | intentionally-empty structure       | `true` — opts out of dormant cleanup suggestions   |
+
+## One file, multiple nodes
+
+A single source file may legitimately decompose into multiple nodes when it
+contains several distinct information units. Example: `AppShell.jsx` exports
+`Sidebar`, `NavItem`, `UserMenu`, `Intro`, `MobileDrawer` — each is its own
+component and earns its own `leaf` node. The split uses two metadata keys:
+
+- `metadata.implements`: array of `file#identifier` references — e.g.
+  `"www/src/components/layout/AppShell.jsx#Sidebar"`. The `#identifier`
+  suffix points at the exported function/class within the file.
+- `metadata.extracted_from`: id of the node that originally represented the
+  whole file. Preserves the decomposition history so the prior shape stays
+  inspectable.
+
+Decompose when the units are independently reusable, separately addressable,
+or named distinctly by users. Do **not** decompose just because a file has
+many internal helpers — pure implementation details stay inside the leaf.
+
+## Restructuring history
+
+Trees evolve. When a node moves to a different parent, record the move in
+metadata so the restructure stays inspectable later:
+
+- `metadata.reparented_at` — ISO date (e.g. `"2026-05-21"`)
+- `metadata.reparented_from` — prior parent id
+- `metadata.reparented_to` — new parent id
+
+The MCP `update_node` tool emits a `reparent-metadata-hint` info warning
+when you change `parent` without including these keys. Recording the move
+matters because the ltree path silently rewrites on parent change — without
+these keys, you can't tell from the current state that the node ever moved.
+
+When the type also changes (twig → leaf, limb → twig, …), add
+`role_change_at` and a short `role_change_reason` so the reclassification
+stays explainable. Pair with `replaces` / `replaced_by` when one node
+absorbs another (e.g. an ad-slot twig absorbing its sole leaf child).
+
+## When adding a node
+
+Ask first: *"What part of the system does this represent for someone using
+or maintaining it?"* If the answer is a file, you're probably one level too
+deep — go up to the information unit and add the file under
+`metadata.implements`. If the answer is a single exported component within
+a larger file, the node is still legitimate — use `path#identifier` in
+`implements` and add `extracted_from` pointing at the file-level node.
+
+## Connections — consider an edge or api each time you add a node
+
+The tree shows *containment* (what lives under what). It does **not** show how
+things relate across branches — that's what edges and apis are for. After you
+add a leaf or vein, pause and ask: **does this node call, feed, or depend on
+another node?** If so, record the connection — the graph is only half-true
+without it.
+
+- **api** (`create_api`) — a **request / call / data flow** between two nodes:
+  a screen calling an endpoint, an endpoint hitting a table, an external
+  integration (NicePay, SMS, a webhook). First-class because flows are the
+  story of how the system runs. Direction is caller → callee (`start` → `end`).
+- **edge** (`create_edge`) — a **structural relation**: `dependency` ("A is
+  built on / needs B") or `data_flow` ("data moves A → B" outside a request).
+  Use for module/library dependencies, a route depending on the data store, a
+  job writing to a table. Direction is `source` → `target`.
+
+Rule of thumb: if it's a *runtime request*, it's an api; if it's a *build-time
+or structural reliance*, it's a dependency edge. Don't connect everything —
+add the connections that a maintainer would actually want to trace (cross-module
+calls, external integrations, the few key dependencies). A standalone leaf with
+no real relation needs no edge; skipping is fine. But the common failure is the
+opposite — adding nodes and never their connections, leaving a tree of isolated
+islands.
+
+### How problems propagate along a connection
+
+The arrow records *who calls / depends on whom*. **Impact — which node is hurt
+when another breaks — does not always flow with the arrow.** Read each
+connection type as follows when tracing a blast radius:
+
+| Connection        | Arrow means                     | A problem propagates                                    |
+| ----------------- | ------------------------------- | ------------------------------------------------------- |
+| edge `dependency` | `source` is built on / needs `target` | **against the arrow** — if `target` breaks, `source` is affected (target → source) |
+| edge `data_flow`  | data moves `source` → `target`  | **with the arrow** — bad data at `source` corrupts `target` (source → target) |
+| api (`start`→`end`) | caller → callee               | **against the arrow** — if the callee (`end`) is down, the caller (`start`) fails (end → start) |
+
+So "what is affected if X breaks?" = walk **dependency edges backward** (to their
+sources) ∪ **data_flow edges forward** (to their targets) ∪ **apis backward**
+(to their callers), transitively. This is the rule the `get_impact` tool
+implements.
+
+Two cautions:
+- The result is a **list of nodes to check, not a proven failure set** — it is
+  only as complete as the connections you have recorded. A sparse graph yields
+  a falsely small blast radius; treat an empty result as "nothing recorded,"
+  not "nothing affected."
+- A connection can carry impact **both ways** in reality (a dependency that also
+  passes data back). Record the dominant direction; when in doubt, trace impact
+  in both directions rather than trusting a single arrow.
+
+## The file-as-leaf antipattern
+
+A common drift: a twig groups a concept (e.g. `Bug log API`), and its only
+child is a leaf named after the implementation file (`bugs.js`). This is
+**one information unit split into two nodes** — the twig and the leaf
+describe the same thing at different vocabularies.
+
+Symptoms:
+- Twig with exactly one leaf child whose label is a filename.
+- Leaf label echoes the twig label plus a file extension.
+- The leaf carries no additional information the twig doesn't already have.
+
+Fix: absorb the file into the twig's `metadata.implements`, then soft-delete
+the leaf. The twig itself becomes the information unit; the file is its
+implementation detail, not a separate node. Decompose into multiple leaves
+*only* when the file contains several independently-meaningful units (see
+"One file, multiple nodes" above).
+
+The MCP `create_node` / `update_node` tools emit a `file-as-leaf` info
+warning when a leaf is created with a filename- or path-shaped label, and
+an `implementation-jargon` warning when any label uses code-architecture
+words (router/handler/middleware/layer/store/...) — both push toward
+naming the information unit rather than the implementation.

package/core/resources/transplant.md

@@ -0,0 +1,63 @@
+# Rule: Transplanting a ground (옮겨심기)
+
+A ground that was **not** born in Umtri — an existing project imported for the
+first time — needs heavy restructuring before its shape settles. To allow
+that, a freshly created ground starts in a **transplanting** state, where the
+normal guardrails are relaxed. When the human is satisfied with the shape they
+**root** the ground (뿌리내리기), and the guardrails snap back on.
+
+`get_graph` returns `project.transplanting` (boolean). Check it before doing
+anything that the normal rules would block.
+
+## While `transplanting = true`
+
+You MAY:
+- **Add or edit nodes in any season, including past seasons.** The usual
+  "cannot create/move into a past season" and "grown (past-season) nodes are
+  immutable" rules are lifted, so you can reconstruct the project's history
+  season by season.
+- **Hard-delete import mistakes.** `delete_node` accepts `hard: true` and the
+  active-descendant guard is lifted (subtree cascades). Use this to remove
+  wrongly-imported nodes for good. Soft delete is still the default; reach for
+  `hard` only to clean up genuine mistakes — it is irreversible.
+
+You MAY NOT:
+- **Create or modify seasons.** Seasons are always human-only
+  (see umtri://rules/seasons-human-only). The human lays down the historical
+  seasons; you fill nodes into them.
+- **Root (settle) a ground.** Ending transplant is human-only — done from the
+  UI ("Root this ground"). You cannot root via MCP.
+
+## Re-opening transplant (`reopen_transplant`)
+
+A rooted ground can be put back into transplant with the `reopen_transplant`
+tool — but **only when the user explicitly asks for it** (e.g. "switch this
+ground to transplanting", "옮겨심기로 바꿔줘"). This removes safety guardrails,
+so you must **never** decide to re-open on your own initiative, however
+convenient it would be for a restructuring task. No explicit request → do not
+call it; instead tell the user the ground is rooted and ask whether they want
+to re-open transplant. After re-opening, the user roots it again from the UI
+when the work is done.
+
+## Audit stamp
+
+Every node you create while the ground is transplanting is automatically
+stamped `metadata.transplanted = true`. The stamp persists after rooting so a
+human can later see which nodes entered during the unsettled period. Do not
+remove it.
+
+## After rooting (`transplanting = false`)
+
+All normal guards return: past seasons reject new/moved nodes, grown nodes are
+immutable, `delete_node` is soft-only and refuses nodes with active children.
+Treat the tree as settled — small, observable changes only
+(see umtri://about/vision).
+
+## How to behave
+
+- Use the relaxed window to get the **structure** right — it is still an
+  information-structure diagram, not a work log (see umtri://rules/vocabulary).
+  Reconstruct what the project *is*, not the history of commits.
+- Prefer soft delete; reserve `hard` for clear mistakes.
+- When the shape looks settled, tell the human it's ready to root — don't keep
+  operating in transplant mode longer than needed.

package/core/resources/vision.md

@@ -0,0 +1,46 @@
+# About Umtri
+
+Umtri is a platform for visualising **how a project grows over time**.
+A project is a *ground*; from it rise *trunks* (apps, services); seasons
+pass; branches and leaves accumulate; bugs erode; APIs connect.
+
+## Why this exists
+
+Complex systems forget their own past. As code and decisions pile up, the
+question *"why is it like this?"* becomes harder to answer than *"how does
+it work?"*. Umtri is a project archaeology tool: a place to trace and
+back-trace structure, dependencies, and decisions across the lifetime of a
+project.
+
+## Primary purposes
+
+- **Track growth** — see how a project's structure expanded season by season.
+- **Trace dependencies** — follow API flows and references across the tree.
+- **Locate origins** — when something is broken or surprising, find the
+  point in time and space where it entered the system.
+- **Open to tools** — Umtri exposes its data through a REST API and this
+  MCP server, so AI assistants, CI pipelines, issue trackers, and IDEs can
+  read and contribute alongside humans.
+
+## Tone for tools
+
+When you (an AI tool) work on an Umtri ground:
+
+- Prefer the language of the metaphor over generic terms — *grounds, trunks,
+  limbs, twigs, leaves, veins, seasons, bugs*. It is intentional.
+- Treat the project as alive. Names, season transitions, and bugs carry
+  meaning the user assigned; do not "tidy up" without asking.
+- Default to small, observable changes. The point of Umtri is to make the
+  history of a project legible — silent bulk edits defeat that.
+
+## What this MCP is not
+
+- It is not a code-editing tool. It does not read or write source files —
+  an external agent does that, using the plan tree as its brief
+  (see `umtri://rules/plan`).
+- It does not run CI/CD jobs. Instead it is the **configuration-record hub**
+  that CI integrates with: commits are recorded back onto the nodes they
+  touched (`metadata.implements`, `metadata.commits`) via the API — e.g. a
+  GitHub Action calling `record_commit` on merge. Umtri stores the form; it
+  does not execute the pipeline.
+- It does not create seasons (see `umtri://rules/seasons-human-only`).

package/core/resources/vocabulary-detailed.md

@@ -0,0 +1,278 @@
+# Umtri Vocabulary — Detailed Guidance
+
+Read this only when you are restructuring an existing tree, auditing legacy
+data, or wrestling with a borderline classification. The core rules live in
+`umtri://rules/vocabulary`; this resource expands them.
+
+## Hierarchy rules (convention, not schema-enforced)
+
+| Parent role | Allowed child role(s)         | Note                                                       |
+| ----------- | ----------------------------- | ---------------------------------------------------------- |
+| structure (trunk/limb/twig) | structure / object | can hold each other or jump straight to a `leaf`           |
+| object (`leaf`)             | action (`vein`) only | a leaf cannot branch back into structure                 |
+| action (`vein`)             | —                  | **vein is terminal — no children**                         |
+
+The schema accepts any combination. The MCP warns when violated but lets
+the data through (legacy migration, experimental use). For new authoring,
+follow the table strictly.
+
+**Skip-level traversal is allowed within structure**: `trunk → leaf`,
+`limb → leaf`, even `trunk → twig` are valid. The full descent
+`trunk → limb → twig → leaf → vein` is canonical, not mandatory.
+
+## Trunk = system-unit, not domain
+
+A `trunk` must be a **deployable system or independent service** — something
+you could point at, deploy, or replace as a whole. Apps, databases, servers,
+external services. Examples that fit: `user-app`, `api-server`, `iot-server`,
+`db`, `www`, `kiosk-app`.
+
+Domains or feature areas (auth, payments, reservations, dashboard, …) are
+**`limb`**, not trunk. They live inside a trunk. "Authentication is a domain
+that spans the user-app and admin trunks" — fine. "Authentication is a
+trunk" — no.
+
+Naming convention (recommended, not enforced):
+- Apps: `<name>-app` (e.g. `user-app`, `kiosk-app`)
+- Servers: `<name>-server` (e.g. `api-server`, `iot-server`)
+- Infra: short single words (`db`, `www`, `cdn`)
+
+## Leaf vs vein — extended heuristics
+
+`leaf` (object) and `vein` (action) look adjacent but carry opposite intents:
+
+- **leaf** — the thing that exists. A component, class, domain entity,
+  screen, card. Noun phrase.
+- **vein** — what the object *does*: a method, function, or operation that
+  exists on it. Verb phrase naming a standing **capability** — not a task,
+  patch, migration step, or change that was performed. A vein is `환불 처리`
+  ("processes refunds"), never `환불 버그 수정` (a completed task).
+
+Korean label patterns:
+
+| Pattern                                                              | Type | Example                                                  |
+| -------------------------------------------------------------------- | ---- | -------------------------------------------------------- |
+| Noun-final / domain model                                            | leaf | `예약 카드`, `결제 정책`, `사용자 메뉴`                  |
+| UI components (모달·카드·페이지·대시보드·패널·화면·표·뷰)            | leaf | `랜딩 페이지`, `매출 대시보드`, `공지 이미지 리사이저`   |
+| Verb-final capability (`…충전`·`…차감`·`…환불`·`…조회`·`…발송`·`…등록`·`…검증`·`…동기화`·`…집계`) | vein | `포인트 충전`, `세션 검증`, `방문 집계`                  |
+| Handlers / methods / crons / jobs (standing capabilities)           | vein | `레슨 자동 완료 cron`, `방문 집계 핑`                    |
+
+Note the boundary with the work-log rule: a vein names an operation the
+object *performs* (a capability that stays true tomorrow), not the act of
+fixing/adding/migrating it. `정적 파일 캐시 버스팅` (a capability the build
+has) is a vein; `캐시 버스터 추가` (work done) is not a node at all.
+
+**Vein litmus — one vein ≈ one locatable code unit.** A vein earns its place
+when you can point to where it lives (a function, guard, calculation, cron) —
+it should carry `metadata.implements`. Reserve veins for the *non-obvious,
+worth-finding-again* logic: business invariants, security, money math
+(`코트·시간대 중복 예약 방지`, `보너스 포인트 FIFO 차감`, `휴대폰 AES-256-GCM
+암호화`). Do **not** explode every endpoint into CRUD veins, and do **not**
+turn a requirement or rule you can't point to in code into a vein — that
+belongs in the leaf's `description`, or as a `bug`/plan node. A good tree uses
+veins sparingly (often <10% of nodes); a forest of veins under every leaf is
+the over-veining smell.
+
+## Reclassification policy (for AI auditors)
+
+When migrating or auditing legacy data, AI tools **may reclassify** a `leaf`
+node to `vein` (or vice-versa) **only if both** hold:
+
+1. The label clearly fits the opposite category by the heuristics above.
+2. The node has **no children** (vein cannot have children).
+
+Always make reclassification edits **one node at a time**, with the label
+visible in the diff. Bulk regex sweeps over labels are explicitly disallowed
+— the Korean heuristics are advisory, not deterministic. When unsure, leave
+the node alone and surface it as a question.
+
+## Build order — leaf-driven, depth-first
+
+The canonical descent `trunk → limb → twig → leaf → vein` describes the
+*shape* of a finished tree. It is **not** an instruction to build the tree
+breadth-first (all trunks, then all limbs, then all leaves). Building that
+way produces a skeleton of empty structure and forces you to guess the IA
+top-down before you know what actually lives in it.
+
+**Author one leaf at a time, depth-first.** The leaf (or vein) is the only
+node that names a thing that genuinely exists; trunk/limb/twig exist solely
+to hold leaves. So let the leaf pull its ancestors into being:
+
+```
+for each information unit you want to record (a leaf or vein):
+    path = [trunk, limb, twig?] it belongs under
+    create_node for each ancestor in path that does NOT exist yet  (reuse the rest)
+    create_node for the leaf, with metadata.implements
+    create_node for each vein the leaf owns
+```
+
+Worked example — recording two screens in a `user-app`:
+
+1. First leaf `예약 카드` lives under `user-app › 예약 › 예약 화면`.
+   - `user-app` (trunk) missing → create it.
+   - `예약` (limb) missing → create it.
+   - `예약 화면` (twig) missing → create it.
+   - create leaf `예약 카드`.
+2. Next leaf `결제 버튼` lives under `user-app › 결제 › 결제 화면`.
+   - `user-app` already exists → reuse.
+   - `결제` (limb) missing → create it.
+   - `결제 화면` (twig) missing → create it.
+   - create leaf `결제 버튼`.
+
+Each new leaf reuses the ancestors earlier leaves already built and only
+creates structure where the path diverges.
+
+**Why depth-first by leaf beats breadth-first by layer:**
+
+- **No dormant scaffolding.** Every trunk/limb/twig gets its first leaf in
+  the same pass, so the `structure-without-children` warning fires only for
+  genuinely-intended placeholders — not for half-built layers.
+- **Structure is earned, not guessed.** You decide a `limb` exists *because*
+  a concrete leaf needs a home, not by sketching an org chart first. This is
+  also when the twig-vs-skip-to-leaf decision (next section) is actually
+  answerable — you can see how many siblings the concept really has.
+- **Recoverable if interrupted.** Stop after any leaf and the tree is a set
+  of complete branches, not a headless skeleton.
+
+A trunk or limb with no leaf descendant *during authoring* is the signal
+you've slipped back into layer-by-layer mode. Add its first leaf before
+moving on, or don't create the structure node yet.
+
+## Twig vs jump straight to leaf
+
+`twig` is for **information groups** — a cluster of related leaves under a
+shared concept. Use it only when you have (or expect to soon have) multiple
+sibling `leaf` nodes that belong together.
+
+If the concept boils down to *one* component, file, or object, **skip twig
+and put the leaf directly under the limb**.
+
+| Case                                                                                       | Use                                                  |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| One React component, one file, one service                                                 | `limb → leaf` directly. No twig.                     |
+| Several leaves that share a clear theme (e.g. design system = Button, Modal, Field, …)     | `limb → twig → leaf+`                                |
+| Several components composing one flow (e.g. auth = SignIn, Login, SignUp)                  | `limb → twig → leaf+`                                |
+| A single file that decomposes into multiple meaningful units                               | Multiple leaves with `metadata.implements` carrying `path#identifier` (see system-structure) |
+
+A twig with no leaves is dormant. Skipping twig when only one object lives
+underneath keeps the tree readable.
+
+The MCP `create_node` tool emits a `structure-without-children` info
+warning when you create a `limb` or `twig`, reminding you that the node
+renders dormant until a leaf/vein appears.
+
+## Tree shape — bushy is fine, don't over-nest
+
+A healthy Umtri tree is **bushy, not deep**: most nodes sit at the middle
+levels (limbs and their leaves), and the full `trunk → limb → twig → leaf →
+vein` descent is reached only where the detail genuinely warrants it. Depth
+is *earned by content*, not added for tidiness.
+
+The biggest pressure toward unnecessary depth is the urge to group siblings
+that merely share a name. **Sharing a label prefix is not, by itself, a
+reason to create a twig.** Korean domain labels naturally share prefixes
+(`예약 생성` / `예약 취소`, `포인트 충전` / `포인트 환불`) — two or three such
+siblings under a limb are perfectly legible as-is. Insert a twig only when a
+parent is genuinely crowded (≈4+ leaves) *and* a real sub-theme groups
+several of them. Wrapping every pair in a twig makes the tree taller and
+harder to read, not easier.
+
+`get_graph` (summary) returns a `shape` block — `maxDepth`, nodes per level,
+and `wideBranches` — plus a `childCount` on each branch node. Use it to judge
+the tree before restructuring: mass concentrated at mid-levels with a shallow
+`maxDepth` is the goal, not a smell. Over-wide trunks are usually fine (a
+trunk's children are top-level domains); an over-wide **limb** (many direct
+leaves) is the case the `junk-drawer-limb` / `sibling-cluster` hints flag.
+
+## Promotion signals — when a twig should be a limb
+
+Some concepts start as twigs nested inside a domain limb but actually
+deserve sibling-limb status. Treat these as **promotion signals** when
+authoring or restructuring:
+
+| Signal                                                  | Example                                                          |
+| ------------------------------------------------------- | ---------------------------------------------------------------- |
+| Route-independent global shell                          | A sidebar shown on every screen, a global header                 |
+| Distinct entry flow (splash → continuation)             | Login + signup pages reached before the main app                 |
+| Globally reusable assets                                | Design tokens + shared components + global toasts                |
+| Domain limb growing into a "junk drawer" (>5 unrelated twigs) | A `dashboard` limb absorbing sidebar + auth + UI + pages   |
+
+When any apply, create the unit as a **limb sibling** of the original
+domain limb rather than burying it as a twig.
+
+The MCP `create_node` and `update_node` tools emit a
+`twig-promotion-candidate` info warning when a twig's `description`
+mentions promotion signals (전역, 라우트 비종속, 스플래시, 재사용 자산,
+global, route-independent, splash, …).
+
+## Labels as information units (anti-patterns)
+
+A label should name the thing a user or external observer perceives, not
+the code construct implementing it.
+
+| Anti-pattern label                                  | Problem                                  | Better                                                |
+| --------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------- |
+| `Bugs router`, `Auth middleware`, `Webhook handler` | names the Express artifact                | `Bug log API`, `Request authorization`, `Provider webhooks` |
+| `API layer`, `Service tier`, `Data store`           | layer/tier/store = architectural plumbing | split by domain, name the surface                     |
+| `store.js`, `middleware/auth.js`, `index.jsx`       | filenames belong in `metadata.implements` | `Persistence`, `Auth guard`, `Graph root`             |
+| `Helper`, `Manager`, `Bootstrap`, `Wrapper`         | generic dev nouns, no info content        | the actual responsibility it carries                  |
+
+The `file-as-leaf` warning also catches the **redundant-child antipattern**:
+a twig whose only child is a leaf named after the same concept's file is
+just one node split into two. Absorb the file into the twig's
+`metadata.implements` and remove the leaf. The twig itself *is* the
+information unit; the file is its implementation.
+
+Apply these on existing data only when a node's label clearly violates the
+rule. Coordinated bulk renames go one node at a time with the diff visible.
+
+## Dormant cleanup — group by branch
+
+When proposing dormant cleanup, group by parent so the user can decide on
+whole branches at once rather than one node at a time. Common reasons a
+node is dormant:
+
+- Placeholder for upcoming work (intentional outline)
+- A plan sketched before any code landed
+- A stale outline that was never filled in (cleanup candidate)
+
+If a node's season is `past` and the label is vague, the user may choose
+to soft-delete. Nodes with `metadata.placeholder = true` are excluded —
+respect that marker and do not flag them.
+
+## Back-filling historical projects (`sproutedAt`)
+
+When importing a project that existed **before Umtri** — past commits,
+migrated trees, archaeological work on legacy code — the node's "creation
+moment" is the original event, not the moment the record landed in Umtri.
+
+`create_node` (and `update_node`) accept an optional `sproutedAt` field
+(ISO 8601 with offset, e.g. `"2024-03-15T09:00:00Z"`). When set, **the
+visualization timeline follows this value** — sibling order, season
+visibility masking, and the events feed all use `sproutedAt` as the
+effective creation moment. The system audit timestamp (`created_at`,
+which records when the row landed in the database) stays untouched and is
+not surfaced in graph responses.
+
+Guidelines:
+
+- **Default behavior is correct for live work.** Omit `sproutedAt` for any
+  node created in the present — the system timestamp is the truth.
+- **Use only for back-fill.** Importing past commit history, recovering a
+  deleted project, migrating from another tool, dogfooding a project's
+  history into Umtri. Do not back-date "for clarity" on live work.
+- **Order matters.** When importing many nodes, set `sproutedAt` to their
+  real historical timestamps so sibling order and season visibility line
+  up. Random or batch-identical timestamps produce a deformed timeline.
+- **Pair with `season`.** Place each back-filled node in the season that
+  was active at its `sproutedAt`. Otherwise the slider will hide nodes
+  whose season has not yet started at T = `sproutedAt`.
+- **Clearing.** `update_node` with `patch.sproutedAt = null` clears the
+  override; the node falls back to its system timestamp.
+- **Cannot back-fill `removed_at` or `grown_at`.** These follow the system
+  clock; only the *birth* of a node can be antedated.
+
+Past-season nodes are still rejected from new `create_node` calls (the
+"cannot create node in past season" rule). For full back-fill of an
+archived season, set the target season to `now` first, import, then
+human-promote it back to `past` via the seasons UI.