From 85b0dc9592fafb8a9f159292816b0e33d8b38a08 Mon Sep 17 00:00:00 2001
From: roboomp <omp@can.ac>
Date: Wed, 17 Jun 2026 17:51:06 +0000
Subject: [PATCH] docs: added developer setup guide

Added a root setup script that installs workspaces and builds the native addon before running the source CLI.

Documented the fresh-clone setup and smoke-check flow in the README development section.

Fixes #2895
---
 README.md                         | 17 +++++++++++++++++
 package.json                      |  2 +-
 packages/coding-agent/scripts/omp |  2 +-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 369c162c6..823c14741 100644
--- a/README.md
+++ b/README.md
@@ -474,6 +474,23 @@ Key ideas:
 
 ## Development
 
+### Getting started from source
+
+Fresh clones need both workspace dependencies and the local Rust/N-API addon before the source CLI can start.
+
+```sh
+bun setup
+bun dev
+```
+
+`bun setup` installs Bun workspaces and builds `@oh-my-pi/pi-natives`. Re-run `bun run build:native` after changing Rust crates or `packages/natives`.
+
+For a non-interactive smoke check:
+
+```sh
+bun dev -- --version
+```
+
 ### Debug Command
 
 `/debug` opens tools for debugging, reporting, and profiling.
diff --git a/package.json b/package.json
index c6f0427d1..236e9f281 100644
--- a/package.json
+++ b/package.json
@@ -91,7 +91,7 @@
   },
   "overrides": {},
   "scripts": {
-    "install:dev": "bun install && bun --cwd=packages/coding-agent link && ln -sfn \"$(pwd)/packages/coding-agent/scripts/omp\" \"$(bun pm -g bin)/omp\"",
+    "setup": "bun install && bun run build:native",
     "dev": "bun --cwd=packages/coding-agent src/cli.ts",
     "dev:timing": "PI_TIMING=x bun --cwd=packages/coding-agent --preload ../utils/src/module-timer.ts src/cli.ts",
     "stats": "bun --cwd=packages/coding-agent src/cli.ts stats",
diff --git a/packages/coding-agent/scripts/omp b/packages/coding-agent/scripts/omp
index 8db47a6b4..2d60cb8b8 100755
--- a/packages/coding-agent/scripts/omp
+++ b/packages/coding-agent/scripts/omp
@@ -1,5 +1,5 @@
 #!/bin/sh
-# Dev launcher for the omp CLI, installed by `bun run install:dev`.
+# Dev launcher for the omp CLI.
 #
 # Problem it solves: Bun reads `bunfig.toml` from the *current working
 # directory* at startup and evaluates its `preload` entries before running the