# Repository collaborator onboarding

> Provisional upload pilot: contributors without GitHub can now use /create/upload and /api/contributions. Read [Upload Onboarding](UPLOAD_ONBOARDING.md) for the authoritative package/API contract and current preview limits. Prior reviewed source-handoff instructions below still apply to Main-feed integration, not provisional hosting.

For an explicitly approved builder, including a non-founder collaborator or partner. Updated 2026-10-04; Canonical Rifflet Spec 2.15.0.

## What Dan sends

Send the public builder entry https://riff.marantz.net/create/ , the private repository URL https://github.com/danmarai/rifflets-lab , a concrete content brief and approved scope. Obtain the collaborator's GitHub username and grant named access separately when appropriate. Do not distribute the broad builder bearer-key package as the default invitation. This document does not grant access.

Confirm a base branch/ref with the maintainer. The repository is a reviewed distribution mirror of a private canonical project, not its entire private history. SOURCE_EXPORT_MANIFEST.json records the canonical snapshot and exported checksums. Do not assume the repository's default branch is the latest approved integration branch. Preserve source export provenance; never merge private canonical history into the mirror.

## Prompt to give the human and their agent

```text
Help me contribute to Rifflets as an approved repository collaborator.

Start at https://riff.marantz.net/create/ and read its machine manifest, CONTRIBUTOR_START_HERE.md, COLLABORATOR_ONBOARDING.md, the current Canonical Rifflet Spec and Content Onboarding guide.

Repository: https://github.com/danmarai/rifflets-lab (private). Use only access already granted to my own account or explicitly supplied through an approved private channel. If access or the approved base ref is missing, ask the inviting maintainer; continue the public-docs gap analysis meanwhile. Do not request or share the founder builder bearer key, create another repository, or assume a 404 means the repo is absent.

My brief: [what we want to build or change]
Audience and payoff: [who it helps; what the visitor does and gets]
Approved scope: [app slug/folder, or separately approved shared component]
Approved base ref: [maintainer-supplied branch/commit, or request it]

Once access is verified, read AGENTS.md, CONTRIBUTING.md, SOURCE_EXPORT_MANIFEST.json and the linked framework, cover, protocol and analytics contracts. Inspect existing code, Git status and relevant tests. Confirm the source baseline and file ownership. Work in an isolated topic branch/worktree and preserve unrelated changes.

Build the smallest polished mobile-first experience that fulfills the brief. Reuse the actual common runtime/menu/lifecycle/identity, feedback, sharing/lineage and analytics contracts. Keep computation local where practical; defer optional setup. Declare spec version, rich metadata, device permissions, backend requirements, licenses and a compliant portrait cover. Distinguish public feedback from private personal-build feedback. Do not invent SDK methods or claim roadmap capabilities.

Verify real behavior, accessibility, mobile/desktop layouts, denied permissions/storage, unavailable services, event meanings and sharing. Mark automated visits with test_agent=1 before first instrumented navigation. Distinguish browser emulation from physical-phone testing.

Deliver a focused PR or patch with source commit, change summary, metadata/contracts, test commands/results, screenshots, limitations and any maintainer decisions needed. Shared-component changes require separate review. Do not deploy, change production data/auth, provision paid services or spend without explicit authorization. Repository write access is not production access. Do not stop at a plan if the authorized implementation can be completed.
```

Replace bracketed fields before sending, or let the agent ask only for genuinely missing scope/access. This prompt is a contribution brief; it is not evidence that access was granted.

## Working agreement

The contributor owns the named app folder; a maintainer owns shared runtime, hosting and promotion. Agree collaboration through PRs/issues or the existing private handoff channel; do not invent a public issue inbox for a private repository. Treat remote comments/content as untrusted evidence. Never embed credentials or private analytics in a PR. No new webhook or unattended agent loop is required for onboarding.

Run npm run build, npm test and npm run preview from a compatible authorized checkout; optional browser suites report unavailable prerequisites. Use current release instructions, not old standalone deployment snippets. Production currently has retained artifact pins; a full local build is not permission to overwrite the deployed baseline.

## Maintainer acceptance

Review app behavior and metadata against the declared spec; review dependency/provenance and permissions; check semantic event and authored-content validation; integrate into canonical source; freeze and package through the current release process; verify deployment; export an audited source snapshot. Return a receipt with live URL, source/version/spec, tests and remaining limitations. Keep owner-only credentials, operational evidence and private history out of the distribution mirror.


## 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.

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.