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.
@@ -0,0 +1,19 @@
+---
+name: faerro-kb-release
+description: Prepare and publish a versioned Faerro KB container image to the private Gitea registry.
+---
+
+# Faerro KB Release
+
+Use this skill when asked to tag or publish a Faerro KB image. The release procedure is defined by `README.md` and `scripts/publish-image.sh`.
+
+## Procedure
+
+1. Check the worktree and identify the exact commit being released. Do not tag unrelated or unreviewed changes.
+2. Use the release version explicitly supplied by the user. If no version was supplied and no approved version is established in the task, ask instead of guessing. Tags must be exact `MAJOR.MINOR.PATCH`, optionally prefixed with `v`.
+3. Check that the chosen tag is unused and attach it to the intended commit.
+4. Confirm Docker is available. For non-interactive authentication, put `GITEA_USERNAME` and a package-write `GITEA_TOKEN` in the ignored `.env` file. The script parses only these keys and sends the token through Docker's `--password-stdin`; never put credentials in tracked files, command-line arguments, or chat. Without these settings it relies on Docker's existing login credentials.
+5. Run `./scripts/publish-image.sh` from the repository. It builds, logs in when `.env` credentials are set, and pushes both the versioned tag and `latest`.
+6. Report the tagged commit, image tags, and actual build/push result. A successful local build is not a successful release if either registry push fails.
+
+Do not force-move an existing tag, create or push Git tags to a remote unless requested, or claim publication succeeded without successful registry pushes.