@bussolabs/closeyourit-cli 0.25.1 → 0.27.0

package/README.md

@@ -157,14 +157,16 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `logs link <id> --to <Errors::Group:uuid\|Ticketing::Ticket:uuid>` | Manually link a log entry to an error group or ticket. |
 | `logs unlink <id> <link-id> --confirm` | Remove a manual log link. |
 | `kb list [--project <id\|key>] [--kind] [--status] [--awaiting-consolidation] [--per] [--page]` | List knowledge pages. Cross-project: omit `--project` for every visible project. Published only unless `--status` says otherwise. |
-| `kb search <query…> [--project <id\|key>] [--kind] [--per] [--page] [--with-related]` | Search knowledge pages (semantic when available, title ILIKE fallback). |
+| `kb search <query…> [--project <id\|key>] [--kind] [--status] [--per] [--page] [--with-related]` | Search knowledge pages (semantic when available, title ILIKE fallback). Accepted pages only unless `--status` says otherwise: `--status all` also searches the proposals waiting for review and the rejected ones, so a duplicate that is not accepted yet shows up before you propose it again. Results carry a `STATUS` column as soon as one row is not published. |
 | `kb show <id> [--related] [--question <q>]` | Show one knowledge page: metadata header (every project it belongs to, its groups and tags), 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>…] [--group <id\|name>…] [--tag <tag>…] --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>] [--author-origin <name>]` | Create a knowledge page (optional technical section, kept separate from the body). `--project`, `--group` and `--tag` are repeatable — a page can belong to several projects and groups at once, and to groups alone; at least one project or group is required. 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. `--author-origin` declares the assistant or skill that wrote the text, which is not the owner of the token. |
+| `kb context [--project <id\|key>] [--limit] [--quiet] [--timeout <seconds>]` | Print the knowledge context of the current project: the short list of pages whoever starts working here should already know. Without `--project` the project is resolved from the `origin` git remote of the current directory (project → repository map). `--quiet` never fails — outside a project it prints nothing, on an unreachable service one line — so a session-start hook can call it blindly. `KB_CONTEXT_DISABLE=1` turns it off. |
+| `kb create [--project <id\|key>…] [--group <id\|name>…] [--tag <tag>…] --title <t> [--kind note\|decision\|guide] (--body <md> \| --body-file <path>) [--tech-spec <md> \| --tech-spec-file <path>] [--in-review] [--review-note <line>] [--author-origin <name>]` | Create a knowledge page (optional technical section, kept separate from the body). `--project`, `--group` and `--tag` are repeatable — a page can belong to several projects and groups at once, and to groups alone; at least one project or group is required. 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 ordinary search, answers and related panels — `kb search --status in_review\|all` finds it on purpose, so nobody proposes the same page twice. `--author-origin` declares the assistant or skill that wrote the text, which is not the owner of the token. |
 | `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 approve <id>` | Accept a page waiting for review: it enters search, answers and related panels. A human decision: a service token is refused, and a page the automatic reviewer rejected must be fixed and saved first. |
-| `kb reject <id>` | Discard a page waiting for review: it stays archived as rejected, out of search and answers, so it is not proposed again. Nothing is deleted. |
+| `kb reject <id>` | Discard a page waiting for review: it stays archived as rejected, out of ordinary search and answers (`kb search --status rejected\|all` still finds it), so it is not proposed again. Nothing is deleted. |
 | `kb consolidate <id> --path <doc-path>` | Mark an accepted page as written to the versioned docs, recording where the document lives. |
+| `kb doctor [--project <id\|key>] [--stale-days <n>] [--docs-root <path>] [--limit <n>]` | Check the health of the knowledge base: pages no search can find, `[[wiki links]]` pointing nowhere, proposals nobody decided, accepted pages never filed, and — with `--docs-root` — filed documents missing from the repository on this machine. Every check reports its outcome, what it means and the safe next step; nothing is ever changed. Exits 1 when a check fails, 0 on warnings alone. `--project` narrows the scan but marks the two organization-wide checks (`duplicate-title`, `dangling-link`) as skipped, because the service resolves those across every project. `--limit` caps how many pages each listing reads (default 500) and the report says when it stopped short. |
 | `kb update <id> [--title] [--kind] [--body \| --body-file] [--tech-spec \| --tech-spec-file] [--project <id\|key>…] [--group <id\|name>…] [--tag <tag>…] [--author-origin <name>]` | Update a page (unpassed fields keep their current value — including projects, groups, tags and attachments). Passing `--project`, `--group` or `--tag` **replaces** that list with what you name; `--tag ""` clears the tags. Changing only scope or tags never rewrites the text, so a concurrent edit is not overwritten. 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 attachments <id>` | List every file attached to a knowledge page — all pages, never truncated (`SCRIPT` says whether the server considers it executable). |
@@ -175,6 +177,7 @@ CLOSEYOURIT_TOKEN=cyi_u_… CLOSEYOURIT_API_URL=https://www.closeyour.it \
 | `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. |
+| `mcp [--timeout <seconds>]` | Serve the knowledge base over the Model Context Protocol on stdin/stdout, so any MCP-speaking assistant can search it, ask it, read pages and propose new ones with your own access. Started by the client as a subprocess — see [Connecting an assistant (MCP)](#connecting-an-assistant-mcp). |
 | `assistant ask <question…> [--conversation <id>] [--timeout <seconds>]` | Ask the assistant a question about your own data; it reads what you are allowed to see, answers, and lists the tools it used. Prints the conversation id so the next question can keep the context (`--conversation <id>`). |
 | `assistant conversations list [--per] [--page]` | List your conversations with the assistant, most recently active first. |
 | `assistant conversations create [--title]` | Open an empty conversation; without `--title` the server names it after its first question. |
@@ -285,6 +288,89 @@ backend `R404-KNOWLEDGE-001` is reserved for a project UUID that is missing or n
 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.
 
+### Knowledge at the start of a session
+
+`kb context` is built to be called by a `SessionStart` hook, so what the project already learned is
+on screen before anyone asks for it. In `--quiet` mode it never gets in the way: a directory that is
+not a project prints nothing, an unreachable service costs one line, and both exit 0.
+
+```bash
+#!/usr/bin/env bash
+# SessionStart hook: stdout becomes the session's additional context.
+command -v cyi >/dev/null 2>&1 || exit 0
+cyi kb context --quiet --limit 5 --timeout 3 2>/dev/null
+exit 0
+```
+
+`kb context` reads the context route of the backend and falls back to the project's page list on a
+server that does not expose it yet, so the list shows up either way.
+
+### Connecting an assistant (MCP)
+
+`cyi mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio: the same
+procedure works for every assistant that speaks MCP, so reaching the knowledge base no longer means
+writing instructions for one particular tool.
+
+Most clients declare their servers in a JSON file. Add this entry under the key your client uses —
+`mcpServers` for Claude Code, Cursor, Windsurf and most others, `context_servers` for
+[Zed](https://zed.dev/docs/ai/mcp):
+
+```json
+{
+  "mcpServers": {
+    "closeyourit": {
+      "command": "cyi",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The client launches it as a subprocess; there is nothing to start or keep running by hand.
+
+It authenticates exactly like the terminal does, with the token `cyi login` already stored in
+`~/.config/closeyourit/config.json` (mode 0600). In the ordinary case the entry above is the whole
+configuration and no secret goes anywhere near it.
+
+For a service account, keep the token out of that file too — a client configuration is a dotfile
+like any other and frequently ends up committed. Export `CLOSEYOURIT_TOKEN` into the environment the
+client is started from, taking it from wherever the secret already lives, rather than writing the
+value into JSON:
+
+```bash
+CLOSEYOURIT_TOKEN=cyi_u_… your-editor-or-agent
+```
+
+Six tools are exposed, each one the call its command already makes:
+
+| Tool | What it does |
+| --- | --- |
+| `kb_search` | Search the pages (`kb search`). Accepted pages only, unless `status` says otherwise — `"all"` also finds the proposals waiting for review. |
+| `kb_ask` | Ask a question and get an answer with its sources (`kb ask`). |
+| `kb_show` | Read one page in full (`kb show`). |
+| `kb_related` | The pages to read next (`kb related`). |
+| `kb_context` | What to know about the project of the working directory (`kb context`). |
+| `kb_propose` | Propose a new page — **always** into the review queue (`kb create --in-review`). |
+
+Two things hold whatever the assistant asks for. `kb_propose` sends `in_review` and nothing else:
+the page waits for a person to accept it and stays out of ordinary search, answers and related
+panels until then — `kb_search` with `status: "all"` looks it up on purpose, before proposing a
+duplicate. There is no tool here that publishes, accepts, edits or deletes. And every call travels on
+your own token, so a project your access does not include returns nothing, exactly as it does from
+the terminal.
+
+`kb_context` recognises the project from the git remote of the directory the client started the
+server in. Clients that launch it elsewhere can name the project instead (`project`), or pass it to
+every call.
+
+To check the server by hand, talk to it the way a client would:
+
+```bash
+printf '%s\n' \
+  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
+  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | cyi mcp
+```
+
 When a command fails in `--json` mode it exits non-zero and prints an error envelope on stdout —
 never a silent success:
 
@@ -315,9 +401,10 @@ to clear it locally; revoke the token on the server at `/account/cli/tokens`.
 
 | Variable | Purpose | Default |
 | --- | --- | --- |
-| `CLOSEYOURIT_TOKEN` | User token (`cyi_u_…`) for headless/CI/agent use; overrides the stored config token. | — |
+| `CLOSEYOURIT_TOKEN` | User token (`cyi_u_…`) for headless/CI/agent use, including the `mcp` server; overrides the stored config token. | — |
 | `CLOSEYOURIT_API_URL` | Default backend base URL (overridden by a persisted `--api-url`). | `https://www.closeyour.it` |
 | `CLOSEYOURIT_CONFIG_DIR` | Directory holding `config.json`. | `~/.config/closeyourit` |
+| `KB_CONTEXT_DISABLE` | Set to `1` to make `kb context` print nothing and call nothing (the switch a session-start hook honours). | — |
 
 ## Development
 

package/dist/base.d.ts

@@ -3,7 +3,7 @@ import type { ArgOutput, FlagOutput, Input, ParserOutput } from '@oclif/core/lib
 import { type CliConfig } from './lib/config';
 import { CliApi } from './lib/api';
 import { type TicketLookup } from './lib/ticket-lookup';
-export declare const UUID_RE: RegExp;
+export { UUID_RE } from './lib/lookup';
 /** Shared `--project <id|key>` flag (required). */
 export declare const projectFlag: {
     project: Interfaces.OptionFlag<string, Interfaces.CustomOptions>;
@@ -43,11 +43,7 @@ export declare abstract class BaseCommand extends Command {
     init(): Promise<void>;
     /** Parse as oclif does, then hand `--yes` to the api client before any request leaves. */
     protected parse<F extends FlagOutput, B extends FlagOutput, A extends ArgOutput>(options?: Input<F, B, A>, argv?: string[]): Promise<ParserOutput<F, B, A>>;
-    /**
-     * Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive).
-     * Walks every page of `/cli/v1/projects`: a key can live past the first page, so a single-page
-     * lookup would 404 keys like legalbloom LBRA/LBWB while their UUID (and first-page keys) worked (CYCL-1).
-     */
+    /** Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive). */
     protected resolveProjectId(value: string): Promise<string>;
     /** Resolve a role reference (UUID passes through; otherwise matched by name, case-insensitive). */
     protected resolveRoleId(value: string): Promise<string>;
@@ -81,18 +77,7 @@ export declare abstract class BaseCommand extends Command {
     protected resolveAll(values: string[], resolve: (value: string) => Promise<string>): Promise<string[]>;
     /** Resolve an `{id, name}` reference by name (UUID passes through). */
     private resolveByName;
-    /**
-     * Every row of an organization lookup (teams, roles, groups, members) — all its pages.
-     *
-     * The server serves ten per page: stopping at the first made the eleventh team or the eleventh
-     * person invisible, and a perfectly good name or email came back as "not found" (CYCL-42, the
-     * lesson `resolveProjectId` already learned on project keys in CYCL-1).
-     *
-     * A 403 here is not about the command being run: listing teams needs `permissions.manage` and
-     * listing members `members.view`, permissions that a team workload board never asks for. Left
-     * alone it would read as "Permesso negato" on an operation the caller is entitled to, so the
-     * refusal carries the way out instead — name the id, skip the lookup.
-     */
+    /** Every row of an organization lookup (teams, roles, groups, members) — all its pages. */
     private fetchLookupRows;
     /**
      * Surface API errors, then exit non-zero. In `--json` mode `logToStderr` is a no-op, so emit the

package/dist/base.js

@@ -9,7 +9,11 @@ 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;
+const lookup_1 = require("./lib/lookup");
+// La ricerca per riferimento leggibile sta in `lib/lookup`: la usano i comandi da qui e il server
+// MCP direttamente (CYCL-56). Ri-esportata perché è già il nome che i comandi importano da `base`.
+var lookup_2 = require("./lib/lookup");
+Object.defineProperty(exports, "UUID_RE", { enumerable: true, get: function () { return lookup_2.UUID_RE; } });
 /** Shared `--project <id|key>` flag (required). */
 exports.projectFlag = {
     project: core_1.Flags.string({ char: 'p', description: 'Project id (UUID) or key', required: true }),
@@ -68,26 +72,9 @@ class BaseCommand extends core_1.Command {
             this.api.confirm = parsed.flags.yes === true;
         return parsed;
     }
-    /**
-     * Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive).
-     * Walks every page of `/cli/v1/projects`: a key can live past the first page, so a single-page
-     * lookup would 404 keys like legalbloom LBRA/LBWB while their UUID (and first-page keys) worked (CYCL-1).
-     */
-    async resolveProjectId(value) {
-        if (exports.UUID_RE.test(value))
-            return value;
-        let page = 1;
-        let totalPages = 1;
-        do {
-            // eslint-disable-next-line no-await-in-loop
-            const res = await this.api.get(`/cli/v1/projects?page=${page}&per=100`);
-            const match = (res.data ?? []).find((project) => (project.key ?? '').toLowerCase() === value.toLowerCase());
-            if (match)
-                return match.id;
-            totalPages = Number(res.meta?.total_pages ?? 1);
-            page += 1;
-        } while (page <= totalPages);
-        throw new api_1.ApiRequestError(404, error_codes_1.ErrorCodes.Project.notFound, `Project not found: ${value}`);
+    /** Resolve a project reference (UUID passes through; otherwise matched by key, case-insensitive). */
+    resolveProjectId(value) {
+        return (0, lookup_1.resolveProjectId)(this.api, value);
     }
     /** Resolve a role reference (UUID passes through; otherwise matched by name, case-insensitive). */
     resolveRoleId(value) {
@@ -103,7 +90,7 @@ class BaseCommand extends core_1.Command {
     }
     /** Resolve a member reference (UUID account id passes through; otherwise matched by email). */
     async resolveMemberId(value) {
-        if (exports.UUID_RE.test(value))
+        if (lookup_1.UUID_RE.test(value))
             return value;
         const rows = await this.fetchLookupRows('/cli/v1/members', 'Listing the organization members needs the members.view permission — pass the account id instead of the email.');
         const match = rows.find((m) => (m.email ?? '').toLowerCase() === value.toLowerCase());
@@ -123,7 +110,7 @@ class BaseCommand extends core_1.Command {
      */
     async resolveTicketId(value) {
         const ref = value.trim();
-        if (exports.UUID_RE.test(ref))
+        if (lookup_1.UUID_RE.test(ref))
             return ref;
         // Stessa forma che il server accetta come code: chiave progetto (max 4) + numero.
         const match = /^([a-z\d]{1,4})-\d+$/i.exec(ref);
@@ -149,7 +136,7 @@ class BaseCommand extends core_1.Command {
      */
     async resolveTicketLookupId(lookup, value) {
         const wanted = value ?? lookup.fallback;
-        if (exports.UUID_RE.test(wanted))
+        if (lookup_1.UUID_RE.test(wanted))
             return wanted;
         const rows = (await this.api.get(lookup.path)).data;
         const matches = (0, ticket_lookup_1.matchTicketLookup)(rows, wanted);
@@ -162,49 +149,12 @@ class BaseCommand extends core_1.Command {
         return Promise.all(values.map((value) => resolve(value)));
     }
     /** Resolve an `{id, name}` reference by name (UUID passes through). */
-    async resolveByName(path, value, code, label) {
-        if (exports.UUID_RE.test(value))
-            return value;
-        const noun = label.toLowerCase();
-        const rows = await this.fetchLookupRows(path, `Listing the ${noun}s needs the permissions.manage permission — pass the ${noun} id instead of its name.`);
-        const match = rows.find((row) => (row.name ?? '').toLowerCase() === value.toLowerCase());
-        if (!match) {
-            throw new api_1.ApiRequestError(404, code, `${label} not found: ${value}`);
-        }
-        return match.id;
+    resolveByName(path, value, code, label) {
+        return (0, lookup_1.resolveNamedId)(this.api, path, value, code, label);
     }
-    /**
-     * Every row of an organization lookup (teams, roles, groups, members) — all its pages.
-     *
-     * The server serves ten per page: stopping at the first made the eleventh team or the eleventh
-     * person invisible, and a perfectly good name or email came back as "not found" (CYCL-42, the
-     * lesson `resolveProjectId` already learned on project keys in CYCL-1).
-     *
-     * A 403 here is not about the command being run: listing teams needs `permissions.manage` and
-     * listing members `members.view`, permissions that a team workload board never asks for. Left
-     * alone it would read as "Permesso negato" on an operation the caller is entitled to, so the
-     * refusal carries the way out instead — name the id, skip the lookup.
-     */
-    async fetchLookupRows(path, hint) {
-        const rows = [];
-        let page = 1;
-        let totalPages = 1;
-        try {
-            do {
-                // eslint-disable-next-line no-await-in-loop
-                const res = await this.api.get(`${path}?page=${page}&per=100`);
-                rows.push(...(res.data ?? []));
-                totalPages = Number(res.meta?.total_pages ?? 1);
-                page += 1;
-            } while (page <= totalPages);
-        }
-        catch (error) {
-            if (error instanceof api_1.ApiRequestError && error.status === 403) {
-                throw new api_1.ApiRequestError(error.status, error.code, `${error.message}. ${hint}`);
-            }
-            throw error;
-        }
-        return rows;
+    /** Every row of an organization lookup (teams, roles, groups, members) — all its pages. */
+    fetchLookupRows(path, hint) {
+        return (0, lookup_1.fetchLookupRows)(this.api, path, hint);
     }
     /**
      * Surface API errors, then exit non-zero. In `--json` mode `logToStderr` is a no-op, so emit the

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

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

package/dist/commands/kb/context.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const api_1 = require("../../lib/api");
+const knowledge_context_1 = require("../../lib/knowledge-context");
+const knowledge_1 = require("../../lib/knowledge");
+/** Environment switch that turns the context off wherever it is invoked from, hook included. */
+const DISABLE_ENV = 'KB_CONTEXT_DISABLE';
+/** The answer when there is nothing to show: no project here, switched off, or service unreachable. */
+function nothing(unavailable = false) {
+    return { data: { project: null, pages: [], ...(unavailable ? { unavailable: true } : {}) } };
+}
+class KbContext extends base_1.BaseCommand {
+    static description = 'Print the knowledge context of the current project: the short list of pages whoever starts working here should already know';
+    static examples = [
+        '<%= config.bin %> kb context',
+        '<%= config.bin %> kb context --project ACME --limit 5',
+        '<%= config.bin %> kb context --quiet --timeout 3',
+    ];
+    static flags = {
+        // Not the shared `projectFlag`: omitted, the project is resolved from the git remote of the
+        // current directory, which is the whole point of a context that shows up on its own (CYCL-55).
+        project: core_1.Flags.string({
+            char: 'p',
+            description: 'Project id (UUID) or key; omitted, it is resolved from the git remote of the current directory',
+        }),
+        limit: core_1.Flags.integer({ description: 'How many pages to print at most', default: 10 }),
+        quiet: core_1.Flags.boolean({
+            description: 'Never fail: outside a project print nothing, on an unreachable service print one line — always exit 0 (for session-start hooks)',
+        }),
+        timeout: core_1.Flags.integer({ description: 'Seconds to wait for the service before giving up (0 = no limit)', default: 5 }),
+    };
+    async run() {
+        // Read before the command line is even parsed: switched off means switched off, not "off unless
+        // the command line is also wrong". A hook written for a newer CLI would otherwise be refused by
+        // an older one — loudly, at every session start, with the switch that should have silenced it
+        // already set.
+        if (process.env[DISABLE_ENV] === '1') {
+            // Parsed anyway, failure and all: oclif warns about a command that never parsed its arguments,
+            // and a warning on stderr is exactly the noise the switch was set to avoid.
+            await this.parse(KbContext).catch(() => undefined);
+            return nothing();
+        }
+        const { flags } = await this.parse(KbContext);
+        if (flags.limit < 1)
+            this.error(`Invalid --limit ${flags.limit}: ask for at least 1 page.`, { exit: 2 });
+        // One deadline for the whole command, not one per call: two requests with a timeout each would
+        // let a slow server cost twice the wait the caller agreed to.
+        const signal = flags.timeout > 0 ? AbortSignal.timeout(flags.timeout * 1000) : undefined;
+        const opts = signal ? { signal } : {};
+        try {
+            const project = flags.project ?? (await (0, knowledge_context_1.projectFromGitRemote)(this.api, process.cwd(), flags.timeout * 1000, opts));
+            if (project === undefined) {
+                // Scenario 2: a directory that is not a project is a normal state, not a failure.
+                if (!flags.quiet && !this.jsonEnabled())
+                    this.log('No CloseYourIt project matches this directory.');
+                return nothing();
+            }
+            const answer = await (0, knowledge_context_1.fetchKnowledgeContext)(this.api, project, flags.limit, opts);
+            // The cap holds on both outputs — printed list and JSON envelope — so `--limit 5` means five
+            // pages however the server chose to interpret `per`.
+            const res = { ...answer, data: (0, knowledge_1.capContextPages)(answer.data, flags.limit) };
+            if (!this.jsonEnabled()) {
+                const pages = (0, knowledge_1.contextPages)(res.data);
+                if (pages.length === 0) {
+                    if (!flags.quiet)
+                        this.log('No knowledge pages for this project yet.');
+                }
+                else {
+                    this.log((0, knowledge_1.renderKnowledgeContext)(pages, (0, knowledge_1.contextProjectLabel)(res.data, project)));
+                }
+            }
+            return res;
+        }
+        catch (error) {
+            // Scenario 3: with --quiet an unreachable (or unauthenticated) service costs one line and a
+            // zero exit — the session starts anyway. Anything that is not an API failure still surfaces.
+            if (!flags.quiet || !(error instanceof api_1.ApiRequestError))
+                throw error;
+            if (this.jsonEnabled())
+                this.logJson(nothing(true));
+            else
+                this.log('Knowledge context unavailable.');
+            // Exit instead of returning: a connection that never completes leaves its socket — and the
+            // event loop — alive until the OS gives up (~10s measured), well past the abort that already
+            // produced the line above. Returning would hand the caller exactly the wait the deadline was
+            // there to prevent, only after the message instead of before it.
+            return this.exit(0);
+        }
+    }
+}
+exports.default = KbContext;

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

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../base';
+/**
+ * Il controllo di salute della conoscenza (CYCL-57): dice quali pagine nessuno troverà mai, quali
+ * collegamenti sono rimasti appesi e quali code sono ferme da settimane.
+ *
+ * Legge e basta. Ogni verifica porta il comando che la sistemerebbe, ma non lo esegue: la
+ * riparazione resta una scelta esplicita di chi legge il referto.
+ */
+export default class KbDoctor extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        project: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'stale-days': import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'docs-root': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+    /** Il percorso è una cartella che esiste qui? Un percorso illeggibile vale come inesistente. */
+    private isDirectory;
+}

package/dist/commands/kb/doctor.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const core_1 = require("@oclif/core");
+const base_1 = require("../../base");
+const knowledge_doctor_1 = require("../../lib/knowledge-doctor");
+/**
+ * Il controllo di salute della conoscenza (CYCL-57): dice quali pagine nessuno troverà mai, quali
+ * collegamenti sono rimasti appesi e quali code sono ferme da settimane.
+ *
+ * Legge e basta. Ogni verifica porta il comando che la sistemerebbe, ma non lo esegue: la
+ * riparazione resta una scelta esplicita di chi legge il referto.
+ */
+class KbDoctor extends base_1.BaseCommand {
+    static description = 'Check the health of the knowledge base: unfindable pages, dangling links, queues nobody moved. Reads only — exits 1 when a check fails';
+    static examples = [
+        '<%= config.bin %> kb doctor',
+        '<%= config.bin %> kb doctor --project acme-api',
+        '<%= config.bin %> kb doctor --docs-root ~/knowledge-base',
+        '<%= config.bin %> kb doctor --stale-days 14 --json',
+    ];
+    static flags = {
+        // Facoltativo come su `kb list`: senza, il controllo guarda ogni progetto visibile.
+        project: core_1.Flags.string({ char: 'p', description: 'Only the pages of this project (key or UUID)' }),
+        'stale-days': core_1.Flags.integer({ description: 'Days after which a queue counts as stuck', default: 30 }),
+        'docs-root': core_1.Flags.string({
+            description: 'Path of the knowledge-base repository, to check that the filed documents are really there',
+        }),
+        // Il tetto vale per CIASCUNA delle due letture (l'elenco e la coda di archiviazione), non per
+        // il loro totale: detto qui, perché chi lo alza sappia quanto sta davvero chiedendo.
+        limit: core_1.Flags.integer({ description: 'How many pages to read at most, per listing', default: 500 }),
+    };
+    async run() {
+        const { flags } = await this.parse(KbDoctor);
+        if (flags.limit < 1)
+            this.error(`Invalid --limit ${flags.limit}: examine at least 1 page.`, { exit: 2 });
+        if (flags['stale-days'] < 1)
+            this.error(`Invalid --stale-days ${flags['stale-days']}: use at least 1 day.`, { exit: 2 });
+        // 6 — Il documento archiviato è un FILE. `existsSync` direbbe di sì anche per una cartella, e
+        // una pagina che punta a una directory passerebbe il controllo che esiste apposta per accorgersene.
+        const isFile = (path) => {
+            try {
+                return (0, node_fs_1.statSync)(path).isFile();
+            }
+            catch {
+                return false;
+            }
+        };
+        // Una radice sbagliata non deve produrre un referto: senza questo controllo, un percorso battuto
+        // male segnalerebbe come mancante OGNI documento del parco, che è l'allarme inventato più grosso
+        // che questo comando possa dare.
+        const docsRoot = flags['docs-root'];
+        if (docsRoot !== undefined && !this.isDirectory(docsRoot)) {
+            this.error(`Invalid --docs-root ${docsRoot}: it is not a directory that exists here.`, { exit: 2 });
+        }
+        const scan = await (0, knowledge_doctor_1.fetchDoctorPages)(this.api, { limit: flags.limit, project: flags.project });
+        // Il servizio è l'unico a sapere quali pagine ASPETTANO davvero di essere archiviate: la coda
+        // esclude quelle scritte a mano dal web, che non hanno mai chiesto niente a nessuno. Derivarla
+        // qui da `consolidated_at` vuoto avrebbe fatto nascere l'elenco con decine di righe innocenti.
+        const awaiting = await (0, knowledge_doctor_1.fetchDoctorPages)(this.api, {
+            awaitingConsolidation: true,
+            limit: flags.limit,
+            project: flags.project,
+        });
+        const checks = (0, knowledge_doctor_1.runDoctorChecks)({
+            awaitingConsolidation: awaiting.pages,
+            docsRoot,
+            fileExists: docsRoot === undefined ? undefined : isFile,
+            now: new Date(),
+            pages: scan.pages,
+            scopedToProject: flags.project !== undefined,
+            staleDays: flags['stale-days'],
+        });
+        const report = {
+            scanned: scan.pages.length,
+            truncated: scan.truncated || awaiting.truncated,
+            stale_days: flags['stale-days'],
+            checks,
+        };
+        const totals = (0, knowledge_doctor_1.doctorTotals)(checks);
+        const envelope = { data: report, meta: totals };
+        if (!this.jsonEnabled())
+            this.log((0, knowledge_doctor_1.renderDoctorReport)(report));
+        // Esce non-zero quando una verifica è fallita — come lo script di audit che questo comando
+        // porta dentro il prodotto — così una pipeline può fermarsi su una conoscenza rotta. Un avviso
+        // non basta: segnala una coda ferma, non una pagina irraggiungibile.
+        if (totals.failures > 0) {
+            // In modalità dati l'envelope va emesso a mano: `this.exit` scarta il valore di ritorno, e
+            // uscire in silenzio darebbe a chi legge da un programma un'uscita vuota indistinguibile da
+            // un guasto.
+            if (this.jsonEnabled())
+                this.logJson(envelope);
+            return this.exit(1);
+        }
+        return envelope;
+    }
+    /** Il percorso è una cartella che esiste qui? Un percorso illeggibile vale come inesistente. */
+    isDirectory(path) {
+        try {
+            return (0, node_fs_1.statSync)(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.default = KbDoctor;

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

@@ -10,6 +10,7 @@ export default class KbSearch extends BaseCommand {
         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>;
         kind: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        status: 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>;
         'with-related': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };

package/dist/commands/kb/search.js

@@ -12,6 +12,7 @@ class KbSearch extends base_1.BaseCommand {
         '<%= config.bin %> kb search "connection pool timeout" --project acme-api',
         '<%= config.bin %> kb search kamal rollback --with-related',
         '<%= config.bin %> kb search retry backoff --kind decision --json',
+        '<%= config.bin %> kb search cache in prova --status all',
     ];
     // Non-required: with strict = false the arg validation is off, so we guard the empty case ourselves.
     static args = {
@@ -20,6 +21,11 @@ class KbSearch extends base_1.BaseCommand {
     static flags = {
         project: core_1.Flags.string({ char: 'p', description: 'Filter by project (key or UUID)' }),
         kind: core_1.Flags.string({ description: 'Filter by kind: note|decision|guide (repeatable or comma-separated)', multiple: true }),
+        // Single value, exactly like `kb list --status`: the endpoint reads one `status=` and answers
+        // R422-KNOWLEDGE-011 to anything else, so a repeatable flag would only build queries the server
+        // rejects. `all` is the one that looks everywhere at once — the way to spot a duplicate that
+        // exists as a proposal without running a second command.
+        status: core_1.Flags.string({ description: 'Filter by review state', options: [...knowledge_1.KNOWLEDGE_STATUSES] }),
         per: core_1.Flags.integer({ description: 'Page size' }),
         // Opt-in: the server only computes this when asked, for the first few results.
         'with-related': core_1.Flags.boolean({ description: 'Also show the pages each result links to' }),
@@ -37,6 +43,7 @@ class KbSearch extends base_1.BaseCommand {
             project: flags.project,
             q,
             related: flags['with-related'],
+            status: flags.status,
         });
         const res = await this.api.get(`/cli/v1/knowledge/pages?${query}`);
         const pages = res.data ?? [];

package/dist/commands/mcp.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../base';
+export default class Mcp extends BaseCommand {
+    static enableJsonFlag: boolean;
+    static description: string;
+    static examples: string[];
+    static flags: {
+        timeout: import("@oclif/core/lib/interfaces").OptionFlag<number, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/mcp.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 server_1 = require("../lib/mcp/server");
+class Mcp extends base_1.BaseCommand {
+    // Niente `--json`: su questo comando lo standard output è il canale del protocollo, e una busta
+    // in più alla fine sarebbe l'unica riga che il client non sa leggere.
+    static enableJsonFlag = false;
+    static description = 'Serve the knowledge base over the Model Context Protocol on stdin/stdout, so any assistant that speaks MCP can search it, ask it and propose pages — with your own access and no instructions written for it';
+    static examples = [
+        '<%= config.bin %> mcp',
+        'CLOSEYOURIT_TOKEN=cyi_u_… <%= config.bin %> mcp',
+    ];
+    static flags = {
+        timeout: core_1.Flags.integer({
+            description: 'Seconds to wait for git when recognising the project of the current directory',
+            default: 5,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Mcp);
+        // Il server vive finché il client tiene aperto il suo standard input: è il client a lanciarlo
+        // come sottoprocesso e a chiuderlo, non c'è nulla da stampare prima né dopo.
+        await (0, server_1.serveStdio)(process.stdin, process.stdout, (0, server_1.createSession)({
+            api: this.api,
+            version: this.config.version,
+            cwd: process.cwd(),
+            timeoutMs: flags.timeout * 1000,
+        }));
+    }
+}
+exports.default = Mcp;