Finalize staging cleanup and safety hardening

.env.example

@@ -1,5 +1,8 @@
 # Production or staging environment template.
 # Set these in your hosting provider's environment-variable UI instead of committing a real .env file.
+# Prefer provider-managed secrets or mounted files. Any private key below can also be supplied as `${NAME}_FILE=/run/secrets/${NAME}`.
+
+KB_ENVIRONMENT="production"
 
 # Optional: Mapbox access token for event location/address geocoding (server).
 # Get a token at https://account.mapbox.com/access-tokens/
@@ -27,6 +30,7 @@ SMTP_PASS=""
 SMTP_FROM="\"Knowledge Basket\" <noreply@example.com>"
 
 # Sentry (errors + performance)
+# Use separate DSNs or projects for staging so non-production traffic stays isolated.
 PUBLIC_SENTRY_DSN="https://public-key@o0.ingest.us.sentry.io/0"
 SENTRY_DSN="https://public-key@o0.ingest.us.sentry.io/0"
 PUBLIC_SENTRY_TRACES_SAMPLE_RATE="0.1"
@@ -39,16 +43,17 @@ PUBLIC_SENTRY_FEEDBACK_AUTO_INJECT="false"
 PUBLIC_SENTRY_ENABLE_DEV="false"
 PUBLIC_SENTRY_ENVIRONMENT="production"
 PUBLIC_SENTRY_RELEASE=""
+SENTRY_ENVIRONMENT="production"
+SENTRY_RELEASE=""
 SENTRY_ENABLE_LOGS="true"
 
 # Optional: enable source map uploads during build.
 # SENTRY_AUTH_TOKEN=""
 # SENTRY_ORG=""
 # SENTRY_PROJECT=""
-# SENTRY_RELEASE=""
-# SENTRY_ENVIRONMENT="production"
 
 # PostHog (product analytics + session replay; explicit events only, after analytics consent)
+# Use a separate staging project or source so staging traffic does not pollute production funnels.
 PUBLIC_POSTHOG_KEY="phc_your_project_api_key"
 PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
 

.env.local.example

@@ -1,5 +1,8 @@
 # Local development template.
 # Copy this file to `.env` for everyday local development.
+# Mounted secret files also work locally. Example: `BETTER_AUTH_SECRET_FILE=.secrets/better-auth-secret`.
+
+KB_ENVIRONMENT="development"
 
 # Optional: Mapbox access token for event location/address geocoding (server).
 # Get a token at https://account.mapbox.com/access-tokens/

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @haydenkoch

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10

.github/pull_request_template.md

@@ -0,0 +1,37 @@
+## Summary
+
+-
+
+## Linear Issue
+
+- Closes:
+
+## Risk Level
+
+- [ ] Low
+- [ ] Medium
+- [ ] High
+
+## Migration Impact
+
+- [ ] No schema or data migration
+- [ ] Requires committed migration files
+
+## Rollback Plan
+
+-
+
+## Testing
+
+- [ ] `pnpm lint`
+- [ ] `pnpm check`
+- [ ] Other:
+
+## Staging Verification
+
+- [ ] Not required
+- [ ] `GET /api/health` verified
+- [ ] Auth smoke-tested
+- [ ] Search smoke-tested
+- [ ] Uploads/assets smoke-tested
+- [ ] Admin/source-ops smoke-tested

.github/workflows/ci.yml

@@ -40,6 +40,7 @@ jobs:
       SMTP_HOST: 127.0.0.1
       SMTP_PORT: 1025
       SMTP_FROM: '"Knowledge Basket" <noreply@example.com>'
+      PUBLIC_ASSET_BASE_URL: http://127.0.0.1:4273/assets
       MEILISEARCH_HOST: http://127.0.0.1:7700
       MEILISEARCH_API_KEY: kbdev
       REINDEX_SECRET: ci-reindex-secret-1234567890123456
@@ -58,28 +59,30 @@ jobs:
             run: pnpm build
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
         with:
           fetch-depth: 0
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: 24
           cache: pnpm
 
       - name: Install
         run: pnpm install --frozen-lockfile
 
+      - name: Verify committed migrations
+        if: matrix.task == 'typecheck'
+        run: node scripts/check-migrations-ci.mjs
+
       - name: Run ${{ matrix.task }}
         run: ${{ matrix.run }}
 
       - name: Upload build artifact
         if: matrix.task == 'build'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
         with:
           name: app-build
           path: build
@@ -107,13 +110,11 @@ jobs:
         shard: [1, 2, 3]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: 24
           cache: pnpm
@@ -164,13 +165,11 @@ jobs:
           --health-retries 5
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: 24
           cache: pnpm
@@ -179,7 +178,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Download build artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
         with:
           name: app-build
           path: build
@@ -208,8 +207,8 @@ jobs:
           throw new Error('Timed out waiting for Postgres');
           EOF
 
-      - name: Apply database schema
-        run: pnpm db:deploy
+      - name: Bootstrap ephemeral database schema
+        run: pnpm db:push --force
 
       - name: Seed database
         run: pnpm db:seed:ci
@@ -264,13 +263,11 @@ jobs:
           --health-retries 10
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: 24
           cache: pnpm
@@ -279,7 +276,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Download build artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
         with:
           name: app-build
           path: build
@@ -320,8 +317,8 @@ jobs:
           }
           EOF
 
-      - name: Apply database schema
-        run: pnpm db:deploy
+      - name: Bootstrap ephemeral database schema
+        run: pnpm db:push --force
 
       - name: Seed database
         run: pnpm db:seed:ci
@@ -362,13 +359,11 @@ jobs:
           --health-retries 5
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: 24
           cache: pnpm
@@ -377,7 +372,7 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Download build artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
         with:
           name: app-build
           path: build
@@ -406,8 +401,8 @@ jobs:
           throw new Error('Timed out waiting for Postgres');
           EOF
 
-      - name: Apply database schema
-        run: pnpm db:deploy
+      - name: Bootstrap ephemeral database schema
+        run: pnpm db:push --force
 
       - name: Seed database
         run: pnpm db:seed:ci
@@ -455,13 +450,11 @@ jobs:
           --health-retries 5
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 10
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
           node-version: 24
           cache: pnpm
@@ -470,13 +463,13 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Download build artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
         with:
           name: app-build
           path: build
 
       - name: Restore Playwright browser cache
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830
         with:
           path: ~/.cache/ms-playwright
           key: ${{ runner.os }}-playwright-${{ hashFiles('pnpm-lock.yaml') }}
@@ -508,8 +501,8 @@ jobs:
           throw new Error('Timed out waiting for Postgres');
           EOF
 
-      - name: Apply database schema
-        run: pnpm db:deploy
+      - name: Bootstrap ephemeral database schema
+        run: pnpm db:push --force
 
       - name: Seed database
         run: pnpm db:seed:ci
@@ -519,7 +512,7 @@ jobs:
 
       - name: Upload Playwright artifacts
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
         with:
           name: playwright-artifacts-${{ matrix.project }}
           path: |

.github/workflows/pr-title.yml

@@ -0,0 +1,33 @@
+name: PR Title
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+
+permissions: {}
+
+jobs:
+  validate-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate Conventional Commit PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          node <<'EOF'
+          const title = process.env.PR_TITLE ?? '';
+          const pattern =
+            /^(build|chore|ci|docs|feat|fix|perf|refactor|release|revert|security|style|test)(\([^)]+\))?!?: .+/;
+
+          if (!pattern.test(title)) {
+            console.error(`Invalid PR title: "${title}"`);
+            console.error(
+              'Use Conventional Commit style, for example: fix(search): handle empty queries'
+            );
+            process.exit(1);
+          }
+          EOF

.prettierignore

@@ -10,3 +10,7 @@ bun.lockb
 /drizzle/
 /.claude/
 /test-results/
+/AGENTS.md
+/CLAUDE.md
+/docs/plans/**
+/docs/reviews/**