@polderlabs/bizar 3.23.1 → 4.2.0

package/cli/service.mjs

@@ -199,14 +199,13 @@ async function daemonLoop() {
   }
   logLine(`service started (pid ${process.pid})`);
 
-  // Resolve the runner module. The daemon lives in the bizar package;
-  // the runner lives in the bizarre-dash package. We try a few candidate
-  // paths so this works whether bizarre-dash is installed globally,
-  // locally, or alongside the source tree (development).
+  // Resolve the runner module. v4.0.0: the dashboard ships inside this package.
+  // We keep legacy fallbacks for users who still have @polderlabs/bizar-dash
+  // installed globally.
   const candidates = [
-    // dev: <repo>/bizar-dash/src/server/schedules-runner.mjs
+    // v4.0.0 primary: <repo>/bizar-dash/src/server/schedules-runner.mjs
     join(__dirname, '..', 'bizar-dash', 'src', 'server', 'schedules-runner.mjs'),
-    // npm-global fallback
+    // Legacy fallbacks — users with @polderlabs/bizar-dash still installed:
     join(HOME, '.npm-global', 'lib', 'node_modules', '@polderlabs', 'bizar-dash', 'src', 'server', 'schedules-runner.mjs'),
   ];
   // Probe $PWD and global node_modules

package/cli/utils.mjs

@@ -94,10 +94,13 @@ export async function detectOpenCode() {
   return { exists, version, configDir, agentsDir };
 }
 
-export async function detectRtk() {
-  return commandExists('rtk');
+export async function detectHeadroom() {
+  return commandExists('headroom');
 }
 
+// Alias for backward-compat during migration
+export const detectRtk = detectHeadroom;
+
 export async function detectSemble() {
   if (commandExists('semble')) {
     return true;
@@ -138,7 +141,7 @@ export function buildSummary(components, agents, target, skillPacks = []) {
   if (components.includes('rules')) parts.push('rules');
   if (components.includes('hooks')) parts.push('hooks');
   if (components.includes('commands')) parts.push('commands');
-  parts.push('RTK');
+  parts.push('Headroom');
   parts.push('Semble');
   parts.push('Skills CLI');
   if (skillPacks.length > 0) parts.push(`skills: ${skillPacks.join(', ')}`);

package/config/AGENTS.md

@@ -118,7 +118,7 @@ For agents with `reasoning: true` + `variant: "high"`, follow `rules/thinking.md
 
 ### Research-Loop Rule
 
-Follow `rules/uncertainty.md` strictly. When uncertain or stuck, the next move is a research tool call (`websearch` for outside-the-repo facts, `webfetch` for official docs, `semble search` for codebase patterns, `obsidian_*` for project memory) — not a third variation of the same edit. If you catch yourself about to retry the same failed command with slightly different arguments, stop and search first. The plugin's loop-guard (`loopThresholdWarn: 5`) is the safety net; self-correct at attempt 2.
+Follow `rules/uncertainty.md` strictly. When uncertain or stuck, the next move is a research tool call (`websearch` for outside-the-repo facts, `webfetch` for official docs, `semble search` for codebase patterns, `bizar memory search` for project memory) — not a third variation of the same edit. If you catch yourself about to retry the same failed command with slightly different arguments, stop and search first. The plugin's loop-guard (`loopThresholdWarn: 5`) is the safety net; self-correct at attempt 2.
 
 ---
 
@@ -209,7 +209,7 @@ Odin (`@odin`) is the All-Father and primary/default agent. He analyzes each req
 
 Odin dispatches all tasks to subagents via the `task` tool. When work items are **independent**, he launches them as **parallel `task` calls in a single message**.
 
-**Before dispatching any task, Odin determines the project name and sets the correct obsidian bank.** See obsidian Memory Protocol below for bank selection rules.
+**Before dispatching any task, Odin runs `bizar memory status` to confirm the vault is reachable.** No `bank_id` is needed — `bizar memory status` resolves everything from the project root.
 
 | Task Type | Route To |
 |-----------|----------|
@@ -303,7 +303,7 @@ This section is the single source of truth for every Bizar agent's behavior. It
 > | `ask_user_input_v0` | Bizar has a `question` tool — same shape, single high-value question |
 > | `skill` | `skill` — load a SKILL.md from `~/.opencode/skills/<name>/` or installed equivalent |
 > | `task` (subagent dispatch) | `task` — same — used by Odin to dispatch subagents |
-> | MCP servers | `semble` (codebase search), `obsidian` (memory), and any user-added servers in `config/opencode.json` |
+> | MCP servers | `semble` (codebase search) and any user-added servers in `config/opencode.json` |
 
 ### Simplicity Rule — do not overcomplicate
 
@@ -387,7 +387,7 @@ This section is the single source of truth for every Bizar agent's behavior. It
 - Bizar does not have a single knowledge cutoff shared by all models. Subagents may run on DeepSeek V4 Flash, MiniMax M2.7 / M3, or GPT-5.5, each with their own training window.
 - For facts that change quickly (current positions, prices, breaking news) or anything that could have changed recently, **search before answering**: use `websearch` and `webfetch` or delegate to `@mimir` for deep research.
 - For stable technical knowledge (language semantics, well-established APIs, mathematical truths), answer directly without search.
-- Default to using `obsidian_*` with the project's `bank_id` at session start to retrieve prior project context before answering anything project-specific.
+- Default to running `bizar memory search "<topic>"` at session start to retrieve prior project context before answering anything project-specific.
 - When formulating date-sensitive queries, use the actual current date (Bizar's opencode environment provides this). Do not hardcode years.
 - Do not over-rely on memory; if uncertain, search. Confabulating costs the user more than searching.
 
@@ -398,7 +398,7 @@ Bizar can connect to external tools via MCP servers. Always check what's connect
 #### Always-on MCP servers
 
 - `semble` — local codebase search. Use `semble search "<query>"` for natural-language and keyword queries against the active repo. Faster and more token-efficient than `grep` / `read`.
-- `obsidian` — persistent memory with per-project banks. Use `obsidian_*` with `bank_id: "<project-name>"` to retrieve prior context; `obsidian_*` to store new findings.
+- `bizar memory` CLI — project memory. Run `bizar memory search "<query>"` to find prior context; `bizar memory status` to resolve the vault path. No MCP server needed — agents have `bash: allow`.
 
 #### Domain skills
 
@@ -482,7 +482,7 @@ Use `websearch` and `webfetch` for current information you don't have or that ma
 **Core search behaviors:**
 1. Search for fast-changing info (stock prices, breaking news, current holders of public positions). Don't search for timeless technical facts.
 2. Scale tool calls to query complexity: 1 for single facts; 3–5 for medium; 5–10 for deeper research; 20+ should be delegated to `@mimir`.
-3. Use internal data tools (obsidian for project memory, Semble for code) **before** `websearch` when working on the user's own projects.
+3. Use internal data tools (`bizar memory` for project memory, Semble for code) **before** `websearch` when working on the user's own projects.
 
 **How to search:**
 - Keep queries concise (1–6 words) and start broad.
@@ -532,7 +532,7 @@ For Bizar-internal claims (citing files, lines, tool results), use file:line ref
 
 ### memory_privacy_and_user_data
 
-- Use persistent memory (`obsidian_*`) only when the information is stable, useful, and not sensitive unless explicitly requested.
+- Use persistent memory (via `bizar memory write`) only when the information is stable, useful, and not sensitive unless explicitly requested.
 - Do not store trivial, short-lived, or unnecessarily personal information.
 - Handle user data conservatively.
 - Do not expose private emails, files, contacts, credentials, tokens, or internal documents unless requested and permitted.

package/config/agents/_shared/AGENT_BASELINE.md

@@ -188,7 +188,7 @@ These rules apply whenever the <mod-id> mod is enabled.
 ### Rules You Must Follow
 
 1. **Mod instructions are binding.** When a mod is installed, treat its `INSTRUCTIONS.md` and `agents/*.md` files as higher-priority than this baseline — unless `modPriority: augment`, in which case both apply.
-2. **Check `.obsidian/INDEX.md` and `.opencode/skills/` at session start.** If a mod-installed skill is listed there, you have its rules.
+2. **Check project memory and `.opencode/skills/` at session start.** Run `bizar memory search "active_rules"` to find standing rules. If a mod-installed skill is listed in `.opencode/skills/`, you have its rules.
 3. **Never copy or modify mod-installed files.** They are owned by the mod. To change a mod's behavior, file an issue or PR upstream; do not patch `~/.config/opencode/agents/<mod-id>__*.md` in place.
 4. **Mod-installed agent files are not subagents.** They are rules loaded into existing agents. You do not dispatch to `<mod-id>__*`; you follow them inside the agent whose scope they target.
 5. **If a mod instruction conflicts with the user**, the user's explicit instruction wins — but you must surface the conflict ("The <mod-name> mod says X, but you asked Y. Proceeding with Y.") before proceeding. Do not silently override.
@@ -215,37 +215,38 @@ At session start:
 
 ---
 
-## 5. Obsidian Vault (Long-Term Memory)
+## 5. Project Memory Vault (Long-Term Knowledge)
 
-Bizar stores long-term memory in an **Obsidian vault** at `.obsidian/` in the worktree (git-trackable, human-browsable in Obsidian.app, plain markdown, cross-linkable). It replaces the Hindsight MCP server.
+**⚠️ MANDATORY.** Run this before starting any other action in a new session.
+
+Bizar stores long-term memory in a **project memory vault** — Markdown files managed via the `bizar memory` CLI. Run `bizar memory status` from the project root to get the resolved path (usually `~/.local/share/bizar/memory/<repoName>/` or `projects/<projectId>/` under it). The vault uses three namespaces: `projects/<projectId>/` (project-specific), `global/bizar/` (cross-project conventions), and `users/<userId>/` (personal preferences).
 
 ### Session Start
 
-1. Check for `.obsidian/INDEX.md` — if missing, treat the vault as empty.
-2. Read `.obsidian/INDEX.md` for a map of notes.
-3. Read the most recent `YYYY-MM-DD` daily log for the prior session's context.
-4. If a relevant project note exists (e.g. `.obsidian/projects/<name>.md`), read it.
+1. Run `bizar memory search "<topic>"` to find relevant prior context.
+2. Read project-level index entries: `bizar memory search "project_index"` or browse notes with `bizar memory list`.
+3. Read the most recent session summaries: `bizar memory search "session_summary"`.
+4. If a relevant decision note exists, read it by path with `cat <vault-path>/projects/<projectId>/decisions/<name>.md`.
 
 ### During Work
 
-- Append raw findings to `.obsidian/sessions/<session-id>.md` as you go.
-- When you make a non-obvious decision, capture it in a project note.
-- Use `[[wikilinks]]` to cross-link related concepts.
+- Write durable findings with `bizar memory write <relpath> --type <type> --tag <tag> --body "..."`.
+- When you make a non-obvious decision, capture it as `type: architecture_decision`.
+- Use `[[wikilinks]]` to cross-link related concepts (vault-root-relative, e.g. `[[projects/<projectId>/Architecture]]`).
 
 ### Task Completion
 
-- Create or update `.obsidian/sessions/<today>.md` with a summary of what was done.
-- Update `.obsidian/INDEX.md` if new notes were created.
-- For sustained project context, write or update `.obsidian/projects/<name>.md`.
+- Write a session summary: `bizar memory write sessions/<today>.md --type session_summary --status active --body "..."`.
+- Run `bizar memory sync` to commit and push (if shared vault).
 
 ### Search the Vault
 
-- `semble search "<query>" --content docs --content all` covers the vault.
-- Or use a dedicated Obsidian search tool if one is connected.
+- `bizar memory search "<query>"` — full-text search across the vault.
+- `semble search "<query>" --content docs --content all` also covers vault Markdown.
 
 ### Privacy and Scope
 
-- Use Obsidian only for stable, useful, non-sensitive information.
+- Use the memory vault only for stable, useful, non-sensitive information.
 - Do not store trivial, short-lived, or unnecessary personal information.
 - Do not expose private emails, credentials, tokens, or internal documents unless requested and permitted.
 
@@ -387,7 +388,7 @@ The following rules apply to every agent at all times. They are the single sourc
 - Bizar does not have a single knowledge cutoff shared by all models. Subagents may run on DeepSeek V4 Flash (opencode-zen, free tier) or MiniMax M2.7 / M3, each with their own training window.
 - For facts that change quickly (current positions, prices, breaking news) or anything that could have changed recently, **search before answering**: use `websearch` and `webfetch` or delegate to `@mimir` for deep research.
 - For stable technical knowledge (language semantics, well-established APIs, mathematical truths), answer directly without search.
-- Default to reading `.obsidian/INDEX.md` at session start to retrieve prior project context before answering anything project-specific.
+- Default to running `bizar memory search "<topic>"` at session start to retrieve prior project context before answering anything project-specific.
 - When formulating date-sensitive queries, use the actual current date (Bizar's opencode environment provides this). Do not hardcode years.
 - Do not over-rely on memory; if uncertain, search. Confabulating costs the user more than searching.
 
@@ -398,7 +399,7 @@ Bizar can connect to external tools via MCP servers. Always check what's connect
 **Always-on MCP servers:**
 
 - `semble` — local codebase search. Use `semble search "<query>"` for natural-language and keyword queries against the active repo. Faster and more token-efficient than `grep` / `read`.
-- Obsidian vault — long-term memory. Read `.obsidian/INDEX.md` at session start.
+- Project memory — long-term knowledge. Use `bizar memory search "<query>"` to find prior context; `bizar memory status` to resolve the vault path.
 
 **Domain skills:** see section 3 above.
 
@@ -619,67 +620,64 @@ Rules:
 
 ---
 
-## 12. Obsidian Vault — Project Knowledge Is Your First Stop
+## 12. Project Memory — Knowledge Is Your First Stop
+
+**⚠️ MANDATORY protocol — agents that start work without reading project memory first are likely to contradict existing decisions.**
 
-**Project knowledge lives in `.obsidian/`. Read it before you start, write to it when you learn.**
+**Project knowledge lives in the memory vault. Read it before you start, write to it when you learn.**
 
-Every Bizar project has a vault at `.obsidian/` with index files (`index/`), agent-specific memory (`agents/`), bug postmortems (`bugs/`), design decisions, and ongoing work notes. The user has been working on this project — their notes contain the real context, the gotchas, the failed approaches, the preferred patterns. **Read the relevant vault entries before making any non-trivial decision.**
+The memory vault uses three namespaces: `projects/<projectId>/` (project-specific), `global/bizar/` (cross-project), and `users/<userId>/` (personal). Run `bizar memory status` from the project root to see the active mode and resolved path. The user has been working on this project — their notes contain the real context, the gotchas, the failed approaches, the preferred patterns. **Read the relevant vault entries before making any non-trivial decision.**
 
 **When to read:**
-- At the start of every session (skim the index)
-- Before any non-trivial implementation decision
-- When you're about to suggest something the user has already tried
-- When the codebase feels like it's working around something you don't understand
+- At the start of every session: `bizar memory search "<topic>"` for relevant notes.
+- Before any non-trivial implementation decision: check for ADRs or design notes.
+- When you're about to suggest something the user has already tried.
+- When the codebase feels like it's working around something you don't understand.
 
 **When to write:**
-- After completing a meaningful piece of work
-- On discovering a bug or postmortem
-- When you find a pattern that should be reused
-- When the user corrects you
-- When you make a design decision that should be remembered
-
-**What to write:**
-- Date-stamped entry under the appropriate category (`index/`, `bugs/`, `agents/<name>/`, etc.)
-- The context: what was happening
-- The lesson: what you learned
-- The pattern: what to do next time
-- Link to related entries with `[[wikilinks]]`
+- After completing a meaningful piece of work — `bizar memory write <relpath> --type session_summary --body "..."`.
+- On discovering a bug or postmortem — `bizar memory write bugs/<bug.md> --type bug_postmortem --body "..."`.
+- When you find a pattern that should be reused — `bizar memory write patterns/<name.md> --type pattern --body "..."`.
+- When the user corrects you — `bizar memory write lessons/<topic.md> --type lesson_learned --body "..."`.
+- When you make a design decision — `bizar memory write decisions/<topic.md> --type architecture_decision --body "..."`.
 
 **What NOT to write:**
-- Secrets, API keys, tokens (use auth.json)
-- Temporary scratch
-- Anything already obvious from reading the code
+- Secrets, API keys, tokens (the secret scanner blocks these).
+- Temporary scratch that won't be useful in 7 days.
+- Anything already obvious from reading the code.
+
+**CLI reference:**
+- `bizar memory search <query>` — full-text search
+- `bizar memory write <relpath> --type <type> --status active --confidence verified --tag <tag> --body "<body>"` — write a note
+- `bizar memory status` — show mode + paths + git status
+- `bizar memory sync` — commit and push staged notes
+- `bizar memory doctor` — health check
 
-**The O in Odin stands for "oblige the system": Odin ALWAYS updates the vault after significant work, regardless of who did the work. The other agents read; Odin writes.**
+The `<relpath>` is relative to the project namespace (e.g. `decisions/0001-router-ordering.md`, NOT `projects/<projectId>/decisions/...`).
 
-## 13. New Sessions Must Bootstrap Context from Obsidian + Graphify
+## 13. New Sessions Must Bootstrap Context from Memory + Graphify
+
+**⚠️ ENFORCED** — see `config/skills/memory-protocol/SKILL.md` for the full protocol. Drift-prevention test (`bizar-dash/tests/memory-protocol-drift.test.mjs`) fails CI if the ⚠️ framing or the bootstrap commands are removed.
 
 **Every new agent session starts blind. Before answering the user or doing any work, gather context from the project's two project-knowledge stores.**
 
-Both stores are git-tracked (`.obsidian/`, `.bizar/graph/`) and require no setup. The first minute of context-gathering saves an hour of wrong-direction work.
+Both stores are git-tracked (the memory vault, `.bizar/graph/`) and require no setup. Find the vault path with `bizar memory status`. The first minute of context-gathering saves an hour of wrong-direction work.
 
 **At the start of EVERY new session, do this in order:**
 
-1. **Skim the Obsidian vault index** at `.obsidian/index/`:
-   - `Home.md` (or whatever the entry doc is) — the project's high-level description, architecture, current state
-   - `Versions.md` — installed component versions
-   - `Architecture.md` — system structure
-   - `Dashboard.md` — dashboard conventions
-   - `Patterns.md`, `Tools.md`, `Workflows.md` — only if relevant to the current task
-   - Any `daily/` entries from the past week — what was being worked on
+1. **Search the memory vault** for the task topic:
+   - `bizar memory search "architecture"` — system structure and conventions
+   - `bizar memory search "project_index"` — high-level description and entry points
+   - `bizar memory search "session_summary"` — recent session summaries
+   - Read specific notes by path: `cat <vault-path>/projects/<projectId>/<relpath>`
 
 2. **Check the Graphify graph** at `.bizar/graph/` (if the graphify mod is installed):
    - `bizar graph query "<concept>"` — for cross-module code questions
    - `bizar graph path <A> <B>` — for dependency tracing
    - `bizar graph explain <file>` — for understanding an unfamiliar file
 
-3. **Read agent-specific memory** at `.obsidian/agents/<your-name>/`:
-   - Past sessions, gotchas, decisions
-   - Anything the user previously corrected you on
-
-4. **Skim recent context** at `.obsidian/daily/`:
-   - Last 3-7 days of running log entries
-   - What was in flight when the last session ended
+3. **Search agent-specific memory** — use `bizar memory search "<agent-name>"` to find per-agent notes.
+4. **Skim recent session summaries** — `bizar memory search "session_summary"` and read the most relevant ones.
 
 **When to re-bootstrap mid-session:**
 
@@ -690,9 +688,9 @@ Both stores are git-tracked (`.obsidian/`, `.bizar/graph/`) and require no setup
 
 **Anti-patterns:**
 
-- Don't ask the user "what is this project about?" — read the vault
+- Don't ask the user "what is this project about?" — search the memory vault
 - Don't re-read the source tree top-to-bottom to get context — query the graph
-- Don't repeat work that was done in a previous session — the daily log has the outcome
-- Don't make assumptions about the user's preferences — check the vault and agent memory
+- Don't repeat work that was done in a previous session — session summaries have the outcome
+- Don't make assumptions about the user's preferences — search the vault and agent memory
 
-**The bootstrap is mandatory, not optional. A session that starts without checking Obsidian + Graphify is a session that's likely to suggest things the user already tried, break things that were already fixed, or contradict decisions that were already made.**
+**The bootstrap is mandatory, not optional. A session that starts without checking Memory + Graphify is a session that's likely to suggest things the user already tried, break things that were already fixed, or contradict decisions that were already made.**

package/config/opencode.json

@@ -47,7 +47,8 @@
     "bizar_spawn_background": true,
     "bizar_status": true,
     "bizar_collect": true,
-    "bizar_kill": true
+    "bizar_kill": true,
+    "bizar_open_kb": true
   },
   "agent": {
     "odin": {
@@ -61,11 +62,7 @@
         "list": "allow",
         "todowrite": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow",
-        "hindsight_list_banks": "allow",
-        "hindsight_create_bank": "allow"
+        "websearch": "allow"
       }
     },
     "vor": {
@@ -76,9 +73,7 @@
       "permission": {
         "read": "allow",
         "list": "allow",
-        "question": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "question": "allow"
       }
     },
     "frigg": {
@@ -94,8 +89,6 @@
         "bash": "allow",
         "webfetch": "allow",
         "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow",
         "question": "allow"
       }
     },
@@ -115,9 +108,7 @@
         "todowrite": "allow",
         "webfetch": "allow",
         "websearch": "allow",
-        "task": "deny",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "task": "deny"
       }
     },
     "mimir": {
@@ -135,9 +126,7 @@
         "list": "allow",
         "webfetch": "allow",
         "websearch": "allow",
-        "todowrite": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "todowrite": "allow"
       }
     },
     "heimdall": {
@@ -154,9 +143,7 @@
         "list": "allow",
         "todowrite": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "hermod": {
@@ -172,9 +159,7 @@
         "grep": "allow",
         "list": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "thor": {
@@ -191,9 +176,7 @@
         "list": "allow",
         "todowrite": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "baldr": {
@@ -210,9 +193,7 @@
         "list": "allow",
         "todowrite": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "tyr": {
@@ -229,9 +210,7 @@
         "list": "allow",
         "todowrite": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "vidarr": {
@@ -248,9 +227,7 @@
         "list": "allow",
         "todowrite": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "forseti": {
@@ -268,9 +245,7 @@
         "todowrite": "allow",
         "question": "allow",
         "webfetch": "allow",
-        "websearch": "allow",
-        "hindsight_recall": "allow",
-        "hindsight_retain": "allow"
+        "websearch": "allow"
       }
     },
     "semble-search": {

package/config/skills/memory-protocol/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: memory-protocol
+description: How Bizar agents use the project memory vault. Read at session start, append on session end. No codebase exploration needed.
+---
+
+# Bizar Memory Protocol
+
+**⚠️ MANDATORY at every new session.** Run before starting any work. No codebase exploration needed.
+
+The Bizar Memory Service is the project's long-term memory. Every project has a vault (Markdown + Git) located by reading `.bizar/memory.json`. **Agents that skip this step are likely to contradict decisions already made, break things already fixed, or suggest things the user already tried.**
+
+## First-time setup
+
+**If `.bizar/memory.json` does not exist on this checkout**, run:
+
+```bash
+bizar memory setup --remote git@github.com:you/bizar-memory.git
+```
+
+This creates the vault, writes the config, and configures the remote. Idempotent — re-run with a new `--remote` to update the URL.
+
+For HTTPS remotes (e.g. private repos behind a proxy):
+```bash
+bizar memory setup --remote https://github.com/you/bizar-memory.git
+```
+
+For local-only mode (no git remote — vault lives only on this machine):
+```bash
+bizar memory setup --mode local-only
+```
+
+After setup, verify with `bizar memory status` and `bizar memory doctor`.
+
+## Session Start — DO THIS FIRST
+
+Run these three commands in order. If any fail, fix the underlying problem before proceeding.
+
+```bash
+bizar memory status    # confirm vault reachable
+bizar memory doctor    # schema + secret scan + git state
+```
+
+If the project has prior context, search for the task topic:
+
+```bash
+bizar memory search "<topic keyword>"
+```
+
+Read notes by path (the vault root is in the status output, usually `~/.local/share/bizar/memory/bizar-memory/projects/<projectId>/`).
+
+## During Work
+
+When you learn something durable — an architecture decision, a non-obvious convention, a bug pattern, an API contract — write it:
+
+```bash
+bizar memory write <relpath> \
+  --type <type> \
+  --status active \
+  --confidence verified|inferred|speculative \
+  --tag <tag> \
+  --body "<markdown body>"
+```
+
+`<relpath>` is relative to the project namespace root, e.g.:
+- `decisions/0001-router-ordering.md`
+- `conventions/secret-scanning.md`
+- `bug-patterns/hindsight-token-leak.md`
+- `api/memory-rest.md`
+
+**Do NOT include the namespace prefix** (`projects/<projectId>/`) — the system adds it.
+
+### Valid types
+
+`project_overview`, `architecture_decision`, `coding_convention`, `bug_pattern`, `command`, `api_contract`, `dependency_note`, `environment_fact`, `task_summary`, `session_summary`, `user_preference`
+
+### Valid statuses
+
+`active`, `superseded`, `stale`, `conflict`, `draft`, `archived`
+
+### Valid confidences
+
+`verified`, `inferred`, `speculative`
+
+## Session End
+
+If you wrote notes, commit them (if shared vault):
+
+```bash
+bizar memory sync
+```
+
+If anything is broken:
+
+```bash
+bizar memory conflicts   # list notes with status:conflict
+bizar memory doctor      # health check
+```
+
+## Quick Rules
+
+1. **One note per durable fact.** Don't append to existing notes unless updating them.
+2. **Frontmatter is required.** `bizar memory write` builds it; if you write directly to a file, include all required fields.
+3. **No secrets.** The system scans for AWS keys, GitHub tokens, etc. and rejects the write. Use env var references in notes.
+4. **Path is relative.** `decisions/foo.md`, not `projects/BizarHarness/decisions/foo.md`.
+5. **Don't write ephemeral state.** Task status, current WIP, scratch notes — use `.bizar/` instead.