# 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.
- 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 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.