chapterhouse 0.7.0 → 0.8.0

package/dist/copilot/tools.js

@@ -10,15 +10,15 @@ import { ModeContext } from "../mode-context.js";
 import { agentEventBus } from "./agent-event-bus.js";
 import { getCurrentSourceChannel, getCurrentActivityCallback, getCurrentActiveProjectRules, getCurrentAuthenticatedUser, getLastAuthenticatedUser, getCurrentAuthorizationHeader, getCurrentSessionKey, sendToAgentSession, invalidateOrchestratorSession, maybeScheduleScopeChangeCheckpoint, resetCheckpointSessionState, switchSessionModel, } from "./orchestrator.js";
 import { getRouterConfig, updateRouterConfig } from "./router.js";
-import { ensureWikiStructure, readPage, writePage, deletePage, writeRawSource, assertPagePath } from "../wiki/fs.js";
-import { searchIndex, addToIndex, removeFromIndex, buildIndexEntryForPage } from "../wiki/index-manager.js";
-import { validateWikiFrontmatter } from "../wiki/frontmatter.js";
-import { fixWiki } from "../wiki/fix.js";
-import { lintWiki, renderWikiLintReport } from "../wiki/lint.js";
-import { rebuildIndexFromPages } from "../wiki/index-manager.js";
+import { ensureWikiStructure, writePage, assertPagePath } from "../wiki/fs.js";
+import { searchIndex, addToIndex, buildIndexEntryForPage, } from "../wiki/index-manager.js";
+import { traverse as wikiTraverse } from "../wiki/links.js";
+import { validateWikiFrontmatter, validateAndBackfillFrontmatter } from "../wiki/frontmatter.js";
+import { appendTimeline } from "../wiki/timeline.js";
+import { ingestSource, detectSourceType } from "../wiki/ingest.js";
 import { appendLog } from "../wiki/log-manager.js";
 import { loadTaxonomy } from "../wiki/taxonomy.js";
-import { getCategoryDir, topicPagePath, slugify, entityCategories, FLAT_CATEGORIES } from "../wiki/topic-structure.js";
+import { topicPagePath } from "../wiki/topic-structure.js";
 import { withWikiWrite } from "../wiki/lock.js";
 import { readWikiPage, teamWikiSync } from "../wiki/team-sync.js";
 import { getAgentRegistry, getAgent, createEphemeralAgentSession, getAgentSessionStatus, getTask, registerTask, completeTask, failTask, createTaskId, createAgentFile, removeAgentFile, loadAgents, } from "./agents.js";
@@ -30,7 +30,7 @@ import { TeamsNotifier } from "../integrations/teams-notify.js";
 import { TeamPushClient } from "../integrations/team-push.js";
 import { OKRMapper, parseOKRPageContent } from "./okr-mapper.js";
 import { childLogger } from "../util/logger.js";
-import { getActiveScope as getMemoryActiveScope, createScope as createMemoryScope, getScope as getMemoryScope, inferScopeFromText, completeActionItem, demoteToCold, demoteToWarm, dropActionItem, queueMemoryProposal, recall as recallMemory, listActionItems, recordDecision, recordActionItem, recordObservation, runHousekeeping, setActiveScope as setMemoryActiveScope, snoozeActionItem, promoteToHot, upsertEntity, } from "../memory/index.js";
+import { getActiveScope as getMemoryActiveScope, createScope as createMemoryScope, getScope as getMemoryScope, inferScopeFromText, completeActionItem, demoteToCold, demoteToWarm, dropActionItem, queueMemoryProposal, recall as recallMemory, listActionItems, recordDecision, recordActionItem, recordObservation, runHousekeeping, reflectOnScope, reflectAllScopes, setActiveScope as setMemoryActiveScope, snoozeActionItem, promoteToHot, upsertEntity, hookDispatcher, } from "../memory/index.js";
 const log = childLogger("tools");
 const modeContext = new ModeContext(config);
 /** Escape a string for safe inclusion as a single-line YAML scalar value. */
@@ -944,6 +944,17 @@ export function createTools(deps) {
                             decided_at: args.decided_at ?? new Date().toISOString().slice(0, 10),
                             tier: args.tier ?? "warm",
                         });
+                        if (entity) {
+                            appendTimeline(topicPagePath(entity.kind, entity.name), `${decision.title}\n\n${decision.rationale}`);
+                        }
+                        hookDispatcher.dispatch("memory:decision", {
+                            id: decision.id,
+                            scope_id: scopeId,
+                            title: decision.title,
+                            rationale: decision.rationale,
+                        }).catch((err) => {
+                            log.error({ err }, "memory.hooks.decision.dispatch_error");
+                        });
                         return {
                             ok: true,
                             id: decision.id,
@@ -1041,6 +1052,13 @@ export function createTools(deps) {
                         description: parsed.data.description ?? "",
                         keywords: [parsed.data.slug],
                     });
+                    hookDispatcher.dispatch("scope:created", {
+                        slug: scope.slug,
+                        title: scope.title,
+                        description: scope.description,
+                    }).catch((err) => {
+                        log.error({ err }, "memory.hooks.scope_created.dispatch_error");
+                    });
                     return {
                         ok: true,
                         scope: {
@@ -1289,6 +1307,51 @@ export function createTools(deps) {
                 }
             },
         }),
+        defineTool("memory_reflect", {
+            description: "Synthesize durable scoped memory patterns from repeated observations. Orchestrator-only reflect tool.",
+            parameters: z.object({
+                scope: z.string().optional(),
+            }),
+            handler: async (args) => {
+                const denied = requireOrchestratorMemoryWrite();
+                if (denied)
+                    return denied;
+                try {
+                    if (args.scope) {
+                        const requestedScope = getMemoryScope(args.scope);
+                        if (!requestedScope) {
+                            return `Unknown memory scope '${args.scope}'.`;
+                        }
+                        const result = await reflectOnScope(args.scope, getDb());
+                        return {
+                            ok: true,
+                            scope: args.scope,
+                            patterns_created: result.patternsCreated,
+                            patterns_updated: result.patternsUpdated,
+                            contradictions_found: result.contradictionsFound,
+                        };
+                    }
+                    const results = await reflectAllScopes(getDb());
+                    const totals = Object.values(results).reduce((acc, result) => ({
+                        patterns_created: acc.patterns_created + result.patternsCreated,
+                        patterns_updated: acc.patterns_updated + result.patternsUpdated,
+                        contradictions_found: acc.contradictions_found + result.contradictionsFound,
+                    }), {
+                        patterns_created: 0,
+                        patterns_updated: 0,
+                        contradictions_found: 0,
+                    });
+                    return {
+                        ok: true,
+                        scope: "all",
+                        ...totals,
+                    };
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
         defineTool("memory_promote", {
             description: "Promote a memory row to the hot tier. Orchestrator-only manual override.",
             parameters: z.object({
@@ -1372,273 +1435,21 @@ export function createTools(deps) {
                 }
             },
         }),
-        // ----- Wiki-backed memory facades (preserve existing remember/recall/forget UX) -----
+        // ----- Removed legacy wiki facades kept as compatibility stubs -----
         defineTool("remember", {
-            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", "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("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);
-                    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;
-                    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.`;
-                        }
-                        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 {
-                        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 also enforces the topic-structure rules.
-                    assertPagePath(pagePath);
-                    const existing = readPage(pagePath);
-                    if (existing) {
-                        const updated = existing.replace(/^(---[\s\S]*?updated:\s*)[\d-]+/m, `$1${now}`);
-                        writePage(pagePath, updated.trimEnd() + `\n- ${args.content} _(${now})_\n`);
-                    }
-                    else {
-                        const tags = [args.category];
-                        if (args.entity)
-                            tags.push(args.entity.toLowerCase());
-                        const safeTags = tags.map(yamlListItem).join(", ");
-                        const safeRelated = (args.related || []).map(yamlListItem).join(", ");
-                        const page = [
-                            "---",
-                            `title: ${yamlEscape(title)}`,
-                            `tags: [${safeTags}]`,
-                            `created: ${now}`,
-                            `updated: ${now}`,
-                            `related: [${safeRelated}]`,
-                            "---",
-                            "",
-                            `# ${title}`,
-                            "",
-                            `- ${args.content} _(${now})_`,
-                            "",
-                        ].join("\n");
-                        writePage(pagePath, page);
-                    }
-                    // Rebuild the index entry from the page on disk so summary/tags/updated
-                    // stay in sync rather than being clobbered by the latest bullet.
-                    const rebuilt = buildIndexEntryForPage(pagePath, {
-                        title,
-                        section: "Knowledge",
-                        tags: [args.category, ...(args.entity ? [args.entity.toLowerCase()] : [])],
-                        updated: now,
-                        // Keep existing summary if present; otherwise use the new content.
-                        summary: indexSafe(args.content).slice(0, 120),
-                    });
-                    if (rebuilt)
-                        addToIndex(rebuilt);
-                    appendLog("update", `remember (${args.category}${args.entity ? `, ${args.entity}` : ""}): ${indexSafe(args.content).slice(0, 80)}`);
-                    const relatedHint = args.related?.length
-                        ? ` Related pages that may need updating: ${args.related.join(", ")}`
-                        : "";
-                    return `Remembered in ${pagePath}: "${args.content}"${relatedHint}`;
-                });
-            },
+            description: "REMOVED: Use wiki_update or memory_remember instead.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. Use wiki_update to write to wiki pages, or memory_remember for agent memory.",
         }),
         defineTool("recall", {
-            description: "Search the wiki for stored knowledge. Returns matching page summaries from the index. " +
-                "Use wiki_read to drill into specific pages for deeper context. " +
-                "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", "org", "tool", "topic", "area"]).optional()
-                    .describe("Optional: filter by category"),
-            }),
-            handler: async (args) => {
-                ensureWikiStructure();
-                const query = [args.keyword, args.category].filter(Boolean).join(" ");
-                const matches = searchIndex(query || "", 10);
-                if (matches.length === 0) {
-                    return "No matching memories found in the wiki. The wiki is the single source of truth — if it's not here, I don't know it yet.";
-                }
-                const sections = [];
-                for (const match of matches) {
-                    const content = readPage(match.path);
-                    if (!content)
-                        continue;
-                    // Extract updated date from frontmatter
-                    const updatedMatch = content.match(/^updated:\s*(.+)$/m);
-                    const updated = updatedMatch ? ` (updated: ${updatedMatch[1].trim()})` : "";
-                    const body = content.replace(/^---[\s\S]*?---\s*/, "").trim();
-                    const trimmed = body.length > 800 ? body.slice(0, 800) + "…" : body;
-                    sections.push(`**${match.title}** (${match.path})${updated}:\n${trimmed}`);
-                }
-                return sections.length > 0
-                    ? `Found ${matches.length} wiki page(s):\n\n${sections.join("\n\n")}`
-                    : "No matching content found.";
-            },
+            description: "REMOVED: Use wiki_search or memory_recall instead.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. Use wiki_search to search wiki pages, or memory_recall for agent memory.",
         }),
         defineTool("forget", {
-            description: "Remove content from the wiki. Three modes: (1) page_path + content removes matching bullet lines, " +
-                "(2) page_path + revision replaces a section with corrected content, " +
-                "(3) page_path alone deletes the entire page.",
-            parameters: z.object({
-                page_path: z.string().describe("Wiki page path to modify or delete"),
-                content: z.string().optional().describe("Specific text to match and remove (line-removal mode)"),
-                revision: z.string().optional().describe("Replacement content for a section (section-rewrite mode)"),
-                section_heading: z.string().optional().describe("The heading of the section to replace (used with revision)"),
-            }),
-            handler: async (args) => {
-                return withWikiWrite(async () => {
-                    // Defense: only allow modifying real pages, never index.md / log.md / sources/.
-                    assertPagePath(args.page_path);
-                    // Delete entire page
-                    if (!args.content && !args.revision) {
-                        const page = readPage(args.page_path);
-                        if (!page)
-                            return `Page ${args.page_path} not found.`;
-                        deletePage(args.page_path);
-                        removeFromIndex(args.page_path);
-                        appendLog("delete", `forget: deleted page ${args.page_path}`);
-                        return `Deleted page ${args.page_path} and removed from index.`;
-                    }
-                    // Line-removal mode: remove bullet lines that match content.
-                    // Precision rules: prefer a single exact match (whole bullet body equals
-                    // the search text). If no exact match, fall back to substring match —
-                    // but if the substring would match >1 bullets, refuse and report so the
-                    // caller can disambiguate. This prevents "forget CST" from nuking every
-                    // bullet that happens to mention CST.
-                    if (args.content) {
-                        const page = readPage(args.page_path);
-                        if (!page)
-                            return `Page ${args.page_path} not found.`;
-                        const search = args.content.trim();
-                        const lines = page.split("\n");
-                        const isBullet = (l) => /^\s*[-*]\s+/.test(l);
-                        const bulletText = (l) => l.replace(/^\s*[-*]\s+/, "").replace(/\s*_\(\d{4}-\d{2}-\d{2}\)_\s*$/, "").trim();
-                        // Pass 1: exact-bullet match (case-insensitive).
-                        const exactMatches = [];
-                        for (let i = 0; i < lines.length; i++) {
-                            if (isBullet(lines[i]) && bulletText(lines[i]).toLowerCase() === search.toLowerCase()) {
-                                exactMatches.push(i);
-                            }
-                        }
-                        let toRemove;
-                        if (exactMatches.length > 0) {
-                            toRemove = new Set(exactMatches);
-                        }
-                        else {
-                            // Pass 2: substring match — but require precision.
-                            const subMatches = [];
-                            for (let i = 0; i < lines.length; i++) {
-                                if (isBullet(lines[i]) && lines[i].toLowerCase().includes(search.toLowerCase())) {
-                                    subMatches.push(i);
-                                }
-                            }
-                            if (subMatches.length === 0) {
-                                return `No matching bullet points found in ${args.page_path}.`;
-                            }
-                            if (subMatches.length > 1) {
-                                const preview = subMatches.slice(0, 5)
-                                    .map((i) => `  • ${lines[i].trim()}`).join("\n");
-                                return `Refused: substring "${search}" matches ${subMatches.length} bullets in ${args.page_path}. Be more specific (paste the full bullet text), or call forget repeatedly with the exact bullet to remove. Matches:\n${preview}`;
-                            }
-                            toRemove = new Set(subMatches);
-                        }
-                        const updatedLines = lines.filter((_, i) => !toRemove.has(i));
-                        // Bump frontmatter `updated:` so the index reflects the change.
-                        const today = new Date().toISOString().slice(0, 10);
-                        let updated = updatedLines.join("\n").replace(/^(---[\s\S]*?updated:\s*)[\d-]+/m, `$1${today}`);
-                        writePage(args.page_path, updated);
-                        // Refresh the corresponding index entry from the page so the index
-                        // doesn't keep advertising forgotten content.
-                        const rebuilt = buildIndexEntryForPage(args.page_path, { updated: today });
-                        if (rebuilt)
-                            addToIndex(rebuilt);
-                        appendLog("update", `forget: removed ${toRemove.size} line(s) matching "${indexSafe(search).slice(0, 60)}" from ${args.page_path}`);
-                        return `Removed ${toRemove.size} line(s) from ${args.page_path}.`;
-                    }
-                    // Section-rewrite mode: replace a section with revised content
-                    if (args.revision) {
-                        const page = readPage(args.page_path);
-                        if (!page)
-                            return `Page ${args.page_path} not found.`;
-                        if (args.section_heading) {
-                            const headingPattern = new RegExp(`(^#{1,6}\\s*${args.section_heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$)`, "m");
-                            const headingMatch = page.match(headingPattern);
-                            if (!headingMatch || headingMatch.index === undefined) {
-                                return `Section "${args.section_heading}" not found in ${args.page_path}.`;
-                            }
-                            const sectionStart = headingMatch.index;
-                            const level = (headingMatch[1].match(/^#+/) || ["#"])[0].length;
-                            const nextHeading = page.slice(sectionStart + headingMatch[0].length)
-                                .search(new RegExp(`^#{1,${level}}\\s`, "m"));
-                            const sectionEnd = nextHeading === -1
-                                ? page.length
-                                : sectionStart + headingMatch[0].length + nextHeading;
-                            const updated = page.slice(0, sectionStart) + args.revision + "\n" + page.slice(sectionEnd);
-                            writePage(args.page_path, updated);
-                        }
-                        else {
-                            // Replace entire body (keep frontmatter)
-                            const fmMatch = page.match(/^---[\s\S]*?---\s*/);
-                            const frontmatter = fmMatch ? fmMatch[0] : "";
-                            writePage(args.page_path, frontmatter + args.revision + "\n");
-                        }
-                        const today = new Date().toISOString().slice(0, 10);
-                        const rebuilt = buildIndexEntryForPage(args.page_path, { updated: today });
-                        if (rebuilt)
-                            addToIndex(rebuilt);
-                        appendLog("update", `forget: revised section in ${args.page_path}`);
-                        return `Revised content in ${args.page_path}.`;
-                    }
-                    return "Nothing to do — provide content (line-removal) or revision (section-rewrite).";
-                });
-            },
+            description: "REMOVED: Use wiki_update instead.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. Use wiki_update to modify wiki pages.",
         }),
         // ----- New wiki tools -----
         defineTool("wiki_search", {
@@ -1686,10 +1497,15 @@ export function createTools(deps) {
             parameters: wikiUpdateArgsSchema,
             handler: async (args) => {
                 try {
-                    const parsedArgs = wikiUpdateArgsSchema.parse(args);
+                    let parsedArgs = wikiUpdateArgsSchema.parse(args);
                     return await withWikiWrite(async () => {
                         ensureWikiStructure();
                         assertPagePath(parsedArgs.path);
+                        // Backfill missing frontmatter fields before validation
+                        const backfilled = validateAndBackfillFrontmatter(parsedArgs.path, parsedArgs.content);
+                        if (backfilled.changed) {
+                            parsedArgs = { ...parsedArgs, content: backfilled.content };
+                        }
                         const validation = validateWikiFrontmatter(parsedArgs.content, {
                             allowedTags: loadTaxonomy(),
                         });
@@ -1728,127 +1544,119 @@ export function createTools(deps) {
             },
         }),
         defineTool("wiki_ingest", {
-            description: "Ingest a source into the wiki. Saves the raw content as an immutable source document, " +
-                "then returns it so you can create wiki pages from it. Supports URLs (fetches the page) " +
-                "or raw text passed directly. For local files, read the file yourself and pass content as text.",
+            description: "REMOVED: Use wiki_ingest_source instead.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. Use wiki_ingest_source instead.",
+        }),
+        defineTool("wiki_lint", {
+            description: "REMOVED: Wiki health checks are no longer needed.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. Wiki health checks are no longer needed with SQLite-backed storage.",
+        }),
+        defineTool("wiki_rebuild_index", {
+            description: "REMOVED: The wiki index is maintained automatically.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. The wiki index is now maintained automatically via SQLite FTS5.",
+        }),
+        defineTool("wiki_traverse", {
+            description: "Walk the wiki entity graph from a starting page. Returns pages connected by typed links. " +
+                "Use to discover related knowledge, trace dependencies, find who works on a project, etc. " +
+                "Depth 1 returns direct neighbors; depth 2-3 expands further (max 3). " +
+                "Optionally filter by link_type: references, implements, supersedes, member_of, works_on, decided_by, depends_on, attended, follow_up.",
             parameters: z.object({
-                type: z.enum(["url", "text"]).describe("Source type: 'url' to fetch a web page, 'text' for raw content"),
-                source: z.string().describe("URL or raw text content"),
-                name: z.string().optional().describe("Name for the source (auto-generated if omitted)"),
+                page: z.string().describe("Wiki page path to traverse from (e.g. 'pages/topics/rust/index.md')"),
+                link_type: z.string().optional().describe("Filter by link type (e.g. 'references', 'implements')"),
+                depth: z.number().int().min(1).max(3).optional().describe("Traversal depth (1–3, default 1)"),
             }),
             handler: async (args) => {
                 ensureWikiStructure();
-                let content;
-                let sourceName;
-                if (args.type === "url") {
-                    // Validate URL scheme
-                    let parsedUrl;
-                    try {
-                        parsedUrl = new URL(args.source);
-                    }
-                    catch {
-                        return "Invalid URL format.";
-                    }
-                    if (!["http:", "https:"].includes(parsedUrl.protocol)) {
-                        return "Only http and https URLs are supported.";
-                    }
-                    // Block private/internal addresses
-                    const host = parsedUrl.hostname.toLowerCase();
-                    if (host === "localhost" || host === "127.0.0.1" || host === "::1" ||
-                        host.startsWith("10.") || host.startsWith("192.168.") ||
-                        host.startsWith("169.254.") || host === "metadata.google.internal") {
-                        return "Cannot fetch internal/private URLs.";
-                    }
-                    try {
-                        const res = await fetch(args.source);
-                        if (!res.ok) {
-                            return `Fetch failed: ${res.status} ${res.statusText}`;
-                        }
-                        content = await res.text();
-                        // Strip HTML tags for a rough markdown conversion
-                        content = content.replace(/<script[\s\S]*?<\/script>/gi, "")
-                            .replace(/<style[\s\S]*?<\/style>/gi, "")
-                            .replace(/<[^>]+>/g, " ")
-                            .replace(/\s{2,}/g, " ")
-                            .trim();
-                    }
-                    catch (err) {
-                        return `Failed to fetch URL: ${err instanceof Error ? err.message : err}`;
-                    }
-                    sourceName = args.name || parsedUrl.hostname + "-" + Date.now();
-                }
-                else {
-                    content = args.source;
-                    sourceName = args.name || "text-" + Date.now();
-                }
-                const fileName = `${new Date().toISOString().slice(0, 10)}-${sourceName}.md`;
-                await withWikiWrite(async () => {
-                    writeRawSource(fileName, content);
-                    appendLog("ingest", `Ingested ${args.type}: ${indexSafe(sourceName)} (${content.length} chars)`);
-                });
-                // Return the content so the LLM can create wiki pages from it
-                const preview = content.length > 3000 ? content.slice(0, 3000) + "\n\n…(truncated)" : content;
-                return `Source saved as sources/${fileName} (${content.length} chars).\n\n` +
-                    "Now create wiki pages from this content using wiki_update. " +
-                    "Update existing pages and the index as needed.\n\n" +
-                    `--- Source content ---\n${preview}`;
+                const results = wikiTraverse(args.page, args.link_type, args.depth ?? 1);
+                if (results.length === 0)
+                    return `No linked pages found for: ${args.page}`;
+                const lines = results.map((r) => `• [depth ${r.depth}] ${r.direction === "outbound" ? "→" : "←"} ${r.page} (${r.link_type})`);
+                return `Found ${results.length} linked page(s):\n${lines.join("\n")}`;
             },
         }),
-        defineTool("wiki_lint", {
-            description: "Health-check the wiki. Looks for: orphan pages (not in index), index entries pointing " +
-                "to missing pages, and pages with no cross-references. Returns a report.",
-            parameters: z.object({}),
-            handler: async () => {
-                ensureWikiStructure();
-                const report = lintWiki();
-                const orphanCount = report.issues.filter((issue) => issue.rule === "orphan-page").length;
-                const missingCount = report.issues.filter((issue) => issue.rule === "missing-page").length;
-                appendLog("lint", `${orphanCount} orphans, ${missingCount} missing`);
-                return renderWikiLintReport(report);
-            },
+        defineTool("wiki_fix", {
+            description: "REMOVED: Use wiki_update instead.",
+            parameters: z.object({}).passthrough(),
+            handler: async () => "This tool has been removed. Use wiki_update to correct wiki pages.",
         }),
-        defineTool("wiki_rebuild_index", {
-            description: "Rebuild the wiki index.md from the pages on disk. Use when the index is " +
-                "corrupted, out of sync with pages, or after manual edits to the wiki. " +
-                "Safe to run anytime — it preserves section assignments where possible.",
-            parameters: z.object({}),
-            handler: async () => {
-                return withWikiWrite(async () => {
-                    const { rebuildIndexFromPages } = await import("../wiki/index-manager.js");
-                    const entries = rebuildIndexFromPages();
-                    appendLog("rebuild-index", `wiki_rebuild_index: rebuilt ${entries.length} entries from pages on disk`);
-                    return `Rebuilt index with ${entries.length} entries.`;
-                });
+        defineTool("wiki_append_timeline", {
+            description: "Append an entry to the '## Timeline' section of a wiki page. " +
+                "Creates the section (and the page itself) if absent. " +
+                "Timeline is append-only — existing entries are never modified. " +
+                "Use for recording events, source ingestion, and interaction history.",
+            parameters: z.object({
+                page: z.string().describe("Relative path from wiki root (e.g. 'pages/people/alice/index.md')"),
+                entry: z.string().describe("Markdown text for the timeline entry"),
+                source_id: z.string().optional().describe("Optional reference to a wiki_sources id"),
+            }),
+            handler: async (args) => {
+                ensureWikiStructure();
+                try {
+                    const entry = args.source_id
+                        ? `${args.entry}\n\n_Source: ${args.source_id}_`
+                        : args.entry;
+                    return await withWikiWrite(async () => {
+                        appendTimeline(args.page, entry);
+                        return `Timeline entry appended to ${args.page}`;
+                    });
+                }
+                catch (err) {
+                    log.error({ err: err instanceof Error ? err.message : err, page: args.page }, "wiki_append_timeline failed");
+                    return { error: err instanceof Error ? err.message : "wiki_append_timeline failed" };
+                }
             },
         }),
-        defineTool("wiki_fix", {
-            description: "Auto-repair common wiki inconsistencies. Defaults to dry-run preview mode and returns a per-file report " +
-                "plus unified diff. Supports frontmatter backfill, taxonomy tag normalization, and autostub marking.",
+        defineTool("wiki_ingest_source", {
+            description: "Ingest an external source (URL, PDF, Git repo, or raw text) into the PKB. " +
+                "Fetches and parses the content, extracts entities with LLM, creates/updates wiki pages, " +
+                "and writes timeline entries. Idempotent: re-ingesting the same source returns the existing result. " +
+                "Type is auto-detected if omitted.",
             parameters: z.object({
-                dry_run: z.boolean().optional().describe("Preview only when true (default). Set false to apply fixes."),
-                fixes: z.array(z.enum(["frontmatter-backfill", "tag-normalize", "autostub-mark"])).optional()
-                    .describe("Optional subset of fixes to apply. Defaults to all fixes."),
-                path_glob: z.string().optional().describe("Optional glob to limit which wiki page paths are considered."),
+                source: z.string().describe("URL, file path, git repo URL, or raw text content to ingest"),
+                type: z.enum(["url", "pdf", "repo", "text"]).optional().describe("Source type. Auto-detected if omitted: http(s) URL → url/repo, .pdf path → pdf, else text"),
+                topic: z.string().optional().describe("Optional hint for entity extraction focus"),
+                session_id: z.string().optional().describe("Optional research session id to persist in wiki_sources"),
+                session_name: z.string().optional().describe("Optional human-readable research session name"),
             }),
             handler: async (args) => {
                 ensureWikiStructure();
-                const dryRun = args.dry_run ?? true;
-                const runFixer = () => {
-                    const report = fixWiki({
-                        dryRun,
-                        fixes: args.fixes,
-                        pathGlob: args.path_glob,
-                        logAction: dryRun ? undefined : (type, path) => appendLog(type, path),
+                try {
+                    const sourceType = args.type ?? detectSourceType(args.source);
+                    const result = await ingestSource(args.source, sourceType, args.topic, {
+                        sessionId: args.session_id,
+                        sessionName: args.session_name,
                     });
-                    if (!dryRun && report.changedFiles > 0) {
-                        rebuildIndexFromPages();
+                    if (result.already_existed) {
+                        return (`Source already ingested (id: ${result.source_id}).\n` +
+                            `Pages previously updated: ${result.pages_updated.length > 0 ? result.pages_updated.join(", ") : "none"}`);
                     }
-                    return report;
-                };
-                if (dryRun) {
-                    return runFixer();
+                    const lines = [
+                        `✅ Ingested source (id: ${result.source_id})`,
+                    ];
+                    if (result.pages_created.length > 0) {
+                        lines.push(`📄 Pages created (${result.pages_created.length}): ${result.pages_created.join(", ")}`);
+                    }
+                    if (result.pages_updated.length > 0) {
+                        lines.push(`✏️ Pages updated (${result.pages_updated.length}): ${result.pages_updated.join(", ")}`);
+                    }
+                    if (result.entities.length > 0) {
+                        lines.push(`🔍 Entities extracted (${result.entities.length}):`);
+                        for (const e of result.entities) {
+                            lines.push(`  • ${e.name} (${e.type}) → ${e.path}`);
+                        }
+                    }
+                    else {
+                        lines.push("🔍 No entities extracted.");
+                    }
+                    return lines.join("\n");
+                }
+                catch (err) {
+                    log.error({ err: err instanceof Error ? err.message : err }, "wiki_ingest_source failed");
+                    return { error: err instanceof Error ? err.message : "Ingestion failed" };
                 }
-                return withWikiWrite(runFixer);
             },
         }),
         defineTool("restart_chapterhouse", {