boxdown 1.0.0 → 1.2.1

package/docs/features/README.md

@@ -4,10 +4,12 @@ This directory explains Boxdown's user-facing capabilities and the main internal
 flows behind them.
 
 - [Start command](./start-and-shell.md)
+- [Setup command](./setup.md)
 - [Lifecycle commands](./lifecycle.md)
 - [SSH config and proxy workflow](./ssh-config-and-proxy.md)
 - [GitHub auth refresh](./github-auth-refresh.md)
 - [Generated config and state](./generated-config-and-state.md)
+- [Commit signing](./commit-signing.md)
 
 Most features share the same first step: resolve a target workspace, derive
 workspace-specific state paths, generate a devcontainer override config, and

package/docs/features/commit-signing.md

@@ -0,0 +1,94 @@
+# Commit signing
+
+New Boxdown environments attempt SSH commit signing by default. Boxdown forwards
+the host SSH agent, selects a signing identity only when there is one
+unambiguous candidate, and keeps the private key on the host.
+
+If the agent is unavailable, has no identities, or has multiple identities
+that Boxdown cannot distinguish, Boxdown warns and configures unsigned commits.
+It never guesses a key and does not block setup or commits.
+
+Signing readiness is resolved when generated devcontainer configuration is
+written. A container created while readiness is unavailable does not gain an
+SSH-agent mount later; recreate it after correcting the warning:
+
+```bash
+boxdown setup --workspace /path/to/project --recreate
+```
+
+The container can request operations from identities exposed by the forwarded
+agent. Use a dedicated signing identity or an agent that confirms sensitive
+operations when that exposure is unacceptable.
+
+On Docker Desktop, Boxdown places a small root-owned relay between the
+host-facing agent socket and the non-root container user. The relay exposes no
+private-key material and lets normal `node`-user Git commits reach the host
+agent.
+
+GitHub verification is separate from signing. Upload the selected public key as
+a GitHub SSH signing key once to receive the Verified badge:
+
+```bash
+gh ssh-key add /path/to/signing-key.pub --type signing --title "Boxdown commit signing"
+```
+
+The same key may already be registered for GitHub SSH authentication; GitHub
+requires a second registration with type `signing`.
+
+## Optional: configure SSH signing on the host
+
+Boxdown can sign commits without changing the host Git configuration. The
+container uses the selected identity from the host SSH agent directly. Configure
+the host as well when you also make commits outside Boxdown, or when you want
+to make the selected Boxdown identity explicit.
+
+First, verify the intended identity is loaded in the SSH agent. `ssh-add -l`
+prints loaded key fingerprints:
+
+```bash
+ssh-add -l
+```
+
+Then configure Git to use that public key for SSH signing:
+
+```bash
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global --unset-all gpg.program || true
+git config --global commit.gpgsign true
+```
+
+Replace `~/.ssh/id_ed25519.pub` with the selected public key when you use a
+different identity. The public key must also be registered with GitHub as a
+Signing key for pushed commits to display the Verified badge.
+
+Boxdown accepts `user.signingkey` as an inline SSH public key, a `key::` public
+key, an absolute path, a `~/` path, or a path relative to the workspace. Only
+public-key files are read. An explicitly configured key is authoritative: if
+it is unreadable, invalid, or absent from the SSH agent, Boxdown disables
+signing instead of selecting another identity.
+
+## User configuration precedence
+
+Boxdown defaults to SSH signing only when Git has no explicit signing
+preference. A repository-local `commit.gpgsign=false`, a non-SSH `gpg.format`,
+or an explicit `gpg.program` is preserved. Explicit SSH signing remains
+supported; Boxdown maps an inaccessible host public-key path to the selected
+public-key snapshot inside the container. This policy is intentional and may
+be revisited in a future release if Boxdown becomes authoritative.
+
+Git can require `gpg.ssh.allowedSignersFile` for trust-aware local verification
+such as `git log --show-signature`. It is not required to create SSH signatures
+or for GitHub to verify a commit.
+
+## Troubleshooting
+
+Signing failures remain non-blocking. User-facing lifecycle commands print a
+concise reason, while the workspace `boxdown.log` records a stable reason code
+and sanitized diagnostic detail. Container validation further distinguishes a
+missing mounted public key, an unavailable forwarded agent, a selected key that
+is not loaded, and a failed disposable signed-commit probe.
+
+Run `boxdown doctor --workspace /path/to/project` to recheck host identity
+selection and GitHub signing-key registration. After fixing the reported
+condition, use `--recreate`; existing unsigned commits are not rewritten.

package/docs/features/generated-config-and-state.md

@@ -35,6 +35,21 @@ Boxdown-specific override is not set.
 SSH private keys live in persistent data. A public-key-only runtime directory is
 used for the container mount.
 
+Boxdown-managed lifecycle command output is appended to one per-workspace log
+file:
+
+```text
+~/.local/share/boxdown/workspaces/<workspace-hash>/boxdown.log
+```
+
+The log is append-only across lifecycle runs. Each run starts a timestamped
+section and records Boxdown-managed command output, Docker/devcontainer child
+process output, and command exit codes. Full interactive shell, agent, and
+tunnel session bytes are not tee'd into the log.
+
+The log lives with the workspace's persistent data so `boxdown status` can show
+its path and `boxdown purge` removes it with the rest of the workspace data.
+
 Each touched workspace also records inventory metadata at:
 
 ```text
@@ -44,21 +59,74 @@ Each touched workspace also records inventory metadata at:
 `boxdown list` reads these metadata files as its source of truth, then enriches
 entries with best-effort Docker state.
 
+Metadata may also record the last inspected Docker image ID for the workspace so
+`boxdown purge` can remove that exact image even after the container is gone.
+
+## Runtime Secret State
+
+`ANTHROPIC_API_KEY`, `SNYK_TOKEN`, and the optional 1Password service-account
+token are written to owner-only files in a per-workspace runtime directory,
+separate from persistent workspace data. Boxdown mounts that directory
+read-only at `/run/boxdown/secrets`; only non-secret mount and Bash-bootstrap
+paths appear in generated Docker configuration.
+
+Bash sessions load available files as ordinary environment variables. Missing
+host values and failed 1Password lookup are non-blocking. `boxdown down` and
+`boxdown purge` remove the workspace runtime directory after container removal.
+Boxdown does not use or modify project `.env.development` files.
+
+## External App Config
+
+External app integration config is not Boxdown workspace state. Boxdown writes
+it only when an SSH install target is selected from an interactive
+`boxdown setup` or `boxdown ssh install` prompt, or requested explicitly with
+`boxdown setup --target <name>` or `boxdown ssh install --target <name>`.
+Non-interactive runs without `--target` install only the SSH alias and leave
+external app config unchanged.
+
+When requested, Boxdown writes Codex's app config at:
+
+```text
+~/.codex/codex-app/config.json
+```
+
+`BOXDOWN_CODEX_APP_CONFIG` overrides this path for tests and local development.
+The Codex entry refers to the Boxdown-managed SSH alias and the canonical
+container-side workspace path `/workspaces/<repo-name>`. Codex owns later
+global-state records and sidebar entries it creates from that config, but
+`boxdown ssh uninstall` removes the matching Codex sidebar cache entry when
+unregistering the project.
+
+When requested, Boxdown writes Claude's SSH remote config at:
+
+```text
+~/Library/Application Support/Claude/ssh_configs.json
+```
+
+`BOXDOWN_CLAUDE_SSH_CONFIGS` overrides this path for tests and local
+development. The Claude entry refers to the Boxdown-managed SSH alias and adds
+that alias to Claude's trusted host list.
+
 ## Generated Changes
 
 Boxdown starts from `assets/devcontainer/devcontainer.json` and rewrites:
 
 - `name`, to include the workspace basename.
-- `initializeCommand`, to call the host asset script with the target workspace.
+- `initializeCommand`, to call the host asset script with the target workspace
+  and host Git config snapshot paths.
 - `postCreateCommand`, to call mounted container assets.
 - `postStartCommand`, to call mounted container assets.
-- `mounts`, to add the read-only asset mount, public-key mount, and host
-  `~/.agents` mount when that directory exists.
+- `mounts`, to add the read-only asset mount, public-key mount, host Git config
+  snapshot mount, runtime secret mount, host `~/.agents` mount when that
+  directory exists, and host `~/.codex/auth.json` read-only mount when that
+  file exists.
 - `containerEnv`, to point SSH bootstrap at the mounted public key and actual
   container workspace.
 
 The target repository is still the Dev Container workspace via
 `--workspace-folder`.
 
-Mounts are create-time container settings. Use `boxdown start --recreate` after
-creating or removing host `~/.agents` so Docker receives the updated mount set.
+Mounts are create-time container settings. Existing containers created before
+runtime-mounted secrets require `boxdown start --recreate`. The same applies
+after creating or removing host `~/.agents` or `~/.codex/auth.json` so Docker
+receives the updated mount set.

package/docs/features/github-auth-refresh.md

@@ -5,6 +5,7 @@
 ```sh
 boxdown refresh-gh-token
 boxdown refresh-gh-token-running
+boxdown refresh-gh-token --verbose
 ```
 
 Both commands copy host GitHub CLI auth into the container using the host token
@@ -16,6 +17,9 @@ gh auth token
 
 They do not start a browser login or device-code flow.
 
+The startup and refresh work uses concise progress output by default. Pass
+`--verbose` to stream raw devcontainer and auth command output while debugging.
+
 These commands are explicit on purpose. Normal `boxdown start`, coding-agent
 launches, and SSH proxy connections do not copy GitHub credentials into the
 container.
@@ -48,6 +52,8 @@ container's authenticated `gh` for `git fetch`, `git pull`, and `git push`.
 For GitHub remotes, Boxdown:
 
 - rewrites fetch and push URLs to `https://github.com/<owner>/<repo>.git`
+- configures container-global GitHub HTTPS credentials through the container's
+  `gh` auth store
 - resets inherited `credential.https://github.com.helper` entries locally
 - adds `!gh auth git-credential` as the local GitHub credential helper
 - adds a repository-specific HTTPS self-rewrite so broader host rewrites like
@@ -57,8 +63,15 @@ For GitHub remotes, Boxdown:
 The local Git config changes are written to the workspace repository because the
 host checkout is mounted into the devcontainer.
 
+Separately, Boxdown snapshots the host `.gitconfig` into workspace state and
+copies it to a writable `/home/node/.gitconfig` during container creation. That
+container copy is sanitized so tools cloning from directories such as `/tmp` use
+HTTPS GitHub auth and do not inherit host-only helpers, GitHub SSH rewrites, or
+signing programs that are unavailable inside Linux.
+
 If host `gh` is missing, logged out, or cannot return a token, the refresh is a
 no-op.
 
-`OP_SERVICE_ACCOUNT_TOKEN`, when present, is a 1Password service account token.
-It is not a GitHub token and is not used by `gh` or GitHub Git operations.
+`OP_SERVICE_ACCOUNT_TOKEN`, when available through Boxdown's runtime secret
+mount, is a 1Password service account token. It is not a GitHub token and is
+not used by `gh` or GitHub Git operations.

package/docs/features/lifecycle.md

@@ -4,33 +4,48 @@
 
 ```sh
 boxdown list
+boxdown list --details
 boxdown list --json
+boxdown list --format json
 boxdown status
 boxdown status --json
+boxdown status --format json
 boxdown stop
 boxdown down
+boxdown purge
 boxdown doctor
 ```
 
-Workspace-targeting commands accept `--workspace <path>`. `status` also accepts
-`--alias <name>` so its output can match a custom SSH host alias.
+Workspace-targeting commands accept `--workspace <path>`. `down` also accepts
+repeated `--workspace` flags to remove multiple workspace containers in order.
+`purge --workspace` also accepts the `PATH`, `SSH ALIAS`, or unambiguous `REPO`
+value shown by `boxdown list`. `purge` does not accept repeated `--workspace`
+flags. `status` accepts `--alias <name>` so its output can match a custom SSH
+host alias.
 
 ## List
 
 `list` shows every workspace with Boxdown metadata under the data root,
 regardless of the directory where the command is run. Human output includes
-`STATE`, `REPO`, `PATH`, `SSH ALIAS`, and `CONTAINER` columns.
+`STATE`, `REPO`, `PATH`, and `CONTAINER` columns.
 
-`list --json` prints the same inventory as structured JSON. Docker state is
-best-effort: if Docker is unavailable, entries still print and their container
-state is `unknown`. If a recorded repository path no longer exists, the entry is
-shown as `missing`.
+`list --details` prints one workspace per block with full copyable `path`,
+`ssh alias`, and `container` values.
+
+`list --json` and `list --format json` print the same inventory as structured
+JSON. Docker state is best-effort and includes recorded SSH aliases: if Docker
+is unavailable, entries still print and their container state is `unknown`. If a
+recorded repository path no longer exists, the entry is shown as `missing`.
+Container states come from Docker, so active containers usually show `running`,
+stopped containers can show `exited`, and workspaces with no matching container
+show `absent`.
 
 ## Status
 
 `status` is read-only. It reports the resolved workspace, intended cache/data
-paths, generated config path, SSH key paths, SSH alias, and the matching Docker
-container state without recording the workspace in Boxdown metadata.
+paths, generated config path, command log path, SSH key paths, SSH alias, and
+the matching Docker container state without recording the workspace in Boxdown
+metadata.
 
 Human output distinguishes intended values from detected state. For example, an
 SSH alias can be shown as a computed default even when the matching Boxdown SSH
@@ -46,7 +61,7 @@ workspace container is running. Missing setup or a stopped/absent container is
 reported in the output and exits nonzero. Installing an SSH alias is optional
 and is not required for a healthy status exit.
 
-## Stop and Down
+## Stop, Down, and Purge
 
 `stop` stops the workspace devcontainer when it is running. If the container is
 already stopped or absent, it prints a short message and exits 0.
@@ -54,11 +69,88 @@ already stopped or absent, it prints a short message and exits 0.
 `down` removes the workspace devcontainer with Docker. It does not remove
 Boxdown cache, generated config, data directories, or SSH keys.
 
+Lifecycle commands append managed output to the workspace command log under the
+workspace data directory. `--verbose` only controls terminal streaming; it does
+not disable or enable log persistence. Foreground interactive shell, agent, and
+tunnel session bytes are not tee'd into the log.
+
+`purge` removes the workspace devcontainer with Docker, force-removes the exact
+Docker image ID Boxdown can inspect or has recorded for the workspace, removes
+Boxdown-managed SSH/Codex/Claude entries for the computed, recorded, and
+provided aliases, and deletes the workspace's Boxdown cache/data directories,
+including the per-workspace command log. It does not delete the target
+repository directory or files inside it.
+
+`purge --workspace <value>` first treats `<value>` as a filesystem path. If that
+path does not exist, it looks for an exact `PATH`, then `SSH ALIAS`, then `REPO`
+match in Boxdown metadata. `PATH` and `REPO` are shown by `boxdown list`; use
+`boxdown status`, `boxdown list --details`, or JSON list output for SSH aliases.
+`REPO` must match exactly one workspace; if multiple known workspaces share the
+same repo basename, use `PATH` or `SSH ALIAS`.
+
+```sh
+boxdown purge
+boxdown purge --workspace my-repo-devcontainer
+boxdown purge --workspace my-repo
+boxdown purge --workspace /path/to/my-repo
+```
+
+To remove multiple workspace containers, repeat `--workspace`:
+
+```sh
+boxdown down --workspace /path/to/repo-a --workspace /path/to/repo-b
+```
+
+When `down` runs without `--workspace` from a directory that is not a known
+Boxdown workspace, interactive terminals show a multi-select list of known
+workspaces with existing repository paths. Non-interactive runs keep the
+current-directory behavior.
+
+Batch `down` continues after individual workspace failures, but exits nonzero if
+any requested workspace cannot be resolved or removed.
+
+When `purge` runs without `--workspace` from a tracked Boxdown workspace, it
+purges that workspace after confirmation. When it runs without `--workspace`
+from an untracked directory, interactive terminals show a multi-select list of
+all tracked workspaces from `boxdown list`, including `running`, `exited`,
+`absent`, `missing`, and `unknown` states. After selection, `purge` asks for one
+destructive confirmation for the selected batch, then purges each selected
+workspace in order. Batch purge continues after individual workspace failures,
+but exits nonzero if any selected workspace fails.
+
+In the interactive purge selector, the focused row color-codes only the state
+token: `running` is green, `exited` is yellow, and `absent`, `missing`, or
+`unknown` are red. These colors are terminal UI affordances only; scripts should
+rely on text or JSON state values.
+
+Interactive `purge` runs ask for confirmation before removing devcontainer,
+image, SSH/Codex integration, cache, and data state. Non-interactive purge runs
+do not prompt so existing targeted scripts keep working. Non-interactive
+`purge` from an untracked directory fails safely instead of treating the current
+directory as a workspace.
+
 ## Doctor
 
 `doctor` validates required host prerequisites: Node, Docker CLI, Docker
 daemon access, SSH tools, packaged devcontainer assets, and Boxdown's packaged
-`@devcontainers/cli` dependency.
+`@devcontainers/cli` dependency. It also uses a local Docker image, when one is
+available, to create and immediately remove disposable containers that verify
+Docker can bind-mount the workspace, Boxdown assets, and Boxdown runtime-state
+paths. The probe never pulls an image or starts container code.
+
+Known bind-mount/share failures are errors with the affected host path and
+Docker Desktop remediation guidance. If Docker has no local image or the probe
+cannot complete for another reason, doctor reports a warning instead.
+
+`boxdown setup` runs the required doctor checks before it prompts, writes
+workspace metadata, creates SSH keys, generates devcontainer configuration, or
+starts Docker. Required failures stop setup; warnings remain non-blocking.
 
 GitHub CLI auth is optional. Missing or unauthenticated `gh` is reported as a
 warning rather than a failure.
+
+Doctor uses the same SSH signing identity precedence as environment creation.
+It honors an explicit `user.signingkey` public-key value or path, can select a
+single GitHub authentication-key match from multiple loaded identities, and
+checks the selected key's GitHub signing registration when available. Signing
+readiness warnings never fail setup.

package/docs/features/setup.md

@@ -0,0 +1,66 @@
+# Setup Command
+
+## Command
+
+```sh
+boxdown setup
+boxdown setup --target codex
+boxdown setup --target claude
+boxdown setup --recreate
+```
+
+`setup` prepares the current workspace for remote tools without opening an
+interactive shell. It accepts:
+
+```sh
+--workspace <path>
+--alias <name>
+--recreate
+--target <name>
+--verbose
+```
+
+## Flow
+
+1. Resolve the workspace to a real absolute path.
+2. Ensure per-workspace SSH key material exists.
+3. Generate a Boxdown-owned devcontainer config.
+4. Run `devcontainer up --workspace-folder <repo> --override-config <config>`.
+5. Install or update the Boxdown-managed SSH alias.
+6. Optionally install selected SSH targets such as Codex or Claude.
+
+`setup` prints plain progress sections by default. Docker, Dev Containers CLI,
+and lifecycle hook output is captured and only summarized if a command fails.
+Pass `--verbose` to stream the raw build and hook logs to the terminal.
+
+Boxdown also appends the managed setup output to the workspace command log at:
+
+```text
+~/.local/share/boxdown/workspaces/<workspace-hash>/boxdown.log
+```
+
+The log is written regardless of `--verbose`; the flag only changes terminal
+streaming.
+
+When `--target codex` is provided, Boxdown writes the Codex app config entry for
+the same alias and container-side project path used by:
+
+```sh
+boxdown ssh install --target codex
+```
+
+When `--target claude` is provided, Boxdown writes the Claude app SSH remote
+entry for the same alias used by:
+
+```sh
+boxdown ssh install --target claude
+```
+
+When no target is provided, Boxdown uses the same optional target prompt as
+`boxdown ssh install`. In non-interactive shells, setup skips target
+registration unless `--target` is provided.
+
+`setup` does not open a shell, launch a coding-agent CLI, or keep a tunnel in the
+foreground. Use `boxdown start`, `boxdown codex`, or `boxdown tunnel` for those
+foreground workflows. Those commands log Boxdown-managed startup steps, but do
+not tee full interactive shell, agent, or tunnel session bytes into the log.