npm - @brunyee-studio/onus-cli - Versions diffs - 2.28.0 → 2.30.0 - Mend

@brunyee-studio/onus-cli 2.28.0 → 2.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +36 -7
package/dist/bin.js +116 -28
package/package.json +1 -1
package/skills/onus-cli/SKILL.md +53 -19

package/README.md CHANGED Viewed

@@ -200,8 +200,8 @@ onus team get <id> [--json]
 ```bash
 onus project list [--json]
 onus project get <id> [--json]
-onus project create --name <name> --team <teamId> [--status <status>] [--priority <priority>] [--lead <leadId>] [--target-date <date>] [--json]
-onus project update <id> [--name <name>] [--status <status>] [--priority <priority>] [--lead <leadId>] [--target-date <date>] [--json]
+onus project create --name <name> --team <teamId> [--status <status>] [--priority <priority>] [--lead <leadId>] [--target-date <date>] [--description <text>] [--description-file <path>] [--agent-context <text>] [--agent-context-file <path>] [--json]
+onus project update <id> [--name <name>] [--status <status>] [--priority <priority>] [--lead <leadId>] [--target-date <date>] [--description <text>] [--description-file <path>] [--agent-context <text>] [--agent-context-file <path>] [--json]
 ```
 ### `onus issue`
@@ -211,8 +211,8 @@ Issues are addressed by human reference (`ENG-42`); UUIDs are also accepted.
 ```bash
 onus issue list [--team <id>] [--project <id>] [--assignee <id>] [--parent <id>] [--status <status>] [--q <query>] [--limit <n>] [--cursor <cursor>] [--json]
 onus issue get <ref> [--json]
-onus issue create --title <title> --team <teamId> [-d <description>] [--status <status>] [--priority <priority>] [--assignee <id>] [--project <id>] [--parent <id>] [--label <labelId>] [--json]
-onus issue update <ref> [--title <title>] [-d <description>] [--status <status>] [--priority <priority>] [--assignee <id>] [--project <id>] [--parent <id>] [--add-label <labelId>] [--remove-label <labelId>] [--json]
+onus issue create --title <title> --team <teamId> [-d <description>] [--description-file <path>] [--status <status>] [--priority <priority>] [--assignee <id>] [--project <id>] [--parent <id>] [--label <labelId>] [--json]
+onus issue update <ref> [--title <title>] [-d <description>] [--description-file <path>] [--status <status>] [--priority <priority>] [--assignee <id>] [--project <id>] [--parent <id>] [--add-label <labelId>] [--remove-label <labelId>] [--json]
 onus issue delete <ref> [--yes] [--json]
 ```
@@ -224,9 +224,9 @@ aliased as `edit`.
 #### Comment subcommands
 ```bash
-onus issue comment create <ref> --body <body> [--json]
+onus issue comment create <ref> [--body <body> | --body-file <path>] [--json]
 onus issue comment list <ref> [--json]
-onus issue comment edit <ref> --comment <commentId> --body <body> [--json]
+onus issue comment edit <ref> --comment <commentId> [--body <body> | --body-file <path>] [--json]
 onus issue comment delete <ref> --comment <commentId> [--json]
 ```
@@ -270,7 +270,7 @@ onus issue unlink-pr <ref> --pr-link <linkId> [--json]
 ```bash
 onus comment list <issueId> [--json]
-onus comment create <issueId> --body <body> [--json]
+onus comment create <issueId> [--body <body> | --body-file <path>] [--json]
 ```
 ### `onus label`
@@ -352,6 +352,35 @@ export ONUS_TOKEN="<your-onus-token>"
 onus me --json
 ```
+### 6. Long text via per-field file input
+Long, multi-line values (issue and project descriptions, comment bodies,
+project agent context) are awkward to inline in shell commands. Each of these
+fields has a companion file flag that reads **only that field** from a file —
+never the whole record — following the standard `--body-file` convention:
+```bash
+onus issue create --title "Fix login bug" --team ONUS --description-file ./body.md
+onus issue update ENG-42 --description-file ./notes.md
+onus issue comment create ENG-42 --body-file ./comment.md
+onus comment create ENG-42 --body-file ./comment.md
+onus project create --name "Migration" --team ONUS --description-file ./brief.md
+onus project update <projectId> --description-file ./brief.md
+onus project update <projectId> --agent-context-file AGENTS.md
+```
+Pass `-` as the path to read the field value from stdin, so agents can pipe
+content directly:
+```bash
+generate-body | onus issue create --title "Fix login bug" --team ONUS --description-file -
+```
+Passing both the inline flag and its file variant (e.g. `--body` together with
+`--body-file`) is an error; the file never silently overrides the inline value.
+Comment bodies must be non-empty: an empty or whitespace-only `--body` or
+`--body-file` is rejected before the request is sent.
 ---
 ## How the CLI is generated from OpenAPI

package/dist/bin.js CHANGED Viewed

@@ -557,15 +557,33 @@ function registerAnalyticsCommands(program2) {
   );
 }
-// src/commands/project.ts
+// src/file-input.ts
 import { readFileSync } from "fs";
-function resolveAgentContext(text, file) {
-  if (file !== void 0 && text !== void 0) {
-    throw new Error("--agent-context and --agent-context-file cannot be used together");
+async function resolveTextValue(opts) {
+  if (opts.file !== void 0 && opts.value !== void 0) {
+    throw new Error(`${opts.inlineFlag} and ${opts.fileFlag} cannot be used together`);
   }
-  if (file !== void 0) return readFileSync(file, "utf8");
-  return text;
+  if (opts.file === void 0) return opts.value;
+  if (opts.file === "-") return readStdin();
+  return readFileSync(opts.file, "utf8");
+}
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", reject);
+  });
 }
+async function resolveRequiredTextValue(opts) {
+  const value = await resolveTextValue(opts);
+  if (value === void 0 || value.trim().length === 0) {
+    throw new Error(`${opts.subject} is required (provide ${opts.inlineFlag} or ${opts.fileFlag})`);
+  }
+  return value;
+}
+// src/commands/project.ts
 function previewAgentContext(value) {
   if (!value) return null;
   const firstLine = value.split("\n")[0].trim();
@@ -623,15 +641,29 @@ function registerProjectCommands(program2) {
       await handleApiError(err, globals.json);
     }
   });
-  project.command("create").description("Create a new project").requiredOption("--name <name>", "Project name").requiredOption("--team <team>", "Team UUID or KEY (e.g. ONUS)").option("--status <status>", "Project status (backlog|planned|in_progress|completed|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--lead <leadId>", "Lead user UUID").option("--target-date <date>", "Target completion date (ISO)").option("--description <text>", "Project description (rendered under the title)").option(
+  project.command("create").description("Create a new project").requiredOption("--name <name>", "Project name").requiredOption("--team <team>", "Team UUID or KEY (e.g. ONUS)").option("--status <status>", "Project status (backlog|planned|in_progress|completed|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--lead <leadId>", "Lead user UUID").option("--target-date <date>", "Target completion date (ISO)").option("--description <text>", "Project description (rendered under the title)").option("--description-file <path>", 'Read the project description from a file ("-" for stdin)').option(
     "--agent-context <text>",
     "Agent context markdown (agents.md-style guidance; '' clears)"
-  ).option("--agent-context-file <path>", "Read agent context markdown from a file").option("-j, --json", "Output raw JSON").action(async function(opts) {
+  ).option(
+    "--agent-context-file <path>",
+    'Read agent context markdown from a file ("-" for stdin)'
+  ).option("-j, --json", "Output raw JSON").action(async function(opts) {
     const globals = this.optsWithGlobals();
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
       const teamId = await resolveTeamId(client, opts.team);
-      const agentContext = resolveAgentContext(opts.agentContext, opts.agentContextFile);
+      const description = await resolveTextValue({
+        value: opts.description,
+        file: opts.descriptionFile,
+        inlineFlag: "--description",
+        fileFlag: "--description-file"
+      });
+      const agentContext = await resolveTextValue({
+        value: opts.agentContext,
+        file: opts.agentContextFile,
+        inlineFlag: "--agent-context",
+        fileFlag: "--agent-context-file"
+      });
       const project2 = await client.projectsPost({
         projectsPostRequest: {
           team_id: teamId,
@@ -640,7 +672,7 @@ function registerProjectCommands(program2) {
           priority: opts.priority,
           lead_id: opts.lead,
           target_date: opts.targetDate,
-          description: opts.description,
+          description,
           agent_context: agentContext
         }
       });
@@ -651,14 +683,28 @@ function registerProjectCommands(program2) {
       await handleApiError(err, globals.json);
     }
   });
-  project.command("update <id>").description("Update an existing project by UUID").option("--name <name>", "Project name").option("--status <status>", "Project status (backlog|planned|in_progress|completed|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--lead <leadId>", "Lead user UUID").option("--target-date <date>", "Target completion date (ISO)").option("--description <text>", "Project description (rendered under the title)").option(
+  project.command("update <id>").description("Update an existing project by UUID").option("--name <name>", "Project name").option("--status <status>", "Project status (backlog|planned|in_progress|completed|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--lead <leadId>", "Lead user UUID").option("--target-date <date>", "Target completion date (ISO)").option("--description <text>", "Project description (rendered under the title)").option("--description-file <path>", 'Read the project description from a file ("-" for stdin)').option(
     "--agent-context <text>",
     "Agent context markdown (agents.md-style guidance; '' clears)"
-  ).option("--agent-context-file <path>", "Read agent context markdown from a file").option("-j, --json", "Output raw JSON").action(async function(id, opts) {
+  ).option(
+    "--agent-context-file <path>",
+    'Read agent context markdown from a file ("-" for stdin)'
+  ).option("-j, --json", "Output raw JSON").action(async function(id, opts) {
     const globals = this.optsWithGlobals();
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
-      const agentContext = resolveAgentContext(opts.agentContext, opts.agentContextFile);
+      const description = await resolveTextValue({
+        value: opts.description,
+        file: opts.descriptionFile,
+        inlineFlag: "--description",
+        fileFlag: "--description-file"
+      });
+      const agentContext = await resolveTextValue({
+        value: opts.agentContext,
+        file: opts.agentContextFile,
+        inlineFlag: "--agent-context",
+        fileFlag: "--agent-context-file"
+      });
       const project2 = await client.projectsIdPatch({
         id,
         projectsIdPatchRequest: {
@@ -667,7 +713,7 @@ function registerProjectCommands(program2) {
           priority: opts.priority,
           lead_id: opts.lead,
           target_date: opts.targetDate,
-          description: opts.description,
+          description,
           agent_context: agentContext
         }
       });
@@ -718,6 +764,7 @@ function registerProjectCommands(program2) {
     [
       'onus project create --name "Website" --team ONUS',
       'onus project create --name "Mobile" --team ONUS --priority high --target-date <YYYY-MM-DD>',
+      'onus project create --name "Migration" --team ONUS --description-file ./brief.md',
       'onus project create --name "Migration" --team ONUS --agent-context-file AGENTS.md'
     ]
   );
@@ -725,6 +772,7 @@ function registerProjectCommands(program2) {
     project.commands.find((c) => c.name() === "update"),
     [
       "onus project update <projectId> --status in_progress",
+      "onus project update <projectId> --description-file ./brief.md",
       "onus project update <projectId> --agent-context 'Add debug logging to all new code'",
       "onus project update <projectId> --agent-context ''   # clears agent context"
     ]
@@ -883,7 +931,7 @@ Comments (${issue2.comments.length}):`);
       await handleApiError(err, globals.json);
     }
   });
-  issue.command("create").description("Create a new issue").option("--title <title>", "Issue title").requiredOption("--team <team>", "Team UUID or KEY (e.g. ONUS)").option("-d, --description <description>", "Issue description (markdown)").option("--status <status>", "Status (backlog|todo|in_progress|done|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--assignee <assigneeId>", "Assignee UUID").option("--project <projectId>", "Project UUID").option("--parent <parentId>", "Parent issue UUID").option("--label <labelId>", "Label UUID to attach (repeatable)", collect, []).option(
+  issue.command("create").description("Create a new issue").option("--title <title>", "Issue title").requiredOption("--team <team>", "Team UUID or KEY (e.g. ONUS)").option("-d, --description <description>", "Issue description (markdown)").option("--description-file <path>", 'Read the issue description from a file ("-" for stdin)').option("--status <status>", "Status (backlog|todo|in_progress|done|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--assignee <assigneeId>", "Assignee UUID").option("--project <projectId>", "Project UUID").option("--parent <parentId>", "Parent issue UUID").option("--label <labelId>", "Label UUID to attach (repeatable)", collect, []).option(
     "--template <nameOrId>",
     "Issue template: UUID or exact name within the team; fills omitted fields"
   ).option("-j, --json", "Output raw JSON").action(async function(opts) {
@@ -891,8 +939,13 @@ Comments (${issue2.comments.length}):`);
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
       const teamId = await resolveTeamId(client, opts.team);
+      let description = await resolveTextValue({
+        value: opts.description,
+        file: opts.descriptionFile,
+        inlineFlag: "--description",
+        fileFlag: "--description-file"
+      });
       let title = opts.title;
-      let description = opts.description;
       let priority = opts.priority;
       let labels = (opts.label ?? []).length > 0 ? opts.label : void 0;
       if (opts.template) {
@@ -946,7 +999,7 @@ Comments (${issue2.comments.length}):`);
       await handleApiError(err, globals.json);
     }
   });
-  issue.command("update <ref>").alias("edit").description("Update (or edit) an existing issue by reference").option("--title <title>", "Issue title").option("-d, --description <description>", "Issue description").option("--status <status>", "Status (backlog|todo|in_progress|done|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--assignee <assigneeId>", "Assignee UUID").option("--project <projectId>", "Project UUID").option("--parent <parentId>", 'Parent issue UUID (pass "null", "none", or "" to clear)').option("--add-label <labelId>", "Label UUID to add (repeatable)", collect, []).option(
+  issue.command("update <ref>").alias("edit").description("Update (or edit) an existing issue by reference").option("--title <title>", "Issue title").option("-d, --description <description>", "Issue description").option("--description-file <path>", 'Read the issue description from a file ("-" for stdin)').option("--status <status>", "Status (backlog|todo|in_progress|done|canceled)").option("--priority <priority>", "Priority (none|urgent|high|medium|low)").option("--assignee <assigneeId>", "Assignee UUID").option("--project <projectId>", "Project UUID").option("--parent <parentId>", 'Parent issue UUID (pass "null", "none", or "" to clear)').option("--add-label <labelId>", "Label UUID to add (repeatable)", collect, []).option(
     "--remove-label <labelId>",
     "Label UUID to remove (repeatable)",
     collect,
@@ -955,9 +1008,15 @@ Comments (${issue2.comments.length}):`);
     const globals = this.optsWithGlobals();
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const description = await resolveTextValue({
+        value: opts.description,
+        file: opts.descriptionFile,
+        inlineFlag: "--description",
+        fileFlag: "--description-file"
+      });
       const patch = {};
       if (opts.title !== void 0) patch.title = opts.title;
-      if (opts.description !== void 0) patch.description = opts.description;
+      if (description !== void 0) patch.description = description;
       if (opts.status !== void 0) patch.status = opts.status;
       if (opts.priority !== void 0) patch.priority = opts.priority;
       if (opts.assignee !== void 0) patch.assignee_id = opts.assignee;
@@ -1017,14 +1076,16 @@ Comments (${issue2.comments.length}):`);
     issue.commands.find((c) => c.name() === "create"),
     [
       'onus issue create --title "Fix login bug" --team ONUS',
-      'onus issue create --title "Ship v2" --team ONUS --priority high --project <projectId>'
+      'onus issue create --title "Ship v2" --team ONUS --priority high --project <projectId>',
+      'onus issue create --title "Refactor auth" --team ONUS --description-file ./body.md'
     ]
   );
   withExamples(
     issue.commands.find((c) => c.name() === "update"),
     [
       "onus issue update <issueId> --status done",
-      "onus issue update <issueId> --priority urgent --assignee <assigneeId>"
+      "onus issue update <issueId> --priority urgent --assignee <assigneeId>",
+      "onus issue update <issueId> --description-file ./notes.md"
     ]
   );
   withExamples(
@@ -1039,13 +1100,20 @@ Comments (${issue2.comments.length}):`);
 }
 function registerIssueCommentCommands(issue) {
   const comment = issue.command("comment").description("Create, list, edit, and delete issue comments");
-  comment.command("create <ref>").description("Post a comment on an issue").requiredOption("--body <body>", "Comment body text (markdown)").option("-j, --json", "Output raw JSON").action(async function(id, opts) {
+  comment.command("create <ref>").description("Post a comment on an issue").option("--body <body>", "Comment body text (markdown)").option("--body-file <path>", 'Read the comment body from a file ("-" for stdin)').option("-j, --json", "Output raw JSON").action(async function(id, opts) {
     const globals = this.optsWithGlobals();
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const body = await resolveRequiredTextValue({
+        value: opts.body,
+        file: opts.bodyFile,
+        inlineFlag: "--body",
+        fileFlag: "--body-file",
+        subject: "comment body"
+      });
       const c = await client.issuesIdCommentsPost({
         id,
-        commentsCommentIdPatchRequest: { body: opts.body }
+        commentsCommentIdPatchRequest: { body }
       });
       printJsonOrFormatted(c, globals.json, () => formatSuccess(`Posted comment ${c.id}.`));
     } catch (err) {
@@ -1078,13 +1146,20 @@ function registerIssueCommentCommands(issue) {
       await handleApiError(err, globals.json);
     }
   });
-  comment.command("edit <ref>").description("Edit an existing comment").requiredOption("--comment <commentId>", "Comment UUID").requiredOption("--body <body>", "New comment body text").option("-j, --json", "Output raw JSON").action(async function(_id, opts) {
+  comment.command("edit <ref>").description("Edit an existing comment").requiredOption("--comment <commentId>", "Comment UUID").option("--body <body>", "New comment body text").option("--body-file <path>", 'Read the new comment body from a file ("-" for stdin)').option("-j, --json", "Output raw JSON").action(async function(_id, opts) {
     const globals = this.optsWithGlobals();
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const body = await resolveRequiredTextValue({
+        value: opts.body,
+        file: opts.bodyFile,
+        inlineFlag: "--body",
+        fileFlag: "--body-file",
+        subject: "comment body"
+      });
       const c = await client.commentsCommentIdPatch({
         commentId: opts.comment,
-        commentsCommentIdPatchRequest: { body: opts.body }
+        commentsCommentIdPatchRequest: { body }
       });
       printJsonOrFormatted(c, globals.json, () => formatSuccess(`Updated comment ${c.id}.`));
     } catch (err) {
@@ -1107,7 +1182,10 @@ function registerIssueCommentCommands(issue) {
   });
   withExamples(
     comment.commands.find((c) => c.name() === "create"),
-    ['onus issue comment create <issueId> --body "Thanks for the fix!"']
+    [
+      'onus issue comment create <issueId> --body "Thanks for the fix!"',
+      "onus issue comment create <issueId> --body-file ./comment.md"
+    ]
   );
   withExamples(
     comment.commands.find((c) => c.name() === "list"),
@@ -1467,13 +1545,20 @@ function registerCommentCommands(program2) {
       await handleApiError(err, globals.json);
     }
   });
-  comment.command("create <issueId>").description("Post a comment on an issue").requiredOption("--body <body>", "Comment body text (markdown)").option("-j, --json", "Output raw JSON").action(async function(issueId, opts) {
+  comment.command("create <issueId>").description("Post a comment on an issue").option("--body <body>", "Comment body text (markdown)").option("--body-file <path>", 'Read the comment body from a file ("-" for stdin)').option("-j, --json", "Output raw JSON").action(async function(issueId, opts) {
     const globals = this.optsWithGlobals();
     try {
       const client = createApiClient({ token: globals.token, apiUrl: globals.apiUrl });
+      const body = await resolveRequiredTextValue({
+        value: opts.body,
+        file: opts.bodyFile,
+        inlineFlag: "--body",
+        fileFlag: "--body-file",
+        subject: "comment body"
+      });
       const comment2 = await client.issuesIdCommentsPost({
         id: issueId,
-        commentsCommentIdPatchRequest: { body: opts.body }
+        commentsCommentIdPatchRequest: { body }
       });
       printJsonOrFormatted(comment2, globals.json, () => {
         formatSuccess(`Posted comment ${comment2.id}.`);
@@ -1488,7 +1573,10 @@ function registerCommentCommands(program2) {
   );
   withExamples(
     comment.commands.find((c) => c.name() === "create"),
-    ['onus comment create <issueId> --body "Looks good to me"']
+    [
+      'onus comment create <issueId> --body "Looks good to me"',
+      "onus comment create <issueId> --body-file ./comment.md"
+    ]
   );
 }

package/package.json CHANGED Viewed

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

package/skills/onus-cli/SKILL.md CHANGED Viewed

@@ -22,6 +22,7 @@ onus --api-url <url> …              # custom API base URL
 - **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`.
 - 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
 - Exit codes: `0` success · `1` general error · `2` validation error · `3` auth error · `4` not found.
 - Issue commands take a `<ref>` = human identifier (e.g. `ENG-42`) or UUID. Every `--team <team>` option accepts a team KEY (e.g. `ONUS`) or a team UUID — prefer the KEY, it's stable and readable.
@@ -65,7 +66,8 @@ reading alongside the issue itself.
   (`issue create/update --project`).
 - Editing a project (name, status, description, `agent_context`) is
   permission-gated; never guess project UUIDs — `onus project list` first.
-  Set context from a file: `onus project update <id> --agent-context-file AGENTS.md`.
+  Set context from a file: `onus project update <id> --agent-context-file AGENTS.md`
+  (or `-` to read stdin).
 ## Create and update issues
@@ -80,6 +82,28 @@ onus issue update ENG-42 --remove-label <labelId> --assignee <userId> --json
 onus issue delete ENG-42 --yes            # skip confirmation
 ```
+## Long text via file input
+Multi-line values (issue and project descriptions, comment bodies, project
+agent context) must not be inlined in the shell command — quoting, escaping,
+and shell length limits make the transcript fragile. Each long-text field has
+a companion file flag that reads exactly that one field from a file; pass `-`
+to read the value from stdin:
+```bash
+onus issue create --title "Refactor auth" --team ONUS --description-file ./body.md --json
+onus issue update ENG-42 --description-file ./notes.md --json
+onus issue comment create ENG-42 --body-file ./comment.md --json
+onus issue comment edit ENG-42 --comment <commentId> --body-file ./comment.md --json
+onus project update <projectId> --description-file ./brief.md --json
+onus project update <projectId> --agent-context-file AGENTS.md --json
+generate-body | onus comment create ENG-42 --body-file - --json
+```
+- The file flag covers exactly one field — never a whole-record file.
+- Inline value and file flag are mutually exclusive: passing both (e.g.
+  `--body` together with `--body-file`) is an error.
 ## Comments
 ```bash
@@ -121,24 +145,34 @@ onus dsn create --team ONUS --label ci    # prints the full secret exactly once
 ## Pull requests and issues
 Linking a PR to an issue means **the issue is auto-closed when the PR merges** —
-there is no "related" link type. How links are created:
-- **Auto-linking is GitHub-style.** The integration scans the PR title, body,
-  and branch name for `KEY-123` refs introduced by a closing keyword —
-  `Fixes` / `Closes` / `Resolves` (case-insensitive, optional colon, comma/
-  `and` lists). A plain prose mention of an issue ID does NOT link and never
-  auto-closes, so avoid writing bare issue IDs in PR text: use the issue's
-  name or its Onus URL instead.
-- **Manual linking is deliberate.** `onus issue link-pr` creates a bot link
-  that survives body edits and closes on merge — use it when the PR fully
-  resolves an issue but its text has no closing keyword.
-- **Only link PRs that actually fix/close the issue.** If a PR merely touches
-  related code, discusses the issue, or implements part of it without completing
-  it, do NOT link it (no keyword in the PR text, no `link-pr`). Use a relation
-  (`onus issue relation add … --type related`) or a comment mention instead.
-- Never guess or assume: before linking, verify the PR's changes fully resolve
-  the issue (e.g. you implemented the fix in that PR, or the PR description
-  says "Fixes ONUS-42").
+there is no "related" link type.
+**Always link manually with `onus issue link-pr`. Never rely on the fix
+keyword.** The integration also scans the PR title, body, and branch name for
+`KEY-123` refs introduced by a closing keyword (`Fixes` / `Closes` /
+`Resolves` — case-insensitive, optional colon, comma/`and` lists), but agents
+must never depend on that scan and must never write a closing keyword before
+an Onus issue ref in PR text or a branch name. Reference issues in PR text by
+name or their Onus URL, never as bare issue IDs.
+Required PR flow, in order:
+1. **Create the PR** (push the branch, open the PR with `gh`).
+2. **Determine whether the PR closes the issue.** It closes the issue only if
+   the PR fully resolves it — you implemented the whole fix in that PR. A PR
+   that merely touches related code, discusses the issue, or implements part
+   of it without completing it does not close it.
+3. **Link it.** If (and only if) step 2 says yes, run:
+   ```bash
+   onus issue link-pr <ref> --repo owner/repo --pr <number> --json
+   ```
+   The bot link survives PR-body edits and closes the issue on merge. If the
+   PR does not close the issue, leave it unlinked — use a relation
+   (`onus issue relation add … --type related`) or a comment mention instead.
+- Never guess or assume: link only issues you know the PR fully resolves.
 - Link at most once per PR per issue; don't spam links across partially-related
   issues.