171 lines
7.8 KiB
Markdown
171 lines
7.8 KiB
Markdown
---
|
|
type: reference
|
|
status: active
|
|
created: 2026-06-02
|
|
updated: 2026-06-07
|
|
tags: [agent, bootstrap, system]
|
|
agent_written: true
|
|
source_notes: []
|
|
---
|
|
|
|
# BOOTSTRAP.md
|
|
|
|
## Purpose
|
|
This is the **first file any agent reads** when operating against this vault. It does two things:
|
|
|
|
1. **Checks** that the required files and folders exist.
|
|
2. **Generates** anything that is missing, using the templates and conventions below.
|
|
|
|
Day-to-day operating procedure is **not** defined here — it is owned by the echo-memory skill (see section 3). Run the bootstrap preflight at the start of a session, then follow the skill. The check is cheap, idempotent, and safe to repeat.
|
|
|
|
---
|
|
|
|
## 1. Preflight Check
|
|
|
|
Verify the following exist. Treat each as `[ ]` until confirmed, then `[x]`. If a path is missing, jump to the matching entry in section 2 (Repair) before continuing.
|
|
|
|
### Root control docs
|
|
- [ ] `CLAUDE.md` — operating contract and session protocol
|
|
- [ ] `BOOTSTRAP.md` — this file
|
|
- [ ] `STRUCTURE.md` — layout, taxonomy, frontmatter standard
|
|
- [ ] `index.md` — navigation hub
|
|
- [ ] `README.md` — human-facing overview
|
|
- [ ] `.env.example` — config template for REST/API clients
|
|
|
|
### Required folders
|
|
- [ ] `inbox/` (with `captures/`, `imports/`, `processing-log/`)
|
|
- [ ] `journal/` (with `daily/`, `weekly/`, `monthly/`, `templates/`)
|
|
- [ ] `projects/` (with `active/`, `incubating/`, `on-hold/`, `archived/`)
|
|
- [ ] `areas/` (with `business/`, `personal/`, `learning/`, `systems/`)
|
|
- [ ] `resources/` (with `concepts/`, `references/`, `people/`, `meetings/`, `source-material/`)
|
|
- [ ] `decisions/` (with `by-date/`; `by-project/` is **deprecated** — see note below)
|
|
- [ ] `reviews/` (with `weekly/`, `monthly/`, `quarterly/`, `annual/`)
|
|
- [ ] `archive/` (with `notes/`, `projects/`, `imports/`)
|
|
- [ ] `_agent/` (see agent subtree below)
|
|
|
|
> **`decisions/by-project/` is deprecated** (0.4.0). Decision notes go in `decisions/by-date/YYYY-MM-DD-<slug>.md`; if a decision belongs to an active project, mirror it as a `[[wikilink]]` under that project's `## Key Decisions` heading rather than creating a topical by-project file.
|
|
|
|
### Required `_agent/` subtree
|
|
- [ ] `_agent/context/` — active context bundles
|
|
- [ ] `_agent/memory/working/` — short-lived working memory
|
|
- [ ] `_agent/memory/episodic/` — event/session-derived memory
|
|
- [ ] `_agent/memory/semantic/` — durable facts, patterns, preferences
|
|
- [ ] `_agent/sessions/` — session logs
|
|
- [ ] `_agent/templates/` — note templates
|
|
- [ ] `_agent/heartbeat/` — liveness / scheduled-run markers
|
|
- [ ] `_agent/skills/` (with `active/`, `archived/`)
|
|
- [ ] `_agent/outputs/` (with `briefs/`, `drafts/`, `summaries/`, `synthesis/`)
|
|
|
|
### Required templates
|
|
- [ ] `_agent/templates/session-log-template.md`
|
|
- [ ] `_agent/templates/context-bundle-template.md`
|
|
- [ ] `_agent/templates/working-memory-template.md`
|
|
- [ ] `_agent/templates/semantic-memory-template.md`
|
|
- [ ] `journal/templates/daily-note-template.md`
|
|
- [ ] `journal/templates/weekly-review-template.md`
|
|
- [ ] `projects/project-template.md`
|
|
- [ ] `decisions/decision-template.md`
|
|
|
|
### Anchor notes (recommended, not blocking)
|
|
- [ ] `_agent/context/current-context.md`
|
|
- [ ] `_agent/memory/semantic/operator-preferences.md`
|
|
- [ ] today's daily note in `journal/daily/YYYY-MM-DD.md`
|
|
|
|
A quick way to list the tree for comparison:
|
|
|
|
```bash
|
|
find . -type d | sort # folders
|
|
find . -type f -name '*.md' | sort # notes
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Repair (generate what's missing)
|
|
|
|
Only create what is missing. **Never overwrite an existing file** during bootstrap — that violates the additive-update principle in [[CLAUDE]]. If a file exists but looks malformed, flag it in the session log instead of replacing it.
|
|
|
|
### Missing folders
|
|
Create the folder and add a one-line `README.md` inside any leaf folder that would otherwise be empty (Obsidian and git both ignore empty dirs):
|
|
|
|
```bash
|
|
mkdir -p "<path>"
|
|
```
|
|
|
|
### Missing root control docs
|
|
- `STRUCTURE.md`, `README.md`, `.env.example` — if absent, note it and reconstruct from the conventions in this file and [[STRUCTURE]]. Do not invent secrets in `.env.example`; use placeholders only.
|
|
- `index.md` — rebuild as a link hub pointing at the Start Here docs, active context, operator preferences, and the most recent daily note / session log.
|
|
|
|
### Missing templates
|
|
Recreate from the canonical frontmatter (section 4). Each template is just frontmatter plus the section headings its note type uses.
|
|
|
|
### Missing anchor notes
|
|
- `_agent/context/current-context.md` — create an empty context bundle (type `context-bundle`) scoped to the current task.
|
|
- today's daily note — create from `journal/templates/daily-note-template.md`.
|
|
- `operator-preferences.md` — only create if you have evidence to record; do not fabricate preferences.
|
|
|
|
### After repair
|
|
Append a line to the daily note's **Agent Log** and write/refresh a session log in `_agent/sessions/` recording what was generated.
|
|
|
|
---
|
|
|
|
## 3. How to Operate (after preflight)
|
|
|
|
Day-to-day operating procedure is owned by the **echo-memory skill** (`SKILL.md`; canonical source `git.alwisp.com/jason/echo`), not this file. The skill defines: session loading order, search-first-before-write, Inbox Triage, Scope Switching, doc-map-before-first-PATCH, the resilient daily-note Agent Log procedure, idempotent appends, and the monthly Vault Health pass. **If this file and the skill ever disagree on procedure, the skill is authoritative.** BOOTSTRAP's job is limited to the structure preflight (section 1) and repair (section 2).
|
|
|
|
The durable reference below binds regardless of client:
|
|
|
|
### Memory model (where things live)
|
|
- **Working** → `_agent/memory/working/` — transient, time-boxed.
|
|
- **Episodic** → `_agent/memory/episodic/` — what happened, when.
|
|
- **Semantic** → `_agent/memory/semantic/` — durable facts, patterns, preferences.
|
|
- **Context bundles** → `_agent/context/` — task-focused reading lists and state.
|
|
|
|
### Safety rules (from [[CLAUDE]])
|
|
- Do not fabricate facts, relationships, or prior decisions.
|
|
- Do not mass-restructure the vault unless explicitly asked.
|
|
- Do not delete notes unless deletion is explicitly requested and clearly safe.
|
|
- Do not store secrets or API keys inside the vault.
|
|
- Default to additive updates and explicit status changes.
|
|
|
|
---
|
|
|
|
## 4. Canonical Frontmatter
|
|
|
|
Every note carries this block. Fill what applies; leave the rest empty rather than guessing.
|
|
|
|
```yaml
|
|
---
|
|
type: # one of the note types in STRUCTURE.md
|
|
status: # active | draft | done | archived
|
|
created: # YYYY-MM-DD
|
|
updated: # YYYY-MM-DD
|
|
tags: []
|
|
agent_written: false
|
|
source_notes: [] # plain relative paths as strings — NEVER [[wikilinks]]
|
|
---
|
|
```
|
|
|
|
Agent-generated notes set `agent_written: true` and list their `source_notes`. This is the key signal that separates agent-managed content from human-authored content.
|
|
|
|
> **No `[[wikilinks]]` in frontmatter.** YAML interprets `[[...]]` as nested lists, so wiki
|
|
> links in frontmatter break — they do not render as clickable links in Obsidian's reading
|
|
> view. Put every cross-reference in a **`## Related`** section in the note **body** as a
|
|
> bulleted list of `[[links]]`. Frontmatter holds scalar/string metadata only; `source_notes`
|
|
> values are plain relative paths, not links. (The older `related:` frontmatter field has
|
|
> been retired for this reason.)
|
|
|
|
---
|
|
|
|
## 5. REST / API Readiness
|
|
|
|
Future clients (Obsidian Local REST API, CoWork plugin) may operate without filesystem access. Keep the bootstrap contract portable: stable paths, parseable frontmatter, durable titles, and all state stored in notes rather than hidden conversation memory. Config for those clients lives in a local `.env` derived from `.env.example` — never committed with real values.
|
|
|
|
---
|
|
|
|
_This file is the entry point. If you change folder conventions or required files, update both this manifest and [[STRUCTURE]] so they stay in sync._
|
|
|
|
## Related
|
|
- [[CLAUDE]]
|
|
- [[STRUCTURE]]
|
|
- [[index]]
|