# Agent Guidelines for XControl

## Repository scope
These instructions apply to the entire repository. Create a more specific `AGENTS.md`
inside a subdirectory only when you need to override or augment the guidance below for
that subtree.

## Project overview
XControl is a polyglot monorepo that ships:
- Multiple Go services (API server, account service, RAG server, supporting CLIs) under
the top-level Go module `xcontrol`.
- A Next.js dashboard (`dashboard/`) implemented in TypeScript with Tailwind CSS and
Vitest/Playwright tests.
- CMS configuration, SQL migrations, deployment manifests, and documentation that are
consumed by the services and UI.

## General expectations
- Match the existing language of the file (English vs. Chinese or bilingual) and retain
the bilingual structure when you touch documentation that already mixes both.
- Prefer structured logging (`log/slog`) or existing helper utilities over raw
`fmt.Println` in Go code.
- Keep configuration files and generated assets deterministic. If you edit files under
`config/`, `docs/cms/`, or `scripts/`, mention any required regeneration steps in your
commit message or PR description.

## Go code (all directories except `dashboard/`)
- Format Go code with `gofmt` (or `go fmt ./...`) before committing.
- Organize imports using `goimports` if available; otherwise maintain the existing
standard library / third-party separation.
- Run `go test ./...` from the repository root (or a narrower package path) after
changing Go files. Use `make test` in submodules such as `rag-server/` when you need the
module-specific workflow.
- Keep configuration structs in sync with their YAML/JSON sources and update default
values when you add new fields.

## TypeScript / Next.js dashboard (`dashboard/`)
- Use `yarn` (not `npm` or `pnpm`). Install dependencies with `yarn install` and run
scripts with `yarn --cwd dashboard <script>`.
- Format code with the existing ESLint rules by running `yarn --cwd dashboard lint
--fix` when possible. Follow the 2-space indentation style and single-quote string
literals you see in the current codebase.
- Run `yarn --cwd dashboard lint` and the relevant tests (`yarn --cwd dashboard test`
and/or `yarn --cwd dashboard test:e2e`) when you touch dashboard code.
- Avoid introducing runtime-only environment variables; prefer adding entries to
`dashboard/config/runtime-service-config.yaml` so that environments stay declarative.

## Documentation and Markdown (`docs/`, `README.md`, etc.)
- Wrap prose at a reasonable width (~100 characters) and preserve existing heading
hierarchies.
- When documenting commands or configuration, prefer fenced code blocks with explicit
language identifiers (e.g., `bash`, `go`, `json`).
- Update cross-references if you rename or relocate files that are linked in the docs.

## Database and migrations
- For schema changes, update both the SQL migration under the relevant `sql/` directory
and any Go structs/DTOs that map to the same tables.
- Provide idempotent migration steps where possible and document required manual steps
in the accompanying README or commit message.

## Testing summary
Before shipping changes, run the narrowest applicable subset of these commands:
- `go test ./...` (Go services)
- `yarn --cwd dashboard lint`
- `yarn --cwd dashboard test`
- `yarn --cwd dashboard test:e2e` (when you modify Playwright specs or end-to-end flows)