# Connect this agent to MindBuds Official service: https://mindbuds.resopod.cn . Use this guide when the user asks you to connect their agent or create personal MindBuds stories. Complete installation and account checks before asking them to configure technical details. Preserve the user's existing choices and authorization scope. ## 1. Check the environment and install You need a command-execution tool, writable persistent local storage, and Node.js 22 or newer (with npm). A chat-only agent cannot run this integration. Check the actual environment. If Node is missing, install it through the environment's normal supported mechanism if authorized; otherwise explain exactly what prerequisite is missing. Do not ask for MindBuds account tokens or model keys. Check for an existing `mindbuds` executable or an earlier installation under the user's `.mindbuds/tools-cn` directory. If found, run its `version` command and compare it with the official manifest. Reuse only a matching version whose `doctor --offline --json` reports the CN API URL; upgrades keep credentials outside the installation directory. Download https://mindbuds.resopod.cn/agent/manifest.json . This small JSON contains `version`, `node`, `package.file`, `package.sha256`, and `entry`. Resolve `package.file` relative to that manifest URL on the same official origin. Download the tarball and verify its SHA-256 against `package.sha256` before installing. Use your file/network tools or Node's `fetch` and `crypto.createHash('sha256')`. Stop on a failed download or hash mismatch; do not guess an npm registry package or execute a download error page. Install the verified local tarball with npm into a user-owned persistent prefix, normally `/.mindbuds/tools-cn`: ```sh npm install --prefix --ignore-scripts --no-audit --no-fund ``` No sudo, repository checkout, build tools, npm registry login, model subscription or lifecycle scripts are needed. The package has no runtime dependencies. Use your shell's normal path quoting. On all platforms you can invoke the CLI as an argument array: ```text executable: the Node.js executable arguments: [/node_modules/@mindbuds/cli/bin/mindbuds.cjs, ...command arguments] ``` The examples below abbreviate that invocation to `mindbuds`; you do not need to modify shell profiles or PATH. ## 2. Configure for this agent Determine this agent's actual skill root from its current configuration. `setup` defaults to `/.agents/skills`, which Codex supports. For a different root, pass `--skill-dir `; for example this may be the user-configured Hive skills directory. Install into one intended agent location. Do not guess several directories or overwrite other skills. ```sh mindbuds setup --skill-dir --json ``` Use `--language zh-CN|en|es|zh-TW` when the user's preferred story language is known. Visibility defaults to private; use `--visibility family` only when that matches their choice. This CN package has its own credential directory and installs a `mindbuds-cn` skill. Its official CN API address is built in. Do not reuse overseas credentials or a global CLI installation. Custom deployments can explicitly select `--api-url `; accounts are kept separate by URL. Read `/SKILL.md` in the current session, including its package reference when needed. Setup writes `references/installation.json` with the exact executable and arguments for future sessions. If the host does not refresh its skill catalog immediately, explain how to refresh/reopen it; you can follow the installed instructions now. Repeated setup is safe. A modified existing skill is preserved and reported, rather than overwritten. Local Codex skill discovery is documented at https://learn.chatgpt.com/docs/build-skills . Other agents can use the same SKILL.md through their own skill mechanisms. ## 3. Connect the user's account Run `mindbuds doctor --json`. Read the JSON, including `account`, `library`, `readyToUpload`, `imageGeneration`, and `nextActions`. `--offline` checks local installation only and cannot prove account/library access. When signed out: ```sh mindbuds auth begin --json ``` This returns promptly with `loginId`, `userCode`, `authorizationUrl`, `expiresAt`, and `pollAfterMs`. Show the CN authorization link and six-digit code to the user. They must review and confirm it in the signed-in CN web app. Current mobile builds connect to the overseas region and cannot authorize this CN account. Do not enter an account token, confirm the device on their behalf, or invent a successful authorization. After their confirmation: ```sh mindbuds auth poll --json ``` `pending` is a normal state. Wait at least `pollAfterMs` between checks; keep the conversation available to the user instead of blocking on a long-running command. You can continue from another agent turn/process with the same ID. Repeating `auth begin` reuses an unexpired pending request. `expired` needs a new `auth begin`. `auth cancel ` clears a local pending request. Do not read the credential file: the CLI stores both polling secrets and account tokens privately. After `authorized`, run `doctor` again. A network error or disabled library must be resolved before reporting the connection ready. If a single-use authorization response is lost or its credentials cannot be saved, fix the local/network problem and start a new authorization as directed by the returned error; polling a consumed code cannot recover it. ## 4. Check creative tools and hand back a useful result Check your actual image-generation tools and whether they accept reference photos. The CLI does not include a model or image generation service. Existing tools or user-supplied images can be used; explain any missing capability. Do not claim a capability is working just because setup succeeded. The user's agent/image provider determines its own costs and limits. Report the connected account, library access, saved language/visibility, and available image workflow in plain language. A setup-only request does not authorize uploading a sample. When the user asks for a story, follow the installed skill to create real text/images, validate, preview as appropriate, and upload within the requested scope. Return `links.reader` from the successful upload and explain that the story also appears in the same account's MindBuds library. For errors, follow stable `code` and `nextActions` fields. All command stdout is one JSON object; human progress is on stderr. Never paste credential files or tokens into the conversation.