llms.txt

# Synergy

> Synergy is an open-source AI agent workspace built as a Bun and TypeScript monorepo. This file routes LLMs and external coding agents to the current documentation; implementation, schemas, generated contracts, and tests remain authoritative.

## Start Here

- [README.md](README.md): concise product, installation, source-development, and SII project overview.
- [docs/README.md](docs/README.md): canonical documentation index and ownership map.
- [docs/product/overview.md](docs/product/overview.md): product objects, surfaces, workflows, connections, and durable principles.
- [AGENTS.md](AGENTS.md): repository rules for coding agents and contributors.
- [CONTRIBUTING.md](CONTRIBUTING.md): contribution and pull-request workflow.

## Understand the Product

- [Workspaces and sessions](docs/product/workspaces-and-sessions.md): Scope, projects, sessions, history, files, and Browser ownership.
- [Agents, tools, skills, and commands](docs/product/agents-and-tools.md): built-in, configured, plugin, and external agents; exposure and ACP.
- [Workflows](docs/product/workflows.md): direct work, Plan, Blueprints, BlueprintLoop, Light Loop, Lattice, delegation, and compaction.
- [Knowledge](docs/product/knowledge.md): Library, Memory, Experience, Notes, Blueprints, recall, and search.
- [Activity and statistics](docs/product/activity-and-statistics.md): session, token, cost, model, agent, tool, code-change, and time-series summaries.
- [Automation](docs/product/automation.md): Agenda schedules, session modes, delivery, recovery, and failure behavior.
- [Connections](docs/product/connections.md): providers, MCP, Channels, Email, Holos, and Synergy Link.
- [Browser workspace](docs/product/browser.md): shared human/agent page, native and Web presentations, private-network HTTP support, and safety boundaries.

## Understand the Runtime

- [Architecture overview](docs/architecture/README.md): ownership and cross-cutting runtime flow.
- [Runtime and Scope](docs/architecture/runtime-and-scope.md): stateless server, global runtime, Scope resolution, and client context.
- [Workspace and files](docs/architecture/workspace-and-files.md): workspace ownership, search, anchored file tools, formatting, LSP, and snapshots.
- [Sessions and messages](docs/architecture/session-and-messages.md): canonical message semantics, inbox modes, task grouping, persistence, history, and attachments.
- [LLM loop and compaction](docs/architecture/llm-loop.md): serial task loop, context construction, model calls, tools, retries, and compaction.
- [Frontend data sync](docs/architecture/frontend-data-sync.md): reconcile writes, sequence/epoch events, replay, streaming, and eviction.
- [Channels](docs/architecture/channels.md): targets, provider lifecycle, managed Projects, task routing, borrowed transports, diagnostics, and navigation projection.
- [Execution boundaries](docs/architecture/execution-boundaries.md): taxonomy, control profiles, permission enforcement, sandboxing, and worktree isolation.
- [Cortex](docs/architecture/cortex.md): delegated child sessions, task lifecycle, outputs, and parent notification.
- [Workflow engine](docs/architecture/workflows.md): Plan, BlueprintLoop, Light Loop, Lattice, and SuperPlan storage substrate.
- [Browser runtime](docs/architecture/browser-runtime.md): one-session/one-page ownership, Electron native mode, WebRTC mode, and input lifecycle.
- [Frontend localization](docs/architecture/localization.md): locale ownership, catalogs, message IDs, formatting, translation boundaries, and verification.

## Exact Reference

- [CLI](docs/reference/cli.md): installed product CLI and source-development distinction.
- [Configuration](docs/reference/configuration.md): global/project domain files, merge order, discovery, and credentials.
- [Storage and paths](docs/reference/storage-and-paths.md): `SYNERGY_HOME`, durable data, indexes, auth, Browser, worktrees, and backup.
- [Package map](docs/reference/packages.md): current monorepo package responsibilities and dependency boundaries.
- [Development](docs/reference/development.md): source modes, isolated second instance, builds, SDK generation, and tests.

## Build a Plugin

Use `@ericsanchezok/synergy-plugin-kit` and the public `@ericsanchezok/synergy-plugin` SDK. A Synergy source checkout is not required for normal plugin development.

- [Plugin documentation](docs/plugins/README.md): platform overview and canonical index.
- [Getting started](docs/plugins/getting-started.md): create, develop, validate, build, test, sign, pack, install, and publish.
- [Generated manifest](docs/plugins/manifest.md): build-produced `plugin.json`, contribution declarations, artifacts, and handler matching.
- [Runtime and capabilities](docs/plugins/runtime-and-permissions.md): approval, generations, scoped Host Services, operations, events, hooks, and lifecycle.
- [Tools and delegation](docs/plugins/tools-and-delegation.md): public runtime tools, helpers, delegated tasks, attachments, and display metadata.
- [UI contributions](docs/plugins/ui-contributions.md): renderers, workbench surfaces, settings, slots, themes, icons, and commands.
- [Marketplace](docs/plugins/marketplace.md): official/local registries, signing, publishing, installation, and update flow.
- [Security](docs/plugins/security.md): review checklist for authors, reviewers, and distributors.
- [Plugin SDK reference](packages/plugin/README.md): public TypeScript API reference and examples.

## Operate and Release

- [Operations index](docs/operations/README.md): current operational runbooks.
- [Open-source quality](docs/operations/open-source-quality.md): local gates, CI matrix, package validation, and contributor scenarios.
- [Desktop release](docs/operations/desktop-release.md): packaging, signing, publishing, updates, and recovery.
- [Performance observability](docs/operations/performance-observability.md): metrics, traces, diagnostics, storage, and tooling.

## History and Investigation

- [Research](docs/research/README.md): measurements and investigations that are not current product contracts.
- [Migrations](docs/migrations/README.md): historical transitions whose upgrade context remains useful.

## Repository Workflows

The project-local `.synergy/skill/` files are executable workflows for this repository. Load the relevant workflow instead of copying architecture facts into an agent prompt:

- `architecture`, `develop-synergy`, `testing-guide`, `develop-benchmark`, and `git-guide`
- `development-standards`, `develop-frontend`, and `integrate-llm`
- `change-server-api` and `change-persistence`
- `change-execution-boundaries`, `change-channel-runtime`, `change-browser-runtime`, and `change-plugin-runtime`
- `add-agent`, `add-cli-command`, and `add-tool`
- `find-logs`, `inspect-sessions`, `find-simplifications`, `release-log-workflow`, and `report-bug`

Use `Scope` for workspace resolution/context and `Library` for the knowledge subsystem. Current built-in primary agents are `synergy` and `synergy-max`; retired terminology belongs only in migration or research material.