boxdown 1.0.0 → 1.2.0

package/README.md

@@ -28,7 +28,7 @@ npm install -g boxdown
 You can also run it without installing:
 
 ```sh
-npx boxdown start
+npx boxdown setup
 ```
 
 ## Usage
@@ -36,22 +36,46 @@ npx boxdown start
 From any project repository on your host:
 
 ```sh
-npx boxdown start
+npx boxdown setup
 ```
 
-Boxdown builds or reuses a Dev Container for the current directory, then opens a shell inside it. The target repository stays clean; Boxdown writes generated configuration and SSH keys under user cache/data directories instead of copying `.devcontainer/` into the project.
+Boxdown builds or reuses a Dev Container for the current directory and installs
+an SSH alias for remote tools. The target repository stays clean; Boxdown writes
+generated configuration and SSH keys under user cache/data directories instead
+of copying `.devcontainer/` into the project.
+
+Startup commands print concise progress by default and hide raw Docker,
+Dev Containers, and lifecycle hook logs unless a step fails. Add `--verbose` to
+stream the full command output while setup/start work runs. Boxdown also keeps
+one append-only per-workspace command log under its data directory; `boxdown
+status` shows the exact path. Interactive shell, agent, and tunnel session bytes
+are not tee'd into the log.
+
+Open an interactive shell inside the container when you need one:
+
+```sh
+npx boxdown start
+```
 
 Boxdown ships and invokes its own `@devcontainers/cli` dependency. It does not require a host/global Dev Containers CLI install.
 
 ### Portless SSH
 
-Install an SSH alias for the current project:
+`boxdown setup` installs an SSH alias for the current project. To only install
+or update that alias without starting the devcontainer, use the lower-level SSH
+command:
 
 ```sh
-npx boxdown ssh-config install
+npx boxdown ssh install
 ```
 
-By default this creates a `<repo-name>-devcontainer` SSH host. Validate it with:
+This creates a `<repo-name>-devcontainer` SSH host. When run in an interactive
+terminal, Boxdown also asks whether to install optional targets such as Codex
+and Claude.
+Non-interactive runs skip optional targets and print the explicit `--target`
+form to use in scripts.
+
+Validate the SSH alias with:
 
 ```sh
 ssh <repo-name>-devcontainer 'whoami && pwd'
@@ -59,32 +83,95 @@ ssh <repo-name>-devcontainer 'whoami && pwd'
 
 Use the same alias in Cursor, Claude, Codex, or any SSH-capable tool.
 
+To also add the project to Codex's remote project sidebar or Claude's SSH
+remote list, pass one or more targets during setup or select them from the
+lower-level SSH prompt:
+
+```sh
+npx boxdown setup --target codex
+npx boxdown setup --target claude
+```
+
+The lower-level SSH command also supports the same targets for scripts:
+
+```sh
+npx boxdown ssh install --target codex
+npx boxdown ssh install --target claude
+```
+
+Restart the target app after installing it so it applies the updated remote
+project config.
+
+From the target project directory, forward a dev server running inside the
+container to your host browser:
+
+```sh
+npx boxdown tunnel --port 3030
+```
+
+If `--port` is omitted in an interactive terminal, Boxdown asks which port or
+port mappings to forward and defaults to the generated devcontainer published
+port when available. Non-interactive runs still require `--port`.
+
+This keeps a foreground SSH tunnel open until you press Ctrl-C. The host and
+Codex in-app browser can then open `http://localhost:3030/`. Repeat `--port`
+or use `<local:remote>` mappings when needed:
+
+```sh
+npx boxdown tunnel --port 3030 --port 8080:3031
+```
+
+Use `--workspace <path>` only when running the command from a different
+directory. Repeat it with `down` to remove multiple workspace containers in one
+command. When `down` runs from a directory that is not a known Boxdown
+workspace, interactive terminals show a workspace picker instead.
+
+Remove Boxdown's managed SSH host block and matching Codex/Claude app entries
+when you no longer need the alias:
+
+```sh
+npx boxdown ssh uninstall
+```
+
 ### Commands
 
 ```sh
+boxdown setup
 boxdown start
 boxdown codex
 boxdown claude
-boxdown cc
 boxdown opencode
 boxdown antigravity
 boxdown list
 boxdown status
 boxdown stop
 boxdown down
+boxdown purge
 boxdown doctor
-boxdown ssh-config install
+boxdown ssh install
+boxdown ssh uninstall
 boxdown ssh-proxy
+boxdown tunnel --port 3030
 boxdown refresh-gh-token
 boxdown refresh-gh-token-running
 ```
 
 `boxdown shell` remains supported as an alias for `boxdown start`, but
 documentation uses `start` as the canonical command.
+`boxdown cc` remains supported as an alias for `boxdown claude`, but
+documentation uses `claude` as the canonical command.
+
+`boxdown setup` begins with a host-readiness preflight before it prompts for
+SSH targets, writes workspace state, or starts Docker work. Required failures
+such as an unavailable Docker daemon stop setup with an actionable summary.
+When a local Docker image is available, the preflight also performs a no-pull,
+no-start bind-mount probe for the workspace and Boxdown-managed mount paths.
+Run `boxdown doctor` directly for the complete diagnostic report; an unavailable
+best-effort mount probe is reported as a warning and does not block setup.
 
-The coding-agent commands start or reuse the devcontainer, refresh the selected
-CLI, then launch it directly inside the container. Use `--` to pass arguments to
-the agent:
+Container bring-up installs Codex and Claude Code by default. The OpenCode and
+Antigravity commands stay available, but install/update those CLIs only when you
+launch them. Use `--` to pass arguments to the selected agent:
 
 ```sh
 boxdown claude -- --continue
@@ -94,18 +181,54 @@ List Boxdown-known devcontainer environments from any directory:
 
 ```sh
 boxdown list
+boxdown list --details
 boxdown list --json
+boxdown list --format json
 ```
 
+Human `boxdown list` output shows `STATE`, `REPO`, `PATH`, and `CONTAINER`.
+Use `boxdown list --details` when you need full copyable paths and SSH aliases
+in human output. Use `boxdown list --json` or `boxdown list --format json` for
+the same structured inventory.
+
 Shared options:
 
 ```sh
---workspace <path>  # target project directory, defaults to cwd
+--workspace <path>  # target project directory, defaults to cwd; repeatable with down; purge also accepts list values
 --alias <name>      # SSH alias, defaults to <repo-name>-devcontainer
+--target <name>     # with setup/ssh install, optional target; repeatable; supported: codex, claude
+--port <port>       # tunnel port for `boxdown tunnel`; repeatable
 --recreate          # recreate the devcontainer before starting
 --json              # JSON output for status and list
+--format json       # JSON output for status and list; equivalent to --json
+--details           # detailed human output for list
+```
+
+Use `boxdown purge` when you want to remove the workspace's Boxdown-managed
+environment residue: the devcontainer, its exact recorded Docker image, managed
+SSH/Codex/Claude entries, command log, and Boxdown cache/data for that
+workspace. It does not delete the local repository directory or files inside it.
+Interactive terminals ask for confirmation before purging.
+
+For `purge`, `--workspace` accepts the `PATH` or unambiguous `REPO` value
+shown by `boxdown list`. It also accepts exact `SSH ALIAS` values from
+`boxdown status`, `boxdown list --details`, or JSON list output:
+
+```sh
+boxdown purge
+boxdown purge --workspace my-repo-devcontainer
+boxdown purge --workspace my-repo
+boxdown purge --workspace /path/to/my-repo
 ```
 
+When `boxdown purge` runs without `--workspace` from a directory that is not a
+tracked Boxdown workspace, interactive terminals show a multi-select list of all
+tracked workspaces, including missing/stale entries. The focused row highlights
+the state token: `running` is green, `exited` is yellow, and `absent`,
+`missing`, or `unknown` are red. Non-interactive runs fail safely from
+untracked directories; scripts should call `boxdown purge --workspace <value>`
+for each workspace.
+
 ## Contributing
 
 Please consult [CONTRIBUTING](./CONTRIBUTING.md) for guidelines on contributing to this project.

package/assets/devcontainer/README.md

@@ -1,11 +1,11 @@
 # Dev container
 
-Run this project in a **consistent Node.js 24 + TypeScript** environment without installing toolchains on your machine. Dependencies install automatically; your repo is the workspace inside the container.
+Run this project in a **consistent Node.js 24 + TypeScript** environment without installing toolchains on your machine. The container starts from the slim Node 24 Debian image, then adds only the shared tools Boxdown needs. Dependencies install automatically; your repo is the workspace inside the container.
 
 ## Why use it?
 
-- **Same stack for everyone** — Node 24, pnpm, and tooling match CI and collaborators.
-- **Fast onboarding** — Open the folder in a container; `pnpm install` and local git tweaks run once after create.
+- **Same stack for everyone** — Node 24 plus pinned features provide Git, uv, ripgrep, GitHub CLI, and common shell utilities; Debian Python is installed during post-create.
+- **Fast onboarding** — Open the folder in a container; dependency installation and local git tweaks run once after create. pnpm-based workspaces bootstrap `pnpm@11` when needed.
 - **Host secrets, container dev** — `ANTHROPIC_API_KEY` and `SNYK_TOKEN` are passed from your Mac/Linux session into the container when set locally (see below).
 - **Optional CLI workflow** — Use `start.sh` if you prefer a terminal-driven container instead of only the editor.
 - **Portless SSH workflow** — Install a normal SSH host alias that proxies into the devcontainer without publishing an SSH port.
@@ -14,15 +14,27 @@ Run this project in a **consistent Node.js 24 + TypeScript** environment without
 
 | File | Role |
 | ---- | ---- |
-| `devcontainer.json` | Image, mounts (e.g. your `~/.gitconfig`), lifecycle commands, env forwarding. |
+| `devcontainer.json` | Slim Node base image, pinned feature set/order, Boxdown state mounts, lifecycle commands, env forwarding. |
 | `start.sh` | Brings the dev container up with the Dev Containers CLI, then opens a shell **inside** the container or acts as an SSH `ProxyCommand`. |
 | `ssh-config-install.sh` | Installs/updates a host SSH config alias for Cursor, Claude, or plain `ssh`. |
 | `hooks/initialize.sh` | Runs on the host before container create/start; prepares the env file and optional secrets. |
-| `hooks/post-create.sh` | Runs once after the container is created — e.g. installs [APM](https://github.com/microsoft/apm) (Agent Package Manager), coding-agent CLIs, and OpenSSH server. |
+| `hooks/post-create.sh` | Runs once after the container is created — e.g. installs OpenSSH server, Debian Python, [APM](https://github.com/microsoft/apm) (Agent Package Manager), and default coding-agent CLIs. |
 | `hooks/post-start.sh` | Runs on each container start; refreshes runtime state such as SSH host keys and authorized keys. |
+| `utils/git-config-bootstrap.sh` | Container-side Git config copy/sanitization helper used by lifecycle scripts. |
+| `utils/python-bootstrap.sh` | Container-side Debian Python runtime helper used by lifecycle scripts. |
 | `utils/ssh-bootstrap.sh` | Container-side OpenSSH install/runtime helper used by lifecycle scripts. |
 | `utils/coding-agent-cli-update.sh` | Shared install/update helper for Codex, OpenCode, Claude Code, and Antigravity CLI. |
-| `utils/deps-install.sh` | Dependency installation helper used by `hooks/post-create.sh`. |
+| `utils/deps-install.sh` | Dependency installation helper used by `hooks/post-create.sh`; bootstraps pnpm/yarn when the slim base does not provide them. |
+
+## Base image
+
+Boxdown uses `node:24-trixie-slim` as the base image to keep the shared image smaller than the full Dev Containers TypeScript/Node image. The devcontainer then installs the required operating-system tools through pinned Dev Container features. `common-utils` and `git` run first so later features and lifecycle hooks can rely on shell basics, `sudo`, package metadata, Git, and related utilities.
+
+Python is installed during `postCreateCommand` from Debian apt packages (`python3`, `python3-venv`, `python3-pip`, and `pipx`). On Debian trixie this currently provides Python 3.13. Boxdown intentionally avoids the Dev Containers Python feature because it added a large Python runtime/dev-tooling layer, including bundled environments for tools such as mypy, black, pylint, pytest, bandit, pipenv, and flake8.
+
+uv remains a separate pinned feature. It provides `uv`/`uvx`, but it does not provide the system Python runtime by default.
+
+JavaScript package managers are handled at workspace setup time: npm comes from the Node image, pnpm is installed as `pnpm@11` for pnpm projects, and Yarn is enabled through Corepack when needed.
 
 ## Usage
 
@@ -40,7 +52,7 @@ From the **repository root** on your host:
 bash .devcontainer/start.sh
 ```
 
-Requires Docker running. The script resolves Boxdown's packaged `@devcontainers/cli` dependency and uses that binary to `up` the workspace and `exec` into `bash`; it does not install or use a host/global Dev Containers CLI package.
+Requires Docker running. The script resolves Boxdown's packaged `@devcontainers/cli` dependency and uses that binary to `up` the workspace and `exec` into `bash`; it does not install or use a host/global Dev Containers CLI package. Startup output is concise by default; pass `--verbose` to stream raw Docker, Dev Containers, and hook logs.
 
 ### GitHub CLI auth from host `gh`
 
@@ -71,10 +83,13 @@ use HTTPS and ask the container's `gh` for credentials during `git fetch`,
 `git pull`, and `git push`. This is intentionally tied to the explicit refresh
 command; regular SSH remote connections do not copy GitHub credentials.
 
-If your host `.gitconfig` is mounted into the container, Boxdown adds local
-repository settings that neutralize incompatible host-only helpers such as
-`/opt/homebrew/bin/gh` and broad rewrites such as
-`url.git@github.com:.insteadOf=https://github.com/`.
+Boxdown snapshots your host `.gitconfig` into workspace state before container
+creation, mounts that snapshot read-only, and copies it to a normal writable
+`/home/node/.gitconfig` during `postCreateCommand`. The container copy is then
+sanitized to neutralize incompatible host-only helpers such as
+`/opt/homebrew/bin/gh`, broad rewrites such as
+`url.git@github.com:.insteadOf=https://github.com/`, and host-only signing
+settings.
 
 If the container is already running and you only want to refresh its GitHub auth:
 
@@ -92,7 +107,7 @@ first when you need to repair host GitHub auth.
 From the **repository root** on your host, install or update the SSH alias:
 
 ```bash
-bash .devcontainer/start.sh ssh-config install
+bash .devcontainer/start.sh ssh install
 ```
 
 By default, this creates:
@@ -112,7 +127,7 @@ Then use the same host alias in Cursor, Claude, or any other SSH client:
 - **SSH Host:** `<repo-name>-devcontainer`
 - **SSH Port:** leave empty
 - **Identity File:** leave empty if the client reads `~/.ssh/config`; otherwise use `.devcontainer/.ssh/id_ed25519`
-- **Remote Folder:** select `<repo-name>` from the default home folder, or enter `/workspaces/<repo-name>`
+- **Remote Folder:** enter `/workspaces/<repo-name>`
 
 To customize the alias, run:
 
@@ -129,7 +144,7 @@ If you are a coding agent running on the host OS, prefer the SSH alias workflow.
 From the repository root on the host:
 
 ```bash
-bash .devcontainer/start.sh ssh-config install
+bash .devcontainer/start.sh ssh install
 ssh <repo-name>-devcontainer 'whoami && pwd'
 ```
 
@@ -138,15 +153,16 @@ Use the generated host alias when configuring the agent:
 - **SSH Host:** `<repo-name>-devcontainer`
 - **SSH Port:** leave empty
 - **Identity File:** leave empty if the agent honors `~/.ssh/config`; otherwise use `.devcontainer/.ssh/id_ed25519`
-- **Remote Folder:** select `<repo-name>` from the default home folder, or enter `/workspaces/<repo-name>`
+- **Remote Folder:** enter `/workspaces/<repo-name>`
 
 `start.sh` has two modes:
 
 - `bash .devcontainer/start.sh` starts or reuses the devcontainer and opens an interactive shell. Use this for a local terminal session.
-- `bash .devcontainer/start.sh ssh-config install` installs or refreshes the host SSH alias and exits.
+- `bash .devcontainer/start.sh ssh install` installs or refreshes the host SSH alias and exits.
 - `bash .devcontainer/start.sh --ssh-proxy` refreshes the SSH alias, starts or reuses the devcontainer, and then bridges SSH over `docker exec`. Do not keep this running manually in a terminal; it is meant to be launched by OpenSSH as the `ProxyCommand` in the generated SSH config.
 - `bash .devcontainer/start.sh --refresh-gh-token` starts or reuses the devcontainer, then refreshes container `gh` auth from host `gh` when a token is available.
 - `bash .devcontainer/start.sh --refresh-gh-token-running` refreshes container `gh` auth from host `gh` only when the devcontainer is already running.
+- Add `--verbose` to any startup mode when debugging raw devcontainer, Docker, or hook output.
 
 If the devcontainer does not exist yet, the first SSH connection through `<repo-name>-devcontainer` will create it with `@devcontainers/cli up`, including `initializeCommand`, features, mounts, `postCreateCommand`, and `postStartCommand`. The first connection may take longer while the container is created.
 
@@ -169,7 +185,23 @@ It is not a GitHub token and does not authenticate `gh` or GitHub Git remotes.
 - **Global agent config** — Boxdown automatically mounts host `~/.agents`
   read-only at `/home/node/.agents` when that directory exists. Recreate the
   devcontainer after creating or removing it so the mount set is refreshed.
-- **Agent config on the host** — Uncomment the `mounts` entries in `devcontainer.json` to bind `~/.claude`, `~/.gemini`, or `~/.codex` into the container so coding agents see your existing settings.
+- **Codex auth on the host** — Boxdown automatically mounts host
+  `~/.codex/auth.json` read-only at `/home/node/.codex/auth.json` when that file
+  exists. Recreate the devcontainer after creating or removing it so the mount
+  set is refreshed.
+- **Other agent config on the host** — Uncomment the `mounts` entries in
+  `devcontainer.json` to bind directories such as `~/.claude` or `~/.gemini`
+  into the container so coding agents see your existing settings.
+- **Coding-agent defaults** — Container create/start installs or refreshes
+  Codex and Claude Code by default. OpenCode and Antigravity CLI remain
+  available through `boxdown opencode` and `boxdown antigravity`, but install
+  lazily only when those commands are launched.
+- **Agent CLI cleanup** — After a successful coding-agent CLI install/update,
+  Boxdown removes stale agent artifacts: old Codex standalone releases, old
+  Claude Code versions, OpenCode installer temp directories, and Antigravity
+  staging cache. Codex keeps only the active standalone release by default; set
+  `BOXDOWN_CODEX_STANDALONE_RELEASES_KEEP_PREVIOUS` to keep extra rollback
+  releases.
 - **1Password / other CLIs** — Follow the commented blocks in `devcontainer.json` and `hooks/post-create.sh` if you need them; keep the image lean by default.
 
 ---

package/assets/devcontainer/devcontainer.json

@@ -1,17 +1,35 @@
 {
     "name": "Project Devcontainer",
-    "image": "mcr.microsoft.com/devcontainers/typescript-node:24-trixie",
+    "image": "node:24-trixie-slim",
     "features": {
-        "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511": {
-            "version": "3.12",
-            "installPythonDevDependencies": true
+        "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a": {
+            "username": "node"
         },
+        "ghcr.io/devcontainers/features/git@sha256:a3e43ff91b9f5f6bd2c14bd510d43e5e698f1266dc41027ba4e04e7e45be607a": {
+            "version": "os-provided"
+        },
+        // Removed from the active feature set after measuring roughly 900MB of
+        // layer growth. Keep this reference for future Python 3.12/dev-tooling needs.
+        // "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511": {
+        //     "version": "3.12",
+        //     "installPythonDevDependencies": true
+        // },
         "ghcr.io/devcontainer-community/devcontainer-features/astral.sh-uv@sha256:36f95b90080248a05aba7b1b3cecf8018bb6d7222f6274f03f050b502abd4fe7": {
             "shellautocompletion": true
         },
         "ghcr.io/devcontainers-extra/features/ripgrep@sha256:0dfc0ac16f0d6aa754d006a138fd4cb4a62c245d308306edf8ad1b7a80b8fdf2": {},
         "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671": {}
     },
+    "overrideFeatureInstallOrder": [
+        "ghcr.io/devcontainers/features/common-utils@sha256:cb0c4d3c276f157eed17935747e364178d75fee17f55c4e129966f64633deb3a",
+        "ghcr.io/devcontainers/features/git@sha256:a3e43ff91b9f5f6bd2c14bd510d43e5e698f1266dc41027ba4e04e7e45be607a",
+        // Python is installed during post-create from Debian apt to avoid the
+        // heavy Dev Containers Python feature layer.
+        // "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511",
+        "ghcr.io/devcontainer-community/devcontainer-features/astral.sh-uv@sha256:36f95b90080248a05aba7b1b3cecf8018bb6d7222f6274f03f050b502abd4fe7",
+        "ghcr.io/devcontainers-extra/features/ripgrep@sha256:0dfc0ac16f0d6aa754d006a138fd4cb4a62c245d308306edf8ad1b7a80b8fdf2",
+        "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
+    ],
     // Ask the editor to forward these container ports (no Docker appPort).
     "forwardPorts": [8787, 3005, 3001, 3000],
 
@@ -51,11 +69,10 @@
     },
 
     "mounts": [
-        "source=${localEnv:HOME}/.gitconfig,target=/home/node/.gitconfig,type=bind,consistency=cached",
         // mount host user home directories for agents:
         // "source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind,consistency=cached",
-        // "source=${localEnv:HOME}/.gemini,target=/home/node/.claude,type=bind,consistency=cached",
-        // "source=${localEnv:HOME}/.codex,target=/home/node/.codex,type=bind,consistency=cached"
+        // "source=${localEnv:HOME}/.gemini,target=/home/node/.claude,type=bind,consistency=cached"
+        // Codex auth.json is mounted automatically by Boxdown's generated config when present.
     ],
 
     // Initialize optional host-side secrets before container create/start.

package/assets/devcontainer/hooks/initialize.sh

@@ -7,19 +7,51 @@ set -euo pipefail
 HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 WORKSPACE_DIR="${BOXDOWN_WORKSPACE_FOLDER:-$(cd "${HOOKS_DIR}/../.." && pwd)}"
 ENV_FILE="${WORKSPACE_DIR}/.env.development"
+HOST_GITCONFIG_PATH="${BOXDOWN_HOST_GITCONFIG_PATH:-${HOME:-}/.gitconfig}"
+HOST_GITCONFIG_SNAPSHOT_PATH="${BOXDOWN_HOST_GITCONFIG_SNAPSHOT_PATH:-}"
 OP_TOKEN_REFERENCE="op://Private/1Password op CLI Service Account for DevContainers/password"
 
 main() {
+  progress "Preparing workspace environment file"
   ensure_env_file_exists
+  progress "Snapshotting host Git config"
+  snapshot_host_gitconfig
+  progress "Checking 1Password service account token"
   maybe_inject_1password_service_account_token
 }
 
+progress() {
+  if [[ "${BOXDOWN_PROGRESS:-0}" == "1" ]]; then
+    printf 'BOXDOWN_PROGRESS: %s\n' "$*"
+  fi
+}
+
 ensure_env_file_exists() {
   if [[ ! -f "${ENV_FILE}" ]]; then
     : > "${ENV_FILE}"
   fi
 }
 
+snapshot_host_gitconfig() {
+  local snapshot_dir
+
+  if [[ -z "${HOST_GITCONFIG_SNAPSHOT_PATH}" ]]; then
+    echo "initialize.sh: host gitconfig snapshot path is not configured; skipping gitconfig snapshot."
+    return 0
+  fi
+
+  snapshot_dir="$(dirname "${HOST_GITCONFIG_SNAPSHOT_PATH}")"
+  mkdir -p "${snapshot_dir}"
+
+  if [[ -f "${HOST_GITCONFIG_PATH}" ]]; then
+    cp "${HOST_GITCONFIG_PATH}" "${HOST_GITCONFIG_SNAPSHOT_PATH}"
+    chmod 0644 "${HOST_GITCONFIG_SNAPSHOT_PATH}"
+    return 0
+  fi
+
+  rm -f "${HOST_GITCONFIG_SNAPSHOT_PATH}"
+}
+
 maybe_inject_1password_service_account_token() {
   local token
 

package/assets/devcontainer/hooks/post-create.sh

@@ -5,27 +5,68 @@ HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 DEVCONTAINER_DIR="$(cd "${HOOKS_DIR}/.." && pwd)"
 
 main() {
-  configure_local_git
-  install_openssh_server
-  install_apm
-  install_or_update_coding_agent_clis
-  install_1password_cli
-  install_snyk_cli
-  run_deps_install
+  run_step "Configuring global Git" configure_global_git
+  run_step "Configuring Git commit signing" configure_git_signing
+  run_step "Configuring workspace Git" configure_local_git
+  run_step "Installing OpenSSH server" install_openssh_server
+  run_step "Installing Python runtime" install_python_runtime
+  run_step "Installing Agent Package Manager" install_apm
+  run_step "Installing coding-agent CLIs" install_or_update_coding_agent_clis
+  run_step "Installing 1Password CLI" install_1password_cli
+  run_step "Installing Snyk CLI" install_snyk_cli
+  run_step "Installing workspace dependencies" run_deps_install
+}
+
+progress() {
+  if [[ "${BOXDOWN_PROGRESS:-0}" == "1" ]]; then
+    printf 'BOXDOWN_PROGRESS: %s\n' "$*"
+  fi
+}
+
+run_step() {
+  local label="$1"
+  shift
+
+  progress "$label"
+  "$@"
+}
+
+configure_global_git() {
+  bash "${DEVCONTAINER_DIR}/utils/git-config-bootstrap.sh"
+}
+
+configure_git_signing() {
+  bash "${DEVCONTAINER_DIR}/utils/git-signing-bootstrap.sh"
 }
 
 configure_local_git() {
   # Local git prefs only apply inside a repository; skip when there is no .git (avoids postCreate failure).
   if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    git config --local commit.gpgsign false
-    git config --local core.pager 'less -R'
-    git config --local credential.https://github.com.helper '!gh auth git-credential'
+    git config --local --replace-all core.pager 'less -R'
+    git config --local --unset-all credential.https://github.com.helper >/dev/null 2>&1 || true
+    git config --local --add credential.https://github.com.helper ''
+    git config --local --add credential.https://github.com.helper '!gh auth git-credential'
   fi
 }
 
 install_apm() {
   # Agent Package Manager: https://github.com/microsoft/apm
-  curl -sSL https://aka.ms/apm-unix | sh
+  local installer
+
+  installer="$(mktemp)"
+  if ! curl -fsSL https://aka.ms/apm-unix -o "${installer}"; then
+    rm -f "${installer}"
+    echo "post-create: warning: could not download APM installer; skipping APM." >&2
+    return 0
+  fi
+
+  if ! sh "${installer}"; then
+    rm -f "${installer}"
+    echo "post-create: warning: APM installer failed; skipping APM." >&2
+    return 0
+  fi
+
+  rm -f "${installer}"
 }
 
 install_or_update_coding_agent_clis() {
@@ -37,6 +78,10 @@ install_openssh_server() {
   bash "${DEVCONTAINER_DIR}/utils/ssh-bootstrap.sh" install
 }
 
+install_python_runtime() {
+  bash "${DEVCONTAINER_DIR}/utils/python-bootstrap.sh" install
+}
+
 install_snyk_cli() {
   # https://docs.snyk.io/snyk-cli/install-the-snyk-cli
   local url
@@ -64,4 +109,6 @@ run_deps_install() {
   bash "${DEVCONTAINER_DIR}/utils/deps-install.sh"
 }
 
-main "$@"
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  main "$@"
+fi

package/assets/devcontainer/hooks/post-start.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # post-start: runs after each container start (postStartCommand in devcontainer.json).
-# Naming matches post-create.sh; extend with more steps as needed (e.g. source scripts from .devcontainer/utils/).
+set -euo pipefail
+
+DEVCONTAINER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+bash "${DEVCONTAINER_DIR}/utils/git-signing-bootstrap.sh"
 
 set -euo pipefail
 
@@ -8,9 +11,23 @@ HOOKS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 DEVCONTAINER_DIR="$(cd "${HOOKS_DIR}/.." && pwd)"
 
 main() {
-  configure_sshd_runtime
-  refresh_coding_agent_clis
-  remove_ephemeral_env_file_if_present
+  run_step "Preparing SSH runtime" configure_sshd_runtime
+  run_step "Refreshing coding-agent CLIs" refresh_coding_agent_clis
+  run_step "Cleaning ephemeral environment file" remove_ephemeral_env_file_if_present
+}
+
+progress() {
+  if [[ "${BOXDOWN_PROGRESS:-0}" == "1" ]]; then
+    printf 'BOXDOWN_PROGRESS: %s\n' "$*"
+  fi
+}
+
+run_step() {
+  local label="$1"
+  shift
+
+  progress "$label"
+  "$@"
 }
 
 configure_sshd_runtime() {

package/assets/devcontainer/ssh-config-install.sh

@@ -89,11 +89,20 @@ write_ssh_config_block() {
   chmod 0600 "$SSH_CONFIG"
 
   tmp_file="$(mktemp)"
-  awk -v begin="$BEGIN_MARKER" -v end="$END_MARKER" '
+  if ! awk -v begin="$BEGIN_MARKER" -v end="$END_MARKER" '
     $0 == begin { skip = 1; next }
-    $0 == end { skip = 0; next }
+    $0 == end && skip { skip = 0; next }
+    skip && $0 ~ /^# (BEGIN|END) [A-Za-z0-9_.-]+ (boxdown )?devcontainer ssh$/ { exit 43 }
     !skip { print }
-  ' "$SSH_CONFIG" > "$tmp_file"
+    END {
+      if (skip) {
+        exit 42
+      }
+    }
+  ' "$SSH_CONFIG" > "$tmp_file"; then
+    rm -f "$tmp_file"
+    die "Refusing to update SSH config for ${HOST_ALIAS}: found \"${BEGIN_MARKER}\" without matching \"${END_MARKER}\" or with an overlapping managed marker. Repair the config manually before running Boxdown again."
+  fi
 
   start_script_quoted="$(ssh_config_quote "$START_SCRIPT")"
   key_path_quoted="$(ssh_config_quote "$SSH_KEY_PATH")"