docs: rewrite README for onboarding and source-first quickstart

[iKwesi]

Summary

• rewrite the README around the current CLI and docs surface
• add source-first install and quickstart guidance for doctor, inspect, explain, status, and the golden demo
• add a documentation regression test so the README keeps matching the repo surface

Why

The old README undersold the current product surface and left too much implicit for first-time users. This update makes the current state, install path, workflow entrypoints, and supporting docs much easier to understand.

Verification

• pnpm exec vitest run tests/documentation/readme-docs.test.ts tests/documentation/golden-demo-docs.test.ts tests/documentation/policy-config-docs.test.ts tests/documentation/roadmap-docs.test.ts
• pnpm test
• pnpm typecheck
• pnpm build

[Copilot]

Pull request overview

Rewrites the repository README to better onboard new users around the current CLI/docs surface, and adds a regression test to keep the README aligned with what the repo actually supports.

Changes:

• Reworked README content around “why”, current capabilities, source-first install, and a command-driven quickstart.
• Added a Vitest documentation regression test that asserts key headings/commands/links remain present in README.md.

Reviewed changes

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

File	Description
README.md	Rewritten onboarding + quickstart for current CLI surface, with updated docs links and repo structure overview.
tests/documentation/readme-docs.test.ts	New regression test asserting README includes key sections, commands, and doc references.

---

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

[Copilot]

Pull request overview

This PR rewrites the repository README to better reflect the current CLI surface and onboarding flow, and adds a regression test to keep the README aligned with the repo’s documented commands and linked docs.

Changes:

• Rewrite README.md around the current CLI workflows (doctor/inspect/explain/status) plus the golden demo and supporting docs.
• Add a Vitest documentation regression test that asserts key README sections/commands/links are present.

Reviewed changes

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

File	Description
README.md	Reworked onboarding narrative, source-first install, quickstart, commands table, and doc links.
tests/documentation/readme-docs.test.ts	Adds a regression test to ensure README continues to document the intended CLI surface and docs.

---

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

[Copilot]

Pull request overview

This PR modernizes the repository’s onboarding documentation to reflect the current CLI surface and adds a regression test to keep the README aligned with the repo’s actual commands and docs.

Changes:

• Rewrite README.md around current CLI workflows (doctor, inspect, explain, status) plus the golden demo.
• Add source-first install + quickstart guidance, including concrete command examples for built and dev execution paths.
• Add a Vitest documentation regression test to assert key README sections/strings remain present.

Reviewed changes

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

File	Description
README.md	Rewrites onboarding narrative, adds source install + quickstart, documents core commands/concepts, and links key docs.
tests/documentation/readme-docs.test.ts	Adds a regression test to ensure the README continues to document the current install/workflow surface and supporting docs.

---

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