Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat: add interactive onboarding and skill market

Rahman0402234d7a9d
diff --git a/.env.example b/.env.example
index 592796ba..54858cbf 100644
--- a/.env.example
+++ b/.env.example
@@ -153,6 +153,9 @@ OS_SESSION_SECRET=
# OS_PREFS_PATH=~/.mso/prefs.json # synced UI prefs (theme, layout)
# OS_MEMORY_STORE=~/.mso/memory.json # assistant long-term memory
# OS_THREADS_DIR=~/.mso/threads # assistant chat threads (one file each)
+# CLI-only override for `mso skills install`; default ~/.mso/skills. The target is
+# the explicit operator-trust root, so point this only at a private directory you own.
+# MSO_SKILL_INSTALL_ROOT=~/.mso/skills
# --- Camoufox browser (the Browser app) ---
# The noVNC/websockify endpoint proxy.ts rewrites /camoufox-vnc/* to, behind the same
diff --git a/README.md b/README.md
index 96b203a3..880efdd9 100644
--- a/README.md
+++ b/README.md
@@ -94,34 +94,98 @@ Demo mode skips real login, forces mock data, blocks live host API access, and s
## Install
-One command on your Linux server installs prerequisites, builds MSO, generates local credentials, and sets up the `mso.service` systemd unit:
+Run one command on the Linux server as your normal user, **not root**:
```bash
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
```
-Run it as your normal server user, **not root**. The installer prints the first-login password once and explains how to approve your first browser device.
+A fresh install now finishes with a **guided terminal onboarding** when a controlling
+terminal is available. `curl | bash` uses stdin for the downloaded script, so the
+installer deliberately opens `/dev/tty` for the prompts instead of silently skipping them.
+The flow lets you choose:
+
+- **Alfa AI provider** — OpenAI ChatGPT/Codex device OAuth, or an API-key provider such
+ as Anthropic, OpenAI Platform, OpenRouter, Google, Groq, xAI, DeepSeek or Mistral;
+- **Alfa response preset** — normal, Caveman or Ponytail;
+- optional **Hermes / OpenClaw** installation (their provider settings remain separate
+ from Alfa's credentials);
+- reviewed **installable skills** such as Ponytail, Caveman and the MSO-safe RTK wrapper.
+
+The installer also generates the owner login credentials, builds production, installs and
+starts `mso.service`, and installs the CLI in both `~/.local/bin/mso` and—when the normal
+service install has sudo available—`/usr/local/bin/mso`. That system launcher is important:
+a child `curl | bash` process cannot modify the PATH of the shell that launched it, so
+`mso -h` must work immediately **after the installer returns**, without asking you to
+restart the shell. The installer also adds an idempotent `~/.local/bin` fallback to the
+normal shell profile for future sessions.
+
+If the environment has no controlling TTY (CI/cloud-init), the installer never blocks. It
+prints the resume command instead:
-It binds **`127.0.0.1` by default**, so nothing is published to your network. Reach it with an SSH tunnel and open `http://localhost:4005`:
+```bash
+mso onboard
+```
+
+For an intentionally non-interactive install, use safe minimal defaults. `-y` does **not**
+auto-connect external accounts, install large managed apps, or silently add community
+skills:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- -y
+```
+
+After installation these should work immediately:
+
+```bash
+mso -h
+mso doctor
+mso onboard # run/re-run guided setup
+mso skills available # reviewed installable skill list
+mso skills install ponytail caveman rtk -y
+```
+
+`Caveman`/`Ponytail` appear in two intentionally different places. **Response presets**
+(`mso config style caveman|ponytail`) are lightweight Alfa output policies. The market
+entries are full `SKILL.md` packages installed into the trusted operator root
+`~/.mso/skills`. Selecting a preset does not secretly install a skill, and installing a
+skill does not rewrite the global response preset.
+
+The curated `rtk` skill is an MSO-safe wrapper: it teaches agents to use RTK when the
+binary is already present, but it does **not** run an unpinned remote installer, modify
+shell profiles, or enable global hooks. Installing the RTK binary is a separate explicit
+system change.
+
+MSO binds **`127.0.0.1` by default**, so nothing is published directly to your network.
+Reach it with an SSH tunnel and open `http://localhost:4005`:
```bash
ssh -N -L 4005:127.0.0.1:4005 you@your-server
```
-That tunnel is not just hygiene. The session cookie is `Secure`, and browsers only keep a `Secure` cookie over plain http on `localhost` — so an `http://<ip>:4005` URL logs in successfully and then drops the cookie. For a permanent setup use `tailscale serve 4005` or a TLS reverse proxy pointed at `127.0.0.1:4005`; pass `--bind 0.0.0.0` only when a proxy you control is already in front.
+The tunnel is not just hygiene. The session cookie is `Secure`; ordinary plain-HTTP IP
+addresses drop it. For a permanent setup use Tailscale Serve or a TLS reverse proxy to
+`127.0.0.1:4005`. Bind wider only when the network/firewall design explicitly requires it.
-Useful options:
+Useful installer controls:
```bash
+# force onboarding even while updating an existing install
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --onboard
+
+# update/build without onboarding
+curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --no-onboard
+
+# other existing controls
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --port 4005
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --bind 0.0.0.0
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --no-service
curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash -s -- --uninstall
```
-There is also a no-login install guide you can share: **<https://mso.rahmanef.com/install>** (every MSO instance serves it at `/install`).
-
-Full production setup, TLS/VPN notes, filesystem roots, updates, and rollback steps live in [docs/INSTALL.md](./docs/INSTALL.md).
+There is also a no-login install guide at **<https://mso.rahmanef.com/install>**. Full
+production setup, TLS/VPN notes, filesystem roots, update/rollback and onboarding details
+live in [docs/INSTALL.md](./docs/INSTALL.md).
## CLI
@@ -132,6 +196,9 @@ covers anything without one.
```bash
mso -h # grouped command list; `mso <command> --help` per command
mso doctor # deps, env, service, session, device — names what broke
+mso onboard # guided AI/app/skill setup
+mso skills available # curated installable skills
+mso skills install ponytail caveman rtk -y
mso device pending # who typed the password and is waiting
mso device approve <id> "my phone"
mso ls ~/projects # files; `raw` for binaries, `zip`/`upload` for transfers
diff --git a/app/install/page.test.ts b/app/install/page.test.ts
new file mode 100644
index 00000000..439468a4
--- /dev/null
+++ b/app/install/page.test.ts
@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const source = fs.readFileSync(path.join(__dirname, "page.tsx"), "utf8");
+
+describe("public install guide", () => {
+ it("documents the terminal onboarding that the one-line installer actually runs", () => {
+ expect(source).toContain("Complete terminal onboarding");
+ expect(source).toContain("mso onboard");
+ expect(source).toContain("OpenAI ChatGPT OAuth");
+ expect(source).toContain("OpenRouter");
+ });
+
+ it("documents an immediately resolvable CLI and the curated skill market", () => {
+ expect(source).toContain("/usr/local/bin/mso");
+ expect(source).toContain("mso -h");
+ expect(source).toContain("mso skills available");
+ expect(source).toContain("mso skills install ponytail caveman rtk -y");
+ });
+});
diff --git a/app/install/page.tsx b/app/install/page.tsx
index 20d25ae5..d7f4e7d4 100644
--- a/app/install/page.tsx
+++ b/app/install/page.tsx
@@ -9,7 +9,7 @@ import { Copy } from "./copy";
export const metadata: Metadata = {
title: "Install Manef Shell OS on your own server",
description:
- "One command installs MSO on a Linux server you own: a browser terminal, file manager, live metrics and a BYOK AI assistant, behind password + device approval.",
+ "One command installs MSO, makes the mso CLI immediately available, and opens guided terminal onboarding for AI providers, optional managed apps and reviewed skills.",
};
const INSTALL = "curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash";
@@ -25,30 +25,39 @@ const STEPS = [
{
n: 1,
title: "Run the installer",
- body: "As your normal user, not root. It installs prerequisites, clones the repo, builds, generates a login password and session secret, and sets up the systemd unit.",
+ body: "As your normal user, not root. It installs prerequisites, clones the repo, builds production, generates owner credentials, installs the service, and makes `mso` resolvable immediately through a guarded /usr/local/bin launcher plus the ~/.local/bin fallback.",
code: INSTALL,
- note: "It prints your login password once. Save it — it is written only to .env.local on the server.",
+ note: "It prints your login password once. Save it — the secret is written only to .env.local on the server.",
},
{
n: 2,
+ title: "Complete terminal onboarding",
+ body: "On a fresh interactive install, the same command opens /dev/tty after the service is healthy. Choose an Alfa provider (OpenAI ChatGPT OAuth or supported API-key providers including OpenRouter), a response preset, optional Hermes/OpenClaw installs, and reviewed skills. If no terminal exists, nothing hangs: run `mso onboard` later.",
+ code: "mso onboard\nmso skills available\nmso skills install ponytail caveman rtk -y",
+ note: "`-y` is available for a safe non-interactive install, but it does not silently connect accounts, install managed apps, or trust community skills you did not select.",
+ },
+ {
+ n: 3,
title: "Reach it",
- body: "The installer binds 127.0.0.1, so :4005 is closed to every other machine and there is nothing to firewall. Tunnel in from whatever you browse on. The tunnel is not only for privacy: the session cookie is Secure, and a browser only keeps a Secure cookie over plain http on localhost — so an http://<ip>:4005 URL returns a successful login and then silently drops the cookie.",
+ body: "The installer binds 127.0.0.1, so :4005 is closed to other machines by default. Tunnel in from whatever you browse on. The session cookie is Secure, so ordinary plain-http IP addresses are not a valid permanent login origin.",
code: "ssh -N -L 4005:127.0.0.1:4005 you@your-server",
- note: "Then open http://localhost:4005. For something permanent use `tailscale serve 4005`, or a TLS reverse proxy on the server pointed at 127.0.0.1:4005 — both give the browser a trustworthy origin. Only pass --bind 0.0.0.0 if a proxy you control is already in front.",
+ note: "Then open http://localhost:4005. For something permanent use `tailscale serve 4005`, or a TLS reverse proxy pointed at 127.0.0.1:4005.",
},
{
- n: 3,
- title: "Pair your first device",
- body: "Open the app and enter the password. Your browser lands in a PENDING state and shows a device id — correct password alone is not enough. Approve it from a shell on the server:",
+ n: 4,
+ title: "Pair your browser",
+ body: "Open the app and enter the password. Your browser lands PENDING and shows a device id. Terminal onboarding approves only the local CLI device; browser devices remain explicit owner approvals.",
code: "mso device pending\nmso device approve <deviceId> \"my laptop\"",
note: "Device approval is a browser allowlist, not standards-based 2FA. Approve only devices you own.",
},
{
- n: 4,
+ n: 5,
title: "Reload and sign in",
- body: "That device can now log in with the password. Approve later devices the same way, or from Settings → Devices once you are in.",
+ body: "That browser can now log in. Approve later devices from Settings → Devices. Re-run `mso onboard` whenever you want to change the first-run choices.",
+ code: undefined,
+ note: undefined,
},
-];
+] as const;
export default function InstallPage() {
return (
@@ -83,7 +92,7 @@ export default function InstallPage() {
</section>
<section className="mb-12">
- <h2 className="mb-5 text-lg font-semibold">Four steps</h2>
+ <h2 className="mb-5 text-lg font-semibold">Five steps</h2>
<ol className="space-y-8">
{STEPS.map((s) => (
<li key={s.n} className="grid grid-cols-[2rem_1fr] gap-x-3">
@@ -111,12 +120,11 @@ export default function InstallPage() {
<section className="mb-12">
<h2 className="mb-3 text-lg font-semibold">Drive it from a shell</h2>
<p className="text-sm leading-relaxed text-muted-foreground">
- The installer also puts <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">mso</code> on
- your PATH. It reaches the same API the browser does — files, host shell, metrics,
- managed apps, devices — so nothing is UI-only. Start with{" "}
- <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">mso doctor</code>.
+ The service install creates a guarded <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">/usr/local/bin/mso</code> launcher,
+ because a child <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">curl | bash</code> process cannot export PATH back into its parent shell.
+ The normal <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">~/.local/bin</code> fallback is persisted too. So the first command after install can be <code className="rounded bg-muted px-1 py-0.5 text-[0.85em]">mso -h</code>.
</p>
- <Copy text="mso doctor" />
+ <Copy text={'mso -h\nmso doctor\nmso onboard\nmso skills available'} />
</section>
<footer className="flex flex-wrap gap-x-6 gap-y-2 border-t border-border pt-6 text-sm">
diff --git a/bin/mso b/bin/mso
index 62de729f..f1667fc2 100755
--- a/bin/mso
+++ b/bin/mso
@@ -39,6 +39,7 @@
# status Public service status (no session needed)
# health Is this CLI's session valid?
# doctor Check deps, env, service, session, device — and say what broke
+# onboard [-y] Guided first-run setup: AI, response style, managed apps, skills
#
# Browser
# camoufox * Power the anti-detection VNC browser + read its password
@@ -52,10 +53,10 @@
# ai <prompt…> One turn with the assistant
# threads * Conversation history: list | show | rm
# memory * Assistant memories: list | add | rm
-# config * BYOK provider + model: show | set | rm
+# config * BYOK provider + model/style: show | set | key | style | rm
# prefs * UI preferences: show | set
# models * Model catalog: list | test
-# skills * Skills across every project: list | read <id> | search <query>
+# skills * Discover host skills + curated market: available/install/remove
# changelog What shipped, newest first (same text Settings → About shows)
# mcp * MCP tokens + live activity: list | activity [n] | revoke <id> | revoke all
# oauth <prov> * Provider sign-in (device code): start | poll
@@ -112,7 +113,7 @@
# Docs: https://github.com/rahmanef63/mso
set -euo pipefail
-VERSION="1.1.0"
+VERSION="1.2.0"
ROOT="$(cd "$(dirname "$(readlink -f "$0")")/.." && pwd)"
die() { echo "mso: $*" >&2; exit 1; }
@@ -220,6 +221,216 @@ kv_args() { local j='{}' kv k v; for kv in "$@"; do k="${kv%%=*}"; v="${kv#*=}"
else j=$(jq -c --arg k "$k" --arg v "$v" '.+{($k):$v}' <<<"$j"); fi; done; printf '%s' "$j"; }
json_arg() { jq -e . >/dev/null 2>&1 <<<"${1-}" || die "not valid JSON: ${1-}"; printf '%s' "$1"; }
+# POST a JSON value that may contain a credential without putting the JSON in
+# curl's argv. We force a fresh login first so there is no retry that would need to
+# replay consumed stdin. The body exists only in this shell process and the pipe.
+secret_post() {
+ local route="$1" body="$2" out code payload
+ login
+ out=$(printf '%s' "$body" | curl -sS -b "$JAR" "${ORIGIN[@]}" -w $'\n%{http_code}' \
+ -H 'content-type: application/json' -d @- "$B$route" || true)
+ code="${out##*$'\n'}"; payload="${out%$'\n'*}"
+ case "$code" in 2*) printf '%s' "$payload" ;; *) die "request failed ($code): $payload" ;; esac
+}
+
+tty_ok() { [ -r /dev/tty ] && [ -w /dev/tty ]; }
+tty_print() { if tty_ok; then printf '%s' "$*" > /dev/tty; else printf '%s' "$*"; fi; }
+tty_line() {
+ local prompt="$1" default="${2-}" value=""
+ if ! tty_ok; then REPLY="$default"; return; fi
+ tty_print "$prompt"
+ IFS= read -r value < /dev/tty || true
+ REPLY="${value:-$default}"
+}
+tty_secret() {
+ local prompt="$1" value=""
+ tty_ok || die "a terminal is required to enter a secret; run this command interactively"
+ tty_print "$prompt"
+ stty -echo < /dev/tty
+ IFS= read -r value < /dev/tty || true
+ stty echo < /dev/tty
+ tty_print $'\n'
+ REPLY="$value"
+}
+
+ensure_local_cli_device() {
+ local d; d=$(cli_device)
+ case "$B" in
+ http://127.0.0.1:*|http://localhost:*|http://[::1]:*) ;;
+ *) return 0 ;;
+ esac
+ if ! dev_script --list 2>/dev/null | grep -q "$d"; then
+ dev_script "$d" "mso cli" >/dev/null
+ echo " ✓ approved this local CLI device"
+ fi
+}
+
+onboard_ai() {
+ local yes="$1" choice provider key body response interval code url poll
+ if [ "$yes" = 1 ]; then
+ echo " -- AI provider skipped (-y keeps external accounts unconfigured)"
+ return
+ fi
+ echo
+ echo "AI for Alfa"
+ echo " 0) Skip for now"
+ echo " 1) OpenAI ChatGPT OAuth (Codex consumer backend; no API key)"
+ echo " 2) Anthropic API key"
+ echo " 3) OpenAI Platform API key"
+ echo " 4) OpenRouter API key"
+ echo " 5) Google Gemini API key"
+ echo " 6) Groq API key"
+ echo " 7) xAI API key"
+ echo " 8) DeepSeek API key"
+ echo " 9) Mistral API key"
+ tty_line "Choose [0]: " 0; choice="$REPLY"
+ case "$choice" in
+ 0|'') echo " -- skipped"; return ;;
+ 1)
+ response=$(jpost "/api/oauth/openai" '{"action":"start"}')
+ code=$(jq -r '.userCode // empty' <<<"$response")
+ url=$(jq -r '.verificationUrl // empty' <<<"$response")
+ interval=$(jq -r '.intervalMs // 5000' <<<"$response")
+ [ -n "$code" ] && [ -n "$url" ] || die "OpenAI OAuth did not return a device code"
+ echo
+ echo "Open this URL in any browser: $url"
+ echo "Enter code: $code"
+ echo "Waiting for authorization (Ctrl-C cancels this local wait; it does not expose the code)..."
+ while true; do
+ sleep "$(( interval / 1000 > 2 ? interval / 1000 : 3 ))"
+ poll=$(jpost "/api/oauth/openai" '{"action":"poll"}')
+ if [ "$(jq -r '.ok // false' <<<"$poll")" = true ]; then
+ echo " ✓ OpenAI connected as $(jq -r '.slug' <<<"$poll")"
+ return
+ fi
+ [ "$(jq -r '.pending // false' <<<"$poll")" = true ] || die "OpenAI OAuth failed: $poll"
+ tty_print "."
+ done ;;
+ 2) provider=anthropic ;;
+ 3) provider=openai ;;
+ 4) provider=openrouter ;;
+ 5) provider=google ;;
+ 6) provider=groq ;;
+ 7) provider=xai ;;
+ 8) provider=deepseek ;;
+ 9) provider=mistral ;;
+ *) echo " ! unknown choice; skipped"; return ;;
+ esac
+ echo " $provider uses an API key here (not OAuth). The key is never placed in argv."
+ tty_secret "Paste $provider API key: "; key="$REPLY"
+ [ -n "$key" ] || { echo " -- empty key; skipped"; return; }
+ body=$(jq -nc --arg p "$provider" --arg k "$key" '{provider:$p,apiKey:$k}')
+ secret_post "/api/config" "$body" >/dev/null
+ unset key body REPLY
+ echo " ✓ $provider configured for Alfa"
+}
+
+onboard_style() {
+ local yes="$1" choice style
+ if [ "$yes" = 1 ]; then
+ echo " -- response preset left unchanged (-y keeps existing/default settings)"
+ return
+ else
+ echo
+ echo "Alfa response preset (this is a response style, not a SKILL.md install)"
+ echo " 0) Normal / off"
+ echo " 1) Caveman — terse fragments, preserve technical substance"
+ echo " 2) Ponytail — minimal senior-dev solution, avoid unnecessary code"
+ tty_line "Choose [0]: " 0; choice="$REPLY"
+ case "$choice" in 1) style=caveman ;; 2) style=ponytail ;; *) style=off ;; esac
+ fi
+ jpost "/api/config" "$(jq -nc --arg v "$style" '{tokenSaver:$v}')" >/dev/null
+ echo " ✓ Alfa response preset: $style"
+}
+
+wait_managed_job() {
+ local app="$1" id="$2" since=0 data chunk status next
+ echo " installing $app (job $id)..."
+ while true; do
+ data=$(jget "/api/v1/managed-apps/$(enc "$app")/jobs/$(enc "$id")?since=$since")
+ chunk=$(jq -r '.job.log // empty' <<<"$data")
+ [ -z "$chunk" ] || printf '%s' "$chunk"
+ next=$(jq -r '.job.logOffset // 0' <<<"$data"); since="$next"
+ status=$(jq -r '.job.status // "unknown"' <<<"$data")
+ case "$status" in
+ succeeded) echo " ✓ $app installed"; return ;;
+ failed|interrupted) die "$app install ended: $status — $(jq -r '.job.error // "see job log"' <<<"$data")" ;;
+ esac
+ sleep 2
+ done
+}
+
+onboard_apps() {
+ local yes="$1" choice apps app response id
+ if [ "$yes" = 1 ]; then
+ echo " -- optional managed apps skipped (-y uses minimal defaults)"
+ return
+ fi
+ echo
+ echo "Optional managed applications"
+ echo " These have their own runtime/provider settings; Alfa credentials above do not configure them."
+ echo " 0) None"
+ echo " 1) Hermes"
+ echo " 2) OpenClaw"
+ echo " 3) Both"
+ tty_line "Choose [0]: " 0; choice="$REPLY"
+ case "$choice" in 1) apps="hermes" ;; 2) apps="openclaw" ;; 3) apps="hermes openclaw" ;; *) return ;; esac
+ for app in $apps; do
+ if jget "/api/v1/managed-apps" | jq -e --arg id "$app" '.apps[] | select(.id==$id and .installed==true)' >/dev/null; then
+ echo " ✓ $app already installed"
+ continue
+ fi
+ response=$(jpost "/api/v1/managed-apps/$(enc "$app")/install" '{}')
+ id=$(jq -r '.job.id // empty' <<<"$response")
+ [ -n "$id" ] || die "could not start $app install: $response"
+ wait_managed_job "$app" "$id"
+ done
+}
+
+onboard_skills() {
+ local yes="$1" choice ids
+ echo
+ echo "Curated installable skills"
+ node "$ROOT/scripts/skill-market.mjs" available
+ if [ "$yes" = 1 ]; then
+ echo " -- none installed automatically; run: mso skills install ponytail caveman rtk -y"
+ return
+ fi
+ echo "Enter skill ids separated by spaces/commas, 'all', or blank to skip."
+ tty_line "Skills: " ""; choice="$REPLY"
+ [ -n "$choice" ] || return
+ if [ "$choice" = all ]; then ids=$(node "$ROOT/scripts/skill-market.mjs" available --json | jq -r '.skills[].id' | tr '\n' ' ')
+ else ids=$(printf '%s' "$choice" | tr ',' ' '); fi
+ # The user's selection is the confirmation; suppress per-skill install prompts.
+ # shellcheck disable=SC2086
+ node "$ROOT/scripts/skill-market.mjs" install $ids -y
+}
+
+run_onboard() {
+ local yes=0
+ case "${1-}" in -y|--yes) yes=1 ;; "") ;; *) die "usage: mso onboard [-y|--yes]" ;; esac
+ echo "MSO onboarding"
+ echo "=============="
+ ensure_local_cli_device
+ if [ "$yes" = 0 ] && ! tty_ok; then
+ die "interactive onboarding needs a terminal; use 'mso onboard -y' for safe minimal defaults"
+ fi
+ # Prove the local service/auth path before asking for account credentials.
+ jget "/api/health" >/dev/null
+ jget "/api/auth/me" >/dev/null
+ onboard_ai "$yes"
+ onboard_style "$yes"
+ onboard_apps "$yes"
+ onboard_skills "$yes"
+ echo
+ echo "Onboarding complete."
+ echo " mso -h command reference"
+ echo " mso doctor verify this install"
+ echo " mso skills available installable skills"
+ echo " mso config show Alfa provider/style"
+ echo " mso mapp list Hermes/OpenClaw state"
+}
+
# Print the header block verbatim — stops at the first non-comment line, so the
# help can never drift out of sync with the comment above.
usage() { awk 'NR>1 { if ($0 !~ /^#/) exit; sub(/^# ?/, ""); print }' "$0"; }
@@ -244,12 +455,12 @@ U_service="service status|start|stop|restart|logs [n]"
U_update="update status|run [true]|log"
U_threads="threads list|show <id>|save <json>|rm <id>"
U_memory="memory list|add <text>|rm <id>"
-U_config="config show|set <json>|rm <provider>"
+U_config="config show|set <json>|key <provider>|style <off|caveman|ponytail>|rm <provider>"
U_prefs="prefs show|set <json>"
U_models="models list|test"
-U_skills="skills list|read <id>|search <query…>"
+U_skills="skills list|read <id>|search <query…>|available|info <id>|install <id…> [-y] [--force]|remove <id…> [-y]"
U_mcp="mcp list|activity [n]|revoke <id>|revoke all"
-U_oauth="oauth <provider> start|poll e.g. mso oauth openai start"
+U_oauth="oauth <provider> start|poll OAuth currently: openai (ChatGPT Codex)"
U_audit="audit [n] [prefix] e.g. mso audit 20 exec."
U_crud="crud list <dir> | get <path> | set <path> <cmd k=v…|text> | del <path> | cmds"
U_api="api <METHOD> <path> [json] e.g. mso api GET /api/v1/sys/stats"
@@ -342,6 +553,8 @@ case "$cmd" in
[ "$fails" -eq 0 ] && echo "all good." || echo "$fails check(s) failed."
exit $(( fails > 0 ? 1 : 0 )) ;;
+ onboard) run_onboard "${1-}" ;;
+
# ── camoufox (the real browser the Browser app drives) ────────────────────
camoufox)
case "${1:-status}" in
@@ -413,6 +626,16 @@ case "$cmd" in
case "${1:-show}" in
show) jget "/api/config" ;;
set) jpost "/api/config" "$(json_arg "${2:?json, e.g. '{\"model\":\"gpt-5.6\"}'}")" ;;
+ key) provider="${2:?provider}"
+ case "$provider" in anthropic|openai|openrouter|google|groq|xai|deepseek|mistral) ;;
+ *) die "API-key provider must be one of: anthropic openai openrouter google groq xai deepseek mistral" ;; esac
+ tty_secret "Paste $provider API key: "; key="$REPLY"
+ [ -n "$key" ] || die "empty API key"
+ body=$(jq -nc --arg p "$provider" --arg k "$key" '{provider:$p,apiKey:$k}')
+ secret_post "/api/config" "$body"; unset key body REPLY ;;
+ style) style="${2:?off|caveman|ponytail}"
+ case "$style" in off|caveman|ponytail) ;; *) die "style must be off, caveman or ponytail" ;; esac
+ jpost "/api/config" "$(jq -nc --arg v "$style" '{tokenSaver:$v}')" ;;
rm) jdel "/api/config?provider=$(enc "${2:?provider}")" ;;
*) die "usage: mso $U_config" ;;
esac ;;
@@ -435,6 +658,10 @@ case "$cmd" in
jget "/api/skills?name=$(enc "$2")" ;;
search) shift; [ $# -gt 0 ] || die "usage: mso $U_skills"
jget "/api/skills?q=$(enc "$*")" ;;
+ available) shift; node "$ROOT/scripts/skill-market.mjs" available "$@" ;;
+ info) shift; node "$ROOT/scripts/skill-market.mjs" info "$@" ;;
+ install) shift; node "$ROOT/scripts/skill-market.mjs" install "$@" ;;
+ remove|rm) shift; node "$ROOT/scripts/skill-market.mjs" remove "$@" ;;
*) jget "/api/skills?name=$(enc "$1")" ;;
esac ;;
# Generated from git subjects by scripts/gen-changelog.mjs; `jq -r` because the
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 8dd503f8..67b027d2 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.
**Added**
+- add interactive onboarding and skill market
- complete terminal and mobile app surfaces
**Fixed**
diff --git a/docs/CLI.md b/docs/CLI.md
index 784d5df7..4e149539 100644
--- a/docs/CLI.md
+++ b/docs/CLI.md
@@ -73,6 +73,7 @@ Commands:
status Public service status (no session needed)
health Is this CLI's session valid?
doctor Check deps, env, service, session, device — and say what broke
+ onboard [-y] Guided first-run setup: AI, response style, managed apps, skills
Browser
camoufox * Power the anti-detection VNC browser + read its password
@@ -86,10 +87,10 @@ Commands:
ai <prompt…> One turn with the assistant
threads * Conversation history: list | show | rm
memory * Assistant memories: list | add | rm
- config * BYOK provider + model: show | set | rm
+ config * BYOK provider + model/style: show | set | key | style | rm
prefs * UI preferences: show | set
models * Model catalog: list | test
- skills * Skills across every project: list | read <id> | search <query>
+ skills * Discover host skills + curated market: available/install/remove
changelog What shipped, newest first (same text Settings → About shows)
mcp * MCP tokens + live activity: list | activity [n] | revoke <id> | revoke all
oauth <prov> * Provider sign-in (device code): start | poll
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 5cf38c06..e5145f63 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -27,14 +27,17 @@ curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install
The installer:
-1. resolves/creates the checkout;
+1. resolves/creates the checkout and records whether this is a fresh install;
2. installs Bun/dependencies as needed;
3. creates private owner auth configuration when missing;
4. runs the production build;
5. installs the `mso.service` system unit when systemd is available;
6. enables the owner's lingering user manager needed by self-update/managed-app user units;
-7. installs the `mso` CLI convenience link and official skills;
-8. starts/replaces the service only after a successful build.
+7. installs `~/.local/bin/mso` plus a guarded `/usr/local/bin/mso` launcher so the parent
+ shell can resolve `mso` immediately after `curl | bash` returns;
+8. persists an idempotent `~/.local/bin` PATH fallback for future shells;
+9. starts/replaces the service only after a successful build;
+10. on a fresh interactive install, opens `/dev/tty` and launches `mso onboard`.
Useful flags:
@@ -44,11 +47,41 @@ Useful flags:
--port N app port (default 4005)
--bind ADDR listen address (default 127.0.0.1)
--no-service build without installing the system unit
+--onboard force guided onboarding (including on an update)
+--no-onboard suppress automatic onboarding
+-y, --yes non-interactive safe defaults; no external accounts/apps/skills
--uninstall remove the system unit; keep code + ~/.mso
```
-Re-running the installer updates an existing installation with the same build-before-replace
-safety rule.
+`curl | bash` cannot use stdin for questions because stdin carries the script itself. The
+installer therefore prompts through `/dev/tty`. If there is no controlling terminal it
+never waits for input and tells the operator to run `mso onboard` later. Re-running the
+installer updates an existing installation with the same build-before-replace safety rule
+and does not repeat onboarding unless `--onboard` is requested.
+
+### Guided onboarding
+
+Run or resume it at any time:
+
+```bash
+mso onboard
+```
+
+It first approves the **local CLI device** in the owner allowlist (a process already running
+as the owning Unix account has equivalent host authority), then verifies the local service
+and session before asking for provider credentials. API keys are read with terminal echo
+disabled and posted from stdin; they are not placed in the CLI/curl argv.
+
+The current provider choices are OpenAI ChatGPT/Codex device OAuth, plus API-key providers
+Anthropic, OpenAI Platform, OpenRouter, Google, Groq, xAI, DeepSeek and Mistral. OpenRouter
+is an API-key integration here, not OAuth. The OpenAI OAuth path is the ChatGPT consumer
+Codex backend; it is separate from OpenAI Platform API keys and separate again from MSO's
+ChatGPT MCP OAuth.
+
+Hermes/OpenClaw installation is optional and uses each app's existing managed-job installer.
+Their model/provider configuration belongs to those applications and is not implicitly
+filled from Alfa's credential. Selected app installs stream their job transcript until a
+terminal status.
## 2. Network exposure
@@ -165,7 +198,32 @@ The optional `openai-codex` provider uses a separate ChatGPT consumer OAuth/devi
Alfa inference. It is unrelated to the ChatGPT MCP connector. See
`docs/MODELS-INTEGRATION.md`.
-## 8. Optional MCP / ChatGPT custom app
+## 8. Curated skill installation
+
+MSO distinguishes **discovery** from **installation**. `mso skills list/search/read` inspect
+the live trusted/discovered catalog. The curated market is a smaller committed review set:
+
+```bash
+mso skills available
+mso skills info ponytail
+mso skills install ponytail caveman rtk -y
+mso skills remove ponytail -y
+```
+
+Market packages are pinned in `skill-market/catalog.json`. The installer verifies the
+committed `SKILL.md` SHA-256 and frontmatter before copying it to `~/.mso/skills/<id>`
+(override only for CLI/operator workflows with `MSO_SKILL_INSTALL_ROOT`), then writes
+`.mso-market.json` provenance. `-y` makes a selected normal install/removal
+non-interactive, but it does **not** overwrite a modified/local skill; replacement requires
+`--force` explicitly. Removal also refuses directories without MSO market provenance.
+
+Ponytail and Caveman are pinned reviewed snapshots. `rtk` is deliberately an MSO-safe
+wrapper rather than the current upstream RTK Integration package: the upstream scan warns
+about automatically executing an unpinned remote installer and editing shell profiles. The
+MSO wrapper only teaches use of an already-installed RTK binary and requires a separate
+explicit request for system installation/hooks.
+
+## 9. Optional MCP / ChatGPT custom app
MCP is **off by default**. Enable it only for a deployment that needs external AI clients:
@@ -178,7 +236,7 @@ Use `docs/CHATGPT-PLUGIN.md` for ChatGPT setup and diagrams, and `docs/MCP.md` f
complete protocol/security model. After changing the MCP toolset, refresh/re-scan the
ChatGPT app; MSO's "Mark ChatGPT refreshed" button is only a local acknowledgement.
-## 9. Optional managed-app dashboards
+## 10. Optional managed-app dashboards
Hermes/OpenClaw lifecycle management works without embedding their web dashboards. The safe
default is therefore no vendor dashboard on the MSO origin.
@@ -195,7 +253,7 @@ Provision DNS/TLS only for the explicit `hermes` and `openclaw` hostnames and si
after changing the cookie domain. There is no supported same-origin iframe fallback. See
`docs/MANAGED-APPS.md`.
-## 10. Public demo mode
+## 11. Public demo mode
A public showcase must be a separate checkout/service built with:
@@ -206,7 +264,7 @@ NEXT_PUBLIC_OS_DEMO=1 bun run build
Demo mode is mock-only: no normal owner auth, no live host API, no real PTY/exec, no MCP and
no API-key storage. Do not toggle demo mode in the production owner checkout.
-## 11. Updating
+## 12. Updating
### Operator update
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 20f251da..0a8e3bc9 100644
--- a/docs/PROGRESS.md
+++ b/docs/PROGRESS.md
@@ -9,6 +9,58 @@ Running log of what shipped each phase. Newest at top.
> [`docs/README.md`](./README.md) and [`docs/ARCHITECTURE.md`](./ARCHITECTURE.md); keep old
> entries intact as historical evidence even when their commands/counts have been superseded.
+## 2026-08-24 — one-line install now ends in terminal onboarding + reviewed skill market (DONE)
+
+The one-line installer previously did the build/service work but stopped at a block of
+printed next steps. It created `~/.local/bin/mso` and merely warned when that directory was
+not on the current PATH; because `curl | bash` runs in a child process, exporting PATH there
+cannot make `mso -h` available in the parent shell. It was also intentionally
+non-interactive, so a successful fresh install felt like "nothing happened" once the build
+finished.
+
+Fresh service installs now create the user launcher plus a guarded `/usr/local/bin/mso`
+symlink (only when the name is free or already points into this install), persist an
+idempotent `~/.local/bin` fallback in the normal shell profile, and assert that `mso` is
+resolvable before finishing. Uninstall removes only launchers that still point into the
+MSO checkout. The bootstrap remains pipe-safe, but a **fresh** interactive install opens
+`/dev/tty` after health succeeds and launches new `mso onboard`; existing installs do not
+repeat it unless `--onboard` is passed, `--no-onboard` suppresses it, and no-TTY/cloud-init
+installs never block. `-y` runs safe minimal onboarding: it leaves external AI accounts,
+response style, optional managed apps and community skills untouched.
+
+`mso onboard` is reusable and configures the existing surfaces rather than inventing a
+second settings store. It can connect Alfa through OpenAI ChatGPT/Codex device OAuth, or
+securely read an Anthropic/OpenAI Platform/OpenRouter/Google/Groq/xAI/DeepSeek/Mistral API
+key from the controlling terminal with echo disabled and post it via stdin rather than
+process argv. It exposes Normal/Caveman/Ponytail response presets, optionally runs the real
+Hermes/OpenClaw managed-app install jobs while streaming their transcripts, then presents
+the reviewed skill market. Managed-app provider state remains explicitly separate from
+Alfa credentials. Settings' old "Codex is chat-only" copy was removed because the current
+Codex Responses adapter forwards Alfa tools.
+
+The new curated skill market is intentionally different from general skill discovery.
+`mso skills available/info/install/remove` installs exact committed, SHA-256-checked
+`SKILL.md` files into the explicit operator-trust root `~/.mso/skills`, recording
+`.mso-market.json` provenance. `-y` confirms only the entries the operator selected; it
+will not overwrite a modified/local skill without an additional explicit `--force`, and
+removal refuses directories it did not install. Initial reviewed entries are pinned
+Ponytail 4.9.0, Caveman 1.0.2, and an MSO-authored safe RTK wrapper. RTK deliberately does
+not copy the current upstream auto-setup instructions: it uses RTK only when the binary is
+already installed and never runs an unpinned remote installer, edits shell profiles or
+enables global hooks without a separate explicit system-change request. Caveman/Ponytail
+remain available independently as Alfa response presets; selecting a preset never silently
+installs the full skill.
+
+README, `docs/INSTALL.md`, generated `docs/CLI.md`, `skills/README.md`, and the public
+`/install` page now describe this same lifecycle. Regression tests pin installer TTY/PATH
+behaviour, public install copy, credential transport, safe `-y`, skill hash/provenance,
+modified-skill overwrite refusal, and unmanaged-skill deletion refusal. Full verification:
+185 test files / 1,585 tests passed (1 expected fail, 4 skipped), typecheck green, lint has
+the one pre-existing max-lines warning and zero errors, docs checker reports 38 Markdown
+files / 28 MCP tools / 21 slices / 10 AppShell feature dirs, 9 official skills are valid,
+value cycles remain zero, contrast has zero AA failures, and the high/critical dependency
+audit is clean.
+
## 2026-08-24 — documentation authority + ChatGPT MCP guide (DONE)
The documentation set was audited against current source and the deployed/public MCP
diff --git a/frontend/slices/os-settings/components/oauth-connect.tsx b/frontend/slices/os-settings/components/oauth-connect.tsx
index 3d539a64..ae22f108 100644
--- a/frontend/slices/os-settings/components/oauth-connect.tsx
+++ b/frontend/slices/os-settings/components/oauth-connect.tsx
@@ -78,14 +78,8 @@ export function OAuthConnect({ onConnected }: { onConnected: () => void }) {
<Button variant="outline" size="sm" className="[@media(pointer:coarse)]:min-h-[44px]" disabled={busy} onClick={start}>
{busy ? "Starting…" : "Sign in with OpenAI (ChatGPT)"}
</Button>
- {/* Said out loud because this path is the ZERO-FRICTION one — no key to paste —
- and it silently turns off the thing the product leads with. The Codex branch
- in app/api/assistant/route.ts never forwards the tools array (codex-stream.ts
- sends no `tools` field at all), so Alfa answers fluently and simply cannot
- call anything. Without this line the only symptom is an assistant that
- politely explains what it would do. */}
<p className="text-xs text-muted-foreground">
- Chat only. Alfa&apos;s host tools need an API-key provider — Anthropic, or OpenAI platform.
+ Uses your ChatGPT Codex subscription through device OAuth. Alfa&apos;s normal tool catalog is forwarded on this path too.
</p>
</div>
) : (
diff --git a/lib/install-contract.test.ts b/lib/install-contract.test.ts
new file mode 100644
index 00000000..fe2440ac
--- /dev/null
+++ b/lib/install-contract.test.ts
@@ -0,0 +1,32 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const INSTALL = path.join(__dirname, "../scripts/install.sh");
+
+describe("one-line installer contract", () => {
+ it("is valid bash and documents onboarding controls", () => {
+ expect(() => execFileSync("bash", ["-n", INSTALL])).not.toThrow();
+ const help = execFileSync("bash", [INSTALL, "--help"], { encoding: "utf8" });
+ expect(help).toContain("--onboard");
+ expect(help).toContain("--no-onboard");
+ expect(help).toContain("-y, --yes");
+ });
+
+ it("uses the controlling tty after curl|bash and never stdin for onboarding", () => {
+ const src = fs.readFileSync(INSTALL, "utf8");
+ expect(src).toContain("[ -r /dev/tty ] && [ -w /dev/tty ]");
+ expect(src).toContain('onboard </dev/tty >/dev/tty 2>/dev/tty');
+ expect(src).toContain('ONBOARD_MODE=auto');
+ expect(src).toContain('FRESH_INSTALL=1');
+ });
+
+ it("makes mso discoverable immediately and persists the user PATH fallback", () => {
+ const src = fs.readFileSync(INSTALL, "utf8");
+ expect(src).toContain("SYSTEM_CLI=/usr/local/bin/mso");
+ expect(src).toContain("# >>> mso cli >>>");
+ expect(src).toContain('export PATH="$BIN_DIR:$PATH"');
+ expect(src).toContain('command -v mso');
+ });
+});
diff --git a/lib/onboard-contract.test.ts b/lib/onboard-contract.test.ts
new file mode 100644
index 00000000..65e98adb
--- /dev/null
+++ b/lib/onboard-contract.test.ts
@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const cli = fs.readFileSync(path.join(__dirname, "../bin/mso"), "utf8");
+
+describe("terminal onboarding contract", () => {
+ it("keeps API keys out of curl argv", () => {
+ expect(cli).toContain('tty_secret "Paste $provider API key: "');
+ expect(cli).toContain("stty -echo < /dev/tty");
+ const start = cli.indexOf("secret_post() {");
+ const end = cli.indexOf("\n}\n\ntty_ok()", start);
+ const secretPost = cli.slice(start, end);
+ expect(secretPost).toContain("-d @-");
+ expect(secretPost).toContain('printf \'%s\' "$body" | curl');
+ expect(secretPost).not.toContain('-d "$body"');
+ expect(cli).toContain('secret_post "/api/config" "$body"');
+ });
+
+ it("documents OAuth separately from API-key providers", () => {
+ expect(cli).toContain("OpenAI ChatGPT OAuth (Codex consumer backend; no API key)");
+ expect(cli).toContain("OpenRouter API key");
+ expect(cli).toContain("OpenAI Platform API key");
+ });
+
+ it("keeps -y minimal instead of selecting external accounts or installs", () => {
+ expect(cli).toContain("AI provider skipped (-y keeps external accounts unconfigured)");
+ expect(cli).toContain("response preset left unchanged (-y keeps existing/default settings)");
+ expect(cli).toContain("optional managed apps skipped (-y uses minimal defaults)");
+ expect(cli).toContain("none installed automatically; run: mso skills install ponytail caveman rtk -y");
+ });
+});
diff --git a/lib/skill-market.test.ts b/lib/skill-market.test.ts
new file mode 100644
index 00000000..dd9ce475
--- /dev/null
+++ b/lib/skill-market.test.ts
@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+const SCRIPT = path.join(__dirname, "../scripts/skill-market.mjs");
+const run = (root: string, ...args: string[]) =>
+ execFileSync("node", [SCRIPT, ...args], {
+ encoding: "utf8",
+ env: { ...process.env, MSO_SKILL_INSTALL_ROOT: root },
+ });
+
+describe("curated skill market", () => {
+ it("lists the reviewed installable catalog", () => {
+ const root = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "mso-skill-market-")), "skills");
+ const out = run(root, "available");
+ expect(out).toContain("ponytail");
+ expect(out).toContain("caveman");
+ expect(out).toContain("rtk");
+ expect(out).toContain("mso-safe-wrapper");
+ });
+
+ it("installs multiple selected skills non-interactively with provenance", () => {
+ const root = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "mso-skill-market-")), "skills");
+ run(root, "install", "ponytail", "caveman", "rtk", "-y");
+ for (const id of ["ponytail", "caveman", "rtk"]) {
+ expect(fs.readFileSync(path.join(root, id, "SKILL.md"), "utf8")).toContain(`name: ${id}`);
+ const marker = JSON.parse(fs.readFileSync(path.join(root, id, ".mso-market.json"), "utf8"));
+ expect(marker.id).toBe(id);
+ expect(marker.sha256).toMatch(/^[a-f0-9]{64}$/);
+ }
+ expect(run(root, "available")).toContain("installed");
+ });
+
+ it("does not let -y clobber a locally modified skill without --force", () => {
+ const root = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "mso-skill-market-")), "skills");
+ run(root, "install", "ponytail", "-y");
+ const skill = path.join(root, "ponytail", "SKILL.md");
+ fs.appendFileSync(skill, "\nlocal edit\n");
+ expect(() => run(root, "install", "ponytail", "-y")).toThrow();
+ expect(fs.readFileSync(skill, "utf8")).toContain("local edit");
+ run(root, "install", "ponytail", "-y", "--force");
+ expect(fs.readFileSync(skill, "utf8")).not.toContain("local edit");
+ });
+
+ it("removes only skills carrying MSO market provenance", () => {
+ const root = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "mso-skill-market-")), "skills");
+ fs.mkdirSync(path.join(root, "ponytail"), { recursive: true });
+ fs.writeFileSync(path.join(root, "ponytail", "SKILL.md"), "---\nname: ponytail\n---\nlocal\n");
+ expect(() => run(root, "remove", "ponytail", "-y")).toThrow();
+ expect(fs.existsSync(path.join(root, "ponytail", "SKILL.md"))).toBe(true);
+ });
+});
diff --git a/scripts/install.sh b/scripts/install.sh
index 6b6807ff..791c7a79 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -4,9 +4,9 @@
# curl -fsSL https://raw.githubusercontent.com/rahmanef63/mso/main/scripts/install.sh | bash
#
# Idempotent: re-running updates the checkout, rebuilds, and restarts the
-# service. Fully non-interactive (safe for curl|bash — no tty): the login
-# password + session secret are GENERATED, never prompted, and an existing
-# .env.local is preserved.
+# service. The bootstrap never needs stdin, so curl|bash stays safe. After a
+# FRESH install it uses /dev/tty (when present) for guided onboarding; CI/headless
+# installs never hang and can run `mso onboard` later. Existing .env.local is preserved.
set -euo pipefail
# ---- config: env override > flag > default ----
@@ -32,6 +32,9 @@ BIND="${MSO_BIND:-127.0.0.1}"
SERVICE="mso.service"
DO_SERVICE=1
DO_UNINSTALL=0
+YES=0
+ONBOARD_MODE=auto
+FRESH_INSTALL=0
# bun is the package manager; the RUNTIME stays node (see ensure_bun below).
export BUN_INSTALL="${BUN_INSTALL:-$HOME/.bun}"
@@ -55,6 +58,9 @@ mso installer
--bind ADDR listen address (default: 127.0.0.1). 0.0.0.0 publishes a shell
to every network this host is on — see the note in this file.
--no-service build only; skip the systemd unit
+ --onboard run guided onboarding even on an existing install
+ --no-onboard never start onboarding automatically
+ -y, --yes safe non-interactive defaults (no external accounts/apps/skills)
--uninstall stop+disable+remove the systemd unit (keeps code + ~/.mso)
-h, --help this help
Env: MSO_DIR MSO_REF MSO_PORT MSO_BIND MSO_REPO
@@ -68,6 +74,9 @@ while [ $# -gt 0 ]; do
--port) PORT="$2"; shift 2 ;;
--bind) BIND="$2"; shift 2 ;;
--no-service) DO_SERVICE=0; shift ;;
+ --onboard) ONBOARD_MODE=always; shift ;;
+ --no-onboard) ONBOARD_MODE=never; shift ;;
+ -y|--yes) YES=1; shift ;;
--uninstall) DO_UNINSTALL=1; shift ;;
-h|--help) usage; exit 0 ;;
*) die "unknown arg: $1 (see --help)" ;;
@@ -85,6 +94,7 @@ if [ "$DIR_EXPLICIT" -eq 0 ] && command -v systemctl >/dev/null 2>&1; then
existing="$(systemctl show -p WorkingDirectory --value "$SERVICE" 2>/dev/null || true)"
[ -n "$existing" ] && [ -d "$existing/.git" ] && DIR="$existing" && info "found existing service → updating $DIR"
fi
+[ -d "$DIR/.git" ] || FRESH_INSTALL=1
# ---- uninstall ----
if [ "$DO_UNINSTALL" -eq 1 ]; then
@@ -106,6 +116,9 @@ if [ "$DO_UNINSTALL" -eq 1 ]; then
if [ -L "$UNINST_BIN" ] && case "$(readlink "$UNINST_BIN")" in "$DIR/"*) true ;; *) false ;; esac; then
rm -f "$UNINST_BIN"; ok "removed cli symlink $UNINST_BIN"
fi
+ if [ -L /usr/local/bin/mso ] && case "$(readlink /usr/local/bin/mso)" in "$DIR/"*) true ;; *) false ;; esac; then
+ sudo_do rm -f /usr/local/bin/mso; ok "removed cli symlink /usr/local/bin/mso"
+ fi
UNINST_SKILLS="${MSO_SKILL_DIR:-$HOME/.claude/skills}"
if [ -d "$UNINST_SKILLS" ]; then
for l in "$UNINST_SKILLS"/*; do
@@ -351,10 +364,58 @@ BIN_DIR="${MSO_BIN_DIR:-$HOME/.local/bin}"
mkdir -p "$BIN_DIR"
ln -sfn "$DIR/bin/mso" "$BIN_DIR/mso"
ok "cli → $BIN_DIR/mso"
+
+# Make the command available to the PARENT shell immediately after curl|bash returns.
+# A child installer cannot export PATH back into its parent. /usr/local/bin is already
+# on the normal system PATH, so install a second launcher there when the name is free
+# (or already ours). Never overwrite an unrelated system command.
+if [ "$DO_SERVICE" -eq 1 ]; then
+ SYSTEM_CLI=/usr/local/bin/mso
+ if [ ! -e "$SYSTEM_CLI" ] && [ ! -L "$SYSTEM_CLI" ]; then
+ sudo_do ln -s "$DIR/bin/mso" "$SYSTEM_CLI"
+ ok "system cli → $SYSTEM_CLI"
+ elif [ -L "$SYSTEM_CLI" ]; then
+ current_cli="$(readlink "$SYSTEM_CLI")"
+ case "$current_cli" in
+ "$DIR/"*) sudo_do ln -sfn "$DIR/bin/mso" "$SYSTEM_CLI"; ok "system cli → $SYSTEM_CLI" ;;
+ *) warn "$SYSTEM_CLI already points elsewhere ($current_cli) — left untouched" ;;
+ esac
+ else
+ warn "$SYSTEM_CLI already exists and is not a symlink — left untouched"
+ fi
+else
+ info "--no-service: skipped /usr/local/bin launcher (user CLI still at $BIN_DIR/mso)"
+fi
+
+# A fresh distro often omits ~/.local/bin from PATH. Persist one small idempotent
+# block for future shells, and export it now so onboarding can invoke `mso`.
+path_block() {
+ local rc="$1"
+ [ -e "$rc" ] || : > "$rc"
+ grep -q '^# >>> mso cli >>>$' "$rc" 2>/dev/null && return
+ cat >> "$rc" <<'EOF'
+
+# >>> mso cli >>>
case ":$PATH:" in
- *":$BIN_DIR:"*) ;;
- *) warn "$BIN_DIR is not on PATH — add: export PATH=\"\$PATH:$BIN_DIR\"" ;;
+ *":$HOME/.local/bin:"*) ;;
+ *) export PATH="$HOME/.local/bin:$PATH" ;;
esac
+# <<< mso cli <<<
+EOF
+ info "added ~/.local/bin to PATH in $rc"
+}
+if [ "$BIN_DIR" = "$HOME/.local/bin" ]; then
+ path_block "$HOME/.profile"
+ case "${SHELL:-}" in
+ */bash) path_block "$HOME/.bashrc" ;;
+ */zsh) path_block "$HOME/.zshrc" ;;
+ esac
+else
+ warn "custom MSO_BIN_DIR=$BIN_DIR is not written into shell profiles; add it to PATH yourself"
+fi
+export PATH="$BIN_DIR:$PATH"
+command -v mso >/dev/null 2>&1 || die "CLI symlink exists but is not executable: $BIN_DIR/mso"
+ok "mso command ready ($(command -v mso))"
# ---- optional Claude Code integration ----
# MSO catalogs $DIR/claude-skills directly, so these symlinks are NOT required by MSO.
@@ -411,6 +472,33 @@ cat <<EOF
Env: $DIR/.env.local
EOF
[ -n "$GEN_PW" ] && printf ' Password: %s (shown once — save it now; edit OS_LOGIN_PASSWORD in .env.local + restart to change)\n' "$GEN_PW"
+
+# A successful fresh install should lead directly into a usable product. curl|bash
+# owns stdin, so interactive setup uses the controlling terminal explicitly.
+RUN_ONBOARD=0
+case "$ONBOARD_MODE" in
+ always) RUN_ONBOARD=1 ;;
+ never) RUN_ONBOARD=0 ;;
+ auto) [ "$FRESH_INSTALL" -eq 1 ] && RUN_ONBOARD=1 ;;
+esac
+if [ "$RUN_ONBOARD" -eq 1 ] && [ "$DO_SERVICE" -eq 1 ]; then
+ if [ "$YES" -eq 1 ]; then
+ echo
+ info "running minimal non-interactive onboarding (-y)…"
+ "$BIN_DIR/mso" onboard -y || warn "onboarding did not finish — rerun: mso onboard"
+ elif [ -r /dev/tty ] && [ -w /dev/tty ]; then
+ echo
+ info "starting guided onboarding…"
+ if ! "$BIN_DIR/mso" onboard </dev/tty >/dev/tty 2>/dev/tty; then
+ warn "onboarding stopped early — resume anytime with: mso onboard"
+ fi
+ else
+ echo
+ warn "no interactive terminal detected — onboarding skipped. Run: mso onboard"
+ fi
+elif [ "$RUN_ONBOARD" -eq 1 ]; then
+ warn "--no-service leaves no running API to configure — run 'mso onboard' after starting MSO"
+fi
cat <<EOF
Pair your first device (device approval is a browser allowlist, not standards-based 2FA):
diff --git a/scripts/skill-market.mjs b/scripts/skill-market.mjs
new file mode 100755
index 00000000..fc056716
--- /dev/null
+++ b/scripts/skill-market.mjs
@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repo = path.resolve(here, "..");
+const market = path.join(repo, "skill-market");
+const catalog = JSON.parse(fs.readFileSync(path.join(market, "catalog.json"), "utf8"));
+const root = path.resolve(process.env.MSO_SKILL_INSTALL_ROOT || path.join(os.homedir(), ".mso", "skills"));
+const sha = (data) => crypto.createHash("sha256").update(data).digest("hex");
+const fail = (message) => { console.error(`mso skills: ${message}`); process.exitCode = 1; };
+
+function safeEntry(id) {
+ const entry = catalog.skills.find((row) => row.id === id);
+ if (!entry) throw new Error(`unknown market skill "${id}"; run: mso skills available`);
+ if (!/^[a-z][a-z0-9-]{0,63}$/.test(entry.id)) throw new Error(`invalid catalog id: ${entry.id}`);
+ const file = path.resolve(market, entry.file);
+ if (!file.startsWith(`${market}${path.sep}`)) throw new Error(`catalog path escapes market: ${entry.file}`);
+ const stat = fs.lstatSync(file);
+ if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${entry.id}: SKILL.md must be a regular file`);
+ const body = fs.readFileSync(file);
+ if (body.length === 0 || body.length > 256 * 1024) throw new Error(`${entry.id}: invalid SKILL.md size`);
+ if (sha(body) !== entry.sha256) throw new Error(`${entry.id}: catalog hash mismatch; repository review is stale`);
+ const text = body.toString("utf8");
+ const match = text.match(/^---\s*\n[\s\S]*?^name:\s*["']?([^\n"']+)["']?\s*$[\s\S]*?^---\s*$/m);
+ if (!match || match[1].trim() !== entry.id) throw new Error(`${entry.id}: SKILL.md frontmatter name does not match catalog id`);
+ return { entry, file, body };
+}
+
+function ensureRoot() {
+ fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+ const stat = fs.lstatSync(root);
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`install root is not a real directory: ${root}`);
+}
+
+function installedState(entry) {
+ const dir = path.join(root, entry.id);
+ if (!fs.existsSync(dir)) return "not-installed";
+ const st = fs.lstatSync(dir);
+ if (!st.isDirectory() || st.isSymbolicLink()) return "conflict";
+ const skill = path.join(dir, "SKILL.md");
+ if (!fs.existsSync(skill) || fs.lstatSync(skill).isSymbolicLink()) return "conflict";
+ return sha(fs.readFileSync(skill)) === entry.sha256 ? "installed" : "modified";
+}
+
+async function confirm(question, yes) {
+ if (yes) return true;
+ if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+ const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
+ rl.close();
+ return answer === "y" || answer === "yes";
+}
+
+async function installOne(id, { yes, force }) {
+ const { entry, body } = safeEntry(id);
+ ensureRoot();
+ const state = installedState(entry);
+ if (state === "installed") { console.log(`${id}: already installed`); return; }
+ if ((state === "modified" || state === "conflict") && !force) {
+ throw new Error(`${id}: existing local skill would be overwritten; inspect it, then use --force explicitly`);
+ }
+ if ((state === "modified" || state === "conflict") && !(await confirm(`Replace existing ${id}?`, yes))) {
+ throw new Error(`${id}: not replaced`);
+ }
+
+ const target = path.join(root, id);
+ const temp = path.join(root, `.mso-market-${id}-${process.pid}-${Date.now()}`);
+ fs.mkdirSync(temp, { mode: 0o700 });
+ try {
+ fs.writeFileSync(path.join(temp, "SKILL.md"), body, { mode: 0o600 });
+ fs.writeFileSync(path.join(temp, ".mso-market.json"), JSON.stringify({
+ catalogVersion: catalog.version,
+ id: entry.id,
+ sha256: entry.sha256,
+ sourceRef: entry.sourceRef,
+ sourceVersion: entry.sourceVersion,
+ installedAt: new Date().toISOString(),
+ }, null, 2), { mode: 0o600 });
+ if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+ fs.renameSync(temp, target);
+ } catch (error) {
+ fs.rmSync(temp, { recursive: true, force: true });
+ throw error;
+ }
+ console.log(`${id}: installed → ${target}`);
+}
+
+async function removeOne(id, { yes }) {
+ const { entry } = safeEntry(id);
+ const target = path.join(root, entry.id);
+ if (!fs.existsSync(target)) { console.log(`${id}: not installed`); return; }
+ const marker = path.join(target, ".mso-market.json");
+ if (!fs.existsSync(marker)) throw new Error(`${id}: refusing to delete an unmanaged/local skill`);
+ let managed;
+ try { managed = JSON.parse(fs.readFileSync(marker, "utf8")); } catch { throw new Error(`${id}: invalid market marker; refusing removal`); }
+ if (managed.id !== id) throw new Error(`${id}: market marker mismatch; refusing removal`);
+ if (!(await confirm(`Remove ${id}?`, yes))) throw new Error(`${id}: not removed (pass -y for non-interactive removal)`);
+ fs.rmSync(target, { recursive: true, force: true });
+ console.log(`${id}: removed`);
+}
+
+function printList(json = false) {
+ const rows = catalog.skills.map((entry) => ({
+ id: entry.id,
+ title: entry.title,
+ description: entry.description,
+ version: entry.sourceVersion,
+ source: entry.sourceRef,
+ security: entry.security,
+ state: installedState(entry),
+ }));
+ if (json) return console.log(JSON.stringify({ catalogVersion: catalog.version, root, skills: rows }, null, 2));
+ for (const row of rows) console.log(`${row.id.padEnd(12)} ${row.state.padEnd(13)} ${row.security.padEnd(19)} ${row.title} — ${row.description}`);
+}
+
+function printInfo(id) {
+ const { entry } = safeEntry(id);
+ console.log(JSON.stringify({ ...entry, state: installedState(entry), installRoot: root }, null, 2));
+}
+
+const args = process.argv.slice(2);
+const command = args.shift() || "list";
+const yes = args.includes("-y") || args.includes("--yes");
+const force = args.includes("--force");
+const json = args.includes("--json");
+const ids = args.filter((arg) => !["-y", "--yes", "--force", "--json"].includes(arg));
+
+try {
+ if (command === "list" || command === "available") printList(json);
+ else if (command === "info") { if (ids.length !== 1) throw new Error("usage: mso skills info <id>"); printInfo(ids[0]); }
+ else if (command === "install") {
+ if (!ids.length) throw new Error("usage: mso skills install <id…> [-y] [--force]");
+ for (const id of ids) await installOne(id, { yes, force });
+ } else if (command === "remove" || command === "rm") {
+ if (!ids.length) throw new Error("usage: mso skills remove <id…> [-y]");
+ for (const id of ids) await removeOne(id, { yes });
+ } else throw new Error("commands: available | info <id> | install <id…> [-y] [--force] | remove <id…> [-y]");
+} catch (error) {
+ fail(error instanceof Error ? error.message : String(error));
+}
diff --git a/skill-market/catalog.json b/skill-market/catalog.json
new file mode 100644
index 00000000..3305ed5a
--- /dev/null
+++ b/skill-market/catalog.json
@@ -0,0 +1,43 @@
+{
+ "version": 1,
+ "reviewedAt": "2026-08-24",
+ "skills": [
+ {
+ "id": "ponytail",
+ "title": "Ponytail",
+ "description": "Minimalist senior-developer coding mode: YAGNI, standard library first, smallest working change.",
+ "file": "ponytail/SKILL.md",
+ "sha256": "dd240060d5734a58fe2783916a63f9401fed75c5f87742dd663a66f9ed4c8c65",
+ "sourceRef": "@dietrichgebert/ponytail",
+ "sourceVersion": "4.9.0",
+ "sourceUrl": "https://clawhub.ai/dietrichgebert/skills/ponytail",
+ "license": "MIT",
+ "security": "clean"
+ },
+ {
+ "id": "caveman",
+ "title": "Caveman",
+ "description": "Ultra-terse response mode that cuts filler while preserving technical substance.",
+ "file": "caveman/SKILL.md",
+ "sha256": "8d3e45d3084847228cbd80b1562323fc19f781e2f06fa955ea5bd671a0e45d9e",
+ "sourceRef": "@skaravind/caveman",
+ "sourceVersion": "1.0.2",
+ "sourceUrl": "https://clawhub.ai/skaravind/skills/caveman",
+ "license": "MIT-0",
+ "security": "clean-with-warnings"
+ },
+ {
+ "id": "rtk",
+ "title": "RTK (safe wrapper)",
+ "description": "Use an already-installed RTK to compress verbose shell output; never auto-installs binaries or global hooks.",
+ "file": "rtk/SKILL.md",
+ "sha256": "fb33a65e48f29266681fd01be939ac398306bae5cb3df688ab100a9914902453",
+ "sourceRef": "mso-curated/rtk",
+ "sourceVersion": "1",
+ "sourceUrl": "https://clawhub.ai/davydenkovm/skills/rtk-integration",
+ "license": "MIT",
+ "security": "mso-safe-wrapper",
+ "upstreamNote": "The upstream rtk-integration 1.1.0 scan was suspicious because it auto-runs an unpinned remote installer and edits shell profiles. This committed wrapper deliberately removes that behavior."
+ }
+ ]
+}
diff --git a/skill-market/caveman/SKILL.md b/skill-market/caveman/SKILL.md
new file mode 100644
index 00000000..18d9cabd
--- /dev/null
+++ b/skill-market/caveman/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: caveman
+description: Ultra-compressed communication mode. Slash token usage ~75% by speaking like smart caveman while keeping technical accuracy. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested. Based on Julius Brussee's original caveman repo: https://github.com/JuliusBrussee/caveman.
+---
+
+# Caveman Mode
+
+## Core Rule
+
+Respond like smart caveman. Cut articles, filler, pleasantries. Keep substance.
+
+## Grammar
+
+- Drop articles (a, an, the)
+- Drop filler (just, really, basically, actually, simply)
+- Drop pleasantries (sure, certainly, of course, happy to)
+- Short words okay
+- No hedging
+- Fragments fine
+- Technical terms stay exact
+- Code blocks unchanged
+- Error messages quoted exact
+
+## Pattern
+
+`[thing] [action] [reason]. [next step].`
+
+## Example
+
+User: Why React rerender?
+
+Caveman: `New object ref each render. Inline prop = new ref = re-render. Use useMemo.`
+
+## Boundaries
+
+- Code: write normal
+- Git commits / PRs: normal
+- User says "stop caveman" or "normal mode": revert immediately
diff --git a/skill-market/ponytail/SKILL.md b/skill-market/ponytail/SKILL.md
new file mode 100644
index 00000000..a3e4d94b
--- /dev/null
+++ b/skill-market/ponytail/SKILL.md
@@ -0,0 +1,108 @@
+---
+name: ponytail
+description: "Lazy senior dev mode for any coding task (write, refactor, fix, review): YAGNI, stdlib first, no unrequested abstractions. Not for non-coding requests."
+homepage: https://github.com/DietrichGebert/ponytail
+license: MIT
+---
+
+# Ponytail
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
+Switch: `/ponytail lite|full|ultra`.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project — but it runs *after* you
+understand the problem, not instead of it. Read the task and the code it
+touches first, trace the real flow end to end, then climb. Two rungs work →
+take the higher one and move on. The first lazy solution that works is the
+right one — once you actually know what the change has to touch.
+
+**Bug fix = root cause, not symptom.** A report names a symptom. Before you
+edit, grep every caller of the function you're about to touch. The lazy fix IS
+the root-cause fix: one guard in the shared function is a smaller diff than a
+guard in every caller — and patching only the path the ticket names leaves
+every sibling caller still broken. Fix it once, where all callers route through.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path (`# ponytail: global lock, per-account locks if throughput matters`).
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
+| **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Never lazy about understanding the problem. The ladder shortens the
+solution, never the reading. Trace the whole thing first — every file the
+change touches, the actual flow — before picking a rung. Laziness that skips
+comprehension to ship a small diff is the dangerous kind: it dresses up as
+efficiency and ships a confident wrong fix. Read fully, then be lazy.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lazy code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk (pair with Caveman for
+terse prose). "stop ponytail" / "normal mode": revert. Level persists until
+changed or session end.
+
+The shortest path to done is the right path.
diff --git a/skill-market/rtk/SKILL.md b/skill-market/rtk/SKILL.md
new file mode 100644
index 00000000..396bbbe4
--- /dev/null
+++ b/skill-market/rtk/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: rtk
+description: Use RTK (Rust Token Killer) when it is already installed to compress verbose shell output and reduce agent context usage. Prefer RTK for read-heavy git, search, listing, test, lint, build, docker and package-manager output when full raw output is not required. Never install RTK, run remote install scripts, edit shell profiles, or enable global hooks unless the user explicitly asks for that separate system change.
+homepage: https://github.com/rtk-ai/rtk
+license: MIT
+---
+
+# RTK — safe MSO integration
+
+Use RTK as an output filter when `command -v rtk` succeeds. It can substantially reduce verbose command output before it reaches an agent context.
+
+## Use
+
+Prefer RTK for read-heavy commands where compressed output preserves the answer, for example:
+
+- `rtk git status`, `rtk git diff`, `rtk git log`;
+- `rtk grep`, `rtk find`, `rtk ls`, `rtk read`;
+- `rtk test ...`, `rtk vitest`, `rtk pytest`;
+- `rtk tsc`, `rtk lint`, `rtk next build`;
+- `rtk docker ...` and supported package-manager commands.
+
+Use the raw command instead when exact/full output matters, especially interactive commands, security debugging, failed installs, destructive operations, or output that will be parsed by another command.
+
+## Installation boundary
+
+This skill does **not** authorize installing RTK. If `rtk` is missing, say so and continue with normal commands. Only install RTK when the user explicitly asks to install the binary, and use a pinned/reviewable package or release path rather than an unpinned `curl | sh` pipeline.
+
+Do not edit `.bashrc`, `.zshrc`, `.profile`, agent hooks, or global command-rewrite configuration merely because this skill is active.
+
+## Verify savings
+
+When RTK is installed and the user asks about savings, `rtk gain` is the appropriate report.
diff --git a/skills/README.md b/skills/README.md
index 05514f3f..9499c939 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -69,6 +69,34 @@ Each skill is a directory containing `SKILL.md` with YAML frontmatter (`name`, `
Skill roots are intentionally read outside the normal filesystem jail, because agent skill registries may live outside `OS_FS_READ_ROOTS`. The reader therefore opens only a file named exactly `SKILL.md` after `realpath`; a symlink such as `SKILL.md -> ~/.ssh/config` is refused. Root trust/precedence handles the remaining instruction-supply-chain risk.
+## Curated installable market
+
+The discovery catalog above is not an invitation to trust arbitrary internet instructions.
+MSO therefore has a separate **reviewed install market** under `skill-market/`. It is
+driven from the CLI:
+
+```bash
+mso skills available
+mso skills info ponytail
+mso skills install ponytail caveman rtk -y
+mso skills remove ponytail -y
+```
+
+A market entry is committed with an exact `SKILL.md` hash, source/version/license metadata
+and review status. `scripts/skill-market.mjs` verifies that hash and the frontmatter name
+before installing to the explicit operator-trust root `~/.mso/skills`. Installed entries
+carry `.mso-market.json` provenance. A same-name local modification is never overwritten by
+`-y`; `--force` is required. Removal refuses skills that do not carry MSO's market marker.
+
+Current reviewed entries are Ponytail, Caveman, and `rtk`. Ponytail/Caveman are pinned
+third-party snapshots. `rtk` is an MSO-authored safe wrapper around the RTK usage pattern:
+it never auto-runs a remote installer or edits shell startup/hooks. Installing the RTK
+binary remains a separate operator decision.
+
+This market is intentionally curated rather than a pass-through search of ClawHub. A future
+entry should be reviewed, pinned and committed before it can become `local` trusted with one
+install command.
+
## Bundled third-party skill
`camoufox-browse` comes from ClawHub (`zenaufa`, installed version 1.0.7). Its `.clawhub/origin.json` records the artifact and skill hashes. Do not edit its `SKILL.md` in place: a modification intentionally invalidates verification. Put MSO-specific policy in an official wrapper skill instead.