From b5873e9e3d0964f174bace91c342a644cda6576c Mon Sep 17 00:00:00 2001
From: Alexander Whitestone <alexpaynex@gmail.com>
Date: Tue, 14 Apr 2026 11:17:01 -0400
Subject: [PATCH] Initial structure: knowledge store, scripts, metrics,
 templates

---
 README.md                 | 69 +++++++++++++++++++++++++++++++++++++--
 knowledge/agents/.gitkeep |  0
 knowledge/global/.gitkeep |  0
 knowledge/index.json      |  6 ++++
 knowledge/repos/.gitkeep  |  0
 metrics/.gitkeep          |  0
 scripts/.gitkeep          |  0
 templates/.gitkeep        |  0
 8 files changed, 73 insertions(+), 2 deletions(-)
 create mode 100644 knowledge/agents/.gitkeep
 create mode 100644 knowledge/global/.gitkeep
 create mode 100644 knowledge/index.json
 create mode 100644 knowledge/repos/.gitkeep
 create mode 100644 metrics/.gitkeep
 create mode 100644 scripts/.gitkeep
 create mode 100644 templates/.gitkeep

diff --git a/README.md b/README.md
index b251d59..20fd178 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,68 @@
-# compounding-intelligence
+# Compounding Intelligence
 
-System for turning 1B+ daily tokens into durable, compounding fleet intelligence
\ No newline at end of file
+Turn 1B+ daily tokens into durable, compounding fleet intelligence.
+
+## The Problem
+
+20,991 sessions on disk. Each one starts at zero. Every agent rediscover the same HTTP 405 is a branch protection issue. The intelligence from a million tokens of work evaporates when the session ends.
+
+## The Solution
+
+Three pipelines that form a compounding loop:
+
+```
+SESSION ENDS → HARVESTER → KNOWLEDGE STORE → BOOTSTRAPPER → NEW SESSION STARTS SMARTER
+                              ↓
+                         MEASURER → Prove it's working
+```
+
+## Architecture
+
+### Pipeline 1: Harvester
+Reads finished session transcripts. Extracts durable knowledge: facts, pitfalls, patterns, tool quirks. Stores in `knowledge/`.
+
+### Pipeline 2: Bootstrap
+Before a session starts, queries knowledge store for relevant facts. Assembles compact 2k-token context. Injects into session so it starts with full situational awareness.
+
+### Pipeline 3: Measure
+Tracks whether compounding is happening. Knowledge velocity, error reduction, hit rate, task completion. Daily report proves the loop works.
+
+## Directory Structure
+
+```
+├── knowledge/
+│   ├── index.json          # Machine-readable fact index
+│   ├── global/             # Cross-repo knowledge
+│   ├── repos/{repo}.md     # Per-repo knowledge
+│   └── agents/{agent}.md   # Agent-type notes
+├── scripts/
+│   ├── harvester.py        # Post-session knowledge extractor
+│   ├── bootstrapper.py     # Pre-session context loader
+│   ├── measurer.py         # Compounding metrics
+│   └── session_reader.py   # JSONL parser
+├── metrics/
+│   └── dashboard.md        # Human-readable status
+└── templates/
+    ├── bootstrap-context.md
+    └── harvest-prompt.md
+```
+
+## The 100x Path
+
+```
+Month 1:  15,000 facts, sessions 20% faster
+Month 2:  45,000 facts, sessions 40% faster, first-try success up 30%
+Month 3:  90,000 facts, fleet measurably smarter per token
+```
+
+Each new session is better than the last. The intelligence compounds.
+
+## Issues
+
+See [all issues](https://forge.alexanderwhitestone.com/Timmy_Foundation/compounding-intelligence/issues) for the full roadmap.
+
+**Epics:**
+- EPIC 1: Session Harvester (#2)
+- EPIC 2: Knowledge Store & Bootstrap (#3)
+- EPIC 3: Compounding Measurement (#4)
+- EPIC 4: Retroactive Harvest (#5)
diff --git a/knowledge/agents/.gitkeep b/knowledge/agents/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/knowledge/global/.gitkeep b/knowledge/global/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/knowledge/index.json b/knowledge/index.json
new file mode 100644
index 0000000..dd3e0d4
--- /dev/null
+++ b/knowledge/index.json
@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "last_updated": "2026-04-13T20:00:00Z",
+  "total_facts": 0,
+  "facts": []
+}
\ No newline at end of file
diff --git a/knowledge/repos/.gitkeep b/knowledge/repos/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/metrics/.gitkeep b/metrics/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/.gitkeep b/scripts/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/templates/.gitkeep b/templates/.gitkeep
new file mode 100644
index 0000000..e69de29