jason/echo

Fork 0

Files

T

jason e3e40af149 ver0.5

2026-06-07 01:18:02 -05:00

7.8 KiB

Raw Permalink Blame History

type, status, created, updated, tags, agent_written, source_notes

type

status

created

updated

BOOTSTRAP.md

Purpose

This is the first file any agent reads when operating against this vault. It does two things:

Checks that the required files and folders exist.
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:

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):

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.

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

7.8 KiB Raw Permalink Blame History