# KAI Document Library → a real PAPERS library (corrected structure + code fix)

*The library today (`[internal endpoint]` → `oracle-core.js` cards) dumps in plans, handoffs, and
~140 vendor dependency docs, shows title + size with NO date, and mis-titles files whose first line
is front-matter. This spec turns it into a papers-only, dated, structured library. The content
(which papers, which category) is authoritative below; the code change is small and localized.*

---

## How it works today (so the fix is surgical)
- Front-end `oracle-core.js` → `_codexPaintLibrary` fetches **`[internal endpoint]`**, gets
  `{categories:{key:{label,icon,docs:[{slug,title,size}]}}}`, renders cards with **only** title + KB
  (`_codexRenderLibGrid`, card-meta = `sizeKb`). Category colors: core/math/kaiverse/oracle/arch/ops/other.
- The **server** (`[internal module]`, the `[internal endpoint]` handler)
  is what scans files, assigns categories, and builds that object. **That's the file to edit** for
  inclusion + categories + adding date/description. (It's ~1 MB — the on-machine assistant should
  do it; my bridge can't read it reliably.)

---

## The corrected taxonomy — PAPERS ONLY, by domain

Replace the current category set with these eight paper categories. Each lists the files/patterns
that belong. (Titles: use the first real `#` heading, skipping BOM/`---`/`|` front-matter.)

**1. Whitepapers & Disclosures** (`whitepaper`)
- RSHL-Inventor-Disclosure-2026.md · RSHL-Whitepaper-Audit-2026-05-20.md

**2. SRHT Theory & Proofs** (`srht`)
- SRHT_MASTER_PAPER.md · SRHT_UNIVERSAL_SOLVER_PAPER.md · SRHT_CRITIQUE_AND_PROOF.md ·
  SRHT_MATH_AUDIT.md · SRHT_MATH_VERIFICATION.md · SRHT_FINAL_SOUNDNESS_AUDIT.md · SRHT_HARDENING_PLAN.md

**3. RSHL Codebase Proofs** (`proofs`)
- rshl_comprehensive_proof_vol1..16.md  (Vol 16 = master index; sort Vol 1→16, not lexically)

**4. Cognition & Architecture** (`cognition`)
- ALGORITHM-INVENTORY.md · COGNITION.md · ARCHITECTURE.md · ARCHITECTURE_V7.md ·
  ARCHITECTURE_MANIFEST.md · neural_ecosystem_manifest.md

**5. Generation / Coherence / Learning Research** (`generation`)
- RSHL_GENERATION_FINDINGS.md · RSHL-LLM-TRAINING-READINESS.md · KAI-COHERENCE-DIAGNOSIS-2026-07-02.md ·
  KAI-JSPACE-ANALYSIS.md · KAI-SELF-MAP.md · KAI-LAYER-STACK.md · KAI-HOW-HE-THINKS.md ·
  KAI-Talking-and-Learning.md · KAI-NATIVE-VOICE-PLAN.md

**6. Benchmarks & System Audits** (`benchmarks`)
- reports/RSHL-BENCH-COMPARISON-2026-07-02.md · reports/RSHL-BENCHMARK-AND-NEXT-PHASE-2026-07-02.md ·
  [config flag].md · [config flag].md · KAI_Lineage_Map.md · KAI_RL_Architecture_Brief.md ·
  ORACLE-VS-ABACUS-ECOSYSTEM.md

**7. Physics & Theory** (`physics`)
- TheEquationoftheUniverse.pdf · Helix-Light-Vortex-Theory.pdf · Attention_Residuals.pdf ·
  sandbox/physics/analysis.md

**8. External ML Research** (`external`)
- hyperprobe-main/outputs/Overview Llama3.1.pdf · Overview Llama4.pdf · Overview Phi-4.pdf ·
  Overview Pythia.pdf · Overview OLMo-2.pdf · Overview GPT-2.pdf

---

## Exclusion rules (what must NOT appear in the papers library)
Drop any file matching these — they are not papers:
- **Vendor/dependency dirs:** `OpenJarvis-main/`, `BitNet-main/`, `bitnet/`, `antigravity-sdk-python-main/`,
  `hyperprobe-main/` (except the 6 model-overview PDFs above), `ada_v2-main/`, `tools/osint/`,
  `node_modules/`, `target/`, `.git/`, `3rdparty/`.
- **Archive/backup:** `_restore-points/`, `backups/`, `_to_delete/`, `*.BACKUP-*`, `*.bak*`.
- **Boilerplate filenames:** `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`,
  `CHANGELOG.md`, `SKILL.md`, anything under a `docs/` site tree.
- **Not papers (plans/ops/handoffs):** `*-GOAL.md`, `*-PLAN.md`, `*-HANDOFF*.md`, `*-RUNBOOK*.md`,
  `*-CHECKLIST*.md`, `DISPATCH*`, `NOTE-FOR-*`, `SESSION-HANDOFF*`, `walkthrough.md`, `findings.md`,
  `*stress-report*`, `CLAUDE.md`, `CLAUDE-CODE-HANDOFF.md`, `ONBOARDING.md`, the Codex itself
  (it has its own tab). Zero-byte files.
  *(Optional: if you still want these reachable, put them in a SEPARATE "Plans & Roadmaps" tab —
  do not mix them into Papers.)*

---

## The two code changes

### A. Server — `[internal module]`, `[internal endpoint]`
1. Build the doc list from the **inclusion set** above (explicit list or the category patterns),
   apply the **exclusion rules**, so only papers remain.
2. Assign each to one of the 8 categories with a clean **label** and **icon**.
3. For each doc add two fields the cards need:
   - `date`: file mtime as `YYYY-MM-DD` (`fs.statSync(path).mtime`).
   - `description`: first non-empty `#` heading OR a one-line summary (skip BOM/`---`/`|` lines) —
     this also **corrects the mis-titles** (files currently showing `---` or a table row as title).
4. Sort each category's `docs` by `date` **newest-first** (except `proofs`: Vol 1→16).

### B. Front-end — `oracle-core.js`, `_codexRenderLibGrid`
Currently the card meta is only `sizeKb`. Change the card body to show date + description:
```
html += '<div class="card-title" ...>'+_codexEsc(doc.title)+'</div>';
html += '<div class="card-desc" style="font-size:11px;color:var(--muted);margin:2px 0">'+_codexEsc(doc.description||'')+'</div>';
html += '<div class="card-meta">'+(doc.date? doc.date+' · ':'')+sizeKb+'</div>';
```
(Additive and safe: if the server doesn't send `date`/`description`, it renders nothing — no breakage.)
Add the eight new keys to `_catColors` so each category gets a stripe color.

---

## Result
A library that shows **only real papers** — yours (whitepaper, SRHT, proofs, cognition, generation,
benchmarks) and the outside research you keep (physics papers, the model-overview PDFs) — each card
**dated, described, and correctly titled**, grouped into eight clear domains, newest-first. The ~140
vendor docs, the plans, and the handoffs no longer clutter it.

**Handoff:** I can't edit the 1 MB `command-center-server.mjs` reliably over my bridge, so the
on-machine assistant should make change (A); change (B) in `oracle-core.js` I *can* stage safely if
you want it done from here (it's additive). Say the word and I'll stage B now, and this spec covers A.