Update to Pipecat Context Hub

{
  "description": "Set up the Pipecat Context Hub plugin after an explicit request, checking native CLI retrieval and required Pipecat/Cloud tools, installing missing prerequisites, creating an initial index and guiding Cloud account signup and login when authorised.",
  "included_files": [],
  "name": "setup",
  "skill_md_contents": "---\nname: setup\ndescription: Set up the Pipecat Context Hub plugin after an explicit request, checking native CLI retrieval and required Pipecat/Cloud tools, installing missing prerequisites, creating an initial index and guiding Cloud account signup and login when authorised.\n---\n\nUse this workflow when the user requests plugin, Context Hub or Pipecat/Cloud\nCLI setup. Determine the requested capabilities from the conversation: full\nplugin setup includes the build/deploy toolchain; explicitly retrieval-only\nsetup needs only PCH. PCH CLI supplies retrieval; Pipecat CLI and its\nCloud extension are required tools for Build and Deploy respectively.\nPlugin installation or an exploration question alone does not authorise\ndependency installation or index creation. The plugin contains skills and assets,\nnot Python, command-line\ntools or an index. Its setup runs in the selected execution environment; it does\nnot configure a desktop MCP client or deploy a remote MCP service.\nSkills supply instructions, not execution permissions or installation hooks.\n\n## Inspect and propose setup\n\n1. Identify the execution environment and selected client. Check native shell/file\n   access with a harmless command. A local computer or cloud execution environment\n   can run PCH when it supports Python and subprocesses; installing a plugin on\n   the web does not provision that environment. Record whether its runtime/index\n   will persist between tasks. Cloud container paths, indexes and login do not\n   configure or authenticate another execution host.\n   Before any index operation, require a POSIX host with descriptor-relative,\n   no-reparse filesystem support. Windows is package/path smoke only: do not\n   run `refresh`, `serve`, or semantic queries against a populated index there;\n   these operations must fail closed rather than falling back to pathname-based\n   deletion or opening.\n   If native execution is unavailable, report setup and grounded retrieval\n   unavailable and provide the user's remaining setup steps; do not install an adapter.\n2. Batch the bounded read-only preflight before proposing any mutation. In one\n   pass, inspect native execution, the selected PCH command/status, `pipecat\n   --version`, `pipecat init --help` and, for Cloud, the required read-only help\n   and organisation metadata. Do not ask for approval for these reads and do not\n   split them into separate approval prompts. Report all findings together.\n   Discover PCH through [Explore's CLI retrieval](../explore/SKILL.md#cli-retrieval):\n   verify `pipecat context-hub` or standalone `pipecat-context-hub`, installed\n   help and JSON `status`. Inspect failures before choosing a path: exit 2 alone\n   does not prove an empty index. Record versions, index path, count, refresh\n   date, framework pin, indexed framework version and any\n   `catalog_groups_not_indexed` coverage gaps. Treat `indexed_repos` and\n   `configured_no_records` as local metadata that may contain private names;\n   reuse the selected installation/index rather than silently picking another.\n   Separately inspect `pipecat --version`, `pipecat init --help` and, for Cloud,\n   `pipecat cloud --help`, `pipecat cloud auth login --help` and organisation-list\n   help. A listed `cloud` command may be an unavailable-extension stub; require\n   working subcommand help rather than treating the root listing as readiness.\n3. Reuse working PCH and a healthy populated index. Staleness, a different requested\n   framework version or disabled reranking does not authorise refresh, upgrade or\n   model downloads. A corrupt/unreadable existing index is a separate recovery\n   request; stop that branch without reset, repair, deletion or a replacement index.\n4. Present the concrete changes needed: required PCH/Pipecat/Cloud package/version\n   specifications and retained extensions, tool-manager\n   environment, resolved initial-index path and sources/framework pin, required\n   storage/persistence and any existing-file backup.\n   Explain that first indexing downloads models and source repositories and can\n   take several minutes. Use only already-authorised changes. If the user has\n   explicitly requested installation and initial indexing, proceed\n   within that scope; otherwise obtain one setup approval covering the complete\n   proposed mutation set before executing it. Group compatible installation and\n   initial-index operations under that approval, while keeping credentials,\n   project writes and deployment as separate workflow approvals. A readiness-only\n   request stays read-only.\n\n   Do not select or require a ChatGPT approval mode. If the user asks about\n   reducing interruptions, explain that approval behavior is controlled by the\n   host/workspace and that any lower-friction choice is their decision for\n   trusted read-only work; it never covers installs, writes, credentials or\n   deployment.\n\n## Required workflow CLIs\n\n| Requested workflow | Required tools | Account requirement |\n|---|---|---|\n| Explore | Usable PCH query CLI and native execution | No Cloud account |\n| Build | Pipecat CLI with working `init`, plus PCH retrieval | No Cloud account |\n| Deploy | Pipecat CLI with working Cloud extension, plus PCH retrieval | Authenticated Pipecat Cloud account and selected workspace/organisation |\n\nFor authorised fresh full-plugin or Cloud setup, the\n[documented installation](https://docs.pipecat.ai/api-reference/cli/overview#installation)\nis `uv tool install \"pipecat-ai[cli]\" --with pipecatcloud`. This supplies the\nPipecat CLI with its Cloud extension; verify whether the selected distribution\nalso bundles PCH, otherwise add `--with pipecat-ai-context-hub`.\nFor an explicitly local-build-only setup, install the standalone PCH package into\nthe same tool environment: `uv tool install \"pipecat-ai[cli]\" --with\npipecat-ai-context-hub`. The Pipecat CLI alone does not provide the required PCH\nretrieval on the qualified CLI version. PCH query commands do not replace the\nrequired build/deployment CLI.\n\nReuse existing working CLI installations. Inspect tool-manager/package metadata\nbefore modifying an existing environment: `uv tool install --with` replaces the\ntool environment, so retain every existing selected extension and its constraints\nin the proposed command. Do not silently remove extensions, change pins or\nupgrade a working installation just to unify it with PCH. An authorised separate\nenvironment is an alternative when the current environment must be preserved.\nIf `uv` is unavailable, use the approved virtual-environment route below with\nthe required packages, or report the missing execution prerequisite.\n\nVerify actual installed versions and required subcommand help after installation.\nIf `pipecat context-hub --help` works, use that PCH installation; otherwise retain\nor install standalone PCH separately. A working Pipecat/Cloud CLI is mandatory\nfor the requested Build/Deploy capability, separately from PCH query readiness.\n\n## Handle an older Pipecat CLI\n\nWhen the installed Pipecat CLI is older than the version needed for the user's\nrequested capability, or the user explicitly asks for the latest CLI, report the\ncurrent version, the missing/changed capability and the package manager that was\nactually detected. Construct one exact upgrade command that preserves every\nexisting selected extension and constraint. For a `uv` tool, this is typically an\n`uv tool install --upgrade \"pipecat-ai[cli]\"` command with the retained `--with`\npackages; for a managed virtual environment, use that environment's\n`python -m pip install --upgrade` route. Do not guess a manager or path.\n\nPresent the command and its expected changes for one explicit approval. Only\nafter approval, run the upgrade, re-check `pipecat --version` and\n`pipecat init --help`, and verify PCH/Cloud subcommands again. If the manager is\nunknown, provide the command the user can run rather than mutating the host. A\nnewer release alone is not a reason to upgrade, and an approved CLI upgrade does\nnot authorise refreshing the Hub index, changing project locks or deploying.\n\n## Install missing PCH and create the initial index\n\nInspect the installed tool manager's help. When `uv` is already available, the\nstandalone package install is `uv tool install pipecat-ai-context-hub`; use an\nexplicit `==VERSION` only when selected by the user. This supplies the PCH CLI.\nPCH may already be bundled with the installed Pipecat CLI; do not\ninstall a duplicate or upgrade a working CLI to obtain it. If `uv` is absent,\nan authorised compatible Python virtual environment and its `pip` can install\nthe same package. Do not install globally or bootstrap another tool manager\nwithout including that in the approved setup. Installed package metadata controls\nPython requirements; this repository currently requires Python 3.11 or newer.\n\nDiscover the resulting executable and its actual Python environment from native\ntool-manager metadata. Inspect PCH help again. Use a neutral working directory\noutside projects so unrelated project `.env` files do not select setup inputs.\nRetain explicitly selected Hub environment/global configuration without exposing\ncredentials. Check the configured data directory and source list before writes;\nprivate/custom source indexing requires explicit authorisation.\n\nOnly create an initial index when the resolved directory is absent or status\nand directory inspection establish an empty, uninitialised index. Use the\nverified PCH prefix with `refresh`, honouring the selected/configured framework\npin and supported flags. Never add `--force`, `--reset-index` or `--prune` to\ninitial setup. Do not refresh a populated index to test setup. On failure, retain\npartial state and report the bounded error; do not retry, clear it or redirect\nto another index automatically. Check `status` after initial indexing and\nrequire nonzero records with known provenance before calling retrieval ready.\n\n## Cloud account and login\n\nFor Cloud/full-plugin onboarding, guide the user through account readiness;\nretrieval-only or local build does not need Cloud login. After verifying the\nCloud CLI, inspect authentication through the supported read-only organisation\nlist. Never run that credential-bearing command directly through an agent-visible\nexecution tool. Invoke the packaged `scripts/safe_cloud_metadata.py` wrapper with\n`--kind organizations` and pass the installed read-only JSON command after `--`.\nResolve the `pipecat` executable to its absolute installed path first; the\nwrapper rejects bare PATH-relative names so a shadow executable cannot receive\n`PIPECAT_TOKEN`. It also requires the CLI and wrapper to use the same Python\nenvironment; separate virtualenv/uv-tool CLIs are rejected rather than\nexecuting copied, unverified packages with the token.\nThe wrapper captures raw stdout/stderr inside its subprocess and emits only\nschema-validated org IDs/names. Treat a nonzero wrapper exit or schema mismatch\nas unresolved; do not retry by printing raw output. Do not use `auth whoami`, auth\nconfig or API-key listings: some versions expose a Daily API key. Successful\nmetadata reads establish existing authentication; skip login for an\nalready-authenticated user.\n\nIf an account is missing, direct the user to [Pipecat Cloud](https://pipecat.daily.co)\nto create/sign in to their account. Explain personal workspaces and team\norganisations using the\n[account guide](https://docs.pipecat.ai/pipecat-cloud/fundamentals/accounts-and-organizations).\nThe user completes signup and any required organisation creation/joining in\nthe dashboard; do not collect passwords or automate account/billing changes.\n\nFor local interactive login, guide the user to run `pipecat cloud auth login`\nin their own terminal on the execution host and complete the browser flow.\nThe [login reference](https://docs.pipecat.ai/api-reference/cli/cloud/auth#login)\nexplains opening the displayed URL manually when needed. Do not capture or\necho that one-time URL/token into model context. Login stores credentials in\nthat host's CLI configuration; it does not authenticate another cloud container.\n\nFor headless cloud/CI, follow the\n[PAT guide](https://docs.pipecat.ai/pipecat-cloud/guides/personal-access-tokens):\nthe user creates a PAT in the dashboard and supplies `PIPECAT_TOKEN` through the\nenvironment's secure secret mechanism. When supported, `pipecat cloud auth use-pat`\naccepts a hidden prompt in the user's own interactive terminal. Never ask them\nto paste tokens into chat, put values in argv or copy desktop auth files to a\ndifferent host. A public session API key is not proof of CLI management login.\n\nAfter the user completes authentication, repeat the safe organisation-list check,\nconfirm the intended workspace/organisation and report Cloud account readiness\nseparately from CLI installation. Prefer explicit target flags during deployment;\ndo not switch a configured default organisation, log out, create keys or mutate\nCloud resources as part of readiness checking. Missing credentials or unavailable\nmetadata stay pending. Account/login setup does not approve a build or deployment.\n\n## Verify and hand off\n\nUse the verified PCH command for `status`, a read-only\n`search-docs \"TTS + STT\"`, then `status` again. Require hits for both concepts and\nunchanged index/version provenance. These checks do not refresh the index.\nNo MCP registration or process restart is needed for this skills-only plugin.\n\nReport installed/reused package versions, initial indexing performed or skipped,\nbackups, storage/persistence limits and separate PCH query, Pipecat build CLI,\nCloud CLI and Cloud account/organisation outcomes. Full-plugin/Cloud setup also\nrequires usable workflow CLIs and successful account metadata checks; missing\nlogin remains pending. Hand off to [Explore](../explore/SKILL.md) when retrieval\nis usable. Missing Cloud login does not block working Explore or local Build.\nBuild and Deploy retain their app-workspace, provider-credential and concrete\ndeployment approvals; setup does not access provider secrets, provision Cloud\ndeployments or start agent sessions. Packaging and successful direct commands\nare not proof of autonomous installed-skill activation or fresh cloud onboarding.\n"
}