init

You're helping the user set up a BrainLift workspace. The user should already be in the folder they want to use. This skill scaffolds the structure inside the current working directory.

What This Creates

[current directory]/
├── CLAUDE.md       # Workspace config + Claude Code project instructions
├── index.md        # Auto-generated catalog, evidence graph, source registry
├── lifts/          # BrainLift .md files go here
├── logs/           # Change logs (auto-generated by other skills)
└── sources/        # Optional: clipped raw source content

Plus a pointer file at ~/.brainlift so the plugin can find this workspace from any Claude Code session.

---

Workflow

Step 1: Confirm Location

Setting up a BrainLift workspace in:
  [absolute path to $CWD]

This will create:
  lifts/      — Your BrainLift files
  logs/       — Change logs (auto-managed)
  sources/    — Raw source content (optional)
  CLAUDE.md   — Workspace config

Continue?

If the user says no, ask where they'd like to set up instead and suggest they cd there first.

Step 2: Check for Existing Content

Before creating anything, scan $CWD for existing BrainLift files:

1. Glob *.md in $CWD (exclude any existing CLAUDE.md)
2. Read each file's first ~30 lines looking for a Purpose section (patterns: purpose, in scope, out of scope)
3. Files with a Purpose section are likely BrainLifts
4. Also check for companion *.log.md files

If existing BrainLift files are found:

I found [N] existing BrainLift files in this directory:

  - ai-agents.md (has Purpose section)
  - edge-computing.md (has Purpose section)
  - knowledge-management.md (has Purpose section)

And [N] companion log files:
  - ai-agents.log.md
  - edge-computing.log.md

Want me to move these into the new structure?
  - BrainLift files → lifts/
  - Log files → logs/
  - Other .md files stay where they are

[y/n]

Important: Only offer to move files that have a Purpose section. Don't move random markdown files. Show the user exactly which files will be moved and get approval before touching anything.

If there are .md files WITHOUT a Purpose section, note them:

These .md files don't look like BrainLifts (no Purpose section found):
  - random-notes.md
  - TODO.md

I'll leave these where they are.

Step 3: Create Structure

Create the directories and files:

1. Create lifts/ directory (if it doesn't exist)
2. Create logs/ directory (if it doesn't exist)
3. Create sources/ directory (if it doesn't exist)
4. Create CLAUDE.md with the workspace template (see below)
5. Create index.md with the empty index template (see infrastructure/index-format.md for the Empty Index Template)
6. Create ~/.brainlift containing the absolute path to $CWD

If CLAUDE.md already exists in $CWD, read it first. If it already has <!-- brainlift-root -->, this workspace is already initialized — do not bail out. Instead, proceed to Step 3B (Upgrade Check).

If CLAUDE.md exists but without the marker, ask before overwriting.

Step 3B: Upgrade Check (Already Initialized)

When CLAUDE.md already has <!-- brainlift-root -->, check what's missing and offer to add it:

Workspace already initialized. Checking for updates...

Check each component and report:

Checking workspace components:
  ✓ CLAUDE.md          — present
  ✓ lifts/             — present ([N] BrainLifts)
  ✓ logs/              — present
  ✓ sources/           — present
  ✗ index.md           — missing (new in v2.2)

Want me to add the missing components?

If index.md is missing: Generate it. If BrainLift files exist in lifts/, trigger a full index rebuild (Step 4B). If no BrainLifts exist, create the empty index template.

If CLAUDE.md is outdated (doesn't mention index.md): Offer to update it:

Your CLAUDE.md doesn't mention index.md (added in v2.2).
Want me to update it with the new workspace description?

If everything is present and current:

Workspace is up to date! Nothing to add.

Step 4: Migrate Files (if approved)

If the user approved migration in Step 2:

1. Move each identified BrainLift .md file from $CWD to lifts/
2. Move each companion .log.md file from $CWD to logs/
3. Use git mv if we're in a git repo, otherwise regular mv
4. Show what was moved:

Moved to lifts/:
  ai-agents.md
  edge-computing.md
  knowledge-management.md

Moved to logs/:
  ai-agents.log.md
  edge-computing.log.md

Step 4B: Full Index Rebuild (after migration or upgrade)

If BrainLift files exist in lifts/ (either migrated in Step 4 or already present during Step 3B upgrade), build the index:

1. For each BrainLift .md file in lifts/ (exclude *.log.md):
   • Spawn a brainlift-reader agent to parse the file
   • Extract: Purpose, DOK4 SPOVs (with anchor IDs if present), DOK3 Insights (with anchor IDs if present), source list, category list, expert count
2. Generate a complete index.md following the schema in infrastructure/index-format.md:
   • BrainLifts catalog with Purpose, stats, categories
   • Evidence Graph (using anchor IDs + Evidence lines if present, prose-based inference with Unknown status if not)
   • Source Registry with all sources across all BrainLifts
   • Workspace Stats
3. Write index.md to [root]/index.md

Building index from [N] BrainLifts...
  - ai-agents.md: 12 sources, 5 insights, 3 SPOVs
  - edge-computing.md: 8 sources, 3 insights, 2 SPOVs

Index generated with [N] sources, [N] insights, [N] SPOVs.

Step 5: Summary

BrainLift workspace ready!

  [absolute path]/
  ├── CLAUDE.md          ✓ created
  ├── index.md           ✓ created (catalog & evidence graph)
  ├── lifts/             ✓ created ([N] BrainLifts moved in)
  ├── logs/              ✓ created ([N] logs moved in)
  └── sources/           ✓ created (empty — for future use)

  ~/.brainlift           ✓ points here

Next steps:
  - Add a source:   /bl:update <url>
  - Ask a question:  /bl:query <question>
  - Health check:    /bl:lint
  - Create a new BrainLift: create a .md file in lifts/ with a Purpose section

For upgrade runs (Step 3B), show only what was added:

Workspace upgraded!

  Added:
  ├── index.md           ✓ generated ([N] BrainLifts indexed)

  Already present:
  ├── CLAUDE.md          ✓
  ├── lifts/             ✓ ([N] BrainLifts)
  ├── logs/              ✓
  └── sources/           ✓

---

CLAUDE.md Template

Write this content to CLAUDE.md:

<!-- brainlift-root -->
# BrainLift Workspace

Your BrainLift knowledge artifacts live here.

## Structure

- `index.md` — Auto-generated catalog of all BrainLifts, evidence graph, and source registry (read by plugin for navigation, viewable in Obsidian graph view)
- `lifts/` — BrainLift files (your knowledge artifacts)
- `logs/` — Change logs tracking how each BrainLift evolves
- `sources/` — Clipped raw source content (optional, for URL rot insurance)

## Commands

- `/bl:update <url> [thoughts]` — Add a source to a BrainLift
- `/bl:query [question]` — Ask questions against your BrainLifts
- `/bl:lint [path]` — Health-check a BrainLift
- `/bl:init` — Set up this workspace (already done)

## How It Works

The plugin handles bookkeeping (extracting facts, generating summaries, tracking evidence
chains, flagging stale content). You handle curation (what to include, what challenges your
thinking, what patterns you see across sources).

BrainLifts use the DOK framework:
- DOK1 (Facts) — AI extracts from sources
- DOK2 (Summaries) — AI generates, you review/edit
- DOK3 (Insights) — AI brainstorms with evidence, you accept/edit/reject
- DOK4 (SPOVs) — AI brainstorms candidates, you decide your positions

---

Error Handling

• Directory not empty but no BrainLifts found: Proceed normally — the user may want to start fresh
• ~/.brainlift already exists: Overwrite it (the user is choosing a new workspace location)
• Permission errors on ~/.brainlift: Warn the user, continue without the pointer file — discovery Step 1 (CLAUDE.md marker) will still work when they're in the workspace
• Already initialized: If CLAUDE.md already has the marker, run Step 3B (Upgrade Check) to add any missing v2.2 components (index.md, etc.) instead of bailing out
• Not a git repo: That's fine — everything works without git. Just use regular file operations instead of git mv.

Rules

• Never create files silently. Always show what will be created and get confirmation.
• Never move files without approval. Migration is opt-in.
• Never overwrite existing CLAUDE.md without asking. It may have user content.
• Keep it fast. This should take < 30 seconds. Don't over-explain.