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

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.