@vibgrate/cli 0.1.1 → 0.1.2

package/DOCS.md

@@ -0,0 +1,554 @@
+# Vibgrate CLI — Full Documentation
+
+> Continuous Upgrade Drift Intelligence for Node & .NET
+
+For a quick overview, see the [README](./README.md). This document covers everything in detail.
+
+---
+
+## Table of Contents
+
+- [How It Works](#how-it-works)
+- [Commands Reference](#commands-reference)
+  - [vibgrate init](#vibgrate-init)
+  - [vibgrate scan](#vibgrate-scan)
+  - [vibgrate baseline](#vibgrate-baseline)
+  - [vibgrate report](#vibgrate-report)
+  - [vibgrate push](#vibgrate-push)
+  - [vibgrate dsn create](#vibgrate-dsn-create)
+  - [vibgrate update](#vibgrate-update)
+- [Upgrade Drift Score](#upgrade-drift-score)
+  - [How the Score Is Calculated](#how-the-score-is-calculated)
+  - [Risk Levels](#risk-levels)
+  - [Score Components](#score-components)
+- [Output Formats](#output-formats)
+  - [Text](#text)
+  - [JSON Artifact](#json-artifact)
+  - [SARIF](#sarif)
+  - [Markdown](#markdown)
+- [Configuration](#configuration)
+  - [vibgrate.config.ts](#vibgrateconfigts)
+  - [Thresholds](#thresholds)
+  - [Scanner Toggles](#scanner-toggles)
+- [Extended Scanners](#extended-scanners)
+  - [Platform Matrix](#platform-matrix)
+  - [Dependency Risk](#dependency-risk)
+  - [Dependency Graph & Duplication](#dependency-graph--duplication)
+  - [Tooling Inventory](#tooling-inventory)
+  - [Build & Deploy Surface Area](#build--deploy-surface-area)
+  - [TypeScript Modernity](#typescript-modernity)
+  - [Breaking Change Exposure](#breaking-change-exposure)
+  - [File Hotspots](#file-hotspots)
+  - [Security Posture](#security-posture)
+  - [Service Dependencies](#service-dependencies)
+- [CI Integration](#ci-integration)
+  - [GitHub Actions](#github-actions)
+  - [Azure DevOps](#azure-devops)
+  - [GitLab CI](#gitlab-ci)
+  - [Generic Pipelines](#generic-pipelines)
+- [Dashboard Upload](#dashboard-upload)
+  - [DSN Tokens](#dsn-tokens)
+  - [Data Residency](#data-residency)
+- [Privacy & Security](#privacy--security)
+- [Exit Codes](#exit-codes)
+- [Programmatic API](#programmatic-api)
+
+---
+
+## How It Works
+
+Vibgrate recursively scans your repository for `package.json` (Node/TypeScript) and `.sln`/`.csproj` (.NET) files. For each project it discovers, it:
+
+1. **Detects** the runtime version, target framework, and all dependencies
+2. **Queries** the npm/NuGet registry for latest stable versions (with built-in caching and concurrency control)
+3. **Computes** how far behind each component is — major version lag, EOL proximity, dependency age distribution
+4. **Generates** a deterministic Upgrade Drift Score (0–100)
+5. **Produces** findings, a full JSON artifact, and optional SARIF output
+
+No source code is read. No secrets are scanned. The CLI works entirely offline — dashboard upload is optional.
+
+---
+
+## Commands Reference
+
+### vibgrate init
+
+Initialise Vibgrate in a project.
+
+```bash
+vibgrate init [path] [--baseline] [--yes]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--baseline` | Create an initial drift baseline after init |
+| `--yes` | Skip confirmation prompts |
+
+Creates:
+- `.vibgrate/` directory
+- `vibgrate.config.ts` with sensible defaults
+
+---
+
+### vibgrate scan
+
+The primary command. Scans your project for upgrade drift.
+
+```bash
+vibgrate scan [path] [--format text|json|sarif] [--out <file>] [--fail-on warn|error] [--baseline <file>] [--changed-only] [--concurrency <n>]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--format` | `text` | Output format: `text`, `json`, or `sarif` |
+| `--out <file>` | — | Write output to a file |
+| `--fail-on <level>` | — | Exit with code 2 if findings at this level exist |
+| `--baseline <file>` | — | Compare against a previous baseline |
+| `--changed-only` | — | Only scan changed files |
+| `--concurrency <n>` | `8` | Max concurrent npm registry calls |
+
+The scan always writes the full artifact to `.vibgrate/scan_result.json`.
+
+---
+
+### vibgrate baseline
+
+Create a drift baseline snapshot for delta comparison.
+
+```bash
+vibgrate baseline [path]
+```
+
+Runs a full scan and saves the result to `.vibgrate/baseline.json`. Use this as the starting point for tracking drift over time.
+
+---
+
+### vibgrate report
+
+Generate a human-readable report from a scan artifact.
+
+```bash
+vibgrate report [--in <file>] [--format md|text|json]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--in` | `.vibgrate/scan_result.json` | Input artifact file |
+| `--format` | `text` | Output format: `md`, `text`, or `json` |
+
+---
+
+### vibgrate push
+
+Upload scan results to the Vibgrate dashboard API.
+
+```bash
+vibgrate push [--dsn <dsn>] [--file <file>] [--region <region>] [--strict]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dsn` | `VIBGRATE_DSN` env | DSN token for authentication |
+| `--file` | `.vibgrate/scan_result.json` | Scan artifact to upload |
+| `--region` | — | Override data residency region (`us`, `eu`) |
+| `--strict` | — | Fail hard on upload errors |
+
+Upload is always optional. Best-effort by default — use `--strict` in CI if you want the pipeline to fail on upload errors.
+
+---
+
+### vibgrate dsn create
+
+Generate an HMAC-signed DSN token for API authentication.
+
+```bash
+vibgrate dsn create --workspace <id> [--region <region>] [--ingest <url>] [--write <path>]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--workspace` | *required* | Your workspace ID |
+| `--region` | `us` | Data residency region (`us`, `eu`) |
+| `--ingest` | — | Custom ingest API URL (overrides `--region`) |
+| `--write` | — | Write DSN to a file (add to `.gitignore`!) |
+
+---
+
+### vibgrate update
+
+Check for and install updates.
+
+```bash
+vibgrate update [--check] [--pm <manager>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--check` | Only check for updates, don't install |
+| `--pm` | Force a package manager (`npm`, `pnpm`, `yarn`, `bun`) |
+
+---
+
+## Upgrade Drift Score
+
+### How the Score Is Calculated
+
+The Upgrade Drift Score is a deterministic, versioned metric (0–100) that represents how far behind your codebase is relative to the current stable ecosystem baseline.
+
+**Higher score = healthier upgrade posture.**
+
+### Risk Levels
+
+| Score | Risk Level |
+|-------|------------|
+| 70–100 | **Low** — You're in good shape |
+| 40–69 | **Moderate** — Some attention needed |
+| 0–39 | **High** — Significant upgrade debt |
+
+### Score Components
+
+The overall score is a weighted combination of four components:
+
+| Component | What It Measures |
+|-----------|-----------------|
+| **Runtime** | Node.js or .NET runtime major version lag |
+| **Frameworks** | Major version distance for core frameworks (React, Next, NestJS, ASP.NET, etc.) |
+| **Dependencies** | Age distribution across all dependencies (current vs 1 major behind vs 2+ behind) |
+| **EOL Risk** | Proximity to end-of-life for runtimes and frameworks |
+
+---
+
+## Output Formats
+
+### Text
+
+The default output. A coloured, human-readable report showing:
+- Overall drift score and risk level
+- Score component breakdown with visual bars
+- Per-project details: runtime lag, framework versions, dependency distribution
+- Findings with severity icons
+
+### JSON Artifact
+
+The full scan artifact in JSON format. Contains all raw data, scores, findings, and VCS metadata. Stable schema (`schemaVersion: "1.0"`). This is the same artifact saved to `.vibgrate/scan_result.json`.
+
+### SARIF
+
+[Static Analysis Results Interchange Format](https://sarifweb.azurewebsites.net/) — compatible with GitHub Code Scanning and Azure DevOps. Contains findings only (not all metrics). Ideal for integrating drift findings directly into your PR review workflow.
+
+### Markdown
+
+A clean Markdown report suitable for PRs, wikis, or documentation.
+
+---
+
+## Configuration
+
+### vibgrate.config.ts
+
+Run `vibgrate init` to generate the config file, or create one manually:
+
+```typescript
+import type { VibgrateConfig } from '@vibgrate/cli';
+
+const config: VibgrateConfig = {
+  exclude: ['legacy/**'],
+  thresholds: {
+    failOnError: {
+      eolDays: 180,
+      frameworkMajorLag: 3,
+      dependencyTwoPlusPercent: 50,
+    },
+    warn: {
+      frameworkMajorLag: 2,
+      dependencyTwoPlusPercent: 30,
+    },
+  },
+  scanners: {
+    platformMatrix:         { enabled: true },
+    dependencyRisk:         { enabled: true },
+    dependencyGraph:        { enabled: true },
+    toolingInventory:       { enabled: true },
+    buildDeploy:            { enabled: true },
+    tsModernity:            { enabled: true },
+    breakingChangeExposure: { enabled: true },
+    fileHotspots:           { enabled: true },
+    securityPosture:        { enabled: true },
+    serviceDependencies:    { enabled: true },
+  },
+};
+
+export default config;
+```
+
+Also supports `vibgrate.config.js` and `vibgrate.config.json`.
+
+### Thresholds
+
+Control when findings are raised and when the CLI should fail.
+
+| Threshold | Default | Triggers |
+|-----------|---------|----------|
+| `failOnError.eolDays` | 180 | Error finding when runtime EOL is within N days |
+| `failOnError.frameworkMajorLag` | 3 | Error finding when any framework is N+ majors behind |
+| `failOnError.dependencyTwoPlusPercent` | 50 | Error finding when N+% of dependencies are 2+ majors behind |
+| `warn.frameworkMajorLag` | 2 | Warning finding when any framework is N+ majors behind |
+| `warn.dependencyTwoPlusPercent` | 30 | Warning finding when N+% of dependencies are 2+ majors behind |
+
+### Scanner Toggles
+
+Each extended scanner can be individually disabled. Set `scanners: false` to disable all extended scanners (the core drift scan always runs).
+
+---
+
+## Extended Scanners
+
+Beyond the core drift score, Vibgrate runs a suite of extended scanners that collect high-value migration intelligence. All scanners:
+
+- Are **read-only** — they never write files or execute project code
+- Run **in parallel** — failures in one scanner never affect the others
+- Can be **individually toggled** in the config
+- Collect **zero sensitive data** — no source code, no secrets, no PII
+
+### Platform Matrix
+
+Collects platform and architecture signals that predict where builds will break when moving CI runners, containers, or CPU architectures.
+
+- `engines.node` and `engines.npm`/`engines.pnpm` ranges
+- `.nvmrc` / `.node-version` files
+- .NET `TargetFramework` and SDK versions
+- Native module risk packages (`sharp`, `bcrypt`, `node-gyp`, etc.)
+- OS-assumption scripts in `package.json`
+- Dockerfile base images (FROM lines only)
+
+### Dependency Risk
+
+Extends dependency analysis with risk classification signals:
+
+- Deprecated packages (npm `deprecated` field)
+- Native module detection
+- Platform-specific package flags
+
+### Dependency Graph & Duplication
+
+Parses lockfiles (pnpm, npm, yarn, .NET) to build a workspace-wide dependency graph:
+
+- Total unique vs. installed dependency counts
+- Duplicated packages (multiple versions of the same package)
+- Phantom dependencies (used but not declared)
+
+### Tooling Inventory
+
+Maps the full technology stack across your workspace by detecting package names in dependencies:
+
+| Category | Examples |
+|----------|---------|
+| Frontend | React, Vue, Angular, Svelte, Solid |
+| Meta-frameworks | Next.js, Nuxt, Astro, Remix |
+| Bundlers | Vite, webpack, esbuild, Rollup |
+| Backend | Express, Fastify, NestJS, Hono |
+| ORM / DB | Prisma, Drizzle, TypeORM, EF Core |
+| Testing | Vitest, Jest, Playwright, xUnit |
+| Observability | Sentry, OpenTelemetry, Pino, Winston |
+
+### Build & Deploy Surface Area
+
+Detects CI/CD, containerisation, and infrastructure-as-code:
+
+- CI systems (GitHub Actions, GitLab CI, Azure DevOps, Jenkins, CircleCI)
+- Docker and Docker Compose
+- IaC (Terraform, Bicep, CloudFormation, Pulumi)
+- Release tooling (Changesets, semantic-release, GitVersion)
+- Package managers and monorepo tools
+
+### TypeScript Modernity
+
+Reads `tsconfig.json` compiler options to assess strictness and modernity:
+
+- TypeScript version
+- `strict`, `noImplicitAny`, `strictNullChecks` flags
+- Module system (`module`, `moduleResolution`, `target`)
+- ESM vs CJS classification
+- `exports` field presence
+
+### Breaking Change Exposure
+
+Flags packages and patterns known to cause upgrade pain:
+
+- Deprecated packages (e.g. `request`, `node-sass`, `tslint`, `moment`)
+- Legacy Node API polyfills no longer needed on Node 18+ (e.g. `node-fetch`, `abort-controller`)
+- Peer dependency conflicts
+- Exposure score (0–100)
+
+### File Hotspots
+
+Lightweight complexity analysis using filesystem metadata only (never reads file contents):
+
+- File counts by extension
+- Largest files by size (path + bytes)
+- Directory depth distribution
+- Most-used packages across the workspace
+
+### Security Posture
+
+Structural security hygiene indicators (not a secret scanner):
+
+- Lockfile presence and consistency
+- `.gitignore` coverage for `.env` files and `node_modules`
+- `.env` files tracked outside `.gitignore`
+- Audit severity counts (via `npm audit --json`)
+
+### Service Dependencies
+
+Maps external service and platform dependencies by detecting SDK packages:
+
+| Category | Examples |
+|----------|---------|
+| Payment | Stripe, Braintree, PayPal |
+| Auth | Auth0, Clerk, Firebase, Passport |
+| Cloud SDKs | AWS, Azure, Google Cloud |
+| Databases | PostgreSQL, MongoDB, Redis |
+| Messaging | SQS, SNS, Kafka, BullMQ |
+| Observability | Sentry, DataDog, New Relic |
+
+---
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+steps:
+  - name: Vibgrate Scan
+    run: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+
+  - name: Upload SARIF
+    uses: github/codeql-action/upload-sarif@v3
+    with:
+      sarif_file: vibgrate.sarif
+
+  # Optional: push metrics to dashboard
+  - name: Push Vibgrate Metrics
+    env:
+      VIBGRATE_DSN: ${{ secrets.VIBGRATE_DSN }}
+    run: npx @vibgrate/cli push --file .vibgrate/scan_result.json
+```
+
+### Azure DevOps
+
+```yaml
+steps:
+  - script: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+    displayName: Vibgrate Scan
+
+  - task: PublishBuildArtifacts@1
+    inputs:
+      PathtoPublish: vibgrate.sarif
+      ArtifactName: VibgrateSARIF
+```
+
+### GitLab CI
+
+```yaml
+vibgrate:
+  script:
+    - npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+  artifacts:
+    reports:
+      sast: vibgrate.sarif
+```
+
+### Generic Pipelines
+
+Vibgrate works in any CI environment. The CLI:
+
+- Requires no login or authentication
+- Returns meaningful exit codes (see below)
+- Produces standard SARIF output
+- Works entirely offline (push is opt-in)
+
+---
+
+## Dashboard Upload
+
+### DSN Tokens
+
+Vibgrate uses HMAC-signed DSN tokens for authenticated uploads. The DSN format:
+
+```
+vibgrate+https://<key_id>:<secret>@<ingest_host>/<workspace_id>
+```
+
+Set `VIBGRATE_DSN` as a secret in your CI environment. Uploads are always optional — the CLI provides full value locally without any server connection.
+
+### Data Residency
+
+Vibgrate supports region-specific ingest endpoints:
+
+| Region | Endpoint |
+|--------|----------|
+| US (default) | `us.ingest.vibgrate.com` |
+| EU | `eu.ingest.vibgrate.com` |
+
+Use `--region eu` on `push` or `dsn create` to route data to the EU endpoint.
+
+---
+
+## Privacy & Security
+
+Vibgrate is built with a privacy-first architecture. Here's what it **never** does:
+
+| Category | Hard guarantee |
+|----------|---------------|
+| Source code | Never read beyond config/manifest files |
+| Secrets | Never scanned for, never extracted |
+| Environment values | Never read — only `.env` file existence is flagged |
+| Git identity data | Never accessed — `git log` is never invoked |
+| File contents | Only structured config fields are extracted |
+| Network endpoints | Never parsed from config files |
+
+What it **does** collect:
+
+- Package names and version numbers (from `package.json`, `.csproj`, lockfiles)
+- Config structure flags (e.g. `strict: true` from `tsconfig.json`)
+- File names and sizes (paths and metadata, never contents)
+- Public npm/NuGet registry metadata (latest versions, deprecation flags)
+- CI/Docker/IaC file presence and structural counts
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Runtime error |
+| `2` | `--fail-on` threshold exceeded |
+
+---
+
+## Programmatic API
+
+The package exports its core types for programmatic use:
+
+```typescript
+import type { VibgrateConfig, ScanArtifact, DriftScore, Finding } from '@vibgrate/cli';
+```
+
+---
+
+## Requirements
+
+- **Node.js** >= 20.0.0
+- Works on macOS, Linux, and Windows
+
+---
+
+## Links
+
+- [Website](https://vibgrate.com)
+- [npm](https://www.npmjs.com/package/@vibgrate/cli)
+
+---
+
+Copyright © 2026 Vibgrate. All rights reserved. See [LICENSE](./LICENSE) for terms.

package/LICENSE

@@ -0,0 +1,45 @@
+Vibgrate Proprietary License
+
+Copyright (c) 2026 Vibgrate. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software in compiled/distributed form (the "Software"),
+to use the Software for internal business and personal purposes, subject to the
+following conditions:
+
+1. PERMITTED USE
+   You may install, run, and use the Software as provided via the npm registry
+   for the purpose of analysing upgrade drift in your own projects.
+
+2. NO MODIFICATION
+   You may not modify, adapt, translate, reverse-engineer, decompile,
+   disassemble, or create derivative works based on the Software.
+
+3. NO REDISTRIBUTION
+   You may not redistribute, sublicense, sell, lease, or otherwise transfer
+   the Software or any copy thereof to any third party, except as part of
+   your own project's development toolchain (e.g. listed as a dependency in
+   package.json).
+
+4. NO SOURCE CODE ACCESS
+   The source code of this Software is proprietary and confidential. Access
+   to source code, if provided separately, does not grant any additional
+   rights beyond those stated in this license.
+
+5. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+   DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+   OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+   USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+7. TERMINATION
+   This license is effective until terminated. It will terminate automatically
+   if you fail to comply with any of its terms. Upon termination, you must
+   destroy all copies of the Software in your possession.
+
+For licensing enquiries: ops@vibgrate.com

package/README.md

@@ -0,0 +1,234 @@
+<p align="center">
+  <strong>@vibgrate/cli</strong>
+  <br />
+  Continuous Upgrade Drift Intelligence for Node & .NET
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@vibgrate/cli"><img src="https://img.shields.io/npm/v/@vibgrate/cli?color=blue&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/@vibgrate/cli"><img src="https://img.shields.io/npm/dm/@vibgrate/cli?color=green" alt="npm downloads" /></a>
+  <a href="https://vibgrate.com"><img src="https://img.shields.io/badge/website-vibgrate.com-blue" alt="website" /></a>
+  <img src="https://img.shields.io/node/v/@vibgrate/cli" alt="node version" />
+</p>
+
+---
+
+Modern codebases don't break all at once — they decay silently. Node runtimes fall behind LTS. .NET frameworks approach end-of-life. Core dependencies lag multiple major versions. Upgrade cost compounds until it becomes a project in itself.
+
+**Vibgrate turns that invisible decay into a measurable signal.** One CLI command gives you an Upgrade Drift Score (0–100), actionable findings, and a clear picture of where your upgrade debt lives.
+
+---
+
+## Quick Start
+
+Run instantly with npx — no install required:
+
+```bash
+npx @vibgrate/cli scan .
+```
+
+Or install as a dev dependency:
+
+```bash
+npm install -D @vibgrate/cli
+```
+
+Then scan your project:
+
+```bash
+vibgrate scan .
+```
+
+That's it. You'll see a full drift report in seconds.
+
+---
+
+## What You Get
+
+```
+╔══════════════════════════════════════════╗
+║        Vibgrate Drift Report             ║
+╚══════════════════════════════════════════╝
+
+  Drift Score:  72/100
+  Risk Level:   Low
+  Projects:     3
+
+  Score Breakdown
+    Runtime:      ████████████████████ 100
+    Frameworks:   ████████████████░░░░  78
+    Dependencies: ██████████████░░░░░░  64
+    EOL Risk:     ████████████████████ 100
+
+  ── my-api (node) src/api
+     Runtime: 20.11.0 (current)
+     Frameworks:
+       NestJS: 10.3.0 → 11.0.0 (1 behind)
+     Dependencies:
+       42 current  8 1-behind  3 2+ behind
+
+  Findings
+    ⚠ Framework "NestJS" is 1 major version(s) behind
+    ⚠ 12% of dependencies are 2+ major versions behind
+```
+
+---
+
+## Key Features
+
+### Upgrade Drift Score
+
+A single 0–100 number that tells you how upgrade-ready your codebase is. Computed from runtime lag, framework versions, dependency age distribution, and EOL proximity. Deterministic and comparable across repos.
+
+### Multi-Platform Scanning
+
+Works across **Node.js/TypeScript** and **.NET** projects in the same scan. Detects `package.json`, `.sln`, and `.csproj` files recursively.
+
+### CI-Native
+
+Designed to live in your build pipeline. Returns meaningful exit codes, produces SARIF output for GitHub Code Scanning and Azure DevOps, and requires zero configuration to get started.
+
+### Ten Extended Scanners
+
+Beyond the core drift score, Vibgrate runs a suite of extended scanners — all optional, all privacy-safe:
+
+| Scanner | What It Finds |
+|---------|---------------|
+| **Platform Matrix** | Native modules, OS assumptions, Docker base images, architecture risks |
+| **Dependency Risk** | Deprecated packages, native module flags, platform-specific dependencies |
+| **Dependency Graph** | Duplicated packages, phantom dependencies, lockfile analysis |
+| **Tooling Inventory** | Full tech stack map — frameworks, bundlers, ORMs, testing tools |
+| **Build & Deploy** | CI systems, Docker, IaC, release tooling, monorepo tools |
+| **TypeScript Modernity** | Strict mode, module system, ESM readiness |
+| **Breaking Change Exposure** | Packages known to cause upgrade pain, legacy polyfills |
+| **File Hotspots** | Codebase shape — file counts, sizes, depth, shared packages |
+| **Security Posture** | Lockfile hygiene, `.gitignore` coverage, audit severity counts |
+| **Service Dependencies** | External SDK detection — payment, auth, cloud, databases, messaging |
+
+### Baseline & Delta Tracking
+
+Take a baseline snapshot, then measure drift over time:
+
+```bash
+vibgrate baseline .
+vibgrate scan . --baseline .vibgrate/baseline.json
+```
+
+### Multiple Output Formats
+
+| Format | Use Case |
+|--------|----------|
+| `text` | Terminal output, local development |
+| `json` | Programmatic consumption, artifact storage |
+| `sarif` | GitHub Code Scanning, Azure DevOps integration |
+| `md` | PR comments, documentation, wikis |
+
+### Dashboard Upload (Optional)
+
+Push scan results to the [Vibgrate Dashboard](https://vibgrate.com) for trend analysis, cross-repo comparison, and team-wide visibility. Upload is always opt-in — the CLI provides full value offline.
+
+```bash
+VIBGRATE_DSN="..." vibgrate push
+```
+
+---
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: Vibgrate Scan
+  run: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: vibgrate.sarif
+```
+
+### Azure DevOps
+
+```yaml
+- script: npx @vibgrate/cli scan . --format sarif --out vibgrate.sarif --fail-on error
+  displayName: Vibgrate Scan
+```
+
+Works in any CI environment. No login required. No configuration needed.
+
+---
+
+## Configuration
+
+Optionally create a `vibgrate.config.ts` to customise thresholds and scanner toggles:
+
+```bash
+vibgrate init
+```
+
+```typescript
+import type { VibgrateConfig } from '@vibgrate/cli';
+
+const config: VibgrateConfig = {
+  exclude: ['legacy/**'],
+  thresholds: {
+    failOnError: {
+      eolDays: 180,
+      frameworkMajorLag: 3,
+      dependencyTwoPlusPercent: 50,
+    },
+  },
+};
+
+export default config;
+```
+
+---
+
+## Privacy First
+
+Vibgrate is designed to be safe to run on any codebase:
+
+- **No source code is read** — only `package.json`, `tsconfig.json`, lockfiles, and project manifests
+- **No secrets are scanned** — ever
+- **No git history, authors, or commit messages** — only HEAD SHA and branch name for traceability
+- **No data leaves your machine** unless you explicitly run `vibgrate push`
+- **No login required** — works fully offline
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `vibgrate scan [path]` | Scan for upgrade drift |
+| `vibgrate baseline [path]` | Create a drift baseline |
+| `vibgrate report` | Generate a report from a scan artifact |
+| `vibgrate init [path]` | Initialise config and `.vibgrate/` directory |
+| `vibgrate push` | Upload scan results to dashboard |
+| `vibgrate dsn create` | Generate a DSN token |
+| `vibgrate update` | Check for and install updates |
+
+---
+
+## Requirements
+
+- **Node.js** >= 20.0.0
+- Works on macOS, Linux, and Windows
+
+---
+
+## Full Documentation
+
+See [DOCS.md](https://github.com/crowers/vibgrate-cli/blob/main/packages/vibgrate-cli/DOCS.md) for the complete reference — all commands, all flags, configuration options, extended scanner details, CI examples, and more.
+
+---
+
+## Links
+
+- [Website](https://vibgrate.com)
+- [Documentation](https://github.com/crowers/vibgrate-cli/blob/main/packages/vibgrate-cli/DOCS.md)
+
+---
+
+Copyright © 2026 Vibgrate. All rights reserved. See [LICENSE](./LICENSE) for terms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibgrate/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI for measuring upgrade drift across Node & .NET projects",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "DOCS.md"
   ],
   "scripts": {
     "build": "tsup src/cli.ts src/index.ts --format esm --dts --clean",
@@ -34,7 +35,8 @@
     "sarif"
   ],
   "author": "Vibgrate",
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://vibgrate.com",
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/semver": "^7.5.0",