Merge remote-tracking branch 'origin/main' into bootstrap/multi-agent-readiness

# Conflicts:
#	docs/START_HERE.md

Author: FlowMemory Bootstrap Agent

docs/START_HERE.md

@@ -18,6 +18,80 @@ This is the first document to read after `AGENTS.md`.
 - Identify whether the task is docs, protocol, service, app, hardware, research, crypto, infra, or security work.
 - If the task touches architecture, security assumptions, public schemas, or cross-agent workflow, update docs in the same pull request.
 
+## Multi-Agent Worktree Setup
+
+Use one Git worktree per Codex agent. Each worktree has its own branch and folder under `E:\FlowMemory`, so agents can work without sharing the same checkout.
+
+Start from the main checkout:
+
+```powershell
+cd E:\FlowMemory\flowmemory-main
+.\infra\scripts\setup-worktrees.ps1
+```
+
+The setup script creates these worktrees if they do not already exist:
+
+```text
+E:\FlowMemory\flowmemory-contracts   agent/contracts
+E:\FlowMemory\flowmemory-indexer     agent/indexer
+E:\FlowMemory\flowmemory-hardware    agent/hardware
+E:\FlowMemory\flowmemory-dashboard   agent/dashboard
+E:\FlowMemory\flowmemory-research    agent/research
+E:\FlowMemory\flowmemory-crypto      agent/crypto
+E:\FlowMemory\flowmemory-chain       agent/chain
+E:\FlowMemory\flowmemory-review      agent/review
+```
+
+Run each Codex agent from its assigned worktree in a separate PowerShell window:
+
+```powershell
+cd E:\FlowMemory\flowmemory-contracts
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-indexer
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-hardware
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-dashboard
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-research
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-crypto
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-chain
+codex
+```
+
+```powershell
+cd E:\FlowMemory\flowmemory-review
+codex
+```
+
+## Multi-Agent Safety Rules
+
+- Keep `E:\FlowMemory\flowmemory-main` as the main checkout and coordination point.
+- Run each agent only inside its assigned worktree folder.
+- Check `git status --short --branch` before starting and before handing off work.
+- Avoid assigning two agents to edit the same files at the same time.
+- Use `git worktree list` from `E:\FlowMemory\flowmemory-main` to inspect all local worktrees.
+
 ## During Work
 
 - Keep changes small and reviewable.

infra/scripts/setup-worktrees.ps1

@@ -0,0 +1,107 @@
+$ErrorActionPreference = "Stop"
+Set-StrictMode -Version Latest
+
+$expectedRepo = "E:\FlowMemory\flowmemory-main"
+$flowMemoryRoot = "E:\FlowMemory"
+
+function Resolve-CanonicalPath {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    return (Resolve-Path -LiteralPath $Path).Path.TrimEnd("\")
+}
+
+function Test-GitRef {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Ref
+    )
+
+    & git show-ref --verify --quiet $Ref *> $null
+    return $LASTEXITCODE -eq 0
+}
+
+function Add-AgentWorktree {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path,
+
+        [Parameter(Mandatory = $true)]
+        [string] $Branch
+    )
+
+    if (Test-Path -LiteralPath $Path) {
+        Write-Host "Exists, skipping: $Path"
+        return
+    }
+
+    Write-Host "Creating: $Path ($Branch)"
+
+    if (Test-GitRef "refs/heads/$Branch") {
+        & git worktree add $Path $Branch
+    }
+    elseif (Test-GitRef "refs/remotes/origin/$Branch") {
+        & git worktree add -b $Branch $Path "origin/$Branch"
+    }
+    else {
+        & git worktree add -b $Branch $Path HEAD
+    }
+
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to create worktree $Path for branch $Branch."
+    }
+}
+
+if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+    throw "git was not found on PATH. Install Git or add it to PATH, then rerun this script."
+}
+
+$currentPath = Resolve-CanonicalPath (Get-Location).Path
+$expectedPath = Resolve-CanonicalPath $expectedRepo
+
+if ($currentPath -ne $expectedPath) {
+    throw "Run this script from $expectedRepo. Current path: $currentPath"
+}
+
+$gitRootRaw = (& git rev-parse --show-toplevel).Trim()
+if ($LASTEXITCODE -ne 0) {
+    throw "Current directory is not inside a Git repository."
+}
+
+$gitRoot = Resolve-CanonicalPath $gitRootRaw
+if ($gitRoot -ne $expectedPath) {
+    throw "Expected Git root $expectedRepo, but found $gitRoot."
+}
+
+$worktrees = @(
+    @{ Path = "$flowMemoryRoot\flowmemory-contracts"; Branch = "agent/contracts" },
+    @{ Path = "$flowMemoryRoot\flowmemory-indexer"; Branch = "agent/indexer" },
+    @{ Path = "$flowMemoryRoot\flowmemory-hardware"; Branch = "agent/hardware" },
+    @{ Path = "$flowMemoryRoot\flowmemory-dashboard"; Branch = "agent/dashboard" },
+    @{ Path = "$flowMemoryRoot\flowmemory-research"; Branch = "agent/research" },
+    @{ Path = "$flowMemoryRoot\flowmemory-crypto"; Branch = "agent/crypto" },
+    @{ Path = "$flowMemoryRoot\flowmemory-chain"; Branch = "agent/chain" },
+    @{ Path = "$flowMemoryRoot\flowmemory-review"; Branch = "agent/review" }
+)
+
+foreach ($worktree in $worktrees) {
+    Add-AgentWorktree -Path $worktree.Path -Branch $worktree.Branch
+}
+
+Write-Host ""
+Write-Host "Exact cd commands:"
+foreach ($worktree in $worktrees) {
+    Write-Host "cd $($worktree.Path)"
+}
+
+Write-Host ""
+Write-Host "How to run Codex in each worktree:"
+Write-Host "Open a separate PowerShell window for each agent, then run one cd command followed by codex."
+Write-Host ""
+foreach ($worktree in $worktrees) {
+    Write-Host "cd $($worktree.Path)"
+    Write-Host "codex"
+    Write-Host ""
+}