MrTrust/docs/agent-target-integration.md

# 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.