# GCP Production Path

Co-Vibe will run at `https://co-vibe.dev` on Google Cloud after the production
database and security gates are complete.

This file is a deployment preparation note, not a deploy log. Do not deploy from
this repo until the human security-review pause is complete.

## Current Decision

- Product name: Co-Vibe is the public-facing brand.
- Domain: `co-vibe.dev`.
- Compute target: Cloud Run container.
- Production database target: Cloud SQL for PostgreSQL.
- Local/dogfood database: PostgreSQL. Use a local Postgres container or a
  managed test database.
- Auth: WorkOS AuthKit stays the hosted auth path.

The repo now has PostgreSQL schema initialization, tenant/workspace
row-level-security policy generation, and a PostgreSQL runtime bridge behind
`getDb()` for the existing repository surface. The bridge is a transition
layer; the long-term cleanup is to convert repositories to native async `pg`
calls.

## GCP Shape

Use one Google Cloud project for the first production environment unless there
is a compliance reason to split projects.

Recommended first resources:

- Cloud Run service: `co-vibe`.
- Artifact Registry repository for the container image.
- Cloud SQL for PostgreSQL instance in the same region as Cloud Run.
- A Cloud Run service account with the Cloud SQL Client role.
- Secret Manager entries for WorkOS, cookie, database, and optional model keys.
- External HTTPS entry point for `co-vibe.dev`.

Required database env for the PostgreSQL path:

```bash
COVIBE_DATABASE_BACKEND=postgres
# Non-superuser, non-owner Cloud SQL role — subject to row-level security.
DATABASE_URL=postgres://covibe_app:...@/covibe?host=/cloudsql/<conn>
# Owner role used only for init + provisioning (db:postgres:init or auto-init).
COVIBE_POSTGRES_ADMIN_URL=postgres://covibe_owner:...@/covibe?host=/cloudsql/<conn>
```

Initialize a fresh PostgreSQL database with:

```bash
npm run db:postgres:init
```

When `COVIBE_POSTGRES_ADMIN_URL` is set, `npm run db:postgres:init` connects as
the owner to create the schema and seeds, then idempotently provisions the
non-superuser `DATABASE_URL` role with `usage` on schema `public` and
`select/insert/update/delete` on all tables (plus default privileges for future
tables). The runtime app then connects only as that role, so Postgres RLS is
enforced. In Cloud SQL, create the owner as a superuser-equivalent (or the
Cloud SQL admin role) and the app role as a plain `LOGIN` role.

Verify the generated schema and tenant isolation policies locally with Docker:

```bash
npm run smoke:postgres
npm run smoke:postgres:runtime
```

Google's Cloud SQL guidance for Cloud Run requires the service to be connected
to the Cloud SQL instance, commonly with `--add-cloudsql-instances`, and the
Cloud Run service account needs the Cloud SQL Client role. Google also
recommends keeping Cloud SQL and Cloud Run in the same region to reduce latency
and cross-region risk.

For `co-vibe.dev`, prefer a global external Application Load Balancer in front
of Cloud Run for production custom-domain traffic. Google documents Cloud Run
domain mapping as preview and not recommended for production services.

References:

- [Cloud SQL for PostgreSQL from Cloud Run](https://docs.cloud.google.com/sql/docs/postgres/connect-run)
- [Cloud Run custom domains](https://docs.cloud.google.com/run/docs/mapping-custom-domains)

## Blockers Before Deploy

1. Run `npm run db:postgres:init` with `COVIBE_POSTGRES_ADMIN_URL` (owner) and
   `DATABASE_URL` (non-superuser app role) set, so the schema is created by the
   owner and the runtime app role is provisioned with least privilege.
2. Run `npm run smoke:postgres` and `npm run smoke:postgres:runtime`.
3. Store profile uploads outside the container, likely Cloud Storage.
4. Keep pre-rename MCP, env, and package names out of the first public launch
   path; all new setup paths must use Co-Vibe names.
5. Run the repo security gate and both external security-review sessions.
6. Add `https://co-vibe.dev/callback` to WorkOS Redirects.
7. Run the strict handoff gate only after the permanent domain is live:

```bash
npm run readiness:handoff -- https://co-vibe.dev
```

## Security-Review Pause

Before any GCP deploy command is run, stop and ask the human operator to run:

- Claude Code security review.
- Codex security review in a separate session.
- Any Cursor-side review the team wants for the local companion path.

Only continue to GCP deployment after those reviews are complete and their
findings are either fixed or explicitly accepted.

## Agent Connection Canary

After deployment and security review, test each supported agent path against
`https://co-vibe.dev` with a fresh MCP token created in Settings.

Claude Code:

- Run the Agent Setup install command.
- Confirm `.mcp.json` exposes the server.
- Confirm `.claude/settings.json` contains the session hooks.
- Start Claude Code and verify `covibe_session` and telemetry usage events.

Codex:

- Run `npm exec -- covibe-local doctor --base-url https://co-vibe.dev`.
- Run `npm exec -- covibe-local watch --base-url https://co-vibe.dev --once`.
- Verify repo snapshot data is stored without file contents.
- Verify Codex/provider telemetry JSON can flush through `.covibe/telemetry`.

Cursor:

- Run `npm exec -- covibe-local setup` and confirm `.cursor/mcp.json` exposes
  the server token-safely and `.cursor/hooks.json` carries the lifecycle hooks.
- Run a Cursor agent session and verify `covibe_session` start/snapshot/end
  events plus swept usage counters.
- Verify the server stores counters and a payload hash, not prompts or
  transcripts.

The final proof is a successful `npm run readiness:handoff -- https://co-vibe.dev`.