@flowmind/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# Flowmind CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The package installs two equal commands, `flowmind` and `fm`. On macOS, `/usr/bin/fm` can be
+Apple's Foundation Models tool, so agents and hooks call `flowmind`.
+
+## Set up coding agents
+
+```sh
+npm install -g @flowmind/cli
+flowmind auth login
+flowmind hooks install
+```
+
+`hooks install` copies the Flowmind skill to Codex and Claude Code and adds session hooks to
+`~/.codex/hooks.json` and `~/.claude/settings.json`. Other hooks in those files stay as they are.
+The hooks run `flowmind agent hook`, which records each agent turn under the CLI config folder.
+In a linked repository, the session-start hook tells the agent which project it works on.
+Codex runs new hooks only after you trust them once in `/hooks`. `hooks status` shows both installs,
+and `hooks uninstall` removes only the Flowmind entries.
+
+Then ask your agent to "set up Flowmind". The skill has it inventory your repositories, propose
+projects, and create and link them after you approve the list.
+
+## Projects and repository links
+
+```sh
+flowmind projects --json
+flowmind projects add "Bead Focus" --description "Focus timer for iOS" --json
+flowmind link "Bead Focus"              # writes .flowmind.json at the repository root
+flowmind link <project-id> --dir ~/projects/bead-focus
+flowmind link                           # shows the current link
+```
+
+A link names the project by id and keeps its name as a label. `link` accepts an id or an exact
+project name and checks it against the projects visible to agents. Commit `.flowmind.json` to share
+the link with other machines and agents.
+
+Log completed work by project name and duration:
+
+```sh
+fm log --project Flowmind --hours 1.5 --outcome "Shipped the reader"
+```
+
+Without a start time, the session ends when saved: 90 minutes saved at 10:00
+records 08:30–10:00. To supply the actual start, use an ISO 8601 timestamp with
+a timezone:
+
+```sh
+fm log --project Flowmind --hours 1.5 --started-at 2026-10-02T08:30:00+02:00 --outcome "Shipped the reader"
+```
+
+Future session ends are rejected before contacting the API. The API enforces
+the seven-day logging window in your stored timezone. `--started-at` applies to
+structured project/hours logging. Natural language logging uses its reviewed
+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:
+
+```sh
+flowmind agent stage --intention "Finish the reader" --outcome "Shipped the reader" \
+  --artifact-url https://example.com/proof --json
+```
+
+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 recorded agent turn time
+since the session's last staged proof; idle time between turns does not count. Fewer than one
+recorded minute is an error. The source kind is `codex` or `claude_code` from the recording host.
+`--dry-run` prints the request and its retry key without staging anything.
+
+Without hooks, pass observed values:
+
+```sh
+fm agent stage --project <project-id> --minutes 45 \
+  --intention "Finish the reader" --outcome "Shipped the reader" \
+  --started-at 2026-10-02T08:30:00+02:00 --source-kind claude_code \
+  --artifact-url https://example.com/proof --session-id <stable-session-id> --json
+```
+
+Source kinds: `calendar`, `claude_code`, `cli`, `codex`, `github`, `linear`,
+`manual`, `session_log`, `other`. `claude` is not an alias. Use `--source-label`
+to override the Claude Code display label. Run `fm agent stage --help` for all options.
+Staging adds no hours; approve in Activity individually or confirm **Approve all with links (N)**.
+
+The retry key derives from the session id, project id, and start time, so each work unit in a
+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`.
+
+## Momentum brief
+
+```sh
+fm momentum
+fm momentum --week 2026-10-12
+fm momentum --json
+```
+
+See eight weeks of outcomes, personal and agent hours, project trends, and signals
+with source outcomes. Brackets mark the selected week; each sparkline uses its own
+peak. Quiet projects show the age of their last outcome. Commitment ideas are
+suggestions only and save nothing.
+
+`--week` requires `YYYY-MM-DD`. The API checks that it is a Monday and is not in
+the future. Without it, the API selects your current personal week.
+`--json` prints only the response data as pretty JSON. Errors go to stderr and
+exit with status 1. Colors require a terminal and an unset `NO_COLOR` variable.
+
+## Project ship log
+
+```sh
+fm ship-log "My Project"
+fm ship-log <project-id> --json
+```
+
+Use a project id or an exact project name, ignoring case. Duplicate names require
+an id; unknown names list the available projects. Both errors exit with status 1.
+Archived projects remain available.
+
+The text view shows publication status, public title and summary, and the API's
+public, new, and changed counts. Existing publications include page, card, and
+Atom feed links, plus README badge Markdown. Unpublished links remain listed,
+but public readers receive 404 until the log has published outcomes.
+
+Public counts include only selected outcomes that still match their saved digest.
+Changed counts include edited selections and eligible corrections of selected outcomes.
+New counts include other eligible, unselected outcomes created after the last save.
+New is zero before the first publication. Saving clears new counts for omitted outcomes.
+When new or changed outcomes exist, the command points you to review in the web app.
+
+This command is read-only. A project id accepts a `read_only` API key; resolving
+a name uses the existing project list, which requires `full_personal`. Publish,
+update, or unpublish in the web app. `--json` prints the API data unchanged as pretty JSON.
+Errors go to stderr and exit with status 1.
+
+## Response failures
+
+[`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.
+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.
+A valid API rejection also exits with status 1.
+One diagnostic names the action, operation, schema location, and request ID when available.
+Diagnostics omit response values, credentials, query values, and server messages.
+
+A write with a transport failure, timeout, or contract failure is not confirmed.
+The client never retries it. Check Activity before submitting it again.
+Natural logging no longer offers a retry prompt after an uncertain save.
+Authentication stops immediately on a failed poll. Pending authorization continues polling.
+Expired authorization exits with status 1. No failed authorization saves a credential.
+Use `fm auth login --no-browser` to open the printed authorization URL yourself.
+
+## Verify the CLI
+
+Run `pnpm --filter @flowmind/cli test` from the repository root.
+This builds the CLI, runs command tests against loopback HTTP fixtures, and tests an installed package.
+The package check uses `npm pack` and a local npm install into a temporary prefix.
+A loopback package fixture serves the runtime dependencies already installed in this workspace.
+The install uses an empty npm cache and never contacts a public registry.
+Installed commands run outside the repository.
+
+Reports are saved under `tools/cli/test-results/`:
+
+- `response-contracts-packed.json`: installed command inputs, build hash, results, and request counts.
+- `pack-install.txt`: package installation and hook lifecycle results.
+
+The response matrix also checks credential persistence, diagnostic redaction, and write counts.
+Fixtures are synthetic. These tests do not prove production API availability.

package/dist/flowmind/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: flowmind
+description: "Set up Flowmind for a builder's coding agents and log agent work to it with the flowmind CLI. Use when the user asks to set up, connect, or onboard Flowmind; to create or link Flowmind projects; to log or stage work in Flowmind; to check Flowmind progress; or when you finish material work in a repository that has a .flowmind.json file. Skip generic time tracking that does not involve Flowmind."
+homepage: https://www.flowmind.pro/
+metadata: { "openclaw": { "emoji": "⏱️" } }
+---
+
+# Flowmind
+
+Flowmind records what a builder ships, including work their agents do. Agents use the `flowmind` CLI. It is also installed as `fm`, but on macOS `fm` can be Apple's Foundation Models tool, so always call `flowmind`.
+
+## Set up Flowmind
+
+Use this when the user says "set up Flowmind", "connect my projects to Flowmind", or similar.
+
+1. Check the CLI with `flowmind --version`. If it is missing or older than 0.2.0, run `npm install -g @flowmind/cli`.
+2. Check sign-in with `flowmind auth status --json`. If `authenticated` is false, run `flowmind auth login --no-browser`, give the user the printed URL, and keep the command running while it waits (up to 5 minutes). The user approves in the browser.
+3. Install the skill and session hooks with `flowmind hooks install`. Tell the user that Codex runs new hooks only after they trust them once in `/hooks`. Claude Code runs them at its next session.
+4. Inventory the user's local work:
+   - Find git repositories in the folders the user works in (for example `~/projects`, `~/code`, `~/src`, and the workspaces your host lists). Read each README or package manifest only far enough to name and describe the project.
+   - Read existing Flowmind projects with `flowmind projects --json`.
+   - Read existing links with `flowmind link --dir <repo> --json`.
+5. Propose a table: repository path, Flowmind project name, one-line description, and action (create, link to an existing project, or skip). Put repositories of one product under one project. Ask the user to approve or edit the list. Create nothing before they approve.
+6. After approval, for each row:
+   - Create: `flowmind projects add "<name>" --description "<one line>" --json`. The new id is `project.id`.
+   - Link: `flowmind link <project-id> --dir <repo> --json`. This writes `.flowmind.json` at the repository root.
+   - Ask whether to commit `.flowmind.json`. A committed link reaches the user's other machines and agents.
+7. Report what you created and linked, and explain how agent work gets logged from now on.
+
+## Log agent work
+
+In a linked repository, the session hooks record how long each agent turn runs. When you finish a material unit of work, such as a feature, fix, investigation, or document, stage it. 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
+```
+
+- The CLI reads the project from `.flowmind.json` and the time from the session record. A second stage in the same session covers only the time after the first.
+- 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.
+
+## Log the user's own work
+
+Use `flowmind log` only when the user asks you to log work that they did themselves:
+
+```bash
+flowmind log -p "<project>" -h <hours> -i "<intention>" -o "<outcome>" [--started-at <ISO date-time>] [-a <artifact URL>]
+```
+
+Ask only for missing fields. A natural-language entry (`flowmind log "2h on the API"`) needs the user at the terminal to review it.
+
+## Read progress
+
+- `flowmind status` and `flowmind stats`: hours, streak, and level.
+- `flowmind momentum --json`: eight weeks of outcomes, personal and agent hours, and project trends.
+- `flowmind ship-log <project> --json`: a project's public ship log.
+- `flowmind agent proposals --status proposed --json`: staged work that waits for approval.
+
+## Troubleshooting
+
+- `flowmind auth status` shows the API URL. A normal install uses `https://api.flowmind.pro`.
+- `flowmind hooks status` shows whether the skill and hooks are installed for Codex and Claude Code.
+- "No recorded agent time": the hooks are missing or not trusted, or the session started before installation. Stage with observed `--minutes` and `--started-at`, or stage in the next session.
+- "Several agent sessions have a turn in progress": pass `--session-id`.
+- "No project given": run `flowmind link <project>` in the repository, or pass `--project`.