# 0001: AI-native repository guidance and documentation

- Status: Accepted
- Date: 2026-08-29
- Owners: Maintainers

## Context

The plugin accumulated implementation notes, local tool state, root-level tests, and stale scripts. Important knowledge was scattered between code and temporary reports, making it difficult for a new maintainer or coding agent to identify runtime boundaries, compatibility constraints, and the correct validation commands.

Codex supports layered `AGENTS.md` files from repository root to working directory. ComfyUI also auto-loads frontend files, so generic repository assumptions can be unsafe for `web/` and node-schema work.

## Decision

- Use a concise root `AGENTS.md` for repository-wide executable rules.
- Use scoped `AGENTS.md` files only in `nodes/`, `web/`, and `tests/`, where local constraints materially differ.
- Use `docs/` as the structured maintainer knowledge base.
- Keep user documentation in root `README.md` and durable design choices in numbered ADRs.
- Keep one-off cleanup reports under `docs/maintenance/`.
- Keep tests in `tests/` and run them in isolated processes through `tests/run_all.py`.

## Consequences

- Agents receive the right constraints close to the files they edit without overloading the root instruction file.
- Architecture and operational knowledge becomes reviewable and versioned.
- Changes that affect configuration, compatibility, or runtime boundaries must update documentation in the same work unit.
- Maintainers must keep links and commands synchronized as the portable layout evolves.

## Alternatives considered

- One large root instruction file: rejected because it mixes executable rules with background knowledge and approaches instruction-size limits as the project grows.
- Documentation only in README: rejected because user guidance and maintainer internals have different audiences and change rates.
- Tool-specific hidden configuration directories: rejected because they are not portable across agents and should not be runtime project state.

## Validation

- Verify root and scoped instruction files are discoverable from their directories.
- Verify every path linked from `docs/README.md` exists.
- Run the full isolated test suite and the plugin import smoke test after structural changes.