feat(foundation): sign in, tenant scoping and audited mutations

Phase 1. The application runs: four seeded roles sign in through Better
Auth, land on a shell that reflects their permissions, and every mutation
writes its audit row inside the same transaction as the change.

Tenant isolation is the point of this phase, so it is structural rather
than remembered:

- forTenant(ctx) injects the organization on reads and stamps it on
  writes, overruling an organizationId the caller supplied. It refuses
  findUnique/update/delete outright, because those address a row by
  unique key alone and Prisma will not accept a non-unique filter beside
  it — a loud error beats a filter that looks applied and is not.
- A registry test parses schema.prisma and fails if a model with an
  organizationId column is not scoped. It immediately found Membership
  missing, which would have let one organization list another's members.
- authorize() answers 404, not 403, for a record in another tenant. A 403
  confirms the record exists.

Two defects were caught by exercising the running server rather than
reading the code. The Command Center listed modules without filtering by
permission, so an Operator could see that an Administration area existed
while the sidebar beside it hid that module. And a page calling
getTenantContext() directly threw an unhandled 401 on anonymous requests,
because a layout's redirect does not stop its pages — Next renders them in
parallel. Pages now use requireTenantContext(), which redirects; queries
and actions keep the throwing variant, where throwing is correct.

Three plan decisions were revised against the environment, each recorded
in DECISIONS.md with its evidence: npm replaces pnpm (corepack cannot
write its shims without administrator rights here), TypeScript is pinned
to 5.9 rather than 7.0 (the ESLint toolchain is not built against 7), and
the PostgreSQL image is pinned exactly — a floating tag restarted the
container against a data directory the newer server refused to open.

Verified: lint, typecheck, 26 tests and build all green; both migrations
apply to an empty database; all 10 CHECK constraints and the partial
unique index exist; the seed is idempotent; a wrong password and an
unknown e-mail return the same 401, and the sixth attempt returns 429.

The Command Center reports "not computable yet" instead of a status,
because three of the four inputs to the readiness score arrive in phases
4 to 6. A green light nobody computed is the one lie this product cannot
afford.

Author: TheAlphaOffshoreCode

.env.example

@@ -0,0 +1,31 @@
+# Copy to .env and fill in. Every variable is parsed by src/config/env.ts at
+# startup: a missing or malformed value fails the boot instead of surfacing as
+# undefined in production three days later.
+
+# ─── Database (required) ──────────────────────────────────────────────────
+# Pooled connection used by the application at runtime.
+DATABASE_URL="postgresql://ocean:ocean_dev_only@localhost:5433/ocean_command"
+# Unpooled connection used by Prisma Migrate. Same value locally; differs on
+# hosted PostgreSQL where the pooler cannot run DDL.
+DIRECT_DATABASE_URL="postgresql://ocean:ocean_dev_only@localhost:5433/ocean_command"
+
+# ─── Authentication (required) ────────────────────────────────────────────
+# Minimum 32 characters. Generate with: openssl rand -base64 32
+BETTER_AUTH_SECRET=""
+BETTER_AUTH_URL="http://localhost:3000"
+
+# ─── Providers (optional — defaults are the free/offline implementations) ──
+# mock (default). A real AIS feed is not part of the MVP.
+AIS_PROVIDER="mock"
+# open-meteo (default) | mock
+WEATHER_PROVIDER="open-meteo"
+# null (default) | openai | anthropic — Phase 9. Ships disabled on purpose.
+AI_PROVIDER="null"
+# OPENAI_API_KEY=""
+# ANTHROPIC_API_KEY=""
+
+# ─── Observability (optional) ─────────────────────────────────────────────
+# Protects /api/metrics. In production, if this is unset the route is NOT
+# registered at all — a metrics endpoint that fails open is an information leak.
+# METRICS_TOKEN=""
+LOG_LEVEL="info"

.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: lint · typecheck · test · build
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: ocean
+          POSTGRES_PASSWORD: ocean_ci
+          POSTGRES_DB: ocean_command
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U ocean -d ocean_command"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DATABASE_URL: postgresql://ocean:ocean_ci@localhost:5432/ocean_command
+      DIRECT_DATABASE_URL: postgresql://ocean:ocean_ci@localhost:5432/ocean_command
+      # CI-only value. Real secrets never live in a workflow file.
+      BETTER_AUTH_SECRET: ci-only-secret-not-used-anywhere-else-000
+      BETTER_AUTH_URL: http://localhost:3000
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - run: npm ci
+
+      - run: npx prisma generate
+
+      # Migrations run against an empty database on every build, which is what
+      # proves they still apply from scratch — not just on top of a dev database
+      # that has been drifting for weeks.
+      - name: Apply migrations
+        run: npx prisma migrate deploy
+
+      - name: Check for schema drift
+        run: |
+          npx prisma migrate diff \
+            --from-migrations prisma/migrations \
+            --to-schema-datamodel prisma/schema.prisma \
+            --shadow-database-url "$DATABASE_URL" \
+            --exit-code && echo "schema and migrations agree"
+
+      - run: npm run db:seed
+
+      - run: npm run lint
+
+      - run: npm run typecheck
+
+      # Integration tests run for real here: the service container means the
+      # tenant-isolation suite cannot silently skip.
+      - run: npm run test
+
+      - run: npm run build
+
+  secret-scan:
+    name: secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # TruffleHog diffs the range a push introduced, which needs the parent
+          # of the first commit. A shallow checkout makes multi-commit pushes
+          # fail for a reason that has nothing to do with secrets.
+          fetch-depth: 0
+
+      - uses: trufflesecurity/trufflehog@main
+        with:
+          extra_args: --results=verified,unknown

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 100,
+  "trailingComma": "all",
+  "arrowParens": "always"
+}

README.md

@@ -10,26 +10,42 @@ down and testable.
 
 ## Current state — read this first
 
-**Phase 0 (Architecture) is complete. There is no application code in this repository yet.**
+**Phases 0 (Architecture) and 1 (Foundation) are complete.** You can run the application, sign in
+as any of four roles, and every mutation is audited. The operational modules — fleet, operations,
+weather, risk, alerts, assets, incidents — are **not built yet**; they are phases 2 to 8.
 
-This is a deliberate first step, not an unfinished one. Phase 0 produced the domain model, the
-schema, the decision rules, the security model and the roadmap, so that Phase 1 starts from a
-design instead of discovering it mid-implementation.
-
-| Deliverable | Status |
+| Capability | Status |
 | --- | --- |
-| Product analysis and module scope | ✅ [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
-| Architecture, layers, module graph, provider strategy | ✅ [ARCHITECTURE.md](docs/ARCHITECTURE.md) |
-| Domain model, reference schema, indexes, constraints | ✅ [DATABASE.md](docs/DATABASE.md) |
-| Risk / weather-window / readiness formulas | ✅ [ARCHITECTURE.md §5](docs/ARCHITECTURE.md) |
-| Auth, RBAC matrix, multi-tenancy, threat model | ✅ [SECURITY.md](docs/SECURITY.md) |
-| Internal API contracts | ✅ [API.md](docs/API.md) |
-| Technology decisions, alternatives rejected | ✅ [DECISIONS.md](docs/DECISIONS.md) + [ADRs](docs/adr/) |
-| Roadmap with per-phase acceptance criteria | ✅ [ROADMAP.md](docs/ROADMAP.md) |
-| Application, database, UI | 🔜 Phase 1 |
-
-Nothing below is described as working unless this table says it is. The status column is updated
-when a phase actually passes its gate — never in advance.
+| Architecture, domain model, decision rules, threat model | ✅ [docs/](docs/) |
+| PostgreSQL schema — 24 tables, 2 migrations, CHECK constraints, partial unique index | ✅ |
+| Authentication — e-mail/password, Argon2id, database sessions, rate limiting | ✅ |
+| RBAC — 4 roles, 36 permissions, one matrix, checked server-side | ✅ |
+| Multi-tenancy — `TenantContext` required by every data access | ✅ |
+| Audit trail — written inside the mutation's transaction | ✅ |
+| Application shell — navigation filtered by role, `DEMO DATA` marker | ✅ |
+| Deterministic idempotent seed — 2 organizations, one user per role | ✅ |
+| Fleet, operations, weather, risk, alerts, assets, incidents, analytics | 🔜 Phases 2–8 |
+| Ocean AI | 🔜 Phase 9 |
+| E2E tests, metrics, deployment | 🔜 Phase 10 |
+
+Nothing is described as working unless this table says it is, and the Command Center says the same
+thing on screen: its Operational Status panel reports **"not computable yet"** rather than a green
+light, because three of the four inputs to that score do not exist before phase 6.
+
+### Verified on 2026-07-26
+
+```text
+lint       ✓ no errors
+typecheck  ✓ no errors
+test       ✓ 26 passed (5 files)
+build      ✓ 6 routes
+```
+
+Plus, against a real PostgreSQL 17: both migrations apply to an empty database, all 10 CHECK
+constraints and the partial unique index exist, the seed is idempotent (run twice → same counts),
+and all four seeded roles sign in and receive a shell that matches their permissions — a Viewer
+sees 10 permissions and no Administration module, an Operator 17 with `alert:acknowledge` but not
+`alert:resolve`, a Manager 30, an Administrator 36.
 
 ---
 
@@ -108,20 +124,49 @@ accept, making a forgotten tenant filter a type error rather than a data leak.
 
 ## Stack
 
-Next.js 16 · React 19 · TypeScript 7 (strict) · Tailwind 4 · shadcn/ui · PostgreSQL 17 ·
-Prisma 7 · Better Auth · Zod 4 · Leaflet · Recharts · Vitest · pnpm.
+Next.js 16 · React 19 · TypeScript 5.9 (strict, `noUncheckedIndexedAccess`) · Tailwind 4 ·
+PostgreSQL 17 · Prisma 7 · Better Auth · Argon2id · Zod 4 · Vitest · npm.
+Leaflet and Recharts arrive with the modules that need them (phases 2 and 8).
 
-Every choice, and the alternative it beat, is in [DECISIONS.md](docs/DECISIONS.md).
-Running cost of the MVP is zero: free tiers and open source only.
+Every choice, and the alternative it beat, is in [DECISIONS.md](docs/DECISIONS.md) — including
+three decisions revised during phase 1 because the environment disagreed with the plan.
+Running cost is zero: free tiers and open source only.
 
 ## Getting started
 
-Nothing to run yet — Phase 1 creates the application. When it exists, this section will carry the
-real commands, verified, and not before.
+Requires Node 22+ and Docker.
+
+```bash
+cp .env.example .env          # then set BETTER_AUTH_SECRET (openssl rand -base64 32)
+npm install
+docker compose up -d          # PostgreSQL 17 on port 5433
+npx prisma migrate deploy     # or `npm run db:migrate` while developing
+npm run db:seed               # idempotent — safe to re-run
+npm run dev                   # http://localhost:3000
+```
+
+### Demo access
+
+Seeded accounts, **development only**, all with the password `OceanCommand2026!`:
+
+| E-mail | Role |
+| --- | --- |
+| `admin@oceancommand.demo` | Administrator |
+| `manager@oceancommand.demo` | Operations Manager |
+| `operator@oceancommand.demo` | Operator |
+| `viewer@oceancommand.demo` | Viewer |
+
+Sign in as more than one to see the same page grant different access. These accounts exist only in
+a database you seeded yourself, in an organization flagged `isDemo`, which is what puts the
+`DEMO DATA` marker in the header.
+
+A second organization, `northern-marine`, is seeded with one user and no data. It is not a demo of
+anything: it exists so the tenant-isolation tests can *prove* that one organization cannot read
+another's records instead of asserting it.
 
 ## Quality gate
 
-From Phase 1 onward, no phase is considered done until all of these pass in CI:
+No phase is considered done until all of these pass in CI:
 
 ```text
 lint  ·  typecheck  ·  unit + integration tests  ·  build  ·  secret scan
@@ -144,7 +189,7 @@ deletable.
 
 ## Roadmap
 
-Phase 0 Architecture ✅ · 1 Foundation · 2 Fleet Command · 3 Operations · 4 Environmental
+Phase 0 Architecture ✅ · 1 Foundation ✅ · 2 Fleet Command · 3 Operations · 4 Environmental
 Intelligence · 5 Risk & Alerts · 6 Asset Monitoring · 7 Incidents · 8 Analytics & Command Center ·
 9 Ocean AI · 10 Production Readiness.
 

docker-compose.yml

@@ -0,0 +1,26 @@
+# Local development database only. Deployed environments use managed PostgreSQL
+# (see docs/adr/002-postgresql-and-hosting.md). Port 5433 on the host to avoid
+# colliding with a PostgreSQL already installed locally.
+services:
+  postgres:
+    # Pinned exactly. A floating tag means the day a new major is published, the
+    # container restarts against a data directory the new server refuses to open.
+    image: postgres:17-alpine
+    container_name: ocean-command-db
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ocean
+      POSTGRES_PASSWORD: ocean_dev_only
+      POSTGRES_DB: ocean_command
+    ports:
+      - '5433:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U ocean -d ocean_command']
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+volumes:
+  postgres-data: