|
1 | 1 | # Springtale |
2 | 2 |
|
3 | | -Local-first, privacy-preserving automation platform built for people whose |
4 | | -safety depends on privacy. Rust workspace. Connector infrastructure first, |
5 | | -AI consumer second. |
| 3 | +Local-first, privacy-preserving automation platform for people whose |
| 4 | +safety depends on privacy. Bots are the primary unit — connector |
| 5 | +infrastructure first, AI consumer second. Everything works without AI. |
6 | 6 |
|
7 | 7 | **Target users:** Trans people, POC, activists, IPV survivors, immigrants — |
8 | 8 | people facing real surveillance, doxxing, deplatforming, and harassment. |
9 | | -Every decision evaluated from the perspective of the most vulnerable user. |
10 | 9 |
|
11 | 10 | ## Build & Test |
12 | 11 |
|
13 | 12 | ```bash |
14 | 13 | cargo build --workspace # build all |
15 | 14 | cargo test --workspace # test all |
16 | | -cargo clippy --workspace --all-targets -- -D warnings # lint (warnings = errors) |
| 15 | +cargo clippy --workspace --all-targets -- -D warnings # lint |
17 | 16 | cargo fmt --check # format check |
18 | 17 | cargo nextest run --workspace # fast test runner (preferred) |
| 18 | +cd tauri && pnpm build # frontend build |
| 19 | +cd tauri/apps/desktop && pnpm tauri dev # desktop dev |
| 20 | +cd tauri/apps/dashboard && pnpm dev # web dashboard dev |
19 | 21 | ``` |
20 | 22 |
|
21 | | -## Architecture (read before writing code) |
| 23 | +## Product Model — read first |
| 24 | + |
| 25 | +**@.claude/rules/shared/product-model.md** — the bot-first model, how settings |
| 26 | +are scoped (app → formation → bot), the colony UI vision, what not to do. |
| 27 | + |
| 28 | +## Architecture |
22 | 29 |
|
23 | 30 | **Use `current-arch` — it supersedes `intended-arch` where they differ.** |
24 | 31 |
|
25 | 32 | - Full architecture: `docs/current-arch/ARCHITECTURE.md` |
26 | 33 | - Security model: `docs/current-arch/SECURITY.md` |
27 | | -- Rekindle P2P spec: `docs/current-arch/rekindle-architecture.md` |
28 | | -- Audit findings: `docs/current-arch/AUDIT-NOTES.md` |
29 | | -- Change log: `docs/current-arch/CHANGELOG.md` |
30 | | - |
31 | | -Original (pre-audit) docs preserved in `docs/intended-arch/` for reference. |
32 | | - |
33 | | -## Phase Roadmap — know what phase you're building |
34 | | - |
35 | | -- **Phase 1a**: Framework + Connectors (springtaled, CLI, SQLite, LocalTransport, NoopAdapter, 7 connectors) |
36 | | -- **Phase 1b**: Bot Foundations (springtale-bot, classical command routing, connector-telegram) |
37 | | -- **Phase 2a**: OpenClaw Parity (HttpTransport, AI adapters, sentinel, chat connectors, recursive pipelines) |
38 | | -- **Phase 2b**: Desktop + Mobile + Safety (Tauri 2, duress/panic, travel mode, app disguise, accessibility) |
39 | | -- **Phase 3**: Veilid Mesh (VeilidTransport via rekindle-protocol, distributed registry) |
40 | | - |
41 | | -**Do not build Phase N+1 features while implementing Phase N.** |
42 | | -Stubs and trait definitions for future phases are fine. Implementations are not. |
| 34 | +- Colony v8 visual reference: `docs/intended-arch/springtale-colony-v8.html` |
| 35 | +- Cooperation framework: `docs/intended-arch/COOPERATION.pdf` |
43 | 36 |
|
44 | 37 | ## Core Constraints (non-negotiable) |
45 | 38 |
|
46 | | -1. **Security and privacy are constraints, not features.** Every decision evaluated against threat model (§2.1-2.9). |
47 | | -2. **Built for the most vulnerable user.** Default-safe. Metadata-leaking features off by default. Zero telemetry. |
48 | | -3. **`NoopAdapter` must work.** The entire platform operates correctly without any AI plugged in. |
49 | | -4. **Secrets are types.** All sensitive values wrapped in `Secret<T>` from `secrecy`. Memory zeroed on drop via `zeroize`. |
50 | | -5. **No native-tls.** `rustls-tls` exclusively. `native-tls` banned via Cargo.toml patch. |
51 | | -6. **Modules over inline.** All functions, types, error variants in named modules. No free-floating impl blocks at crate root. |
| 39 | +1. **Security and privacy are constraints, not features.** Every decision evaluated against threat model. |
| 40 | +2. **Built for the most vulnerable user.** Default-safe. Zero telemetry. |
| 41 | +3. **`NoopAdapter` must work.** The entire platform operates without any AI plugged in. |
| 42 | +4. **Secrets are types.** All sensitive values wrapped in `Secret<T>` from `secrecy`. |
| 43 | +5. **No native-tls.** `rustls-tls` exclusively. |
| 44 | +6. **Modules over inline.** All functions, types, error variants in named modules. |
52 | 45 | 7. **Connectors are untrusted.** WASM sandbox, manifest signing, capability allow-list. |
53 | | -8. **Transport is swappable.** All inter-node comms through `Transport` trait. No concrete transport escapes the module. |
| 46 | +8. **Transport is swappable.** All inter-node comms through `Transport` trait. |
54 | 47 |
|
55 | 48 | ## Workspace Structure |
56 | 49 |
|
57 | | -- `crates/` — Pure Rust library crates (no Tauri dependency) |
58 | | -- `connectors/` — First-party connector crates |
59 | | -- `apps/` — springtaled (daemon) + springtale-cli |
60 | | -- `tauri/` — Desktop shell (Phase 2b) |
61 | | -- `sdk/` — TypeScript connector SDK (jco componentize → wasm32-wasip2) |
| 50 | +``` |
| 51 | +crates/ — Pure Rust library crates (no Tauri dependency) |
| 52 | +connectors/ — First-party connector crates |
| 53 | +apps/ — springtaled (daemon) + springtale-cli |
| 54 | +tauri/ — Desktop shell + web dashboard (SolidJS + Tailwind) |
| 55 | +sdk/ — TypeScript connector SDK |
| 56 | +docs/ — Architecture, security, design references |
| 57 | +``` |
62 | 58 |
|
63 | 59 | ## Dependency Rules |
64 | 60 |
|
65 | | -- All version pins at workspace root `Cargo.toml`. No crate specifies its own version for shared deps. |
66 | | -- Bounded version ranges only (e.g., `"42"` not `">=42.0.0"`). No unbounded `>=` pins. |
67 | | -- `thiserror` for library error types. `anyhow` only in app binaries. Transport trait uses `TransportError`. |
68 | | -- `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]` in all library crates. |
69 | | -- `#![forbid(unsafe_code)]` on all crates except `springtale-crypto` and `springtale-connector` (audited unsafe only). |
| 61 | +- All version pins at workspace root `Cargo.toml`. |
| 62 | +- `thiserror` for library errors. `anyhow` only in app binaries. |
| 63 | +- `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]` in library crates. |
| 64 | +- `#![forbid(unsafe_code)]` except `springtale-crypto` and `springtale-connector`. |
70 | 65 |
|
71 | 66 | ## Competitive Context |
72 | 67 |
|
73 | | -- **Phase 1a obsoletes NosytLabs' approach** — framework makes ad-hoc unsandboxed MCP servers obsolete. |
74 | | -- **Phase 2a obsoletes OpenClaw** — 250K+ stars but 800+ malicious skills in ClawHub, CVE-2026-25253 RCE, no sandboxing. |
75 | | -- **Phase 3 adds what no centralized platform can match** — E2E encrypted P2P AI chat via Veilid, no server, no phone number. |
| 68 | +- **Obsoletes OpenClaw** — 250K+ stars but 800+ malicious skills, CVE-2026-25253 RCE, no sandboxing. |
| 69 | +- **Obsoletes NosytLabs** — framework makes ad-hoc unsandboxed MCP servers obsolete. |
| 70 | +- **Phase 3 adds P2P** — E2E encrypted AI chat via Veilid, no server, no phone number. |
| 71 | + |
| 72 | +## Rules |
| 73 | + |
| 74 | +Rules are organized by domain and path-scoped: |
| 75 | + |
| 76 | +- `.claude/rules/backend/` — Rust conventions, security, crate structure, connectors, testing |
| 77 | +- `.claude/rules/frontend/` — SolidJS conventions, Tauri integration |
| 78 | +- `.claude/rules/shared/` — Product model, git workflow |
76 | 79 |
|
77 | | -@.claude/rules/rust-conventions.md |
78 | | -@.claude/rules/security.md |
79 | | -@.claude/rules/crate-structure.md |
80 | | -@.claude/rules/connector-guidelines.md |
81 | | -@.claude/rules/testing.md |
| 80 | +@.claude/rules/shared/product-model.md |
| 81 | +@.claude/rules/backend/rust-conventions.md |
| 82 | +@.claude/rules/backend/security.md |
| 83 | +@.claude/rules/backend/crate-structure.md |
| 84 | +@.claude/rules/backend/connector-guidelines.md |
| 85 | +@.claude/rules/backend/testing.md |
| 86 | +@.claude/rules/frontend/solidjs-conventions.md |
0 commit comments