Merge remote-tracking branch 'origin/full-docker-defaults' into async-action-fixes

# Conflicts:
#	foundry/CLAUDE.md
#	foundry/packages/backend/src/actors/task/workbench.ts
#	foundry/packages/frontend/src/components/dev-panel.tsx
#	foundry/packages/frontend/src/components/mock-layout.tsx
#	justfile

foundry/CLAUDE.md

@@ -31,16 +31,26 @@ Use `pnpm` workspaces and Turborepo.
 - Foundry is the canonical name for this product tree. Do not introduce or preserve legacy pre-Foundry naming in code, docs, commands, or runtime paths.
 - Install deps: `pnpm install`
 - Full active-workspace validation: `pnpm -w typecheck`, `pnpm -w build`, `pnpm -w test`
-- Start the full dev stack: `just foundry-dev`
+- Start the full dev stack (real backend + frontend): `just foundry-dev` — frontend on **port 4173**, backend on **port 7741** (Docker via `compose.dev.yaml`)
+- Start the mock frontend stack (no backend): `just foundry-mock` — mock frontend on **port 4174** (Docker via `compose.mock.yaml`)
 - Start the local production-build preview stack: `just foundry-preview`
 - Start only the backend locally: `just foundry-backend-start`
 - Start only the frontend locally: `pnpm --filter @sandbox-agent/foundry-frontend dev`
-- Start the frontend against the mock workbench client: `FOUNDRY_FRONTEND_CLIENT_MODE=mock pnpm --filter @sandbox-agent/foundry-frontend dev`
+- Start the mock frontend locally (no Docker): `just foundry-dev-mock` — mock frontend on **port 4174**
+- Dev and mock stacks can run simultaneously on different ports (4173 and 4174).
 - Stop the compose dev stack: `just foundry-dev-down`
-- Tail compose logs: `just foundry-dev-logs`
+- Tail compose dev logs: `just foundry-dev-logs`
+- Stop the mock stack: `just foundry-mock-down`
+- Tail mock logs: `just foundry-mock-logs`
 - Stop the preview stack: `just foundry-preview-down`
 - Tail preview logs: `just foundry-preview-logs`
 
+## Dev Environment Setup
+
+- `compose.dev.yaml` loads `foundry/.env` (optional) for credentials needed by the backend (GitHub OAuth, Stripe, Daytona, API keys, etc.).
+- The canonical source for these credentials is `~/misc/the-foundry.env`. If `foundry/.env` does not exist, copy it: `cp ~/misc/the-foundry.env foundry/.env`
+- `foundry/.env` is gitignored and must never be committed.
+
 ## Railway Logs
 
 - Production Foundry Railway logs can be read from a linked workspace with `railway logs --deployment --lines 200` or `railway logs <deployment-id> --deployment --lines 200`.
@@ -117,6 +127,17 @@ The client subscribes to `app` always, `workspace` when entering a workspace, `t
 - Backend mutations that affect sidebar data (task title, status, branch, PR state) must push the updated summary to the parent workspace actor, which broadcasts to workspace subscribers.
 - Comment architecture-related code: add doc comments explaining the materialized state pattern, why deltas flow the way they do, and the relationship between parent/child actor broadcasts. New contributors should understand the data flow from comments alone.
 
+## UI System
+
+- Foundry's base UI system is `BaseUI` with `Styletron`, plus Foundry-specific theme/tokens on top. Treat that as the default UI foundation.
+- The full `BaseUI` reference for available components and guidance on animations, customization, composition, and forms is at `https://base-ui.com/llms.txt`.
+- Prefer existing `BaseUI` components and composition patterns whenever possible instead of building custom controls from scratch.
+- Reuse the established Foundry theme/token layer for colors, typography, spacing, and surfaces instead of introducing ad hoc visual values.
+- If the same UI pattern is shared with the Inspector or other consumers, prefer extracting or reusing it through `@sandbox-agent/react` rather than duplicating it in Foundry.
+- If a requested UI cannot be implemented cleanly with an existing `BaseUI` component, stop and ask the user whether they are sure they want to diverge from the system.
+- In that case, recommend the closest existing `BaseUI` components or compositions that could satisfy the need before proposing custom UI work.
+- Only introduce custom UI primitives when `BaseUI` and existing Foundry patterns are not sufficient, or when the user explicitly confirms they want the divergence.
+
 ## Runtime Policy
 
 - Runtime is Bun-native.
@@ -174,7 +195,9 @@ For all Rivet/RivetKit implementation:
 - Do not build blocking flows that wait on external systems to become ready or complete. Prefer push-based progression driven by actor messages, events, webhooks, or queue/workflow state changes.
 - Use workflows/background commands for any repo sync, sandbox provisioning, agent install, branch restack/rebase, or other multi-step external work. Do not keep user-facing actions/requests open while that work runs.
 - `send` policy: always `await` the `send(...)` call itself so enqueue failures surface immediately, but default to `wait: false`.
-- Only use `send(..., { wait: true })` for short, bounded mutations that should finish quickly and do not depend on external readiness, polling actors, provider setup, repo/network I/O, or long-running queue drains.
+- Only use `send(..., { wait: true })` for short, bounded local mutations (e.g. a DB write that returns a result the caller needs). Never use `wait: true` for operations that depend on external readiness, polling actors, provider setup, repo/network I/O, sandbox sessions, GitHub API calls, or long-running queue drains.
+- Never self-send with `wait: true` from inside a workflow handler — the workflow processes one message at a time, so the handler would deadlock waiting for the new message to be dequeued.
+- When an action is void-returning and triggers external work, use `wait: false` and let the UI react to state changes pushed by the workflow.
 - Request/action contract: wait only until the minimum resource needed for the client's next step exists. Example: task creation may wait for task actor creation/identity, but not for sandbox provisioning or session bootstrap.
 - Read paths must not force refresh/sync work inline. Serve the latest cached projection, mark staleness explicitly, and trigger background refresh separately when needed.
 - If a workflow needs to resume after some external work completes, model that as workflow state plus follow-up messages/events instead of holding the original request open.