`README.md`

35 lines
# AbramsOS

A household "rights operating system." Ingests receipts (Gmail), warranties, recall feeds, and service guarantees into a unified ownership graph; runs a case engine that decides what's owned, what risks/deadlines apply, and what next action is worth taking.

**Status:** scaffold + Gmail-connector MVP. Single-user local. Port 9931. Standalone PG (`abrams_os`).

**Canonical spec:** [`docs/SPEC.md`](docs/SPEC.md). Roadmap in [`docs/ROADMAP.md`](docs/ROADMAP.md). Architecture in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Schema in [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md). Compliance posture in [`docs/COMPLIANCE.md`](docs/COMPLIANCE.md). Engineering guardrails in [`AGENTS.md`](AGENTS.md).

## Run locally

```bash
npm install
createdb abrams_os                 # one-time
psql -d abrams_os -f db/schema.sql # idempotent
cp .env.example .env                  # then fill ENCRYPTION_KEY + Google OAuth via /secrets
npm start                             # → http://localhost:9931
```

## Architecture in one paragraph

Connectors (Gmail today, more later) drop raw evidence into `source_message`. The ingestion pipeline normalizes purchases into `purchase` + `purchase_item` and links them to assets. A case engine (later) reads the graph plus a versioned rights-rule corpus and produces drafts for the user to approve. Everything that happens lands in `audit_log`. Side-effecting actions are gated by an approval-policy engine; nothing leaves the system without an explicit consent grant.

## What's built today

- Express server on `:9931` with `/healthz`, `/`, `/connectors`, `/purchases`
- 8-table PG schema (user, consent, connector, source_message, document, purchase, purchase_item, audit_log)
- Google OAuth round-trip (`/auth/google/start` → `/auth/google/callback`)
- Gmail message sync (`POST /api/connectors/:id/sync`) — pulls last 90 days of receipt-shaped mail
- Heuristic receipt extractor (regex over subject/body); local-Ollama fallback hook (TODO)
- Liquid-glass UI shell with dark/light toggle and sort+density grid on `/purchases`

## What's deferred

Recall ingestion, medical/DME tables, claim composer, card-benefit corpus, multi-tenant household, mobile, e-sign, Kamatera deploy. See `docs/ROADMAP.md`.