@fluxvita/jovida-cli 0.0.1 → 0.0.2

package/README.md

@@ -15,22 +15,21 @@ The **Jovida Daily CLI** — capture and manage your **Jovida Daily** todos from
 
 ## Setup
 
-**1. Install the `jovida` command** so it is on your `PATH`. Pre-release — build from source:
+**1. Install the `jovida` command** so it is on your `PATH`:
 
 ```bash
-git clone https://github.com/FluxVita/jovida-cli && cd jovida-cli
-npm install && npm run build && npm link
+npm i -g @fluxvita/jovida-cli
 ```
 
-(When published: `npm i -g @fluxvita/jovida-cli`.) Verify with `jovida --version`.
+(Or build from source: `git clone https://github.com/FluxVita/jovida-cli && cd jovida-cli && npm install && npm run build && npm link`.) Verify with `jovida --version`.
 
 **2. Install the skill** so your AI knows when/how to use the CLI:
 
 ```bash
-npx skills add FluxVita/jovida-cli
+jovida skill install
 ```
 
-Installs `SKILL.md` into detected agents (`~/.codex/skills/jovida-cli/`, `~/.claude/skills/jovida-cli/`, …). Or paste this repo's URL to your agent and ask it to add the skill.
+Copies the bundled `SKILL.md` (kept in lockstep with the CLI version) into your detected agents (`~/.codex/skills/jovida-cli/`, `~/.claude/skills/jovida-cli/`). Add `--all` to install for all known agents even if not detected. (Alternative: `npx skills add FluxVita/jovida-cli`.)
 
 **3. Sign in — this is the user's step (interactive; the agent cannot do it):**
 
@@ -42,16 +41,16 @@ Verify with `jovida whoami`. From here the CLI stays signed in (auto-renews) unt
 
 ## Updating
 
-- **Installed from npm** (`@fluxvita/jovida-cli`): `npm i -g @fluxvita/jovida-cli@latest`.
-- **Installed from source** (current pre-release): in the cloned repo run `git pull && npm install && npm run build`. The `npm link` symlink persists, so the rebuilt CLI takes effect immediately — no need to re-link.
-- **The skill updates separately:** re-run `npx skills add FluxVita/jovida-cli` to refresh `SKILL.md` in your agents. Do this whenever the CLI's commands change, so the agent's knowledge stays in sync.
+- **CLI**: `npm i -g @fluxvita/jovida-cli@latest`. (In an interactive terminal the CLI also notifies you when a newer version exists.)
+- **Skill**: run `jovida skill update` after updating the CLI — it re-copies the bundled `SKILL.md`, so the agent's knowledge stays in lockstep with the installed CLI version (same npm package, no drift).
+- **From source**: in the cloned repo run `git pull && npm install && npm run build` (the `npm link` symlink persists), then `jovida skill update`.
 
 ## Quickstart
 
 ```bash
 jovida create "submit the report by Friday 6pm" --when 2026-06-12T18:00:00+08:00
 jovida list
-jovida show <entry_id>
+jovida view <entry_id>
 jovida complete <entry_id>
 ```
 
@@ -60,7 +59,7 @@ jovida complete <entry_id>
 
 ## Commands
 
-`create` · `list` · `show` · `update` · `complete` · `delete` · `login` · `logout` · `whoami`.
+`create` · `list` · `view` · `update` · `complete` · `reopen` · `delete` · `login` · `logout` · `whoami`.
 Run `jovida help` for usage, or see [`SKILL.md`](./SKILL.md) for flags & field conventions.
 
 ## Auth

package/README.zh-CN.md

@@ -15,22 +15,21 @@
 
 ## 安装
 
-**1. 安装 `jovida` 命令**,让它在 `PATH` 上。预发布——暂时从源码构建:
+**1. 安装 `jovida` 命令**,让它在 `PATH` 上:
 
 ```bash
-git clone https://github.com/FluxVita/jovida-cli && cd jovida-cli
-npm install && npm run build && npm link
+npm i -g @fluxvita/jovida-cli
 ```
 
-(发布后:`npm i -g @fluxvita/jovida-cli`。)用 `jovida --version` 验证。
+(或从源码构建:`git clone https://github.com/FluxVita/jovida-cli && cd jovida-cli && npm install && npm run build && npm link`。)用 `jovida --version` 验证。
 
 **2. 安装 skill**,让 AI 知道何时/如何用 CLI:
 
 ```bash
-npx skills add FluxVita/jovida-cli
+jovida skill install
 ```
 
-把 `SKILL.md` 装进探测到的 agent(`~/.codex/skills/jovida-cli/`、`~/.claude/skills/jovida-cli/`……)。或把本仓库 URL 贴给 agent、让它自行安装。
+把随包的 `SKILL.md`(与 CLI 同版本)拷进探测到的 agent(`~/.codex/skills/jovida-cli/`、`~/.claude/skills/jovida-cli/`)。加 `--all` 可对所有已知 agent 安装(即使未探测到)。(备选:`npx skills add FluxVita/jovida-cli`。)
 
 **3. 登录 —— 这是用户的步骤(交互式;agent 做不了):**
 
@@ -42,16 +41,16 @@ jovida login          # 打开浏览器;登录并点「允许」授权该 CLI
 
 ## 更新
 
-- **npm 安装**(`@fluxvita/jovida-cli`):`npm i -g @fluxvita/jovida-cli@latest`。
-- **源码安装**(当前预发布):在克隆的仓库里运行 `git pull && npm install && npm run build`。`npm link` 的软链常驻,重新 build 即刻生效——无需重新 link。
-- **skill 单独更新:** 重跑 `npx skills add FluxVita/jovida-cli` 刷新 agent 里的 `SKILL.md`。CLI 命令有变化时记得做,让 agent 的认知保持同步。
+- **CLI**:`npm i -g @fluxvita/jovida-cli@latest`。(交互式终端里,CLI 还会在有新版时提示你。)
+- **skill**:更新完 CLI 后跑 `jovida skill update`——它重拷随包的 `SKILL.md`,让 agent 认知与已装 CLI 版本同步(同一 npm 包,不漂移)。
+- **源码**:在克隆的仓库里 `git pull && npm install && npm run build`(`npm link` 软链常驻),再 `jovida skill update`。
 
 ## 快速开始
 
 ```bash
 jovida create "周五下午6点前交报告" --when 2026-06-12T18:00:00+08:00
 jovida list
-jovida show <entry_id>
+jovida view <entry_id>
 jovida complete <entry_id>
 ```
 
@@ -60,7 +59,7 @@ jovida complete <entry_id>
 
 ## 命令
 
-`create` · `list` · `show` · `update` · `complete` · `delete` · `login` · `logout` · `whoami`。
+`create` · `list` · `view` · `update` · `complete` · `reopen` · `delete` · `login` · `logout` · `whoami`。
 `jovida help` 查看用法,或见 [`SKILL.md`](./SKILL.md) 了解参数与字段约定。
 
 ## 鉴权

package/SKILL.md

@@ -1,94 +1,66 @@
 ---
 name: jovida-cli
-description: Capture and manage the user's Jovida Daily todos from the command line via the `jovida` CLI — create, list, update, complete, or delete tasks (changes apply immediately, no confirmation step). Use when the conversation surfaces action items, follow-ups, or commitments, or when the user asks to track / remember / organize a task.
+description: Capture and manage the user's Jovida Daily todos via the `jovida` CLI — create, list, update, complete, delete (changes apply immediately, no confirmation, no undo). Use when the conversation surfaces action items, follow-ups, or commitments, or when the user asks to track / remember / organize a task.
 allowed-tools: Bash(jovida:*)
 ---
 
 # Jovida Daily Todo (CLI)
 
-Help the user capture and manage their **Jovida Daily** todos by shelling out to the `jovida` command-line tool. Run `jovida` commands through your shell — the CLI is the interface to the user's account, and changes sync to their other Jovida devices.
+Help the user capture and manage their **Jovida Daily** todos by shelling out to the `jovida` command. The CLI is the interface to the user's account; changes sync to their other Jovida devices.
 
-> **If the `jovida` command isn't found**, the Jovida Daily CLI isn't installed here — tell the user to install it (see the jovida-cli README); don't pretend you tracked anything.
-> **Sign-in is required — and it is the user's step.** No anonymous mode; nothing works until the user runs `jovida login` (interactive browser sign-in — you **cannot** do it for them, and **must not** skip it). Be proactive: if you're not sure they're signed in, run `jovida whoami` first. If `whoami` or any command exits `2` (`NOT_SIGNED_IN`), **stop, tell the user to run `jovida login`, and wait until they confirm before retrying** — don't silently drop the task or claim you can't help.
+This skill teaches the *semantics* — when to act, which command, how to compose them. For the **exact flags** of any command, run `jovida <command> --help` (e.g. `jovida create --help`); that is the source of truth and stays in lockstep with the installed version. Don't rely on a flag this skill doesn't name without checking `--help` first.
 
-## Core mental model — read this first
-
-Writes apply **immediately**. There is **no proposal or confirmation step**: when you run `jovida create / update / complete / delete`, it takes effect on the user's account at once and syncs to their devices. So:
-
-- Say "I've **created / completed / deleted** …" — never "I've proposed …".
-- Because it's immediate, only run a write when the user **clearly wants that change**. When unsure, ask first (see *Clarify*).
-- **There is no undo** from the CLI — be especially careful with `delete` and `complete`.
-
-## When to use
-
-Act when the context holds a real, actionable item:
-- an explicit action item, follow-up, or commitment ("I need to…", "remember to…", "before launch, check…");
-- the user asks to track / remember / add / organize a task, or to mark one done / remove it.
+> **If `jovida` isn't found**, the CLI isn't installed here — tell the user to install it (see the jovida-cli README); don't pretend you tracked anything.
+> **Sign-in is required, and it's the user's step.** No anonymous mode. You **cannot** sign in for them (interactive browser) and **must not** skip it. If unsure they're signed in, run `jovida whoami` first. If `whoami` or any command exits `2` (`NOT_SIGNED_IN`), **stop, ask the user to run `jovida login`, and wait for their confirmation before retrying** — don't silently drop the task or claim you can't help.
 
-Do **not** over-capture:
-- ignore hypotheticals, brainstorming, and things already done;
-- when unsure whether something is a real task, ask rather than writing noise.
-
-## Clarify before writing
-
-A write changes the user's data immediately — and `delete` / `complete` can't be undone here — so a vague or wrong call is costly. Before writing, make sure the essentials are concrete: *what* the task is, and — when time is implied — *which day / deadline / reminder time*. If the user's message leaves these genuinely ambiguous, **ask one brief question first**; don't fill the gaps with guesses.
-
-- "remind me about the thing tomorrow" → ask *what* the thing is, and roughly *when*, before writing.
-- "set a reminder" with no time → ask for the time.
-- Don't over-correct: when details are clear ("submit the report by Friday 6pm"), just act.
+## Core mental model — read this first
 
-## Commands
+- **Writes apply immediately.** There is no proposal/confirmation step: `create / update / complete / delete` take effect on the user's account at once and sync to their devices. Say "I've created / completed / deleted …", never "I've proposed …". `complete` is reversible (`reopen`), but **`delete` is permanent — no undo** — so be especially careful with it.
+- **Only write when the user clearly wants the change.** When the intent or the essentials (what the task is; which day / deadline / reminder time) are genuinely vague, **ask one short question first** — don't fill gaps with guesses. ("Remind me about the thing tomorrow" → ask *what* and roughly *when* before writing.) But don't over-correct: when it's clear ("submit the report by Friday 6pm"), just act.
+- **Read before you change.** `update / complete / delete` need a **real `entry_id`** — get it from `jovida list` or `jovida view` and parse the JSON. **Never guess an id.**
+- **Output is machine-readable.** Run non-interactively, the CLI prints **JSON on stdout** (parse it); errors go to **stderr** as `{"error":{"code","message"}}` with a non-zero exit code (`2` not signed in · `3` backend/network · `4` not found · `1` usage). `--json` forces JSON.
 
-You invoke these through your shell. When run non-interactively (as you do), output is **JSON on stdout** — parse it. Errors go to **stderr** as `{"error":{"code","message"}}` with a **non-zero exit code** (`2` = not signed in, `3` = backend/network, `4` = entry not found, `1` = usage). You can pass `--json` to force JSON.
+## When to use — and when not
 
-Run `jovida help` to confirm it's available and see the current usage before relying on a flag.
+Act when the context holds a **real, actionable** item: an explicit action item, follow-up, or commitment ("I need to…", "remember to…", "before launch, check…"), or when the user asks to track / remember / organize something, or to mark one done / remove it.
 
-**Read** (understand state, and get the real `entry_id` before any update/complete/delete):
-- `jovida list [--scope today|upcoming|recent|range|all] [--status pending|completed|all] [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N]`
-  → `{ "todos": [ { "entry_id", "title", "when", "priority", "status", "category" } ] }`. A scoped view (defaults: `scope=today`, `status=pending`, `limit=20`), **not** a search.
-- `jovida show <entry_id>` → the full todo (description, subtasks, remind_at, hint, …).
+Don't over-capture: ignore hypotheticals, brainstorming, and things already done. When unsure whether something is a genuine task, ask rather than writing noise.
 
-**Write** (immediate):
-- `jovida create "<title>" [--when <ISO>] [--priority none|low|medium|high] [--remind <ISO> …] [--category <s>] [--desc <s>] [--subtask "<title>" …] [--hint <s>]`
-  → `{ "entry_id", "status": "created" }`. **One todo per call** — run it again for more.
-- **Recurring**: add `--repeat day|week|month|year` (with `--when` as the **first occurrence**) → creates a recurring series, returns `{ "recurring_id", "status": "created" }`. Tune with `--every N` (e.g. every 2 weeks), `--weekdays mon,wed,fri` (weekly), `--day-of-month N` (monthly/yearly), `--month-of-year N` (yearly), `--until YYYY-MM-DD` (end). Occurrences then show up in `list` like normal todos.
-- `jovida update <entry_id> [--title <s>] [--when <ISO>] [--priority …] [--remind <ISO> …] [--category <s>] [--desc <s>] [--subtask "<title>" …] [--hint <s>]`
-  → `{ "entry_id", "status": "updated" }`.
-- `jovida complete <entry_id> [<entry_id> ...]` → `{ "entry_ids", "status": "completed" }`.
-- `jovida delete <entry_id> [<entry_id> …]` → `{ "entry_ids": […], "status": "deleted" }`. Pass several ids in one call.
+## Concepts
 
-Quote the title and any value containing spaces. **Keep `--title` / `--desc` to single-line plain text** — passing newlines or shell metacharacters as arguments is fragile (they get mangled). For a long note, keep it short and single-line rather than embedding markdown/newlines.
+These shape *what you put in a command* — internalize them; flag spelling lives in `--help`.
 
-**Never put a token in a command** (it lands in shell history / process listings). Signing in is the user's step (interactive browser) — see the not-signed-in note above.
+- **A todo's time has two granularities (one `--when`).** A bare **date** (`2026-06-05`) means it *belongs to that day*, no hard deadline; a **datetime** (`2026-06-05T18:00:00+08:00`) is a precise **deadline**. Give whichever you actually know. Don't split "do it Wed, due Fri" — if it's due Friday, it's a Friday todo.
+- **Reminders are separate from the time, and a reminder ≠ a deadline.** A reminder is *when to nudge*; each must be at or before the todo's time. "Remind me about X tomorrow" = a todo tomorrow with a reminder tomorrow morning — it does **not** make X *due* at that moment. A todo can carry several reminders.
+- **Recurring = a series, not a todo.** Creating with a repeat rule makes a recurring **series** (you get a `recurring_id`); its individual occurrences then appear in `list` like normal todos, each with its own `entry_id` (and a `recurring_id` linking back). Use a series for a genuinely repeating commitment ("standup every weekday"), not for a handful of distinct dates — make those individual todos.
+- **The rest:** **subtasks** break one task into steps; **category** is a grouping label; **priority** is none/low/medium/high; **hint** is an optional one-line nudge — add it only when it genuinely helps.
 
-## Field conventions
+## Commands at a glance
 
-- **`--when`** — the todo's time, **one flag, two granularities** (ISO 8601):
-  - a **date** (`2026-06-05`) → belongs to *that day*, no hard deadline;
-  - a **datetime** (`2026-06-05T18:00:00+08:00`) → a precise **deadline**.
-  - Give whichever you actually know. Don't split "do it Wed but due Fri" — if it's due Friday, it's a Friday todo.
-- **`--priority`**: `none` | `low` | `medium` | `high`.
-- **`--category`**: a grouping label. **`--desc`**: a free-text note.
-- **`--subtask "<title>"`** (repeatable): break a task into steps.
-- **`--remind <ISO>`** (repeatable) — when to alert the user; **separate from `--when`**:
-  - each must be **at or before** the todo's time (before the deadline, or any time on a date-only todo's day);
-  - **reminding ≠ deadline**: "remind me about X tomorrow" → `--when "<tomorrow>" --remind "<tomorrow>T09:00:00+08:00"` (it does *not* make X due);
-  - if you give only `--remind` and no `--when`, the todo lands on the **latest** reminder's day.
-- **`--hint <s>`** — an *optional* one-line nudge shown under the todo. Off by default; add only when it genuinely helps (≤ ~20 chars, never restate the title).
-- Recurring tasks are **not supported in the CLI yet** — don't try to express them; create individual todos or tell the user.
+Semantics below; exact flags via `jovida <cmd> --help`.
 
-## Read before you write
+- **`jovida list`** — a scoped *view* of todos (defaults to today's pending), **not a search**; widen with scope/status/range. Your go-to for finding the `entry_id` you need. Add `--full` to get every field (description, subtasks, reminders) in the same call — one round-trip instead of `list` then `view`.
+- **`jovida view <entry_id>`** — full detail of one todo (description, subtasks, reminders, …).
+- **`jovida create "<title>"`** — add one todo (**one per call**; run again for more). Add a repeat rule to create a recurring series instead.
+- **`jovida update <entry_id>`** — change fields of an existing todo; **only the fields you pass change**. `--remind` / `--subtask` **replace** the whole list (not append).
+- **`jovida complete <id> [<id> …]`** — mark done (pass several ids in one call).
+- **`jovida reopen <id> [<id> …]`** — reopen completed todos (the inverse of `complete`).
+- **`jovida delete <id> [<id> …]`** — permanently remove (several ids in one call; **no undo**).
+- **`jovida whoami` / `login` / `logout`** — session. `login` is the user's interactive step.
 
-`update` / `complete` / `delete` need a **real `entry_id`** — get it from `jovida list` or `jovida show` (parse the JSON) first. Never guess an id.
+## Workflows — composing the commands
 
-## Grouping
+Map the user's intent to a sequence; read before any change.
 
-- Several independent todos → run `jovida create` once per todo.
-- Deleting several related todos at once → **one** `jovida delete` with all the ids.
+- **Capture several items from one message** (meeting notes, a brain-dump): pick out the *real* commitments, then run `jovida create` once per item. Don't cram several tasks into one todo, and don't capture the surrounding discussion.
+- **A deliverable with steps:** one `jovida create` for the outcome, with `--subtask` per step — not many separate todos, when the steps belong to a single result.
+- **Change or reschedule:** `jovida list` (or `view`) to get the `entry_id`, then `jovida update`. To move a deadline, update `--when`. Remember `--remind` / `--subtask` replace the list.
+- **Finish or clean up:** `jovida list` to see what's open, then `jovida complete` (done) or `jovida delete` (remove) — pass all related ids in one call. Prefer `complete` over `delete` unless the item was never real; if you marked one done by mistake, `jovida reopen` undoes it (a `delete` cannot be undone).
+- **A repeating commitment:** create once with a repeat rule (a series). For a few irregular dates, create individual todos instead.
+- **"What's on my plate?"** `jovida list` (today, or widen the scope) and summarize from the JSON. Read-only — don't write anything.
 
-## Do / Don't
+## Discipline
 
-- DO `list` / `show` before `update` / `complete` / `delete` (you need the real `entry_id`).
-- DO write clear, action-oriented titles (verb-first, concrete).
-- DO say "created / updated / completed / deleted" — writes are immediate.
-- DON'T over-capture; DON'T run an immediate write the user didn't clearly ask for (there's no undo); DON'T claim success if a command exited non-zero — read the error and tell the user (e.g. exit `2` → ask them to `jovida login`).
+- Quote the title and any value containing spaces. Keep titles/descriptions **single-line plain text** — newlines and shell metacharacters passed as arguments get mangled.
+- **Never put a token in a command** (it lands in shell history / process listings). Signing in is the user's interactive step.
+- Don't claim success if a command exited non-zero — read the error and tell the user (exit `2` → ask them to `jovida login`).

package/dist/cli.js

@@ -4,16 +4,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const ctx_1 = require("./ctx");
 const create_1 = require("./commands/create");
 const list_1 = require("./commands/list");
-const show_1 = require("./commands/show");
+const view_1 = require("./commands/view");
 const update_1 = require("./commands/update");
 const complete_1 = require("./commands/complete");
+const reopen_1 = require("./commands/reopen");
 const delete_1 = require("./commands/delete");
 const login_1 = require("./commands/login");
 const whoami_1 = require("./commands/whoami");
+const skill_1 = require("./commands/skill");
 const shared_1 = require("./commands/shared");
 const session_1 = require("./session");
 const api_1 = require("./api");
 const state_1 = require("./state");
+const update_check_1 = require("./lib/update-check");
+const VERSION = require('../package.json').version;
 // 可重复的值 flag（收集成数组）。其余值 flag 取最后一次,无值则布尔 true。
 const REPEATABLE = new Set(['remind', 'subtask']);
 function parse(argv) {
@@ -55,6 +59,7 @@ Usage:
   jovida login --token <vita-token>    # dev-only interim: paste a signed-in vita token
   jovida logout
   jovida whoami [--json]
+  jovida skill install                 # copy the bundled skill into detected agents (Codex/Claude)
 
   jovida create "<title>" [--when <ISO>] [--priority none|low|medium|high]
                           [--remind <ISO> ...] [--category <s>] [--desc <s>]
@@ -63,15 +68,127 @@ Usage:
                           [--day-of-month N] [--month-of-year N] [--until YYYY-MM-DD]
                           (--repeat requires --when as the first occurrence)
   jovida list  [--scope today|upcoming|recent|range|all] [--status pending|completed|all]
-               [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N] [--json]
-  jovida show <entry_id> [--json]
+               [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N] [--full] [--json]
+  jovida view <entry_id> [--json]
   jovida update <entry_id> [--title ...] [--when ...] [--priority ...] [--remind ...] [...]
   jovida complete <entry_id> [<entry_id> ...] [--json]
+  jovida reopen <entry_id> [<entry_id> ...] [--json]
   jovida delete <entry_id> [<entry_id> ...] [--json]
 
 Output: JSON is emitted automatically when stdout is not a TTY (use --json/--no-json to force).
-Env:    JOVIDA_API_URL=<url> (default https://api.jovida.ai) · JOVIDA_HOME=<dir> (default ~/.jovida)
+Exit:   0 ok · 1 usage · 2 not signed in · 3 backend/network · 4 not found
+Env:    JOVIDA_API_URL=<url> (default https://tapi.jovida.ai) · JOVIDA_HOME=<dir> (default ~/.jovida)
+        JOVIDA_NO_UPDATE_CHECK=1 to silence the "update available" notice
+
+Run \`jovida <command> --help\` for details on a command (e.g. jovida create --help).
 `;
+// 子命令详细 help(`jovida <cmd> --help` / `jovida help <cmd>`)。
+const COMMAND_HELP = {
+    create: `jovida create — add a todo (or a recurring series)
+
+Usage:
+  jovida create "<title>" [options]
+
+Options:
+  --when <ISO>           date "2026-06-15" = that day · datetime "2026-06-15T18:00:00+08:00" = deadline
+  --priority <p>         none | low | medium | high
+  --category <s>         free-text label
+  --desc <s>             description (single line)
+  --remind <ISO> ...     reminder time(s), repeatable; must be at/before --when
+  --subtask "<t>" ...    subtask(s), repeatable
+  --hint <s>             short companion hint
+  --json
+
+Recurring (creates a series; requires --when as the first occurrence):
+  --repeat <unit>        day | week | month | year
+  --every <N>            interval, e.g. --repeat week --every 2 = biweekly
+  --weekdays <list>      weekly: mon,wed,fri (or 1..7)
+  --day-of-month <N>     monthly/yearly
+  --month-of-year <N>    yearly
+  --until <YYYY-MM-DD>   end date
+
+Examples:
+  jovida create "submit report" --when 2026-06-20T18:00:00+08:00 --priority high
+  jovida create "standup" --when 2026-06-15 --repeat week --weekdays mon,wed,fri
+`,
+    list: `jovida list — list todos (a scoped view, not a search)
+
+Usage:
+  jovida list [options]
+
+Options:
+  --scope <s>    today (default) | upcoming | recent | range | all
+  --status <s>   pending (default) | completed | all
+  --from <YYYY-MM-DD>  range start (with --scope range)
+  --to <YYYY-MM-DD>    range end
+  --limit <N>    max items (default 20)
+  --full         JSON: include all fields (description, subtasks, reminders) — one round-trip instead of list + view
+  --json
+
+Examples:
+  jovida list
+  jovida list --scope all --status all
+  jovida list --scope range --from 2026-06-01 --to 2026-06-30
+  jovida list --full          # full detail of each todo in one call
+`,
+    view: `jovida view — full details of one todo
+
+Usage:
+  jovida view <entry_id> [--json]
+`,
+    update: `jovida update — change fields of an existing todo (only the given fields change)
+
+Usage:
+  jovida update <entry_id> [options]
+
+Options (same as create; --title renames):
+  --title <s>  --when <ISO>  --priority <p>  --category <s>  --desc <s>
+  --remind <ISO> ...   (replaces the reminder list)
+  --subtask "<t>" ...  (replaces the subtask list)
+  --hint <s>  --json
+
+Example:
+  jovida update cli_01H... --priority high --when 2026-06-21T09:00:00+08:00
+`,
+    complete: `jovida complete — mark one or more todos done
+
+Usage:
+  jovida complete <entry_id> [<entry_id> ...] [--json]
+`,
+    reopen: `jovida reopen — reopen one or more completed todos (the inverse of complete)
+
+Usage:
+  jovida reopen <entry_id> [<entry_id> ...] [--json]
+`,
+    delete: `jovida delete — permanently remove one or more todos (no undo)
+
+Usage:
+  jovida delete <entry_id> [<entry_id> ...] [--json]
+`,
+    login: `jovida login — sign in (OAuth device authorization; opens a browser)
+
+Usage:
+  jovida login [--json]
+  jovida login --token <vita-token>   # dev-only interim: paste a signed-in vita token
+
+The CLI prints a URL + short code and (best-effort) opens your browser; sign in
+and approve there. It cannot sign in for you.
+`,
+    logout: `jovida logout — clear local credentials (~/.jovida)
+`,
+    whoami: `jovida whoami — show the signed-in account (online check)
+
+Usage:
+  jovida whoami [--json]
+`,
+    skill: `jovida skill — install/update the agent skill from the bundled SKILL.md
+
+Usage:
+  jovida skill install         # copy SKILL.md into detected agents (~/.codex, ~/.claude → skills/jovida-cli/)
+  jovida skill update          # same (re-copy; keeps the skill in lockstep with the CLI version)
+  jovida skill install --all   # install for all known agents even if not detected
+`
+};
 /** 错误 → 退出码(0 ok / 1 用法 / 2 未登录 / 3 后端 / 4 not found)。 */
 function exitCodeFor(e) {
     if (e instanceof session_1.NotSignedInError)
@@ -95,11 +212,17 @@ async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const { positionals, flags } = parse(rest);
     if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
-        console.log(HELP);
+        const topic = positionals[0]; // `jovida help <command>`
+        console.log(topic && COMMAND_HELP[topic] ? COMMAND_HELP[topic] : HELP);
         return;
     }
     if (cmd === 'version' || cmd === '--version' || cmd === '-v') {
-        console.log(require('../package.json').version);
+        console.log(VERSION);
+        return;
+    }
+    // `jovida <command> --help` / `-h` → that command's detailed help.
+    if (flags.help === true || rest.includes('--help') || rest.includes('-h')) {
+        console.log(COMMAND_HELP[cmd] ?? HELP);
         return;
     }
     // JSON 输出:非 TTY 自动开;--json / --no-json 强制。
@@ -116,6 +239,9 @@ async function main() {
         case 'whoami':
             await (0, whoami_1.cmdWhoami)(ctx, { json });
             break;
+        case 'skill':
+            (0, skill_1.cmdSkill)(positionals[0], { all: flags.all === true, json });
+            break;
         case 'create':
             await (0, create_1.cmdCreate)(ctx, {
                 title: positionals.join(' ').trim(),
@@ -142,11 +268,12 @@ async function main() {
                 from: str(flags.from),
                 to: str(flags.to),
                 limit: num(flags.limit),
+                full: flags.full === true,
                 json
             });
             break;
-        case 'show':
-            await (0, show_1.cmdShow)(ctx, { id: positionals[0], json });
+        case 'view':
+            await (0, view_1.cmdView)(ctx, { id: positionals[0], json });
             break;
         case 'update':
             await (0, update_1.cmdUpdate)(ctx, {
@@ -165,6 +292,9 @@ async function main() {
         case 'complete':
             await (0, complete_1.cmdComplete)(ctx, { ids: positionals, json });
             break;
+        case 'reopen':
+            await (0, reopen_1.cmdReopen)(ctx, { ids: positionals, json });
+            break;
         case 'delete':
             await (0, delete_1.cmdDelete)(ctx, { ids: positionals, json });
             break;
@@ -173,6 +303,7 @@ async function main() {
             console.log(HELP);
             process.exitCode = 1;
     }
+    await (0, update_check_1.maybeNotifyUpdate)(VERSION); // 节流 + 仅 TTY + 永不抛;放最后,不影响命令输出/退出码
 }
 main().catch((e) => {
     const msg = e instanceof Error ? e.message : String(e);

package/dist/commands/list.js

@@ -55,7 +55,8 @@ async function cmdList(ctx, a) {
         items.sort((x, y) => (anchorSec(x) || Number.POSITIVE_INFINITY) - (anchorSec(y) || Number.POSITIVE_INFINITY));
     items = items.slice(0, a.limit ?? 20);
     if (a.json) {
-        console.log(JSON.stringify({ todos: items.map(convert_1.toListItem) }, null, 2));
+        const todos = a.full ? items.map((e) => (0, convert_1.toFullTodo)(e)) : items.map(convert_1.toListItem);
+        console.log(JSON.stringify({ todos }, null, 2));
         return;
     }
     if (!items.length) {

package/dist/commands/reopen.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdReopen = cmdReopen;
+const shared_1 = require("./shared");
+/**
+ * 重新打开一个或多个已完成 entry(清 completedAt)——complete 的逆操作。
+ * 一次 pull 解析全部 id → 批量 put;任一 id 不存在则整体失败(不改任何条目)。
+ */
+async function cmdReopen(ctx, a) {
+    if (!a.ids || a.ids.length === 0) {
+        throw new Error('entry_id(s) required:  jovida reopen <entry_id> [<entry_id> ...]');
+    }
+    await ctx.session.ensureSession();
+    const snap = await ctx.sync.pull();
+    const t = (0, shared_1.nowSec)();
+    const reopened = [];
+    const missing = [];
+    for (const id of a.ids) {
+        const e = snap.entries.find((x) => x.entryId === id);
+        if (e)
+            reopened.push({ ...e, completedAt: 0, updatedAt: t });
+        else
+            missing.push(id);
+    }
+    if (missing.length)
+        throw new shared_1.NotFoundError(missing.join(', '));
+    await ctx.sync.putEntries(reopened);
+    if (a.json) {
+        console.log(JSON.stringify({ entry_ids: reopened.map((e) => e.entryId), status: 'reopened' }));
+        return;
+    }
+    for (const e of reopened)
+        console.log(`✓ reopened  ${e.title}  (${e.entryId})`);
+}

package/dist/commands/skill.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdSkill = cmdSkill;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+// 已知 agent → skill 安装位置 <home>/<dir>/skills/jovida-cli/SKILL.md。
+const AGENTS = [
+    { name: 'Codex', dir: '.codex' },
+    { name: 'Claude Code', dir: '.claude' }
+];
+const SKILL_NAME = 'jovida-cli';
+// 随包的 SKILL.md(包根)。dist/commands/skill.js → ../../SKILL.md;dev src/commands → 同样解析到仓根。
+function skillSource() {
+    return (0, node_path_1.resolve)(__dirname, '..', '..', 'SKILL.md');
+}
+/**
+ * 把随 CLI 包发布的 SKILL.md 装 / 更新进 agent 的 skill 目录。
+ * 与 CLI 同一个 npm 版本 → 不漂移。`install` 与 `update` 行为相同(覆盖)。
+ */
+function cmdSkill(sub, a) {
+    if (sub && sub !== 'install' && sub !== 'update') {
+        throw new Error('usage: jovida skill install   (or: jovida skill update)');
+    }
+    const src = skillSource();
+    if (!(0, node_fs_1.existsSync)(src))
+        throw new Error(`bundled SKILL.md not found at ${src}`);
+    const installed = [];
+    const skipped = [];
+    for (const ag of AGENTS) {
+        const home = (0, node_path_1.join)((0, node_os_1.homedir)(), ag.dir);
+        if (!a.all && !(0, node_fs_1.existsSync)(home)) {
+            skipped.push(ag.name);
+            continue;
+        }
+        const dir = (0, node_path_1.join)(home, 'skills', SKILL_NAME);
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        (0, node_fs_1.copyFileSync)(src, (0, node_path_1.join)(dir, 'SKILL.md'));
+        installed.push((0, node_path_1.join)(dir, 'SKILL.md'));
+    }
+    if (a.json) {
+        console.log(JSON.stringify({ installed, skipped }));
+        return;
+    }
+    if (installed.length === 0) {
+        console.log('No agents detected (~/.codex or ~/.claude). Re-run with --all to install for all known agents.');
+        return;
+    }
+    console.log('✓ skill installed/updated:');
+    for (const p of installed)
+        console.log(`  ${p}`);
+    if (skipped.length)
+        console.log(`(skipped, not detected: ${skipped.join(', ')} — use --all to force)`);
+}

package/dist/commands/{show.js → view.js}

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cmdShow = cmdShow;
+exports.cmdView = cmdView;
 const convert_1 = require("../core/convert");
 const shared_1 = require("./shared");
-async function cmdShow(ctx, a) {
+async function cmdView(ctx, a) {
     if (!a.id)
-        throw new Error('entry_id required:  jovida show <entry_id>');
+        throw new Error('entry_id required:  jovida view <entry_id>');
     const e = await (0, shared_1.fetchEntry)(ctx, a.id);
     const full = (0, convert_1.toFullTodo)(e);
     if (a.json) {

package/dist/config.js

@@ -11,7 +11,8 @@ function loadConfig() {
         appId: process.env['JOVIDA_APP_ID'] || DEFAULT_APP_ID
     };
 }
-exports.APP_VERSION = '0.0.1';
+// 单一版本来源:取 package.json,避免与 npm 版本双写漂移(dist/config.js 与 src/config.ts 都解析到包根)。
+exports.APP_VERSION = require('../package.json').version;
 /** process.platform → Vita-Platform 值。 */
 function platformName() {
     if (process.platform === 'darwin')

package/dist/lib/update-check.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maybeNotifyUpdate = maybeNotifyUpdate;
+// 轻量更新提示:每天最多查一次 npm 最新版,仅交互终端(TTY)、走 stderr(不污染 --json stdout)、
+// 超时 2s、**永不抛错也永不阻塞命令**。CI / NO_UPDATE_NOTIFIER / JOVIDA_NO_UPDATE_CHECK 关闭。
+const state_1 = require("../state");
+const PKG = '@fluxvita/jovida-cli';
+const DAY = 86400;
+const nowSec = () => Math.floor(Date.now() / 1000);
+function isNewer(latest, current) {
+    const a = latest.split('.').map((n) => parseInt(n, 10));
+    const b = current.split('.').map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const x = a[i] || 0;
+        const y = b[i] || 0;
+        if (x > y)
+            return true;
+        if (x < y)
+            return false;
+    }
+    return false;
+}
+async function fetchLatest() {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 2000);
+        const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: ctrl.signal });
+        clearTimeout(t);
+        if (!res.ok)
+            return null;
+        const j = (await res.json());
+        return typeof j.version === 'string' ? j.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function maybeNotifyUpdate(current) {
+    try {
+        if (!process.stderr.isTTY)
+            return; // 仅给人看;脚本/agent(非 TTY)不打扰
+        if (process.env['CI'] || process.env['JOVIDA_NO_UPDATE_CHECK'] || process.env['NO_UPDATE_NOTIFIER'])
+            return;
+        const { at, latest: cached } = (0, state_1.getUpdateCheck)();
+        let latest = cached;
+        if (!at || nowSec() - at > DAY) {
+            const fresh = await fetchLatest();
+            latest = fresh ?? cached;
+            (0, state_1.setUpdateCheck)(nowSec(), latest);
+        }
+        if (latest && isNewer(latest, current)) {
+            process.stderr.write(`\n  Update available: ${current} → ${latest}\n` +
+                `  Run: npm i -g ${PKG}@latest   (then: jovida skill update)\n\n`);
+        }
+    }
+    catch {
+        /* 更新检查永不影响命令 */
+    }
+}

package/dist/state.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDeviceId = getDeviceId;
 exports.getLastServerVersion = getLastServerVersion;
 exports.setLastServerVersion = setLastServerVersion;
+exports.getUpdateCheck = getUpdateCheck;
+exports.setUpdateCheck = setUpdateCheck;
 exports.getToken = getToken;
 exports.setToken = setToken;
 exports.clearCredentials = clearCredentials;
@@ -53,6 +55,16 @@ function setLastServerVersion(v) {
     s.lastServerVersion = v;
     saveState(s);
 }
+function getUpdateCheck() {
+    const s = loadState();
+    return { at: s.updateCheckAt ?? 0, latest: s.updateLatest ?? '' };
+}
+function setUpdateCheck(at, latest) {
+    const s = loadState();
+    s.updateCheckAt = at;
+    s.updateLatest = latest;
+    saveState(s);
+}
 function readCreds() {
     return readJson(CRED);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxvita/jovida-cli",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Jovida Daily CLI — capture and manage your todos from the command line and AI agents",
   "license": "MIT",
   "bin": {