chapterhouse 0.3.16 → 0.3.18

package/dist/api/server.js

@@ -203,6 +203,20 @@ function assertValidPagePath(path) {
 function getWikiPageScope(path) {
     return teamWikiSync.isTeamPath(path) ? "team" : "personal";
 }
+function getEmptyWikiWelcomeContent(today = new Date()) {
+    return `---
+title: Wiki
+summary: Empty wiki — get started.
+updated: ${today.toISOString().slice(0, 10)}
+---
+
+# Wiki
+
+Your wiki is empty. Pages are organized by category — projects, people, tools, topics, areas, orgs, facts, preferences, routines.
+
+Create your first page via the wiki UI or by editing files under \`pages/\`.
+`;
+}
 // Active SSE connections
 const sseClients = new Map();
 const pendingSseMessages = [];
@@ -746,6 +760,10 @@ app.get("/api/wiki/page", async (req, res) => {
         : undefined;
     const content = await readWikiPage(path, { authorizationHeader });
     if (content === undefined) {
+        if (path === "pages/index.md") {
+            res.json({ path, content: getEmptyWikiWelcomeContent() });
+            return;
+        }
         throw new NotFoundError("Page not found");
     }
     res.json({ path, content });

package/dist/api/server.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { mkdirSync, rmSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { join } from "node:path";
 import test from "node:test";
@@ -293,6 +293,62 @@ test("server wiki routes support authenticated CRUD", async () => {
         assert.deepEqual(await missingResponse.json(), { error: "Page not found" });
     });
 });
+test("server wiki route synthesizes a welcome page when pages/index.md is missing", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        rmSync(join(serverTestRoot, ".chapterhouse", "wiki", "pages", "index.md"), { force: true });
+        const response = await fetch(`${baseUrl}/api/wiki/page?path=pages/index.md`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(response.status, 200);
+        assert.deepEqual(await response.json(), {
+            path: "pages/index.md",
+            content: `---
+title: Wiki
+summary: Empty wiki — get started.
+updated: ${new Date().toISOString().slice(0, 10)}
+---
+
+# Wiki
+
+Your wiki is empty. Pages are organized by category — projects, people, tools, topics, areas, orgs, facts, preferences, routines.
+
+Create your first page via the wiki UI or by editing files under \`pages/\`.
+`,
+        });
+    });
+});
+test("server wiki route returns stored content for pages/index.md when it exists", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const indexPath = join(serverTestRoot, ".chapterhouse", "wiki", "pages", "index.md");
+        const content = `---
+title: Wiki
+summary: Existing home page.
+updated: 2026-05-12
+---
+
+# Custom Wiki Home
+`;
+        mkdirSync(join(serverTestRoot, ".chapterhouse", "wiki", "pages"), { recursive: true });
+        writeFileSync(indexPath, content, "utf-8");
+        const response = await fetch(`${baseUrl}/api/wiki/page?path=pages/index.md`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(response.status, 200);
+        assert.deepEqual(await response.json(), {
+            path: "pages/index.md",
+            content,
+        });
+    });
+});
+test("server wiki route still returns 404 for other missing wiki pages", async () => {
+    await withStartedServer(async ({ baseUrl, authHeader }) => {
+        const response = await fetch(`${baseUrl}/api/wiki/page?path=pages/projects/nonexistent/index.md`, {
+            headers: { authorization: authHeader },
+        });
+        assert.equal(response.status, 404);
+        assert.deepEqual(await response.json(), { error: "Page not found" });
+    });
+});
 test("server message route validates the SSE connection id", async () => {
     await withStartedServer(async ({ baseUrl, authHeader }) => {
         const response = await fetch(`${baseUrl}/api/message`, {

package/dist/copilot/agents.js

@@ -222,6 +222,8 @@ You are an agent within Chapterhouse, a team-level AI assistant for engineering
 ### Shared Wiki
 All agents share a wiki knowledge base for persistent memory. Use \`wiki_read\` and \`wiki_search\` to find existing knowledge, and \`wiki_update\` to save important findings.
 
+Invoke \`wiki-conventions\` before wiki writes or restructuring work. Treat \`wiki_update\`, \`remember\`, \`forget\`, \`wiki_ingest\`, \`wiki_lint\`, and \`wiki_rebuild_index\` as write-sensitive workflows. Before using them, read \`pages/index.md\`, scan the last 20-30 entries of \`pages/_meta/log.md\`, and run \`wiki_search\` for the topic when the wiki is large or the topic is ambiguous.
+
 ### Communication
 - You receive tasks from @chapterhouse (the orchestrator) or directly from the user
 - Your results are relayed back to the user by @chapterhouse

package/dist/copilot/agents.test.js

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { composeAgentSystemMessage, } from "./agents.js";
+function makeAgent(slug) {
+    return {
+        slug,
+        name: slug,
+        description: `${slug} test agent`,
+        model: "claude-sonnet-4.6",
+        systemMessage: `You are ${slug}.`,
+    };
+}
+test("composeAgentSystemMessage steers wiki-capable agents to wiki-conventions", () => {
+    for (const slug of ["coder", "general-purpose"]) {
+        const message = composeAgentSystemMessage(makeAgent(slug));
+        assert.match(message, /invoke `wiki-conventions` before wiki writes/i);
+        assert.match(message, /wiki_update[\s\S]{0,80}remember[\s\S]{0,80}forget[\s\S]{0,80}wiki_ingest[\s\S]{0,80}wiki_lint[\s\S]{0,80}wiki_rebuild_index/i);
+        assert.match(message, /read `pages\/index\.md`/i);
+        assert.match(message, /scan the last 20-30 entries of `pages\/_meta\/log\.md`/i);
+    }
+});
+//# sourceMappingURL=agents.test.js.map

package/dist/copilot/skills.test.js

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { listSkills } from "./skills.js";
+test("listSkills includes bundled wiki-conventions skill metadata", () => {
+    const skill = listSkills().find((entry) => entry.slug === "wiki-conventions" && entry.source === "bundled");
+    assert.ok(skill);
+    assert.equal(skill.name, "wiki-conventions");
+    assert.match(skill.description, /creating, editing, linting, restructuring, or reviewing Chapterhouse wiki content/i);
+});
+//# sourceMappingURL=skills.test.js.map

package/dist/copilot/system-message.js

@@ -122,6 +122,8 @@ You can delegate **multiple tasks simultaneously**. Different agents can work in
 - With \`remember\`, pass \`entity\` for entity categories (and \`facet\` to target a sub-page). With \`wiki_update\`, give the full canonical path — bad paths are rejected with a suggested correction; just retry with the suggestion.
 - If the structure ever looks wrong, call \`wiki_rebuild_index\` to regenerate the index from disk.
 
+**Wiki writes and restructuring**: Before writing or restructuring wiki content, invoke the \`wiki-conventions\` skill. Treat \`wiki_update\`, \`remember\`, \`forget\`, \`wiki_ingest\`, \`wiki_lint\`, and \`wiki_rebuild_index\` as write-sensitive workflows. Before using them, read \`pages/index.md\`, scan the last 20-30 entries of \`pages/_meta/log.md\`, and run \`wiki_search\` for the topic when the wiki is large or the topic is ambiguous.
+
 **Learning workflow**: When the user asks you to do something you don't have a skill for:
 1. **Search skills.sh first**: Use the find-skills skill to search for existing community skills.
 2. **Present what you found**: Tell the user the skill name, what it does, and its security status.

package/dist/copilot/system-message.test.js

@@ -22,4 +22,15 @@ test("orchestrator prompt omits version banner when version is not provided", ()
     const message = getOrchestratorSystemMessage();
     assert.doesNotMatch(message, /chapterhouse v\d/);
 });
+test("orchestrator prompt requires wiki-conventions before write-sensitive wiki work", () => {
+    const message = getOrchestratorSystemMessage();
+    assert.match(message, /wiki-conventions[\s\S]{0,500}wiki_update[\s\S]{0,200}remember[\s\S]{0,200}forget[\s\S]{0,200}wiki_ingest[\s\S]{0,200}wiki_lint[\s\S]{0,200}wiki_rebuild_index/i);
+    assert.match(message, /before writing or restructuring wiki content/i);
+});
+test("orchestrator prompt describes the wiki orientation ritual", () => {
+    const message = getOrchestratorSystemMessage();
+    assert.match(message, /read `pages\/index\.md`/i);
+    assert.match(message, /scan the last 20-30 entries of `pages\/_meta\/log\.md`/i);
+    assert.match(message, /run `wiki_search` for the topic/i);
+});
 //# sourceMappingURL=system-message.test.js.map

package/dist/wiki/fs.js

@@ -7,6 +7,7 @@ import { WIKI_DIR, WIKI_PAGES_DIR, WIKI_SOURCES_DIR } from "../paths.js";
 import { normalizeWikiPath } from "./path-utils.js";
 import { topicPathError } from "./topic-structure.js";
 const INDEX_PATH = join(WIKI_DIR, "index.md");
+const PAGES_INDEX_PATH = join(WIKI_PAGES_DIR, "index.md");
 const LOG_PATH = join(WIKI_PAGES_DIR, "_meta", "log.md");
 /**
  * Write a file atomically: write to a temp file in the same directory, fsync,
@@ -63,6 +64,18 @@ Last updated: ${new Date().toISOString().slice(0, 10)}
 _(No pages yet.)_
 `;
 }
+function getInitialPagesIndex() {
+    return `---
+title: Wiki
+summary: Index of all wiki pages.
+updated: ${new Date().toISOString().slice(0, 10)}
+---
+
+# Wiki
+
+Welcome to your Chapterhouse wiki. Pages are organized by category — projects, people, tools, topics, areas, orgs, facts, preferences, routines. Use the navigation to explore, or search.
+`;
+}
 const INITIAL_LOG = `# Wiki Action Log
 
 _Append-only record of wiki operations._
@@ -79,6 +92,9 @@ export function ensureWikiStructure() {
     if (!existsSync(INDEX_PATH)) {
         writeFileAtomic(INDEX_PATH, getInitialIndex());
     }
+    if (!existsSync(PAGES_INDEX_PATH)) {
+        writeFileAtomic(PAGES_INDEX_PATH, getInitialPagesIndex());
+    }
     if (!existsSync(LOG_PATH)) {
         writeFileAtomic(LOG_PATH, INITIAL_LOG);
     }

package/dist/wiki/fs.test.js

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import test from "node:test";
 const repoRoot = process.cwd();
@@ -20,6 +20,7 @@ test("wiki fs creates the wiki structure and supports page CRUD", async () => {
     assert.equal(wiki.ensureWikiStructure(), true);
     assert.equal(wiki.ensureWikiStructure(), false);
     assert.equal(existsSync(join(wikiDir, "index.md")), true);
+    assert.equal(existsSync(join(wikiDir, "pages", "index.md")), true);
     assert.equal(existsSync(join(wikiDir, "pages", "_meta", "log.md")), true);
     wiki.writePage("pages/shared/runbooks/deploy.md", "# Deploy\n");
     assert.equal(wiki.pageExists("pages/shared/runbooks/deploy.md"), true);
@@ -30,6 +31,23 @@ test("wiki fs creates the wiki structure and supports page CRUD", async () => {
     assert.equal(wiki.deletePage("pages/shared/runbooks/deploy.md"), false);
     assert.equal(wiki.readPage("pages/shared/runbooks/deploy.md"), undefined);
 });
+test("wiki fs seeds pages/index.md when missing", async () => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+    mkdirSync(join(repoRoot, ".test-work"), { recursive: true });
+    const wiki = await loadFsModule();
+    wiki.ensureWikiStructure();
+    const pagesIndex = readFileSync(join(wikiDir, "pages", "index.md"), "utf-8");
+    assert.match(pagesIndex, /^---\n/m);
+    assert.match(pagesIndex, /^title: Wiki$/m);
+});
+test("wiki fs does not overwrite an existing pages/index.md", async () => {
+    rmSync(sandboxRoot, { recursive: true, force: true });
+    mkdirSync(join(wikiDir, "pages"), { recursive: true });
+    writeFileSync(join(wikiDir, "pages", "index.md"), "# Custom Wiki Home\n", "utf-8");
+    const wiki = await loadFsModule();
+    wiki.ensureWikiStructure();
+    assert.equal(readFileSync(join(wikiDir, "pages", "index.md"), "utf-8"), "# Custom Wiki Home\n");
+});
 test("wiki fs rejects unsafe page paths", async () => {
     const wiki = await loadFsModule();
     assert.doesNotThrow(() => wiki.assertPagePath("pages/shared/runbooks/deploy.md"));

package/dist/wiki/index-manager.test.js

@@ -58,10 +58,19 @@ test("buildIndexEntryForPage treats frontmatter summary as the canonical index s
 });
 test("parseIndex self-heals an empty index from on-disk pages", async () => {
     const { indexManager, wikiFs } = await loadModules();
+    const today = new Date().toISOString().slice(0, 10);
     wikiFs.writePage("pages/team/vision.md", "# Vision\n\nShared direction for the team.\n");
     wikiFs.writeIndexFile("# Wiki Index\n\n");
     const entries = indexManager.parseIndex();
     assert.deepEqual(entries, [
+        {
+            path: "pages/index.md",
+            title: "Wiki",
+            summary: "Index of all wiki pages.",
+            section: "Knowledge",
+            tags: undefined,
+            updated: today,
+        },
         {
             path: "pages/team/vision.md",
             title: "Vision",
@@ -119,6 +128,7 @@ test("searchIndex ranks strong metadata matches and falls back to page bodies",
 });
 test("addToIndex, removeFromIndex, and getIndexSummary keep the catalog in sync", async () => {
     const { indexManager } = await loadModules();
+    const today = new Date().toISOString().slice(0, 10);
     indexManager.addToIndex({
         path: "pages/people/ada.md",
         title: "Ada Lovelace",
@@ -143,6 +153,8 @@ test("addToIndex, removeFromIndex, and getIndexSummary keep the catalog in sync"
     });
     assert.equal(indexManager.removeFromIndex("pages/projects/launch.md"), true);
     assert.equal(indexManager.removeFromIndex("pages/projects/missing.md"), false);
-    assert.equal(indexManager.getIndexSummary(), "**People**: Ada Lovelace: Owns regression coverage [qa, testing] (2026-05-06)");
+    const summary = indexManager.getIndexSummary();
+    assert.match(summary, /\*\*People\*\*: Ada Lovelace: Owns regression coverage \[qa, testing\] \(2026-05-06\)/);
+    assert.match(summary, new RegExp(`\\*\\*Index\\*\\*: Wiki: Index of all wiki pages\\. \\(${today}\\)`));
 });
 //# sourceMappingURL=index-manager.test.js.map

package/dist/wiki/lint.test.js

@@ -25,6 +25,18 @@ test.after(() => {
 function wikiPage(frontmatter, body) {
     return `---\n${frontmatter.join("\n")}\n---\n\n${body.trim()}\n`;
 }
+function wikiIndexWithSharedEntries(...entries) {
+    return `# Wiki Index
+
+## Index
+
+- [Wiki](pages/index.md) — Index of all wiki pages.
+
+## Shared
+
+${entries.join("\n")}
+`;
+}
 function setPageAge(relativePath, ageInDays) {
     const stamped = new Date(Date.now() - ageInDays * 24 * 60 * 60 * 1000);
     const fullPath = join(wikiDir, relativePath);
@@ -39,14 +51,9 @@ test("lintWiki reports orphan pages and index entries pointing to missing pages"
         "updated: 2026-05-12",
         "tags: [engineering]",
     ], "# Orphan\n\nThis orphan page has enough descriptive body text to avoid the premature-page lint while still remaining absent from the index."));
-    wikiFs.writeIndexFile(`# Wiki Index
-
-## Shared
-
-- [Missing](pages/shared/missing.md) — Not on disk
-`);
+    wikiFs.writeIndexFile(wikiIndexWithSharedEntries("- [Missing](pages/shared/missing.md) — Not on disk"));
     const report = lint.lintWiki();
-    assert.equal(report.pageCount, 1);
+    assert.equal(report.pageCount, 2);
     assert.equal(report.sourceCount, 0);
     assert.deepEqual(report.issues.map((issue) => `${issue.rule}:${issue.severity}:${issue.path ?? "-"}`).sort(), [
         "missing-page:warning:pages/shared/missing.md",
@@ -62,14 +69,9 @@ test("renderWikiLintReport preserves the current wiki_lint report format", async
         "updated: 2026-05-12",
         "tags: [engineering]",
     ], "# Orphan\n\nThis orphan page has enough descriptive body text to avoid the premature-page lint while still remaining absent from the index."));
-    wikiFs.writeIndexFile(`# Wiki Index
-
-## Shared
-
-- [Tracked](pages/shared/tracked.md) — Present only in the index
-`);
+    wikiFs.writeIndexFile(wikiIndexWithSharedEntries("- [Tracked](pages/shared/tracked.md) — Present only in the index"));
     const rendered = lint.renderWikiLintReport(lint.lintWiki());
-    assert.match(rendered, /^Wiki health report \(1 pages, 0 sources\):/);
+    assert.match(rendered, /^Wiki health report \(2 pages, 0 sources\):/);
     assert.match(rendered, /warning\s+\|\s+orphan-page\s+\|\s+pages\/shared\/orphan\.md/);
     assert.match(rendered, /warning\s+\|\s+missing-page\s+\|\s+pages\/shared\/tracked\.md/);
     assert.match(rendered, /\*\*Suggestions\*\*: Look for pages that should link to each other/);
@@ -83,12 +85,7 @@ test("renderWikiLintReport reports the healthy wiki message when no issues are f
         "updated: 2026-05-12",
         "tags: [engineering]",
     ], "# Indexed\n\n## Overview\n\nTracked page with enough detail to stay above the premature-page threshold and remain clearly established as a real page in the healthy-wiki case."));
-    wikiFs.writeIndexFile(`# Wiki Index
-
-## Shared
-
-- [Indexed](pages/shared/indexed.md) — Tracked page
-`);
+    wikiFs.writeIndexFile(wikiIndexWithSharedEntries("- [Indexed](pages/shared/indexed.md) — Tracked page"));
     const rendered = lint.renderWikiLintReport(lint.lintWiki());
     assert.match(rendered, /✅ No issues found\. Index and pages are in sync\./);
 });

package/dist/wiki/topic-structure.js

@@ -21,12 +21,16 @@ import { normalizeWikiPath } from "./path-utils.js";
 export const FLAT_CATEGORIES = ["preferences", "facts", "routines"];
 /** Path prefixes (relative to the wiki root) that follow their own conventions. */
 export const EXEMPT_PREFIXES = [
+    "pages/_meta/",
     "pages/conversations/",
     "pages/team/",
     "pages/okrs/",
     "pages/kpis/",
     "pages/shared/",
 ];
+export const EXEMPT_PAGES = [
+    "pages/index.md",
+];
 /** Map a `remember`-style category name to its directory under pages/. */
 const CATEGORY_DIR_MAP = {
     person: "people",
@@ -65,7 +69,8 @@ function isFlatCategory(dir) {
     return FLAT_CATEGORIES.includes(dir);
 }
 function isExemptPath(relativePath) {
-    return EXEMPT_PREFIXES.some((p) => relativePath.startsWith(p));
+    return EXEMPT_PAGES.includes(relativePath)
+        || EXEMPT_PREFIXES.some((p) => relativePath.startsWith(p));
 }
 /** Slugify a free-text name into a wiki-safe path segment. */
 export function slugify(name) {
@@ -154,7 +159,8 @@ export function validateTopicPath(relativePath) {
         ok: false,
         reason: `'${topDir}' is not a recognized wiki category. ` +
             `Use one of: ${valid} (entity categories take a topic directory: pages/<category>/<topic>/<page>.md). ` +
-            `Conversations and team pages are written by the system.`,
+            `Conversations and team pages are written by the system. ` +
+            `(pages/_meta/ is reserved for system metadata.)`,
     };
 }
 /** Convenience: returns the error message string for an invalid path, or undefined if valid. */

package/dist/wiki/topic-structure.test.js

@@ -25,6 +25,7 @@ test("topicPagePath builds canonical paths", () => {
     assert.equal(topicPagePath("tool", "Kubernetes"), "pages/tools/kubernetes/index.md");
 });
 test("validateTopicPath accepts canonical and exempt paths", () => {
+    assert.deepEqual(validateTopicPath("pages/index.md"), { ok: true });
     assert.deepEqual(validateTopicPath("pages/projects/chapterhouse/index.md"), { ok: true });
     assert.deepEqual(validateTopicPath("pages/projects/chapterhouse/decisions.md"), { ok: true });
     assert.deepEqual(validateTopicPath("pages/people/brian/index.md"), { ok: true });
@@ -34,6 +35,16 @@ test("validateTopicPath accepts canonical and exempt paths", () => {
     assert.deepEqual(validateTopicPath("pages/team/onboarding.md"), { ok: true });
     assert.deepEqual(validateTopicPath("pages/okrs/2026-Q2.md"), { ok: true });
 });
+test("validateTopicPath accepts system-managed pages/_meta subtree paths", () => {
+    assert.deepEqual(validateTopicPath("pages/_meta/log.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/_meta/taxonomy.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/_meta/log-2026.md"), { ok: true });
+    assert.deepEqual(validateTopicPath("pages/_meta/sub/file.md"), { ok: true });
+});
+test("validateTopicPath rejects pages/_meta without a page file", () => {
+    const r = validateTopicPath("pages/_meta");
+    assert.equal(r.ok, false);
+});
 test("validateTopicPath rejects a bare entity-category file and suggests the topic index", () => {
     const r = validateTopicPath("pages/projects/chapterhouse.md");
     assert.equal(r.ok, false);
@@ -60,6 +71,7 @@ test("validateTopicPath rejects unknown top-level categories", () => {
     const r = validateTopicPath("pages/randomstuff/foo.md");
     assert.equal(r.ok, false);
     assert.match(r.ok === false ? r.reason : "", /not a recognized wiki category/);
+    assert.match(r.ok === false ? r.reason : "", /pages\/_meta\/ is reserved for system metadata/);
 });
 test("validateTopicPath rejects non-slug topic or page names", () => {
     const r = validateTopicPath("pages/projects/Chapter House/index.md");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chapterhouse",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Chapterhouse — a team-level AI assistant for engineering teams, built on the GitHub Copilot SDK. Web UI only.",
   "bin": {
     "chapterhouse": "dist/cli.js"

package/skills/wiki-conventions/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: wiki-conventions
+description: Use when creating, editing, linting, restructuring, or reviewing Chapterhouse wiki content.
+when_to_load: Wiki tools, remember/forget workflows, or direct edits under the Chapterhouse wiki.
+related_skills:
+  - squad
+---
+
+# Wiki Conventions
+
+Use this skill before creating, editing, linting, restructuring, archiving, or reviewing Chapterhouse wiki content.
+
+## Orientation Ritual — Mandatory Before Any Wiki Write
+
+Perform this checklist before using `wiki_update`, `remember`, `forget`, `wiki_ingest`, `wiki_lint`, or `wiki_rebuild_index`:
+
+1. Read `pages/index.md` with `wiki_read`.
+2. Scan the last 20-30 entries of `pages/_meta/log.md` to see recent edits, archives, and reorganizations.
+3. If the wiki is large, the topic is ambiguous, or you might be creating a page, run `wiki_search` for the topic first.
+
+Do not skip the ritual because the task feels small. The point is to avoid duplicate pages, category mistakes, stale contradictions, and taxonomy drift.
+
+## Wiki Structure Recap
+
+- **Entity categories** live at `pages/<category>/<topic>/index.md` with optional facet pages beside the overview.
+- **Flat categories** live in a single page such as `pages/preferences.md`, `pages/facts.md`, or `pages/routines.md`.
+- **Decisions** always belong to an entity and should land in `pages/<entity-category>/<topic>/decisions.md`.
+
+## Naming Conventions
+
+- Use lowercase only.
+- Use kebab-case slugs.
+- Do not put dates in slugs.
+- Keep facet names predictable and durable, such as `decisions`, `feature-ideas`, or `architecture`.
+- If a name feels ad hoc, it probably belongs as a section on an existing page instead of a new facet.
+
+## `index.md` vs Facet Pages
+
+- Use `index.md` for the durable overview of a topic, entity, or area.
+- Use a facet page only when the subtopic has ongoing value and a stable identity.
+- Do not create a facet page as random overflow for a page that merely feels long today.
+- If a page is growing because it contains several durable subtopics, split those into facets and keep `index.md` as the orientation page.
+
+## Page Creation Thresholds
+
+- Create a new page when a topic appears in two or more distinct sources or interactions.
+- Create a new page when the topic is central to one major source, even if it is only one source so far.
+- Add to an existing page when coverage already exists.
+- Do not create a page for a passing mention, transient detail, or one-off aside.
+- Split pages once they approach roughly 300 lines.
+- Archive fully superseded pages into `pages/_archive/` and remove them from the active index rather than letting stale content linger in place.
+
+## Decision Recording Protocol
+
+- With `remember`, use `category: "decision"` plus both `about` and `entity`.
+- Record the decision against the actual entity that owns it.
+- Keep decision facets canonical; prefer `decisions.md` over inventing one-off decision page names.
+
+## Cross-Reference Standards
+
+- Prefer wiki-relative paths over raw URLs when a wiki page exists.
+- Avoid raw local absolute paths in the body when a canonical wiki page can be linked instead.
+- Add reciprocal links when the relationship is durable enough that future readers should discover it from either side.
+
+## Tag Usage
+
+- Treat the merged taxonomy as the source of truth: code-defined defaults plus optional `pages/_meta/taxonomy.md` extensions.
+- Read `pages/_meta/taxonomy.md` before inventing a new tag.
+- If a new durable tag is needed, extend `pages/_meta/taxonomy.md` first instead of inventing the tag inline on a page.
+
+## Contradiction Update Policy
+
+When two sources disagree:
+
+1. Compare dates first.
+2. If the conflict is real, preserve both claims instead of collapsing them into one "truth".
+3. Keep dates, sources, or citations in the page body so the disagreement is auditable.
+4. Add reciprocal `contradictions:` frontmatter references.
+5. Set `contested: true` while the issue remains unresolved.
+6. Use `confidence` to describe certainty; do not smooth over disagreement with vague prose.
+
+## Tone
+
+- Be terse.
+- Be factual.
+- Be dated when the timing matters.
+- Avoid speculative voice such as "I think" unless the uncertainty itself is the fact being recorded.
+- Prefer explicit source attribution over implied certainty.
+
+## Frontmatter Shape
+
+Required fields:
+
+```yaml
+---
+title: Chapterhouse
+summary: Team-level AI assistant for engineering teams.
+---
+```
+
+Recommended fields for most durable pages:
+
+```yaml
+---
+title: Chapterhouse
+summary: Team-level AI assistant for engineering teams.
+updated: 2026-05-12
+tags: [engineering, orchestration]
+related: [pages/projects/chapterhouse/decisions.md]
+---
+```
+
+Use contradiction-supporting fields when needed:
+
+```yaml
+---
+title: Chapterhouse
+summary: Coordination notes about the runtime architecture.
+updated: 2026-05-12
+tags: [engineering, architecture]
+related: [pages/projects/chapterhouse/index.md]
+confidence: low
+contested: true
+contradictions: [pages/projects/chapterhouse/decisions.md]
+---
+```
+
+Use `autostub: true` only for genuine stubs that are intentionally thin and expected to grow later.
+
+## Common Mistakes
+
+- **Wrong category:** move the content to the correct entity or flat page instead of stretching the path rules.
+- **Page created too early:** merge it into an existing page or section until the topic earns a standalone page.
+- **Invented tag:** update `pages/_meta/taxonomy.md` first.
+- **Skipped orientation ritual:** stop, orient, then retry.
+- **Collapsed contradiction:** preserve both claims, date them, and mark the relationship explicitly.
+
+## Routing Guide — "I want to record X. Where does it go?"
+
+- A durable fact about a named project, tool, person, org, topic, or area -> `pages/<category>/<slug>/index.md`
+- A durable subtopic of an existing entity -> `pages/<category>/<slug>/<facet>.md`
+- A decision about an entity -> `remember` with `category: "decision"`, `about`, and `entity`, or write to that entity's `decisions.md`
+- A user preference or routine -> the corresponding flat category page
+- Source material you want preserved before synthesis -> `wiki_ingest`
+- A passing mention with no durable value yet -> do not create a new page; add it to existing context or leave it out