unbound-force · em-redhat · Aug 27, 2026
diff --git a/openspec/changes/devpod-preflight-docs/.openspec.yaml b/openspec/changes/devpod-preflight-docs/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: unbound-force
+created: 2026-08-20
diff --git a/openspec/changes/devpod-preflight-docs/design.md b/openspec/changes/devpod-preflight-docs/design.md
@@ -0,0 +1,45 @@
+## Context
+
+PR unbound-force/unbound-force#436 removed the `LookPath("podman")` pre-flight check from `uf sandbox create --backend devpod` and added a diagnostic hint on `devpod up` failure. The website documentation currently states Podman must be installed as a prerequisite and does not mention the diagnostic hint. These docs need updating to match the new behavior.
+
+The proposal (constitution alignment: all N/A) confirms this is a documentation-only change with no hero functionality, artifact interfaces, or testability implications.
+
+## Goals / Non-Goals
+
+### Goals
+- Update sandbox reference prerequisites to remove standalone Podman binary requirement for DevPod workspaces
+- Document the new `devpod up` failure diagnostic hint (`uf doctor` / `uf setup`)
+- Clarify that `uf setup` registers a docker-type provider under the name `podman` via `DOCKER_PATH=podman`
+- Update blog post to remove misleading "Podman required" limitation for DevPod users
+- Add changelog entry for the pre-flight change
+- Preserve accuracy: ephemeral Podman sandbox (`uf sandbox start` without DevPod) still requires Podman installed
+
+### Non-Goals
+- Rewriting the sandbox reference page structure or adding new sections
+- Documenting the upstream code changes (that belongs in the unbound-force repo)
+- Updating DevPod provider internals or architecture diagrams
+- Modifying CLI reference (subcommand table is already accurate)
+
+## Decisions
+
+### D1: Distinguish ephemeral vs. persistent prerequisites
+
+The sandbox has two paths: ephemeral containers (`uf sandbox start` — uses Podman directly) and persistent workspaces (`uf sandbox create` — uses DevPod). Only the DevPod path dropped the standalone Podman requirement. The documentation must make this distinction clear to avoid confusing users who use ephemeral containers (and still need Podman).
+
+**Approach**: Split the prerequisites paragraph into two contexts — ephemeral (Podman required) and persistent/DevPod (`uf setup` configures everything). This avoids a blanket statement in either direction.
+
+### D2: Blog post update scope
+
+The blog post `sandbox-isolation.md` lists "Podman required" as a current limitation. Rather than removing the limitation entirely (since ephemeral mode still needs it), update the wording to clarify the limitation applies to ephemeral containers only, and that DevPod workspaces handle runtime resolution automatically.
+
+### D3: Changelog placement
+
+Add the pre-flight change to the changelog as a "Changed" item under the next release version. Since the upstream PR targets a future release, use a placeholder version header that will be finalized at release time.
+
+## Risks / Trade-offs
+
+### Risk: Over-simplification
+Removing "Podman required" without nuance could lead DevPod users to think they never need Podman, when ephemeral mode still requires it. **Mitigation**: Explicit split between ephemeral and DevPod prerequisites.
+
+### Risk: Blog post drift
+Blog posts are point-in-time artifacts. Editing post-publication content could create confusion if readers saw the original version. **Mitigation**: The edit is factual correction, not opinion change. The limitation is being refined, not removed.
diff --git a/openspec/changes/devpod-preflight-docs/proposal.md b/openspec/changes/devpod-preflight-docs/proposal.md
@@ -0,0 +1,71 @@
+## Why
+
+PR unbound-force/unbound-force#436 (fixing #431) changed the DevPod sandbox pre-flight behavior:
+
+1. **Removed** the `LookPath("podman")` pre-flight check — users no longer need the `podman` binary in `$PATH`. The docker provider aliased as `podman` (configured by `uf setup`) handles container runtime resolution internally.
+2. **Added** a diagnostic hint on `devpod up` failure: `"run 'uf doctor' to diagnose or 'uf setup' to configure"`.
+3. **Unchanged**: The `--provider podman` flag is retained — it references the registered DevPod provider name, not a standalone binary.
+
+The website documentation currently states Podman must be installed as a prerequisite and implies a standalone `podman` binary is required in `$PATH`. This is no longer accurate and could confuse users who follow the docs and install standalone Podman when `uf setup` already configures everything needed.
+
+## What Changes
+
+Update documentation across multiple pages to reflect the new DevPod provider model and diagnostic hint.
+
+## Capabilities
+
+### New Capabilities
+- `diagnostic-hint-docs`: Document the new `devpod up` failure diagnostic hint that directs users to `uf doctor` and `uf setup`
+
+### Modified Capabilities
+- `sandbox-prerequisites`: Update prerequisites to clarify that `uf setup` configures the DevPod provider (a docker-type provider registered under the name `podman` via `DOCKER_PATH=podman`) — users do not need to install standalone Podman separately for DevPod workspaces
+- `sandbox-blog-post`: Update the blog post to remove the implication that standalone Podman installation is a user prerequisite for DevPod workspaces
+
+### Removed Capabilities
+- `podman-in-path-prerequisite`: Remove documentation stating users need `podman` in `$PATH` as a prerequisite for DevPod sandbox usage
+
+## Impact
+
+**Affected pages** (files containing outdated podman prerequisite or DevPod provider information):
+
+| File | What Needs Changing |
+|------|-------------------|
+| `content/docs/reference/sandbox.md` | Update Prerequisites paragraph (line 15): remove "Podman and DevPod must be installed" framing, clarify provider model, add diagnostic hint |
+| `content/blog/sandbox-isolation.md` | Update "Current Limitations" section (line 147): "Podman required" is misleading for DevPod users; update blog post startup sequence to reflect new pre-flight behavior |
+| `content/docs/reference/cli.md` | No changes needed — sandbox subcommand table is accurate as-is |
+| `content/docs/getting-started/quick-start.md` | No changes needed — no Podman prerequisite mentioned |
+| `content/docs/changelog/_index.md` | Add changelog entry for the pre-flight change in the next release section |
+
+**What is NOT changing:**
+
+- Ephemeral Podman sandbox (`uf sandbox start` without DevPod) still requires Podman — only the DevPod workspace path (`uf sandbox create`) dropped the standalone binary requirement
+- `--backend podman` flag name is unchanged
+- UID mapping, mount modes, security model — all unchanged
+
+## Constitution Alignment
+
+Assessed against the Unbound Force org constitution.
+
+### I. Autonomous Collaboration
+
+**Assessment**: N/A
+
+This is a documentation-only change. No artifact interfaces, hero communication protocols, or runtime coupling are affected.
+
+### II. Composability First
+
+**Assessment**: N/A
+
+No hero functionality is added, removed, or modified. The change updates text content to reflect upstream CLI behavior changes.
+
+### III. Observable Quality
+
+**Assessment**: N/A
+
+No machine-parseable output or provenance metadata is involved. This is a static website content update.
+
+### IV. Testability
+
+**Assessment**: N/A
+
+Documentation changes are validated through `npm run build` (build succeeds) and visual verification (content renders correctly). No code-level testability concerns.
diff --git a/openspec/changes/devpod-preflight-docs/specs/sandbox-docs.md b/openspec/changes/devpod-preflight-docs/specs/sandbox-docs.md
@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: DevPod failure diagnostic hint
+
+The sandbox reference page MUST document that when `devpod up` fails, the CLI displays a diagnostic hint: `"run 'uf doctor' to diagnose or 'uf setup' to configure"`.
+
+#### Scenario: User reads about DevPod workspace troubleshooting
+- **GIVEN** a user is reading the sandbox reference page
+- **WHEN** they look for information about DevPod workspace creation failures
+- **THEN** they find documentation that `uf doctor` and `uf setup` are the recommended diagnostic and recovery commands
+
+### Requirement: Changelog entry for pre-flight change
+
+The changelog MUST include an entry documenting the removal of the standalone Podman binary pre-flight check for DevPod workspaces and the addition of the diagnostic hint.
+
+#### Scenario: User checks changelog for breaking changes
+- **GIVEN** a user is reading the changelog for the next release
+- **WHEN** they look for sandbox-related changes
+- **THEN** they find an entry describing the DevPod pre-flight change (removed `podman` binary check, added diagnostic hint)
+
+## MODIFIED Requirements
+
+### Requirement: Sandbox prerequisites
+
+The sandbox reference prerequisites MUST distinguish between ephemeral containers (which require Podman installed) and DevPod persistent workspaces (which do not require a standalone `podman` binary in `$PATH`). The documentation MUST clarify that `uf setup` registers a docker-type DevPod provider under the name `podman` via `DOCKER_PATH=podman`, handling runtime resolution automatically.
+
+Previously: "Prerequisites: Podman and DevPod must be installed."
+
+#### Scenario: User reads prerequisites for DevPod workspace
+- **GIVEN** a user wants to create a persistent DevPod workspace
+- **WHEN** they read the sandbox prerequisites
+- **THEN** they understand that `uf setup` configures the DevPod provider and they do not need to install standalone Podman separately
+
+#### Scenario: User reads prerequisites for ephemeral sandbox
+- **GIVEN** a user wants to run an ephemeral sandbox container
+- **WHEN** they read the sandbox prerequisites
+- **THEN** they understand that Podman must be installed for ephemeral containers
+
+### Requirement: Blog post Podman limitation
+
+The blog post "Current Limitations" section SHOULD clarify that the "Podman required" limitation applies to ephemeral containers only, not to DevPod persistent workspaces where the provider handles runtime resolution.
+
+Previously: "Podman required: The sandbox uses Podman, not Docker."
+
+#### Scenario: User reads blog post limitations
+- **GIVEN** a user is reading the sandbox isolation blog post
+- **WHEN** they read the current limitations section
+- **THEN** they understand that Podman is required only for ephemeral containers, and DevPod workspaces use a configured provider
+
+## REMOVED Requirements
+
+### Requirement: Standalone Podman binary as universal prerequisite
+
+Documentation MUST NOT state that users need `podman` in `$PATH` as a blanket prerequisite for all sandbox usage. The standalone binary requirement applies only to ephemeral containers, not DevPod workspaces.
+
+Reason: The upstream `LookPath("podman")` pre-flight check was removed from the DevPod code path. The docker provider aliased as `podman` (configured by `uf setup`) handles container runtime resolution without requiring the standalone binary.
diff --git a/openspec/changes/devpod-preflight-docs/tasks.md b/openspec/changes/devpod-preflight-docs/tasks.md
@@ -0,0 +1,28 @@
+<!--
+  [P] marks tasks eligible for parallel execution.
+  Add [P] when a task: (a) touches different files from
+  other [P] tasks in the group, (b) has no dependency
+  on prior tasks in the group, (c) can safely execute
+  without ordering constraints.
+  Do NOT add [P] when tasks modify the same file —
+  parallel workers will cause merge conflicts.
+  Tasks without [P] run sequentially first, then [P]
+  tasks run in parallel.
+-->
+
+## 1. Update sandbox reference prerequisites
+
+- [x] 1.1 [P] Update the Prerequisites paragraph in `content/docs/reference/sandbox.md` (line 15): split into ephemeral container prerequisites (Podman required) and DevPod persistent workspace prerequisites (`uf setup` configures the docker-type provider aliased as `podman`). Add note about the `devpod up` failure diagnostic hint (`uf doctor` / `uf setup`). File: `content/docs/reference/sandbox.md`
+
+## 2. Update blog post limitations
+
+- [x] 2.1 [P] Update the "Current Limitations" section in `content/blog/sandbox-isolation.md` (line 147): refine the "Podman required" limitation to clarify it applies to ephemeral containers only, and that DevPod persistent workspaces use a configured provider that handles runtime resolution automatically. File: `content/blog/sandbox-isolation.md`
+
+## 3. Add changelog entry
+
+- [x] 3.1 [P] Add a changelog entry to `content/docs/changelog/_index.md` documenting: (a) removed standalone `podman` binary pre-flight check for DevPod workspaces, (b) added diagnostic hint on `devpod up` failure directing users to `uf doctor` and `uf setup`. File: `content/docs/changelog/_index.md`
+
+## 4. Verification
+
+- [x] 4.1 Run `npm run build` to verify the site builds without errors
+- [x] 4.2 Verify constitution alignment: all four principles assessed as N/A (documentation-only change — no hero functionality, artifact interfaces, machine-parseable output, or testability implications)