pi-para 0.5.2

package/src/tag-registry.ts

@@ -0,0 +1,157 @@
+/**
+ * Canonical tag registry — normalizes and deduplicates wiki page tags.
+ *
+ * Rules:
+ * 1. Spaces → hyphens ("session files" → "session-files")
+ * 2. Lowercase everything
+ * 3. Map aliases → canonical tags
+ * 4. Remove tags that duplicate scope values on the same page
+ * 5. Deduplicate
+ */
+
+// -- Scope normalization -----------------------------------------------------
+
+/**
+ * Normalize a scope value.
+ *
+ * Scope should be a project name (kebab-case, single token), not a topic
+ * description. The daemon LLM sometimes writes freeform multi-word
+ * descriptions like "session exploration" or "mono project" as scope.
+ *
+ * Rules:
+ * 1. Trim + lowercase
+ * 2. If the value contains a known project name as a prefix, extract it
+ *    (e.g. "pi-para daemon" → "pi-para", "pi-mono project" → "pi-mono")
+ * 3. If still multi-word after extraction, drop it — it's a topic
+ *    description, not a project name
+ * 4. Return the clean kebab-case scope
+ *
+ * This is project-agnostic — works for any project, not just pi-para.
+ */
+export function normalizeScope(scope: string): string | null {
+  const s = scope.trim().toLowerCase();
+  if (!s) return null;
+
+  // Already clean (no spaces) — pass through
+  if (!s.includes(" ")) return s;
+
+  // Try to extract a kebab-case project name prefix.
+  // Multi-word scopes from the LLM follow the pattern:
+  //   "<project-name> <topic words>"  e.g. "pi-mono project", "pi-para daemon"
+  // Extract the first kebab-case token if it looks like a project name.
+  const firstToken = s.split(" ")[0];
+  if (firstToken && firstToken.includes("-")) {
+    // Looks like a kebab-case project name (e.g. "pi-mono", "pi-para")
+    return firstToken;
+  }
+
+  // Multi-word without a kebab prefix → topic description, drop it
+  return null;
+}
+
+/**
+ * Normalize a full scope list:
+ * 1. Normalize each value
+ * 2. Deduplicate
+ * 3. Ensure at least one scope remains (fallback to "global")
+ */
+export function normalizeScopes(scopes: string[]): string[] {
+  const result = new Set<string>();
+  for (const s of scopes) {
+    const normalized = normalizeScope(s);
+    if (normalized) result.add(normalized);
+  }
+  if (result.size === 0) result.add("global");
+  return [...result].sort();
+}
+
+// -- Tag normalization -------------------------------------------------------
+
+/** Canonical tag → list of aliases that map to it. */
+const TAG_ALIASES: Record<string, string[]> = {
+  // session/capture family
+  "session-capture": ["capture", "background-capture", "session"],
+  "session-files": ["session files"],
+
+  // project identity
+  "pi-para": ["para"],
+  "pi-mono": ["mono"],
+  "coding-agent": ["agent"],
+
+  // tech
+  "node-llama-cpp": [],
+  "qmd-search": ["bm25"],
+  "lazy-loading": [],
+
+  // kebab-case normalization
+  "scope-detection": ["scope detection"],
+  "project-structure": ["project structure", "structure"],
+  "model-registry": ["model registry"],
+  "thinking-level": ["thinking level"],
+  "interactive-mode": ["interactive mode"],
+  "exploration-incomplete": ["exploration incomplete"],
+  "ui-component": ["UI component"],
+  "scoped-models": ["scopedModels"],
+  "github-packages": [],
+  "architecture-pattern": [],
+  "knowledge-management": ["knowledge-base"],
+
+  // UI
+  "webui": ["ui", "frontend", "react"],
+};
+
+/** Build reverse lookup: alias → canonical. */
+function buildAliasMap(): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [canonical, aliases] of Object.entries(TAG_ALIASES)) {
+    for (const alias of aliases) {
+      map.set(alias.toLowerCase(), canonical);
+    }
+  }
+  return map;
+}
+
+const ALIAS_MAP = buildAliasMap();
+
+/**
+ * Normalize a single tag:
+ * 1. Trim + lowercase
+ * 2. Spaces → hyphens
+ * 3. Resolve alias → canonical
+ */
+export function normalizeTag(tag: string): string {
+  let t = tag.trim().toLowerCase().replace(/\s+/g, "-");
+  const canonical = ALIAS_MAP.get(t);
+  if (canonical) t = canonical;
+  return t;
+}
+
+/**
+ * Normalize a full tag list for a page, given its scope.
+ *
+ * 1. Normalize each tag
+ * 2. Remove tags that exactly match a scope value
+ * 3. Deduplicate
+ * 4. Sort alphabetically
+ */
+export function normalizeTags(tags: string[], scope: string[]): string[] {
+  const scopeSet = new Set(scope.map(s => s.toLowerCase()));
+  const normalized = new Set<string>();
+
+  for (const tag of tags) {
+    const t = normalizeTag(tag);
+    if (!t) continue;
+    // Don't add tags that duplicate scope
+    if (scopeSet.has(t)) continue;
+    normalized.add(t);
+  }
+
+  return [...normalized].sort();
+}
+
+/**
+ * Get the full alias map for external inspection (e.g., lint reporting).
+ */
+export function getAliasMap(): ReadonlyMap<string, string> {
+  return ALIAS_MAP;
+}

package/src/templates/index.md

@@ -0,0 +1,17 @@
+# Wiki Index
+
+## Projects
+
+_No active projects yet._
+
+## Areas
+
+_No areas defined yet._
+
+## Resources
+
+_No resources yet._
+
+## Archives
+
+_No archived items._

package/src/templates/prompts.ts

@@ -0,0 +1,274 @@
+/**
+ * LLM prompt templates for ingest, query, lint, capture, and summarize operations.
+ *
+ * Use getPrompt(name) to load the GEPA-optimized version (if deployed) or the original.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Load a prompt by name — returns the GEPA-optimized version if
+ * config.gepa.useOptimized is true, otherwise returns the original.
+ *
+ * Resolution order:
+ * 1. User-generated optimized prompt at ~/.pi/wiki/gepa/optimized/{name}.txt
+ * 2. Bundled optimized prompt shipped with the package (src/gepa/optimized/{name}.txt)
+ * 3. Original constant from this file
+ */
+export function getPrompt(name: string): string {
+  const original = _originals()[name];
+  if (!original) return "";
+  try {
+    const cfgPath = join(homedir(), ".pi", "wiki", "config.json");
+    if (!existsSync(cfgPath)) return original;
+    const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+    if (!cfg.gepa?.useOptimized) return original;
+
+    // 1. Check user-generated optimized prompt
+    const userPath = join(homedir(), ".pi", "wiki", "gepa", "optimized", `${name}.txt`);
+    if (existsSync(userPath)) {
+      const content = readFileSync(userPath, "utf-8").trim();
+      if (content.length > 50) return content;
+    }
+
+    // 2. Check bundled optimized prompt (shipped with package)
+    const bundledPath = join(dirname(new URL(import.meta.url).pathname), "..", "gepa", "optimized", `${name}.txt`);
+    if (existsSync(bundledPath)) {
+      const content = readFileSync(bundledPath, "utf-8").trim();
+      if (content.length > 50) return content;
+    }
+  } catch { /* fall through to original */ }
+  return original;
+}
+
+function _originals(): Record<string, string> {
+  return {
+    "wiki-system-prompt": WIKI_SYSTEM_PROMPT,
+    "ingest-prompt": INGEST_PROMPT,
+    "query-prompt": QUERY_PROMPT,
+    "capture-system-prompt": CAPTURE_SYSTEM_PROMPT,
+    "capture-prompt": CAPTURE_PROMPT,
+    "explicit-capture-prompt": EXPLICIT_CAPTURE_PROMPT,
+    "summarize-system-prompt": SUMMARIZE_SYSTEM_PROMPT,
+    "iterative-update-prompt": ITERATIVE_UPDATE_PROMPT,
+    "overview-prompt": OVERVIEW_PROMPT,
+    "lint-prompt": LINT_PROMPT,
+  };
+}
+
+// -- Wiki System Prompt (standalone agent) ------------------------------------
+
+/**
+ * System prompt for the standalone wiki agent used in capture, lint, and
+ * summarize operations. This agent runs outside the session's agent loop.
+ */
+export const WIKI_SYSTEM_PROMPT = `You are a wiki knowledge management agent. You maintain a PARA-structured knowledge base.
+
+Your job is to read content, extract knowledge, and write structured wiki pages. You operate autonomously — no user confirmation needed.
+
+PARA category rules:
+- **resources/**: Use for almost everything — architecture docs, how-tos, debugging solutions, configs, patterns, implementation notes. This is the default.
+- **areas/**: Only for ongoing responsibilities with no end date (e.g. server config, deployment procedures).
+- **projects/**: ONLY for actual goals with a defined end date and completion criteria. Do NOT use for documentation about a project's internals.
+- **archives/**: Never create pages here — pages get moved here when completed.
+
+When the user defines a specific goal with a completion condition, create a projects/ page. When identifying a repeating responsibility (monitoring, maintenance, quality), create an areas/ page.
+
+Scope and tag rules:
+- scope must be a kebab-case project name (e.g. "pi-para", "qmd"). NOT topic descriptions like "session exploration".
+- tags must be kebab-case (no spaces). Don't duplicate scope values as tags.
+
+Content rules:
+- Use [[wikilinks]] to connect related pages. Always add a ## Connections section.
+- Use the wiki summary format: Topic, Key Facts, Insights, Connections, Open Questions, Sources
+- Keep pages focused on one concept each
+- Be concise and factual — no fluff
+- Check for existing similar pages before creating new ones to avoid duplicates
+- NEVER include API keys, tokens, passwords, or secrets. Document WHERE they are stored, not the values.
+- Index is auto-rebuilt after every write — do not manage index.md manually. Do NOT pass indexContent to wiki_write.`;
+
+// -- Ingest Prompts ----------------------------------------------------------
+
+/**
+ * Prompt included in the tool result when the LLM processes an ingested source.
+ * The LLM reads this along with the source content, schema, and current index.
+ */
+export const INGEST_PROMPT = `Analyze the source content below and integrate it into the wiki.
+
+Instructions:
+1. Identify key entities, concepts, facts, and relationships in the source
+2. Review the current index to find existing pages that should be updated
+3. Decide which existing wiki pages need updates and what new pages to create
+4. For each page, use the wiki summary format:
+   - Topic: what this page covers
+   - Key Facts: established knowledge points
+   - Insights: non-obvious findings, patterns, implications
+   - Connections: [[wikilinks]] to related pages with descriptions
+   - Open Questions: gaps in knowledge, unresolved contradictions
+   - Sources: source URLs, file paths, session references
+5. Assign PARA category correctly:
+   - resources/ for reference material (DEFAULT — use this for most pages)
+   - areas/ for ongoing responsibilities
+   - projects/ ONLY for actual goals with end dates
+6. scope must be a kebab-case project name (NOT topic descriptions). tags must be kebab-case (no spaces).
+7. Always add [[wikilinks]] and a ## Connections section linking related pages
+8. Flag any contradictions with existing wiki content in Open Questions
+9. When updating existing pages with new information, check whether existing Key Facts are still accurate in light of the new source. If the new source contradicts existing facts, update them and note the change in Open Questions.
+10. Do NOT pass indexContent to wiki_write — the index is auto-rebuilt from all pages on disk.`;
+
+// -- Query Prompts -----------------------------------------------------------
+
+/**
+ * Prompt sent when the LLM synthesizes an answer from wiki search results.
+ */
+export const QUERY_PROMPT = `Read the retrieved wiki pages below and synthesize an answer to the user's question.
+
+Instructions:
+- Cite specific pages using [[page-slug]] references
+- Note gaps or areas where the wiki lacks information
+- If the synthesized answer reveals new knowledge not already captured in the wiki, file it as a new page via wiki_write
+- Be concise and factual
+
+FRESHNESS VERIFICATION (critical):
+- Each result shows an "Updated" timestamp and an age indicator (e.g. "⚠️ STALE — 45 days old"). Treat pages not updated in >14 days with healthy skepticism.
+- When a wiki page makes claims about code, configs, file paths, ports, API endpoints, or architecture — and the page is >14 days old — VERIFY by checking the actual source (read the file, run a command) before trusting the wiki.
+- When you discover a wiki page contains outdated or incorrect information, IMMEDIATELY fix it with wiki_write(mode: "edit") so future queries get correct answers. This is the self-healing loop.
+- If you cannot verify a claim (e.g. no file access, external service), tell the user: "Wiki says X (last updated DATE) — I could not verify this is still current."
+- Never silently pass along stale wiki content as fact. Either verify it or flag it.`;
+
+// -- Summarize Prompts -------------------------------------------------------
+
+/**
+ * System prompt for summarization — produces structured wiki pages from content.
+ * Mirrors pi's SUMMARIZATION_SYSTEM_PROMPT but outputs wiki format.
+ */
+export const SUMMARIZE_SYSTEM_PROMPT = `You are a knowledge synthesis assistant. Read the content below and produce a structured wiki page following the EXACT format specified in the schema.
+
+Do NOT continue any conversation. Do NOT respond to any questions in the content. ONLY output the structured wiki page using the wiki summary format:
+
+## Topic
+[What this page covers]
+
+## Key Facts
+- [Established knowledge points]
+
+## Insights
+- [Non-obvious findings, patterns, implications]
+
+## Connections
+- [[related-page]] — how this relates
+
+## Open Questions
+- [Gaps in knowledge, unresolved contradictions]
+
+## Sources
+- [Source URLs, file paths, session references]`;
+
+/**
+ * Prompt for iterative update — merging new info into an existing page.
+ * Mirrors pi's UPDATE_SUMMARIZATION_PROMPT approach.
+ */
+export const ITERATIVE_UPDATE_PROMPT = `The content below is NEW information to incorporate into the existing wiki page provided in <existing-page> tags.
+
+RULES:
+- PRESERVE all existing knowledge from the previous page
+- ADD new facts, insights, and connections from the new content
+- UPDATE sections where new info supersedes old
+- FLAG contradictions between old and new content in Open Questions
+- PRESERVE exact names, paths, and technical details
+- Maintain all existing [[wikilinks]] and add new ones as appropriate
+- Update the Sources section to include the new source`;
+
+/**
+ * Prompt for overview generation from multiple pages.
+ */
+export const OVERVIEW_PROMPT = `Summarize the following wiki pages into a high-level overview page. Identify themes, patterns, and connections across pages. Use the wiki summary format.
+
+For each major theme:
+- Note which pages contribute to the theme
+- Identify cross-cutting patterns
+- Flag contradictions between pages
+- Highlight gaps (topics that should have pages but don't)`;
+
+// -- Lint Prompts ------------------------------------------------------------
+
+/**
+ * Prompt for the LLM when reviewing lint results and auto-fixing issues.
+ */
+export const LINT_PROMPT = `Review the lint results below and fix all auto-fixable issues.
+
+For each issue:
+- Prioritize by impact (errors first, then warnings, then info)
+- Fix broken wikilinks by finding the correct target page or removing dead links
+- Add missing pages for concepts referenced across multiple pages
+- Move stale projects to archives if inactive for 90+ days
+- Fix frontmatter issues (missing fields, invalid dates, empty scope)
+- Update index.md to include any pages missing from the index
+- Propose archiving for inactive projects
+
+Report unfixable issues that require human judgment.`;
+
+// -- Capture Prompts ---------------------------------------------------------
+
+/**
+ * System prompt for the standalone capture agent.
+ * Used as WIKI_SYSTEM_PROMPT for the capture agent instance.
+ */
+export const CAPTURE_SYSTEM_PROMPT = `You are a knowledge capture assistant. Your job is to extract persistent knowledge from coding sessions and write it to a PARA-structured wiki.
+
+Capture ANY of the following — even from short sessions:
+- Architecture decisions and rationale ("we chose X because Y")
+- Debugging solutions (root cause + fix)
+- Server/infrastructure details (IPs, paths, credentials locations, configs)
+- Build and deployment procedures (commands, steps, gotchas)
+- API keys, service endpoints, and where they are stored
+- Project conventions and coding patterns
+- Tool configurations and setup steps
+- Dependencies and version constraints
+- Environment-specific knowledge (dev vs prod differences)
+- Operational runbooks (how to restart, deploy, rollback)
+
+Index is auto-rebuilt after every write — do not manage index.md manually. Do NOT pass indexContent to wiki_write.
+
+Rules:
+- If the session was ONLY greetings or completely off-topic chitchat with zero project knowledge, respond with "nothing to capture"
+- Otherwise, always capture — even small facts are valuable ("the deploy key is at /path/to/key")
+- Classify each piece of knowledge by PARA category autonomously
+- When the user defines a specific goal with a completion condition, create a projects/ page. When identifying a repeating responsibility (monitoring, maintenance, quality), create an areas/ page.
+- Produce wiki pages in the standard wiki summary format (Topic, Key Facts, Insights, Connections, Open Questions, Sources)
+- Include the full session file path in the Sources section for traceability
+- ALWAYS search wiki_query BEFORE creating any page — update existing pages instead of creating duplicates
+- If wiki_query finds a page on the same topic (even with a different title/slug), update THAT page using its existing slug
+- The conversation may include compaction summaries from earlier in the session — treat these as authoritative records of prior work
+- Write directly via wiki_write — no user confirmation needed
+- NEVER include API keys, tokens, passwords, or secrets in wiki pages. Document WHERE they are stored, not the actual values.`;
+
+/**
+ * Prompt template for auto-capture at session_shutdown.
+ * The serialized conversation is appended after this prompt.
+ */
+export const CAPTURE_PROMPT = `Analyze the session conversation below and capture ALL project-relevant knowledge into the wiki.
+
+Capture bias: when in doubt, capture it. Small operational facts (paths, configs, server details, commands) are often the most valuable because they are hard to rediscover.
+
+Only respond with "nothing to capture" if the session was purely greetings or off-topic chitchat with zero project knowledge.
+
+For everything else:
+1. Use wiki_query to search for EXISTING pages on each topic FIRST
+2. If a matching page exists, use wiki_read to get its content, then wiki_write with its EXACT slug to update it
+3. Only create a NEW page if wiki_query returned no relevant results
+4. Each page must include the session file path in its Sources section
+5. Do NOT pass indexContent to wiki_write - the index is auto-rebuilt from all pages on disk
+
+CRITICAL: prefer updating over creating. The wiki likely already has pages on most topics.
+
+<session-conversation>
+`;
+
+/**
+ * Prompt template for explicit capture via /wiki-capture.
+ * A topic hint (if provided) and the serialized conversation are appended.
+ */
+export const EXPLICIT_CAPTURE_PROMPT = `Capture knowledge from the current session into the wiki.`;

package/src/templates/schema.md

@@ -0,0 +1,116 @@
+# Wiki Schema
+
+## Page Format
+
+Every wiki page is a markdown file with YAML frontmatter:
+
+```yaml
+---
+title: Page Title
+para: projects | areas | resources | archives
+scope:
+  - project-name
+tags:
+  - topic-tag
+sources:
+  - https://example.com
+created: "2026-01-01"
+updated: "2026-01-01"
+links:
+  - other-page-slug
+---
+```
+
+## PARA Categories
+
+- **resources/**: Reference material, architecture docs, how-tos, patterns, debugging solutions, implementation notes. **Use this for almost everything.** If you're documenting how something works, put it here.
+- **areas/**: Ongoing responsibilities with no end date — server configs, deployment procedures, infrastructure. Default scope: `["global"]`.
+- **projects/**: ONLY for actual project goals with a defined end date and completion criteria (e.g. "migrate auth to OAuth2"). Do NOT use for documentation about a project's internals. A page about "pi-para daemon architecture" is a resource, not a project.
+- **archives/**: Completed or deprecated items. Never create pages here — pages get moved here when done.
+
+### Category decision rule
+
+Ask: "Is this a goal I'm trying to accomplish, or knowledge I'm recording?"
+- **Goal with end date** → projects/
+- **Knowledge/reference** → resources/
+- **Ongoing responsibility** → areas/
+
+## Scope
+
+Scope is the **project name** this page relates to. Must be kebab-case, single token.
+
+✅ Correct: `pi-para`, `qmd`, `pi-mono`, `my-app`
+❌ Wrong: `session exploration`, `daemon implementation`, `project structure`
+
+Pages relevant to all projects use `global`.
+
+## Tags
+
+Tags are topic classifiers. Must be kebab-case (no spaces).
+
+✅ Correct: `session-capture`, `lazy-loading`, `architecture`
+❌ Wrong: `session files`, `UI component`, `model registry`
+
+Don't duplicate scope values as tags — if scope is `pi-para`, don't also tag `pi-para`.
+
+## Naming Conventions
+
+- Slugs: lowercase, hyphens, no special characters (e.g., `ssl-cert-gotchas`)
+- One concept per page
+
+## Wikilinks
+
+Use `[[slug]]` to connect related pages. Every page should link to related pages in a `## Connections` section:
+
+```markdown
+## Connections
+- [[related-page]] — how this relates
+- [[another-page]] — why it's relevant
+```
+
+The `links` frontmatter field is auto-synced from body `[[wikilinks]]` — don't set it manually.
+
+## Wiki Summary Format
+
+```markdown
+## Topic
+[What this page covers]
+
+## Key Facts
+- [Established knowledge points]
+
+## Insights
+- [Non-obvious findings, patterns, implications]
+
+## Connections
+- [[related-page]] — how this relates
+
+## Open Questions
+- [Gaps in knowledge, unresolved contradictions]
+
+## Sources
+- [Source URLs, file paths, session references]
+```
+
+## Updates vs. New Pages
+
+- Update an existing page when new information relates to the same concept
+- Create a new page when the concept is distinct enough to stand alone
+- When in doubt, create a new page and add [[wikilinks]]
+
+## Secrets
+
+NEVER include secrets in wiki pages:
+- API keys, tokens, passwords, private keys
+- Connection strings with credentials
+- Any value that would be dangerous if exposed
+
+Instead, document WHERE the secret is stored:
+- ✅ `API key stored in ~/.config/qmd/index.yml on server 10.88.1.8`
+- ❌ `key: sk-or-v1-abc123...`
+
+Secrets are automatically redacted on write. If you see `<REDACTED>` in a page, it was stripped for security.
+
+## Tone
+
+Technical, concise, factual. No fluff.