Phase 1 hardening: production-grade workstation packaging

[mdheller]

Problem

Phase 1 is functionally installable, but the current workstation install is still too janky for product use.

Observed macOS validation:

• brew reinstall sourceos-linux/tap/noetica succeeds.
• noetica version, doctor, and smoke --dry-run succeed.
• noetica start reaches Next.js ✓ Ready, which means the foreground server is running.
• However, the command feels like a hang because foreground mode does not clearly tell the operator to open the URL and press Ctrl-C to stop.
• The formula is still installing/running a dev-mode Next app rather than a production-grade release artifact.
• Because Phase 1 uses next dev, dependency handling has already been awkward and too mutable.

Required hardening

1. Make noetica start operator-clear:

   • print Noetica is running at http://127.0.0.1:3737;
   • print Press Ctrl-C to stop foreground mode;
   • optionally suggest noetica open in a second terminal;
   • do this before handing control to Next.

2. Add a non-blocking mode:

   • noetica start --detach, or
   • noetica launch, or
   • a clearer noetica service start path documented as the background path.

3. Stop shipping a dev-mode server as the product path:

   • build a production artifact;
   • install the built app;
   • run next start or a standalone Next server from the installed payload;
   • remove dev dependencies from the runtime formula once this exists.

4. Upgrade Homebrew packaging:

   • formula should consume a release artifact or deterministic built payload;
   • formula should not install mutable runtime dependencies during first run;
   • no brew services path should be introduced.

5. Add local validation commands:

brew reinstall sourceos-linux/tap/noetica
noetica version
noetica doctor --json
noetica smoke --dry-run
noetica start
noetica open
noetica service install
noetica service start
noetica service status
noetica service stop
noetica service uninstall

Acceptance

• brew reinstall sourceos-linux/tap/noetica produces an install that does not mutate itself on first start.
• noetica start has clear foreground semantics.
• Operator does not mistake normal foreground server behavior for a hang.
• noetica open opens the running app.
• Background/service path is documented and works through OS-native service control.
• Production artifact path is defined or implemented.

Boundary

This is Phase 1 hardening before Phase 2. Do not begin deeper SourceOS routing work until the workstation install feels clean.

[mdheller]

Additional UX requirement: Claude-quality startup experience

The hardening bar is not merely that the server runs. noetica start needs to feel like a polished agent workstation tool, comparable to Claude-style CLI ergonomics.

Required startup UX

When the operator runs:

noetica start

Noetica should show a clean startup surface before handing off to the underlying server:

Noetica
Governed workstation UI

Status: starting
URL:    http://127.0.0.1:3737
Mode:   foreground

Open:   noetica open
Stop:   Ctrl-C
Run in background: noetica service install && noetica service start

Then, once ready, the terminal output should make the state obvious:

Noetica is ready at http://127.0.0.1:3737
Press Ctrl-C to stop foreground mode.

Requirements

• Do not expose raw Next.js output as the primary product experience if avoidable.
• The operator should never wonder whether the process is hung.
• The CLI should distinguish foreground mode, background/service mode, and browser-open behavior.
• noetica start should feel intentional, not like a dev server leaking through the product.
• noetica open should be part of the normal startup flow.
• The service path should be presented as the clean non-blocking alternative.

Product standard

We will not win if Noetica feels like a rough wrapper around Next.js. The startup interaction should be as clear and confidence-building as Claude-style tooling: minimal, deliberate, readable, and operationally obvious.

[mdheller]

Additional product target: desktop app, not browser-bound

Important correction: Claude is not merely a browser tab pointed at a local server; the user experience is a desktop app. Noetica needs the same class of experience if it is going to feel credible.

Product requirement

The production workstation target should be a desktop shell, not a browser-bound localhost app.

Acceptable implementation paths:

1. Electron shell

   • closer to the Claude-style desktop model;
   • packages web UI into a native app window;
   • can manage local server lifecycle or embed app runtime;
   • good near-term fit if speed matters.

2. Tauri shell

   • lighter and more SourceOS/Linux-aligned long term;
   • stronger native/packaging posture;
   • may need more integration work depending on local service and webview behavior.

Required UX

• brew install noetica should install a workstation app surface, not only a browser-launched dev server.
• noetica start should either open the app window or clearly delegate to noetica app / noetica launch.
• The normal user path should not require manually opening http://127.0.0.1:3737.
• Browser mode can remain as a dev/admin fallback:
  • noetica start --web
  • noetica open
  • noetica dev
• The primary product path should feel like a desktop agent workstation.

Revised target state

Phase 1 hardening should split runtime modes explicitly:

noetica app        # launch desktop shell; primary UX
noetica start      # start local service/foreground server; operational mode
noetica open       # open web fallback
noetica service    # OS-native background service lifecycle
noetica dev        # developer-mode Next server

Acceptance update

Phase 1 hardening is not complete until we have either:

• an Electron/Tauri desktop shell integrated into the install path; or
• a documented interim release with noetica app stubbed/blocked and browser mode explicitly labeled as temporary/dev fallback.

The strategic product goal is a Claude-class desktop experience, not a localhost browser tool.

[mdheller]

Go-forward execution plan: Tauri-first desktop hardening

Decision: proceed Tauri-first, but with an explicit feasibility gate. Noetica must remain the workstation UX shell; SourceOS / Agent Machine / model-router / policy / memory remain the authority layers.

Target command contract

noetica app        # primary desktop app UX
noetica start      # operational foreground local service/server mode
noetica open       # web fallback
noetica service    # OS-native background service lifecycle
noetica dev        # developer-only Next dev server

Turn 1 — Tauri skeleton / native window

Add:

src-tauri/
src-tauri/Cargo.toml
src-tauri/src/main.rs
src-tauri/tauri.conf.json

Add scripts:

npm run tauri:dev
npm run tauri:build

Acceptance:

• native Noetica window opens on macOS;
• no SourceOS routing work yet;
• browser mode remains fallback;
• no claim that this is production-grade yet.

Turn 2 — Static UI / service-boundary gate

Determine whether current Noetica can build as a Tauri-compatible static frontend.

Acceptance:

• either next export/static output path works; or
• we have a concrete blocker list of server/API/SSR dependencies that must move into a local service or SourceOS-owned endpoint.

Decision gate:

Continue Tauri if:
  native shell opens
  static UI path is viable
  local-service boundary is manageable

Fallback to Electron only if:
  Tauri blocks desktop delivery for >2-3 turns
  or static export requires a large rewrite before any desktop shell can ship

Turn 3 — CLI product semantics

Add/refactor commands:

noetica app
noetica web
noetica dev

Reclassify noetica start as operational mode, not the main product path.

Acceptance:

• noetica app is the primary UX command;
• noetica dev is the only command that looks like a raw Next dev server;
• operator-facing startup text is Claude-class clear.

Turn 4 — Local service boundary

Define the minimal local service contract needed by Tauri:

config status
provider status
provider smoke request
SourceOS route status placeholder
Agent Machine readiness placeholder

Acceptance:

• Noetica does not become Agent Machine-lite;
• any local Noetica service is explicitly transitional/thin;
• authority remains delegated outward as soon as SourceOS/Agent Machine endpoints exist.

Turn 5 — Packaging split decision

Decide between:

sourceos-linux/tap/noetica        CLI + service tooling
sourceos-linux/tap/noetica-app    desktop app/cask-style package

or a combined package.

Acceptance:

• Homebrew install path no longer presents a browser/dev-server as the product UX;
• no brew services path;
• OS-native service control remains inside noetica service ....

Turn 6 — UX polish pass

Expected startup surface:

Noetica
Governed workstation UI

Status: Ready
Mode: Desktop
Provider: Not configured
Agent Machine: Not detected
SourceOS route: Disabled

Acceptance:

• no raw Next.js output in primary UX;
• app tells the user what is configured, missing, or deferred;
• empty state guides setup without requiring JSON editing.

Turn 7 — Phase 1H closeout

Close hardening only when:

• noetica app launches native desktop app;
• browser mode is fallback, not primary;
• noetica dev is developer-only;
• install path does not mutate itself on first run;
• service/background path is clear;
• desktop UX is credible enough to continue to Phase 2.

Estimates

Best case: 4 turns
Expected: 6-7 turns
Worst case: 9-10 turns if static export forces service refactor immediately

Strategic rule

Do not start deeper SourceOS routing work until this desktop shell is credible. Serious substrate under an amateur entrypoint is not acceptable.

[mdheller]

UX north star: Claude-class shell + Gemini-class administration + SourceOS OS agent

Reference screenshots provided by Lord Michael define three invariant top-level surfaces:

Chat
Cowork
Code

Important boundary: we are not cloning Claude branding or proprietary visual assets. We are treating these screenshots as invariant interaction architecture: desktop app shell, mode topology, sidebar hierarchy, command composer, status surfaces, and work-mode affordances. Noetica must retain its own identity, language, iconography, and SourceOS governance semantics.

Primary product direction

Noetica Desktop must feel like a native agent workstation, not a localhost web app.

noetica app        # primary desktop experience
noetica web        # browser fallback
noetica dev        # raw Next dev server only
noetica service    # OS-native background service lifecycle
noetica start      # operational foreground runtime, not primary UX

Invariant surface 1: Chat

Purpose: everyday conversational agent mode.

Required layout:

• Native desktop window chrome.
• Dark, low-contrast, calm surface.
• Left sidebar with mode switcher: Chat / Cowork / Code.
• Primary action: New chat / New session.
• Secondary actions: routines, customization, more/settings.
• Recent conversations area.
• Account/org selector at bottom.
• Main panel greeting and empty state.
• Bottom composer with text input, attachment/tool affordances, model/status selector, send affordance.

Noetica-specific additions:

• Governance state visible but unobtrusive.
• Provider route status: configured/missing/deferred/local.
• SourceOS route status.
• Agent Machine readiness status.
• Prophet Mesh status as deferred until live.

Invariant surface 2: Cowork

Purpose: task/project execution mode.

Required layout:

• Same desktop shell and sidebar.
• Mode switcher: Chat / Cowork / Code.
• Primary action: New task.
• Navigation: Projects, Scheduled, Live artifacts, Dispatch, Customize.
• Recent tasks and active work items.
• Central task composer with large prompt card.
• Work context selector: project/workspace.
• Action mode selector: ask/execute/dispatch.
• Model/effort selector.
• Suggested task cards / templates.

Noetica-specific additions:

• SourceOS job/route surface.
• AgentPlane/receipt placeholders where execution evidence is required.
• Policy admission status.
• Memory scope status.
• Dispatch is tied to SourceOS/Agent Machine capability, not a mock success path.

Invariant surface 3: Code

Purpose: local coding/operator mode.

Required layout:

• Same desktop shell and sidebar.
• Mode switcher: Chat / Cowork / Code.
• Primary action: New session.
• Routines/customize/more navigation.
• Session recents area.
• Central status/analytics card area.
• Local/project folder selector.
• Bottom code/task composer.
• Accept edits control row.
• Model/effort/status indicators.

Noetica-specific additions:

• Local repo/project binding.
• Agent Machine coding readiness.
• SourceOS local workspace awareness.
• Git/GitHub state integration later.
• Audit/receipt state for generated edits.

Gemini-class office / administration layer

Noetica needs first-class office/admin workflows, not only chat/coding.

Target capabilities:

calendar/meetings
mail/message triage
docs/sheets/slides-style document operations
summaries and briefings
task capture and follow-through
project/admin dashboards
workspace search
people/org context
meeting prep and follow-up
policy-aware delegated actions

This should appear primarily inside Cowork and Chat, not as random tools buried in settings.

Suggested first-class objects:

Person
Meeting
Task
Project
Document
Thread
Decision
Brief
Artifact
Workflow

UI modules:

• Today / Agenda card.
• Inbox / attention card.
• Docs / artifacts card.
• Tasks / commitments card.
• Follow-up / delegation card.
• Admin routines.

OS-first SourceOS / Linux agent layer

Noetica also needs OS-native agency, analogous in ambition to a desktop assistant, but SourceOS/Linux-first rather than consumer Siri-like behavior.

Target capabilities:

open apps and workspaces
inspect local system state
manage files/projects with policy boundaries
control SourceOS services
query Agent Machine status
route work to local/hosted providers
surface notifications and scheduled work
invoke safe OS actions through explicit permissions

This layer must be capability-gated. No broad shell power by default.

UI surfaces:

• OS status capsule.
• Device/workstation readiness panel.
• SourceOS services panel.
• Agent Machine status panel.
• Local model/provider inventory.
• Permission prompts for device-level actions.

Visual and interaction standard

The target is Claude-class polish:

• native desktop shell;
• quiet dark interface;
• strong left navigation hierarchy;
• mode switcher always visible;
• bottom composer as primary interaction affordance;
• clear empty states;
• no raw server output in product path;
• no browser/localhost ceremony as primary UX;
• no confusing foreground/background behavior;
• mode-specific affordances are obvious.

Noetica identity requirements:

• use Noetica/SourceOS language;
• no Claude branding;
• no Claude icon assets;
• own color/token/icon system;
• governance/SourceOS concepts should feel native, not bolted on.

Build strategy

1. Use Tauri feasibility shell to establish native desktop window.
2. Build a Noetica shell layout that implements Chat/Cowork/Code topology.
3. Make browser mode fallback only.
4. Move server/API authority behind service/SourceOS/Agent Machine boundaries as needed.
5. Add office/admin modules as first-class Cowork/Chat surfaces.
6. Add SourceOS OS-agent capabilities behind explicit permissions.

Acceptance criteria for this UX tranche

• noetica app opens a native desktop app window.
• The app has the three invariant top-level modes: Chat, Cowork, Code.
• Sidebar, mode switcher, composer, recents, account/org area, and status affordances exist.
• Browser mode is clearly secondary.
• Noetica has its own visual identity.
• Office/admin layer is represented as first-class workflow objects and cards.
• SourceOS/Agent Machine/OS-agent state is visible but not falsely live.
• No raw Next.js output appears in primary product path.

Key product rule

We are not competing with browser tabs. We are building a governed operating workstation. The desktop shell must make that obvious on first launch.

[mdheller]

Local build-readiness evidence — macOS

Fresh local validation completed successfully from a clean clone.

Successful command sequence:

npm install
npm run cli:doctor
npm run cli:smoke
npm run sourceos:events:path:check
npm run sourceos:events:export
npm run icons:generate
npm run packaging:validate
npm run typecheck
npm run lint
npm run build
npm run build:static
npm run tauri:build:static
npm run cli -- app

Observed result:

• CLI doctor returned status: ok.
• CLI smoke returned status: ok.
• SourceOS event path/export checks passed.
• Icon generation passed for placeholder SVG outputs.
• Packaging metadata validation passed.
• Typecheck passed.
• Lint passed with no warnings or errors.
• Standard Next build passed.
• Static Next build passed.
• Tauri static build produced a release binary.
• noetica app launched the Tauri dev shell and served the local app.

Residual warning:

• Tauri warns that the bundle identifier ends with .app; this should be fixed before production packaging/signing.

Interpretation:

• Phase 1H local build-readiness is achieved.
• Desktop launch-readiness is achieved for the dev shell path.
• Production packaging is still open: bundle output remains disabled, signing/notarization are not implemented, final PNG/ICNS assets remain pending, and release provenance/SBOM/update-channel work remains out of scope for this pass.

Recommended next tranche:

1. Decide and patch the stable bundle identifier.
2. Decide whether Phase 1H should enable unsigned bundle artifact generation.
3. Preserve the current dev-shell success path while adding artifact-output validation.
4. Keep signing/notarization as a later production release tranche.

[mdheller]

Triage — Phase 1 production-grade packaging: Correctness/hardening. noetica start feels like a hang due to missing foreground-vs-daemon UX. Recommend: add a startup banner showing readiness, implement noetica stop / noetica status for the service lifecycle, and document the expected user flow.