npm - @polderlabs/bizar - Versions diffs - 10.7.1 → 10.7.2 - Mend

@polderlabs/bizar 10.7.1 → 10.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

package/.claude/agents/_shared/AGENT_BASELINE.md +266 -0
package/.claude/agents/_shared/CLAUDE_TOOLS.md +412 -0
package/.claude/agents/_shared/SKILLS.md +109 -0
package/.claude/agents/brand-designer.md +55 -0
package/.claude/agents/exec-assistant.md +34 -0
package/.claude/agents/help-desk.md +44 -0
package/.claude/agents/it-lead.md +53 -0
package/.claude/agents/knowledge-manager.md +49 -0
package/.claude/agents/office-coordinator.md +39 -0
package/.claude/agents/office-greeter.md +53 -0
package/.claude/agents/office-manager.md +287 -0
package/.claude/agents/principal-engineer.md +58 -0
package/.claude/agents/qa-reviewer.md +51 -0
package/.claude/agents/research-analyst.md +53 -0
package/.claude/agents/senior-engineer.md +55 -0
package/.claude/agents/support-tech.md +87 -0
package/.claude/agents/vp-engineering.md +54 -0
package/.claude/commands/audit.md +48 -0
package/.claude/commands/bizar.md +22 -0
package/.claude/commands/cron.md +36 -0
package/.claude/commands/explain.md +17 -0
package/.claude/commands/goal.md +99 -0
package/.claude/commands/init.md +15 -0
package/.claude/commands/learn.md +46 -0
package/.claude/commands/plan.md +35 -0
package/.claude/commands/plow-through.md +50 -0
package/.claude/commands/pr-review.md +49 -0
package/.claude/commands/setup-provider.md +96 -0
package/.claude/commands/spec.md +47 -0
package/.claude/commands/sprint.md +43 -0
package/.claude/commands/tailscale-serve.md +100 -0
package/.claude/commands/team.md +132 -0
package/.claude/commands/test.md +62 -0
package/.claude/commands/validate.md +68 -0
package/.claude/commands/visual-plan.md +24 -0
package/.claude/hooks/README.md +108 -0
package/.claude/hooks/__tests__/pretooluse-editwrite.test.mjs +146 -0
package/.claude/hooks/__tests__/sessionend-recall.test.mjs +256 -0
package/.claude/hooks/__tests__/sessionstart-prime.test.mjs +325 -0
package/.claude/hooks/__tests__/thinking-route.test.mjs +319 -0
package/.claude/hooks/auto-instinct.sh +81 -0
package/.claude/hooks/learning-extract.mjs +92 -0
package/.claude/hooks/post-merge-audit.sh +93 -0
package/.claude/hooks/posttooluse-editwrite.mjs +91 -0
package/.claude/hooks/pretooluse-bash.mjs +87 -0
package/.claude/hooks/pretooluse-editwrite.mjs +117 -0
package/.claude/hooks/sessionend-recall.mjs +384 -0
package/.claude/hooks/sessionstart-prime.mjs +278 -0
package/.claude/hooks/thinking-route.mjs +314 -0
package/.claude/hooks/worker-suggest.mjs +110 -0
package/.claude/settings.json +167 -0
package/.claude/skills/9router/SKILL.md +80 -0
package/.claude/skills/9router-chat/SKILL.md +73 -0
package/.claude/skills/9router-embeddings/SKILL.md +69 -0
package/.claude/skills/9router-image/SKILL.md +86 -0
package/.claude/skills/9router-stt/SKILL.md +79 -0
package/.claude/skills/9router-tts/SKILL.md +80 -0
package/.claude/skills/9router-web-fetch/SKILL.md +99 -0
package/.claude/skills/9router-web-search/SKILL.md +91 -0
package/.claude/skills/agent-browser/SKILL.md +64 -0
package/.claude/skills/bizar/README.md +9 -0
package/.claude/skills/bizar/SKILL.md +447 -0
package/.claude/skills/cpp-coding-standards/README.md +28 -0
package/.claude/skills/cpp-coding-standards/SKILL.md +634 -0
package/.claude/skills/cpp-coding-standards/references/concurrency.md +320 -0
package/.claude/skills/cpp-coding-standards/references/error-handling.md +229 -0
package/.claude/skills/cpp-coding-standards/references/memory-safety.md +216 -0
package/.claude/skills/cpp-coding-standards/references/modern-idioms.md +282 -0
package/.claude/skills/cpp-coding-standards/references/review-checklist.md +96 -0
package/.claude/skills/cpp-testing/README.md +28 -0
package/.claude/skills/cpp-testing/SKILL.md +304 -0
package/.claude/skills/cpp-testing/references/coverage.md +370 -0
package/.claude/skills/cpp-testing/references/framework-compare.md +175 -0
package/.claude/skills/cpp-testing/references/host-test-for-embedded.md +499 -0
package/.claude/skills/cpp-testing/references/mocking.md +364 -0
package/.claude/skills/cpp-testing/references/tdd-workflow.md +308 -0
package/.claude/skills/cubesandbox/SKILL.md +148 -0
package/.claude/skills/de-sloppify/SKILL.md +38 -0
package/.claude/skills/de-sloppify/cleanup.mjs +253 -0
package/.claude/skills/de-sloppify/cleanup.test.mjs +189 -0
package/.claude/skills/embedded-esp-idf/README.md +41 -0
package/.claude/skills/embedded-esp-idf/SKILL.md +439 -0
package/.claude/skills/embedded-esp-idf/references/freertos-patterns.md +214 -0
package/.claude/skills/embedded-esp-idf/references/host-tests.md +164 -0
package/.claude/skills/embedded-esp-idf/references/idf-py-commands.md +157 -0
package/.claude/skills/embedded-esp-idf/references/kconfig.md +159 -0
package/.claude/skills/embedded-esp-idf/references/logging-discipline.md +118 -0
package/.claude/skills/embedded-esp-idf/references/memory-and-iram.md +137 -0
package/.claude/skills/embedded-esp-idf/references/nvs.md +121 -0
package/.claude/skills/embedded-esp-idf/references/packed-structs.md +192 -0
package/.claude/skills/embedded-esp-idf/scripts/idf_env.sh +47 -0
package/.claude/skills/embedded-esp-idf/scripts/size_check.sh +77 -0
package/.claude/skills/glyph/SKILL.md +163 -0
package/.claude/skills/harness-engineering/SKILL.md +142 -0
package/.claude/skills/lightrag/SKILL.md +81 -0
package/.claude/skills/memory-protocol/SKILL.md +105 -0
package/.claude/skills/obsidian/SKILL.md +306 -0
package/.claude/skills/read-the-damn-docs/SKILL.md +113 -0
package/.claude/skills/self-improvement/SKILL.md +64 -0
package/.claude/skills/skillopt/SKILL.md +129 -0
package/.claude/skills/thinking-archetypes/SKILL.md +90 -0
package/.claude/skills/thinking-bayesian/SKILL.md +267 -0
package/.claude/skills/thinking-bounded-rationality/SKILL.md +406 -0
package/.claude/skills/thinking-circle-of-competence/SKILL.md +216 -0
package/.claude/skills/thinking-cynefin/SKILL.md +70 -0
package/.claude/skills/thinking-debiasing/SKILL.md +192 -0
package/.claude/skills/thinking-dual-process/SKILL.md +282 -0
package/.claude/skills/thinking-effectuation/SKILL.md +366 -0
package/.claude/skills/thinking-feedback-loops/SKILL.md +464 -0
package/.claude/skills/thinking-fermi-estimation/SKILL.md +263 -0
package/.claude/skills/thinking-first-principles/SKILL.md +167 -0
package/.claude/skills/thinking-five-whys-plus/SKILL.md +139 -0
package/.claude/skills/thinking-inversion/SKILL.md +195 -0
package/.claude/skills/thinking-jobs-to-be-done/SKILL.md +363 -0
package/.claude/skills/thinking-kepner-tregoe/SKILL.md +154 -0
package/.claude/skills/thinking-leverage-points/SKILL.md +390 -0
package/.claude/skills/thinking-lindy-effect/SKILL.md +331 -0
package/.claude/skills/thinking-map-territory/SKILL.md +111 -0
package/.claude/skills/thinking-margin-of-safety/SKILL.md +330 -0
package/.claude/skills/thinking-model-combination/SKILL.md +406 -0
package/.claude/skills/thinking-model-router/SKILL.md +360 -0
package/.claude/skills/thinking-model-selection/SKILL.md +341 -0
package/.claude/skills/thinking-occams-razor/SKILL.md +129 -0
package/.claude/skills/thinking-ooda/SKILL.md +127 -0
package/.claude/skills/thinking-opportunity-cost/SKILL.md +360 -0
package/.claude/skills/thinking-pre-mortem/SKILL.md +170 -0
package/.claude/skills/thinking-probabilistic/SKILL.md +324 -0
package/.claude/skills/thinking-red-team/SKILL.md +142 -0
package/.claude/skills/thinking-regret-minimization/SKILL.md +335 -0
package/.claude/skills/thinking-reversibility/SKILL.md +326 -0
package/.claude/skills/thinking-scientific-method/SKILL.md +162 -0
package/.claude/skills/thinking-second-order/SKILL.md +184 -0
package/.claude/skills/thinking-socratic/SKILL.md +198 -0
package/.claude/skills/thinking-steel-manning/SKILL.md +332 -0
package/.claude/skills/thinking-systems/SKILL.md +238 -0
package/.claude/skills/thinking-theory-of-constraints/SKILL.md +338 -0
package/.claude/skills/thinking-thought-experiment/SKILL.md +354 -0
package/.claude/skills/thinking-triz/SKILL.md +171 -0
package/.claude/skills/thinking-via-negativa/SKILL.md +358 -0
package/cli/install/postinstall.mjs +54 -28
package/cli/install/postinstall.test.mjs +98 -0
package/package.json +7 -2

package/.claude/skills/obsidian/SKILL.md ADDED Viewed

@@ -0,0 +1,306 @@
+---
+name: obsidian
+description: Use the Bizar Memory Service for persistent project knowledge — local Obsidian-compatible Markdown + Git-shared sync. Read vault entries before non-trivial decisions; write after meaningful work. Three layers: Markdown (truth) → Git (collaboration) → LightRAG (derived index, Phase 2).
+version: 2
+---
+# Bizar Memory Service — Project Knowledge
+**The Bizar Memory Service is the project's persistent knowledge layer.** It replaces the disabled Hindsight MCP service. Every Bizar project uses the same three-layer architecture; only the backend mode (`local-only` vs `managed`) and the vault location differ.
+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.**
+## Quick Start for Agents
+**First-time setup** (if `.bizar/memory.json` is missing):
+```bash
+bizar memory setup --remote git@github.com:you/bizar-memory.git
+bizar memory status    # confirm vault reachable
+bizar memory doctor    # schema + secrets + git state
+```
+Memory is accessed via the `bizar memory` CLI — agents have `bash: allow` and can invoke it directly.
+**Find the vault root:**
+```bash
+bizar memory status
+```
+**Search memory:**
+```bash
+bizar memory search "<query>"
+```
+**Read a specific note:**
+```bash
+# 1. List notes to find the path
+bizar memory list 2>/dev/null || ls ~/.local/share/bizar/memory/bizar-memory/projects/<projectId>/
+# 2. Read the note
+cat ~/.local/share/bizar/memory/bizar-memory/projects/<projectId>/<relpath>
+```
+**Write a new note:**
+```bash
+bizar memory write <relpath> \
+  --type <type> \
+  --status active \
+  --confidence verified \
+  --tag <tag1> --tag <tag2> \
+  --body "<body text>"
+```
+`<relpath>` is relative to the project namespace root (e.g. `decisions/0001-foo.md`). Do NOT include the `projects/<projectId>/` prefix — that double-nests.
+**Commit and push (if shared vault):**
+```bash
+bizar memory sync
+```
+**Health check:**
+```bash
+bizar memory doctor
+```
+## The three layers
+| Layer | Role | Backed by | Write path |
+|---|---|---|---|
+| **Markdown** | Canonical truth | Obsidian-flavoured `.md` files on disk | Author writes here; this is the only layer that is authoritative |
+| **Git** | Collaboration / history | The vault directory is a Git repo (local-only mode keeps it as a local repo with no remote) | The `bizar memory sync` orchestrator runs `git add/commit/push` after a write |
+| **LightRAG** (Phase 2) | Derived search index | A LightRAG server (disabled by default in `memory.json`) | NEVER write here directly — always rebuild from Markdown via `bizar memory reindex` |
+**Rule of thumb:** if you wanted to "update the project's memory," write Markdown. Git and LightRAG follow.
+## Vault location
+The root of the vault is determined by `.bizar/memory.json` in the active project. Two modes:
+- **`local-only` (default)** — vault is `.obsidian/` inside this project. Single-machine. Stays out of any cross-project repo. Use this when the project is solo or when the project itself is private.
+- **`managed`** — vault is `~/.local/share/bizar/memory/<repoName>/` (a user-level shared repo). Multiple projects contribute to the same Git repo under per-project namespaces. Use this when you want cross-project search and a single source of truth across all your Bizar projects.
+`bizar memory status` prints the active mode and resolved paths; `bizar memory doctor` validates the vault is reachable and the Git state is consistent.
+## The three namespaces
+Namespaces live at the vault root. Pick a namespace by deciding the SCOPE of the note, not the project.
+| Namespace | Path (under vault root) | When to write here |
+|---|---|---|
+| **project** | `projects/<projectId>/` | Anything specific to THIS project — design decisions, postmortems, agent-tuning notes, project-local gotchas, daily logs of what happened in this repo |
+| **global** | `global/bizar/` | Anything that applies to Bizar AS A SYSTEM, regardless of project — agent patterns, model-routing rules, CLI conventions, cross-project gotchas that should reach every project you work on |
+| **user** | `users/<userId>/` | Anything that is purely personal — your preferences, your scratch notes, your "things I keep forgetting" |
+Resolution rule: **memory root = `~/.local/share/bizar/memory/<repoName>/` (or `.obsidian/`) + the namespace you picked**. The `projectId` is the basename of the project root (e.g. `bizar` for `/path/to/bizar`); the `userId` is the OS username.
+When in doubt, write to **project**. Promote to **global** only when the pattern repeats across another project; demote to **user** only when it's purely personal preference.
+## How to read vault entries
+### Via the dashboard REST API (canonical)
+```bash
+# List notes under a namespace
+curl -s http://127.0.0.1:4321/api/memory/notes?namespace=projects/bizar | jq
+# Read a specific note (returns parsed frontmatter + body)
+curl -s http://127.0.0.1:4321/api/memory/notes/projects/bizar/Architecture.md | jq
+# Full-text search (Markdown content + frontmatter)
+curl -s -X POST http://127.0.0.1:4321/api/memory/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"router ordering","namespace":"projects/bizar"}' | jq
+```
+### Via the CLI
+```bash
+bizar memory search "router ordering"           # full-text search
+bizar memory status                             # show mode + paths + git status
+bizar memory doctor                             # health check
+bizar memory log --tail 20                      # recent operations log
+bizar memory conflicts                          # list notes with status=conflict
+```
+## Operations
+- **Open in Obsidian**: `/kb` — opens the project vault in Obsidian (resolves
+  from .bizar/memory.json; falls back to printing the path if Obsidian isn't
+  installed)
+### Via direct file read (acceptable for one-off reads)
+```bash
+# local-only
+cat .obsidian/projects/<projectId>/Architecture.md
+# managed
+cat ~/.local/share/bizar/memory/bizar-memory/projects/<projectId>/Architecture.md
+```
+Direct reads bypass the dashboard, which is fine for diagnostics. Bypass the dashboard for writes too ONLY in an emergency (CI recovery, hook-driven bots) — always prefer the API for agent-driven writes so the schema, secret scan, and Git sync run.
+## How to write vault entries
+### Via the dashboard REST API (canonical)
+```bash
+# Write or update a note — the API validates schema, scans for secrets, and
+# runs the sync orchestrator (git commit) if memory.json.git.autoCommit is on.
+curl -s -X POST http://127.0.0.1:4321/api/memory/notes \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "path": "projects/bizar/adr/0001-router-ordering.md",
+    "namespace": "projects/bizar",
+    "frontmatter": {
+      "title": "Router ordering: Forseti before Tier 4/5",
+      "type": "architecture_decision",
+      "status": "active",
+      "confidence": "verified",
+      "date": "2026-06-29",
+      "tags": ["router", "agents"]
+    },
+    "body": "## Context\n...\n## Decision\n...\n## Consequences\n..."
+  }'
+# LightRAG reindex — NEVER run during a write. Schedule from the
+# orchestrator or run manually after a batch of writes.
+curl -s -X POST http://127.0.0.1:4321/api/memory/reindex \
+  -H 'Content-Type: application/json' \
+  -d '{"namespace":"projects/bizar"}'
+```
+The rich shape (path, namespace, frontmatter, body) is the canonical write. The legacy `/api/obsidian/notes` endpoint accepts the same body wrapped as `{ content: "<frontmatter + body>", path, namespace }` for back-compat.
+### Via the CLI
+```bash
+bizar memory write "<path>"                       # opens $EDITOR for the body
+bizar memory sync                                 # git add/commit/push the staged notes
+bizar memory commit -m "adr: 0001 router ordering"
+bizar memory pull                                 # fetch + rebase from configured remote
+bizar memory push                                 # push committed notes to remote
+bizar memory reindex                              # rebuild LightRAG from Markdown (Phase 2)
+bizar memory conflicts                            # human review surface for status=conflict
+```
+## When to read
+- **At the start of every session** — skim the project namespace's index entries (`index/`, `_index.md`, anything tagged `type: project_index`).
+- **Before any non-trivial implementation decision** — search the relevant namespace for prior art.
+- **When you're about to suggest something the user has already tried** — search before recommending.
+- **When the codebase feels like it's working around something you don't understand** — there's probably a vault entry explaining the why.
+- **When you encounter a `// FIXME` or `// HACK` comment** — there's probably a vault entry explaining it.
+- **Before claiming a pattern is "the Bizar way"** — global namespace might say otherwise.
+## When to write
+- **After completing a meaningful piece of work** — what was decided, what was learned, what the consequences were.
+- **On discovering a bug or postmortem** — `type: bug_postmortem` with the root cause, evidence links, and the fix.
+- **When you find a pattern that should be reused** — `type: pattern`, with the rationale and a code snippet.
+- **When the user corrects you** — `type: lesson_learned` with what was wrong, why, and the new rule.
+- **When you make a design decision that should be remembered** — `type: architecture_decision` (the classic ADR format).
+- **When you encode an active rule** that future sessions should follow — `type: active_rule`, and (importantly) also add it to `.bizar/AGENTS_SELF_IMPROVEMENT.md` under "Active Rules" so the orchestrator picks it up before vault lookups.
+## Write categories (matches the 11 schema `type` values)
+| type | Use when |
+|---|---|
+| `architecture_decision` | ADR — context, decision, consequences |
+| `pattern` | Reusable approach with code example |
+| `lesson_learned` | A mistake or surprise the next agent should not repeat |
+| `bug_postmortem` | Root-cause analysis of an actual bug, with evidence |
+| `active_rule` | A standing rule for this project (mirror in `.bizar/AGENTS_SELF_IMPROVEMENT.md`) |
+| `agent_memory` | Per-agent history — what THIS agent learned across sessions |
+| `project_index` | Top-level entry points (`Architecture`, `Conventions`, `Entry-Points`) |
+| `reference` | External API docs, tool notes, library gotchas |
+| `workflow` | Multi-step procedure with prerequisites + steps + verification |
+| `note` | Free-form scratch that doesn't fit another category |
+| `adr` | Alias for `architecture_decision` (kept for legacy writers) |
+## Status values (frontmatter `status`)
+| status | Meaning | When to use |
+|---|---|---|
+| `active` | Current truth | The note still reflects reality |
+| `draft` | Work in progress | Agent is still thinking; do not auto-commit |
+| `superseded` | Replaced by a newer note | **Always link `superseded_by` to the replacement** |
+| `stale` | Probably outdated | Needs human review — the orchestrator tags these after a `--reindex` heuristic |
+| `conflict` | Two versions disagree | **Requires human resolution** — never auto-resolve |
+| `archived` | Kept for history, not searched | Visible only with explicit namespace filter |
+## Confidence values (frontmatter `confidence`)
+| confidence | Meaning | Rule |
+|---|---|---|
+| `verified` | Proven with evidence | Always link the evidence file in the note body (`path:line` citation) |
+| `inferred` | Likely true but unproven | Phrase the body as "appears to be" / "based on X, looks like" |
+| `speculative` | Hypothesis to test | Mark with `type: pattern` and a clear "to verify" section |
+**Prefer `verified`.** A note with no evidence is a hypothesis at best. The schema rejects writes missing required fields for `architecture_decision` and `lesson_learned`.
+## Conflict handling
+The service NEVER auto-resolves a conflict. When the same path is written from two sources (e.g. local edit + remote pull that doesn't fast-forward), the orchestrator:
+1. Renames the incoming version to `<path>.conflict-<timestamp>.md`.
+2. Sets BOTH versions' `status: conflict`.
+3. Exits non-zero so the user can review.
+4. Lists both in `bizar memory conflicts`.
+Human resolution:
+1. Read both versions.
+2. Decide which is canonical (usually the more recent or more evidence-backed).
+3. Edit the losing version: `status: superseded`, set `superseded_by: <winning-path>`, add a `## Why this was superseded` section.
+4. `bizar memory sync` to commit the resolution.
+Never delete a superseded note — history matters.
+## Secret scanning (commit gate)
+`bizar memory commit` (and the auto-commit path during a write) runs the secret scanner over the staged Markdown. Severities:
+- **HIGH** — real API keys, bearer tokens, PEM blocks, password= assignments → **BLOCKS the commit**. Fix the leak first, then commit. Use `.template` files and `.gitignore` for live secrets (see `.bizar/AGENTS_SELF_IMPROVEMENT.md` rule #4 for the token-leak history).
+- **MEDIUM** — credential-like patterns (e.g. `ghp_*` with weak validation), obvious test fixtures that could be mistaken for real keys → warns. Commit proceeds unless `--strict`.
+- **LOW** — possible PII, dev URLs on non-public hosts → informational.
+Override flags: `--allow-secrets` (HIGH-bypass), `--strict` (LOW-becomes-warning). Never use `--allow-secrets` to ship a real credential — fix the secret in the source, not the gate.
+## Markdown conventions (Obsidian-flavoured)
+- **Frontmatter is YAML** between the leading and trailing `---` lines. Required keys depend on `type`; the validator in `memory-schema.mjs` enforces this.
+- **`[[wikilinks]]`** point at note paths relative to the vault root (e.g. `[[projects/bizar/Architecture]]`, not `[[Architecture]]`).
+- **Tag lists** (`tags: [a, b]`) drive search; keep them short and concrete.
+- **Code blocks** with language tags survive parsing — use them for snippets longer than 2 lines.
+- **Callouts** (`> [!note]`, `> [!warning]`) are preserved; use `> [!danger]` for HIGH-severity warnings.
+- **Status emojis** are noise — keep notes emoji-free unless the user has put one in the frontmatter.
+## Sync model
+The vault directory is a Git repo. `bizar memory sync` does, in order:
+1. **Pull** — `git fetch` and `git rebase` from the configured remote (no-op for local-only).
+2. **Schema check** — every staged file is validated by the schema in `memory-schema.mjs`. Bad files become `untracked` until fixed.
+3. **Secret scan** — staged content is scanned; HIGH blocks, MEDIUM warns.
+4. **Stage** — `git add` of all Markdown under the vault root.
+5. **Commit** — `git commit` with `commitMessageTemplate` (default `memory({projectId}): {summary}`).
+6. **Push** — only if `memory.json.git.autoPushOnSessionEnd` is true.
+`autoCommitOnMemoryWrite` defaults to `false` — writes return success without committing. The user reviews and runs `bizar memory sync` themselves. This is the default for production deployments.
+## What NOT to write
+- **Secrets, API keys, tokens** — the secret scanner blocks them, but defense in depth: never produce them in the first place.
+- **Temporary scratch that won't be useful in 7 days** — keep that in a TODO comment in code, not the vault.
+- **Long code dumps** — link with `path:line` so the note stays a living doc. Two-line snippets are fine.
+- **Anything already obvious from reading the code** — the vault is for things code CAN'T say.
+- **Notes that are already in another namespace** — search before writing to avoid duplicates; if you must mirror, link with `mirror_of: <other-path>`.
+## See also
+- `.bizar/AGENTS_SELF_IMPROVEMENT.md` — project-specific active rules (read before vault lookups).
+- `.bizar/PROJECT.md` — stack, conventions, entry points (Vör reads this first).
+- `wiki/Architecture.md` — system-level architecture, including the Memory section.
+- `wiki/Self-Improvement.md` — self-improvement log conventions.
+- `config/skills/glyph/SKILL.md` — graphify knowledge graph (separate from the memory vault).
+- `config/skills/obsidian-skills/SKILL.md` — Obsidian Markdown / Bases / Canvas / CLI (auto-installed by `install.sh` via `skills add kepano/obsidian-skills`).

package/.claude/skills/read-the-damn-docs/SKILL.md ADDED Viewed

@@ -0,0 +1,113 @@
+---
+name: read-the-damn-docs
+description: When using a library, tool, or API you don't fully understand, READ THE DOCS before guessing. Don't infer behavior from function names. The source of truth is the official documentation and source code, not your prior assumptions.
+version: 1
+---
+# Read the Damn Docs
+When you reach for a library, tool, or API you haven't used recently (or ever), **read the actual documentation** before writing code. Don't guess. Don't infer from function names. Don't assume "it probably works like X". The source of truth is the docs, then the source code, then examples. Everything else is noise.
+## Why this skill exists
+LLMs are confidently wrong. They have a strong prior for "this is what libraries usually look like" — and that prior is sometimes right but often subtly wrong. Common failure modes:
+- "The function is called `parseFoo` so it probably takes a string and returns an object" — wrong, it takes `{format, version}` and returns a promise
+- "I'll just try it and see what error comes back" — wastes a turn, often hallucinates the fix
+- "The README has an example, that's enough" — examples are cherry-picked; edge cases will bite you
+The fix: spend 30-90 seconds reading the docs first. The cost is a single tool call. The benefit is a correct first attempt.
+## Hierarchy of truth
+When resolving how a library/tool/API works, use this priority order:
+1. **Official documentation** (the canonical reference) — most authoritative
+2. **Source code** (the actual implementation) — definitive when docs are vague
+3. **Examples** (in the docs or repo) — show typical use, but don't trust edge cases
+4. **StackOverflow / GitHub issues** — useful for known footguns
+5. **Your prior model** — last resort, often wrong
+**Stop at step 1 unless the docs are unclear.** If they are, drop to step 2.
+## Practical workflow
+```
+1. IDENTIFY: "I'm about to use library X for the first time (or first time in months)"
+2. READ: webfetch the official docs for the specific function/method I'll call
+   - Don't read the entire docs — read the specific section
+3. VERIFY: cross-check against source if anything is ambiguous
+4. NOTE: write down the gotchas in your agent memory or a relevant file
+5. USE: now write the code, knowing the actual API
+```
+## When to invoke this skill
+Use it whenever:
+- You're using a library you haven't touched in this session
+- You're using a function/method whose exact signature you don't remember
+- The function name is misleading or you have low confidence
+- You're upgrading to a new major version of a library
+- You're switching between similar libraries (axios vs fetch, etc.)
+- You're using a CLI tool you don't have muscle memory for
+- You're hitting an error you don't recognize and "guessing" the fix
+## Anti-patterns
+### "I'll just try it"
+Don't write code, run it, see the error, and fix from there. That works for trivial cases but burns turns on anything non-trivial. Read the docs first.
+### "The function name tells me what it does"
+`Array.prototype.flatMap`, `Promise.allSettled`, `fs.opendirSync` — names are hints, not specs. The actual behavior (sync vs async, return shape, error cases) is in the docs.
+### "I used this library before, I know it"
+Libraries change. APIs deprecate. Defaults shift. Even if you used something 6 months ago, a pam doc check (30 seconds) saves 10 minutes of debugging when your prior knowledge is stale.
+### "The README example is enough"
+README examples are demos, not documentation. They show one happy path. The real API has edge cases, error modes, and options that aren't in the example.
+### "The error message is enough to fix it"
+Sometimes. But error messages are often misleading or incomplete. Reading the docs for the function that errored often reveals the actual constraint.
+## Examples
+### Good: Read first
+```
+[Agent wants to use the Vite `defineConfig` API for the first time]
+Agent: "Let me check the Vite docs for the exact shape of `defineConfig`."
+[webfetch https://vitejs.dev/config/]
+Agent: "OK, `defineConfig` accepts a UserConfig object with `plugins`, `build`, etc.
+       I need a `define` key for compile-time constants."
+[Writes correct config]
+```
+### Bad: Guess
+```
+[Agent wants to use the Vite `defineConfig` API for the first time]
+Agent: "defineConfig is probably a function that takes a config object with
+       common options like plugins and build. Let me just write it."
+[Writes config with `define: { __VERSION__: '1.0' }`]
+[Runs vite build, gets a warning about an unexpected option]
+Agent: "Hmm, the docs must have changed. Let me guess it's a different syntax."
+[Wastes 2-3 turns guessing before reading the docs]
+```
+## Where to read
+- **Webfetch** the official docs URL: `webfetch <url>` — fast, gives you the actual current docs
+- **Source code** via Semble search: `semble search "functionName" <repo>` — useful when docs are vague
+- **Local docs** if available: `semble search "<query>" --content docs` for the project's own docs
+## See also
+- [[obsidian]] — write postmortems and patterns to the project vault
+- [[glyph]] — create a glyph when the design decision is non-trivial
+- The agent baseline — `simplest thing that works` rule

package/.claude/skills/self-improvement/SKILL.md ADDED Viewed

@@ -0,0 +1,64 @@
+---
+name: self-improvement
+description: Use when setting up, configuring, or debugging the project-level self-improvement system. Every task records lessons learned to .bizar/AGENTS_SELF_IMPROVEMENT.md for agent behavior improvement across sessions.
+---
+# Self Improvement
+Project-level learning system. Every task records what worked, what didn't, and what patterns to follow next time — stored in `.bizar/AGENTS_SELF_IMPROVEMENT.md` at the project root.
+## How It Works
+1. **Session start**: Odin reads `.bizar/AGENTS_SELF_IMPROVEMENT.md` from project root and factors active rules into routing
+2. **During work**: Agents follow documented patterns and avoid previously-caught mistakes
+3. **Task completion**: Odin dispatches @brenda to append a structured entry to the file
+4. **Next session**: The cycle repeats — agents get smarter over time
+## File Format
+The file lives at `<project-root>/.bizar/AGENTS_SELF_IMPROVEMENT.md`. Structure:
+```markdown
+# Self Improvement
+## Active Rules
+<!-- Keep top 5-10 actionable patterns here. Extract from recent entries. -->
+## Log
+### 2026-06-16: Brief descriptive title
+- **Context**: What was the task
+- **Lesson**: What we learned
+- **Pattern**: What to do next time
+- **Files**: src/foo.ts, src/bar.ts
+- **Agent**: todd, karen
+```
+## Entry Rules for Agents
+When writing an entry:
+- **File per project** — `.bizar/AGENTS_SELF_IMPROVEMENT.md` at the root of whatever project you're working in
+- **If file doesn't exist**, create it with the header template
+- **Entry format**: H3 date header, bullet list with Context, Lesson, Pattern, Files, Agent
+- **Active Rules**: At the top, keep 5-10 distilled patterns from recent entries. If adding a new entry makes it necessary, add a rule too or promote a pattern from an entry.
+- **Deduplicate**: Don't repeat the same lesson. If the same lesson comes up again, update the existing entry's date instead.
+- **Be specific**: "Always use strictNullChecks" not "TypeScript is good"
+- **Agent tag**: Use the subagent name (todd, karen, brenda, greg, etc.)
+## Setup
+For a new project where no such file exists yet, create the initial file:
+```
+# Self Improvement
+Template for project-specific agent learning. Entries are auto-appended by Odin
+at task completion and read at session start.
+## Active Rules
+<!-- Top 5-10 actionable patterns extracted from recent entries -->
+## Log
+```

package/.claude/skills/skillopt/SKILL.md ADDED Viewed

@@ -0,0 +1,129 @@
+---
+name: skillopt
+description: Microsoft's SkillOpt trains skill files via rollouts + reflection against a frozen target model. Install with `pip install skillopt` and produce a `best_skill.md`. Always human-review.
+---
+# SkillOpt Workflow
+## Overview
+SkillOpt (microsoft/SkillOpt, MIT-licensed) is a Microsoft Research Python tool that **optimizes skill files for a specific target model**. Given a starting `SKILL.md`, a target model (frozen), a benchmark of inputs, and a reward signal, SkillOpt runs a rollout → reflect → aggregate → select → update → evaluate loop and emits a `best_skill.md` artifact that scores higher against the held-out validation gate.
+It is *not* a general prompt editor and *not* a free-form rewriting tool. It is a closed-loop optimizer: it changes the skill text, runs the agent under the new skill against the benchmark, measures reward, and keeps mutations that improve the score.
+**Core Principle:** SkillOpt trains a skill file the way you'd fine-tune a model — with a held-out validation gate, a frozen target, and a reward signal — not by hand-tweaking prose. Don't commit the output without human review; treat `best_skill.md` as a candidate, not a verdict.
+## When to Use
+- A skill's quality is measurably degrading on a benchmark (success rate dropping, regression in eval)
+- You have a benchmark of representative inputs and a reward signal (task success / rubric score / pass-rate)
+- You want to A/B a new skill variant against the current one against the same target model
+- A skill has grown organically past ~200 lines and you suspect prose bloat is hurting recall
+Decision flow:
+```
+Skill quality question?
+  → Do you have a benchmark + reward + frozen target model? → no → DON'T RUN SKILLOPT (you can't measure without them)
+  → Is the skill underperforming on the gate? → no → no work to do
+  → Yes to both → see the 6-phase loop below
+```
+## When NOT to Use
+- **No benchmark, no reward, no frozen target.** SkillOpt needs all three. If any is missing, the loop has nothing to optimize against — you'll burn compute on something you can't evaluate. Compose the benchmark first or skip SkillOpt entirely.
+- **For a one-off skill polish.** SkillOpt is a multi-rollout loop with token cost on the order of dozens to hundreds of completions. For "rewrite this paragraph to be clearer," edit the skill by hand. Reach for SkillOpt when you have evidence the skill underperforms and a way to measure the fix.
+- **On a non-frozen target model.** If the target model is updating daily, the rollout scores are non-reproducible and the held-out gate stops meaning anything. Pin the model version and don't retrain against a moving target.
+- **Without human review of `best_skill.md`.** SkillOpt optimizes the reward signal — that is not the same as "is this skill correct, well-bounded, and aligned with what we want the agent to do." A skill that scores higher on the rubric can still be narrower, more brittle, or subtly off-vibe. Always review before committing.
+## The 6-Phase Loop
+```
+┌─ Phase 1: Rollout        ─ run the agent under the current skill against benchmark inputs
+│
+├─ Phase 2: Reflect        ─ for each rollout, capture which skill instructions helped vs hurt
+│
+├─ Phase 3: Aggregate      ─ across all rollouts, find recurring failure modes and structural patterns
+│
+├─ Phase 4: Select         ─ choose one mutation hypothesis (a concrete edit) to try next
+│
+├─ Phase 5: Update         ─ apply the mutation to produce a candidate skill
+│
+└─ Phase 6: Evaluate       ─ run the candidate against the HELD-OUT validation set; keep if it improves, drop if not
+                              ↑                                                              │
+                              └────────────── next iteration reuses the kept variant ─────────┘
+```
+### Phase 1 — Rollout
+Run the agent under the **frozen target model** with the current skill against the benchmark. Capture outputs + per-input scores. Don't peek at the validation set during this phase.
+### Phase 2 — Reflect
+For each rollout, ask: which lines of the skill contributed to the success or failure? Mark helpful / neutral / harmful spans. This is the closest you get to a teacher signal without a human labeler.
+### Phase 3 — Aggregate
+Across all rollouts this iteration, find the recurring failure modes. If 4 of 5 failures on a particular input pattern come from the same missing instruction in the skill, that's the highest-leverage next mutation.
+### Phase 4 — Select
+Pick **one** mutation to try. SkillOpt is not a search-and-replace shotgun; it's one edit per round. Co-edits entangle effects and make the held-out gate stop carrying signal.
+### Phase 5 — Update
+Apply the mutation. Save the candidate as a sibling file (e.g. `candidate-3.md`); never overwrite `SKILL.md` mid-loop.
+### Phase 6 — Evaluate
+Run the candidate against the **held-out validation set** (never been seen during Phases 1–5). If it improves the held-out gate, promote it to the next iteration's starting point. If it regresses, drop it and try a different mutation. Do not cherry-pick from a known input; the held-out gate is what makes the loop trustworthy.
+## How Bizar Agents Use It
+```bash
+# 1. Install (do this once per machine)
+pip install skillopt
+# 2. Set up a benchmark directory (you write this — SkillOpt doesn't generate it)
+#    benchmark/
+#    ├── inputs.jsonl       # one prompt per line, hold-out set included
+#    ├── reward.py          # your scoring fn: takes (prompt, completion) → float
+#    └── target_model.json  # the frozen target model spec (id + version pin)
+# 3. Run the loop against a draft skill
+python -m skillopt.cli optimize \
+  --skill config/skills/thinking-some-skill/SKILL.md \
+  --benchmark ./benchmark \
+  --out ./skillopt-out
+# 4. Inspect the output before committing anything
+ls skillopt-out/
+cat skillopt-out/best_skill.md
+diff config/skills/thinking-some-skill/SKILL.md skillopt-out/best_skill.md
+# 5. If the diff is genuinely better (held-out improvement + human review passes),
+#    replace the source. Otherwise discard and tune the benchmark.
+cp skillopt-out/best_skill.md config/skills/thinking-some-skill/SKILL.md
+```
+We do **not** vendor SkillOpt into the Bizar JS harness — the tool lives in Python (`pip install skillopt`), runs offline, and writes a markdown artifact. The Bizar loop is: write draft → run SkillOpt → human review `best_skill.md` → commit if better.
+## Pitfalls
+- **Don't retrain daily.** The target model is frozen for a reason; if your benchmark doesn't drift, the skill shouldn't either. Bumping SkillOpt runs on every PR turns the skill into a moving target the agent can't build a stable intuition against.
+- **Don't bypass the held-out gate.** It's tempting to "peek" at validation items to bias the mutation — that converts the loop into a curve-fit on a small set and the held-out number stops meaning anything. Hold-out integrity is the whole point.
+- **Never auto-commit `best_skill.md`.** It is a *candidate*. The reward signal optimizes task success; it does not optimize for tone, scope, or alignment with sibling skills in the same family. A/B test in shadow, then promote deliberately.
+- **Don't use SkillOpt on skills you don't have a benchmark for.** If the input space and reward are unknown, you're optimizing prose against nothing and will learn something — just not something useful.
+- **Don't optimize `thinking-*` skills together as one bundle.** They share front-matter shape but address different problem types; co-optimizing entangles their effects and makes individual improvements hard to attribute.
+## Relationship to Bizar's Existing Skill Pipeline
+| Concern | Owner |
+|---|---|
+| What skills ship | `config/skills/<name>/SKILL.md` (canonical, provisioned) |
+| Provision to user | `cli/provision.mjs:syncConfigExtras` + `writeBizarSkillLock` |
+| Skill discovery at runtime | `~/.claude/skills/<name>/SKILL.md` (provisioned mirror) |
+| Offline quality loop | SkillOpt (this skill) — run on a draft, produce `best_skill.md`, human-promote |
+| Editing prose by hand | You + your editor — fine for one-off tweaks, don't loop it |
+SkillOpt is a **research-quality tool** for the rare case where you have the benchmark, the reward, and the time. For 90% of skill edits, just write it well.