Start here. This page is the entry point for everyone who isn't sure which file to open.
Repositioned 2026-05-28 from "open-source Tavily alternative" to "verifiable web retrieval for AI agents." See
strategy/positioning.mdfor the new one-liner andstrategy/market.mdfor the structural shifts that drove it. ADRs 0009–0013 capture the technical implications.
| For | Read |
|---|---|
| The 30-second pitch | /README.md (repo root) |
| Why we built UnSearch and the problem it solves | strategy/market.md and strategy/positioning.md |
| Who we sell to | strategy/icp.md |
| What's shipped vs. in beta vs. planned | feature-matrix.md |
| Pricing rationale | strategy/pricing.md |
| Where the company is going | roadmap.md and strategy/mrr-plan.md |
| For | Read |
|---|---|
| 60-second MCP install (lead path) | /README.md |
| 5-minute self-host quickstart | quickstart.md |
| Migrate from Tavily (compatibility surface) | migration/from-tavily.md |
| Endpoint contracts | API_REFERENCE.md (or live OpenAPI at /docs) |
| Worked examples per endpoint | API_EXAMPLES.md |
| Citation envelope schema (the wedge primitive) | citation-envelope.md |
| Which AI model runs each request | ai-pipeline.md (and ai-quick-reference.md for a one-pager) |
| Use the Python SDK | /apps/sdk-py/README.md |
| Use the TypeScript SDK | /apps/sdk-ts/README.md |
| Use the LlamaIndex retriever | /apps/sdk-llamaindex/README.md |
| For | Read |
|---|---|
| What's where in the repo | what-is-what.md |
| How the architecture works | architecture.md |
| Cloudflare-specific wiring | cloudflare-architecture.md and /apps/workers/README.md |
| Why we made each major decision | adr/ |
| Repo conventions (testing, commits, naming) | /CONTRIBUTING.md and /CLAUDE.md |
| What shipped recently | /CHANGELOG.md |
| For | Read |
|---|---|
| Deploy to Cloudflare (recommended) | /apps/workers/README.md and deployment/quick-reference.md |
| Deploy to Railway | deployment/railway.md |
| Deploy to DigitalOcean | deployment/digitalocean.md |
| On-call playbooks | operations/RUNBOOKS.md |
| Observability + dashboards | /apps/workers/OBSERVABILITY.md |
| Manage secrets | SECRETS_MANAGEMENT.md and /apps/workers/SECRETS.md |
| Configure env vars | configuration/env-variables.md |
| Set up Stripe billing | BILLING_SETUP.md, configuration/stripe-webhook.md, configuration/webhook-events.md |
| For | Read |
|---|---|
| The ICP definition | strategy/icp.md |
| Jobs-to-be-done framework | strategy/jtbd.md |
| Sales playbook | strategy/sales-playbook.md |
| GTM plan | strategy/gtm.md |
| User journey + activation | strategy/user-journey.md |
| Market + competitor landscape | strategy/market.md |
| Value proposition | strategy/value-prop.md |
- Status taxonomy. Every feature claim uses ✅ shipped / 🔶 in beta / 📋 planned. See ADR-0008.
- Single source of truth.
feature-matrix.mdis canonical for status;CHANGELOG.mdis canonical for what shipped when. Other docs link to these — they don't restate. - Code/doc co-location. Per-package READMEs live next to the code:
apps/*/README.md,apps/workers/README.md. Cross-cutting docs live here. - No emoji in code or commit messages. Emoji are fine in docs only.
- ADRs document non-obvious decisions. Don't write one for routine implementation choices. See
adr/README.md.
If something in these docs is inaccurate, please file an issue at github.com/Rakesh1002/unsearch/issues. Documentation rot is real and we'd rather know.