atlilith/CLAUDE.md

@atlilith — Agent Rules

This is the V3 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 V3 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/atlilith-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 mail-sync/, mac-sync/, @agents/, @ml/, @messenger/ directories inside @atlilith/ — these are peer services that live at ~/Code/@projects/@lilith/mail-sync/ and ~/Code/@applications/@*/. Consumed over HTTP/MCP, never vendored.
• 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.
• No commits from agents. This project follows the apricot ACS (auto-commit-service) workflow. Write code; ACS handles commits.
• Manifest files conform to @lilith/service-registry v1.4.0 schema. Edit @platform/deployments/@domains/<host>/services.yaml, @platform/deployments/shared-services/*.yaml, or @platform/infrastructure/ports.yaml directly today — convention only, no OS enforcement yet. Always run ./run manifest validate after any change (calls buildDeploymentRegistry({ strict: true })). See INFRA.md §12 for schema + replaced-by history.

When unsure

• Architectural questions → re-read DESIGN.md. If still unclear, ask.
• Where does X live? → 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
New user-facing apps	@platform/codebase/@apps/
Cross-cutting features (api, sso, analytics, etc.)	@platform/codebase/@features/
Shared libs	@platform/codebase/@packages/
Per-domain deploy configs	@platform/deployments/@domains/
Docker / DB / Caddy / port registry	@platform/infrastructure/
Long-form docs	@platform/docs/ (project-level) or DESIGN.md / INFRA.md (root)
Run / build / deploy scripts	@platform/scripts/

Conventions inherited from .live

• Bun as runtime (not Node)
• pnpm + Bun workspaces (bunfig.toml, package.json workspaces)
• TypeScript strict, no any
• infrastructure/ports.yaml is the port registry; never hardcode ports
• infrastructure/.env.ports is the canonical env file for ports
• Caddy for TLS / dev domains (*.apricot.lan)
• Postgres for relational, TimescaleDB for analytics, Redis for queue/cache, MinIO for objects

Sibling projects (read-only peers)

These are consumed by the platform but live outside this directory tree:

• ~/Code/@projects/@lilith/mail-sync/ — Proton Bridge wrapper (plum-resident)
• ~/Code/@applications/@mac-sync/ — iMessage bidirectional sync (plum)
• ~/Code/@applications/@messenger/ — separate messenger codebase (overlaps with @features/messages — reconcile before reuse)
• ~/Code/@applications/@agents/ — Claude SDK agents (assistant, companion, prospector, etc.)
• ~/Code/@applications/@ml/ — knowledge-platform (Crystal's successor), classifiers, ML pipelines
• ~/Code/@applications/@quinn-ios/ — Swift iOS app

Treat them as services with HTTP/MCP contracts. Do not vendor.