[P2][docs] Vault concept buried in documentation — new users don't understand it

[sepehrn0107]

Problem

The vault is the core persistence mechanism, but:

• README.md never mentions the word "vault"
• Install docs mention it in Step 3, after clone and setup

New users won't understand what a vault is, why they need one, or what it stores.

Proposed Fix

• Add a "Key Concepts" section to README (workspace, vault, memory, standards, skills)
• Explain vault before Step 1 in install docs
• Add a visual diagram of the architecture

[sepehrn0107]

---

issue: "3.2 Vault concept in docs"
priority: P2
type: documentation
date: 2026-04-07

Implementation Plan — Vault Concept in Docs

Problem Summary

The vault is the central persistence mechanism: it stores all persistent output (global memory, plans, specs, ADRs) across project repos and sessions. Despite being required by Step 3 of the install flow, the word "vault" does not appear once in README.md. New users complete the install before they have any conceptual handle on what the vault is.

Current exposure:

Location	First mention of "vault"	Context
README.md	Never	The word does not appear
docs/getting-started/install.md	Step 3 (/upgrade-dev)	After clone and setup
docs/getting-started/concepts.md	Memory section (line 24)	Brief, no dedicated section
docs/user-guide/multi-project.md	"The vault" section	Correct definition, buried

Files to Change

File	Change
README.md	Add "Key Concepts" section between "The fix" and "Install"
docs/getting-started/install.md	Add "What is the vault?" callout before Step 1
docs/getting-started/concepts.md	Add "Vault" section before the existing Memory section

Step-by-Step Changes

Step 1 — Add "Key Concepts" section to README.md

Insert after "The fix" section, before ## Install:

## Key Concepts

Before installing, a two-minute orientation:

**Workspace** — a single folder (e.g. `~/Documents/workspace/`) that contains the
`toolbox/` clone and all your project repos as siblings.

**Vault** — a folder outside your project repos where all persistent output lives:
global memory, plans, specs, and ADRs. It can be an Obsidian vault, a plain folder,
or any synced directory. You set the vault path once during install.

**Memory** — Markdown files that capture what each project is, what stack it uses,
what has been built, and what was learned. Memory files live in the vault, not the repo.

**Standards** — coding rules (universal + stack-specific) that load automatically
before Claude writes any code.

**Skills** — named workflows (e.g. `/implement`, `/new-project`, `/git-push`) that
Claude runs in response to plain-English phrases.

Step 2 — Add vault callout to install.md (before Step 1)

Insert between "Requirements" and ## Step 1 — Clone:

## What is the vault?

The toolkit stores all persistent output — memory files, plans, specs, and ADRs —
in a single folder called the **vault**. This folder lives outside your project repos,
so it survives re-clones and branch switches.

The vault can be:
- An existing [Obsidian](https://obsidian.md) vault
- A plain folder anywhere on disk (e.g. `~/Documents/notes/`)
- A synced cloud directory (iCloud, Dropbox, etc.)

You set the vault path in Step 3. You can change it anytime with `/set-vault`.

Step 3 — Add Vault section to concepts.md (before Memory)

Insert before the existing ## Memory heading:

## Vault

The vault is the folder where the toolkit writes everything that needs to survive across
sessions, repos, and re-clones: global memory, per-project memory, plans, specs, and ADRs.
It is deliberately separate from your project repos — re-cloning a project never touches
the vault.

The toolkit expects the vault to follow a specific folder structure (written during install).
You can inspect it at any time; it is plain Markdown.

Revised concepts.md section order: Sessions → Vault (new) → Memory → Routing → Standards Gate → Sub-agent Architecture

Validation Steps

1. grep -i "vault" README.md — must return at least 2 lines.
2. Read install.md top to bottom — "vault" must appear before ## Step 1.
3. docs/getting-started/concepts.md — vault defined before memory is referenced.
4. Canonical definition in docs/user-guide/multi-project.md remains unchanged.
5. mkdocs build --strict — zero warnings.
6. Peer read — unfamiliar person can answer "what is the vault?" before clicking any links.

Parallelism Guide

All three edits are independent — dispatch in parallel:

Group	Task	Agent
A	Edit README.md — insert Key Concepts	Sub-agent 1
B	Edit docs/getting-started/install.md — insert vault callout	Sub-agent 2
C	Edit docs/getting-started/concepts.md — insert Vault section	Sub-agent 3

Run validation sequentially after all three complete.