update documentation (8 files)

README.md

@@ -95,7 +95,7 @@ npm run lint
 
 - **"missing bearer token"** from `/users/bootstrap` — Clerk session not attached. Sign out and back in.
 - **`Gitea did not become ready`** during provisioning — Gitea takes 10–20s on first pull. Wait, then `POST /actors/provision` (the frontend retries via polling).
-- **OpenCode container exits immediately** — check `OPENCODE_IMAGE`. The compose env passes `Cmd: ["serve", ...]`; if you swap to a different image, ensure it exposes the `opencode serve` HTTP surface on `:4096`.
+- **OpenCode container exits immediately** — check `OPENCODE_IMAGE`. The backend starts containers with `Cmd: ["opencode", "serve", ...]`; if you swap images, ensure they expose the OpenCode HTTP surface on `:4096`.
 - **`No free ports in USER_PORT_RANGE`** — bump `USER_PORT_RANGE_END` in `.env` or stop unused user stacks via `POST /actors/stop`.
 
 ## PRD status

agents/emily.md

@@ -3,8 +3,6 @@ id: emily
 name: Emily
 role: Roleplay Agent
 service: roleplay-service
-tools:
-  - start_roleplay_session
 ---
 
 ## Domain

agents/job-apply.md

@@ -2,10 +2,6 @@
 id: job-apply
 name: Job Apply Agent
 role: Application Operator
-tools:
-  - prepare_application
-  - track_submission
-  - schedule_followup
 ---
 
 ## Domain

agents/job-search.md

@@ -2,10 +2,6 @@
 id: job-search
 name: Job Search Agent
 role: Opportunity Scout
-tools:
-  - search_jobs
-  - rank_opportunities
-  - prepare_shortlist
 ---
 
 ## Domain

agents/qscore.md

@@ -3,9 +3,6 @@ id: qscore
 name: Quinn
 role: Q-Score Agent
 service: qscore-service
-tools:
-  - compute_qscore
-  - ingest_signals
 ---
 
 ## Domain

agents/resume.md

@@ -3,11 +3,6 @@ id: resume
 name: Resume Agent
 role: Resume Builder
 service: resume-service
-tools:
-  - build_resume
-  - review_resume
-  - tailor_resume
-  - analyze_resume
 ---
 
 Analyzes, builds, and tailors resumes for specific roles. Backed by the resume-builder microservice. Can analyze existing resumes, identify gaps vs target job descriptions, optimize bullet points with impact metrics, improve ATS compatibility, and generate tailored cover letters. Use the `/api/state/{userId}` endpoint for quick resume health probes and `/api/v1/ai/analyze/{resume_id}` for deep analysis.

agents/sara.md

@@ -3,8 +3,6 @@ id: sara
 name: Sara
 role: Interview Agent
 service: interview-service
-tools:
-  - start_interview_session
 ---
 
 ## Domain

docs/opencode-lifecycle-followups.md

@@ -0,0 +1,34 @@
+# OpenCode Lifecycle Follow-ups
+
+These are non-blocking improvements deferred during the time-crunch pass.
+
+## Architecture split
+
+Longer term, keep these concerns independently scalable:
+
+- **Frontend**: Next.js app, hosted separately.
+- **Core backend/API**: auth, DB, workflows, user-facing routes.
+- **Actor runtime**: Rivet user actors; actors orchestrate work and call control-plane APIs.
+- **OpenCode lifecycle/control plane**: Docker/Kubernetes/Fly/Nomad manager that creates, health-checks, upgrades, and tears down per-user OpenCode runtimes.
+- **Git service**: Gitea or hosted Git provider, reachable through a public URL.
+
+Today, `src/docker/manager.ts` is not a separate service. It is an internal module inside `growqr-backend`; authenticated HTTP routes under `/opencode` and `/actors` call into it, and the user actor calls into it directly through imports.
+
+## Deferred hardening
+
+- Add a dedicated OpenCode lifecycle service/API instead of embedding Docker control in the backend process.
+- Add admin rollout endpoints for image/prompt upgrades:
+  - recreate one user's OpenCode container
+  - recreate all stale containers
+  - inspect container version/labels/health
+- Make `provisionUserStack` validate existing `running` rows instead of trusting DB state.
+- Make `startOpencodeContainer` inspect existing containers and recreate them if image/version/labels/env are stale.
+- Make `reconcileOnBoot` mark stale containers as stopped/needs migration instead of only logging.
+- Add explicit migration state to `user_stacks` if rollouts need to be asynchronous.
+- Attach spawned OpenCode containers to a controlled Docker network or move to an orchestrator-native network model.
+- Split service URLs consistently for every external dependency:
+  - public browser URL
+  - backend internal URL
+  - OpenCode/container egress URL
+- Add rate limits and stricter resource quotas per user/container.
+- Encrypt stored OpenCode per-container passwords or move them to a secrets manager.