snitcher_reports 0.2.0

data/README.md

@@ -0,0 +1,685 @@
+# snitcher_reports
+
+> Embeddable multi-source work-report generator — Jira, ClickUp, Linear, Git, Google Calendar.
+
+A host application builds one `Snitcher::Client` from a config file plus **organization-level**
+credentials (read from the host's `ENV`), then generates a work report **per user** — selecting
+the user on each call. This is the multi-user path: one set of org credentials, many users of
+that organization.
+
+> **On the name.** The gem is named `snitcher_reports` because `snitcher` on RubyGems is an
+> unrelated Dead Man's Snitch client. The Ruby namespace and require path are unchanged:
+> `require "snitcher"` → `Snitcher::Client`.
+
+## What it does
+
+Aggregates completed work across trackers into a unified per-user report, so a host application
+does not have to talk to five APIs and reconcile their models. You get back a plain `Hash` — and,
+when you ask for a document, a Markdown or HTML file written to disk with its path in that Hash.
+
+### Data sources
+
+| Source | What it contributes |
+|---|---|
+| **Jira** | completed issues, tracked time |
+| **Git** | commits from a local checkout |
+| **ClickUp** | closed tasks, tracked time |
+| **Linear** | completed issues, tracked time |
+| **Google Calendar** | meeting time, reported separately from ticket time |
+
+Sources without credentials are skipped automatically — the skip is recorded in
+`failed_sources` (see below), so it never passes as a quiet week with nothing to report.
+By default every source above is requested, so a host that only uses, say, Git gets a
+`failed_sources` entry for each of the other four on every report. That is expected — "never
+configured" and "configured but broken" read identically in `failed_sources`, since neither
+has items to show — but if it is noise rather than signal for your setup, pass the sources
+you actually use explicitly (`sources: "git"`, or a comma-separated list) instead of relying
+on the default.
+
+### Output formats
+
+- **Hash** — data to compute with. The primary form; `Client#work_report` returns
+  the Hash directly.
+- **Markdown** — rich `.md` report with header, summary and per-source sections.
+- **HTML** — self-contained page with responsive design, stat cards and per-source tables;
+  includes "Print to PDF" buttons.
+
+The two document formats are written to disk and the call still returns the Hash, now
+carrying the file's path. See [Rendering a report](#rendering-a-report).
+
+## Install
+
+Add the gem to your host application's `Gemfile`:
+
+```ruby
+gem "snitcher_reports"
+```
+
+or install it directly with `gem install snitcher_reports`.
+
+## Configuration
+
+Static, non-secret configuration (status mappings, project/space filters, the git repo path
+and the work-email → git-email map) lives in a YAML file you point `config_path:` at. It uses
+the schema documented under [`.snitcher.yml` format](#snitcheryml-format):
+
+```yaml
+# config/snitcher.yml
+version: 1
+sources:
+  git:
+    # Absolute path to a local checkout of the repository to read commits from.
+    repo_path: /srv/app/repo
+    # Map each work email to the address that user commits under.
+    # Falls back to the requested user_email when there is no entry.
+    emails:
+      alice@corp.com: alice.private@gmail.com
+      bob@corp.com:   bob@corp.com
+```
+
+The file is optional and **backward compatible** — if it does not exist, every source falls
+back to its built-in defaults.
+
+### Credentials
+
+Secrets come from the **host's** `ENV` (org-level credentials), not the config file.
+Every variable may be given a `SNITCHER_` prefix, which is the recommended form when
+embedding: a host application's `.env` holds credentials for several libraries, and the
+prefix says at a glance which ones belong here.
+
+```bash
+# ClickUp
+SNITCHER_CLICKUP_API_TOKEN=...
+SNITCHER_CLICKUP_TEAM_ID=...
+# Jira
+SNITCHER_JIRA_URL=https://your-org.atlassian.net
+SNITCHER_JIRA_USERNAME=service-account@corp.com
+SNITCHER_JIRA_API_TOKEN=...
+# Linear
+SNITCHER_LINEAR_API_KEY=...
+```
+
+The unprefixed names (`CLICKUP_API_TOKEN`, `JIRA_URL`, …) remain fully supported. When both
+are present the prefixed one wins, so a leftover bare variable cannot silently shadow an
+explicit `SNITCHER_` declaration. See `.env.example` for the full list.
+
+| Source | Variables |
+|---|---|
+| Jira | `JIRA_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN` |
+| Linear | `LINEAR_API_KEY` |
+| ClickUp | `CLICKUP_API_TOKEN`, `CLICKUP_TEAM_ID` |
+| Google Calendar | `GOOGLE_SERVICE_ACCOUNT_JSON` (several users), or `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GOOGLE_REFRESH_TOKEN` (one user) |
+| Git | None (uses the current directory; override with `sources.git.repo_path`) |
+
+Jira is worth one note: Snitcher calls the Jira Cloud REST API v3 directly, authenticating
+with `JIRA_USERNAME` + `JIRA_API_TOKEN` as HTTP Basic. **Jira Data Center is not
+supported** — only `/rest/api/3` on Jira Cloud.
+
+For tickets with no worklogs, Snitcher reads time from the status history, which means it
+has to decide which statuses count as "in progress". It resolves that in three steps:
+
+1. the names under `sources.jira.*_statuses` in `.snitcher.yml`, if the status is listed
+   there — an explicit decision, so it wins;
+2. the instance's own status catalogue (`/rest/api/3/status`), which carries Jira's
+   language-independent `statusCategory` and therefore works on non-English instances;
+3. a small set of hardcoded English names (`In Progress`, `Done`, `To Do`, …), used only
+   when neither of the above answers.
+
+Step 2 means most instances need no `*_statuses` configuration at all. Configure it when
+your classification differs from Jira's own — for example to count `In Review` as active
+work when Jira files it under "To Do", or for a status Jira leaves in "No Category".
+
+`require "snitcher"` does **not** read a `.env` file — the embedded core takes the host
+application's `ENV` as-is.
+
+### `.snitcher.yml` format
+
+```yaml
+version: 1
+sources:
+  clickup:
+    # Optional: limit reports to specific ClickUp spaces.
+    # Omit or leave empty to include all spaces. Names are case-sensitive.
+    # This also limits where archived lists are looked for.
+    spaces:
+      - Engineering
+    done_statuses:
+      - "Zamkniete"
+      - "Done"
+    in_progress_statuses:
+      - "W trakcie"
+    todo_statuses:
+      - "Do zrobienia"
+  jira:
+    # Optional: limit reports to specific JIRA projects
+    projects:
+      - SCRUM
+    done_statuses:
+      - "Gotowe"
+    in_progress_statuses:
+      - "W realizacji"
+    todo_statuses:
+      - "Do zrobienia"
+  linear:
+    done_statuses:
+      - "Done"
+    in_progress_statuses:
+      - "In Progress"
+    todo_statuses:
+      - "Todo"
+  git:
+    # Optional: default git commit email used when work_report is called without
+    # a user_email. Ignored once user_email is supplied.
+    user: your.personal@email.com
+    # Optional: per-user git identities. Maps each work email (as passed in
+    # user_email: / user_emails:) to the git commit email(s) that person authors
+    # under. A value may be a single email or a list.
+    emails:
+      alice@corp.com: alice.personal@example.com
+      bob@corp.com:
+        - bob@corp.com
+        - bob.noreply@users.noreply.github.com
+    # Optional: path to the git repository (default: current directory).
+    repo_path: /path/to/your/project
+    # Optional: seconds any single git command may run before it is killed and the
+    # source is reported as failed (default: 30). Raise it for very large histories.
+    timeout: 30
+
+# Optional: filter calculated time to business hours.
+# Applies to Jira, ClickUp, Linear and Google Calendar meeting time.
+# Omit this block to keep raw wall-clock time calculation.
+# Note: start_hour must be earlier than end_hour (night shifts not supported); equal
+# hours are rejected too. A shared block that breaks this is ignored with a warning,
+# leaving time unfiltered; a person's block falls back to the shared one.
+working_hours:
+  timezone: "Europe/Warsaw"       # IANA timezone name
+  start_hour: "09:00"             # Work day start (HH:MM, must be quoted)
+  end_hour: "17:00"               # Work day end (HH:MM, must be quoted)
+  work_days: [1, 2, 3, 4, 5]      # Mon-Fri (0=Sun, 1=Mon, ..., 6=Sat)
+  holidays_region: "pl"           # ISO country code for public holiday exclusion (optional)
+
+  # Optional: per-person overrides, keyed by the work email reports are requested for
+  # (user_email: / user_emails:). A person inherits every key they leave out, and anyone
+  # not listed here uses the block above unchanged.
+  people:
+    bob@corp.com:
+      timezone: "America/New_York"
+      holidays_region: "us"
+    cara@corp.com:
+      end_hour: "15:00"
+
+# Optional: directory that saved markdown/html reports are written to.
+# Default: ./snitcher_reports (see "Where the file lands").
+output_dir: "tmp/snitcher_reports"
+```
+
+Status names are language-specific (Polish, German, …), so the values above are illustrative —
+replace them with the names your workspace actually uses. A `.snitcher.yml.example` ships with
+the gem as a starting point.
+
+`working_hours.people` resolves per the work email a report is requested for (`user_email:` /
+`user_emails:`). A person not listed there uses the shared block above unchanged; a person who is
+listed inherits every key they leave out from it. The resolved hours apply on both sides: the
+source-side time calculations (Jira changelog, Linear cycle time, ClickUp status history, Google
+Calendar meeting clamping) and the anomaly-side availability, expected working days and holiday
+exclusion.
+
+A malformed address under `sources.<name>.user` or `sources.<name>.emails` is warned about on
+stderr and dropped; the rest of the config still loads. An `emails` entry left with no valid
+address falls back to filtering by the work email itself, and a `user` left with none leaves
+that source out of a report run without `user_email:`, listed in `failed_sources`.
+
+## Usage
+
+```ruby
+require "snitcher"
+
+snitcher = Snitcher.new(config_path: "config/snitcher.yml")
+
+# One user:
+snitcher.work_report(user_email: "alice@corp.com", from: "2026-07-01", to: "2026-07-14")
+snitcher.work_report(user_email: "bob@corp.com",   from: "2026-07-01", to: "2026-07-14")
+
+# Many users in one call — reuses one Orchestrator, isolates per-user failures:
+reports = snitcher.work_reports(
+  user_emails: ["alice@corp.com", "bob@corp.com"],
+  from: "2026-07-01", to: "2026-07-14"
+)
+# => { "alice@corp.com" => { metadata:, anomalies:, items:, summary: },
+#      "bob@corp.com"   => { ... } }
+# A failed user: { "bob@corp.com" => { error: "...", error_class: "..." } }
+```
+
+Each call returns the same `Hash`:
+
+```ruby
+{
+  metadata:  { ... },  # user, date range, counts
+  anomalies: [ ... ],  # detected anomalies (empty when include_anomalies: false)
+  items:     [ ... ],  # the work items
+  summary:   { ... }   # aggregate totals
+}
+```
+
+### Check `failed_sources` before you trust the numbers
+
+A source that raises while fetching is logged and skipped so the rest of the report still
+renders; a source that was never available to start with — missing credentials, a
+misconfigured path — is skipped the same way, before it ever gets to fetch anything. Either
+way, its items are missing everywhere — items, totals and anomaly signals alike — and an
+outage looks exactly like a quiet week. The key is present **only** when something failed, so
+its absence means every requested source answered:
+
+```ruby
+report = snitcher.work_report(user_email: "alice@corp.com", from: "2026-03-01")
+
+if report[:metadata][:failed_sources]
+  # [{ source: "linear", error: "Snitcher::Error: Authentication required" },
+  #  { source: "git", error: "sources.git.repo_path (/srv/app/repo) is not a git checkout" }]
+  # error is a free-form sentence, not always "ExceptionClass: message" — don't parse its shape.
+  # Tell the user the report is partial, or retry — do not present it as complete.
+end
+```
+
+A source skipped for want of an identity lands here too: a `work_report` without `user_email:`
+whose `sources.<name>.user` holds no valid address reports that source as failed.
+
+Saved Markdown and HTML reports carry no such marker: they are the artefact a reader
+receives, and a broken credential is the operator's problem, not theirs. Surface the fact in
+your own UI if a person needs to see it.
+
+### Parameters
+
+- `user_email:` (`work_report`, optional) / `user_emails:` (`work_reports`, required) — the
+  user(s) to report on, resolved to a git commit email via `sources.git.emails` and falling
+  back to the value itself. When `user_email:` is omitted, `work_report` falls back to the
+  per-source default identity (`sources.<name>.user`) from the config file.
+- `from:` (required), `to:` (optional, defaults to today) — `YYYY-MM-DD`, `to` inclusive.
+- `sources:` (optional) — a Symbol/String, an Array, or a comma-separated String. `nil`,
+  `""`, or `"all"` select every multi-user source (git, jira, clickup, linear). An unknown
+  source raises `ArgumentError`.
+- `include_anomalies:` (optional, default `true`).
+- `format:` (optional, default `:hash`) — see [Rendering a report](#rendering-a-report). A
+  Symbol or String; an unknown value raises `ArgumentError`.
+- `narrative:` (optional) — prose rendered as an Overview section by the `:markdown` and
+  `:html` formats.
+- `output_dir:` / `output_path:` (optional) — where a saved document goes; see
+  [Where the file lands](#where-the-file-lands).
+
+### Thread safety
+
+The `Client` loads the configuration once at construction. Each `work_report` call builds
+its own orchestrator, so separate `work_report` calls are independent and safe to run from
+different threads. `work_reports` deliberately reuses a **single** orchestrator across the
+whole batch (to avoid re-initializing sources per user) and runs its users **sequentially** —
+do not parallelize a single `work_reports` call, as its sources hold per-batch state.
+
+## Rendering a report
+
+Pass `format:` to the same call. `Client` already knows the period, the working-hours
+config and which sources failed — everything the presenters need — so there is nothing to
+assemble by hand:
+
+```ruby
+report = snitcher.work_report(user_email: "alice@corp.com", from: "2026-07-01",
+                              to: "2026-07-14", format: :html)
+
+report[:metadata][:report_path]
+# => "/srv/app/snitcher_reports/alice-at-corp.com_2026-07-01_2026-07-14.html"
+```
+
+The three formats fall into two kinds:
+
+| `format:` | Returns | On disk |
+|---|---|---|
+| `:hash` (default) | the fact payload as a `Hash` | — |
+| `:markdown` | the payload, plus `metadata[:report_path]` | rich `.md` document |
+| `:html` | the payload, plus `metadata[:report_path]` | self-contained page |
+
+**A document format writes the file and still returns the payload.** Markdown and HTML are
+artefacts a person opens, not values a program computes with; handing back a
+multi-kilobyte String would leave every host to invent its own filename. So the gem writes
+it, and `metadata[:report_path]` (with `metadata[:report_format]`) says where. The key is
+present only when something was actually written, so its absence means "nothing was saved".
+
+The HTML output is self-contained — the logo is embedded as base64, so the page needs no
+external assets. An unknown format raises `ArgumentError` **before** any source is queried,
+so a typo costs no API calls.
+
+**There is no JSON format, on purpose.** The payload is a plain `Hash` with symbol keys, and
+serializing it is one call the host already knows how to make — `payload.to_json`,
+`JSON.pretty_generate(payload)`, `Oj.dump(payload)`, or `render json: payload` in a Rails
+controller. Owning a `:json` format would only mean one value of `format:` returning a
+`String` while the rest return a `Hash`, which every caller then has to special-case. Note
+that JSON turns the symbol keys into strings, so a round trip through JSON does not hand back
+an identical `Hash`.
+
+### Where the file lands
+
+In order of precedence:
+
+1. `output_path:` on the call — an exact file path, `work_report` only. Missing
+   directories are created.
+2. `output_dir:` on the call — a directory; the filename is generated.
+3. `output_dir:` in `.snitcher.yml` — the same, for every call.
+4. `./snitcher_reports/` — the fallback. Deliberately a subdirectory, not the working
+   directory itself: that is the host application's root, not the gem's to scatter files
+   across.
+
+Generated names are `<user>_<from>_<to>.<ext>` (`alice-at-corp.com_2026-07-01_2026-07-14.html`),
+so regenerating the same report for the same period **overwrites** it rather than piling
+up copies. Pass `output_path:` if you want a name of your own.
+
+`work_reports` takes `format:` and `output_dir:` too, and writes one document per user —
+named after that user, since one shared path would have the last user overwrite everyone
+before them. There is no `output_path:` counterpart for that reason:
+
+```ruby
+reports = snitcher.work_reports(user_emails: %w[alice@corp.com bob@corp.com],
+                                from: "2026-07-01", format: :html,
+                                output_dir: "tmp/reports")
+
+reports.each do |email, report|
+  next puts "#{email}: #{report[:error]}" if report[:error]
+
+  puts "#{email}: #{report[:metadata][:report_path]}"
+end
+```
+
+`Snitcher::Report` remains public for the case where you already hold work items from
+somewhere other than a `work_report` call. It only renders — writing is `ReportWriter`'s
+job — and building it yourself means building its `config` yourself: omit
+`since:`/`until_time:` and you lose the report header and every period-aware anomaly rule.
+
+### Narrative summaries
+
+Pass `narrative:` and the Markdown and HTML formats render it as an Overview section:
+
+```ruby
+snitcher.work_report(user_email: "alice@corp.com", from: "2026-07-01",
+                     format: :markdown, narrative: my_summary_text)
+```
+
+For a batch, give `work_reports` a Hash keyed by the requested email — one prose summary per
+person — or a single String to caption every report:
+
+```ruby
+snitcher.work_reports(user_emails: %w[alice@corp.com bob@corp.com], from: "2026-07-01",
+                      format: :markdown,
+                      narrative: { "alice@corp.com" => "Shipped the parser rewrite." })
+```
+
+The gem ships **no** LLM integration. The slot is there so a host that already has a model
+available can generate the prose with it and pass the string in; without it the section is
+simply omitted.
+
+## Google Calendar Setup
+
+The Google Calendar source reports **meeting time** — how many hours went into meetings during
+the report period. Meetings appear in a dedicated **Meetings** section (recurring series
+collapsed to one row each) and are kept separate from tracked ticket time.
+
+There are two ways to authenticate. Pick one.
+
+| | Service account | OAuth2 |
+|---|---|---|
+| Reports on | any number of users | one user |
+| Whose calendar | each reported user's own | the account you signed in with |
+| Setup needs | Google Cloud + Workspace Admin access | a Google account |
+| Variable | `GOOGLE_SERVICE_ACCOUNT_JSON` | the three `GOOGLE_*` values below |
+
+If both are configured, the service account is used and Snitcher prints a warning.
+
+### Service account (several users)
+
+To report on more than one person, use a Google Cloud service account with domain-wide
+delegation.
+
+1. In the [Google Cloud Console](https://console.cloud.google.com/), create or pick a project.
+   Under **APIs & Services → Library**, enable the **Google Calendar API**. The API is free.
+2. Create a service account and a JSON key for it.
+3. In the Google Workspace Admin console, go to **Security → Access and data control → API
+   controls → Domain-wide delegation**. Add the service account's numeric client ID (it is in
+   the key file) and authorize the scope
+   `https://www.googleapis.com/auth/calendar.events.readonly`.
+   This step is what makes impersonation work. Most setup problems come from skipping it.
+4. **Put the key in the host's environment, base64-encoded.** The key file is multi-line JSON,
+   with braces, quotes and `\n` sequences inside the private key. An environment variable must
+   be one line, so the file cannot go there as it is. Base64 turns it into a single line of
+   plain characters.
+
+   Run this from the directory that holds your `.env`, with the path to your own key file:
+
+   ```bash
+   echo "GOOGLE_SERVICE_ACCOUNT_JSON=$(ruby -rbase64 -e 'print Base64.strict_encode64(File.binread(ARGV[0]))' key.json)" >> .env
+   ```
+
+   It appends one finished line to `.env`. There is nothing else to edit. You can then move
+   `key.json` out of the project or delete it, because Snitcher reads only the variable.
+
+Each reported user's own `primary` calendar is read, so
+`work_reports(user_emails: ["a@corp.com", "b@corp.com"])` gives one report per person. Set
+`sources.google_calendar.calendar_id` and every reported user reads that one calendar instead.
+Each user is still authenticated as themselves, so Google checks their access.
+
+`sources.google_calendar.emails` must give one address per person. Two addresses for one
+person is an error: the calendar section is skipped with a warning and the rest of the report
+still renders.
+
+### OAuth2 (one user)
+
+OAuth2 reads the calendar of one Google account. The requested `user_email:` does not change
+which calendar is read. It needs a one-time bootstrap to obtain a long-lived `refresh_token`.
+You only do this once per machine.
+
+1. **Create a Google Cloud project and enable the API.** Go to the
+   [Google Cloud Console](https://console.cloud.google.com/), create (or pick) a project, then under
+   **APIs & Services → Library** enable the **Google Calendar API**.
+2. **Create an OAuth 2.0 Client ID.** Under **APIs & Services → Credentials → Create Credentials →
+   OAuth client ID**, choose application type **Web application** (not "Desktop app" — the OAuth
+   Playground used in step 3 needs a registered redirect URI, which Desktop clients do not support).
+   Under **Authorized redirect URIs** click **Add URI** and enter exactly:
+   ```
+   https://developers.google.com/oauthplayground
+   ```
+   (no trailing slash, and it goes in **Authorized redirect URIs** — *not* "Authorized JavaScript
+   origins", which rejects paths). Save, then note the generated **Client ID** and **Client secret**.
+   If prompted, configure the OAuth consent screen first and add your own Google account as a test user.
+
+   > **Token lifetime — important.** A consent screen left in **Testing** mode issues refresh tokens
+   > that **expire after 7 days**, after which the report stops working until you repeat step 3. For a
+   > token that does not expire, publish the app: **APIs & Services → OAuth consent screen** (or
+   > **Google Auth Platform → Audience**) → **Publish app** → status **In production**. For a read-only
+   > calendar scope and personal use, publishing does not require Google's app-verification review.
+   > After publishing, re-run step 3 to mint a fresh, durable token.
+3. **Obtain a `refresh_token`** for the read-only scope
+   `https://www.googleapis.com/auth/calendar.events.readonly`. The simplest path is the
+   [OAuth 2.0 Playground](https://developers.google.com/oauthplayground/):
+   1. Click the gear icon (⚙, top right) → check **Use your own OAuth credentials** and paste your
+      Client ID and Client secret from step 2.
+   2. In **Step 1 (Select & authorize APIs)**, paste the scope
+      `https://www.googleapis.com/auth/calendar.events.readonly` into the input box and click
+      **Authorize APIs**. Sign in with the Google account whose calendar you want to report on and
+      grant access.
+   3. In **Step 2**, click **Exchange authorization code for tokens**. Copy the **Refresh token** value.
+
+   > For the Playground to return a refresh token, your client must be authorized for it. If you ever
+   > need to re-issue the token, revoke the app's access at
+   > [myaccount.google.com/permissions](https://myaccount.google.com/permissions) and repeat steps i–iii.
+   >
+   > **Hitting `Error 400: redirect_uri_mismatch`?** The Client ID pasted into the Playground (⚙) must
+   > be the *same* client whose **Authorized redirect URIs** include `https://developers.google.com/oauthplayground`
+   > (see step 2). A common cause is editing the redirect URI on one client while the Playground still
+   > holds a different client's ID. Re-check both, then refresh the Playground page; newly added URIs
+   > can also take a minute to propagate.
+4. **Put the three values in the host's environment:**
+   ```bash
+   GOOGLE_CLIENT_ID=...        # from step 2
+   GOOGLE_CLIENT_SECRET=...    # from step 2
+   GOOGLE_REFRESH_TOKEN=...    # from step 3
+   ```
+   The report reads the authenticated account's `primary` calendar. To read a different calendar, set
+   `sources.google_calendar.calendar_id` in the config file (the calendar's ID, e.g. an email-like
+   address from Google Calendar settings). On this path `user_email:` does **not** select a calendar —
+   every reported user gets the same account's meetings.
+
+   To cover several people without a service account, run one report per person, each with that
+   person's own `GOOGLE_REFRESH_TOKEN` in the environment.
+5. **Filtering rules.** These events are excluded automatically: meetings that have not finished yet,
+   declined invitations, all-day events, and solo events (no other attendees — e.g. personal focus
+   blocks). When a `working_hours` block is configured, meeting time outside business hours is dropped
+   and partial overlaps are clamped. Meeting time is reported separately from tracked ticket time, so
+   it never inflates the "Total tracked time" / "Hours Logged" figures.
+6. **A report that includes today stops at the current moment.** Meetings scheduled for later today
+   are not counted, and neither is a meeting you are in right now — it appears once it is over. The
+   reported period still shows the full range you asked for, so a report generated at 11:00 for today
+   says `2026-08-21`, not `2026-08-21 11:00`. A report for a range that lies entirely in the future
+   returns no meetings.
+
+### Multi-user needs a service account
+
+Whether `google_calendar` can serve a multi-user report depends on the credentials you
+configured.
+
+With `GOOGLE_SERVICE_ACCOUNT_JSON` set, it works like every other source: each requested
+`user_email` is impersonated and gets their own calendar. It is part of the default source set.
+
+With only an OAuth token, it reads one fixed account and cannot honour a requested
+`user_email`. It is then left out of the default source set, and a host that asks for it by
+name (`sources: "google_calendar"`) gets a warning on stderr and no calendar section.
+
+## Git source details
+
+The Git source parses the local commit history of the checkout at `sources.git.repo_path`
+(default: the current directory) to find work items. It generates **commit links** by resolving
+the `origin` remote URL into a browsable HTTPS URL (supports SCP-style SSH, `ssh://`, and HTTPS
+remotes). Repos without an `origin` remote produce work items without links.
+
+Git items carry no time-tracking data — use the Jira, Linear or ClickUp sources for tracked time.
+
+**When git fails.** A git command that exits non-zero fails the source: it lands in
+`metadata[:failed_sources]` and warns on stderr, exactly like a Jira or ClickUp outage. This
+matters because the alternative — an empty list — is indistinguishable from a period in which
+nobody committed, and a report cannot tell you which one it is looking at. A command that hangs
+is killed after `sources.git.timeout` seconds (default 30) and fails the same way, so one stuck
+process cannot wedge a batch of reports.
+
+**When there is simply nothing to report.** Zero items is a legitimate answer and never a
+failure, in both the ways it happens:
+
+- the checkout has commits, none in the requested window — `git log` exits zero with no
+  output, and always has;
+- the checkout has **no commits at all** — a fresh `git init`, or a branch nobody has
+  committed to. `git log` exits 128 for this, the same as for a broken checkout, so the two
+  are told apart structurally rather than by reading git's (localised) wording: for an
+  unborn HEAD the repository itself still resolves (`git rev-parse --git-dir` succeeds) and
+  only `HEAD` does not. Nothing is reported as failed.
+
+Two further failures are tolerated, because for them a non-zero exit is an ordinary answer
+rather than an outage. Both warn on stderr and cost one detail:
+
+- no `origin` remote — the items are correct, they just carry no commit links;
+- `git diff` against the parent of a **root commit**, which has none — that item's
+  `lines_added`/`lines_deleted`/`files_changed` read as zero.
+
+## System dependencies
+
+- **Git** — reads commits from a **local checkout** on the host; set `sources.git.repo_path`
+  to that checkout. The host machine needs the `git` binary.
+
+## Architecture
+
+`Snitcher.new` returns a `Client`, the one public entry point. Everything below it is a plain
+object graph — no global state, no CLI, no daemon:
+
+```
+Snitcher.new  →  Snitcher::Client  →  ReportService  →  Orchestrator  →  Sources::*
+                                            └──────────→  Report  ─┬→  #json_payload  (Hash)
+                                                                   └→  Presenters::*  (String)
+                                                                          └→  ReportWriter  (file)
+                                                       AnomalyDetector → AnomalyRules::*
+```
+
+`Client` resolves which sources can serve the requested user and delegates to `ReportService`,
+which parses the date range, runs the `Orchestrator` over the selected sources and hands the
+resulting work items to `Report`. `Orchestrator` degrades rather than aborts: a source that
+raises, or that was never available to start with, is recorded in `failed_sources` and the
+rest of the report still renders.
+
+```
+lib/
+  snitcher.rb              # entry point, Zeitwerk autoloader setup
+  snitcher/
+    version.rb
+    client.rb              # the public facade: work_report / work_reports
+    report_service.rb      # parameters → Orchestrator + Report → Hash (saving the document)
+    report_writer.rb       # writes markdown/html to disk, returns the path
+    work_item.rb           # common data model
+    configuration.rb       # YAML config loader and validator (read-only)
+    jql_validator.rb       # JQL query sanitization
+    validators.rb          # input validation utilities
+    time_formatter.rb      # duration formatting
+    working_hours_calculator.rb  # business hours time filtering
+    holiday_region_resolver.rb   # timezone → holidays gem region mapping
+    sources/
+      source.rb            # base class for all sources
+      jira.rb              # Jira Cloud REST API v3
+      jira/client.rb       # Faraday transport
+      jira/status_categories.rb  # status id → category map
+      git.rb               # local git log
+      git/command_runner.rb  # git subprocess transport (timeout, failure reporting)
+      linear.rb            # Linear GraphQL API
+      clickup.rb           # ClickUp REST API
+      clickup/archived_lists.rb  # tasks that live in archived lists
+      clickup/working_hours_filter.rb  # working hours applied to status history
+      google_calendar.rb   # Google Calendar meeting time
+    presenters/
+      presenter.rb         # shared presenter module (escaping, truncation, total_seconds)
+      markdown.rb          # rich .md report presenter
+      html.rb              # self-contained HTML report presenter
+    templates/
+      report.html.erb      # ERB template for HTML reports
+      snitcher-logo.png    # embedded as base64 by the HTML presenter
+    orchestrator.rb        # coordinates all sources
+    meetings_aggregator.rb # collapses calendar items into per-series meeting rows
+    report.rb              # format dispatch (presenter registry)
+    anomaly.rb             # anomaly value object
+    anomaly_context.rb     # inputs shared by every rule
+    anomaly_detector.rb    # runs the rule registry
+    anomaly_rules/         # one file per rule
+```
+
+### Adding a new source
+
+1. Create `lib/snitcher/sources/github.rb` inheriting from `Source`
+2. Implement `source_name`, `available?`, and `fetch`; optionally override
+   `unavailable_reason` to say which setting is missing
+3. Add it to `Orchestrator::SOURCE_MAP`
+4. Add its env vars to `.env.example`
+
+No changes are needed to the orchestrator logic or the report formatter.
+
+## Development
+
+Ruby 3.4.4 (pinned in `.ruby-version`).
+
+```bash
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Run linter
+bundle exec rubocop
+```
+
+## Releasing
+
+1. Bump `Snitcher::VERSION` in `lib/snitcher/version.rb` and add a section to `CHANGELOG.md`.
+2. Merge to `master`, then tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+3. The `Release` workflow publishes the gem to RubyGems via
+   [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (no API key stored).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).