---
name: uru-library
description: Find, read, organize, link, share, version, and distribute work in the Uru Library. Use for Library paths, backlinks, sharing, what was shared with you, contacts, Distribution results, comments, labels, or Collections.
---

# Uru Library

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

## Select the correct tool

- Use `library_query` for `ls`, `stat`, `read`, `search`, and `patch_preview`.
  `search` also returns up to five items shared with you that match, from any
  workspace.
- 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 of every kind of item, Gems included, for
  what was shared with you (`received_place`, `received_copy`,
  `received_remove`), share settings, ownership, comments, labels, and
  version restore.
- Use `sharing_query` to read who has access, who opened a share, what was
  shared with you, what you shared, permissions, versions, and labels.
- Use `collections_query` for Collection reads and `collections` for
  Collection changes.
- Use `contacts_query` and `contacts` for your private contacts and
  companies.
- Use `distribution_query` for the results of what you shared by name, and
  `distribution` for follow-ups.
- Use `gem_query` and `gem_control_plane` inside a `.gem` project.
- Use Dataset 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, a card from `sharing_query op="received_list"`,
or stale-path recovery.

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

## Order and times

A listing puts folders first, then the most recently modified item.
`modifiedAt` is the last time a person, or an Agent or automation that works
for a person, changed the item's content, name, or description. A star, a
move, the trash, a share, a preview, or a background re-sync does not change
it. A shortcut shows the time of its target. Use `modifiedAt` to find recent
work. Do not read an edit from any other time.

## 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;
- 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.
- Backlinks show reference relationships.
- Gem SDK links come from a Gem build.

A Collection's items are not links. Change them with `collections`.

Do not delete a derived link directly.

## Sharing

Every kind of Library item shares the same way: a file, folder, Dataset,
Prompt, Context, automation, Agent, Collection, or Gem. Inspect current access
with `sharing_query op="item_shares"` before you widen it.

- Share with `library_collab op="share_create"`. `kind` is `viewer` (the
  default), `commenter` (a file, folder, or Dataset), or `editor`.
- Each person you name gets their own link and one email unless
  `notify=false`. The optional `message` goes in the email and in their Uru
  inbox. A person without an Uru account can create one with that exact
  address from the email. There is no accept step.
- `audience` sets general access, one level at a time: chosen workspaces of
  the item's organization, the whole organization, or anyone with the link.
  Anyone with the link is view only, behind a gate. The workspace and
  organization levels need a workspace in a real organization.
- The owner shares. An Editor also shares and changes general access while
  "Editors can share" is on (`set_share_settings` with `writers_can_share`).
  Folders and Collections follow the same rule.
- A folder or Collection share shares everything inside it, and the items
  added later. A Gem inside opens as a view-only Gem link and uses your
  connections or Datasets only after `pack_consents`.
- To change someone's role, call `share_create` with the new `kind`, then
  `share_remove_person` on the old share.
- You can name 1,000 people in one call and email 1,000 people a day. Over
  the limit the call is refused and nothing changes.
  `sharing_query op="send_allowance"` says how many emails are left today.
  `share_resend_email` sends one named person their email again.
- A workspace API key may only name Viewers and Commenters. General access,
  Editors, and consents need a sign-in or a thread token, not a workspace key.
- There is no share-as-copy. A Viewer makes a copy with the Library's own
  copy when the owner allows it (`copy_requires_writer_permission`).

A change that takes a live link from people who have it is refused with
`share_link_off_confirmation_required`. Tell the person you work for who will
lose the link and how many opened it (`details.people_opened`). Send the same
change with `audience_confirm_link_off=true` only after that person agrees.

An Editor share of an automation also shares, as Editor, each Library item
the automation uses that you may share. The write that gives Editor is
refused first with `share_used_items_confirmation_required`, and nothing
changes. Tell the person which items Editors get too (`details.items` with
`withheld_reason` null) and which they do not, with why. Send the same call
with `confirm_used_items` only after that person agrees.

Read [sharing](references/sharing.md) before the first share write. It has
every share op, the fields each kind takes, the credential rules, and the
refusals.

## Shared with you

- `sharing_query op="received_list"` lists everything shared with you, one
  card per item, from every workspace you are in. `received_get` shows every
  way you can open one item.
- `library_collab op="received_place"` puts a shortcut to a card in one of
  your workspaces. The item itself never moves: its workspace, folder,
  connections, and edit rights stay where they are.
- `library_collab op="received_copy"` makes your own copy of a prompt or
  context shared with you, at the root of your Personal workspace, when the
  card says `copy: "allowed"`. Each call makes another copy, unless you send
  it again with the same `idempotency_key`: then it answers the copy the
  first call made.
- `library_collab op="received_remove"` takes a card off your list and ends
  your access through the shares to you.
- `home_pins_manage op="pins_add"` with `kind="share"` and `target_id` set to
  the card's `itemId` pins it on Home in the call's workspace.

A card with `needsYou: true` (state `verify_email`) waits for the person to
prove an address in the app. A tool cannot read a mailbox, so tell the person.
A card in state `other_login` is held by another login of the same person:
they open it from that login.

## Contacts and Distribution

Contacts are private to one person and are the same list in every workspace.
Uru adds a contact when the person names someone on a share. No contacts op
sends email. Read [contacts](references/contacts.md) for the ops, the
sources, and companies.

Distribution reads the results of what the person shared by name: who opened
it, when, and for how long, by person, company, and Version, plus
follow-ups. Opens by the sender and their team are not counted. Read
[Distribution](references/distribution.md).

Contacts, opens, Distribution, and the received list belong to a person. A
workspace API key or a Gem token is refused with `personal_caller_required`.

## Collections

A Collection is a live pack: a visible Library item that holds items from any
folders of its workspace, in one order, shared as one.

- Create and change one with `collections`; read with `collections_query`.
- The owner and the Collection's Editors add, remove, reorder, rename, and
  describe it. Only the owner deletes it. The items stay in their folders.
- Add only items you can share, from the Collection's workspace. A folder or
  another Collection is refused.
- `items_add` sends no email, and everyone the Collection is shared with can
  open the added items at once.
- Share it with `library_collab op="share_create"` (`kind` `viewer` or
  `editor`). Move it with `library_fs op="mv"`. Its results are in
  `distribution_query`.

Read [Collections](references/collections.md) for the ops and examples.

## Versions and ownership

Use `library_collab` for `restore_version`, `transfer_ownership`, comments,
comment resolution, and labels. Use `sharing_query` for `list_permissions`,
`list_versions`, `get_version`, `diff_versions`, and `list_labels`.

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

## 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.
- Confirm a link-off only after the person agrees.
- Stop on a conflict or stale path. Resolve the current item before retrying.