@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/.claude/skills/embedded-esp-idf/scripts/size_check.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# size_check.sh — run a project size-budget check.
+# Prefers the AMS7-specific `tools/check_idf_size_budget.py` if present, else falls back to `idf.py size`.
+# Exits 0 on pass, 1 on size violation (AMS7 budget tool) or build failure (fallback).
+# Usage: bash scripts/size_check.sh [--project-dir DIR] [--min-iram-remain BYTES] [--min-dram-remain BYTES]
+
+set -euo pipefail
+
+PROJECT_DIR="."
+MIN_IRAM_REMAIN=""
+MIN_DRAM_REMAIN=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --project-dir)
+            PROJECT_DIR="${2:?--project-dir requires a value}"
+            shift 2
+            ;;
+        --min-iram-remain)
+            MIN_IRAM_REMAIN="${2:?--min-iram-remain requires a value}"
+            shift 2
+            ;;
+        --min-dram-remain)
+            MIN_DRAM_REMAIN="${2:?--min-dram-remain requires a value}"
+            shift 2
+            ;;
+        -h|--help)
+            sed -n '2,6p' "$0" | sed 's/^# \?//'
+            exit 0
+            ;;
+        *)
+            echo "size_check.sh: unknown argument: $1" >&2
+            exit 2
+            ;;
+    esac
+done
+
+# Resolve absolute path so the AMS7 budget tool's argparse sees a clean --project-dir.
+if [[ -d "${PROJECT_DIR}" ]]; then
+    PROJECT_DIR="$(cd "${PROJECT_DIR}" && pwd)"
+fi
+
+AMS7_BUDGET="${PROJECT_DIR}/tools/check_idf_size_budget.py"
+
+if [[ -f "${AMS7_BUDGET}" ]]; then
+    # AMS7-specific path: uses hard thresholds from tools/check_idf_size_budget.py.
+    cmd=(python3 "${AMS7_BUDGET}" --project-dir "${PROJECT_DIR}")
+    if [[ -n "${MIN_IRAM_REMAIN}" ]]; then
+        cmd+=(--min-iram-remain "${MIN_IRAM_REMAIN}")
+    fi
+    if [[ -n "${MIN_DRAM_REMAIN}" ]]; then
+        cmd+=(--min-dram-remain "${MIN_DRAM_REMAIN}")
+    fi
+    echo "size_check: running AMS7 budget tool: ${cmd[*]}"
+    if "${cmd[@]}"; then
+        exit 0
+    else
+        echo "size_check: AMS7 size budget failed" >&2
+        exit 1
+    fi
+fi
+
+# Fallback: plain idf.py size. This prints IRAM/DRAM/flash but does NOT enforce
+# a hard threshold — exit code is whatever idf.py returns.
+if ! command -v idf.py >/dev/null 2>&1; then
+    echo "size_check: idf.py not on PATH and no AMS7 budget tool found." >&2
+    echo "size_check: source esp/esp-idf/export.sh first." >&2
+    exit 1
+fi
+
+echo "size_check: no AMS7 budget tool; running 'idf.py size' as a fallback."
+if idf.py -C "${PROJECT_DIR}" size; then
+    exit 0
+else
+    echo "size_check: idf.py size failed" >&2
+    exit 1
+fi

package/.claude/worktrees/kanban-overhaul/.claude/skills/glyph/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: glyph
+description: Create visual glyphs at `artifacts/<slug>/` for plans, recaps, design proposals, postmortems, handoffs. Glyphs should be compact and visual — one screen, dense info, no walls of text. This skill enforces that. Use when the user asks for a plan preview, design review surface, or decisions document that needs visual blocks (Stat, Callout, Table, Decision, etc.).
+version: 4
+---
+
+# Glyphs
+
+A **glyph** is an MDX file the dashboard renders with a comment-pin overlay and right-click menu. Three files per glyph:
+
+```
+artifacts/<slug>/
+├── meta.json          ← title, status, author, created
+├── artifact.mdx       ← source of truth
+└── comments.json      ← free-placed pins (mutable)
+```
+
+Two locations: `<projectRoot>/.bizar/artifacts/` (preferred) and `~/.bizar_home/artifacts/` (global).
+
+## Frontmatter
+
+```yaml
+---
+title: "Short, action-oriented title"
+brief: "One sentence."
+status: draft | review | shipped | archived
+kind: plan | postmortem | recap | design
+---
+```
+
+## The 6 rules — read this first, every time
+
+These are non-negotiable. The existing 357-line v3-to-v4-consolidation glyph is a cautionary tale — don't write that one.
+
+### Rule 1 — One screen
+
+A glyph MUST fit on one screen of the dashboard (≈ 1000px tall at desktop width). Long glyphs are skimmed and abandoned. If you can't fit the work in 5-10 blocks, you're covering too much. Break the work into multiple glyphs, one per phase.
+
+### Rule 2 — One idea per block
+
+If a block covers two ideas, split it. Each block is a single visual unit. The dashboard groups blocks into sections by id prefix — use that.
+
+### Rule 3 — RichText is glue, not body
+
+RichText is for 1-3 sentence transitions between visual blocks. NEVER use RichText for the actual content. If you find yourself writing 4+ sentences in a RichText, switch to:
+
+- **A table** if you're listing things with attributes
+- **A decision** if you're explaining why one option won
+- **A file tree** if you're listing changes
+- **A stat** if you're highlighting a number
+- **A workflow** if you're describing a sequence
+
+### Rule 4 — Lead with visuals
+
+The first block after the title/headline should be a visual: a Stat, a Callout, or a Table. Never open with a long RichText. The user decides in 5 seconds whether to keep scrolling based on the visual.
+
+### Rule 5 — One headline callout
+
+Use `<Callout tone="success|danger">` once, near the top, as the TL;DR. Everything else supports it.
+
+### Rule 6 — Truncate hints, not bodies
+
+Stat `hint` props should be 1 short clause. Long hints mean the value needs to be a different block.
+
+## The block vocabulary — minimal reference
+
+| Block | What it shows | Required `data` |
+| --- | --- | --- |
+| `<RichText>` | 1-3 sentences of glue | none |
+| `<Callout tone>` | Boxed TL;DR | none (tone defaults to info) |
+| `<Stat label value trend hint />` | Big number + label | `label`, `value` |
+| `<Checklist items />` | Checkbox list | `items: [{id,label,checked}]` |
+| `<Table columns rows />` | Tabular data | `columns: []`, `rows: [[]]` |
+| `<CodeTabs tabs />` | Tabbed code | `tabs: [{id,label,language,code}]` |
+| `<Decision title question options />` | Multi-option choice | `options: [{id,label,detail,recommended?}]` |
+| `<OpenQuestions questions />` | Unanswered questions | `questions: [{id,label,kind,options?}]` |
+| `<FileTree title entries />` | File-by-file changes | `entries: [{path,change,note?}]` |
+| `<Diff before after filename language mode />` | Before/after | `before`, `after` |
+| `<Workflow steps connections />` | Node graph | `steps: [{id,label,type}]` |
+| `<Mockup title x y w h html />` | Inline UI mockup | `html` |
+| `<Diagram title dataHtml dataCss />` | Inline SVG | `dataHtml` |
+
+Every block needs a unique `id`. RichText + Callout use open/close tags (markdown body); everything else is self-closing.
+
+## Skeleton
+
+```mdx
+<RichText id="overview">
+## What this is
+
+One sentence the reader can't miss.
+</RichText>
+
+<Stat id="headline" label="X shipped" value="7" trend="flat" hint="across v3.22 → v4.4.7" />
+
+<Callout id="tldr" tone="success">
+One-sentence TL;DR.
+</Callout>
+
+<Table
+  id="releases"
+  columns={["v", "what", "fix"]}
+  rows={[
+    ["3.22", "unified", "—"],
+    ["4.4.1", "bg fix", "process exit crash"],
+  ]}
+/>
+
+<FileTree
+  id="files"
+  title="Files changed"
+  entries={[
+    { path: "cli/provision.mjs", change: "added", note: "unified provisioner" },
+  ]}
+/>
+```
+
+## The 5 things that break a glyph
+
+These shipped as bugs. Read before writing.
+
+### 1. Backticks inside attribute strings
+
+The parser scans for `` ` `` and breaks. Use straight quotes or rephrase:
+
+```
+WRONG: Run `bizar install` to bootstrap.
+RIGHT: Run 'bizar install' to bootstrap.
+```
+
+### 2. Braces inside string values
+
+The brace counter doesn't know about strings. `{` / `}` in notes still bump depth. Keep note strings brace-free.
+
+### 3. `FileTree` `change` must be exact
+
+`added | modified | removed | renamed`. Empty string or `null` crashes on `t.bg`. Default to `modified` with a `note` when unclear.
+
+### 4. Duplicate block ids
+
+Comment pins and error reporting key off ids. Two blocks with the same id collide.
+
+### 5. `## Heading <768px`
+
+The parser sees `<7` as a malformed JSX tag. Use parentheses or colons.
+
+## Validate before shipping
+
+```bash
+node -e "import('./bizar-dash/src/server/glyphs/mdx-compiler.mjs').then(m => { \
+  const fs = require('node:fs'); \
+  const out = m.compileGlyphMdxSync(fs.readFileSync('artifacts/<slug>/artifact.mdx','utf8')); \
+  console.log('blocks:', out.blocks.length, 'errors:', out.errors.length); \
+})"
+```
+
+Also check yourself: does it fit on one screen? Are there any 4-sentence RichText blocks? Are the stats/tables/file trees doing the heavy lifting? If not, rewrite.
+
+## See also
+
+- `bizar-dash/src/server/glyphs/mdx-compiler.mjs` — parser
+- `bizar-dash/src/web/views/glyphs/GlyphRenderer.tsx` — React renderer (has error banner)
+- `bizar-dash/src/web/views/glyphs/components.tsx` — block implementations

package/.claude/worktrees/kanban-overhaul/.claude/skills/harness-engineering/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: harness-engineering
+description: Use when designing or evaluating the environment around an AI coding agent — instructions, state, verification, scope, and lifecycle. Triggers on questions about agent harness design, session lifecycle, definition of done, scope discipline, state persistence, loop engineering, context engineering, or observability. Synthesizes the walkinglabs/awesome-harness-engineering canon with Bizar's Norse-pantheon architecture so every agent session starts from a strong baseline.
+---
+
+# Harness Engineering for Bizar agents
+
+The model decides the code. The harness decides when, where, and how.
+Without a harness, even Opus 4.5 spends $9 in 20 minutes and ships
+something broken; with one it ships working code in 6 hours. Same model,
+different environment.
+
+References:
+- walkinglabs/awesome-harness-engineering (curated canon)
+- walkinglabs/learn-harness-engineering (13 lectures, 7 projects)
+- Anthropic: "Effective harnesses for long-running agents"
+- Anthropic: "Effective context engineering for AI agents"
+- OpenAI: "Harness engineering: leveraging Codex in an agent-first world"
+
+## Five subsystems of a harness
+
+```
+                THE HARNESS
+                ============
+
+   Instructions       State            Verification
+   -----------       -----            ------------
+   AGENTS.md         PROGRESS.md      make check
+   CLAUDE.md         feature_list.json make test
+   .claude/          .harness/traces/ make e2e
+     agents/         DECISIONS.md     make clean-check
+     skills/         init.sh output
+     hooks/
+
+   Scope              Session Lifecycle
+   -----              ------------------
+   WIP=1 rule         make session-start
+   one feature        make session-end
+   per session        init.sh (install + verify)
+   explicit DoD       clean restart
+```
+
+Bizar ships all five. This skill is your reminder to use them.
+
+## Session lifecycle (L06, L12)
+
+Every agent session MUST follow this lifecycle:
+
+1. **Read AGENTS.md** — your operating manual.
+2. **Read CLAUDE.md** — Claude Code mirror of AGENTS.md (auto-loaded).
+3. **Read .claude/agents/_shared/AGENT_BASELINE.md** — baseline behavior rules.
+4. **Run `make session-start`** — record session ID.
+5. **Read PROGRESS.md** — state from the last session.
+6. **Read feature_list.json** — pick the next `not_started` feature.
+7. **Work on ONE feature only** — WIP=1.
+8. **Run verification:** `make check && make test && make e2e`.
+9. **Update PROGRESS.md + feature_list.json** — record evidence.
+10. **Score against `templates/evaluator-rubric.md`** — every dim B+.
+11. **Run `make session-end`** — close the session.
+12. **Commit only when safe to resume** (Hermod does this).
+
+If you find yourself doing steps 7-9 on more than one feature, stop.
+
+## Definitions of Done (L08, L09)
+
+A feature is `passing` only when ALL THREE LAYERS verify:
+
+- **L1 typecheck:** `make check` exits 0.
+- **L2 unit tests:** `make test` passes for the touched module.
+- **L3 E2E:** `make e2e` exercises real plugin load + tools.
+
+Do NOT proceed to L(n+1) if L(n) fails. Confidence ≠ correctness.
+
+## Scope discipline (L07)
+
+- WIP=1. Only one feature `active` in `feature_list.json`.
+- No silent scope creep. If a fix requires touching unrelated code,
+  STOP and report — do not improvise.
+- No half-finishing three things. No rewriting the feature list to
+  hide unfinished work.
+
+## State persistence (L05)
+
+- Progress belongs in PROGRESS.md + feature_list.json + git log.
+- The repo is the single source of truth. If the agent can't see it,
+  it doesn't exist.
+- Handoff note: every session must leave a clean restart path.
+
+## Loop engineering (L13)
+
+When you find yourself repeating the same manual orchestration, build a
+loop. Three primitives:
+
+1. **Goal loop** — `while !done; run-one-step; done`
+2. **Timer loop** — `every N minutes: run-the-job`
+3. **Maker-checker loop** — `make.sh` produces, `check.sh` rejects
+
+Bizar ships three:
+- `scripts/run-loop.sh` — generic loop driver (see below)
+- `make test` — verification (checker)
+- `scripts/clean-state-check.sh` — final pass/fail gate
+
+## Context engineering (Anthropic)
+
+Treat the context window as a working memory budget, not a dump site:
+
+- Progressive disclosure: load skills on demand, not all at once.
+- KV-cache locality: keep system prompts stable; append, don't rewrite.
+- Drop noisy tool output before passing to the next model call.
+
+## Observability (L11, OTel)
+
+If you can't see what the agent did, you can't fix what it broke. Bizar
+records every session to `.harness/traces/sessions.jsonl` (gitignored)
+and via the SessionEnd hook to `~/.bizar_home/memory/projects/<name>/sessions/`.
+For OpenTelemetry-compatible exporters, see `packages/sdk/src/observability.ts`.
+
+## Sandbox (CubeSandbox — v6.3.0)
+
+For dangerous-pattern decisions and risky operations, Bizar routes the
+execution through `bizar_sandbox_run` (CubeSandbox) instead of running
+directly in the host shell. See the `cubesandbox` skill.
+
+## Quick checklist before each commit
+
+- [ ] feature_list.json updated (state machine moved)
+- [ ] PROGRESS.md updated (current state, in progress, next steps)
+- [ ] `make check` exits 0
+- [ ] `make test` exits 0
+- [ ] `make e2e` exits 0
+- [ ] `make clean-check` 5/5 dimensions pass
+- [ ] Every dim of `templates/evaluator-rubric.md` is B+
+- [ ] Commit message is WHY-focused, not WHAT-focused
+
+## Further reading
+
+The skill `find-skills` can install the full walkinglabs course. The
+local copy lives at `bizar-learn-harness` (auto-bundled by
+`scripts/install-learn-course.sh`). To rebuild locally:
+
+```bash
+git clone https://github.com/walkinglabs/learn-harness-engineering /tmp/lhe
+```

package/.claude/worktrees/kanban-overhaul/.claude/skills/lightrag/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: lightrag-instructions
+description: Always-on rules for the LightRAG mod. When the LightRAG server is running, prefer the knowledge graph for cross-document questions before re-reading source files. Triggers on questions where LightRAG should be queried (cross-document semantic questions, entity/relationship lookups) instead of grep-style searches.
+---
+
+# LightRAG — Installed Instructions
+
+These rules apply whenever the **lightrag** mod is enabled and the LightRAG server is running (default port 9621).
+
+## What is LightRAG?
+
+LightRAG is a graph-based Retrieval-Augmented Generation system. It builds a knowledge graph from ingested documents and answers questions by traversing entities and relationships, not just keyword-matching chunks.
+
+The Bizar dashboard exposes a LightRAG view at `/lightrag` that lets you:
+- Insert documents (text, file paths, URLs)
+- Query the knowledge graph (5 modes: local, global, hybrid, naive, mix)
+- Inspect entities and relationships
+- See query history
+
+The HTTP server runs at `http://127.0.0.1:9621` by default. The Bizar dashboard talks to it via the REST API.
+
+## When to Use LightRAG (vs grep / Semble)
+
+**Use LightRAG for:**
+- "What does this codebase say about X?" (semantic, not literal)
+- "What entities relate to Y?" (graph traversal)
+- "Summarize all documentation about Z"
+- "Find all decisions made about authentication"
+- Any cross-document question where grep would give 30+ results
+
+**Use grep / Semble for:**
+- Single-line, single-file lookups
+- "Does the string `TODO` exist?"
+- "Where is function X defined?"
+
+**Use Semble for:**
+- Code-aware semantic search
+- "What calls function X?" (with file:line)
+- "Find the line that handles auth"
+
+LightRAG is for **natural-language questions about content**, not code structure.
+
+## Rules by Agent
+
+### @mimir (research)
+- Before deep-diving into a research question with 20+ tool calls, query the LightRAG knowledge graph first: `POST /query` with the question text. The graph often points you at the right document in 1-2 calls.
+- If LightRAG returns no results, fall back to Semble and grep. Don't force-fit results.
+- After running any new document through LightRAG, the graph updates — query again to see the new context.
+
+### @frigg (Q&A)
+- When the user asks a project-specific question that grep can't answer (e.g. "what did we decide about X?"), check LightRAG first via `POST /query` with the question as the query text.
+- LightRAG returns retrieved context with the answer. Use that as the basis for the response.
+
+### @odin (router)
+- After completing a piece of work that produced documentation (decisions, postmortems, ADRs), consider whether the content should be ingested into LightRAG. If yes, call the dashboard's `/api/mods/lightrag/insert` with the file path.
+
+## API quick reference
+
+```
+POST /query              — body: { query: string, mode: "mix" | "local" | "global" | "hybrid" | "naive" }
+POST /insert/text        — body: { text: string, id?: string }
+POST /insert/file        — body: { path: string }   (file is read and ingested)
+GET  /entities            — list entities
+GET  /relations           — list relationships
+GET  /status              — server health + counts
+```
+
+All endpoints are at `http://127.0.0.1:9621` (or via the dashboard at `/api/mods/lightrag/proxy/*`).
+
+## Common pitfalls
+
+- **Embedding model must be set before indexing.** If you change it, re-embed all text chunks, entities, and relationships. (LightRAG does not provide a re-embedding tool.)
+- **Vector dimension depends on the embedding model.** Some storage backends (e.g. PostgreSQL) require the vector dimension to be defined when creating tables. If you change the embedding model, you may need to drop and recreate the vector tables.
+- **The server binds to 127.0.0.1 by default.** The dashboard proxies requests to it. If you want to access LightRAG from outside the host, set `host: 0.0.0.0` in the mod config.
+- **First query is slow** (~3s) because the graph cache is cold. Subsequent queries are faster.
+
+## See also
+
+- LightRAG docs: https://github.com/HKUDS/LightRAG
+- Bizar mod guide: `.obsidian/reference/mods.md`
+- Dashboard mod config: `Settings → Mods → LightRAG`

package/.claude/worktrees/kanban-overhaul/.claude/skills/memory-protocol/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: memory-protocol
+description: How Bizar agents use the project memory vault via the `bizar memory` CLI. Read at session start, append on session end. No codebase exploration needed. Triggers on session-start checks, memory writes/reads, and any vault interaction.
+---
+
+# 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.