feat: unify setup-dev flow into shared setup module

.agents/skills/internal-surface-areas/SKILL.md

@@ -96,7 +96,7 @@ Developer/operator goal: configure the system safely for dev/test/prod and keep
 | **Environment templates (`.env.example`, `.env.docker.example`)** | Canonical environment variable templates used for local dev and containerized runs. | — | `.env.example`, `.env.docker.example` |
 | **Runtime env schemas (API/CLI/Core)** | Zod schemas that validate and type environment variables per package at startup. | Environment file loader (`loadEnvironmentFiles`), Environment templates (`.env.example`, `.env.docker.example`) | `agents-api/src/env.ts`, `agents-cli/src/env.ts`, `packages/agents-core/src/env.ts` |
 | **Env schema documentation enforcement** | Checks ensuring each env var is documented via `.describe()` in the Zod schema (kept in sync with templates). | Runtime env schemas (API/CLI/Core), Environment templates (`.env.example`, `.env.docker.example`) | `scripts/check-env-descriptions.mjs` |
-| **Local dev bootstrap (`pnpm setup-dev`)** | One-command developer setup that provisions env files, starts Docker services, runs migrations, and applies the SpiceDB schema. | Environment templates (`.env.example`, `.env.docker.example`), Local database stack (Docker Compose), Drizzle kit configs (manage + runtime), Migration directories (Drizzle SQL), SpiceDB schema (Zed) | `scripts/setup.sh`, `docker-compose.dbs.yml`, `packages/agents-core/spicedb/schema.zed` |
+| **Local dev bootstrap (`pnpm setup-dev`)** | One-command developer setup that provisions env files, starts Docker services, runs migrations, and applies the SpiceDB schema. Shared setup module (`@inkeep/agents-core/setup`) used by both monorepo and quickstart template. | Environment templates (`.env.example`, `.env.docker.example`), Local database stack (Docker Compose), Drizzle kit configs (manage + runtime), Migration directories (Drizzle SQL), SpiceDB schema (Zed) | `packages/agents-core/src/setup/setup.ts`, `scripts/setup-dev.js`, `docker-compose.dbs.yml`, `packages/agents-core/spicedb/schema.zed` |
 
 ### Docker & Deployment Artifacts
 Developer/operator goal: run the system in containers for local development and integration testing.

.changeset/clumsy-bronze-nightingale.md

@@ -0,0 +1,5 @@
+---
+"@inkeep/agents-core": patch
+---
+
+Add shared setup module for unified dev environment bootstrapping

.github/composite-actions/cypress-e2e/action.yml

@@ -42,11 +42,15 @@ runs:
           sleep 2
         done
 
+    - name: Build agents-core (required by setup-dev.js)
+      shell: bash
+      run: pnpm turbo run build --filter=@inkeep/agents-core
+
     - name: Setup development environment
       shell: bash
       env:
         ENVIRONMENT: development
-      run: pnpm setup-dev
+      run: pnpm setup-dev --skip-push
 
     - name: Start backend API server
       shell: bash

.gitignore

@@ -26,6 +26,7 @@ coverage/
 .DS_Store
 *.pem
 *.db
+.setup-complete
 
 # debug
 npm-debug.log*

agents-cookbook/template-projects/inkeep.config.ts

@@ -4,6 +4,7 @@ export default defineConfig({
   tenantId: 'default',
   agentsApi: {
     url: 'http://localhost:3002',
+    apiKey: process.env.INKEEP_AGENTS_MANAGE_API_BYPASS_SECRET,
   },
   manageUiUrl: 'http://localhost:3000',
 });

agents-docs/content/community/contributing/overview.mdx

@@ -37,16 +37,19 @@ pnpm setup-dev
 This will:
 
 - Create `.env` from `.env.example` if missing
-- Create `~/.inkeep/config` for user-global settings if missing
-- Add `.env` to `.gitignore` if needed
-- Install dependencies
-- Start Doltgres (manage) + Postgres (runtime) + SpiceDB (authorization) via `docker-compose.dbs.yml` and run migrations
-- Create the admin user for auto-login (`pnpm db:auth:init`)
+- Generate JWT keys if not already configured
+- Check that Docker is running and required ports (5432, 5433, 5434) are free
+- Start Doltgres (manage) + Postgres (runtime) + SpiceDB (authorization) via `docker-compose.dbs.yml`
+- Run database migrations (manage + runtime)
+- Initialize the default organization and admin user
+- Push a sample project (weather-project) so the UI is pre-seeded
 
 <Tip>
-`pnpm setup-dev` is idempotent — safe to re-run after pulling changes, resetting your database, or switching branches.
+Safe to re-run at any time. Each step is additive — it won't drop tables, delete projects, or reset credentials. Migrations apply only what's new, and existing data is preserved. If Docker containers are already running, setup skips startup and proceeds to migrations.
 </Tip>
 
+If another Docker Compose project is using the required ports, setup tells you exactly which project is blocking and the command to stop it.
+
 Add API keys for the AI providers you want to use in the root `.env` or `~/.inkeep/config`. `ANTHROPIC_API_KEY` is required.
 
 ```dotenv

agents-docs/content/troubleshooting.mdx

@@ -80,11 +80,21 @@ If `pnpm dev` fails or services aren't reachable, the most common cause is that
 **How to fix:**
 
 1. Ensure Docker Desktop (or Docker daemon) is running
-2. Run `pnpm setup-dev` — this is idempotent and will start any stopped databases, apply pending migrations, and ensure the admin user exists
+2. Run `pnpm setup-dev` — it will start any stopped databases, apply pending migrations, and ensure the admin user exists
 3. Run `pnpm dev` again
 
 For the [quickstart template](/get-started/quick-start), the same applies: run `pnpm setup-dev` from the workspace root before `pnpm dev`.
 
+### Port conflicts
+
+If `pnpm setup-dev` reports that ports 5432, 5433, or 5434 are in use by another Docker Compose project, stop that project first:
+
+```bash
+docker compose -p <project-name> down
+```
+
+The setup script tells you the exact project name and command. After stopping the conflicting project, re-run `pnpm setup-dev`.
+
 ## Check service logs (local development)
 
 When running `pnpm dev` from your [quickstart workspace](/quick-start/start-development), you will see an interactive terminal interface. This interface allows you to inspect the logs of each [running service](/quick-start/start-development#service-ports). You can navigate between services using the up and down arrow keys.