Second Brain — LLM Wiki Schema

This is a personal knowledge base maintained by an LLM following the LLM Wiki 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 — paste a URL and it flags AI-sounding patterns.

Glossary

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

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):

---
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.

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

Parent Field

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

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:

---
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:

---
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:

## 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:

## [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