@supernala/cli 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @supernala/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect your own computer to a Supernala workspace as a **Machine**, so your Agents can read files,
+run commands and work with your coding agents (Claude Code, Codex, OpenCode, pi) there, and so you
+can run coding agent Sessions from Supernala.
+
+Requires Node.js 22.4 or later.
+
+## Connect
+
+```sh
+supernala connect        # pairs this computer; approve the code in Supernala
+supernala daemon         # keeps the connection open while you want Agents to reach it
+```
+
+The Machine starts **Read-only** for all Agents. Change its Agent access and mode in Supernala under
+Machines → Computers. Full access lets the chosen Agents run any command as you on this computer.
+
+## Commands
+
+| Command                                | What it does                                                   |
+| -------------------------------------- | -------------------------------------------------------------- |
+| `supernala connect`                    | Pair this computer with a workspace                            |
+| `supernala daemon`                     | Keep the connection open; runs commands and Sessions           |
+| `supernala daemon --background`        | As `daemon`, but also runs unpaired or paused (the app's mode) |
+| `supernala status [--json]`            | Show the connection; `--json` asks the running daemon          |
+| `supernala stop`                       | Stop a running daemon                                          |
+| `supernala disconnect`                 | Forget this computer's credential                              |
+| `supernala doctor`                     | Check the setup and installed coding agents                    |
+| `supernala files ls / pull / push`     | Move files between this computer and Workspace Files           |
+| `supernala send <paths…> [-m note]`    | Hand files back to the Agent that started this command or turn |
+| `supernala skills install [--agent …]` | Teach your coding agents to work with Supernala                |
+
+## Security
+
+- The Machine holds an Ed25519 key in `~/.supernala` (mode 0600); your Supernala sign-in never
+  leaves the browser.
+- The connection is outbound only. The daemon's only listener is its local control socket,
+  `~/.supernala/control.sock` (a named pipe on Windows), which the Supernala menu bar app and
+  `supernala status --json` use. It is a Unix socket in the owner-only config directory with mode
+  0600, so only your user can reach it; it never accepts network connections.
+- Workspace Secrets are never sent to a Machine.
+- Session transcripts are stored in your workspace and count toward its storage; delete them in
+  Machines, or turn on auto-delete. From version 0.2.0 they include the thinking a coding agent
+  shows (encrypted or redacted thinking is never sent), and imported sessions bring theirs along.
+  OpenCode turns run with `--thinking` so OpenCode reports it.
+
+## The menu bar app and the control socket
+
+The daemon serves JSON lines on its control socket, typed in `@supernala/protocol/machine-control`:
+`status`, `pair.start` (returns the code, then `paired`, `denied` or `expired`), `connect`,
+`disconnect` (pauses without unpairing, kept across restarts), `unpair`, `sessions.list`,
+`agents.list` and `events` (status changes). The Supernala menu bar app
+(`apps/machine-desktop`) starts `supernala daemon --background` and talks only to this socket.
+Only one daemon runs per config directory: a second one exits, and `supernala connect` hands a
+fresh pairing to the daemon already running. `SUPERNALA_HOME` moves the config directory and the
+socket.