feat(paths): --user-dir / RALPH_USER_DIR + scout init --from-example (#51)

Closes #50.

Lets scouts and results live outside the ralph-for-kiro checkout via a
documented resolution order:

  1. --user-dir <path>        (highest priority)
  2. $RALPH_USER_DIR
  3. $XDG_CONFIG_HOME/ralph-for-kiro/   (honored only when present)
  4. process.cwd()            (legacy fallback — preserves existing crons)

Implementation:

  - src/utils/paths.ts — new getUserDir() / resolveUserDir() /
    setUserDir() helpers; scoutsDir() / resultsDir() /
    watchManifestFile() getters replace the old SCOUTS_DIR /
    RESULTS_DIR / WATCH_MANIFEST_FILE constants.
  - src/index.ts — --user-dir is a global program option; a
    preSubcommand commander hook calls setUserDir() once before any
    subcommand handler runs, so every path helper reads a stable value
    for the duration of the process.
  - src/core/watch-runner.ts + src/commands/{watch,scout}.ts — all path
    call sites migrated to the new getters.
  - src/commands/scout.ts — new `--from-example <template>` option on
    `ralph scout init`. A SCOUT_EXAMPLES registry maps template keys to
    bundled manifest JSON + steering markdown (currently: hn-frontpage).
    `ralph scout init --from-example hn-frontpage my-hn-scout` copies
    both files into the new scout's tree; ensureScoutKiroTree
    preserves steering on first run so the template customization
    survives.
  - scouts/README.md — documents the resolution order, drops the
    incorrect "4am CST cron" reference (cron times run in the host's
    local TZ, not ours), and shows a generic cron example that pins
    $RALPH_USER_DIR explicitly.

Tests:

  - tests/user-dir.test.ts — 6 new tests for the full resolution
    precedence, including XDG-when-absent falling through to cwd,
    and scoutsDir/resultsDir/watchManifestFile following the active
    user dir.
  - tests/scout-init.test.ts — 2 new tests for --from-example:
    happy path (manifest + steering land) and unknown-template
    rejection.

Backwards compatibility: setting no flag / env / XDG dir results in the
previous repo-relative behavior. Existing cron invocations keep working
without modification.

Verified with live CLI runs: `--user-dir`, `RALPH_USER_DIR`, and
`scout init --from-example` all produce expected files; backwards-compat
fallback correctly reports no scouts when cwd is empty.

All gates green: typecheck, biome, 101/101 tests.

Author: theagenticguy

scouts/README.md

@@ -17,20 +17,28 @@ committed to the ralph-for-kiro repo. Think of it the same way you think of
    rewrites each scout's `.kiro/{agents,steering,hooks,settings}` on
    every run, so any committed copy goes stale immediately.
 
+## Where does `scouts/` live?
+
+By default, `scouts/` sits alongside the ralph-for-kiro checkout. That works
+for a single-machine setup but means scout data is coupled to the repo clone.
+Override with either:
+
+- `--user-dir <path>` CLI flag (e.g. `ralph --user-dir ~/ralph-data scout ls`)
+- `RALPH_USER_DIR=<path>` env var (useful in cron entries)
+- `$XDG_CONFIG_HOME/ralph-for-kiro/` (auto-detected if the directory exists)
+
+Resolution order is flag → env → XDG → cwd. The cwd fallback keeps existing
+setups working without change.
+
 ## Making a new scout
 
 Two ways:
 
-**From an example template** (recommended for feed-shaped scouts):
+**From a built-in template** (recommended for feed-shaped scouts):
 ```bash
-# Coming in the follow-up PR per GH issue #TBD —
-# `ralph scout init --from-example hn-frontpage`
-cp src/data/examples/hn-frontpage-manifest.json \
-   scouts/my-hn-scout/manifest.json
-mkdir -p scouts/my-hn-scout/.kiro/steering
-cp src/data/examples/hn-frontpage-steering.md \
-   scouts/my-hn-scout/.kiro/steering/watcher-context.md
+ralph scout init --from-example hn-frontpage my-hn-scout
 ```
+Available templates: `hn-frontpage`.
 
 **From scratch** (repo-watch scouts like ai-eval):
 ```bash
@@ -50,8 +58,19 @@ ralph scout tail my-scout             # watch an in-flight run
 
 Output lands in `results/<scout-name>/pw-YYYYMMDD-HHmm/` (also gitignored).
 
-## Heads-up on the 4am-CST cron
+## Running nightly via cron
 
 If you set up a nightly cron, it will fail silently if `scouts/` is empty.
-Either seed from an example or have `ralph scout init` run once before the
-first cron invocation.
+Either seed a scout from a template or run `ralph scout init` once before
+the first cron invocation. Pin the user dir explicitly in the crontab entry
+if you want scouts to live outside the repo:
+
+```cron
+0 9 * * * RALPH_USER_DIR=$HOME/ralph-data /path/to/ralph-for-kiro \
+  scout --concurrency 3 --min-iterations 2 --max-iterations 4 \
+  >> $HOME/ralph-data/cron.log 2>&1
+```
+
+Remember that crontab times are in the host's local timezone — if your
+devbox runs UTC and you want a local-CST time, convert accordingly (and
+remember DST will shift the run by an hour twice a year).

src/commands/scout.ts

@@ -13,7 +13,28 @@ import {
 	runWatch,
 	type WatchRunEntry,
 } from "../core/watch-runner";
-import { RESULTS_DIR, SCOUTS_DIR } from "../utils/paths";
+import hnFrontpageManifest from "../data/examples/hn-frontpage-manifest.json";
+import hnFrontpageSteering from "../data/examples/hn-frontpage-steering.md" with {
+	type: "text",
+};
+import { resultsDir, scoutsDir } from "../utils/paths";
+
+/**
+ * Registry of built-in scout templates shipped under src/data/examples/.
+ * Each entry supplies a manifest object + a steering markdown string that
+ * `ralph scout init --from-example <key>` copies into a new scout's tree.
+ */
+const SCOUT_EXAMPLES: Record<
+	string,
+	{ manifest: unknown; steering: string; description: string }
+> = {
+	"hn-frontpage": {
+		manifest: hnFrontpageManifest,
+		steering: hnFrontpageSteering,
+		description:
+			"RSS-feed-driven trend scout for HN frontpage + best + show. Trend + surprise output, not repo discovery.",
+	},
+};
 
 /**
  * A scout definition derived from its directory and manifest.
@@ -48,18 +69,18 @@ interface ScoutRunOptions {
  */
 async function discoverScouts(): Promise<ScoutInfo[]> {
 	try {
-		await readdir(SCOUTS_DIR);
+		await readdir(scoutsDir());
 	} catch {
 		return [];
 	}
 
-	const entries = await readdir(SCOUTS_DIR, { withFileTypes: true });
+	const entries = await readdir(scoutsDir(), { withFileTypes: true });
 	const scouts: ScoutInfo[] = [];
 
 	for (const entry of entries) {
 		if (!entry.isDirectory()) continue;
 
-		const manifestPath = join(SCOUTS_DIR, entry.name, "manifest.json");
+		const manifestPath = join(scoutsDir(), entry.name, "manifest.json");
 		try {
 			const manifest = await readManifest(manifestPath);
 			scouts.push({
@@ -98,7 +119,7 @@ export async function scoutRunCommand(opts: ScoutRunOptions): Promise<void> {
 	if (allScouts.length === 0) {
 		log.error(
 			pc.red(
-				`No scouts found in ${SCOUTS_DIR}/\nRun 'ralph scout init <name>' to create one.`,
+				`No scouts found in ${scoutsDir()}/\nRun 'ralph scout init <name>' to create one.`,
 			),
 		);
 		return;
@@ -232,7 +253,7 @@ export async function scoutLsCommand(): Promise<void> {
 
 	if (scouts.length === 0) {
 		log.message(
-			`No scouts found in ${SCOUTS_DIR}/. Run 'ralph scout init <name>' to create one.`,
+			`No scouts found in ${scoutsDir()}/. Run 'ralph scout init <name>' to create one.`,
 		);
 		return;
 	}
@@ -335,13 +356,22 @@ export async function scoutResultsCommand(name?: string): Promise<void> {
 }
 
 /**
- * Scaffolds a new scout with an empty manifest.
+ * Scaffolds a new scout with an empty manifest — or, with --from-example,
+ * by copying a built-in template (manifest + steering) into the new scout's
+ * tree. Steering from a template goes to
+ * `scouts/<name>/.kiro/steering/watcher-context.md`; ensureScoutKiroTree
+ * preserves existing steering so the template customization survives.
  */
 export async function scoutInitCommand(
 	name: string,
-	opts: { topics?: string; languages?: string; force?: boolean },
+	opts: {
+		topics?: string;
+		languages?: string;
+		force?: boolean;
+		fromExample?: string;
+	},
 ): Promise<void> {
-	const scoutDir = join(SCOUTS_DIR, name);
+	const scoutDir = join(scoutsDir(), name);
 	const manifestPath = join(scoutDir, "manifest.json");
 
 	// Check for existing
@@ -362,6 +392,38 @@ export async function scoutInitCommand(
 
 	await mkdir(scoutDir, { recursive: true });
 
+	if (opts.fromExample) {
+		const example = SCOUT_EXAMPLES[opts.fromExample];
+		if (!example) {
+			const available = Object.keys(SCOUT_EXAMPLES).join(", ");
+			log.error(
+				pc.red(
+					`Unknown example "${opts.fromExample}". Available: ${available || "(none)"}`,
+				),
+			);
+			return;
+		}
+
+		// Write the template manifest as-is.
+		await Bun.write(
+			manifestPath,
+			`${JSON.stringify(example.manifest, null, "\t")}\n`,
+		);
+
+		// Stamp the custom steering so ensureScoutKiroTree preserves it on
+		// first run (it skips steering writes when the file already exists).
+		const steeringDir = join(scoutDir, ".kiro", "steering");
+		await mkdir(steeringDir, { recursive: true });
+		await Bun.write(join(steeringDir, "watcher-context.md"), example.steering);
+
+		log.success(
+			`${pc.green("Created")} scout ${pc.cyan(name)} from example ${pc.cyan(opts.fromExample)} at ${scoutDir}`,
+		);
+		log.message(pc.dim(`  ${example.description}`));
+		log.message(pc.dim(`\n  Run: ralph scout run --name ${name}`));
+		return;
+	}
+
 	const topics = opts.topics
 		? opts.topics.split(",").map((t) => t.trim())
 		: [name];
@@ -399,7 +461,7 @@ export async function scoutInitCommand(
 export async function scoutStatusCommand(): Promise<void> {
 	const scouts = await discoverScouts();
 	if (scouts.length === 0) {
-		log.message(`No scouts found in ${SCOUTS_DIR}/.`);
+		log.message(`No scouts found in ${scoutsDir()}/.`);
 		return;
 	}
 
@@ -477,7 +539,7 @@ export async function scoutTailCommand(
 		return;
 	}
 
-	const iterationsDir = join(RESULTS_DIR, name, latest.taskId, "iterations");
+	const iterationsDir = join(resultsDir(), name, latest.taskId, "iterations");
 	log.info(pc.bold(`Tailing ${pc.cyan(name)} — run ${latest.taskId}`));
 	log.message(pc.dim(`   ${iterationsDir} (polling every ${intervalMs}ms)`));
 	console.log();

src/commands/watch.ts

@@ -20,8 +20,8 @@ import {
 	KIRO_AGENTS_DIR,
 	KIRO_SETTINGS_DIR,
 	KIRO_STEERING_DIR,
-	RESULTS_DIR,
-	WATCH_MANIFEST_FILE,
+	resultsDir,
+	watchManifestFile,
 } from "../utils/paths";
 
 /**
@@ -98,7 +98,7 @@ export async function watchInitCommand(opts: WatchInitOptions): Promise<void> {
 	await mkdir(KIRO_AGENTS_DIR, { recursive: true });
 	await mkdir(KIRO_STEERING_DIR, { recursive: true });
 	await mkdir(KIRO_SETTINGS_DIR, { recursive: true });
-	await mkdir(RESULTS_DIR, { recursive: true });
+	await mkdir(resultsDir(), { recursive: true });
 
 	// Write agent config
 	await Bun.write(agentPath, `${JSON.stringify(agentConfig, null, 2)}\n`);
@@ -132,16 +132,16 @@ export async function watchInitCommand(opts: WatchInitOptions): Promise<void> {
 	}
 
 	// Copy manifest if it doesn't exist
-	if (!(await Bun.file(WATCH_MANIFEST_FILE).exists())) {
+	if (!(await Bun.file(watchManifestFile()).exists())) {
 		const manifestSource = Bun.file(manifestSourcePath);
 		if (await manifestSource.exists()) {
 			const manifestContent = await manifestSource.text();
-			await Bun.write(WATCH_MANIFEST_FILE, manifestContent);
-			log.success(`${pc.green("Created")} ${WATCH_MANIFEST_FILE}`);
+			await Bun.write(watchManifestFile(), manifestContent);
+			log.success(`${pc.green("Created")} ${watchManifestFile()}`);
 			log.message(pc.dim("  Edit this file to set your topics and languages"));
 		}
 	} else {
-		log.message(pc.dim(`  ${WATCH_MANIFEST_FILE} already exists, skipping`));
+		log.message(pc.dim(`  ${watchManifestFile()} already exists, skipping`));
 	}
 
 	// Success message
@@ -221,7 +221,7 @@ export async function watchResultsCommand(taskId?: string): Promise<void> {
 	}
 
 	// Show iteration files
-	const iterationsDir = join(RESULTS_DIR, targetId, "iterations");
+	const iterationsDir = join(resultsDir(), targetId, "iterations");
 	try {
 		const files = await readdir(iterationsDir);
 		if (files.length > 0) {

src/core/watch-runner.ts

@@ -11,10 +11,10 @@ import { LoopConfigSchema } from "../schemas/config";
 import { type WatchManifest, WatchManifestSchema } from "../schemas/manifest";
 import { type WatchStatus, WatchStatusSchema } from "../schemas/results";
 import {
-	RESULTS_DIR,
-	SCOUTS_DIR,
+	resultsDir,
+	scoutsDir,
 	WATCH_AGENT_NAME,
-	WATCH_MANIFEST_FILE,
+	watchManifestFile,
 } from "../utils/paths";
 import { runLoop } from "./loop-runner";
 import { ensureScoutKiroTree } from "./scout-init";
@@ -52,7 +52,7 @@ export function generateTaskId(): string {
 export async function readManifest(
 	manifestPath?: string | null,
 ): Promise<WatchManifest> {
-	const path = manifestPath ?? WATCH_MANIFEST_FILE;
+	const path = manifestPath ?? watchManifestFile();
 	const file = Bun.file(path);
 
 	if (!(await file.exists())) {
@@ -123,8 +123,8 @@ export async function runWatch(opts: WatchRunOptions): Promise<void> {
 	// When running as a scout, namespace results under the scout name
 	const taskId = generateTaskId();
 	const resultsBase = opts.scoutName
-		? join(RESULTS_DIR, opts.scoutName)
-		: RESULTS_DIR;
+		? join(resultsDir(), opts.scoutName)
+		: resultsDir();
 	const resultsPath = join(resultsBase, taskId);
 	const iterationsPath = join(resultsPath, "iterations");
 
@@ -165,7 +165,7 @@ export async function runWatch(opts: WatchRunOptions): Promise<void> {
 	const absResultsPath = isAbsolute(resultsPath)
 		? resultsPath
 		: resolve(process.cwd(), resultsPath);
-	const manifestFilePath = opts.manifestPath ?? WATCH_MANIFEST_FILE;
+	const manifestFilePath = opts.manifestPath ?? watchManifestFile();
 	const absManifestPath = isAbsolute(manifestFilePath)
 		? manifestFilePath
 		: resolve(process.cwd(), manifestFilePath);
@@ -182,7 +182,7 @@ export async function runWatch(opts: WatchRunOptions): Promise<void> {
 	// repo root for backwards compatibility.
 	let scoutCwd: string | null = null;
 	if (opts.scoutName) {
-		const scoutDir = resolve(process.cwd(), SCOUTS_DIR, opts.scoutName);
+		const scoutDir = resolve(process.cwd(), scoutsDir(), opts.scoutName);
 		await ensureScoutKiroTree(scoutDir);
 		scoutCwd = scoutDir;
 	}
@@ -229,7 +229,7 @@ export async function readStatus(
 	taskId: string,
 	scoutName?: string | null,
 ): Promise<WatchStatus | null> {
-	const base = scoutName ? join(RESULTS_DIR, scoutName) : RESULTS_DIR;
+	const base = scoutName ? join(resultsDir(), scoutName) : resultsDir();
 	const statusPath = join(base, taskId, "status.json");
 	const file = Bun.file(statusPath);
 
@@ -248,7 +248,7 @@ export async function readSummary(
 	taskId: string,
 	scoutName?: string | null,
 ): Promise<string | null> {
-	const base = scoutName ? join(RESULTS_DIR, scoutName) : RESULTS_DIR;
+	const base = scoutName ? join(resultsDir(), scoutName) : resultsDir();
 	const summaryPath = join(base, taskId, "summary.md");
 	const file = Bun.file(summaryPath);
 
@@ -272,7 +272,7 @@ export interface WatchRunEntry extends WatchStatus {
 export async function listRuns(
 	scoutName?: string | null,
 ): Promise<WatchRunEntry[]> {
-	const base = scoutName ? join(RESULTS_DIR, scoutName) : RESULTS_DIR;
+	const base = scoutName ? join(resultsDir(), scoutName) : resultsDir();
 
 	// Check if directory exists
 	try {

src/index.ts

@@ -22,12 +22,23 @@ import {
 	watchResultsCommand,
 	watchRunCommand,
 } from "./commands";
+import { setUserDir } from "./utils/paths";
 import { VERSION } from "./version";
 
 const program = new Command()
 	.name("ralph")
 	.description("Ralph Wiggum iterative loop technique for Kiro CLI")
 	.version(VERSION)
+	.option(
+		"--user-dir <path>",
+		"Directory where scouts/ and results/ live (overrides $RALPH_USER_DIR and $XDG_CONFIG_HOME/ralph-for-kiro; falls back to cwd)",
+	)
+	.hook("preSubcommand", (thisCommand) => {
+		// Resolve --user-dir once before any subcommand runs so every path
+		// helper in src/utils/paths.ts reads a stable value.
+		const opts = thisCommand.opts();
+		setUserDir((opts["userDir"] as string | undefined) ?? null);
+	})
 	.addHelpText(
 		"after",
 		`
@@ -38,7 +49,13 @@ Common tasks:
   ralph scout tail ai-eval             Follow a live scout run
   ralph loop "Build a CLI" -m 20       Run Ralph iteratively on a task
 
-Data:
+User directory resolution (where scouts/ and results/ live):
+  --user-dir <path>                    Flag (highest precedence)
+  $RALPH_USER_DIR                      Env var
+  $XDG_CONFIG_HOME/ralph-for-kiro/     XDG default (only if it exists)
+  $(pwd)                               Legacy fallback
+
+Data layout (under the resolved user directory):
   scouts/<name>/                       Per-scout manifest + .kiro/ tree
   results/<scout>/pw-YYYYMMDD-HHmm/    Per-run artefacts (iterations/,
                                        summary.md, discovery.json,
@@ -211,6 +228,10 @@ scoutCmd
 	.option("-t, --topics <topics>", "Comma-separated topics")
 	.option("-l, --languages <langs>", "Comma-separated languages")
 	.option("-f, --force", "Overwrite existing scout")
+	.option(
+		"--from-example <template>",
+		"Scaffold from a built-in template (e.g. 'hn-frontpage'). Copies manifest + steering",
+	)
 	.action(scoutInitCommand);
 
 scoutCmd