diff --git a/README.md b/README.md
index 63afc70..95683be 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,125 @@
 # NomadCode
 
-NomadCode is the monorepo for the mobile app, web console, core service, shared contracts, and agent-operation rules that coordinate AI-assisted development workflows.
+NomadCode is a monorepo for AI-assisted development workflows. It brings together a Go orchestration service, a React/Vite operator console, a Flutter client, shared contract space, and root-level agent-operation rules.
 
-## Workspace
+The repository is currently an early product scaffold. The core service owns task orchestration and persistence, the web and mobile apps provide initial operator surfaces, and `agent-ops/` keeps the rules and roadmap that AI agents need before changing the workspace.
 
-- `apps/mobile`: Flutter client.
-- `apps/web`: React/Vite web console.
-- `services/core`: Go backend and orchestration service.
-- `packages/contracts`: shared API contracts and generated client boundary.
-- `agent-ops`: root-level rules, skills, and routing context for AI agents.
-- `docs`: architecture and operations notes.
-- `bin`: workspace helper commands.
+## Current Status
 
-## Common Commands
+- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, model/A2A client paths, and Plane/Mattermost adapter stubs.
+- `apps/web` is a React/Vite scaffold for Agent, Projects, and Settings views. Some state and integration status areas are still mocked or stubbed.
+- `apps/mobile` is a Flutter app scaffold with Firebase Messaging, local notifications, and HTTP client dependencies.
+- `packages/contracts` is a placeholder for future shared OpenAPI, protobuf, generated client, fixture, and compatibility assets.
+- Active planning lives under `agent-ops/roadmap/`; this README links to that context instead of duplicating milestone state.
 
-```sh
-bin/test
-bin/build
-bin/lint
+## Quick Start
+
+Install only the runtimes needed for the part of the workspace you are using.
+
+```bash
+# Show service/app dev entrypoints.
 bin/dev
+
+# Run workspace checks for installed toolchains.
+bin/test
+bin/lint
+bin/build
 ```
 
-Each command delegates to the projects that are present in the workspace.
+Run the core service locally. The scripts provide local defaults, but they still expect reachable PostgreSQL and Redis services; see `services/core/README.md` for the current `code-server` database setup notes.
+
+```bash
+cd services/core
+./bin/migrate-up
+./bin/run
+```
+
+Run the web console:
+
+```bash
+cd apps/web
+npm install
+npm run dev
+```
+
+Run the Flutter app:
+
+```sh
+cd apps/mobile
+flutter pub get
+flutter run
+```
+
+## Major Commands
+
+| Purpose | Command | Notes |
+|------|------|------|
+| Show local dev entrypoints | `bin/dev` | Prints core, web, and mobile commands. |
+| Test workspace | `bin/test` | Runs `go test ./...`, web `npm run check` or tests if present, and `flutter test`; skips missing toolchains. |
+| Lint workspace | `bin/lint` | Runs `go vet ./...`, web `npm run lint --if-present`, and `flutter analyze --no-fatal-infos`; skips missing toolchains. |
+| Build workspace | `bin/build` | Runs core `go build ./...`, web `npm run build`, and `flutter build web`; skips missing toolchains. |
+| Run core | `cd services/core && ./bin/run` | Uses local defaults from the core script unless environment variables override them. |
+| Migrate core DB | `cd services/core && ./bin/migrate-up` | Uses goose against the configured PostgreSQL database. |
+| Test core | `cd services/core && ./bin/test` | Thin wrapper around `go test ./...`. |
+| Build core binary | `cd services/core && ./bin/build` | Outputs to `.build/nomadcode-core` unless `OUTPUT` is set. |
+| Run web dev server | `cd apps/web && npm run dev` | Vite development server. |
+| Check web types | `cd apps/web && npm run check` | TypeScript `--noEmit`. |
+| Verify web | `cd apps/web && npm run verify` | Runs type check and production build. |
+| Run mobile tests | `cd apps/mobile && flutter test` | Flutter test suite. |
+
+## Structure
+
+| Path | Role |
+|------|------|
+| `services/core/` | Go backend for orchestration, persistence, scheduling, HTTP APIs, and external service adapters. |
+| `apps/web/` | React/Vite operator console and browser-based agent/project workspace UI. |
+| `apps/mobile/` | Flutter mobile/desktop client and notification integration surface. |
+| `packages/contracts/` | Future shared API/schema contracts and generated client boundary. |
+| `docs/` | Architecture and operations notes. |
+| `bin/` | Root test, lint, build, and dev helper commands. |
+| `agent-ops/` | Agent rules, domain routing, roadmap, and repeatable task skills. |
+
+## Work Context
+
+AI agents should start with the root instructions and project rules before changing files:
+
+- `AGENTS.md`
+- `agent-ops/rules/project/rules.md`
+- `agent-ops/rules/private/rules.md` when present
+
+For workspace-level files such as this README, also check:
+
+- `agent-ops/rules/project/domain/workspace-ops/rules.md`
+- `agent-ops/skills/common/create-readme/SKILL.md`
+- `agent-ops/roadmap/current.md`
+
+Keep detailed roadmap state in `agent-ops/roadmap/` and detailed domain rules in `agent-ops/rules/project/domain/`. Do not read `agent-task/archive/**` unless the user explicitly asks for it.
+
+## Development Flow
+
+- Prefer the root `bin/test`, `bin/lint`, `bin/build`, and `bin/dev` entrypoints for whole-workspace work.
+- Keep changes scoped to the owning domain rules. Cross-boundary changes should close the contract, service, and client behavior in the same branch when those boundaries move together.
+- For core database changes, update `services/core/migrations/` and `services/core/queries/`, then regenerate sqlc output instead of hand-editing generated files under `services/core/internal/db/`.
+- Keep `agent-ops/rules/common/**` and `agent-ops/skills/common/**` as framework-synced areas; put project-specific rules under `agent-ops/rules/project/**`.
+
+## Environment Variables
+
+| Runtime | Name | Required | Notes |
+|------|------|------|------|
+| Core | `DATABASE_URL` | No, with scripts | Core scripts provide local defaults; set it when running the binary directly or using a different PostgreSQL database. |
+| Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | No, with scripts | Core scripts provide local defaults for worker/queue state; set them when running outside those scripts. |
+| Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | No | `AUTH_PASSWORD` enables HTTP Basic Auth for `/readyz` and `/api/*`. |
+| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | No | Configure the OpenAI-compatible model endpoint used by worker execution. |
+| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the A2A-compatible agent call path. |
+| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | No | Reserved for Mattermost adapter integration. |
+| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | No | Reserved for Plane adapter integration. |
+| Web | `VITE_NOMADCODE_API_BASE_URL` | No | The web client falls back to `http://localhost:8080`; `apps/web/.env.example` documents the same local value. |
+
+## Reference Documents
+
+- `docs/monorepo.md`
+- `services/core/README.md`
+- `apps/web/README.md`
+- `apps/mobile/README.md`
+- `packages/contracts/README.md`
+- `agent-ops/roadmap/current.md`
diff --git a/agent-ops/roadmap/milestones/workflow-core.md b/agent-ops/roadmap/milestones/workflow-core.md
index 1ab1e55..fb429c1 100644
--- a/agent-ops/roadmap/milestones/workflow-core.md
+++ b/agent-ops/roadmap/milestones/workflow-core.md
@@ -49,3 +49,4 @@ Workflow Core
 - 선행 작업: Plane Thin E2E Loop
 - 후속 작업: External Integration
 - 검증 기준: scheduler, persistence, adapter behavior를 크게 바꾸면 관련 테스트를 함께 갱신한다.
+벼
\ No newline at end of file