chore/docs+test+desktop: docs governance refresh, e2e stabilization, and auth/api hardening

.env.example

@@ -8,4 +8,13 @@ OIDC_AUDIENCE=your-api-audience
 # Optional:
 # OIDC_SEND_AUDIENCE_IN_AUTHORIZE=1
 # OIDC_API_BEARER_TOKEN_SOURCE=access_token
-# OIDC_ALLOW_INSECURE_TOKEN_STORAGE=1
+# OIDC_ALLOW_INSECURE_TOKEN_STORAGE=1
+
+# Bring-your-own secured API endpoint template for the `call.secure-endpoint` operation.
+# Must be HTTPS and include any required path placeholders.
+# Example: https://your-api.example.com/users/{{user_id}}/profile
+# API_SECURE_ENDPOINT_URL_TEMPLATE=
+#
+# Optional JSON mapping of endpoint placeholders to JWT claim paths.
+# Example: {"user_id":"sub","tenant_id":"org.id"}
+# API_SECURE_ENDPOINT_CLAIM_MAP=

.github/pull_request_template.md

@@ -1,8 +1,25 @@
 ## Summary
 
--
+- What changed:
+- Why this change is needed:
+- Risk level (low/medium/high):
 
-## Checklist
+## Change Groups
+
+- Docs / Governance:
+- Frontend / UX:
+- Desktop Main / Preload / Contracts:
+- CI / Tooling:
+
+## Validation
+
+- [ ] `pnpm nx run contracts:test`
+- [ ] `pnpm nx run desktop-main:test`
+- [ ] `pnpm nx run renderer:build`
+- [ ] `pnpm nx run desktop-main:build`
+- [ ] Additional checks run:
+
+## Engineering Checklist
 
 - [ ] Conventional Commit title used
 - [ ] Unit/integration tests added or updated
@@ -13,9 +30,14 @@
 
 ## Security (Required For Sensitive Changes)
 
-- [x] Security review completed
-- [x] Threat model updated or N/A explained
+IMPORTANT:
+
+- If this PR touches `apps/desktop-main/**`, `apps/desktop-preload/**`, `libs/shared/contracts/**`, `.github/workflows/**`, or `docs/02-architecture/security-architecture.md`, the two items below MUST be checked to pass CI.
+
+- [ ] Security review completed
+- [ ] Threat model updated or N/A explained
 
 ### Security Notes
 
-- ## N/A rationale (when no threat model update is needed):
+- Threat model link/update:
+- N/A rationale (when no threat model update is needed):

.gitignore

@@ -49,6 +49,7 @@ vitest.config.*.timestamp*
 
 FILE_INDEX.txt
 FEEDBACK.md
+TASK.md
 
 # local environment configuration
 .env*

.husky/pre-commit

@@ -1,2 +1,3 @@
 pnpm lint-staged
 pnpm i18n-check
+pnpm docs-lint

CURRENT-SPRINT.md

@@ -0,0 +1,97 @@
+# Current Sprint
+
+Sprint window: 2026-02-13 onward  
+Owner: Platform Engineering + Frontend  
+Status: Active
+
+## Sprint Goal
+
+Reduce risk in privileged runtime boundaries by completing the P0 refactor set while preserving existing behavior.
+
+## In Scope (Committed)
+
+- `BL-016` Refactor desktop-main composition root and IPC modularization.
+- `BL-017` Refactor preload bridge into domain modules with shared invoke client.
+- `BL-018` Introduce reusable validated IPC handler factory in desktop-main.
+
+## Stretch Scope (If Capacity Allows)
+
+- `BL-023` Expand IPC integration harness for preload-main real handler paths.
+- `BL-025` Strengthen compile-time typing for API operation contracts end-to-end.
+
+## Out Of Scope (This Sprint)
+
+- `BL-019`, `BL-020`, `BL-021`, `BL-022`, `BL-024`.
+
+## Execution Plan (Coherent + Individually Testable)
+
+### Workstream A: `BL-016` desktop-main modularization
+
+1. `BL-016A` Extract non-IPC concerns from `apps/desktop-main/src/main.ts`.
+
+- Scope: move window creation, navigation hardening, environment/version resolution, and runtime-smoke setup into dedicated modules.
+- Done when: `main.ts` is composition-focused and behavior remains unchanged.
+- Proof:
+  - `pnpm nx build desktop-main`
+  - `pnpm nx test desktop-main`
+
+2. `BL-016B` Extract IPC handlers into per-domain modules.
+
+- Scope: move handlers into `ipc/handlers/*` while retaining channel and response behavior.
+- Done when: handler registration is centralized and each domain handler is isolated.
+- Proof:
+  - `pnpm nx build desktop-main`
+  - `pnpm nx test desktop-main`
+
+### Workstream B: `BL-018` validated handler factory
+
+3. `BL-018A` Add reusable handler wrapper.
+
+- Scope: create shared factory for sender authorization + schema validation + typed failure envelope mapping.
+- Done when: at least handshake/app/auth handlers use factory with no behavior drift.
+- Proof:
+  - `pnpm nx test desktop-main`
+  - `pnpm nx build desktop-main`
+
+4. `BL-018B` Migrate remaining handlers to wrapper.
+
+- Scope: migrate dialog/fs/storage/api/updates/telemetry handlers.
+- Done when: all privileged handlers use one validation/authorization path.
+- Proof:
+  - `pnpm nx test desktop-main`
+  - `pnpm nx build desktop-main`
+
+### Workstream C: `BL-017` preload modularization
+
+5. `BL-017A` Extract invoke client core.
+
+- Scope: move correlation-id generation, timeout race handling, result parsing, and error mapping into shared `invoke` module.
+- Done when: existing namespaces call shared invoke core.
+- Proof:
+  - `pnpm nx build desktop-preload`
+  - `pnpm nx build desktop-main`
+
+6. `BL-017B` Split preload API by domain.
+
+- Scope: split app/auth/dialog/fs/storage/api/updates/telemetry methods into domain modules and compose into exported `desktopApi`.
+- Done when: `apps/desktop-preload/src/main.ts` becomes thin composition only.
+- Proof:
+  - `pnpm nx build desktop-preload`
+  - `pnpm nx build desktop-main`
+
+### Cross-cut verification gate (after each merged unit)
+
+- `pnpm unit-test`
+- `pnpm integration-test`
+- `pnpm runtime:smoke`
+
+## Exit Criteria
+
+- P0 items merged through PR workflow with no security model regressions.
+- Existing CI quality gates remain green.
+- Docs updated for any changed project structure or conventions.
+
+## Progress Log
+
+- 2026-02-13: Sprint initialized from governance backlog with P0 focus (`BL-016`, `BL-017`, `BL-018`).
+- 2026-02-13: Added PR-sized execution breakdown with per-unit proof commands.