Update environment example, enhance copilot instructions, and add release skills documentation

.github/copilot-instructions.md

@@ -1,7 +1,27 @@
-# Faerro KB project notes
+# Faerro KB project instructions
 
-- Keep audio, transcripts, and indexes on infrastructure controlled by the user.
-- Never add a cloud speech, LLM, or geocoding dependency.
-- Preserve original audio and raw transcripts when adding correction workflows.
-- PWA uploads must remain queued until the API acknowledges durable storage.
-- Treat iOS background execution and browser storage as best-effort; communicate limits in the UI/docs.
+## Product goal
+
+Faerro KB is a self-hosted voice-note inbox designed for an iPhone-installed web app. The browser records locally first; the user's server stores audio and searchable transcripts. Favor privacy, reliable recovery, and straightforward self-hosting over hosted convenience services. The initial deployment has no login layer, so keep it behind the user's VPN/firewall and be explicit about that limitation.
+
+## Non-negotiable data and privacy rules
+
+- Keep audio, transcripts, indexes, models, and backups on infrastructure controlled by the user.
+- Never add a cloud speech, LLM, geocoding, analytics, or other third-party processing dependency without explicit user direction.
+- Preserve original audio and raw transcripts. A correction workflow may add a proposal or corrected text, but must not silently replace either source.
+- A PWA upload stays queued on the device until the API confirms durable storage. Do not treat a request starting, a network response without success, or a local UI update as acknowledgement.
+- Treat iOS background execution and browser storage as best-effort. Communicate the limits in relevant UI and documentation; do not promise background uploads or permanent browser retention.
+- Keep local transcription services private to the Docker network. Do not expose them publicly or send recordings to external services.
+- Avoid logging audio, transcript contents, credentials, or other sensitive material.
+
+## Engineering practices
+
+- Preserve the local-first capture and retry behavior when changing the PWA, API, or service worker. Prefer additive, recoverable data changes.
+- Follow the existing small stack: FastAPI, SQLite/FTS5, and the vanilla JavaScript PWA. Avoid new dependencies unless they solve a real need and can run on the user's infrastructure.
+- Keep changes scoped. Inspect the owning code path, add or update focused tests for behavior changes, and run the narrowest relevant checks available.
+- Update README/UI documentation when behavior, deployment, security, backup, or platform limitations change. Do not claim a capability that iOS or browsers cannot guarantee.
+- Preserve user data and existing local changes. Do not perform destructive migrations or remove stored recordings without explicit confirmation and a recovery path.
+
+## Releases
+
+Git tags are the source of truth for image versions. The publish script requires the checked-out commit to have an exact `MAJOR.MINOR.PATCH` tag, optionally prefixed with `v`. Do not invent a version for a future release; use the version explicitly selected by the user or ask. Publishing pushes both the versioned image and `latest` to the configured private Gitea registry, so confirm registry authentication is available before treating a release as complete.

.github/skills/faerro-kb-development/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: faerro-kb-development
+description: Implement or review Faerro KB product changes while preserving local-first capture, user-controlled storage, privacy, and recoverable data behavior.
+---
+
+# Faerro KB Development
+
+Use this skill for feature work, bug fixes, and reviews in this repository. The repository's `.github/copilot-instructions.md` is the source of truth for product goals and non-negotiable guardrails.
+
+## Before changing behavior
+
+1. Trace the owning path in `app/main.py`, `frontend/app.js`, `frontend/sw.js`, or the relevant deployment file. Read the nearby tests and documentation when present.
+2. Identify what happens to the original recording, raw transcript, browser queue, server acknowledgement, and retry behavior. Keep recovery possible across offline periods and failures.
+3. State the narrow behavior change and a focused check that could disprove it before editing.
+
+## Implementation requirements
+
+- Keep audio processing and persistence on user-controlled infrastructure. Do not introduce hosted AI, speech, geocoding, analytics, or storage services.
+- Keep original audio and raw transcription immutable when adding transcript edits or correction suggestions.
+- Remove an upload from the browser queue only after the API confirms durable storage. Handle failed, interrupted, and retried requests without losing the local copy.
+- Treat browser persistence and iOS background activity as best-effort. Make limitations visible in relevant user-facing documentation or UI.
+- Keep transcription services private to the Docker network. Preserve the existing VPN/firewall deployment assumptions and explain the lack of authentication where relevant.
+- Prefer focused changes consistent with FastAPI, SQLite/FTS5, and the vanilla JavaScript PWA. Avoid unrelated refactors and new dependencies.
+
+## Verification and handoff
+
+- Add or update focused tests for changed behavior, especially queue acknowledgement, retries, and data-preserving transcript workflows.
+- Run the narrowest relevant test, compile, or lint check available, then document any important limitation or unverified check.
+- Update `README.md` when setup, deployment, backups, privacy, or platform behavior changes.
+- Never claim that iOS guarantees background execution or that browser storage is permanent.

.github/skills/faerro-kb-release/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: faerro-kb-release
+description: Prepare and publish a versioned Faerro KB container image to the private Gitea registry.
+---
+
+# Faerro KB Release
+
+Use this skill when asked to tag or publish a Faerro KB image. The release procedure is defined by `README.md` and `scripts/publish-image.sh`.
+
+## Procedure
+
+1. Check the worktree and identify the exact commit being released. Do not tag unrelated or unreviewed changes.
+2. Use the release version explicitly supplied by the user. If no version was supplied and no approved version is established in the task, ask instead of guessing. Tags must be exact `MAJOR.MINOR.PATCH`, optionally prefixed with `v`.
+3. Check that the chosen tag is unused and attach it to the intended commit.
+4. Confirm Docker is available. For non-interactive authentication, put `GITEA_USERNAME` and a package-write `GITEA_TOKEN` in the ignored `.env` file. The script parses only these keys and sends the token through Docker's `--password-stdin`; never put credentials in tracked files, command-line arguments, or chat. Without these settings it relies on Docker's existing login credentials.
+5. Run `./scripts/publish-image.sh` from the repository. It builds, logs in when `.env` credentials are set, and pushes both the versioned tag and `latest`.
+6. Report the tagged commit, image tags, and actual build/push result. A successful local build is not a successful release if either registry push fails.
+
+Do not force-move an existing tag, create or push Git tags to a remote unless requested, or claim publication succeeded without successful registry pushes.