docs(platform-specific): 📝 Clarify project setup docs and configure workspace tools for better toolchain consistency

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>

@platform/CLAUDE.md

@@ -0,0 +1,52 @@
+# @platform — monorepo agent rules
+
+Inherits from `../CLAUDE.md`. Repo-wide rules apply; this file captures monorepo-internal conventions only.
+
+## Stack (V3)
+
+- **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**: `http://registry.black.lan:4873/` for `@lilith/*` packages (see `.npmrc`)
+
+## 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` | V3 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}` 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": "@atlilith/{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 (V3-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`, `@ml/*` live at `~/Code/@applications/` and are consumed over HTTP/MCP. (Root CLAUDE.md hard rule.)
+- **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.

@platform/pnpm-workspace.yaml

@@ -0,0 +1,21 @@
+# V3 monorepo — feature-rooted layout (no @apps/ tier; features own their own surfaces).
+# See ../DESIGN.md §4. iOS code (`ios-fe/`) is Swift, NOT a pnpm workspace — excluded by absence
+# of `package.json` in those directories.
+
+packages:
+  # Per-feature TS packages (heterogeneous: ai-core, web-fe, worker per feature)
+  - 'codebase/@features/*/ai-core'
+  - 'codebase/@features/*/web-fe'
+  - 'codebase/@features/*/worker'
+
+  # Standalone features (no sub-tier — single-purpose)
+  - 'codebase/@features/platform-api'
+  - 'codebase/@features/scheduler'
+  - 'codebase/@features/engagement-ingestor'
+  - 'codebase/@features/prospect-resolver'
+  - 'codebase/@features/notifier'
+  - 'codebase/@features/cache-rebuilder'
+
+  # Shared libs (flat + scoped)
+  - 'codebase/@packages/*'
+  - 'codebase/@packages/@*/*'

@platform/turbo.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": ["**/.env.*local"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"],
+      "outputs": []
+    },
+    "lint": {
+      "outputs": []
+    },
+    "test": {
+      "dependsOn": ["^build"],
+      "outputs": ["coverage/**"]
+    },
+    "test:unit": {
+      "dependsOn": ["^build"],
+      "outputs": ["coverage/**"]
+    },
+    "test:e2e": {
+      "dependsOn": ["^build"],
+      "outputs": ["../../test-output/**"],
+      "cache": false
+    },
+    "test:coverage": {
+      "dependsOn": ["^build"],
+      "outputs": ["coverage/**"]
+    },
+    "preview": {
+      "dependsOn": ["build"],
+      "cache": false,
+      "persistent": true
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "clean": {
+      "cache": false
+    },
+    "validate": {
+      "outputs": [],
+      "cache": false
+    },
+    "validate:security": {
+      "dependsOn": ["^build"],
+      "outputs": [],
+      "cache": false
+    }
+  }
+}