faerro-kb/.github/copilot-instructions.md

Faerro KB project instructions

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.