---
name: uru-library
description: Find, read, organize, link, share, version, and distribute work in the Uru Library. Use for Library paths, backlinks, permissions, comments, labels, or Collections.
---

# Uru Library

The Library is the durable workspace tree for files, folders, Context, Prompts,
Datasets, Agents, Gems, and other shipped work.

## Select the correct tool

- Use `library_query` for `ls`, `stat`, `read`, `search`, and `patch_preview`.
- Use `library_fs` for create, write, patch, copy, move, trash, restore, and
  favorite changes.
- Use `library_upload` for generic or binary files.
- Use `library_collab` for shares, permissions, ownership, comments, labels,
  and version restore.
- Use `sharing_query` to inspect shares, permissions, and versions.
- Use `collections_query` for Collection reads and analytics.
- Use `collections` for Collection changes and publication.
- Use `gem_query` and `gem_control_plane` inside a `.gem` project.
- Use Dataset V2 tools for Dataset content.

## Read before write

1. Search or list the relevant folder.
2. Read or stat the exact item.
3. Use the returned path, item id, resource slug, and resource type.
4. Make the smallest complete change.
5. Read the result when exact content or state matters.

Prefer a visible path such as `library/Clients/Acme/Brief.md`. Use `item_id`
only for an exact UI handoff or stale-path recovery.

Do not invent a slug from a display name. Copy the returned `resourceSlug`.

## Typed text resources

`library_fs` can create and change Context, Prompt, and Agent resources.

- Context and Prompt content is text.
- Agent content is a JSON object.
- Generic files use `library_upload`.
- Gem child files use Gem tools.

Use `patch_preview` before a complex patch. Use `write` for a full replacement.

## Links and backlinks

Uru stores relationships between Library items as directed links with an
origin. Common origins include:

- manual links;
- Agent attachments;
- Collection membership;
- derived backlinks;
- derived Gem SDK bindings;
- workspace-default and team links.

An id-pinned reference has this form:

```md
[Display name](/__wiki_link__/<item_id>)
```

It survives renames. Raw `[[Name]]` text resolves when Uru saves the source.
Uru derives backlinks from saved text. Change the source to change a backlink.

Do not treat every link the same:

- Agent-to-Context links enable automatic retrieval.
- Other Agent links create inventory.
- Collection links create membership.
- Backlinks show reference relationships.
- Gem SDK links come from a Gem build.

Do not delete a derived link directly.

## Sharing and versions

Inspect current access before you widen it.

Use `library_collab` for:

- user, team, or workspace shares;
- permission changes;
- share settings;
- ownership transfer;
- comments and comment resolution;
- labels;
- version restore.

Use `sharing_query` for permission, share, and version reads.

Moving to trash is recoverable. Permanent removal and trash-empty operations
are destructive. Use the current tool confirmation policy for those actions.

## Collections

A Collection is an ordered distribution package. It can group Library work and
publish it through DocSend-style links.

Use `collections` to:

- create or update a Collection;
- add, remove, or order base members;
- add a private viewer overlay;
- publish or unpublish;
- create, change, or revoke distribution links.

Use `collections_query` to inspect the Collection, publication, links, and
engagement analytics.

Collection membership does not share each child directly. A Collection grants
view-through access. Removing the grant or member removes that derived access.

Private overlay members are visible only to the viewer who added them. They do
not appear on the public Collection.

Published links can use access gates, expiry, view limits, and notifications.
Analytics can show Collection, member, and visitor engagement.

Do not place a Collection inside another Collection. It is not a supported
shape.

## Stop rules

- Do not use raw backing paths.
- Do not write Gem source through `library_fs`.
- Do not write Dataset rows through `library_fs`.
- Do not widen access because two items are linked.
- Do not replace content that you did not read.
- Stop on a conflict or stale path. Resolve the current item before retrying.