lozenge0 · lozenge0 · Sep 13, 2026 · Sep 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,54 +1,39 @@
 # Changelog
 
-## Unreleased — targeting v0.1.0
-
-- Added a `Changes` field to the template so Community Apps shows a changelog
-  to users who already installed the app.
-- Project status now lives in one place, the top of `docs/RELEASE-REVIEW.md`.
-  Other documents link to it. Removed internal review narrative and stale test
-  and file counts from the public documentation.
-- The publication inventory test now reads Git's file list, so `pytest` caches
-  and other ignored files no longer fail it. Tests check document structure and
-  links rather than exact status sentences.
-- Added a PNG export of the existing community artwork and switched template/profile
-  icon URLs to PNG for Docker Manager compatibility. Original SVG preserved.
-- Changed the default host WebUI/API port to `6969` for CPU, CUDA 12 and CUDA 13
-  installations. Internal port `8080` and WebUI port resolution remain unchanged;
-  existing installations retain their configured host port.
-- Reworked the README around first-time use, hardware choice, installation and a
-  first speech sample. Moved detailed configuration, validation context and
-  maintainer notes into linked guides without changing container settings.
-- Added AI alongside Tools categorization for the base app and inherited CUDA
-  variants. Replaced pre-submission wording after owner-reported CA auto-approval;
-  beta status, catalog visibility uncertainty and remaining runtime checks retained.
-- Initial draft: one Community Apps template with CPU, CUDA 12 and CUDA 13 variants.
-- Direct moving upstream image references; no application builds or runtime wrappers.
-- Native model storage, network port and NVIDIA selection fields.
-- Native Docker `--user=99:100` for all variants, matching tested Unraid-created
-  model-directory ownership without modifying upstream images or file permissions.
-- Isolated CPU/CUDA 12/CUDA 13 downloads and browser/API inference, plus
-  owner-operated installation of pre-expanded private CA templates.
-- Controlled CUDA 13 recreation, newer-image update and retained-container
-  rollback with configuration/model integrity checks.
-- September 12 fixed official CPU image passed short-text, explicit streaming
-  and restart regression tests; owner subsequently confirmed playback.
-- Public CA branch selection, full DockerMan/scheduled update workflows and
-  optional JSON configuration remain outstanding; no full acceptance claim.
-- Reconciled release review and explicit publication file list.
-- Upstream artwork-independent community icon supplied by the project owner.
-- Owner approved MIT for integration files and CC0 1.0 for the icon on September
-  12, limited to rights they hold; upstream licences are unchanged.
-- Local structural checks and a deployment acceptance checklist.
-- Independent pre-GitHub template/privacy review; removed a host-specific GPU
-  prefix from a test fixture, clarified optional JSON validation and image ID labels.
-- Local light/dark icon previews and read-only embedded metadata inspection;
-  original artwork unchanged.
-- Prepared least-privilege, commit-pinned GitHub Actions CI, Dependabot action
-  updates, contribution/security guidance and a standalone Git publishing checklist.
-- September 13: published the approved GitHub review draft with a clean signed
-  history and noreply commit identity. First hosted CI passed. Public links,
-  file hashes and recorded repository security settings verified.
-
-No public versioned release has been made; the GitHub repository is a review draft.
-Version numbers describe the Unraid integration,
-not upstream audio.cpp. v1.0.0 is reserved for a validated stable integration.
+User-facing changes to the Unraid integration. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version numbers
+describe this integration, not upstream audio.cpp. `v1.0.0` is reserved for a
+validated stable integration. Entries that affect installed users are mirrored
+in the template's `Changes` field, which Community Apps shows as the app changelog.
+
+## [Unreleased]
+
+Targeting `v0.1.0`, the first beta release.
+
+### Added
+
+- Community Apps template for audio.cpp with CPU, NVIDIA CUDA 12 and NVIDIA
+  CUDA 13 variants, using unmodified upstream Docker images.
+- Model storage, host port and NVIDIA GPU selection fields.
+- A `Changes` field in the template so Community Apps shows release notes.
+- A PNG export of the community icon for the Unraid Docker page.
+- First-time user guide in the README, with configuration, maintainer and
+  validation notes under `docs/`.
+
+### Changed
+
+- New installations default to host port `6969`. Existing installations keep
+  their configured port.
+- Every variant runs as Docker user `99:100`, which matches the ownership of
+  model folders that Unraid creates. No image or file permissions are changed.
+
+### Fixed
+
+- The Unraid Docker page showed no icon because the template pointed at an SVG.
+  Docker Manager caches icons as PNG.
+
+### Known limitations
+
+- Public Community Apps branch selection, scheduled container updates and the
+  optional JSON configuration path are not yet validated. See the
+  [release review](docs/RELEASE-REVIEW.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,10 +16,12 @@ Before proposing a change:
 
 1. Explain its purpose and keep changes scoped to the integration.
 2. Run `python3 -m unittest discover -s tests -v` from the repository root.
-3. If adding a file, review its publication safety and update both the explicit
-   inventory in `tests/test_publication.py` and [release review](docs/RELEASE-REVIEW.md).
-4. Update setup guidance and the changelog when behavior changes. Record runtime
-   tests separately from local structural tests; CI has no Unraid server or GPU.
+3. If adding a file, review its publication safety and add it to the explicit
+   inventory in `tests/test_publication.py`.
+4. If behavior changes, update setup guidance and the changelog. If the change
+   affects installed users, add an entry to the template's `Changes` field.
+   Record runtime tests in a dated report under `docs/reports/`. CI has no
+   Unraid server or GPU.
 
 Pull requests run read-only CI on GitHub-hosted runners. Passing CI does not prove
 hardware compatibility or CA acceptance. Action updates are proposed by Dependabot

diff --git a/README.md b/README.md
@@ -134,6 +134,21 @@ See [permissions](docs/CONFIGURATION.md#storage-permissions-and-process-identity
 and [updates/rollback](docs/CONFIGURATION.md#updates-persistence-and-rollback)
 for the details.
 
+## Already installed?
+
+Unraid does not update the template of a container that is already installed.
+Changes to this template apply to new installations only. The app's change log
+in the Apps tab lists each change. If you installed before 2026-09-13:
+
+- The default host port changed to `6969` for new installations. Your
+  container keeps its current port. Nothing to do.
+- The app icon changed to a PNG so that the Docker page can show it. To get
+  the new icon, remove the container (your model folder stays), then install
+  `audio-cpp` again from the Apps tab with the same port and folder. If the old
+  icon still shows, Unraid kept a cached copy at
+  `/boot/config/plugins/dockerMan/images/audio-cpp-icon.png`. Delete that file
+  and reload the Docker page.
+
 ## Need help?
 
 - **WebUI will not open:** check that the container is running, its logs, and the

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -162,6 +162,8 @@ container is recreated. We run no image-building or image-mirroring pipeline.
 Updates remain on the selected CPU/CUDA tag; they do not switch backend, upgrade
 host drivers, update model weights, or safely migrate every installation setting.
 Template changes are not a universal migration mechanism for installed containers.
+The README section [Already installed?](../README.md#already-installed) lists
+the template changes that an existing installation can adopt by hand.
 An existing installation is not automatically migrated to UID `99` / GID `100`
 by this template change. Review its current identity and storage before adopting
 the setting; preserve the matching identity throughout an image update/rollback.

diff --git a/docs/MAINTAINER.md b/docs/MAINTAINER.md
@@ -1,77 +1,135 @@
 # Maintainer guide
 
 For installation and everyday use, start with the [README](../README.md).
-This page collects project scope, validation history, release process and sources
-previously in the README. The [release review](RELEASE-REVIEW.md) is the current
-status tracker; detailed experiment reports remain in this docs directory.
+This page holds project scope, fixed decisions, the release process and the
+maintainer checks. [The release review](RELEASE-REVIEW.md) is the status
+tracker. Dated experiment reports live in `docs/reports/`.
 
-## Validation and submission context
+## Status and evidence
 
 The current submission state, completed evidence and remaining gates live in
 [the release review](RELEASE-REVIEW.md). Do not repeat that status here.
 
-CPU, CUDA 12 and CUDA 13 passed isolated Pocket TTS testing on one
-Unraid host. Native Docker `--user=99:100` resolved the initial model-folder
-permission failure. The [September 12 CPU retest](CPU-RETEST-20260912.md) passed
+CPU, CUDA 12 and CUDA 13 passed isolated Pocket TTS testing on one Unraid host.
+Native Docker `--user=99:100` resolved the initial model-folder permission
+failure. The [September 12 CPU retest](reports/CPU-RETEST-20260912.md) passed
 short-text, streaming and restart checks on a fixed official image. Controlled
 CUDA 13 recreation, image update and rollback passed within their documented
 scope. These are not full Community Apps release acceptance, and portal approval
 does not establish runtime compatibility.
 
-The repository is `lozenge0/audio-cpp-unraid`, with GitHub Issues for support.
-The template requests both **AI** and **Tools** categories.
+## Decisions fixed by the project owner
+
+- Project: audio.cpp for Unraid. Repository: `lozenge0/audio-cpp-unraid`.
+  Support: repository GitHub Issues.
+- Template: CPU base with CUDA 12 and CUDA 13 branches, all on unmodified
+  upstream images and moving upstream tags. No custom image, fork, runtime
+  wrapper, personal code or configuration.
+- Every variant runs as Docker `--user=99:100`. No ownership-changing helper
+  and no `PUID`/`PGID` mapping.
+- Standard Unraid controls only, plus optional upstream CLI arguments or a
+  user-owned JSON file.
+- Licences: MIT for integration files and CC0 1.0 for the icon, approved on
+  2026-09-12. The artwork dedication covers only the rights the owner holds.
+  The owner confirmed the artwork came from their own prompts with Claude/AI.
+- Versions: `v0.1.0` is the first beta release. `v1.0.0` is reserved for a
+  validated stable integration. Integration versions do not describe the
+  upstream audio.cpp version inside the container.
+- Upstream now builds a Vulkan image. A Vulkan branch needs its own integration
+  and hardware review before it is added.
 
 ## Scope and layout
 
 This is a standalone integration repository with its own clean Git history.
-It was prepared separately from the upstream audio.cpp source; no upstream
-checkout/history belongs here. Do not build an application image from this
+It was prepared separately from the upstream audio.cpp source. No upstream
+checkout or history belongs here. Do not build an application image from this
 repository. Nothing here changes an existing personal installation.
 
 - `templates/audio-cpp.xml`: one app with CPU base and two CUDA branches.
 - `ca_profile.xml`: Community Apps repository metadata.
-- `assets/`: supplied community integration icon and provenance/licensing notes.
-- `docs/PLAN.md`: implementation stages and approval boundaries.
+- `assets/`: community integration icon and provenance/licensing notes.
+- `docs/CONFIGURATION.md`: detailed deployment and tuning notes.
+- `docs/RELEASE-REVIEW.md`: current status, evidence and remaining gates.
 - `docs/VALIDATION.md`: acceptance checklist and evidence requirements.
-- `docs/RELEASE-REVIEW.md`: current release status and publication boundaries.
-- [Configuration reference](CONFIGURATION.md): detailed deployment and tuning notes.
-- `tests/`: maintainer-only structural checks; never shipped into the container.
+- `docs/reports/`: dated experiment reports. They record what was known at
+  the time and are not updated later.
+- `tests/`: maintainer-only structural checks, never shipped into the container.
 - `.github/`: read-only CI checks and Dependabot updates for the CI actions only.
 
-The project is called **audio.cpp for Unraid**; the template/container name is
-`audio-cpp`. Integration versions (`v0.1.0`, eventually `v1.0.0`) do not represent
-the version of upstream audio.cpp running inside the container. This integration
-does not imply endorsement by the audio.cpp maintainers or Unraid.
+The project is called **audio.cpp for Unraid**. The template and container name
+is `audio-cpp`. This integration does not imply endorsement by the audio.cpp
+maintainers or Unraid.
 
-## Maintainer checks and publishing
+## Maintainer checks
 
-Run from the repository root (not this docs directory), with Python 3.9+:
+Run from the repository root, with Python 3.9 or later:
 
 ```sh
 python3 -m unittest discover -s tests -v
 ```
 
-These checks validate local structural/design invariants, not the CA parser,
-live registry availability, hardware, browser workflows, or installation success.
-Follow [the release review](RELEASE-REVIEW.md) and
-[full acceptance checklist](VALIDATION.md) before any release.
+These checks validate local structural invariants, not the CA parser, live
+registry availability, hardware, browser workflows or installation success.
+The publication test holds the exact list of files that belong in the
+repository. If you add a file, review its publication safety first, then add
+it to that list.
+
+GitHub Actions runs the same tests on pushes, pull requests and manual
+dispatch. The workflow uses GitHub-hosted Ubuntu, a read-only repository token,
+commit-pinned official actions and no persisted checkout credentials. There are
+no application builds, deployments, artifact uploads, scheduled server tasks,
+custom secrets or access to Unraid. Do not add an Unraid SSH key or API token to
+repository secrets. Dependabot proposes weekly updates for the CI actions only.
+It does not track audio.cpp releases or merge its own pull requests.
+
+Keep these repository settings:
+
+- Default branch `main` is protected by the validation status check. Force
+  pushes and deletion are blocked.
+- Issues are enabled. Auto-merge is disabled.
+- The Actions token is read-only, Actions cannot approve pull requests, and
+  workflows from outside contributors need approval.
+- Private vulnerability reporting, secret scanning and push protection are on.
 
-The GitHub Actions workflow runs these tests on pushes, pull requests
-and manual dispatch, with no custom secrets, image builds or server access.
-Dependabot proposes CI action updates for review, not container updates.
 See [contribution guidance](../CONTRIBUTING.md) and
 [security reporting](../SECURITY.md).
 
-Next verify catalog visibility and the public branch-selection/install flow,
-review tested images and complete or explicitly defer outstanding lifecycle
-checks. Rerun CA Validate/Scan after meaningful XML changes. Follow the
-[GitHub publishing checklist](PUBLISHING.md). Never publish the surrounding
-audio.cpp checkout. Portal approval is not full deployment acceptance.
-
-When a template change affects installed users, add a dated entry to the
-`Changes` field in `templates/audio-cpp.xml`. Community Apps shows that field
-as the app changelog. Docker Manager does not refresh installed templates, so
-the entry must say what an existing user needs to change by hand.
+## Release process
+
+1. Run the maintainer checks. For a template change, also run CA Validate/Scan
+   against the public repository and resolve findings.
+2. If a change affects installed users, add a dated entry to the `Changes`
+   field in `templates/audio-cpp.xml`. Community Apps shows that field as the app
+   changelog. Docker Manager does not refresh installed templates, so the entry
+   must say what an existing user needs to change by hand. Mirror the entry in
+   `CHANGELOG.md`.
+3. Update the [release review](RELEASE-REVIEW.md) status section and, for
+   runtime changes, the [validation checklist](VALIDATION.md). Record runtime
+   tests in a dated report under `docs/reports/`. CI has no Unraid server or GPU.
+4. Open a pull request and merge it after CI passes.
+5. Once the app is visible in the public catalog and the open release gates are
+   complete or explicitly deferred, tag `v0.1.0` and create a GitHub release
+   from the changelog.
+
+Never publish the surrounding audio.cpp checkout. If the repository is ever
+restaged, start from a new directory and make sure that
+`git rev-parse --show-toplevel` points at it. Copy only the files in the
+publication list. Use the GitHub noreply commit identity and a fresh root
+commit. Never force-push.
+
+## Ongoing maintenance
+
+Upstream images update independently. Monitor changes to launch arguments,
+permissions, storage, driver requirements and security. If one of them
+changes, update the template and docs. Changes that affect existing
+installations need explicit migration instructions in the README and in the
+`Changes` field. No remote access to other users' servers is required.
+Release-only image tags are a separate upstream request.
+
+Testing on the owner's server follows fixed rules. Use a separate container
+name, an unused port and a fresh appdata directory. Never replace the personal
+container. Never run a host-wide updater to test one container. Make sure that
+free disk space is enough before you pull more CUDA images.
 
 ## Primary references
 
@@ -84,12 +142,12 @@ the entry must say what an existing user needs to change by hand.
 - [Unraid container settings](https://docs.unraid.net/unraid-os/using-unraid-to/run-docker-containers/managing-and-customizing-containers/)
 - [NVIDIA container GPU selection](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html)
 - [CUDA 13 compatibility changes](https://docs.nvidia.com/cuda/archive/13.0.0/cuda-toolkit-release-notes/index.html)
+- [GitHub workflow security guidance](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions)
 
 ## Licensing
 
-The [MIT licence](../LICENSE) applies to this integration's templates, documentation
-and tests, not upstream software, third-party dependencies or model weights.
-The icon is separately dedicated under CC0 1.0 Universal, to the extent the owner
-holds applicable rights; see [artwork provenance and terms](../assets/README.md).
-The owner approved these choices and subsequent GitHub draft publication on
-2026-09-12.
+The [MIT licence](../LICENSE) applies to this integration's templates,
+documentation and tests, not to upstream software, third-party dependencies or
+model weights. The icon is separately dedicated under CC0 1.0 Universal, to the
+extent the owner holds applicable rights. See
+[artwork provenance and terms](../assets/README.md).