kd-cli 2.9.1__tar.gz → 2.11.0__tar.gz

{kd_cli-2.9.1/kd_cli.egg-info → kd_cli-2.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.9.1
+Version: 2.11.0
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT
@@ -59,7 +59,7 @@ The **primer** (`kd /primer`) is the centerpiece: a small, workspace-local file
 It exists to solve a problem that has gotten worse as LLMs have become central to real work:
 
 - **Visible memory.** Agentic tools accumulate hidden "memories" in opaque per-LLM buckets you cannot easily read, edit, or audit. The primer is a plain file you can open, version, and review. If an LLM appears to "remember" something load-bearing, you can see exactly where that came from.
-- **LLM-portable.** One primer works for any model. Switch from Claude to GPT-5 to the next generation — the primer travels with the project, not with a vendor.
+- **LLM-portable.** One primer works for any model. Switch from Claude to GPT to the next generation — the primer travels with the project, not with a vendor.
 - **Shared by humans and LLMs.** A developer jotting "on this project the sprint field is called `Board`" in the primer is building the same artifact an LLM would build, in the same place, readable by both. No separate convention to maintain.
 - **A routing layer, not a copy.** The primer can pin real knowledge-base articles (`kd /primer/article add FB-A-42`). It never duplicates their content — it points at them. The rest of kd extends this shape: pull what the current task needs from live systems, reason, push updates back. Nothing gets mirrored into a parallel store.
 
@@ -83,20 +83,24 @@ uv tool install kd-cli
 
 The PyPI distribution name is `kd-cli` (two-letter `kd` is reserved by PyPI policy). The installed command, the import name, and the CLI entry point are all `kd`.
 
-Release notes for the installed version: `kd /release-notes`. The canonical changelog lives at [`kd/resources/CHANGELOG.md`](kd/resources/CHANGELOG.md).
+Release notes for the installed version: `kd /release-notes`. Every release is listed in the [changelog](https://github.com/IntellectSolutionsCom/kd-cli/blob/main/CHANGELOG.md).
 
 ## Configure
 
 ```bash
-# Scaffold a project-local config in the current directory.
-kd init
+# Global config with your YouTrack URL (recommended on first install).
+kd init --global https://your-instance.youtrack.cloud
 
-# Or set via environment (overrides workspace + global config).
-export KD_TOKEN=your_token
-export KD_CONNECTION=main
+# The scaffolded connection reads its token from KD_TOKEN (its token_env).
+export KD_TOKEN=perm:your-token-here
+
+# Check the connection.
+kd /system info
 ```
 
-Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.
+Create the token in YouTrack under Profile → Account Security → New token. In PowerShell, set it with `$env:KD_TOKEN = "perm:your-token-here"`, or `setx KD_TOKEN perm:your-token-here` to keep it, then open a new terminal. `token_cmd:` in the connection reads the token from a command, such as a secrets manager, instead.
+
+Global config lives at `~/.config/kd/config.yaml` (Windows: `C:\Users\<you>\.config\kd\config.yaml`); `kd init <url>` without `--global` writes `.kd/config.yaml` in the current directory. `KD_CONNECTION` picks the connection by name.
 
 ## Usage
 
@@ -116,13 +120,13 @@ kd /issue show FB-1
 kd /time log FB-1 45 --type Development --description "Router reconfiguration"
 
 # Articles
-kd /article list --project CMCSA
-kd /article push guide.md --project CMCSA --title "Setup Guide" --tag "type:guide"
+kd /article list --project FB
+kd /article push guide.md --project FB --title "Setup Guide" --tag "type:guide"
 kd /article pull FB-A-42 > setup.md
 
 # Tags
 kd /tag list
-kd /tag articles type:case --project CMCSA
+kd /tag articles type:case --project FB
 
 # Saved queries
 kd /query list
@@ -156,7 +160,7 @@ client = YouTrackClient(
 projects = client.projects.list()
 issue = client.issues.create(project="FB", summary="Fix router config")
 client.time.log(issue_id="FB-1", minutes=45, work_type="Development")
-articles = client.tags.articles(["type:case"], project="CMCSA")
+articles = client.tags.articles(["type:case"], project="FB")
 results = client.search.search("router", types=["issue", "article"])
 ```
 
@@ -167,8 +171,8 @@ pytest tests/ -v --tb=short
 
 ruff format kd/ tests/
 ruff check --fix kd/ tests/
-mypy kd/
+uv run mypy
 ```
 
 ---
-Updated: 2026-04-14
+Updated: 2026-11-01

{kd_cli-2.9.1 → kd_cli-2.11.0}/README.md

@@ -19,7 +19,7 @@ The **primer** (`kd /primer`) is the centerpiece: a small, workspace-local file
 It exists to solve a problem that has gotten worse as LLMs have become central to real work:
 
 - **Visible memory.** Agentic tools accumulate hidden "memories" in opaque per-LLM buckets you cannot easily read, edit, or audit. The primer is a plain file you can open, version, and review. If an LLM appears to "remember" something load-bearing, you can see exactly where that came from.
-- **LLM-portable.** One primer works for any model. Switch from Claude to GPT-5 to the next generation — the primer travels with the project, not with a vendor.
+- **LLM-portable.** One primer works for any model. Switch from Claude to GPT to the next generation — the primer travels with the project, not with a vendor.
 - **Shared by humans and LLMs.** A developer jotting "on this project the sprint field is called `Board`" in the primer is building the same artifact an LLM would build, in the same place, readable by both. No separate convention to maintain.
 - **A routing layer, not a copy.** The primer can pin real knowledge-base articles (`kd /primer/article add FB-A-42`). It never duplicates their content — it points at them. The rest of kd extends this shape: pull what the current task needs from live systems, reason, push updates back. Nothing gets mirrored into a parallel store.
 
@@ -43,20 +43,24 @@ uv tool install kd-cli
 
 The PyPI distribution name is `kd-cli` (two-letter `kd` is reserved by PyPI policy). The installed command, the import name, and the CLI entry point are all `kd`.
 
-Release notes for the installed version: `kd /release-notes`. The canonical changelog lives at [`kd/resources/CHANGELOG.md`](kd/resources/CHANGELOG.md).
+Release notes for the installed version: `kd /release-notes`. Every release is listed in the [changelog](https://github.com/IntellectSolutionsCom/kd-cli/blob/main/CHANGELOG.md).
 
 ## Configure
 
 ```bash
-# Scaffold a project-local config in the current directory.
-kd init
+# Global config with your YouTrack URL (recommended on first install).
+kd init --global https://your-instance.youtrack.cloud
 
-# Or set via environment (overrides workspace + global config).
-export KD_TOKEN=your_token
-export KD_CONNECTION=main
+# The scaffolded connection reads its token from KD_TOKEN (its token_env).
+export KD_TOKEN=perm:your-token-here
+
+# Check the connection.
+kd /system info
 ```
 
-Global config lives at `~/.config/kd/config.yaml`; workspace config lives at `.kd/config.yaml`.
+Create the token in YouTrack under Profile → Account Security → New token. In PowerShell, set it with `$env:KD_TOKEN = "perm:your-token-here"`, or `setx KD_TOKEN perm:your-token-here` to keep it, then open a new terminal. `token_cmd:` in the connection reads the token from a command, such as a secrets manager, instead.
+
+Global config lives at `~/.config/kd/config.yaml` (Windows: `C:\Users\<you>\.config\kd\config.yaml`); `kd init <url>` without `--global` writes `.kd/config.yaml` in the current directory. `KD_CONNECTION` picks the connection by name.
 
 ## Usage
 
@@ -76,13 +80,13 @@ kd /issue show FB-1
 kd /time log FB-1 45 --type Development --description "Router reconfiguration"
 
 # Articles
-kd /article list --project CMCSA
-kd /article push guide.md --project CMCSA --title "Setup Guide" --tag "type:guide"
+kd /article list --project FB
+kd /article push guide.md --project FB --title "Setup Guide" --tag "type:guide"
 kd /article pull FB-A-42 > setup.md
 
 # Tags
 kd /tag list
-kd /tag articles type:case --project CMCSA
+kd /tag articles type:case --project FB
 
 # Saved queries
 kd /query list
@@ -116,7 +120,7 @@ client = YouTrackClient(
 projects = client.projects.list()
 issue = client.issues.create(project="FB", summary="Fix router config")
 client.time.log(issue_id="FB-1", minutes=45, work_type="Development")
-articles = client.tags.articles(["type:case"], project="CMCSA")
+articles = client.tags.articles(["type:case"], project="FB")
 results = client.search.search("router", types=["issue", "article"])
 ```
 
@@ -127,8 +131,8 @@ pytest tests/ -v --tb=short
 
 ruff format kd/ tests/
 ruff check --fix kd/ tests/
-mypy kd/
+uv run mypy
 ```
 
 ---
-Updated: 2026-04-14
+Updated: 2026-11-01

{kd_cli-2.9.1 → kd_cli-2.11.0}/kd/api/http.py

@@ -11,6 +11,7 @@ Wraps httpx.Client with:
 from __future__ import annotations
 
 import json
+import math
 import time
 from typing import Any
 
@@ -23,11 +24,69 @@ from kd.exceptions import (
     ConflictError,
     NotFoundError,
     PermissionDeniedError,
+    ValidationError,
     enrich_error,
 )
 
-_RETRYABLE_STATUSES = {429, 502, 503}
-_MAX_RETRIES = 3
+_GATEWAY_RETRY = {502, 503}  # retried, only for a request that cannot write
+_GATEWAY_UNCONFIRMED = {502, 503, 504}  # on a write: may have been applied
+_MAX_ATTEMPTS = 3
+_BACKOFF_BASE = 1.0  # seconds; doubles per attempt
+_RETRY_AFTER_CAP = 10.0  # seconds; a longer Retry-After ends the request
+
+
+def _refuse_control_characters(path: str) -> None:
+    """Refuse a path that no URL can carry, before it is sent.
+
+    The refused set is exactly what httpx rejects as non-printable ASCII:
+    C0 controls and DEL. The user values kd puts in a path are entity ids,
+    one per segment, so the error names the segment that carries the
+    character, escaped onto one line.
+    """
+    for segment in path.split("/"):
+        if any(c < " " or c == "\x7f" for c in segment):
+            raise ValidationError(
+                f"Invalid id {segment!r}: it contains a control character "
+                "(line break, tab or similar). Pass one id per argument."
+            )
+
+
+def _retry_after_seconds(response: httpx.Response) -> float | None:
+    """Return ``Retry-After`` as non-negative seconds, or ``None``.
+
+    The HTTP-date form, a negative value and anything unparseable count
+    as no header.
+    """
+    raw = response.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        value = float(raw)
+    except ValueError:
+        return None
+    if value < 0 or not math.isfinite(value):
+        return None
+    return value
+
+
+def _retry_delay(response: httpx.Response, attempt: int, *, safe: bool) -> float | None:
+    """Return the delay before the next attempt, or ``None`` to stop.
+
+    A 429 is retried for any method: the server refused before processing
+    it. It waits ``Retry-After`` up to the cap, and above the cap it stops.
+    A 502 or 503 is retried only for a request that cannot write, since a
+    proxy can answer one after the server applied the write. A 504 is not
+    retried.
+    """
+    backoff: float = _BACKOFF_BASE * 2.0**attempt
+    if response.status_code == 429:
+        wait = _retry_after_seconds(response)
+        if wait is None:
+            return backoff
+        return wait if wait <= _RETRY_AFTER_CAP else None
+    if response.status_code in _GATEWAY_RETRY and safe:
+        return backoff
+    return None
 
 
 class HttpClient:
@@ -69,12 +128,17 @@ class HttpClient:
         json: dict[str, Any] | None = None,
         fields: str | None = None,
         params: dict[str, Any] | None = None,
+        safe: bool = False,
     ) -> Any:
-        """POST with optional fields on query string."""
+        """POST with optional fields on query string.
+
+        ``safe=True`` marks a POST that only reads (an assist call): it is
+        retried like a GET, and a failure is never reported as a write.
+        """
         all_params: dict[str, Any] = dict(params or {})
         if fields:
             all_params["fields"] = fields
-        response = self._request("POST", path, json=json, params=all_params or None)
+        response = self._request("POST", path, json=json, params=all_params or None, safe=safe)
         if response.status_code == 204 or not response.content:
             return {}
         return self._decode_json(response)
@@ -114,9 +178,13 @@ class HttpClient:
         """DELETE. Returns nothing."""
         self._request("DELETE", path)
 
-    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+    def _request(
+        self, method: str, path: str, *, safe: bool = False, **kwargs: Any
+    ) -> httpx.Response:
         """Execute request with retry and error mapping."""
+        _refuse_control_characters(path)
         d = self._debug
+        safe = safe or method == "GET"
 
         # Log request details before first attempt
         if params := kwargs.get("params"):
@@ -130,8 +198,7 @@ class HttpClient:
         d.trace("http", "  headers: Authorization=Bearer ***")
 
         start = time.monotonic()
-        last_response: httpx.Response | None = None
-        for attempt in range(_MAX_RETRIES):
+        for attempt in range(_MAX_ATTEMPTS):
             try:
                 response = self._client.request(method, path, **kwargs)
             except httpx.HTTPError as e:
@@ -148,12 +215,14 @@ class HttpClient:
                 d.trace("http", f"  response: {response.text[:1000]}")
                 return response
 
-            last_response = response
-            if response.status_code in _RETRYABLE_STATUSES and attempt < _MAX_RETRIES - 1:
+            delay = _retry_delay(response, attempt, safe=safe)
+            if delay is not None and attempt < _MAX_ATTEMPTS - 1:
                 d.debug(
                     "http",
-                    f"  retry {attempt + 1}/{_MAX_RETRIES} (status {response.status_code})",
+                    f"  retry {attempt + 1}/{_MAX_ATTEMPTS} in {delay:g}s "
+                    f"(status {response.status_code})",
                 )
+                time.sleep(delay)
                 continue
 
             d.info(
@@ -161,11 +230,9 @@ class HttpClient:
                 f"{method} {path} -> {response.status_code} ({duration_ms:.0f}ms) FAILED",
             )
             d.trace("http", f"  response: {response.text[:1000]}")
-            self._raise_for_status(response)
+            self._raise_for_status(response, unconfirmed_write=self._unconfirmed(response, safe))
 
-        # Satisfy type checker — _raise_for_status always raises
-        assert last_response is not None
-        self._raise_for_status(last_response)
+        # Every attempt returns, raises or continues while attempts remain.
         raise AssertionError("unreachable")  # pragma: no cover
 
     @staticmethod
@@ -231,15 +298,45 @@ class HttpClient:
         return body
 
     @staticmethod
-    def _raise_for_status(response: httpx.Response) -> None:
-        """Map HTTP status to kd exceptions. Always raises."""
+    def _unconfirmed(response: httpx.Response, safe: bool) -> bool:
+        """A 502, 503 or 504 on a request that can write: it may have been applied."""
+        return response.status_code in _GATEWAY_UNCONFIRMED and not safe
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response, *, unconfirmed_write: bool = False) -> None:
+        """Map HTTP status to kd exceptions. Always raises.
+
+        *unconfirmed_write* marks a 502, 503 or 504 on a request kd did not
+        resend because it can write: the message says so and the hint
+        names a read that checks it.
+        """
         body = response.text
         status = response.status_code
         extracted = HttpClient._extract_message(body)
         request_path = response.request.url.path if response.request else None
-        message, suggestion = enrich_error(extracted, status=status, path=request_path)
+        message, suggestion = enrich_error(
+            extracted,
+            status=status,
+            path=request_path,
+            unconfirmed_write=unconfirmed_write,
+        )
+        if unconfirmed_write:
+            method = response.request.method if response.request else "request"
+            lines = message.strip().splitlines()
+            server = lines[0] if lines else "(empty response)"
+            raise APIError(
+                status,
+                f"API error ({status}) on {method} {request_path}: kd did not resend it, "
+                f"because the server may have applied it. Server said: {server}",
+                body,
+                suggestion,
+            )
+        if status == 429:
+            wait = _retry_after_seconds(response)
+            if wait is not None:
+                message = f"{message}; the server asked to wait {wait:g} s."
         if status == 401:
-            raise AuthError(f"Authentication failed: {message}")
+            raise AuthError(f"Authentication failed: {message}", suggestion=suggestion)
         if status == 403:
             body_lower = body.lower()
             if suggestion or "permission" in body_lower or "access" in body_lower:

{kd_cli-2.9.1 → kd_cli-2.11.0}/kd/api/youtrack.py

@@ -267,7 +267,7 @@ class YouTrackAPI:
                 "Create one issue (any contributor token works), or use a "
                 "token with project-administration rights. Or omit "
                 "--type / --priority / --state to create a minimal first "
-                "issue, then update it via `/issue update`. See KDCLI-A-22."
+                "issue, then update it via `/issue update`."
             ),
         )
 
@@ -525,7 +525,7 @@ class YouTrackAPI:
         body: dict[str, Any] = {"query": query}
         if caret is not None:
             body["caret"] = caret
-        data = self._http.post("/search/assist", json=body, fields=_ASSIST_FIELDS)
+        data = self._http.post("/search/assist", json=body, fields=_ASSIST_FIELDS, safe=True)
         return AssistResponse.model_validate(data)
 
     def commands_assist(
@@ -546,5 +546,5 @@ class YouTrackAPI:
         }
         if caret is not None:
             body["caret"] = caret
-        data = self._http.post("/commands/assist", json=body, fields=_ASSIST_FIELDS)
+        data = self._http.post("/commands/assist", json=body, fields=_ASSIST_FIELDS, safe=True)
         return AssistResponse.model_validate(data)

{kd_cli-2.9.1 → kd_cli-2.11.0}/kd/article_marker.py

@@ -18,6 +18,9 @@ Grammar (informal):
 Rules (pinned down by ``tests/test_article_marker.py``):
 
 - Open and close lines must be exact (``<!-- kd-meta`` / ``-->``).
+- Only a marker that opens on the first non-blank line counts; a
+  marker-open line after body content is body. A second marker block
+  directly below the top one (only blank lines between) is an error.
 - Keys match ``[a-z][a-z0-9-]*``; uppercase and underscores are
   rejected to keep the grammar ASCII-boring.
 - Unknown keys are preserved verbatim on round-trip — the load-bearing
@@ -49,8 +52,9 @@ Legacy marker synonym (transitional, proposal 28 / M003 §S4):
     upstream population of ``ytctl-meta`` is empty. No auto-disable,
     no timer — a deliberate future milestone.
 
-Stdlib only; no third-party deps. The push workflow (in
-``kd.client.ArticleOperations.push``) and its tests are the only
+Stdlib only; no third-party deps. The push workflow
+(``kd.client.ArticleOperations.push``), ``/article update``
+(``kd.client.ArticleOperations.update``) and their tests are the only
 importers.
 """
 
@@ -248,13 +252,17 @@ def parse_content(text: str) -> ParsedFile:
     if close_idx is None:
         raise MarkerError("marker block not closed (expected '-->' on its own line)")
 
-    # Refuse a second marker anywhere later in the file — native or
-    # legacy. Prevents a stray ``<!-- ytctl-meta`` further down from
-    # being silently accepted as body content on a file that also
-    # carries a native header at the top.
-    for k in range(close_idx + 1, len(lines)):
-        if lines[k] in _RECOGNIZED_OPENS:
-            raise MarkerError("file contains more than one kd-meta block")
+    # A second marker block with only blank lines above it would become
+    # the identity once the top block is stripped (``/article update
+    # --content``) or edited away, so it is refused. A marker-open line
+    # after body content stays body. This check only refuses, so it
+    # compares leniently (whitespace, stray CR, BOM): an editor or
+    # encoding round trip can turn a near-exact open into an exact one.
+    k = close_idx + 1
+    while k < len(lines) and _loose(lines[k]) == "":
+        k += 1
+    if k < len(lines) and _loose(lines[k]) in _RECOGNIZED_OPENS:
+        raise MarkerError("a second kd-meta block directly follows the top marker; keep one")
 
     # Parse key:value lines between open and close.
     marker = ArticleMarker()
@@ -291,6 +299,12 @@ def parse_content(text: str) -> ParsedFile:
     )
 
 
+def _loose(line: str) -> str:
+    """Normalize a line for the stacked-block refusal only: drop BOMs and
+    surrounding whitespace. Never used to detect the top marker."""
+    return line.replace("\ufeff", "").strip()
+
+
 def _join_body(lines: list[str], trailing_newline: bool) -> str:
     """Join body lines with ``\\n``, restoring the final terminator if any."""
     if not lines:

{kd_cli-2.9.1 → kd_cli-2.11.0}/kd/auth.py

@@ -69,9 +69,8 @@ def resolve_connection_token(
         value = os.environ.get(conn.token_env)
         if value:
             return value
-        raise _missing_token_error(conn, name, origin)
-
-    raise _no_auth_source_error(conn, name, origin)
+    # ConnectionConfig requires token_cmd or token_env, so only an unset env var lands here.
+    raise _missing_token_error(conn, name, origin)
 
 
 def _run_token_cmd(cmd: str) -> str:
@@ -122,26 +121,6 @@ def _missing_token_error(
     return AuthError(message, suggestion=suggestion)
 
 
-def _no_auth_source_error(
-    conn: ConnectionConfig,
-    name: str | None,
-    origin: ConnectionOrigin | None,
-) -> AuthError:
-    """Build an ``AuthError`` for a connection with no ``token_cmd`` or ``token_env``."""
-    where = _describe_connection(conn, name)
-    message = f"{where} has no auth source configured."
-    suggestion = _build_suggestion(
-        lines=[
-            "Set one of `token_cmd:` or `token_env:` on the connection:",
-            f"  connections.{name or '<name>'}.token_cmd: gopass show -o path/to/token",
-            f"  connections.{name or '<name>'}.token_env: KD_{(name or 'NAME').upper()}_TOKEN",
-        ],
-        origin=origin,
-        key=None,
-    )
-    return AuthError(message, suggestion=suggestion)
-
-
 def _describe_connection(conn: ConnectionConfig, name: str | None) -> str:
     """Render the ``Connection '<name>' (<url>)`` prefix, degraded when no name."""
     if name:

{kd_cli-2.9.1 → kd_cli-2.11.0}/kd/cache.py

@@ -153,7 +153,7 @@ SCOPE_MANIFEST_KIND = "cache_scope"
 
 #: Markdown banner for cached article bodies. Five-space continuation
 #: indent matches ``"<!-- "`` width so the banner reads as one logical
-#: line. Pinned by tests; aligned with KDCLI-A-18 §Cache contract.
+#: line. Pinned by tests; described in ``kd --guide`` §Cache.
 BANNER_TEMPLATE_MD = (
     "<!-- kd-cache: upstream={id} fetched={iso}.\n"
     "     Disposable mirror. Edits lost on refresh. Not authoritative. -->"
@@ -2026,7 +2026,7 @@ def refresh_primer_scope(
     Read-only by contract: writes only under ``cache_root``; the primer
     is read but never mutated; no upstream mutation.
 
-    See KDCLI-A-18 §Cache contract; M008 proposal 39.
+    See ``kd --guide`` §Cache.
     """
     workspace_dir = require_workspace_dir()
     primer = load_primer(workspace_dir / PRIMER_FILENAME)
@@ -2440,7 +2440,7 @@ def refresh_milestone(
     """Hydrate a milestone-scoped query into ``cache_root/queries/milestone-<slug>.yaml``.
 
     Resolves the project's milestone field through the per-project
-    ``field_aliases`` map (KDCLI-A-18 §Project tier) — if the project
+    ``field_aliases`` map — if the project
     aliased ``milestone`` → ``Stage``, the discovered field is ``Stage``
     and the cache file's ``source.field_name`` records that. Without an
     alias, falls back to the literal ``Milestone`` name. The discovery

{kd_cli-2.9.1 → kd_cli-2.11.0}/kd/cli/core/command_base.py

@@ -11,6 +11,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
 from kd.cli.core.option_registry import OptionDeclaration, ResolvedOptions
+from kd.exceptions import ValidationError
 
 if TYPE_CHECKING:
     from kd.config import ResolvedConfig
@@ -20,6 +21,18 @@ if TYPE_CHECKING:
 CommandResult = list[dict[str, Any]] | dict[str, Any] | str | None
 
 
+def reject_extra_args(args: list[str], allowed: int, usage: str) -> None:
+    """Refuse positionals beyond the first *allowed* ones.
+
+    For commands whose positional count is fixed and whose effect is
+    outward or irreversible: a word left over by the parser (for example
+    ``off`` after a boolean option) must not be dropped silently. The
+    error names the first extra word and the command's usage line.
+    """
+    if len(args) > allowed:
+        raise ValidationError(f"Unexpected argument '{args[allowed]}'. Usage: {usage}")
+
+
 class Command(ABC):
     """Base class for all CLI commands."""
 
@@ -31,6 +44,7 @@ class Command(ABC):
         requires_client: bool = False,
         requires_config: bool = False,
         usage: str = "",
+        joins_text: bool = False,
         long_description: str = "",
         examples: list[str] | None = None,
         see_also: list[str] | None = None,
@@ -40,10 +54,17 @@ class Command(ABC):
         self.requires_client = requires_client
         self.requires_config = requires_config
         self.usage = usage
+        # The command joins its arguments into one text (a summary, comment,
+        # note, name or query). The parser then refuses a bare switch that is
+        # directly followed by a word when an argument comes before it.
+        self.joins_text = joins_text
         self.long_description = long_description
         self.examples: list[str] = examples or []
         self.see_also: list[str] = see_also or []
         self.display_hint: str | None = None
+        # A connection the command's own output names as invalid: the dispatcher
+        # adds no connection_invalid warning about it (kd init's next line).
+        self.invalid_connection_named: str | None = None
         self._options: list[OptionDeclaration] = []
         self._resolved_config: ResolvedConfig | None = None
         self._register_options()