docs: restructure and expand project documentation

[PatrickJS]

Restructure the README and add a durable docs/ handbook. Move long-form content out of README into docs/*.md, add CI/release, getting-started, fixtures-and-schemas, configuration, server-and-viewer, package-api, integrations, concepts, generated-files, and architecture updates. Update examples READMEs and AGENTS.md to reference the new docs and clarify generated output and trusted local code. Rationale: keep root README concise and provide task-focused, linkable docs for contributors and consumers.

Summary by CodeRabbit

• Documentation
  • Reorganized primary README with data-first workflow emphasis; condensed from detailed reference to quick-start format.
  • Added comprehensive documentation suite: getting started guide, configuration reference, concepts, architecture, generated files, fixtures/schemas, server/viewer behavior, integrations, CI/release, and package API.
  • Restructured all example READMEs with consistent "Files To Inspect," "REST Request To Try," and "More Docs" sections for improved navigation.
  • Updated agent guidance for generated types and implementation rules.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR comprehensively restructures jsondb's documentation. The root README shrinks from embedded API and behavioral details to a lean data-first workflow with links to modular docs. A new docs/ system provides topic-specific pages covering concepts, configuration, fixtures, generated files, getting started, integrations, package APIs, server/viewer capabilities, architecture, and CI/release processes. All example READMEs adopt a consistent structure.

Changes

Documentation Restructure & Modularization

Layer / File(s)	Summary
Root README & Documentation Index README.md, docs/README.md	Root README rewritten to compact data-first workflow with quick summary, five-minute start, and operational contract table; points readers to modular docs. New docs/README.md provides TOC and routing to task-specific documentation pages with explicit rules for where content should live.
Foundational Concepts & Architecture docs/concepts.md, docs/architecture.md	New docs/concepts.md defines jsondb product boundary, data-first/schema-first/mixed modes, mirror/source semantics, and diagnostics workflow. Updated docs/architecture.md adds "Public Surfaces" table mapping CLI, runtime API, config API, HTTP client, REST server, GraphQL, viewer, Vite, and optional Hono/SQLite integrations to source entry points.
Configuration & Data Building docs/configuration.md, docs/fixtures-and-schemas.md, docs/generated-files.md	New docs/configuration.md documents defineConfig with Config Map table and dedicated sections for dbDir, mirror/source modes, schema strictness, mock delay, server options, and database forks. New docs/fixtures-and-schemas.md covers fixture discovery, JSON/JSONC/CSV formats, schema inference, schema file usage, JavaScript schema modules, source-reader pipeline with custom reader examples, and nested folder organization with resource naming strategies. New docs/generated-files.md describes default outputs under .jsondb/, runtime state vs committed sources, generated IDs, TypeScript type output with types.commitOutFile, schema manifest output, and cleanup rules.
Getting Started & Runtime APIs docs/getting-started.md, docs/package-api.md, docs/server-and-viewer.md	New docs/getting-started.md walks through installation, fixture creation, sync, serving, REST usage, schema authoring, validation, and example execution. New docs/package-api.md documents CLI commands, runtime API (openJsonFixtureDb, collections, singleton documents), HTTP client batching/deduping, fork usage, package export subpaths, and repo examples launcher. New docs/server-and-viewer.md covers jsondb serve, viewer access, REST routes and examples, output formats, relation expansion, REST batching semantics and error shaping, GraphQL boundary and limitations, fixture watch behavior, and fork-scoped routes.
Integrations & Release Operations docs/integrations.md, docs/ci-and-release.md	New docs/integrations.md documents optional Vite dev server plugin with route scoping and watch-ignore settings, Hono route registration with lifecycle hooks and short-circuit behavior, jsondb generate hono starter generation with schema error/warning constraints, and optional runtime Hono/SQLite exports. New docs/ci-and-release.md specifies Node version support, verification/smoke commands, npm pack allowlist expectations, generated runtime output rules, docs link-check commands, and release hygiene bullet points.
Agent Guidance & Example Consistency AGENTS.md, examples/*/README.md	Updated AGENTS.md to expand "committed generated types" examples across multiple projects and clarify that .schema.mjs, jsondb.config.mjs, and schema manifest hooks are trusted local code. All eight example READMEs (advanced, basic, CSV, data-first, diagnostics, hono-auth, relations, rest-client, schema-first, schema-manifest) restructured with consistent "Files To Inspect" sections, "REST Request To Try" sections with terminal workflow guidance, and "More Docs" sections linking to relevant documentation pages.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

In a hop and a bound, the docs are rebound,
From one big README to pages profound.
Schema and config in chapters so clear,
Each example now shines with consistency dear! 🐰📚

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: restructure and expand project documentation' directly and accurately reflects the main change—reorganizing and expanding documentation by moving content from README to dedicated docs pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-cleanup

---

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 and usage tips.}