docs: make self-hosting and contribution guides clearer

[izadoesdev]

The README now gives founders, self-hosters, and contributors a clear starting point. It replaces stale badges, speculative features, and repeated FAQs with a short product introduction and direct links to each path.

Self-host instructions start from the short self-host environment template and cover direct ClickHouse delivery, disabled hosted billing and Databuddy telemetry, and optional email and AI. Setup and upgrades cover matching releases, secret generation, public URLs, database prompts, DQL's separate setup, and the optional status app. The contributor guide uses supported Node releases, enables local development without billing keys, fixes outdated commands, and keeps the branch/review workflow. The AI policy keeps disclosure, accepted-issue, human-verification, media, and enforcement requirements while removing personal attacks and public-shaming language.

The three guides are about one-quarter shorter overall. Documentation only; no runtime changes.

Validation and dependencies

• Checked commands against package scripts, Turbo tasks, Compose, and the verified self-host flow. Local links, heading anchors, and code fences pass.
• Repository lint, all 33 typecheck tasks, and all 29 test tasks pass. Independent copy and technical reviews completed.
• Ran the documented status production build/start with synthetic local URLs: build passed, port 3002 served a healthy response, and robots.txt used the configured status URL.
• Depends on fix(api): honor self-hosted email sender settings #803, fix(ci): simplify self-host setup and database initialization #804, fix(basket): allow self-hosted ingestion without hosted billing #805, fix(dashboard): support custom-domain self-host onboarding #806, fix(env): simplify self-host runtime defaults #814, fix(basket): use direct delivery when self-hosting #815, and fix(rpc): remove hosted billing requirements from self-hosting #816 for the documented self-host behavior; all are merged. Rebased directly onto staging containing fix(ci): simplify self-host setup and database initialization #804. This PR owns the README copy previously in fix(ci): simplify self-host setup and database initialization #804, plus CONTRIBUTING.md and AI_POLICY.md.
• No published release includes databuddy-init yet. The README says so; update that notice once a compatible release and all its service images are published.

AI-assisted writing and verification with Codex.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
dashboard	Ready	Preview	Sep 17, 2026 8:25am UTC
databuddy-status	Ready	Preview	Sep 17, 2026 8:25am UTC
documentation	Ready	Preview	Sep 17, 2026 8:25am UTC

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: f8f9f7bf-b841-4dcc-9733-07b61be8ff76

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[unkey-deploy]

The latest updates on your projects. Learn more about Unkey Deploy

Name	Status	Preview	Inspect	Updated (UTC)
links (preview)	Ready	Visit Preview	Inspect	Sep 17, 2026 8:24am

[greptile-apps]

Confidence Score: 4/5

The documentation should not merge until the status-app instructions include the required API and public-status URL configuration.

Findings

1.  Status app configuration incomplete ▶

Summary

The PR substantially streamlines the project’s entry-point documentation:

• Replaces the README’s stale badges, speculative feature list, and repeated FAQ with concise hosted, self-hosted, and contributor paths.
• Adds release-aware self-host setup and upgrade instructions, including optional email, Insights, status-page, and DQL guidance.
• Updates contributor setup, validation, branch, review, and AI-assistance guidance.
• Rewrites the AI policy while retaining disclosure, accepted-issue, human-verification, media, and enforcement requirements.

_{Reviews (2) · Last reviewed commit: "docs(docs): enable local development wit..."}

[izadoesdev]

@greptileai review this. Final head 9dccc1a is rebased directly onto staging containing merged #804 and all other self-host prerequisites. All five dependency findings are now addressed in the actual base and have evidence replies. This remains a three-file docs-only diff, including local SELFHOST setup, supported Node releases, and optional status pages. All 14 local links/anchors, repository lint, 33 typecheck tasks, and 29 test tasks pass.