@offgridsec/kira-lite-mcp 0.1.3 → 0.1.5

package/README.md

@@ -9,74 +9,501 @@ Kira-Lite catches vulnerabilities **before code is written to disk**. It integra
 Security tools shouldn't live in a separate tab. Kira-Lite runs **inside your AI coding assistant** — the same place you write code. No context switching, no separate dashboards, no CI pipeline to wait for.
 
 - **Scans before code hits disk** — vulnerabilities are caught and fixed in the same conversation
-- **Works where you already are** — Claude Code, Cursor, Windsurf, or any MCP-compatible editor
+- **Works where you already are** — Claude Code, Cursor, Windsurf, Codex, Antigravity, or any MCP-compatible editor
 - **Zero config to start** — one `npx` command, no API keys, no accounts
 - **Your code stays local** — nothing is sent to external servers; all scanning happens on your machine
 
+## Prerequisites
+
+- **Node.js** >= 18
+- An MCP-compatible AI coding assistant
+
 ## Quick Start
 
 ```bash
 # Install globally
 npm install -g @offgridsec/kira-lite-mcp
 
-# Or run directly
+# Or run directly without installing
 npx @offgridsec/kira-lite-mcp
 ```
 
-## Setup
+---
 
-### 1. Register MCP Server (one-time, global)
+## Setup by IDE / Tool
 
-**Claude Code:**
+Pick your IDE or tool below and follow the steps. Each section is self-contained.
 
-```bash
-claude mcp add --scope user kira-lite -- npx -y @offgridsec/kira-lite-mcp
-```
+### Claude Code (CLI)
 
-**Cursor / Windsurf / Other MCP Clients:**
+Claude Code requires three things: (1) register the MCP server, (2) add a `CLAUDE.md` file so Claude knows to scan automatically, and (3) add `.claude/settings.local.json` for auto-permissions and hook enforcement.
 
-Add to your MCP configuration:
+#### Step 1 — Register the MCP server (one-time, global)
 
-```json
-{
-  "kira-lite": {
-    "command": "npx",
-    "args": ["-y", "@offgridsec/kira-lite-mcp"]
-  }
-}
+```bash
+claude mcp add --scope user kira-lite -- npx -y @offgridsec/kira-lite-mcp
 ```
 
-### 2. Per-Project Setup (Claude Code only)
-
-After registering the MCP server, you also need to copy **two files** into each project where you want automatic scanning:
+This makes kira-lite available in every project.
 
-| File | What it does |
-|------|-------------|
-| `CLAUDE.md` | Tells Claude to call `scan_code` before every Edit/Write — without this, Claude won't scan automatically |
-| `.claude/settings.local.json` | Auto-allows the kira-lite MCP tools (no approval prompts) and adds a post-write hook as a safety net |
+#### Step 2 — Per-project setup
 
-**Without these files**, the MCP tools are still available but Claude won't use them unless you ask manually.
+Navigate to your project directory, then copy the two config files:
 
-**New project (no existing CLAUDE.md or settings):**
+**macOS / Linux:**
 
 ```bash
-# macOS / Linux
+cd /path/to/your-project
+
+# Copy CLAUDE.md (tells Claude to scan before every write)
 cp $(npm root -g)/@offgridsec/kira-lite-mcp/config/CLAUDE.md .
+
+# Copy settings (auto-allows kira-lite tools + adds post-write hook)
 mkdir -p .claude
 cp $(npm root -g)/@offgridsec/kira-lite-mcp/config/settings.local.json .claude/settings.local.json
 ```
 
+**Windows (PowerShell):**
+
 ```powershell
-# Windows (PowerShell)
+cd C:\path\to\your-project
+
 $pkg = (npm root -g) + "\@offgridsec\kira-lite-mcp"
 Copy-Item "$pkg\config\CLAUDE.md" .
 New-Item -ItemType Directory -Force .claude | Out-Null
 Copy-Item "$pkg\config\settings.local.json" .claude\settings.local.json
 ```
 
-**Already have a CLAUDE.md or settings?** See [INSTALL.md](INSTALL.md) for merge instructions (Scenarios B, C, D).
+> **Already have a `CLAUDE.md` or `.claude/settings.local.json`?** Don't overwrite them — merge manually:
+>
+> <details>
+> <summary><strong>If you already have a CLAUDE.md</strong></summary>
+>
+> Append the kira-lite instructions to the end of your existing file:
+>
+> ```bash
+> # macOS / Linux
+> echo "" >> CLAUDE.md
+> cat $(npm root -g)/@offgridsec/kira-lite-mcp/config/CLAUDE.md >> CLAUDE.md
+> ```
+>
+> Or manually add this block to the bottom of your `CLAUDE.md`:
+>
+> ```markdown
+> # SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+>
+> You MUST call the `scan_code` MCP tool before EVERY single Edit or Write tool call. No exceptions. This is not optional.
+>
+> ## How it works
+>
+> 1. Before you use Edit or Write, call `scan_code` with the code you are about to write
+> 2. If findings are returned, fix them and call `scan_code` again
+> 3. Only write the code after scan returns clean
+> 4. For edits to existing files, use `scan_diff` with original and new code
+>
+> ## Rules
+>
+> - EVERY Edit/Write MUST be preceded by a scan_code call
+> - If scan returns critical or high findings, DO NOT write the code
+> - Tell the user what you found and what you fixed
+> - This applies to ALL files: .js, .ts, .py, .go, .java, .rb, .php, .yaml, .tf, Dockerfile, etc.
+>
+> ## ONBOARDING — First-time registration check
+>
+> On your **FIRST interaction** in any new conversation, you MUST call `get_config`.
+>
+> - If `registered` is `true`, do NOT mention registration. Proceed normally.
+> - If `registered` is `false` AND `registrationSkippedUntil` is a future date, do NOT ask. The user already skipped.
+> - If `registered` is `false` AND `registrationSkippedUntil` is `null`, ask the user:
+>   > "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories for popular frameworks, and product updates. Just share your email or say 'skip'."
+> - If the user provides an email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+> - Do NOT ask about registration more than once per conversation.
+> ```
+>
+> </details>
+>
+> <details>
+> <summary><strong>If you already have .claude/settings.local.json</strong></summary>
+>
+> Merge these entries into your existing file:
+>
+> **Add to `permissions.allow` array:**
+>
+> ```json
+> "mcp__kira-lite__scan_code",
+> "mcp__kira-lite__scan_file",
+> "mcp__kira-lite__scan_diff",
+> "mcp__kira-lite__fix_vulnerability",
+> "mcp__kira-lite__get_config",
+> "mcp__kira-lite__set_config"
+> ```
+>
+> **Add to `hooks` object:**
+>
+> ```json
+> "PostToolCall": [
+>   {
+>     "matcher": "Write|Edit",
+>     "hooks": [
+>       {
+>         "type": "command",
+>         "command": "npx --yes @offgridsec/kira-lite-mcp/hook.mjs"
+>       }
+>     ]
+>   }
+> ]
+> ```
+>
+> **Example — before:**
+>
+> ```json
+> {
+>   "permissions": {
+>     "allow": [
+>       "Bash(npm test:*)"
+>     ]
+>   }
+> }
+> ```
+>
+> **Example — after:**
+>
+> ```json
+> {
+>   "permissions": {
+>     "allow": [
+>       "Bash(npm test:*)",
+>       "mcp__kira-lite__scan_code",
+>       "mcp__kira-lite__scan_file",
+>       "mcp__kira-lite__scan_diff",
+>       "mcp__kira-lite__fix_vulnerability",
+>       "mcp__kira-lite__get_config",
+>       "mcp__kira-lite__set_config"
+>     ]
+>   },
+>   "hooks": {
+>     "PostToolCall": [
+>       {
+>         "matcher": "Write|Edit",
+>         "hooks": [
+>           {
+>             "type": "command",
+>             "command": "npx --yes @offgridsec/kira-lite-mcp/hook.mjs"
+>           }
+>         ]
+>       }
+>     ]
+>   }
+> }
+> ```
+>
+> </details>
+
+#### Step 3 — Verify
+
+Start a new Claude Code session in your project and run `/mcp`. You should see `kira-lite` listed with 7 tools. Claude will now automatically scan code before every write.
+
+---
+
+### Cursor
+
+#### Step 1 — Add MCP server
+
+Open Cursor Settings > MCP and add a new server, or add this to your `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
+
+```json
+{
+  "mcpServers": {
+    "kira-lite": {
+      "command": "npx",
+      "args": ["-y", "@offgridsec/kira-lite-mcp"]
+    }
+  }
+}
+```
+
+#### Step 2 — Add project rules (recommended)
+
+Create or append to your `.cursorrules` file in the project root:
+
+```
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY code change. No exceptions.
+
+1. Before writing any code, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+5. If scan returns critical or high findings, DO NOT write the code
+6. Tell the user what you found and what you fixed
+
+# ONBOARDING — First-time registration check
+On your FIRST interaction in any new conversation, call `get_config`.
+- If `registered` is false and `registrationSkippedUntil` is null, ask the user:
+  "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories, and product updates. Share your email or say 'skip'."
+- If user provides email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+- If `registered` is true or `registrationSkippedUntil` is a future date, do not ask.
+- Do NOT ask about registration more than once per conversation.
+```
+
+#### Step 3 — Verify
+
+Open Cursor, start an Agent chat, and ask: "What MCP tools do you have?" You should see the kira-lite tools listed.
+
+---
+
+### Windsurf
+
+#### Step 1 — Add MCP server
+
+Open Windsurf Settings > MCP and add a new server, or add this to your `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "kira-lite": {
+      "command": "npx",
+      "args": ["-y", "@offgridsec/kira-lite-mcp"]
+    }
+  }
+}
+```
+
+#### Step 2 — Add project rules (recommended)
+
+Create or append to your `.windsurfrules` file in the project root:
+
+```
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY code change. No exceptions.
+
+1. Before writing any code, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+5. If scan returns critical or high findings, DO NOT write the code
+6. Tell the user what you found and what you fixed
+
+# ONBOARDING — First-time registration check
+On your FIRST interaction in any new conversation, call `get_config`.
+- If `registered` is false and `registrationSkippedUntil` is null, ask the user:
+  "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories, and product updates. Share your email or say 'skip'."
+- If user provides email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+- If `registered` is true or `registrationSkippedUntil` is a future date, do not ask.
+- Do NOT ask about registration more than once per conversation.
+```
+
+#### Step 3 — Verify
+
+Start a Cascade session and ask: "What MCP tools do you have?" You should see the kira-lite tools listed.
+
+---
+
+### VS Code (Copilot / GitHub Copilot)
+
+#### Step 1 — Add MCP server
+
+Add this to your `.vscode/mcp.json` (per-project) or user-level MCP settings:
+
+```json
+{
+  "servers": {
+    "kira-lite": {
+      "command": "npx",
+      "args": ["-y", "@offgridsec/kira-lite-mcp"]
+    }
+  }
+}
+```
+
+#### Step 2 — Add project instructions (recommended)
+
+Create or append to your `.github/copilot-instructions.md` file:
+
+```markdown
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY code change. No exceptions.
+
+1. Before writing any code, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+5. If scan returns critical or high findings, DO NOT write the code
+6. Tell the user what you found and what you fixed
+
+# ONBOARDING — First-time registration check
+On your FIRST interaction in any new conversation, call `get_config`.
+- If `registered` is false and `registrationSkippedUntil` is null, ask the user:
+  "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories, and product updates. Share your email or say 'skip'."
+- If user provides email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+- If `registered` is true or `registrationSkippedUntil` is a future date, do not ask.
+- Do NOT ask about registration more than once per conversation.
+```
+
+#### Step 3 — Verify
 
-> **Cursor / Windsurf users:** You do **not** need to copy these files. Those editors handle MCP tool instructions differently.
+Open Copilot Chat in Agent mode and ask: "What MCP tools do you have?"
+
+---
+
+### OpenAI Codex CLI
+
+#### Step 1 — Add MCP server
+
+Add this to your `~/.codex/config.yaml` or project-level `codex.yaml`:
+
+```yaml
+mcp_servers:
+  - name: kira-lite
+    command: npx
+    args: ["-y", "@offgridsec/kira-lite-mcp"]
+```
+
+#### Step 2 — Add project instructions (recommended)
+
+Create or append to your `AGENTS.md` file in the project root:
+
+```markdown
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY code change. No exceptions.
+
+1. Before writing any code, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+5. If scan returns critical or high findings, DO NOT write the code
+6. Tell the user what you found and what you fixed
+
+# ONBOARDING — First-time registration check
+On your FIRST interaction in any new conversation, call `get_config`.
+- If `registered` is false and `registrationSkippedUntil` is null, ask the user:
+  "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories, and product updates. Share your email or say 'skip'."
+- If user provides email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+- If `registered` is true or `registrationSkippedUntil` is a future date, do not ask.
+- Do NOT ask about registration more than once per conversation.
+```
+
+#### Step 3 — Verify
+
+Start a Codex session and ask: "What MCP tools do you have?"
+
+---
+
+### Antigravity
+
+#### Step 1 — Add MCP server
+
+In Antigravity, open Settings > MCP Servers and add a new server with:
+
+- **Command:** `npx`
+- **Args:** `-y @offgridsec/kira-lite-mcp`
+
+Or add to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "kira-lite": {
+      "command": "npx",
+      "args": ["-y", "@offgridsec/kira-lite-mcp"]
+    }
+  }
+}
+```
+
+#### Step 2 — Add project rules (recommended)
+
+Follow your IDE's instructions file convention (e.g., rules file or system prompt) and add:
+
+```
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY code change. No exceptions.
+
+1. Before writing any code, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+5. If scan returns critical or high findings, DO NOT write the code
+6. Tell the user what you found and what you fixed
+
+# ONBOARDING — First-time registration check
+On your FIRST interaction in any new conversation, call `get_config`.
+- If `registered` is false and `registrationSkippedUntil` is null, ask the user:
+  "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories, and product updates. Share your email or say 'skip'."
+- If user provides email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+- If `registered` is true or `registrationSkippedUntil` is a future date, do not ask.
+- Do NOT ask about registration more than once per conversation.
+```
+
+#### Step 3 — Verify
+
+Start a chat and ask: "What MCP tools do you have?"
+
+---
+
+### Other MCP-Compatible Clients
+
+For any MCP-compatible tool not listed above:
+
+#### Step 1 — Register the MCP server
+
+Add this to your client's MCP configuration:
+
+```json
+{
+  "kira-lite": {
+    "command": "npx",
+    "args": ["-y", "@offgridsec/kira-lite-mcp"]
+  }
+}
+```
+
+The exact file location varies by client — check your tool's MCP documentation.
+
+#### Step 2 — Add scanning instructions
+
+Add the following to whatever instructions/rules file your tool supports (system prompt, rules file, etc.):
+
+```
+# SECURITY SCANNING — REQUIRED ON EVERY CODE CHANGE
+
+You MUST call the `scan_code` MCP tool before EVERY code change. No exceptions.
+
+1. Before writing any code, call `scan_code` with the code you are about to write
+2. If findings are returned, fix them and call `scan_code` again
+3. Only write the code after scan returns clean
+4. For edits to existing files, use `scan_diff` with original and new code
+5. If scan returns critical or high findings, DO NOT write the code
+6. Tell the user what you found and what you fixed
+
+# ONBOARDING — First-time registration check
+On your FIRST interaction in any new conversation, call `get_config`.
+- If `registered` is false and `registrationSkippedUntil` is null, ask the user:
+  "Kira-Lite is active! Would you like to register your email? You'll get: new vulnerability rule alerts, security advisories, and product updates. Share your email or say 'skip'."
+- If user provides email, call `register`. If they skip, call `skip_registration` (7-day cooldown).
+- If `registered` is true or `registrationSkippedUntil` is a future date, do not ask.
+- Do NOT ask about registration more than once per conversation.
+```
+
+---
+
+## Quick Reference: Instructions File by IDE
+
+| IDE / Tool | Instructions File | MCP Config File |
+|------------|-------------------|-----------------|
+| **Claude Code** | `CLAUDE.md` (project root) | `claude mcp add` CLI or `~/.claude.json` |
+| **Cursor** | `.cursorrules` (project root) | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
+| **Windsurf** | `.windsurfrules` (project root) | `~/.codeium/windsurf/mcp_config.json` |
+| **VS Code (Copilot)** | `.github/copilot-instructions.md` | `.vscode/mcp.json` |
+| **OpenAI Codex CLI** | `AGENTS.md` (project root) | `~/.codex/config.yaml` |
+| **Antigravity** | Check IDE docs | Check IDE docs |
+
+---
 
 ## MCP Tools
 
@@ -87,8 +514,10 @@ Copy-Item "$pkg\config\settings.local.json" .claude\settings.local.json
 | `scan_diff` | Compare original vs modified code — reports only NEW vulnerabilities |
 | `scan_dependencies` | Scan project dependencies for known CVEs via OSV.dev (supports 13 lockfile formats across 11 ecosystems) |
 | `fix_vulnerability` | Get fix guidance for a specific vulnerability ID or CWE |
-| `get_config` | View current Kira-Lite configuration |
+| `get_config` | View current configuration and registration status |
 | `set_config` | Change scan frequency and other settings |
+| `register` | Register your email for security updates and vulnerability alerts |
+| `skip_registration` | Skip registration with a 7-day cooldown before being asked again |
 
 ## Configuration
 
@@ -126,6 +555,45 @@ get_config()
 
 > **Note:** The default mode is `"every-edit"`, which preserves the original behavior when no config file exists.
 
+## Registration (Optional)
+
+Register your email to receive security updates — new vulnerability rules, security advisories for popular frameworks, and product updates.
+
+### What you get
+
+| Benefit | Description |
+|---------|-------------|
+| **New vulnerability rules** | Get notified when Kira adds detection for new CVEs and attack patterns |
+| **Security advisories** | Early alerts for critical vulnerabilities affecting popular frameworks and libraries |
+| **Product updates** | New features, engine improvements, and expanded language support |
+
+### How it works
+
+On your first conversation, your AI assistant will ask if you'd like to register. You can:
+
+- **Register** — provide your email and the assistant calls `register`
+- **Skip** — say "skip" and you won't be asked again for 7 days
+
+### Manual registration
+
+You can also register anytime by asking your AI assistant:
+
+```
+Please register my email user@example.com with Kira-Lite
+```
+
+Or call the tool directly:
+
+```
+register({ email: "user@example.com" })
+```
+
+### Data storage
+
+- Your email is stored locally at `~/.kira-lite/profile.json`
+- Delete the file anytime to unregister
+- No email is sent to external servers — registration is linked to your anonymous device ID via telemetry only
+
 ## How It Works
 
 Kira-Lite ships with **Kira-Core**, a compiled Go binary that includes all 376 security rules and runs entirely on your machine. No external tools required.
@@ -349,21 +817,105 @@ The built-in rules map to **50+ distinct CWEs**, including:
 | CWE-190 | Integer Overflow | 1+ |
 | CWE-416 | Use After Free | 1+ |
 
-## Development
+## Troubleshooting
+
+### Claude doesn't scan before writing
+
+1. Check that `CLAUDE.md` exists in the project root with the kira-lite instructions
+2. Verify the hook is in `.claude/settings.local.json` — this is the enforcement layer
+3. Start a **new** session (`CLAUDE.md` is read at session start)
+
+### MCP tools not showing up
+
+- **Claude Code:** Re-register with `claude mcp add --scope user kira-lite -- npx -y @offgridsec/kira-lite-mcp`
+- **Cursor / Windsurf / VS Code:** Restart the IDE after adding the MCP config
+- **All tools:** Ensure Node.js >= 18 is installed and `npx` is available in your PATH
+
+### "Settings Error: PostToolCall: Invalid key in record" (Claude Code)
+
+You have hooks in the **user-level** settings file (`~/.claude/settings.local.json`). Hooks only work at project level. Remove the `hooks` section from the user-level file.
+
+### Scans returning "Skipped"
+
+Your scan mode is set to `"on-save"` or `"manual"`. Check with `get_config()` and change with `set_config({ scanMode: "every-edit" })`.
+
+### Hook fails silently (Claude Code)
+
+Make sure Node.js can find the hook script:
 
 ```bash
-npm install
-npm run build
-npm run dev    # watch mode
+node $(npm root -g)/@offgridsec/kira-lite-mcp/hook.mjs
 ```
 
+If it exits with no output, it's working. If it throws an error, check the path.
+
+## Uninstall
+
+### Remove from a single project
+
+Delete the kira-lite section from your instructions file (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc.) and remove the MCP config entry.
+
+For Claude Code projects, also remove kira-lite entries from `.claude/settings.local.json`.
+
+### Remove globally
+
+```bash
+# Claude Code
+claude mcp remove --scope user kira-lite
+
+# npm
+npm uninstall -g @offgridsec/kira-lite-mcp
+
+# Remove config
+rm -rf ~/.kira-lite
+```
+
+For Cursor/Windsurf/VS Code, remove the `kira-lite` entry from your MCP configuration file.
+
 ## Privacy
 
 Kira-Lite collects **anonymous, non-personalized** telemetry (tool usage stats, rule IDs, scan durations). No source code, file paths, or personal data is ever collected.
 
 **Opt out** by setting `KIRA_TELEMETRY=off` in your environment.
 
-See [PRIVACY.md](https://www.npmjs.com/package/@offgridsec/kira-lite-mcp?activeTab=code) for full details.
+<details>
+<summary><strong>Full privacy details</strong></summary>
+
+### What we collect
+
+- **Tool usage** — which scan tools are called (e.g. `scan_code`, `scan_file`)
+- **Scan statistics** — number of lines scanned, number of findings, severity counts, scan duration
+- **Vulnerability rule IDs and titles** — which rules triggered (e.g. `KIRA-JS-SQLI-001`, `CWE-89`)
+- **Environment metadata** — Node.js version, platform (win32/linux/darwin), Kira-Lite version
+- **Anonymous device ID** — a randomly generated UUID stored locally at `~/.kira-lite/device-id`
+
+### What we do NOT collect
+
+- **No source code** — your code never leaves your machine
+- **No file paths** — we do not log file names or directory structures
+- **No personal information** — no names, emails, IP addresses, or account identifiers
+- **No code snippets** — scan findings reference rule IDs only, not your actual code
+- **No project metadata** — no repository names, branch names, or commit hashes
+
+### How to opt out
+
+```bash
+# macOS / Linux — add to ~/.bashrc or ~/.zshrc
+export KIRA_TELEMETRY=off
+```
+
+```powershell
+# Windows (PowerShell)
+[System.Environment]::SetEnvironmentVariable("KIRA_TELEMETRY", "off", "User")
+```
+
+When telemetry is off, **no data is sent anywhere**. Kira-Lite functions exactly the same.
+
+Telemetry is sent to [PostHog](https://posthog.com) (US region) using an anonymous device ID. This ID is a random UUID generated on first run and stored locally. It cannot be traced back to you.
+
+Questions? Reach us at [contact@offgridsec.com](mailto:contact@offgridsec.com).
+
+</details>
 
 ## License