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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.10.0
+Version: 0.11.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.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.10.0"
+version = "0.11.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.11.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.11.0"

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

@@ -0,0 +1,218 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from typing import 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 _resolve_membership(client: CrowdTimeClient, ref: str) -> dict:
+    """Resolve a membership by UUID, user UUID, or email. Returns the membership dict."""
+    data = client.get("/members/")
+    members_list = extract_results(data)
+
+    ref_lower = ref.lower()
+    # Exact email match
+    for m in members_list:
+        if (m.get("user", {}).get("email") or "").lower() == ref_lower:
+            return m
+    # Membership ID match
+    for m in members_list:
+        if m.get("id") == ref:
+            return m
+    # User ID match
+    for m in members_list:
+        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,
+    )
+
+
+@app.command("assign")
+def assign(
+    manager: str = typer.Argument(..., help="Manager (email, user ID, or membership ID)."),
+    member: str = typer.Argument(..., help="Member to assign (email, user ID, or membership ID)."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Assign a member as a direct report 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 <manager-membership-id> <member-membership-id>
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        manager_m = _resolve_membership(client, manager)
+        member_m = _resolve_membership(client, member)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    try:
+        data = client.post("/manager-assignments/", data={
+            "manager": manager_m["id"],
+            "member": member_m["id"],
+        })
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json(data)
+        return
+    manager_name = manager_m.get("user", {}).get("full_name") or manager_m.get("user", {}).get("email")
+    member_name = member_m.get("user", {}).get("full_name") or member_m.get("user", {}).get("email")
+    format_success(f"{member_name} now reports to {manager_name}.")
+
+
+@app.command("unassign")
+def unassign(
+    assignment_id: str = typer.Argument(..., help="Manager assignment ID (from `ct team list`)."),
+) -> None:
+    """Remove a direct-report assignment.
+
+    Admin+ only.
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+    try:
+        client.delete(f"/manager-assignments/{assignment_id}/")
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+    format_success(f"Assignment {assignment_id} removed.")
+
+
+@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.11.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.11.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.11.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.11.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,22 @@ 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 (manager only)
+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 unassign <assignment-id>                      # Remove an assignment (admin+)
+```
+
+**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 +416,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.11.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,99 @@ 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 [--json]
+```
+
+Assigns `MEMBER` as a direct report to `MANAGER`. Admin or owner only.
+
+Each argument accepts an email, user ID, or membership ID. The CLI resolves each to a membership in the current org.
+
+- Manager must have role `project_manager`, `manager`, `admin`, or `owner`.
+- Both must be in the same organization.
+- A member cannot manage themselves.
+
+Endpoint: `POST /manager-assignments/`
+
+### ct team unassign
+
+```
+ct team unassign ASSIGNMENT_ID
+```
+
+Removes a direct-report assignment by its ID (from `ct team list`). Admin or owner only.
+
+Endpoint: `DELETE /manager-assignments/<id>/`
+
+### 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.11.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.11.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,
+    )