ycb 3.4.2__tar.gz → 3.4.3__tar.gz

{ycb-3.4.2 → ycb-3.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ycb
-Version: 3.4.2
+Version: 3.4.3
 Summary: Your Company Brain: Automated local knowledge extraction pipeline converting docs & threads into AI agent skills
 Requires-Python: >=3.11
 Requires-Dist: anthropic>=0.40
@@ -19,14 +19,17 @@ Requires-Dist: slack-sdk
 Requires-Dist: sqlalchemy>=2.0
 Description-Content-Type: text/markdown
 
-# 🧠 Your Company Brain (v3.4.2)
+# 🧠 Your Company Brain (v3.4.3)
 
 **Your Company Brain** is an automated, offline-first knowledge extraction pipeline and multi-provider AI Q&A system. It connects to **38 connectors** across your company's communication, engineering, HR, productivity, customer support, and analytics stack, pulls all scattered information, runs it through local or cloud LLMs, and outputs structured "Skills" — machine-readable procedure cards that AI agents can directly execute, or lets you query your company data directly in your terminal using natural-language search (`ycb --ask`).
 
 Instead of manually writing instruction manuals for your AI tools or searching across 10 different dashboards, Your Company Brain generates them automatically and answers questions across any model you choose.
 
-> 🚀 **What's New in v3.4.2 — Max Subscription Tier, Self-Healing Licensing, Dedicated Auth & Windows ASCII UI**:
-> - **Max Monthly Subscription Tier**: New `"max"` tier unlocks all **38 connectors** with automated 30-day subscription management.
+> 🚀 **What's New in v3.4.3 — Guided Connector Setup, Sync Onboarding & API Key Management**:
+> - **Guided `ycb connect` with Credential Links**: Every credential prompt now shows exactly where to get the key — direct link to the platform's dashboard (e.g. `https://github.com/settings/tokens` for GitHub, `https://linear.app/settings/api` for Linear) across all 38 connectors.
+> - **Smart `ycb sync` Onboarding**: When no connectors are configured, `ycb sync` now shows a clean panel with tier-specific `ycb connect` examples instead of launching an empty idle dashboard.
+> - **`ycb switch model --update-key`**: New flag to re-enter your API key for the current provider. Switching to a different provider (e.g. OpenAI → Anthropic) automatically re-prompts for the new key.
+> - **Max Monthly Subscription Tier**: `"max"` tier unlocks all **38 connectors** with automated 30-day subscription management and background self-healing.
 > - **Self-Healing License Synchronization**: When key or email updates occur in `.env`, the CLI automatically validates and heals local cache in the background with zero manual re-login required.
 > - **Automated Occasional Expiry & Freshness Check**: Verifies license validity every 24 hours and upon subscription expiration with a 72-hour offline grace period and clean renewal notices.
 > - **Dedicated Auth Commands (`ycb login` & `ycb logout`)**: Easily switch accounts, authenticate with license key and registered email, and clear local sessions securely.

{ycb-3.4.2 → ycb-3.4.3}/README.md

@@ -1,11 +1,14 @@
-# 🧠 Your Company Brain (v3.4.2)
+# 🧠 Your Company Brain (v3.4.3)
 
 **Your Company Brain** is an automated, offline-first knowledge extraction pipeline and multi-provider AI Q&A system. It connects to **38 connectors** across your company's communication, engineering, HR, productivity, customer support, and analytics stack, pulls all scattered information, runs it through local or cloud LLMs, and outputs structured "Skills" — machine-readable procedure cards that AI agents can directly execute, or lets you query your company data directly in your terminal using natural-language search (`ycb --ask`).
 
 Instead of manually writing instruction manuals for your AI tools or searching across 10 different dashboards, Your Company Brain generates them automatically and answers questions across any model you choose.
 
-> 🚀 **What's New in v3.4.2 — Max Subscription Tier, Self-Healing Licensing, Dedicated Auth & Windows ASCII UI**:
-> - **Max Monthly Subscription Tier**: New `"max"` tier unlocks all **38 connectors** with automated 30-day subscription management.
+> 🚀 **What's New in v3.4.3 — Guided Connector Setup, Sync Onboarding & API Key Management**:
+> - **Guided `ycb connect` with Credential Links**: Every credential prompt now shows exactly where to get the key — direct link to the platform's dashboard (e.g. `https://github.com/settings/tokens` for GitHub, `https://linear.app/settings/api` for Linear) across all 38 connectors.
+> - **Smart `ycb sync` Onboarding**: When no connectors are configured, `ycb sync` now shows a clean panel with tier-specific `ycb connect` examples instead of launching an empty idle dashboard.
+> - **`ycb switch model --update-key`**: New flag to re-enter your API key for the current provider. Switching to a different provider (e.g. OpenAI → Anthropic) automatically re-prompts for the new key.
+> - **Max Monthly Subscription Tier**: `"max"` tier unlocks all **38 connectors** with automated 30-day subscription management and background self-healing.
 > - **Self-Healing License Synchronization**: When key or email updates occur in `.env`, the CLI automatically validates and heals local cache in the background with zero manual re-login required.
 > - **Automated Occasional Expiry & Freshness Check**: Verifies license validity every 24 hours and upon subscription expiration with a 72-hour offline grace period and clean renewal notices.
 > - **Dedicated Auth Commands (`ycb login` & `ycb logout`)**: Easily switch accounts, authenticate with license key and registered email, and clear local sessions securely.

{ycb-3.4.2 → ycb-3.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ycb"
-version = "3.4.2"
+version = "3.4.3"
 description = "Your Company Brain: Automated local knowledge extraction pipeline converting docs & threads into AI agent skills"
 readme = "README.md"
 requires-python = ">=3.11"

{ycb-3.4.2 → ycb-3.4.3}/src/__init__.py

@@ -1,2 +1,2 @@
 """Company Brain package root"""
-__version__ = "3.4.2"
+__version__ = "3.4.3"

{ycb-3.4.2 → ycb-3.4.3}/src/cli/main.py

@@ -19,6 +19,7 @@ from src.licensing.tier_mapping import (
     TIER_CONNECTORS,
     CONNECTOR_CATEGORIES,
     CONNECTOR_ENV_VARS,
+    CONNECTOR_CREDENTIAL_LINKS,
     get_cached_plan_tier,
     is_connector_permitted,
     save_connector_credentials,
@@ -240,6 +241,39 @@ def sync(days, once, interactive, plain, connector):
     else:
         target_connectors = None
 
+    # ── Pre-flight connector check ────────────────────────────────────────────
+    # Resolve enabled connectors once here so we can give immediate feedback.
+    # We re-use the same list for the scheduler below.
+    enabled_connectors = get_enabled_connectors(target_connectors=target_connectors, plan_tier=plan_tier)
+
+    if not enabled_connectors:
+        # Suggest the first few connectors allowed on the user's tier
+        tier_connectors = TIER_CONNECTORS.get(plan_tier.lower(), ["google_docs", "slack"])
+        examples = tier_connectors[:3] if tier_connectors else ["google_docs", "slack", "github"]
+        example_lines = "\n".join(f"  [cyan]ycb connect {c}[/cyan]" for c in examples)
+
+        console.print(
+            Panel.fit(
+                "[bold yellow]No connectors are currently connected or configured.[/bold yellow]\n\n"
+                "To ingest and sync your company knowledge, connect at least one platform:\n"
+                "  [bold cyan]ycb connect <connector_name>[/bold cyan]\n\n"
+                f"[bold]Available in your {plan_tier.title()} plan:[/bold]\n"
+                f"{example_lines}\n\n"
+                "Run [bold cyan]ycb status[/bold cyan] to see all available connectors for your plan tier.",
+                title="[bold cyan]Company Brain — Sync[/bold cyan]",
+                border_style="yellow",
+            )
+        )
+        return
+
+    # Show a brief summary of what will be synced
+    connector_names = [c.get_source_name() for c in enabled_connectors]
+    console.print(
+        f"[bold green][OK][/bold green] Connected applications "
+        f"({len(connector_names)}): [bold cyan]{', '.join(connector_names)}[/bold cyan]\n"
+    )
+    # ─────────────────────────────────────────────────────────────────────────
+
     scheduler = SyncScheduler(sync_interval_minutes=30)
 
     # Setup UI state and logging
@@ -314,15 +348,25 @@ def connect(connector_name):
         return
 
     if name == "slack":
+        console.print()
+        console.print(
+            "[bold]Slack requires a Slack App with OAuth enabled.[/bold]\n"
+            "  [dim]Where to get credentials:[/dim] "
+            "[cyan]https://api.slack.com/apps[/cyan]\n"
+            "  1. Create a new Slack App (or use an existing one)\n"
+            "  2. Under [bold]OAuth & Permissions[/bold], add the user token scopes you need\n"
+            "  3. Copy the [bold]Client ID[/bold] and [bold]Client Secret[/bold] from [bold]Basic Information[/bold]"
+        )
+        console.print()
         client_id = os.getenv("SLACK_CLIENT_ID", "")
         client_secret = os.getenv("SLACK_CLIENT_SECRET", "")
 
         if not client_id:
-            console.print("[cyan]Admin Setup: SLACK_CLIENT_ID not found in config.[/cyan]")
+            console.print("[cyan]SLACK_CLIENT_ID not found in config.[/cyan]")
             client_id = click.prompt("Enter Slack App Client ID (SLACK_CLIENT_ID)").strip()
 
         if not client_secret:
-            console.print("[cyan]Admin Setup: SLACK_CLIENT_SECRET not found in config.[/cyan]")
+            console.print("[cyan]SLACK_CLIENT_SECRET not found in config.[/cyan]")
             client_secret = click.prompt("Enter Slack App Client Secret (SLACK_CLIENT_SECRET)").strip()
 
         console.print("[cyan]Launching browser to authorize your personal Slack account...[/cyan]")
@@ -343,16 +387,37 @@ def connect(connector_name):
             return
 
     required_vars = CONNECTOR_ENV_VARS[name]
-    console.print(f"[cyan]Connecting '{name}' ({len(required_vars)} credential field(s) required)...[/cyan]")
+    console.print(f"\n[bold cyan]Connecting '{name}'[/bold cyan] ({len(required_vars)} credential field(s) required)")
+    console.print()
 
     credentials = {}
     for var in required_vars:
+        # Print the "where to get this" hint if we have one
+        hint = CONNECTOR_CREDENTIAL_LINKS.get(var)
+        if hint:
+            label, url = hint
+            if url.startswith("http"):
+                console.print(f"  [dim]{var}[/dim]")
+                console.print(f"    [bold]Where to get it:[/bold] {label}")
+                console.print(f"    [cyan]{url}[/cyan]")
+            else:
+                # It's a freeform hint (e.g. "e.g. myorg/repo1")
+                console.print(f"  [dim]{var}[/dim]")
+                console.print(f"    [bold]Hint:[/bold] {label}")
+                console.print(f"    [dim]{url}[/dim]")
+            console.print()
+
         existing_val = os.getenv(var, "")
-        val = click.prompt(f"Enter {var}", default=existing_val if existing_val else None)
+        val = click.prompt(
+            f"  {var}",
+            default=existing_val if existing_val else None,
+            show_default=bool(existing_val),
+        )
         credentials[var] = val
+        console.print()
 
     save_connector_credentials(name, credentials)
-    console.print(f"[bold green][OK] Connected connector '{name}'![/bold green]")
+    console.print(f"[bold green][OK] '{name}' connected successfully![/bold green]")
 
 
 @cli.command()
@@ -715,8 +780,13 @@ def _provider_key_env_var(provider: str) -> str:
     return mapping.get(provider, "")
 
 
-def _apply_model_switch(provider_name: str, model_id: str) -> None:
-    """Persist provider + model to .env; prompt for API key only if missing."""
+def _apply_model_switch(provider_name: str, model_id: str, force_key_update: bool = False) -> None:
+    """Persist provider + model to .env; prompt for API key when needed.
+
+    Prompts for an API key when:
+      - switching to a cloud provider that has no key saved yet, OR
+      - force_key_update=True (explicit --update-key flag or provider change)
+    """
     from src.licensing.tier_mapping import get_env_file_path, save_connector_credentials
 
     env_path = get_env_file_path()
@@ -725,28 +795,45 @@ def _apply_model_switch(provider_name: str, model_id: str) -> None:
         "YCB_LLM_MODEL": model_id,
     }
 
-    # Cloud providers: only prompt for key if not already saved
+    # Cloud providers: prompt for key if missing OR if user asked to update it
     if provider_name != "local":
         key_var = _provider_key_env_var(provider_name)
         existing_key = os.environ.get(key_var, "").strip()
-        if not existing_key:
-            provider_labels = {
-                "openai": "OpenAI",
-                "anthropic": "Anthropic",
-                "openrouter": "OpenRouter",
-            }
-            label = provider_labels.get(provider_name, provider_name)
-            import click as _click
-            api_key = _click.prompt(
-                f"  Enter your {label} API key",
-                hide_input=True,
-            ).strip()
-            if not api_key:
-                console.print("[bold red]Error:[/bold red] API key cannot be empty.")
-                return
-            credentials[key_var] = api_key
+        provider_labels = {
+            "openai": "OpenAI",
+            "anthropic": "Anthropic",
+            "openrouter": "OpenRouter",
+        }
+        label = provider_labels.get(provider_name, provider_name)
+
+        if not existing_key or force_key_update:
+            if existing_key and force_key_update:
+                console.print(f"  [dim]Updating {key_var} (press Enter to keep existing):[/dim]")
+                import click as _click
+                api_key = _click.prompt(
+                    f"  Enter your {label} API key",
+                    hide_input=True,
+                    default="",
+                    show_default=False,
+                ).strip()
+                if api_key:  # only overwrite if they entered something
+                    credentials[key_var] = api_key
+                else:
+                    console.print(f"  [dim]Keeping existing {key_var}.[/dim]")
+            else:
+                import click as _click
+                api_key = _click.prompt(
+                    f"  Enter your {label} API key",
+                    hide_input=True,
+                ).strip()
+                if not api_key:
+                    console.print("[bold red]Error:[/bold red] API key cannot be empty.")
+                    return
+                credentials[key_var] = api_key
         else:
-            console.print(f"  [dim]Using saved {_provider_key_env_var(provider_name)} (already configured)[/dim]")
+            # Mask the key for display: show first 8 chars + ***
+            masked = existing_key[:8] + "***" if len(existing_key) > 8 else "***"
+            console.print(f"  [dim]Using saved {key_var}: {masked} (run with --update-key to change)[/dim]")
 
     save_connector_credentials("llm_provider", credentials, env_path)
 
@@ -764,20 +851,26 @@ def _apply_model_switch(provider_name: str, model_id: str) -> None:
 @click.argument("model_name", required=False, default=None)
 @click.option("--list", "list_only", is_flag=True, default=False,
               help="Print the model list without switching.")
-def switch_model(model_name, list_only):
+@click.option("--update-key", "update_key", is_flag=True, default=False,
+              help="Re-prompt for the provider API key even if one is already saved.")
+def switch_model(model_name, list_only, update_key):
     """Switch the active LLM model for --ask.
 
     MODEL_NAME: optional model string to switch directly (e.g. gpt-5.6-terra,
     claude-sonnet-5, gemma4:e4b). Omit to show the interactive menu.
     Any string containing '/' that is not a known named model is treated as a
     custom OpenRouter model string.
+
+    To update/change your saved API key for a provider, run:
+      ycb switch model --update-key
     """
     from src.qa.providers import MODELS, resolve_model_entry
 
+    current_provider = os.environ.get("YCB_LLM_PROVIDER", "local")
+
     # ── --list: just print, don't switch ────────────────────────────────
     if list_only:
         _print_model_menu()
-        current_provider = os.environ.get("YCB_LLM_PROVIDER", "local")
         current_model = os.environ.get("YCB_LLM_MODEL", "gemma4:e4b")
         console.print(
             f"[dim]Current: [bold]{current_model}[/bold] via {current_provider}[/dim]"
@@ -789,7 +882,10 @@ def switch_model(model_name, list_only):
         # Check named models first
         entry = resolve_model_entry(model_name)
         if entry:
-            _apply_model_switch(entry.provider, entry.model_id)
+            # Auto-force key update when switching to a different provider
+            switching_provider = entry.provider != current_provider
+            _apply_model_switch(entry.provider, entry.model_id,
+                                force_key_update=update_key or switching_provider)
             return
 
         # Treat any slug with '/' as a custom OpenRouter model
@@ -797,7 +893,9 @@ def switch_model(model_name, list_only):
             console.print(
                 f"  [dim]Treating '{model_name}' as a custom OpenRouter model.[/dim]"
             )
-            _apply_model_switch("openrouter", model_name)
+            switching_provider = "openrouter" != current_provider
+            _apply_model_switch("openrouter", model_name,
+                                force_key_update=update_key or switching_provider)
             return
 
         # Unknown string and no '/'
@@ -846,10 +944,14 @@ def switch_model(model_name, list_only):
                 console.print("  [yellow]Model string cannot be empty.[/yellow]")
                 continue
 
-            _apply_model_switch("openrouter", custom_model)
+            switching_provider = "openrouter" != current_provider
+            _apply_model_switch("openrouter", custom_model,
+                                force_key_update=update_key or switching_provider)
             return
 
-        _apply_model_switch(entry.provider, entry.model_id)
+        switching_provider = entry.provider != current_provider
+        _apply_model_switch(entry.provider, entry.model_id,
+                            force_key_update=update_key or switching_provider)
         return
 
 

{ycb-3.4.2 → ycb-3.4.3}/src/licensing/tier_mapping.py

@@ -40,16 +40,6 @@ TIER_CONNECTORS: Dict[str, List[str]] = {
         "hubspot", "salesforce", "monday", "basecamp", "ashby",
         "bamboohr", "deel", "rippling",
     ],
-    "test": [
-        "slack", "google_docs", "github", "notion", "discord",
-        "google_sheets", "linear", "outlook", "gitlab", "dropbox",
-        "mixpanel", "amplitude", "algolia", "exa", "perplexity",
-        "facebook", "gmail", "google_drive", "todoist", "web_crawler",
-        "jira", "asana", "calendly", "clickup", "airtable",
-        "datadog", "segment", "front", "zoom", "twitter",
-        "hubspot", "salesforce", "monday", "basecamp", "ashby",
-        "bamboohr", "deel", "rippling",
-    ],
 }
 
 # Categorized grouping of all 38 connectors for clean CLI status display
@@ -104,6 +94,110 @@ CONNECTOR_ENV_VARS: Dict[str, List[str]] = {
     "rippling": ["RIPPLING_API_TOKEN"],
 }
 
+# Where to get credentials — env var -> (label, url)
+# Shown as a hint before each credential prompt in `ycb connect`.
+CONNECTOR_CREDENTIAL_LINKS: Dict[str, Tuple[str, str]] = {
+    # Slack
+    "SLACK_CLIENT_ID":          ("Slack App Dashboard",     "https://api.slack.com/apps"),
+    "SLACK_CLIENT_SECRET":      ("Slack App Dashboard",     "https://api.slack.com/apps"),
+    "SLACK_USER_TOKEN":         ("Slack App OAuth & Permissions", "https://api.slack.com/apps"),
+    # Google (shared across google_docs, gmail, sheets, drive)
+    "GOOGLE_CREDENTIALS_PATH":  ("Google Cloud Console — OAuth credentials (download as credentials.json)",
+                                 "https://console.cloud.google.com/apis/credentials"),
+    # GitHub
+    "GITHUB_TOKEN":             ("GitHub Personal Access Tokens", "https://github.com/settings/tokens"),
+    "GITHUB_REPOS":             ("Your GitHub repo list",     "e.g. myorg/repo1,myorg/repo2"),
+    # Notion
+    "NOTION_TOKEN":             ("Notion My Integrations",   "https://www.notion.so/my-integrations"),
+    # Discord
+    "DISCORD_BOT_TOKEN":        ("Discord Developer Portal", "https://discord.com/developers/applications"),
+    "DISCORD_GUILD_IDS":        ("Your Discord Server IDs",  "Right-click server → Copy Server ID (enable Developer Mode first)"),
+    # Linear
+    "LINEAR_API_KEY":           ("Linear API Settings",      "https://linear.app/settings/api"),
+    # Outlook / Microsoft Graph
+    "MS_CLIENT_ID":             ("Azure App Registrations",  "https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps"),
+    "MS_CLIENT_SECRET":         ("Azure App — Certificates & Secrets", "https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps"),
+    "MS_TENANT_ID":             ("Azure Active Directory — Tenant ID", "https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade"),
+    # GitLab
+    "GITLAB_TOKEN":             ("GitLab Personal Access Tokens", "https://gitlab.com/-/profile/personal_access_tokens"),
+    "GITLAB_URL":               ("Your GitLab instance URL", "e.g. https://gitlab.com or your self-hosted URL"),
+    "GITLAB_PROJECTS":          ("Your GitLab project list", "e.g. mygroup/project1,mygroup/project2"),
+    # Dropbox
+    "DROPBOX_TOKEN":            ("Dropbox App Console",      "https://www.dropbox.com/developers/apps"),
+    # Mixpanel
+    "MIXPANEL_API_SECRET":      ("Mixpanel Project Settings — Service Account", "https://mixpanel.com/settings/project"),
+    "MIXPANEL_PROJECT_ID":      ("Mixpanel Project Settings", "https://mixpanel.com/settings/project"),
+    # Amplitude
+    "AMPLITUDE_API_KEY":        ("Amplitude Project Settings", "https://analytics.amplitude.com/login"),
+    "AMPLITUDE_SECRET_KEY":     ("Amplitude Project Settings", "https://analytics.amplitude.com/login"),
+    # Algolia
+    "ALGOLIA_APP_ID":           ("Algolia Dashboard — API Keys", "https://dashboard.algolia.com/account/api-keys"),
+    "ALGOLIA_API_KEY":          ("Algolia Dashboard — API Keys", "https://dashboard.algolia.com/account/api-keys"),
+    "ALGOLIA_INDEX_NAME":       ("Your Algolia index name",  "Found in Algolia Dashboard → Search → Indices"),
+    # Exa
+    "EXA_API_KEY":              ("Exa Dashboard",            "https://dashboard.exa.ai/api-keys"),
+    # Perplexity
+    "PERPLEXITY_API_KEY":       ("Perplexity API Settings",  "https://www.perplexity.ai/settings/api"),
+    # Facebook
+    "FACEBOOK_PAGE_TOKEN":      ("Facebook Developer Portal — Page Access Token", "https://developers.facebook.com/apps"),
+    "FACEBOOK_PAGE_ID":         ("Your Facebook Page ID",   "Found in Facebook Page → About or Page Settings"),
+    # Todoist
+    "TODOIST_API_TOKEN":        ("Todoist Integrations Settings", "https://app.todoist.com/app/settings/integrations/developer"),
+    # Web Crawler
+    "WEB_CRAWLER_START_URLS":   ("Comma-separated list of URLs to crawl", "e.g. https://docs.yourcompany.com,https://yourcompany.com/blog"),
+    # Jira / Atlassian
+    "JIRA_DOMAIN":              ("Your Jira workspace domain", "e.g. yourcompany.atlassian.net"),
+    "JIRA_EMAIL":               ("Your Atlassian account email", "The email you use to log in to Jira"),
+    "JIRA_API_TOKEN":           ("Atlassian API Tokens",    "https://id.atlassian.com/manage-profile/security/api-tokens"),
+    # Asana
+    "ASANA_TOKEN":              ("Asana Developer Console — Personal Access Token", "https://app.asana.com/0/developer-console"),
+    "ASANA_WORKSPACE_GID":      ("Your Asana Workspace GID", "Found via GET https://app.asana.com/api/1.0/workspaces"),
+    # Calendly
+    "CALENDLY_TOKEN":           ("Calendly Developer Portal — Personal Access Token", "https://developer.calendly.com/how-to-authenticate-with-personal-access-tokens"),
+    "CALENDLY_USER_URI":        ("Your Calendly User URI",  "Found via GET https://api.calendly.com/users/me"),
+    # ClickUp
+    "CLICKUP_API_TOKEN":        ("ClickUp Settings — Apps",  "https://app.clickup.com/settings/apps"),
+    "CLICKUP_TEAM_ID":          ("Your ClickUp Team ID",    "Found in ClickUp URL: app.clickup.com/<team_id>/"),
+    # Airtable
+    "AIRTABLE_TOKEN":           ("Airtable Developer Hub — Personal Access Tokens", "https://airtable.com/create/tokens"),
+    "AIRTABLE_BASE_IDS":        ("Your Airtable Base IDs",  "Found in Airtable API docs page for each base: airtable.com/appXXXXXX/api/docs"),
+    # Datadog
+    "DATADOG_API_KEY":          ("Datadog Organization Settings — API Keys", "https://app.datadoghq.com/organization-settings/api-keys"),
+    "DATADOG_APP_KEY":          ("Datadog Organization Settings — Application Keys", "https://app.datadoghq.com/organization-settings/application-keys"),
+    # Segment
+    "SEGMENT_PERSONAS_TOKEN":   ("Segment App — Access Tokens", "https://app.segment.com/goto-my-workspace/settings/access-management"),
+    "SEGMENT_SPACE_ID":         ("Your Segment Space ID",   "Found in Segment → Engage → Settings → API Access"),
+    # Front
+    "FRONT_API_TOKEN":          ("Front App Settings — API Tokens", "https://app.frontapp.com/settings/tools/api"),
+    # Zoom
+    "ZOOM_ACCOUNT_ID":          ("Zoom Marketplace — Server-to-Server OAuth App", "https://marketplace.zoom.us/develop/create"),
+    "ZOOM_CLIENT_ID":           ("Zoom Marketplace — Server-to-Server OAuth App", "https://marketplace.zoom.us/develop/create"),
+    "ZOOM_CLIENT_SECRET":       ("Zoom Marketplace — Server-to-Server OAuth App", "https://marketplace.zoom.us/develop/create"),
+    # Twitter / X
+    "TWITTER_BEARER_TOKEN":     ("Twitter Developer Portal — Project/App Keys", "https://developer.twitter.com/en/portal/dashboard"),
+    "TWITTER_SEARCH_QUERIES":   ("Comma-separated search queries", "e.g. @yourcompany,#yourproduct"),
+    # HubSpot
+    "HUBSPOT_ACCESS_TOKEN":     ("HubSpot Private App Access Token", "https://app.hubspot.com/private-apps"),
+    # Salesforce
+    "SALESFORCE_CLIENT_ID":     ("Salesforce Connected App Consumer Key", "Setup → Apps → App Manager → New Connected App"),
+    "SALESFORCE_CLIENT_SECRET": ("Salesforce Connected App Consumer Secret", "Setup → Apps → App Manager → New Connected App"),
+    "SALESFORCE_DOMAIN":        ("Your Salesforce domain",  "e.g. yourcompany.my.salesforce.com"),
+    # Monday
+    "MONDAY_API_TOKEN":         ("Monday.com Developer Center — API Token", "https://auth.monday.com/users/sign_in (Profile → Developers → API)"),
+    # Basecamp
+    "BASECAMP_ACCESS_TOKEN":    ("Basecamp — Launchpad OAuth / Personal Tokens", "https://launchpad.37signals.com/"),
+    "BASECAMP_ACCOUNT_ID":      ("Your Basecamp Account ID", "Found in your Basecamp URL: 3.basecamp.com/<account_id>/"),
+    # Ashby
+    "ASHBY_API_KEY":            ("Ashby Settings — API Keys", "https://app.ashbyhq.com/admin/api/keys"),
+    # BambooHR
+    "BAMBOOHR_API_KEY":         ("BambooHR API Access — Generate API Key", "https://app.bamboohr.com/settings/permissions/"),
+    "BAMBOOHR_SUBDOMAIN":       ("Your BambooHR subdomain", "e.g. if your URL is mycompany.bamboohr.com, enter 'mycompany'"),
+    # Deel
+    "DEEL_API_TOKEN":           ("Deel API Settings",        "https://app.deel.com/settings/api"),
+    # Rippling
+    "RIPPLING_API_TOKEN":       ("Rippling API Credentials", "https://app.rippling.com/api"),
+}
+
 
 def get_cached_plan_tier(cache_dir: Optional[str] = None, expected_key: Optional[str] = None) -> str:
     """Read the plan_tier from ~/.company-brain/license.json. Defaults to 'solo' if unconfigured.