Maintenance

Second Brain Maintenance

Kaleb's second brain is a monolithic single-repo knowledge base rendered as a

Notes are GitHub-flavored Markdown. Claude maintains these notes through conversations.

Obsidian is not used — never suggest it.

> ⚠️ Canonical source of truth: `domains/ai-tooling/SYSTEM_PROMPT.md`

> Read that file at the start of any second-brain session. This skill is a fast

> reference; SYSTEM_PROMPT.md wins on any conflict.

Single Repo — No External Repos

The second brain is monolithic. Previous external repos (`halden-city-wiki`,

`wood-home-cooking`) are retired and fully integrated. Do not reference or route

content to them.

Domains

All substantive content lives under `domains/`. Route here first. Do not duplicate into

`notes/personal/` unless it is reference context with no natural domain home.

Routing Table

Books Domain Rules (CRITICAL)

> ⚠️ A background worker automatically fetches book metadata from an API and generates

> full enriched `.md` files in `domains/books/` from bullet points in `MASTER_LIST.md`.

When Kaleb mentions a book to track:

1. Add a bullet to the appropriate section in `domains/books/MASTER_LIST.md`

2. Format: `- [Title] by [Author]`

3. Tell Kaleb the worker will auto-generate the enriched file on next sync

Music Domain Rules

> ⚠️ `domains/music/` is managed entirely by GitHub Actions + Spotify API.

> Do not create, edit, or delete files there. Treat as read-only.

Frontmatter (REQUIRED on every .md file)

Every markdown file must include YAML frontmatter. The React dashboard and `Cmd+K`

global search rely on this metadata. Never omit it.

```yaml

title: "Human Readable Title"

domain: worldbuilding # worldbuilding / cooking / health / novel / household / tools / entertainment / books / system

status: active # active / paused / loop

tags:

- tag-name

```

• Use `status: loop` (or include `loop` in tags) for open questions and unresolved items.

• Use `status: active` for current, maintained notes.
• Use `status: paused` for deprioritized content.

Worldbuilding Content Rules

When writing lore, character notes, or faction details under `domains/worldbuilding/`:

• Use wikilink syntax for cross-references: `Avi`, `A.E.G.I.S.`
• These links are functional in the React SPA — they resolve to other files
• Always check `domains/worldbuilding/DECISIONS.md` before a session to avoid

Halden City content lives at `domains/worldbuilding/halden-city/` with subfolders:

`characters/`, `factions/`, `locations/`, `lore/`, `plot/`, `images/`, `meta/`

Cooking Content Rules

All food/recipe content is native to `domains/cooking/`.

• Dashboard: The main entry point is `domains/cooking/index.md`.
• Recipes: `domains/cooking/recipes/`. Every file gets a graphical card on the `CookingGrid`.
• Meal Plans: `domains/cooking/meal-plans/YYYY-MM.md`. Use Markdown tables.
• Grocery Lists: `domains/cooking/grocery-lists/MASTER_LIST.md`. Use Markdown checkboxes.
• Rules:

- Avoid onions and tomatoes strictly.

- Do NOT use raw HTML for grocery lists; use the checklist format in `MASTER_LIST.md`.

Architecture Overview

The second brain is a Vite + React SPA. Understanding this is essential before

touching any source files.

Stack

How the build works

1. `generate-manifest.js` runs as the Cloudflare Pages build step

2. It walks the repo, reads git dates + frontmatter, outputs `public/manifest.json`

3. It copies every `.md` file into `public/` so Vite can serve them at runtime

4. Vite builds `src/` → `dist/` — this is what Cloudflare Pages serves

5. At runtime, `App.jsx` fetches `manifest.json`, builds the sidebar, fetches `.md` on demand

Source files

Domain metadata (colors)

```js

// generate-manifest.js — DEFAULT_DOMAIN_COLORS

const DEFAULT_DOMAIN_COLORS = {

worldbuilding: '#534ab7',

novel: '#993c1d',

household: '#185fa5',

health: '#3b6d11',

tools: '#993556',

entertainment: '#7a3f99'

};

```

To add a new domain color: add an entry here and re-run the build.

CSS design system

All in `src/index.css`. Use CSS custom properties — never hardcode colors.

File Structure

```

second-brain/

├── src/

│ ├── App.jsx — All React components

│ ├── index.css — All styles

│ └── main.jsx — React entry point

├── public/

│ ├── manifest.json — Auto-generated (DO NOT EDIT)

│ └── [all .md files] — Copied here by generate-manifest.js

├── dist/ — Vite build output (Cloudflare serves this)

├── generate-manifest.js — Build script

├── vite.config.js — Vite config

├── package.json — Dependencies

├── index.html — Vite HTML shell

├── domains/

│ ├── ai-tooling/ — Repository logic, system prompt, chat conventions

│ │ ├── skills/ — maintenance.md, specialized instructions

│ │ └── index.md — AI Hub Dashboard

│ ├── worldbuilding/ — halden-city/, sessions/, CONTEXT.md, DECISIONS.md

│ ├── novel/ — CONTEXT.md, PROGRESS.md, drafts/

│ ├── household/ — CONTEXT.md

│ ├── cooking/ — recipes/, meal-plans/, grocery-lists/, knowledge-base/

│ ├── health/ — GOALS.md

│ ├── entertainment/ — BACKLOG.md, WATCHED.md, CONTEXT.md

│ ├── books/ — MASTER_LIST.md (bullets only), auto-generated files

│ ├── tools/ — ROADMAP.md, DECISIONS.md (PAUSED)

│ └── music/ — GitHub Actions managed (DO NOT TOUCH)

├── notes/

│ ├── personal/ — profile, home-family, calendar-system, work-ibm,

│ │ finance-home, tech-tools, hobbies, writing, projects,

│ │ food-health

│ └── halden-city/ — Quick Halden City reference notes

├── maps/

│ ├── master-map.md — Navigation hub

│ └── halden-city-map.md — Halden City specific map

├── meta/ — System docs, conventions, this skill file

├── inbox/ — Unprocessed captures

└── journal/ — Dated entries

```

File Naming Conventions

• kebab-case for notes: `home-family.md`, `session-2026-04-01.md`
• ALLCAPS for core system files: `OPEN_LOOPS.md`, `PROJECTS.md`, `INBOX.md`, `MASTER_LIST.md`
• Date journal entries: `YYYY-MM-DD.md`
• Domain session logs: `domains/[domain]/sessions/YYYY-MM-DD.md`

Writing Style

• GitHub-flavored Markdown throughout
• Tables for structured data
• `##` / `###` headers for navigable sections
• Factual, reference-style prose — docs, not essays
• Include `Last updated: YYYY-MM-DD` in frequently-updated notes
• Relative cross-links: `Calendar System`
• Worldbuilding cross-references: wikilink syntax `Entity Name`

Sync Process

After writing or modifying `.md` content files:

```

D:\Kaleb\second-brain\sync.bat (double-click)

D:\Kaleb\second-brain\sync.ps1 (PowerShell, colored output)

```

Runs `git pull → git add → git commit → git push`.

Cloudflare Pages then runs `npm install && npm run build` and deploys to `dist/`.

Site live at brain.kaleb.one within ~60 seconds of push.

Exception: When `windows-mcp` filesystem access is available, Claude can write directly

and trigger sync via PowerShell.

Cloudflare Pages Build Reference

> ⚠️ The raw `vite` binary is not on Cloudflare's PATH — always go through npm.

master-map.md Update Protocol

• New file in existing domain → no update needed (manifest auto-discovers)
• New domain or new top-level concept →

2. Add section to `maps/master-map.md`

3. Update `domains/ai-tooling/repo-index.md`

Common Tasks

Add a worldbuilding session log

1. Create `domains/worldbuilding/sessions/YYYY-MM-DD.md` with required frontmatter

2. Use session summary format from `SYSTEM_PROMPT.md`

3. Check `DECISIONS.md` first — don't contradict locked lore

Add a recipe

1. Create `domains/cooking/recipes/[recipe-name].md`

2. Include frontmatter (`domain: cooking`, `status: active`)

3. Include calorie count, serving size, Gout ★ rating, Fatty Liver ★ rating

4. No nav update needed

Add a book to track

1. Edit `domains/books/MASTER_LIST.md`

2. Add `- [Title] by [Author]` to the correct section

3. Do not create individual book files — the background worker handles that

Capture to inbox

1. Append to `INBOX.md` or create `inbox/[descriptive-name].md`

2. Use frontmatter: `status: loop`

3. Flag for triage: "Added to inbox — process during next daily loop"

Update an existing note

1. Read the current file first

2. Append or merge — don't overwrite unless restructuring

3. Update `Last updated` date

4. No nav update needed

Add a new domain

1. Create `domains/[new-domain]/CONTEXT.md` with frontmatter

2. Add color to `DEFAULT_DOMAIN_COLORS` in `generate-manifest.js`

3. Add section to `maps/master-map.md`

4. Sync — manifest rebuild auto-adds all files to the nav

Edit the UI

1. Edit `src/App.jsx` or `src/index.css`

2. Do NOT run a local build

3. Sync — Cloudflare runs `vite build` automatically

Pre-Flight Checklist

Before writing any second brain files:

• Read `domains/ai-tooling/SYSTEM_PROMPT.md` — it is the canonical source of truth
• Is this domain-specific content? → Route to `domains/[domain]/`, not `notes/personal/`
• Books? → Bullet in `MASTER_LIST.md` only — no individual file
• Music? → Do NOT touch `domains/music/` — it's managed by GitHub Actions
• Does every new file have YAML frontmatter with `title`, `domain`, `status`, `tags`?
• Worldbuilding content? → Use wikilink syntax for cross-references
• Filename: kebab-case for notes, ALLCAPS for system files?
• Does `master-map.md` need updating? (Only for new domains or top-level concepts)
• Do NOT touch `public/manifest.json`, `index.html`, or `dist/`
• Have I told Kaleb to run `sync.bat`, or do I have filesystem access to do it?