Add examples, docs, and CLI help/UI improvements

[PatrickJS]

Add a comprehensive examples catalog, architecture docs, and improved CLI help and example serving. Introduces docs/architecture.md, expands README and AGENTS.md with cross-references and contribution paths, and adds many example folders (basic, advanced, csv, data-first, diagnostics, relations, rest-client, schema-first, schema-manifest) including example metadata, READMEs, config files (migrated to defineConfig and dbDir), seeds and schema fixtures, and generated schema/types for the schema-manifest example. Update scripts/serve-examples.js to read example.json metadata, render titles, descriptions and tags, and include helper functions for formatting; adjust package.json globs to include example metadata and example src. Add CLI arg helper isHelpRequested and wire help handling into several commands (doctor, generate, schema, serve, types) plus small related changes. Overall polish for discoverability, example UX, and developer workflows.

Summary by CodeRabbit

• New Features

  • Added three new example projects: Relations (demonstrating one-to-one relationships), REST Client (batched API requests), and Schema Manifest (UI customization).
  • Added --help support across CLI subcommands for clearer usage guidance.
  • Enhanced example discovery with metadata and learning paths.

• Documentation

  • Restructured all example READMEs with "What This Teaches," "Files To Inspect," and "Expected Result" sections.
  • Added architecture documentation and codebase guidance in AGENTS.md and docs/architecture.md.
  • Added "Which Example Should I Start With?" learning-path table in main README.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR restructures the jsondb examples ecosystem by adding three new complete examples (relations, rest-client, schema-manifest), standardizing all nine example configs to use defineConfig, overhauling example documentation into a consistent format, implementing a CLI help system across subcommands, adding architecture documentation, and enabling metadata-driven example discovery in the UI.

Changes

Documentation, Examples, and CLI Enhancements

Layer / File(s)	Summary
Documentation and Architecture Foundation docs/architecture.md, AGENTS.md, README.md	New architecture doc outlines main flow and boundaries; AGENTS and README add navigation pointers (edit paths, example start guide, codebase map link).
Example Metadata Discovery Infrastructure scripts/serve-examples.js	Reads example.json metadata (title, description, tags) for each example; enriches examples index UI and /examples.json with searchable metadata via new helpers (readExampleMetadata, renderTags, titleFromName).
Example Configuration Standardization examples/*/jsondb.config.mjs (8 files)	Migrates basic, advanced, csv, data-first, diagnostics, schema-first configs from plain object to defineConfig wrapper; updates sourceDir to dbDir and adds @ts-check.
Documentation and Metadata for Existing Examples examples/*/README.md, examples/*/example.json (6 examples)	Restructures 6 existing example READMEs into consistent sections ("What This Teaches", "Files To Inspect", "Run It", "Expected Result", "REST Request To Try", "Cleanup"); adds example.json metadata files with title, description, tags.
Relations Example: Schema Links and Expansion examples/relations/README.md, examples/relations/db/users.schema.jsonc, examples/relations/db/posts.schema.jsonc, examples/relations/jsondb.config.mjs, examples/relations/example.json	New example demonstrating to-one relation metadata and REST expand/select; users and posts schemas with relation links (authorId → users.id); complete documentation and configuration.
REST Client Example: Batched Requests examples/rest-client/README.md, examples/rest-client/db/users.schema.jsonc, examples/rest-client/db/settings.json, examples/rest-client/jsondb.config.mjs, examples/rest-client/src/client-demo.mjs, examples/rest-client/example.json	New example showing REST consumer script with direct and batched API calls; users and settings data; client-demo script that reads JSONDB_URL env var and executes batched requests; complete documentation.
Schema Manifest Example: UI Customization examples/schema-manifest/README.md, examples/schema-manifest/db/users.schema.jsonc, examples/schema-manifest/db/projects.schema.jsonc, examples/schema-manifest/jsondb.config.mjs, examples/schema-manifest/example.json	New example demonstrating UI schema manifest customization via schemaManifest.customizeField; overrides component types for selected fields (segmented-control for projects.status, markdown for users.bio); complete documentation and hook implementation.
CLI Help System: Core Infrastructure src/cli/args.js, src/cli/output.js	Adds isHelpRequested utility; exports five help printers (printTypesHelp, printSchemaHelp, printDoctorHelp, printServeHelp, printGenerateHelp) that display usage text for each jsondb subcommand.
CLI Help System: Command Integration src/cli/commands/doctor.js, src/cli/commands/generate.js, src/cli/commands/schema.js, src/cli/commands/serve.js, src/cli/commands/types.js	Integrates help detection into all five subcommands; each checks isHelpRequested and prints focused help before executing logic, enabling --help to display usage without side effects.
Publishing, Testing, and Package Updates package.json, test/cli/cli.test.js, test/examples/examples.test.js	Updates package.json to publish example metadata and docs; adds CLI help test verifying --help prints usage for all subcommands; expands examples test to validate new examples, metadata assertions, and schema UI component customization.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐰 A field of examples now blooms with guides so clear,
Relations expand, CLI helps appear—
From schema manifest hooks to REST client streams,
The docs and the discovery fulfill all dreams!
🌟

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: addition of examples, documentation, and CLI improvements, which aligns with the core objectives and file modifications throughout the PR.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/onboarding-examples-polish

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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.}