DOCS / 01

Getting started

Three steps, assuming Node 20+, pnpm 10.33.4, Rust stable, and Postgres (or docker compose up -d postgres).

QUICK START · POWERSHELL

# 1. install
git clone <repo-url> orcyx && cd orcyx
pnpm install
# 2. provision the backend + issue yourself a token (prints once)
pnpm db:push:bridgespace
pnpm --filter bridgespace-api token:create --label "dev-laptop"
# 3. run — API in one shell, app in another
pnpm --filter bridgespace-api dev
pnpm --filter bridgespace dev

On first launch, paste the bspc_* token from step 2 into the onboarding screen. It's stored in the OS keyring from then on.

Requirements

Node 20 LTS+ · pnpm 10.33.4
Rust 1.78+ stable · Postgres 15+
Tauri platform prerequisites

Windows note

Install VS Build Tools (Desktop C++) + Windows SDK. WSL2 works for the backend; the Tauri build runs on the host.

DOCS / 02

Architecture

Renderer

React 18 · TypeScript · Vite · Tailwind

Desktop core

Tauri 2 · portable-pty · notify · tracing

MCP

rmcp SDK · 12 Vault tools · per-tool ACL

Backend

Fastify · Prisma · Postgres

Auth

Bearer token in OS keyring — never the webview

Architecture decision records

ADR-0001

Tauri shell over Electron

ADR-0002

Zustand for state

ADR-0003

In-process MCP server

ADR-0004

Swarm coordinator model

ADR-0005

Markdown files for the Vault

ADR-0006

Defer code signing to Phase 18

DOCS / 03

Changelog

Keep-a-Changelog format, semantic versioning. Highlights from the current hardening sprint (audit-sprint-1, unreleased):

PHASE 10 · IDE + BROWSER

Multi-file Composer with diff review; per-hunk Apply / Reject; embedded browser inspect-chat dock.

PHASE 9 · SWARM COORDINATOR

Reference-based topology — pointers into the Vault instead of re-stated payloads; outbound body compaction.

PHASE 8 · MCP SERVER

Vector-backed memory.search; per-tool ACL on every handler; inbound rate limiting.

PHASE 6 · VOICE + MULTIMODAL

Mic dictation in the agent textarea; image paste/drop; device picker; 16k mono capture with noise/echo/AGC.

PHASE 4 · PERFORMANCE

Pane-scoped PTY channels; lazy-loaded routes; xterm WebGL renderer; Vite chunk splitting for Monaco and transformers.

PHASE 2 · DURABILITY

Atomic fsync writes; soft-delete trash with restore + TTL; snapshot ring buffer for the Vault; corruption RestoreWizard.

DOCS / 04

Security

Do not open a public issue for vulnerabilities. Email the maintainers privately — responsible disclosure is coordinated with the reporter and credited.

3 days

ACKNOWLEDGEMENT

7 days

INITIAL TRIAGE

30 days

FIX · HIGH / CRITICAL

In scope: the desktop app, the Rust core including the IPC command surface and the in-process MCP server. Until code signing ships (Phase 18), only the latest commit on main and audit-sprint-1 is supported.

DOCS / 05

Contributing

The contributing guide is the contract — read it before opening a PR. If it's wrong or out of date, fix it in the same PR as your code change.

Conventions

Conventional commits enforced via commitlint + husky. ESLint, Prettier, EditorConfig baseline. PR template + CODEOWNERS.

Design rules

Tokens, not hex values. Utility classes for surfaces. Canonical easings. Reduced motion respected. New interactive components need an axe-clean test.

DEV LOOP

pnpm dev # every workspace in parallel
pnpm --filter bridgespace dev # desktop app only
pnpm --filter bridgespace-api dev # backend only

DOCS / 06

Code of conduct

The project ships a standard contributor code of conduct: be direct, be respectful, assume good faith. Enforcement questions and reports go to the maintainers privately — the same channel as security disclosures.