andrea/faerro-kb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
andrea
2026-09-26 17:08:02 +02:00
parent 13fcb70a27
commit c8809e56b2
6 changed files with 105 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/copilot-instructions.md
+26 -6
View File
@@ -1,7 +1,27 @@
# Faerro KB project notes
# Faerro KB project instructions
- Keep audio, transcripts, and indexes on infrastructure controlled by the user.
- Never add a cloud speech, LLM, or geocoding dependency.
- Preserve original audio and raw transcripts when adding correction workflows.
- PWA uploads must remain queued until the API acknowledges durable storage.
- Treat iOS background execution and browser storage as best-effort; communicate limits in the UI/docs.
## 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.