Skip to content
SHC Docs

Marketplace roadmap: the four questions, answered

Layer 5. Objects. Objects

Status: PROPOSED, 2026-08-18. Not a ruling. §7 lists the twelve decisions that are the owner’s and nobody else’s; everything above it is inventory, measurement and a recommendation.

This document exists because four questions were asked in one sitting and each of them has a different shape: what must the marketplace support, what did I not think of, what is this for, and how does it meet the portal. They are answered here in that order.

Companions: ../decisions/2026-08-16-marketplace-identity-and-install.md (who is logged in where; §1–§8 settled, §10/Q4 open) · ../decisions/2026-08-16-marketplace-entitlement-and-licensing.md (what a paid install adds) · ../decisions/2026-08-16-marketplace-belongs-in-the-shc-tenant.md · docs/proposals/2026-08-18-app-metrics-and-trust.md (shc!294, the metric taxonomy) · docs/decisions/2026-08-18-comment-backend-frappe-not-adopted.md (shc!291).

Every load-bearing claim carries [M] (measured: a command, a file:line or an HTTP probe, all re-run 2026-08-18) or [I] (inferred: reasoning from measured facts, not itself observed). A claim with neither mark is a recommendation, and can be argued with on taste.

Measurement baseline. shc origin/main at 32d44a56f; ce at 97a0e0c4; live probes against marketplace.selfhostedcloud.org, api.marketplace.selfhostedcloud.org and my.selfhostedcloud.org on 2026-08-18.


0. Read this before anything else: the estate is not main

Section titled “0. Read this before anything else: the estate is not main”

The single most expensive fact in this document. Six substantial capabilities are merged, pinned into the built artefacts, and invisible in production. Decisions taken by looking at the live site are being taken against a picture that is weeks old.

CapabilityLive, 2026-08-18On main
Home-page navigation0 <a href> in 305,848 bytes [M]every card, chip, shelf and hero is a real anchor: StoreHome.tsx:45 “EVERY NAVIGATION ON THIS PAGE IS A REAL <a href>” [M]
Community layerlisting_community → No module named 'marketplace.community' [M]5 modules under frappe/apps/marketplace/marketplace/community/: api, installs, policy, ranking [M]
Install counterabsentApp Listing.install_cluster_count + install_count_basis; api.py:739 recompute_install_counts(); rendered at ListingCommunity.tsx:123 [M]
Tags77 of 167 rows, all add-ons, zero apps [M]82 of 99 app.yaml declare tags; seeder fix landed at 5a61c245c [M]
Taxonomy43 categories [M]31 distinct category: values [M]
Listing page2 <script type=ld+json>, 2 <h1> on /apps/nextcloud [M]single render [M]
Catalogue size90 apps + 77 add-ons = 167 [M]99 packages + 77 add-ons; 9 apps have never been seeded [M]

Nothing in that table is new work. It is a deploy and a seeder run.

Second fact of the same kind, and it is worse. The store’s entire purpose is untested code. portal.agent.enroll (the method the cluster daemon POSTs its enrolment to (ce modules/portal/client.go:74)) does not exist [M]: frappe/apps/portal/portal/agent.py whitelists exactly one method, session (agent.py:423), and a grep for def enroll or def deregister across frappe/apps/portal/portal/ returns nothing [M]. The bench instead implements portal.api.redeem_registration_code (api.py:141), a different unsigned shape. The two halves of the channel do not speak the same protocol, so no estate can register, so no install can be dispatched, so the tier gate, the payment route, the verified-install mark and the install count are all written and none has ever run [I].

The signing refusal everyone points at (signing_available() needing all three of portal_dispatch_key/kid/bundle) is real and is later in the ladder [M]. A perfect vendor key changes nothing until enrolment speaks one protocol.


1. Question one: everything the marketplace must support

Section titled “1. Question one: everything the marketplace must support”

Grouped by function; each row carries a state and its evidence. The four states are LIVE (deployed and visible), MERGED (on main, invisible in production: see §0), IN FLIGHT (a named MR), OWED (decided, unwritten) and NOT STARTED.

CapabilityStateEvidence
Catalogue listing, 167 rowsLIVElive probe [M]
Server-resolved ?category= / ?q= / ?shelf=MERGEDStoreHome.tsx loader [M]
Every card/chip/shelf as a real anchorMERGEDStoreHome.tsx:45,258,265,322 [M]
Featured / New / Updated shelves, each printing the date it sorted byMERGEDhome/shelves.ts:44-52 [M]
Trending / Popular shelvesREFUSED IN WRITINGshelves.ts:20-40 [M]
Search that ranks, tags as linksIN FLIGHTshc!213, draft, held for a demo [M]
Category landing pages as real URLsNOT STARTEDapps/marketplace/routes/ holds 3 human routes [M]
Tag landing pagesNOT STARTEDsame
Capability / socket landing pagesNOT STARTED§2.1 item 1
Comparison pagesNOT STARTED§2.2 item 3
CapabilityStateEvidence
Listing page per app and per add-onLIVE/apps/nextcloud 200 [M]
Flathub order: header, chip grid, screenshots, description, versions, links, relatedIN FLIGHTshc!264: 209 files, in CONFLICT [M]
The five-chip fact row (version, category, tier, verified licence, tags)MERGEDListingFacts.tsx:29-31: “THIS IS THE ONLY METADATA SURFACE THE PAGE HAS” [M]
Screenshots / galleryPARTIAL22 of 99 app.yaml carry gallery:; 14 gallery directories [M]
Related appsMERGED, weakmodel.ts:453 keys off category: 31 categories over 167 rows [M]
Light / dark / system controlIN FLIGHTshc!282 [M]
App-specific register (per-app copy)IN FLIGHTshc!289 [M]
Backup contract, SSO capability, resource floor, integration listNOT STARTEDsee §1.6

Nine gates in portal.dispatch.request_install order. Gates 1–2 work.

#GateState
1Storefront Install anchor → <portal>/install?app=LIVE: a real <a target=_blank rel=noopener>, pinned to fire no network request by installHandoff.spec.tsx:125-130 [M]
2Portal /install pageLIVE: my.selfhostedcloud.org/install → 200 [M]
3Caller holds a portal roleSHUT: Portal Settings.default_role empty, so a fresh identity is 403’d by portal.api.fleet [M]
4Cluster is registeredSHUT: the real blocker. portal.agent.enroll does not exist [M]
5–7Tier gate, payment route, add-on stack pickerwritten, never executed [I]
8Directive is signedSHUT: signing_available(), agent.py:402 [M]
9Daemon applies and reportsnever reached [I]
CapabilityStateEvidence
App Review (stars + required body), App Comment (threaded, parent_comment+depth), App Comment Vote, App Content ReportMERGED4 DocTypes [M]
Wilson lower-bound ranking, no time decayMERGEDcommunity/ranking.py [M]
Guest-readable projections over an explicit allowlist; _display_name refuses any string containing @MERGEDcommunity/api.py [M]
submit_review / withdraw_review / submit_comment / vote_comment / report_contentMERGEDapi.py:322,383,402,450,518 [M]
A caller for any write endpointNONE ANYWHEREonly callers in the repo are two SSR reads, serverCatalog.ts:389,393 [M]
The write surface itself (<portal>/reviews)404 IN PRODUCTIONcommunity.ts:170 builds it; my.selfhostedcloud.org/reviews → 404 [M]
aggregateRating / Review JSON-LDwithheld on purposelistingSeo.ts:41-46: “DELIBERATELY NEVER EMITTED… we have no ratings” [M]

This is the highest-value cheap fix on the board. A finished backend, five endpoints, zero callers, and the one link that would call them is a 404 the storefront renders on every listing page [M].

CapabilityState
App Content Report DocType + moderation methodsMERGED [M]
Moderation queue UINOT STARTED
Curator badges applied from the back officeIN FLIGHT (curator lane)
Featured with a time window and a blurbIN FLIGHT (curator lane)

1.6 Metrics, trust and evidence: the largest gap in the product

Section titled “1.6 Metrics, trust and evidence: the largest gap in the product”
CapabilityStateEvidence
Install count, k-anonymised at floor 5, labelled “installs from registered clusters”MERGEDinstalls.py:130,135; community.ts:24,31 [M]
Version-in-the-wildNOT STARTEDCluster.app_inventory already carries [{name, version}] verbatim [M]
Backup contract on the listingNOT STARTED70 backup.yaml in the tree; 0 references to backup or restore in features/marketplace/src [M]
SSO capability on the listingNOT STARTED41 oidc.plug.yaml; 5 oidc references in the storefront, all comments and a preconnect [M]
Resource floorNOT STARTED, and not sourceableno mem_limit in the catalogue [M]
Integration graph on the listingNOT STARTED222 *.plug.yaml, 62 *.socket.yaml; 3 references in the storefront [M]
Container CVE scanIN FLIGHT (app-intelligence lane)
Composite trust scoreIN FLIGHT: §3 argues against itshc!294

The headline for this section. apps/ holds 75,638 lines of bats behavioural tests over 89 of 99 packages, 113,080 lines of catalogue YAML, 222 declared integration plugs across 39 kinds, 70 backup contracts and 41 SSO wirings [M]. The storefront renders five chips [M]. Not one fact that required running the software reaches a visitor.

CapabilityStateEvidence
sitemap.xml, robots.txtMERGEDroutes/sitemap.xml+api.ts, robots.txt+api.ts [M]
Per-listing JSON-LD (SoftwareApplication, FAQPage)LIVE, but doubled2 blocks live [M]
aggregateRating + ReviewOWED, gated on reviews existinglistingSeo.ts:41-46 [M]
srcset for gallery artOWED: stored, emitted nowhere[M]
The middle layer of crawlable pagesNOT STARTED: biggest single lever3 human routes → ~169 indexable URLs [M]
CapabilityStateEvidence
Storefront account UINONE. ZERO.grep -rniI "useAuth|KeycloakProvider|signIn(" over features/marketplace/src → 0 hits; apps/marketplace/src/app.ts:130 hard-codes keycloak: { enabled: false } [M]
Portal profile iconDOES NOT EXISTgrep -rniI avatar features/portal/src → 0 hits. The portal has a bare “Sign out” button and a separate “Signed in as <email>” band, AppLayout.tsx:158,184 [M]
Console account controlEXISTS, and is the one to copyfeatures/console/src/springboard/AccountButton.tsx:61: a 26px monogram with a dropdown [M]
The shareable rule moduleEXISTS, wrong packagespringboard/avatar.ts + avatar.spec.ts [M]
Storefront loginBLOCKED AT THE IdPthe cloud realm’s portal client allows one exact redirect URI; api.marketplace… → 400 “Invalid parameter: redirect_uri” [M, 2026-08-17]

1.9 Ranked: what is OWED and NOT STARTED, by value × cheapness

Section titled “1.9 Ranked: what is OWED and NOT STARTED, by value × cheapness”
  1. Roll the estate. Six capabilities, zero new code. §0.
  2. Re-run the seeder. Tags on 90 apps, 31-category taxonomy, 9 unseeded packages.
  3. Fix cluster registration (gate 4). Until this lands the store’s purpose is untested. Pick one: implement portal.agent.enroll + deregister on the bench to match wire.EnrollRequest, or repoint the daemon at redeem_registration_code. One, not both.
  4. Ship apps/portal/routes/reviews.tsx. Turns a live 404 into the first caller of five finished endpoints.
  5. Emit aggregateRating + Review JSON-LD the day reviews exist. Roughly one function; it is the SEO stars the “a star requires a review” ruling exists for.
  6. Socket/plug chips + /connect/<socket> pages. §2.1 item 1.
  7. Merge shc!282 (theme control); it also opens the header slot the account chip needs.
  8. Set Portal Settings.default_role (gate 3). One field.
  9. Unblock shc!264: rebase or slice. 209 files in conflict; the cost grows hourly [M].
  10. Emit the stored srcset.
  11. Category and tag routes.
  12. Backup / SSO / integration chips from files already in the tree.
  13. Curator badges (subject to the §3 rule on badge vocabulary).
  14. Screenshots for the 77 listings without art, and a headless value so an absence reads as a fact.
  15. App Version.released_on backfill: NULL for all 90 rows [M].
  16. Catalogue-change RSS.
  17. Moderation queue.
  18. Verify the 68 license: {id: unverified} postures [M].
  19. CVE scanning, presented as what we did about it (§3).
  20. Spanish routing.

2. Question two: what was not mentioned, and what was over-valued

Section titled “2. Question two: what was not mentioned, and what was over-valued”

2.1 Do now: every one of these runs on data already in the repo

Section titled “2.1 Do now: every one of these runs on data already in the repo”
  1. ★ Socket/plug chips and /connect/<socket> pages. Two chip rows per listing: “Plugs into: Postgres · Keycloak · SMTP · S3” from its *.plug.yaml, “Provides: …” from its *.socket.yaml, every chip an <a href> to a page listing that socket’s consumers. Measured: 222 plug files and 62 socket files; 71 of 99 packages consume at least one plug, 56 provide at least one socket; demand ranks postgres 42, oidc 41, smtp 40, s3 17, llm 12, mysql 9 [M]. That is roughly 62 new crawlable pages of exactly the query shape that ranks (“self-hosted apps with S3 support”, “self-hosted apps with SSO”) generated from a find, with no new data and no moderation burden. Against a storefront that today has three human routes [M], this is the highest value-per-unit-of- effort item in this document.

  2. Replace category-relatedness with socket adjacency. model.ts:453 keys “related” off category: 31 categories over 167 rows, so the rail is near-random siblings [M]. “Apps that plug into the same things you do” and “apps that can consume this app” are real recommendations. Same component, different query.

  3. A “Backup: supported” chip. 70 packages ship backup.yaml [M]. Lock-in is the first fear a self-hoster names, and this is the only store that can answer it per-app from a file that already exists.

  4. Version-in-the-wild. Cluster.app_inventory carries {name, version} and is rewritten on every heartbeat (portal/api.py:295) [M]; the install-count walker already reads that JSON. One more aggregate gives “most estates run 34”, the single most useful fact for should I upgrade, and structurally impossible for any store that does not operate the software. Same floor, same label, same privacy posture. Marginal cost near zero [I].

  5. Migration chips and platform landing pages. Adapters exist for ~15 platforms; only 8 .migration.yaml recipes across 5 packages [M]. “Coming from Umbrel / CasaOS / Portainer / TrueNAS” is pure acquisition traffic. Honesty gate: publish proven adapters loudly and fixture-only ones as “adapter exists, not yet proven live”. A false migration promise moves somebody’s data and is the most expensive lie this store could tell.

  6. Finish the 68 unverified licences. Not a feature, a content job. Licence is a top-three purchase question and the store declines to answer it for 69% of the catalogue [M]. It also gates any honest “Verified” rail.

  7. Say when an absence is information. 77 of 167 listings have no gallery art [M], and headless packages (bridges, connectors, the external-* wrappers) can never be screenshotted. “A slot with no data is ABSENT” is right for polish, but it leaves a visitor unable to tell “no UI exists” from “nobody got round to it”. One line (“Headless: no user interface”) converts a gap into a fact.

  1. Stacks and bundles. “A small business office” is an authored marketing artefact needing hand-maintenance per combination. The generated version is already in the data: the plug files say installing Nextcloud implies a postgres, an SMTP and an OIDC. Ship “What this needs” (a generated dependency preview) first, and see whether anyone asks for curated bundles. Also: the noun-space is full. app / add-on / preset / vapp / integration are all taken, and App Listing.listing_type already reserves an unseeded integration value (app_listing.json:55) [M]. A “stack” concept needs a vocabulary ruling before code.

  2. Personalised “works with what you already run”. Right feature, wrong surface. The storefront must serve anonymous crawlers. Ship the anonymous half now (“Uses Postgres and Keycloak; if you already run them, this reuses them”) and put the personalised half where a session exists.

  3. Comparison pages. Accept the SEO logic, reject the naive build. 99 packages is 4,851 pairs, and a generated grid of thin pages is the doorway-page pattern search engines demote [I]. Restrict to both apps in the catalogue, same category, compared only on measured facts: digest-pinned image, socket list, backup support, installs, version in the wild. That is perhaps 30–60 pages that say something nobody else can say.

  4. Deprecation and succession. apps/RETIRED exists [M]. Add a succeeded_by field the day the first app retires, not before.

  5. Third-party submission. Imports a review burden and a trust tier with no staff behind it. Ship the request path first: a public page of “apps people asked for” with counts. One form, a demand signal for what to package next, and a public page full of app names people are actively searching for.

2.3 ★ The critical half: stated wants that are worth less than they look

Section titled “2.3 ★ The critical half: stated wants that are worth less than they look”

This was asked for explicitly. Four answers.

  1. The Reddit-style comment system does not earn its burden at this size, and the proof is in our own code. The install count needs a privacy floor of 5 because below five the number deanonymises (installs.py:103-115; a listing showing one install that also carries one verified-install review, “the badge and the review are the same person”) [M]. A registered population small enough that 5 is deanonymising will not produce threaded discussion [I]. Ship threading, votes, per-app bans and image uploads and the result is an empty comment section on ~160 of 167 pages, which reads as dead, is worse than absent, and contradicts the standing “a slot with no data is ABSENT” ruling. Reshape: keep the landed schema (parent_comment/depth already exist; do not rip them out), ship flat, text-only, no image uploads, flagship apps only, portal-account-gated, and turn threading on the day one page reaches 20 comments. Reject image uploads outright until moderator hours are allocated: on an anonymously-browsable site that is a legal exposure, not a cleanup chore.

  2. “Trending” has no basis and would be invented. Of the six pages in flight: Popular now has a real basis (the install count), New and Updated have creation/modified, Verified has the licence posture. Trending needs a time series and nothing stores one: community_updated_on is a recompute stamp, not history [M]. Either add a small daily snapshot table first (cheap, and it also unlocks the version-adoption trend line) or drop the page. On a product whose whole register is we do not fake measurements, an invented ordering costs more than a missing page.

  3. The Flathub 2×3 chip grid copies the wrong slots. Flathub’s chips answer desktop questions: licence, download size, runtime. SHC has none of those honestly: 68 of 99 packages carry license: {id: unverified} [M], and there is no download and no size. Copy Flathub’s discipline (dense, scannable, no prose), not its slots. The six that are true here: what it plugs into · what it provides · packaging tier · backup supported · headless or not · installs from registered clusters. Five of the six are computable today [M].

  4. The featured markdown blurb fights the “people don’t read” ruling. Both cannot hold. A featured slot should be a reason in six words.


SHC’s marketplace is the operator’s record: for every app we run, what actually happened when we ran it: does the backup restore, does SSO work end to end, does the upgrade survive a major, what does it cost to run, what does it connect to. The install button is how you get the same result.

Two corrections are folded into that sentence and both matter.

“Evidence”, not “data”. Anyone with a crawler produces data: GitHub stars, CVE feeds, release dates, licence strings. A better-funded catalogue out-scrapes us within a year and a page built on scraped aggregates has no moat [I]. OpenRouter is not defensible because it has statistics; it is defensible because it routes the traffic it measures. Snyk is not defensible because it has metrics; it runs the scan. The instrument is the product; the data is exhaust. SHC’s instrument is that it installs and operates every listing, and the instrument is already built: 75,638 lines of behavioural tests over 89 of 99 packages, 113,080 lines of catalogue YAML, 222 integration plugs, 70 backup contracts [M].

Depth on a curated set, not “the authoritative reference for self-hosted software”. 99 packages will never out-cover awesome-selfhosted or Flathub, and a reference that claims coverage it does not have loses the credibility that is its only asset [I].

Could a competitor with a crawler produce this number? Yes → table stakes: ship it, never lead with it. No → that is the product.

And the falsifiable one:

If we deleted the Install button, would the page still be worth a bookmark? Today: no. Every unit of work should move that toward yes.

  1. Surface the evidence that already exists before adding any new measurement. Backup contract, SSO capability, integration matrix, test coverage, packaging tier. Zero collection cost, and the listing page currently renders none of it [M].
  2. The middle layer of crawlable pages is the biggest SEO lever available and needs no new data. Three human routes today [M].
  3. Reviews before threads. App Review.verified_install and verified_basis already exist [M]. A review from a cluster we can see installed the app is evidence; an anonymous star is noise.
  4. Publish the measurements, refuse the composite. A single trust score hides its inputs and is unfalsifiable. OpenRouter publishes no score: it publishes latency, throughput, price and uptime per provider. If a composite ships anyway, every input must be visible and each must link to the measurement that produced it.
  5. Frame CVE data as what we did about it. “We scanned the image we ship, at this digest, on this date, and here is what changed” is operator’s evidence and is unbeatable. A raw count is a commodity anyone with Trivy reproduces, and puts us in a fight on data nobody owns [I].
  6. A badge either derives from a measurement and links to it, or it is lexically and visually distinct from one. “Editor’s pick”, never “Verified”. The codebase already has the instinct: ListingFacts.tsx says “verified” only when verified, and renders ”★ Featured” rather than leaking the internal tier word [M].
  7. Adopt Flathub above the fold and abandon it below. Flathub’s anatomy is a store anatomy; adopting it wholesale caps the page at store depth. The chip grid is the top of the data surface, not the whole of it.
  8. The crawler is a distribution channel, not an audience. Its requirements (server-rendered, anonymous, <a href>-navigable, unique substantive content per URL) are identical to the self-hoster’s, so designing for it costs nothing. Already ruled at 2026-08-16-marketplace-identity-and-install.md §1: “a crawler has no account.”
  1. The crawler. Not a concession, a requirement.
  2. The self-hoster choosing software. The one who converts. He wants: does it work, what does it cost to run, does SSO actually work, will my backups restore, what did people who ran it say.
  3. The existing customer. Smallest population, cheapest to serve, arrives from a console tile with intent. Do not design the store around him.

★ What the marketplace explicitly is NOT

Section titled “★ What the marketplace explicitly is NOT”

The scope-creep backstop. Each line has cost something to hold.

  1. Not a comprehensive catalogue. 99 packages, no breadth claim.
  2. Not a popularity contest. No downloads, ever; shc install runs on the operator’s machine and reports to nobody, “which is not an oversight, it is the product” (shelves.ts) [M]. The only permitted count is installs from registered clusters, k-anonymised, labelled as the partial thing it is.
  3. Not a package repository. Repos are added by CLI, never the store.
  4. Not a social network. Comments exist to answer which of these should I run, and what breaks, not to host a community.
  5. Not the console. It never administers clusters, shows live health or manages running apps.
  6. Not a native app: owner ruling 2026-08-17, recorded at StoreHome.tsx:6-8. See the conflict in §7.
  7. Not a marketing site for SHC. selfhostedcloud.org sells SHC. The marketplace sells the apps, and sells SHC by being obviously right about them.
  8. Not a vendor self-publishing platform, yet. See the fork below.

“We ran it” is true of 100% of listings today, which is why the claim can attach to the store. The day a third party publishes its own listing that stops being true, and the evidence claim must become per-listing or it dies quietly; the store keeps saying we measured this over pages where nobody did [I].

This is not an argument against third-party publishing. It is an argument for deciding now, at zero third-party listings, that provenance is a per-listing field. App Gallery Asset already models exactly this pattern with provenance / captured_from / grant_url [M]. Copy it upward before the retrofit costs anything.


“The user profile icon should show in the same spot as it shows on portal.” The portal has no profile icon. grep -rniI avatar features/portal/src → 0 hits [M]. What the portal has is a chromeless “Sign out” button and a separate band below the header reading “Signed in as <email>” (AppLayout.tsx:158,184) [M].

The surface that has the avatar is the console: features/console/src/springboard/AccountButton.tsx:61, a 26px monogram/avatar with a dropdown carrying identity, environment scope and Sign out, built 2026-08-18 on “shouldn’t top left have my profile image?” [M]. That is the control to propagate, and the portal needs it as much as the storefront does.

4.2 A literally shared component is impossible; here is what is shared

Section titled “4.2 A literally shared component is impossible; here is what is shared”

The portal header is Tamagui (SizableText/XStack/Button from @multiplatform.one/components) and ships native. The storefront header on shc!282’s branch is hand-written <header>/<nav>/<a> with CSS classes, under an exemption that names its own boundary: “the exemption is the storefront’s home page AND THE CHROME AROUND IT, and it stops there. The portal and the console are NOT exempt” (apps/marketplace/home.css:12-18) [M]. Two markup systems, two style systems, one explicitly web-only.

What is actually shared, in descending order of realism:

  • (a) The rule module: a real, literal share. features/console/src/springboard/avatar.ts moved into a package. avatarDisplayName() and resolveAvatarImageURL() are pure, tested, and carry the ruling with three measurements behind it: the avatar is a monogram unless the image is same-origin, because hotlinking a third-party avatar publishes the user’s identity and presence off the estate, the estate’s own ivatar 403s off-LAN, and Keycloak’s picture claim commonly carries exactly such a URL [M]. Keep avatar.spec.ts with it. All three surfaces import the same functions.
  • (b) The contract. One table, in one place, stating what the control contains in each of its three states (signed out, authenticated, auth disabled) and what the menu holds. Pinned per surface by a spec that reads that table, so drift shows up as a red test rather than a screenshot.
  • (c) The pixels. 26px circle, top-right on storefront and portal, top-left on the console springboard where it is already ruled. Same monogram ladder (glyphSeed/glyphColors/glyphMonogram from @package/springboard-ui) so a person and an app tile are drawn by the same rules everywhere.

The honest cost: the chip is written twice: once in Tamagui for the portal (a genuine lift from the console, both inside the token regime) and once in hand-HTML for the storefront. Roughly one file each plus a CSS block. The drift risk is behaviour, not pixels, which is why (b) matters more than (c).

4.3 Identity on the storefront is progressive enhancement, and nothing else

Section titled “4.3 Identity on the storefront is progressive enhancement, and nothing else”

Logged out is the default, and the served HTML is byte-identical for every anonymous visitor: full catalogue, full listing, every published review and comment, star averages, install command, Install button as an inert <a>, and a plain “Sign in” <a href> to the portal authorize entry. No provider mounts, no fetch fires, no session is checked. That is the same door Install already uses, and installHandoff.spec.tsx’s zero-fetch property survives untouched [M].

Logged in, painted after hydration only: the avatar chip, write a review, reply and vote, report content, “your reviews”, “you run this” marks. Install dispatch still crosses to the portal, because that flow needs the cluster dropdown and the tier routing InstallScreen.tsx already owns [M].

What breaks if anyone puts a wall up; say it in these words:

  • A login redirect on / or /apps/* takes the store out of the index. Googlebot follows the 302, meets a login page, and 167 listing URLs collapse to one non-indexable page [I].
  • The aggregateRating and Review rich results die with it; they need review bodies present in the anonymous document.
  • Third parties read the catalogue unauthenticated today. A wall is a breaking API change dressed as a UI change.
  • Mechanically: mounting KeycloakProvider in the storefront’s SSR tree reopens the measured double-render: apps/portal/src/keycloakProvider.tsx recorded +11,561 bytes per request and <title> never reaching <head>, on the one surface where document bytes and <title> are the entire product [M].

The rule that follows: no auth provider in the storefront’s SSR tree, ever. The chip’s session is read client-side after hydration, the way theme/schemeBoot.ts reads the theme [M]. Pin it with a spec; precedent exists, shellChrome.spec.ts already polices the stylesheet budget on the same file [M].

4.4 What an account means on the storefront: the seam, stated once

Section titled “4.4 What an account means on the storefront: the seam, stated once”

The marketplace owns objects whose subject is a LISTING: your reviews, comments, votes, reports, saved apps. The portal owns objects whose subject is an ESTATE: clusters, registration codes, install dispatch, billing and tier, install requests and spending policy, and notifications about apps you run. One profile, portal-owned, because the Frappe User row is portal-minted by SSO (portal/identity.py) and the display name is what community/api.py _display_name publishes [M]. The marketplace links to that profile; it does not host it.

Recommendation on the write question: relax the storefront-only-links rule for community writes (review, comment, vote, report) through a scoped storefront Keycloak client, and keep install dispatch on the portal forever. A storefront token must not be able to call portal.dispatch.request_install. That separation is what makes “the store can post a review as you” a different grant from “the store can install software on your cluster”.

Realms: two, and it stays two. Storefront and portal both use realm cloud on auth.corp.bitspur.com, which is what makes one login across both true [M]. An estate console uses its own daemon-managed realm. The customer realm asserting into ours is refused by 2026-08-16-marketplace-identity-and-install.md §3 as a trust boundary, and that is not reopened.

The cloud realm’s portal client allows exactly one redirect URI. Measured against the live IdP 2026-08-17: my.selfhostedcloud.org/... → 200; api.marketplace.selfhostedcloud.org/... → 400 “Invalid parameter: redirect_uri” [M]. deploy/marketplace.shc.yaml:236-243 names widening that list “to a wildcard” as “the one change that must never be made to a shared production realm” [M].

So marketplace.selfhostedcloud.org cannot complete a Keycloak login today. Every item about a profile chip is dead until this is ruled. The ask is not a wildcard: it is a second public client storefront, PKCE, no secret, one exact redirect URI, scoped to the community endpoints only, added through the existing scripts/ensure-portal-keycloak-client.sh the deployfile already names as a pre-promote step [M].

4.6 ★ In-shell versus new tab: the concrete answer

Section titled “4.6 ★ In-shell versus new tab: the concrete answer”

KILL THE IFRAME. KEEP THE TILE. SHIP THE ASSERTION.

The tile is right and it is ruled: Marketplace stays a kind: "route" entry on the springboard grid (systemApps.ts:88-104, on the 2026-08-18 reversal “marketplace shouldn’t feel like im leaving the system it’s just an app on the console”) [M], with its icon, position and launch gesture. What changes is what the route does. Instead of framing the store (MarketplaceScreen.tsx:116) it asks the daemon to mint the §5 assertion and performs a top-level navigation to marketplace.selfhostedcloud.org/enter?a=<assertion>.

Why this is the fix and not a compromise:

  • The frame cannot hold a session. Not degrades, cannot. Safari ITP blocks third-party cookies outright and Chrome is closing the same door; the workarounds (CHIPS, the Storage Access API) put a tracking-consent prompt in front of a customer’s staff inside their own admin console. MarketplaceScreen.tsx’s own header admits framing “does NOT carry a session across origins, which is exactly the problem” [M].
  • The two identities are correct and must not be merged. §3 refuses the customer realm asserting into our store as a trust boundary, not a preference: the customer admin owns that Keycloak and could mint themselves entitlements. So the answer can never be “one session”.
  • The actual fix for “you’re actually switching users” is to name both, not to hide one. Today the frame shows a store that is logged out (or logged in as someone else) under a band explaining that the user is two people. With the handoff: the assertion says which cluster, the store’s own login says who you are, and the header says both at once: “clay@… · installing to compose01.hel1”. It stops being strange the moment the UI stops pretending it is one identity and starts being useful about two.
  • It costs one login, once. The store’s session persists on marketplace. as a first-party origin; the assertion is minted per launch, so the second launch from the tile is silent [I].
  • It removes the cluster dropdown for console-initiated installs, which is §5’s quiet win.
  • §6’s anti-replay property is why it is safe: holding an assertion proves you were already inside that cluster, and the daemon honours a dispatch only if it matches a request it minted. Two independent mechanisms must fail before anything installs anywhere.

The interim, shipping this week: one line and one deletion. Flip the tile to kind: "external" until the assertion exists. useSystemAppNavigation.ts already implements the branch and says in-file that “today no registry entry is external, so this branch is a contract, not a path anyone walks” [M]. The contract exists; use it. That removes a surface documented to be session-broken in Safari, and replaces the identity-seam band with nothing, because a new tab needs no apology.

The prerequisite is this lane’s own work. The console tile currently frames a store whose header has no account at all: there is nothing on screen that could name either identity. The header work is not a nicety beside the handoff; it is what makes the handoff legible.

  • The tombstone. App Review.author, App Comment.author, App Comment Vote.voter and App Content Report.reporter are all Link User with reqd: 1, permissions are System Manager only, and there is no ignore_links, no on_delete and no doc_events on User anywhere in the marketplace app [M]. Inference from Frappe’s default check_if_doc_is_linked: a User who has ever reviewed anything is undeletable [I]. Recommendation: on account deletion, re-point author/voter/reporter to one deleted@ sentinel rather than deleting or nulling. Keep the row, keep identity_key (already a one-way sha256, community/api.py _identity_key) [M], let _display_name return the existing user_<8hex> pseudonym. Clear verified_install: verification is a claim about a live account↔cluster relationship. Do not recompute the listing average: letting account churn move a public number is an attack surface. Keep withdraw_review as a real permanent delete and keep it on a different code path; retracting your own words and closing your account are different acts.
  • “Your installs” has no estate-side data source. ce ent/schema/ deployment.go carries name, tenant, app, version, digest, environment, node ids and status, and no installed_by / requested_by / created_by; grep -rn "installed_by\|InstalledBy" ent/schema/ → 0 [M, ce@97a0e0c4]. Until an actor column lands, “apps have owners” is a claim rather than a design.

Sequenced so each step unblocks the next, not by size.

Phase 0: stop deciding against a stale picture (days)

  1. Roll the estate to main.
  2. Re-run the seeder. Verify: tags on 90 apps, 31 categories, 99 packages, one <h1> on a listing page, listing_community answering.
  3. Rewrite the stale doc block in home/shelves.ts; it still asserts “There is no install counter anywhere in this system” and installs.py contradicts it on the same branch [M]. Whichever way §7 rules on Trending, that block misleads the next reader.

Phase 1: make the store’s purpose testable (weeks)

  1. Fix cluster registration (gate 4): one protocol, not two.
  2. Set Portal Settings.default_role (gate 3).
  3. Roll the vendor key’s public half (gate 8).
  4. Sequence 4–6 deliberately, because the review write door will refuse for a completely different reason and the two failures look identical on a listing page.

Phase 2: close the community loop (weeks)

  1. Ship apps/portal/routes/reviews.tsx: same shape as InstallScreen: Keycloak bearer through usePortal’s HttpClient, refusals rendered verbatim, isRoleRefusal handled as its own state. Review + comment + vote + withdraw + report in one screen.
  2. Emit aggregateRating + Review JSON-LD the day it has data.
  3. Ship reviews before threads; comments flat, text-only, flagship-only.

Phase 3: the identity chip (weeks, gated on §7 ruling 1)

  1. Move avatar.ts + avatar.spec.ts into a package.
  2. Lift AccountButton onto the portal: a genuine component lift, both surfaces inside the token regime. Do this before the storefront chip, or “the same spot as portal” still points at nothing.
  3. Merge shc!282, then land the storefront chip in the header slot it opens, so that file is merged once.
  4. Add the storefront Keycloak client with one exact redirect URI.
  5. Add the spec asserting the chip is absent from the server-rendered document and that no auth provider mounts in the storefront tree.

Phase 4: the seam (weeks)

  1. Flip the console tile to kind: "external", one line, ships now.
  2. Build the daemon-side assertion mint (ce) and the storefront /enter route (shc).
  3. Ship the dual-identity header line: “clay@… · installing to compose01.hel1”.
  4. Delete the iframe and the apology band.
  5. Amend 2026-08-16-marketplace-identity-and-install.md §4 to record that the no-iframe ruling was reversed 2026-08-18, shipped as an iframe (c0a6273, on main), and is being resolved by implementing §5 rather than by averaging the two. That document currently reads as settled and it is not.

Phase 5: the data surface and the middle layer (ongoing, highest SEO value)

  1. Socket/plug chips + /connect/<socket> pages.
  2. Socket adjacency replaces category relatedness.
  3. Backup / SSO / headless chips from files already in the tree.
  4. Category and tag routes.
  5. Version-in-the-wild.
  6. Unblock shc!264: rebase or slice.
  7. Licence verification burn-down (68 packages).
  8. Comparison pages, restricted per §2.2.
  9. Daily snapshot table, if Trending is funded.
  10. Close ce’s actor-column gap so “your installs” has a source.

Each was believed and each is wrong as of 2026-08-18.

BelievedMeasured
”No install counter exists anywhere”It shipped. install_cluster_count + install_count_basis, recompute_install_counts() at api.py:739, floor of 5, rendered at ListingCommunity.tsx:123 [M]
“The taxonomy pass is merged”It is not; it lives in shc!264, which is in conflict. Live bench: 43 categories; main: 31 [M]
“70 of 167 listings have gallery art”22 of 99 app.yaml carry gallery:; 14 gallery directories [M]
“The flagship double-render is fixed”Fixed on main; still 2 JSON-LD and 2 <h1> in production [M]
“The Install button refuses because of the vendor key”The key gate is eighth. The blocker is fourth: portal.agent.enroll does not exist [M]
“96 packages / 79,628 bats lines / 255 plugs / 75 backups”99 packages, 75,638 bats lines, 222 plug files, 70 backup.yaml, 62 socket files, 41 oidc.plug.yaml [M]
“The portal has a profile icon to match”It has none. The console does [M]
“167 = 90 apps + 77 add-ons”Confirmed live, and main now carries 99 packages, so 9 have never been seeded [M]
“App Version.released_on is NULL for all 90”Confirmed [M]
“The storefront has zero account UI”Confirmed, and deliberate: apps/marketplace/src/app.ts:130 hard-codes keycloak: { enabled: false } [M]

Twelve. Nothing below can be settled by measurement.

  1. The redirect URI: the single gate. May we add one more exact redirect URI to the cloud realm, as a second public client storefront, for https://marketplace.selfhostedcloud.org? The deployfile forbids widening to a wildcard; two exact URIs on two clients is not a wildcard. Without this the storefront can never hold a session and every profile-chip item is dead.
  2. In-shell versus new tab. Recommendation: kill the iframe, keep the tile, ship the §5 signed handoff (§4.6). Confirm, because it means deleting a surface that shipped to main eight days after it was asked for. And confirm the interim: kind: "external" now, or keep framing with the apology band?
  3. Gate 4 versus gate 8. Implement portal.agent.enroll + deregister on the bench to match wire.EnrollRequest, or repoint the daemon at redeem_registration_code. One, not both.
  4. The premise correction. Lift AccountButton onto the portal first and then match it on the storefront (three surfaces, one rule module) or leave the portal alone and have the storefront copy the console directly? Recommendation: the former.
  5. Can the storefront write, or does it only link? Recommendation: relax it for community writes only through the scoped storefront client; keep install dispatch on the portal forever.
  6. Trending and Popular. shelves.ts refused them in writing; the install counter makes them technically sourceable from a biased sample with most of the catalogue under the floor. One ruling: two in-flight lanes currently point opposite ways. Recommendation: they stay refused, and Trending is dropped unless a daily snapshot table is funded.
  7. Comments. Accept or reject the reshape to flat / text-only / no image uploads / flagship-only. Image uploads on an anonymously-browsable store need an explicit yes/no and a named moderator with allocated hours if yes.
  8. Trust score: composite or components? Recommendation: components-only. If a composite ships anyway, rule that every input is visible and links to its measurement.
  9. Badge vocabulary. Rule that a badge either derives from a measurement and links to it, or is lexically distinct from one (“Editor’s pick”, never “Verified”). Without this, curator opinion and measurement become indistinguishable on the same chip row.
  10. The GNOME native client versus the 2026-08-17 ruling that the marketplace is never a native app. Both are in the tree today (apps/marketplace/gnome/ and StoreHome.tsx:6-8) [M]. Which survives?
  11. Vocabulary before any stacks work. app / add-on / preset / vapp / integration are all taken and listing_type already reserves an unseeded integration. Is “stack” a new noun, or is the reserved slot it? And separately: is App Listing.bucket (flagship / enterprise / integrated / standalone / classic) the SHC-integration-maturity axis the openness lane is designing, or a different one? Two maturity ladders on one page will contradict each other.
  12. Third-party publishing and provenance. Decide now, at zero third-party listings, whether “who measured this” becomes a per-listing field. The retrofit is free today and expensive later.

Two smaller ones that ride along: does a deleted account’s review keep its verified-install mark? (recommendation: no; verification is a claim about a live relationship) and keep-and-pseudonymise versus delete-the-content (recommendation: keep-and-pseudonymise; note that today neither is possible because the account is undeletable [I]).