Add autonomous MrTrust target integration contract

AGENTS.md

@@ -16,6 +16,8 @@ MrTrust manages explicit Windows certificate trust for MrSphay software.
 - `assets/certificates/` contains public certificates only.
 - `private/` is ignored and may contain local signing material.
 - `docs/integration-prompt.md` is the prompt for adding MrTrust to other projects.
+- `docs/agent-target-integration.md` is the autonomous runbook for agents modifying target projects.
+- `mrtrust.integration.json` is the machine-readable integration contract.
 - `docs/security-model.md` documents the intended behavior and limits.
 - `MrTrust.exe` is the user-facing standalone trust installer. The PowerShell scripts are source/build internals.
 

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Added an autonomous target-project integration runbook for agents.
+- Added `mrtrust.integration.json` as a machine-readable integration contract.
+- Updated agent-facing documentation to prefer the standalone `MrTrust.exe` integration path.
+
 ## 0.1.1
 
 - Added a custom MrTrust application icon and embedded it into the launcher.

README.md

@@ -21,6 +21,8 @@ MrTrust does not bypass Microsoft Defender or SmartScreen. Windows can still sca
 - `scripts/Sign-MrTrustProject.ps1` signs `.exe`, `.msi`, `.ps1`, and other Authenticode-compatible files.
 - `scripts/New-MrTrustRelease.ps1` builds a distributable ZIP package.
 - `docs/integration-prompt.md` is a prompt you can paste into other Windows projects.
+- `docs/agent-target-integration.md` is the autonomous target-project integration runbook for agents.
+- `mrtrust.integration.json` is the machine-readable integration contract.
 - `MrTrust.exe` is standalone for normal users. It embeds the public certificates and runtime scripts.
 
 ## Quick Start For MrSphay
@@ -95,6 +97,12 @@ Then choose the all-users option in the GUI.
 
 Yes. Give another agent this repository URL, the target Windows project, and `docs/integration-prompt.md`.
 
+For autonomous work, the agent should read these files in order:
+
+1. `mrtrust.integration.json`
+2. `docs/agent-target-integration.md`
+3. `docs/integration-prompt.md`
+
 The agent's job is to modify the target project, not this repository:
 
 - expose a visible "Open MrTrust" or trust setup path for users
@@ -121,3 +129,5 @@ If the target project is not signed, MrTrust cannot make it trusted.
 ## Recommended Project Integration
 
 Use `docs/integration-prompt.md` in another Windows project. The prompt tells Codex or another assistant to add a visible trust check, a link or bundled copy of the standalone `MrTrust.exe`, and a signing step without hiding security changes from the user.
+
+For agents that can inspect files autonomously, `docs/agent-target-integration.md` gives the decision tree, installer patterns, signing commands, and completion checklist.

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.

manifest.json

@@ -1,7 +1,16 @@
 {
   "name": "codex-agent-repository-kit",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Universal repository baseline for Codex-assisted projects.",
+  "mrtrustIntegration": {
+    "contract": "mrtrust.integration.json",
+    "agentRunbook": "docs/agent-target-integration.md",
+    "prompt": "docs/integration-prompt.md",
+    "standaloneExecutable": "MrTrust.exe",
+    "publicThumbprint": "A024A89200469F099EC4A172B4F96F6428AFD41B",
+    "sourceRepository": "https://git.wilkensxl.de/MrSphay/MrTrust",
+    "releasePage": "https://git.wilkensxl.de/MrSphay/MrTrust/releases"
+  },
   "agentResponsibilities": [
     "Read manifest.json before copying files.",
     "Use copyMap target paths unless the repository already has an equivalent convention.",

manifest.schema.json

@@ -13,6 +13,34 @@
     "description": {
       "type": "string"
     },
+    "mrtrustIntegration": {
+      "type": "object",
+      "required": ["contract", "agentRunbook", "prompt", "standaloneExecutable", "publicThumbprint"],
+      "properties": {
+        "contract": {
+          "type": "string"
+        },
+        "agentRunbook": {
+          "type": "string"
+        },
+        "prompt": {
+          "type": "string"
+        },
+        "standaloneExecutable": {
+          "type": "string"
+        },
+        "publicThumbprint": {
+          "type": "string"
+        },
+        "sourceRepository": {
+          "type": "string"
+        },
+        "releasePage": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
     "agentResponsibilities": {
       "type": "array",
       "items": {

mrtrust.integration.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "name": "MrTrust",
+  "purpose": "Add explicit MrSphay trust onboarding and signing support to Windows target projects.",
+  "sourceRepository": "https://git.wilkensxl.de/MrSphay/MrTrust",
+  "releasePage": "https://git.wilkensxl.de/MrSphay/MrTrust/releases",
+  "userFacingReleaseArtifact": {
+    "fileName": "MrTrust.exe",
+    "releaseZipNamePattern": "MrTrust-<version>.zip",
+    "recommendedBundledPath": "MrTrust\\MrTrust.exe",
+    "distribution": "Bundle this file directly or link to the MrTrust release ZIP.",
+    "launchCommand": ".\\MrTrust\\MrTrust.exe",
+    "removeTrustInstruction": "Open MrTrust and choose Remove trust."
+  },
+  "certificate": {
+    "publisher": "MrSphay",
+    "publicThumbprint": "A024A89200469F099EC4A172B4F96F6428AFD41B",
+    "defaultTrustScope": "CurrentUser",
+    "allUsersTrustScope": "LocalMachine",
+    "privateMaterialPolicy": "Never commit .pfx files, private keys, passwords, tokens, or signing secrets."
+  },
+  "signing": {
+    "supportedExtensions": [
+      ".exe",
+      ".msi",
+      ".dll",
+      ".ps1",
+      ".psm1",
+      ".psd1",
+      ".cat"
+    ],
+    "preferredCommand": ".\\MrTrust\\MrTrust.exe sign -Path <artifact-path> -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B",
+    "ciGuidance": "Run signing only on a trusted Windows release runner or secure local release machine where the private certificate is already installed or supplied through secrets.",
+    "unsignedBehavior": "Unsigned builds should remain unsigned. MrTrust only makes correctly signed MrSphay artifacts validate after the user has installed trust."
+  },
+  "targetProjectAgentContract": {
+    "modifyTargetProject": true,
+    "requiredOutcomes": [
+      "Expose a visible optional Open MrTrust or trust setup path.",
+      "Link to or bundle the standalone MrTrust.exe.",
+      "Sign Windows release artifacts when the target project produces supported artifact types.",
+      "Document how users install and remove MrTrust trust.",
+      "Verify no private signing material is present in the target repository or release artifacts."
+    ],
+    "forbiddenOutcomes": [
+      "Do not silently install certificates.",
+      "Do not bypass Defender, SmartScreen, UAC, firewall, or Windows security policy.",
+      "Do not claim MrTrust makes unsigned software trusted.",
+      "Do not commit private signing material."
+    ],
+    "fallbackWhenNoInstallerExists": [
+      "Add release documentation that links to or bundles MrTrust.exe.",
+      "Add a release signing step for supported Windows artifacts.",
+      "Add verification notes explaining that the app starts normally after the user installs MrTrust and the artifact signature validates."
+    ]
+  },
+  "agentRunbook": "docs/agent-target-integration.md",
+  "prompt": "docs/integration-prompt.md"
+}