LLM Best Practices

How to bootstrap and audit a vault

4 min read

View markdown source

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 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:
export SK=./skills/axia-authored/vault-architect

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 vault-frontmatter-schema. Only the types you list are scaffolded.

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

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

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

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

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 vault-audit.

6. Close the autofix loop

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 audit-rule-catalog.

7. Assemble the semantic bundle

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 semantic-audit.

Verify it worked

# 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 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.

Backlinks