sb-setup

name	sb-setup
description	Scaffold a new LLM Wiki project. Use when asked to "setup wiki", "create wiki", "init wiki", "start new wiki", "new knowledge base". Creates directory structure, AGENTS.md, and scripts.

LLM Wiki Setup

Scaffold a new LLM Wiki project with proper directory structure, AGENTS.md template, and Python scripts.

Prerequisites

1. Confirm wiki root location with user (default: current directory)
2. Confirm wiki name and domain/purpose

Step 1: Create Directory Structure

Create the following directories under the wiki root:

raw/
  articles/
  papers/
  podcasts/
  books/
  notes/
  assets/
wiki/
  entities/
  concepts/
  sources/
  synthesis/
scripts/

Run:

mkdir -p raw/{articles,papers,podcasts,books,notes,assets}
mkdir -p wiki/{entities,concepts,sources,synthesis}
mkdir -p scripts

Step 2: Create AGENTS.md

Generate AGENTS.md with these sections filled in:

# AGENTS.md — [Wiki Name]

## Wiki Overview
- **Domain**: [user-provided]
- **Purpose**: [user-provided]
- **Scope**: [what belongs here vs. outside]

## Directory Structure
- `raw/` — immutable source documents (articles, papers, podcasts, books, notes, assets)
- `wiki/` — LLM-generated pages
  - `entities/` — people, places, organizations
  - `concepts/` — ideas, topics, methods
  - `sources/` — summary pages for each ingested source
  - `synthesis/` — ideas/explorations derived from wiki
  - `index.md` — catalog of all pages
  - `log.md` — chronological append-only log

## Naming Conventions
- **Slugs**: kebab-case only (e.g., `neural-networks`, `attention-is-all-you-need`)
- **Page names**: globally unique across entire wiki
- **Categories**: use folder prefix (entities/, concepts/, etc.)
- **Never**: Title Case, snake_case, or spaces in slugs

## Link Syntax
- Wikilinks: `[[slug]]` (e.g., `[[neural-networks]]`)
- Link to heading: `[[slug#heading]]`
- Link to alias: `[[slug|Display Text]]`
- **Always use kebab-case** inside wikilinks

## Page Format

### Frontmatter (YAML)
\`\`\`yaml
---
title: Page Title
tags: [tag1, tag2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [source-slug-1, source-slug-2]
---
\`\`\`

### Section Structure
\`\`\`markdown
# Page Title

## Summary

[2-3 sentence overview]

## Key Points

- [bullet 1]
- [bullet 2]

## Related

- [[related-slug]]
\`\`\`

## Workflow: Ingest

1. User drops source in `raw/[category]/`
2. Call `sb:ingest` skill
3. LLM interviews user (see ingest skill for details)
4. LLM creates pages breadth-first
5. Run post-edit script: `uv run scripts/ingest_post.py`
6. Script validates links, creates stubs, logs to `log.md`

## Workflow: Query

1. User asks question
2. Call `sb:query` skill
3. LLM searches wiki via `index.md` and page content
4. LLM synthesizes answer
5. Ask: "Save this to wiki?" if answer is valuable
6. If yes → save to `synthesis/`

## Workflow: Lint

1. User triggers lint: "lint the wiki"
2. Call `sb:lint` skill
3. Run lint script: `uv run scripts/lint.py`
4. Report findings to user
5. If user approves fixes → run with `--fix` flag

## Logging

- All operations logged to `wiki/log.md` by scripts only
- LLM never edits `log.md` directly
- Format: `## [YYYY-MM-DD] action | type | details`
- Log rotation: 1000 rows

## Index

- `wiki/index.md` catalog of all pages
- Updated automatically after every ingest
- Format: link + one-line summary per page

Replace [Wiki Name], [Wiki Name], [user-provided] placeholders with actual values from user.

Step 3: Create Initial Files

Create empty initial files:

• wiki/index.md — with header: # Wiki Index\n\n## Pages\n\n_(empty)_
• wiki/log.md — with header: # Wiki Log\n\n## Entries\n\n_(start of log)_\n
• .gitignore — see template below

# macOS
.DS_Store

# Editor
.obsidian/

# Logs (keep log.md but archive old ones)
wiki/log-archive/

# OS
Thumbs.db

Step 4: Create Initial Manifest

Create empty manifest file:

echo '{}' > wiki/manifest.json

This tracks which raw files have been ingested.

Step 5: Verify Setup

After scaffolding, verify:

1. All directories exist
2. AGENTS.md is complete
3. wiki/index.md, wiki/log.md, wiki/manifest.json exist
4. scripts/ directory is ready for skill scripts

Step 6: Copy Skill Scripts

Copy the script templates from each skill's scripts/ folder to scripts/:

• sb-ingest/scripts/ingest_post.py → scripts/ingest_post.py
• sb-ingest/scripts/list_raw.py → scripts/list_raw.py
• sb-lint/scripts/lint.py → scripts/lint.py
• (sb-query has no scripts currently)

Exit Criteria

• All directories created
• AGENTS.md populated with wiki-specific info
• Initial index and log files present
• Skill scripts copied and ready
• Inform user: "Wiki scaffolded. Drop your first source into raw/[category]/ and call sb:ingest."