agent-workflow-inspector 1.0.0 → 2.0.0

package/docs/assets/banner.svg

@@ -0,0 +1,105 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 280" width="100%" height="100%">
+  <defs>
+    <linearGradient id="bannerBg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#090d13"/>
+      <stop offset="50%" stop-color="#0d1117"/>
+      <stop offset="100%" stop-color="#161b22"/>
+    </linearGradient>
+    <linearGradient id="textGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#38bdf8"/>
+      <stop offset="50%" stop-color="#818cf8"/>
+      <stop offset="100%" stop-color="#c084fc"/>
+    </linearGradient>
+    <linearGradient id="shieldGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#38bdf8"/>
+      <stop offset="100%" stop-color="#4f46e5"/>
+    </linearGradient>
+    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="6" result="blur" />
+      <feComposite in="SourceGraphic" in2="blur" operator="over" />
+    </filter>
+  </defs>
+
+  <style>
+    .font-sans { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+    .font-mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
+  </style>
+
+  <!-- Background -->
+  <rect width="1000" height="280" rx="16" fill="url(#bannerBg)" stroke="#30363d" stroke-width="1.5"/>
+
+  <!-- Subtle Grid Pattern in Background -->
+  <g opacity="0.08" stroke="#ffffff" stroke-width="1">
+    <line x1="50" y1="0" x2="50" y2="280"/>
+    <line x1="150" y1="0" x2="150" y2="280"/>
+    <line x1="250" y1="0" x2="250" y2="280"/>
+    <line x1="350" y1="0" x2="350" y2="280"/>
+    <line x1="450" y1="0" x2="450" y2="280"/>
+    <line x1="550" y1="0" x2="550" y2="280"/>
+    <line x1="650" y1="0" x2="650" y2="280"/>
+    <line x1="750" y1="0" x2="750" y2="280"/>
+    <line x1="850" y1="0" x2="850" y2="280"/>
+    <line x1="950" y1="0" x2="950" y2="280"/>
+    <line x1="0" y1="70" x2="1000" y2="70"/>
+    <line x1="0" y1="140" x2="1000" y2="140"/>
+    <line x1="0" y1="210" x2="1000" y2="210"/>
+  </g>
+
+  <!-- Left Icon / Badge -->
+  <g transform="translate(60, 65)">
+    <!-- Outer Glow & Shield Frame -->
+    <rect width="140" height="140" rx="28" fill="#131d2e" stroke="#1e3a5f" stroke-width="2"/>
+    <rect x="12" y="12" width="116" height="116" rx="20" fill="url(#shieldGrad)" opacity="0.15"/>
+    
+    <!-- Inspector Graphic: Magnifying Glass + Trace Loop Node -->
+    <!-- Loop Nodes -->
+    <circle cx="50" cy="52" r="8" fill="#38bdf8"/>
+    <circle cx="90" cy="52" r="8" fill="#818cf8"/>
+    <circle cx="70" cy="88" r="8" fill="#f43f5e"/>
+
+    <!-- Connecting path -->
+    <path d="M 58 52 L 82 52" stroke="#38bdf8" stroke-width="2.5"/>
+    <path d="M 88 58 L 74 82" stroke="#818cf8" stroke-width="2.5"/>
+    <path d="M 66 82 L 52 58" stroke="#f43f5e" stroke-width="2.5" stroke-dasharray="3 2"/>
+
+    <!-- Warning badge on loop -->
+    <circle cx="70" cy="88" r="14" fill="none" stroke="#f43f5e" stroke-width="2" opacity="0.8"/>
+    <text x="70" y="122" text-anchor="middle" class="font-mono" font-size="11" font-weight="700" fill="#38bdf8">AWI v1.0</text>
+  </g>
+
+  <!-- Main Titles -->
+  <g transform="translate(235, 78)">
+    <text x="0" y="32" class="font-sans" font-size="34" font-weight="800" fill="url(#textGrad)" letter-spacing="-0.5">Agent Workflow Inspector</text>
+    
+    <text x="0" y="66" class="font-sans" font-size="17" font-weight="500" fill="#e6edf3">
+      Local-first, deterministic diagnostics &amp; linter for AI agent execution traces
+    </text>
+
+    <text x="0" y="94" class="font-sans" font-size="13.5" fill="#8b949e">
+      Detect suspicious retry storms, loops, cycles, and token waste • Zero LLM • Zero telemetry • Offline &amp; CI-ready
+    </text>
+
+    <!-- Badges Row Inside Banner -->
+    <g transform="translate(0, 114)">
+      <rect width="112" height="24" rx="12" fill="#1f2937" stroke="#374151"/>
+      <circle cx="12" cy="12" r="4" fill="#38bdf8"/>
+      <text x="22" y="16" class="font-sans" font-size="11" font-weight="600" fill="#f3f4f6">100% Local</text>
+
+      <rect x="122" width="138" height="24" rx="12" fill="#1f2937" stroke="#374151"/>
+      <circle cx="134" cy="12" r="4" fill="#34d399"/>
+      <text x="144" y="16" class="font-sans" font-size="11" font-weight="600" fill="#f3f4f6">Deterministic</text>
+
+      <rect x="270" width="150" height="24" rx="12" fill="#1f2937" stroke="#374151"/>
+      <circle cx="282" cy="12" r="4" fill="#fbbf24"/>
+      <text x="292" y="16" class="font-sans" font-size="11" font-weight="600" fill="#f3f4f6">OTLP &amp; AWI JSON</text>
+
+      <rect x="430" width="128" height="24" rx="12" fill="#1f2937" stroke="#374151"/>
+      <circle cx="442" cy="12" r="4" fill="#a855f7"/>
+      <text x="452" y="16" class="font-sans" font-size="11" font-weight="600" fill="#f3f4f6">CLI &amp; TS API</text>
+
+      <rect x="568" width="118" height="24" rx="12" fill="#1f2937" stroke="#374151"/>
+      <circle cx="580" cy="12" r="4" fill="#f43f5e"/>
+      <text x="590" y="16" class="font-sans" font-size="11" font-weight="600" fill="#f3f4f6">CI Gatekeeper</text>
+    </g>
+  </g>
+</svg>

package/docs/assets/detection-patterns.svg

@@ -0,0 +1,134 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 940 320" width="100%" height="100%">
+  <defs>
+    <linearGradient id="bg2" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0d1117"/>
+      <stop offset="100%" stop-color="#161b22"/>
+    </linearGradient>
+    <linearGradient id="pCardGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#1c2128"/>
+      <stop offset="100%" stop-color="#12161c"/>
+    </linearGradient>
+    <filter id="pCardShadow" x="-5%" y="-5%" width="110%" height="110%">
+      <feDropShadow dx="0" dy="4" stdDeviation="8" flood-color="#000000" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+
+  <style>
+    .font-sans { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; }
+    .font-mono { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; }
+  </style>
+
+  <rect width="940" height="320" rx="14" fill="url(#bg2)" stroke="#30363d" stroke-width="1"/>
+
+  <!-- Pattern 1: Retry Storm & Repeated Errors -->
+  <g transform="translate(24, 25)" filter="url(#pCardShadow)">
+    <rect width="206" height="270" rx="10" fill="url(#pCardGrad)" stroke="#f85149" stroke-width="1.2"/>
+    <rect width="206" height="38" rx="10" fill="#2d1519"/>
+    <rect y="28" width="206" height="10" fill="#2d1519"/>
+    <text x="14" y="24" class="font-sans" font-size="12" font-weight="700" fill="#ff7b72">AWI002 &amp; AWI004</text>
+    <text x="14" y="58" class="font-sans" font-size="13" font-weight="700" fill="#f0f6fc">Retry Storms</text>
+    <text x="14" y="76" class="font-sans" font-size="11" fill="#8b949e">Repeated failing calls</text>
+
+    <!-- Visual Sequence -->
+    <g transform="translate(14, 96)">
+      <rect width="178" height="30" rx="4" fill="#381a1f" stroke="#f85149" stroke-width="0.8"/>
+      <text x="10" y="20" class="font-mono" font-size="11" fill="#ff7b72">tool(search) ❌ FAIL</text>
+
+      <path d="M 89 32 L 89 42" stroke="#f85149" stroke-width="1.5" stroke-dasharray="2 2"/>
+      
+      <rect y="44" width="178" height="30" rx="4" fill="#381a1f" stroke="#f85149" stroke-width="0.8"/>
+      <text x="10" y="64" class="font-mono" font-size="11" fill="#ff7b72">tool(search) ❌ FAIL</text>
+
+      <path d="M 89 76 L 89 86" stroke="#f85149" stroke-width="1.5" stroke-dasharray="2 2"/>
+
+      <rect y="88" width="178" height="30" rx="4" fill="#381a1f" stroke="#f85149" stroke-width="0.8"/>
+      <text x="10" y="108" class="font-mono" font-size="11" fill="#ff7b72">tool(search) ❌ FAIL</text>
+
+      <text x="0" y="146" class="font-sans" font-size="10.5" fill="#fca5a5">💥 Rapid consecutive errors with identical arguments.</text>
+    </g>
+  </g>
+
+  <!-- Pattern 2: Execution Cycles -->
+  <g transform="translate(252, 25)" filter="url(#pCardShadow)">
+    <rect width="206" height="270" rx="10" fill="url(#pCardGrad)" stroke="#d29922" stroke-width="1.2"/>
+    <rect width="206" height="38" rx="10" fill="#2f2413"/>
+    <rect y="28" width="206" height="10" fill="#2f2413"/>
+    <text x="14" y="24" class="font-sans" font-size="12" font-weight="700" fill="#e3b341">AWI003</text>
+    <text x="14" y="58" class="font-sans" font-size="13" font-weight="700" fill="#f0f6fc">Execution Cycles</text>
+    <text x="14" y="76" class="font-sans" font-size="11" fill="#8b949e">Periodic tool loops (A-B-C-A)</text>
+
+    <!-- Visual Sequence -->
+    <g transform="translate(14, 96)">
+      <rect width="178" height="26" rx="4" fill="#1c2433" stroke="#58a6ff" stroke-width="0.8"/>
+      <text x="10" y="17" class="font-mono" font-size="10.5" fill="#79c0ff">1. Tool: read_file</text>
+
+      <rect y="32" width="178" height="26" rx="4" fill="#1c2433" stroke="#bc8cff" stroke-width="0.8"/>
+      <text x="10" y="49" class="font-mono" font-size="10.5" fill="#d2a8ff">2. Tool: edit_code</text>
+
+      <rect y="64" width="178" height="26" rx="4" fill="#1c2433" stroke="#3fb950" stroke-width="0.8"/>
+      <text x="10" y="81" class="font-mono" font-size="10.5" fill="#7ee787">3. Tool: run_test</text>
+
+      <!-- Loop Indicator -->
+      <path d="M 184 77 Q 198 48 184 20" fill="none" stroke="#d29922" stroke-width="2"/>
+      <polygon points="184,17 188,24 180,24" fill="#d29922"/>
+
+      <text x="0" y="122" class="font-sans" font-size="11" font-weight="600" fill="#e3b341">🔁 Repeated 3+ times</text>
+      <text x="0" y="146" class="font-sans" font-size="10.5" fill="#fde047">Agent trapped in circular non-converging logic.</text>
+    </g>
+  </g>
+
+  <!-- Pattern 3: Excessive Depth & Complexity -->
+  <g transform="translate(480, 25)" filter="url(#pCardShadow)">
+    <rect width="206" height="270" rx="10" fill="url(#pCardGrad)" stroke="#a371f7" stroke-width="1.2"/>
+    <rect width="206" height="38" rx="10" fill="#241936"/>
+    <rect y="28" width="206" height="10" fill="#241936"/>
+    <text x="14" y="24" class="font-sans" font-size="12" font-weight="700" fill="#d2a8ff">AWI005</text>
+    <text x="14" y="58" class="font-sans" font-size="13" font-weight="700" fill="#f0f6fc">Runaway Tree</text>
+    <text x="14" y="76" class="font-sans" font-size="11" fill="#8b949e">Excess depth or operations</text>
+
+    <!-- Visual Tree -->
+    <g transform="translate(14, 96)">
+      <rect width="178" height="22" rx="4" fill="#261b3d" stroke="#8957e5"/>
+      <text x="8" y="15" class="font-mono" font-size="10" fill="#d2a8ff">Root Coordinator</text>
+
+      <g transform="translate(14, 28)">
+        <path d="M 0 0 L 0 14 L 10 14" stroke="#8957e5" stroke-width="1.5" fill="none"/>
+        <rect x="12" width="152" height="22" rx="4" fill="#261b3d" stroke="#8957e5"/>
+        <text x="20" y="15" class="font-mono" font-size="10" fill="#d2a8ff">Subagent A</text>
+      </g>
+
+      <g transform="translate(28, 56)">
+        <path d="M 0 0 L 0 14 L 10 14" stroke="#8957e5" stroke-width="1.5" fill="none"/>
+        <rect x="12" width="138" height="22" rx="4" fill="#261b3d" stroke="#8957e5"/>
+        <text x="20" y="15" class="font-mono" font-size="10" fill="#d2a8ff">Sub-task ... [Depth &gt; 20]</text>
+      </g>
+
+      <text x="0" y="122" class="font-mono" font-size="11" font-weight="600" fill="#d2a8ff">&gt; 100 total operations</text>
+      <text x="0" y="146" class="font-sans" font-size="10.5" fill="#e9d5ff">Catches exponential subagent recursion bugs.</text>
+    </g>
+  </g>
+
+  <!-- Pattern 4: Resource & Cost Burn -->
+  <g transform="translate(708, 25)" filter="url(#pCardShadow)">
+    <rect width="206" height="270" rx="10" fill="url(#pCardGrad)" stroke="#3fb950" stroke-width="1.2"/>
+    <rect width="206" height="38" rx="10" fill="#142b1a"/>
+    <rect y="28" width="206" height="10" fill="#142b1a"/>
+    <text x="14" y="24" class="font-sans" font-size="12" font-weight="700" fill="#7ee787">AWI006</text>
+    <text x="14" y="58" class="font-sans" font-size="13" font-weight="700" fill="#f0f6fc">Resource Burn</text>
+    <text x="14" y="76" class="font-sans" font-size="11" fill="#8b949e">Tokens &amp; cost pinned to errors</text>
+
+    <!-- Visual Burn -->
+    <g transform="translate(14, 96)">
+      <rect width="178" height="38" rx="4" fill="#132317" stroke="#238636"/>
+      <text x="10" y="18" class="font-mono" font-size="11" fill="#7ee787">Wasted Tokens: +84,200</text>
+      <text x="10" y="32" class="font-sans" font-size="10" fill="#8b949e">Pinned to culprit leaves</text>
+
+      <rect y="46" width="178" height="38" rx="4" fill="#132317" stroke="#238636"/>
+      <text x="10" y="66" class="font-mono" font-size="11" fill="#7ee787">Wasted Cost: $4.21 USD</text>
+      <text x="10" y="80" class="font-sans" font-size="10" fill="#8b949e">Direct currency tracking</text>
+
+      <text x="0" y="122" class="font-sans" font-size="11" font-weight="600" fill="#7ee787">💰 Leaf Attribution</text>
+      <text x="0" y="146" class="font-sans" font-size="10.5" fill="#bbf7d0">Pinpoints financial waste directly to flawed loops.</text>
+    </g>
+  </g>
+</svg>

package/docs/assets/terminal-preview.svg

@@ -0,0 +1,93 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 540" width="100%" height="100%">
+  <defs>
+    <linearGradient id="terminalBg" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#161b22"/>
+      <stop offset="100%" stop-color="#0d1117"/>
+    </linearGradient>
+    <filter id="shadow" x="-5%" y="-5%" width="110%" height="110%">
+      <feDropShadow dx="0" dy="12" stdDeviation="16" flood-color="#000000" flood-opacity="0.5"/>
+    </filter>
+  </defs>
+
+  <style>
+    .window { fill: url(#terminalBg); stroke: #30363d; stroke-width: 1; rx: 10px; }
+    .header { fill: #161b22; stroke: #30363d; stroke-width: 1; }
+    .title { fill: #8b949e; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 13px; font-weight: 500; text-anchor: middle; }
+    .text { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 13px; line-height: 20px; }
+    .cmd { fill: #58a6ff; font-weight: 600; }
+    .prompt { fill: #7ee787; font-weight: 600; }
+    .dim { fill: #8b949e; }
+    .info { fill: #c9d1d9; }
+    .high-badge { fill: #f85149; font-weight: bold; }
+    .high-title { fill: #ff7b72; font-weight: 600; }
+    .med-badge { fill: #d29922; font-weight: bold; }
+    .med-title { fill: #e3b341; font-weight: 600; }
+    .desc { fill: #8b949e; }
+    .evidence { fill: #79c0ff; }
+    .summary { fill: #f85149; font-weight: 600; }
+    .exit-code { fill: #ff7b72; font-weight: bold; }
+  </style>
+
+  <g filter="url(#shadow)">
+    <!-- Terminal Window -->
+    <rect x="20" y="20" width="880" height="500" rx="10" class="window" />
+    
+    <!-- Title Bar -->
+    <path d="M 20 30 Q 20 20 30 20 L 890 20 Q 900 20 900 30 L 900 56 L 20 56 Z" fill="#161b22" stroke="#30363d" stroke-width="1" />
+    <line x1="20" y1="56" x2="900" y2="56" stroke="#30363d" stroke-width="1"/>
+
+    <!-- Mac-style Window Controls -->
+    <circle cx="42" cy="38" r="6" fill="#ff5f56" stroke="#e0443e" stroke-width="0.5"/>
+    <circle cx="62" cy="38" r="6" fill="#ffbd2e" stroke="#dea123" stroke-width="0.5"/>
+    <circle cx="82" cy="38" r="6" fill="#27c93f" stroke="#1aab29" stroke-width="0.5"/>
+
+    <!-- Title -->
+    <text x="460" y="42" class="title">awi inspect examples/suspicious/retries.json</text>
+
+    <!-- Terminal Content -->
+    <g transform="translate(42, 86)">
+      <!-- Command line -->
+      <text x="0" y="0" class="text">
+        <tspan class="prompt">$ </tspan>
+        <tspan class="cmd">awi inspect examples/suspicious/retries.json</tspan>
+      </text>
+
+      <text x="0" y="26" class="text info">Agent Workflow Inspector — Find loops, retries, and wasted work in AI agent traces.</text>
+      <text x="0" y="46" class="text dim">Trace retries: 5 operations, 5 tool calls, depth 1; duration 9000 ms; recorded leaf usage {"inputTokens":50}</text>
+
+      <!-- Finding 1: AWI002 -->
+      <text x="0" y="80" class="text">
+        <tspan class="high-badge">[HIGH] </tspan>
+        <tspan class="high-title">AWI002 Repeated identical failing tool call (high evidence)</tspan>
+      </text>
+      <text x="16" y="100" class="text dim">Trace: retries; operations: op-0, op-1, op-2, op-3, op-4</text>
+      <text x="16" y="120" class="text info">Equivalent recorded tool calls failed with matching error evidence.</text>
+      <text x="16" y="140" class="text evidence">Evidence: {"occurrences":5,"identicalArguments":true,"equivalentFailureOutcomes":true}</text>
+
+      <!-- Finding 2: AWI004 -->
+      <text x="0" y="174" class="text">
+        <tspan class="high-badge">[HIGH] </tspan>
+        <tspan class="high-title">AWI004 Retry storm (moderate evidence)</tspan>
+      </text>
+      <text x="16" y="194" class="text dim">Trace: retries; operations: op-0, op-1, op-2, op-3, op-4</text>
+      <text x="16" y="214" class="text info">Rapid equivalent attempts follow explicit failures in a 30s window.</text>
+      <text x="16" y="234" class="text evidence">Evidence: {"attempts":5,"windowSeconds":30,"priorAttemptsExplicitlyFailed":true}</text>
+
+      <!-- Finding 3: AWI006 -->
+      <text x="0" y="268" class="text">
+        <tspan class="med-badge">[MEDIUM] </tspan>
+        <tspan class="med-title">AWI006 Recorded resource usage associated with suspicious execution</tspan>
+      </text>
+      <text x="16" y="288" class="text dim">Trace: retries; operations: op-0, op-1, op-2, op-3, op-4</text>
+      <text x="16" y="308" class="text info">Recorded resources belong directly to operations in suspicious patterns.</text>
+      <text x="16" y="328" class="text evidence">Evidence: {"recordedUsage":{"inputTokens":50},"recordedCosts":{"USD":0.005},"relatedRules":["AWI002","AWI004"]}</text>
+
+      <!-- Footer summary -->
+      <line x1="0" y1="354" x2="836" y2="354" stroke="#21262d" stroke-width="1"/>
+      <text x="0" y="380" class="text">
+        <tspan class="summary">✖ 3 findings (2 high, 1 medium); analysis complete.</tspan>
+        <tspan class="dim">  [Exit code: </tspan><tspan class="exit-code">2</tspan><tspan class="dim">]</tspan>
+      </text>
+    </g>
+  </g>
+</svg>

package/docs/ci-integration.md

@@ -1,17 +1,45 @@
 # CI integration
 
-AWI does not upload traces. Supply local synthetic/recorded JSON from your own job and treat reports as potentially sensitive.
+AWI analyzes local JSON and sends no telemetry. Use synthetic traces for examples. Review reports before sharing because workflow measurements, source indices and relationships can be sensitive. See the [security and privacy documentation](security.md).
+
+## Inside the AWI repository
+
+After checkout, use the repository's pinned pnpm version and build its source:
 
 ```yaml
+- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+  with:
+    persist-credentials: false
 - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
   with:
-    node-version: '24'
+    node-version: '24.11.0'
+    package-manager-cache: false
 - uses: pnpm/action-setup@a8198c4bff370c8506180b035930dea56dbd5288 # v5
 - run: pnpm install --frozen-lockfile
 - run: pnpm build
-- run: node dist/cli/index.js inspect ./traces --format json --fail-on high --output awi-report.json
+- run: pnpm verify:quickstart
+```
+
+The verifier expects exit 0 for the healthy fixture and exit 2 with `AWI002`, `AWI004`, and `AWI006` for retries. It exits 0 only when both match, so expected findings do not fail the job.
+
+Repository CI runs this verification alongside typecheck, lint, 69 tests, build, formatting, schema drift, production audit and package smoke checks on Windows/macOS/Linux × Node 22.18.0/24.11.0/26. Earlier hosted results are recorded in [verification](verification.md); a fresh matrix is needed for these changes.
+
+## Inside another repository
+
+Install the published CLI rather than expecting AWI's `dist/` and `examples/` paths in your application. Version 1.0.0 was confirmed in the [npm registry](https://registry.npmjs.org/agent-workflow-inspector/1.0.0) on October 20, 2026. The following steps assume your checkout contains `test-traces/` with supported JSON exports:
+
+```yaml
+- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+  with:
+    persist-credentials: false
+- uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6
+  with:
+    node-version: '24.11.0'
+    package-manager-cache: false
+- run: npm install --global --ignore-scripts agent-workflow-inspector@1.0.0
+- run: awi inspect ./test-traces --format json --fail-on high --output awi-report.json
 ```
 
-Repository CI is configured to check Node 22/24/26 on Windows/Linux/macOS with typecheck, lint, tests, build, format, schema drift, production audit and packaging. Local Windows and Linux WSL checks do not prove the hosted matrix outcomes; macOS remains unverified. Workflow actions are pinned to verified upstream commits using Node 24; checkout does not persist credentials. Permissions are read-only and nothing is published.
+Set workflow permissions to `contents: read`. For lockfile-controlled dependencies, add AWI as an exact dev dependency in your application, commit its lockfile, and use your package manager's local executable instead of a global install.
 
-Exit 1 takes precedence over finding thresholds: structural errors prevent a report; truncation emits incomplete JSON and exits 1. Exit 2 means completed analysis meets severity. fail-on none never masks errors. Warnings are structured in JSON, not mixed into stdout. Missing evidence is documented even when all applicable rules complete.
+The gate exits 0 below threshold, 2 for completed analysis meeting the threshold, or 1 for errors/incomplete analysis. `--fail-on none` never masks errors. Do not suppress exit 2 when you want findings to block CI. JSON warnings remain structured in stdout. `--output` requires a new filename in an existing directory; keep reports outside input directories and remove old reports before rerunning.

package/docs/configuration.md

@@ -13,3 +13,5 @@ awi-sha256-v1 hashes operation type, toolName (fallback name), argument presence
 Generated canonical JSON is not subject to the per-input-string limit; argument objects containing multiple individually valid strings remain supported within the content budget. The v1 byte contract is unchanged. Ignored paths are compiled into bounded maps, safely reused while unchanged, and never matched by repeatedly serializing full ancestor paths.
 
 Identical fingerprints mean identical recorded values under these rules, not identical effects. Hashes are sensitive correlators, not anonymization, and are absent from ordinary reports.
+
+AWI007 defaults to `{ "enabled": false, "threshold": 4, "minDistinctArguments": 3 }`. Threshold accepts integers 4–100; minDistinctArguments accepts integers 3–100. Both are minimums over a maximal sequential failure run, so the distinct minimum can exceed the call threshold. Unknown fields and non-integer/out-of-range values fail strict validation. Enable with [the opt-in example](../examples/argument-drift.config.json).

package/docs/detection-rules.md

@@ -11,7 +11,7 @@ Identity rules require recorded tool/operation identity (not an adapter display
 | AWI003 | Contiguous cycle length 2–6 repeating 3 times, at least two distinct fingerprints                | Shortest matching period wins; consumed cycles not rescanned                      |
 | AWI004 | 5 equivalent attempts in 30 seconds from first attempt, every prior attempt explicitly failed    | Retry intent inferred; successes, unknown status and slow attempts do not qualify |
 | AWI005 | More than 100 total operations OR observed depth over 20                                         | One trace-wide finding, not a tool-count limit; complexity is not a defect        |
-| AWI006 | Recorded usage or cost on implicated leaf operations from AWI001–004                             | Direct association only; no inferred price or unrelated model attribution         |
+| AWI006 | Recorded usage or cost on implicated leaf operations from AWI001–004 or enabled AWI007           | Direct association only; no inferred price or unrelated model attribution         |
 
 AWI001/002/004 use disjoint 100-call windows after segmentation; AWI004 accepts disjoint time groups within each fingerprint group, ending a retry chain at its first non-error outcome. Later attempts cannot erase an earlier qualifying storm. Boundary-spanning patterns may be missed. AWI003 scans the full eligible segment, with configurable length capped at 16. Single-fingerprint repetition is AWI001/002 rather than a cycle.
 
@@ -26,3 +26,13 @@ Summaries sum recorded leaf usage, excluding parent aggregates. Input/output/tot
 ## Limits
 
 16 MiB/file; 64 MiB aggregate CLI inputs; 256 files; 2,048 directory entries; directory depth 16; 50,000 total operations; 50,000 traces; JSON depth 64; 65,536 UTF-16 code units/string or key; 1,000,000 JSON values and a 64 MiB escaped-content budget per raw or normalized structure (shared values count per occurrence); 1,000 findings. Structural limits fail with exit 1. Default report data is subject to the same node/content budget before serialization; excessive evidence amplification fails with an explicit report-limit error rather than attempting unbounded output. Finding overflow returns complete:false, warning, exit 1 even with fail-on none. At most 100 fingerprint paths. Config schemas bound thresholds/windows/cycle lengths. A 50,000-span test uses a generous 15-second regression ceiling, not a cross-hardware benchmark claim.
+
+## AWI007: Repeated failure with argument drift
+
+Opt-in; medium severity, moderate confidence. Requires at least four consecutive eligible tool failures in one trace and parent, the same toolName (fallback name), an exactly matching nonblank explicit error code, and at least three distinct existing v1 fingerprints. No case folding or semantic argument comparison occurs. Fingerprint ignore paths apply. Missing arguments, unknown identity, missing/blank codes, success, unknown status, or a different tool/code interrupt a sequence. Non-tool siblings constrain timing but are projected out, as with existing sequence rules. Missing/zero-duration sibling timing excludes the sibling group; overlapping operations split runs and are excluded.
+
+One finding covers each maximal qualifying run, without sliding-window duplicates. Thresholds are minimum counts, not fixed window sizes. The scan adds linear time and memory after existing timing sorting, bounded by the 50,000-operation input limit and existing report budgets.
+
+AWI002 compares equivalent arguments and complete recorded error objects; AWI004 counts rapid equivalent attempts after failures within its time window. AWI007 requires varying fingerprints and a shared error code, without a retry-time window. Messages may differ and are never used by AWI007. Other rules may independently report the same operations; AWI006 can associate recorded leaf resources when AWI007 is enabled.
+
+Legitimate parameter exploration, validation attempts, pagination, and fallback strategies can match. Repeated recorded failures do not prove a lack of progress or reveal intent. Review the error code and retry policy before deciding whether to bound retries or escalate.

package/docs/getting-started.md

@@ -1,8 +1,49 @@
 # Getting started
 
-Install the Node/pnpm versions listed in README, then run `pnpm install --frozen-lockfile` and `pnpm check`. Only dependency installation needs network access.
+Use Node.js **22.18+ within 22.x, 24.11+ within 24.x, or 26.x** and **pnpm 11.25.0**, matching `package.json`. Check `node --version` and `pnpm --version` first. If pnpm is missing, install the pinned version with `npm install --global pnpm@11.25.0` using a supported Node version.
 
-Run `node dist/cli/index.js --help` and `node dist/cli/index.js inspect --help`. Try examples/healthy/basic.json for a clean result, examples/suspicious/retries.json for a finding, and examples/opentelemetry/tools.json for OTLP ingestion. AWI analyzes exports, not live executions.
+From a new checkout (PowerShell, macOS, or Linux shell):
+
+```sh
+git clone https://github.com/jigar48/awi.git
+cd awi
+pnpm install --frozen-lockfile
+pnpm build
+pnpm verify:quickstart
+```
+
+This uses the checked-out source, including the verifier added after v1.0.0; the original release tag does not contain that script. For a reproducible repeat, record `git rev-parse HEAD` and use that commit. Clone, toolchain setup, and dependency installation need network access; build, verification, and analysis run locally with no telemetry.
+
+Expected verification output:
+
+```text
+examples/healthy/basic.json: exit 0; rules none
+examples/suspicious/retries.json: exit 2; rules AWI002, AWI004, AWI006
+Quickstart verification passed.
+```
+
+The verifier runs the built CLI on synthetic, checked-in examples and itself exits 0 when both cases match. Rebuild after changing source. To run the CLI yourself:
+
+```sh
+node dist/cli/index.js --help
+node dist/cli/index.js inspect examples/healthy/basic.json
+node dist/cli/index.js inspect examples/suspicious/retries.json --format json
+node dist/cli/index.js inspect examples/opentelemetry/tools.json --input-format otel
+```
+
+The retry and OTLP examples intentionally exit 2 at the default high threshold; a shell/CI job may stop there. Exit 1 means an operational error or incomplete analysis. `--fail-on none` disables finding-based failure only. AWI analyzes exports, not live executions.
+
+For contributor checks, run `pnpm check` and `pnpm format:check`.
+
+For use outside this checkout, `agent-workflow-inspector@1.0.0` is [published on npm](https://www.npmjs.com/package/agent-workflow-inspector/v/1.0.0) (verified October 20, 2026):
+
+```sh
+npm install --global agent-workflow-inspector@1.0.0
+awi --version
+awi --help
+```
+
+Save the following synthetic example as `trace.json`, then run `awi inspect trace.json` (exit 0). Checkout-relative `examples/` and `dist/` paths apply only inside AWI's source repository.
 
 A minimal canonical trace is:
 

package/docs/limitations.md

@@ -9,3 +9,7 @@ Only recorded leaf resources are counted. Parent aggregates and unrelated model
 OTLP support is the documented subset, not every export/framework. Duplicate JSON keys are last-wins; numbers use double precision. Strings preserve large integers exactly. Timestamp ordering retains up to nanosecond precision; duration summaries use floating-point milliseconds.
 
 Windows and Ubuntu WSL checks do not establish macOS or hosted-runner compatibility; the full CI matrix must run. Regression timing is not a universal speed promise. Trusted directories remain required against concurrent replacement of parent components. Legitimate symlink paths, including package-manager aliases and some OS temporary paths, must be resolved to real paths before inspection. Report publication requires hard-link support. Opt-in key-based redaction is not general anonymization.
+
+AWI007 is disabled by default. Legitimate argument exploration and fallback attempts may produce the same code repeatedly. Fingerprint differences do not measure semantic change or progress; ignored paths can hide differences. Exact error-code equality can miss equivalent failures with different codes. Missing codes/arguments/status/timing can hide runs. AWI007 emits maximal runs rather than using the disjoint repetition windows of AWI001/002/004.
+
+AWI007 evidence contains the failure count, distinct fingerprint count and operation references. Its tool name and shared error code are used internally. `--show-content` can expose recorded identifiers, labels and argument content despite key-based redaction. See the [security and privacy documentation](security.md).

package/docs/releases/v1.0.0.md

@@ -1,6 +1,6 @@
 # Agent Workflow Inspector v1.0.0 — Deterministic AI Agent Trace Diagnostics
 
-Release notes prepared for approval. This version has not been published.
+Published on [GitHub](https://github.com/jigar48/awi/releases/tag/v1.0.0) October 19, 2026. [npm version 1.0.0](https://registry.npmjs.org/agent-workflow-inspector/1.0.0) confirmed October 20, 2026.
 
 Agent Workflow Inspector is a local-first, deterministic linter for AI agent execution traces. It highlights recorded patterns for investigation; it does not understand agent intentions or prove a workflow is stuck.
 
@@ -11,7 +11,7 @@ Agent Workflow Inspector is a local-first, deterministic linter for AI agent exe
 - CLI and ESM/TypeScript library, configurable thresholds, human-readable and structured JSON reports, stable evidence references and CI exit codes.
 - Local analysis without telemetry or an LLM. Input budgets, terminal escaping, symlink checks and exclusive output creation.
 
-## Install after publication
+## Install
 
 ```sh
 npm install --global agent-workflow-inspector@1.0.0
@@ -21,7 +21,7 @@ awi inspect trace.json --format json
 
 Requires Node 22.18+ (22.x), 24.11+ (24.x), or 26.x. Exit 0: completed below threshold; 1: invalid input, operational failure or incomplete analysis; 2: completed with findings meeting the configured threshold (high by default).
 
-The audited source passed 69 tests and nine hosted Windows/macOS/Linux × Node 22/24/26 jobs. The final release commit must pass a fresh matrix before publication; see the [verification record](https://github.com/jigar48/awi/blob/v1.0.0/docs/verification.md).
+The audited source passed 69 tests and nine hosted Windows/macOS/Linux × Node 22/24/26 jobs. These historical results do not validate later documentation or verification-script changes; see the [verification record](https://github.com/jigar48/awi/blob/v1.0.0/docs/verification.md).
 
 ## Privacy and limitations