Merlin started as a developer tool you ran from a repo. That was the right shape while we were proving the agent loop: specs loaded into context, fledge lanes as the verifier, plugins as the tool surface, multiple providers behind one CLI.

The next milestone changes the product shape. Merlin is becoming an app-first client with a managed CLI attached to it.

That distinction matters. The end-user version should not assume a cloned Merlin checkout, a hand-edited .env, or knowledge of where the plugin runtime lives. An approved tester should be able to receive the app, add provider keys securely, open a project, install the CLI from the app, and run merlin from any folder on the machine.

We are not calling this a public launch yet. The next release target is an invite-only internal alpha for Apple Silicon Macs.

What changed

The packaging path now builds a real Merlin.app bundle with the desktop UI, the merlin CLI, bundled plugins, runtime metadata, icon assets, and a DMG layout that includes the Applications shortcut. The release lane is designed to answer the boring questions before anyone gets a build:

  • Does the app bundle launch outside the repo?
  • Does the managed CLI install as ~/.local/bin/merlin?
  • Does the CLI find the bundled runtime and official plugins from a random project folder?
  • Does merlin doctor explain runtime source, plugin availability, key source, and CLI install state?
  • Does the app keep provider keys in the OS keychain instead of scattering secrets through local project files?

The important internal move is runtime resolution. The app-installed CLI can find merlin-runtime/plugins and merlin-runtime/target/release from the app bundle layout, while source checkouts still behave like source checkouts. MERLIN_RUNTIME_ROOT exists as an explicit override, and MERLIN_HOME remains the legacy checkout override rather than being repurposed for app bundles.

Why the CLI is managed by the app

The CLI is still load-bearing. Merlin is not turning into a desktop-only tool. But a final user app needs one owner for install and update state, and that owner should be the app.

The desktop can show whether the CLI is installed, where it points, whether ~/.local/bin is on PATH, and whether a new app release is available. It can also install the CLI as a symlink to the bundled binary, then verify the result with merlin --version and a runtime/plugin check.

We are intentionally not editing shell rc files automatically. If ~/.local/bin is missing from PATH, Merlin shows copyable shell guidance and lets the user choose how to apply it.

Keys are product surface now

Secure key storage used to be a CLI feature. It is now part of onboarding.

Provider readiness in the desktop checks the same credential resolver the agent uses: environment, .env, and OS keychain/keyring sources are reported as credential status rather than guessed through raw environment checks. That means the app can tell the truth when a key is set globally in the keychain and the current shell does not expose it as an environment variable.

The current model is bring-your-own provider keys. No Corvid account billing, no hidden proxy, no hosted key vault in this milestone.

Memory is identity

The alpha also hardens Merlin’s memory model. Memory is not just a search box over old summaries; it is keyed context for users, projects, conversations, decisions, feedback, releases, benchmark findings, and agent workflow lessons.

The memory plugin now supports exact lookup, key-family prefix lookup, and broad content search. That gives the agent a stable path: try a known key, then a family like user-leif or project-merlin, then fall back to content search only when the key family is unknown.

This matters for app-first Merlin because approved testers should not have to keep re-explaining the same preferences and project facts. The app and CLI can share the same memory-backed identity layer while still keeping provider keys in the OS keychain.

What is still being gated

After the latest desktop and GitHub Pages polish, the alpha gate is mostly packaging and smoke testing:

  • Build the macOS release lane from a fresh main.
  • Open the DMG and verify the icon, Applications shortcut, and app metadata.
  • Launch the app and complete onboarding.
  • Save a provider key, restart, and confirm the key source still resolves.
  • Install the CLI from the app.
  • Run merlin --version, merlin doctor, and a provider-backed chat from a folder with no Merlin checkout.
  • Save and recall memories by exact key, key-family prefix, and broad query across multiple providers.
  • Run the UI snapshot suite across the desktop panels and keep contrast/readout quality high enough that the app feels like a product, not a debug harness.
  • Keep the homepage and docs private-alpha positioned: no public download CTA until the signed build pipeline and tester workflow are boring.

Linux follows the same model later with an AppImage and managed CLI symlink. The current release workflow only keeps Linux CLI tarballs alive; the first public Linux app target is x86_64 unless runner availability says otherwise.

AlgoChat is deliberately not part of the 1.0 critical path. The Rust-native plugin is now documented as a preview / 1.1+ feature; transaction signing and submission need their own golden-vector and live-network validation before they graduate.

The shape of the alpha

The alpha is for proving the end-user loop:

  1. Download a signed/notarized Apple Silicon DMG.
  2. Drag Merlin into Applications.
  3. Open the app, add provider keys, and pick a project.
  4. Install the CLI from the app.
  5. Use the same Merlin from the GUI and terminal.

That is the release we are trying to make boring. Once that loop is boring, the rest of the product work gets much easier.

What comes next

The next planning slice should stay narrow:

  1. Release candidate smoke: build from fresh main, open the DMG, launch the app, save a key, install the CLI, run merlin doctor, and complete one provider-backed chat.
  2. Distribution matrix: close the macOS Apple Silicon lane first, keep CLI tarballs alive, then design the Linux AppImage lane as the follow-up.
  3. Docs and positioning: keep GitHub Pages focused on private alpha until public distribution exists; publish install copy only when a tester can actually follow it end to end.
  4. 1.0 issue triage: work through the open 1.0 tickets in order: security sign-off, observability, distribution, compatibility, spec stabilization, then docs launch.

— The Merlin team