ultimate-pi 0.1.0 → 0.1.3

package/.agents/skills/wiki/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: wiki
+description: >
+  pi + Obsidian knowledge companion. Sets up a persistent wiki vault, scaffolds
+  structure from a one-sentence description, and routes to specialized sub-skills.
+  Use for setup, scaffolding, cross-project referencing, and hot cache management.
+  Triggers on: "set up wiki", "scaffold vault", "create knowledge base", "/wiki",
+  "wiki setup", "obsidian vault", "knowledge base", "second brain setup",
+  "running notetaker", "persistent memory", "llm wiki".
+allowed-tools: Read Write Edit Glob Grep Bash
+---
+
+# wiki: pi + Obsidian Knowledge Companion
+
+You are a knowledge architect. You build and maintain a persistent, compounding wiki inside an Obsidian vault. You don't just answer questions. You write, cross-reference, file, and maintain a structured knowledge base that gets richer with every source added and every question asked.
+
+The wiki is the product. Chat is just the interface.
+
+The key difference from RAG: the wiki is a persistent artifact. Cross-references are already there. Contradictions have been flagged. Synthesis already reflects everything read. Knowledge compounds like interest.
+
+---
+
+## Wiki Path Resolution
+
+All `wiki/` paths in this skill are relative to the wiki directory inside the Obsidian vault. Resolve before any file operation:
+
+```bash
+WIKI_PATH="${VAULT_WIKI_PATH:-vault/wiki}"
+```
+
+Use `$WIKI_PATH/` as the prefix for all `wiki/...` file paths. Example: `wiki/index.md` → `$WIKI_PATH/index.md` (default: `vault/wiki/index.md`).
+
+---
+
+## Architecture
+
+Three layers:
+
+```
+vault/
+├── .raw/       # Layer 1: immutable source documents
+├── wiki/       # Layer 2: LLM-generated knowledge base
+└── WIKI.md     # Layer 3: vault configuration and instructions
+```
+
+Standard wiki structure:
+
+```
+wiki/
+├── index.md            # master catalog of all pages
+├── log.md              # chronological record of all operations
+├── hot.md              # hot cache: recent context summary (~500 words)
+├── overview.md         # executive summary of the whole wiki
+├── sources/            # one summary page per raw source
+├── entities/           # people, orgs, products, repos
+│   └── _index.md
+├── concepts/           # ideas, patterns, frameworks
+│   └── _index.md
+├── domains/            # top-level topic areas
+│   └── _index.md
+├── comparisons/        # side-by-side analyses
+├── questions/          # filed answers to user queries
+└── meta/               # dashboards, lint reports, conventions
+```
+
+Dot-prefixed folders (`.raw/`) are hidden in Obsidian's file explorer and graph view. Use this for source documents.
+
+---
+
+## Hot Cache
+
+`wiki/hot.md` is a ~500-word summary of the most recent context. It exists so any session (or any other project pointing at this vault) can get recent context without crawling the full wiki.
+
+Update hot.md:
+- After every ingest
+- After any significant query exchange
+- At the end of every session
+
+Format:
+```markdown
+---
+type: meta
+title: "Hot Cache"
+updated: YYYY-MM-DDTHH:MM:SS
+---
+
+# Recent Context
+
+## Last Updated
+YYYY-MM-DD. [what happened]
+
+## Key Recent Facts
+- [Most important recent takeaway]
+- [Second most important]
+
+## Recent Changes
+- Created: [[New Page 1]], [[New Page 2]]
+- Updated: [[Existing Page]] (added section on X)
+- Flagged: Contradiction between [[Page A]] and [[Page B]] on Y
+
+## Active Threads
+- User is currently researching [topic]
+- Open question: [thing still being investigated]
+```
+
+Keep it under 500 words. It is a cache, not a journal. Overwrite it completely each time.
+
+---
+
+## Operations
+
+Route to the correct operation based on what the user says:
+
+| User says | Operation | Sub-skill |
+|-----------|-----------|-----------|
+| "scaffold", "set up vault", "create wiki" | SCAFFOLD | this skill |
+| "ingest [source]", "process this", "add this" | INGEST | `wiki-ingest` |
+| "what do you know about X", "query:" | QUERY | `wiki-query` |
+| "lint", "health check", "clean up" | LINT | `wiki-lint` |
+| "save this", "file this", "/save" | SAVE | `wiki-save` |
+| "/wiki-autoresearch [topic]", "/autoresearch [topic]", "research [topic]" | AUTORESEARCH | `wiki-autoresearch` |
+| "/canvas", "add to canvas", "open canvas" | CANVAS | `canvas` |
+
+---
+
+## SCAFFOLD Operation
+
+Trigger: user describes what the vault is for.
+
+Steps:
+
+1. Determine the wiki mode. Read `references/modes.md` to show the 6 options and pick the best fit.
+2. Ask: "What is this vault for?" (one question, then proceed).
+3. Create full folder structure under `wiki/` based on the mode.
+4. Create domain pages + `_index.md` sub-indexes.
+5. Create `wiki/index.md`, `wiki/log.md`, `wiki/hot.md`, `wiki/overview.md`.
+6. Create `_templates/` files for each note type.
+7. Apply visual customization. Read `references/css-snippets.md`. Create `.obsidian/snippets/vault-colors.css`.
+8. Create the vault WIKI.md using the template below.
+9. Initialize git. Read `references/git-setup.md`.
+10. Present the structure and ask: "Want to adjust anything before we start?"
+
+### Vault WIKI.md Template
+
+Create this file in the vault root when scaffolding a new project vault (not this plugin directory):
+
+```markdown
+# [WIKI NAME]: LLM Wiki
+
+Mode: [MODE A/B/C/D/E/F]
+Purpose: [ONE SENTENCE]
+Owner: [NAME]
+Created: YYYY-MM-DD
+
+## Structure
+
+[PASTE THE FOLDER MAP FROM THE CHOSEN MODE]
+
+## Conventions
+
+- All notes use YAML frontmatter: type, status, created, updated, tags (minimum)
+- Wikilinks use [[Note Name]] format: filenames are unique, no paths needed
+- .raw/ contains source documents: never modify them
+- wiki/index.md is the master catalog: update on every ingest
+- wiki/log.md is append-only: never edit past entries
+- New log entries go at the TOP of the file
+
+## Operations
+
+- Ingest: drop source in .raw/, say "ingest [filename]"
+- Query: ask any question: pi reads index first, then drills in
+- Lint: say "lint the wiki" to run a health check
+- Archive: move cold sources to .archive/ to keep .raw/ clean
+```
+
+---
+
+## Cross-Project Referencing
+
+This is the force multiplier. Any pi project can reference this vault without duplicating context.
+
+In another project's SYSTEM.md (or project skill file), add:
+
+```markdown
+## Wiki Knowledge Base
+Path: ~/path/to/vault
+
+When you need context not already in this project:
+1. Read wiki/hot.md first (recent context, ~500 words)
+2. If not enough, read wiki/index.md (full catalog)
+3. If you need domain specifics, read wiki/<domain>/_index.md
+4. Only then read individual wiki pages
+
+Do NOT read the wiki for:
+- General coding questions or language syntax
+- Things already in this project's files or conversation
+- Tasks unrelated to [your domain]
+```
+
+This keeps token usage low. Hot cache costs ~500 tokens. Index costs ~1000 tokens. Individual pages cost 100-300 tokens each.
+
+---
+
+## Summary
+
+Your job as the LLM:
+1. Set up the vault (once)
+2. Scaffold wiki structure from user's domain description
+3. Route ingest, query, and lint to the correct sub-skill
+4. Maintain hot cache after every operation
+5. Always update index, sub-indexes, log, and hot cache on changes
+6. Always use frontmatter and wikilinks
+7. Never modify .raw/ sources
+
+The human's job: curate sources, ask good questions, think about what it means. Everything else is on you.

package/.agents/skills/wiki/references/css-snippets.md

@@ -0,0 +1,122 @@
+# Visual Customization
+
+Apply during scaffold. This makes the file explorer color-coded by folder type and adds custom callout styles.
+
+---
+
+## CSS Snippet
+
+Create this file at `.obsidian/snippets/vault-colors.css` inside the vault:
+
+```css
+:root {
+  --wiki-1: #4fc1ff;
+  --wiki-2: #c586c0;
+  --wiki-3: #dcdcaa;
+  --wiki-4: #ce9178;
+  --wiki-5: #6a9955;
+  --wiki-6: #d16969;
+  --wiki-7: #569cd6;
+}
+
+/* Folder colors in file explorer */
+.nav-folder-title[data-path^="wiki/domains"]     { color: var(--wiki-1); }
+.nav-folder-title[data-path^="wiki/entities"]    { color: var(--wiki-2); }
+.nav-folder-title[data-path^="wiki/concepts"]    { color: var(--wiki-3); }
+.nav-folder-title[data-path^="wiki/sources"]     { color: var(--wiki-4); }
+.nav-folder-title[data-path^="wiki/questions"]   { color: var(--wiki-5); }
+.nav-folder-title[data-path^="wiki/comparisons"] { color: var(--wiki-6); }
+.nav-folder-title[data-path^="wiki/meta"]        { color: var(--wiki-7); }
+.nav-folder-title[data-path=".raw"]              { color: #808080; opacity: 0.6; }
+
+/* Custom callouts */
+.callout[data-callout='contradiction'] {
+  --callout-color: 209, 105, 105;
+  --callout-icon: lucide-alert-triangle;
+}
+.callout[data-callout='gap'] {
+  --callout-color: 220, 220, 170;
+  --callout-icon: lucide-help-circle;
+}
+.callout[data-callout='key-insight'] {
+  --callout-color: 79, 193, 255;
+  --callout-icon: lucide-lightbulb;
+}
+.callout[data-callout='stale'] {
+  --callout-color: 128, 128, 128;
+  --callout-icon: lucide-clock;
+}
+```
+
+---
+
+## Enable the Snippet
+
+Tell the user: Settings > Appearance > CSS Snippets > open folder > paste the file > click the refresh icon > toggle it on.
+
+---
+
+## Graph View Groups
+
+Guide the user to set these in Graph View settings (click the settings icon in the graph view):
+
+| Query | Color |
+|-------|-------|
+| `path:wiki/domains` | Blue (`#4fc1ff`) |
+| `path:wiki/entities` | Purple (`#c586c0`) |
+| `path:wiki/concepts` | Yellow (`#dcdcaa`) |
+| `path:wiki/sources` | Orange (`#ce9178`) |
+| `path:wiki/questions` | Green (`#6a9955`) |
+| `path:.raw` | Gray (dimmed) |
+
+---
+
+## Custom Callouts
+
+This vault defines **four custom callout types** beyond Obsidian's built-in set (`note`, `tip`, `warning`, `info`, `todo`, `success`, `question`, `failure`, `danger`, `bug`, `example`, `quote`). They render correctly **only when `vault-colors.css` is enabled**. Without the snippet, they fall back to default callout styling (still readable, just plain).
+
+| Custom callout | Color | Icon | Use for |
+|---|---|---|---|
+| `contradiction` | reddish-brown (rgb 209,105,105) | `lucide-alert-triangle` | New source conflicts with existing claim |
+| `gap` | beige (rgb 220,220,170) | `lucide-help-circle` | Topic has no source yet |
+| `key-insight` | bright blue (rgb 79,193,255) | `lucide-lightbulb` | Important takeaway worth highlighting |
+| `stale` | gray (rgb 128,128,128) | `lucide-clock` | Claim may be outdated, source older than threshold |
+
+### Usage
+
+Use these in wiki pages to flag important states:
+
+```markdown
+> [!contradiction] Title
+> [[Page A]] claims X. [[Page B]] says Y. Needs resolution.
+
+> [!gap] Title
+> This topic has no source yet. Consider finding one.
+
+> [!key-insight] Title
+> The most important takeaway from this section.
+
+> [!stale] Title
+> This claim may be outdated. Source was from 2022.
+```
+
+### Why custom callouts (vs built-in)
+
+The four custom types map to wiki-specific concepts that don't fit cleanly into Obsidian's default set:
+
+- `contradiction` is more specific than `warning`: it signals a **resolvable conflict** between two wiki pages, not a generic warning.
+- `gap` is more specific than `question`: it signals a **missing source**, an actionable improvement.
+- `key-insight` is more specific than `tip`: it marks **the** most important takeaway from a section, used sparingly.
+- `stale` has no built-in equivalent: it signals time-based decay of a claim.
+
+If you don't want custom callouts, replace them with built-ins:
+- `[!contradiction]` → `[!warning] Contradiction`
+- `[!gap]` → `[!question] Gap`
+- `[!key-insight]` → `[!tip] Key insight`
+- `[!stale]` → `[!warning] Stale`
+
+---
+
+## Minimal Theme (Recommended)
+
+The color scheme looks best with the Minimal theme. Install via Settings > Appearance > Manage > search "Minimal".

package/.agents/skills/wiki/references/frontmatter.md

@@ -0,0 +1,107 @@
+# Frontmatter Schema
+
+Every wiki page starts with flat YAML frontmatter. No nested objects. Obsidian's Properties UI requires flat structure.
+
+---
+
+## Universal Fields
+
+Every page, no exceptions:
+
+```yaml
+---
+type: <source|entity|concept|domain|comparison|question|overview|meta>
+title: "Human-Readable Title"
+created: 2026-04-07
+updated: 2026-04-07
+tags:
+  - <domain-tag>
+  - <type-tag>
+status: <seed|developing|mature|evergreen>
+related:
+  - "[[Other Page]]"
+sources:
+  - "[[.raw/articles/source-file.md]]"
+---
+```
+
+**status values:**
+- `seed`: exists, barely populated
+- `developing`: has real content, not yet complete
+- `mature`: comprehensive, well-linked
+- `evergreen`: unlikely to need updates
+
+---
+
+## Type-Specific Additions
+
+### source
+
+Add these fields after the universal fields:
+
+```yaml
+source_type: article    # article | video | podcast | paper | book | transcript | data
+author: ""
+date_published: YYYY-MM-DD
+url: ""
+confidence: high        # high | medium | low
+key_claims:
+  - "First key claim from this source"
+  - "Second key claim"
+```
+
+### entity
+
+```yaml
+entity_type: person     # person | organization | product | repository | place
+role: ""
+first_mentioned: "[[Source Title]]"
+```
+
+### concept
+
+```yaml
+complexity: intermediate  # basic | intermediate | advanced
+domain: ""
+aliases:
+  - "alternative name"
+  - "abbreviation"
+```
+
+### comparison
+
+```yaml
+subjects:
+  - "[[Thing A]]"
+  - "[[Thing B]]"
+dimensions:
+  - "performance"
+  - "cost"
+  - "ease of use"
+verdict: "One-line conclusion."
+```
+
+### question
+
+```yaml
+question: "The original query as asked."
+answer_quality: solid   # draft | solid | definitive
+```
+
+### domain
+
+```yaml
+subdomain_of: ""        # leave empty for top-level domains
+page_count: 0
+```
+
+---
+
+## Rules
+
+1. Use flat YAML only. Never nest objects.
+2. Dates as `YYYY-MM-DD` strings, not ISO datetime.
+3. Lists always use the `- item` format, not inline `[a, b, c]`.
+4. Wikilinks in YAML fields must be quoted: `"[[Page Name]]"`.
+5. Keep `related` and `sources` as wikilinks, not plain URLs.
+6. Update `updated` every time you edit the page content.

package/.agents/skills/wiki/references/git-setup.md

@@ -0,0 +1,58 @@
+# Git Setup
+
+Initialize git in the vault to get full history and protect against bad writes.
+
+---
+
+## Initialize
+
+```bash
+cd "$VAULT_PATH"
+git init
+git add -A
+git commit -m "Initial vault scaffold"
+```
+
+---
+
+## .gitignore
+
+The root `.gitignore` in this repo already covers the right exclusions:
+
+```
+.obsidian/workspace.json
+.obsidian/workspace-mobile.json
+.smart-connections/
+.obsidian-git-data
+.trash/
+.DS_Store
+```
+
+`workspace.json` changes constantly as you move panes around. Excluding it keeps the diff clean.
+
+---
+
+## Obsidian Git Plugin
+
+After installing the plugin (see `plugins.md`):
+
+Settings > Obsidian Git:
+- Auto backup interval: **15 minutes**
+- Auto backup after file change: on
+- Push on backup: on (if you have a remote)
+- Commit message: `vault: auto backup {{date}}`
+
+This runs silently in the background. You get a full history of every note without thinking about it.
+
+---
+
+## Remote (Optional)
+
+To back up to GitHub:
+
+```bash
+git remote add origin https://github.com/yourname/your-vault
+git push -u origin main
+```
+
+Keep the repo private if the vault contains personal notes.

package/.agents/skills/wiki/references/mcp-setup.md

@@ -0,0 +1,149 @@
+# MCP Setup
+
+MCP lets pi read and write vault notes directly without copy-paste. Four options ordered from simplest to most featureful.
+
+> [!tip] Recommendation
+> If you have **Obsidian v1.12 or newer**, start with **Option D: Obsidian CLI**. It needs no MCP server, no plugins, and no TLS workarounds. Use Options A or B only if you need persistent MCP integration or are on an older Obsidian version.
+
+---
+
+## Step 1: Install the Local REST API Plugin
+
+You must do this in Obsidian (pi cannot do it programmatically):
+
+1. Obsidian > Settings > Community Plugins > Turn off Restricted Mode
+2. Browse > Search "Local REST API" > Install > Enable
+3. Settings > Local REST API > Copy the API key
+
+The plugin runs on `https://127.0.0.1:27124` with a self-signed certificate.
+
+Test it:
+```bash
+curl -sk -H "Authorization: Bearer <YOUR_KEY>" https://127.0.0.1:27124/
+```
+
+You should get a JSON response with vault info.
+
+---
+
+## Option A: mcp-obsidian (REST API based)
+
+Uses MarkusPfundstein's mcp-obsidian. Requires the Local REST API plugin running.
+
+```bash
+Add the MCP server to pi's configuration. In `.pi/settings.json` or via pi's MCP bridge, configure:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-vault": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-obsidian"],
+      "env": {
+        "OBSIDIAN_API_KEY": "<YOUR_KEY>",
+        "OBSIDIAN_HOST": "127.0.0.1",
+        "OBSIDIAN_PORT": "27124",
+        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+      }
+    }
+  }
+}
+```
+```
+
+> [!warning] Security
+> `NODE_TLS_REJECT_UNAUTHORIZED: "0"` **disables TLS certificate verification process-wide** for the MCP server. It is required here because the Local REST API plugin uses a self-signed certificate. This is acceptable for `127.0.0.1` (localhost) connections only. Never use this setting for any non-loopback connection. If you are uncomfortable with the global TLS bypass, prefer **Option D (Obsidian CLI)** or **Option B (filesystem-based)** which avoid this entirely.
+
+Capabilities: read notes, write notes, search, patch frontmatter fields, append under headings.
+
+---
+
+## Option B: MCPVault (filesystem based)
+
+No Obsidian plugin needed. Reads the vault directory directly.
+
+```bash
+Add the MCP server to pi's configuration. In `.pi/settings.json` or via pi's MCP bridge, configure:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-vault": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@bitbonsai/mcpvault@latest", "/absolute/path/to/your/vault"]
+    }
+  }
+}
+```
+```
+
+Replace `/absolute/path/to/your/vault` with the actual vault path.
+
+Tools available: `search_notes` (BM25), `read_note`, `create_note`, `update_note`, `get_frontmatter`, `update_frontmatter`, `list_all_tags`, `read_multiple_notes`.
+
+---
+
+## Option C: Direct REST API via curl
+
+No MCP needed. Use curl in bash throughout the session. See `rest-api.md` for all commands.
+
+---
+
+## Option D: Obsidian CLI (recommended for v1.12+)
+
+Obsidian shipped a native CLI in v1.12 (2026). It exposes vault operations directly to the terminal. No REST API plugin, no MCP server, no self-signed certs, no TLS workarounds. pi calls it through the Bash tool.
+
+**Check if available:**
+```bash
+which obsidian-cli 2>/dev/null && obsidian-cli --version
+# or, on flatpak:
+flatpak run md.obsidian.Obsidian --cli --version
+```
+
+**Common operations:**
+```bash
+# List all notes in a folder
+obsidian-cli list /path/to/vault wiki/
+
+# Read a note
+obsidian-cli read /path/to/vault wiki/index.md
+
+# Create or update a note
+obsidian-cli write /path/to/vault wiki/new-note.md < content.md
+
+# Search notes by content
+obsidian-cli search /path/to/vault "query term"
+```
+
+**Why prefer this**:
+- No plugin install required (CLI is built into Obsidian)
+- No MCP server process to manage
+- No TLS certificate bypass needed
+- Survives Obsidian restarts (no persistent connection)
+- Works identically across desktop and headless environments
+
+**When to use Options A/B/C instead**: If you need persistent semantic search, frontmatter patching, or are on Obsidian < v1.12.
+
+The `kepano/obsidian-skills` repo includes an `obsidian-cli` skill that wraps these commands as reusable patterns. Install it alongside this plugin for first-class CLI support.
+
+---
+
+## Use `--scope user`
+
+Configure MCP servers at the user level so the vault is available across all pi projects, not just the one where you ran the command.
+
+---
+
+## Verification
+
+After setup:
+
+```bash
+Check pi's MCP status to confirm the server appears and the path/URL is correct.
+```
+
+In a pi session, type `/mcp` to check connection status.
+
+Then test: "List all notes in my wiki folder."