@flowmind/cli 0.1.0 → 0.2.1

package/README.md

@@ -1,5 +1,44 @@
 # Flowmind CLI
 
+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 `agent hook` through the absolute paths of the installing Node binary and CLI file,
+because hooks start without your shell profile and a version manager may not put `node` on PATH.
+Codex on Windows gets a PowerShell command (`& '<node>' '<cli>' agent hook --agent codex`).
+After you upgrade Node or move the CLI, `hooks status` shows `outdated`; run `hooks install` again
+and trust the changed hooks. The hook 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
@@ -21,7 +60,21 @@ AI confirmation time. Run `fm log --help` for all options.
 
 ## Stage an agent proof
 
-Claude Code can stage completed work for explicit human approval:
+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 \
@@ -35,6 +88,10 @@ Source kinds: `calendar`, `claude_code`, `cli`, `codex`, `github`, `linear`,
 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
@@ -53,6 +110,33 @@ 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.

package/dist/flowmind/SKILL.md

@@ -1,169 +1,69 @@
 ---
 name: flowmind
-description: "Use the fm CLI or Flowmind API to log user-requested time, stage completed agent work for review, or inspect Flowmind projects and progress. Skip generic time tracking or project questions that do not request Flowmind data."
+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 Skill
+# Flowmind
 
-Use Flowmind to quickly log work sessions, track streaks/XP, and review weekly progress.
+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`.
 
-## When to Use
+## Set up Flowmind
 
-✅ **USE this skill when the user asks to:**
+Use this when the user says "set up Flowmind", "connect my projects to Flowmind", or similar.
 
-- Log time or add a time entry
-- Track time against a project
-- Check streak, XP, or level
-- Get a weekly hours/progress summary
-- List available projects before logging
+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.
 
-Typical trigger phrases:
+## Log agent work
 
-- "log 2 hours on my project"
-- "add a time entry"
-- "how's my streak"
-- "what did I work on this week"
-
-## When NOT to Use
-
-❌ **DON'T use this skill for:**
-
-- Calendar scheduling (use calendar tools)
-- Payroll/accounting reports unless user explicitly wants Flowmind data only
-- Generic project management tasks not related to time logging or Flowmind progress
-
-## Setup
-
-### 1) Install the CLI
-
-```bash
-npm install -g @flowmind/cli
-```
-
-### 2) Authenticate
-
-```bash
-fm auth login
-```
-
-### 3) Install agent skills
-
-```bash
-fm hooks install
-```
-
-This installs the same staging instructions for Codex and Claude Code. Check them with:
-
-```bash
-fm hooks status
-```
-
-<!-- Codex personal skills: https://learn.chatgpt.com/docs/build-skills -->
-<!-- Claude Code personal skills: https://code.claude.com/docs/en/skills -->
-Codex reads `~/.agents/skills/flowmind/SKILL.md`; Claude Code reads `~/.claude/skills/flowmind/SKILL.md`. An older Codex copy at `~/.codex/skills/flowmind/SKILL.md` is reported by `fm hooks status` but never changed by install or uninstall.
-
-## Core Commands
-
-### Log time (preferred: natural language)
-
-```bash
-fm log "2h working on the backend API"
-```
-
-The command shows the original input and lets you correct project, whole minutes and outcome. Choose the work date explicitly, then confirm the final preview. Only today in your saved timezone is eligible. Parsing never writes; saving sends the reviewed fields to `/v1/ai/log/confirm` without another model call. If the save response is lost, retry from the same prompt to reuse its idempotency key. After leaving an uncertain save, check Activity before starting a new capture.
-
-
-### Log time (structured)
-
-```bash
-fm log -p "ProjectName" -h 2 -i "Ship the API slice" -o "Implemented and validated the API slice" -a <optional-artifact-url>
-```
-
-### Check progress/streak
+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
-fm status
+flowmind agent stage --intention "<what you set out to do>" --outcome "<what changed or shipped>" --artifact-url <commit, PR, or document URL> --json
 ```
 
-### Weekly summary
+- 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.
 
-```bash
-fm stats
-```
-
-### List projects
-
-```bash
-fm projects
-```
+## Log the user's own work
 
-### Agent Toolkit V2 (automatic staged proof)
+Use `flowmind log` only when the user asks you to log work that they did themselves:
 
 ```bash
-fm agent capabilities
-fm agent projects
-fm agent routines
-fm agent stage --project <project-id> --minutes 120 --intention "Ship the API slice" --outcome "Implemented and validated the API slice" --artifact-url <optional-url> --session-evidence "API slice completed and tested" --session-id <thread-or-run-id> --started-at <iso-date-time> --json
-fm agent proposals
-fm agent cancel <proposal-id> --idempotency-key <stable-key>
+flowmind log -p "<project>" -h <hours> -i "<intention>" -o "<outcome>" [--started-at <ISO date-time>] [-a <artifact URL>]
 ```
 
-## Agent Behavior Guidelines
+Ask only for missing fields. A natural-language entry (`flowmind log "2h on the API"`) needs the user at the terminal to review it.
 
-- After completing a material project work session, automatically stage one proof when `fm agent capabilities` reports `flowmind-agent-toolkit-v2` and includes `log_proposals:create`.
-- Staging does not mutate the Hour Bank, so do not interrupt the user for confirmation before staging. Share the returned review URL.
-- Stage only when project, actual elapsed minutes, session start, intention, and outcome are known. Do not invent missing values or infer duration from token/tool usage.
-- Use one stable session/run/thread id per completed work unit. The CLI derives the retry key when both `--session-id` and `--started-at` are present.
-- Never stage routine or unassigned work through the project proof command.
-- Use direct `fm log` only when the current user request or standing preference explicitly authorizes the complete entry and the current account/API permits that write. Reuse that authorization; clarify missing or ambiguous fields instead of asking twice. Agent-originated staged proofs still require human approval in Flowmind Activity; never bypass that product boundary or substitute a direct write.
-- If automatic staging fails, report the failure. Never fall back to a direct ledger write.
-- After logging, confirm success and include **XP earned** when available.
-- If the logged session is a flow session (≥ 90 minutes), mention that the deep-work bonus applies only to time beyond the first 90 minutes.
+## Read progress
 
-## Agent Toolkit V2 Status
-
-Flowmind Agent Toolkit V2 is defined in `docs/specs/2026-08-31-flowmind-agent-proof-staging-v2.md`. Scoped API-key storage exists for `read_only`, `log_only`, and `full_personal`. Backend staged proof routes and matching `fm agent` commands exist for:
-
-- capability discovery
-- agent-visible project/routine context
-- canonical project-proof creation with intention, outcome, and optional artifact
-- proposal listing
-- proposal cancellation
-- session-log provenance and automatically derived retry identity
-- machine-readable stage output for agent hooks
-
-Agents should first call `fm agent capabilities`. If it reports `flowmind-agent-toolkit-v2` and includes `log_proposals:create`, use staged proofs for completed agent-originated project work. Proposal approval is intentionally not an API-key CLI command; a human approves staged proofs in Flowmind Activity.
-
-For coding/session work, pass a short `--session-evidence` summary, stable `--session-id`, actual `--started-at`, and optional `--session-url`. Pass a canonical artifact through `--artifact-url`. Do not store raw terminal logs, transcript text, commit messages, issue titles, calendar titles, emails, or other sensitive raw source text as evidence.
-
-Agent-specific parse, proof-status, and weekly-summary commands are not shipped yet. If staging is unavailable, report that limitation. A separate, fully specified user request may authorize a supported direct entry; missing staging capability never authorizes an agent-originated ledger write.
-
-### Missing entry details
-
-Ask only for the fields needed to make the requested entry unambiguous, such as the project, duration, intention, or outcome. Preserve the CLI preview when natural-language parsing still requires review.
-
-## Direct API Fallback (No CLI)
-
-If `fm` is unavailable, use the Flowmind API directly.
-
-- Default local base URL: `http://localhost:8080`
-- Auth header: `Authorization: Bearer $FLOWMIND_API_KEY`
-- If a different environment is configured, use that base URL instead.
-
-```bash
-curl -X POST http://localhost:8080/v1/agent/log-proposals \
-  -H "Authorization: Bearer $FLOWMIND_API_KEY" \
-  -H "Idempotency-Key: <stable-session-key>" \
-  -H "Content-Type: application/json" \
-  -d '{"targetKind":"project","projectId":"...","startedAt":"2026-08-31T10:00:00Z","durationMinutes":120,"description":"Ship the API slice","note":"Implemented and validated the API slice","artifactUrl":"https://github.com/example/repo/pull/42","source":{"kind":"session_log","label":"Agent session","externalId":"session-or-thread-id"},"evidence":[{"kind":"session_log","label":"API slice completed and tested","externalId":"session-or-thread-id","url":null}]}'
-```
+- `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.
 
-## Practical Workflow
+## Troubleshooting
 
-1. Run `fm agent capabilities` once per environment or after an integration error.
-2. If V2 staged proofs are available and `log_proposals:create` is present, run `fm agent projects` to resolve the project id.
-3. At the end of a material completed work unit, stage it with canonical proof fields, actual timing, `--session-id`, and `--json`.
-4. Share the proposal review URL with the user for approval.
-5. If staged proofs are unavailable, report the limitation. For a separately authorized direct entry, resolve its complete fields and use the supported `fm log ...` path without a redundant confirmation.
+- `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.
+- `outdated` hooks: run `flowmind hooks install` again (for example after a Node upgrade) and trust the changed hooks.
+- "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`.