cli-consumption 0.1.1__tar.gz → 0.2.1__tar.gz

cli_consumption-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    env:
+      TEST_POSTGRESQL_URL: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/cli_consumption_test
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_DB: cli_consumption_test
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_USER: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d cli_consumption_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: "3.14"
+      - run: uv sync --locked --all-groups --all-extras
+      - run: uv run pre-commit run --all-files --show-diff-on-failure
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run ty check --output-format github
+      - run: uv run pytest --cov --cov-report=term-missing
+      - run: uv build
+      - name: Smoke test the minimal wheel
+        run: |
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          uv run --isolated --no-project --python 3.14 \
+            --with "${wheel}" python tests/smoke_minimal_install.py
+
+  compatibility:
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --all-groups --all-extras
+      - run: uv run pytest

{cli_consumption-0.1.1 → cli_consumption-0.2.1}/.github/workflows/release.yaml

@@ -84,13 +84,18 @@ jobs:
         with:
           enable-cache: true
           python-version: "3.14"
-      - run: uv sync --locked --all-groups
+      - run: uv sync --locked --all-groups --all-extras
       - run: uv run pre-commit run --all-files --show-diff-on-failure
       - run: uv run ruff format --check .
       - run: uv run ruff check .
       - run: uv run ty check --output-format github
       - run: uv run pytest --cov --cov-report=term-missing
       - run: uv build
+      - name: Smoke test the minimal wheel
+        run: |
+          wheel="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          uv run --isolated --no-project --python 3.14 \
+            --with "${wheel}" python tests/smoke_minimal_install.py
       - name: Upload distributions
         uses: actions/upload-artifact@v7.0.1
         with:

{cli_consumption-0.1.1 → cli_consumption-0.2.1}/AGENTS.md

@@ -6,7 +6,7 @@ Read this file, `README.md`, `CONTRIBUTING.md`, and the relevant documents under
 `docs/` before changing the repository. Keep changes scoped to one short-lived branch
 and one coherent pull request.
 
-The project is a Python 3.14+ package managed exclusively with `uv`. Do not introduce
+The project is a Python 3.12+ package managed exclusively with `uv`. Do not introduce
 another package manager, task runner, ORM, web framework, or migration tool without an
 accepted architecture decision.
 
@@ -39,6 +39,7 @@ accepted architecture decision.
 Run all of the following before requesting review:
 
 ```bash
+uv sync --all-extras --all-groups
 uv run pre-commit run --all-files
 uv run ruff format --check .
 uv run ruff check .

{cli_consumption-0.1.1 → cli_consumption-0.2.1}/CONTRIBUTING.md

@@ -6,7 +6,7 @@
 git switch main
 git pull --ff-only
 git switch -c feat/short-description
-uv sync --all-groups
+uv sync --all-extras --all-groups
 uv run pre-commit install
 ```
 
@@ -16,12 +16,26 @@ file manually.
 ## Make a change
 
 Keep provider parsing behind the adapter interface and normalized persistence behind
-the storage module. A new field must have a documented meaning across providers or be
-explicitly namespaced as provider-specific.
+the storage module. Register providers once in the adapter registry rather than adding
+parallel CLI or detection lists. A new field must have a documented meaning across
+providers or be explicitly namespaced as provider-specific.
 
 Do not add telemetry. Test fixtures must be synthetic and must not contain copied user
 conversations or credentials.
 
+Schema changes require a forward Alembic migration for both SQLite and PostgreSQL, an
+explicit downgrade boundary, legacy-adoption tests, and mixed-version deployment notes.
+Snapshot protocol changes must preserve strict validation, bounded payloads, generic
+errors, and the documented server-first upgrade sequence. Export changes must preserve
+deterministic ordering, bounded-memory CSV streaming, complete selected conversation
+graphs, and spreadsheet-formula neutralization.
+
+Provider readers must use the bounded file and JSONL helpers in `adapters/_shared.py`,
+must not follow direct provider-file symlinks, and must stay within the shared snapshot
+record budget. Every registered adapter test module must include a synthetic canary and
+assert its absence from the normalized snapshot; shared privacy tests cover all later
+output surfaces.
+
 ## Validate and review
 
 Run the quality gates documented in `AGENTS.md`, inspect the complete diff, then open a

{cli_consumption-0.1.1 → cli_consumption-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-consumption
-Version: 0.1.1
+Version: 0.2.1
 Summary: Analyze and consolidate AI coding CLI consumption across machines.
 Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
 Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
@@ -15,15 +15,22 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.14
-Requires-Dist: fastapi>=0.115
-Requires-Dist: httpx>=0.27
-Requires-Dist: psycopg[binary]>=3.2
+Requires-Python: >=3.12
+Requires-Dist: alembic>=1.14
+Requires-Dist: pydantic>=2.10
 Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: typer>=0.15
-Requires-Dist: uvicorn>=0.34
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: uvicorn>=0.34; extra == 'server'
+Provides-Extra: sync
+Requires-Dist: httpx>=0.27; extra == 'sync'
 Description-Content-Type: text/markdown
 
 # CLI Consumption
@@ -34,18 +41,22 @@ machines, and can send metadata-only snapshots to a central collector.
 
 It never stores prompts, responses, tool arguments, credentials, or raw provider
 events. Local token counters are usage metadata, not billing records. Read the
-[privacy boundary](docs/privacy.md) before sharing a database or report.
+[privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+before sharing a database or report.
 
 ## Quick start
 
-CLI Consumption requires Python 3.14 or newer and uses
+CLI Consumption requires Python 3.12 or newer and uses
 [`uv`](https://docs.astral.sh/uv/).
+Supporting 3.12–3.14 keeps the package usable on more existing development and CI
+images without changing its architecture; the compatibility matrix exercises all
+three versions.
 
 From a checkout, collect every supported CLI detected on the machine and generate a
 self-contained dashboard:
 
 ```bash
-uv sync
+uv sync --all-extras
 uv run cli-consumption collect --provider all
 uv run cli-consumption export --output reports
 ```
@@ -66,6 +77,12 @@ uv tool run cli-consumption collect --provider all
 uv tool run cli-consumption export --output reports
 ```
 
+The default installation covers local collection, SQLite storage, and exports. Install
+only the optional runtime capabilities you use: `cli-consumption[sync]` for the sync
+client, `cli-consumption[server]` for the collector service, and
+`cli-consumption[postgres]` for PostgreSQL. Extras can be combined, for example
+`cli-consumption[server,postgres]` on a central collector.
+
 To run the latest unreleased GitHub source:
 
 ```bash
@@ -104,7 +121,7 @@ Use the provider name below with `--provider` to select one CLI explicitly.
 
 Provider formats are internal and can change without notice. The detailed extraction
 rules and qualification versions are documented in
-[Provider support](docs/provider-support.md).
+[Provider support](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md).
 
 ## Collect copied data
 
@@ -126,6 +143,11 @@ Copy only the required provider data. For Codex, copy the `sessions/` directory
 never `auth.json` or other credentials. Globally identical conversation IDs are
 deduplicated, and the most complete copy wins.
 
+Provider files are untrusted. Monolithic JSON files are limited to 64 MiB, JSONL files
+to 256 MiB with an 8 MiB per-line limit, and a snapshot to 250,000 normalized records
+while it is being built. Direct provider-file symlinks are refused. `collect --strict`
+refuses to write a snapshot when malformed records were skipped.
+
 Map original working-directory prefixes to stable project labels with repeated
 `--project NAME=PATH_PREFIX` options. The longest matching prefix wins:
 
@@ -147,7 +169,7 @@ uv run cli-consumption collect --provider plandex \
 
 The dashboard can filter by time, provider, machine, project, and model. It reports
 activity, token composition, cache efficiency, latency and duration distributions,
-technical throughput, context pressure, work-item reliability, configuration cohorts,
+turn rate, context pressure, work-item reliability, configuration cohorts,
 compactions, subagent delegation, and ingestion quality. Availability varies by
 provider, as summarized in the table above.
 
@@ -162,6 +184,19 @@ Share-safe reports still disclose aggregate work patterns and remain private
 operational data. A technically completed turn is not a measure of task quality or
 productivity.
 
+Limit an export to conversations whose activity overlaps a half-open UTC window:
+
+```bash
+uv run cli-consumption export --output reports \
+  --since 2026-08-01 --until 2026-08-31
+```
+
+Dates denote UTC calendar boundaries; timestamps must include a timezone. An included
+conversation is exported with its complete child graph rather than partially redacted
+to the window. CSV rows are streamed in stable primary-key order. Spreadsheet formula
+prefixes in text cells are neutralized with a leading apostrophe; CSV remains a
+detailed operational-data export, not a share-safe format.
+
 ## SQLite and PostgreSQL
 
 A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:
@@ -175,6 +210,30 @@ uv run cli-consumption collect --provider all \
 Pass credentials through environment variables or a secret manager rather than shell
 history. `CLI_CONSUMPTION_DATABASE` can provide the database setting.
 
+Database schemas are upgraded automatically when a command opens them. Existing
+unversioned databases that exactly match a published schema are adopted before the
+upgrade; unknown or modified schemas are refused. Back up production databases before
+upgrading and do not run mixed application versions against one database while a
+migration is in progress. See the
+[migration decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0001-versioned-schema-migrations.md)
+for rollback and compatibility rules.
+
+Timezone-aware timestamps are normalized to fixed-width UTC strings during ingestion.
+Revision `0003` rewrites legacy timestamp text in bounded batches and adds an indexed
+conversation end-time path; see the
+[timestamp decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0002-canonical-utc-timestamps.md)
+for the exact representation and downgrade boundary.
+
+Preview retention before deleting normalized metadata:
+
+```bash
+uv run cli-consumption retention --keep-days 90 --database usage.sqlite
+uv run cli-consumption retention --keep-days 90 --database usage.sqlite --apply
+```
+
+The first command is a dry run. `--apply` deletes old conversations and their child
+rows, old subagent relationships, and old ingestion-run records.
+
 ## Central collector API
 
 Copied files are simplest for personal or air-gapped use. For recurring collection
@@ -196,8 +255,31 @@ uv run cli-consumption sync --provider all \
 ```
 
 The application refuses to bind beyond localhost without a token. Production
-deployments also need TLS and standard operational controls. See
-[Architecture](docs/architecture.md) for the trade-offs.
+deployments also need TLS and standard operational controls. The sync client refuses
+plain HTTP beyond loopback unless `--allow-insecure` is passed explicitly. See
+[Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md) for the trade-offs.
+
+Snapshots use strict schema version 1. The collector rejects request bodies larger
+than 32 MiB and snapshots containing more than 250,000 normalized records. A sync
+client checks `/api/v1/capabilities` before sending when the endpoint exposes it.
+Upgrade the server before clients whenever supported snapshot schemas change.
+
+## Provider diagnostics
+
+`providers` reads the central adapter registry. Its machine-readable mode checks local
+default stores and emits deterministic JSON:
+
+```bash
+uv run cli-consumption providers --json
+```
+
+Each provider reports one of `no-data`, `detected`, `compatible`, `degraded`, or
+`unsupported-schema`. Diagnostics parse enough metadata to assess compatibility but do
+not persist it and never include paths, identifiers, record contents, counts, or parser
+errors in their output. Schema version 2 also declares whether token counters are
+additive, conversation aggregates, context snapshots, or unavailable. Dashboard token
+per-turn percentiles use only additive providers rather than treating missing measures
+as zero.
 
 ## Commands
 
@@ -208,13 +290,18 @@ deployments also need TLS and standard operational controls. See
 | `serve` | Run the central collection API. |
 | `export` | Write the HTML dashboard and optional CSV tables. |
 | `providers` | List provider names and support status. |
+| `retention` | Preview or apply deletion of metadata outside a retention window. |
 
 Run `uv run cli-consumption COMMAND --help` for all options.
 
+`collect`, `export`, and `retention` accept `--json` for deterministic
+machine-readable results. `collect --strict` rejects snapshots containing malformed
+provider records before opening the destination database.
+
 ## Development
 
 ```bash
-uv sync --all-groups
+uv sync --all-extras --all-groups
 uv run pre-commit install
 uv run pre-commit run --all-files
 uv run ruff format --check .
@@ -225,9 +312,12 @@ uv build
 ```
 
 Development uses short-lived branches and squash-merged pull requests into protected
-`main`. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before
-changing the project.
+`main`. Read
+[CONTRIBUTING.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
+and [AGENTS.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/AGENTS.md)
+before changing the project. Security issues follow the private reporting guidance in
+[SECURITY.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/SECURITY.md).
 
 ## License
 
-Licensed under the [Apache License 2.0](LICENSE).
+Licensed under the [Apache License 2.0](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/LICENSE).

{cli_consumption-0.1.1 → cli_consumption-0.2.1}/README.md

@@ -6,18 +6,22 @@ machines, and can send metadata-only snapshots to a central collector.
 
 It never stores prompts, responses, tool arguments, credentials, or raw provider
 events. Local token counters are usage metadata, not billing records. Read the
-[privacy boundary](docs/privacy.md) before sharing a database or report.
+[privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md)
+before sharing a database or report.
 
 ## Quick start
 
-CLI Consumption requires Python 3.14 or newer and uses
+CLI Consumption requires Python 3.12 or newer and uses
 [`uv`](https://docs.astral.sh/uv/).
+Supporting 3.12–3.14 keeps the package usable on more existing development and CI
+images without changing its architecture; the compatibility matrix exercises all
+three versions.
 
 From a checkout, collect every supported CLI detected on the machine and generate a
 self-contained dashboard:
 
 ```bash
-uv sync
+uv sync --all-extras
 uv run cli-consumption collect --provider all
 uv run cli-consumption export --output reports
 ```
@@ -38,6 +42,12 @@ uv tool run cli-consumption collect --provider all
 uv tool run cli-consumption export --output reports
 ```
 
+The default installation covers local collection, SQLite storage, and exports. Install
+only the optional runtime capabilities you use: `cli-consumption[sync]` for the sync
+client, `cli-consumption[server]` for the collector service, and
+`cli-consumption[postgres]` for PostgreSQL. Extras can be combined, for example
+`cli-consumption[server,postgres]` on a central collector.
+
 To run the latest unreleased GitHub source:
 
 ```bash
@@ -76,7 +86,7 @@ Use the provider name below with `--provider` to select one CLI explicitly.
 
 Provider formats are internal and can change without notice. The detailed extraction
 rules and qualification versions are documented in
-[Provider support](docs/provider-support.md).
+[Provider support](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/provider-support.md).
 
 ## Collect copied data
 
@@ -98,6 +108,11 @@ Copy only the required provider data. For Codex, copy the `sessions/` directory
 never `auth.json` or other credentials. Globally identical conversation IDs are
 deduplicated, and the most complete copy wins.
 
+Provider files are untrusted. Monolithic JSON files are limited to 64 MiB, JSONL files
+to 256 MiB with an 8 MiB per-line limit, and a snapshot to 250,000 normalized records
+while it is being built. Direct provider-file symlinks are refused. `collect --strict`
+refuses to write a snapshot when malformed records were skipped.
+
 Map original working-directory prefixes to stable project labels with repeated
 `--project NAME=PATH_PREFIX` options. The longest matching prefix wins:
 
@@ -119,7 +134,7 @@ uv run cli-consumption collect --provider plandex \
 
 The dashboard can filter by time, provider, machine, project, and model. It reports
 activity, token composition, cache efficiency, latency and duration distributions,
-technical throughput, context pressure, work-item reliability, configuration cohorts,
+turn rate, context pressure, work-item reliability, configuration cohorts,
 compactions, subagent delegation, and ingestion quality. Availability varies by
 provider, as summarized in the table above.
 
@@ -134,6 +149,19 @@ Share-safe reports still disclose aggregate work patterns and remain private
 operational data. A technically completed turn is not a measure of task quality or
 productivity.
 
+Limit an export to conversations whose activity overlaps a half-open UTC window:
+
+```bash
+uv run cli-consumption export --output reports \
+  --since 2026-08-01 --until 2026-08-31
+```
+
+Dates denote UTC calendar boundaries; timestamps must include a timezone. An included
+conversation is exported with its complete child graph rather than partially redacted
+to the window. CSV rows are streamed in stable primary-key order. Spreadsheet formula
+prefixes in text cells are neutralized with a leading apostrophe; CSV remains a
+detailed operational-data export, not a share-safe format.
+
 ## SQLite and PostgreSQL
 
 A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:
@@ -147,6 +175,30 @@ uv run cli-consumption collect --provider all \
 Pass credentials through environment variables or a secret manager rather than shell
 history. `CLI_CONSUMPTION_DATABASE` can provide the database setting.
 
+Database schemas are upgraded automatically when a command opens them. Existing
+unversioned databases that exactly match a published schema are adopted before the
+upgrade; unknown or modified schemas are refused. Back up production databases before
+upgrading and do not run mixed application versions against one database while a
+migration is in progress. See the
+[migration decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0001-versioned-schema-migrations.md)
+for rollback and compatibility rules.
+
+Timezone-aware timestamps are normalized to fixed-width UTC strings during ingestion.
+Revision `0003` rewrites legacy timestamp text in bounded batches and adds an indexed
+conversation end-time path; see the
+[timestamp decision](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/decisions/0002-canonical-utc-timestamps.md)
+for the exact representation and downgrade boundary.
+
+Preview retention before deleting normalized metadata:
+
+```bash
+uv run cli-consumption retention --keep-days 90 --database usage.sqlite
+uv run cli-consumption retention --keep-days 90 --database usage.sqlite --apply
+```
+
+The first command is a dry run. `--apply` deletes old conversations and their child
+rows, old subagent relationships, and old ingestion-run records.
+
 ## Central collector API
 
 Copied files are simplest for personal or air-gapped use. For recurring collection
@@ -168,8 +220,31 @@ uv run cli-consumption sync --provider all \
 ```
 
 The application refuses to bind beyond localhost without a token. Production
-deployments also need TLS and standard operational controls. See
-[Architecture](docs/architecture.md) for the trade-offs.
+deployments also need TLS and standard operational controls. The sync client refuses
+plain HTTP beyond loopback unless `--allow-insecure` is passed explicitly. See
+[Architecture](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/architecture.md) for the trade-offs.
+
+Snapshots use strict schema version 1. The collector rejects request bodies larger
+than 32 MiB and snapshots containing more than 250,000 normalized records. A sync
+client checks `/api/v1/capabilities` before sending when the endpoint exposes it.
+Upgrade the server before clients whenever supported snapshot schemas change.
+
+## Provider diagnostics
+
+`providers` reads the central adapter registry. Its machine-readable mode checks local
+default stores and emits deterministic JSON:
+
+```bash
+uv run cli-consumption providers --json
+```
+
+Each provider reports one of `no-data`, `detected`, `compatible`, `degraded`, or
+`unsupported-schema`. Diagnostics parse enough metadata to assess compatibility but do
+not persist it and never include paths, identifiers, record contents, counts, or parser
+errors in their output. Schema version 2 also declares whether token counters are
+additive, conversation aggregates, context snapshots, or unavailable. Dashboard token
+per-turn percentiles use only additive providers rather than treating missing measures
+as zero.
 
 ## Commands
 
@@ -180,13 +255,18 @@ deployments also need TLS and standard operational controls. See
 | `serve` | Run the central collection API. |
 | `export` | Write the HTML dashboard and optional CSV tables. |
 | `providers` | List provider names and support status. |
+| `retention` | Preview or apply deletion of metadata outside a retention window. |
 
 Run `uv run cli-consumption COMMAND --help` for all options.
 
+`collect`, `export`, and `retention` accept `--json` for deterministic
+machine-readable results. `collect --strict` rejects snapshots containing malformed
+provider records before opening the destination database.
+
 ## Development
 
 ```bash
-uv sync --all-groups
+uv sync --all-extras --all-groups
 uv run pre-commit install
 uv run pre-commit run --all-files
 uv run ruff format --check .
@@ -197,9 +277,12 @@ uv build
 ```
 
 Development uses short-lived branches and squash-merged pull requests into protected
-`main`. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before
-changing the project.
+`main`. Read
+[CONTRIBUTING.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/CONTRIBUTING.md)
+and [AGENTS.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/AGENTS.md)
+before changing the project. Security issues follow the private reporting guidance in
+[SECURITY.md](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/SECURITY.md).
 
 ## License
 
-Licensed under the [Apache License 2.0](LICENSE).
+Licensed under the [Apache License 2.0](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/LICENSE).

cli_consumption-0.2.1/SECURITY.md

@@ -0,0 +1,37 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made on the latest released version and on `main`. Older releases
+are not maintained as separate security branches. Upgrade to the latest release before
+reporting a problem that may already have been fixed.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Email
+`lombardo.guillaume@gmail.com` with the subject `CLI Consumption security report` and
+include:
+
+- the affected version and operating system;
+- the provider, command, or API surface involved;
+- reproduction steps using synthetic data;
+- the expected and observed impact;
+- any suggested mitigation.
+
+Do not send real prompts, responses, credentials, provider databases, or other private
+conversation data. Use a synthetic canary when demonstrating a disclosure.
+
+The maintainer will acknowledge the report, assess whether it crosses the documented
+privacy or security boundary, and coordinate a fix and disclosure when appropriate.
+
+## Security boundary
+
+Provider files and incoming snapshots are untrusted input. Relevant reports include
+content or credential disclosure, unsafe filesystem traversal, denial of service,
+authentication bypass, cross-machine data corruption, and generated dashboards that
+perform network requests or execute provider-controlled content.
+
+Operational exposure caused solely by publishing a normalized database or detailed CSV
+is outside the vulnerability boundary: those artifacts intentionally contain private
+operational metadata. The precise allowed and prohibited fields are documented in the
+[privacy boundary](https://github.com/Guillaume-Lombardo/cli-consumption/blob/main/docs/privacy.md).