@fugood/bricks-project 2.24.2 → 2.24.4

package/skills/bricks-ux/references/ux-critique.md

@@ -0,0 +1,256 @@
+# UX Critique
+
+Verification proves the flow *runs*. UX critique proves the flow is *usable*. Both are required before declaring done; neither substitutes for the other.
+
+UX critique runs in parallel with visual-design critique (`bricks-design/design-critique.md`). A Canvas can fail one and pass the other; both block ship.
+
+This file is tiered. The same UX problem (e.g., closure missing) is **CRITICAL** on a payment kiosk and **MEDIUM** on a museum signage loop. Critique fails ship when CRITICAL or HIGH items go unaddressed in their applicable tiers.
+
+## How to run the pass
+
+1. **Open the journey.** Walk every interaction step-by-step using `user-journey.md` as the spine.
+2. **For each Canvas / Brick group, classify by deployment risk** (table below). The classification determines which tier of checks apply.
+3. **Run the checks in the applicable tier(s).** CRITICAL items always run; HIGH applies broadly; MEDIUM and LOW depend on classification.
+4. **Fix every CRITICAL miss and every HIGH miss.** Surface MEDIUM and LOW misses in the trade-off note if not addressed.
+5. **Re-verify after fixes.** Don't accumulate fix debt.
+
+## Risk classification by deployment shape
+
+| Deployment shape | Risk profile | Tier weighting |
+|---|---|---|
+| Payment / identity capture / safety-critical | CRITICAL-dense — every transact discipline must pass | CRITICAL + HIGH + MEDIUM all apply |
+| Self-service interactive (ordering, check-in, configuration) | HIGH-dense — journey completeness, idle reset, recovery paths | CRITICAL + HIGH apply; MEDIUM where relevant |
+| Monitoring / dashboard / control room | HIGH-dense — alarm hierarchy, stale-data trust, calm/detect/demand | CRITICAL + HIGH apply for alarm states |
+| Browse / wayfinding / menu board | MEDIUM-dense — legibility, comparison clarity, sparse states | HIGH legibility, MEDIUM elsewhere |
+| Glanceable signage / dwell / ambient loop | LOW-dense — main checks are legibility and rhythm | HIGH legibility, LOW elsewhere |
+
+## CRITICAL — blocks ship
+
+Failure on any of these is sufficient grounds to declare the work mid-iteration.
+
+### CR-1. The user-journey spine is whole
+
+Every interaction must have all seven steps present (or deliberately compressed; see `user-journey.md` § "When the seven steps compress"). Most-common holes:
+
+- **Immediate feedback missing** (step 3). User taps, nothing visible, taps again.
+- **In-flight visibility missing** (step 4). Action triggered, screen frozen, user re-triggers.
+- **Recovery as dead-end** (step 6). Error Canvas with no path forward.
+- **Closure ambiguous or missing** (step 7). Success state transient or unclear.
+
+**Must Have:** every interaction has a designed and verified affordance, instruction, feedback, in-flight state, continuation, recovery, closure — or deliberate documented collapse.
+**Anti-Pattern:** journey skipping any step on the assumption "it's fast enough not to need".
+
+### CR-2. Transact has its intensification
+
+For payment / identity / safety-critical flows, the seven steps must be tightened (`user-journey.md` § "When the seven steps intensify"):
+
+- Confirmation step before commit.
+- In-flight visibility non-skippable.
+- Recovery categorised (declined / network / cancelled / timeout).
+- Closure with weight and hold time.
+
+**Must Have:** transact closure holds ≥ 5 seconds, success unmistakable, peripheral state visible.
+**Anti-Pattern:** "Process payment in one tap" with no confirmation; closure that auto-advances in < 2s.
+
+### CR-3. Monitoring has demand discipline
+
+For dashboards / monitor screens with alarm capability:
+
+- Calm / detect / demand are three distinct designed states.
+- Demand state stands out unambiguously; not a slight colour change.
+- Multiple concurrent demand states have priority ordering already designed.
+- Stale-data is visibly declared per source.
+- Color is never the only encoding of severity.
+
+**Must Have:** alarm-state preview captured and reviewed; squint-test passes (alarm visible from peripheral vision); monochrome preview still distinguishes severity tiers.
+**Anti-Pattern:** alarm styled identically to detect-state; "stale" indicator at 8pt in corner; severity by colour alone.
+
+### CR-4. Accessibility floors met for the audience
+
+The seven accessibility disciplines (`accessibility.md`) apply at deployment-relative floors. CRITICAL when the audience includes:
+
+- Reduced-vision users (contrast, scale, color-not-only).
+- Reduced-motor users (touch targets, no precise gestures, no time-pressure auto-cancels).
+- Sensitive-to-motion users (reduced-motion path available).
+- Multilingual audience (strings via Data; type scale accommodates longest translation).
+
+**Must Have:** contrast verified under deployment-actual lighting; touch targets verified with real-finger / real-hardware testing; severity / status encoded by shape + color + label.
+**Anti-Pattern:** WCAG-compliance-on-desktop-monitor as the audit (deployment is sunlit signage at 4m); time-pressure UI on a venue that includes slow / hesitant users.
+
+### CR-5. Idle reset is clean
+
+For self-service interactive deployments:
+
+- Idle timeout exists and is calibrated to the use pattern.
+- Idle reset clears flow state — no half-built order persists; no name on screen; no half-confirmed action.
+- Reset returns to a designed idle / attractor state, not to "whatever Canvas was loaded".
+
+**Must Have:** verified idle reset behaviour via Automation or live test; verified that no leaked state persists to next session.
+**Anti-Pattern:** idle = last interact Canvas; idle that requires operator to manually reset.
+
+## HIGH — must fix before launch
+
+### H-1. Affordance is unambiguous
+
+Every pressable Brick declares "press me" visually — contrast, weight, motion, or icon. Affordance vocabulary is consistent across the deployment.
+
+**Must Have:** pressable tiles visually distinct from non-pressable; squint test confirms which Bricks are interactive.
+**Anti-Pattern:** identical-looking tiles where some are pressable and some aren't; pressable Bricks with no visual distinction from background.
+
+### H-2. Press feedback at registration
+
+Every `on_press` produces a visible state change at the moment of registration — scale, opacity, color, or new Brick entry via Standby Transition. Not a fade-in.
+
+**Must Have:** Brick under press visibly responds within 100ms (effectively snap, not fade).
+**Anti-Pattern:** press registers, no visible change; press relies on Canvas-change-only feedback (user perceives lag).
+
+### H-3. Flow states designed, not skipped
+
+Idle / loading / empty / error / boot / maintenance (as applicable to the deployment) are designed states, each with verified preview.
+
+**Must Have:** every applicable state's preview captured and reviewed; failure modes per state checked against `flow-states.md`.
+**Anti-Pattern:** "empty state is fine, the list is always populated" without testing the empty case; error state in 8pt corner text; boot = loading spinner.
+
+### H-4. Hero continuity across journey Canvases
+
+For multi-Canvas flows, hero Bricks share ids across Canvases — chrome (logo, progress indicator, time, back action) carries via Truth #3 auto-tween.
+
+**Must Have:** primary chrome elements identifiable in the same screen positions across the flow's Canvases.
+**Anti-Pattern:** every Canvas remounts its full Brick set; user loses spatial mental model between steps.
+
+### H-5. Error recovery has a path
+
+Every error state offers retry, alternate method, abandon, or help — never a dead-end. Different error categories get distinguishable recovery treatments.
+
+**Must Have:** each error path verified end-to-end via Automation or live test.
+**Anti-Pattern:** "Error. Please try again." with no retry mechanism; generic recovery for all error types.
+
+### H-6. Stale-data trust
+
+For monitoring / live-data screens, every dynamic source has a visibly declared staleness state or a visible "last update" relative-time indicator.
+
+**Must Have:** staleness visible in peripheral vision; stale value distinguishable from current value.
+**Anti-Pattern:** dynamic value with no age indication; "last update" in 8pt absolute timestamp.
+
+### H-7. Predictable navigation
+
+Navigation affordances (back, next, home) sit consistently across Canvases. Idle returns to the same idle Canvas every time.
+
+**Must Have:** back / next affordance positions verified across Canvases; idle reset produces identical idle Canvas every time.
+**Anti-Pattern:** back button at top-left on Canvas 2, bottom-right on Canvas 3; idle rotates such that the "anchor" element moves.
+
+## MEDIUM — impacts polish; prioritize by user impact
+
+### M-1. Instruction matches user mental model
+
+Action instructions ("Scan your code", "Tap to start", "Pay now") match the user's likely understanding; jargon avoided; language locale-matched.
+
+**Must Have:** wording reviewed for the actual audience; jargon removed.
+**Anti-Pattern:** "Initiate authentication sequence" on a public kiosk; English-only instruction on a multilingual venue.
+
+### M-2. Continuation is non-surprising
+
+The Canvas the user lands on after an action matches their expectation. Big jumps in journey context happen only with explicit transition.
+
+**Must Have:** continuation Canvas reviewed for context preservation; hero continuity in place.
+**Anti-Pattern:** success on Canvas A jumps to Canvas D mid-flow; user loses context.
+
+### M-3. Closure proportional to stakes
+
+Success closure hold time and visual weight match the action's stakes. Routine completions get brief acknowledgement; transact completions get held visible.
+
+**Must Have:** closure hold time tuned to action stakes; auto-advance only after enough time for the user to read.
+**Anti-Pattern:** 1.5s closure for a transact flow; 8s closure for a "saved to favorites" toast.
+
+### M-4. Density rhythm in browse / dwell
+
+For browse / dwell deployments, content rotation has variation in density / framing / colour rhythm across Canvases or slides. Three identical-rhythm Canvases in a row is a tell. (Cross-reference: `bricks-design/design-critique.md` density-rhythm collapse.)
+
+**Must Have:** rhythm variation across the sequence; no three identical-archetype Canvases in a row.
+**Anti-Pattern:** ten Canvases that all read as "headline + bullet list".
+
+### M-5. Audio cues calibrated (when hardware allows)
+
+If the deployment uses audio, volume / timing / time-of-day awareness is intentional.
+
+**Must Have:** audio volume / scheduling reviewed; success / alarm cues distinguishable from ambient.
+**Anti-Pattern:** constant-volume cues regardless of time; audio-only confirmation (no visual pair).
+
+### M-6. Reduced-motion path available (if relevant)
+
+For deployments in clinical / safety / motion-sensitive contexts, a reduced-motion path exists.
+
+**Must Have:** `reduceMotion` Data flag wired where applicable; verified reduced-motion preview.
+**Anti-Pattern:** continuous-motion design with no reduction path for a clinical deployment.
+
+## LOW — context-dependent
+
+### L-1. Polish on idle / attractor presence
+
+For deployments where idle dominates: idle is *inviting*, not just *running*.
+
+**Must Have for high-traffic public deployments:** attractor sequence engages from peripheral vision.
+**Anti-Pattern:** logo-only idle on a deployment whose purpose is to invite interaction.
+
+### L-2. Maintenance state designed
+
+If the deployment has scheduled downtime, a maintenance Canvas exists and distinguishes itself from error.
+
+**Must Have for deployments with maintenance windows:** maintenance Canvas with return path.
+**Anti-Pattern:** maintenance = black screen.
+
+### L-3. Empty-state composition
+
+Empty states explain the absence and suggest what populates.
+
+**Must Have:** empty state designed rather than collapsed-whitespace.
+**Anti-Pattern:** "—" or blank where content would be.
+
+## Tier-by-tier checklist (running order)
+
+Use this when running the pass:
+
+**CRITICAL (always run):**
+
+- [ ] User-journey spine whole (CR-1)
+- [ ] Transact intensified if applicable (CR-2)
+- [ ] Monitoring demand discipline if applicable (CR-3)
+- [ ] Accessibility floors met (CR-4)
+- [ ] Idle reset clean if applicable (CR-5)
+
+**HIGH (always run except for glance / dwell loops):**
+
+- [ ] Affordance unambiguous (H-1)
+- [ ] Press feedback at registration (H-2)
+- [ ] Flow states designed (H-3)
+- [ ] Hero continuity across Canvases (H-4)
+- [ ] Error recovery has a path (H-5)
+- [ ] Stale-data trust if applicable (H-6)
+- [ ] Predictable navigation (H-7)
+
+**MEDIUM (run for interact / transact / browse):**
+
+- [ ] Instruction matches mental model (M-1)
+- [ ] Continuation non-surprising (M-2)
+- [ ] Closure proportional (M-3)
+- [ ] Density rhythm (M-4)
+- [ ] Audio cues calibrated (M-5)
+- [ ] Reduced-motion path (M-6)
+
+**LOW (run for public-facing / high-dwell):**
+
+- [ ] Idle / attractor polish (L-1)
+- [ ] Maintenance state (L-2)
+- [ ] Empty-state composition (L-3)
+
+## Definition of UX done
+
+A flow is UX-done when:
+
+1. The CRITICAL tier passes — zero unaddressed CRITICAL items.
+2. The HIGH tier passes — zero unaddressed HIGH items (or surfaced as accepted trade-off with rationale).
+3. Applicable MEDIUM / LOW items either pass or are surfaced.
+4. Every state (golden path + error categories + idle + empty if relevant) has been verified via preview screenshot or Automation, and reviewed.
+5. Accessibility floors are met at the deployment-relative threshold, not at a desktop default.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.

package/tools/_git-author.ts

@@ -15,7 +15,15 @@ async function hasGitIdentity(cwd: string): Promise<boolean> {
 // If no identity is configured (typical for non-tech users), CTOR becomes the
 // main author via per-command `-c user.name/-c user.email` overrides so the
 // user's git config is left untouched.
-export async function buildCommitArgs(cwd: string, messages: string[]): Promise<string[]> {
+//
+// `extraFlags` are inserted between `commit` and the `-m` args (e.g.
+// `['--no-verify']` to bypass pre-commit hooks for controlled cases like
+// committing merge-conflict markers).
+export async function buildCommitArgs(
+  cwd: string,
+  messages: string[],
+  extraFlags: string[] = [],
+): Promise<string[]> {
   const hasIdentity = await hasGitIdentity(cwd)
   const prefix = hasIdentity
     ? []
@@ -23,7 +31,7 @@ export async function buildCommitArgs(cwd: string, messages: string[]): Promise<
   const msgArgs: string[] = []
   for (const m of messages) msgArgs.push('-m', m)
   if (hasIdentity) msgArgs.push('-m', CTOR_COAUTHOR_TRAILER)
-  return [...prefix, 'commit', ...msgArgs]
+  return [...prefix, 'commit', ...extraFlags, ...msgArgs]
 }
 
 export { CTOR_NAME, CTOR_EMAIL, CTOR_COAUTHOR_TRAILER }

package/tools/_last-pushed-commit.ts

@@ -0,0 +1,28 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+
+// Local sync marker: the git commit hash that was on HEAD when we last
+// successfully pushed to the server (deploy or update-config) or pulled
+// from it. Stored at the `.bricks/` top level (gitignored explicitly) — it's
+// per-clone state, not a build artifact, so it doesn't belong under
+// `.bricks/build/`.
+//
+// Why this exists: server's `bricks_project_last_commit_id` can be an opaque
+// nanoid for content-only edits (config-editor saves), so it isn't a
+// reliable git anchor for `git checkout` during pull. The local marker is
+// always a real reachable commit hash from THIS clone.
+const REL_PATH = '.bricks/.last-pushed-commit'
+
+export async function readLastPushedCommit(cwd: string): Promise<string | null> {
+  try {
+    const content = await readFile(`${cwd}/${REL_PATH}`, 'utf8')
+    return content.trim() || null
+  } catch {
+    return null
+  }
+}
+
+export async function writeLastPushedCommit(cwd: string, commitId: string): Promise<void> {
+  if (!commitId) return
+  await mkdir(`${cwd}/.bricks`, { recursive: true })
+  await writeFile(`${cwd}/${REL_PATH}`, commitId)
+}

package/tools/deploy.ts

@@ -2,6 +2,11 @@ import { access, readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
 import { buildCommitArgs } from './_git-author'
+import { writeLastPushedCommit } from './_last-pushed-commit'
+
+if (!process.env.BRICKS_RELEASE_SIGN) {
+  process.env.BRICKS_RELEASE_SIGN = 'CTOR'
+}
 
 const cwd = process.cwd()
 
@@ -141,6 +146,10 @@ await writeFile(configPath, JSON.stringify(releaseConfig))
 
 const args = ['bricks', command, 'release', app.id, '-c', configPath, '--json']
 
+if (app.name) {
+  args.push('--name', app.name)
+}
+
 if (version) {
   args.push('--version', version)
 }
@@ -162,4 +171,10 @@ if (result.exitCode !== 0) {
 }
 
 const output = JSON.parse(result.stdout.toString())
+
+// Record the commit we just pushed from so a later pull can use it as the
+// merge base regardless of what the server stores in
+// bricks_project_last_commit_id.
+if (commitId) await writeLastPushedCommit(cwd, commitId)
+
 console.log(`${isModule ? 'Module' : 'App'} deployed: ${output.name}`)

package/tools/preview-main.mjs

@@ -6,6 +6,12 @@ import { createServer } from 'http'
 import { parseArgs } from 'util'
 import * as TOON from '@toon-format/toon'
 
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (err) => {
+    if (err.code !== 'EPIPE') throw err
+  })
+}
+
 const { values } = parseArgs({
   args: process.argv,
   options: {
@@ -224,16 +230,23 @@ app.on('ready', () => {
     )
     if (takeScreenshotConfig) {
       const { delay, width, height, path } = takeScreenshotConfig
-      setTimeout(() => {
+      setTimeout(async () => {
+        let screenshotFailed = false
         console.log('Taking screenshot')
-        mainWindow.webContents.capturePage().then((image) => {
+        try {
+          const image = await mainWindow.webContents.capturePage()
           console.log('Writing screenshot to', path)
-          writeFile(path, image.resize({ width, height }).toJPEG(75))
+          await writeFile(path, image.resize({ width, height }).toJPEG(75))
+        } catch (err) {
+          screenshotFailed = true
+          console.error('Screenshot capture/write failed', err)
+        } finally {
           if (noKeepOpen) {
             console.log('Closing app')
-            app.quit()
+            if (screenshotFailed) app.exit(1)
+            else app.quit()
           }
-        })
+        }
       }, delay)
     }
   }

package/tools/pull.ts

@@ -1,7 +1,31 @@
-import { readFile, writeFile } from 'node:fs/promises'
+import { readdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
 import { format } from 'oxfmt'
 import { sh } from './_shell'
 import { buildCommitArgs } from './_git-author'
+import { readLastPushedCommit, writeLastPushedCommit } from './_last-pushed-commit'
+
+// Directories whose .ts contents are entirely owned by the generator.
+// Anything under these dirs not present in the freshly pulled file list is an orphan.
+const ownedTsDirs = ['subspaces', 'automation-tests']
+
+async function walkTsFiles(dir: string, baseDir: string): Promise<string[]> {
+  if (!existsSync(dir)) return []
+  const result: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+  await Promise.all(
+    entries.map(async (entry) => {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        result.push(...(await walkTsFiles(full, baseDir)))
+      } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+        result.push(relative(baseDir, full))
+      }
+    }),
+  )
+  return result
+}
 
 const cwd = process.cwd()
 const args = process.argv.slice(2)
@@ -52,30 +76,40 @@ if (result.exitCode !== 0) {
   }
 }
 
-const { files, lastCommitId } = JSON.parse(result.stdout.toString())
+const { files, lastCommitId: serverLastCommitId } = JSON.parse(result.stdout.toString())
+
+// The locally-saved commit (recorded by deploy/update-config) is the
+// authoritative merge base for THIS clone — the server's value can be an
+// opaque nanoid (config-only updates) or point to a commit other clients
+// produced. Fall back to the server's value only if we have no local
+// record yet.
+const savedLocalCommitId = await readLastPushedCommit(cwd)
+const baseCommitId = savedLocalCommitId || serverLastCommitId
+
+const branchName = isModule
+  ? 'BRICKS_PROJECT_try-pull-module'
+  : 'BRICKS_PROJECT_try-pull-application'
 
-let useMain = false
 if (isGitRepo && !force) {
-  console.log(`Checking commit ${lastCommitId}...`)
-  const found = (await sh`cd ${cwd} && git rev-list -1 ${lastCommitId}`.nothrow().text())
+  console.log(`Checking commit ${baseCommitId}...`)
+  const found = (await sh`cd ${cwd} && git rev-list -1 ${baseCommitId}`.nothrow().text())
     .trim()
     .match(/^[\da-f]{40}$/)
 
-  const commitId = (await sh`cd ${cwd} && git rev-parse HEAD`.text()).trim()
+  const headCommitId = (await sh`cd ${cwd} && git rev-parse HEAD`.text()).trim()
 
-  if (commitId === lastCommitId) throw new Error('Commit not changed')
-
-  const branchName = isModule
-    ? 'BRICKS_PROJECT_try-pull-module'
-    : 'BRICKS_PROJECT_try-pull-application'
+  if (headCommitId === serverLastCommitId) throw new Error('Commit not changed')
 
   await sh`cd ${cwd} && git branch -D ${branchName}`.nothrow()
 
+  // When the base commit isn't reachable in this clone (server stored a
+  // nanoid, or the commit was pruned), fall back to forking from current
+  // HEAD. The downstream merge into main collapses both paths into the
+  // same result, just with different merge bases.
   if (found) {
-    await sh`cd ${cwd} && git checkout -b ${branchName} ${lastCommitId}`.nothrow()
+    await sh`cd ${cwd} && git checkout -b ${branchName} ${baseCommitId}`.nothrow()
   } else {
     await sh`cd ${cwd} && git checkout -b ${branchName}`
-    useMain = true
   }
 }
 
@@ -89,6 +123,23 @@ const oxfmtConfig = await readFile(`${cwd}/.oxfmtrc.json`, 'utf8')
     printWidth: 100,
   }))
 
+const expectedFiles = new Set(files.map((file: { name: string }) => file.name))
+
+// Remove orphan .ts files under generator-owned directories before writing.
+// File paths are produced by buildApplicationFiles and use forward slashes,
+// so normalise the walked paths the same way for comparison.
+const orphans: string[] = []
+await Promise.all(
+  ownedTsDirs.map(async (dir) => {
+    const existing = await walkTsFiles(join(cwd, dir), cwd)
+    for (const file of existing) {
+      const normalized = file.split(/[\\/]/).join('/')
+      if (!expectedFiles.has(normalized)) orphans.push(normalized)
+    }
+  }),
+)
+await Promise.all(orphans.map((name) => unlink(`${cwd}/${name}`)))
+
 await Promise.all(
   files.map(async (file: { name: string; input: string; formatable?: boolean }) => {
     let content = file.input
@@ -112,11 +163,35 @@ if (isGitRepo) {
     const commitArgs = await buildCommitArgs(cwd, [commitMsg])
     await sh`cd ${cwd} && git ${commitArgs}`
   }
-  if (!force && !useMain) {
-    await sh`cd ${cwd} && git merge main`
+  if (!force) {
+    // Land the pulled commits on main with a single 3-way merge using
+    // baseCommit as the merge base. The user doesn't have to manage a side
+    // branch, and conflicts (if any) land in the working tree on main where
+    // auto-compile surfaces them as typecheck errors to resolve in-place.
+    await sh`cd ${cwd} && git checkout main`
+    const mergeResult = await sh`cd ${cwd} && git merge ${branchName} --no-edit`.nothrow()
+    if (mergeResult.exitCode !== 0) {
+      // Conflict markers are in the working tree — commit them so the tree
+      // is clean for auto-compile to detect, leaving the resolution to the
+      // user. Pre-commit hooks would reject markers (lint/format fail on
+      // invalid syntax), so bypass them for this controlled case.
+      await sh`cd ${cwd} && git add .`
+      const conflictArgs = await buildCommitArgs(
+        cwd,
+        ['chore(project): merge with conflicts (resolve in main)'],
+        ['--no-verify'],
+      )
+      await sh`cd ${cwd} && git ${conflictArgs}`
+    }
+    // The try-pull branch served its purpose; delete it so `git branch`
+    // stays tidy. The next pull recreates it anyway (line 103).
+    await sh`cd ${cwd} && git branch -D ${branchName}`.nothrow()
   }
+  // Record the new sync point so a follow-up pull starts from the right base.
+  const newHead = (await sh`cd ${cwd} && git rev-parse HEAD`.nothrow().text()).trim()
+  if (newHead) await writeLastPushedCommit(cwd, newHead)
 }
 
 console.log(
-  `${isModule ? 'Module' : 'App'} project pulled: ${files.length} files${force ? ' (force)' : ''}`,
+  `${isModule ? 'Module' : 'App'} project pulled: ${files.length} files${orphans.length ? `, removed ${orphans.length} orphan .ts file${orphans.length === 1 ? '' : 's'}` : ''}${force ? ' (force)' : ''}`,
 )

package/tools/update-config.ts

@@ -0,0 +1,118 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { parseArgs } from 'util'
+import { sh } from './_shell'
+import { buildCommitArgs } from './_git-author'
+import { writeLastPushedCommit } from './_last-pushed-commit'
+
+const cwd = process.cwd()
+
+const readJson = async (p: string) => JSON.parse(await readFile(p, 'utf8'))
+
+const {
+  values: { 'auto-commit': autoCommit, 'no-check': noCheck, 'no-validate': noValidate, yes, help },
+} = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    'auto-commit': { type: 'boolean' },
+    'no-check': { type: 'boolean' },
+    'no-validate': { type: 'boolean' },
+    yes: { type: 'boolean', short: 'y' },
+    help: { type: 'boolean', short: 'h' },
+  },
+  allowPositionals: true,
+})
+
+if (help) {
+  console.log(`Push compiled config to BRICKS without creating a release.
+
+Options:
+  --auto-commit              Auto-commit unstaged changes before pushing
+  --no-check                 Skip the conflict guard (don't pass --last-commit-id)
+  --no-validate              Skip server-side config schema validation
+  -y, --yes                  Skip all prompts
+  -h, --help                 Show this help message`)
+  process.exit(0)
+}
+
+// Detect git repo (mirrors deploy.ts)
+const { exitCode } = await sh`cd ${cwd} && git status`.quiet().nothrow()
+const isGitRepo = exitCode === 0
+
+if (!isGitRepo && !yes) {
+  const confirmContinue = prompt('No git repository found, continue? (y/n)')
+  if (confirmContinue !== 'y') throw new Error('Update cancelled')
+}
+
+// Read application.json + compiled config
+const app = await readJson(`${cwd}/application.json`)
+const config = await readJson(`${cwd}/.bricks/build/application-config.json`)
+
+// Handle unstaged changes the same way deploy.ts does.
+let commitId = ''
+let parentCommitId = ''
+if (isGitRepo) {
+  const unstagedChanges = await sh`cd ${cwd} && git diff --name-only --diff-filter=ACMR`.text()
+  if (unstagedChanges) {
+    if (autoCommit) {
+      // Capture the pre-commit HEAD so we can use it as the conflict-check
+      // baseline (the server should still hold it from the prior deploy).
+      parentCommitId = (await sh`cd ${cwd} && git rev-parse HEAD`.nothrow().text()).trim()
+      await sh`cd ${cwd} && git add -A`
+      const commitArgs = await buildCommitArgs(cwd, ['chore: update bricks config'])
+      await sh`cd ${cwd} && git ${commitArgs}`
+    } else {
+      throw new Error('Unstaged changes found, please commit or stash your changes before updating')
+    }
+  }
+  commitId = (await sh`cd ${cwd} && git rev-parse HEAD`.text()).trim()
+}
+
+// Auto-derive --last-commit-id for the server-side conflict guard.
+//   - parent of the auto-commit (server still holds it from the prior deploy)
+//   - current HEAD (clean tree — server should be at the same commit too)
+let lastCommitId: string | undefined
+if (!noCheck) {
+  if (parentCommitId) lastCommitId = parentCommitId
+  else if (commitId) lastCommitId = commitId
+}
+
+if (!yes) {
+  const confirm = prompt('Are you sure you want to push the new config? (y/n)')
+  if (confirm !== 'y') throw new Error('Update cancelled')
+}
+
+const isModule = app.type === 'module'
+const command = isModule ? 'module' : 'app'
+
+const updateConfig = {
+  ...config,
+  bricks_project_last_commit_id: commitId || undefined,
+}
+const configPath = `${cwd}/.bricks/build/update-config.json`
+await writeFile(configPath, JSON.stringify(updateConfig))
+
+const args = ['bricks', command, 'update', app.id, '-f', configPath, '--json']
+if (noValidate) args.push('--no-validate')
+if (lastCommitId) args.push('--last-commit-id', lastCommitId)
+
+const result = await sh`${args}`.quiet().nothrow()
+
+if (result.exitCode !== 0) {
+  const output = result.stderr.toString() || result.stdout.toString()
+  try {
+    const json = JSON.parse(output)
+    throw new Error(json.error?.message || json.error || 'Update failed')
+  } catch {
+    throw new Error(output || 'Update failed')
+  }
+}
+
+const output = JSON.parse(result.stdout.toString())
+
+// Record the commit we just pushed from so a later pull can use it as the
+// merge base regardless of what the server stores in
+// bricks_project_last_commit_id (which may be an opaque nanoid for
+// content-only edits).
+if (commitId) await writeLastPushedCommit(cwd, commitId)
+
+console.log(`${isModule ? 'Module' : 'App'} config updated: ${output.target?.name || app.name}`)