@bussolabs/closeyourit-cli 0.19.0 → 0.21.0

package/opencli.json

@@ -3,7 +3,7 @@
   "opencli": "0.1",
   "info": {
     "title": "closeyourit",
-    "version": "0.19.0",
+    "version": "0.21.0",
     "description": "CLI for CloseYourIt — manage org, errors, tokens and tickets with your user token",
     "license": {
       "name": "MIT",
@@ -292,7 +292,8 @@
                       "server_replication_down",
                       "server_replication_up",
                       "server_container_restart_loop",
-                      "server_container_stable"
+                      "server_container_stable",
+                      "seo_issue_new"
                     ]
                   }
                 ]
@@ -662,7 +663,8 @@
                       "server_replication_down",
                       "server_replication_up",
                       "server_container_restart_loop",
-                      "server_container_stable"
+                      "server_container_stable",
+                      "seo_issue_new"
                     ]
                   }
                 ]
@@ -1946,7 +1948,7 @@
               },
               {
                 "name": "--title",
-                "description": "Ticket title (skips AI when set together with --description)",
+                "description": "Ticket title (skips AI when set together with --description, max 255 characters)",
                 "arguments": [
                   {
                     "name": "TITLE",
@@ -1956,7 +1958,7 @@
               },
               {
                 "name": "--description",
-                "description": "Ticket description (skips AI when set together with --title)",
+                "description": "Ticket description (skips AI when set together with --title, max 4000 characters)",
                 "arguments": [
                   {
                     "name": "DESCRIPTION",
@@ -1981,21 +1983,21 @@
                 ]
               },
               {
-                "name": "--status-id",
-                "description": "Status lookup id (default: open)",
+                "name": "--status",
+                "description": "Status code, label or id (e.g. open, \"In Progress\") — default: open",
                 "arguments": [
                   {
-                    "name": "STATUS-ID",
+                    "name": "STATUS",
                     "required": true
                   }
                 ]
               },
               {
-                "name": "--priority-id",
-                "description": "Priority lookup id (default: medium)",
+                "name": "--priority",
+                "description": "Priority code, label or id (e.g. medium, High) — default: medium",
                 "arguments": [
                   {
-                    "name": "PRIORITY-ID",
+                    "name": "PRIORITY",
                     "required": true
                   }
                 ]
@@ -2461,6 +2463,121 @@
               "closeyourit kb ask \"what is our retry/backoff policy?\" --json"
             ]
           },
+          {
+            "name": "book",
+            "description": "Knowledge books: ordered collections of pages (summary, add a page)",
+            "commands": [
+              {
+                "name": "add-page",
+                "description": "Add a knowledge page to a book, optionally at a given position in the summary",
+                "options": [
+                  {
+                    "name": "--page",
+                    "description": "Id of the knowledge page to add (an id, not a page number; alias: --page-id)",
+                    "required": true,
+                    "arguments": [
+                      {
+                        "name": "PAGE",
+                        "required": true
+                      }
+                    ]
+                  },
+                  {
+                    "name": "--position",
+                    "description": "Where to put it in the summary (0 = top; omit to append at the end)",
+                    "arguments": [
+                      {
+                        "name": "POSITION",
+                        "required": true
+                      }
+                    ]
+                  }
+                ],
+                "arguments": [
+                  {
+                    "name": "ID",
+                    "required": true,
+                    "description": "Knowledge book id"
+                  }
+                ],
+                "examples": [
+                  "closeyourit kb book add-page <book-id> --page <page-id>",
+                  "closeyourit kb book add-page <book-id> --page <page-id> --position 0",
+                  "closeyourit kb book add-page <book-id> --page <page-id> --json"
+                ]
+              },
+              {
+                "name": "list",
+                "description": "List knowledge books (ordered collections of pages) across the projects you can see",
+                "options": [
+                  {
+                    "name": "--project",
+                    "aliases": [
+                      "-p"
+                    ],
+                    "description": "Filter by project (key or UUID)",
+                    "arguments": [
+                      {
+                        "name": "PROJECT",
+                        "required": true
+                      }
+                    ]
+                  },
+                  {
+                    "name": "--q",
+                    "description": "Filter by title (substring, case-insensitive)",
+                    "arguments": [
+                      {
+                        "name": "Q",
+                        "required": true
+                      }
+                    ]
+                  },
+                  {
+                    "name": "--per",
+                    "description": "Page size",
+                    "arguments": [
+                      {
+                        "name": "PER",
+                        "required": true
+                      }
+                    ]
+                  },
+                  {
+                    "name": "--page",
+                    "description": "Page number",
+                    "arguments": [
+                      {
+                        "name": "PAGE",
+                        "required": true
+                      }
+                    ]
+                  }
+                ],
+                "examples": [
+                  "closeyourit kb book list",
+                  "closeyourit kb book list --project acme-api",
+                  "closeyourit kb book list --q deploy --per 50",
+                  "closeyourit kb book list --json"
+                ]
+              },
+              {
+                "name": "show",
+                "description": "Show a knowledge book: its metadata, then the summary of the pages it collects",
+                "arguments": [
+                  {
+                    "name": "ID",
+                    "required": true,
+                    "description": "Knowledge book id"
+                  }
+                ],
+                "examples": [
+                  "closeyourit kb book show <book-id>",
+                  "closeyourit kb book show <book-id> --json"
+                ]
+              }
+            ]
+          },
           {
             "name": "consolidate",
             "description": "Mark an accepted page as written to the versioned docs, recording its path",
@@ -2509,7 +2626,7 @@
               },
               {
                 "name": "--title",
-                "description": "Page title",
+                "description": "Page title (max 255 characters)",
                 "required": true,
                 "arguments": [
                   {
@@ -2530,7 +2647,7 @@
               },
               {
                 "name": "--body",
-                "description": "Page body (markdown)",
+                "description": "Page body (markdown, max 4000 characters)",
                 "arguments": [
                   {
                     "name": "BODY",
@@ -2540,7 +2657,7 @@
               },
               {
                 "name": "--body-file",
-                "description": "Read the body (markdown) from a local file",
+                "description": "Read the body (markdown, max 4000 characters) from a local file",
                 "arguments": [
                   {
                     "name": "BODY-FILE",
@@ -2550,7 +2667,7 @@
               },
               {
                 "name": "--tech-spec",
-                "description": "Technical section, kept separate from the simple body",
+                "description": "Technical section, kept separate from the simple body (max 1500 characters)",
                 "arguments": [
                   {
                     "name": "TECH-SPEC",
@@ -2560,7 +2677,7 @@
               },
               {
                 "name": "--tech-spec-file",
-                "description": "Read the technical section from a local file",
+                "description": "Read the technical section (max 1500 characters) from a local file",
                 "arguments": [
                   {
                     "name": "TECH-SPEC-FILE",
@@ -2574,7 +2691,7 @@
               },
               {
                 "name": "--review-note",
-                "description": "One line explaining why the page is worth keeping (review queue)",
+                "description": "One line explaining why the page is worth keeping (review queue, max 240 characters)",
                 "arguments": [
                   {
                     "name": "REVIEW-NOTE",
@@ -2686,6 +2803,82 @@
               "closeyourit kb list --awaiting-consolidation"
             ]
           },
+          {
+            "name": "publish",
+            "description": "Idempotently create or update a Knowledge page by publication key.\n\nExactly one of --body or --body-file is required.",
+            "options": [
+              {
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Project id (UUID) or key",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--publication-key",
+                "description": "Stable publication key (1-255 URL-safe characters)",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "PUBLICATION-KEY",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--title",
+                "description": "Page title (max 255 characters)",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "TITLE",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--kind",
+                "description": "Page kind: note|decision|guide (new page: note; existing: unchanged)",
+                "arguments": [
+                  {
+                    "name": "KIND",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--body",
+                "description": "Page body (markdown, max 4000 characters); exactly one of --body or --body-file is required",
+                "arguments": [
+                  {
+                    "name": "BODY",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--body-file",
+                "description": "Read the page body (markdown, max 4000 characters) from a local file; exactly one of --body or --body-file is required",
+                "arguments": [
+                  {
+                    "name": "BODY-FILE",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "examples": [
+              "closeyourit kb publish --project CYCL --publication-key docs:release --title \"Release guide\" --body \"Steps…\"",
+              "closeyourit kb publish -p CYCL --publication-key docs:release --title \"Release guide\" --kind guide --body-file ./release.md"
+            ]
+          },
           {
             "name": "related",
             "description": "List the pages to read next: the ones this page links to (and that link to it), plus close matches by meaning",
@@ -2821,7 +3014,7 @@
             "options": [
               {
                 "name": "--title",
-                "description": "New title",
+                "description": "New title (max 255 characters)",
                 "arguments": [
                   {
                     "name": "TITLE",
@@ -2841,7 +3034,7 @@
               },
               {
                 "name": "--body",
-                "description": "New body (markdown)",
+                "description": "New body (markdown, max 4000 characters)",
                 "arguments": [
                   {
                     "name": "BODY",
@@ -2851,7 +3044,7 @@
               },
               {
                 "name": "--body-file",
-                "description": "Read the new body (markdown) from a local file",
+                "description": "Read the new body (markdown, max 4000 characters) from a local file",
                 "arguments": [
                   {
                     "name": "BODY-FILE",
@@ -2861,7 +3054,7 @@
               },
               {
                 "name": "--tech-spec",
-                "description": "New technical section, kept separate from the simple body",
+                "description": "New technical section, kept separate from the simple body (max 1500 characters)",
                 "arguments": [
                   {
                     "name": "TECH-SPEC",
@@ -2871,7 +3064,7 @@
               },
               {
                 "name": "--tech-spec-file",
-                "description": "Read the new technical section from a local file",
+                "description": "Read the new technical section (max 1500 characters) from a local file",
                 "arguments": [
                   {
                     "name": "TECH-SPEC-FILE",
@@ -5138,7 +5331,7 @@
             "examples": [
               "closeyourit personal import --from-file .env",
               "closeyourit personal import --format json --from-file secrets.json",
-              "doppler secrets download --no-file --format json | closeyourit personal import --format json"
+              "printf '{\"API_KEY\":\"value\"}' | closeyourit personal import --format json"
             ]
           },
           {
@@ -5151,7 +5344,7 @@
           },
           {
             "name": "run",
-            "description": "Run a command with your personal secrets injected as env vars (like `doppler run`). Secrets never touch disk.",
+            "description": "Run a command with your personal secrets injected as env vars. Secrets never touch disk.",
             "examples": [
               "closeyourit personal run -- bundle exec rails server",
               "closeyourit personal run -- printenv OPENAI_API_KEY"
@@ -6248,7 +6441,7 @@
       },
       {
         "name": "run",
-        "description": "Run a command with the project/environment secrets injected as env vars (like `doppler run`). Secrets never touch disk.",
+        "description": "Run a command with project/environment secrets injected as env vars. Secrets never touch disk.",
         "options": [
           {
             "name": "--project",
@@ -6876,7 +7069,7 @@
             "examples": [
               "closeyourit secrets import -p acme-api -e production --from-file .env",
               "closeyourit secrets import -p acme-api -e production --format json --from-file secrets.json",
-              "doppler secrets download --config production --no-file --format json | closeyourit secrets import -p acme-api -e production --format json"
+              "printf '{\"API_KEY\":\"value\"}' | closeyourit secrets import -p acme-api -e development --format json"
             ]
           },
           {
@@ -7015,110 +7208,502 @@
         ]
       },
       {
-        "name": "servers",
-        "description": "Server monitoring fleet (agents, enrollment tokens)",
+        "name": "seo",
         "commands": [
           {
-            "name": "delete",
-            "description": "Delete a server and all its metrics (a live agent would re-register it)",
+            "name": "ignore",
+            "description": "Ignore an SEO finding: you accept living with it",
             "options": [
               {
-                "name": "--confirm",
-                "description": "Required: confirm the deletion"
+                "name": "--note",
+                "description": "Why you are keeping it (shown alongside the ignored row)",
+                "arguments": [
+                  {
+                    "name": "NOTE",
+                    "required": true
+                  }
+                ]
               }
             ],
             "arguments": [
               {
                 "name": "ID",
                 "required": true,
-                "description": "Server id"
+                "description": "SEO finding id"
               }
             ],
             "examples": [
-              "closeyourit servers delete <server-id> --confirm"
+              "closeyourit seo ignore <issue-id>",
+              "closeyourit seo ignore <issue-id> --note \"Service page, not meant to be found.\""
             ]
           },
           {
-            "name": "ignored-containers",
-            "description": "Read or set the container names this server does not treat as services",
+            "name": "list",
+            "description": "List the SEO findings of your sites (cross-project)",
             "options": [
               {
-                "name": "--clear",
-                "description": "Remove every ignored container name"
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Filter by project id (UUID) or key",
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
               },
               {
-                "name": "--set",
-                "description": "Comma-separated names to ignore (replaces the list)",
+                "name": "--severity",
+                "description": "Filter by severity (critical, high, medium, low)",
                 "arguments": [
                   {
-                    "name": "SET",
+                    "name": "SEVERITY",
                     "required": true
                   }
                 ]
-              }
-            ],
-            "arguments": [
+              },
               {
-                "name": "ID",
-                "required": true,
-                "description": "Server id"
-              }
-            ],
-            "examples": [
-              "closeyourit servers ignored-containers <server-id>",
-              "closeyourit servers ignored-containers <server-id> --set buildkit,runner",
-              "closeyourit servers ignored-containers <server-id> --clear"
-            ]
-          },
-          {
-            "name": "list",
-            "description": "List the monitored servers in your organization (fleet snapshot)",
-            "options": [
+                "name": "--status",
+                "description": "Filter by status (open, resolved, ignored)",
+                "arguments": [
+                  {
+                    "name": "STATUS",
+                    "required": true
+                  }
+                ]
+              },
               {
-                "name": "--page",
-                "description": "Page number",
+                "name": "--area",
+                "description": "Filter by area (indexability, structure, content, i18n, performance)",
                 "arguments": [
                   {
-                    "name": "PAGE",
+                    "name": "AREA",
                     "required": true
                   }
                 ]
               },
               {
-                "name": "--status",
-                "description": "Filter by status (repeatable)",
+                "name": "--page",
+                "description": "Page number",
                 "arguments": [
                   {
-                    "name": "STATUS",
-                    "required": true,
-                    "acceptedValues": [
-                      "pending",
-                      "up",
-                      "down",
-                      "paused"
-                    ]
+                    "name": "PAGE",
+                    "required": true
                   }
                 ]
               }
             ],
             "examples": [
-              "closeyourit servers list",
-              "closeyourit servers list --status down --json"
+              "closeyourit seo list",
+              "closeyourit seo list --severity critical",
+              "closeyourit seo list --project acme-site --status open",
+              "closeyourit seo list --area indexability --json"
             ]
           },
           {
-            "name": "pause",
-            "description": "Pause a server (no staleness checks or alerts until resumed)",
-            "arguments": [
+            "name": "pages",
+            "description": "List the pages the SEO check has visited, with their state",
+            "options": [
               {
-                "name": "ID",
-                "required": true,
-                "description": "Server id"
-              }
-            ],
-            "examples": [
-              "closeyourit servers pause <server-id>"
-            ]
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Filter by project id (UUID) or key",
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--url",
+                "description": "Filter by URL (partial match)",
+                "arguments": [
+                  {
+                    "name": "URL",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--page",
+                "description": "Page number",
+                "arguments": [
+                  {
+                    "name": "PAGE",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "examples": [
+              "closeyourit seo pages",
+              "closeyourit seo pages --project acme-site",
+              "closeyourit seo pages --url /prezzi --json"
+            ]
+          },
+          {
+            "name": "promote",
+            "description": "Open a ticket from an SEO finding, evidence included",
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "SEO finding id"
+              }
+            ],
+            "examples": [
+              "closeyourit seo promote <issue-id>"
+            ]
+          },
+          {
+            "name": "reopen",
+            "description": "Reopen an ignored SEO finding: you changed your mind",
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "SEO finding id"
+              }
+            ],
+            "examples": [
+              "closeyourit seo reopen <issue-id>"
+            ]
+          },
+          {
+            "name": "rescan",
+            "description": "Check a site now, without waiting for the next scheduled run",
+            "options": [
+              {
+                "name": "--site",
+                "description": "Site id (from `seo-sites list`)",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "SITE",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "examples": [
+              "closeyourit seo rescan --site <site-id>"
+            ]
+          },
+          {
+            "name": "show",
+            "description": "Show a single SEO finding, with the evidence behind it",
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "SEO finding id"
+              }
+            ],
+            "examples": [
+              "closeyourit seo show <issue-id>"
+            ]
+          }
+        ]
+      },
+      {
+        "name": "seo-sites",
+        "commands": [
+          {
+            "name": "create",
+            "description": "Declare a site to keep an eye on (one per project and environment)",
+            "options": [
+              {
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Project id (UUID) or key",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--url",
+                "description": "Public address the visit starts from",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "URL",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--environment",
+                "description": "Environment id (must be declared by the project)",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "ENVIRONMENT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--frequency",
+                "description": "How often to check it: daily (default) or weekly",
+                "arguments": [
+                  {
+                    "name": "FREQUENCY",
+                    "required": true,
+                    "acceptedValues": [
+                      "daily",
+                      "weekly"
+                    ]
+                  }
+                ]
+              },
+              {
+                "name": "--max-pages",
+                "description": "How many pages to visit at most each run",
+                "arguments": [
+                  {
+                    "name": "MAX-PAGES",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--no-sitemap",
+                "description": "Don't read the sitemap: start from the home page and follow links only"
+              }
+            ],
+            "examples": [
+              "closeyourit seo-sites create --project acme-site --url https://www.acme.example --environment <env-id>",
+              "closeyourit seo-sites create -p acme-site --url https://www.acme.example --environment <env-id> --frequency weekly --max-pages 50"
+            ]
+          },
+          {
+            "name": "delete",
+            "description": "Stop watching a site and remove its pages and findings",
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Site id"
+              }
+            ],
+            "examples": [
+              "closeyourit seo-sites delete <site-id>"
+            ]
+          },
+          {
+            "name": "list",
+            "description": "List the sites under SEO check",
+            "options": [
+              {
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Filter by project id (UUID) or key",
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--page",
+                "description": "Page number",
+                "arguments": [
+                  {
+                    "name": "PAGE",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "examples": [
+              "closeyourit seo-sites list",
+              "closeyourit seo-sites list --project acme-site --json"
+            ]
+          },
+          {
+            "name": "update",
+            "description": "Change how a site is checked (project and environment are its identity: they never change)",
+            "options": [
+              {
+                "name": "--url",
+                "description": "Public address the visit starts from",
+                "arguments": [
+                  {
+                    "name": "URL",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--frequency",
+                "description": "How often to check it: daily or weekly",
+                "arguments": [
+                  {
+                    "name": "FREQUENCY",
+                    "required": true,
+                    "acceptedValues": [
+                      "daily",
+                      "weekly"
+                    ]
+                  }
+                ]
+              },
+              {
+                "name": "--max-pages",
+                "description": "How many pages to visit at most each run",
+                "arguments": [
+                  {
+                    "name": "MAX-PAGES",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--sitemap",
+                "description": "Read the sitemap"
+              },
+              {
+                "name": "--enable",
+                "description": "Resume the checks"
+              },
+              {
+                "name": "--disable",
+                "description": "Pause the checks (the site and its findings stay)"
+              }
+            ],
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Site id"
+              }
+            ],
+            "examples": [
+              "closeyourit seo-sites update <site-id> --frequency weekly",
+              "closeyourit seo-sites update <site-id> --max-pages 200 --disable"
+            ]
+          }
+        ]
+      },
+      {
+        "name": "servers",
+        "description": "Server monitoring fleet (agents, enrollment tokens)",
+        "commands": [
+          {
+            "name": "delete",
+            "description": "Delete a server and all its metrics (a live agent would re-register it)",
+            "options": [
+              {
+                "name": "--confirm",
+                "description": "Required: confirm the deletion"
+              }
+            ],
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Server id"
+              }
+            ],
+            "examples": [
+              "closeyourit servers delete <server-id> --confirm"
+            ]
+          },
+          {
+            "name": "ignored-containers",
+            "description": "Read or set the container names this server does not treat as services",
+            "options": [
+              {
+                "name": "--clear",
+                "description": "Remove every ignored container name"
+              },
+              {
+                "name": "--set",
+                "description": "Comma-separated names to ignore (replaces the list)",
+                "arguments": [
+                  {
+                    "name": "SET",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Server id"
+              }
+            ],
+            "examples": [
+              "closeyourit servers ignored-containers <server-id>",
+              "closeyourit servers ignored-containers <server-id> --set buildkit,runner",
+              "closeyourit servers ignored-containers <server-id> --clear"
+            ]
+          },
+          {
+            "name": "list",
+            "description": "List the monitored servers in your organization (fleet snapshot)",
+            "options": [
+              {
+                "name": "--page",
+                "description": "Page number",
+                "arguments": [
+                  {
+                    "name": "PAGE",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--status",
+                "description": "Filter by status (repeatable)",
+                "arguments": [
+                  {
+                    "name": "STATUS",
+                    "required": true,
+                    "acceptedValues": [
+                      "pending",
+                      "up",
+                      "down",
+                      "paused"
+                    ]
+                  }
+                ]
+              }
+            ],
+            "examples": [
+              "closeyourit servers list",
+              "closeyourit servers list --status down --json"
+            ]
+          },
+          {
+            "name": "pause",
+            "description": "Pause a server (no staleness checks or alerts until resumed)",
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Server id"
+              }
+            ],
+            "examples": [
+              "closeyourit servers pause <server-id>"
+            ]
           },
           {
             "name": "rename",
@@ -7931,7 +8516,7 @@
               },
               {
                 "name": "--body",
-                "description": "Comment body",
+                "description": "Comment body (max 240 characters — longer text goes in the work report)",
                 "required": true,
                 "arguments": [
                   {
@@ -8030,7 +8615,7 @@
           },
           {
             "name": "create",
-            "description": "Create a ticket",
+            "description": "Create a ticket (status defaults to open, priority to medium; both take a code or a label)",
             "options": [
               {
                 "name": "--project",
@@ -8048,7 +8633,7 @@
               },
               {
                 "name": "--title",
-                "description": "Ticket title",
+                "description": "Ticket title (max 255 characters)",
                 "required": true,
                 "arguments": [
                   {
@@ -8075,7 +8660,7 @@
               },
               {
                 "name": "--description",
-                "description": "Free-form description (human-simple summary)",
+                "description": "Free-form description (human-simple summary, max 4000 characters)",
                 "arguments": [
                   {
                     "name": "DESCRIPTION",
@@ -8085,7 +8670,7 @@
               },
               {
                 "name": "--technical-analysis",
-                "description": "Technical analysis (stack, cause) — kept out of the human-simple body",
+                "description": "Technical analysis (stack, cause) — kept out of the human-simple body (max 1500 characters)",
                 "arguments": [
                   {
                     "name": "TECHNICAL-ANALYSIS",
@@ -8174,21 +8759,21 @@
                 ]
               },
               {
-                "name": "--status-id",
-                "description": "Status lookup id",
+                "name": "--status",
+                "description": "Status code, label or id (e.g. open, \"In Progress\") — default: open",
                 "arguments": [
                   {
-                    "name": "STATUS-ID",
+                    "name": "STATUS",
                     "required": true
                   }
                 ]
               },
               {
-                "name": "--priority-id",
-                "description": "Priority lookup id",
+                "name": "--priority",
+                "description": "Priority code, label or id (e.g. medium, High) — default: medium",
                 "arguments": [
                   {
-                    "name": "PRIORITY-ID",
+                    "name": "PRIORITY",
                     "required": true
                   }
                 ]
@@ -8237,7 +8822,8 @@
             "examples": [
               "closeyourit tickets create --project acme-api --title \"Checkout fails\"",
               "closeyourit tickets create -p acme-api --title \"Login bug\" --kind bug --step-given \"logged out\" --step-when \"I submit\" --step-then \"it 500s\"",
-              "closeyourit tickets create -p acme-api --title \"Checkout\" --scenarios '[{\"title\":\"Happy\",\"step_given\":\"logged in\",\"step_when\":\"I pay\",\"step_then\":\"order created\"}]' --condition \"confirmation email is sent\""
+              "closeyourit tickets create -p acme-api --title \"Checkout\" --scenarios '[{\"title\":\"Happy\",\"step_given\":\"logged in\",\"step_when\":\"I pay\",\"step_then\":\"order created\"}]' --condition \"confirmation email is sent\"",
+              "closeyourit tickets create -p acme-api --title \"Payment retry\" --status in_progress --priority High"
             ]
           },
           {
@@ -8727,6 +9313,139 @@
               "closeyourit tickets reject <ticket-id> --project acme-api --reason \"Edge case not covered\""
             ]
           },
+          {
+            "name": "report",
+            "description": "Write the work report of a ticket — the long text a comment cannot hold. Each write adds a version, it never overwrites the previous one",
+            "options": [
+              {
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Project id (UUID) or key",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--body",
+                "description": "Report body (markdown, max 20000 characters)",
+                "arguments": [
+                  {
+                    "name": "BODY",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--body-file",
+                "description": "Read the report body (max 20000 characters) from a local file",
+                "arguments": [
+                  {
+                    "name": "BODY-FILE",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Ticket id or code (e.g. DRFL-3)"
+              }
+            ],
+            "examples": [
+              "closeyourit tickets report <ticket-id> --project acme-api --body \"Cosa ho fatto, come si verifica\"",
+              "closeyourit tickets report DRFL-3 -p acme-api --body-file ./report.md"
+            ]
+          },
+          {
+            "name": "report-show",
+            "description": "Show the current work report of a ticket, or a past version with --version",
+            "options": [
+              {
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Project id (UUID) or key",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--version",
+                "description": "Version number to read instead of the current one",
+                "arguments": [
+                  {
+                    "name": "VERSION",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Ticket id or code (e.g. DRFL-3)"
+              }
+            ],
+            "examples": [
+              "closeyourit tickets report-show <ticket-id> --project acme-api",
+              "closeyourit tickets report-show DRFL-3 -p acme-api --version 2"
+            ]
+          },
+          {
+            "name": "report-versions",
+            "description": "List the versions of the work report of a ticket (newest first)",
+            "options": [
+              {
+                "name": "--project",
+                "aliases": [
+                  "-p"
+                ],
+                "description": "Project id (UUID) or key",
+                "required": true,
+                "arguments": [
+                  {
+                    "name": "PROJECT",
+                    "required": true
+                  }
+                ]
+              },
+              {
+                "name": "--page",
+                "description": "Page number",
+                "arguments": [
+                  {
+                    "name": "PAGE",
+                    "required": true
+                  }
+                ]
+              }
+            ],
+            "arguments": [
+              {
+                "name": "ID",
+                "required": true,
+                "description": "Ticket id or code (e.g. DRFL-3)"
+              }
+            ],
+            "examples": [
+              "closeyourit tickets report-versions <ticket-id> --project acme-api",
+              "closeyourit tickets report-versions DRFL-3 -p acme-api --page 2 --json"
+            ]
+          },
           {
             "name": "reviewer",
             "description": "Set the reviewer of a ticket (requires tickets.assign)",
@@ -8802,7 +9521,7 @@
           },
           {
             "name": "status",
-            "description": "Change a ticket status",
+            "description": "Change a ticket status (by code, label or id)",
             "options": [
               {
                 "name": "--project",
@@ -8819,12 +9538,12 @@
                 ]
               },
               {
-                "name": "--status-id",
-                "description": "Target status lookup id",
+                "name": "--status",
+                "description": "Target status code, label or id (e.g. in_review, \"In Review\")",
                 "required": true,
                 "arguments": [
                   {
-                    "name": "STATUS-ID",
+                    "name": "STATUS",
                     "required": true
                   }
                 ]
@@ -8838,7 +9557,8 @@
               }
             ],
             "examples": [
-              "closeyourit tickets status <ticket-id> --project acme-api --status-id <status-id>"
+              "closeyourit tickets status <ticket-id> --project acme-api --status in_review",
+              "closeyourit tickets status <ticket-id> --project acme-api --status <status-id>"
             ]
           },
           {
@@ -8980,7 +9700,7 @@
           },
           {
             "name": "update",
-            "description": "Update a ticket (full replace — fields you omit are cleared server-side)",
+            "description": "Update a ticket, changing only the fields you pass (the others keep their current value; use --clear to empty one, --replace for the raw full replace)",
             "options": [
               {
                 "name": "--project",
@@ -8998,7 +9718,7 @@
               },
               {
                 "name": "--title",
-                "description": "Ticket title",
+                "description": "Ticket title (max 255 characters)",
                 "arguments": [
                   {
                     "name": "TITLE",
@@ -9024,7 +9744,7 @@
               },
               {
                 "name": "--description",
-                "description": "Free-form description (human-simple summary)",
+                "description": "Free-form description (human-simple summary, max 4000 characters)",
                 "arguments": [
                   {
                     "name": "DESCRIPTION",
@@ -9034,7 +9754,7 @@
               },
               {
                 "name": "--technical-analysis",
-                "description": "Technical analysis (stack, cause) — kept out of the human-simple body",
+                "description": "Technical analysis (stack, cause) — kept out of the human-simple body (max 1500 characters)",
                 "arguments": [
                   {
                     "name": "TECHNICAL-ANALYSIS",
@@ -9123,21 +9843,21 @@
                 ]
               },
               {
-                "name": "--status-id",
-                "description": "Status lookup id",
+                "name": "--status",
+                "description": "Status code, label or id (e.g. open, \"In Progress\") — unchanged when omitted",
                 "arguments": [
                   {
-                    "name": "STATUS-ID",
+                    "name": "STATUS",
                     "required": true
                   }
                 ]
               },
               {
-                "name": "--priority-id",
-                "description": "Priority lookup id",
+                "name": "--priority",
+                "description": "Priority code, label or id (e.g. medium, High) — unchanged when omitted",
                 "arguments": [
                   {
-                    "name": "PRIORITY-ID",
+                    "name": "PRIORITY",
                     "required": true
                   }
                 ]
@@ -9181,6 +9901,30 @@
                     "required": true
                   }
                 ]
+              },
+              {
+                "name": "--clear",
+                "description": "Empty a field on purpose (repeatable): description, technical-analysis, weight, due-at, assignee, milestone, parent, platforms",
+                "arguments": [
+                  {
+                    "name": "CLEAR",
+                    "required": true,
+                    "acceptedValues": [
+                      "description",
+                      "technical-analysis",
+                      "weight",
+                      "due-at",
+                      "assignee",
+                      "milestone",
+                      "parent",
+                      "platforms"
+                    ]
+                  }
+                ]
+              },
+              {
+                "name": "--replace",
+                "description": "Send only the flags you passed (full replace — every field you omit is cleared server-side)"
               }
             ],
             "arguments": [
@@ -9192,7 +9936,10 @@
             ],
             "examples": [
               "closeyourit tickets update <ticket-id> --project acme-api --title \"New title\"",
-              "closeyourit tickets update <ticket-id> -p acme-api --title \"Login bug\" --scenarios '[{\"step_given\":\"logged out\",\"step_when\":\"I submit\",\"step_then\":\"it 500s\",\"step_expected\":\"dashboard loads\"}]' --condition \"login works\""
+              "closeyourit tickets update <ticket-id> -p acme-api --clear assignee --clear due-at",
+              "closeyourit tickets update <ticket-id> -p acme-api --title \"Login bug\" --scenarios '[{\"step_given\":\"logged out\",\"step_when\":\"I submit\",\"step_then\":\"it 500s\",\"step_expected\":\"dashboard loads\"}]' --condition \"login works\"",
+              "closeyourit tickets update <ticket-id> -p acme-api --status in_review --priority High",
+              "closeyourit tickets update <ticket-id> -p acme-api --replace --title \"Only this\" --status open --priority medium"
             ]
           },
           {