Merge branch 'docs/partial-adoption' into feat/init-discovery-validation

Author: roodboi

docs/guides/agent-first-setup.md

@@ -64,6 +64,53 @@ never go stale on substance.
 5. Verification loop — `hack up --json` → `hack ps --json` → `hack open --json`
    → curl or `hack logs`, iterating until `hack doctor` is clean.
 
+## Partial adoption (backing services only)
+
+Full containerization (every process in compose) is the default recommendation, but
+it is not the only supported shape. hack works fine running only the backing
+services — postgres, temporal, redis, and similar — while app dev servers (`bun
+dev`, `dotnet watch`, `vite`) stay on the host.
+
+**When to choose it:**
+- Heavy native toolchains (.NET, large native builds) develop faster on the host
+  than in a container.
+- The hot-path dev server (the one you restart constantly) benefits from host-native
+  file watching, debuggers, or hot reload that containers make slower or flakier.
+- The team already has a working host-based dev workflow and containerizing it is
+  not worth the churn.
+
+**What hack still gives you in this shape:**
+- Stable hostnames and TLS for the backing services via Caddy (`postgres.<project>.hack`,
+  `temporal.<project>.hack`, ...), so host processes and containers address them the
+  same way.
+- Branch instances for the containerized services (`--branch <name>`), even though
+  the host-run app processes are not branch-isolated on their own.
+- Committed, hack-managed env (`hack env add`) for connection strings and secrets,
+  instead of hand-maintained `.env` files.
+- Lifecycle hooks (`startup`/`lifecycle` in `.hack/hack.config.json`) for host-side
+  setup — tunnels, SSO bootstrap — that would otherwise be ad-hoc terminal steps.
+
+**How to wire it:**
+- Define only the backing services in `.hack/docker-compose.yml`; add Caddy labels
+  where a stable hostname is useful (databases usually don't need one — connect by
+  container port — but admin UIs, queues, or shared services often do).
+- Give host dev servers their connection info via `hack host exec --scope <svc> --
+  <cmd>` (injects the resolved env without touching `.env` files) or `hack env list`
+  for a one-off lookup.
+- App URLs can stay on plain `localhost:<port>` for the fast path, or get promoted
+  to a routed compose service later if you want a stable `*.hack` hostname for them
+  too — the two are not mutually exclusive and can be migrated incrementally.
+
+**Tradeoffs vs full containerization:**
+- No single `hack up` brings up the whole stack for a newcomer — they still need to
+  start the host dev servers themselves (document that step).
+- Host-run app processes are not branch-isolated by hack; running two branches side
+  by side means varying ports/env per worktree yourself.
+
+Partial adoption is a valid end state, not an incomplete migration — do not treat it
+as something to "finish" into full containerization unless the tradeoffs above
+actually bite.
+
 ## Copy-paste bootstrap
 
 Paste this into a fresh Claude Code / Codex session started at the repo root:

src/agents/onboarding-prompt.ts

@@ -108,7 +108,7 @@ function renderInventoryPhase(): string[] {
     "- Read the root package.json, workspace globs, and lockfiles to identify the package manager and monorepo layout.",
     "- Identify runnable services (web, api, workers): dev/start scripts, framework configs, and the ports they listen on.",
     "- Detect databases, caches, and queues from code and config: ORM schemas (prisma/drizzle), migration dirs, existing Dockerfiles and compose files.",
-    "- List every `.env*` file. Their keys and values are candidates for `hack env add`; treat `.env.example` values as placeholders (ask the user for real values or leave them unset).",
+    "- List every `.env*` file. Their keys and values are candidates for `hack env add`; treat `.env.example` values as placeholders (ask the user for real values or leave them unset). Not every repo has `.env*` files — also harvest candidate keys from `environment:` blocks in existing compose files, `ENV` lines in Dockerfiles, and CI config (workflow env/secrets).",
     "- Note repo scripts that need env vars to run (migrations, seeds, codegen) — they will run via `hack host exec` or an ops container later.",
     "- Read README/docs for one-time setup steps you might otherwise miss.",
   ];
@@ -128,6 +128,8 @@ function renderSetupPhase(opts: {
     "## Phase 2 — Set up hack",
     "",
     bootstrap,
+    "- Decide full containerization vs backing-services-only (partial adoption): if the inventory shows heavy native toolchains (.NET, large native builds) or the human prefers host dev servers, compose backing services (db/queue/cache) only and keep app dev servers on the host pointed at the routed services — ask the human when it's ambiguous; partial adoption is a valid end state, not a fallback to fix later.",
+    "- Check for reuse before authoring new services: if the repo already containerizes for prod (existing Dockerfiles/compose with build contexts, runtime-config injection points like an nginx-served runtime-config.js), prefer reusing those images/contexts with minimal glue over hand-authoring new dev-mode services from scratch.",
     "- Define one compose service per runnable process in `.hack/docker-compose.yml`. HTTP services need the Caddy labels (`caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`) and the `hack-dev` network to be routable.",
     `- Design hostnames: the primary app answers on dev_host (${devHostExample}); every other routable service gets a subdomain (\`api.${devHostExample}\`, \`grafana.${devHostExample}\`, ...). Set dev_host in \`.hack/hack.config.json\`.`,
     "- Migrate env values: for each key found during inventory run `hack env add <KEY> <value>` — add `--secret` for anything sensitive (API keys, tokens, passwords, connection strings with credentials). Never commit plaintext secrets to the repo.",