diff --git a/README.md b/README.md
index 95c88cc5e..7cd7c3a06 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,32 @@ Use `--force` to re-apply updates even when your installed version already match
 
 ---
 
+## Local Development Installation
+
+To install and run Squad from source for development:
+
+```bash
+# Clone the repository
+git clone https://github.com/bradygaster/squad.git
+cd squad
+
+# Install dependencies (npm workspaces)
+npm install
+
+# Build the project (SDK first, then CLI)
+npm run build
+
+# Run the CLI directly
+node ./packages/squad-cli/dist/cli-entry.js init
+
+# Or link it globally for convenience
+npm run dev:link
+```
+
+After `npm run dev:link`, the `squad` command will be available globally and will use your local build. To update after code changes, re-run `npm run build` to recompile.
+
+---
+
 ## All Commands (17 commands)
 
 | Command | What it does |
diff --git a/docs/src/content/docs/guide/contributing.md b/docs/src/content/docs/guide/contributing.md
index 251d04c8d..6da9dcc03 100644
--- a/docs/src/content/docs/guide/contributing.md
+++ b/docs/src/content/docs/guide/contributing.md
@@ -73,12 +73,9 @@ npm workspaces automatically links local packages. `@bradygaster/squad-cli` can
 ### 2. Build
 
 ```bash
-# Compile TypeScript to dist/
+# Compile TypeScript for both packages (SDK + CLI)
 npm run build
 
-# Build + bundle CLI (includes esbuild)
-npm run build:cli
-
 # Watch mode (auto-recompile on changes)
 npm run dev
 ```
@@ -191,16 +188,17 @@ This convention makes `squad version` show the preview tag locally, clearly indi
 To make the `squad` CLI command globally available and pointing to your local development build:
 
 ```bash
-npm run build -w packages/squad-sdk && npm run build -w packages/squad-cli
-npm link -w packages/squad-cli
+npm run dev:link
 ```
 
-After this, `squad version` will show `0.8.6-preview` (or the current preview version). When you make code changes and rebuild, the `squad` command automatically picks up the changes—no need to reinstall. To verify your local build is active, the version output should include the `-preview` tag.
+This builds both packages and runs `npm link` to make `squad` available globally pointing to your local source.
+
+When you make code changes, re-run `npm run build` to recompile. No need to re-link — the linked package automatically picks up changes.
 
 To revert back to the globally installed npm package version, run:
 
 ```bash
-npm unlink -w packages/squad-cli
+npm run dev:unlink
 ```
 
 ## Changesets: Independent Versioning