gadriel 0.9.8

package/CHANGELOG.md

@@ -0,0 +1,290 @@
+# Changelog
+
+All notable changes to the **gadriel CLI** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Pre-1.0 versions may include breaking changes between minor versions; those are called out explicitly under a **⚠ Breaking** subsection.
+
+> **Note:** the CLI version is intentionally decoupled from the broader Preflight workspace version (currently 0.2.1). This file tracks only the CLI's user-visible behavior.
+
+---
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+---
+
+## [0.9.8] — 2026-05-28
+
+### Fixed
+
+- **Build Intel macOS on an Apple-Silicon runner.** GitHub's Intel
+  macOS runners (`macos-13`) are being deprecated and are effectively
+  unavailable — in the v0.9.7 run the `x86_64-apple-darwin` job sat
+  queued for **7.5 hours** without ever getting a runner, while the
+  other 4 targets built green. Switched that matrix entry to the
+  plentiful `macos-14` (Apple Silicon) runner and cross-compile to
+  `x86_64-apple-darwin` (the Apple clang toolchain is a universal
+  cross-compiler; rustup installs the x86_64 std). Produces a genuine
+  Intel binary without depending on scarce Intel runners.
+
+### Note about 0.9.7
+
+v0.9.7 was tagged but never published. All five binaries are now
+buildable (Windows + both Linux + macOS arm64 all went green; the
+Intel-Mac binary just couldn't get a runner). 0.9.8 routes the Intel
+build to an available runner.
+
+---
+
+## [0.9.7] — 2026-05-28
+
+### Fixed
+
+- **Release pipeline — portable sha256 in artifact staging.** With all
+  cross-compile bugs fixed in 0.9.6, the Windows binary finally built
+  (50 min — vendored OpenSSL from source) but the run failed in the
+  `Stage artifact` step: `shasum: command not found`. Git-Bash on
+  windows-2022 ships `sha256sum` but not `shasum`; macOS ships `shasum`
+  but not `sha256sum`. The workflow now prefers `sha256sum` and falls
+  back to `shasum -a 256`, covering all three OSes.
+
+### Note about 0.9.6
+
+v0.9.6 was tagged but never published. It proved every cross-compile
+fix worked — Linux x64/arm64 + macOS arm64 built green, the Windows
+binary compiled successfully — but the sha256 sidecar step used a
+command absent from Git-Bash. 0.9.7 is purely that one-line fix.
+
+---
+
+## [0.9.6] — 2026-05-28
+
+### Fixed
+
+- **macOS builds — patch `rvf-runtime`'s glibc-only errno symbol.**
+  `rvf-runtime 0.2.0/src/locking.rs` declared `__errno_location` in an
+  `extern "C"` block gated on `#[cfg(unix)]`. That symbol exists on
+  glibc/musl Linux but NOT on macOS (errno lives behind `__error`),
+  so macOS release builds failed at link time with
+  `Undefined symbols for architecture arm64: ___errno_location`.
+  Fixed by vendoring `rvf-runtime` under `vendor/rvf-runtime` (wired
+  via `[patch.crates-io]`) and replacing the hand-rolled extern with
+  the portable `std::io::Error::last_os_error()`. Remove the patch
+  once the fix lands upstream (>= 0.2.1).
+
+- **Windows builds — use Strawberry Perl for vendored OpenSSL.**
+  `webauthn-rs-core` pulls vendored OpenSSL (`openssl-src`), whose
+  build runs `perl ./Configure`. On windows-2022 the bash shell is
+  Git-Bash, which puts a minimal MSYS perl first on PATH — it lacks
+  `Locale::Maketext::Simple` / `Text::Template`, so Configure died
+  with exit code 2. The release workflow now sets
+  `OPENSSL_SRC_PERL=C:/Strawberry/perl/bin/perl.exe` on Windows runners.
+
+### Note about 0.9.5
+
+v0.9.5 was tagged but never published. The workspace native-tls strip
+(below) fixed Linux x64 + arm64, but macOS (rvf-runtime errno) and
+Windows (openssl-src perl) each had a further platform bug, both fixed
+in 0.9.6.
+
+---
+
+## [0.9.5] — 2026-05-27
+
+### Fixed
+
+- **Cross-compile reliability — strip `native-tls` workspace-wide**
+  (the biome / swc / rolldown pattern). The cli-v0.9.4 release run
+  produced working Linux binaries but failed on macOS arm64 and
+  Windows because vendoring OpenSSL from source is fragile on those
+  platforms. Root cause: `reqwest`'s default-tls feature pulled
+  `native-tls` → `openssl-sys`, and `fastembed` explicitly opted into
+  `hf-hub-native-tls`. Fixed by:
+    - Setting `default-features = false` + adding `rustls-tls` to
+      every workspace `reqwest` declaration (workspace root + 9
+      individual crates).
+    - Switching `preflight-embeddings`'s `fastembed` feature from
+      `hf-hub-native-tls` to `hf-hub-rustls-tls`.
+    - Switching `sqlx`'s `runtime-tokio-native-tls` →
+      `runtime-tokio-rustls` in `preflight-auth-service`,
+      `preflight-docs`, and `infrastructure/provisioning-api`.
+    - Switching `lettre`'s `tokio1-native-tls` → `tokio1-rustls-tls`
+      in `preflight-api` and `infrastructure/provisioning-api`.
+    - Disabling `webauthn-rs`'s default `attestation` feature where
+      possible (attestation APIs aren't called by any code in the
+      workspace).
+
+  Result: `cargo tree -p gadriel-cli --invert native-tls` returns
+  empty. The only remaining `openssl-sys` consumer is
+  `webauthn-rs-core` (which hardcodes a non-optional openssl dep),
+  forced to vendored mode via a single `openssl = { features =
+  ["vendored"] }` line in `gadriel-cli/Cargo.toml`. That smaller
+  openssl footprint (just webauthn cert parsing, no TLS) is what
+  should let the vendored build succeed on Mac/Windows where it
+  previously failed building the full stack.
+
+### Note about 0.9.4
+
+v0.9.4 was tagged but never published — the workflow built linux-x64
++ linux-arm64 successfully (Cargo.lock fix worked) but failed on
+macOS / Windows because of the deeper native-tls problem fixed here.
+
+---
+
+## [0.9.4] — 2026-05-27
+
+### Fixed
+
+- **Release tooling** — `scripts/release/bump-cli.sh` now refreshes
+  `Cargo.lock` after bumping the crate version (via
+  `cargo update -p gadriel-cli --precise <new> --offline`). Without
+  this, every CI build using `cargo build --locked` would fail with
+  `cannot update the lock file ... because --locked was passed` —
+  which is exactly what blocked v0.9.3.
+
+### Note about 0.9.3
+
+v0.9.3 was tagged but never published — Cargo.lock referenced the old
+crate version, and CI's `cargo build --locked` refused to update it.
+0.9.4 fixes the bump script so this won't happen again.
+
+---
+
+## [0.9.3] — 2026-05-27
+
+### Fixed
+
+- **Release pipeline** — removed a bogus gitlink at
+  `examples/ai-hedge-fund/repo` (mode 160000) that had no corresponding
+  `.gitmodules` entry. Modern `actions/checkout@v4` treats this as a
+  fatal error (`fatal: No url found for submodule path 'examples/
+  ai-hedge-fund/repo' in .gitmodules`), which blocked **every** matrix
+  job from progressing past checkout. The inconsistent state has lived
+  on `main` since 2026-03-03 — older actions/checkout was lenient.
+
+### Note about 0.9.2
+
+v0.9.2 was tagged but never published — the checkout-step failure
+above prevented any binary from building. 0.9.3 is the first
+release that actually ships.
+
+---
+
+## [0.9.2] — 2026-05-27
+
+### Fixed
+
+- **Cross-compile reliability** — added `openssl = { features = ["vendored"] }` to
+  `crates/gadriel-cli/Cargo.toml`. A transitive workspace dependency was pulling
+  in `openssl-sys`, which broke the 4 non-linux-x64 release matrix runners
+  (no system OpenSSL available for Windows, macOS, and linux-arm64). The
+  vendored feature makes `openssl-sys` compile OpenSSL from source as part
+  of the build — works on every platform, adds ~5 MB to the binary and
+  ~2 min to the build.
+
+### Note about 0.9.1
+
+v0.9.1 was tagged (`cli-v0.9.1`) but **never published to npm or GitHub
+Releases** — the multi-platform build matrix failed on the openssl-sys
+issue above. 0.9.2 is the first version with a working release artifact.
+
+---
+
+## [0.9.1] — 2026-05-27
+
+First publicly distributed release. The CLI moves from "internal workspace tool"
+to "installable end-user product." Everything below is what makes that
+possible; the underlying feature surface (code-security scanning, AI-agent
+testing, MCP server) has been baking internally for many iterations.
+
+### Added
+
+- **npm distribution** via the `optionalDependencies` pattern (same as esbuild
+  / swc / biome / turbo). One install command — `npm install -g gadriel` —
+  picks the right prebuilt binary for the host OS+arch automatically.
+- **Five prebuilt platform binaries** published as scoped npm packages:
+  - `@gadriel/cli-linux-x64`
+  - `@gadriel/cli-linux-arm64`
+  - `@gadriel/cli-darwin-x64`
+  - `@gadriel/cli-darwin-arm64`
+  - `@gadriel/cli-win32-x64`
+- **GitHub Releases pipeline** (`.github/workflows/cli-release.yml`) that
+  cross-compiles all five targets on every `cli-v*` tag, attaches tarballs
+  + matching `.sha256` sidecars to a GitHub Release, then atomically
+  publishes all six npm packages.
+- **Comprehensive README** (`crates/gadriel-cli/README.md`) covering install,
+  quick start, command reference, output formats, configuration, CI/CD
+  integration, privacy model, performance, and troubleshooting.
+- **Operator runbook** at `docs/runbooks/cli-release.md` documenting the
+  release process (one-time setup, per-release steps, dry-run, rollback).
+- **Version-bump helper** at `scripts/release/bump-cli.sh` that updates all
+  7 manifests in one shot (Cargo.toml + 6 npm package.json files).
+
+### Changed
+
+- ⚠ **Versioning** — `gadriel-cli` is now detached from the workspace
+  version. Previously it inherited `version.workspace = true` and tracked
+  the engine version (0.2.1). Going forward the CLI has its own
+  user-facing version (0.9.1+), and the npm packages mirror it exactly.
+- **README** — replaced the stale `preflight-cli` README with a
+  user-oriented one. The old README pre-dated the rename + code-security
+  surface and no longer described how the tool actually worked.
+- **`gadriel --version`** now reports 0.9.1 (previously 0.2.1, matching the
+  workspace).
+
+### Notes
+
+- macOS binaries are **not yet Apple-notarized**. First-run Gatekeeper
+  prompt is expected; the README documents the `xattr -d` workaround.
+  Notarization is on the v1.0 milestone (requires Apple Developer ID).
+- Windows binaries are **not yet code-signed**. SmartScreen will warn on
+  first run; click "More info → Run anyway". Also on the v1.0 milestone.
+- `linux-musl`, FreeBSD, and Windows ARM are **build-from-source only**.
+
+---
+
+## Pre-history (0.1.0 – 0.8.x)
+
+These versions never had a public binary release. The CLI evolved
+internally as part of the Preflight monorepo through many waves of
+work; the most user-relevant landmarks were:
+
+- **0.8.x** — Code-security surface stabilized: `gadriel code init/scan/
+  findings/watch/sbom/report/dashboard/policies/store/mcp` shipped.
+  Ruby/Rails SAST extractor + 31-rule pack (iter-33). RVF World-Class
+  HTML reports.
+- **0.7.x** — Beta-program portal integration (`gadriel auth login`,
+  30-day token rotation, OS-keyring storage).
+- **0.6.x** — MCP server (`gadriel code mcp`) for Claude Code / Cursor
+  integration via JSON-RPC 2.0.
+- **0.5.x** — Layer 1 file-save watcher (300ms debounced, per-file SAST
+  + secrets), license-gate enforcement (ADR-085), privacy-by-default
+  model (ADR-090).
+- **0.4.x** — `.claude/` scaffold: slash-commands (gadriel-fix,
+  gadriel-scan, gadriel-watch, gadriel-status, gadriel-reports),
+  reviewer agents (security, compliance, safety, bias, coherence,
+  operational, finops, teamwork), 20+ Claude Code skills.
+- **0.3.x** — SBOM generation (SPDX 2.3 + CycloneDX 1.4 per ADR-084),
+  per-framework compliance reports (OWASP LLM Top-10, NIST AI RMF, EU
+  AI Act per ADR-085).
+- **0.2.x** — Initial code-security surface alongside the original
+  AI-agent testing surface (scan, target, plan, scenario, run,
+  remediate, explain, doctor, dashboard).
+- **0.1.x** — Renamed from `preflight-cli` to `gadriel-cli`, with the
+  user-visible binary becoming `gadriel`.
+
+For full git history of any of the above, see `git log
+crates/gadriel-cli/` in the [Preflight
+repository](https://github.com/Gadriel-ai/preflight).
+
+---
+
+[Unreleased]: https://github.com/Gadriel-ai/preflight/compare/cli-v0.9.1...HEAD
+[0.9.1]: https://github.com/Gadriel-ai/preflight/releases/tag/cli-v0.9.1

package/README.md

@@ -0,0 +1,598 @@
+# gadriel
+
+> **Code-security scanning + AI-agent testing CLI** — built for projects where humans and coding agents commit side-by-side.
+
+Gadriel finds vulnerabilities, exposed secrets, license issues, and AI-specific risks (prompt injection, taint flows, agent contract violations) in any codebase. It also runs adversarial test plans against live AI agents to catch behavior issues *before* they reach production.
+
+Everything runs **locally**. Source code never leaves your machine. See [Privacy & data handling](#privacy--data-handling).
+
+[![npm](https://img.shields.io/npm/v/gadriel.svg)](https://www.npmjs.com/package/gadriel)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows-lightgrey.svg)](#supported-platforms)
+
+---
+
+## Table of contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Authentication](#authentication)
+- [What gadriel does](#what-gadriel-does)
+- [Command reference](#command-reference)
+- [Output formats](#output-formats)
+- [Configuration](#configuration)
+- [CI/CD integration](#cicd-integration)
+- [Privacy & data handling](#privacy--data-handling)
+- [Performance](#performance)
+- [Supported platforms](#supported-platforms)
+- [Troubleshooting](#troubleshooting)
+- [Versioning & support](#versioning--support)
+- [License](#license)
+
+---
+
+## Install
+
+### Via npm (recommended)
+
+```bash
+npm install -g gadriel
+```
+
+Or run once without installing:
+
+```bash
+npx gadriel code scan .
+```
+
+npm picks the right prebuilt binary for your OS+arch automatically (via the `optionalDependencies` pattern). 5 platforms supported out of the box — see [Supported platforms](#supported-platforms).
+
+### Via cargo
+
+```bash
+git clone https://github.com/Gadriel-ai/preflight && cd preflight
+cargo install --path crates/gadriel-cli
+```
+
+Requires Rust 1.87+. Useful if you're on a platform we don't prebuild for (e.g. linux-musl, freebsd), or if you want to hack on the CLI itself.
+
+### From a release tarball
+
+Every release publishes binaries to [GitHub Releases](https://github.com/Gadriel-ai/preflight/releases) with matching `.sha256` sidecars:
+
+```bash
+curl -sLo gadriel.tar.gz https://github.com/Gadriel-ai/preflight/releases/download/cli-v0.9.1/gadriel-0.9.1-linux-x64.tar.gz
+curl -sLo gadriel.tar.gz.sha256 https://github.com/Gadriel-ai/preflight/releases/download/cli-v0.9.1/gadriel-0.9.1-linux-x64.tar.gz.sha256
+shasum -a 256 -c gadriel.tar.gz.sha256
+tar xzf gadriel.tar.gz && sudo mv gadriel /usr/local/bin/
+```
+
+---
+
+## Quick start
+
+### 1. Initialize gadriel in your project
+
+```bash
+cd path/to/your/repo
+gadriel code init
+```
+
+This scaffolds:
+
+- `.security/` — local findings store (gitignored by default)
+- `.claude/` — Claude Code slash-commands + reviewer agents + skills
+- `.gadriel/config.toml` — project-level overrides
+- Optional pre-commit hook that runs `gadriel code scan` on staged files
+
+### 2. Run your first scan
+
+```bash
+gadriel code scan .
+```
+
+Output (abbreviated):
+
+```
+Scanning ./my-app ...
+  ⚠ 12 findings (3 critical, 5 high, 4 medium)
+  ⚠ 2 secrets exposed (AWS_ACCESS_KEY_ID at src/config/aws.ts:14)
+  ⚠ 1 license violation (GPL-3.0 in transitive dep "foo-lib")
+  ✓ SBOM generated → .security/sbom.spdx.json
+  ✓ Report  → .security/findings.json
+```
+
+### 3. Triage findings
+
+```bash
+# Browse findings interactively
+gadriel code findings
+
+# Or as JSON for scripting
+gadriel code findings --format json | jq '.[] | select(.severity == "critical")'
+
+# Mark a finding as a false positive (writes to .security/triage.json)
+gadriel code fix FIND-AB12CD --dismiss "fp: test fixture, not prod code"
+```
+
+### 4. Generate compliance artifacts
+
+```bash
+# Software Bill of Materials (SPDX 2.3 + CycloneDX 1.4)
+gadriel code sbom --format spdx > sbom.spdx.json
+gadriel code sbom --format cyclonedx > sbom.cyclonedx.json
+
+# Per-framework compliance report (Markdown, with --pdf for typst PDF source)
+gadriel code report --framework owasp-llm-top10
+gadriel code report --framework nist-ai-rmf --pdf
+```
+
+---
+
+## Authentication
+
+Most commands work fully offline. Gadriel only contacts the control plane (`app.gadriel.ai`) for:
+
+- **License-gate verification** — one HEAD request per scan that asks "is this license still valid?". The request includes no source code, no findings, no file paths.
+- **Sync** — `gadriel sync` uploads findings to your portal account *if you opt in*; off by default.
+
+### Sign in
+
+```bash
+gadriel login
+# or, for the new beta-program portal:
+gadriel auth login
+```
+
+Either opens `https://app.gadriel.ai/beta/login` in your browser. After you sign in, gadriel mints a 30-day API token and stores it in your OS keyring (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
+
+### Check status
+
+```bash
+gadriel status
+```
+
+```
+gadriel 0.9.1
+  Logged in:    farshid@gadriel.ai
+  Portal:       https://app.gadriel.ai
+  Token expires: 2026-06-26 (30 days)
+  License:      Active (Pro, seat #1)
+  Last sync:    2 hours ago
+```
+
+### Sign out
+
+```bash
+gadriel logout
+```
+
+Wipes the token from your keyring.
+
+---
+
+## What gadriel does
+
+Gadriel has **two distinct scanning surfaces**. Most users only need the first.
+
+### 1. Code security (`gadriel code …`)
+
+Static analysis of your repository. Catches:
+
+| Category | Examples |
+|---|---|
+| **SAST** | SQL injection, XSS, command injection, path traversal, deserialization (Java/Python/Ruby/Go/JS), Rails-specific (mass assignment, unsafe `send`), 31-rule Ruby/Rails pack |
+| **SCA** | Vulnerable dependencies (OSV.dev integration), transitive risks |
+| **Secrets** | AWS/GCP/Azure keys, GitHub PATs, Slack webhooks, JWT secrets, API keys, ~80 patterns |
+| **AI-specific** | Prompt-injection sinks in agent code, taint flows through LLM APIs, agent-contract violations (A2A), output-schema drift |
+| **License** | Copyleft contamination, license incompatibility across deps, ADR-085 license-gate enforcement |
+| **Config** | Dockerfile best practices, Kubernetes hardening, `.env` exposure, CI/CD misconfig |
+| **API** | OpenAPI/AsyncAPI contract violations, missing auth, overly permissive CORS |
+
+### 2. AI agent testing (`gadriel scan`, `gadriel run`, `gadriel scenario …`)
+
+Run adversarial test plans against **live AI agents**. Catches:
+
+- Jailbreaks and prompt-injection escalations
+- Output-format violations (JSON schema drift, missing required fields)
+- Cost / token-budget runaways
+- Bias, safety, and compliance issues (OWASP LLM Top-10, NIST AI RMF, EU AI Act mappings)
+- Latency regressions
+
+```bash
+gadriel scan https://api.your-agent.com --type llm
+gadriel run my-test-plan --target https://api.your-agent.com
+gadriel scenario list --framework owasp-llm-top10
+```
+
+This surface is more advanced. The [docs site](https://docs.gadriel.ai) covers it in depth.
+
+---
+
+## Command reference
+
+The CLI groups commands into three tiers. The full `gadriel --help` lists everything.
+
+### Tier 1 — daily-use commands
+
+| Command | What it does |
+|---|---|
+| `gadriel code init` | Scaffold `.security/`, `.claude/`, hooks, MCP config in this repo |
+| `gadriel code scan [path]` | Run code-security scan (SAST + SCA + secrets + license) |
+| `gadriel code findings` | Read/filter `.security/findings.json` |
+| `gadriel code watch` | Background file-save validator (300ms debounced, per-file scans) |
+| `gadriel code fix <id>` | Confirm, dismiss, or hand off a finding to an AI agent for fix |
+| `gadriel code sbom` | Export SPDX 2.3 + CycloneDX 1.4 SBOM |
+| `gadriel code report` | Per-framework compliance report (Markdown / HTML / PDF) |
+| `gadriel code dashboard` | Local-only web dashboard at `127.0.0.1` |
+| `gadriel login` / `gadriel logout` | Auth |
+| `gadriel status` | Show auth + sync state |
+| `gadriel doctor` | Diagnose issues (paths, perms, network, configs) |
+
+### Tier 2 — AI agent testing
+
+| Command | What it does |
+|---|---|
+| `gadriel scan <url>` | Quick scan with built-in scenarios (auto-detects target type) |
+| `gadriel quicktest` | Run a single scenario for debugging |
+| `gadriel target` | Manage configured agent endpoints |
+| `gadriel plan` | Manage saved test plans |
+| `gadriel scenario` | Browse / validate / run individual scenarios |
+| `gadriel run <plan-id>` | Execute a multi-scenario plan |
+| `gadriel report` | View scan reports |
+| `gadriel explain <finding-id>` | LLM-narrated explanation of a finding |
+| `gadriel remediate <finding-id>` | Generate remediation plan |
+
+### Tier 3 — meta / advanced
+
+| Command | What it does |
+|---|---|
+| `gadriel init` | Initialize a new gadriel project (root-level config) |
+| `gadriel config` | Read/write `gadriel.toml` |
+| `gadriel profile` | Switch between named auth/portal profiles |
+| `gadriel composition` | Manage multi-agent compositions |
+| `gadriel sync` | Push pending results to portal |
+| `gadriel update` | Self-update (no-op on npm installs; use `npm update -g gadriel`) |
+| `gadriel completion [shell]` | Generate bash/zsh/fish/powershell completions |
+| `gadriel hooks` | Claude Code hook dispatcher (invoked by `.claude/settings.json`) |
+| `gadriel version` | Print version + build info |
+| `gadriel code mcp` | Start MCP JSON-RPC server (for Claude Code / Cursor integrations) |
+| `gadriel code store` | RVF substrate ops (advanced; per-machine + per-repo data stores) |
+| `gadriel code policies` | Manage GVL rule corpus + OSV advisory snapshots |
+
+Every command supports:
+
+- `--json` — machine-readable output (overrides `--format`)
+- `--quiet` / `-q` — minimal output for CI
+- `--verbose` / `-v` — more detail
+- `--no-color` — for log files
+- `--config <path>` — use a specific config file
+- `--portal <url>` — override portal URL (for self-hosted deployments)
+
+---
+
+## Output formats
+
+Pick the right format for your downstream consumer.
+
+| Format | Flag | Use case |
+|---|---|---|
+| Terminal (default) | (none) | Human-readable, color-coded, with severity icons |
+| JSON | `--json` | Pipe to `jq`, post to Slack, ingest into Splunk |
+| SARIF 2.1.0 | `--format sarif` | GitHub Code Scanning, Azure DevOps |
+| SPDX 2.3 | `gadriel code sbom --format spdx` | SBOM ingestion (most enterprise tooling) |
+| CycloneDX 1.4 | `gadriel code sbom --format cyclonedx` | OWASP-aligned SBOM |
+| Markdown | `gadriel code report` | Human-readable compliance docs, GitHub Wiki |
+| HTML | `gadriel code report --html` | Static RVF World-Class bundle for portal/CI hosting |
+| PDF (typst source) | `gadriel code report --pdf` | Compliance evidence packs; render with `typst compile` |
+
+### SARIF for GitHub Code Scanning
+
+```yaml
+- run: gadriel code scan --format sarif > results.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+Findings appear in the **Security → Code scanning** tab.
+
+---
+
+## Configuration
+
+Configuration is layered (later overrides earlier):
+
+1. **Built-in defaults**
+2. **`~/.config/gadriel/config.toml`** — user-wide
+3. **`./gadriel.toml`** or **`./.gadriel/config.toml`** — project-level
+4. **Environment variables** (`GADRIEL_PORTAL`, `GADRIEL_NO_TELEMETRY`, etc.)
+5. **CLI flags** (highest priority)
+
+### Project config example
+
+```toml
+# .gadriel/config.toml
+
+[scan]
+ignore_paths = ["target/", "node_modules/", "vendor/"]
+fail_on = "high"          # exit non-zero if any finding ≥ this severity
+max_file_size_mb = 5
+
+[secrets]
+allowlist = [
+  "EXAMPLE_API_KEY=changeme",  # demo fixture; safe to commit
+]
+
+[license]
+disallow = ["GPL-3.0-only", "AGPL-3.0-only"]
+warn_on  = ["LGPL-2.1-only"]
+
+[code.sbom]
+format = "spdx"           # default for `gadriel code sbom`
+include_dev_deps = false
+
+[portal]
+url = "https://app.gadriel.ai"
+profile = "default"
+
+[telemetry]
+enabled = false           # opt-in, off by default
+```
+
+### Setting values
+
+```bash
+gadriel config set scan.fail_on critical
+gadriel config get scan.fail_on
+gadriel config list
+gadriel config unset secrets.allowlist
+```
+
+### Environment variables
+
+| Variable | What it does |
+|---|---|
+| `GADRIEL_PORTAL` | Override portal URL (for self-hosted) |
+| `GADRIEL_TOKEN` | Use this API token instead of the keyring (for CI) |
+| `GADRIEL_CONFIG` | Path to config file |
+| `GADRIEL_NO_TELEMETRY` | Force-disable telemetry regardless of config |
+| `GADRIEL_LOG` | Log level (`error`, `warn`, `info`, `debug`, `trace`) |
+| `NO_COLOR` | Disable ANSI colors (standard convention) |
+
+---
+
+## CI/CD integration
+
+### GitHub Actions
+
+```yaml
+name: Gadriel security scan
+on: [push, pull_request]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write   # for SARIF upload
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install gadriel
+        run: npm install -g gadriel
+      - name: Scan
+        env:
+          GADRIEL_TOKEN: ${{ secrets.GADRIEL_TOKEN }}
+        run: gadriel code scan --format sarif > results.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
+```
+
+### GitLab CI
+
+```yaml
+gadriel-scan:
+  image: node:20
+  script:
+    - npm install -g gadriel
+    - gadriel code scan --format json > gl-sast-report.json
+  artifacts:
+    reports:
+      sast: gl-sast-report.json
+  variables:
+    GADRIEL_TOKEN: $GADRIEL_TOKEN
+```
+
+### Jenkins
+
+```groovy
+pipeline {
+  agent any
+  stages {
+    stage('Gadriel scan') {
+      steps {
+        sh 'npm install -g gadriel'
+        withCredentials([string(credentialsId: 'gadriel-token', variable: 'GADRIEL_TOKEN')]) {
+          sh 'gadriel code scan --format sarif > results.sarif'
+        }
+        recordIssues tools: [sarif(pattern: 'results.sarif')]
+      }
+    }
+  }
+}
+```
+
+### Pre-commit hook
+
+`gadriel code init` offers to install one. Manually:
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/sh
+gadriel code scan --staged --quiet --fail-on critical
+```
+
+---
+
+## Privacy & data handling
+
+Gadriel is **privacy-by-default** ([ADR-090](https://github.com/Gadriel-ai/preflight/blob/main/docs/adr/ADR-090-privacy-by-default.md)).
+
+**What stays on your machine:**
+- Source code (always)
+- Findings (`.security/findings.json`, local files)
+- SBOMs (local files)
+- File paths, function names, identifiers
+- Logs
+
+**What leaves your machine (and when):**
+
+| Event | What's sent | To where |
+|---|---|---|
+| `gadriel login` | OAuth flow only | `app.gadriel.ai` |
+| Every scan | License-gate HEAD request: `{ token, license_id }` | `app.gadriel.ai/api/v1/license/verify` |
+| `gadriel sync` (opt-in) | Findings (you control what; default = nothing) | Your portal account |
+| Telemetry (opt-in, off by default) | Aggregate counters: scan count, command names, exit codes, latency buckets | `app.gadriel.ai/api/v1/telemetry` |
+
+No CDNs. No third-party trackers. No source code shipping anywhere, ever. The [ADR-090 doc](https://github.com/Gadriel-ai/preflight/blob/main/docs/adr/ADR-090-privacy-by-default.md) covers the threat model in detail.
+
+### Air-gapped mode
+
+```bash
+export GADRIEL_OFFLINE=true
+gadriel code scan .
+```
+
+Skips license-gate, telemetry, and any control-plane I/O. Requires a previously-fetched license cache (`gadriel auth refresh` while online).
+
+---
+
+## Performance
+
+Numbers from a 2024 MacBook Pro M3 Pro / linux x64 (i7-12700K, NVMe):
+
+| Codebase | Files | Scan time (cold) | Scan time (warm) |
+|---|---|---|---|
+| Small (1k LOC, Python) | 12 | 0.4s | 0.1s |
+| Medium (50k LOC, monorepo) | 1,250 | 8s | 2s |
+| Large (500k LOC, polyglot) | 12,000 | 45s | 12s |
+| RVF substrate full-scan | 50,000 | 3m | 35s |
+
+Warm runs use the `.gadriel/cache/` graph store + incremental file-hash diffing. Cold runs build the whole codebase graph from scratch.
+
+`gadriel code watch` runs sub-300ms per file save (SAST + secrets only; SBOM / SCA happen on full scans).
+
+---
+
+## Supported platforms
+
+| OS | Architecture | npm package | Status |
+|---|---|---|---|
+| Linux | x86_64 | `@gadriel/cli-linux-x64` | ✅ stable |
+| Linux | aarch64 | `@gadriel/cli-linux-arm64` | ✅ stable |
+| macOS | x86_64 (Intel) | `@gadriel/cli-darwin-x64` | ✅ stable |
+| macOS | aarch64 (Apple Silicon) | `@gadriel/cli-darwin-arm64` | ✅ stable |
+| Windows | x86_64 | `@gadriel/cli-win32-x64` | ✅ stable |
+| Linux | x86_64 (musl) | — | 🛠 build from source (`cargo install`) |
+| FreeBSD | x86_64 | — | 🛠 build from source |
+| Windows | aarch64 | — | 🛠 build from source |
+
+For unsupported platforms, build from source — see [Install via cargo](#via-cargo).
+
+---
+
+## Troubleshooting
+
+### `gadriel: command not found` after `npm install -g`
+
+Either your npm global `bin` directory isn't on `PATH`, or the optional platform package was skipped. Check:
+
+```bash
+npm config get prefix    # global bin lives in $PREFIX/bin
+echo $PATH | tr ':' '\n' | grep -i npm
+```
+
+If `optionalDependencies` was skipped (common with corporate npm mirrors or `--no-optional`):
+
+```bash
+npm install -g gadriel --include=optional --force
+```
+
+### "platform package was not installed"
+
+Same root cause as above — fix with `--include=optional`. The shim's error message will tell you the exact platform package name.
+
+### macOS Gatekeeper: "cannot be opened because the developer cannot be verified"
+
+The current beta binaries are not yet Apple-notarized (tracked for v1.0). Workaround:
+
+```bash
+xattr -d com.apple.quarantine "$(which gadriel)"
+```
+
+Or via UI: **System Settings → Privacy & Security → "Allow Anyway"** after the first failed launch.
+
+### Windows SmartScreen: "Windows protected your PC"
+
+Same root cause — binary isn't yet signed with a CA-issued cert. Click **More info → Run anyway**. Tracked for v1.0.
+
+### `gadriel doctor` reports issues
+
+`doctor` is the diagnostic tool — run it first whenever something feels wrong:
+
+```bash
+gadriel doctor
+```
+
+It checks: PATH, OS keyring access, portal connectivity, license validity, write perms to `.security/`, `.claude/` integration, MCP server health, cache integrity.
+
+### Scan is slow on the first run
+
+That's normal — the cold scan builds the full codebase graph. Subsequent scans use the incremental cache and are ~5–10× faster. Force a rebuild with:
+
+```bash
+gadriel code scan --no-cache
+# or wipe the cache and start fresh:
+rm -rf .gadriel/cache/ && gadriel code scan .
+```
+
+### `gadriel sync` says "license expired"
+
+Your portal token expired (30-day rotation by default):
+
+```bash
+gadriel login
+```
+
+Re-mints a token and stores it in the keyring.
+
+### Issue not covered here?
+
+- Run `gadriel doctor` and paste the output.
+- Search [open issues](https://github.com/Gadriel-ai/preflight/issues).
+- File a new issue with the doctor output + repro steps.
+
+---
+
+## Versioning & support
+
+- **Current version:** 0.9.1 — see [CHANGELOG.md](./CHANGELOG.md) for release history.
+- **Versioning policy:** [SemVer](https://semver.org/). Pre-1.0 releases may include breaking changes between minor versions; the CHANGELOG calls them out explicitly.
+- **Support window:** the last 2 minor versions receive security patches. Older versions are best-effort.
+- **Release cadence:** roughly monthly minor releases, ad-hoc patches.
+
+### Getting help
+
+- **Documentation:** [docs.gadriel.ai](https://docs.gadriel.ai)
+- **Issues / bugs / feature requests:** [GitHub Issues](https://github.com/Gadriel-ai/preflight/issues)
+- **Beta program:** [app.gadriel.ai/beta](https://app.gadriel.ai/beta) (request access)
+- **Security disclosures:** `security@gadriel.ai` (please don't open public issues for vulns)
+
+---
+
+## License
+
+MIT — see [LICENSE](https://github.com/Gadriel-ai/preflight/blob/main/LICENSE).
+
+Copyright © Gadriel team.

package/bin/gadriel.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Gadriel CLI launcher.
+//
+// At install time, npm picks exactly one of the five
+// `@gadriel/cli-<platform>-<arch>` packages declared as
+// optionalDependencies — the one whose `os` + `cpu` fields in its
+// package.json match the host. This shim resolves that package, finds
+// its bundled binary, and execs it with stdio inherited.
+
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { platform, arch, exit, argv, env } from "node:process";
+
+const require = createRequire(import.meta.url);
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// Map Node's platform/arch to our npm-package suffix. Anything outside
+// the matrix here is genuinely unsupported (e.g. linux-mips, freebsd).
+const SUPPORTED = {
+  "linux-x64":     { pkg: "@gadriel/cli-linux-x64",     ext: ""    },
+  "linux-arm64":   { pkg: "@gadriel/cli-linux-arm64",   ext: ""    },
+  "darwin-x64":    { pkg: "@gadriel/cli-darwin-x64",    ext: ""    },
+  "darwin-arm64":  { pkg: "@gadriel/cli-darwin-arm64",  ext: ""    },
+  "win32-x64":     { pkg: "@gadriel/cli-win32-x64",     ext: ".exe" },
+};
+
+const key = `${platform}-${arch}`;
+const target = SUPPORTED[key];
+
+if (!target) {
+  console.error(
+    `gadriel: unsupported platform "${key}". Supported: ${Object.keys(SUPPORTED).join(", ")}.\n` +
+      `If you need this platform, please open an issue:\n` +
+      `  https://github.com/Gadriel-ai/preflight/issues`
+  );
+  exit(1);
+}
+
+// Resolve the platform package's directory by asking Node for its
+// package.json — works whether npm hoisted it or kept it nested.
+let pkgRoot;
+try {
+  const pkgJson = require.resolve(`${target.pkg}/package.json`);
+  pkgRoot = dirname(pkgJson);
+} catch (e) {
+  console.error(
+    `gadriel: platform package "${target.pkg}" was not installed.\n` +
+      `\n` +
+      `This usually means npm skipped optionalDependencies. Re-install with:\n` +
+      `  npm install gadriel --include=optional\n` +
+      `\n` +
+      `Or install the platform package directly:\n` +
+      `  npm install -g ${target.pkg}\n`
+  );
+  exit(1);
+}
+
+const binPath = join(pkgRoot, "bin", `gadriel${target.ext}`);
+if (!existsSync(binPath)) {
+  console.error(
+    `gadriel: binary missing at ${binPath}.\n` +
+      `Reinstall: npm install -g gadriel --force --include=optional`
+  );
+  exit(1);
+}
+
+// Exec the binary with the user's args. stdio inherited so prompts /
+// progress bars / colors work normally. spawnSync returns control with
+// the child's exit code, which we propagate.
+const result = spawnSync(binPath, argv.slice(2), {
+  stdio: "inherit",
+  env,
+});
+
+if (result.error) {
+  if (result.error.code === "EACCES") {
+    console.error(
+      `gadriel: binary at ${binPath} is not executable.\n` +
+        `Try: chmod +x "${binPath}"\n` +
+        `Or reinstall: npm install -g gadriel --force --include=optional`
+    );
+  } else {
+    console.error(`gadriel: failed to spawn binary: ${result.error.message}`);
+  }
+  exit(1);
+}
+
+exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "gadriel",
+  "version": "0.9.8",
+  "description": "Gadriel - Code-security CLI for AI-assisted development",
+  "keywords": [
+    "security",
+    "sast",
+    "cli",
+    "audit",
+    "ai-coding",
+    "scanner"
+  ],
+  "homepage": "https://gadriel.ai",
+  "bugs": "https://github.com/Gadriel-ai/preflight/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gadriel-ai/preflight.git",
+    "directory": "npm/gadriel"
+  },
+  "license": "MIT",
+  "author": "Gadriel team",
+  "type": "module",
+  "bin": {
+    "gadriel": "bin/gadriel.js"
+  },
+  "files": [
+    "bin/gadriel.js",
+    "scripts/postinstall.js",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js || true"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "optionalDependencies": {
+    "@gadriel/cli-linux-x64": "0.9.8",
+    "@gadriel/cli-linux-arm64": "0.9.8",
+    "@gadriel/cli-darwin-x64": "0.9.8",
+    "@gadriel/cli-darwin-arm64": "0.9.8",
+    "@gadriel/cli-win32-x64": "0.9.8"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Lightweight install-time sanity check.
+//
+// We do NOT download anything here (the optionalDependencies pattern
+// is the whole point: npm fetches the right binary directly). This
+// script only verifies a platform package was resolved and prints a
+// helpful message if it wasn't, so users find out at install time
+// instead of at first invocation.
+//
+// `|| true` in package.json means a missing platform package never
+// fails the install — `bin/gadriel.js` will give a more actionable
+// error on the first run.
+
+import { createRequire } from "node:module";
+import { platform, arch } from "node:process";
+
+const require = createRequire(import.meta.url);
+
+const MAP = {
+  "linux-x64":    "@gadriel/cli-linux-x64",
+  "linux-arm64":  "@gadriel/cli-linux-arm64",
+  "darwin-x64":   "@gadriel/cli-darwin-x64",
+  "darwin-arm64": "@gadriel/cli-darwin-arm64",
+  "win32-x64":    "@gadriel/cli-win32-x64",
+};
+
+const key = `${platform}-${arch}`;
+const target = MAP[key];
+
+if (!target) {
+  console.warn(
+    `gadriel: no prebuilt binary for ${key}. ` +
+      `Open an issue at https://github.com/Gadriel-ai/preflight/issues`
+  );
+  process.exit(0); // don't fail npm install
+}
+
+try {
+  require.resolve(`${target}/package.json`);
+  // Resolved — install is good.
+} catch {
+  console.warn(
+    `gadriel: optional platform package "${target}" was skipped by npm.\n` +
+      `         If 'gadriel' fails to run, reinstall with:\n` +
+      `         npm install -g gadriel --include=optional`
+  );
+}