Developing Synapse

Build, test, document, and publish each Synapse surface from its own workspace.

The website, terminal bridge, core engine, native window, and optional sync server have separate checks. Run the gates for every surface a change touches.

Repository map

Path	What lives here
`crates/synapsecore`	Library, CLI, terminal dashboard, MCP, memory, credentials, mesh, skills, setup, imports
`crates/synapse`	Native desktop window over core
`crates/synapsesync`	Shared encrypted sync wire types
`crates/synapseserve`	Optional opaque sync log server
`pi`	Terminal bridge package embedded by the core build
`website`	Static site templates, styles, browser behavior, and manual content
`docs`	Technical documentation, rendered into the public manual
`site`	Generated site, committed for GitHub Pages

The root, core, and server are independent Cargo workspaces. Core and server must resolve without the desktop dependency graph. The desktop pins its released UI dependency exactly. Desktop and core versions must agree.

Build and test

From the repository root:

cargo build --locked
cargo test --locked
cargo fmt --check
cargo test --locked --manifest-path crates/synapsecore/Cargo.toml
cargo check --locked --manifest-path crates/synapsecore/Cargo.toml --no-default-features
cargo test --locked --manifest-path crates/synapsecore/Cargo.toml --test cli --test mcp
cargo test --locked --manifest-path crates/synapseserve/Cargo.toml

For the terminal bridge:

cd pi
bun install
bun run check

See Windows for the installer toolchain and platform smoke check.

Work on the website

Use Bun 1.4.3 or later. Technical Markdown uses Bun's built-in renderer; the site has no package dependency or runtime service. Build before starting the preview:

bun run site
bun run sitecheck
bun run serve

Open http://127.0.0.1:4173/synapse/. The prefix matters: GitHub Pages publishes under /synapse/, and every local link and asset must work from nested routes. Rebuild after source changes. PORT changes the preview port.

website/home.ts owns the landing page.
website/template.ts owns the shared frame, navigation, and article layout.
website/navigation.ts groups the manual.
website/docs and website/tutorials hold task and reference pages.
Every Markdown file under docs becomes a searchable manual page automatically.
website/technical.ts adds titles, source links, code controls, and contents.
website/deploy.ts is the source for canonical and release URLs. The displayed release version comes from the desktop manifest.

The checker verifies local links and fragments, metadata, landmarks, navigation coverage, command coverage, search indexing, and documentation sources. Inspect both desktop and mobile in a browser as well: source checks cannot verify layout, keyboard navigation, search interaction, or clipboard behavior.

Commit source and regenerated site together. The Pages workflow builds and checks again on main, then publishes the artifact. Confirm the workflow and the live page after pushing.

Documentation boundaries

Document released behavior as released behavior. Label proposals and snapshots explicitly. Do not turn a library module into a promised CLI setup flow, or a performance fixture into a product-wide benchmark.

The core library, Embedding, Retrieval checks, The memory map, What launching costs, and Encrypted sync describe the implementation and its checks. The Federation proposal is a design record and does not establish available commands.

Contributions

Public command, MCP, descriptor, and storage surfaces are compatibility promises. Preserve user-owned configuration and instructions. Managed writes need backups, atomic replacement, and selective removal. Memory corrections retain a restore path; proposed skills reach no tool before approval. Keep credential values out of memory, scope YAML, protocol responses, logs, and command arguments.

For a tool connector, add a descriptor rather than extending a closed product enum. Include detection, connection, repair, and selective cleanup checks. Update the supported-tool table and the manual with the platforms actually tested.