---
title: "How to bootstrap and audit a vault"
slug: "bootstrap-a-research-vault"
category: "howto"
tags: ["howto", "knowledge-vaults", "obsidian", "audit", "tutorial", "python"]
status: "stable"
last_updated: 2026-09-01
summary: "Generate an Obsidian vault from a spec with the vault-architect scripts, run its auditor, close the autofix loop, and build the semantic-audit bundle."
related: ["[[knowledge-vaults/vault-architecture]]", "[[knowledge-vaults/vault-audit]]", "[[knowledge-vaults/audit-rule-catalog]]", "[[knowledge-vaults/semantic-audit]]", "[[knowledge-vaults/vault-orchestration]]", "[[knowledge-vaults/vault-frontmatter-schema]]", "[[tooling/obsidian-plugins]]", "[[howto/set-up-claude-code]]"]
---

## Overview

The `vault-architect` skill holds the tooling behind the Knowledge Vaults pages: a generator that turns a spec into a vault, an auditor that lives inside the vault, and a bundler for the semantic pass. This guide runs all three on a fresh vault. Every command below was run and its output checked before being written down. The result is the structure described in [[knowledge-vaults/vault-architecture]].

## Prerequisites

- Python 3.8 or later. The scripts are standard library only.
- Git, so the vault has an undo.
- The `vault-architect` skill from the `axia-claude-skills` repository, which is private at the time of writing. Install it as a Claude Code plugin (`/plugin marketplace add AXIA-Enterprises/axia-claude-skills`, then `/plugin install vault-architect@axia-skills`) or clone the repository and point `SK` at the skill folder:

```bash
export SK=./skills/axia-authored/vault-architect
```

- Obsidian with Dataview and Templater, per [[tooling/obsidian-plugins]].

## Steps

### 1. Write the Architecture Spec

The generator consumes one YAML file. `vault` and `note_types` are required. Each note type declares its folder, filename pattern, and required frontmatter fields, as in [[knowledge-vaults/vault-frontmatter-schema]]. Only the types you list are scaffolded.

```yaml
vault:
  name: "Research Vault"
  owner: "Your name"
  scope: "Evidence-backed notes on retrieval and embeddings"
  framework_primary: claim-evidence-counter

note_types:
  atom:
    folder: 20-Atoms
    filename_pattern: "^[a-z0-9]+(-[a-z0-9]+)+$"
    required: [id, title, type, status, created, modified, confidence]
  source:
    folder: 10-Sources
    filename_pattern: "^@[a-z]+-\\d{4}-[a-z0-9-]+$"
    required: [id, title, type, source_type, created, atoms_extracted]
  moc:
    folder: 30-Maps
    filename_pattern: "^MOC-[a-z0-9-]+$"
    required: [id, title, type, status, created, modified]

folders: [00-Inbox, 90-Templates, 99-Archive, 99-Tools, _attachments]
```

### 2. Dry-run the plan

```bash
python3 $SK/scripts/bootstrap_vault.py spec.yaml --out vault --check
```

`--check` prints every folder and file it would create and writes nothing. Confirm the last line reads `audit.py installed: True`.

### 3. Generate the vault, seeded and verified

```bash
python3 $SK/scripts/bootstrap_vault.py spec.yaml --out vault --seed --verify
```

`--seed` writes one cross-linked atom and source pair to copy from. `--verify` audits the result and exits non-zero unless it is clean. Expect `verify PASSED` with 0 critical, 0 warning.

### 4. Put it in Git and open it

```bash
cd vault && git init && git add -A && git commit -m "Bootstrap vault"
```

Open it in Obsidian; `dashboard.md` holds the quality-gate queries, `90-Templates/` the templates.

### 5. Run the first audit from the vault root

```bash
python3 99-Tools/audit.py --format both
```

Reports land in `99-Tools/audits/`: `AUDIT.md` to read, `audit.json` to reason over, `log.md` as the trend. Confirm `summary.spec_status` in the JSON is `loaded`; anything else means a defaults-only run, per [[knowledge-vaults/vault-audit]].

### 6. Close the autofix loop

```bash
python3 99-Tools/audit.py --fix              # dry run: prints the plan, writes nothing
python3 99-Tools/audit.py --fix --apply      # writes; refuses a vault that is not in Git
python3 99-Tools/audit.py --quiet            # re-audit and read the delta
```

`--fix` repairs only the mechanical tier in [[knowledge-vaults/audit-rule-catalog]].

### 7. Assemble the semantic bundle

```bash
python3 $SK/scripts/semantic_prep.py --vault-root . --sample 40
```

This writes `99-Tools/semantic-bundle.json`: candidate notes ordered by the deterministic flags they tripped, plus the rubric and output schema. Hand it and the skill's `references/semantic-audit.md` to the judge in [[knowledge-vaults/semantic-audit]].

## Verify it worked

```bash
# 1. The auditor is clean and read the real spec.
python3 99-Tools/audit.py --quiet; echo "exit=$?"
python3 -c "import json; print(json.load(open('99-Tools/audits/audit.json'))['summary']['spec_status'])"

# 2. The spec and the auditor are versioned.
git ls-files vault-spec.yaml 99-Tools/audit.py
```

Exit 0, `loaded`, and both files tracked means the vault is ready for the loop in [[knowledge-vaults/vault-orchestration]].

## Common errors

- The generator exits 2. The target exists and is not empty. Pick a new path or pass `--force`.
- The generator exits 4 with "Spec invalid". `vault` or `note_types` is missing or empty.
- The audit reports M000 and exits 1 on a vault you believe is clean. `vault-spec.yaml` is missing from the vault root or failed to parse.
- `--fix --apply` refuses to write. The vault is not Git-tracked. Commit first; there is no other undo.
- `semantic_prep.py` fails with `TypeError: Object of type date is not JSON serializable`. With PyYAML installed, frontmatter dates parse into date objects the bundler cannot serialize; the standard-library parser succeeds. Until the script is patched, run it from a virtual environment without PyYAML.

## Related

- [[knowledge-vaults/vault-architecture]]
- [[knowledge-vaults/vault-audit]]
- [[knowledge-vaults/audit-rule-catalog]]
- [[knowledge-vaults/semantic-audit]]
- [[knowledge-vaults/vault-orchestration]]
- [[knowledge-vaults/vault-frontmatter-schema]]
- [[tooling/obsidian-plugins]]
- [[howto/set-up-claude-code]]