---
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.
- If tooling required for a relevant test or check is missing, tell the user which tool is needed and prompt them to install it locally instead of silently skipping the 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.