@hasna/economy 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this repository are tracked here. This project follows semantic versioning for published npm packages when practical.
 
+## @hasna/economy 0.3.9 - 2026-08-04
+
+Release-only bump. Four PRs merged after `0.3.8` and were never published, because
+this repo has no workflow that runs `npm publish` — the registry sat at `0.3.8`
+while `main` accumulated a contracts migration, a data-correctness fix and a
+metadata correction.
+
+**Breaking for server operators.** `HASNA_ECONOMY_STORAGE_MODE` (and the
+`ECONOMY_STORAGE_MODE` alias) are retired for server backend selection. They are
+now *rejected at startup with a migration hint* rather than normalized, so a
+half-migrated deployment fails loudly instead of quietly serving the wrong store.
+The server data backend is `sqlite | postgresql`, selected by the presence of
+`HASNA_ECONOMY_DATABASE_URL` alone. If you set `HASNA_ECONOMY_STORAGE_MODE=cloud`
+to reach Postgres, unset it and rely on the database URL.
+
+- **#27** `fix(client)` — hard-fail a half-applied cloud flip instead of silently
+  serving local data. An `API_URL` set *without* an `API_KEY` previously resolved
+  to `local` with no warning, byte-identical to an unconfigured host: the CLI
+  served the local SQLite store while the operator had pointed it at the cloud
+  API — a different dataset rendered as plausible spend numbers. It now reports
+  `misconfigured` and refuses. An unconfigured machine (neither variable set)
+  stays silently local; that negative control is covered by a test.
+- **#28** `fix(contracts)` — migrate `storage.mode` to `storage.backend` for
+  contract kit `0.9.0`; declare `hosting` and `serviceSurfaces` in
+  `hasna.contract.json`. Bumps `@hasna/contracts` `^0.4.2` -> `^0.9.0`.
+- **#29** `fix(server)` — make the runtime speak the `0.9.0` backend vocabulary it
+  declares; `isCloudMode()` is replaced by `resolveEconomyServerBackend()` and
+  `isPostgresBackend()` (both internal — neither was ever exported from the
+  package root).
+- **#30** `fix(package)` — describe Gemini CLI support as legacy rather than
+  active, and name the Gemini API billing ingest separately. Google retired the
+  Gemini CLI on 2026-06-18.
+
 ## @hasna/economy 0.3.7 - 2026-07-24
 
 Reconciliation release: `main` had diverged from the published npm line. The `0.3.x`
@@ -29,10 +62,6 @@ three-way merge that keeps **both** histories.
   (and with it the `cloud schedule install|status|remove` commands) and
   `src/lib/fleet-sync.ts`. The MCP `sync` tool no longer reports `cloud_pushed` /
   `cloud_pulled` because `SyncAllResult` no longer carries them.
-- Replaced the `@hasna/agent-registry` and `@hasna/mcp-harness` `file:../open-*`
-  sibling pins with the registry ranges (`^0.1.0`) that every published tarball has
-  carried anyway. `bun install`, `tsc` and `src/mcp/http.test.ts` no longer require
-  unpublished sibling checkouts, and `package.json` now matches what actually ships.
 - Bumped strictly above the published `0.3.6` latest. (The `v0.3.6` tag commit itself
   carried `package.json` version `0.3.5`; the `0.3.6` publish bumped the registry
   without a follow-up commit.)

package/README.md

@@ -39,6 +39,15 @@ Open the dashboard with:
 economy dashboard --port 3456
 ```
 
+## Documentation
+
+- [CLI reference](docs/cli.md)
+- [Ingestion sources and attribution](docs/ingestion.md)
+- [Configuration, storage modes, and deployment](docs/configuration.md)
+- [REST API](docs/rest-api.md)
+- [MCP server](docs/mcp.md)
+- [OTLP/HTTP sidecar](docs/otel.md)
+
 ## CLI Output Defaults
 
 Economy CLI commands are compact by default so agent terminals do not fill their context with full records. High-cardinality list and status commands show essential columns, cap row counts, and print a hint when more rows are available.
@@ -55,7 +64,7 @@ economy todos list --verbose
 economy todos show 9.7
 ```
 
-`--json` remains the machine-readable path for commands that support it. Human output may truncate rows or long text; use `--json`, `--verbose`, `--limit`, or a `show`/detail command for complete data.
+`--json` remains the machine-readable path for commands that support it. Human output may truncate rows or long text; use `--json`, `--limit`, or a `show`/detail command for complete data. `--verbose` expands output where supported; its exact limit is command-specific (for example, `economy session --verbose` shows up to 50 requests).
 
 Status subcommands follow the same rule. For example, `economy goal status` prints a compact human summary by default and `economy goal status --limit 5` or `--verbose` controls how many goals are listed.
 
@@ -91,7 +100,7 @@ Gemini settings:
 }
 ```
 
-The MCP server exposes read tools for summaries, sessions, machines, pricing, daily spend, budgets, goals, provider billing, usage snapshots, savings, project/account/agent/cost-center breakdowns, and subscriptions. MCP tools are compact by default for agent context safety; high-cardinality tools accept `limit`, `verbose`, or `json=true` where raw structured output is useful. It also exposes mutation tools for budgets, pricing rows, goals, and subscriptions so coding agents can manage Economy data through the same validated surface as the CLI and REST API.
+The MCP server exposes read tools for summaries, sessions, machines, pricing, daily spend, budgets, goals, provider billing, usage snapshots, savings, project/account/agent/cost-center breakdowns, and subscriptions. MCP tools are compact by default for agent context safety; high-cardinality tools accept `limit`, `verbose`, or `json=true` where raw structured output is useful. It also exposes mutation tools for budgets, pricing rows, goals, and subscriptions so coding agents can manage Economy data through the same validated surface as the CLI and REST API. See the [MCP guide](docs/mcp.md) for HTTP mode and the complete tool list.
 
 ## Ingest
 
@@ -125,7 +134,7 @@ economy sync --recalculate
 economy sync --backfill-machine
 ```
 
-Full sync also imports active project metadata from `@hasna/projects` when the registry is available. The Codex source reads both legacy `~/.codex/state_5.sqlite` and current Codewith `~/.codewith/state_5.sqlite` usage stores by default; explicit `HASNA_ECONOMY_CODEX_DB_PATH` and `HASNA_ECONOMY_CODEWITH_DB_PATH` values override those locations.
+Full sync also imports active project metadata from `@hasna/projects` when the registry is available. The Codex source reads both `~/.codex/state_5.sqlite` and the Codewith store at `~/.codewith/state_5.sqlite` by default; explicit `HASNA_ECONOMY_CODEX_DB_PATH` and `HASNA_ECONOMY_CODEWITH_DB_PATH` values override those locations.
 
 Account attribution is automatic when `@hasna/accounts` has a matching active, applied, or env-dir profile for the agent. Account identity is the email address plus coding agent, so `work@example.com` under Codex and Claude is reported as two accounts. You can also force attribution for a process with `ECONOMY_ACCOUNT=tool:name` or agent-specific overrides such as `ECONOMY_CODEX_ACCOUNT=codex:work`.
 
@@ -157,7 +166,7 @@ curl -X POST http://127.0.0.1:4318/ingest \
   -d '{"source":"app","cost_center":"alumia","cost_center_kind":"app","project_path":"/workspace/alumia","model":"gpt-5-mini","cost_usd":0.12,"input_tokens":1200,"output_tokens":300}'
 ```
 
-Accepted `/ingest` attribution fields include `cost_center`, `cost_center_kind`, `cost_center_id`, `attribution_tag`, `project_path`, `repo`, `account_key`, `account_tool`, `account_name`, `account_email`, and explicit `cost_usd`.
+Accepted `/ingest` attribution fields include `cost_center`, `cost_center_kind`, `cost_center_id`, `attribution_tag`, `project_path`, `repo`, `account_key`, `account_tool`, `account_name`, `account_email`, and explicit `cost_usd`. The [OTLP guide](docs/otel.md) documents both payload formats and all aliases.
 
 Subscription plans can be configured locally and are used by savings calculations:
 
@@ -187,7 +196,7 @@ OpenRouter-style model IDs ending in `:free` are treated as zero-cost variants e
 
 ## Billing
 
-Estimated costs can be reconciled with provider billing:
+Estimated costs can be reconciled with provider billing in local mode:
 
 ```bash
 economy billing sync --days 31
@@ -228,37 +237,16 @@ Start the server:
 economy-serve --port 3456
 ```
 
-Common endpoints:
-
-- `GET /health`
-- `GET /api/summary?period=today`
-- `GET /api/sessions?agent=codex&account=work@example.com&limit=20`
-- `GET /api/sessions/:id/requests`
-- `GET /api/models`
-- `GET /api/projects?period=month`
-- `GET /api/breakdown?by=agent&period=month`
-- `GET /api/breakdown?by=cost-center&period=month`
-- `GET /api/breakdown?by=loop&period=month`
-- `GET /api/accounts?period=month`
-- `GET /api/usage?period=month`
-- `GET /api/savings?period=month`
-- `GET /api/subscriptions`
-- `POST /api/subscriptions`
-- `DELETE /api/subscriptions/:id`
-- `GET /api/budgets`
-- `POST /api/budgets`
-- `DELETE /api/budgets/:id`
-- `GET /api/pricing`
-- `POST /api/pricing`
-- `DELETE /api/pricing/:model`
-- `GET /api/goals`
-- `POST /api/goals`
-- `DELETE /api/goals/:id`
-- `GET /api/billing?period=month`
-- `POST /api/sync`
-- `POST /api/billing/sync`
-
-Budget, goal, and subscription mutation endpoints validate agent scopes against `claude`, `takumi`, `codex`, `gemini`, `opencode`, `cursor`, `pi`, and `hermes`.
+The canonical API uses `/v1`; `/api` remains a legacy alias for the dashboard and older clients. For example:
+
+- `GET /health`, `/ready`, `/version`, and `/openapi.json`
+- `GET /v1/summary?period=today`
+- `GET /v1/sessions?agent=codex&account=work@example.com&limit=20`
+- `GET /v1/breakdown?by=cost-center&period=month`
+- `POST /v1/budgets`, `/v1/goals`, `/v1/pricing`, and `/v1/subscriptions`
+- `POST /v1/sync`, `/v1/billing/sync`, and `/v1/ingest`
+
+See the [REST API reference](docs/rest-api.md) for every route, response envelopes, authentication, and legacy aliases. The server publishes the current generated contract at `/openapi.json`.
 
 The server also serves the built dashboard when `dashboard/dist` is present. The dashboard includes account-scoped session filtering, subscription plan create/update/delete controls in Savings, and savings/usage/account tables for subscription-aware cost analysis.
 
@@ -282,22 +270,13 @@ economy menubar stop
 economy menubar uninstall
 ```
 
-## Cloud Sync
-
-Economy can push and pull local SQLite data through `@hasna/cloud` PostgreSQL sync:
-
-```bash
-economy cloud status
-economy cloud push
-economy cloud pull
-economy cloud sync
-```
-
 ## Data Directory
 
 Data is stored in `~/.hasna/economy/`.
 
-The main SQLite database lives at `~/.hasna/economy/economy.db`. Older `~/.economy/` data is auto-migrated on first open. Override the database path with `HASNA_ECONOMY_DB_PATH` or `ECONOMY_DB`.
+The main SQLite database lives at `~/.hasna/economy/economy.db`. Older `~/.economy/` data is copied on first open when the new directory does not exist. Override the database path with `HASNA_ECONOMY_DB_PATH` or `ECONOMY_DB`.
+
+For shared deployments, CLI and MCP can use a remote `/v1` API instead of local SQLite by setting `HASNA_ECONOMY_API_URL` and `HASNA_ECONOMY_API_KEY`. See [configuration](docs/configuration.md) for client resolution, server auth, Postgres mode, and all environment variables.
 
 ## Development
 
@@ -305,6 +284,7 @@ The main SQLite database lives at `~/.hasna/economy/economy.db`. Older `~/.econo
 bun test
 bun run typecheck
 bun run build
+bun scripts/sync-openapi.ts
 cd dashboard && bun run lint
 cd menubar && swift build -c release
 ```
@@ -313,19 +293,6 @@ cd menubar && swift build -c release
 
 Economy is published under the Apache-2.0 license. See [CONTRIBUTING.md](CONTRIBUTING.md) for local development and release hygiene, [SECURITY.md](SECURITY.md) for vulnerability reporting, [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations, and [CHANGELOG.md](CHANGELOG.md) for release notes.
 
-## HTTP mode
-
-Shared Streamable HTTP transport for multi-agent sessions (stdio remains the default):
-
-```bash
-economy-mcp --http              # http://127.0.0.1:8860/mcp
-MCP_HTTP=1 economy-mcp            # same
-economy-mcp --http --port 8815    # explicit port
-```
-
-- Health: `GET http://127.0.0.1:8860/health` -> `{"status":"ok","name":"economy"}`
-- Override port with `MCP_HTTP_PORT` or `--port`
-
 ## License
 
 Apache-2.0 -- see [LICENSE](LICENSE)

package/dashboard/README.md

@@ -1,73 +1,26 @@
-# React + TypeScript + Vite
+# Economy dashboard
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+The dashboard is the React/Vite UI served by `economy-serve`. It covers overview, sessions, models, projects, budgets, goals, usage, accounts, savings, fleet, reconciliation, pricing, and provider billing.
 
-Currently, two official plugins are available:
+## Development
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+Run the API from the repository root, then start Vite:
 
-## React Compiler
-
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+economy-serve --port 3456
+cd dashboard
+bun install
+bun run dev
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+The development build uses `http://localhost:3456` by default. Set `VITE_API_URL` at build/dev time to use another origin. The dashboard currently calls the server's legacy-compatible `/api` routes; the public canonical API is `/v1`.
 
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+## Validation
 
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+bun test
+bun run lint
+bun run build
 ```
+
+The root package build writes production assets to `dashboard/dist`; `economy-serve` serves those assets and provides SPA fallback routing.

package/docs/README.md

@@ -0,0 +1,12 @@
+# Economy documentation
+
+Economy can run as an on-machine SQLite application or as a client of a shared self-hosted HTTP service. These guides describe the current command and network surfaces:
+
+- [CLI reference](cli.md) — the `economy` command and the four installed binaries.
+- [Ingestion](ingestion.md) — supported sources, default paths, sync behavior, billing, and account attribution.
+- [Configuration and deployment](configuration.md) — data paths, environment variables, local/server modes, and authentication.
+- [REST API](rest-api.md) — canonical `/v1` routes, request conventions, probes, and legacy aliases.
+- [MCP server](mcp.md) — stdio/HTTP setup and the available tools.
+- [OTLP sidecar](otel.md) — OTLP metrics and the simplified `/ingest` payload.
+
+For generated API details, start `economy-serve` and open [`/openapi.json`](http://127.0.0.1:3456/openapi.json). The checked-in source is [`openapi/economy.json`](../openapi/economy.json).

package/docs/cli.md

@@ -0,0 +1,88 @@
+# CLI reference
+
+Installing `@hasna/economy` provides four binaries:
+
+| Binary | Purpose |
+| --- | --- |
+| `economy` | Ingest, query, and manage Economy data. |
+| `economy-mcp` | Run the MCP server over stdio or Streamable HTTP. |
+| `economy-serve` | Serve the REST API and built dashboard, or migrate a self-hosted database. |
+| `economy-otel` | Ingest OTLP/HTTP metrics or simplified cost events into local SQLite. |
+
+Use `<binary> --help` and `economy <command> --help` for the exact help emitted by the installed version.
+
+## Core commands
+
+The supported coding-agent values are `claude`, `takumi`, `codex`, `gemini`, `opencode`, `cursor`, `pi`, and `hermes`.
+
+| Command | Current behavior and principal options |
+| --- | --- |
+| `economy sync` | Ingest every local source, or select sources with `--claude`, `--takumi`, `--codex`, `--gemini`, `--opencode`, `--cursor`, `--pi`, `--hermes`, or `--loops`. Maintenance flags are `--force`, `--backfill-machine`, and `--recalculate`; `--verbose` prints source details. |
+| `economy today`, `week`, `month` | Auto-sync in local mode and print the corresponding summary. Auto-sync is skipped in cloud-client mode. |
+| `economy sessions` | List sessions. Filters: `--agent`, `--project`, `--account`, `--machine`, `--since`, and `--search`; `--limit` defaults to 20; `--format` is `table`, `compact`, `csv`, or `json`. |
+| `economy session <id>` | Show one session and its requests. IDs may be prefixes. `--limit` defaults to 20 and `--verbose` shows up to 50 requests. |
+| `economy top` | Rank expensive sessions with `-n`, `--agent`, and `--since`. |
+| `economy breakdown` | Group by `model`, `agent`, `project`, `account`, `cost-center`, `loop`, `app`, or `repo`; accepts `--since`, `--limit`, `--verbose`, and `--json`. |
+| `economy accounts [period]` | Account/profile totals for `today`, `week`, `month`, `year`, or `all`; accepts `--limit`, `--verbose`, and `--json`. |
+| `economy machines` | Machines represented in stored data; accepts `--limit` and `--verbose`. |
+| `economy fleet` | Shared summary plus per-machine rows; accepts `--period`, `--limit`, `--verbose`, and `--json`. |
+| `economy brief` | Fleet brief with `--since <24h|7d|ISO-date>`, `--machine <id|all>`, or `--json`. |
+| `economy usage [period]` | Quota/usage snapshots with `--agent`, `--limit`, `--verbose`, or `--json`. |
+| `economy savings [period]` | Subscription-versus-API-equivalent savings with `--agent` or `--json`. |
+| `economy watch` | Poll recent costs, or use `--daemon` to sync watched local paths. Also accepts `--interval`, `--agent`, and macOS `--notify`. In cloud mode it streams the API and does not ingest local files. |
+| `economy status` | Print one-line spend, fleet, storage, top-agent, and available quota status. |
+| `economy doctor` | Check source paths/token availability, storage mode, pricing gaps, deduplication, and billing drift. |
+| `economy init` | Print first-run local and cloud-client setup hints. |
+
+Human output for high-cardinality commands is intentionally capped. Use the command's `--json`, `--verbose`, or `--limit` option when available. JSON output is complete; `--verbose` has command-specific semantics, so consult `--help`.
+
+## Analysis and export
+
+| Command | Behavior |
+| --- | --- |
+| `economy export` | Export `sessions` or `requests` as CSV. `--period` accepts `today`, `week`, `month`, or `all`; `--output` writes a file instead of stdout. |
+| `economy compare <period1> <period2>` | Compare `today`, `yesterday`, `week`, `lastweek`, `month`, or `lastmonth`. |
+| `economy forecast` | Project the current month's total from the observed burn rate. |
+| `economy efficiency` | Show output/input ratio, cache-hit percentage, and cost per 1,000 output tokens by model. |
+| `economy estimate --model <id>` | Estimate cost from `--input` and `--output` token counts using the active pricing table. |
+| `economy tui` | Terminal dashboard; `--watch` refreshes at `--interval` seconds. |
+| `economy waybar` | Emit a Waybar-compatible JSON status object. |
+| `economy bar tui`, `bar waybar` | Aliases for the TUI and Waybar commands. |
+
+## Data management
+
+| Command group | Subcommands |
+| --- | --- |
+| `economy budget` | `set` (`--limit` required; optional `--project`, `--agent`, `--cost-center`, `--period`, `--alert`), `list` (`--limit`, `--verbose`), `remove <id>`. |
+| `economy goal` | `set` (`--limit` required; optional `--period`, `--project`, `--agent`), `list`, `status`, `remove <id>`. List/status accept `--limit` and `--verbose`. |
+| `economy project` | `add <path> [--name]`, `list`, `show <nameOrPath>`, `rename <path> <name>`, `remove <path>`. |
+| `economy pricing` | `list`, `set <model>`, `remove <model>`. Set accepts `--input`, `--output`, `--cache-read`, `--cache-write`, `--cache-write-1h`, and `--cache-storage`. |
+| `economy subscriptions` | `set` (requires `--provider` and `--plan`; optional `--agent`, `--fee`, `--included`), `list`, `remove <id>`. |
+| `economy billing` | `sync` (`--days`, provider selectors), `show --period`, and `diff --period`. Provider sync is local-only. |
+| `economy config` | Show config, `get <key>`, `set <key> <value>`, or `webhook-test`. See [configuration](configuration.md). |
+| `economy remove <type> <id>` | Top-level alias for removing a `budget`, `project`, `goal`, or `pricing` row. Alias: `rm`. |
+
+## Integrations and utilities
+
+| Command | Behavior |
+| --- | --- |
+| `economy serve --port <port>` | Start the REST API in-process. Equivalent server controls are documented under [`economy-serve`](configuration.md#rest-server). |
+| `economy dashboard --port <port>` | Start the server when necessary and open the dashboard URL. |
+| `economy mcp` | Print Claude Code, Codex, and Gemini MCP configuration; select one or use `--all`. |
+| `economy completion <shell>` | Print completion for `bash`, `zsh`, or `fish`. |
+| `economy menubar` | `install [--force]`, `start`, `stop`, or `uninstall` the macOS Economy Bar app. |
+| `economy brains` | `gather`, `train`, `model [set|clear]`, and `status`. Fine-tuning requires the optional `@hasna/brains` package; gathering does not. |
+| `economy events`, `economy webhooks` | Event emit/list/replay and event-subscription commands supplied by `@hasna/events`; use the nested `--help` for options. |
+| `economy todos` | Display the bundled Economy roadmap, filter tasks, or show a task ID. This is project planning data, not live service status. |
+
+## Other binary help
+
+```text
+economy-mcp [--http] [--port <port>]
+economy-serve [--port <port>]
+economy-serve migrate
+economy-serve version
+economy-otel [--port <port>]
+```
+
+`economy-mcp` and `economy-serve` support `--version`. See [MCP](mcp.md), [configuration](configuration.md), and [OTLP](otel.md) for environment controls and endpoints.

package/docs/configuration.md

@@ -0,0 +1,88 @@
+# Configuration and deployment
+
+## Local data
+
+The default data directory is `~/.hasna/economy/` and the SQLite database is `~/.hasna/economy/economy.db`. On first access, regular files in an older `~/.economy/` directory are copied when the new directory does not yet exist.
+
+| Variable | Effect |
+| --- | --- |
+| `HASNA_ECONOMY_DB_PATH` | SQLite path; takes precedence over `ECONOMY_DB`. |
+| `ECONOMY_DB` | Alternate SQLite path. `:memory:` is useful for tests. |
+| `HASNA_ECONOMY_CONFIG_PATH` | Path to `config.json`; defaults under the data directory. |
+| `ECONOMY_MACHINE_ID` | Machine identifier; otherwise Economy uses the normalized hostname. |
+| `ECONOMY_TAG` | Fallback attribution tag on locally written sessions/requests. |
+
+`economy config` reads and writes `config.json`. The defaults are `port=3456`, `default-period=today`, `auto-sync=true`, `sync-interval=30`, `alert-thresholds=[5,10,25,50,100]`, and `webhook-url=null`. At present, `webhook-url` drives budget notifications and `activeModel` drives `economy brains`; the other stored values are compatibility/settings metadata. Binary ports, periods, and watch intervals still come from command options or the environment described below.
+
+## Account attribution
+
+For an agent token such as `CODEX`, Economy checks these explicit forms before consulting `@hasna/accounts`:
+
+```text
+ECONOMY_CODEX_ACCOUNT_KEY or ECONOMY_CODEX_ACCOUNT
+ECONOMY_ACCOUNT_KEY       or ECONOMY_ACCOUNT
+```
+
+Values may be `tool:name` (for example `codex:work`) or a bare name/email. The structured form is:
+
+```text
+ECONOMY_CODEX_ACCOUNT_TOOL / _NAME / _EMAIL
+ECONOMY_ACCOUNT_TOOL       / _NAME / _EMAIL
+```
+
+The same agent-specific pattern applies to all eight supported agents. Account keys use the tool plus normalized email when available, otherwise the profile name.
+
+## CLI/MCP cloud client
+
+Local is the default. To route CLI and MCP data operations to a shared server, set:
+
+```bash
+export HASNA_ECONOMY_API_URL=https://economy.example.com
+export HASNA_ECONOMY_API_KEY='...'
+```
+
+URL plus key is itself a cloud-mode signal. You may explicitly set `HASNA_ECONOMY_STORAGE_MODE=cloud`; `self_hosted`, `remote`, and `hybrid` are accepted deprecated aliases. The resolver also accepts `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, and `ECONOMY_MODE`, plus unprefixed `ECONOMY_API_URL`/`ECONOMY_API_KEY` aliases. An existing `/v1` suffix is normalized, otherwise it is appended. Cloud mode with no key or an invalid URL fails rather than reading an unintended local dataset.
+
+In cloud-client mode, data commands use the HTTP API, and local auto-sync, explicit `economy sync`, and `economy billing sync` are skipped. Clients never need or use a Postgres DSN.
+
+## REST server
+
+Start the local server with either:
+
+```bash
+economy serve --port 3456
+economy-serve --port 3456
+```
+
+`ECONOMY_PORT` supplies the `economy-serve` default. `ECONOMY_BIND` (or `ECONOMY_HOST`) controls the local bind host. `ECONOMY_API_TOKEN` (or `HASNA_ECONOMY_API_TOKEN`) enables the local shared-token check; send it as `Authorization: Bearer ...` or `X-Economy-Token`.
+
+Without a local token, the current server defaults to `0.0.0.0` and API routes are unauthenticated. Set a token and an intentional bind address before exposing a local-mode server to another host.
+
+The server serves `dashboard/dist` and falls back to its `index.html` for non-API paths when those assets exist.
+
+## Self-hosted server
+
+The server backend follows the database URL alone — `postgresql` when one of these is set, `sqlite` when none is:
+
+```text
+HASNA_ECONOMY_DATABASE_URL
+ECONOMY_DATABASE_URL
+DATABASE_URL
+```
+
+`HASNA_ECONOMY_STORAGE_MODE` (and `HASNA_ECONOMY_MODE`, `ECONOMY_STORAGE_MODE`, `ECONOMY_MODE`) no longer selects a backend: the server refuses to start and prints a migration hint. Delete it and set a DSN instead. This is server-only — the CLI/MCP client still reads the mode variable described above.
+
+Apply migrations with `economy-serve migrate`. `ECONOMY_PG_POOL_MAX` defaults to 5. A non-loopback server also requires one of `HASNA_ECONOMY_API_SIGNING_KEY`, `HASNA_API_SIGNING_KEY`, or `API_KEY_SIGNING_SECRET`; API keys are then verified by `@hasna/contracts`. The signing secret belongs only on the server.
+
+See [REST API authentication](rest-api.md#authentication) for request headers and open probes.
+
+## Other services
+
+| Variable | Effect |
+| --- | --- |
+| `MCP_HTTP=1` | Run `economy-mcp` in Streamable HTTP mode instead of stdio. |
+| `MCP_HTTP_PORT` | MCP HTTP port; default 8860 and overridden by `--port`. |
+| `ECONOMY_OTEL_PORT` | OTLP sidecar port; default 4318 and overridden by `--port`. |
+| `ECONOMY_OTEL_BIND` | OTLP sidecar bind host; default `127.0.0.1`. |
+
+Source- and billing-specific environment variables are listed in [Ingestion](ingestion.md).

package/docs/ingestion.md

@@ -0,0 +1,47 @@
+# Ingestion
+
+`economy sync` imports local coding-agent usage into Economy's SQLite database. A sync with no source flag runs every source; one or more source flags limit the run. Reads such as `economy today` also auto-sync all local sources before querying.
+
+In cloud-client mode, CLI and MCP reads/writes go directly to the shared HTTP API. Local `sync` and `billing sync` deliberately do nothing in that mode; ingest on a machine running in local mode, or use the authenticated server ingest endpoints.
+
+## Sources
+
+| Source | Default input | Notes and overrides |
+| --- | --- | --- |
+| Claude Code | `~/.claude/projects/**/*.jsonl` | Imports assistant messages with usage, including cache tiers and supported pricing modifiers. Quota uses `~/.claude/.credentials.json`, `CLAUDE_OAUTH_TOKEN`, or `ANTHROPIC_OAUTH_TOKEN`. |
+| Takumi | `~/.takumi/projects/**/*.jsonl` | Uses the same JSONL ingestion format as Claude. |
+| Codex | `~/.codex/state_5.sqlite`, rollout JSONL, and `~/.codex/config.toml` | Overrides: `HASNA_ECONOMY_CODEX_DB_PATH`, `HASNA_ECONOMY_CODEX_CONFIG_PATH`. Quota uses `~/.codex/auth.json` or `CODEX_OAUTH_TOKEN`; `CODEX_USAGE_URL` can override the quota URL. |
+| Codewith (reported as Codex) | `~/.codewith/state_5.sqlite` and `~/.codewith/config.toml` | Overrides: `HASNA_ECONOMY_CODEWITH_DB_PATH`, `HASNA_ECONOMY_CODEWITH_CONFIG_PATH`. An explicit Codex DB path disables default Codewith discovery unless a Codewith DB path is also explicit. |
+| Gemini CLI | `~/.gemini/tmp` and `~/.gemini/history` | Overrides: `HASNA_ECONOMY_GEMINI_TMP_DIR`, `HASNA_ECONOMY_GEMINI_HISTORY_DIR`. |
+| OpenCode | `~/.local/share/opencode/storage/message/**/*.json` | Imports assistant-message usage and uses the recorded cost when present. |
+| Cursor | Cursor `/api/usage` and `/api/usage-summary` | Requires `CURSOR_SESSION_TOKEN` (or `CURSOR_API_TOKEN`). Creates daily usage snapshots and a subscription rollup when spend is present. |
+| Pi | `~/.pi/agent/sessions/**/*.json` | Override with `PI_CODING_AGENT_SESSION_DIR`. Uses recorded turn cost; a missing cost remains zero until pricing is repaired or the source records one. |
+| Hermes | `~/.hermes/state.db` | Imports session-level token and cost rollups. |
+| OpenLoops | `~/.hasna/loops/loops.db` | Override with `HASNA_ECONOMY_LOOPS_DB_PATH`; price with `HASNA_ECONOMY_LOOPS_MODEL` or `ECONOMY_LOOPS_MODEL`. Imports orchestration/judge `goal_runs.tokens_used` only, into `loop:*` cost centers. |
+
+Full, unfiltered sync also attempts to import active metadata from `@hasna/projects`. Missing files, optional registries, and unavailable quota credentials are skipped; use `--verbose` to see source-level diagnostics.
+
+## Incremental and repair behavior
+
+File/database state is cached in the `ingest_state` table, and request IDs are upserted and deduplicated. Consequently, normal repeated syncs are incremental.
+
+- `--force` clears the ingest-state entries for the supported sources and reprocesses them.
+- `--backfill-machine` fills empty `machine_id` values with `ECONOMY_MACHINE_ID` or the normalized hostname.
+- `--recalculate` prices token-bearing requests whose `cost_usd` is zero, then rerolls affected sessions. It reports buckets still missing usable pricing.
+- Budget webhooks are checked after a CLI or REST sync. Failed deliveries remain eligible for a later retry.
+
+## Account and cost-center attribution
+
+Economy first checks agent-specific overrides such as `ECONOMY_CODEX_ACCOUNT`, then generic `ECONOMY_ACCOUNT` overrides, then matching `@hasna/accounts` env-dir/applied/current profiles. An override may be `tool:name`, an email, or separate `*_ACCOUNT_TOOL`, `*_ACCOUNT_NAME`, and `*_ACCOUNT_EMAIL` fields. See [configuration](configuration.md#account-attribution).
+
+Apps and services can report explicit project, repository, account, attribution-tag, and cost-center fields through [`economy-otel`](otel.md). `ECONOMY_TAG` supplies a fallback attribution tag for records written through the local database helpers.
+
+## Provider billing
+
+`economy billing sync --days 31` imports ground-truth daily billing locally:
+
+- Anthropic: `HASNAXYZ_ANTHROPIC_LIVE_ADMIN_API_KEY` or `ANTHROPIC_ADMIN_API_KEY`.
+- OpenAI: `HASNAXYZ_OPENAI_LIVE_ADMIN_API_KEY` or `OPENAI_ADMIN_API_KEY`.
+- Gemini export: `HASNA_ECONOMY_GEMINI_BILLING_EXPORT_PATH`, `HASNAXYZ_ECONOMY_GEMINI_BILLING_EXPORT_PATH`, or `GEMINI_BILLING_EXPORT_PATH`.
+
+Gemini imports JSON arrays, objects with a `rows` array, JSONL, or simple CSV. `economy billing show` compares totals; `economy billing diff` applies the reconciliation threshold.

package/docs/mcp.md

@@ -0,0 +1,65 @@
+# MCP server
+
+`economy-mcp` uses stdio by default:
+
+```bash
+claude mcp add --transport stdio --scope user economy -- economy-mcp
+```
+
+Codex configuration:
+
+```toml
+[mcp_servers.economy]
+command = "economy-mcp"
+args = []
+```
+
+Gemini settings:
+
+```json
+{
+  "mcpServers": {
+    "economy": { "command": "economy-mcp", "args": [] }
+  }
+}
+```
+
+`economy mcp --all` prints these snippets. The MCP server uses the same local-versus-cloud Store selection as the CLI; configure a shared API with `HASNA_ECONOMY_API_URL` and `HASNA_ECONOMY_API_KEY` as described in [configuration](configuration.md#climcp-cloud-client).
+
+## Streamable HTTP
+
+```bash
+economy-mcp --http                 # http://127.0.0.1:8860/mcp
+MCP_HTTP=1 economy-mcp             # same
+economy-mcp --http --port 8815
+```
+
+`MCP_HTTP_PORT` supplies the default HTTP port. The transport binds to loopback, exposes `POST /mcp`, and exposes `GET /health`. Stdio remains the default when `--http`/`MCP_HTTP` is absent.
+
+## Tools
+
+Discovery helpers:
+
+- `search_tools`, `describe_tools`
+
+Cost and activity reads:
+
+- `get_cost_summary`, `get_sessions`, `get_session_detail`, `get_top_sessions`
+- `get_model_breakdown`, `get_project_breakdown`, `get_agent_breakdown`, `get_account_breakdown`, `get_cost_center_breakdown`
+- `get_daily`, `list_machines`, `get_usage`, `get_savings`, `get_billing_summary`
+
+Management and estimation:
+
+- `get_budget_status`, `set_budget`, `remove_budget`
+- `get_goals`, `set_goal`, `remove_goal`
+- `get_pricing`, `set_pricing`, `remove_pricing`, `estimate_cost`
+- `list_subscriptions`, `set_subscription`, `remove_subscription`
+- `sync`, `send_feedback`
+
+Shared agent-registry tools:
+
+- `register_agent`, `heartbeat`, `set_focus`, `list_agents`
+
+High-cardinality tools return compact text by default. Where the schema offers them, use `limit`, `verbose=true`, or `json=true`. Limits are clamped to 100 for MCP calls.
+
+The `sync` tool accepts `all`, any supported coding agent, or `loops`. It ingests on-box files only in local mode. In cloud-client mode it returns an explanatory no-op because all other data tools already use the shared API.