feat: add OAuth staging docker-compose and env template

[cmeans-claude-dev]

Summary

• Adds docker-compose.oauth.yaml — isolated Docker Compose stack for testing OAuth/WorkOS AuthKit on port 8421 (separate containers, volumes, and tunnel from production)
• Adds .env.oauth.example — template with all required/optional env vars for staging
• Adds .env.oauth to .gitignore to prevent committing secrets

QA

Prerequisites

• Copy .env.oauth.example to .env.oauth and fill in WorkOS values
• Have a Cloudflare staging tunnel configured (or comment out tunnel-oauth service)

Manual tests (via MCP tools)

1. • Stack starts cleanly

   docker compose -f docker-compose.oauth.yaml --env-file .env.oauth up -d
   

   Expected: awareness-oauth, postgres-oauth, and awareness-tunnel-oauth containers running and healthy

2. • Briefing responds on staging port

   get_briefing()  # via MCP client pointed at localhost:8421 or staging.mcpawareness.com
   

   Expected: valid briefing JSON (may be empty if fresh database)

3. • Production unaffected

   get_briefing()  # via production MCP client
   

   Expected: production briefing still works, separate from staging data

4. • Clean teardown

   docker compose -f docker-compose.oauth.yaml down -v
   

   Expected: all staging containers and volumes removed

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

Adding QA Active — beginning code review and manual verification.

[cmeans]

QA Review — PR #137

CI Status

All checks green: lint ✓, typecheck ✓, tests (3.10/3.11/3.12) ✓, codecov/patch ✓

Code Review Findings

1. SUBSTANTIVE — pull_policy: always contradicts build: .
docker-compose.oauth.yaml:28 — The awareness-oauth service has both build: . and pull_policy: always. pull_policy applies to image pulls, but build triggers a local build. This is misleading. Either remove pull_policy (since you're building), or uncomment the image: line and remove build.

2. SUBSTANTIVE — Shared Ollama volume default between prod and staging
docker-compose.oauth.yaml:131 — ollama-oauth defaults to ${AWARENESS_OLLAMA_DATA:-~/awareness-ollama}, same as production (docker-compose.yaml:118). The comment says "shares model cache to avoid re-download," but concurrent access from both stacks could corrupt data. Consider defaulting to ~/awareness-ollama-oauth, or documenting mutual exclusion.

3. OBSERVATION — Hardcoded AWARENESS_PUBLIC_URL
docker-compose.oauth.yaml:48 — AWARENESS_PUBLIC_URL=https://staging.mcpawareness.com is hardcoded rather than parameterized via ${AWARENESS_PUBLIC_URL:-https://staging.mcpawareness.com}. Inconsistent with the pattern used for other variables.

4. NIT — Example issuer in template
.env.oauth.example:5 — AWARENESS_OAUTH_ISSUER=https://thoughtful-saga-02-staging.authkit.app includes what appears to be a real WorkOS staging domain. Consider using a placeholder like https://your-app.authkit.app.

Manual Test Results

#	Test	Result
1	Stack starts cleanly (3 containers healthy)	PASS
2	Briefing responds on staging port 8421 (JWT auth enforced, valid JSON)	PASS
3	Production unaffected on port 8420	PASS
4	Clean teardown (down -v removes all containers/network)	PASS

Verdict

4/4 manual tests pass. 2 substantive findings, 1 observation, 1 nit. Substantive items (#1 pull_policy, #2 shared Ollama volume) should be addressed before merge.

[cmeans]

QA Audit — 4/4 manual tests pass, CI all green. 2 substantive findings posted in review (pull_policy contradiction, shared Ollama volume). Applying QA Failed pending resolution of substantive items.

[cmeans]

Adding QA Active — starting second-round review to verify fixes for findings #1–#4.

[cmeans]

QA Re-Review — PR #137 (Round 2)

Fix Verification

All 4 findings from Round 1 addressed in commit 85f5bd8:

#	Severity	Finding	Status
1	SUBSTANTIVE	pull_policy: always contradicts build: .	FIXED — pull_policy removed
2	SUBSTANTIVE	Shared Ollama volume default	FIXED — defaults to ~/awareness-ollama-oauth, comment clarifies isolation
3	OBSERVATION	Hardcoded AWARENESS_PUBLIC_URL	FIXED — parameterized via ${AWARENESS_PUBLIC_URL:-...}
4	NIT	Real WorkOS domain in template	FIXED — replaced with https://your-app.authkit.app

Additional Scan

No new issues introduced by fix commit. Verified:

• Localhost-only port binding preserved (127.0.0.1:8421:8421)
• Required env vars still use ?Set ... error syntax
• Postgres volume still isolated (~/awareness-oauth-pg)
• Resource limits and healthchecks intact
• Ollama behind profiles: [embeddings]

CI Status

All checks green: lint ✓, typecheck ✓, tests (3.10/3.11/3.12) ✓, codecov/patch ✓

Verdict

0 open findings. All substantive issues resolved. PR is ready for signoff.

[cmeans]

QA Audit (Round 2) — All 4 round-1 findings verified fixed. CI all green. 0 open findings. Applying Ready for QA Signoff.

[cmeans]

LGTM