@lythos/skill-arena 0.9.41 → 0.9.43

package/README.md

@@ -49,23 +49,20 @@ Note: Claude `-p` mode has known issues with web tools in Bun.spawn (deferred to
 ```bash
 bun add -d @lythos/skill-arena
 # or use directly
-bunx @lythos/skill-arena@0.9.41 <command>
+bunx @lythos/skill-arena@0.9.43 <command>
 ```
 
 ## Quick Start
 
 ```bash
-# Single: test a deck with one agent (exec shortcut)
-bunx @lythos/skill-arena@0.9.41 single \
-  --brief "Generate auth flow diagram" \
-  --deck ./examples/decks/documents.toml
-
-# Vs: compare multiple decks side by side (declarative)
-bunx @lythos/skill-arena@0.9.41 vs \
-  --config examples/arena/research-compare/arena.toml
-
-# Visualize results
-bunx @lythos/skill-arena@0.9.41 viz tmp/arena-<id>/
+# Single: test a deck with one agent
+bunx @lythos/skill-arena@0.9.43 single \
+  --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \
+  --brief "Generate auth flow diagram"
+
+# Vs: compare multiple decks side by side
+curl -fsSL https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/arena/research-compare/arena.toml > arena.toml
+bunx @lythos/skill-arena@0.9.43 vs --config ./arena.toml
 ```
 
 ## Commands
@@ -74,32 +71,23 @@ bunx @lythos/skill-arena@0.9.41 viz tmp/arena-<id>/
 
 ```bash
 # Print execution plan without running
-bunx @lythos/skill-arena@0.9.41 vs --config arena.toml --dry-run
+bunx @lythos/skill-arena@0.9.43 vs --config arena.toml --dry-run
 
 # Execute with per-side runs_per_side and statistical aggregation
-bunx @lythos/skill-arena@0.9.41 vs --config arena.toml
-```
-
-### CLI-flag mode (backward compat)
-
-```
-bunx @lythos/skill-arena@0.9.41 run \
-  --task ./TASK-arena.md \
-  --players ./players/claude.toml \
-  --decks ./decks/run-01.toml,./decks/run-02.toml \
-  --criteria coverage,relevance,actionability,depth
+bunx @lythos/skill-arena@0.9.43 vs --config arena.toml
 ```
 
 ### Scaffold mode (legacy, manual execution)
 
 ```
-bunx @lythos/skill-arena@0.9.41 scaffold --task "..." --decks a.toml,b.toml
+bunx @lythos/skill-arena@0.9.43 scaffold --task "Generate auth flow diagram" \
+  --decks https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml,https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/documents.toml
 ```
 
 ### Viz
 
 ```bash
-bunx @lythos/skill-arena@0.9.41 viz runs/arena-<id>/
+bunx @lythos/skill-arena@0.9.43 viz runs/arena-<id>/
 ```
 
 ## Skill Documentation
@@ -113,7 +101,7 @@ The agent-visible **Skill** layer documentation is here:
 Part of the [lythoskill](https://github.com/lythos-labs/lythoskill) ecosystem — the thin-skill pattern separates heavy logic (this npm package) from lightweight agent instructions (SKILL.md).
 
 ```
-Starter (this package) → npm publish → bunx @lythos/skill-arena@0.9.41 ...
+Starter (this package) → npm publish → bunx @lythos/skill-arena@0.9.43 ...
 Skill   (packages/<name>/skill/)     → build → SKILL.md + thin scripts
 Output  (skills/<name>/)             → git commit → agent-visible skill
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-arena",
-  "version": "0.9.41",
+  "version": "0.9.43",
   "description": "Skill Arena — benchmark skill effectiveness with controlled-variable comparison",
   "keywords": [
     "ai-agent",

package/src/cli.ts

@@ -63,16 +63,20 @@ Options:
       --timeout <ms>     Subagent timeout (single only)
 
 Examples:
-  # Single-player deck test (exec shortcut)
-  lythoskill-arena single --task ./TASK.agent.md --deck ./deck.toml
-  lythoskill-arena single --brief "Generate auth flow diagram" --deck ./deck.toml --player kimi
+  # Single-player deck test (--deck accepts local paths and http/https URLs)
+  lythoskill-arena single \\
+    --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
+    --brief "Generate auth flow diagram" --player kimi
 
   # Multi-side comparison (declarative)
+  curl -fsSL https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/arena/add-remove/arena.toml > arena.toml
   lythoskill-arena vs --config ./arena.toml
   lythoskill-arena vs --config ./arena.toml --dry-run
 
   # Legacy scaffolding
-  lythoskill-arena scaffold --task "Refactor auth module" --decks ./decks/a.toml,./decks/b.toml
+  # scaffold creates structure; decks via URL (auto-downloaded during link):
+  lythoskill-arena scaffold --task "Refactor auth module" \\
+    --decks https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml,https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/documents.toml
   lythoskill-arena viz runs/arena-20260504
 `)
 }
@@ -91,16 +95,19 @@ async function singleRun(args: string[]) {
   }
 
   if (!opts.deck) {
-    console.error(`❌ --deck <path> is required.
-   Usage: lythoskill-arena single --deck ./deck.toml --task ./scenario.agent.md
-          lythoskill-arena single --deck ./deck.toml --brief "your task description"
-   Example decks: examples/decks/scout.toml, examples/decks/documents.toml`)
+    console.error(`❌ --deck <path|url> is required.
+   --deck accepts local paths and http/https URLs (auto-fetched).
+   Example: lythoskill-arena single \\
+              --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
+              --brief "your task"`)
     process.exit(1)
   }
   if (!opts.task && (!opts.brief || !opts.brief.trim())) {
-    console.error(`❌ --task <path> or --brief "<prompt>" is required.
-   Usage: lythoskill-arena single --deck ./deck.toml --task ./scenario.agent.md
-          lythoskill-arena single --deck ./deck.toml --brief "your task description"`)
+    console.error(`❌ --task <path> or --brief "<text>" is required.
+   --task reads a .agent.md scenario file; --brief takes inline text.
+   Example: lythoskill-arena single \\
+              --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml \\
+              --brief "your task"`)
     process.exit(1)
   }
 
@@ -117,17 +124,26 @@ async function singleRun(args: string[]) {
     } catch { /* keep original url */ }
     const dest = resolve(process.cwd(), 'arena-deck.toml')
     console.log(`📥 Fetching arena deck: ${url}`)
-    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) })
-    if (!res.ok) { console.error(`❌ Failed to fetch deck (HTTP ${res.status}): ${url}`); process.exit(1) }
+    let res: Response
+    try { res = await fetch(url, { signal: AbortSignal.timeout(30_000) }) } catch (e: any) {
+      console.error(`❌ Cannot reach ${url}
+   Network issue? Try a GitHub proxy mirror:
+     ${url.replace('https://raw.githubusercontent.com/', 'https://ghfast.top/https://raw.githubusercontent.com/')}
+   Or download manually and reference the local file.`)
+      process.exit(1)
+    }
+    if (!res.ok) { console.error(`❌ Failed to fetch deck (HTTP ${res.status}): ${url}
+   Try a GitHub proxy mirror:
+     ${url.replace('https://raw.githubusercontent.com/', 'https://ghfast.top/https://raw.githubusercontent.com/')}`); process.exit(1) }
     deckWrite(dest, await res.text())
     console.log(`   → saved to ${dest}`)
     deckPath = dest
   } else {
     deckPath = resolve(opts.deck)
     if (!deckExists(deckPath)) { console.error(`❌ Deck file not found: ${deckPath}
-   Create one: examples/decks/scout.toml (minimal), examples/decks/documents.toml (documents)
-   Or fetch:   curl -fsSL https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml > deck.toml
-   Or create:  see https://github.com/lythos-labs/lythoskill/tree/main/examples/decks/`); process.exit(1) }
+   Make sure the path is correct, or use a URL:
+     --deck https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/decks/scout.toml
+   (URLs are auto-fetched — no local file needed)`); process.exit(1) }
   }
 
   const { useAgent } = await import('@lythos/test-utils/agents')
@@ -148,9 +164,9 @@ async function singleRun(args: string[]) {
   if (opts.task) {
     const taskPath = resolve(opts.task)
     if (!existsSync(taskPath)) { console.error(`❌ Task file not found: ${taskPath}
-   Create a .agent.md scenario or use --brief for inline tasks.
-   Format: frontmatter (name, description, timeout) + Given/When/Then/Judge sections.
-   Example: see playground/arena-one-shot/TASK-arena.agent.md`); process.exit(1) }
+   Use --brief for inline tasks, or point --task to an existing .agent.md file.
+   Format: name + description + Given/When/Then/Judge sections.
+   Example: lythoskill-arena single --brief "your task" --deck <url>`); process.exit(1) }
     scenarioOpt.scenarioPath = taskPath
     // Quick validation: check frontmatter presence
     const raw = readFileSync(taskPath, 'utf-8')
@@ -767,10 +783,9 @@ async function vsRun(argv: string[]) {
   console.error(`❌ --config <arena.toml> is required.
    Usage: lythoskill-arena vs --config ./arena.toml
           lythoskill-arena vs --config ./arena.toml --dry-run
-   Example configs:
-     examples/arena/research-compare/arena.toml   — two-side A/B
-     examples/arena/add-remove/arena.toml          — three-side Pareto
-   Create one: cp examples/arena/research-compare/arena.toml ./arena.toml`)
+   Fetch an example:
+     curl -fsSL https://raw.githubusercontent.com/lythos-labs/lythoskill/main/examples/arena/add-remove/arena.toml > arena.toml
+   Then edit arena.toml and run: lythoskill-arena vs --config ./arena.toml`)
   process.exit(1)
 
   const result = await runArenaProgrammatic({