@bussolabs/closeyourit-cli 0.19.0 → 0.21.0

package/README.md

@@ -85,6 +85,16 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `vulnerabilities promote <id>` | Open a ticket from it — automatic promotion only fires on high/critical. |
 | `vulnerabilities rescan --project <id\|key>` | Rescan now, without waiting for the nightly run. |
 | `vulnerabilities runtimes [--project <id\|key>] [--page]` | Support state of the declared runtimes (Ruby, Node, Flutter…). |
+| `seo list [--project <id\|key>] [--severity] [--status] [--area] [--page]` | List the SEO findings of your sites, worst first. |
+| `seo show <id>` | Show one, with the evidence behind it. |
+| `seo pages [--project <id\|key>] [--url] [--page]` | The pages the check visited: status, title, h1, words. |
+| `seo ignore <id> [--note]` / `reopen <id>` | Accept living with a finding, or change your mind (requires seo.triage). |
+| `seo promote <id>` | Open a ticket from it, evidence included. |
+| `seo rescan --site <id>` | Check a site now, without waiting for the scheduled run (requires seo.manage). |
+| `seo-sites list [--project <id\|key>] [--page]` | The sites under SEO check, with cadence and open findings. |
+| `seo-sites create --project <id\|key> --url <url> --environment <id> [--frequency] [--max-pages] [--no-sitemap]` | Declare a site to watch; the first check starts right away. |
+| `seo-sites update <id> [--url] [--frequency] [--max-pages] [--sitemap\|--no-sitemap] [--enable\|--disable]` | Change how a site is checked. |
+| `seo-sites delete <id>` | Stop watching a site and remove its pages and findings. |
 | `tokens list --project <id\|key>` | List ingest tokens. |
 | `tokens create --project <id\|key> --name <name> --environment-id <id>` | Create a token (secret shown once). |
 | `tokens provision --project <id\|key> --name <name> --environment-id <code\|id> --to-project <id\|key> --to-environment-id <code\|id> --secret-name <NAME>` | Generate and deliver a token without revealing its value. GitHub sync is enabled by default; use `--no-sync-github` for vault-only delivery. |
@@ -99,9 +109,12 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `secrets assets shared-list\|shared-upload\|delegate\|undelegate …` | Manage one organization-level ciphertext and delegate it to authorized projects. |
 | `tickets list --project <id\|key> [--page]` | List tickets. |
 | `tickets show <id> --project <id\|key>` | Show one ticket. |
-| `tickets create --project <id\|key> --title <t> [--kind bug\|story\|task\|epic] [--parent-id] [--step-*] [--description] [--status-id] [--priority-id]` | Create a ticket. |
-| `tickets statuses` | List the org ticket statuses (id, code, label) — the id feeds `create --status-id`. |
-| `tickets priorities` | List the org ticket priorities (id, code, label) — the id feeds `create --priority-id`. |
+| `tickets create --project <id\|key> --title <t> [--kind bug\|story\|task\|epic] [--parent-id] [--step-*] [--description] [--status <code\|label\|id>] [--priority <code\|label\|id>]` | Create a ticket. `--status` defaults to `open` and `--priority` to `medium`, and both take a code or a label (`in_progress`, `"In Progress"`), so no id lookup is needed. Length caps: title 255, description 4000, technical analysis 1500 characters — every field over the cap is listed at once, before the call. |
+| `tickets statuses` | List the org ticket statuses (id, code, label) — any of the three works as `--status`. |
+| `tickets priorities` | List the org ticket priorities (id, code, label) — any of the three works as `--priority`. |
+| `tickets report <id\|code> --project <id\|key> (--body <text> \| --body-file <path>)` | Write the work report — the long text a comment cannot hold (max 20000 characters). Each write adds a version, it never overwrites the previous one. |
+| `tickets report-show <id\|code> --project <id\|key> [--version <n>]` | Show the current work report, or a past version. |
+| `tickets report-versions <id\|code> --project <id\|key> [--page]` | List the versions of the work report (newest first). |
 | `tickets reject <id> --project <id\|key> --reason <text>` | Reject the review: back to work, the reason becomes a comment. |
 | `tickets approve <id> --project <id\|key>` | Approve the review: move to the first done status. |
 | `tickets links <id> --project <id\|key>` | List the ticket-to-ticket links (duplicate/related) involving a ticket. |
@@ -128,11 +141,15 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `kb search <query…> [--project <id\|key>] [--kind] [--per] [--page] [--with-related]` | Search knowledge pages (semantic when available, title ILIKE fallback). |
 | `kb show <id> [--related] [--question <q>]` | Show one knowledge page: metadata header, raw markdown body, then the technical section. |
 | `kb related <id> [--question <q>] [--links-only]` | Pages to read next: linked with `[[wiki links]]` plus close matches by meaning. |
-| `kb create --project <id\|key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>]` | Create a knowledge page (optional technical section, kept separate from the body). With `--in-review` the page waits for a human and stays out of search, answers and related panels. |
+| `kb create --project <id\|key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>]` | Create a knowledge page (optional technical section, kept separate from the body). Length caps: title 255, body 4000, technical section 1500, review note 240 characters — every field over the cap is listed at once, before the call. With `--in-review` the page waits for a human and stays out of search, answers and related panels. |
+| `kb publish --project <id\|key> --publication-key <key> --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>)` | Create or update a knowledge page in one atomic call, keyed by a stable `--publication-key` (1-255 URL-safe characters). Safe to repeat: the same key always lands on the same page, and the output says whether it was `created` or `updated`. Exactly one body source is required. Omitting `--kind` keeps the kind the page already has (a new page is a `note`). Same title/body caps as `kb create`. |
 | `kb consolidate <id> --path <doc-path>` | Mark an accepted page as written to the versioned docs, recording where the document lives. |
-| `kb update <id> [--title] [--kind] [--body \| --body-file] [--tech-spec \| --tech-spec-file]` | Update a page (unpassed fields keep their current value). |
+| `kb update <id> [--title] [--kind] [--body \| --body-file] [--tech-spec \| --tech-spec-file]` | Update a page (unpassed fields keep their current value). Same length caps as `kb create`; text already over the cap is refused only if it grows. |
 | `kb delete <id> --confirm` | Delete a knowledge page (irreversible). |
 | `kb ask <question…>` | Ask a question; the AI answers from the knowledge base and cites the pages it used. |
+| `kb book list [--project <id\|key>] [--q <text>] [--per] [--page]` | List knowledge books (ordered collections of pages). Cross-project: omit `--project` for every visible project. |
+| `kb book show <id>` | Show a book: metadata, then the summary of the pages it collects (`#` is the 0-based position). |
+| `kb book add-page <id> --page <page-id> [--position <n>]` | Add a page to a book's summary. `--page` takes a page **id** (alias: `--page-id`), not a page number; `--position` is 0-based (`0` = top, omitted = last), like the position the summary shows back. Idempotent: repeating it never lists the page twice. |
 | `servers list [--status] [--page]` | List the monitored servers (fleet snapshot: status, cpu/mem/disk, last seen). |
 | `servers show <id>` | Show a monitored server (latest snapshot + machine details). |
 | `servers rename <id> --name <name>` | Rename a server (display name only). |
@@ -219,6 +236,23 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 Every command accepts `--json` for machine-readable output and `--help` for usage details.
 `--project` accepts either a project UUID or its key (matched case-insensitively).
 
+`kb publish` needs a backend exposing the atomic Knowledge publication route; an older one fails with
+`C404-KNW-001` and says to upgrade. An unknown project key fails locally with `C404-PRJ-001`; the
+backend `R404-KNOWLEDGE-001` is reserved for a project UUID that is missing or not visible to the
+caller. `R403-KNOWLEDGE-003` means the key already belongs to a page you cannot manage, and
+`R409-KNOWLEDGE-001` that two untagged pages share the title the key would adopt.
+
+When a command fails in `--json` mode it exits non-zero and prints an error envelope on stdout —
+never a silent success:
+
+```json
+{ "error": { "code": "C400-INP-001", "message": "Missing required flag project" } }
+```
+
+`C400-INP-001` means the command line itself needs fixing (missing flag or argument, unknown flag,
+missing `--confirm`) and `message` says what; `C500-SYS-001` is reserved for unexpected failures.
+Codes starting with `R`/`G` come straight from the backend.
+
 ## Configuration
 
 The CLI stores its state in:

package/dist/base.d.ts

@@ -1,6 +1,7 @@
 import { Command, type Interfaces } from '@oclif/core';
 import { type CliConfig } from './lib/config';
 import { CliApi } from './lib/api';
+import { type TicketLookup } from './lib/ticket-lookup';
 export declare const UUID_RE: RegExp;
 /** Shared `--project <id|key>` flag (required). */
 export declare const projectFlag: {
@@ -14,6 +15,17 @@ export declare const environmentFlag: {
 export declare const pageFlag: {
     page: Interfaces.OptionFlag<number, Interfaces.CustomOptions>;
 };
+/**
+ * Message for a `--page`/`--per` outside the sensible range, or undefined when both are fine.
+ *
+ * The backend silently clamps them (`Pagination`): `--per 0` quietly returns the default page size
+ * and `--page 0` returns page 1, so a script that computed the wrong number gets plausible data
+ * back instead of an error. Say it before the call, and exit 2 like any other rejected command line.
+ */
+export declare function paginationError(opts: {
+    page?: number;
+    per?: number;
+}): string | undefined;
 export declare abstract class BaseCommand extends Command {
     static enableJsonFlag: boolean;
     protected cfg: CliConfig;
@@ -33,6 +45,16 @@ export declare abstract class BaseCommand extends Command {
     protected resolveTeamId(value: string): Promise<string>;
     /** Resolve a member reference (UUID account id passes through; otherwise matched by email). */
     protected resolveMemberId(value: string): Promise<string>;
+    /**
+     * Resolve a ticket status/priority reference: a UUID passes through, anything else is matched
+     * against the organization lookup by code first, then by label (case-insensitive).
+     *
+     * `undefined` means the flag was not passed, so the lookup's own default applies (`open`,
+     * `medium`): the server demands both fields on a new ticket while the help gave them as optional,
+     * and getting through used to take two id hunts (`tickets statuses`, `tickets priorities`) and a
+     * pair of UUIDs pasted by hand (CYCL-34).
+     */
+    protected resolveTicketLookupId(lookup: TicketLookup, value?: string): Promise<string>;
     /** Resolve each value of a list to an id, preserving order. */
     protected resolveAll(values: string[], resolve: (value: string) => Promise<string>): Promise<string[]>;
     /** Resolve an `{id, name}` reference by name (UUID passes through). */

package/dist/base.js

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseCommand = exports.pageFlag = exports.environmentFlag = exports.projectFlag = exports.UUID_RE = void 0;
+exports.paginationError = paginationError;
 const core_1 = require("@oclif/core");
 const config_1 = require("./lib/config");
 const api_1 = require("./lib/api");
 const output_1 = require("./lib/output");
 const error_codes_1 = require("./errors/error-codes");
+const input_error_1 = require("./errors/input-error");
+const ticket_lookup_1 = require("./lib/ticket-lookup");
 exports.UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Shared `--project <id|key>` flag (required). */
 exports.projectFlag = {
@@ -19,6 +22,20 @@ exports.environmentFlag = {
 exports.pageFlag = {
     page: core_1.Flags.integer({ description: 'Page number', default: 1 }),
 };
+/**
+ * Message for a `--page`/`--per` outside the sensible range, or undefined when both are fine.
+ *
+ * The backend silently clamps them (`Pagination`): `--per 0` quietly returns the default page size
+ * and `--page 0` returns page 1, so a script that computed the wrong number gets plausible data
+ * back instead of an error. Say it before the call, and exit 2 like any other rejected command line.
+ */
+function paginationError(opts) {
+    if (opts.page !== undefined && opts.page < 1)
+        return `Invalid --page ${opts.page}: the first page is 1.`;
+    if (opts.per !== undefined && opts.per < 1)
+        return `Invalid --per ${opts.per}: ask for at least 1 row.`;
+    return undefined;
+}
 class BaseCommand extends core_1.Command {
     static enableJsonFlag = true;
     cfg;
@@ -72,6 +89,25 @@ class BaseCommand extends core_1.Command {
         }
         return match.account_id;
     }
+    /**
+     * Resolve a ticket status/priority reference: a UUID passes through, anything else is matched
+     * against the organization lookup by code first, then by label (case-insensitive).
+     *
+     * `undefined` means the flag was not passed, so the lookup's own default applies (`open`,
+     * `medium`): the server demands both fields on a new ticket while the help gave them as optional,
+     * and getting through used to take two id hunts (`tickets statuses`, `tickets priorities`) and a
+     * pair of UUIDs pasted by hand (CYCL-34).
+     */
+    async resolveTicketLookupId(lookup, value) {
+        const wanted = value ?? lookup.fallback;
+        if (exports.UUID_RE.test(wanted))
+            return wanted;
+        const rows = (await this.api.get(lookup.path)).data;
+        const matches = (0, ticket_lookup_1.matchTicketLookup)(rows, wanted);
+        if (matches.length === 1)
+            return matches[0].id;
+        throw new api_1.ApiRequestError(404, lookup.errorCode, (0, ticket_lookup_1.ticketLookupErrorMessage)(lookup, wanted, rows, { matched: matches.length, isDefault: value === undefined }));
+    }
     /** Resolve each value of a list to an id, preserving order. */
     resolveAll(values, resolve) {
         return Promise.all(values.map((value) => resolve(value)));
@@ -102,6 +138,16 @@ class BaseCommand extends core_1.Command {
             }
             return this.exit(1);
         }
+        // A rejected command line is not a server failure: oclif refuses it before the command body runs
+        // (missing required flag/arg, nonexistent flag, value outside the options) and the `this.error(...)`
+        // guards refuse it inside. Both used to collapse into the generic C500-SYS-001 "Command failed" in
+        // --json, so a script could not tell a forgotten flag from an outage. Emit the same message the
+        // human mode prints, under a dedicated code (CYCL-33). Human mode is untouched: oclif keeps
+        // rendering its own error plus the usage help.
+        if ((0, input_error_1.isInputError)(error) && this.jsonEnabled()) {
+            this.logJson({ error: { code: error_codes_1.ErrorCodes.Input.invalid, message: (0, input_error_1.inputErrorMessage)(error) } });
+            return this.exit(1);
+        }
         // Oclif's default JSON formatter serializes the complete CommandError. That object references
         // the command instance and therefore cfg/api.config, including the bearer token. Never pass an
         // unknown error to that formatter in JSON mode: emit a deliberately small allow-listed envelope.

package/dist/commands/alerts/notifications/read-all.js

@@ -5,6 +5,9 @@ class AlertsNotificationsReadAll extends base_1.BaseCommand {
     static description = 'Mark all your unread notifications as read';
     static examples = ['<%= config.bin %> alerts notifications read-all'];
     async run() {
+        // Validate the command line before marking anything read: a mistyped flag must stop the
+        // command instead of being ignored (CYCL-33).
+        await this.parse(AlertsNotificationsReadAll);
         const res = await this.api.put('/cli/v1/alert_notifications/read_all');
         if (!this.jsonEnabled()) {
             this.log(`Marked ${res.data?.marked_read ?? 0} notification(s) read`);

package/dist/commands/alerts/preferences/show.js

@@ -6,6 +6,8 @@ class AlertsPreferencesShow extends base_1.BaseCommand {
     static description = 'Show your personal alert preferences (per organization)';
     static examples = ['<%= config.bin %> alerts preferences show'];
     async run() {
+        // No flags of its own, but the parser is what rejects a mistyped one (CYCL-33).
+        await this.parse(AlertsPreferencesShow);
         const res = await this.api.get('/cli/v1/alert_preferences');
         if (!this.jsonEnabled()) {
             this.log((0, output_1.renderRecord)(res.data ?? {}));

package/dist/commands/ideas/convert.d.ts

@@ -6,11 +6,11 @@ export default class IdeasConvert extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        status: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        priority: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         title: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         kind: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'status-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-        'priority-id': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<unknown>;

package/dist/commands/ideas/convert.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const base_1 = require("../../base");
+const limits_1 = require("../../lib/limits");
 const output_1 = require("../../lib/output");
+const ticket_lookup_1 = require("../../lib/ticket-lookup");
 class IdeasConvert extends base_1.BaseCommand {
     static args = {
         id: core_1.Args.string({ description: 'Idea id', required: true }),
@@ -14,14 +16,28 @@ class IdeasConvert extends base_1.BaseCommand {
     ];
     static flags = {
         ...base_1.projectFlag,
-        title: core_1.Flags.string({ description: 'Ticket title (skips AI when set together with --description)' }),
-        description: core_1.Flags.string({ description: 'Ticket description (skips AI when set together with --title)' }),
+        // Il ticket nasce qui, quindi valgono i tetti di `tickets create` (CYCL-32).
+        title: core_1.Flags.string({
+            description: `Ticket title (skips AI when set together with --description, max ${limits_1.LENGTH_LIMITS.title} characters)`,
+        }),
+        description: core_1.Flags.string({
+            description: `Ticket description (skips AI when set together with --title, max ${limits_1.LENGTH_LIMITS.description} characters)`,
+        }),
         kind: core_1.Flags.string({ description: 'Ticket kind (default: story)', options: ['bug', 'story', 'task', 'epic'] }),
-        'status-id': core_1.Flags.string({ description: 'Status lookup id (default: open)' }),
-        'priority-id': core_1.Flags.string({ description: 'Priority lookup id (default: medium)' }),
+        // Il ticket nasce qui: stato e priorità si indicano per code o etichetta, e omettendoli vale il
+        // predefinito che il server applica alla conversione (CYCL-34).
+        ...ticket_lookup_1.newTicketLookupFlags,
     };
     async run() {
         const { args, flags } = await this.parse(IdeasConvert);
+        // Il ticket è nuovo: niente da salvaguardare, tetto pieno, e i campi troppo lunghi si leggono
+        // tutti in questo unico rifiuto — prima dei ~30 secondi di sintesi AI, non dopo.
+        const tooLong = (0, limits_1.tooLongMessage)([
+            { flag: '--title', value: flags.title, max: limits_1.LENGTH_LIMITS.title, orthography: true },
+            { flag: '--description', value: flags.description, max: limits_1.LENGTH_LIMITS.description, orthography: true },
+        ]);
+        if (tooLong)
+            this.error(tooLong, { exit: 2 });
         const projectId = await this.resolveProjectId(flags.project);
         const body = {};
         if (flags.title !== undefined)
@@ -30,10 +46,11 @@ class IdeasConvert extends base_1.BaseCommand {
             body.description = flags.description;
         if (flags.kind !== undefined)
             body.kind = flags.kind;
-        if (flags['status-id'] !== undefined)
-            body.status_id = flags['status-id'];
-        if (flags['priority-id'] !== undefined)
-            body.priority_id = flags['priority-id'];
+        if (flags.status !== undefined)
+            body.status_id = await this.resolveTicketLookupId(ticket_lookup_1.TICKET_STATUS, flags.status);
+        if (flags.priority !== undefined) {
+            body.priority_id = await this.resolveTicketLookupId(ticket_lookup_1.TICKET_PRIORITY, flags.priority);
+        }
         if (!this.jsonEnabled() && (flags.title === undefined || flags.description === undefined)) {
             this.log('Synthesizing the ticket draft with AI (idea + comments), this may take ~30s…');
         }

package/dist/commands/kb/book/add-page.d.ts

@@ -0,0 +1,18 @@
+import { BaseCommand } from '../../../base';
+/**
+ * Put one page in a book's summary. Idempotent server-side: repeating the same call leaves the
+ * summary as it is (the page is moved, never added twice), which is what makes it safe for an
+ * automation that cannot know whether the previous run got through.
+ */
+export default class KbBookAddPage extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        page: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        position: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/book/add-page.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const knowledge_1 = require("../../../lib/knowledge");
+/**
+ * Put one page in a book's summary. Idempotent server-side: repeating the same call leaves the
+ * summary as it is (the page is moved, never added twice), which is what makes it safe for an
+ * automation that cannot know whether the previous run got through.
+ */
+class KbBookAddPage extends base_1.BaseCommand {
+    static description = 'Add a knowledge page to a book, optionally at a given position in the summary';
+    static examples = [
+        '<%= config.bin %> kb book add-page <book-id> --page <page-id>',
+        '<%= config.bin %> kb book add-page <book-id> --page <page-id> --position 0',
+        '<%= config.bin %> kb book add-page <book-id> --page <page-id> --json',
+    ];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge book id', required: true }),
+    };
+    static flags = {
+        // `--page` is the name the Automator already calls (closeyourit-automator, lib/book.ts
+        // `assignPage`), and this command has no pagination, so there is nothing to collide with. It
+        // still takes a page *id*, unlike the `--page` of every list command: `--page-id` is accepted
+        // as an alias so a human can be explicit about that.
+        page: core_1.Flags.string({
+            aliases: ['page-id'],
+            description: 'Id of the knowledge page to add (an id, not a page number; alias: --page-id)',
+            required: true,
+        }),
+        // 0-based, like the server (Knowledge::Books::AddPage) and like the `position` the summary
+        // shows back. A caller counting from 1 must subtract one: passing its own number would put the
+        // page one slot too low, and the backend clamps instead of refusing.
+        position: core_1.Flags.integer({ description: 'Where to put it in the summary (0 = top; omit to append at the end)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(KbBookAddPage);
+        if (flags.position !== undefined && flags.position < 0) {
+            this.error(`Invalid --position ${flags.position}: the summary starts at 0 (the top).`, { exit: 2 });
+        }
+        // `!== undefined`, not a truthiness test: position 0 is the top of the summary, not "unset".
+        const body = { page_id: flags.page };
+        if (flags.position !== undefined)
+            body.position = flags.position;
+        const res = await this.api.post(`/cli/v1/knowledge/books/${encodeURIComponent(args.id)}/pages`, body);
+        if (!this.jsonEnabled()) {
+            // "updated", not "added": the call is idempotent, so on a repeat nothing was inserted — what
+            // is worth showing either way is the resulting order.
+            this.log('Book summary updated:');
+            this.log((0, knowledge_1.renderBook)(res.data ?? {}));
+        }
+        return res;
+    }
+}
+exports.default = KbBookAddPage;

package/dist/commands/kb/book/list.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '../../../base';
+export default class KbBookList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        page: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        q: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        per: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/book/list.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const knowledge_1 = require("../../../lib/knowledge");
+class KbBookList extends base_1.BaseCommand {
+    static description = 'List knowledge books (ordered collections of pages) across the projects you can see';
+    static examples = [
+        '<%= config.bin %> kb book list',
+        '<%= config.bin %> kb book list --project acme-api',
+        '<%= config.bin %> kb book list --q deploy --per 50',
+        '<%= config.bin %> kb book list --json',
+    ];
+    static flags = {
+        // Optional (the endpoint is cross-project): omit it to span every visible project.
+        project: core_1.Flags.string({ char: 'p', description: 'Filter by project (key or UUID)' }),
+        q: core_1.Flags.string({ description: 'Filter by title (substring, case-insensitive)' }),
+        per: core_1.Flags.integer({ description: 'Page size' }),
+        ...base_1.pageFlag,
+    };
+    async run() {
+        const { flags } = await this.parse(KbBookList);
+        const invalid = (0, base_1.paginationError)(flags);
+        if (invalid)
+            this.error(invalid, { exit: 2 });
+        const res = await this.api.get(`/cli/v1/knowledge/books?${(0, knowledge_1.buildBooksQuery)(flags)}`);
+        if (!this.jsonEnabled()) {
+            this.log((0, knowledge_1.renderBooksTable)(res.data ?? []));
+        }
+        return res;
+    }
+}
+exports.default = KbBookList;

package/dist/commands/kb/book/show.d.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from '../../../base';
+export default class KbBookShow extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        id: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/kb/book/show.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../../base");
+const knowledge_1 = require("../../../lib/knowledge");
+class KbBookShow extends base_1.BaseCommand {
+    static description = 'Show a knowledge book: its metadata, then the summary of the pages it collects';
+    static examples = ['<%= config.bin %> kb book show <book-id>', '<%= config.bin %> kb book show <book-id> --json'];
+    static args = {
+        id: core_1.Args.string({ description: 'Knowledge book id', required: true }),
+    };
+    async run() {
+        const { args } = await this.parse(KbBookShow);
+        const res = await this.api.get(`/cli/v1/knowledge/books/${encodeURIComponent(args.id)}`);
+        // The summary only lists the pages of the projects the reader can see, so a multi-project book
+        // never shows titles from a project this account has no access to.
+        if (!this.jsonEnabled())
+            this.log((0, knowledge_1.renderBook)(res.data ?? {}));
+        return res;
+    }
+}
+exports.default = KbBookShow;

package/dist/commands/kb/create.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const promises_1 = require("node:fs/promises");
 const core_1 = require("@oclif/core");
 const base_1 = require("../../base");
+const limits_1 = require("../../lib/limits");
 const output_1 = require("../../lib/output");
 class KbCreate extends base_1.BaseCommand {
     static description = 'Create a knowledge page in a project';
@@ -15,21 +16,31 @@ class KbCreate extends base_1.BaseCommand {
     static flags = {
         // Required — passed straight to the server as `project` (key or UUID), resolved there.
         ...base_1.projectFlag,
-        title: core_1.Flags.string({ description: 'Page title', required: true }),
+        title: core_1.Flags.string({ description: `Page title (max ${limits_1.LENGTH_LIMITS.title} characters)`, required: true }),
         kind: core_1.Flags.string({ description: 'Page kind: note|decision|guide', default: 'note' }),
-        body: core_1.Flags.string({ description: 'Page body (markdown)' }),
-        'body-file': core_1.Flags.string({ description: 'Read the body (markdown) from a local file' }),
-        'tech-spec': core_1.Flags.string({ description: 'Technical section, kept separate from the simple body' }),
-        'tech-spec-file': core_1.Flags.string({ description: 'Read the technical section from a local file' }),
+        body: core_1.Flags.string({ description: `Page body (markdown, max ${limits_1.LENGTH_LIMITS.pageBody} characters)` }),
+        'body-file': core_1.Flags.string({
+            description: `Read the body (markdown, max ${limits_1.LENGTH_LIMITS.pageBody} characters) from a local file`,
+        }),
+        'tech-spec': core_1.Flags.string({
+            description: `Technical section, kept separate from the simple body (max ${limits_1.LENGTH_LIMITS.techSpec} characters)`,
+        }),
+        'tech-spec-file': core_1.Flags.string({
+            description: `Read the technical section (max ${limits_1.LENGTH_LIMITS.techSpec} characters) from a local file`,
+        }),
         // Propose instead of publish: the page waits for a human in the review queue and stays out of
         // search, answers and related panels until it is accepted (see `kb list --status in_review`).
         'in-review': core_1.Flags.boolean({ description: 'Create the page in review instead of publishing it' }),
-        'review-note': core_1.Flags.string({ description: 'One line explaining why the page is worth keeping (review queue)' }),
+        'review-note': core_1.Flags.string({
+            description: `One line explaining why the page is worth keeping (review queue, max ${limits_1.LENGTH_LIMITS.reviewNote} characters)`,
+        }),
     };
     async run() {
         const { flags } = await this.parse(KbCreate);
         let body = flags.body;
+        let bodyFlag = '--body';
         if (body === undefined && flags['body-file'] !== undefined) {
+            bodyFlag = '--body-file';
             try {
                 body = await (0, promises_1.readFile)(flags['body-file'], 'utf8');
             }
@@ -41,7 +52,9 @@ class KbCreate extends base_1.BaseCommand {
             this.error('Provide the page body via --body or --body-file.', { exit: 2 });
         }
         let techSpec = flags['tech-spec'];
+        let techSpecFlag = '--tech-spec';
         if (techSpec === undefined && flags['tech-spec-file'] !== undefined) {
+            techSpecFlag = '--tech-spec-file';
             try {
                 techSpec = await (0, promises_1.readFile)(flags['tech-spec-file'], 'utf8');
             }
@@ -52,6 +65,16 @@ class KbCreate extends base_1.BaseCommand {
         if (flags['review-note'] !== undefined && !flags['in-review']) {
             this.error('--review-note only applies to a page created with --in-review.', { exit: 2 });
         }
+        // Una pagina nuova non ha niente da salvaguardare: il tetto vale pieno su ogni campo, e i campi
+        // troppo lunghi si leggono tutti in questo unico rifiuto invece che uno per tentativo (CYCL-32).
+        const tooLong = (0, limits_1.tooLongMessage)([
+            { flag: '--title', value: flags.title, max: limits_1.LENGTH_LIMITS.title },
+            { flag: bodyFlag, value: body, max: limits_1.LENGTH_LIMITS.pageBody },
+            { flag: techSpecFlag, value: techSpec, max: limits_1.LENGTH_LIMITS.techSpec },
+            { flag: '--review-note', value: flags['review-note'], max: limits_1.LENGTH_LIMITS.reviewNote },
+        ]);
+        if (tooLong)
+            this.error(tooLong, { exit: 2 });
         const res = await this.api.post('/cli/v1/knowledge/pages', {
             project: flags.project,
             title: flags.title,

package/dist/commands/kb/publish.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../../base';
+export default class KbPublish extends BaseCommand {
+    static description: string;
+    static usage: string;
+    static examples: string[];
+    static flags: {
+        'publication-key': import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        kind: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        body: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'body-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}