From de177b78b94a2fe34024aa4ad897a5041147b5db Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Thu, 5 Mar 2026 01:18:04 -0500
Subject: [PATCH] docs(sync): document bundled credentials and config fields

---
 doc/pending.txt | 53 +++++++++++++++++++++++++++++++++++++------------
 1 file changed, 40 insertions(+), 13 deletions(-)

diff --git a/doc/pending.txt b/doc/pending.txt
index 08c6315..d3eb03b 100644
--- a/doc/pending.txt
+++ b/doc/pending.txt
@@ -608,11 +608,8 @@ loads: >lua
       sync = {
         gcal = {
           calendar = 'Pendings',
-          credentials_path = '/path/to/client_secret.json',
-        },
-        gtasks = {
-          credentials_path = '/path/to/client_secret.json',
         },
+        gtasks = {},
       },
     }
 <
@@ -683,7 +680,9 @@ Fields: ~
     {sync}               (table, default: {})          *pending.SyncConfig*
                          Sync backend configuration. Each key is a backend
                          name and the value is the backend-specific config
-                         table. Currently only `gcal` is built-in.
+                         table. Built-in backends: `gcal`, `gtasks`. Both
+                         ship bundled OAuth credentials so no setup is
+                         needed beyond `:Pending <backend> auth`.
 
     {icons}              (table)                          *pending.Icons*
                          Icon characters displayed in the buffer. The
@@ -934,12 +933,14 @@ Configuration: >lua
       sync = {
         gcal = {
           calendar = 'Pendings',
-          credentials_path = '/path/to/client_secret.json',
         },
       },
     }
 <
 
+No configuration is required to get started — bundled OAuth credentials are
+used by default. Run `:Pending gcal auth` and the browser opens immediately.
+
                                                           *pending.GcalConfig*
 Fields: ~
     {calendar}           (string, default: 'Pendings')
@@ -947,13 +948,27 @@ Fields: ~
                          with this name does not exist it is created
                          automatically on the first sync.
 
-    {credentials_path}   (string)
-                         Path to the OAuth client secret JSON file downloaded
+    {client_id}          (string, optional)
+                         OAuth client ID. When set together with
+                         {client_secret}, these take priority over the
+                         credentials file and bundled defaults.
+
+    {client_secret}      (string, optional)
+                         OAuth client secret. See {client_id}.
+
+    {credentials_path}   (string, optional)
+                         Path to an OAuth client secret JSON file downloaded
                          from the Google Cloud Console. Default:
                          `stdpath('data')..'/pending/gcal_credentials.json'`.
                          The file may be in the `installed` wrapper format
                          that Google provides or as a bare credentials object.
 
+Credential resolution: ~
+Credentials are resolved in order:
+1. `client_id` + `client_secret` config fields (highest priority).
+2. JSON file at `credentials_path` (or the default path).
+3. Bundled credentials shipped with the plugin (always available).
+
 OAuth flow: ~
 On the first `:Pending gcal` call the plugin detects that no refresh token
 exists and opens the Google authorization URL in the browser using
@@ -988,22 +1003,34 @@ created automatically on first sync.
 Configuration: >lua
     vim.g.pending = {
       sync = {
-        gtasks = {
-          credentials_path = '/path/to/client_secret.json',
-        },
+        gtasks = {},
       },
     }
 <
 
+No configuration is required to get started — bundled OAuth credentials are
+used by default. Run `:Pending gtasks auth` and the browser opens immediately.
+
                                                         *pending.GtasksConfig*
 Fields: ~
-    {credentials_path}   (string)
-                         Path to the OAuth client secret JSON file downloaded
+    {client_id}          (string, optional)
+                         OAuth client ID. When set together with
+                         {client_secret}, these take priority over the
+                         credentials file and bundled defaults.
+
+    {client_secret}      (string, optional)
+                         OAuth client secret. See {client_id}.
+
+    {credentials_path}   (string, optional)
+                         Path to an OAuth client secret JSON file downloaded
                          from the Google Cloud Console. Default:
                          `stdpath('data')..'/pending/gtasks_credentials.json'`.
                          Accepts the `installed` wrapper format or a bare
                          credentials object.
 
+Credential resolution: ~
+Same three-tier resolution as the gcal backend (see |pending-gcal|).
+
 OAuth flow: ~
 Same PKCE flow as the gcal backend; listens on port 18393. Tokens are stored
 at `stdpath('data')/pending/gtasks_tokens.json`. Run `:Pending gtasks auth`