Portable setup: venv, Claude Code + Codex project config

Makes the skill work on any laptop regardless of installed Python version
or LLM harness, without per-command approval prompts or missing deps.

- Makefile: auto-detect Python (venv > 3.12 > 3.11 > 3.10 > python3)
  and new `make venv` target that picks the best Python at creation time
- .claude/settings.json: project-level Claude Code permissions
  (Write to examples/ and output/, common bash commands pre-authorized)
- .codex/config.toml: Codex sandbox config with network_access=true,
  approval_policy=never, sandbox_mode=workspace-write — fixes
  `make venv` failing with "No matching distribution" in Codex
- CLAUDE.md / AGENTS.md: document the `make venv` flow, drop all
  hardcoded python3.12 references in favor of make targets
- CLAUDE.md: add Karpathy-style coding guidelines (think before coding,
  simplicity first, surgical changes, goal-driven execution)
- .gitignore: add .venv/

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(**)",
+      "Write(examples/**)",
+      "Write(output/**)",
+      "Bash(python3.12:*)",
+      "Bash(python3:*)",
+      "Bash(.venv/bin/python:*)",
+      "Bash(make:*)",
+      "Bash(git:*)",
+      "Bash(pip:*)",
+      "Bash(pip3:*)",
+      "Bash(pip3.12:*)",
+      "Bash(ls:*)",
+      "Bash(which:*)",
+      "Bash(find:*)"
+    ]
+  }
+}

.codex/config.toml

@@ -0,0 +1,21 @@
+# Codex project configuration for OCI Deal Accelerator
+# Applies to every user who opens this project with Codex CLI.
+
+# Allow the agent to run commands without per-command approval prompts.
+approval_policy = "never"
+
+# Workspace-write: agent can write inside the project root but not system-wide.
+sandbox_mode = "workspace-write"
+
+[sandbox_workspace_write]
+# Allow network access so `pip install -r requirements.txt` and `make venv`
+# can actually download dependencies. Without this, Codex blocks PyPI.
+network_access = true
+writable_roots = []
+exclude_tmpdir_env_var = false
+exclude_slash_tmp = false
+
+[shell_environment_policy]
+# Inherit the user's shell env so python3.12 / python3 resolution works
+# the same way as the Makefile expects.
+inherit = "all"

.gitignore

@@ -1,3 +1,4 @@
+.venv/
 __pycache__/
 *.pyc
 *.pyo

AGENTS.md

@@ -85,32 +85,39 @@ DEFINE (Ideate → Validate → Plan)  →  DESIGN (Current → Future → Confi
 
 Phase details in `docs/` — skill references them via progressive disclosure.
 
+## Environment Setup (MANDATORY before running tools)
+
+```bash
+make venv && source .venv/bin/activate
+```
+
+The Makefile auto-detects the best available Python (3.12 > 3.11 > 3.10 > python3).
+**Always use `make <target>` to run tools.** For custom specs, activate the venv first.
+
+### Codex sandbox note
+
+This project ships `.codex/config.toml` which enables `network_access = true`
+for the workspace-write sandbox. This is required so `make venv` can reach
+PyPI. If you see `No matching distribution found for pyyaml`, the config file
+is missing or Codex is ignoring it — re-open the project from its root so
+Codex loads `.codex/config.toml`.
+
 ## Running Tools
 
 ```bash
-# Generate slide deck (default output)
+# Standard targets (recommended)
-python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx
+make deck                    # slide deck with sample spec
-
+make diagram                 # architecture diagram
-# Generate customer-facing PDF (branded, no internal KB refs)
+make full                    # all outputs (pptx + drawio + docx + xlsx + pdf)
-python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf
+make validate                # WA validation
-
-# Generate diagram
-python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio
-
-# Run WA validation
-python scripts/validate-architecture.py \
-  --profile examples/sample-workload-profile.yaml \
-  --architecture examples/sample-architecture.yaml \
-  --output scorecard.yaml
-
-# Output orchestrator (multiple formats at once)
-python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/
-
-# Build automation
-make help           # show all commands
-make full           # generate all outputs
-make validate       # run WA validation
 make lint                    # check YAML syntax
+make venv                    # create/update virtual environment
+
+# Custom specs (activate venv first)
+python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx
+python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf
+python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio
+python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/
 ```
 
 ## Output Formats

CLAUDE.md

@@ -110,47 +110,44 @@ doc only          ← technical doc without slides
 deliver           ← handover + go-live checklist + success criteria
 ```
 
-## Running Tools
+## Environment Setup
+
+Before running ANY Python tool, ensure dependencies are installed:
 
 ```bash
-# Generate slide deck (default output)
+make venv && source .venv/bin/activate
+```
+
+The Makefile auto-detects the best available Python (3.12 > 3.11 > 3.10 > python3).
+**Always use `make <target>` to run tools** — this guarantees the correct Python with all dependencies.
+
+## Running Tools
+
+Prefer `make` targets. For custom specs, activate the venv first (`source .venv/bin/activate`), then use `python`:
+
+```bash
+# Standard targets (recommended)
+make deck                    # slide deck with sample spec
+make diagram                 # architecture diagram
+make full                    # all outputs (pptx + drawio + docx + xlsx + pdf)
+make validate                # WA validation
+make lint                    # check YAML syntax
+make venv                    # create/update virtual environment
+make freshness               # check KB freshness
+
+# Custom specs (activate venv first)
 python tools/oci_deck_gen.py --spec examples/proposal-spec.yaml --output proposal.pptx
-
-# Generate customer-facing PDF (branded, no internal KB refs)
 python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf
-python tools/oci_pdf_gen.py --spec examples/proposal-spec.yaml --output proposal.pdf --diagram arch.png
-
-# Generate BOM (.xlsx Bill of Materials)
 python tools/oci_bom_gen.py --spec examples/bom-spec.yaml --output customer-bom.xlsx
-
-# Generate diagram
 python tools/oci_diagram_gen.py --spec examples/diagram-spec.yaml --output arch.drawio
-
-# Run WA validation
-python scripts/validate-architecture.py \
-  --profile examples/sample-workload-profile.yaml \
-  --architecture examples/sample-architecture.yaml \
-  --output scorecard.yaml
-
-# Output orchestrator (multiple formats at once)
 python tools/oci_output.py --spec examples/proposal-spec.yaml --format full --output-dir output/
 
-# Refresh SKU catalog from Oracle pricing API
+# KB maintenance (activate venv first)
 python tools/refresh_sku_catalog.py --refresh          # update all prices
 python tools/refresh_sku_catalog.py --refresh --diff   # update + show changes
 python tools/refresh_sku_catalog.py --validate         # check for stale prices
-python tools/refresh_sku_catalog.py --sku B110627      # inspect single SKU
-
-# Refresh Architecture Center catalog
 python tools/refresh_arch_catalog.py --whats-new       # crawl What's New pages
-python tools/refresh_arch_catalog.py --url <url>       # add single entry
 python tools/refresh_arch_catalog.py --validate        # validate catalog
-
-# Build automation
-make help           # show all commands
-make full           # generate all outputs
-make validate       # run WA validation
-make lint           # check YAML syntax
 ```
 
 ## Key Principles
@@ -162,6 +159,39 @@ make lint           # check YAML syntax
 - **KB is the moat** — field experience, not documentation regurgitation
 - **ECAL-aligned** — Define → Design → Deliver with iterative checkpoints
 
+## Coding Guidelines
+
+### 1. Think Before Coding
+Don't assume. Don't hide confusion. Surface tradeoffs.
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Simplicity First
+Minimum code that solves the problem. Nothing speculative.
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+### 3. Surgical Changes
+Touch only what you must. Clean up only your own mess.
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+- Remove imports/variables/functions that YOUR changes made unused.
+- Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+Define success criteria. Loop until verified.
+- "Add validation" → write tests for invalid inputs, then make them pass.
+- "Fix the bug" → write a test that reproduces it, then make it pass.
+- "Refactor X" → ensure tests pass before and after.
+- For multi-step tasks, state a brief plan with verification steps.
+
 ## Welcome Flow
 
 When the user starts a conversation without providing discovery notes or a specific request (e.g., a greeting like "hola", "hey", or empty context):

Makefile

@@ -2,7 +2,14 @@
 
 .PHONY: help install test validate example diagram deck full clean lint codex-package update-icons freshness freshness-refresh sync-skill
 
-PYTHON ?= python3.12
+# Use venv if present, otherwise find best available python3
+ifneq (,$(wildcard .venv/bin/python))
+  PYTHON ?= .venv/bin/python
+else ifneq (,$(shell command -v python3.12 2>/dev/null))
+  PYTHON ?= python3.12
+else
+  PYTHON ?= python3
+endif
 SPEC_DIR = examples
 OUTPUT_DIR = examples/sample-output
 
@@ -10,7 +17,16 @@ help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
 
-install: ## Install Python dependencies
+VENV_PYTHON := $(shell command -v python3.12 2>/dev/null || command -v python3.11 2>/dev/null || command -v python3.10 2>/dev/null || echo python3)
+
+venv: ## Create virtual environment and install dependencies
+	@echo "Using $(VENV_PYTHON) to create venv..."
+	$(VENV_PYTHON) -m venv .venv
+	.venv/bin/pip install --upgrade pip
+	.venv/bin/pip install -r requirements.txt
+	@echo "Virtual environment ready. Run: source .venv/bin/activate"
+
+install: ## Install Python dependencies (system-wide)
 	pip install -r requirements.txt
 
 validate: ## Validate imports and configs

codex/README.md

@@ -8,7 +8,10 @@
 # Navigate to the project root
 cd oci-deal-accelerator
 
-# Run Codex — it auto-discovers AGENTS.md and .agents/skills/
+# One-time: create virtual environment with all dependencies
+make venv
+
+# Run Codex — it auto-discovers AGENTS.md, .agents/skills/, and .codex/config.toml
 codex
 
 # Or explicitly load the skill
@@ -18,6 +21,18 @@ codex --skill oci-deal-accelerator
 Codex automatically reads:
 - `AGENTS.md` at project root (project-level instructions)
 - `.agents/skills/oci-deal-accelerator/SKILL.md` (the skill definition)
+- `.codex/config.toml` (project sandbox + approval config — **enables network for pip**)
+
+### Why `.codex/config.toml` matters
+
+By default Codex CLI blocks network access and prompts before every command.
+The committed `.codex/config.toml` pre-configures this project with:
+
+- `approval_policy = "never"` — no per-command prompts
+- `sandbox_mode = "workspace-write"` — agent can write in the repo
+- `network_access = true` — `pip install` and `make venv` actually work
+
+Without this file, `make venv` fails with `No matching distribution found for pyyaml` because PyPI is unreachable from the sandbox.
 
 ### Option 2: Using Codex App