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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.14.0
+Version: 0.15.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
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Office/Business
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: click>=8.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: humanize>=4.0
 Requires-Dist: keyring>=25.0
@@ -29,7 +30,7 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: python-dateutil>=2.9
 Requires-Dist: rich>=13.0
 Requires-Dist: tomlkit>=0.12.0
-Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: typer>=0.12.0
 Description-Content-Type: text/markdown
 
 # CrowdTime CLI

{crowdtime_cli-0.14.0 → crowdtime_cli-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "crowdtime-cli"
-version = "0.14.0"
+version = "0.15.0"
 description = "AI-powered time tracking CLI — a modern, developer-friendly alternative to Harvest"
 readme = "README.md"
 license = {text = "Proprietary"}
@@ -21,7 +21,14 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "typer[all]>=0.12.0",
+    # Not typer[all]: that extra no longer exists (typer warns on every
+    # install), and what it used to pull in — rich, shellingham — typer
+    # requires outright now.
+    "typer>=0.12.0",
+    # Imported directly by commands/org_cmd.py. It used to arrive through
+    # typer and stopped when typer 0.27 dropped it, which broke `ct` on
+    # every fresh install: importing a package means declaring it.
+    "click>=8.0",
     "rich>=13.0",
     "httpx>=0.27.0",
     "pydantic>=2.0",
@@ -42,7 +49,10 @@ crowdtime = "crowdtime_cli.main:_original_main"
 ct = "crowdtime_cli.main:_original_main"
 
 [build-system]
-requires = ["hatchling"]
+# Pinned below 1.28: from there hatchling stamps Metadata-Version 2.5,
+# which twine refuses to upload ("not a valid metadata version"). 0.14.0
+# shipped 2.4. Lift once the packaging toolchain accepts 2.5.
+requires = ["hatchling<1.28"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]

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

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

{crowdtime_cli-0.14.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/commands/billing_cmd.py

@@ -143,6 +143,8 @@ def status(
     table.add_column("Value")
 
     table.add_row("Status", f"[{color}]{label}[/{color}]")
+    if data.get("billing_exempt"):
+        table.add_row("Exempt", "[green]Billing exempt — full access, not billed[/green]")
     table.add_row("Plan", PLAN_LABELS.get(plan, plan.capitalize()))
     table.add_row("Seats", str(seat_count))
     table.add_row("Base", f"{format_currency(base_dollars)}/mo")

{crowdtime_cli-0.14.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/commands/invoice_cmd.py

@@ -89,6 +89,7 @@ def _resolve_payment_terms(value: str) -> int | None:
     """
     mapping = {
         "receipt": 0,
+        "net7": 7,
         "net15": 15,
         "net30": 30,
     }
@@ -580,6 +581,14 @@ def create_invoice(
         None, "--period", "-P",
         help="Preset period: last-week, last-2-weeks, last-month, this-month.",
     ),
+    projects: Optional[list[str]] = typer.Option(
+        None, "--project", "-p",
+        help=(
+            "Limit the invoice to specific project ID(s). Repeat for multiple. "
+            "Required to bill a fixed-fee project, which is never included "
+            "in a client-wide invoice."
+        ),
+    ),
     group_by: Optional[str] = typer.Option(
         None, "--group-by", "-g", help="Group line items by: project, task, user, date, none."
     ),
@@ -590,7 +599,17 @@ def create_invoice(
     terms: Optional[str] = typer.Option(None, "--terms", help="Payment terms text."),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
-        help="Payment terms: receipt, net15, net30, or number of days.",
+        help=(
+            "Payment terms: receipt, net15, net30, or number of days. "
+            "Omit to use the client's configured terms, then the org default."
+        ),
+    ),
+    issue_date: Optional[str] = typer.Option(
+        None, "--issue-date", help="Invoice date. Default: today."
+    ),
+    due_date: Optional[str] = typer.Option(
+        None, "--due-date",
+        help="Explicit due date. Default: issue date + payment terms.",
     ),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
@@ -600,11 +619,17 @@ def create_invoice(
     the specified date range. Use --period for preset ranges or
     --from/--to for custom dates.
 
+    The due date is derived from the invoice date, never from the end of the
+    billing period — invoicing a period weeks after it closed would otherwise
+    produce an invoice that is already overdue.
+
     Examples:
         ct invoice create --client <id> --from 2026-03-01 --to 2026-03-31
         ct invoice create --client <id> --period last-month --group-by project
         ct invoice create --client <id> --period last-2-weeks --payment-terms net30
         ct invoice create --client <id> --from monday --to friday --payment-terms 15
+        ct invoice create --client <id> --period last-month --due-date 2026-09-15
+        ct invoice create --client <id> --period last-month --project <fixed-project-id>
     """
     # Resolve period dates
     if period:
@@ -638,6 +663,20 @@ def create_invoice(
             )
             raise typer.Exit(1)
 
+    # Resolve explicit invoice dates
+    try:
+        issue_date_str = format_date(parse_date(issue_date)) if issue_date else None
+        due_date_str = format_date(parse_date(due_date)) if due_date else None
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
+
+    if issue_date_str and due_date_str and due_date_str < issue_date_str:
+        format_error(
+            f"--due-date {due_date_str} is before --issue-date {issue_date_str}."
+        )
+        raise typer.Exit(1)
+
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
     payload: dict = {
@@ -645,6 +684,12 @@ def create_invoice(
         "date_from": start,
         "date_to": end,
     }
+    if issue_date_str:
+        payload["issue_date"] = issue_date_str
+    if due_date_str:
+        payload["due_date"] = due_date_str
+    if projects:
+        payload["project_ids"] = list(projects)
     if group_by:
         payload["group_by"] = group_by
     if tax_rate is not None:
@@ -796,7 +841,7 @@ def update_invoice(
     tax_rate: Optional[float] = typer.Option(None, "--tax-rate", help="Tax rate percentage (e.g. 21 for 21%)."),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
-        help="Payment terms: receipt, net15, net30, or number of days.",
+        help="Payment terms: receipt, net7, net15, net30, or number of days.",
     ),
     from_name: Optional[str] = typer.Option(None, "--from-name", help="Issuer/sender name."),
     from_email: Optional[str] = typer.Option(None, "--from-email", help="Issuer/sender email."),
@@ -906,6 +951,10 @@ def send_invoice(
         None, "--cc",
         help="Contact ID(s) to CC. Repeat for multiple.",
     ),
+    keep_dates: bool = typer.Option(
+        False, "--keep-dates",
+        help="Send with the drafted dates as-is instead of re-stamping a stale issue date to today.",
+    ),
     force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
@@ -915,10 +964,15 @@ def send_invoice(
     Use --to to specify contact(s) or it defaults to the client's primary contact.
     This action cannot be undone (use void instead).
 
+    If the draft's issue date has fallen into the past, it is re-stamped to
+    today and the due date shifts by the same number of days, so the invoice
+    doesn't arrive already overdue. Pass --keep-dates to send it as drafted.
+
     Examples:
         ct invoice send <invoice-id>
         ct invoice send <invoice-id> --to <contact-id>
         ct invoice send <invoice-id> --to <contact-id-1> --to <contact-id-2> --cc <contact-id-3>
+        ct invoice send <invoice-id> --keep-dates
         ct invoice send <invoice-id> --force
     """
     if not force:
@@ -933,6 +987,8 @@ def send_invoice(
         payload["contact_ids"] = to
     if cc:
         payload["cc_contact_ids"] = cc
+    if keep_dates:
+        payload["keep_dates"] = True
 
     try:
         data = client.post(f"/invoices/{invoice_id}/send/", data=payload if payload else None)
@@ -1305,6 +1361,10 @@ def show_recurring(
             console.print(f"  Currency:        {data.get('currency', 'USD')}")
             console.print(f"  Payment Terms:   {data.get('payment_terms_days', 30)} days")
             console.print(f"  Next Run:        {data.get('next_run_date', '') or 'Not scheduled'}")
+            next_start = data.get("next_period_start")
+            next_end = data.get("next_period_end")
+            if next_start and next_end:
+                console.print(f"  Next Period:     {next_start} to {next_end}")
             console.print(f"  Last Run:        {data.get('last_run_date', '') or 'Never'}")
             console.print(f"  Total Generated: {data.get('total_generated', 0)}")
             console.print(f"  Auto-send:       {'Yes' if data.get('auto_send') else 'No'}")
@@ -1482,25 +1542,80 @@ def delete_recurring(
 @recurring_app.command("generate-now")
 def generate_now(
     template_id: str = typer.Argument(..., help="Recurring template ID."),
+    period_start: Optional[str] = typer.Option(
+        None, "--period-start", help="Start of the period to bill (YYYY-MM-DD)."
+    ),
+    period_end: Optional[str] = typer.Option(
+        None, "--period-end", help="End of the period to bill (YYYY-MM-DD)."
+    ),
+    issue_date: Optional[str] = typer.Option(
+        None, "--issue-date", help="Invoice date (YYYY-MM-DD). Defaults to today."
+    ),
+    allow_overlap: bool = typer.Option(
+        False, "--allow-overlap", help="Bill a period this template already invoiced."
+    ),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
     """Manually generate an invoice from a recurring template.
 
+    With no dates the template bills its scheduled period, dated today —
+    the same invoice the nightly job would raise, and it advances the
+    schedule. Naming a period bills that one instead as a one-off and
+    leaves the schedule untouched. The invoice date is separate from the
+    period: an invoice raised today can bill a period that closed months
+    ago (`ct invoice recurring show` prints both).
+
     Examples:
         ct invoice recurring generate-now <template-id>
+        ct invoice recurring generate-now <template-id> --period-start 2026-03-01 --period-end 2026-03-31
+        ct invoice recurring generate-now <template-id> --period-start 2026-03-01 --period-end 2026-03-31 --issue-date 2026-08-20
     """
+    if bool(period_start) != bool(period_end):
+        format_error("Give both --period-start and --period-end, or neither.")
+        raise typer.Exit(1)
+
     client = CrowdTimeClient(require_auth=True, require_org=True)
 
+    payload: dict = {}
+    if period_start:
+        payload["period_start"] = period_start
+        payload["period_end"] = period_end
+    if issue_date:
+        payload["issue_date"] = issue_date
+    if allow_overlap:
+        payload["allow_overlap"] = True
+
     try:
-        data = client.post(f"/invoices/recurring-templates/{template_id}/generate-now/")
+        data = client.post(
+            f"/invoices/recurring-templates/{template_id}/generate-now/", data=payload
+        )
 
         if output_json:
             print_json(data)
         else:
+            invoice = data.get("invoice") or {}
             format_success(data.get("detail", "Invoice generated successfully."))
+            if invoice:
+                console.print(f"  Invoice: {invoice.get('invoice_number', '')}")
+                console.print(f"  ID:      {invoice.get('id', '')}")
+                console.print(
+                    f"  Period:  {invoice.get('period_start', '')} to {invoice.get('period_end', '')}"
+                )
+                console.print(f"  Issued:  {invoice.get('issue_date', '')}")
     except APIError as e:
         if e.status_code == 404:
             format_error(f"Recurring template '{template_id}' not found.")
+        elif e.status_code == 409:
+            # The period is already billed, or is about to be by the scheduled
+            # run. Fixed lines go out in full every run, so say what clashes.
+            format_error(e.message)
+            body = e.detail if isinstance(e.detail, dict) else {}
+            for inv in body.get("overlapping_invoices", []):
+                console.print(
+                    f"  {inv.get('invoice_number', '')} ({inv.get('status', '')}) "
+                    f"— {inv.get('period_start', '')} to {inv.get('period_end', '')}"
+                )
+            console.print("[dim]Re-run with --allow-overlap to bill it anyway.[/dim]")
         else:
             format_error(e.message)
         raise typer.Exit(1)

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

@@ -21,6 +21,44 @@ console = Console()
 
 BILLING_MODES = ["per_task", "per_person", "custom"]
 
+# WHAT the client is charged. Distinct from BILLING_MODES, which only decides
+# HOW an hourly rate is resolved and is irrelevant for fixed-fee work.
+BILLING_TYPES = ["time_and_materials", "fixed_fee"]
+# Friendly aliases so `--billing-type fixed` and `--billing-type t&m` work.
+BILLING_TYPE_ALIASES = {
+    "tm": "time_and_materials",
+    "t&m": "time_and_materials",
+    "time": "time_and_materials",
+    "hourly": "time_and_materials",
+    "time_and_materials": "time_and_materials",
+    "fixed": "fixed_fee",
+    "fixed_fee": "fixed_fee",
+    "fixedfee": "fixed_fee",
+}
+
+
+def _resolve_billing_type(value: str) -> str | None:
+    """Normalise a --billing-type value, or None if unrecognised."""
+    return BILLING_TYPE_ALIASES.get(value.strip().lower().replace("-", "_"))
+
+
+PAYMENT_TERMS_ALIASES = {"receipt": 0, "net7": 7, "net15": 15, "net30": 30}
+
+
+def _resolve_payment_terms_opt(value: str) -> int | None:
+    """Resolve a --payment-terms value to days, or None if unrecognised.
+
+    Accepts the same presets as the invoice commands plus a raw day count.
+    """
+    lower = value.strip().lower()
+    if lower in PAYMENT_TERMS_ALIASES:
+        return PAYMENT_TERMS_ALIASES[lower]
+    try:
+        days = int(lower)
+    except ValueError:
+        return None
+    return days if days >= 0 else None
+
 
 def _resolve_or_create_client(api_client: CrowdTimeClient, client_name: str) -> str:
     """Look up a client by name; create one if it doesn't exist. Returns the client UUID."""
@@ -101,7 +139,17 @@ def show(
             console.print(f"  Client:       {project.client_name or project.client or '-'}")
             console.print(f"  Status:       {project.status}")
             console.print(f"  Billable:     {'Yes' if project.is_billable else 'No'}")
-            console.print(f"  Billing Mode: {billing_labels.get(project.billing_mode, project.billing_mode)}")
+            if project.billing_type == "fixed_fee":
+                currency = data.get("currency", "USD")
+                fee = (
+                    format_currency(project.fixed_fee_amount, currency)
+                    if project.fixed_fee_amount is not None
+                    else "[red]not set[/red]"
+                )
+                console.print(f"  Billing:      Fixed Fee — {fee}")
+            else:
+                console.print("  Billing:      Time & Materials")
+                console.print(f"  Billing Mode: {billing_labels.get(project.billing_mode, project.billing_mode)}")
             if project.budget_type and project.budget_type != "none" and project.budget_amount:
                 currency = data.get("currency", "USD")
                 budget_label = f"{project.budget_amount}h" if project.budget_type == "hours" else format_currency(project.budget_amount, currency)
@@ -126,7 +174,22 @@ def create(
                                   help="Mark as billable."),
     billing_mode: Optional[str] = typer.Option(
         None, "--billing-mode", "-m",
-        help="Billing mode: per_task, per_person, custom.",
+        help="Rate resolution for time & materials work: per_task, per_person, custom.",
+    ),
+    billing_type: Optional[str] = typer.Option(
+        None, "--billing-type",
+        help="What the client is charged: time_and_materials (default) or fixed_fee.",
+    ),
+    fixed_fee: Optional[float] = typer.Option(
+        None, "--fixed-fee",
+        help="Agreed price billed instead of logged hours. Implies --billing-type fixed_fee.",
+    ),
+    payment_terms: Optional[str] = typer.Option(
+        None, "--payment-terms",
+        help=(
+            "Payment terms for this project: receipt, net7, net15, net30, or a "
+            "number of days. Omit to inherit the client/org default."
+        ),
     ),
     color: Optional[str] = typer.Option(None, "--color", help="Project color hex code (e.g. #FF5733)."),
     budget: Optional[float] = typer.Option(None, "--budget", help="Budget amount (hours or money depending on --budget-type)."),
@@ -137,13 +200,39 @@ def create(
     code: Optional[str] = typer.Option(None, "--code", help="Short project code."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
-    """Create a new project."""
+    """Create a new project.
+
+    Fixed-fee projects bill an agreed price instead of logged hours. That fee
+    is never billed automatically — only when the project is selected
+    explicitly on an invoice, or pulled in by a recurring template.
+    """
     api_client = CrowdTimeClient(require_auth=True, require_org=True)
 
     if billing_mode and billing_mode not in BILLING_MODES:
         format_error(f"Invalid billing mode. Choose from: {', '.join(BILLING_MODES)}")
         raise typer.Exit(1)
 
+    # --fixed-fee alone is enough to mean "this is a fixed-fee project".
+    resolved_billing_type = None
+    if billing_type:
+        resolved_billing_type = _resolve_billing_type(billing_type)
+        if resolved_billing_type is None:
+            format_error(f"Invalid billing type. Choose from: {', '.join(BILLING_TYPES)}")
+            raise typer.Exit(1)
+    elif fixed_fee is not None:
+        resolved_billing_type = "fixed_fee"
+
+    if resolved_billing_type == "fixed_fee":
+        if fixed_fee is None:
+            format_error("--fixed-fee is required for fixed-fee projects.")
+            raise typer.Exit(1)
+        if fixed_fee <= 0:
+            format_error("--fixed-fee must be greater than zero.")
+            raise typer.Exit(1)
+    elif fixed_fee is not None:
+        format_error("--fixed-fee only applies to fixed-fee projects.")
+        raise typer.Exit(1)
+
     budget_types = ["hours", "money", "none"]
     if budget_type and budget_type not in budget_types:
         format_error(f"Invalid budget type. Choose from: {', '.join(budget_types)}")
@@ -158,6 +247,19 @@ def create(
     payload: dict = {"name": name, "is_billable": billable}
     if billing_mode:
         payload["billing_mode"] = billing_mode
+    if resolved_billing_type:
+        payload["billing_type"] = resolved_billing_type
+    if fixed_fee is not None:
+        payload["fixed_fee_amount"] = fixed_fee
+    if payment_terms is not None:
+        resolved_terms = _resolve_payment_terms_opt(payment_terms)
+        if resolved_terms is None:
+            format_error(
+                f"Invalid --payment-terms: '{payment_terms}'. "
+                "Use: receipt, net7, net15, net30, or a non-negative number of days."
+            )
+            raise typer.Exit(1)
+        payload["payment_terms_days"] = resolved_terms
     if color:
         payload["color"] = color
     if budget is not None:
@@ -229,7 +331,19 @@ def update(
                                             help="Mark as billable or not."),
     billing_mode: Optional[str] = typer.Option(
         None, "--billing-mode", "-m",
-        help="Billing mode: per_task, per_person, custom.",
+        help="Rate resolution for time & materials work: per_task, per_person, custom.",
+    ),
+    billing_type: Optional[str] = typer.Option(
+        None, "--billing-type",
+        help="What the client is charged: time_and_materials or fixed_fee.",
+    ),
+    fixed_fee: Optional[float] = typer.Option(
+        None, "--fixed-fee",
+        help="Agreed price billed instead of logged hours.",
+    ),
+    payment_terms: Optional[str] = typer.Option(
+        None, "--payment-terms",
+        help="Payment terms: receipt, net7, net15, net30, or a number of days.",
     ),
     color: Optional[str] = typer.Option(None, "--color", help="Project color hex code (e.g. #FF5733)."),
     budget: Optional[float] = typer.Option(None, "--budget", help="Budget amount (hours or money depending on --budget-type)."),
@@ -273,6 +387,19 @@ def update(
         format_error(f"Invalid status. Choose from: {', '.join(valid_statuses)}")
         raise typer.Exit(1)
 
+    resolved_billing_type = None
+    if billing_type:
+        resolved_billing_type = _resolve_billing_type(billing_type)
+        if resolved_billing_type is None:
+            format_error(f"Invalid billing type. Choose from: {', '.join(BILLING_TYPES)}")
+            raise typer.Exit(1)
+    elif fixed_fee is not None:
+        resolved_billing_type = "fixed_fee"
+
+    if fixed_fee is not None and fixed_fee <= 0:
+        format_error("--fixed-fee must be greater than zero.")
+        raise typer.Exit(1)
+
     payload: dict = {}
     if name is not None:
         payload["name"] = name
@@ -280,6 +407,19 @@ def update(
         payload["is_billable"] = billable
     if billing_mode:
         payload["billing_mode"] = billing_mode
+    if resolved_billing_type:
+        payload["billing_type"] = resolved_billing_type
+    if fixed_fee is not None:
+        payload["fixed_fee_amount"] = fixed_fee
+    if payment_terms is not None:
+        resolved_terms = _resolve_payment_terms_opt(payment_terms)
+        if resolved_terms is None:
+            format_error(
+                f"Invalid --payment-terms: '{payment_terms}'. "
+                "Use: receipt, net7, net15, net30, or a non-negative number of days."
+            )
+            raise typer.Exit(1)
+        payload["payment_terms_days"] = resolved_terms
     if color:
         payload["color"] = color
     if budget is not None:

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

@@ -597,9 +597,19 @@ def calendar_cmd(
     from_date: Optional[str] = typer.Option(None, "--from", help="Start date. Default: first of current month."),
     to_date: Optional[str] = typer.Option(None, "--to", help="End date. Default: last day of current month."),
     user: Optional[str] = typer.Option(None, "--user", "-u", help="Filter to a single user (email or UUID)."),
+    status: Optional[str] = typer.Option(
+        None,
+        "--status",
+        "-s",
+        help=(
+            "Statuses to include, comma-separated "
+            "(pending, approved, rejected, canceled). Default: approved. "
+            "Use 'all' for every status."
+        ),
+    ),
     output_json: bool = typer.Option(False, "--json", help="Output raw API response as JSON."),
 ) -> None:
-    """Render an approved-PTO calendar grid for the given window."""
+    """Render a PTO calendar grid for the given window (approved by default)."""
     today = date.today()
     try:
         if from_date:
@@ -631,6 +641,12 @@ def calendar_cmd(
         except APIError as e:
             format_error(e.message)
             raise typer.Exit(1)
+    if status:
+        params["status"] = (
+            "pending,approved,rejected,canceled"
+            if status.strip().lower() == "all"
+            else status
+        )
 
     try:
         data = client.get("/time-off/calendar/", params=params)
@@ -645,7 +661,8 @@ def calendar_cmd(
     rows = data if isinstance(data, list) else extract_results(data)
     items = [TimeOffCalendarItem(**item) for item in rows]
     if not items:
-        console.print("[dim]No approved PTO in this window.[/dim]")
+        scope = "PTO" if status else "approved PTO"
+        console.print(f"[dim]No {scope} in this window.[/dim]")
         return
 
     console.print(format_timeoff_calendar(items, f_date, t_date))

{crowdtime_cli-0.14.0 → crowdtime_cli-0.15.0}/src/crowdtime_cli/commands/timesheet_cmd.py

@@ -1,4 +1,4 @@
-"""Timesheet commands: list, submit, approve, reject, team overview."""
+"""Timesheet commands: list, submit, approve, reject, recall, reopen, team overview."""
 
 from __future__ import annotations
 
@@ -425,6 +425,55 @@ def recall_timesheet(
         raise typer.Exit(1)
 
 
+@app.command("reopen")
+def reopen_timesheet(
+    timesheet_id: str = typer.Argument(..., help="Timesheet ID to reopen."),
+    notes: str = typer.Option(
+        ..., "--notes", "-n", help="Reason for reopening (required)."
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation prompt."),
+    output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Reopen an APPROVED timesheet back to draft (project_manager+).
+
+    The reviewer-side undo for an approval granted in error: clears the
+    approval, unlocks the period's time entries and returns the timesheet to
+    draft so the user can fix it and resubmit. Blocked if any of that time is
+    already on a finalized invoice.
+
+    Examples:
+        ct timesheet reopen <timesheet-id> --notes "Approved before Friday's entries were added"
+        ct timesheet reopen <timesheet-id> --notes "Wrong project on Tuesday" --force
+    """
+    client = CrowdTimeClient(require_auth=True, require_org=True)
+
+    if not force and not output_json:
+        console.print(
+            "[yellow]Reopening clears the approval and unlocks every entry in the period "
+            "so the user can edit and resubmit.[/yellow]"
+        )
+        if not typer.confirm(f"Reopen timesheet {timesheet_id}?"):
+            console.print("[dim]Cancelled.[/dim]")
+            raise typer.Exit(0)
+
+    try:
+        result = client.post(f"/timesheets/{timesheet_id}/reopen/", data={"notes": notes})
+
+        if output_json:
+            print_json(result)
+        else:
+            user_name = result.get("user_name", "user")
+            format_success(
+                f"Timesheet from {user_name} reopened to draft. Entries are unlocked for editing."
+            )
+    except APIError as e:
+        if e.status_code == 404:
+            format_error(f"Timesheet '{timesheet_id}' not found.")
+        else:
+            format_error(e.message)
+        raise typer.Exit(1)
+
+
 @app.command("team")
 def team_overview(
     period_start: Optional[str] = typer.Option(
@@ -728,6 +777,7 @@ def timesheet_history(
                     "approved": "green",
                     "rejected": "red",
                     "recalled": "yellow",
+                    "reopened": "magenta",
                 }
                 style = event_styles.get(event_type, "dim")
 

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

@@ -768,15 +768,25 @@ def format_timeoff_calendar(
         else:
             cursor = cursor.replace(month=cursor.month + 1)
 
-    # Legend
-    legend_parts: list[str] = []
-    for kind, glyph in PTO_KIND_GLYPHS.items():
-        style = _pto_kind_style(kind)
-        legend_parts.append(f"[{style}]{glyph}[/{style}] {kind}")
-    legend = "  ".join(legend_parts)
+    # Legend — two axes: the letter is the kind, the colour is the status.
+    # Only list statuses actually present, so the default approved-only view
+    # doesn't advertise four colours it never renders.
+    present_statuses = [
+        s for s in PTO_STATUS_STYLES if any((i.status or "") == s for i in items)
+    ]
+    kind_legend = "  ".join(
+        f"{glyph} {kind}" for kind, glyph in PTO_KIND_GLYPHS.items()
+    )
+    status_legend = "  ".join(
+        f"[{_pto_status_style(s)}]■[/{_pto_status_style(s)}] {s}"
+        for s in present_statuses
+    )
 
     from rich.console import Group
-    body = Group(*month_blocks, Text(""), Text.from_markup(legend))
+    legend_lines = [Text.from_markup(f"[dim]kind[/dim]    {kind_legend}")]
+    if status_legend:
+        legend_lines.append(Text.from_markup(f"[dim]status[/dim]  {status_legend}"))
+    body = Group(*month_blocks, Text(""), *legend_lines)
     return Panel(
         body,
         title=f"PTO Calendar — {from_date.isoformat()} → {to_date.isoformat()}",
@@ -817,8 +827,10 @@ def _render_pto_month(
         day_label = f"[bold]{day:>2}[/bold]" if in_window else f"[dim]{day:>2}[/dim]"
         markers: list[str] = []
         for item in by_day.get(d, []):
+            # Letter = kind, colour = status (mirrors the web calendar, where
+            # the chip letter is the kind and the fill is the status).
             glyph = PTO_KIND_GLYPHS.get(item.kind, "?")
-            style = _pto_kind_style(item.kind)
+            style = _pto_status_style(item.status)
             markers.append(f"[{style}]{glyph}[/{style}]")
         marker_str = "".join(markers[:6])  # cap to avoid overflow
         cells.append(f"{day_label} {marker_str}".rstrip())

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

@@ -38,6 +38,9 @@ class Project(BaseModel):
     client_name: str | None = None
     color: str = "#3B82F6"
     billing_mode: str = "custom"
+    billing_type: str = "time_and_materials"
+    fixed_fee_amount: Decimal | None = None
+    payment_terms_days: int | None = None
     status: str = "active"
     is_billable: bool = True
     budget_type: str | None = "none"
@@ -342,4 +345,6 @@ class TimeOffCalendarItem(BaseModel):
     start_date: Optional[dt.date] = None
     end_date: Optional[dt.date] = None
     kind: str = "vacation"
+    status: str = "approved"
+    status_display: str = ""
     resolved_hours_per_day: Decimal | None = None

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

@@ -126,6 +126,7 @@ ct projects list                    # List all projects
 ct projects show <id>               # Project details
 ct projects create "New Project" --client "Acme" --budget 100 --budget-type hours -b
 ct projects create "New Project" --client "Acme" --billing-mode per_person  # Set billing mode
+ct projects create "Redesign" --client "Acme" --fixed-fee 10000  # Fixed price instead of hours
 ct projects archive <id>            # Archive a project
 ct projects switch <slug>           # Set default project
 
@@ -147,7 +148,11 @@ ct projects add-tasks <project-id> --task <tid1> --task <tid2>  # Bulk assign ta
 
 **Note:** `--client` on `projects create` accepts a client name. If the client doesn't exist yet, it will be auto-created.
 
-**Billing modes:** `custom` (default), `per_task` (rate per task), `per_person` (rate per person).
+**Billing types** (*what* is charged): `time_and_materials` (default) or `fixed_fee` (an agreed price via `--fixed-fee`, billed instead of logged hours).
+
+**Billing modes** (*how* an hourly rate resolves, T&M only): `custom` (default), `per_task` (rate per task), `per_person` (rate per person).
+
+A fixed fee is never billed automatically — client-wide invoices skip fixed-fee projects. Bill it by naming the project explicitly (`ct invoice create --project <id>`) or via a recurring template.
 
 **Rate waterfall** (order depends on billing mode):
 - `custom`: Entry → ProjectMember → ProjectTask → Project → Task → Membership → User
@@ -245,6 +250,7 @@ ct timesheet approve <id> --project <project-id>  # Approve one project's portio
 ct timesheet approve <id> --force       # Skip confirmation prompt
 ct timesheet reject <id> --notes "Missing entries for Wednesday"  # Reject with notes
 ct timesheet reject <id> --project <project-id> --notes "Hours too high"  # Reject one project portion
+ct timesheet reopen <id> --notes "Approved too early"  # Undo an approval — back to draft, entries unlocked (manager+)
 ct timesheet approvals <id>             # Show per-project approval status
 ct timesheet team                       # Team overview with capacity % (manager+)
 ct timesheet team --from 2026-03-10 --to 2026-03-16  # Custom period
@@ -353,7 +359,7 @@ ct pto edit <id> [fields]             # Edit date range, kind, notes, hours/day
 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 calendar [--from --to --user]  # Render-ready slice of approved PTO for a date window
+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
 ```
 

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

@@ -946,7 +946,10 @@ ct projects create NAME [options]
 | `--client`, `-c` | string | Client name (auto-creates if not found) |
 | `--billable`, `-b` | flag | Billable (default: true) |
 | `--no-billable`, `-B` | flag | Non-billable |
-| `--billing-mode` | string | Billing mode: `per_task`, `per_person`, `custom` (default) |
+| `--billing-type` | string | What the client is charged: `time_and_materials` (default) or `fixed_fee`. Accepts `tm` / `fixed` as aliases |
+| `--fixed-fee` | float | Agreed price billed instead of logged hours. Implies `--billing-type fixed_fee` |
+| `--billing-mode` | string | Rate resolution for T&M work: `per_task`, `per_person`, `custom` (default). Ignored for fixed-fee projects |
+| `--payment-terms` | string | Terms for this project: `receipt`, `net7`, `net15`, `net30`, or a number of days. Omit to inherit the client, then org, default |
 | `--color` | string | Hex color code |
 | `--budget` | float | Budget amount (hours or money depending on `--budget-type`) |
 | `--budget-type` | string | Budget type: `hours` (default when `--budget` given), `money`, `none` |
@@ -954,13 +957,32 @@ ct projects create NAME [options]
 | `--code` | string | Short project code |
 | `--json` | flag | JSON output |
 
-**Billing modes:**
+**Billing types** — *what* the client is charged:
+| Type | Description |
+|------|-------------|
+| `time_and_materials` | Default. Billed from logged hours at the resolved rate |
+| `fixed_fee` | Billed at `--fixed-fee`, an agreed price. Logged hours are tracked but never charged by the hour |
+
+> **How a fixed fee gets invoiced.** It is *never* billed automatically. A client-wide invoice (`ct invoice create` with no project filter) deliberately skips fixed-fee projects entirely, so the fee cannot go out by accident. It is billed only when:
+> 1. the project is named explicitly — `ct invoice create --client <id> --project <fixed-project-id>`, or
+> 2. a recurring template lists the project.
+>
+> When the fee is billed, that project's hours in the period are linked to the fee line and marked invoiced, so they stop showing as outstanding work without ever being charged twice. Until then they stay uninvoiced and available.
+
+**Billing modes** — *how* an hourly rate is resolved (T&M only):
 | Mode | Description |
 |------|-------------|
 | `custom` | Default. Full rate waterfall: Entry → ProjectMember → ProjectTask → Project → Task → Membership → User |
 | `per_task` | Task-first waterfall: Entry → ProjectTask → Task → ProjectMember → Membership → User → Project (last) |
 | `per_person` | Person-first waterfall: Entry → ProjectMember → Membership → User → ProjectTask → Task → Project (last) |
 
+**Fixed-fee examples:**
+```bash
+ct projects create "Rediseño Web" --client "Acme" --fixed-fee 10000
+ct projects update redesign --billing-type fixed --fixed-fee 12000
+ct projects update redesign --billing-type tm --billing-mode per_person
+```
+
 Endpoint: `POST /projects/`
 
 ### ct projects update
@@ -1694,6 +1716,8 @@ ct timesheet approve TIMESHEET_ID [--project PROJECT_ID] [--notes NOTES] [--forc
 
 Without `--project`: approves ALL project portions at once (manager+ role). With `--project`: approves only that project's portion — PM for that project can do this. When all project portions are approved, the timesheet auto-transitions to approved.
 
+Self-approval: admins and owners can approve their own timesheet (nobody above them can review it). Project managers and managers cannot — the API returns 400 and they must ask an admin or owner.
+
 Endpoints:
 - Bulk: `POST /timesheets/{id}/approve/`
 - Per-project: `POST /timesheets/{id}/approvals/{project_id}/approve/`
@@ -1713,6 +1737,8 @@ ct timesheet reject TIMESHEET_ID [--project PROJECT_ID] --notes NOTES [--force]
 
 Rejecting ANY project portion rejects the entire timesheet — the user must fix entries and resubmit. Notes are required.
 
+Self-rejection follows the same rule as approval: admins and owners can reject their own timesheet; everyone else should use `ct timesheet recall` instead.
+
 Endpoints:
 - Bulk: `POST /timesheets/{id}/reject/`
 - Per-project: `POST /timesheets/{id}/approvals/{project_id}/reject/`
@@ -1732,6 +1758,26 @@ ct timesheet recall TIMESHEET_ID [--notes NOTES] [--force] [--json]
 Recalls a submitted timesheet back to draft so you can edit and resubmit. Only the timesheet owner can recall, and only before it's been approved or rejected. Notes are optional but recorded in the audit trail.
 Endpoint: `POST /timesheets/{id}/recall/`
 
+Once a timesheet is APPROVED the owner can no longer recall it — use `ct timesheet reopen` (reviewer side) instead.
+
+### ct timesheet reopen
+
+```
+ct timesheet reopen TIMESHEET_ID --notes NOTES [--force] [--json]
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `--notes`, `-n` | string (required) | Reason for reopening |
+| `--force`, `-f` | flag | Skip confirmation prompt |
+| `--json` | flag | JSON output |
+
+The reviewer-side undo of an approval, for a mistake caught only after the timesheet was approved. Returns the timesheet to **draft**, clears the approval and its per-project records, and unlocks every time entry in the period so the user can fix and resubmit. Requires the same approval authority as `approve` (project_manager+ with visibility; admin/owner anywhere), and a reason is mandatory — it's written to the audit trail with the original approver and approval time.
+
+Only APPROVED timesheets can be reopened (400 otherwise). Returns 409 if any time in the period is already on a finalized invoice (sent/viewed/paid/partially paid/overdue) — void or credit the invoice first. Draft invoices don't block it.
+
+Endpoint: `POST /timesheets/{id}/reopen/`
+
 ### ct timesheet team
 
 ```
@@ -1898,7 +1944,7 @@ Shows invoice details including line items, payments, and totals. Endpoint: `GET
 ### ct invoice create
 
 ```
-ct invoice create --client CLIENT --from DATE --to DATE [--period PERIOD] [--group-by GROUP] [--tax-rate RATE] [--payment-terms TERMS] [--notes NOTES] [--terms TEXT] [--json]
+ct invoice create --client CLIENT --from DATE --to DATE [--period PERIOD] [--group-by GROUP] [--tax-rate RATE] [--payment-terms TERMS] [--issue-date DATE] [--due-date DATE] [--notes NOTES] [--terms TEXT] [--json]
 ```
 
 Creates an invoice from tracked time entries. Requires either `--from`/`--to` or `--period`.
@@ -1909,21 +1955,31 @@ Creates an invoice from tracked time entries. Requires either `--from`/`--to` or
 | `--from` | string | Period start date |
 | `--to` | string | Period end date |
 | `--period` | string | Preset: `last-week`, `last-2-weeks`, `last-month`, `this-month` |
+| `--project`, `-p` | string (repeatable) | Limit to specific project ID(s). **Required to bill a fixed-fee project** — those are never included in a client-wide invoice |
 | `--group-by` | string | Group line items by: `project`, `task`, `user`, `date`, `none` |
 | `--tax-rate` | float | Tax rate percentage (e.g. 21 for 21%) |
-| `--payment-terms` | string | Payment terms: `receipt`, `net15`, `net30`, or number of days |
+| `--payment-terms` | string | Payment terms: `receipt` (0 days), `net7`, `net15`, `net30`, or number of days. **Omit** to resolve from the waterfall below |
+| `--issue-date` | string | Invoice date. Default: today |
+| `--due-date` | string | Explicit due date. Default: issue date + payment terms |
 | `--notes` | string | Invoice notes |
 | `--terms` | string | Payment terms text |
 | `--json` | flag | JSON output |
 
 Billable time entries and expenses from the period are automatically imported as line items.
 
+> **Dates:** the due date is derived from the **invoice date**, never from the end of the billing period. Invoicing a period weeks after it closed would otherwise produce an invoice that is already overdue the moment it is sent. `--payment-terms receipt` (0 days) means due on the issue date, and is preserved rather than treated as "unset".
+>
+> **Payment terms waterfall:** `--payment-terms` > project > client > org default > 15 days. The **project tier only applies when the invoice covers exactly one project** (`--project <id>` given once) — a multi-project invoice resolves from the client instead, so one project's negotiated terms never silently govern another project's work.
+
 **Usage examples:**
 ```bash
 ct invoice create --client <id> --period last-month --payment-terms net30
 ct invoice create --client <id> --from 2026-03-01 --to 2026-03-31
 ct invoice create --client <id> --period last-2-weeks --group-by project
 ct invoice create --client <id> --period last-month --group-by user    # One line item per team member
+ct invoice create --client <id> --period last-month                    # Uses the client's own terms
+ct invoice create --client <id> --period last-month --due-date 2026-09-15
+ct invoice create --client <id> --period last-month --project <fixed-project-id>  # Bills the fixed fee
 ```
 
 Endpoint: `POST /invoices/from-time-entries/`
@@ -1983,18 +2039,21 @@ Adds a line item to a draft invoice. Endpoint: `POST /invoices/{id}/line-items/`
 ### ct invoice send
 
 ```
-ct invoice send INVOICE_ID [--to CONTACT_ID]... [--cc CONTACT_ID]... [--force/-f] [--json]
+ct invoice send INVOICE_ID [--to CONTACT_ID]... [--cc CONTACT_ID]... [--keep-dates] [--force/-f] [--json]
 ```
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `--to` | string (repeatable) | Contact ID(s) to send to. Repeat for multiple. Default: primary contact |
 | `--cc` | string (repeatable) | Contact ID(s) to CC. Repeat for multiple |
+| `--keep-dates` | flag | Send with the drafted dates as-is, skipping the stale-date re-stamp below |
 | `--force`, `-f` | flag | Skip confirmation prompt |
 | `--json` | flag | JSON output |
 
 Transitions invoice from draft to sent. This action cannot be undone (use void instead). Endpoint: `POST /invoices/{id}/send/`
 
+> **Stale drafts:** if the draft's issue date has fallen into the past, sending re-stamps it to today and shifts the due date by the same number of days, so a custom due-date offset survives and the invoice never arrives already overdue. Pass `--keep-dates` when the issue date must stay frozen (e.g. it belongs to a closed accounting period).
+
 ### ct invoice pay
 
 ```
@@ -2036,7 +2095,9 @@ Endpoint: `GET /invoices/recurring-templates/`
 ct invoice recurring show TEMPLATE_ID [--json]
 ```
 
-Shows full details of a recurring template including line items.
+Shows full details of a recurring template including line items. Prints both
+`Next Run` (when the invoice is raised) and `Next Period` (the work it bills) —
+they are different dates.
 Endpoint: `GET /invoices/recurring-templates/{id}/`
 
 ### ct invoice recurring create
@@ -2094,10 +2155,39 @@ Endpoint: `DELETE /invoices/recurring-templates/{id}/`
 ### ct invoice recurring generate-now
 
 ```
-ct invoice recurring generate-now TEMPLATE_ID [--json]
+ct invoice recurring generate-now TEMPLATE_ID [--period-start DATE] [--period-end DATE] [--issue-date DATE] [--json]
 ```
 
+| Option | Type | Description |
+|--------|------|-------------|
+| `--period-start` | date | Start of the period to bill (YYYY-MM-DD) |
+| `--period-end` | date | End of the period to bill (YYYY-MM-DD) |
+| `--issue-date` | date | Invoice date (YYYY-MM-DD). Defaults to today |
+| `--allow-overlap` | flag | Bill a period this template already invoiced |
+| `--json` | flag | JSON output |
+
 Manually triggers invoice generation from a template, regardless of schedule.
+Returns the created invoice (number, ID, period, issue date).
+
+**The period and the invoice date are separate.** With no dates the template
+bills its scheduled period (`next_period_start` / `next_period_end` on the
+template), dated today, and the schedule advances one cycle. Passing a period
+bills that one as a one-off and leaves the schedule exactly where it was —
+use it to bill a period that closed months ago without disturbing the cycle.
+`--period-start` and `--period-end` go together; passing one alone is an error.
+
+Deleting or voiding an invoice that consumed the scheduled run hands that run
+back to the template, so the period can be generated again.
+
+**Overlaps are refused with 409.** A template's fixed lines and fixed-fee
+projects are billed in full on *every* run regardless of the period, so billing
+a period twice duplicates them (logged hours are safe — they are settled on the
+invoice that pulled them). The refusal covers both a period another invoice from
+this template already bills, and a period the next scheduled run will bill — the
+response carries `requested_period`, `scheduled_period` and `overlapping_invoices`.
+Pass `--allow-overlap` for a deliberate re-bill, or set the period to the
+scheduled one so it consumes the run instead of adding to it.
+
 Endpoint: `POST /invoices/recurring-templates/{id}/generate-now/`
 
 ---
@@ -2892,40 +2982,48 @@ ct pto reject 3a9b4f22-1c5d-4e78-bf2a-0d1e2f3a4b5c --notes "Necesitamos verifica
 ### ct pto calendar
 
 ```
-ct pto calendar --from DATE --to DATE [--user/-u USER] [--json]
+ct pto calendar --from DATE --to DATE [--user/-u USER] [--status/-s STATUSES] [--json]
 ```
 
-Render-ready calendar slice of **approved** PTO entries overlapping the specified date window. Returns only approved entries. Scoped to visible users.
+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 approved entries); manager+ sees entries for their visibility scope; admin/owner sees all.
+**Who can call it:** any active member (sees own entries); manager+ sees entries for their visibility scope; admin/owner sees all.
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `--from` | string | **yes** | Window start date `YYYY-MM-DD` |
 | `--to` | string | **yes** | Window end date `YYYY-MM-DD` |
 | `--user`, `-u` | string | no | Filter to a specific user (email or UUID) |
+| `--status`, `-s` | string | no | Comma-separated statuses to include: `pending`, `approved`, `rejected`, `canceled`. Or `all` for every status. **Default: `approved` only** |
 | `--json` | flag | no | JSON output |
 
-**Output (table):** User, Start, End, Kind, Hours/day. Each row is one PTO block (may span multiple days).
+**Output (table):** a month grid. Each marker's **letter is the kind** (V/S/H/P/O) and its **colour is the status** (yellow pending, green approved, red rejected, dim canceled). A legend below the grid spells out both axes.
 
-**Response (JSON):** flat array — id, user, user_name, start_date, end_date, kind, resolved_hours_per_day.
+**Response (JSON):** flat array — id, user, user_name, start_date, end_date, kind, status, status_display, resolved_hours_per_day.
 
 **Errors:**
-- `400` — `--from` or `--to` missing, malformed, or `to < from`.
+- `400` — `--from` or `--to` missing, malformed, `to < from`, or `--status` contains an unrecognised value.
 
 **Usage examples:**
 
 ```bash
-# Team calendar for June 2026
+# Team calendar for June 2026 (approved only — the default)
 ct pto calendar --from 2026-06-01 --to 2026-06-30
 
 # Just Jane's PTO for Q3
 ct pto calendar --from 2026-07-01 --to 2026-09-30 --user jane@example.com
 
-# This week's approved time-off (for capacity planning)
-ct pto calendar --from 2026-05-25 --to 2026-05-31 --json
+# Capacity planning: who is out OR has asked to be out
+ct pto calendar --from 2026-06-01 --to 2026-06-30 --status pending,approved
+
+# Everything, including rejected and canceled requests
+ct pto calendar --from 2026-06-01 --to 2026-06-30 --status all --json
 ```
 
+> Use `--status pending,approved` for capacity planning: approved time off is
+> committed, pending is at risk of becoming time off. Plain `--status pending`
+> answers "what is waiting on my approval this month?".
+
 **Endpoint:** `GET /api/v1/organizations/<slug>/time-off/calendar/`
 
 ---

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

@@ -577,6 +577,8 @@ ct timesheet list
 ct timesheet recall <timesheet-id> --notes "Need to fix Wednesday entries"
 ct timesheet recall <timesheet-id> --force  # Skip confirmation
 
+# Already approved? You can't recall it — ask a manager to `ct timesheet reopen <id>`
+
 # Fix and resubmit
 ct l -p project-alpha -d friday 2h "missed entry"
 ct timesheet submit --from 2026-03-09 --to 2026-03-15 --force
@@ -621,6 +623,10 @@ ct timesheet reject <timesheet-id> --notes "Missing entries for Wednesday — pl
 # Reject multiple timesheets at once
 ct timesheet bulk-reject <id1> <id2> --notes "Incomplete entries for the week"
 
+# Approved it too early? Reopen — back to draft, entries unlocked, user fixes & resubmits
+ct timesheet reopen <timesheet-id> --notes "Approved before Friday's entries were added"
+ct timesheet reopen <timesheet-id> --notes "Wrong project on Tuesday" --force
+
 # View full audit trail for a timesheet (submissions, approvals, rejections)
 ct timesheet history <timesheet-id>
 ```
@@ -1049,13 +1055,69 @@ ct invoice recurring update <template-id> --active
 # Change schedule
 ct invoice recurring update <template-id> --schedule weekly --next-run 2026-04-14
 
-# Manually generate an invoice from a template (out-of-cycle)
+# Run the template now for its scheduled period (advances the schedule)
 ct invoice recurring generate-now <template-id>
 
+# Bill a specific period as a one-off — the schedule stays where it is
+ct invoice recurring generate-now <template-id> \
+  --period-start 2026-03-01 --period-end 2026-03-31
+
+# Same, dated today rather than inside the period it bills
+ct invoice recurring generate-now <template-id> \
+  --period-start 2026-03-01 --period-end 2026-03-31 --issue-date 2026-08-20
+
 # Delete a template
 ct invoice recurring delete <template-id>
 ```
 
+### Billing a Period Again
+
+A template's schedule moves on when it generates for its scheduled period, so
+the run and the period it billed are held by that invoice. Deleting or voiding
+it hands both back:
+
+```bash
+# Wrong period, or a bad draft — delete it
+ct invoice delete <invoice-id>
+
+# The template's next run is back where it was; check before regenerating
+ct invoice recurring show <template-id>    # Next Run / Next Period
+
+# Bill it again
+ct invoice recurring generate-now <template-id>
+```
+
+The hours and expenses on that invoice go back to being uninvoiced too, so
+they are pulled in again by the next invoice covering their dates. Voiding a
+sent invoice releases exactly the same things.
+
+Note the one asymmetry worth knowing: deleting a *voided* invoice releases
+nothing, because voiding already did. That is deliberate — the work may since
+have been billed on another invoice.
+
+### Why an Overlapping Period Is Refused
+
+`generate-now` returns 409 if the period is already billed by another invoice
+from the template, or is one the next scheduled run will bill:
+
+```bash
+# Refused: Jun 1-20 overlaps the scheduled Jun 1-30 run, which would bill the
+# template's fixed lines a second time
+ct invoice recurring generate-now <template-id> \
+  --period-start 2026-06-01 --period-end 2026-06-20
+
+# Either bill the scheduled period exactly, which uses up that run...
+ct invoice recurring generate-now <template-id>
+
+# ...or say you mean it
+ct invoice recurring generate-now <template-id> \
+  --period-start 2026-06-01 --period-end 2026-06-20 --allow-overlap
+```
+
+Logged hours cannot be double-billed — they are settled on the invoice that
+pulled them. Fixed lines and fixed-fee projects can: they are billed in full on
+every run whatever the period, which is what the guard exists for.
+
 ---
 
 ## Retainer Management
@@ -1221,6 +1283,12 @@ ct billing
 ct billing --json
 ```
 
+> **Billing-exempt orgs:** Some organizations (internal/comp accounts) are flagged
+> billing-exempt by a platform admin. `ct billing` shows an "Exempt" indicator and
+> `is_usable` is `true` regardless of subscription status — these orgs have full
+> access and are never charged. This flag can only be set in the Django admin, not
+> via the CLI.
+
 ### Start a Subscription
 
 ```bash