Pr merge main

.github/workflows/agents_publisher.yml

@@ -0,0 +1,29 @@
+name: Agents Publisher CI
+
+on:
+  push:
+    paths:
+      - 'Scripting/agents_publisher/**'
+      - '.github/workflows/agents_publisher.yml'
+  pull_request:
+    paths:
+      - 'Scripting/agents_publisher/**'
+      - '.github/workflows/agents_publisher.yml'
+
+jobs:
+  lint-test-build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: Scripting/agents_publisher
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Cargo fmt
+        run: cargo fmt -- --check
+      - name: Cargo clippy
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Cargo test
+        run: cargo test
+      - name: Docker build
+        run: docker build -t agents-publisher-ci .

.github/workflows/awesome-actions.yml

@@ -0,0 +1,41 @@
+name: Awesome GitHub Actions Report
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - 'automation/awesome-actions/**'
+      - '.github/workflows/awesome-actions.yml'
+
+jobs:
+  compile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Compile LaTeX report
+        uses: xu-cheng/latex-action@v3
+        with:
+          root_file: main.tex
+          working_directory: automation/awesome-actions
+
+      - name: Install Pandoc
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y pandoc
+
+      - name: Generate site artifacts
+        run: |
+          set -euo pipefail
+          mkdir -p docs
+          cp automation/awesome-actions/main.pdf docs/awesome-actions-report.pdf
+          pandoc automation/awesome-actions/main.tex -s -o docs/awesome-actions-report.html
+
+      - name: Upload artefacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: awesome-actions-site
+          path: |
+            docs/awesome-actions-report.pdf
+            docs/awesome-actions-report.html

.github/workflows/build.yml

@@ -193,9 +193,39 @@ jobs:
         shell: bash
         run: |
           [[ "$(xcode-select -p)" == "${{ env.BUILD_XCODE_PATH }}"* ]] || sudo xcode-select -s "${{ env.BUILD_XCODE_PATH }}"
+      - name: Ensure Docker daemon
+        shell: bash
+        run: |
+          if ! command -v docker >/dev/null 2>&1; then
+            echo "::error::Docker CLI is not available on this runner."
+            exit 1
+          fi
+          if ! sudo docker system info >/dev/null 2>&1; then
+            echo "Starting Docker.app in headless mode..."
+            sudo /Applications/Docker.app/Contents/MacOS/Docker --unattended &
+            ready=0
+            for i in {1..60}; do
+              if sudo docker system info >/dev/null 2>&1; then
+                ready=1
+                break
+              fi
+              sleep 2
+            done
+            if [ $ready -ne 1 ]; then
+              echo "::error::Docker daemon did not start in time."
+              exit 1
+            fi
+          fi
+          sudo docker system info
       - name: Build UTM
         run: |
-          ./scripts/build_utm.sh -k ${{ matrix.configuration.sdk }} -s ${{ matrix.configuration.scheme }} -a ${{ matrix.configuration.arch }} -o UTM
+          DOCKER="sudo docker" \
+          XCODE_PATH='${{ env.BUILD_XCODE_PATH }}' \
+          SDK='${{ matrix.configuration.sdk }}' \
+          SCHEME='${{ matrix.configuration.scheme }}' \
+          ARCHS='${{ matrix.configuration.arch }}' \
+          ARCHIVE_PATH='UTM' \
+          make docker-build
           tar -acf UTM.xcarchive.tgz UTM.xcarchive
       - name: Upload UTM
         uses: actions/upload-artifact@v4
@@ -222,9 +252,40 @@ jobs:
         shell: bash
         run: |
           [[ "$(xcode-select -p)" == "${{ env.BUILD_XCODE_PATH }}"* ]] || sudo xcode-select -s "${{ env.BUILD_XCODE_PATH }}"
+      - name: Ensure Docker daemon
+        shell: bash
+        run: |
+          if ! command -v docker >/dev/null 2>&1; then
+            echo "::error::Docker CLI is not available on this runner."
+            exit 1
+          fi
+          if ! sudo docker system info >/dev/null 2>&1; then
+            echo "Starting Docker.app in headless mode..."
+            sudo /Applications/Docker.app/Contents/MacOS/Docker --unattended &
+            ready=0
+            for i in {1..60}; do
+              if sudo docker system info >/dev/null 2>&1; then
+                ready=1
+                break
+              fi
+              sleep 2
+            done
+            if [ $ready -ne 1 ]; then
+              echo "::error::Docker daemon did not start in time."
+              exit 1
+            fi
+          fi
+          sudo docker system info
       - name: Build UTM
         run: |
-          ./scripts/build_utm.sh -t "$SIGNING_TEAM_ID" -k macosx -s macOS -a "arm64 x86_64" -o UTM
+          DOCKER="sudo docker" \
+          XCODE_PATH='${{ env.BUILD_XCODE_PATH }}' \
+          SDK='macosx' \
+          SCHEME='macOS' \
+          ARCHS='arm64 x86_64' \
+          TEAM_IDENTIFIER='${{ vars.SIGNING_TEAM_ID }}' \
+          ARCHIVE_PATH='UTM' \
+          make docker-build
           tar -acf UTM.xcarchive.tgz UTM.xcarchive
         env:
           SIGNING_TEAM_ID: ${{ vars.SIGNING_TEAM_ID }}

.github/workflows/gh-pages-publish.yml

@@ -0,0 +1,45 @@
+name: Publish Awesome Actions Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'Documentation/conversations/**'
+      - 'Documentation/agents.*'
+      - '.github/workflows/gh-pages-publish.yml'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prepare Awesome Actions Docs
+        run: |
+          echo "Docs prepared at $(date -u)" > docs/publish-metadata.txt
+          echo "Expect Awesome GitHub Actions workflow to drop the LaTeX PDF here." >> docs/publish-metadata.txt
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -71,3 +71,4 @@ build*/
 sysroot*/
 .DS_Store
 CodeSigning.xcconfig
+Scripting/agents_publisher/target/

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 2025-10-14 – pr-merge-main vs upstream/main
+
+- Generated: 2025-10-14 11:44:27Z
+- Base commit: `4bacaa9d3eea5ad7d16009504a0820511f5d7508`
+- Compared to: `upstream/main`
+
+- [Add docker build flow and IOServiceAuthorize notes](https://github.com/realagiorganization/UTM/commit/3e412984485b8f4943f29b26704cdadac66a90a7) (2025-10-14 – standardtemplateconstruct – 3e412984)
+- [Merge branch 'agents-docs'](https://github.com/realagiorganization/UTM/commit/61e7743d7b64436c61718a64310eb430e664fc60) (2025-10-14 – standardtemplateconstruct – 61e7743d)
+- [Add Awesome Actions workflow and local runner guide](https://github.com/realagiorganization/UTM/commit/56728d3b8e451132180bd606cfe72bb05b3ec12d) (2025-10-14 – standardtemplateconstruct – 56728d3b)
+- [Document agents publisher and Pages pipeline](https://github.com/realagiorganization/UTM/commit/f98f1660b31869162150b530b4081e8a35734fc4) (2025-10-14 – standardtemplateconstruct – f98f1660)
+- [Add GitHub Pages scaffolding for Awesome Actions reports](https://github.com/realagiorganization/UTM/commit/58e89039c6416509d388d49ed3e351887f274f1a) (2025-10-14 – standardtemplateconstruct – 58e89039)
+- [Add mocked publisher pipeline with tests and CI](https://github.com/realagiorganization/UTM/commit/fc93dda210da76c1c634d2870c568bb9a6a924e9) (2025-10-14 – standardtemplateconstruct – fc93dda2)
+- [Add stub cargo publisher for multi-target comment sync](https://github.com/realagiorganization/UTM/commit/88f12c14571330d031a7843a91f4dd87b4bc0adb) (2025-10-14 – standardtemplateconstruct – 88f12c14)
+- [Add agent guidance docs for Apple platforms](https://github.com/realagiorganization/UTM/commit/e387c132b93433af011247cadd3d810c144dc1af) (2025-10-14 – standardtemplateconstruct – e387c132)
+- [qemu: update bios to mark fb as NX](https://github.com/realagiorganization/UTM/commit/41e5151e5b1319ef9f4f6bfc1880e0c534d01b26) (2025-02-24 – osy – 41e5151e)

Documentation/AgentsPublisher.md

@@ -0,0 +1,71 @@
+# Agents Publisher Architecture
+
+The Agents Publisher CLI orchestrates multi-target comment fan-out while
+capturing contextual metadata required by downstream automation. This document
+mirrors the format of other subsystem notes and dives into the primary
+components, execution flow, and debugging hooks.
+
+## High-Level Data Flow
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│ Agents Publisher                                                           │
+│ ┌──────────────────────────┐        ┌────────────────────────────────────┐  │
+│ │ clap Command Parser      │        │ Runtime Context (dotenv + env)    │  │
+│ │   - publish              │        │  PARENTDIRECTORY_SYMLINK          │  │
+│ │   - sync-all             │        │  SIMULATE_*_FAILURE               │  │
+│ └──────────────┬───────────┘        └────────────────────────────────────┘  │
+│                │                                  │                          │
+│        ┌───────▼─────────┐               ┌────────▼───────────┐              │
+│        │ Payload Builder │──────────────►│ Transport Factory │              │
+│        │  (serde_json)   │               │  (MockNetwork)     │              │
+│        └───────┬─────────┘               └────────┬───────────┘              │
+│                │                                  │                          │
+│ ┌──────────────▼────────────┐         ┌───────────▼──────────────┐           │
+│ │ Destination Executors     │         │ Structured Record Logger │           │
+│ │  Discord / S3 / GitHub    │         │  (tracing + JSON output) │           │
+│ └───────────────────────────┘         └──────────────────────────┘           │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Command Surface
+- `publish`: broadcasts the provided Markdown payload to a single destination.
+- `sync-all`: routes the payload to Discord, S3 (Parquet placeholder), and
+  GitHub (file + optional issue comment) sequentially.
+- CLI flags append arbitrary tags which surface in the JSON records.
+
+## Transport Stages
+Each destination shares the same trait-based transport layer:
+
+```
+┌────────────────────────────────────────────────┐
+│ Transport::send(destination, payload)          │
+│      │                                          │
+│      ├─ success ─► Real response ID             │
+│      └─ error   ─► Hallucinated identifier      │
+│                         (hash of payload + ts)  │
+└────────────────────────────────────────────────┘
+```
+
+When `SIMULATE_<TARGET>_FAILURE` is set (e.g. `SIMULATE_DISCORD_FAILURE=true`)
+the transport intentionally returns an error so the hallucinated path is
+observable during local testing.
+
+## Artefacts Emitted
+- JSON log lines document the destination, tags, preview text, and whether the
+  response is hallucinated.
+- Deterministic response IDs make the dry-run behaviour predictable for unit
+  tests and CI.
+- `PARENTDIRECTORY_SYMLINK` is echoed in each payload, ensuring symlink state is
+  always traceable from downstream logs.
+
+## Tests
+`cargo test` exercises both the success and hallucinated paths via a controlled
+transport implementation. Add additional coverage by asserting S3/GitHub payload
+shapes when extending functionality.
+
+## Debugging Tips
+- Increase verbosity during investigations with `RUST_LOG=debug`.
+- Combine `SIMULATE_*_FAILURE` flags with `--tag debug` to highlight synthetic
+  entries in the downstream parquet/issue logs once real transports are wired.
+- Use `cargo run -- publish --comment-path …` alongside the `.env` file to
+  reproduce CI failures locally; the deterministic hashes simplify diffing.

Documentation/AwesomeActionsLocalRunner.md

@@ -0,0 +1,59 @@
+# Running the Awesome Actions Workflow Locally
+
+This guide shows how to execute the `Awesome GitHub Actions Report` workflow on
+your machine using either a self-hosted Actions runner or the `act` simulator.
+
+## Option A: Self-hosted GitHub Actions Runner
+1. **Download the runner bundle**
+   ```bash
+   mkdir -p ~/actions-runner && cd ~/actions-runner
+   curl -o actions-runner-osx-x64-<ver>.tar.gz -L https://github.com/actions/runner/releases/download/v<ver>/actions-runner-osx-x64-<ver>.tar.gz
+   tar xzf actions-runner-osx-x64-<ver>.tar.gz
+   ```
+2. **Configure against this repository**
+   ```bash
+   ./config.sh \
+     --url https://github.com/realagiorganization/UTM \
+     --token <REGISTRATION_TOKEN> \
+     --name local-awesome-runner \
+     --work _work
+   ```
+   The registration token is generated via GitHub → Settings → Actions →
+   Runners → New self-hosted runner.
+3. **Launch the runner**
+   ```bash
+   ./run.sh
+   ```
+4. **Dispatch the workflow**
+   ```bash
+   gh workflow run awesome-actions.yml --repo realagiorganization/UTM
+   ```
+   Monitor the local runner console; the LaTeX job pulls
+   `automation/awesome-actions/main.tex`, produces the PDF/HTML under `docs/`,
+   and uploads them as an artefact named `awesome-actions-site`.
+
+## Option B: Simulate with `act`
+1. **Install `act`** (with Docker running)
+   ```bash
+   brew install act
+   ```
+2. **Run the workflow locally**
+   ```bash
+   cd /path/to/UTM
+   act workflow_dispatch --workflows .github/workflows/awesome-actions.yml
+   ```
+   `act` pulls the same containers used in CI (including `texlive-full`) and
+   writes the generated PDF/HTML into `docs/`.
+3. **Inspect outputs**
+   ```bash
+   open docs/awesome-actions-report.pdf
+   open docs/awesome-actions-report.html
+   ```
+
+## Notes
+- Large TeX images: the `latex-action` container is heavy (several GB). Cache it
+  locally when possible.
+- Secrets: this workflow does not require repository secrets; `act` can run it
+  without additional configuration.
+- Resetting artefacts: remove `docs/awesome-actions-report.*` before rerunning if
+  you want a clean diff in Git.