# AGENTS

This file defines predictable agent behavior for this monorepo.
Primary navigation entry: `docs/_core/README.md`.

## Sources of truth
Resolve cross-document conflicts using `docs/_core/SOURCES_OF_TRUTH.md`.

## Guardrails (hard rules)
- No secrets in git (keys, tokens, credentials, private URLs). If discovered, stop and ask.
- No new LAN exposure, port changes, or host-binding changes without an explicit plan and approval.
- No dependency or lockfile churn unless the task explicitly asks for it.
- No unrelated refactors, renames, or drive-by cleanups.
- Repo-root markdown is allowlisted. Keep only stable root control-surface files
  at repo root; dated reports, review packs, one-off specs, and bulky plans go
  to `docs/journal/`, `docs/archive/`, or `next-projects/`.
- Concurrent `Build`/`Verify` efforts must use separate worktrees. Do not run
  multiple implementation passes in one dirty worktree.
- The primary worktree is baseline-only. Do not run `Build` or `Verify` there;
  start a linked worktree first with `uv run python scripts/start_effort.py ...`
  or an equivalent linked-worktree flow.
- Finish linked implementation lanes from the primary worktree with
  `uv run python scripts/closeout_effort.py --worktree <path> ...`.
- Abandon failed linked lanes from the primary worktree with
  `uv run python scripts/abandon_effort.py --worktree <path> ...`; if journal
  deltas exist, salvage them with `--salvage-journal` before pruning.
- `Build`/`Verify` work must pass local worktree-effort preflight before repo
  writes: `uv run python scripts/worktree_effort.py preflight --stage <stage>`.
- Prefer `uv run python scripts/start_effort.py --service <service-id> ...`
  when the lane maps to a canonical service in `platform/registry/services.jsonl`.
- If a dirty worktree is holding context only while another worktree builds or
  verifies, park it locally first with `uv run python scripts/worktree_effort.py park`.
- `uv run python scripts/worktree_effort.py close --json` is metadata-only; it
  does not commit, merge, or clean up the linked lane.
- Failed experiment branches may be discarded, but `docs/journal/` records must
  first be landed on `master`; never prune a branch/worktree with unsalvaged
  journal deltas.
- Local effort metadata must stay outside repo-tracked files; `NOW.md` is
  project-level status only, not a concurrent-effort registry.
- Broad parallel docs/layer lanes are not allowed. If a docs pass would claim
  `docs`, `layer-gateway`, `layer-inference`, `layer-interface`, `layer-tools`,
  `layer-data`, `services`, or `experiments` while another implementation lane
  is active, narrow the scope first.
- **MLX control:** Ports `8100-8119` are `mlxctl`-managed and MUST use `mlxctl`
  (load/unload/assign-team/sync). Ports `8120-8139` are experimental and do not
  require `mlxctl`.
  Mutating `mlxctl` commands require local/Studio CLI parity:
  `mlxctl studio-cli-sha` then `mlxctl sync-studio-cli` when mismatched.
  Never start/stop `mlx-openai-server` directly on the Studio.
- **Studio launchd governance:** Owned Studio labels (`com.bebop.*`, `com.deploy.*`)
  must be allowlisted and policy-audited via the Studio scheduling contract.
  Unmanaged owned labels are policy violations.
- Large outputs or long copy/paste blocks must go into `SCRATCH_PAD.md` for review.
- `NOW.md` must reflect the active task; update it when the active work changes.
- `NOW.md` contains only active work + a single “NEXT UP” section. Everything else goes to `BACKLOG.md`.

## Before making changes (required)
- State the goal in 1–3 lines.
- List the exact files you intend to change.
- Select verification mode (FAST or FULL) and list the commands you will run.

## Per-layer consultation
If you touch anything inside a `layer-*` taxonomy surface, read first:
- `layer-*/README.md`

`layer-*` is taxonomy/navigation only. It is not a service boundary or the
authoritative architecture surface.

## Per-service consultation
If you touch a service (code, config, or docs), read first:
- the canonical service root from `platform/registry/services.jsonl`
- `<service-root>/AGENTS.md`
- `<service-root>/CONSTRAINTS.md`
- `<service-root>/RUNBOOK.md`
- `<service-root>/SERVICE_SPEC.md`

If touched files are below the service root, read every `AGENTS.md` on the path
from the service root to the touched directory, with the deepest applicable
file treated as the most specific guidance.

If any are missing, state that and proceed with the least risky interpretation.

## Scope control (monorepo)
- Prefer working within a single service boundary per task.
- Only change shared docs/registries when required by the change.
- If a change triggers doc obligations, follow `docs/_core/CHANGE_RULES.md`.
- Treat `platform/registry/services.jsonl` as the canonical taxonomy surface.
- Treat `layer-*` as thin navigation/index surfaces only.
- When cleaning or adding repo-root docs, preserve the root markdown allowlist
  in `DOCS_CONTRACT.md`.
- For concurrent implementation work, prefer one worktree per effort and keep
  effort scope explicit and narrow.

## Verification modes
- FAST: per-touched-service quick checks (lint/smoke/unit where they exist).
- FULL: per-touched-service runtime checks (systemd/curl/journal/bench where applicable).
  Always state which mode you used and the results. If verification was not run, say so and mark the outcome UNVERIFIED.

## Python checks
- Prefer `uv run python` for scripts and checks.
- Never run compile/test across `.venv` (exclude it explicitly).

## Output requirements (required)
After changes, report:
- Files changed
- Commands run + results
- Any skipped checks and why