@monoes/monomindcli 1.18.6 → 1.18.7

package/.claude/commands/monoes/README.md

@@ -0,0 +1,30 @@
+---
+name: monoes:README
+description: monoes tool family commands — install and manage monotask, mono-agent, and mono-clip
+---
+
+# monoes Commands
+
+Commands for interacting with the `monoes` tool family — separate sibling projects (not part of this monorepo) that live alongside it on disk.
+
+| Tool | What it is | Distribution |
+|---|---|---|
+| `monotask` | P2P kanban / task board (Rust, CLI + Tauri desktop app) | Homebrew tap `monoes/tap` (renamed from `nokhodian/tap`) |
+| `mono-agent` | Workflow/browser automation agent (Go CLI + Wails GUI), binary name `monoagentcli` | Prebuilt GitHub releases (`monoes/mono-agent`), or build from source |
+| `mono-clip` | Desktop clipboard/utility app (Tauri + SvelteKit) + `mclip` CLI sidecar | Homebrew tap `monoes/tap` (renamed from `nokhodian/tap`) |
+
+## Files
+
+- [install.md](./install.md) — Detect, install, and troubleshoot any of the three tools; records their existence in monomind's memory once installed
+- [monoagent.md](./monoagent.md) — Drive the mono-agent CLI (`monoagentcli`): logins, search/message/comment, actions, workflows, node execution
+- [monotask.md](./monotask.md) — Drive the monotask CLI: boards/columns/cards, spaces, GitHub/Linear/mail sync
+- [monoclip.md](./monoclip.md) — Drive mono-clip's `mclip` sidecar CLI: clipboard history and folders
+
+## Crash reporting
+
+All four tools (monomind, mono-agent, monotask, mono-clip) auto-file a GitHub issue on their own repo when they hit an uncaught crash — on by default, `monomind crash-reporting disable` to opt out. That only covers hard crashes. If a user is stuck on non-crash friction with any of these tools — a confusing error, undocumented behavior, something that looks like a real bug — suggest opening an issue yourself (`gh issue create -R monoes/<repo> ...`) rather than staying silent about it.
+
+## See Also
+
+- CLAUDE.md Knowledge Graph / memory sections — how monomind persists cross-session knowledge
+- CLAUDE.md's "Crash reporting" behavioral rule

package/.claude/commands/monoes/install.md

@@ -0,0 +1,163 @@
+---
+name: monoes:install
+description: Detect, install, and troubleshoot the monoes tool family (monotask, mono-agent, mono-clip), then record their existence in monomind's memory
+---
+
+# monoes install
+
+Installs one or more tools from the `monoes` family:
+
+| Tool | What it is | Distribution |
+|---|---|---|
+| **monotask** | P2P kanban / task board (Rust, CLI + Tauri desktop app) | Homebrew tap `monoes/tap` (renamed from `nokhodian/tap` — see Gotchas) — `monotask` formula (CLI) + `monotask` cask (desktop) |
+| **mono-agent** | Workflow/browser automation agent (Go CLI + Wails desktop GUI "MonoAgent"), binary name `monoagentcli` | No Homebrew tap — prebuilt CLI binary + desktop app zip on GitHub releases (`monoes/mono-agent`), or build from source |
+| **mono-clip** | Desktop clipboard/utility app (Tauri + SvelteKit) | Homebrew tap `monoes/tap` (renamed from `nokhodian/tap`) — `mono-clip` cask (desktop only, no CLI, but see mclip sidecar below) |
+
+Sibling repos, if present, live at `../mono-agent`, `../mono-clip`, `../monotask` relative to this repo (i.e. `/Volumes/media/projects/monoes/<name>` on this machine) — used as the source-build fallback and as the source of truth for what each tool does.
+
+## Steps
+
+### 1. Detect current state
+
+Run these checks (batch in one message):
+
+```bash
+command -v monotask; command -v monoagentcli; command -v mclip
+ls /Applications 2>/dev/null | grep -iE "monotask|mono ?clip|mono ?agent"
+brew tap 2>/dev/null | grep -iE "nokhodian|monoes/tap"
+which brew
+which go
+which gh
+```
+
+Note for each tool whether: not installed / CLI installed / desktop app installed / both.
+
+### 2. Ask the user what to install
+
+Use `AskUserQuestion` (multiSelect) with options: **All three**, **monotask**, **mono-agent**, **mono-clip** — skip options that detection already shows as fully installed (mention that in the option description). Each selected tool gets **both its CLI and its desktop app by default** — don't ask a CLI-vs-Desktop follow-up. If a tool already has one half installed (e.g. desktop app present, CLI missing), just install the missing half.
+
+### 3. Install each selected tool
+
+**monotask** (prefer Homebrew — use the fully-qualified `monoes/tap/monotask` name; see Gotchas for why; installs both CLI and desktop app by default):
+```bash
+brew tap monoes/tap   # no-op if already tapped
+brew install monoes/tap/monotask            # CLI
+brew install --cask monoes/tap/monotask     # Desktop app
+```
+**Important**: the formula installs the raw binary as `monotaskcli` (not `monotask`), and Homebrew will refuse to auto-link it if the `monotask` cask is also installed ("monotask cask is installed, skipping link"). After install, check `command -v monotask` — if missing, find and symlink it:
+```bash
+ln -sf "$(brew --cellar)"/monotask/*/bin/monotaskcli "$(brew --prefix)/bin/monotask"
+```
+Fallback if Homebrew unavailable or the formula 404s, and `../monotask` exists locally (requires Rust 1.78+):
+```bash
+cd ../monotask
+cargo build -p monotask-cli --release
+cp target/release/monotaskcli /usr/local/bin/monotask
+```
+
+**mono-clip** (Homebrew cask; the `mclip` CLI sidecar auto-installs on first launch, so launch it once as part of install):
+```bash
+brew tap monoes/tap
+brew install --cask monoes/tap/mono-clip
+```
+**Important**: apply the Gatekeeper fix (see Troubleshooting) to `/Applications/MonoClip.app` **immediately after install, before the first launch** — macOS's `syspolicyd`/AppleSystemPolicy can silently move the unsigned app straight to Trash on its first launch attempt, not just show a "damaged" dialog. If that already happened, the app is recoverable: reinstall from Homebrew's cache (`brew reinstall --cask --force monoes/tap/mono-clip`) rather than trying to resurrect it from Trash (there may be an unrelated stale app of the same name already in Trash from a prior session). Then launch it once via explicit path (not `open -a`, which can resolve to a stale same-named app elsewhere on disk — see the mono-agent gotcha below) to trigger the `mclip` CLI symlink:
+```bash
+find /Applications/MonoClip.app -print0 | xargs -0 xattr -c
+codesign --force --deep --sign - /Applications/MonoClip.app
+open /Applications/MonoClip.app
+sleep 2
+ls ~/.local/bin/mclip   # confirm the symlink appeared
+```
+
+Fallback if `../mono-clip` exists locally (requires Rust, Node 18+, pnpm, Tauri CLI):
+```bash
+cd ../mono-clip
+pnpm install
+pnpm build:mclip    # required: builds the mclip sidecar into src-tauri/binaries/mclip-<target-triple>
+                    # (tauri.conf.json's externalBin needs this to exist first — not wired into
+                    # beforeBuildCommand, must be run manually; skipping it fails the bundle step)
+cargo tauri build   # → src-tauri/target/release/bundle/macos/MonoClip.app
+```
+
+**mono-agent** (no Homebrew tap — prefer the prebuilt release binary/app; binary name is `monoagentcli`, desktop app name "MonoAgent"; macOS Apple Silicon shown, swap the asset suffix for other platforms; installs both CLI and desktop app by default):
+```bash
+curl -fsSL https://github.com/monoes/mono-agent/releases/latest/download/monoagentcli-darwin-arm64 -o monoagentcli
+chmod +x monoagentcli
+sudo mv monoagentcli /usr/local/bin/
+```
+(Other CLI assets on the same release: `monoagentcli-darwin-amd64`, `monoagentcli-linux-amd64`, `monoagentcli-windows-amd64.exe`.)
+
+Desktop app "MonoAgent" ships as a zip on the same release (`MonoAgent-darwin-arm64.zip` / `MonoAgent-linux-amd64.tar.gz` / `MonoAgent-windows-amd64.exe`):
+```bash
+curl -fsSL https://github.com/monoes/mono-agent/releases/latest/download/MonoAgent-darwin-arm64.zip -o /tmp/MonoAgent.zip
+unzip -q -o /tmp/MonoAgent.zip -d /tmp/monoagent-extract
+cp -R /tmp/monoagent-extract/MonoAgent.app /Applications/MonoAgent.app   # NOT sudo cp — sudo makes it root-owned
+                                                                          # and breaks the codesign step below
+find /Applications/MonoAgent.app -print0 | xargs -0 xattr -c
+codesign --force --deep --sign - /Applications/MonoAgent.app
+open /Applications/MonoAgent.app   # explicit path, not `open -a MonoAgent` — see Gotchas
+```
+**Important**: use `cp -R` (no `sudo`) to place the app — a `sudo`-owned copy makes `xattr -c` fail on the root-owned `com.apple.provenance` attribute and produces a broken/partial codesign ("internal error in Code Signing subsystem"), confirmed live. And launch it via the explicit `/Applications/MonoAgent.app` path, not `open -a MonoAgent` — if a stray local dev build exists anywhere on disk (e.g. `../mono-agent/wails-app/build/bin/MonoAgent.app` from a prior `wails build`), Launch Services can resolve the bare app name to that one instead of the one just installed.
+
+Fallback if offline/no network access to GitHub, and `../mono-agent` exists locally (requires Go 1.25+, per `go.mod`):
+```bash
+cd ../mono-agent
+CGO_ENABLED=0 go build -o bin/monoagentcli ./cmd/monoagentcli    # or: make build-cli (same output, matches canonical CI build)
+sudo cp bin/monoagentcli /usr/local/bin/monoagentcli
+```
+
+### 4. Troubleshoot as issues come up
+
+Known issues from each project's README/Makefile — apply the fix automatically when the matching error appears, then retry once:
+
+- **`brew`**: not installed → offer `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` (confirm with user first, this is a real install action).
+- **The tap was renamed**: `nokhodian/tap` now redirects to `monoes/tap`. If both end up tapped (e.g. from an old muscle-memory command), formula/cask lookups become ambiguous — `Error: Formulae found in multiple taps: * monoes/tap/monotask * nokhodian/tap/monotask`. Fix: always use the fully-qualified `monoes/tap/<name>` form (as in the install commands above); if something was already installed from the old tap name, `brew uninstall nokhodian/tap/<name>` then reinstall from `monoes/tap/<name>` (this reinstalls the identical package under its current tap, not a downgrade/different version — safe). To just clear the ambiguity without touching either install, `brew untap --force nokhodian/tap` is safe as long as the installed formula/cask's `INSTALL_RECEIPT.json` already points at `monoes/tap` (check with `brew info <formula>` or `cat "$(brew --cellar)/<name>"/*/INSTALL_RECEIPT.json`).
+- **Faster path for all of the above**: this repo's own `npx monomind doctor -c monoes-tools --install` runs and auto-fixes exactly these three known issues (tap ambiguity, monotask's missing `monotask`→`monotaskcli` symlink, mono-clip's quarantine flag) — it's an opt-in doctor component, not part of the default `doctor` run, since these are unrelated sibling tools rather than monomind dependencies. Prefer it over manually reapplying the fixes below.
+- **`Refusing to load cask/formula ... from untrusted tap monoes/tap` (or `nokhodian/tap`)** → run `brew trust monoes/tap` (or `brew trust --formula monoes/tap/monotask` / `--cask monoes/tap/<name>` if it's scoped to one item), then retry the install.
+- **`"<App> is damaged and can't be opened"` (Gatekeeper, unsigned app) — or the app silently vanishes / relaunches from Trash**: macOS's `syspolicyd` can reject an ad-hoc-signed app on its very first launch and move it to Trash without any visible dialog (confirmed via `log show --predicate 'eventMessage contains "<AppName>"'`: `AppleSystemPolicy: Security policy would not allow process`). Apply this **before** the first launch, not after:
+  ```bash
+  find /Applications/<App>.app -print0 | xargs -0 xattr -c
+  codesign --force --deep --sign - /Applications/<App>.app
+  ```
+  If the app already got trashed: don't try to recover it from `~/.Trash` (there may be an unrelated older copy of the same app name sitting there from a prior session, and `open -a <App>` can resolve to the wrong one). Instead reinstall from Homebrew's cache — `brew reinstall --cask --force <tap>/<name>` re-extracts a fresh copy into `/Applications` — then apply the fix above immediately, then launch.
+- **`open -a <App>` launches the wrong copy, or a stray dev build**: macOS Launch Services resolves a bare app name against *every* registered app bundle by that name on disk, not just the one in `/Applications` — a leftover local build (e.g. `../mono-agent/wails-app/build/bin/MonoAgent.app` from a prior `wails build`) can win. Always launch by explicit path after install: `open /Applications/<App>.app`.
+- **`sudo cp`-ing an app bundle into `/Applications` breaks the Gatekeeper fix**: use plain `cp -R` (no `sudo`) to place `.app` bundles — Homebrew casks install them user-owned, and a root-owned copy makes `xattr -c` fail on `com.apple.provenance` and can produce a broken/partial `codesign` ("internal error in Code Signing subsystem"). `sudo` is only needed for placing plain CLI binaries into `/usr/local/bin`, not `.app` bundles into `/Applications`.
+- **Go build fails, `go: command not found`** → `brew install go`.
+- **`curl` to the mono-agent release 404s or times out** → confirm the asset name matches the current platform exactly (`monoagentcli-darwin-arm64` etc. — check `gh release view -R monoes/mono-agent --json assets -q '.assets[].name'` for the current list (omit the tag argument entirely to get latest — `gh release view latest ...` is invalid syntax and returns "release not found"), since asset names have changed across past renames), then fall back to the source-build path.
+- **`cargo tauri` not found** → `cargo install tauri-cli` (or check `../mono-clip`/`../monotask` `package.json` for a pinned `@tauri-apps/cli` dev dependency and use `pnpm tauri` instead).
+- **Sibling repo missing** (`../<name>` doesn't exist) → tell the user the source-build fallback isn't available on this machine and stick to the Homebrew path, or ask for the repo path.
+- Any other failure → show the actual error output to the user and ask how they want to proceed. Don't retry silently more than once per issue.
+
+### 5. Verify
+
+After each install, confirm it actually works:
+```bash
+monotask version 2>&1 || true         # subcommand, not --version flag
+monoagentcli version 2>&1 || true    # mono-agent CLI
+mclip --help 2>&1 | head -1 || true  # mono-clip CLI sidecar (after the launch-once step above)
+ls /Applications/Monotask.app /Applications/MonoAgent.app /Applications/MonoClip.app 2>&1
+```
+
+### 6. Record knowledge in monomind
+
+For every tool that ends this run **installed and verified** (not for ones skipped or left failing), store a memory entry so monomind's routing/agents know it exists:
+
+```bash
+npx monomind memory store --namespace tools --key "tool:monotask" \
+  --value "monotask — P2P kanban/task board, Rust. CLI: 'monotask <cmd>' (Homebrew formula installs the raw binary as 'monotaskcli' and won't auto-link to 'monotask' if the same-named cask is present — symlink manually, see install.md). Desktop: Monotask.app. Both CLI and desktop app installed by default. Source: ../monotask. Installed via Homebrew (monoes/tap, renamed from nokhodian/tap). Use /monoes:monotask to interact with it." \
+  --tags "external-tool,cli,desktop,installed"
+
+npx monomind memory store --namespace tools --key "tool:mono-agent" \
+  --value "mono-agent — workflow/browser automation agent, Go + Wails. CLI binary name: 'monoagentcli' (renamed from monoes -> monoagent -> monoagentcli; built from ./cmd/monoagentcli). Desktop app: MonoAgent.app (installed via the release zip, not a cask — cp -R without sudo, then xattr -c + codesign --force --deep --sign - before launch; launch via explicit /Applications path, not open -a, since stray local dev builds can shadow it). Both CLI and desktop app installed by default. Prebuilt binaries on GitHub releases (monoes/mono-agent), no Homebrew tap. Source: ../mono-agent. Use /monoes:monoagent to interact with it." \
+  --tags "external-tool,cli,desktop,installed"
+
+npx monomind memory store --namespace tools --key "tool:mono-clip" \
+  --value "mono-clip — desktop clipboard utility, Tauri + SvelteKit. Desktop app: MonoClip.app (unsigned — apply xattr -c + codesign --force --deep --sign - BEFORE first launch, or macOS silently trashes it). Also ships a CLI sidecar, 'mclip' (list/add/get/pin/folder + an MCP stdio server), auto-symlinked to ~/.local/bin/mclip on first GUI launch — install.md now launches it once as part of install to guarantee the CLI is present too. Source: ../mono-clip. Installed via Homebrew (monoes/tap, renamed from nokhodian/tap, cask). Use /monoes:monoclip to interact with it." \
+  --tags "external-tool,cli,desktop,installed"
+```
+
+Only run the `memory store` calls for the tools actually installed this run — don't overwrite entries for tools the user chose to skip.
+
+### 7. Summarize
+
+One short report: what got installed, what was skipped (and why), what's left to fix, and which memory entries were written.

package/.claude/commands/monoes/monoagent.md

@@ -0,0 +1,148 @@
+---
+name: monoes:monoagent
+description: Drive the mono-agent CLI (binary `monoagentcli`) — browser-automation bots, workflows, and node execution for Instagram/LinkedIn/X/TikTok/Gemini and API-connected services
+---
+
+# monoes monoagent
+
+Interact with **mono-agent** — a Go CLI, source at `../mono-agent`, GitHub `monoes/mono-agent`. Not installed? Run `/monoes:install` first.
+
+**Binary name is `monoagentcli`** (as of release `v0.5.2`, "Binary renamed to monoagent", and finalized to `monoagentcli` in the `v0.7.0`-era release pipeline rework). The project went through two renames: `monoes` → `monoagent` → `monoagentcli`. The Cobra root `Use:` field, the `Makefile`, `.github/workflows/release.yml`, and the actual GitHub release assets all agree on `monoagentcli` — that's current truth. **The README.md in the repo still shows the old `monoes` name in its examples — it's stale, don't follow it.**
+
+Given the user's request in `$ARGUMENTS`, pick the matching command(s) below and run them via Bash. If nothing matches cleanly, run `monoagentcli <subcommand> --help` to double-check rather than guessing a flag shape — **not** `monoagentcli ref commands`, whose hand-maintained flag docs are themselves stale for several commands (see Gotchas). `monoagentcli ref nodes` / `ref node <type>` (the node catalogue) is a separate, more reliable code path and fine to use.
+
+## Global flags (available on every subcommand)
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--db-path` | `~/.monoagent/monoagent.db` | SQLite state |
+| `--output-dir` | `~/.monoagent/output` | `export` destination |
+| `--config-dir` | `~/.monoagent/configs` | XPath/selector cache |
+| `--headless` | `false` | Run Chrome headless |
+| `--workers` | `1` | Parallel workers |
+| `-v, --verbose` | | Verbose logging |
+| `--json` | | Machine-readable output |
+| `--log-file` | | Log to file |
+| `--profile` | `""` (falls back to `settings.active_profile_id`, then `"default"`) | Active profile |
+
+**Two separate state directories exist** — don't confuse them: `~/.monoagent/*` (DB, output, config-dir — the flags above) vs. `~/.monoes/*` (workflows, installed action templates, crawl captures, the persistent Chrome login profile, Gemini image downloads, ONNX models). This split predates the binary rename and hasn't been cleaned up — real, not a typo.
+
+## Setup / auth
+
+- **Social platforms** (instagram, linkedin, x, tiktok, gemini): `monoagentcli login <platform>` opens a real Chrome window, waits for manual login, saves cookies (30-day expiry). `monoagentcli login status` / `monoagentcli logout [platform|--all]`.
+  - `gemini` needs **no API key** — browser automation against gemini.google.com after login. `monoagentcli login gemini` unlocks `gemini.generate_text` / `gemini.generate_image` / `gemini.chat_session` nodes for free.
+- **API/OAuth services** (Slack, GitHub, Google Sheets, Notion, Stripe, etc.): `monoagentcli connect <platform>`, `monoagentcli connect list --all`, `monoagentcli connect test <id>`, `monoagentcli connect refresh <id>`.
+- A Chrome extension bridge listens on `:9222`; if connected it's preferred over launching Chromium directly. Only one process (CLI or the Wails desktop app, product name "MonoAgent") should hold it at a time.
+- Multiple isolated identities: `monoagentcli profile list|create <name>|switch <name-or-id>|current` — sessions/workflows/actions/connections are all scoped per-profile.
+
+## Command tree
+
+```
+monoagentcli login <platform> [--timeout 3m]        # instagram|linkedin|x|tiktok|telegram|email|gemini
+monoagentcli login status
+monoagentcli logout [platform] [--all]
+
+monoagentcli search <platform> --keyword TEXT [--max 50] [--timeout 10m]
+monoagentcli message <platform> <username> --text TEXT [--timeout 10m]
+monoagentcli comment <platform> <post-url...> --text TEXT [--timeout 10m]
+
+monoagentcli run [action-id] [--file PATH] [--queue] [--watch --interval 30s] [--timeout 10m] [--param k=v ...]
+monoagentcli action list|get <id>|create --type --platform [--keyword] [--message]|import --file PATH
+monoagentcli action pause|resume|delete <id>
+monoagentcli action targets <id>
+monoagentcli action template capture <url> [--headless] [--wait 8] [--out PATH]
+monoagentcli action template install <file>          # writes ~/.monoes/actions/<platform>/<type>.json
+monoagentcli action template list
+
+monoagentcli crawl <url> [--headless] [--wait 8]     # standalone HTML capture for ActionDef authoring
+
+monoagentcli workflow list [--json]
+monoagentcli workflow get <id>
+monoagentcli workflow create <name> [--description] [--active]
+monoagentcli workflow import [--file PATH] [--overwrite]   # reads stdin if no --file
+monoagentcli workflow export <id> [--output PATH]
+monoagentcli workflow run <id>                       # positional — NOT --id
+monoagentcli workflow activate <id> / deactivate <id>
+monoagentcli workflow delete <id> [--force]
+monoagentcli workflow executions <workflow-id> [--limit 20] [--json]
+monoagentcli workflow migrate                        # SQLite store -> ~/.monoes/workflows/*.json
+monoagentcli workflow node add <workflow-id> --type --name [--config json] [--x] [--y]
+monoagentcli workflow node list <workflow-id>
+monoagentcli workflow node set <workflow-id> <node-id> [--config] [--name] [--x] [--y]
+monoagentcli workflow node remove <workflow-id> <node-id>
+monoagentcli workflow connect <workflow-id> --from nodeID[:handle] --to nodeID[:handle]
+monoagentcli workflow disconnect <workflow-id> <connection-id>
+
+monoagentcli node list [--filter STRING]             # control.* data.* http.* db.* comm.* ai.* image.* instagram.* ...
+monoagentcli node run <node-type> [--config json] [--input json] [--output pretty|json|jsonl] [--credential id-or-platform]
+
+monoagentcli connect <platform>
+monoagentcli connect list [--platform] [--json] [--all]
+monoagentcli connect test <id> / remove <id> / refresh <id> [--timeout 5m]
+
+monoagentcli people list [-p platform] [-n 50] / get <id> / delete <id> / import --file --platform
+monoagentcli list ls / create --name / show <id> / delete <id> / add-item <list-id> --username --platform
+monoagentcli template list / get <id> / create --name --body [--subject] / delete <id>
+monoagentcli config list / get <name> / set <name> <value> / delete <name>
+monoagentcli schedule list / add <action-id> --cron "..." [--start-date] [--end-date] / remove <action-id>
+
+monoagentcli export [--output-dir PATH]              # always writes people_export.json + actions_export.json
+monoagentcli status [--json]
+monoagentcli version
+monoagentcli update                                  # self-update from monoes/mono-agent GitHub releases
+monoagentcli init [--claude]                         # installs action-template-generator skill into ~/.claude/skills/
+monoagentcli profile list / create <name> / switch <name-or-id> / current
+
+monoagentcli ref commands|nodes|node <type>|workflow|expressions|examples|crawling   # offline docs, no side effects
+```
+
+## Examples
+
+```bash
+# One-time login, then a quick search
+monoagentcli login instagram
+monoagentcli search instagram --keyword "golang developer" --max 50
+
+# One-off DM / comment
+monoagentcli message instagram johndoe --text "hello"
+monoagentcli comment instagram https://instagram.com/p/xyz --text "nice!"
+
+# Free-tier AI node via Gemini browser automation (no API key)
+monoagentcli login gemini
+monoagentcli node run gemini.generate_text --config '{"prompt":"Summarize AI news today"}'
+
+# Workflow lifecycle
+monoagentcli workflow list
+monoagentcli workflow run <workflow-id>
+monoagentcli workflow activate <workflow-id>     # registers cron/webhook triggers for this process's lifetime
+
+# Connect an API service and inspect connections
+monoagentcli connect github
+monoagentcli connect list --all
+
+# When unsure, check the CLI's own docs instead of guessing
+monoagentcli ref commands
+monoagentcli ref node gemini.generate_image
+```
+
+## Gotchas (verified against source and the live GitHub release)
+
+- Binary name is `monoagentcli` — not `monoes`, not `monoagent`. The repo's own README.md still shows `monoes` in its examples (pre-rename); the Makefile, `root.go`'s Cobra `Use:` field, `release.yml`, and the actual assets on the latest GitHub release (`v0.10.3`) all confirm `monoagentcli`.
+- Prebuilt binaries exist — no need to build from source if a release matches your platform:
+  ```bash
+  curl -fsSL https://github.com/monoes/mono-agent/releases/latest/download/monoagentcli-darwin-arm64 -o monoagentcli
+  chmod +x monoagentcli && sudo mv monoagentcli /usr/local/bin/
+  ```
+  (Also available: `-darwin-amd64`, `-linux-amd64`, `-windows-amd64.exe`. Desktop app "MonoAgent" ships separately as `MonoAgent-darwin-arm64.zip` / `-linux-amd64.tar.gz` / `-windows-amd64.exe`.)
+- `workflow run/get/export`, `workflow node add/connect`, and `node run` take **positional** arguments (`workflow run <id>`, `node run <node-type>`). The README's "CLI Reference" section shows `--id`/`--type`/`--from`/`--to` flag forms that don't match the actual Cobra signatures — don't copy that section literally.
+- There is **no `schedule run` daemon command**, despite `monoagentcli ref workflow`/`ref examples` referencing one. Cron execution only happens via `trigger.schedule` nodes inside a `workflow activate`d workflow, which only fires while that process is alive.
+- `export` always writes `people_export.json` + `actions_export.json` — there's no `--format csv`.
+- `people import` requires **both** `--file` and `--platform`.
+- No standalone always-on daemon ships with the CLI; `run --watch --interval` (polls pending actions) and `workflow activate` (in-process scheduler) are the closest things — the Wails desktop app ("MonoAgent") is the real long-running host in normal use.
+- `monoagentcli update` self-updates from the latest `monoes/mono-agent` GitHub release — prefer it over re-running the install command.
+- `monoagentcli ref commands`' built-in flag/usage docs (the hardcoded `cliDocs` table in `ref.go`) are hand-maintained and stale for several commands — they describe flags that don't exist on the real Cobra definitions (e.g. claims `run` takes `--platform`/`--list`/`--text`, `search` takes `--limit`/`--output`, `message`/`comment` take `--list`/`--delay`, `people` has `add`/`export`/`remove` subcommands instead of the real `list`/`get`/`delete`/`import`, `list create` takes a positional name instead of `--name`, and `export` supports `--format csv`). Don't rely on `ref commands` for exact flag names — use `--help` on the actual subcommand instead. `ref nodes` / `ref node <type>` is a separate, accurate code path.
+
+## See Also
+
+- `/monoes:install` — install mono-agent if the `monoagentcli` binary isn't found
+- `../mono-agent/README.md` — mostly accurate for feature scope, but stale on the binary name and some flag shapes; verify against `cmd/monoagentcli/root.go` / `ref.go` if something looks off

package/.claude/commands/monoes/monoclip.md

@@ -0,0 +1,64 @@
+---
+name: monoes:monoclip
+description: Drive mono-clip's CLI sidecar (`mclip`) — read/write clipboard history and folders, or run its MCP stdio server
+---
+
+# monoes monoclip
+
+Interact with **mono-clip** — a macOS menu-bar clipboard manager (Tauri + SvelteKit, app bundle `MonoClip.app`). The GUI app itself has **no CLI flags, deep-link scheme, or HTTP/IPC surface** — the only scriptable surface is a separate sidecar binary, **`mclip`**, that talks directly to the same SQLite database the GUI reads/writes (`~/.monoclip/monoclip.db`). `mclip` works whether or not the GUI is currently running, as long as the app has been launched at least once (so the DB exists).
+
+Not installed, or `mclip` not on PATH? Run `/monoes:install` first — after installing `mono-clip.app`, launch it once (its own startup hook symlinks `mclip` into `~/.local/bin/mclip`), then make sure `~/.local/bin` is on `PATH`.
+
+## Command tree
+
+```
+mclip list [--folder NAME] [--search QUERY] [--limit N]
+mclip add "text" [--folder NAME]
+mclip get <id>                     # prints raw content — pipeable, e.g. mclip get 7 | pbcopy
+mclip remove <id>
+mclip pin <id> / unpin <id>
+
+mclip folder list
+mclip folder add "Name" [--icon ICON --color COLOR]
+mclip folder remove "Name"
+
+mclip context                       # prints a canned AI-context block (for pasting into CLAUDE.md/.cursorrules)
+mclip mcp                           # starts a JSON-RPC-over-stdio MCP server (see below)
+```
+
+## Examples
+
+```bash
+# Save something to a folder, then recall it
+mclip add "ssh user@example.com" --folder "Snippets"
+mclip list --folder "Snippets"
+
+# Pull a clip straight into the system clipboard
+mclip get 12 | pbcopy
+
+# Pin an important clip so auto-cleanup never removes it
+mclip pin 12
+
+# Organize folders
+mclip folder add "Work" --icon "briefcase" --color "#4287f5"
+mclip folder list
+```
+
+## MCP server mode
+
+`mclip mcp` starts a hand-rolled JSON-RPC-over-stdio MCP server exposing: `list_clips`, `add_clip`, `get_clip`, `remove_clip`, `pin_clip`, `list_folders`, `create_folder`, `delete_folder`. To use it from an MCP client (e.g. Claude Desktop), register it as a stdio server with `"command": "mclip", "args": ["mcp"]` in that client's config — this is a separate integration path from shelling out to individual `mclip` subcommands above, and mostly relevant outside Claude Code itself (which already has direct Bash access to `mclip`).
+
+## What this app is (for context, not directly scriptable)
+
+Menu-bar-only clipboard manager: background watcher (polls every 300ms), auto-detects content type (text/url/email/color/code), multi-folder organization with per-folder global shortcuts (press hotkey → captures selection straight into that folder), a master shortcut (`⌘⇧V` default) toggling a floating panel, pin/soft-delete, image & file-path capture with thumbnails, search, configurable auto-cleanup retention (always keeps the last 10 Inbox items), local-only SQLite storage, no network/telemetry, self-update.
+
+## Gotchas (verified against source)
+
+- There is genuinely no way to control the running GUI app from outside it — no deep link (`monoclip://...`), no HTTP/Unix-socket API (that's on the project's own TODO list, not implemented), no `tauri-plugin-cli`. Don't invent flags for the main `monoclip`/`MonoClip.app` binary — everything scriptable lives in `mclip`.
+- `mclip` requires the app to have been launched at least once (so `~/.monoclip/monoclip.db` exists) — a fresh install with the GUI never opened will fail.
+- If `mclip` isn't found after install, it's almost always a `PATH` issue — the symlink at `~/.local/bin/mclip` is created automatically on first GUI launch (or via the GUI's Settings → "Install mclip CLI"), but `~/.local/bin` isn't always on `PATH` by default.
+
+## See Also
+
+- `/monoes:install` — install mono-clip if `MonoClip.app` / `mclip` aren't found
+- `../mono-clip/README.md` — Homebrew cask / build-from-source instructions

package/.claude/commands/monoes/monotask.md

@@ -0,0 +1,137 @@
+---
+name: monoes:monotask
+description: Drive the monotask CLI — a local-first, P2P kanban board (boards/columns/cards, spaces, GitHub/Linear/mail sync)
+---
+
+# monoes monotask
+
+Interact with **monotask** — a Rust CLI (binary `monotask`, source at `../monotask`) for a local-first, P2P kanban board. Not installed? Run `/monoes:install` first.
+
+Given the user's request in `$ARGUMENTS`, pick the matching command(s) below and run them via Bash. When uncertain, run `monotask ai-help --json` — it introspects the live CLI definition, so it never drifts from the real command surface (unlike hand-written docs).
+
+## Model
+
+- Local-first: every board/column/card lives as an Automerge CRDT doc in SQLite in the OS data dir (Linux: `~/.local/share/monotask/`; **macOS: `~/Library/Application Support/monotask/`**; Windows: `%APPDATA%\monotask\`) — override with global `--data-dir`.
+- Identity is an Ed25519 keypair, auto-generated on first use (or `profile import-ssh-key`).
+- **Boards must belong to a Space** — `board create` requires `--space <SPACE_ID>`, so `space create` comes first.
+- The CLI does **not** sync between users by itself — that needs the `monotask sync` daemon or the desktop (Tauri) app running.
+- IDs are UUID v4 for everything except: Attachment IDs (6-char hex, `img:<id>`) and the human-readable card number (`<prefix>-<seq>`, display-only, not a valid ID for commands).
+- Pass `--json` on any command for structured output — recommended when scripting (e.g. piping through `jq`).
+
+## Command tree
+
+```
+monotask [--data-dir PATH] init | version | ai-help [--json] [--section commands|schemas|workflows|gotchas]
+
+monotask board create <title> --space SPACE_ID [--json]
+monotask board list|rename <id> <new-title>|delete <id> --space SPACE_ID|schema <id>|undo <id>|redo <id>
+
+monotask column create|list|rename|delete <board-id> [...]
+
+monotask card create <board-id> <col-id> <title> [--field NAME=VALUE ...] [--json]
+monotask card list <board-id> [--col ID] [--label L] [--where "FIELD_REF(=|!=|>|>=|<|<=|~)VALUE" ...]
+monotask card view|rename|delete|archive <board-id> <card-id>
+monotask card copy|move <board-id> <card-id> <target-col-id>
+monotask card set-description|set-cover|set-due-date <board-id> <card-id> <value>
+monotask card set-priority <board-id> <card-id> low|medium|high|none      # legacy string priority
+monotask card set-impact|set-effort <board-id> <card-id> 0-10             # priority = floor((impact+10-effort)/2)
+monotask card set-direct-priority <board-id> <card-id> [0-10] [--clear]
+monotask card clear-priority <board-id> <card-id>                        # clears impact+effort+direct_priority
+monotask card set-assignee <board-id> <card-id> <pubkey-hex|none>
+monotask card attach-image <board-id> <card-id> <file>                   # png/jpg/jpeg/gif/webp/svg
+monotask card list-attachments|save-attachment <board-id> <card-id> [<attachment-id>]
+monotask card mentions <board-id> <card-id>
+monotask card field-set <board-id> <card-id> <field-ref> <value>
+monotask card field-get|field-clear <board-id> <card-id> <field-ref>
+monotask card field-list <board-id> <card-id>
+monotask card upsert <board-id> <col-id> <title> --match-field REF --match-value V [--field NAME=V ...]
+monotask card label add|remove|list <board-id> <card-id> [label]
+monotask card comment add|list|delete|edit <board-id> <card-id> [...]
+monotask card subtask add <parent-board> <parent-card> <child-board> <col-id> <title> | list <board-id> <card-id>
+monotask card link add|list|remove <board-id> <card-id> <target-board> <target-card>
+monotask card prerequisite add|list|remove <board-id> <card-id> <prereq-board> <prereq-card>
+
+monotask checklist add <board-id> <card-id> <title>
+monotask checklist item-add|item-check|item-uncheck|item-delete <board-id> <card-id> <checklist-id> [item-id] [text]
+monotask checklist delete <board-id> <card-id> <checklist-id>
+
+monotask field create <board-id> <name> [--field-type text|number|date|select|multi_select|checkbox] [--option V ...] [--default-value V] [--auto-apply]
+monotask field list <board-id>
+monotask field rename <board-id> <field-ref> <new-name>
+monotask field delete|backfill <board-id> <field-ref>
+monotask field update <board-id> <field-ref> [--default-value V] [--auto-apply true|false]
+
+monotask space create <name>
+monotask space list|info <id>
+monotask space invite generate <id> | export <id> <output.space> | revoke <id>
+monotask space join <token-or-file>
+monotask space boards add|remove|list <space-id> [<board-id>]
+monotask space members list <space-id> | kick <space-id> <pubkey>
+
+monotask profile show | set-name <name> | set-avatar <path> | import-ssh-key [path]
+
+monotask github connect [token]        # prefer: echo "$TOKEN" | monotask github connect
+monotask github status | link <board-id> <owner> <repo> --done-col COL | unlink <board-id> | sync <board-id>
+
+monotask linear connect [token]        # prefer stdin
+monotask linear status | teams | projects <team-id>
+monotask linear link <board-id> --team ID --project ID [--done-col COL] | unlink <board-id> | sync <board-id>
+
+monotask mail gmail-connect --client-id ID [--no-wait]
+monotask mail outlook-connect --client-id ID [--tenant-id common] [--no-wait]
+monotask mail oauth-complete --provider gmail|outlook --code CODE     # finishes a --no-wait flow
+monotask mail status | disconnect gmail|outlook
+monotask mail link <board-id> [--provider both|gmail|outlook|imap] [--inbox-col COL] [--keep-last 2] [...]
+monotask mail imap-connect --host H --username U [--port 993] [--password P] [--folder INBOX]
+monotask mail imap-status | imap-disconnect | unlink <board-id> | sync <board-id>
+
+monotask app open <url>                # monotask://board/<id> or monotask://board/<id>/card/<id>
+
+monotask chat send <space-id> <text> | list <space-id> [--limit 50]
+
+monotask sync [--detach] [--stop] [--status] [--port 0] [--peer /ip4/.../tcp/... ...]
+```
+
+## Examples
+
+```bash
+# First-time setup: identity, space, board, column, card
+monotask profile set-name "Ada"
+SPACE=$(monotask space create "Personal" --json | jq -r .id)
+BOARD=$(monotask board create "Sprint 1" --space $SPACE --json | jq -r .id)
+TODO=$(monotask column create $BOARD "Todo" --json | jq -r .id)
+monotask card create $BOARD $TODO "Write onboarding docs" --json
+
+# Triage: list, prioritize, move
+monotask card list $BOARD --col $TODO --json
+monotask card set-impact $BOARD $CARD 8
+monotask card set-effort $BOARD $CARD 3
+monotask card move $BOARD $CARD $DOING_COL
+
+# Invite a teammate into a shared space
+monotask space invite export $SPACE team-invite.space
+# teammate runs: monotask space join team-invite.space
+
+# Wire up GitHub Issues sync
+echo "$GITHUB_TOKEN" | monotask github connect --json
+monotask github link $BOARD myorg myrepo --done-col $DONE_COL --json
+monotask github sync $BOARD --json
+
+# When unsure, ask the CLI itself
+monotask ai-help --section commands
+```
+
+## Gotchas (verified against source)
+
+- The clap `Parser` name is `monotaskcli` and `ai-help`'s own examples print that name — but invoke it as `monotask`. **This is only automatic for a source build that renames the binary during install** (per the tool's own README) — the Homebrew formula installs the raw binary as `monotaskcli` verbatim and does not create a `monotask` alias, and won't even auto-link it into `PATH` if the `monotask` cask (desktop app) is also installed. If `command -v monotask` comes up empty after `brew install monoes/tap/monotask`, symlink it manually: `ln -sf "$(brew --cellar)"/monotask/*/bin/monotaskcli "$(brew --prefix)/bin/monotask"`.
+- Exit codes: `0` success, `1` generic error, `2` not_found, `3` invalid_input, `4` io_error. **With `--json`, errors print to stdout** as `{"ok":false,"error":"...","kind":"..."}`; without it, errors go to stderr as plain text.
+- `card create` currently stamps a placeholder `"aaaa"` card-number prefix — known incomplete, per the tool's own gotchas.
+- `card view --json`'s `number` field is `{"prefix":..,"seq":..}`, not the display string.
+- `field backfill` only fills cards with **no** existing value — never overwrites a stale one.
+- Pipe secrets via stdin (`echo "$TOKEN" | monotask github connect`), not as a positional arg — avoids shell-history/`ps` exposure. Same for `linear connect` and `mail imap-connect --password`.
+- Real cross-machine sync requires `monotask sync` (a daemon, not automatic) or the desktop app — the CLI alone only mutates the local CRDT store.
+
+## See Also
+
+- `/monoes:install` — install monotask if the `monotask` binary isn't found
+- `../monotask/README.md`, `crates/monotask-cli/src/main.rs` — source of truth if `ai-help` output looks incomplete