kd-cli 2.0.4__py3-none-any.whl

kd/client.py

@@ -0,0 +1,1953 @@
+"""YouTrackClient — main SDK entry point.
+
+Composes YouTrackAPI and HubAPI into a single high-level interface.
+Accepts a :class:`~kd.connection.ConnectionContext` (resolved URL + token)
+and provides grouped access to operations:
+
+    from kd.connection import ConnectionContext
+    ctx = ConnectionContext(name="main", provider="youtrack",
+                            base_url="https://yt.example.com", token="perm:...",
+                            default_project=None, output=None, limit=None,
+                            defaults={}, compat_tier="auto", capabilities=frozenset())
+    client = YouTrackClient(connection=ctx)
+
+For quick SDK usage, ``url`` and ``token`` keyword arguments are also accepted:
+
+    client = YouTrackClient(url="https://yt.example.com", token="perm:...")
+"""
+
+from __future__ import annotations
+
+import builtins
+import difflib
+from collections import OrderedDict
+from dataclasses import dataclass, field as dataclass_field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from kd.api.articles import ArticlesAPI
+from kd.api.http import HttpClient
+from kd.api.hub import HubAPI
+from kd.api.saved_queries import SavedQueriesAPI
+from kd.api.tags import TagsAPI
+from kd.api.youtrack import YouTrackAPI
+from kd.article_marker import (
+    ArticleMarker,
+    MarkerError,
+    ParsedFile,
+    parse_content,
+    render_content,
+    validate_slug,
+)
+from kd.config import ResolvedConfig
+from kd.connection import ConnectionContext
+from kd.debug import DebugLog
+from kd.exceptions import APIError, ConfigError, NotFoundError, ValidationError, KdError
+from kd.models import (
+    Article,
+    ArticleCreate,
+    ArticleUpdate,
+    AssistResponse,
+    Attachment,
+    BundleValue,
+    Comment,
+    CommentCreate,
+    CustomField,
+    Duration,
+    IdEntity,
+    Issue,
+    IssueCreate,
+    IssueUpdate,
+    Project,
+    ProjectCreate,
+    ProjectCustomField,
+    QueryValidationResult,
+    SavedQuery,
+    SavedQueryCreate,
+    SavedQueryUpdate,
+    SearchResult,
+    Tag,
+    TimeTrackingSettings,
+    User,
+    UserCreate,
+    WorkItem,
+    WorkItemCreate,
+    WorkItemType,
+    WorkItemUpdate,
+)
+
+
+# Maps user-friendly link type names to YT command language strings.
+# Used with POST /api/commands to create issue links.
+_LINK_TYPE_MAP: dict[str, str] = {
+    "subtask-of": "subtask of",
+    "parent-for": "parent for",
+    "depends-on": "depends on",
+    "required-for": "is required for",
+    "duplicates": "duplicates",
+    "duplicated-by": "is duplicated by",
+    "relates-to": "relates to",
+}
+
+
+def _resolve_link_command(link_type: str) -> str:
+    """Resolve a user-friendly link type to a YT command string."""
+    result = _LINK_TYPE_MAP.get(link_type.lower())
+    if not result:
+        valid = ", ".join(sorted(_LINK_TYPE_MAP))
+        raise ValidationError(f"Unknown link type '{link_type}'. Valid types: {valid}")
+    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",
+}
+
+# Default target field names for semantic CLI slots.
+_SLOT_DEFAULTS: dict[str, str] = {
+    "state": "State",
+    "type": "Type",
+    "priority": "Priority",
+}
+
+
+# ---------------------------------------------------------------------------
+# Article push — types and helpers
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PushResult:
+    """Outcome of ``ArticleOperations.push``.
+
+    - ``action`` is ``"create"`` or ``"update"``. An ``"unchanged"``
+      no-op would require a content-hash optimization the M029 marker
+      format explicitly defers to a later milestone.
+    - ``article_id`` is the readable id of the target article (empty
+      string for dry-run of a create that has not written yet).
+    - ``remote_updated_sec`` is the epoch-seconds timestamp of the
+      article's ``updated`` field on the upstream side after the push.
+      Zero for dry-runs that did not resolve an existing article.
+    """
+
+    action: Literal["create", "update"]
+    article_id: str
+    slug: str
+    path: Path
+    remote_updated_sec: int
+    dry_run: bool
+    tags_applied: builtins.list[str] = dataclass_field(default_factory=list)
+    tags_failed: builtins.list[str] = dataclass_field(default_factory=list)
+
+
+def _derive_slug_from_path(file_path: Path) -> str:
+    """Derive a slug from a file path: stem relative to CWD if possible.
+
+    ``docs/infra/dns-setup.md`` → ``docs/infra/dns-setup`` (when run
+    from the directory containing ``docs``).
+    """
+    try:
+        rel = file_path.resolve().relative_to(Path.cwd().resolve())
+    except ValueError:
+        rel = Path(file_path.name)
+    # Drop the last suffix only; keep intermediate dots (e.g. v1.2).
+    parent = rel.parent
+    stem = rel.stem
+    if str(parent) in ("", "."):
+        return stem
+    return f"{parent.as_posix()}/{stem}"
+
+
+def _iso_to_epoch_sec(iso: str) -> int:
+    """Parse ``YYYY-MM-DDTHH:MM:SSZ`` into epoch seconds (UTC).
+
+    Raises ``ValueError`` on malformed input; callers decide whether
+    to treat that as a conflict or a first-push.
+    """
+    return int(
+        datetime.strptime(iso, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc).timestamp()
+    )
+
+
+def _epoch_sec_to_iso(sec: int) -> str:
+    """Format epoch seconds (UTC) as ``YYYY-MM-DDTHH:MM:SSZ``."""
+    return datetime.fromtimestamp(sec, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+    """Write *text* to *path* atomically.
+
+    Delegates to :func:`kd.history.atomic_write_text`.
+    """
+    from kd.history import atomic_write_text
+
+    atomic_write_text(path, text)
+
+
+class FieldSchema:
+    """Per-project custom field discovery and semantic resolution.
+
+    Caches project field metadata on first access. Resolves semantic
+    CLI slots (state, type, priority) to actual project field names
+    using config aliases, name matching, and field type matching.
+    """
+
+    def __init__(self, yt: YouTrackAPI, debug_log: DebugLog | None = None) -> None:
+        self._yt = yt
+        self._debug = debug_log or DebugLog()
+        self._cache: dict[str, builtins.list[ProjectCustomField]] = {}
+
+    def get_fields(self, project_id: str) -> builtins.list[ProjectCustomField]:
+        """Fetch and cache custom fields for a project."""
+        if project_id in self._cache:
+            self._debug.debug("fields", f"cache hit for project {project_id}")
+            return self._cache[project_id]
+
+        self._debug.info("fields", f"discovering custom fields for project {project_id}")
+        raw = self._yt.list_project_custom_fields(project_id)
+        fields = [self._convert(item) for item in raw]
+        self._cache[project_id] = fields
+        self._debug.debug(
+            "fields",
+            f"discovered {len(fields)} fields: {', '.join(f.name for f in fields)}",
+        )
+        return fields
+
+    def resolve_semantic_fields(
+        self,
+        project_id: str,
+        slots: dict[str, str],
+        aliases: dict[str, str] | None = None,
+    ) -> builtins.list[CustomField]:
+        """Resolve semantic slot names to CustomField objects for issue mutations.
+
+        ``slots`` maps semantic names to values, e.g. ``{"type": "Bug", "state": "Open"}``.
+        ``aliases`` maps semantic names to actual field names from config.
+        """
+        if not slots:
+            return []
+
+        project_fields = self.get_fields(project_id)
+        aliases = aliases or {}
+        result: builtins.list[CustomField] = []
+
+        for slot, value in slots.items():
+            target_name = aliases.get(slot, _SLOT_DEFAULTS.get(slot, slot))
+            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}'"
+                )
+
+            validated_value = self._validate_field_value(field, value)
+            field_value = (
+                {"login": validated_value}
+                if self._is_user_field(field)
+                else {"name": validated_value}
+            )
+            self._debug.debug(
+                "fields",
+                f"resolved '{slot}' -> field '{field.name}' ($type={issue_type})",
+            )
+            result.append(
+                CustomField.model_validate(
+                    {"name": field.name, "value": field_value, "$type": issue_type}
+                )
+            )
+
+        return result
+
+    def _find_field(
+        self,
+        fields: builtins.list[ProjectCustomField],
+        target_name: str,
+        slot: str,
+    ) -> ProjectCustomField:
+        """Find a project field by name match, then type-based fallback for state."""
+        target_lower = target_name.lower()
+
+        # Name match (case-insensitive)
+        for f in fields:
+            if f.name.lower() == target_lower:
+                return f
+
+        # Type-based fallback: state slot -> field with state[1] type
+        if slot == "state":
+            for f in fields:
+                if f.field_type_id == "state[1]":
+                    self._debug.info(
+                        "fields",
+                        f"no field named '{target_name}', "
+                        f"falling back to state-type field '{f.name}'",
+                    )
+                    return f
+
+        field_names = [f.name for f in fields]
+        close = difflib.get_close_matches(target_name, field_names, n=3, cutoff=0.6)
+        candidates = ", ".join(f"{f.name} ({f.field_type_id})" for f in fields)
+        msg = f"Cannot resolve field '{slot}' (target: '{target_name}') in project."
+        if close:
+            msg += f" Did you mean: {', '.join(close)}?"
+        msg += f" Available fields: {candidates}"
+        raise ValidationError(msg)
+
+    def resolve_field(
+        self,
+        project_id: str,
+        field_name: str,
+        value: str,
+    ) -> CustomField:
+        """Resolve a generic field name + value to a CustomField for issue mutations.
+
+        Uses fuzzy matching for field names and validates values against
+        the field's bundle. Auto-corrects case on exact case-insensitive
+        value matches.
+        """
+        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}'"
+            )
+        validated_value = self._validate_field_value(field, value)
+        field_value = (
+            {"login": validated_value} if self._is_user_field(field) else {"name": validated_value}
+        )
+        self._debug.debug(
+            "fields",
+            f"resolved generic '{field_name}' -> field '{field.name}' "
+            f"value '{validated_value}' ($type={issue_type})",
+        )
+        return CustomField.model_validate(
+            {"name": field.name, "value": field_value, "$type": issue_type}
+        )
+
+    def _find_field_fuzzy(
+        self,
+        fields: builtins.list[ProjectCustomField],
+        target_name: str,
+    ) -> ProjectCustomField:
+        """Find a field by name with fuzzy matching fallback."""
+        target_lower = target_name.lower()
+
+        # Exact case-insensitive match
+        for f in fields:
+            if f.name.lower() == target_lower:
+                return f
+
+        # Fuzzy match — suggest close names
+        field_names = [f.name for f in fields]
+        close = difflib.get_close_matches(target_name, field_names, n=3, cutoff=0.6)
+        candidates = ", ".join(f"{f.name} ({f.field_type_id})" for f in fields)
+        if close:
+            raise ValidationError(
+                f"Unknown field '{target_name}'. "
+                f"Did you mean: {', '.join(close)}? "
+                f"Available fields: {candidates}"
+            )
+        raise ValidationError(f"Unknown field '{target_name}'. Available fields: {candidates}")
+
+    @staticmethod
+    def _is_user_field(field: ProjectCustomField) -> bool:
+        """Return True if this field is a user-type field (user[1])."""
+        return field.field_type_id.startswith("user")
+
+    def _validate_field_value(
+        self,
+        field: ProjectCustomField,
+        value: str,
+    ) -> str:
+        """Validate a value against the field's bundle.
+
+        Returns the canonical value name (case-corrected).
+        Raises ValidationError with allowed values on mismatch.
+        """
+        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
+
+        # Case-insensitive exact match → return canonical name
+        value_lower = value.lower()
+        for bv in field.bundle_values:
+            if bv.name.lower() == value_lower:
+                return bv.name
+
+        # No match — suggest close values
+        value_names = [bv.name for bv in field.bundle_values]
+        close = difflib.get_close_matches(value, value_names, n=3, cutoff=0.6)
+        allowed = ", ".join(value_names)
+        if close:
+            raise ValidationError(
+                f"Invalid value '{value}' for field '{field.name}'. "
+                f"Did you mean: {', '.join(close)}? "
+                f"Allowed values: {allowed}"
+            )
+        raise ValidationError(
+            f"Invalid value '{value}' for field '{field.name}'. Allowed values: {allowed}"
+        )
+
+    @staticmethod
+    def _convert(raw: dict[str, Any]) -> ProjectCustomField:
+        """Convert raw API dict to ProjectCustomField model."""
+        field_info = raw.get("field", {})
+        field_type = field_info.get("fieldType", {})
+        bundle = raw.get("bundle", {})
+        bundle_vals = bundle.get("values", [])
+
+        return ProjectCustomField(
+            name=field_info.get("name", ""),
+            field_type_id=field_type.get("id", ""),
+            project_field_type=raw.get("$type", ""),
+            can_be_empty=raw.get("canBeEmpty", True),
+            empty_field_text=raw.get("emptyFieldText"),
+            bundle_values=[
+                BundleValue.model_validate(
+                    {
+                        "name": v.get("name", ""),
+                        "ordinal": v.get("ordinal", 0),
+                        "isResolved": v.get("isResolved"),
+                    }
+                )
+                for v in bundle_vals
+            ],
+        )
+
+
+class YouTrackClient:
+    """Main SDK entry point."""
+
+    def __init__(
+        self,
+        connection: ConnectionContext | None = None,
+        *,
+        url: str | None = None,
+        token: str | None = None,
+        config: ResolvedConfig | None = None,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._debug = debug_log or DebugLog()
+
+        if connection is None:
+            # SDK convenience: build a synthetic ConnectionContext from url/token
+            if not url:
+                raise ConfigError(
+                    "No YouTrack URL. Provide a ConnectionContext or url= keyword argument."
+                )
+            if not token:
+                raise ConfigError(
+                    "No API token. Provide a ConnectionContext or token= keyword argument."
+                )
+            connection = ConnectionContext(
+                name="sdk",
+                provider="youtrack",
+                base_url=url,
+                token=token,
+                default_project=None,
+                output=None,
+                limit=None,
+                defaults={},
+                compat_tier="auto",
+                capabilities=frozenset(),
+            )
+
+        base_url = connection.base_url
+        resolved_token = connection.token
+
+        self._yt_http = HttpClient(
+            base_url=f"{base_url}/api",
+            token=resolved_token,
+            debug_log=self._debug,
+        )
+        self._hub_http = HttpClient(
+            base_url=f"{base_url}/hub/api/rest",
+            token=resolved_token,
+            debug_log=self._debug,
+        )
+
+        self._config = config
+        self._yt_api = YouTrackAPI(self._yt_http)
+        self._hub_api = HubAPI(self._hub_http)
+        self._articles_api = ArticlesAPI(self._yt_http)
+        self._tags_api = TagsAPI(self._yt_http)
+        self._saved_queries_api = SavedQueriesAPI(self._yt_http)
+        self._field_schema = FieldSchema(self._yt_api, self._debug)
+
+        self.tags = TagOperations(self._tags_api, self._articles_api, self._yt_api, self._debug)
+        self.articles = ArticleOperations(
+            self._articles_api, self._yt_api, tag_ops=self.tags, debug_log=self._debug
+        )
+        self.projects = ProjectOperations(self._yt_api, self._field_schema, self._debug)
+        self.issues = IssueOperations(self._yt_api, self._field_schema, self._debug)
+        self.attachments = AttachmentOperations(self._yt_api, self._debug)
+        self.users = UserOperations(self._yt_api, self._hub_api, self._debug)
+        self.time = TimeOperations(self._yt_api, self._debug)
+        self.queries = SavedQueryOperations(
+            self._saved_queries_api, self._yt_api, tag_ops=self.tags, debug_log=self._debug
+        )
+        self.assist = AssistOperations(self._yt_api, self._debug)
+        self.search = SearchOperations(
+            self._yt_api, self._articles_api, self._tags_api, self._debug
+        )
+
+    @property
+    def config(self) -> ResolvedConfig | None:
+        """Resolved config, if available."""
+        return self._config
+
+    def create_issue_with_attachments(
+        self,
+        project: str,
+        summary: str,
+        description: str | None = None,
+        custom_fields: builtins.list[CustomField] | None = None,
+        file_paths: builtins.list[Path] | None = None,
+    ) -> Issue:
+        """Composite: create issue + upload attachments.
+
+        Returns the issue with attachment metadata populated.
+        If attachment upload fails, the issue still exists (no rollback).
+        """
+        issue = self.issues.create(
+            project=project,
+            summary=summary,
+            description=description,
+            custom_fields=custom_fields,
+        )
+        if file_paths:
+            self._debug.info(
+                "api",
+                f"uploading {len(file_paths)} attachment(s) to {issue.id_readable}",
+            )
+            self.attachments.add(issue.id_readable, file_paths)
+            issue = self.issues.get(issue.id_readable, detail="rich")
+        return issue
+
+    def close(self) -> None:
+        """Close underlying HTTP connections."""
+        self._yt_http.close()
+        self._hub_http.close()
+
+
+class ProjectOperations:
+    """High-level project operations."""
+
+    def __init__(
+        self,
+        yt: YouTrackAPI,
+        field_schema: FieldSchema,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._yt = yt
+        self._field_schema = field_schema
+        self._debug = debug_log or DebugLog()
+
+    def list(self, top: int = 50, skip: int = 0) -> builtins.list[Project]:
+        return self._yt.list_projects(top=top, skip=skip)
+
+    def list_fields(self, project_id: str) -> builtins.list[ProjectCustomField]:
+        """List custom fields for a project."""
+        return self._field_schema.get_fields(project_id)
+
+    def get(self, project_id: str) -> Project:
+        return self._yt.get_project(project_id)
+
+    def create(self, name: str, short_name: str, leader_id: str | None = None) -> Project:
+        """Create a project. Defaults leader to the current user if not specified."""
+        self._debug.info("api", f"creating project {name} ({short_name})")
+        if not leader_id:
+            me = self._yt.get_me()
+            leader_id = me["id"]
+        result = self._yt.create_project(
+            ProjectCreate(name=name, shortName=short_name, leader=IdEntity(id=leader_id))
+        )
+        self._debug.info("api", f"created project {result.short_name}")
+        return result
+
+    def delete(self, project_id: str) -> None:
+        self._yt.delete_project(project_id)
+
+    def configure_time_tracking(self, project_id: str, enabled: bool) -> TimeTrackingSettings:
+        """Enable or disable time tracking on a project."""
+        self._yt.update_time_tracking_settings(project_id, enabled)
+        return self._yt.get_time_tracking_settings(project_id)
+
+
+class IssueOperations:
+    """High-level issue operations."""
+
+    def __init__(
+        self,
+        yt: YouTrackAPI,
+        field_schema: FieldSchema,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._yt = yt
+        self._field_schema = field_schema
+        self._debug = debug_log or DebugLog()
+
+    def list(self, query: str = "", top: int = 50, skip: int = 0) -> builtins.list[Issue]:
+        return self._yt.list_issues(query=query, top=top, skip=skip)
+
+    def resolve_custom_fields(
+        self,
+        project: str,
+        slots: dict[str, str],
+        aliases: dict[str, str] | None = None,
+    ) -> builtins.list[CustomField]:
+        """Resolve semantic field names to CustomField objects for a project.
+
+        ``project`` is the project shortName (KEY).
+        ``slots`` maps semantic names to values, e.g. ``{"type": "Bug"}``.
+        ``aliases`` maps semantic names to actual field names from config.
+        """
+        project_obj = self._yt.get_project(project)
+        return self._field_schema.resolve_semantic_fields(project_obj.id, slots, aliases)
+
+    def resolve_generic_fields(
+        self,
+        project: str,
+        field_pairs: builtins.list[str],
+    ) -> builtins.list[CustomField]:
+        """Resolve generic NAME=VALUE field pairs to CustomField objects.
+
+        Each pair is a string like ``"Sprint=Sprint 47"`` or ``"Story Points=5"``.
+        Uses fuzzy matching for field names and validates values against bundles.
+        """
+        if not field_pairs:
+            return []
+        project_obj = self._yt.get_project(project)
+        result: builtins.list[CustomField] = []
+        for pair in field_pairs:
+            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())
+            result.append(cf)
+        return result
+
+    def get(self, issue_id: str, detail: str = "rich") -> Issue:
+        """Fetch an issue. ``detail`` is 'rich' (default) or 'brief'."""
+        return self._yt.get_issue(issue_id, rich=(detail == "rich"))
+
+    def create(
+        self,
+        project: str,
+        summary: str,
+        description: str | None = None,
+        custom_fields: builtins.list[CustomField] | None = None,
+    ) -> Issue:
+        """Create an issue. ``project`` is the project shortName (KEY)."""
+        self._debug.info("api", f"creating issue in project {project}")
+        project_obj = self._yt.get_project(project)
+        result = self._yt.create_issue(
+            IssueCreate(
+                project=IdEntity(id=project_obj.id),
+                summary=summary,
+                description=description,
+                customFields=custom_fields,
+            )
+        )
+        self._debug.info("api", f"created {result.id_readable}")
+        return result
+
+    def update(
+        self,
+        issue_id: str,
+        summary: str | None = None,
+        description: str | None = None,
+        custom_fields: builtins.list[CustomField] | None = None,
+    ) -> Issue:
+        return self._yt.update_issue(
+            issue_id,
+            IssueUpdate(summary=summary, description=description, customFields=custom_fields),
+        )
+
+    def delete(self, issue_id: str) -> None:
+        self._yt.delete_issue(issue_id)
+
+    def list_comments(self, issue_id: str) -> builtins.list[Comment]:
+        return self._yt.list_comments(issue_id)
+
+    def add_comment(self, issue_id: str, text: str) -> Comment:
+        return self._yt.create_comment(issue_id, CommentCreate(text=text))
+
+    def list_links(self, issue_id: str) -> builtins.list[dict[str, Any]]:
+        """List all links on an issue."""
+        return self._yt.list_issue_links(issue_id)
+
+    def link(self, issue_id: str, link_type: str, target_id: str) -> None:
+        """Link two issues. ``link_type`` is a user-friendly name like 'subtask-of'."""
+        command_str = _resolve_link_command(link_type)
+        self._yt.apply_command(issue_id, f"{command_str} {target_id}")
+
+    def assign(self, issue_id: str, user_ref: str) -> User:
+        """Assign an issue. Returns the resolved user.
+
+        ``user_ref`` may be a login, email, display name, or ``"me"``.
+        """
+        self._debug.info("api", f"assigning {issue_id} to '{user_ref}'")
+        user = self._resolve_user(user_ref)
+        self._debug.debug("api", f"resolved user '{user_ref}' -> {user.login}")
+        self._yt.apply_command(issue_id, f"Assignee {user.login}")
+        return user
+
+    def unassign(self, issue_id: str) -> None:
+        """Remove the assignee from an issue."""
+        self._yt.apply_command(issue_id, "Assignee Unassigned")
+
+    def list_assignees(self, query: str = "") -> builtins.list[User]:
+        """Search users that could be assigned."""
+        return self._yt.search_users(query)
+
+    def move(self, issue_id: str, target_project: str) -> None:
+        """Move an issue to another project via the commands API."""
+        self._yt.apply_command(issue_id, f"move to {target_project}")
+
+    def _resolve_user(self, user_ref: str) -> User:
+        """Resolve a flexible user reference to a User object.
+
+        Resolution order:
+        1. ``"me"`` → current authenticated user
+        2. Exact match on login
+        3. Exact match on email
+        4. Exact match on name (case-insensitive)
+        5. Unique prefix match on login
+        6. Fail with candidates
+        """
+        if user_ref.lower() == "me":
+            data = self._yt.get_me()
+            return User.model_validate(data)
+
+        candidates = self._yt.search_users(user_ref)
+        self._debug.debug("api", f"user resolution: {len(candidates)} candidates for '{user_ref}'")
+        if not candidates:
+            raise NotFoundError(f"User not found: '{user_ref}'")
+
+        # Exact login
+        for u in candidates:
+            if u.login == user_ref:
+                return u
+
+        # Exact email
+        for u in candidates:
+            if u.email and u.email == user_ref:
+                return u
+
+        # Exact name (case-insensitive)
+        ref_lower = user_ref.lower()
+        for u in candidates:
+            if u.name.lower() == ref_lower:
+                return u
+
+        # Unique prefix on login
+        prefix_matches = [u for u in candidates if u.login.startswith(user_ref)]
+        if len(prefix_matches) == 1:
+            return prefix_matches[0]
+
+        # Ambiguous — show rich candidate info
+        lines = [f"Ambiguous user reference '{user_ref}'. Candidates:"]
+        for u in candidates:
+            parts = [f"  {u.login}"]
+            if u.name:
+                parts.append(f"({u.name})")
+            if u.email:
+                parts.append(f"<{u.email}>")
+            lines.append(" ".join(parts))
+        raise ValidationError("\n".join(lines))
+
+
+class AttachmentOperations:
+    """High-level attachment operations."""
+
+    def __init__(self, yt: YouTrackAPI, debug_log: DebugLog | None = None) -> None:
+        self._yt = yt
+        self._debug = debug_log or DebugLog()
+
+    def list(self, issue_id: str) -> builtins.list[Attachment]:
+        return self._yt.list_attachments(issue_id)
+
+    def get(self, issue_id: str, attachment_id: str) -> Attachment:
+        return self._yt.get_attachment(issue_id, attachment_id)
+
+    def add(self, issue_id: str, file_paths: builtins.list[Path]) -> builtins.list[Attachment]:
+        """Upload one or more files as attachments."""
+        self._debug.info("api", f"uploading {len(file_paths)} attachment(s) to {issue_id}")
+        results: builtins.list[Attachment] = []
+        for fp in file_paths:
+            if not fp.is_file():
+                raise ValidationError(f"File not found: {fp}")
+            content = fp.read_bytes()
+            att = self._yt.create_attachment(issue_id, fp.name, content)
+            self._debug.debug("api", f"  uploaded {fp.name} ({len(content)} bytes)")
+            results.append(att)
+        return results
+
+    def download(
+        self,
+        issue_id: str,
+        attachment_id: str,
+        target_dir: Path | None = None,
+    ) -> Path:
+        """Download an attachment to disk. Returns the written file path."""
+        meta = self._yt.get_attachment(issue_id, attachment_id)
+        if not meta.url:
+            raise ValidationError(f"Attachment {attachment_id} has no download URL")
+        # The URL from YT starts with /api/ but HttpClient base already includes /api
+        download_path = meta.url
+        if download_path.startswith("/api/"):
+            download_path = download_path[4:]  # strip /api prefix
+        content = self._yt._http.get_bytes(download_path)
+        dest_dir = target_dir or Path.cwd()
+        dest = dest_dir / meta.name
+        try:
+            dest.write_bytes(content)
+        except OSError as e:
+            raise KdError(f"Cannot write to {dest}: {e}") from e
+        return dest
+
+    def delete(self, issue_id: str, attachment_id: str) -> None:
+        self._yt.delete_attachment(issue_id, attachment_id)
+
+
+class UserOperations:
+    """High-level user operations. Bridges YT and Hub APIs."""
+
+    def __init__(self, yt: YouTrackAPI, hub: HubAPI, debug_log: DebugLog | None = None) -> None:
+        self._yt = yt
+        self._hub = hub
+        self._debug = debug_log or DebugLog()
+
+    def list(self, top: int = 100, skip: int = 0) -> builtins.list[User]:
+        return self._hub.list_users(top=top, skip=skip)
+
+    def create(self, login: str, name: str, email: str) -> User:
+        return self._hub.create_user(UserCreate(login=login, name=name, email=email))
+
+    def delete(self, hub_user_id: str) -> None:
+        self._hub.delete_user(hub_user_id)
+
+    def add_to_team(self, user_login: str, project_id: str) -> None:
+        """Add user to project team. Multi-step cross-API operation.
+
+        1. Get project ringId from YT API
+        2. Find matching Hub project team
+        3. Get user ringId from YT API
+        4. Add user to team via Hub API
+        """
+        self._debug.info("api", f"adding {user_login} to project {project_id} team")
+        # 1. Get project ringId
+        project = self._yt.get_project(project_id)
+        if not project.ring_id:
+            raise ValidationError(f"Project {project_id} has no ringId")
+
+        # 2. Find Hub team for this project
+        teams = self._hub.list_project_teams()
+        team = next(
+            (t for t in teams if t.project and t.project.id == project.ring_id),
+            None,
+        )
+        if not team:
+            raise NotFoundError(f"No project team found for project {project_id}")
+
+        # 3. Get user ringId via YT API search
+        users = self._yt.search_users(user_login)
+        user = next((u for u in users if u.login == user_login), None)
+        if not user or not user.ring_id:
+            raise NotFoundError(f"User '{user_login}' not found or has no ringId")
+
+        # 4. Add to team
+        self._hub.add_team_member(team.id, user.ring_id)
+
+
+class TimeOperations:
+    """High-level time tracking operations."""
+
+    def __init__(self, yt: YouTrackAPI, debug_log: DebugLog | None = None) -> None:
+        self._yt = yt
+        self._debug = debug_log or DebugLog()
+        self._work_item_types: builtins.list[WorkItemType] | None = None
+
+    def list(
+        self,
+        issue_id: str,
+        date_from: int | None = None,
+        date_to: int | None = None,
+    ) -> builtins.list[WorkItem]:
+        """List work items on an issue, optionally filtered by date range (epoch ms)."""
+        self._debug.info("sdk", f"listing work items for {issue_id}")
+        items = self._yt.list_work_items(issue_id)
+        if date_from is None and date_to is None:
+            return items
+        return [
+            w
+            for w in items
+            if w.date is not None
+            and (date_from is None or w.date >= date_from)
+            and (date_to is None or w.date <= date_to)
+        ]
+
+    def log(
+        self,
+        issue_id: str,
+        minutes: int,
+        work_type: str | None = None,
+        description: str | None = None,
+        date: int | None = None,
+    ) -> WorkItem:
+        """Log work. Resolves work_type name to ID transparently."""
+        self._debug.info("sdk", f"logging {minutes}m on {issue_id}")
+        type_entity = None
+        if work_type:
+            type_entity = IdEntity(id=self._resolve_work_type_id(work_type))
+        return self._yt.create_work_item(
+            issue_id,
+            WorkItemCreate(
+                duration=Duration(minutes=minutes),
+                text=description,
+                type=type_entity,
+                date=date,
+            ),
+        )
+
+    def get(self, issue_id: str, work_item_id: str) -> WorkItem:
+        """Fetch a single work item."""
+        self._debug.info("sdk", f"getting work item {work_item_id} on {issue_id}")
+        return self._yt.get_work_item(issue_id, work_item_id)
+
+    def update(
+        self,
+        issue_id: str,
+        work_item_id: str,
+        minutes: int | None = None,
+        work_type: str | None = None,
+        description: str | None = None,
+        date: int | None = None,
+    ) -> WorkItem:
+        """Update a work item. Only supplied fields are sent."""
+        self._debug.info("sdk", f"updating work item {work_item_id} on {issue_id}")
+        type_entity = None
+        if work_type is not None:
+            type_entity = IdEntity(id=self._resolve_work_type_id(work_type))
+        update = WorkItemUpdate(
+            duration=Duration(minutes=minutes) if minutes is not None else None,
+            text=description,
+            type=type_entity,
+            date=date,
+        )
+        return self._yt.update_work_item(issue_id, work_item_id, update)
+
+    def delete(self, issue_id: str, work_item_id: str) -> None:
+        """Delete a work item."""
+        self._debug.info("sdk", f"deleting work item {work_item_id} on {issue_id}")
+        self._yt.delete_work_item(issue_id, work_item_id)
+
+    def _resolve_work_type_id(self, name: str) -> str:
+        """Resolve work item type name to ID. Caches types on first call."""
+        if self._work_item_types is None:
+            self._work_item_types = self._yt.list_work_item_types()
+        for t in self._work_item_types:
+            if t.name.lower() == name.lower():
+                return t.id
+        available = ", ".join(t.name for t in self._work_item_types)
+        raise ValidationError(f"Unknown work item type '{name}'. Available: {available}")
+
+
+class ArticleOperations:
+    """High-level knowledge base article operations."""
+
+    def __init__(
+        self,
+        articles_api: ArticlesAPI,
+        yt: YouTrackAPI,
+        tag_ops: TagOperations | None = None,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._articles = articles_api
+        self._yt = yt
+        self._tag_ops = tag_ops
+        self._debug = debug_log or DebugLog()
+
+    def list(
+        self,
+        project: str | None = None,
+        top: int = 50,
+        skip: int = 0,
+    ) -> builtins.list[Article]:
+        """List articles. If *project* is given, scopes to that project."""
+        if project:
+            self._debug.info("api", f"listing articles for project {project}")
+            project_obj = self._yt.get_project(project)
+            return self._articles.list_project_articles(project_obj.id, top=top, skip=skip)
+        return self._articles.list_articles(top=top, skip=skip)
+
+    def get(self, article_id: str) -> Article:
+        return self._articles.get_article(article_id)
+
+    def pull(self, article_id: str) -> str | None:
+        """Fetch an article and return its content with a fresh marker.
+
+        The server does not store ``upstream-updated`` inside article
+        content (see YTCTL-6); pull injects it from ``article.updated``
+        so a pull -> edit -> push round-trip does not trip the conflict
+        check.  Marker-less content passes through verbatim.  Malformed
+        markers pass through verbatim so the user can see and fix them.
+        Returns ``None`` if the article has no content.
+        """
+        article = self._articles.get_article(article_id)
+        if article.content is None:
+            return None
+        try:
+            parsed = parse_content(article.content)
+        except MarkerError:
+            return article.content
+        if parsed.marker is None:
+            return article.content
+        if article.updated is not None:
+            parsed.marker.set(
+                "upstream-updated",
+                _epoch_sec_to_iso(article.updated // 1000),
+            )
+        else:
+            parsed.marker.data.pop("upstream-updated", None)
+        return render_content(parsed)
+
+    def children(self, article_id: str, top: int = 50, skip: int = 0) -> builtins.list[Article]:
+        return self._articles.list_child_articles(article_id, top=top, skip=skip)
+
+    def create(
+        self,
+        project: str,
+        summary: str,
+        content: str | None = None,
+        parent: str | None = None,
+        tags: builtins.list[str] | None = None,
+    ) -> Article:
+        """Create an article. *project* is the project shortName (key).
+
+        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.
+        """
+        self._debug.info("api", f"creating article in project {project}")
+        project_obj = self._yt.get_project(project)
+        parent_ref: IdEntity | None = None
+        if parent is not None:
+            parent_obj = self._articles.get_article(parent)
+            parent_ref = IdEntity(id=parent_obj.id)
+            self._debug.info("api", f"attaching to parent {parent} ({parent_obj.id})")
+        result = self._articles.create_article(
+            ArticleCreate(
+                project=IdEntity(id=project_obj.id),
+                summary=summary,
+                content=content,
+                parentArticle=parent_ref,
+            )
+        )
+        self._debug.info("api", f"created {result.id_readable}")
+        if tags:
+            applied, failed = self._apply_tags(result.id_readable, tags)
+            if failed:
+                raise KdError(
+                    f"Article {result.id_readable} created but tagging failed. "
+                    f"Applied: {applied or '(none)'}. "
+                    f"Failed: {', '.join(failed)}."
+                )
+        return result
+
+    def _apply_tags(
+        self,
+        article_id: str,
+        tags: builtins.list[str],
+    ) -> tuple[builtins.list[str], builtins.list[str]]:
+        """Apply tags to an article. Returns (applied, failed) lists.
+
+        Failed entries include the reason so the caller can distinguish
+        not-found from permission-denied (tag visible but not usable).
+        """
+        if self._tag_ops is None:
+            raise KdError("Tag operations not available")
+        applied: builtins.list[str] = []
+        failed: builtins.list[str] = []
+        for tag in tags:
+            try:
+                self._tag_ops.add(article_id, tag)
+                applied.append(tag)
+            except (NotFoundError, KdError) as exc:
+                failed.append(f"{tag} ({exc})")
+        return applied, failed
+
+    def update(
+        self,
+        article_id: str,
+        summary: str | None = None,
+        content: str | None = None,
+    ) -> Article:
+        if content is not None:
+            content = parse_content(content).body
+        return self._articles.update_article(
+            article_id,
+            ArticleUpdate(summary=summary, content=content),
+        )
+
+    def push(
+        self,
+        file_path: Path,
+        project: str,
+        summary: str,
+        slug: str | None = None,
+        parent: str | None = None,
+        force: bool = False,
+        dry_run: bool = False,
+        tags: builtins.list[str] | None = None,
+    ) -> PushResult:
+        """Idempotently upsert a local markdown file as a YouTrack article.
+
+        See ``docs/proposals/19-article-push-proposal.md`` for the
+        design rationale. The marker block inside the file (or
+        synthesized on first push) is the upsert key; ``slug`` is the
+        user-chosen identity.
+
+        On success, the local file is rewritten atomically to refresh
+        the marker's ``upstream-id`` and ``upstream-updated`` fields.
+        """
+        # Step 1: read the local file and parse the marker.
+        try:
+            text = file_path.read_text(encoding="utf-8")
+        except OSError as e:
+            raise KdError(f"Cannot read {file_path}: {e}") from e
+        parsed = parse_content(text)
+        marker = parsed.marker if parsed.marker is not None else ArticleMarker()
+
+        # Step 2: resolve slug (priority: marker → --slug → file path).
+        marker_slug = marker.get("slug")
+        if marker_slug and slug and marker_slug != slug:
+            raise ValidationError(
+                f"File {file_path} has slug {marker_slug!r} in its marker; "
+                f"--slug {slug!r} does not match. Refusing to change an existing "
+                "slug. Edit the marker directly."
+            )
+        resolved_slug = marker_slug or slug or _derive_slug_from_path(file_path)
+        if not resolved_slug:
+            raise ValidationError(
+                f"Cannot derive slug from {file_path}. Pass --slug or put "
+                "'slug: <value>' in a marker at the top of the file."
+            )
+        validate_slug(resolved_slug)
+        marker.set("slug", resolved_slug)
+
+        # Step 3: summary is required — no auto-derivation.
+        resolved_summary = summary
+
+        # Step 4: resolve target article.
+        existing_remote: Article | None = None
+        cached_upstream_id = marker.get("upstream-id")
+        if cached_upstream_id:
+            try:
+                existing_remote = self._articles.get_article(cached_upstream_id)
+            except NotFoundError:
+                self._debug.info(
+                    "api",
+                    f"cached upstream-id {cached_upstream_id} stale; scanning by slug",
+                )
+                existing_remote = None
+
+        if existing_remote is None:
+            # Scan by slug across the project's articles. List first
+            # (cheap), then fetch content per candidate until we find a
+            # match. Stops on first match so the common "no duplicate"
+            # case is O(N) fetches worst case; a cached upstream-id
+            # avoids this scan entirely.
+            project_obj = self._yt.get_project(project)
+            stubs = self._articles.list_project_articles(project_obj.id, top=500)
+            matches: builtins.list[Article] = []
+            for stub in stubs:
+                full = self._articles.get_article(stub.id_readable)
+                if full.content is None:
+                    continue
+                try:
+                    stub_parsed = parse_content(full.content)
+                except ValidationError:
+                    # A malformed marker on a remote article should not
+                    # poison an unrelated push — skip and continue.
+                    continue
+                if stub_parsed.marker and stub_parsed.marker.slug == resolved_slug:
+                    matches.append(full)
+            if len(matches) > 1:
+                ids = ", ".join(m.id_readable for m in matches)
+                raise ValidationError(
+                    f"Multiple articles in project {project} have slug "
+                    f"{resolved_slug!r}: {ids}. Delete duplicates, or fix the "
+                    "marker to include upstream-id."
+                )
+            if len(matches) == 1:
+                existing_remote = matches[0]
+
+        is_update = existing_remote is not None
+
+        # Step 5: conflict check on the update path.
+        if is_update and not force:
+            assert existing_remote is not None
+            marker_iso = marker.get("upstream-updated")
+            if (
+                marker_iso
+                and marker_iso != "1970-01-01T00:00:00Z"
+                and existing_remote.updated is not None
+            ):
+                try:
+                    marker_sec = _iso_to_epoch_sec(marker_iso)
+                except ValueError:
+                    marker_sec = 0
+                remote_sec = existing_remote.updated // 1000
+                if remote_sec > marker_sec:
+                    remote_iso = _epoch_sec_to_iso(remote_sec)
+                    raise ValidationError(
+                        f"Article {existing_remote.id_readable} was updated "
+                        f"upstream at {remote_iso} after our last push at "
+                        f"{marker_iso}. Pass --force to overwrite, or inspect "
+                        f"the remote: kd /article pull "
+                        f"{existing_remote.id_readable}."
+                    )
+
+        # Step 6: reject --parent on the update path.
+        if is_update and parent is not None:
+            assert existing_remote is not None
+            raise ValidationError(
+                f"--parent can only be used when creating a new article. To "
+                f"reparent {existing_remote.id_readable}, use: kd /article "
+                f"move {existing_remote.id_readable} --parent {parent}."
+            )
+
+        # Dry-run bails out here with all validation done but no writes.
+        if dry_run:
+            existing_sec = 0
+            if existing_remote is not None and existing_remote.updated is not None:
+                existing_sec = existing_remote.updated // 1000
+            return PushResult(
+                action="update" if is_update else "create",
+                article_id=existing_remote.id_readable if existing_remote else "",
+                slug=resolved_slug,
+                path=file_path,
+                remote_updated_sec=existing_sec,
+                dry_run=True,
+            )
+
+        # Step 7: build outgoing content. `upstream-updated` is intentionally
+        # omitted from the server payload — storing a snapshot of `updated`
+        # inside the content creates an unsolvable chicken-and-egg (YTCTL-6).
+        # `pull` injects it from `article.updated` on read.
+        if existing_remote is not None:
+            marker.set("upstream-id", existing_remote.id_readable)
+
+        outgoing_data: OrderedDict[str, str] = OrderedDict(
+            (k, v) for k, v in marker.data.items() if k != "upstream-updated"
+        )
+        outgoing_marker = ArticleMarker(data=outgoing_data)
+        outgoing = ParsedFile(
+            marker=outgoing_marker,
+            body=parsed.body,
+            newline=parsed.newline,
+            trailing_newline=parsed.trailing_newline,
+            body_separator=parsed.body_separator,
+        )
+        outgoing_content = render_content(outgoing)
+
+        # Step 8: write remote.
+        if is_update:
+            assert existing_remote is not None
+            self._debug.info("api", f"updating article {existing_remote.id_readable}")
+            result_article = self._articles.update_article(
+                existing_remote.id_readable,
+                ArticleUpdate(summary=resolved_summary, content=outgoing_content),
+            )
+        else:
+            self._debug.info("api", f"creating new article in project {project}")
+            result_article = self.create(
+                project=project,
+                summary=resolved_summary,
+                content=outgoing_content,
+                parent=parent,
+            )
+
+        # Step 8b: apply tags. Tagging bumps the server-side `updated`
+        # timestamp, so re-fetch the article afterward to capture the
+        # final timestamp for the marker (avoids false conflict on next push).
+        tags_applied: builtins.list[str] = []
+        tags_failed: builtins.list[str] = []
+        if tags:
+            tags_applied, tags_failed = self._apply_tags(result_article.id_readable, tags)
+            if tags_applied:
+                result_article = self._articles.get_article(result_article.id_readable)
+
+        # Step 9: compute final marker with the server-reported timestamp.
+        remote_updated_sec = (
+            result_article.updated // 1000 if result_article.updated is not None else 0
+        )
+        remote_iso = (
+            _epoch_sec_to_iso(remote_updated_sec) if remote_updated_sec else "1970-01-01T00:00:00Z"
+        )
+        marker.set("upstream-id", result_article.id_readable)
+        marker.set("upstream-updated", remote_iso)
+
+        final = ParsedFile(
+            marker=marker,
+            body=parsed.body,
+            newline=parsed.newline,
+            trailing_newline=parsed.trailing_newline,
+            body_separator=parsed.body_separator,
+        )
+        final_content = render_content(final)
+
+        # Step 10: atomic local write-back.
+        _atomic_write_text(file_path, final_content)
+
+        # Step 11: return result.
+        push_result = PushResult(
+            action="update" if is_update else "create",
+            article_id=result_article.id_readable,
+            slug=resolved_slug,
+            path=file_path,
+            remote_updated_sec=remote_updated_sec,
+            dry_run=False,
+            tags_applied=tags_applied,
+            tags_failed=tags_failed,
+        )
+        if tags_failed:
+            raise KdError(
+                f"Article {result_article.id_readable} {'updated' if is_update else 'created'} "
+                f"but tagging failed. "
+                f"Applied: {tags_applied or '(none)'}. "
+                f"Failed: {', '.join(tags_failed)}."
+            )
+        return push_result
+
+    def delete(self, article_id: str) -> None:
+        self._articles.delete_article(article_id)
+
+    # --- Comments ---
+
+    def list_comments(self, article_id: str) -> builtins.list[Comment]:
+        return self._articles.list_article_comments(article_id)
+
+    def add_comment(self, article_id: str, text: str) -> Comment:
+        return self._articles.create_article_comment(article_id, CommentCreate(text=text))
+
+    # --- Attachments ---
+
+    def list_attachments(self, article_id: str) -> builtins.list[Attachment]:
+        return self._articles.list_article_attachments(article_id)
+
+    def get_attachment(self, article_id: str, attachment_id: str) -> Attachment:
+        return self._articles.get_article_attachment(article_id, attachment_id)
+
+    def add_attachments(
+        self, article_id: str, file_paths: builtins.list[Path]
+    ) -> builtins.list[Attachment]:
+        """Upload one or more files as article attachments."""
+        self._debug.info("api", f"uploading {len(file_paths)} attachment(s) to {article_id}")
+        results: builtins.list[Attachment] = []
+        for fp in file_paths:
+            if not fp.is_file():
+                raise ValidationError(f"File not found: {fp}")
+            content = fp.read_bytes()
+            att = self._articles.create_article_attachment(article_id, fp.name, content)
+            self._debug.debug("api", f"  uploaded {fp.name} ({len(content)} bytes)")
+            results.append(att)
+        return results
+
+    def download_attachment(
+        self,
+        article_id: str,
+        attachment_id: str,
+        target_dir: Path | None = None,
+    ) -> Path:
+        """Download an article attachment to disk. Returns the written file path."""
+        meta = self._articles.get_article_attachment(article_id, attachment_id)
+        if not meta.url:
+            raise ValidationError(f"Attachment {attachment_id} has no download URL")
+        download_path = meta.url
+        if download_path.startswith("/api/"):
+            download_path = download_path[4:]  # strip /api prefix
+        content = self._articles._http.get_bytes(download_path)
+        dest_dir = target_dir or Path.cwd()
+        dest = dest_dir / meta.name
+        try:
+            dest.write_bytes(content)
+        except OSError as e:
+            raise KdError(f"Cannot write to {dest}: {e}") from e
+        return dest
+
+    def delete_attachment(self, article_id: str, attachment_id: str) -> None:
+        self._articles.delete_article_attachment(article_id, attachment_id)
+
+    # --- Hierarchy ---
+
+    def move(self, article_id: str, parent: str | None) -> Article:
+        """Move an article to a new parent, or to project root if parent is None."""
+        # The childArticles endpoint requires the database ID in the body
+        child = self._articles.get_article(article_id)
+        if parent is not None:
+            self._debug.info("api", f"moving {article_id} under {parent}")
+            self._articles.attach_child_article(parent, child.id)
+        else:
+            self._debug.info("api", f"moving {article_id} to root")
+            self._articles.detach_parent_article(article_id)
+        return self._articles.get_article(article_id)
+
+
+def _detect_entity_type(entity_id: str) -> str:
+    """Determine entity type from ID format.
+
+    Article IDs contain an ``-A-`` infix (e.g. ``FB-A-1``).
+    Issue IDs are ``PROJECT-NUMBER`` (e.g. ``FB-123``).
+    """
+    return "article" if "-A-" in entity_id else "issue"
+
+
+class TagOperations:
+    """High-level tag operations with name resolution and entity detection."""
+
+    def __init__(
+        self,
+        tags_api: TagsAPI,
+        articles_api: ArticlesAPI,
+        yt: YouTrackAPI,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._tags = tags_api
+        self._articles = articles_api
+        self._yt = yt
+        self._debug = debug_log or DebugLog()
+        self._name_cache: dict[str, str] = {}
+
+    def list(self, top: int = 50, skip: int = 0) -> builtins.list[Tag]:
+        return self._tags.list_tags(top=top, skip=skip)
+
+    def get(self, name: str) -> Tag:
+        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 rename(self, name: str, new_name: str) -> Tag:
+        tag_id = self._resolve_tag(name)
+        self._debug.info("api", f"renaming tag '{name}' → '{new_name}'")
+        tag = self._tags.update_tag(tag_id, new_name)
+        del self._name_cache[name.lower()]
+        self._name_cache[new_name.lower()] = tag.id
+        return tag
+
+    def delete(self, name: str) -> None:
+        tag_id = self._resolve_tag(name)
+        self._debug.info("api", f"deleting tag '{name}' ({tag_id})")
+        self._tags.delete_tag(tag_id)
+        self._name_cache.pop(name.lower(), None)
+
+    def add(self, entity_id: str, tag: str) -> None:
+        """Add a tag to an issue or article. Entity type is auto-detected."""
+        tag_id = self._resolve_tag(tag)
+        entity_type = _detect_entity_type(entity_id)
+        self._debug.info("api", f"tagging {entity_type} {entity_id} with '{tag}'")
+        if entity_type == "article":
+            self._tags.add_tag_to_article(entity_id, tag_id)
+        else:
+            self._tags.add_tag_to_issue(entity_id, tag_id)
+
+    def remove(self, entity_id: str, tag: str) -> None:
+        """Remove a tag from an issue or article. Entity type is auto-detected."""
+        tag_id = self._resolve_tag(tag)
+        entity_type = _detect_entity_type(entity_id)
+        self._debug.info("api", f"untagging {entity_type} {entity_id} from '{tag}'")
+        if entity_type == "article":
+            self._tags.remove_tag_from_article(entity_id, tag_id)
+        else:
+            self._tags.remove_tag_from_issue(entity_id, tag_id)
+
+    def issues(self, tag: str, top: int = 50, skip: int = 0) -> builtins.list[Issue]:
+        """List issues tagged with the given tag."""
+        tag_id = self._resolve_tag(tag)
+        return self._tags.list_tag_issues(tag_id, top=top, skip=skip)
+
+    def articles(
+        self,
+        tags: str | builtins.list[str],
+        project: str | None = None,
+        top: int = 50,
+    ) -> builtins.list[Article]:
+        """List articles tagged with the given tag(s).
+
+        The YouTrack API has no server-side article-by-tag endpoint,
+        so this scans article pages with the tags field and filters
+        client-side.  When multiple tags are given, only articles that
+        carry **all** of them (AND semantics) are returned.  Stops once
+        *top* matches are collected or the article source is exhausted.
+        """
+        tag_names = [tags] if isinstance(tags, str) else tags
+        tag_ids = frozenset(self._resolve_tag(name) for name in tag_names)
+        self._debug.info("api", f"scanning articles for tags {tag_names} ({tag_ids})")
+
+        project_id: str | None = None
+        if project:
+            project_id = self._yt.get_project(project).id
+
+        matched: builtins.list[Article] = []
+        page_size = max(top, 50)
+        skip = 0
+
+        while len(matched) < top:
+            if project_id:
+                page = self._articles.list_project_articles_with_tags(
+                    project_id,
+                    top=page_size,
+                    skip=skip,
+                )
+            else:
+                page = self._articles.list_articles_with_tags(
+                    top=page_size,
+                    skip=skip,
+                )
+            if not page:
+                break
+            for article in page:
+                if tag_ids.issubset({t.id for t in article.tags}):
+                    matched.append(article)
+                    if len(matched) >= top:
+                        break
+            skip += len(page)
+
+        return matched
+
+    def _resolve_tag(self, name: str) -> str:
+        """Resolve tag name to ID. Cached for client lifetime."""
+        key = name.lower()
+        if key in self._name_cache:
+            return self._name_cache[key]
+        self._debug.info("api", f"resolving tag '{name}'")
+        all_tags = self._tags.list_tags(top=500)
+        for t in all_tags:
+            self._name_cache[t.name.lower()] = t.id
+        if key in self._name_cache:
+            return self._name_cache[key]
+        available = [t.name for t in all_tags]
+        close = difflib.get_close_matches(name, available, n=3, cutoff=0.5)
+        hint = f" Did you mean: {', '.join(close)}?" if close else ""
+        raise NotFoundError(f"Tag '{name}' not found.{hint}")
+
+
+class SavedQueryOperations:
+    """High-level saved-query operations with name-or-ID resolution."""
+
+    def __init__(
+        self,
+        saved_queries_api: SavedQueriesAPI,
+        yt: YouTrackAPI,
+        tag_ops: TagOperations | None = None,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._api = saved_queries_api
+        self._yt = yt
+        self._tag_ops = tag_ops
+        self._debug = debug_log or DebugLog()
+        # Lowercase-name → ID. Populated lazily on first resolve.
+        self._name_cache: dict[str, str] = {}
+        # Cached full listing used by name resolution (avoids re-fetch).
+        self._last_listing: builtins.list[SavedQuery] | None = None
+
+    # --- Listing / reads ---
+
+    def list(
+        self,
+        owner: str | None = None,
+        top: int = 50,
+        skip: int = 0,
+    ) -> builtins.list[SavedQuery]:
+        """List saved queries. If ``owner`` is given, scopes to that user.
+
+        ``owner`` may be a user login or the literal string ``"me"`` (accepted
+        verbatim by the upstream ``/api/users/{userID}/savedQueries`` route).
+        """
+        if owner:
+            self._debug.info("api", f"listing saved queries owned by {owner}")
+            return self._api.list_user_saved_queries(owner, top=top, skip=skip)
+        self._debug.info("api", "listing saved queries")
+        return self._api.list_saved_queries(top=top, skip=skip)
+
+    def get(self, name_or_id: str) -> SavedQuery:
+        sq_id = self._resolve(name_or_id)
+        return self._api.get_saved_query(sq_id)
+
+    # --- Writes ---
+
+    def create(self, name: str, query: str) -> SavedQuery:
+        self._debug.info("api", f"creating saved query '{name}'")
+        sq = self._api.create_saved_query(SavedQueryCreate(name=name, query=query))
+        self._name_cache[name.lower()] = sq.id
+        self._last_listing = None  # invalidate
+        self._debug.info("api", f"created saved query '{name}' ({sq.id})")
+        return sq
+
+    def update(
+        self,
+        name_or_id: str,
+        name: str | None = None,
+        query: str | None = None,
+    ) -> SavedQuery:
+        """Update a saved query. Both fields optional at the SDK layer.
+
+        The CLI enforces "at least one" as a user-facing business rule; the SDK
+        stays permissive so programmatic callers can compose updates freely.
+        """
+        sq_id = self._resolve(name_or_id)
+        self._debug.info("api", f"updating saved query {sq_id}")
+        sq = self._api.update_saved_query(sq_id, SavedQueryUpdate(name=name, query=query))
+        if name is not None:
+            # Rename invalidates the old cache key.
+            self._name_cache.pop(name_or_id.lower(), None)
+            self._name_cache[name.lower()] = sq.id
+            self._last_listing = None
+        return sq
+
+    def delete(self, name_or_id: str) -> None:
+        sq_id = self._resolve(name_or_id)
+        self._debug.info("api", f"deleting saved query {sq_id}")
+        self._api.delete_saved_query(sq_id)
+        self._name_cache.pop(name_or_id.lower(), None)
+        self._last_listing = None
+
+    # --- Composition ---
+
+    def run_issues(
+        self,
+        name_or_id: str,
+        top: int = 50,
+        skip: int = 0,
+        project: str | None = None,
+    ) -> builtins.list[Issue]:
+        """Resolve a saved query and execute it via ``issues.list``."""
+        sq_id = self._resolve(name_or_id)
+        sq = self._api.get_saved_query(sq_id)
+        query = sq.query
+        if project:
+            query = f"project: {project} {query}"
+        self._debug.info("api", f"running saved query '{sq.name}' as issues → {query!r}")
+        return self._yt.list_issues(query=query, top=top, skip=skip)
+
+    def run_articles(
+        self,
+        name_or_id: str,
+        top: int = 50,
+        project: str | None = None,
+    ) -> builtins.list[Article]:
+        """Resolve a saved query, parse for tag/project fields, find matching articles.
+
+        Raises :class:`~kd.exceptions.ValidationError` if the query contains
+        issue-specific fields that cannot be translated to article lookups.
+        """
+        from dataclasses import replace
+
+        from kd.query_parser import parse_article_query
+
+        if self._tag_ops is None:
+            raise KdError("Tag operations not available")
+        sq_id = self._resolve(name_or_id)
+        sq = self._api.get_saved_query(sq_id)
+        self._debug.info("api", f"running saved query '{sq.name}' as articles → {sq.query!r}")
+        parsed = parse_article_query(sq.query)
+        if project:
+            parsed = replace(parsed, project=project)
+        if not parsed.tags and not parsed.project:
+            raise ValidationError(
+                "Query is empty — cannot search articles without at least a project or tag filter."
+            )
+        return self._tag_ops.articles(parsed.tags, project=parsed.project, top=top)
+
+    # --- Validation ---
+
+    def validate(self, query: str) -> QueryValidationResult:
+        """Validate query syntax by executing a dry-run search.
+
+        Sends the query to ``/api/issues?$top=1`` and checks whether
+        YouTrack accepts it. A 400 response indicates a syntax error;
+        all other API errors are re-raised.
+        """
+        self._debug.info("api", f"validating query: {query!r}")
+        try:
+            self._yt.list_issues(query=query, top=1)
+            return QueryValidationResult(valid=True, query=query)
+        except APIError as e:
+            if e.status_code == 400:
+                return QueryValidationResult(
+                    valid=False,
+                    query=query,
+                    error=str(e),
+                    suggestion=e.suggestion,
+                )
+            raise
+
+    # --- Resolution ---
+
+    def _resolve(self, name_or_id: str) -> str:
+        """Resolve a saved-query argument to its ID.
+
+        Strategy (matches TagOperations._resolve_tag with two extensions):
+
+        1. Direct-ID shortcut: ``NN-NN`` matches an ID we have already seen.
+        2. Lowercase-name cache hit.
+        3. Cache miss → fetch full listing, repopulate, retry. A duplicate-name
+           match raises ``ValidationError`` with the conflicting IDs.
+        4. Still no match → ``NotFoundError`` with difflib suggestions.
+        """
+        key = name_or_id.lower()
+        # Direct-ID shortcut — only trusts IDs we have already seen so that a
+        # typo like ``11-9`` which happens to look like an ID doesn't sneak
+        # through without validation.
+        if self._last_listing is not None:
+            for sq in self._last_listing:
+                if sq.id == name_or_id:
+                    return sq.id
+        if key in self._name_cache:
+            return self._name_cache[key]
+
+        self._debug.info("api", f"resolving saved query '{name_or_id}'")
+        listing = self._api.list_saved_queries(top=500)
+        self._last_listing = listing
+
+        # Check for a direct ID match against the fresh listing before any
+        # name matching — IDs are unambiguous.
+        for sq in listing:
+            if sq.id == name_or_id:
+                return sq.id
+
+        # Build name → [IDs] map to detect duplicates.
+        by_name: dict[str, builtins.list[str]] = {}
+        for sq in listing:
+            by_name.setdefault(sq.name.lower(), []).append(sq.id)
+        # Repopulate single-ID names into the cache; duplicates stay out so
+        # every future lookup re-runs the duplicate check.
+        for lname, ids in by_name.items():
+            if len(ids) == 1:
+                self._name_cache[lname] = ids[0]
+
+        matches = by_name.get(key, [])
+        if len(matches) == 1:
+            return matches[0]
+        if len(matches) > 1:
+            joined = ", ".join(matches)
+            raise ValidationError(
+                f"Multiple saved queries named '{name_or_id}' (IDs: {joined}). Use the ID instead."
+            )
+
+        available = [sq.name for sq in listing]
+        close = difflib.get_close_matches(name_or_id, available, n=3, cutoff=0.5)
+        hint = f" Did you mean: {', '.join(close)}?" if close else ""
+        raise NotFoundError(f"Saved query '{name_or_id}' not found.{hint}")
+
+
+class AssistOperations:
+    """Wrappers around ``/api/search/assist`` and ``/api/commands/assist``.
+
+    These two endpoints provide autocomplete suggestions for YouTrack search
+    queries and YT command-language strings respectively. They are free-form
+    helpers that operate on caller-supplied strings, so they live on their
+    own operation class rather than being attached to any domain entity.
+    """
+
+    def __init__(
+        self,
+        yt: YouTrackAPI,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._yt = yt
+        self._debug = debug_log or DebugLog()
+
+    def search(self, query: str, caret: int | None = None) -> AssistResponse:
+        """Autocomplete a YouTrack search query."""
+        self._debug.info("api", f"search assist query={query!r} caret={caret}")
+        return self._yt.search_assist(query, caret=caret)
+
+    def command(
+        self,
+        query: str,
+        caret: int | None = None,
+        issue_ids: builtins.list[str] | None = None,
+    ) -> AssistResponse:
+        """Autocomplete a YT command-language string.
+
+        ``issue_ids`` is the readable IDs of the issues the command would
+        target. An empty list (or ``None``) still produces useful field/value
+        suggestions.
+        """
+        self._debug.info(
+            "api",
+            f"command assist query={query!r} caret={caret} issues={issue_ids or []}",
+        )
+        return self._yt.commands_assist(query, caret=caret, issue_ids=issue_ids)
+
+
+class SearchOperations:
+    """Aggregated cross-entity search.
+
+    Fans out to per-type APIs and returns a unified list of
+    :class:`SearchResult` objects. Issues and users use server-side
+    query parameters; tags, projects, and articles use client-side
+    substring matching over list endpoints.
+    """
+
+    VALID_TYPES: frozenset[str] = frozenset({"issue", "user", "tag", "project", "article"})
+
+    def __init__(
+        self,
+        yt: YouTrackAPI,
+        articles_api: ArticlesAPI,
+        tags_api: TagsAPI,
+        debug_log: DebugLog | None = None,
+    ) -> None:
+        self._yt = yt
+        self._articles = articles_api
+        self._tags = tags_api
+        self._debug = debug_log or DebugLog()
+
+    def search(
+        self,
+        query: str,
+        types: builtins.list[str] | None = None,
+        project: str | None = None,
+        limit: int = 50,
+    ) -> builtins.list[SearchResult]:
+        """Search across entity types and return unified results.
+
+        Args:
+            query: Search term.
+            types: Entity types to search. Defaults to all five.
+            project: Scope issue queries and article scans to this project key.
+            limit: Maximum total results returned.
+        """
+        requested = builtins.list(types or self.VALID_TYPES)
+        invalid = set(requested) - self.VALID_TYPES
+        if invalid:
+            raise ValidationError(
+                f"Invalid search type(s): {', '.join(sorted(invalid))}. "
+                f"Valid types: {', '.join(sorted(self.VALID_TYPES))}"
+            )
+
+        self._debug.info("search", f"query={query!r} types={requested} project={project}")
+
+        buckets: dict[str, builtins.list[SearchResult]] = {}
+        for t in requested:
+            buckets[t] = getattr(self, f"_search_{t}s")(query, project)
+
+        return self._interleave(buckets, requested, limit)
+
+    # --- per-type search methods ---
+
+    def _search_issues(self, query: str, project: str | None) -> builtins.list[SearchResult]:
+        full_query = f"project: {project} {query}" if project else query
+        issues = self._yt.list_issues(query=full_query, top=50)
+        return [
+            SearchResult(
+                type="issue",
+                id=i.id_readable,
+                title=i.summary,
+                project=i.project.name or "" if i.project else "",
+            )
+            for i in issues
+        ]
+
+    def _search_users(
+        self,
+        query: str,
+        project: str | None,  # noqa: ARG002
+    ) -> builtins.list[SearchResult]:
+        users = self._yt.search_users(query)
+        return [SearchResult(type="user", id=u.login, title=u.name, project="") for u in users]
+
+    def _search_tags(
+        self,
+        query: str,
+        project: str | None,  # noqa: ARG002
+    ) -> builtins.list[SearchResult]:
+        tags = self._tags.list_tags(top=500)
+        q = query.lower()
+        return [
+            SearchResult(type="tag", id=t.name, title=t.name, project="")
+            for t in tags
+            if q in t.name.lower()
+        ]
+
+    def _search_projects(
+        self,
+        query: str,
+        project: str | None,  # noqa: ARG002
+    ) -> builtins.list[SearchResult]:
+        projects = self._yt.list_projects(top=200)
+        q = query.lower()
+        return [
+            SearchResult(
+                type="project",
+                id=p.short_name,
+                title=p.name,
+                project=p.short_name,
+            )
+            for p in projects
+            if q in p.name.lower() or q in p.short_name.lower()
+        ]
+
+    def _search_articles(self, query: str, project: str | None) -> builtins.list[SearchResult]:
+        if project:
+            articles = self._articles.list_project_articles(project, top=200)
+        else:
+            articles = self._articles.list_articles(top=200)
+        q = query.lower()
+        return [
+            SearchResult(
+                type="article",
+                id=a.id_readable,
+                title=a.summary,
+                project=a.project.name or "" if a.project else "",
+            )
+            for a in articles
+            if q in a.summary.lower()
+        ]
+
+    # --- result merging ---
+
+    @staticmethod
+    def _interleave(
+        buckets: dict[str, builtins.list[SearchResult]],
+        order: builtins.list[str],
+        limit: int,
+    ) -> builtins.list[SearchResult]:
+        """Round-robin interleave results from each type bucket."""
+        merged: builtins.list[SearchResult] = []
+        indices = {t: 0 for t in order}
+        while len(merged) < limit:
+            added = False
+            for t in order:
+                items = buckets.get(t, [])
+                idx = indices[t]
+                if idx < len(items):
+                    merged.append(items[idx])
+                    indices[t] = idx + 1
+                    added = True
+                    if len(merged) >= limit:
+                        break
+            if not added:
+                break
+        return merged