feat(docs): add project-scoping guide and update system architecture implementation summary

refactor(tests): rename environment-related tests to project-related and remove obsolete test file
fix(tests): update environment object tests to reflect project object changes

Author: hotlong

content/docs/guides/meta.json

@@ -18,6 +18,7 @@
     "---Integration---",
     "api-reference",
     "client-sdk",
+    "project-scoping",
     "driver-configuration",
     "kernel-services",
     "data-flow",

content/docs/guides/project-scoping.mdx

@@ -0,0 +1,130 @@
+---
+title: Project-Scoped Routing
+description: Enable multi-project isolation at the URL level — /api/v1/projects/:projectId/... — with REST, Client SDK, and dispatcher support.
+---
+
+# Project-Scoped Routing
+
+ObjectStack's project-scoping feature puts each project (the "workspace" or "base" in Airtable / "environment" in traditional stacks) into its own URL segment. When enabled, every data, metadata, automation, and AI request runs through `/api/v1/projects/:projectId/...` instead of relying on hostname / header / session resolution alone.
+
+This gives you:
+
+- **Explicit tenancy in URLs** — no more guessing what project a request targets.
+- **Safer client code** — `client.project(id).data.find(...)` cannot be confused with the default project.
+- **Future foundation for RBAC** — the project is in the URL, so middleware can enforce access before any handler runs.
+- **Incremental rollout** — the `'auto'` resolution strategy mounts both scoped and unscoped routes, so you can migrate clients on your own schedule.
+
+## Server configuration
+
+Enable scoping in your `objectstack.config.ts`:
+
+```typescript
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  // ... rest of your stack
+  api: {
+    enableProjectScoping: true,
+    projectResolution: 'auto', // 'required' | 'optional' | 'auto'
+  },
+});
+```
+
+### Resolution strategies
+
+| Strategy     | Behavior                                                                                   | When to use                                                                 |
+| ------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| `'auto'`     | Registers **both** `/api/v1/data/:object` and `/api/v1/projects/:projectId/data/:object`.  | Default. Zero risk during migration — old and new clients both work.        |
+| `'optional'` | Same as `auto` today; reserved so a future release can require one of URL / header / session to be present. | Same as `auto`.                                                             |
+| `'required'` | Only scoped routes are registered. Unscoped requests return 404.                           | Production hardening after all clients have migrated.                       |
+
+The setting also propagates to:
+
+- **Dispatcher plugin** — AI (`/ai/*`) and automation (`/automation/*`) routes gain scoped variants.
+- **Package management** — `/api/v1/projects/:projectId/packages` mirrors `/api/v1/packages`.
+- **Discovery** — the `/api/v1/discovery` response includes a `scoping` block so clients can detect the mode.
+
+## Client SDK
+
+The client exposes a `project(id)` factory that returns a sub-client wired to the scoped URL prefix:
+
+```typescript
+import { ObjectStackClient } from '@objectstack/client';
+
+const client = new ObjectStackClient({ baseUrl: 'https://api.example.com' });
+
+const scoped = client.project('00000000-0000-0000-0000-000000000001');
+
+// All calls hit /api/v1/projects/:projectId/...
+const tasks = await scoped.data.find('task', { top: 20 });
+const objects = await scoped.meta.getItems('object');
+const pkg = await scoped.packages.get('my-package');
+```
+
+The top-level `client.data.*`, `client.meta.*`, `client.packages.*` namespaces continue to work unchanged — they hit the unscoped routes, falling back to hostname / `X-Project-Id` header / session resolution exactly as before.
+
+You can switch between projects without rebuilding the client:
+
+```typescript
+const projectA = client.project('proj-a');
+const projectB = client.project('proj-b');
+
+await Promise.all([
+  projectA.data.find('task'),
+  projectB.data.find('task'),
+]);
+```
+
+## Request resolution order
+
+When `enableProjectScoping: true`, `HttpDispatcher.resolveEnvironmentContext` resolves the project in this order:
+
+1. **URL path parameter** — `/api/v1/projects/:projectId/...`. Highest priority.
+2. **Hostname** — `acme-dev.objectstack.app`.
+3. **`X-Project-Id` header** — the client SDK sets this automatically if you pass `projectId` in `ClientConfig`.
+4. **Session** — `session.activeProjectId` (or legacy `activeEnvironmentId`).
+5. **Default project for active organization** — falls back to the org's default.
+
+Under `'required'` mode, the URL path is the only supported source; the other fallbacks are bypassed for data/meta/AI/automation routes.
+
+## System project
+
+Every deployment has a built-in system project at the well-known UUID `00000000-0000-0000-0000-000000000001`. It's used for platform infrastructure (system packages, platform-level flows, etc.) and is created automatically on first startup if you register the plugin:
+
+```typescript
+import { createSystemProjectPlugin } from '@objectstack/runtime';
+
+kernel.use(tenantPlugin);
+kernel.use(createSystemProjectPlugin());
+```
+
+The plugin is idempotent — it's safe to call `provisionSystemProject()` on every boot. Subsequent calls return the existing row.
+
+## Control-plane routes remain unscoped
+
+Control-plane endpoints always live under their unscoped paths:
+
+- `/api/v1/auth/*`
+- `/api/v1/cloud/projects` (CRUD on the project list itself)
+- `/api/v1/cloud/organizations`
+- `/api/v1/health`
+- `/api/v1/discovery`
+- `/.well-known/objectstack`
+
+These are not affected by `enableProjectScoping` because they operate on the control plane, not a specific project's data plane.
+
+## Migration checklist
+
+1. ✅ Upgrade to `@objectstack/core@≥4.x` with the Phase 2 runtime.
+2. ✅ Add `enableProjectScoping: true, projectResolution: 'auto'` to your stack config.
+3. ✅ Register `createSystemProjectPlugin()` in your kernel wiring.
+4. ⏳ Update callers that hard-code `/api/v1/data/...` to use `client.project(id)` or keep them as-is under `auto` mode.
+5. ⏳ Once all callers have migrated, flip `projectResolution` to `'required'` and remove the unscoped code paths.
+
+Steps 4 and 5 are intentionally separate — you can ship Step 3 today and migrate clients over weeks or months.
+
+## Related reading
+
+- [ADR-0002 — Project-per-database isolation](/docs/adr/0002-environment-database-isolation)
+- [Client SDK](/docs/guides/client-sdk)
+- [Authentication](/docs/guides/authentication)

docs/design/SYSTEM_ARCHITECTURE_IMPLEMENTATION.md

@@ -1,10 +1,50 @@
 # System Architecture Implementation Summary
 
-**Status**: Phase 1 Complete ✅
+**Status**: Phase 1 & Phase 2 Complete ✅
 **Date**: 2026-04-22
 **Branch**: `claude/design-new-system-architecture`
 
-## Overview
+---
+
+## Phase 2 — Runtime Implementation (2026-04-22)
+
+Phase 2 wires the Phase 1 schemas into the runtime so project-scoped APIs actually work end-to-end.
+
+### What was delivered
+
+1. **REST server dual-mode routing** — `RestServer.registerRoutes()` now reads `enableProjectScoping` / `projectResolution` from the normalized config and registers CRUD / metadata / batch / UI / package / discovery handlers under both `/api/v1/...` and `/api/v1/projects/:projectId/...` (or only the scoped form in `'required'` mode). Scoped handlers forward `req.params.projectId` into every protocol call.
+2. **HttpDispatcher URL-param resolution** — new `extractProjectIdFromPath` helper and a top-of-chain branch in `resolveEnvironmentContext` that resolves a project from the URL path before falling back to hostname / header / session. `/cloud/projects/...` is explicitly excluded so it does not collide with the scoping pattern.
+3. **Dispatcher plugin scoping** — automation and AI routes now mount both unscoped and scoped variants when `DispatcherPluginConfig.scoping.enableProjectScoping` is set. Routes share a single handler factory.
+4. **Client SDK `project(id)` factory** — new `ScopedProjectClient` class in `packages/client/src/index.ts` exposes `data`, `meta`, and `packages` namespaces under the scoped URL prefix. `client.data.*` / `client.meta.*` remain untouched for backward compatibility.
+5. **System project bootstrap plugin** — new `createSystemProjectPlugin()` in `@objectstack/runtime` idempotently calls `ProjectProvisioningService.provisionSystemProject()` on startup and logs the well-known UUID. Strict mode throws on failure; default mode logs a warning and continues.
+6. **Tenant object rename follow-up** — stale `sys_environment*` tests were rewritten to target the renamed `sys_project*` objects. The obsolete `environment-provisioning.test.ts` (duplicate of `project-provisioning.test.ts`) was deleted.
+7. **Documentation** — new guide `content/docs/guides/project-scoping.mdx` walks developers through server config, client usage, resolution order, and the `auto` → `required` migration path.
+
+### Test coverage added in Phase 2
+
+- `packages/rest/src/rest.test.ts` — +5 tests covering default / `auto` / `required` registration and projectId propagation into protocol calls.
+- `packages/runtime/src/http-dispatcher.test.ts` — +3 tests covering URL-param precedence, `/cloud/projects/` skip, and fallback to header resolution.
+- `packages/runtime/src/system-project-plugin.test.ts` (new) — +7 tests covering service resolution, strict vs lenient failure handling, and idempotent invocation.
+- `packages/client/src/client.test.ts` — +6 tests covering URL prefixing, encoding, validation, and accessors on `ScopedProjectClient`.
+- `packages/client/src/client.project-scoping.test.ts` (new) — live Hono integration test: 5 cases covering scoped CRUD, unscoped CRUD backward compat, scoped meta, end-to-end `client.project(id).data.find()`, and discovery `scoping` metadata.
+- `packages/services/service-tenant/src/objects/environment-objects.test.ts` — rewritten to target the renamed `sys_project*` objects; 17 passing tests.
+
+**Aggregate**: 305 tests passing across `@objectstack/rest` (46), `@objectstack/runtime` (160), `@objectstack/client` (99); `@objectstack/service-tenant` went from 7 failed / 30 passed to 38 passed / 2 skipped.
+
+### What remains for Phase 3 and beyond
+
+Each item below is intentionally sized to be a focused PR:
+
+- **Studio UI migration** — Studio pages should call `client.project(id).*` once a project switcher is wired in. Large surface under `apps/studio/`.
+- **CLI `projects` commands** — `objectstack projects list/create/switch` in `packages/cli/src/commands/projects/`.
+- **Browser E2E** — Playwright suite covering login → project switch → data/meta flows.
+- **`projectResolution: 'required'` as default** — requires Studio migration and examples update; flip only after a deprecation cycle.
+- **Project-level RBAC middleware** — formal hook that enforces `can(user, 'read:project', projectId)` before any scoped handler runs. `DefaultEnvironmentDriverRegistry` already caches drivers, so this only needs an auth check layer.
+- **`envRegistry` rename** — internal field name in `HttpDispatcher` still uses the environment-era naming; cosmetic rename deferred to avoid touching constructors across the runtime test suite.
+
+---
+
+## Phase 1 Overview
 
 This document summarizes the implementation of ObjectStack's new system architecture featuring a built-in "system" project and project-scoped API routing configuration, following Airtable's workspace/base scoping model.