cli-consumption 0.1.0__tar.gz → 0.2.0__tar.gz

cli_consumption-0.2.0/.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.0 → cli_consumption-0.2.0}/.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.0 → cli_consumption-0.2.0}/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.0 → cli_consumption-0.2.0}/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,20 @@ 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.
+
 ## Validate and review
 
 Run the quality gates documented in `AGENTS.md`, inspect the complete diff, then open a

cli_consumption-0.1.0/README.md → cli_consumption-0.2.0/PKG-INFO

@@ -1,3 +1,38 @@
+Metadata-Version: 2.5
+Name: cli-consumption
+Version: 0.2.0
+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
+Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
+Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
+Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai,cli,codex,observability,tokens,usage
+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.12
+Requires-Dist: alembic>=1.14
+Requires-Dist: pydantic>=2.10
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.15
+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
 
 CLI Consumption measures how AI coding CLIs use models, tokens, tools,
@@ -10,14 +45,17 @@ events. Local token counters are usage metadata, not billing records. Read the
 
 ## 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 +76,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
@@ -67,6 +111,7 @@ Use the provider name below with `--provider` to select one CLI explicitly.
 | Grok Build | `grok` | `~/.grok/sessions/` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
 | Kilo Code | `kilo` | `~/.local/share/kilo/kilo.db` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
 | Kimi Code CLI | `kimi` | `~/.kimi/sessions/` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
+| Mistral Vibe CLI | `mistral-vibe` | `~/.vibe/logs/session/` | Session-level token aggregates, user turns, tools, and compactions; no per-message timestamps or historical model attribution. |
 | OpenCode | `opencode` | `~/.local/share/opencode/opencode.db` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
 | OpenHands CLI | `openhands` | `~/.openhands/conversations/` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
 | Pi | `pi` | `~/.pi/agent/sessions/` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
@@ -133,6 +178,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:
@@ -146,6 +204,24 @@ 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](docs/decisions/0001-versioned-schema-migrations.md) for rollback
+and compatibility rules.
+
+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
@@ -170,6 +246,25 @@ 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.
 
+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.
+
 ## Commands
 
 | Command | Purpose |
@@ -179,13 +274,14 @@ 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.
 
 ## 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 .

cli_consumption-0.1.0/PKG-INFO → cli_consumption-0.2.0/README.md

@@ -1,31 +1,3 @@
-Metadata-Version: 2.5
-Name: cli-consumption
-Version: 0.1.0
-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
-Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
-Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
-Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: ai,cli,codex,observability,tokens,usage
-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.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-Dist: sqlalchemy>=2.0
-Requires-Dist: typer>=0.15
-Requires-Dist: uvicorn>=0.34
-Description-Content-Type: text/markdown
-
 # CLI Consumption
 
 CLI Consumption measures how AI coding CLIs use models, tokens, tools,
@@ -38,14 +10,17 @@ events. Local token counters are usage metadata, not billing records. Read the
 
 ## 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 +41,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
@@ -95,6 +76,7 @@ Use the provider name below with `--provider` to select one CLI explicitly.
 | Grok Build | `grok` | `~/.grok/sessions/` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
 | Kilo Code | `kilo` | `~/.local/share/kilo/kilo.db` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
 | Kimi Code CLI | `kimi` | `~/.kimi/sessions/` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
+| Mistral Vibe CLI | `mistral-vibe` | `~/.vibe/logs/session/` | Session-level token aggregates, user turns, tools, and compactions; no per-message timestamps or historical model attribution. |
 | OpenCode | `opencode` | `~/.local/share/opencode/opencode.db` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
 | OpenHands CLI | `openhands` | `~/.openhands/conversations/` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
 | Pi | `pi` | `~/.pi/agent/sessions/` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
@@ -161,6 +143,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:
@@ -174,6 +169,24 @@ 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](docs/decisions/0001-versioned-schema-migrations.md) for rollback
+and compatibility rules.
+
+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
@@ -198,6 +211,25 @@ 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.
 
+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.
+
 ## Commands
 
 | Command | Purpose |
@@ -207,13 +239,14 @@ 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.
 
 ## 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 .

cli_consumption-0.2.0/docs/architecture.md

@@ -0,0 +1,105 @@
+# Architecture
+
+## Goals
+
+CLI Consumption separates provider-specific extraction from provider-neutral storage
+and reporting. This lets users compare multiple AI coding CLIs without forcing their
+local formats into one parser.
+
+```text
+provider files -> adapter -> metadata-only snapshot -> SQL storage -> dashboard/CSV
+                                      |
+                                      +-> HTTPS collector -> central SQL storage
+```
+
+## Components
+
+- `adapters`: parse a CLI's local data into conversations, turns, model calls, tool
+  calls, context-pressure samples, bounded turn settings, compactions, and content-free
+  work-item intervals. Codex exposes the complete analytics contract. Aider, Amazon Q
+  Developer CLI, Amp, Cline CLI, Claude Code, Continue CLI, Crush, Cursor CLI, Gemini
+  CLI, GitHub Copilot CLI, Goose, Grok Build, Kilo Code, Kimi Code CLI, OpenCode,
+  OpenHands CLI, Pi, Plandex, and Qwen Code expose the reliable subset available in
+  each local store. The exact differences are maintained in
+  [Provider support](provider-support.md).
+- `models`: define the strict, versioned transport boundary shared by offline and API
+  ingestion.
+- `storage`, `schema`, and `migrations`: own the normalized schema, idempotent
+  replacement rules, automatic Alembic upgrades, legacy adoption, SQLite, and
+  PostgreSQL engine creation.
+- `api` and `sync`: offer an optional push workflow for recurring multi-machine use.
+- `dashboard`, `reporting`, and `exporting`: select complete conversation graphs,
+  provide an offline HTML view by default, and stream deterministic portable CSV tables
+  when explicitly requested.
+- `adapters.registry`: is the single source for canonical names, aliases, adapter
+  classes, default homes, detection markers, and support state.
+- `cli`: exposes the same capabilities through one executable.
+
+When Codex exposes its local thread graph, the adapter also records metadata-only
+subagent relationships. Agent filesystem paths and nicknames are intentionally
+discarded. Roles and statuses are reduced to fixed provider-neutral vocabularies, and
+the stored conversation `source` is a normalized format label rather than an arbitrary
+provider value.
+
+## Multi-machine alternatives
+
+### Copied files
+
+Copy provider metadata directories to a trusted machine and pass repeated `--source`
+options. This has no listening service, works offline, and is easiest to audit. It is
+recommended for personal use, occasional reports, and air-gapped environments.
+
+The trade-off is operational: users must schedule copies and keep machine clocks
+synchronized if they later analyze overlapping activity.
+
+### Central API
+
+Run `serve` with PostgreSQL and send snapshots using `sync`. Parsing stays on the source
+machine, so raw provider files do not cross the network. This works well for recurring
+collection and several workstations.
+
+The API is intentionally small. A bearer token protects ingestion; a production
+deployment still needs TLS, token rotation, backups, monitoring, and a reverse proxy
+or platform ingress. Read access is not exposed. The collector limits bodies to 32 MiB
+including chunked requests, accepts snapshot schema v1, and caps a snapshot at 250,000
+normalized records. `/api/v1/capabilities` publishes these limits and the supported
+schema range so clients can fail before uploading incompatible data.
+
+## Storage
+
+SQLite is the zero-configuration default. PostgreSQL is selected by passing a
+`postgresql+psycopg://` URL. Every database open upgrades through packaged Alembic
+migrations. An unversioned database is adopted only when its tables exactly match a
+published schema; an unknown, newer, or locally modified schema is refused. Migration
+revisions support SQLite and PostgreSQL and define a bounded downgrade, but application
+rollback can still require restoring a pre-upgrade backup. Operators must upgrade the
+server first and avoid mixed-version access during migration. The detailed policy is
+recorded in [ADR 0001](decisions/0001-versioned-schema-migrations.md).
+
+Conversation records use a provider-qualified stable ID. Repeated ingestion skips an
+identical or less complete record. A more complete copy atomically replaces the
+conversation and its child records.
+
+Workflow analytics use additive child tables: `work_items`, `context_samples`,
+`turn_settings`, and `compaction_events`. Snapshot schema v1 validates every record,
+rejects unknown fields, enforces normalized labels and relationships, and exposes only
+generic validation errors. A newer client sent to an older strict API is rejected
+before ingestion, so central deployments must upgrade the server first.
+
+Retention is an explicit two-step operation: `retention --keep-days N` reports what
+would be deleted, while `--apply` deletes old conversations (with cascading children),
+subagent relationships, and ingestion runs in one transaction.
+
+Time-bounded reporting selects conversations whose recorded activity overlaps the
+half-open `[since, until)` window. Once selected, the complete conversation and all its
+children are included; this is graph consistency, not timestamp-level redaction.
+Related subagent edges are included when either endpoint belongs to a selected
+conversation, while ingestion runs are filtered by their own timestamp. All tables are
+ordered by primary key. CSV output consumes streamed batches rather than materializing
+each table, and neutralizes text that spreadsheet software could execute as a formula.
+
+## Adapter qualification
+
+Adapters are introduced one at a time because local data formats are undocumented or
+can evolve independently. Each adapter must have synthetic fixtures, format detection,
+privacy tests, and a documented support level before it appears as supported.

cli_consumption-0.2.0/docs/decisions/0001-versioned-schema-migrations.md

@@ -0,0 +1,50 @@
+# ADR 0001: Versioned schema migrations
+
+- Status: Accepted
+- Scope: SQLite and PostgreSQL normalized storage
+
+## Context
+
+`create_all` can create missing tables but cannot safely evolve published columns,
+constraints, indexes, or data. CLI Consumption must preserve repeatable ingestion on
+both supported databases while rejecting unknown schemas rather than guessing how to
+modify them.
+
+## Decision
+
+Package Alembic revisions with the application and upgrade the database to the known
+head whenever storage is initialized. Every schema change must provide SQLite and
+PostgreSQL coverage, deterministic data conversion, and an explicit downgrade boundary.
+
+For databases created before revision tracking, inspect every recognized table before
+adoption. Stamp and migrate only an exact published layout, including explicitly known
+transitional layouts. Refuse databases with unknown columns, missing columns, unknown
+revision heads, or revisions newer than the running application. Do not fall back to
+`create_all` after a compatibility failure.
+
+The initial baseline records the published normalized schema. The next migration
+normalizes retained subagent roles and statuses and removes `agent_nickname`, which has
+no required analytical purpose. Its downgrade can recreate the column only with a
+content-free placeholder; it cannot recover discarded nicknames.
+
+## Deployment and rollback
+
+Back up a production database before upgrading. Stop or drain writers, deploy and
+initialize the server first, then upgrade sync clients. Do not run mixed application
+versions against a database during migration: an older writer may not understand the
+new layout or replacement semantics.
+
+Use the packaged downgrade only to a documented known revision and only after stopping
+newer writers. A schema downgrade does not guarantee application-level recovery when a
+migration deliberately discarded or transformed metadata. Restore the pre-upgrade
+backup when exact rollback is required.
+
+## Consequences
+
+- Fresh, legacy SQLite, legacy PostgreSQL, and already-versioned databases follow one
+  migration history.
+- Unknown or locally modified schemas fail closed with a generic compatibility error.
+- Releases that change storage must include migration, adoption, idempotency,
+  upgrade/downgrade, and both-dialect tests.
+- Operators gain automatic upgrades but remain responsible for backups, writer
+  coordination, and retention of those backups.

{cli_consumption-0.1.0 → cli_consumption-0.2.0}/docs/privacy.md

@@ -11,7 +11,8 @@ CLI Consumption measures activity; it does not archive conversations.
 - Whitelisted work-item categories, normalized technical status, and timing
 - Model input-to-context-window samples and bounded provider configuration labels
 - Timestamped compaction counts without replacement content or window identifiers
-- Metadata-only subagent relationships, roles, status, timing, and token counters
+- Metadata-only subagent relationships, normalized roles and status, timing, and token
+  counters; provider nicknames are not retained
 - Content hashes and event counts used only for deduplication
 
 ## Prohibited data
@@ -24,6 +25,7 @@ CLI Consumption measures activity; it does not archive conversations.
 - Commands, exit output, file-change details, MCP arguments/results, and item content
 - Raw rate-limit, credit, plan, or spend-control payloads
 - Original working directories and rollout paths in shared exports
+- Provider-supplied subagent nicknames and arbitrary role, status, or source labels
 
 Adapters may inspect a working directory transiently to apply an explicit project
 mapping, but persistence records only the resulting project label and mapping source.
@@ -36,8 +38,12 @@ objects, exit output, commands, paths, patches, messages, and item-specific payl
 discarded. Context samples persist only the latest model-call input-token count and the
 reported context-window size; cumulative payloads and rate-limit metadata are ignored.
 Turn configuration labels accept only bounded identifier-like values. Snapshot
-validation rejects unknown work categories, arbitrary statuses, malformed timestamps,
-out-of-range counters, and unconstrained analytics labels before opening a transaction.
+validation rejects unknown fields, unknown work categories, arbitrary roles or
+statuses, malformed timestamps, inconsistent token compositions, out-of-range
+counters, unconstrained analytics labels, broken relationships, snapshots above
+250,000 records, and API requests above 32 MiB before opening a transaction. Errors
+use generic codes and do not echo rejected values. Snapshot schema v1 is advertised by
+the collector capabilities endpoint so an incompatible client can stop before upload.
 
 ## Threat model
 
@@ -68,3 +74,22 @@ pseudonymized per-turn rows remain embedded so local filtering works. Provider n
 daily activity, durations, counts, token counters, configuration labels, statuses, and
 aggregate work patterns remain disclosed. Share-safe is a minimization profile, not
 anonymization.
+
+Time filters select complete conversations that overlap the requested window. They do
+not redact child records whose individual timestamps fall outside it; related subagent
+edges can also reveal activity around the boundary. Ingestion-run rows are selected by
+their own timestamp. CSV output neutralizes leading spreadsheet formula and control
+prefixes with an apostrophe, but still contains detailed normalized operational data.
+
+Provider diagnostics inspect local stores transiently and emit only provider name,
+documented aliases, support state, and one coarse compatibility status. They do not
+persist snapshots or reveal paths, conversation identifiers, record counts, malformed
+values, or exception text.
+
+Retention removes normalized rows, not provider source files, existing exports,
+database backups, database engine logs, reverse-proxy logs, or snapshots already sent
+elsewhere. A dry run reports aggregate deletion counts; `--apply` is required to
+delete. Operators remain responsible for retention and secure disposal of those
+residual copies. Project names, machine labels, model/tool names, stable IDs,
+timestamps, and activity aggregates remain sensitive wherever normalized databases or
+detailed CSV files survive.