The tree carried uncommitted work from several areas (web push, mobile screens, admin charts, test-hygiene cleanup, CI and map docs). It is landed as one commit so the release pipeline can start from a clean tree; the desktop transcript-correction behaviour shipped in the previous commit and is unchanged here.
11 KiB
AGENTS.md — D3RO Voice
Operating guide for any AI agent (or human) working in this repository. Read this first. It tells you where the infrastructure map lives and what you must update when you change the product.
1. What this repo is
D3RO Voice is a multi-platform AI voice assistant monorepo:
apps/desktop— Electron desktop app (local-first: SoX + faster-whisper sidecar + Ollama + SQLite)apps/web— Next.js cloud consoleapps/mobile-rn— React Native product mobile app (cloud-first; active)apps/api-server— ASP.NET Core 10 AI proxy + back office backendapps/admin— Next.js admin back officeserver/supabase— Postgres + RLS + Auth + Storage + ~27 Deno Edge Functions (canonical product backend)server/cloudflare-worker— edge gatewaysite/— landing/marketing/legal sitepackages/*— shared@d3ro/core,ui,ui-native,i18n,api-client
Full detail: docs/map/01-system-overview.md.
2. The map — read before you work
docs/map/ is the authoritative feature & infrastructure map. Use it to learn
what infrastructure exists and how far each feature is developed before writing code.
Start at docs/map/00-index.md. Key files:
| Need | File |
|---|---|
| Map index + status legend + how to use | docs/map/00-index.md |
| Product / IA / identity / pipeline | docs/map/01-system-overview.md |
| Repo layout, build, CI/CD, Docker, deploy | docs/map/02-infrastructure.md |
| Shared packages | docs/map/03-shared-packages.md |
| Desktop services/IPC/pages | docs/map/04-desktop-app.md |
| Web routes/components | docs/map/05-web-app.md |
| Mobile screens/features | docs/map/06-mobile-app.md |
| .NET API | docs/map/07-api-server.md |
| Admin console | docs/map/08-admin-console.md |
| Supabase + Cloudflare | docs/map/09-supabase-backend.md |
| Feature map (per platform, with status) | docs/map/10-feature-catalog.md |
| Gaps / backlog / external blockers | docs/map/11-gap-backlog.md |
| How to keep the map current | docs/map/12-update-protocol.md |
Recommended sequence for a new task:
- Read the surface doc for the area you will touch (
04–09). - Find the feature in
10-feature-catalog.mdand check its status per platform. - Check
11-gap-backlog.mdso you do not re-plan tracked work. - Do the work.
- Update the map before declaring done (see §4).
Mobile status is authoritative in docs/v3/MOBILE_APP_COMPLETION_SSOT.md; the map
mirrors and rolls it up. When they disagree, fix the SSOT first, then the map.
3. Non-negotiable repo rules
These come from CLAUDE.md and are enforced here too:
- TypeScript strict, no
any, noconsole.log(uselogger). - Services are singletons +
EventEmitter. IPC channels are${feature}:${action}from the SSOTpackages/core/src/ipc-channels.ts; wrap errors inD3ROError/ErrorCodeandIPCResult. - Theme SSOT: only
d3roPalette/d3roShadow/d3roTypo/d3roRadius; no hardcoded hex outsidetheme.ts. - i18n: use
t(); no hardcoded Korean/English strings in UI. - No
Co-Authored-Byor Claude-related wording in commits. Follow the commit format in the shell tool instructions. - Desktop GUI: do not background-launch Electron from an agent subshell (virtual desktop). Tell the user to run
run-desktop.bator an external terminal. - Audio device discovery: never
execSync(use asyncexec). - GPU: keep
app.disableHardwareAcceleration()and--disable-gpu. - Desktop: keep
app.setName('d3ro-voice')+app.setAppUserModelIdat the top; prevent dev silent exit. - Never hardcode secrets; production secrets are injected at build/CI time. Fail closed, never fake success.
- Security-first: only defensive security work.
- Tests: behavior only (no private methods, call order, or CSS classes). Test names say what breaks:
동작_시나리오_기대. E2E is*.spec.ts(Playwright) and only for the critical journeys; everything else is*.test.ts(x). Never weaken/delete/skip a test to get green. - Protected journeys (
apps/desktop/tests/e2e/{navigation,settings,onboarding,customer-support,records}.spec.ts,apps/web/e2e/smoke.spec.ts): do not edit assertions without a product-behavior reason in the commit body. - Test hygiene gate:
npm run test:hygienerejects.only, reason-less.skip(), trivial assertions,isVisible()-gated assertions, machine-specific paths,waitForTimeout, and.e2e.test.tsnames.
Build/test commands: docs/map/02-infrastructure.md §3. Root: npm run typecheck, npm run test, npm run lint, npm run test:hygiene. Mobile: npm --prefix apps/mobile-rn run lint|typecheck|test. TDD policy: docs/tdd-red/06-repo-application.md.
4. MANDATORY: keep the map updated
Feature change ⇒ map change, in the same commit / PR. A feature is not done until the map reflects it.
Whenever you add, remove, change, or defer a feature, or touch infrastructure, you MUST update the map:
- Edit
docs/map/10-feature-catalog.md(status per surface + notes/anchors). - Edit the relevant surface doc (
04–09) if you changed services, routes, screens, IPC channels, tables, Edge Functions, or build/CI. - Edit
docs/map/11-gap-backlog.md:- resolved gap →
[x]+ date + evidence; - newly deferred item → new row + next step;
- cleared external blocker →
[x]+ evidence.
- resolved gap →
- Reconcile with
docs/v3/MOBILE_APP_COMPLETION_SSOT.mdfor mobile changes. - Update
docs/map/02-infrastructure.mdand the00-index.mdheader dates when build/release/CI or the product version changes.
Full procedure and templates: docs/map/12-update-protocol.md.
Status semantics: [x] verified · [~] partial/unverified · [ ] planned/absent · [!] blocked externally · [-] N/A. Never mark [x] on typecheck alone.
5. Definition of done (feature work)
- Code implemented, wired end-to-end (no TODOs / placeholders / fake success).
- Tests added/updated and passing; lint/typecheck clean on the touched scope.
npm run test:hygieneclean; new behavior has a test that fails for the expected reason before the fix.- Relevant surface doc (
04–09) updated if interfaces changed. 10-feature-catalog.mdrow updated (status per platform + anchors).11-gap-backlog.mdupdated (closed/opened/external).- Mobile SSOT reconciled if mobile was touched.
- No secrets committed; fail-closed preserved.
6. Update & release system
Desktop auto-update runs electron-updater against the Forgejo feed
https://git.chanpaca.net/api/packages/yunchan/generic/d3ro-voice/latest.
The installer is unsigned (no Authenticode yet), so latest.yml is signed with an
Ed25519 key and the app verifies the downloaded installer against it before
installing (apps/desktop/src/main/update-signature.ts). The GitLab registry mirror
was retired in 2026-10. Full evaluation:
docs/deployment/update-system-assessment.md.
To ship a desktop release, run one command on main with a clean tree:
npm run release -- patch # fix → 1.9.0 → 1.9.1
npm run release -- minor # feat → 1.9.0 → 1.10.0
npm run release -- --resume # continue after a failed build/publish/push
It bumps the version, drafts the CHANGELOG section if missing (write it by hand first for user-facing notes), runs the gates, commits + tags, builds, signs, publishes, re-verifies the public feed, then pushes. Existing installs pick it up on their next check (15 s after launch, then every 4 h).
These files move together and are enforced by npm run release:metadata:test:
| Concern | SSOT |
|---|---|
| runtime feed + channels | apps/desktop/src/main/update-feed.ts |
| builder publish URL | apps/desktop/electron-builder.yml |
| update policy (channels, min version, force, delta/full, rollout, kill switch) | release/update-policy.json |
| policy runtime logic | apps/desktop/src/main/update-policy.ts |
| one-command release | scripts/ci/release-desktop.mjs (npm run release) |
| installer build | scripts/ci/build-desktop-installer.mjs |
| publisher (sign + upload + verify) | scripts/ci/publish-forgejo-release.mjs |
| update signing key | .env D3RO_UPDATE_SIGNING_KEY (private) · release/desktop-update-public.pem == update-signature.ts |
| version SSOT | release/product-version.json |
Rules:
- Tag-only, immutable releases. Publish runs only on annotated
vX.Y.Ztags. Tags are never moved or deleted; a bad release is fixed forward with a higher patch. Same-version re-release is forbidden by SemVer. - Feed contract.
UPDATE_FEED_URL== builderpublish.url== Forgejo URL. The app verifies against the immutable<version>/latest.yml+.sig, never the mutablelatestalias. - Never rotate or lose the update signing key. Installs that embed its public key
reject releases signed by any other key; the only recovery is a manual reinstall.
Back up
.env. - Version discipline. SemVer:
feat=MINOR,fix=PATCH, breaking=MAJOR. Runnpm run version:syncwhen syncing surfaces;npm run version:checkmust be clean. - Channels.
latest(stable),beta,alpha. Stable clients never receive a prerelease unless their channel allows it. - Major vs incremental.
release/update-policy.jsondecides whether an update is mandatory (minimumSupportedVersion,forceInstallBelow) and whether to use a full installer instead of a blockmap delta (fullInstallOnMajorChange,fullInstallVersionGap).stagingPercentagelimits rollout;killSwitchstops update checks remotely. - Secrets stay fail-closed. Publishing needs
FORGEJO_TOKEN(write:package+write:repository) andD3RO_UPDATE_SIGNING_KEY; a missing or mismatched signing key fails before any upload.WIN_CSC_*Authenticode material is optional — when present electron-builder also signs the installer. - CI is the backup path.
.forgejo/workflows/release.ymlruns on the pushed tag with the same build/publish scripts and skips when the feed already has the version (the normal case afternpm run release). Sync secrets withnpm run release:secrets.
Other commands: npm run release -- minor --dry-run, npm run release:build,
npm run release:metadata:test, npm run release:forgejo:check.
7. Where deeper context lives (optional)
- Design (historical desktop architecture):
docs/design/* - Build-out phases:
docs/phases/* - Multi-platform plan:
docs/v2/* - Mobile SSOT + Play package:
docs/v3/* - Monetization:
docs/monetization-plan.md - Deployment/release:
docs/deployment/*,release/*,scripts/ci/* - Refactor policy + reports:
docs/REFACTOR_POLICY.md,docs/REFACTOR_WAVE*_REPORT.md - Project log/handoffs:
memory/*,CHANGELOG.md
Treat those as history; treat docs/map/* and the code as current.