umtri-mcp 1.0.2 → 1.2.0

package/README.md

@@ -73,7 +73,7 @@ nodes are meant to be realized, and how a ground behaves while transplanting.
 ```
 umtri://rules/vocabulary            umtri://rules/transplant
 umtri://rules/vocabulary-detailed   umtri://rules/plan
-umtri://rules/seasons-human-only    umtri://about/vision
+umtri://rules/seasons               umtri://about/vision
 umtri://rules/system-structure
 ```
 

package/core/api-client.js

@@ -36,7 +36,12 @@ export function createApiClient({ baseUrl, getToken }) {
     if (!res.ok) {
       const text = await res.text().catch(() => '');
       if (res.status === 403) {
-        throw new Error(`${method} ${path} → 403: token lacks write scope. Generate a 'write' token in Settings → API Tokens.`);
+        // 403은 한 가지가 아니다 — write scope 없음과 admin 전용 경로(feedback 관리 등)가 같이 온다.
+        // 서버가 준 이유를 버리고 토큰 안내로 덮으면, 관리자 경로에서 막힌 사람이 멀쩡한 토큰을
+        // 다시 발급하러 간다. 이유를 그대로 싣고, 스코프 문제일 때만 발급 안내를 덧붙인다.
+        const reason = text.slice(0, 200) || 'forbidden';
+        const hint = /scope/i.test(text) ? " Generate a 'write' token in Settings → API Tokens." : '';
+        throw new Error(`${method} ${path} → 403: ${reason}${hint}`);
       }
       throw new Error(`${method} ${path} → ${res.status}: ${text.slice(0, 200)}`);
     }

package/core/instructions.js

@@ -0,0 +1,20 @@
+// MCP initialize 응답의 instructions — 클라이언트가 세션 시작에 모델에게 그대로
+// 전달한다. 서버가 먼저 말을 걸 수 있는 유일한 자리다(리소스·도구는 불러야 열린다).
+//
+// 그래서 여기엔 "언젠가 읽으면 좋은 것"이 아니라 **읽지 않으면 조용히 어긋나는 것**만
+// 둔다. 매 세션 컨텍스트에 실리므로 길어지면 그 자체가 비용이고, 길수록 안 읽힌다.
+// 상세는 전부 umtri://rules/* 리소스로 넘긴다.
+//
+// send_feedback 문단이 여기 있는 건 그 기준의 예외처럼 보이지만 아니다. 도구 목록에
+// 이름이 있어도 모델은 요청받은 일만 하므로, 이 한 줄이 없으면 도구는 있고 아무도
+// 부르지 않는 상태로 남는다. 마찰을 가장 먼저 겪는 건 에이전트인데 그 관찰은 세션이
+// 끝나면 사라진다. "사람에게 권한다"까지가 문단의 핵심이다 — 자율 발송을 허용하면
+// 접수함이 에이전트의 불평으로 먼저 죽는다.
+
+export const SERVER_INSTRUCTIONS = `Umtri maps a project's structure as a tree (trunk → limb → twig → leaf → vein) and tracks how it changes over seasons. Start with list_projects, then get_graph.
+
+Umtri never reads git. A commit reaches the ground only because something called create_node / update_node / record_commit — so the tree drifts behind the code unless the repo has a habit that says otherwise. If this repo's own rules file (CLAUDE.md, AGENTS.md, …) has no commit-sync policy, read umtri://rules/commit-sync and offer the human a short one to paste in.
+
+Before creating or reclassifying nodes, read umtri://rules/vocabulary. Opening a season seals the current one, so create_season only acts after the user confirms (umtri://rules/seasons).
+
+If Umtri itself gets in your way — a call rejected for a reason that looks wrong, a capability that is missing, a tool description that misled you — tell the human what happened and offer to file it with send_feedback. Never file it on your own initiative.`;

package/core/policy.js

@@ -231,6 +231,93 @@ export function reparentMetadataHint(patch) {
   };
 }
 
+// ── wiki 본문 ────────────────────────────────────────────────────────
+// 위키를 로그로 쓰는 경향이 실제로 관찰됐다 — 작업을 끝낸 에이전트가 페이지를 열어
+// "이번에 뭘 했는지"를 덧붙이고, 몇 번 반복되면 페이지가 세션 요약 더미가 된다.
+// 규칙 문서(umtri://rules/wiki)에 적어뒀지만 리소스는 pull-only라 안 읽으면 그만이라,
+// 쓰는 순간에 신호를 준다.
+//
+// **거부하지 않고 경고만 한다.** 판정이 휴리스틱이고, 날짜가 정당하게 필요한 문서도
+// 있기 때문이다(마이그레이션 위험 고지 등). 오탐이 잦으면 경고 자체가 무시되므로
+// 정밀도가 높은 신호만 고른다 — 셋 다 산문형 레퍼런스에는 거의 나오지 않는 형태다.
+// 날짜가 제목 **앞머리**에 올 때만 잡는다. "## 2026-08-27 — 인증 분리"는 일지 항목이지만
+// "## 확정된 결정 (2026-07-28)"은 결정에 날짜를 단 것이라 정당하다. 괄호 안 날짜까지
+// 잡으면 오탐이 늘고, 오탐이 늘면 경고를 아무도 안 본다.
+const WIKI_DATE_HEADING_RE = /^#{1,6}\s*[([]?\s*20\d{2}\s*[-./년]\s*\d{1,2}\s*[-./월]\s*\d{1,2}/m;
+const WIKI_CHANGELOG_HEADING_RE = /^#{1,6}\s*(?:.*(?:change\s*(?:log|history)|revision history|release notes|변경\s*(?:이력|내역)|작업\s*이력|업데이트\s*내역|진행\s*(?:표시|상황)).*)$/im;
+const WIKI_CHECKBOX_RE = /^\s*[-*+]\s*\[[ xX]\]/gm;
+
+export function wikiLogShapeCheck(body) {
+  if (!body || typeof body !== 'string') return [];
+  const out = [];
+
+  if (WIKI_DATE_HEADING_RE.test(body)) {
+    out.push({
+      rule: 'wiki-dated-entry',
+      severity: 'warn',
+      message: 'This body has a date heading. A wiki page is a description of how something works now, not a dated log — the page\'s own past is kept in its revisions (list_wiki_revisions) and who-changed-what in list_events. Fold the fact into the prose and drop the date, unless the date is itself a live hazard a reader must know.',
+    });
+  }
+
+  if (WIKI_CHANGELOG_HEADING_RE.test(body)) {
+    out.push({
+      rule: 'wiki-changelog-section',
+      severity: 'warn',
+      message: 'This body has a change-history / progress section. Revisions already record what the page said before, so that section duplicates them and goes stale. Delete it and let the prose describe the current state.',
+    });
+  }
+
+  const boxes = body.match(WIKI_CHECKBOX_RE);
+  if (boxes && boxes.length >= 3) {
+    out.push({
+      rule: 'wiki-progress-checklist',
+      severity: 'info',
+      message: `This body has ${boxes.length} checklist items. Outstanding work belongs in bugs (create_bug) or plan nodes, where it can be tracked and closed — a checklist in a wiki page is read by nobody and rots. Keep the page to what is true now.`,
+    });
+  }
+
+  return out;
+}
+
+// ── 도구 호출 마크업 유출 ────────────────────────────────────────────
+// 인자가 필드로 쪼개지지 못하고 첫 필드에 통째로 들어오는 사고가 실제로 있었다
+// (feedback #1: create_bug을 세 번 부르는 동안 세 번 다 solution이 description 꼬리에
+// 문자열로 붙고 solution은 null로 저장됐다). 긴 산문 필드 둘이 나란히 오면 특히 잦다.
+//
+// 저장 자체는 성공하므로 아무도 모른 채 지나가고, 사람이 앱에서 볼 때에야 드러난다.
+// 그래서 쓰기 응답에 그 자리에서 신호를 준다.
+//
+// **거부하지 않고 경고만 한다.** 도구 포맷을 *설명하는* 산문이 이 조각들을 정상적으로
+// 담기 때문이다 — 하필 이 프로젝트의 위키가 그런 글을 쓴다. 대신 코드펜스와 인라인
+// 코드를 걷어내고 검사한다: 설명하는 글은 따옴표 안에 넣고, 진짜 유출은 맨몸으로 온다.
+// 이 구분이 오탐을 거의 없앤다.
+const TOOL_MARKUP_RES = [
+  /<\/?(?:antml:)?parameter\b/i,
+  /<\/?(?:antml:)?invoke\b/i,
+  /<\/?(?:antml:)?function_calls\b/i,
+  /<\/(?:description|solution|body|title|label|note|metadata)>/i,
+];
+
+function withoutCode(text) {
+  return text.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`]*`/g, ' ');
+}
+
+// fields: { 필드이름: 값 } — 문자열이 아닌 값은 건너뛴다.
+export function toolMarkupCheck(fields) {
+  const out = [];
+  for (const [name, value] of Object.entries(fields || {})) {
+    if (!value || typeof value !== 'string') continue;
+    const bare = withoutCode(value);
+    if (!TOOL_MARKUP_RES.some((re) => re.test(bare))) continue;
+    out.push({
+      rule: 'tool-markup-leaked',
+      severity: 'warn',
+      message: `The "${name}" value contains raw tool-call markup (e.g. "</${name}>" or "<parameter name=...>"). That means this call's arguments were not split into fields: the text meant for the next parameter was appended to this one, and that parameter was almost certainly saved empty. Read the record back and re-send the values as separate arguments — nothing else will report this. (Writing *about* tool-call syntax is fine: put it in a code fence or inline code, which this check ignores.)`,
+    });
+  }
+  return out;
+}
+
 // ── bug lifecycle ────────────────────────────────────────────────────
 // Bug Codex reads status as three states: open=wild, in_progress=chasing,
 // resolved|closed=catched. The recommended path is wild → chasing → catched:

package/core/resources/commit-sync.md

@@ -0,0 +1,55 @@
+# Recommendation: Keep a Commit-Sync Policy in the Repo
+
+**Umtri never reads your git history by itself.** It has no job runner and no
+repo access — a node learns about a commit only because something called
+`record_commit`, and it learns about a *new* file only because something called
+`create_node`. Nothing in this server can interrupt you at commit time.
+
+That is why the tree drifts: code moves forward, the ground stays where it was,
+and no one finds out until a person compares the two by hand.
+
+## What to do about it
+
+Write a short commit-sync policy into **the repo's own agent rules file** — the
+one every session already loads (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`,
+whatever that project uses). That file is read before the work starts, by the
+same agent that will do the committing. This resource cannot be, because MCP
+resources are pull-only: they are read when someone asks for them, which is
+exactly the moment that never arrives on its own.
+
+This is a recommendation, not a gate. Nothing here blocks a commit, and a
+project that ignores it still works — the ground simply ages faster than the
+code.
+
+## Snippet to adapt
+
+Paste into the repo's rules file and edit to fit the project (translate it if
+the file is in another language — the wording matters less than the trigger):
+
+```markdown
+### Umtri sync (before committing)
+
+Umtri does not read git. When a commit is about to be made, check whether the
+change also belongs in the ground:
+
+1. Changed paths vs `metadata.implements` — does every changed file map to a node?
+   - New unit of the system (route, screen, table, integration) → `create_node`,
+     with `metadata.implements` set. Then wire its connections
+     (`create_edge` / `create_api`) — an unconnected node is invisible to impact.
+   - File moved or renamed → `update_node` on the affected nodes' `implements`.
+     Directory moves are the expensive case: one `git mv` can strand dozens.
+   - Behavior changed but structure did not → nothing to do.
+2. Does the commit close a tracked bug? → `update_bug` (status, and `solution`
+   describing what was actually done).
+3. Then `record_commit` with the SHA and the changed paths.
+
+Ask the human before adding nodes for anything ambiguous — a wrong node is
+harder to notice later than a missing one.
+```
+
+## Where automation fits
+
+CI (a GitHub Action on push) is a good place for step 3 — it never forgets a
+SHA. It is a poor place for steps 1 and 2: by then the commit exists, the log
+is unread, and the run is green either way. Detection belongs in CI; the
+decision belongs where a human or agent is still in the loop.

package/core/resources/plan.md

@@ -41,7 +41,7 @@ back onto the nodes. The human commits when satisfied.
 ## Boundaries
 
 - Plan is independent of seasons; you still cannot create or modify seasons
-  (see umtri://rules/seasons-human-only).
+  (see umtri://rules/seasons).
 - The brief is still an information-structure diagram, not a work log
   (see umtri://rules/vocabulary) — realize the structure the human intends,
   and name nodes as what they are.

package/core/resources/seasons.md

@@ -0,0 +1,47 @@
+# Rule: Seasons Need the Human's Word
+
+A `season` is a deliberate growth epoch — "Q3 2026", "v2 redesign", "PoC".
+It is the unit by which a project owner *consciously breaks time* in their
+ground. You may create one, but never on your own judgment.
+
+## Why this needs confirming
+
+Creating a season is not additive. The ground's current `now` season is sealed
+as `past` and every node in it is marked grown, which locks that node's
+`parent`, `season`, `type` and `sproutedAt`. A season opened because you could
+not decide where a node belonged turns the ground's timeline into noise, and
+the lock it leaves behind is not yours to undo.
+
+## The gate
+
+`create_season` refuses to create anything until the human has agreed.
+
+1. Call it with `slug` and `label` and **no** `confirm`. Nothing is created;
+   you get back the label you proposed and the season that would be sealed.
+2. Put that to the user in your own words — the new season and what closes.
+3. Only once they say yes, call again with `confirm: true`.
+
+Passing `confirm: true` on the first call is a protocol violation, even when
+the user's request seems to imply it. "Move the pre-April work into a PoC
+season" names a season; it does not confirm sealing the current one.
+
+## When not to reach for it at all
+
+Unsure which season a new node belongs to? Do **not** open one.
+
+- Attach it to the existing season whose state is `now`.
+- If no `now` season exists, ask the user which season to attach to.
+
+A missing season is a question for the human, not a gap for you to fill.
+
+## What needs no confirmation
+
+- Reading seasons (`list_seasons`).
+- Attaching new nodes to existing seasons via the `season` field.
+- Suggesting that a new season *might* be useful, and waiting.
+
+## Still human-only
+
+Rooting a ground (ending transplant) stays human-only through the UI, and once
+rooted it cannot be re-opened by anyone but an administrator.
+See umtri://rules/transplant.

package/core/resources/transplant.md

@@ -23,22 +23,26 @@ You MAY:
   `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.
+- **Open a season without asking.** `create_season` exists, but it only acts
+  after the user confirms (see umtri://rules/seasons). Laying down historical
+  seasons is exactly the case where you propose and they decide.
 - **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`)
+## Rooting is final
 
-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.
+Once a ground is rooted, **nothing re-opens transplant** — not you, not the
+person who owns the ground. There is no `reopen_transplant` tool, and
+`POST /api/projects/:slug/root` refuses `rooted: false`. Only an administrator
+can re-open it, out of band.
+
+This is deliberate. Re-opening unlocks every past season at once, so a window
+meant for the first import would otherwise become the standard way around a
+guard. If a rooted ground genuinely needs restructuring, say so plainly and
+let the human decide whether to take it to an administrator.
+
+Most of what people reach for transplanting to do does not need it — a stale
+`metadata.implements` on a past node is editable as it stands (see below).
 
 ## Audit stamp
 

package/core/resources/vision.md

@@ -43,4 +43,4 @@ When you (an AI tool) work on an Umtri ground:
   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`).
+- It does not open a season on its own judgment (see `umtri://rules/seasons`).

package/core/resources/vocabulary.md

@@ -98,7 +98,7 @@ nodes (in `type` or `label`) is the most common mistake.
 
 - Bug / error / issue → `bugs` table — use `create_bug`
 - API / endpoint / integration → `apis` table — use `create_api`
-- Season / sprint / epoch → human-only, see `umtri://rules/seasons-human-only`
+- Season / sprint / epoch → needs the user's confirmation, see `umtri://rules/seasons`
 - Dependency / data flow → `edges` table — use `create_edge`
 
 ## Bug lifecycle — one step at a time

package/core/resources/wiki.md

@@ -0,0 +1,210 @@
+# Writing a Ground's Wiki
+
+The tree holds structure. The wiki holds what the tree cannot: the conventions a
+project settled on, the decisions it made and why, the vocabulary it uses, what
+an investigation concluded.
+
+Two things to remember. The first is the shape of a page:
+
+> **A page is named after a thing, and its revisions are that thing's life.**
+> Revision 1 is the plan. Later revisions are what it became. The newest
+> revision is what is true now.
+
+The second is what a page *is*:
+
+> **A page is a description, not a log.**
+> It tells a reader how something works right now. It does not narrate what
+> happened to it.
+
+Everything below follows from those two.
+
+## Write reference, not a diary
+
+This is the mistake that actually happens. An agent finishes some work, opens
+the page, and appends a paragraph about what it just did. Do that a few times
+and the page is a pile of session summaries that nobody can read as an
+explanation of anything.
+
+**The page should read like an encyclopedia entry for the thing, in the present
+tense.** Someone who arrives knowing nothing should finish it understanding how
+the thing works. They should not have to reconstruct the current state by
+replaying a timeline.
+
+| Log — do not write this | Description — write this |
+| --- | --- |
+| "Added retry logic to the webhook handler today." | "The webhook handler retries three times with backoff. Toss redelivers on any non-2xx, so a slow database would otherwise double-charge." |
+| "## 2026-08-27 — split the auth middleware" | "Auth runs in two stages: session or bearer resolution, then scope check. They are separate because MCP loopback needs the second without the first." |
+| "Phase 1 done, Phase 2 in progress" | (belongs in bugs or plan nodes, not here) |
+| "## Change history" / "## 변경 이력" | (delete it — that is what revisions are for) |
+
+Concretely, a page should not contain:
+
+- **Date headings** or dated entries of any kind
+- **Progress checklists** — "Phase 2 완료", "- [x] W3", "TODO: …"
+- **Sentences about the act of working** — "we added", "이번에 …했다", "next I will"
+- **A changelog section**
+
+### Why this is not a loss
+
+The temporal record already exists, in better places:
+
+| What you want to record | Where it belongs |
+| --- | --- |
+| What this page said before | revisions (`list_wiki_revisions`) |
+| Who changed what, when | the ground's history (`list_events`) |
+| Which commit touched which code | `record_commit` → the node's `metadata.commits` |
+| What still needs doing | bugs (`create_bug`) or plan nodes |
+| What you plan to do | revision 1 of the page, written *before* you build |
+
+**Because the history lives in the revisions, the body is free to be purely
+present-tense.** That is the whole point of versioning the page: you never have
+to keep an old paragraph around just to preserve the record of it. Rewrite the
+sentence to say what is true now, and the previous wording stays readable in the
+revision underneath.
+
+A page that logs is doing, badly, a job four other things already do well — and
+failing at the one job only it can do.
+
+### The exception: what "why" survives
+
+Present tense does not mean stripping the reasoning. "The webhook handler
+retries because Toss redelivers on any non-2xx" is present tense and is exactly
+the sentence worth keeping. The test is not *is this about the past* but **would
+someone changing this code get it wrong without knowing it** — see "What stays
+on the page" below.
+
+Past events belong in a page only when the event is *itself* a live constraint:
+"the `apex` type was renamed to `leaf` in 2026-05; old exports may still carry
+it." That is not a diary entry, it is a hazard a reader needs.
+
+## Name the thing, not the document
+
+A page is called `mcp`, `billing`, `impact-analysis` — the subject it is about.
+
+Never name a page after what it currently *is*: `prd-mcp`, `mcp-spec`,
+`mcp-notes-v2`, `mcp-final`. Those names are accurate for a week. The page that
+begins life as a plan for MCP and ends as the description of the MCP you built
+is the same page the whole time, and `prd-mcp` becomes a lie the moment the
+first line of it ships.
+
+Use lowercase letters, digits and hyphens. Say what a maintainer would say out
+loud: `deploy`, not `deployment-process-documentation`.
+
+If a name turns out wrong, use `write_wiki`'s **`rename`**. Do not create a new
+page and delete the old one — that throws away every revision, which is the part
+of the page that was worth keeping. A rename on its own adds no revision; a
+revision records content, and the name is not content.
+
+## Revision 1 is the plan
+
+Before building something, write the page. What you are about to do, why this
+way, what you decided against. That is revision 1, and it is a real deliverable:
+another agent picking up the work reads it instead of guessing.
+
+This replaces keeping design docs in the repo. A plan in a repo file goes stale
+silently — nothing makes anyone revisit it, and six months later no one can tell
+whether it describes the code or someone's old intention. A plan that is
+revision 1 of a living page cannot rot the same way, because the page keeps
+being updated and the plan stays readable underneath as history.
+
+Plan nodes and this page do different jobs and work together: the plan nodes say
+*where* in the structure something goes, the page says *what and why*. See
+`umtri://rules/plan`.
+
+## Write back what you actually built — with `newRevision: true`
+
+When the thing exists, come back and make the page describe it. Not "the plan
+plus a note that it's done" — the page should now read as a description of what
+is there.
+
+**Pass `newRevision: true` on that write.** This matters more than it looks.
+Writes fold together when they come from the same author within about half an
+hour, so that eight passes of polishing leave one revision instead of eight.
+That folding cannot tell "still drafting the plan" from "the plan has become the
+thing" — clock and author look identical in both cases. Without the flag, an
+agent that plans and then builds in one sitting overwrites its own plan, and
+revision 1 is gone.
+
+Use it whenever the page crosses a boundary: plan → built, v1 → v2, one approach
+abandoned for another. Skip it while you are still working on the same stage.
+
+## What stays on the page, what becomes history
+
+The page is the current state. But "current state" is not just the mechanics —
+**a live reason is part of the current spec.**
+
+| Stays on the page | Becomes history |
+| --- | --- |
+| How it works now | How it used to work |
+| The constraint that makes it work this way | A constraint that no longer applies |
+| A decision you would repeat, and why | The full argument that led to a reversed decision |
+| The conclusion of a reversal: "we tried A, moved to B, because —" | The prose written while A was still true |
+
+The test: **would someone about to change this code get it wrong without
+knowing this?** If yes, it belongs on the page, however old it is.
+
+A rule like "team org keeps `plan='free'` because plan describes that org's own
+subscription and a team org has none" is not history. It is a live trap, and a
+page that files it away as an old decision will get rewritten wrong.
+
+A page that strips out every reason becomes a manual, and a manual is exactly
+the thing the tree could have held. Do not optimize the wiki into uselessness.
+
+## One page per thing
+
+Split when a page starts answering two questions a reader would arrive with
+separately. Merge — or never split — when the answer to one requires the other.
+
+Do not split by document type. `mcp` and `mcp-architecture` are not two pages;
+they are one page at two points in its life. Do not create a page per file, per
+sprint, or per meeting. A ground with forty one-paragraph pages is harder to
+read than the code.
+
+## Choosing how to write
+
+| | |
+| --- | --- |
+| The thing changed | `mode="replace"` — **read the page first** (`get_wiki`) |
+| The page is missing a whole topic you can add as its own section | `mode="append"` |
+| Crossing into a new stage | add `newRevision: true` |
+| A write went wrong | `list_wiki_revisions`, then `mode="restore"` with the rev |
+| You read, thought, then wrote, and someone else may have written meanwhile | add `baseRev` — the write is refused instead of clobbering |
+
+**`append` is the narrow case, not the default.** It is for adding a section
+that was genuinely absent — a new subsystem the page never covered. It is not
+for tacking on what you just did. If your addition would only make sense to
+someone who knows what happened this week, you want `replace`: fold the new fact
+into the sentence that was already there.
+
+After any write, look at what came back. `previousBodyChars` is how long the
+body was before you wrote. If it is much larger than what you just wrote, you
+replaced someone's work — check `list_wiki_revisions` before moving on. Nothing
+is lost, but nobody will tell you later.
+
+## Attaching to nodes
+
+A page can hang off a node or float free. Floating is normal and expected early:
+knowledge arrives before structure, and a page that has to wait for a node is a
+page that never gets written.
+
+Once the tree has grown, list the unattached pages (`list_wiki` with
+`node="none"`) and attach the ones that now have a home. Deleting a node
+detaches its pages rather than deleting them.
+
+## Deleting
+
+Almost never. Deleting removes the page **and its entire revision history** —
+unlike an overwrite, it cannot be undone.
+
+A stale page is not a reason to delete. Rewrite it, and let the old state live
+in its revisions. Delete only a page that should never have existed: a
+duplicate, a test, something filed under the wrong ground.
+
+## What does not belong here
+
+- **Structure** — that is what nodes are for. Do not maintain a prose copy of
+  the tree; it will drift within a week.
+- **Defects** — use bugs. A wiki page is not a to-do list.
+- **Requirements dumped in a ground's description** — that field is a one-line
+  summary, not a spec. Move it here.
+- **Secrets** — tokens, keys, passwords. The wiki is prose, not a vault.

package/core/resources.js

@@ -23,11 +23,11 @@ const RESOURCES = [
     description: 'Reclassification policy, twig vs leaf decision matrix, twig promotion signals, redundant-child antipattern, Korean label heuristics. Read only when restructuring an existing tree or wrestling with a borderline classification.',
   },
   {
-    name: 'seasons-human-only',
-    uri: 'umtri://rules/seasons-human-only',
-    file: 'seasons-human-only.md',
-    title: 'Seasons are human-only',
-    description: 'AI tools must not create seasons. Defaults and exceptions explained.',
+    name: 'seasons',
+    uri: 'umtri://rules/seasons',
+    file: 'seasons.md',
+    title: 'Seasons need the human\'s word',
+    description: 'create_season exists but is gated: the first call only reports what would be sealed, and creation needs confirm:true after the user agrees. Read before opening a season, or when unsure which season a node belongs to.',
   },
   {
     name: 'transplant',
@@ -43,6 +43,20 @@ const RESOURCES = [
     title: 'Plan nodes are a node-based brief',
     description: 'Nodes marked plan:true are the human\'s structural brief (intent expressed as nodes, not a prompt). Read them as instructions, realize the code, attach metadata.implements (required), keep new detail as plan, and leave committing to the human. Read when get_graph shows any plan:true node.',
   },
+  {
+    name: 'commit-sync',
+    uri: 'umtri://rules/commit-sync',
+    file: 'commit-sync.md',
+    title: 'Keep the ground in step with commits',
+    description: 'Umtri never reads git — nodes drift unless something records the change. Recommends writing a short commit-sync policy into the repo\'s own agent rules file (CLAUDE.md/AGENTS.md), with a snippet to adapt. Read when setting Umtri up in a repo, or when a commit turns out to have left the tree behind.',
+  },
+  {
+    name: 'wiki',
+    uri: 'umtri://rules/wiki',
+    file: 'wiki.md',
+    title: 'How to write a ground\'s wiki',
+    description: 'A wiki page is named after a thing, and its revisions are that thing\'s life: rev 1 is the plan, later revisions are what it became, the newest is what is true now. Covers naming (the subject, never "prd-x"), writing the plan first, marking the plan→built boundary with newRevision, what stays on the page versus what becomes history (a live reason is current spec, not history), when to split pages, replace/append/restore/baseRev, attaching to nodes, and why deleting is almost never right. Read before writing or reorganizing wiki pages.',
+  },
   {
     name: 'system-structure',
     uri: 'umtri://rules/system-structure',