# Add and verify a Plugin

Install the reviewed Player Rig Plugin in an existing Environment, render its
public React Three Fiber adapter, and submit a new immutable Environment
revision containing the exact installation.

## Result

At the end:

- the Environment manifest identifies the exact Plugin release and `r3f`
  adapter;
- `al-amr.lock.json` records the Registry release, package artifact, and
  SHA-512 integrity;
- `package.json` contains the selected package;
- a walkable player rig renders and moves through the reviewed public adapter;
- the updated Environment revision has passed publication checks and can be
  submitted for review.

## Prerequisites

- a completed and linked [Environment guide](/docs/start/environment)
- the same Registry configured for the CLI and running Environment
- a published `al-amr/player-rig` release in that Registry catalog
- npm dependencies already installed

Every copyable command below uses the complete pinned
`npx @al-amr/cli@0.1.0-alpha.7` invocation. Installing a managed Plugin still
depends on the exact release advertised by a promoted Platform Release Set; if
the Start page shows no install command, do not guess a version. Use the package
manager recorded by the Environment's `package.json` for dependencies.

Run all commands from the Environment directory. Do not create or edit
`al-amr.lock.json` by hand.

## 1. Inspect the immutable release

```sh
npx @al-amr/cli@0.1.0-alpha.7 inspect al-amr/player-rig --json
```

The result includes the public card, exact manifest, available versions,
installable artifacts, immutable release ID, integration guide URL, and
Environments already using the Plugin. Before installation verify:

- `runtimeClass` is `trusted_library`;
- the `r3f` adapter exists and lists the exports you plan to import;
- contract and SDK compatibility match the Environment;
- platform permissions are limited to what the Plugin needs;
- browser requirements, network access, data handling, and license are
  acceptable;
- the selected artifact has a Registry-validated integrity value.

The canonical page is
`https://developer.al-amr.com/catalog/plugins/al-amr/player-rig`. The version page
and its `integration.md` are immutable once published.

## 2. Add the selected adapter and install bytes

```sh
npx @al-amr/cli@0.1.0-alpha.7 add al-amr/player-rig@0.3.0-alpha.5 --adapter r3f --dry-run --json
npx @al-amr/cli@0.1.0-alpha.7 add al-amr/player-rig@0.3.0-alpha.5 --adapter r3f --yes --json
pnpm install
npx @al-amr/cli@0.1.0-alpha.7 validate --json
```

The dry run is the trust boundary. Review Publisher verification, release and
artifact identity, runtime class, declared permissions, browser/network/data
disclosures, adapter exports, integrity, and `filesToChange`. It performs no
write. The second command approves those exact reviewed inputs.

The CLI performs one atomic metadata update across:

- `al-amr.environment.json`, which records `pluginId`, `releaseVersion`, and
  `adapterId`;
- `al-amr.lock.json`, which adds `releaseId`, `artifactId`, package
  specification, and integrity;
- `package.json`, which adds the exact installable package.

`--yes` is required because frontend Plugin bytes execute as trusted library
code. It also permits an intentional replacement when this Plugin or dependency
is already locked to another version. It does not bypass Registry validation,
artifact integrity, compatibility, or publication review.

A successful command reports `Added al-amr/player-rig@...` and returns the
chosen version, adapter, Registry-reviewed package name, integrity, canonical
URL, and install command. Treat `data.packageName` as the import specifier and
run the exact package-manager command returned in `data.installCommand`. Do not
derive an import from a source-workspace package name. After installation,
local validation must still return process code `0`.

## 3. Render the Player Rig through the selected adapter

For this published first-party release, `data.packageName` is
`@al-amr-community/al-amr--player-rig`. Import only exports declared by the
reviewed `r3f` adapter and render them inside the shared R3F canvas:

```tsx
import { AlAmrProvider, AlAmrRuntimeGate } from "@al-amr/react";
import { createEnvironmentRuntimeClient } from "@al-amr/sdk";
import { EnvironmentCanvas } from "@al-amr/r3f/canvas";
import {
  PlayerRig,
  createFlatNavigationSurface,
  createPlayerController,
} from "@al-amr-community/al-amr--player-rig";
import { sdkConfig } from "./config.js";

// The controller and navigation surface live outside the canvas so a
// renderer retry or device-loss recovery never resets the player.
const controller = createPlayerController({ position: [0, 0, 6] });
const navigation = createFlatNavigationSurface(0);

// The platform this build talks to. The desktop client supplies `window.alamr`;
// `alamr dev` installs the loose build and returns the exact client link.
const runtimeClient = createEnvironmentRuntimeClient({ options: sdkConfig });

export function App() {
  return (
    <AlAmrProvider client={runtimeClient}>
      <AlAmrRuntimeGate direction="ltr">
        <EnvironmentCanvas controls={false}>
          <PlayerRig controller={controller} navigation={navigation} />
        </EnvironmentCanvas>
      </AlAmrRuntimeGate>
    </AlAmrProvider>
  );
}
```

The Environment still owns terrain, collision authority, and spawn policy: it
supplies the `NavigationSurface` the rig queries. Player Rig owns movement,
camera, avatar presentation, and its reviewed render adapter. Set
`controls={false}` so the rig's camera is the only one driving the view.
`AlAmrRuntimeGate` unmounts the world when this page loses the active Runtime
lease. The desktop Shell owns the one platform Widget; the Environment must not
mount another one.

## 4. Verify the local integration

```sh
npm run typecheck
npm run build
npx @al-amr/cli@0.1.0-alpha.7 inspect --json
npx @al-amr/cli@0.1.0-alpha.7 validate --json
npx @al-amr/cli@0.1.0-alpha.7 dev --json
```

The local inspect output should show the Player Rig installation with the selected
release and `r3f` adapter. Validation also checks that every
Environment installation has a matching lock entry.

Execute the `open` next action returned by `alamr dev`. In the desktop client,
confirm that the avatar renders and that WASD movement and camera drag respond
inside the Environment canvas.

## 5. Check and submit the updated Environment revision

```sh
npx @al-amr/cli@0.1.0-alpha.7 test --bundle dist --json --visibility unlisted --channel preview
npx @al-amr/cli@0.1.0-alpha.7 publish --json --yes
npx @al-amr/cli@0.1.0-alpha.7 status --json
```

`test` inventories, packs, uploads, binds, and checks the exact `dist` bytes,
including the new manifest digest, exact Plugin installation, and SDK version.
`publish` sends that checked revision for review. The Registry remains the
source of truth for whether and when the revision becomes published.

## Common failures

- **`Plugin not found` or network exit code `4`** — confirm that the CLI uses
  the Registry whose catalog contains `al-amr/player-rig`.
- **Adapter `r3f` is not provided** — inspect the release and choose one of
  the adapter IDs it actually declares.
- **The release is yanked** — choose a currently published version. Existing
  integrity-locked installations remain reproducible, but new installation of
  a yanked version is rejected.
- **Dependency conflict** — inspect the existing `package.json` entry. Use
  `--yes` only when replacing it is intentional.
- **Missing or stale lock entry** — rerun `alamr add` for the intended version;
  do not repair the lock manually.
- **TypeScript cannot find the export** — compare the selected adapter's
  `exportPath` and named exports with its versioned `types.d.ts` and integration
  guide.
- **Nothing renders or the player falls** — keep the component inside
  `EnvironmentCanvas`, return a finite ground point from the navigation
  surface, and disable the canvas's own controls so they do not fight the
  rig camera.

## Security checklist

- A v0.x frontend Plugin is trusted library code in the Environment's
  JavaScript realm; permissions are not a sandbox.
- Inspect the exact version, disclosures, source, and integrity before adding
  it.
- Import only exports declared by the selected adapter and reviewed type
  declaration.
- Never pass a management token or browser secret to Plugin code.
- Keep `al-amr.lock.json` under source control when appropriate for the
  application, but do not edit its integrity or identity fields manually.

To create your own reusable capability, continue with
[Build a Plugin](/docs/start/plugin). For the exact file boundary read
[Manifest reference](/reference/manifests).