@siriusai_cybernetics/stacksy — Stacksy specialist onboarding CLI

Tier 2.5 npm-publishable package (2026-05-29). Operator-facing distribution guide. Specialists see docs/runbooks/SPECIALIST_ONBOARDING_2026-05-29.md §A.

Distributed under the @siriusai_cybernetics npm org (operator-controlled via siriusai.nl). The CLI + product stay branded stacksy — parent-brand (Siriusai) / product-brand (Stacksy) split.

What it does

One command takes a specialist from "nothing installed" to "ready to fire first Interpolis run in Claude Desktop" in ~2 minutes.

npx @siriusai_cybernetics/stacksy@latest onboard

Or, after global install (npm install -g @siriusai_cybernetics/stacksy):

stacksy onboard

Package layout

scripts/onboard/
├── package.json          @siriusai_cybernetics/stacksy npm package metadata
├── README.md             this file
├── bin/
│   └── stacksy.mjs       bin shim — routes `stacksy <command>`
└── lib/
    └── onboard.mjs       the `stacksy onboard` command implementation

CLI options

stacksy onboard [options]

  --env <prod|staging>      Skip the env prompt (default: ask)
  --bundle-url <URL>        Fetch the .mcpb from this URL
                            (default: resolve from repo-local
                             extensions/stacksy.mcpb)
  --knowledge-url <URL>     Fetch Knowledge file from this URL
                            (default: resolve from repo-local
                             docs/handoff/STACKSY_SPECIALIST_KNOWLEDGE.md)
  --skip-open               Don't auto-open the .mcpb
                            (specialist double-clicks manually)

When called via npx @siriusai_cybernetics/stacksy@latest, the CLI is NOT inside a repo checkout — so --bundle-url and --knowledge-url MUST be set (typically baked into the operator's hosted entrypoint script).

Operator publish flow (~50 min total)

Step 1 — Register the @siriusai_cybernetics npm org (one-time, ~5 min)

Status (2026-05-29): DONE. Org registered. Skip to Step 2.

Visit https://www.npmjs.com/org/create and register siriusai_cybernetics as an organization. Add yourself ([email protected] or your npm account) as the owner.

• Free plan = public packages only
• Paid plan = restricted packages (specialists need to authenticate to install)

Recommended for the pilot: free plan + publishConfig.access: "public" so specialists can npx without credentials. Flip to restricted later once specialist count + monetization model justify the change.

If you go public, update package.json:

{
  "publishConfig": {
    "access": "public"
  }
}

Step 2 — Publish the package (~10 min including login)

cd scripts/onboard
npm login                # uses your @siriusai_cybernetics org credentials
npm publish              # publishes @siriusai_cybernetics/stacksy@<version>

Verify on https://www.npmjs.com/package/@siriusai_cybernetics/stacksy.

Step 3 — Host the release artifacts (~30 min)

The CLI fetches the .mcpb and Knowledge file from URLs you control. Recommended setup using siriusai.nl + Cloud Storage:

Cloud Storage public bucket:

gsutil mb -p western-beanbag-445419-q5 -l europe-west4 gs://siriusai-stacksy-releases/
gsutil iam ch allUsers:objectViewer gs://siriusai-stacksy-releases/

Auto-upload from the bundle build script — add to extensions/stacksy-mcpb/build.sh:

# After `mcpb pack`:
if [[ "${STACKSY_PUBLISH_RELEASE:-false}" == "true" ]]; then
  gsutil cp extensions/stacksy.mcpb \
    gs://siriusai-stacksy-releases/latest/stacksy.mcpb
  gsutil cp docs/handoff/STACKSY_SPECIALIST_KNOWLEDGE.md \
    gs://siriusai-stacksy-releases/latest/STACKSY_SPECIALIST_KNOWLEDGE.md
fi

Run STACKSY_PUBLISH_RELEASE=true bash extensions/stacksy-mcpb/build.sh to publish.

URLs become:

• https://storage.googleapis.com/siriusai-stacksy-releases/latest/stacksy.mcpb
• https://storage.googleapis.com/siriusai-stacksy-releases/latest/STACKSY_SPECIALIST_KNOWLEDGE.md

Step 4 — Host the install one-liner (DONE — via the release bucket)

Status (2026-05-29): DONE. The install script is hosted directly in the public Cloud Storage release bucket — no separate frontend hosting needed. URL:

https://storage.googleapis.com/siriusai-stacksy-releases/install

How it was set up (for reference / re-deploy):

# scripts/onboard/install-redirect.sh content uploaded to the bucket
gsutil cp scripts/onboard/install-redirect.sh gs://siriusai-stacksy-releases/install
gsutil setmeta -h "Content-Type:text/x-shellscript" gs://siriusai-stacksy-releases/install

# Windows PowerShell entrypoint (2026-06-11):
#   irm https://storage.googleapis.com/siriusai-stacksy-releases/install.ps1 | iex
gsutil cp scripts/onboard/install-redirect.ps1 gs://siriusai-stacksy-releases/install.ps1
gsutil setmeta -h "Content-Type:text/plain" -h "Cache-Control: no-cache, max-age=0" gs://siriusai-stacksy-releases/install.ps1

The script content:

#!/usr/bin/env bash
# https://storage.googleapis.com/siriusai-stacksy-releases/install
# Stacksy specialist onboarding entrypoint.
# Source: github.com/Hyperborean42/siriusai-stacksy (scripts/onboard/)
exec npx -y @siriusai_cybernetics/stacksy@latest onboard \
  --bundle-url https://storage.googleapis.com/siriusai-stacksy-releases/latest/stacksy.mcpb \
  --knowledge-url https://storage.googleapis.com/siriusai-stacksy-releases/latest/STACKSY_SPECIALIST_KNOWLEDGE.md

Specialist final shape (live):

curl -sSL https://storage.googleapis.com/siriusai-stacksy-releases/install | bash

Step 5 (optional polish) — Pretty URL via siriusai.nl/install/stacksy

Optional follow-up to shorten the install URL. The Cloud Storage URL works fine for the pilot; this is purely cosmetic.

Two viable paths whenever you have time:

• Cloud Run subdomain redirect — add an install.siriusai.nl Cloud Run domain mapping + tiny redirect service. Then specialists run curl -sSL https://install.siriusai.nl | bash. ~30 min operator-side.
• TransIP/DNS subpath — host the same bash script at https://siriusai.nl/install/stacksy via your frontend's static file config. Path depends on your frontend stack.

Until then: the Cloud Storage URL is the canonical install URL — stable, signed, public, free.

Pre-publish testing (locally)

The CLI works inside a repo checkout without needing npm publish:

# From repo root:
node scripts/onboard/bin/stacksy.mjs onboard

# Or with explicit overrides:
node scripts/onboard/bin/stacksy.mjs onboard --env staging

This is the path you'd use for pilot specialists who have repo access while npm publish is pending.

To test the npm-installed shape:

cd scripts/onboard
npm pack                    # creates siriusai_cybernetics-stacksy-<version>.tgz
npm install -g ./siriusai_cybernetics-stacksy-*.tgz
stacksy --version           # should print 0.1.0
stacksy onboard --env prod --bundle-url <test-bundle-URL>

What's deferred to Tier 2.5+ / Tier 3

| Item | Status | Notes | |---|---|---| | Browser OAuth provisioning | Deferred | Needs admin panel + backend self-service endpoint; ~1-2 days. Spec §C.2 | | @siriusai_cybernetics npm org registration | Operator-action | 5 min on npmjs.com; gates everything else | | Cloud Storage release hosting | Operator-action | Configure gsutil cp in build pipeline; ~30 min | | https://siriusai.nl/install/stacksy pretty URL (optional) | Operator-action | Cosmetic only — the GCS URL works today. Path depends on frontend stack (~30 min if Cloud Run subdomain; varies for Vercel/TransIP) | | Claude Desktop Project API integration | Researching | API availability uncertain; defer | | Windows CLI support + install.ps1 one-liner | DONE (2026-06-11) | Clipboard (clip.exe), auto-open (cmd /c start), PowerShell entrypoint. Needs Node 18+ like macOS | | Windows installer (.msi) | Deferred | Would only remove the Node.js prerequisite; revisit after 5 specialists onboarded | | Auto-update mechanism | Deferred | Tier 3 D.1 |

Failure recovery

• "Bundle not found" — provide --bundle-url OR run from inside a repo checkout
• "Knowledge file not found" — provide --knowledge-url OR run from repo (Knowledge install is optional)
• "Couldn't auto-open the bundle" — Claude Desktop not installed or the .mcpb file association is broken; specialist double-clicks the .mcpb manually (CLI prints the path)
• 37 tools don't show up post-install — bundle is stale; rebuild via bash extensions/stacksy-mcpb/build.sh + re-host + re-run CLI

Source

• Package: scripts/onboard/ (this directory)
• Spec: docs/specs/SPECIALIST_UX_HARDENING_2026-05-29.md §C (Tier 2)
• Specialist runbook: docs/runbooks/SPECIALIST_ONBOARDING_2026-05-29.md
• Knowledge file pointer: docs/handoff/STACKSY_SPECIALIST_KNOWLEDGE.md §I