@flowmind/cli 0.2.2 → 0.3.1

package/README.md

@@ -21,6 +21,15 @@ and trust the changed hooks. The hook records each agent turn under the CLI conf
 In a linked repository, the session-start hook tells the agent which project it works on. Once 20 or more minutes of
 finished agent turns are unstaged, each prompt also carries a reminder with the minutes and the
 staging command. A successful `agent stage` resets the count.
+
+In a git repository without `.flowmind.json`, the session-start hook first reads `.flowmind.json` from the
+local remote-tracking refs: the current branch's upstream, then `origin/HEAD`, `origin/main` and
+`origin/master`. It does not fetch. If a remote ref links the repository, the agent learns the project and
+is told to run `git pull` and never to create a new project. Otherwise the agent gets the steps to link
+the repository: pull, find the existing project, create one only for a new product, link, and commit
+`.flowmind.json`, or mark a third-party clone or scratch folder with `link --ignore`. Once 20 minutes of
+agent turns are recorded in such a repository, one prompt per session repeats this as a short reminder.
+Ignored repositories and folders outside git get no context and no reminder.
 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.
 
@@ -35,12 +44,28 @@ 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
+flowmind link --ignore --reason "Third-party clone"
+flowmind link --scan ~/projects ~/code --depth 2
 ```
 
 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.
 
+One product is one project on every machine. `projects add` refuses a name that an existing project
+already has (trimmed, ignoring case), names that project and its id, and suggests `flowmind link <id>`.
+It creates nothing in that case. `--allow-duplicate` creates the second project anyway.
+
+`link --ignore` writes `{"ignore": true, "reason": "..."}` as `.flowmind.json` for a third-party clone or
+a scratch folder. `link` then prints `Ignored for Flowmind`, the hooks stay silent there, and
+`agent stage` fails unless you pass `--project`. Commit the marker so other machines skip it too.
+
+`link --scan <dir...>` finds git repositories in each directory and up to `--depth` folder levels below
+it (default 2). It skips hidden folders and `node_modules`, and does not search inside a repository.
+Each repository gets a status: `linked`, `ignored`, `remote-linked` (a local remote-tracking ref has the
+link; run `git pull`) or `unlinked`, with the project and the origin URL without credentials.
+`--json` prints `{ "repositories": [...] }`. The scan exits 0 and does not use the network.
+
 Log completed work by project name and duration:
 
 ```sh
@@ -71,9 +96,13 @@ flowmind agent stage --intention "Finish the reader" --outcome "Shipped the read
 ```
 
 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.
+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
+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.
 
 Without hooks, pass observed values:

package/dist/flowmind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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; when you finish material work in a repository that has a .flowmind.json file; when you start or scaffold a new project or repository; or when you work in a repository that Flowmind reports as not linked. Skip generic time tracking that does not involve Flowmind."
 homepage: https://www.flowmind.pro/
 metadata: { "openclaw": { "emoji": "⏱️" } }
 ---
@@ -13,29 +13,50 @@ Flowmind records what a builder ships, including work their agents do. Agents us
 
 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`.
+1. Check the CLI with `flowmind --version`. If it is missing or older than 0.3.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.
+   - Find git repositories and their link status with `flowmind link --scan <dir...> --json` over 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.
+   - A `remote-linked` repository needs only `git pull`.
+5. Propose a table: repository path, Flowmind project name, one-line description, and action (create, link to an existing project, or ignore). 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.
+   - Ignore: `flowmind link --ignore --dir <repo>`.
    - 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.
 
+## New projects and unlinked repositories
+
+Use this when you start or scaffold a new project or repository, or when a session starts in a repository that Flowmind reports as not linked.
+
+One product is one Flowmind project on every machine. The same repository on another machine already shares its link through the committed `.flowmind.json`. Never create a duplicate project.
+
+1. Run `git pull` first. Another machine may have linked the repository already. If Flowmind says the remote links it, the pull is all you need.
+2. Look for the existing project with `flowmind projects --json`. Match by product, repository, and name.
+3. Create a project with `flowmind projects add "<name>" --description "<one line>" --json` only for a new product. If it refuses because the name exists, link to that project instead.
+4. Run `flowmind link <project-id>` and commit `.flowmind.json`.
+5. For a third-party clone or a scratch folder, run `flowmind link --ignore` instead, and commit the marker.
+
+Ask the user once when you are unsure which project a repository belongs to, or whether it counts at all. Do this before you finish the task.
+
+To find gaps across the user's folders, run `flowmind link --scan <dir...>`. It lists each repository as `linked`, `ignored`, `remote-linked`, or `unlinked`.
+
 ## 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.
+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
 ```
 
-- 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.
+- 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 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.
 - 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.
@@ -68,3 +89,5 @@ Ask only for missing fields. A natural-language entry (`flowmind log "2h on the
 - "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`.
+- "This repository is ignored for Flowmind": the repository has an ignore marker. Pass `--project` only if the user wants this work staged.
+- "A project named ... already exists": link to that project with `flowmind link <id>`. Use `--allow-duplicate` only when the user asks for a second project with the same name.