Skip to content

docs: reposition to verifiable web retrieval for AI agents - #6

Merged
Rakesh1002 merged 1 commit into
mainfrom
Rakesh1002/repo-description-check
May 28, 2026
Merged

docs: reposition to verifiable web retrieval for AI agents#6
Rakesh1002 merged 1 commit into
mainfrom
Rakesh1002/repo-description-check

Conversation

@Rakesh1002

Copy link
Copy Markdown
Owner

Summary

Repositions UnSearch from "open-source Tavily alternative, 10× cheaper" to verifiable web retrieval for AI agents — every result signed, hashed, snapshotted, and replayable months later. Driven by Q1–Q2 2026 market shifts that made the prior wedge unsellable to indie devs (Anthropic native web_search, Codex CLI first-party search, MCP search vendor saturation, Tavily→Nebius, Brave free-tier kill, Exa price hike) and three regulatory/litigation forces that opened a sharper wedge for regulated AI (Q1 2026 $145K US court sanctions for hallucinated legal citations, Harvey AI 1-in-6 hallucination rate at $8B valuation, EU AI Act Article 12 enforcement August 2026).

What changed (30 files, +2241 / -1859)

  • Strategy docs rewritten (11): docs/strategy/{positioning,icp,jtbd,value-prop,market,user-journey,pricing,gtm,sales-playbook,mrr-plan,README}.md. New personas: Priya (ICP-1, regulated-AI startup eng lead), David (ICP-2, regulated-company AI platform director), Anika (ICP-3, citation-integrity research/newsroom). Maya (indie dev) retired — eaten by native LLM search.
  • Top-level rewrites (5): README.md, docs/README.md, docs/roadmap.md, docs/introduction.mdx, apps/web/app/page.tsx landing (new ProblemStrip with $145K / 1-in-6 / 40-60% / Aug 2026 stats; MCP-install hero; new pricing tiers including $24K self-host v1).
  • New ADRs (5): 0009-verifiable-retrieval-as-product-surface, 0010-cloudflare-containers-as-origin-runtime, 0011-wacz-aligned-signed-envelope, 0012-mcp-first-distribution, 0013-icp-shift-to-regulated-ai. ADR-0003 (Tavily-compat) downgraded to compatibility surface.
  • New spec: docs/citation-envelope.md — wire format (HMAC v1, WACZ-Auth-aligned, PKI v2 path).
  • Feature matrix rewritten around verifiable retrieval; comparison columns now include Anthropic native web_search, Codex CLI search, Webrecorder.
  • Migration housekeeping: docs/migration/from-tavily.md keeps as compatibility surface with a banner; SDK package name fixed (@unsearch/sdk, class UnSearch). docs/mint.json dropped 20+ dead navigation references (features/*, api-reference/auth/*, etc.) and added new docs + ADRs.
  • Stale cleanup:
    • firecrawl/ — orphaned git submodule (no .gitmodules), empty in worktree, git rm --cached.
    • docs/getting-started/next-steps.md — referenced /root/unsearch/... paths and wrong Stripe pricing ($29/10K vs actual $19/25K).
    • quickstart.sh banner — "Tavily Alternative" → "Verifiable Retrieval for AI Agents".

What this PR does NOT change

  • Backend code, API endpoints, Workers, container deploy config — those are Week 1–3 work per the approved rebuild plan at ~/.claude/plans/app-unsearch-dev-is-not-deployed-luminous-wilkinson.md.
  • nginx/, monitoring/, ecosystem.config.js, scripts/setup-stripe.*, docs/architecture.md, docs/cloudflare-architecture.md, docs/ai-pipeline.md — all still load-bearing for self-host / operations.
  • A repo-structure audit (app/ vs apps/backend/ duplication, monitoring/ vs apps/backend/monitoring/, etc.) is the next session — see follow-up.

Test plan

  • Skim README.md and apps/web/app/page.tsx for tone consistency.
  • Verify ADR cross-references resolve (00090010001100120013).
  • Confirm docs/strategy/README.md reading order links land on the right files.
  • pnpm --filter @unsearch/web build succeeds on the new landing copy.
  • docs/mint.json validates against the Mintlify schema.
  • GitHub repo description still reads as the verifiability-first line (set in an earlier session).

Strategy reposition driven by three Q1-Q2 2026 structural shifts that
killed the "cheaper Tavily" wedge for indie devs (Anthropic native
web_search, Codex CLI first-party search, MCP search vendor saturation)
and three regulatory/litigation forces that opened a sharper wedge for
regulated AI (Q1 2026 $145K US court sanctions for hallucinated legal
citations, Harvey AI 1-in-6 hallucination rate at $8B, EU AI Act
Article 12 enforcement Aug 2026).

Strategy docs rewritten around verifiable retrieval as the product
surface and regulated-AI buyers (legal, medical, finance, insurance,
research) as the new ICP. README, feature-matrix, roadmap, landing
page, and Mintlify entry follow the same reposition.

Five new ADRs (0009-0013) capture the decisions: verifiable retrieval
as product surface, Cloudflare Containers GA as origin runtime, WACZ-
aligned signed envelope format, MCP-first distribution, ICP shift to
regulated AI. New citation-envelope.md specifies the wire format.

Stale content removed: empty firecrawl/ orphaned submodule (no
.gitmodules), docs/getting-started/next-steps.md (references
/root/unsearch/ paths and wrong Stripe pricing from a 2024 setup).

Approved 3-week rebuild plan lives at
~/.claude/plans/app-unsearch-dev-is-not-deployed-luminous-wilkinson.md
@Rakesh1002
Rakesh1002 merged commit c5903b6 into main May 28, 2026
3 of 9 checks passed
@Rakesh1002
Rakesh1002 deleted the Rakesh1002/repo-description-check branch May 28, 2026 14:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant