canvas-pilot/AGENTS.md

113 lines
6.9 KiB
Markdown

# Canvas Pilot
Independent Rust/egui layout editor for presentation switchers; not affiliated with
Analog Way. This repository owns the application, device probe, exchange templates,
manual and build tooling. It must build without a sibling beffroi-tools checkout.
Keep the single-member workspace and adapter design simple; avoid speculative layers
of abstraction. User instructions take precedence over this guidance.
When resuming the migrated conversation, read `docs/development/handoff.md` for
pending decisions, video plans, prior test authorization and publication state.
Treat dated observations as a snapshot and verify current state before acting.
## Project map
- `crates/canvas-pilot/src/`: editor and application. `lib.rs`, `project.rs`,
`formats.rs` and `snapping.rs` own geometry, persistence and editing rules;
`gui.rs` and the `*_ui.rs` modules own interaction and presentation.
- `device.rs`, `device/`, `device_send.rs` and `device_capture.rs`: shared device
representation and Midra/Aquilon implementations. Keep protocol paths, conversion
and apply behavior inside the appropriate adapter; do not leak them into generic
geometry or editor controls. Preserve bounded reads, partial writes, preflight,
cancellation, explicit unsupported-mode errors and verified readback.
- `exchange.rs`, `interchange.rs`, `geometry_formats.rs`, `vendor_formats.rs` and
`exchange_metadata.rs`: exchange formats and embedded metadata. Preserve the shared
geometry model, precision, import review and optional vendor-format build.
- `crates/canvas-pilot/tests/` and `tests/fixtures/` within that crate: Rust regression
tests and sanitized device/clipboard fixtures. `examples/` contains explicitly
invoked device diagnostics; these are not automated hardware tests.
- `tools/midra_probe.py`: standalone, read-only Python diagnostic tool.
`tests/` at the repository root covers the probe, templates and build/publication
helpers. `docs/templates/canvas-pilot/` owns all eleven-format starter files and ZIP.
- `scripts/`, root Cargo/Cross/release configuration and `Jenkinsfile`: independent
build, checks, packaging, artwork, launchers and documentation publication.
## Authoritative documentation
Use `AGENT_DOCUMENTATION.md` as the index for contracts, research, handoffs,
acceptance evidence and technical notes. Use `docs/development/README.md` for the
project plan, tasks, stretch goals and contribution workflow. Read the linked
records before changing behavior; do not duplicate their status in new checklists.
The user manual is built from the Markdown files listed in
`docs/manuals/canvas-pilot/SUMMARY.md`. Edit those chapters as the single source of
user-facing instructions. Keep READMEs short navigation pages. Do not put task lists,
handoffs or agent contracts on the main README or in the user book's chapter list.
Keep completed work, remaining acceptance and future ideas distinct. Preserve the
documented support boundaries; emulator evidence is not physical-output acceptance.
## Compatibility and device behavior
Document every persistent save/export representation under `docs/interfaces/`,
including fields, units, precision, versions, validation, omissions and round trips.
The project, settings, recovery and exchange contracts and versioned examples are
there, alongside device adapters and reviewed Midra transfers. Update documentation,
fixtures and meaningful regression tests in the same change as a schema modification.
Provide tested migrations or clear unsupported-version errors for breaking changes.
Preserve settings locations and legacy Midra identifiers; renaming the repository
must not reset user preferences or change serialized formats.
Preserve source documents. Imports and failed operations must not silently replace
working projects or existing exports. Keep device writes explicit and within the
user's authorized scope; never infer authorization from a saved address. Geometry
operations must not implicitly route sources, TAKE, or alter shared input settings.
Advanced input writes remain opt-in. Device writes and physical-output acceptance
are never CI tests. Do not commit credentials or unsanitized captures.
## Validation and documentation
For Rust changes, follow `docs/development/ci.md`: formatting, Clippy and rustdoc
with warnings denied, workspace tests, default vendor-format tests and the
`--no-default-features --features no_proprietary` tests. `--all-features` activates
`no_proprietary`, so it does not cover the normal vendor codecs by itself.
Run `python3 scripts/ci.py coverage` for whole-application coverage (75% floor);
never exclude production GUI or format code to inflate it.
Run `python3 -m unittest discover -s tests -v` for Python/build-helper changes.
For documentation changes, run `python3 scripts/manuals.py build` with the mdBook
version pinned in `docs/manuals/mdbook-version`; it validates links, downloads and
print-view anchors. Use `docs/manuals/canvas-pilot/SUMMARY.md` to maintain chapters.
Keep screenshots and template bytes intact unless intentionally updating them;
the template ZIP and individual files must agree. Test actual rendering with the
relevant external tools when available; report checks that could not be completed.
Keep root README concise and put details in `docs/`. Add a succinct Unreleased
entry to `docs/canvas-pilot/changelog.md` for each change, including useful validation
or limitations; it is linked from `docs/changelogs.md`.
## Version bookkeeping
Bump the workspace patch version once per completed subject (feature, fix or
substantive documentation task), not once per commit. Follow-up corrections and
validation for that same subject share its version. Read-only work needs no bump.
Use a requested minor/major bump instead of an additional patch bump. Keep
`Cargo.toml`, the Canvas Pilot entry in `Cargo.lock` and the changelog in sync;
group entries by version under Unreleased until published. Keep this lightweight:
version bookkeeping alone does not call for a tag, binary build, push or release.
## Publication and working conventions
Manual publication owns only `/mnt/books/manuals/canvas-pilot/`; never replace the
shared manuals index or another book. Badge publication owns only
`/mnt/assets/coverage/idle-org/canvas-pilot/main/`. Main/non-PR restrictions apply.
Jenkins archives exactly the version, test and coverage SVGs; it does not create
releases or publish binaries. See `docs/development/ci.md` for job setup and
`docs/development/releases.md` for manually invoked packaging.
Inspect the working tree first. Preserve unrelated changes, use existing dependencies
and Python's standard library where practical, and keep temporary files temporary.
Never commit credentials, caches, generated manuals, release archives or executables.
Every completed task changing repository files must end with a descriptive Git commit.
Stage only task-owned changes, report the commit and validation, and do not push unless
requested. Read-only audits need no empty commit.