@futuvara/connect

The one Futuvara installer. It gives this machine every Futuvara skill and the end-of-turn check (once — every project and worktree then has them), and connects a repository to one Futuvara project. Run it inside the project's repository, once per repository:

export FUTUVARA_KEY_LUXURY_FRONTIERS_PLATFORM=<key from Futuvara > Coding agent access>
npx @futuvara/connect --project Luxury-Frontiers-Platform --agent claude-code

One key variable per project, so several projects work on one machine: FUTUVARA_KEY_ + the project name upper-cased, every run of other characters as _ (Futuvara-Platform → FUTUVARA_KEY_FUTUVARA_PLATFORM). Put the export line in your shell profile so your agent sees it too. The old plain FUTUVARA_KEY alone is not enough: the repository's agent config reads the project variable, so the installer stops with a [FAIL] and the exact export line. Futuvara › Coding agent access shows both lines filled in when a key is made.

What it does, in order:

0. Preflight — before anything is written: Node 20+, git, bash (Git Bash on Windows) and a real Python 3 (not the Microsoft Store stub) for the project config, gh (a warning only — agents need it for pull requests) and the key. Each line is [ ok ] or [FAIL] with the fix; any [FAIL] exits 1 with nothing installed. The key is then checked against the server before any file is touched.
1. MCP server — per repository. Inside a git repository the futuvara server goes into the repository's own, committed config (table below), reading the project's variable. Outside a git repository nothing is connected: "run again inside the project's repo to connect it". Nothing goes into the agent's user config; a machine-wide futuvara entry left by 0.3.0 in ~/.claude.json or ~/.cursor/mcp.json is removed (only that entry), and the output says so.
2. Skills — once per machine (--scope user, the default): list_skills, then get_skill for each, over the MCP server (the set lives in sdk/futu-skills/ in the Futuvara repo, published to the knowledge base on each deploy), written in plugin layout to a fixed temp folder and installed with npx skills add <folder> -s '*' -a <agent> -y --copy -g: ~/.claude/skills for Claude Code, ~/.agents/skills for Cursor, Codex, Copilot and the other agents that read .agents/skills; the shared lib/ the scripts source goes beside them. --scope project installs into this folder instead (.claude/skills or .agents/skills), as before 0.3.1.
3. Config — bash <skills>/futu-setup/futu-setup.sh apply (with FUTU_SETUP_SCOPE=user by default): the end-of-turn check in ~/.claude/settings.json, pointing at the installed futu-setup/references/stop-check.sh, so it runs in every project and does nothing where .futu/ci.sh is absent; inside a git repository also the docs/ skeleton, the AGENTS.md rules block, .futu/ (ESLint futu rules and scanners), eslint.config.mjs wiring and .github/workflows/futu.yml. Skip it with --no-config.
4. Verify — every skill the server lists is where it was installed, the end-of-turn check is in the settings it was written to (Claude Code), the repository's futuvara entry reads the project's variable, and that variable is set. A [FAIL] exits 1 with the exact fix.
5. Jean — when the Jean desktop app is installed, every run (not only installs) makes sure claude:futuvara (or codex: / cursor:) is in Jean's default MCP servers: Jean hands each session its own server list and ignores .mcp.json. --check only reports it.

Staying current. Each install writes the live version to <skills dir>/.futuvara-version. A re-run reads the live version with one list_skills call: when the marker matches and verify passes it prints [ ok ] skills up to date (vX) and finishes in seconds — no download, no restart; when the platform has a newer version it reinstalls and says "Updated the skills to vX". Agents run npx -y @futuvara/connect@latest … at the start of every build pack, so every machine stays current. --check on an older install reports [FAIL] skills out of date and writes nothing.

Is this machine set up? Add --check: preflight + verify only, nothing installed, exit 0 or 1.

Unattended (agents, CI, scripts). It always exits on its own: no child process reads stdin (stdio: ignore), each runs with CI=1, npm_config_yes=true and GIT_TERMINAL_PROMPT=0 and a time limit (npx skills 5 min, futu-setup 3 min), and every server call times out after 60 s. npx is started as node npx-cli.js — no shell. Windows: run it from Git Bash. 0.3.0 could hang there from a folder outside any git repository (such as the home folder): Git Bash hands Node the working folder as C:/…, and futu-setup's walk up to / never ended, because the parent of C: is C:. Fixed in 0.3.1 (plugin 0.17.6).

| --agent | Skills land in (default) | MCP server, per repository | | --- | --- | --- | | claude-code | ~/.claude/skills | merges .mcp.json with Authorization: Bearer ${FUTUVARA_KEY_<PROJECT>} | | cursor | ~/.agents/skills | merges .cursor/mcp.json with Authorization: Bearer ${env:FUTUVARA_KEY_<PROJECT>} | | codex | ~/.agents/skills | prints a .codex/config.toml snippet using bearer_token_env_var = "FUTUVARA_KEY_<PROJECT>" | | copilot | ~/.agents/skills (-a github-copilot) | prints the repo-settings JSON with Authorization: Bearer $COPILOT_MCP_FUTUVARA_KEY; add the key as the Agents secret COPILOT_MCP_FUTUVARA_KEY | | other | -a <agent> | prints the server URL and header |

--url points at another Futuvara host (default https://www.futuvara.com). Needs Node 20 or later. Tests: npm test.

The old futuvara-context skill (0.1.x) is retired in favour of futu-mcp-context, futu-mcp-progress and futu-mcp-signoff; remove an old copy with npx skills remove futuvara-context.

Releasing: bump version in package.json and merge to main. The publish-connect.yml workflow tests and publishes it through npm trusted publishing — no token. The first version was published by hand, because npm cannot trust a publisher for a package that does not exist yet.