Dev Container Maintenance

Maintain .devcontainer/ so it stays in sync with the project's regular development requirements.

Spec & Documentation

• Spec: .ai/specs/implemented/SPEC-050-2026-02-26-dev-container-setup.md
• User docs: .devcontainer/README.md

Dev Container File Map

Workflow

1. Audit (compare regular setup vs dev container)

Read and follow the checklist in references/audit-checklist.md. It covers version alignment, service parity, env var sync, package coverage, system deps, port forwarding, and build sequence.

2. Diagnose (when something is broken)

Read the guide in references/troubleshooting.md. Covers container build failures, health check failures, postCreateCommand step failures, env var mismatches, volume permissions, and DB migration conflicts.

3. Fix (apply changes)

After identifying drift or bugs:

1. Make the minimal change to the affected file(s) per the file map above
2. New .env.example keys needing container values: add sed rules to setup-env.sh with verification
3. New service: add to .devcontainer/docker-compose.yml with health check + forward port in devcontainer.json
4. Node.js or Yarn version change: update .devcontainer/Dockerfile (FROM line and corepack prepare)
5. Update documentation (see step 4 below) — this is mandatory for every change

4. Update documentation (mandatory after every change)

Every dev container change MUST be reflected in both documentation files. Skipping this causes drift between implementation and docs.

.devcontainer/README.md — user-facing docs

Update the relevant section(s):

• Services table — when adding/removing/upgrading a service
• Named Volumes table — when adding/removing volumes
• Lifecycle Hooks section — when changing bootstrap steps
• Environment Variables section — when changing env var handling
• Key Design Decisions table — when making a new architectural choice
• Common Tasks table — when adding new developer commands
• Updating the Dev Container table — when the maintenance protocol itself changes
• Troubleshooting table — when discovering new failure modes or fixes

.ai/specs/SPEC-050-2026-02-26-dev-container-setup.md — spec

Use the om-spec-writing skill (/om-spec-writing) to update the spec properly. At minimum:

• Changelog section: Add a dated entry with a concise summary of what changed and why
• Architecture / Volume Strategy / Configuration tables: Update if services, volumes, ports, or versions changed
• Design Decisions table: Add a row if a new architectural decision was made
• Risk Register: Add/update entries if the change introduces or mitigates a risk
• Service Versions table: Update when any image tag changes
• Compliance Matrix: Re-verify if the change touches areas covered by root AGENTS.md rules

The spec-writing skill ensures the update follows project conventions (TLDR, structured sections, compliance gate).

Key Comparison Points

Version sources (regular setup) vs targets (dev container):

Environment variable flow:

apps/mercato/.env.example
  → .devcontainer/scripts/setup-env.sh (sed rewrites)
  → apps/mercato/.env (generated, overwritten on rebuild)
  → apps/mercato/.env.local (manual overrides, never touched)

Build sequence equivalence:

Regular:   yarn install → yarn build:packages → yarn generate → yarn build:packages → yarn initialize
Container: post-create.sh steps [0]-[7] mirror this exact sequence