docs: tighter value proposition, accuracy fixes, maintenance posture

[mazze93]

Summary

• README: Rewrites the opening with a concrete one-liner + who-it's-for, adds an explicit v0.3-experimental status block, replaces the six-section Design Principles bloat with a single table, removes the admin-only social preview instructions, adds a Maintenance Posture section (SLA, breaking-change policy, security link), and adds a Known Issues table with severity/target-version.
• INSTALL.md: Fixes wrong prerequisites (macOS 12→13, Swift 5.7→5.8, Xcode 14→15), removes non-existent CLI flags (--status, --config, --feedback positive), clarifies that SPM produces executables not .app bundles, and replaces the incorrect config JSON with the actual default_config.json structure.
• Both files: Fix CLI examples to use real flags (--feedback good|bad), real config JSON (uniform Beta priors, actual trigger keys), and link SECURITY.md from the README for a clear trust path.

Test plan

• Read through README top-to-bottom as a new visitor — value prop lands in the first two sentences
• All CLI examples in README and INSTALL.md are runnable against the actual binary
• Prerequisites match CLAUDE.md (macOS 13+, Swift 5.8+)
• Config JSON matches default_config.json in the repo root
• SECURITY.md is reachable from the Maintenance Posture section
• CI passes (file existence checks include README, INSTALL.md, SECURITY.md)

https://claude.ai/code/session_0193B19zr8PsbvJMphKxufw4

---

Generated by Claude Code

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (2)

• INSTALL.md is excluded by none and included by none
• README.md is excluded by none and included by none

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: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ebba266c-5b5f-410b-a951-11f8c52431c7

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/repo-docs-value-trust-dLqaj

---

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

[mazze93]

Heads up: this PR is now docs-only again. The CLI fix that was briefly on this branch has been split into #14 (targets main), since it repairs a bug that lives in main rather than anything in these docs.

As a result, Build, test, and guardrails here will be red until #14 merges — this branch inherits the failing testExportAndImportAcceptUserFlagBeforeCommandFlag from main. Once #14 lands, rebasing this branch on main turns it green with no further changes.

---

Generated by Claude Code