wiki-setup

name

wiki-setup

description

Initialize a new Obsidian wiki vault with the correct structure, special files, and configuration. Use this skill when the user wants to set up a new wiki from scratch, initialize the vault structure, create the .env file, or says things like "set up my wiki", "initialize obsidian", "create a new vault", "get started with the wiki". Also use when the user needs to reconfigure their existing vault or fix a broken setup.

Obsidian Setup — Vault Initialization

You are setting up a new Obsidian wiki vault (or repairing an existing one).

Step 0: Detect AGENTS.md Profile (vault override)

Before running any of the framework defaults below, check whether the target vault already has an AGENTS.md defining its own categories. This is how project-specific vaults (e.g. MemoryLane) override the generic structure.

1. After Step 1 resolves OBSIDIAN_VAULT_PATH, check for $OBSIDIAN_VAULT_PATH/AGENTS.md.
2. If it exists, read it and look for a Categories table (markdown table with a Category and Path column).
3. If found, extract (category_name, path) rows. The path column tells you the on-disk folder for that category (use the directory portion — e.g. moments/<moment_id>.md → moments/).
4. The categories from AGENTS.md are now authoritative for this run. Substitute them everywhere this skill mentions framework defaults (concepts/, skills/, references/, projects/, etc.).

Reference example — the MemoryLane vault declares:

Category	Path
moment	moments/<moment_id>.md
session	sessions/<session_id>.md
journal	journal/<YYYY-MM-DD>.md
entity	entities/{people,places,objects}/<slug>.md
synthesis	synthesis/<slug>.md

Resulting folders to create: moments/, sessions/, journal/, entities/people/, entities/places/, entities/objects/, synthesis/. Plus the framework-required infrastructure: _archives/, _raw/, _meta/, .obsidian/. AGENTS.md may also specify subdirectories (e.g. MemoryLane requires _raw/failed/); honor those too.

If AGENTS.md does not exist or has no Categories table, fall through to the framework defaults in Step 2.

Step 1: Create .env

If .env doesn't exist, create it from .env.example. Ask the user for:

1. Where should the vault live? → OBSIDIAN_VAULT_PATH

   • Default: ~/Documents/obsidian-wiki-vault
   • Must be an absolute path (after expansion)

2. Where are your source documents? → OBSIDIAN_SOURCES_DIR

   • Can be multiple paths, comma-separated
   • Default: ~/Documents

3. Want to import Claude history? → CLAUDE_HISTORY_PATH

   • Default: auto-discovers from ~/.claude
   • Set explicitly if Claude data is elsewhere

4. Have QMD installed? → QMD_WIKI_COLLECTION / QMD_PAPERS_COLLECTION

   • Optional. Enables semantic search in wiki-query and source discovery in wiki-ingest.
   • If unsure, skip for now — both skills fall back to Grep automatically.
   • Install instructions: see .env.example (QMD section).

Step 2: Create Vault Directory Structure

If Step 0 found AGENTS.md categories, build the mkdir command from those paths plus the framework infrastructure folders. Example for MemoryLane:

mkdir -p "$OBSIDIAN_VAULT_PATH"/{moments,sessions,journal,synthesis,entities/people,entities/places,entities/objects,_raw/failed,_archives,_meta,.obsidian}

Otherwise, use the framework defaults:

mkdir -p "$OBSIDIAN_VAULT_PATH"/{concepts,entities,skills,references,synthesis,journal,projects,_archives,_raw,_meta,.obsidian}

Common to both:

• .obsidian/ — Obsidian's own config. Creates vault recognition.
• _archives/ — Stores wiki snapshots for rebuild/restore operations.
• _raw/ — Staging area for unprocessed drafts. (For MemoryLane, _raw/failed/ is for failed-ingest moments and is not indexed — see AGENTS.md.)
• _meta/ — Holds taxonomy.md (controlled tag vocabulary) and .base dashboard files.

Default-only folders (skip when AGENTS.md is in use):

• projects/ — Per-project knowledge (only meaningful when wiki-update is the ingest path).

Step 3: Create Special Files

index.md

Build the section headers from the categories you decided on in Step 0.

For AGENTS.md-driven vaults (use one ## section per category, in the order they appear in the table). Example for MemoryLane:

---
title: Wiki Index
---

# Wiki Index

*This index is automatically maintained. Last updated: TIMESTAMP*

## Moments

*No moments yet. The §7.5 analysis pipeline writes them directly into `moments/`.*

## Sessions

## Entities

### People

### Places

### Objects

## Synthesis

## Journal

For framework-default vaults:

---
title: Wiki Index
---

# Wiki Index

*This index is automatically maintained. Last updated: TIMESTAMP*

## Concepts

*No pages yet. Use `wiki-ingest` to add your first source.*

## Entities

## Skills

## References

## Synthesis

## Journal

log.md

---
title: Wiki Log
---

# Wiki Log

- [TIMESTAMP] INIT vault_path="OBSIDIAN_VAULT_PATH" categories=<comma-separated list of the categories you actually created>

.manifest.json

Create an empty manifest at the vault root so subsequent skills can read it without first having to handle the missing-file case:

{
  "version": 1,
  "last_updated": "TIMESTAMP",
  "sources": {},
  "projects": {},
  "stats": {
    "total_sources_ingested": 0,
    "total_pages": 0,
    "total_projects": 0,
    "last_full_rebuild": null
  }
}

hot.md

---
title: Hot Cache
updated: TIMESTAMP
---

# Hot Cache

*A ~500-word semantic snapshot of recent activity. Updated after every major write operation.*

## Recent Activity

- [TIMESTAMP] INIT — vault created at OBSIDIAN_VAULT_PATH

## Active Threads

*None yet — start ingesting sources to populate.*

## Key Takeaways

*None yet.*

## Flagged Contradictions

*None yet.*

Step 4: Create .obsidian Configuration

Create minimal Obsidian config for a good out-of-box experience:

.obsidian/app.json

{
  "strictLineBreaks": false,
  "showFrontmatter": false,
  "defaultViewMode": "preview",
  "livePreview": true
}

.obsidian/appearance.json

{
  "baseFontSize": 16
}

Step 5: Recommend Obsidian Plugins

Tell the user about these recommended community plugins (they install manually):

1. Dataview — Query page metadata, create dynamic tables. Essential for a wiki.
2. Graph Analysis — Enhanced graph view for exploring connections.
3. Templater — If they want to create pages manually using templates.
4. Obsidian Git — Auto-backup the vault to a git repo.

Step 6: Verify Setup

Run a quick sanity check. The exact folder list depends on Step 0:

• All category folders from Step 2 exist
• _archives/, _raw/, _meta/, .obsidian/ exist
• index.md exists at vault root
• log.md exists at vault root
• hot.md exists at vault root
• .manifest.json exists at vault root
• .env has OBSIDIAN_VAULT_PATH set
• If AGENTS.md was present, confirm its filename is preserved (do not overwrite or move it)

Report the results.

For AGENTS.md-driven vaults, the next-steps message should match the vault's actual ingest path (per AGENTS.md). For example, MemoryLane's AGENTS.md says wiki-ingest is not used — moments arrive pre-distilled from the §7.5 pipeline. So suggest:

1. Open the vault in Obsidian (File → Open Vault → select the directory)
2. Wire the §7.5 pipeline to write into moments/ per docs/ingest_contract.md
3. Run wiki-status after the first batch arrives
4. Run cross-linker periodically to weave entities into moments

For framework-default vaults, suggest:

1. Open the vault in Obsidian (File → Open Vault → select the directory)
2. Run wiki-status to see what's available to ingest
3. Run wiki-ingest to add their first sources
4. Run claude-history-ingest / codex-history-ingest to mine session history
5. Run wiki-status again anytime to check the delta