# Maintainer and agent documentation

This directory is the structured knowledge base for maintaining `comfyui_o1key`. Keep executable rules concise in `AGENTS.md`; keep explanations, diagrams, and procedures here.

## Start here

- [Architecture](architecture.md): runtime boundaries, startup flow, storage, and dependency direction.
- [Development](development.md): how to add or change nodes, clients, routes, and frontend extensions.
- [Testing](testing.md): isolated offline suite, smoke tests, and validation matrix.
- [Configuration](configuration.md): supported settings, storage, precedence, and security rules.
- [Architecture decisions](decisions/README.md): durable decisions and the ADR template.
- [Maintenance history](maintenance/cleanup-2026-08-29.md): the deep-cleanup baseline for the current layout.

## Knowledge ownership

| Change | Required documentation |
| --- | --- |
| User installation or visible behavior | `README.md` |
| Runtime boundary or data flow | `docs/architecture.md` |
| Configuration key or precedence | `docs/configuration.md` |
| Development/test procedure | `docs/development.md` or `docs/testing.md` |
| Compatibility-sensitive design choice | `docs/decisions/NNNN-title.md` |
| One-time repository maintenance | `docs/maintenance/YYYY-MM-DD-topic.md` |

## AI handoff checklist

Before ending a non-trivial change, leave the repository in a state where the next maintainer or agent can answer:

1. What runtime boundary changed?
2. Which invariant protects backward compatibility?
3. Which offline test proves the behavior?
4. Which document is now the source of truth?
5. Are any follow-up risks or decisions still open?