Add robust run-repo shortcuts with nested project support

Author: nikivdev

docs/commands/sync.md

@@ -6,6 +6,17 @@ Sync git repo: pull from tracking remote, merge upstream changes, optionally pus
 
 Single command to bring a repository up to date. Pulls from the tracking branch, syncs upstream if configured (fork workflow), and optionally pushes. Works with both plain git and jj (jujutsu) colocated repos.
 
+## Context Card
+
+Use this block when passing `f sync` behavior to another agent:
+
+- Default behavior: pull/sync only; push is off unless `--push`.
+- Defaults: `--stash=true`, `--fix=true`.
+- Modes: uses jj flow in healthy colocated workspaces, falls back to plain git when needed.
+- Push target: configured `[git].remote` first, then standard fallback behavior.
+- Clipboard output: synced commit list is copied only when remote commit ranges are detected (typically jj fetch path).
+- Conflict note: jj can finish with unresolved conflicts and prints `jj resolve` guidance.
+
 ## Quick Start
 
 ```bash
@@ -77,8 +88,10 @@ Restores auto-stashed changes if any were stashed in step 1.
 
 ### Step 6: Synced commit list + clipboard
 
-On successful sync, Flow prints only the deduplicated list of newly synced commits (hash + subject)
-and copies that same list to your clipboard.
+When remote commit ranges are discovered (typically during jj fetch), Flow prints a deduplicated
+list of newly synced commits (hash + subject) and copies that same list to your clipboard.
+
+If no synced commit ranges were detected, this section is skipped.
 
 Set `FLOW_NO_CLIPBOARD=1` to disable clipboard copy.
 
@@ -178,6 +191,14 @@ jj git import
 rm -rf .jj && jj git init --colocate
 ```
 
+### "Sync complete (jj) but conflicts remain"
+
+This means sync/rebase completed but conflict revisions still exist in jj.
+
+```bash
+jj resolve
+```
+
 ## See Also
 
 - [upstream](upstream.md) - Manage upstream fork workflow

docs/index.mdx

@@ -40,6 +40,7 @@ High-signal docs for the Codex/Claude workflow:
 - [`rl-for-myflow-harbor.md`](rl-for-myflow-harbor.md): practical RL roadmap for turning myflow -> Harbor exports into a gated training/improvement loop.
 - [`rl-myflow-harbor-task-specs.md`](rl-myflow-harbor-task-specs.md): executable task contracts for validate/reward/canary/hardcase stages.
 - [`private-fork-flow.md`](private-fork-flow.md): generic AI runbook for private-fork setup and safe push routing via Flow `[git].remote`.
+- [`run-repos.md`](run-repos.md): shortcuts and resolution rules for running tasks in `~/code/run` and `~/code/run/i` from anywhere.
 - [`dependency-vendoring.md`](dependency-vendoring.md): inhouse dependency workflow, offender ranking, and fast upstream sync loop for vendored crates.
 - [`vendor-code-intelligence.md`](vendor-code-intelligence.md): opensrc-style local code indexing/search for vendored crates + first-party code via Typesense.
 - [`vendor-nix-inspiration.md`](vendor-nix-inspiration.md): how Flow vendoring borrows Nix ideas (pinning, reproducibility, provenance, rollback) while staying Cargo-first.

docs/run-repos.md

@@ -0,0 +1,83 @@
+# Run Repos Shortcuts (`f r`, `f ri`, `f rp`, `f rip`)
+
+This workflow lets you run Flow tasks in `~/code/run` and `~/code/run/i` from anywhere,
+without manual `cd`.
+
+## Standard Layout
+
+```text
+~/code/run/            # public run repo (has flow.toml)
+~/code/run/i/          # internal run repo (has flow.toml)
+~/code/run/i/linsa/    # nested internal project example
+```
+
+`f health` now ensures `~/code/run` and `~/code/run/i` directories exist.
+
+## Primary Commands
+
+| Command | Meaning |
+|---|---|
+| `f r <task> [args...]` | Run task in `~/code/run` |
+| `f ri <task> [args...]` | Run task in `~/code/run/i` |
+| `f rp <project> <task> [args...]` | Run task in project under run tree |
+| `f rip <project> <task> [args...]` | Run task in `~/code/run/i/<project>` |
+
+## Resolution Rules
+
+`f rp <project> ...` resolves in this order:
+
+1. `~/code/run/<project>`
+2. `~/code/run/i/<project>` (fallback)
+
+If both exist, Flow fails with an ambiguity error and asks for explicit path:
+
+- `f rp <project> ...` for public path
+- `f rp i/<project> ...` or `f rip <project> ...` for internal path
+
+## Nested Project Support
+
+Nested `flow.toml` projects are supported. Example:
+
+```bash
+f rip linsa bootstrap
+f rp linsa opencode-codex-login
+```
+
+Both target `~/code/run/i/linsa` (unless `~/code/run/linsa` also exists).
+
+## Why This Is Robust
+
+- Uses explicit `f run --config <dir>/flow.toml <task>` internally.
+- Avoids task-lookup ambiguity when nested `flow.toml` files exist.
+- Blocks unsafe paths (`/absolute`, `..` traversal) for run repo/project selectors.
+
+## Discovery and Maintenance
+
+```bash
+f run-list           # list all flow.toml repos/projects under ~/code/run (recursive)
+f run-sync           # sync all git repos under ~/code/run (recursive)
+f run-sync i         # sync only ~/code/run/i
+```
+
+## Script Interface
+
+Task shortcuts are powered by:
+
+```bash
+scripts/run-repos.sh
+```
+
+Direct script commands:
+
+```bash
+bash ./scripts/run-repos.sh r <task> [args...]
+bash ./scripts/run-repos.sh ri <task> [args...]
+bash ./scripts/run-repos.sh rp <project> <task> [args...]
+bash ./scripts/run-repos.sh rip <project> <task> [args...]
+```
+
+`RUN_ROOT` can be overridden for testing:
+
+```bash
+RUN_ROOT=/tmp/my-run-layout f rp linsa whoami
+```

flow.toml

@@ -398,6 +398,30 @@ name = "run-exec"
 command = "bash ./scripts/run-repos.sh exec $@"
 description = "Ensure run repo exists (clone/sync) and run a task. Usage: f run-exec <name> <repo-ssh-url> [--branch <branch>] <task> [args...]"
 
+[[tasks]]
+name = "run-ri"
+command = "bash ./scripts/run-repos.sh ri $@"
+description = "Run a task in the internal run repo (~/code/run/i). Usage: f ri <task> [args...]"
+shortcuts = ["ri"]
+
+[[tasks]]
+name = "run-r"
+command = "bash ./scripts/run-repos.sh r $@"
+description = "Run a task in the public run repo (~/code/run). Usage: f r <task> [args...]"
+shortcuts = ["r"]
+
+[[tasks]]
+name = "run-rp"
+command = "bash ./scripts/run-repos.sh rp $@"
+description = "Run a task in a run project. Usage: f rp <project> <task> [args...] (resolves ~/code/run/<project> or ~/code/run/i/<project>)"
+shortcuts = ["rp"]
+
+[[tasks]]
+name = "run-rip"
+command = "bash ./scripts/run-repos.sh rip $@"
+description = "Run a task in an internal run project. Usage: f rip <project> <task> [args...] (maps to ~/code/run/i/<project>)"
+shortcuts = ["rip"]
+
 [storage]
 provider = "myflow.sh"
 env_var = "FLOW_SECRETS_TOKEN" # optional; defaults to this value