prepare-experimental-source-release

name	prepare-experimental-source-release
description	Prepare Voice Layer for an experimental public source release. Use when publishing the repository, validating the source-first release boundary, documenting build-from-source expectations, or troubleshooting contributor build and local llama-server setup. This workflow deliberately does not create GitHub Releases or distribute binary assets.

Prepare Experimental Source Release

Publish Voice Layer as experimental source code that users build on their own Macs. The public deliverable is the repository and its Git history, not a downloadable application.

Default policy and stop boundary

• Prefer a public repository and the existing build-from-source quick start. Users install the prerequisites, run their own llama-server, and build or run Voice Layer locally.
• Do not create a GitHub Release object, attach a .app, .dmg, .zip, checksum, or other binary asset, or configure a binary publishing workflow. Do not run gh release create.
• Do not set up Apple Developer credentials, Developer ID signing, notarization, GitHub Actions release secrets, or release-environment approvals for this workflow. Those are only relevant if the product decision changes to distributing prebuilt macOS software.
• A Git tag may be useful for source provenance only after explicit approval. It is not a request to create a GitHub Release or publish an installer.
• Treat the repository's current source, tests, and documentation as authoritative. Do not infer binary-release readiness from a successful source preflight.

References and product boundary

Read these before changing publication material or advising users:

• README.md: macOS prerequisites, source quick start, the three supported local server aliases, and the explicit user-managed server boundary.
• CONTRIBUTING.md: supported validation commands and prohibited tracked runtime data.
• PRIVACY.md and docs/chatgpt-subscription.md: local-first behavior and the explicit, experimental ChatGPT opt-in.
• SECURITY.md: safe vulnerability reporting. Never ask a user to paste a token, transcript, credential, or private file into an issue.
• THIRD_PARTY_NOTICES.md: model and reference-audio terms. In particular, Pocket's upstream archive is treated as non-commercial; do not make commercial-use claims for it.
• docs/model-integrations.md: curated model IDs, cache behavior, local server setup, and the deferred sherpa-onnx native-build limitation.
• justfile: the supported just install, just test, just check, just dev, and just bundle commands.

The default Local provider sends visible text only to the user's localhost llama-server; microphone audio and local speech runtimes remain on-device. The optional ChatGPT provider sends visible conversation text only when the user explicitly selects it. Preserve that distinction in all public copy.

Preflight before making the repository public

1. Establish the exact source state without modifying it:

   git status --short --branch
   git rev-parse HEAD
   git diff --check
   git remote -v
   

   Preserve unrelated changes. Do not reset, clean, broad-stage, push, or change repository visibility without explicit user authorization.

2. Confirm that documentation still tells the source-first truth:

   • README requires macOS, Bun, Rust/Tauri prerequisites, and just.
   • README says users manage their own LLM server and model weights.
   • License, privacy, security, contribution, and third-party notices are present and linked.
   • No page promises a signed, notarized, supported, or one-click installer.

3. Check the intended tracked files without printing potential secrets:

   git ls-files | rg -i '\.(env|pem|p12|key|mobileprovision|sqlite|db|wav|mp3|gguf|onnx|dmg|app|zip)$'
   git check-ignore -v .env credentials.json transcript.json 2>/dev/null || true
   

   Review any tracked result by filename and purpose. If a credential, private key, user transcript, downloaded model, generated bundle, or machine-local configuration is found, stop publication. Do not echo its contents into a terminal, issue, chat, commit, or release note. Remove and rotate it through a separately approved remediation plan.

4. Run the supported credential-free checks:

   just test
   just check
   bun audit
   

   Record failures accurately. A passing check is source evidence; it is not signing, notarization, fresh-device, live-microphone, or audible-playback evidence.

5. Before the first public push, obtain explicit approval for the exact remote, branch, and visibility. Then push only the reviewed source files. Do not create a GitHub Release or upload a build artifact as part of this skill.

Known source-build limitation

sherpa-onnx currently downloads its matching native static archive during a normal Rust source build. This does not prevent publishing source, but it means a clean source build requires network access and is not yet fully reproducible offline.

When that fetch fails:

1. Preserve the first complete error; it identifies whether the problem is DNS/network access, an upstream archive, a toolchain mismatch, or a linker error.
2. Confirm the normal source preflight with just check; do not repeatedly rerun an unchanged command without new evidence.
3. Check the contributor's network/proxy policy and current Rust toolchain. Do not ask them to disable security controls or copy credentials.
4. If they already have a trusted, matching native archive, they may configure SHERPA_ONNX_LIB_DIR according to docs/model-integrations.md. Do not invent a path or substitute an unverified library.
5. The maintainer-level fix is to vendor the exact archive with a checksum, set SHERPA_ONNX_LIB_DIR for builds, and prove a clean-clone offline build. That is separate future work, not a reason to claim a binary release today.

User troubleshooting

Prerequisites or build failure

Ask the user for the command that failed and its first error, plus macOS, Bun, Rust, and Tauri prerequisite versions. Start with:

command -v bun rustc cargo just
bun --version
rustc --version
just --version
just install
just check

Point missing macOS tooling to the Tauri prerequisites linked in README.md. Keep fixes scoped to the reported prerequisite or first error; do not delete Cargo, Bun, model, or application-data caches as a generic repair.

App runs but Local Chat cannot reply

Voice Layer never starts or configures llama-server. Ask the user to inspect their own server in a separate terminal:

curl -fsS http://127.0.0.1:8080/health
curl -fsS http://127.0.0.1:8080/v1/models

Require one advertised alias that exactly matches the selected app model: glm47-flash, qwen36-27b, or gemma4-e4b. If the service is absent or the alias differs, direct the user to their own llama.cpp/server setup rather than starting, stopping, downloading, or reconfiguring it on their behalf.

Speech model first-use or microphone issue

First use of a selected speech model may download an exact pinned artifact only after the user starts the relevant action. Preserve the visible error and verify disk/network availability before retrying. Do not manually add model files, delete partially downloaded assets, or reset microphone permissions without the user's explicit approval. For microphone failures, verify the macOS Privacy & Security microphone permission and then reproduce the one reported operation (Chat recording or Live).

Optional ChatGPT issue

ChatGPT is an experimental explicit opt-in, not a required source-build dependency. Keep Local as the troubleshooting baseline. Refer to docs/chatgpt-subscription.md; never request an API key, browser session, account token, or copied credential.

Issue and handoff quality

For a safe public issue, request only:

• the public commit hash and command run;
• macOS, Bun, Rust, and just versions;
• a redacted first error and whether it happens before or after the app opens;
• selected local model alias and whether /health and /v1/models succeed;
• whether the issue concerns source build, Local Chat, first-use speech, microphone permission, or the optional ChatGPT path.

Never request model weights, chat history, raw audio, OAuth state, API keys, credentials, absolute private paths, or copied application data. Route security reports through SECURITY.md rather than a public issue.

Completion receipt

Report the repository commit, dirty-state decision, exact checks run and their results, documentation reviewed, remote/visibility approval, and any known limitations. State explicitly: “Published as experimental source only; no GitHub Release or binary asset was created.”