From 06ce28bcea58d255c5f2dfc6afa0cae88e8f6613 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 16 Mar 2026 11:07:21 -0400
Subject: [PATCH] Add install.md for AI agent-driven installation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-contained installation instructions following the install.md spec.
Decoupled from install.sh — handles platform detection, binary download,
PATH setup in shell dotfiles, and verification independently. Prompts
the user to run `fabro install` interactively to complete setup.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 apps/marketing/public/install.md |   1 +
 install.md                       | 101 +++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 120000 apps/marketing/public/install.md
 create mode 100644 install.md

diff --git a/apps/marketing/public/install.md b/apps/marketing/public/install.md
new file mode 120000
index 000000000..deb797142
--- /dev/null
+++ b/apps/marketing/public/install.md
@@ -0,0 +1 @@
+../../../install.md
\ No newline at end of file
diff --git a/install.md b/install.md
new file mode 100644
index 000000000..3cc4b4d90
--- /dev/null
+++ b/install.md
@@ -0,0 +1,101 @@
+# fabro
+
+> AI-powered workflow orchestration platform. Workflows are defined as DOT graphs and executed by the Fabro engine.
+
+I want you to install Fabro for me. Execute all the steps below autonomously.
+
+OBJECTIVE: Install the Fabro CLI binary and verify it works.
+
+DONE WHEN: `fabro --version` prints a version string.
+
+## TODO
+
+- [ ] Ensure the `gh` CLI is installed and authenticated
+- [ ] Detect the platform and download the correct release asset
+- [ ] Extract the binary and install it to `~/.fabro/bin`
+- [ ] Add `~/.fabro/bin` to PATH in the user's shell config
+- [ ] Verify `fabro --version` works
+
+## Ensure `gh` CLI is available
+
+You need the GitHub CLI (`gh`) installed and authenticated. Check with:
+
+```bash
+gh auth status
+```
+
+If `gh` is not installed, install it:
+
+- **macOS:** `brew install gh`
+- **Linux:** See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+
+Then authenticate with `gh auth login` if needed.
+
+## Detect platform and download
+
+Determine the correct release asset based on the platform:
+
+| OS | Architecture | Asset name |
+|---|---|---|
+| macOS | arm64 (Apple Silicon) | `fabro-aarch64-apple-darwin.tar.gz` |
+| Linux | x86_64 | `fabro-x86_64-unknown-linux-gnu.tar.gz` |
+
+On macOS, if `uname -m` reports `x86_64`, check for Rosetta translation with `sysctl -n sysctl.proc_translated`. If it returns `1`, the actual architecture is arm64.
+
+Download the asset using `gh`:
+
+```bash
+gh release download --repo fabro-sh/fabro --pattern "fabro-<TARGET>.tar.gz" --dir /tmp/fabro-install --clobber
+```
+
+Replace `<TARGET>` with the correct target triple from the table above.
+
+## Extract and install
+
+```bash
+tar xzf /tmp/fabro-install/fabro-<TARGET>.tar.gz -C /tmp/fabro-install
+mkdir -p ~/.fabro/bin
+mv /tmp/fabro-install/fabro-<TARGET>/fabro ~/.fabro/bin/fabro
+chmod +x ~/.fabro/bin/fabro
+rm -rf /tmp/fabro-install
+```
+
+## Add to PATH
+
+If `~/.fabro/bin` is not already on PATH, you must add it to the user's shell configuration file so it persists across sessions.
+
+**zsh** — append to `~/.zshrc` (or `$ZDOTDIR/.zshrc` if `ZDOTDIR` is set):
+
+```bash
+printf '\n# fabro\nexport PATH="$HOME/.fabro/bin:$PATH"\n' >> ~/.zshrc
+```
+
+**bash** — append to `~/.bash_profile` if it exists, otherwise `~/.bashrc`:
+
+```bash
+printf '\n# fabro\nexport PATH="$HOME/.fabro/bin:$PATH"\n' >> ~/.bash_profile
+```
+
+**fish** — append to `~/.config/fish/config.fish`:
+
+```bash
+printf '\n# fabro\nfish_add_path $HOME/.fabro/bin\n' >> ~/.config/fish/config.fish
+```
+
+After updating the config file, export PATH for the current session too:
+
+```bash
+export PATH="$HOME/.fabro/bin:$PATH"
+```
+
+## Verify
+
+```bash
+fabro --version
+```
+
+This must print a version string like `fabro 0.x.y`. If it does, installation is complete.
+
+Tell the user to run `fabro install` in their terminal to complete setup.
+
+EXECUTE NOW: Complete the above TODO list to achieve: `fabro --version` prints a version string.