From bbb3e19c6f5694418f5705dac12cc875f8cccbb9 Mon Sep 17 00:00:00 2001
From: Granis87 <55180608+RobinALG87@users.noreply.github.com>
Date: Wed, 15 Jul 2026 22:51:53 +0200
Subject: [PATCH] docs: add safe local worktree bootstrap guidance (#9195)

## Thinking Path

> - Parallel local agent experiments should not reuse the primary
Paperclip instance.
> - Paperclip already creates isolated worktree instances with generated
names and environment files.
> - The local development guide lacked a complete bootstrap and recovery
path.
> - This pull request adds that path using the registered CLI forms and
generated selector.
> - The benefit is safer setup, recovery, and cleanup for local
experiments.

## Linked Issues or Issue Description

No public issue was found. The local development guide did not connect
worktree creation, environment loading, startup, repair/reseed, and
cleanup into one safe sequence.

## What Changed

- Added an isolated worktree bootstrap example.
- Documented bash/zsh environment loading without presenting invalid
PowerShell syntax.
- Used registered repair/reseed commands and the generated
paperclip-local-lab selector.
- Added explicit cleanup guidance.

## Verification

- git diff --check upstream/master...HEAD
- Verified command registration and generated naming in
cli/src/commands/worktree.ts.

## Risks

Low. Documentation-only; reviewed command and selector mismatches are
corrected.

## Model Used

OpenAI GPT-5.3 Codex Spark for initial branch work; OpenAI GPT-5 Codex
for review and follow-up fixes, with repository and GitHub tool use.
Context-window sizes were not exposed in this session.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this docs PR does not
duplicate planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked or
described the problem above
- [x] I have either linked an existing issue or described the issue
in-PR
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run focused validation locally
- [x] I have added or updated tests where applicable
(documentation-only; no runtime tests needed)
- [x] I have updated the relevant documentation
- [x] I have considered and documented risks above
- [x] All Paperclip CI gates are green on the latest commit
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
on the latest commit
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: RobinALG87 <RobinALG87@users.noreply.github.com>
---
 docs/deploy/local-development.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.md
index 3bc423341e..950b572e03 100644
--- a/docs/deploy/local-development.md
+++ b/docs/deploy/local-development.md
@@ -79,6 +79,32 @@ curl http://localhost:3100/api/companies
 # -> []
 ```
 
+## Safe Worktree Bootstrap for Local Agent Runs
+
+For safer parallel local experiments, initialize a dedicated worktree instance instead of reusing your main checkout:
+
+```sh
+pnpm paperclipai worktree:make local-lab --seed-mode minimal
+cd ~/paperclip-local-lab
+pnpm paperclipai worktree env                       # inspect generated env exports
+eval "$(pnpm paperclipai worktree env)"             # bash/zsh
+pnpm paperclipai run
+pnpm paperclipai doctor
+```
+
+If the experiment gets noisy, repair or reseed the worktree without touching the main branch:
+
+```sh
+pnpm paperclipai worktree repair --branch paperclip-local-lab
+pnpm paperclipai worktree reseed --from . --to paperclip-local-lab
+```
+
+When done, shut it down and remove the isolated state explicitly:
+
+```sh
+pnpm paperclipai worktree:cleanup local-lab --force
+```
+
 ## Reset Dev Data
 
 To wipe local data and start fresh: