premanmcp 1.1.5 → 1.1.7

package/README.md

@@ -18,6 +18,65 @@ four-tool PreMan conversation protocol:
 
 PreMan can add private agent capabilities without publishing a new npm package.
 
+## Installing
+
+```bash
+npm install -g premanmcp   # once; this is what puts `preman` on your PATH
+preman install             # account, desktop app, integrations
+preman update              # later, to get the newest version
+```
+
+`preman install` walks the whole setup and installs the desktop app as part of
+it — no question asked, because an account with no app is the state people got
+stuck in. `--no-desktop` (or `PREMAN_NO_DESKTOP=1`) skips it, and it is skipped
+automatically off macOS, where there is no build. The git pre-push hook is the
+one thing still asked about, since it changes what happens on every push.
+
+`preman install --cursor` writes Cursor's MCP config and nothing else, which is
+what plain `install` used to mean; `install --api-key …` and
+`install --project --backend …` are unchanged.
+
+Nothing needs installing to try it: `npm exec -y premanmcp@latest -- <command>`
+runs any of these once, fetching the newest version each time.
+
+## The `preman` terminal session
+
+Installed globally, a bare `preman` opens an interactive session with the PreMan
+agent in your terminal — the same agent, workspace and conversation as the app,
+so anything started here is visible there.
+
+```bash
+preman                                  # open a session (signs you in if needed)
+preman "which endpoints broke today?"   # open one with the first message sent
+preman chat --continue                  # pick up the most recent conversation
+preman chat -p "list my endpoints"      # one turn, printed, then exit
+```
+
+Inside a session: `/help`, `/new`, `/conversations`, `/resume <id>`, `/app`,
+`/eval`, `/clear`, `/exit`. `/eval list` shows what your agent can be measured
+on, numbered; `/eval on 3 12` or `/eval on sycophancy` switches those on (a
+number, a `3-7` range, `all`, an id, or enough of one to be unambiguous), `/eval
+off` the same in reverse, and `/eval` runs what is on. `/eval defaults` reads
+what this project says about itself, picks a few behaviours that suit it, and
+switches those on — without an eval provider key on the account it falls back to
+a curated shortlist and says so. A finished run prints its results here: what
+was scored, what was flagged, what never ran, and why a failed run failed. The
+link underneath opens the PreMan desktop app when it is installed (a build older
+than 0.4.0 comes forward on whatever it was showing rather than on the run), and
+the run's dashboard URL is always printed with it.
+
+A session takes a screen of its own, the way `vim` does: nothing above it is
+scrollable, and leaving hands your shell back exactly as it was with one line
+saying how to resume. Ctrl+C stops the current turn (PreMan keeps working on it)
+or clears a half-typed line; pressed again within two seconds it leaves. Ctrl+D
+and `/exit` leave straight away. However the session ends -- including a closed
+tab or a `kill` -- the terminal is put back: scrolling region released, title
+cleared, cursor shown.
+
+Piped or redirected stdin with no arguments stays the stdio MCP server below, so
+an MCP host launching this package is unaffected. `preman start` asks for the
+server explicitly.
+
 ## Marketplace users
 
 Do not install this package. The PreMan Codex/ChatGPT plugin connects directly