eden/README.md

# EVE Intelligence

A self-hosted EVE Online intelligence assistant built with **Bun, SvelteKit/Svelte 5, convex-svelte, self-hosted Convex and bun:sqlite**.

Milestone 1: connect multiple EVE characters, synchronize assets, and view a **reference-price estimate** through the same service in chat and the Assets page. JEV makes a typed intent judgment; application code owns authorization and arithmetic.

**This is an initial implementation, not a production-audited release.** The offline quick start downloads no reference archives; the explicit production worker imports real EVE Ref, Hoboleaks, and CCP SDE data. Manufacturing, market-depth liquidation, capital routing and general-purpose conversational answers are not implemented.

## Quick start: offline fixture slice

Requires Bun **1.3.14** (the tested runtime). No API credentials or Docker required for the explicitly labeled demo.

```sh
bun install --frozen-lockfile
bun run reference:fixture
APP_MODE=demo bun run dev
```

Open <http://localhost:5173>. Use **Estimate all assets**, **Browse assets**, or `/value` and `/assets`. The two pilots and prices are synthetic. Item names come from the compiled SQLite fixture database, not runtime raw JSON. Natural-language intent routing requires a TypeSafe key; without one the app honestly supports only explicit commands.

```sh
bun test
bun run check
bun run build
APP_MODE=demo APP_ORIGIN=http://localhost:3000 ORIGIN=http://localhost:3000 bun run start
```

The estimate excludes unpriced/unknown items and blueprint copies. ESI average prices are **not Jita buy orders**, firm quotes, liquidity estimates or replacement costs. Stale/incomplete data blocks valuation rather than silently becoming zero.

## This instance: Infisical + Pangolin

Use [the live deployment guide](docs/live-setup.md) for `dev.evebot.app`, the read-only Infisical machine identity, safe secret injection, and the persistent Docker deployment on host ports 5173/3210. Public settings live in `config/dev.env`; credentials are not committed.

## Live local development (standalone alternative)

1. Copy `.env.example` to private `.env`. Keep `APP_MODE=live`.
2. Generate application secrets with `bun run keys:generate`. This creates `.env.keys` with mode `0600` and refuses to overwrite it. Merge those values into `.env` (do not commit either file). Encryption/signing/bridge keys are distinct.
3. Start only your local backend: `docker compose up -d backend`.
4. Generate the deployment admin key: `docker compose exec backend ./generate_admin_key.sh`. Put it in `CONVEX_SELF_HOSTED_ADMIN_KEY` in `.env`. This key is CLI-only, not a browser or web-container credential.
5. Configure backend function environment, then deploy:

   ```sh
   bun run convex:configure
   bunx convex dev --once
   ```

   `APP_AUTH_ISSUER`, `APP_AUTH_JWKS` and `CONVEX_BRIDGE_SECRET` must be set in **Convex's environment**, not merely the Docker process environment. The configure script handles these three. Custom JWT audience is `eve-intelligence`; the public JWKS data URI avoids a boot dependency on the web server.

6. Register an EVE application and exact callback at <https://developers.eveonline.com/>. Set `EVE_CLIENT_ID`, `EVE_CALLBACK_URL`, and `EVE_CLIENT_SECRET` for a confidential web client. A public PKCE client leaves the secret blank. Initial requested scope is only `esi-assets.read_assets.v1`.
7. Set `ESI_USER_AGENT` with your actual operator contact. Optional `TYPESAFE_API_KEY` enables server-side JEV routing. Set public/internal Convex URLs as described in `.env.example`.
8. Build the fixture reference database and start `bun run dev`. Connect a character, synchronize it, and add more characters with **Connect EVE Character**. Each connects explicitly to the current application user.

**Important:** the fixture DB contains only a handful of types. Live assets absent from it remain explicitly unpriced/unknown. Do not describe a fixture-backed report as a complete real-character valuation. See [full-import handoff](docs/reference-operations.md) before ingesting real releases.

The first verified EVE character creates an application user; there is no EVE-account-wide lookup. Reconnecting a character to a different application user or with a changed owner hash fails closed. Account merging/recovery and unlink/revocation UX are not yet implemented; this is a deployment limitation, not an implicit ownership transfer policy.

## Single-host Docker Compose

Compose uses Convex's default SQLite backend; it introduces no other datastore.

- `backend`: persistent Convex SQLite volume, API bound to loopback by default (the configured Pangolin deployment explicitly overrides this).
- `web`: Bun web service with read-only reference volume.
- `reference-worker`: dedicated one-shot heavy-ingestion process (`tools` profile).
- `dashboard`: optional loopback-only management UI (`admin` profile).

For local container use, set `APP_ORIGIN` and `APP_AUTH_ISSUER` to `http://localhost:3000` and the EVE callback to `http://localhost:3000/auth/eve/callback`. Repeat `convex:configure` after changing issuer.

```sh
docker compose up -d backend
# Configure/deploy Convex as above before starting live web.
# Explicit production archive import (~109 MiB for the reviewed releases):
docker compose --profile tools run --rm --build reference-worker
docker compose up -d --build web
# Optional management UI:
docker compose --profile admin up -d dashboard
```

Invoking the `tools` worker explicitly imports **production archives** into `/app/data/reference`, the shared web/worker volume. `--check` fetches metadata only. Fixture imports require an explicit `--fixture` override and a separate demo output directory/volume; never use a fixture worker against the live volume.

For remote exposure use HTTPS reverse proxies for the app and Convex browser WebSocket/API endpoints. `PUBLIC_CONVEX_URL` must be browser-reachable, while Compose's `CONVEX_URL=http://backend:3210` is internal. Configure exact origins/callbacks. Keep backend/admin ports on loopback/management networks. The backend defaults to the immutable digest exercised by this repository’s smoke test. The optional dashboard’s `latest` default is a development convenience: pin a tested digest before production. See [security gates](docs/security.md).

## Structure

```text
src/lib/domain/             framework-independent capabilities, assets, money, future domain ports
src/lib/server/             Bun-only composition, ESI/SSO, crypto, Convex and SQLite adapters
src/lib/server/assistant/   typed JEV intent routing and allowlisted deterministic dispatch
src/convex/                validated user state, secure bridge, browser-safe reactive queries
src/routes/                Svelte views and same-origin server endpoints
workers/                   reference compiler entrypoint (outside Convex actions)
fixtures/reference/        tiny documented source-shape fixtures
scripts/                   key generation and Convex configuration
tests/                     offline deterministic regression tests
docs/research/             current official-source evidence and captured ESI contracts
```

- [Architecture](docs/architecture.md) and [milestone scope](docs/milestone.md)
- [Remaining-feature roadmap](docs/roadmap.md): inventory and personal finances first, public signup readiness, then markets, industry, capital logistics, and corporation workspaces
- [First-batch parallel worktree tasks](docs/parallel-worktrees.md): task briefs, dependency waves, shared-file ownership and acceptance gates
- [Reference lifecycle and production imports](docs/reference-operations.md)
- [ESI cache, pagination and compatibility operations](docs/esi-operations.md)
- [EVE/SSO and 2026 structure/ACL evidence](docs/research/eve.md)
- [EVE Ref schemas/provenance](docs/research/reference.md)
- [JEV research and integration constraints](docs/research/jev.md)
- [Convex/Bun platform evidence](docs/research/platform.md)
- [Security invariants](docs/security.md)
- [Executed checks and remaining verification gates](docs/verification.md)

## Operational limits

- The configured development deployment has passed live TypeSafe routing and public Convex WebSocket checks; the operator has confirmed real EVE sign-in, asset synchronization, and matching Assets/chat valuation totals for one character. Live multi-character linking and revocation/transfer scenarios remain separate checks.
- Production imports use reviewed source adapters and immutable SQLite artifacts. Station data is not imported; 21 dangling blueprint references in the reviewed release are preserved explicitly rather than fabricated. See reference operations and the verification record for executed import checks and limitations.
- Asset synchronization runs on demand in a single Bun web process. Convex leases/CAS protect staging and token rotation, but durable background character-sync job recovery and scheduled refresh are future work.
- ESI page collections are not transactional snapshots. Stability checks reduce risk; cache rollover/mutation may require a later retry.
- Location IDs are shown explicitly as unresolved. Fitted/nested assets are distinct ESI items; no contents multiplier is applied to ship prices.
- Conversations/execution summaries persist for authenticated live users; this first UI does not yet provide a history browser. A pending guest request is kept only in tab `sessionStorage` and rechecked after login/sync.
- Reference-source state is local to the worker/artifact volume for this milestone; future Convex jobs may initiate/check it without extracting archives inside Convex.
- Add snapshot/session/execution retention, unlink/revocation, key rotation and restore-tested backups before multi-user production. Preserve encryption keys with backups: losing them loses access to stored credentials.

EVE Online is a trademark of CCP Games. This project is not endorsed by CCP.