@oozou/velocity 0.1.2 → 0.1.4

package/AGENT.md

@@ -0,0 +1,210 @@
+# Velocity CLI — Agent Reference
+
+You are operating the `velocity` CLI. This file is the contract — every
+flag, output shape, and failure mode you need is here. If a behavior
+isn't documented below, run `velocity <subcommand> --help` first; don't
+guess.
+
+## Output contract
+
+- Mode is **autodetected from TTY**: a non-TTY stdout (i.e. anything
+  an agent captures — pipes, subprocess stdout, redirects) gets JSON
+  by default. You usually don't need `--json` explicitly.
+- **Pass `--json` anyway** if you want to be defensive against agent
+  runtimes that allocate a pty for the subprocess. Cheap insurance.
+- Under JSON mode stdout is exactly one JSON value per command, schema
+  stable. Errors print `{"error":"<message>"}` on stderr and exit
+  non-zero. Always check the exit code.
+- Don't parse the human view — it's tables and prose, not stable.
+
+## Authentication
+
+The CLI must be authenticated before any non-`auth` command. Three ways:
+
+1. `velocity auth login` — opens a browser. Interactive only.
+2. `VELOCITY_TOKEN=<vel_…>` env var — for headless/CI/agent-runner
+   environments. Token is a regular Velocity API token (Settings →
+   API Tokens in the web app).
+3. A previously written credentials file from a prior `auth login`
+   (lives at `~/.config/velocity/credentials.json`, mode `0600`).
+
+To check: `velocity auth status` returns
+`{"authenticated": true|false, ...}`. If `false`, ask the user to run
+`velocity auth login` — never try to prompt for credentials yourself.
+
+`velocity whoami` is the lighter probe: `{authenticated, user}`.
+
+## Project context
+
+Most commands operate on a single project. Resolution order:
+
+1. `--project <slug-or-id>` flag on the command.
+2. `VELOCITY_PROJECT` env var.
+3. The persisted active project (set by `velocity projects use <slug>`).
+
+Projects accept either a slug (`acme-website`) or a Convex `_id`. Slugs
+are returned by `velocity projects list` and are the preferred form.
+
+If no project is resolvable the command exits non-zero with
+`{"error":"No project selected..."}`. List options with
+`velocity projects list` and either pass `--project <slug>` or set
+the active project once with `velocity projects use <slug>`.
+
+## Commands
+
+All commands send/receive JSON. Examples below assume an authenticated
+session and an active project where relevant.
+
+### Discovery
+
+```
+velocity whoami                                          # → { authenticated, user }
+velocity projects list                                   # → [{_id, slug, name, isActive, client}]
+velocity projects get <slug-or-id>                       # → full project record
+velocity projects current                                # → {env, projectId}
+velocity members                                         # → [{_id, name, email, role}]
+velocity stats                                           # → {totals, statusBreakdown, ...}
+velocity activity --limit 20                             # → [{type, actor, target, at}]
+```
+
+### Stories
+
+Stories are identified by their globally-unique `number` (an integer like
+`10634`). Use that, not the Convex `_id`.
+
+```
+velocity stories list                                    # → [{_id, number, title, status, priority, type}]
+velocity stories get <number>                            # → full story (includes assignee, sprint, parent, children)
+velocity stories create \
+  --title "Title" \
+  --type feature|bug|chore \
+  --status <stage> \
+  --priority urgent|high|medium|low \
+  [--description "..." | --description-file <path> | --description-stdin] \
+  [--assignee <userId>] [--sprint <sprintId>] [--release <releaseId>] \
+  [--parent <storyId>] [--points <num>] \
+  [--complexity none|low|medium|high]
+# → { _id, number, projectId, ... }
+
+velocity stories update <number> [same flags as create, all optional;
+                                  pass "null" to clear a relation]
+velocity stories delete <number>                         # → { status: "ok" }
+```
+
+Valid `--status` values come from the project's configured stages
+(typically `backlog`, `in_progress`, `done`, etc.). On invalid status
+the server returns 400 — read the `error` field for the allowed list.
+
+### Sprints
+
+```
+velocity sprints list                                    # → [{_id, name, startDate, endDate, status}]
+velocity sprints active                                  # → {sprint, stories, totalPoints, donePoints}
+velocity sprints get <sprintId>                          # → full sprint record + stories
+velocity sprints stories <sprintId>                      # → [stories assigned to this sprint]
+```
+
+### Releases
+
+```
+velocity releases list [--include-archived]              # → [{_id, name, version, status, targetDate}]
+velocity releases get <releaseId>                        # → full release + grouped changelog
+velocity releases create \
+  --name "v1.2 Launch" \
+  --target-date 2026-06-30 \
+  [--version 1.2.0] \
+  [--description "..." | --description-file <path> | --description-stdin]
+# → { _id, ... }
+
+velocity releases update <releaseId> [same flags, all optional]
+velocity releases status <releaseId> planned|in_progress|released|archived
+velocity releases assign <storyNumber> <releaseId>
+velocity releases unassign <storyNumber>
+```
+
+Setting status to `released` or `archived` locks the release — further
+edits are rejected.
+
+### Comments
+
+Comments attach to a story (by story number).
+
+```
+velocity comments list <storyNumber>                     # → [{_id, body, user, _creationTime}]
+velocity comments add <storyNumber> "body"
+velocity comments add <storyNumber> --file ./comment.md
+velocity comments add <storyNumber> --stdin < comment.md
+```
+
+### Notes
+
+```
+velocity notes list                                      # → [{_id, title, updatedAt}]
+velocity notes get <noteId>                              # → full note + content (markdown)
+velocity notes create \
+  --title "Title" \
+  [--content "..." | --file <path> | --stdin]
+velocity notes update <noteId> [--title "..."] \
+  [--content "..." | --file <path> | --stdin]
+velocity notes delete <noteId>                           # → { status: "ok" }
+```
+
+### Todos
+
+```
+velocity todos list                                      # → [{_id, title, priority, dueDate, done}]
+velocity todos create \
+  --title "Title" \
+  [--priority urgent|high|medium|low] \
+  [--due-date 2026-06-15] [--assignee <userId>]
+velocity todos update <todoId> [--title "..."] \
+  [--priority ...] [--due-date <yyyy-mm-dd> | --due-date null] \
+  [--assignee <userId> | --assignee null] \
+  [--done]
+velocity todos delete <todoId>                           # → { status: "ok" }
+```
+
+## Failure modes
+
+| Exit code / error fragment | Meaning | What to do |
+| --- | --- | --- |
+| stdout has JSON, exit 0 | Success | Continue. |
+| `"Not authenticated"` | Token missing or revoked | Ask user to run `velocity auth login`. |
+| `"No project selected"` | No active project resolvable | Tell user to run `velocity projects use <slug>` or pass `--project <slug>`. |
+| `"Project not found"` | Bad slug or id | List options via `velocity projects list`. |
+| `"Story not found"` / `"Note not found"` etc. | Bad numeric id / id | Confirm the value via the relevant `list` command. |
+| `"Cannot assign story to a locked release"` | Release is `released`/`archived` | Either pick an unlocked release or unlock it (web UI only). |
+| Any 500 / unexpected error | Server-side issue | Retry once; if persistent, surface to user verbatim. |
+
+Always check the exit code before parsing stdout.
+
+## Conventions
+
+- Pass long-text inputs (descriptions, note bodies, comment bodies) via
+  `--file <path>` or `--stdin` when the content is more than a line —
+  it avoids quoting headaches and surfaces shell injection less often.
+- For mutations, prefer named flags over positional arguments. The
+  flag names match the field names in the JSON response, so reading
+  back what you just wrote is straightforward.
+- To clear an optional relation (assignee, sprint, release, parent,
+  due-date), pass `null` as the value: `--assignee null`.
+- Web URLs for stories, notes, and releases are not returned by these
+  commands; they're constructed as
+  `https://velocity.oozou.com/projects/<projectId>/stories/<number>`
+  etc. when you need to link from agent output to the web app.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `VELOCITY_TOKEN` | Bearer token; bypasses the credentials file. |
+| `VELOCITY_API_BASE` | Override the API base URL. |
+| `VELOCITY_PROJECT` | Override the active project slug or id. |
+| `VELOCITY_OUTPUT` | `json` or `human`; forces output mode. |
+| `VELOCITY_NO_UPDATE_NOTIFIER` | Set to `1` to silence the update prompt. |
+
+## When in doubt
+
+Run `velocity <cmd> --help` for the live flag list — it always matches
+the binary you're invoking, even if this file drifts. Then come back
+to this contract for shape and failure-mode details.

package/README.md

@@ -1,56 +1,240 @@
 # @oozou/velocity
 
-Command-line interface for [Velocity](https://velocity.oozou.com). Usable by humans and AI agents.
+Command-line client for [Velocity](https://velocity.oozou.com). Built for humans
+at a terminal and for AI agents driving it programmatically. Output is plain
+tabular text on a TTY, JSON when piped.
 
 ## Install
 
 ```sh
 npm i -g @oozou/velocity
-# or
-pnpm add -g @oozou/velocity
 # or run without installing
 npx -y @oozou/velocity auth login
 ```
 
+Update later with `velocity update` (it shells out to `npm i -g @latest`).
+
 ## Quick start
 
 ```sh
-velocity env use production       # or `local` for a dev stack
-velocity auth login               # opens a browser to authorize
+velocity auth login                     # browser-based sign-in
 velocity whoami
-velocity project use <projectId>
+velocity projects list
+velocity projects use <slug>
 velocity stories list
-velocity stories create --title "..." --type feature --status backlog --priority medium
+velocity stories create --title "Fix nav crash" --type bug --status backlog --priority high
 ```
 
 ## Output modes
 
-- TTY → human (tables, plain text)
-- Pipe / non-TTY → JSON, one well-formed value per command
-- Force with `--json` / `--human` flags or `VELOCITY_OUTPUT=json|human`
+| Mode | When |
+| --- | --- |
+| Human | stdout is a TTY |
+| JSON | stdout is piped / non-TTY |
+
+Override per-invocation with `--json` / `--human`, or set
+`VELOCITY_OUTPUT=json|human`.
+
+Errors land on stderr. Under `--json`, errors are a single
+`{"error":"..."}` line. Exit code is non-zero on any failure.
 
 ## Headless / CI
 
-Skip the browser flow with an existing API token from Settings → API Tokens:
+Skip the browser flow with an existing API token (Settings → API Tokens):
 
 ```sh
 export VELOCITY_TOKEN=vel_…
-export VELOCITY_ENV=production
-velocity stories list --project <id>
+velocity stories list --project <slug>
 ```
 
-## Environments
+`VELOCITY_API_BASE` overrides the default endpoint if you're pointing at a
+non-production stack.
 
-| Name | API base |
-| --- | --- |
-| `production` | `https://velocity.oozou.com` |
-| `local` | `http://localhost:3000` |
+## Project context
 
-`velocity env list / current / use <name> / reset`. `--env <name>` flag and `VELOCITY_ENV` env var override per-invocation.
+Most commands operate on a single project. Resolution precedence:
+
+1. `--project <slug-or-id>` flag on the command
+2. `VELOCITY_PROJECT` env var
+3. The persisted active project (set by `velocity projects use <slug>`)
+
+Projects are addressable by slug (`acme-website`) or by Convex id. Slugs are
+the friendly identifier shown by `velocity projects list`.
 
 ## Commands
 
-`velocity agent-help` prints the full command tree as markdown — useful as model context for AI agents.
+### `velocity auth`
+
+Browser-based auth via OAuth 2.0 device-code flow.
+
+```
+velocity auth login         # opens browser, polls for approval
+velocity auth logout        # delete locally stored credentials
+velocity auth status        # show session details
+```
+
+Credentials live at `~/.config/velocity/credentials.json` (mode `0600`). The
+token issued is a regular Velocity API token — revokable from
+Settings → API Tokens in the web app.
+
+### `velocity whoami`
+
+Print the currently authenticated user. Unix `whoami` analogue.
+
+```
+velocity whoami
+```
+
+### `velocity update`
+
+Upgrade the CLI to the latest version on npm. Shells out to
+`npm i -g @oozou/velocity@latest`.
+
+```
+velocity update
+```
+
+Pass `VELOCITY_NO_UPDATE_NOTIFIER=1` to silence the passive
+"update available" prompt the CLI prints on its next run.
+
+### `velocity projects`
+
+Project listing and the active-project switcher.
+
+```
+velocity projects list                   # all projects you can access
+velocity projects get [slug-or-id]       # detail (defaults to active project)
+velocity projects use <slug-or-id>       # set the active project
+velocity projects current                # show the active project
+velocity projects reset                  # clear the active project
+```
+
+### `velocity stories`
+
+Stories are addressed by their globally-unique number (`#10634`).
+
+```
+velocity stories list
+velocity stories get <number>
+velocity stories create \
+  --title "Title" \
+  --type feature|bug|chore \
+  --status <stage> \
+  --priority urgent|high|medium|low \
+  [--description "..." | --description-file <path> | --description-stdin] \
+  [--assignee <userId>] \
+  [--sprint <sprintId>] \
+  [--release <releaseId>] \
+  [--parent <storyId>] \
+  [--points <number>] \
+  [--complexity none|low|medium|high]
+velocity stories update <number> [same options as create, all optional;
+                                 pass "null" to clear a relation]
+velocity stories delete <number>
+```
+
+### `velocity sprints`
+
+```
+velocity sprints list                    # all sprints in active project
+velocity sprints active                  # current sprint + stories + day totals
+velocity sprints get <sprintId>
+velocity sprints stories <sprintId>      # all stories in a sprint
+```
+
+### `velocity releases`
+
+```
+velocity releases list [--include-archived]
+velocity releases get <releaseId>
+velocity releases create \
+  --name "v1.2 Launch" \
+  --target-date 2026-06-30 \
+  [--version 1.2.0] \
+  [--description "..." | --description-file <path> | --description-stdin]
+velocity releases update <releaseId> [same options as create, all optional;
+                                     pass "null" to clear]
+velocity releases status <releaseId> planned|in_progress|released|archived
+velocity releases assign <storyNumber> <releaseId>
+velocity releases unassign <storyNumber>
+```
+
+### `velocity comments`
+
+Comments attach to a story (by story number).
+
+```
+velocity comments list <storyNumber>
+velocity comments add <storyNumber> "body text"
+velocity comments add <storyNumber> --file ./comment.md
+velocity comments add <storyNumber> --stdin < comment.md
+```
+
+### `velocity notes`
+
+```
+velocity notes list
+velocity notes get <noteId>
+velocity notes create \
+  --title "Architecture decisions" \
+  [--content "..." | --file <path> | --stdin]
+velocity notes update <noteId> [--title "..."] \
+  [--content "..." | --file <path> | --stdin]
+velocity notes delete <noteId>
+```
+
+### `velocity todos`
+
+```
+velocity todos list
+velocity todos create \
+  --title "Email Alice" \
+  [--priority urgent|high|medium|low] \
+  [--due-date 2026-06-15] \
+  [--assignee <userId>]
+velocity todos update <todoId> [--title "..."] \
+  [--priority ...] [--due-date 2026-06-15 | --due-date null] \
+  [--assignee <userId> | --assignee null] \
+  [--done]
+velocity todos delete <todoId>
+```
+
+### Project meta
+
+Top-level commands that operate on the active project.
+
+```
+velocity stats                           # totals, status breakdown
+velocity activity [--limit N]            # recent activity feed
+velocity members                         # team members
+```
+
+### `velocity agent-help`
+
+Prints a markdown guide intended as model context for AI agents driving the
+CLI. Useful at the top of an agent session:
+
+```sh
+velocity agent-help --json
+```
+
+## Global flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--json` / `--human` | Force output mode regardless of TTY |
+| `--api-base <url>` | Override the API base URL for one invocation |
+| `--project <slug-or-id>` | Override the active project for one invocation |
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `VELOCITY_TOKEN` | Bearer token; bypasses the credentials file |
+| `VELOCITY_API_BASE` | Override the API base URL |
+| `VELOCITY_PROJECT` | Override the active project slug or id |
+| `VELOCITY_OUTPUT` | `json` or `human`; forces output mode |
+| `VELOCITY_NO_UPDATE_NOTIFIER` | Set to `1` to silence the update prompt |
 
 ## License
 

package/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: velocity
+description: Operate the Velocity CLI to read and manage projects, stories, sprints, releases, notes, todos, and comments. Use whenever the user asks to look at Velocity data or to create/update/delete anything in their Velocity workspace.
+---
+
+# velocity
+
+You have access to the `velocity` CLI. It is the sanctioned way to read
+or write Velocity content from a terminal or agent runtime.
+
+**Always read [AGENT.md](./AGENT.md) before issuing your first command in
+a session.** It contains the full command surface, the JSON output
+contract, project resolution rules, and the failure modes you will
+hit. Do not guess command names or flag shapes.
+
+If `AGENT.md` is not on disk (sandboxed environments), run
+`velocity agent-help` to print the same content to stdout.

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import updateNotifier from "update-notifier";
 
 // src/commands/auth.ts
@@ -497,7 +497,7 @@ var runReset = async (cmd) => {
   );
 };
 var registerEnvCommands = (program2) => {
-  const env = program2.command("env").description("Switch between Velocity deployments (production/local)");
+  const env = program2.command("env", { hidden: true }).description("Switch between Velocity deployments (production/local)");
   env.command("list").description("List known environments and which one is active").action(async function() {
     try {
       await runList(this);
@@ -1316,98 +1316,33 @@ var registerUpdateCommand = (program2) => {
 };
 
 // src/commands/agent-help.ts
-var HELP_TEXT = `# Velocity CLI agent guide
-
-The Velocity CLI is a REST client over /api/v1/* with two output modes:
-- Human (default on a TTY): tabular plain text.
-- JSON (default when stdout is piped, or pass --json): a single JSON value per command.
-
-## Environments
-- \`velocity env list\` \u2014 show known envs (production, local) and which is active.
-- \`velocity env use <name>\` \u2014 set the active env for future invocations.
-- \`velocity env current\` \u2014 show active env + api base + signed-in state.
-- \`velocity env reset\` \u2014 clear the active-env file (falls back to production).
-- \`--env <name>\` flag overrides per-command. \`VELOCITY_ENV\` env var overrides next.
-
-## Auth
-- \`velocity auth login\` \u2014 opens a browser, polls for approval. Stores creds at
-  ~/.config/velocity/credentials.<env>.json (mode 0600).
-- \`velocity auth logout\` \u2014 deletes the local credentials file.
-- \`velocity auth status\` \u2014 show session details. \`velocity whoami\` \u2014 short form.
-- Headless escape hatch: set \`VELOCITY_TOKEN=vel_\u2026\`. With \`VELOCITY_ENV\` it's
-  enough; \`VELOCITY_API_BASE\` overrides the URL.
-
-## Active project
-Most commands need a projectId. Resolution:
-1. \`--project <id>\` flag
-2. \`VELOCITY_PROJECT\` env var
-3. The active-project file (\`velocity projects use <slug>\`)
-
-## Command tree
-
-\`\`\`
-auth login | logout | status
-env list | current | use <name> | reset
-whoami
-
-projects list
-projects get [slug-or-id]
-projects use <slug-or-id> | current | reset
-
-update                 # upgrade the CLI to the latest version on npm
-
-stories list
-stories get <number>
-stories create --title --type --status --priority [--description --assignee --sprint --release --parent --points --complexity]
-stories update <number> [--title --description --type --status --priority --assignee --sprint --release --parent --points --complexity]
-stories delete <number>
-
-sprints list
-sprints active
-sprints get <sprintId>
-sprints stories <sprintId>
-
-releases list [--include-archived]
-releases get <releaseId>
-releases create --name --target-date [--version --description]
-releases update <releaseId> [--name --target-date --version --description]
-releases status <releaseId> <planned|in_progress|released|archived>
-releases assign <storyNumber> <releaseId>
-releases unassign <storyNumber>
-
-comments list <storyNumber>
-comments add <storyNumber> <body> | --body | --file | --stdin
-
-notes list
-notes get <noteId>
-notes create --title [--content | --file | --stdin]
-notes update <noteId> [--title --content | --file | --stdin]
-notes delete <noteId>
-
-todos list
-todos create --title [--priority --due-date --assignee]
-todos update <todoId> [--title --priority --due-date --assignee --done]
-todos delete <todoId>
-
-stats
-activity [--limit N]
-members
-\`\`\`
-
-## Output rules for scripts
-- Stdout: success result (human or JSON depending on TTY / flags / VELOCITY_OUTPUT).
-- Stderr: prompts, errors, browser hints. Never JSON success data.
-- Exit code: 0 on success, non-zero on failure.
-- 401 from any command \u2192 token rotted or revoked. Re-run \`velocity auth login\`.
-
-## Errors
-JSON mode errors come back as \`{"error":"..."}\` on stderr with a non-zero exit
-code. Human mode prints \`Error: ...\` on stderr.
-`;
+import { readFile as readFile4 } from "fs/promises";
+import { fileURLToPath } from "url";
+import { dirname as dirname3, join as join2 } from "path";
+var findAgentDoc = async () => {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join2(here, "..", "AGENT.md"),
+    // dist/index.js → ../AGENT.md
+    join2(here, "..", "..", "AGENT.md")
+    // dev: src/commands → ../../AGENT.md
+  ];
+  for (const path of candidates) {
+    try {
+      return await readFile4(path, "utf8");
+    } catch {
+    }
+  }
+  throw new Error(
+    "AGENT.md not found. Reinstall the CLI with `npm i -g @oozou/velocity@latest`."
+  );
+};
 var registerAgentHelpCommand = (program2) => {
-  program2.command("agent-help").description("Print a markdown guide for AI agents using the CLI").action(async function() {
+  program2.command("agent-help").description("Print the agent contract (AGENT.md) to stdout").action(async function() {
     try {
-      writeResult(this, { markdown: HELP_TEXT }, () => HELP_TEXT);
+      const doc = await findAgentDoc();
+      process.stdout.write(doc);
+      if (!doc.endsWith("\n")) process.stdout.write("\n");
     } catch (err) {
       exitWithError(err, this);
     }
@@ -1415,7 +1350,7 @@ var registerAgentHelpCommand = (program2) => {
 };
 
 // src/index.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.4";
 if (process.stdout.isTTY && process.env.VELOCITY_NO_UPDATE_NOTIFIER !== "1") {
   try {
     updateNotifier({
@@ -1429,7 +1364,10 @@ if (process.stdout.isTTY && process.env.VELOCITY_NO_UPDATE_NOTIFIER !== "1") {
   }
 }
 var program = new Command();
-program.name("velocity").description("CLI for Velocity").version(VERSION).option("--json", "force JSON output regardless of TTY", false).option("--human", "force human output regardless of TTY", false).option("--env <name>", "Target a named env (production, local)").option("--api-base <url>", "Override the Velocity API base URL").option("--project <id>", "Target a specific project for this invocation");
+program.name("velocity").description("CLI for Velocity").version(VERSION).option("--json", "force JSON output regardless of TTY", false).option("--human", "force human output regardless of TTY", false).addOption(
+  // Functional but intentionally not surfaced in --help output.
+  new Option("--env <name>", "Target a named env").hideHelp()
+).option("--api-base <url>", "Override the Velocity API base URL").option("--project <id>", "Target a specific project for this invocation");
 registerAuthCommands(program);
 registerEnvCommands(program);
 registerWhoamiCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oozou/velocity",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Velocity CLI — browser-based auth + REST client for the Velocity project management API.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://velocity.oozou.com",
@@ -25,6 +25,8 @@
   },
   "files": [
     "dist",
+    "AGENT.md",
+    "SKILL.md",
     "README.md",
     "LICENSE"
   ],