Phase 20: package Linux builds and document release and maintenance workflows

docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,35 @@
+# Known limitations and qualification boundaries
+
+- Development version 0.1.0, Linux C99/C++17/FLTK, optional JACK. Physical-device
+  playback/capture, human transition listening, independent user acceptance and
+  long-duration device qualification are pending.
+- Fixed 4/4 and constant tempo snapshots; no tempo map, loop transport, plugin
+  latency compensation, limiter, background streaming or multichannel mixer buses.
+- Mono capture/import downmix; stereo track output. Graph ports are mono with
+  independent paired processing. Maximum 64 project graph nodes (256 standalone),
+  64 tracks, 1024 clips/automation points, 4096 scheduled notes, 256 live MIDI
+  events/block, 32 voices, 65536 frames/block. See API headers for exact bounds.
+- WAV samples preload with the memory/format limits in AUDIO_FILES.md. Callback
+  overflow reports/silences; there is no CPU preemption or expensive-plugin rescue.
+- Live MIDI fixed volume/pan/sustain mapping; no controller learn, capture, SMF
+  import, pitch bend, custom-instrument chooser or instrument timbre controls.
+- Native ABI 1 graph nodes are session-only. ABI 2 state is parameter-only. LADSPA
+  supports the documented mono amp/inverter/sine set; no opaque state, native
+  editor, MIDI, true multichannel layout, latency compensation or crash isolation.
+  Automated LADSPA controls use run(1) and can be expensive.
+- GUI loading/compilation is synchronous on the control thread. Timeline grid/
+  zoom/selection and graph positions are session UI state. Undo retains 32 edits
+  plus baseline; allocation failures are reported, not silently hidden. Media is
+  never removed by undo/delete. Broad screen-reader/accessibility testing is pending.
+- Format v7 reads v1–v6 and uses relative local media references. External absolute
+  media/module paths need manual repair after relocation. Saving does not bundle
+  media; missing media stays referenced, missing plugins reject GUI installation.
+  Unknown data is rejected rather than stripped. Post-rename directory-sync errors
+  can report failure even though the complete new document was published.
+- No autosave/session crash restoration, RF64, system service, automatic dependency
+  installation or public signed release. Source/binary archives are local artifacts;
+  binary packages require compatible system libraries. No third-party plugin or
+  dependency binary is bundled. Power-cut durability depends on the filesystem.
+
+See ROADMAP.md, AUDIO_QUALITY.md, CONTROL.md, WORKFLOW.md, PROJECT_FORMAT.md,
+PERFORMANCE.md, PLUGIN_HOSTING.md and RECOVERY.md for tested contracts/evidence.

docs/LINUX.md

@@ -56,3 +56,29 @@ Static backend consumers need JACK if that optional backend was built; the pc
 file records its private dependency. Public headers contain no JACK/FLTK types.
 To build without optional libraries, set PKG_CONFIG=false FLTK_CONFIG=false.
 Python is not needed to run the installed executables or library.
+
+## Phase 20 binary/development archive
+
+`make package` creates a system-linked Linux archive plus SHA-256 sidecar below
+BUILD_DIR; `make test-package` verifies its contents. It includes usr/bin,
+headers/static library/pkg-config metadata, desktop file (when FLTK is present),
+manuals, baseline and MIT license. No shared library, third-party plugin, media,
+service or dependency installer is bundled. `BINARY_MANIFEST.json` lists file
+hashes/sizes, architecture/libc and ELF NEEDED libraries. The entire archive's hash
+covers the manifest too. Do not assume compatibility with another distribution.
+
+Inspect/test under a temporary directory first. For a writable user prefix,
+extract the archive with two leading path components stripped (`xtc-VERSION-linux-
+ARCH/usr`), placing bin/include/lib/share directly under that prefix. Put its bin
+on PATH and lib/pkgconfig on PKG_CONFIG_PATH. The archive's pkg-config prefix is
+relative to its installed location; normal `make install` retains explicit PREFIX.
+Use the matching source's uninstall with that PREFIX, or review the manifest
+before removing its files. Unknown/unrelated files are retained by source uninstall.
+This local tar package is not a pacman/RPM/deb registration or public distribution.
+
+`xtc-check --diagnose` reports build capabilities and format/engine limits without
+opening a server or executing a plugin. `xtc --diagnose` works headlessly as well.
+Missing runtime GUI libraries are loader errors: install the distribution's
+compatible dependencies or rebuild the core-only configuration. Build without
+optional libraries using a fresh directory, `PKG_CONFIG=false FLTK_CONFIG=false
+CPPFLAGS=-DXTC_DISABLE_LADSPA`. No system setting or package is changed by tests.

docs/MAINTENANCE.md

@@ -0,0 +1,55 @@
+# Release and maintenance policy
+
+## Supported development target
+
+Initial target: x86_64 Artix/Arch-family Linux with glibc, GNU Make, GCC/Clang,
+FLTK 1.4 and a JACK-compatible client/server. The inspected host uses GCC 16.2.1,
+FLTK 1.4.5 and the dependencies in LICENSES.md. Core-only/no-JACK/no-LADSPA builds
+are checked too. Build on the destination distribution for different library ABIs;
+there is no cross-distribution static-binary promise. Python 3.12+ and binutils
+are build/package/test tools only. No dependency is fetched automatically.
+
+## Release checklist
+
+1. Work from a clean reviewed commit. Record `git rev-parse HEAD`, compiler,
+   libc/FLTK/JACK versions and `xtc-check --diagnose`. No automatic version bump,
+   Git tag, public upload or external release is performed by local targets.
+2. Run warning-enabled `make all test gui test-plugins test-plugins-real
+   test-gui-plugins test-workflow test-gui-jack test-jack-midi test-recording
+   test-recovery test-reliability test-scale analyze` where dependencies exist.
+3. Use a separate BUILD_DIR for ASan/UBSan/leak runs and another for optional-
+   dependency builds. GUI leak checks use only the documented fontconfig
+   suppression; core tests use none. Run publication/recording race tests as
+   described in RELIABILITY.md. Sanitizers are not latency qualification.
+4. Run `make benchmark test-performance test-stress`; compare on matching
+   host/compiler/flags against a reviewed baseline. Investigate regressions;
+   do not weaken thresholds or replace evidence without explanation.
+5. Run `make test-install test-release test-package`. Inspect archive manifests,
+   hashes, dynamic dependency names and licenses. Source exports rebuild twice
+   with identical artifacts on this host. Repeat binary packaging compares bytes.
+6. Complete physical listening, recording/device/endurance, and independent human
+   install/workflow checks before claiming production qualification. They remain
+   pending for this prototype, even when all automated checks pass.
+7. Save checksums/test logs/conditions with the proposed release. Review known
+   limitations and format compatibility and update user/developer docs. Publishing
+   or distro repository submission is a separate action.
+
+## Regressions and compatibility
+
+Report the exact version/commit, OS/toolchain, compiled features, reproduction,
+expected/actual output, GUI errors/xruns and whether plugins are involved. Keep a
+minimal project/media fixture when redistribution is permitted; do not attach
+private recordings or full memory dumps inadvertently. No telemetry/upload occurs.
+
+A confirmed defect gets a focused deterministic regression or repeatable runtime
+check before its fix. Memory/thread/file-loss defects take priority; disable the
+unsafe path rather than silently dropping media or unknown project records. Keep
+candidate preparation/plan publication transactional and callbacks bounded.
+
+Format changes increment XTC_PROJECT_FORMAT_VERSION, retain explicit bounded
+migrations/fixtures for all supported older versions, and add malformed/roundtrip
+checks. Unknown versions/types/records fail with actionable errors. Never rewrite
+an unsupported source file during failed Open. Keep the original when diagnosing
+post-publication sync errors. Native descriptor ABI compatibility is distinct from
+project format and is documented in NATIVE_API.md; opaque DSP state is not promised.
+No public stability guarantee or support SLA is implied by development version 0.1.0.

docs/PROJECT_FORMAT.md

@@ -154,7 +154,8 @@ discrete-mode compatibility are checked on control-thread compilation. Versions
 Current writer emits v7; readers migrate v1–v6. Record ordering and field bounds
 are otherwise unchanged from v6. v7 ASSET may contain a relative path, interpreted
 against the actual containing directory of the named project file (resolved on
-the control thread), never the launch working directory. After loading, all core
+the control thread), never the launch working directory. Opening a symlink to a project uses the
+resolved target project directory; Save replaces the named entry as before. After loading, all core
 asset references are absolute, including missing media. Media inside the save
 folder are written relative; references outside remain absolute. Save As resolves
 against its new folder and preserves media identity rather than rebasing it by

docs/RELEASING.md

@@ -54,3 +54,21 @@ semantics. Physical devices, power loss, sustained recording/performance, user
 acceptance on other distributions and binary redistribution are still separate
 qualification work. There is no DEB/RPM/AppImage, bundled runtime, autosave,
 external plugin host or stable shared-library extension ABI in this release.
+
+## Phase 20 local binary packaging and installed workflow
+
+`make test-package` builds the release, stages installation only in a temporary
+DESTDIR, writes a normalized Linux binary/development archive, checks its SHA-256
+sidecar and per-file manifest, relocatable pkg-config paths and headless commands.
+Same-host repeated packaging is byte-identical; dependency versions and toolchain
+still determine binary compatibility. `make test-install` now repeats installation
+to verify repair/upgrade of owned files while preserving an unrelated sentinel,
+then compiles both C99 and C++17 installed consumers that create MIDI, save/reopen
+and compare nonzero exact rendering. Removal remains exact and idempotent.
+
+USER_MANUAL.md consolidates operation; KNOWN_LIMITATIONS.md lists qualification
+gaps; MAINTENANCE.md defines the release checklist, regression and compatibility
+policy. Build diagnostics make no server/plugin calls. There is no asynchronous
+crash uploader or signal-handler cleanup: inspect OS core/debugger evidence on
+the control side, preserving project/media recovery paths. No release is publicly
+published by these commands, and human/device/listening checks remain pending.

docs/ROADMAP.md

@@ -448,6 +448,16 @@ policy. Arbitrary plugin costs and physical realtime/endurance are unqualified.
 - Dependencies, licensing, limitations, and troubleshooting steps are documented.
 - A release can be reproduced from a clean checkout with recorded build instructions.
 
+Implemented: normalized Linux binary/development archives with SHA-256/file/
+ELF-dependency manifests, headless compiled-feature diagnostics, repeat-install
+upgrade/repair and installed C/C++ save/reopen/render checks. Existing deterministic
+source/release, no-dependency, sanitizer, staged uninstall and GUI/live tests are
+retained. USER_MANUAL.md, KNOWN_LIMITATIONS.md and MAINTENANCE.md consolidate setup,
+operation, licensing/diagnostics, release and regression policy. No public release
+or distro registration is performed. Independent human installation/usability,
+physical-device/endurance and listening acceptance remain pending and must be
+completed before claiming production qualification.
+
 ---
 
 ## Recommended Execution Order

docs/USER_MANUAL.md

@@ -0,0 +1,98 @@
+# xtc user manual (0.1.0 development build)
+
+xtc is a bounded Linux music-making prototype. Start with a copy of an important
+project and keep backups of its WAV media. Supported limits and unfinished areas
+are listed in KNOWN_LIMITATIONS.md; no production/device qualification is implied.
+
+## Build or install
+
+Follow BUILD.md and LINUX.md. Core: `make all test`; GUI: `make gui`, then
+`./build/xtc`. Use an existing JACK-compatible server and reconnect with F6.
+Connect `midi_in` to a controller, `input` to mono capture and `output` /
+`output_right` to left/right playback using your JACK routing application.
+No server, physical routing or system configuration is changed automatically.
+`xtc --version`, `xtc --help` and `xtc --diagnose` need no display/server.
+
+For a source install stage with `make install-gui DESTDIR="$PWD/build/stage"
+PREFIX=/usr`, inspect the stage, and use your normal deployment process. A user
+prefix is supported (for example an absolute path to your `.local` folder).
+`make uninstall` with the same DESTDIR/PREFIX removes only that version's known
+files. See LINUX.md for package extraction, dependencies and removal. Never use
+a release built for a different system ABI without rebuilding/testing it.
+
+## Make a short project
+
+1. New/Open starts in Sequencer. Add track; use F2 to name it.
+2. Add MIDI clip, select it and open Piano roll (Ctrl+4). Left-click to draw
+   notes, drag to move, drag a right edge to resize, Delete/right-click to remove.
+3. Alternatively Import WAV (Ctrl+I). It creates/routes an Audio clips source;
+   supported WAV formats and preload limits are in AUDIO_FILES.md.
+4. Drag clips to arrange them and edges to trim. View/Snap sets the timeline
+   grid; +/- zoom buttons and scrollbars navigate. Ctrl+D duplicates a clip after
+   its end, retaining its complete source. F2 names clips; right-click offers
+   duplicate/rename/delete. Alt+Up/Down with timeline focus reorders tracks.
+5. Play/F5 starts; Pause/F7 or Stop/F8 leaves the position for resuming. Home
+   returns to start while stopped (or stops first); click the ruler to seek.
+   Recording uses Stop, not Pause. F9 Panic releases the instrument.
+6. Mixer (Ctrl+2) offers track gain/pan/mute/solo and Gain/Pan automation lanes.
+   Click to add points, right-click to remove. CONTROL.md explains timing and
+   live CC7 volume, CC10 pan and CC64 sustain.
+7. Save (Ctrl+S), close, reopen and continue editing. Ctrl+Z undoes and
+   Ctrl+Shift+Z/Ctrl+Y redoes. New/Open resets history after unsaved-change handling.
+
+Modular Graph (Ctrl+3) exposes routing. Drag output to input to connect, select a
+wire/node and Delete to remove; cycles and invalid ports are rejected. Keep an
+Output route for playback. GUI changes show queued/active graph status. Graph
+positions are session-only; music/routing/automation are saved. Edits that prepare
+new plans stop playback; disk/compilation may pause the GUI, never run in audio.
+
+## Record and retain media
+
+Choose a project folder and save the project there first. Record/Shift+F5 asks for
+an unused WAV path. Stop finalizes the take and inserts it. Existing destinations
+are protected, including a file created while recording. Undo/removing a take
+removes its reference, never the recorded file. Imported external files are also
+never deleted. WAVs inside the save folder become relative references; move the
+folder and media together. Save As preserves the same source media, not a copy.
+
+On write failure the GUI reports a retained path. Keep it and recover complete
+frames to a different, unused destination:
+
+```sh
+xtc-check --recover-recording take.wav.tmp.XXXXXX recovered.wav
+```
+
+Only xtc's canonical float32 mono temporary format is salvaged. Incomplete trailing
+frames are omitted. The source is retained. Import/relink the recovered WAV.
+Missing/unreadable media is silent and reported; select the clip and use File/
+Relink selected audio. See RECOVERY.md for interruption, disk-full and power-loss
+limits. Close/project operations are refused while recording; finish the take first.
+
+## Trusted effects and sources
+
+File/Load LADSPA plugin lists compatible descriptor indices from the chosen `.so`.
+Loading executes native code. Select a documented compatible mono plugin, connect
+its graph ports, then use Edit/Selected plugin control. Edit/Selected plugin
+automation adds/removes tick-based linear or step points. Control names/ranges
+appear in the dialogs. Module identity/control values/lanes save with the project;
+module binaries and DSP history do not. The initial amp/inverter/sine set and
+unsupported layouts are listed in PLUGIN_HOSTING.md. Missing plugins reject GUI
+Open with identity/path information and preserve the saved/current documents.
+Restore the compatible module at that path and retry. Plugins are not sandboxed.
+
+## Diagnose a problem
+
+Run `xtc-check --diagnose` and capture the version, architecture, compiled features,
+GUI error text and steps to reproduce. `xtc-check --validate song.xtc` checks
+metadata without opening plugins/media; it does not certify playback resources.
+Check JACK routing, sample rate/format and xrun/process status in the GUI. After
+server loss/rate change stop/reconnect and retry. Keep the original project,
+media and retained temporary files before recovery attempts.
+
+A native plugin can crash/hang the process. There is no crash-isolation guarantee.
+Use the operating system's core-dump/debugger tools if available; xtc does not
+install signal handlers, change core limits or upload crash reports. Debugger/
+core files may contain media paths and audio memory; share only what you intend.
+Report bugs following MAINTENANCE.md, including whether the issue reproduces
+without plugins. Physical listening and independent human install/usability
+acceptance remain pending.