Imported from JoernStoehler/tetraspore-gemini (.devcontainer/AGENTS.md). Install upstream with npx skills add JoernStoehler/tetraspore-gemini --skill .devcontainer. Copyright stays with the author.

Environments Guide (Local, Codespaces, Codex Cloud)

This repo ships three small, opinionated dev environments. Each mirrors the same lifecycle names (post-create, post-start), even if the hosting platform uses different terms.

Goals

• Keep developers productive with a single golden path per environment
• Avoid fragile scripting; never fail container creation/start due to workspace issues
• Minimize surprises across environments

What we explicitly avoid

• Telemetry, CLI aliases, auto-editing config files
• Heavy auto-setup; scripts are best-effort and idempotent

Local DevContainer

• Path: .devcontainer/local/
• Image: mcr.microsoft.com/devcontainers/universal:2 (Node.js 20 preinstalled)
• Secrets: local .env (optional). Never commit .env.
• Volumes: persisted for ~/.npm and shell history
• Lifecycle:
  • post-create.sh: ensures PATH; respects .nvmrc (Node 20); installs npm deps; optionally installs MkDocs for docs preview
  • post-start.sh: hydrates npm deps (idempotent)
• VS Code extensions: ESLint, Prettier, Vitest Explorer, YAML, icons, Error Lens

GitHub Codespaces

• Path: .devcontainer/codespace/
• Image: Universal (pre-cached). The devcontainer.json leaves the image commented, which selects the prebuilt Universal image in Codespaces.
• Secrets: injected as env vars from GitHub Secrets; no .env
• Lifecycle:
  • post-create.sh: ensures PATH; respects .nvmrc (Node 20); installs npm deps; optionally installs MkDocs
  • post-start.sh: hydrates npm deps (idempotent)
• VS Code extensions: ESLint, Prettier, Vitest Explorer, YAML, icons, Error Lens

Codex Cloud

• Path: .devcontainer/codex/
• No devcontainer.json; use the Codex Cloud UI
  • Setup script → .devcontainer/codex/post-create.sh
  • Maintenance script → .devcontainer/codex/post-start.sh
• Secrets: injected via the Cloud UI; no .env
• Behavior:
  • Setup: adds PATH export to ~/.bashrc; hydrates npm deps; optionally installs MkDocs
  • Start: ensures PATH; hydrates npm deps if package.json is present

Golden Commands

• Dev server: npm run dev
• Tests: npm test
• Lint: npm run lint
• Type-check: npm run typecheck
• Storybook: npm run storybook
• Docs (local): npm run docs:serve (MkDocs)

Constraints and Practices

• Scripts never use set -e or pipefail; they log and continue
• We do not rely on volumes in Codespaces or Codex Cloud
• PATH is appended to ~/.bashrc once on create; start scripts ensure PATH in non-interactive shells
• Node 20 across environments; Python is optional for docs tooling

Picking an Environment

• Local: maximum performance and persistent caches
• Codespaces: hosted VS Code with GitHub-managed secrets
• Codex Cloud: headless agent-only environment

Git Hooks

We do not use local Git hooks. All checks (lint, type-check, tests) run in CI via GitHub Actions. This avoids local friction and keeps enforcement consistent.