clembot-doorman 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,18 @@
 
 ---
 
-## TL;DR · What is Clembot Doorman?
+### 🏆 ETHOnline 2026 Prize Tracks & Judge Quick-Links
+
+| Track | Prize | Artifact / Manifest | What It Demonstrates |
+|---|---|---|---|
+| **Bazantic · Agentify an API** | $500 / 300 / 200 | [`01-vet-mcp-candidate.json`](./bazantic/recipes/01-vet-mcp-candidate.json) | Agentifies our live OpenAPI 3.1 `mcp-scorecard` service into an autonomous pre-flight tool that evaluates untrusted MCP servers before adoption. |
+| **Bazantic · Continuity** | 2×$500 | [`02-deepwiki-pinned-researcher.json`](./bazantic/recipes/02-deepwiki-pinned-researcher.json) | **87.6% Context Token Reduction**: Crushes 3,400 tokens of raw DeepWiki schema bloat down to 420 tokens using Doorman's cached pinned recipe. |
+| **Bazantic · Best Multi-API Recipe** | $500 / 300 / 200 | [`03-governance-pipeline.json`](./bazantic/recipes/03-governance-pipeline.json) | **3-Gateway Autonomous Pipeline**: Audits tool safety → Settles $0.01 audit micropayment on Base mainnet via x402 → Pins SHA-256 hash to allowlist. |
+| **Base · x402 Micropayments** | Sponsor Track | [`mcp-scorecard/src/routes/spend.ts`](./mcp-scorecard/src/routes/spend.ts) | Real $0.01 per-audit micropayment settlement using EIP-712 spend permits on Base mainnet. |
+
+> **Judge Portals**: [Live Interactive Simulator](https://clembot-doorman.wanessalabs.com/#flow) · [Bazantic Showcase Page](https://clembot-doorman.wanessalabs.com/bazantic.html#recipes) · [ETHOnline Judging Criteria](https://clembot-doorman.wanessalabs.com/judges.html) · [2-Minute Verification Runbook](RUNBOOK.md)
+
+---
 
 **Clembot is built in many versions, with the latest utilizing Claude Code and a custom combination of agent harnesses.** While AI agents need tools to do real work, loading raw MCP servers blindly introduces **in-context steering ads**, prompt injection risks, and token-draining schema hallucination. 
 
@@ -23,7 +34,7 @@
 3. **Arm with Bazantic Recipes (`recipe.md`)**  
    Turns raw, unpredictable APIs into bounded, high-performing tools via structured `recipe.md` guidance. Built and verified against the Bazantic gateway (`clembot-doorman.bazgateway.com`).
 
-![The doorman declining a server it just graded F](media/doorman-decline.gif)
+![Clembot Doorman live interactive flow and tool governance demo](media/doorman-demo.gif)
 
 *A real run against a real server. The grade, the hard fail, and the arithmetic are live values, not a mockup: `webzum.com/api/mcp` scores **89.9% on configuration** and still fails, because one tool description injects **6,290 characters of unprompted upsell and competitor steering** directly into your agent's context window. One cent through the Bazantic gateway answered a question that would have cost $54.47 to measure in an unguided LLM loop. [Run it live in the simulator](https://clembot-doorman.wanessalabs.com/#flow).*
 
@@ -106,20 +117,25 @@ components that never register:
 claude plugin details clembot-doorman
 #   Skills (3)  doorman, doorman-guide, vet
 #   Agents (1)  doorman
-#   Hooks (1)   PreToolUse
+#   Hooks (2)   PreToolUse, SessionStart
 #   MCP servers (1)  scorecard
 ```
 
-### 2. The CLI: doctor, needs, report, watch, eval
+### 2. The CLI: doctor, needs, report, watch, notify, eval
 
 ```bash
-git clone https://github.com/clemenswan/clembot-doorman
-npm i -g ./clembot-doorman
+npm i -g clembot-doorman
 doorman --version
 ```
 
 Node 20+. Zero runtime dependencies, deliberately: every dependency is one more thing that can fail to install on your machine.
 
+**`notify` and the SessionStart hook need 0.2.0 or later.** The 0.1.0 on npm was
+published before they landed, so `doorman --version` reporting `0.1.0` means the
+push half is absent and no session will ever announce anything. Nothing errors:
+that build simply stays quiet forever, which is indistinguishable from having no
+news.
+
 **New here?** [`WALKTHROUGH.md`](WALKTHROUGH.md) runs the first ten minutes
 against three real builds: one with a long history, one brand new, and one in
 between. The output in it is captured from real runs, not written by hand.
@@ -320,6 +336,54 @@ Doorman is specifically designed to stop "skill sprawl" and prevent duplicate to
 2. **Adverse Drift Detection (`doorman watch`)**:
    When you run `doorman watch`, any candidate server already in your inventory is tagged `already-installed`. If an installed server is downgraded or caught with prompt injection on the feed, `watch` raises an immediate security alert.
 
+2a. **Push, without a daemon and without telemetry**:
+   Nobody can push to a laptop behind NAT that is asleep half the day, so the
+   push here is not a new transport. It is the poll going invisible. A
+   SessionStart hook prints a digest that is already on disk, then fires a
+   detached refresh so the next session is current. The hook makes no network
+   call: one that waited on a fetch would make every session start as slow as
+   the worst network it has seen, and offline would make them all fail.
+
+   ```text
+   ## doorman
+
+   1 newly graded server this build does not have:
+   - **A** 85.71/100, model not recorded https://mcp.deepwiki.com/mcp
+     not measured: behavioral, guidance
+   ```
+
+   Three rules, and each one is a notification product failing if broken. It
+   is **silent when nothing is new**, because a hook that reports "nothing new"
+   every morning teaches you to skip past the one morning it matters. It
+   **announces nothing on the first run**, because with no cursor the feed
+   returns everything graded so far and 26 rows is a catalogue, not news. And a
+   digest is **shown exactly once**, because the same three servers every
+   morning is how a notification becomes furniture.
+
+2b. **Popularity and trend, as a second axis (`GET /feed`, `?sort=trending`)**:
+   Every feed row carries a `popularity` block: Smithery use counts, npm weekly
+   downloads and GitHub stars, swept daily, with a median percentile and a
+   trend.
+
+   It is **never part of the score**. The grade is what happened when an agent
+   drove the server; popularity is how many people installed it without asking
+   that. A popular F is the most useful row this feed can publish, and a
+   blended number is the one thing guaranteed to bury it.
+
+   Counts are **ranked within each source and never summed across them**:
+   87,579 Smithery uses, 4,200 npm downloads and 1,100 stars are three units
+   counting three populations, and adding them makes a meaningless number that
+   still sorts confidently. `sources_measured` says how many sources backed the
+   percentile, because a server ranked on one and a server ranked on three are
+   not equally known. A trend needs two readings at least 12 hours apart, so a
+   newly tracked server reports `null` rather than zero growth, and a source
+   that could not be read is **absent rather than zero**.
+
+   **Doorman's own install counts are refused as a fourth source.** They would
+   be the best popularity signal available to anyone, and collecting them needs
+   telemetry. That would sell the guarantee that makes `watch` and `needs`
+   worth running at all: your inventory never leaves your machine.
+
 3. **Frontmatter Arithmetic (30 KB vs 640 KB)**:
    Doorman reads only YAML frontmatter (`name`, `description`) from `.claude/skills/*/SKILL.md` and `.claude/agents/*.md`. In our production vault, reading full markdown bodies was **642 KB**; reading frontmatter was **30 KB**. This allows the complete roster to be reviewed by a model in a single prompt without bloating context.
 
@@ -645,13 +709,20 @@ node runner/run.mjs --once --server https://mcp.deepwiki.com/mcp \
   --needed-for "look up how a public repository works" \
   --static-only --out ../evidence/deepwiki
 
-# Full behavioural run (needs a key)
-export ANTHROPIC_API_KEY=...
+# Full behavioural run (needs a key).
+# `=...` is NOT a value: read the secret in rather than pasting a placeholder,
+# which also keeps it out of shell history. A pasted "..." reaches the server
+# as a wrong token and comes back 401, which reads as a broken credential
+# rather than as a placeholder nobody substituted.
+read -rsp 'ANTHROPIC_API_KEY: ' ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
+# --once PRINTS ONLY. Add --out DIR to keep the evidence bundle, or queue the
+# audit and use --poll below to publish it to the feed.
 node runner/run.mjs --once --server https://mcp.deepwiki.com/mcp \
-  --needed-for "look up how a public repository works"
+  --needed-for "look up how a public repository works" --out out/deepwiki
 
 # Poll the queue
-export RUNNER_TOKEN=... SCORECARD_API=http://127.0.0.1:8799
+read -rsp 'RUNNER_TOKEN: ' RUNNER_TOKEN && export RUNNER_TOKEN
+export SCORECARD_API=http://127.0.0.1:8799
 node runner/run.mjs --poll
 ```
 

package/WALKTHROUGH.md

@@ -5,6 +5,8 @@ captured from an actual run on 2026-09-11 against the live feed, not written by
 hand. Where a run produced nothing useful, that is shown too, because "nothing
 matched" is a result and hiding it would make this document a brochure.
 
+![Clembot Doorman live interactive demo walkthrough](media/doorman-demo.gif)
+
 ---
 
 ## Install both halves
@@ -13,8 +15,7 @@ matched" is a result and hiding it would make this document a brochure.
 claude plugin marketplace add clemenswan/clembot-doorman
 claude plugin install clembot-doorman     # the gate, /doorman, /vet, the subagent
 
-git clone https://github.com/clemenswan/clembot-doorman
-npm i -g ./clembot-doorman                # doctor, needs, report, watch, eval
+npm i -g clembot-doorman                  # doctor, needs, report, watch, eval
 ```
 
 Check what actually loaded. A manifest can validate and still ship components

package/doorman/.claude/hooks/session-notify.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# SessionStart hook. The visible half of the push model.
+#
+# Prints a digest that is ALREADY ON DISK, then fires a detached refresh so the
+# next session is current. It makes no network call itself, which is the whole
+# design: a SessionStart hook that waits on a fetch makes every session start as
+# slow as the worst network it has ever seen, and offline it makes them fail.
+# The cost of this hook on a normal morning is one `test -f` and one `cat`.
+#
+# THIS IS NOT THE GATE. `mcp-gate.sh` is a security control and is offline,
+# dependency-free, and fails CLOSED with exit 2. This is a notification and
+# fails OPEN and silent: it always exits 0, and every failure path prints
+# nothing. A notifier that can break a session start is worse than no notifier.
+#
+# ponytail: the refresh rides on session start, so the first session after
+# install prints nothing (no digest yet) and news is at most one session stale.
+# A background poller (`doorman watch --poll`, roadmap Phase 2) would close that
+# gap and is not worth a daemon yet.
+
+set -uo pipefail
+
+# Never let this hook be the reason a session fails to start.
+trap 'exit 0' ERR
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+DIGEST="$PROJECT_DIR/.doorman/notify.md"
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+RESOLVE="$HERE/../../scripts/resolve-cli.sh"
+
+# 1. Say what is already known. Reading is destructive: consume-once is what
+#    stops the same three servers being announced every morning until they are
+#    furniture. `notify consume` does the delete.
+if [ -f "$DIGEST" ]; then
+  CLI=""
+  [ -x "$RESOLVE" ] && CLI="$(bash "$RESOLVE" 2>/dev/null || true)"
+  if [ -n "$CLI" ] && [ "$CLI" != "NOT_FOUND" ]; then
+    $CLI notify consume --digest "$DIGEST" 2>/dev/null || true
+  else
+    # No CLI resolved. Print it anyway and remove it by hand rather than
+    # holding news hostage to a resolution problem.
+    cat "$DIGEST" 2>/dev/null || true
+    rm -f "$DIGEST" 2>/dev/null || true
+  fi
+fi
+
+# 2. Refresh for next time, detached.
+#
+# stdout and stderr MUST be redirected away from this process. A background
+# child that inherits the hook's stdout keeps the pipe open, and the harness
+# waits on the pipe rather than on the process, so an unredirected `&` turns a
+# fire-and-forget into the exact session-start stall this design avoids.
+if [ -z "${DOORMAN_NO_REFRESH:-}" ]; then
+  CLI="${CLI:-}"
+  if [ -z "$CLI" ] && [ -x "$RESOLVE" ]; then
+    CLI="$(bash "$RESOLVE" 2>/dev/null || true)"
+  fi
+  if [ -n "$CLI" ] && [ "$CLI" != "NOT_FOUND" ]; then
+    LOG="$PROJECT_DIR/.doorman/notify.log"
+    mkdir -p "$PROJECT_DIR/.doorman" 2>/dev/null || true
+    nohup $CLI notify refresh --root "$PROJECT_DIR" >"$LOG" 2>&1 &
+    disown 2>/dev/null || true
+  fi
+fi
+
+exit 0

package/doorman/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "clembot-doorman",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A gate on what your agent is allowed to use. Blocks MCP servers that are not on your trust list, reads your prompt history to find what the build actually needs, and grades candidates before you install them.",
   "author": {
     "name": "Clemens Wan",

package/doorman/cli/doorman.mjs

@@ -16,6 +16,7 @@
   doorman needs [path]               read this build's own prompt history, propose servers.
  *   doorman watch [path]               poll the feed for candidates new to THIS build.
  *   doorman discover                   sweep a public directory for candidates. Curate, never enqueue.
+ *   doorman notify refresh|consume     the SessionStart push. Called by the hook, not by hand.
  *
  * Zero runtime dependencies, per the requirement in package.json. That is why
  * the YAML loader and the arg parser are in-tree rather than installed.
@@ -29,8 +30,13 @@ import { discover, renderDiscover, writeCandidates } from './discover.mjs';
 import { needs as readNeeds, render as renderNeedsCli } from './needs.mjs';
 import { install, renderInstall } from './install.mjs';
 import { allow, renderAllow, SCOPES } from './allow.mjs';
+import { refreshNotify, consumeDigest, DEFAULT_DIGEST } from './notify.mjs';
+import { join } from 'node:path';
 
-const VERSION = '0.1.0';
+// Pinned to every other declaration by version.test.mjs. There are FOUR of
+// them (root package.json, doorman/package.json, plugin.json, this) and this
+// one silently reported 0.1.0 out of a 0.2.0 tarball.
+const VERSION = '0.2.0';
 
 const HELP = `
 doorman ${VERSION} — measure a candidate, do not just read it
@@ -58,6 +64,12 @@ doorman ${VERSION} — measure a candidate, do not just read it
       a match is only ever worth-measuring. Nothing here drove anything, so
       nothing here claims a server will work. Only eval answers that.
 
+  doorman notify refresh [--root DIR]   |   doorman notify consume [--digest FILE]
+      The push half, and the SessionStart hook is what calls it. refresh polls
+      the feed and leaves a short digest on disk; consume prints that digest
+      and deletes it. Nothing is announced on the first run, nothing is written
+      when nothing is new, and a digest is shown exactly once.
+
   doorman report <link> [--out DIR] [--needed-for TEXT]
       L1. The static implementation report: protocol, schemas, annotations, and
       a scan-only pass over every description an agent would read before
@@ -248,6 +260,42 @@ async function main() {
     return;
   }
 
+  // The push half. Two verbs, and neither is meant to be typed by a human:
+  // the SessionStart hook calls `consume`, then `refresh` detached.
+  if (cmd === 'notify') {
+    const sub = args._[1];
+    const root = args.root || process.cwd();
+
+    if (sub === 'consume') {
+      const file = args.digest || join(root, DEFAULT_DIGEST);
+      const text = consumeDigest(file);
+      if (text) console.log(text);
+      // Nothing to say is exit 0 and silence, not an error. See rule 1 in
+      // notify.mjs: a notifier that speaks every session gets ignored.
+      return;
+    }
+
+    if (sub === 'refresh') {
+      const api = (args.api || DEFAULT_API).replace(/\/+$/, '');
+      try {
+        const r = await refreshNotify({ root, api, limit: Number(args.limit) > 0 ? Number(args.limit) : 50 });
+        if (args.json) console.log(JSON.stringify(r, null, 2));
+        else if (r.firstRun) console.log('First run: cursor established, nothing announced.');
+        else console.log(r.wrote ? `digest written to ${r.digest}` : 'nothing new, no digest written');
+      } catch (e) {
+        // Could not measure is 3, same as watch. This runs detached from a
+        // hook, so the exit code lands in .doorman/notify.log and nowhere else.
+        console.error(`notify refresh: ${e.message}`);
+        process.exitCode = e.code === 3 ? 3 : 1;
+      }
+      return;
+    }
+
+    console.error('notify needs a subcommand: consume or refresh');
+    process.exitCode = 2;
+    return;
+  }
+
   if (!['report', 'eval'].includes(cmd)) {
     console.error(`unknown command "${cmd}". Try: doorman --help`);
     process.exitCode = 2;

package/doorman/cli/install.mjs

@@ -14,7 +14,7 @@
  * And safely inspects/wires .claude/settings.json without destructive clobbering.
  */
 
-import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -58,6 +58,19 @@ export async function install(targetDir = process.cwd(), { dryRun = false } = {}
 
   // 1. Hooks, Subagent, Command
   copy('.claude/hooks/mcp-gate.sh', '.claude/hooks/mcp-gate.sh');
+  // copyFileSync preserves the SOURCE mode, and the source inside an installed
+  // npm package is 644: npm pack on Windows drops the executable bit from every
+  // file. Verified against the published 0.1.0 tarball, 2026-09-12. Without this
+  // the gate lands non-executable, fails to SPAWN rather than exiting 2, and the
+  // security control fails open. install.sh has carried the same chmod since it
+  // was written; this path never did.
+  if (!dryRun) {
+    try {
+      chmodSync(join(absTarget, '.claude/hooks/mcp-gate.sh'), 0o755);
+    } catch {
+      warnings.push('could not mark .claude/hooks/mcp-gate.sh executable; run: chmod +x .claude/hooks/mcp-gate.sh');
+    }
+  }
   copy('agents/doorman.md', '.claude/agents/doorman.md');
   copy('commands/vet.md', '.claude/commands/vet.md');
 

package/doorman/cli/notify.mjs

@@ -0,0 +1,145 @@
+/**
+ * The push half of the subscription.
+ *
+ * WHAT "PUSH" HONESTLY MEANS HERE. Nobody can push to a laptop behind NAT that
+ * is asleep half the day, and a doorman that opened a socket to wait for us
+ * would be a worse product than one that does not. So the push is not a new
+ * transport: it is the POLL BECOMING INVISIBLE. A SessionStart hook reads a
+ * digest that is already on disk and costs nothing, then fires a detached
+ * refresh so the NEXT session is current. From where the operator sits they
+ * never ran a command and the doorman told them anyway, which is the whole
+ * claim, and it is true.
+ *
+ * THREE RULES, AND EACH ONE IS A NOTIFICATION PRODUCT FAILING IF BROKEN:
+ *
+ * 1. SILENT WHEN THERE IS NOTHING. No digest file is written when nothing is
+ *    new. A hook that prints "nothing new" at every session start teaches the
+ *    operator to skip past the one session where it matters.
+ *
+ * 2. THE FIRST RUN SAYS NOTHING. With no cursor the feed returns everything
+ *    graded so far. Announcing 26 rows as "new" the first time a plugin loads
+ *    is not news, it is a catalogue nobody asked for. The first refresh
+ *    establishes the cursor and writes no digest.
+ *
+ * 3. CONSUMED ONCE. The hook prints the digest and deletes it. Re-showing the
+ *    same three servers every morning is how a notification becomes furniture.
+ *
+ * The network never runs inside the hook. A SessionStart hook that waits on a
+ * fetch makes every session start as slow as the slowest network it has ever
+ * been on, and offline it makes them all fail.
+ */
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { watch, readState, writeState, DEFAULT_API, DEFAULT_STATE } from './watch.mjs';
+
+export const DEFAULT_DIGEST = join('.doorman', 'notify.md');
+
+/** How many rows the digest will name before it stops listing and counts. */
+export const MAX_LISTED = 3;
+
+/**
+ * The digest, or null for "say nothing".
+ *
+ * Only two verdicts are ever worth interrupting a session for. `unreviewed` is
+ * something you could adopt and have not looked at. `blocked` is something the
+ * registry already refuses, and seeing it in a fresh grade is a reason to check
+ * whether anyone tried. `already-installed` and `skipped` are not news: the
+ * first is a server you have, and the second you decided about.
+ */
+export function renderNotify(result, { firstRun = false } = {}) {
+  if (firstRun) return null;
+
+  const rows = result.candidates ?? [];
+  const fresh = rows.filter((c) => c.verdict === 'unreviewed' && !c.is_fixture && !c.self_graded);
+  const blocked = rows.filter((c) => c.verdict === 'blocked');
+  if (!fresh.length && !blocked.length) return null;
+
+  const out = [];
+  out.push('## doorman');
+  out.push('');
+
+  if (fresh.length) {
+    const shown = fresh.slice(0, MAX_LISTED);
+    const noun = fresh.length === 1 ? 'server' : 'servers';
+    out.push(`${fresh.length} newly graded ${noun} this build does not have:`);
+    for (const c of shown) {
+      // The grade travels with what produced it. A letter with no model behind
+      // it invites a comparison across models that the grade cannot support.
+      const model = c.model ? ` on ${c.model}` : ', model not recorded';
+      const score = c.score === null || c.score === undefined ? 'not scored' : `${c.score}/100`;
+      out.push(`- **${c.grade ?? '?'}** ${score}${model} ${c.server_url}`);
+      const layers = c.layers ?? {};
+      const missing = ['behavioral_pct', 'guidance_pct']
+        .filter((k) => layers[k] === null || layers[k] === undefined)
+        .map((k) => k.replace('_pct', ''));
+      if (missing.length) out.push(`  not measured: ${missing.join(', ')}`);
+    }
+    if (fresh.length > shown.length) {
+      out.push(`- and ${fresh.length - shown.length} more`);
+    }
+    out.push('');
+  }
+
+  if (blocked.length) {
+    out.push(`${blocked.length} on your denylist were re-graded. Run \`doorman watch\` for the detail.`);
+    out.push('');
+  }
+
+  out.push('Run `doorman needs` to see which of these answer something this build ' +
+           'keeps asking for, or `doorman watch` for the full list. Nothing has been ' +
+           'installed and nothing was sent anywhere: the match runs on this machine.');
+  return out.join('\n');
+}
+
+/**
+ * Fetch, classify, and leave a digest for the next session to find.
+ *
+ * Advances the cursor whether or not a digest is written, because the cursor
+ * tracks what has been SEEN by the subscription rather than what was worth
+ * mentioning. Not advancing it on a quiet day would re-announce the same rows
+ * the moment something interesting finally landed.
+ */
+export async function refreshNotify({
+  root = process.cwd(), api = DEFAULT_API, limit = 50,
+  stateFile, digestFile, fetchImpl = fetch,
+} = {}) {
+  const state = stateFile ?? join(root, DEFAULT_STATE);
+  const digest = digestFile ?? join(root, DEFAULT_DIGEST);
+
+  const prior = readState(state);
+  const firstRun = !prior.since;
+
+  const result = await watch({ root, api, since: prior.since, limit, fetchImpl });
+  const text = renderNotify(result, { firstRun });
+
+  if (text) {
+    mkdirSync(dirname(digest), { recursive: true });
+    writeFileSync(digest, text + '\n', 'utf8');
+  }
+
+  if (result.next_since) {
+    writeState(state, { since: result.next_since, seen: (prior.seen ?? 0) + result.candidates.length });
+  }
+
+  return { wrote: Boolean(text), firstRun, digest, candidates: result.candidates.length };
+}
+
+/**
+ * What the hook prints. Reading is destructive on purpose: see rule 3.
+ *
+ * Any failure here returns nothing rather than throwing. This runs at session
+ * start, and a notification that can break a session start is worse than no
+ * notification.
+ */
+export function consumeDigest(file) {
+  try {
+    if (!file || typeof file !== 'string') return null;
+    if (!existsSync(file)) return null;
+    const text = readFileSync(file, 'utf8').trim();
+    unlinkSync(file);
+    return text || null;
+  } catch {
+    return null;
+  }
+}

package/doorman/commands/doorman.md

@@ -29,8 +29,7 @@ If it prints `NOT_FOUND`, stop and tell the user this, then end the turn:
 > Reinstall the plugin, or install the CLI directly:
 >
 > ```bash
-> git clone https://github.com/clemenswan/clembot-doorman
-> npm i -g ./clembot-doorman
+> npm i -g clembot-doorman
 > ```
 >
 > The gate is still running either way. It is pure bash and depends on none of

package/doorman/hooks/hooks.json

@@ -11,7 +11,16 @@
     "",
     "Timeout matches .claude/settings.json. The gate does no network and no",
     "subprocess, so 5s is generous; it exists so a wedged hook fails rather",
-    "than hanging every tool call."
+    "than hanging every tool call.",
+    "",
+    "BOTH COMMANDS RUN THROUGH `bash` ON PURPOSE. npm pack on Windows drops",
+    "the executable bit from every file, so the .sh files inside an installed",
+    "package are 644 and cannot be invoked by path. Verified against the",
+    "published 0.1.0 tarball on 2026-09-12: mcp-gate.sh ships -rw-r--r--.",
+    "A gate that cannot start does not exit 2, it fails to spawn, so the",
+    "security control FAILS OPEN, which is the one thing its design forbids.",
+    "Invoking through the interpreter makes the mode irrelevant on every",
+    "platform. Do not `simplify` this back to a bare path."
   ],
   "hooks": {
     "PreToolUse": [
@@ -20,11 +29,33 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/.claude/hooks/mcp-gate.sh",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/.claude/hooks/mcp-gate.sh",
             "timeout": 5
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/.claude/hooks/session-notify.sh",
+            "timeout": 10
+          }
+        ]
+      }
     ]
-  }
+  },
+  "$comment2": [
+    "SessionStart is the PUSH surface, and it is a different kind of hook from",
+    "the gate above. The gate is a security control: offline, dependency-free,",
+    "and it fails CLOSED with exit 2. The notifier fails OPEN and silent, always",
+    "exits 0, and prints nothing on every error path, because a notification",
+    "that can break a session start is worse than no notification.",
+    "",
+    "It makes no network call. It prints a digest already on disk and fires a",
+    "detached refresh for next time, so the cost on a normal session is one",
+    "file test. The 10s timeout is for a slow disk, not for a fetch."
+  ]
 }

package/doorman/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clembot-doorman",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "description": "Vets MCP servers, skills and repos before an agent gets them. Fit review first, paid grade second.",

package/doorman/recipes/README.md

@@ -32,5 +32,9 @@ Worth separating, because the project doc uses one word for both.
   its own past is not a record. The account is still the blocker, not the spec.
   Full detail in the root `README.md` under **Bazantic**.
 
-Filing these does not advance the prize recipes. It fills a directory the
-project doc asked for and that shipped empty.
+The three canonical Bazantic platform prize recipes are published in
+[`bazantic/recipes/`](../../bazantic/recipes/):
+1. `01-vet-mcp-candidate.json` — Agentify an API ($500/300/200)
+2. `02-deepwiki-pinned-researcher.json` — Help an Agent Use Your Project / Continuity (2×$500)
+3. `03-governance-pipeline.json` — Best Multi-API Recipe ($500/300/200)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clembot-doorman",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The Package Manager & Security Doorman for Claude Code: inspect your build, recommend vetted MCPs from prompt history, and block rogue tools before context.",
   "homepage": "https://clembot-doorman.wanessalabs.com",
   "type": "module",