docs(skills): document first-time gws setup

.changeset/document-gws-skill-setup.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Document first-time installation and OAuth setup for the Google Chat agent skill.

crates/google-workspace-cli/src/generate_skills.rs

@@ -685,7 +685,96 @@ metadata:
 
 ## Installation
 
-The `gws` binary must be on `$PATH`. See the project README for install options.
+The `gws` binary must be on `$PATH`.
+
+```bash
+npm install -g @googleworkspace/cli
+gws --version
+```
+
+Install the shared skill together with the service skills you need. A selective
+installation does not automatically include `gws-shared`.
+
+```bash
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat-send
+```
+
+To install every Workspace skill, use
+`npx skills add https://github.com/googleworkspace/cli`.
+
+## First-time setup
+
+Check the current state before starting another login flow:
+
+```bash
+gws auth status
+```
+
+If no credentials exist, install and authenticate the Google Cloud CLI. On
+macOS with Homebrew:
+
+```bash
+brew install --cask google-cloud-sdk
+gcloud auth login
+```
+
+Then run the guided setup:
+
+```bash
+gws auth setup --login
+```
+
+The setup creates or selects a Google Cloud project, enables the chosen
+Workspace APIs, and configures an OAuth desktop client. Select only the APIs
+needed for the task. For a Chat-to-Slides workflow, enable Google Chat, Google
+Drive, and Google Slides.
+
+### Setup interruptions
+
+- If project creation says the account has not accepted Google Cloud Terms,
+  sign in to `https://console.cloud.google.com/` with the same account, accept
+  the terms, and retry the setup.
+- If the setup requests manual OAuth configuration, open the consent screen for
+  the selected project. Use an Internal audience when the Workspace permits it.
+  Otherwise use External and add the authenticating account as a test user.
+- Create an OAuth client with application type **Desktop app**, download its
+  JSON, and save it as `~/.config/gws/client_secret.json` with mode `600`.
+- Never print the client secret, refresh token, or decrypted credentials. Move
+  the downloaded JSON directly instead of displaying its contents.
+
+Example secure install of the downloaded client file:
+
+```bash
+mkdir -p ~/.config/gws
+install -m 600 /path/to/client_secret.json ~/.config/gws/client_secret.json
+```
+
+Authorize explicit scopes after installing the OAuth client. Prefer
+`--scopes` for Chat because some `gws` releases have omitted Chat scopes when
+using `--services chat`.
+
+Chat read access:
+
+```bash
+gws auth login --scopes \
+  'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly'
+```
+
+Chat discovery plus reading Drive links and editing Google Slides:
+
+```bash
+gws auth login --scopes \
+  'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/presentations'
+```
+
+Verify the result without exposing credentials:
+
+```bash
+gws auth status
+gws chat spaces list --params '{"pageSize":1000}'
+```
 
 ## Authentication
 
@@ -1291,6 +1380,18 @@ mod tests {
             fm.contains("- gws"),
             "shared skill frontmatter should contain '- gws'"
         );
+        assert!(
+            content.contains("npm install -g @googleworkspace/cli"),
+            "shared skill should document CLI installation"
+        );
+        assert!(
+            content.contains("gws auth setup --login"),
+            "shared skill should document first-time authentication setup"
+        );
+        assert!(
+            content.contains("https://www.googleapis.com/auth/chat.spaces.readonly"),
+            "shared skill should document explicit Chat scopes"
+        );
     }
 
     #[test]

skills/gws-shared/SKILL.md

@@ -14,7 +14,96 @@ metadata:
 
 ## Installation
 
-The `gws` binary must be on `$PATH`. See the project README for install options.
+The `gws` binary must be on `$PATH`.
+
+```bash
+npm install -g @googleworkspace/cli
+gws --version
+```
+
+Install the shared skill together with the service skills you need. A selective
+installation does not automatically include `gws-shared`.
+
+```bash
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat-send
+```
+
+To install every Workspace skill, use
+`npx skills add https://github.com/googleworkspace/cli`.
+
+## First-time setup
+
+Check the current state before starting another login flow:
+
+```bash
+gws auth status
+```
+
+If no credentials exist, install and authenticate the Google Cloud CLI. On
+macOS with Homebrew:
+
+```bash
+brew install --cask google-cloud-sdk
+gcloud auth login
+```
+
+Then run the guided setup:
+
+```bash
+gws auth setup --login
+```
+
+The setup creates or selects a Google Cloud project, enables the chosen
+Workspace APIs, and configures an OAuth desktop client. Select only the APIs
+needed for the task. For a Chat-to-Slides workflow, enable Google Chat, Google
+Drive, and Google Slides.
+
+### Setup interruptions
+
+- If project creation says the account has not accepted Google Cloud Terms,
+  sign in to `https://console.cloud.google.com/` with the same account, accept
+  the terms, and retry the setup.
+- If the setup requests manual OAuth configuration, open the consent screen for
+  the selected project. Use an Internal audience when the Workspace permits it.
+  Otherwise use External and add the authenticating account as a test user.
+- Create an OAuth client with application type **Desktop app**, download its
+  JSON, and save it as `~/.config/gws/client_secret.json` with mode `600`.
+- Never print the client secret, refresh token, or decrypted credentials. Move
+  the downloaded JSON directly instead of displaying its contents.
+
+Example secure install of the downloaded client file:
+
+```bash
+mkdir -p ~/.config/gws
+install -m 600 /path/to/client_secret.json ~/.config/gws/client_secret.json
+```
+
+Authorize explicit scopes after installing the OAuth client. Prefer
+`--scopes` for Chat because some `gws` releases have omitted Chat scopes when
+using `--services chat`.
+
+Chat read access:
+
+```bash
+gws auth login --scopes \
+  'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly'
+```
+
+Chat discovery plus reading Drive links and editing Google Slides:
+
+```bash
+gws auth login --scopes \
+  'https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/drive.readonly,https://www.googleapis.com/auth/presentations'
+```
+
+Verify the result without exposing credentials:
+
+```bash
+gws auth status
+gws chat spaces list --params '{"pageSize":1000}'
+```
 
 ## Authentication