@@ -0,0 +1,14 @@
+---
+'@ogs-tech/press-web': patch
+---
+
+fix(cli): `press build` surfaces the failing subprocess's real exit code
+
+`util/run.ts` now rejects with a `SubprocessError` carrying the child's real
+`code` (and `signal`), and `bin/press.ts` re-exits with it instead of a blanket
+`1`. Before, any failing step in `press build` (`strapi build` / `next build`)
+collapsed to exit `1`, weakening the "truthful failure" guarantee that `dev.ts`
+already upholds via `waitForReadyOrExit` — a CMS build failing with a specific
+code was indistinguishable from any other error in CI. `press dev`'s pre-boot
+`seed`/`sync-types` steps become truthful for free (same `run()` helper). No
+behavior change on success (exit 0).
@@ -20,12 +20,15 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
+      # Guard the committed versions.generated.ts BEFORE `pnpm build` runs — the cli's
+      # build script is `gen:versions && tsc` (WRITE mode), which would regenerate the
+      # file in the runner's tree and mask a stale commit. Must stay above `pnpm build`.
+      - run: pnpm --filter @ogs-tech/create-press gen:versions --check
+
       - run: pnpm build
 
       - run: pnpm -r --if-present typecheck
 
       - run: pnpm -r test
 
-      - run: pnpm --filter @ogs-tech/press-cli gen:versions --check
-
       - run: pnpm pack:check
@@ -0,0 +1,75 @@
+# BASE/CLI — tracked follow-ups (2026-07-11)
+
+Surfaced by the BASE/CLI closing review. These are **not** blockers for closing
+the CRM task — the DONE criteria are met (see the review summary). They are the
+robustness/cleanup gaps we consciously deferred. Each is independently shippable
+as its own PR (do not bundle — separate concerns).
+
+The task-closing PR fixed only the two "truthful failure" defects:
+- CI `gen:versions --check` gate made real (wrong `--filter` name + step ordered
+  after `pnpm build`, which regenerated the file before the check could see drift).
+- `press build` now surfaces the subprocess's real exit code (`SubprocessError`
+  in `util/run.ts` + `bin/press.ts`), matching `dev.ts`.
+
+---
+
+## 1. End-to-end + orchestration tests
+
+**Gap.** The two most important commands — `devCommand` (`packages/web/src/commands/dev.ts`)
+and `buildCommand` (`build.ts`) — have **no direct tests**. Their primitives
+(`waitForReadyOrExit`, `watchSchema`, `materialize`, `run`) are well covered, but
+the orchestration itself (6-step boot sequence, `killAll`, SIGINT/SIGTERM
+handlers, the `cms.exit`/`web.exit` race, the `shuttingDown` flag) is validated
+only by manual `pnpm dev` dogfooding. Likewise, `@ogs-tech/create-press` has no
+test that runs the **published binary** (`bin/create-press.js` → `dist/cli.js` →
+real `pnpm install`); `scaffold()` is tested in isolation and only exercised from
+TS source via `scripts/create-playground.ts`.
+
+**Do.**
+- Unit-level orchestration tests for `dev.ts`/`build.ts` by injecting a spawn/`run`
+  seam (mock children like `wait-for-ready-or-exit.test.ts`'s `FakeChild`): assert
+  the boot order, that a cms crash aborts before booting web, that SIGINT exits 0,
+  and that an unexpected child exit re-exits with its real code.
+- A Playwright/e2e smoke (already named as planned in the root README): scaffold a
+  temp project via the built binary, `press dev`, assert `:1337` + `:3000` serve
+  and `shared/types/generated.ts` is written.
+
+**Acceptance.** `dev.ts`/`build.ts` have coverage; a CI smoke boots a scaffolded
+project end-to-end.
+
+## 2. Documentation drift + dead code
+
+**Gap.**
+- **`press.config.ts` naming.** CLAUDE.md and the README describe build-time
+  anchors as living in `press.config.ts` at the repo root, but the scaffold emits
+  `packages/web/config.ts` (its header comment even says `// press.config.ts`).
+  No generated file is literally named/located `press.config.ts`. There is also a
+  stray `press.config.ts` at this monorepo's root with no functional link to the
+  CLI. Harmless, but it misleads anyone auditing literally.
+- **`VERSIONS.pressCli` dead field.** Computed and tested in `compute-versions.ts`
+  but never consumed by `scaffold.ts` (a scaffolded project never depends on
+  `@ogs-tech/create-press`, by design).
+- **Stale `packages/cli/dist/`.** Contains artifacts from a prior architecture
+  (`dist/commands/{dev,build,deploy}.js`, `dist/materialize.js`, …) with no `src/`
+  counterpart. `dist/` is gitignored so publish is unaffected, but it confuses a
+  manual `node bin/create-press.js` without a fresh rebuild.
+
+**Do.** Reconcile the docs to the real path (or rename the emitted file — decide
+which is canonical); drop `pressCli` from `ScaffoldVersions` (or wire it if a use
+appears); note that `dist/` must be rebuilt before manual bin inspection.
+
+**Acceptance.** Docs match the scaffold output; no computed-but-unused version field.
+
+## 3. Derive `NEXT_PIN` instead of hardcoding
+
+**Gap.** `compute-versions.ts:41` hardcodes `NEXT_PIN = '^15.1.0'` — the only
+scaffold pin not derived from a real manifest (react/strapi come from engine
+`devDependencies`; the follow-up is already noted in-code). `@ogs-tech/press-web`
+declares only an open `next: '>=15'` peer range, useless as a pin.
+
+**Do.** Add `next` to `@ogs-tech/press-web` `devDependencies` (the version the
+engine is actually tested against) and derive the pin via `requireDevDep`, exactly
+like react/strapi. Removes the last manual knob and closes the drift loop for Next.
+
+**Acceptance.** `computeVersions` derives `next` from a manifest; no `NEXT_PIN`
+constant.
@@ -1,7 +1,10 @@
 #!/usr/bin/env tsx
 import { run } from '../src/runtime-cli';
+import { SubprocessError } from '../src/util/run';
 
 run(process.argv).catch((err) => {
   console.error(err?.message ?? err);
-  process.exit(1);
+  // Surface the failing subprocess's REAL exit code (never a blanket 1) so build
+  // failures are truthful in CI; a signal-killed child (code null) still exits non-zero.
+  process.exit(err instanceof SubprocessError ? (err.code ?? 1) : 1);
 });
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { run, SubprocessError } from './run';
+
+describe('run', () => {
+  it('resolves when the command exits 0', async () => {
+    await expect(run('node', ['-e', 'process.exit(0)'])).resolves.toBeUndefined();
+  });
+
+  it('rejects with a SubprocessError that carries the REAL exit code', async () => {
+    // The whole point of press build/dev "truthful failures": a non-zero
+    // subprocess must surface ITS code, never a generic 1.
+    const err = await run('node', ['-e', 'process.exit(3)']).catch((e) => e);
+    expect(err).toBeInstanceOf(SubprocessError);
+    expect((err as SubprocessError).code).toBe(3);
+  });
+
+  it('rejects (not resolves) when the command cannot be spawned', async () => {
+    const err = await run('this-binary-does-not-exist-press', []).catch((e) => e);
+    expect(err).toBeInstanceOf(Error);
+  });
+});
@@ -9,6 +9,23 @@ export interface RunOptions {
   env?: Record<string, string | undefined>;
 }
 
+/**
+ * A subprocess that exited non-zero, carrying the REAL exit code (and signal, if
+ * killed). bin/press.ts re-exits with this code so `press build` surfaces the
+ * failing tool's own code instead of a generic 1 — the same "truthful failure"
+ * guarantee dev.ts already gives via waitForReadyOrExit.
+ */
+export class SubprocessError extends Error {
+  constructor(
+    readonly command: string,
+    readonly code: number | null,
+    readonly signal: NodeJS.Signals | null = null,
+  ) {
+    super(`${command} exited ${code ?? `(signal ${signal})`}`);
+    this.name = 'SubprocessError';
+  }
+}
+
 /** Runs a command, inheriting stdio, and resolves on exit 0 (rejects otherwise). */
 export function run(cmd: string, args: string[], opts: RunOptions = {}): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -18,8 +35,10 @@ export function run(cmd: string, args: string[], opts: RunOptions = {}): Promise
       stdio: 'inherit',
     });
     child.on('error', reject);
-    child.on('exit', (code) =>
-      code === 0 ? resolve() : reject(new Error(`${cmd} ${args.join(' ')} exited ${code}`)),
+    child.on('exit', (code, signal) =>
+      code === 0
+        ? resolve()
+        : reject(new SubprocessError(`${cmd} ${args.join(' ')}`, code, signal)),
     );
   });
 }