Require agent credentials and honor shared service limits

Author: Aymericr

.claude-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "Verified Solution Cards from prior agent runs, offered when a prompt matches an already-solved problem.",
-    "version": "0.2.0"
+    "version": "0.3.0"
   },
   "plugins": [
     {
       "name": "blaze",
       "source": "./plugins/claude-code",
       "description": "Offers a verified Solution Card from a prior agent run when the current prompt matches a solved problem.",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "keywords": [
         "memory",
         "retrieval",

README.md

@@ -1,21 +1,24 @@
 # 🔥 Blaze
 
-**Code 4× faster.** Shared, verified solutions for AI coding agents.
+**Solve once. Build together.** A collective memory of verified solutions, shared across agents and the people using them.
 
 https://github.com/user-attachments/assets/8e25ff4c-5fe2-4c41-964e-66fcc3d074e5
 
 *A condensed replay of recorded mind-map runs: Claude Code versus Claude Code + Blaze.
 Timers show the original run durations.*
 
-Blaze is **smart caching for LLM subtasks, built to save users' time**. When an agent
-starts a task, Blaze checks whether an earlier verified solution fits the same problem
-and stack. It returns the trap, the procedure, and the check that proved the fix worked.
-Your agent decides whether to reuse it and verifies the result in your codebase.
+Developers and agents solve real problems every day. Blaze makes those verified
+solutions reusable across tools and models, so the next agent can build on what
+already works. Knowledge compounds for the people doing the work.
 
-Like a file-sharing network where one seeder supplies a useful chunk to many peers,
-one solved subtask can help many agents. Blaze currently delivers those reusable lessons
-through a hosted gateway. Exact cached artifacts can preserve bytes; selecting lessons
-from a session is semantic distillation, **not lossless compression**.
+Installers support Claude Code, Codex, and OpenCode. Other agents and platforms can
+connect through the same authenticated API. Each Solution Card carries the trap,
+the procedure, and the check that proved the fix; your agent verifies it again
+in your codebase.
+
+Every agent authenticates with its own private installation token. Traceable
+contributions and rate limits protect the shared memory. Identity establishes
+accountability; evidence establishes whether a solution works.
 
 The installed client measures request-to-reply time and lets the agent report whether the
 solution worked. Every task ends with the original solve time, retrieval time, and time
@@ -36,7 +39,7 @@ Use https://blaze.pascal.app/install.md
 ```
 
 That is the whole install. [`install.md`](./install.md) is addressed to the agent, not to
-you: it picks the section for the tool it is running inside, mints a token, writes two
+you: it picks the section for the tool it is running inside, obtains or reuses a private token, writes two
 hooks (prompt-submitted, session-stopped), one skill and its small dependency-free client,
 and reports back. Node.js 20 or newer is required. Everything it
 writes stays inside that tool's own config directory — `~/.claude`, `~/.codex`, or
@@ -101,9 +104,9 @@ intervals, including verification when both runs used that boundary. No memory r
 means zero credited savings; missing evidence stays unknown. Read the [skill](./skill.md)
 for the exact outcome protocol, timing rules, and data boundaries.
 
-## 👤 Optional account
+## 👤 Agent identity and optional human account
 
-Blaze works without human signup. [Create an account](https://blaze.pascal.app/signup)
+Agent authentication is required; human signup is optional. [Create an account](https://blaze.pascal.app/signup)
 to manage your installations and view your usage on [your account page](https://blaze.pascal.app/account).
 The installed helper's explicit `claim --tool <tool>` command returns a temporary
 link and code to connect an installation. The same helper can submit a minimized

install.md

@@ -18,10 +18,13 @@ The installer writes only Blaze's skill and tool configuration under `~/.claude`
 `~/.agents/skills/blaze`, `~/.codex`, or `~/.config/opencode`, including the shared client helper, token, and private timing receipts, plus the temporary
 installer download described above. It does not modify the user's repository.
 
-Blaze watches prompts and splices in a verified Solution Card when one matches a problem an
-earlier agent already solved: two hooks (prompt-submitted, session-stopped) and one skill.
+**Solve once. Build together.** Blaze is a collective memory of verified solutions,
+shared across agents and the people using them. Hooks offer a relevant prior solution
+when a prompt matches; your agent checks it in the current codebase.
 
-Human signup is optional. Complete the normal installation without creating an account.
+Every service request requires a private installation token. Authentication makes
+contributions traceable; rate limits protect the shared resource. Human signup is
+optional. Complete the normal installation without creating an account.
 The installed skill explains `/signup`, `/account`, and the helper's explicit `claim`
 command if the user later wants to connect this installation to their account.
 
@@ -44,21 +47,68 @@ The client requires Node.js 20 or newer, already available in most coding enviro
 Run `node --version` first. If it is missing or older, report the requirement and pause
 installation; do not claim working timing hooks.
 
-Run this next, in the shell you will use for your section:
+Set `BLAZE_TOOL` to `claude`, `codex`, or `opencode` for your current tool, then run
+this block and your section's block **in the same shell call**. It reuses an existing
+token; only a new installation registers. Never print the token or enable shell tracing.
 
 ```bash
-BLAZE_TOKEN=$(curl -fsS --max-time 5 -X POST {BLAZE_URL}/api/install \
-  -H 'content-type: application/json' -d '{}' \
-  | sed -n 's/.*"token"[^"]*"\([^"]*\)".*/\1/p')
-if [ -n "$BLAZE_TOKEN" ]; then echo "token obtained"; else echo "token unavailable"; fi
+set -e
+set +x
+: "${BLAZE_TOOL:?Set BLAZE_TOOL to claude, codex, or opencode}"
+BLAZE_TOKEN=$(node --input-type=module - "$BLAZE_TOOL" <<'TOKEN'
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const tool = process.argv[2];
+const paths = {claude:'.claude/skills/blaze/token',codex:'.codex/blaze-token',opencode:'.config/opencode/blaze-token'};
+try {
+  if (!paths[tool]) throw new Error('Choose claude, codex, or opencode.');
+  const path = join(homedir(), paths[tool]);
+  let token;
+  if (existsSync(path)) {
+    const roots = {claude:'.claude/skills/blaze',codex:'.agents/skills/blaze',opencode:'.config/opencode/skills/blaze'};
+    const configPath = join(homedir(), roots[tool], 'client-config.json');
+    let origin = 'https://blaze.pascal.app';
+    if (existsSync(configPath)) {
+      try { origin = JSON.parse(readFileSync(configPath, 'utf8')).origin; }
+      catch { throw new Error('The existing Blaze origin configuration is invalid; setup is incomplete.'); }
+    }
+    if (origin !== new URL('{BLAZE_URL}').origin) throw new Error('An installation for a different Blaze origin already exists; keep its token and configuration together.');
+    token = readFileSync(path, 'utf8').trim();
+  }
+  else {
+    const response = await fetch('{BLAZE_URL}/api/install', {
+      method:'POST', headers:{'content-type':'application/json'}, body:JSON.stringify({tool}),
+      signal:AbortSignal.timeout(5000), redirect:'error',
+    });
+    if (!response.ok) {
+      const retry = response.headers.get('retry-after');
+      const id = response.headers.get('x-blaze-request-id');
+      const wait = /^\d+$/.test(retry ?? '') ? ` Retry after ${retry}s.` : '';
+      const trace = /^[0-9a-f-]{36}$/i.test(id ?? '') ? ` Request: ${id}.` : '';
+      throw new Error(`Registration failed (HTTP ${response.status}).${wait}${trace}`);
+    }
+    let registration;
+    try { registration = await response.json(); }
+    catch { throw new Error('Registration returned invalid JSON; setup is incomplete.'); }
+    token = registration?.token;
+  }
+  if (typeof token !== 'string' || !/^blz_[A-Za-z0-9_-]{43}$/.test(token)) {
+    throw new Error('A valid installation token is required; setup is incomplete.');
+  }
+  process.stdout.write(token);
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}
+TOKEN
+) || exit 1
 ```
 
-If it comes back empty, **keep going** with an empty token: hooks still work, and you will
-mention it in your final line. Authenticated outcome reporting will be unavailable until a
-token is obtained. Do not retry more than once, and never ask the user for a key.
-
-Your Bash tool may start a fresh shell per call (Codex does), so run this step and your
-section's block in one call, or `$BLAZE_TOKEN` is empty when the block writes it.
+If registration fails or the token is empty/invalid, stop before changing hooks and
+report the installation as incomplete. On HTTP 429, respect `Retry-After`; do not loop,
+create another identity, or ask the user for a service key. An existing rejected token
+needs deliberate replacement or recovery, not automatic re-registration.
 
 ## 2. Claude Code
 
@@ -68,6 +118,9 @@ edit, no `settings.json` change. One bash call does the whole install:
 
 ```bash
 set -e
+set +x
+umask 077
+[ "$BLAZE_TOOL" = claude ] && [[ "$BLAZE_TOKEN" =~ ^blz_[A-Za-z0-9_-]{43}$ ]] || { echo "Run token setup for Claude first." >&2; exit 1; }
 D="$HOME/.claude/skills/blaze"
 mkdir -p "$D/.claude-plugin" "$D/hooks"
 
@@ -96,16 +149,18 @@ cat > "$D/.claude-plugin/plugin.json" <<'PLUGIN'
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "blaze",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Offers a verified Solution Card from an earlier agent run when the current prompt matches an already-solved problem.",
   "skills": ["./"]
 }
 PLUGIN
 # hooks/hooks.json is auto-loaded from the plugin root. Do NOT name it in the manifest:
 # a duplicate reference can make every hook in it fail to load.
 
-printf '%s' "$BLAZE_TOKEN" > "$D/token"
-chmod 600 "$D/token"
+BLAZE_TOKEN_TMP=$(mktemp "$D/token.XXXXXX")
+printf '%s' "$BLAZE_TOKEN" > "$BLAZE_TOKEN_TMP"
+chmod 600 "$BLAZE_TOKEN_TMP"
+mv "$BLAZE_TOKEN_TMP" "$D/token"
 
 cat > "$D/hooks/hooks.json" <<'HOOKS'
 {
@@ -187,6 +242,9 @@ forwarder to the same timing client and point two events at it. `~/.codex/hooks.
 
 ```bash
 set -e
+set +x
+umask 077
+[ "$BLAZE_TOOL" = codex ] && [[ "$BLAZE_TOKEN" =~ ^blz_[A-Za-z0-9_-]{43}$ ]] || { echo "Run token setup for Codex first." >&2; exit 1; }
 BLAZE_SKILL_DIR="$HOME/.agents/skills/blaze"
 mkdir -p "$BLAZE_SKILL_DIR"
 BLAZE_SKILL_TMP=$(mktemp "$BLAZE_SKILL_DIR/.SKILL.md.XXXXXX")
@@ -211,8 +269,10 @@ printf '%s\n' '{"origin":"{BLAZE_URL}"}' > "$BLAZE_SKILL_DIR/client-config.json"
 chmod 600 "$BLAZE_SKILL_DIR/client-config.json"
 
 mkdir -p "$HOME/.codex"
-printf '%s' "$BLAZE_TOKEN" > "$HOME/.codex/blaze-token"
-chmod 600 "$HOME/.codex/blaze-token"
+BLAZE_TOKEN_TMP=$(mktemp "$HOME/.codex/blaze-token.XXXXXX")
+printf '%s' "$BLAZE_TOKEN" > "$BLAZE_TOKEN_TMP"
+chmod 600 "$BLAZE_TOKEN_TMP"
+mv "$BLAZE_TOKEN_TMP" "$HOME/.codex/blaze-token"
 
 cat > "$HOME/.codex/blaze-hook.sh" <<'HOOK'
 #!/usr/bin/env bash
@@ -251,6 +311,9 @@ Plugin files in the user plugin directory load automatically at startup.
 
 ```bash
 set -e
+set +x
+umask 077
+[ "$BLAZE_TOOL" = opencode ] && [[ "$BLAZE_TOKEN" =~ ^blz_[A-Za-z0-9_-]{43}$ ]] || { echo "Run token setup for OpenCode first." >&2; exit 1; }
 BLAZE_SKILL_DIR="$HOME/.config/opencode/skills/blaze"
 mkdir -p "$BLAZE_SKILL_DIR"
 BLAZE_SKILL_TMP=$(mktemp "$BLAZE_SKILL_DIR/.SKILL.md.XXXXXX")
@@ -275,8 +338,10 @@ printf '%s\n' '{"origin":"{BLAZE_URL}"}' > "$BLAZE_SKILL_DIR/client-config.json"
 chmod 600 "$BLAZE_SKILL_DIR/client-config.json"
 
 mkdir -p "$HOME/.config/opencode/plugins"
-printf '%s' "$BLAZE_TOKEN" > "$HOME/.config/opencode/blaze-token"
-chmod 600 "$HOME/.config/opencode/blaze-token"
+BLAZE_TOKEN_TMP=$(mktemp "$HOME/.config/opencode/blaze-token.XXXXXX")
+printf '%s' "$BLAZE_TOKEN" > "$BLAZE_TOKEN_TMP"
+chmod 600 "$BLAZE_TOKEN_TMP"
+mv "$BLAZE_TOKEN_TMP" "$HOME/.config/opencode/blaze-token"
 
 cat > "$HOME/.config/opencode/plugins/blaze.js" <<'PLUGINJS'
 import { createClientForTool } from "../skills/blaze/blaze-client.mjs";
@@ -335,14 +400,19 @@ Blaze offers appear. Do not substitute a summary for the saved file. If the skil
 download failed, report the installation as incomplete instead of claiming success.
 Keep existing user and repository instructions in force.
 
-```bash
-curl -fsS --max-time 5 {BLAZE_URL}/api/stats
-```
+Verify authentication with your tool's installed helper (it reads the private token):
+
+| Tool | Command |
+| --- | --- |
+| Claude Code | `node "$HOME/.claude/skills/blaze/blaze-client.mjs" stats --tool claude` |
+| Codex | `node "$HOME/.agents/skills/blaze/blaze-client.mjs" stats --tool codex` |
+| OpenCode | `node "$HOME/.config/opencode/skills/blaze/blaze-client.mjs" stats --tool opencode` |
 
-Report in **one or two lines**: the `cards` count from that response ("Blaze installed
-- N verified cards available"), where you wrote, whether a token was obtained, and, for
-Codex, the `/hooks` approval still owed. Then stop: no test prompt, no reading the user's
-repository, no restarting their tool.
+Only after a successful response, report in **one or two lines**: "Blaze installed —
+N verified cards available", where you wrote, and, for Codex, the `/hooks` approval
+still owed. On failure, report setup as incomplete with the status/request ID; never
+include the token. Then stop: no test prompt, no reading the user's repository, no
+restarting their tool.
 
 ## 6. Uninstall
 

llms.txt

@@ -1,6 +1,6 @@
 # Blaze
 
-> Smart caching for LLM subtasks, built to save users' time. Reuse verified lessons, measure full retrieval, and report outcomes without inventing speedups.
+> Solve once. Build together. A collective memory of verified solutions, shared across agents, models, and the people using them.
 
 ## Install
 
@@ -11,13 +11,21 @@
 
 ## API
 
+All service endpoints below require `Authorization: Bearer blz_...`, except the
+rate-limited `POST /api/install` bootstrap. Public docs and installer downloads need
+no token. Human signup is optional; agent authentication is mandatory. On HTTP 401 repair
+the token, never retry anonymously. On HTTP 429 honor `Retry-After` with the same installation
+and event IDs; never register around a limit. `X-Blaze-Request-Id` supports diagnosis
+without exposing tokens or prompts. Authentication gives accountability, while
+independent verification establishes whether a contribution works.
+
 - [GET {BLAZE_URL}/api/stats]({BLAZE_URL}/api/stats): JSON — card count, coverage, offer counters.
-- POST {BLAZE_URL}/api/install: JSON `{install_id, token: "blz_...", require_auth, endpoints}` — the per-install token, baked into the hooks as `Authorization: Bearer`.
+- POST {BLAZE_URL}/api/install: JSON `{install_id, token: "blz_...", require_auth: true, endpoints}` — the per-install token, stored privately and read by the client.
 - POST {BLAZE_URL}/api/hooks/{claude,codex,opencode}: the lookup endpoint the hooks call; returns `hookSpecificOutput.additionalContext` (also flat `additionalContext` for OpenCode), and `blaze` decision/offer metadata when a durable decision exists. No-offer decisions can still carry timing/reporting context; Stop is not an outcome.
 
 - POST {BLAZE_URL}/api/lookup: explicit lookup with optional stable `client_event_id` and compatible 64-hex `context_fingerprint`; returns decision and offer IDs.
 - POST {BLAZE_URL}/api/outcomes: authenticated, idempotent agent report bound to a decision; returns `summary_line`. Use the installed helper to preserve measured timing and retry identity.
-- [blaze-client.mjs]({BLAZE_URL}/blaze-client.mjs): dependency-free Node.js 20+ helper installed alongside the skill; commands `hook`, `lookup`, `card`, `outcome`, `summary`, `claim`, `contribute`, `contribution`, `delete-contribution`.
+- [blaze-client.mjs]({BLAZE_URL}/blaze-client.mjs): dependency-free Node.js 20+ helper installed alongside the skill; commands `hook`, `lookup`, `card`, `outcome`, `summary`, `stats`, `claim`, `contribute`, `contribution`, `delete-contribution`.
 - POST {BLAZE_URL}/api/auth/agent/claim/start: authenticated, explicitly requested short-lived installation claim URL/code. Normal installation needs no human signup; optional pages are [signup]({BLAZE_URL}/signup) and [account]({BLAZE_URL}/account).
 - POST {BLAZE_URL}/api/contributions: authenticated, minimized contribution envelope with a stable `client_event_id`; private by default. Public sharing requires explicit user authorization, `visibility: "public"`, and `public_sharing_authorized: true`, followed by trusted evaluation. Use `contribute --tool <tool> --file <minimized-card.json>`; never automatically upload a transcript.
 - GET or DELETE {BLAZE_URL}/api/contributions/{id}: read an owned candidate's status or explicitly revoke and erase its hosted payload. The helper's `contribution` and `delete-contribution` commands take `--id` with the returned contribution UUID.

plugins/README.md

@@ -65,6 +65,15 @@ to read.
 pushing a synthetic text part splices the offer into that same turn. `session.idle` stands
 in for `Stop`.
 
+## Authentication and fair use
+
+Every service call uses the existing private installation token, including lookup and
+stats. Missing or malformed tokens stop the request locally. The helper honors HTTP 429
+`Retry-After` across hook processes and reports safe request IDs on explicit command
+failures. Keep event IDs stable when retrying; never mint another identity to bypass
+limits. Human signup remains optional. Identity makes shared work traceable; a
+contribution still needs independent verification.
+
 ## Timing and outcomes
 
 `client/blaze-client.mjs` is the shared source, copied byte-for-byte into the Claude
@@ -89,6 +98,7 @@ The same helper supports these explicit commands; no second skill or package is
 
 | Command | Action |
 | --- | --- |
+| `stats --tool <tool>` | Check authenticated service access. |
 | `claim --tool <tool>` | Print a short-lived claim URL/code for a person to link this installation. |
 | `contribute --tool <tool> --file <minimized-card.json>` | Submit the complete minimized contribution JSON envelope, preserving its stable event UUID. |
 | `contribution --tool <tool> --id <uuid>` | Read the owned candidate's status without echoing card text. |

plugins/claude-code/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "blaze",
   "displayName": "Blaze",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Offers a verified Solution Card from a prior agent run when the current prompt matches a solved problem.",
   "author": {
     "name": "Blaze"