prole/prole-app/README.md

```
#####################################################
# ╭───────────────────────────────────────────────╮ #
# │               _     ___ _        _            │ #
# │  _ __ _ _ ___| |___/ __| |_ __ _| |_ _  _ ___ │ #
# │ | '_ \ '_/ _ \ / -_)__ \  _/ _` |  _| || (_-< │ #
# │ | .__/_| \___/_\___|___/\__\__,_|\__|\_,_/__/ │ #
# │ |_|                                           │ #
# ╰───────────────────────────────────────────────╯ #
#####################################################
```

Prole
— macOS status and control surface for Prole endpoints, with a path to an integrated virtual workstation harness.

Overview
- Prole provides live reachability and latency signals for Prole service endpoints. It operates in two modes: a regular application window for situational awareness and a minimalist status‑bar overlay for persistent at‑a‑glance status.
- The application will evolve to include a virtual workstation surface to coordinate work across a network of Prole‑linked LLMs. The current scope is operational visibility and control of endpoints.

Supported platform
- macOS 12.0+ (Monterey or newer) on Apple Silicon (arm64) and Intel (x86_64). Universal builds are supported by the build script.

Execution environment requirements (runtime)
- No external daemons or brew packages are required to run the built app bundle.
- Network access to the configured endpoints.

Build environment requirements
- Xcode Command Line Tools (swiftc, xcrun). Install if needed:
  ```
  xcode-select --install
  ```
- System tools used by the build:
  - `iconutil` and `sips` (for `.icns` generation)
  - `codesign` (ad‑hoc signing)
  - `plutil` (plist formatting, via xcrun if needed)

Repository layout (subset)
- `prole-app/` — macOS app sources and build system
  - `Sources/` — Swift sources (AppKit)
  - `build.sh` — hermetic CLI build producing a `.app` bundle
  - `prole.properties` — default endpoint configuration (bundled into Resources)
  - `dist/Prole.app` — build output

Build script
- The build is driven by `prole-app/build.sh`. Typical usage:
  ```
  cd prole-app
  ./build.sh build             # build for host arch
  ./build.sh run               # build (if needed) and open the app
  ./build.sh build-universal   # produce a universal (arm64+x86_64) binary
  ./build.sh debug             # run in foreground with verbose logs
  ./build.sh clean             # remove build artifacts
  ./build.sh package           # zip dist/Prole.app into dist/Prole.zip
  ```

What the script does
- Compiles all Swift sources with `swiftc` (AppKit, Carbon, Network frameworks).
- Generates `Contents/Info.plist` with `LSUIElement=false` so the app can present a standard menu when in Application Window mode.
- Generates an application icon (`Prole.icns`) and a template status glyph as needed.
- Copies resources:
  - `www/images/prole-type.gif` → `Contents/Resources/prole-type.gif` (for the startup tip splash)
  - `prole-app/prole.properties` → `Contents/Resources/prole.properties`
- Performs ad‑hoc code signing of the `.app` bundle.

Alternate build path (installer UI)
- The repository includes `install.py`, a Tkinter helper that can orchestrate the build. From the repository root:
  ```
  python3 install.py
  ```
- Use the “Build Prole macOS app” step. The installer will produce `prole-app/dist/Prole.app` and can optionally copy it to `/Applications`.

Run modes and controls
- Modes:
  - Application Window mode (default): resizable window with three vertical status rows (svc, k3s aggregate, local) and a timestamp in the top‑right. A small control bar bottom‑left exposes Refresh (⟳) and Minimize to Status Bar (_).
  - Status Bar mode: thin overlay aligned with the macOS menu bar; shows a scrolling summary and a 'maximize' button (□) to return to the main window.
- Toggle between modes with the global shortcut:
  - `Cmd`+`Option`+`Shift`+`P`
- Menus:
  - Application menu “Prole” (next to the Apple menu): Show Status Bar / Show Main Window (same toggle as the hotkey), Refresh Now, Quit.
  - Status‑bar “P” icon (right‑click): Show/Hide Status Bar Icon, Show/Hide Application Window, Refresh Now, Quit.

Configuration
- Endpoint configuration is provided via Java‑style `key=value` properties. Two locations are read at startup; the user override has precedence:
  1. Bundled defaults: `Prole.app/Contents/Resources/prole.properties`
  2. User override (optional): `~/Library/Application Support/Prole/prole.properties`
- Default keys:
  - `svc.host`, `svc.port`
  - `k3s.retropie.host`, `k3s.retropie.port`
  - `k3s.pi.host`, `k3s.pi.port`
  - `k3d.local.host`, `k3d.local.port`
- Example user override:
  ```
  # Override core service endpoint
  svc.host=svc.my-domain.tld
  svc.port=443

  # Local k3d on a custom port
  k3d.local.port=6445
  ```

Operational notes
- Status checks are TCP connect probes executed on a background timer (default: 30s). Latency is the connection time in milliseconds; failures record a short diagnostic for tooltips.
- The splash screen is transient (~ 5s) and can be dismissed with a click. It loads `prole-type.gif` if present in Resources.

Diagnostics & troubleshooting
- Ensure Xcode CLT is installed if the build fails:
  ```
  xcode-select --install
  ```
- If the app launches without a standard menu/window, verify `Info.plist` has `LSUIElement=false` (the build script sets this). Rebuild using `build.sh`.
- If the hotkey appears inactive, bring the app to the foreground or use the Prole menu item (it triggers the same toggle).
- If status indicators stay red, validate network reachability and adjust `prole.properties` to endpoints reachable from your host.
- For ad‑hoc logging, search the sources for `dlog("…")` and run via `./build.sh debug` to watch stdout.

Security & signing
- The `.app` bundle is ad‑hoc signed by default. For distribution, replace with a Developer ID signature and notarize as appropriate for your environment.

Roadmap
- Integration of a virtual workstation to orchestrate a network of Prole‑linked LLMs from within the Prole surface.

License
- See the repository `LICENSE` file.