Audit migration completeness and expand agent and book guidance

This commit is contained in:
Dandaedre 2026-11-16 10:30:17 +01:00
parent 4eef1bca81
commit a595838a31
7 changed files with 180 additions and 16 deletions

120
AGENTS.md
View File

@ -1,21 +1,113 @@
# Canvas Pilot
Keep the single-member Cargo workspace simple. Preserve adapter boundaries and the
shared geometry representation. Device writes require explicit user authorization;
never run real hardware tests in CI. The Python probe remains read-only.
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.
Document persistent formats, units, precision, validation and migrations under
`docs/interfaces/`. Update fixtures and regression tests with schema changes.
Keep versioned compatibility, settings storage paths and legacy identifiers stable.
Use `docs/canvas-pilot/changelog.md` for succinct Unreleased entries for every change,
and keep the book chapter list and user guide current. See `docs/development/ci.md`
for required Rust/Python checks, both vendor and no_proprietary configurations, and
whole-application coverage. Never exclude production code to inflate coverage.
## 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 and task records
Start with `docs/README.md` for the full navigation index.
- `docs/canvas-pilot/README.md` and `guide/README.md`: introduction and advanced guide.
- `docs/canvas-pilot/plan.md`: completed implementation, current to-do list, distant
stretch goals and a separate acceptance-test list. Keep these categories distinct;
do not turn a completed task into new work during refactoring or migration.
- `docs/canvas-pilot/device-check.md`: hardware findings and verification procedures.
- `docs/canvas-pilot/aquilon_support.task.md`: completed Aquilon implementation
handoff; `aquilon-compatibility.md` records evidence and support boundaries.
Do not generalize the tested standalone AQL Cmax 6.2.x profile to every model or
firmware, or describe emulator evidence as physical-output acceptance.
- `docs/canvas-pilot/midra-aspect-test-checklist.md`: practical operator checks.
`midra-fit-precision.md`: unresolved precision questions for a manufacturer engineer.
Keep assumptions distinct from measured or operator-confirmed behavior.
- `docs/canvas-pilot/presentation-switcher-adapters.md`: future-adapter research and
documentation ranking. New adapters require protocol documentation and a usable
emulator/simulator before development; a candidate is not a release commitment.
- `docs/canvas-pilot/feature-demo-checklist.md`: ordered feature presentation script.
- `docs/canvas-pilot/images/README.md`: screenshot provenance and update instructions;
`images/` contains screenshots and `design/` retains historical visual proposals.
- `docs/development/migration.md`: migration provenance and completeness audit.
Earlier history and shared release notes remain linked to the old repository.
When implementing work, reconcile the plan and acceptance evidence as well as the
user guide. Removed or deferred ideas are not implicit authorization to implement
features. Consult the current plan instead of copying its changing status here.
## 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`.
## 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/`. CI must not create releases.
`/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 and commit every completed
task with a descriptive message. Report the commit and validation; do not push unless
requested. Do not commit credentials, temporary files, generated manuals or binaries.
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.

View File

@ -20,6 +20,8 @@ and GTK development libraries. Python tooling requires Python 3.11+.
[User guide](docs/canvas-pilot/guide/README.md) ·
[Templates](docs/templates/canvas-pilot/README.md) ·
[Changelog](docs/canvas-pilot/changelog.md) ·
[Development](docs/development/README.md)
[Development](docs/development/README.md) ·
[Tasks and stretch goals](docs/canvas-pilot/plan.md) ·
[Documentation index](docs/README.md)
Originally part of [beffroi-tools](https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools); see [migration notes](docs/development/migration.md).

View File

@ -1,3 +1,21 @@
# Documentation
[Canvas Pilot](canvas-pilot/README.md) · [User guide](canvas-pilot/guide/README.md) · [Templates](templates/canvas-pilot/README.md) · [Interfaces](interfaces/README.md) · [Development](development/README.md) · [Changelog](changelogs.md)
[Full manual](https://books.dandaedre.com/manuals/canvas-pilot/) · [Changelog](changelogs.md)
| Area | Documents |
| --- | --- |
| Getting started | [Introduction](canvas-pilot/README.md), [first layout](canvas-pilot/guide/quickstart.md) |
| Advanced use | [Advanced guide](canvas-pilot/guide/README.md), [resolution/cropping model](canvas-pilot/resolutions.md) |
| Tasks and stretch goals | [Implementation, to-do, stretch goals and acceptance tests](canvas-pilot/plan.md) |
| Device acceptance | [Hardware verification](canvas-pilot/device-check.md), [practical aspect checklist](canvas-pilot/midra-aspect-test-checklist.md), [engineering precision questions](canvas-pilot/midra-fit-precision.md) |
| Aquilon | [Completed support task](canvas-pilot/aquilon_support.task.md), [compatibility and evidence](canvas-pilot/aquilon-compatibility.md) |
| Future adapters | [Candidates and documentation ranking](canvas-pilot/presentation-switcher-adapters.md) |
| Presentation | [Feature demonstration checklist](canvas-pilot/feature-demo-checklist.md) |
| Pictures and designs | [Screenshot instructions](canvas-pilot/images/README.md), [historical visual proposals](canvas-pilot/plan.md#visual-proposals) |
| Exchange and persistence | [Starter templates](templates/canvas-pilot/README.md), [interface contracts and fixtures](interfaces/README.md) |
| Development | [Developer guide](development/README.md), [CI](development/ci.md), [release preparation](development/releases.md) |
| Book | [Generation and publication](manuals/README.md), [chapter list](manuals/canvas-pilot/SUMMARY.md) |
| Migration | [Provenance and completeness audit](development/migration.md) |
The plan is the authoritative task list. Completed work, outstanding acceptance
checks and distant stretch goals remain separate; the migration did not reset them.

View File

@ -4,6 +4,12 @@
## Unreleased
- Audited all 165 migrated project files; task lists, stretch goals, advanced guide,
screenshots, templates and fixtures were retained. Expanded agent guidance and
documentation navigation, and included the transferred checklists/research in
the book. Recorded the comparison against the exact pre-migration commit.
- Moved Canvas Pilot, its device probe, templates, tests and manual into the standalone
`idle-org/canvas-pilot` repository. Builds and documentation no longer require
beffroi-tools; project/settings compatibility and the public manual URL are unchanged.

View File

@ -9,3 +9,6 @@ in `docs/interfaces/`; maintain compatibility when changing persistence or expor
See the [plan](../canvas-pilot/plan.md) and [device checks](../canvas-pilot/device-check.md)
for remaining work and hardware validation. Device writes are never CI tests.
See [the documentation index](../README.md) for every planning and acceptance record,
and [AGENTS.md](../../AGENTS.md) for repository working conventions.

View File

@ -16,3 +16,37 @@ license and now belong to this repository. Build and test commands work without
sibling beffroi-tools checkout. The manual keeps its public URL; publication owns
only its book directory and its separate badge directory. Configure the new Jenkins
Multibranch Pipeline as described in [CI](ci.md) before expecting automatic updates.
## Completeness audit — 2026-11-16
Compared all project-owned files at the source commit above with the standalone
repository after migration (`4eef1bc`). All **165 files** were present:
| Transferred material | Files |
| --- | ---: |
| Application source, assets, examples and Rust tests | 68 |
| Guides, tasks, plans, research, screenshots and visual proposals | 27 |
| Canvas Pilot interface contracts and versioned fixtures | 31 |
| Midra interface contracts and fixtures | 5 |
| Adapter contract, Python probe and its/template tests | 4 |
| Book manifest and chapter list | 2 |
| Eleven formats × two template sizes, catalog and ZIP | 24 |
| Probe artwork | 4 |
At that migration commit, 163 files matched the source byte for byte. The only
intentional differences were the changelog (migration entry and historical release
links) and book configuration (new repository URL). In particular, every task and
stretch-goal checkbox, the advanced guide, all three screenshots, three SVG design
proposals, template downloads and regression fixtures were unchanged.
Shared Cargo/CI, coverage, icons, launcher and manual helpers were copied and adapted
separately. Developer documentation, root README, license and `AGENTS.md` were
adapted for the independent project. Earlier shared release notes remain linked
at the fixed source commit. The old repository's general future-program list is
about unrelated DMX/Dante projects and is intentionally not a Canvas Pilot backlog.
The follow-up audit expanded `AGENTS.md` and the documentation index, and added the
transferred demo, aspect, precision, adapter and completed-Aquilon checklists to the
book navigation. No outstanding acceptance item was marked completed by this audit.
Generated HTML is rebuilt from these sources rather than tracked. The public URL
is unchanged; automatic publication still depends on the new Jenkins job setup.

View File

@ -37,3 +37,12 @@
- [Aquilon compatibility investigation](../../canvas-pilot/aquilon-compatibility.md)
- [Device adapters and Aquilon exchange](../../interfaces/device-adapters.md)
# Checklists and future work
- [Feature demonstration checklist](../../canvas-pilot/feature-demo-checklist.md)
- [Midra aspect acceptance checklist](../../canvas-pilot/midra-aspect-test-checklist.md)
- [Midra precision questions for engineers](../../canvas-pilot/midra-fit-precision.md)
- [Future presentation-switcher adapters](../../canvas-pilot/presentation-switcher-adapters.md)
- [Completed Aquilon support task](../../canvas-pilot/aquilon_support.task.md)
- [Repository migration and completeness](../../development/migration.md)