argus-code 0.2.0__tar.gz

argus_code-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,68 @@
+name: Bug report
+description: Something doesn't work the way it should
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. The more specific you can
+        be about what you ran and what you saw, the faster this gets fixed.
+
+        **For security issues**, please use [SECURITY.md](https://github.com/KrishBhimani/argus-code/blob/main/SECURITY.md) instead of a public issue.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+      description: What did you think would happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to reproduce
+      description: |
+        Step-by-step. A repro repo, JSONL fixture, or exact command beats a
+        prose description. If the bug is about parsing a session, include
+        the smallest JSONL line that triggers it (with sensitive content
+        scrubbed).
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        Please include:
+        - OS (Windows / macOS / Linux + version)
+        - Python version (`python --version`)
+        - Argus version (`argus --version`)
+        - How you installed it (pipx, uv tool, git clone, etc.)
+      placeholder: |
+        OS: macOS 14.5
+        Python: 3.12.4
+        Argus: 0.2.0
+        Install: pipx install argus-code
+      render: markdown
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output (optional)
+      description: Any relevant error messages, stack traces, or terminal output.
+      render: shell
+    validations:
+      required: false

argus_code-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/KrishBhimani/argus-code/security/advisories/new
+    about: Please report security issues privately via GitHub Security Advisories — see SECURITY.md for details.

argus_code-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,46 @@
+name: Feature request
+description: Suggest a new feature or change in behavior
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Argus prioritizes "things you cannot get from `ccusage` or other
+        existing tools" — feature ideas that lean on the local-only data
+        in `~/.claude/` are especially welcome.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Lead with the problem, not the solution. What can't you do today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: |
+        How you imagine it working — what would you click on, what would you
+        see? Screenshots of mockups, references to other tools, or rough
+        sketches all welcome.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other ways to solve this you ruled out, and why?
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Related issues, links, screenshots — anything else useful.
+    validations:
+      required: false

argus_code-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,36 @@
+## Summary
+
+<!-- What does this PR do, and why? Skip the "what" if the diff makes it
+obvious; the "why" is rarely obvious from the diff alone. -->
+
+## Type of change
+
+- [ ] Bug fix (`fix:`)
+- [ ] New feature (`feat:`)
+- [ ] Docs / README / comments (`docs:`)
+- [ ] Refactor / cleanup (`refactor:` / `chore:`)
+- [ ] CI / build (`ci:` / `build:`)
+
+## Related issue
+
+<!-- e.g. Closes #42, Fixes #17, or "n/a" for unsolicited changes. -->
+
+## Test plan
+
+<!-- What did you actually run to convince yourself this works?
+  - New tests added / existing tests updated?
+  - Manual smoke test? On which OS?
+  - Edge cases checked? -->
+
+## Screenshots (UI changes only)
+
+<!-- Delete this section if it's not a UI change. -->
+
+## Checklist
+
+- [ ] Tests added or updated for the change
+- [ ] `npm test` and `npm run build` pass locally
+- [ ] Considered cross-platform behavior (especially if touching paths or fs)
+- [ ] Updated `README.md` / `SECURITY.md` if user-facing behavior or the
+      security model changed
+- [ ] No `console.log` or debug-only code left in

argus_code-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+node_modules/
+dist/
+*.log
+.env
+.env.local
+.argus/
+.DS_Store
+.vitest-cache/
+coverage/
+
+# Personal planning notes — kept local, not published
+docs/
+
+# Python build / virtualenv / cache artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.egg-info/
+build/

argus_code-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,307 @@
+# Argus architecture
+
+A guide to how the pieces fit together, aimed at anyone about to change
+the code. Read this before adding a feature so you know where things
+live and why. README.md is the user-facing intro; this is the
+contributor's map.
+
+## The 30-second mental model
+
+Claude Code writes a `.jsonl` file every time you use it, one file per
+session, at `~/.claude/projects/<project>/<session-id>.jsonl`. Each
+line is one event: a user message, an assistant reply, a tool call, or
+a tool result.
+
+Argus is two things:
+
+1. A **watcher** that reads those files as they grow, validates each
+   line, and stores it in a local SQLite database at
+   `~/.argus/argus.db`. The database is also an **archive** —
+   rows survive even after Claude Code's own cleanup deletes the
+   source `.jsonl`.
+2. A **local web server** that queries SQLite and serves a static
+   dashboard at `http://localhost:4242`.
+
+No network calls (except optional `argus pricing refresh`). No
+telemetry. No LLM calls. Everything stays on your machine.
+
+The backend is Python (≥3.11, FastAPI + uvicorn + pydantic + watchdog
++ stdlib sqlite3 + typer). The dashboard is Astro + ECharts, statically
+built. Both ship together in the `argus-code` wheel on PyPI.
+
+## The data layer
+
+SQLite in WAL mode. Two tables you'll touch most often:
+
+### `sessions`
+One row per session. **Pre-summed totals** for fast listing:
+
+- `id` (e.g. `claude_code:abc123…`), `agent`, `project_path`
+- `started_at`, `ended_at`, `duration_sec`
+- `total_*_tokens` (fresh_input, output, cache_read, cache_write)
+- `total_cost_usd`, `primary_model`, `turn_count`
+
+Use for: the Sessions table, "Top sessions in window" lists, anything
+that needs a whole-session view.
+
+### `turns`
+One row per back-and-forth with Claude — **the source of truth** for
+everything else.
+
+- `id`, `session_id`, `sequence`, `timestamp`
+- `model`, `model_raw`
+- Per-turn token counts (fresh_input, output, cache_read,
+  cache_write_5m, cache_write_1h)
+- `tool_calls_count`, `cost_usd`, `metadata`
+
+Use for: anything that needs **per-day** granularity — Overview
+heatmap, Trends line chart, "Last N days" totals.
+
+> ⚠️ **Critical rule for windowed views.** Query `turns` by their
+> `timestamp`, not `sessions` by `started_at`. A session that started
+> 3 weeks ago but had turns this week must still count toward "last 7
+> days". The canonical helper is
+> `Repository.aggregateTurnsByDay(cutoffIso)`.
+
+### Other tables
+- `tool_calls` — one row per tool invocation; powers the Tools page
+- `prompts`, `transcript_segments` (+ FTS5 siblings) — opt-in full-text
+  search indexes
+- `file_offsets` — per-file ingest cursor so we re-read only new bytes
+- `parse_errors` — surfaced on Settings → Parse errors
+- `alerts` — detector findings shown on the Overview "What needs
+  attention" card; written **only** by the alert scheduler (see below)
+- `app_meta` — schema version, search-indexing flag
+
+## The write path (ingest)
+
+```
+~/.claude/projects/<proj>/<session-id>.jsonl
+        │
+        │  watchdog Observer emits add/change events
+        ▼
+python/argus/adapters/claude_code/    parse one line at a time
+        │
+        │  pydantic models validate each line
+        ▼
+python/argus/collector/pipeline.py    convert to sessions/turns/tool_calls
+        │
+        ▼
+python/argus/store/repository.py      upsert into SQLite (idempotent — re-ingest is safe)
+        │
+        ▼
+~/.argus/argus.db
+```
+
+Two ingest paths share the same `ingest_file` function:
+
+1. **First run** (`python/argus/collector/first_run.py`) — at startup,
+   walks every file. Recent files first (foreground), older files in a
+   background thread. Dashboard becomes useful within a few seconds.
+2. **Watcher** (`python/argus/collector/watcher.py`) — keeps running
+   after first-run, picks up new lines as Claude Code writes them. A
+   per-path 100ms debouncer coalesces fs-event bursts before handing
+   the path to a single ingest worker thread (SQLite WAL = one writer
+   at a time).
+
+## The read path (server + dashboard)
+
+```
+browser → http://localhost:4242
+        │
+        ▼
+python/argus/server/app.py         FastAPI app + uvicorn, binds 127.0.0.1 by default
+        │
+        ▼
+python/argus/server/api.py         /api/overview, /api/sessions, /api/tools, …
+        │
+        ▼
+python/argus/store/repository.py   parameterized SQL queries
+        │
+        ▼
+dashboard-dist/                    static HTML+JS bundled from dashboard/src/ (Astro + ECharts)
+```
+
+The dashboard is **statically built**. No server-side rendering, no
+Node in the browser. Pages just `fetch('/api/...')` and render with
+ECharts.
+
+## Detection (alerts)
+
+Beyond passively charting history, Argus runs **detectors** that flag
+behavior worth your attention. The flow reuses ingest's separation of
+concerns — readers read, one writer writes:
+
+```
+python/argus/detectors/registry.py   @register + available_detectors()
+        │  each detector is pure: detect(repo, now_iso) reads, returns Findings
+        ▼
+python/argus/collector/scheduler.py  the ONLY writer of alerts; runs every
+        │                            detector on a fixed cadence in a thread
+        ▼
+~/.argus/argus.db  →  alerts table   upsert by (detector, dedup_key);
+        │                            idempotent, with a resolved_at lifecycle
+        ▼
+python/argus/server/api.py           GET /api/alerts, GET /api/alerts/unseen,
+        │                            POST /api/alerts/{id}/seen
+        ▼
+dashboard "What needs attention"     card (hidden when empty) + a browser
+                                     Notification on unseen critical findings
+```
+
+Rules that matter:
+
+- **Detectors are pure.** `detect(repo, now_iso)` reads the DB and returns
+  `Finding` objects — it never writes. The scheduler owns every write. That
+  boundary is what makes detectors trivially unit-testable.
+- **Idempotent upserts.** `upsert_alert` keys on `(detector, dedup_key)` with
+  `ON CONFLICT … DO UPDATE … RETURNING id`, so re-running a detector updates
+  the existing row instead of duplicating.
+- **`resolved_at` lifecycle.** Each tick the scheduler resolves alerts whose
+  `dedup_key` is no longer in the detector's current findings
+  (`resolve_stale_alerts`). If the issue recurs, the row un-resolves and its
+  `seen_at` clears — so a tool that recovers then re-spikes notifies again
+  rather than staying silent.
+- **Self-registration.** Detectors `@register` in their module, imported for
+  side-effect in `python/argus/detectors/__init__.py` — same pattern as
+  adapters. Adding one is a new file + the import line; no scheduler edits.
+
+The v1 detector (`tool_error_rate_spike`) compares each tool's last-7-day
+error rate against its preceding 4-week baseline and fires when the rate
+multiplies past a threshold — or breaks from a zero baseline. Cost was
+deliberately *not* the v1 signal: it's meaningless for Pro/Max users who
+don't pay per token.
+
+## Scaffolding (`argus claude`)
+
+Separate from ingest/serve: a file-copy tool that stamps a `.claude/` setup
+(and a root `CLAUDE.md`) into a project — proactive config *before* the agent
+runs, not just observation after. No DB, no daemon, no schema.
+
+```
+python/argus/scaffold/storage.py     resolve template names across two tiers
+python/argus/scaffold/scaffolder.py  init: copy a template dir → a project
+python/argus/scaffold/snapshot.py    create: snapshot a project's .claude/
+        │
+        ▼
+templates/<name>/                    bundled (read-only, shipped in the wheel)
+~/.argus/templates/<name>/           user templates (read-write)
+```
+
+- **Two tiers, user-first.** `resolve_template` checks `~/.argus/templates/`
+  then the bundled `templates/`. The bundled `default` ships in the wheel via
+  `force-include`, exactly like `pricing/` and `dashboard-dist/`.
+- **Pure file copy.** No templating or substitution in v1. `init` copies each
+  template file to its matching path in the project (`CLAUDE.md` → root,
+  everything else → `.claude/`).
+- **`CLAUDE.md` is never overwritten**, even with `--force` — it's the user's
+  project brain. `create` is scoped to `.claude/` and excludes session/cache
+  dirs from the snapshot.
+
+## Conventions that matter
+
+A few patterns to absorb before adding code:
+
+- **Cutoff-string aggregation.** Windowed queries take an ISO
+  timestamp string and use `WHERE timestamp >= ?`. Pass `''` for
+  "all time" (empty string sorts below every real ISO string).
+  Examples: `aggregateTurnsByDay`, `toolCallsTotal`, `mcpToolCalls`.
+
+- **Top-level vs sub-agent ids.** Sub-agent rollup sessions contain
+  `/` in their `id`. SQL excludes them with
+  `session_id NOT LIKE '%/%'`; JS excludes them with the
+  `isTopLevel(id)` helper. Sub-agent token usage is rolled into the
+  parent's totals during ingest, so excluding them at read time
+  prevents double-counting.
+
+- **Migrations are append-only.** Never edit a published migration in
+  `python/argus/store/migrations/inline.py`. Add a new `MIGRATION_N+1`
+  and bump the schema version check in `db.py`. Production users have
+  data that depends on the exact SQL that already ran.
+
+- **Idempotent ingest.** `upsert_turn`, `upsert_session`, etc. all use
+  `ON CONFLICT(id) DO UPDATE`. Re-ingesting a file from offset 0 is
+  safe — useful for backfilling derived data after a schema change.
+
+- **HTML-escape every user-controlled string.** Anything from the
+  JSONL that ends up in `innerHTML` goes through `escapeHtml()` from
+  `dashboard/src/scripts/format.ts`. The only HTML allowed through
+  raw is `<mark>` from FTS5 snippets, via `safeSnippet()`.
+
+- **CSRF Origin check.** All non-GET `/api/*` routes verify the
+  `Origin` header is loopback. Implemented as FastAPI middleware in
+  `python/argus/server/app.py`. Defends against random tabs in your
+  browser hitting argus while it's running.
+
+- **Path safety.** `discover_session_files` calls `Path.resolve(strict=True)`
+  on each candidate and rejects anything that doesn't canonicalise
+  under `~/.claude/`. Defends against a hostile symlink planted in
+  `projects/` pointing at e.g. `/etc/passwd`. On Windows the
+  containment check lowercases both sides so case differences in the
+  canonical path don't silently reject every candidate.
+
+- **Adapter registry.** Adapter classes self-register via the
+  `@register` decorator (`python/argus/adapters/registry.py`).
+  `available_adapters()` returns every registered class whose
+  `is_present()` is True. Adding a new adapter (Codex, OpenClaw,
+  Hermes, …) is one new folder + one `@register` — zero edits to CLI,
+  watcher, pipeline, or server.
+
+## Where things live
+
+```
+python/argus/
+  cli.py                    argus start / search / pricing / claude / wipe (typer)
+  adapters/
+    base.py                 Adapter protocol + ParseError
+    registry.py             @register + available_adapters()
+    claude_code/            JSONL parsers, discovery, history.jsonl
+  collector/                pipeline, watcher, first-run, backfills, alert scheduler
+  detectors/                alert detectors (pure reads) + @register registry
+  scaffold/                 argus claude: template storage / init / snapshot
+  pricing/                  LiteLLM-derived price table + cost compute
+  store/                    SQLite repository + migrations
+  server/                   FastAPI app (app.py) + routes (api.py)
+  schema/                   pydantic data models
+
+dashboard/
+  src/
+    layouts/Default.astro   nav, footer, font, styles
+    pages/                  one .astro per route
+    scripts/                api client, charts, formatters
+    styles/global.css       single theme stylesheet
+dashboard-dist/             built dashboard, shipped in the wheel as data
+
+pricing/                    bundled LiteLLM price tables (shipped in wheel as data)
+templates/                  bundled .claude/ scaffolding templates (shipped in wheel as data)
+tests/                      pytest suite, mirrors python/argus/ layout
+~/.argus/argus.db           SQLite DB (created on first run)
+~/.argus/templates/         user-saved scaffolding templates (argus claude template create)
+~/.claude/                  source data we read from
+```
+
+## What's deliberately NOT here
+
+- **No embeddings, no vector DB.** Search is SQLite FTS5 — inverted
+  index, BM25 ranking, sub-millisecond, fully offline.
+- **No external APIs** except the optional `argus pricing refresh`
+  (single HTTP GET to LiteLLM's GitHub).
+- **No message queues or external workers.** Concurrency is at most three
+  in-process threads: the file watcher, the HTTP server, and a lightweight
+  detector scheduler. No brokers, no cron, no separate processes.
+- **No auth.** Loopback binding is the security model — see
+  [SECURITY.md](./SECURITY.md).
+
+## Common changes and where to start
+
+| Want to… | Touch these |
+|---|---|
+| Add a new dashboard page | `dashboard/src/pages/<name>.astro`, add nav link in `dashboard/src/layouts/Default.astro` |
+| Add a new API endpoint | `python/argus/server/api.py`, add a `repo.<method_name>()` in `python/argus/store/repository.py` |
+| Add a new SQL table or column | New `MIGRATION_N+1` in `python/argus/store/migrations/inline.py`, bump schema check in `db.py`, add `repo` method, add pydantic model in `python/argus/schema/types.py` |
+| Parse a new JSONL field | `python/argus/adapters/claude_code/schemas.py` (pydantic), wire into `pipeline.py` |
+| Tweak cost computation | `python/argus/pricing/compute.py`, then re-ingest to recompute via a backfill |
+| Add a new chart | `dashboard/src/scripts/charts.ts` (theme is shared) |
+| Add a new adapter (Codex, OpenClaw, Hermes, …) | New folder `python/argus/adapters/<agent>/` + `@register class` in `adapter.py`. No edits to CLI / watcher / pipeline / server. |
+| Add an alert detector | New file in `python/argus/detectors/` with a `@register` class whose pure `detect()` returns `Finding`s, plus the side-effect import in `detectors/__init__.py`. The scheduler picks it up automatically. |
+| Change the bundled scaffold template | Edit files under `templates/default/`; they're force-included into the wheel. New top-level dirs need a `force-include` entry in `pyproject.toml`. |

argus_code-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# Contributing to Argus
+
+Thanks for being here. Argus is a one-person project at this point, so
+the bar for contributions is "does it make the tool better for people
+running it?". Bug fixes, docs improvements, and small features are all
+welcome — please skim this file before opening a big PR so we're not
+working at cross-purposes.
+
+If you're new to the codebase, **read [ARCHITECTURE.md](./ARCHITECTURE.md)
+first** — it's a 5-minute tour of how the pieces fit together.
+
+## Quick start
+
+```sh
+git clone https://github.com/KrishBhimani/argus-code.git
+cd argus-code
+uv sync               # creates .venv and installs deps + dev tools
+uv run pytest         # ~215 tests, ~20s
+uv run argus start    # fast iteration loop — runs directly from source
+```
+
+`uv run argus start` runs the Python source directly. No build step.
+Change a file, restart, see the result.
+
+If you don't have `uv` yet: <https://docs.astral.sh/uv/getting-started/installation/>.
+
+## Running the built form
+
+CI builds and tests on every push. To smoke-test the built wheel
+locally exactly as a user would:
+
+```sh
+cd dashboard && npm ci && npm run build && cd ..
+cp -r dashboard/dist dashboard-dist          # bundle the dashboard
+uv build                                     # wheel + sdist in dist/
+uv tool install ./dist/argus_cli-*.whl       # install globally
+argus start
+```
+
+## Tests
+
+```sh
+uv run pytest                # one-shot
+uv run pytest -k <expr>      # filter by test name
+uv run pytest tests/store/   # by directory
+uv run pytest --cov=argus    # with coverage
+```
+
+Tests live in a sibling `tests/` tree mirroring `python/argus/`
+(e.g., `python/argus/store/repository.py` → `tests/store/test_repository.py`).
+New features need new tests. Bug fixes need a regression test that
+fails before the fix and passes after. See [TESTING.md](./TESTING.md)
+for the full catalog.
+
+## CI
+
+`.github/workflows/test.yml` runs on every push and PR:
+
+- **Test matrix:** Ubuntu, macOS, Windows × Python 3.11, 3.12, 3.13.
+- **Dashboard build** (release-only): runs `npm ci && npm run build`
+  before `uv build` to bundle the static dashboard into the wheel.
+
+The Windows runner is non-negotiable — path normalisation, WAL `-shm`
+cleanup, and short-name path quirks are all platform-sensitive.
+
+If CI fails on a platform you don't have, mention it in the PR and we'll
+help debug rather than asking you to set up a Windows VM.
+
+## Code style
+
+- Type-annotated Python (`from __future__ import annotations`,
+  `int | None` over `Optional[int]`).
+- Match the existing style. There's no separate lint config — read the
+  neighboring files and mimic.
+- Run `uv run pytest` before pushing. CI is a backstop, not a replacement.
+- Conventional commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`,
+  `ci:`) for clarity. Not strictly enforced, but helpful.
+
+## Areas to be careful
+
+A few corners of the codebase have hidden complexity. If you're
+touching them, take a beat.
+
+### Path handling on Windows
+
+The Windows filesystem is case-insensitive but Python's string
+equality isn't. `discover_session_files()` lowercases both sides of
+the canonical-root containment check before comparing, so case
+differences in resolved paths don't silently reject every candidate.
+If your change touches path comparison logic, test on Windows CI
+before assuming it works.
+
+### Pricing tables (`pricing/*.json`)
+
+These are generated from LiteLLM via `argus pricing refresh`. Don't
+hand-edit them. If you need to change pricing logic, look at
+`python/argus/pricing/compute.py`.
+
+### Schema migrations (`python/argus/store/migrations/inline.py`)
+
+Append-only. Never edit a published migration. Add a new `MIGRATION_N+1`
+and bump the `schema_version` check in `db.py`. SQLite in production
+has data that depends on the exact SQL that already ran.
+
+### Windowed aggregations
+
+For any "last N days" / windowed view, query the **`turns`** table by
+`timestamp`, NOT the **`sessions`** table by `started_at`. Session
+totals are pre-summed across the session's lifetime — using them for
+windowed views silently drops activity in sessions that started before
+the window and dumps multi-day spend onto the session's start date in
+heatmaps. The canonical helper is `Repository.aggregate_turns_by_day()`.
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the data-model rationale.
+
+### Adapters
+
+The `Adapter` protocol in `python/argus/adapters/base.py` is what the
+pipeline, watcher, and server depend on. Per-adapter packages
+self-register via `@register` in their `adapter.py`. If you're adding
+a new adapter (Codex, OpenClaw, Hermes, …), do not edit shared code
+to special-case it — express the per-agent behavior through the
+optional extension points (`extra_watch_paths`, `ingest_extra`,
+`sub_session_files_for`, `should_skip`, `normalize_model_name`).
+
+### Detectors and the alert scheduler
+
+Detectors (`python/argus/detectors/`) must stay **pure**: `detect()` reads
+the DB and returns `Finding`s, and that's it. The scheduler
+(`python/argus/collector/scheduler.py`) is the **only** thing that writes to
+the `alerts` table — don't blur that boundary by writing from a detector.
+Alerts are upserted on `(detector, dedup_key)` and reconciled each tick via
+`resolved_at`, so the key you choose for `dedup_key` *is* the identity of the
+thing being alerted on. See ARCHITECTURE.md → "Detection (alerts)".
+
+### Security model
+
+`SECURITY.md` lists the invariants this codebase deliberately
+maintains: `127.0.0.1` binding by default, CSRF Origin check, HTML
+escaping, symlink rejection, parameterized SQL, no postinstall scripts.
+If your change weakens any of those, call it out explicitly in the PR
+description so review can focus there.
+
+## Reporting bugs / requesting features
+
+Use the issue templates:
+
+- **Bug** — include OS, Python version, argus version, repro steps.
+- **Feature** — describe the problem first, the solution second.
+
+For **security issues**, do not open a public issue — see
+[SECURITY.md](./SECURITY.md) for the private reporting path.
+
+## License
+
+By contributing, you agree your code ships under the MIT license (same
+as the rest of the repo — see [LICENSE](./LICENSE)).

argus_code-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krish Bhimani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. 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.