docs(dev-corp): handoff 문서를 추가한다

agent-test/dev-corp/HANDOFF.md

@@ -0,0 +1,114 @@
+# dev-corp Control Plane Observability Handoff
+
+last_updated_at: 2026-07-13
+
+## Target
+
+- Environment: dev-corp
+- Scope: Control Plane compose group and observability ports
+- First entry points:
+  - `agent-test/dev-corp/inventory.yaml`
+  - `agent-test/dev-corp/rules.md`
+  - `.env.dev-corp.example`
+  - `docker-compose.yml`
+- Do not rely on `../.workspace-ops` on the dev-corp runner. The dev-corp setup environment is expected to have only the project checkout, so all required handoff and inventory details must be available inside this repo.
+
+## Current State
+
+- dev environment was deployed and verified in this session.
+- dev-corp environment was not deployed in this session because the dev-corp runner was not reachable from the current workspace.
+- dev-corp compose settings are documented only. In `agent-test/dev-corp/inventory.yaml`, `compose.setup_status` is `documented_only_current_session_not_deployed`.
+- Existing dev-corp public Edge path is still the active user path:
+  - artifact/bootstrap: `iop.ai.kr:18085`
+  - OpenAI-compatible: `digitalplatform.iop.ai.kr:18086`
+  - native Edge TCP: `iop.ai.kr:18087`
+  - Edge metrics: `iop.ai.kr:19102`
+- Do not expose PostgreSQL, Redis, Prometheus, Grafana, or Control Plane metrics to the public internet. Assume operator access through VPN or runner-local access.
+
+## Intended dev-corp Compose Profile
+
+- compose project: `iop-dev-corp-agent`
+- compose network: `iop-dev-corp-agent-net`
+- compose subnet: `10.89.2.0/24`
+- env file: `.env.dev-corp.example`
+- core services:
+  - `postgres`
+  - `redis`
+  - `control-plane`
+  - `web`
+  - `prometheus`
+  - `grafana`
+
+Host ports:
+
+- web: `13002`
+- Control Plane HTTP: `18002`
+- Client WS: `19004`
+- CP-Edge wire: `19005`
+- compose Edge-Node TCP: `19006`
+- PostgreSQL: `15402`
+- Redis: `16302`
+- Edge metrics: `19102`
+- Control Plane metrics: `19104`
+- Prometheus: `19112`
+- Grafana: `19122`
+
+## Public Port Policy
+
+Only open additional public ports if dev-corp Control Plane UI must be tested from an external browser:
+
+- `13002/tcp`
+- `18002/tcp`
+- `19004/tcp`
+
+Keep these internal/VPN-only:
+
+- `15402/tcp`
+- `16302/tcp`
+- `19104/tcp`
+- `19112/tcp`
+- `19122/tcp`
+
+`19005` and `19006` are not required for ordinary browser UI access. Open them only for explicit external Edge/Node connection validation.
+
+## Next Steps
+
+1. Restore access to the dev-corp runner (`fe@172.24.63.178`) or confirm the current replacement runner.
+2. Sync `/Users/fe/agent-work/iop-dev-corp` to the intended ref.
+3. Run `docker compose --env-file .env.dev-corp.example config` and confirm published ports match `agent-test/dev-corp/inventory.yaml`.
+4. Check port occupancy before starting services.
+5. Start the core group only:
+
+   ```bash
+   docker compose --env-file .env.dev-corp.example up -d postgres redis control-plane web prometheus grafana
+   ```
+
+6. Do not start compose `edge` unless the validation explicitly requires it.
+7. Validate:
+   - `curl -fsS http://127.0.0.1:18002/healthz`
+   - `curl -fsS http://127.0.0.1:18002/readyz`
+   - WebSocket upgrade on `ws://<host>:19004/client` if UI is public.
+   - Prometheus readiness on runner-local `127.0.0.1:19112`.
+   - Grafana health on runner-local `127.0.0.1:19122/api/health`.
+
+## Open Decision
+
+The generic Prometheus compose config scrapes `control-plane:9093` and compose `edge:9092`. If dev-corp keeps using the native public Edge instead of compose Edge, decide whether to add a dev-corp-specific Prometheus config that scrapes the native Edge metrics endpoint via a runner-reachable address.
+
+## Evidence From This Session
+
+- dev Control Plane/UI stack was deployed with `postgres`, `redis`, `control-plane`, `web`, `prometheus`, and `grafana`.
+- dev external checks passed for:
+  - `http://toki-labs.com:13001`
+  - `http://toki-labs.com:18001/healthz`
+  - `ws://toki-labs.com:19001/client`
+- dev Prometheus targets were `up` for:
+  - `control-plane:9093`
+  - `host.docker.internal:19101`
+  - `prometheus:9090`
+- dev-corp public checks showed existing Edge paths open (`18085`, `18086`, `18087`, `19102`) and Control Plane UI path closed (`13002`, `18002`, `19004`) before any dev-corp compose deployment.
+
+## Notes
+
+- Do not record API keys, tokens, DB passwords, or private credentials in tracked docs.
+- `source.remote_runner.setup_status` in `inventory.yaml` refers to the existing source/build/provider runner context. The compose-specific deployment status is tracked separately under `compose.setup_status`.