chapterhouse 0.3.13 → 0.3.15

package/dist/copilot/task-event-log.test.js

@@ -14,13 +14,13 @@
  * 10. Multiple tasks tracked independently
  * 11. RING_BUFFER_CAPACITY constant: 500 items, evicts oldest
  *
- * Uses node:test (same pattern as hooks.test.ts, agents.squad.test.ts) so the
+ * Uses node:test (same pattern as hooks.test.ts) so the
  * daemon's `npm test` runner (node --test) picks these up from dist/.
  */
 import { describe, it, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { EventBus } from "@bradygaster/squad-sdk/runtime/event-bus";
-import { RingBuffer, RING_BUFFER_CAPACITY, } from "./task-event-log.js";
+import { agentEventBus } from "./agent-event-bus.js";
+import { RingBuffer, RING_BUFFER_CAPACITY, initTaskEventLog, getTaskLogEvents, subscribeTaskLog, clearTaskLog, taskLogSize, } from "./task-event-log.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -48,87 +48,6 @@ function makeDestroyedEvent(sessionId) {
         timestamp: new Date(),
     };
 }
-/**
- * Builds an isolated task-event-log wired to a fresh EventBus so tests don't
- * share state through the process-level squadEventBus singleton.
- */
-function buildIsolatedLog(bus) {
-    const CAPACITY = RING_BUFFER_CAPACITY;
-    const buffers = new Map();
-    const listeners = new Map();
-    function getOrCreate(taskId) {
-        let b = buffers.get(taskId);
-        if (!b) {
-            b = new RingBuffer(CAPACITY);
-            buffers.set(taskId, b);
-        }
-        return b;
-    }
-    function notify(taskId, event) {
-        const ls = listeners.get(taskId);
-        if (!ls)
-            return;
-        for (const fn of ls) {
-            try {
-                fn(event);
-            }
-            catch { /* non-fatal */ }
-        }
-    }
-    const unsubToolCall = bus.subscribe("session:tool_call", (event) => {
-        const taskId = event.sessionId;
-        if (!taskId)
-            return;
-        const p = event.payload;
-        const ev = {
-            id: 0, taskId,
-            seq: p._seq ?? 0,
-            ts: p._ts ?? Date.now(),
-            kind: p._kind === "tool_complete" ? "tool_complete" : "tool_start",
-            toolName: p.toolName ?? null,
-            summary: p._summary ?? null,
-        };
-        getOrCreate(taskId).push(ev);
-        notify(taskId, ev);
-    });
-    const unsubDestroyed = bus.subscribe("session:destroyed", (event) => {
-        if (event.sessionId) {
-            buffers.delete(event.sessionId);
-            listeners.delete(event.sessionId);
-        }
-    });
-    return {
-        getEvents: (taskId, afterSeq = 0) => {
-            const buf = buffers.get(taskId);
-            if (!buf)
-                return [];
-            const all = buf.getAll();
-            return afterSeq === 0 ? all : all.filter((e) => e.seq > afterSeq);
-        },
-        subscribe: (taskId, fn) => {
-            let ls = listeners.get(taskId);
-            if (!ls) {
-                ls = new Set();
-                listeners.set(taskId, ls);
-            }
-            ls.add(fn);
-            return () => {
-                const lss = listeners.get(taskId);
-                if (lss) {
-                    lss.delete(fn);
-                    if (lss.size === 0)
-                        listeners.delete(taskId);
-                }
-            };
-        },
-        clear: (taskId) => {
-            buffers.delete(taskId);
-            listeners.delete(taskId);
-        },
-        size: () => buffers.size,
-        shutdown: () => { unsubToolCall(); unsubDestroyed(); },
-    };
-}
 // ---------------------------------------------------------------------------
 // RingBuffer — pure class tests
 // ---------------------------------------------------------------------------
@@ -189,87 +108,94 @@ describe("RingBuffer", () => {
 // Task event log (bus-wired) tests
 // ---------------------------------------------------------------------------
 describe("task event log — bus-wired", () => {
-    let bus;
-    let log;
+    let shutdown;
     beforeEach(() => {
-        bus = new EventBus();
-        log = buildIsolatedLog(bus);
+        shutdown = initTaskEventLog();
     });
     afterEach(() => {
-        log.shutdown();
+        shutdown();
     });
     it("returns [] for an unknown taskId", () => {
-        assert.deepEqual(log.getEvents("no-such-task"), []);
+        assert.deepEqual(getTaskLogEvents("no-such-task"), []);
     });
-    it("populates ring buffer on session:tool_call bus event", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-001", kind: "tool_start", seq: 1, toolName: "view" }));
-        const events = log.getEvents("task-001");
+    it("populates ring buffer on session:tool_call bus event", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-001", kind: "tool_start", seq: 1, toolName: "view" }));
+        const events = getTaskLogEvents("task-001");
         assert.equal(events.length, 1);
         assert.equal(events[0].kind, "tool_start");
         assert.equal(events[0].toolName, "view");
         assert.equal(events[0].taskId, "task-001");
         assert.equal(events[0].seq, 1);
+        clearTaskLog("task-001");
     });
-    it("accumulates multiple events in order", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_start", seq: 1, toolName: "bash" }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_complete", seq: 2, summary: "ok" }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_start", seq: 3, toolName: "view" }));
-        const events = log.getEvents("task-002");
+    it("accumulates multiple events in order", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_start", seq: 1, toolName: "bash" }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_complete", seq: 2, summary: "ok" }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-002", kind: "tool_start", seq: 3, toolName: "view" }));
+        const events = getTaskLogEvents("task-002");
         assert.equal(events.length, 3);
         assert.equal(events[0].seq, 1);
         assert.equal(events[2].seq, 3);
         assert.equal(events[1].kind, "tool_complete");
-    });
-    it("getEvents filters by afterSeq", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 1 }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 2 }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 3 }));
-        assert.equal(log.getEvents("task-003", 1).length, 2);
-        assert.equal(log.getEvents("task-003", 2).length, 1);
-        assert.equal(log.getEvents("task-003", 3).length, 0);
-    });
-    it("subscribe delivers events as they arrive", async () => {
+        clearTaskLog("task-002");
+    });
+    it("getEvents filters by afterSeq", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 1 }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 2 }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-003", seq: 3 }));
+        assert.equal(getTaskLogEvents("task-003", 1).length, 2);
+        assert.equal(getTaskLogEvents("task-003", 2).length, 1);
+        assert.equal(getTaskLogEvents("task-003", 3).length, 0);
+        clearTaskLog("task-003");
+    });
+    it("subscribe delivers events as they arrive", () => {
         const received = [];
-        log.subscribe("task-004", (e) => received.push(e.toolName ?? "?"));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-004", toolName: "bash" }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-004", toolName: "view" }));
+        const unsub = subscribeTaskLog("task-004", (e) => received.push(e.toolName ?? "?"));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-004", toolName: "bash" }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-004", toolName: "view" }));
+        unsub();
         assert.deepEqual(received, ["bash", "view"]);
+        clearTaskLog("task-004");
     });
-    it("subscribe unsub stops delivery", async () => {
+    it("subscribe unsub stops delivery", () => {
         const received = [];
-        const unsub = log.subscribe("task-005", (e) => received.push(e.toolName ?? "?"));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-005", toolName: "bash" }));
+        const unsub = subscribeTaskLog("task-005", (e) => received.push(e.toolName ?? "?"));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-005", toolName: "bash" }));
         unsub();
-        await bus.emit(makeToolCallEvent({ sessionId: "task-005", toolName: "view" }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-005", toolName: "view" }));
         assert.equal(received.length, 1);
         assert.equal(received[0], "bash");
-    });
-    it("clearTaskLog removes buffer and listeners", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-006", seq: 1 }));
-        assert.equal(log.getEvents("task-006").length, 1);
-        log.clear("task-006");
-        assert.equal(log.getEvents("task-006").length, 0);
-    });
-    it("session:destroyed auto-clears ring buffer", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-007", seq: 1 }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-007", seq: 2 }));
-        assert.equal(log.getEvents("task-007").length, 2);
-        await bus.emit(makeDestroyedEvent("task-007"));
-        assert.equal(log.getEvents("task-007").length, 0);
-    });
-    it("tracks multiple tasks independently", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-A", seq: 1, toolName: "bash" }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-B", seq: 1, toolName: "view" }));
-        await bus.emit(makeToolCallEvent({ sessionId: "task-A", seq: 2, toolName: "edit" }));
-        assert.equal(log.getEvents("task-A").length, 2);
-        assert.equal(log.getEvents("task-B").length, 1);
-        assert.equal(log.getEvents("task-A")[0].toolName, "bash");
-        assert.equal(log.getEvents("task-B")[0].toolName, "view");
-        assert.equal(log.size(), 2);
-    });
-    it("events for wrong taskId are not visible to other tasks", async () => {
-        await bus.emit(makeToolCallEvent({ sessionId: "task-X", seq: 1 }));
-        assert.equal(log.getEvents("task-Y").length, 0);
+        clearTaskLog("task-005");
+    });
+    it("clearTaskLog removes buffer and listeners", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-006", seq: 1 }));
+        assert.equal(getTaskLogEvents("task-006").length, 1);
+        clearTaskLog("task-006");
+        assert.equal(getTaskLogEvents("task-006").length, 0);
+    });
+    it("session:destroyed auto-clears ring buffer", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-007", seq: 1 }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-007", seq: 2 }));
+        assert.equal(getTaskLogEvents("task-007").length, 2);
+        agentEventBus.emit(makeDestroyedEvent("task-007"));
+        assert.equal(getTaskLogEvents("task-007").length, 0);
+    });
+    it("tracks multiple tasks independently", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-A", seq: 1, toolName: "bash" }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-B", seq: 1, toolName: "view" }));
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-A", seq: 2, toolName: "edit" }));
+        assert.equal(getTaskLogEvents("task-A").length, 2);
+        assert.equal(getTaskLogEvents("task-B").length, 1);
+        assert.equal(getTaskLogEvents("task-A")[0].toolName, "bash");
+        assert.equal(getTaskLogEvents("task-B")[0].toolName, "view");
+        assert.equal(taskLogSize(), 2);
+        clearTaskLog("task-A");
+        clearTaskLog("task-B");
+    });
+    it("events for wrong taskId are not visible to other tasks", () => {
+        agentEventBus.emit(makeToolCallEvent({ sessionId: "task-X", seq: 1 }));
+        assert.equal(getTaskLogEvents("task-Y").length, 0);
+        clearTaskLog("task-X");
     });
 });
 //# sourceMappingURL=task-event-log.test.js.map

package/dist/copilot/tools.js

@@ -6,36 +6,21 @@ import { join } from "path";
 import { homedir } from "os";
 import { listSkills, createSkill, removeSkill } from "./skills.js";
 import { config, persistModel } from "../config.js";
-import { createSessionHooks } from "./hooks.js";
-import { getCurrentSourceChannel, getCurrentActivityCallback, getCurrentAuthenticatedUser, getLastAuthenticatedUser, getCurrentAuthorizationHeader, getCurrentChannelKey, getCurrentSessionKey, switchSessionModel, } from "./orchestrator.js";
+import { getCurrentSourceChannel, getCurrentActivityCallback, getCurrentAuthenticatedUser, getLastAuthenticatedUser, getCurrentAuthorizationHeader, getCurrentSessionKey, switchSessionModel, } from "./orchestrator.js";
 import { getRouterConfig, updateRouterConfig } from "./router.js";
 import { ensureWikiStructure, readPage, writePage, deletePage, listPages, writeRawSource, listSources, assertPagePath } from "../wiki/fs.js";
 import { searchIndex, addToIndex, removeFromIndex, parseIndex, buildIndexEntryForPage } from "../wiki/index-manager.js";
 import { appendLog } from "../wiki/log-manager.js";
+import { getCategoryDir, topicPagePath, slugify, entityCategories, FLAT_CATEGORIES } from "../wiki/topic-structure.js";
 import { withWikiWrite } from "../wiki/lock.js";
 import { readWikiPage, teamWikiSync } from "../wiki/team-sync.js";
-import { getAgentRegistry, getAgent, createEphemeralAgentSession, createSquadAgentSession, getAgentSessionStatus, getTask, registerTask, completeTask, failTask, createAgentFile, removeAgentFile, loadAgents, } from "./agents.js";
+import { getAgentRegistry, getAgent, createEphemeralAgentSession, getAgentSessionStatus, getTask, registerTask, completeTask, failTask, createAgentFile, removeAgentFile, loadAgents, } from "./agents.js";
 import { adoGetOkrs, adoOkrSummary, adoUpdateKr } from "../integrations/ado-skill.js";
 import { TeamsNotifier } from "../integrations/teams-notify.js";
 import { TeamPushClient } from "../integrations/team-push.js";
 import { OKRMapper, parseOKRPageContent } from "./okr-mapper.js";
-import { getChannelProject } from "../squad/context.js";
-import { findSquadAgent } from "../squad/registry.js";
-import { buildSquadSystemPrefix } from "../squad/charter.js";
-import { mirrorDecisionToWiki, syncDecisionsFileToWiki } from "../squad/mirror.js";
 import { childLogger } from "../util/logger.js";
 const log = childLogger("tools");
-function getCategoryDir(category) {
-    const map = {
-        person: "people",
-        project: "projects",
-        preference: "preferences",
-        fact: "facts",
-        routine: "routines",
-        decision: "decisions",
-    };
-    return map[category] || category;
-}
 /** Escape a string for safe inclusion as a single-line YAML scalar value. */
 function yamlEscape(value) {
     // Always quote and escape backslashes, double quotes, and newlines.
@@ -112,45 +97,15 @@ export function createTools(deps) {
                 if (agent?.slug === "chapterhouse") {
                     return "Cannot delegate to yourself. Handle this directly or pick a specialist agent.";
                 }
-                const channelKey = getCurrentChannelKey() ?? "default";
-                const projectRoot = config.squadEnabled ? (getChannelProject(channelKey) ?? undefined) : undefined;
-                const squadDescriptor = (!agent && projectRoot)
-                    ? (() => { try {
-                        return findSquadAgent(projectRoot, args.agent_name);
-                    }
-                    catch {
-                        return null;
-                    } })()
-                    : null;
-                if (!agent && !squadDescriptor) {
+                if (!agent) {
                     const available = getAgentRegistry().map((a) => a.slug).join(", ");
                     return `Agent '${args.agent_name}' not found. Available agents: ${available}`;
                 }
-                const delegatedSlug = agent?.slug ?? squadDescriptor?.slug ?? args.agent_name;
+                const delegatedSlug = agent.slug;
                 let session;
-                let isSquadAgent = false;
                 try {
                     const allTools = createTools(deps);
-                    if (squadDescriptor && projectRoot) {
-                        const squadContext = {
-                            projectRoot,
-                            squadDir: join(projectRoot, ".squad"),
-                            teamDir: join(projectRoot, ".squad"),
-                            personalDir: null,
-                            mode: "local",
-                            projectKey: null,
-                            config: {},
-                            agents: [squadDescriptor],
-                            decisionsPath: join(projectRoot, ".squad", "decisions.md"),
-                            loadedAt: new Date().toISOString(),
-                        };
-                        const charterPrefix = await buildSquadSystemPrefix(squadContext, squadDescriptor);
-                        session = await createSquadAgentSession(delegatedSlug, deps.client, allTools, charterPrefix, args.model_override || squadDescriptor.modelPreference);
-                        isSquadAgent = true;
-                    }
-                    else {
-                        session = await createEphemeralAgentSession(agent.slug, deps.client, allTools, args.model_override);
-                    }
+                    session = await createEphemeralAgentSession(agent.slug, deps.client, allTools, args.model_override);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -212,28 +167,6 @@ export function createTools(deps) {
                         completeTask(task.taskId, output);
                         db.prepare(`UPDATE agent_tasks SET status = 'completed', result = ?, completed_at = CURRENT_TIMESTAMP WHERE task_id = ?`).run(output.slice(0, 10000), task.taskId);
                         deps.onAgentTaskComplete(task.taskId, delegatedSlug, output);
-                        if (isSquadAgent && projectRoot && squadDescriptor) {
-                            try {
-                                const wikiDecisionPath = await mirrorDecisionToWiki({
-                                    taskId: task.taskId,
-                                    projectRoot,
-                                    squadAgentSlug: squadDescriptor.slug,
-                                    wikiDecisionPath: "",
-                                }, args.summary, output);
-                                db.prepare(`INSERT OR REPLACE INTO squad_task_links (task_id, project_root, squad_agent_slug, wiki_decision_path)
-                   VALUES (?, ?, ?, ?)`).run(task.taskId, projectRoot, squadDescriptor.slug, wikiDecisionPath);
-                                // Sync the full decisions.md file to the wiki so the page reflects
-                                // all 89+ entries, not just this task-completion entry.
-                                syncDecisionsFileToWiki(projectRoot).then(syncResult => {
-                                    if (syncResult) {
-                                        log.info({ entriesSynced: syncResult.entriesSynced, wikiPath: syncResult.wikiPath }, "Post-task squad decisions synced to wiki");
-                                    }
-                                }).catch(() => { });
-                            }
-                            catch (mirrorErr) {
-                                log.error({ err: mirrorErr instanceof Error ? mirrorErr.message : mirrorErr }, "Failed to mirror squad decision to wiki (non-fatal)");
-                            }
-                        }
                     }
                     catch (err) {
                         const msg = err instanceof Error ? err.message : String(err);
@@ -253,7 +186,7 @@ export function createTools(deps) {
                 })();
                 const model = (args.model_override && args.model_override.length > 0)
                     ? args.model_override
-                    : squadDescriptor?.modelPreference || (agent?.model === "auto" ? "claude-sonnet-4.6" : agent?.model || "claude-sonnet-4.6");
+                    : (agent.model === "auto" ? "claude-sonnet-4.6" : agent.model || "claude-sonnet-4.6");
                 return `Task delegated to @${delegatedSlug} (${model}). Task ID: ${task.taskId}. I'll notify you when it's done.`;
             },
         }),
@@ -323,12 +256,10 @@ export function createTools(deps) {
             },
         }),
         defineTool("show_agent_roster", {
-            description: "List all registered agents with their name, model, status, and current tasks. When a squad project is active, also shows squad team members available via @mention.",
+            description: "List all registered agents with their name, model, status, and current tasks.",
             parameters: z.object({}),
             handler: async () => {
                 const agents = getAgentRegistry();
-                const channelKey = getCurrentChannelKey() ?? "default";
-                const projectRoot = config.squadEnabled ? (getChannelProject(channelKey) ?? undefined) : undefined;
                 const chLines = agents.map((a) => {
                     const status = getAgentSessionStatus(a.slug);
                     const runningTasks = status.tasks.filter((t) => t.status === "running");
@@ -338,25 +269,9 @@ export function createTools(deps) {
                         : "";
                     return `• @${a.slug} (${a.name}) — ${a.model} — ${badge}${taskInfo}\n  ${a.description}`;
                 });
-                let squadSection = "";
-                if (projectRoot) {
-                    try {
-                        const { renderProjectAgentRoster } = await import("../squad/registry.js");
-                        const squadRoster = renderProjectAgentRoster(projectRoot);
-                        if (squadRoster) {
-                            squadSection = `\n\nSquad agents (project: ${projectRoot}):\n${squadRoster}`;
-                        }
-                    }
-                    catch {
-                        // squad unavailable — skip
-                    }
-                }
-                else if (config.squadEnabled) {
-                    squadSection = "\n\n(Squad is enabled — select a project context to see squad agents)";
-                }
-                if (chLines.length === 0 && !squadSection)
+                if (chLines.length === 0)
                     return "No agents registered.";
-                return `Registered agents (${chLines.length}):\n${chLines.join("\n")}${squadSection}`;
+                return `Registered agents (${chLines.length}):\n${chLines.join("\n")}`;
             },
         }),
         defineTool("teams_notify", {
@@ -584,7 +499,6 @@ export function createTools(deps) {
                     const session = await deps.client.resumeSession(args.session_id, {
                         model: config.copilotModel,
                         onPermissionRequest: approveAll,
-                        hooks: createSessionHooks(args.name),
                     });
                     const db = getDb();
                     db.prepare(`INSERT OR REPLACE INTO agent_sessions (slug, copilot_session_id, model, status)
@@ -726,55 +640,73 @@ export function createTools(deps) {
         }),
         // ----- Wiki-backed memory facades (preserve existing remember/recall/forget UX) -----
         defineTool("remember", {
-            description: "Save a fact, preference, or detail to the wiki. Routes to entity-specific pages automatically. " +
+            description: "Save a fact, preference, or detail to the wiki. Routes to topic pages automatically. " +
                 "Use for discrete facts ('The team prefers dark mode', 'Project uses Vercel'). " +
+                "Entity categories (project/person/org/tool/topic/area) are filed under pages/<category>/<topic>/index.md; " +
+                "pass `entity` for those, and `facet` to file under a sub-page like pages/projects/chapterhouse/feature-ideas.md. " +
+                "A `decision` is always recorded against an entity: pass both `about` (which entity category) and `entity`; " +
+                "it lands at pages/<about>/<entity>/decisions.md. " +
                 "For richer knowledge pages, use wiki_update instead.",
             parameters: z.object({
-                category: z.enum(["preference", "fact", "project", "person", "routine", "decision"])
-                    .describe("Category: preference (likes/dislikes/settings), fact (general knowledge), project (codebase/repo info), person (people info), routine (schedules/habits), decision (choices made)"),
+                category: z.enum(["preference", "fact", "project", "person", "routine", "decision", "org", "tool", "topic", "area"])
+                    .describe("Category. Entity categories (need `entity`): project (codebase/repo), person (people), org (companies/teams), tool (software/technologies), topic (knowledge areas), area (areas of responsibility). decision (a choice made — needs `about` + `entity`). Flat categories: preference (likes/dislikes/settings), fact (general knowledge), routine (schedules/habits)."),
                 content: z.string().describe("The thing to remember — a concise, self-contained statement"),
-                entity: z.string().optional().describe("The specific entity this is about (e.g. 'team', 'chapterhouse', 'vercel'). Routes to a dedicated entity page."),
+                entity: z.string().optional().describe("Required for entity categories and for decisions: the specific topic this is about (e.g. 'chapterhouse', 'vercel', 'Brian'). Routes to pages/<category>/<topic-slug>/…"),
+                about: z.enum(["project", "person", "org", "tool", "topic", "area"]).optional()
+                    .describe("Required only when category='decision': which entity category the decision concerns. The decision is filed at pages/<about>/<entity>/decisions.md."),
+                facet: z.string().optional().describe("Optional sub-page within the topic directory (e.g. 'feature-ideas', 'architecture'). Only meaningful with an entity category + `entity`. Defaults to the topic's index page. (For decisions use `about` instead.)"),
                 related: z.array(z.string()).optional().describe("Wiki page paths this connects to, for cross-referencing"),
             }),
             handler: async (args) => {
                 return withWikiWrite(async () => {
                     ensureWikiStructure();
                     const now = new Date().toISOString().slice(0, 10);
-                    // Entity routing: code-authoritative slugification and page lookup
+                    const titleCase = (s) => s.split(/[-_\s]+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+                    // Routing: code-authoritative slugification and page lookup.
                     let pagePath;
                     let title;
-                    if (args.entity) {
-                        const slug = args.entity.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-                        const categoryDir = getCategoryDir(args.category);
-                        pagePath = `pages/${categoryDir}/${slug}.md`;
-                        // Check for existing page with fuzzy match before creating new
-                        const existingPages = searchIndex(args.entity, 5);
-                        const existingMatch = existingPages.find((p) => {
-                            const pSlug = p.path.split("/").pop()?.replace(".md", "") || "";
-                            return pSlug === slug || p.title.toLowerCase() === args.entity.toLowerCase();
-                        });
-                        if (existingMatch) {
-                            pagePath = existingMatch.path;
-                            title = existingMatch.title;
+                    let routedCategoryDir; // the directory under pages/ this ends up in
+                    if (args.category === "decision") {
+                        if (!args.about || !args.entity) {
+                            return `A decision needs both 'about' (the entity category it concerns — one of: ${entityCategories().join(", ")}) and 'entity' (the specific one, e.g. "chapterhouse"). It will be filed at pages/<about>/<entity>/decisions.md.`;
                         }
-                        else {
-                            title = args.entity.split(/[-_\s]+/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+                        routedCategoryDir = getCategoryDir(args.about);
+                        if (!entityCategories().includes(routedCategoryDir)) {
+                            return `'${args.about}' isn't a known entity category. Use one of: ${entityCategories().join(", ")}.`;
                         }
+                        pagePath = topicPagePath(args.about, args.entity, "decisions");
+                        const existingMatch = searchIndex(args.entity, 5).find((p) => p.path === pagePath);
+                        title = existingMatch ? existingMatch.title : `${titleCase(args.entity)} — Decisions`;
                     }
                     else {
-                        const categoryMap = {
-                            preference: "pages/preferences.md",
-                            fact: "pages/facts.md",
-                            project: "pages/projects.md",
-                            person: "pages/people.md",
-                            routine: "pages/routines.md",
-                            decision: "pages/decisions.md",
-                        };
-                        pagePath = categoryMap[args.category] || `pages/${args.category}.md`;
-                        title = args.category.charAt(0).toUpperCase() + args.category.slice(1);
+                        routedCategoryDir = getCategoryDir(args.category);
+                        const isFlat = FLAT_CATEGORIES.includes(routedCategoryDir);
+                        if (!isFlat) {
+                            if (!args.entity) {
+                                return `The '${args.category}' category needs an 'entity' (the specific ${args.category} this is about) so it can be filed under pages/${routedCategoryDir}/<topic>/. Re-call remember with an entity, e.g. entity: "chapterhouse".`;
+                            }
+                            const facet = args.facet ? slugify(args.facet) : "index";
+                            pagePath = topicPagePath(args.category, args.entity, facet);
+                            // Reuse an existing page if the index already has one at (or matching) this path.
+                            const existingPages = searchIndex(args.entity, 5);
+                            const existingMatch = existingPages.find((p) => p.path === pagePath ||
+                                (facet === "index" && p.title.toLowerCase() === args.entity.toLowerCase() && p.path.startsWith(`pages/${routedCategoryDir}/`)));
+                            if (existingMatch) {
+                                pagePath = existingMatch.path;
+                                title = existingMatch.title;
+                            }
+                            else {
+                                const topicTitle = titleCase(args.entity);
+                                title = facet === "index" ? topicTitle : `${topicTitle} — ${titleCase(facet)}`;
+                            }
+                        }
+                        else {
+                            pagePath = `pages/${routedCategoryDir}.md`;
+                            title = titleCase(routedCategoryDir);
+                        }
                     }
                     // Defense-in-depth: pagePath is constructed from controlled parts but
-                    // assertPagePath will catch any drift (e.g. an entity slug producing "..").
+                    // assertPagePath also enforces the topic-structure rules.
                     assertPagePath(pagePath);
                     const existing = readPage(pagePath);
                     if (existing) {
@@ -829,7 +761,7 @@ export function createTools(deps) {
                 "Use when you need to look up something the user told you, or when asked 'do you remember...?'",
             parameters: z.object({
                 keyword: z.string().optional().describe("Search term to match against wiki pages"),
-                category: z.enum(["preference", "fact", "project", "person", "routine", "decision"]).optional()
+                category: z.enum(["preference", "fact", "project", "person", "routine", "decision", "org", "tool", "topic", "area"]).optional()
                     .describe("Optional: filter by category"),
             }),
             handler: async (args) => {
@@ -992,9 +924,12 @@ export function createTools(deps) {
         }),
         defineTool("wiki_read", {
             description: "Read a specific wiki page by path. Use after wiki_search to read full page content. " +
-                "Paths are relative to the wiki root (e.g. 'pages/preferences.md', 'index.md').",
+                "Paths are relative to the wiki root. Layout: entity categories (projects, people, orgs, tools, " +
+                "topics, areas) live at 'pages/<category>/<topic>/index.md' (the topic overview) plus optional " +
+                "'pages/<category>/<topic>/<facet>.md' sub-pages; flat categories at 'pages/<category>.md' " +
+                "(preferences, facts, routines, decisions); daily summaries at 'pages/conversations/YYYY-MM-DD.md'.",
             parameters: z.object({
-                path: z.string().describe("Path to the wiki page (e.g. 'pages/people/brian.md', 'index.md')"),
+                path: z.string().describe("Path to the wiki page (e.g. 'pages/people/brian/index.md', 'pages/projects/chapterhouse/decisions.md', 'index.md')"),
             }),
             handler: async (args) => {
                 ensureWikiStructure();
@@ -1008,9 +943,14 @@ export function createTools(deps) {
             description: "Create or update a wiki page. You provide the full page content (markdown with optional " +
                 "YAML frontmatter). The page will be written to disk and the index updated. Use this for " +
                 "rich knowledge pages, entity pages, synthesis documents — anything more structured than " +
-                "a quick 'remember' call. After creating/updating a page, the index is automatically updated.",
+                "a quick 'remember' call. After creating/updating a page, the index is automatically updated. " +
+                "PATH RULES: entity-category pages MUST be 'pages/<category>/<topic-slug>/<page>.md' where " +
+                "category is one of projects, people, orgs, tools, topics, areas, '<page>' is 'index' for the " +
+                "topic overview or a facet name (e.g. 'decisions', 'feature-ideas') — exactly one topic level, " +
+                "lowercase slugs only. Flat-category pages MUST be 'pages/<category>.md' (preferences, facts, " +
+                "routines, decisions). Bad paths are rejected with a suggested correction.",
             parameters: z.object({
-                path: z.string().describe("Page path relative to wiki root (e.g. 'pages/projects/max.md')"),
+                path: z.string().describe("Page path relative to wiki root (e.g. 'pages/projects/chapterhouse/index.md', 'pages/projects/chapterhouse/decisions.md', 'pages/people/brian/index.md')"),
                 title: z.string().describe("Page title for the index"),
                 summary: z.string().describe("One-line summary for the index"),
                 section: z.string().optional().describe("Index section (default: 'Knowledge')"),