@@ -1,16 +1,47 @@
-# Project creation
+# Projects
 
 A Project groups environments. An environment is an existing `workspace` record; there is no separate environment table. Every newly created Project starts with an environment.
 
 Project APIs return HTTP 503 until the `projects` feature flag is on (AppConfig on hosted deployments; the `PROJECT_API_ENABLED` secret elsewhere). The flag defaults off and gates only the Project APIs: workspace creation always assigns a Project atomically, and assigned Projects keep their lifecycle protections (fork inheritance, disconnect) either way.
 
+## Storage and consistency
+
+Each workspace belongs to exactly one Project through the required `workspace.project_id`
+foreign key. One Project can contain many workspaces, including disconnected roots; there
+is no membership connector table. Referenced Projects cannot be deleted while their
+workspaces remain. `project.updated_at` is Project-record metadata, not a workspace
+activity counter or a concurrency version.
+
+Native composite foreign keys enforce two structural invariants:
+
+- Workspace and Project organizations agree, including personal (`NULL`) scope. Both
+  tables have a stored generated `organization_scope_key`: `personal` for NULL and
+  `organization:` followed by the organization ID otherwise. Writers cannot supply this
+  key independently. A unique Project `(id, organization_scope_key)` constraint supports
+  the workspace `(project_id, organization_scope_key)` foreign key.
+- A connected fork and its parent share a Project. A unique workspace `(id, project_id)`
+  constraint supports `(forked_from_workspace_id, project_id)` referencing that pair.
+  The parent-ID foreign key uses `ON DELETE SET NULL`, clearing only the parent pointer.
+  The composite foreign key uses `NO ACTION`; Project membership never cascades automatically.
+
+Both composite foreign keys are `DEFERRABLE INITIALLY DEFERRED`, allowing atomic
+organization transfers and subtree moves before validation. Drizzle records the columns,
+indexes, and relationships; the shared schema finalizer sets deferred timing after a fresh
+schema push because Drizzle does not represent that timing.
+
+Application transactions own creation with the first workspace, nonempty Projects,
+archive lifecycle, workflow admission/restoration, and subtree disconnection. Their
+Project, lineage, edge, and workspace locks protect these business operations. PostgreSQL
+owns referential-integrity concurrency through the native constraints; no custom Project
+integrity triggers or artificial Project row touches are required.
+
 ## Choose the creation flow
 
 | Caller | Flow | Result |
 | --- | --- | --- |
 | New Project onboarding | `POST /api/projects` | Creates a Project and its first environment together, with independently supplied names. |
 | Existing workspace creation UI or caller | `POST /api/workspaces` | Creates a workspace and automatically creates its Project, preserving the existing workspace response. |
-| Create another environment by forking | Existing workspace fork operation | Inherits the source workspace's Project; unassigned legacy families remain unassigned until backfilled. |
+| Create another environment by forking | Existing workspace fork operation | Inherits the source workspace's Project. |
 
 Both POST endpoints are internal, session-authenticated APIs. `POST /api/projects` is not a public `/api/v2` endpoint and does not accept API-key principals. Existing workspace creation endpoints remain supported.