Distribution UX Readiness

Use this checklist to split Build.moe distribution work into focused, Codex-ready issues. Keep implementation changes in the dedicated surface repositories and only update the root submodule pointers after those changes are committed and pushed.

Current Inventory

Surface	Path	Repository	Current state	Distribution anchor
Web	web/build-moe	uebliche/build-moe-web	Next.js surface with public catalog pages, auth, presence, live counts, admin pages, translations, ads, OpenNext, and Cloudflare configuration.	wrangler.jsonc, package.json, app/manifest.ts, public/sw.js
App	app/build-moe	uebliche/build-moe-app	Tauri and Vue shell with service-exchange auth, discover/create/profile routes, backend configuration, desktop packaging, and mobile scaffolding.	src-tauri/tauri.conf.json, package.json, src/lib/backend.ts
Mod	mod/build-moe	uebliche/build-moe-mod	Fabric client mod based on the current mod-template stack, with Uebliche.dev deploy metadata and release-matrix wiring.	uebliche.dev, build.gradle, gradle.properties, mod/release-registry.toml
Docs	docs/build-moe	uebliche/docs	Public docs landing page, feature checklist, changelog, downloads component, and this readiness checklist.	docs/build-moe/*, .vitepress/public-docs.ts

Cross-Surface Release Contract

• [ ] Define one supported release channel model for web, app, and mod (snapshot, rc, release) and document which surfaces use each channel.
• [ ] Confirm the version identifier format shown to users and download APIs is YYYY.M.D-bHHMMSS<ShortHash> or the current project-approved successor.
• [ ] Decide whether Build.moe release notes are authored once in docs/build-moe/changelog.md or mirrored per surface before publishing.
• [ ] Add a pre-release smoke list that names the exact web route, app route, and mod task to verify before a public rollout.
• [ ] Document rollback ownership for web deploys, app releases, and mod artifacts.

Web Distribution UX

• [ ] Make the public download/install route obvious from the Build.moe landing page and docs overview.
• [ ] Expose current app and mod versions from the docs/download data source so users do not need to inspect repository tags.
• [ ] Add no-JS fallback copy for download links and support links on public pages.
• [ ] Verify Cloudflare/OpenNext output includes the manifest, service worker, icons, and all static assets required by install prompts.
• [ ] Add a release checklist item for validating BACKEND, NEXT_PUBLIC_API_BASE, auth callback URLs, and production headers.

App Distribution UX

• [ ] Define the primary install path for desktop users and the fallback path for platform-specific blockers.
• [ ] Add an in-app version/about surface that shows the app version, API base, auth service id, and support link.
• [ ] Document update behavior for desktop builds and mobile builds separately.
• [ ] Verify deep-link auth callbacks after packaged install, not only in the Vite/Tauri dev flow.
• [ ] Add a release smoke check covering sign-in, discover feed loading, profile loading, and sign-out.

Mod Distribution UX

• [ ] Confirm the public package target before release; the current Modrinth metadata points at MpREDR75 and should be verified during release preparation.
• [ ] Add user-facing install instructions for the supported Minecraft version range and loader set.
• [ ] Ensure Uebliche.dev deploy metadata, mod/release-registry.toml, and the docs download component agree on artifact names and channels.
• [ ] Add a release smoke check for ./gradlew build with the selected Minecraft version and loader.
• [ ] Decide which in-game entrypoint or command proves the companion UX is working after install.

Support And Observability

• [ ] Route support links consistently across web, app, mod docs, and packaged surfaces.
• [ ] Add a short troubleshooting section for auth callback failures, stale app builds, missing mod artifacts, and API reachability.
• [ ] Define the minimum telemetry or logs needed to diagnose failed installs without exposing secrets.
• [ ] Keep environment examples separate from real .env files and never publish secrets in docs.

Future Codex-Ready Issue Criteria

Every follow-up issue should include:

• The exact surface: web, app, mod, docs, or cross-surface.
• The user-visible outcome and one narrow non-goal.
• The files or modules expected to change.
• Required translation updates when UI copy changes.
• Required changelog location.
• Validation commands that can run without production secrets.
• Submodule handling notes when a surface repo must be changed.
• Acceptance criteria that can be checked from a clean checkout.

Prefer one issue per surface unless the work is only a documentation or release contract update.