Dashboard/Scout/wiki/decisions/2026-05-20-workdir-and-env-local.md
Scout

wiki/decisions/2026-05-20-workdir-and-env-local.md

ADR: Scout Working Directory And .env.local

Date: 2026-05-20

Status

Accepted.

Context

Scout now runs as a CLI, HTTP app, and skill-backed tool. Runs produce multiple artifacts: records, source evidence, blocked pages, validation, reports, and future interim status/config files. Writing those artifacts to /tmp makes runs hard to find, hard to audit, and hard to reuse for PRISM, job monitoring, and research workflows.

Scout also needs a clear answer for local secrets and machine-specific settings such as SCOUT_API_KEY, LLM_API_KEY, and default run storage.

Decision

Scout will use a two-level storage model:

  1. output_dir is the exact run artifact directory. If provided, Scout writes exactly there.
  2. workdir is the base working directory used to create timestamped run folders when output_dir is not provided.

Resolution order:

  1. Explicit --output-dir or JSON output_dir.
  2. Explicit CLI --workdir.
  3. SCOUT_WORKDIR from environment or .env.local.
  4. Default ./scout-runs.

CLI high-level workflows and scout products prompt for the working directory when run interactively without --output-dir. HTTP, Docker, scheduled jobs, and skill-driven runs do not prompt; they must pass output_dir, pass --workdir through the CLI, or rely on SCOUT_WORKDIR.

Local secrets and machine-specific defaults belong in .env.local, which is ignored by git. Public docs and examples use .env.example.

Consequences

  • Run outputs are discoverable and stable across CLI, HTTP, skill, and future scheduled automation.
  • Interactive CLI use remains friendly without forcing users to remember a flag.
  • Non-interactive modes remain deterministic and automation-safe.
  • Secrets stay out of the public repo.
  • Future deep research status, config, saved evidence, and replay inputs can live under the same workdir contract.

Verification

Initial RED/GREEN tests added:

  • CLI derives scout-work/company-adobe-* from --workdir.
  • HTTP derives an output directory from SCOUT_WORKDIR when output_dir is omitted.
  • settings load .env.local after .env, so local overrides win.