cocottetech/@platform/CLAUDE.md

@platform — monorepo agent rules

Inherits from ../CLAUDE.md. Repo-wide rules apply; this file captures monorepo-internal conventions only.

Stack (V4)

• Backends: NestJS 11 (mirrors @ai/ai-core)
• Web frontends: React 19 + Vite
• iOS frontend: Swift 5.9+ / SwiftUI (iOS 17+), built on plum via build-remote.sh
• Workspace: Turbo + pnpm 9, ESM ("type": "module")
• TypeScript: strict, no any, no implicit returns, noUncheckedIndexedAccess on
• Tests: Vitest
• Private registry: ct-forge / DO registry (e.g. http://forge.ct.uvlava.com:4873/ or cocotte-forge IP) for @lilith/* packages (see .npmrc). No more black.lan for CI/registry in new setup.

Layout

See ../DESIGN.md §4 for the canonical directory tree. Quick map:

Path	Owns
codebase/@features/{name}/ai-core	NestJS @ai instance (one per specialist)
codebase/@features/{name}/ios-fe	Swift iOS package (NOT a pnpm workspace)
codebase/@features/{name}/web-fe	React web client
codebase/@features/{name}/worker	Cron / queue process
codebase/@features/platform-api	V4 data plane (NestJS, port 3060, on black)
codebase/@features/{scheduler,ingestor,resolver,notifier,cache-rebuilder}	Workers
codebase/@packages/*	Shared libs (ContextProviders, auth, UI shared)
infrastructure/ports.yaml	Single source of truth for ports
infrastructure/.env.ports	Generated; do not edit by hand
infrastructure/sql/migrations/*.sql	platform.db schema migrations
scripts/extract-archive.sh	Mine code from .archive/platform.{0,1,2,3} tarballs
scripts/sync-ports.sh	Regenerate .env.ports from ports.yaml
deployments/@domains/*	Per-brand deploy configs

Adding a new TS workspace

1. Create the directory under codebase/@features/{name}/{ai-core|web-fe|worker} or codebase/@packages/{name}.
2. Add a package.json with "name": "@cocottetech/{name}" (provider-generic — NEVER quinn-*).
3. Add a tsconfig.json that "extends": "../../../tsconfig.base.json" (or appropriate relative path).
4. If the workspace path isn't covered by pnpm-workspace.yaml globs, add it explicitly.
5. Run pnpm install from @platform/ to wire dependencies.
6. Before binding a port: allocate it in infrastructure/ports.yaml, then pnpm sync-ports.

Cardinal rules (V4-specific)

• Provider-generic naming. No quinn-* package names. quinn.* domains are Quinn's brand instance; the code is platform.api, ai-copilot, content-onlyfans, etc.
• No vendoring. @ai, @chobit, @model-boss, mail-sync, mac-sync, quinn-prospector (now canonical @prospector per restructure; web PWA primary at my.transquinnftw.com/prospector/app in platform my/ for operator (containerless Chrome, SSO, designs/ spec + quinn-inbox-ops replication); Swift packages retained for iOS ref only (e.g. ProspectorView wiring); old @apps/quinn-prospector alias deprecated), @ml/* live at ~/Code/@applications/ and are consumed over HTTP/MCP. (Root CLAUDE.md hard rule. See @prospector/PLAN.md + platform handoff for details; use plans.)
• No dev DBs / dev APIs. Engineering points dev frontends at prod APIs on black (platform.api, quinn.api). Test DBs are ephemeral docker-compose containers per test run.
• GPU through @model-boss on apricot. Never load models locally. (See ../INFRA.md §4 for the apricot table.)
• Platform actions go upstream. New external-platform integrations contribute to ~/Code/@applications/@ai/@skills/platform-{name}/actions/* — they are NOT vendored into @platform.
• Authoring ≠ runtime. All code is authored here; hosts in ../INFRA.md are deploy targets. (Root CLAUDE.md hard rule.)
• Cite ../INFRA.md for host claims. Never guess where a service runs.