agent-economy 0.0.0-stage → 0.2.1

package/AGENTS.md

@@ -0,0 +1,36 @@
+# agent-economy
+
+This repo follows its own dogma — the request-economy block below is the product.
+
+<!-- agent-economy:start level=strict -->
+
+## Request economy (metering is per request — every model round-trip bills one)
+
+- Emit independent tool calls in PARALLEL within one round; never spread them one-per-round.
+- Combine closely-related shell commands into a single call (max ~5, `;`-joined); batch related file reads into one round.
+- Before running anything, check whether a result already in this session answers it; never re-run for information you already have.
+- When an answer is inferable, state the assumption and proceed — do not spend a round asking a clarifying question.
+- Do a task's follow-up work in the same turn; do not stop after each micro-step.
+- Filter expected-large output at the source (`rtk <cmd>`, `--oneline`, `| head -50`) so rounds stay cheap to fold.
+- Avoid subagents for small lookups — each runs its own multi-request loop; use direct tools instead.
+
+<!-- agent-economy:end -->
+
+## Project rules
+
+- Run `node src/cli.js verify` before committing — a release that fails its own check is not a release.
+- The CLI must stay dependency-free (Node stdlib only); packs are fetched on demand, never vendored.
+
+## Agent skills
+
+### Issue tracker
+
+GitHub Issues on `markymakes-dev/agent-economy` (via the `gh` CLI). See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default five-role vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `GLOSSARY.md` at the root + `docs/adr/` (created lazily by `/domain-modeling`). See `docs/agents/domain.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-economy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# agent-economy
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Request economy for coding agents.** Free and metered agent tiers bill **per request** — every model round-trip costs one, no matter how small. agent-economy installs a battle-tested rule set that makes agents batch, dedupe, and finish in fewer round-trips — as an idempotent, marker-bounded block in `AGENTS.md`, the open standard every major agent already reads (opencode, Codex, Cursor, Gemini CLI, Jules, Amp, Zed).
+
+```
+npm i -g agent-economy        # once per machine (or use npx agent-economy <cmd>)
+
+ae init                       # per project: interactive level + scope
+ae init --level strict --yes  # scripted onboarding
+ae verify --min-level strict  # CI gate: exit 1 missing, 2 below level
+ae doctor                     # detect rtk / billion-context / goal plugin
+ae packs                      # curated third-party rule/skill packs
+```
+
+### Install with your agent (no terminal needed)
+
+Paste this into opencode / Claude Code / Codex / Cursor — the agent does the rest:
+
+> Install agent-economy: run `npx -y agent-economy@latest init --level standard --yes`, then `npx -y agent-economy@latest skill`, then `npx -y agent-economy@latest doctor`, and report the results. Don't ask clarifying questions; project scope.
+
+After that, every future session discovers the `agent-economy-setup` skill and knows how to verify, re-configure, or extend the setup on its own.
+
+## Why requests, not tokens
+
+Token-compression tools (billion-context, RTK, headroom) are plentiful. **Request-economy tooling does not exist** — yet per-request metering is what actually caps free-tier sessions (measured baseline: ~7 model requests per user message in a real opencode session). Batching 3 independent calls into 1 round saves 2 requests *and* 2 round-trips of latency, every time. No plugin can force batching — call count is decided at generation time — so the prompt is the only injection point. This project owns that injection point.
+
+## Levels
+
+| Level | Rules |
+|---|---|
+| `standard` | parallel independent calls · batch related shell commands (max ~5) · never re-run for known info · filter large output at the source |
+| `strict` | standard **+** assume-and-proceed instead of clarifying questions · same-turn completion · no subagents for small lookups |
+| `off` | removes the block (clean uninstall) |
+
+## Mechanics
+
+- **Idempotent** — blocks are wrapped in `<!-- agent-economy:start level=… -->` … `<!-- agent-economy:end -->`; re-running updates in place, never duplicates
+- **Backup first** — `AGENTS.md.bak-<timestamp>` before any change
+- **Zero dependencies** — Node stdlib only; runs anywhere Node ≥ 18 runs
+- **Zero runtime cost** — the CLI runs once at setup; the artifact is the file. No plugin, no MCP, no per-session overhead
+
+## Enforce it in CI
+
+You can't police teammates' machines — you can police the repo:
+
+```yaml
+# .github/workflows/agents-md.yml
+- run: npx agent-economy verify --min-level strict
+```
+
+## Packs
+
+Curated, attributed, pinned fetch-on-demand integrations - never vendored:
+
+| Pack | Source | Kind |
+|---|---|---|
+| `karpathy-rules` | multica-ai/andrej-karpathy-skills | behavior rules |
+| `matt-skills` | mattpocock/skills | engineering skills |
+| `ecc-harness` | affaan-m/ECC | harness performance patterns |
+| `anthropic-skills` | anthropics/skills | official skills |
+
+```bash
+ae packs --install ecc-harness   # → ~/.claude/skills (override with --dir)
+```
+
+RTK and billion-context are **runtime tools**, not packs — `ae packs` prints their setup commands, `ae inventory` shows whether they're alive. `ae` never installs them for you.
+
+## Positioning
+
+Token compressors optimize **bytes**; this optimizes **round-trips**. Different unit, different layer, complementary stack. The dedicated AGENTS.md-template niche is empty (existing repos: 6–41★) while the adjacent skills ecosystem measures in six figures — the lane is open.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "agent-economy",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "files": [
+    "src",
+    "packs",
+    "skills",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "description": "Request economy for coding agents — treat every model round-trip as the billable unit. Idempotent AGENTS.md presets, tool detection, CI verify.",
+  "type": "module",
+  "bin": {
+    "ae": "src/cli.js",
+    "economy": "src/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "agents-md",
+    "opencode",
+    "codex",
+    "cursor",
+    "claude-code",
+    "request-economy",
+    "token-savings",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markymakes-dev/agent-economy.git"
+  }
+}

package/packs/registry.json

@@ -0,0 +1,75 @@
+{
+  "packs": [
+    {
+      "id": "karpathy-rules",
+      "source": "multica-ai/andrej-karpathy-skills",
+      "ref": "main",
+      "kind": "rules",
+      "status": "curated",
+      "install": [
+        { "from": "skills/karpathy-guidelines", "to": "karpathy-guidelines" }
+      ],
+      "note": "Behavior rules distilled from Karpathy's LLM coding-pitfall observations"
+    },
+    {
+      "id": "matt-skills",
+      "source": "mattpocock/skills",
+      "ref": "main",
+      "kind": "skills",
+      "status": "curated",
+      "install": [
+        { "from": "skills/engineering/tdd", "to": "tdd" },
+        { "from": "skills/engineering/code-review", "to": "code-review" },
+        { "from": "skills/engineering/diagnosing-bugs", "to": "diagnosing-bugs" },
+        { "from": "skills/engineering/codebase-design", "to": "codebase-design" },
+        { "from": "skills/engineering/pr", "to": "pr" },
+        { "from": "skills/productivity/writing-for-agents", "to": "writing-for-agents" }
+      ],
+      "note": "Curated subset of Matt Pocock's engineering skills (the full 66-skill collection is worth browsing; these are the evergreen ones)"
+    },
+    {
+      "id": "ecc-harness",
+      "source": "affaan-m/ECC",
+      "ref": "main",
+      "kind": "harness",
+      "status": "curated",
+      "install": [
+        { "from": ".agents/skills/strategic-compact", "to": "strategic-compact" },
+        { "from": ".agents/skills/verification-loop", "to": "verification-loop" },
+        { "from": ".agents/skills/change-impact", "to": "change-impact" },
+        { "from": ".agents/skills/coding-standards", "to": "coding-standards" },
+        { "from": ".agents/skills/security-review", "to": "security-review" }
+      ],
+      "note": "Request-economy-relevant subset of ECC's harness skills (strategic-compact alone earns the install); ECC-specific skills like ecc-conventions deliberately excluded"
+    },
+    {
+      "id": "anthropic-skills",
+      "source": "anthropics/skills",
+      "ref": "main",
+      "kind": "skills",
+      "status": "curated",
+      "install": [
+        { "from": "skills/skill-creator", "to": "skill-creator" },
+        { "from": "skills/mcp-builder", "to": "mcp-builder" },
+        { "from": "skills/webapp-testing", "to": "webapp-testing" }
+      ],
+      "note": "Official Anthropic skills, agent-tooling subset (document skills docx/pdf/pptx/xlsx live in the same repo if you want them manually)"
+    },
+    {
+      "id": "rtk",
+      "source": "rtk-ai/rtk",
+      "kind": "tool",
+      "status": "stack",
+      "setup": "winget install rtk-ai.rtk · then: rtk init -g --opencode --hook-only --no-patch",
+      "note": "Command rewriter — cuts agent tool output at the source (100+ per-command filters, fail-open)"
+    },
+    {
+      "id": "billion-context",
+      "source": "ranxianglei/billion-context",
+      "kind": "tool",
+      "status": "stack",
+      "setup": "npm i -g billion-context · then: bili plugin install opencode",
+      "note": "Context-compression proxy for agent sessions — folds stale context out of every request"
+    }
+  ]
+}

package/skills/agent-economy-setup/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: agent-economy-setup
+description: Install, verify, or configure agent-economy request-economy rules. Use when the user asks to install/set up agent-economy, wants the agent to save requests/quota/credits, mentions ae commands, or a CI check on agent-economy fails.
+license: MIT
+---
+
+# agent-economy setup
+
+Free and metered agent tiers bill **per request** — every model round-trip costs one. agent-economy manages a battle-tested rule set as an idempotent, marker-bounded block in `AGENTS.md`, so agents batch, dedupe, and finish in fewer round-trips.
+
+## Commands
+
+- `ae init [--level off|standard|strict] [--scope project|global|both] [--yes]` — install/update the rules block (interactive unless `--yes`)
+- `ae verify [file] [--min-level standard|strict]` — check the block; exit 0 ok, 1 missing, 2 below level (this is the CI gate)
+- `ae doctor` — detect companion tooling (rtk, billion-context, goal plugin)
+- `ae inventory` — list the token-economy stack (with live health) + all loaded plugins/skills/MCP
+- `ae packs` / `ae packs --install <id>` — curated third-party rule/skill packs (fetch-on-demand, attributed)
+- `ae skill` — (re)install this skill
+
+## Installing for a user
+
+1. Run `npx -y agent-economy@latest init --level standard --yes` (project scope). Use `--level strict` when the user wants maximum savings; `--scope global` writes `~/.config/opencode/AGENTS.md`.
+2. Run `npx -y agent-economy@latest skill` so future sessions can manage the setup themselves.
+3. Run `npx -y agent-economy@latest doctor` and report the results.
+4. Optional: `npx -y agent-economy@latest packs --install karpathy-rules` (behavior rules). NEVER install stack tools (`rtk`, `billion-context`) without asking — they change runtime behavior, not content.
+
+## Guardrails
+
+- The block between `<!-- agent-economy:start level=… -->` and `<!-- agent-economy:end -->` is MANAGED — never hand-edit it; change the level with `ae init --level <lvl>`.
+- `ae init` is idempotent and backs up to `AGENTS.md.bak-<timestamp>` first.
+- If a repo contains the block, run `ae verify --min-level strict` before committing.
+- Levels: `standard` = batch + dedupe + filter output at source; `strict` = + assume-and-proceed, same-turn completion, no subagents for small lookups.

package/src/cli.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+// agent-economy — request economy for coding agents.
+// Metering is per request: every model round-trip bills one. This CLI manages
+// the request-economy rules as an idempotent, marker-bounded AGENTS.md block.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execSync, spawnSync } from "node:child_process";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const MARKER_START = /<!-- agent-economy:start level=(\w+) -->/;
+const MARKER_END = "<!-- agent-economy:end -->";
+const RE_BLOCK = /<!-- agent-economy:start level=\w+ -->[\s\S]*?<!-- agent-economy:end -->/;
+const HEADER = "## Request economy (metering is per request — every model round-trip bills one)";
+
+const RULES = {
+  standard: [
+    "- Emit independent tool calls in PARALLEL within one round; never spread them one-per-round.",
+    "- Combine closely-related shell commands into a single call (max ~5, `;`-joined); batch related file reads into one round.",
+    "- Before running anything, check whether a result already in this session answers it; never re-run for information you already have.",
+    "- Filter expected-large output at the source (`rtk <cmd>`, `--oneline`, `| head -50`) so rounds stay cheap to fold."
+  ],
+  strict: [
+    "- Emit independent tool calls in PARALLEL within one round; never spread them one-per-round.",
+    "- Combine closely-related shell commands into a single call (max ~5, `;`-joined); batch related file reads into one round.",
+    "- Before running anything, check whether a result already in this session answers it; never re-run for information you already have.",
+    "- When an answer is inferable, state the assumption and proceed — do not spend a round asking a clarifying question.",
+    "- Do a task's follow-up work in the same turn; do not stop after each micro-step.",
+    "- Filter expected-large output at the source (`rtk <cmd>`, `--oneline`, `| head -50`) so rounds stay cheap to fold.",
+    "- Avoid subagents for small lookups — each runs its own multi-request loop; use direct tools instead."
+  ]
+};
+
+const RANK = { off: 0, standard: 1, strict: 2 };
+const startMarker = (lvl) => `<!-- agent-economy:start level=${lvl} -->`;
+const blockFor = (lvl) => [startMarker(lvl), "", HEADER, "", ...RULES[lvl], "", MARKER_END].join("\n");
+const globalFile = () => path.join(os.homedir(), ".config", "opencode", "AGENTS.md");
+
+function skill(dir) {
+  const src = path.join(ROOT, "skills", "agent-economy-setup");
+  const target = path.resolve(dir || path.join(os.homedir(), ".claude", "skills", "agent-economy-setup"));
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.cpSync(src, target, { recursive: true });
+  console.log(`  ✔ agent-economy-setup skill → ${target}`);
+  console.log("  = agents discover it automatically (opencode picks it up without restart)");
+}
+
+function upsert(file, level) {
+  const exists = fs.existsSync(file);
+  const prev = exists ? fs.readFileSync(file, "utf8") : "";
+  let next;
+  if (level === "off") {
+    if (!RE_BLOCK.test(prev)) { console.log(`  = no agent-economy block in ${file}`); return; }
+    next = prev.replace(RE_BLOCK, "").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  } else {
+    next = RE_BLOCK.test(prev)
+      ? prev.replace(RE_BLOCK, blockFor(level))
+      : (prev.trimEnd() ? prev.trimEnd() + "\n\n" + blockFor(level) + "\n" : blockFor(level) + "\n");
+  }
+  if (next === prev) { console.log(`  = unchanged ${file}`); return; }
+  if (exists) {
+    const bak = `${file}.bak-${Date.now()}`;
+    fs.copyFileSync(file, bak);
+    console.log(`  + backup  ${bak}`);
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, next);
+  console.log(`  ✔ wrote   ${file} (level=${level})`);
+}
+
+function verify(file, minLevel) {
+  if (!fs.existsSync(file)) return { code: 1, msg: `✘ ${file} not found` };
+  const m = fs.readFileSync(file, "utf8").match(MARKER_START);
+  if (!m) return { code: 1, msg: `✘ ${file} has no agent-economy block` };
+  const lvl = m[1];
+  if (RANK[lvl] === undefined) return { code: 2, msg: `✘ ${file} has unknown level "${lvl}"` };
+  if (RANK[lvl] < RANK[minLevel]) return { code: 2, msg: `✘ ${file} level=${lvl} is below required ${minLevel}` };
+  return { code: 0, msg: `✔ ${file} level=${lvl} (required ≥ ${minLevel})` };
+}
+
+const hasBin = (cmd) => {
+  try { execSync(`${process.platform === "win32" ? "where" : "which"} ${cmd}`, { stdio: "pipe" }); return true; }
+  catch { return false; }
+};
+
+function doctor() {
+  const opencodeDir = path.join(os.homedir(), ".config", "opencode");
+  const opencodeCfg = (() => { try { return fs.readFileSync(path.join(opencodeDir, "opencode.json"), "utf8"); } catch { return ""; } })();
+  const goalInstalled = /goal/i.test(opencodeCfg) || ["plugin", "plugins"].some((d) => {
+    try {
+      return fs.readdirSync(path.join(opencodeDir, d)).some((f) =>
+        /goal/i.test(f) || /goal/i.test(fs.readFileSync(path.join(opencodeDir, d, f), "utf8")));
+    } catch { return false; }
+  });
+  const rows = [
+    ["rtk (output filter)", hasBin("rtk"), "winget install rtk-ai.rtk"],
+    ["billion-context (context folds)", hasBin("bili") || fs.existsSync(path.join(os.homedir(), ".local", "bili.cmd")), "npm install -g billion-context --prefix=~/.local && bili plugin install opencode"],
+    ["opencode CLI", hasBin("opencode"), "opencode.ai"],
+    ["/goal (opencode command)", goalInstalled || hasBin("opencode"), "built into opencode 2.x — else install prevalentWare/opencode-goal-plugin"],
+    ["project AGENTS.md", fs.existsSync(path.resolve("AGENTS.md")), "economy init"],
+    ["global AGENTS.md", fs.existsSync(globalFile()), "economy init --scope global"]
+  ];
+  for (const [name, ok, hint] of rows) console.log(`  ${ok ? "✔" : "✘"} ${name}${ok ? "" : `  → ${hint}`}`);
+}
+
+function packs() {
+  const reg = JSON.parse(fs.readFileSync(path.join(ROOT, "packs", "registry.json"), "utf8"));
+  console.log("  Curated packs (fetch-on-demand; attribution + pinned refs):\n");
+  for (const p of reg.packs.filter((p) => p.status !== "stack"))
+    console.log(`  ${p.id.padEnd(18)} ${p.source.padEnd(38)} [${p.status}] ${p.note}`);
+  const tools = reg.packs.filter((p) => p.status === "stack");
+  if (tools.length) {
+    console.log("\n  Stack tools (runtime — detected by `ae inventory`; ae never installs these):\n");
+    for (const p of tools) console.log(`  ${p.id.padEnd(18)} ${p.source.padEnd(38)} setup: ${p.setup}`);
+  }
+}
+
+async function installPack(id, dir) {
+  const reg = JSON.parse(fs.readFileSync(path.join(ROOT, "packs", "registry.json"), "utf8"));
+  const p = reg.packs.find((x) => x.id === id);
+  if (!p) { console.error(`  ✘ unknown pack "${id}"`); process.exit(2); }
+  if (p.status === "stack") {
+    console.error(`  ✘ "${id}" is a runtime tool, not a fetchable pack — ae never installs those.`);
+    console.error(`    set it up directly: ${p.setup}`);
+    process.exit(2);
+  }
+  if (!Array.isArray(p.install) || !p.install.length) {
+    console.error(`  ✘ pack "${id}" has no curated install spec yet (status: ${p.status})`);
+    process.exit(2);
+  }
+  const target = path.resolve(dir || path.join(os.homedir(), ".claude", "skills"));
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), "ae-pack-"));
+  try {
+    const url = `https://codeload.github.com/${p.source}/tar.gz/refs/heads/${p.ref || "main"}`;
+    console.log(`  ↓ ${url}`);
+    const res = await fetch(url);
+    if (!res.ok) { console.error(`  ✘ download failed: HTTP ${res.status}`); process.exit(2); }
+    const tgz = path.join(work, "pack.tgz");
+    fs.writeFileSync(tgz, Buffer.from(await res.arrayBuffer()));
+    const root = path.join(work, "x");
+    fs.mkdirSync(root, { recursive: true });
+    const r = spawnSync("tar", ["-xzf", tgz, "-C", root]);
+    if (r.status !== 0) { console.error("  ✘ untar failed (is tar available?)"); process.exit(2); }
+    const base = path.join(root, fs.readdirSync(root)[0]);
+    fs.mkdirSync(target, { recursive: true });
+    for (const spec of p.install) {
+      const from = path.join(base, spec.from);
+      const to = path.join(target, spec.to);
+      if (!fs.existsSync(from)) { console.error(`  ✘ missing in pack: ${spec.from}`); process.exit(2); }
+      fs.cpSync(from, to, { recursive: true });
+      console.log(`  ✔ ${spec.from} → ${to}`);
+    }
+    const attr = path.join(target, `${p.id}.ATTRIBUTION.md`);
+    fs.writeFileSync(attr, `# ${p.id}\n\nSource: https://github.com/${p.source} (ref ${p.ref || "main"})\nInstalled by agent-economy on ${new Date().toISOString()}\nLicense: see the pack repository.\n`);
+    console.log(`  ✔ attribution → ${attr}`);
+    console.log(`  = done: ${p.id} installed to ${target}`);
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+function listDir(p, filter) {
+  try { return fs.readdirSync(p, { withFileTypes: true }).filter((d) => filter(d, p)).map((d) => d.name); }
+  catch { return []; }
+}
+
+const pkgName = (spec) => spec.replace(/@[^/@]+$/, "");
+
+function rtkStatus() {
+  const r = spawnSync("rtk", ["--version"], { encoding: "utf8", timeout: 5000 });
+  const v = (r.stdout || "").trim().split(/\r?\n/)[0] || "";
+  if (r.error && !v) return "rtk — not found   (install: winget install rtk-ai.rtk · then: rtk init -g --opencode --hook-only --no-patch)";
+  if (!v) return "rtk — installed (version unknown)";
+  return v.startsWith("rtk") ? v : `rtk ${v}`;
+}
+
+async function biliStatus() {
+  const dir = path.join(os.homedir(), ".local", "state", "billion-context", "instances");
+  const files = listDir(dir, (d) => d.isFile() && d.name.endsWith(".json"));
+  for (const f of files) {
+    try {
+      const inst = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      if (!inst.origin) continue;
+      const res = await fetch(`${inst.origin}/__bili/health`, { signal: AbortSignal.timeout(3000) });
+      const h = await res.json();
+      return h.ok
+        ? `billion-context v${h.version} — healthy (${inst.origin})`
+        : `billion-context — responding, not healthy (${inst.origin})`;
+    } catch { /* dead instance file, try next */ }
+  }
+  if (files.length) return "billion-context — proxy not responding (restart opencode to relaunch it)";
+  return "billion-context — not detected   (install: npm i -g billion-context · then: bili plugin install opencode)";
+}
+
+async function inventory() {
+  const home = os.homedir();
+  const oc = path.join(home, ".config", "opencode");
+  const rows = [];
+  let active = new Set();
+  try {
+    const j = JSON.parse(fs.readFileSync(path.join(oc, "opencode.json"), "utf8"));
+    for (const p of j.plugin || []) { rows.push(["opencode plugin (config)", p]); active.add(pkgName(p)); }
+    for (const m of Object.keys(j.mcp || {})) rows.push(["opencode mcp", m]);
+  } catch {}
+  for (const f of listDir(path.join(oc, "plugins"), (d) => d.isFile())) rows.push(["opencode plugin (file)", f]);
+  for (const f of listDir(path.join(oc, "command"), (d) => d.isFile())) rows.push(["opencode command", f]);
+  for (const dir of [
+    path.join(oc, "skill"), path.join(oc, "skills"),
+    path.resolve(".opencode", "skill"), path.resolve(".opencode", "skills"),
+    path.join(home, ".claude", "skills")
+  ]) for (const d of listDir(dir, (e) => e.isDirectory())) rows.push([`skills  ${dir.replace(home, "~")}`, d]);
+  for (const d of listDir(path.join(home, ".claude", "plugins"), (e) => e.isDirectory())) rows.push(["claude plugin", d]);
+  const cache = path.join(home, ".cache", "opencode", "npm");
+  for (const d of listDir(cache, (e) => e.isDirectory())) {
+    if (d.startsWith("@")) for (const c of listDir(path.join(cache, d), (e) => e.isDirectory())) rows.push(["opencode npm cache", `${d}/${c}`]);
+    else rows.push(["opencode npm cache", d]);
+  }
+  const seen = new Set();
+  console.log("  Token-economy stack:\n");
+  for (const line of await Promise.all([rtkStatus(), biliStatus()])) console.log(`    · ${line}`);
+  console.log("\n  Plugins / skills / MCP loaded across agents on this machine:\n");
+  let last = "";
+  let n = 0;
+  for (const [src, name] of rows) {
+    const k = `${src}|${name}`;
+    if (seen.has(k)) continue;
+    seen.add(k); n++;
+    if (src !== last) { console.log(`  ${src}`); last = src; }
+    const orphan = src === "opencode npm cache" && !active.has(pkgName(name));
+    console.log(`    · ${name}${orphan ? "   (not in config — orphaned)" : ""}`);
+  }
+  console.log(`\n  ${n} entries · health: ae doctor · curated extras: ae packs`);
+}
+
+const HELP = `
+  agent-economy — request economy for coding agents
+
+  Usage: ae <command> [options]      (alias: economy)
+
+  One-time install:  npm i -g agent-economy        (or: npx agent-economy <cmd>)
+
+  Commands:
+    init      Install/update the request-economy block
+              --level off|standard|strict   (default: interactive, standard)
+              --scope project|global|both   (default: interactive, project)
+              --yes                         non-interactive defaults
+    verify    Check a file carries the block; exit 1 missing, 2 below level
+              [file=AGENTS.md] --min-level standard|strict
+    doctor    Detect agent tooling (rtk, billion-context, goal plugin, ...)
+    inventory Show the token-economy stack (rtk, billion-context) with health,
+              then every plugin/skill/MCP actually loaded on this machine
+    packs     List curated third-party rule/skill packs
+              --install <id> [--dir <target>]   fetch + install a curated pack
+                                                (default target: ~/.claude/skills)
+    skill     Install the agent-economy-setup skill (teaches any agent to run ae)
+    help      This text
+
+  Every model round-trip bills one request. Batch the independent ones.
+`;
+
+async function ask(q, def) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const a = (await rl.question(`${q} [${def}]: `)).trim() || def;
+  rl.close();
+  return a;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0] || "help";
+  const get = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+  const hasFlag = (f) => args.includes(f);
+
+  if (cmd === "init") {
+    const yes = hasFlag("--yes");
+    let level = get("--level");
+    let scope = get("--scope");
+    if (!level) level = yes ? "standard" : await ask("Economy level off/standard/strict?", "standard");
+    if (!scope) scope = yes ? "project" : await ask("Scope project/global/both?", "project");
+    if (!(level in RANK)) { console.error(`✘ unknown level "${level}"`); process.exit(2); }
+    const targets = { project: [path.resolve("AGENTS.md")], global: [globalFile()], both: [path.resolve("AGENTS.md"), globalFile()] }[scope];
+    if (!targets) { console.error(`✘ unknown scope "${scope}"`); process.exit(2); }
+    for (const f of targets) upsert(f, level);
+    return;
+  }
+
+  if (cmd === "verify") {
+    const VALUE_FLAGS = ["--level", "--scope", "--min-level"];
+    const positional = [];
+    for (let i = 1; i < args.length; i++) {
+      if (VALUE_FLAGS.includes(args[i])) { i++; continue; }
+      if (!args[i].startsWith("--")) positional.push(args[i]);
+    }
+    const file = positional[0] || path.resolve("AGENTS.md");
+    const min = get("--min-level") || "standard";
+    if (!(min in RANK)) { console.error(`✘ unknown --min-level "${min}"`); process.exit(2); }
+    const r = verify(file, min);
+    console.log("  " + r.msg);
+    process.exit(r.code);
+  }
+
+  if (cmd === "doctor") return doctor();
+  if (cmd === "skill") return skill(get("--dir"));
+  if (cmd === "inventory") return inventory();
+  if (cmd === "packs") {
+    if (get("--install")) return installPack(get("--install"), get("--dir"));
+    return packs();
+  }
+  console.log(HELP);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });