umtri-mcp 1.3.3 → 1.4.0

package/README.md

@@ -56,26 +56,34 @@ appear and then error, re-check the token and its scope — `read` tokens cannot
 **Read** — `get_graph`, `get_bug`, `get_impact`, `list_projects`, `list_bugs`, `list_seasons`,
 `list_events`
 
-**Write** — `create_project`, `create_node`, `update_node`, `delete_node`, `create_edge`,
-`delete_edge`, `create_api`, `update_api`, `delete_api`, `create_bug`, `update_bug`, `delete_bug`,
-`create_season` (acts only after the user confirms)
+**Write** — `create_project`, `create_node`, `update_node`, `delete_node` (a subtree only with
+`cascade: true`), `create_edge`, `delete_edge`, `create_api`, `update_api`, `delete_api`,
+`create_bug`, `update_bug`, `delete_bug`, `create_season` (acts only after the user confirms)
 
 **Plan loop** — `commit_plan`, `record_commit`
 
+**Wiki** — `list_wiki`, `get_wiki`, `list_wiki_revisions`, `write_wiki`, `delete_wiki`. The ground's
+encyclopedia: pages form a table of contents (`parent`, `position`) read from an overview down,
+each has a kind, and every write comes back with warnings when a page strays from the skeleton.
+
+**Feedback** — `send_feedback` files a suggestion or defect about Umtri itself.
+
 `get_graph` returns a slice, not a dump: scope by subtree (`rootId`), by layer (`maxType`), by role,
 or by season, and control description weight separately. A large tree stays cheap to read.
 
 ## Resources
 
-Seven read-only documents the agent can pull for domain rules — the plant vocabulary
+Ten read-only documents the agent can pull for domain rules — the plant vocabulary
 (trunk/limb/twig/leaf/vein), what counts as a node and what does not, how seasons work, how plan
-nodes are meant to be realized, and how a ground behaves while transplanting.
+nodes are meant to be realized, how a ground behaves while transplanting, keeping the tree in step
+with commits, and how to write and organize the wiki.
 
 ```
-umtri://rules/vocabulary            umtri://rules/transplant
-umtri://rules/vocabulary-detailed   umtri://rules/plan
-umtri://rules/seasons               umtri://about/vision
-umtri://rules/system-structure
+umtri://rules/vocabulary            umtri://rules/plan
+umtri://rules/vocabulary-detailed   umtri://rules/commit-sync
+umtri://rules/system-structure      umtri://rules/wiki
+umtri://rules/seasons               umtri://templates/wiki
+umtri://rules/transplant            umtri://about/vision
 ```
 
 ## Links

package/core/policy.js

@@ -232,52 +232,9 @@ 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;
-}
+// 위키 판정(로그 형태 + 백과사전 뼈대)은 서버 server/data/wikiLint.js에 있고 쓰기 응답의
+// warnings[]로 온다. 여기 두면 REST로 쓴 문서는 판정을 안 받고, stdio 사용자는 패키지를
+// 새로 받을 때까지 옛 판정에 묶인다.
 
 // ── 도구 호출 마크업 유출 ────────────────────────────────────────────
 // 인자가 필드로 쪼개지지 못하고 첫 필드에 통째로 들어오는 사고가 실제로 있었다

package/core/resources/transplant.md

@@ -55,8 +55,9 @@ remove it.
 
 All normal guards return: past seasons reject new/moved nodes, grown nodes lock
 their shape and timeline, `delete_node` is soft-only and refuses nodes with
-active children. Treat the tree as settled — small, observable changes only
-(see umtri://about/vision).
+active children unless you pass `cascade: true` (only when the human asked to
+remove the whole branch — soft-deleted nodes cannot be restored). Treat the
+tree as settled — small, observable changes only (see umtri://about/vision).
 
 ### What stays editable on a grown node
 

package/core/resources/wiki-templates.md

@@ -0,0 +1,80 @@
+# Wiki Templates
+
+A ground's wiki is read front to back: an overview at the top, chapters under
+it, entries under those. These are recommended tables of contents by project
+type. Pick the one closest to the project, adapt it, and grow into it.
+
+**Use a template as a map, not a stub generator.** Create a page when you have
+something true to write in it — an empty page reads the same as a page nobody
+has written yet, and a table of contents full of them hides the ones that
+matter. The overview and chapter pages come first; entries arrive as knowledge
+does.
+
+How to read the tables:
+
+- Indentation is the tree (`parent`), order is `position`.
+- Titles are plain nouns in the reader's language. Each entry shows an English
+  and a Korean title; use the one that matches the people reading the wiki.
+- `kind` decides the skeleton (see `umtri://rules/wiki`): `overview` needs only
+  a lead, `concept` / `component` need `## Spec`, `rule` needs `## Rules`,
+  `glossary` is a term table.
+- Skip what the project does not have. Add what it has that is not listed.
+
+## Web service
+
+A server-backed product used in the browser: frontend, API server, database,
+deployed somewhere.
+
+| Page | 제목 | kind | What it holds |
+| --- | --- | --- | --- |
+| Overview | 개요 | overview | What the product is, who uses it, the stack in one table, how to read this wiki |
+|   Concepts | 개념 | overview | The domain model a newcomer must learn before the code makes sense |
+|     *one page per core concept* | | concept | The entities and rules of the domain (e.g. order, account, workspace) |
+|   Architecture | 구성 | overview | How the system is put together; one sentence per part below |
+|     Server | 서버 | component | Request pipeline, routing, error shape, where business logic lives |
+|       Authentication | 인증 | component | Sessions/tokens, who can call what |
+|       *one page per server domain* | | component | e.g. billing, notifications, search |
+|     Database | 데이터베이스 | component | Tables, ownership, migrations, invariants the schema enforces |
+|     Frontend | 프론트엔드 | component | Routing, state, design system, i18n |
+|       *one page per major screen or flow* | | component | |
+|     Integrations | 외부 연동 | component | Payment, mail, third-party APIs — contracts and failure modes |
+|   Operations | 운영 | overview | How the product is shipped and kept running |
+|     Deployment | 배포 | rule | Environments, order of steps, what must never be skipped |
+|     *conventions* | | rule | e.g. commit sync, code review, copy and i18n, secrets |
+|   Glossary | 용어 | glossary | Product vocabulary and names that mean something specific here |
+
+## App service
+
+A mobile or desktop app, usually with a backend it talks to.
+
+| Page | 제목 | kind | What it holds |
+| --- | --- | --- | --- |
+| Overview | 개요 | overview | What the app does, platforms, the stack, how to read this wiki |
+|   Concepts | 개념 | overview | The domain model |
+|     *one page per core concept* | | concept | |
+|   Architecture | 구성 | overview | App, backend and the boundary between them |
+|     App | 앱 | component | Navigation, state, offline behaviour, platform differences |
+|       *one page per major screen or flow* | | component | |
+|     Backend | 백엔드 | component | API the app calls, auth, sync |
+|     Device features | 기기 기능 | component | Push, permissions, camera, storage — what the OS allows and when |
+|   Operations | 운영 | overview | |
+|     Release | 릴리스 | rule | Build, signing, store review, versioning, staged rollout |
+|     *conventions* | | rule | |
+|   Glossary | 용어 | glossary | |
+
+## Library
+
+A package other code depends on: SDK, framework, CLI, shared module.
+
+| Page | 제목 | kind | What it holds |
+| --- | --- | --- | --- |
+| Overview | 개요 | overview | What it solves, who depends on it, supported runtimes |
+|   Concepts | 개념 | overview | The mental model users must hold |
+|     *one page per core concept* | | concept | |
+|   Public API | 공개 API | overview | The surface other code relies on |
+|     *one page per module or entry point* | | component | Behaviour, guarantees, errors |
+|   Internals | 내부 구조 | component | How it works inside; what may change without notice |
+|   Operations | 운영 | overview | |
+|     Releases | 릴리스 | rule | Versioning, compatibility promises, deprecation, publishing |
+|     *conventions* | | rule | |
+|   Glossary | 용어 | glossary | |

package/core/resources/wiki.md

@@ -1,22 +1,127 @@
 # 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.
+The tree holds structure. The wiki is **the project's encyclopedia**: it holds
+what the tree cannot — how each part works, the rules the project keeps, the
+concepts it is built on, the words it uses.
 
-Two things to remember. The first is the shape of a page:
+Four things to remember.
 
-> **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 wiki is read front to back.** It is a tree — an overview at the top,
+> chapters under it, entries under those. Someone who reads it in order should
+> come out understanding the project.
 
-The second is what a page *is*:
+> **One page is one entry.** It is named after a thing, and its body is that
+> thing's current spec and rules.
 
-> **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.
+> **Background goes in footnotes.** How it came to be, what was tried before,
+> side notes — `[^name]`, not body text.
+
+> **Revisions are the page's life.** Revision 1 is the plan, later revisions
+> are what it became, the newest is what is true now. The body never narrates
+> that history.
+
+## The table of contents
+
+Every page has a place in the tree: a `parent` page and a `position` among its
+siblings. The app draws the table of contents from it, numbers the entries, and
+links each page to the previous and next one in reading order.
+`list_wiki` with `order="tree"` returns the same order.
 
-Everything below follows from those two.
+- **One overview at the top.** It says what the project is, who it is for, the
+  stack at a glance, and how the wiki is laid out. Only `overview` pages stand
+  at the top level; any other page without a parent is flagged.
+- **Chapters under it** — usually Concepts, Architecture, Operations, Glossary.
+  A chapter page is an `overview` too: a lead and one sentence per page under it.
+- **Entries under the chapters**, nested where one thing is part of another
+  (Authentication under Server, Write policy under MCP).
+- **Order teaches.** Put what a newcomer needs first before what depends on it:
+  the core concept before its details, the server before its domains.
+
+Starting a wiki, or reorganizing one with no clear shape: read
+`umtri://templates/wiki` and pick the table of contents for the project type.
+Grow into it — create a page when there is something true to put in it, not as
+an empty placeholder.
+
+## Titles
+
+A title is **a plain noun for the thing, in the reader's language**: `조직`,
+`배포`, `영향 분석` for a Korean-speaking team; `Organizations`, `Deployment`,
+`Impact analysis` for an English one. Product vocabulary and proper names stay
+as they are (`MCP`, `Season`).
+
+The table of contents is made of titles; it only reads as a structure when each
+line is a name. So no description after a dash or colon, no parenthetical, no
+sentence. "Organizations — tenancy, teams and who pays" belongs in the lead,
+not the title. The write warns about titles that look like that.
+
+## Kinds
+
+Every page has a `kind`. It decides which sections the page needs.
+
+| kind | For | Needs |
+| --- | --- | --- |
+| `overview` | The top page and chapter pages — what is under them and why in that order | a lead only |
+| `concept` | A product or domain concept, a model (node roles, the plan loop) | `## Spec` |
+| `component` | How one part of the system works (MCP, organizations, billing) | `## Spec` |
+| `rule` | A convention that must be kept (commit sync, deploy order) | `## Rules` |
+| `glossary` | The project's vocabulary | nothing — a table or list |
+
+Pick by what a reader arrives asking. "What is X?" is a concept. "How does X
+work / how do I change it?" is a component. "What must I always / never do?" is
+a rule. If a page answers two of these, it is probably two pages — or one
+component page with a strong Rules section.
+
+## The skeleton
+
+```
+Lead paragraph — what this is, in 1–3 sentences.
+
+## 스펙 (Spec)
+How it works now. Break it down with ### headings.
+
+## 규칙 (Rules)
+What you get wrong if you don't know it: invariants, prohibitions, required order.
+
+[^name]: Background, history, rejected alternatives, side notes.
+```
+
+- **The lead comes first**, as a paragraph. Not a heading, not a `> Status:`
+  banner, not a list. A reader who stops after it should know what the thing is.
+- **Only two top-level sections**: `## 스펙` / `## Spec` and `## 규칙` /
+  `## Rules`. Everything else is a `###` under one of them. (`overview` and
+  `glossary` pages are free-form after the lead.)
+- **Spec** is descriptive: how it works. **Rules** is normative: what must hold.
+  "Tokens are hashed with SHA-256" is spec. "Never log a raw token" is a rule.
+- Write the body in the language the project uses; the section names are
+  recognised in Korean and English.
+
+## Footnotes: where background lives
+
+An encyclopedia entry is not stripped of reasons — but it is careful about
+*which* reasons sit in the text.
+
+**The test: would someone about to change this code get it wrong without
+knowing this?**
+
+- **Yes** → it is part of the spec or a rule. Keep it in the body. "The webhook
+  handler retries three times, because Toss redelivers on any non-2xx" — the
+  "because" stops someone from removing the retry.
+- **No** → it is background. Put it in a footnote. How the decision was
+  reached, the approach that came before, who asked for it, a caveat worth
+  knowing but not acting on.
+
+```
+Team orgs keep `plan='free'`.[^plan]
+
+[^plan]: `plan` describes the org's own subscription. An earlier draft billed
+teams through the owner's personal plan; that was dropped when billing moved to
+the team itself.
+```
+
+Footnote syntax is `[^name]` in the text and `[^name]: …` on its own line,
+usually at the end. The app renders references as superscripts and collects the
+definitions into a notes list at the bottom. Every reference needs a
+definition, and every definition needs a reference.
 
 ## Write reference, not a diary
 
@@ -25,26 +130,19 @@ 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 |
+| Log — do not write this | Entry — 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) |
+| "Added retry logic to the webhook handler today." | "The webhook handler retries three times with backoff." (+ the reason, in the body or a footnote) |
+| "## 2026-08-27 — split the auth middleware" | "Auth runs in two stages: session or bearer resolution, then scope check." |
+| "> Status: Phase 1–3 implemented" | (nothing — progress lives in bugs and plan nodes) |
+| "Decision ⑦: tokens capped at 3" | A rule: "A user holds at most 3 active write tokens." |
 | "## 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
+A page does not contain dated headings, status or source banners, progress
+checklists, sentences about the act of working ("we added", "이번에 …했다"),
+or a changelog section. A numbered decision log is the same mistake in a
+different shape: turn each live decision into a spec sentence or a rule, and
+move how it was decided into a footnote.
 
 The temporal record already exists, in better places:
 
@@ -53,158 +151,103 @@ The temporal record already exists, in better places:
 | 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 still needs doing, what is undecided | 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.
+Past events belong in the body only when the event is *itself* a live
+constraint: "the `apex` type was renamed to `leaf`; old exports may still carry
+it." That is not a diary entry, it is a hazard.
 
-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 write tells you what is off
 
-### 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.
+`write_wiki` answers with `warnings[]` when the saved page strays from the
+skeleton: no kind, no parent (outside the table of contents), a title that is
+not a plain noun, no lead, a status banner, a dated heading, a checklist, a
+change-history section, a top-level section other than Spec/Rules, a missing
+required section, or a footnote without its pair. The write is saved either
+way. Read the warnings, fix the page, write again.
 
 ## Name the thing, not the document
 
-A page is called `mcp`, `billing`, `impact-analysis` — the subject it is about.
+The page slug (its URL name) is called `mcp`, `billing`, `impact-analysis` —
+the subject it is about, in lowercase English even when the title is Korean.
 
 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.
+`mcp-notes-v2`, `mcp-final`. The page that begins as a plan for MCP and ends as
+the description of the MCP you built is the same page the whole time.
 
 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.
+page and delete the old one — that throws away every revision.
 
 ## 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.
+Before building something, write the page: what you are about to do, why this
+way, what you decided against. That is revision 1, and another agent picking up
+the work reads it instead of guessing. A plan is the one revision allowed to be
+in the future tense.
 
 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.
+silently; a plan that is revision 1 of a living page 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
+Plan nodes and the page 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.
+## Write back what you built — with `newRevision: true`
 
-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.
+When the thing exists, rewrite the page so it describes it. Not "the plan plus
+a note that it's done" — an entry for what is there.
 
-## What stays on the page, what becomes history
+**Pass `newRevision: true` on that write.** Writes by the same author within
+about half an hour fold into one revision. That folding cannot tell "still
+drafting the plan" from "the plan has become the thing"; without the flag, an
+agent that plans and builds in one sitting overwrites its own plan.
 
-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.
+Use it whenever the page crosses a boundary: plan → built, v1 → v2, one
+approach abandoned for another.
 
 ## 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.
+separately. Do not split by document type — `mcp` and `mcp-architecture` are
+one page at two points in its life. Do not create a page per file, per sprint,
+or per meeting.
 
 ## 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"` |
+| The page lacks a whole topic you can add as its own `###` | `mode="replace"` with it folded in; `append` only if it truly stands alone at the end |
 | 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.
+| Someone else may have written meanwhile | add `baseRev` — the write is refused instead of clobbering |
 
-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.
+After any write, check `previousBodyChars`. If it is much larger than what you
+just wrote, you replaced someone's work — look at `list_wiki_revisions`.
 
 ## 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.
+A page can hang off a node or float free. Floating is normal early: knowledge
+arrives before structure. Once the tree has grown, list the unattached pages
+(`list_wiki` with `node="none"`) and attach the ones that now have a home.
+`list_wiki` with `kind="none"` lists the pages not yet classified.
 
 ## 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.
+Almost never. Deleting removes the page **and its entire revision history**.
+A stale page is not a reason to delete — rewrite it. 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.
+- **Structure** — that is what nodes are for. Do not keep a prose copy of the tree.
+- **Defects and open questions** — use bugs.
+- **Reports and archives** — an investigation's conclusion becomes spec or rules
+  on the page it is about; the report itself is not an entry.
+- **Secrets** — tokens, keys, passwords.

package/core/resources.js

@@ -55,7 +55,14 @@ const RESOURCES = [
     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.',
+    description: 'The wiki is the project\'s encyclopedia, read front to back as a tree: overview → chapters → entries. Covers the tree (parent/position), noun titles, kinds and their skeleton (lead → Spec → Rules → footnotes), background in footnotes, why a page is a description and not a log, naming, revisions (plan first, newRevision at the plan→built boundary), and why deleting is almost never right. Read before writing or reorganizing wiki pages.',
+  },
+  {
+    name: 'wiki-templates',
+    uri: 'umtri://templates/wiki',
+    file: 'wiki-templates.md',
+    title: 'Wiki tables of contents by project type',
+    description: 'Recommended wiki trees for a web service, an app service and a library — page, Korean title, kind, and what each holds. Read when starting a ground\'s wiki or when its table of contents has no clear shape.',
   },
   {
     name: 'system-structure',

package/core/tools.js

@@ -5,7 +5,7 @@
 //   - api: createApiClient(...) 결과 — get/post/put/patch/delete
 
 import { z } from 'zod';
-import { validateNode, validateEdge, validateUpdate, validateBugUpdate, wikiLogShapeCheck, toolMarkupCheck } from './policy.js';
+import { validateNode, validateEdge, validateUpdate, validateBugUpdate, toolMarkupCheck } from './policy.js';
 
 // LLM이 소비하는 결과 — 들여쓰기는 순수 토큰 낭비라 minify. (큰 그래프에서 ~19% 절감)
 function jsonResult(data) {
@@ -177,6 +177,12 @@ function compressProjects(projects, { descMode = 'excerpt' } = {}) {
       openBugs: p.openBugs,
       seasonCount: p.seasonCount,
     };
+    // 팀 ground면 소속과 내 역할을 싣는다 — viewer면 쓰기 도구가 403으로 막힌다는 걸 미리 알 수 있게.
+    // personal이면 생략(대부분의 ground가 personal이라 매번 실으면 잡음이다).
+    if (p.org && p.org.kind === 'team') {
+      out.org = p.org.slug;
+      out.role = p.role;
+    }
     // 문서가 있다는 사실만 흘린다. 0이면 생략 — 대부분의 ground가 0이라 매번 실으면 잡음이다.
     if (p.wikiCount) out.wikiCount = p.wikiCount;
     if (p.nowSeasonLabel) out.nowSeasonLabel = p.nowSeasonLabel;
@@ -329,7 +335,7 @@ export function registerTools(server, { api }) {
     'list_projects',
     {
       title: 'List grounds (projects)',
-      description: 'Returns all grounds the authenticated user can access, with latest activity timestamp. Use this first to discover slugs for other tools. By default returns a summary view — each ground carries slug, name, isActive, transplanting, nodeCount, openBugs, seasonCount, nowSeasonLabel, latestActivityAt, plus a 200-char description excerpt. A ground with wiki pages also carries wikiCount — prose the tree cannot hold (conventions, decisions, glossary); read it with list_wiki. Pass view="full" for all fields (seedMeta — the ground\'s human-written intent: goal, endDate, budget, audience — plus typeCounts, raw metadata, timestamps); the icon base64 in metadata is always stripped (UI-only).',
+      description: 'Returns all grounds the authenticated user can access, with latest activity timestamp. Use this first to discover slugs for other tools. By default returns a summary view — each ground carries slug, name, isActive, transplanting, nodeCount, openBugs, seasonCount, nowSeasonLabel, latestActivityAt, plus a 200-char description excerpt. A ground that belongs to a team also carries org (the team slug) and role (owner/editor/viewer) — a viewer can read but every write tool returns 403 there. A ground with wiki pages also carries wikiCount — prose the tree cannot hold (conventions, decisions, glossary); read it with list_wiki. Pass view="full" for all fields (seedMeta — the ground\'s human-written intent: goal, endDate, budget, audience — plus typeCounts, raw metadata, timestamps); the icon base64 in metadata is always stripped (UI-only).',
       inputSchema: z.object({
         view: z.enum(['summary', 'full']).optional().describe('summary (default) for a compact list; full for every field.'),
       }),
@@ -590,18 +596,20 @@ export function registerTools(server, { api }) {
     'create_project',
     {
       title: 'Create a new ground (project)',
-      description: 'Creates a new ground. Slug must match /^[a-z0-9][a-z0-9-]{0,49}$/ and be unique. The authenticated user owns it. Requires a write-scope token.',
+      description: 'Creates a new ground. Slug must match /^[a-z0-9][a-z0-9-]{0,49}$/ and be unique. By default it goes into the authenticated user\'s personal space; pass org (a team slug, as list_projects shows it) to create it in a team — only the team\'s owner can. Requires a write-scope token.',
       inputSchema: z.object({
         slug: z.string().regex(/^[a-z0-9][a-z0-9-]{0,49}$/).describe('URL slug. Lowercase letters, digits, hyphens; 1–50 chars.'),
         name: z.string().min(1).max(200).describe('Display name.'),
         description: z.string().optional(),
         visibility: z.enum(['private', 'unlisted', 'public']).optional().describe('Defaults to private.'),
+        org: z.string().min(1).optional().describe('Team slug to create the ground in. Omit for your personal space. You must own the team.'),
       }),
     },
-    async ({ slug, name, description, visibility }) => {
+    async ({ slug, name, description, visibility, org }) => {
       try {
         const markupWarnings = toolMarkupCheck({ description });
         const body = { slug, name };
+        if (org !== undefined) body.org = org;
         if (description !== undefined) body.description = description;
         if (visibility !== undefined) body.visibility = visibility;
         const created = await api.post('/api/projects', body);
@@ -777,14 +785,15 @@ export function registerTools(server, { api }) {
     'delete_node',
     {
       title: 'Soft-delete a node',
-      description: 'Sets removed_at on the node. By policy this tool rejects deletion if the node has any active descendant — delete children explicitly first to avoid accidental cascades. (The underlying REST API would cascade; the MCP layer guards against silent loss.) EXCEPTION — while the ground is transplanting (project.transplanting=true), the active-descendant guard is lifted (subtree cascade allowed) and you may pass hard=true to permanently remove import mistakes, including grown (past-season) nodes. Once the human roots the ground, normal guards return.',
+      description: 'Sets removed_at on the node. By default this tool rejects deletion if the node has any active descendant, so a subtree is never lost silently. To soft-delete the node together with all its active descendants, pass cascade=true — only when the human asked to remove the whole branch; soft-deleted nodes cannot be restored. The response lists the cascaded ids. EXCEPTION — while the ground is transplanting (project.transplanting=true), the active-descendant guard is lifted (subtree cascade allowed) and you may pass hard=true to permanently remove import mistakes, including grown (past-season) nodes. Once the human roots the ground, normal guards return.',
       inputSchema: z.object({
         slug: z.string().min(1).describe('Ground slug.'),
         id: z.string().min(1).describe('Node id.'),
+        cascade: z.boolean().optional().describe('Also soft-delete every active descendant. Without it, a node with active children is rejected.'),
         hard: z.boolean().optional().describe('Permanently delete (incl. descendants via FK cascade) instead of soft-delete. Only honored while the ground is transplanting; irreversible — use for import cleanup.'),
       }),
     },
-    async ({ slug, id, hard }) => {
+    async ({ slug, id, cascade, hard }) => {
       try {
         const graph = await api.get(`/api/projects/${encodeURIComponent(slug)}/graph`);
         const target = (graph.nodes || []).find(n => n.id === id);
@@ -792,13 +801,15 @@ export function registerTools(server, { api }) {
 
         const transplanting = graph.project?.transplanting === true;
 
-        // 옮겨심는 중이면 cascade 허용(가드 해제). 평상시엔 활성 자손 있으면 거부.
-        if (!transplanting) {
+        // 평상시엔 활성 자손이 있으면 거부한다 — 삭제된 노드는 되살릴 경로가 없어서, 가지 하나를 지우려다
+        // 서브트리가 통째로 사라지는 걸 막는다. cascade=true로 의도를 밝히면 서버의 cascade를 그대로 탄다.
+        // 옮겨심는 중이면 가드 해제.
+        if (!transplanting && cascade !== true) {
           const children = (graph.nodes || []).filter(n => n.parent === id && !n.removedAt);
           if (children.length > 0) {
             const list = children.slice(0, 5).map(c => `${c.id}("${c.label}")`).join(', ');
             const more = children.length > 5 ? ` (+${children.length - 5} more)` : '';
-            throw new Error(`Node has ${children.length} active child node(s). Delete them first. Children: ${list}${more}`);
+            throw new Error(`Node has ${children.length} active child node(s). Delete them first, or pass cascade=true to delete the whole subtree. Children: ${list}${more}`);
           }
         }
 
@@ -1156,19 +1167,21 @@ export function registerTools(server, { api }) {
     'list_wiki',
     {
       title: 'List wiki pages of a ground',
-      description: 'Lists the ground\'s wiki — the prose the tree cannot hold: conventions, decisions and why they were made, glossary, onboarding. Reference entries describing how things work, not a log of what happened: the change record is list_events, the page\'s own past is in its revisions. Not the structure itself (get_graph) and not defects (list_bugs). Bodies come back as 200-char excerpts by default so a scan stays cheap; pass body="full" only when you mean to read them, or body="none" for a pure index. A page may hang off a node (nodeId) or float free — pass node=<id> for one node\'s pages, or node="none" for the pages not yet attached to anything, which is the list worth reviewing when the tree has grown.',
+      description: 'Lists the ground\'s wiki — the prose the tree cannot hold: conventions, decisions and why they were made, glossary, onboarding. Reference entries describing how things work, not a log of what happened: the change record is list_events, the page\'s own past is in its revisions. Not the structure itself (get_graph) and not defects (list_bugs). Bodies come back as 200-char excerpts by default so a scan stays cheap; pass body="full" only when you mean to read them, or body="none" for a pure index. A page may hang off a node (nodeId) or float free — pass node=<id> for one node\'s pages, or node="none" for the pages not yet attached to anything, which is the list worth reviewing when the tree has grown. The wiki is a tree: each page has a parent page and a position among its siblings, starting from an overview page. order="tree" returns the whole table of contents in reading order (depth-first, with depth) — use it to read the wiki front to back or to see where a new page belongs. Every page also has a kind (overview / concept / component / rule / glossary); kind="none" lists the pages not yet classified.',
       inputSchema: z.object({
         slug: z.string().min(1).describe('Ground slug.'),
         node: z.string().optional().describe('Node id to filter by, or "none" for pages attached to nothing yet. Omit for all.'),
+        kind: z.enum(['overview', 'concept', 'component', 'rule', 'glossary', 'none']).optional().describe('Only pages of this kind, or "none" for unclassified pages. Omit for all.'),
         body: z.enum(['none', 'excerpt', 'full']).optional().describe('How much body text per page. Default "excerpt" (200 chars).'),
         limit: z.coerce.number().int().positive().optional(),
-        order: z.enum(['asc', 'desc']).optional().describe('By last update. Default "desc" (most recently touched first).'),
+        order: z.enum(['asc', 'desc', 'tree']).optional().describe('"desc" (default) / "asc" by last update, or "tree" for the table of contents in reading order.'),
       }),
     },
-    async ({ slug, node, body, limit, order }) => {
+    async ({ slug, node, kind, body, limit, order }) => {
       try {
         const qs = [];
         if (node) qs.push(`node=${encodeURIComponent(node)}`);
+        if (kind) qs.push(`kind=${kind}`);
         if (body) qs.push(`body=${body}`);
         if (limit) qs.push(`limit=${limit}`);
         if (order) qs.push(`order=${order}`);
@@ -1230,6 +1243,7 @@ export function registerTools(server, { api }) {
       title: 'Create or update a wiki page',
       description: [
         'Writes one wiki page. Creates it if the page slug is new, updates it otherwise — you do not need to check first.',
+        '**The wiki is the project\'s encyclopedia: one page is one entry, and its body is the current spec and rules of that thing.** It is a tree read front to back: an overview page at the top, chapter pages under it, entries under those — place every page with parent (a page slug or id) and position (its order among siblings), and check list_wiki order="tree" to see where it belongs. For a new wiki, follow the table of contents in umtri://templates/wiki. The title is a plain noun for the thing in the reader\'s language (조직, 배포, Billing) — no dash, colon, parenthetical or sentence; the description goes in the lead. Give every page a kind — overview (the top page and chapter pages that introduce what is under them), concept (a product/domain concept or model), component (how one part of the system works), rule (a convention that must be kept), glossary (the project\'s vocabulary). Write it to this skeleton: a lead paragraph first (1–3 sentences saying what the thing is — not a heading, quote or list), then "## 스펙" / "## Spec" (how it works now; break it down with ###), then "## 규칙" / "## Rules" (invariants, prohibitions, required order). concept and component need Spec; rule needs Rules; overview and glossary are free-form after the lead. No other top-level (##) sections. Background, history, rejected alternatives and side notes go into footnotes — [^name] in the text, [^name]: … at the end — not into the body. A reason stays in the body only if someone changing the code would get it wrong without it.',
         'Write what the tree cannot hold and what a maintainer would otherwise have to reconstruct: why a decision went the way it did, the vocabulary this project uses, what an investigation concluded. Do not restate the structure — that is what nodes are for.',
         '**A page is a description, not a log.** Write it in the present tense, as a reference entry for the thing: how it works now, and the reasons that still constrain it. Do not append what you just did, do not add dated entries or a change-history section, do not keep progress checklists here — those go to bugs, plan nodes, list_events, and record_commit, and the page\'s own past is already kept in its revisions. When something changes, rewrite the sentence that is now wrong rather than adding a sentence saying it changed.',
         'mode="replace" (default) overwrites the whole body — read the page first, or you will drop what was there; this is the normal way to update a page. mode="append" is the narrow case: adding a section the page genuinely lacked, never tacking on this session\'s summary. mode="restore" puts an earlier revision back: pass rev=<n> and nothing else, and the page returns to what it said then.',
@@ -1239,6 +1253,7 @@ export function registerTools(server, { api }) {
         'rename moves the page to a new slug, keeping its id and its whole revision history — do not create a new page and delete the old one, that throws the history away.',
         'The response tells you what the write did: rev is the revision it landed in, coalesced says whether it folded into your previous one, and previousBodyChars is how long the body was before you wrote. If previousBodyChars is much larger than what you just wrote, you replaced someone\'s work — check list_wiki_revisions before moving on.',
         'baseRev is optional and is how you avoid clobbering a concurrent edit: pass the rev you read, and the write is refused if the page moved on since. Use it when you read, think, then write.',
+        'The response carries warnings[] when the page strays from the skeleton or reads like a log (status banners, dated headings, checklists, change-history sections, unmatched footnotes). The write is saved either way — fix what they point at and write again.',
         'The change also lands in the ground\'s history (list_events, entityType="wiki"), where the body is recorded as a length delta rather than a copy of the prose — the prose itself lives in the revisions.',
         'Requires a write-scope token.',
       ].join(' '),
@@ -1248,6 +1263,9 @@ export function registerTools(server, { api }) {
         title: z.string().min(1).max(200).optional().describe('Display title. Required when creating a page.'),
         body: z.string().optional().describe('Markdown body. With mode="append" this is the text to add. Ignored by mode="restore".'),
         node: z.string().nullable().optional().describe('Node id to attach to. null detaches. Omit to leave the current attachment untouched.'),
+        kind: z.enum(['overview', 'concept', 'component', 'rule', 'glossary']).nullable().optional().describe('Page kind — decides the required sections. Give it when creating. Omit to keep the current kind.'),
+        parent: z.string().nullable().optional().describe('Parent page (slug or id) — where this page sits in the table of contents. null moves it to the top level (only overview pages belong there). Omit to keep it.'),
+        position: z.coerce.number().int().nullable().optional().describe('Order among siblings under the same parent (ascending; pages without one come after, by title). Omit to keep it.'),
         mode: z.enum(['replace', 'append', 'restore']).optional().describe('"replace" (default) overwrites the body — the normal way to update a page; "append" adds a missing section to the end (not a session summary); "restore" brings back the revision named by rev.'),
         rev: z.coerce.number().int().positive().optional().describe('With mode="restore": the revision number to bring back (from list_wiki_revisions).'),
         baseRev: z.coerce.number().int().positive().optional().describe('The revision you based this write on. If the page has moved past it, the write is refused instead of overwriting.'),
@@ -1260,22 +1278,24 @@ export function registerTools(server, { api }) {
         rename: z.string().regex(/^[a-z0-9][a-z0-9-]{0,79}$/).optional().describe('New page slug. Keeps the id and the revision history; refused if that name is taken.'),
       }),
     },
-    async ({ slug, page, title, body, node, mode, rev, baseRev, newRevision, rename }) => {
+    async ({ slug, page, title, body, node, kind, parent, position, mode, rev, baseRev, newRevision, rename }) => {
       try {
         const payload = { slug: page };
         if (title !== undefined) payload.title = title;
         if (body !== undefined) payload.body = body;
         if (node !== undefined) payload.node = node;
+        if (kind !== undefined) payload.kind = kind;
+        if (parent !== undefined) payload.parent = parent;
+        if (position !== undefined) payload.position = position;
         if (mode !== undefined) payload.mode = mode;
         if (rev !== undefined) payload.rev = rev;
         if (baseRev !== undefined) payload.baseRev = baseRev;
         if (newRevision !== undefined) payload.newRevision = newRevision;
         if (rename !== undefined) payload.rename = rename;
         const written = await api.put(`/api/projects/${encodeURIComponent(slug)}/wiki`, payload);
-        // 로그 형태 경고는 쓰기를 막지 않는다 — 이미 저장된 뒤에 붙인다. 판정이 휴리스틱이라
-        // 거부하면 정당한 문서까지 막히고, 어차피 리비전이 있어 되돌릴 수 있다.
-        // 검사 대상은 저장된 본문이다: append면 이어붙인 결과 전체를 봐야 한다.
-        const warnings = wikiLogShapeCheck(written?.body)
+        // 본문 판정(뼈대·로그 형태)은 서버가 저장된 본문에 걸어 warnings로 돌려준다.
+        // 여기선 도구 호출 마크업 유출만 더한다 — 그건 MCP 인자 직렬화 사고라 이 층의 일이다.
+        const warnings = (written?.warnings ?? [])
           .concat(toolMarkupCheck({ title, body: written?.body }));
         return jsonResult(warnings.length ? { ...written, warnings } : written);
       } catch (e) { return errorResult(e); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umtri-mcp",
-  "version": "1.3.3",
+  "version": "1.4.0",
   "description": "MCP server for Umtri — give your AI coding agent a persistent map of your project's structure, dependencies, and bugs.",
   "mcpName": "io.umtri/umtri",
   "keywords": [