---
name: uru-gems
description: Build, inspect, revise, test, version, release, publish, and operate Uru Gems. Use for interactive work, hosted apps, sites, workers, server functions, or shareable Gem links.
---

# Uru Gems

A Gem is shipped work. It can be a small interactive view, a static
experience, or a hosted application with server code.

Use file-specific Skills for a normal deck, document, sheet, image, or PDF.
Use a Gem when the output needs an interactive or hosted runtime.

## Core model

Keep these states separate:

- **Current** is the editable source tree.
- An **Edit** records one coherent source change.
- A **Build** compiles and checks one source revision.
- A **Version** freezes a selected ready state.
- A hosted **Release** deploys one Version.
- A **Link** selects one explicit Version and access policy.

Changing Current does not change a published Link. Saving a Version does not
publish it. Move a Link only after checks pass.

## Select the correct tool

Use `gem_query` for reads:

- inspect;
- file tree and file reads;
- patch preview;
- status and diff;
- validate;
- Builds, logs, Versions, Releases, Links, runs, domains, and analytics.

Use `gem_control_plane` for changes:

- init;
- write, batch write, sync, patch, move, copy, and remove;
- build;
- save or restore a Version;
- create or retry a Release;
- create or change a Link;
- bindings, secrets, domains, verification, and run control.

Use `library_fs` only to organize or trash the Gem root. Do not use it for Gem
child files.

## Build workflow

1. Search the Library before you create a Gem.
2. Inspect an existing Gem before a change.
3. Create a new Gem with `gem_control_plane` and `op="init"`.
4. Write the root `uru.json` and entrypoint in one batch.
5. Add the smallest complete source tree.
6. Validate with `gem_query` and `op="validate"`.
7. Build and inspect the result.
8. Fix diagnostics until the intended behavior works.
9. Run a meaningful browser or output check.
10. Save a Version with `op="version_save"`.
11. Create a Release with `op="release_create"` when the runtime needs one.
12. Create a Link with `op="link_create"`, or move it with
    `op="link_set_version"`.
13. Verify the published result.

Do not stop after file upload. Leave the Gem in a clear, inspectable state.

`gem_control_plane` with `op="iterate"` is an optional compound operation. It
can apply one bounded non-destructive change, build it, and return preview
evidence. It is not the only authoring path. Use direct file operations for
large changes, new applications, or work that needs several coherent edits.

Read [the operation reference](references/operations.md) for current operation
names and required fields.

## Source contract

Every Gem has one root `uru.json`.

```json
{
  "schema": "uru.gem.v2",
  "schemaVersion": 2,
  "name": "Account Review",
  "description": "Review account health and next steps.",
  "framework": "tanstack_start",
  "entry": "src/start.ts",
  "servingMode": "top_level_app",
  "runtimeIntent": {
    "server": "required"
  },
  "bindings": {
    "datasets": [],
    "tools": {},
    "ai_models": [],
    "personas": [],
    "secrets": [],
    "external_connections": []
  },
  "capabilities": {
    "queries": [],
    "actions": {},
    "jobs": {},
    "server_functions": []
  },
  "dataset_mutation_allowed": false,
  "storage": false
}
```

The source declares intent. Uru compiles runtime authority and selects
infrastructure. Do not author deployment ids, provider choices, compiled
capabilities, grants, runtime manifests, or credentials.

Read [the `uru.json` reference](references/uru-json.md) when you need exact
framework, serving, binding, or capability fields.

## Full-stack applications

Choose the smallest runtime that meets the need:

- Use a single-file or static framework for simple views.
- Use React or Vite React for client applications.
- Use TanStack Start for a full hosted application.
- Use `server_function` for an API or worker-style server entry.
- Declare server, WebSocket, native dependency, background process, or
  persistent file-system intent only when the application requires it.

The build compiler maps source intent to Uru runtime resources. Do not write
infrastructure-specific deployment files unless the selected framework
requires a normal build file.

Keep browser code free of credentials. Put privileged work behind server
functions, actions, jobs, or approved bindings.

## Data, tools, and credentials

- Read `uru-datasets` for Dataset V2 and the Dataset SDK.
- Declare each Dataset in `uru.json`.
- Keep Dataset writes disabled unless the Gem must write.
- Declare tool needs as logical roles and operations.
- Let Uru resolve the connected provider after the tool call.
- Do not ask the user for an Uru key or hosting-provider key.
- Never write secret values into source.
- Declare a custom secret only when the application needs a server secret that
  Uru cannot supply through a resource connection.

After a build, inspect unresolved bindings. Use the returned continuation or
binding operations. Do not invent connection ids or provider operations.

## Testing and operation

Check behavior, not only build success.

- Test one main user path.
- Test empty, loading, error, and permission states.
- Use server-side Dataset pagination and aggregates.
- Inspect build and runtime logs after a failure.
- Return durable run or Release ids for long work.
- Keep published quota, retry, cached, queued, running, and failed states
  visible.

For a rollback, move the Link to a previously served Version when the tool
permits it. Do not rebuild old source to simulate a rollback.

## Publishing

Use one explicit Link as the traffic pointer.

Before a forward publish:

1. inspect the Version;
2. inspect or create its Release;
3. run required checks;
4. inspect current Link access;
5. move the Link to the exact Version;
6. verify the public result.

Use Uru Link access controls for gates, expiry, notifications, and revocation.
Do not publish by changing a guessed URL or provider route.

Read [publishing](references/publishing.md) for the stable release and rollback
rules.

## Stop rules

- Do not use retired Gem authoring tools or metadata blocks.
- Do not write internal runtime fields.
- Do not put credentials in source or logs.
- Do not use old Dataset tools or SDK calls.
- Do not publish a failed or unverified Version.
- Do not hide a failed Build, Release, run, or Link change.
- Stop after a conflict. Inspect Current, the target Version, and the Link
  before retrying.