docs: forbid unbounded home directory searches in agent notes

[Aviator-Coding]

Intent

Add prominent rule to AGENTS.md forbidding unbounded find searches of /Users/coder and /Users/coder. Explains the concrete consequence (19-96 minute wedges), shows how to find tools properly (mise), and clarifies that cluster credentials like kubeconfig don't exist in fresh worktrees. Generalizes PR #1482's kustomize-specific patch to prevent recurrence. Documentation only, no changes to workflows or tooling.

What Changed

• Added a top-of-NOTES rule in AGENTS.md banning unbounded find of /Users/coder, $HOME, and parent paths, citing 19–96 minute validation wedges and requiring agents to report missing tools/files instead of hunting for them.
• Documented the correct resolution path: mise-managed CLIs via mise which / mise exec, plus the expectation that kubeconfig/talosconfig are absent in fresh worktrees and must not be searched for.
• Generalized the earlier kustomize-only note to point at the new rule so the same guidance covers all mise-managed tools.

Risk Assessment

✅ Low: Documentation-only AGENTS.md guidance that matches the stated intent with no workflow, tooling, or behavioral code changes.

Testing

Verified the agent-facing NOTES surface and CLAUDE.md symlink against the full intent checklist, confirmed only AGENTS.md changed, and demonstrated expected-missing cluster credentials plus the mise lookup path without home-directory find; all acceptance checks passed.

Evidence: Intent acceptance checklist (all PASS)

intent_acceptance: forbids_find_Users_coder: PASS forbids_find_HOME: PASS forbids_unbounded_home_or_parent: PASS consequence_19_96_minutes: PASS mise_which_pattern: PASS mise_install_path: PASS kubeconfig_absent_expected: PASS talosconfig_mentioned: PASS report_and_continue: PASS generalized_not_kustomize_only: PASS cross_ref_from_cli_bullet: PASS rule_is_first_notes_bullet: PASS overall: PASS

intent_acceptance:
  forbids_find_Users_coder: PASS
  forbids_find_HOME: PASS
  forbids_unbounded_home_or_parent: PASS
  consequence_19_96_minutes: PASS
  mise_which_pattern: PASS
  mise_install_path: PASS
  kubeconfig_absent_expected: PASS
  talosconfig_mentioned: PASS
  report_and_continue: PASS
  generalized_not_kustomize_only: PASS
  cross_ref_from_cli_bullet: PASS
  rule_is_first_notes_bullet: PASS
overall: PASS

first_notes_bullet:
- **NEVER run `find /Users/coder`, `find $HOME`, or any unbounded search of the home directory or parent paths.** Validation agents wedge for 19-96 minutes on these searches because the home directory contains hundreds of cached clones and tool installations. When a tool or file is not found, report it and continue - do not hunt for it. The correct pattern: (1) Tools are mise-managed, resolved with `mise which <name>` / `mise exec -- <name>` and live under `~/.local/share/mise/`. (2) Cluster credentials (`kubeconfig`, `talosconfig`) do not exist in fresh worktrees and their absence is **expected and normal** - a pipeline sandbox has no cluster access. If code needs them, it should report the missing file and skip, not search for one. (3) If a tool is not mise-installed, report it explicitly rather than trying to locate it.

Evidence: Agent-facing NOTES opening with new first bullet

## NOTES

- **NEVER run `find /Users/coder`, `find $HOME`, or any unbounded search of the home directory or parent paths.** Validation agents wedge for 19-96 minutes on these searches because the home directory contains hundreds of cached clones and tool installations. When a tool or file is not found, report it and continue - do not hunt for it. The correct pattern: (1) Tools are mise-managed, resolved with `mise which <name>` / `mise exec -- <name>` and live under `~/.local/share/mise/`. (2) Cluster credentials (`kubeconfig`, `talosconfig`) do not exist in fresh worktrees and their absence is **expected and normal** - a pipeline sandbox has no cluster access. If code needs them, it should report the missing file and skip, not search for one. (3) If a tool is not mise-installed, report it explicitly rather than trying to locate it.

- **`kubernetes/clusters/main/` is the only Flux entry point.** The flux-instance HelmRelease's `values.instance.sync.path` (`kubernetes/apps/base/flux-system/flux-instance/app/helmrelease.yaml` - there is no separate `FluxInstance` CR manifest in this repo) points at `kubernetes/clusters/main`. `cluster-apps.spec.path` is `kubernetes/apps/main`; `cluster-meta.spec.path` is `kubernetes/apps/base/flux-system/meta`. Every namespace lives at `kubernetes/apps/base/<ns>/` (resources) plus overlay `kubernetes/apps/main/<ns>/` (Flux `Kustomization` CRs, one yaml per former `ks.yaml`; `default` is overlay-only scaffolding). A brand-new top-level namespace goes on `kubernetes/apps/main/kustomization.yaml` only.

- **A namespace-scoped manifest test still cannot prove a namespace is healthy - the reason changed with flate, the trap did not.** Under flux-local, `test --namespace X` never traversed into `apps/main/<ns>` at all. flate *does* always reconcile the whole tree from `--path` (there is no partial-reconcile mode), but `-n/--namespace` filters the **result and the exit code**, not just the printed lines. Measured 2026-08-29 on this repo: with a broken Kustomization in `network`, `flate test all -n monitoring` exits **0** and prints `38 passed`, while the same run unscoped exits 1. So the false green survived the migration. `task flux:test:ns` therefore runs twice - the scoped run for readable output, then an unscoped run as the authoritative gate - and `task flux:test:all` remains the plain full check; both point at the same `kubernetes/clusters/main` path as `.github/workflows/flate.yaml`. A full run is ~0.3s warm, so prefer it. Note this is a *separate* gap from the `postBuild.substitute` collision above, which a full run does not catch either.

- **`.github/workflows/validate.yaml` is the only CI signal for `talos/`, `bootstrap/`, and `.renovate/`.** Everything else (`flate`, `image-pull`) filters on `kubernetes/**` and never sees them; before it existed a `talos/`-only PR ran exactly one check, the labeler. Six path-filtered jobs on the local ARC runner: shell gates under `scripts/ci/*.sh`, plus `python-tests` which globs `scripts/ci/*-test.py` (inventory and local run notes: `scripts/ci/README.md`). Its `talosctl validate` gate is a **schema** check only: it catches render breakage and unknown machine-config keys, but **not** invalid enums, bad CIDRs, or a missing install disk - all three were tested and pass validation. Green there is not permission to `apply-node`. Per-job scope and triggers are stated in the workflow header; the `bootstrap` job covers `bootstrap/kustomize/` only, because `bootstrap/helmfile/` needs vals + 1Password to render. `terraform/` still gets validate.yaml's credential-less schema job, but live read-only plans and OCI publish live in `terraform-diff.yaml` / `terraform-publish.yaml` - see the `terraform/` NOTES entry below.
- **A red `validate.yaml` check that passes on rerun is runner-pool contention, not a validation bug - and raising `maxRunners` is the wrong first move.** Editing the workflow file matches every per-job path filter, so the whole validate set (plus Labeler on the same scale set) can launch at once on `gha-runner-scale-set-aviator-coding-home-ops`. Measured 2026-08-29 on PR #1481: that was cluster CPU/network/disk under load, not a slot wait (`maxRunners: 15` was not the ceiling). Do not drop `.github/workflows/validate.yaml` from the per-job filters (that skips self-test of a workflow edit) and do not job-concurrency-serialize the whole set (GitHub counts concurrency wait toward `timeout-minutes`, which recreates the same cancel under queue). Measured durations, timeout floors, and the `python-tests` `needs:` ordering that keeps heavy `litellm[proxy]` pip off the lighter jobs' `mise-action` Setup Tools live in the `.github/workflows/validate.yaml` header (pinned by `scripts/ci/validate-contention-test.py`).

- `talos/*.j2` changes are not applied by Flux. `machineconfig.yaml.j2` / node overlays: render, `--dry-run`, then `just talos apply-node` per node. `schematic.yaml.j2` (kernel args + extensions) needs `just talos upgrade-node` - `apply-node` only restages the install image reference and does not boot it. Offline validation and the apply vs upgrade distinction: `talos/AGENTS.md`.

Evidence: Fresh worktree credentials absent + mise path (no home find)

absent (expected): kubeconfig absent (expected): talos/talosconfig

# Doc says: tools via mise which / mise exec, not find $HOME
# Demonstrating the recommended pattern (not unbounded find):
mise which kustomize -> mise ERROR error parsing config file: ~/.no-mistakes/worktrees/07f90326a876/01M171G6PQBD0AQCK3GZCM6ZD1/.mise.toml
mise ERROR Config files in ~/.no-mistakes/worktrees/07f90326a876/01M171G6PQBD0AQCK3GZCM6ZD1/.mise.toml are not trusted.
Trust them with `mise trust`. See https://mise.jdx.dev/cli/trust.html for more information.
mise ERROR Version: 2026.8.10 macos-arm64 (2026-08-20)
mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information
(not installed in this sandbox — report and continue, per rule)
mise which kubectl -> mise ERROR error parsing config file: ~/.no-mistakes/worktrees/07f90326a876/01M171G6PQBD0AQCK3GZCM6ZD1/.mise.toml
mise ERROR Config files in ~/.no-mistakes/worktrees/07f90326a876/01M171G6PQBD0AQCK3GZCM6ZD1/.mise.toml are not trusted.
Trust them with `mise trust`. See https://mise.jdx.dev/cli/trust.html for more information.
mise ERROR Version: 2026.8.10 macos-arm64 (2026-08-20)
mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information
(not installed in this sandbox — report and continue, per rule)
mise which helm -> mise ERROR error parsing config file: ~/.no-mistakes/worktrees/07f90326a876/01M171G6PQBD0AQCK3GZCM6ZD1/.mise.toml
mise ERROR Config files in ~/.no-mistakes/worktrees/07f90326a876/01M171G6PQBD0AQCK3GZCM6ZD1/.mise.toml are not trusted.
Trust them with `mise trust`. See https://mise.jdx.dev/cli/trust.html for more information.
mise ERROR Version: 2026.8.10 macos-arm64 (2026-08-20)
mise ERROR Run with --verbose or MISE_VERBOSE=1 for more information
(not installed in this sandbox — report and continue, per rule)

# Cluster credentials expected missing in fresh worktree:
absent (expected): kubeconfig
absent (expected): talos/talosconfig

Evidence: CLAUDE.md symlink surfaces identical rule

CLAUDE.md -> AGENTS.md identical_bytes: true

CLAUDE.md -> AGENTS.md
---
SHA256 AGENTS.md:  a5f374c408d87fce609e669bf0a149b22ada6fc2887edb5868fa7f745a932eaa
SHA256 CLAUDE.md:  a5f374c408d87fce609e669bf0a149b22ada6fc2887edb5868fa7f745a932eaa
identical_bytes: true
---
Rule visible through CLAUDE.md:
## NOTES

- **NEVER run `find /Users/coder`, `find $HOME`, or any unbounded search of the home directory or parent paths.** Validation agents wedge for 19-96 minutes on these searches because the home directory contains hundreds of cached clones and tool installations. When a tool or file is not found, report it and continue - do not hunt for it. The correct pattern: (1) Tools are mise-managed, resolved with `mise which <name>` / `mise exec -- <name>` and live under `~/.local/share/mise/`. (2) Cluster credentials (`kubeconfig`, `talosconfig`) do not exist in fresh worktrees and their absence is **expected and normal** - a pipeline sandbox has no cluster access. If code needs them, it should report the missing file and skip, not search for one. (3) If a tool is not mise-installed, report it explicitly rather than trying to locate it.

Evidence: Full acceptance summary

USER INTENT ACCEPTANCE EVIDENCE
================================
Change: docs-only AGENTS.md (generalize PR #1482 kustomize-specific find ban)
Files changed vs base: AGENTS.md 
Workflows/tooling touched: none

intent_acceptance:
  forbids_find_Users_coder: PASS
  forbids_find_HOME: PASS
  forbids_unbounded_home_or_parent: PASS
  consequence_19_96_minutes: PASS
  mise_which_pattern: PASS
  mise_install_path: PASS
  kubeconfig_absent_expected: PASS
  talosconfig_mentioned: PASS
  report_and_continue: PASS
  generalized_not_kustomize_only: PASS
  cross_ref_from_cli_bullet: PASS
  rule_is_first_notes_bullet: PASS
overall: PASS

first_notes_bullet:
- **NEVER run `find /Users/coder`, `find $HOME`, or any unbounded search of the home directory or parent paths.** Validation agents wedge for 19-96 minutes on these searches because the home directory contains hundreds of cached clones and tool installations. When a tool or file is not found, report it and continue - do not hunt for it. The correct pattern: (1) Tools are mise-managed, resolved with `mise which <name>` / `mise exec -- <name>` and live under `~/.local/share/mise/`. (2) Cluster credentials (`kubeconfig`, `talosconfig`) do not exist in fresh worktrees and their absence is **expected and normal** - a pipeline sandbox has no cluster access. If code needs them, it should report the missing file and skip, not search for one. (3) If a tool is not mise-installed, report it explicitly rather than trying to locate it.


Credential absence (fresh worktree):
absent (expected): kubeconfig
absent (expected): talos/talosconfig

gitignore:
.gitignore:16:kubeconfig	kubeconfig
.gitignore:17:talosconfig	talos/talosconfig

CLAUDE.md symlink:
CLAUDE.md -> AGENTS.md
---
SHA256 AGENTS.md:  a5f374c408d87fce609e669bf0a149b22ada6fc2887edb5868fa7f745a932eaa
SHA256 CLAUDE.md:  a5f374c408d87fce609e669bf0a149b22ada6fc2887edb5868fa7f745a932eaa
identical_bytes: true

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• git diff --name-only acfcde3592f00e26a570e678e8dd84325eebeb58..HEAD (docs-only: AGENTS.md)
• intent acceptance checklist over AGENTS.md NOTES (12 required constraints)
• readlink/shasum CLAUDE.md symlink identity with AGENTS.md
• fresh-worktree credential absence check for kubeconfig and talos/talosconfig
• git check-ignore -v kubeconfig talos/talosconfig
• doc-recommended tool lookup via mise which without unbounded find $HOME

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.