crowdtime-cli 0.15.0__tar.gz → 0.17.0__tar.gz

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.15.0
+Version: 0.17.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.15.0 → crowdtime_cli-0.17.0}/pyproject.toml

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

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/__init__.py

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

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/commands/ai_cmd.py

@@ -37,6 +37,7 @@ def parse(
         ct ai parse "2 hours on project alpha doing code review"
         ct ai parse "spent yesterday afternoon on bug fixes for client X"
         ct ai parse "30min standup" --force
+        ct ai parse "daily 15 min standup on argo all week"   # creates 5 entries
     """
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
@@ -54,8 +55,13 @@ def parse(
             console.print("[dim]Dry run - not saving.[/dim]")
             return
 
+        occurrence_count = len(result.occurrence_dates)
         if not force:
-            if not typer.confirm("Create this entry?"):
+            prompt = (
+                f"Create {occurrence_count} entries?" if occurrence_count > 1
+                else "Create this entry?"
+            )
+            if not typer.confirm(prompt):
                 console.print("[dim]Cancelled.[/dim]")
                 return
 
@@ -65,6 +71,16 @@ def parse(
             **result.parsed_fields,
         })
 
+        # A recurring parse comes back as {count, entries}; a single date keeps
+        # the plain TimeEntry shape.
+        if "entries" in confirm_data:
+            entries = [TimeEntry(**e) for e in confirm_data["entries"]]
+            format_success(f"{confirm_data['count']} entries created from AI parse")
+            from ..formatters import format_entry_summary
+            for entry in entries:
+                format_entry_summary(entry)
+            return
+
         # Response may be a full TimeEntry or a minimal {detail, time_entry_id}
         if "id" in confirm_data and "project_name" in confirm_data:
             entry = TimeEntry(**confirm_data)

crowdtime_cli-0.17.0/src/crowdtime_cli/commands/calendar_cmd.py

@@ -0,0 +1,136 @@
+"""Calendar commands: status, events, disconnect (CRO-74).
+
+Connecting requires a browser for the Google consent screen, so that step
+lives in the web app (Settings → Integrations). Once connected, the CLI can
+read the day's meetings and turn one into a time entry.
+
+Events are fetched live from Google on every call and are never stored by
+CrowdTime — only the entry you create from one is.
+"""
+
+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 format_error, format_success, print_json
+from ..utils import format_date, parse_date
+
+app = typer.Typer(help="Google Calendar integration.")
+console = Console()
+
+
+@app.command("status")
+def status(
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show whether a calendar is connected.
+
+    Examples:
+        ct calendar status
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        data = client.get("/calendar/")
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json(data)
+        return
+
+    if data.get("available") is False:
+        console.print("[dim]Google Calendar is not configured for this deployment.[/dim]")
+        return
+
+    if not data.get("connected"):
+        console.print("[dim]No calendar connected.[/dim]")
+        console.print(
+            "[dim]Connect one from the web app: Settings → Integrations.[/dim]"
+        )
+        return
+
+    account = data.get("account_email") or "(unknown account)"
+    console.print(f"Connected: [green]{account}[/green]")
+    if data.get("last_used_at"):
+        console.print(f"  Last read: {data['last_used_at']}")
+    if data.get("last_error"):
+        console.print(f"  [yellow]Last error:[/yellow] {data['last_error']}")
+
+
+@app.command("events")
+def events(
+    date: Optional[str] = typer.Option(None, "--date", "-d", help="Day to read (YYYY-MM-DD). Defaults to today."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List your calendar events for a day.
+
+    Fetched live from Google. Use the hours and title to create an entry:
+
+        ct calendar events
+        ct log 0.25 --project argo --task BE --notes "Daily standup"
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    params = {}
+    if date:
+        params["date"] = format_date(parse_date(date))
+
+    try:
+        data = client.get("/calendar/events/", params=params)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+    if output_json:
+        print_json(data)
+        return
+
+    items = data.get("events", [])
+    if not items:
+        console.print(f"[dim]No events on {data.get('date', 'that day')}.[/dim]")
+        return
+
+    table = Table(title=f"Calendar — {data.get('date', '')}")
+    table.add_column("Title")
+    table.add_column("Hours", justify="right")
+    table.add_column("Start", style="dim")
+    for event in items:
+        title = event.get("title", "")
+        if event.get("declined"):
+            title = f"[dim]{title} (declined)[/dim]"
+        table.add_row(
+            title,
+            "—" if event.get("all_day") else f"{event.get('hours', 0)}",
+            "all day" if event.get("all_day") else (event.get("start", "") or "")[11:16],
+        )
+    console.print(table)
+
+
+@app.command("disconnect")
+def disconnect(
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
+) -> None:
+    """Disconnect your calendar and revoke CrowdTime's access.
+
+    Examples:
+        ct calendar disconnect
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    if not force and not typer.confirm("Disconnect your Google Calendar?"):
+        console.print("[dim]Cancelled.[/dim]")
+        return
+
+    try:
+        client.delete("/calendar/")
+        format_success("Calendar disconnected.")
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/commands/log_cmd.py

@@ -43,7 +43,8 @@ def create(
     task: Optional[str] = typer.Option(None, "--task", "-t", help="Task name or ID."),
     date: Optional[str] = typer.Option(None, "--date", "-d", help="Date in YYYY-MM-DD (default: today)."),
     billable: Optional[bool] = typer.Option(None, "--billable/--no-billable", "-b/-B",
-                                            help="Mark as billable/non-billable."),
+                                            help="Override billable status. Account managers only — "
+                                                 "otherwise the project/task setting decides."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
     """Log a completed time entry.
@@ -137,7 +138,8 @@ def edit(
     task: Optional[str] = typer.Option(None, "--task", "-t", help="New task."),
     date: Optional[str] = typer.Option(None, "--date", "-d", help="New date (YYYY-MM-DD)."),
     billable: Optional[bool] = typer.Option(None, "--billable/--no-billable", "-b/-B",
-                                            help="Mark as billable/non-billable."),
+                                            help="Override billable status. Account managers only — "
+                                                 "otherwise the project/task setting decides."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
     """Edit an existing time entry."""

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/commands/projects_cmd.py

@@ -755,6 +755,52 @@ def update_member(
         raise typer.Exit(1)
 
 
+@app.command("assignable-users")
+def assignable_users(
+    project_id: str = typer.Argument(..., help="Project ID."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """List org members who can still be added to a project.
+
+    Everyone active in the organization who is not already on the project.
+    Use this to find user IDs for `ct projects add-members`.
+
+    Examples:
+        ct projects assignable-users <project-id>
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    try:
+        project_uuid = resolve_project(client, project_id)
+        data = client.get(f"/projects/{project_uuid}/assignable-users/")
+        users = extract_results(data) or data
+
+        if output_json:
+            print_json(users)
+            return
+
+        if not users:
+            console.print("[dim]Everyone in the organization is already on this project.[/dim]")
+            return
+
+        table = Table(title="Assignable users")
+        table.add_column("ID", style="dim")
+        table.add_column("Name")
+        table.add_column("Email")
+        table.add_column("Org role")
+        for u in users:
+            table.add_row(
+                u.get("id", ""),
+                u.get("full_name", ""),
+                u.get("email", ""),
+                u.get("org_role", ""),
+            )
+        console.print(table)
+    except APIError as e:
+        format_error(e.message)
+        raise typer.Exit(1)
+
+
 @app.command("add-members")
 def add_members_bulk(
     project_id: str = typer.Argument(..., help="Project ID."),

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/commands/pto_cmd.py

@@ -5,13 +5,13 @@ Mirrors the PTO API at `/organizations/<slug>/time-off/` — see
 
 Subcommands:
     request   – ask for time off (status=pending)
-    add       – manager-on-behalf creation (auto-approved by backend)
+    add       – on-behalf creation by project manager+ (auto-approved)
     list      – list / filter entries (own or team)
     show      – detail panel
     edit      – patch fields
-    cancel    – self/manager+ cancel
-    approve   – manager+ approve
-    reject    – manager+ reject (notes required)
+    cancel    – self/project manager+ cancel
+    approve   – project manager+ approve
+    reject    – project manager+ reject (notes required)
     calendar  – render-ready month grid
     summary   – aggregate hours/days for a window
 """
@@ -215,7 +215,7 @@ def request_cmd(
     notes: Optional[str] = typer.Option(None, "--notes", "-n", help="Optional free-text notes."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Request time off for yourself (status=pending until a manager approves)."""
+    """Request time off for yourself (status=pending until an approver decides)."""
     _validate_kind(kind)
     start, end = _parse_range_or_exit(dates)
     hpd = _hours_payload(hours_per_day)
@@ -258,9 +258,15 @@ def add_cmd(
         help="Decimal hours per day. Omit for full-day from membership.",
     ),
     notes: Optional[str] = typer.Option(None, "--notes", "-n", help="Optional free-text notes."),
+    paid: Optional[bool] = typer.Option(
+        None, "--paid/--unpaid",
+        help="Whether these hours are paid. Omit to follow the organization's "
+             "policy for this kind. Account managers and above only — the API "
+             "rejects the request from anyone below, it is not ignored.",
+    ),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Manager-on-behalf PTO entry. Backend auto-approves when caller is manager+."""
+    """On-behalf PTO entry, auto-approved. Project manager+, within their scope."""
     _validate_kind(kind)
     start, end = _parse_range_or_exit(dates)
     hpd = _hours_payload(hours_per_day)
@@ -283,12 +289,18 @@ def add_cmd(
         payload["hours_per_day"] = str(hpd)
     if notes is not None:
         payload["notes"] = notes
+    # Declared since the flag was added but never sent, so --unpaid silently
+    # booked paid leave. The backend defaults every kind to paid, so the
+    # omission was not neutral.
+    if paid is not None:
+        payload["is_paid"] = paid
 
     try:
         data = client.post("/time-off/", data=payload)
     except APIError as e:
-        # Surface 403 as a friendly error — backend rejects non-managers
-        # who try to set `user` to anyone but themselves.
+        # Surface the rejection as a friendly error — the backend refuses
+        # `user` values outside the caller's visible set, refuses it entirely
+        # below project manager, and refuses `is_paid` below account manager.
         format_error(e.message)
         raise typer.Exit(1)
 
@@ -516,7 +528,7 @@ def cancel_cmd(
     force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Cancel a PTO entry (self if pending; manager+ for any state except canceled)."""
+    """Cancel a PTO entry (self if pending; project manager+ for any non-canceled state)."""
     if not force:
         if not typer.confirm(f"Cancel PTO entry {pto_id}?"):
             console.print("[dim]Cancelled.[/dim]")
@@ -544,7 +556,7 @@ def approve_cmd(
     notes: Optional[str] = typer.Option(None, "--notes", "-n", help="Optional decision notes."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Approve a pending PTO entry (manager+ only)."""
+    """Approve a pending PTO entry (project manager+, within their scope)."""
     payload: dict = {}
     if notes is not None:
         payload["notes"] = notes
@@ -571,7 +583,7 @@ def reject_cmd(
     notes: Optional[str] = typer.Option(None, "--notes", "-n", help="Decision notes (REQUIRED)."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Reject a pending PTO entry (manager+ only). --notes is required."""
+    """Reject a pending PTO entry (project manager+, within scope). --notes is required."""
     if not notes or not notes.strip():
         format_error("--notes is required when rejecting a PTO entry.")
         raise typer.Exit(1)

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/formatters.py

@@ -378,7 +378,15 @@ def format_parse_result(result: ParseResult) -> None:
         console.print(f"  Task:        {result.task_name}")
     if result.hours is not None:
         console.print(f"  Duration:    [yellow]{format_duration(result.hours)}[/yellow]")
-    if result.date:
+    occurrences = result.occurrence_dates
+    if len(occurrences) > 1:
+        console.print(
+            f"  Dates:       [yellow]{len(occurrences)} entries[/yellow] "
+            f"({occurrences[0]} to {occurrences[-1]})"
+        )
+        for d in occurrences:
+            console.print(f"    - {d:%a %d %b}")
+    elif result.date:
         console.print(f"  Date:        {result.date}")
     console.print(f"  Billable:    {'Yes' if result.is_billable else 'No'}")
 

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/main.py

@@ -23,6 +23,7 @@ from .commands import (
     ai_cmd,
     auth_cmd,
     billing_cmd,
+    calendar_cmd,
     clients_cmd,
     config_cmd,
     expense_cmd,
@@ -74,6 +75,7 @@ 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(pto_cmd.app, name="pto", help="Manage PTO (paid time off) requests")
+app.add_typer(calendar_cmd.app, name="calendar", help="Google Calendar integration")
 app.add_typer(version_cmd.app, name="version")
 
 
@@ -158,18 +160,30 @@ def _show_status(output_json: bool = False) -> None:
             params={"status": "pending", "page_size": 50},
         )
         pending_items = extract_results(pending) if pending is not None else []
-        # If the caller is a plain member, the backend already scoped to
-        # `own`. If they're manager+, they get team-wide pending which is
-        # exactly what we want for the "requests pending review" surface.
-        pto_pending_count = len(pending_items)
-        # If we know the caller's id and *every* pending row belongs to
-        # them, label as "yours pending"; otherwise as "to review".
-        if pto_pending_count and self_user_id:
-            user_ids = {row.get("user") for row in pending_items}
-            if user_ids == {self_user_id}:
-                pto_pending_label = "of your PTO requests pending"
-            else:
-                pto_pending_label = "PTO requests pending review"
+        own_pending = [
+            row for row in pending_items if row.get("user") == self_user_id
+        ] if self_user_id else []
+
+        # Approvers get the server's routed count — it excludes requests that
+        # were routed to someone else, which listing and filtering here cannot
+        # know. Falls back to the local count when the caller isn't an approver
+        # (the endpoint is project manager+ and 403s for everyone below).
+        routed_count = None
+        try:
+            routed = client.get("/time-off/pending-count/")
+            if isinstance(routed, dict):
+                routed_count = routed.get("count")
+        except APIError:
+            routed_count = None
+
+        if routed_count:
+            pto_pending_count = routed_count
+            pto_pending_label = "PTO requests pending review"
+        elif own_pending:
+            pto_pending_count = len(own_pending)
+            pto_pending_label = "of your PTO requests pending"
+        else:
+            pto_pending_count = 0
     except APIError:
         pto_pending_count = None
     except Exception:

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/models.py

@@ -136,11 +136,22 @@ class ParseResult(BaseModel):
     task_id: str | None = None
     task_name: str | None = None
     date: Optional[dt.date] = None
+    # Every date the description covers. A one-off entry holds a single date
+    # equal to ``date``; recurring input ("daily standup all week") expands to
+    # one date per occurrence.
+    dates: list[dt.date] = Field(default_factory=list)
     is_billable: bool = True
     confidence: float = 0.0
     ambiguities: list[str] = Field(default_factory=list)
     parse_log_id: str | None = None
 
+    @property
+    def occurrence_dates(self) -> list[dt.date]:
+        """The dates to create entries for, never empty when a date parsed."""
+        if self.dates:
+            return self.dates
+        return [self.date] if self.date else []
+
     @property
     def parsed_fields(self) -> dict[str, Any]:
         """Return the parsed entry fields as a dict (for confirm endpoint)."""
@@ -160,6 +171,8 @@ class ParseResult(BaseModel):
             fields["task_name"] = self.task_name
         if self.date:
             fields["date"] = str(self.date)
+        if self.occurrence_dates:
+            fields["dates"] = [str(d) for d in self.occurrence_dates]
         fields["is_billable"] = self.is_billable
         return fields
 
@@ -269,6 +282,11 @@ class TimeOffEntryListItem(BaseModel):
     days_count: int = 0
     kind: str = "vacation"
     kind_display: str = ""
+    # Explicit override; None follows the org policy for the kind.
+    is_paid: bool | None = None
+    # Effective paid/unpaid after resolution. Unpaid hours explain the absence
+    # but do not count towards the hours the person is paid for.
+    resolved_is_paid: bool = True
     status: str = "pending"
     status_display: str = ""
     resolved_hours_per_day: Decimal | None = None
@@ -294,6 +312,8 @@ class TimeOffEntry(BaseModel):
     total_hours: Decimal | None = None
     kind: str = "vacation"
     kind_display: str = ""
+    is_paid: bool | None = None
+    resolved_is_paid: bool = True
     status: str = "pending"
     status_display: str = ""
     notes: str = ""

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -34,6 +34,19 @@ ct s            # Short alias
 ct s --json     # Machine-readable output
 ```
 
+### Recurring Entries
+
+`ct ai parse` expands a repeating description into one entry per day, so a
+whole week goes in with a single command:
+
+```bash
+ct ai parse "daily 15 min standup on argo all week"   # → 5 entries, one per weekday
+ct ai parse "1h code review on acme monday and wednesday"
+```
+
+It shows every date before creating anything. Prefer this over looping `ct log`
+when the user describes repeating work; use `ct log` for one-off entries.
+
 ### Timers
 ```bash
 ct timer start "description" -p project-slug -t "task name"  # Start a timer
@@ -52,6 +65,20 @@ ct t                                 # timer status
 ct c                                 # timer continue
 ```
 
+### Billable Status
+
+Billability comes from the **project and task configuration**, not from whoever
+logs the time:
+
+1. A non-billable project always wins — nothing on it is ever billable.
+2. Otherwise the task's billable setting decides, when a task is set.
+3. Otherwise the project's setting.
+
+`--billable/--no-billable` is an override that only account managers and above
+can use, and never on a non-billable project. For everyone else the flag is
+ignored, so do not pass it and do not tell the user an entry is billable
+because they asked for it — check the project/task setup instead.
+
 ### Logging Time
 
 **Options MUST come BEFORE positional arguments (duration, description).**
@@ -137,10 +164,21 @@ ct p -a                             # include archived
 
 #### Project Members
 ```bash
+ct projects assignable-users <project-id>            # Who can still be added (gives you the user IDs)
 ct projects update-member <project-id> <user-id> --role project_manager --rate 150  # Set per-project role & rate
 ct projects add-members <project-id> --user <uid1> --user <uid2> --role member --rate 120  # Bulk add
 ```
 
+**Adding someone to a project:** run `assignable-users` first to get the user
+IDs — it lists every active org member not already on the project. Do not use
+`ct team list` for this; it is scoped to who you can review time for, which is
+a different and narrower set.
+
+**Per-project roles:** setting `--role project_manager` on a project member
+grants them management of *that project only* (adding members, editing it,
+managing its tasks), whatever their organization role is. That is the way to
+let a member run one project without making them an org-wide project manager.
+
 #### Bulk Task Assignment
 ```bash
 ct projects add-tasks <project-id> --task <tid1> --task <tid2>  # Bulk assign tasks to project
@@ -343,22 +381,44 @@ ct billing events -n 50 # Show last 50 events
 ct b                    # billing status
 ```
 
+### Calendar (Google)
+
+```bash
+ct calendar status                    # Is a calendar connected?
+ct calendar events                    # Today's meetings, fetched live from Google
+ct calendar events --date 2026-06-01  # A specific day
+ct calendar disconnect                # Revoke access
+```
+
+Connecting requires the Google consent screen, so it happens in the web app
+(Settings → Integrations); the CLI can only read and disconnect. Events are
+fetched live on every call and are never stored by CrowdTime.
+
+**Turning a meeting into an entry:** read the events, then log the time
+explicitly — there is no automatic conversion:
+
+```bash
+ct calendar events                    # e.g. "Daily standup", 0.25h
+ct log 0.25 --project argo --task BE --notes "Daily standup"
+```
+
 ### Time Off (PTO)
 
-Per-user time-off entries with a kind (vacation, sick, holiday, personal, other) and a status lifecycle (pending → approved/rejected; pending → canceled). Members submit requests that await manager approval; managers can also add PTO directly on behalf of someone (auto-approved).
+Per-user time-off entries with a kind (vacation, sick, holiday, personal, other) and a status lifecycle (pending → approved/rejected; pending → canceled). Members submit requests that await approval, and their approvers are emailed automatically; project managers and above can also add PTO directly on behalf of someone in their scope (auto-approved).
 
 > **IMPORTANT**: Never use magic routing (`ct "..."`) or `ct ai parse` for PTO operations. Always construct explicit `ct pto ...` commands.
 > Full reference: `references/pto.md` and `references/commands.md` § PTO.
 
 ```bash
 ct pto request <dates>                # Submit your own PTO request (status=pending)
-ct pto add <user> <dates>             # Manager adds PTO on behalf of user (auto-approved)
+ct pto add <user> <dates>             # Add PTO on behalf of user, auto-approved (project manager+, in scope)
+ct pto add <user> <dates> --unpaid    # ... marked unpaid (account manager+; 400 for anyone below, not ignored)
 ct pto list [--mine|--team]           # List PTO entries with optional filters
 ct pto show <id>                      # Detail view of a single PTO entry (NEVER truncate the ID)
 ct pto edit <id> [fields]             # Edit date range, kind, notes, hours/day (pending entries)
-ct pto cancel <id> [--force]          # Cancel a PTO entry (own pending; or manager+ any)
-ct pto approve <id> [--notes "..."]   # Approve a pending entry (manager+)
-ct pto reject <id> --notes "..."      # Reject a pending entry — notes required (manager+)
+ct pto cancel <id> [--force]          # Cancel a PTO entry (own pending; or project manager+ any)
+ct pto approve <id> [--notes "..."]   # Approve a pending entry (project manager+)
+ct pto reject <id> --notes "..."      # Reject a pending entry — notes required (project manager+)
 ct pto calendar [--from --to --user --status]  # PTO slice for a date window (approved only unless --status)
 ct pto summary [--from --to --user]   # Aggregate approved PTO hours/days, by kind and by user
 ```
@@ -481,8 +541,8 @@ Read `references/workflows.md` for detailed multi-step workflow patterns includi
 - Checking project budgets
 - Retainer management and withdrawals
 - **Requesting your own PTO** (member submits, awaits approval)
-- **Reviewing and approving team PTO** (manager+ reviews pending requests)
-- **Adding PTO on behalf of someone** (manager logs pre-agreed leave, auto-approved)
+- **Reviewing and approving team PTO** (project manager+ reviews pending requests)
+- **Adding PTO on behalf of someone** (approver logs pre-agreed leave, auto-approved)
 - **Reconciling missing hours with PTO** (diagnose low-hour weeks: check PTO coverage, then anomaly report)
 
 ## Complete Command Reference
@@ -508,4 +568,4 @@ Read `references/commands.md` for the full reference of every command, subcomman
 15. **Invoices include expenses** — when creating invoices with `ct invoice create --period`, billable expenses from the same period are automatically included as line items. Mention this to users so they know their expenses will appear on the invoice. Invoices can be grouped by `project`, `task`, `user`, `date`, or `none` via `--group-by`. Line items support discounts (`--discount-type fixed|percent|hours --discount-value N`)
 16. **Client contacts** — use `ct clients contacts` and `ct clients add-contact` to manage multiple contacts per client. Set `--primary` for the main point of contact. Use `--receives-invoices` to flag contacts who should receive invoice emails
 17. **Payroll** — payroll data is strictly confidential. Only HR managers, admins, and owners can access it. When the user asks about payroll, always use the `ct payroll` commands. Compensation types are `hourly` (rate × hours) or `salary` (fixed monthly). Rate changes are always effective from the 1st of a month. The payroll workflow is: configure compensation → run liquidation → approve → mark paid
-18. **PTO / Time Off** — always construct explicit `ct pto ...` commands. Never use magic routing or `ct ai parse` for PTO. Before requesting PTO, always confirm the exact date range with the user — date ambiguity is the most common source of mistakes. Use `YYYY-MM-DD` for a single day or `YYYY-MM-DD:YYYY-MM-DD` for a range. `ct pto request` creates a pending entry (requires manager approval); `ct pto add <user>` is manager-only and creates an auto-approved entry. When reconciling missing hours for a user, always check `ct pto summary --user <email> --from X --to Y` before assuming the hours are missing. See `references/pto.md` for the full status lifecycle, kind definitions, and LLM guidance.
+18. **PTO / Time Off** — always construct explicit `ct pto ...` commands. Never use magic routing or `ct ai parse` for PTO. Before requesting PTO, always confirm the exact date range with the user — date ambiguity is the most common source of mistakes. Use `YYYY-MM-DD` for a single day or `YYYY-MM-DD:YYYY-MM-DD` for a range. `ct pto request` creates a pending entry (the requester's approvers are notified by email); `ct pto add <user>` requires project manager+ with the subject in their scope, and creates an auto-approved entry. When reconciling missing hours for a user, always check `ct pto summary --user <email> --from X --to Y` before assuming the hours are missing. See `references/pto.md` for the full status lifecycle, kind definitions, and LLM guidance.

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/skills/crowdtime/references/commands.md

@@ -1119,6 +1119,20 @@ ct projects update-member <project-id> <user-id> --rate 120
 
 Endpoint: `PATCH /projects/{id}/members/{user_id}/`
 
+### ct projects assignable-users
+
+```
+ct projects assignable-users PROJECT_ID [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--json` | flag | JSON output |
+
+Lists every **active organization member not already on the project**, with their user IDs and org roles. This is the correct source for the user IDs that `ct projects add-members` needs.
+
+It is deliberately not filtered by review visibility — `ct team list` and the timesheet endpoints answer "whose time can I review", which is a narrower set and the wrong question when staffing a project. Requires permission to manage the project (org project_manager+ assigned to it, an account manager or above, or a per-project `project_role` of `project_manager`). Endpoint: `GET /projects/<id>/assignable-users/`
+
 ### ct projects add-members
 
 ```
@@ -1373,8 +1387,21 @@ ct ai parse TEXT [--dry-run] [--force/-f] [--json]
 | `--force`, `-f` | flag | Skip confirmation |
 | `--json` | flag | JSON output |
 
-Shows parsed: description, project, task, duration, date, billable, confidence, ambiguities.
-Endpoints: `POST /ai/parse/` then `POST /ai/parse/confirm/`
+Shows parsed: description, project, task, duration, date(s), billable, confidence, ambiguities.
+
+**Recurring input creates several entries.** When the text describes work repeating over
+several days ("daily standup all week", "1h every day this week", "2h monday and
+wednesday"), the parse expands it into explicit dates and lists them all; confirming
+creates one entry per date in a single transaction. A one-off description still produces
+exactly one entry.
+
+```
+ct ai parse "daily 15 min standup on argo all week"   # → 5 entries, one per weekday
+```
+
+The confirm response is a plain time entry for a single date, and `{count, entries}` when
+several were created. Endpoints: `POST /ai/parse/` then `POST /ai/parse/confirm/`
+(the latter accepts `dates` to create a subset of what was parsed).
 
 ### ct ai suggest
 
@@ -1699,7 +1726,9 @@ 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 (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/`
+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 periods that overlap with already submitted/approved timesheets.
+
+A zero-hour period is rejected **unless every working day in it is covered by approved time off** — a full vacation week has no time entries by design and is submitted as-is. If someone was away and the submit is rejected, the fix is an approved PTO entry (`ct pto request`), not a fake time entry. Endpoint: `POST /timesheets/submit/`
 
 ### ct timesheet approve
 
@@ -2703,9 +2732,9 @@ ct pto request 2026-08-04:2026-08-08 --kind vacation --json
 ct pto add <user> <dates> [--kind/-k KIND] [--hours-per-day/-h HOURS] [--notes/-n TEXT] [--json]
 ```
 
-Add a PTO entry on behalf of another user (manager, admin, or owner only). The entry is created with `status=approved` immediately — no pending state. Use when an employee notified you via Slack or email and you are logging it for them.
+Add a PTO entry on behalf of another user (project manager and above). The entry is created with `status=approved` immediately — no pending state. Use when an employee notified you via Slack or email and you are logging it for them.
 
-**Who can call it:** `manager`, `admin`, `owner` (within their visibility scope — see `references/pto.md`).
+**Who can call it:** `project_manager`, `manager`, `admin`, `owner`. Project managers and account managers may only name a user inside their visibility scope — a subject outside it returns `400` on the `user` field, not `403`. Admins and owners may name any active member. See `references/pto.md`.
 
 | Argument/Option | Type | Required | Description |
 |-----------------|------|----------|-------------|
@@ -2714,6 +2743,7 @@ Add a PTO entry on behalf of another user (manager, admin, or owner only). The e
 | `--kind`, `-k` | string | no | `vacation` (default), `sick`, `holiday`, `personal`, `other` |
 | `--hours-per-day`, `-h` | decimal | no | Hours/day. Empty = capacity-based default |
 | `--notes`, `-n` | string | no | Reason or context notes |
+| `--paid` / `--unpaid` | flag | no | Whether the hours are paid. **Account manager+ only** — sending it as a project manager returns `400`, it is NOT ignored. Omit to follow the org policy for the kind |
 | `--json` | flag | no | JSON output |
 
 **Response (201):** full entry serializer with `status=approved`, `decided_by=<your user>`, `decided_at=<now>`.
@@ -2721,7 +2751,11 @@ Add a PTO entry on behalf of another user (manager, admin, or owner only). The e
 **Errors:**
 - `400` — date overlap, invalid dates, or hours_per_day > 24.
 - `400` — user is not an active member of this organization.
-- `403` — caller lacks manager+ role, or user is outside caller's visibility scope.
+- `400` on the `user` field — caller is below `project_manager`, or the named
+  user is outside the caller's visibility scope. This is a `400`, not a `403`:
+  the check lives in the serializer, so treat it as a validation error.
+- `400` on the `is_paid` field — caller is below account manager and sent
+  `--paid`/`--unpaid`.
 
 **Usage examples:**
 
@@ -2743,6 +2777,22 @@ ct pto add jane@example.com 2026-06-09:2026-06-13 --kind vacation --json
 
 ---
 
+### PTO pending count (no dedicated command)
+
+`ct` with no arguments surfaces a "PTO requests pending review" line driven by
+`GET /organizations/<slug>/time-off/pending-count/` (project manager+). There is
+no `ct pto pending-count` subcommand — use `ct pto list --team --status pending`
+when you need the entries themselves.
+
+The endpoint returns `{"count": N}` for the requests **routed to the caller**,
+excluding their own. For admins and owners that is not every pending request in
+the org — requests with a named approver (a direct manager, or a PM on the
+person's project) are excluded, because those were emailed to that person
+instead. Never recompute this by listing and filtering; you cannot see the
+routing from the list payload.
+
+---
+
 ### ct pto list
 
 ```
@@ -2800,7 +2850,7 @@ ct pto show <id> [--json]
 
 Show full details of a single PTO entry.
 
-**Who can call it:** own entries (any role); manager+ for entries within their visibility scope; admin/owner for any entry.
+**Who can call it:** own entries (any role); project manager+ for entries within their visibility scope; admin/owner for any entry.
 
 | Argument | Type | Required | Description |
 |----------|------|----------|-------------|
@@ -2987,7 +3037,7 @@ ct pto calendar --from DATE --to DATE [--user/-u USER] [--status/-s STATUSES] [-
 
 Render-ready calendar slice of PTO entries overlapping the specified date window, scoped to visible users. **Returns approved entries only unless `--status` is passed.**
 
-**Who can call it:** any active member (sees own entries); manager+ sees entries for their visibility scope; admin/owner sees all.
+**Who can call it:** any active member (sees own entries); project manager+ sees entries for their visibility scope; admin/owner sees all.
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
@@ -3036,7 +3086,7 @@ ct pto summary --from DATE --to DATE [--user/-u USER] [--json]
 
 Aggregate **approved** PTO hours and days within the specified window, clipping partial overlaps to the window boundaries. Shows totals, breakdown by kind, and breakdown by user.
 
-**Who can call it:** any active member (sees own data); manager+ sees summaries for their visibility scope; admin/owner sees all.
+**Who can call it:** any active member (sees own data); project manager+ sees summaries for their visibility scope; admin/owner sees all.
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
@@ -3148,3 +3198,43 @@ Displays all available shortcut commands in a formatted table. Shows each alias
 | `ct f <id>` | `ct favorites start <id>` |
 | `ct ex` | `ct expense` |
 | `ct "text"` | `ct ai parse "text"` |
+
+
+---
+
+## ct calendar
+
+Google Calendar integration. Events are fetched live from Google on every call and are never stored by CrowdTime — only a time entry the user creates from one is.
+
+Connecting a calendar needs the Google consent screen, so it happens in the web app (Settings → Integrations). The CLI can read and disconnect only.
+
+The connect flow is `POST /calendar/authorize/` → Google → `POST /calendar/callback/`. The authorize step returns a single-use `state` bound to the caller; the callback requires that exact value back and rejects anything else, so an authorization code cannot be redeemed by or planted on a different user.
+
+### ct calendar status
+
+```
+ct calendar status [--json]
+```
+
+Reports whether a calendar is connected, which Google account, when it was last read, and the last error if the connection has broken. Endpoint: `GET /calendar/`
+
+### ct calendar events
+
+```
+ct calendar events [--date DATE] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--date`, `-d` | string | Day to read (YYYY-MM-DD). Defaults to today |
+| `--json` | flag | JSON output |
+
+Lists that day's events with durations rounded to the nearest quarter hour. All-day events show `—` for hours; declined invitations are marked. There is **no automatic conversion** — read the events, then create entries explicitly with `ct log`. Endpoint: `GET /calendar/events/`
+
+### ct calendar disconnect
+
+```
+ct calendar disconnect [--force/-f]
+```
+
+Deletes the stored connection and asks Google to revoke the grant. Endpoint: `DELETE /calendar/`

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/skills/crowdtime/references/pto.md

@@ -31,6 +31,25 @@ If the user doesn't specify a kind, default to `vacation` but **confirm before s
 
 ---
 
+## Paid vs unpaid
+
+Every entry resolves to paid or unpaid, exposed as `resolved_is_paid`:
+
+1. The entry's own `is_paid`, when set.
+2. Otherwise the organization's policy for that kind (`time_off_paid_kinds`).
+3. Otherwise paid.
+
+**Paid** hours count towards the hours a person is paid for that month. **Unpaid**
+hours still explain the absence — reports and anomaly checks treat the person as
+away either way — but do not count towards what they are paid.
+
+Only account managers and above can set `is_paid`, via `ct pto add --paid/--unpaid`. A project manager passing the flag gets a `400` on the `is_paid` field — the request is refused, not silently booked under the org default. Omit the flag and the organization's policy for the kind applies.
+A member submitting their own request never chooses; it follows the org policy.
+Do not tell a user their leave is paid because they asked for it — read
+`resolved_is_paid` back from the entry.
+
+---
+
 ## Status lifecycle
 
 ```
@@ -80,7 +99,7 @@ The resolved value is surfaced as `resolved_hours_per_day` in API responses —
 | `admin` | All entries in the organization |
 | `owner` | All entries in the organization |
 
-Managers using `ct pto list --team` or `ct pto add <user>` can only target users in their visibility scope. Attempting to act on a user outside the scope returns `403`.
+Project managers and account managers using `ct pto list --team` or `ct pto add <user>` can only target users in their visibility scope. On `ct pto add` an out-of-scope user returns a **`400`** on the `user` field (the check is in the serializer, so it is a validation error, not a permission error); the detail-route actions (`approve`/`reject`/`cancel`) return `403` or `404` instead, because scope there is enforced by the queryset.
 
 ---
 
@@ -89,7 +108,7 @@ Managers using `ct pto list --team` or `ct pto add <user>` can only target users
 | Operation | member/viewer | project_manager / manager | admin / owner |
 |-----------|--------------|--------------------------|---------------|
 | `ct pto request` (own) | Own, → pending | Own, → pending | Own, → pending |
-| `ct pto add <user>` (on-behalf) | No | Within scope → approved | Any user → approved |
+| `ct pto add <user>` (on-behalf) | No | Within scope → approved (400 outside it) | Any user → approved |
 | `ct pto list / show` | Own only | Within scope | Any |
 | `ct pto edit` | Own + pending only | Within scope (any status) | Any |
 | `ct pto cancel` | Own + pending only | Within scope (any non-canceled) | Any |
@@ -99,6 +118,25 @@ Managers using `ct pto list --team` or `ct pto add <user>` can only target users
 
 ---
 
+## Approver notifications and the pending count
+
+Creating a **pending** entry (`ct pto request`, or the web request form) emails
+the requester's approvers automatically — one message each. Recipients are
+resolved per person, not by role sweep: whoever manages them directly, or runs
+a project they work on; org admins and owners only when nobody else does. An
+on-behalf `ct pto add` lands approved and notifies nobody.
+
+`GET /organizations/<slug>/time-off/pending-count/` (project manager+) returns
+`{"count": N}` — the requests **routed to the caller**, excluding their own. It
+is not "all pending in the org": for an admin or owner it counts only the
+requests with no named approver, so it agrees with who was actually emailed.
+`ct` (bare status) uses it for the "PTO requests pending review" line.
+
+Do not compute this by listing and filtering — that cannot tell which requests
+were routed elsewhere, and will over-count for admins and owners.
+
+---
+
 ## LLM guidelines for PTO
 
 1. **Never use magic routing or `ct ai parse` for PTO.** Always construct explicit `ct pto ...` commands. You are an LLM capable of building the correct command — no AI-parse intermediary is needed.
@@ -110,8 +148,8 @@ Managers using `ct pto list --team` or `ct pto add <user>` can only target users
 4. **Check for overlap before requesting.** Run `ct pto list --mine --json` first to confirm there are no conflicting pending or approved entries for the same user and date range. The API will reject overlaps, but catching them proactively avoids a confusing 400 error.
 
 5. **`ct pto request` vs `ct pto add`:**
-   - `ct pto request` → creates `status=pending`, requires manager approval. Use for the member's own PTO.
-   - `ct pto add <user>` → creates `status=approved` immediately. Use when the manager is logging pre-agreed PTO on behalf of someone else.
+   - `ct pto request` → creates `status=pending`, requires approval. Use for the member's own PTO. Their approvers are emailed automatically — do not tell the user to chase someone manually.
+   - `ct pto add <user>` → creates `status=approved` immediately, and notifies nobody. Use when an approver is logging pre-agreed PTO on behalf of someone else. Requires `project_manager+` **and** the subject must be inside the caller's scope; a `400` on the `user` field means they are out of scope, not that the role is wrong.
 
 6. **Rejection notes are required.** `ct pto reject` will fail with `400` if `--notes` is empty or omitted. Always ask the manager for a reason before running the command.
 

{crowdtime_cli-0.15.0 → crowdtime_cli-0.17.0}/src/crowdtime_cli/skills/crowdtime/references/workflows.md

@@ -1472,11 +1472,11 @@ ct pto request 2026-07-15 --kind sick --notes "Cita médica"
 ct pto request 2026-08-20 --kind personal --hours-per-day 4 --notes "Trámites personales"
 ```
 
-After running: confirm the output shows `status: pending`. Explain to the user that the entry is queued for manager approval — it is NOT yet in effect.
+After running: confirm the output shows `status: pending`. Explain to the user that the entry is queued for approval — it is NOT yet in effect. Their approvers are emailed automatically, so there is no need to chase anyone manually.
 
 ---
 
-### Workflow B: Review and Approve Team PTO (manager+)
+### Workflow B: Review and Approve Team PTO (project manager+)
 
 Use this when a manager wants to review pending requests from their team and approve or reject them.