crowdtime-cli 0.21.1__tar.gz → 0.23.0__tar.gz

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crowdtime-cli
-Version: 0.21.1
+Version: 0.23.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.21.1 → crowdtime_cli-0.23.0}/pyproject.toml

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

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/__init__.py

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

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/commands/invoice_cmd.py

@@ -572,6 +572,41 @@ def show_invoice(
         raise typer.Exit(1)
 
 
+# How hours are shown on an invoice (CRO-94). "person" is accepted for "user".
+HOURS_DISPLAYS = {
+    "project": "project", "task": "task", "user": "user", "person": "user",
+    "date": "date", "none": "none", "detailed": "detailed",
+}
+LINE_DETAILS = ["date", "person", "project", "task", "notes"]
+GROUP_BY_HELP = (
+    "How to display hours: project, task, person (one line each, per project), "
+    "detailed (one line per time entry), date, or none (everything on one line)."
+)
+DETAILS_HELP = (
+    "What each detailed line shows (implies --group-by detailed), comma-separated "
+    "from date, person, project, task, notes. Default: person,date,notes."
+)
+
+
+def _display_payload(group_by: Optional[str], details: Optional[str]) -> dict:
+    """Validate --group-by / --details into API fields, or raise ValueError."""
+    payload: dict = {}
+    if group_by is not None:
+        resolved = HOURS_DISPLAYS.get(group_by.strip().lower())
+        if resolved is None:
+            raise ValueError(f"Invalid --group-by. Choose from: {', '.join(HOURS_DISPLAYS)}.")
+        payload["group_by"] = resolved
+    if details is not None:
+        items = [d.strip().lower() for d in details.split(",") if d.strip()]
+        bad = [d for d in items if d not in LINE_DETAILS]
+        if bad or not items:
+            raise ValueError(f"Invalid --details. Choose from: {', '.join(LINE_DETAILS)}.")
+        if payload.setdefault("group_by", "detailed") != "detailed":
+            raise ValueError("--details only applies to --group-by detailed.")
+        payload["line_details"] = items
+    return payload
+
+
 @app.command("create")
 def create_invoice(
     client_id: str = typer.Option(..., "--client", "-c", help="Client ID."),
@@ -589,9 +624,16 @@ def create_invoice(
             "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."
+    payments: Optional[list[str]] = typer.Option(
+        None, "--payment",
+        help=(
+            "One-off fixed-fee payment ID(s) to bill (see `ct projects show`). "
+            "Repeat for multiple. Without it a selected one-off project bills "
+            "its next unbilled payment; each payment is billed only once."
+        ),
     ),
+    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help=GROUP_BY_HELP),
+    details: Optional[str] = typer.Option(None, "--details", help=DETAILS_HELP),
     tax_rate: Optional[float] = typer.Option(
         None, "--tax-rate", help="Tax rate percentage (e.g. 21 for 21%)."
     ),
@@ -626,10 +668,13 @@ def create_invoice(
     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-month --group-by person
+        ct invoice create --client <id> --period last-month --group-by detailed --details date,person,notes
         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>
+        ct invoice create --client <id> --period last-month --project <fixed-project-id> --payment <payment-id>
     """
     # Resolve period dates
     if period:
@@ -690,8 +735,16 @@ def create_invoice(
         payload["due_date"] = due_date_str
     if projects:
         payload["project_ids"] = list(projects)
-    if group_by:
-        payload["group_by"] = group_by
+    if payments:
+        if not projects:
+            format_error("--payment needs the fixed-fee project selected with --project.")
+            raise typer.Exit(1)
+        payload["milestone_ids"] = list(payments)
+    try:
+        payload.update(_display_payload(group_by, details))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if tax_rate is not None:
         payload["tax_rate"] = str(tax_rate)
     if notes:
@@ -1370,6 +1423,9 @@ def show_recurring(
             console.print(f"  Auto-send:       {'Yes' if data.get('auto_send') else 'No'}")
             console.print(f"  Pull Entries:    {'Yes' if data.get('pull_time_entries') else 'No'}")
             console.print(f"  Group By:        {data.get('group_by', 'project')}")
+            if data.get("group_by") == "detailed":
+                shown = ", ".join(data.get("line_details") or ["person", "date", "notes"])
+                console.print(f"  Line Details:    {shown}")
 
             line_items = data.get("line_items", [])
             if line_items:
@@ -1402,7 +1458,8 @@ def create_recurring(
     payment_terms: Optional[int] = typer.Option(None, "--payment-terms", help="Payment terms in days."),
     auto_send: bool = typer.Option(False, "--auto-send", help="Automatically send generated invoices."),
     pull_entries: bool = typer.Option(True, "--pull-entries/--no-pull-entries", help="Pull time entries into invoice."),
-    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help="Group by: project, task, user, date, none."),
+    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help=GROUP_BY_HELP),
+    details: Optional[str] = typer.Option(None, "--details", help=DETAILS_HELP),
     notes: Optional[str] = typer.Option(None, "--notes", help="Invoice notes."),
     terms: Optional[str] = typer.Option(None, "--terms", help="Payment terms text."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
@@ -1428,8 +1485,11 @@ def create_recurring(
         payload["payment_terms_days"] = payment_terms
     if auto_send:
         payload["auto_send"] = True
-    if group_by:
-        payload["group_by"] = group_by
+    try:
+        payload.update(_display_payload(group_by, details))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if notes:
         payload["notes"] = notes
     if terms:
@@ -1460,7 +1520,8 @@ def update_recurring(
     active: Optional[bool] = typer.Option(None, "--active/--inactive", help="Activate or deactivate."),
     auto_send: Optional[bool] = typer.Option(None, "--auto-send/--no-auto-send", help="Auto-send invoices."),
     payment_terms: Optional[int] = typer.Option(None, "--payment-terms", help="Payment terms in days."),
-    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help="Group by: project, task, user, date, none."),
+    group_by: Optional[str] = typer.Option(None, "--group-by", "-g", help=GROUP_BY_HELP),
+    details: Optional[str] = typer.Option(None, "--details", help=DETAILS_HELP),
     notes: Optional[str] = typer.Option(None, "--notes", help="Invoice notes."),
     output_json: bool = typer.Option(False, "--json", help="Output as JSON."),
 ) -> None:
@@ -1486,8 +1547,11 @@ def update_recurring(
         payload["auto_send"] = auto_send
     if payment_terms is not None:
         payload["payment_terms_days"] = payment_terms
-    if group_by is not None:
-        payload["group_by"] = group_by
+    try:
+        payload.update(_display_payload(group_by, details))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if notes is not None:
         payload["notes"] = notes
 

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/commands/projects_cmd.py

@@ -42,6 +42,69 @@ def _resolve_billing_type(value: str) -> str | None:
     return BILLING_TYPE_ALIASES.get(value.strip().lower().replace("-", "_"))
 
 
+FEE_SCHEDULES = {"one-off": "one_off", "one_off": "one_off", "oneoff": "one_off",
+                 "recurring": "recurring"}
+FEE_FREQUENCIES = ["weekly", "biweekly", "monthly", "quarterly"]
+
+
+def _parse_payment(value: str) -> dict:
+    """Parse a --payment value: NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD."""
+    if "=" not in value:
+        raise ValueError(f"Invalid --payment '{value}'. Use NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD.")
+    name, rest = value.rsplit("=", 1)
+    amount, _, due = rest.partition("@")
+    try:
+        amount_dec = Decimal(amount.strip())
+    except Exception:
+        raise ValueError(f"Invalid amount in --payment '{value}'.")
+    if not name.strip() or amount_dec <= 0:
+        raise ValueError(f"Invalid --payment '{value}': needs a name and an amount above zero.")
+    return {"name": name.strip(), "amount": str(amount_dec), "due_date": due.strip() or None}
+
+
+def _fee_plan_payload(
+    fee_schedule: Optional[str],
+    fee_frequency: Optional[str],
+    payments: Optional[List[str]],
+    first_invoice: Optional[str],
+    existing: Optional[list[dict]] = None,
+) -> dict:
+    """Build the fixed-fee plan fields of a project payload (CRO-61).
+
+    On update, ``existing`` milestones keep their id when a --payment names
+    them, and payments already invoiced are always kept — the API refuses a
+    plan that drops or changes them.
+    """
+    payload: dict = {}
+    if fee_schedule is not None:
+        resolved = FEE_SCHEDULES.get(fee_schedule.strip().lower())
+        if resolved is None:
+            raise ValueError("Invalid --fee-schedule. Choose from: one-off, recurring.")
+        payload["fixed_fee_schedule"] = resolved
+    if fee_frequency is not None:
+        if fee_frequency not in FEE_FREQUENCIES:
+            raise ValueError(f"Invalid --fee-frequency. Choose from: {', '.join(FEE_FREQUENCIES)}.")
+        payload["fixed_fee_frequency"] = fee_frequency
+        payload.setdefault("fixed_fee_schedule", "recurring")
+    if first_invoice is not None:
+        payload["fixed_fee_first_invoice_date"] = first_invoice
+    if payments:
+        items = [_parse_payment(p) for p in payments]
+        by_name = {m["name"]: m for m in (existing or [])}
+        for item in items:
+            if item["name"] in by_name:
+                item["id"] = by_name[item["name"]]["id"]
+        named = {i["name"] for i in items}
+        billed = [
+            {"id": m["id"], "name": m["name"], "amount": m["amount"], "due_date": m.get("due_date")}
+            for m in (existing or [])
+            if m.get("invoice") and m["name"] not in named
+        ]
+        payload["fixed_fee_milestones"] = billed + items
+        payload.setdefault("fixed_fee_schedule", "one_off")
+    return payload
+
+
 PAYMENT_TERMS_ALIASES = {"receipt": 0, "net7": 7, "net15": 15, "net30": 30}
 
 
@@ -146,7 +209,26 @@ def show(
                     if project.fixed_fee_amount is not None
                     else "[red]not set[/red]"
                 )
-                console.print(f"  Billing:      Fixed Fee — {fee}")
+                if project.fixed_fee_schedule == "recurring":
+                    freq = project.fixed_fee_frequency or "?"
+                    console.print(f"  Billing:      Recurring fixed fee — {fee} {freq}")
+                    tpl = project.fixed_fee_template
+                    if tpl:
+                        state = (f"next invoice {tpl['next_run_date']}" if tpl.get("is_active")
+                                 else "paused")
+                        console.print(f"  Invoiced by:  {tpl['name']} ({tpl['id']}) — {state}")
+                    else:
+                        console.print("  Invoiced by:  [yellow]no active recurring invoice[/yellow]")
+                else:
+                    console.print(f"  Billing:      Fixed Fee (one-off) — {fee}")
+                    for m in project.fixed_fee_milestones or []:
+                        inv = m.get("invoice")
+                        status = f"billed on {inv['invoice_number']}" if inv else "not billed"
+                        due = f" due {m['due_date']}" if m.get("due_date") else ""
+                        console.print(
+                            f"    • {m['name']}: {format_currency(Decimal(m['amount']), currency)}"
+                            f"{due} — {status}  [dim]{m['id']}[/dim]"
+                        )
             else:
                 console.print("  Billing:      Time & Materials")
                 console.print(f"  Billing Mode: {billing_labels.get(project.billing_mode, project.billing_mode)}")
@@ -184,6 +266,22 @@ def create(
         None, "--fixed-fee",
         help="Agreed price billed instead of logged hours. Implies --billing-type fixed_fee.",
     ),
+    fee_schedule: Optional[str] = typer.Option(
+        None, "--fee-schedule",
+        help="one-off (the price is paid in payments, default) or recurring (the price every period).",
+    ),
+    fee_frequency: Optional[str] = typer.Option(
+        None, "--fee-frequency",
+        help="How often a recurring fee is billed: weekly, biweekly, monthly, quarterly.",
+    ),
+    payments: Optional[List[str]] = typer.Option(
+        None, "--payment",
+        help="One-off payment as NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD (due date). Repeat; must add up to --fixed-fee.",
+    ),
+    first_invoice: Optional[str] = typer.Option(
+        None, "--first-invoice",
+        help="Recurring fee: date of the first invoice (YYYY-MM-DD). Default: one period after start.",
+    ),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
         help=(
@@ -202,9 +300,16 @@ def create(
 ) -> None:
     """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.
+    Fixed-fee projects bill an agreed price instead of logged hours, one of two
+    ways. One-off: --fixed-fee is the whole price, paid in --payment
+    milestones (one full payment if none are given), each billed once.
+    Recurring: --fixed-fee is billed every --fee-frequency period by a
+    recurring invoice the project sets up for itself.
+
+    Examples:
+        ct projects create "Website" -c Acme --fixed-fee 5000 \
+            --payment Kickoff=1500@2026-06-01 --payment Midpoint=1500 --payment Delivery=2000
+        ct projects create "Support" -c Acme --fixed-fee 4000 --fee-frequency monthly
     """
     api_client = CrowdTimeClient(require_auth=True, require_org=True)
 
@@ -251,6 +356,17 @@ def create(
         payload["billing_type"] = resolved_billing_type
     if fixed_fee is not None:
         payload["fixed_fee_amount"] = fixed_fee
+    if resolved_billing_type != "fixed_fee" and (fee_schedule or fee_frequency or payments or first_invoice):
+        format_error("--fee-schedule, --fee-frequency, --payment and --first-invoice only apply to fixed-fee projects.")
+        raise typer.Exit(1)
+    try:
+        payload.update(_fee_plan_payload(fee_schedule, fee_frequency, payments, first_invoice))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
+    if payload.get("fixed_fee_schedule") == "recurring" and not payload.get("fixed_fee_frequency"):
+        format_error("A recurring fee needs --fee-frequency.")
+        raise typer.Exit(1)
     if payment_terms is not None:
         resolved_terms = _resolve_payment_terms_opt(payment_terms)
         if resolved_terms is None:
@@ -341,6 +457,22 @@ def update(
         None, "--fixed-fee",
         help="Agreed price billed instead of logged hours.",
     ),
+    fee_schedule: Optional[str] = typer.Option(
+        None, "--fee-schedule",
+        help="one-off (the price is paid in payments, default) or recurring (the price every period).",
+    ),
+    fee_frequency: Optional[str] = typer.Option(
+        None, "--fee-frequency",
+        help="How often a recurring fee is billed: weekly, biweekly, monthly, quarterly.",
+    ),
+    payments: Optional[List[str]] = typer.Option(
+        None, "--payment",
+        help="One-off payment as NAME=AMOUNT or NAME=AMOUNT@YYYY-MM-DD (due date). Repeat; replaces the plan; invoiced payments are kept.",
+    ),
+    first_invoice: Optional[str] = typer.Option(
+        None, "--first-invoice",
+        help="Recurring fee: date of the first invoice (YYYY-MM-DD). Moves the next invoice.",
+    ),
     payment_terms: Optional[str] = typer.Option(
         None, "--payment-terms",
         help="Payment terms: receipt, net7, net15, net30, or a number of days.",
@@ -364,6 +496,8 @@ def update(
         ct projects update my-project --name "New Name"
         ct projects update my-project --budget 200 --budget-type hours
         ct projects update my-project --billing-mode per_person --status paused
+        ct projects update my-project --fixed-fee 6000 --payment Kickoff=1500 --payment Rest=4500
+        ct projects update my-project --fee-frequency quarterly
     """
     api_client = CrowdTimeClient(require_auth=True, require_org=True)
 
@@ -411,6 +545,21 @@ def update(
         payload["billing_type"] = resolved_billing_type
     if fixed_fee is not None:
         payload["fixed_fee_amount"] = fixed_fee
+    existing_milestones = None
+    if payments:
+        try:
+            current = api_client.get(f"/projects/{resolve_project(api_client, project_id)}/")
+            existing_milestones = current.get("fixed_fee_milestones") or []
+        except APIError as e:
+            format_error(e.message)
+            raise typer.Exit(1)
+    try:
+        payload.update(_fee_plan_payload(
+            fee_schedule, fee_frequency, payments, first_invoice, existing_milestones,
+        ))
+    except ValueError as e:
+        format_error(str(e))
+        raise typer.Exit(1)
     if payment_terms is not None:
         resolved_terms = _resolve_payment_terms_opt(payment_terms)
         if resolved_terms is None:

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/models.py

@@ -40,6 +40,11 @@ class Project(BaseModel):
     billing_mode: str = "custom"
     billing_type: str = "time_and_materials"
     fixed_fee_amount: Decimal | None = None
+    # one_off (price paid in milestones) or recurring (amount per period).
+    fixed_fee_schedule: str = "one_off"
+    fixed_fee_frequency: str = ""
+    fixed_fee_milestones: list[dict] | None = None
+    fixed_fee_template: dict | None = None
     payment_terms_days: int | None = None
     status: str = "active"
     is_billable: bool = True

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/skills/crowdtime/SKILL.md

@@ -161,7 +161,9 @@ 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 create "Redesign" --client "Acme" --fixed-fee 10000  # One-off price, one payment
+ct projects create "Web" --client "Acme" --fixed-fee 5000 --payment Kickoff=1500@2026-06-01 --payment Delivery=3500
+ct projects create "Support" --client "Acme" --fixed-fee 4000 --fee-frequency monthly  # Recurring fee
 ct projects archive <id>            # Archive a project
 ct projects switch <slug>           # Set default project
 
@@ -202,9 +204,13 @@ ct projects add-tasks <project-id> --task <tid1> --task <tid2>  # Bulk assign ta
 
 **Billing types** (*what* is charged): `time_and_materials` (default) or `fixed_fee` (an agreed price via `--fixed-fee`, billed instead of logged hours).
 
+**Fixed fees come in two schedules** — ask which one when the user doesn't say:
+- **One-off** (default): `--fixed-fee` is the whole project price, split into `--payment NAME=AMOUNT[@DUE]` milestones that must add up to it (one "Full payment" if none are given). Each payment is invoiced exactly once.
+- **Recurring**: `--fixed-fee` is charged every `--fee-frequency` (`weekly`, `biweekly`, `monthly`, `quarterly`). The project sets up its own recurring invoice automatically — don't create a template for it by hand.
+
 **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.
+A fixed fee is never swept into a client-wide invoice. A one-off price is billed by naming the project (`ct invoice create --project <id>`, which bills its next unbilled payment; add `--payment <payment-id>` to pick one — IDs are in `ct projects show`). A recurring fee is billed by its own recurring invoice.
 
 **Rate waterfall** (order depends on billing mode):
 - `custom`: Entry → ProjectMember → ProjectTask → Project → Task → Membership → User
@@ -337,7 +343,8 @@ ct invoice aging                        # Overdue aging report: buckets 1-30d, 3
 ct invoice aging --client <id>          # Aging for a specific client
 ct invoice show <id>                    # Invoice details with line items
 ct invoice create --client <id> --period last-month --payment-terms net30  # From time entries
-ct invoice create --client <id> --period last-month --group-by user        # Group by team member
+ct invoice create --client <id> --period last-month --group-by person      # One line per person on each project
+ct invoice create --client <id> --period last-month --group-by detailed --details date,person,notes  # One line per entry
 ct invoice create-blank --client <id> --issue-date today --payment-terms net30  # Empty draft
 ct invoice update <id> --terms "Wire to IBAN XX" --notes "March"  # Edit draft fields
 ct invoice update <id> --subject "April Dev" --currency EUR --tax-rate <id>  # More fields
@@ -595,7 +602,7 @@ Read `references/commands.md` for the full reference of every command, subcomman
 12. **Output formats** — `ct report` supports `table`, `json`, `csv`, and `markdown` via `--format`; suggest `csv` for spreadsheet export, `markdown` for docs
 13. **Ask for details when vague** — if the user's request is ambiguous (e.g. "log 2 hours" with no description or project), ask them for the missing context rather than guessing. It's better to ask one clarifying question than to log something wrong that needs to be edited or deleted
 14. **Expenses** — when the user mentions expenses, receipts, or purchases, use the `ct expense` commands. Always suggest a category and ask if the expense is billable. If recording a billable expense for a client project, always set `--project` and `--billable` so it gets included automatically when the client is invoiced
-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`)
+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. Hours are shown per `--group-by`: `project`, `task` or `person` (one line each, per project, labelled with the period), `detailed` (one line per time entry; `--details` picks what each line shows from date, person, project, task, notes), `date`, or `none` (all on one line). Recurring templates take the same options. 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. **Permission errors are answers, not glitches** — the CLI now prints the server's reason on `403` (not your entry, already invoiced, no approval authority, read-only token, role too low) and on `400` validation errors (not assigned to the project, task not on the project). Relay the reason and the suggested alternative; do not retry the same command or look for another route to the same data. What each role can see is summarised under Team → Visibility rule and Organizations → Role hierarchy
 18. **Rate confidentiality** — rates, budgets, amounts, invoices and retainers are manager+ only (see Projects). If a member, viewer or project manager asks about rates or billed amounts, tell them it's restricted to account managers instead of trying workarounds

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/skills/crowdtime/references/commands.md

@@ -958,7 +958,11 @@ ct projects create NAME [options]
 | `--billable`, `-b` | flag | Billable (default: true) |
 | `--no-billable`, `-B` | flag | Non-billable |
 | `--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` |
+| `--fixed-fee` | float | Agreed price billed instead of logged hours. Implies `--billing-type fixed_fee`. The whole price for a one-off fee; the amount per period for a recurring one |
+| `--fee-schedule` | string | `one-off` (default) or `recurring` |
+| `--fee-frequency` | string | Recurring fee cadence: `weekly`, `biweekly`, `monthly`, `quarterly`. Implies `--fee-schedule recurring` |
+| `--payment` | string (repeatable) | One-off payment `NAME=AMOUNT` or `NAME=AMOUNT@YYYY-MM-DD`. Must add up to `--fixed-fee`. Omitted → one "Full payment" |
+| `--first-invoice` | string | Recurring fee: date of the first invoice. Default: one period after the project starts |
 | `--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 |
@@ -974,9 +978,13 @@ ct projects create NAME [options]
 | `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:
+> **Fixed-fee schedules.**
+> - **One-off** — the price is paid in payments (milestones) that add up to it. Each payment is billed **once**: naming the project on an invoice bills its next unbilled payment (or the ones picked with `--payment <id>`), and a fully billed project bills nothing. Voiding or deleting the invoice frees the payment again. A recurring template that lists the project bills the payments due by the end of the period it covers; payments without a due date are only billed by naming the project on an invoice. Duplicating an invoice leaves out its payment lines. Invoiced payments cannot be changed or removed.
+> - **Recurring** — the amount is billed every period. Creating the project (or switching it to recurring) sets up its own recurring invoice template with that cadence; changing the frequency updates it, and switching away, making it non-billable or archiving pauses it. If a hand-made template already bills the project, no second one is created.
+>
+> **How a fixed fee gets invoiced.** 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.
+> 2. a recurring template lists the project (including the one a recurring fee creates for itself).
 >
 > 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.
 
@@ -992,7 +1000,12 @@ ct projects create NAME [options]
 **Fixed-fee examples:**
 ```bash
 ct projects create "Rediseño Web" --client "Acme" --fixed-fee 10000
+ct projects create "Web" --client "Acme" --fixed-fee 5000 \
+  --payment Kickoff=1500@2026-06-01 --payment Midpoint=1500@2026-07-01 --payment Delivery=2000@2026-08-01
+ct projects create "Soporte" --client "Acme" --fixed-fee 4000 --fee-frequency monthly --first-invoice 2026-12-01
 ct projects update redesign --billing-type fixed --fixed-fee 12000
+ct projects update web --fixed-fee 6000 --payment Kickoff=1500 --payment Rest=4500  # Invoiced payments are kept
+ct projects update soporte --fee-frequency quarterly
 ct projects update redesign --billing-type tm --billing-mode per_person
 ```
 
@@ -2016,7 +2029,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] [--issue-date DATE] [--due-date DATE] [--notes NOTES] [--terms TEXT] [--json]
+ct invoice create --client CLIENT --from DATE --to DATE [--period PERIOD] [--group-by GROUP] [--details LIST] [--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`.
@@ -2028,7 +2041,9 @@ Creates an invoice from tracked time entries. Requires either `--from`/`--to` or
 | `--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` |
+| `--payment` | string (repeatable) | One-off fixed-fee payment ID(s) to bill (from `ct projects show`). Without it, each selected one-off project bills its next unbilled payment |
+| `--group-by` | string | How to display hours: `project`, `task`, `person` (alias `user`) — one line each, per project, e.g. "Website: Ana Pérez (Oct 1 – Oct 31, 2026)"; `detailed` — one line per time entry; `date`; `none` — all on one line. Omitted: by project, or the project's billing mode when one project is billed |
+| `--details` | string | With `detailed`: comma-separated `date`, `person`, `project`, `task`, `notes` (default `person,date,notes`), e.g. "10/23/2026 – Ana Pérez: Signup form". Implies `--group-by detailed` |
 | `--tax-rate` | float | Tax rate percentage (e.g. 21 for 21%) |
 | `--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 |
@@ -2048,10 +2063,12 @@ Billable time entries and expenses from the period are automatically imported as
 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 --group-by person  # One line per person on each project
+ct invoice create --client <id> --period last-month --group-by detailed --details date,task,notes  # One line per entry
 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
+ct invoice create --client <id> --period last-month --project <fixed-project-id>  # Bills the next payment / one period
+ct invoice create --client <id> --period last-month --project <fixed-project-id> --payment <payment-id>
 ```
 
 Endpoint: `POST /invoices/from-time-entries/`
@@ -2188,7 +2205,8 @@ ct invoice recurring create --name NAME --client CLIENT_ID --schedule SCHEDULE -
 | `--payment-terms` | integer | Payment terms in days |
 | `--auto-send` | flag | Auto-send generated invoices |
 | `--pull-entries/--no-pull-entries` | flag | Pull time entries (default: yes) |
-| `--group-by`, `-g` | string | Group by: `project`, `task`, `user`, `date`, `none` |
+| `--group-by`, `-g` | string | How to display hours: `project`, `task`, `person`, `detailed`, `date`, `none` (see `ct invoice create`) |
+| `--details` | string | With `detailed`: what each line shows (`date,person,project,task,notes`) |
 | `--notes` | string | Invoice notes |
 | `--terms` | string | Payment terms text |
 | `--json` | flag | JSON output |
@@ -2209,7 +2227,8 @@ ct invoice recurring update TEMPLATE_ID [options]
 | `--active/--inactive` | flag | Activate or deactivate |
 | `--auto-send/--no-auto-send` | flag | Auto-send setting |
 | `--payment-terms` | integer | Payment terms in days |
-| `--group-by`, `-g` | string | Group by setting |
+| `--group-by`, `-g` | string | How to display hours (see `ct invoice create`) |
+| `--details` | string | With `detailed`: what each line shows |
 | `--notes` | string | Invoice notes |
 | `--json` | flag | JSON output |
 

{crowdtime_cli-0.21.1 → crowdtime_cli-0.23.0}/src/crowdtime_cli/skills/crowdtime/references/workflows.md

@@ -278,6 +278,26 @@ ct projects update-member consulting-engagement senior@co.com --rate 200
 ct projects update-member consulting-engagement junior@co.com --rate 100
 ```
 
+### Set Up a Fixed-Fee Project
+
+First ask which kind of fixed fee it is — the two are billed very differently:
+
+```bash
+# One project price, paid in milestones (each invoiced exactly once)
+ct projects create "Website" --client "Acme" --fixed-fee 5000 \
+  --payment Kickoff=1500@2026-06-01 --payment Midpoint=1500@2026-07-01 --payment Delivery=2000@2026-08-01
+
+# Bill the next payment when it's time (see `ct projects show` for payment IDs)
+ct invoice create --client <client-id> --period this-month --project <project-id>
+
+# The same amount every month — a recurring invoice is created for it automatically
+ct projects create "Support" --client "Acme" --fixed-fee 4000 --fee-frequency monthly
+ct projects show support   # "Invoiced by:" names the template and its next run
+```
+
+Payments must add up to the price. Invoiced payments can't be changed or removed;
+void the invoice first if one was billed by mistake.
+
 ### Apply Task Presets to an Existing Project
 
 ```bash
@@ -310,7 +330,7 @@ When a project uses per-person billing, grouping the invoice by user gives clien
 
 ```bash
 # Create invoice grouped by team member
-ct invoice create --client "Acme Corp" --period last-month --group-by user --payment-terms net30
+ct invoice create --client "Acme Corp" --period last-month --group-by person --payment-terms net30
 
 # Add a line item with a discount (e.g. 2 hours courtesy)
 ct invoice add-item <invoice-id> --desc "Extra support" --qty 10 --rate 150 --discount-type hours --discount-value 2
@@ -1142,8 +1162,9 @@ ct invoice recurring generate-now <template-id> \
 ```
 
 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.
+pulled them. Fixed lines and recurring fixed fees can: they are billed in full
+on every run whatever the period, which is what the guard exists for. One-off
+fixed-fee payments are safe — each is billed only once.
 
 ---