# Second Brain — LLM Wiki Schema

# Second Brain — LLM Wiki Schema

This is a personal knowledge base maintained by an LLM following the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern. The LLM builds and maintains the wiki; the human curates sources and directs exploration.

## Directory Structure

```
second-brain/
├── CLAUDE.md              # this file — schema and conventions
├── meta/                  # docs about the wiki itself (pattern, writing style, etc.)
├── sources/               # raw, immutable source documents (never modified by LLM)
│   └── ingested-urls.md   # URLs fetched from terminal that need manual backup
├── inbox/                 # Obsidian web clips landing here for processing
├── inbox-processed/       # clips moved here after ingest (backup, not deleted)
├── inbox-assets/          # staging for clip attachments; drained into sources/assets/
├── toolbox/               # tool/project pages (type: toolbox)
├── books/                 # book pages (type: book)
└── wiki/                  # LLM-maintained markdown pages
    ├── index.md           # content catalog — updated on every ingest
    └── log.md             # append-only activity log
```

The `meta/` directory holds documents that define how the wiki works — the LLM Wiki pattern description, writing style guides, etc. These are not knowledge base content; they shape how content gets written. Read them before writing wiki pages.

The `inbox/` directory is where Obsidian web clips land. During inbox processing, each clip gets ingested normally, then moved to `inbox-processed/` (never deleted — it's our backup).

`inbox-assets/` is where the Obsidian web clipper drops images and attachments. It is a staging area, not a resting place: ingest moves anything it finds there into `sources/assets/`, which is the only directory attachments are linked from. Expect `inbox-assets/` to be empty between ingests — it has been empty since it was created, because every clip so far has been text.

The `sources/ingested-urls.md` file tracks URLs that were fetched directly from the terminal during ingest. These exist only as saved markdown in `sources/` and should be manually clipped/backed up when convenient.

## Writing Style

Wiki pages are meant to be read by a human and parsed by a machine. Write naturally:

- Use plain, direct language. Avoid AI-isms: "delve", "leverage", "robust", "tapestry", "landscape", "ecosystem", "harness", "streamline", "utilize".
- Don't inflate stakes or use false drama. Say what something is, not how world-changing it is.
- No filler transitions ("It's worth noting", "Let's break this down", "Here's the thing").
- No fractal summaries — don't tell the reader what you're about to say, then say it, then say what you said.
- No bold-first bullet lists. No rhetorical questions answered in the next line.
- Vary sentence length and structure. Short sentences are fine. So are longer ones that develop an idea.
- When a page covers a list of items, write about them — don't just reformat the source as bullets.
- Prefer concrete examples over abstract descriptions.

For a full catalog of tropes to avoid, see `meta/tropes.md`. To check a published page against these tropes, use [tropes.fyi/vetter](https://tropes.fyi/vetter) — paste a URL and it flags AI-sounding patterns.

## Glossary

Use these terms consistently. Don't mix with alternatives.

| Use | Don't use |
|-----|-----------|
| LLM | large model, foundation model, large language model |
| RAG | Retrieval-Augmented Generation, retrieval augmented generation |
| Claude Code | CC, claude-code, Anthropic's coding tool |
| frontmatter | YAML header, metadata, file header |
| wikilink | bidirectional link, backlink (backlink is the reverse direction) |
| vault | knowledge base (when referring to Obsidian specifically) |
| ingest | import, add, process (for the source→wiki workflow) |
| Golang | Go (ambiguous in search), golang |

## Conventions

### Obsidian Compatibility

This vault is designed to be opened directly in Obsidian. All markdown follows Obsidian conventions:

- Wikilinks: `[[page-name]]` (Obsidian resolves by filename across all folders)
- Aliased links: `[[page-name|display text]]` when the filename isn't readable enough
- Tags: use `tags:` in YAML frontmatter as a list, and `#tag` inline where natural
- Embeds: `![[page-name]]` to embed another page's content
- Images: store in `sources/assets/`, reference as `![[image-name.png]]`
- No `# Title` heading if it duplicates the frontmatter `title:` — Obsidian shows the title from properties

### Page Format

Every wiki page uses YAML frontmatter (Obsidian Properties):

```markdown
---
title: Page Title
type: summary | entity | concept | comparison | analysis | overview | toolbox | catalog | log
summary: One-sentence abstract of what this page covers
parent: "[[parent-page]]"
tags:
  - topic-tag
sources:
  - "[[source-filename]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

Content here. Link to other wiki pages with [[page-name]].
Cite sources with [[source-filename]].
```

Page types: `summary`, `entity`, `concept`, `comparison`, `analysis`, `overview`, `toolbox`, `book`, `catalog`, `log`.

The `summary:` field lets me scan pages without reading full content. Keep it under 100 characters — imagine answering "what's this page about?" in one breath. It is also what a stranger sees when the vault is served as a site, so write it as a search-result line rather than a note to self.

### Catalog and Log Pages

Two page types are structural rather than content: `catalog` for the four `index.md` files, `log` for `wiki/log.md`. They link to nearly every other page — the four catalogs plus the log carry about a third of every wikilink in the vault — so counting their links makes backlink counts meaningless and orphan detection impossible. A page listed in `wiki/index.md` always has an inbound link, whether or not anything actually refers to it.

Link metrics therefore ignore them: when counting inbound links or looking for orphans, skip every page whose `type:` is `catalog` or `log`. Any future catalog page has to carry `type: catalog` for the same reason.

The `aliases:` field is optional and natively supported by Obsidian. Use it to keep an old filename resolving after a rename, since the filename stem is also the page's URL when the vault is served. It widens search matching too — a page can be found under a name nobody chose as its filename.

```markdown
aliases:
  - old-page-name
  - Full Product Name
```

### Parent Field

The `parent:` field is optional. Use it to nest pages under broader topics:

```markdown
parent: "[[networking]]"
```

This creates a hierarchy without moving files into folders. Obsidian resolves the wikilink normally. Use `parent:` when a page clearly belongs under a broader concept or overview page. Don't force it — flat pages with cross-references are fine when there's no natural parent.

### Updated Date

Always bump `updated:` to today's date when revising an existing page (adding new information, correcting claims, adding cross-references). Do not bump it for trivial formatting changes. The `created:` date never changes.

### Toolbox Pages

Toolbox pages describe interesting projects/tools for potential future use. Frontmatter includes extra fields:

```markdown
---
title: tool-name
type: toolbox
summary: One-sentence abstract of what this tool is and what makes it distinct
tags:
  - language
  - domain
repo: https://github.com/owner/repo
language: Go
license: MIT
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

Content should cover:
- What the tool does (one paragraph)
- How it works technically (architecture, key design decisions)
- Basic usage examples with code blocks
- Limitations or platform constraints
- Repo link with star count and license at the end

No source file needed — the repo URL in frontmatter is the source. Cross-reference related concept or entity pages where relevant.

### Book Pages

Book pages cover long-form works — books, monographs, multi-part essays. Live in `books/`. Frontmatter:

```markdown
---
title: Book Title
type: book
summary: One-sentence abstract of what the book argues or contains
author: Author Name
year: YYYY
isbn: optional
url: https://publisher.example/book   # canonical publisher / free-distribution page
tags:
  - topic-tag
status: reading | finished | want-to-read | abandoned
rating: 1-5 (optional, only after finishing)
sources:
  - "[[source-filename]]"
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```

Additional optional fields can be added when relevant — e.g., `cohort:` linking to a reading-group discussion page, or `pdf:` for a freely-available PDF. Keep them lowercase and snake_case.

Content should cover:
- One paragraph: what the book argues or contains
- Key ideas or claims (concept pages get extracted from these over time)
- Chapter notes — only where worth keeping, not a full ToC
- Quotes worth keeping, with page numbers where available
- How it relates to other books or wiki concepts (lineage, contrasts)

A book page may be created in `want-to-read` status with just the front matter and a short why-I-want-this paragraph. Update `status:` and bump `updated:` as the read progresses. After finishing, the concept pages that came out of the book are the primary deliverable — the book page itself is the index, not the substance.

Add new entries to the appropriate section of `books/index.md`. No source file is required for `want-to-read`; for `reading` and `finished`, link any reviews or excerpts under `sources:`.

### Watchlist

`toolbox/watchlist.md` tracks toolbox entries that aren't yet ready to commit to — alpha-stage projects, single-author repos, single-platform tools, anything dependent on outside circumstances. The point is to come back periodically and re-decide: graduated, abandoned, or still waiting.

When a toolbox page meets watchlist criteria:

1. Add `watchlist` to its frontmatter `tags:`
2. Add a row to the table in `toolbox/watchlist.md` with: tool wikilink, what we're waiting on, next-check date (default 90 days out), reason
3. Mention the watchlist in the toolbox page itself (one line, link to `[[toolbox/watchlist]]`)

When re-checking, evaluate: activity in last 90 days, star trajectory, release cadence, author bandwidth, platform breadth, whether the README still says "alpha", competitor consolidation. Move graduated tools to the Graduated section, abandoned ones to Abandoned, and drop the `watchlist` tag in either case.

### Naming

- All filenames: `kebab-case.md` (e.g., `llm-wiki-pattern.md`)
- Source filenames: preserve original name where possible
- Short, descriptive names — no dates in filenames
- Prefer names that are unique across all directories — Obsidian resolves `[[links]]` by filename, so a name used twice makes every bare link to it ambiguous

Uniqueness is what lets a page be addressed by its stem alone. `[[raft]]` only means one thing if exactly one `raft.md` exists, and the same stem becomes the page's URL when the vault is served. A duplicate name costs a folder prefix on every link; a rename costs every existing link and address pointing at the old one, which is what `aliases:` is for.

Uniqueness is a goal, not a fact. About 110 names are currently used twice, plus the four `index.md`. Nearly all of the duplicates are a `wiki/` or `toolbox/` page and the `sources/` document it was written from, which is deliberate and worth keeping — the source is named after the page it produced.

Where a name is reused, put the folder in the link: `[[sources/lsm-trees-nosql]]` for the clipped article, `[[lsm-trees-nosql]]` for the page written from it.

A bare `[[name]]` resolves nearest first: a file in the same folder, then the same top-level directory, then the rest of the vault in the order vault root, `wiki/`, `toolbox/`, `books/`, `meta/`, `sources/`. That order also decides URLs when the vault is served — the wiki page keeps the short one and the source falls back to `sources/<name>` — so renaming a page changes its address. Non-markdown attachments need their extension in the link (`[[paper.pdf]]`, not `[[paper]]`).

### Cross-References

- Link between pages with `[[page-name]]` — works across folders automatically
- When updating a page, check for and add relevant cross-references
- Every page should have at least one inbound link (no orphans — check via Obsidian graph view)

### Deliberate Gaps

A wikilink pointing at a page that does not exist is a defect by default. The exception is a link that is correct and simply ahead of the page — deleting it would erase the record that something is missing.

Declare those in `[[planned-pages]]`, which carries them in a `planned:` frontmatter list and explains each one in a table. `warren check` accepts a dangling wikilink only when some page declares its target, fails on anything else outside `sources/`, and warns when a declaration starts resolving so the list gets pruned rather than growing into a permanent allowlist. Any page may carry `planned:`, but keeping them in one place is what makes the gaps reviewable.

Do not write a stub to make a link resolve. An empty page is worse than a declared gap, because it stops looking like one.

Dangling links inside `sources/` are expected and are not gated. Clipped articles and READMEs point at paths in the repository they came from, and `sources/` is immutable, so nothing can clear them.

### index.md

Organized by page type. Each entry is one line:

```markdown
## Summaries
- [[page-name]] — one-line description

## Entities
- [[page-name]] — one-line description

## Concepts
- [[page-name]] — one-line description
```

(Same pattern for Comparisons, Analyses, Overviews, Toolbox.)

### log.md

Append-only. Each entry:

```markdown
## [YYYY-MM-DD] action | Title
Brief description of what was done. List pages created/updated.
```

Actions: `ingest`, `query`, `lint`, `update`.

## Workflows

### Ingest

1. Read the source document fully
2. Discuss key takeaways with the user
3. Create a summary page in `wiki/`
4. Create or update entity/concept pages as needed
5. Add cross-references to/from existing pages
6. Update `wiki/index.md`
7. Append entry to `wiki/log.md`

### Query

1. Read `wiki/index.md` to find relevant pages
2. Read relevant wiki pages
3. Synthesize an answer with citations
4. If the answer is substantial and reusable, offer to save it as an analysis page

### Inbox Processing

1. List files in `inbox/`
2. For each clip, read it and ingest normally (summary + entity/concept pages)
3. After successful ingest, move the clip from `inbox/` to `inbox-processed/`
4. Never delete inbox files — `inbox-processed/` is the backup
5. Update `wiki/index.md` and `wiki/log.md` as usual

### URL Backup

When ingesting from a URL in the terminal (not from `inbox/`), append the URL to `sources/ingested-urls.md`. Mark status as `pending` — the user will manually back these up and mark them `done`.

### Lint

1. Read `wiki/index.md` and all wiki pages
2. Report:
   - Contradictions between pages
   - Orphan pages (no inbound links)
   - Stale claims superseded by newer sources
   - Concepts mentioned but lacking their own page
   - Missing cross-references
   - Content gaps worth investigating
3. Fix issues with user approval
4. Append lint entry to `wiki/log.md`