karpathy-wiki

# LLM Wiki Schema

This vault is a **personal knowledge base** maintained by an LLM agent. The human curates sources, directs analysis, and asks questions. The LLM does all summarizing, cross-referencing, filing, and maintenance.

## Wiki Scope

> **PLACEHOLDER — replace this paragraph during the customize-template prompt.**
>
> Describe in one paragraph what this wiki is about: the kinds of sources you'll add, the kinds of pages you want, and any adjacent topics that are in scope when they materially affect the main one. Examples: *"AI tools and workflows for developers,"* *"food science and home cooking experiments,"* *"home-lab infrastructure and self-hosting,"* *"medieval history primary sources."*

> **Important**: this scope statement is the **only** place where the wiki's topic focus lives. Everything in `.instructions/core/` is intentionally topic-agnostic — the same prompts, templates, and rules would work for any LLM-maintained personal knowledge base. When the lint prompt asks "is this page off-topic?", the answer comes from *this section*, not from any rule file.

## Git Rules

- Never add `Co-Authored-By` or any Claude attribution to commit messages.
- Commits should appear under the repo owner's account only.
- Don't auto-close GitHub issues from commit messages — use `Refs #N`, not `Closes #N`. The user closes issues themselves after verification.

## Roles

- **Human**: Adds sources to `raw/`, asks questions, directs analysis, reviews wiki pages, closes issues.
- **LLM**: Reads sources, writes and maintains all files in `wiki/`, updates index and log. After ingesting a source, moves it from `raw/` to `raw/archive/`.

## Directory Structure

```
your-wiki/
  CLAUDE.md                           # This file: rules + scope + project declarations
  README.md                           # Repo description for humans
  .instructions/
    core/                             # Data-agnostic methodology — works for any second brain
      prompts/    {customize-template,ingest,lint,clean-data,orphans,task-review,upgrade-from-template}.md
      rules/      {page-conventions,hot-cache-rules,index-rules,log-rules,overview-rules,tasks-rules,pdf-extraction}.md
      templates/  {source-summary,youtube-source,pdf-source,person-page}.md
    projects/                         # Project-specific methodology (declared per-wiki below)
    tools/                            # ⚠️ GITIGNORED — per-installation helpers
  raw/                                # Source documents (gitignored)
    archive/                          #   already-ingested sources
    assets/{,/archive/}               #   image/PDF attachments + their archive
  wiki/                               # LLM-generated and LLM-maintained markdown
    {hot,index,log,overview,tasks}.md # State files (read hot.md first)
    people/   orgs/   tools/   open-source/   # Generic entity folders
    concepts/ analyses/ sources/      # Generic concept/analysis/document folders
```

**Project-specific subdirectories**: if your wiki needs structured tracking beyond standard source ingest (e.g., recipe testing, hardware benchmarks, paper reading lists), declare them here in this tree and put their methodology under `.instructions/projects/<name>/`. The `customize-template` prompt scaffolds these for you during onboarding. **Nothing project-specific belongs in `.instructions/core/`.**

## Reusable prompts

The user invokes these by name (e.g. *"run the ingest prompt"*). Each one is a complete, self-contained protocol — **read the prompt file when invoked, do not summarize from memory.**

| Scope | Prompt | Path | Purpose |
|---|---|---|---|
| core | Customize Template | `.instructions/core/prompts/customize-template.md` | One-time onboarding for a fresh template clone (sets topic scope) |
| core | Upgrade From Template | `.instructions/core/prompts/upgrade-from-template.md` | Pull methodology updates from the upstream template repo |
| core | Ingest | `.instructions/core/prompts/ingest.md` | Add new sources from `raw/` into the wiki |
| core | Task Review | `.instructions/core/prompts/task-review.md` | Walk through open questions in `wiki/tasks.md` one at a time |
| core | Lint | `.instructions/core/prompts/lint.md` | Quality audit — duplicates, contradictions, stale content |
| core | Orphans | `.instructions/core/prompts/orphans.md` | Link-graph audit — orphaned pages and dangling links |
| core | Clean Data | `.instructions/core/prompts/clean-data.md` | Mechanical hygiene — frontmatter, naming, tags, encoding |

## Templates

| Scope | Template | Path |
|---|---|---|
| core | Source summary (base) | `.instructions/core/templates/source-summary.md` |
| core | YouTube source (extends base) | `.instructions/core/templates/youtube-source.md` |
| core | PDF source (extends base) | `.instructions/core/templates/pdf-source.md` |
| core | Person page | `.instructions/core/templates/person-page.md` |

## Rules

Detailed rules live in `.instructions/core/rules/`. Read on demand, not preemptively.

| File | Covers |
|---|---|
| `page-conventions.md` | Frontmatter, page types & folders, wikilinks, quality bar |
| `hot-cache-rules.md` | What goes in `wiki/hot.md` and what doesn't (500-word cap) |
| `overview-rules.md` | What goes in `wiki/overview.md` (1,500-word cap, synthesis only) |
| `index-rules.md` | Format and content of `wiki/index.md` |
| `log-rules.md` | Rolling-window changelog rules for `wiki/log.md` (10-entry cap; git is the historical record) |
| `tasks-rules.md` | What belongs in `wiki/tasks.md` (user-input items only) and how lint/task-review keep it pruned |
| `pdf-extraction.md` | How to detect/install/run a PDF→text tool and inject the result into the clipping MD |

## Querying the wiki

Read `wiki/hot.md` then `wiki/index.md`, then load only the relevant pages. Synthesize with citations. Optionally file the answer as an `analysis` page if the user agrees.

## Session Start Checklist

1. Read `CLAUDE.md` (this file).
2. Read `wiki/hot.md` — fast context, do not skip.
3. Read `wiki/index.md` — full page catalog.
4. Read all of `wiki/log.md` — recent activity (capped at 10 entries per `log-rules.md`).
5. Glance at `wiki/tasks.md` — note any open items relevant to the session.
6. Do **not** read individual wiki pages unless the user's request requires it.
7. Ask the user what they'd like to do: ingest, query, lint, or explore.