Audit migration completeness and expand agent and book guidance
This commit is contained in:
parent
4eef1bca81
commit
a595838a31
120
AGENTS.md
120
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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in New Issue