docs: improve connector onboarding steps

Improve connector docs with clearer onboarding and validation steps.

Signed-off-by: Cheney Zhang <chen.zhang@zilliz.com>

Author: zc277584121

docs/connectors/bigquery.md

@@ -23,21 +23,28 @@ BigQuery uses **Application Default Credentials (ADC)** — there is no token in
 TOML; the credentials must be visible to the **server process**. Three common
 paths:
 
-1. **Service account JSON** (production): create a service account with
-   `roles/bigquery.dataViewer` on the target datasets, then point the server at
-   it:
+1. **Service account JSON** (production): in Google Cloud Console, open
+   *IAM & Admin → Service Accounts* → **Create service account**. Name it
+   `mfs-bigquery-reader`, grant `roles/bigquery.dataViewer` on the target
+   datasets or project, then open the service account's *Keys* tab →
+   **Add key → Create new key → JSON**. Store the downloaded JSON outside the
+   repo and point the server at it:
 
     ```bash
     export GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json
     mfs-server run
     ```
 
-2. **`gcloud auth application-default login`** (dev / single-user) — writes
-   `~/.config/gcloud/application_default_credentials.json`.
+2. **`gcloud auth application-default login`** (dev / single-user): run it as
+   the same OS user that starts `mfs-server`. It opens a browser consent flow and
+   writes `~/.config/gcloud/application_default_credentials.json`.
 
 3. **Workload Identity** on GKE / Cloud Run — ADC is automatic.
 
-Make sure the **BigQuery API** is enabled on the project.
+Before any of those, open *APIs & Services → Library → BigQuery API* and enable
+it on the project. If the connector can authenticate but cannot list a dataset,
+check the dataset IAM page first; the service account needs read access to every
+dataset listed in `datasets`.
 
 ![Google Cloud BigQuery API page](https://github.com/user-attachments/assets/fd034ea0-4607-4e74-b65a-106460830889)
 
@@ -58,6 +65,13 @@ text_fields = ["title", "body_markdown"]
 locator_fields = ["article_id"]
 ```
 
+Save the file as `bigquery.toml`, then probe before the first index:
+
+```bash
+mfs connector probe bigquery://analytics --config ./bigquery.toml
+mfs add bigquery://analytics --config ./bigquery.toml
+```
+
 ## Sync and freshness
 
 The connector uses the table's `modified` time as its cursor; deletions are caught
@@ -67,8 +81,6 @@ tables.
 ## Search and browse
 
 ```bash
-mfs add bigquery://analytics --config ./bigquery.toml
-
 mfs search "refund event" bigquery://analytics/events/tables/user_events/rows.jsonl
 mfs search "email column" bigquery://analytics --kind schema_summary
 mfs cat bigquery://analytics/kb/tables/articles/rows.jsonl --locator '{"article_id":"a-123"}'
@@ -80,3 +92,5 @@ mfs cat bigquery://analytics/kb/tables/articles/rows.jsonl --locator '{"article_
 - BigQuery has no primary key for most tables — choose stable `locator_fields`
   explicitly.
 - Rows need `text_fields` to be searchable.
+- User ADC from `gcloud` is convenient for local testing; service accounts or
+  workload identity are easier to operate in long-running deployments.

docs/connectors/discord.md

@@ -60,6 +60,13 @@ guild_id = "987654321098765432"
 max_read_rows = 50000
 ```
 
+Save the file as `discord.toml`, then probe and index:
+
+```bash
+mfs connector probe discord://community --config ./discord.toml
+mfs add discord://community --config ./discord.toml
+```
+
 ## Sync and freshness
 
 The connector tracks the latest `message_id` per channel as its cursor;
@@ -68,8 +75,6 @@ re-syncs fetch only newer messages. Deletion detection is `never`.
 ## Search and browse
 
 ```bash
-mfs add discord://community --config ./discord.toml
-
 mfs search "deploy failed" discord://community
 mfs ls discord://community/channels/general__987654321
 mfs cat discord://community/channels/general__987654321/messages.jsonl --locator '{"id":"1234567890123456789"}'

docs/connectors/feishu.md

@@ -55,8 +55,10 @@ Add the connector — the wizard runs a one-time browser authorization inline:
 mfs-server connector add feishu://workspace
 ```
 
-Open the printed URL and approve. **This consent must be done by a person and
-can't be automated** — it's the OAuth user-authorization step. After that the
+The wizard prompts for App ID, App Secret, region, and auth mode, writes the TOML
+under `$MFS_HOME/connectors/`, and registers the connector against the local
+server. Open the printed URL and approve. **This consent must be done by a person
+and can't be automated** — it's the OAuth user-authorization step. After that the
 token refreshes automatically while the connector is actively synced (each sync
 renews it). If it goes unused for several days the authorization expires; the next
 use reports that re-authorization is needed. To re-authorize, have a person
@@ -88,6 +90,15 @@ docs_folder_token = "fldcn..."   # optional: limit docs to one shared folder
 max_read_rows = 50000
 ```
 
+Tenant mode does not need browser consent. You can use the same
+`mfs-server connector add feishu://workspace` wizard and choose `tenant`, or save
+the TOML yourself and run:
+
+```bash
+mfs connector probe feishu://workspace --config ./feishu.toml
+mfs add feishu://workspace --config ./feishu.toml
+```
+
 ## Sync and freshness
 
 The connector uses the message `create_time` as its cursor; deletion detection is

docs/connectors/gdrive.md

@@ -21,13 +21,31 @@ Google Drive uses a **user OAuth token JSON** — the `token.json` from Google's
 OAuth flow, containing `refresh_token` / `client_id` / `client_secret`.
 Service-account keys are **not** supported.
 
-1. GCP Console → *APIs & Services → Library* → enable **Google Drive API**.
-2. *Credentials → Create Credentials → OAuth client ID* → *Desktop app* →
-   **Download JSON** (the client credentials).
-3. Run Google's OAuth flow once on a machine with a browser (e.g.
-   `InstalledAppFlow.run_local_server`) requesting scope
-   `https://www.googleapis.com/auth/drive.readonly`. This writes `token.json`.
-4. Copy `token.json` to the server and reference it from the TOML.
+1. <https://console.cloud.google.com> → pick or create a project. If this is
+   the first OAuth client in the project, finish the OAuth consent screen first
+   and add the authorizing Google account as a test user when the app is in
+   testing.
+2. *APIs & Services → Library → Google Drive API* → **Enable**.
+3. *APIs & Services → Credentials → Create Credentials → OAuth client ID* →
+   choose **Desktop app** → **Create** → **Download JSON**. Save it locally as
+   `client_secret.json`.
+4. On a workstation with a browser, run the consent flow once:
+
+    ```bash
+    uv run --with google-auth-oauthlib python - <<'PY'
+    from pathlib import Path
+    from google_auth_oauthlib.flow import InstalledAppFlow
+
+    scopes = ["https://www.googleapis.com/auth/drive.readonly"]
+    flow = InstalledAppFlow.from_client_secrets_file("client_secret.json", scopes)
+    creds = flow.run_local_server(port=0)
+    Path("token.json").write_text(creds.to_json())
+    PY
+    ```
+
+5. Copy `token.json` to a path the **server process** can read, for example
+   `/home/x/.mfs/gdrive-token.json`, and reference that absolute path from the
+   TOML.
 
 ![Google Cloud Drive API page](https://github.com/user-attachments/assets/523b9021-f809-4b1f-a1ad-16703739c409)
 
@@ -45,6 +63,14 @@ anything explicitly shared with them. If you also use [`gmail`](gmail.md), reque
 token = "file:/home/x/.mfs/gdrive-token.json"
 ```
 
+Save the file as `gdrive.toml`, then probe from the same environment that can
+reach the MFS server:
+
+```bash
+mfs connector probe gdrive://engineering --config ./gdrive.toml
+mfs add gdrive://engineering --config ./gdrive.toml
+```
+
 ## Sync and freshness
 
 The connector uses each file's `modifiedTime` as its cursor; deletions are caught
@@ -60,8 +86,6 @@ indexes only files modified on or after that date. Older files are left untouche
 ## Search and browse
 
 ```bash
-mfs add gdrive://engineering --config ./gdrive.toml
-
 mfs search "roadmap" gdrive://engineering/Product/
 mfs cat gdrive://engineering/Product/Roadmap.txt --range 1:80
 mfs export gdrive://engineering/Product/Design.pdf /tmp/design.pdf

docs/connectors/gmail.md

@@ -24,14 +24,31 @@ Gmail uses a **user OAuth token JSON** — the `token.json` from Google's OAuth
 flow, containing `refresh_token` / `client_id` / `client_secret`. Service-account
 keys are **not** supported.
 
-1. <https://console.cloud.google.com> → pick or create a project.
+1. <https://console.cloud.google.com> → pick or create a project. If this is
+   the first OAuth client in the project, finish the OAuth consent screen first
+   and add the authorizing Google account as a test user when the app is in
+   testing.
 2. *APIs & Services → Library → Gmail API* → **Enable**.
-3. *Credentials → Create Credentials → OAuth client ID* → *Desktop app* →
-   **Download JSON** (the client credentials, not the token yet).
-4. Run Google's OAuth flow once on a machine with a browser (e.g.
-   `InstalledAppFlow.run_local_server`) requesting scope
-   `https://www.googleapis.com/auth/gmail.readonly`. This writes `token.json`.
-5. Copy `token.json` to the server and reference it from the TOML.
+3. *APIs & Services → Credentials → Create Credentials → OAuth client ID* →
+   choose **Desktop app** → **Create** → **Download JSON**. Save it locally as
+   `client_secret.json`.
+4. On a workstation with a browser, run the consent flow once:
+
+    ```bash
+    uv run --with google-auth-oauthlib python - <<'PY'
+    from pathlib import Path
+    from google_auth_oauthlib.flow import InstalledAppFlow
+
+    scopes = ["https://www.googleapis.com/auth/gmail.readonly"]
+    flow = InstalledAppFlow.from_client_secrets_file("client_secret.json", scopes)
+    creds = flow.run_local_server(port=0)
+    Path("token.json").write_text(creds.to_json())
+    PY
+    ```
+
+5. Copy `token.json` to a path the **server process** can read, for example
+   `/home/x/.mfs/gmail-token.json`, and reference that absolute path from the
+   TOML.
 
 ![Google Cloud Gmail API page](https://github.com/user-attachments/assets/8a2b96ab-8ea6-4442-9e25-f186c879dd14)
 
@@ -55,6 +72,13 @@ max_read_rows = 5000
 bare access-token string or inline token JSON, but the file reference is the
 common form.
 
+Save the file as `gmail.toml`, then probe and index:
+
+```bash
+mfs connector probe gmail://work --config ./gmail.toml
+mfs add gmail://work --config ./gmail.toml
+```
+
 ## Sync and freshness
 
 The connector uses Gmail's `historyId` as its cursor for incremental re-sync.
@@ -63,8 +87,6 @@ Deletion detection is `never` — removed mail isn't retroactively pruned.
 ## Search and browse
 
 ```bash
-mfs add gmail://work --config ./gmail.toml
-
 mfs search "contract renewal" gmail://work/labels/INBOX__CATEGORY_PERSONAL/messages.jsonl
 mfs cat gmail://work/labels/INBOX__CATEGORY_PERSONAL/messages.jsonl --locator '{"threadId":"THREAD_ID","id":"MESSAGE_ID"}'
 ```

docs/connectors/hubspot.md

@@ -54,6 +54,13 @@ locator_fields = ["id"]
 If `object_types` is omitted, the connector probes the common objects and silently
 drops the ones the portal rejects (a 403 on Service Hub tickets, say).
 
+Save the file as `hubspot.toml`, then probe and index:
+
+```bash
+mfs connector probe hubspot://acme --config ./hubspot.toml
+mfs add hubspot://acme --config ./hubspot.toml
+```
+
 ## Sync and freshness
 
 The connector uses each object's `hs_lastmodifieddate` as its cursor for
@@ -62,8 +69,6 @@ incremental re-sync; deletions are caught by `full_scan`.
 ## Search and browse
 
 ```bash
-mfs add hubspot://acme --config ./hubspot.toml
-
 mfs search "customer health" hubspot://acme/contacts/records.jsonl
 mfs cat hubspot://acme/contacts/records.jsonl --locator '{"id":"12345"}'
 ```

docs/connectors/jira.md

@@ -48,6 +48,13 @@ projects = ["ENG", "OPS"]      # empty = all visible projects
 max_read_rows = 50000
 ```
 
+Save the file as `jira.toml`, then probe and index:
+
+```bash
+mfs connector probe jira://acme --config ./jira.toml
+mfs add jira://acme --config ./jira.toml
+```
+
 ## Sync and freshness
 
 The connector uses the issue `updated` timestamp as its cursor; Cloud retrieval
@@ -56,8 +63,6 @@ pages through `enhanced_jql`. Deletions are caught by `full_scan`.
 ## Search and browse
 
 ```bash
-mfs add jira://acme --config ./jira.toml
-
 mfs search "SSO regression" jira://acme/projects/ENG/issues.jsonl
 mfs cat jira://acme/projects/ENG/issues.jsonl --locator '{"key":"ENG-1234"}'
 ```

docs/connectors/linear.md

@@ -42,6 +42,13 @@ api_key = "env:LINEAR_API_KEY"
 teams = ["ENG"]               # empty = all visible teams
 ```
 
+Save the file as `linear.toml`, then probe and index:
+
+```bash
+mfs connector probe linear://workspace --config ./linear.toml
+mfs add linear://workspace --config ./linear.toml
+```
+
 ## Sync and freshness
 
 The connector uses the issue `updatedAt` field as its cursor for incremental
@@ -50,8 +57,6 @@ re-sync; deletions are caught by `full_scan`.
 ## Search and browse
 
 ```bash
-mfs add linear://workspace --config ./linear.toml
-
 mfs search "billing migration" linear://workspace/teams/ENG/issues.jsonl
 mfs cat linear://workspace/teams/ENG/issues.jsonl --locator '{"identifier":"ENG-42"}'
 ```

docs/connectors/mongo.md

@@ -27,13 +27,20 @@ mongodb+srv://user:pass@cluster.mongodb.net/?retryWrites=true
 ```
 
 For Atlas, copy the SRV URI from *Database → Connect → Drivers* and substitute
-the real password. A read-only user is enough — the connector only runs `find()`.
-Probe before MFS sees it:
+the real password. Before copying it, open *Database Access → Add New Database
+User*, create a user with the built-in **read** role on the target database, then
+open *Network Access* and allow the egress IP of the machine or container running
+`mfs-server`. A read-only user is enough — the connector only runs `find()`.
+
+Probe from the server host before MFS sees it:
 
 ```bash
 mongosh "$MONGO_URI" --eval "db.adminCommand({ping: 1})"
 ```
 
+If the password contains `@`, `:`, `/`, or other URL characters, percent-encode
+it before putting it in the URI.
+
 ## Configuration
 
 ```toml
@@ -52,6 +59,14 @@ metadata_fields = ["status"]
 `text_fields` supports nested paths like `messages[].body` to pull text out of
 arrays of subdocuments.
 
+Keep the URI in the server environment, then probe and index:
+
+```bash
+export MONGO_URI='mongodb+srv://mfs_reader:<password>@cluster.mongodb.net/'
+mfs connector probe mongo://prod-cluster --config ./mongo.toml
+mfs add mongo://prod-cluster --config ./mongo.toml
+```
+
 ## Sync and freshness
 
 With `cursor_field` set (`updatedAt` or `_id`), re-syncs pull only documents
@@ -60,9 +75,6 @@ changed since the last run; deletions are caught by `full_scan`.
 ## Search and browse
 
 ```bash
-mfs connector probe mongo://prod-cluster --config ./mongo.toml
-mfs add mongo://prod-cluster --config ./mongo.toml
-
 mfs search "refund escalation" mongo://prod-cluster/support_threads/documents.jsonl
 mfs cat mongo://prod-cluster/support_threads/documents.jsonl --locator '{"_id":"65a3..."}'
 ```