docs: center the core search library

[jgpruitt]

Summary

• reframe the README and docs around the published searchgres core library
• add conceptual guides for retrieval, record modeling, and architecture boundaries
• add RAG, comparison, and benchmark-evidence documentation
• position the server, CLI, MCP server, and Compose stack as optional applications
• add runnable examples for basic, document, temporal, RAG, and worker workflows
• type-check examples and validate relative Markdown links in the normal checks

Validation

• ./bun run check
• ./bun x tsc -p examples/tsconfig.json
• ./bun test scripts/docs-links.test.ts

[Copilot]

🟡 Changes recommended

The new Markdown link validation test currently only validates the root README because its directory traversal never includes discovered .md files.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR recenters the repository documentation around the published searchgres core TypeScript library, adding conceptual guides and runnable examples while wiring docs link validation and example type-checking into the normal CI checks.

Changes:

• Rewrites the top-level README and docs landing page to position the core library as the primary product, with server/CLI/MCP/Compose as optional layers.
• Adds new conceptual documentation (how search works, record modeling, architecture boundaries), plus RAG/comparison/benchmarks docs.
• Adds runnable TypeScript examples and updates checks to type-check them and validate relative Markdown links.

File summaries

File	Description
scripts/docs-links.test.ts	Adds a test intended to validate relative Markdown links across public docs/examples.
README.md	Reframes the project around the core library; adds “why/how” sections and updated navigation.
package.json	Extends typecheck to include tsc -p examples/tsconfig.json.
examples/tsconfig.json	Adds a TS config for type-checking example programs.
examples/README.md	Adds an examples index page and prerequisites/usage notes.
examples/basic-search/README.md	Documents the basic search runnable example.
examples/basic-search/index.ts	Implements a basic create/ingest/embed/search workflow example.
examples/document-search/README.md	Documents the document modeling runnable example.
examples/document-search/index.ts	Implements raw-vs-derived record modeling example.
examples/rag-retriever/README.md	Documents the RAG retriever runnable example.
examples/rag-retriever/index.ts	Implements a scoped hybrid retriever and context formatter example.
examples/temporal-search/README.md	Documents the temporal search runnable example.
examples/temporal-search/index.ts	Implements temporal record modeling and temporal filters example.
examples/worker/README.md	Documents running a separate embedding worker process.
examples/worker/index.ts	Implements a long-lived embedding worker with graceful shutdown.
docs/README.md	Updates docs landing page structure and navigation for the core library focus.
docs/getting-started.md	Updates getting started to emphasize core-library flow and next steps.
docs/installation.md	Reworks installation guidance around the library; moves Compose/apps into optional sections.
docs/guides/indexes.md	Adds architectural boundary references and clarifies index shape/ownership.
docs/guides/ingest.md	Expands ingest guidance (indexing existing data, raw vs derived record patterns).
docs/guides/search.md	Links to the new “How search works” concept doc and updates next-step navigation.
docs/guides/rag.md	Adds a new guide describing how to build a RAG retriever using the library.
docs/guides/production.md	Expands access-control guidance with concrete filter composition examples.
docs/concepts/how-search-works.md	Adds a conceptual explanation of retrieval modes, RRF, candidate windows, and filters.
docs/concepts/record-model.md	Adds a conceptual guide for record fields and modeling choices.
docs/concepts/architecture.md	Adds an explicit “responsibility boundary” and architecture rationale doc.
docs/comparison.md	Adds a comparison doc positioning searchgres against alternatives.
docs/benchmarks/README.md	Adds benchmark evidence documentation and interpretation guidance.

Review details

• Files reviewed: 28/28 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.