tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/goals.py

@@ -0,0 +1,1144 @@
+"""Pure async operations for the goals API."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient, TetraClientError
+from tetra_cli.registry import arg, operation, opt
+
+# Mapping of status labels (case-insensitive, whitespace-tolerant) to the
+# numeric values defined in ``tetra.core.core.Status``. Kept here — inside the
+# op layer — so both the CLI and the MCP surface (both generated from these
+# ops) inherit the same label→int normalization. The previous CLI-only sugar
+# (removed when the goals group moved to the generator) used this exact map.
+_STATUS_LABELS: dict[str, int] = {
+    "created": 1,
+    "in_progress": 2,
+    "archived": 3,
+    "abandoned": 4,
+    "completed": 5,
+}
+
+
+def _normalize_status(value: int | str) -> int:
+    """Coerce a status given as an int or a known label string to its int.
+
+    Accepts plain ints (1-5) unchanged, integer-as-string ("3"), and the
+    canonical labels (case-insensitive, whitespace-tolerant). Raises
+    ``TetraClientError`` — the same error type ops raise for bad input, which
+    the CLI generator renders as a clean ``api_error`` — on an unknown label.
+    """
+    if isinstance(value, int):
+        return value
+    raw = value.strip()
+    if raw.lstrip("-").isdigit():
+        return int(raw)
+    label = raw.lower()
+    if label in _STATUS_LABELS:
+        return _STATUS_LABELS[label]
+    accepted = ", ".join(sorted(_STATUS_LABELS))
+    raise TetraClientError(
+        f"--status {value!r} is not recognized; accepted: {accepted}"
+    )
+
+
+@operation(
+    cli="goals list",
+    summary="List all goals with their hierarchy and status.",
+    covers=[("GET", "/api/v1/goals/")],
+)
+async def list_goals(client: TetraClient) -> dict[str, Any]:
+    """List all goals with their hierarchy and status.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'goals' list
+    """
+    return await client.get("/api/v1/goals/")
+
+
+@operation(
+    cli="goals get",
+    summary="Get a single goal by UID or hierarchical name.",
+    covers=[("GET", "/api/v1/goals/{uid_or_name}")],
+    params={"uid_or_name": arg(help="Goal UID or full hierarchical name")},
+)
+async def get_goal(client: TetraClient, uid_or_name: str) -> dict[str, Any]:
+    """Get a single goal by UID or hierarchical name.
+
+    Args:
+        client: Authenticated TetraClient
+        uid_or_name: Goal UID or full hierarchical name (e.g., 'Exercise > Weight Training')
+
+    Returns:
+        Goal dict
+    """
+    return await client.get(f"/api/v1/goals/{uid_or_name}")
+
+
+@operation(
+    cli="goals create",
+    summary="Create a new goal.",
+    covers=[("POST", "/api/v1/goals/")],
+    params={
+        "name": arg(help="Leaf name (e.g. 'Bench Press')"),
+        "values": opt("--value", repeatable=True, help="Value name (repeatable)"),
+        "depends_on": opt("--depends-on", repeatable=True,
+                          help="Prerequisite goal name (repeatable)"),
+        "outcome_names": opt("--outcome-name", repeatable=True,
+                             help="Record-outcome field name (repeatable)"),
+        "metric_config": opt("--metric-config", json=True,
+                             help="Metric configuration as a JSON dict"),
+        "importance": opt("--importance", min=1, max=5, help="Importance (1-5)"),
+        "urgency": opt("--urgency", min=1, max=5, help="Urgency (1-5)"),
+        "expected_time": opt("--expected-time",
+                             help="Expected time to complete, in seconds"),
+    },
+)
+async def create_goal(
+    client: TetraClient,
+    *,
+    name: str,
+    parent: str | None = None,
+    values: list[str] | None = None,
+    depends_on: list[str] | None = None,
+    description: str | None = None,
+    importance: int | None = None,
+    urgency: int | None = None,
+    expected_time: int | None = None,
+    metric_config: dict[str, Any] | None = None,
+    outcome_shape: str | None = None,
+    outcome_names: list[str] | None = None,
+    group_uid: str | None = None,
+    for_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Create a new goal.
+
+    Only the fields explicitly provided are included in the request body;
+    optional fields that are None are omitted so API defaults apply.
+
+    Args:
+        client: Authenticated TetraClient
+        name: Leaf name for the goal (e.g., 'Bench Press')
+        parent: Parent goal's full hierarchical name
+        values: Value names this goal contributes to
+        depends_on: Names of prerequisite goals that must complete first
+        description: Human-readable description
+        importance: Importance level (1-5)
+        urgency: Urgency level (1-5)
+        expected_time: Expected time to complete the goal, in seconds.
+        metric_config: Custom metric configuration dict
+        outcome_shape: Shape of outcome data ('numeric', 'record', etc.)
+        outcome_names: Field names for record-type outcomes
+
+    Returns:
+        Created goal dict with assigned UID
+    """
+    body: dict[str, Any] = {"name": name}
+    if parent:
+        body["parent"] = parent
+    if values:
+        body["values"] = values
+    if depends_on:
+        body["depends_on"] = depends_on
+    if description:
+        body["description"] = description
+    if importance is not None:
+        body["importance"] = importance
+    if urgency is not None:
+        body["urgency"] = urgency
+    if expected_time is not None:
+        body["expected_time"] = expected_time
+    if metric_config:
+        body["metric_config"] = metric_config
+    if outcome_shape:
+        body["outcome_shape"] = outcome_shape
+    if outcome_names:
+        body["outcome_names"] = outcome_names
+    # Creation context — pair (group_uid, for_account_uid) picks shape
+    # A/B/C per docs/architecture/creation-context.md.
+    if group_uid is not None:
+        body["group_uid"] = group_uid
+    if for_account_uid is not None:
+        body["for_account_uid"] = for_account_uid
+    return await client.post("/api/v1/goals/", json=body)
+
+
+@operation(
+    cli="goals update",
+    summary="Update an existing goal. Only provided fields are changed.",
+    covers=[("PUT", "/api/v1/goals/{uid}")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "name": opt("--name", help="New leaf name"),
+        "values": opt("--value", repeatable=True, clears=True,
+                      help="Value name (repeatable; replaces all)"),
+        "depends_on": opt("--depends-on", repeatable=True, clears=True,
+                          help="Prerequisite goal name (repeatable; replaces all)"),
+        "metric_config": opt("--metric-config", json=True,
+                             help="Metric configuration as a JSON dict"),
+        "outcome_names": opt("--outcome-name", repeatable=True,
+                             help="Record-outcome field name (repeatable)"),
+        "importance": opt("--importance", min=1, max=5, help="Importance (1-5)"),
+        "urgency": opt("--urgency", min=1, max=5, help="Urgency (1-5)"),
+        "expected_time": opt("--expected-time",
+                             help="Expected time to complete, in seconds"),
+        "status": opt(
+            "--status",
+            help=("Goal status as a label (created | in_progress | archived | "
+                  "abandoned | completed) or its numeric form (1-5)."),
+        ),
+    },
+)
+async def update_goal(
+    client: TetraClient,
+    *,
+    uid: str,
+    name: str | None = None,
+    parent: str | None = None,
+    description: str | None = None,
+    importance: int | None = None,
+    urgency: int | None = None,
+    expected_time: int | None = None,
+    values: list[str] | None = None,
+    depends_on: list[str] | None = None,
+    metric_config: dict[str, Any] | None = None,
+    outcome_shape: str | None = None,
+    outcome_names: list[str] | None = None,
+    status: str | None = None,
+) -> dict[str, Any]:
+    """Update an existing goal. Only provided (non-None) fields are changed.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID (required)
+        name: New leaf name
+        parent: New parent path (empty string to move to root)
+        description: New description
+        importance: New importance (1-5)
+        urgency: New urgency (1-5)
+        expected_time: New expected time to complete, in seconds.
+        values: New value names (replaces all)
+        depends_on: New prerequisite goal names (replaces all)
+        metric_config: New metric configuration
+        outcome_shape: New outcome shape
+        outcome_names: New outcome field names
+        status: New status as either a numeric value (1=CREATED,
+            2=IN_PROGRESS, 3=ARCHIVED, 4=ABANDONED, 5=COMPLETED) or a label
+            string ("created" … "completed", case-insensitive). The op
+            normalizes labels→int so the CLI/MCP surfaces share the behavior.
+
+    Returns:
+        Updated goal dict
+
+    Raises:
+        TetraClientError: If ``status`` is a string that is neither a known
+            label nor a numeric value.
+    """
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if parent is not None:
+        body["parent"] = parent
+    if description is not None:
+        body["description"] = description
+    if importance is not None:
+        body["importance"] = importance
+    if urgency is not None:
+        body["urgency"] = urgency
+    if expected_time is not None:
+        body["expected_time"] = expected_time
+    if values is not None:
+        body["values"] = values
+    if depends_on is not None:
+        body["depends_on"] = depends_on
+    if metric_config is not None:
+        body["metric_config"] = metric_config
+    if outcome_shape is not None:
+        body["outcome_shape"] = outcome_shape
+    if outcome_names is not None:
+        body["outcome_names"] = outcome_names
+    if status is not None:
+        body["status"] = _normalize_status(status)
+    return await client.put(f"/api/v1/goals/{uid}", json=body)
+
+
+@operation(
+    cli="goals delete",
+    summary="Delete a goal permanently.",
+    covers=[("DELETE", "/api/v1/goals/{uid}")],
+    params={"uid": arg(help="Goal UID to delete")},
+)
+async def delete_goal(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Delete a goal permanently.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID to delete
+
+    Returns:
+        Deletion confirmation dict
+    """
+    return await client.delete(f"/api/v1/goals/{uid}")
+
+
+@operation(
+    cli="goals status",
+    summary="Get achievement progress and status for a goal.",
+    covers=[("GET", "/api/v1/goals/{uid}/status")],
+    params={"uid": arg(help="Goal UID")},
+)
+async def get_goal_status(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Get achievement progress and status for a goal.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID
+
+    Returns:
+        Dict with status, percentage, current_value, target, and metric_type
+    """
+    return await client.get(f"/api/v1/goals/{uid}/status")
+
+
+@operation(
+    cli="goals rankings",
+    summary="Get all goals ranked by progress, tier, and achievement status.",
+    covers=[("GET", "/api/v1/goals/rankings")],
+)
+async def get_goal_rankings(client: TetraClient) -> dict[str, Any]:
+    """Get all goals ranked by progress, tier, and achievement status.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'rankings' list of goals sorted by progress
+    """
+    return await client.get("/api/v1/goals/rankings")
+
+
+@operation(
+    cli="goals metrics",
+    summary="List all metrics for a goal (active + archived history).",
+    covers=[("GET", "/api/v1/goals/{uid}/metrics")],
+    params={"goal_uid": arg(help="Goal UID")},
+)
+async def list_goal_metrics(
+    client: TetraClient, goal_uid: str,
+) -> list[dict[str, Any]]:
+    """List all metrics for a goal (active + archived).
+
+    Reading metrics before adding new ones prevents accidental duplication.
+    Each metric exposes ``is_active`` (True for the current one) and the
+    full ``metric_config`` so an agent can summarize the existing rule.
+
+    Args:
+        client: Authenticated TetraClient
+        goal_uid: Goal UID
+
+    Returns:
+        List of metric dicts ordered by creation. Empty list if none.
+    """
+    return await client.get(f"/api/v1/goals/{goal_uid}/metrics")
+
+
+@operation(
+    cli="goals metric-active",
+    summary="Get the single active metric for a goal (null if none).",
+    covers=[("GET", "/api/v1/goals/{uid}/metrics/active")],
+    params={"goal_uid": arg(help="Goal UID")},
+)
+async def get_active_goal_metric(
+    client: TetraClient, goal_uid: str,
+) -> dict[str, Any] | None:
+    """Return the single active metric for a goal, or None if there is none.
+
+    The active-metric endpoint returns ``null`` (not 404) when no active
+    metric exists, so this is safe to call before deciding whether to
+    create one.
+    """
+    return await client.get(f"/api/v1/goals/{goal_uid}/metrics/active")
+
+
+@operation(
+    cli="goals metric-create",
+    summary="Create a new metric for a goal (archives the current active one).",
+    covers=[("POST", "/api/v1/goals/{uid}/metrics")],
+    params={
+        "goal_uid": arg(help="Goal UID"),
+        "metric_config": opt("--metric-config", json=True,
+                             help="MetricConfig payload as a JSON dict"),
+        "tier_override": opt("--tier-override", choices=["D", "C", "B", "A"],
+                             help="Optional user-set difficulty tier (D/C/B/A)."),
+    },
+)
+async def create_goal_metric(
+    client: TetraClient,
+    goal_uid: str,
+    *,
+    name: str,
+    metric_config: dict[str, Any],
+    tier_override: str | None = None,
+) -> dict[str, Any]:
+    """Create a new metric for a goal.
+
+    Creating a metric automatically archives any currently-active metric
+    on the goal — there is at most one active metric at any time.
+
+    The server derives the computed tier from metric semantics and
+    cumulative effort. Pass ``tier_override`` to mark the goal as harder
+    than the metric suggests — accepted values are D/C/B/A. S is rejected
+    because reaching it requires the globally-shared-goal + top-decile
+    gate, not opt-in.
+
+    Args:
+        client: Authenticated TetraClient
+        goal_uid: Goal UID
+        name: Human-readable metric name (e.g. "Quarterly call")
+        metric_config: ``MetricConfig`` payload — see docs/architecture/rules-spec.md
+        tier_override: Optional user-set tier (D/C/B/A).
+    """
+    body: dict[str, Any] = {"name": name, "metric_config": metric_config}
+    if tier_override is not None:
+        body["tier_override"] = tier_override
+    return await client.post(f"/api/v1/goals/{goal_uid}/metrics", json=body)
+
+
+# Sentinel for "field not provided" so callers can distinguish leaving
+# tier_override alone from clearing it (passing None).
+_UNSET: Any = object()
+
+
+@operation(
+    cli="goals metric-update",
+    summary="Update an existing goal metric (name, config, tier, or activate).",
+    covers=[("PUT", "/api/v1/goals/{uid}/metrics/{metric_uid}")],
+    params={
+        "goal_uid": arg(help="Goal UID"),
+        "metric_uid": arg(help="Metric UID"),
+        "metric_config": opt("--metric-config", json=True,
+                             help="MetricConfig payload as a JSON dict"),
+        "tier_override": opt("--tier-override", choices=["D", "C", "B", "A"],
+                             help="Set the user difficulty tier (D/C/B/A)."),
+    },
+)
+async def update_goal_metric(
+    client: TetraClient,
+    goal_uid: str,
+    metric_uid: str,
+    *,
+    name: str | None = None,
+    metric_config: dict[str, Any] | None = None,
+    tier_override: Any = _UNSET,
+    activate: bool | None = None,
+) -> dict[str, Any]:
+    """Update an existing goal metric.
+
+    ``activate=True`` makes this metric active (archiving the previously
+    active one). Pass any subset of fields you want to change.
+
+    Pass ``tier_override`` to set the user override (D/C/B/A) or
+    explicitly ``None`` to clear it; omit it to leave the existing
+    override untouched. The server still computes the underlying tier
+    from metric semantics — override is a display/XP overlay.
+    """
+    body: dict[str, Any] = {}
+    if name is not None:
+        body["name"] = name
+    if metric_config is not None:
+        body["metric_config"] = metric_config
+    if tier_override is not _UNSET:
+        body["tier_override"] = tier_override
+    if activate is not None:
+        body["activate"] = activate
+    return await client.put(
+        f"/api/v1/goals/{goal_uid}/metrics/{metric_uid}", json=body,
+    )
+
+
+async def delete_goal_metric(
+    client: TetraClient, goal_uid: str, metric_uid: str,
+) -> dict[str, Any]:
+    """Permanently delete a goal metric."""
+    return await client.delete(
+        f"/api/v1/goals/{goal_uid}/metrics/{metric_uid}",
+    )
+
+
+@operation(
+    cli="goals move",
+    summary="Move a goal to a new parent and/or position in the sibling order.",
+    covers=[("POST", "/api/v1/goals/move")],
+    params={
+        "uid": arg(help="Goal UID to move"),
+        "new_parent": opt("--new-parent",
+                          help="New parent goal name (omit to keep current)."),
+        "new_priority": opt("--priority", min=1,
+                            help="New priority among siblings (1 = top)."),
+    },
+)
+async def move_goal(
+    client: TetraClient,
+    *,
+    uid: str,
+    new_parent: str | None = None,
+    new_priority: int | None = None,
+) -> dict[str, Any]:
+    """Move a goal to a new parent and/or position in the sibling order.
+
+    The API treats ``new_parent: null`` as "promote to root" — there is no
+    "keep current parent" sentinel on the wire. So when the caller only
+    wants to reorder (priority change, no parent change), this helper
+    fetches the goal first and forwards its current parent so the route
+    doesn't accidentally promote it to root.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID to move
+        new_parent: New parent goal name. Omit to keep current parent.
+            Pass an empty string ``""`` to explicitly promote to root.
+        new_priority: Target priority among siblings (1 = top). The API
+            normalizes neighboring siblings atomically.
+
+    Returns:
+        Move result with ``uid``, ``name``, ``parent``, ``priority``,
+        ``siblings_updated``.
+    """
+    body: dict[str, Any] = {"uid": uid}
+    if new_parent is None:
+        # Caller didn't specify — pre-fetch and use current parent so the
+        # API doesn't interpret missing as "move to root."
+        current = await client.get(f"/api/v1/goals/{uid}")
+        if current.get("parent"):
+            body["new_parent"] = current["parent"]
+        # else: goal is already a root, omit new_parent (API treats omitted
+        # the same as null = root, which is correct in this case).
+    elif new_parent == "":
+        # Explicit root promotion: send null on the wire.
+        body["new_parent"] = None
+    else:
+        body["new_parent"] = new_parent
+    if new_priority is not None:
+        body["new_priority"] = new_priority
+    return await client.post("/api/v1/goals/move", json=body)
+
+
+@operation(
+    cli="goals batch-delete",
+    summary="Soft-delete multiple goals at once (archived for restore).",
+    covers=[("POST", "/api/v1/goals/batch-delete")],
+    params={
+        "uids": opt("--uid", repeatable=True, help="Goal UID to delete (repeatable)."),
+    },
+)
+async def batch_delete_goals(
+    client: TetraClient,
+    *,
+    uids: list[str],
+    delete_children: bool = False,
+    delete_events: bool = False,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """Soft-delete multiple goals at once.
+
+    Each goal is archived for potential restoration. Children and events are
+    either deleted alongside the goal or have their references cleared,
+    depending on the flags.
+
+    Args:
+        client: Authenticated TetraClient
+        uids: Goal UIDs to delete
+        delete_children: If True, delete child goals; else clear their parent.
+        delete_events: If True, delete events; else remove the goal from them.
+        reason: Optional human-readable reason recorded with the deletion.
+
+    Returns:
+        Dict with ``deleted`` (list of UIDs) and ``failed`` (list of errors).
+    """
+    body: dict[str, Any] = {
+        "uids": uids,
+        "delete_children": delete_children,
+        "delete_events": delete_events,
+    }
+    if reason is not None:
+        body["reason"] = reason
+    return await client.post("/api/v1/goals/batch-delete", json=body)
+
+
+@operation(
+    cli="goals batch-priorities",
+    summary="Batch-reorder goals within a sibling group.",
+    covers=[("POST", "/api/v1/goals/batch-update-priorities")],
+    params={
+        "updates": opt("--updates", json=True,
+                       help="JSON map of {goal_uid: new_priority} (1-based, sequential)."),
+        "parent": opt("--parent", help="Parent goal name (omit for root siblings)."),
+    },
+)
+async def batch_update_goal_priorities(
+    client: TetraClient,
+    *,
+    updates: dict[str, int],
+    parent: str | None = None,
+) -> dict[str, Any]:
+    """Batch-update priorities for goals within one sibling group.
+
+    All goals must share the same parent. Priorities must be sequential
+    starting from 1 (the server validates this).
+
+    Args:
+        client: Authenticated TetraClient
+        updates: Map of ``{goal_uid: new_priority}`` (1 = top).
+        parent: Parent goal name (null/omit for root-level siblings).
+
+    Returns:
+        Dict with ``updated`` count and the affected ``uids``.
+    """
+    body: dict[str, Any] = {"updates": updates}
+    if parent is not None:
+        body["parent"] = parent
+    return await client.post("/api/v1/goals/batch-update-priorities", json=body)
+
+
+@operation(
+    cli="goals merge",
+    summary="Merge multiple goals into a new goal, reassigning their events.",
+    covers=[("POST", "/api/v1/goals/merge")],
+    params={
+        "source_uids": opt("--source-uid", repeatable=True,
+                           help="Source goal UID to merge (repeatable; 2+ required)."),
+        "new_goal": opt("--new-goal", json=True,
+                        help="New goal data as a JSON dict (at least {\"name\": ...})."),
+    },
+)
+async def merge_goals(
+    client: TetraClient,
+    *,
+    source_uids: list[str],
+    new_goal: dict[str, Any],
+) -> dict[str, Any]:
+    """Merge two or more goals into a new goal.
+
+    Events from all source goals are reassigned to the new goal, and the
+    source goals are soft-deleted after the merge.
+
+    Args:
+        client: Authenticated TetraClient
+        source_uids: UIDs of the goals to merge (at least 2).
+        new_goal: New goal payload (must include ``name``; may include
+            ``parent``, ``values``, etc.).
+
+    Returns:
+        The created goal dict.
+    """
+    body: dict[str, Any] = {"source_uids": source_uids, "new_goal": new_goal}
+    return await client.post("/api/v1/goals/merge", json=body)
+
+
+@operation(
+    cli="goals status-all",
+    summary="Get achievement status for all goals (two-phase: cached + pending).",
+    covers=[("GET", "/api/v1/goals/status/all")],
+    params={
+        "as_of": opt("--as-of", help="Status as of this date (YYYY-MM-DD) or ISO datetime."),
+        "group_uid": opt("--group-uid", help="Group UID (omit for personal goals)."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a specific member's status (needs group_uid)."),
+    },
+)
+async def get_all_goals_status(
+    client: TetraClient,
+    *,
+    as_of: str | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get achievement status for all goals.
+
+    Returns cached statuses immediately plus a list of pending goal UIDs
+    whose status is being recalculated in the background.
+
+    Args:
+        client: Authenticated TetraClient
+        as_of: Optional point-in-time for the calculation.
+        group_uid: Optional group scope (omit for personal goals).
+        target_account_uid: Optional member to view (requires group_uid).
+
+    Returns:
+        Dict with ``statuses``, ``pending_goal_uids``, and ``calculation_id``.
+    """
+    params: dict[str, Any] = {}
+    if as_of is not None:
+        params["as_of"] = as_of
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/goals/status/all", params=params or None)
+
+
+@operation(
+    cli="goals status-recalculate",
+    summary="Clear the goal status cache and recalculate all goal statuses.",
+    covers=[("POST", "/api/v1/goals/status/recalculate")],
+    params={
+        "as_of": opt("--as-of", help="Recalculate as of this date/datetime (default now)."),
+    },
+)
+async def recalculate_all_goals(
+    client: TetraClient,
+    *,
+    as_of: str | None = None,
+) -> dict[str, Any]:
+    """Clear all goal status cache and recalculate every goal's status.
+
+    Args:
+        client: Authenticated TetraClient
+        as_of: Optional point-in-time for the recalculation (default: now).
+
+    Returns:
+        Dict with ``cache_cleared`` and ``goals_recalculated`` counts.
+    """
+    params: dict[str, Any] = {}
+    if as_of is not None:
+        params["as_of"] = as_of
+    return await client.post(
+        "/api/v1/goals/status/recalculate"
+        + ("?" + "&".join(f"{k}={v}" for k, v in params.items()) if params else ""),
+    )
+
+
+@operation(
+    cli="goals children",
+    summary="Get the direct child goals of a goal.",
+    covers=[("GET", "/api/v1/goals/{uid}/children")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+    },
+)
+async def get_goal_children(
+    client: TetraClient,
+    uid: str,
+    *,
+    group_uid: str | None = None,
+) -> list[dict[str, Any]]:
+    """Get the direct children of a goal.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Parent goal UID.
+        group_uid: Optional group scope.
+
+    Returns:
+        List of child goal dicts.
+    """
+    params: dict[str, Any] = {}
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    return await client.get(
+        f"/api/v1/goals/{uid}/children", params=params or None,
+    )
+
+
+@operation(
+    cli="goals completion-status",
+    summary="Check whether a goal can be marked complete (lists blockers).",
+    covers=[("GET", "/api/v1/goals/{uid}/completion-status")],
+    params={"uid": arg(help="Goal UID")},
+)
+async def get_goal_completion_status(
+    client: TetraClient, uid: str,
+) -> dict[str, Any]:
+    """Get a goal's completion status (can it be marked complete?).
+
+    Reports unmet transitive dependencies and unachieved child goals that
+    block completion.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+
+    Returns:
+        Dict with ``can_complete``, ``blocking_dependencies``,
+        ``blocking_children``.
+    """
+    return await client.get(f"/api/v1/goals/{uid}/completion-status")
+
+
+@operation(
+    cli="goals detail-analytics",
+    summary="Get comprehensive analytics for a single goal's detail view.",
+    covers=[("GET", "/api/v1/goals/{uid}/detail-analytics")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a member's analytics (requires mentor permission)."),
+    },
+)
+async def get_goal_detail_analytics(
+    client: TetraClient,
+    uid: str,
+    *,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get comprehensive detail-view analytics for a goal.
+
+    Includes XP history, streaks, summary factoids, consistency heatmap,
+    mood-vs-performance scatter, and missed-reasons word cloud.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        group_uid: Optional group scope.
+        target_account_uid: Optional member to view.
+
+    Returns:
+        Goal detail analytics dict.
+    """
+    params: dict[str, Any] = {}
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/goals/{uid}/detail-analytics", params=params or None,
+    )
+
+
+@operation(
+    cli="goals events",
+    summary="Get paginated events for a goal (with filtering and sorting).",
+    covers=[("GET", "/api/v1/goals/{uid}/events")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "tag_uids": opt("--tag-uid", repeatable=True,
+                        help="Tag UID filter (repeatable; event must match)."),
+        "sort_order": opt("--sort-order", choices=["asc", "desc"],
+                          help="Date sort order (default desc = newest first)."),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a specific member's events."),
+    },
+)
+async def get_goal_events(
+    client: TetraClient,
+    uid: str,
+    *,
+    include_descendants: bool = True,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    tag_uids: list[str] | None = None,
+    search: str | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+    sort_order: str = "desc",
+) -> dict[str, Any]:
+    """Get paginated events for a goal.
+
+    Tag UIDs are sent comma-joined (the backend splits on commas and treats
+    them as an AND filter expanded to descendants).
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        include_descendants: Include events from child goals (default True).
+        group_uid: Optional group scope.
+        target_account_uid: Optional member whose events to show.
+        limit: Max events per page (1-500, default 50).
+        offset: Events to skip (default 0).
+        tag_uids: Tag UID filters (event must have all).
+        search: Case-insensitive description search.
+        date_from: Inclusive start date (YYYY-MM-DD).
+        date_to: Inclusive end date (YYYY-MM-DD).
+        sort_order: ``asc`` or ``desc`` (default ``desc``).
+
+    Returns:
+        Dict with ``items``, ``has_more``, ``offset``, ``limit``.
+    """
+    params: dict[str, Any] = {
+        "include_descendants": include_descendants,
+        "limit": limit,
+        "offset": offset,
+        "sort_order": sort_order,
+    }
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    if tag_uids:
+        params["tag_uids"] = ",".join(tag_uids)
+    if search is not None:
+        params["search"] = search
+    if date_from is not None:
+        params["date_from"] = date_from
+    if date_to is not None:
+        params["date_to"] = date_to
+    return await client.get(f"/api/v1/goals/{uid}/events", params=params)
+
+
+@operation(
+    cli="goals progress-history",
+    summary="Get a goal's progress snapshots over time (for charting).",
+    covers=[("GET", "/api/v1/goals/{uid}/progress-history")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "metric_config": opt("--metric-config", json=True,
+                             help="Override MetricConfig as a JSON dict (else the active one)."),
+        "tuple_fields": opt("--tuple-field", repeatable=True,
+                            help="Field name for tuple outcomes (repeatable)."),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a member's progress history."),
+    },
+)
+async def get_goal_progress_history(
+    client: TetraClient,
+    uid: str,
+    *,
+    start: str | None = None,
+    end: str | None = None,
+    metric_config: dict[str, Any] | None = None,
+    tuple_fields: list[str] | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get progress history for a goal at each event date.
+
+    The backend takes ``metric_config`` and ``tuple_fields`` as encoded query
+    params (JSON string and comma-joined list, respectively), so this op
+    serializes them before sending.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        start: Inclusive start datetime (ISO).
+        end: Inclusive end datetime (ISO).
+        metric_config: Optional metric config override (else the goal's active).
+        tuple_fields: Field names for tuple outcomes.
+        group_uid: Optional group scope.
+        target_account_uid: Optional member to view.
+
+    Returns:
+        Dict with ``goal_uid`` and ``points`` (progress snapshots).
+    """
+    import json as _json
+
+    params: dict[str, Any] = {}
+    if start is not None:
+        params["start"] = start
+    if end is not None:
+        params["end"] = end
+    if metric_config is not None:
+        params["metric_config"] = _json.dumps(metric_config)
+    if tuple_fields:
+        params["tuple_fields"] = ",".join(tuple_fields)
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/goals/{uid}/progress-history", params=params or None,
+    )
+
+
+@operation(
+    cli="goals time-history",
+    summary="Get time/count-per-period aggregation history for a goal's events.",
+    covers=[("GET", "/api/v1/goals/{uid}/time-history")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a member's time history."),
+    },
+)
+async def get_goal_time_history(
+    client: TetraClient,
+    uid: str,
+    *,
+    start: str | None = None,
+    end: str | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get time-based aggregation history for a goal's events.
+
+    Returns duration-per-period or event-count-per-period data, used as a
+    fallback chart on goal detail when the goal has no metric.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        start: Inclusive start date (YYYY-MM-DD).
+        end: Inclusive end date (YYYY-MM-DD).
+        group_uid: Optional group scope.
+        target_account_uid: Optional member to view.
+
+    Returns:
+        Time history aggregation dict.
+    """
+    params: dict[str, Any] = {}
+    if start is not None:
+        params["start"] = start
+    if end is not None:
+        params["end"] = end
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/goals/{uid}/time-history", params=params or None,
+    )
+
+
+@operation(
+    cli="goals week-events",
+    summary="Get this-week and last-week events for a goal, with summaries.",
+    covers=[("GET", "/api/v1/goals/{uid}/week-events")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a member's week events."),
+    },
+)
+async def get_goal_week_events(
+    client: TetraClient,
+    uid: str,
+    *,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get this-week and last-week events for a goal, with summaries.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        group_uid: Optional group scope.
+        target_account_uid: Optional member to view.
+
+    Returns:
+        Dict with this-week/last-week event lists and summaries.
+    """
+    params: dict[str, Any] = {}
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/goals/{uid}/week-events", params=params or None,
+    )
+
+
+@operation(
+    cli="goals status-stages",
+    summary="Get the stage-by-stage breakdown of a goal's status calculation.",
+    covers=[("GET", "/api/v1/goals/{uid}/status/stages")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "as_of": opt("--as-of", help="Compute as of this date (YYYY-MM-DD) or ISO datetime."),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+    },
+)
+async def get_goal_status_stages(
+    client: TetraClient,
+    uid: str,
+    *,
+    as_of: str | None = None,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get the stage-by-stage breakdown of a goal's status calculation.
+
+    Only stage-based metric types (count, duration, money, outcome,
+    moneytime) produce stages; other types return an empty stages list.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        as_of: Optional point-in-time for the calculation.
+        group_uid: Optional group scope.
+
+    Returns:
+        Dict with ``stages``, ``achieved``, ``actual``, ``target``.
+    """
+    params: dict[str, Any] = {}
+    if as_of is not None:
+        params["as_of"] = as_of
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    return await client.get(
+        f"/api/v1/goals/{uid}/status/stages", params=params or None,
+    )
+
+
+@operation(
+    cli="goals rename-field",
+    summary="Rename a record/tuple field on a goal and all its events.",
+    covers=[("POST", "/api/v1/goals/{uid}/rename-field")],
+    params={
+        "uid": arg(help="Goal UID"),
+        "old_name": opt("--old-name", help="Current field name to rename."),
+        "new_name": opt("--new-name", help="New field name."),
+    },
+)
+async def rename_goal_field(
+    client: TetraClient,
+    uid: str,
+    *,
+    old_name: str,
+    new_name: str,
+) -> dict[str, Any]:
+    """Rename a tuple/record field on a goal and across all its events.
+
+    Atomically updates ``goal.outcome_names`` and every event's outcome
+    records so the field name stays consistent.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        old_name: Existing field name.
+        new_name: Replacement field name.
+
+    Returns:
+        Dict with ``success``, ``events_updated``, and the new
+        ``outcome_names``.
+    """
+    body: dict[str, Any] = {"old_name": old_name, "new_name": new_name}
+    return await client.post(f"/api/v1/goals/{uid}/rename-field", json=body)
+
+
+@operation(
+    cli="goals reorder",
+    summary="Persist the root ordering of the interleaved 'all' goals view.",
+    covers=[("POST", "/api/v1/goals/reorder-all")],
+    params={
+        "order": opt("--uid", repeatable=True,
+                     help="Root goal UID, in top-to-bottom order (repeatable)."),
+    },
+)
+async def reorder_all_goals(
+    client: TetraClient,
+    *,
+    order: list[str],
+) -> dict[str, Any]:
+    """Persist the root ordering of the interleaved "all" goals view.
+
+    Stored as a per-account overlay; canonical per-scope priorities are never
+    touched, so personal and group orders stay independent.
+
+    Args:
+        client: Authenticated TetraClient
+        order: Full top-to-bottom sequence of root goal UIDs across scopes.
+
+    Returns:
+        Dict with ``updated`` (count of overlay rows written).
+    """
+    return await client.post(
+        "/api/v1/goals/reorder-all", json={"order": order}
+    )