docs: switch macos install guidance to source

Author: web3dev1337

CODEBASE_DOCUMENTATION.md

@@ -17,6 +17,7 @@ FRONTEND:   client/app.js, client/terminal.js        - Web client
 NATIVE:     src-tauri/src/main.rs                    - Native desktop app
 CONFIG:     config.json, package.json                - Configuration files
 GUIDES:     CLAUDE.md, AGENTS.md                     - Repo workflow + release guardrails for contributors/agents
+DOCS:       docs/MACOS_SIGNING_RELEASE_CHECKLIST.md - Maintainer checklist for Apple signing/notarization secrets and macOS desktop releases
 META:       .github/FUNDING.yml                      - GitHub Sponsors button configuration
 PACKAGING:  scripts/tauri/prepare-backend-resources.js - Bundles backend resources + reusable packaged prod deps
             scripts/tauri/run-tauri-build.js          - Centralized Tauri build entrypoint (local Windows fast-cache pinning + profile dispatch)

README.md

@@ -1,7 +1,7 @@
 # Agent Workspace
 
 [![Website](https://img.shields.io/badge/Website-agent--workspace.ai-00d4ff?style=for-the-badge)](https://agent-workspace.ai)
-[![Download](https://img.shields.io/badge/Download-Latest%20Release-00d4ff?style=for-the-badge)](https://github.com/web3dev1337/agent-workspace/releases/latest)
+[![Releases](https://img.shields.io/badge/Releases-Latest-00d4ff?style=for-the-badge)](https://github.com/web3dev1337/agent-workspace/releases/latest)
 [![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/web3dev1337)
 [![Follow on X](https://img.shields.io/badge/Follow-%40AIOnlyDeveloper-000000?style=for-the-badge&logo=x)](https://x.com/AIOnlyDeveloper)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)
@@ -91,7 +91,7 @@ Compatibility rule: if it can be launched from a terminal command in your worktr
 - **Task Integration** — Pull tasks from Trello and/or use local task records. GitHub Issues and Linear coming soon.
 - **Browser-like Tabs** — Multiple workspaces open simultaneously, each with its own terminals and state.
 - **Runs Locally** — Runs on your hardware. Access through the desktop app or the browser. No publisher-hosted telemetry by default.
-- **Desktop Apps** — Native Tauri builds for Windows and macOS are published on the latest GitHub release.
+- **Desktop Apps** — Windows desktop builds are published on the latest GitHub release. macOS users should run from source until the signed Apple desktop release path is restored.
 
 ## Tier System
 
@@ -119,25 +119,23 @@ Get-AuthenticodeSignature .\downloaded-file.exe
 
 ### macOS
 
-[Download the latest release](https://github.com/web3dev1337/agent-workspace/releases/latest) and grab the `.dmg` build.
-
-Current macOS releases are packaged as Apple Silicon (`aarch64`) disk images. Open the `.dmg`, drag **Agent Workspace** into `Applications`, then launch it from there.
-
-If Gatekeeper blocks the first launch, right-click the app and choose **Open**, or allow it in **System Settings -> Privacy & Security**.
-
-Or run from source:
+Packaged macOS downloads are temporarily unavailable while Apple signing and notarization are being configured. For now, run Agent Workspace from source:
 
 ```bash
 git clone https://github.com/web3dev1337/agent-workspace.git
-cd agent-workspace && npm install
+cd agent-workspace
+npm install
 npm start
 ```
 
-### Mac / Linux / WSL
+Maintainers: see [docs/MACOS_SIGNING_RELEASE_CHECKLIST.md](docs/MACOS_SIGNING_RELEASE_CHECKLIST.md) before publishing the next macOS desktop release.
+
+### Linux / WSL
 
 ```bash
 git clone https://github.com/web3dev1337/agent-workspace.git
-cd agent-workspace && npm install
+cd agent-workspace
+npm install
 npm start
 ```
 

docs/MACOS_SIGNING_RELEASE_CHECKLIST.md

@@ -0,0 +1,102 @@
+# macOS Signing Release Checklist
+
+Use this before shipping another macOS desktop build.
+
+## Why
+
+Unsigned or un-notarized macOS downloads can be blocked by Gatekeeper with messages like:
+
+- `Agent Workspace.app is damaged and can't be opened`
+- `Agent Workspace.app is from an unidentified developer`
+
+The GitHub Actions macOS workflow now expects proper Apple signing and notarization credentials for tag releases.
+
+## GitHub Actions Secrets
+
+Add these repository secrets before cutting the next macOS release.
+
+Required:
+
+- `APPLE_CERTIFICATE`
+- `APPLE_CERTIFICATE_PASSWORD`
+
+Optional but recommended:
+
+- `APPLE_SIGNING_IDENTITY`
+
+Choose one notarization path.
+
+App Store Connect API key path:
+
+- `APPLE_API_KEY`
+- `APPLE_API_ISSUER`
+- `APPLE_API_KEY_BASE64`
+
+Apple ID path:
+
+- `APPLE_ID`
+- `APPLE_PASSWORD`
+- `APPLE_TEAM_ID`
+
+## Secret Formats
+
+`APPLE_CERTIFICATE`
+
+- export the `Developer ID Application` certificate as a `.p12`
+- base64-encode the file contents
+- store the base64 string in the secret
+
+`APPLE_CERTIFICATE_PASSWORD`
+
+- password used when exporting the `.p12`
+
+`APPLE_API_KEY_BASE64`
+
+- base64-encode the `.p8` App Store Connect API key file
+
+`APPLE_SIGNING_IDENTITY`
+
+- optional override
+- example: `Developer ID Application: Your Name (TEAMID)`
+
+## Release Steps
+
+1. Confirm the repo version is ready for release.
+2. Confirm the macOS secrets above are present in GitHub Actions.
+3. Push the release tag.
+4. Wait for `.github/workflows/macos.yml` to finish.
+5. Confirm the workflow passes the `Verify signed + notarized macOS bundle` step.
+6. Confirm the uploaded macOS `.app` and `.dmg` came from that signed workflow run.
+
+## What the Workflow Now Verifies
+
+The release workflow now:
+
+- imports the Apple certificate into a temporary keychain
+- resolves the macOS signing identity
+- passes notarization credentials into the Tauri build
+- validates the built app with `codesign`
+- checks Gatekeeper acceptance with `spctl`
+- validates notarization stapling with `xcrun stapler validate`
+
+If signing or notarization is not configured on a tag release, the macOS workflow fails before publishing assets.
+
+## After Shipping
+
+Test the released macOS artifact on a clean machine:
+
+1. download the `.dmg` from GitHub Releases
+2. move the app into `Applications`
+3. launch it normally
+4. confirm Gatekeeper does not show a damaged/unidentified warning
+
+## Source Install Fallback
+
+Until a signed macOS desktop release is published, direct users to:
+
+```bash
+git clone https://github.com/web3dev1337/agent-workspace.git
+cd agent-workspace
+npm install
+npm start
+```

site/index.html

@@ -108,8 +108,8 @@ <h1 class="mega-title">
           <a class="btn-glow download-btn download-windows" href="https://github.com/web3dev1337/agent-workspace/releases/latest" target="_blank">
             <span>Download for Windows</span>
           </a>
-          <a class="btn-glow download-btn download-mac" href="https://github.com/web3dev1337/agent-workspace/releases/latest" target="_blank" style="display:none">
-            <span>Download for Mac</span>
+          <a class="btn-glow download-btn download-mac" href="#install-mid" style="display:none">
+            <span>Install on Mac</span>
           </a>
           <a class="btn-glow download-btn download-linux" href="#install-mid" style="display:none">
             <span>Install on Linux</span>
@@ -248,20 +248,22 @@ <h2 class="section-title">Install</h2>
 
         <div class="install-panel" id="tab-mac-mid">
           <div class="install-option">
-            <a class="btn-glow install-download" href="https://github.com/web3dev1337/agent-workspace/releases/latest" target="_blank">Download for Mac (Apple Silicon)</a>
-          </div>
-          <p class="install-note">Download the <span class="text-cyan">.dmg</span>, open it, and drag Agent Workspace to Applications.</p>
-          <div class="install-option" style="margin-top: 1.5rem">
-            <span class="btn-outline install-download install-source-label">Or run from source ↓</span>
+            <span class="btn-outline install-download install-source-label">Run from Source on Mac ↓</span>
           </div>
+          <p class="install-note">Packaged macOS downloads are temporarily unavailable while Apple signing and notarization are being configured.</p>
           <div class="install-cmd">
             <code>git clone https://github.com/web3dev1337/agent-workspace.git</code>
             <button class="copy-btn" data-copy="git clone https://github.com/web3dev1337/agent-workspace.git">Copy</button>
           </div>
           <div class="install-cmd">
-            <code>cd agent-workspace && npm install && npm start</code>
-            <button class="copy-btn" data-copy="cd agent-workspace && npm install && npm start">Copy</button>
+            <code>cd agent-workspace && npm install</code>
+            <button class="copy-btn" data-copy="cd agent-workspace && npm install">Copy</button>
+          </div>
+          <div class="install-cmd">
+            <code>npm start</code>
+            <button class="copy-btn" data-copy="npm start">Copy</button>
           </div>
+          <p class="install-note">Opens at <span class="text-cyan">http://localhost:9461</span> in your browser.</p>
         </div>
 
         <div class="install-panel" id="tab-linux-mid">
@@ -461,20 +463,22 @@ <h2 class="section-title">Install</h2>
 
         <div class="install-panel" id="tab-mac">
           <div class="install-option">
-            <a class="btn-glow install-download" href="https://github.com/web3dev1337/agent-workspace/releases/latest" target="_blank">Download for Mac (Apple Silicon)</a>
-          </div>
-          <p class="install-note">Download the <span class="text-cyan">.dmg</span>, open it, and drag Agent Workspace to Applications.</p>
-          <div class="install-option" style="margin-top: 1.5rem">
-            <span class="btn-outline install-download install-source-label">Or run from source ↓</span>
+            <span class="btn-outline install-download install-source-label">Run from Source on Mac ↓</span>
           </div>
+          <p class="install-note">Packaged macOS downloads are temporarily unavailable while Apple signing and notarization are being configured.</p>
           <div class="install-cmd">
             <code>git clone https://github.com/web3dev1337/agent-workspace.git</code>
             <button class="copy-btn" data-copy="git clone https://github.com/web3dev1337/agent-workspace.git">Copy</button>
           </div>
           <div class="install-cmd">
-            <code>cd agent-workspace && npm install && npm start</code>
-            <button class="copy-btn" data-copy="cd agent-workspace && npm install && npm start">Copy</button>
+            <code>cd agent-workspace && npm install</code>
+            <button class="copy-btn" data-copy="cd agent-workspace && npm install">Copy</button>
+          </div>
+          <div class="install-cmd">
+            <code>npm start</code>
+            <button class="copy-btn" data-copy="npm start">Copy</button>
           </div>
+          <p class="install-note">Opens at <span class="text-cyan">http://localhost:9461</span> in your browser.</p>
         </div>
 
         <div class="install-panel" id="tab-linux">
@@ -511,7 +515,7 @@ <h2 class="section-title">Install</h2>
       </div>
       <div class="footer-links">
         <a href="https://github.com/web3dev1337/agent-workspace" target="_blank">GitHub</a>
-        <a href="https://github.com/web3dev1337/agent-workspace/releases/latest" target="_blank">Download</a>
+        <a href="https://github.com/web3dev1337/agent-workspace/releases/latest" target="_blank">Releases</a>
         <a href="https://github.com/web3dev1337/agent-workspace" target="_blank">Run from Source</a>
         <a class="footer-sponsor" href="https://github.com/sponsors/web3dev1337" target="_blank">Sponsor</a>
         <a href="terms.html">Terms</a>

site/llms-full.txt

@@ -58,10 +58,15 @@ Agent Workspace is an open-source, local-first orchestration layer for CLI codin
 ### Windows (recommended)
 - Download: <https://github.com/web3dev1337/agent-workspace/releases/latest>
 
+### macOS
+- Packaged macOS downloads are temporarily unavailable while Apple signing and notarization are being configured.
+- Use the source install flow below for now.
+
 ### Source
 ```bash
 git clone https://github.com/web3dev1337/agent-workspace.git
-cd agent-workspace && npm install
+cd agent-workspace
+npm install
 npm start
 ```