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.
• If tooling required for a relevant test or check is missing, tell the user which tool is needed and prompt them to install it on the local machine; do not silently skip the check.
• 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.
• At the end of each chat, check whether it introduced durable project requirements, decisions, workflows, or corrections missing from these instructions or a relevant skill. Update the narrowest relevant guidance file when the change is clearly reusable and within the user's authorized scope; otherwise note the gap and ask before expanding scope. Do not record transient task details or sensitive information.

Releases

Git tags are the source of truth for image versions. The publish script requires a clean worktree, chooses the next version from existing MAJOR.MINOR.PATCH tags, and creates an annotated local tag on the checked-out commit. Do not invent a version for a future release; use the script's next-version behavior or the version explicitly selected by the user. The script does not push Git tags. 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.