UX improvement: distinguish wrong-cwd from missing build strategy; print next-step footer after `dot mod`

[ottovlotto]

Context

dot mod scaffolds a project as a sibling directory of the user's cwd but doesn't (and can't) change the parent shell's cwd. If the user then opens Claude / RevX / their IDE from the parent directory, every subsequent dot build / dot deploy runs from a directory with no package.json and fails with:

No build strategy detected. Add a "build" script to package.json, or install vite/next/typescript.

That error message points at the wrong fix: it suggests editing the project's package.json, but the project is fine — the user just isn't in it. Reproduced today against paritytech/Rock-Paper-Scissors while triaging a (false) "RPS is missing a build script" hard-blocker. From inside the project, dot build succeeds via the vite framework-hint fallback (npm exec vite build); from the parent dir, it fails with the misleading error.

Suggested improvements

In rough priority order:

1. Disambiguate the error in src/utils/build/detect.ts

detectBuildConfig (around line 228) currently throws the same message whether the cwd has no package.json at all, or has one with neither a build script nor a recognised framework. Split those cases:

• No package.json in cwd: "No package.json found in <cwd> — are you in your project directory? Try cd <subdir> first, or pass the path: dot deploy <dir>."
• package.json present but unrecognised: keep the current message.

This single string change closes the entire "wrong directory" class of confused bug reports.

2. dot mod prints a "Next step" footer

After scaffolding finishes, print:

▶ Next: cd <scaffolded-dir>
  then run `dot deploy --playground` (or open Claude/RevX in that directory)

Cheap UX polish; catches the gotcha at the exact moment it would save the user.

3. Positional arg for dot build / dot deploy

dot deploy <dir> and dot build <dir> would let the user (or Claude / RevX / CI) pass the project path explicitly, sidestepping the cwd issue entirely. Useful in agent contexts where the agent's cwd is often one level above the project.

Repro

cd ~                                            # one level above project
dot mod rock-paper-scissors                     # scaffolds ~/rock-paper-scissors08-XXXXX/
# (shell cwd is still ~)
dot build                                       # → "No build strategy detected"
cd rock-paper-scissors08-XXXXX
dot build                                       # → succeeds via npm exec vite build

Workaround in the meantime

Document in the user-facing flow: after dot mod <name>, cd into the new project directory before opening Claude / RevX / any other tooling. Or launch Claude pointed at the project directly (claude /path/to/project).

[ottovlotto]

@UtkarshBhardwaj007 additional from testathon feedback

Session 02 testathon (2026-05-20) reproduced this exact gap. Two testers hit it in different ways:

• Francisco — dot mod didn't tell him to cd into the new directory; subsequent commands ran from the wrong cwd.
• Torsten — "Please warn that this command will create a new project in the current work directory." — felt blindsided by dot mod writing files into cwd without pre-warning.

Captured as B15 in the testathon bug list. Combines what this issue already covers (post-mod footer + wrong-cwd error disambiguation) with one extra ask: a one-liner before cloning so the user knows what's about to happen on disk — e.g. Cloning <repo> into ./<dir>/.

[ottovlotto]

Automated comment: related to #255 from the DevEx Audit (External, 3 June 2026). Audit confirmed the missing-cd-hint as live user friction (plus a separate bug: post-mod hint references a non-existent --quest flag).