docs(docs): improve formatting and structure

[avanibapna06]

What

• Improved the formatting and overall layout of the README.md file.
• Properly formatted and structured Markdown tables, lists, and code blocks for cleaner rendering on GitHub.
• Structured the Mermaid architecture and deployment diagrams correctly within the documentation.

Why

Fixes #173

How

• Fixed broken syntax errors in the README layout where plain text blocks had merged incorrectly.
• Wrapped CLI usage commands, configurations, and scripts into appropriate syntax-highlighted code fences (bash, yaml).
• Grouped peripheral details like shell completions and core metrics using HTML <details> blocks to keep the document highly readable.

Testing

• go build ./... passes
• Verified local Markdown rendering to ensure all sections, tables, and Mermaid workflows display without errors.

[github-actions]

🚀 First PR — welcome aboard!

A few things to expect:

1. CI: every PR runs build + race tests + lint + (eventually) the kernel matrix. If something fails, the log will tell you exactly which gate.
2. DCO: every commit needs Signed-off-by: — git commit -s adds it automatically.
3. Conventional Commits: PR titles like feat(doctor): add new rule or fix(bpf): handle X. We squash-merge by default.
4. Review: a maintainer will review within 72 hours. Suggestions are conversations, not orders — push back if something doesn't fit your context.

If you get stuck, reply here or jump to Discussions. We want this PR to land.

[avanibapna06]

Hi @optiqor and @btwshivam , just wanted to leave a gentle reminder on this PR. All the automated bot checks have passed successfully and the documentation formatting is ready for review. Could you please check and merge it when you get some time? Thank you! 🙏 #gssoc26