pi-para 0.5.2

package/scripts/gepa/wiki_reader.py

@@ -0,0 +1,113 @@
+"""Read wiki pages from disk for training data.
+
+Parses YAML frontmatter + markdown body from ~/.pi/wiki/{category}/{slug}.md.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+PARA_CATEGORIES = ("projects", "areas", "resources", "archives")
+
+
+@dataclass
+class WikiPage:
+    """A parsed wiki page."""
+    category: str
+    slug: str
+    title: str
+    scope: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    links: list[str] = field(default_factory=list)
+    body: str = ""
+    created: str = ""
+    updated: str = ""
+
+    @property
+    def path(self) -> str:
+        return f"{self.category}/{self.slug}"
+
+
+def parse_page(filepath: str) -> WikiPage | None:
+    """Parse a wiki markdown file into a WikiPage."""
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            content = f.read()
+    except (IOError, OSError):
+        return None
+
+    # Split frontmatter from body
+    fm_match = re.match(r"^---\s*\n(.*?\n)---\s*\n(.*)", content, re.DOTALL)
+    if not fm_match:
+        return None
+
+    try:
+        fm = yaml.safe_load(fm_match.group(1))
+    except yaml.YAMLError:
+        return None
+
+    if not isinstance(fm, dict):
+        return None
+
+    body = fm_match.group(2).strip()
+    path = Path(filepath)
+    slug = path.stem
+    category = path.parent.name
+
+    return WikiPage(
+        category=category,
+        slug=slug,
+        title=fm.get("title", slug),
+        scope=fm.get("scope", []) or [],
+        tags=fm.get("tags", []) or [],
+        links=fm.get("links", []) or [],
+        body=body,
+        created=str(fm.get("created", "")),
+        updated=str(fm.get("updated", "")),
+    )
+
+
+def load_all_pages(wiki_dir: str) -> list[WikiPage]:
+    """Load all wiki pages from disk."""
+    pages = []
+    for cat in PARA_CATEGORIES:
+        cat_dir = os.path.join(wiki_dir, cat)
+        if not os.path.isdir(cat_dir):
+            continue
+        for fname in sorted(os.listdir(cat_dir)):
+            if not fname.endswith(".md"):
+                continue
+            page = parse_page(os.path.join(cat_dir, fname))
+            if page:
+                pages.append(page)
+    return pages
+
+
+def get_wiki_stats(wiki_dir: str) -> dict:
+    """Get summary stats about the wiki."""
+    pages = load_all_pages(wiki_dir)
+    cat_counts = {}
+    all_scopes = set()
+    all_tags = set()
+    total_links = 0
+
+    for p in pages:
+        cat_counts[p.category] = cat_counts.get(p.category, 0) + 1
+        all_scopes.update(p.scope)
+        all_tags.update(p.tags)
+        total_links += len(p.links)
+
+    return {
+        "total_pages": len(pages),
+        "categories": cat_counts,
+        "unique_scopes": sorted(all_scopes),
+        "unique_tags": sorted(all_tags)[:20],  # top 20
+        "total_links": total_links,
+        "avg_links_per_page": round(total_links / max(len(pages), 1), 1),
+    }

package/skills/para/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: para
+description: Active PARA knowledge management during work. Consult wiki before planning, write decisions as they happen, search for past solutions when debugging, check conventions when reviewing. Use when starting any task, making architecture decisions, debugging problems, or reviewing code.
+---
+
+# PARA Active Knowledge
+
+Behavioral guidelines for actively using the PARA wiki during work — not just passively capturing at session end.
+
+**The shift**: Wiki isn't just a record. It's a working tool. Consult it before acting. Write to it while acting.
+
+## 1. PARA Categories — Know What Goes Where
+
+**Most things are resources. Projects and areas are special.**
+
+| Category | What it is | When to create/update |
+|----------|-----------|----------------------|
+| **resources/** | Reference material — architecture docs, debugging solutions, patterns, configs, how-tos | Default for almost everything. When you learn something, it's probably a resource. |
+| **projects/** | A discrete goal with an **end condition** — "Ship feature X by date Y" | When the user defines a goal with a finish line. Update status as milestones are hit. Move to archives when done. |
+| **areas/** | An ongoing responsibility with **quality standards** — "Keep wiki healthy", "Monitor prod uptime" | When there's a repeating responsibility that never "finishes". Update with current health/status. |
+| **archives/** | Completed or inactive items | Don't create here. Move finished projects here via `wiki_move`. |
+
+Common mistake: putting architecture docs about a project into `projects/`. A page like "pi-para daemon architecture" is a **resource** about pi-para, not a project.
+
+## 2. Before You Start — Consult
+
+**Don't plan from scratch. Check what's already known.**
+
+Before starting any non-trivial task:
+- `wiki_query` for the topic, feature area, or technology involved
+- Read any relevant pages (architecture decisions, past debugging, conventions)
+- Check for existing patterns that should be followed or pitfalls to avoid
+- If the wiki has a `projects/` page for this work, read it for goals and constraints
+
+Skip this for trivial tasks (typo fix, single-line change). Use judgment.
+
+## 3. During Work — Write As You Go
+
+**Don't wait for session end. Capture decisions when they're fresh.**
+
+Write to the wiki immediately when you:
+- Make an architecture or design decision ("chose X over Y because Z")
+- Discover a non-obvious gotcha or constraint
+- Solve a debugging problem (root cause + fix)
+- Learn how a system actually works (vs. how you assumed)
+- Establish a convention or pattern others should follow
+
+Use `wiki_write(mode: 'edit')` for surgical updates to existing pages. Use `wiki_write(mode: 'append')` to add new sections. Don't defer — context and reasoning degrade with time.
+
+## 4. When Debugging — Search First
+
+**Someone may have solved this before.**
+
+Before deep-diving into a bug:
+- `wiki_query` for the error message, component name, or symptom
+- Check for past debugging pages that describe similar root causes
+- Look for operational knowledge (config paths, service dependencies, known failure modes)
+
+After solving:
+- Write the root cause + fix to the wiki immediately
+- Include the exact error message (makes future searches find it)
+
+## 5. When Reviewing — Check Conventions
+
+**The wiki holds the team's agreed patterns.**
+
+When reviewing or writing code that touches architecture:
+- `wiki_query` for conventions in the relevant area
+- Check existing architecture decision pages before proposing new approaches
+- If you're contradicting an existing decision, note why in the wiki (update the page, don't just ignore it)
+
+## 6. What Not To Do
+
+- Don't dump every thought into the wiki — capture knowledge, not noise
+- Don't create new pages when an existing page covers the topic — update it
+- Don't skip the search step — duplicate pages degrade the wiki
+- Don't include secrets — document WHERE keys are stored, not the values

package/skills/setup/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: setup
+description: Set up pi-para PARA knowledge base extension. Installs qmd search engine, configures providers, starts background capture daemon. Use when user asks to install, set up, or configure pi-para wiki.
+---
+
+# pi-para Setup
+
+Read and follow the instructions in `SETUP.md` at the root of the pi-para package.
+
+The setup file is at: `{{skill_dir}}/../../SETUP.md`
+
+Steps:
+1. `pi install @picassio/pi-para` (extension)
+2. `npm install -g @picassio/qmd` (search engine)
+3. Configure `~/.config/qmd/index.yml` (providers)
+4. Set `daemonModel` in `~/.pi/wiki/config.json` (daemon LLM)
+5. Start systemd daemon service
+6. Verify with `/wiki-settings`
+
+Ask the user for their API keys if needed. Check what's already installed before re-installing.