chapterhouse 0.3.17 → 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/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,6 +21,7 @@ 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/",
@@ -158,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

@@ -35,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);
@@ -61,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.17",
+  "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"