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).
How to read the evidence marks
Section titled “How to read the evidence marks”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.
| Capability | Live, 2026-08-18 | On main |
|---|---|---|
| Home-page navigation | 0 <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 layer | listing_community → No module named 'marketplace.community' [M] | 5 modules under frappe/apps/marketplace/marketplace/community/: api, installs, policy, ranking [M] |
| Install counter | absent | App Listing.install_cluster_count + install_count_basis; api.py:739 recompute_install_counts(); rendered at ListingCommunity.tsx:123 [M] |
| Tags | 77 of 167 rows, all add-ons, zero apps [M] | 82 of 99 app.yaml declare tags; seeder fix landed at 5a61c245c [M] |
| Taxonomy | 43 categories [M] | 31 distinct category: values [M] |
| Listing page | 2 <script type=ld+json>, 2 <h1> on /apps/nextcloud [M] | single render [M] |
| Catalogue size | 90 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.
1.1 Browse, search, filter
Section titled “1.1 Browse, search, filter”| Capability | State | Evidence |
|---|---|---|
| Catalogue listing, 167 rows | LIVE | live probe [M] |
Server-resolved ?category= / ?q= / ?shelf= | MERGED | StoreHome.tsx loader [M] |
| Every card/chip/shelf as a real anchor | MERGED | StoreHome.tsx:45,258,265,322 [M] |
| Featured / New / Updated shelves, each printing the date it sorted by | MERGED | home/shelves.ts:44-52 [M] |
| Trending / Popular shelves | REFUSED IN WRITING | shelves.ts:20-40 [M] |
| Search that ranks, tags as links | IN FLIGHT | shc!213, draft, held for a demo [M] |
| Category landing pages as real URLs | NOT STARTED | apps/marketplace/routes/ holds 3 human routes [M] |
| Tag landing pages | NOT STARTED | same |
| Capability / socket landing pages | NOT STARTED | §2.1 item 1 |
| Comparison pages | NOT STARTED | §2.2 item 3 |
1.2 The listing page
Section titled “1.2 The listing page”| Capability | State | Evidence |
|---|---|---|
| Listing page per app and per add-on | LIVE | /apps/nextcloud 200 [M] |
| Flathub order: header, chip grid, screenshots, description, versions, links, related | IN FLIGHT | shc!264: 209 files, in CONFLICT [M] |
| The five-chip fact row (version, category, tier, verified licence, tags) | MERGED | ListingFacts.tsx:29-31: “THIS IS THE ONLY METADATA SURFACE THE PAGE HAS” [M] |
| Screenshots / gallery | PARTIAL | 22 of 99 app.yaml carry gallery:; 14 gallery directories [M] |
| Related apps | MERGED, weak | model.ts:453 keys off category: 31 categories over 167 rows [M] |
| Light / dark / system control | IN FLIGHT | shc!282 [M] |
| App-specific register (per-app copy) | IN FLIGHT | shc!289 [M] |
| Backup contract, SSO capability, resource floor, integration list | NOT STARTED | see §1.6 |
1.3 Install
Section titled “1.3 Install”Nine gates in portal.dispatch.request_install order. Gates 1–2 work.
| # | Gate | State |
|---|---|---|
| 1 | Storefront 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] |
| 2 | Portal /install page | LIVE: my.selfhostedcloud.org/install → 200 [M] |
| 3 | Caller holds a portal role | SHUT: Portal Settings.default_role empty, so a fresh identity is 403’d by portal.api.fleet [M] |
| 4 | Cluster is registered | SHUT: the real blocker. portal.agent.enroll does not exist [M] |
| 5–7 | Tier gate, payment route, add-on stack picker | written, never executed [I] |
| 8 | Directive is signed | SHUT: signing_available(), agent.py:402 [M] |
| 9 | Daemon applies and reports | never reached [I] |
1.4 Community
Section titled “1.4 Community”| Capability | State | Evidence |
|---|---|---|
App Review (stars + required body), App Comment (threaded, parent_comment+depth), App Comment Vote, App Content Report | MERGED | 4 DocTypes [M] |
| Wilson lower-bound ranking, no time decay | MERGED | community/ranking.py [M] |
Guest-readable projections over an explicit allowlist; _display_name refuses any string containing @ | MERGED | community/api.py [M] |
submit_review / withdraw_review / submit_comment / vote_comment / report_content | MERGED | api.py:322,383,402,450,518 [M] |
| A caller for any write endpoint | NONE ANYWHERE | only callers in the repo are two SSR reads, serverCatalog.ts:389,393 [M] |
The write surface itself (<portal>/reviews) | 404 IN PRODUCTION | community.ts:170 builds it; my.selfhostedcloud.org/reviews → 404 [M] |
aggregateRating / Review JSON-LD | withheld on purpose | listingSeo.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].
1.5 Moderation and curation
Section titled “1.5 Moderation and curation”| Capability | State |
|---|---|
| App Content Report DocType + moderation methods | MERGED [M] |
| Moderation queue UI | NOT STARTED |
| Curator badges applied from the back office | IN FLIGHT (curator lane) |
| Featured with a time window and a blurb | IN 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”| Capability | State | Evidence |
|---|---|---|
| Install count, k-anonymised at floor 5, labelled “installs from registered clusters” | MERGED | installs.py:130,135; community.ts:24,31 [M] |
| Version-in-the-wild | NOT STARTED | Cluster.app_inventory already carries [{name, version}] verbatim [M] |
| Backup contract on the listing | NOT STARTED | 70 backup.yaml in the tree; 0 references to backup or restore in features/marketplace/src [M] |
| SSO capability on the listing | NOT STARTED | 41 oidc.plug.yaml; 5 oidc references in the storefront, all comments and a preconnect [M] |
| Resource floor | NOT STARTED, and not sourceable | no mem_limit in the catalogue [M] |
| Integration graph on the listing | NOT STARTED | 222 *.plug.yaml, 62 *.socket.yaml; 3 references in the storefront [M] |
| Container CVE scan | IN FLIGHT (app-intelligence lane) | |
| Composite trust score | IN FLIGHT: §3 argues against it | shc!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.
1.7 SEO
Section titled “1.7 SEO”| Capability | State | Evidence |
|---|---|---|
sitemap.xml, robots.txt | MERGED | routes/sitemap.xml+api.ts, robots.txt+api.ts [M] |
| Per-listing JSON-LD (SoftwareApplication, FAQPage) | LIVE, but doubled | 2 blocks live [M] |
aggregateRating + Review | OWED, gated on reviews existing | listingSeo.ts:41-46 [M] |
srcset for gallery art | OWED: stored, emitted nowhere | [M] |
| The middle layer of crawlable pages | NOT STARTED: biggest single lever | 3 human routes → ~169 indexable URLs [M] |
1.8 Identity and account
Section titled “1.8 Identity and account”| Capability | State | Evidence |
|---|---|---|
| Storefront account UI | NONE. 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 icon | DOES NOT EXIST | grep -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 control | EXISTS, and is the one to copy | features/console/src/springboard/AccountButton.tsx:61: a 26px monogram with a dropdown [M] |
| The shareable rule module | EXISTS, wrong package | springboard/avatar.ts + avatar.spec.ts [M] |
| Storefront login | BLOCKED AT THE IdP | the 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”- Roll the estate. Six capabilities, zero new code. §0.
- Re-run the seeder. Tags on 90 apps, 31-category taxonomy, 9 unseeded packages.
- Fix cluster registration (gate 4). Until this lands the store’s
purpose is untested. Pick one: implement
portal.agent.enroll+deregisteron the bench to matchwire.EnrollRequest, or repoint the daemon atredeem_registration_code. One, not both. - Ship
apps/portal/routes/reviews.tsx. Turns a live 404 into the first caller of five finished endpoints. - Emit
aggregateRating+ReviewJSON-LD the day reviews exist. Roughly one function; it is the SEO stars the “a star requires a review” ruling exists for. - Socket/plug chips +
/connect/<socket>pages. §2.1 item 1. - Merge shc!282 (theme control); it also opens the header slot the account chip needs.
- Set
Portal Settings.default_role(gate 3). One field. - Unblock shc!264: rebase or slice. 209 files in conflict; the cost grows hourly [M].
- Emit the stored
srcset. - Category and tag routes.
- Backup / SSO / integration chips from files already in the tree.
- Curator badges (subject to the §3 rule on badge vocabulary).
- Screenshots for the 77 listings without art, and a
headlessvalue so an absence reads as a fact. App Version.released_onbackfill: NULL for all 90 rows [M].- Catalogue-change RSS.
- Moderation queue.
- Verify the 68
license: {id: unverified}postures [M]. - CVE scanning, presented as what we did about it (§3).
- 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”-
★ 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 afind, 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. -
Replace category-relatedness with socket adjacency.
model.ts:453keys “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. -
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. -
Version-in-the-wild.
Cluster.app_inventorycarries{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]. -
Migration chips and platform landing pages. Adapters exist for ~15 platforms; only 8
.migration.yamlrecipes 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. -
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.
-
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.
2.2 Right idea, wrong time
Section titled “2.2 Right idea, wrong time”-
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_typealready reserves an unseededintegrationvalue (app_listing.json:55) [M]. A “stack” concept needs a vocabulary ruling before code. -
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.
-
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.
-
Deprecation and succession.
apps/RETIREDexists [M]. Add asucceeded_byfield the day the first app retires, not before. -
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.
-
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/depthalready 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. -
“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_onis 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. -
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]. -
The featured markdown blurb fights the “people don’t read” ruling. Both cannot hold. A featured slot should be a reason in six words.
3. Question three: the vision
Section titled “3. Question three: the vision”The paragraph
Section titled “The paragraph”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].
The test to hand every lane
Section titled “The test to hand every lane”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.
The consequences this implies
Section titled “The consequences this implies”- 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].
- The middle layer of crawlable pages is the biggest SEO lever available and needs no new data. Three human routes today [M].
- Reviews before threads.
App Review.verified_installandverified_basisalready exist [M]. A review from a cluster we can see installed the app is evidence; an anonymous star is noise. - 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.
- 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].
- 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.tsxsays “verified” only when verified, and renders ”★ Featured” rather than leaking the internal tier word [M]. - 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.
- 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 at2026-08-16-marketplace-identity-and-install.md§1: “a crawler has no account.”
The visitor, in order
Section titled “The visitor, in order”- The crawler. Not a concession, a requirement.
- 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.
- 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.
- Not a comprehensive catalogue. 99 packages, no breadth claim.
- Not a popularity contest. No downloads, ever;
shc installruns 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. - Not a package repository. Repos are added by CLI, never the store.
- Not a social network. Comments exist to answer which of these should I run, and what breaks, not to host a community.
- Not the console. It never administers clusters, shows live health or manages running apps.
- Not a native app: owner ruling 2026-08-17, recorded at
StoreHome.tsx:6-8. See the conflict in §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.
- Not a vendor self-publishing platform, yet. See the fork below.
★ The one strategic fork this exposes
Section titled “★ The one strategic fork this exposes”“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.
4. Question four: the portal seam
Section titled “4. Question four: the portal seam”4.1 The premise needs correcting first
Section titled “4.1 The premise needs correcting first”“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.tsmoved into a package.avatarDisplayName()andresolveAvatarImageURL()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’spictureclaim commonly carries exactly such a URL [M]. Keepavatar.spec.tswith 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/glyphMonogramfrom@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
aggregateRatingandReviewrich 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
KeycloakProviderin the storefront’s SSR tree reopens the measured double-render:apps/portal/src/keycloakProvider.tsxrecorded +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
Userrow is portal-minted by SSO (portal/identity.py) and the display name is whatcommunity/api.py _display_namepublishes [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.
4.5 ★ The blocker, and it is not design
Section titled “4.5 ★ The blocker, and it is not design”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.
4.7 Two seam items that need naming now
Section titled “4.7 Two seam items that need naming now”- The tombstone.
App Review.author,App Comment.author,App Comment Vote.voterandApp Content Report.reporterare allLink Userwithreqd: 1, permissions are System Manager only, and there is noignore_links, noon_deleteand nodoc_eventson User anywhere in the marketplace app [M]. Inference from Frappe’s defaultcheck_if_doc_is_linked: a User who has ever reviewed anything is undeletable [I]. Recommendation: on account deletion, re-pointauthor/voter/reporterto onedeleted@sentinel rather than deleting or nulling. Keep the row, keepidentity_key(already a one-way sha256,community/api.py _identity_key) [M], let_display_namereturn the existinguser_<8hex>pseudonym. Clearverified_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. Keepwithdraw_reviewas 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.gocarries name, tenant, app, version, digest, environment, node ids and status, and noinstalled_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.
5. The ordered work
Section titled “5. The ordered work”Sequenced so each step unblocks the next, not by size.
Phase 0: stop deciding against a stale picture (days)
- Roll the estate to
main. - Re-run the seeder. Verify: tags on 90 apps, 31 categories, 99 packages,
one
<h1>on a listing page,listing_communityanswering. - Rewrite the stale doc block in
home/shelves.ts; it still asserts “There is no install counter anywhere in this system” andinstalls.pycontradicts 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)
- Fix cluster registration (gate 4): one protocol, not two.
- Set
Portal Settings.default_role(gate 3). - Roll the vendor key’s public half (gate 8).
- 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)
- Ship
apps/portal/routes/reviews.tsx: same shape asInstallScreen: Keycloak bearer throughusePortal’s HttpClient, refusals rendered verbatim,isRoleRefusalhandled as its own state. Review + comment + vote + withdraw + report in one screen. - Emit
aggregateRating+ReviewJSON-LD the day it has data. - Ship reviews before threads; comments flat, text-only, flagship-only.
Phase 3: the identity chip (weeks, gated on §7 ruling 1)
- Move
avatar.ts+avatar.spec.tsinto a package. - Lift
AccountButtononto 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. - Merge shc!282, then land the storefront chip in the header slot it opens, so that file is merged once.
- Add the
storefrontKeycloak client with one exact redirect URI. - 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)
- Flip the console tile to
kind: "external", one line, ships now. - Build the daemon-side assertion mint (ce) and the storefront
/enterroute (shc). - Ship the dual-identity header line: “clay@… · installing to compose01.hel1”.
- Delete the iframe and the apology band.
- 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)
- Socket/plug chips +
/connect/<socket>pages. - Socket adjacency replaces category relatedness.
- Backup / SSO / headless chips from files already in the tree.
- Category and tag routes.
- Version-in-the-wild.
- Unblock shc!264: rebase or slice.
- Licence verification burn-down (68 packages).
- Comparison pages, restricted per §2.2.
- Daily snapshot table, if Trending is funded.
- Close ce’s actor-column gap so “your installs” has a source.
6. Corrections to the working record
Section titled “6. Corrections to the working record”Each was believed and each is wrong as of 2026-08-18.
| Believed | Measured |
|---|---|
| ”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] |
7. ★ What needs the owner’s ruling
Section titled “7. ★ What needs the owner’s ruling”Twelve. Nothing below can be settled by measurement.
- The redirect URI: the single gate. May we add one more exact
redirect URI to the
cloudrealm, as a second public clientstorefront, forhttps://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. - 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
maineight days after it was asked for. And confirm the interim:kind: "external"now, or keep framing with the apology band? - Gate 4 versus gate 8. Implement
portal.agent.enroll+deregisteron the bench to matchwire.EnrollRequest, or repoint the daemon atredeem_registration_code. One, not both. - The premise correction. Lift
AccountButtononto 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. - Can the storefront write, or does it only link? Recommendation:
relax it for community writes only through the scoped
storefrontclient; keep install dispatch on the portal forever. - Trending and Popular.
shelves.tsrefused 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. - 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.
- Trust score: composite or components? Recommendation: components-only. If a composite ships anyway, rule that every input is visible and links to its measurement.
- 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.
- 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/andStoreHome.tsx:6-8) [M]. Which survives? - Vocabulary before any stacks work. app / add-on / preset / vapp /
integration are all taken and
listing_typealready reserves an unseededintegration. Is “stack” a new noun, or is the reserved slot it? And separately: isApp 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. - 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]).