databuddy-analytics · izadoesdev · Sep 17, 2026 · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026
diff --git a/.agents/skills/databuddy-internal/SKILL.md b/.agents/skills/databuddy-internal/SKILL.md
diff --git a/.agents/skills/databuddy-internal/references/codebase-map.md b/.agents/skills/databuddy-internal/references/codebase-map.md
@@ -9,6 +9,8 @@ Use this file when the task spans multiple packages or when the right edit locat
 - Theme tokens and WCAG-oriented contrast: `apps/dashboard/app/globals.css` (`:root`, `.dark`)
 - Next.js dashboard application
 - Default dev port: `3000`
+- For local app review, use `bun run dev:dashboard` with the same existing root `.env` across services; do not blank billing or AI credentials and present the resulting environment as a working app.
+- Include interaction feedback in billing/pricing work: short transform/opacity reveals, native pending buttons with accessible labels, and reduced-motion support. Keep disabled billing details unmounted and verify motion in the local browser.
 - Talks to the backend through oRPC using [`apps/dashboard/lib/orpc.ts`](/Users/iza/Dev/Databuddy/apps/dashboard/lib/orpc.ts)
 - **Status pages:** Public page lives under `app/status/[slug]`; **dashboard** edit surface is `app/(main)/monitors/status-pages/[id]/page.tsx`. For stable chrome (no tab strip pop-in), keep `Tabs` always mounted and gate **content** with `useFeatureAccess` + `FeatureLockedPanel`—do not wrap the whole `Tabs` in `FeatureAccessGate` with a list-only `loadingFallback`. Reserve `PageHeader` `right` with skeletons until `statusPage` loads; use a static `description` and breadcrumb fallback `"Status page"` so the header does not reflow on fetch.
 - Typical work:
@@ -54,6 +56,7 @@ Use this file when the task spans multiple packages or when the right edit locat
 - Next.js docs site using Fumadocs
 - Default dev port: `3005`
 - Good place for product docs, guides, and marketing-adjacent content with app integrations
+- `SciFiButton` styles its inner control separately from the corner-frame wrapper. In stretched pricing-card layouts, use `className="w-full"` and verify their bounds match at desktop and mobile widths.
 - Pricing for agents: `public/pricing.md`; `GET /api/pricing` (JSON or markdown via `Accept`); middleware rewrites `/pricing` → `/api/pricing` when markdown wins.
 - Cookie cost calculator: [`apps/docs/app/(home)/calculator/`](/Users/iza/Dev/Databuddy/apps/docs/app/(home)/calculator/) — uses **visitor data loss rate** (consent / analytics visibility), not “banner bounce”; literature band 40–70% in `calculator-engine.ts`.
 
@@ -73,7 +76,7 @@ Use this file when the task spans multiple packages or when the right edit locat
   - Postgres schema and relations
   - ClickHouse client and schema
 - Key files:
-  - [`packages/db/src/drizzle/schema.ts`](/Users/iza/Dev/Databuddy/packages/db/src/drizzle/schema.ts)
+  - [`packages/db/src/drizzle/schema/index.ts`](/Users/iza/Dev/Databuddy/packages/db/src/drizzle/schema/index.ts)
   - [`packages/db/src/drizzle/relations.ts`](/Users/iza/Dev/Databuddy/packages/db/src/drizzle/relations.ts)
   - [`packages/db/src/client.ts`](/Users/iza/Dev/Databuddy/packages/db/src/client.ts) — strips `sslrootcert=system` from `DATABASE_URL` before `pg` Pool: libpq uses it for the OS trust store, but node-postgres treats `sslrootcert` as a file path and throws `ENOENT` on path `"system"`.
   - [`packages/db/src/clickhouse/client.ts`](/Users/iza/Dev/Databuddy/packages/db/src/clickhouse/client.ts)

diff --git a/.env.example b/.env.example
@@ -1,3 +1,5 @@
+# Local development. For Docker self-hosting, use selfhost.env.example.
+
 CLICKHOUSE_URL="http://default:@localhost:8123/databuddy_analytics"
 # Required by DQL. This must use the separately provisioned dql_user account;
 # never point it at the application/admin ClickHouse credentials.
@@ -6,13 +8,6 @@ DATABASE_URL="postgres://databuddy:databuddy_dev_password@localhost:5432/databud
 REDIS_URL="redis://localhost:6379"
 BULLMQ_REDIS_URL="redis://localhost:6379"
 
-# Required only by docker-compose.selfhost.yml. Use URL-safe passwords and make
-# the local database URLs above use the same credentials before initialization.
-IMAGE_TAG=""
-POSTGRES_PASSWORD=""
-CLICKHOUSE_PASSWORD=""
-REDIS_PASSWORD=""
-
 # Public URLs. Local development uses built-in localhost defaults when blank.
 DASHBOARD_URL=""
 API_URL=""
@@ -31,12 +26,15 @@ FIRECRAWL_API_KEY=""
 SUPERMEMORY_API_KEY=""
 
 BETTER_AUTH_URL="http://localhost:3000"
-# Required by docker-compose.selfhost.yml. Generate independent random values.
+# Generate independent random values for sessions and encryption.
 BETTER_AUTH_SECRET="generate-a-random-32-byte-base64-secret"
 DATABUDDY_ENCRYPTION_KEY=""
 
 AUTUMN_SECRET_KEY=""
 
+# Dub conversion tracking (server-side lead events on sign-up)
+DUB_API_KEY=""
+
 # Local dev default. Root build/start scripts force NODE_ENV=production.
 NODE_ENV=development
 
@@ -57,7 +55,8 @@ GOOGLE_CLIENT_SECRET=""
 RESEND_API_KEY=""
 # Required when RESEND_API_KEY is set; use a domain verified in Resend.
 EMAIL_FROM="Databuddy <no-reply@example.com>"
-ALERTS_EMAIL_FROM="Databuddy <alerts@example.com>"
+# Optional alert-specific sender; defaults to EMAIL_FROM.
+ALERTS_EMAIL_FROM=""
 NEXT_PUBLIC_OPENAI_ADS_PIXEL_ID=""
 
 # Slack bot / AI agent adapter

@@ -81,6 +81,7 @@ jobs:
           restore-keys: ${{ runner.os }}-bun-
       - run: bun install --frozen-lockfile --ignore-scripts
       - run: bun run --cwd apps/docs postinstall
+      - run: bun run --cwd apps/docs lint:links
       - run: bun run check-types
       - name: ClickHouse types match DDL
         run: bun run --cwd packages/db ch:check
@@ -181,12 +182,22 @@ jobs:
           CLICKHOUSE_URL: http://default:@localhost:8123
           NODE_ENV: test
         run: bun run test
+      - name: Self-hosted dashboard settings
+        run: >-
+          bun test --no-env-file apps/dashboard/next-config.test.ts
+          apps/dashboard/app/layout.test.ts
+          apps/dashboard/lib/app-url.test.ts
+          'apps/dashboard/app/(main)/websites/[id]/_components/utils/code-generators.test.ts'
+          'apps/dashboard/app/(main)/onboarding/_components/step-install-tracking.test.ts'
+          packages/auth/src/selfhost-config.test.ts
+      - name: Self-hosted billing UI
+        run: bun test --no-env-file --isolate apps/dashboard/components/providers/selfhost-billing.test.tsx
       - name: Business context integration
         env:
           NODE_ENV: test
           BUSINESS_CONTEXT_INTEGRATION_TESTS: "true"
         run: |
-          bun test packages/services/src/organization-business-context.integration.test.ts packages/services/src/organization-business-context-hardening.integration.test.ts
+          bun test packages/services/src/organization-business-context.integration.test.ts packages/services/src/business-memory.integration.test.ts packages/services/src/measurement-plan.integration.test.ts
           bun test packages/auth/src/organization-metadata.integration.test.ts
       - name: Insights integration
         env:

@@ -0,0 +1,30 @@
+name: Publish Self-host Init Image
+
+on:
+  release:
+    types: [published]
+  push:
+    branches: [main]
+    paths:
+      - "init.Dockerfile"
+      - ".dockerignore"
+      - "apps/**"
+      - "packages/**"
+      - "tsconfig/**"
+      - "bun.lock"
+      - "package.json"
+      - "turbo.json"
+      - ".github/workflows/docker-publish.yml"
+      - ".github/workflows/docker-publish-init.yml"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+      security-events: write
+    uses: ./.github/workflows/docker-publish.yml
+    with:
+      init-only: true
@@ -15,9 +15,15 @@ on:
       - "turbo.json"
       - ".github/workflows/docker-publish.yml"
   workflow_dispatch:
+  workflow_call:
+    inputs:
+      init-only:
+        description: Publish only the self-host database initialization image
+        type: boolean
+        default: false
 
 concurrency:
-  group: docker-${{ github.ref }}
+  group: docker-${{ github.ref }}${{ inputs.init-only && '-init' || '' }}
   cancel-in-progress: ${{ github.event_name != 'release' }}
 
 env:
@@ -46,9 +52,14 @@ jobs:
       - run: bun install --frozen-lockfile --ignore-scripts
       - id: detect
         env:
+          INIT_ONLY: ${{ inputs.init-only }}
           EVENT_NAME: ${{ github.event_name }}
           BEFORE_SHA: ${{ github.event.before }}
         run: |
+          if [[ "$INIT_ONLY" == "true" ]]; then
+            echo 'services=["init"]' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
           ALL='["api","basket","dashboard","insights","links","uptime"]'
           if [[ "$EVENT_NAME" != "push" ]]; then
             echo "services=$ALL" >> "$GITHUB_OUTPUT"
@@ -136,6 +147,7 @@ jobs:
             api) text="Databuddy API service - analytics backend" ;;
             basket) text="Databuddy Basket service - event ingestion" ;;
             dashboard) text="Databuddy Dashboard service - web analytics UI" ;;
+            init) text="Databuddy database initialization and schema tools" ;;
             insights) text="Databuddy Insights service - queued insight generation" ;;
             links) text="Databuddy Links service - URL shortening and tracking" ;;
             uptime) text="Databuddy Uptime service - availability monitoring" ;;

@@ -5,6 +5,9 @@ on:
     branches: [main]
     paths:
       - "*.Dockerfile"
+      - "docker-compose.selfhost.yml"
+      - "selfhost.env.example"
+      - "scripts/test-selfhost-init.sh"
       - ".dockerignore"
       - "apps/api/**"
       - "apps/basket/**"
@@ -15,11 +18,15 @@ on:
       - "bun.lock"
       - "package.json"
       - "turbo.json"
+      - "tsconfig/**"
       - ".github/workflows/health-check.yml"
   pull_request:
     branches: [main, staging]
     paths:
       - "*.Dockerfile"
+      - "docker-compose.selfhost.yml"
+      - "selfhost.env.example"
+      - "scripts/test-selfhost-init.sh"
       - ".dockerignore"
       - "apps/api/**"
       - "apps/basket/**"
@@ -30,6 +37,7 @@ on:
       - "bun.lock"
       - "package.json"
       - "turbo.json"
+      - "tsconfig/**"
       - ".github/workflows/health-check.yml"
 
 permissions:
@@ -40,6 +48,14 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  selfhost-init:
+    name: Self-host Database Initialization
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+      - run: bash scripts/test-selfhost-init.sh
+
   vector-config-check:
     name: Vector Delivery Canary
     runs-on: blacksmith-2vcpu-ubuntu-2404

diff --git a/AGENTS.md b/AGENTS.md
@@ -160,6 +160,7 @@ For picker controls, use the component that matches the interaction:
 - **Start fresh**: Check for an existing PR that owns the same surface, public contract, schema, or deployment configuration, then create the branch from an up-to-date `origin/staging`. Do not use an unmerged feature branch as a base unless the dependency is explicit, approved, and named as `Depends on #…` in both PRs.
 - **Make ownership visible**: Push and open a draft PR against `staging` once the slice has a first commit. State its scope, dependencies, and known overlaps.
 - **Keep integration linear**: Rebase a slice onto current `origin/staging` before it is ready for review; do not merge `staging` into the slice merely to refresh it. Request fresh review when a rebase changes reviewed code.
+- **Resolve all review feedback before merging**: Mark the PR ready and wait for configured reviewers to finish on the final head; green CI alone is insufficient. Read every page of general comments, reviews, and inline threads, including outdated threads. Fix actionable findings or document a supported reason for declining them, then resolve each thread. Immediately before merging, re-fetch feedback and verify zero unresolved threads and no unaddressed comments or pending reviews. Never merge immediately after marking a draft ready or pushing review fixes while reviewers are still running.
 - **Isolate parallel work**: Use one worktree per active branch. Never let two agents or contributors mutate the same branch or reuse a task branch for a different concern.
 - **Retire completed work**: Merged PR source branches are automatically deleted. Delete closed PR branches manually, remove clean finished worktrees, and create a new branch from current `staging` for any follow-up—never revive or repurpose an old PR branch.
 

diff --git a/AI_POLICY.md b/AI_POLICY.md
@@ -1,73 +1,29 @@
-# AI Usage Policy
+# AI usage policy
 
-The Databuddy project has strict rules for AI usage:
+AI tools are welcome here. You're responsible for the work you submit: understand
+it, check it, and make it useful to the people reviewing it.
 
-- **All AI usage in any form must be disclosed.** You must state
-  the tool you used (e.g. Claude Code, Cursor, GitHub Copilot, ChatGPT) along with
-  the extent that the work was AI-assisted.
+These requirements apply to outside contributions. Maintainers may use AI tools
+at their discretion.
 
-- **Pull requests created in any way by AI can only be for accepted issues.**
-  Drive-by pull requests that do not reference an accepted issue will be
-  closed. If AI isn't disclosed but a maintainer suspects its use, the
-  PR will be closed. If you want to share code for a non-accepted issue,
-  open a discussion or attach it to an existing discussion.
+## Before you submit
 
-- **Pull requests created by AI must have been fully verified with
-  human use.** AI must not create hypothetically correct code that
-  hasn't been tested. Importantly, you must not allow AI to write
-  code for platforms or environments you don't have access to manually
-  test on.
+- **Disclose all AI use.** Name the tool and explain which parts of the work it helped with.
+- **Start with an accepted issue.** Every AI-assisted PR must reference one. For other ideas, open a discussion or share code in an existing discussion first.
+- **Review and test the complete change yourself.** AI-assisted PRs must be verified through human use. Don't submit code for a platform or environment you can't test manually.
+- **Edit issues and discussions yourself.** Review and edit AI-assisted text before posting. Check the facts and remove noise.
+- **Keep AI assistance to text and code.** AI-generated images, video, audio, and other media aren't accepted.
 
-- **Issues and discussions can use AI assistance but must have a full
-  human-in-the-loop.** This means that any content generated with AI
-  must have been reviewed _and edited_ by a human before submission.
-  AI is very good at being overly verbose and including noise that
-  distracts from the main point. Humans must do their research and
-  trim this down.
+PRs that don't meet these requirements, including undisclosed AI use, will be
+closed. A maintainer will also close a PR if they suspect undisclosed AI use.
+Contributors who misuse AI will be banned.
 
-- **No AI-generated media is allowed (art, images, videos, audio, etc.).**
-  Text and code are the only acceptable AI-generated content, per the
-  other rules in this policy.
+## Make review easier
 
-- **Bad AI drivers will be banned and ridiculed in public.** You've
-  been warned. We love to help junior developers learn and grow, but
-  if you're interested in that then don't use AI, and we'll help you.
-  I'm sorry that bad AI drivers have ruined this for you.
-
-These rules apply only to outside contributions to Databuddy. Maintainers
-are exempt from these rules and may use AI tools at their discretion;
-they've proven themselves trustworthy to apply good judgment.
-
-## There are Humans Here
-
-Please remember that Databuddy is maintained by humans.
-
-Every discussion, issue, and pull request is read and reviewed by
-humans (and sometimes machines, too). It is a boundary point at which
-people interact with each other and the work done. It is rude and
-disrespectful to approach this boundary with low-effort, unqualified
-work, since it puts the burden of validation on the maintainer.
-
-In a perfect world, AI would produce high-quality, accurate work
-every time. But today, that reality depends on the driver of the AI.
-And today, most drivers of AI are just not good enough. So, until either
-the people get better, the AI gets better, or both, we have to have
-strict rules to protect maintainers.
-
-## AI is Welcome Here
-
-Databuddy is written with plenty of AI assistance, and many maintainers embrace
-AI tools as a productive tool in their workflow. As a project, we welcome
-AI as a tool!
-
-**Our reason for the strict AI policy is not due to an anti-AI stance**, but
-instead due to the number of highly unqualified people using AI. It's the
-people, not the tools, that are the problem.
-
-I include this section to be transparent about the project's usage about
-AI for people who may disagree with it, and to address the misconception
-that this policy is anti-AI in nature.
+Share what you tried, what you checked, and what still needs help. If you're
+learning, ask questions and we'll help you find a starting point.
 
 ---
 
-_This policy is adapted from the [Ghostty project's AI Usage Policy](https://github.com/ghostty-org/ghostty/blob/main/AI_POLICY.md), originally created by [mitchellh](https://github.com/mitchellh) and the Ghostty team. Thanks for setting the standard._
+Adapted from the [Ghostty AI Usage Policy](https://github.com/ghostty-org/ghostty/blob/main/AI_POLICY.md)
+by [mitchellh](https://github.com/mitchellh) and the Ghostty team.