Add autonomous MrTrust target integration contract

docs/agent-target-integration.md

@@ -0,0 +1,162 @@
+# Agent Target Integration Runbook
+
+Use this file when you are an agent modifying another Windows project to support MrTrust.
+
+## Non-Negotiable Goal
+
+Modify the target project so that, after a user has installed trust with `MrTrust.exe`, the target project's MrSphay-signed Windows release artifacts start and validate normally.
+
+Do not modify Windows security policy, Defender, SmartScreen, UAC, or certificate stores silently. MrTrust must remain visible, optional, and reversible.
+
+## Inputs To Read First
+
+1. Read `mrtrust.integration.json`.
+2. Read `docs/integration-prompt.md`.
+3. Inspect the target project for:
+   - build commands
+   - release artifact paths
+   - installer technology
+   - existing signing steps
+   - user-facing docs
+   - CI workflows
+
+If the target project already has equivalent trust or signing integration, update it instead of duplicating it.
+
+## Required Target Project Changes
+
+Apply every item that fits the target project:
+
+1. Add a user-facing MrTrust entry point.
+   - If the project has an installer, add an optional action named `Open MrTrust` or `Trust MrSphay signed apps`.
+   - If the project has an app settings/about/help screen, add a button or menu item that launches `MrTrust.exe`.
+   - If the project has no UI or installer, add release documentation linking to or bundling `MrTrust.exe`.
+
+2. Bundle or link the standalone executable.
+   - Preferred bundled path: `MrTrust\MrTrust.exe`.
+   - Source repository: `https://git.wilkensxl.de/MrSphay/MrTrust`.
+   - Release page: `https://git.wilkensxl.de/MrSphay/MrTrust/releases`.
+   - Do not require users to run `MrTrust.ps1`.
+   - Do not copy MrTrust source scripts into user-facing release output unless the target project explicitly ships source.
+
+3. Add signing for Windows artifacts.
+   - Sign `.exe`, `.msi`, `.dll`, `.ps1`, `.psm1`, `.psd1`, and `.cat` release artifacts.
+   - Use the public thumbprint from `mrtrust.integration.json`.
+   - Only run signing where private signing material is securely available.
+   - Do not commit `.pfx`, private keys, passwords, tokens, or signing secrets.
+
+4. Add verification.
+   - Verify the target project still builds.
+   - Verify the release output contains the app artifacts and either `MrTrust.exe` or clear MrTrust download instructions.
+   - Verify signing status where the OS/tooling is available.
+   - Verify no private signing material is tracked or present in release output.
+
+## Default Commands
+
+Open MrTrust from a bundled release:
+
+```powershell
+.\MrTrust\MrTrust.exe
+```
+
+Sign one artifact from a Windows release runner:
+
+```powershell
+.\MrTrust\MrTrust.exe sign -Path .\dist\App.exe -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
+```
+
+Sign a release directory:
+
+```powershell
+.\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
+```
+
+Check a signature:
+
+```powershell
+Get-AuthenticodeSignature .\dist\App.exe | Format-List Status,SignerCertificate,StatusMessage
+```
+
+## Installer Patterns
+
+### Inno Setup
+
+Bundle `MrTrust.exe` and add an optional task or post-install action:
+
+```ini
+[Files]
+Source: "MrTrust\MrTrust.exe"; DestDir: "{app}\MrTrust"; Flags: ignoreversion
+
+[Run]
+Filename: "{app}\MrTrust\MrTrust.exe"; Description: "Open MrTrust"; Flags: postinstall skipifsilent nowait
+```
+
+### NSIS
+
+```nsis
+SetOutPath "$INSTDIR\MrTrust"
+File "MrTrust\MrTrust.exe"
+CreateShortcut "$SMPROGRAMS\$StartMenuFolder\Open MrTrust.lnk" "$INSTDIR\MrTrust\MrTrust.exe"
+```
+
+### WiX
+
+Install `MrTrust.exe` as a regular file under an application `MrTrust` folder and expose a Start Menu shortcut or installer UI action. Do not run it silently during install.
+
+### Electron Builder
+
+Add `MrTrust\MrTrust.exe` to `extraResources`, then add a Help/About action that launches the copied executable with the platform shell API. Keep the action user-initiated.
+
+### Portable ZIP
+
+Place `MrTrust.exe` next to the app under:
+
+```text
+MrTrust\MrTrust.exe
+```
+
+Document that users should run it once before launching signed MrSphay apps if Windows does not yet trust the publisher.
+
+## CI Signing Patterns
+
+### Gitea Actions On Windows Runner
+
+```yaml
+- name: Sign Windows artifacts
+  shell: powershell
+  run: |
+    .\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
+```
+
+Use this only on a runner where the matching private code-signing certificate is installed in `Cert:\CurrentUser\My` or `Cert:\LocalMachine\My`.
+
+### Local Secure Release Machine
+
+```powershell
+.\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
+```
+
+Run this after build and before packaging.
+
+## Autonomy Rules
+
+Make reasonable target-project-specific choices without asking the user when:
+
+- artifact paths are discoverable from existing build scripts
+- installer technology is obvious from repository files
+- there is already a docs or release notes location
+- CI already has a Windows release job you can extend
+
+Stop and ask the user only when:
+
+- signing requires a private certificate that is not present and no secret mechanism exists
+- the target project has multiple conflicting release systems and no primary release path is identifiable
+- a requested change would silently alter trust or weaken security policy
+
+## Completion Checklist
+
+- Target project has a visible MrTrust user path.
+- Target project links to or bundles standalone `MrTrust.exe`.
+- Supported Windows release artifacts are signed or the blocker is explicitly documented.
+- User docs explain install and remove trust.
+- No private signing material is committed.
+- Target project build/release verification ran, or the exact blocker is documented.

docs/integration-prompt.md

@@ -2,6 +2,10 @@
 
 Use this prompt in another Windows project when you want Codex or another agent to add MrTrust support.
 
+Before changing the target project, read:
+- `mrtrust.integration.json`
+- `docs/agent-target-integration.md`
+
 ```text
 Integrate MrTrust support into this Windows project.
 
@@ -12,6 +16,7 @@ Goal:
 
 Agent contract:
 - You are modifying the target Windows project, not MrTrust itself.
+- Use `mrtrust.integration.json` and `docs/agent-target-integration.md` as the authoritative integration contract.
 - Add MrTrust as a visible, optional trust-onboarding path for users.
 - Add or update the target project's release/signing pipeline so produced Windows artifacts are signed.
 - Do not mark the task complete after only copying documentation. The target project needs user-facing integration and signing support where applicable.