Initial commit

Author: briandominick

.agent/team/handoff-readme-volumes.md

@@ -0,0 +1,79 @@
+# DocOps Box — Agent Handoff Note
+
+**Date:** 2026-04-07  
+**From:** Chat agent (README overhaul session)  
+**To:** Co-agent  
+**Re:** README.adoc merge progress + named-volume architecture decision
+
+---
+
+## README Status
+
+Active work: merging a detailed original 1845-line README into a modernized 770-line structure. User has accepted all changes so far and added the full `ruby-for-real` appendix with their own edits. File is now ~1200+ lines and growing.
+
+**Completed sections** (all accepted by user):
+- Consolidated two quickstart guides (VS Code + CLI) into single `== Quick Start` with Option A / Option B
+- Prerequisites (all platforms: terminal, WSL2, Docker, VS Code)
+- Tooling Overview with definition lists
+- Codebase Overview
+- Configuration Reference
+- Volume Lifecycle
+- `docr` Command Reference
+- Troubleshooting
+- Extending DocOps Box
+- Development & Contribution
+- Appendices: Who Is This For, Background/ADR, Beyond Ruby DocOps, Installing Everything for Real (ruby-for-real)
+
+**Still needs work before release** — user has not specified what's next; treat the file as a live draft.
+
+**Key constraints:**
+- `docr` only — NO `docksh` or `docopsbox` CLI references anywhere
+- First-person voice throughout
+- LibreOffice only on `max`/`live` image
+- Regular users do NOT perform image builds — keep that in appendices/extending only
+- All sidebars use `ifdef::env-github` / `ifndef::env-github` conditional pattern
+- Single file (README.adoc) — no splitting
+
+---
+
+## Architecture Decision: Named Volumes for All Runtimes
+
+**Decision reached:** Use named Docker volumes consistently for all three runtime dependency trees (Ruby, Node.js, Python). Do NOT use workspace bind-mounts for installed packages.
+
+### Current state (inconsistent — needs fixing)
+
+| Runtime | Installed deps | Download cache |
+|---------|---------------|----------------|
+| Ruby | Named vol per-project (`/usr/local/bundle`) ✅ | n/a |
+| Node.js | Workspace bind-mount (`node_modules`) ⚠️ | Named vol shared (`/npm-cache`) |
+| Python | **Lost on container restart** ❌ | Named vol shared (`/pip-cache`) |
+
+### Target state
+
+| Runtime | Named volume | Mount point | Scope |
+|---------|-------------|-------------|-------|
+| Ruby gems | `docops-{slug}-bundle` | `/usr/local/bundle` | Per-project |
+| Node modules | `docops-{slug}-node` | `/workspace/node_modules` | Per-project |
+| Python packages | `docops-{slug}-python` | `/usr/local/lib/pythonX.Y/site-packages` (or a venv path) | Per-project |
+| npm download cache | `docops-npm-cache` | `/npm-cache` | Shared |
+| pip download cache | `docops-pip-cache` | `/pip-cache` | Shared |
+| Shell history | `docops-shell-history` | `/commandhistory` | Shared |
+
+### Rationale summary
+
+- Container-built `node_modules` contains Linux binaries — useless natively on macOS/Windows regardless of where it lives; "workspace path = native access" is an illusion
+- Python `.venv` in workspace creates broken symlinks from host filesystem; beginners will commit it to Git
+- Named volumes give consistent behavior on macOS, Linux, WSL2 with no bind-mount overhead
+- The one weakness (orphan volume lifecycle) is a `docr` tooling gap, not a reason to reject the strategy
+
+### Files that need updating
+
+1. **`Dockerfile`** — add `ENV` for Python package path; create/chown the new volume mount points
+2. **`docopsbox.yml`** — add `docops-{slug}-node` and `docops-{slug}-python` named volumes; update `volumes:` block
+3. **`.devcontainer/devcontainer.json`** — update `postCreateCommand` to include `pip install -r requirements.txt` (guarded like the others)
+4. **`README.adoc`** — update Volume Lifecycle table (add Node and Python rows), update "What Just Happened?" bullet list, update `docr reset` docs to mention all three volumes
+5. **`docr` script** — `docr reset` should destroy node and python volumes alongside bundle; `docr list`/`docr status` should show all three
+
+### Open question for Python mount path
+
+Using a fixed venv path (e.g., `/opt/venv`) set via `VIRTUAL_ENV` env var is cleaner than site-packages directly, and plays well with `pip install` without `--break-system-packages`. Confirm with user or research best practice for the base image in use.

.agent/team/handoff-restructure.md

@@ -0,0 +1,23 @@
+# Handoff: File Restructure
+
+**Date:** 2026-04-08
+
+Two structural changes — README needs updating:
+
+## `bin/docr` (was `docr` at root)
+
+- `curl` install URL changed: `.../bin/docr` not `.../docr` (already fixed in README line 470)
+- Codebase Overview: mention script lives at `bin/docr`
+
+## `templates/` (new directory)
+
+Files moved there: `docopsbox.yml`, `.env`, `dockerfile-pre-build.sh`, `dockerfile-post-build.sh`, `package.json`, `requirements.txt`, `.devcontainer/devcontainer.json`
+
+These are the project scaffold files users get via `docr init` (fetched from upstream). They are NOT active files in the repo itself.
+
+README needs:
+- Codebase Overview: describe `templates/` as the user-project scaffold library
+- Extending section: hook scripts (`dockerfile-pre-build.sh`, `dockerfile-post-build.sh`) now live at `templates/` in the repo, but users copy/create them at their own project root
+- Any remaining file listings that imply these files live at the repo root
+
+The `.devcontainer/` at the repo root is *gone* — it was only ever the template. If the repo needs its own dev container config in future, that's a separate concern.

.agent/team/handoff-volumes-implemented.md

@@ -0,0 +1,80 @@
+# DocOps Box — Agent Handoff: Volumes Architecture Implemented
+
+**Date:** 2026-04-07
+**From:** Tooling/script agent
+**To:** README/docs agent
+**Re:** Named-volume architecture decision is fully implemented
+
+---
+
+## What Was Done
+
+All five files from the handoff plan are updated and shellcheck-clean.
+
+### `Dockerfile`
+- `VIRTUAL_ENV=/opt/venv` added to `ENV` block
+- `PATH` updated: `/opt/venv/bin:/usr/local/bundle/bin:$PATH`
+- `python3-venv` added to the Python apt install block
+- `mkdir -p` now creates `/opt/venv` and `$WORKDIR/node_modules` as volume mount points
+- `chown -R` covers `/opt/venv` (mount points must pre-exist and be owned by run user)
+
+### `entrypoint.sh`
+- Added `/opt/venv` to the recursive `chown` at startup
+- Added `chown` of `/workspace/node_modules` (named volume mount, not workspace bind)
+- Added lazy venv bootstrap: if `VIRTUAL_ENV` is set, `/opt/venv/bin/python` is absent,
+  and `python3` exists → runs `python3 -m venv /opt/venv` as root then chowns it.
+  Fires only on first container start after a fresh/reset volume; no-op thereafter.
+
+### `docopsbox.yml`
+Two new per-project named volumes:
+- `docops-{slug}-node` → mounted at `/workspace/node_modules`
+- `docops-{slug}-python` → mounted at `/opt/venv`
+
+Both are declared in the `volumes:` section with slug-interpolated names.
+Existing shared caches (`docops-npm-cache`, `docops-pip-cache`) are unchanged.
+
+### `.devcontainer/devcontainer.json`
+- `postCreateCommand` now also runs `pip install -r requirements.txt` (guarded: only
+  if `requirements.txt` exists)
+
+### `docr` script
+- `cmd_reset`: `node_vol` and `python_vol` variables added; both are removed on plain
+  `reset` and on `--full`. Help text updated accordingly.
+- `cmd_status`: now reports node and python volume state/size alongside bundle.
+- `cmd_list`: disposition labels improved — shared download caches labeled separately
+  from per-project disposable volumes.
+- `cmd_help`: reset description updated to name gems/node/python.
+
+---
+
+## Final Volume Architecture (Implemented)
+
+| Volume | Docker name | Mount point | Scope |
+|--------|-------------|-------------|-------|
+| Ruby gems | `docops-{slug}-bundle` | `/usr/local/bundle` | Per-project |
+| Node modules | `docops-{slug}-node` | `/workspace/node_modules` | Per-project |
+| Python venv | `docops-{slug}-python` | `/opt/venv` | Per-project |
+| npm download cache | `docops-npm-cache` | `/npm-cache` | Shared |
+| pip download cache | `docops-pip-cache` | `/pip-cache` | Shared |
+| Shell history | `docops-shell-history` | `/commandhistory` | Shared |
+
+---
+
+## README Updates Needed (Your Side)
+
+The Volume Lifecycle section and related prose need to reflect:
+
+1. **Volume table**: Add Node modules and Python venv rows (see table above)
+2. **"What Just Happened?" bullet list** (after `docr init`/`docr run`): mention that
+   node_modules and the Python venv are now in named volumes, not in the workspace
+3. **`docr reset` docs**: say "dependency caches (gems, node modules, Python venv)"
+   rather than just "gem cache"
+4. **Why named volumes for Node/Python** (a brief explainer, or a sidebar): Linux
+   binaries in node_modules are useless on macOS/Windows host; Python venv uses
+   symlinks that break on the host filesystem. Named volumes keep them inside Docker
+   where they work correctly and persist across restarts.
+5. **`VIRTUAL_ENV` / Python**: users can `pip install` normally inside the container;
+   no `--user` or `--break-system-packages` flags needed. The venv is at `/opt/venv`.
+
+The `uninstall` subcommand was also added since the last handoff — you may want a
+one-liner in the command reference: removes installed binary and backup data dir.

.config/actionlint.yml

@@ -0,0 +1,13 @@
+# actionlint configuration for this project
+# References DocOps Lab base configuration
+
+# Project-specific ignores (add as needed):
+ignore:
+  # Example: Ignore specific workflow patterns
+  # - 'workflow "deploy.yml"'
+  # - '"ubuntu-20.04" is deprecated'
+  
+# Project-specific overrides:
+shellcheck:
+  enable: true
+  # shell-options: "-e SC2016"  # Add project-specific ShellCheck exclusions

.config/docopslab-dev.yml

@@ -0,0 +1,77 @@
+source:
+  repo: DocOps/lab
+  ref: v1
+docs:
+  - source: docs/agent/skills/*.md
+    target: .agent/docs/skills/
+    synced: true
+  - source: docs/agent/topics/*.md
+    target: .agent/docs/topics/
+    synced: true
+  - source: docs/agent/roles/*.md
+    target: .agent/docs/roles/
+    synced: true
+  - source: docs/agent/missions/*.md
+    target: .agent/docs/missions/
+    synced: true
+
+templates:
+  manifest:
+    - source: templates/AGENTS.markdown
+      target: ./AGENTS.md
+    - source: templates/gitignore
+      target: .gitignore
+    - source: templates/README.asciidoc
+      target: README.adoc
+
+tools:
+  - tool: rubocop
+    files:
+      - source: rubocop/base.yml
+        target: .config/.vendor/docopslab/rubocop.yml
+        synced: true
+      - source: rubocop/project.yml
+        target: .config/rubocop.yml
+        synced: false
+
+  - tool: vale
+    files:
+      - source: vale/base.ini
+        target: .config/.vendor/docopslab/vale.ini
+        synced: true
+      - source: vale/project.ini
+        target: .config/vale.local.ini
+        synced: false
+
+  - tool: htmlproofer
+    enabled: false  # Disabled by default, enable per project
+    files:
+      - source: htmlproofer/base.yml
+        target: .config/.vendor/docopslab/htmlproofer.yml
+        synced: true
+      - source: htmlproofer/project.yml
+        target: .config/htmlproofer.yml
+        synced: false
+    paths:
+      lint: docs/_site
+
+  - tool: shellcheck
+    files:
+      - source: shellcheck/base.shellcheckrc
+        target: .config/shellcheckrc
+        synced: true
+  
+  - tool: actionlint
+    files:
+      - source: actionlint/base.yml
+        target: .config/.vendor/docopslab/actionlint.yml
+        synced: true
+      - source: actionlint/project.yml
+        target: .config/actionlint.yml
+        synced: false
+
+library:
+  enabled: true
+  source:
+    repo: DocOps/lab
+    ref: labdev-library

.config/shellcheckrc

@@ -0,0 +1,14 @@
+# ShellCheck configuration for DocOps Lab projects
+# This file is synced from docopslab-dev gem
+
+# Disable some overly strict rules for our use cases
+disable=SC2034 # Variable appears unused (common in sourced scripts)
+disable=SC2086 # Double quote to prevent globbing (sometimes we want globbing)
+disable=SC2181 # Check exit code directly with e.g. 'if mycmd;', not indirectly with $?
+
+# Set default shell to bash (most of our scripts are bash)
+shell=bash
+
+# Enable additional optional checks
+enable=quote-safe-variables
+enable=require-variable-braces

.config/vale.local.ini

@@ -0,0 +1,5 @@
+# DocOps Lab Vale Configuration
+# Combined base and project configuration for consistent Vale linting
+
+MinAlertLevel = warning
+StylesPath = .vendor/vale/styles

.dockerignore

@@ -0,0 +1,43 @@
+# DocOps Box — Docker build context exclusions
+# Keeps the build context fast and prevents development files from leaking into
+# the image. Files intentionally included in the build (Gemfile*, package.json,
+# requirements.txt, dockerfile-*.sh) are expected in the project root (the
+# build context) and are NOT listed here. The repo's own copies live under
+# templates/ but users place them at their project root before building.
+
+# Repo-only directories — not needed in user image builds
+templates/
+bin/
+scripts/
+
+# Version control
+.git/
+.gitignore
+
+# Agent/session scratch directories
+.agent/
+.agents/
+
+# Documentation source (not needed inside the image)
+*.adoc
+*.html
+LICENSE
+
+# Development tooling configs
+.config/
+Rakefile
+
+# Editor and IDE
+.vscode/
+.idea/
+
+# OS artifacts
+.DS_Store
+
+# Runtime artifacts
+_site/
+.jekyll-cache/
+tmp/
+*.log
+*.bak
+*~