diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3f491cd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,179 @@
+# AGENTS.md
+
+This file constrains future work in this repository. Follow it for all non-trivial changes.
+
+## Repository Snapshot
+
+- Root purpose: `managed-portal` is a standalone management portal for managed services and web devices.
+- Backend: Go service under `cmd/managed-portal` and `internal/`.
+- Frontend: Vue 3 + Vite + Element Plus app under `web/`.
+- Managed child services: Python projects under `managed/people_flow_project/` and `managed/store_dwell_alert/`.
+- Deployment assets: `deploy/`, root `Dockerfile`, `managed_services.yaml`.
+- Primary default ports from the current README: backend `9080`, frontend `13000`, child service APIs `18081` and `18082`.
+- Operating environment: this repository is intended for use in mainland China, so future changes must account for China-network constraints and domestic deployment realities.
+
+## Repository Map
+
+- `cmd/managed-portal/`: Go backend entrypoint.
+- `internal/config/`: backend configuration loading.
+- `internal/managed/`: managed service registry, runtime, remote client, orchestration logic.
+- `internal/server/`: HTTP server and handlers.
+- `internal/webdevice/`: web device proxying, rewriting, and related service logic.
+- `web/src/`: frontend app, router, API client, and views.
+- `managed/people_flow_project/`: Python people-flow service with `src/`, `tests/`, deployment scripts, and weights.
+- `managed/store_dwell_alert/`: Python store-dwell-alert service with `app/`, `tests/`, deployment scripts, and weights.
+- `deploy/`: Docker Compose deployment files and env files.
+- `docs/`: rollout and integration documentation.
+- `tasks/`: task plan, review evidence, and lessons learned.
+
+## Workflow Orchestration
+
+### 1) Plan Node Default
+
+- For any non-trivial task, enter plan mode before implementation.
+- Treat a task as non-trivial if any of the following is true:
+  - it needs 3 or more steps;
+  - it involves architecture, sequencing, or cross-file decisions;
+  - it requires a verification chain, not just a code edit.
+- Write the specification, scope, risks, and validation approach before making substantive changes.
+- If execution drifts, gets blocked, or a core assumption fails, stop and re-plan instead of forcing the current path.
+- Validation steps are part of the plan and are never optional.
+
+### 2) Subagent Strategy
+
+- Prefer subagents for exploration, repository search, investigation, and parallel analysis.
+- Keep one subagent focused on one clear tactical question.
+- For complex tasks, split exploration into parallel subproblems to protect the main context window.
+- Keep the main agent focused on decisions, edits, and verification.
+
+### 3) Self-Improvement Loop
+
+- At the start of a non-trivial task, quickly review `tasks/lessons.md` for rules relevant to the current work.
+- Any user correction must update `tasks/lessons.md`.
+- Record corrections in `trigger -> rule -> preventive action` form.
+- Use recorded lessons to prevent repeating the same process or decision error.
+
+### 4) Verification Before Done
+
+- Do not mark work complete without verification evidence.
+- When applicable, compare before and after behavior, not just changed files.
+- Run the narrowest meaningful validation first, then widen only if needed.
+- Report executable evidence such as tests, builds, lint, config checks, or log output.
+- Ask whether the result meets a staff-engineer standard before closing the task.
+
+### 5) Demand Elegance (Balanced)
+
+- Before a non-trivial change, ask whether a simpler, more robust design is available.
+- Replace obviously hacky solutions with the best reasonable implementation supported by current information.
+- Do not over-design straightforward fixes.
+
+### 6) Autonomous Bug Fixing
+
+- Treat bug reports as requests to diagnose and fix, not as prompts for the user to drive every step.
+- Use logs, failing behavior, and targeted tests to find the root cause.
+- Close the loop with a fix plus validation inside task scope.
+- When CI-like failures are in scope, investigate and repair them autonomously.
+
+## Task Management
+
+### 1) Plan First
+
+- Before substantive implementation on a non-trivial task, create or update `tasks/todo.md`.
+- The plan must use checkboxes and include scope, risks, and validation intent.
+
+### 2) Verify Plan
+
+- Confirm the plan covers the user request, repository-specific risks, and the expected verification path before coding.
+
+### 3) Track Progress
+
+- Update `tasks/todo.md` as tasks are completed.
+- Keep plan state accurate enough that another engineer could resume from it.
+
+### 4) Explain Changes
+
+- For each major step, provide a high-level explanation of what changed and why.
+
+### 5) Document Results
+
+- `tasks/todo.md` must contain a `Review` section with result and verification evidence.
+
+### 6) Capture Lessons
+
+- If the user corrected the process, assumptions, or implementation direction, update `tasks/lessons.md` before closing the task.
+
+## Core Principles
+
+- Simplicity First: prefer the smallest change that fully solves the problem.
+- No Laziness: find the real cause and avoid cosmetic patches.
+- Minimal Impact: limit edits to the necessary surface and reduce regression risk.
+
+## China Mainland Environment Constraints
+
+- Assume the software will run in mainland China networks by default.
+- Prefer China-accessible defaults for package mirrors, container registries, and third-party endpoints when code or documentation needs a default choice.
+- Do not hard-code dependencies on services that are commonly inaccessible or unstable from mainland China unless there is an explicit fallback or configurability.
+- When adding build, install, or deployment steps, consider whether Go, Node, Python, Docker, and model-download paths need domestic mirror support.
+- When integrating external APIs, downloads, or web assets, make network reachability, timeout behavior, and fallback strategy explicit.
+- Keep region-specific choices configurable so the repo can still run elsewhere, but mainland China should be the default assumption.
+
+## Repo-Specific Change Rules
+
+### Backend Go Rules
+
+- Backend entry code belongs in `cmd/managed-portal/`; business logic belongs in `internal/`.
+- Keep configuration behavior coherent across `internal/config/`, `deploy/`, and the README when ports, env vars, or service addresses change.
+- When editing service management logic, check adjacent tests in `internal/managed/`, `internal/server/`, and `internal/webdevice/`.
+- Prefer focused package tests before full-repo Go tests.
+
+### Frontend Rules
+
+- Frontend changes belong under `web/src/` and should respect the current Vite + Vue 3 structure.
+- When changing routes, views, or API calls, verify the corresponding backend endpoints or proxy paths still match.
+- Prefer minimal UI changes consistent with the existing portal instead of introducing a new design language.
+
+### Managed Python Service Rules
+
+- Treat `managed/people_flow_project/` and `managed/store_dwell_alert/` as embedded but separately testable projects.
+- Keep edits contained to the relevant child service unless a shared contract change requires broader updates.
+- Preserve deployment/runtime assumptions in each child project's scripts, configs, and tests.
+- Be careful with large model weights and local config files; do not assume ignored assets exist in source control.
+
+### Deployment And Operations Rules
+
+- For changes touching `deploy/docker-compose.yml`, env files, root `Dockerfile`, or child-service Docker assets, verify configuration consistency.
+- For registry or service-address changes, keep `managed_services.yaml`, deployment files, and README examples aligned.
+- Do not bulk-sync from external directories into this repo without a diff plan, overwrite-risk check, and rollback path.
+- For dependency installation, image builds, or artifact downloads, prefer defaults that are reliable from mainland China or document the required mirror configuration.
+
+## Validation Matrix
+
+- Go backend changes:
+  - Prefer targeted `go test` commands for touched packages.
+  - Use `go test ./...` when the change spans multiple backend packages or contracts.
+- Frontend changes:
+  - Prefer `pnpm build` in `web/` for structural verification.
+  - Use narrower checks when available, but do not skip build validation for meaningful UI or routing changes.
+- Python child service changes:
+  - Prefer targeted test files under each project's `tests/` directory.
+  - Expand to broader test runs only when the change crosses module boundaries.
+- Deployment/configuration changes:
+  - Validate with the narrowest config check available, such as compose config rendering or related test coverage.
+- Documentation-only changes:
+  - Verify file presence, required sections, and consistency with the current repository structure.
+
+## Required Artifacts For Non-Trivial Tasks
+
+- `tasks/todo.md`: current checklist, scope, risks, and review evidence.
+- `tasks/lessons.md`: updated whenever the user corrects the workflow or technical direction.
+- Final response: concise summary, what was verified, and any residual risk or natural next step.
+
+## Definition Of Done
+
+Do not close a non-trivial task until all of the following are true:
+
+1. The request is fully covered.
+2. Plan items in `tasks/todo.md` are updated.
+3. Key verification has run and is reproducible.
+4. `tasks/todo.md` includes a completed `Review` section.
+5. `tasks/lessons.md` was updated for any user correction in the task.
diff --git a/tasks/lessons.md b/tasks/lessons.md
new file mode 100644
index 0000000..2cbc1ce
--- /dev/null
+++ b/tasks/lessons.md
@@ -0,0 +1,15 @@
+# Lessons
+
+## 2026-05-12
+
+- Trigger: the user corrected the execution workflow for non-trivial tasks and required persistent task tracking.
+- Rule: for any non-trivial task, create or update `tasks/todo.md` before substantive implementation, keep progress current, and do not mark done without review evidence.
+- Preventive action: check for `tasks/todo.md`, `tasks/lessons.md`, and repository guidance files before editing code; if the user corrects process expectations, record the rule immediately.
+
+- Trigger: the user required corrections to be persisted for future sessions.
+- Rule: any user correction must be recorded in `tasks/lessons.md` as `trigger -> rule -> preventive action`.
+- Preventive action: after any correction, update lessons before closing the task and mention the recorded rule in the final verification summary.
+
+- Trigger: the user clarified that this repository is meant to run in mainland China environments.
+- Rule: future code, build, deployment, and integration changes must consider mainland China network accessibility and should prefer China-friendly defaults where practical.
+- Preventive action: when adding dependencies, mirrors, external endpoints, or download flows, explicitly check whether the default path works reliably in mainland China and add configuration or fallback when needed.
diff --git a/tasks/todo.md b/tasks/todo.md
new file mode 100644
index 0000000..8d73c18
--- /dev/null
+++ b/tasks/todo.md
@@ -0,0 +1,25 @@
+# Task Plan
+
+## Checklist
+
+- [x] Clarify scope, repository boundaries, and validation requirements for a repository-level AGENTS.md.
+- [x] Verify that the plan covers the user-specified workflow rules, project structure, and risk points.
+- [x] Create a complete AGENTS.md that embeds the requested workflow orchestration rules and repo-specific guardrails.
+- [x] Verify the generated AGENTS.md against the current repository structure and required workflow sections.
+- [x] Update the Review section with the final result and verification evidence.
+
+## Scope And Risks
+
+- Scope: add a repository-root AGENTS.md that governs future modifications across the Go backend, Vue frontend, deployment assets, and embedded Python managed services.
+- Risk: omit a repository area or validation command and leave future work under-constrained.
+- Risk: copy the requested workflow rules without adapting them to this repo's actual layout and toolchain.
+- Risk: finish without writing persistent task evidence for plan, review, and lessons.
+
+## Review
+
+- Status: completed.
+- Result: added a repository-root `AGENTS.md` plus `tasks/todo.md` and `tasks/lessons.md` to enforce the requested workflow for future non-trivial tasks.
+- Verification:
+  - confirmed `AGENTS.md` exists at the repository root;
+  - read back `AGENTS.md` and verified it covers workflow orchestration, task management, repo structure, validation matrix, and definition of done;
+  - matched required repository-specific references including `internal/webdevice/`, `managed/people_flow_project/`, `managed/store_dwell_alert/`, `tasks/todo.md`, and `tasks/lessons.md`.