heron-ai 0.1.3 → 0.1.4

package/README.md

@@ -17,7 +17,11 @@
 </p>
 
 <p align="center">
-  <strong>See the demo &rarr;</strong> <a href="https://github.com/theonaai/Heron">View on GitHub</a>
+  <img src=".github/heron-demo.gif" alt="Heron demo" width="800" />
+</p>
+
+<p align="center">
+  <strong>Watch the full demo (2 min) &rarr;</strong> <a href="https://youtu.be/Gk2MP9qsCLY">YouTube</a>
 </p>
 
 ---
@@ -30,10 +34,12 @@ The alternative to Heron is a Google Doc that nobody updates. The doc is wrong t
 
 Heron interviews the agent directly. The agent answers about itself &mdash; what systems it touches, what data it handles, what permissions it has, what happens when something goes wrong. You get a structured audit report with risk scoring, findings, and a permissions delta showing what the agent has versus what it actually needs.
 
-I tested it on a real content pipeline agent. Heron found **9 connected systems**, **1 critical issue** (an unauthenticated local HTTP worker), **5 high-severity findings**, and **2 scopes that can be safely revoked right now**. Total time: about 5 minutes from one command.
+I tested it on a real content pipeline agent. Heron found **9 connected systems**, **1 critical issue** (an unauthenticated local HTTP worker), **4 high-severity findings**, and **2 scopes that can be safely revoked right now**. Total time: about 5 minutes from one command.
 
 No SDK integration. No code changes to the agent. Works with any agent that speaks the OpenAI API.
 
+Try it: `npx heron-ai`
+
 ```
 ┌──────────┐         ┌──────────────┐         ┌──────────────┐
 │          │         │              │         │              │
@@ -46,6 +52,16 @@ No SDK integration. No code changes to the agent. Works with any agent that spea
                      └──────────────┘         └──────────────┘
 ```
 
+## Who this is for
+
+**Security engineers approving agent deployments.** Your dev team wants to ship a new agent. You need to know what it touches before you sign off. Run `npx heron-ai`, get a structured report with findings, risk score, and a permissions delta. Faster than a Google Doc, harder to fake than a verbal walkthrough.
+
+**Platform and DevOps leads inheriting agents from other teams.** You just got handed three agents from a team that left. You don't know what they do. Heron interviews them in about 5 minutes and tells you which production systems they touch and which OAuth scopes they hold. Map your blast radius before you have to defend it.
+
+**Compliance and audit teams preparing evidence packages.** Heron generates regulator-ready reports with EU AI Act, GDPR, SOC 2, and UK GDPR mappings &mdash; based on what the agent actually does, not a generic checklist. Attach to your control evidence.
+
+**Founders and tech leads asked "is this safe?" by a customer.** You're selling an AI feature into a regulated buyer. They ask for an access review. You don't have one. Heron gives you a structured artifact you can hand them in 5 minutes instead of writing one from scratch.
+
 ## Quick Start
 
 Three ways to use Heron, depending on your setup.
@@ -278,15 +294,7 @@ Follow-ups are generated when answers are vague or compliance fields are missing
 
 **[View full example report &rarr;](examples/example-report.md)**
 
-A real audit of an educational content pipeline agent &mdash; reads lessons from Google Sheets, generates Russian content with Gemini, creates Google Docs and slide decks, publishes to an LMS. The report covers 9 connected systems, 1 critical and 5 high-severity findings, per-system access cards, regulatory flags (GDPR, SOC 2, EU AI Act), and a verdict with actionable recommendations.
-
-## Use Cases
-
-**Security team: "vet before you deploy"** &mdash; Deploy Heron as a gate. Agents must pass an audit before getting production access. Review structured reports with findings, risk levels, and recommendations.
-
-**Team lead: "what does this agent actually do?"** &mdash; Paste the prompt into the agent's chat. Get a clear breakdown of systems, data, permissions, and blast radius.
-
-**Compliance: "prove your agents are controlled"** &mdash; Heron generates audit-ready reports with regulatory flags for EU AI Act, GDPR, SOC 2, and UK GDPR. Attach to compliance evidence packages.
+A real audit of an educational content pipeline agent &mdash; reads lessons from Google Sheets, generates Russian content with Gemini, creates Google Docs and slide decks, publishes to an LMS. The report covers 9 connected systems, 1 critical and 4 high-severity findings, per-system access cards, regulatory flags (GDPR, SOC 2, EU AI Act), and a verdict with actionable recommendations.
 
 ## Two Modes
 

package/dist/bin/heron.js

@@ -8,7 +8,7 @@ const program = new Command();
 program
     .name('heron')
     .description('Open-source agent checkpoint — vet AI agents before granting production access')
-    .version('0.1.3');
+    .version('0.1.4');
 // ─── scan: active mode (Heron → Agent) ───────────────────────────────────
 program
     .command('scan')
@@ -81,6 +81,20 @@ program
         process.exit(1);
     }
 });
+// ─── install-skill: install Claude Code skill ───────────────────────────────
+program
+    .command('install-skill')
+    .description('Install the /heron-audit skill for Claude Code')
+    .action(async () => {
+    try {
+        const { installSkill } = await import('../src/commands/install-skill.js');
+        await installSkill();
+    }
+    catch (err) {
+        logger.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+});
 // ─── Interactive mode: no args → ask what to do ─────────────────────────────
 import { createInterface } from 'node:readline';
 /** Arrow-key selector like Claude Code / npm init */
@@ -179,7 +193,7 @@ async function interactiveStart() {
     }
 }
 const args = process.argv.slice(2);
-const hasSubcommand = args.length > 0 && ['scan', 'serve', 'help', '--help', '-h', '--version', '-V'].includes(args[0]);
+const hasSubcommand = args.length > 0 && ['scan', 'serve', 'install-skill', 'help', '--help', '-h', '--version', '-V'].includes(args[0]);
 if (!hasSubcommand && args.length > 0) {
     // Legacy: flags without subcommand → scan
     process.argv.splice(2, 0, 'scan');

package/dist/bin/heron.js.map

@@ -1 +1 @@
-{"version":3,"file":"heron.js","sourceRoot":"","sources":["../../bin/heron.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"heron.js","sourceRoot":"","sources":["../../bin/heron.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/install-skill.d.ts

@@ -0,0 +1,2 @@
+export declare function installSkill(): Promise<void>;
+//# sourceMappingURL=install-skill.d.ts.map

package/dist/src/commands/install-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-skill.d.ts","sourceRoot":"","sources":["../../../src/commands/install-skill.ts"],"names":[],"mappings":"AASA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAwBlD"}

package/dist/src/commands/install-skill.js

@@ -0,0 +1,26 @@
+import { mkdirSync, copyFileSync, existsSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import * as logger from '../util/logger.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export async function installSkill() {
+    const skillSource = join(__dirname, '..', '..', 'skills', 'heron-audit');
+    const skillTarget = join(homedir(), '.claude', 'skills', 'heron-audit');
+    if (!existsSync(join(skillSource, 'SKILL.md'))) {
+        logger.error(`Skill source not found: ${skillSource}`);
+        logger.raw('  If you cloned the repo, run: bash skills/heron-audit/install.sh');
+        process.exit(1);
+    }
+    mkdirSync(join(skillTarget, 'bin'), { recursive: true });
+    mkdirSync(join(homedir(), '.heron'), { recursive: true });
+    copyFileSync(join(skillSource, 'SKILL.md'), join(skillTarget, 'SKILL.md'));
+    copyFileSync(join(skillSource, 'bin', 'heron-update-check'), join(skillTarget, 'bin', 'heron-update-check'));
+    chmodSync(join(skillTarget, 'bin', 'heron-update-check'), 0o755);
+    logger.success(`Installed skill to ${skillTarget}`);
+    logger.raw('');
+    logger.raw('  Usage: type /heron-audit in any Claude Code session.');
+    logger.raw('');
+}
+//# sourceMappingURL=install-skill.js.map

package/dist/src/commands/install-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-skill.js","sourceRoot":"","sources":["../../../src/commands/install-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAE5C,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IACzE,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;IAExE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,2BAA2B,WAAW,EAAE,CAAC,CAAC;QACvD,MAAM,CAAC,GAAG,CAAC,mEAAmE,CAAC,CAAC;QAChF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE1D,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;IAC3E,YAAY,CACV,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,oBAAoB,CAAC,EAC9C,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAC/C,CAAC;IACF,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,oBAAoB,CAAC,EAAE,KAAK,CAAC,CAAC;IAEjE,MAAM,CAAC,OAAO,CAAC,sBAAsB,WAAW,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACf,MAAM,CAAC,GAAG,CAAC,wDAAwD,CAAC,CAAC;IACrE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heron-ai",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Open-source agent interrogator — audit what your AI agents do, need, and access",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   "license": "MIT",
   "files": [
     "dist/",
+    "skills/",
     "README.md",
     "LICENSE",
     "heron.example.yaml"

package/skills/heron-audit/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: heron-audit
+version: 0.3.0
+description: Audit this project's AI agent access — systems, permissions, data, risks, regulatory flags.
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Write
+  - Agent
+---
+
+# /heron-audit — AI Agent Access Audit
+
+## Preamble — Update Check
+
+Before doing anything else, run this:
+
+```bash
+_UPD=$(~/.claude/skills/heron-audit/bin/heron-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+```
+
+**If output shows `UPGRADE_AVAILABLE <old> <new>`:**
+
+Check if auto-upgrade is enabled:
+```bash
+cat ~/.heron/config 2>/dev/null | grep -q "auto_upgrade=true" && echo "AUTO" || echo "ASK"
+```
+
+If `AUTO`: upgrade silently (see upgrade steps below).
+
+If `ASK`: Tell the user "Heron update available: v{old} -> v{new}" and ask with these options:
+1. **"Yes, upgrade now"** — proceed with upgrade
+2. **"Always keep me up to date"** — write `auto_upgrade=true` to `~/.heron/config`, then upgrade
+3. **"Not now"** — skip update, continue with audit
+4. **"Never ask again"** — write `update_check=false` to `~/.heron/config`, continue with audit
+
+**Upgrade steps:**
+1. Find repo dir: `readlink -f ~/.claude/skills/heron-audit/SKILL.md 2>/dev/null | sed 's|/skills/heron-audit/SKILL.md||'`
+2. Run: `cd <repo-dir> && git pull origin main`
+3. Write marker: `echo "<old>" > ~/.heron/just-upgraded-from`
+4. Clear cache: `rm -f ~/.heron/last-update-check`
+5. Tell user: "Updated to v{new}. Running audit..."
+6. Continue with audit.
+
+**If output shows `JUST_UPGRADED <from> <to>`:** Tell the user "Running Heron v{to} (just updated!)" and continue.
+
+**If no output or error:** Continue silently.
+
+---
+
+You are now acting as **Heron**, an AI agent access auditor. Your job is to audit the **current project** by interviewing yourself about its systems, data access, permissions, and write operations — then produce a structured compliance report.
+
+## How It Works
+
+1. **Gather evidence** from the codebase (config files, env vars, API clients, SDKs)
+2. **Answer 10 structured interview questions** based on what you found
+3. **Analyze** the answers for risks, excessive permissions, and blast radius
+4. **Generate** a markdown report and save it
+
+## Step 1: Gather Evidence
+
+Before answering any questions, research the current project thoroughly. Look for:
+
+```
+# Config & environment
+.env, .env.example, .env.*, *.yaml, *.yml, *.toml, *.json (config files)
+docker-compose.yml, Dockerfile
+
+# API clients & SDKs
+package.json, requirements.txt, Gemfile, go.mod, Cargo.toml (dependencies)
+**/client.*, **/api.*, **/sdk.*, **/service.*
+
+# Auth & permissions
+**/*auth*, **/*token*, **/*credential*, **/*oauth*, **/*scope*
+**/*permission*, **/*role*, **/*policy*
+
+# Database & storage
+**/*database*, **/*db*, **/*migration*, **/*schema*
+**/*s3*, **/*storage*, **/*bucket*
+
+# Integrations
+**/*slack*, **/*webhook*, **/*email*, **/*notification*
+**/*stripe*, **/*payment*, **/*billing*
+
+# Claude/AI agent config
+CLAUDE.md, AGENTS.md, .claude/, MCP server configs
+```
+
+Use `Glob`, `Grep`, and `Read` to find relevant files. Do NOT read `.env` files with real secrets — only `.env.example` or references to env var names.
+
+Spawn an **Explore agent** to do a thorough codebase scan for all integration points, API clients, database connections, and external service usage. Tell it to look for the patterns above.
+
+## Step 2: Self-Interview
+
+Answer each of these 10 questions based ONLY on evidence you found in the codebase. If you cannot find evidence for something, answer "NOT PROVIDED — no evidence found in codebase."
+
+**CRITICAL RULES:**
+- ONLY report what you can verify from code, config, or documentation
+- Do NOT guess or infer scopes/permissions that aren't explicitly configured
+- Do NOT hallucinate system connections that aren't in the code
+- "NOT PROVIDED" is always better than a guess
+- If a `.env.example` shows `STRIPE_API_KEY=`, that's evidence of Stripe integration
+- If code imports `@slack/bolt`, that's evidence of Slack integration
+- If there's no evidence of writes, say "No write operations found in codebase"
+
+### Questions
+
+**Q1 — Deployment Profile**
+1. Project/product name
+2. Owner (team or person) — check package.json, README, CLAUDE.md
+3. What triggers execution (event / schedule / manual / CLI)
+4. One sentence: what this project specifically does
+
+**Q2 — Systems Enumeration**
+List every external system this project connects to.
+Format: Name -> API type -> Auth method
+Only list systems with actual code evidence (imports, API calls, config).
+
+**Q3 — Permissions Per System**
+For each system, what specific permissions are configured?
+List exact OAuth scopes, API key types, or database roles.
+Do NOT reveal actual secret values.
+
+**Q4 — Data Sensitivity**
+For each system, what data do you read?
+Classify each as: PII / financial / credentials / confidential / non-sensitive.
+Give one concrete example of the most sensitive data accessed.
+
+**Q5 — Write Operations**
+List every write operation. Format:
+Action -> Target system -> Reversible? -> Approval needed? -> Volume/day
+
+**Q6 — Blast Radius**
+For the most dangerous write operation:
+1. How many records/users can it affect? (1 record / 1 user / whole team / whole org)
+2. Worst-case scenario if it goes wrong?
+3. Can it be undone?
+
+**Q7 — Frequency and Volume**
+1. How often does this run?
+2. How many API calls per run?
+3. One-at-a-time or batches? What batch size?
+
+**Q8 — Excess Permissions**
+Which configured permissions are never actually used in the code?
+What could safely be revoked?
+
+**Q9 — Worst Case Failure**
+Worst realistic failure: wrong data to wrong recipient at max scale.
+What goes wrong, who's affected, how bad, can it be recovered?
+
+**Q10 — Decision-Making About People**
+Does this project make or influence decisions about people?
+Examples: hiring/screening, scoring creditworthiness, approving insurance, moderating content, granting/denying access, evaluating employees.
+If yes: what kind, who is affected, is a human involved before the final decision?
+
+## Step 3: Analyze
+
+After answering all 10 questions, analyze the answers:
+
+### Risk Assessment
+
+For each system, assess:
+- **Per-system risk**: LOW / MEDIUM / HIGH using this rubric:
+  - LOW: Read-only, non-sensitive data, single-user scope
+  - MEDIUM: Read access to sensitive data OR write to non-sensitive, reversible
+  - HIGH: Write to team/org data, or PII/financial access, or irreversible ops, or excessive permissions
+- **Overall risk** = highest individual system risk
+
+### Findings
+
+Generate findings with IDs (HERON-001, HERON-002, ...) for:
+- Excessive permissions (scopes granted but never used)
+- Sensitive data with broad blast radius
+- Irreversible write operations without safeguards
+- Missing approval workflows for high-impact operations
+- Any other security concerns
+
+Each finding needs: severity, title, description, and specific recommendation.
+
+### Positive Findings
+
+Note what's working well:
+- Reversible write operations
+- Limited blast radius
+- Appropriate permissions
+- No decision-making about people
+- Low frequency reduces risk
+
+### Regulatory Flags
+
+Based on the evidence, flag regulatory implications for three jurisdictions:
+
+**EU (EU AI Act + GDPR)**:
+- Does it process PII? -> GDPR applies
+- Does it make decisions about people? -> Check EU AI Act risk classification
+- Does it hold excessive permissions? -> GDPR Article 25 (data protection by design)
+
+**US (SOC 2 + State AI Laws)**:
+- Map to SOC 2 controls: CC1 (governance), CC6 (access), CC7 (monitoring), CC8 (change management)
+- Excessive permissions -> CC6.3 least privilege violation
+- Org-wide blast radius + writes -> CC7.2 / CC8.1
+
+**UK (UK GDPR + ICO)**:
+- Same as GDPR but reference UK GDPR / DPA 2018
+- ICO AI Risk Toolkit recommendations
+
+### Verdict
+
+Choose one:
+- **APPROVE** — minimal access, appropriate for stated purpose
+- **APPROVE WITH CONDITIONS** — acceptable but improvements needed
+- **DENY** — excessive access, unacceptable risk without remediation
+
+## Step 4: Generate Report
+
+Create the report and save it to `reports/heron-audit-YYYY-MM-DD.md`:
+
+The report must include these sections in this order:
+
+1. **Header** — Generated date, project name, risk level, data quality score, regulatory summary
+2. **Scope & Methodology** — Assessment type, method, duration, limitations
+3. **Executive Summary** — Dashboard table (Risk | Systems | Findings) + 2-3 sentence summary
+4. **Agent Profile** — Purpose, trigger, owner, frequency
+5. **Findings** — Table with ID, Severity, Finding, Description, Recommendation columns
+6. **Systems & Access** — Per-system cards with risk rating, scopes, data, blast radius, writes
+7. **What's Working Well** — Positive findings with checkmarks
+8. **Verdict & Recommendations** — Decision + numbered recommendations + permissions delta
+9. **Regulatory Compliance** — EU, US, UK sub-sections with specific flags
+10. **Data Quality** — Field-by-field coverage table (7 compliance fields)
+11. **Evidence Sources** — List of files analyzed (in collapsible details)
+
+Footer: *This report was generated automatically by [Heron](https://github.com/theonaai/Heron), an open-source AI agent auditor.*
+
+## Important Notes
+
+- Create the `reports/` directory if it doesn't exist
+- Use today's date in the filename
+- If a report already exists for today, append a number: `heron-audit-YYYY-MM-DD-2.md`
+- After saving, tell the user where the report is and give a brief summary of findings

package/skills/heron-audit/bin/heron-update-check

@@ -0,0 +1,81 @@
+#!/bin/bash
+# heron-update-check — check for newer versions of Heron
+# Outputs: UPGRADE_AVAILABLE <local> <remote>  |  JUST_UPGRADED <from> <to>  |  (nothing)
+set -euo pipefail
+
+# ── Paths ────────────────────────────────────────────────────────────────────
+HERON_DIR=""
+STATE_DIR="$HOME/.heron"
+CACHE_FILE="$STATE_DIR/last-update-check"
+MARKER_FILE="$STATE_DIR/just-upgraded-from"
+
+# Find the Heron repo root — resolve symlinks first
+SCRIPT_PATH="$0"
+# Follow symlinks to get the real path
+if command -v readlink >/dev/null 2>&1; then
+  REAL_PATH="$(readlink -f "$SCRIPT_PATH" 2>/dev/null || readlink "$SCRIPT_PATH" 2>/dev/null || echo "$SCRIPT_PATH")"
+else
+  REAL_PATH="$SCRIPT_PATH"
+fi
+SCRIPT_DIR="$(cd "$(dirname "$REAL_PATH")" && pwd)"
+
+# Script is in skills/heron-audit/bin/ → repo root is ../../..
+if [ -f "$SCRIPT_DIR/../../../VERSION" ]; then
+  HERON_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+fi
+
+# Can't find repo — skip silently
+[ -z "$HERON_DIR" ] && exit 0
+
+LOCAL_VERSION=""
+[ -f "$HERON_DIR/VERSION" ] && LOCAL_VERSION=$(cat "$HERON_DIR/VERSION" | tr -d '[:space:]')
+[ -z "$LOCAL_VERSION" ] && exit 0
+
+mkdir -p "$STATE_DIR"
+
+# ── Step 0: Check if updates disabled ───────────────────────────────────────
+if [ -f "$STATE_DIR/config" ] && grep -q "update_check=false" "$STATE_DIR/config" 2>/dev/null; then
+  exit 0
+fi
+
+# ── Step 1: Check "just upgraded" marker ────────────────────────────────────
+if [ -f "$MARKER_FILE" ]; then
+  OLD_VERSION=$(cat "$MARKER_FILE" | tr -d '[:space:]')
+  rm -f "$MARKER_FILE"
+  echo "JUST_UPGRADED $OLD_VERSION $LOCAL_VERSION"
+  exit 0
+fi
+
+# ── Step 2: Check cache (60-min TTL) ────────────────────────────────────────
+if [ -f "$CACHE_FILE" ]; then
+  CACHE_AGE=$(( $(date +%s) - $(stat -f%m "$CACHE_FILE" 2>/dev/null || stat -c%Y "$CACHE_FILE" 2>/dev/null || echo 0) ))
+  CACHED_RESULT=$(cat "$CACHE_FILE" 2>/dev/null || true)
+
+  if [ "$CACHE_AGE" -lt 3600 ]; then
+    # Cache is fresh
+    if echo "$CACHED_RESULT" | grep -q "^UPGRADE_AVAILABLE"; then
+      echo "$CACHED_RESULT"
+    fi
+    exit 0
+  fi
+fi
+
+# ── Step 3: Fetch remote VERSION from GitHub ────────────────────────────────
+REMOTE_VERSION=$(curl -sf --max-time 5 "https://raw.githubusercontent.com/theonaai/Heron/main/VERSION" 2>/dev/null | tr -d '[:space:]' || true)
+
+# Network error — assume up to date
+if [ -z "$REMOTE_VERSION" ]; then
+  echo "UP_TO_DATE" > "$CACHE_FILE"
+  exit 0
+fi
+
+# ── Step 4: Compare ─────────────────────────────────────────────────────────
+if [ "$LOCAL_VERSION" = "$REMOTE_VERSION" ]; then
+  echo "UP_TO_DATE" > "$CACHE_FILE"
+  exit 0
+fi
+
+# Versions differ — upgrade available
+RESULT="UPGRADE_AVAILABLE $LOCAL_VERSION $REMOTE_VERSION"
+echo "$RESULT" > "$CACHE_FILE"
+echo "$RESULT"

package/skills/heron-audit/install.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Install the /heron-audit skill for Claude Code
+#
+# Usage (from the repo root):
+#   cd Heron && bash skills/heron-audit/install.sh
+#
+# Or install via npx (no clone needed):
+#   npx heron-ai install-skill
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SKILL_DIR="$HOME/.claude/skills/heron-audit"
+
+echo "Installing /heron-audit skill for Claude Code..."
+
+mkdir -p "$SKILL_DIR/bin"
+mkdir -p "$HOME/.heron"
+
+# Symlink SKILL.md so updates to the repo automatically apply
+ln -sf "$SCRIPT_DIR/SKILL.md" "$SKILL_DIR/SKILL.md"
+
+# Symlink update checker
+ln -sf "$SCRIPT_DIR/bin/heron-update-check" "$SKILL_DIR/bin/heron-update-check"
+
+echo "Installed: $SKILL_DIR/SKILL.md -> $SCRIPT_DIR/SKILL.md"
+echo "Installed: $SKILL_DIR/bin/heron-update-check -> $SCRIPT_DIR/bin/heron-update-check"
+echo ""
+echo "Usage: Type /heron-audit in any Claude Code session to run an access audit."