guide

Learning Path

New to Springtale? Read these in order. Each builds on the last.

  ┌─────────────────────────────────────────────────────────┐
  │                                                         │
  │   1. README.md ─────────────> What is it? Who is it for?│
  │         │                                               │
  │         v                                               │
  │   2. installation/ ────────> Pick how you'll run it     │
  │         │                                               │
  │         v                                               │
  │   3. QUICKSTART.md ────────> First bot in 60 seconds    │
  │         │                                               │
  │         v                                               │
  │   4. guide/architecture.md ─> How the pieces fit        │
  │         │                                               │
  │         v                                               │
  │   5. guide/security.md ────> How it protects you        │
  │         │                                               │
  │         v                                               │
  │   6. guide/connectors.md ──> What connectors are        │
  │         │                                               │
  │         v                                               │
  │   7. guide/rules.md ───────> How to automate things     │
  │         │                                               │
  │         v                                               │
  │   8. tutorials/ ───────────> Build something real       │
  │         │                                               │
  │         v                                               │
  │   9. GLOSSARY.md ──────────> Look up anything unfamiliar│
  │                                                         │
  └─────────────────────────────────────────────────────────┘

Fig. 1. Suggested reading order for newcomers.

Already know what you're looking for?

I want to...	Go to
Install Springtale	installation/
First bot fast	QUICKSTART.md
Multi-step tutorials	tutorials/
Cookbook recipes for common patterns	cookbook/
Look up a CLI command	reference/cli.md
Look up an API endpoint	reference/api.md
API client examples	reference/api-clients/
See a specific connector's triggers/actions	reference/connectors/
Check a config option	reference/configuration.md
Performance characteristics	reference/performance.md
Use the Python bindings	python/
Understand a technical term	GLOSSARY.md
Frequently asked questions	FAQ.md
Build a new connector	contributing/adding-a-connector.md
Add a transport / AI adapter / sentinel check	contributing/extension-points.md
Understand why we chose X over Y	contributing/design-decisions.md + adr/
Operate a daemon long-term	operations/
See what's shipped vs planned	ROADMAP.md

Cooperation deep-dives

Once you've shipped your first bot, these task-oriented guides cover how Springtale's RTS-style cooperation primitives actually work in practice. Each is opinionated; read them when you hit the symptom, not before.

Topic	Guide
Governance — what's allowed, who approved, what happened	governance.md
Why bots cooperate (the overall model)	cooperation.md
L6 intervention — when the orchestrator escalates	intervention.md
Consensus votes at Fever tier	consensus.md
Voluntary task yielding (sacrifice)	sacrifice.md
What knowledge persists across formations	mental-model.md
Throughput governor (preparation→active→peak→…)	pacing.md
Cross-formation gossip + outcome propagation	cross-formation.md
When something's off — symptoms → fixes	troubleshooting-cooperation.md

Recipes + observability (W- and Phase A/B/D1)

The newer surfaces — click-and-play recipes, the executions log, external workspaces, dedupe semantics for polling.

Topic	Guide
Click-and-play recipes (browse, fill, deploy)	recipes.md
Recipe data shape reference	../reference/recipes-format.md
Authoring tools — preflight, preview, test-step, selector picker	recipe-authoring-tools.md
Phase A — Action::Dedupe and Action::Extract for polling	dedupe-and-extract.md
Phase B — per-fire executions log + drift detection	executions-and-drift.md
D1 — discovered chat destinations (workspace directory)	external-workspaces.md

Safety and OPSEC

Springtale targets users whose threat model is hostile attention. These pages cover the trust + privacy posture in depth.

Topic	Where
Vulnerability disclosure policy	SECURITY.md
Threat model in plain language	threat-model-faq.md
Running in adversarial environments	opsec.md
Anonymous contribution	anonymous-contribution.md
Privacy policy (the formal one)	privacy-policy.md
Backup, restore, host migration	operations/backup-and-restore.md, operations/host-migration.md

Architecture Decision Records

For "why did you pick X?" questions. See adr/ for the full index. Highlights:

Decision	ADR
rusqlite over sqlx	0001
Wasmtime sandbox	0002
rustls only; native-tls banned	0003
Secret<T> discipline	0004
Cooperation as separate crate	0005
Declarative schema over migrations	0006
Axum for HTTP	0007
Tauri for desktop	0008
Veilid for Phase 3 P2P	0009
DefaultDenyApprovalGate	0010