The app roster — about a dozen launcher apps

Maintainer, 2026-10-10 (binding for this phase):

• "see we don't have a gazillion apps" — about a dozen launcher apps.
• Settings packages belong in the settings apps; examples belong in the Examples app; categories stay as they are.
• "games are included in personal tier" — Chess, Role Play, Quality Time and Quality Time (de) are tier: personal, and so is the Games host.
• Personal and Games are new host apps. This directive is the owner's explicit go for these two new packages.

This page records phase 2 of the plan in Apps live on the instance (Store/AppsOnTheInstance, §6 and §8). Phase 2 changes only declarations: app, hostedIn, extensionSlot, tier and display names. It copies no app data into anyone's home. The launcher still reads the _App records until phase 1a's AppDirectory is switched on, so until then the existing install machinery does what it always does with these declarations:

• a hosted package's tile is removed by the Store's hosted-tile purge (HostedTilePurgeWatcher), and the package appears on its host's shelf instead;
• the two new preInstalled hosts, Personal and Games, are auto-installed like every pre-installed pack: each viewer gets their _App tile and _Install record (StandardPacks, AppTileRefresh). Those are launcher bookkeeping, not app content; phases 4–6 retire them.

The roster

Only these packages may declare app: true. The literal set is APP_ROSTER in scripts/validate-repos.py; adding a tile is a reviewed one-line change to it.

Satellite repos carry their own roster: SocialMedia, Reinsurance, Crm, Manufacturing, the FundReporting root, and none in Education.

Where every other package lives

category values are unchanged everywhere.

Reachable on the day it lands

Until phase 1a's AppDirectory is the launcher's source (core #6446, behind Home:AppSource, default Records), a tile exists only as a {viewer}/_App record, and the same deploy that hosts a package purges its tile (HostedTilePurgeWatcher). So a host must be reachable before its guests lose their tiles, and a package whose host has no shelf yet is not hosted yet:

• Personal and Games are preInstalled, as Developer is. A brand-new package has no viewer install, and app: true alone mints no record (AppTileRefresh.Missing mints only for an auto-installing app or one a viewer's manifest names), so without it the replacement host would be unreachable while the hosted tiles are purged. Each host page holds only its shelves; every game and connector on it keeps its own tier and its own Get action, so preInstalled opens no paid content. Once the launcher reads AppDirectory, the Games tile is shown by plan (personal).
• The Admin moves wait for an Admin shelf. hostedIn: Admin removes a tile while the core Admin app renders no shelf, so Providers, Governance, BuildServer, Observability and AzureCostManagement keep standing on their own. Governance drops app: true (it is an enterprise package, so an install still tiles it today). They get hostedIn: Admin in phase 3, in the same change that adds Administration › Operations and AI providers.

The gate

check_app_roster in validate-repos.py fails a pull request when:

• a Store/Plugin root declares app: true and is not on the roster;
• a hostedIn names a host that is not DECLARED in HOST_SLOTS — the literal host → slots contract ({user}/Settings, AI/AiThreads, Developer/Home, Personal/Home, Games/Home, Edu/Courses; a satellite adds its own host, e.g. SocialMedia). A host is valid because its shelf is declared, never because a node exists at that path; Admin is absent until its shelf lands. A declared host inside this repo must also exist as a node (never a README, raw content/ file or …/index alias);
• hostedIn without extensionSlot, a slot the host does not render, a slot without hostedIn, or an app that is also a section (a {user}/Settings tab excepted);
• a roster entry that does not declare app: true or has no root at all.

The checker is one block, the same text in all seven plugin repos; only APP_ROSTER and HOST_SLOTS are repo input. Its fixtures also run from main(), so a regression reds ordinary validation.

Both failures are silent at runtime: a stray app is one more tile on every home, and a missing host removes the package's tile and lists it on a shelf nobody renders. --self-test runs the gate over fixtures in both directions.

Host apps and their shelves

Cornerstone (in this repo, category Insurance) is listed by the plan as absorbed by Reinsurance; this phase leaves it standing on its own because the Reinsurance host lives in a satellite repo.

After a deploy — in this order

A merge reaches an instance through the registry once main's settle-locks pull request lands. Then:

1. Recycle the Store root (enqueue_recycle(path: "Store", reason: "app roster deployed: rebind the catalog")), so its hub binds the new catalog. Recycling mints no tile for Personal or Games: they install nothing (Localize takes its NothingToInstall branch), and the hosted-tile purge runs on that activation anyway.

2. Run RefreshAppTiles straight after: a Store/Maintenance node under Admin/Maintenance with task: RefreshAppTiles, requestedAction: Run. This step mints the hosts' tiles and fixes the rename:

   • AppTileRefresh.Missing mints a tile for every package that is an app, preInstalled and not hosted, which is exactly Personal and Games, in every home.
   • A tile copies its package's name at install, so this also renames the Developer tiles to Examples.

   Between the purge and this run there is a short window in which a home has neither the old guest tiles nor the new hosts. No data is touched: every package stays at its own URL and on its host's shelf. A viewer who renders the Store in that window self-heals the same way. Phase 1a's AppDirectory removes the window, because the launcher stops reading records.

3. Recycle the changed types: Developer/DeveloperApp, Edu/CourseCatalog, Personal/PersonalApp and Games/GamesApp, each with enqueue_recycle(path, reason). The reason is required and is recorded in the audit under Admin/_Recycle.

4. Verify on a real home (get @{user}/_App/*). Personal and Games are present; Google, iCloud, Home Assistant, Apple Music, Apple Weather, Learning Roadmap and the game tiles are gone; the Examples tile reads Examples. Personal/Home and Games/Home render their sections.