Add AGENTS.md with unified section order

AGENTS.md

@@ -0,0 +1,81 @@
+# Repository Guidelines
+
+## Project Layout
+
+- `src/main.rs`: entrypoint — parses CLI and delegates to `run()`.
+- `src/cli.rs`: Clap definitions and help text.
+- `src/auth.rs`: credential resolution from env vars, embedded config, or interactive prompt.
+- `src/client.rs`: YouTrack SDK client setup.
+- `src/commands/`: user-facing handlers for `issue`, `comment`, and `attachment`.
+- `src/output.rs`: shared table and JSON output helpers.
+- `src/error.rs`: error types and exit-code mapping.
+- `.github/workflows/ci.yml`: GitHub Actions workflow for tests and release artifacts.
+- `CHANGELOG.md`: user-visible change log.
+
+## Build and Verification
+
+- `cargo fmt --all`: format the workspace.
+- `cargo check`: validate the crate.
+- `cargo test`: run unit tests.
+- `cargo clippy --all-targets -- -D warnings`: lint this crate.
+- `cargo run -- --help`: smoke-test the CLI locally.
+- `make build`: build the host binary.
+- `make build-locked YOUTRACK_URL=... YOUTRACK_TOKEN=...`: build the locked host binary.
+- `make install-binary`: install the host build from `target/release/youtrack-cli`.
+- `make ci`: runs fmt-check + lint + test.
+- GitHub Actions uploads release artifacts for `macos-silicon`, `linux-x64`, and `linux-x86`.
+
+## Implementation Rules
+
+- Follow `rustfmt` defaults: 4-space indentation, no manual alignment, trailing commas where formatter-friendly.
+- Use `snake_case` for modules and functions.
+- Use `PascalCase` for types and enums.
+- Keep command DTOs explicit and serializable.
+- Keep `src/main.rs` and the Clap layer thin.
+- Keep direct YouTrack API logic in `src/client.rs` or via the SDK, not in CLI structs.
+- Prefer small facade methods and thin command handlers over cross-layer abstractions.
+
+## Testing Expectations
+
+- Add tests beside the code they cover.
+- Keep CLI parser coverage in `src/cli.rs` under `#[cfg(test)]`.
+- Follow the existing `parses_*` and `rejects_*` naming pattern.
+- New commands should include at least one happy-path parse test and one invalid-input test for conflicting flags.
+
+## Versioning and Docs
+
+- Behavior changes require a patch version bump in the root `Cargo.toml`.
+- Keep the version bump in the same commit as the behavior change.
+- Update `CHANGELOG.md` after every commit and add the newest entry first under the current branch section.
+- Update `AGENTS.md` only when architecture, conventions, dependencies, versioning rules, or repo workflows change.
+
+Behavior changes include changes in `src/`, config resolution, request building, auth, output shaping, error mapping, or contributor workflows that change how the project is built, tested, released, or consumed.
+
+## Commit Rules
+
+- Keep commits small and imperative.
+- Capitalize the first word and omit the trailing period.
+- Keep the subject at 72 characters or fewer.
+- Do not use conventional-commit prefixes.
+- Focus the subject on what changed and why it matters.
+
+Examples:
+- `Add issue comment commands`
+- `Add attachment upload support`
+
+After each commit:
+1. Update `CHANGELOG.md`.
+2. Update `AGENTS.md` if repo conventions changed.
+3. Amend the commit so those documentation updates stay in the same commit.
+
+## Pull Requests
+
+- Include a short user-visible summary.
+- List verification performed, such as `cargo test` or `cargo clippy --quiet --no-deps`.
+- Call out config, credential, or embedded-build impact.
+
+## Security and Configuration
+
+- Do not hardcode runtime secrets in source.
+- Treat embedded-token builds as secret-bearing artifacts.
+- Credentials resolve in order: env var > embedded config > interactive prompt.