docs: rework both front doors — README and the book introduction

[jensholdgaard]

What

Both front doors aligned with the current state of the project — the maintainer's "a lot of water has run into the lake" request. Two commits, docs only.

README.md rework. Stale claims fixed: "no packaged release yet" (v0.2.x signed releases + images + Helm exist), "Parquet on local filesystem" (all seams on S3 per RFC 0013/0019), "served querier pending" (RFC 0016 green), WAL checkpointing "still open" (RFC 0008 accepted), "ten RFCs" (33). Benchmark section rewritten with channel-qualified language cross-checked against docs/benchmarks.md: B1/B2 pass on the spec-described baseline, A1 framed as the RFC 0011 diagnostic, and the RFC 0031 comparative program summarized honestly (frozen storage-bytes must-wins ~77×/~22×, needle latency ~75 ms vs 23–24 s, window browses a documented storage-bytes loss, gates asserting on dispatch). New sections: quick start (verified against the clap CLI and the quickstart guide), the MCP surface (tool/resource names verified in source), and the development process incl. the honest fully-AI-assisted-under-human-review stance. Badges: added OpenSSF Best Practices + a ?filter=v* Release badge (the unfiltered form shows the corpus tag), docs badge now points at the live Pages site; all kept badges verified live. DSL example verified against the RFC 0002 test corpus; every relative link script-checked.

docs/introduction.md. The published book's landing page still said "Greenfield. No code has been written yet." Replaced with a short page: the §2 thesis wording, honest pre-release status pointing at Benchmarks, and a map of all five book parts with working links (including a real caught bug: mdbook renders rfcs/README.md as rfcs/index.html without rewriting inline links — the link is written against the rendered form; all 14 internal links verified against book/).

Checks run

mdbook build clean (re-run after rebasing onto today's main); rendered introduction page eyeballed; link targets script-verified. Docs only, no Rust touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WQY9wfrfRggqSpMLH8Xj3Y

Summary by CodeRabbit

• Documentation
  • Updated project positioning, pre-release status, and implementation details.
  • Clarified the architecture, data flow, durability guarantees, and operational model.
  • Expanded guidance for getting started, configuration, authentication, Docker, and Helm deployments.
  • Refreshed benchmark methodology and comparisons, including regression gates.
  • Updated repository documentation, RFC references, and contribution guidance.
  • Added clearer notes about available binaries, container images, and Helm charts.

[coderabbitai]

Warning

Review limit reached

@jensholdgaard, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 14 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 368b2b26-14a9-4216-957e-1e6bbfce26db

📥 Commits

Reviewing files that changed from the base of the PR and between 050a1a0 and 195953c.

📒 Files selected for processing (2)

• README.md
• docs/introduction.md

📝 Walkthrough

Walkthrough

README and introduction documentation are refreshed with updated project positioning, architecture and implementation descriptions, thesis-gate language, navigation links, pre-release status, and development-process details.

Changes

Documentation refresh

Layer / File(s)	Summary
Project positioning and status README.md, docs/introduction.md	Updates the template-mining narrative, pre-release status, project thesis, non-goals, and implementation caveats.
Architecture and implementation narrative README.md	Revises the architecture diagram, durability ordering, implementation inventory, quick-start material, MCP surface, thesis gates, and Grafana Loki comparison.
Documentation navigation and development process README.md, docs/introduction.md	Reorganizes repository and guide links and documents the AI-assisted development process and contribution references.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• jensholdgaard/ourios#181: Updates similar README status, badge, architecture, and WAL ordering descriptions.
• jensholdgaard/ourios#205: Revises documentation status and descriptions of ingest/query paths and acceptance gates.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main documentation rewrite in README.md and docs/introduction.md.
Description check	✅ Passed	The description is detailed and matches the PR goals, but it omits the template's Related and checklist sections.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch readme-rework

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 285: Update the repository-layout fenced code block in README.md to
specify the text language identifier, changing the opening fence to use text
while preserving the ASCII tree contents.
- Around line 221-229: Update the README quick-start example around the OTLP
query to align ingest and query tenancy: configure the example's ingest-side
service.name as checkout, or explicitly state that X-Ourios-Tenant must match
the service.name used during ingestion, while preserving the existing query
example.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b30361b4-f47f-41c6-b358-70475fe3dbe5

📥 Commits

Reviewing files that changed from the base of the PR and between 02d622e and 050a1a0.

📒 Files selected for processing (2)

• README.md
• docs/introduction.md

[Copilot]

Pull request overview

Reworks the project’s two primary entry points (root README.md and the mdBook docs/introduction.md) to reflect the current implementation status, updated benchmarks framing, and the current “front door” navigation for new readers.

Changes:

• Refreshes README status/architecture description, adds quickstart instructions, and documents the MCP surface.
• Updates the README’s “What is implemented” and “How it measures” sections to align with current RFCs and benchmark documentation.
• Replaces the mdBook introduction’s outdated “greenfield” text with an updated thesis/status blurb and a navigational map of the book.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
README.md	Updates badges, status/architecture narrative, implementation/benchmarks summary, adds quickstart + MCP + development-process sections.
docs/introduction.md	Updates the book landing page to reflect current project status and adds organized navigation links into the book.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.