constructive-io
diff --git a/‎.github/workflows/run-tests.yaml‎
Lines changed: 3 additions & 3 deletions b/‎.github/workflows/run-tests.yaml‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 13 additions & 13 deletions b/‎AGENTS.md‎
Lines changed: 13 additions & 13 deletions
diff --git a/‎DEVELOPMENT_JOBS.md‎
Lines changed: 135 additions & 10 deletions b/‎DEVELOPMENT_JOBS.md‎
Lines changed: 135 additions & 10 deletions
diff --git a/‎FOOTER.md‎
Lines changed: 5 additions & 5 deletions b/‎FOOTER.md‎
Lines changed: 5 additions & 5 deletions
@@ -1,4 +1,4 @@
-name: Constructive matrix tests
+name: CI tests
 on:
   push:
     branches:
@@ -148,8 +148,8 @@ jobs:
 
       - name: seed app_user
         run: |
-          pnpm --filter @launchql/cli exec node dist/index.js admin-users bootstrap --yes
-          pnpm --filter @launchql/cli exec node dist/index.js admin-users add --test --yes
+          pnpm --filter pgpm exec node dist/index.js admin-users bootstrap --yes
+          pnpm --filter pgpm exec node dist/index.js admin-users add --test --yes
 
       - name: Test ${{ matrix.package }}
         run: cd ./${{ matrix.package }} && pnpm test
 
@@ -1,6 +1,6 @@
-# LaunchQL Agent Navigation Guide
+# Constructive Agent Navigation Guide
 
-This guide helps AI agents quickly navigate and understand the LaunchQL codebase without having to read everything. LaunchQL is a comprehensive full-stack framework for building secure, role-aware GraphQL APIs backed by PostgreSQL databases.
+This guide helps AI agents quickly navigate and understand the Constructive codebase without having to read everything. Constructive is a comprehensive full-stack framework for building secure, role-aware GraphQL APIs backed by PostgreSQL databases.
 
 ## 🎯 Quick Start for Agents
 
@@ -12,17 +12,17 @@ This guide helps AI agents quickly navigate and understand the LaunchQL codebase
 5. **`packages/types`** - TypeScript type definitions
 
 **Key Classes to Understand:**
-- **`LaunchQLPackage`** (`packages/core/src/core/class/launchql.ts`) - Workspace and module management
-- **`LaunchQLMigrate`** (`packages/core/src/migrate/client.ts`) - Database migration operations
+- **`PgpmPackage`** (`packages/core/src/core/class/pgpm.ts`) - Workspace and module management
+- **`PgpmMigrate`** (`packages/core/src/migrate/client.ts`) - Database migration operations
 
 ## 📦 Package Categories
 
 ### 🏗️ Core Framework
 | Package | Purpose | Key Files |
 |---------|---------|-----------|
-| **`core`** | Main orchestration, migrations, dependency resolution | `src/core/class/launchql.ts`, `src/migrate/client.ts` |
+| **`core`** | Main orchestration, migrations, dependency resolution | `src/core/class/pgpm.ts`, `src/migrate/client.ts` |
 | **`cli`** | Command-line interface (`lql` command) | `src/commands.ts`, `src/commands/deploy.ts` |
-| **`types`** | TypeScript type definitions | `src/launchql.ts` |
+| **`types`** | TypeScript type definitions | `src/pgpm.ts` |
 | **`env`** | Environment and configuration management | - |
 
 ### 🚀 API & Server
@@ -89,8 +89,8 @@ This guide helps AI agents quickly navigate and understand the LaunchQL codebase
 
 ## 🔑 Key Classes and Entry Points
 
-### LaunchQLPackage Class
-**Location:** `packages/core/src/core/class/launchql.ts`
+### PgpmPackage Class
+**Location:** `packages/core/src/core/class/pgpm.ts`
 
 **Purpose:** High-level orchestration for workspace and module management
 
@@ -107,7 +107,7 @@ This guide helps AI agents quickly navigate and understand the LaunchQL codebase
 - `getContext()` - Determine if in workspace, module, or outside
 - `isInWorkspace()` / `isInModule()` - Context checks
 
-### LaunchQLMigrate Class
+### PgpmMigrate Class
 **Location:** `packages/core/src/migrate/client.ts`
 
 **Purpose:** Low-level database migration operations
@@ -122,7 +122,7 @@ This guide helps AI agents quickly navigate and understand the LaunchQL codebase
 
 **Configuration:**
 - Supports `content` or `ast` hash methods for SQL files
-- Configurable via `LaunchQLMigrateOptions`
+- Configurable via `PgpmMigrateOptions`
 
 ### CLI Command Structure
 **Location:** `packages/cli/src/commands.ts`
@@ -150,7 +150,7 @@ export default async (argv: ParsedArgs, prompter: Inquirerer, options: CLIOption
 ### 1. Module Development Workflow
 ```typescript
 // 1. Initialize workspace
-const pkg = new LaunchQLPackage(cwd);
+const pkg = new PgpmPackage(cwd);
 pkg.initWorkspace();
 
 // 2. Create module
@@ -177,7 +177,7 @@ await db.query('SELECT 1'); // Ready for testing
 ### 3. Migration Workflow
 ```typescript
 // Direct migration operations
-const migrate = new LaunchQLMigrate(pgConfig);
+const migrate = new PgpmMigrate(pgConfig);
 await migrate.deploy({ modulePath: './my-module' });
 await migrate.verify({ modulePath: './my-module' });
 ```
@@ -187,7 +187,7 @@ await migrate.verify({ modulePath: './my-module' });
 ### Module Structure
 ```
 my-module/
-├── launchql.plan          # Migration plan
+├── pgpm.plan          # Migration plan
 ├── my-module.control      # Extension metadata
 ├── Makefile              # Build configuration
 ├── deploy/               # Deploy scripts
 
@@ -2,9 +2,10 @@
 
 This guide covers a local development workflow for the jobs stack:
 
-- Postgres + `launchql-ext-jobs`
+- Postgres + `launchql-database-jobs`
 - LaunchQL API server
 - `simple-email` function
+- `send-email-link` function
 - `knative-job-service`
 
 It assumes:
@@ -58,17 +59,17 @@ Make sure `pgpm` is installed and up to date.
 
 From the `constructive-db/` directory (with `pgenv` applied):
 
-1. Bootstrap admin users:
+1. Create the `launchql` database (if it does not already exist):
 
    ```sh
-   pgpm admin-users bootstrap --yes
-   pgpm admin-users add --test --yes
+   createdb launchql
    ```
 
-2. Create the `launchql` database (if it does not already exist):
+2. Bootstrap admin users:
 
    ```sh
-   createdb launchql
+   pgpm admin-users bootstrap --yes
+   pgpm admin-users add --test --yes
    ```
 
 3. Deploy the main app and jobs packages into `launchql`:
@@ -102,19 +103,111 @@ This starts:
 
 - `launchql-server` – GraphQL API server
 - `simple-email` – Knative-style HTTP function
+- `send-email-link` – Knative-style HTTP function
 - `knative-job-service` – jobs runtime (callback server + worker + scheduler)
 
 ---
 
-## 5. Enqueue a test job (simple-email)
+### Switching dry run vs real Mailgun sending
+
+By default, `docker-compose.jobs.yml` runs both email functions in dry-run mode (no real email is sent), and it uses placeholder Mailgun credentials unless you provide `MAILGUN_API_KEY` / `MAILGUN_KEY`.
+
+Quick start commands:
+
+Dry run:
+
+```sh
+docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
+```
+
+Real sending (Mailgun):
+
+```sh
+MAILGUN_API_KEY="your-mailgun-key" MAILGUN_KEY="your-mailgun-key" SIMPLE_EMAIL_DRY_RUN=false SEND_EMAIL_LINK_DRY_RUN=false docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
+```
+
+To use a real Mailgun key without editing `docker-compose.jobs.yml`, set these env vars before starting the stack (or put them in a local `.env` file in the `constructive/` directory). Don't commit your `.env`.
+
+```sh
+export MAILGUN_API_KEY="your-mailgun-key"
+export MAILGUN_KEY="your-mailgun-key"
+```
+
+If you're not using `mg.constructive.io`, also override `MAILGUN_DOMAIN`, `MAILGUN_FROM`, and `MAILGUN_REPLY` (for example in the override file below) to match your Mailgun setup.
+
+To actually send email (instead of dry-run), set these env vars (or put them in your local `.env`):
+
+```sh
+export SIMPLE_EMAIL_DRY_RUN=false
+export SEND_EMAIL_LINK_DRY_RUN=false
+```
+
+Then recreate the stack so the new env is applied:
+
+```sh
+docker compose -f docker-compose.jobs.yml up -d --build --force-recreate
+```
+
+If you prefer not to export env vars, create a local override file (don't commit it) at `docker-compose.jobs.override.yml`:
+
+```yml
+services:
+  simple-email:
+    environment:
+      SIMPLE_EMAIL_DRY_RUN: "false"
+
+  send-email-link:
+    environment:
+      SEND_EMAIL_LINK_DRY_RUN: "false"
+```
+
+Start the stack with both files:
+
+```sh
+docker compose -f docker-compose.jobs.yml -f docker-compose.jobs.override.yml up -d --build --force-recreate
+```
+
+To switch back to dry-run, set `SIMPLE_EMAIL_DRY_RUN=true` and `SEND_EMAIL_LINK_DRY_RUN=true` (or delete the override file) and recreate again.
+
+---
+
+## 5. Ensure GraphQL host routing works for `send-email-link`
+
+LaunchQL selects the API by the HTTP `Host` header using rows in `meta_public.domains`.
+
+For local development, `app-svc-local` seeds `admin.localhost` as the admin API domain. `docker-compose.jobs.yml` adds a Docker network alias so other containers can resolve `admin.localhost` to the `launchql-server` container, and `send-email-link` uses:
+
+- `GRAPHQL_URL=http://admin.localhost:3000/graphql`
+
+Quick check from your host (should return JSON, not HTML):
+
+```sh
+curl -s -H 'Host: admin.localhost' \
+  -H 'Content-Type: application/json' \
+  -X POST http://localhost:3000/graphql \
+  --data '{"query":"query { __typename }"}'
+```
+
+If your GraphQL server requires auth, set `GRAPHQL_AUTH_TOKEN` before starting the jobs stack (it is passed through to the `send-email-link` container).
+
+---
+
+## 6. Enqueue a test job (simple-email)
 
 With the jobs stack running, you can enqueue a test job from your host into the Postgres container:
 
+First, grab a real `database_id` (required by `send-email-link`, optional for `simple-email`):
+
+```sh
+DBID="$(docker exec -i postgres psql -U postgres -d launchql -Atc 'SELECT id FROM collections_public.database ORDER BY created_at LIMIT 1;')"
+echo "$DBID"
+```
+
 ```sh
 docker exec -it postgres \
   psql -U postgres -d launchql -c "
     SELECT app_jobs.add_job(
-      '00000000-0000-0000-0000-000000000001'::uuid,
+      '$DBID'::uuid,
       'simple-email',
       json_build_object(
         'to',      'user@example.com',
@@ -129,7 +222,39 @@ You should then see the job picked up by `knative-job-service` and the email pay
 
 ---
 
-## 6. Inspect logs and iterate
+## 7. Enqueue a test job (`send-email-link`)
+
+`send-email-link` queries GraphQL for site/database metadata, so it requires:
+
+- The app/meta packages deployed in step 3 (`app-svc-local`, `db-meta`)
+- A real `database_id` (use `$DBID` above)
+- A GraphQL hostname that matches a seeded domain route (step 5)
+
+With `SEND_EMAIL_LINK_DRY_RUN=true` (default in `docker-compose.jobs.yml`), enqueue a job:
+
+```sh
+docker exec -it postgres \
+  psql -U postgres -d launchql -c "
+    SELECT app_jobs.add_job(
+      '$DBID'::uuid,
+      'send-email-link',
+      json_build_object(
+        'email_type',   'invite_email',
+        'email',        'user@example.com',
+        'invite_token', 'invite123',
+        'sender_id',    '00000000-0000-0000-0000-000000000000'
+      )::json
+    );
+  "
+```
+
+You should see a log like:
+
+- `[send-email-link] DRY RUN email (skipping send) ...`
+
+---
+
+## 8. Inspect logs and iterate
 
 To watch logs while you develop:
 
@@ -153,7 +278,7 @@ docker compose -f docker-compose.jobs.yml up --build
 
 ---
 
-## 7. Stopping services
+## 9. Stopping services
 
 To stop only the jobs stack:
 
 
@@ -47,18 +47,18 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 
 ### 🔁 Streaming & Uploads
 
+* [etag-hash](https://github.com/constructive-io/constructive/tree/main/packages/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
+* [etag-stream](https://github.com/constructive-io/constructive/tree/main/packages/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
+* [uuid-hash](https://github.com/constructive-io/constructive/tree/main/packages/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
+* [uuid-stream](https://github.com/constructive-io/constructive/tree/main/packages/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
 * [launchql/s3-streamer](https://github.com/constructive-io/constructive/tree/main/packages/s3-streamer): **📤 Direct S3 streaming** for large files with support for metadata injection and content validation.
-* [launchql/etag-hash](https://github.com/constructive-io/constructive/tree/main/packages/etag-hash): **🏷️ S3-compatible ETags** created by streaming and hashing file uploads in chunks.
-* [launchql/etag-stream](https://github.com/constructive-io/constructive/tree/main/packages/etag-stream): **🔄 ETag computation** via Node stream transformer during upload or transfer.
-* [launchql/uuid-hash](https://github.com/constructive-io/constructive/tree/main/packages/uuid-hash): **🆔 Deterministic UUIDs** generated from hashed content, great for deduplication and asset referencing.
-* [launchql/uuid-stream](https://github.com/constructive-io/constructive/tree/main/packages/uuid-stream): **🌊 Streaming UUID generation** based on piped file content—ideal for upload pipelines.
 * [launchql/upload-names](https://github.com/constructive-io/constructive/tree/main/packages/upload-names): **📂 Collision-resistant filenames** utility for structured and unique file names for uploads.
 
 ### 🧰 CLI & Codegen
 
 * [pgpm](https://github.com/constructive-io/constructive/tree/main/packages/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
 * [@launchql/cli](https://github.com/constructive-io/constructive/tree/main/packages/cli): **🖥️ Command-line toolkit** for managing LaunchQL projects—supports database scaffolding, migrations, seeding, code generation, and automation.
-* [constructive-io/constructive-gen](https://github.com/constructive-io/constructive/tree/main/packages/launchql-gen): **✨ Auto-generated GraphQL** mutations and queries dynamically built from introspected schema data.
+* [launchql-gen](https://github.com/constructive-io/constructive/tree/main/packages/launchql-gen): **✨ Auto-generated GraphQL** mutations and queries dynamically built from introspected schema data.
 * [@launchql/query-builder](https://github.com/constructive-io/constructive/tree/main/packages/query-builder): **🏗️ SQL constructor** providing a robust TypeScript-based query builder for dynamic generation of `SELECT`, `INSERT`, `UPDATE`, `DELETE`, and stored procedure calls—supports advanced SQL features like `JOIN`, `GROUP BY`, and schema-qualified queries.
 * [@launchql/query](https://github.com/constructive-io/constructive/tree/main/packages/query): **🧩 Fluent GraphQL builder** for PostGraphile schemas. ⚡ Schema-aware via introspection, 🧩 composable and ergonomic for building deeply nested queries.