vibe-sketcherDocumentation

Supporter recognition and website updates

Cross-product design record for #213. Viewer recorded its contract plan at fb9267e; Scheduler already has admin-confirmed cosmetic recognition and tracks further funding/shared recognition in vibe-scheduler #242. This plans a uniform system; it does not activate funding gates, select a new dependency, deploy a service or authorize a release. Release placement remains unassigned.

Existing behavior and ownership

Yes: the website can serve update metadata and installers. Sketcher already uses electron-updater 6.8.9 with electron-builder 26.15.3’s generic provider at https://vibyverse.com/updates/vibe-sketcher/. The shell has Check for Updates, startup checks, notifications, download/restart handlers, and source-install instructions. Its package gate currently selects macOS arm64 and Linux x64 AppImage. Those code paths are not proof of every installed update route. Current ad-hoc macOS previews deliberately offer manual replacement rather than self-install; bundled-runtime and signing/Store qualification remain separate. Website metadata availability alone does not establish installed-package acceptance or authorize a new release.

Extend the existing implementation rather than adding another update engine. The distribution policy retains public Linux downloads with no supporter membership requirement, separate paid Store purchases, and the source/redistribution rights provided by included licences. Recognition and update access are separate concepts; a badge must not silently redefine policy.

Owner / tracker

Responsibility

Website/service owner, still to be assigned; shared candidates in vibe-viewer #195

Provider verification, linking/reconciliation, policy and versioned signed recognition receipts. One issuer, not three app-specific payment systems.

Website/release service owner, still to be assigned; shared candidate vibe-viewer #198

Immutable artifacts, metadata trust, atomic publication, retention/cache/range behavior and any separately approved download authorization.

Sketcher #214–#218; Viewer consumers vibe-viewer #196/#197

Product-specific status/menus, receipt validation, installer routing, safe apply/recovery and acceptance. Product versions remain independent.

Scheduler dev owner; vibe-scheduler #242

Dashboard account recognition, audited admin grants and future shared-receipt adapter. Scheduler authorization and agent/service update ownership remain independent.

The shared candidates are coordination records in Viewer, not permission to implement website code in that repository. Final backend repository, service operator, trust-root custody and shared protocol versions must be named before implementation. Each product owns its adapter; shared backend code belongs in the assigned service repository. Cross-project issue numbers are qualified because unrelated Sketcher issues use the same IDs.

Uniform supporter experience

Use common labels: Upgrade to supporter, Supporter, Manage supporter status and Refresh status. Open the canonical website support page in the system browser; the website owns verified Ko-fi/GitHub Sponsors destinations. An unconfigured provider remains explicitly unavailable. Include an already supporting/claim route. Merely opening a payment link does not verify support.

The proposed badge is opt-in recognition in application chrome or About, with an accessible text equivalent. Do not place it in scientific figures, exported files, VSK/QVF documents, calculation inputs or provenance hashes. Supporting one product must not grant Scheduler roles, job priority, quotas or access to another account. Any future commercial entitlement is a separately reviewed policy and protocol, not an implication of a cosmetic badge.

Proposed shared flow:

  1. User opens Upgrade to supporter or Manage supporter status in any product.

  2. The browser links a verified support event or an authorized manual grant to the user’s chosen account/claim. Bind the result to the initiating session; do not trust arbitrary deep-link parameters, typed email or screenshots.

  3. The shared issuer returns a versioned signed receipt with opaque subject and grant IDs, product audience, issuer/key ID, recognition kind/status and validity/refresh information. Different apps can hold appropriate receipts for the same support relationship without sharing raw credentials.

  4. A local verifier or authenticated hosted adapter derives the display state. Invalid signatures, unknown keys, wrong audiences and malformed receipts do not grant a verified badge. Refresh/unlink and optional receipt-file import are bounded and session checked. Keep refresh credentials in appropriate private storage, not command arguments, URLs, logs or shared documents.

The issuer keeps provider secrets and financial/donor data server-side with minimal retention and authorized audit/recovery. Clients need only recognition state. Existing Scheduler staff-confirmed recognition can be a bootstrap source; portable receipts are an additive bridge, not permission for a dashboard query or payment link to self-promote an account.

Ko-fi reports payment events but not ended memberships. GitHub Sponsors reports sponsorship lifecycle changes. The shared owner must authenticate provider messages, deduplicate/reconcile deliveries, and define paid-through and manual correction rules. No invented Ko-fi cancellation event, silent email matching or shared provider secret in a desktop package.

Update delivery and installation

Static HTTPS hosting can serve each product’s immutable artifacts and generated update metadata. Provider webhooks/identity reconciliation require a backend; that service does not need to sit in the update download path. Shared protocol requirements should cover:

  • Product, version/build sequence, platform, architecture, channel and install kind; minimum OS/runtime/updater compatibility and immutable artifact identity.

  • Bounded signed metadata, trust-root/key rotation and freshness/replay rules, artifact size/digest and platform publisher-signature validation. A checksum from an untrusted manifest is not independent publisher authentication.

  • Exact verified metadata and bytes pinned through apply. Do not verify an index and then independently refetch mutable YAML or a substituted artifact.

  • Atomic latest-metadata promotion only after complete artifact/source/notices upload; safe cache expiry, range/resume and approved redirect/origin behavior. Never forward credentials to an arbitrary redirect or include donor identity in public feed URLs. Public updates retain their current access policy.

Reuse the installed electron-updater stack where its reviewed APIs suffice. The default upstream documentation currently describes unreleased v27 features; use the v26 documentation for the pinned builder and review any additional signature verifier/protocol before choosing it. This plan does not assume newer APIs exist in shipped code.

Install kind

Planned update route

Qualified writable Linux AppImage

Website metadata/download, complete staged AppImage, verified replacement and recovery. Do not infer eligibility from the OS alone.

Direct macOS package

Self-install only after publisher signing and installed-route qualification. Current ad-hoc previews retain notify/download/manual replacement.

Mac App Store or Microsoft Store

Store-managed updates and channel-appropriate funding UI after current policy review; never replace Store binaries from the website.

Direct Windows NSIS

Conditional future route only if separately selected and qualified; a build target alone does not establish support.

Source/pip/system-managed install

Existing source/package manager or operator workflow. Show status/instructions; do not overwrite a checkout or managed environment.

Browser or hosted service

Server owner deploys; browser refresh/version notices do not install software on the host. Scheduler workers require their own authorized maintenance workflow.

Use shared check/download/progress/cancel/retry/ready/apply states and clear preferences for automatic checks/downloads. Avoid concurrent checks. Prompt before restart; respect unsaved canvas/document edits, backend shutdown and active calculations. Stage a complete verified app including bundled runtime and notices; do not pip-upgrade parts of a signed bundle. Retain a usable prior installation or a defined manual recovery route on permission/disk/interruption failure. An unavailable feed or recognition service must leave offline chemistry usable. One app’s update must not update other products or active workers.

SDK/CLI/REST/MCP expose common redacted status and supported intent, including explicit Store/manual/operator-managed refusals. Refresh/receipt import and any permitted staging action use the same validation as the UI. No unauthenticated HTTP endpoint, arbitrary URL/path or remote agent request may install software. Final apply stays within the trusted local installer/operator boundary; the exact consent and handoff contract belongs in implementation acceptance.

Decisions, sequence and acceptance

Decision still required

Record / effect

One-off and recurring recognition, lifetime/expiry/grace, refunds/revocation, account linking and offline display

#214 with shared Viewer #195; no eligibility or duration silently chosen.

Verified GitHub Sponsors destination and provider setup

Website owner configuration; do not publish guessed account URLs.

Shared service repository/operator, trust roots, receipt format and key rotation

Viewer #195/#198 plus consumer adoption; separate receipt and software-update signing purposes.

Metadata trust/migration protocol compatible with current updater

#216; no automatic dependency upgrade or invented signature API.

Direct signing, Store-specific external-support UI, supported install routes

#217 and existing distribution/release owners; no Store acceptance inferred.

Automatic check/download defaults and restart consent

#217 with common wording and user choice.

Implement after the contracts/policy are reviewed: #214 shared supporter policy, #215 Sketcher menu/badge, #216 feed/trust adoption, #217 safe updater and #218 cross-channel acceptance. Keep each capability API-first, bounded and documented. Use prospective shared test vectors for valid/invalid/cross-product receipts, duplicate/out-of-order provider events, offline and manual grants, malformed or replayed feeds, wrong platform/channel, changed bytes, partial publication and interrupted/permission/disk-full updates. Installed old-to-new tests must name exact artifact hashes, runtime and install kind; source mocks are insufficient.

Extend #69/#71 and the other products’ acceptance rather than claiming a release from this plan. Preserve failures, dirty-document recovery and active-job behavior; include keyboard/screen-reader review. Store/payment terms and any new entitlement policy need maintainer review. Publication still needs separate authorization, and contract freeze/user evaluation remain pending.

References