chore: adjust agents.md slightly from latest approaches

Author: nlopes

AGENTS.md

@@ -3,14 +3,34 @@
 ## Project rules
 
 - **Use nextest**: `cargo nextest run` for tests, `cargo test --doc` for doctests
-- **Always `--all-features`**: all test/build/clippy commands
-- **Clippy pedantic**: `cargo clippy --all-targets --all-features -- --deny clippy::pedantic`
+- **Product spelling**: always write the product name as `acdc`, lowercase. Preserve other casing only in exact external quotations or case-sensitive identifiers and test inputs.
+- **Worktree ownership**: inspect `git status --short` before editing. Preserve unrelated and staged work, and do not stage or commit unless the user explicitly asks.
+- **Feature coverage**: use `--all-features` for standard test/build/clippy commands. When a task changes supported feature-off behavior, also run the applicable documented `--no-default-features` configuration.
+- **Clippy pedantic**: `cargo clippy --all-targets --all-features -- --deny clippy::pedantic --deny clippy::todo`
 - **Format before committing**: `cargo fmt --all`
 - **Compact imports**: merge imports from the same crate/module into one `use` with braces, e.g. `use std::{borrow::Cow, io::Write};` — not separate `use std::borrow::Cow;` / `use std::io::Write;` lines
 - **Update changelogs**: each crate has its own `CHANGELOG.md`; update `[Unreleased]` for affected crates. Entries describe what a user sees or is affected by — the new behavior, the attribute/option to reach it, and any divergence from `asciidoctor`. Never regurgitate internal mechanics (function/field names, struct changes, control flow); those belong in code/commits, not the changelog.
 - **Surface converter warnings structurally**: user-relevant converter warnings should use `Warning` / `Diagnostics`, not `tracing::warn!`
 - **Never use CLI for fixtures**: use the examples directly (CLI adds `last_updated` timestamps)
-- **asciidoctor is reference**: when output differs, use `compare-asciidoc-output` agent
+- **asciidoctor is reference**: compare one source using the built `acdc` CLI and the matching asciidoctor backend first. Compare observable behavior, not byte-identical output, and avoid temporary Rust harnesses. Use the `compare-asciidoc-output` agent only after a direct comparison confirms a divergence or deeper research is needed. For PDF comparisons, keep clearly named `*-acdc.pdf` and `*-asciidoctor.pdf` outputs; do not create raster previews unless the user asks.
+
+## Validation workflow
+
+- Never run Cargo commands concurrently against the same target directory.
+- During implementation, run the smallest relevant package, test, or stable nextest expression, such as `-E 'test(/name/)'` rather than a generated fixture number.
+- Use `--all-features` for standard validation. When changing feature-off behavior, also run the applicable documented `--no-default-features` checks.
+- At a cross-crate, public-API, checklist, or commit boundary, run:
+
+  ```console
+  cargo fmt --all -- --check
+  cargo nextest run --workspace --all-features
+  cargo test --doc --workspace --all-features
+  cargo clippy --all-targets --all-features -- --deny clippy::pedantic --deny clippy::todo
+  git diff --check
+  ```
+
+- Report whether a broad command failed during compilation or after tests began.
+- Do not rerun Rust checks after a documentation-only wording change when the relevant code checks have already passed.
 
 ## Workspace features
 
@@ -32,7 +52,7 @@ New code that gates parsing or rendering on a specific substitution belongs behi
 
 When tests fail, identify the category and follow the appropriate path:
 
-- **Fixture mismatches** → run `regen-fixtures` skill (ask first)
+- **Fixture mismatches** → run the `regen-fixtures` skill (ask first). If the skill is unavailable, ask before using the documented scoped generator.
 - **Parser / grammar / preprocessor failures** → `acdc-parser/AGENTS.md`
 - **Converter failures** → `converters/AGENTS.md`
 

acdc-cli/AGENTS.md

@@ -8,6 +8,13 @@
 
 `setext` is default-on as a build feature and exposes the runtime `--setext` compatibility flag. `highlighting` forwards to whichever of the HTML and terminal backends are selected without enabling either backend itself.
 
+## Attribute overrides
+
+- The CLI owns parsing of `-a` syntax only. Parser `Options` owns protected and caller-locked attribute decisions.
+- Preserve the distinction between locked defaults and soft `@` assignments and unsets.
+- Do not add CLI-only lock exceptions.
+- Changes require CLI tests plus parser policy fixture and API tests.
+
 ## TCK compliance
 
 The CLI supports the AsciiDoc TCK (Test Compatibility Kit) behind a feature flag.

acdc-parser/AGENTS.md

@@ -23,6 +23,14 @@ The default-on `pre-spec-subs` feature governs whether `[subs="..."]` block attr
 
 Converter-side plumbing (`SubsFlags`, `effective_subs`, fixture naming) lives in `converters/AGENTS.md`.
 
+## Document attribute policy
+
+- `constants.rs` owns the static built-in read-only and API-only attribute protection.
+- `Options` combines built-in protection with locks supplied by the caller.
+- The CLI parses attribute assignment syntax, and converters may add unlocked defaults. Neither duplicates the parser's lock policy.
+- Keep the policy internal. The public parser API should expose only stable caller intent, never converter-specific or test-specific fields and functions.
+- When changing the policy, test document entries, parser `Options` and builder input, CLI `-a` input, locked and soft `@` assignments and unsets, and header/body exceptions. Compare both the official attribute documentation and the current asciidoctor implementation.
+
 ## Debugging
 
 - **Grammar failures** → use `trace-parse` skill, then check `src/grammar/`
@@ -40,6 +48,8 @@ Regenerate parser fixtures:
 cargo run -p acdc-parser --example generate_parser_fixtures --all-features
 ```
 
+The generator rewrites all parser JSON fixtures. Record `git status --short` before running it and inspect every changed fixture afterward. Treat the `.adoc` file as the test input and the generated `.json` file as expected output. Use stable nextest expressions instead of generated fixture numbers when running one fixture test.
+
 ## Property tests
 
 ```bash

converters/AGENTS.md

@@ -43,13 +43,23 @@ Shared utilities in `core/`:
     explicitly, and `test_fixture` has the matching `.contains("subs")`
     early-return.
 
+## Test placement
+
+- Use source and expected-output fixtures for rendered HTML, text, Typst, and other snapshot-like converter output.
+- Use integration tests for properties that snapshots cannot prove, including structured diagnostics, PDF annotations, PDF objects and metadata, warnings, and end-to-end behavior.
+
 ## Debugging
 
-- Use `compare-asciidoc-output` agent to diff converter output against asciidoctor
+- Compare the same source with the built `acdc` CLI and the matching asciidoctor backend before using the `compare-asciidoc-output` agent. Compare observable behavior rather than byte-identical output.
 - For fixture mismatches, run `regen-fixtures` skill (ask first)
 
 ## Fixture regeneration
 
+- Get approval before regenerating fixtures.
+- Record `git status --short` before regeneration.
+- Run one generator at a time. Each generator may rewrite its full fixture corpus.
+- Inspect status and the diff immediately afterward. Keep only intended changes or explicitly approved new baselines, and reject environment-only changes.
+
 ```bash
 cargo run -p acdc-converters-html --example generate_html_fixtures --all-features
 cargo run -p acdc-converters-terminal --example generate_terminal_fixtures --all-features
@@ -61,3 +71,10 @@ bash converters/markdown/tests/regenerate_expected.sh
 # Regenerate a single fixture:
 bash converters/markdown/tests/regenerate_expected.sh <fixture_name>
 ```
+
+### Terminal capability fixtures
+
+- The terminal fixture macro's boolean argument controls whether the test reads `.osc8.txt`. When it is `true`, the generic harness skips the fixture for terminals without OSC 8 support.
+- A plain `.txt` file for that same fixture is unused unless a separate no-OSC8 assertion reads it.
+- If both `.txt` and `.osc8.txt` are retained, add explicit coverage for both outputs.
+- Test terminal capability-dependent behavior with both `TERM=dumb` and `TERM=xterm-ghostty`.