@plurnk/plurnk 0.75.0 → 0.76.1

package/man/plurnk.1

@@ -0,0 +1,153 @@
+.TH PLURNK 1 "" "plurnk 0.75.0" "User Commands"
+.SH NAME
+plurnk \- terminal client for the plurnk\-service agentic daemon
+.SH SYNOPSIS
+.nf
+plurnk [--json] [--workspace <name>] [--worker <name>] [--model <selector>] [--reasoning <policy>] [prompt...]
+       <piped stdin> | plurnk [options] [prompt...]
+       plurnk models [search...] [--provider <name>] [--all] [--offset <n>] [--limit <n>] [--json]
+       plurnk workspace list [--json]
+       plurnk workspace workers <name> [--json]
+       plurnk workspace rename <name> <newname> [--json]
+       plurnk log read --workspace <name> [--worker <name>]
+                       [--loop <id>] [--turn <id>] [--since <id>] [--limit <n>] [--json]
+       plurnk read <loop>/<turn>/<seq> --workspace <name> [--worker <name>] [--json]
+       plurnk reasoning [policy] --workspace <name> [--worker <name>] [--json]
+       plurnk mcp [add <alias> <target> [options.json] | enable <alias> [options.json]
+                   | disable|remove <alias> | oauth <alias> <callback-url>]
+.fi
+.SH DESCRIPTION
+Connects to the plurnk-service daemon. Run a single prompt one-shot
+(positional args, piped stdin, or both — positionals come first, stdin
+is appended after a blank line). With no positionals and a TTY stdin,
+enters the interactive REPL. Read-only subcommands (models / workspace list /
+log read / read <coord>) inspect daemon state without running a loop.
+.SH OPTIONS
+.nf
+  -h, --help              print this message and exit
+  -v, --version           print executable provenance and exit
+      --json              json OUTPUT MODE: one complete structured document on
+                          stdout (the whole client-observed record — turns/ops,
+                          notices, the answer at .response, usage), stderr
+                          silent, Problems emitted under "problem". Drill into one
+                          op's content with: plurnk read <coord> --json. CLI only.
+      --workspace <name>    resume the named workspace, or create it under that name
+                          if none exists (attach-or-create). Without it, a fresh
+                          auto-named workspace is created. Overrides PLURNK_CLIENT_WORKSPACE.
+      --worker <name>        resume (or create) the named worker within the workspace.
+                          Requires --workspace. Overrides PLURNK_CLIENT_WORKER.
+      --model <selector>  persistently select the conversation worker's model
+                          before the first loop (worker.model.set). A selector is
+                          a declared alias or exact provider/model route. Without
+                          this, the worker's durable model or the daemon's
+                          boot-time default runs.
+      --reasoning <policy> persistently select the conversation worker's reasoning
+                          policy before the first loop. The daemon validates the
+                          policy against the selected parent and child models.
+      --project-root <p>  absolute path. Sent on workspace.create only; ignored
+                          on --workspace attach (daemon preserves stored value).
+                          Default: cwd. Empty string = headless. Overrides
+                          PLURNK_CLIENT_PROJECT_ROOT.
+      --yolo              auto-accept every proposal locally without prompting.
+                          Overrides PLURNK_CLIENT_YOLO.
+      --auto              keep proposal authority inside the loop; proposals
+                          resolve automatically without a client review round-trip.
+      --flags <json>      raw LoopFlags JSON passthrough on every loop.run
+                          (e.g. '{"auto":true}' for unattended
+                          benchmark/automation runs).
+      --request_user_input  let the model ask you through the question tool when it
+                          needs a decision (multiple choice with a free-response
+                          escape, or an open question). Off by default for the
+                          one-shot CLI; on by default for the TUI. Overrides
+                          PLURNK_REQUEST_USER_INPUT.
+      --env-file <p>      load env from <p> (errors if missing). Repeatable.
+      --env-file-if-exists <p>  same, but silently skip a missing file. Repeatable.
+      --max-turns <n>     per-loop turn cap (daemon default PLURNK_MAX_TURNS).
+      --timeout <s>       CLI mode: cancel the loop (loop.cancel) after <s>
+                          seconds; exits 3 with "timedOut":true in the result.
+      --pick <glob>       membership: track file(s) in manifest (the sole
+                          source when headless). Repeatable.
+      --hide <glob>       membership: block file(s) from manifest. Repeatable.
+      --view <glob>       membership: track file(s) in manifest (read-only). Repeatable.
+      --files-items <n>   workspace-open preview of the TRACKED-FILE list
+                          (## FIND0 (file:///**)): -1 full / 0 off / N first-N. Memory
+                          (known/unknown/worker/plurnk) always foists full. Create-time.
+      --md <name=path>    pin a markdown doc into the workspace (read at turn 0);
+                          merges with operator PLURNK_MD_*. Repeatable. Create-time.
+      --max-commands <n>  ceiling on ops per emission for the workspace (min with the
+                          daemon's PLURNK_MAX_COMMANDS — can only tighten). Create-time.
+      --no-git            deny git membership + working-tree status for the workspace (never
+                          re-enables past the operator lockout). Create-time.
+      --loop <id>         (log read) filter to a single loop id
+      --turn <id>         (log read) filter to a single turn id
+      --since <id>        (log read) return entries with id > <id>
+      --limit <n>         (log read) max entries to return (default 100)
+      --provider <name>   (models) restrict the catalog to one provider
+      --all               (models) include unconfigured models with readiness causes
+      --offset <n>        (models) catalog page offset (default 0)
+.fi
+.SH SUBCOMMANDS
+.nf
+  models [search...]      list the bounded daemon model catalog (models.list)
+  workspace list            list workspaces on the daemon (workspace.list)
+  workspace workers <name>  list workers in the named workspace (workspace.workers)
+  workspace rename <a> <b>  rename workspace <a> to <b> (workspace.rename — a workspace's
+                          name is a mutable handle; workers are immutable)
+  log read --workspace ...  read log entries from the named workspace's worker
+  reasoning [policy]      inspect or set a worker's durable reasoning policy
+  mcp ...                 list and manage MCP servers for --workspace
+  script <file.plk>       run a .plk file: feed its DSL to op.parse, render the
+                          trace, exit by worst op status. Honors --workspace/--yolo
+                          /--project-root + membership flags. The daemon owns the
+                          grammar; the client just feeds the file.
+.fi
+.SH ENVIRONMENT
+.nf
+env (cascade, low → high: packaged .env.defaults < $XDG_CONFIG_HOME/plurnk/.env
+     < ./.env < repeated --env-file flags (last wins) < shell):
+                        Works with no config at all.
+  PLURNK_CLIENT_WORKSPACE        resume/create a workspace by name. UNSET = the daemon
+                        mints a fresh, uniquely-named workspace per invocation.
+  PLURNK_CLIENT_WORKER            resume (or create) a named worker within that workspace
+  PLURNK_CLIENT_PROJECT_ROOT   absolute path passed to workspace.create as the workspace's
+                        project_root (workspace for file ops). Default: cwd.
+                        Empty string = headless (no project_root, file ops 400).
+  PLURNK_CLIENT_YOLO           when truthy, auto-accept every proposal without prompting.
+  PLURNK_AUTO                  when truthy, keep proposal authority inside the loop.
+                        Client-side only — proposals still go through the wire.
+  PLURNK_CLIENT_JSON           when truthy, same as --json for one-shot runs.
+  PLURNK_REQUEST_USER_INPUT  when truthy, the conversation worker may ask you
+                        through the question tool. TUI/nvim default on; the
+                        one-shot CLI defaults off. --request_user_input overrides.
+  PLURNK_AGUI_URL       plurnk-agui bridge URL (e.g. http://127.0.0.1:8787). When
+                        set, a one-shot (text AND --json) runs THROUGH the bridge
+                        instead of raw daemon WS (the exclusive-portal path).
+                        PLURNK_AGUI_TOKEN is the bearer if the bridge requires one.
+                        Scripts + subcommands stay on the daemon.
+  PLURNK_EXECS_ONLY /   per-workspace exec-runtime policy, sent to the daemon at
+  PLURNK_EXECS_<tag>    workspace.create (ONLY=a,b allowlist; <tag>=0 kills one).
+                        Plugin configuration with longer underscore suffixes is
+                        never forwarded. Subtractive only — the
+                        daemon intersects with its ceiling; the client can narrow,
+                        never re-enable. Shares the daemon's grammar; a workspace's
+                        .env carries its own.
+  PLURNK_MCP_*          raw server declarations accompany MCP list and enable.
+                        Service controls do not. The daemon owns parsing,
+                        activation, persistence, and credential expansion.
+.fi
+.SH EXIT STATUS
+.TP
+.B 0
+The loop concluded successfully (or the subcommand completed).
+.TP
+.B 3
+The loop failed, timed out (\-\-timeout), or a script's worst op status was an error.
+.TP
+.B 143
+Terminated by SIGTERM after emitting the partial record.
+.SH FILES
+.TP
+.I $XDG_CONFIG_HOME/plurnk/.env
+Operator configuration (model aliases, provider credentials, client defaults).
+.SH SEE ALSO
+plurnk\-service(1), and the repository SPEC.md for the client contract.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk",
-    "version": "0.75.0",
+    "version": "0.76.1",
     "description": "Plurnk client app — CLI/TUI consuming plurnk-service. Type prompts at a terminal, drive real model loops through the protocol.",
     "type": "module",
     "license": "MIT",
@@ -16,8 +16,11 @@
     "files": [
         "bin/plurnk.js",
         "dist/**/*",
+        "conformance/agui-client.json",
         ".env.defaults",
-        "README.md"
+        "README.md",
+        "man/",
+        "completions/"
     ],
     "scripts": {
         "test:lint": "tsc --noEmit",
@@ -41,7 +44,8 @@
         "build:local:uninstall": "node scripts/install-sandbox.mjs uninstall",
         "test:installation": "node scripts/test-installation.mjs",
         "test:composition": "node scripts/test-composition.mjs",
-        "release:publish": "node scripts/release-publish.mjs"
+        "release:publish": "node scripts/release-publish.mjs",
+        "build:posix": "node --conditions=plurnk-dev scripts/generate-posix.mjs"
     },
     "devDependencies": {
         "@types/node": "^26.1.1",
@@ -52,9 +56,10 @@
     "dependencies": {
         "@ag-ui/client": "^0.0.58",
         "@ag-ui/core": "^0.0.58",
-        "@plurnk/plurnk-contracts": "^1.8.0"
+        "@plurnk/plurnk-contracts": "^1.9.1"
     },
     "plurnk": {
-        "builtAgainst": "1.8.0"
-    }
+        "builtAgainst": "1.9.1"
+    },
+    "man": "./man/plurnk.1"
 }