@productlobster/plob 0.1.7 → 0.1.8

package/README.md

@@ -31,13 +31,13 @@ plob --help
 | `plob build --target <runId>` | Build the prototype and requirements from a finished launch run. |
 | `plob run-status <runId> [--since <cursor>]` | Read a run's status. |
 | `plob run-output <runId> [--stage <name>]` | Read structured run output. |
-| `plob checkpoint-resolve <runId> <optionId>` | Resolve a pending decision in a run. |
+| `plob checkpoint-resolve <runId> <optionId> [--reason <text>]` | Answer a pending decision in a run with the option the person chose. From plob 0.1.8, `--reason` sends an optional one-line reason, shown to the person when the pick is recorded as a suggestion; it is sent only when given. |
 | `plob run-cancel <runId>` | Cancel a run. |
 | `plob run-replay <runId> [--from-stage <name>]` | Replay a run, optionally from a given stage. |
 | `plob prototype-list [--cursor <cursor>]` | List prototypes in the workspace. |
 | `plob prototype-pack --prototype-id <id> [--out <dir>]` | Fetch a prototype ZIP reference (extracts when `--out` is set). |
 | `plob document-list [--type <type>] [--run <runId>] [--latest] [--since <iso>] [--limit <n>] [--cursor <cursor>]` | List workspace documents. `--latest` applies only with `--type`. |
-| `plob document-get --document-id <id>` | Read a document. |
+| `plob document-get --document-id <id> [--out <file>] [--body-only]` | Read a document. |
 | `plob analysis-pull <documentId> [--out <file>] [--body-only]` | Write one analysis document as Markdown, with the statements it rests on. |
 | `plob document-put --document-id <id> --version-token <token> --content <markdown> [--idempotency-key <key>]` | Update a document. |
 | `plob context-pack [--sections <list>] [--limit <n>] [--cursor <cursor>]` | Read accumulated workspace context. |
@@ -45,17 +45,22 @@ plob --help
 | `plob ingest --bundle <path-or-dash> [--content-type <type>] [--source-name <name>] [--idempotency-key <key>]` | Ingest a bundle of notes. |
 | `plob premise-list [--document-id <id> \| --run-id <id>] [--status <status>] [--cursor <cursor>]` | List the statements the workspace's analyses rely on, with suggested changes waiting for the person. Each line shows the premise id and the revision id `plob premise-propose` needs. Available once the workspace's server lists the `premise-list` tool. |
 | `plob premise-propose --premise-id <id> --revision-id <id> --proposal <confirm\|correct> --evidence <text> [--text <text>] [--source-document-id <id>] [--idempotency-key <key>]` | Suggest a confirmation or a corrected wording for one statement, with your evidence, for the person to confirm. Needs `write:observe`. Prints the suggestion id and "Waiting for the person to confirm." Generates an idempotency key when none is given. Available once the workspace's server lists the `premise-propose` tool. |
+| `plob decision-list [--view log\|queue] [--status <status>] [--limit <n>] [--cursor <cursor>]` | List the calls the person recorded in the workspace's decision log, newest first: one line per call with its status, review date, question and decision id. `--status` is `holding`, `review_due`, `scored`, `withdrawn` or `superseded`; superseded calls are left out unless asked for. `--status`, `--limit` and `--cursor` apply to the log view only. `--view queue` prints how many things wait on the person, then one line per item: a review waiting for a choice or paused (with its link), a document a run waits on, a check-in that is due, an agent's report or suggestion. Available once the workspace's server lists the `decision-list` tool. |
+| `plob decision-get <decisionId>` | Read one call in full: the question, the call and the prediction, its status, review date and reversibility, the call that replaced it and the call it replaced (`Replaced by:` / `Replaces:`), the passages it rests on ("source deleted" where the document is gone), its score once there is one, and a waiting agent report ("from this connection" when this key sent it). Available once the workspace's server lists the `decision-get` tool. |
+| `plob decision-report-outcome --decision-id <id> --outcome <worked\|learned\|too_early\|didnt_get_to_it> --note <text> [--upload-id <id>] [--idempotency-key <key>]` | Report what happened after a call, with a note saying what you saw and optionally an upload that holds your evidence (the document id `plob upload` prints). The report waits for the person to confirm it and changes nothing on the call; a later report replaces a waiting one. Prints the decision id and "Waiting for the person to confirm." Needs a key with Add observations (`write:observe`). Generates an idempotency key when none is given. Available once the workspace's server lists the `decision-report-outcome` tool. |
 | `plob --workspace <workspaceId> upload --file <path>` | Upload a document file to a workspace. |
 | `plob --version` | Print the installed CLI version. |
 
 `plob workspaces` lists the workspace your stored credential can access. The initial credential is workspace-bound, so it returns that single workspace.
 
-`plob launch` and `plob audit` run on the workspace's stored product idea, the same product every start in the app uses, so leave `--idea` out. A different product needs a new workspace. These runs do not yet carry the onboarding context the app's Start Analysis adds. From plob 0.1.7 `--idea` is optional; when given, it is sent and must be the workspace's product. The server refuses a different product with `workspace_mismatch` and starts nothing: the key works only in its one workspace, so a new product needs a new workspace that the person creates in the app. The message says what the person does next and names the link, and `--json` carries it in `details.url`: the new-workspace page; the plan page when the plan has no room for another workspace, the trial has ended or an invoice is overdue; or, at a beta workspace allowance, the support email address. A workspace that is not set up yet refuses both commands until the person finishes setting it up in the app. A blank `--idea` is refused before any call.
+`plob launch` and `plob audit` run on the workspace's stored product idea, the same product every start in the app uses, so leave `--idea` out. A different product needs a new workspace. These runs do not yet carry the onboarding context the app's Start Analysis adds. From plob 0.1.7 `--idea` is optional; when given, it is sent and must be the workspace's product. The server refuses a different product with `workspace_mismatch` and starts nothing: the key works only in its one workspace, so a new product needs a new workspace that the person creates in the app. The message says what the person does next and names the link, and `--json` carries it in `details.url`: the new-workspace page; the plan page when the plan has no room for another workspace, the trial has ended or an invoice is overdue; or, at a beta workspace allowance, the support email address. A workspace that is not set up yet refuses both commands until the person finishes setting it up in the app. From plob 0.1.8, human output words both refusals for the terminal ("run it again without --idea", then the step for a new product or for finishing setup), chosen by the refusal's `details.reason` (`new_idea_needs_new_workspace` or `workspace_setup_incomplete`) rather than by the server's sentence, which is written for an MCP agent; `--json` keeps the server's message and `details` unchanged. A blank `--idea` is refused before any call.
 
 `plob refine` starts a poll-only refinement of a prior run. It returns the child run id; poll it with `plob run-status`.
 
 `plob build --target <runId>` builds the prototype, its solution design and its requirements from a finished launch run. It returns the build's run id; poll it with `plob run-status` and answer its checkpoint with `plob checkpoint-resolve`. Only a launch run that finished after its second checkpoint can be built; any other run in the workspace answers `conflict`, a run id from outside it answers `workspace_mismatch`, and nothing starts. If a build of that run is already under way, the command prints that build's run id instead of starting another. A blank `--target` is refused before any call. The first build of a run is included with it; a second build counts as one of the person's full analyses. When the build ends, the person gets one email from ProductLobster unless they turned emails off; the CLI sends none.
 
+`plob checkpoint-resolve` passes the option the person chose. When the server records it as a suggestion (`suggestionRecorded: true` in `--json`), the person makes the call on the review, and the CLI prints "your suggestion is recorded; the person makes the call on the review": tell them it is waiting, keep polling `plob run-status` and don't resolve again unless they pick a different option. The review then shows the reason beside the suggestion, and without one the person sees just the suggestion; a reason over 300 characters once its spacing is tidied is refused as `invalid_arguments`. Otherwise the choice is recorded and the run resumes, the reason is ignored, and the CLI prints the selection lines it always has.
+
 The global `--workspace <id>` option is used by `plob upload`; for every other command the workspace is resolved server-side from the stored API key, and the CLI never sends a workspace identifier.
 
 ## Examples
@@ -125,6 +130,15 @@ plob analysis-pull doc_123 --body-only > analysis.md
 
 The version token belongs to the stored document: use it with `plob document-put` to replace the stored body (read the body with `plob document-get`). Don't write the pulled Markdown back as it is, since it adds the title, the statements section and any front-matter. One pull makes several requests on the connection (about 4 for the document, plus one per page of up to 50 statements: up to about 14), and they count against the per-connection limit of about 50 requests a minute, so pull a few documents a minute rather than a whole workspace at once.
 
+Save one document's stored body as a Markdown file:
+
+```bash
+plob document-get --document-id doc_123 --body-only > document.md
+plob document-get --document-id doc_123 --out ./document.md
+```
+
+`plob document-get --out` and `--body-only` (plob 0.1.8 and later) work as `analysis-pull`'s do, on the stored body alone. `--body-only` sends exactly the document's body to stdout, even when stdout is piped, and writes the document id and version token to stderr, so `plob document-put --document-id doc_123 --version-token <token> --content - < document.md` writes it back. `--out <file>` creates a new file with the same refusals as `analysis-pull --out` (it never overwrites, the folder must already exist, a blank value is refused); the file opens with a front-matter block holding `documentId` and `versionToken`, or, with `--body-only`, is the body alone. Stdout then carries only `Wrote <path>` on a terminal, or one JSON document `{ path, documentId, versionToken }`. `--body-only` cannot be combined with `--json` (exit `2`). Without either flag the output is unchanged.
+
 `plob upload` attaches one file to the selected workspace. Use the workspace `id` from `plob workspaces`, not the display name. The connection must include the `write:upload` scope. Supported extensions: `.pdf`, `.docx`, `.txt`, `.md`, `.markdown`, `.csv`, `.png`, `.jpg`, `.jpeg`, and `.webp`; files must be non-empty and at most 10 MB.
 
 ```bash