tracer-sh 0.3.4 → 0.3.6

package/README.md

@@ -10,14 +10,32 @@ During an incident, most time goes to switching between observability tools
 and gathering context — not fixing the problem. Tracer connects your providers
 to a single AI chat interface so you find the root cause in one place.
 
+## How it works
+
+```
+┌─────────┐       your API keys         ┌──────────────────┐
+│         │ ◄──────────────────────────►│  Observability   │
+│ Tracer  │                             │  Providers       │
+│  local  │       your API keys         ├──────────────────┤
+│         │ ◄──────────────────────────►│  LLM Providers   │
+└─────────┘                             └──────────────────┘
+```
+
+Everything runs on your machine. Your data stays local in an encrypted SQLite
+database. Tracer talks directly to your provider and LLM APIs using your own
+API keys — no intermediary servers, no telemetry, no data leaves your machine
+except the API calls you control.
+
 ## Debug
 
-Chat with an AI agent that queries your providers in real-time and finds root causes — all from a single conversation.
+Chat with an AI agent that queries your providers in real time and finds root
+causes — all from a single conversation.
 
-- Natural language investigation
+- Natural language investigation across all connected providers
 - Live query execution with inline charts
+- Attach evidence to any message — screenshots, log files, code, PDFs — via paperclip, drag-and-drop, or paste
 - Post-mortem reports — download as Markdown to share
-- Share investigations as PNG — drop the exported image back into Tracer to re-open the analysis
+- Share investigations as PNG — drop the exported image onto the sidebar to re-open the full analysis
 - Agent memory across sessions
 - Session history and cost tracking
 
@@ -25,65 +43,26 @@ Chat with an AI agent that queries your providers in real-time and finds root ca
 
 ## Settings
 
-Configure providers, LLM credentials, agent behavior, and memory. All data is stored locally — nothing leaves your machine except the API calls you configure.
+Configure providers, LLM credentials, integrations, and agent behavior. Each
+provider setup includes connectivity tests and guidance on creating
+least-privilege API keys.
 
-- Anthropic (Claude) and Google (Gemini) API keys
+- LLM backends: Anthropic (Claude), Google (Gemini via AI Studio or Vertex AI)
 - Data provider setup with connectivity tests
+- Jira integration
 - Thinking budgets and step limits
 - Agent memory management
 
 ![Settings page](docs/screenshots/settings_page.png)
 
-## How it works
-
-```
-┌─────────┐       your API keys         ┌──────────────────┐
-│         │ ◄──────────────────────────►│  Observability   │
-│ Tracer  │                             │  Providers       │
-│  local  │       your API keys         ├──────────────────┤
-│         │ ◄──────────────────────────►│  LLM Providers   │
-└─────────┘                             └──────────────────┘
-```
-
-Everything runs on your machine. Your data stays local in an encrypted SQLite
-database. Tracer talks directly to your provider and LLM APIs using your own API
-keys — no intermediary servers, no data leaves your machine except API calls you control.
-
-## Security
+## Supported providers
 
-Tracer is built **defense-in-depth**: your secrets — provider and LLM API keys,
-integration tokens, chat history, and agent memory — sit behind several independent
-layers, so no single failure exposes them.
-
-- **Local-only.** Nothing leaves your machine except the provider and LLM API calls you configure. No Tracer servers, no telemetry, no sync.
-- **Encrypted at rest.** The entire SQLite database is encrypted with SQLCipher (AES-256). On disk it is ciphertext — a stolen laptop, a copied `.db` file, or a backup is useless without the key.
-- **Machine-bound, user-scoped key.** A random 256-bit key is generated on first run and stored in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). It never leaves the machine and is scoped to your OS user, so another user on the same box can't read the database either.
-- **Hardened on disk.** The data directory is created owner-only (`0700`); if no keychain is available, the fallback key file is written `0600`.
-
-**Automatic and transparent.** New installs are encrypted from the first run. An
-existing plaintext database is migrated on the first launch of this version — the
-encrypted copy is verified and atomically swapped in, and no plaintext is left behind.
-There's nothing to enable.
-
-**CI / headless.** Where no keychain exists, supply the key yourself with
-`TRACER_DB_KEY` — a 64-character hex string (e.g. `openssl rand -hex 32`).
-
-**What this protects — and what it doesn't.** Encryption at rest defends the file
-(theft, backups, copies) and blocks other users on the same machine. It does **not**
-defend against you, the logged-in user, running code as yourself: the app must hold the
-key at runtime to read its own data, so anyone controlling your user session can too. No
-local-first app escapes this — it's the honest boundary of on-device encryption.
+**Data:** New Relic (NRQL), Google Cloud (Logs, Traces, Metrics, Errors), PostHog (HogQL)
 
-**Key loss means data loss.** Because the key lives only in your keychain, losing it (an
-OS reinstall or keychain reset) makes the database unrecoverable. For a safety net, back
-up the `tracer-sh` / `db-key` keychain value somewhere secure.
+**LLM:** Anthropic (Claude), Google (Gemini — AI Studio or Vertex AI)
 
-**Verify it yourself.** The raw file should be unreadable without the key:
-
-```bash
-sqlite3 ~/.tracer/data/tracer.db '.tables'    # → "Error: file is not a database"
-head -c 16 ~/.tracer/data/tracer.db | od -c   # → random bytes, not "SQLite format 3"
-```
+**Integrations:** Jira — the agent reads issue details and comment threads for
+incident context, and posts comments back only when you explicitly ask.
 
 ## Install
 
@@ -95,8 +74,6 @@ Requires [Node.js 20+](https://nodejs.org/).
 npx tracer-sh@latest
 ```
 
-`npx` is ephemeral — it runs the newest published version on every launch and isn't a pinned version.
-
 **Install a pinned copy:**
 
 ```bash
@@ -104,42 +81,69 @@ npm install -g tracer-sh
 tracer-sh
 ```
 
-The first run gets the latest version; it then stays on that version until you explicitly update — either with **Update now** in the app (click the version in the sidebar) or by re-running the install.
-
-**Which should I pick?** Use the global install if you want a stable version that only changes when you choose; use `npx` to always grab the newest with zero install.
+Either way, Tracer stays on its installed version until you explicitly update:
+click the version in the sidebar and hit **Update now**, or re-run the install
+command. Note that bare `npx tracer-sh` reuses npm's cached copy and does NOT
+check for new releases — use the in-app update or `npx tracer-sh@latest` to get
+the newest version.
 
-Open `http://localhost:3579`, go to **Settings** to add your API keys and choose an LLM — done.
+Open `http://localhost:3579`, go to **Settings** to add your API keys and
+choose an LLM — done.
 
 ## Headless / CLI
 
-Run an investigation from the terminal and get back the final analysis — so other tools and agents (including Claude Code) can drive Tracer:
+Run an investigation from the terminal and get back the final analysis — so
+other tools and agents (including Claude Code) can drive Tracer:
 
 ```bash
 tracer-sh analyze "Why did checkout error rate spike after 14:00 UTC?"
 ```
 
-Continue a prior run with `--session <id>`; pass `--json` for the full response (session id, queries, usage). Requires a running server.
+- `--session <id>` — continue a prior run with full context
+- `--provider <name>` — scope the investigation to one provider
+- `--json` — full response envelope (session id, queries, usage)
+- `tracer-sh --help` — usage for every subcommand
 
-## Supported Providers
+Requires a running server.
 
-**Data:** New Relic (NRQL), Google Cloud (Logs, Traces, Metrics, Errors), PostHog (HogQL)
+## Security
 
-**LLM:** Anthropic (Claude), Google (Gemini)
+Your secrets — API keys, integration tokens, chat history, agent memory — sit
+behind several independent layers:
 
-## Uninstall
+- **Local-only.** No Tracer servers, no telemetry, no sync.
+- **Encrypted at rest.** The entire SQLite database is encrypted with SQLCipher (AES-256). A stolen laptop, a copied `.db` file, or a backup is ciphertext without the key.
+- **Machine-bound, user-scoped key.** A random 256-bit key is generated on first run and stored in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). It never leaves the machine and other OS users can't read it.
+- **Hardened on disk.** The data directory is owner-only (`0700`); a keychain-less fallback key file is `0600`.
+
+Encryption is automatic — new installs are encrypted from the first run, and
+an existing plaintext database is migrated in place on first launch. In CI or
+headless environments without a keychain, supply the key yourself via
+`TRACER_DB_KEY` (64-char hex, e.g. `openssl rand -hex 32`).
+
+Two honest caveats. Encryption at rest defends the file, not your live
+session: anyone running code as your OS user can read what the app can read —
+that is the boundary of every local-first app. And the key lives only in your
+keychain, so losing it (OS reinstall, keychain reset) makes the database
+unrecoverable; back up the `tracer-sh` / `db-key` keychain value if you want
+a safety net.
+
+Verify it yourself:
 
 ```bash
-npm uninstall -g tracer-sh
+sqlite3 ~/.tracer/data/tracer.db '.tables'    # → "Error: file is not a database"
+head -c 16 ~/.tracer/data/tracer.db | od -c   # → random bytes, not "SQLite format 3"
 ```
 
-To also remove your local database (settings, sessions, API keys):
+## Uninstall
 
 ```bash
-rm -rf ~/.tracer
+npm uninstall -g tracer-sh
+rm -rf ~/.tracer    # also removes settings, sessions, API keys
 ```
 
-The database encryption key also lives in your OS keychain (service `tracer-sh`,
-account `db-key`). Remove it for a clean slate — on macOS:
+The database encryption key lives in your OS keychain (service `tracer-sh`,
+account `db-key`). On macOS:
 
 ```bash
 security delete-generic-password -s tracer-sh -a db-key
@@ -156,19 +160,10 @@ security delete-generic-password -s tracer-sh -a db-key
 
 ## Contributing
 
-Contributions are welcome! There are two main ways to help:
-
-**Report bugs or request features** — [open an issue](https://github.com/sholub-dev/tracer/issues). Include steps to reproduce for bugs, or a clear description for feature requests.
-
-**Submit a code change:**
-
-1. Fork this repo
-2. Create a branch (`git checkout -b fix/my-fix`)
-3. Make your changes and commit
-4. Push to your fork (`git push origin fix/my-fix`)
-5. Open a pull request against `master`
+**Report bugs or request features** — [open an issue](https://github.com/sholub-dev/tracer/issues) with steps to reproduce or a clear description.
 
-All PRs require approval before merging.
+**Submit a code change** — fork, branch, and open a pull request against
+`master`. All PRs require approval before merging.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracer-sh",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "type": "module",
   "description": "Local-first debugging & analysis platform",
   "license": "SEE LICENSE IN LICENSE",

package/packages/server/dist/{chunk-XFJVNMJI.js → chunk-LDYGR5S3.js}

@@ -154,14 +154,14 @@ _Flag if:_ Count is more than 20% lower than the baseline.
 ---
 
 ### Reporting Format
-After completing all applicable checks, report results as a table:
+After completing all applicable checks, report results as a table. (This verdict summary is the ONE permitted markdown table \u2014 each check's underlying data must still be shown via tool calls.)
 
 | Check | Current | Baseline (1w ago) | Delta | Status |
 |-------|---------|-------------------|-------|--------|
-| Response Time P99 | ... | ... | +X% | \u2705 Pass / \u26A0\uFE0F Flagged |
-| Transaction Error Rate | ... | ... | +X% | \u2705 Pass / \u26A0\uFE0F Flagged |
-| External Services Errors | ... | ... | ... | \u2705 Pass / \u26A0\uFE0F Flagged / \u2014 N/A |
-| Success Transactions | ... | ... | -X% | \u2705 Pass / \u26A0\uFE0F Flagged |
+| Response Time P99 | ... | ... | +X% | Pass / FLAGGED |
+| Transaction Error Rate | ... | ... | +X% | Pass / FLAGGED |
+| External Services Errors | ... | ... | ... | Pass / FLAGGED / N/A |
+| Success Transactions | ... | ... | -X% | Pass / FLAGGED |
 
 End with an overall verdict on its own line:
 - \`Service appears healthy.\` \u2014 all checks pass

package/packages/server/dist/{domain-knowledge-6MEHHDWL.js → domain-knowledge-KF3XTKCK.js}

@@ -4,7 +4,7 @@ import {
   NR_DOMAIN_KNOWLEDGE,
   NR_INSIDE_OUT_DEBUGGING,
   NR_SERVICE_HEALTH_RUNBOOK
-} from "./chunk-XFJVNMJI.js";
+} from "./chunk-LDYGR5S3.js";
 import "./chunk-ZAYYPDZP.js";
 export {
   NR_AUTH_STOP_RULE,