@flowmind/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,90 @@
-# 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.
+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
+
+Claude Code can stage completed work for explicit human approval:
+
+```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)**.
+
+## 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.
+
+## 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,169 @@
+---
+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."
+homepage: https://www.flowmind.pro/
+metadata: { "openclaw": { "emoji": "⏱️" } }
+---
+
+# Flowmind Skill
+
+Use Flowmind to quickly log work sessions, track streaks/XP, and review weekly progress.
+
+## When to Use
+
+✅ **USE this skill when the user asks to:**
+
+- 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
+
+Typical trigger phrases:
+
+- "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
+
+```bash
+fm status
+```
+
+### Weekly summary
+
+```bash
+fm stats
+```
+
+### List projects
+
+```bash
+fm projects
+```
+
+### Agent Toolkit V2 (automatic staged proof)
+
+```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>
+```
+
+## Agent Behavior Guidelines
+
+- 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.
+
+## 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}]}'
+```
+
+## Practical Workflow
+
+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.