@polderlabs/bizar 10.7.2 → 10.11.0

package/bizar-dash/skills/publishing/SKILL.md

@@ -1,147 +0,0 @@
----
-name: publishing
-description: Cut and publish a release of BizarHarness (@polderlabs/bizar). Use when bumping version, updating CHANGELOG, committing release commits, tagging, pushing, or publishing to npm. Covers the 4 test runners, version bump rules, hotfixes, and 10 known pitfalls.
----
-
-# Publishing BizarHarness
-
-Cut a release of `@polderlabs/bizar`. Read `/home/drb0rk/Projects/BizarHarness/docs/RELEASING.md` for the comprehensive guide; this skill is the action-oriented checklist.
-
-## Pre-flight (must all be true)
-
-```bash
-git status --short                                # empty
-git branch --show-current                         # master
-npm whoami                                        # drb0rk
-```
-
-## Test gate (all 4 runners must pass)
-
-```bash
-npx tsc --noEmit                                  # 0 errors
-npm test                                          # 388 node + 75 SDK + 295 bun + 7 smoke = 765 pass
-npm run build                                     # 0 errors
-```
-
-Counts above are post-v4.7.0 (commit `3005611`, tag `v4.7.0`).
-
-## Doc updates (in order)
-
-1. **`CHANGELOG.md`** — add `## vX.Y.Z — short title` at top, sections: Highlights / What's New / Tests / Upgrade.
-2. **`package.json`** — bump `"version"` field.
-3. **`.bizar/PROJECT.md`** — bump `Current Version` line.
-4. **`.bizar/AGENTS_SELF_IMPROVEMENT.md`** — append `### YYYY-MM-DD — vX.Y.Z` entry under `## Log`.
-
-## Release sequence
-
-```bash
-# Pre-flight + tests + build (see above)
-
-# Commit (hand off to Hermod for write-level git)
-git add -A
-git commit -m "vX.Y.Z: short title
-
-Highlights:
-- bullet 1
-- bullet 2
-- bullet 3
-
-Tests: <N> pass / 0 fail across <M> runners.
-tsc: clean. build: <main> KB + <mobile> KB."
-
-# Tag
-git tag -a vX.Y.Z -m "vX.Y.Z — short title"
-
-# Push
-git push origin master --follow-tags
-
-# Publish (prepublishOnly runs build automatically)
-npm publish
-
-# Verify
-npm view @polderlabs/bizar@X.Y.Z version
-git ls-remote --tags origin | grep vX.Y.Z
-```
-
-## Versioning
-
-| Bump | When |
-|---|---|
-| Patch | Bug fixes only |
-| Minor | New features, behavior-preserving changes |
-| Major | Breaking changes requiring user action |
-
-When in doubt, ask the user.
-
-## Hotfix
-
-```bash
-git checkout -b hotfix/vX.Y.Z+1 vX.Y.Z
-# make minimal fix
-npx tsc --noEmit && npm test && npm run build
-# bump version, update CHANGELOG with "Hotfix" entry
-git add -A && git commit -m "vX.Y.Z+1: hotfix — ..."
-git tag -a vX.Y.Z+1 -m "vX.Y.Z+1 — Hotfix: ..."
-git push origin hotfix/vX.Y.Z+1 --follow-tags
-git checkout master && git merge --no-ff hotfix/vX.Y.Z+1
-git push origin master
-npm publish
-```
-
-## Rollback
-
-`npm unpublish` is almost never right (breaks existing installs, 72h limit). Prefer:
-
-```bash
-npm deprecate @polderlabs/bizar@X.Y.Z "Critical bug; use X.Y.Z-1 instead"
-# then cut a new patch with the fix
-```
-
-## 10 pitfalls (avoid these)
-
-1. **Auth is NOT needed in v1 routes.** Tailscale handles it. Don't add auth during a release refactor.
-2. **`--help` global vs per-subcommand.** `bizar --help` ≠ `bizar <cmd> --help`. Test both.
-3. **Pre-existing merge conflict markers.** `grep -c '<<<<<<<\|>>>>>>>' <file>` before declaring a file clean. TS1185 will fail otherwise.
-4. **Source maps.** `vite.config.ts` must have `sourcemap: 'hidden'`. Don't ship 3 MB of maps.
-5. **Empty catch blocks.** Replace `catch { /* ignore */ }` with `catch (err) { logger.warn('swallowed in <ctx>:', err.message); }`.
-6. **Sibling collisions.** Define `Owns (read+write)` and `Siblings READ-ONLY` before dispatching parallel streams.
-7. **Test imports after refactor.** `grep -rn 'from.*<old-path>' <test-dirs>` to find stale imports.
-8. **`npm publish` requires version bump.** Re-publishing the same version is rejected.
-9. **`prepublishOnly` runs build.** Don't run build separately before publish — it runs anyway.
-10. **`npm view` propagation delay.** New version may 404 for ~5s after publish. Retry.
-
-## Agent routing
-
-| Agent | Release role |
-|---|---|
-| Odin | Decompose release into parallel prep streams |
-| Heimdall | Mechanical edits (bump `package.json`, append to AGENTS_SELF_IMPROVEMENT.md) |
-| Mimir | Research prior releases, summarize changes |
-| Thor | CHANGELOG drafting, test additions |
-| Tyr | Full release orchestration, breaking-change analysis |
-| **Hermod** | **The only agent that runs `git commit`, `git tag`, `git push`, `npm publish`** |
-| Forseti | Review the release plan (when called by Odin) |
-
-If a non-Hermod agent tries to push or publish, stop — route to Hermod via handoff.
-
-## Post-release verification
-
-```bash
-npm view @polderlabs/bizar version                          # X.Y.Z
-npm view @polderlabs/bizar@X.Y.Z dist.tarball                # registry URL
-git ls-remote --tags origin | grep vX.Y.Z                   # tag visible
-
-# Smoke test in a clean dir
-mkdir /tmp/bizar-smoke && cd /tmp/bizar-smoke
-npm install -g @polderlabs/bizar@X.Y.Z
-bizar --version                                             # X.Y.Z
-bizar doctor                                                # exit 0
-```
-
-## Reference
-
-- Comprehensive guide: `docs/RELEASING.md` (~600 lines, all details)
-- Most recent release: **v4.7.0** (commit `3005611`, tag `v4.7.0`, npm `@polderlabs/bizar@4.7.0`)
-- Diff stats: 62 files, +7,361 / −4,083 lines
-- Test counts: 388 node + 75 vitest + 295 bun + 7 smoke = **765 pass, 0 fail**
-- Build: 372 KB main + 476 KB mobile JS bundles

package/bizar-dash/skills/sdk/SKILL.md

@@ -1,138 +0,0 @@
----
-name: sdk
-description: @polderlabs/bizar-sdk usage - building AI agents on Cloudflare Workers using the Agents SDK. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks.
----
-
-# @polderlabs/bizar-sdk
-
-The Bizar SDK lets you build AI-powered agents on Cloudflare Workers using the Agents SDK. It runs on Cloudflare's global network with automatic scaling and durable state.
-
-## Installation
-
-```bash
-npm install @polderlabs/bizar-sdk
-```
-
-## Core Concepts
-
-### Agent Class
-
-```typescript
-import { Agent } from '@polderlabs/bizar-sdk';
-
-const agent = new Agent({
-  name: 'my-agent',
-  model: 'minimax/MiniMax-M3',
-  systemPrompt: 'You are a helpful assistant.',
-  env: { MINIMAX_API_KEY },
-});
-
-export default agent;
-```
-
-### State Management
-
-Agents maintain durable state across requests using Cloudflare Durable Objects:
-
-```typescript
-const state = await agent.state.get();
-// { count: 0, lastSeen: Date }
-await agent.state.patch({ count: state.count + 1 });
-```
-
-### Callable RPC
-
-Agents expose RPC methods callable via HTTP:
-
-```typescript
-agent.method('greet', async (name: string) => {
-  return `Hello, ${name}!`;
-});
-```
-
-Call from the dashboard or any HTTP client:
-```bash
-curl -X POST https://my-agent.workers.dev/rpc/greet \
-  -H "Content-Type: application/json" \
-  -d '{"name": "World"}'
-```
-
-## Workflows
-
-For long-running tasks, use Workflows (durable execution):
-
-```typescript
-import { Workflow } from '@polderlabs/bizar-sdk';
-
-const workflow = new Workflow({
-  name: 'data-processor',
-  retry: { maxAttempts: 3, backoff: 'exponential' },
-});
-
-workflow.step('fetch', async ({ input }) => {
-  return await fetch(input.url);
-});
-
-workflow.step('process', async ({ input, state }) => {
-  const data = await input.json();
-  return { ...data, processed: true };
-});
-
-export default workflow;
-```
-
-## Queues
-
-For async message processing:
-
-```typescript
-import { Queue } from '@polderlabs/bizar-sdk';
-
-const queue = new Queue('my-queue', {
-  maxRetries: 3,
-  batchSize: 10,
-});
-
-queue.processor(async (messages) => {
-  for (const msg of messages) {
-    console.log('Received:', msg.body);
-  }
-});
-```
-
-## Observability
-
-Built-in tracing to Cloudflare Analytics:
-- Request logs
-- Token usage
-- Error rates
-- Latency percentiles
-
-## React Hooks
-
-For building chat interfaces:
-
-```typescript
-import { useAgent, useSession } from '@polderlabs/bizar-sdk/react';
-
-function ChatComponent({ agentName }: { agentName: string }) {
-  const { messages, send, isLoading } = useAgent(agentName);
-
-  return (
-    <div>
-      {messages.map((m) => (
-        <div key={m.id}>{m.role}: {m.content}</div>
-      ))}
-      <input onSend={send} disabled={isLoading} />
-    </div>
-  );
-}
-```
-
-## Deployment
-
-```bash
-npx wrangler deploy
-```
-
-Workers are deployed to Cloudflare's global network. No cold starts, automatic HTTPS.

package/bizar-dash/skills/self-improvement/SKILL.md

@@ -1,53 +0,0 @@
----
-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 Protocol
-
-Records lessons learned after every meaningful task to `.bizar/AGENTS_SELF_IMPROVEMENT.md`. This enables agents to avoid repeating mistakes and build on past successes.
-
-## How It Works
-
-After completing a non-trivial task, the agent appends a structured entry to `.bizar/AGENTS_SELF_IMPROVEMENT.md` in the project root. Entries are written in Markdown with frontmatter for easy querying.
-
-## Entry Format
-
-```markdown
-## [YYYY-MM-DD] <one-line summary>
-
-**Task:** <what was asked>
-
-**Approach taken:** <key decisions and why>
-
-**What worked:** <specific things that went well>
-
-**What could be better:** <mistakes, friction points, missed opportunities>
-
-**Will do differently:** <concrete rule or habit for next time>
-
-**Tags:** #<tag1> #<tag2>
-```
-
-## When to Write an Entry
-
-Write an entry when:
-- A bug took more than 30 minutes to find or fix
-- A significant architectural decision was made
-- A known pattern or idiom was rediscovered
-- A previous mistake was identified and corrected
-- A task involved non-obvious tool usage or workflow
-
-## Reading Before New Tasks
-
-Before starting a non-trivial task in an unfamiliar area, agents should search the self-improvement file:
-```
-grep -A5 "tag:debugging" .bizar/AGENTS_SELF_IMPROVEMENT.md
-grep -A5 "tag:typescript" .bizar/AGENTS_SELF_IMPROVEMENT.md
-```
-
-This surfaces prior lessons that apply to the current work.
-
-## Skill File Location
-
-The skill instructions are at `~/.cline/skills/self-improvement/SKILL.md`. Load with the `skill` tool when setting up or debugging the system.

package/bizar-dash/skills/skills-cli/SKILL.md

@@ -1,94 +0,0 @@
----
-name: skills-cli
-description: How to discover and install skills using the skills CLI. Covers skills list, search, add, and the skills.sh ecosystem of skill repositories.
----
-
-# Skills CLI
-
-The `skills` CLI (`npm install -g skills`) is the standard way to discover and install skills in BizarHarness. Skills are Markdown files with YAML frontmatter that encode specialized knowledge and workflows for agents.
-
-## Installation
-
-```bash
-npm install -g skills
-```
-
-Verify: `skills --version`
-
-## Core Commands
-
-### skills list
-List all installed skills:
-```bash
-skills list --json
-```
-
-### skills search
-Search for skills by keyword:
-```bash
-skills search "react performance"
-```
-
-### skills add
-Install a skill from a GitHub repository:
-```bash
-skills add owner/repo --all -y          # install all skills from repo
-skills add owner/repo -s "skill-name" -y # install specific skill
-```
-
-### skills info
-Get details about a skill:
-```bash
-skills info my-skill
-```
-
-## Known Skill Repositories
-
-| Domain | Repository |
-|---|---|
-| General (find-skills, skill-creator) | `vercel-labs/skills` |
-| Frontend (React, a11y, web-design) | `vercel-labs/agent-skills`, `shadcn/ui` |
-| Backend (Supabase, Postgres, auth) | `supabase/agent-skills` |
-| Testing (TDD, Playwright) | `mattpocock/skills`, `microsoft/playwright-cli` |
-| Design (frontend-design, UI/UX) | `anthropics/skills`, `leonxlnx/taste-skill` |
-
-## Skill File Format
-
-Skills are `.md` files named `SKILL.md` inside a skill directory:
-
-```
-~/.cline/skills/my-skill/
-  SKILL.md   ← the skill content
-```
-
-The first line must be YAML frontmatter:
-```yaml
----
-name: my-skill
-description: Use when you need to do X. Covers Y and Z.
----
-```
-
-## Skill Discovery Protocol
-
-1. **Assess** - When given a task, consider whether a skill might exist for it
-2. **Check installed** - Run `skills list --json` to see what is already available
-3. **Try known repos** - Based on the task domain, attempt installation from known repos
-4. **Use** - Load the skill with the `skill` tool before writing code
-5. **Skip** - If no skill found, proceed without
-
-## SKILL.md Structure
-
-A good skill is 50–200 lines:
-
-1. **Frontmatter** - `name`, `description`
-2. **When to use** - trigger conditions and use cases
-3. **Key concepts** - essential background
-4. **Code examples** - realistic, copy-pasteable snippets
-5. **Common gotchas** - pitfalls and how to avoid them
-
-## Skill Loading in Bizar
-
-When an agent task is dispatched, Bizar checks if a skill matches the task description. If matched, the skill's `SKILL.md` content is injected into the agent's context before the task prompt.
-
-Use the `skill` tool explicitly when you want to load a skill's instructions into the current conversation.

package/bizar-dash/skills/usage/SKILL.md

@@ -1,62 +0,0 @@
----
-name: usage
-description: Usage monitoring and analytics in BizarHarness - token tracking, cost estimation, usage store, and the MiniMax usage dashboard.
----
-
-# Usage Monitoring
-
-BizarHarness tracks LLM token usage across all sessions and agents. Data is stored in `bizar-dash/src/server/minimax-usage-store.mjs` and surfaced in the dashboard.
-
-## What Is Tracked
-
-Per request:
-- **Input tokens** - prompt tokens sent to the model
-- **Output tokens** - tokens received from the model
-- **Model** - which model was used (MiniMax-M2.7, MiniMax-M3, etc.)
-- **Provider** - which provider handled the request
-- **Session ID** - which session this belongs to
-- **Agent** - which agent made the request (Thor, Tyr, etc.)
-- **Timestamp** - when the request completed
-
-## Cost Estimation
-
-Token counts are converted to cost using the model's published pricing:
-- MiniMax-M2.7: $0.30/M input · $1.20/M output
-- MiniMax-M3: $0.30/M input · $1.20/M output
-
-The usage dashboard shows:
-- Total cost (current billing period)
-- Cost breakdown by agent
-- Cost breakdown by day/week
-- Token count vs cost trend
-
-## Usage Store
-
-`bizar-dash/src/server/minimax-usage-store.mjs` uses a simple JSON file at `~/.config/bizar/usage.jsonl` (one JSON object per line - append-only log).
-
-The store aggregates on read:
-- Daily totals
-- Per-agent totals
-- Per-session totals
-
-## Usage API Endpoints
-
-- `GET /api/minimax/usage` - aggregated usage stats
-- `GET /api/minimax/usage/daily` - daily breakdown
-- `GET /api/minimax/usage/sessions` - per-session usage
-
-## Dashboard View
-
-`bizar-dash/src/web/views/MiniMaxUsage.tsx` renders:
-- Summary cards (total cost, total tokens, avg cost/session)
-- Line chart of daily cost
-- Bar chart of cost by agent
-- Table of recent sessions with usage
-
-## Retention
-
-Usage data is retained for 90 days by default. Old entries are pruned on each write to keep the log manageable.
-
-## Cost Alerts
-
-When a session's cumulative cost exceeds a threshold, the system logs a warning. The threshold is configurable via `MINIMAX_COST_ALERT_THRESHOLD` env var (default: $5 per session).