Publishing & updates

There is no store: a card is published when it is on GitHub, and installed by its GitHub address. Review is optional — if you want your card in the app’s verified catalog (searchable from the add menu, with a Verified badge), send a pull request to glmn-ai/neurosquad-cards as described in its SUBMITTING.md . Each reviewed version is pinned to one commit.

Publish

1. Run npx @neurosquad/card-sdk validate and pack --dry-run. Fix every error; read the install dialog preview as a stranger would.
2. Commit everything the card needs — including build output (dist/), since the app never builds anything. pack lists exactly what will be installed.
3. Push to a public GitHub repository (private ones work too, for users who add a GitHub token).
4. Optionally tag a release: git tag v1.0.0 && git push --tags, and create a GitHub release from the tag.
5. Tell people the address.

Several cards in one repository is fine: each lives in its own folder with its own manifest, and is installed as owner/repo/path/to/folder.

What users can install from

github.com/owner/repo, https://github.com/owner/repo.git work too. A ref containing / must use the @ref form.

Pinned to a commit. Whatever the address, the app resolves it to one commit and installs that commit’s files. A commit given by hash must be reachable from the repository’s default branch — a commit that exists only in a fork is refused — and a repository that was renamed or transferred must be installed under its current name. The app records the commit and a tree hash of every file. The address the user typed is not the card’s identity — github:owner/repo[/folder] is — so an update keeps the card’s permissions, storage and every copy on every canvas.

How updates reach users

• The app checks a minute after it starts, then every 24 hours, and when the user presses Check for updates.
• A newer commit is downloaded and validated, then offered: Update in Settings and a dot on the card. Nothing is applied automatically.
• The user sees the change: the new version, the old → new commit with a link to GitHub’s comparison, and the permission diff —
  • new permissions and new network hosts → the update waits for the user’s consent;
  • permissions no longer needed → revoked on update;
  • new optional permissions → listed as “may ask later”, never granted automatically;
  • new or reworded tools, new or retyped ports, new secret settings, a changed displayName, author or homepage → the update waits for the user’s consent too.
• On update, every open copy of the card reloads with launch === 'updated'. Storage and settings carry over — migrate them in code if you changed their shape.
• If a manifest no longer validates in a newer app, the card is shown as broken, with the reason; it is never run anyway.

Versioning

Your card’s version is informational — installs are pinned to commits — but users see it in the install dialog, the update dialog and Settings → Custom cards. Use SemVer and bump it with every release. Put breaking changes to your ports or tools in the description: other people’s cards and agents’ habits may depend on them.

minAppVersion stops the card from installing into an app that is too old for it.

The protocol is versioned separately: "protocol": 1 in your manifest, CARD_PROTOCOL_VERSION in the SDK.

• New methods, events and optional fields arrive within protocol 1. Feature-detect them with card.host.supports('method.name') and keep working without them.
• A breaking change would be protocol 2. An app that only speaks 1 refuses a card built for 2 with “needs a newer NeuroSquad”; the app would keep serving protocol-1 cards alongside for at least a year.
• Upgrading @neurosquad/card-sdk within the same major is safe; rebuild and republish.

Changing permissions and what the card offers

Adding a required permission or a network host — or a tool, a port, a secret setting, or changing your card’s name, author or homepage — means every existing user must accept the update before they get anything in it — bug fixes included. Consider:

• making the new permission optional and asking for it when the user reaches for the feature;
• shipping the permission change in its own release, explained in the description.

Deprecating a card

Keep the repository available: installed copies do not need it to run, but updates and reinstalls do. Say so in the description, and point to the replacement.