v2.5.0 — Launch-Ready Onboarding + Daemon Hardening

Technical preview readiness release. The centerpiece is a rewritten onboarding path that makes the first run fully deterministic — no network, no Ollama, no YouTube required. A bundled sample source (SRC-000000-DEMO) lets new users go from clone to extraction in 5 minutes. Alongside: daemon reliability hardening, a public-surface contract verifier, and a data fix for collapsed embeddings.

Highlights

• Deterministic first-run onboarding — init.ts now creates a bundled sample source so the quickstart works without internet or Ollama. README rewritten around the principle "first run must be deterministic" with clear dependency table showing what each feature requires.
• Routing producer self-check — findMissingProducers() statically verifies every routed daemon status has at least one updateStatus producer. Two new tests prevent the class of state-machine drift bug that silently orphaned stepMerge, stepVerify, and stepDeepRead in prior releases.
• Heavy-path health signal — daemon-status.json now surfaces heavy_path.last_commit_at and heavy_path.last_insights_extracted so external users can monitor heavy-mode pipeline health without grepping logs.
• Surface contract verification — verify-contracts replaces verify-readme, enforcing 40 stable public-surface claims (MCP tools, inbox routes, skills, script exports, doc-code consistency). Volatile test-count checks removed.
• Embedding collapse fix — 4 zero-distance embedding pairs (1 insight, 3 principle) re-embedded after discovering identical vectors from transient Ollama response duplication. Synthesis-candidates regenerated, 1.00 false positive cleared.
• defusedxml phantom closed — investigated the "100 health warnings" claim from session state; found it was a prior-session hallucination propagated through session.md. Filed session-state propagation risk for future hardening.

Commits

• d128ee7715 daemon: restore heavy-mode pipeline routing
• fa14f49375 daemon: filter pdf and reddit stub bodies before extraction
• b3dedd044b contracts: verify stable public surface claims
• 8c6ac41603 onboarding: make first run deterministic with demo source
• 8121487e13 daemon: add routing producer self-check
• f3072a6f4b daemon: surface heavy-path health signal in status file
• eeba4a39fc auto: post-learn — connection updates after embedding repair

Test coverage

Contract tests: 9. Routing tests: 7 (5 existing + 2 new). Full suite: 459 passed, 3 env-gated skips across 31 files.

v2.4.1 — Slow-Graph Tension Filter + Targeted Compression

Three system-level fixes plus 8 new principles from targeted compression. The centerpiece is the polarity rework: the tension-candidate generator now consumes the 28,659-edge slow graph as an authoritative pre-filter instead of relying on weak lexical heuristics, reducing the candidate queue from 28 paraphrase-dominated entries to 9 legitimate candidates with real CHALLENGES pairs boosted to the top.

Highlights

• Tension generator consumes the slow graph — pairs that classify-edges.ts has already marked as SUPPORTS/REFINES/EXTENDS are hard-rejected before any scoring runs. CHALLENGES/CONTRADICTS pairs get a +5 boost. A content-level Jaccard gate at 0.30 catches no-edge paraphrases as a secondary filter. Both gates apply during the merge step so stale candidates from prior runs get cleaned too.
• Wake ghost-prediction fix centralized — extracted filterActivePredictionEvidence<T> as a shared generic helper so both Prediction Watch and Your Judgment Needed filter resolved predictions through the same code path. Previously only Your Judgment Needed was fixed.
• 34 zero-insight stubs archived — 19 paste/reddit/pdf ingestion stubs from a half-finished March 2026 session plus 15 sub-floor YouTube clips, with manifest documenting the triage rationale, 3 manual-extraction candidates, and a deferred stub-body ingest guardrail.
• 8 new principles from targeted compression of the three highest-surprise COMPRESS topics.

Fixes

• 4af0429347 fix(tensions): consume slow graph to reject paraphrases and boost real tensions
• b18f6790e7 fix(wake): centralize active-predictions filter across both sections
• ce3618c94e chore(stubs-260411): archive 34 zero-insight stub + sub-floor sources

Compression

• ai-development/llm-training (63:1 → 63:4): training-pipeline compounding, RL-discovers-model-native-reasoning, distillation-as-distribution
• psychology/negotiation (17:0 → 17:3): settlement-space-requires-limited-objectives, lower-defenses-first, leverage-is-manufactured
• ai-development/ai-capabilities (148:17 → 148:19): quantum-advantage-is-structurally-narrow, wet-lab-bottleneck-is-irreducible

Test coverage

40 new tests (wake: 6, learning: 34). Full suite: 434 total (431 run + 3 env-gated skips).

v2.4.0 — Pipeline Hardening + Cohort-Scoped Extraction

Seventeen architectural fixes plus 1,099 new insights across six ingest cohorts. The centerpiece is making the extract control plane honest: post-ingest.ts is now a pure derived-state rebuild, autoknowledge.ts supports explicit --batch scoping, and ingest-channel.ts --auto-extract generates a manifest so cohort ingests no longer silently consume the global backlog.

Highlights

• Pure post-ingest — removed the hidden autoknowledge --limit 5 recursion. The pipeline now does exactly what its name says and nothing more.
• autoknowledge --batch <manifest> — explicit cohort scope. Relative paths resolve against PROJECT_ROOT so it works from any cwd.
• Scoped ingest-channel --auto-extract — generates a batch manifest from the videos that just ingested and hands it to autoknowledge, instead of calling it unscoped.
• Blog fetch hardening — 30 s timeout, browser User-Agent, JSON-LD author/publisher normalization, and @graph article-node selection.
• First real test coverage for ingest-channel.ts — 21 tests locking in tracker round-trip, zero-view fallback labeling, batch manifest generation, and collectNewlyIngestedIds filter semantics.
• Blog backlog archival — 252 unextracted blog sources (100% below the 500-word floor, verified by an 8-sample pipeline canary) moved to archive/blog-backlog-20260411/ with a full manifest.

Control plane cleanup

• 7e11097719 fix(post-ingest): remove opportunistic autoknowledge recursion
• a89d9bf851 feat(autoknowledge): add --batch manifest scope for explicit cohorts
• 31d40e0990 fix(pipeline): Tier 1 follow-ups — --batch path resolution, graph node selection
• ee0166780f fix(ingest-channel): --auto-extract now scopes to a batch manifest
• 81262007ed fix(pipeline): harden large-batch ingest + extraction against crash residue
• dc0f72a918 fix(ingest-channel): remove outer autoknowledge wall-clock timeout
• 49787fedf5 fix(ingest-channel): resolve channelName before referencing it in trackerTitle
• 407ee83046 fix(ingest): clean up tracker semantics and allow whisper transcript type

Ingest hardening

• b6443d4e44 fix(ingest): add browser UA and bump blog fetch timeout to 30s
• 20b3a24306 fix(blog): normalize JSON-LD author and publisher metadata
• e1b9ed9343 fix(extract): retry salt on insight ID collisions before write

Other fixes

• 9cc6fb8481 fix(learning): filter archived insights from tension candidates
• 7c9a679083 fix(wake): filter resolved predictions out of Your Judgment Needed
• 9bee67c360 fix(sleep): scope git add/diff/commit to session.md via pathspec
• e96fee0967 fix(sleep): stop pretending sleep.ts can commit gitignored session state

Test coverage

• 9e75c5fa0c test(ingest-channel): add unit tests + refactor helpers for testability — 21 new tests, first real coverage for the channel ingest control plane.

Audit and archival

• 6c6561902e feat(audit): blog backlog audit and one-shot archival tools
  • scripts/audit-blog-backlog.ts — read-only inventory (word-count distribution, hosts, authors, date histogram)
  • scripts/audit-blog-recoverability.ts — pipeline canary using the same headers and timeout as ingest.ts, calling extractArticle from blog.ts
  • scripts/archive-blog-backlog.ts — one-shot archival with manifest
  • knowledge-base/archive/blog-backlog-20260411/manifest.json — rationale, per-host counts, PG follow-up top-10 candidates, audio-ingest follow-up note for Lenny/Chamath podcast show notes

Content additions

1,099 new insights across six cohorts: Karpathy full channel, Dwarkesh top 50, Anthropic engineering blog, Buffett 2025 shareholder letter (Greg Abel's first as CEO), Acquired top 50, plus manual morning ingests (mempalace, Appleton, Matuschak/Nielsen TTFT, Jerry Liu Latent Space, Julia Galef EconTalk).

Total diff vs v2.3.0: 8,379 files changed, +268,556 / −10,657 lines — insertions are dominated by regenerated views, fresh insights, and updated principle backlinks from post-ingest sweeps.

v2.3.0 — Ambient Retrieval + Chronological Log

What's in this release

The conversation that produced this release started with "tackle all 35 COMPRESS flags" and ended with a coherent nine-phase roadmap built around a single evaluation standard: did this make Zuhn change what the user noticed, decided, or did?

Phase 1 — Ambient retrieval

Added a concise mode to the decision brief that returns a ~300-token summary instead of the full ~2000-token markdown. This is a cost-structure change: cheap enough for Claude to invoke reflexively during any decision-shaped prompt, without explicit user invocation.

• scripts/lib/brief.ts: new renderBriefAsConciseContext() — 3 principles, 2 predictions, 1 decision, 1 tension, 1-line track record. Pure render-layer truncation, no reordering or ranking logic.
• scripts/mcp-server.ts: zuhn_brief tool now defaults to mode="concise" and returns rendered text. Breaking change: was structured JSON. Instructs callers to invoke before decision-shaped prompts.
• scripts/brief.ts: CLI --mode concise|full flag with the opposite default (CLI stays full for human deep work).
• ~/.claude/CLAUDE.md: tightened global instruction so Claude reflexively invokes zuhn_brief(mode="concise") on decision-shaped prompts.
• Bug fix: evidence-only briefs now render a fallback Evidence: section instead of falsely reporting "no relevant context" when raw insights exist but no compressed artifacts do.

Phase 2 — Chronology

Added an append-only meta/log.md that records every mutation to the knowledge base. Direct steal from Karpathy's llm-wiki pattern. Will become the substrate for wake-time context retrieval, resolve-due prompts, and the wiki-health diagnostic in later phases.

• scripts/lib/log.ts: logEntry() + safeLogEntry() + normalizeBodyLine(). Strict validation + pipeline-safe wrapper. Format locked: ## [date] action | scope followed by 1-3 grep-friendly body lines.
• Wired into ingest (6 content-type branches), extract, create-principles (grouped by domain, with actual-write accounting — not input counts), predict, decide, resolve. All log writes use safeLogEntry so failures warn instead of breaking the pipeline.
• Bug fix (post-review): create-principles no longer overcounts domains on mixed-outcome runs (skips + errors were previously counted as if they had succeeded).
• Bug fix (post-review): freeform body text (prediction claims, decision contexts, resolve notes, source titles) is now normalized through normalizeBodyLine() to collapse embedded newlines, preserving the grep-friendly format discipline.

Compression marathon (included)

Same session also tackled all 35 COMPRESS flags in one pass, producing 40 new principles across ai-development, psychology, startups, investing, and health. Highlights:

• Form-meaning gap in LLMs — fluency masks absence of understanding
• Phase transitions in AI capability adoption — workflows flip overnight once a threshold is crossed
• RuBisCo-style lock-in pattern — early suboptimal cores scale through volume rather than replacement
• Dopamine baseline ratcheting — digital stimulation creates neurological damage
• Silent error accumulation — systems fail suddenly after invisible drift

Tests

• 348/348 passing (was 307 at session start — +41 tests across 3 new test files)

The roadmap continues

Phase 3-9 are planned in docs/superpowers/plans/2026-04-08-concise-brief-mode.md:

3. Wake-time contextual retrieval
4. Outcome forcing (resolve-due.ts)
5. Wiki-health diagnostic (likely subsumes the deprioritized graph plan)
6. Index layer (index.md)
7. Per-domain overview pages
8. Fileable analyses (brief.ts --save)
9. Re-evaluate topic connection graph

Every phase must pass the same test: did it change what the user noticed, decided, or did?

Commits

0864f7b29  docs: v2.3.0 plan docs, README updates, broaden .db gitignore
6c4c518a9  fix(log): count actual writes and normalize freeform body
682dd1df5  feat(log): add meta/log.md + wire pipeline scripts
6ebd63faa  fix(brief): evidence-only briefs no longer falsely report empty
c9e237768  feat(brief-cli): add --mode concise|full flag
d32924d63  feat(mcp): wire zuhn_brief mode with concise default
d35b4af91  feat(brief): add renderBriefAsConciseContext
ce109ad29  auto: post-ingest — 40 new principles, 2309 updated

Zuhn v2.2.0 — Full Compression + Decision Briefs

What's New

Every topic in the knowledge base is now compressed to ≤10:1 insight-to-principle ratio, and a new decision brief tool makes compressed knowledge actionable during real decisions.

Compression Marathon — 344 New Principles

• Principles: 426 → 770 (81% increase)
• All 44 topics compressed to ≤10:1 ratio (worst was 143:1)
• 20 parallel agents compressed topics simultaneously
• 2 duplicate ID collisions from parallel agents detected and fixed
• Health check: PASS (0 errors)

Domains compressed:

• startups (20 topics): fundraising (41 new), competitive-strategy (29), execution (15), strategy (16), scaling (11), validation (13), innovation (10), founder-mindset (9), growth (8), + 11 smaller topics
• psychology (10 topics): learning (17), cognitive-biases (14), group-dynamics (10), decision-making (9), cognition (7), expertise (5), + 4 smaller topics
• investing (5 topics): venture-capital (27), geopolitics (12), fintech (3), ai-business-models (3), bubbles (2)
• ai-development (6 topics): system-building (6), future-of-work (5), ai-agents (4), ai-market-dynamics (3), + 2 smaller topics
• health/nutrition (3 new), psychology/focus (3), psychology/resilience (3)

Decision Brief Tool

New scripts/brief.ts and zuhn_brief MCP tool that assembles everything the KB knows about a decision context:

• Relevant principles ranked by evidence overlap and empirical state
• Past decisions with outcomes
• Active predictions with deadlines
• Unresolved tensions between conflicting principles
• Supporting evidence from insight search
• Empirical track record (confirmed/falsified/untested)

npm run brief "Should I raise VC or bootstrap?"
npm run brief --domain startups "pricing strategy"

Also available as zuhn_brief MCP tool in any Claude session.

Ambient Knowledge Access

• Created global ~/.claude/CLAUDE.md instructing Claude to consult Zuhn during decisions across all sessions
• MCP tools now serve as the bridge between stored knowledge and real-time decision-making

Tests

• 24 test files, 307 tests, all passing
• New scripts/lib/brief.test.ts with 7 focused tests (search, punctuation, domain filtering, empty results, markdown rendering)
• TypeScript: tsc --noEmit clean

Stats

Metric	v2.1.0	v2.2.0
Insights	9,063	9,063
Principles	426	770
Domains	9	9
Topics	138	138
Tests	300	307
Health errors	0	0

Zuhn v2.1.0 — Clean KB, Full Graph, 56 New Principles

What's New

The knowledge base is clean, the connection graph is complete, and the system is ready for new content.

Semantic Dedup System

• Built scripts/dedup-insights.ts — multi-pass deduplication (title-exact, fuzzy-prefix, stance-prefix, slug-prefix, keyword-targeted)
• 1,494 duplicate insight files archived (collision bug from batch ingestion created ~60 copies of same insights)
• Fixed root cause: source IDs now salted with URL to prevent hash collisions
• Added write-time near-duplicate prevention to write-insights.ts
• Restored 7 corrupted source file bodies from raw HTML
• Fixed source attribution on 494 mis-attributed insights
• Remapped 1,600 classified connections to canonical insight IDs

Full Connection Graph

• All 9,672 cross-domain + tension pairs classified (was 6,364 at start of session)
• Zero unclassified pairs remaining
• Zero unextracted sources remaining

Compression Sprint — 56 New Principles

New principles across 22 topics including:

• AI capabilities, platform shifts, alignment, system building, architecture
• Psychology: learning, decision-making, communication, persuasion, expertise, cognition, resilience
• Startups: strategy, execution, leadership, sales, validation, ideation, innovation, competitive strategy
• Investing: bubbles, fintech, geopolitics, venture capital, AI business models

Health Check: Zero Errors

• Fixed 3,691 health errors → 0 errors
• Normalized author arrays/objects to strings across 2,000+ files
• Cleaned 6,650 broken related[] references
• Resolved 35 duplicate insight IDs

TypeScript Cleanup

• npx tsc --noEmit passes clean (was 37 errors)
• Fixed dynamic import extensions, Graphology typing, test fixtures
• 300/300 tests pass

Code Fixes

• ask.ts: Repaired hybrid search API — generates query embeddings via Ollama, keyword fallback
• batch-ingest.ts: Added missing image case and exhaustive default
• autoknowledge.ts: Fixed "emerging" → "inspiration" enum mismatch
• classify-edges.ts: Doubled timeout from 60s → 120s

README Rewrite

• 574 → 221 lines — optimized for conversion, not completeness
• Added worked example (source → insight → principle → search)
• Clarified extraction step for newcomers

Stats

Metric	v2.0.0	v2.1.0
Insight files	~10,657	9,063 (1,494 duplicates archived)
Principles	~370	426 (+56)
Classified connections	~50	9,672 (complete)
Health errors	~3,691	0
tsc --noEmit	37 errors	0
Tests	300/300	300/300

Full Changelog: v2.0.0...v2.1.0

Zuhn v2.0.0 — Dual-Graph Architecture

What's New

Zuhn v2 upgrades the knowledge operating system from a retrieval-and-compression system to a continual learning system — where knowledge doesn't just accumulate but reorganizes, sharpens, and self-evaluates over time.

Dual-Graph Architecture

The core innovation: two complementary graph layers that separate cheap structural discovery from expensive semantic classification.

• Fast Graph (related: string[]) — vector similarity, rebuilt every learn.ts run, zero LLM calls
• Slow Graph (evidence: TypedRelation[]) — semantic classification, built async by classify-edges.ts
• Relationship taxonomy: SUPPORTS, CONTRADICTS, EXTENDS, TRANSFERS_TO, REFINES, CHALLENGES, PREDICTED

New Learning Mechanisms

Feature	What it Does
Surprise-Gated Compression	COMPRESS flags now sort by surprise score — topics with more tensions/transfers compress first, not just the largest topics
Principle Provenance	Every principle tracks its lineage: source insights with relationship types, surprise score, compression trigger
PageRank Seed Selection	Compression prompts sort insights by PageRank on the connections subgraph — the most load-bearing insight anchors the principle
Common Neighbors Link Prediction	Finds structurally plausible connections the embedding model missed (1,770 predicted links on first run)
Confidence Trajectory Tracking	Monitors whether typed connections persist across learn runs (stable / increasing / decreasing)
Stale Insight Detection	Flags time-sensitive insights past their 180-day shelf-life for revalidation

Session→KB Pipeline

Explicit-intent capture of insights from Claude Code sessions:

• zuhn_queue_session_insight MCP tool queues observations during sessions
• npm run extract-session processes the queue through the standard pipeline
• SessionEnd hook template reminds about queued insights

By the Numbers

• 300 tests across 23 files (up from 294/22)
• 45+ TypeScript scripts (up from 40+)
• 10 MCP tools (6 read + 4 write)
• 5,844 insights, 323 principles, 9 domains
• 156 typed relationships classified in first batch run

Commits

• a68b1bd docs: add v2 design spec, roadmap, and neo4j graph improvements
• a6edd5b feat: Phase 1 — Dual-Graph Architecture foundation
• 0581de5 feat: Phases 2-5, 7 — learning mechanisms upgrade
• d39b2a5 feat: Phase 8 — Session→KB pipeline (explicit intent only)
• e4f1c42 docs: update README for v2