@flowmind/cli 0.3.2 → 0.3.6

package/README.md

@@ -91,19 +91,35 @@ AI confirmation time. Run `fm log --help` for all options.
 ## Stage an agent proof
 
 Agents stage completed work for explicit human approval. In a linked repository with the session
-hooks installed, the intention and outcome are enough:
+hooks installed, the intention and outcome are enough. Write the outcome as one line of at most
+120 characters: what changed for the project or its users. Add up to three optional `--detail`
+values for proof or open items. Each detail must be one line of at most 100 characters.
+Keep commits, runs, paths, and open items in details or use `--artifact-url` for the proof link.
+
+For example:
 
 ```sh
-flowmind agent stage --intention "Finish the reader" --outcome "Shipped the reader" \
-  --artifact-url https://example.com/proof --json
+flowmind agent stage --intention "Fix CLI sign-in" \
+  --outcome "Signed-out CLI sign-in now returns to Authorize CLI" --detail "Cause: Supabase rejected the www callbacks" --detail "Still needs: deploy approval" \
+  --json
 ```
 
+If a proof breaks these rules, the CLI rejects it before any request. The error says exactly
+what to shorten or split and includes the worked example above. In `--json` mode, stderr contains
+an `error` message and an `issues` list. API rejections retain the server's exact message.
+Existing long notes remain readable; this rule applies to new proofs. `agent proposals` shows
+details as indented bullets, and `--json` includes the API's details unchanged.
+
 The CLI reads the project from `.flowmind.json` and the session from `CODEX_THREAD_ID` or the one
 session with a turn in progress in the repository. The duration is the main agent's recorded turn
 time since the session's last staged proof, in whole minutes; the remaining seconds carry over to
 the next proof. Idle time between turns does not count, and neither does sleep: the hooks read the
 awake clock that Codex uses for "Worked for". Subagent prompts never start a turn, because the main
-agent's turn already contains their work. When nothing new is recorded, or when a Codex subagent
+agent's turn already contains their work. Codex runs no prompt hook for a turn that another chat
+starts (`send_message_to_thread`, `create_thread`). For such a turn the CLI reads the start, the end
+and Codex's own awake time from the Codex session file. It places a time on the awake clock only where
+the record shows no sleep in between; on macOS that record is the kernel's last wake time. The JSON
+output gives the recorded `unstagedSeconds`. When nothing new is recorded, or when a Codex subagent
 calls the command, it stages nothing, prints `"staged": false` with a `reason` and a `message`,
 and exits 0. The source kind is `codex` or `claude_code` from the recording host.
 `--dry-run` prints the request and its retry key without staging anything.
@@ -126,6 +142,27 @@ The retry key derives from the session id, project id, and start time, so each w
 session gets its own key. `agent capabilities`, `agent projects`, `agent routines`, `agent proposals`,
 and `agent cancel` accept `--json`. `auth status` shows the API URL and accepts `--json`.
 
+### Saved stages
+
+The CLI saves every stage on the machine before it sends it, so a crash, a timeout or a lost answer
+never loses it. When Flowmind does not take the stage, because the API is unreachable, answers too
+slowly (30 seconds), fails, limits the request, or sends an answer the CLI cannot read, the stage
+stays saved and the command exits 0 with `"staged": false`, `"reason": "saved"`, the `error`, and a
+`pendingStageId`. The session counts its time as staged, so the next proof does not repeat it. A
+refused or missing credential, or an unexpected CLI error, keeps the stage saved but exits 1, because
+someone must act. A stage that the API refuses for its content is removed, and its time stays unstaged
+for a corrected proof.
+
+Saved stages are sent with the same retry key and body. The API keeps one proof per account and
+retry key, also after its 24-hour receipt expires and under another credential, so a stage that
+reached the server before its answer was lost comes back as the same proposal. Saved stages go out after the next accepted stage
+(`savedStagesSent` in the JSON output) and from the session hooks, which start `agent retry --due`
+in the background when one is due: 1, 2, 4 … minutes after each failed attempt, at most an hour.
+`agent pending` lists them and `agent retry` sends them now; both accept `--json`. A saved stage that
+the API later refuses for its content stays listed as `rejected` and is not sent again.
+If a process ends between saving a stage and marking its session, the next stage on the machine
+restores the mark first. One sender runs at a time per machine.
+
 ## Momentum brief
 
 ```sh
@@ -176,6 +213,11 @@ Errors go to stderr and exit with status 1.
 [`src/api.ts`](src/api.ts) exposes `apiRequest(descriptor, args, options)` through the shared response decoder.
 [`src/contracts.ts`](src/contracts.ts) binds command workflows to generated descriptors and `@flowmind/contracts/wire` types.
 Every API request validates the media type, envelope, status agreement, and response schema.
+An installed CLI can be older than the API, so it accepts one kind of difference: a response field that its contracts do not declare, inside a closed object.
+It drops that field before the command reads the response, so the field never reaches the output or `--json`.
+Every other difference still fails: a missing, retyped or renamed field, an unknown enum value, a union that matches no branch, and an unknown top-level envelope field.
+[`src/response-additions.ts`](src/response-additions.ts) owns this rule; the [decision](../../docs/decisions/2026-10-23-cli-response-additions.md) gives the reasons and the limits.
+The rule is sound only for some schema forms, so the build runs [`response-forms.mjs`](response-forms.mjs) and fails when a response that the CLI reads uses another form.
 See the [contract generation flow](../../docs/reference/codebase/ARCHITECTURE.md#api-contract-generation-and-decoding) and [endpoint procedure](../../docs/reference/codebase/CONVENTIONS.md#add-or-change-an-endpoint).
 Do not cast response data, write payload parsers, or add generic request helpers.
 Commands exit with status 1 when transport, JSON, media type, envelope, or payload checks fail.

package/dist/flowmind/SKILL.md

@@ -49,20 +49,51 @@ To find gaps across the user's folders, run `flowmind link --scan <dir...>`. It
 In a linked repository, the session hooks record how long the main agent's turns run. When you finish a material unit of work, such as a feature, fix, investigation, or document, stage it before you start the next one. Do not stage every turn.
 
 ```bash
-flowmind agent stage --intention "<what you set out to do>" --outcome "<what changed or shipped>" --artifact-url <commit, PR, or document URL> --json
+flowmind agent stage --intention "<what you set out to do>" --outcome "<one line: what changed>" --detail "<proof or open item>" --artifact-url <commit, PR, or document URL> --json
 ```
 
 - The CLI reads the project from `.flowmind.json` and the time from the session record. The time is the main agent's turn time on the awake clock that Codex uses for "Worked for", so sleep does not count. It includes the time that subagents work during the turn.
+- A turn that another chat starts, for example with `send_message_to_thread` or `create_thread`, counts like a typed turn. Codex runs no prompt hook for it, so the CLI reads its start from the Codex session file.
 - A stage covers the whole minutes since the session's last proof. The remaining seconds carry over to the next proof.
 - When several units of work finish together, stage them as one proof that names them all. A second stage right after the first has no new time.
 - Subagents do not stage. In a Codex subagent, `flowmind agent stage` stages nothing and tells the subagent to report its outcome to the main agent.
 - `"staged": false` in the JSON output means that nothing was staged, and it is not an error. `reason` is `no-new-time` when the last proof (`lastProposalId`) already holds the session's time, or `subagent`. Tell the user which proof covers the work.
+- `"reason": "saved"` means that the server did not take the proof yet, for example because Flowmind was unreachable, a limit was reached, or its answer could not be read. The CLI saved it on this machine and sends it automatically: after the next accepted stage, or in the background from the session hooks. Its time already counts as staged. Do not stage it again, do not invent another `--idempotency-key`, and tell the user it waits to be sent.
+- A refused credential also keeps the proof saved, but exits with an error: the user must run `flowmind auth login`. A proof that the server refuses for its content (too long, unknown project) is not saved; fix it and stage again.
+- `flowmind agent pending --json` lists the proofs saved on this machine; `flowmind agent retry --json` sends them now.
 - After 20 minutes of unstaged agent time, each prompt in a linked repository carries a reminder with the unstaged minutes. Stage when the current unit of work is complete; a stage with explicit times also resets the count.
 - Add `--dry-run` to preview the project and minutes without staging.
 - Pass `--project`, `--minutes`, and `--started-at` only when no session record exists. Use observed times only. Never estimate time from tokens or tool calls.
-- Write the intention and the outcome as one short sentence each. Never paste transcripts, terminal output, commit messages, issue titles, emails, or secrets.
 - Share `proposal.webReviewUrl` with the user. The user approves staged work in Flowmind Activity; **Approve all with links** approves every item with an artifact link at once. Approved agent time counts on the project, not as the user's personal effort or XP.
-- If staging fails, report the error. Never fall back to `flowmind log`, and never approve your own proposals.
+- If staging fails with an error, report it. Never fall back to `flowmind log`, and never approve your own proposals.
+
+### Write the proof for a person
+
+The user reads many proofs at once, often on a dashboard. Keep each one short:
+
+- `--intention`: what you set out to do, in one short sentence.
+- `--outcome`: one line of at most 120 characters that says what changed for the project or its users. Lead with the result, not the method.
+- `--detail`: optional, at most 3, each one line of at most 100 characters. Use details for proof (cause, check, version) and for anything still open ("Still needs: ..."). Repeat the flag for each detail.
+- Put the commit, PR, or document in `--artifact-url`, not in the text.
+- Never paste transcripts, terminal output, commit messages, issue titles, emails, or secrets.
+
+The CLI and the API reject a proof that breaks these limits and say what to change. Shorten the text and stage again.
+
+Good:
+
+```bash
+flowmind agent stage --intention "Fix CLI sign-in for signed-out users" \
+  --outcome "Signed-out CLI sign-in now returns to Authorize CLI" \
+  --detail "Cause: production Supabase rejected the www callbacks" \
+  --detail "Still needs: Supabase URL settings and deploy approval" \
+  --artifact-url https://github.com/<owner>/<repo>/commit/<sha> --json
+```
+
+Rejected, because the outcome is a paragraph:
+
+```text
+--outcome "Found that production Supabase rejects every www sign-in callback and falls back to the apex domain, so Google and GitHub sign-in land on the home page signed out. Changed the web app so a signed-out CLI link goes to /login ..."
+```
 
 ## Log the user's own work