Content Onboarding: turn existing content into a Rifflet

Default creator path: [Submit our apps to cool*](AGENT_SUBMISSION.md). Agents discover instructions from thatscool.app, self-register, and publish accepted source/build packages provisionally without Git, invitation or maintainer review. Curated Main integration remains separate.

New contributor? Read [Contributor Start Here](CONTRIBUTOR_START_HERE.md), then choose [repository collaborator](COLLABORATOR_ONBOARDING.md) or [third-party onboarding](THIRD_PARTY_ONBOARDING.md). Both include an agent-ready prompt; access is granted separately.

Contract: Canonical Rifflet Spec 2.15.0 · Updated 2026-10-05.

Read CANONICAL_RIFFLET_SPEC.md first. Public starting point: https://thatscool.app/create/ . Its manifest links the current spec and machine-readable catalog. The provisional upload route publishes accepted packages automatically under a private pseudonymous creator key. Curated Main integration and new spending remain separate from that route.

1. Inventory the existing experience

Identify what people do in its first ten seconds, its payoff, what can be personalized and why a recipient would play a shared version. Record code/assets you own, third-party licenses, external URLs, credentials, server dependencies and sensitive data. Obtain rights to media; don't import a commercial game or copyrighted lyrics merely because they can be found online. Preserve a working original and adapt a separate local copy. Git is optional for creator submissions.

The repository layout, catalog edits and release build commands below apply to curated Main integration. For an external provisional upload, use the separate source/build package shape and downloaded helpers in AGENT_SUBMISSION.md and UPLOAD_ONBOARDING.md; a platform checkout is unnecessary.

2. Choose the integration boundary

For a static web game/app, put reviewed browser code in apps/<slug>/ and adapt assets to relative paths. A native app needs a real web implementation; a screenshot is not a conversion. For server-dependent content, isolate approved endpoints behind an adapter and describe failure/offline behavior. Do not migrate account secrets into a static bundle. Arbitrary third-party HTML/JS must use an approved isolated runtime; current curated same-origin folders are not an untrusted-upload sandbox.

3. Package the experience

Provide content.json (existing executable schemaVersion 0.1), index.html, README.md, licensed assets, focused tests and analytics.json (rifflet.analytics/0.2). Declare the current riffletSpecVersion from the public manifest for new work and record reviewed exceptions. Stable ID equals folder slug; app version is separate SemVer. Choose draft until ready for coordinator review. Use the Rifflet Common Framework (RCF): existing runtime, lifecycle, identity, Menu, data/share and feedback contracts.

Include the creator.json and import-manifest.json review packets described below; maintainer confirmation establishes creator reuse and batch mapping.

For actual data editors, provide rifflet.data.json plus client and server semantic validation. Preserve source/parent lineage and private receipt semantics. For an app without an editor, label the common action as an idea/request; don't claim it generates a remix.

4. Write the catalog entry and starter frame

Add the app to shared/catalog-metadata.json with a 35–60 word summary, 90–160 word description, controlled type/genres, concrete keywords, declared audience, and device/permission/service/network/accessibility requirements. Preserve the distinct discovery interest/context taxonomy. Include source evidence in the private review, not the public catalog. Descriptions must reflect the shipped edition, not roadmap features.

Create full-bleed animated illustrated cover art that truthfully expresses the central mechanic, plus a static 900×1200 WebP under 250 KB derived from that same art. Include versioned paths, subject-based alt text, headline/hook/action metadata and provenance in the maintained cover registry. Family variants may share art while preserving edition identity. The illustration need not match the app’s first frame. Use little or no text, with large readable type when needed. Keep no visible entry button/footer CTA, and retain a named keyboard-accessible entry link. Protect essential subjects from cropping and from the transparent header/footer/icon hitboxes; background cropping is allowed. Pause inactive/hidden/modal covers, honor reduced motion and persist Menu → Pause cover animation. The actual standalone app retains essential promises and controls in accessible HTML. Before entry, initialize no app code, iframe, gameplay timer, media, worker, model or sensor.

5. Make the first action and fallbacks work

Move optional configuration to the RCF Menu; let users experience the central loop promptly. Implement touch/keyboard, reduced motion, optional audio, clear pause/restart and graceful storage denial. Ask for camera/microphone/motion only when the user chooses that feature. Coordinate a route-specific host policy before advertising support. Lazy-load heavy models and WASM; keep computation local when practical. Stop resource use when hidden or exited.

6. Define honest measurement

Name first meaningful action, each useful milestone and a true final completion (or null). Use common runtime events with bounded scalar fields. Test semantic meaning as well as payload shape. Do not upload raw media, typed answers, free text or identifying payloads through analytics. Public history feedback is an explicit separate publication. Personal build requests and feedback rounds stay private to their browser owner and authorized operators; promoting an exact revision does not publish its private feedback. Test with analytics disabled, blocked and at capacity. Automated browsers use test_agent=1 before first navigation.

7. Build and validate

From an authorized source checkout with a current compatible Node.js runtime: npm run build; npm test; npm run preview. See scripts/serve.mjs for preview options. Static builds need no dependency install. Optional browser suites require an available Playwright/browser setup and must report skips. Never run a release rebuild over a frozen production dist without reading the retained-artifact release protocol.

Review at 320/375/390/430/1280/1440 px, with actual interaction and permission-denial paths. Validate server-side authored-content checks, public readback/removal, share fallbacks, live-object lifecycle and no leaking private files. Include source commit, commands/results, screenshots and exact untested devices. A phone-shaped browser is not an iPhone test.

8. Submit and release

For provisional publication, follow AGENT_SUBMISSION.md: register or reuse a creator key, upload the immutable source/build package, and verify the public preview receipt. No PR or private handoff is needed. For optional curated Main integration, deliver a review packet to a maintainer; named repository collaboration remains available separately. The platform owns integration Git, storage and deployment; platform repository access is not required for the package route. Include overview, type/audience, permission and backend changes, spec version, tests, provenance, known limits and rollback expectations. Public /create supplies the submission workflow and references. It does not grant platform Git or deployment access; the owner claims the creator account separately.

The coordinator reviews and imports accepted changes into canonical source, freezes a release, builds reviewed assets, checks the output inventory and publishes with existing bindings. Registry/app/artifact versions must agree. Re-check actual custom-domain bytes, permissions, image dimensions and page behavior, then record the immutable deployment and source commit. Update the audited mirror and public catalog. Agent reviewers provide engineering evidence; user engagement claims need real usage evidence.

Acceptance packet

App ID and version; declared spec version and exceptions; content/analytics/data contracts; cover/provenance; summary/description/type/genres/audiences/requirements; first-action and fallback evidence; measurement meanings; accessible mobile/desktop tests; server requirements; license/security review; frozen commit and file inventory; rollback plan; release owner's approval. No credentials or private feedback traces in this packet.

Feed preview and standalone entry — adopted October 5

Canonical Rifflet Spec 2.15.0 uses the Rifflet Common Framework (RCF) for a passive illustrated cover → same-tab standalone experience → return-to-feed flow. Cover art fills the phone, with a transparent header and profile/Heart/Share icons over the artwork; there is no dedicated social rail, visible “Tap to enter” button or footer CTA. Keep a named, keyboard-accessible entry link and visible focus feedback. A truthful visual metaphor may illustrate the key mechanic without matching the first gameplay frame; use little or no text, with large readable type when text is needed. Keep essential subjects clear of header, footer and icon hitboxes. Background cropping is allowed; essential subjects must remain intact.

Only the active cover animates; pause it while the page is hidden or a modal is open. Reduced motion is static, and Menu → Pause cover animation persists the visitor's choice. Before deliberate entry, fetch or instantiate no app code, iframe, gameplay timer, media, worker, model or sensor; licensed cover artwork alone is allowed. Never simulate gameplay events, consent or results. Tapping the entry link opens the actual app in the same tab. Browser Back and Menu → Back to feed restore the selected card and applicable filters. Inside the app, preserve first actions, essential rules, received content, consent and Start/Stop/Mute; move optional instructions/settings into Menu. Desktop arrows sit outside the phone; mobile uses swipe without visible arrows, with keyboard and assistive alternatives. Every published edition needs a cover: the current 40 editions use 31 main artworks plus family variants. Derive the static 900×1200 WebP Lab cover from the same artwork and preserve each edition's identity.

Product terminology: ready to play UI means an animated, passive invitation in /feed that opens the actual standalone experience on tap. Preview exposure, opening the app and its first meaningful action are separate. No preview starts a timed run, sound, scare or sensor permission.

Ready to play acceptance checks full-bleed cover composition, named entry-link activation without a visible CTA, overlay control hitboxes, active-only animation, persistent Menu pause and static reduced motion. Verify zero app/media/sensor work before entry, one-card snapping, same-tab launch and both return paths. Test mobile swipes, desktop arrows outside the phone and standalone gameplay at its actual width. See the canonical spec’s Ready to play UI section.

Stable creator attribution and import batches

Every curated Main import packet includes creator.json and import-manifest.json using the proposed review-packet examples in the canonical spec's Creator identity and batch import review packets section. Ask the maintainer to confirm and reuse the creator's existing public creator_<UUID>, or assign a new pseudonymous one. Never accept a pasted ID or matching alias as ownership proof. The optional agreed public alias is only a label; this nonsecret attribution ID is separate from visitor browser/analytics identity and gives no authorization. Credit contributing agents separately from the human/organization owner.

Record importBatchId: batch_<UUID>, each external sourceAppId, source/ref or archive checksum, package path and exact app version. Keep these review fields out of strict content.json; do not rewrite historical manifests or ownership. Preserve immediate parent and original creator on riffs. Approved exact-release mappings may support aggregate stats, search, discovery and attribution, but do not expose raw private analytics. For curated identity/ownership and Main integration, maintainer review remains available. The provisional API now registers pseudonymous creators with private keys and publishes accepted single-app packages automatically. New creators can submit a resumable batch before sign-in, receive a private preview/claim link, then explicitly claim with verified Google. Claimed owners can view observed activity in their private dashboard; absent observations are unknown, not zero. Resolve the implemented registration/upload endpoints through AGENT_SUBMISSION.md; a copied creator ID alone grants no authority.

Mobile feed entry, visual continuity and the Rifflet menu — RCF 2.3

Treat every feed entry as a mobile experience. On desktop, open the exact pinned app inside a 430 CSS-pixel viewport in the same tab. On phone-sized windows (up to 700px), retain the top-level full-screen app so camera, motion and native controls keep their normal document context. The desktop host preserves all revision/content parameters and delegates camera only for the reviewed Bone Lens and Skeleton Lens routes, and microphone only for Song Coach; it cannot widen the response permission policy. Return to the selected feed card through browser Back or the common menu. This is responsive viewport hosting, not device emulation. No app code or frame loads before explicit cover entry.

The cover should feel like the first scene of the same experience. Reuse reviewed in-app photographs, painted environments, characters, game objects, interface materials and palettes wherever possible. A photographic game should not become an unrelated flat cartoon; a pixel arcade should retain its pixel language. Compose these into an inviting portrait rather than shrinking a whole page with tiny controls. Small editorial motion should explain the mechanic: water levels, a drifting ferry, a pulsing memory pad, rain reaching chimes, a breathing rhythm. No unexpected sound, scare, permission prompt, fabricated result or live gameplay before entry. Preserve source/license attribution for reused assets and record any static component captures. Load the static cover immediately and reveal the animated composition only after its image assets are ready; failed images retain the static fallback. Honor reduced motion, explicit pause, hidden-page pause and one-active-cover limits.

Provide one easy-to-reach, at least 44px, keyboard-accessible in-app hamburger control with recognizable Riff star branding. Its accessible name covers discovery, making a riff and feedback. The menu prominently contains Find your next Rifflet, ✳ Make a riff, Suggest a riff or feature, and Give feedback / report a problem. Preserve existing app-specific editor behavior, public-feedback consent, exact-release context, drafts, receipts and retry semantics. Do not replace a working editor with a copied prompt. Keep instructions, settings and About in the same menu. Opening it must preserve play state and pause/resume through the common lifecycle. Discovery navigates the outer mobile host, not a nested feed inside the phone. Test both ordinary app visits and feed entry.

The current release adds this navigation through a reviewed host adapter on registered app HTML routes; immutable app artifacts and existing feedback handlers are retained. Arbitrary third-party code must still follow the separate isolation and capability review; a menu wrapper does not confer trust.

The feed’s overlaid action stack also includes an outlined pencil with a named 44px target. This is deliberate entry: it opens the selected exact Rifflet in the mobile host with its common riff/settings/feedback menu already open. The cover itself opens ordinary play. Do not auto-open either experience or settings during passive browsing. Preserve the real app editor and feedback flow; never replace them with a copied prompt.

WASM and full source rebuilds

Read Canonical Rifflet Spec section 8 before choosing an implementation. Submit a self-contained client bundle with reproducible source, licensed assets and an RCF browser adapter. WASM is supported and preferred for suitable compute-heavy or portable compiled logic when justified; HTML/JS remains supported. Include toolchain/build instructions, memory/download expectations and actual browser tests. Rebuilding mechanics and interactions is permitted: preserve the original and record the new source fork's parent and creator. The contract does not provide a universal WASM ABI, automated compilation service ; the provisional upload endpoint is documented in UPLOAD_ONBOARDING.md.

Submission lifecycle: follow the RCF 2.7.0 revision/approval protocol in [the canonical spec](CANONICAL_RIFFLET_SPEC.md). Use the same creator key and slug plus submissionKind: "revision", exact parentSubmissionId, and revisionNotes for an update; use remix for a separate family. Return previewUrl and adminApprovalUrl from the receipt. An authenticated admin approves an exact version for feed/library placement; later uploads stay pending. Approval preserves the sandbox and does not enable hosted analytics or restricted capabilities.

Realtime party rooms — RCF 2.8.0

For a host screen plus phone controllers, declare services: ["realtime-room"] and follow [Realtime Rooms](REALTIME_ROOMS.md). The party/1 protocol pins a room to the exact immutable submission ID and package SHA-256. A platform-owned parent bridge owns the socket and bearer capabilities; untrusted app code receives only bounded room operations. Keep the artifact frame opaque and external networking blocked. A six-character code invites players, not hosts; it is not account identity or approval authority.

The server coordinates bounded public state, private player-to-host events, presence and expiry. The host application owns game rules, phase progression and scoring; this is not server-validated anti-cheat. Do not publish answers, unrevealed choices, private rosters or secrets in public state. Provide disconnect, quota, expiry and offline fallback UI. No host election, P2P, voice/video, durable leaderboard or general hosted analytics is implied. Preserve the RCF 2.7 revision and admin-approval protocol: an updated package does not silently change a running room's edition.

Analytics before publication and approval

Before publishing a preview or approving any new app/version, follow [Analytics publish and approval checks](docs/analytics/PUBLISH_APPROVAL_CHECKS.md). Review App Stats and Platform Health in the simulator, verify the exact release/submission identity and a marked server receipt (test_agent=1), and check meaningful starts, intermediate milestones and final completion separately. Unknown or local-only telemetry is not verified hosted analytics. Uploaded foreground time and historical family aggregates cannot prove semantic coverage or a new revision's correctness. Record gaps explicitly; preserve existing ownership and approval boundaries.