docs: User Guide, restructure, add versioning

[cassidyjames]

Pass of the docs to more clearly separate into a user guide and development guide, similar to the Coop docs.

• Updated "Welcome" page similar to the Coop one, introducing the subsections
• Splits "UI" into a user guide with a new landing page, and three subsections (Investigate, Manage, Operate) to match the UI
• Updated development tools page for clarity
• Consolidated two troubleshooting sections into the one page
• Minor copy/style improvements throughout
• Versioned the docs build in CI to fix Versioned docs #351

Summary by CodeRabbit

• Documentation

  • Restructured the documentation into clearer Welcome, User Guide, and Development Guide sections.
  • Added new guides for Investigate, Query Syntax, Labels, Manage, and Operate, plus an expanded “Solve common issues” troubleshooting hub.
  • Updated the rules introduction and added supporting cross-links; removed the older UI guide.
  • Refreshed the documentation styling and typography for a more consistent look.

• Build & Release

  • Updated the documentation site build and deployment process for more reliable updates.

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces the GitHub Pages OIDC deployment workflow with a versioned gh-pages branch push that places builds under latest or a numeric tag subdirectory. Reconfigures book.toml to build from the repository root. Restructures the documentation into a User Guide (Investigate, Manage, Operate pages) and a Development Guide, removing UI.md and expanding the troubleshooting page.

Changes

Versioned Docs Deployment and Restructure

Layer / File(s)	Summary
Workflow triggers, permissions, and mdBook config .github/workflows/mdbook.yml, docs/book.toml, docs/docs.md	Switches workflow permissions to contents: write, adds workflow_dispatch with an optional ref input, updates push filters to docs/** and numeric tag patterns, and reconfigures book.toml to use . as source root, ./book as output, /osprey/ as site URL, and docs/{path} in the edit template.
Workflow build cache and gh-pages push logic .github/workflows/mdbook.yml	Adds deploy-path computation selecting latest or a sanitized version subdirectory, replaces cargo install with an actions-cache-backed binary download for a pinned MDBOOK_VERSION, and replaces Pages artifact upload with a direct gh-pages branch clone/populate/index-regen/push flow.
TOC, landing page, fonts, and navigation restructure docs/SUMMARY.md, docs/README.md, docs/UI.md, docs/theme/fonts/fonts.css	Reorganizes the mdBook TOC into User Guide and Development Guide sections with updated paths, rewrites the docs landing page to Welcome/Contributing/Get help layout, removes UI.md (281 lines), and introduces a custom stylesheet loading Funnel Display/Funnel Sans from Google Fonts with heading and link styles.
New User Guide pages docs/user/README.md, docs/user/investigate/README.md, docs/user/investigate/labels.md, docs/user/investigate/query-syntax.md, docs/user/manage.md, docs/user/operate.md	Adds a User Guide overview and pages for Investigate (Query workspace, Labels, SML query syntax with UDF and DidAddLabel coverage), Manage (Rules Visualizer, UDF Registry, Features, Rules), and Operate (Bulk Actions job creation/monitoring and Bulk Job History).
Development Guide updates and rules cross-links docs/development/README.md, docs/development/ide.md, docs/development/troubleshooting.md, docs/rules.md	Removes the Troubleshooting section from development/README.md and expands it into a standalone troubleshooting.md with new Druid/Kafka/UI entries. Updates IDE setup heading in ide.md. Updates the rules cross-link in development/README.md and adds a Labels user guide link in rules.md.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• roostorg/osprey#350: Both PRs modify .github/workflows/mdbook.yml for workflow permissions and checkout credential configuration.

Suggested reviewers

• ayubun
• EXBreder
• vinaysrao1
• haileyok

🚥 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 PR title accurately summarizes the main changes: documentation restructuring into user and development guides, and implementation of versioning for the CI build system.
Linked Issues check	✅ Passed	The PR implements versioned documentation as requested in issue #351, including workflow changes for tag-based deployment and mdbook configuration updates to support versioning.
Out of Scope Changes check	✅ Passed	All changes align with stated objectives: documentation restructuring (user/development guides), versioning implementation (workflow and build config), and documentation content updates are all within scope.
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.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cassidyjames/docs

---

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

[julietshen]

LGTM, thank you!

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/theme/fonts/fonts.css (1)

1-1: 💤 Low value

Apply stylelint-preferred import notation.

The import-notation rule prefers a quoted string instead of the url() function syntax. Both are functionally equivalent; this is purely a style preference.

✨ Proposed style fix

-@import url('https://fonts.googleapis.com/css2?family=Funnel+Display:wght@300..800&family=Funnel+Sans:ital,wght@0,300..800;1,300..800&display=swap');
+@import 'https://fonts.googleapis.com/css2?family=Funnel+Display:wght@300..800&family=Funnel+Sans:ital,wght@0,300..800;1,300..800&display=swap';

🤖 Prompt for 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.

In `@docs/theme/fonts/fonts.css` at line 1, The `@import` statement in fonts.css
currently uses the url() function syntax, but stylelint prefers quoted string
notation for consistency. Replace the `@import` url('...') syntax with `@import`
'...' by removing the url() function wrapper and keeping just the quoted string
with the Google Fonts URL.

🤖 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 @.github/workflows/mdbook.yml:
- Around line 90-115: The mdBook workflow builds with a static site-url but
deploys to versioned subdirectories, causing asset and 404 paths to be
incorrect. Before the mdBook build step (which occurs before the deployment
section shown), set the MDBOOK_OUTPUT_HTML_SITE_URL environment variable
dynamically by constructing it from the DEPLOY_PATH output. For example, set
MDBOOK_OUTPUT_HTML_SITE_URL to "/osprey/${DEPLOY_PATH}" or similar, ensuring the
site-url matches the actual deployment path. This environment variable will
override the static site-url in book.toml during the build, so the generated
404.html and asset paths will be correct for each versioned deployment.

In `@docs/theme/fonts/fonts.css`:
- Around line 17-19: The fonts.css stylesheet exists at
docs/theme/fonts/fonts.css but is not integrated into the documentation build.
Add the additional-css configuration to the [output.html] section of
docs/book.toml to reference the stylesheet. Include the relative path
"theme/fonts/fonts.css" in the additional-css array so that custom font and link
styles (such as the .content a text-decoration rule) are applied when the
documentation is built.

---

Nitpick comments:
In `@docs/theme/fonts/fonts.css`:
- Line 1: The `@import` statement in fonts.css currently uses the url() function
syntax, but stylelint prefers quoted string notation for consistency. Replace
the `@import` url('...') syntax with `@import` '...' by removing the url() function
wrapper and keeping just the quoted string with the Google Fonts URL.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1f2fabe9-9e9a-413c-bb48-78f8a72b56ab

📥 Commits

Reviewing files that changed from the base of the PR and between eac8738 and c393929.

📒 Files selected for processing (19)

• .github/workflows/mdbook.yml
• docs/README.md
• docs/SUMMARY.md
• docs/UI.md
• docs/book.toml
• docs/development/README.md
• docs/development/ide.md
• docs/development/tools.md
• docs/development/troubleshooting.md
• docs/docs.md
• docs/research-personas.md
• docs/rules.md
• docs/theme/fonts/fonts.css
• docs/user/README.md
• docs/user/investigate/README.md
• docs/user/investigate/labels.md
• docs/user/investigate/query-syntax.md
• docs/user/manage.md
• docs/user/operate.md

💤 Files with no reviewable changes (1)

• docs/UI.md

✅ Files skipped from review due to trivial changes (14)

• docs/user/README.md
• docs/user/investigate/labels.md
• docs/README.md
• docs/docs.md
• docs/development/troubleshooting.md
• docs/user/manage.md
• docs/development/tools.md
• docs/user/investigate/README.md
• docs/rules.md
• docs/user/investigate/query-syntax.md
• docs/development/ide.md
• docs/user/operate.md
• docs/SUMMARY.md
• docs/development/README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/book.toml