docs: create dedicated markdown documentation and explicit navigation tree

[Vaishnav88sk]

📖 Description

Resolves #41.

This PR establishes the dedicated, standalone documentation pages for the Claritty website. It completely extracts the core instructional content out of the root README.md and migrates it into a beautifully styled, Docusaurus-native format inside website/docs/.

The root repository README.md has been left completely untouched to preserve its original state, ensuring a clean separation of concerns.

💡 What Changed

• Dedicated Markdown Pages: Created four highly-readable documentation pages:
  • intro.md: High-level AI-SRE introduction and Zero-Trust architecture overview.
  • installation.md: Copy-pasteable setup guides for both clarctl and the SRE Agent.
  • architecture.md: Deep dive into the Hub-Spoke model and the 6-stage AI pipeline.
  • cli-usage.md: Interactive terminal remediation walkthrough.
• Docusaurus Admonitions: Fully implemented native Docusaurus UI alerts (:::warning, :::info, :::tip) replacing standard GitHub blockquotes to create beautiful UI popouts for critical instructions.
• Explicit Navigation Tree: Overrode the Docusaurus autogenerated sidebar in sidebars.ts to build a professional, categorized navigation menu (Getting Started, Core Concepts, Reference).
• Global Issue Redirect: Overrode the default editUrl logic in docusaurus.config.ts via a custom javascript function. Clicking "Edit this page" on any doc will now strictly redirect the user to the GitHub Issues page rather than the file editor.

✅ Checklist

• Documentation builds successfully locally without errors.
• "Edit this page" correctly routes directly to the repository issues page.
• UI Alerts render properly.

Summary by CodeRabbit

Release Notes

• Documentation
  • Added comprehensive architecture documentation detailing the decentralized multi-agent system design and 6-stage AI pipeline
  • Added CLI usage guide covering scan operations and interactive remediation workflows
  • Added installation instructions for CLI and in-cluster deployment options
  • Enhanced introduction with key features and safety safeguards
  • Reorganized documentation structure with improved navigation categories

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (3)

• docs/images/claritty_favicon.ico is excluded by !**/*.ico
• docs/images/claritty_favicon.png is excluded by !**/*.png
• website/static/img/favicon.ico is excluded by !**/*.ico

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 12eb7bbd-ee4f-445a-a65c-56a492693d5f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds four new Docusaurus documentation pages (intro.md, installation.md, architecture.md, cli-usage.md) covering Claritty's product overview, installation paths, hub-and-spoke architecture, 6-stage AI pipeline, and CLI remediation flow. Updates sidebars.ts to use an explicit category-based navigation and changes docusaurus.config.ts editUrl from a static string to a callback function.

Changes

Claritty Documentation Site Content & Navigation

Layer / File(s)	Summary
Product intro and architecture docs website/docs/intro.md, website/docs/architecture.md	intro.md adds full product overview, zero-trust design, two operation modes, and key-features list. architecture.md documents hub-and-spoke topology with stateless in-cluster agents and enumerates the 6-stage AI pipeline (Triage → Commander) with safety/allowlist guarantees.
Installation guide website/docs/installation.md	Adds two-path installation doc: Option 1 covers Clarctl CLI binary download and scan; Option 2 covers Hub startup via Docker Compose, RBAC deployment, agent config (with placeholder warning), and agent daemon deployment.
CLI usage and remediation flow website/docs/cli-usage.md	Documents clarctl version/clarctl scan commands, local 6-stage pipeline invocation with lipgloss/bubbletea output, and the Commander Agent's interactive per-command approval prompt with y/dry/n semantics and allowlist warning.
Sidebar navigation and editUrl config website/sidebars.ts, website/docusaurus.config.ts	sidebars.ts replaces autogenerated config with explicit Getting Started, Core Concepts, and Reference categories referencing the new doc IDs. docusaurus.config.ts changes editUrl from a static string to a callback returning the GitHub issues URL without trailing slash.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• [Docs] Create Dedicated Markdown Documentation #41: This PR directly fulfills the issue's scope—creating intro.md, installation.md, architecture.md, and cli-usage.md inside website/docs/, and constructing an explicit categorized sidebar in sidebars.ts, without touching the root README.md.
• [Feature] Build the Official Claritty Documentation Website #24: The PR implements the Docusaurus documentation content population described as part of the site setup initiative.

Possibly related PRs

• Vaishnav88sk/claritty#44: Both PRs modify website/docusaurus.config.ts and website/sidebars.ts as part of the Docusaurus site setup, with this PR building directly on the site initialization established there.

Suggested labels

documentation, enhancement

Poem

🐇 Hoppity-hop, the docs are here at last,
Six pipeline stages documented fast!
Hub-and-spoke drawn with stateless care,
clarctl scan runs with lipgloss flair.
The rabbit approves — y to deploy,
Clean markdown pages, oh what a joy! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	❓ Inconclusive	The editUrl configuration change in docusaurus.config.ts redirects documentation edits to GitHub Issues rather than the file editor, which was not explicitly mentioned in the linked issue scope.	Clarify whether the editUrl redirect to GitHub Issues is intentional and part of the documentation strategy or if it should point to the actual file editor instead.

✅ 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: creating dedicated markdown documentation and building an explicit navigation structure in sidebars.ts.
Linked Issues check	✅ Passed	All coding requirements from issue #41 are met: four new markdown docs created in website/docs/, explicit sidebar navigation implemented with categorization, documentation renders correctly, and root README.md remains untouched.
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 feat/docs-content

---

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

[github-actions]

Package	Line Rate	Health
github.com/Vaishnav88sk/claritty/clarctl-go/cmd	36%	❌
github.com/Vaishnav88sk/claritty/clarctl-go/internal/ai	72%	➖
github.com/Vaishnav88sk/claritty/clarctl-go/internal/config	92%	✔
github.com/Vaishnav88sk/claritty/clarctl-go/internal/ui	12%	❌
github.com/Vaishnav88sk/claritty/sre-agent/hub/internal/api	60%	➖
github.com/Vaishnav88sk/claritty/sre-agent/agent/internal/ai	67%	➖
github.com/Vaishnav88sk/claritty/sre-agent/agent/internal/k8s	71%	➖
Summary	62% (992 / 1622)	➖