moshcode 0.24.0

package/examples/templates/caddy-static/README.md

@@ -0,0 +1,90 @@
+# caddy-static
+
+A static site at a Moshpit name. No runtime, no database, no service to keep
+alive — Caddy and a directory of files.
+
+Reach for [`bun-caddy-sqlite`](../bun-caddy-sqlite) instead when you need
+something that runs.
+
+## The part that surprises people
+
+Three machines' worth of concerns, and they fail independently:
+
+| | needs the resolver? | what it does |
+|---|---|---|
+| the box serving the name | **no** | Caddy matches a `Host` header, nothing more |
+| the registry | — | holds the address the name points at |
+| every visitor | **yes** | `sudo moshcode dns enable`, or the name resolves to nothing |
+
+Nothing on the server ever resolves its own name. That is why there is no DNS
+software in this template.
+
+## Setup
+
+1. **Point the name at the box.** In the Pit, set `points at` to its public
+   IPv6 address — bare, no scheme, no brackets, no port:
+
+   ```sh
+   ip -6 addr show scope global | grep inet6
+   ```
+
+   Pick the globally routable one. An `fd..`/`fc..` address is unique-local
+   (Tailscale and friends live there) and the registry refuses it, because a
+   name pointed at one resolves somewhere only you can reach.
+
+2. **Put the files where the Caddyfile expects them.** `SITE_ROOT` defaults to
+   `/srv/moshpit-site`; `site/` here is a placeholder to replace.
+
+   ```sh
+   sudo mkdir -p /srv/moshpit-site
+   sudo cp -r site/. /srv/moshpit-site/
+   ```
+
+3. **Serve it.**
+
+   ```sh
+   export MOSHPIT_NAME=foo.whatever
+   export SITE_ROOT=/srv/moshpit-site
+   sudo cp Caddyfile /etc/caddy/Caddyfile
+   sudo systemctl enable --now caddy
+   sudo ufw allow 80/tcp
+   ```
+
+4. **Reach it,** on any machine that should see the name:
+
+   ```sh
+   sudo moshcode dns enable
+   sudo cp deploy/moshcode-dns.service /etc/systemd/system/   # survives reboot
+   sudo systemctl enable --now moshcode-dns
+   ```
+
+## Verifying, one layer at a time
+
+A failure at any layer looks identical in a browser, so do not start there.
+
+```sh
+# Server only — no DNS involved. Proves Caddy and the firewall.
+curl -6 -H "Host: foo.whatever" http://[YOUR:V6:ADDR]/
+
+# Resolver only. Proves the registry and the bridge.
+moshcode dns resolve foo.whatever
+
+# Both.
+curl -6 http://foo.whatever/
+```
+
+If the first works and the last does not, it is DNS. If the first fails, stop
+looking at DNS.
+
+## Known limits
+
+- **No HTTPS, ever.** No CA will issue for an ending outside the DNS root. That
+  rules out secure cookies, service workers, and WebCrypto in the browser. The
+  `http://` in the Caddyfile is what stops Caddy trying and failing.
+- **Only machines running the resolver can reach the name.** Not phones, not a
+  colleague who has not installed it, not webhooks.
+  `pit.moshcode.sh/n/foo.whatever` is the URL for people who installed nothing.
+- **One level deep.** `foo.whatever` works; `www.foo.whatever` does not.
+- **Port 80 only** on the resolver path. A DNS record carries an address and has
+  nowhere to put a port, so a target like `[addr]:8080` only works through the
+  `/n/` gateway.

package/examples/templates/caddy-static/deploy/moshcode-dns.service

@@ -0,0 +1,39 @@
+# The Moshpit resolver, kept running across reboots.
+#
+# `moshcode dns enable` sets up two halves: a systemd-resolved drop-in that
+# routes Moshpit endings at the bridge, and the bridge process itself. The
+# drop-in is a file and survives a reboot on its own. The process does not —
+# so after a restart the routing still points at a port with nothing behind it,
+# and every Moshpit name stops resolving with no obvious cause. This unit is
+# the missing half.
+#
+#   sudo cp deploy/moshcode-dns.service /etc/systemd/system/
+#   sudo systemctl enable --now moshcode-dns
+#
+# Install this on machines that need to REACH Moshpit names. A box that only
+# serves one does not need it — Caddy answers whatever Host header arrives and
+# never resolves its own name.
+
+[Unit]
+Description=Moshpit DNS bridge
+After=network-online.target
+Wants=network-online.target
+Before=systemd-resolved.service
+
+[Service]
+Type=simple
+# Port 5354 is unprivileged, so this does not need root. The trade-off is that
+# the parking responder cannot take port 80 and falls back to the public
+# parking address — which only affects names that point nowhere yet.
+ExecStart=/usr/bin/env moshcode dns start --port 5354
+Restart=always
+RestartSec=2
+
+DynamicUser=yes
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+
+[Install]
+WantedBy=multi-user.target

package/examples/templates/caddy-static/site/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<meta charset="utf-8">
+<title>served at a moshpit name</title>
+<h1>It resolved.</h1>
+<p>
+  Your resolver answered this name out of the Moshpit registry and connected
+  straight to the box holding it. Nothing proxied, nothing redirected.
+</p>
+<p>
+  Replace this file. It lives in whatever <code>SITE_ROOT</code> points at.
+</p>

package/examples/templates/caddy-static/template.json

@@ -0,0 +1,8 @@
+{
+  "name": "caddy-static",
+  "description": "Caddy serving a static site at a Moshpit name — no runtime, no service to keep alive",
+  "vars": {
+    "MOSHPIT_NAME": "the registered name to serve, e.g. foo.whatever",
+    "SITE_ROOT": "directory of files to serve (default /srv/moshpit-site)"
+  }
+}

package/install.sh

@@ -0,0 +1,194 @@
+#!/bin/sh
+# moshcode — one-line installer 🤘
+#
+# Usage:
+#   curl -fsSL https://moshcoding.com/install.sh | sh
+#   curl -fsSL https://moshcoding.com/install.sh | sh -s -- update      (alias: upgrade)
+#   curl -fsSL https://moshcoding.com/install.sh | sh -s -- remove      (alias: uninstall)
+#
+# (also works straight from GitHub:)
+#   curl -fsSL https://raw.githubusercontent.com/moshcoder/moshcode/main/install.sh | sh
+#
+# What it does — dead simple, no build step:
+#   1. Checks for Node.js 18+ (moshcode is zero-dependency ESM — needs a node).
+#   2. Downloads the latest release tarball of moshcoder/moshcode from GitHub
+#      (falls back to the main branch if no release is published yet).
+#   3. Unpacks it to $MOSHCODE_HOME (default: $HOME/.moshcode).
+#   4. Drops a `moshcode` wrapper at $MOSHCODE_BIN (default: $HOME/.local/bin)
+#      that just exec's `node $MOSHCODE_HOME/bin/moshcode.mjs "$@"`.
+#   5. Ensures that bin dir is on your PATH.
+#
+# Env overrides:
+#   MOSHCODE_HOME=/path      install dir      (default: $HOME/.moshcode)
+#   MOSHCODE_BIN=/path/dir   wrapper bin dir  (default: $HOME/.local/bin)
+#   MOSHCODE_REF=vX.Y.Z      pin a tag/branch (default: latest release, else main)
+#   MOSHCODE_ALLOW_ROOT=1    install as root anyway (see below)
+#
+# Do not install this with sudo. moshcode is a user-level CLI, and every path
+# here is derived from $HOME — under sudo that is /root, so the payload and the
+# wrapper land in root's home where your own user cannot read them. Nothing
+# fails at install time; it surfaces later as "permission denied" on a binary
+# that looks installed. The installer refuses that case and tells you how.
+#
+# Re-running updates an existing install in place.
+
+set -eu
+
+REPO="moshcoder/moshcode"
+INSTALL_URL="https://moshcoding.com/install.sh"
+MOSHCODE_HOME="${MOSHCODE_HOME:-$HOME/.moshcode}"
+MOSHCODE_BIN="${MOSHCODE_BIN:-$HOME/.local/bin}"
+WRAPPER="$MOSHCODE_BIN/moshcode"
+SCRIPT_WRAPPER="$MOSHCODE_BIN/moshscript"
+
+# ---- pretty output (acid-lime, matching the CLI) --------------------------
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+    ACID=$(printf '\033[38;2;158;240;26m'); ASH=$(printf '\033[38;2;139;147;138m')
+    RED=$(printf '\033[31m'); BOLD=$(printf '\033[1m'); RESET=$(printf '\033[0m')
+else
+    ACID=''; ASH=''; RED=''; BOLD=''; RESET=''
+fi
+info() { printf '%s·%s %s\n' "$ASH" "$RESET" "$*"; }
+ok()   { printf '%s✓%s %s\n' "$ACID" "$RESET" "$*"; }
+fail() { printf '%s✗%s %s\n' "$RED" "$RESET" "$*" >&2; exit 1; }
+
+# ---- prerequisites --------------------------------------------------------
+need() { command -v "$1" >/dev/null 2>&1 || fail "$1 is required but not found."; }
+
+# Installing under sudo silently installs for the wrong user. Every path here
+# comes from $HOME, which sudo sets to /root, so the payload and wrappers land
+# in a directory mode 0700 root — invisible to the user who ran the command.
+# The install reports success and only breaks later, at first use.
+#
+# A bare root shell (containers, CI images, root-only boxes) has no SUDO_USER
+# and is a legitimate way to install, so only the sudo-from-a-real-user case is
+# refused, and MOSHCODE_ALLOW_ROOT overrides even that.
+check_not_sudo() {
+    [ "$(id -u)" = "0" ] || return 0
+    [ -n "${SUDO_USER:-}" ] || return 0
+    if [ -n "${MOSHCODE_ALLOW_ROOT:-}" ]; then
+        info "MOSHCODE_ALLOW_ROOT set — installing as root into $MOSHCODE_HOME"
+        return 0
+    fi
+    fail "don't install moshcode with sudo.
+
+  Every path is based on \$HOME, which sudo has set to $HOME, so this would
+  install for root and leave $SUDO_USER unable to run it.
+
+  Run it as yourself instead:
+      curl -fsSL $INSTALL_URL | sh
+
+  If you really do want it system-wide, choose the paths explicitly:
+      sudo MOSHCODE_ALLOW_ROOT=1 MOSHCODE_HOME=/opt/moshcode \\
+           MOSHCODE_BIN=/usr/local/bin sh -c 'curl -fsSL $INSTALL_URL | sh'"
+}
+
+check_node() {
+    command -v node >/dev/null 2>&1 || fail \
+        "Node.js 18+ is required. Install it (https://nodejs.org) and re-run."
+    _major="$(node -v 2>/dev/null | sed 's/^v//' | cut -d. -f1)"
+    [ "${_major:-0}" -ge 18 ] || fail "Node.js 18+ required, found $(node -v)."
+    ok "Node.js $(node -v)"
+    unset _major
+}
+
+# Resolve the download URL for the latest release tag, or fall back to main.
+resolve_ref() {
+    if [ -n "${MOSHCODE_REF:-}" ]; then
+        echo "$MOSHCODE_REF"; return 0
+    fi
+    # Ask GitHub for the latest release tag (no auth needed for public repos).
+    _tag="$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null \
+        | grep '"tag_name"' | head -1 | sed 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/')"
+    if [ -n "$_tag" ]; then echo "$_tag"; else echo "main"; fi
+    unset _tag
+}
+
+fetch_and_unpack() {
+    _ref="$1"
+    _url="https://codeload.github.com/$REPO/tar.gz/$_ref"
+    info "downloading moshcode@$_ref"
+    _tmp="$(mktemp -d 2>/dev/null || mktemp -d -t moshcode)"
+    if ! curl -fsSL "$_url" | tar -xz -C "$_tmp" 2>/dev/null; then
+        rm -rf "$_tmp"; fail "download failed ($_url) — check the ref/network."
+    fi
+    # Tarball extracts to a single top-level dir (e.g. moshcode-main/).
+    _src="$(find "$_tmp" -maxdepth 1 -type d -name 'moshcode-*' | head -1)"
+    [ -n "$_src" ] && [ -f "$_src/bin/moshcode.mjs" ] || { rm -rf "$_tmp"; fail "unexpected tarball layout."; }
+    rm -rf "$MOSHCODE_HOME"
+    mkdir -p "$(dirname "$MOSHCODE_HOME")"
+    mv "$_src" "$MOSHCODE_HOME"
+    rm -rf "$_tmp"
+    chmod +x "$MOSHCODE_HOME/bin/moshcode.mjs" 2>/dev/null || true
+    ok "installed to $MOSHCODE_HOME"
+    unset _ref _url _tmp _src
+}
+
+write_wrapper() {
+    mkdir -p "$MOSHCODE_BIN"
+    cat > "$WRAPPER" <<WRAP_EOF
+#!/bin/sh
+# moshcode wrapper — installed by $INSTALL_URL. Re-run the installer to update.
+exec node "$MOSHCODE_HOME/bin/moshcode.mjs" "\$@"
+WRAP_EOF
+    chmod +x "$WRAPPER"
+    ok "wrapper at $WRAPPER"
+
+    # moshscript — thin alias for `moshcode run`, so .mosh files can use
+    # #!/usr/bin/env moshscript as a shebang and run like shell scripts.
+    cat > "$SCRIPT_WRAPPER" <<SCRIPT_EOF
+#!/bin/sh
+# moshscript wrapper — installed by $INSTALL_URL. Re-run the installer to update.
+exec node "$MOSHCODE_HOME/bin/moshcode.mjs" run "\$@"
+SCRIPT_EOF
+    chmod +x "$SCRIPT_WRAPPER"
+    ok "wrapper at $SCRIPT_WRAPPER"
+}
+
+ensure_path() {
+    case ":$PATH:" in *":$MOSHCODE_BIN:"*) return 0 ;; esac
+    for rc in "$HOME/.bashrc" "$HOME/.zshrc" "$HOME/.profile"; do
+        [ -f "$rc" ] || continue
+        grep -q "$MOSHCODE_BIN" "$rc" 2>/dev/null && continue
+        printf '\n# Added by moshcode installer\nexport PATH="%s:$PATH"\n' "$MOSHCODE_BIN" >> "$rc"
+    done
+    info "add $MOSHCODE_BIN to PATH in this shell:  export PATH=\"$MOSHCODE_BIN:\$PATH\""
+}
+
+# ---- commands -------------------------------------------------------------
+run_install() {
+    printf '\n%smoshcode installer%s %s— code hard, mosh harder 🤘%s\n\n' "$BOLD" "$RESET" "$ASH" "$RESET"
+    check_not_sudo
+    need curl; need tar
+    check_node
+    _ref="$(resolve_ref)"
+    fetch_and_unpack "$_ref"
+    write_wrapper
+    ensure_path
+    printf '\n%sdone.%s run:\n' "$ACID" "$RESET"
+    printf '  moshcode                 # open the TUI shell\n'
+    printf '  moshcode start claude    # raw engine session (use agents for autonomous)\n'
+    printf '  moshcode prd "your idea" # plan with a numbered OpenPRD\n'
+    printf '  moshcode tools           # install/run UGig and CoinPay CLIs\n'
+    printf '  moshcode help\n\n'
+    unset _ref
+}
+
+run_remove() {
+    info "removing moshcode"
+    rm -f "$WRAPPER" 2>/dev/null || true
+    rm -f "$SCRIPT_WRAPPER" 2>/dev/null || true
+    rm -rf "$MOSHCODE_HOME" 2>/dev/null || true
+    ok "removed $WRAPPER, $SCRIPT_WRAPPER, and $MOSHCODE_HOME. 🤘"
+}
+
+CMD="${1:-install}"
+if [ $# -gt 0 ]; then shift; fi
+case "$CMD" in
+    install)            run_install ;;
+    update|upgrade)     run_install ;;   # re-fetch latest, same path
+    remove|uninstall)   run_remove ;;
+    -h|--help|help)
+        sed -n '2,33p' "$0" 2>/dev/null || printf 'moshcode installer — install | update | remove\n' ;;
+    *) fail "unknown command: $CMD (try: install | update | remove)" ;;
+esac

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "moshcode",
+  "version": "0.24.0",
+  "type": "module",
+  "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
+  "bin": {
+    "moshcode": "./bin/moshcode.mjs",
+    "moshscript": "./bin/moshscript.mjs"
+  },
+  "scripts": {
+    "start": "node bin/moshcode.mjs",
+    "demo": "node bin/moshcode.mjs run examples/alive.mosh",
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "prd",
+    "install.sh",
+    "README.md"
+  ],
+  "license": "MIT",
+  "packageManager": "pnpm@10.32.1",
+  "devDependencies": {
+    "@moshcoder/moshpit-dns": "^0.5.0"
+  }
+}

package/prd/0000-template.md

@@ -0,0 +1,49 @@
+---
+openprd: "0.2"
+id: "0000"
+title: "Short imperative title — start with a verb if possible"
+status: Draft
+authors:
+  - you@example.com
+created: 2026-01-01
+updated: 2026-01-01
+repo:
+discussion:
+implementation:
+tags:
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+The user/business problem, and why it matters now.
+
+## Goals
+
+What success looks like, as outcomes (not features).
+
+## Non-Goals
+
+Explicitly out of scope, to bound the work.
+
+## Users
+
+Who this is for; personas or segments.
+
+## Requirements
+
+- R1 [P0] First required capability.
+- R2 [P1] Next capability.
+
+## UX Notes
+
+Flows, states, and constraints that shape the experience.
+
+## Success Metrics
+
+How the goals will be measured.
+
+## Risks & Open Questions
+
+- Known risk or decision still owed.

package/prd/0001-wrap-ugig-and-coinpay-clis.md

@@ -0,0 +1,121 @@
+---
+openprd: "0.2"
+id: "0001"
+title: Wrap the UGig and CoinPay CLIs
+status: Accepted
+authors:
+  - anthony@chovy.com
+created: 2026-07-13
+updated: 2026-07-13
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation:
+tags:
+  - cli
+  - ugig
+  - coinpay
+  - orchestration
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+MoshCode already installs and delegates to coding engines, but users and coding
+agents must leave its workflow to discover paid work through UGig or operate the
+CoinPay payment rail. Both products already ship broad native CLIs. Rebuilding
+their APIs in MoshCode would duplicate authentication, command semantics, and
+release cadence; omitting them leaves a gap between finding work, doing it, and
+getting paid.
+
+## Goals
+
+- Make the native `ugig` and `coinpay` CLIs installable and discoverable through
+  MoshCode.
+- Provide transparent top-level and TUI delegation without changing native CLI
+  behavior.
+- Include installed external tools in MoshCode's existing upgrade workflow.
+- Keep ownership clear: UGig owns marketplace state, CoinPay owns payment state,
+  and MoshCode only conducts the installed CLIs.
+
+## Non-Goals
+
+- Reimplementing UGig or CoinPay API clients or command trees in MoshCode.
+- Adding composed `gigs`, invoice, escrow, or settlement workflows in this
+  release.
+- Adding irreversible payment operations to moshscript.
+- Normalizing or parsing either tool's human-readable or JSON output.
+- Managing UGig or CoinPay credentials on MoshCode's behalf.
+
+## Users
+
+- Developers using MoshCode who want to find and manage UGig work from the same
+  terminal workflow.
+- Coding agents that need machine-readable UGig output or direct CoinPay access.
+- Operators who want one installation and upgrade surface for their coding
+  engines and adjacent workflow tools.
+
+## Requirements
+
+- R1 [P0] MoshCode MUST define UGig and CoinPay in a `TOOLS` registry separate
+  from the coding-engine registry. Each entry MUST declare its executable and
+  official package installation/upgrade command.
+- R2 [P0] `moshcode tools` MUST list both tools and report whether each native
+  executable is on `PATH`.
+- R3 [P0] `moshcode install ugig` and `moshcode install coinpay` MUST install the
+  official npm packages; existing engine installation behavior MUST remain
+  compatible.
+- R4 [P0] `moshcode ugig [args…]` and `moshcode coinpay [args…]` MUST pass
+  arguments, stdin, stdout, stderr, the working directory, and environment
+  through unchanged and MUST propagate the native process exit result.
+- R5 [P0] The interactive shell MUST accept `/ugig [args…]` and
+  `/coinpay [args…]`, hand terminal control to the native CLI, and return to the
+  MoshCode prompt when it exits.
+- R6 [P0] `moshcode upgrade` MUST update installed tools as well as installed
+  engines. `upgrade tools`, `upgrade ugig`, and `upgrade coinpay` MUST be valid
+  narrower targets.
+- R7 [P1] Missing executables and unknown install/upgrade targets MUST produce
+  actionable errors that identify the correct MoshCode command.
+- R8 [P1] Help text and the README MUST document installation, status,
+  passthrough, authentication ownership, and upgrade behavior.
+- R9 [P1] Automated tests MUST cover tool resolution and transparent
+  passthrough, including arguments, standard streams, and non-zero exit codes.
+
+## UX Notes
+
+```sh
+moshcode tools
+moshcode install ugig
+moshcode install coinpay
+
+moshcode ugig --json gigs list
+moshcode coinpay wallet balance
+
+moshcode upgrade tools
+```
+
+`moshcode tools` distinguishes adjacent workflow tools from `/agents` and
+`moshcode engines`. The wrappers do not insert banners or status messages into
+native stdout because that would corrupt JSON pipelines. Native authentication
+continues to use each tool's config files and environment variables.
+
+CoinPay currently requires Node.js 20 or newer while MoshCode itself supports
+Node.js 18. Its npm installer remains the authority for enforcing that package
+requirement; MoshCode documents it rather than changing its own runtime floor.
+
+## Success Metrics
+
+- All P0 requirements have automated coverage or direct CLI verification.
+- Native `ugig` and `coinpay` help/output can be invoked through MoshCode without
+  MoshCode text appearing on stdout.
+- A native non-zero exit code is observed unchanged by a calling shell or agent.
+- Existing MoshCode tests and coding-engine commands continue to pass.
+
+## Risks & Open Questions
+
+- CoinPay's machine-readable output is not yet uniform across commands. MoshCode
+  will preserve it verbatim; CoinPay should standardize JSON-only stdout and
+  diagnostics on stderr before agents depend on every command in pipelines.
+- Composed gig-to-invoice or escrow flows may be valuable later, but should be
+  based on observed usage and require explicit confirmation for irreversible
+  payment actions.

package/prd/0002-separate-agent-and-raw-engine-launches.md

@@ -0,0 +1,113 @@
+---
+openprd: "0.2"
+id: "0002"
+title: Separate autonomous agent and raw engine launches
+status: Accepted
+authors:
+  - anthony@chovy.com
+created: 2026-07-13
+updated: 2026-07-13
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation:
+tags:
+  - cli
+  - agents
+  - permissions
+  - orchestration
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+MoshCode currently treats `/agents <engine>` as an ordinary native CLI launch.
+That name implies an autonomous coding session, but the underlying engines still
+pause for their normal permission or approval prompts. At the same time, users
+need an explicit way to start the unmodified native CLI when they want its normal
+safety model or need to supply their own flags.
+
+## Goals
+
+- Make `/agents <engine>` a predictable autonomous launch across every supported
+  coding engine.
+- Provide `/start <engine>` as an explicit raw passthrough that injects no flags.
+- Preserve the existing bare `moshcode <engine>` raw behavior for compatibility.
+- Make the dangerous nature of autonomous mode visible before handoff.
+
+## Non-Goals
+
+- Bypassing administrator policies that disable an engine's autonomous mode.
+- Claiming that every engine provides identical sandbox or permission semantics.
+- Applying autonomous flags to UGig, CoinPay, installers, upgrades, or moshscript.
+- Parsing or rewriting user-supplied native engine arguments.
+
+## Users
+
+- Developers who intentionally want uninterrupted agent execution in an
+  isolated or otherwise trusted workspace.
+- Developers who want a memorable raw-start command for normal interactive use.
+- Scripts that need the same distinction outside the MoshCode TUI.
+
+## Requirements
+
+- R1 [P0] Every coding-engine registry entry MUST declare the engine's current
+  autonomous or auto-approval arguments.
+- R2 [P0] The autonomous mappings MUST be Claude
+  `--dangerously-skip-permissions`, Codex
+  `--dangerously-bypass-approvals-and-sandbox`, Gemini
+  `--approval-mode=yolo`, Aider `--yes-always`, and OpenCode `--auto`.
+- R3 [P0] `/agents <engine> [args…]` MUST prepend the registered autonomous
+  arguments and then preserve all user-supplied arguments.
+- R4 [P0] `/start <engine> [args…]` MUST launch the engine with only the
+  user-supplied arguments.
+- R5 [P0] `moshcode agents <engine> [args…]` and
+  `moshcode start <engine> [args…]` MUST provide the equivalent non-TUI paths.
+- R6 [P0] Bare `moshcode <engine> [args…]` and bare engine names in the TUI MUST
+  remain raw passthroughs for backward compatibility.
+- R7 [P1] Agent-mode launches MUST show a warning that permission or approval
+  protections are being bypassed or auto-approved.
+- R8 [P1] `/agents` and `moshcode agents` with no engine MUST continue listing
+  engines and their install status.
+- R9 [P1] Automated tests MUST verify the registered mappings, autonomous
+  argument order, and raw-start behavior for every engine.
+
+## UX Notes
+
+```sh
+# Autonomous: MoshCode injects the engine-specific bypass/auto-approve flag.
+moshcode agents claude
+moshcode agents codex --model gpt-5
+
+# Raw: MoshCode injects nothing.
+moshcode start claude
+moshcode start codex --sandbox workspace-write
+
+# Backward-compatible raw shorthand.
+moshcode claude
+```
+
+TUI equivalents are `/agents claude`, `/start claude`, and bare `claude`.
+`/agents` remains the status list when no engine name follows it.
+
+The mappings are intentionally not described as identical. Claude and Codex
+offer explicit full-bypass flags. Gemini and Aider auto-approve confirmations.
+OpenCode's `--auto` approves requests that are not explicitly denied, so deny
+rules remain effective.
+
+## Success Metrics
+
+- Each engine receives exactly its registered autonomous arguments through the
+  agent-mode path.
+- Raw starts receive no MoshCode-injected engine arguments.
+- Existing engine aliases, environment scrubbing, stdio, cwd, and exit behavior
+  remain intact.
+- The full MoshCode test suite passes.
+
+## Risks & Open Questions
+
+- Full-bypass modes can execute destructive or prompt-injected actions. Users
+  should reserve `/agents` for isolated containers, VMs, or trusted workspaces.
+- Engine flags can change between releases. Their own installers and help output
+  remain authoritative, and the registry mappings need maintenance when upstream
+  CLIs rename a mode.