@10et/cli 1.0.0

package/packages/pi/skills/viz/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: viz
+description: Terminal data visualization via kuva — inline plots for agents and humans
+---
+
+# /viz — Terminal Visualization
+
+Pipe JFL data to kuva for inline terminal plots. Agents see results without leaving flow.
+
+## Prerequisites
+
+```bash
+cargo install kuva --features cli
+```
+
+If kuva is not installed, falls back to ASCII bar/sparkline rendering.
+
+## Commands
+
+```
+/viz events      # Event bus activity (bar chart by type, sankey of service flows)
+/viz sessions    # Session activity (line chart over time, duration box plot)
+/viz costs       # API costs (bar by model, pie by provider)
+/viz tools       # Tool usage frequency (bar chart)
+/viz flows       # Flow trigger rates (bar chart, sankey of trigger→action)
+/viz arena       # Arena leaderboard (composite bar chart, score trajectory)
+/viz learning    # Pattern confidence trends (line chart)
+/viz health      # Service health dashboard (cost sparklines, error bars, latency box)
+/viz <custom>    # Describe what you want to visualize
+```
+
+## How It Works
+
+Each `/viz` command:
+1. Reads the relevant data source (events, journals, telemetry, arena results)
+2. Transforms to TSV format
+3. Pipes to `kuva [plot-type] --terminal`
+4. Renders inline in the terminal
+
+## Implementation
+
+### /viz events
+
+Read `.jfl/service-events.jsonl` and `.jfl/map-events.jsonl`:
+
+```bash
+# Event type distribution
+cat .jfl/service-events.jsonl | \
+  jq -r '.type' | sort | uniq -c | sort -rn | \
+  awk '{print $2"\t"$1}' | \
+  kuva bar --label-col 0 --value-col 1 --title "Events by Type" --terminal
+
+# Service-to-service flow (sankey)
+cat .jfl/service-events.jsonl | \
+  jq -r '[.source // "unknown", .type, 1] | @tsv' | \
+  kuva sankey --source-col 0 --target-col 1 --value-col 2 --title "Event Flows" --terminal
+```
+
+Or use the programmatic API from `jfl-cli/src/lib/kuva.ts`:
+
+```typescript
+import { barChart, linePlot, sparkline } from 'jfl-cli/src/lib/kuva.js'
+
+const events = loadEvents()
+const byType = countBy(events, 'type')
+const chart = barChart(
+  Object.entries(byType).map(([label, value]) => ({ label, value })),
+  'Events by Type'
+)
+console.log(chart)
+```
+
+### /viz sessions
+
+```bash
+# Sessions over time (line)
+cat .jfl/journal/*.jsonl | \
+  jq -r 'select(.type == "session-end") | [.ts[:10], 1] | @tsv' | \
+  sort | uniq -c | awk '{print $2"\t"$1}' | \
+  kuva line --x 0 --y 1 --title "Sessions per Day" --terminal
+```
+
+### /viz costs
+
+```bash
+# Cost by model (bar)
+cat .jfl/telemetry-queue.jsonl | \
+  jq -r 'select(.event == "stratus:api_call") | [(.model_name // "unknown"), .estimated_cost_usd] | @tsv' | \
+  kuva bar --label-col 0 --value-col 1 --title "Cost by Model" --terminal
+```
+
+### /viz arena
+
+```bash
+# Run from arena directory
+cd /path/to/productrank-arena
+npm run arena -- leaderboard --all --plots
+```
+
+Or programmatically — arena's `formatLeaderboardPlots()` renders composite scores as kuva bar chart.
+
+### /viz flows
+
+```bash
+# Flow triggers (bar)
+cat .jfl/service-events.jsonl | \
+  jq -r 'select(.type == "flow:triggered") | .data.flow_name' | \
+  sort | uniq -c | sort -rn | awk '{print $2"\t"$1}' | \
+  kuva bar --label-col 0 --value-col 1 --title "Flow Triggers" --terminal
+
+# Flow trigger→action sankey
+cat .jfl/service-events.jsonl | \
+  jq -r 'select(.type == "flow:completed") | [.data.flow_name, .data.action_type, 1] | @tsv' | \
+  kuva sankey --source-col 0 --target-col 1 --value-col 2 --title "Flow Actions" --terminal
+```
+
+### /viz health
+
+Composite dashboard — renders multiple charts:
+
+```
+  Health Dashboard
+  ━━━━━━━━━━━━━━━━
+
+  API Costs (last 24h)
+  [kuva bar: cost by model]
+
+  Error Rate ▁▂▁▁▃▅▂▁▁▁  (sparkline)
+
+  Latency Distribution
+  [kuva box: latency by endpoint]
+
+  Session Duration
+  [kuva box: duration by session]
+```
+
+### /viz learning (RL / Training)
+
+For agents with reinforcement learning loops:
+
+```typescript
+// After each training epoch
+const rewards = epochs.map((e, i) => ({ ts: `epoch-${i}`, value: e.reward }))
+const chart = linePlot(rewards, 'Reward per Epoch')
+console.log(chart)
+
+// Action distribution
+const actions = countBy(episodes, 'action')
+const actionChart = barChart(
+  Object.entries(actions).map(([label, value]) => ({ label, value })),
+  'Action Frequency'
+)
+console.log(actionChart)
+```
+
+### /viz custom
+
+When user describes what they want to visualize, the agent:
+1. Identifies the data source
+2. Extracts/transforms to TSV
+3. Picks the right kuva plot type
+4. Renders with `--terminal`
+
+## Available Plot Types
+
+| kuva command | Best for | Key flags |
+|-------------|----------|-----------|
+| `bar` | Categorical comparisons | `--label-col`, `--value-col` |
+| `line` | Time series, trends | `--x`, `--y`, `--color-by` |
+| `scatter` | Correlations, clustering | `--x`, `--y`, `--color-by` |
+| `box` | Distributions, outliers | `--group-col`, `--value-col` |
+| `histogram` | Value distributions | `--value-col`, `--bins` |
+| `pie` | Proportions | `--label-col`, `--value-col`, `--donut` |
+| `sankey` | Flow routing, transitions | `--source-col`, `--target-col`, `--value-col` |
+| `heatmap` | Matrix data, correlations | First col = row labels |
+| `violin` | Distribution shape | `--group-col`, `--value-col` |
+
+## Design Principles
+
+1. **TSV is the universal interface** — any data source that can produce rows can generate kuva plots
+2. **Graceful degradation** — ASCII fallback (bars, sparklines) when kuva isn't installed
+3. **Agent-native** — inline terminal output, no browser needed, no context-switching
+4. **Composable** — pipe any JSONL through `jq -r @tsv` into kuva. Unix philosophy.
+5. **Zero coupling** — kuva is a standalone Rust binary. kuva.ts is a standalone module. Neither needs the other's internals.
+
+## Examples
+
+```
+User: "show me event activity"
+Agent: *runs /viz events*
+→ Bar chart of event types + sankey of service flows
+
+User: "what's our cost breakdown?"
+Agent: *runs /viz costs*
+→ Bar chart by model + pie chart by provider
+
+User: "how is the arena looking?"
+Agent: *runs /viz arena*
+→ Leaderboard table + composite score bar chart
+
+User: "plot my training rewards"
+Agent: *runs /viz learning with user's data*
+→ Line chart of reward per epoch + action frequency bars
+```

package/packages/pi/skills/web-architect/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: web-architect
+description: Generate brand assets and audit web code against best practices - CSS, favicons, social images, exports, React/Next.js performance
+---
+
+# Web Architect Skill
+
+Implements the brand system by generating all required assets. Also audits web code against best practices.
+
+## Related Skills
+
+- **react-best-practices** - React/Next.js performance optimization. Use when building or auditing React sites.
+
+## Capabilities
+
+- Generate favicon package (all sizes)
+- Create social assets (OG images, banners, PFP)
+- Build CSS with brand tokens
+- Export SVGs to PNGs
+- Audit asset completeness
+- Update preview files with final assets
+
+## Input Requirements
+
+Requires `knowledge/BRAND_DECISIONS.md` with:
+- Selected mark
+- Color palette
+- Typography choices
+
+## Commands
+
+```
+/web-architect                    # Show status
+/web-architect audit              # Check what's missing
+/web-architect implement all      # Generate everything
+/web-architect implement css      # Generate CSS only
+/web-architect implement favicons # Generate favicon package
+/web-architect implement social   # Generate social assets
+/web-architect implement marks    # Generate mark size variants
+/web-architect export png         # Export all SVGs to PNG
+```
+
+## Workflow
+
+### Audit
+
+```
+/web-architect audit
+
+Checking brand assets...
+
+MARKS:
+├─ [✓] Primary mark selected
+├─ [✓] Transparent version
+├─ [ ] Size variants (80, 160, 400)
+└─ [ ] Dark/light variants
+
+FAVICONS:
+├─ [ ] 16px
+├─ [ ] 32px
+├─ [ ] 48px
+├─ [ ] 96px
+├─ [ ] 180px (Apple Touch)
+├─ [ ] 192px (Android)
+└─ [ ] 512px (PWA)
+
+SOCIAL:
+├─ [ ] Twitter banner (1500x500)
+├─ [ ] OG image (1200x630)
+├─ [ ] Twitter PFP (400x400)
+└─ [ ] Banner size variants
+
+CSS:
+├─ [ ] Color tokens
+├─ [ ] Typography tokens
+└─ [ ] global.css generated
+
+Missing: 18 assets
+Run /web-architect implement all to generate.
+```
+
+### Implement All
+
+```
+/web-architect implement all
+
+Generating brand assets...
+
+MARKS:
+├─ [✓] mark-v3-80-dark.svg
+├─ [✓] mark-v3-80-light.svg
+├─ [✓] mark-v3-160-dark.svg
+├─ [✓] mark-v3-400-dark.svg
+└─ Saved to outputs/svg/mark/
+
+FAVICONS:
+├─ [✓] favicon-16-dark.svg
+├─ [✓] favicon-32-dark.svg
+├─ [✓] favicon-48-dark.svg
+├─ [✓] favicon-96-dark.svg
+├─ [✓] favicon-180-dark.svg
+├─ [✓] favicon-192-dark.svg
+├─ [✓] favicon-512-dark.svg
+└─ Saved to outputs/svg/favicon/
+
+SOCIAL:
+├─ [✓] twitter-banner-sm-1500x500-dark.svg
+├─ [✓] twitter-banner-md-1500x500-dark.svg
+├─ [✓] twitter-banner-lg-1500x500-dark.svg
+├─ [✓] twitter-banner-xl-1500x500-dark.svg
+├─ [✓] og-default-1200x630-dark.svg
+├─ [✓] pfp-400-dark.svg
+└─ Saved to outputs/svg/social/
+
+CSS:
+├─ [✓] outputs/css/global.css
+└─ Tokens from BRAND_DECISIONS.md
+
+PNG EXPORT:
+├─ [✓] All SVGs exported to PNG
+└─ Saved to outputs/png/
+
+Complete! 24 assets generated.
+```
+
+## Asset Generation
+
+### Favicons
+
+Generate all standard favicon sizes:
+
+```bash
+# Sizes needed
+16   - Browser tab
+32   - Browser tab @2x
+48   - Windows
+96   - Android Chrome
+180  - Apple Touch Icon
+192  - Android Chrome @2x
+512  - PWA splash
+```
+
+SVG structure:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {size} {size}">
+  <rect width="100%" height="100%" fill="{bg-color}"/>
+  <!-- Mark scaled to fit with padding -->
+</svg>
+```
+
+### Social Assets
+
+#### Twitter Banner (1500x500)
+- Box with mark inside
+- Left-aligned with padding
+- Size variants: sm, md, lg, xl
+
+#### OG Image (1200x630)
+- Mark centered in box
+- Optional: tagline variant
+
+#### PFP (400x400)
+- Square crop
+- Mark centered
+- High contrast
+
+### CSS Generation
+
+Read from BRAND_DECISIONS.md and generate:
+
+```css
+:root {
+  /* Colors from decisions */
+  --brand-bg: {bg};
+  --brand-fg: {fg};
+  --brand-accent: {accent};
+
+  /* Typography from decisions */
+  --brand-font: {font-stack};
+  --brand-font-weight: {weight};
+}
+```
+
+### PNG Export
+
+Use rsvg-convert for all SVG → PNG conversions:
+
+```bash
+# Single file
+rsvg-convert -w {width} -h {height} input.svg -o output.png
+
+# Batch export script
+./scripts/export-pngs.sh
+```
+
+## File Structure
+
+```
+outputs/
+├── svg/
+│   ├── mark/
+│   │   ├── mark-v3-transparent.svg
+│   │   ├── mark-v3-80-dark.svg
+│   │   ├── mark-v3-80-light.svg
+│   │   ├── mark-v3-160-dark.svg
+│   │   ├── mark-v3-400-dark.svg
+│   │   └── ...
+│   ├── social/
+│   │   ├── twitter-banner-sm-1500x500-dark.svg
+│   │   ├── twitter-banner-md-1500x500-dark.svg
+│   │   ├── twitter-banner-lg-1500x500-dark.svg
+│   │   ├── twitter-banner-xl-1500x500-dark.svg
+│   │   ├── og-default-1200x630-dark.svg
+│   │   ├── pfp-400-dark.svg
+│   │   └── (light variants)
+│   └── favicon/
+│       ├── favicon-16-dark.svg
+│       ├── favicon-32-dark.svg
+│       └── ...
+├── png/
+│   ├── mark/
+│   ├── social/
+│   └── favicon/
+└── css/
+    └── global.css
+```
+
+## Naming Conventions
+
+```
+{type}-{variant}-{size}-{theme}.{ext}
+
+Examples:
+mark-v3-80-dark.svg
+twitter-banner-xl-1500x500-dark.svg
+og-tagline-1200x630-dark.svg
+favicon-32-dark.png
+```
+
+## Error Handling
+
+### No Decisions Found
+```
+No brand decisions found.
+
+Run /brand-architect first to:
+1. Generate mark options
+2. Select colors and typography
+3. Record decisions
+
+Then run /web-architect implement all.
+```
+
+### Missing Dependencies
+```
+rsvg-convert not found.
+
+PNG export requires librsvg. Install with:
+  brew install librsvg   # macOS
+  apt install librsvg2-bin  # Ubuntu
+```
+
+### Incomplete Decisions
+```
+Brand decisions incomplete.
+
+Missing:
+- Primary mark selection
+- Color palette
+
+Update knowledge/BRAND_DECISIONS.md or run /brand-architect decide.
+```
+
+---
+
+## Code Auditing
+
+### React/Next.js Projects
+
+For React or Next.js sites, use the **react-best-practices** skill:
+
+```
+/web-architect audit react
+```
+
+This runs the Vercel React Best Practices audit covering:
+- Eliminating waterfalls (CRITICAL)
+- Bundle size optimization (CRITICAL)
+- Server-side performance (HIGH)
+- Client-side data fetching (MEDIUM-HIGH)
+- Re-render optimization (MEDIUM)
+- Rendering performance (MEDIUM)
+- JavaScript performance (LOW-MEDIUM)
+
+See `skills/react-best-practices/SKILL.md` for full rule reference.
+
+### Static Sites
+
+For static HTML sites:
+```
+/web-architect audit static
+```
+
+Checks:
+- Asset optimization (images, SVGs)
+- CSS best practices
+- Accessibility basics
+- Performance hints