kd-cli 2.4.1__tar.gz → 2.5.1__tar.gz

{kd_cli-2.4.1/kd_cli.egg-info → kd_cli-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.4.1
+Version: 2.5.1
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/api/tags.py

@@ -38,6 +38,7 @@ _TAGGED_ISSUE_FIELDS = str(
         "summary",
         "updated",
         project=FieldSet("id", "name", "shortName"),
+        tags=FieldSet("id", "name"),
     )
 )
 

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/cli/namespaces/article/__init__.py

@@ -353,7 +353,11 @@ class ArticleCreateCommand(Command):
                 "title. Pass --parent to attach the new article under an "
                 "existing one in a single call, avoiding a create-then-move "
                 "two-step in migration scripts. Pass --tag (repeatable) to "
-                "apply tags at creation time."
+                "apply tags at creation time: every --tag must exist, the "
+                "article is refused before creation if any tag is missing "
+                "(no orphan article on unknown tags), and the structured "
+                "response reflects post-tag state so it matches a "
+                "subsequent /article show on the returned id."
             ),
             examples=[
                 'kd /article create "Setup Guide" --project FB --content @guide.md',

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/cli/namespaces/issue/__init__.py

@@ -270,11 +270,20 @@ class IssueCreateCommand(Command):
             "Create an issue",
             requires_client=True,
             usage='kd /issue create "Summary" --project P [--field NAME=VALUE] [--attach FILE]',
-            long_description="Summary is the issue title. --project is the project key (e.g. FB).",
+            long_description=(
+                "Summary is the issue title. --project is the project key (e.g. FB). "
+                "--field NAME=VALUE supports bundle families (enum, state, owned, "
+                "version, build), user logins, period, and string custom fields; the "
+                "field name is fuzzy-matched and the value is passed verbatim. "
+                "Unsupported families (text, Multi*, and integer/float/date subtypes "
+                "of SimpleProjectCustomField) fail client-side with an error naming "
+                "both the project $type and fieldType.id subtype."
+            ),
             examples=[
                 'kd /issue create "Fix router config" --project FB --type Task',
                 'kd /issue create "Bug report" -p FB --attach screenshot.png --attach log.txt',
                 'kd /issue create "Sprint task" -p FB --field "Sprint=Sprint 47"',
+                'kd /issue create "Tracked" -p VIS --field "Milestone=M039"',
                 'kd /issue create "Design doc" -p FB --description @design.md',
             ],
             see_also=["/issue list", "/issue show", "/issue/attachment add", "/project/field list"],
@@ -437,10 +446,21 @@ class IssueUpdateCommand(Command):
             "Update an issue",
             requires_client=True,
             usage="kd /issue update ID [--title T] [--field NAME=VALUE]",
+            long_description=(
+                "--field NAME=VALUE supports bundle families (enum, state, owned, "
+                "version, build), user logins, period, and string custom fields; the "
+                "field name is fuzzy-matched and the value is passed verbatim. "
+                "Clear optional custom fields with NAME= (empty value). Unsupported "
+                "families (text, Multi*, and integer/float/date subtypes of "
+                "SimpleProjectCustomField) fail client-side with an error naming "
+                "both the project $type and fieldType.id subtype."
+            ),
             examples=[
                 'kd /issue update FB-42 --title "New title"',
                 "kd /issue update FB-42 --state Open --priority Critical",
                 'kd /issue update FB-42 --field "Sprint=Sprint 48"',
+                'kd /issue update VIS-21 --field "Milestone=M039"',
+                'kd /issue update FB-42 --field "Milestone="',
                 "kd /issue update FB-42 --description @updated.md",
             ],
             see_also=["/issue show", "/project/field list"],

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/cli/namespaces/system/__init__.py

@@ -9,10 +9,12 @@ copy-on-write history for config and primer files.
 from __future__ import annotations
 
 import difflib
+import platform as _platform
 from dataclasses import asdict
 from pathlib import Path
 from typing import Any
 
+from kd import __version__ as _kd_version
 from kd.cli.core.command_base import Command, CommandResult
 from kd.cli.core.namespaces import Namespace
 from kd.cli.core.option_registry import OptionDeclaration, OptionLayer, ResolvedOptions
@@ -51,10 +53,13 @@ class SystemInfoCommand(Command):
             requires_client=True,
             usage="kd /system info",
             long_description="Connects to the YouTrack instance and displays the current "
-            "user, server URL, and connection status. Uses the active connection "
-            "(selected via -c or 'default_connection').",
+            "user, server URL, and connection status, plus kd client/runtime metadata "
+            "(`kd_version`, `python_version`, `platform`) so bug reports are "
+            "self-describing without hand-typing the version. Uses the active "
+            "connection (selected via -c or 'default_connection').",
             examples=[
                 "kd /system info",
+                "kd /system info -o yaml",
                 "kd -c upstream /system info",
             ],
             see_also=["/system/config list"],
@@ -73,6 +78,9 @@ class SystemInfoCommand(Command):
             "user": me.get("login", "unknown"),
             "name": me.get("name", ""),
             "email": me.get("email", ""),
+            "kd_version": _kd_version,
+            "python_version": _platform.python_version(),
+            "platform": _platform.platform(),
         }
 
 

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/cli/namespaces/tag/__init__.py

@@ -152,7 +152,7 @@ class TagShowCommand(Command):
 
 
 class TagCreateCommand(Command):
-    """Create a tag."""
+    """Create a tag (idempotent)."""
 
     def __init__(self) -> None:
         super().__init__(
@@ -160,8 +160,16 @@ class TagCreateCommand(Command):
             "Create a tag",
             requires_client=True,
             usage="kd /tag create TAG_NAME",
+            long_description=(
+                "Idempotent: if a tag with the requested name is already "
+                "visible, the command returns the existing tag with "
+                "action: exists and does not POST. Response envelope: "
+                "{ok, action, tag} with action ∈ {create, exists} in both "
+                "branches. Name resolution is case-insensitive (same "
+                "resolver /tag show uses)."
+            ),
             examples=['kd /tag create "sprint-47"'],
-            see_also=["/tag list", "/tag delete"],
+            see_also=["/tag list", "/tag show", "/tag delete"],
         )
 
     def execute(
@@ -169,8 +177,12 @@ class TagCreateCommand(Command):
     ) -> CommandResult:
         if not args:
             raise ValidationError("Usage: kd /tag create TAG_NAME")
-        tag = client.tags.create(args[0])
-        return _tag_to_detail(tag)
+        result = client.tags.create(args[0])
+        return {
+            "ok": True,
+            "action": result.action,
+            "tag": _tag_to_detail(result.tag),
+        }
 
 
 class TagRenameCommand(Command):

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/client.py

@@ -22,6 +22,7 @@ import builtins
 import difflib
 import shlex
 from collections import OrderedDict
+from collections.abc import Callable
 from dataclasses import dataclass, field as dataclass_field
 from datetime import datetime, timezone
 from pathlib import Path
@@ -72,6 +73,7 @@ from kd.models import (
     EntityRef,
     KindMeta,
     Tag,
+    TagCreateResult,
     TagEntitiesResult,
     TimeTrackingSettings,
     User,
@@ -129,15 +131,43 @@ def _resolve_link_command(link_type: str) -> str:
     return result
 
 
-# Maps project custom field $type to the $type needed for issue mutations.
-_PROJECT_TO_ISSUE_TYPE: dict[str, str] = {
-    "EnumProjectCustomField": "SingleEnumIssueCustomField",
-    "StateProjectCustomField": "StateIssueCustomField",
-    "UserProjectCustomField": "SingleUserIssueCustomField",
-    "OwnedProjectCustomField": "SingleOwnedIssueCustomField",
-    "VersionProjectCustomField": "MultiVersionIssueCustomField",
-    "BuildProjectCustomField": "SingleBuildIssueCustomField",
-    "PeriodProjectCustomField": "PeriodIssueCustomField",
+# Dispatch over (project_field_type, field_type_id) → (issue_type, payload_builder).
+#
+# The builder wraps a validated value into the exact shape YouTrack expects in
+# the ``customFields[].value`` slot of an issue create/update payload. Bundle
+# families wrap as ``{"name": ...}``; user fields wrap as ``{"login": ...}``;
+# the scalar simple-string family passes through verbatim.
+#
+# ``""`` as the second tuple element means "any field_type_id under this
+# ``$type``" — used when every subtype of a family shares one payload shape.
+# A specific ``field_type_id`` key wins over the wildcard when both are present
+# (see ``SimpleProjectCustomField`` which only supports the ``string`` subtype
+# this session; ``integer``/``float``/``date`` stay unmapped).
+
+FieldValueBuilder = Callable[[str], Any]
+
+
+def _bundle_name(value: str) -> dict[str, str]:
+    return {"name": value}
+
+
+def _user_login(value: str) -> dict[str, str]:
+    return {"login": value}
+
+
+def _scalar(value: str) -> str:
+    return value
+
+
+_FIELD_DISPATCH: dict[tuple[str, str], tuple[str, FieldValueBuilder]] = {
+    ("EnumProjectCustomField", ""): ("SingleEnumIssueCustomField", _bundle_name),
+    ("StateProjectCustomField", ""): ("StateIssueCustomField", _bundle_name),
+    ("UserProjectCustomField", ""): ("SingleUserIssueCustomField", _user_login),
+    ("OwnedProjectCustomField", ""): ("SingleOwnedIssueCustomField", _bundle_name),
+    ("VersionProjectCustomField", ""): ("MultiVersionIssueCustomField", _bundle_name),
+    ("BuildProjectCustomField", ""): ("SingleBuildIssueCustomField", _bundle_name),
+    ("PeriodProjectCustomField", ""): ("PeriodIssueCustomField", _bundle_name),
+    ("SimpleProjectCustomField", "string"): ("SimpleIssueCustomField", _scalar),
 }
 
 # Default target field names for semantic CLI slots.
@@ -273,14 +303,10 @@ class FieldSchema:
             self._debug.debug("fields", f"resolving slot '{slot}' -> target '{target_name}'")
 
             field = self._find_field(project_fields, target_name, slot)
-            issue_type = _PROJECT_TO_ISSUE_TYPE.get(field.project_field_type)
-            if not issue_type:
-                raise ValidationError(
-                    f"Unsupported field type '{field.project_field_type}' for field '{field.name}'"
-                )
+            issue_type, builder = self._resolve_dispatch(field)
 
             validated_value = self._validate_field_value(field, value)
-            field_value = self._field_value_payload(field, validated_value)
+            field_value = builder(validated_value) if validated_value is not None else None
             self._debug.debug(
                 "fields",
                 f"resolved '{slot}' -> field '{field.name}' ($type={issue_type})",
@@ -341,13 +367,9 @@ class FieldSchema:
         """
         project_fields = self.get_fields(project_id)
         field = self._find_field_fuzzy(project_fields, field_name)
-        issue_type = _PROJECT_TO_ISSUE_TYPE.get(field.project_field_type)
-        if not issue_type:
-            raise ValidationError(
-                f"Unsupported field type '{field.project_field_type}' for field '{field.name}'"
-            )
+        issue_type, builder = self._resolve_dispatch(field)
         validated_value = self._validate_field_value(field, value)
-        field_value = self._field_value_payload(field, validated_value)
+        field_value = builder(validated_value) if validated_value is not None else None
         self._debug.debug(
             "fields",
             f"resolved generic '{field_name}' -> field '{field.name}' "
@@ -387,19 +409,30 @@ class FieldSchema:
         """Return True if this field is a user-type field (user[1])."""
         return field.field_type_id.startswith("user")
 
-    def _field_value_payload(
-        self,
+    @staticmethod
+    def _resolve_dispatch(
         field: ProjectCustomField,
-        value: str | None,
-    ) -> dict[str, str] | None:
-        """Build the YouTrack issue-field value payload.
-
-        ``None`` is a deliberate clear operation and must serialize as
-        ``"value": null`` in the final issue mutation payload.
+    ) -> tuple[str, FieldValueBuilder]:
+        """Look up the issue-side ``$type`` and payload builder for *field*.
+
+        Prefers an exact ``(project_field_type, field_type_id)`` key, then
+        falls back to the wildcard ``(project_field_type, "")`` key for
+        families where every subtype shares a payload shape. Unmapped
+        combinations raise a ``ValidationError`` naming both identifiers so
+        a follow-on ticket has the upstream type info it needs.
         """
-        if value is None:
-            return None
-        return {"login": value} if self._is_user_field(field) else {"name": value}
+        key = (field.project_field_type, field.field_type_id)
+        if key in _FIELD_DISPATCH:
+            return _FIELD_DISPATCH[key]
+        wildcard = (field.project_field_type, "")
+        if wildcard in _FIELD_DISPATCH:
+            return _FIELD_DISPATCH[wildcard]
+        raise ValidationError(
+            f"Unsupported custom field type '{field.project_field_type}' "
+            f"with subtype '{field.field_type_id}' for field '{field.name}'. "
+            "kd does not know how to build a safe value payload for this "
+            "YouTrack field family."
+        )
 
     def _validate_field_value(
         self,
@@ -420,7 +453,7 @@ class FieldSchema:
         if self._is_user_field(field):
             return value  # User fields: server validates against group members
         if not field.bundle_values:
-            return value  # Freeform field (period, text) — accept as-is
+            return value  # Freeform family (period or scalar string) — server validates
 
         # Case-insensitive exact match → return canonical name
         value_lower = value.lower()
@@ -683,7 +716,7 @@ class IssueOperations:
             if "=" not in pair:
                 raise ValidationError(f"Invalid field format: '{pair}'. Expected NAME=VALUE")
             name, value = pair.split("=", 1)
-            cf = self._field_schema.resolve_field(project_obj.id, name.strip(), value.strip())
+            cf = self._field_schema.resolve_field(project_obj.id, name.strip(), value)
             result.append(cf)
         return result
 
@@ -1031,24 +1064,44 @@ def _extract_tag_suggestions(error: NotFoundError) -> builtins.list[str]:
     return [part.strip() for part in raw.split(",") if part.strip()]
 
 
-def _missing_tag_resolution(tag: str, error: NotFoundError) -> str:
-    """Format an actionable missing-tag instruction for article push."""
+def _missing_tag_resolution(
+    tag: str,
+    error: NotFoundError,
+    *,
+    context: Literal["create", "push"] = "push",
+) -> str:
+    """Format an actionable missing-tag instruction for ``/article create`` or ``/article push``.
+
+    *context* selects the retry-wording so the create path does not ship
+    push-specific recovery text and vice versa. The shared prelude
+    (heading, near-matches, ``/tag list --prefix``, ``/tag create``)
+    is identical across callers.
+    """
     lines = [f"Tag '{tag}' not found."]
     suggestions = _extract_tag_suggestions(error)
     if suggestions:
         lines.append(f"  Near matches: {', '.join(suggestions)}")
     prefix = _tag_prefix_for_list(tag)
-    lines.extend(
-        [
-            "",
-            f"To use an existing tag:   kd /tag list --prefix {shlex.quote(prefix)}",
-            f"To create a new tag:      kd /tag create {shlex.quote(tag)}",
+    shared = [
+        "",
+        f"To use an existing tag:   kd /tag list --prefix {shlex.quote(prefix)}",
+        f"To create a new tag:      kd /tag create {shlex.quote(tag)}",
+    ]
+    if context == "push":
+        recovery = [
             f"To retry push without this tag: omit --tag {shlex.quote(tag)}",
             "",
             "If you are still curating the tag set, push without --tag and apply tags",
             f"separately with kd /tag add ARTICLE-ID {shlex.quote(tag)}.",
         ]
-    )
+    else:
+        recovery = [
+            f"To retry create without this tag: omit --tag {shlex.quote(tag)} from kd /article create",
+            "",
+            "If you are still curating the tag set, create the article without --tag and apply",
+            f"tags separately with kd /tag add ARTICLE-ID {shlex.quote(tag)}.",
+        ]
+    lines.extend(shared + recovery)
     return "\n".join(lines)
 
 
@@ -1126,9 +1179,21 @@ class ArticleOperations:
 
         When *parent* is given (readable id like ``FB-A-1`` or internal id),
         the new article is attached to that parent in a single POST.
-        When *tags* is given, each tag is applied after article creation.
+        When *tags* is given, tag existence is validated **before** the
+        article write so an unknown tag aborts with an actionable error
+        instead of creating an orphan article that then fails on
+        attachment. After every applied tag, the article is re-fetched
+        so the returned :class:`Article` reflects post-tag state and
+        matches a subsequent ``/article show`` on the returned ID.
         """
         self._debug.info("api", f"creating article in project {project}")
+        if tags:
+            preflight_failed = self._preflight_tags(tags, context="create")
+            if preflight_failed:
+                raise KdError(
+                    "Article create aborted because tagging failed.\n\n"
+                    + "\n\n".join(preflight_failed)
+                )
         project_obj = self._yt.get_project(project)
         parent_ref: IdEntity | None = None
         if parent is not None:
@@ -1152,6 +1217,8 @@ class ArticleOperations:
                     f"Applied: {applied or '(none)'}. "
                     f"Failed: {', '.join(failed)}."
                 )
+            if applied:
+                result = self._articles.get_article(result.id_readable)
         return result
 
     def _apply_tags(
@@ -1182,12 +1249,14 @@ class ArticleOperations:
         *,
         create_missing: bool = False,
         dry_run: bool = False,
+        context: Literal["create", "push"] = "push",
     ) -> builtins.list[str]:
-        """Resolve tags before mutating an article.
+        """Resolve tags before ``/article create`` or ``/article push`` writes.
 
-        Returns actionable failure blocks. When ``create_missing`` is true,
-        missing tags are created before the article write; ``dry_run`` never
-        writes tags and treats missing tags as would-create.
+        Returns actionable failure blocks. *context* selects the retry-wording
+        for missing-tag recovery so create and push do not share push-only
+        prose. ``create_missing`` and ``dry_run`` are push-only flags today
+        and are expected to stay false on the create path.
         """
         if self._tag_ops is None:
             raise KdError("Tag operations not available")
@@ -1206,7 +1275,7 @@ class ArticleOperations:
                             f"Tag '{tag}' not found and could not be created. {create_exc}"
                         )
                     continue
-                failed.append(_missing_tag_resolution(tag, exc))
+                failed.append(_missing_tag_resolution(tag, exc, context=context))
             except KdError as exc:
                 failed.append(f"Tag '{tag}' could not be resolved. {exc}")
         return failed
@@ -1631,12 +1700,28 @@ class TagOperations:
         tag_id = self._resolve_tag(name)
         return self._tags.get_tag(tag_id)
 
-    def create(self, name: str) -> Tag:
-        self._debug.info("api", f"creating tag '{name}'")
-        tag = self._tags.create_tag(name)
-        self._name_cache[name.lower()] = tag.id
-        self._debug.info("api", f"created tag '{name}' ({tag.id})")
-        return tag
+    def create(self, name: str) -> TagCreateResult:
+        """Idempotent tag creation.
+
+        Pre-checks existence via :meth:`_resolve_tag` — the same resolver
+        ``/tag show`` uses, so case-insensitive by construction — and
+        short-circuits with ``action="exists"`` if a tag by that name is
+        already visible. Otherwise POSTs and returns ``action="create"``.
+        ``Tag.name-is-invalid`` from the upstream POST is enriched by
+        ``kd/resources/error-messages.yaml`` into a factual diagnostic
+        naming sharing/visibility and name-acceptance as plausible causes.
+        """
+        try:
+            tag_id = self._resolve_tag(name)
+        except NotFoundError:
+            self._debug.info("api", f"creating tag '{name}'")
+            created = self._tags.create_tag(name)
+            self._name_cache[name.lower()] = created.id
+            self._debug.info("api", f"created tag '{name}' ({created.id})")
+            return TagCreateResult(action="create", tag=created)
+        self._debug.info("api", f"tag '{name}' already exists ({tag_id})")
+        existing = self._tags.get_tag(tag_id)
+        return TagCreateResult(action="exists", tag=existing)
 
     def rename(self, name: str, new_name: str) -> Tag:
         tag_id = self._resolve_tag(name)
@@ -1697,6 +1782,14 @@ class TagOperations:
         composes the OR query (``tag: A or tag: B``).  The single-tag fast
         path is unaffected by ``match`` because one tag is itself the same
         set regardless of combinator.
+
+        Both dispatch paths unconditionally project ``tags(id,name)`` on
+        issue rows — the fast-path field-set (``_TAGGED_ISSUE_FIELDS`` in
+        :mod:`kd.api.tags`) includes it, and the composed-query call
+        passes ``with_tags=True`` to :meth:`YouTrackAPI.list_issues`.
+        Keeps ``/tag entities`` discovery rows in parity with
+        ``/issue show --rich`` and ``/issue list --with-tags`` so
+        tag-matched rows expose which tags caused the match.
         """
         tag_names = [tags] if isinstance(tags, str) else list(tags)
         if not tag_names:
@@ -1710,7 +1803,7 @@ class TagOperations:
         if project is not None:
             query += f" project: {youtrack_query_literal(project)}"
         self._debug.info("api", f"composing multi-tag issue query ({match}): {query}")
-        return self._yt.list_issues(query=query, top=top, skip=skip)
+        return self._yt.list_issues(query=query, top=top, skip=skip, with_tags=True)
 
     def articles(
         self,

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/models/__init__.py

@@ -24,7 +24,7 @@ from kd.models.saved_query import (
     SavedQueryUpdate,
 )
 from kd.models.search import SearchResult
-from kd.models.tag import Tag, TagColor
+from kd.models.tag import Tag, TagColor, TagCreateResult
 from kd.models.tag_entities import EntityRef, KindMeta, TagEntitiesResult
 from kd.models.user import Group, ProjectTeam, User, UserCreate
 from kd.models.work_item import (
@@ -68,6 +68,7 @@ __all__ = [
     "SearchResult",
     "Tag",
     "TagColor",
+    "TagCreateResult",
     "TagEntitiesResult",
     "TimeTrackingSettings",
     "User",

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/models/tag.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Literal
+
 from pydantic import BaseModel, ConfigDict, Field
 
 from kd.models.common import IdEntity, NamedEntity
@@ -28,3 +30,18 @@ class Tag(IdEntity):
     owner: NamedEntity | None = None
     color: TagColor | None = None
     untag_on_resolve: bool = Field(default=False, alias="untagOnResolve")
+
+
+class TagCreateResult(BaseModel):
+    """Result of an idempotent tag-create call.
+
+    ``action`` is ``"create"`` when YouTrack minted a new tag and
+    ``"exists"`` when the pre-check resolved a tag with the requested
+    name (short-circuit, no POST). The ``tag`` field carries the current
+    upstream state either way.
+    """
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    action: Literal["create", "exists"]
+    tag: Tag

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/resources/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to kd-cli are recorded here. The project follows [Semantic V
 
 ## [Unreleased]
 
+## [2.5.1] — 2026-04-19
+
+### Fixed
+- `kd /issue create --field NAME=VALUE` and `kd /issue update --field NAME=VALUE` now accept **string custom fields**. Before: `kd /issue update VIS-21 --field Milestone=M039` rejected with `Error: Unsupported field type 'SimpleProjectCustomField' for field 'Milestone'`, blocking workflows that track freeform per-issue metadata such as a rolling milestone string. `--field "NAME="` clears an optional string field just like it clears enum/user fields today; required string fields reject empty values with the same client-side error shipped in 2.2.2. Whitespace inside the value is preserved — `--field "Milestone=  M 039  "` sends `  M 039  ` verbatim. Only the field **name** is trimmed (KDCLI-106).
+
+### Changed
+- Unsupported custom-field errors now name both identifiers and the cause. Before: `Error: Unsupported field type 'X' for field 'Y'`. Now: `Error: Unsupported custom field type 'X' with subtype 'Y' for field 'Z'. kd does not know how to build a safe value payload for this YouTrack field family.` Applies to YouTrack text fields, multi-arity enum/user variants, and integer/float/date simple-field subtypes — paste the message into a bug report and the two type identifiers are already there (KDCLI-106).
+
+## [2.5.0] — 2026-04-19
+
+Dogfooding friction fixes across tag and article workflows, plus self-describing `/system info` output for bug reports. Focus of this release: the taxonomy and article-create loops now behave the way field use expects, and a paste of `kd /system info -o yaml` replaces hand-typed version footers.
+
+### Added
+- `kd /system info` now carries three additional fields alongside the existing connection identity: `kd_version` (matches `kd --version`), `python_version`, and `platform`. Paste `kd /system info -o yaml` into a bug report to tie an observed behavior to a specific build without hand-typing the version. The four existing keys (`url`, `user`, `name`, `email`) are unchanged; redact `url` / `email` before sharing externally (KDCLI-104).
+
+### Changed
+- `kd /tag create TAG_NAME` is now idempotent and returns a `{ok, action, tag}` envelope with `action` being either `create` or `exists`. Re-running create on an already-visible tag is safe and no longer surfaces `Tag.name-is-invalid`. **Breaking vs. the prior flat tag object** — downstream scripts and SDK consumers that parsed the top-level tag fields must now read from the nested `tag:` block. Python SDK: the `create(...)` method on the tag operations client returns a `TagCreateResult(action, tag)` object; unpack `.tag` to reach the tag fields (KDCLI-105).
+
+### Fixed
+- `kd /tag create TAG_NAME` against an already-existing tag no longer emits the raw upstream `Tag.name-is-invalid` error. When the POST still fails (genuinely unacceptable name, or a tag hidden by sharing/visibility that the caller cannot see), the error names both plausible causes without inventing a character grammar (KDCLI-105).
+- `kd /tag entities` structured output (`-o yaml` / `-o json`, including `--primer-scope`) now populates the `tags` field on issue rows, bringing the verb to parity with `/issue show --rich` and `/issue list --with-tags`. Before: structured issue rows reported `tags: []` even when they matched via a pinned tag, forcing a second `/issue show` round-trip to see which tag caused the match. Table output is unchanged and still omits the tag column by design (KDCLI-100).
+- `kd /article create --tag TAG` structured output now returns the post-tag article state: the response `tags` field matches a subsequent `kd /article show` on the returned id. Missing tags are rejected **before** the article is created, so a typo in `--tag` no longer leaves an untagged article behind; the error names `kd /tag create` for the missing tag, retrying `kd /article create` without the tag, or applying the tag after create via `kd /tag add ARTICLE-ID TAG`. Before: the CLI rendered `tags: ''` even when tags were attached upstream (KDCLI-101).
+
 ## [2.4.1] — 2026-04-19
 
 ### Fixed

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/resources/error-messages.yaml

@@ -70,6 +70,17 @@
   message: 'Issue {id} not found'
   suggestion: 'Check the issue ID and project key.'
 
+# --- Tag create 400 (path-scoped so rename POSTs are unaffected) ---
+
+- status: 400
+  path: '/tags$'
+  pattern: 'Tag\.name-is-invalid'
+  message: 'YouTrack rejected the tag name.'
+  suggestion: >-
+    The tag may already exist but be hidden by sharing or visibility
+    settings, or the name may contain characters YouTrack does not accept.
+    Verify with 'kd /tag show TAG_NAME' or try a different name.
+
 # --- Query parse errors ---
 
 - pattern: "(?i)can.t parse search query"

{kd_cli-2.4.1 → kd_cli-2.5.1}/kd/resources/operating-guide.md

@@ -108,6 +108,8 @@ kd /project/field list KDCLI
 
 Clear optional custom fields with an empty value, for example `kd /issue update KDCLI-42 --field "Milestone="`. Required fields reject empty values before any upstream write.
 
+`--field` supports bundle families (enum, state, owned, version, build), user fields, period, and string `SimpleProjectCustomField` subtypes; whitespace inside the value is preserved. Unsupported families (text, `Multi*` enum/user variants, and `SimpleProjectCustomField` with `integer` / `float` / `date` subtypes) fail client-side with a message naming both the project `$type` and the `fieldType.id` subtype so a follow-on bug report can skip the probe.
+
 Attachment metadata download URLs may start with `/api/`. kd handles this internally on download commands; do not assume the raw URL can be appended unchanged to an API base URL in custom scripts.
 
 Tag existence, tag visibility, and tag sharing rights are different concerns. A visible tag may not be usable for every operation, and sharing settings are provider-specific security posture, not just display metadata.
@@ -158,6 +160,8 @@ Do not use push for one-off web edits or broad tree migration. It is single-file
 
 When pushing with `--tag`, kd validates all tags before the article write. Missing tags abort with commands to list the namespace, create the tag, retry without it, or apply the tag separately after push. `--create-tags` is the explicit opt-in for automation that should create missing tags first.
 
+`/article create --tag` applies the same preflight: every tag must exist, missing tags abort before the article write (no orphan article on a typo), and the structured response reflects post-tag state so it matches an immediate `/article show` on the returned id. There is no `--create-tags` on `/article create` — curate the namespace with `/tag create` first, or omit `--tag` and apply tags after creation via `/tag add ARTICLE-ID TAG`.
+
 ## Tags And Discovery
 
 Tags are the main YouTrack-native cross-entity discovery primitive. A namespaced taxonomy such as `kind:*`, `component:*`, and `outcome:*` gives both humans and LLMs a stable way to move across issues and articles.
@@ -182,6 +186,10 @@ Use `/tag entities` when the question is "what do we know about this topic acros
 
 Do not treat `--primer-scope` as implicit global state. It is a deliberate flag for content-management triage and workspace orientation. When you need a precise topical intersection, pass the tags explicitly.
 
+`/tag entities` structured output (`-o yaml` / `-o json`) populates the `tags` field on both issue and article rows with the entity's visible tags, so a primer-scope or explicit-tag match is self-describing — no second `/issue show` round-trip is needed to confirm which tags caused a row to surface. Table output groups by kind and does not render a tag column.
+
+`/tag create TAG_NAME` is idempotent. It resolves the name first (same case-insensitive resolver `/tag show` uses) and returns `{ok, action, tag}` with `action: exists` when the tag is already visible, or `action: create` after a successful POST. Taxonomy bootstrapping and fixture setup can re-run the command safely without decoding `Tag.name-is-invalid`. When the POST still fails — either a genuinely unacceptable name or an existing tag hidden by sharing/visibility — kd surfaces a factual diagnostic naming both plausible causes rather than the raw upstream error.
+
 ## Output And Debugging
 
 For deterministic machine consumption, always pass an explicit output format:
@@ -211,6 +219,8 @@ kd /system/config which primer_show.output
 
 If a command exits 0 but includes `warnings` in JSON or YAML, keep the primary result and inspect the warning code. For example, `tag_not_found` on `/primer/tag add` means the local primer changed but the upstream tag did not resolve at validation time.
 
+When filing a kd bug, include the output of `kd /system info -o yaml`. It names the active connection alongside `kd_version`, `python_version`, and `platform`, so the report is self-describing without hand-typing the version. Redact `url` / `email` before sharing externally.
+
 ## Where To Go Next
 
 Use these sources together:

{kd_cli-2.4.1 → kd_cli-2.5.1/kd_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kd-cli
-Version: 2.4.1
+Version: 2.5.1
 Summary: Knowledge Dispatcher for issue trackers and knowledge bases
 Author: Sergiy Gladkyy
 License-Expression: MIT

{kd_cli-2.4.1 → kd_cli-2.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kd-cli"
-version = "2.4.1"
+version = "2.5.1"
 description = "Knowledge Dispatcher for issue trackers and knowledge bases"
 readme = "README.md"
 requires-python = ">=3.11"