Use the Sidecar Library

Use Library to decide which capabilities one application will contain. This guide covers selection, configuration, dependencies and user-authored package import, then follows the selection into a new build.

Before you begin

Open the intended project and application component in Build. Compile or select its release so Library has an application identity. You can browse without one, but adding a capability needs an app to receive it.

Decide the target platform and the result you need. Library contains built-in and imported packages, including planned entries. A catalogue description is not proof of a working runtime on your selected device; the component's declared state and platform support matter.

Choose capabilities, not a global bundle

Open Library, or Choose sidecars from Build. Check the current app identity before editing. The selection belongs to that app, not every project on the computer. Import globally means a package becomes available across projects, not that it is automatically enabled in all of them.

Choose List for compact browsing, Cards for descriptions or Details for columns. Search, Category, Platform and All / Selected / Needs setup filters operate on the same catalogue. Sort order, page size and layout are browsing preferences; they do not change the package selection.

Start with a task rather than a large preset. Guide adds authored help, Local AI supplies local inference, Test Runner provides bounded app-surface testing, and Service Inspector observes declared runtime services. These jobs are distinct. See the component directory and composition guide for each capability's API and prerequisites.

Select and configure a first capability

1. Search for the component and check its implementation state, platforms, permissions and overview.
2. Choose Add to app. In Build's picker the equivalent action can read Add to build.
3. Choose Configure and inspect the component's sections and field descriptions. Change only what this app needs.
4. Open Selected and check the resulting configuration and any Needs dependency notice.
5. Return to Build, inspect the effective selection, package for the intended platform and install that updated package.

For example, adding Guide can provide authored help without Local AI. Add Local AI only when you also need supported local inference and have an appropriate engine/model. Do not assume every component listed near another is a mandatory dependency.

Selection and configuration

Library configuration controls save to the app's selection as you change them; Done closes the configuration view. This is different from Agent's embedded forms, where Save is explicit. Neither action changes an already installed binary by itself.

Click the component name for technical details. More opens its Overview or Studio, or removes it from the current app. Build configuration is distinct from a component's own in-app configuration UI: the latter affects the running provider only where the component explicitly supports it.

The Selected panel has its own search, independent of catalogue search. Selection tools & JSON includes Copy JSON, Export JSON and Clear selection. The exported capp.sidecar-library.selection.v1 describes selected IDs, versions, configuration and app identity; it is not a copy of every package, an installed provider or a native permission grant.

Review exported configuration before sharing it because fields may contain private endpoints or other app-specific values. This panel exposes selection export, not a promise of a universal one-click selection import. User package import and Studio JSON import are separate operations.

Dependencies, platforms and readiness

Read the component's declared dependencies and each Needs notice. Add and configure required peers rather than assuming selecting one automatically selects them all. Some reusable components support an explicitly supplied external provider instead of a peer package; use that component's reference rather than guessing a compatible object shape.

A selected package missing required target assets should block packaging, not silently disappear. Planned entries do not become implemented merely because they have documentation. Selecting Local AI does not mean a model is loaded; selecting an RPC capability does not establish network connectivity; selecting a wallet-related capability does not approve a transaction.

For Solana work, distinguish Arena's deterministic simulation from a configured live provider and from native wallet handoff. Use Solana providers for those boundaries rather than treating the whole suite as either entirely simulated or entirely production-ready.

Import a user-authored Sidecar

Expand Import or create a Sidecar. Download scaffold supplies the public starter package; the authoring guide explains its manifest, surface and API boundaries.

1. Extract the package ZIP into a folder and inspect its manifest and source. The importer selects a package folder, not the unopened ZIP.
2. Choose Import globally for availability across projects, or Import for this project for a project-only package. A project must be active for project import.
3. Select the folder, inspect the validation result and use Refresh user sidecars when you need to rescan available packages.
4. Find the imported component in Library, review it, then add and configure it for the intended app. Importing alone does not select it for every build.

Project packages take precedence over a global package with the same ID. Built-in cApp IDs are reserved. Use a stable, unique ID for your own component and publish a new version when its behaviour changes.

Import validation is not a security audit of another person's JavaScript. Inspect provenance and code before enabling it. A package cannot acquire native authority simply by declaring a bridge name in its manifest. Do not import unknown code merely to remove a validation warning.

Configure without rewriting history

Library settings, project Guide selection and Studio configuration contribute to the effective package. Studio combines canonical design with explicit global defaults and explicit project changes. A project override can explain why changing a global default did not change that project.

Replacing an imported package folder preserves its separately stored Studio history. That does not certify that every older customisation still matches the new package's mapped elements; inspect and test it after replacement.

Use Studio for visual/function customisation, Checkpoint for a draft and Publish version for an immutable authored version. Do not reinterpret an older compiler release as if it had always contained today's source or configuration. A distributed application changes only through the relevant compile/package/update path.

Remove and Clear selection affect the next package's choices. They do not uninstall the already running component, delete its application data or erase the package from every scope. Inspect dependent capabilities before removing a peer they still need.

Troubleshooting

What success looks like

The intended app has a minimal, compatible selection with its dependencies/configuration understood, and an updated installed package confirms the required runtime capabilities. Continue with Studio, Sidecar authoring or application tests.