docs(kbn): freeze KBN-101 database role split contract (#774)

docs/guides/dev-guide.md

@@ -39,7 +39,7 @@ mosaic-mono-v1/
 │   ├── queue/            # Valkey-backed task queue
 │   └── types/            # Shared TypeScript types
 ├── docker/               # Dockerfile(s) for containerized deployment
-├── infra/                # Infra config (OTEL collector, pg-init scripts)
+├── infra/                # Infrastructure configuration (for example, OTEL collector)
 ├── docker-compose.yml    # Local services (Postgres, Valkey, OTEL, Jaeger)
 └── CLAUDE.md             # Project conventions for AI coding agents
 ```
@@ -86,71 +86,54 @@ cd mosaic-mono-v1
 pnpm install
 ```
 
-### 2. Start Infrastructure Services
+### 2. Use the local PGlite tier
+
+The supported local tier is in-process PGlite and requires no PostgreSQL service. Leave
+`DATABASE_URL` unset for this route. Its default local configuration uses PGlite and performs no
+external database probe.
+
+If a local queue service is useful, start only that non-PostgreSQL service:
 
 ```bash
-docker compose up -d
+docker compose up -d valkey
 ```
 
-This starts:
+Do not use the current Compose PostgreSQL service: it mounts legacy `infra/pg-init` SQL and is
+not qualified for KBN-101. Start OTEL Collector or Jaeger individually only when needed and
+without starting PostgreSQL.
 
-| Service                  | Port           | Description          |
-| ------------------------ | -------------- | -------------------- |
-| PostgreSQL 17 + pgvector | `5433` (host)  | Primary database     |
-| Valkey 8                 | `6380` (host)  | Queue and cache      |
-| OpenTelemetry Collector  | `4317`, `4318` | OTEL gRPC and HTTP   |
-| Jaeger                   | `16686`        | Distributed trace UI |
+### 3. Gateway/Web local process (held)
 
-### 3. Configure Environment
+Do not start the current Gateway or web process as a local PGlite route. Gateway first loads the
+daemon configuration and then project environment files without a tier guard; a pre-existing
+`DATABASE_URL` can select PostgreSQL, where current startup still reaches runtime DDL/migrations.
+Creating a root `.env` that omits `DATABASE_URL` does not make this safe, so neither a local
+credential file nor a web environment file is a current developer procedure.
 
-Create a `.env` file in the monorepo root:
+PGlite remains the supported in-process data-layer implementation, and the optional Valkey command
+above remains safe because it does not start PostgreSQL. A safe Gateway/Web local procedure is held
+until KBN-101-02 rejects a daemon, inherited, root, or app-local PostgreSQL DSN and any non-local
+tier before connection or DDL; KBN-101-05 then supplies the production renderer/Vault process-exec
+or `LoadCredential` boundary.
 
-```env
-# Database (matches docker-compose defaults)
-DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
+### Held future procedure
 
-# Auth (required — generate a random 32+ char string)
-BETTER_AUTH_SECRET=change-me-to-a-random-secret
+PostgreSQL local and federated deployment are held until KBN-101-00 (external bootstrap),
+KBN-101-03 (runner), and KBN-101-05 (renderer-backed deployment) land. The following is the
+**held, non-operative future activation order with no current command authority**:
 
-# Gateway
-GATEWAY_PORT=14242
-GATEWAY_CORS_ORIGIN=http://localhost:3000
+external bootstrap → TLS/roles → `mosaic-db-migrator --run` →
+`mosaic-db-migrator --verify` → Gateway/Compose readiness.
 
-# Web
-NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
+Neither current Compose nor this development guide authorizes PostgreSQL initialization SQL,
+manual DDL, or a pre-runner start.
 
-# Optional: Ollama
-OLLAMA_BASE_URL=http://localhost:11434
-OLLAMA_MODELS=llama3.2
-```
+### 5. Gateway/Web start (held)
 
-The gateway loads `.env` from the monorepo root via `dotenv` at startup
-(`apps/gateway/src/main.ts`).
-
-### 4. Push the Database Schema
-
-```bash
-pnpm --filter @mosaicstack/db db:push
-```
-
-This applies the Drizzle schema directly to the database (development only; use
-migrations in production).
-
-### 5. Start the Gateway
-
-```bash
-pnpm --filter @mosaicstack/gateway exec tsx src/main.ts
-```
-
-The gateway starts on port `14242` by default.
-
-### 6. Start the Web App
-
-```bash
-pnpm --filter @mosaicstack/web dev
-```
-
-The web app starts on port `3000` by default.
+No Gateway/Web start command is currently authorized for the local PGlite route. Do not use root
+`pnpm dev` as a workaround: it additionally starts configured integrations and cannot establish the
+required local-tier/DSN isolation. Resume this section only after KBN-101-02 provides its
+fail-closed local-startup evidence.
 
 ---
 
@@ -300,26 +283,13 @@ Implement a standard MCP server that exposes tools via the streamable HTTP
 transport or SSE transport. The server must accept connections at a `/mcp`
 endpoint.
 
-### 2. Configure `MCP_SERVERS`
+### 2. Gateway MCP configuration (held)
 
-In your `.env`:
-
-```env
-MCP_SERVERS='[{"name":"my-server","url":"http://localhost:3001/mcp"}]'
-```
-
-With authentication:
-
-```env
-MCP_SERVERS='[{"name":"secure-server","url":"http://my-server/mcp","headers":{"Authorization":"Bearer token"}}]'
-```
-
-### 3. Restart the Gateway
-
-On startup, `McpClientService` (`apps/gateway/src/mcp-client/mcp-client.service.ts`)
-connects to each configured server, calls `tools/list`, and bridges the results
-to Pi SDK `ToolDefinition` format. These tools become available in all new agent
-sessions.
+Do not configure MCP endpoint credentials, write them to a local environment file, or restart the
+Gateway from this guide. Gateway/Web startup is held until KBN-101-02 supplies fail-closed
+local-tier/DSN isolation and KBN-101-05 supplies the renderer/Vault process-exec or
+`LoadCredential` secret-consumer interface. The future authenticated MCP route requires verified
+HTTPS and certificate validation; plaintext bearer-token examples are forbidden.
 
 ### Tool Naming
 
@@ -355,42 +325,31 @@ The schema lives in a single file:
 
 The `insights` table uses a `vector(1536)` column (pgvector) for semantic search.
 
-### Development: Push Schema
+### PostgreSQL schema work (held)
 
-Apply schema changes directly to the dev database (no migration files created):
+Do not prepare or run a PostgreSQL target from this branch. The sole runner, bootstrap, and
+renderer are future KBN-101 artifacts, not current commands. When KBN-101-00/-03/-05 land, the
+owned activation documentation will require external bootstrap → TLS/roles → runner `--run` →
+runner `--verify` → Gateway/Compose readiness.
 
-```bash
-pnpm --filter @mosaicstack/db db:push
-```
+### Generating migration artifacts
 
-### Generating Migrations
-
-For production-safe, versioned changes:
-
-```bash
-pnpm --filter @mosaicstack/db db:generate
-```
-
-This creates a new SQL migration file in `packages/db/drizzle/`.
-
-### Running Migrations
-
-```bash
-pnpm --filter @mosaicstack/db db:migrate
-```
+`pnpm --filter @mosaicstack/db db:generate` is an offline artifact-generation command. It does
+not authorize connecting to or initializing PostgreSQL. A future reviewed PostgreSQL procedure
+will determine when its output is applied.
 
 ### Drizzle Config
 
-Config is at `packages/db/drizzle.config.ts`. The schema file path and output
-directory are defined there.
+Config is at `packages/db/drizzle.config.ts`. The schema file path and output directory are
+defined there.
 
 ### Adding a New Table
 
 1. Add the table definition to `packages/db/src/schema.ts`.
 2. Export it from `packages/db/src/index.ts`.
-3. Run `pnpm --filter @mosaicstack/db db:push` (dev) or
-   `pnpm --filter @mosaicstack/db db:generate && pnpm --filter @mosaicstack/db db:migrate`
-   (production).
+3. Generate the offline artifact with `pnpm --filter @mosaicstack/db db:generate`.
+4. Do not apply it to PostgreSQL until the future KBN-101 activation artifacts and their owned
+   procedure are available. Direct schema push is not a production-like workflow.
 
 ---