Make onboarding readable and document the real trust boundary

[samtay32]

What changed

• rewrites the README as a plain-language front door for non-coders and coders
• keeps the 30-second prompt, three commands, delivery flow, adapter model, synthesis visual, and maintainer checks
• removes the repository-popularity claim, defensive repetition, and front-page source tables
• links the complete, unchanged research ledger in docs/SOURCES_AND_TRADEOFFS.md
• adds docs/TRUST.md with a side-by-side map of CLI-enforced controls versus agent instructions
• documents the threat model, containment boundary, approval behavior, executable-check limitation, review gate, parallel-work boundary, and release controls

Why

The previous README was a strong engineering audit but a difficult product entrance. The package names non-coders as a primary audience, yet most of the front page required senior-engineer vocabulary. The old structure also mixed provenance, onboarding, architecture, and trust into one long page.

User impact

A new user reaches the working prompt and commands immediately, understands what the agent will ask, and can see the honest safety boundary without reading an audit ledger. Engineers retain direct links to the full architecture, trust model, source history, review loop, adapters, and release process.

The README falls from 438 lines and roughly 2,108 words to 198 lines and roughly 1,136 total words. Prose-only estimation is about 693 words, Flesch reading ease 53.3, and grade level 9.0.

Validation

• npm run release:check
• 65/65 tests
• package dry-run: 78 intended files, including docs/TRUST.md
• packed install smoke passed
• npx --yes markdownlint-cli2@0.20.0 '**/*.md': 49 files, 0 errors
• all local links in README and TRUST resolve
• git diff --check

Summary by CodeRabbit

• Documentation
  • Reworked the README into a shorter, sectioned overview covering onboarding, CLI commands, installation, delivery, adapters, safety, requirements, and licensing.
  • Added comprehensive trust and safety documentation describing enforced protections, limitations, verification steps, and related resources.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0984b9f0-9e97-44e1-b45b-2a794fdfbb2f

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

The README is substantially condensed and reorganized around onboarding, CLI usage, delivery, installation, adapters, safety, and references. A new docs/TRUST.md documents enforced protections, limitations, release controls, threats, and verification steps.

Changes

Documentation and Trust Boundaries

Layer / File(s)	Summary
README onboarding and delivery flow README.md	Introduces concise onboarding, the three-command workflow, conditional setup questions, and risk-scaled delivery flow.
README installation and adapter semantics README.md	Summarizes installed components, replaceable adapters, provider fallback behavior, and safety boundaries.
README references and maintenance README.md	Condenses prior-art, documentation, requirements, maintainer checks, release process, and license information.
Trust promises and CLI protections docs/TRUST.md	Defines CLI-enforced checks and documents containment, updates, approvals, command policies, evidence handling, review receipts, and parallel-work constraints.
Release boundaries and claim verification docs/TRUST.md	Documents package release controls, remaining threats, operational measures, verification commands, tests, and implementation references.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• samtay32/ultimate-agent-stack#6: Also updates README.md with project lineage and source-synthesis documentation.

🚥 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 title accurately captures the README onboarding rewrite and the new trust-boundary documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/readme-trust-v060

---

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

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@README.md`:
- Around line 84-95: Update the Mermaid delivery flow around “Project tests and
checks” and “Independent review” so independent review is conditional on project
policy rather than mandatory for every project. Preserve the existing
valid-finding loop and route projects that do not require review directly to the
merge-ready result.

🪄 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: ASSERTIVE

Plan: Pro Plus

Run ID: 7a8a8132-dda9-4a6e-b809-fa49b2957b73

📥 Commits

Reviewing files that changed from the base of the PR and between 408218b and 24ad697.

📒 Files selected for processing (2)

• README.md
• docs/TRUST.md

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.