# Agent guide

MPV Manager is a Go application for installing and managing mpv, with a Web UI,
Bubble Tea TUI, and CLI. Start with [README.md](README.md) and
[architecture](docs/ARCHITECTURE.md). This file contains durable working rules;
Atlas holds task status and handoffs, and dated reports preserve audit evidence.

## Tracking and scope

- Use `atlas brief`, `atlas task`, and `atlas heartbeat` throughout work. Check
  `atlas help` for syntax. Record implementation evidence and remaining gates.
- Never hand-edit [TRACKING.md](TRACKING.md); Atlas generates it.
- Follow the user's authorization for changes and commits. Publishing, pushing,
  or calling a release ready requires the corresponding authorization and gates.
- Keep review findings distinguishable from verified fixes. Do not mark native
  or external release tasks complete based only on cross-compilation or mocks.

## Toolchain and validation

Go 1.27.0+, Make, and Node.js 22.12+ on a supported Node major are required;
`go.mod` and `package.json` are authoritative. Use the lockfile with `npm ci`.

```sh
go test ./...
go test -race ./...
make lint
npm test
make frontend-vendor-check
make build
```

Run relevant focused checks while editing; use full checks for broad changes.
`make lint` includes vet and pinned Staticcheck correctness checks. See
[testing](docs/TESTING.md), [build/deployment](docs/BUILD_DEPLOYMENT.md), and
[CI](docs/GITLAB_CI.md) for release checks and cross-builds.

The release matrix includes Windows amd64 (x86-64-v2) and arm64, Linux amd64 and
arm64, and macOS (separate arm64 and x86_64 executables), macOS 13+.
Native behavior must be tested on the actual OS in disposable installations.
Never reuse a user's real app/config directories for destructive QA.
The owner has dedicated the `agent` account on the `win-dev` Windows VM to agent
use; use that account for desktop QA. Keep config snapshots and test evidence
needed to verify preservation and recovery.

## Code boundaries

- `cmd/mpv-manager`: CLI, Web/TUI startup, shutdown and update handoff.
- `pkg/installer`: staging, validation, platform commands and durable replacement.
- `pkg/version` and `pkg/releasemanifest`: signed release checks and updater trust.
- `pkg/config`, `internal/mpvconf`, `internal/scriptopts`: persistent settings and
  shared editors. Preserve profiles, comments, permissions and concurrent edits.
- `pkg/web`: HTTP auth, jobs, resource leases and SSE. `pkg/tui`: terminal state.
- `internal/process`: bounded command execution and owned subprocess trees.
- `internal/packagequery`: localized, bounded package discovery/version probes.
- `internal/fileops`: atomic writes and process/cross-process file coordination.
- `internal/webassets`: embedded templates, behavior, fonts and vendor assets.
- `pkg/constants`: shared identifiers and paths; do not duplicate method tables.

Prefer existing boundaries over new forwarding wrappers or speculative seams.
Test shipped behavior and failure outcomes. Platform-specific filenames must
match their build intent: `windows.go` compiles everywhere; `*_windows.go` does
not. Format Go edits with gofmt and retain meaningful exported API comments.

## Mutation and recovery rules

Stage/download before the commit guard. Once destructive work begins, workers
own it through terminal results; shutdown/navigation must drain them. Use
resource leases, file locks, durable journals and explicit ownership inventories.
Do not delete ambiguous recovery evidence or execute an untrusted old backup.
The updater journal authentication key must remain private and available through
recovery. Signing/provenance services and native permission gates remain separate
from repository tests; see [CI](docs/GITLAB_CI.md).

## Frontend conventions

Use Go templates + htmx partial swaps + Alpine components for stateful UI. Keep
runtime assets embedded and offline. Exact Alpine/htmx versions and integrity
live in npm manifests; `make frontend` syncs vendors and builds Tailwind. Commit
fresh `internal/webassets/static/css/tailwind.min.css` after relevant template or
class changes. See [frontend dependencies](docs/FRONTEND_DEPENDENCIES.md).

Alpine automatically calls `init()` and `destroy()`: do not add `x-init="init()"`.
Destroy handlers must remove listeners/timers and abort pending requests. Export
component factories for Vitest; use real-browser integration for framework,
htmx, SSE and navigation behavior. Do not substitute factory mocks for that gate.

Reuse `MPVUtils.apiFetch`, `MPVDialog` (focus/inert and `hidden` toggling),
`showToast`, and `MPVRocksModal`. Keep request cancellation and bounded output
retention intact. CSP disallows inline scripts/native event attributes; htmx
script execution is disabled. Keep production UI free of implementation details.

## Documentation

Update maintained feature/architecture/test docs when behavior changes. Historical
reviews remain evidence, with remediation status recorded separately. Start with
[September audit](docs/CODEBASE_AUDIT_2026-09-05.md),
[reconciliation](docs/REVIEW_RECONCILIATION_2026-09-05.md), and the
[August baseline](docs/CODEBASE_REVIEW_FINALIZED_2026-08-31.md).

<!-- ATLAS:BEGIN -->
## Atlas tracker

This project is tracked by Atlas (status: **active**). Dashboard: this host (slug `mpvrocks-mpv-manager`).

Update via the `atlas` CLI (`atlas status`, `atlas task`, `atlas heartbeat`) or the API.
TRACKING.md is generated — do not hand-edit it.
<!-- ATLAS:END -->