@productlobster/plob 0.1.6 → 0.1.8

package/README.md

@@ -23,31 +23,44 @@ plob --help
 | `plob logout` | Remove the stored API key. |
 | `plob guide` | Print the agent setup guide (local, no network). |
 | `plob workspaces` | List accessible workspaces. |
-| `plob audit --idea <text>` | Assess an existing product. |
-| `plob launch --idea <text>` | Take an idea through the launch workflow. |
+| `plob audit [--idea <text>]` | Assess the workspace's existing product. |
+| `plob launch [--idea <text>]` | Take the workspace's idea through the launch workflow. |
 | `plob focused-analysis --question <text> [--analysis-type <id>]` | Run a single focused analysis. |
 | `plob prototype [--context <text>] [--template <id>]` | Build a clickable prototype. |
 | `plob refine --target <runId> --instruction <text>` | Re-run a prior run with new instructions. |
+| `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. |
 | `plob observe --kind <kind> --content <text> [--idempotency-key <key>]` | Record a single observation. |
 | `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. 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
@@ -55,7 +68,7 @@ The global `--workspace <id>` option is used by `plob upload`; for every other c
 Start a run and poll it as JSON:
 
 ```bash
-plob --json launch --idea "Scheduling for architecture review teams"
+plob --json launch
 plob --json run-status run_123 | jq .status
 ```
 
@@ -102,6 +115,30 @@ local filesystem: this does not defend against another process replacing parent
 directories during extraction, and exclusive creation may not be reliable on
 every network filesystem.
 
+Pull one analysis as a Markdown file:
+
+```bash
+plob analysis-pull doc_123 --out ./analysis.md
+plob analysis-pull doc_123 --body-only > analysis.md
+```
+
+`plob analysis-pull` (plob 0.1.7 and later) reads the document with `document-get`, then the statements it cites with `premise-list`, on one connection. The Markdown is the title, the body, and, when the workspace records statements, a "What we're taking as true" section with one line per statement (its tier, its status, and "confirmed" when the person confirmed it), followed by one line counting the suggested changes waiting for the person on those statements. The text of a suggestion is never included. Server text quoted in the title and the statements is Markdown-escaped, so it cannot add headings, links, images or HTML. The section lists at most 200 statements and says so when there are more. When the workspace does not record statements, the section is left out and so are the `premiseCount` and `truncated` fields below and the JSON `premises` and `truncated`.
+
+- `--out <file>` creates a new file (permissions 0600 on POSIX) that opens with a front-matter block holding `documentId`, `versionToken`, `premiseCount` (the statements listed) and `truncated`. It never overwrites or follows anything already at the path, a symlink included; the folder must already exist and allow writing, and a path ending in `/` is refused. Each refusal exits `2` with nothing written; a write that fails part-way removes the partial file. Stdout then carries only the metadata: `Wrote <path>` on a terminal, or one JSON document `{ path, documentId, versionToken, premiseCount, truncated }`, never the body.
+- `--body-only` sends only the Markdown to stdout, even when stdout is piped, and writes the document id and version token to stderr; a failure then goes to stderr as text, so stdout is the Markdown or nothing. With `--out` it writes the file without front-matter. It cannot be combined with `--json` (exit `2`), and the Markdown still includes the title and the statements section.
+- Otherwise output follows the usual rule: the document id, the version token and the Markdown on a terminal, or one JSON document (`document`, `premises`, `truncated`) under `--json` or a pipe.
+
+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
@@ -180,7 +217,8 @@ Anything shaped like an API key is redacted to `ak_[redacted]` in those diagnost
 | 16 | Rate limited |
 | 17 | CLI version revoked; upgrade before retrying |
 | 18 | Backend temporarily unavailable; retry shortly |
-| 19 | Included outcomes used; the account is read-only for agents |
+| 19 | The account is read-only (trial or plan ended, or invoice overdue); the message says which |
+| 20 | `not_available`: the command exists but is not turned on for this workspace; don't retry |
 | 70 | Network or transport failure |
 
 When the server reports a version is no longer supported, the CLI exits 17 and prints the npm upgrade command from the structured error details. In `--json` mode, the same detail is emitted in the single JSON error document.