From a595838a31ac8e02588bccf58e9bb4d5d44f56db Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Mon, 16 Nov 2026 10:30:17 +0100 Subject: [PATCH] Audit migration completeness and expand agent and book guidance --- AGENTS.md | 120 +++++++++++++++++++++++---- README.md | 4 +- docs/README.md | 20 ++++- docs/canvas-pilot/changelog.md | 6 ++ docs/development/README.md | 3 + docs/development/migration.md | 34 ++++++++ docs/manuals/canvas-pilot/SUMMARY.md | 9 ++ 7 files changed, 180 insertions(+), 16 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4282f60..786dcba 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/README.md b/README.md index 8293804..6c8facf 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/docs/README.md b/docs/README.md index 6261dad..6b03139 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. diff --git a/docs/canvas-pilot/changelog.md b/docs/canvas-pilot/changelog.md index 59a975f..1e6db0a 100644 --- a/docs/canvas-pilot/changelog.md +++ b/docs/canvas-pilot/changelog.md @@ -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. diff --git a/docs/development/README.md b/docs/development/README.md index 8091f16..f579954 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -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. diff --git a/docs/development/migration.md b/docs/development/migration.md index 04aa86a..96cd6cc 100644 --- a/docs/development/migration.md +++ b/docs/development/migration.md @@ -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. diff --git a/docs/manuals/canvas-pilot/SUMMARY.md b/docs/manuals/canvas-pilot/SUMMARY.md index 7ab9dda..d90570e 100644 --- a/docs/manuals/canvas-pilot/SUMMARY.md +++ b/docs/manuals/canvas-pilot/SUMMARY.md @@ -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)