ultimate-pi 0.1.0 → 0.1.3

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

@@ -0,0 +1,259 @@
+# Wiki Modes
+
+Six modes cover the most common use cases. Pick the one that fits, or combine them.
+
+---
+
+## Mode A: Website / Sitemap
+
+Use when: "build a sitemap wiki for my website", "map content gaps", "SEO audit wiki"
+
+```
+vault/
+├── .raw/              # crawl exports, analytics, scraped pages, GSC data
+├── wiki/
+│   ├── pages/         # one note per URL: status, meta, content summary
+│   ├── structure/     # site architecture, nav hierarchy, internal link map
+│   ├── audits/        # content gaps, redirect needs, thin content flags
+│   ├── keywords/      # keyword clusters, target page assignments
+│   └── entities/      # brand, authors, topic hubs
+├── _meta/
+│   ├── index.md
+│   └── log.md
+└── WIKI.md
+```
+
+Frontmatter for `wiki/pages/` notes:
+```yaml
+---
+type: page
+url: "https://example.com/page-slug"
+status: live          # live | redirect | 404 | stub | no-index
+title: ""
+h1: ""
+meta_description: ""
+word_count: 0
+has_schema: false
+indexed: true
+canonical: ""
+internal_links_in: 0
+internal_links_out: 0
+last_crawled: YYYY-MM-DD
+tags: [page]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Key wiki pages to create: `[[Site Overview]]`, `[[Navigation Structure]]`, `[[Content Gaps]]`, `[[Redirect Map]]`, `[[Keyword Clusters]]`
+
+---
+
+## Mode B: GitHub / Repository
+
+Use when: "map my codebase", "architecture wiki for my repo", "understand this project"
+
+```
+vault/
+├── .raw/              # README, git log exports, code dumps, issue exports
+├── wiki/
+│   ├── modules/       # one note per major module / package / service
+│   ├── components/    # reusable UI or functional components
+│   ├── decisions/     # Architecture Decision Records (ADRs)
+│   ├── dependencies/  # external deps, versions, risk assessment
+│   └── flows/         # data flows, request paths, auth flows
+├── _meta/
+│   ├── index.md
+│   └── log.md
+└── WIKI.md
+```
+
+Frontmatter for `wiki/modules/` notes:
+```yaml
+---
+type: module           # module | component | decision | dependency | flow
+path: "src/auth/"
+status: active         # active | deprecated | experimental | planned
+language: typescript
+purpose: ""
+maintainer: ""
+last_updated: YYYY-MM-DD
+linked_issues: []
+depends_on: []
+used_by: []
+tags: [module]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Key wiki pages to create: `[[Architecture Overview]]`, `[[Data Flow]]`, `[[Tech Stack]]`, `[[Dependency Graph]]`, `[[Key Decisions]]`
+
+---
+
+## Mode C: Business / Project
+
+Use when: "project wiki", "competitive intelligence", "team knowledge base", "meeting notes"
+
+```
+vault/
+├── .raw/              # meeting transcripts, Slack exports, docs, emails
+├── wiki/
+│   ├── stakeholders/  # people, companies, decision-makers
+│   ├── decisions/     # key decisions with rationale and date
+│   ├── deliverables/  # milestones, outputs, status tracking
+│   ├── intel/         # competitor analysis, market research
+│   └── comms/         # synthesized meeting notes, key threads
+├── _meta/
+│   ├── index.md
+│   └── log.md
+└── WIKI.md
+```
+
+Frontmatter for `wiki/decisions/` notes:
+```yaml
+---
+type: decision         # stakeholder | decision | deliverable | intel | meeting | competitor
+status: active         # active | pending | done | blocked | superseded
+priority: 3            # 1 (highest) to 5 (lowest)
+date: YYYY-MM-DD
+owner: ""
+due_date: ""
+context: ""
+tags: [decision]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Key wiki pages to create: `[[Project Overview]]`, `[[Stakeholder Map]]`, `[[Decision Log]]`, `[[Competitor Landscape]]`
+
+---
+
+## Mode D: Personal / Second Brain
+
+Use when: "personal second brain", "track my goals", "journal synthesis", "life wiki"
+
+```
+vault/
+├── .raw/              # journal entries, articles, podcast notes, voice transcripts
+├── wiki/
+│   ├── goals/         # personal and professional goals with progress tracking
+│   ├── learning/      # concepts being mastered, skill development
+│   ├── people/        # relationships, shared context, follow-ups
+│   ├── areas/         # life areas: health, finances, career, creative
+│   └── resources/     # books, courses, tools worth referencing
+├── _meta/
+│   ├── index.md
+│   ├── log.md
+│   └── hot-cache.md   # ~500-word summary of most active context
+└── WIKI.md
+```
+
+Frontmatter for `wiki/goals/` notes:
+```yaml
+---
+type: goal             # goal | concept | person | area | resource | reflection
+status: active         # active | paused | completed | abandoned
+area: career           # health | career | finance | creative | relationships | growth
+priority: 1
+target_date: YYYY-MM-DD
+progress: 0            # 0-100 percent
+tags: [goal]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Hot cache note: `_meta/hot-cache.md` is a ~500-word file pi updates at the end of each session. It captures current focus areas, recent wins, and open threads. This prevents pi from having to crawl the whole wiki to answer "where were we?".
+
+Key wiki pages to create: `[[North Star]]`, `[[Weekly Review Template]]`, `[[Annual Goals]]`
+
+---
+
+## Mode E: Research
+
+Use when: "research wiki on [topic]", "track papers I'm reading", "build a thesis"
+
+```
+vault/
+├── .raw/              # PDFs, web clips, data files, raw notes
+├── wiki/
+│   ├── papers/        # paper summaries with key claims and methodology
+│   ├── concepts/      # extracted concepts, models, frameworks
+│   ├── entities/      # people, organizations, methods, datasets
+│   ├── thesis/        # evolving synthesis: the "state of the field" pages
+│   └── gaps/          # open questions, contradictions, research needed
+├── _meta/
+│   ├── index.md
+│   └── log.md
+└── WIKI.md
+```
+
+Frontmatter for `wiki/papers/` notes:
+```yaml
+---
+type: paper            # paper | concept | entity | thesis | gap
+status: summarized     # raw | summarized | synthesized | superseded
+year: 2024
+authors: []
+venue: ""
+key_claim: ""
+methodology: ""
+contradicts: []
+supports: []
+tags: [paper]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Key wiki pages to create: `[[Research Overview]]`, `[[Key Claims Map]]`, `[[Open Questions]]`, `[[Methodology Comparison]]`
+
+---
+
+## Mode F: Book / Course
+
+Use when: "companion wiki for a book", "course notes wiki", "as I read [title]"
+
+```
+vault/
+├── .raw/              # chapter notes, highlights, exercises
+├── wiki/
+│   ├── characters/    # characters, personas, agents, experts (adapt to content)
+│   ├── themes/        # major themes with supporting evidence
+│   ├── concepts/      # domain-specific terms and frameworks
+│   ├── timeline/      # plot structure, curriculum sequence, chapter map
+│   └── synthesis/     # your own takeaways, questions, applications
+├── _meta/
+│   ├── index.md
+│   └── log.md
+└── WIKI.md
+```
+
+Frontmatter for `wiki/concepts/` notes:
+```yaml
+---
+type: concept          # concept | character | theme | chapter | synthesis
+status: developing     # stub | developing | mature
+source_chapters: []
+first_appearance: ""
+tags: [concept]
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Key wiki pages to create: `[[Book Overview]]`, `[[Theme Map]]`, `[[Character / Expert Index]]`, `[[My Takeaways]]`
+
+---
+
+## Combining Modes
+
+You can combine modes. Examples:
+
+- "GitHub repo + research on the AI approach used" -> Mode B folders + Mode E papers/ folder
+- "My SaaS business + second brain" -> Mode C intel/ + Mode D goals/
+- "YouTube channel" -> Mode F (content as "book") + Mode E (research on topics covered)
+
+When combining, keep folder names distinct. Don't merge `decisions/` from Mode B and Mode C into one folder.

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

@@ -0,0 +1,96 @@
+# Obsidian Setup
+
+---
+
+## Install Obsidian
+
+### Linux (Flatpak: recommended)
+
+Check if installed:
+```bash
+flatpak list 2>/dev/null | grep -i obsidian && echo "FOUND via flatpak" || \
+which obsidian 2>/dev/null && echo "FOUND in PATH" || echo "NOT FOUND"
+```
+
+Install if not found:
+```bash
+flatpak install flathub md.obsidian.Obsidian
+```
+
+### macOS
+
+```bash
+ls /Applications/Obsidian.app 2>/dev/null && echo "FOUND" || brew install --cask obsidian
+```
+
+### Windows
+
+```powershell
+Test-Path "$env:LOCALAPPDATA\Obsidian" && echo "FOUND" || winget install Obsidian.Obsidian
+```
+
+### All platforms: direct download
+
+https://obsidian.md/download
+
+---
+
+## Open the Vault
+
+After installing: Obsidian > Manage Vaults > Open Folder as Vault > select your vault directory.
+
+---
+
+## Core Plugins (Built-in: No Install Required)
+
+These ship with Obsidian. Enable them in Settings > Core Plugins:
+
+| Plugin | Purpose |
+|--------|---------|
+| **Bases** | Native database-like views for `.base` files. Powers `wiki/meta/dashboard.base`. Available since Obsidian v1.9.10 (August 2025). **Replaces Dataview for most wiki use cases.** |
+| **Properties** | Visual frontmatter editor. Always enabled. |
+| **Backlinks** | Outgoing/incoming links pane. |
+| **Outline** | Document heading navigation. |
+
+## Recommended Community Plugins
+
+Install via Settings > Community Plugins > Turn off Restricted Mode > Browse.
+
+| Plugin | Purpose |
+|--------|---------|
+| **Templater** | Auto-populate frontmatter on note creation from `_templates/`. |
+| **Obsidian Git** | Auto-commit every 15 minutes. Protects against bad writes. |
+| **Calendar** | Right-sidebar calendar with word count, task, and link indicators. Pre-installed in this vault via `.obsidian/plugins/calendar/`. |
+| **Thino** | Quick memo capture panel in right sidebar. Pre-installed via `.obsidian/plugins/thino/`. |
+| **Iconize** | Visual folder icons for navigation. |
+| **Minimal Theme** | Best dark theme for dense information display. |
+| **Dataview** *(optional/legacy)* | Only needed if you're on Obsidian < 1.9.10 or want to use the legacy `dashboard.md` queries. The primary dashboard now uses Bases. |
+
+**Calendar and Thino are pre-installed**. They ship with this vault. Enable them in Settings → Community Plugins → toggle on. No download needed.
+
+If installing in a different vault: download `main.js` + `manifest.json` from their GitHub releases into `.obsidian/plugins/calendar/` and `.obsidian/plugins/thino/` respectively.
+
+Optional additions:
+- **Smart Connections**: semantic search across all notes
+- **QuickAdd**: macros for fast note creation
+- **Folder Notes**: click a folder to open an overview note
+
+---
+
+## Web Clipper
+
+The Obsidian Web Clipper browser extension converts web articles to markdown and sends them to `.raw/` in one click.
+
+Install for Chrome, Firefox, or Safari from the Obsidian website.
+
+Set the default folder to `.raw/` in the extension settings.
+
+---
+
+## After Installing Plugins
+
+1. Enable Bases: Settings > Core Plugins > toggle on (already on by default in Obsidian v1.9.10+)
+2. Enable Templater: Settings > Templater > set template folder to `_templates`
+3. Enable Obsidian Git: Settings > Obsidian Git > Auto backup interval: 15 minutes
+4. Enable the CSS snippet: Settings > Appearance > CSS Snippets > toggle on `vault-colors`
+5. *(Optional)* Enable Dataview only if you want the legacy `wiki/meta/dashboard.md` queries to work alongside the primary `dashboard.base`

package/.agents/skills/wiki/references/rest-api.md

@@ -0,0 +1,124 @@
+# REST API Quick Reference
+
+Use these commands when MCP tools are not available. Requires the Local REST API plugin running in Obsidian (port 27124).
+
+Set your key before running any command:
+```bash
+API="https://127.0.0.1:27124"
+KEY="your-api-key-here"
+```
+
+---
+
+## Read a file
+
+```bash
+curl -sk \
+  -H "Authorization: Bearer $KEY" \
+  "$API/vault/wiki/index.md"
+```
+
+---
+
+## Create or replace a file
+
+```bash
+curl -sk -X PUT \
+  -H "Authorization: Bearer $KEY" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @local-file.md \
+  "$API/vault/wiki/entities/Name.md"
+```
+
+Or with inline content:
+```bash
+curl -sk -X PUT \
+  -H "Authorization: Bearer $KEY" \
+  -H "Content-Type: text/markdown" \
+  --data "# Page Title
+
+Content here." \
+  "$API/vault/wiki/concepts/Name.md"
+```
+
+---
+
+## Append to a file
+
+```bash
+curl -sk -X POST \
+  -H "Authorization: Bearer $KEY" \
+  -H "Content-Type: text/markdown" \
+  --data "- New log entry" \
+  "$API/vault/wiki/log.md"
+```
+
+---
+
+## Patch a frontmatter field
+
+```bash
+curl -sk -X PATCH \
+  -H "Authorization: Bearer $KEY" \
+  -H "Operation: replace" \
+  -H "Target-Type: frontmatter" \
+  -H "Target: status" \
+  -H "Content-Type: application/json" \
+  --data '"mature"' \
+  "$API/vault/wiki/concepts/Name.md"
+```
+
+---
+
+## Append content under a heading
+
+```bash
+curl -sk -X PATCH \
+  -H "Authorization: Bearer $KEY" \
+  -H "Operation: append" \
+  -H "Target-Type: heading" \
+  -H "Target: Connections" \
+  -H "Content-Type: text/markdown" \
+  --data "- [[New Page]]" \
+  "$API/vault/wiki/entities/Name.md"
+```
+
+---
+
+## Search
+
+Simple keyword search:
+```bash
+curl -sk -X POST \
+  -H "Authorization: Bearer $KEY" \
+  "$API/search/simple/?query=machine+learning"
+```
+
+Dataview query:
+```bash
+curl -sk -X POST \
+  -H "Authorization: Bearer $KEY" \
+  -H "Content-Type: application/vnd.olrapi.dataview.dql+txt" \
+  --data 'TABLE status FROM "wiki" WHERE status = "seed"' \
+  "$API/search/"
+```
+
+---
+
+## List all tags
+
+```bash
+curl -sk \
+  -H "Authorization: Bearer $KEY" \
+  "$API/tags/"
+```
+
+---
+
+## List files in a folder
+
+```bash
+curl -sk \
+  -H "Authorization: Bearer $KEY" \
+  "$API/vault/wiki/entities/"
+```

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

@@ -0,0 +1,211 @@
+---
+name: wiki-autoresearch
+description: >
+  Autonomous iterative research loop. Takes a topic, runs web searches, fetches sources,
+  synthesizes findings, and files everything into the wiki as structured pages.
+  Based on Karpathy's autoresearch pattern: program.md configures objectives and constraints,
+  the loop runs until depth is reached, output goes directly into the knowledge base.
+  Triggers on: "/wiki-autoresearch", "/autoresearch", "wiki-autoresearch", "autoresearch",
+  "research [topic]", "deep dive into [topic]", "investigate [topic]",
+  "find everything about [topic]", "research and file", "go research", "build a wiki on".
+allowed-tools: Read Write Edit Glob Grep WebFetch WebSearch
+---
+
+# wiki-autoresearch: Autonomous Research Loop
+
+You are a research agent. You take a topic, run iterative web searches, synthesize findings, and file everything into the wiki. The user gets wiki pages, not a chat response.
+
+This is based on Karpathy's autoresearch pattern: a configurable program defines your objectives. You run the loop until depth is reached. Output goes into the knowledge base.
+
+---
+
+## 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="${WIKI_VAULT_PATH:-${VAULT_WIKI_PATH:-vault/wiki}}"
+```
+
+Use `$WIKI_PATH/` as the prefix for all `wiki/...` file paths. Example: `wiki/sources/` → `$WIKI_PATH/sources/` (default: `vault/wiki/sources/`).
+
+---
+
+## Before Starting
+
+Read `references/program.md` to load the research objectives and constraints. This file is user-configurable. It defines what sources to prefer, how to score confidence, and any domain-specific constraints.
+
+---
+
+## Topic Selection
+
+Two paths to a topic. Follow the first one that applies.
+
+### A. Explicit topic (always respected)
+
+The topic is whatever the user said after the trigger phrase. Extract it by removing the trigger from the user's message.
+
+**How to extract:**
+- User: `/autoresearch kubernetes operators` → topic: `kubernetes operators`
+- User: `/wiki-autoresearch Rust async patterns` → topic: `Rust async patterns`
+- User: `research the current state of WASM` → topic: `the current state of WASM`
+- User: `deep dive into transformers vs diffusers` → topic: `transformers vs diffusers`
+- User: `investigate Postgres query planning` → topic: `Postgres query planning`
+- User: `find everything about eBPF` → topic: `eBPF`
+- User: `build a wiki on Zig allocators` → topic: `Zig allocators`
+
+**Rule**: strip the trigger phrase (`/autoresearch`, `/wiki-autoresearch`, `research`, `deep dive into`, `investigate`, `find everything about`, `go research`, `research and file`, `build a wiki on`), trim whitespace, and treat everything remaining as the topic. Use it verbatim.
+
+If the topic is present, skip to the Research Loop. Do NOT ask "what topic."
+
+### B. No topic given (fallback)
+When the user invokes `/autoresearch`, `/wiki-autoresearch`, `go research`, or `research and file` with NO topic after the trigger, ask: "What topic should I research?"
+
+---
+
+## Research Loop
+
+```
+Input: topic (from Topic Selection, above)
+
+Round 1. Broad search
+1. Decompose topic into 3-5 distinct search angles
+2. For each angle: run 2-3 WebSearch queries
+3. For top 2-3 results per angle: WebFetch the page
+4. Extract from each: key claims, entities, concepts, open questions
+
+Round 2. Gap fill
+5. Identify what's missing or contradicted from Round 1
+6. Run targeted searches for each gap (max 5 queries)
+7. Fetch top results for each gap
+
+Round 3. Synthesis check (optional, if gaps remain)
+8. If major contradictions or missing pieces still exist: one more targeted pass
+9. Otherwise: proceed to filing
+
+Max rounds: 3 (as set in program.md). Stop when depth is reached or max rounds hit.
+```
+
+---
+
+## Filing Results
+
+After research is complete, create these pages:
+
+**wiki/sources/**. One page per major reference found
+- Use source frontmatter (type, source_type, author, date_published, url, confidence, key_claims)
+- Body: summary of the source, what it contributes to the topic
+
+**wiki/concepts/**. One page per significant concept extracted
+- Only create a page if the concept is substantive enough to stand alone
+- Check the index first: update existing concept pages rather than creating duplicates
+
+**wiki/entities/**. One page per significant person, org, or product identified
+- Check the index first: update existing entity pages
+
+**wiki/questions/**. One synthesis page titled "Research: [Topic]"
+- This is the master synthesis. Everything comes together here.
+- Sections: Overview, Key Findings, Entities, Concepts, Contradictions, Open Questions, Sources
+- Full frontmatter with related links to all pages created in this session
+
+---
+
+## Synthesis Page Structure
+
+```markdown
+---
+type: synthesis
+title: "Research: [Topic]"
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags:
+  - research
+  - [topic-tag]
+status: developing
+related:
+  - "[[Every page created in this session]]"
+sources:
+  - "[[wiki/sources/Source 1]]"
+  - "[[wiki/sources/Source 2]]"
+---
+
+# Research: [Topic]
+
+## Overview
+[2-3 sentence summary of what was found]
+
+## Key Findings
+- Finding 1 (Source: [[Source Page]])
+- Finding 2 (Source: [[Source Page]])
+- ...
+
+## Key Entities
+- [[Entity Name]]: role/significance
+
+## Key Concepts
+- [[Concept Name]]: one-line definition
+
+## Contradictions
+- [[Source A]] says X. [[Source B]] says Y. [Brief note on which is more credible and why]
+
+## Open Questions
+- [Question that research didn't fully answer]
+- [Gap that needs more sources]
+
+## Sources
+- [[Source 1]]: author, date
+- [[Source 2]]: author, date
+```
+
+---
+
+## After Filing
+
+1. Update `wiki/index.md`. Add all new pages to the right sections
+2. Append to `wiki/log.md` (at the TOP):
+   ```
+   ## [YYYY-MM-DD] wiki-autoresearch | [Topic]
+   - Rounds: N
+   - Sources found: N
+   - Pages created: [[Page 1]], [[Page 2]], ...
+   - Synthesis: [[Research: Topic]]
+   - Key finding: [one sentence]
+   ```
+3. Update `wiki/hot.md` with the research summary
+
+---
+
+## Report to User
+
+After filing everything:
+
+```
+wiki-autoresearch complete: [Topic]
+
+Rounds: N | Searches: N | Pages created: N
+
+Created:
+  wiki/questions/Research: [Topic].md (synthesis)
+  wiki/sources/[Source 1].md
+  wiki/concepts/[Concept 1].md
+  wiki/entities/[Entity 1].md
+
+Key findings:
+- [Finding 1]
+- [Finding 2]
+- [Finding 3]
+
+Open questions filed: N
+```
+
+---
+
+## Constraints
+
+Follow the limits in `references/program.md`:
+- Max rounds (default: 3)
+- Max pages per session (default: 15)
+- Confidence scoring rules
+- Source preference rules
+
+If a constraint conflicts with completeness, respect the constraint and note what was left out in the Open Questions section.