crowdtime-cli 0.10.0__tar.gz → 0.12.0__tar.gz

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/.gitignore

@@ -13,6 +13,10 @@ build/
 venv/
 ENV/
 
+# Accidentally-created user/pip caches when pip runs with HOME=repo
+.cache/
+.local/
+
 # Environment
 .env
 
@@ -65,3 +69,4 @@ coolify_deployment.md
 pypi_deployment.md
 sentry-workflow.md
 linear-workflow.md
+seeds-mentores.md

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.10.0
+Version: 0.12.0
 Summary: AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest
 Project-URL: Homepage, https://crowdtime.lat
 Project-URL: Documentation, https://crowdtime.lat/docs

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.10.0"
+version = "0.12.0"
 description = "AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest"
 readme = "README.md"
 license = {text = "Proprietary"}

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/src/crowdtime_cli/__init__.py

@@ -1,3 +1,3 @@
 """CrowdTime CLI - AI-powered time tracking from the command line."""
 
-__version__ = "0.10.0"
+__version__ = "0.12.0"

crowdtime_cli-0.12.0/src/crowdtime_cli/commands/team_cmd.py

@@ -0,0 +1,415 @@
+"""Team commands: manage manager → direct-report assignments.
+
+Mirrors Harvest's manager model. Admins assign members as direct reports
+to a manager; the manager can see those members' hours across any project
+without being added as a PM to each project individually.
+
+Bulk operations use the delta-based ``/manager-assignments/bulk-set/``
+endpoint — the client computes ``add`` and ``remove`` sets, keeping
+concurrent edits from clobbering each other.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import APIError, CrowdTimeClient
+from ..formatters import extract_results, format_error, format_success, print_json
+
+app = typer.Typer(name="team", help="Manage direct-report assignments.")
+console = Console()
+
+
+def _members_list(client: CrowdTimeClient) -> list[dict]:
+    data = client.get("/members/")
+    return extract_results(data)
+
+
+def _resolve_membership(client: CrowdTimeClient, ref: str, *, members: Optional[list[dict]] = None) -> dict:
+    """Resolve a membership by email, user UUID, or membership UUID.
+
+    Accepts an optional pre-fetched ``members`` list to avoid repeat HTTP
+    calls when resolving many refs at once.
+    """
+    members = members or _members_list(client)
+    ref_lower = ref.lower()
+    for m in members:
+        if (m.get("user", {}).get("email") or "").lower() == ref_lower:
+            return m
+    for m in members:
+        if m.get("id") == ref:
+            return m
+    for m in members:
+        if m.get("user", {}).get("id") == ref:
+            return m
+    raise APIError(
+        f"No member found matching '{ref}'. Use email, user ID, or membership ID.",
+        status_code=404,
+    )
+
+
+def _current_direct_report_ids(client: CrowdTimeClient, manager_id: str) -> set[str]:
+    """Return the set of membership IDs currently assigned to ``manager_id``."""
+    data = client.get("/manager-assignments/", params={"manager": manager_id})
+    rows = extract_results(data)
+    return {row["member"] for row in rows}
+
+
+def _render_bulk_result(result: dict, *, members_by_id: dict[str, dict]) -> None:
+    """Pretty-print the bulk-set response."""
+    added = result.get("added") or []
+    removed = result.get("removed") or []
+    skipped = result.get("skipped") or {}
+
+    def _label(mid: str) -> str:
+        m = members_by_id.get(mid)
+        if not m:
+            return mid
+        u = m.get("user") or {}
+        return u.get("full_name") or u.get("email") or mid
+
+    if added:
+        console.print(f"[green]+ added[/green]   {', '.join(_label(x) for x in added)}")
+    if removed:
+        console.print(f"[red]- removed[/red] {', '.join(_label(x) for x in removed)}")
+    for bucket_key, color, noun in (
+        ("already_assigned", "dim", "already assigned"),
+        ("not_assigned", "dim", "not assigned"),
+        ("not_in_org", "yellow", "not in org"),
+        ("invalid_role", "yellow", "invalid"),
+    ):
+        items = skipped.get(bucket_key) or []
+        if items:
+            console.print(f"[{color}]· {noun}: {', '.join(_label(x) for x in items)}[/{color}]")
+
+
+def _bulk_set(
+    client: CrowdTimeClient,
+    manager_id: str,
+    *,
+    add: List[str],
+    remove: List[str],
+    members: list[dict],
+    output_json: bool,
+) -> None:
+    """Call the bulk-set endpoint and render the result."""
+    if not add and not remove:
+        console.print("[dim]Nothing to change.[/dim]")
+        return
+    members_by_id = {m["id"]: m for m in members}
+    try:
+        result = client.post("/manager-assignments/bulk-set/", data={
+            "manager": manager_id,
+            "add": add,
+            "remove": remove,
+        })
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+    if output_json:
+        print_json(result)
+        return
+    added_n = len(result.get("added") or [])
+    removed_n = len(result.get("removed") or [])
+    if added_n or removed_n:
+        parts = []
+        if added_n:
+            parts.append(f"{added_n} added")
+        if removed_n:
+            parts.append(f"{removed_n} removed")
+        format_success("; ".join(parts))
+    _render_bulk_result(result, members_by_id=members_by_id)
+
+
+@app.command("assign")
+def assign(
+    manager: str = typer.Argument(..., help="Manager (email, user ID, or membership ID)."),
+    members: Optional[List[str]] = typer.Argument(None, help="One or more members to assign (email, user ID, or membership ID)."),
+    assign_all: bool = typer.Option(False, "--all", help="Assign every active member of the organization."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Assign one or more members as direct reports to a manager.
+
+    Admin+ only. The member's hours become visible to the manager across
+    all projects — no per-project PM assignment needed.
+
+    Examples:
+        ct team assign alice@acme.com bob@acme.com
+        ct team assign alice@acme.com bob@acme.com carol@acme.com dave@acme.com
+        ct team assign alice@acme.com --all
+    """
+    if bool(members) == assign_all:
+        format_error(
+            "Pass one or more members, OR use --all. Not both, not neither."
+            if members and assign_all
+            else "Specify members to assign, or pass --all."
+        )
+        raise typer.Exit(2)
+
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+    try:
+        all_members = _members_list(client)
+        manager_m = _resolve_membership(client, manager, members=all_members)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if assign_all:
+        add_ids = [
+            m["id"] for m in all_members
+            if m.get("is_active", True) and m["id"] != manager_m["id"]
+        ]
+    else:
+        try:
+            resolved = [
+                _resolve_membership(client, ref, members=all_members)
+                for ref in members
+            ]
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+        add_ids = [m["id"] for m in resolved]
+
+    _bulk_set(
+        client, manager_m["id"],
+        add=add_ids, remove=[],
+        members=all_members, output_json=output_json,
+    )
+
+
+@app.command("unassign")
+def unassign(
+    manager: str = typer.Argument(..., help="Manager (email, user ID, or membership ID)."),
+    members: Optional[List[str]] = typer.Argument(None, help="One or more direct reports to remove. Mutually exclusive with --all."),
+    unassign_all: bool = typer.Option(False, "--all", help="Remove every current direct report of this manager."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Remove one or more direct-report assignments from a manager.
+
+    Admin+ only.
+
+    Examples:
+        ct team unassign alice@acme.com bob@acme.com
+        ct team unassign alice@acme.com --all
+    """
+    if bool(members) == unassign_all:
+        format_error(
+            "Pass one or more members, OR use --all. Not both, not neither."
+            if members and unassign_all
+            else "Specify members to unassign, or pass --all."
+        )
+        raise typer.Exit(2)
+
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+    try:
+        all_members = _members_list(client)
+        manager_m = _resolve_membership(client, manager, members=all_members)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if unassign_all:
+        try:
+            remove_ids = list(_current_direct_report_ids(client, manager_m["id"]))
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+    else:
+        try:
+            resolved = [
+                _resolve_membership(client, ref, members=all_members)
+                for ref in members
+            ]
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+        remove_ids = [m["id"] for m in resolved]
+
+    _bulk_set(
+        client, manager_m["id"],
+        add=[], remove=remove_ids,
+        members=all_members, output_json=output_json,
+    )
+
+
+@app.command("set")
+def set_reports(
+    manager: str = typer.Argument(..., help="Manager (email, user ID, or membership ID)."),
+    members: List[str] = typer.Option(
+        [], "--member", "-m",
+        help="Member to include as a direct report. Repeat for each. Pass zero to clear all.",
+    ),
+    all_members: bool = typer.Option(False, "--all", help="Set the direct reports to every active org member."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Declaratively set the full list of direct reports for a manager.
+
+    Computes the diff against the current assignments and applies it in one
+    atomic call. Members not in the list are unassigned; new members are
+    added. Admin+ only.
+
+    Examples:
+        ct team set alice@acme.com --member bob@acme.com --member carol@acme.com
+        ct team set alice@acme.com --all       # replace with every org member
+        ct team set alice@acme.com              # clear all reports (no --member flags)
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        all_active = _members_list(client)
+        manager_m = _resolve_membership(client, manager, members=all_active)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if all_members:
+        if members:
+            format_error("Pass --member or --all, not both.")
+            raise typer.Exit(2)
+        desired = {
+            m["id"] for m in all_active
+            if m.get("is_active", True) and m["id"] != manager_m["id"]
+        }
+    else:
+        try:
+            desired = {
+                _resolve_membership(client, ref, members=all_active)["id"]
+                for ref in members
+            }
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+
+    try:
+        current = _current_direct_report_ids(client, manager_m["id"])
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    add_ids = sorted(desired - current)
+    remove_ids = sorted(current - desired)
+
+    _bulk_set(
+        client, manager_m["id"],
+        add=add_ids, remove=remove_ids,
+        members=all_active, output_json=output_json,
+    )
+
+
+@app.command("list")
+def list_assignments(
+    manager: Optional[str] = typer.Option(None, "--manager", "-m", help="Filter to a manager (ID, user ID, or email)."),
+    member: Optional[str] = typer.Option(None, "--member", help="Filter to a member (ID, user ID, or email)."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List manager→direct-report assignments.
+
+    Admin+ sees all assignments in the org. Other roles see only rows where
+    they are the manager.
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    params: dict = {}
+    try:
+        if manager:
+            m = _resolve_membership(client, manager)
+            params["manager"] = m["id"]
+        if member:
+            m = _resolve_membership(client, member)
+            params["member"] = m["id"]
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    try:
+        data = client.get("/manager-assignments/", params=params)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    rows = extract_results(data)
+
+    if output_json:
+        print_json(rows)
+        return
+
+    if not rows:
+        console.print("[dim]No direct-report assignments.[/dim]")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Assignment ID", style="dim")
+    table.add_column("Manager")
+    table.add_column("Manager Email", style="dim")
+    table.add_column("Direct Report")
+    table.add_column("Report Email", style="dim")
+
+    for row in rows:
+        table.add_row(
+            row.get("id", ""),
+            row.get("manager_name") or "-",
+            row.get("manager_email") or "-",
+            row.get("member_name") or "-",
+            row.get("member_email") or "-",
+        )
+
+    console.print(table)
+
+
+@app.command("reports")
+def reports(
+    manager: Optional[str] = typer.Option(None, "--manager", "-m", help="Manager to list reports for. Defaults to you."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show direct reports of a manager (defaults to the current user).
+
+    Examples:
+        ct team reports
+        ct team reports --manager alice@acme.com
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    params: dict = {}
+    if manager:
+        try:
+            m = _resolve_membership(client, manager)
+            params["manager"] = m["id"]
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+
+    try:
+        data = client.get("/manager-assignments/", params=params)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    rows = extract_results(data)
+
+    if output_json:
+        print_json(rows)
+        return
+
+    if not rows:
+        console.print("[dim]No direct reports.[/dim]")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Direct Report")
+    table.add_column("Email", style="dim")
+    table.add_column("User ID", style="dim")
+    table.add_column("Assignment ID", style="dim")
+
+    for row in rows:
+        table.add_row(
+            row.get("member_name") or "-",
+            row.get("member_email") or "-",
+            row.get("member_user_id") or "-",
+            row.get("id", ""),
+        )
+
+    console.print(table)

crowdtime_cli-0.12.0/src/crowdtime_cli/commands/version_cmd.py

@@ -0,0 +1,57 @@
+"""Version command: show installed and latest CrowdTime CLI versions."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from .. import __version__
+from ..formatters import print_json
+from ..version_check import _parse_simple, get_latest, is_outdated
+
+app = typer.Typer(name="version", help="Show installed and latest CLI versions.")
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def version(
+    ctx: typer.Context,
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show the installed CLI version and the latest published on PyPI.
+
+    Bypasses the 12-hour cache used by the background update check —
+    always fetches the latest version fresh.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    latest = get_latest(force_refresh=True)
+    outdated = is_outdated(__version__, latest)
+    parseable = _parse_simple(__version__) is not None and _parse_simple(latest or "") is not None
+    up_to_date = parseable and not outdated
+
+    if output_json:
+        print_json({
+            "installed": __version__,
+            "latest": latest,
+            "up_to_date": up_to_date if parseable else None,
+            "outdated": outdated,
+        })
+        return
+
+    console.print(f"Installed: [bold]{__version__}[/bold]")
+    if latest is None:
+        console.print("Latest:    [dim](could not reach PyPI)[/dim]")
+    else:
+        console.print(f"Latest:    [bold]{latest}[/bold]")
+
+    if not parseable:
+        console.print("[dim]Unable to compare versions (dev or pre-release build).[/dim]")
+    elif outdated:
+        console.print(
+            f"[yellow]\u26a0 A newer version is available. "
+            f"Run [bold]pip install -U crowdtime-cli[/bold] to upgrade.[/yellow]"
+        )
+    else:
+        console.print("[green]\u2713 You are up to date.[/green]")

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/src/crowdtime_cli/main.py

@@ -36,8 +36,10 @@ from .commands import (
     report_cmd,
     skill_cmd,
     tasks_cmd,
+    team_cmd,
     timesheet_cmd,
     timer_cmd,
+    version_cmd,
 )
 
 console = Console()
@@ -69,6 +71,8 @@ app.add_typer(timesheet_cmd.app, name="timesheet")
 app.add_typer(invoice_cmd.app, name="invoice")
 app.add_typer(expense_cmd.app, name="expense")
 app.add_typer(insights_cmd.app, name="insights")
+app.add_typer(team_cmd.app, name="team")
+app.add_typer(version_cmd.app, name="version")
 
 
 # ─── Status command (default when no subcommand given) ──────────────────────
@@ -398,6 +402,7 @@ def _is_known_command(arg: str) -> bool:
     known = {
         "auth", "billing", "timer", "log", "projects", "clients", "tasks", "report",
         "ai", "org", "config", "favorites", "skill", "timesheet", "invoice", "expense", "payroll",
+        "insights", "team", "version",
         "status", "s", "t", "ts", "tx", "sw", "c", "d", "f", "aliases",
         "l", "ll", "r", "p", "b", "ex", "--help", "-h", "--version", "-v", "--json",
     }
@@ -421,12 +426,56 @@ def _fix_log_routing() -> None:
             sys.argv = [sys.argv[0], "log", "create"] + sys.argv[2:]
 
 
+_SUPPRESS_CHECK_FLAGS = frozenset({"--json", "--version", "-v", "--help", "-h"})
+# Subcommands that either render their own version info or shouldn't be
+# followed by extra stderr chatter.
+_SUPPRESS_CHECK_COMMANDS = frozenset({"version", "aliases"})
+
+
+def _should_run_version_check(original_argv: list[str]) -> bool:
+    """Return True when the post-command update-check hint should run.
+
+    Only real CLI flags are inspected — a quoted positional like
+    ``ct "refactor the --json output"`` must not suppress the check.
+    """
+    argv = original_argv[1:]
+    if not argv:
+        return True
+    for token in argv:
+        # Only treat tokens that look like flags (start with '-') as flags.
+        if token.startswith("-") and token in _SUPPRESS_CHECK_FLAGS:
+            return False
+    if argv[0] in _SUPPRESS_CHECK_COMMANDS:
+        return False
+    # LLM-facing paths: warn text on stderr can confuse agents/tools that
+    # parse `ct` output. `ct ai parse ...` and the magic-routing fallthrough
+    # (unknown first arg → rewritten to `ai parse`) both qualify.
+    if argv[0] == "ai" and len(argv) > 1 and argv[1] == "parse":
+        return False
+    if not argv[0].startswith("-") and not _is_known_command(argv[0]):
+        return False
+    return True
+
+
+def _run_version_check() -> None:
+    """Best-effort update-check. Never raises, never writes to stdout."""
+    try:
+        from .version_check import check_and_warn
+        check_and_warn(Console(stderr=True))
+    except Exception:
+        pass
+
+
 def _original_main() -> None:
     """CLI entry point with magic routing and error handling.
 
     If the first argument is not a known command, treat the entire
     argument string as natural language and route to 'ai parse'.
     """
+    # Snapshot argv *before* magic routing rewrites it, so the version-check
+    # suppression rules see what the user actually typed.
+    original_argv = list(sys.argv)
+
     if len(sys.argv) > 1:
         first_arg = sys.argv[1]
         # If it's not a known command and doesn't start with --, route to ai parse
@@ -436,18 +485,31 @@ def _original_main() -> None:
 
     _fix_log_routing()
 
+    exit_code = 0
     try:
         app()
     except APIError as e:
         format_error(e.message)
-        raise SystemExit(1)
-    except SystemExit:
-        raise
+        exit_code = 1
+    except SystemExit as e:
+        # Python convention: None → 0, int → pass through, anything else
+        # (including str — used by Click/Typer usage errors) → 1.
+        if e.code is None:
+            exit_code = 0
+        elif isinstance(e.code, int):
+            exit_code = e.code
+        else:
+            exit_code = 1
     except KeyboardInterrupt:
-        raise SystemExit(0)
+        exit_code = 0
     except Exception as e:
         format_error(f"Unexpected error: {e}")
-        raise SystemExit(1)
+        exit_code = 1
+
+    if _should_run_version_check(original_argv):
+        _run_version_check()
+
+    raise SystemExit(exit_code)
 
 
 if __name__ == "__main__":

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/src/crowdtime_cli/models.py

@@ -40,9 +40,9 @@ class Project(BaseModel):
     billing_mode: str = "custom"
     status: str = "active"
     is_billable: bool = True
-    budget_type: str = "none"
+    budget_type: str | None = "none"
     budget_amount: Decimal | None = None
-    budget_alert_percent: int = 80
+    budget_alert_percent: int | None = 80
     description: str = ""
     notes: str = ""
 

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -237,7 +237,8 @@ ct favorites delete <id>
 ```bash
 ct timesheet list                       # List your timesheets
 ct timesheet list --status submitted    # Filter by status
-ct timesheet submit --from 2026-03-10 --to 2026-03-16  # Submit for a period
+ct timesheet submit --from 2026-03-10 --to 2026-03-16  # Submit full week
+ct timesheet submit --from 2026-03-30 --to 2026-03-31  # Partial week (end-of-month split)
 ct timesheet recall <id>                # Recall submitted timesheet back to draft (--force to skip confirm)
 ct timesheet approve <id>               # Approve all project portions at once (manager+)
 ct timesheet approve <id> --project <project-id>  # Approve one project's portion (PM for that project)
@@ -363,6 +364,30 @@ ct payroll payments --period 2026-03 --status paid
 
 **Workflow**: Configure compensation → Run liquidation → Approve → Mark paid.
 
+### Team (Direct Reports)
+```bash
+ct team list                                           # All direct-report assignments (admin+) or your own
+ct team list --manager alice@company.com               # Filter to a specific manager
+ct team reports                                        # Show YOUR direct reports
+ct team reports --manager alice@company.com            # Someone else's reports (admin+)
+ct team assign alice@co.com bob@co.com                 # Assign bob as a direct report of alice (admin+)
+ct team assign alice@co.com bob@co.com carol@co.com    # Assign multiple in one call
+ct team assign alice@co.com --all                      # Assign every active org member as her reports
+ct team unassign alice@co.com bob@co.com               # Remove one or more reports (by member, not assignment id)
+ct team unassign alice@co.com --all                    # Clear all her direct reports
+ct team set alice@co.com --member bob@co.com --member carol@co.com  # Declarative: replace the full set
+ct team set alice@co.com                               # Clear all (zero --member flags)
+ct team set alice@co.com --all                         # Set her reports to the full org
+```
+
+All mutating commands (`assign`, `unassign`, `set`) hit the atomic `bulk-set` endpoint — changes apply in a single transaction and the response reports `added` / `removed` / `skipped` buckets.
+
+**Visibility rule**: a `manager` or `project_manager` sees time entries / timesheets / team reports only for users in their visible set, which is the union of:
+1. **Direct reports** — members assigned via `ct team assign`.
+2. **PM-project members** — users of projects where the caller holds `project_role = project_manager`.
+
+A `manager` with **zero** assignments and **zero** PM projects sees only their own entries. `admin` and `owner` always see everything. This is the Harvest-style assignment model: assign *people* to a manager for cross-project visibility, or assign them as a PM on specific projects for project-scoped visibility.
+
 ### Organizations
 ```bash
 ct org list                             # List your organizations
@@ -399,8 +424,18 @@ ct config set server.url https://...    # Set server URL
 ct config set defaults.project myproj   # Set default project
 ct config set defaults.daily_target 7h  # Set daily target
 ct config edit                          # Open in editor
+ct config set update_check.enabled false  # Disable the daily update-check warning
 ```
 
+### Version
+```bash
+ct version                              # Show installed + latest CLI version (hits PyPI)
+ct version --json                       # Machine-readable output
+ct --version                            # Print just the installed version (no network)
+```
+
+The CLI also runs a once-per-12-hours background update check after every command and prints a one-line hint on stderr when a newer version exists. Opt out with `CROWDTIME_NO_VERSION_CHECK=1` or `ct config set update_check.enabled false`.
+
 ## Common Workflows
 
 Read `references/workflows.md` for detailed multi-step workflow patterns including:

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/src/crowdtime_cli/skills/crowdtime/references/commands.md

@@ -23,6 +23,8 @@ Every command, subcommand, argument, flag, and option in the CrowdTime CLI.
 - [ct timesheet](#ct-timesheet)
 - [ct invoice](#ct-invoice)
 - [ct insights](#ct-insights)
+- [ct team](#ct-team)
+- [ct version](#ct-version)
 - [ct aliases](#ct-aliases)
 - [Short Aliases](#short-aliases)
 
@@ -1674,7 +1676,7 @@ ct timesheet submit --from DATE --to DATE [--force/-f] [--json]
 | `--force`, `-f` | flag | Skip confirmation prompt |
 | `--json` | flag | JSON output |
 
-Submits a timesheet for the given period. Shows a preview of entries and hours before confirming (use `--force` to skip). Rejects zero-hour submissions and overlapping periods. Endpoint: `POST /timesheets/submit/`
+Submits a timesheet for the given period (any date range — not limited to full weeks). Supports partial-week submissions for end-of-month splits. Shows a preview of entries and hours before confirming (use `--force` to skip). Rejects zero-hour submissions and periods that overlap with already submitted/approved timesheets. Endpoint: `POST /timesheets/submit/`
 
 ### ct timesheet approve
 
@@ -2437,6 +2439,119 @@ Endpoint: `GET /insights/profitability/`
 
 ---
 
+## ct team
+
+Manage manager → direct-report assignments. Mirrors Harvest's manager model: assign people to a manager so the manager can see their hours across any project without being a PM on each project individually. Orthogonal to per-project PM assignments; visibility is the union of both.
+
+### ct team list
+
+```
+ct team list [options]
+```
+
+Lists manager → direct-report assignments in the current organization. Admins and owners see everything; managers and project managers see only rows where they are the manager.
+
+**Options:**
+- `--manager/-m TEXT` — filter to a specific manager (membership ID, user ID, or email)
+- `--member TEXT` — filter to a specific member
+- `--json` — JSON output
+
+Endpoint: `GET /manager-assignments/`
+
+### ct team reports
+
+```
+ct team reports [options]
+```
+
+Shows the direct reports of a manager. Defaults to the current user. Same shape as `ct team list` but focused on the "who reports to this person" view.
+
+**Options:**
+- `--manager/-m TEXT` — target manager (defaults to the caller). Admins can query any manager; non-admin callers can only see their own.
+- `--json` — JSON output
+
+### ct team assign
+
+```
+ct team assign MANAGER MEMBER [MEMBER...] [--json]
+ct team assign MANAGER --all [--json]
+```
+
+Assigns one or more members as direct reports to `MANAGER`. Admin or owner only.
+
+Each positional accepts an email, user ID, or membership ID. `--all` assigns every active member of the organization (excluding the manager themselves). Mutually exclusive with positional members.
+
+- Manager must have role `project_manager`, `manager`, `admin`, or `owner`.
+- Members must be in the same organization.
+- Already-assigned members are silently skipped (reported in `skipped.already_assigned`).
+
+Endpoint: `POST /manager-assignments/bulk-set/` with `{manager, add: [ids]}`.
+
+### ct team unassign
+
+```
+ct team unassign MANAGER MEMBER [MEMBER...] [--json]
+ct team unassign MANAGER --all [--json]
+```
+
+Removes one or more direct-report assignments from `MANAGER`. Admin or owner only.
+
+Each positional is a member (email, user ID, or membership ID) — **not** an assignment ID. `--all` clears every current direct report for this manager.
+
+Endpoint: `POST /manager-assignments/bulk-set/` with `{manager, remove: [ids]}`.
+
+### ct team set
+
+```
+ct team set MANAGER [--member EMAIL]... [--all] [--json]
+```
+
+Declaratively sets the full list of direct reports for `MANAGER`. The CLI fetches the current assignments, computes the diff against the desired set, and applies both adds and removes in a single atomic call. Admin or owner only.
+
+Examples:
+
+- `ct team set alice@co.com --member bob --member carol` — reports are exactly {bob, carol}; anyone else currently assigned is unassigned.
+- `ct team set alice@co.com` — clear all (zero `--member` flags).
+- `ct team set alice@co.com --all` — reports are every active org member.
+
+Endpoint: `POST /manager-assignments/bulk-set/` with both `add` and `remove` computed client-side.
+
+### Visibility semantics
+
+A `manager` or `project_manager` sees time entries, timesheets, and team reports only for users in their **visible set**, which is the union of:
+
+1. **Direct reports** — members in `ct team list --manager me`.
+2. **PM-project members** — users of projects where the caller holds `project_role = project_manager` (see `ct projects update-member`).
+
+A `manager` with **zero** assignments and **zero** PM projects sees only their own entries. `admin` and `owner` always see everything.
+
+Timesheet approval follows the same rule: a manager can approve/reject only timesheets of users in their visible set (or projects where they are the explicit PM). Admins/owners can approve anything.
+
+---
+
+## ct version
+
+```
+ct version [--json]
+```
+
+Shows the installed CrowdTime CLI version and the latest version published to PyPI. Fetches fresh from PyPI every call (bypasses the 12-hour background-check cache).
+
+**Output:**
+- Plain: three lines — installed, latest, and a summary (`✓ You are up to date` or `⚠ A newer version is available`).
+- `--json`: `{ "installed": "0.10.0", "latest": "0.11.0", "up_to_date": false, "outdated": true }`.
+
+**Related:** after every other `ct` command, the CLI also performs a once-per-12-hours background check against PyPI and prints a one-line upgrade hint to stderr when out of date. Opt out with either:
+
+- `CROWDTIME_NO_VERSION_CHECK=1` environment variable
+- `ct config set update_check.enabled false`
+
+Dev builds, pre-release tags (`rc`, `a`, `dev`, etc.), and local version suffixes are skipped — no warning, no network call is wasted on comparing uncomparable versions.
+
+**Note:** `ct --version` (top-level flag) prints only the installed version without hitting the network, while `ct version` (subcommand) also fetches and compares.
+
+---
+
 ## ct aliases
 
 ```

{crowdtime_cli-0.10.0 → crowdtime_cli-0.12.0}/src/crowdtime_cli/skills/crowdtime/references/workflows.md

@@ -443,6 +443,38 @@ ct report team --month --member john@company.com
 ct org members
 ```
 
+### Assign Direct Reports to a Manager
+
+A `manager` or `project_manager` sees time entries, timesheets, and reports only for users they are responsible for. Two independent axes determine that visibility:
+
+1. **Direct-report assignments** (`ct team assign`) — person-based, visible across every project the member works on.
+2. **Per-project PM assignment** (`ct projects update-member ... --role project_manager`) — project-based, visible to the PM for anyone logging time on that project.
+
+A `manager` with zero assignments and zero PM projects sees only their own entries. `admin` and `owner` always see everything.
+
+```bash
+# Admin assigns three members as direct reports of a manager
+ct team assign alice@company.com bob@company.com
+ct team assign alice@company.com carol@company.com
+ct team assign alice@company.com dave@company.com
+
+# Alice — now a manager for those three — checks who reports to her
+ct team reports
+
+# Alice reviews her team's hours for the week (scoped automatically)
+ct log list --week
+
+# Alice can approve their timesheets without being a PM on any of their projects
+ct timesheet list --status submitted
+ct timesheet approve <timesheet-id>
+
+# Remove an assignment later
+ct team list --manager alice@company.com   # find the assignment ID
+ct team unassign <assignment-id>
+```
+
+**Tip**: combine with per-project PM assignment when a manager should also see *all* contributors on a specific project — even those who aren't direct reports. For example, use `ct projects update-member <project-id> <user-id> --role project_manager` for a project lead, and `ct team assign` for HR-style oversight.
+
 ---
 
 ## Reporting and Export
@@ -518,7 +550,10 @@ ct report saved delete <report-id>
 
 ## Timesheet Submission and Approval
 
-### Submit a Weekly Timesheet
+### Submit a Timesheet
+
+Timesheets can cover any date range — a full week, a partial week, or a custom period.
+This is useful when the month ends mid-week and you need to split submissions.
 
 ```bash
 # Review your week first
@@ -527,9 +562,13 @@ ct report --week -g day
 # Fill any gaps
 ct l -p project-alpha -d monday 6h "feature development"
 
-# Submit the timesheet
+# Submit a full week
 ct timesheet submit --from 2026-03-09 --to 2026-03-15 --force
 
+# Submit a partial week (e.g. end-of-month split)
+ct timesheet submit --from monday --to wednesday --force   # Close out March
+ct timesheet submit --from thursday --to friday --force     # Start April
+
 # Check submission status
 ct timesheet list
 
@@ -609,7 +648,7 @@ ct timesheet compliance --from 2026-03-09 --to 2026-03-15
 # pending approval (with days waiting), and rejected timesheets needing resubmission
 ```
 
-### End-of-Week Timesheet Routine
+### End-of-Week / End-of-Month Timesheet Routine
 
 ```bash
 # 1. Check your hours
@@ -618,10 +657,15 @@ ct report --week
 # 2. Fill gaps
 ct report --week -g day   # spot light days
 
-# 3. Submit
+# 3a. Submit full week
 ct timesheet submit --from 2026-03-09 --to 2026-03-15 --force
 
-# 4. (Manager) Review team — shows capacity % and status
+# 3b. OR submit partial week (month ends mid-week)
+ct timesheet submit --from 2026-03-30 --to 2026-03-31 --force  # Close March
+# ...later, after logging remaining days...
+ct timesheet submit --from 2026-04-01 --to 2026-04-05 --force  # Submit April portion
+
+# 4. (Manager) Review team — shows capacity %, status, and partial submissions
 ct timesheet team
 
 # 5. (Manager) Bulk approve all submitted

crowdtime_cli-0.12.0/src/crowdtime_cli/version_check.py

@@ -0,0 +1,184 @@
+"""PyPI version check: warn when the installed CLI is out of date.
+
+A single outbound call to PyPI, cached locally for 12 hours. The check is
+fire-and-forget — network errors, PyPI outages, and parse failures are all
+silenced so they never affect command output or exit status.
+
+Opt-out:
+- Environment variable: ``CROWDTIME_NO_VERSION_CHECK=1``
+- Config flag: ``[update_check] enabled = false`` in ``config.toml``
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional, Tuple
+
+import httpx
+
+from . import __version__
+
+PYPI_URL = "https://pypi.org/pypi/crowdtime-cli/json"
+CHECK_INTERVAL = timedelta(hours=12)
+FETCH_TIMEOUT_SEC = 2.0
+OPT_OUT_ENV = "CROWDTIME_NO_VERSION_CHECK"
+
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+def _cache_path() -> Path:
+    """Return the cache file path. Deferred so tests can monkeypatch CONFIG_DIR."""
+    from .config import CONFIG_DIR
+    return CONFIG_DIR / "version_check.json"
+
+
+def _parse_simple(v: Optional[str]) -> Optional[Tuple[int, int, int]]:
+    """Parse a strict ``MAJOR.MINOR.PATCH`` version string.
+
+    Returns None for dev builds, pre-releases, and local versions —
+    we deliberately skip the check in those cases rather than risk a
+    false positive.
+    """
+    if not v:
+        return None
+    m = _VERSION_RE.match(v)
+    if not m:
+        return None
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+def _read_cache() -> dict:
+    try:
+        return json.loads(_cache_path().read_text())
+    except (FileNotFoundError, ValueError, OSError):
+        return {}
+
+
+def _write_cache(latest: Optional[str]) -> None:
+    """Write the cache atomically via tmp-file + os.replace.
+
+    Guards against two concurrent ``ct`` processes interleaving writes and
+    leaving a truncated/partial JSON behind (which would silently disable
+    the cache on the next read).
+    """
+    try:
+        path = _cache_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps({
+            "last_checked": datetime.now(timezone.utc).isoformat(),
+            "latest_version": latest,
+        })
+        fd, tmp = tempfile.mkstemp(
+            prefix="version_check-", suffix=".tmp", dir=str(path.parent),
+        )
+        try:
+            with os.fdopen(fd, "w") as f:
+                f.write(payload)
+            os.replace(tmp, path)
+        except Exception:
+            # Ensure tmp doesn't linger if replace fails.
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise
+    except OSError:
+        pass  # Cache is a performance nicety — never fatal.
+
+
+def _is_fresh(cache: dict) -> bool:
+    last = cache.get("last_checked")
+    if not isinstance(last, str):
+        return False
+    try:
+        last_dt = datetime.fromisoformat(last)
+    except ValueError:
+        return False
+    if last_dt.tzinfo is None:
+        last_dt = last_dt.replace(tzinfo=timezone.utc)
+    delta = datetime.now(timezone.utc) - last_dt
+    # Guard against a system clock set to the past: a negative delta would
+    # otherwise keep stale caches "fresh" indefinitely. Treat any non-positive
+    # delta as stale so we re-fetch on the next invocation.
+    return timedelta(0) <= delta < CHECK_INTERVAL
+
+
+def _fetch_latest() -> Optional[str]:
+    """Fetch the latest published version from PyPI. Returns None on any failure."""
+    try:
+        resp = httpx.get(PYPI_URL, timeout=FETCH_TIMEOUT_SEC)
+        resp.raise_for_status()
+        version = resp.json().get("info", {}).get("version")
+        return version if isinstance(version, str) else None
+    except Exception:
+        return None
+
+
+def get_latest(force_refresh: bool = False) -> Optional[str]:
+    """Return the latest known version string, from cache or a fresh fetch.
+
+    When ``force_refresh=True``, always hit PyPI and update the cache.
+    Otherwise, a cache entry younger than ``CHECK_INTERVAL`` is reused.
+    A failed fetch falls back to the previous cached value (if any) so
+    transient PyPI outages don't wipe out the warning signal.
+    """
+    cache = _read_cache()
+    cached_latest = cache.get("latest_version")
+    if not force_refresh and _is_fresh(cache):
+        return cached_latest if isinstance(cached_latest, str) else None
+
+    fetched = _fetch_latest()
+    if fetched is not None:
+        _write_cache(fetched)
+        return fetched
+
+    # Fetch failed. Refresh the timestamp anyway so we don't retry on every
+    # single command, but preserve any prior cached version for warning text.
+    _write_cache(cached_latest if isinstance(cached_latest, str) else None)
+    return cached_latest if isinstance(cached_latest, str) else None
+
+
+def _opt_out() -> bool:
+    """Return True when the user has disabled the version check."""
+    if os.environ.get(OPT_OUT_ENV) == "1":
+        return True
+    try:
+        from .config import get_config
+        return not get_config().get("update_check.enabled", True)
+    except Exception:
+        return False
+
+
+def is_outdated(current: str, latest: Optional[str]) -> bool:
+    """Return True iff ``current`` and ``latest`` are both parseable and current < latest."""
+    current_t = _parse_simple(current)
+    latest_t = _parse_simple(latest)
+    if current_t is None or latest_t is None:
+        return False
+    return current_t < latest_t
+
+
+def check_and_warn(console) -> None:
+    """Daily-ish check: print an upgrade hint on stderr if out of date.
+
+    Silent on any error. Honors the opt-out env var and config flag. Dev /
+    pre-release / local versions are skipped (no comparison possible).
+    """
+    if _opt_out():
+        return
+    if _parse_simple(__version__) is None:
+        return  # dev build — not something we can sensibly compare
+    latest = get_latest()
+    if not is_outdated(__version__, latest):
+        return
+    console.print(
+        f"[yellow]\u26a0 crowdtime-cli {latest} is available "
+        f"(you have {__version__}). "
+        f"Run [bold]pip install -U crowdtime-cli[/bold] to upgrade.[/yellow]",
+        highlight=False,
+    )