Optimize README and docs structure for adoption clarity#222
Merged
Conversation
Restructure README from 354-line reference doc into ~210-line conversion-oriented landing page. Create documentation funnel: README for first impression + quick start, docs/* for depth. Changes: - README: Remove Key Features table (redundant with comparison table), Commands Reference (extracted to docs/cli.md), component type catalog and pack creation snippet (already in creating-tech-packs.md), condense Safety & Trust table to summary with link, condense Use Cases, move Real-World Examples up for social proof after Quick Start - docs/cli.md: New complete CLI reference with all commands and flags including mcs export (previously undocumented in user-facing docs) - docs/architecture.md: Add Safety & Trust section with expanded guarantee explanations, fix broken relative link to techpack-schema.md - docs/README.md: New documentation index with progressive-disclosure navigation and task-to-page quick links - All docs: Add consistent navigation footer with next/prev suggestions No information lost — every section removed from README exists in docs/. https://claude.ai/code/session_01QQjDZUxdL9JvBjqmQPKd8N
- docs/cli.md: Add missing `-y, --yes` flag to `mcs doctor` section (exists in DoctorCommand.swift but was not documented) - docs/architecture.md: Clarify trust verification behavior — modified scripts are detected and user is prompted to re-trust, not outright rejected https://claude.ai/code/session_01QQjDZUxdL9JvBjqmQPKd8N
There was a problem hiding this comment.
Pull request overview
Restructures project documentation to make the root README more adoption-focused (quick-start first) while moving reference-heavy material into a dedicated docs/ hub and CLI reference.
Changes:
- Slims the root
README.mdby removing long reference sections and linking to dedicated docs. - Adds a docs hub (
docs/README.md) and a full CLI reference (docs/cli.md). - Updates existing docs with consistent footer navigation and expands architecture docs with a “Safety & Trust” section.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Refocuses the root README around quick-start + links to deeper docs. |
docs/README.md |
New documentation landing page with quick links and navigation. |
docs/cli.md |
New complete CLI reference extracted from README. |
docs/architecture.md |
Fixes an internal link and adds “Safety & Trust” section + footer nav. |
docs/creating-tech-packs.md |
Adds “Next” + footer navigation. |
docs/techpack-schema.md |
Adds “Next” + footer navigation. |
docs/troubleshooting.md |
Adds “Back to docs home” + footer navigation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/cli.md
Outdated
| @@ -0,0 +1,138 @@ | |||
| # CLI Reference | |||
|
|
|||
| Complete command reference for `mcs`. For a quick introduction, see the [README](../README.md#-quick-start). | |||
There was a problem hiding this comment.
The fragment #-quick-start does not match the generated GitHub anchor for the ## 🚀 Quick Start heading in the root README (it will be #quick-start). Update this link so it resolves correctly.
Suggested change
| Complete command reference for `mcs`. For a quick introduction, see the [README](../README.md#-quick-start). | |
| Complete command reference for `mcs`. For a quick introduction, see the [README](../README.md#quick-start). |
docs/README.md
Outdated
|
|
||
| New to mcs? Start here: | ||
|
|
||
| 1. [Install and Quick Start](../README.md#-quick-start) — Get your first pack running in under 2 minutes |
There was a problem hiding this comment.
The ../README.md#-quick-start link is using an incorrect anchor. In the root README the heading is ## 🚀 Quick Start, which GitHub anchors as #quick-start (without the leading dash). Update the fragment so the link resolves.
Suggested change
| 1. [Install and Quick Start](../README.md#-quick-start) — Get your first pack running in under 2 minutes | |
| 1. [Install and Quick Start](../README.md#quick-start) — Get your first pack running in under 2 minutes |
- Remove leading dash from Quick Start anchor (#-quick-start → #quick-start)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
The README had grown into a comprehensive reference document that buried the quick-start flow under walls of feature tables, use cases, and command listings. New users had to scroll past ~300 lines before reaching real-world examples. This restructure optimizes for the adoption funnel: hook → install → use → learn more.
Changes
docs/cli.md— Complete CLI reference extracted from README, with flag tables and usage examples for every command (sync,pack,doctor,cleanup,export)docs/README.md— Documentation hub with "Getting Started", "Building Tech Packs", and "Understanding the Engine" sections plus a quick-links tabledocs/architecture.md— Added "Safety & Trust" section (previously only in README) with implementation details--yesflag to doctor command docs, clarified trust verification behavior for local packsTest Plan
docs/cli.mdcovers all commands frommcs --help