From f180968b771175cad256723b789862c0c3d3326b Mon Sep 17 00:00:00 2001
From: Alexander Brandstedt <alexander@infralium.com>
Date: Tue, 7 Jul 2026 19:15:08 +0200
Subject: [PATCH] docs: remote recipe sources section; ci: scope releases to
 darwin/arm64
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

README gains a remote recipe sources section ([[recipe_sources]] example,
source/recipe namespacing, pin vs follow) and a releases section; the
goreleaser matrix drops linux — ralph targets macOS, matching thismoon.
---
 .goreleaser.yml | 10 ++--------
 README.md       | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/.goreleaser.yml b/.goreleaser.yml
index 565fd33..8ed6a31 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -11,12 +11,10 @@ builds:
     binary: ralph
     # Main package location
     main: ./cmd/ralph/
-    # Goos and Goarch to build for
+    # darwin/arm64 only — ralph targets macOS, same scoping as thismoon
     goos:
-      - linux
-      - darwin # macOS
+      - darwin
     goarch:
-      - amd64
       - arm64
     # Optional: Goarm for arm architectures (e.g., '6', '7')
     # goarm:
@@ -37,10 +35,6 @@ archives:
     files:
       - LICENSE
       - README.md
-    # For Windows, often .zip is preferred
-    format_overrides:
-      - goos: windows
-        format: zip
 
 # Checksum generation for the archives
 checksum:
diff --git a/README.md b/README.md
index 580f75b..b0d3d48 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,33 @@ See [Commands → JSON output](docs/commands.md#json-output) for the document sh
 - **Packages** -- clone remote tools or track local projects; `ralph up` syncs and rebuilds on changes
 - **Tool checks** -- verify tools are installed, show install hints
 - **Recipes** -- split config into modular `recipe.toml` files alongside source files, ordered into dependency waves (`ralph graph` renders the layout)
+- **Remote recipe sources** -- pull recipes from other git repos, so a project can ship its code and its install recipe together
+- **Machine profiles** -- tag machines and recipes with roles (`personal`, `work`, ...) and hostnames; only matching recipes apply
+
+## Remote recipe sources
+
+A repo can ship recipes next to its code and any machine can consume them.
+Point a `[[recipe_sources]]` stanza at the repo:
+
+```toml
+[[recipe_sources]]
+name = "thismoon"
+url = "git@github.com:mad01/thismoon.git"
+ref = "main"
+update = true
+```
+
+ralph clones the source into `~/.config/ralph/sources/<name>`, discovers
+`recipe.toml` files under its `recipes/` directory, and merges them under the
+namespaced identity `<source>/<recipe>` (here `thismoon/reminder`,
+`thismoon/csl`, ...). A branch ref with `update = true` follows the branch on
+every `ralph up`; a tag or commit ref pins. Machine-private wiring (secrets,
+host config, overlays) stays in your own config repo as companion recipes
+layered on top.
+
+See [Recipes → Remote sources](docs/recipes.md) for the full reference, and
+[thismoon](https://github.com/mad01/thismoon) for a repo built around this
+pattern.
 
 ## Documentation
 
@@ -93,6 +120,13 @@ See [Commands → JSON output](docs/commands.md#json-output) for the document sh
 | [with-packages](examples/with-packages/) | Local and remote package builds |
 | [dotfiles-repo](examples/dotfiles-repo/) | Full dotfiles repository structure |
 
+## Releases
+
+Releases are tag-driven: pushing a `v*` tag runs GoReleaser in CI, which
+builds a darwin/arm64 binary (ralph targets macOS), embeds the version via
+ldflags, and publishes a tar.gz archive with checksums and a changelog to the
+[Releases](https://github.com/mad01/ralph/releases) page.
+
 ## Contributing
 
 Contributions welcome. Open an issue or PR on [GitHub](https://github.com/mad01/ralph).