# Dev Feature Profiles

## Problem

`./dev --server` is the single local development entrypoint, but optional development capabilities have been controlled by ad-hoc knobs:

- `MESHX=ENABLE` controls MeshX backend startup and the web build-time `__MESHX_BUILD_ENABLED__` define.
- Earlier local workflows used a separate `make dev-search` entrypoint to bootstrap a TiDB Ultra / TiFlash runtime for message search readiness.

Those knobs split the developer workflow across multiple entrypoints and make it unclear which environment variables are product/runtime flags versus local development profile selectors.

## Goals

- Keep `./dev --server` as the only local dev startup entrypoint.
- Use one local-dev feature selector for optional capabilities: `AGENTTEAM_DEV_FEATURES`.
- Replace `MESHX=ENABLE` completely; no compatibility alias is retained.
- Integrate FTS/TiDB Ultra bootstrap into the existing `cmd/agentteam-dev` helper instead of adding `cmd/agentteam-dev-search`.
- Keep message-search readiness operations in the main module admin command, not in the shared `cmd/agentteam-dev` command.

## User Interface

```bash
./dev --server                        # core AgentTeam dev
AGENTTEAM_DEV_FEATURES=MESHX ./dev --server       # core + MeshX
AGENTTEAM_DEV_FEATURES=FTS ./dev --server         # core + FTS / TiDB Ultra
AGENTTEAM_DEV_FEATURES=MESHX,FTS ./dev --server  # core + MeshX + FTS / TiDB Ultra
```

`AGENTTEAM_DEV_FEATURES` is parsed case-insensitively and accepts comma or whitespace separated tokens. Unknown features are fatal so typos do not silently fall back to a smaller runtime.

Supported features:

- `MESHX`: enables the profile-owned MeshX runtime in `agentteam-server`, ensures MeshX databases, starts the
  Docker-backed MeshX server-managed automation runner for shell-only Automation
  jobs, watches `meshx/` Go changes, and enables the web MeshX build define.
  The dev helper defaults `MESHX_AUTOMATION_DOCKER_IMAGES` to the public
  `ubuntu-latest=ubuntu:24.04` image mapping when the variable is unset, and
  preserves explicit overrides. The local Docker daemon must be available for
  the server-managed runner to advertise labels and claim jobs; if the daemon is
  unreachable, AgentTeam still starts without a host-shell fallback and leaves the
  server-managed runner disabled for that process.
- `FTS`: starts a search-ready local TiDB Ultra runtime with TiFlash/CSE support, runs schema initialization, and ensures workspace-global message-search readiness.

## Architecture

The `cmd/agentteam-dev` command owns local process and dependency orchestration. It parses `AGENTTEAM_DEV_FEATURES` into a `devOptions` value during command startup and passes that value explicitly into dependency preparation, service startup, web startup, and file watching.

The FTS runtime bootstrap lives in `cmd/agentteam-dev/ultra_runtime.go` because it is a local-development dependency concern. It uses worktree-local state under `.data/dev/ultra/`, including a worktree-local `TIUP_HOME`, mirror metadata, lock file, PID file, and logs. It starts a `tidb-ultra` playground with TiFlash/CSE from the configured internal TiUP mirror.

Message-search readiness remains in the main module:

```bash
go run ./cmd/agentteam-tidb-admin workspace-message-search-ensure-ready
```

This keeps store/backfill/readiness business logic in the main module and lets `cmd/agentteam-dev` call it as a command boundary.

## MeshX Build Integration

`web/vite.config.ts` reads `AGENTTEAM_DEV_FEATURES` and enables `__MESHX_BUILD_ENABLED__` when the `MESHX` feature is present. It no longer reads `MESHX=ENABLE`.

The `cmd/agentteam-dev` command passes the canonical `AGENTTEAM_DEV_FEATURES` value to the Vite dev process so backend and frontend behavior come from the same feature set.

## Cleanup Semantics

`make stop-dep` stops both the normal TiDB playground and the FTS TiDB Ultra runtime. Normal and FTS runtimes use separate tags so ownership and cleanup remain explicit. Because both profiles default to the same SQL port, starting the FTS profile stops the normal local playground first.

## Non-goals

- No backward compatibility for `MESHX=ENABLE`.
- No separate `make dev-search` or `cmd/agentteam-dev-search` entrypoint.
- No production feature flag semantics; `AGENTTEAM_DEV_FEATURES` is local dev-only.