# 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.