@brunyee-studio/onus-cli 2.30.1 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunyee-studio/onus-cli",
-  "version": "2.30.1",
+  "version": "2.31.0",
   "description": "Official CLI and TypeScript SDK for Onus issue tracking platform",
   "keywords": [
     "agent",

package/skills/onus-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onus-cli
-description: Work with Onus issue tracking through the onus CLI — authenticate, fetch teams/projects/issues, create and update issues, manage comments, labels, relations, and attachments. Use when the user asks to find, list, create, update, comment on, or organize Onus issues, projects, or teams.
+description: Work with Onus issue tracking through the onus CLI — authenticate, fetch teams/projects/issues, create and update issues, manage comments, labels, relations, and attachments, and consult the knowledge base (kb). Use when the user asks to find, list, create, update, comment on, or organize Onus issues, projects, or teams, or to read KB docs.
 ---
 
 # Onus CLI
@@ -26,7 +26,7 @@ Transparent refresh on 401 applies only to the stored config-file session.
 
 ## Golden rules
 
-- **Starting work on an issue: transition it to `in_progress` immediately.** As soon as you pick up an issue to implement it — before writing any code — run `onus issue update <ref> --status in_progress --json`. No update needed if `onus issue get <ref> --json` already shows the status is `in_progress` or `done`.
+- **Starting work on an issue: transition it to `in_progress` and make sure it has an owner — you.** As soon as you pick up an issue to implement it — before writing any code — resolve your user id (`onus me --json` → `.id`), then run `onus issue update <ref> --status in_progress --assignee <userId> --json`. Self-assign only when the issue is unassigned or already assigned to you; if someone else is the assignee, leave them in place and say so. No update needed if `onus issue get <ref> --json` already shows the status is `in_progress` or `done` — but if it is `in_progress` while unassigned, still assign it to yourself.
 - Add `--json` to every command you intend to parse.
 - Multi-line text (issue descriptions, comment bodies, agent context) goes through the field's file flag — `--description-file`, `--body-file`, `--agent-context-file` — never inline in the shell command. See "Long text via file input" below.
 - Whenever referencing an Onus issue in any response, include its link: `https://onus.brunyeestudio.com/team/{TEAM}/issues/{NUM}` where `{TEAM}` is the team key (the tag before the dash in the ref, e.g. `ONUS`) and `{NUM}` is the issue number (the number after the dash). Example: for ref `ONUS-1`, `TEAM = ONUS`, `NUM = 1` → https://onus.brunyeestudio.com/team/ONUS/issues/1
@@ -50,8 +50,10 @@ onus label list --json                  # workspace labels (for --label ids)
 ```bash
 onus issue list --json
 onus issue list --team ONUS --status in_progress --json
+onus issue list --priority high --team ONUS --json          # filter by priority
 onus issue list --assignee <userId> --project <projectId> --json
 onus issue list --q "login bug" --limit 20 --json          # free-text search
+onus issue list --q ONUS-42 --json                          # display-key search
 onus issue list --cursor <cursor> --json                    # next page
 onus issue get ENG-42 --json                                # single issue by ref
 ```
@@ -198,6 +200,27 @@ onus dsn enable <keyId> --json            # re-enable a disabled key
 onus dsn revoke <keyId> --json            # terminal
 ```
 
+## Knowledge base (agent workflow)
+
+Consult the KB before implementing an issue — docs (`index | area | process |
+incident` kinds) describe code areas, processes, and incidents. Read-only: no
+CLI command or API mutates docs.
+
+```bash
+onus kb locate --issue <issueUuid> --json   # locate first, on issue start (or --query "text"; exactly one)
+onus kb get <slug> --json                    # then read each returned doc (also accepts UUID; ambiguous slug → exit 2)
+onus kb search "<query>" --json              # scored search; --mode string|semantic|hybrid|related (--doc <slug> required with related)
+onus kb related <slug> --json                # expand related docs
+onus kb list --team ONUS --kind area --tag auth --limit 20 --cursor <cursor> --json
+```
+
+- Results carry staleness `{stale, confidence, reason}` — a `stale` doc is
+  planning input: verify it against current code and surface drift.
+- **Surface drift, never write it.** Note stale/incorrect docs in the PR
+  description ("KB drift: …"); regeneration is infrastructure-led on merge —
+  the pipeline updates affected docs automatically after the PR merges
+  (human-edited docs get proposed revisions for human approval).
+
 ## Pull requests and issues
 
 Linking a PR to an issue means **the issue is auto-closed when the PR merges** —