@ngocsangairvds/vsaf 4.1.8 → 4.1.9

package/skills/vds-skill/vds-scripts/confluence_orchestrator/src/confluence_orchestrator/cli.py

@@ -1,3160 +0,0 @@
-"""Typer CLI wrapper for Confluence operations during the native Python implementations."""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-import sys
-from dataclasses import asdict, dataclass
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any, cast
-from urllib.parse import urlparse
-
-import structlog
-import typer
-from vds_platform_core.logging import configure_structlog
-
-from .config import ConfluenceSettings, load_settings
-from .content import ContentClient
-from .content_v2 import ContentClientV2
-from .crawl_tree import CrawlOptions, crawl_tree_to_disk
-from .errors import VDSClientError
-from .eventing import Poller
-from .http import ConfluenceClient
-from .orchestration import BatchRunner, WebhookClient
-from .reporting import RunSummary, write_reports
-from .tree_copier import CopyOptions, TreeCopier
-
-# ---------------------------------------------------------------------------
-# Typer setup & logging
-# ---------------------------------------------------------------------------
-
-app = typer.Typer(add_completion=False, help="Confluence operations orchestrator")
-content_app = typer.Typer(help="Native Confluence API commands")
-batch_app = typer.Typer(help="Batch polling utilities (REST v1)")
-webhook_app = typer.Typer(help="Webhook management (REST v1)")
-app.add_typer(content_app, name="content")
-app.add_typer(batch_app, name="batch-native")
-app.add_typer(webhook_app, name="webhook-native")
-
-# Logger will be configured in main() callback
-logger = logging.getLogger("confluence_cli")
-
-# ---------------------------------------------------------------------------
-# Paths and legacy script mapping
-# ---------------------------------------------------------------------------
-
-_SCRIPTS_DIR = Path(__file__).resolve().parents[3]
-_DEFAULT_REPORT_DIR = (_SCRIPTS_DIR / "reports" / "confluence_runs").resolve()
-
-
-@dataclass(slots=True)
-class CLIContext:
-    report_dir: Path
-    markdown: bool
-    api_version: str
-    reports: bool
-
-
-# ---------------------------------------------------------------------------
-# Helper functions
-# ---------------------------------------------------------------------------
-
-
-def _normalise_server(server: str | None, settings: ConfluenceSettings) -> str:
-    return server.lower() if server else settings.default_server.lower()
-
-
-def _infer_server_from_root_ref(root_ref: str, settings: ConfluenceSettings) -> str | None:
-    root_ref = (root_ref or "").strip()
-    if not root_ref:
-        return None
-
-    parsed = urlparse(root_ref)
-    if not parsed.scheme or not parsed.netloc:
-        return None
-
-    target = parsed.netloc.lower()
-    internal = urlparse(str(settings.internal_url)).netloc.lower()
-    external = urlparse(str(settings.external_url)).netloc.lower()
-
-    if target == internal:
-        return "internal"
-    if target == external:
-        return "external"
-    return None
-
-
-def _build_env(server: str, settings: ConfluenceSettings) -> dict:
-    token = settings.token_for(server)
-    if not token and not (settings.username and settings.password):
-        raise VDSClientError(
-            f"Credentials for server '{server}' are missing. Provide VDS_USERNAME+VDS_PASSWORD as the primary auth mechanism or tokens "
-            "(INTERNAL_CONFLUENCE_TOKEN/EXTERNAL_CONFLUENCE_TOKEN) as fallback.",
-            context={"server": server},
-        )
-    env = os.environ.copy()
-    env.update(
-        {
-            "CONFLUENCE_SERVER": server,
-            "CONFLUENCE_TOKEN": token or "",
-            "CONFLUENCE_URL": str(settings.url_for(server)),
-            "INTERNAL_CONFLUENCE_TOKEN": settings.internal_token or "",
-            "EXTERNAL_CONFLUENCE_TOKEN": settings.external_token or "",
-        }
-    )
-    return env
-
-
-def _build_http_client(settings: ConfluenceSettings, server: str) -> ConfluenceClient:
-    return ConfluenceClient(settings, server=server)
-
-
-def _get_cli_ctx(ctx: typer.Context) -> CLIContext:
-    cli_ctx = ctx.obj
-    if not isinstance(cli_ctx, CLIContext):
-        raise RuntimeError("CLI context not initialised")
-    return cli_ctx
-
-
-def _ensure_v1_api(_ctx: typer.Context, _command: str) -> None:
-    """Legacy command guard - redirects to native implementations."""
-    settings = load_settings(strict=False)
-    if settings is None:
-        typer.echo("Error: configuration not found", err=True)
-        raise typer.Exit(code=1) from None
-
-
-def _build_content_client(
-    settings: ConfluenceSettings,
-    server: str,
-    api_version: str,
-):
-    http_client = _build_http_client(settings, server)
-    if not http_client.supports_api_version(api_version):
-        raise VDSClientError(
-            f"API version '{api_version}' is not supported for server '{server}'.",
-            context={"server": server, "api_version": api_version},
-        )
-    if api_version == "v1":
-        return ContentClient(http_client)
-    if api_version == "v2":
-        return ContentClientV2(http_client)
-    raise VDSClientError(f"Unsupported API version '{api_version}'")
-
-
-def _record_summary(
-    ctx: typer.Context,
-    *,
-    command: str,
-    args: list[str],
-    server: str,
-    exit_code: int,
-    started_at: datetime,
-    finished_at: datetime,
-) -> None:
-    cli_ctx = _get_cli_ctx(ctx)
-    summary = RunSummary(
-        command=command,
-        args=args,
-        server=server,
-        exit_code=exit_code,
-        duration_ms=int((finished_at - started_at).total_seconds() * 1000),
-        started_at=started_at,
-        finished_at=finished_at,
-    )
-    if cli_ctx.reports:
-        write_reports(summary, base_dir=cli_ctx.report_dir, include_markdown=cli_ctx.markdown)
-
-
-def _emit_json(payload: object) -> None:
-    text = json.dumps(payload, indent=2, sort_keys=True)
-    if sys.stdout.isatty():
-        typer.echo(text)
-    else:
-        sys.stdout.write(text + "\n")
-
-
-def _expand_option(value: str | None) -> list[str] | None:
-    if not value:
-        return None
-    return [part.strip() for part in value.split(",") if part.strip()]
-
-
-def _content_summary_args(
-    *, cql: str | None = None, limit: int | None = None, start: int | None = None, space: str | None = None
-) -> list[str]:
-    parts: list[str] = []
-    if cql is not None:
-        parts.append(cql)
-    if limit is not None:
-        parts.append(f"limit={limit}")
-    if start is not None:
-        parts.append(f"start={start}")
-    if space is not None:
-        parts.append(f"space={space}")
-    return parts
-
-
-def _read_text_file(path: Path) -> str:
-    if not path.exists():
-        raise typer.BadParameter(f"File not found: {path}")
-    if path.is_dir():
-        raise typer.BadParameter(f"Expected file but found directory: {path}")
-    try:
-        return path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise typer.BadParameter(f"Unable to read file {path}: {exc}") from exc
-
-
-def _parse_json_option(value: str | None, option_name: str) -> dict[str, Any] | None:
-    if value is None:
-        return None
-    try:
-        parsed = json.loads(value)
-    except json.JSONDecodeError as exc:
-        raise typer.BadParameter(f"Invalid JSON for {option_name}: {exc}") from exc
-    if not isinstance(parsed, dict):
-        raise typer.BadParameter(f"{option_name} must decode to a JSON object")
-    return parsed
-
-
-def _parent_context(ctx: typer.Context) -> typer.Context:
-    return cast("typer.Context", ctx.parent or ctx)
-
-
-# ---------------------------------------------------------------------------
-# Typer callbacks & native commands
-# ---------------------------------------------------------------------------
-
-
-@app.callback()
-def main(
-    ctx: typer.Context,
-    report_dir: Path | None = typer.Option(
-        None, help="Directory for run reports (default: <vds-scripts>/reports/confluence_runs)"
-    ),
-    markdown: bool = typer.Option(True, help="Emit Markdown summaries alongside JSON reports"),
-    reports: bool = typer.Option(True, "--reports/--no-reports", help="Persist run reports to disk"),
-    json_only: bool = typer.Option(
-        False,
-        "--json-only",
-        help="Emit JSON to stdout only (disables reports and markdown)",
-    ),
-    api_version: str = typer.Option("v1", "--api-version", "-A", help="Select REST API version (v1 or v2)"),
-    structured_logs: bool = typer.Option(
-        False, "--structured-logs/--no-structured-logs", help="Emit structured JSON logs to stderr"
-    ),
-) -> None:
-    resolved = report_dir.resolve() if report_dir else _DEFAULT_REPORT_DIR
-    version = api_version.lower()
-    if version not in {"v1", "v2"}:
-        raise typer.BadParameter("api-version must be one of: v1, v2")
-    if json_only:
-        markdown = False
-        reports = False
-
-    # Configure logging/structlog
-    if structured_logs or json_only:
-        configure_structlog(
-            json_logs=structured_logs, quiet=json_only and not structured_logs, cache_logger=structured_logs
-        )
-    if structured_logs:
-        global logger
-        logger = structlog.get_logger("confluence_cli")  # type: ignore[assignment]
-
-    ctx.obj = CLIContext(report_dir=resolved, markdown=markdown, api_version=version, reports=reports)
-
-
-@app.command("templates")
-def cmd_templates(
-    ctx: typer.Context,
-    args: list[str] | None = typer.Argument(
-        None, help="Additional arguments for template operations", show_default=False, metavar="ARGS"
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    limit: int = typer.Option(20, "--limit", "-l", help="Number of templates to list"),
-    space_key: str | None = typer.Option(None, "--space", "-k", help="Space key filter"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Native Python template management"""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
-
-        # Use native Python implementation
-        if hasattr(client, "list_templates"):
-            result = client.list_templates(space_key=space_key)
-        else:
-            result = {"templates": [], "message": "Templates API not available for this server"}
-
-        if json_output:
-            _emit_json(result)
-        else:
-            templates_payload = []
-            if isinstance(result, dict):
-                templates_payload = (
-                    result.get("blueprints")
-                    or result.get("templates")
-                    or result.get("results")
-                    or result.get("contentTemplates")
-                    or []
-                )
-            elif isinstance(result, list):
-                templates_payload = result
-
-            count = len(templates_payload)
-            typer.echo(f"Found {count} templates:")
-            for template in templates_payload[:limit]:
-                if isinstance(template, dict):
-                    name = template.get("name", "Unknown")
-                    template_id = template.get("templateId") or template.get("id") or template.get("uuid") or "Unknown"
-                else:
-                    name = str(template)
-                    template_id = "Unknown"
-                typer.echo(f"  - {name} (ID: {template_id})")
-
-        exit_code = 0
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="templates",
-            args=args or [],
-            server=server_key,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-    except Exception as exc:
-        logger.exception("templates_command_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-
-
-@app.command("batch")
-def cmd_batch(
-    _ctx: typer.Context,
-    _args: list[str] | None = typer.Argument(
-        None, help="Use 'confluence content batch --help' for available subcommands", show_default=False, metavar="ARGS"
-    ),
-    _server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Legacy batch command - use 'confluence content batch' subcommands instead."""
-    typer.echo("Error: The 'batch' command is deprecated. Use 'confluence content batch' subcommands:", err=True)
-    typer.echo("  confluence content batch scan --cql '<query>' [options]", err=True)
-    typer.echo("  confluence content batch snapshot --cql '<query>' [options]", err=True)
-    raise typer.Exit(code=1) from None
-
-
-@app.command("webhooks")
-def cmd_webhooks(
-    ctx: typer.Context,
-    args: list[str] | None = typer.Argument(
-        None, help="Additional arguments for webhook operations", show_default=False, metavar="ARGS"
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    list_webhooks: bool = typer.Option(False, "--list", "-l", help="List existing webhooks"),
-    create_name: str | None = typer.Option(None, "--name", "-n", help="Webhook name"),
-    create_url: str | None = typer.Option(None, "--url", "-u", help="Webhook URL"),
-    create_event: str | None = typer.Option(None, "--event", "-e", help="Event type"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Native Python webhook management"""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-
-    server_key = "internal"
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        webhook_client = WebhookClient(_build_http_client(settings, server_key))
-
-        if list_webhooks or (not create_name and not create_url and not create_event):
-            # List webhooks
-            result = webhook_client.list()
-            if json_output or not sys.stdout.isatty():
-                _emit_json(result)
-            else:
-                result_payload = result if isinstance(result, dict) else {"webhooks": result}
-                webhooks_raw = result_payload.get("webhooks", [])
-                webhooks = (
-                    [item for item in webhooks_raw if isinstance(item, dict)] if isinstance(webhooks_raw, list) else []
-                )
-                count = len(webhooks)
-                typer.echo(f"Found {count} webhooks:")
-                for webhook in webhooks:
-                    name = webhook.get("name", "Unknown")
-                    url = webhook.get("url", "Unknown")
-                    events = webhook.get("events", [])
-                    typer.echo(f"  - {name}: {url} (events: {', '.join(events)})")
-
-        elif create_name and create_url and create_event:
-            # Create webhook
-            result = webhook_client.create(name=create_name, url=create_url, events=[create_event])
-            if json_output or not sys.stdout.isatty():
-                _emit_json(result)
-            else:
-                webhook_id = result.get("id", "Unknown")
-                typer.echo(f"Created webhook '{create_name}' with ID: {webhook_id}")
-
-        else:
-            typer.echo(
-                "Error: Either use --list to list webhooks or provide --name, --url, and --event to create", err=True
-            )
-            raise typer.Exit(code=1) from None
-
-        exit_code = 0
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="webhooks",
-            args=args or [],
-            server=server_key,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-    except Exception as exc:
-        logger.exception("webhooks_command_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-
-
-@app.command("search")
-def cmd_search(
-    ctx: typer.Context,
-    args: list[str] | None = typer.Argument(
-        None, help="Additional arguments for CQL search", show_default=False, metavar="ARGS"
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    cql: str = typer.Option(..., "--cql", "-q", help="CQL query string"),
-    limit: int = typer.Option(25, "--limit", "-l", help="Number of results"),
-    start: int = typer.Option(0, "--start", help="Pagination start"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    excerpt: str | None = typer.Option(None, "--excerpt", help="Excerpt strategy (e.g., 'highlighted', 'indexed')"),
-    advanced: bool = typer.Option(False, "--advanced", help="Use advanced CQL search with additional options"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Native Python CQL search. Use --advanced for additional options like excerpt."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    server_key = "internal"
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
-
-        # Use native Python implementation
-        expand_list = _expand_option(expand) if expand else None
-        if advanced or excerpt:
-            result = client.cql_advanced(cql, limit=limit, start=start, expand=expand_list, excerpt=excerpt)
-        else:
-            result = client.search_cql(cql, limit=limit, start=start, expand=expand_list)
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result)
-        else:
-            results = result.get("results", [])
-            count = len(results)
-            total = result.get("size", 0)
-            typer.echo(f"Found {count} of {total} results for CQL: {cql}")
-            for item in results:
-                title = item.get("title", "Unknown")
-                page_id = item.get("id", "Unknown")
-                space = item.get("space", {}).get("key", "Unknown")
-                typer.echo(f"  - {title} (ID: {page_id}, Space: {space})")
-
-        exit_code = 0
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="search",
-            args=args or [],
-            server=server_key,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-    except Exception as exc:
-        logger.exception("search_command_failed: %s", exc)
-
-
-@content_app.command("child-pages")
-def cmd_child_pages(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Parent page ID"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Get child pages using the direct API endpoint (faster than CQL)."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    server_key = "internal"
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
-        expand_list = _expand_option(expand)
-
-        results = client.get_child_pages(page_id, expand=expand_list)
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(results)
-        else:
-            count = len(results)
-            typer.echo(f"Found {count} child pages for {page_id}:")
-            for item in results:
-                title = item.get("title", "Unknown")
-                child_id = item.get("id", "Unknown")
-                typer.echo(f"  - {title} (ID: {child_id})")
-
-    except Exception as exc:
-        exit_code = 1
-        logger.exception("child_pages_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="child-pages",
-            args=[page_id],
-            server=server_key if "server_key" in locals() else "internal",
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("search-by-space-type")
-def cmd_search_by_space_type(
-    ctx: typer.Context,
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    space_key: str | None = typer.Option(None, "--space", help="Space key to filter by"),
-    content_type: str | None = typer.Option(None, "--type", help="Content type (e.g., 'page', 'blogpost', 'comment')"),
-    limit: int = typer.Option(25, "--limit", "-l", help="Number of results"),
-    start: int = typer.Option(0, "--start", help="Pagination start"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Search by space and/or content type (helper that builds CQL automatically)."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    server_key = "internal"
-
-    try:
-        if not space_key and not content_type:
-            raise typer.BadParameter("At least one of --space or --type must be provided")
-
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
-
-        expand_list = _expand_option(expand) if expand else None
-        result = client.search_by_space_and_type(
-            space_key=space_key,
-            content_type=content_type,
-            limit=limit,
-            start=start,
-            expand=expand_list,
-        )
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result)
-        else:
-            results = result.get("results", [])
-            count = len(results)
-            total = result.get("size", 0)
-            typer.echo(f"Found {count} of {total} results")
-            for item in results:
-                title = item.get("title", "Unknown")
-                page_id = item.get("id", "Unknown")
-                space = item.get("space", {}).get("key", "Unknown")
-                item_type = item.get("type", "Unknown")
-                typer.echo(f"  - {title} (ID: {page_id}, Space: {space}, Type: {item_type})")
-
-        exit_code = 0
-    except (typer.BadParameter, Exception) as exc:
-        exit_code = 1
-        logger.exception("search_by_space_type_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        args_list: list[str] = []
-        if space_key:
-            args_list.append(f"space={space_key}")
-        if content_type:
-            args_list.append(f"type={content_type}")
-        _record_summary(
-            parent_ctx,
-            command="search-by-space-type",
-            args=args_list,
-            server=server_key,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("attachments")
-def cmd_attachments(
-    ctx: typer.Context,
-    args: list[str] | None = typer.Argument(
-        None, help="Additional arguments for attachment operations", show_default=False, metavar="ARGS"
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    page_id: str | None = typer.Option(None, "--page", "-p", help="Page ID for attachments"),
-    list_attachments: bool = typer.Option(False, "--list", "-l", help="List attachments for page"),
-    upload_file: str | None = typer.Option(None, "--upload", "-f", help="File to upload"),
-    comment: str | None = typer.Option(None, "--comment", "-c", help="Upload comment"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Native Python attachment management"""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_content_client(settings, server_key, parent_ctx.obj.api_version)
-
-        if list_attachments or (page_id and not upload_file):
-            # List attachments
-            if not page_id:
-                typer.echo("Error: --page ID required for listing attachments", err=True)
-                raise typer.Exit(code=1) from None
-
-            result = client.list_attachments(page_id)
-            if json_output or not sys.stdout.isatty():
-                _emit_json(result)
-            else:
-                attachments = result.get("results", [])
-                count = len(attachments)
-                typer.echo(f"Found {count} attachments for page {page_id}:")
-                for attachment in attachments:
-                    name = attachment.get("title", "Unknown")
-                    size = attachment.get("size", 0)
-                    typer.echo(f"  - {name} ({size} bytes)")
-
-        elif upload_file and page_id:
-            # Upload attachment
-            file_path = Path(upload_file)
-            if not file_path.exists():
-                typer.echo(f"Error: File not found: {upload_file}", err=True)
-                raise typer.Exit(code=1) from None
-
-            result = client.upload_attachment(page_id, file_path, comment=comment)
-            if json_output or not sys.stdout.isatty():
-                _emit_json(result)
-            else:
-                attachment_id = result.get("id", "Unknown")
-                typer.echo(f"Uploaded attachment '{file_path.name}' with ID: {attachment_id}")
-
-        else:
-            typer.echo("Error: Either use --list with --page or provide --page and --upload", err=True)
-            raise typer.Exit(code=1) from None
-
-        exit_code = 0
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="attachments",
-            args=args or [],
-            server=server_key,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-    except Exception as exc:
-        logger.exception("attachments_command_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-
-
-@app.command("space-permissions")
-def cmd_space_permissions(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: get, set, remove"),
-    space_key: str = typer.Option(..., "--space-key", "-k", help="Confluence space key"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    user_key: str | None = typer.Option(None, "--user", "-u", help="User key for user-targeted operations"),
-    group_name: str | None = typer.Option(None, "--group", "-g", help="Group name for group-targeted operations"),
-    anonymous: bool = typer.Option(False, "--anonymous", help="Target anonymous permissions"),
-    operations: list[str] = typer.Option(
-        [],
-        "--operation",
-        "-o",
-        help="Space permission operation key (repeatable, e.g., administer, read)",
-    ),
-    permissions_file: Path | None = typer.Option(
-        None,
-        "--permissions-file",
-        help="JSON object/array with bulk permission definitions (target.type: user|group|anonymous, operations: [...])",
-    ),
-    yes: bool = typer.Option(False, "--yes", help="Confirm write operations"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence space permissions."""
-
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        resolved_operations = operations or None
-        args_summary = [
-            action,
-            f"space={space_key}",
-            f"user={user_key}",
-            f"group={group_name}",
-            f"anonymous={anonymous}",
-            f"operations={operations}",
-            f"permissions_file={permissions_file}",
-        ]
-
-        if action == "get":
-            result = client.get_space_permissions(space_key)
-            result_payload = {"space": space_key, "permissions": result}
-
-        elif action == "set":
-            if not yes:
-                raise typer.BadParameter("--yes required for write operations")
-
-            targets = [bool(user_key), bool(group_name), anonymous, bool(permissions_file)]
-            if sum(1 for flag in targets if flag) != 1:
-                raise typer.BadParameter(
-                    "Provide exactly one of --user, --group, --anonymous, or --permissions-file for set action"
-                )
-
-            if permissions_file:
-                file_content = _read_text_file(permissions_file)
-                try:
-                    parsed = json.loads(file_content)
-                except json.JSONDecodeError as exc:
-                    raise typer.BadParameter(f"Invalid JSON in permissions file: {exc}") from exc
-
-                if isinstance(parsed, dict):
-                    items: list[dict[str, Any]] = [parsed]
-                elif isinstance(parsed, list):
-                    if not all(isinstance(item, dict) for item in parsed):
-                        raise typer.BadParameter("--permissions-file list entries must be JSON objects")
-                    items = parsed  # type: ignore[assignment]
-                else:
-                    raise typer.BadParameter("--permissions-file must contain a JSON object or array")
-
-                result = client.set_permissions_to_multiple_items_for_space(space_key, items)
-                result_payload = {"space": space_key, "bulk": True, "items_processed": len(items), "result": result}
-
-            elif user_key:
-                if not resolved_operations:
-                    raise typer.BadParameter("At least one --operation required when setting user permissions")
-                result = client.set_permissions_to_user_for_space(
-                    space_key,
-                    user_key,
-                    operations=resolved_operations,
-                )
-                result_payload = {
-                    "space": space_key,
-                    "target": {"type": "user", "key": user_key},
-                    "operations": resolved_operations,
-                    "result": result,
-                }
-
-            elif group_name:
-                if not resolved_operations:
-                    raise typer.BadParameter("At least one --operation required when setting group permissions")
-                result = client.set_permissions_to_group_for_space(
-                    space_key,
-                    group_name,
-                    operations=resolved_operations,
-                )
-                result_payload = {
-                    "space": space_key,
-                    "target": {"type": "group", "name": group_name},
-                    "operations": resolved_operations,
-                    "result": result,
-                }
-
-            elif anonymous:
-                if not resolved_operations:
-                    raise typer.BadParameter("At least one --operation required when setting anonymous permissions")
-                result = client.set_permissions_to_anonymous_for_space(
-                    space_key,
-                    operations=resolved_operations,
-                )
-                result_payload = {
-                    "space": space_key,
-                    "target": {"type": "anonymous"},
-                    "operations": resolved_operations,
-                    "result": result,
-                }
-
-        elif action == "remove":
-            if not yes:
-                raise typer.BadParameter("--yes required for write operations")
-
-            targets = [bool(user_key), bool(group_name), anonymous]
-            if sum(1 for flag in targets if flag) != 1:
-                raise typer.BadParameter("Provide exactly one of --user, --group, or --anonymous for remove action")
-
-            if user_key:
-                result = client.remove_permissions_from_user_for_space(space_key, user_key)
-                result_payload = {
-                    "space": space_key,
-                    "target": {"type": "user", "key": user_key},
-                    "result": result,
-                }
-
-            elif group_name:
-                result = client.remove_permissions_from_group_for_space(space_key, group_name)
-                result_payload = {
-                    "space": space_key,
-                    "target": {"type": "group", "name": group_name},
-                    "result": result,
-                }
-
-            elif anonymous:
-                result = client.remove_permissions_from_anonymous_for_space(space_key)
-                result_payload = {
-                    "space": space_key,
-                    "target": {"type": "anonymous"},
-                    "result": result,
-                }
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("space_permissions_command_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("space_permissions_command_unexpected")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="space-permissions",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("space-management")
-def cmd_space_management(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: archive, trash-list, trash-remove"),
-    space_key: str = typer.Option(..., "--space-key", "-k", help="Confluence space key"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    cursor: str | None = typer.Option(None, "--cursor", help="Pagination cursor for trash-list"),
-    limit: int = typer.Option(50, "--limit", help="Limit for trash-list (max 100)"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions for trash-list"),
-    yes: bool = typer.Option(False, "--yes", help="Confirm write operations"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence space lifecycle operations."""
-
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        if limit < 1 or limit > 100:
-            raise typer.BadParameter("--limit must be between 1 and 100")
-
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        expand_value = expand if expand else None
-        args_summary = [
-            action,
-            f"space={space_key}",
-            f"cursor={cursor}",
-            f"limit={limit}",
-            f"expand={expand_value}",
-        ]
-
-        if action == "archive":
-            if not yes:
-                raise typer.BadParameter("--yes required for archive")
-            result = client.archive_space(space_key)
-            result_payload = {"space": space_key, "action": "archive", "result": result}
-
-        elif action == "trash-list":
-            result = client.get_trashed_contents_by_space(
-                space_key,
-                cursor=cursor,
-                expand=expand_value,
-                limit=limit,
-            )
-            result_payload = {
-                "space": space_key,
-                "action": "trash-list",
-                "result": result,
-            }
-
-        elif action == "trash-remove":
-            if not yes:
-                raise typer.BadParameter("--yes required for trash-remove")
-            result = client.remove_trashed_contents_by_space(space_key)
-            result_payload = {"space": space_key, "action": "trash-remove", "result": result}
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("space_management_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("space_management_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="space-management",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("group")
-def cmd_group(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: list, members"),
-    group_name: str | None = typer.Option(None, "--group", "-g", help="Group name (for members)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    start: int = typer.Option(0, "--start", help="Start index for pagination"),
-    limit: int = typer.Option(1000, "--limit", help="Limit for pagination (max 1000)"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence groups."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        if limit < 1 or limit > 1000:
-            raise typer.BadParameter("--limit must be between 1 and 1000")
-
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        args_summary = [action, f"start={start}", f"limit={limit}"]
-
-        if action == "list":
-            result = client.get_all_groups(start=start, limit=limit)
-            result_payload = {"count": len(result), "groups": result}
-
-        elif action == "members":
-            if not group_name:
-                raise typer.BadParameter("--group required for members action")
-            args_summary.append(f"group={group_name}")
-            result = client.get_group_members(group_name, start=start, limit=limit)
-            result_payload = {"group": group_name, "count": len(result), "members": result}
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("group_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("group_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="group",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("user")
-def cmd_user(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: get, password, group-add, group-remove"),
-    username: str | None = typer.Option(None, "--username", "-u", help="Username"),
-    userkey: str | None = typer.Option(None, "--userkey", help="User key"),
-    group_name: str | None = typer.Option(None, "--group", "-g", help="Group name (for group-add/group-remove)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma-separated fields to expand (for get)"),
-    new_password: str | None = typer.Option(None, "--new-password", help="New password (for password)"),
-    yes: bool = typer.Option(False, "--yes", help="Confirm write operations"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence users."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        args_summary = [action]
-
-        if action == "get":
-            if not username and not userkey:
-                raise typer.BadParameter("Provide --username or --userkey for get action")
-            if username and userkey:
-                raise typer.BadParameter("Provide either --username or --userkey, not both")
-            expand_value = expand if expand else None
-            args_summary.append(f"username={username}" if username else f"userkey={userkey}")
-            if expand_value:
-                args_summary.append(f"expand={expand_value}")
-
-            if username:
-                result = client.get_user_details_by_username(username, expand=expand_value)
-            else:
-                assert userkey is not None
-                result = client.get_user_details_by_userkey(userkey, expand=expand_value)
-            result_payload = {"user": result}
-
-        elif action == "password":
-            if not yes:
-                raise typer.BadParameter("--yes required for password change")
-            if not username:
-                raise typer.BadParameter("--username required for password action")
-            if not new_password:
-                raise typer.BadParameter("--new-password required for password action")
-            args_summary.append(f"username={username}")
-            client.change_user_password(username, new_password)
-            result_payload = {"username": username, "status": "password_changed"}
-
-        elif action == "group-add":
-            if not yes:
-                raise typer.BadParameter("--yes required for group-add")
-            if not username:
-                raise typer.BadParameter("--username required for group-add")
-            if not group_name:
-                raise typer.BadParameter("--group required for group-add")
-            args_summary.append(f"username={username}")
-            args_summary.append(f"group={group_name}")
-            client.add_user_to_group(username, group_name)
-            result_payload = {"username": username, "group": group_name, "status": "added"}
-
-        elif action == "group-remove":
-            if not yes:
-                raise typer.BadParameter("--yes required for group-remove")
-            if not username:
-                raise typer.BadParameter("--username required for group-remove")
-            if not group_name:
-                raise typer.BadParameter("--group required for group-remove")
-            args_summary.append(f"username={username}")
-            args_summary.append(f"group={group_name}")
-            client.remove_user_from_group(username, group_name)
-            result_payload = {"username": username, "group": group_name, "status": "removed"}
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("user_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("user_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="user",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("export")
-def cmd_export(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: page, space"),
-    page_id: str | None = typer.Option(None, "--page-id", help="Page ID (for page)"),
-    space_key: str | None = typer.Option(None, "--space-key", "-k", help="Space key (for space)"),
-    export_type: str | None = typer.Option(None, "--export-type", help="Export type: pdf, html, xml (for space)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    output: Path | None = typer.Option(None, "--output", "-o", help="Output file path (for page PDF)"),
-    api_version: str | None = typer.Option(
-        None, "--api-version", help="API version: cloud, server (for page, auto-detected if not specified)"
-    ),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Export Confluence pages or spaces."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        args_summary = [action]
-
-        if action == "page":
-            if not page_id:
-                raise typer.BadParameter("--page-id required for page action")
-            args_summary.append(f"page_id={page_id}")
-            if api_version:
-                args_summary.append(f"api_version={api_version}")
-
-            pdf_bytes = client.export_page(page_id, api_version=api_version)
-
-            if output:
-                output.write_bytes(pdf_bytes)
-                result_payload = {"page_id": page_id, "output_file": str(output), "size_bytes": len(pdf_bytes)}
-                typer.echo(f"Exported page {page_id} to {output} ({len(pdf_bytes)} bytes)")
-            else:
-                # Write to stdout as binary
-                sys.stdout.buffer.write(pdf_bytes)
-                result_payload = {"page_id": page_id, "size_bytes": len(pdf_bytes), "format": "pdf"}
-
-        elif action == "space":
-            if not space_key:
-                raise typer.BadParameter("--space-key required for space action")
-            if not export_type:
-                raise typer.BadParameter("--export-type required for space action")
-            if export_type not in ("pdf", "html", "xml"):
-                raise typer.BadParameter("--export-type must be one of: pdf, html, xml")
-            args_summary.append(f"space_key={space_key}")
-            args_summary.append(f"export_type={export_type}")
-
-            download_url = client.get_space_export(space_key, export_type)
-            result_payload = {"space_key": space_key, "export_type": export_type, "download_url": download_url}
-
-            if json_output or not sys.stdout.isatty():
-                _emit_json(result_payload)
-            else:
-                typer.echo(f"Space export URL: {download_url}")
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        # For page action, JSON output only if explicitly requested or output file specified
-        if action == "page" and (json_output or output) and json_output:
-            _emit_json(result_payload)
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("export_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("export_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="export",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("crawl-tree")
-def cmd_crawl_tree(
-    ctx: typer.Context,
-    root: str = typer.Argument(..., help="Root page reference (numeric ID, ?pageId= URL, or /display/<SPACE>/<Title>)"),
-    output_dir: Path = typer.Option(..., "--out", "-o", help="Output directory for downloaded pages/attachments"),
-    depth: int = typer.Option(
-        3,
-        "--depth",
-        "--crawl-max-depth",
-        min=0,
-        max=20,
-        help="Recursive child-page crawl depth (0 = only root).",
-    ),
-    include_attachments: bool = typer.Option(
-        True,
-        "--include-attachments/--no-include-attachments",
-        help="Download attachments for each visited page",
-    ),
-    emit_corpus: bool = typer.Option(
-        False,
-        "--emit-corpus/--no-emit-corpus",
-        help="Emit `corpus.jsonl` chunked by headings for LLM ingestion",
-    ),
-    emit_link_graph: bool = typer.Option(
-        False,
-        "--emit-link-graph/--no-emit-link-graph",
-        help="Emit `link-graph.json` (normalized outbound links) for doc↔code alignment",
-    ),
-    emit_tables: bool = typer.Option(
-        False,
-        "--emit-tables",
-        help="Emit `tables.jsonl` (extracted HTML tables) for downstream analysis",
-    ),
-    emit_mentions: bool = typer.Option(
-        False,
-        "--emit-mentions",
-        help="Emit `mentions.jsonl` (cross-system refs: Confluence/Jira/Bitbucket/external/email) for downstream analysis",
-    ),
-    body_format: str = typer.Option(
-        "view",
-        "--body-format",
-        help="Body representation to store/analyze: view|export_view|storage (default: view)",
-    ),
-    chunk_max_chars: int = typer.Option(
-        4000,
-        "--chunk-max-chars",
-        help="Max characters per corpus chunk (emit-corpus only). Oversized heading chunks are split into ordered subchunks (0 disables splitting).",
-    ),
-    cache_mode: str = typer.Option(
-        "read-write",
-        "--cache-mode",
-        help="Compatibility cache mode flag (off|read|read-write|refresh) for downstream orchestrators.",
-    ),
-    cache_ttl_hours: int | None = typer.Option(
-        None,
-        "--cache-ttl-hours",
-        min=1,
-        help="Compatibility cache TTL (hours) for downstream orchestrators.",
-    ),
-    incremental: bool = typer.Option(
-        True,
-        "--incremental/--no-incremental",
-        help="Compatibility incremental mode flag; enables resume semantics by default.",
-    ),
-    incremental_overlap_minutes: int = typer.Option(
-        5,
-        "--incremental-overlap-minutes",
-        min=0,
-        help="Incremental crawl overlap window in minutes for last-modified high-water mark refresh.",
-    ),
-    full_reconciliation_interval_days: int = typer.Option(
-        7,
-        "--full-reconciliation-interval-days",
-        min=1,
-        help="Interval in days for full reconciliation sweep when incremental mode is enabled.",
-    ),
-    content_root: Path | None = typer.Option(
-        None,
-        "--content-root",
-        help="Compatibility content root for downstream orchestrators (diagnostic metadata only).",
-    ),
-    project_storage_key: str | None = typer.Option(
-        None,
-        "--project-storage-key",
-        help="Compatibility project storage namespace key (diagnostic metadata only).",
-    ),
-    resume: bool = typer.Option(
-        False,
-        "--resume",
-        help="Resume from previous crawl state; skip unchanged pages (TSK-188)",
-    ),
-    max_nodes: int | None = typer.Option(
-        500,
-        "--max-nodes",
-        "--crawl-max-nodes",
-        min=1,
-        help="Safety limit: max pages to process before stopping (default: 500).",
-    ),
-    page_concurrency: int = typer.Option(
-        5,
-        "--page-concurrency",
-        "--crawl-concurrency",
-        min=1,
-        help="Bounded page fetch concurrency (default: 5).",
-    ),
-    staged_mode: str = typer.Option(
-        "off",
-        "--staged-mode",
-        "--staged-crawl-mode",
-        help="Optional staged crawl mode: off|structure-first (default: off).",
-    ),
-    rate_limit_budget: int = typer.Option(
-        50000,
-        "--rate-limit-budget",
-        min=100,
-        help="Hourly Confluence API points budget used for proactive crawl throttling.",
-    ),
-    bundle: bool = typer.Option(
-        False,
-        "--bundle",
-        help="Create zip bundle of all artifacts for offline handoff (TSK-189)",
-    ),
-    manifest_path: Path | None = typer.Option(
-        None,
-        "--manifest",
-        help="Optional manifest file path (default: <out>/crawl_manifest.json)",
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Crawl a Confluence page tree and download content + attachments to disk."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    server_key: str | None = None
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-
-    try:
-        settings = load_settings(strict=True)
-        if server is None:
-            inferred = _infer_server_from_root_ref(root, settings)
-            if inferred:
-                server = inferred
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        body_format = (body_format or "view").strip().lower().replace("-", "_")
-        if body_format not in {"view", "export_view", "storage"}:
-            raise typer.BadParameter("--body-format must be one of: view, export_view, storage")
-        cache_mode = (cache_mode or "read-write").strip().lower()
-        if cache_mode not in {"off", "read", "read-write", "refresh"}:
-            raise typer.BadParameter("--cache-mode must be one of: off, read, read-write, refresh")
-        staged_mode = (staged_mode or "off").strip().lower().replace("-", "_")
-        if staged_mode not in {"off", "structure_first"}:
-            raise typer.BadParameter("--staged-mode must be one of: off, structure-first")
-        if chunk_max_chars < 0:
-            raise typer.BadParameter("--chunk-max-chars must be >= 0")
-        effective_resume = bool(resume or incremental)
-
-        args_summary = [
-            root,
-            f"depth={depth}",
-            f"out={output_dir!s}",
-            f"attachments={include_attachments}",
-            f"body_format={body_format}",
-            f"chunk_max_chars={chunk_max_chars}",
-            f"resume={resume}",
-            f"incremental={incremental}",
-            f"incremental_overlap_minutes={incremental_overlap_minutes}",
-            f"full_reconciliation_interval_days={full_reconciliation_interval_days}",
-            f"effective_resume={effective_resume}",
-            f"cache_mode={cache_mode}",
-            f"cache_ttl_hours={cache_ttl_hours}",
-            f"content_root={content_root}",
-            f"project_storage_key={project_storage_key}",
-            f"max_nodes={max_nodes}",
-            f"page_concurrency={page_concurrency}",
-            f"staged_mode={staged_mode}",
-            f"rate_limit_budget={rate_limit_budget}",
-            f"bundle={bundle}",
-        ]
-
-        runtime_event_logger = logging.getLogger("confluence_cli.crawl_tree")
-
-        def _runtime_event_sink(event_name: str, payload: dict[str, Any]) -> None:
-            runtime_event_logger.info(
-                "crawl_tree_runtime_event %s %s",
-                event_name,
-                json.dumps(payload, ensure_ascii=False, sort_keys=True),
-            )
-
-        result_payload = crawl_tree_to_disk(
-            http=client,
-            root_ref=root,
-            output_dir=output_dir,
-            options=CrawlOptions(
-                max_depth=depth,
-                include_attachments=include_attachments,
-                emit_corpus=emit_corpus,
-                emit_link_graph=emit_link_graph,
-                emit_tables=emit_tables,
-                emit_mentions=emit_mentions,
-                body_format=body_format,
-                chunk_max_chars=None if chunk_max_chars == 0 else chunk_max_chars,
-                resume=effective_resume,
-                max_nodes=max_nodes,
-                page_concurrency=page_concurrency,
-                staged_mode=staged_mode,
-                incremental_cql=incremental,
-                incremental_overlap_minutes=incremental_overlap_minutes,
-                full_reconciliation_interval_days=full_reconciliation_interval_days,
-                rate_limit_budget=rate_limit_budget,
-                runtime_event_sink=_runtime_event_sink,
-                bundle=bundle,
-            ),
-            manifest_path=manifest_path,
-        )
-        result_payload["cache"] = {
-            "mode": cache_mode,
-            "ttl_hours": cache_ttl_hours,
-            "incremental": incremental,
-            "incremental_overlap_minutes": incremental_overlap_minutes,
-            "full_reconciliation_interval_days": full_reconciliation_interval_days,
-            "effective_resume": effective_resume,
-            "content_root": str(content_root) if content_root else None,
-            "project_storage_key": project_storage_key,
-        }
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            root_id = result_payload.get("root_page_id")
-            pages = 1 + len(result_payload.get("child_pages") or [])
-            atts = len(result_payload.get("attachments") or [])
-            resume_state = result_payload.get("resume_state") or {}
-            skipped = resume_state.get("skipped_unchanged", 0)
-            typer.echo(f"Crawled {pages} page(s), downloaded {atts} attachment(s). Root: {root_id}.")
-            if skipped > 0:
-                typer.echo(f"Skipped {skipped} unchanged page(s) (resume mode).")
-            if max_nodes and not resume_state.get("completed", True):
-                typer.echo(f"Stopped at max_nodes={max_nodes}. Use --resume to continue.")
-            typer.echo(f"Output: {result_payload.get('out_dir')}")
-            if result_payload.get("bundle_path"):
-                typer.echo(f"Bundle: {result_payload.get('bundle_path')}")
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("crawl_tree_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("crawl_tree_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="crawl-tree",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("draft")
-def cmd_draft(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: get, list, remove"),
-    page_id: str | None = typer.Option(None, "--page-id", help="Page ID (for get/remove)"),
-    space_key: str | None = typer.Option(None, "--space-key", "-k", help="Space key (for list)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    limit: int = typer.Option(25, "--limit", help="Limit for list (max 100)"),
-    yes: bool = typer.Option(False, "--yes", help="Confirm write operations (for remove)"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence draft pages (Server-only)."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        if limit < 1 or limit > 100:
-            raise typer.BadParameter("--limit must be between 1 and 100")
-
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        args_summary = [action]
-
-        if action == "get":
-            if not page_id:
-                raise typer.BadParameter("--page-id required for get action")
-            args_summary.append(f"page_id={page_id}")
-            result = client.get_draft_page_by_id(page_id)
-            result_payload = {"draft_page": result}
-
-        elif action == "list":
-            if not space_key:
-                raise typer.BadParameter("--space-key required for list action")
-            args_summary.append(f"space_key={space_key}")
-            args_summary.append(f"limit={limit}")
-            result = client.get_all_draft_pages_from_space(space_key, limit=limit)
-            result_payload = {"space": space_key, "count": len(result), "drafts": result}
-
-        elif action == "remove":
-            if not yes:
-                raise typer.BadParameter("--yes required for remove action")
-            if not page_id:
-                raise typer.BadParameter("--page-id required for remove action")
-            args_summary.append(f"page_id={page_id}")
-            client.remove_page_as_draft(page_id)
-            result_payload = {"page_id": page_id, "status": "removed"}
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("draft_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("draft_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="draft",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("history")
-def cmd_history(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: get, version, remove"),
-    page_id: str | None = typer.Option(None, "--page-id", help="Page ID"),
-    version: int | None = typer.Option(None, "--version", help="Version number (for version/remove)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    yes: bool = typer.Option(False, "--yes", help="Confirm write operations (for remove)"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence page history and versioning."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        args_summary = [action]
-
-        if action == "get":
-            if not page_id:
-                raise typer.BadParameter("--page-id required for get action")
-            args_summary.append(f"page_id={page_id}")
-            result = client.history(page_id)
-            result_payload = {"page_id": page_id, "history": result}
-
-        elif action == "version":
-            if not page_id:
-                raise typer.BadParameter("--page-id required for version action")
-            if version is None:
-                raise typer.BadParameter("--version required for version action")
-            args_summary.append(f"page_id={page_id}")
-            args_summary.append(f"version={version}")
-            result = client.get_content_history_by_version_number(page_id, version)
-            result_payload = {"page_id": page_id, "version": version, "content": result}
-
-        elif action == "remove":
-            if not yes:
-                raise typer.BadParameter("--yes required for remove action (experimental feature)")
-            if not page_id:
-                raise typer.BadParameter("--page-id required for remove action")
-            if version is None:
-                raise typer.BadParameter("--version required for remove action")
-            args_summary.append(f"page_id={page_id}")
-            args_summary.append(f"version={version}")
-            typer.echo("Warning: remove_content_history is an experimental feature", err=True)
-            client.remove_content_history(page_id, version)
-            result_payload = {"page_id": page_id, "version": version, "status": "removed"}
-
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("history_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("history_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="history",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("cache")
-def cmd_cache(
-    ctx: typer.Context,
-    action: str = typer.Argument(..., help="Action: statistics, flush, size"),
-    cache_name: str | None = typer.Option(None, "--cache-name", help="Cache name (for flush)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    yes: bool = typer.Option(False, "--yes", help="Confirm write operation (for flush)"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Manage Confluence cache (Server-only)."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    args_summary: list[str] = []
-    server_key: str | None = None
-    settings: ConfluenceSettings | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        args_summary = [action]
-
-        if action == "statistics":
-            result = client.get_cache_statistics()
-            result_payload = {"cache_statistics": result}
-        elif action == "flush":
-            if not yes:
-                raise typer.BadParameter("Refusing to flush cache without --yes")
-            if cache_name:
-                args_summary.append(f"cache_name={cache_name}")
-            client.flush_cache(cache_name=cache_name)
-            result_payload = {"status": "success", "cache_flushed": cache_name or "all"}
-        elif action == "size":
-            result = client.get_cache_size()
-            result_payload = {"cache_size": result}
-        else:
-            raise typer.BadParameter(f"Unknown action: {action}")
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("cache_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("cache_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="cache",
-            args=args_summary,
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@app.command("get")
-def cmd_get(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    expand: str | None = typer.Option(
-        None, "--expand", "-e", help="Comma separated expansions (e.g., 'body.storage,version')"
-    ),
-    format: str | None = typer.Option(None, "--format", "-f", help="Output format (storage|editor|view)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Get Confluence content by page ID."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "get")
-    started_at = datetime.now(UTC)
-    settings = load_settings(strict=True)
-    server_key = _normalise_server(server, settings)
-
-    try:
-        client = ContentClientV2(_build_http_client(settings, server_key))
-        content = client.get_content(page_id, expand=_expand_option(expand), format=format)
-
-        if content:
-            _emit_json(content)
-        else:
-            typer.echo(f"Content not found: {page_id}", err=True)
-            raise typer.Exit(code=1) from None
-
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="get",
-            args=[page_id],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-    except Exception as exc:
-        logger.exception("get_command_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-
-
-# ---------------------------------------------------------------------------
-# Native content commands
-# ---------------------------------------------------------------------------
-
-
-@batch_app.command("scan")
-def batch_scan(
-    ctx: typer.Context,
-    cql: str = typer.Option(..., "--cql", "-q", help="CQL query string"),
-    limit: int = typer.Option(25, "--limit", help="Number of results per request"),
-    max_results: int | None = typer.Option(None, "--max-results", help="Total results to fetch"),
-    start: int = typer.Option(0, "--start", help="Pagination start offset"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "batch.scan")
-    started_at = datetime.now(UTC)
-    settings = load_settings(strict=True)
-    server_key = _normalise_server(server, settings)
-    runner = BatchRunner(_build_http_client(settings, server_key), expand=_expand_option(expand))
-    results: list[dict[str, Any]] = []
-    for item in runner.scan(cql, limit=limit, max_results=max_results, start=start):
-        results.append(item)
-    metrics = runner.last_metrics
-    payload: dict[str, Any] = {
-        "cql": cql,
-        "count": len(results),
-        "limit": limit,
-        "maxResults": max_results,
-        "start": start,
-        "results": results,
-    }
-    if metrics is not None:
-        payload["metrics"] = {
-            "requests": metrics.requests,
-            "pagesProcessed": metrics.pages_processed,
-            "durationSeconds": metrics.duration_seconds,
-        }
-    if json_output or not sys.stdout.isatty():
-        _emit_json(payload)
-    else:
-        typer.echo(
-            f"Scanned {payload['count']} results (requests={payload['metrics']['requests'] if 'metrics' in payload else '?'})"
-        )
-    finished_at = datetime.now(UTC)
-    _record_summary(
-        parent_ctx,
-        command="batch.scan",
-        args=[cql, f"limit={limit}", f"start={start}"],
-        server=server_key,
-        exit_code=0,
-        started_at=started_at,
-        finished_at=finished_at,
-    )
-
-
-@batch_app.command("snapshot")
-def batch_snapshot(
-    ctx: typer.Context,
-    cql: str = typer.Option(..., "--cql", "-q", help="CQL query string"),
-    limit: int = typer.Option(25, "--limit", help="Number of results per request"),
-    max_results: int | None = typer.Option(None, "--max-results", help="Total results to fetch"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "batch.snapshot")
-    started_at = datetime.now(UTC)
-    settings = load_settings(strict=True)
-    server_key = _normalise_server(server, settings)
-    runner = BatchRunner(_build_http_client(settings, server_key))
-    payload = runner.snapshot(cql, limit=limit, max_results=max_results, expand=_expand_option(expand))
-    _emit_json(payload)
-    finished_at = datetime.now(UTC)
-    _record_summary(
-        parent_ctx,
-        command="batch.snapshot",
-        args=[cql, f"limit={limit}"],
-        server=server_key,
-        exit_code=0,
-        started_at=started_at,
-        finished_at=finished_at,
-    )
-
-
-@batch_app.command("poll")
-def batch_poll(
-    ctx: typer.Context,
-    cql: str = typer.Option(..., "--cql", "-q", help="Base CQL query (will be augmented with lastmodified filter)"),
-    state_file: Path = typer.Option(..., "--state-file", help="Path to persistent cursor file (JSON)"),
-    limit: int = typer.Option(25, "--limit", help="Page size per request"),
-    max_results: int | None = typer.Option(None, "--max-results", help="Max results this run"),
-    expand: str | None = typer.Option(
-        "version", "--expand", help="Comma separated expansions (default includes 'version')"
-    ),
-    out_jsonl: Path | None = typer.Option(None, "--out-jsonl", help="Write results to JSONL (one object per line)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "batch.poll")
-    started_at = datetime.now(UTC)
-    server_key = "internal"
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-        poller = Poller(client)
-        expand_list = _expand_option(expand) or ["version"]
-        count = poller.poll_once(
-            base_cql=cql,
-            state_file=state_file,
-            limit=limit,
-            max_results=max_results,
-            expand=expand_list,
-            out_jsonl=out_jsonl,
-        )
-        typer.echo(f"Polled {count} items")
-    except Exception as exc:
-        logger.exception("batch.poll failed", extra={"cql": cql})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    finally:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="batch.poll",
-            args=[cql, f"limit={limit}", f"out={str(out_jsonl) if out_jsonl else '-'}"],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@webhook_app.command("create")
-def webhook_create(
-    ctx: typer.Context,
-    name: str = typer.Option(..., "--name", "-n", help="Webhook name"),
-    url: str = typer.Option(..., "--url", help="Destination URL"),
-    event: list[str] = typer.Option(["page_created"], "--event", "-e", help="Event identifier"),
-    active: bool = typer.Option(True, "--active/--inactive", help="Toggle webhook activation"),
-    filters: str | None = typer.Option(None, "--filters", help="JSON object filters"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "webhook.create")
-    started_at = datetime.now(UTC)
-    settings = load_settings(strict=True)
-    server_key = _normalise_server(server, settings)
-    client = WebhookClient(_build_http_client(settings, server_key))
-    payload = client.create(
-        name=name,
-        url=url,
-        events=event,
-        active=active,
-        filters=_parse_json_option(filters, "--filters"),
-    )
-    if json_output:
-        _emit_json(payload)
-    else:
-        typer.echo(f"Created webhook {payload.get('id')}")
-    finished_at = datetime.now(UTC)
-    _record_summary(
-        parent_ctx,
-        command="webhook.create",
-        args=[name, f"events={len(event)}"],
-        server=server_key,
-        exit_code=0,
-        started_at=started_at,
-        finished_at=finished_at,
-    )
-
-
-@webhook_app.command("list")
-def webhook_list(
-    ctx: typer.Context,
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "webhook.list")
-    started_at = datetime.now(UTC)
-    settings = load_settings(strict=True)
-    server_key = _normalise_server(server, settings)
-    client = WebhookClient(_build_http_client(settings, server_key))
-    payload = client.list()
-    if json_output:
-        _emit_json(payload)
-    else:
-        typer.echo(f"{len(payload)} webhooks")
-    finished_at = datetime.now(UTC)
-    _record_summary(
-        parent_ctx,
-        command="webhook.list",
-        args=[f"count={len(payload)}"],
-        server=server_key,
-        exit_code=0,
-        started_at=started_at,
-        finished_at=finished_at,
-    )
-
-
-@webhook_app.command("delete")
-def webhook_delete(
-    ctx: typer.Context,
-    webhook_id: str = typer.Argument(..., help="Webhook identifier"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "webhook.delete")
-    started_at = datetime.now(UTC)
-    settings = load_settings(strict=True)
-    server_key = _normalise_server(server, settings)
-    client = WebhookClient(_build_http_client(settings, server_key))
-    client.delete(webhook_id)
-    typer.echo(f"Deleted webhook {webhook_id}")
-    finished_at = datetime.now(UTC)
-    _record_summary(
-        parent_ctx,
-        command="webhook.delete",
-        args=[webhook_id],
-        server=server_key,
-        exit_code=0,
-        started_at=started_at,
-        finished_at=finished_at,
-    )
-
-
-@content_app.command("page")
-def content_page(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Fetch a Confluence page by ID."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        cli_ctx = _get_cli_ctx(parent_ctx)
-        client = _build_content_client(settings, server_key, cli_ctx.api_version)
-        expand_list = _expand_option(expand)
-        payload = client.get_page(page_id, expand=expand_list)
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.page failed", extra={"page_id": page_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.page",
-            args=[page_id],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("search")
-def content_search(
-    ctx: typer.Context,
-    cql: str = typer.Argument(..., help="CQL query string"),
-    limit: int = typer.Option(25, "--limit", help="Number of results"),
-    start: int = typer.Option(0, "--start", help="Pagination start"),
-    expand: str | None = typer.Option(None, "--expand", help="Comma separated expansions"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Search Confluence pages by CQL query."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    server_key: str = ""
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        cli_ctx = _get_cli_ctx(parent_ctx)
-        client = _build_content_client(settings, server_key, cli_ctx.api_version)
-        expand_list = _expand_option(expand)
-        payload = client.search_cql(cql, limit=limit, start=start, expand=expand_list)
-        _emit_json(payload)
-    except Exception as exc:
-        exit_code = 1
-        logger.exception("content.search failed", extra={"cql": cql})
-        # Provide targeted guidance for CQL auth failures
-        from .errors import AuthError  # local import to avoid top-level cycles
-
-        if isinstance(exc, AuthError):
-            typer.echo("Error: Authentication failed for CQL search.", err=True)
-            typer.echo("Hint: We default to Basic auth (VDS_USERNAME/PASSWORD). If using token, ensure:", err=True)
-            typer.echo("  - Token has permission to use CQL (/rest/api/*search)", err=True)
-            typer.echo("  - Or set VDS_USERNAME/VDS_PASSWORD to use Basic auth", err=True)
-            typer.echo(
-                "  - Quick check: curl -u \"$VDS_USERNAME:$VDS_PASSWORD\" 'http://confluence.digital.vn/rest/api/search?cql=type=page&limit=1'",
-                err=True,
-            )
-        else:
-            typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.search",
-            args=_content_summary_args(cql=cql, limit=limit, start=start),
-            server=server_key,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@content_app.command("templates")
-def content_templates(
-    ctx: typer.Context,
-    space_key: str | None = typer.Option(None, "--space", help="Space key"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """List available Confluence page templates."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        cli_ctx = _get_cli_ctx(parent_ctx)
-        client = _build_content_client(settings, server_key, cli_ctx.api_version)
-        if hasattr(client, "list_templates"):
-            payload = client.list_templates(space_key=space_key)
-        else:
-            payload = {"templates": [], "message": "Templates API not available for this server"}
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.templates failed", extra={"space": space_key})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.templates",
-            args=_content_summary_args(space=space_key or "*"),
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("create-page")
-def content_create_page(
-    ctx: typer.Context,
-    space_key: str = typer.Option(..., "--space", "-S", help="Space key to create the page in"),
-    title: str = typer.Option(..., "--title", "-t", help="Page title"),
-    body_file: Path = typer.Option(
-        ..., "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
-    ),
-    parent_id: str | None = typer.Option(None, "--parent", help="Ancestor page id"),
-    representation: str = typer.Option(
-        "storage", "--representation", help="Content representation (storage, wiki, view)"
-    ),
-    status: str = typer.Option("current", "--status", help="Target page status (current, draft)"),
-    notify_watchers: bool = typer.Option(
-        False, "--notify-watchers/--no-notify-watchers", help="Send notifications to watchers"
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Create a new Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.create-page")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        body = _read_text_file(body_file)
-        payload = client.create_page(
-            space_key=space_key,
-            title=title,
-            body=body,
-            parent_id=parent_id,
-            representation=representation,
-            status=status,
-            notify_watchers=notify_watchers,
-        )
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.create-page failed", extra={"space": space_key, "title": title})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.create-page",
-            args=[f"space={space_key}", f"title={title}"],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("update-page")
-def content_update_page(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    title: str | None = typer.Option(None, "--title", help="New page title"),
-    body_file: Path | None = typer.Option(
-        None, "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
-    ),
-    space_key: str | None = typer.Option(None, "--space", help="Move page to this space"),
-    version: int | None = typer.Option(None, "--version", help="Explicit version number"),
-    representation: str = typer.Option("storage", "--representation", help="Content representation for --body-file"),
-    minor_edit: bool = typer.Option(False, "--minor-edit/--no-minor-edit", help="Mark version as minor edit"),
-    message: str | None = typer.Option(None, "--message", help="Version comment"),
-    status: str = typer.Option("current", "--status", help="Target page status"),
-    notify_watchers: bool = typer.Option(
-        False, "--notify-watchers/--no-notify-watchers", help="Send notifications to watchers"
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Update an existing Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.update-page")
-    if body_file is None and title is None and space_key is None:
-        raise typer.BadParameter("Provide at least one of --title, --body-file or --space")
-    body = _read_text_file(body_file) if body_file else None
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        payload = client.update_page(
-            page_id,
-            title=title,
-            body=body,
-            space_key=space_key,
-            representation=representation,
-            version=version,
-            minor_edit=minor_edit,
-            message=message,
-            status=status,
-            notify_watchers=notify_watchers,
-        )
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.update-page failed", extra={"page_id": page_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        args = [page_id]
-        if version is not None:
-            args.append(f"version={version}")
-        if title is not None:
-            args.append(f"title={title}")
-        _record_summary(
-            parent_ctx,
-            command="content.update-page",
-            args=args,
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("delete-page")
-def content_delete_page(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    status: str = typer.Option("current", "--status", help="Specify current or draft"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Delete a Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.delete-page")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        client.delete_page(page_id, status=status)
-        typer.echo(f"Deleted page {page_id} (status={status})")
-    except Exception as exc:
-        logger.exception("content.delete-page failed", extra={"page_id": page_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.delete-page",
-            args=[page_id, f"status={status}"],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("add-attachment")
-def content_add_attachment(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    file_path: Path = typer.Option(..., "--file", exists=True, file_okay=True, dir_okay=False, help="File to upload"),
-    filename: str | None = typer.Option(None, "--filename", help="Override uploaded filename"),
-    content_type: str | None = typer.Option(None, "--content-type", help="MIME type for the attachment"),
-    comment: str | None = typer.Option(None, "--comment", help="Attachment comment"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Add an attachment to a Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.add-attachment")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        payload = client.upload_attachment(
-            page_id,
-            str(file_path),
-            filename=filename,
-            content_type=content_type,
-            comment=comment,
-        )
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.add-attachment failed", extra={"page_id": page_id, "file": str(file_path)})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.add-attachment",
-            args=[page_id, file_path.name],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("download-attachment")
-def content_download_attachment(
-    ctx: typer.Context,
-    attachment_id: str = typer.Argument(..., help="Attachment ID"),
-    output_path: Path = typer.Option(
-        ..., "--out", "-o", file_okay=True, dir_okay=True, help="Output file path or directory"
-    ),
-    filename: str | None = typer.Option(None, "--filename", help="Override downloaded filename"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Download a Confluence attachment by ID to a local file."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.download-attachment")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        output = client.download_attachment(attachment_id, output_path, filename=filename)
-        _emit_json({"attachment_id": attachment_id, "output_path": str(output)})
-    except Exception as exc:
-        logger.exception("content.download-attachment failed", extra={"attachment_id": attachment_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.download-attachment",
-            args=[attachment_id, str(output_path)],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("add-comment")
-def content_add_comment(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    body: str | None = typer.Option(None, "--body", help="Comment body in Confluence storage format"),
-    body_file: Path | None = typer.Option(
-        None, "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to file containing comment body"
-    ),
-    parent_id: str | None = typer.Option(
-        None,
-        "--parent-id",
-        help="Optional parent comment ID to create a threaded reply instead of a top-level comment",
-    ),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Add a comment to a Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.add-comment")
-    started_at = datetime.now(UTC)
-
-    if bool(body) == bool(body_file):
-        raise typer.BadParameter("Provide either --body or --body-file")
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        if body is not None:
-            comment_body = body
-        else:
-            assert body_file is not None
-            comment_body = _read_text_file(body_file)
-        payload = client.add_comment(page_id, comment_body, parent_id=parent_id)
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.add-comment failed", extra={"page_id": page_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.add-comment",
-            args=[page_id],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("update-attachment")
-def content_update_attachment(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    attachment_id: str = typer.Argument(..., help="Attachment ID"),
-    file_path: Path = typer.Option(..., "--file", exists=True, file_okay=True, dir_okay=False, help="Replacement file"),
-    filename: str | None = typer.Option(None, "--filename", help="Override uploaded filename"),
-    content_type: str | None = typer.Option(None, "--content-type", help="MIME type for the attachment"),
-    comment: str | None = typer.Option(None, "--comment", help="Attachment comment"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Update an existing attachment on a Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.update-attachment")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        payload = client.update_attachment(
-            page_id,
-            attachment_id,
-            str(file_path),
-            filename=filename,
-            content_type=content_type,
-            comment=comment,
-        )
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.update-attachment failed", extra={"page_id": page_id, "attachment_id": attachment_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.update-attachment",
-            args=[page_id, attachment_id],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("delete-attachment")
-def content_delete_attachment(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    attachment_id: str | None = typer.Argument(None, help="Attachment ID"),
-    version: int | None = typer.Option(None, "--version", help="Delete a specific attachment version"),
-    filename: str | None = typer.Option(None, "--filename", help="Attachment filename (delete all versions)"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Delete an attachment from a Confluence page."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.delete-attachment")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        if not attachment_id and not filename:
-            raise typer.BadParameter("Provide either attachment_id or --filename")
-
-        client = ContentClient(_build_http_client(settings, server_key))
-        client.delete_attachment(page_id, attachment_id=attachment_id, version=version, filename=filename)
-        target = filename or attachment_id
-        typer.echo(f"Deleted attachment {target} from page {page_id}")
-    except Exception as exc:
-        logger.exception("content.delete-attachment failed", extra={"page_id": page_id, "attachment_id": attachment_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.delete-attachment",
-            args=[
-                page_id,
-                filename or attachment_id or "<unspecified>",
-                f"version={version}" if version is not None else "all_versions",
-            ],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("ancestors")
-def content_ancestors(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Get page ancestors (parent pages)."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    server_key: str | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        result = client.get_page_ancestors(page_id)
-        result_payload = {"page_id": page_id, "count": len(result), "ancestors": result}
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("content.ancestors_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("content.ancestors_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="content.ancestors",
-            args=[page_id],
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@content_app.command("move")
-def content_move(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    target_title: str = typer.Option(..., "--target-title", help="Target page title to move under"),
-    position: str = typer.Option("append", "--position", help="Position: append, before, after"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    yes: bool = typer.Option(False, "--yes", help="Confirm move operation"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Move page to a new location."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    server_key: str | None = None
-
-    try:
-        if not yes:
-            raise typer.BadParameter("--yes required for move operation")
-        if position not in ("append", "before", "after"):
-            raise typer.BadParameter("--position must be one of: append, before, after")
-
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        result = client.move_page(page_id, target_title, position=position)
-        result_payload = {"page_id": page_id, "target_title": target_title, "position": position, "result": result}
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("content.move_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("content.move_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="content.move",
-            args=[page_id, f"target={target_title}", f"position={position}"],
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@content_app.command("tables")
-def content_tables(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Extract tables from page."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    server_key: str | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        result = client.get_tables_from_page(page_id)
-        result_payload = {"page_id": page_id, "count": len(result), "tables": result}
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("content.tables_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("content.tables_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="content.tables",
-            args=[page_id],
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@content_app.command("regex")
-def content_regex(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    pattern: str = typer.Option(..., "--pattern", help="Regex pattern to match"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Extract regex matches from page."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    server_key: str | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        result = client.scrap_regex_from_page(page_id, pattern)
-        result_payload = {"page_id": page_id, "pattern": pattern, "count": len(result), "matches": result}
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("content.regex_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("content.regex_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="content.regex",
-            args=[page_id, f"pattern={pattern}"],
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@content_app.command("restrictions")
-def content_restrictions(
-    ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    json_output: bool = typer.Option(False, "--json", help="Emit JSON payload"),
-) -> None:
-    """Get all restrictions for content."""
-    parent_ctx = _parent_context(ctx)
-    started_at = datetime.now(UTC)
-    exit_code = 0
-    result_payload: dict[str, Any] = {}
-    server_key: str | None = None
-
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = _build_http_client(settings, server_key)
-
-        result = client.get_all_restrictions_for_content(page_id)
-        result_payload = {"page_id": page_id, "restrictions": result}
-
-        if json_output or not sys.stdout.isatty():
-            _emit_json(result_payload)
-        else:
-            typer.echo(json.dumps(result_payload, indent=2, sort_keys=True))
-
-    except (VDSClientError, typer.BadParameter) as exc:
-        exit_code = 1
-        logger.exception("content.restrictions_failed: %s", exc)
-        typer.echo(f"Error: {exc}", err=True)
-    except Exception as exc:  # pragma: no cover - unexpected errors
-        exit_code = 1
-        logger.exception("content.restrictions_unexpected_error")
-        typer.echo(f"Error: {exc}", err=True)
-    finally:
-        finished_at = datetime.now(UTC)
-        server_label = server_key or (server.lower() if server else "internal")
-        _record_summary(
-            parent_ctx,
-            command="content.restrictions",
-            args=[page_id],
-            server=server_label,
-            exit_code=exit_code,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-        if exit_code != 0:
-            raise typer.Exit(code=exit_code) from None
-
-
-@content_app.command("create-template")
-def content_create_template(
-    ctx: typer.Context,
-    name: str = typer.Option(..., "--name", "-n", help="Template name"),
-    body_file: Path = typer.Option(
-        ..., "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
-    ),
-    template_type: str = typer.Option("page", "--type", help="Template type (page or other supported types)"),
-    space_key: str | None = typer.Option(None, "--space", help="Limit template to space key"),
-    description: str | None = typer.Option(None, "--description", help="Template description"),
-    representation: str = typer.Option("storage", "--representation", help="Content representation"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Create a new Confluence page template."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.create-template")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        body = _read_text_file(body_file)
-        payload = client.create_template(
-            name=name,
-            body=body,
-            template_type=template_type,
-            space_key=space_key,
-            description=description,
-            representation=representation,
-        )
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.create-template failed", extra={"name": name, "space": space_key})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        args = [name, f"type={template_type}"]
-        if space_key:
-            args.append(f"space={space_key}")
-        _record_summary(
-            parent_ctx,
-            command="content.create-template",
-            args=args,
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("update-template")
-def content_update_template(
-    ctx: typer.Context,
-    template_id: str = typer.Argument(..., help="Template identifier"),
-    name: str | None = typer.Option(None, "--name", help="Template name"),
-    body_file: Path | None = typer.Option(
-        None, "--body-file", exists=True, file_okay=True, dir_okay=False, help="Path to storage-format body"
-    ),
-    description: str | None = typer.Option(None, "--description", help="Template description"),
-    template_type: str | None = typer.Option(None, "--type", help="Template type"),
-    representation: str = typer.Option("storage", "--representation", help="Representation for --body-file"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Update an existing Confluence page template."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.update-template")
-    if name is None and body_file is None and description is None and template_type is None:
-        raise typer.BadParameter("Provide at least one of --name, --body-file, --description, or --type")
-    body = _read_text_file(body_file) if body_file else None
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        payload = client.update_template(
-            template_id,
-            name=name,
-            body=body,
-            description=description,
-            representation=representation,
-            template_type=template_type,
-        )
-        _emit_json(payload)
-    except Exception as exc:
-        logger.exception("content.update-template failed", extra={"template_id": template_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        args = [template_id]
-        if name:
-            args.append(f"name={name}")
-        _record_summary(
-            parent_ctx,
-            command="content.update-template",
-            args=args,
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-@content_app.command("delete-template")
-def content_delete_template(
-    ctx: typer.Context,
-    template_id: str = typer.Argument(..., help="Template identifier"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-) -> None:
-    """Delete a Confluence page template."""
-    parent_ctx = _parent_context(ctx)
-    _ensure_v1_api(parent_ctx, "content.delete-template")
-    started_at = datetime.now(UTC)
-    try:
-        settings = load_settings(strict=True)
-        server_key = _normalise_server(server, settings)
-        client = ContentClient(_build_http_client(settings, server_key))
-        client.delete_template(template_id)
-        typer.echo(f"Deleted template {template_id}")
-    except Exception as exc:
-        logger.exception("content.delete-template failed", extra={"template_id": template_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.delete-template",
-            args=[template_id],
-            server=server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Diagnostics
-# ---------------------------------------------------------------------------
-
-
-@app.command("env")
-def cmd_env(_ctx: typer.Context) -> None:
-    """Show Confluence connection environment variable status."""
-    settings = load_settings(strict=False)
-    typer.echo(
-        f"Default server: {settings.default_server}\n"
-        f"Internal URL: {settings.internal_url}\n"
-        f"External URL: {settings.external_url}\n"
-        f"Internal token set: {bool(settings.internal_token)}\n"
-        f"External token set: {bool(settings.external_token)}"
-    )
-
-
-# ---------------------------------------------------------------------------
-# Sync Commands (delegate to standalone scripts)
-# ---------------------------------------------------------------------------
-
-sync_app = typer.Typer(help="Sync attachments from local files to Confluence")
-app.add_typer(sync_app, name="sync")
-
-
-@sync_app.command("pngs")
-def cmd_sync_pngs(
-    _ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    directory: Path = typer.Option(..., "--dir", "-d", help="Directory containing PNG files"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    pattern: str | None = typer.Option(None, "--pattern", "-p", help="Filter PNG files by pattern"),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be done without making changes"),
-    comment: str | None = typer.Option(None, "--comment", "-c", help="Comment for attachment updates"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-confirm without prompting"),
-) -> None:
-    """Sync local PNG files with Confluence page attachments."""
-    import subprocess
-    import sys
-
-    # Project root for confluence_orchestrator (where sync scripts live)
-    script_path = Path(__file__).resolve().parents[2] / "sync_png_attachments.py"
-    if not script_path.exists():
-        typer.echo(f"Error: Sync script not found: {script_path}", err=True)
-        raise typer.Exit(code=1) from None
-
-    cmd = [
-        sys.executable,
-        str(script_path),
-        "sync",
-        page_id,
-        "--dir",
-        str(directory),
-    ]
-    if server:
-        cmd.extend(["--server", server])
-    if pattern:
-        cmd.extend(["--pattern", pattern])
-    if dry_run:
-        cmd.append("--dry-run")
-    if comment:
-        cmd.extend(["--comment", comment])
-    if yes:
-        cmd.append("--yes")
-
-    result = subprocess.run(cmd, check=False)
-    raise typer.Exit(code=result.returncode) from None
-
-
-@sync_app.command("pdfs")
-def cmd_sync_pdfs(
-    _ctx: typer.Context,
-    page_id: str = typer.Argument(..., help="Confluence page ID"),
-    directory: Path = typer.Option(..., "--dir", "-d", help="Directory containing PDF files"),
-    server: str | None = typer.Option(None, "--server", "-s", help="internal|external"),
-    pattern: str | None = typer.Option(None, "--pattern", "-p", help="Filter PDF files by pattern"),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be done without making changes"),
-    comment: str | None = typer.Option(None, "--comment", "-c", help="Comment for attachment updates"),
-    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-confirm without prompting"),
-) -> None:
-    """Sync local PDF files with Confluence page attachments.
-
-    This command delegates to the standalone sync_pdfs_to_confluence.py script.
-    For markdown-to-PDF sync, use the PDF orchestrator: vds-cli pdf -- md2pdf
-    """
-    import subprocess
-    import sys
-
-    # Look for script in confluence_orchestrator/ directory (standard location)
-    script_path = Path(__file__).resolve().parents[2] / "sync_pdfs_to_confluence.py"
-
-    if not script_path.exists():
-        typer.echo(
-            f"Error: Sync script not found: {script_path}\n"
-            "Note: Ensure sync_pdfs_to_confluence.py exists in confluence_orchestrator/ directory.",
-            err=True,
-        )
-        raise typer.Exit(code=1) from None
-
-    cmd = [
-        sys.executable,
-        str(script_path),
-        "sync",
-        page_id,
-        "--dir",
-        str(directory),
-    ]
-    if server:
-        cmd.extend(["--server", server])
-    if pattern:
-        cmd.extend(["--pattern", pattern])
-    if dry_run:
-        cmd.append("--dry-run")
-    if comment:
-        cmd.extend(["--comment", comment])
-    if yes:
-        cmd.append("--yes")
-
-    result = subprocess.run(cmd, check=False)
-    raise typer.Exit(code=result.returncode) from None
-
-
-# ---------------------------------------------------------------------------
-# content copy-tree
-# ---------------------------------------------------------------------------
-
-
-@content_app.command("copy-tree")
-def content_copy_tree(
-    ctx: typer.Context,
-    source_page_id: str = typer.Argument(..., help="Source root page ID"),
-    target_page_id: str = typer.Option(..., "--target-page-id", help="Target root page ID"),
-    source_server: str = typer.Option(
-        "external", "--source-server", help="Source Confluence server (internal|external)"
-    ),
-    target_server: str = typer.Option(
-        "internal", "--target-server", help="Target Confluence server (internal|external)"
-    ),
-    source_space: str | None = typer.Option(
-        None, "--source-space", help="Source space key (auto-detected from source page if omitted)"
-    ),
-    target_space: str = typer.Option(..., "--target-space", help="Target space key"),
-    skip_attachments: bool = typer.Option(False, "--skip-attachments", help="Skip attachment copy"),
-    skip_labels: bool = typer.Option(False, "--skip-labels", help="Skip label copy"),
-    skip_link_remap: bool = typer.Option(False, "--skip-link-remap", help="Skip link remapping"),
-    max_depth: int | None = typer.Option(None, "--max-depth", help="Max BFS depth (0=root only; max: 100)"),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Report what would be copied without writing"),
-) -> None:
-    """Copy a Confluence page tree from one space/server to another."""
-    parent_ctx = _parent_context(ctx)
-    if max_depth is not None and max_depth > 100:
-        raise typer.BadParameter("--max-depth cannot exceed 100 (NFR-05)")
-    started_at = datetime.now(UTC)
-    source_server_key: str = ""
-    try:
-        settings = load_settings(strict=True)
-        source_server_key = _normalise_server(source_server, settings)
-        target_server_key = _normalise_server(target_server, settings)
-        source_client = ContentClient(_build_http_client(settings, source_server_key))
-        target_client = ContentClient(_build_http_client(settings, target_server_key))
-        if source_space:
-            resolved_source_space = source_space
-        else:
-            src_page = source_client.get_page(source_page_id, expand=["space"])
-            space_info = src_page.get("space")
-            if not isinstance(space_info, dict) or not space_info.get("key"):
-                raise VDSClientError(
-                    f"Cannot determine source space key from page {source_page_id}. Pass --source-space explicitly.",
-                    context={"source_page_id": source_page_id},
-                )
-            resolved_source_space = str(space_info["key"])
-        options = CopyOptions(
-            skip_attachments=skip_attachments,
-            skip_labels=skip_labels,
-            skip_link_remap=skip_link_remap,
-            dry_run=dry_run,
-            max_depth=max_depth,
-        )
-        copier = TreeCopier(source_client, target_client, target_space, resolved_source_space, options)
-        result = copier.copy_tree(source_page_id, target_page_id)
-        _emit_json(asdict(result))
-    except Exception as exc:
-        logger.exception("content.copy-tree failed", extra={"source_page_id": source_page_id})
-        typer.echo(f"Error: {exc}", err=True)
-        raise typer.Exit(code=1) from None
-    else:
-        finished_at = datetime.now(UTC)
-        _record_summary(
-            parent_ctx,
-            command="content.copy-tree",
-            args=[source_page_id, f"target={target_page_id}", f"target_space={target_space}"],
-            server=source_server_key,
-            exit_code=0,
-            started_at=started_at,
-            finished_at=finished_at,
-        )
-
-
-if __name__ == "__main__":
-    app()