cocottetech/CLAUDE.md

@cocottetech — Agent Rules

This is the V4 platform workspace. See DESIGN.md for architecture, INFRA.md for hosts/DBs.

Hard rules

• DO NOT touch ~/Code/@projects/@lilith/lilith-platform.live/ — it's still serving production. All V4 work happens here.
• Prior versions are vendored in .archive/ as LFS-tracked tarballs — this repo is the monolith workspace for the lineage. To mine code: ./scripts/extract-archive.sh <version> (extracts to /tmp/cocottetech-archive/<version>/ so the working tree stays clean). The .live source path at ~/Code/@projects/@lilith/lilith-platform.live/ is also live production — never modify it. See .archive/ARCHIVED.md for the mining map and the superseded-by-peer-apps table.
• DO NOT add @ai/, mail-sync/, mac-sync/, @ml/, @messenger/, @chobit/ directories inside @cocottetech/ — these are peer services that live at ~/Code/@projects/@lilith/mail-sync/ and ~/Code/@applications/@*/. Consumed over HTTP/MCP, never vendored. Platform-action skills (@ai/@skills/platform-*/actions/*) are contributed upstream to @ai, not vendored into @platform.
• Provider-generic naming. No quinn-* package names in new code. Quinn's deployed quinn.* domains remain (that's Quinn's instance), but the code that backs them is provider-portal, ai-assistant, messenger, etc.
• Person-first tenancy. Every new table that owns user data must support both user_id (Person) and optional org_id (Org). See DESIGN.md §5.
• Agents commit directly. (STALE: the apricot ACS auto-commit-service is removed/offline.) Author scoped, atomic, conventional commits and git push your own work — never blind git add -A, never defer to a commit daemon. (Historical: this project used to route commits through ACS; that workflow no longer runs.)
• Manifest files are tool-managed. users/*/app.manifest.yaml, @platform/infrastructure/ports.yaml, @platform/infrastructure/.env.ports, and deployments/@domains/*/services.yaml are mutated through ./run manifest <subcommand> only. Direct edits work today (no OS enforcement yet), but they're a SMELL — always ./run manifest validate after a change to confirm consistency. See INFRA.md §12.
• Authoring location ≠ runtime host. All V4 code is authored here, in this repo (the local Mac working tree), under @platform/codebase/. Hosts named in INFRA.md (black, apricot, vps-0, plum) are runtime / deploy targets, never scaffold targets. "Service X runs on black" never means "scaffold X on black" — it means scaffold here, deploy artifact to black. Dev iteration runs on local Mac or on apricot (the engineering dev box per INFRA.md §1); production runtime lives on black/vps-0/plum per INFRA's service-distribution tables.
  • CI / Forgejo runners: NO MORE BLACK. ct-forge (cocottetech's forge on DO) uses on-demand horizontally scaled DO runners via Terraform IaC in infra/terraform/ci-runners/ (modeled directly on LP's infrastructure/setup-forgejo-host.sh provisioning logic — same labels, host-mode config, registration, but cloud-init + golden image from packer/test-fleet for DO cattle. Scale with terraform apply -var="runners=N"; 0 for zero cost. LP's CI + deploys now target [self-hosted, linux, do, ct-forge] (no black runners). See ci-runners/README.md and LP .forgejo/workflows updates.
• Before reasoning about any host, deploy target, or service placement: read INFRA.md. Specifically §1 Hosts, §4 Service distribution, and §5 Network & routing. Do not infer host roles from filenames, package names, or memory. If a claim about where X runs isn't backed by an INFRA.md line you can cite, you haven't verified it.

When unsure

• Architectural questions → re-read DESIGN.md. If still unclear, ask.
• Anything about hosts, ports, deploy targets, or networking → read INFRA.md first (§1, §4, §5). Cite the line. Never guess host roles.
• Where does code live (authoring)? → always @platform/codebase/ in this repo. Hosts in INFRA are runtime, not authoring.
• Where does X live (runtime)? → check INFRA.md §4 (service distribution by host).
• Does V1/V0 have prior art for X? → grep .archive/platform.{0,1,2}/ and ARCHIVED.md for the mining map.
• Naming a new package → see DESIGN.md §7. Generic > person-specific.

What's where

Concern	Location
V4 features (each owns its ai-core/, ios-fe/, web-fe/, worker/ subdirs as needed)	@platform/codebase/@features/
Shared libs (NestJS modules, ContextProvider impls, Swift packages)	@platform/codebase/@packages/
Secondary web surfaces (content-portal, engagement-portal — later, under @features/{name}/web-fe/)	@platform/codebase/@features/{portal-name}/web-fe/
Per-domain deploy configs	@platform/deployments/@domains/
SQL migrations, port registry, Caddy/nginx configs	@platform/infrastructure/
Long-form docs	@platform/docs/ (project-level) or DESIGN.md / INFRA.md (root)
Feature design docs (*.brief.md, *.contract.md, *.screen.md, *.flow.md)	.project/designs/<feature>/ — one folder per feature (ai-copilot, client-area, prospecting, …)
Run / build / deploy scripts	@platform/scripts/

A V4 @features/{name}/ folder is heterogeneous: it can contain ai-core/ (NestJS @ai instance), ios-fe/ (Swift), web-fe/ (React), and/or worker subdirs — whatever the feature owns. There is no separate @apps/ tier in V4; the iOS app and any web FEs live inside the feature that owns them.

Conventions (V4 stack)

• Stack: NestJS (backends) + React (web frontends) + Swift/SwiftUI (iOS), Turbo + pnpm workspaces, TypeScript strict (no any). Matches @ai/ai-core and v1 lilith-platform. Not Bun + Hono (that's v2).
• Single API plane: all web FEs (dev on apricot, prod on vps-0) call prod APIs on black (platform.api for V4, quinn.api for v2). No dev API stack. No dev DBs. Test DBs are ephemeral containers per test run.
• Platform actions live upstream in @ai/@skills/platform-{name}/actions/ — V4 contributes new platform skills to ~/Code/@applications/@ai/, never vendors them inside @platform.
• GPU through @model-boss (apricot, 2× 24 GB). Never load models locally.
• infrastructure/ports.yaml is the port registry; never hardcode ports.
• Caddy for TLS / dev domains (*.apricot.lan).
• Postgres for relational, TimescaleDB for analytics (vps-0 hot tier), Redis for queue/cache + cache-invalidate pub/sub, MinIO for objects.

Sibling projects (read-only peers)

These are consumed by the platform but live outside this directory tree. Never vendor.

• ~/Code/@applications/@ai/ — shared AI cognitive layer (ai-core NestJS :3790, inference-worker, relationship-worker). V4 forks ai-core per specialist and contributes @ai/@skills/platform-*/actions/* upstream.
• ~/Code/@applications/@chobit/ — Godot avatar runtime (V4 doesn't depend on it today; future integration when ai-copilot needs a face).
• @model-boss (apricot-resident) — GPU inference router; all V4 GPU work routes here over HTTP.
• ~/Code/@projects/@lilith/mail-sync/ — Proton Bridge wrapper (plum-resident, :4444).
• ~/Code/@applications/@mac-sync/ — iMessage bidirectional sync (plum, :3100). V4 notifier enqueues iMessage notifications via mac-sync's send-queue.
• ~/Code/@applications/@messenger/ — separate messenger codebase (v2-era; do not reuse without reconciling against v2's messages feature first).
• ~/Code/@applications/@ml/ — knowledge-platform (Crystal's successor), classifiers, ML pipelines.
• ~/Code/@applications/lilith-messenger-ios/ — existing iOS messenger app. V4's @features/ai-copilot/ios-fe ports useful parts from this (api-client, domain-models, rich-cards, foundations, ui, build-tools, config, build-remote.sh plum-build flow).
• quinn-prospector (MCP service) — correction-pattern store + draft-message + prospect classification. V4 surface agents (P1+) consume mcp__quinn-prospector__* tools. Operator primary UI is web PWA at my.transquinnftw.com/prospector/app (see @applications/@prospector/PLAN.md + designs/ for takeover; platform my/ for code). Use plans.

Treat them as services with HTTP/MCP contracts.