Agents docs

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

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.

Documentation/AwesomeActionsPages.md

@@ -0,0 +1,58 @@
+# Awesome Actions Publishing Stack
+
+This overview captures how the Awesome GitHub Actions LaTeX artefacts are turned
+into a live GitHub Pages site and how conversation transcripts are archived for
+future agents.
+
+## Workflow Topology
+```
+┌────────────────────────────┐      ┌────────────────────────────┐
+│ Awesome GitHub Actions CI │      │ Publish Awesome Actions    │
+│ (LaTeX/PDF generator)     │      │ Docs (GitHub Actions)      │
+└────────────┬──────────────┘      └────────────┬───────────────┘
+             │                                   │
+             │ writes                             │ packages
+             ▼                                   ▼
+      docs/awesome-actions-report.pdf     docs/ (HTML, metadata)
+             │                                   │
+             ├───────────────┐                   │ upload-pages-artifact
+             │               │                   │
+             ▼               ▼                   ▼
+  docs/awesome-actions-report.html    Documentation/conversations/
+             │                                   │
+             └───────────────────────┬───────────┘
+                                     ▼
+                           GitHub Pages Deployment
+```
+
+The `Publish Awesome Actions Docs` workflow runs on `main` pushes affecting the
+documentation or manually via `workflow_dispatch`. It packages `docs/` as a
+Pages artefact and deploys via `actions/deploy-pages`.
+
+## Directory Contract
+- `docs/index.md`: Markdown landing page rendered by Pages.
+- `docs/awesome-actions-report.pdf`: Latest LaTeX output; overwritten by the
+  generator workflow.
+- `docs/awesome-actions-report.html`: Lightweight viewer embedding the PDF.
+- `Documentation/conversations/`: Session summaries with timestamps and branch
+  metadata to preserve agent continuity.
+- `docs/publish-metadata.txt`: Generated during deployment runs to timestamp the
+  publish event.
+
+## Required Automation Steps
+1. **Render Artefacts**: Ensure the upstream workflow copies the compiled PDF
+   into `docs/awesome-actions-report.pdf` and refreshes the HTML if the schema
+   changes.
+2. **Archive the Session**: Before finishing a change, store the current
+   conversation under `Documentation/conversations/` with clear headings.
+3. **Trigger Deployment**: Merge to `main` or use `workflow_dispatch` to push
+   the latest bundle to Pages. Verify the site at the URL emitted by the deploy
+   job.
+
+## Debugging Tips
+- Inspect the generated `docs/publish-metadata.txt` in the workflow artefact to
+  confirm the deploy step ran with the expected timestamp.
+- Use `actions/github-script` or `gh api` to list the latest Pages deployment if
+  stale content appears.
+- Keep the placeholder PDF in source control to provide a deterministic preview
+  for branches where the LaTeX job has not executed yet.

Documentation/agents.D

@@ -0,0 +1,37 @@
+# Agents Behaviour Design Notes
+
+Context: Automation agents occasionally propose code for iOS and macOS
+repositories. This file outlines the behavioural contract they should follow.
+
+Objectives:
+- Maintain deterministic builds by keeping Xcode project state reproducible.
+- Preserve platform specific assets (icons, intents, entitlements) and confirm
+  bundle identifiers remain untouched unless explicitly requested.
+- Keep shared Swift modules compiling on both platforms and run unit tests when
+  available.
+
+Operational Guidance:
+- Prefer editing `.xcconfig`, `.plist`, and scheme files through scripted tools
+  to avoid introducing opaque Xcode state changes.
+- When modifying SwiftUI or storyboard resources, provide before/after
+  snapshots or GIFs to aid human review.
+- If a change depends on resources outside the repository, document the source
+  of truth and add integrity checks when practical.
+- Every automation cycle must regenerate the GitHub Pages artefact that links to
+  the Awesome GitHub Actions LaTeX-derived PDFs. Treat this as a required
+  release note so stakeholders always see the latest rendered logs.
+- Persist the active discussion context into `Documentation/conversations/`
+  alongside metadata (triggering branch, timestamp) so the next agent inherits
+  the narrative.
+
+Dependency Safety:
+- Announce new package dependencies, pin versions, and update the dependency
+  mirrors used by the CI pipeline.
+- For binary frameworks, include hash fingerprints and storage locations so the
+  build cache remains verifiable.
+
+ParentDirectory Handling:
+- Detect the absence of the `ParentDirectory` symlink during setup scripts and
+  guide maintainers to recreate it with `ln -s .. ParentDirectory`.
+- Avoid committing the resolved path of the symlink; it must stay a relative
+  link so cloned checkouts behave the same.

Documentation/agents.md

@@ -0,0 +1,44 @@
+# Agent Guidelines for iOS and macOS Repositories
+
+This note captures the expectations for automation agents that propose or land
+changes in the Apple platform portions of the project. The goal is to keep the
+codebase healthy while enabling quick experimentation.
+
+## Core Principles
+- Prioritise reproducibility: always document any build, signing, or runtime
+  requirements that are not already scripted.
+- Optimise for safety: prefer additive changes, gate risky behaviour behind
+  feature flags, and surface migration steps explicitly.
+- Keep human reviewers in control: summarise intent, affected components, and
+  potential regressions in commit messages and pull requests.
+
+## Workflow Expectations
+1. Validate the change on both iOS and macOS targets using the relevant Xcode
+   schemes whenever the modification touches shared code.
+2. Capture simulator and device caveats in the change description so the human
+   reviewer knows which environments were exercised.
+3. Update user-facing documentation under `Documentation/` when behaviour
+   observable by end users changes.
+
+## Handling the `ParentDirectory` Symlink
+- Some Xcode project references rely on a `ParentDirectory` symlink that points
+  back to the repository root. If the link is missing, recreate it with
+  `ln -s .. ParentDirectory` from the directory that expects the link.
+- Never replace the symlink with a real directory. Doing so breaks relative
+  paths that the project file includes.
+- When touching build scripts, ensure they continue to tolerate the absence of
+  the link and produce a helpful error message instructing contributors to
+  recreate it.
+
+## Communication Checklist
+- Provide a brief risk assessment covering crash, data-loss, and regression
+  vectors.
+- Mention any new dependencies or entitlements, especially if they require new
+  approval in Apple developer tooling.
+- Offer follow-up tasks for manual QA if the change touches UI flows that are
+  hard to exercise via automation.
+- Produce a GitHub Pages update summarising any generated PDF artefacts from the
+  "Awesome GitHub Actions" LaTeX logs and link the freshly rendered pages. Make
+  sure the site remains up to date even when only automation runs.
+- Archive the latest session transcript under `Documentation/conversations/`
+  before concluding the change so future agents can reference prior context.