From 4df8bf9de9cee896edd994d229f3f35189645526 Mon Sep 17 00:00:00 2001 From: Travis James Date: Sat, 26 Sep 2026 01:27:22 -0500 Subject: [PATCH] docs: brand The Boss README and document UI routing Assisted-by: Codex:GPT-6 [Git, Node.js, Playwright] --- CONTRIBUTING.md | 92 ++------ DESIGN.md | 6 +- README.md | 312 ++++----------------------- docs/README.md | 7 +- docs/contrib/development.md | 12 +- docs/contrib/the-boss-release.md | 2 +- docs/contrib/ui-ux-routing.md | 103 +++++++++ docs/references/components/README.md | 2 + scripts/gen-doc-index.ts | 2 +- 9 files changed, 183 insertions(+), 355 deletions(-) create mode 100644 docs/contrib/ui-ux-routing.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 721760a9409..e4e32573a35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,93 +1,43 @@ -# Cherry Studio Contributor Guide +# The Boss Contributor Guide -Welcome to the Cherry Studio contributor community! We are committed to making Cherry Studio a project that provides long-term value and hope to invite more developers to join us. Whether you are an experienced developer or a beginner just starting out, your contributions will help us better serve users and improve software quality. +Contribute improvements to The Boss desktop workspace, documentation, or integrations through [this repository](https://github.com/Prometheus-AGS/the-boss). Start with an observed problem or explicit requirement, keep the change scoped, and preserve existing behavior outside that scope. -## How to Contribute +## Before you start -Here are several ways you can participate: +Read the [Code of Conduct](CODE_OF_CONDUCT.md), [LICENSE](LICENSE), and repository instructions in [CLAUDE.md](CLAUDE.md). Follow the [development guide](docs/contrib/development.md) for the pinned Node/pnpm environment and local setup. Active development targets this repository's `main` branch. -1. **Contribute Code**: Help us develop new features or optimize existing code. Please ensure your code adheres to our coding standards and passes all tests. +Use [GitHub Issues](https://github.com/Prometheus-AGS/the-boss/issues) for reproducible defects or proposed work. Include the affected platform, version, steps, expected behavior, and relevant evidence without credentials or private user data. -2. **Fix Bugs**: If you find a bug, you are welcome to submit a fix. Please confirm the issue is resolved before submitting and include relevant tests. +## UI/UX and team workflow -3. **Maintain Issues**: Help us manage issues on GitHub by assisting with tagging, classifying, and resolving problems. +Read [UI/UX routing and team adoption](docs/contrib/ui-ux-routing.md) for the portable catalog, project installation, and evidence limits. The existing [boss-core team](.agent-team/boss-core/README.md) provides role instructions: `boss-ux` owns usability/design artifacts, `boss-renderer` implements renderer changes, and `boss-verifier` reviews completed acceptance independently where the harness supports it. -4. **Product Design**: Participate in product design discussions to help us improve user experience and interface design. +Follow [DESIGN.md](DESIGN.md), the shared token system, and existing Electron tooling. Routing guidance does not authorize a new palette, framework, dependency, or redesign. Backend-only tasks use the relevant team role without loading UI guidance. -5. **Write Documentation**: Help us improve the user manual, API documentation, and developer guides. +## Implementation and verification -6. **Community Maintenance**: Participate in community discussions, help answer user questions, and promote community activity. +Finish the coherent production phase before its verification boundary. Exercise the promised behavior through the real UI, IPC, process, filesystem, database, or protocol path. Unit or mock-only results do not establish completion. Record the commands actually run, source boundary, evidence paths, failures, and unavailable platform checks. -7. **Promote Usage**: Promote Cherry Studio through blogs, social media, and other channels to attract more users and developers. +For documentation changes, edit document headings and frontmatter, then run `pnpm docs:index` to regenerate [the index](docs/README.md). Run `pnpm docs:check` at the completed documentation boundary; it checks links, structure, frontmatter/source paths, and index freshness. -## Before You Start +UI acceptance also requires the applicable captures and interaction evidence plus independent review. The routing helper's `phase-boundary` result is an evidence request, not a test run or PASS. -Please make sure you have read the [Code of Conduct](CODE_OF_CONDUCT.md) and the [LICENSE](LICENSE). +## Pull requests -## Setting Up Your Development Environment +Use a focused branch and Conventional Commit messages. Explain the problem, resulting behavior, scope, and actual verification. Follow [.github/pull_request_template.md](.github/pull_request_template.md) and the repository's `gh-create-pr` workflow. Draft PRs may communicate incomplete work, but do not claim that draft status or a passing automated check proves acceptance. -Please refer to the [Developer Guide](docs/contrib/development.md) for instructions on setting up your local development environment, including prerequisites, installation steps, and available commands. +### Contributor certification -For a comprehensive overview of the project architecture, tech stack, conventions, and available commands, see [`CLAUDE.md`](CLAUDE.md). +The inherited contribution policy requires human contributors to certify their right to contribute under [LICENSE](LICENSE). Human certification uses the conventional trailer: -## Getting Started - -To help you get familiar with the codebase, we recommend tackling issues tagged with one or more of the following labels: [good first issue](https://github.com/CherryHQ/cherry-studio/labels/good%20first%20issue), [help wanted](https://github.com/CherryHQ/cherry-studio/labels/help%20wanted), or [bug](https://github.com/CherryHQ/cherry-studio/labels/bug). Any help is welcome. - -### Testing - -Features without tests are considered non-existent. To ensure code is truly effective, relevant processes should be covered by unit tests and functional tests. Therefore, when considering contributions, please also consider testability. All tests can be run locally without dependency on CI. Please refer to the "Testing" section in the [Developer Guide](docs/contrib/development.md). - -### Automated Testing for Pull Requests - -Automated tests are triggered on pull requests (PRs) opened by members of the Cherry Studio organization, except for draft PRs. PRs opened by new contributors will initially be marked with the `needs-ok-to-test` label and will not be automatically tested. Once a Cherry Studio organization member adds `/ok-to-test` to the PR, the test pipeline will be created. - -### Consider Opening Your Pull Request as a Draft - -Not all pull requests are ready for review when created. This might be because the author wants to start a discussion, they are not entirely sure if the changes are heading in the right direction, or the changes are not yet complete. Please consider creating these PRs as [draft pull requests](https://github.blog/2019-02-14-introducing-draft-pull-requests/). Draft PRs are skipped by CI, thus saving CI resources. This also means reviewers will not be automatically assigned, and the community will understand that this PR is not yet ready for review. -Reviewers will be assigned after you mark the draft pull request as ready for review. - -### Contributor Compliance with Project Terms - -We require every contributor to certify that they have the right to legally contribute to our project. Contributors express this by consciously signing their commits, thereby indicating their compliance with the [LICENSE](LICENSE). -A signed commit is one where the commit message includes the following: - -``` +```text Signed-off-by: Your Name ``` -You can generate a signed commit using the following command [git commit --signoff](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff): - -``` -git commit --signoff -m "Your commit message" -``` - -### Getting Code Reviewed/Merged - -Maintainers are here to help you implement your use case within a reasonable timeframe. They will do their best to review your code and provide constructive feedback promptly. However, if you get stuck during the review process or feel your Pull Request is not receiving the attention it deserves, please contact us via comments in the Issue or through the [Community](README.md#-community). - -### Participating in the Test Plan - -The Test Plan aims to provide users with a more stable application experience and faster iteration speed. For details, please refer to the [Test Plan](docs/contrib/test-plan.md). - -### Other Suggestions - -- **Contact Developers**: Before submitting a PR, you can contact the developers first to discuss or get help. - -## Important Contribution Guidelines & Focus Areas - -Please review the following critical information before submitting your Pull Request: - -### Branch Strategy - -`main` is the default branch for active development — submit features, refactors, optimizations, and fixes here. - - -## Contact Us +This is a human certification, distinct from cryptographic commit signing. Agents must follow the active operator and repository instructions for generated-content attribution and must not manufacture a human certification. -If you have any questions or suggestions, feel free to contact us through the following ways: +## Releases and upstream -- WeChat: kangfenmao -- [GitHub Issues](https://github.com/CherryHQ/cherry-studio/issues) +Use [The Boss release workflow](docs/contrib/the-boss-release.md) for fork releases and installed acceptance. A source merge does not establish inclusion in an existing published installer. -Thank you for your support and contributions! We look forward to working with you to make Cherry Studio a better product. +This project derives from Cherry Studio. Preserve upstream attribution, notices, and compatibility identifiers. Follow the [upstream merge policy](docs/contrib/upstream-merges.md); upstream service names and historical data identifiers are not cosmetic branding. diff --git a/DESIGN.md b/DESIGN.md index e50f9e3c080..cb8f9ed1e24 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,6 +1,6 @@ -# Cherry Studio Design System +# The Boss Design System -This document defines Cherry Studio's product-wide visual direction and the rules for choosing shared design +This document defines The Boss's product-wide visual direction and the rules for choosing shared design semantics. It is intentionally not a component API reference, a copy of Tailwind classes, or a specification for individual feature pages. @@ -21,7 +21,7 @@ only when the product-wide design intent has changed. ## 1. Design direction -Cherry Studio is a content-first AI workspace. The interface should feel calm, precise, and utilitarian so that +The Boss is a content-first AI workspace. The interface should feel calm, precise, and utilitarian so that conversation, code, documents, and user-created content remain the visual focus. The shared direction is: diff --git a/README.md b/README.md index 68b2f79da5a..088aa957784 100644 --- a/README.md +++ b/README.md @@ -1,295 +1,59 @@ +

+ The Boss logo +

-

- - banner
- -

+

The Boss

-

English | Official Site | Documents | Development | Feedback

+

An AI desktop workspace for conversations, agents, tools, and project work.

-
+

+ Website · + Downloads · + Documentation · + Development · + Issues +

-[![][deepwiki-shield]][deepwiki-link] -[![][twitter-shield]][twitter-link] -[![][discord-shield]][discord-link] -[![][telegram-shield]][telegram-link] +The Boss is the Know Me Tools desktop workspace built on [Cherry Studio](https://github.com/CherryHQ/cherry-studio). It brings multi-provider AI conversations, agent sessions, workspace tools, knowledge and document workflows together with Prometheus integration. This repository owns The Boss source, documentation, and release workflow. -
-
+## Get The Boss -[![][github-release-shield]][github-release-link] -[![][github-nightly-shield]][github-nightly-link] -[![][github-contributors-shield]][github-contributors-link] -[![][license-shield]][license-link] -[![][commercial-shield]][commercial-link] -[![][sponsor-shield]][sponsor-link] +Download the installer for your platform and architecture from [The Boss releases](https://github.com/Prometheus-AGS/the-boss/releases). Read that release's notes and platform records for its available installers, UAR profile, signing status, and acceptance evidence. Source support for a platform does not establish that a tested installer is available for it. -
+The documentation on `main` describes current source. The UI/UX catalog and team-routing adoption described below were merged after the existing 2.2.2 release; that merge does **not** establish that the 2.2.2 installers contain them. Use the [release runbook](docs/contrib/the-boss-release.md) for packaging and installed acceptance. -
- Featured｜HelloGitHub - CherryHQ%2Fcherry-studio | Trendshift - Cherry Studio - AI Chatbots, AI Desktop Client | Product Hunt -
+## Workspace capabilities -# 🍒 Cherry Studio +- Conversations and assistants across cloud and local model providers. +- Agent sessions with workspace context, MCP tools, skills, and approval boundaries. +- Knowledge, document, code, and Markdown workflows. +- Prometheus settings for packaged skills, workspace indexing, tools, and optional services. +- Shared renderer components, semantic design tokens, and light/dark themes. -Cherry Studio is a desktop client that supports multiple LLM providers, available on Windows, Mac and Linux. +Provider access and optional integrations require their own configuration. See the [documentation index](docs/README.md) for architecture and operational contracts. -👏 Join [Telegram Group](https://t.me/CherryStudioAI)｜[Discord](https://discord.gg/wez8HtpxqQ) | [QQ Group(575014769)](https://qm.qq.com/q/lo0D4qVZKi) +## UI/UX skills and project teams -❤️ Like Cherry Studio? Give it a star 🌟 or [Sponsor](docs/sponsor.md) to support the development! +The current source distributes **97 mini skills**, including **40 portable UI/UX catalog entries**, through `resources/skills/`. The shared `prometheus-ui-ux` router selects project context, focused Pro Max guidance, craft, and platform instructions. `prometheus-ui-review` defines independent review at a completed UI phase; it does not automatically launch a browser or certify an application. -# 🌠 Screenshot +The existing ten-role [boss-core team](.agent-team/boss-core/README.md) is adopted through the project routing record. UI work goes to `boss-ux` and `boss-renderer`; completed UI acceptance goes to `boss-verifier`. Existing tokens, Electron workflows, permissions, and ownership remain authoritative. -![](https://github.com/user-attachments/assets/36dddb2c-e0fb-4a5f-9411-91447bab6e18) +Read [UI/UX routing and team adoption](docs/contrib/ui-ux-routing.md) for commands, prerequisites, installation boundaries, deferred engine support, and evidence limits. -![](https://github.com/user-attachments/assets/f549e8a0-2385-40b4-b52b-2039e39f2930) +## Develop and contribute -![](https://github.com/user-attachments/assets/58e0237c-4d36-40de-b428-53051d982026) +Use the Node version in [.node-version](.node-version), the engine range and pnpm pin in [package.json](package.json), and the [development guide](docs/contrib/development.md). Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the repository instructions in [CLAUDE.md](CLAUDE.md). Active development targets this repository's `main` branch. -# 🌟 Key Features +- [Documentation index](docs/README.md) +- [UI/UX routing and team adoption](docs/contrib/ui-ux-routing.md) +- [Design system](DESIGN.md) +- [The Boss release workflow](docs/contrib/the-boss-release.md) +- [Upstream merge policy](docs/contrib/upstream-merges.md) -1. **Diverse LLM Provider Support**: +Documentation lives in this repository as Markdown. The index is generated from document headings and frontmatter with `pnpm docs:index`; the completed documentation gate is `pnpm docs:check`. -- ☁️ Major LLM Cloud Services: OpenAI, Gemini, Anthropic, and more -- 🔗 AI Web Service Integration: Claude, Perplexity, [Poe](https://poe.com/), and others -- 💻 Local Model Support with Ollama, LM Studio +## Attribution and license -2. **AI Assistants & Conversations**: +The Boss is derived from [Cherry Studio](https://github.com/CherryHQ/cherry-studio). Upstream contributors, copyright notices, and license obligations remain applicable. See [LICENSE](LICENSE) for the GNU Affero General Public License v3.0. -- 📚 300+ Pre-configured AI Assistants -- 🤖 Custom Assistant Creation -- 💬 Multi-model Simultaneous Conversations - -3. **Document & Data Processing**: - -- 📄 Supports Text, Images, Office, PDF, and more -- ☁️ WebDAV File Management and Backup -- 📊 Mermaid Chart Visualization -- 💻 Code Syntax Highlighting - -4. **Practical Tools Integration**: - -- 🔍 Global Search Functionality -- 📝 Topic Management System -- 🔤 AI-powered Translation -- 🎯 Drag-and-drop Sorting -- 🔌 Mini Program Support -- ⚙️ MCP(Model Context Protocol) Server - -5. **Enhanced User Experience**: - -- 🖥️ Cross-platform Support for Windows, Mac, and Linux -- 📦 Ready to Use - No Environment Setup Required -- 🎨 Light/Dark Themes and Transparent Window -- 📝 Complete Markdown Rendering -- 🤲 Easy Content Sharing - -# 📝 Roadmap - -We're actively working on the following features and improvements: - -1. 🎯 **Core Features** - -- Selection Assistant with smart content selection enhancement -- Deep Research with advanced research capabilities -- Document Preprocessing with improved document handling -- MCP Marketplace for Model Context Protocol ecosystem - -2. 🗂 **Knowledge Management** - -- Notes and Collections -- Dynamic Canvas visualization -- OCR capabilities -- TTS (Text-to-Speech) support - -3. 📱 **Platform Support** - -- HarmonyOS Edition (PC) -- Android App (Phase 1) -- iOS App (Phase 1) -- Multi-Window support -- Window Pinning functionality -- Intel AI PC (Core Ultra) Support - -4. 🔌 **Advanced Features** - -- Plugin System -- ASR (Automatic Speech Recognition) -- Assistant and Topic Interaction Refactoring - -Track our progress and contribute on our [project board](https://github.com/orgs/CherryHQ/projects/7). - -Want to influence our roadmap? Join our [GitHub Discussions](https://github.com/CherryHQ/cherry-studio/discussions) to share your ideas and feedback! - -# 🌈 Theme - -- Theme Gallery: -- Aero Theme: -- PaperMaterial Theme: -- Claude dynamic-style: -- Maple Neon Theme: - -Welcome PR for more themes - -# 🤝 Contributing - -We welcome contributions to Cherry Studio! Here are some ways you can contribute: - -1. **Contribute Code**: Develop new features or optimize existing code. -2. **Fix Bugs**: Submit fixes for any bugs you find. -3. **Maintain Issues**: Help manage GitHub issues. -4. **Product Design**: Participate in design discussions. -5. **Write Documentation**: Improve user manuals and guides. -6. **Community Engagement**: Join discussions and help users. -7. **Promote Usage**: Spread the word about Cherry Studio. - -Refer to the [Branching Strategy](docs/contrib/branching-strategy.md) for contribution guidelines - -## Getting Started - -1. **Fork the Repository**: Fork and clone it to your local machine. -2. **Create a Branch**: For your changes. -3. **Submit Changes**: Commit and push your changes. -4. **Open a Pull Request**: Describe your changes and reasons. - -For more detailed guidelines, please refer to our [Contributing Guide](CONTRIBUTING.md). - -Thank you for your support and contributions! - -# 🔧 Developer Co-creation Program - -We are launching the Cherry Studio Developer Co-creation Program to foster a healthy and positive-feedback loop within the open-source ecosystem. We believe that great software is built collaboratively, and every merged pull request breathes new life into the project. - -We sincerely invite you to join our ranks of contributors and shape the future of Cherry Studio with us. - -## Contributor Rewards Program - -To give back to our core contributors and create a virtuous cycle, we have established the following long-term incentive plan. - -**The inaugural tracking period for this program will be Q3 2025 (July, August, September). Rewards for this cycle will be distributed on October 1st.** - -Within any tracking period (e.g., July 1st to September 30th for the first cycle), any developer who contributes more than **30 meaningful commits** to any of Cherry Studio's open-source projects on GitHub will be eligible for the following benefits: - -- **Cursor Subscription Sponsorship**: Receive a **$70 USD** credit or reimbursement for your [Cursor](https://cursor.sh/) subscription, making AI your most efficient coding partner. -- **Unlimited Model Access**: Get **unlimited** API calls for the **DeepSeek** and **Qwen** models. -- **Cutting-Edge Tech Access**: Enjoy occasional perks, including API access to models like **Claude**, **Gemini**, and **OpenAI**, keeping you at the forefront of technology. - -## Growing Together & Future Plans - -A vibrant community is the driving force behind any sustainable open-source project. As Cherry Studio grows, so will our rewards program. We are committed to continuously aligning our benefits with the best-in-class tools and resources in the industry. This ensures our core contributors receive meaningful support, creating a positive cycle where developers, the community, and the project grow together. - -**Moving forward, the project will also embrace an increasingly open stance to give back to the entire open-source community.** - -## How to Get Started? - -We look forward to your first Pull Request! - -You can start by exploring our repositories, picking up a `good first issue`, or proposing your own enhancements. Every commit is a testament to the spirit of open source. - -Thank you for your interest and contributions. - -Let's build together. - -# 🏢 Enterprise Edition - -Building on the Community Edition, we are proud to introduce **Cherry Studio Enterprise Edition**—a privately-deployable AI productivity and management platform designed for modern teams and enterprises. - -The Enterprise Edition addresses core challenges in team collaboration by centralizing the management of AI resources, knowledge, and data. It empowers organizations to enhance efficiency, foster innovation, and ensure compliance, all while maintaining 100% control over their data in a secure environment. - -## Core Advantages - -- **Unified Model Management**: Centrally integrate and manage various cloud-based LLMs (e.g., OpenAI, Anthropic, Google Gemini) and locally deployed private models. Employees can use them out-of-the-box without individual configuration. -- **Enterprise-Grade Knowledge Base**: Build, manage, and share team-wide knowledge bases. Ensures knowledge retention and consistency, enabling team members to interact with AI based on unified and accurate information. -- **Fine-Grained Access Control**: Easily manage employee accounts and assign role-based permissions for different models, knowledge bases, and features through a unified admin backend. -- **Fully Private Deployment**: Deploy the entire backend service on your on-premises servers or private cloud, ensuring your data remains 100% private and under your control to meet the strictest security and compliance standards. -- **Reliable Backend Services**: Provides stable API services and enterprise-grade data backup and recovery mechanisms to ensure business continuity. - -## ✨ Online Demo - -**🔗 [Cherry Studio Enterprise](https://enterprise.cherry-ai.com)** - -## Version Comparison - -| Feature | Community Edition | Enterprise Edition | -| :---------------- | :----------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | -| **Open Source** | ✅ Yes | ⭕️ Partially released to customers | -| **Cost** | [AGPL-3.0 License](https://github.com/CherryHQ/cherry-studio?tab=AGPL-3.0-1-ov-file) | Buyout / Subscription Fee | -| **Admin Backend** | — | ● Centralized **Model** Access
● **Employee** Management
● Shared **Knowledge Base**
● **Access** Control
● **Data** Backup | -| **Server** | — | ✅ Dedicated Private Deployment | - -## Get the Enterprise Edition - -We believe the Enterprise Edition will become your team's AI productivity engine. If you are interested in Cherry Studio Enterprise Edition and would like to learn more, request a quote, or schedule a demo, please feel free to contact us. - -- **For Business Inquiries & Purchasing**: - **📧 [bd@cherry-ai.com](mailto:bd@cherry-ai.com)** - -# 🔗 Related Projects - -- [new-api](https://github.com/QuantumNous/new-api): The next-generation LLM gateway and AI asset management system supports multiple languages. - -- [one-api](https://github.com/songquanpeng/one-api): LLM API management and distribution system supporting mainstream models like OpenAI, Azure, and Anthropic. Features a unified API interface, suitable for key management and secondary distribution. - -- [Poe](https://poe.com/): Poe gives you access to the best AI, all in one place. Explore GPT-5, Claude Opus 4.1, DeepSeek-R1, Veo 3, ElevenLabs, and millions of others. - -- [ublacklist](https://github.com/iorate/ublacklist): Blocks specific sites from appearing in Google search results - -# 🚀 Contributors - - - - -

- -# 📊 GitHub Stats - -![Stats](https://repobeats.axiom.co/api/embed/a693f2e5f773eed620f70031e974552156c7f397.svg "Repobeats analytics image") - -# ⭐️ Star History - - - - - - Star History Chart - - - -# 📜 License - -The Cherry Studio Community Edition is governed by the standard GNU Affero General Public License v3.0 (AGPL-3.0), available at https://www.gnu.org/licenses/agpl-3.0.html. - -Use of the Cherry Studio Community Edition for commercial purposes is permitted, subject to full compliance with the terms and conditions of the AGPL-3.0 license. - -Should you require a commercial license that provides an exemption from the AGPL-3.0 requirements, please contact us at bd@cherry-ai.com. - - - -[deepwiki-shield]: https://img.shields.io/badge/Deepwiki-CherryHQ-0088CC?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNy45MyAzMiI+PHBhdGggZD0iTTE5LjMzIDE0LjEyYy42Ny0uMzkgMS41LS4zOSAyLjE4IDBsMS43NCAxYy4wNi4wMy4xMS4wNi4xOC4wN2guMDRjLjA2LjAzLjEyLjAzLjE4LjAzaC4wMmMuMDYgMCAuMTEgMCAuMTctLjAyaC4wM2MuMDYtLjAyLjEyLS4wNS4xNy0uMDhoLjAybDMuNDgtMi4wMWMuMjUtLjE0LjQtLjQxLjQtLjdWOC40YS44MS44MSAwIDAgMC0uNC0uN2wtMy40OC0yLjAxYS44My44MyAwIDAgMC0uODEgMEwxOS43NyA3LjdoLS4wMWwtLjE1LjEyLS4wMi4wMnMtLjA3LjA5LS4xLjE0VjhhLjQuNCAwIDAgMC0uMDguMTd2LjA0Yy0uMDMuMDYtLjAzLjEyLS4wMy4xOXYyLjAxYzAgLjc4LS40MSAxLjQ5LTEuMDkgMS44OC0uNjcuMzktMS41LjM5LTIuMTggMGwtMS43NC0xYS42LjYgMCAwIDAtLjIxLS4wOGMtLjA2LS4wMS0uMTItLjAyLS4xOC0uMDJoLS4wM2MtLjA2IDAtLjExLjAxLS4xNy4wMmgtLjAzYy0uMDYuMDItLjEyLjA0LS4xNy4wN2gtLjAybC0zLjQ3IDIuMDFjLS4yNS4xNC0uNC40MS0uNC43VjE4YzAgLjI5LjE1LjU1LjQuN2wzLjQ4IDIuMDFoLjAyYy4wNi4wNC4xMS4wNi4xNy4wOGguMDNjLjA1LjAyLjExLjAzLjE3LjAzaC4wMmMuMDYgMCAuMTIgMCAuMTgtLjAyaC4wNGMuMDYtLjAzLjEyLS4wNS4xOC0uMDhsMS43NC0xYy42Ny0uMzkgMS41LS4zOSAyLjE3IDBzMS4wOSAxLjExIDEuMDkgMS44OHYyLjAxYzAgLjA3IDAgLjEzLjAyLjE5di4wNGMuMDMuMDYuMDUuMTIuMDguMTd2LjAycy4wOC4wOS4xMi4xM2wuMDIuMDJzLjA5LjA4LjE1LjExYzAgMCAuMDEgMCAuMDEuMDFsMy40OCAyLjAxYy4yNS4xNC41Ni4xNC44MSAwbDMuNDgtMi4wMWMuMjUtLjE0LjQtLjQxLjQtLjd2LTQuMDFhLjgxLjgxIDAgMCAwLS40LS43bC0zLjQ4LTIuMDFoLS4wMmMtLjA1LS4wNC0uMTEtLjA2LS4xNy0uMDhoLS4wM2EuNS41IDAgMCAwLS4xNy0uMDNoLS4wM2MtLjA2IDAtLjEyIDAtLjE4LjAyLS4wNy4wMi0uMTUuMDUtLjIxLjA4bC0xLjc0IDFjLS42Ny4zOS0xLjUuMzktMi4xNyAwYTIuMTkgMi4xOSAwIDAgMS0xLjA5LTEuODhjMC0uNzguNDItMS40OSAxLjA5LTEuODhaIiBzdHlsZT0iZmlsbDojNWRiZjlkIi8+PHBhdGggZD0ibS40IDEzLjExIDMuNDcgMi4wMWMuMjUuMTQuNTYuMTQuOCAwbDMuNDctMi4wMWguMDFsLjE1LS4xMi4wMi0uMDJzLjA3LS4wOS4xLS4xNGwuMDItLjAyYy4wMy0uMDUuMDUtLjExLjA3LS4xN3YtLjA0Yy4wMy0uMDYuMDMtLjEyLjAzLS4xOVYxMC40YzAtLjc4LjQyLTEuNDkgMS4wOS0xLjg4czEuNS0uMzkgMi4xOCAwbDEuNzQgMWMuMDcuMDQuMTQuMDcuMjEuMDguMDYuMDEuMTIuMDIuMTguMDJoLjAzYy4wNiAwIC4xMS0uMDEuMTctLjAyaC4wM2MuMDYtLjAyLjEyLS4wNC4xNy0uMDdoLjAybDMuNDctMi4wMmMuMjUtLjE0LjQtLjQxLjQtLjd2LTRhLjgxLjgxIDAgMCAwLS40LS43bC0zLjQ2LTJhLjgzLjgzIDAgMCAwLS44MSAwbC0zLjQ4IDIuMDFoLS4wMWwtLjE1LjEyLS4wMi4wMi0uMS4xMy0uMDIuMDJjLS4wMy4wNS0uMDUuMTEtLjA3LjE3di4wNGMtLjAzLjA2LS4wMy4xMi0uMDMuMTl2Mi4wMWMwIC43OC0uNDIgMS40OS0xLjA5IDEuODhzLTEuNS4zOS0yLjE4IDBsLTEuNzQtMWEuNi42IDAgMCAwLS4yMS0uMDhjLS4wNi0uMDEtLjEyLS4wMi0uMTgtLjAyaC0uMDNjLS4wNiAwLS4xMS4wMS0uMTcuMDJoLS4wM2MtLjA2LjAyLS4xMi4wNS0uMTcuMDhoLS4wMkwuNCA3LjcxYy0uMjUuMTQtLjQuNDEtLjQuNjl2NC4wMWMwIC4yOS4xNS41Ni40LjciIHN0eWxlPSJmaWxsOiM0NDY4YzQiLz48cGF0aCBkPSJtMTcuODQgMjQuNDgtMy40OC0yLjAxaC0uMDJjLS4wNS0uMDQtLjExLS4wNi0uMTctLjA4aC0uMDNhLjUuNSAwIDAgMC0uMTctLjAzaC0uMDNjLS4wNiAwLS4xMiAwLS4xOC4wMmgtLjA0Yy0uMDYuMDMtLjEyLjA1LS4xOC4wOGwtMS43NCAxYy0uNjcuMzktMS41LjM5LTIuMTggMGEyLjE5IDIuMTkgMCAwIDEtMS4wOS0xLjg4di0yLjAxYzAtLjA2IDAtLjEzLS4wMi0uMTl2LS4wNGMtLjAzLS4wNi0uMDUtLjExLS4wOC0uMTdsLS4wMi0uMDJzLS4wNi0uMDktLjEtLjEzTDguMjkgMTlzLS4wOS0uMDgtLjE1LS4xMWgtLjAxbC0zLjQ3LTIuMDJhLjgzLjgzIDAgMCAwLS44MSAwTC4zNyAxOC44OGEuODcuODcgMCAwIDAtLjM3LjcxdjQuMDFjMCAuMjkuMTUuNTUuNC43bDMuNDcgMi4wMWguMDJjLjA1LjA0LjExLjA2LjE3LjA4aC4wM2MuMDUuMDIuMTEuMDMuMTYuMDNoLjAzYy4wNiAwIC4xMiAwIC4xOC0uMDJoLjA0Yy4wNi0uMDMuMTItLjA1LjE4LS4wOGwxLjc0LTFjLjY3LS4zOSAxLjUtLjM5IDIuMTcgMHMxLjA5IDEuMTEgMS4wOSAxLjg4djIuMDFjMCAuMDcgMCAuMTMuMDIuMTl2LjA0Yy4wMy4wNi4wNS4xMS4wOC4xN2wuMDIuMDJzLjA2LjA5LjEuMTRsLjAyLjAycy4wOS4wOC4xNS4xMWguMDFsMy40OCAyLjAyYy4yNS4xNC41Ni4xNC44MSAwbDMuNDgtMi4wMWMuMjUtLjE0LjQtLjQxLjQtLjdWMjUuMmEuODEuODEgMCAwIDAtLjQtLjdaIiBzdHlsZT0iZmlsbDojNDI5M2Q5Ii8+PC9zdmc+ -[deepwiki-link]: https://deepwiki.com/CherryHQ/cherry-studio -[twitter-shield]: https://img.shields.io/badge/Twitter-CherryStudioApp-0088CC?logo=x -[twitter-link]: https://twitter.com/CherryStudioHQ -[discord-shield]: https://img.shields.io/badge/Discord-@CherryStudio-0088CC?logo=discord -[discord-link]: https://discord.gg/wez8HtpxqQ -[telegram-shield]: https://img.shields.io/badge/Telegram-@CherryStudioAI-0088CC?logo=telegram -[telegram-link]: https://t.me/CherryStudioAI - - - -[github-release-shield]: https://img.shields.io/github/v/release/CherryHQ/cherry-studio?logo=github -[github-release-link]: https://github.com/CherryHQ/cherry-studio/releases -[github-nightly-shield]: https://img.shields.io/github/actions/workflow/status/CherryHQ/cherry-studio/nightly-build.yml?label=nightly%20build&logo=github -[github-nightly-link]: https://github.com/CherryHQ/cherry-studio/actions/workflows/nightly-build.yml -[github-contributors-shield]: https://img.shields.io/github/contributors/CherryHQ/cherry-studio?logo=github -[github-contributors-link]: https://github.com/CherryHQ/cherry-studio/graphs/contributors - - - -[license-shield]: https://img.shields.io/badge/License-AGPLv3-important.svg?logo=gnu -[license-link]: https://www.gnu.org/licenses/agpl-3.0 -[commercial-shield]: https://img.shields.io/badge/License-Contact-white.svg?logoColor=white&logo=telegram&color=blue -[commercial-link]: mailto:license@cherry-ai.com?subject=Commercial%20License%20Inquiry -[sponsor-shield]: https://img.shields.io/badge/Sponsor-FF6699.svg?logo=githubsponsors&logoColor=white -[sponsor-link]: https://github.com/CherryHQ/cherry-studio/blob/main/docs/sponsor.md +The Boss name and logo identify this fork. Existing `@cherrystudio/*` package names, Cherry-operated services, and historical migration identifiers are technical contracts; their presence does not redirect this project's downloads, documentation, or support to upstream. diff --git a/docs/README.md b/docs/README.md index 391d48087a0..eca70824c8c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# Cherry Studio Documentation +# The Boss Documentation @@ -9,12 +9,13 @@ | [Contributing](../CONTRIBUTING.md) | How to contribute code | | [App Update Architecture](./contrib/app-upgrade.md) | How clients check for updates through the managed release service, with channels and the release history feed | | [🌿 Branching Strategy](./contrib/branching-strategy.md) | Branch model for contributions, pull request guidelines, and version tag management targeting main | -| [🖥️ Develop](./contrib/development.md) | Developer environment setup covering IDE configuration, Windows symlink support, and project install steps | +| [Develop The Boss](./contrib/development.md) | The Boss developer environment, pinned prerequisites, project setup, and UI team workflow | | [Feishu Notification Script](./contrib/feishu-notify.md) | CLI script that sends Feishu webhook card notifications from GitHub Actions workflows, with command reference | | [Linux Packaging](./contrib/linux-packaging.md) | Linux packaging flow using pinned better-sqlite3 prebuilds, with build commands and prebuild update steps | | [Release Workflow Operations](./contrib/release-workflow.md) | Maintainer runbook for preparing, validating, hotfixing, publishing, and synchronizing release branches | | [Test Plan](./contrib/test-plan.md) | The Test Plan process for beta and rc testing, covering user participation and maintainer PR workflow | -| [The Boss integration release](./contrib/the-boss-release.md) | Native integration payloads, installer publication, and installed Windows acceptance for The Boss | +| [The Boss integration release](./contrib/the-boss-release.md) | Native integration payloads, serialized publication, and installed acceptance for The Boss | +| [UI/UX routing and team adoption](./contrib/ui-ux-routing.md) | The Boss UI/UX catalog, project-team adoption, portable helpers, and completed-phase evidence limits | | [Upstream merge log](./contrib/upstream-merge-log.md) | Dated record of every upstream CherryHQ/cherry-studio merge into The Boss fork, plus open branding items carried between merges | | [Consuming upstream](./contrib/upstream-merges.md) | How this fork consumes upstream CherryHQ/cherry-studio releases without losing The Boss branding | diff --git a/docs/contrib/development.md b/docs/contrib/development.md index 4639b0687ee..bdbe5272988 100644 --- a/docs/contrib/development.md +++ b/docs/contrib/development.md @@ -1,8 +1,8 @@ --- -description: Developer environment setup covering IDE configuration, Windows symlink support, and project install steps +description: The Boss developer environment, pinned prerequisites, project setup, and UI team workflow --- -# 🖥️ Develop +# Develop The Boss ## IDE Setup @@ -123,3 +123,11 @@ $ pnpm build:linux For architecture-specific commands and the pinned `better-sqlite3` prebuild workflow, see [Linux Packaging](./linux-packaging.md). + +## UI/UX and project teams + +Follow [UI/UX routing and team adoption](./ui-ux-routing.md) for the current portable catalog and existing boss-core role bindings. Its Node 22+ helpers do not relax The Boss application engine and package-manager pins. Preserve shared design tokens and use the tracked Electron workflow for visible changes. Native role files are configuration, not proof of harness invocation. + +## Documentation + +Documentation is repository Markdown. Edit source headings and frontmatter, run `pnpm docs:index` to generate the index, then run `pnpm docs:check` once the documentation phase is complete. See [The Boss release workflow](./the-boss-release.md) for source-versus-installer evidence; the upstream release workflow is a separate process. diff --git a/docs/contrib/the-boss-release.md b/docs/contrib/the-boss-release.md index b47e19cc282..394eb7189ce 100644 --- a/docs/contrib/the-boss-release.md +++ b/docs/contrib/the-boss-release.md @@ -12,7 +12,7 @@ sources: - scripts/release-preflight.cjs - scripts/release-profile.cjs - scripts/update-release-entry.cjs - - src/renderer/pages/settings/PrometheusSettings/IntegrationSettings.tsx + - src/renderer/pages/settings/PrometheusSettings/IntegrationPage.tsx --- # The Boss integration release diff --git a/docs/contrib/ui-ux-routing.md b/docs/contrib/ui-ux-routing.md new file mode 100644 index 00000000000..19da62019f5 --- /dev/null +++ b/docs/contrib/ui-ux-routing.md @@ -0,0 +1,103 @@ +--- +description: The Boss UI/UX catalog, project-team adoption, portable helpers, and completed-phase evidence limits +sources: + - resources/skills/prometheus-ui-ux + - resources/skills/prometheus-ui-review + - resources/skills/ui-ux-pro-max + - scripts/sync-prometheus-skills.ts + - scripts/package-prometheus.js + - .agent-team/project-routing.json + - .agent-team/boss-core/skill-bindings.json + - src/main/services/prometheus/fullPackDetection.ts + - src/main/services/prometheus/pushSkills.ts +--- + +# UI/UX routing and team adoption + +This guide describes the merged source integration. It does not certify a published installer: the existing 2.2.2 binary predates this adoption. A future release must freeze its sources, package the payload, and complete the applicable installed acceptance in [The Boss release workflow](the-boss-release.md). + +## What is included + +The shared catalog has 41 entries. The Boss consumes mini's **40 portable entries** as part of **97 synchronized mini skills** in `resources/skills/`. The canonical mini source is the pinned `resources/prometheus-skills-mini` submodule; `pnpm skills:sync:prometheus` produces the tracked built-in copies. Packaging also carries the mini runtime closure. Do not hand-edit the built-in copies to diverge from that source. + +The workflow includes `prometheus-ui-ux`, `prometheus-ui-review`, `prometheus-impeccable-core`, Node-based UI/UX Pro Max search, selective taste/craft guidance, and platform instructions. Catalog inclusion records provenance and suitability, not proof that a skill is universally best. + +Mini's Impeccable core is a bounded workflow adaptation. The full-only native detector/live-browser engine is excluded; its proposed Node port is **not implemented or invocable**. See the [deferred engine design](../../resources/skills/prometheus-ui-ux/references/deferred-ports.md). Portable SwiftUI, Android, Flutter, and other platform guidance does not install SDKs or prove native execution. + +## Choose context and roles + +The [project routing record](../../.agent-team/project-routing.json) selects the existing `boss-core` team for code work. Read its [routing table](../../.agent-team/boss-core/routing.md), [skill bindings](../../.agent-team/boss-core/skill-bindings.json), and [design playbook](../../.agent-team/boss-core/design-playbook.md). + +| Work | Role and entry point | +| --- | --- | +| User-visible flow, design, accessibility | `boss-ux` → `resources/skills/prometheus-ui-ux/SKILL.md` | +| Renderer implementation | `boss-renderer` → the same router plus relevant React/Electron guidance | +| Completed UI acceptance | `boss-verifier` → `resources/skills/prometheus-ui-review/SKILL.md` in an independent context | +| Backend-only changes | Relevant existing specialist; no UI workflow preload | + +Ten role identities and their ownership are retained. Native definitions configure roles; they do not prove a harness invoked them. The lead assigns disjoint work; reviewers activate only after the complete implementation phase. When native delegation is unavailable, follow selected roles sequentially and disclose that builder-context inspection is not independent review. Zed's parallel-thread UI is not an automatic delegation API, and external ACP agents retain their native configuration. + +The operational desktop defaults to **Operate** mode. Read [DESIGN.md](../../DESIGN.md), [.impeccable.md](../../.impeccable.md), the [token system](../../packages/ui/docs/design-token-system.md), and the [variable catalog](../../packages/ui/docs/variable-catalog.md) before visible changes. Preserve `@cherrystudio/ui` components, semantic tokens, fonts, and the tracked `cherry-electron-dev` workflow. Pro Max recommendations do not replace project design authority. + +Refinement and review load no taste implementation. New surfaces or an explicitly authorized redesign may select one taste implementation and at most one requested overlay. `gpt-taste` requires an actual GPT-family model, not merely a particular harness. User-only `interface-review`, `break`, `variant`, and `explain-interface` remain user-invoked. + +## Use the portable helpers + +The helpers require Node.js 22+ and carry their runtime assets; no Python, native engine, extra daemon, or network service is needed. Developing The Boss itself requires the stricter [.node-version](../../.node-version) and [package.json](../../package.json) pins. Use the skill's actual installed directory when running outside this checkout. + +From this repository root, save a request such as `ui-request.json`: + +```json +{ + "project": ".", + "affected": ["src/renderer"], + "operation": "refine", + "surface": "app", + "focus": "layout", + "ui": true +} +``` + +```text +node resources/skills/prometheus-ui-ux/scripts/cli.mjs route --input ui-request.json +node resources/skills/ui-ux-pro-max/scripts/search.mjs "keyboard navigation React 19" --stack react --json +``` + +Read returned context files before the selected skills. Use focused search for refinement; generate a complete design-system recommendation only when establishing or explicitly replacing visual direction. Missing skills or tooling are gaps, not silently downloaded dependencies. Pro Max persistence writes its own `design-system/` output and preserves existing master/page decisions unless replacement is authorized; it does not overwrite `DESIGN.md`. + +## Installation is separate from export + +The UI bootstrap/injector installs the portable catalog and routing instructions. Existing-team adoption is a separate creator operation. For an explicitly selected project, preview both before applying: + +```text +node resources/skills/prometheus-ui-ux/scripts/cli.mjs install --project "" --dry-run +node .agents/skills/agent-team-creator/scripts/cli.mjs install-project --project "" --team boss-core --dry-run +``` + +Use `boss-core` only for a project containing that team; otherwise select the project's actual team. Omit `--dry-run` to apply an authorized installation; use `--check` to inspect drift without writes. Installation preserves project protocol overrides, unrelated instructions, and existing native configuration. Read its result and the project's `.agent-team/project-routing.json` rather than assuming every harness discovers identical files. + +Creator **export** produces artifacts for inspection and deliberate merging; it does not install or activate a project team. Do not rerun initialization to overwrite live team state. The UI-only installer does not perform Zed team adoption; creator's `install-project` owns that operation and records effective instruction files. + +The Boss application keeps its mini runtime in application data. Existing full-pack detection and refusal to push mini into native skill roots when a full pack is present remain unchanged: the full pack is authoritative and must not be shadowed. Repository synchronization, project installation, and application-to-native skill pushing are distinct operations. See [pushSkills.ts](../../src/main/services/prometheus/pushSkills.ts) and [fullPackDetection.ts](../../src/main/services/prometheus/fullPackDetection.ts). + +## Complete the phase, then gather evidence + +After the complete authorized UI implementation, change the request's operation to `review` and run: + +```text +node resources/skills/prometheus-ui-ux/scripts/cli.mjs phase-boundary --input ui-request.json +``` + +This returns an evidence contract with `status: "evidence-required"` and `executed: false`. It accepts no evidence payload, launches no browser, runs no checks, and cannot certify PASS. + +Use a verified tracked Electron instance for applicable window widths, light/dark states, real content, keyboard/focus, loading/empty/error/disabled states, overflow, and reduced motion. Keep credentials out of captures. The independent reviewer records PASS/BLOCK against actual evidence with scoped findings and unavailable checks. Allow one batched correction/confirmation cycle; outstanding blockers remain blocking. Screenshots do not substitute for native screen-reader or installed Windows evidence. + +## Recorded evidence and remaining gaps + +The [packaged-helper receipt](../../.agent-team/boss-core/ui-routing-packaged-evidence.json) records a macOS offline materialization and helper run with 40 portable skills, preserving 50 native definitions and ten role ownership records. The [pin/sync receipt](../../.agent-team/boss-core/ui-routing-pin-sync-evidence.json) records synchronization and unchanged anti-shadowing implementation. These are source/payload evidence, not installer or Electron acceptance. + +The [mini delivery record](../../resources/prometheus-skills-mini/docs/research/ui-ux-routing/DELIVERY.md) separates macOS/Linux helper evidence and independent skill-contract review from release gaps. Native Windows execution, live invocation across every supported harness, and a full installed Electron run remain unverified for this adoption. The prior Boss repository lint stopped on bundled creator diagnostics; later pipeline stages were not proved. No rendered product UI changed in the routing implementation, so its receipt has no product screenshot acceptance claim. + +## Documentation surface + +The Boss documentation is repository Markdown, linked from [docs/README.md](../README.md). There is no local Docusaurus site in this repository. The inherited documentation-dispatch workflow points to the upstream docs repository and is not evidence of a deployed Boss documentation site. Edit source headings/frontmatter, generate the index with `pnpm docs:index`, then run `pnpm docs:check` at the completed documentation boundary. diff --git a/docs/references/components/README.md b/docs/references/components/README.md index 6ff77196eaa..2f9330fd4d8 100644 --- a/docs/references/components/README.md +++ b/docs/references/components/README.md @@ -18,3 +18,5 @@ workbench and its Python execution path, the diagram preview family, and the | [Code Execution](./code-execution.md) | In-browser Python execution via Pyodide in a Web Worker: UI, service, and worker layers | | [Image Preview Components](./image-preview.md) | Shared Mermaid / PlantUML / SVG / Graphviz preview components, toolbar, and the `useDebouncedRender` hook | | [UI Semantic Contract](./ui-semantic-contract.md) | The `data-ui` selector contract for themes, tests, and automation, and its build-time generation pipeline | + +For contributors changing these surfaces, start with [UI/UX routing and team adoption](../../contrib/ui-ux-routing.md). It connects the existing design tokens and Electron workflow to the shared router and completed-phase review. diff --git a/scripts/gen-doc-index.ts b/scripts/gen-doc-index.ts index 31ad240e9ad..a9aa2dc255a 100644 --- a/scripts/gen-doc-index.ts +++ b/scripts/gen-doc-index.ts @@ -54,7 +54,7 @@ const domainOrder = (domainDir: string, files: string[]): string[] => { export const generateIndex = (repoRoot: string): string => { const docsDir = path.join(repoRoot, 'docs') const lines: string[] = [ - '# Cherry Studio Documentation', + '# The Boss Documentation', '', '', '',