docs: document embedding workflow

[alltheseas]

Summary

- add a getting-started section that covers cloning, building libnostrdb, and linking requirements
- provide lifecycle examples for ingestion, querying, fulltext search, data access, and subscriptions
- document event-building helpers and how to regenerate the Swift/Rust/C bindings

## Testing
- not required (documentation-only change)

Summary by CodeRabbit

• Documentation
  • Significantly expanded README with Getting Started (build & usage), Configuration reference, Event Ingestion workflow, Structured Queries examples, Fulltext Search setup, Data reading helpers, Event creation & signing guide, Subscriptions and notification behavior, Language bindings/codegen workflow, CLI examples, and Development/testing instructions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Expanded the repository README with detailed getting-started instructions, a minimal C example, configuration reference, ingestion and query workflows, fulltext search setup, data-reading and event-creation examples, subscriptions, language bindings/codegen notes, CLI usage, and development/testing guidance.

Changes

Cohort / File(s)	Summary
Documentation Expansion README.md	Added ~236 lines: comprehensive Getting Started (Embedding) steps, Minimal C example, ndb_config reference, Event Ingestion and Structured Queries workflows, Fulltext Search configuration, Reading Data examples, Event Creation and signing, Subscriptions, Language Bindings & codegen, CLI examples, and Development/testing notes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through the docs to tidy the trail,
Added examples and steps so no one will fail,
C snippets and queries, a nibble of code,
Subscriptions and search on the information road,
Hop on—these README carrots will speed up your build! 🥕🐇

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: document embedding workflow' directly aligns with the main change—a comprehensive README expansion documenting the embedding workflow including getting started, event ingestion, queries, fulltext search, and other related features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

---

🧹 Recent nitpick comments

README.md (3)

23-28: Add language specifiers to shell code blocks.

The shell code blocks lack language identifiers, which prevents proper syntax highlighting. Add bash or sh to improve readability.

📝 Proposed improvements

-```
+```bash
 git clone https://github.com/damus-io/nostrdb.git
 cd nostrdb
 git submodule update --init --recursive
 make lib ndb

```diff
-```
+```bash
 cc app.c libnostrdb.a \
   -Isrc -Ideps/lmdb -Ideps/secp256k1/include \
   -llmdb -lsecp256k1 -lpthread -lzstd

```diff
-```
+```bash
 mkdir -p /var/lib/nostrdb

</details>


Also applies to: 34-38, 43-45

---

`226-226`: **Consider clarifying the nsec placeholder.**

Similar to the clarification added on line 67, the `"nsec1..."` placeholder could benefit from a brief comment explaining that users need a valid nostr secret key (nsec) for signing.



<details>
<summary>📝 Suggested addition</summary>

```diff
+// Replace "nsec1..." with a valid nostr secret key
 struct ndb_keypair keypair;
 ndb_decode_key("nsec1...", &keypair);
 ndb_builder_finalize(&builder, &note, &keypair);

---

249-249: Hyphenate compound adjective.

"Higher level" should be hyphenated when used as a compound adjective modifying "bindings."

📝 Suggested fix

-`make bindings` regenerates higher level bindings using `flatc` and `flatcc`:
+`make bindings` regenerates higher-level bindings using `flatc` and `flatcc`:

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5a0f6d1 and b15b285.

📒 Files selected for processing (1)

• README.md

🧰 Additional context used

🪛 LanguageTool

README.md

[grammar] ~249-~249: Use a hyphen to join words.
Context: ...ings make bindings regenerates higher level bindings using flatc and `flatcc...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

README.md

23-23: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

34-34: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

43-43: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (1)

README.md (1)

67-73: Good addition of the clarifying comment!

The warning note properly addresses the previous review concern by clearly explaining that placeholder values must be replaced with valid cryptographic data. Users will now understand the requirements before attempting to use this example.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 68-73: The example ldjson string uses placeholder values ("...")
for id, pubkey, and sig which will cause ndb_process_events(db, ldjson,
strlen(ldjson)) to fail; update the const char *ldjson used in the example to
either (a) contain valid test nostr event fields (id and pubkey as 32-byte hex,
sig as 64-byte hex) or (b) add a clear comment immediately above the ldjson
declaration explaining that id/pubkey must be 32-byte hex and sig must be
64-byte hex and that placeholders must be replaced with valid cryptographic
values for ndb_process_events to succeed. Ensure the note references the ldjson
variable and the ndb_process_events call so readers know why the change is
required.

🧹 Nitpick comments (3)

README.md (3)

23-27: Add language specifiers to code blocks for syntax highlighting.

The code blocks lack language identifiers, which prevents proper syntax highlighting and violates markdown best practices.

📝 Proposed fix

-```
+```bash
 git clone https://github.com/damus-io/nostrdb.git
 cd nostrdb
 git submodule update --init --recursive
 make lib ndb

```diff
-```
+```bash
 cc app.c libnostrdb.a \
   -Isrc -Ideps/lmdb -Ideps/secp256k1/include \
   deps/lmdb/liblmdb.a deps/secp256k1/.libs/libsecp256k1.a \
   -lpthread -lzstd

```diff
-```
+```bash
 mkdir -p /var/lib/nostrdb

</details>


Also applies to: 34-39, 44-46

---

`226-226`: **Clarify placeholder nsec key or provide test data.**

The example uses `"nsec1..."` as a placeholder for `ndb_decode_key`, which won't work in practice. Consider adding a comment noting this is a placeholder, or provide a valid test nsec key for users to try the example.



<details>
<summary>📝 Suggested clarification</summary>

```diff
 struct ndb_keypair keypair;
-ndb_decode_key("nsec1...", &keypair);
+// Replace with your actual nsec key
+ndb_decode_key("nsec1...", &keypair);

---

249-249: Fix hyphenation of compound modifier.

The phrase "higher level" should be hyphenated as "higher-level" when used as a compound adjective modifying "bindings."

📝 Proposed fix

-`make bindings` regenerates higher level bindings using `flatc` and `flatcc`:
+`make bindings` regenerates higher-level bindings using `flatc` and `flatcc`:

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9464456 and 5a0f6d1.

📒 Files selected for processing (1)

• README.md

🧰 Additional context used

🪛 LanguageTool

README.md

[grammar] ~249-~249: Use a hyphen to join words.
Context: ...ings make bindings regenerates higher level bindings using flatc and `flatcc...

(QB_NEW_EN_HYPHEN)

🪛 markdownlint-cli2 (0.18.1)

README.md

23-23: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

34-34: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

44-44: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (7)

README.md (7)

108-121: Excellent configuration documentation.

This section provides comprehensive coverage of all major configuration options with clear descriptions of their purposes. Well-organized and helpful for users.

---

122-133: Clear and comprehensive ingestion documentation.

The section effectively explains the different ingestion functions, their use cases, and important considerations like verification bypass and ingest filters.

---

135-159: Well-structured query documentation with clear examples.

The explanation of the transaction model and filter construction is clear, and the code example effectively demonstrates the API. The note about result validity is an important detail.

---

161-167: Concise and informative fulltext search documentation.

The section covers the essential aspects of fulltext search including configuration and the ability to combine with structured queries.

---

169-204: Comprehensive data access documentation with practical examples.

The section provides a thorough list of accessor functions and includes a complete, working code example that demonstrates block iteration and proper memory management. The optimization tip about NDB_FLAG_NO_NOTE_BLOCKS is valuable.

---

240-245: Clear subscription mechanism overview.

The section concisely explains the subscription model and the two notification delivery approaches, providing enough information for users to understand the feature.

---

301-304: Good development guidance.

The section provides essential information for contributors, including test execution and the rationale for vendored dependencies.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}