run-guide — make it build, make it run, then write down the route that worked

run-guide — make it build, make it run, then write down the route that worked

The verification phase. document-project wrote build/run steps tagged ⚠️ unverified; this skill runs the loop that proves or corrects them, then distills the happy path into RUN.md. It is where "looks right on paper" meets "actually boots".

Language

RUN.md is human-facing → write it in ONBOARDING_LANG (env var, default ru; en/other to override), translating only prose — every command, env-key name, port and path stays verbatim. The working state (journey-log.md, project-map.md) and the generated scripts are agent-facing → always English. (Full policy in the orchestrator's AGENTS.md.)

Loop engineering: bounded, stateful, resumable

Two loops — build, then run — each the same shape:

attempt → observe the real failure → form ONE hypothesis → apply the smallest
fix → RECORD it → retry        (until green, or budget exhausted)

Rules that make the loop safe and durable:

• One change per iteration. Change one thing, retry, read the new error. Never batch fixes — you lose which one worked.
• State lives on disk, not in context. Append every iteration to docs/onboarding/journey-log.md before retrying (format below). The LLM context is ~100k and resets with only a summary — the journey log is the memory that survives. On resume, read it and continue from the last open step.
• Budget the loop. Cap retries (e.g. 6 per phase). On exhaustion, stop and report the wall with its evidence — do not thrash.
• Secrets come from the human. When a failure needs a credential/token/key you cannot derive (DB password, registry cert, API key), pause and ask the user. Write the value into the local .env (never into a doc, a commit, or the journey log — log only the key name and that it was supplied).
• Read logs, don't guess. The next fix is almost always named in the last failure's output (wrong Java version, missing cert, "connection refused" to a