Where to Find Troubleshooting Information for Vorssaint-Utils

The primary troubleshooting information for Vorssaint-Utils is located in docs/TROUBLESHOOTING.md, which provides step-by-step solutions for Gatekeeper blocks, macOS permission resets, and clean uninstallation procedures.

When issues arise with the Vorssaint-Utils macOS utility suite, the repository maintains a dedicated troubleshooting guide rather than scattering solutions across GitHub issues. This centralized documentation addresses the most common setup and runtime failures, from initial launch blocking to sticky permission grants that prevent features from functioning.

Primary Troubleshooting Documentation Location

The central resource is docs/TROUBLESHOOTING.md in the repository root. This Markdown file is viewable directly on GitHub at https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md and is referenced from the application's Settings → Help pane, making it accessible both within the running app and from the raw source tree.

Common Issues Covered in the Guide

The documentation organizes solutions into distinct sections targeting specific failure modes encountered on macOS systems.

Application Launch Failures

For scenarios where the app will not open, the guide explains how to bypass Gatekeeper restrictions on self-built or unofficial binaries. This section specifically addresses security quarantine attributes and unsigned binary execution blocks that prevent the application from starting.

Permission and Feature Malfunctions

When a feature does nothing or a permission will not stick, the documentation provides a detailed walkthrough of macOS Privacy & Security settings. It covers the four critical entitlement categories Vorssaint-Utils requires: Accessibility, Screen Recording, System Audio Recording, and Automation.

Resetting macOS Privacy Grants

The tccutil command-line utility is documented for resolving corrupted or stuck permission states. Use these specific commands to reset grants for the application's bundle identifier:

# Reset all privacy permissions for Vorssaint-Utils

tccutil reset All com.vorssaint.utils

# Reset only the Accessibility permission

tccutil reset Accessibility com.vorssaint.utils

Diagnostic Commands and Maintenance Scripts

The repository ships executable resources that facilitate system diagnostics and complete removal.

Running the Built-in Self-Test

Before reporting bugs, generate diagnostic output using the application's self-validation mode implemented in the build system:

./build/Vorssaint --selftest

This executes validation routines against the compiled binary and environment, producing technical output essential for high-quality issue reports.

Performing a Clean Uninstall

The Tools/uninstall.sh script performs complete removal of the application bundle, Login Items, preference files, and residual privacy grants. Execute it from the repository root:

./Tools/uninstall.sh

This ensures no orphaned permissions or configuration files remain that could interfere with future installations.

Supporting Documentation and Source References

Additional files provide architectural context for advanced troubleshooting:

• docs/PERMISSIONS.md – Detailed descriptions of each macOS permission category required by Vorssaint-Utils and the specific application features that depend on them.
• Sources/Vorssaint/main.swift – The application entry point containing the startup sequence logic useful for diagnosing launch-time crashes or initialization failures.
• build.sh – The build automation script that produces the self-test binary and manages compilation flags affecting runtime behavior.

Summary

• The definitive troubleshooting information for Vorssaint-Utils resides in docs/TROUBLESHOOTING.md.
• Use tccutil reset All com.vorssaint.utils to clear all macOS privacy grants when permissions persist incorrectly.
• Execute ./build/Vorssaint --selftest to generate diagnostic reports required for bug submissions.
• Run ./Tools/uninstall.sh to completely remove the application, its preferences, and privacy grants.
• Consult docs/PERMISSIONS.md for detailed explanations of required system entitlements and their functional dependencies.

Frequently Asked Questions

Where is the main troubleshooting guide for Vorssaint-Utils located?

The main guide is docs/TROUBLESHOOTING.md in the repository root. You can view it on GitHub or access it directly from the Vorssaint-Utils Settings → Help interface.

How do I reset Vorssaint-Utils permissions when features stop responding?

Run tccutil reset Accessibility com.vorssaint.utils to reset only the Accessibility permission, or tccutil reset All com.vorssaint.utils to wipe all privacy grants for the application. These commands require administrator privileges and must be run in Terminal.

What diagnostic information should I include in bug reports?

Run ./build/Vorssaint --selftest from the repository root and include the complete output in your issue. This command executes the built-in self-test routine that validates the build environment and core functionality, providing maintainers with essential technical context.

How do I completely uninstall Vorssaint-Utils including all privacy data?

Execute ./Tools/uninstall.sh from a cloned copy of the repository. This script removes the application bundle, Login Item entries, preference plist files, and all associated Privacy & Security grants, ensuring no residual configuration remains on the system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}