docs: how-to guides for time management

Author: thekaveman

docs/guides/time/convert.md

@@ -0,0 +1,70 @@
+# How to Convert Time Reports
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin time convert` reference section](../../reference/cli/time.md#compiler-admin-time-convert).
+
+This guide explains how to use the `compiler-admin time convert` command to convert a time report from one format (like Toggl) to another (like Harvest or Justworks).
+
+## Basic Usage
+
+The `convert` command reads from an input source, which defaults to `toggl` format, and writes to an output source, which defaults to `harvest` format.
+
+The simplest usage reads from standard input and writes to standard output:
+
+```bash
+cat toggl-report.csv | compiler-admin time convert > harvest-report.csv
+```
+
+## Specifying Input and Output Files
+
+For clarity, it's often better to use the `--input` and `--output` flags.
+
+```bash
+compiler-admin time convert --input toggl-report.csv --output harvest-report.csv
+```
+
+## Specifying Conversion Formats
+
+You can explicitly define the source and destination formats using the `--from` and `--to` flags.
+
+### Convert from Toggl to Harvest
+
+```bash
+compiler-admin time convert \
+  --from toggl \
+  --to harvest \
+  --input toggl-export.csv \
+  --output harvest-import.csv
+```
+
+### Convert from Harvest to Toggl
+
+```bash
+compiler-admin time convert \
+  --from harvest \
+  --to toggl \
+  --input harvest-export.csv \
+  --output toggl-import.csv
+```
+
+### Convert from Toggl to Justworks
+
+```bash
+compiler-admin time convert \
+  --from toggl \
+  --to justworks \
+  --input toggl-export.csv \
+  --output justworks-import.csv
+```
+
+## Setting a Client Name
+
+When converting, you may need to specify a client name for the destination format. Use the `--client` option for this.
+
+```bash
+compiler-admin time convert \
+  --input toggl.csv \
+  --output harvest.csv \
+  --client "Specific Client Name"
+```

docs/guides/time/download.md

@@ -0,0 +1,53 @@
+# How to Download a Toggl Time Report
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin time download` reference section](../../reference/cli/time.md#compiler-admin-time-download).
+
+This guide explains how to use the `compiler-admin time download` command to download a detailed time report from Toggl in CSV format.
+
+## Basic Usage
+
+To download a report for the previous calendar month (the default behavior):
+
+```bash
+compiler-admin time download
+```
+
+This will create a CSV file in the current directory named `Toggl_time_entries_[start-date]_[end-date].csv`.
+
+## Specifying a Date Range
+
+You can specify a custom date range using the `--start` and `--end` options. The date format is `YYYY-MM-DD`.
+
+```bash
+compiler-admin time download --start 2025-01-01 --end 2025-01-31
+```
+
+## Specifying an Output File
+
+To save the report to a specific file path, use the `--output` option.
+
+```bash
+compiler-admin time download --output /path/to/my-report.csv
+```
+
+## Filtering the Report
+
+The command provides several options for filtering the time entries included in the report:
+
+- `--all`: Include all time entries, not just billable ones.
+- `-c, --client CLIENT_ID`: Filter by a specific Toggl client ID.
+- `-p, --project PROJECT_ID`: Filter by a specific Toggl project ID.
+- `-t, --task TASK_ID`: Filter by a specific Toggl task ID.
+- `-u, --user USER_ID`: Filter by a specific Toggl user ID.
+
+You can use these options multiple times to include multiple IDs.
+
+### Example
+
+To download all billable time entries for Project ID `12345` and `67890` for the prior month:
+
+```bash
+compiler-admin time download -p 12345 -p 67890
+```

docs/guides/time/lock.md

@@ -0,0 +1,31 @@
+# How to Lock Time Entries in Toggl
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin time lock` reference section](../../reference/cli/time.md#compiler-admin-time-lock).
+
+This guide explains how to use the `compiler-admin time lock` command to lock time entries in Toggl, preventing them from being edited.
+
+This is typically the first step before downloading and preparing time reports.
+
+You can see the current lock date at <https://track.toggl.com/${TOGGL_WORKSPACE_ID}/settings/general>.
+
+## Basic Usage
+
+To lock time entries up to the last day of the previous calendar month (the default behavior), run the command without any options:
+
+```bash
+compiler-admin time lock
+```
+
+The command will print the date it is locking entries up to and ask for confirmation before proceeding.
+
+## Specifying a Lock Date
+
+You can lock entries up to any specific date using the `--date` option. The date format is `YYYY-MM-DD`.
+
+For example, to lock all entries on or before January 31, 2025:
+
+```bash
+compiler-admin time lock --date 2025-01-31
+```

docs/guides/time/run-github-workflow.md

@@ -0,0 +1,48 @@
+# How to Run the Monthly Time Reporting GitHub Actions Workflow
+
+This guide explains how to manually trigger and monitor the `Monthly Time Reporting` GitHub Actions workflow, which automates the process of downloading, converting, verifying, and posting monthly time reports.
+
+## Overview
+
+The workflow performs the following automated steps:
+
+- **Lock Toggl time entries**: Locks time entries in Toggl up to the specified `end-date` (or end of prior month).
+- **Download Toggl time entries**: Downloads a detailed CSV report from Toggl.
+- **Convert Toggl entries to Harvest format**: Converts the downloaded report into a Harvest-compatible CSV.
+- **Verify time entries**: Compares the downloaded and converted files to ensure data integrity, and generates a summary.
+- **Post to Slack**: Sends the summary and the converted Harvest CSV to a designated Slack channel.
+
+This workflow ensures that monthly time reporting is consistent and automated.
+
+## Prerequisites
+
+To run this workflow, you must have:
+
+- Write access to the GitHub repository.
+- The necessary GitHub Secrets configured in the repository settings. These secrets include API tokens and configuration for Toggl, Harvest, Google Workspace (GAM), and Slack. Without these, the workflow will fail.
+
+## Locating the Workflow
+
+The workflow definition file is located at:
+[`./.github/workflows/time-reporting.yml`](https://github.com/compilerla/compiler-admin/blob/main/.github/workflows/time-reporting.yml)
+
+## Manually Triggering the Workflow
+
+To manually trigger the workflow:
+
+1. Navigate to the [**Actions**](https://github.com/compilerla/compiler-admin/actions) tab in the GitHub repository.
+2. In the left sidebar, click on the **Monthly Time Reporting** workflow.
+3. On the workflow page, click the **Run workflow** dropdown button.
+4. Leave the `Branch: main` selection as-is.
+5. You will see optional input fields for `start-date` and `end-date`.
+   - If left blank, the workflow will default to the previous calendar month.
+   - Enter dates in `YYYY-MM-DD` format if you need to process a specific period.
+6. Click the green **Run workflow** button to start the execution.
+
+## Monitoring a Workflow Run
+
+After triggering, you will be redirected to the workflow run page (you may need to refresh).
+
+1. Click on the active workflow run to view its progress.
+2. You can expand each job step (e.g., "Lock Toggl time entries", "Download Toggl time entries", "Verify time entries") to see its detailed output.
+3. The final step, "Post to Slack", will send a summary of the time report to the configured Slack channel and upload the converted Harvest CSV file.

docs/guides/time/verify.md

@@ -0,0 +1,68 @@
+# How to Verify Time Reports
+
+!!! seealso "Full Command Reference"
+
+    For a complete reference of all options, see the [`compiler-admin time verify` reference section](../../reference/cli/time.md#compiler-admin-time-verify).
+
+This guide explains how to use the `compiler-admin time verify` command to check the contents of time report CSV files.
+
+You can use this command in two ways:
+
+1. To get a summary of a single time report.
+2. To compare two different time reports (e.g., a Toggl export and a converted Harvest file) to ensure they match.
+
+## Summarizing a Single Report
+
+To see a summary of a single CSV file, provide its path to the command:
+
+```bash
+compiler-admin time verify toggl-report.csv
+```
+
+The output will show you a summary of the data in that file, including:
+
+- Date range
+- Total number of entries
+- Total hours
+- Hours broken down by project
+- Hours broken down by user and project
+
+```text
+Summary for: toggl-report.csv
+  Date range: 2025-09-01 - 2025-09-30
+
+  Total entries: 150
+  Total hours: 160.0
+  Project A: 80.0
+  Project B: 50.0
+  Project C: 30.0
+
+  user1@example.com:
+    Project A: 40.0
+    Project B: 20.0
+  user2@example.com:
+    Project A: 40.0
+    Project B: 30.0
+    Project C: 30.0
+```
+
+## Comparing Two Reports
+
+To verify that a conversion was successful, you can provide two file paths. The command will compare their summaries.
+
+The tool automatically detects the file format (Toggl or Harvest) and normalizes the data so that a meaningful comparison can be made.
+
+```bash
+compiler-admin time verify toggl-report.csv harvest-report.csv
+```
+
+If the reports match, the command will output "Summaries match." and exit successfully.
+
+If there are differences in total hours, projects, or other details, the command will print a list of the discrepancies and exit with an error.
+
+```text
+Summaries do not match:
+- Total hours: 160.0 vs 155.0
+  Project 'Project B' hours: 50.0 vs 45.0
+  User 'user1@example.com', Project 'Project B' hours: 20.0 vs 15.0
+```

mkdocs.yml

@@ -10,6 +10,13 @@ nav:
       - Monthly Time Reporting: tutorials/monthly-time-reporting.md
       - Onboarding a User: tutorials/onboarding-a-user.md
       - Offboarding a User: tutorials/offboarding-a-user.md
+  - How-to Guides:
+      - Time Management:
+          - Download a Toggl Report: guides/time/download.md
+          - Convert Time Reports: guides/time/convert.md
+          - Lock Time Entries: guides/time/lock.md
+          - Verify Time Reports: guides/time/verify.md
+          - Run GitHub Actions Workflow: guides/time/run-github-workflow.md
   - Reference:
       - Configuration: reference/configuration.md
       - CLI Reference: