docs: fix self-host first-run break, pgvector prereq, licensing drift

[devin-ai-integration]

What

Open-source audit of the repo. Secrets/leftovers came back clean (gitleaks over all 430 commits found only the dummy pk_test_Y2xlcmsuZXhhbXBsZS5jb20k in CI; no keys, PEMs, personal data, .env, or internal links in tree or history). The fixes here are all self-hosting/licensing accuracy:

• backend/.env.example crash-loops a fresh self-host. It shipped MERMAID_VALIDATOR_BASE_URL=http://localhost:3000 with an empty MERMAID_VALIDATOR_SECRET, and config.Load rejects a half-set pair — so the documented path (cp .env.example .env → docker compose up) never starts: loading config: MERMAID_VALIDATOR_BASE_URL and MERMAID_VALIDATOR_SECRET must be configured together, restarting forever. Both are now commented out, with the pairing rule stated in the file and in the self-hosting guide.
• Vendor origins were the example values. DASHBOARD_BASE_URL=https://argus.reviews / API_BASE_URL=https://api.argus.reviews / GITHUB_APP_SLUG=argus-eye meant a self-host that copied the example posted GitHub comments linking to a dashboard it doesn't run. Example now defaults to localhost + your-app-slug, and the fallback behaviour is documented.
• pgvector prerequisite was undocumented. Migration 057 hard-fails below pgvector 0.8.2, but README only said "PostgreSQL (or Neon)". Added a Postgres requirements section (required pgvector ≥ 0.8.2, optional pgcontext, CREATE EXTENSION privilege).
• docs/architecture.md claimed a different license than the repo has — a "Sustainable Use License" core/enterprise split with .ee. files (no such files exist, LICENSE is AGPL-3.0, README says no feature gating). Rewritten to AGPL-3.0.
• Embeddings docs matched neither the code defaults (api.voyageai.com/v1 + voyage-4) nor the example file; EMBEDDINGS_DIMENSIONS was the one env var in code but not in .env.example. Both fixed.
• test command (@<slug> test [--code]) was missing from the architecture command table/regex/flowchart; CONTRIBUTING now says the CLAUDE.md adversarial gate is maintainer-side so external contributors don't try to run it.

Why

The repo is public and self-hosting is the headline promise, but the documented first run does not boot, and the license section contradicts LICENSE.

Verified end to end on a clean machine: docker compose down -v then cp .env.example .env + ENCRYPTION_KEY → migrations apply to version 85 and GET /healthz returns {"status":"ok"}. Before the change the same sequence crash-loops.

Checklist

• Tests pass — docs/env-example only; no Go or TS source changed (backend builds clean in the compose image build)
• Lint passes — no code touched
• Web typecheck — web/ unchanged
• No secrets or credentials in the diff
• Updated docs if behavior changed

Link to Devin session: https://app.devin.ai/sessions/574b4293927945cead22d3c0c80c5767
Open in Devin Desktop: https://app.devin.ai/desktop/session/574b4293927945cead22d3c0c80c5767?variant=devin
Requested by: @BeLazy167

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

[devin-ai-integration]

🟡 Direct setup ignores copied configuration

After users edit .env, the documented go run commands never load it. Startup fails because required database and GitHub settings remain unset.

Prompt for agents

Update docs/self-hosting.md's direct backend setup to distinguish shell execution from Docker Compose. The Go binaries read process environment variables and do not load backend/.env. Tell users to export the file before running go run (for example with set -a; source .env; set +a), or provide an equivalent command that explicitly loads it. Keep the note that Docker Compose loads backend/.env automatically.

---

Was this helpful? React with 👍 or 👎 to provide feedback.