pi-para 0.5.2

package/dist/processor.js

@@ -0,0 +1,361 @@
+/**
+ * Session processor — uses Agent with session exploration tools
+ * to extract knowledge and write wiki pages.
+ */
+import { Agent } from "@mariozechner/pi-agent-core";
+import { readPage, writePage, listPages, writeIndex, appendLog, gitCommit, PARA_CATEGORIES, } from "./wiki.js";
+import { validateFrontmatter } from "./frontmatter.js";
+import { extractWikilinks, autoLinkSlugs, syncFrontmatterLinks } from "./link-utils.js";
+import { normalizeTags, normalizeScopes } from "./tag-registry.js";
+import { redactSecrets } from "./redact.js";
+import { reindex, searchWiki } from "./store.js";
+import { appendSessionDigest } from "./raw.js";
+import { Type } from "typebox";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { loadSession, createSessionTools } from "./session-tools.js";
+// -- Wiki tools for the Agent ------------------------------------------------
+const WikiWriteParams = Type.Object({
+    category: StringEnum(["projects", "areas", "resources", "archives"]),
+    slug: Type.String(),
+    title: Type.String(),
+    scope: Type.Array(Type.String()),
+    tags: Type.Array(Type.String()),
+    body: Type.String(),
+});
+const WikiQueryParams = Type.Object({ query: Type.String() });
+const WikiReadParams = Type.Object({ path: Type.String({ description: "category/slug" }) });
+function createWikiTools(wikiDir, store) {
+    const wikiWrite = {
+        name: "wiki_write",
+        label: "Wiki Write",
+        description: "Create or update a wiki page with PARA frontmatter.",
+        parameters: WikiWriteParams,
+        execute: async (_id, params) => {
+            const now = new Date().toISOString();
+            const slug = params.slug.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+            const existing = await readPage(wikiDir, params.category, slug);
+            // Gather all existing slugs for auto-linking
+            const allRefs = await listPages(wikiDir);
+            const allSlugs = new Set(allRefs.map(r => r.slug));
+            allSlugs.add(slug);
+            // Auto-link slug mentions in body text, redact any secrets
+            const linkedBody = redactSecrets(autoLinkSlugs(params.body, allSlugs, slug)).text;
+            if (existing) {
+                // Update existing page (exact slug match)
+                const rawScope = params.scope.length > 0 ? params.scope : existing.frontmatter.scope;
+                const newScope = normalizeScopes(rawScope);
+                const mergedTags = [...new Set([...existing.frontmatter.tags, ...params.tags])];
+                const updated = {
+                    ...existing,
+                    body: linkedBody,
+                    frontmatter: {
+                        ...existing.frontmatter,
+                        title: params.title,
+                        scope: newScope,
+                        tags: normalizeTags(mergedTags, newScope),
+                        updated: now,
+                        links: syncFrontmatterLinks(linkedBody),
+                    },
+                };
+                await writePage(wikiDir, updated);
+            }
+            else {
+                // Create new page
+                const newScope = normalizeScopes(params.scope);
+                const fm = validateFrontmatter({
+                    title: params.title,
+                    para: params.category,
+                    scope: newScope,
+                    tags: normalizeTags(params.tags, newScope),
+                    sources: [],
+                    created: now,
+                    updated: now,
+                    links: syncFrontmatterLinks(linkedBody),
+                });
+                await writePage(wikiDir, { category: params.category, slug, frontmatter: fm, body: linkedBody });
+            }
+            await reindex(store);
+            await rebuildIndex(wikiDir);
+            await gitCommit(wikiDir, `capture: ${params.category}/${slug}`);
+            return {
+                content: [{ type: "text", text: `Wrote ${params.category}/${slug}` }],
+                details: { path: `${params.category}/${slug}`, existed: !!existing },
+            };
+        },
+    };
+    const wikiQuery = {
+        name: "wiki_query",
+        label: "Wiki Query",
+        description: "Search the wiki for existing pages (for deduplication).",
+        parameters: WikiQueryParams,
+        execute: async (_id, params) => {
+            const results = await searchWiki(store, params.query, { limit: 5 });
+            if (results.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No matching wiki pages found." }],
+                    details: { count: 0 },
+                };
+            }
+            const text = results
+                .map((r) => `${r.page.path}: ${r.frontmatter.title} (score: ${r.score.toFixed(3)})`)
+                .join("\n");
+            return {
+                content: [{ type: "text", text: `Found ${results.length} pages:\n${text}` }],
+                details: { count: results.length },
+            };
+        },
+    };
+    const wikiRead = {
+        name: "wiki_read",
+        label: "Wiki Read",
+        description: "Read an existing wiki page by path (category/slug).",
+        parameters: WikiReadParams,
+        execute: async (_id, params) => {
+            const parts = params.path.split("/");
+            if (parts.length !== 2) {
+                return {
+                    content: [{ type: "text", text: `Invalid path: ${params.path}` }],
+                    details: {},
+                };
+            }
+            const [cat, slug] = parts;
+            const page = await readPage(wikiDir, cat, slug);
+            if (!page) {
+                return {
+                    content: [{ type: "text", text: `Page not found: ${params.path}` }],
+                    details: {},
+                };
+            }
+            return {
+                content: [{ type: "text", text: `# ${page.frontmatter.title}\n\n${page.body}` }],
+                details: { title: page.frontmatter.title },
+            };
+        },
+    };
+    return [wikiWrite, wikiQuery, wikiRead];
+}
+// -- Helpers -----------------------------------------------------------------
+async function rebuildIndex(wikiDir) {
+    const allPages = await listPages(wikiDir);
+    const sections = {
+        projects: [], areas: [], resources: [], archives: [],
+    };
+    for (const ref of allPages) {
+        const page = await readPage(wikiDir, ref.category, ref.slug);
+        const title = page?.frontmatter.title ?? ref.title;
+        const summary = page?.body.split("\n").find(l => l.trim() && !l.startsWith("#") && !l.startsWith("---"))?.trim() ?? "";
+        const desc = summary.length > 120 ? summary.slice(0, 117) + "..." : summary;
+        sections[ref.category].push(`- [[${ref.slug}]] \u2014 ${title}${desc ? ": " + desc : ""}`);
+    }
+    const indexLines = [
+        "# Wiki Index", "",
+        "## Projects", "", sections.projects.length > 0 ? sections.projects.join("\n") : "_No active projects._", "",
+        "## Areas", "", sections.areas.length > 0 ? sections.areas.join("\n") : "_No areas._", "",
+        "## Resources", "", sections.resources.length > 0 ? sections.resources.join("\n") : "_No resources._", "",
+        "## Archives", "", sections.archives.length > 0 ? sections.archives.join("\n") : "_No archived items._",
+    ];
+    await writeIndex(wikiDir, indexLines.join("\n"));
+}
+// -- System prompt -----------------------------------------------------------
+const CAPTURE_SYSTEM_PROMPT = `You are a knowledge capture agent. You explore coding session transcripts and extract valuable knowledge into a PARA-structured wiki.
+
+You have tools to explore the session:
+- session_stats: Get an overview of the session (message count, topics)
+- session_search: Search for keywords in the session
+- session_slice: Read a specific character range of the session
+
+And tools to write to the wiki:
+- wiki_query: Search existing wiki pages (check for duplicates first!)
+- wiki_read: Read an existing page
+- wiki_write: Create or update a wiki page
+
+PARA category rules (IMPORTANT):
+- **resources/**: Use for almost everything — architecture docs, how-tos, debugging solutions, configs, patterns, reference material. This is the default.
+- **areas/**: Only for ongoing responsibilities with no end date (e.g. server config, deployment procedures).
+- **projects/**: ONLY for actual project goals with a defined end date. Do NOT use for documentation about a project's internals. A page like "pi-para-daemon" is a resource about pi-para, not a project.
+- **archives/**: Never create pages here — pages get moved here when completed.
+
+Scope rules:
+- scope must be a project name in kebab-case (e.g. "pi-para", "qmd", "pi-mono")
+- Do NOT put topic descriptions in scope (wrong: "session exploration", right: "pi-para")
+
+Security rules:
+- NEVER include API keys, tokens, passwords, or secrets in wiki pages
+- Document WHERE the secret is stored (e.g. "API key in ~/.config/qmd/index.yml"), not the value itself
+
+Your workflow:
+1. Call session_stats to understand the session
+2. For each topic, call wiki_query FIRST to find existing pages on that topic
+3. Call session_search or session_slice to read the relevant discussion
+4. If wiki_query found a matching page, call wiki_read to get its content, then wiki_write to UPDATE it (use the same slug)
+5. Only create a NEW page if wiki_query returned no relevant results
+
+CRITICAL: ALWAYS prefer updating existing pages over creating new ones. The wiki already has many pages — search before writing. If you find a page covering the same topic (even with a different title), update it by using its exact slug.
+
+Capture ANY of these — even small facts:
+- Architecture decisions and rationale
+- Debugging solutions (root cause + fix)
+- Server/infrastructure details (IPs, paths, configs)
+- Build and deployment procedures
+- Tool configurations and setup steps
+- Package names and versions
+- Project conventions and coding patterns
+- Operational knowledge (how to restart, deploy, rollback)
+
+Each wiki page must use this format:
+## Topic
+[What this covers]
+
+## Key Facts
+- [Fact 1]
+- [Fact 2]
+
+## Insights
+- [Non-obvious finding]
+
+## Sources
+- [Session file path]
+
+When done, respond with a summary of what you captured.`;
+// -- Main processor ----------------------------------------------------------
+export async function processSession(sessionPath, wikiDir, store, scope, model, getApiKey) {
+    // 1. Load session
+    const session = loadSession(sessionPath);
+    // 2. Quick check: worth processing?
+    const { stats } = session;
+    const hasToolCalls = stats.toolCalls > 0;
+    if (!hasToolCalls && (stats.totalMessages < 4 || stats.totalChars < 200)) {
+        return { pagesCreated: [], pagesUpdated: [], skipped: true, reason: "trivial session" };
+    }
+    // 3. Create tools
+    const sessionTools = createSessionTools(session);
+    const wikiTools = createWikiTools(wikiDir, store);
+    const allTools = [...sessionTools, ...wikiTools];
+    // 4. Spin up Agent with context pruning for long-running exploration.
+    // After many tool calls, the accumulated context can exceed the LLM's
+    // context window. Prune old session_slice/session_search results — the
+    // Agent already extracted what it needed from them.
+    // Use 75% of the model's context window (chars ≈ tokens * 4), leave headroom.
+    const contextWindowChars = (model.contextWindow ?? 128_000) * 4;
+    const MAX_CONTEXT_CHARS = Math.floor(contextWindowChars * 0.75);
+    const agent = new Agent({
+        initialState: {
+            systemPrompt: CAPTURE_SYSTEM_PROMPT,
+            model,
+            tools: allTools,
+            messages: [],
+        },
+        getApiKey,
+        transformContext: async (messages) => {
+            // Estimate total chars
+            let total = CAPTURE_SYSTEM_PROMPT.length;
+            for (const m of messages) {
+                if ("content" in m) {
+                    const c = m.content;
+                    if (typeof c === "string")
+                        total += c.length;
+                    else if (Array.isArray(c)) {
+                        for (const b of c) {
+                            if (typeof b === "object" && b !== null && "text" in b && typeof b.text === "string") {
+                                total += b.text.length;
+                            }
+                        }
+                    }
+                }
+            }
+            if (total <= MAX_CONTEXT_CHARS)
+                return messages;
+            // Prune old tool results — truncate text blocks to 200 chars
+            return messages.map((m, i) => {
+                if (i >= messages.length - 10)
+                    return m;
+                if (m.role !== "toolResult")
+                    return m;
+                if (!("content" in m) || !Array.isArray(m.content))
+                    return m;
+                const newContent = m.content.map(b => {
+                    if (b.type === "text" && b.text.length > 200) {
+                        return { type: "text", text: b.text.slice(0, 200) + "\n[pruned]" };
+                    }
+                    return b;
+                });
+                return { ...m, content: newContent };
+            });
+        },
+    });
+    // 5. Prompt the agent
+    const promptText = [
+        `Process this session and capture all valuable knowledge into the wiki.`,
+        `Session file: ${sessionPath}`,
+        `Project scope: ${scope}`,
+        `Start by calling session_stats to understand the session.`,
+    ].join("\n");
+    try {
+        await agent.prompt(promptText);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[processor] Agent error: ${errMsg}`);
+        return {
+            pagesCreated: [],
+            pagesUpdated: [],
+            skipped: true,
+            reason: `Agent error: ${errMsg}`,
+        };
+    }
+    // Debug: log what the agent did
+    const msgCount = agent.state.messages.length;
+    const toolCalls = agent.state.messages.filter(m => m.role === "toolResult").length;
+    const lastMsg = agent.state.messages[msgCount - 1];
+    let lastContent = "";
+    if (lastMsg && "content" in lastMsg) {
+        const c = lastMsg.content;
+        if (typeof c === "string")
+            lastContent = c.slice(0, 200);
+        else if (Array.isArray(c)) {
+            const tb = c.find((b) => b.type === "text");
+            if (tb)
+                lastContent = tb.text.slice(0, 200);
+        }
+    }
+    console.log(`[processor] Agent finished: ${msgCount} messages, ${toolCalls} tool results. Last: ${lastContent}`);
+    // 6. Extract what was written from agent's messages
+    const pagesCreated = [];
+    const pagesUpdated = [];
+    for (const msg of agent.state.messages) {
+        if (msg.role !== "toolResult")
+            continue;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (typeof block !== "object" || block === null)
+                continue;
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string" && b.text.startsWith("Wrote ")) {
+                const path = b.text.replace("Wrote ", "").trim();
+                // Check details to see if it was a create or update
+                pagesCreated.push(path);
+            }
+        }
+    }
+    if (pagesCreated.length === 0 && pagesUpdated.length === 0) {
+        return { pagesCreated: [], pagesUpdated: [], skipped: true, reason: "no pages written" };
+    }
+    // 7. Append session digest
+    try {
+        await appendSessionDigest(wikiDir, {
+            date: new Date().toISOString().split("T")[0],
+            project: scope,
+            sessionFile: sessionPath,
+            scope,
+            capturedPages: pagesCreated,
+            summary: `Daemon captured ${pagesCreated.length} page(s) from session`,
+        });
+    }
+    catch {
+        // Non-fatal
+    }
+    return { pagesCreated, pagesUpdated, skipped: false };
+}
+//# sourceMappingURL=processor.js.map

package/dist/processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.js","sourceRoot":"","sources":["../src/processor.ts"],"names":[],"mappings":"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"}

package/dist/query.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Query pipeline — searches the wiki and returns relevant results.
+ *
+ * Performs scoped search via qmd and returns results for the LLM
+ * to synthesize answers from. This is the reusable library function;
+ * the wiki_query tool wraps it with LLM prompt formatting.
+ */
+import type { QMDStore } from "@picassio/qmd";
+import type { ParaCategory } from "./wiki.js";
+import type { WikiSearchResult } from "./store.js";
+import type { ProjectScope } from "./scope.js";
+export interface QueryOptions {
+    /** Natural language search query */
+    query: string;
+    /** Override auto-detected scope tags */
+    scope?: string[];
+    /** Search all scopes (ignore project filter) */
+    global?: boolean;
+    /** Restrict to a PARA category */
+    category?: ParaCategory;
+    /** Maximum results (default 10) */
+    limit?: number;
+    /** Include archives in results (default false) */
+    includeArchives?: boolean;
+    /** Also search the raw/ collection (default false) */
+    includeRaw?: boolean;
+    /** Enable graph-boosted search via 1-hop wikilink expansion (default true) */
+    graphBoost?: boolean;
+}
+export interface QueryResult {
+    /** Search results with page metadata and snippets */
+    results: WikiSearchResult[];
+    /** The scope that was used for filtering */
+    scopeUsed: ProjectScope;
+    /** Whether the search was global (no scope filtering) */
+    wasGlobal: boolean;
+}
+/**
+ * Search the wiki with scope and category filtering.
+ *
+ * This is the reusable library function. It:
+ * 1. Applies scope filtering (unless global flag is set)
+ * 2. Filters by PARA category if specified
+ * 3. Excludes archives unless explicitly requested
+ * 4. Returns results sorted by relevance score
+ *
+ * The caller (tool or standalone agent) can format the results
+ * into an LLM prompt or use them directly.
+ */
+export declare function queryWiki(store: QMDStore, options: QueryOptions, scope: ProjectScope): Promise<QueryResult>;
+/**
+ * Format query results as a readable text block.
+ * Useful for building LLM prompts or display.
+ *
+ * Includes freshness indicators so the LLM knows which pages to trust
+ * vs. which need verification against current code/state.
+ */
+export declare function formatQueryResults(results: WikiSearchResult[]): string;
+/**
+ * Compute a human-readable freshness indicator from the page's `updated` date.
+ *
+ * - < 7 days  → "✅ FRESH"
+ * - 7-14 days → "✅ Recent — N days old"
+ * - 14-30 days → "⚠️ AGING — N days old — verify claims about code/configs"
+ * - 30-90 days → "⚠️ STALE — N days old — verify before trusting"
+ * - > 90 days  → "🚨 VERY STALE — N days old — likely outdated, verify everything"
+ */
+export declare function formatFreshness(updatedISO: string, nowMs: number): string;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,4CAA4C;IAC5C,SAAS,EAAE,YAAY,CAAC;IACxB,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;CACpB;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,WAAW,CAAC,CAgCtB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,CAmBtE;AAID;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYzE"}

package/dist/query.js

@@ -0,0 +1,107 @@
+/**
+ * Query pipeline — searches the wiki and returns relevant results.
+ *
+ * Performs scoped search via qmd and returns results for the LLM
+ * to synthesize answers from. This is the reusable library function;
+ * the wiki_query tool wraps it with LLM prompt formatting.
+ */
+import { searchWiki } from "./store.js";
+// -- Main pipeline -----------------------------------------------------------
+/**
+ * Search the wiki with scope and category filtering.
+ *
+ * This is the reusable library function. It:
+ * 1. Applies scope filtering (unless global flag is set)
+ * 2. Filters by PARA category if specified
+ * 3. Excludes archives unless explicitly requested
+ * 4. Returns results sorted by relevance score
+ *
+ * The caller (tool or standalone agent) can format the results
+ * into an LLM prompt or use them directly.
+ */
+export async function queryWiki(store, options, scope) {
+    const limit = options.limit ?? 10;
+    const isGlobal = options.global ?? false;
+    const includeArchives = options.includeArchives ?? (options.category === "archives");
+    // Build scope override if explicit scope tags provided
+    let effectiveScope;
+    if (isGlobal) {
+        effectiveScope = undefined; // no scope filtering
+    }
+    else if (options.scope && options.scope.length > 0) {
+        effectiveScope = {
+            ...scope,
+            name: scope.name,
+            include: options.scope,
+        };
+    }
+    else {
+        effectiveScope = scope;
+    }
+    const results = await searchWiki(store, options.query, {
+        scope: effectiveScope,
+        category: options.category,
+        limit,
+        includeArchives,
+        graphBoost: options.graphBoost,
+    });
+    return {
+        results,
+        scopeUsed: effectiveScope ?? scope,
+        wasGlobal: isGlobal,
+    };
+}
+/**
+ * Format query results as a readable text block.
+ * Useful for building LLM prompts or display.
+ *
+ * Includes freshness indicators so the LLM knows which pages to trust
+ * vs. which need verification against current code/state.
+ */
+export function formatQueryResults(results) {
+    if (results.length === 0)
+        return "No results found.";
+    const now = Date.now();
+    return results
+        .map((r, i) => {
+        const fm = r.frontmatter;
+        const freshness = formatFreshness(fm.updated, now);
+        return [
+            `### Result ${i + 1}: ${fm.title} (${r.page.path})`,
+            `PARA: ${fm.para} | Scope: ${fm.scope.join(", ")} | Tags: ${fm.tags.join(", ")}`,
+            `Updated: ${fm.updated} | ${freshness}`,
+            `Score: ${r.score.toFixed(3)}`,
+            "",
+            r.snippet,
+        ].join("\n");
+    })
+        .join("\n\n");
+}
+// -- Freshness helpers -------------------------------------------------------
+/**
+ * Compute a human-readable freshness indicator from the page's `updated` date.
+ *
+ * - < 7 days  → "✅ FRESH"
+ * - 7-14 days → "✅ Recent — N days old"
+ * - 14-30 days → "⚠️ AGING — N days old — verify claims about code/configs"
+ * - 30-90 days → "⚠️ STALE — N days old — verify before trusting"
+ * - > 90 days  → "🚨 VERY STALE — N days old — likely outdated, verify everything"
+ */
+export function formatFreshness(updatedISO, nowMs) {
+    const updatedMs = Date.parse(updatedISO);
+    if (isNaN(updatedMs))
+        return "❓ Unknown freshness (no valid date)";
+    const ageDays = Math.floor((nowMs - updatedMs) / (1000 * 60 * 60 * 24));
+    if (ageDays < 0)
+        return "✅ FRESH";
+    if (ageDays < 7)
+        return "✅ FRESH";
+    if (ageDays < 14)
+        return `✅ Recent — ${ageDays} days old`;
+    if (ageDays < 30)
+        return `⚠️ AGING — ${ageDays} days old — verify claims about code/configs`;
+    if (ageDays < 90)
+        return `⚠️ STALE — ${ageDays} days old — verify before trusting`;
+    return `🚨 VERY STALE — ${ageDays} days old — likely outdated, verify everything`;
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/raw.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Raw source vault and session digests.
+ *
+ * Manages immutable source material in ~/.pi/wiki/raw/ and
+ * session digest entries in sessions.md.
+ */
+export interface RawSource {
+    type: "url" | "file" | "text";
+    originalPath: string;
+    savedPath: string;
+    ingestedAt: string;
+    wikiPages: string[];
+}
+export interface SessionDigest {
+    date: string;
+    project: string;
+    sessionFile: string;
+    scope: string;
+    capturedPages: string[];
+    summary: string;
+}
+/**
+ * Save a raw source to the vault. URL sources go to raw/articles/,
+ * file sources to raw/docs/, text sources to raw/notes/.
+ *
+ * The file is saved as markdown with a metadata header.
+ * Returns the path relative to wikiDir (e.g. "raw/articles/example-com-page.md").
+ */
+export declare function saveRawSource(wikiDir: string, source: {
+    type: "url" | "file" | "text";
+    content: string;
+    originalPath: string;
+}): Promise<string>;
+/**
+ * Append a session digest entry to sessions.md in the documented format:
+ *
+ * ```
+ * ## [2026-04-27] pi-mono | SSL certificate debugging
+ * - **Session**: `~/.pi/agent/sessions/.../file.jsonl`
+ * - **Scope**: pi-mono
+ * - **Captured**: [[ssl-cert-gotchas]]
+ * - **Summary**: One-paragraph summary...
+ * ```
+ *
+ * Creates sessions.md if it does not exist.
+ */
+export declare function appendSessionDigest(wikiDir: string, digest: SessionDigest): Promise<void>;
+/**
+ * Parse sessions.md and return session digest entries.
+ * Optionally filter by scope and/or limit the number of results.
+ * Results are returned in file order (oldest first).
+ */
+export declare function readSessionDigests(wikiDir: string, options?: {
+    limit?: number;
+    scope?: string;
+}): Promise<SessionDigest[]>;
+//# sourceMappingURL=raw.d.ts.map

package/dist/raw.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw.d.ts","sourceRoot":"","sources":["../src/raw.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAgFD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;IACN,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,OAAO,CAAC,aAAa,EAAE,CAAC,CAiE1B"}