Guides

Guides

These pages are generated straight from the resources/ directory of the salmon repository — the repository is always the canonical source, and may be ahead of what is published here.

• The salmon model — the general, domain-independent model that lives in salmon-core (Graph, OpGraph, Track, Eval), why it is shaped this way, and where else it could be pointed. Start here for the why.
• How to write and test salmon ops — the cookbook: copy the patterns, adapt the names, and you produce a valid Op. Written to be usable as a reference even by less-context-heavy tooling. Start here for the how.
• Salmon ops patterns — recurring shapes worth reusing across recipes, such as a one-time privileged bootstrap.
• run serve: convergence and supervision — what the long-running mode gives you for free (convergence, status/force/pause, self-healing on re-declaration), how to try it, the line protocol, the HTTP API and event stream, the web UI, TLS over TCP, pull mode and the status sink, and what to decorate a node with (check, Supervision, managed) to get more out of it.
• A Postgres pair whose primary is declared, not discovered — what a switchover does step by step, when the recipe refuses and why, and how to watch a client keep writing across one with the salmon-toy-qemu-pg-ha demo.
• Validating the GCP builtins against a real project — the playbook for exercising the Gcp.* builtins in a sandbox you are willing to destroy, with the salmon-gcp-toy binary.

One more document exists only in the repository:

• CLAUDE.md — the architecture module by module and the repository-level conventions (package layering, idempotency, failure propagation), for anyone, human or AI, working in the codebase.