@productlobster/plob 0.1.6 → 0.1.7

package/README.md

@@ -23,11 +23,12 @@ 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. |
@@ -37,17 +38,24 @@ plob --help
 | `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 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 --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 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.
+
 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 +63,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 +110,21 @@ 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.
+
 `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 +203,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.