@diottodev/runic 1.0.0 → 1.1.0

package/engineering/llm-wiki/skills/llm-wiki/assets/example-vault/wiki/sources/monosemanticity.md

@@ -0,0 +1,41 @@
+---
+title: "Towards Monosemanticity: Decomposing Language Models With Dictionary Learning"
+category: source
+summary: Anthropic 2023 paper using sparse autoencoders to extract interpretable features from a one-layer transformer
+tags: [interpretability, sparse-autoencoders, anthropic]
+source_path: raw/papers/monosemanticity.pdf
+source_date: 2023-10
+authors: [Bricken et al.]
+ingested: 2026-04-10
+updated: 2026-04-10
+---
+
+# Towards Monosemanticity
+
+## TL;DR
+Trains a wide sparse autoencoder on the residual stream of a one-layer transformer and finds that the resulting features are substantially more interpretable than the model's native neurons.
+
+## Key claims
+1. SAE features are more monosemantic than neurons
+2. Features come in interpretable families (tokens, contexts, syntactic roles)
+3. The approach is complementary to, not a replacement for, mechanistic circuits work
+
+## Methods
+- One-layer transformer target
+- Wide sparse autoencoder on residual stream
+- L1 sparsity regularization
+- Feature dictionary size >> model width
+
+## Evidence cited
+- Qualitative inspection of top activating examples per feature
+- Comparison with probing
+- Feature family analysis
+
+## Connections
+- Extends [[concepts/sparse-autoencoder]]
+- Builds on [[entities/anthropic]]'s prior Transformer Circuits work
+
+## Where it's cited
+- [[concepts/sparse-autoencoder]]
+- [[entities/anthropic]]
+- [[synthesis/interpretability-overview]]

package/engineering/llm-wiki/skills/llm-wiki/assets/example-vault/wiki/synthesis/interpretability-overview.md

@@ -0,0 +1,32 @@
+---
+title: Interpretability Overview
+category: synthesis
+summary: Current synthesis on mechanistic interpretability in large language models
+tags: [interpretability, overview]
+sources: 1
+updated: 2026-04-10
+---
+
+# Interpretability Overview
+
+## Thesis
+_(early — only one source ingested)_ Mechanistic interpretability is shifting from direct neuron inspection (limited by polysemanticity) toward sparse-autoencoder-based feature decomposition. The empirical bet is that overcomplete sparse dictionaries recover the "true" feature basis of trained models.
+
+## The landscape
+- **Sparse-autoencoder line** — pursued by [[entities/anthropic]]; see [[sources/monosemanticity]]
+- **Circuits work** — (no sources ingested yet)
+- **Probing** — (no sources ingested yet)
+
+## Key concepts
+- [[concepts/sparse-autoencoder]] — primary method under investigation
+
+## Key sources
+- [[sources/monosemanticity]] — foundational SAE paper
+
+## Current open problems
+- Scaling SAEs beyond toy models
+- Whether features are truly monosemantic vs merely "more" monosemantic
+- How SAE features relate to circuits-based analysis
+
+## How this synthesis has changed
+- **2026-04-10** — initial synthesis after ingesting [[sources/monosemanticity]]. Only one data point; thesis is intentionally tentative.

package/engineering/llm-wiki/skills/llm-wiki/assets/index.md.template

@@ -0,0 +1,32 @@
+# Index — {{VAULT_NAME}}
+
+_Initialized {{DATE}} • 0 pages_
+
+> Content-oriented catalog of every page in `wiki/`. Updated by
+> `scripts/update_index.py` or during `/wiki-ingest`. Answer queries
+> by reading this file first, then drilling into relevant pages.
+>
+> Topic: **{{TOPIC}}**
+
+## Synthesis (0)
+_No pages yet. Will appear here as you ingest sources and build high-level theses._
+
+## Concept (0)
+_No pages yet. Will populate with ideas, theories, methods as sources are ingested._
+
+## Entity (0)
+_No pages yet. People, organizations, places, products mentioned in your sources will show up here._
+
+## Source (0)
+_No pages yet. Each ingested source gets one summary page here._
+
+## Comparison (0)
+_No pages yet. Cross-source or cross-concept analyses will live here._
+
+---
+
+### First steps
+
+1. Drop a source into `raw/`
+2. Run `/wiki-ingest raw/<your-file>` in your LLM CLI
+3. Watch this index populate

package/engineering/llm-wiki/skills/llm-wiki/assets/log.md.template

@@ -0,0 +1,12 @@
+# Log — {{VAULT_NAME}}
+
+> Append-only timeline. Every LLM operation leaves an entry here.
+>
+> Format: `## [YYYY-MM-DD] <op> | <title>` followed by an optional detail line.
+> Valid ops: `ingest`, `query`, `lint`, `create`, `update`, `delete`, `note`.
+>
+> Grep the last 10 entries: `grep "^## \[" log.md | tail -10`
+
+## [{{DATE}}] note | Vault initialized
+Topic: **{{TOPIC}}**. Layers created: `raw/`, `wiki/{entities,concepts,sources,comparisons,synthesis}`.
+Schema loader: `CLAUDE.md` + `AGENTS.md` + `.cursorrules`.

package/engineering/llm-wiki/skills/llm-wiki/assets/page-templates/comparison.md

@@ -0,0 +1,39 @@
+---
+title: "<A> vs <B>"
+category: comparison
+summary: <one-line summary — what this comparison is about>
+tags: [comparison]
+sources: 0
+updated: <YYYY-MM-DD>
+---
+
+# <A> vs <B>
+
+## What they share
+Common ground. Same problem space? Same goals?
+
+## Where they diverge
+| Dimension | <A> | <B> |
+|---|---|---|
+| Dimension 1 | ... | ... |
+| Dimension 2 | ... | ... |
+| Dimension 3 | ... | ... |
+
+## Which sources take which side
+- [[sources/xxx]] — pro-<A>
+- [[sources/yyy]] — pro-<B>
+- [[sources/zzz]] — neutral / both
+
+## When to prefer <A>
+- Context where A wins
+
+## When to prefer <B>
+- Context where B wins
+
+## Open questions
+- Unresolved disagreements
+- Data that would settle the question
+
+## Related
+- [[concepts/a]] · [[concepts/b]]
+- [[synthesis/xxx]]

package/engineering/llm-wiki/skills/llm-wiki/assets/page-templates/concept.md

@@ -0,0 +1,31 @@
+---
+title: <Concept Name>
+category: concept
+summary: <one-line definition>
+tags: []
+sources: 0
+updated: <YYYY-MM-DD>
+---
+
+# <Concept Name>
+
+## Definition
+Precise, one-paragraph definition. The canonical form used across your sources.
+
+## Origin
+Who proposed it, when, in what work. Link [[entities]] and [[sources]].
+
+## Key claims
+- Claim 1 — cited from [[sources/xxx]]
+- Claim 2 — cited from [[sources/yyy]]
+
+## Contrasts with
+- [[concepts/other]] — see [[comparisons/xxx-vs-other]]
+
+## Open questions / disagreements
+- Unresolved questions across sources
+- ⚠️ Contradiction: [[sources/a]] claims X but [[sources/b]] claims ~X
+
+## Used in
+- [[synthesis/xxx]]
+- [[sources/yyy]]

package/engineering/llm-wiki/skills/llm-wiki/assets/page-templates/entity.md

@@ -0,0 +1,31 @@
+---
+title: <Entity Name>
+category: entity
+summary: <one-line summary — what this entity is and why it matters>
+tags: []
+sources: 0
+updated: <YYYY-MM-DD>
+---
+
+# <Entity Name>
+
+## What it is
+One-paragraph definition. What kind of entity (person, org, place, product), founded/born when, by whom, active in what.
+
+## Why it matters
+Why this entity shows up across sources. What role does it play in the narrative of this wiki?
+
+## Key facts
+- Fact 1 — cited from [[sources/xxx]]
+- Fact 2 — cited from [[sources/yyy]]
+
+## Related
+- Related [[entities/other]]
+- Related [[concepts/xxx]]
+
+## Appears in
+- [[sources/xxx]] — short note on the connection
+- [[sources/yyy]] — short note
+
+## Open questions
+- Things the sources don't answer. Good prompts for new source hunts.

package/engineering/llm-wiki/skills/llm-wiki/assets/page-templates/source-summary.md

@@ -0,0 +1,41 @@
+---
+title: "<Source Title>"
+category: source
+summary: <one-line summary>
+tags: []
+source_path: raw/<path-to-source>
+source_date: <YYYY-MM>
+authors: [<author1>, <author2>]
+ingested: <YYYY-MM-DD>
+updated: <YYYY-MM-DD>
+---
+
+# <Source Title>
+
+## TL;DR
+Two sentences max. What did they do, what did they find / argue.
+
+## Key claims
+1. Claim with page/section pointer if applicable
+2. ...
+
+## Methods (if applicable)
+How the work was done. Data, model, training, evaluation. For non-research sources, describe the approach/argument structure.
+
+## Evidence cited
+- Figure X shows ...
+- Table Y ...
+- Quote: "..." (p. NN)
+
+## Surprises / contradictions
+- Where this source conflicts with [[sources/other]] or [[concepts/xxx]]
+
+## Connections
+- Extends [[concepts/xxx]]
+- Builds on [[entities/yyy]]'s prior work
+- Related: [[sources/zzz]]
+
+## Where it's cited in this wiki
+- [[concepts/xxx]]
+- [[entities/yyy]]
+- [[synthesis/zzz]]

package/engineering/llm-wiki/skills/llm-wiki/assets/page-templates/synthesis.md

@@ -0,0 +1,38 @@
+---
+title: <Topic> Overview
+category: synthesis
+summary: <current thesis in one line>
+tags: [overview]
+sources: 0
+updated: <YYYY-MM-DD>
+---
+
+# <Topic> Overview
+
+## Thesis
+Two or three sentences capturing the current synthesis across all sources read so far. **Revised** as new sources come in.
+
+## The landscape
+- Sub-area A — pursued by [[entities/x]], papers [[sources/y]]
+- Sub-area B — ...
+- Sub-area C — ...
+
+## Key concepts
+- [[concepts/xxx]] — short note on role
+- [[concepts/yyy]] — short note
+- [[concepts/zzz]] — short note
+
+## Key sources
+- [[sources/xxx]] — why it matters
+- [[sources/yyy]] — why it matters
+
+## Current open problems
+Short list with [[concepts]] and [[sources]] pointers.
+
+## How this synthesis has changed
+- **<YYYY-MM-DD>** — initial synthesis after first N sources.
+- **<YYYY-MM-DD>** — added [[sources/xxx]]; shifted emphasis toward ...
+
+## Related
+- [[synthesis/other-overview]]
+- [[comparisons/a-vs-b]]

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/README.md

@@ -0,0 +1,19 @@
+# Expected Outputs
+
+Sample outputs for each script in `scripts/`. Use these as fixtures when testing
+or to verify the scripts behave correctly end-to-end.
+
+| Script | Fixture |
+|---|---|
+| `init_vault.py --json` | `init_vault.json` |
+| `ingest_source.py --json` | `ingest_source.json` |
+| `update_index.py --json` | `update_index.json` |
+| `append_log.py --json` | `append_log.json` |
+| `wiki_search.py --json` | `wiki_search.json` |
+| `lint_wiki.py --json` | `lint_wiki.json` |
+| `graph_analyzer.py --json` | `graph_analyzer.json` |
+| `export_marp.py --json` | `export_marp.json` |
+
+These were captured against a small 2-page example vault (one concept page and
+one source page, both with proper frontmatter). Paths have been anonymized to
+`/tmp/test-vault`.

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/append_log.json

@@ -0,0 +1,9 @@
+{
+  "status": "ok",
+  "log_path": "/tmp/test-vault/wiki/log.md",
+  "date": "2026-04-11",
+  "op": "ingest",
+  "title": "Hello Monosemanticity",
+  "header": "## [2026-04-11] ingest | Hello Monosemanticity",
+  "detail": "touched 2 pages"
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/export_marp.json

@@ -0,0 +1,9 @@
+{
+  "status": "ok",
+  "vault": "/tmp/test-vault",
+  "source": "wiki/concepts/sparse-autoencoder.md",
+  "theme": "gaia",
+  "output_dir": "slides",
+  "rendered_count": 1,
+  "rendered": ["slides/sparse-autoencoder.marp.md"]
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/graph_analyzer.json

@@ -0,0 +1,18 @@
+{
+  "total_pages": 2,
+  "total_edges": 2,
+  "top_outbound_hubs": [
+    {"page": "sources/hello", "outbound": 1},
+    {"page": "concepts/sparse-autoencoder", "outbound": 1}
+  ],
+  "top_inbound_hubs": [
+    {"page": "sources/hello", "inbound": 1},
+    {"page": "concepts/sparse-autoencoder", "inbound": 1}
+  ],
+  "orphans": [],
+  "sinks": [],
+  "components": [
+    {"size": 2, "sample": ["concepts/sparse-autoencoder", "sources/hello"]}
+  ],
+  "component_count": 1
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/ingest_source.json

@@ -0,0 +1,12 @@
+{
+  "source_path": "/tmp/test-vault/raw/articles/hello.md",
+  "relative": "raw/articles/hello.md",
+  "bytes": 204,
+  "sha256": "dcb7021b49882e26",
+  "ext": ".md",
+  "title_guess": "Hello Monosemanticity",
+  "word_count": 28,
+  "preview": "# Hello Monosemanticity\n\nAnthropic's Bricken et al. 2023 paper trained a sparse autoencoder on a one-layer transformer and found interpretable features.\nKey claim: the feature dictionary is overcomplete.\n",
+  "existing_summary_page": null,
+  "suggested_summary_path": "wiki/sources/hello-monosemanticity.md"
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/init_vault.json

@@ -0,0 +1,26 @@
+{
+  "status": "ok",
+  "vault_path": "/tmp/test-vault",
+  "topic": "LLM interpretability",
+  "tool": "all",
+  "date": "2026-04-11",
+  "installed_files": [
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".cursorrules",
+    "wiki/index.md",
+    "wiki/log.md"
+  ],
+  "page_templates_copied": 5,
+  "layers": {
+    "raw": "your sources — immutable",
+    "wiki": "LLM-maintained knowledge base",
+    "index": "wiki/index.md",
+    "log": "wiki/log.md"
+  },
+  "next_steps": [
+    "Open the vault in Obsidian",
+    "Drop a source into raw/",
+    "Run /wiki-ingest <path> in your LLM CLI"
+  ]
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/lint_wiki.json

@@ -0,0 +1,10 @@
+{
+  "vault": "/tmp/test-vault",
+  "total_pages": 2,
+  "orphans": [],
+  "broken_links": [],
+  "stale": [],
+  "missing_frontmatter": [],
+  "duplicate_titles": {},
+  "log_gap": null
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/update_index.json

@@ -0,0 +1,11 @@
+{
+  "status": "ok",
+  "vault": "/tmp/test-vault",
+  "total_pages": 2,
+  "by_category": {
+    "concept": 1,
+    "source": 1
+  },
+  "dry_run": false,
+  "index_path": "/tmp/test-vault/wiki/index.md"
+}

package/engineering/llm-wiki/skills/llm-wiki/expected_outputs/wiki_search.json

@@ -0,0 +1,10 @@
+{
+  "query": "sparse autoencoder",
+  "hits": [
+    {
+      "path": "concepts/sparse-autoencoder.md",
+      "score": 1.995,
+      "snippet": "--- title: Sparse Autoencoder category: concept summary: Dictionary-learning method for interpretable features tags: [interpretability] sources: 1 updated: 2026-04-11 --- # Sparse Autoencoder See [[sources/hello]] for th…"
+    }
+  ]
+}

package/engineering/llm-wiki/skills/llm-wiki/references/cross-tool-setup.md

@@ -0,0 +1,108 @@
+# Cross-Tool Setup
+
+The LLM Wiki plugin is tool-agnostic. The **scripts** are pure Python stdlib and run anywhere. Only the **schema loader file** (the file the tool reads to understand conventions) differs per tool.
+
+## How different CLIs discover project-level instructions
+
+| Tool | Loader file | Notes |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | Loaded automatically when CC starts in the vault dir |
+| Codex CLI (OpenAI) | `AGENTS.md` | Loaded at session start |
+| Cursor (new) | `AGENTS.md` | Modern Cursor reads `AGENTS.md` |
+| Cursor (legacy) | `.cursorrules` | Older Cursor versions |
+| Google Antigravity | `AGENTS.md` | Uses the standard `AGENTS.md` convention |
+| OpenCode / Pi | `AGENTS.md` | Same convention |
+| Gemini CLI | `AGENTS.md` | Same convention |
+| Aider | `CONVENTIONS.md` or `.aider.conf.yml` | Point Aider at `CLAUDE.md` with `--read CLAUDE.md` |
+
+**Recommendation:** ship **both** `CLAUDE.md` and `AGENTS.md` in every vault. `init_vault.py --tool all` does this by default.
+
+## Multi-tool vault
+
+If you use multiple CLIs against the same vault:
+
+```bash
+python scripts/init_vault.py --path ~/vaults/research --topic "X" --tool all
+```
+
+This creates:
+- `CLAUDE.md`
+- `AGENTS.md`
+- `.cursorrules`
+
+All three are **the same content**, formatted appropriately. You can symlink to keep them in sync:
+
+```bash
+cd <vault>
+ln -sf CLAUDE.md AGENTS.md
+# or edit both manually when you tune the schema
+```
+
+## Per-tool quickstart
+
+### Claude Code
+
+```bash
+cd <vault>
+claude
+> /wiki-init              # if vault isn't initialized
+> /wiki-ingest raw/paper.pdf
+> /wiki-query "what does the paper say about X?"
+```
+
+The slash commands ship with this plugin. To install the plugin itself, either:
+- Clone claude-code-skills and copy `engineering/llm-wiki/` into `~/.claude/skills/`, or
+- Install via the marketplace if published
+
+### Codex CLI
+
+Codex reads `AGENTS.md` automatically. Then:
+
+```bash
+cd <vault>
+codex
+> ingest raw/paper.pdf into the wiki
+> query: what does the paper say about X?
+```
+
+Codex doesn't have slash commands, but the schema file teaches it the ingest/query/lint workflow, so natural-language triggers work.
+
+### Cursor
+
+```bash
+cd <vault>
+cursor .
+```
+
+Open the Cursor chat in the sidebar. Cursor auto-reads `AGENTS.md`. Ask the same questions.
+
+### Antigravity / OpenCode / Pi
+
+Same as Codex — drop `AGENTS.md` in the vault root and use natural language.
+
+### Multi-tool same session
+
+You can run Claude Code and Codex **simultaneously** against the same vault. They'll both see updates if one writes a page — filesystem is the source of truth. Just make sure each vault is committed to git so you can resolve conflicts.
+
+## Running the scripts directly (any tool)
+
+The scripts don't care which tool calls them. You can run them from the shell any time:
+
+```bash
+# from inside the vault
+python ~/.claude/skills/llm-wiki/scripts/lint_wiki.py --vault .
+python ~/.claude/skills/llm-wiki/scripts/update_index.py --vault .
+python ~/.claude/skills/llm-wiki/scripts/wiki_search.py --vault . --query "superposition"
+```
+
+Aliases are handy. Add to your shell rc:
+
+```bash
+alias wiki-lint='python ~/.claude/skills/llm-wiki/scripts/lint_wiki.py --vault .'
+alias wiki-index='python ~/.claude/skills/llm-wiki/scripts/update_index.py --vault .'
+alias wiki-search='python ~/.claude/skills/llm-wiki/scripts/wiki_search.py --vault .'
+```
+
+## MCP exposure (future)
+
+The wiki can be exposed as an MCP tool so any MCP-capable client (Claude Desktop, Claude Code, etc.) can query it. See `engineering/mcp-design` in this repo for the pattern. A future version of this plugin will ship an `mcp/` directory with a reference MCP server.

package/engineering/llm-wiki/skills/llm-wiki/references/ingest-workflow.md

@@ -0,0 +1,97 @@
+# Ingest Workflow
+
+The detailed flow the LLM follows when the user runs `/wiki-ingest <path>` or dispatches the `wiki-ingestor` sub-agent.
+
+## Inputs
+
+- Path to a source file (inside `raw/` — if not, prompt the user to move it first)
+- The current state of `wiki/` (especially `index.md`)
+
+## Step-by-step
+
+### 1. Prepare the brief
+
+Run `python scripts/ingest_source.py --vault . --source <path> --json` to get:
+- title guess
+- word count
+- preview (first 1200 chars)
+- suggested summary-page path
+- whether a summary page already exists (→ **merge mode**)
+
+### 2. Read the source
+
+Use the Read tool on the source directly. For PDFs, use the Read tool's PDF support. For images clipped locally to `raw/assets/`, inspect them if the LLM has vision.
+
+### 3. Discuss with the user
+
+Before writing anything, tell the user:
+- Title and author(s)
+- 2-3 sentence TL;DR
+- Key claims (bulleted, 3-7 items)
+- Which existing wiki pages this source will touch
+- Any **contradictions** with existing pages
+
+**Wait for user to confirm or redirect.** This is the "LLM makes edits, you browse" loop — the user is in the loop.
+
+### 4. Create / merge the source summary page
+
+Path: `wiki/sources/<slug>.md`. Use the **source summary** template from `references/page-formats.md`. Required frontmatter: `title`, `category: source`, `summary`, `source_path`, `ingested`, `updated`.
+
+**Merge mode** (summary page already exists): append a new "## Re-ingest <date>" section at the bottom with what changed. Do not overwrite.
+
+### 5. Identify entities and concepts
+
+For each entity and concept mentioned in the source:
+- Check if a page exists in `wiki/entities/` or `wiki/concepts/`
+- **If yes:** update it. Add a new bullet under "Appears in" / "Used in" pointing to this source. Update "Key claims" if this source adds or contradicts a claim. Update `sources:` count in frontmatter. Update `updated:` to today.
+- **If no:** create a new page from the entity/concept template. Start with the minimum: title, summary, one key fact sourced from this reading, link back to this source.
+
+Typical ingest touches **5-15 pages** across `entities/`, `concepts/`, and sometimes `comparisons/`.
+
+### 6. Flag contradictions explicitly
+
+If the new source contradicts an existing page, add a callout to BOTH pages:
+
+```markdown
+> ⚠️ **Contradiction** — [[sources/new]] claims X but [[sources/old]] claims ~X.
+> Unresolved as of 2026-04-10.
+```
+
+Log contradictions in `log.md` with `op: note`.
+
+### 7. Update synthesis (optional)
+
+If the source meaningfully shifts a `synthesis/` page's thesis, revise the "Thesis" paragraph and append a dated entry under "How this synthesis has changed". Don't rewrite history; append.
+
+### 8. Update `index.md`
+
+Either:
+- Run `python scripts/update_index.py --vault .` to regenerate the entire index from frontmatter, OR
+- Edit the relevant category sections inline (faster for small ingests).
+
+### 9. Append to `log.md`
+
+Run `python scripts/append_log.py --vault . --op ingest --title "<title>" --detail "<detail>"`.
+
+The detail line should list which pages were touched:
+
+```
+## [2026-04-10] ingest | Anthropic Monosemanticity
+Added sources/monosemanticity.md. Updated concepts/sparse-autoencoder,
+concepts/polysemanticity, entities/anthropic-interpretability-team. Flagged
+contradiction with sources/distributed-representations.
+```
+
+### 10. Report back to the user
+
+Summary the user sees in chat:
+- Source summary page created/updated
+- Pages touched (bulleted wikilinks so the user can click through)
+- Contradictions flagged (if any)
+- Suggested next sources to pursue
+
+## After-ingest tips
+
+- **Big ingest?** Run `python scripts/lint_wiki.py --vault .` to check for new orphans or broken links.
+- **Graph check?** Run `python scripts/graph_analyzer.py --vault .` to see if the new page is well-connected.
+- **Open Obsidian graph view** — the user should see the new page attached to the existing cluster.