ShaheerKhawaja/setup-secondbrain

setup-secondbrain: Persistent Knowledge Layer

Scaffold a SecondBrain vault that persists knowledge across all Claude Code sessions and projects. Uses the PARA method (Projects, Areas, Resources, Archive) combined with an LLM-powered wiki layer.

The wiki is the product. Chat is just the interface.

---

Prerequisites

• Obsidian installed (optional but recommended for graph view)
• git available (for vault version control)

---

Setup Flow

Step 1: Gather User Context (no PII stored in code)

Ask the user these questions (one at a time, adapt based on answers):

1. "Where should the vault live?" Default: ~/SecondBrain
2. "What are your active projects?" (names + one-line descriptions)
3. "What domains do you work in?" (e.g., AI/ML, web dev, consulting, marketing)
4. "Any areas of ongoing responsibility?" (e.g., engineering, clients, ops)

Derive user identity from git config (NEVER hardcode):

USERNAME=$(git config --global user.name 2>/dev/null || echo "User")
EMAIL=$(git config --global user.email 2>/dev/null || echo "")

Step 2: Scaffold Vault Structure

$VAULT_PATH/
  .raw/               # Immutable source documents (hidden in Obsidian)
  .obsidian/          # Obsidian config
    snippets/
  wiki/               # LLM-generated knowledge base
    index.md          # Master catalog
    log.md            # Chronological operation log
    hot.md            # Hot cache (~500 words, recent context)
    overview.md       # Executive summary
    sources/          # One summary per raw source
    entities/         # Products, people, orgs, repos
      _index.md
    concepts/         # Patterns, frameworks, mental models
      _index.md
    domains/          # Top-level topic areas
      _index.md
    comparisons/      # Side-by-side analyses
    questions/        # Filed answers
    meta/             # Dashboards, lint reports
  00-Inbox/           # PARA: temporary capture
  01-Projects/        # PARA: active initiatives (one folder per project)
  02-Areas/           # PARA: ongoing responsibilities
  03-Resources/       # PARA: reference materials
  04-Archive/         # PARA: completed/inactive
  05-Templates/       # Note templates
  Daily/              # Daily notes
  Sessions/           # Claude Code session logs
  Handoffs/           # Session handoff documents
  _attachments/       # Images, PDFs

Step 3: Create CLAUDE.md in Vault

Use this template (substitute user values):

# $VAULT_NAME: LLM Wiki + PARA Second Brain

Mode: D (Personal) + C (Business)
Purpose: Persistent knowledge base for $USERNAME
Owner: $USERNAME
Created: $TODAY

## Structure
[paste folder map]

## Conventions
- All notes use YAML frontmatter: type, status, created, updated, tags (minimum)
- Wikilinks use [[Note Name]] format: filenames are unique, no paths needed
- .raw/ contains source documents: never modify them
- wiki/index.md is the master catalog: update on every ingest
- wiki/log.md is append-only: never edit past entries
- New log entries go at the TOP of the file

## Operations
- Ingest: drop source in .raw/, say "ingest [filename]"
- Query: ask any question -- Claude reads index first, then drills in
- Lint: say "lint the wiki" to run a health check
- Save: "/save" to file current conversation as a wiki note

Step 4: Create Domain Pages

For each domain the user listed, create wiki/domains/<slug>.md:

---
type: domain
title: "$DOMAIN_NAME"
created: $TODAY
updated: $TODAY
tags: [domain, $TAG1, $TAG2]
status: active
---

# $DOMAIN_NAME

[User's description]

## Products
- [[Product 1]] -- description
- [[Product 2]] -- description

## Key Architecture
[Populated from user's answers or left as TODO]

Step 5: Create Entity Pages

For each project/product, create wiki/entities/<slug>.md:

---
type: entity
title: "$ENTITY_NAME"
created: $TODAY
updated: $TODAY
tags: [entity, product, $TAG1]
status: active
entity_type: product
---

# $ENTITY_NAME

## Overview
| Field | Value |
|-------|-------|
| Repo | $REPO_PATH |
| Stack | $STACK |
| Domain | [[$DOMAIN]] |
| Status | $STATUS |

Step 6: Create PARA Notes

• 02-Areas/<area>.md for each ongoing responsibility
• 03-Resources/<resource>.md for reference materials
• 01-Projects/<project>/ folder for each active project

Step 7: Create Templates

Create 05-Templates/ with: entity.md, concept.md, domain.md, source.md, question.md, comparison.md, daily-note.md, session-log.md, handoff.md, research-note.md, project.md

Step 8: Wire Cross-Project References

For EACH project that has a CLAUDE.md, append:

## Wiki Knowledge Base
Path: $VAULT_PATH

When you need context not already in this project:
1. Read wiki/hot.md first (recent context, ~500 words)
2. If not enough, read wiki/index.md (full catalog)
3. If you need domain specifics, read wiki/domains/<relevant-domain>.md
4. Only then read individual wiki pages

Do NOT read the wiki for:
- General coding questions or language syntax
- Things already in this project's files or conversation
- Tasks unrelated to the current project

Step 9: Wire ProductionOS Integration

Register the vault path in ProductionOS config:

# In ~/.productionos/config/settings.json
{
  "secondbrain_path": "$VAULT_PATH",
  "secondbrain_auto_session_log": true,
  "secondbrain_hot_cache_update": "session_end"
}

Update stop-session-handoff.sh to:

1. Copy session summary to $VAULT_PATH/Sessions/
2. Update wiki/hot.md ONLY if session produced meaningful work (>3 commits or >5 file edits)
3. Copy handoff to $VAULT_PATH/Handoffs/

Step 10: Initialize Git

cd $VAULT_PATH
git init
echo ".obsidian/workspace.json" >> .gitignore
echo ".obsidian/cache/" >> .gitignore  
echo ".trash/" >> .gitignore
git add -A
git commit -m "chore: scaffold SecondBrain vault"

Step 11: Validate

Run these checks:

1. All frontmatter is valid YAML with required fields (type, title)
2. All wikilinks resolve to real files (exclude templates)
3. Cross-project CLAUDE.md refs point to existing paths
4. Read path simulation: hot.md -> index.md -> domain -> entity (measure tokens)
5. No PII patterns in committed files (emails, IPs, API keys, tokens)

Report results as pass/fail table.

---

Post-Setup Operations

After initial scaffold, the wiki grows through:

• Ingest: Drop documents in .raw/, say "ingest [filename]"
• Query: Ask questions -- answers get filed in wiki/questions/
• Session logs: Auto-captured at session end
• Hot cache: Updated after every meaningful session
• Lint: Say "lint the wiki" to find orphans, dead links, gaps

---

Security Rules

• NEVER store API keys, tokens, passwords, or secrets in the vault
• User identity comes from git config, not hardcoded values
• Vault .gitignore excludes workspace state and cache
• PII scan runs during validation step
• If vault is pushed to remote, ensure repo is PRIVATE