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

2026-09-26 17:08:02 +02:00
parent 13fcb70a27
commit c8809e56b2
6 changed files with 105 additions and 9 deletions
@@ -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.