merge: Google Kalender som menupunkt, med Verdandes egen kalender lagt over

Læs bredt, skriv snævert — decision 5 i planen, og kun den første halvdel:
kalenderen læses, og der skrives ingenting tilbage.

**OAuth-blokeringen er reel og blev ikke gået udenom.** En klient registreret som
*Internal* tager kun konti i sit eget workspace — også til kalendere, ikke kun
Gmail. Andreas' private konto bliver afvist med `org_internal`, og det er
klienten, der virker efter hensigten, ikke en fejl. Fladen siger det nu med ord,
man kan handle på, frem for at vise Googles egen skærm, der ikke gør.

Vejen udenom, som ikke er bygget: kalenderens egen hemmelige ICS-adresse. Ingen
OAuth, virker for enhver konto, og `internal/ics` findes allerede. Det er det
næste stykke, og det eneste, der låser den private konto op.

`internal/google` er flyttet ud af `internal/gmail`, fordi de to er det samme
flow, der er uenige om én streng. Egen callback-adresse frem for at dele Gmails:
én callback, der finder ud af hvilken token-butik den skal skrive i, går galt ved
at overskrive en Gmail-forbindelse, der virkede.

Egne tabeller frem for `mailboxes`. `trigger_kind`, `seen` og `last_uid` svarer
alle på "hvad gør en besked til en opgave", og ingenting her bliver til en
opgave; én konto har mange kalendere, og `mailboxes` har ikke plads til en
en-til-mange. Afgørende i praksis: `mailboxes.kind` har en CHECK, og SQLite kan
ikke ændre en — en tredje værdi koster den tabelombygning, som migration 0021
skulle igennem.

Begivenheder erstattes pr. kalender pr. vindue frem for at flettes med et
sync-token: et vindue, der slettes og skrives forfra, kan ikke komme ud af trit,
og et sync-token er endnu en ting, der skal være rigtig for altid, for at gitteret
ikke stille viser noget forkert.

`CalendarView` er udvidet, ikke kopieret. En begivenhed er et fyldt bånd, hvor en
opgave er et kort med en farvet kant, så de to læses forskelligt før et ord er
læst — og den kan ikke trækkes og er aldrig en knap: der er ikke noget at gøre
færdigt ved en andens møde.

To værn på det, der kommer fra Google: farven skal matche et hex-mønster, før den
må stå i en style, og linket bliver kun til et href, hvis det begynder med https.

Konflikten i jobs.go var to nye jobs skrevet på samme linje. Begge skal med.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/caldav.md

@@ -1,13 +1,14 @@
 # Calendar and CalDAV
 
-Two ways to get your tasks into a calendar, and they are not the same thing.
+Two ways to get your tasks into a calendar, one way to get a calendar into
+verdande, and none of the three is the same thing.
 
-| | [Feed](#subscribing-to-a-feed) | [CalDAV](#connecting-a-caldav-client) |
-|---|---|---|
-| Direction | Read only | Two-way |
-| Works with | Anything that subscribes to a URL | Apple Reminders, Thunderbird, DAVx⁵ |
-| You can tick things off | No | Yes |
-| Setup | Paste a URL | Username and token |
+| | [Feed](#subscribing-to-a-feed) | [CalDAV](#connecting-a-caldav-client) | [Google Calendar](#showing-a-google-calendar-in-verdande) |
+|---|---|---|---|
+| Direction | Tasks out, read only | Tasks out, two-way | Events **in**, read only |
+| Works with | Anything that subscribes to a URL | Apple Reminders, Thunderbird, DAVx⁵ | A Google account |
+| You can tick things off | No | Yes | No — an event is not a task |
+| Setup | Paste a URL | Username and token | Connect, then pick calendars |
 
 ## Subscribing to a feed
 
@@ -39,6 +40,42 @@ most people actually keep.
     **Settings → Calendar feed → Rotate** issues a new one and breaks the old
     immediately.
 
+## Showing a Google calendar in verdande
+
+The two sections above send your tasks *out*. This is the other direction: your
+Google calendar drawn underneath them, so one screen answers "what does this day
+already have in it".
+
+**Settings → Integrations → Google Calendar → Connect**, then tick the calendars
+you want and press Save. They appear in **Calendar** in the sidebar, in Google's
+own colour for each one, beside your own tasks with due dates.
+
+It needs the same OAuth client Gmail uses, with the Calendar API enabled and the
+second redirect URI registered — see [Configuration](configuration.md#google).
+
+!!! warning "Read only"
+    verdande never writes to your Google calendar. An event cannot be dragged,
+    edited or ticked off here; clicking one opens it in Google, which is where it
+    can be changed. Your own tasks in the same grid still drag to another day as
+    they always have.
+
+    Writing would need the `calendar.events` scope and an answer to what should
+    happen when both sides moved the same meeting — which is a synchronisation
+    model rather than a scope, and it is deliberately not built yet.
+
+!!! note "The Internal client applies here too"
+    An OAuth client registered as *Internal* in a Google Workspace can only be
+    used by accounts in that workspace, calendars included. A personal
+    `@gmail.com` address is refused with `org_internal`. For one personal account
+    the shorter road is the calendar's own secret address: in Google Calendar,
+    **Settings → the calendar → Integrate calendar → Secret address in iCal
+    format**. Nothing in verdande subscribes to one yet — it is the next piece of
+    this feature.
+
+Events are kept for ninety days back and a year forward, refreshed every fifteen
+minutes and whenever you press **Fetch now**. Paging the grid past that window
+says so rather than showing an empty month.
+
 ## Connecting a CalDAV client
 
 This is the one where ticking something off in Apple Reminders ticks it off here.

docs/configuration.md

@@ -39,12 +39,24 @@ Any Go duration: `720h`, `30m`, `45s`.
     yourself, password resets are written to the log, and reminders arrive in the
     app and as Web Push rather than by email.
 
-## Gmail
+## Google
 
-Only needed if anyone will connect a mailbox. Register an OAuth client in Google
-Cloud (**APIs & Services → Credentials → OAuth client ID → Web application**) with
-the redirect URI `https://your-address/oauth/gmail/callback`, enable the Gmail API,
-and add the `gmail.readonly` scope.
+Only needed if anyone will connect a Gmail mailbox or a Google calendar. One
+registration covers both: register an OAuth client in Google Cloud
+(**APIs & Services → Credentials → OAuth client ID → Web application**) and add
+**both** redirect URIs:
+
+```
+https://your-address/oauth/gmail/callback
+https://your-address/oauth/calendar/callback
+```
+
+Then enable the APIs and scopes for whichever you want:
+
+| For | Enable | Scope |
+|---|---|---|
+| Mailboxes | Gmail API | `gmail.readonly` |
+| Calendar | Google Calendar API | `calendar.readonly` |
 
 | Variable | What it does |
 |---|---|
@@ -52,8 +64,15 @@ and add the `gmail.readonly` scope.
 | `VERDANDE_GMAIL_CLIENT_SECRET` | The client secret. |
 
 One registration serves every user on the instance; each person authorises their
-own mailbox from **Settings → Gmail**. The redirect URI is derived from
-`VERDANDE_BASE_URL`, so it cannot drift out of step with what you registered.
+own mailbox from **Settings → Integrations → Gmail** and their own calendar from
+**Settings → Integrations → Google Calendar**. Both redirect URIs are derived from
+`VERDANDE_BASE_URL`, so they cannot drift out of step with what you registered.
+
+!!! note "Two connections, two grants"
+    Connecting a calendar does not disturb a working Gmail connection, and
+    disconnecting one does not take the other with it. Google issues a refresh
+    token per authorisation and keeps up to a hundred of them live per account,
+    each carrying only the scopes it was granted with.
 
 ## Secrets
 

docs/mailboxes.md

@@ -16,7 +16,7 @@ administrator who can read yours.
 **Settings → Integrations → Gmail → Connect.**
 
 Gmail needs an OAuth client, which is the instance's registration with Google
-rather than anybody's account — see [Configuration](configuration.md#gmail).
+rather than anybody's account — see [Configuration](configuration.md#google).
 Once it is set up, each person connects their own mailbox through it.
 
 Choose what makes a task:

docs/openapi.yaml

@@ -2654,6 +2654,126 @@ paths:
                   created: { type: integer }
         "502": { $ref: "#/components/responses/Upstream" }
 
+  /api/v1/calendar:
+    get:
+      tags: [integrations]
+      summary: The Google Calendar connection and the calendars in it.
+      description: |
+        Read-only. verdande shows a Google calendar beside its own dated tasks and
+        never writes one back — writing needs the `calendar.events` scope and an
+        answer to what happens when both sides moved the same meeting, which is a
+        synchronisation model rather than a scope.
+
+        The list of calendars is fetched from Google when it is empty, so an
+        account that connected during a hiccup corrects itself on the next look
+        rather than showing an empty panel for ever.
+      responses:
+        "200": { $ref: "#/components/responses/Calendar" }
+    delete:
+      tags: [integrations]
+      summary: Disconnect the calendar and forget its tokens.
+      description: >
+        The cached events go too. Unlike the tasks a mailbox made, none of this is
+        the person's own work — it is a copy of somebody else's calendar, and it
+        means nothing without the account.
+      responses:
+        "204": { description: Disconnected. }
+
+  /api/v1/calendar/calendars:
+    put:
+      tags: [integrations]
+      summary: Choose which calendars are drawn.
+      description: >
+        The whole set in one write rather than one flip at a time, for the reason
+        the projects' order is written the same way: the question is "these ones",
+        and a list built out of several requests can land half applied. A calendar
+        turned off has its cached events removed; they come back if it is turned
+        on again.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                shown:
+                  type: array
+                  items: { type: string }
+      responses:
+        "204": { description: Saved. }
+        "404": { $ref: "#/components/responses/NotFound" }
+
+  /api/v1/calendar/authorize:
+    post:
+      tags: [integrations]
+      summary: Begin the OAuth flow for a calendar.
+      description: |
+        The same registration Gmail signs in through, asking for
+        `calendar.readonly` and coming back to `/oauth/calendar/callback`. Google
+        issues a refresh token per authorisation, so connecting a calendar does not
+        disturb a working Gmail connection.
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  url: { type: string }
+        "409":
+          $ref: "#/components/responses/Conflict"
+
+  /api/v1/calendar/sync:
+    post:
+      tags: [integrations]
+      summary: Refresh the chosen calendars now.
+      description: >
+        Refreshes the list of calendars and replaces the cached window of events
+        for the ones that are shown. `partial` means the budget ran out before the
+        last calendar; what was read is kept, and the rest arrive on the next run.
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  events: { type: integer }
+                  partial: { type: boolean }
+        "502": { $ref: "#/components/responses/Upstream" }
+
+  /api/v1/calendar/events:
+    get:
+      tags: [integrations]
+      summary: The events of the chosen calendars, between two days.
+      description: |
+        Both ends inclusive, and an event that merely overlaps the range comes
+        back — a grid asks which cells an event covers, not where it begins.
+
+        `from` and `to` in the answer are the window verdande holds a copy of,
+        which is not the window that was asked for. A grid paged past it gets no
+        events, and an empty answer with no explanation is a calendar quietly
+        claiming a day is clear.
+      parameters:
+        - { name: from, in: query, required: true, schema: { type: string, format: date } }
+        - { name: to, in: query, required: true, schema: { type: string, format: date } }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  events:
+                    type: array
+                    items: { $ref: "#/components/schemas/CalendarEvent" }
+                  from: { type: string, format: date }
+                  to: { type: string, format: date }
+        "422": { $ref: "#/components/responses/Validation" }
+
   /api/v1/export/notes.zip:
     get:
       tags: [notes]
@@ -3297,6 +3417,26 @@ paths:
       responses:
         "302": { description: "Back into the app, with the outcome as a query parameter." }
 
+  /oauth/calendar/callback:
+    get:
+      tags: [integrations]
+      summary: Where Google sends the browser after consent to a calendar.
+      description: |
+        A URI of its own rather than a reuse of Gmail's. One callback deciding from
+        stored state which of the two flows had come back would put the choice of
+        which token store to write behind a lookup — and when that goes wrong it
+        goes wrong by overwriting a working Gmail connection with calendar tokens.
+
+        Answers with a redirect to `/indstillinger/integrationer`, not with JSON.
+        An `org_internal` error here means the OAuth app is registered as Internal
+        and the account is outside the organisation.
+      parameters:
+        - { name: code, in: query, schema: { type: string } }
+        - { name: state, in: query, schema: { type: string } }
+        - { name: error, in: query, schema: { type: string } }
+      responses:
+        "302": { description: "Back into the app, with the outcome as a query parameter." }
+
   /mcp:
     post:
       tags: [integrations]
@@ -3479,6 +3619,40 @@ components:
               email: { type: string }
               trigger: { type: string, enum: ["", starred, label, both] }
               label: { type: string }
+    Calendar:
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              connected: { type: boolean }
+              account:
+                type: string
+                description: >
+                  The address of the connected account, taken from the id of its
+                  primary calendar — which is where Google puts it, so no profile
+                  scope has to be asked for to learn it.
+              read_only:
+                type: boolean
+                description: >
+                  Always true today. Stated rather than assumed: an interface that
+                  quietly looks editable is one somebody will try to edit.
+              has_client:
+                type: boolean
+                description: >
+                  Whether an OAuth client is registered on this instance at all, so
+                  the page can explain rather than offer a button that answers 409.
+              redirect_uri:
+                type: string
+                description: >
+                  What has to be registered with Google, spelled out. Derived from
+                  VERDANDE_BASE_URL and matched exactly — the single most likely
+                  thing to be wrong, and the error Google gives names neither value.
+              last_sync_at: { type: string, format: date-time }
+              calendars:
+                type: array
+                items: { $ref: "#/components/schemas/Calendar" }
     ImportResult:
       description: Created
       content:
@@ -3496,6 +3670,62 @@ components:
                 items: { type: string }
 
   schemas:
+    Calendar:
+      type: object
+      description: >
+        One calendar inside a connected account. Kept whether or not it is shown,
+        so turning one off and on again gives back the same row.
+      properties:
+        id: { type: string }
+        remote_id: { type: string, description: "The id Google knows it by; an address for the primary calendar." }
+        name: { type: string }
+        colour:
+          type: string
+          description: >
+            Google's own hex value, not one of verdande's ten named colours. Those
+            are names so the interface can restyle them per theme and they are
+            verdande's palette; a Google calendar is told apart by the colour the
+            person already knows it by.
+        time_zone: { type: string }
+        primary: { type: boolean }
+        writable:
+          type: boolean
+          description: >
+            Whether the connected account could write to it. Nothing does — the
+            scope is read-only — and it is stored so the day something can, the
+            interface knows which calendars could even be offered.
+        shown: { type: boolean }
+
+    CalendarEvent:
+      type: object
+      description: >
+        One occurrence, in the shape a grid asks about. A recurrence is expanded by
+        Google into its occurrences, so what arrives here is a day, not a rule.
+      properties:
+        id: { type: string }
+        calendar_id: { type: string }
+        summary: { type: string }
+        starts_at:
+          type: string
+          description: >
+            RFC 3339 as Google wrote it, offset and all. Empty for an all-day
+            event, which has a day rather than a moment — inventing midnight for it
+            is how an event moves a day when a container moves time zone.
+        ends_at: { type: string }
+        start_day: { type: string, format: date }
+        end_day:
+          type: string
+          format: date
+          description: >
+            The last day the event covers, inclusive. Google's all-day end date is
+            exclusive and is corrected on the way in, once, rather than by every
+            reader.
+        all_day: { type: boolean }
+        location: { type: string }
+        url: { type: string, description: "Opens the event in Google's own interface." }
+        calendar_name: { type: string }
+        colour: { type: string }
+
     Note:
       type: object
       description: A page of Markdown. The body is the stored form and the exported form.