Skip to content

docs(modules): marketplace v1.1 — managed hosting becomes the mainline install path (HT-79) #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zaridan merged 2 commits into from
Jul 20, 2026
Merged

docs(modules): marketplace v1.1 — managed hosting becomes the mainline install path (HT-79) #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
27897ea
docs(modules): managed hosting becomes the mainline install path (HT-79)
zaridan Jul 20, 2026
1b91667
docs(modules): collect module runtime config browser-direct to the co…
zaridan Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHARTER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ This charter is not legal advice. Counsel reviews the licensing structure, the p

Serverless kills the traditional runtime plugin-folder model — there's no long-lived filesystem to drop a module into. Helpthread's extension model is designed in from day one along two tracks: **build-time npm modules**, where an operator adds a package and redeploys — the install *is* the Vercel build — and **typed event hooks / webhooks** for integrations that live out-of-process entirely. The plumbing paid modules need (license keys, license-gated distribution, an update channel) is built alongside the modules themselves and exercised through the project's own installs long before a stranger's money touches it — never as a runtime restriction: a license authenticates downloads and updates, and no shipped module ever phones home or stops working when a license lapses (`specs/modules/catalog.md` §5).

**Amended 2026-07-19 (managed hosting):** the *default* install path is no longer the operator redeploying a module themselves — clicking Install in Manage → Modules provisions a Resonant IQ-hosted instance of the module for that deployment, the realization of the hosted convenience services §3 already contemplates. The self-host path (download the versioned tarball, deploy to your own Vercel) remains fully supported as the open-core escape hatch. Both preserve the same invariants without exception: a license is only ever a distribution credential — no runtime license check ships in any module, hosted or self-hosted, and the hosted artifact is byte-identical to the self-host tarball; no module phones home; and a lapsed license never stops running software, even when Resonant IQ is the host. The credential-bearing install/update orchestration lives entirely outside the AGPL core, in a Resonant IQ-operated hosting control plane — the one component that holds both a license key and a per-desk provisioning grant; the core holds neither and never calls the marketplace (`specs/modules/marketplace-v1.md` §3/§5).

**Platform posture: Vercel-first, not Vercel-only.** The first-class deployment target is Vercel + Supabase, and the deploy story is optimized for it without apology. But the engine's core never calls a platform directly: queueing, scheduled and durable work, blob storage, and inbound email all sit behind thin provider interfaces the project owns, with today's implementations (Vercel Queues, Vercel Cron and Workflows, Supabase Storage, Gmail push) as adapters rather than assumptions. Inbound email forces this discipline anyway — Gmail can't be the only supported mailbox forever — and applying it to the other seams keeps a future plain-Node-plus-Postgres deployment mode reachable without an engine rewrite. Supabase itself is open source and self-hostable, so that half of the stack is a soft dependency by construction. No additional deployment targets are promised at launch: every supported target is a permanent test matrix, and that cost gets taken on only when demand justifies it.

The conversation model is **channel-agnostic from day one**. Email is the founding channel — but a conversation and its threads don't care how a message arrived, and the schema never assumes SMTP. Chat/messaging arrives later as a second channel over the same engine (Supabase Realtime is the push transport; a "chat" is a conversation whose threads travel a faster wire), and an embeddable support widget — knowledge-base search, start a conversation, follow the replies, in the tradition of Help Scout's Beacon — is a planned first-party module built on the same public API. Live-chat trappings like presence and typing indicators layer onto that channel per-operator; they are staffing promises more than plumbing.
Expand Down Expand Up @@ -87,4 +89,6 @@ Solo-maintainer, BDFL model for now — there is one project, one person account

**Amended 2026-07-19 (HT-79):** §3, §4, §5 — the marketplace moves from "a later phase, once demand justifies it" to a launch-day component of Phase 3, built now and proven as the project's own dogfood install path. Rationale: the original deferral assumed the module substrate and first modules would not exist until after launch; both shipped during the dogfood phase, so the remaining marketplace work is commerce plumbing, not speculation — and launching the free helpdesk with its sustainability model already visible is the more honest story. The §7 plugin exception's counsel deadline is unchanged (before first external contribution): every v1 marketplace module is out-of-process and needs no exception. New counsel items before the marketplace takes real money: the commercial module license text and terms of sale.

**Amended 2026-07-19 (HT-79, managed hosting):** §4 — the marketplace's default install path becomes **managed hosting**: clicking Install in Manage → Modules provisions a Resonant IQ-hosted instance of the module, the realization of the "hosted convenience services" §3 already names. Decided after TJ walked the manual self-host install as customer #1 (HT-82 dogfood) and rejected its friction. The posture invariants are restated, not relaxed: (a) a license key stays a distribution credential only — no runtime license check exists in any module, hosted or self-hosted, and the hosted artifact is byte-identical to the self-host tarball; (b) a lapsed license never stops running software — a hosted instance keeps running at its entitled version, updates simply stop; (c) the AGPL core holds no license key and no marketplace credential and never calls the marketplace — the credential-bearing install/update orchestration lives entirely outside the core, in a Resonant IQ-operated hosting control plane, the only trust domain holding both license keys and per-desk provisioning grants. The self-host tarball path remains fully supported as the open-core escape hatch, and a refunded/revoked customer's already-held self-host copy keeps running with no DRM and no runtime check, ever — a consciously accepted residual exposure. Managed hosting is opt-in per operator; the core mail/data path is unchanged. Left to `specs/modules/marketplace-v1.md`, not settled here: the exact refund-window and config-export-grace figures, the scoped per-desk provisioning-credential the substrate must add, and the reconciliation of §2's "conversation data never proxies through Helpthread's infrastructure" wording with a hosted module processing operator data on Resonant IQ infrastructure (a data-residency call flagged for TJ, deliberately not resolved by this amendment).

**Amended 2026-07-19 (HT-75):** §3 and §4 — the knowledge base reclassified from free-forever core to a paid first-party module. FreeScout's own reference instance runs its Knowledge Base as a paid purchase (`specs/ui/admin-ia.md`); keeping ours core was chosen 2026-07-18 as a marketed free-vs-FreeScout differentiator (`specs/modules/catalog.md` §1), and TJ reversed that call on review. Not a retroactive paywall under the §3 invariant — the knowledge base was never shipped (`specs/modules/catalog.md` §2.1's shipped list never included it). Full paid-module catalog: `specs/modules/catalog.md`.
13 changes: 12 additions & 1 deletion specs/modules/catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,13 @@ now so the marketplace design inherits it:
install/uninstall/health tooling references existing rows rather than retrofitting
identity.
- Modules **we host** as convenience services are ordinary SaaS billing — no special
machinery in the product.
machinery in the product. *(Updated 2026-07-19, HT-79 managed hosting: hosting is now
the **mainline** module install path, not just an occasional convenience — clicking
Install provisions a Resonant IQ-hosted instance. The "no special machinery in the
product" clause still holds literally: the machinery — a hosting control plane that
holds the license key and per-desk provisioning grant — lives entirely **outside** the
AGPL core, never in the product. The self-host path remains as the escape hatch. See
`specs/modules/marketplace-v1.md` §3d/§5.)*

## 6. Changelog

Expand Down Expand Up @@ -212,3 +218,8 @@ now so the marketplace design inherits it:
marketplace plumbing "stays deferred to its charter phase," which no longer
matches step 4's own supersession note or `marketplace-v1.md` §1's "launch-day,
built now" framing. Reworded so both steps agree.
- **2026-07-19** (HT-79, managed hosting): §5's "modules we host … no special machinery
in the product" bullet annotated — hosting is now the mainline install path
(`marketplace-v1.md` v1.1), delivered by a hosting control plane that sits outside the
AGPL core, so the "no special machinery in the product" clause still holds. Free/paid
line and build sequence unchanged; the substrate stays AGPL-free.
Loading