chore: launch-readiness — CI, community health, and AI-path fixes

CI (type-check + build on a pgvector service), SECURITY.md, CODE_OF_CONDUCT.md,
issue/PR templates, plus fixes from a pre-launch audit of the AI golden path
(EMBEDDING_DIM wiring, answer-model thinking budget, attachment handoff, router
bias, SSRF guard on URL ingestion, embedding order) and VERIFYING.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nullarch

.env.example

@@ -8,9 +8,10 @@ APP_URL=http://localhost:3000          # loader/iframe origin (CSP + email links
 ANTHROPIC_API_KEY=sk-ant-...
 EMBEDDINGS_PROVIDER=voyage             # voyage | openai | local(bge-m3)
 EMBEDDINGS_API_KEY=                    # provider key (omit for self-hosted bge-m3)
-EMBEDDINGS_MODEL=voyage-3              # must match EMBEDDING_DIM
-EMBEDDING_DIM=1024                     # 1024 voyage/bge-m3 ; 1536 openai text-embedding-3-small
-                                       #   (must match knowledge_chunk.embedding vector(N))
+EMBEDDINGS_MODEL=voyage-3              # must produce EMBEDDING_DIM-length vectors
+EMBEDDING_DIM=1024                     # 1024 voyage/bge-m3 · 1536 openai text-embedding-3-small
+                                       #   db:migrate sizes knowledge_chunk.embedding to this
+                                       #   value — re-run db:reset if you change it later
 # ANTHROPIC_MODEL_ROUTER=claude-haiku-4-5-20251001
 # ANTHROPIC_MODEL_ANSWER=claude-sonnet-5
 # ANTHROPIC_MODEL_HARD=claude-opus-4-8

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Something isn't working as expected
+title: ""
+labels: bug
+assignees: ""
+---
+
+**What happened?**
+A clear description of the bug.
+
+**Steps to reproduce**
+1. …
+2. …
+3. …
+
+**Expected behavior**
+What you expected to happen instead.
+
+**Environment**
+- Deployment: `docker compose` / local dev / managed host
+- openConcierge commit or version:
+- Postgres + pgvector version:
+- Embeddings provider: voyage / openai / local (bge-m3)
+- Browser (if this is a widget or desk issue):
+
+**Logs / screenshots**
+Paste relevant server logs or screenshots. **Scrub any secrets and customer PII first.**

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/nullarch/openconcierge/security/advisories/new
+    about: Please report security issues privately here, never as a public issue.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+**Problem**
+What are you trying to do that's hard or impossible today?
+
+**Proposed solution**
+What you'd like to see.
+
+**Alternatives considered**
+Other approaches you've thought about.
+
+**Scope check**
+Does this fit the MVP wedge (an AI concierge + self-hosted support desk), or is
+it a post-MVP item from the roadmap? Link the relevant roadmap point if you can.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!-- Thanks for contributing to openConcierge! -->
+
+## What & why
+<!-- What does this change, and why? Link any related issue, e.g. "Closes #123". -->
+
+## How to test
+<!-- Steps for a reviewer to verify the change. -->
+
+## Checklist
+- [ ] `npm run build` passes (type-check + build)
+- [ ] DB changes are a **new** timestamped file in `db/migrations/` (not an edit to an already-applied one)
+- [ ] No secrets, API keys, or customer PII in the diff
+- [ ] README / docs updated if behavior or setup changed

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Type-check and build
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: openconcierge
+          POSTGRES_PASSWORD: openconcierge
+          POSTGRES_DB: openconcierge
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U openconcierge"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DATABASE_URL: postgres://openconcierge:openconcierge@localhost:5432/openconcierge
+      APP_URL: http://localhost:3000
+      # Dummy AI config so the production build never needs real keys.
+      # (Keys are read at request time, not at build time.)
+      ANTHROPIC_API_KEY: build-only-not-used
+      EMBEDDINGS_PROVIDER: voyage
+      EMBEDDINGS_API_KEY: build-only-not-used
+      EMBEDDINGS_MODEL: voyage-3
+      EMBEDDING_DIM: "1024"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Apply migrations + seed
+        run: npm run db:migrate
+
+      - name: Build (includes the TypeScript type-check)
+        run: npm run build

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement privately through
+the repository's [Security Advisories](https://github.com/nullarch/openconcierge/security/advisories/new)
+or by direct message to a maintainer. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

README.md

@@ -159,6 +159,8 @@ npm run dev              # → http://localhost:3000
 
 `npm run build` runs the production build **and** the TypeScript type-check. `npm run db:reset` drops and re-applies migrations + seed.
 
+> **Verifying the AI concierge works?** The live golden path (grounded answer + citations + handoff) needs your keys and a pgvector Postgres — see **[VERIFYING.md](VERIFYING.md)**.
+
 ### Managed hosting
 
 Runs on any Node host (Fly.io, Railway, Render, a plain VM) against a managed Postgres that has `pgvector` (Neon, Supabase Postgres, RDS, Crunchy…). Set the env below and run `npm run db:migrate` once.

SECURITY.md

@@ -0,0 +1,38 @@
+# Security Policy
+
+openConcierge is self-hosted software that handles customer conversations and
+personal data. We take security seriously and appreciate responsible disclosure.
+
+## Supported versions
+
+openConcierge is pre-1.0 and moves quickly. Security fixes land on `main` —
+please run a recent commit. There are no long-term-support branches yet.
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security problems.**
+
+Report privately through GitHub Security Advisories:
+
+👉 https://github.com/nullarch/openconcierge/security/advisories/new
+
+Please include a description, reproduction steps, the affected version/commit,
+and the impact. We aim to acknowledge within 72 hours and to ship a fix or
+mitigation as quickly as the severity warrants. We're happy to credit you unless
+you'd prefer to stay anonymous.
+
+## Scope
+
+Because you self-host, your deployment's security is ultimately yours. The
+highest-value reports concern the **code itself**:
+
+- authentication / session handling (`src/lib/auth.ts`, `src/lib/password.ts`)
+- the widget ↔ desk trust boundary and anonymous-visitor identity
+- SQL construction (`src/lib/db.ts` and callers)
+- file-upload handling (`src/lib/storage.ts`, the upload routes)
+- SSRF via URL ingestion in the knowledge base (`src/lib/ai/`)
+- secret handling and accidental exposure
+
+Misconfigured infrastructure (a publicly reachable `DATABASE_URL`, missing TLS,
+a committed `.env`) is out of scope, but the README's self-hosting section has
+hardening notes to help you avoid it.

VERIFYING.md

@@ -0,0 +1,68 @@
+# Verifying the AI concierge
+
+`npm run build` and CI verify types + schema, but the AI path (retrieval →
+grounded answer → citations → handoff) only runs with **real keys against a
+pgvector Postgres**. This is the ~2-minute check that the live golden path works.
+
+## 1. Run with keys + pgvector
+
+The bundled Docker stack ships pgvector; a bare local Postgres often doesn't
+(`create extension vector` will fail if the extension isn't installed).
+
+```bash
+cp .env.example .env
+# In .env, set at least:
+#   ANTHROPIC_API_KEY=sk-ant-...
+#   EMBEDDINGS_API_KEY=...                      (Voyage or OpenAI)
+#   EMBEDDINGS_PROVIDER / _MODEL / EMBEDDING_DIM  (defaults: voyage-3 / 1024)
+docker compose up          # → http://localhost:3000
+```
+
+Your key stays in `.env` — never paste it into a shell that logs it, or into a PR.
+If you change `EMBEDDING_DIM`, run `npm run db:reset` (it re-sizes the vector column).
+
+## 2. Feed it knowledge
+
+Open http://localhost:3000 → sign up (the first user becomes the owner) →
+**Knowledge** → add a source (paste an FAQ, or a public URL) → wait for status
+**ready**.
+
+Confirm it actually embedded:
+
+```sql
+select title, status, chunk_count from knowledge_source;
+-- want: status = 'ready', chunk_count > 0
+```
+
+If it's stuck at **error**, the `error` column says why (wrong `EMBEDDING_DIM`,
+bad embeddings key, or a private URL blocked by the SSRF guard).
+
+## 3. Ask — and watch it answer
+
+Open http://localhost:3000/embed-test.html → open the bubble → ask something the
+source covers.
+
+**Expect:** a grounded answer with a **Source** chip within a few seconds.
+
+Then ask something off-topic, or type "I'd like to talk to a person" → **expect a
+handoff** ("someone will reply shortly"), and the conversation appears in `/desk`
+flagged *needs human*. Reply from the desk and watch it arrive in the widget live.
+
+## If it hands off instead of answering
+
+Every handoff records a reason (in `message.log` and the server logs):
+
+| reason | meaning | what to do |
+|---|---|---|
+| `no_knowledge` | no source is `ready` | add a source; confirm it reached `ready` |
+| `low_confidence` | retrieval scored below threshold | question isn't covered, or an `EMBEDDING_DIM` mismatch — re-ingest |
+| `router_escalate` | the router saw no relevant source | expected for genuinely off-topic questions |
+| `explicit_request` | the visitor asked for a human | expected |
+| `attachment` | the message was image/file-only | expected — the concierge can't read files |
+| `ai_error` | a Claude or embeddings call threw | check your keys and the server logs |
+
+## What CI covers
+
+`.github/workflows/ci.yml` builds against a real pgvector service and runs the
+migrations on every push/PR — so the schema and type-check are always green. It
+does **not** call the AI (no keys in CI); the live check above is yours to run.