@phreshos/cli 0.1.41 → 0.1.43

package/README.md

@@ -1,448 +1,101 @@
-# @phreshos/cli
+# `@phreshos/cli`
 
-The `phresh` command for creating and operating Programs, and for installing
-and managing the PhreshOS System on the current machine.
+The `phresh` command for creating and operating Programs and managing the
+PhreshOS System on the current machine.
 
-## Package status
+The CLI uses the same public System interface as the Node and Server SDKs. It
+adds command parsing, terminal presentation, project workflows, packaging, and
+native service management.
 
-This package is one component of a larger architecture that is still under
-active testing. The architecture's components will be released in stages as
-their contracts and integrations are verified.
+## Installation
 
-`@phreshos/cli` is not intended to be used independently of that architecture.
-Its Program commands use `@phreshos/node`, whose `Project` model owns local
-project behavior and whose `System.connect()` provides the same Core contract
-used inside Server Programs. Runtime operations require a compatible System.
+| Package manager | Command |
+| --- | --- |
+| npm | `npm install --global @phreshos/cli` |
+| pnpm | `pnpm add --global @phreshos/cli` |
+| Bun | `bun add --global @phreshos/cli` |
+| Yarn Classic | `yarn global add @phreshos/cli` |
 
-```bash
-phresh create app # create a complete new Program
-phresh init     # describe this program, once
-phresh pack     # run the optional build, then package its result
-phresh install  # lay this program out on this machine
-phresh uninstall # remove its installed form
-phresh start    # run what your build left, and stay with it
-phresh dev      # run from source, and stay with it
-phresh system status # inspect the local System and its background service
-phresh program list # inspect authoritative state in the running System
-phresh describe endpoint ask # read one capability's exact contract
-```
+Node.js 20.10 or newer is required.
+
+## Program projects
 
-`phresh --help` lists them, `phresh <command> --help` explains one, and
-`phresh --version` says which CLI you have. `phresh describe [path...]` exposes
-the same complete command tree as machine-readable contracts. Nothing is guessed: an
-unknown command, an unknown flag and a malformed option are each refused
-and named.
+```sh
+phresh create
+phresh init
+phresh dev
+phresh start
+phresh install
+phresh uninstall
+phresh pack
+```
 
-Program authoring commands act on the current project when no Program name is
-provided. `install` and `uninstall` accept a direct Program name. Running-System
-capabilities live in the top-level `program`, `process`, `endpoint`, and `window`
-namespaces. System execution and native lifecycle remain isolated under
-`phresh system`.
+`create` produces the official starter Program. The remaining commands operate
+on the current Program project, derive its concrete definition, and delegate
+runtime operations to the connected System.
 
-## System lifecycle
+## System
 
-```bash
+```sh
 phresh system install
-phresh system uninstall
 phresh system status
-phresh system version
 phresh system start
 phresh system stop
 phresh system enable
 phresh system disable
+phresh system uninstall
 ```
 
-`install` resolves the newest compatible stable release from the official
-[`PhreshOS/system`](https://github.com/PhreshOS/system) GitHub Releases. It
-downloads the production archive and adjacent checksum, verifies every byte,
-installs production dependencies into a staged version directory, atomically
-points the stable `current` path at it, then registers, enables, and starts the
-native per-user service. The selected release and the service entry therefore
-cannot become two competing sources of truth if installation is interrupted.
-It never reads a source checkout and never requires Bun or TypeScript.
-
-The System runs under `launchd` on macOS, a real `systemd --user` manager on
-Linux, and a least-privilege per-user scheduled task on Windows. In Linux
-containers with no init manager, it runs as a detached user-owned background
-process that survives the terminal but ends with the container. Automatic
-startup is unavailable there rather than being reported as enabled. `start`
-and `stop` change current execution only; where a native manager exists,
-`enable` and `disable` change automatic startup only. Successful installation
-and startup show the desktop address. `status` reports that same address with
-the installed version, service readiness, and automatic startup without
-changing them; `version` reports only the installed System release.
-
-Installation files and persistent System state have separate homes. Removing
-the System unregisters its service and removes its release files while keeping
-`~/.phreshos`, including Programs and owner data. The owner-local gateway uses an
-owner-only socket file on POSIX and an owner-created duplex named pipe on
-Windows; neither becomes a network endpoint or introduces a bearer secret.
-
-## create
-
-`phresh create <directory>` creates a complete Server and Client Program from
-the maintained `PhreshOS/phresh-program` repository. The CLI build downloads
-the newest complete stable release, validates its source identity and version,
-removes repository-only material, and bundles that exact authoring project.
-The resolved source digest is recorded with the bundle. The installed CLI
-therefore creates projects offline without reading a live branch or maintaining
-a release pin or second template by hand.
-
-The directory name becomes the stable kebab-case Program identity. In a
-terminal, `create` asks for the directory when it is omitted, the readable
-Program name, and the package manager. With no terminal, the directory is the
-first argument and every optional choice is named:
-
-```bash
-phresh create status-board \
-    --name "Status Board" \
-    --package-manager npm
-```
-
-Dependencies are installed by default. `--no-install` creates the same valid
-project and leaves installation as the first reported next step. Generated and
-initialized Programs always use the published package ranges embedded in the
-CLI; repository layout never changes dependency meaning.
-
-## Saying something to a program you start
-
-```bash
-phresh dev --run-option-path=/notes.md --run-option-line=42
-```
-
-Read back by name, on either half:
-
-```ts
-const path = await context.option("path")
-```
-
-**Options are text, all of them.** An option must mean the same thing
-however the process was started, and a command line can only hand over
-text — a number made here would be a guess about your program's meaning
-by the one party with no way to know it. Is `--run-option-id=007` seven,
-or a string with two noughts in front? Only your program knows, so your
-program decides: `Number(...)`, once, where the meaning is.
-
-Which is what argv and the environment have always been, for the same
-reason. The prefix is long because these share a line with the tool's
-own flags, and a program wanting an option called `client` should not
-have to fight the CLI for the word.
-
-## phresh.config is not a program's configuration
-
-A program's configuration is **derived** from it — three times, and the
-derivations differ only in where each half is said to be. That is the
-rule everything else here follows from.
-
-It follows that every field which lands in a `program.json` is spelled
-the way the contract spells it and crosses untouched: `size`, not a
-width and a height; `startCommand` or `entryFile`, not a generic command.
-
-An optional top-level `buildCommand` is authoring metadata. `phresh start`,
-`phresh install`, and `phresh pack` run it from this project before consuming
-the production files. It never crosses into `program.json` or the system.
-`phresh dev` uses the development declarations and does not build.
-
-Everything else is yours: where each half is left.
-
-```ts
-import { defineConfig } from "@phreshos/core"
-
-export default defineConfig({
-
-    identity: "file-manager",      // kebab-case: the program's stable address
-
-    name: "File Manager",          // what a person reads
-
-    version: "0.1.0",
-
-    description: "A file manager",
-
-    icon: "icon.png",
-
-    categories: ["Utilities"],
-
-    keywords: ["files", "storage"],
-
-    website: "https://example.com/file-manager",
-
-    buildCommand: "bun run build",
-
-    server: {
-
-        location: "build/server",
-
-        installCommand: "npm ci",
-
-        uninstallCommand: "npm run clean:external",
-
-        startCommand: "node main.js",
-
-        development: {
-
-            startCommand: "tsx server/main.ts"
-        }
-    },
-
-    client: {
-
-        location: "dist",
-
-        size: { width: "1/2", height: 440 },
-
-        position: { x: 60, y: 40 },
-
-        development: {
-
-            url: "http://localhost:5173",
-
-            startCommand: "bun run dev"
-        }
-    }
-})
-```
-
-**`identity` identifies; `name` is read.** The identity is kebab-case
-because it is also the directory the system lays your program out in, so
-it is a path component before anything else. The name is free-form,
-identifies nothing, and absent means the identity serves for both.
-
-`identity`, `version` and `description` begin from your `package.json`
-during `init`; the readable `name` is asked for. They are written into
-the config rather than read from the manifest later. `pack` says so if
-the two versions have drifted apart.
-
-A window's `size` and `position` are finite pixel numbers or linear
-expressions. Fractions and percentages are equivalent relative terms, so
-`"1/2"` and `"50%"` mean the same thing; pixel offsets may be combined with
-them, as in `"50% + 10"`. Every value survives derivation unchanged.
-
-## development — what `phresh dev` needs
-
-`phresh init` offers to configure development for each declared half. It uses
-the project's `dev` script as a suggested command when one exists, but records
-nothing unless the author chooses it. If development is left unconfigured,
-`phresh dev` refuses and names the declarations it needs:
-
-```
-Nothing here says how this program is developed.
-
-Say how the server runs or where the client is served:
-
-    server: { …, development: { startCommand: "tsx source/server/main.ts" } }
-    client: { …, development: { url: "http://localhost:5173", startCommand: "bun run dev" } }
-```
-
-Each half may carry a `development` block, but the two shapes are deliberately
-different. A Server and its development block each select exactly one of
-`startCommand` or `entryFile`. A command starts an isolated operating-system
-process tree; an entry module runs as a Worker owned by the System. In
-development, the directory containing `phresh.config.ts` becomes the derived
-Server location. A client block requires an HTTP(S) `url`; development clients
-are never resolved from filesystem paths.
-
-An `entryFile` is a path inside its Server location. Packaging copies it with
-the rest of that directory, and the System rejects a path that escapes those
-files. A Worker has no independent process working directory and is not a
-security boundary; resolve module-owned resources with `import.meta.url` and
-use the Server SDK for Program storage.
-
-The client development shape may also declare `startCommand`. `phresh dev`
-runs it from the project directory as a foreground development tool; the
-command is never derived into the Program sent to the system. The tool and
-the attached Program share one lifetime, so ending either ends the other.
-
-Before launching the Program, `phresh dev` waits up to 15 seconds for the client
-development URL to respond. While it remains unavailable, the URL is printed
-every two seconds. A command that exits first is reported immediately. This
-means the window is never deliberately opened onto a client that the authoring
-tool already knows is unavailable.
-
-## init
-
-`phresh init` turns an existing package into a Program project. It reads the
-identity, version, and description from `package.json`, ensures the project has
-the matching `@phreshos/core` development dependency, and writes the typed
-`phresh.config.ts` authoring description.
-
-In a terminal, `init` asks for the production locations and Server execution
-modes needed by `start` and `install`, including whether a package build should
-prepare those locations. It then offers the development Server mode, Client
-command, and URL needed by `dev`.
-Existing `build` and `dev` package scripts become editable suggestions, never
-silent assumptions. A single Endpoint defaults to `dist`; when both Endpoints
-exist, their defaults are `dist/server` and `dist/client`. API documentation is
-opt-in and defaults to disabled even when a likely document already exists.
+System installation acquires and verifies the official release archive and
+configures the native per-user service. Starting and stopping control current
+execution; enabling and disabling control automatic startup.
 
-Outside a terminal it never waits for input; the same values are supplied as
-named options:
+## Runtime
 
-```bash
-phresh init --client \
-    --client-location dist \
-    --build-command "bun run build" \
-    --client-development-url http://localhost:5173 \
-    --client-development-start-command "bun run dev"
-
-phresh init --server \
-    --server-location dist \
-    --server-start-command "node main.js"
+```sh
+phresh program list
+phresh process list --program my-program
+phresh endpoint inspect \
+  --program my-program \
+  --process main \
+  --endpoint server
+phresh window inspect --program my-program --process main
 ```
 
-Use `phresh init --help` for the complete option list. An existing config is
-never replaced silently: a terminal asks, while automation must say `--force`.
-
-A Program must declare a Server endpoint, a Client endpoint, or both. Neither is
-refused during the interview rather than at the border, which is the
-earliest place it can be refused.
-
-The final `Next` line is derived from the resulting config. It always shows
-`phresh start` and `phresh install`; it shows `phresh dev` only when at least
-one Endpoint received a development declaration.
-
-Visual and advanced runtime defaults remain for the author to add deliberately:
-`icon`, `size`, `position`, `installCommand`, `start`, layers, and minimization
-are not guessed. An omitted `start` is `true`; only a default-off Endpoint needs to
-say `start: false`.
-
-## start and dev
-
-Both **run your program without installing it, and stay attached.** They
-print the `program.json` it will be declared as, hand that to the system
-through the socket below the selected system home. With no override, that is
-`~/.phreshos/gateway.sock`. Set `PHRESHOS_HOME` to an absolute system home to
-address another system instance; the CLI derives
-`<PHRESHOS_HOME>/gateway.sock` from it. The socket is not selected
-separately from its instance. Only your account can open it, so nothing is
-sent to prove anything, and then the command holds.
-
-**The connection is the tether, in both directions.** Ctrl-C and your
-program stops. Close the window it opened and the command returns, with
-your program's own exit status as its own. Its `stdout` and `stderr`
-arrive in your terminal as well as its system log. The system always
-drains a server process; attachment adds the terminal as an audience
-rather than changing how the process starts.
-
-Nothing has to promise to clean up, which is the point — a promise would
-not survive `kill -9`, a closed terminal, or a dropped ssh session. All
-three end the command without running a line of it, and all three still
-close the socket, which is what the system is watching.
-
-**Attached means not installed; installed means persistent.** A program
-meant to outlive your terminal is installed rather than run.
-
-The run is registered as an ordinary uninstalled Program under the identity
-declared by this project. Before registration, the system ends and forgets any
-runtime Program already using that identity, whether it was installed or
-uninstalled. Forgetting never uninstalls: installed files and storage remain
-untouched while the attached Program becomes the sole runtime occupant. Its
-root process tethers the whole Program to this command; when it exits, remaining
-processes end and the runtime record disappears. A later `phresh install` can
-replace the preserved installed files and immediately register the identity as
-installed again. If no system is listening, the gateway says so plainly rather
-than exposing `ENOENT`.
-
-An attached Program still owns persistent project storage. The authoring tool
-declares `<project>/storage` explicitly, so `start` and `dev` keep the same
-database, store, data, cache, and logs as any other runtime form without
-inventing a path from the system's working directory. Installation changes
-where Program files are laid out; it does not change the logging contract.
-
-They are one derivation over one config, differing only in where each
-half is said to be:
+The command hierarchy follows the runtime ownership hierarchy. Unknown
+commands, flags, and malformed values reject rather than being guessed.
 
-| | locations from | derived form |
-|---|---|---|
-| `pack` | `location` | none — the system lays an installed program out |
-| `start` | `location` | absolute |
-| `dev` | project root for a declared server development block; `development.url` for a declared client block | server absolute, client URL |
-
-Every derived filesystem path is absolute because relative paths resolve
-against the `program.json` they were read from, and a derived one does not live
-beside your source. A client development URL remains the URL the author wrote.
-
-## install
-
-**A program has two ways of being used: run it, or install it.**
-
-```bash
-phresh install   # this project, laid out on this machine
-phresh install flambo   # the official Flambo Program
+```sh
+phresh describe
+phresh describe program
+phresh describe process list
 ```
 
-Without a name, what is sent is
-the description this directory derives, and the system copies what it
-names into place — your program's parts are already on this disk at the
-locations it names, so there is nothing an archive would carry that the
-description does not already point at. `phresh pack` is for when you have
-somewhere to send a program; installing here is a different act.
-
-With a name, the CLI resolves and verifies that official Program's production
-release directly; the current directory is irrelevant.
-
-If `buildCommand` is declared, it completes successfully before anything is
-sent to the system. Without it, install uses the production files exactly as
-they stand.
+`describe` exposes the command tree and exact options as machine-readable
+contracts.
 
-Installing is the persistent one — laid out under `~/.phreshos/programs/<identity>`,
-marked installed, and reconstructed after a restart. Running is the other one:
-`phresh start` / `phresh dev` register it under its declared identity and
-attach its whole lifetime to your terminal.
+## Development
 
-The command installs through the machine's local gateway. A running
-Program may also install itself through the server SDK; installation is not a
-client capability.
-
-When a Server declares `installCommand`, `phresh install` writes that command's
-`stdout` and `stderr` chunks as the System emits them. The final installed
-confirmation appears only after the output stream completes successfully.
-
-That is also why it names **paths** rather than sending bytes: install
-used to want an upload because the installer was a browser, which has
-bytes and no path. You have the paths.
-
-## uninstall
-
-```bash
-phresh uninstall
-phresh uninstall flambo
-phresh uninstall --everything
+```sh
+bun install --frozen-lockfile
+bun run verify
 ```
 
-Ordinary uninstall removes the installed Program files while preserving its
-running Processes, stored data, and runtime Program. `--everything` explicitly
-ends those Processes, removes everything the system owns for the Program, and
-forgets its runtime record.
+`verify` checks the scripts, builds the CLI and bundled starter, runs the
+command tests, and validates the package artifact.
 
-When the installed Server declares `uninstallCommand`, the System runs it from
-that Server directory before removing files. `phresh uninstall` writes its
-ordered `stdout` and `stderr` chunks as they arrive. A failed cleanup command
-aborts removal and reports the failure.
+See the [CLI documentation](https://github.com/PhreshOS/docs/blob/main/content/docs/sdks/cli.mdx)
+for the command model.
 
-Without a name, the identity comes from this project's `phresh.config.ts`.
-With a name, the installed Program is addressed directly and the current
-directory is irrelevant.
+## Repository boundary
 
-## What pack produces
+This repository owns terminal interaction, project commands, packaging, System
+acquisition, and host service integration. Node owns the external JavaScript
+interface, Core owns shared contracts, and the System owns authoritative state.
 
-`pack` takes what is at each half's `location` and writes both `program.json`
-and `<identity>@<version>.zip`. The exact generated declaration is also stored
-inside the archive. Your program may leave its halves anywhere; the
-package always keeps them in the same places, so the artifact's shape
-belongs to the contract rather than to your project. That is why the
-`program.json` it writes names `server` and `client` explicitly — those
-are the canonical locations the package just created. An explicit
-`start: false` crosses with its half; an omitted value remains omitted
-and means `true`. At least one declared half must resolve to true.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting.
 
-There is **no wrapping directory**: `program.json`, `server/`, `client/`,
-optional `icon.png`, and optional `agent.md` sit at the package's root. The
-system names the directory it installs into from your program's `identity`.
-An authored agent document may use any project-relative path, while packaging
-normalizes it to `agent.md`.
+## License
 
-Nothing about the system moves because this exists. `program.json` is
-still the only declaration the system and release catalog read. Root
-`categories`, `keywords`, and `website` values are optional and cross into it
-without affecting execution. The file is generated output; `phresh.config.ts`
-remains the authored source.
+Licensed under the [MIT License](LICENSE). Copyright © 2026 Zohayr SLILEH.

package/dist/cli.js

@@ -12,6 +12,7 @@ import systemCommands from "./system/command.js";
 import controlCommands from "./control/command.js";
 import describeCommands from "./describe-command.js";
 import { commandContract } from "./command-contract.js";
+import { blank, failure } from "./style.js";
 const metadata = createRequire(import.meta.url)("../package.json");
 const { version } = metadata;
 const coreRange = metadata.dependencies["@phreshos/core"];
@@ -96,13 +97,12 @@ describe(program.command("install")
     .description("install a local or official Program")
     .argument("[name]", "name of an official Program")
     .option("--run", "run the installed Program now")
-    .option("--startup", "run the Program when the System starts")
     .action(async function (name, options) {
-    await install({ name, run: options.run === true, startup: options.startup === true });
+    await install({ name, run: options.run === true });
 }), [
     "Without a name, builds and installs the Program declared by this project.",
     "A name installs its verified official production release. --run launches",
-    "it now; --startup persists the same default launch for future starts."
+    "the installed Program now."
 ]);
 describe(program.command("uninstall")
     .description("uninstall a local or installed Program")
@@ -129,7 +129,7 @@ controlCommands(program);
 describeCommands(program);
 // Every command begins with the same breathing room. Keep this at the entry
 // point so individual commands never need to manufacture their own opening.
-console.log("");
+blank();
 if (process.argv.length === 2)
     program.help();
 try {
@@ -141,7 +141,7 @@ catch (error) {
     else if (error instanceof ReportedFailure)
         process.exitCode = 1;
     else {
-        console.error(`\n  phresh: ${error instanceof Error ? error.message : String(error)}\n`);
+        failure(error instanceof Error ? error.message : String(error));
         process.exitCode = 1;
     }
 }

package/dist/control/endpoint.js

@@ -1,7 +1,7 @@
 import { Option } from "commander";
 import { commandContract } from "../command-contract.js";
-import { clientOverrideOptions, endpointOptions, outputOptions } from "./options.js";
-import { bounded, clientLaunch, connected, endpoint, endpointView, integer, output, payload, requireProcess, wait } from "./shared.js";
+import { clientOverrideOptions, endpointOptions, outputOptions, serverOverrideOptions } from "./options.js";
+import { bounded, clientLaunch, connected, endpoint, endpointView, integer, output, payload, requireProcess, serverLaunch, wait } from "./shared.js";
 export default function endpointCommands(root, connect) {
     const endpoints = commandContract(root.command("endpoint")
         .description("inspect, control, and communicate with Process Endpoints"));
@@ -10,16 +10,19 @@ export default function endpointCommands(root, connect) {
         .action(async (options) => withEndpoint(connect, options, async (process, name) => {
         output(await endpointView(process, name), options.compact);
     }));
-    outputOptions(clientOverrideOptions(endpointOptions(endpoints.command("start")
-        .description("start a fresh Endpoint incarnation"))))
+    outputOptions(serverOverrideOptions(clientOverrideOptions(endpointOptions(endpoints.command("start")
+        .description("start a fresh Endpoint incarnation")))))
         .action(async (options) => withEndpoint(connect, options, async (process, name) => {
-        const overrides = clientLaunch(options);
-        if (name === "server" && overrides !== undefined)
+        const client = clientLaunch(options);
+        const server = serverLaunch(options);
+        if (name === "server" && client !== undefined)
             throw new Error("Client overrides require --endpoint client");
+        if (name === "client" && server !== undefined)
+            throw new Error("Server overrides require --endpoint server");
         if (name === "client")
-            await process.client.start(typeof overrides === "object" ? overrides : undefined);
+            await process.client.start(typeof client === "object" ? client : undefined);
         else
-            await process.server.start();
+            await process.server.start(typeof server === "object" ? server : undefined);
         output(await endpointView(process, name), options.compact);
     }));
     outputOptions(endpointOptions(endpoints.command("stop")

package/dist/control/options.js

@@ -19,6 +19,8 @@ export function clientOptions(command) {
 }
 export function clientOverrideOptions(command) {
     return command
+        .option("--client-service", "address this Client incarnation through system.service()")
+        .option("--no-client-service", "do not address this Client incarnation through system.service()")
         .option("--client-title <title>", "initial Window title")
         .option("--client-width <value>", "initial Window width")
         .option("--client-height <value>", "initial Window height")
@@ -28,8 +30,13 @@ export function clientOverrideOptions(command) {
         .option("--client-location <location>", "initial page beneath the Client location")
         .option("--client-minimized", "open the Window minimized");
 }
+export function serverOverrideOptions(command) {
+    return command
+        .option("--server-service", "address this Server incarnation through system.service()")
+        .option("--no-server-service", "do not address this Server incarnation through system.service()");
+}
 export function launchOptions(command) {
-    return clientOptions(command)
+    return serverOverrideOptions(clientOptions(command))
         .option("--name <name>", "stable Program-local Process name")
         .option("--server", "start the Server Endpoint")
         .option("--no-server", "do not start the Server Endpoint")

package/dist/control/shared.js

@@ -1,4 +1,5 @@
 import { System } from "@phreshos/node";
+import { blank } from "../style.js";
 export const connectSystem = () => System.connect();
 export async function connected(connect, action) {
     const system = await connect();
@@ -39,14 +40,19 @@ export async function programView(program) {
     };
 }
 export async function processView(process) {
-    const [server, client] = await Promise.all([process.server.exists(), process.client.exists()]);
+    const [server, client, serverService, clientService] = await Promise.all([
+        process.server.exists(),
+        process.client.exists(),
+        process.server.isService(),
+        process.client.isService()
+    ]);
     return {
         identity: process.identity,
         name: process.name,
         program: process.program().identity,
         startedAt: process.startedAt.toISOString(),
-        server: { declared: process.program().server !== null, running: server },
-        client: { declared: process.program().client !== null, running: client }
+        server: { declared: process.program().server !== null, running: server, service: serverService },
+        client: { declared: process.program().client !== null, running: client, service: clientService }
     };
 }
 export async function endpointView(process, name) {
@@ -56,7 +62,8 @@ export async function endpointView(process, name) {
         program: program.identity,
         endpoint: name,
         declared: name === "server" ? program.server !== null : program.client !== null,
-        running: await endpoint(process, name).exists()
+        running: await endpoint(process, name).exists(),
+        service: await endpoint(process, name).isService()
     };
 }
 export async function windowView(process) {
@@ -74,6 +81,7 @@ export async function windowView(process) {
 }
 export function output(value, compact) {
     console.log(JSON.stringify(value ?? null, null, compact ? undefined : 2));
+    blank();
 }
 export function payload(value) {
     if (value === undefined)
@@ -118,12 +126,13 @@ export function page(values, search, offset = 0, limit = 30, text) {
 }
 export function launch(options, named = false) {
     const client = clientLaunch(options);
+    const server = serverLaunch(options);
     const values = entries(options.option);
     const result = {};
     if (options.name !== undefined)
         result.name = options.name;
-    if (options.server !== undefined)
-        result.server = options.server;
+    if (server !== undefined)
+        result.server = server;
     if (client !== undefined)
         result.client = client;
     if (Object.keys(values).length)
@@ -133,6 +142,7 @@ export function launch(options, named = false) {
     return result;
 }
 export function clientLaunch(options) {
+    const service = options.clientService;
     const configured = options.clientTitle !== undefined
         || options.clientWidth !== undefined
         || options.clientHeight !== undefined
@@ -140,7 +150,8 @@ export function clientLaunch(options) {
         || options.clientY !== undefined
         || options.clientLayer !== undefined
         || options.clientLocation !== undefined
-        || options.clientMinimized === true;
+        || options.clientMinimized === true
+        || service !== undefined;
     if (!configured)
         return options.client;
     if (options.client === false)
@@ -152,6 +163,7 @@ export function clientLaunch(options) {
         throw new Error("--client-x and --client-y must be supplied together");
     }
     return {
+        ...(service === undefined ? {} : { service }),
         ...(options.clientTitle === undefined ? {} : { title: options.clientTitle }),
         ...(options.clientWidth === undefined ? {} : { size: size(options.clientWidth, options.clientHeight) }),
         ...(options.clientX === undefined ? {} : { position: position(options.clientX, options.clientY) }),
@@ -160,6 +172,14 @@ export function clientLaunch(options) {
         ...(options.clientMinimized === true ? { minimize: true } : {})
     };
 }
+export function serverLaunch(options) {
+    const service = options.serverService;
+    if (service === undefined)
+        return options.server;
+    if (options.server === false)
+        throw new Error("Server overrides cannot be combined with --no-server");
+    return { service };
+}
 export function collect(value, previous = []) {
     return [...previous, value];
 }

package/dist/create.js

@@ -1,6 +1,6 @@
 import { installProjectDependencies, projectPackageManager, projectScript } from "./project-dependency.js";
 import prompts from "./prompts.js";
-import { accent, bold } from "./style.js";
+import { accent, blank, bold } from "./style.js";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, relative, resolve } from "node:path";
 /** Creates a complete Program from the bundled Phresh Program snapshot. */
@@ -60,7 +60,7 @@ export default async function create(options = {}, directory = process.cwd()) {
     console.log(bold(`\n${bundled.development ? "Run Development Program" : "Run Program"}`));
     console.log(accent(script));
     console.log(bold("\nYou can now open the project and start building your Program"));
-    console.log("");
+    blank();
 }
 function template() {
     const candidates = [

package/dist/describe-command.js

@@ -1,4 +1,5 @@
 import { commandContract, readCommandContract } from "./command-contract.js";
+import { blank } from "./style.js";
 /** Add one machine-readable description entry point for the complete CLI tree. */
 export default function describeCommands(program) {
     commandContract(program.command("describe")
@@ -9,6 +10,7 @@ export default function describeCommands(program) {
         const command = resolveCommand(program, path);
         const description = describe(command, path);
         console.log(JSON.stringify(description, null, options.compact ? undefined : 2));
+        blank();
     }), { guidance: ["Omit the path to discover all top-level commands, then describe progressively deeper paths."] });
 }
 function resolveCommand(root, path) {

package/dist/install.js

@@ -1,5 +1,5 @@
 import { Project } from "@phreshos/node";
-import { dim, heading, line } from "./style.js";
+import { blank, dim, heading, line } from "./style.js";
 import installProgram, {} from "./program-installation.js";
 import { prepareOfficialProgram } from "./program-release.js";
 /**
@@ -15,10 +15,10 @@ import { prepareOfficialProgram } from "./program-release.js";
  * production Program is derived and sent. The command remains authoring
  * metadata and never becomes part of the installed Program.
  *
- * Installation remains distinct from execution unless `run` or `startup`
- * is explicitly requested. A run created here belongs to the installed
- * Program and therefore outlives this command; `phresh start` and `phresh
- * dev` remain attached authoring runs whose lifetime is the terminal's.
+ * Installation remains distinct from execution unless `run` is explicitly
+ * requested. A run created here belongs to the installed Program and
+ * therefore outlives this command; `phresh start` and `phresh dev` remain
+ * attached authoring runs whose lifetime is the terminal's.
  */
 export default async function install(options = {}) {
     const directory = options.directory ?? process.cwd();
@@ -32,11 +32,11 @@ export default async function install(options = {}) {
             const { name, identity, version } = result.program;
             heading(`${name || identity}${version ? ` ${version}` : ""}`, result.replaced ? "reinstalled" : "installed");
             if (result.replaced)
-                console.log(`  ${dim("its storage was kept, and its previous processes were ended")}\n`);
-            if (result.startupEnabled)
-                line("startup", "enabled");
+                console.log(`  ${dim("its storage was kept, and its previous processes were ended")}`);
             if (result.process)
                 line("process", result.process);
+            if (result.replaced || result.process)
+                blank();
         }
         return result;
     }

package/dist/launch.js

@@ -1,7 +1,7 @@
 import { Project } from "@phreshos/node";
 import { relative } from "node:path";
 import { assertAvailable, commandFailure, DevelopmentClient, waitForDevelopmentClient } from "./development-client.js";
-import { dim, heading, line } from "./style.js";
+import { blank, dim, heading, line } from "./style.js";
 /** Run the current project through one connected System. */
 export default async function launch(mode, directory = process.cwd(), options = {}) {
     const project = await Project.open(directory);
@@ -16,7 +16,7 @@ export default async function launch(mode, directory = process.cwd(), options =
     line("storage", place(project.directory, String(definition.storage)));
     if (Object.keys(options).length)
         line("options", Object.entries(options).map(([name, value]) => `${name}=${value}`).join("  "));
-    console.log("");
+    blank();
     const system = await (await import("@phreshos/node")).System.connect();
     const controller = new AbortController();
     const development = mode === "development" && definition.client && (definition.client.start ?? true)
@@ -70,7 +70,9 @@ export default async function launch(mode, directory = process.cwd(), options =
         process.exit(130);
     if (!ended)
         throw new Error("The System closed before the Program ended");
-    console.log(`\n  ${dim(ended.signal ? `ended on ${ended.signal}` : `ended with ${ended.code ?? 0}`)}\n`);
+    blank();
+    console.log(`  ${dim(ended.signal ? `ended on ${ended.signal}` : `ended with ${ended.code ?? 0}`)}`);
+    blank();
     process.exit(ended.signal ? 128 : ended.code ?? 0);
 }
 async function consume(lifecycle, client) {

package/dist/pack.js

@@ -1,11 +1,14 @@
 import { Project } from "@phreshos/node";
-import { line } from "./style.js";
+import { blank, line } from "./style.js";
 /** Package the current Project and present only its command-facing progress. */
 export default async function pack(directory = process.cwd()) {
     const project = await Project.open(directory);
     if (project.config.buildCommand)
         line("build", project.config.buildCommand);
     const packed = await project.pack();
-    console.log(`\nPacked ${packed.archive}`);
+    if (project.config.buildCommand)
+        blank();
+    console.log(`Packed ${packed.archive}`);
+    blank();
     return packed.archive;
 }

package/dist/program-installation.js

@@ -7,7 +7,6 @@ export default async function installProgram(program, options = {}) {
     const current = await system.program.find(identity);
     const replaced = await current?.installed() ?? false;
     let installed = null;
-    let startupEnabled = false;
     let process = null;
     let installationFinished = false;
     try {
@@ -20,10 +19,6 @@ export default async function installProgram(program, options = {}) {
         for await (const chunk of installed.install())
             writeProgramCommandOutput(chunk);
         installationFinished = true;
-        if (options.startup) {
-            await installed.startup.enable();
-            startupEnabled = true;
-        }
         if (options.run)
             process = (await installed.process.create()).identity;
     }
@@ -41,14 +36,11 @@ export default async function installProgram(program, options = {}) {
     }
     if (!installed)
         throw new Error("The System ended Program installation without confirming it");
-    if (options.startup && !startupEnabled)
-        throw new Error("The System installed the Program without confirming startup");
     if (options.run && !process)
         throw new Error("The System installed the Program without confirming that it is running");
     return {
         program: { identity: installed.identity, name: installed.name, version: installed.version },
         replaced,
-        startupEnabled,
         process
     };
 }

package/dist/project-dependency.js

@@ -1,4 +1,4 @@
-import { line } from "./style.js";
+import { blank, line } from "./style.js";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -33,7 +33,7 @@ export default async function ensureProjectDependency(name, range, directory = p
     const manager = projectPackageManager(directory, manifest.packageManager);
     line("dependency", name, `${manager.name}, ${range}`);
     await run(manager.name, [...manager.addArgs(section), `${name}@${range}`], directory);
-    console.log("");
+    blank();
 }
 function run(command, args, directory, output = "inherit") {
     return new Promise(function (settle, refuse) {

package/dist/prompts.js

@@ -1,6 +1,6 @@
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import colors from "picocolors";
-import { caution, column, ending, line, section } from "./style.js";
+import { blank, caution, column, ending, line, section } from "./style.js";
 /** Signals an ordinary interactive cancellation rather than an operation failure. */
 export class PromptCancelled extends Error {
 }
@@ -36,8 +36,10 @@ export default function prompts() {
     function message(value = "") {
         if (interactive)
             log.message(value, { spacing: 0 });
+        else if (value)
+            console.log(`  ${value}`);
         else
-            console.log(value ? `  ${value}` : "");
+            blank();
     }
     function warning(value) {
         if (interactive)

package/dist/style.js

@@ -6,6 +6,10 @@ export const accent = colors.cyan;
 export const positive = colors.green;
 export const caution = colors.yellow;
 export const negative = colors.red;
+/** Writes one intentional blank line between terminal report blocks. */
+export function blank() {
+    console.log("");
+}
 // A label, what it says, and where that came from. The label is quiet
 // and the value is not, because the value is the thing being reported.
 //
@@ -20,12 +24,17 @@ export function column(label) {
 }
 export function heading(title, note) {
     section(title, note);
-    console.log("");
+    blank();
 }
 export function section(title, note) {
     console.log(`  ${bold(title)}${note ? `  ${dim("·")}  ${dim(note)}` : ""}`);
 }
 export function ending(message) {
     console.log(`  ${bold(message)}`);
-    console.log("");
+    blank();
+}
+/** Writes one consistently indented command failure followed by closing space. */
+export function failure(message) {
+    console.error(`  phresh: ${message}`);
+    console.error("");
 }

package/dist/system/lifecycle.js

@@ -201,7 +201,7 @@ export default class SystemLifecycle {
     }
 }
 async function provisionSetup() {
-    await installProgram({ name: "setup", run: true, startup: true, announce: false });
+    await installProgram({ name: "setup", run: true, announce: false });
 }
 function definition(installation, executable) {
     return {

package/dist/template/README.md

@@ -1,16 +1,23 @@
 # Phresh Program
 
-The minimal PhreshOS starter Program. Its Client talks directly to its Server;
-there is no MVC structure and no registered service.
+The official minimal starter Program generated by `phresh create`.
 
-```bash
-bun install
-bun run dev
+It demonstrates one Client and one Server communicating directly through the
+standard PhreshOS Endpoint contracts.
+
+## Create a Program
+
+```sh
+phresh create
 ```
 
-The complete Program is intentionally small:
+The CLI bundles a verified release of this repository and creates the new
+project without requiring a live template checkout.
+
+## Structure
 
 ```text
+phresh.config.ts
 client/
 ├── app.tsx
 ├── index.html
@@ -18,8 +25,42 @@ client/
 └── style.css
 server/
 └── main.ts
+scripts/
+└── build.ts
+```
+
+The Server owns the counter. The Client renders it and communicates with its
+paired Server. The example deliberately has no additional MVC hierarchy and no
+registered Service.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run verify
+bun run dev
 ```
 
-`app.tsx` owns the small React component. The two `main` files are direct
-endpoint entries: the Client renders the app and the Server owns the counter.
-Nothing registers or exposes a named service.
+Build, attach the production definition, or package the Program with:
+
+```sh
+bun run build
+bun run start
+bun run pack
+```
+
+`verify` checks the source, builds both Endpoints, and validates the packaged
+Program shape.
+
+## Repository boundary
+
+This repository owns the starter source distributed by the CLI. It remains a
+complete ordinary Program rather than a second template model or generator-only
+fixture.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
+[SECURITY.md](SECURITY.md) for private vulnerability reporting.
+
+## License
+
+Licensed under the [MIT License](LICENSE). Copyright © 2026 Zohayr SLILEH.

package/dist/template/package.json

@@ -1,7 +1,7 @@
 {
     "name": "phresh",
     "private": true,
-    "version": "0.1.23",
+    "version": "0.1.25",
     "description": "The official PhreshOS starter Program.",
     "type": "module",
     "scripts": {
@@ -14,15 +14,15 @@
         "starter"
     ],
     "dependencies": {
-        "@phreshos/client": "^0.1.26",
-        "@phreshos/core": "^0.1.26",
-        "@phreshos/react": "^0.1.14",
-        "@phreshos/server": "^0.1.27",
+        "@phreshos/client": "^0.1.29",
+        "@phreshos/core": "^0.1.31",
+        "@phreshos/react": "^0.1.17",
+        "@phreshos/server": "^0.1.32",
         "react": "^19.2.8",
         "react-dom": "^19.2.8"
     },
     "devDependencies": {
-        "@phreshos/cli": "^0.1.41",
+        "@phreshos/cli": "^0.1.43",
         "@types/node": "^26.2.0",
         "@types/react": "^19.2.18",
         "@types/react-dom": "^19.2.4",

package/dist/template/phresh.config.ts

@@ -4,7 +4,7 @@ export default defineConfig({
     identity: "phresh",
     name: "Phresh Program",
     description: "A minimal counter with direct Client and Server endpoints.",
-    version: "0.1.23",
+    version: "0.1.25",
     icon: "icon.png",
     categories: ["Development"],
     keywords: ["example", "counter", "client", "server"],

package/dist/template.json

@@ -1,6 +1,6 @@
 {
     "repository": "PhreshOS/phresh-program",
-    "version": "0.1.23",
-    "sha256": "055a84726198072f481b14bd2aabd0f155982238914aded7808008c4197c123f",
+    "version": "0.1.25",
+    "sha256": "fa1d6e82cda7b129f08f0ca8d86d1bef1ff543b73e5926342ba5054054211d3e",
     "development": true
 }

package/dist/uninstall.js

@@ -1,5 +1,5 @@
 import { readConfig } from "./project.js";
-import { dim, heading } from "./style.js";
+import { blank, dim, heading } from "./style.js";
 import writeProgramCommandOutput from "./program-command-output.js";
 /** Uninstall an installed Program by name or by the current project's identity. */
 export default async function uninstall(options = {}) {
@@ -15,8 +15,9 @@ export default async function uninstall(options = {}) {
             writeProgramCommandOutput(chunk);
         heading(identity, "uninstalled");
         console.log(options.everything
-            ? `  ${dim("Its processes, installed files, stored data, and runtime record were removed.")}\n`
-            : `  ${dim("Its installed files were removed. Processes, stored data, and runtime state were kept.")}\n`);
+            ? `  ${dim("Its processes, installed files, stored data, and runtime record were removed.")}`
+            : `  ${dim("Its installed files were removed. Processes, stored data, and runtime state were kept.")}`);
+        blank();
     }
     finally {
         await system.disconnect();

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@phreshos/cli",
     "type": "module",
-    "version": "0.1.41",
+  "version": "0.1.43",
     "description": "The Phresh command-line interface for Program projects and system management.",
     "engines": {
         "node": ">=20.10"
@@ -49,8 +49,8 @@
     "packageManager": "bun@1.3.14",
     "dependencies": {
         "@clack/prompts": "^1.7.0",
-        "@phreshos/core": "^0.1.27",
-        "@phreshos/node": "^0.1.6",
+    "@phreshos/core": "^0.1.32",
+    "@phreshos/node": "^0.1.10",
         "adm-zip": "^0.6.0",
         "commander": "^15.0.0",
         "picocolors": "^1.1.1"