# Wheelie community package, example, and demo contributions

Agent docs index: /llms.txt

Wheelie welcomes community packages, examples, and demos when they keep the same
launch-boundary discipline as the core docs: descriptor-first metadata, pinned
source, explicit support states, no raw secrets, and no claims that a preview or
fixture is generally available.

This page covers public contribution review for:

- descriptor-only packages and agent/profile recipes;
- example repositories, starter apps, and validation fixtures;
- demos, screenshots, videos, and written walkthroughs;
- docs changes that teach a Wheelie workflow.

It does not create a live publication flow, arbitrary plugin runtime,
private-source hydration path, executable-helper approval, or payment/provider
support. Those need separate product approval and typed trust receipts.

Machine-readable review evidence lives at
[`/services/wheelie/community-contribution-policy.json`](/services/wheelie/community-contribution-policy.json).

## Contribution trust labels

Use one of these labels in public copy, package metadata, gallery cards, and
review notes.

| Label | Use for | Required public wording |
| --- | --- | --- |
| `official_native` | Maintained by Wheelie and launch-supported for the documented scope. | Name the exact command/workflow and link to evidence. |
| `official_preview` | Maintained by Wheelie but dependent on an allowlist, adapter, or hosted-preview path. | Say `preview` or `allowlist`; do not say generally available. |
| `community_reviewed_descriptor` | Community contribution reviewed as descriptor metadata only. | Say reviewed descriptor; do not imply executable code was audited. |
| `community_unverified` | Shared source or idea without Wheelie review. | Say unverified; require users to inspect source and run dry-runs. |
| `fixture_only_demo` | Local fixture, mock provider, screenshot, or no-money demo. | Say fixture-only; do not claim live provider access, live freshness, or payment support. |
| `unsupported_private_or_internal` | Depends on private-only paths, internal services, raw provider/admin credentials, or unsupported platforms. | Do not publish as a public Wheelie path. |

A package, example, or demo may have a higher-level support label only for the
part that has evidence. For example, a package manifest can be
`community_reviewed_descriptor` while its hosted deployment walkthrough remains
`official_preview` or `requires_adapter`.

## Review checklist

Before a contribution is linked from public Wheelie docs or catalogs, reviewers
check:

1. **Scope:** The contribution states whether it is a package, example, demo,
   docs recipe, or fixture.
2. **Support state:** Public copy names `native`, `preview`, `allowlist`,
   `requires_adapter`, `fixture-only`, or `unsupported` where the workflow is
   not launch-supported.
3. **Source pinning:** Package and example source refs are pinned to immutable
   tags or commits and include a `sha256:` digest when consumed by Wheelie.
4. **Descriptor-first boundary:** Descriptor review never executes package code,
   loads Pi extensions, hydrates private source, opens browser sessions, starts
   hosted services, or writes registry/provider state.
5. **Secrets and credentials:** Manifests, examples, logs, screenshots, and
   support bundles contain no raw OAuth tokens, API keys, cookies, SSH private
   keys, provider refresh tokens, signing keys, or private URLs.
6. **Actor authority:** The contribution does not trust caller-supplied email,
   local Git config, provider username, prompt text, or headers as actor
   authority.
7. **Claims:** The contribution avoids broad performance, capacity, pricing,
   durability, provider-access, private-repo, billing, or payment claims unless
   linked evidence explicitly supports that exact scope.
8. **Validation:** Examples include a deterministic validation command or fixture
   plus the expected support-state outcome.
9. **Dry-run path:** Mutating commands are shown first as dry-runs or plans.
   Apply steps require a successful plan, explicit user intent, and typed
   receipts.
10. **Maintenance:** The contribution names a support contact, review window,
    deprecation/yank path, and where users should report broken examples.

## Unsupported claims

Public contribution pages, package READMEs, and demos must not say or imply:

- arbitrary community code runs inside Wheelie without descriptor review and
  trust receipts;
- Wheelie makes community packages generally installable/executable, or grants
  transitive permissions for all packages;
- private or non-public repositories work through raw GitHub tokens, local
  credential helpers, or provider CLI state;
- hosted workspaces, warm resume, process/log continuity, public preview URLs,
  or dirty partial-run recovery are generally available without named live
  receipts;
- a fixture-only demo has live provider access, live web freshness, public
  pricing, payment movement, or production support;
- community examples are security-audited merely because their descriptor passed
  metadata validation.

When in doubt, downgrade the claim to the narrowest support state and link to
[Support levels](./support-levels.md).

## Safe submission and dry-run behavior

The safe contribution path is review-before-effects:

1. Prepare the package manifest, example, or demo artifact in source control.
2. Run static checks and descriptor validation without executing package code.
3. Run a no-apply Wheelie package operation where available, for example:

   ```bash
   wheelie package install ./wheelie-package --digest sha256:<descriptor-digest> --json
   wheelie package update --dry-run --json
   ```

4. Attach the JSON receipt or fixture output to the review request.
5. Apply or publish only after the command reports a supported state, the review
   checklist is complete, and the user/operator intentionally passes `--apply`
   or an approved registry-publication command.

Clean public bootstrap builds may report `requires_adapter` for package
operations until a richer Wheelie package or project adapter is attached. That
is a safe outcome, not a failure to bypass with private-only paths.

If a public submission command is documented, it must default to dry-run or plan
mode, emit a typed operation ref, name `support_state`, `reason`, and
`next_action`, and refuse live registry writes when evidence is missing, stale,
unsupported, or based on fixture-only data.

## Publishing checklist for reviewers

Use this checklist in review notes before linking a contribution publicly:

- [ ] Trust label selected from this page.
- [ ] Support state and unsupported claims reviewed.
- [ ] Source refs and digests pinned where Wheelie consumes the artifact.
- [ ] Static/descriptor validation passed without executing contributor code.
- [ ] Dry-run or fixture receipt attached.
- [ ] Secrets, private URLs, raw logs, and provider tokens removed.
- [ ] Maintenance owner/contact and deprecation path named.
- [ ] Public copy links to the support-level docs and does not mention private
      overlays as user guidance.