ultimate-pi 0.1.7 → 0.2.2

package/.agents/skills/wiki-fold/references/fold-template.md

@@ -1,133 +0,0 @@
-# Fold Page Template
-
-Canonical output format for `wiki-fold`. Every fold page uses this layout exactly.
-
----
-
-## Frontmatter
-
-```yaml
----
-type: fold
-title: "Fold k{K} — {EARLIEST-DATE} to {LATEST-DATE} — n{COUNT}"
-fold_id: "fold-k{K}-from-{EARLIEST-DATE}-to-{LATEST-DATE}-n{COUNT}"
-batch_exponent: {K}
-entry_count: {COUNT}
-entry_range:
-  from: "{EARLIEST-CHILD-DATE}"
-  to: "{LATEST-CHILD-DATE}"
-created: "{YYYY-MM-DD}"
-updated: "{YYYY-MM-DD}"
-tags:
-  - meta
-  - fold
-  - "fold/k{K}"
-status: mature
-children:
-  - date: "{YYYY-MM-DD}"
-    op: "{save|ingest|fold|session|setup|decision}"
-    title: "{log entry title verbatim}"
-    page: "[[{canonical page wikilink}]]"
-    page_missing: false
-  # ... one record per log entry. No dedupe by page.
-related:
-  - "[[DragonScale Memory]]"
-  - "[[log]]"
-  - "[[index]]"
----
-```
-
-All fields are required. Missing any field is a dry-run failure. `title` does not contain the current date. `fold_id` is deterministic and matches the filename.
-
----
-
-## Body Sections (in order, all required)
-
-### 1. Scope (one paragraph)
-
-```markdown
-Level-{K} fold of {COUNT} log entries spanning {FROM} to {TO}. Dominant themes: {THEME-1}, {THEME-2}, {THEME-3}.
-```
-
-### 2. Child Entries
-
-One row per log entry. Row count must equal `entry_count` in frontmatter and the length of `children:`.
-
-```markdown
-## Child Entries
-
-| Date | Op | Title | Page | Summary (extractive) |
-|---|---|---|---|---|
-| 2026-04-23 | save | DragonScale Memory v0.2 — post-adversarial-review | [[DragonScale Memory]] | Adversarial-review rewrite; 7/7 critiques accepted after one surgical fix. |
-| 2026-04-15 | save | Claude SEO v1.9.0 Slides and GitHub Release | [[2026-04-15-slides-and-release-session]] | 15-slide HTML deck, v1.9.0 tagged, GitHub release with PDF asset. |
-<!-- one row per log entry; no dedupe by page -->
-```
-
-The Summary column is extractive: one sentence paraphrased from the log entry's bullets. If the source is ambiguous, write "ambiguous in source" rather than guessing.
-
-### 3. Key Outcomes (3-7 bullets, extractive)
-
-Every bullet must cite the specific child entry (by date) it draws from. Every numeric value must be grep-verifiable against that child entry. Count-check before emitting.
-
-```markdown
-## Key Outcomes
-
-- {CONCRETE CHANGE 1, quoting or paraphrasing a child entry} (from 2026-04-14 session entry)
-- {CONCRETE CHANGE 2, with numeric grep-verified against source} (from 2026-04-10 session entry)
-<!-- max 7 bullets. Each bullet names a concrete artifact or decision AND cites its source entry. -->
-```
-
-### 4. Cross-entry Themes (0-4 bullets, must name contributing entries)
-
-Themes are optional. If a theme cannot be supported by naming at least two child entries that contribute to it, do not write it.
-
-```markdown
-## Cross-entry Themes
-
-- {THEME: describes a pattern supported by multiple entries} (supported by: 2026-04-14, 2026-04-15, 2026-04-23 entries)
-```
-
-Do not invent a theme to justify the fold. If no cross-entry patterns are present, write "No cross-entry themes identified; entries are independent within this range."
-
-### 5. Contradictions or Corrections
-
-```markdown
-## Contradictions or Corrections
-
-- None detected.
-```
-
-Or, if present:
-
-```markdown
-## Contradictions or Corrections
-
-- [[Earlier Entry]] claimed X; [[Later Entry]] corrected to Y. Resolution: {STATUS}.
-```
-
-### 6. Links
-
-The `Child Pages` section is **deduped by page**: one wikilink per unique target page, even if multiple log entries point at it. This is the graph-connection section, different from frontmatter `children:` which is **per log entry** (no dedupe).
-
-```markdown
-## Child Pages
-
-- [[{UNIQUE-PAGE-1}]]
-- [[{UNIQUE-PAGE-2}]]
-<!-- dedupe by page; see frontmatter `children:` for per-entry records -->
-
-## Related
-
-- [[DragonScale Memory]] - fold-operator spec
-- [[log]] - source entries
-- [[index]] - vault catalog
-```
-
----
-
-## Notes
-
-- No hot-cache update: that is the save/ingest skill's responsibility.
-- No edits to child pages. Folds are strictly read-only with respect to children.
-- If a child entry's referenced pages are missing, note "source missing" in the Summary column rather than fabricating content.
-- The body is terse. A fold is a rollup, not a retelling. Target 200-400 lines total for a k=4 fold.

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

@@ -1,288 +0,0 @@
----
-name: wiki-ingest
-description: "Ingest sources into the Obsidian wiki vault. Reads a source, extracts entities and concepts, creates or updates wiki pages, cross-references, and logs the operation. Supports files, URLs, and batch mode. Triggers on: ingest, process this source, add this to the wiki, read and file this, batch ingest, ingest all of these, ingest this url."
----
-
-# wiki-ingest: Source Ingestion
-
-Read the source. Write the wiki. Cross-reference everything. A single source typically touches 8-15 wiki pages.
-
-**Syntax standard**: Write all Obsidian Markdown using proper Obsidian Flavored Markdown. Wikilinks as `[[Note Name]]`, callouts as `> [!type] Title`, embeds as `![[file]]`, properties as YAML frontmatter. If the kepano/obsidian-skills plugin is installed, prefer its canonical obsidian-markdown skill for Obsidian syntax reference. Otherwise, follow the guidance in this skill.
-
----
-
-## 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`).
-
----
-
-## Delta Tracking
-
-Before ingesting any file, check `.raw/.manifest.json` to avoid re-processing unchanged sources.
-
-```bash
-# Check if manifest exists
-[ -f .raw/.manifest.json ] && echo "exists" || echo "no manifest yet"
-```
-
-**Manifest format** (create if missing):
-```json
-{
-  "sources": {
-    ".raw/articles/article-slug-2026-04-08.md": {
-      "hash": "abc123",
-      "ingested_at": "2026-04-08",
-      "pages_created": ["wiki/sources/article-slug.md", "wiki/entities/Person.md"],
-      "pages_updated": ["wiki/index.md"]
-    }
-  }
-}
-```
-
-**Before ingesting a file:**
-1. Compute a hash: `md5sum [file] | cut -d' ' -f1` (or `sha256sum` on Linux).
-2. Check if the path exists in `.manifest.json` with the same hash.
-3. If hash matches, skip. Report: "Already ingested (unchanged). Use `force` to re-ingest."
-4. If missing or hash differs, proceed with ingest.
-
-**After ingesting a file:**
-1. Record `{hash, ingested_at, pages_created, pages_updated}` in `.manifest.json`.
-2. Write the updated manifest back.
-
-Skip delta checking if the user says "force ingest" or "re-ingest".
-
----
-
-## URL Ingestion
-
-Trigger: user passes a URL starting with `https://`.
-
-Steps:
-
-1. **Fetch** the page using WebFetch.
-2. **Clean** (optional): if `defuddle` is available (`which defuddle 2>/dev/null`), run `defuddle [url]` to strip ads, nav, and clutter. Typically saves 40-60% tokens. Fall back to raw WebFetch output if not installed.
-3. **Derive slug** from the URL path (last segment, lowercased, spaces→hyphens, strip query strings).
-4. **Save** to `.raw/articles/[slug]-[YYYY-MM-DD].md` with a frontmatter header:
-   ```markdown
-   ---
-   source_url: [url]
-   fetched: [YYYY-MM-DD]
-   ---
-   ```
-5. Proceed with **Single Source Ingest** starting at step 2 (file is now in `.raw/`).
-
----
-
-## Image / Vision Ingestion
-
-Trigger: user passes an image file path (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.avif`).
-
-Steps:
-
-1. **Read** the image file using the Read tool. pi can process images natively.
-2. **Describe** the image contents: extract all text (OCR), identify key concepts, entities, diagrams, and data visible in the image.
-3. **Save** the description to `.raw/images/[slug]-[YYYY-MM-DD].md`:
-   ```markdown
-   ---
-   source_type: image
-   original_file: [original path]
-   fetched: YYYY-MM-DD
-   ---
-   # Image: [slug]
-
-   [Full description of image contents, transcribed text, entities visible, etc.]
-   ```
-4. Copy the image to `_attachments/images/[slug].[ext]` if it's not already in the vault.
-5. Proceed with **Single Source Ingest** on the saved description file.
-
-Use cases: whiteboard photos, screenshots, diagrams, infographics, document scans.
-
----
-
-## Single Source Ingest
-
-Trigger: user drops a file into `.raw/` or pastes content.
-
-Steps:
-
-1. **Read** the source completely. Do not skim.
-2. **Discuss** key takeaways with the user. Ask: "What should I emphasize? How granular?" Skip this if the user says "just ingest it."
-3. **Create** source summary in `wiki/sources/`. Use the source frontmatter schema from `references/frontmatter.md`. Assign an address per the **Address Assignment** section below.
-4. **Create or update** entity pages for every person, org, product, and repo mentioned. One page per entity. Assign addresses to new entity pages.
-5. **Create or update** concept pages for significant ideas and frameworks. Assign addresses to new concept pages.
-6. **Update** relevant domain page(s) and their `_index.md` sub-indexes.
-7. **Update** `wiki/overview.md` if the big picture changed.
-8. **Update** `wiki/index.md`. Add entries for all new pages.
-9. **Update** `wiki/hot.md` with this ingest's context.
-10. **Append** to `wiki/log.md` (new entries at the TOP):
-    ```markdown
-    ## [YYYY-MM-DD] ingest | Source Title
-    - Source: `.raw/articles/filename.md`
-    - Summary: [[Source Title]]
-    - Pages created: [[Page 1]], [[Page 2]]
-    - Pages updated: [[Page 3]], [[Page 4]]
-    - Key insight: One sentence on what is new.
-    ```
-11. **Check for contradictions.** If new info conflicts with existing pages, add `> [!contradiction]` callouts on both pages.
-
----
-
-## Batch Ingest
-
-Trigger: user drops multiple files or says "ingest all of these."
-
-Steps:
-
-1. List all files to process. Confirm with user before starting.
-2. Process each source following the single ingest flow. Defer cross-referencing between sources until step 3.
-3. After all sources: do a cross-reference pass. Look for connections between the newly ingested sources.
-4. Update index, hot cache, and log once at the end (not per-source).
-5. Report: "Processed N sources. Created X pages, updated Y pages. Here are the key connections I found."
-
-Batch ingest is less interactive. For 30+ sources, expect significant processing time. Check in with the user after every 10 sources.
-
----
-
-## Context Window Discipline
-
-Token budget matters. Follow these rules during ingest:
-
-- Read `wiki/hot.md` first. If it contains the relevant context, don't re-read full pages.
-- Read `wiki/index.md` to find existing pages before creating new ones.
-- Read only 3-5 existing pages per ingest. If you need 10+, you are reading too broadly.
-- Use PATCH for surgical edits. Never re-read an entire file just to update one field.
-- Keep wiki pages short. 100-300 lines max. If a page grows beyond 300 lines, split it.
-- Use search (`/search/simple/`) to find specific content without reading full pages.
-
----
-
-## Contradictions
-
-> [!note] Custom callout dependency
-> The `[!contradiction]` callout type used below is a **custom callout** defined in `.obsidian/snippets/vault-colors.css` (auto-installed by `/wiki` scaffold). It renders with reddish-brown styling and an alert-triangle icon when the snippet is enabled. If the snippet is missing, Obsidian falls back to default callout styling, so the page still works without the visual flourish. See [[skills/wiki/references/css-snippets.md]] for the four custom callouts (`contradiction`, `gap`, `key-insight`, `stale`).
-
-When new info contradicts an existing wiki page:
-
-On the existing page, add:
-```markdown
-> [!contradiction] Conflict with [[New Source]]
-> [[Existing Page]] claims X. [[New Source]] says Y.
-> Needs resolution. Check dates, context, and primary sources.
-```
-
-On the new source summary, reference it:
-```markdown
-> [!contradiction] Contradicts [[Existing Page]]
-> This source says Y, but existing wiki says X. See [[Existing Page]] for details.
-```
-
-Do not silently overwrite old claims. Flag and let the user decide.
-
----
-
-## What Not to Do
-
-- **Source files under `.raw/` are immutable.** Do not modify the files that users drop there (articles, transcripts, images). The `.raw/.manifest.json` delta tracker and its `address_map` (DragonScale Mechanism 2) are the only files under `.raw/` that `wiki-ingest` itself maintains. Treat every other file under `.raw/` as read-only source content.
-- Do not create duplicate pages. Always check the index and search before creating.
-- Do not skip the log entry. Every ingest must be recorded.
-- Do not skip the hot cache update. It is what keeps future sessions fast.
-
----
-
-## Address Assignment (DragonScale Mechanism 2 MVP)
-
-**Opt-in feature**. DragonScale address assignment runs only if `scripts/allocate-address.sh` is present AND `.vault-meta/` exists. Otherwise, skip this entire section and proceed with ingest normally.
-
-**Feature detection (run at start of every ingest)**:
-
-```bash
-if [ -x ./scripts/allocate-address.sh ] && [ -d ./.vault-meta ]; then
-  DRAGONSCALE_ADDRESSES=1
-else
-  DRAGONSCALE_ADDRESSES=0
-fi
-```
-
-When `DRAGONSCALE_ADDRESSES=0`, pages are created without an `address:` frontmatter field, and `wiki-lint`'s Address Validation section is skipped entirely (missing addresses are not flagged in any severity). This preserves default plugin behavior for vaults that have not adopted DragonScale.
-
-When `DRAGONSCALE_ADDRESSES=1`, proceed with the rest of this section.
-
----
-
-Every **newly created non-meta wiki page** gets a stable address in its frontmatter:
-
-```yaml
-address: c-000042
-```
-
-Format: `c-<6-digit-counter>`. The `c-` prefix stands for "creation-order counter." Zero-padded.
-
-Rollout baseline: **2026-04-23** (Phase 2 ship date). Pages with `created:` >= this date are post-rollout and MUST have an address (unless excluded below). Pages with `created:` earlier are legacy-exempt until a deliberate backfill pass assigns `l-NNNNNN` addresses.
-
-### Required tool: `scripts/allocate-address.sh`
-
-Address allocation is delegated to an atomic Bash helper. The helper uses `flock` on `.vault-meta/.address.lock` to prevent read-use-increment races and recovers the counter by scanning existing frontmatter if the counter file is missing.
-
-```bash
-ADDR=$(./scripts/allocate-address.sh)
-# ADDR is now e.g. "c-000042"; counter is already incremented
-```
-
-**CRITICAL**: never use the Write or Edit tool on `.vault-meta/address-counter.txt`. That would fire the PostToolUse hook, which runs `git add $WIKI_PATH/ .raw/` and can accidentally commit unrelated pending wiki changes under a generic message. Counter mutation is **only** permitted through the helper script (Bash tool).
-
-### Helper modes
-
-- `./scripts/allocate-address.sh` — atomically reserves and returns the next address.
-- `./scripts/allocate-address.sh --peek` — prints the next value without reserving (safe, read-only).
-- `./scripts/allocate-address.sh --rebuild` — recomputes the counter from the highest observed `c-NNNNNN` in existing frontmatter. Never resets to 1 silently if pages already have addresses. Run this if the counter file is suspected corrupt.
-
-### Assignment procedure (per new page)
-
-1. Before writing a new non-meta page, call `./scripts/allocate-address.sh` and capture the output.
-2. Include `address: c-XXXXXX` in the page's frontmatter.
-3. Record the path-to-address mapping in `.raw/.manifest.json` under a new top-level key `address_map` (see schema below).
-
-### `address_map` in `.raw/.manifest.json`
-
-```json
-{
-  "sources": { ... },
-  "address_map": {
-    "wiki/concepts/Example.md": "c-000042",
-    "wiki/entities/Another.md": "c-000043"
-  }
-}
-```
-
-On re-ingest of the same source (whether by `--force` or a changed hash), always consult `address_map` first. If the target page path has a prior address, REUSE it. Do not allocate a new one.
-
-On a page rename, the skill must update the `address_map` key (old path -> new path) while preserving the address value.
-
-### Exclusions (do NOT assign an address to)
-
-- Meta files: `_index.md`, `index.md`, `log.md`, `hot.md`, `overview.md`, `dashboard.md`, `dashboard.base`, `Wiki Map.md`, `getting-started.md`.
-- Fold pages under `wiki/folds/` (they use their own deterministic `fold_id`).
-- Pre-rollout legacy pages (`created:` < 2026-04-23). Legacy pages get `l-NNNNNN` addresses only via a deliberate backfill operation.
-
-### Idempotency rules
-
-- If a page being (re)written already has an `address:` field in its current content, REUSE it. Do not allocate a new one.
-- If a source is re-ingested and `address_map` has a mapping for the target path, reuse that mapping.
-- If the source has been ingested before AND the target page has no address AND the page `created:` date is post-rollout, allocate an address and record it. This covers the case where an older ingest produced a page before Phase 2 rollout; the rollout cutoff still applies (pages dated pre-2026-04-23 stay legacy).
-
-### Concurrency policy
-
-- **Single-writer only** in Phase 2. Do not run parallel ingests from multiple pi sessions or sub-agents that assign addresses. The `flock` in the helper prevents counter corruption but does not serialize page writes themselves.
-- Sub-agents (codex, general-purpose) that are dispatched for research or review MUST NOT call the allocator. They are read-only in this respect.
-- Multi-writer support is a deferred feature.
-
-### Batch ingest
-
-Assign addresses sequentially during single-source-ingest for each source. Do not pre-reserve a block of counter values. The helper is cheap (one lock, one integer read/write).

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

@@ -1,183 +0,0 @@
----
-name: wiki-lint
-description: >
-  Health check the Obsidian wiki vault. Finds orphan pages, dead wikilinks, stale claims,
-  missing cross-references, frontmatter gaps, and empty sections. Creates or updates
-  Dataview dashboards. Generates canvas maps. Triggers on: "lint", "health check",
-  "clean up wiki", "check the wiki", "wiki maintenance", "find orphans", "wiki audit".
----
-
-# wiki-lint: Wiki Health Check
-
-Run lint after every 10-15 ingests, or weekly. Ask before auto-fixing anything. Output a lint report to `wiki/meta/lint-report-YYYY-MM-DD.md`.
-
----
-
-## 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`).
-
----
-
-## Lint Checks
-
-Work through these in order:
-
-1. **Orphan pages**. Wiki pages with no inbound wikilinks. They exist but nothing points to them.
-2. **Dead links**. Wikilinks that reference a page that does not exist.
-3. **Stale claims**. Assertions on older pages that newer sources have contradicted or updated.
-4. **Missing pages**. Concepts or entities mentioned in multiple pages but lacking their own page.
-5. **Missing cross-references**. Entities mentioned in a page but not linked.
-6. **Frontmatter gaps**. Pages missing required fields (type, status, created, updated, tags).
-7. **Empty sections**. Headings with no content underneath.
-8. **Stale index entries**. Items in `wiki/index.md` pointing to renamed or deleted pages.
-
----
-
-## Lint Report Format
-
-Create at `wiki/meta/lint-report-YYYY-MM-DD.md`:
-
-```markdown
----
-type: meta
-title: "Lint Report YYYY-MM-DD"
-created: YYYY-MM-DD
-updated: YYYY-MM-DD
-tags: [meta, lint]
-status: developing
----
-
-# Lint Report: YYYY-MM-DD
-
-## Summary
-- Pages scanned: N
-- Issues found: N
-- Auto-fixed: N
-- Needs review: N
-
-## Orphan Pages
-- [[Page Name]]: no inbound links. Suggest: link from [[Related Page]] or delete.
-
-## Dead Links
-- [[Missing Page]]: referenced in [[Source Page]] but does not exist. Suggest: create stub or remove link.
-
-## Missing Pages
-- "concept name": mentioned in [[Page A]], [[Page B]], [[Page C]]. Suggest: create a concept page.
-
-## Frontmatter Gaps
-- [[Page Name]]: missing fields: status, tags
-
-## Stale Claims
-- [[Page Name]]: claim "X" may conflict with newer source [[Newer Source]].
-
-## Cross-Reference Gaps
-- [[Entity Name]] mentioned in [[Page A]] without a wikilink.
-```
-
----
-
-## Naming Conventions
-
-Enforce these during lint:
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Filenames | Title Case with spaces | `Machine Learning.md` |
-| Folders | lowercase with dashes | `wiki/data-models/` |
-| Tags | lowercase, hierarchical | `#domain/architecture` |
-| Wikilinks | match filename exactly | `[[Machine Learning]]` |
-
-Filenames must be unique across the vault. Wikilinks work without paths only if filenames are unique.
-
----
-
-## Writing Style Check
-
-During lint, flag pages that violate the style guide:
-
-- Not declarative present tense ("X basically does Y" instead of "X does Y")
-- Missing source citations where claims are made
-- Uncertainty not flagged with `> [!gap]`
-- Contradictions not flagged with `> [!contradiction]`
-
----
-
-## Dataview Dashboard
-
-Create or update `wiki/meta/dashboard.md` with these queries:
-
-````markdown
----
-type: meta
-title: "Dashboard"
-updated: YYYY-MM-DD
----
-# Wiki Dashboard
-
-## Recent Activity
-```dataview
-TABLE type, status, updated FROM "wiki" SORT updated DESC LIMIT 15
-```
-
-## Seed Pages (Need Development)
-```dataview
-LIST FROM "wiki" WHERE status = "seed" SORT updated ASC
-```
-
-## Entities Missing Sources
-```dataview
-LIST FROM "wiki/entities" WHERE !sources OR length(sources) = 0
-```
-
-## Open Questions
-```dataview
-LIST FROM "wiki/questions" WHERE answer_quality = "draft" SORT created DESC
-```
-````
-
----
-
-## Canvas Map
-
-Create or update `wiki/meta/overview.canvas` for a visual domain map:
-
-```json
-{
-  "nodes": [
-    {
-      "id": "1",
-      "type": "file",
-      "file": "wiki/overview.md",
-      "x": 0, "y": 0,
-      "width": 300, "height": 140,
-      "color": "1"
-    }
-  ],
-  "edges": []
-}
-```
-
-Add one node per domain page. Connect domains that have significant cross-references. Colors map to the CSS scheme: 1=blue, 2=purple, 3=yellow, 4=orange, 5=green, 6=red.
-
----
-
-## Before Auto-Fixing
-
-Always show the lint report first. Ask: "Should I fix these automatically, or do you want to review each one?"
-
-Safe to auto-fix:
-- Adding missing frontmatter fields with placeholder values
-- Creating stub pages for missing entities
-- Adding wikilinks for unlinked mentions
-
-Needs review before fixing:
-- Deleting orphan pages (they might be intentionally isolated)
-- Resolving contradictions (requires human judgment)
-- Merging duplicate pages