README.md

Synergy Documentation

This documentation describes the current Synergy product and implementation. Code remains the authority when behavior changes; documentation should state the supported current model directly and keep historical narratives inside dedicated migration or research material.

Start Here

Reader or task	Start with
Understand the product	Product overview
Install or operate Synergy	CLI reference and configuration reference
Understand the runtime	Architecture overview
Contribute to the repository	Development reference and CONTRIBUTING.md
Change frontend colors or themes	Frontend themes and color
Build a plugin	Plugin documentation
Modify Synergy with an AI agent	AGENTS.md

Product

Product documents explain what users work with and how the major capabilities relate.

• Product overview — positioning, product objects, surfaces, and durable principles
• Workspaces and sessions — Scope, projects, sessions, agents, tools, history, and Browser ownership
• Agents, tools, skills, and commands — catalogs, external agents, exposure, customization, and ACP
• Workflows — direct work, Plan, Blueprints, BlueprintLoop, Light Loop, Boss Mode, Lattice, delegation, and compaction
• Knowledge — Library memories and experiences, Notes, Blueprints, recall, and search
• Activity and statistics — usage, tokens, costs, agents, tools, code changes, trends, and derived-data freshness
• Automation — Agenda triggers, session modes, delivery, recovery, and failure behavior
• Connections — providers, MCP, Channels, Email, Holos, and plugins
• Browser workspace — Desktop pages, persistent identities, permissions and recovery
• Web product contract — durable interaction, visual, and accessibility rules

Architecture

Architecture documents define current invariants, ownership boundaries, and the flows maintainers must preserve.

• Architecture overview
• Runtime and Scope
• Agent storage
• Workspace and files
• Environments
• Sessions and messages
• LLM loop and compaction
• Usage accounting
• Frontend data sync
• Interactive visual results
• Frontend plugin platform
• Frontend localization
• Channels
• Execution boundaries
• Cortex and delegated work
• Workflow engine
• Browser runtime
• Native Computer Use

Reference

Reference documents answer exact operational and repository questions without repeating the product narrative.

• Configuration layout — domain file layout and semantics guide
• Configuration — generated field-level reference
• CLI guide — concept and lifecycle guide
• CLI — generated command reference
• Tools — generated tool catalog
• Skills
• Storage and paths
• Package map
• Installable packages — optional mechanisms, company presets and host components
• Embedding — Bun embedding, managed Node.js processes and runtime capabilities
• Development
• Local performance experiments
• Frontend themes and color

Plugins

The plugin documentation covers the external authoring surface and the runtime's extension trust model:

• getting started and development kit
• manifest and contribution reference
• generated manifests, capabilities, runtime generations, trust, and approval
• tools, agents, commands, MCP, and product UI contributions
• validation, signing, packaging, marketplace publishing, and security

Historical plugin upgrade instructions live under migrations, outside the current authoring contract.

The package-level SDK reference remains in packages/plugin.

Operations

• Operations index
• Open-source quality — local checks, CI, package validation, and contributor scenarios
• Desktop release — packaging, signing, publishing, updating, and recovery
• Performance observability — metrics, traces, storage, APIs, and performance tooling

Research and Migration History

Research documents record investigations and measurements; they are not current product contracts. Migration documents explain historical state transitions only when that history remains operationally useful.

• Research index
• Migration history

Documentation Ownership

• README.md is the concise repository and product entry point.
• docs/product/ owns user-facing concepts and flows.
• apps/web/PRODUCT.md owns durable Web interaction and visual principles.
• docs/architecture/ owns implementation invariants and subsystem boundaries.
• docs/reference/ owns exact commands, configuration, Skills, paths, packages, and development procedures.
• docs/plugins/ owns the public plugin platform documentation.
• docs/operations/ owns release, quality, and observability runbooks.
• docs/research/ and docs/migrations/ are the only homes for investigation and historical narratives.
• AGENTS.md files contain repository rules for coding agents rather than general product explanation.
• .synergy/skill/ contains executable repository workflows and links to the canonical documents above.