electric-sql · balegas · Jul 23, 2026 · Jul 23, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for your interest in Electric Circuits. Issues and pull requests are welcome.
+
+## Getting started
+
+Read the [README](README.md) for what the project is, and [AGENTS.md](AGENTS.md) for the
+repository layout, the docs index, and the invariants the engine must hold. The docs it points
+to (`docs/ARCHITECTURE.md`, `docs/ivm-engine-internals.md`) explain the design; read them
+before changing the engine.
+
+## Build and test
+
+You need Node 20+, pnpm, Rust (pinned by `rust-toolchain.toml`), and Docker (for Postgres).
+
+```bash
+pnpm install
+pnpm engine:test                               # Rust unit + integration (fast)
+ELECTRIC_CIRCUITS_ENGINE_PREBUILT=1 pnpm test  # full vitest suite incl. oracle conformance
+```
+
+A change that touches the engine must pass both suites. The full runbook — conformance against
+Electric's own oracle, the demo stack, the visualizer — is in the "Build & test" and "Testing
+checklist" sections of AGENTS.md.
+
+## Pull requests
+
+- Keep each PR to one change; small PRs merge faster.
+- Say what the change does and why; link the issue if one exists.
+- Add or extend tests for behavior you change — the conformance suite is the safety net, but
+  regressions should be caught closer to the code.
+
+## License
+
+This project is dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE).
+Unless you state otherwise, any contribution you submit is licensed under the same terms,
+with no additional conditions.
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,5 @@
+# Security Policy
+
+If you find a vulnerability, do not open a public issue. Email
+[balegas@electric-sql.com](mailto:balegas@electric-sql.com) with a description and, if you can,
+steps to reproduce. You will get a reply within a few days.
diff --git a/apps/api/package.json b/apps/api/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/api",
+  "description": "The extended tRPC API server — the surface @electric-circuits/client talks to, sitting beside the engine's Electric-protocol endpoint.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/apps/engine/Cargo.toml b/apps/engine/Cargo.toml
@@ -1,5 +1,6 @@
 [package]
 name = "electric-circuits-engine"
+description = "The Electric Circuits engine: ingests Postgres logical replication and keeps live queries (joins, aggregates, subqueries) incrementally in sync via dbsp circuits, serving the Electric wire protocol."
 edition.workspace = true
 version.workspace = true
 license.workspace = true

diff --git a/apps/pipeline-viz/package.json b/apps/pipeline-viz/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/pipeline-viz",
+  "description": "Web GUI attached to a running engine that visualizes the dbsp pipeline it is executing, live.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/package.json b/package.json
@@ -1,5 +1,6 @@
 {
   "name": "electric-circuits",
+  "description": "Monorepo for Electric Circuits — live queries for Postgres: a Rust engine ingests logical replication and keeps every query result (joins, aggregates, subqueries) in sync, speaking the Electric protocol plus an extended API.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/bench/package.json b/packages/bench/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/bench",
+  "description": "Benchmark and measurement tooling — every runner boots the full stack (Postgres, engine, durable-streams) and measures it end to end.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/client/package.json b/packages/client/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/client",
+  "description": "Browser/Node client for the extended electric-circuits API: a typed tRPC client adding subset queries and live aggregations on top of the Electric client.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/conformance/package.json b/packages/conformance/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/conformance",
+  "description": "End-to-end conformance suite: asserts the real stack (Postgres, engine, wire protocol) agrees with the oracle on every shape.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/ds-rust/package.json b/packages/ds-rust/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/ds-rust",
+  "description": "Drop-in replacement for @durable-streams/server's test server, backed by the native Rust durable-streams binary.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/loadgen/package.json b/packages/loadgen/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/loadgen",
+  "description": "Headless load generator that simulates LinearLite users to observe engine behavior and cost under realistic load.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/oracle/package.json b/packages/oracle/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/oracle",
+  "description": "Reference implementation of shape semantics that the conformance suite compares the real system against.",
   "version": "0.0.0",
   "private": true,
   "type": "module",

diff --git a/packages/protocol/package.json b/packages/protocol/package.json
@@ -1,5 +1,6 @@
 {
   "name": "@electric-circuits/protocol",
+  "description": "The shared contract: JSON types, predicate and SQL compilers used by the TS packages and mirrored by the Rust engine.",
   "version": "0.0.0",
   "private": true,
   "type": "module",