project-librarian 0.2.1 → 0.4.0

package/dist/taxonomy.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyMigrationUnit = classifyMigrationUnit;
+exports.storageToMigrationKind = storageToMigrationKind;
+const taxonomyAreas = [
+    {
+        id: "research-sources",
+        label: "Research / Source Evidence",
+        storage: "sources",
+        targetSlug: "research-sources",
+        keywords: ["source", "sources", "reference", "references", "citation", "bibliography", "research", "paper", "article", "link", "출처", "참고", "자료", "근거", "링크", "리서치", "논문"],
+    },
+    {
+        id: "decision-record",
+        label: "Decision Record",
+        storage: "decisions",
+        targetSlug: "decision-records",
+        keywords: ["adr", "decision", "decisions", "rationale", "tradeoff", "trade-off", "alternative", "rejected", "accepted", "decided", "결정", "의사결정", "기각", "대안", "트레이드오프", "선택", "채택"],
+    },
+    {
+        id: "strategy",
+        label: "Strategy / Business Context",
+        storage: "canonical",
+        targetSlug: "strategy-context",
+        keywords: ["vision", "mission", "strategy", "business model", "market", "positioning", "competitive", "gtm", "pricing", "roadmap", "비전", "미션", "전략", "시장", "포지셔닝", "경쟁", "사업", "가격", "로드맵"],
+    },
+    {
+        id: "product-requirements",
+        label: "Product Requirements",
+        storage: "canonical",
+        targetSlug: "product-requirements",
+        keywords: ["prd", "requirement", "requirements", "feature", "features", "function", "functional", "scope", "goal", "goals", "acceptance", "use case", "기능", "기능명세", "요구사항", "요건", "범위", "목표", "수용기준", "유스케이스", "서비스기획", "기획"],
+    },
+    {
+        id: "user-flow",
+        label: "User Flow / Journey",
+        storage: "canonical",
+        targetSlug: "user-flows",
+        keywords: ["user flow", "flow", "journey", "scenario", "persona", "story", "navigation", "screen flow", "유저플로우", "사용자 흐름", "사용자 여정", "시나리오", "페르소나", "스토리", "화면흐름", "동선"],
+    },
+    {
+        id: "ux-content",
+        label: "UX / Content",
+        storage: "canonical",
+        targetSlug: "ux-content",
+        keywords: ["ux", "interaction", "wireframe", "copy", "content", "microcopy", "empty state", "error state", "accessibility", "i18n", "사용성", "인터랙션", "와이어프레임", "카피", "콘텐츠", "빈상태", "오류상태", "접근성", "문구"],
+    },
+    {
+        id: "design-system",
+        label: "Design System / UI",
+        storage: "canonical",
+        targetSlug: "design-system",
+        keywords: ["design", "ui", "component", "prototype", "figma", "style guide", "brand", "visual", "layout", "디자인", "컴포넌트", "프로토타입", "스타일가이드", "브랜드", "시각", "레이아웃"],
+    },
+    {
+        id: "data-analytics",
+        label: "Data / Analytics",
+        storage: "canonical",
+        targetSlug: "data-analytics",
+        keywords: ["data", "schema", "database", "db", "erd", "entity", "event", "metric", "analytics", "kpi", "tracking", "데이터", "스키마", "디비", "엔티티", "이벤트", "지표", "분석", "트래킹"],
+    },
+    {
+        id: "api-contract",
+        label: "API Contract",
+        storage: "canonical",
+        targetSlug: "api-contracts",
+        keywords: ["api", "endpoint", "request", "response", "rest", "graphql", "webhook", "sdk", "openapi", "swagger", "인증", "토큰", "요청", "응답", "엔드포인트", "웹훅", "api명세", "api 명세"],
+    },
+    {
+        id: "engineering-architecture",
+        label: "Engineering / Architecture",
+        storage: "canonical",
+        targetSlug: "engineering-architecture",
+        keywords: ["architecture", "system", "service", "module", "implementation", "tech stack", "dependency", "infra", "deployment", "queue", "cache", "아키텍처", "시스템", "서비스", "모듈", "구현", "기술스택", "인프라", "배포", "큐", "캐시"],
+    },
+    {
+        id: "security-legal",
+        label: "Security / Legal",
+        storage: "canonical",
+        targetSlug: "security-legal",
+        keywords: ["security", "privacy", "permission", "role", "auth", "authorization", "compliance", "legal", "terms", "consent", "보안", "개인정보", "권한", "역할", "인가", "인증", "준수", "법무", "약관", "동의"],
+    },
+    {
+        id: "policy",
+        label: "Policy / Governance",
+        storage: "canonical",
+        targetSlug: "policy-governance",
+        keywords: ["policy", "rule", "moderation", "governance", "sla", "retention", "eligibility", "refund", "정책", "규칙", "운영정책", "거버넌스", "보관", "자격", "환불"],
+    },
+    {
+        id: "qa",
+        label: "QA / Test",
+        storage: "canonical",
+        targetSlug: "qa-test-plan",
+        keywords: ["qa", "test", "testing", "validation", "verification", "bug", "edge case", "regression", "acceptance test", "테스트", "검증", "품질", "버그", "엣지케이스", "회귀", "테스트케이스"],
+    },
+    {
+        id: "release-ops",
+        label: "Release / Operations",
+        storage: "canonical",
+        targetSlug: "release-operations",
+        keywords: ["release", "launch", "operation", "runbook", "monitoring", "alert", "incident", "support", "cs", "migration", "rollout", "릴리즈", "출시", "운영", "런북", "모니터링", "알림", "장애", "고객지원", "마이그레이션"],
+    },
+    {
+        id: "business-ops",
+        label: "Business Operations",
+        storage: "canonical",
+        targetSlug: "business-operations",
+        keywords: ["sales", "marketing", "crm", "customer success", "finance", "billing", "invoice", "contract", "영업", "마케팅", "고객성공", "재무", "청구", "계약", "정산"],
+    },
+    {
+        id: "wiki-meta",
+        label: "Wiki Operations / Meta",
+        storage: "meta",
+        targetSlug: "wiki-operations",
+        keywords: ["wiki", "documentation", "document taxonomy", "canonical", "source of truth", "lint", "doctor", "위키", "문서화", "문서체계", "정본", "정보구조", "린트", "닥터"],
+    },
+];
+function slugPart(value, maxLength = 36) {
+    return value.toLowerCase().replace(/[^a-z0-9가-힣ぁ-んァ-ン一-龥]+/g, "-").replace(/^-|-$/g, "").slice(0, maxLength) || "migration";
+}
+function legacyStem(legacyPath) {
+    return slugPart(legacyPath.replace(/\.(md|mdx)$/i, "").split(/[\\/]+/).pop() ?? legacyPath);
+}
+function fallbackStorageFromLegacyPath(legacyPath) {
+    if (/^meta\//.test(legacyPath))
+        return "meta";
+    if (/^decisions\//.test(legacyPath))
+        return "decisions";
+    if (/^sources\//.test(legacyPath))
+        return "sources";
+    return "canonical";
+}
+function keywordScore(haystack, keyword) {
+    const normalized = keyword.toLowerCase();
+    const escaped = normalized.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (/^[a-z0-9 -]+$/.test(normalized)) {
+        const matches = haystack.match(new RegExp(`\\b${escaped}\\b`, "g"));
+        return matches ? matches.length : 0;
+    }
+    return haystack.includes(normalized) ? 1 : 0;
+}
+function areaScore(area, haystack) {
+    return area.keywords.reduce((sum, keyword) => sum + keywordScore(haystack, keyword), 0);
+}
+function targetPath(storage, base, targetSlug) {
+    return `wiki/${storage}/${slugPart(base, 32)}-${targetSlug}.md`;
+}
+function classifyMigrationUnit(input) {
+    const haystack = [
+        legacyStem(input.legacyPath),
+        input.heading,
+        input.headingPath.join(" "),
+        input.summary,
+        input.content,
+    ].join("\n").toLowerCase();
+    const scored = taxonomyAreas
+        .map((area) => ({ area, score: areaScore(area, haystack) }))
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || left.area.id.localeCompare(right.area.id));
+    const fallbackStorage = fallbackStorageFromLegacyPath(input.legacyPath);
+    const best = scored[0]?.area ?? {
+        id: "unclassified",
+        label: "Needs Human Review",
+        storage: fallbackStorage,
+        targetSlug: "migration-review",
+        keywords: [],
+    };
+    const bestScore = scored[0]?.score ?? 0;
+    const secondScore = scored[1]?.score ?? 0;
+    const confidence = bestScore >= 3 && bestScore > secondScore ? "high" : bestScore >= 1 && bestScore >= secondScore ? "medium" : "low";
+    const base = legacyStem(input.legacyPath);
+    const reason = confidence === "low"
+        ? "no strong taxonomy signal; human review required"
+        : `matched ${best.label}${secondScore > 0 && bestScore === secondScore ? " with overlapping signals" : ""}`;
+    return {
+        area: best.id,
+        label: best.label,
+        storage: best.storage,
+        target: targetPath(best.storage, base, best.targetSlug),
+        confidence,
+        reason,
+    };
+}
+function storageToMigrationKind(storage) {
+    if (storage === "decisions")
+        return "decision";
+    if (storage === "sources")
+        return "source";
+    if (storage === "meta")
+        return "meta";
+    return "canonical";
+}

package/dist/templates.js

@@ -1,8 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.starterFiles = exports.decisionPolicy = exports.wikiOperatingModel = exports.inboxIndexBlock = exports.glossaryIndexBlock = exports.glossary = exports.index = exports.startup = exports.metadata = exports.wikiAgentsSection = exports.cursorRule = exports.geminiSection = exports.claudeSection = exports.agentsSection = void 0;
+exports.defaultStarterFilePaths = exports.starterFiles = exports.documentTaxonomy = exports.decisionPolicy = exports.wikiOperatingModel = exports.inboxIndexBlock = exports.glossaryIndexBlock = exports.glossary = exports.index = exports.startup = exports.metadata = exports.wikiAgentsSection = exports.cursorRule = exports.geminiSection = exports.claudeSection = exports.STARTUP_TLDR_MAX_CHARS = exports.startupTldrSyncLabel = exports.codeEvidenceTrustContract = exports.wikiTrustContract = void 0;
+exports.extractStartupTldr = extractStartupTldr;
+exports.agentsSection = agentsSection;
 const workspace_1 = require("./workspace");
-exports.agentsSection = `<!-- PROJECT-WIKI-FIRST:START -->
+// B4 (gated on B2, which ships in the same phase): a single-sentence trust
+// contract in the managed AGENTS.md block. It is the substitution mechanism that
+// stops repo-wide re-verification greps; the --doctor router-truth rule (B2)
+// guards against trusting a stale router.
+exports.wikiTrustContract = "Wiki decision documents are authoritative for project decisions: do not re-verify them against the repository unless directly conflicting code evidence appears, since the `--doctor` router-truth rule guards against stale routers.";
+// B4 analogue for code evidence: a single-sentence trust contract making the
+// code-evidence tool/report outputs authoritative for code-structure questions,
+// gated on the same staleness check the tools surface (`--code-status` /
+// `code_status`). Mirrors wikiTrustContract scale; kept budget-conscious. The
+// closing clause is the scale-conditional guidance (2026-06-12 decision, stageR1
+// evidence): on small repos simple lookups measured cheaper via direct reads.
+exports.codeEvidenceTrustContract = "Code-evidence tool and report outputs (`--code-impact`, `--code-report`, and the `project-librarian mcp` tools) are authoritative for code-structure questions: do not re-verify them with repo-wide greps unless `--code-status`/`code_status` reports staleness; on small repos below the measured scale threshold, prefer direct reads over these tools for simple lookups (measured cheaper at small scale).";
+// B1 fallback: label for the auto-synced startup TL;DR sub-block embedded in the
+// managed AGENTS.md marker section. Non-interactive `codex exec` does not run
+// SessionStart hooks (measured 2026-06-10), so AGENTS.md is the only startup
+// context carrier there; the sync stays TL;DR-only per token discipline.
+exports.startupTldrSyncLabel = "Startup TL;DR (auto-synced for non-interactive sessions; source: wiki/startup.md)";
+// Hard cap on the extracted TL;DR text embedded in AGENTS.md. The startup hook
+// budget is 3500 chars for the full wiki/startup.md; the TL;DR sub-section must
+// stay well under that so the managed block remains token-efficient. 2000 chars is
+// a documented hard bound: it leaves headroom for frontmatter, other sections, and
+// the AGENTS.md surrounding content. Per the no-fallback rule, we NEVER truncate —
+// if the extracted bullets exceed this limit the sync fails loudly so the author
+// knows to trim the TL;DR.
+exports.STARTUP_TLDR_MAX_CHARS = 2000;
+// Extract the `## TL;DR` bullet list from a startup.md body (TL;DR section ONLY —
+// never Recent Decisions or Project State). Returns the `- ` bullet lines between
+// the `## TL;DR` heading and the next `## ` heading. Throws loudly when the
+// startup body has no `## TL;DR` section, that section has no bullets, or the
+// extracted text exceeds STARTUP_TLDR_MAX_CHARS (no fallback, no silent truncation).
+function extractStartupTldr(startupMarkdown) {
+    const match = startupMarkdown.match(/^##\s+TL;DR[^\n]*\n([\s\S]*?)(?=\n##\s|(?![\s\S]))/m);
+    if (!match) {
+        throw new Error("cannot sync startup TL;DR into AGENTS.md: wiki/startup.md has no \"## TL;DR\" section");
+    }
+    const bullets = (match[1] ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => /^\s*-\s+\S/.test(line));
+    if (bullets.length === 0) {
+        throw new Error("cannot sync startup TL;DR into AGENTS.md: the wiki/startup.md \"## TL;DR\" section has no bullet items");
+    }
+    const result = bullets.join("\n");
+    if (result.length > exports.STARTUP_TLDR_MAX_CHARS) {
+        throw new Error(`cannot sync startup TL;DR into AGENTS.md: extracted TL;DR is ${result.length} chars, which exceeds the ${exports.STARTUP_TLDR_MAX_CHARS}-char limit; trim the ## TL;DR section in wiki/startup.md`);
+    }
+    return result;
+}
+// Build the managed AGENTS.md marker section. The startup TL;DR is synced in as a
+// clearly labeled sub-block (B1 fallback) so non-interactive Codex sessions, which
+// never run the SessionStart hook, still receive compact startup context; the
+// trust contract sentence (B4) is appended to the during-conversation rules. Only
+// this marker block changes; user content outside the markers is untouched, and
+// because the section is built deterministically from the current startup TL;DR a
+// re-run with unchanged startup yields the same section ("exists" via
+// upsertMarkedSection).
+function agentsSection(startupTldr) {
+    return `<!-- PROJECT-WIKI-FIRST:START -->
 ## Wiki-First Planning
 
 This project uses \`./wiki\` as the durable project-planning source of truth.
@@ -13,13 +72,21 @@ At the start of every session:
 2. Review \`wiki/index.md\` as the router for which files to read next.
 3. Read detailed \`wiki/canonical/\`, \`wiki/decisions/\`, \`wiki/meta/\`, and \`wiki/sources/\` files on demand only when the current question needs them.
 
+### ${exports.startupTldrSyncLabel}
+
+${startupTldr}
+
 During conversation:
 
 - Update \`./wiki\` in the same turn when project planning content is added, changed, or removed.
+- Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in project wiki canonical or decision docs.
 - Follow \`wiki/AGENTS.md\` for detailed rules when editing files under \`wiki/\`.
 - Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically for staged wiki, hook, AGENTS, or project-librarian files.
+- ${exports.wikiTrustContract}
+- ${exports.codeEvidenceTrustContract}
 <!-- PROJECT-WIKI-FIRST:END -->`;
+}
 exports.claudeSection = `<!-- PROJECT-WIKI-CLAUDE:START -->
 # Claude Code Project Instructions
 
@@ -79,6 +146,14 @@ Storage boundaries:
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in \`canonical/\` or \`decisions/\`; use root \`AGENTS.md\`, compatibility instruction files, hooks, rules, or skills instead.
 - During migration review, preserve useful meaning while converting it to the current wiki structure. Legacy files, sections, blocks, and wording may be retained when review confirms they belong in the new topic shape and remain current project truth. Do not link to or cite \`wiki_legacy*\` from the new wiki; cite current-project evidence when possible and keep unresolved or ambiguous material in migration inboxes.
 
+Classification rules:
+
+- Before adding or consolidating project content, classify it with \`meta/document-taxonomy.md\`.
+- Write current agreement to the narrowest durable canonical document that fits the taxonomy; do not append unrelated material to \`canonical/project-brief.md\`.
+- If one input crosses several lifecycle areas, split it into separate canonical updates and link the related pages.
+- If the input explains why a direction changed, update the relevant decision log or Decision Pack in addition to canonical truth.
+- If an external artifact is the better source of truth (for example Figma, OpenAPI, ERD, issue tracker, or code), keep a concise canonical summary and link the external source as the authoritative location.
+
 Update rules:
 
 - Every wiki knowledge markdown file should include compact metadata with \`status\`, \`updated\`, \`scope\`, \`read_budget\`, \`decision_ref\`, and \`review_trigger\`. This \`wiki/AGENTS.md\` instruction file is excluded from that wiki-page metadata requirement.
@@ -117,14 +192,12 @@ exports.startup = `${(0, exports.metadata)("startup-router", "short", "wiki/meta
 - At session start, read only this file and \`wiki/index.md\` first; read detailed files on demand.
 - Project canonical content language is not fixed by this bootstrap. The LLM should choose the language that best matches the user and project context.
 - Update the wiki in the same turn when project-planning content changes.
+- Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 
 ## Read On Demand
 
 - [[index]]: document router.
-- [[canonical/project-brief]]: read only when product direction, audience, scope, success criteria, or core scenarios matter.
-- [[canonical/open-questions]]: read only when unresolved questions or next clarification items matter.
-- [[canonical/assumptions]]: read only when temporary assumptions or unverified premises matter.
-- [[canonical/risks]]: read only when risks, revisit triggers, or uncertainty matter.
+- [[meta/document-taxonomy]]: read only when classifying or reorganizing project wiki content.
 
 ## Project State
 
@@ -179,22 +252,7 @@ This file is a router, not a file to expand into every answer. Read only the fil
 
 ## Canonical
 
-- [[canonical/project-brief]]
-  - Read: product direction, audience, scope, success criteria, core scenarios.
-  - Update: product, audience, scope, or success criteria changes.
-  - Token budget: medium.
-- [[canonical/open-questions]]
-  - Read: unresolved questions or next clarifications.
-  - Update: questions are added, answered, or moved.
-  - Token budget: short.
-- [[canonical/assumptions]]
-  - Read: temporary assumptions or unverified premises.
-  - Update: assumptions are added, validated, or retired.
-  - Token budget: short.
-- [[canonical/risks]]
-  - Read: risks, revisit triggers, uncertainty.
-  - Update: risks are added, mitigated, or resolved.
-  - Token budget: short.
+No empty canonical starter pages are created by default. Create focused pages under \`wiki/canonical/\` only when durable project truth exists, then route them here or with \`--refresh-index\`.
 
 ## Project Decisions
 
@@ -202,18 +260,14 @@ This file is a router, not a file to expand into every answer. Read only the fil
   - Read: recent important project decisions.
   - Update: a decision belongs in startup context.
   - Token budget: short.
+- [[decisions/README]]
+  - Read: decision directory structure or decision routing conventions.
+  - Update: decision directory conventions change.
+  - Token budget: short.
 - [[decisions/log]]
   - Read: project decision timing matters.
   - Update: a trivial decision needs timestamp tracking.
   - Token budget: on-demand.
-- [[decisions/decision-pack-template]]
-  - Read: creating a Decision Pack.
-  - Update: Decision Pack format changes.
-  - Token budget: short.
-- [[decisions/full-adr-template]]
-  - Read: creating a Full ADR.
-  - Update: Full ADR format changes.
-  - Token budget: short.
 
 ## Wiki Meta
 
@@ -221,6 +275,10 @@ This file is a router, not a file to expand into every answer. Read only the fil
   - Read: wiki operation, hooks, bootstrap, maintenance, language policy.
   - Update: wiki operation or startup behavior changes.
   - Token budget: medium.
+- [[meta/document-taxonomy]]
+  - Read: classifying, writing, consolidating, splitting, or reorganizing project wiki content.
+  - Update: wiki information architecture or service-documentation categories change.
+  - Token budget: medium.
 - [[meta/decision-policy]]
   - Read: decision level, ADR need, canonical/decision split.
   - Update: decision classification or ADR criteria changes.
@@ -281,6 +339,7 @@ exports.wikiOperatingModel = `${(0, exports.metadata)("wiki-meta", "medium", "wi
 - Operating documents generated by bootstrap are English by default.
 - Project canonical content language is selected from user/project context, not hardcoded by this bootstrap.
 - Search, index refresh, inbox capture, and lifecycle checks are explicit script modes.
+- New project content is classified through [[meta/document-taxonomy]] before it is written or consolidated.
 
 ## Purpose
 
@@ -299,6 +358,18 @@ Karpathy's LLM Wiki pattern favors a continuously maintained markdown wiki over
 5. Router: read/update/token-budget guidance in \`wiki/index.md\`.
 6. Wiki meta: operating rules, decision policy, bootstrap, migration, lint, and language policy under \`wiki/meta/\`.
 
+## Content Classification Procedure
+
+Before writing or reorganizing project-planning content:
+
+1. Identify the content's lifecycle area with [[meta/document-taxonomy]].
+2. Decide whether the content is current truth, decision rationale, source evidence, an unresolved candidate, or a wiki operating rule.
+3. Write current truth to the narrowest relevant \`canonical/\` page, decision rationale to \`decisions/\`, source notes to \`sources/\`, candidates to \`inbox/\`, and wiki operating rules to \`meta/\`.
+4. Split multi-area inputs instead of making one catch-all document.
+5. Link upstream and downstream pages when the content derives from another artifact or produces another artifact.
+
+Do not treat \`canonical/project-brief.md\` as a default dumping ground. It should summarize direction, audience, scope, and success criteria; detailed product, policy, UX, data, engineering, QA, release, or operations truth should move into focused pages when it grows.
+
 ## Language Policy
 
 - Bootstrap-generated operating documents are English.
@@ -371,6 +442,106 @@ Use a Full ADR when the decision affects product direction, architecture, public
 - Do not inject full canonical or decision bodies into startup context.
 - Read long decision files only when \`wiki/index.md\` routing says they are relevant.
 `;
+exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki/meta/wiki-ops-v1-decisions.md", "wiki information architecture, documentation categories, or content classification rules change")}
+# Document Taxonomy
+
+## TL;DR
+
+- Classify new project-planning content before writing it into the wiki.
+- Use this page to classify content into \`canonical/\`, \`decisions/\`, \`sources/\`, \`inbox/\`, or \`meta/\`.
+- Keep \`canonical/project-brief.md\` compact; move detailed truth into focused canonical pages.
+- Preserve derivation links: evidence -> strategy -> requirements -> design/data/engineering -> QA -> release/operations -> feedback.
+
+## Top-Level Flow
+
+\`\`\`text
+0. Source-of-truth governance
+  -> 1. Research and evidence
+    -> 2. Strategy and business model
+      -> 3. Product scope and requirements
+        -> 4. Policies and rules
+        -> 5. UX and content
+        -> 6. Design
+        -> 7. Data and analytics
+        -> 8. Engineering
+          -> 9. Security, legal, compliance
+          -> 10. QA and verification
+            -> 11. Release and operations
+              -> 12. Business operations
+                -> 13. Improvement, migration, and end-of-life
+                  -> next product scope, policy, or roadmap change
+\`\`\`
+
+## Storage Decision
+
+| Content Type | Store In | Notes |
+| --- | --- | --- |
+| Current valid project truth | \`wiki/canonical/\` | Split by topic and read frequency. |
+| Why a choice was made | \`wiki/decisions/\` | Use log, Decision Pack, or ADR by impact. |
+| Source material or summarized evidence | \`wiki/sources/\` | Keep links, checked dates, and applicability. |
+| Unreviewed or ambiguous material | \`wiki/inbox/\` | Do not treat as canonical truth. |
+| Wiki operation, taxonomy, hooks, migration, lint, language rules | \`wiki/meta/\` | Keep outside project canonical truth. |
+| Better external source of truth | External artifact plus a concise wiki route | Examples: Figma, OpenAPI, ERD, Jira, code. |
+
+## Lifecycle Areas
+
+| Area | Put Here | Usually Derives From | Usually Produces |
+| --- | --- | --- | --- |
+| 0. Governance | source-of-truth map, owners, RACI, approval flow, change rules, glossary, state dictionary, assumptions, risk register | team/process constraints | routing, ownership, conflict resolution |
+| 1. Research | market, competitor, user interviews, VOC, analytics, legal/regulatory, technical feasibility, cost, vendor, accessibility research | raw discovery | strategy, risks, sources |
+| 2. Strategy | service overview, vision, problem, target users, personas, jobs-to-be-done, value offer, positioning, business model, KPI/OKR, success/stop criteria, roadmap, MVP, non-goals | research | PRD, roadmap, scope |
+| 3. Product | PRD, user stories, use cases, priorities, backlog rules, acceptance criteria, feature spec, exceptions, state definitions, notification rules, search/filter/sort rules, admin requirements | strategy and policy | UX, API, data, QA |
+| 4. Policy | operations policy, auth/account, permissions, pricing, payment/refund, coupon/credit, content moderation, notifications, retention/deletion, abuse response, support, EOL | business model, law, risks | feature constraints, API rules, CS/ops |
+| 5. UX and Content | IA, sitemap, user flow, task flow, screen list, wireframes, screen specs, content model, UX writing, empty/error states, help/FAQ, localization, SEO, accessibility criteria | product and policy | design, frontend, QA |
+| 6. Design | brand guide, design principles, design system, component spec, responsive rules, interaction spec, prototype, design QA | UX and brand | UI implementation, design QA |
+| 7. Data and Analytics | ERD, data dictionary, classification, ownership/stewardship, event taxonomy, metric definitions, funnels, data quality, lineage, export/import, anonymization, dashboards | product, policy, KPI | schemas, events, reports |
+| 8. Engineering | architecture, technology decisions, API/OpenAPI, integrations, webhooks/idempotency, state machines, jobs/cron, error codes, env vars, secrets, local dev, conventions, branch/release strategy, CI/CD, feature flags, dependencies, migrations, performance, scalability, FinOps | product, UX, data, policy | implementation and verification |
+| 9. Security/Legal | security requirements, threat model, privacy rules, privacy impact, terms, privacy policy, audit logs, permission history, internal access controls, key rotation, vulnerability response, licenses, vendor and DPA documents | data, architecture, law | controls, tests, release gates |
+| 10. QA | test strategy, QA scenarios, test cases, regression checklist, UAT, browser/device matrix, accessibility tests, performance tests, security tests, data quality tests, design QA, quality gates | requirements, design, engineering | release approval |
+| 11. Release/Ops | release plan, deployment procedure, rollback, release notes, operator manual, runbooks, monitoring, observability, SLO/SLA, on-call/escalation, incident response, backup/restore, DR/BCP, recurring checks | QA and infrastructure | stable operation |
+| 12. Business Ops | CS macros, support policy, training, sales/adoption guide, CRM rules, onboarding playbook, churn/offboarding, admin operations, communication templates, revenue recognition, tax/invoice, partner operations | policy, release, sales motion | customer-facing operation |
+| 13. Improvement/EOL | VOC summary, retrospectives, experiments, experiment results, cohort/retention analysis, feature deprecation, migration/data transfer, service end-of-life | operations and analytics | next PRD, policy, roadmap |
+
+## Writing Rule
+
+When a new note arrives:
+
+1. Identify the lifecycle area and storage location.
+2. Update an existing focused page when the topic already has a canonical home.
+3. Create a new focused page only when the topic is durable, likely to be read independently, or too large for its current page.
+4. Add an \`index.md\` route when the page becomes durable.
+5. Add upstream/downstream links in prose or tables when one artifact derives from another.
+6. Record decision rationale separately when the change explains why the project chose one option over another.
+
+## Page Shape
+
+Use this shape for focused canonical pages unless a domain-specific shape is clearly better:
+
+\`\`\`md
+---
+status: active
+updated: YYYY-MM-DD
+scope: project-canonical
+read_budget: short|medium|on-demand
+decision_ref: none|wiki/decisions/...
+review_trigger: what should cause this page to change
+---
+
+# <Topic>
+
+## TL;DR
+
+- Current agreement in one to five bullets.
+
+## Current Truth
+
+## Upstream Inputs
+
+## Downstream Artifacts
+
+## Open Questions
+\`\`\`
+`;
 exports.starterFiles = {
     "wiki/README.md": `${(0, exports.metadata)("wiki-entry", "short", "wiki/meta/wiki-ops-v1-decisions.md", "top-level wiki structure changes")}
 # Project Wiki
@@ -381,10 +552,7 @@ This directory is the durable project-planning source of truth. Keep product dir
 
 - [[startup]]
 - [[index]]
-- [[canonical/project-brief]]
-- [[canonical/open-questions]]
-- [[canonical/assumptions]]
-- [[canonical/risks]]
+- [[meta/document-taxonomy]]
 `,
     "wiki/canonical/project-brief.md": `${(0, exports.metadata)("project-canonical", "medium", "none", "product direction, audience, scope, success criteria, or language choice changes")}
 # Project Brief
@@ -502,17 +670,18 @@ No project decisions yet.
 ## TL;DR
 
 - This Decision Pack records accepted wiki operating choices for project-librarian.
-- It covers wiki structure, startup hook scope, metadata, language policy, git hook behavior, migration review, and inbox handling.
+- It covers wiki structure, document taxonomy, startup hook scope, metadata, language policy, git hook behavior, migration review, and inbox handling.
 - Project product decisions belong in \`wiki/decisions/\`, while these operating decisions stay in \`wiki/meta/\`.
 
 Status: accepted
 Scope: wiki operation
-Canonical: [[meta/operating-model]], [[meta/decision-policy]]
+Canonical: [[meta/operating-model]], [[meta/decision-policy]], [[meta/document-taxonomy]]
 
 | Date | Decision | Rationale | Rejected Alternative | Revisit Trigger | Canonical Link |
 | --- | --- | --- | --- | --- | --- |
 | ${workspace_1.today} | Keep the wiki root at \`./wiki\`. | Planning docs live with the project. | External docs only. | Another tool cannot read \`./wiki\` or the team needs another path. | [[meta/operating-model]] |
 | ${workspace_1.today} | Split \`canonical/\` and \`decisions/\`. | Current truth and decision history are easier to scan when separated. | A single mixed docs directory. | The structure proves too heavy for small projects. | [[meta/decision-policy]] |
+| ${workspace_1.today} | Classify new wiki content through a service-lifecycle document taxonomy before writing or consolidating it. | Agents need a structural contract for deciding whether content is strategy, product, policy, UX, design, data, engineering, security/legal, QA, release/ops, business ops, or improvement/EOL truth. | Let agents append new content to whichever existing page is nearby. | The taxonomy becomes too heavy for small projects or repeatedly misroutes content. | [[meta/document-taxonomy]], [[meta/operating-model]] |
 | ${workspace_1.today} | Inject only \`startup.md\` and \`index.md\` through Codex, Claude Code, Cursor, and Gemini CLI startup hooks; route detailed files Read On Demand. | Full canonical and decision bodies waste startup tokens. | Always read detailed canonical and decision files first. | Important context is repeatedly missed at startup. | [[startup]], [[index]] |
 | ${workspace_1.today} | Use metadata headers on wiki knowledge pages. | Agents and humans can quickly judge status, scope, budget, and review triggers. | Body-only conventions. | Header maintenance costs more than it saves. | [[meta/operating-model]] |
 | ${workspace_1.today} | Keep wiki operating docs in \`wiki/meta/\`. | Project truth stays focused on product/project content. | Store operating docs in \`canonical/\` or \`decisions/\`. | Meta docs become hard to discover. | [[meta/operating-model]] |
@@ -523,6 +692,7 @@ Canonical: [[meta/operating-model]], [[meta/decision-policy]]
 | ${workspace_1.today} | Migration may mark rows \`needs-human-review\`. | Ambiguous, risky, or high-impact legacy content should not be closed automatically. | Force every migrated row into adopted/rejected/resolved. | Human review queues become too large. | [[meta/operating-model]] |
 | ${workspace_1.today} | Capture stores candidates in \`wiki/inbox/\`. | Useful ideas are not lost, but unreviewed content does not become canonical truth. | Save all conversation content directly into canonical docs. | Inbox content is frequently abandoned. | [[meta/operating-model]] |
 `,
+    "wiki/meta/document-taxonomy.md": exports.documentTaxonomy,
     "wiki/decisions/decision-pack-template.md": `${(0, exports.metadata)("project-decision-template", "short", "wiki/meta/decision-policy.md", "decision pack format changes", "template")}
 # <Topic> v<N> Decisions
 
@@ -571,3 +741,11 @@ Checked: ${workspace_1.today}
 - \`wiki/meta/\` stores wiki operating rules and operating decisions.
 `,
 };
+exports.defaultStarterFilePaths = new Set([
+    "wiki/README.md",
+    "wiki/decisions/README.md",
+    "wiki/decisions/log.md",
+    "wiki/decisions/recent.md",
+    "wiki/meta/document-taxonomy.md",
+    "wiki/sources/karpathy-llm-wiki.md",
+]);

package/dist/wiki-concepts.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conceptIdForFile = conceptIdForFile;
+exports.wikiConceptType = wikiConceptType;
+exports.conceptFromPage = conceptFromPage;
+exports.readWikiConcepts = readWikiConcepts;
+const wiki_files_1 = require("./wiki-files");
+const workspace_1 = require("./workspace");
+function conceptIdForFile(file) {
+    return file.replace(/^wiki\//, "").replace(/\.(md|mdx)$/i, "");
+}
+function wikiConceptType(file, scope) {
+    if (scope === "startup-router" || file === "wiki/startup.md")
+        return "Startup Router";
+    if (scope === "wiki-router" || file === "wiki/index.md" || /^wiki\/indexes\//.test(file))
+        return "Wiki Router";
+    if (scope === "project-canonical" || /^wiki\/canonical\//.test(file))
+        return "Project Canonical Concept";
+    if (scope === "project-decisions" || /^wiki\/decisions\//.test(file))
+        return "Project Decision";
+    if (scope === "source-summary" || /^wiki\/sources\//.test(file))
+        return "Source Summary";
+    if (scope === "wiki-meta" || /^wiki\/meta\//.test(file))
+        return "Wiki Operations Concept";
+    if (/^migration-/.test(scope) || /^wiki\/migration\//.test(file))
+        return "Migration Ledger";
+    if (scope === "inbox" || /^wiki\/inbox\//.test(file))
+        return "Project Candidate";
+    return "Wiki Concept";
+}
+function conceptFromPage(file, text) {
+    const scope = (0, workspace_1.metadataValue)(text, "scope") || "-";
+    const tldr = (0, wiki_files_1.firstTldrBullet)(text);
+    return {
+        budget: (0, workspace_1.metadataValue)(text, "read_budget") || "-",
+        conceptId: conceptIdForFile(file),
+        description: tldr || (0, wiki_files_1.compactSummary)(text),
+        file,
+        reviewTrigger: (0, workspace_1.metadataValue)(text, "review_trigger"),
+        scope,
+        status: (0, workspace_1.metadataValue)(text, "status") || "-",
+        timestamp: (0, workspace_1.metadataValue)(text, "updated"),
+        title: (0, wiki_files_1.wikiTitleForFile)(file, text),
+        type: wikiConceptType(file, scope),
+    };
+}
+function readWikiConcepts(files = (0, wiki_files_1.wikiMarkdownFiles)()) {
+    return files.map((file) => conceptFromPage(file, (0, workspace_1.read)(file)));
+}