Merge pull request #68 from TrentBrown/tb-portreeve-public-install-docs

Document public PortReeve installation paths

Author: TrentBrown

README.md

@@ -3,16 +3,38 @@
 > [!WARNING]
 >
 > **Alpha Preview** — PortReeve is evolving quickly. Breaking changes remain possible,
-> and the first macOS preview downloads will be unsigned until Apple Developer ID
-> signing and notarization are configured. No public preview has been published yet;
-> current users should build from source. See the
-> [preview installation and removal guide](docs/installation.md) before installing a
-> future preview.
+> and the current macOS preview is unsigned until Apple Developer ID signing and
+> notarization are configured. Review the
+> [installation and removal guide](docs/installation.md), including the scoped macOS
+> **Open Anyway** procedure, before installing it.
 
 <p align="center">
   <img src="apps/desktop/assets/branding/portreeve-lockup.svg" width="570" alt="PortReeve, Local Port Authority">
 </p>
 
+## Install the alpha preview
+
+The current public alpha preview is available on
+[GitHub Releases](https://github.com/TrentBrown/portreeve/releases). On macOS, install
+the graphical application with Homebrew after reviewing and narrowly trusting its cask:
+
+```sh
+brew tap TrentBrown/portreeve
+brew trust --cask trentbrown/portreeve/portreeve-app
+brew install --cask trentbrown/portreeve/portreeve-app
+```
+
+For terminal and MCP use, install the standalone CLI independently:
+
+```sh
+brew trust --formula trentbrown/portreeve/portreeve
+brew install trentbrown/portreeve/portreeve
+```
+
+Homebrew does not silently install or start the supervised service. Direct macOS DMGs,
+Linux executables, checksum verification, unsigned-app guidance, and removal procedures
+are covered in the [installation guide](docs/installation.md).
+
 <!-- product-overview:identity-problem -->
 
 ## Localhost port conflicts, solved
@@ -29,10 +51,9 @@ copy naturally reaches for the same ports.
 PortReeve replaces duplicated startup-time probing and remapping with one shared,
 inspectable source of truth.
 
-> **Want to try it?**
-> [Build and open PortReeve Desktop](#build-and-open-portreeve-desktop). Desktop is the
-> primary visual experience; CLI, MCP, and JavaScript clients remain independent
-> first-class ways to use the same authority.
+> **Want to try it?** [Install the alpha preview](#install-the-alpha-preview) and open
+> PortReeve from Applications. Desktop is the primary visual experience; CLI, MCP, and
+> JavaScript clients remain independent first-class ways to use the same authority.
 
 ![PortReeve Desktop open to Overview, showing the product header and “What is PortReeve?” introduction](docs/assets/portreeve-desktop-overview.png)
 
@@ -262,11 +283,18 @@ Sandbox orchestration or integration.
 
 PortReeve sends no telemetry and does not load project `.env` files.
 
-### Build and open PortReeve Desktop
+### Open PortReeve Desktop
 
-PortReeve has not published its first npm package, Homebrew release, GitHub Release, or
-packaged macOS download yet. Until then, build on macOS from the public source
-repository with the pinned Bun 1.3.14 toolchain:
+Install the current preview through [Homebrew](#install-the-alpha-preview) or download
+the architecture-specific DMG from the
+[GitHub Releases page](https://github.com/TrentBrown/portreeve/releases), then open
+**PortReeve** from Applications. In Desktop, open **Service** and choose **Install and
+Start PortReeve** to place the verified bundled CLI in its managed per-user location and
+configure `launchd`. Then use **Quick Start** to try one existing project or
+**Integrations** to connect a stack.
+
+To build Desktop from source instead, use the public repository and pinned Bun 1.3.14
+toolchain:
 
 ```sh
 git clone https://github.com/TrentBrown/portreeve.git
@@ -277,28 +305,29 @@ bun run build
 PORTREEVE_DESKTOP_CLI_PATH="$PWD/dist/portreeve" bun run desktop:start
 ```
 
-In Desktop, open **Service** and choose **Install and Start PortReeve** to place the
-verified executable in its managed per-user location and configure `launchd`. Then use
-**Quick Start** to try one existing project or **Integrations** to connect a stack.
-
 ### Use PortReeve without Desktop
 
-The same build provides a foreground server and the complete CLI:
+The Homebrew formula, direct macOS/Linux downloads, and source build all provide the
+same complete CLI. Run a temporary foreground server with:
 
 ```sh
-./dist/portreeve serve
+portreeve serve
 ```
 
 Or install the supervised per-user service directly:
 
 ```sh
-./dist/portreeve install
-./dist/portreeve start
-./dist/portreeve status --json
+portreeve install
+portreeve start
+portreeve status --json
 ```
 
+For a source build, substitute `./dist/portreeve`; for example,
+`./dist/portreeve status --json`.
+
 Installation does not require root. PortReeve uses `launchd` on macOS and
-`systemd --user` on Linux.
+`systemd --user` on Linux. The JavaScript client archive is retained in the release
+evidence, but npm publication remains deferred.
 
 ## Documentation
 

docs/installation.md

@@ -2,16 +2,16 @@
 
 > **Alpha Preview**
 >
-> PortReeve is evolving quickly and may make breaking changes. No public preview has
-> been published yet. When the first preview is published, its macOS application will
-> be unsigned until Apple Developer ID signing and notarization are configured. Product
-> maturity (`alpha`), release channel (`preview`), and macOS trust (`unsigned`) are
-> separate facts.
+> PortReeve is evolving quickly and may make breaking changes. The current public alpha
+> preview is available on
+> [GitHub Releases](https://github.com/TrentBrown/portreeve/releases), and its macOS
+> application is unsigned until Apple Developer ID signing and notarization are
+> configured. Product maturity (`alpha`), release channel (`preview`), and macOS trust
+> (`unsigned`) are separate facts.
 
-Until a preview appears on [GitHub Releases](https://github.com/TrentBrown/portreeve/releases),
-use the [source build](#build-from-source). The commands in the download sections below
-describe the prepared public-preview paths; they are not evidence that those downloads
-already exist.
+Use [GitHub Releases](https://github.com/TrentBrown/portreeve/releases) to identify the
+newest preview and verify its assets. The commands below install the currently published
+Homebrew, DMG, and direct-download artifacts.
 
 ## Choose an installation path
 
@@ -20,7 +20,7 @@ already exist.
 | macOS graphical application | Homebrew cask | `PortReeve.app`; service setup remains explicit in Desktop |
 | macOS graphical application without Homebrew | Architecture-specific DMG | `PortReeve.app`; service setup remains explicit in Desktop |
 | macOS or Linux terminal/MCP use | Homebrew formula on macOS or direct CLI download | One standalone `portreeve` executable |
-| Current development before the first preview | Source build | Local development CLI and Desktop |
+| Contributor development or an unreleased change | Source build | Local development CLI and Desktop |
 
 There is one PortReeve installation and one per-user registry. Desktop, CLI, MCP, and
 the JavaScript client are peer clients of the same server; installing Desktop does not
@@ -32,22 +32,28 @@ If Homebrew is not installed, follow [Homebrew's maintained installation
 instructions](https://docs.brew.sh/Installation). Review Homebrew's installer and its
 requested filesystem changes before running it.
 
-After a PortReeve preview is published, add the personal tap and install either or both
-artifacts:
+Add the personal tap, review the requested artifact, and trust only the formula or cask
+you intend to install. Current Homebrew releases require explicit trust for third-party
+taps and otherwise refuse to load PortReeve. Specific-artifact trust is narrower than
+trusting every current and future artifact in the tap.
 
 ```sh
 brew tap TrentBrown/portreeve
 
 # Graphical application
-brew install --cask portreeve-app
+brew trust --cask trentbrown/portreeve/portreeve-app
+brew install --cask trentbrown/portreeve/portreeve-app
 
 # Standalone CLI and MCP bridge
-brew install portreeve
+brew trust --formula trentbrown/portreeve/portreeve
+brew install trentbrown/portreeve/portreeve
 ```
 
 The cask moves `PortReeve.app` into Applications. The formula installs the CLI. Neither
 one silently installs or starts the PortReeve supervised service, and neither one
-deletes PortReeve data during routine uninstall.
+deletes PortReeve data during routine uninstall. See Homebrew's
+[Tap Trust](https://docs.brew.sh/Tap-Trust) documentation before choosing broader
+whole-tap trust.
 
 ## Direct macOS DMG
 
@@ -56,9 +62,10 @@ GitHub Releases provides separate images:
 - `PortReeve-VERSION-macos-arm64.dmg` for Apple Silicon;
 - `PortReeve-VERSION-macos-x64.dmg` for Intel Macs.
 
-Download the matching DMG and `SHA256SUMS-DISTRIBUTION`, compare the recorded checksum,
-open the DMG, and drag **PortReeve** to Applications. The DMG installs no daemon and
-runs no package script.
+Download the matching DMG and `SHA256SUMS-DISTRIBUTION` from the
+[GitHub Releases page](https://github.com/TrentBrown/portreeve/releases),
+compare the recorded checksum, open the DMG, and drag **PortReeve** to Applications. The
+DMG installs no daemon and runs no package script.
 
 ```sh
 shasum -a 256 PortReeve-VERSION-macos-ARCH.dmg

docs/product-overview-contract.md

@@ -8,8 +8,8 @@ order, diagrams, interaction, and layout to their respective surfaces.
 
 - **README** serves repository discovery and evaluation. It gives a complete
   product introduction, makes Desktop tangible, provides a truthful primary
-  path to build and open Desktop, and preserves visible CLI, MCP, and JavaScript
-  alternatives.
+  path to install and open the current Desktop preview, retains a contributor
+  source-build path, and preserves visible CLI, MCP, and JavaScript alternatives.
 - **Desktop Overview** serves in-application orientation and continued use. It
   presents the same product model through native interaction and links users to
   the installed application's client and workflow destinations.
@@ -88,9 +88,9 @@ evidence- and ownership-bound.
 ### `boundaries-next-step`
 
 State what PortReeve deliberately does not own. Continue with the
-surface-appropriate action: README truthfully builds and opens Desktop from
-source until a package exists; Desktop leads into installed workflows. Preserve
-CLI, MCP, and JavaScript alternatives on both surfaces.
+surface-appropriate action: README truthfully installs and opens the published
+Desktop preview while retaining a source-build path; Desktop leads into installed
+workflows. Preserve CLI, MCP, and JavaScript alternatives on both surfaces.
 
 - README landmark: `<!-- product-overview:boundaries-next-step -->`
 - Desktop landmark: `data-product-overview-topic="boundaries-next-step"`

test/docs/product-overview-parity.test.js

@@ -101,8 +101,9 @@ test('README keeps truthful Desktop and peer-client continuation paths', async (
   ]) {
     expect(readme).toContain(command);
   }
-  expect(readme).toContain('packaged macOS download yet');
-  expect(readme).not.toContain('Download PortReeve for macOS');
+  expect(readme).toContain('Install the alpha preview');
+  expect(readme).toContain('brew install --cask trentbrown/portreeve/portreeve-app');
+  expect(readme).toContain('current public alpha preview');
   expect(readme).not.toContain('npm install portreeve');
   for (const client of ['Desktop', 'MCP', 'CLI', 'JavaScript client']) {
     expect(readme).toContain(client);

test/release/documentation.test.js

@@ -96,7 +96,8 @@ test('README is a truthful product landing page for the four peer clients', asyn
   }
   expect(readme).toContain('bun install --frozen-lockfile');
   expect(readme).toContain('./dist/portreeve status --json');
-  expect(readme).toContain('has not published its first npm package');
+  expect(readme).toContain('brew install --cask trentbrown/portreeve/portreeve-app');
+  expect(readme).toContain('npm publication remains deferred');
   expect(readme).toMatch(/does not currently\s+provide Docker\s+Sandbox/u);
   expect(readme).not.toContain('npm install portreeve');
 });
@@ -149,8 +150,8 @@ test('README and every Desktop view carry a persistent truthful Alpha Preview no
   const alpha = readme.indexOf('**Alpha Preview**');
   expect(alpha).toBeGreaterThan(0);
   expect(alpha).toBeLessThan(readme.indexOf('portreeve-lockup.svg'));
-  expect(readme).toContain('No public preview has been published yet');
-  expect(readme).toContain('macOS preview downloads will be unsigned');
+  expect(readme).toContain('current macOS preview is unsigned');
+  expect(readme).toContain('current public alpha preview');
   expect(desktop).toMatch(
     /<header class="app-header">[\s\S]*class="alpha-preview"[\s\S]*Alpha Preview[\s\S]*Product maturity is alpha[\s\S]*<\/header>/u,
   );
@@ -168,7 +169,13 @@ test('preview installation guidance is safe, scoped, and lifecycle explicit', as
     readFile(resolve('scripts/desktop-release-lib.js'), 'utf8'),
   ]);
   const combined = [readme, installation, releasing, caskSource].join('\n');
-  expect(installation).toContain('brew install --cask portreeve-app');
+  expect(installation).toContain(
+    'brew trust --cask trentbrown/portreeve/portreeve-app',
+  );
+  expect(installation).toContain(
+    'brew install --cask trentbrown/portreeve/portreeve-app',
+  );
+  expect(installation).toContain('brew trust --formula trentbrown/portreeve/portreeve');
   expect(installation).toContain('PortReeve-VERSION-macos-arm64.dmg');
   expect(installation).toContain('System Settings');
   expect(installation).toContain('Privacy & Security');