update

AGENTS.md

@@ -0,0 +1,160 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository.
+
+## Project at a glance
+- Language: Python
+- Package layout: `src/flow/`
+- Tests: `tests/` with `pytest`
+- Build backend: Hatchling (`pyproject.toml`)
+- CLI entrypoint: `flow.cli:main` (`python3 -m flow`)
+- Binary packaging: PyInstaller (`Makefile`)
+
+## Build, test, and validation commands
+
+### Setup
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+### Run CLI locally
+```bash
+python3 -m flow --help
+python3 -m flow --version
+```
+
+### Run all tests
+```bash
+python3 -m pytest
+```
+
+### Run a single test file
+```bash
+python3 -m pytest tests/test_cli.py
+```
+
+### Run a single test function
+```bash
+python3 -m pytest tests/test_cli.py::test_version
+```
+
+### Run a single test class
+```bash
+python3 -m pytest tests/test_commands.py::TestParseImageRef
+```
+
+### Run tests by keyword expression
+```bash
+python3 -m pytest -k "terminfo"
+```
+
+### Build standalone binary
+```bash
+make build
+```
+
+### Install local binary
+```bash
+make install-local
+```
+
+### Smoke-check built binary
+```bash
+make check-binary
+```
+
+### Clean build artifacts
+```bash
+make clean
+```
+
+### Lint/format/type-check status
+- No dedicated lint/format/type-check commands are currently configured.
+- There is no Ruff/Black/isort/mypy config in `pyproject.toml`.
+- Agents must follow existing style and keep diffs readable.
+
+## Code style conventions
+
+### Imports
+- Group imports as stdlib, third-party, then local (`flow.*`).
+- Use explicit imports; avoid wildcard imports.
+- Keep imports at module top unless a local import prevents a cycle or unnecessary load.
+
+### Formatting
+- Use 4 spaces for indentation.
+- Keep lines readable; wrap long calls/literals across lines.
+- Keep trailing commas in multiline calls/lists where helpful for cleaner diffs.
+- Match local quoting style within each file (mostly double quotes).
+
+### Typing
+- Codebase uses gradual typing, not strict typing.
+- Add type hints for new helpers, dataclasses, and public functions.
+- Follow local module style (`Optional`, `Dict`, `List` vs builtin generics).
+
+### Naming
+- `snake_case` for functions, variables, module-level helpers.
+- `PascalCase` for classes/dataclasses.
+- `UPPER_SNAKE_CASE` for constants.
+- Prefix private helpers with `_` when not part of module API.
+
+### Command module patterns
+- Each command module exposes `register(subparsers)`.
+- Subcommands bind handlers via `set_defaults(handler=...)`.
+- Runtime handler signature is typically `(ctx: FlowContext, args)`.
+- Keep parse/plan/execute steps separated when logic grows.
+
+### Error handling
+- Use concise user-facing messages via `ctx.console.error(...)`.
+- Use `sys.exit(1)` for expected CLI failures.
+- Keep `KeyboardInterrupt` behavior as exit `130`.
+- Raise `RuntimeError` in lower-level helpers for domain failures.
+- Avoid noisy tracebacks for normal user mistakes.
+
+### Subprocess safety
+- Prefer `subprocess.run([...], check=True)` when possible.
+- For shell strings, quote dynamic values (`shlex.quote`).
+- Avoid passing unchecked external input into shell commands.
+- Use `capture_output=True, text=True` when parsing command output.
+
+### Filesystem and paths
+- Prefer `pathlib.Path` for path-heavy logic.
+- Expand `~` intentionally when required.
+- Ensure parent dirs exist before write/link operations.
+
+### Tests
+- Add/update tests for behavior changes.
+- Keep tests deterministic and host-independent when possible.
+- Favor focused tests for parser/planner helper functions.
+
+## Architecture notes
+- `src/flow/cli.py`: parser wiring, context creation, top-level exception handling.
+- `src/flow/commands/`: user-facing command implementations.
+- `src/flow/core/`: shared primitives (`config`, `console`, `process`, `stow`, etc.).
+- `FlowContext` holds config, manifest, platform info, and console logger.
+
+## Behavior constraints to preserve
+- Self-hosted config/manifest priority: dotfiles path first, local fallback.
+- Manifest uses `profiles`; legacy `environments` is intentionally rejected.
+- Dotfiles link state supports v2 format only (`linked.json`).
+
+## Cursor/Copilot rule files
+No repository-level rule files were found at the time of writing:
+- `.cursorrules` not found
+- `.cursor/rules/` not found
+- `.github/copilot-instructions.md` not found
+
+If these files are later added, treat them as authoritative and update this guide.
+
+## Workspace hygiene
+- Do not commit generated outputs: `build/`, `dist/`, `*.spec`.
+- Do not commit Python bytecode/cache files: `__pycache__/`, `*.pyc`, `*.pyo`.
+- Keep changes scoped; avoid unrelated refactors.
+- Update tests/docs when user-facing behavior changes.
+
+## Agent checklist before finishing
+- Run targeted tests for touched behavior.
+- Run full suite: `python3 -m pytest`.
+- If packaging/build paths changed, run `make build`.
+- Verify no generated artifacts are staged.
+- Ensure errors are concise and actionable.