docs: refresh README with stronger positioning and structure#1049
docs: refresh README with stronger positioning and structure#1049
Conversation
- Lead with tagline instead of CAUTION box (moved to subtle early-access note) - Add 'Why SynthOrg?' section with 6 differentiators - Convert capabilities table to linked list with docs links - Add Dashboard and CLI as first-class capabilities - Add Compare section linking to /compare/ (44 frameworks) - Move security badges to collapsible details section - Expand documentation table with guide count and module count - Update architecture diagram to include Dashboard and CLI nodes - Add contributor note pointing to design spec
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
🧰 Additional context used📓 Path-based instructions (1)**/*.md📄 CodeRabbit inference engine (CLAUDE.md)
Files:
🧠 Learnings (21)📓 Common learnings📚 Learning: 2026-04-03T19:34:11.483ZApplied to files:
📚 Learning: 2026-03-19T07:12:14.508ZApplied to files:
📚 Learning: 2026-03-21T12:54:22.557ZApplied to files:
📚 Learning: 2026-04-02T07:18:02.381ZApplied to files:
📚 Learning: 2026-04-03T19:34:11.483ZApplied to files:
📚 Learning: 2026-03-19T07:12:14.508ZApplied to files:
📚 Learning: 2026-03-20T08:28:32.845ZApplied to files:
📚 Learning: 2026-03-17T22:08:13.456ZApplied to files:
📚 Learning: 2026-03-26T15:18:16.848ZApplied to files:
📚 Learning: 2026-03-16T06:24:56.341ZApplied to files:
📚 Learning: 2026-04-01T15:36:39.993ZApplied to files:
📚 Learning: 2026-03-14T15:43:05.601ZApplied to files:
📚 Learning: 2026-03-17T22:08:13.456ZApplied to files:
📚 Learning: 2026-03-19T07:12:14.508ZApplied to files:
📚 Learning: 2026-03-19T07:12:14.508ZApplied to files:
📚 Learning: 2026-03-17T06:30:14.180ZApplied to files:
📚 Learning: 2026-03-19T07:13:44.964ZApplied to files:
📚 Learning: 2026-03-16T06:24:56.341ZApplied to files:
📚 Learning: 2026-03-19T07:12:14.508ZApplied to files:
📚 Learning: 2026-03-15T18:38:44.202ZApplied to files:
🔇 Additional comments (12)
WalkthroughThe README.md file has been restructured with content modifications and organizational changes. The "MASSIVE WORK IN PROGRESS" warning was removed and branding content was condensed. Two security-related badges (OpenSSF Scorecard and SLSA 3) were removed from the header. The "What is SynthOrg?" and "Capabilities" sections were replaced with a concise narrative covering YAML-based company definition, message-bus collaboration, and workflows. CLI command listings were simplified. A new "What's Inside" section was added with detailed documentation links. The architecture diagram was updated to include React Dashboard and Go CLI components. A "Security" section replaced the previous "Status" section, and documentation and licensing information were adjusted. Suggested labels
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
There was a problem hiding this comment.
Code Review
This pull request refactors the README.md to enhance the project's value proposition and documentation structure. Key changes include a revised introduction, a reorganized features section, and an updated architecture diagram. The review feedback identifies an issue with syntax highlighting in the installation instructions and suggests consistent naming for the design documentation.
| ```bash | ||
| # Linux / macOS | ||
| curl -sSfL https://synthorg.io/get/install.sh | bash | ||
| ``` | ||
|
|
||
| ```powershell | ||
| # Windows (PowerShell) | ||
| irm https://synthorg.io/get/install.ps1 | iex | ||
| ``` |
There was a problem hiding this comment.
The installation instructions for Windows (PowerShell) are now included within a bash code block. This will result in incorrect syntax highlighting and may be confusing for users. It is better to keep them in separate code blocks with the appropriate language identifiers as they were previously.
| ```bash | |
| # Linux / macOS | |
| curl -sSfL https://synthorg.io/get/install.sh | bash | |
| ``` | |
| ```powershell | |
| # Windows (PowerShell) | |
| irm https://synthorg.io/get/install.ps1 | iex | |
| ``` | |
| ### Install | |
| ```bash | |
| # Linux / macOS | |
| curl -sSfL https://synthorg.io/get/install.sh | bash |
# Windows (PowerShell)
irm https://synthorg.io/get/install.ps1 | iex| | [Licensing](docs/licensing.md) | BSL 1.1 terms, Additional Use Grant, commercial options | | ||
| | [Roadmap](docs/roadmap/) | Current status, open questions, future vision | | ||
|
|
||
| > **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature. See [`DESIGN_SPEC.md`](docs/DESIGN_SPEC.md) for the full design set. |
There was a problem hiding this comment.
The file docs/design/index.md is referred to as "Design Specification" in the documentation table (line 121). Using the same name here ("Design Specification" instead of "Design Overview") improves consistency and helps users navigate the documentation more easily.
| > **Contributors:** Start with the [Design Overview](docs/design/index.md) before implementing any feature. See [`DESIGN_SPEC.md`](docs/DESIGN_SPEC.md) for the full design set. | |
| > **Contributors:** Start with the [Design Specification](docs/design/index.md) before implementing any feature. See [`DESIGN_SPEC.md`](docs/DESIGN_SPEC.md) for the full design set. |
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Snapshot WarningsEnsure that dependencies are being submitted on PR branches. Re-running this action after a short time may resolve the issue. See the documentation for more information and troubleshooting advice. Scanned FilesNone |
There was a problem hiding this comment.
Pull request overview
Refreshes the README to improve positioning and structure, presenting SynthOrg more confidently while still communicating early-access status and linking readers to deeper docs.
Changes:
- Replaces the WIP caution block with a tagline + “Early access” note and a new “Why SynthOrg?” differentiators section
- Reworks capabilities into a “What’s Inside” linked list and expands the Documentation table with more structure/metadata
- Moves security badges into a collapsible section and updates the architecture diagram to include Dashboard and CLI
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```bash | ||
| # Linux / macOS | ||
| curl -sSfL https://synthorg.io/get/install.sh | bash | ||
| ``` | ||
|
|
||
| ```powershell | ||
| # Windows (PowerShell) | ||
| irm https://synthorg.io/get/install.ps1 | iex | ||
| ``` |
There was a problem hiding this comment.
The install snippet is marked as a bash code block but includes a Windows PowerShell command (`irm ... | iex`). This can confuse readers and gives incorrect syntax highlighting; consider splitting into separate bash/powershell blocks (or using a neutral sh block) so each platform’s command is clearly scoped.
|
Closing in favor of a comprehensive docs refresh PR that includes the README changes plus full docs/ audit fixes. |
README: - Lead with tagline instead of CAUTION box - Add 'Why SynthOrg?' section with 6 differentiators - Security badges (OpenSSF, SLSA) promoted to top, CI badge removed - Capabilities as linked list with docs links - Add Dashboard, CLI, Compare sections - Split bash/powershell install blocks (PR #1049 feedback) - Architecture diagram includes Dashboard and CLI nodes Roadmap (fully rewritten -- was severely stale): - index.md: accurate 'What works today' list, honest 'What's not there yet' - future-vision.md: add 'Recently Shipped' section for features that were listed as future but are now done (workflow editor, network hosting, etc.) - open-questions.md: remove resolved questions, update mitigations Guides: - quickstart.md: fix 'Solo Builder' -> 'Solo Founder' template name - deployment.md: fix backend image name (synthorg -> synthorg-backend) Architecture: - decisions.md: remove pinned MCP version, update fine-tuning pipeline status, remove pinned Pydantic patch version Design: - memory.md: keep future backend options, remove stale 'see Decision Log' ref
README: - Lead with tagline instead of CAUTION box - Add 'Why SynthOrg?' section with 6 differentiators - Security badges (OpenSSF, SLSA) promoted to top, CI badge removed - Capabilities as linked list with docs links - Add Dashboard, CLI, Compare sections - Split bash/powershell install blocks (PR #1049 feedback) - Architecture diagram includes Dashboard and CLI nodes Roadmap (fully rewritten -- was severely stale): - index.md: accurate 'What works today' list, honest 'What's not there yet' - future-vision.md: add 'Recently Shipped' section for features that were listed as future but are now done (workflow editor, network hosting, etc.) - open-questions.md: remove resolved questions, update mitigations Guides: - quickstart.md: fix 'Solo Builder' -> 'Solo Founder' template name - deployment.md: fix backend image name (synthorg -> synthorg-backend) Architecture: - decisions.md: remove pinned MCP version, update fine-tuning pipeline status, remove pinned Pydantic patch version Design: - memory.md: keep future backend options, remove stale 'see Decision Log' ref
## Summary Full audit and refresh of all documentation. Fixes stale content found by 3 parallel audit agents across guides/, design/, architecture/, roadmap/, and reference/. ### README (rewrite) - Lead with tagline instead of CAUTION box - "Why SynthOrg?" section with 6 differentiators - Security badges (OpenSSF, SLSA) promoted to top row, CI badge removed - Capabilities converted from static HTML table to linked list with docs links - Dashboard, CLI, Compare sections added as first-class entries - Split bash/powershell install blocks (incorporates PR #1049 reviewer feedback from Gemini + Copilot) - Architecture diagram expanded to include Dashboard and CLI nodes ### Roadmap (fully rewritten -- was severely stale) - **index.md**: accurate "What works today" list reflecting v0.6.0 reality, honest "What's not there yet" section - **future-vision.md**: add "Recently Shipped" section (workflow editor, network hosting, local model management, ceremony scheduling were listed as "future" but are done). Update remaining items with version targets. - **open-questions.md**: remove resolved questions (#3 context window partially resolved, #10 meetings resolved), update risk mitigations with current state ### Guides - **quickstart.md**: fix "Solo Builder" -> "Solo Founder" (actual template name) - **deployment.md**: fix backend image name `synthorg` -> `synthorg-backend` ### Architecture - **decisions.md**: remove pinned MCP version (gets stale), update fine-tuning pipeline status, remove pinned Pydantic patch version ### Design - **memory.md**: keep future backend options in config comment, remove stale cross-reference
Summary
Refresh the README to lead with confidence instead of caveats, following patterns from top agent frameworks (CrewAI, LangGraph, Pydantic AI, OpenAI Agents SDK).
Key changes