kb-bootstrap

name	kb-bootstrap
description	Initialize a new LLM-maintained knowledge base in the current directory. Use when the user wants to create, bootstrap, initialize, or set up a new knowledge base, KB, or wiki. Also triggers on "kb-bootstrap" or "/kb-bootstrap".

kb-bootstrap

Initialize a new LLM-maintained knowledge base in the current working directory.

Pre-flight Safety Checks

1. Check if AGENTS.md already exists in the current directory.
   • If it exists and contains <!-- kb:root --> on the first line, abort with: "This directory is already a knowledge base. Use --force to reinitialize."
   • If it exists without the marker, abort with: "AGENTS.md exists but is not a KB root. Refusing to overwrite. Use --force to proceed."
   • If --force was passed, warn the user and proceed after confirmation.
2. Check if CLAUDE.md exists. If so, warn that it will be replaced with a symlink.

Gather Input

3. Ask the user for a KB name (short, lowercase, hyphenated). Suggest a default based on the parent directory name.

Create Directory Structure

4. Create the following directories:

mkdir -p raw/assets wiki/entities wiki/concepts wiki/summaries wiki/synthesis wiki/deprecated output

Generate AGENTS.md

5. Write AGENTS.md with the following EXACT content (substitute {{KB_NAME}} and {{DATE}} with actual values):

<!-- kb:root -->
# {{KB_NAME}} Knowledge Base

> LLM-maintained knowledge base. This file is the authoritative schema reference.

## Directory Structure

- `raw/` — Append-only source archive. Never overwrite files here.
- `raw/assets/` — Binary assets referenced by sources.
- `wiki/entities/` — Entity pages (people, tools, companies, projects).
- `wiki/concepts/` — Concept pages (ideas, patterns, methodologies).
- `wiki/summaries/` — Source summaries (one per ingested source).
- `wiki/synthesis/` — Promoted query outputs and cross-cutting analyses.
- `wiki/deprecated/` — Tombstoned pages moved here during pruning.
- `output/` — Query results. Ephemeral, never modify wiki from here.

## Frontmatter Contract

Every wiki page MUST have this YAML frontmatter block:

```yaml
---
title: "Page Title"
type: entity | concept | summary | synthesis
source_ids:
  - raw/source-file.md
confidence: 0.8          # 0.0-1.0, event-driven updates only
stability: stable         # stable | permanent | evolving | volatile
human_reviewed: false     # true = write-protected from automation
created: YYYY-MM-DD
last_verified: YYYY-MM-DD
supersedes: []            # list of page paths this replaces
contradictions: []        # list of {page, claim, conflicting_claim}
tags: []
---
```

## Page Types

### entity
Represents a specific thing: person, tool, company, project, protocol.
- One entity per page.
- `stability: stable` or `permanent` for well-established entities.
- Update when new sources mention the entity.

### concept
Represents an idea, pattern, methodology, or principle.
- Captures the what and why, not just definitions.
- Link to entities that implement or relate to the concept.
- `stability: evolving` for concepts under active development.

### summary
One-to-one mapping with a raw/ source file.
- `source_ids` contains exactly one entry.
- Captures key claims, findings, and takeaways.
- `confidence` reflects source quality and recency.

### synthesis
Cross-cutting analysis combining multiple sources/pages.
- `source_ids` lists all contributing sources.
- Created by promoting query outputs or during contradiction resolution.
- Higher `confidence` requires more corroborating sources.

## Confidence Thresholds

| Level | Range | Meaning |
|-------|-------|---------|
| High | 0.8-1.0 | Multiple corroborating sources, recently verified |
| Medium | 0.5-0.79 | Single source or partially corroborated |
| Low | 0.2-0.49 | Weak evidence, needs verification |
| Minimal | 0.0-0.19 | Speculative or contested |

Confidence is EVENT-DRIVEN only. Update when:
- New corroborating source is ingested (increase)
- Contradicting source is ingested (decrease)
- Source is re-verified (adjust based on findings)
- NEVER decay confidence based on time alone

## Stability Definitions

- **permanent** — Facts unlikely to change (historical events, math).
- **stable** — Established and unlikely to change soon.
- **evolving** — Actively changing, expect updates.
- **volatile** — Rapidly changing, may be outdated quickly.

## Wikilinks and Cross-References

Use `[[page-name]]` wikilinks to connect pages. Dataview-style relationship fields:

```markdown
## Relationships
- related:: [[other-page]]
- implements:: [[concept-page]]
- part_of:: [[parent-entity]]
- depends_on:: [[dependency]]
- contradicts:: [[conflicting-page]]
- supersedes:: [[old-page]]
```

## Safety Rules

1. **human_reviewed: true** pages are write-protected. Never auto-edit them.
2. **raw/** is append-only. Never overwrite or delete raw source files.
3. **confidence** is event-driven. Never decay it based on time.
4. **Rebuilds are staged.** Always diff + confirm before applying changes.
5. **Mutating commands fail closed** outside a KB root directory.

## Commands

| Command | Mode | Purpose |
|---------|------|---------|
| kb-ingest | mutating | Add new source to KB |
| kb-reingest | mutating | Re-process updated source |
| kb-query | readonly | Query KB, save answer to output/ |
| kb-promote | mutating | Promote output to wiki/synthesis/ |
| kb-lint | readonly+ | Health check, optional auto-fix |
| kb-contradictions | mutating | Semantic contradiction sweep |
| kb-prune | mutating | Deprecate outdated content |
| kb-rebuild | mutating | Regenerate wiki from raw sources |

Create CLAUDE.md Symlink

6. Create a symlink from CLAUDE.md to AGENTS.md:

ln -sf AGENTS.md CLAUDE.md

Generate index.md

7. Write index.md in the KB root:

# {{KB_NAME}} — Index

> Auto-generated. Do not edit manually. Regenerated by `kb_index.py`.

Generated: {{DATE}}

## Entities

_No entities yet._

## Concepts

_No concepts yet._

## Summaries

_No summaries yet._

## Synthesis

_No synthesis pages yet._

## Statistics

- Total pages: 0
- Sources ingested: 0
- Last updated: {{DATE}}

Generate log.md

8. Write log.md in the KB root:

# {{KB_NAME}} — Activity Log

| Date | Action | Details |
|------|--------|---------|
| {{DATE}} | bootstrap | Knowledge base initialized |

Register the KB

9. Run the registry script:

python3 ~/.config/kb/scripts/kb_registry.py register --name "{{KB_NAME}}" --path "$(pwd)"

Initialize Git

10. Initialize a git repository if one does not already exist:

git init 2>/dev/null || true

11. Create a .gitignore if it does not exist, with:

.wiki-backup-*/
.wiki-rebuild-staging/

12. Make an initial commit:

git add -A
git commit -m "feat: initialize {{KB_NAME}} knowledge base"

Final Output

Print a summary:

• KB name and path
• Directory structure created
• Number of files generated
• Next step suggestion: "Use /kb-ingest to add your first source."