# The organization folder and suggestions

## Summary

Every organization has one organization folder (the API's library). It is a
shared place for files that every workspace of the organization uses: logos,
brand guides, fonts, anything that belongs to the whole organization and not
to one brand or client. Every member of the organization reads the
organization folder. Only the organization's owners and admins change it.

A suggestion is a batch of proposed changes to files - tags to add or remove,
moves, new names and alt texts - that somebody prepares and a person reviews.
Nothing changes until a person applies it in the app. Suggestions exist in
every workspace and in the organization folder. They are how an agent tidies
files without changing anything on its own.

In the API and in MCP a suggestion is called a library proposal. The name is
the same for workspaces and for the organization folder: a proposal in a
workspace is also a "library proposal".

This page covers what the organization folder is and how it differs from a
workspace, and suggestions in full: what one can hold, who makes, applies
and rejects it, its states, its expiry and what applying does.

## Who can do what

"In a workspace" means the effective role in that workspace. "In the
organization folder" means the role in the organization. See
[Roles and permissions](../reference/permissions.md).

| Action | In a workspace | In the organization folder | Session | Credential (scope) |
| --- | --- | --- | --- | --- |
| Open it and read its files, folders and tags | Everyone who can open the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Download files | Everyone who can open the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Star a file or folder as a favorite | Everyone who can open the workspace | Every member of the organization | Yes | Yes (`files:read`), REST only |
| List the duplicate groups | Everyone who can open the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Hide a duplicate warning for yourself, or show it again | Everyone who can open the workspace | Every member of the organization | Yes | Yes (`files:read`), REST only |
| Upload, rename, describe, tag, move, trash and restore files; create, rename, move, trash and restore folders | Everyone who can open the workspace | Organization owner or admin | Yes | Yes (`files:write`) |
| Rename and delete tags | Owner or admin | Organization owner or admin | Yes | Yes (`files:write`) |
| Manage the statuses, custom fields and their choices | Owner or admin | Organization owner or admin | Yes | No |
| Set a status on files | Owner or admin | Organization owner or admin | Yes | Yes (`files:approve`) |
| Change general access of a file or folder | Owner or admin | Organization owner or admin | Yes | No |
| Delete a trashed file or folder for good, empty the trash | Owner or admin | Organization owner or admin | Yes | No |
| List and read suggestions | Everyone who can open the workspace | Every member of the organization | Yes | Yes (`files:read`) |
| Make a suggestion | Everyone who can open the workspace | Organization owner or admin | Yes | Yes (`files:write`) |
| Reject items of a suggestion | Everyone who can open the workspace | Organization owner or admin | Yes | Yes (`files:write`) |
| Apply items of a suggestion | Everyone who can open the workspace | Organization owner or admin | Yes | No |
| Apply a move that makes files public | Owner or admin | Organization owner or admin | Yes | No |

- A credential acts for one member. Its scope is not enough by itself: the
  member must also hold the role the row asks for. A plain member's key with
  `files:write` cannot change the organization folder.
- A credential that tries to apply a suggestion gets `403 FORBIDDEN` with
  `details.reason` `HUMAN_APPROVAL_REQUIRED`.
- Someone who is not a member of the organization gets `404 NOT_FOUND` for
  the organization folder and everything in it, the same answer as for an
  organization that does not exist.

## How it works

### The organization folder

- Every organization has exactly one organization folder.
- The organization folder belongs to the organization, not to a workspace. Every
  workspace of the organization shows the same organization folder.
- The organization folder holds files with their versions, folders, tags, a
  trash, uploads and suggestions of its own, just like a workspace.
- Every member of the organization reads the organization folder: lists and
  searches its files, opens them, reads their versions and downloads them.
  This needs no workspace membership.
- Only organization owners and admins change the organization folder. They
  upload, rename, describe, tag, move, trash and restore its files, manage
  its folders and rename or delete its tags.
- A plain member who tries to change the organization folder gets `403
  FORBIDDEN`. Nothing changes.
- A member's role in a workspace gives nothing in the organization folder.
  Someone who is owner of a workspace but a plain member of the organization
  still only reads the organization folder.
- There is no operation that deletes the organization folder. It exists as
  long as the organization does. See [Deleting and
  restoring](../organizations/delete-and-restore.md).

### How the organization folder differs from a workspace

| | A workspace | The organization folder |
| --- | --- | --- |
| How many | Any number per organization, at least one | One per organization |
| Who reads | Organization owners and admins, and the workspace's members | Every member of the organization |
| Who changes files and folders, and tags files | Everyone who can open it | Organization owners and admins |
| Who manages statuses, fields and tags, sets statuses, changes general access and deletes for good | Its owners and admins | Organization owners and admins |
| Where its statuses, fields and tags are managed | Its pages "Statuses", "Custom fields" and "Tags" under "Files & Assets", in its own settings navigation under "File spaces" | The same three pages of "Organization folder" under "File spaces" in the settings navigation |
| The role that counts | The effective role in the workspace | The role in the organization |
| REST path | `/v1/workspaces/{workspaceID}/...` | `/v1/organizations/{organizationID}/library/...` |
| MCP tools | `workspace_...`, with `workspaceID` | `library_...`, with `organizationID` |
| What a credential reaches | Only the workspaces it lists | Always the organization folder of its own organization |
| Badge on an item that is not public | "Restricted" | "Every workspace" |
| Can be deleted | Yes, and restored for 30 days | No |

Everything else works the same way in both. The operations have the same
inputs and the same answers. The pages [Uploading](uploading.md),
[Folders, moving and finding](organizing.md),
[Versions and history](versions.md), [Trash and restore](trash.md) and
[Downloading](downloading.md) apply to the organization folder as they do to a
workspace.

### What the organization folder shares with workspaces, and what it keeps apart

- **Statuses and fields are separate.** The organization folder and each
  workspace have their own statuses and custom fields. An organization
  folder file carries only the organization folder's status and field
  values; a status, field or choice of a workspace is refused there with
  `422 VALIDATION_FAILED`, and the other way round. See
  [Statuses](statuses.md) and [Fields and
  tags](fields-and-tags.md#custom-fields).
- **Folders are separate.** The organization folder has its own folder tree.
  A folder of the organization folder is not listed in any workspace, and a
  workspace folder is not listed in the organization folder.
- **Tags are separate.** A tag belongs to the organization folder or to one
  workspace. The organization folder's tags are not offered in a workspace.
  See [Fields and tags](fields-and-tags.md#tags).
- **Files are separate.** An organization folder file cannot be read through
  a workspace path, and a workspace file cannot be read through the library
  path. Both answer `404 NOT_FOUND`.
- **Files do not move between the two.** A file cannot be moved from a
  workspace into the organization folder, from the organization folder into a
  workspace or from one workspace into another. Naming a folder of another
  place as the destination answers `422 VALIDATION_FAILED`.
- **The trash is separate.** The organization folder has its own trash. Only
  organization owners and admins trash and restore organization folder
  files, and only they delete them for good or empty the organization
  folder's trash, in a browser. The rest is as described in [Trash and
  restore](trash.md).
- **Favorites are separate and private.** Each person has their own favorites
  in the organization folder and in each workspace. A member who only reads
  the organization folder can still star its files and folders.
- **Suggestions are separate.** A suggestion belongs to the organization
  folder or to one workspace and names only files of that place.
- **Duplicates are found across both.** A file's details name other live
  files with the same content in the same place, in the organization folder
  and in the other workspaces you can open. See [Duplicate
  groups](#duplicate-groups).
- **The audit trail records organization folder changes for the
  organization**, without a workspace. See [Audit
  trail](../reference/audit-trail.md).

### Public sharing of organization folder files

- An organization folder file or folder is "Restricted" or public, with the
  same rule as in a workspace: a file is public only while its status allows
  public use, it is live, and it or a folder above it is shared. See
  [Sharing and public links](sharing.md#the-strict-rule).
- An organization folder item that is not public can be opened by every
  member of the organization. The card "Folder details" shows the badge
  "Every workspace" for it where a workspace folder reads "Restricted", and
  an organization folder file's "Sharing" section says "Only people in the
  organization can open it."
- Organization owners and admins change general access of organization
  folder files and folders, in a browser. No credential can.
- Organization owners and admins set statuses on organization folder files,
  in a browser or through a credential with `files:approve`. See
  [Statuses](statuses.md#setting-a-status-on-files).

### Suggestions

- A suggestion is a list of proposed changes to files, with a one-line
  summary of what it is about.
- A suggestion belongs to one place: one workspace, or the organization
  folder. Every file it names is in that place.
- Making a suggestion changes no file. Each proposed change waits as an item
  with the state `pending`.
- A person reviews the items in the app and applies the ones they choose.
  They can also change an item's value before applying it, or reject items.
- Applying is done by a person in a browser. No API key and no connected app
  can apply a suggestion, whatever its scopes.
- A suggestion cannot change a status, general access, a description, a
  caption, a custom field, a version or anything outside its place. It cannot
  trash, restore or delete a file. See
  [What a suggestion can hold](#what-a-suggestion-can-hold).
- The app has no form for making a suggestion. Suggestions are made through
  the REST API or MCP, typically by an agent with a `files:write` key.
- A suggestion stays open for 14 days. Then it expires and nothing more of
  it can be applied.
- A suggestion cannot be edited or deleted. To withdraw one, reject its
  pending items. To change one, reject it and make a new one.

### What a suggestion can hold

A suggestion holds 1 to 500 items. Each item names one file, one action and
the action's payload.

| Action | Payload | What applying it does |
| --- | --- | --- |
| `add_tag` | `{"tag": "name"}` | Adds the tag to the file. The tag is created in that place if it does not exist yet. |
| `remove_tag` | `{"tag": "name"}` | Takes the tag off the file. The tag itself stays. |
| `move` | `{"folderPath": ["Brand", "Logos"]}` | Moves the file into that folder, named from the top level down. `[]` is the top level. Folders that do not exist are created. |
| `rename` | `{"name": "new name"}` | Gives the file that name. |
| `set_alt_text` | `{"altText": "text"}` | Sets the alt text. `null` or blank text clears it. |

- A payload must fit its action exactly. A missing key, an extra key or a
  value of the wrong kind answers `422 VALIDATION_FAILED` on `payload`.
- Payloads are stored in their normalized form. A tag is trimmed, its inner
  spaces are collapsed and it is put in lower case, so "Logo" is stored as
  "logo". Names and alt text are trimmed. Blank alt text is stored as `null`.
- A tag is 1 to 50 characters once normalized and holds no comma. See
  [Fields and tags](fields-and-tags.md#tags).
- A `folderPath` names at most 16 folders. Each name is 1 to 200 characters
  and has no `/`.
- A file name is 1 to 200 characters and has no `/` or `\`.
- Alt text is at most 1,000 characters. See
  [Fields and tags](fields-and-tags.md#built-in-details).
- No value may contain a control character such as a tab or a line break.
- An item can carry a `rationale`: why the change is proposed, in 1 to 2,000
  characters on one line. The app shows it under the item. Leave it out or
  send `null` when there is none; a blank string is refused.
- A suggestion can hold several items for the same file, also several of the
  same action.
- Items keep the order they were sent in. That is the order they are shown
  and applied in.

### Making a suggestion

- In a workspace, everyone who can open the workspace makes suggestions. In
  the organization folder, organization owners and admins do.
- A credential needs `files:write`, and its member needs that same role.
- A suggestion needs a `summary` of 1 to 500 characters on one line, and 1
  to 500 `items`.
- Every item must name a live file of the same workspace or organization
  folder. A file in the trash, a file of another place and an unknown ID are
  all refused the same way: `422 VALIDATION_FAILED` on `items`. One such
  item refuses the whole suggestion.
- Each item records the file's `lockVersion` it is based on, as
  `baseLockVersion`. When the request leaves it out, the file's current
  `lockVersion` is used.
- `baseLockVersion` must be at least 1. It is not compared with the file's
  current `lockVersion` when the suggestion is made. A value that does not
  match shows only when the item is applied: the item then ends `stale`.
- Several items for one file that leave `baseLockVersion` out all get the
  same value. They still all apply, one after the other. See
  [Applying](#applying).
- The answer is `201` with the suggestion and its items. The suggestion is
  `open`, every item is `pending`, and `expiresAt` is 14 days after
  `createdAt`.
- A request can carry a `requestID` so that a retry does not make a second
  suggestion. Over REST it is optional. Over MCP it is required. See
  [Safe retries](../agents/rest-api.md#safe-retries-with-requestid).
- Nobody is notified by email when a suggestion is made. It shows in the app
  at once.

### States

A suggestion is in one of three states:

| State | In the app | Meaning |
| --- | --- | --- |
| `open` | "Open" | It has not expired, and not every item is decided. Items can be applied and rejected. |
| `closed` | "Closed" | Every item was decided before the suggestion expired. |
| `expired` | "Expired" | 14 days passed while at least one item was still pending. |

An item is in one of four states:

| State | In the app | Meaning |
| --- | --- | --- |
| `pending` | "Pending" | Not decided yet. |
| `applied` | "Applied" | A person applied it. The file was changed. |
| `rejected` | "Rejected" | Somebody rejected it. The file was not changed. |
| `stale` | "Changed since suggested", or "Expired" | It could not be applied because its file changed ("Changed since suggested"), or the suggestion expired before anyone decided it ("Expired"). The file was not changed. |

- A suggestion closes by itself the moment its last pending item is applied,
  rejected or found stale. Nobody closes a suggestion by hand.
- It also closes the moment its last pending item disappears because its
  file was deleted for good. Nothing is left to decide then.
- `closedAt` is the time that happened. It is `null` while items are
  pending.
- A closed suggestion stays `closed` for good. It does not turn `expired`
  after 14 days.
- `allowedActions` lists what the caller who reads the suggestion may do to
  it now. It is `[]` once the suggestion is closed or expired.
- While it is open, a person in the browser who may decide it sees
  `["apply", "reject"]`. A credential with `files:write` acting for such a
  person sees `["reject"]`, because applying needs a browser.
- A credential without `files:write`, and a member reading an organization
  folder suggestion, see `[]`.
- A decided item never changes again. Applying or rejecting an item that is
  not pending answers `409 CONFLICT` with reason `ITEM_DECIDED`.
- `decidedAt` and `decidedBy` say when an item was decided and by whom. Both
  are `null` while it is pending.

### Expiry

- A suggestion expires 14 days after it was made, at `expiresAt`, if any of
  its items is still pending then.
- From that moment it reads `expired`, and applying or rejecting answers
  `409 CONFLICT` with reason `CLOSED`.
- Within about an hour after that, its pending items are marked `stale`.
  They get a `decidedAt` but no `decidedBy`, since no person decided them.
  `closedAt` is set at the same time. The suggestion keeps reading `expired`.
- Until that happens, an expired suggestion can still show items as
  `pending`. They can no longer be decided.
- The app calls both kinds "Expired": a pending item of an expired
  suggestion, and a stale item nobody decided.
- Items that were applied or rejected before the expiry keep their state.
  Their changes stay.
- The 14 days cannot be extended. Make a new suggestion for what is left.

### Applying

Applying is the step that changes files.

- Only a person signed in with a browser applies. In a workspace that is
  everyone who can open it. In the organization folder it is the
  organization's owners and admins.
- The person chooses which pending items to apply: 1 to 500 of them, each
  named once. Items that are not chosen stay pending and can be decided
  later.
- The person can change the value of an item before applying it. The changed
  payload must fit the item's action, like a new one. What was applied is
  then kept on the item as `appliedPayload`, next to the original `payload`.
  `appliedPayload` is `null` when the item was applied as suggested.
- Chosen items are applied in the suggestion's order, whatever order the
  request names them in.
- Before an item is applied, its file is checked. The file must be live in
  that place, and its `lockVersion` must be the one the item expects.
  Otherwise the item becomes `stale` and the file is left alone. See
  [Changed since suggested](#changed-since-suggested).
- An item expects its `baseLockVersion`, or, when earlier items of the same
  suggestion were applied to the same file, the `lockVersion` the last of
  them left. This is why two items for one file both apply, in one go or one
  after the other.
- Each applied item raises the file's `lockVersion` by one. The item records
  the new value as `resultLockVersion`.
- An applied item counts as a change by the person who applied it. The file
  reads as last changed by them, and each applied item is recorded in the
  [audit trail](../reference/audit-trail.md#library-proposals) as a file
  change that names the suggestion.
- The answer is `200` with `applied` (how many items were applied), `stale`
  (how many were found stale) and the suggestion as it is now.
- The suggestion closes when no item is pending any more.

What each action does when it is applied:

- **`add_tag`** adds the tag. If the file already has it, the tags stay as
  they are and the item still counts as applied.
- **`remove_tag`** takes the tag off. If the file does not have it, nothing
  is removed and the item still counts as applied.
- **`move`** finds the destination folder by its names, from the top level
  down, ignoring case: "brand" finds the folder "Brand". A folder on the
  path that does not exist is created, with the name as the suggestion spells
  it, by the person applying. Folders in the trash do not count: a new folder
  of that name is created. Two items that move files to the same new folder
  create it once.
- **`rename`** sets the name. The file's public link, if it has one, keeps
  working: the name in a link is only decoration.
- **`set_alt_text`** sets the alt text, or clears it when the value is
  `null` or blank.

When a chosen item is refused, the whole request changes nothing. No item of
it is applied, none is marked stale, and every chosen item stays pending.
This happens when:

- a changed payload does not fit its action or breaks a naming rule
  (`422 VALIDATION_FAILED`),
- adding the tag would give the file more than 50 tags
  (`422 VALIDATION_FAILED` on `tags`),
- a move would make files public and the person applying is not an owner or
  admin (`403 FORBIDDEN` with reason `MAKES_FILES_PUBLIC`),
- a chosen item was already decided (`409 CONFLICT`, reason `ITEM_DECIDED`),
  or an ID is not an item of this suggestion (`422 VALIDATION_FAILED` on
  `items`).

Leave the refused item out, or reject it, and apply the rest.

What applying never does:

- It never changes a file's status or its general access setting.
- It never changes a member's role or anybody's access to a workspace.
- It never touches the file's content or versions.
- It never changes a file that is not named by a chosen item.

### Moves that change access

A move can change who can open a file, because a file in a shared folder is
public while its status allows public use. See
[Public folders](sharing.md#public-folders).

- A plain move asks for a confirmation when it would start or stop public
  links. Applying a suggestion is that confirmation: the person applying
  sees each move and its destination, and the move goes ahead without a
  second question.
- A move that only stops public links - the file leaves a shared folder -
  is applied by everyone who may apply the suggestion.
- A move that makes files public is applied only by an owner or admin. When
  a plain member of a workspace applies such an item, the whole request is
  refused with `403 FORBIDDEN`, reason `MAKES_FILES_PUBLIC`, and
  `details.becomePublic`, the number of files the selected moves together
  would make public. Nothing is applied.
- The item stays pending. An owner or admin can apply it, or the member can
  reject it and apply the rest.
- In the organization folder this refusal does not occur, since only owners
  and admins apply there.
- The general rule, with every case, is in
  [Moves and restores that change access](sharing.md#moves-and-restores-that-change-access).

### Rejecting

- Rejecting marks pending items `rejected`. Their files do not change.
- In a workspace, everyone who can open it rejects. In the organization folder,
  organization owners and admins do.
- A credential with `files:write` can reject, for a member with that role.
  This is how an agent withdraws its own suggestion.
- A request names the items to reject in `itemIDs`: 1 to 500 pending items,
  each once. Without `itemIDs`, every pending item is rejected.
- Rejecting the last pending item closes the suggestion.
- A rejected item cannot be applied later. Suggest the change again in a new
  suggestion.
- Rejecting a suggestion that is closed or expired answers `409 CONFLICT`
  with reason `CLOSED`. Naming an item that is already decided answers
  `ITEM_DECIDED`, and nothing is rejected.
- Anyone who may reject can reject any suggestion of that place, not only
  their own.

### Changed since suggested

"Changed since suggested" is what the app calls an item in the state
`stale`. A stale item changed nothing and never will.

An item becomes stale when it is applied and:

- its file was changed after the suggestion was made: renamed, moved,
  tagged, described, given a field value, trashed and restored, or changed
  in any other way that raises its `lockVersion`,
- a tag the file carries was renamed or deleted, or a custom field or
  choice the file had a value for was deleted, since those raise its
  `lockVersion` too,
- its file is in the trash,
- the item was sent with a `baseLockVersion` that does not match the file.

An item also becomes stale when the suggestion expires while it is pending.

- A new version of the file does not raise its `lockVersion`. Replacing a
  file's content alone does not make items stale.
- A stale item found while applying records the person who applied as
  `decidedBy`. One made stale by expiry has no `decidedBy`.
- When one item of a file is stale, later items of the same suggestion for
  that file are stale too when they are applied, since the file is no longer
  what they expect.
- The way forward is a new suggestion based on the file as it is now.

### Duplicate groups

A duplicate group is a set of live files whose current versions have the
same bytes. The organization folder and each workspace can list their groups.

- Files are compared by their bytes, never by their names. Only the current
  version of a file counts.
- A place lists a group when at least one copy is in that place and the
  reader can open at least two copies in all.
- The copies can be anywhere the reader can open: the same workspace or
  organization folder, the organization folder, and the reader's other
  workspaces. So a file with one copy in a workspace and one in the
  organization folder is a group in both.
- A copy in a workspace the reader cannot open is not named and is not
  counted. Two people can see different copies of the same group, or one of
  them can see no group at all.
- A credential sees only the workspaces it lists, and the organization folder.
- Copies in another organization are never compared.
- Files in the trash are not copies. Trashing a copy takes it out of its
  group, and a group left with one copy is no longer a group. Restoring the
  file brings it back.
- A group has `digest` (the SHA-256 of the shared bytes, as `sha256:` and
  64 hex digits), `fileCount` (the copies the reader can open), `hidden` and
  `files`.
- `files` names up to 20 copies: the copies of this place first, then the
  organization folder's, then other workspaces'. Within each, oldest file first.
- Each copy has `id`, `name`, `workspaceID` (`null` for the organization
  folder), `fileSpaceName` (the workspace's name, or "Library", which the app
  shows as "Organization folder"), `folderPath` (from the top folder down;
  empty at the top level) and `sizeBytes`.
- Groups come newest first: the group whose newest copy was created last
  leads.
- The list is paged. It also answers `totalCount`, the groups the reader
  has not hidden, and `hiddenCount`, the groups they have. Both cover every
  page and do not change with the `hidden` filter.
- `hidden=true` lists only the groups the reader hid. `hidden=false` lists
  only the others. Without it every group is listed.
- This is the same comparison as `duplicates` on a file and on an upload.
  See [Uploading](uploading.md#duplicates).
- The file listing's `duplicates=true` filter is narrower. It keeps files
  with another copy in the same workspace or organization folder only. See
  [Folders, moving and finding](organizing.md#filters).
- Nothing is merged or removed automatically. A group is information.

### Hiding a duplicate warning

Each person can hide the warning of a group for themselves.

- Hiding is private. It changes nothing for anyone else: other people still
  see the group as not hidden, and admins neither see nor change someone
  else's hides.
- Everyone who can read the place can hide there. A member who only reads
  the organization folder can hide an organization folder file's warning.
- A hide is for the whole group, not for one file. It is made through any
  live copy of the group, and it then applies to every copy: each copy's
  details read `duplicatesHidden: true`, in every place the person opens.
- A hide remembers the copies the person could open when hiding.
- **A new copy shows the warning again.** When a copy appears that was not
  there when the person hid the group, the group reads `hidden: false`
  again and counts in `totalCount`. A new copy is a new upload with the same
  bytes, a new version that makes another file identical, a copy restored
  from the trash that was in the trash when hiding, or a copy in a
  workspace the person has joined since.
- A copy that leaves does not end the hide. Trashing a copy, or replacing
  its content, keeps the rest of the group hidden.
- Hiding again after a new copy appeared hides the group with the new copy.
- Hiding twice is not an error. Showing a group that is not hidden is not
  an error either.
- Showing again removes the hide. The group reads `hidden: false` and counts
  in `totalCount` at once.
- A hidden group is still listed, with `hidden: true`, so it can be shown
  again.
- A file's `duplicates` are named whether hidden or not. `duplicatesHidden`
  only says that the reader hid the warning. It is `false` for a file
  without duplicates.
- A hide made with a credential covers the copies the credential can open.
  If the member's browser session opens more copies, their session still
  sees the warning.
- A file without any copy can be hidden too. It has no effect until a copy
  appears, and that first copy shows the warning.
- Only a live file can be named when hiding or showing. A file in the trash
  answers `404 NOT_FOUND`.
- Hiding and showing are not recorded in the audit trail and raise no
  `lockVersion`.

## In the app

### Opening the organization folder

The organization folder is opened from Files & Assets of any workspace of the
organization.

- The tree "Folders" in the Files & Assets navigation starts with the name
  of the organization, which is the organization folder: choosing it opens
  the organization folder, and its arrow closes or opens the nodes below it.
- Below it the tree has a workspace folder for each workspace of that
  organization you can open, then the organization folder's own folders.
  Choosing a workspace folder opens that workspace's files.
- The organization folder's top level lists the same workspace folders
  first, marked "Workspace", then its own folders and files. A workspace
  folder has no menu or select box and cannot be moved, renamed or deleted
  there: it only opens the workspace. Search, filters and type tabs leave
  workspace folders out.
- The command palette offers "Go to Organization folder".
- The organization folder's address is
  `https://app.usetalewright.com/w/{workspaceID}/files/library`. The
  workspace in the address is the one you came from. The organization folder
  shown is the same from every workspace.
- The breadcrumb reads "Files & Assets", the organization's name, then
  "Organization folder". The organization's name is not a link.
- The organization folder's top level lists only the organization folder's
  own folders and files. "Upload" and "New folder" there, for owners and
  admins, put files and folders in the organization folder.
- The card "Folder details" shows the badge "Every workspace" for the
  organization folder and for folders of the organization folder that are not
  public. A public one reads "Public", or "Public, from {folder}" when a
  folder above shares it.
- The card "People" shows the members of the organization.
- The organization folder has its own "All files" and "Suggestions" pages in the
  navigation "Files pages", a "Trash" page for owners and admins, and its
  own favorites.

### What a member sees in the organization folder

A plain member of the organization reads the organization folder and is
offered nothing that changes it:

- no "New folder" and no "Upload",
- no "Trash" in the navigation,
- no checkboxes to select files,
- a file's menu with "Open" and "Download", without "Rename", "Move" or
  "Move to trash",
- a file's page with "Download", without "Save details", "Move" or "Move to
  trash", and without a field to change the name,
- no "Upload files" in the command palette while the organization folder is
  open, and a file dropped on the organization folder page is not uploaded.

Where a change is refused anyway, for example on a page that was open while
the person's role changed, the app says "Only organization owners and admins
can change the organization folder." The organization folder's trash page,
opened by its address, shows the same sentence to a member.

Owners and admins of the organization see the organization folder like a
workspace, with every control.

### The Suggestions page

"Suggestions" in the navigation "Files pages" opens the suggestions of the
place that is open: the workspace's, or the organization folder's.

- The link shows a number while something waits for a look. The number
  is the open suggestions of the place plus its duplicate groups you have
  not hidden.
- The number counts every open suggestion of the place, however many there
  are and whoever may decide them. A plain member in the organization folder
  sees them counted too.
- A screen reader hears the two parts apart: "Suggestions, 1 open",
  "Suggestions, 2 duplicates" or "Suggestions, 1 open, 2 duplicates".
- Hiding a duplicate warning, or showing it again, changes the number at
  once, without a reload.
- With no open suggestion and no duplicate group left to look at, the link
  shows no number.
- The command palette offers "Go to Organization folder suggestions", which
  opens the organization folder's page from any workspace.
- The page is titled "Suggestions". From the top it has the queue "To
  decide", the table "Duplicate files" and the closed section "Handled".
  See [The queue "To decide"](#the-queue-to-decide),
  [Duplicate files on the Suggestions page](#duplicate-files-on-the-suggestions-page)
  and ["Handled"](#handled).
- In the organization folder, a plain member reads above the queue:
  "Organization owners and admins apply the organization folder's suggestions."

### The queue "To decide"

The queue shows what waits for a decision one card at a time: the open
suggestions of the place, newest first, then its duplicate groups you have
not hidden, in the order of "Duplicate files".

- A card is marked "Suggestion" or "Duplicate" and reads "1 of 4" at its
  end, where 4 is every open suggestion and every duplicate group you have
  not hidden, also those not loaded yet.
- A suggestion's card shows its summary and a line such as "3 items to
  decide · by Ravi Admin". Its button "Review" opens the suggestion. A plain
  member in the organization folder gets "Review" too, and the suggestion
  opens to read.
- A duplicate's card shows the name of the group's first copy and a line
  such as "2 copies, 18.4 kB each · in Sorrel Copies, Organization folder",
  with up to three places and "and 2 more" for the others. Its button "Hide"
  hides the group's warning for you, exactly as "Hide" in the table does:
  the app says "Duplicate warning hidden" with "Undo", and the next card
  comes forward.
- "Hide" is disabled when none of the group's listed copies is in the place
  that is open, as in the table.
- "Not now" puts the card at the back of the queue and brings the next one
  forward. It lasts until you leave the page: the next visit starts in the
  usual order again, and nothing is saved.
- Once every loaded card has been put off, the queue loads the next 50
  suggestions or groups, which come forward before the cards you put off.
- With a single card and nothing more to load, "Not now" is disabled.
- A runs the card's button ("Review" or "Hide"); S is "Not now". The keys
  work while no text field, dialog or menu has the keyboard. The command
  palette offers the same as "Review suggestion", "Hide duplicate warning"
  and "Not now", only while the Suggestions page shows a card.
- With nothing to decide it reads "Nothing to decide."
- While it loads it says "Loading what to decide". If the suggestions or the
  duplicates cannot be loaded it says "Could not load the open
  suggestions." or "Could not load the duplicates." with "Retry", and shows
  the cards of the other one.
- A card that replaces another fades in quickly. With reduced motion it
  simply appears.

### "Handled"

"Handled (3)" below "Duplicate files" opens the suggestions that are
done: "Closed" and "Expired", each newest first. The number counts both.

- It is closed when the page opens. While the number is not read yet, or
  could not be read, the button reads "Handled".
- With no closed or expired suggestion it is not there at all.
- Each row shows the summary as a link, then its progress, who made it and
  the time it was made. A closed one reads, for example, "1 applied, 1
  rejected, 1 changed since suggested". The last part is left out when no
  item is stale.
- An expired one reads, for example, "0 applied, 0 rejected, 1 not
  applied". "Not applied" counts the items nobody decided in time together
  with those whose file had changed.
- An empty list reads "No suggestion has been closed yet." or "No
  suggestion has expired."
- Each list shows the 50 newest suggestions in that state. "Load more"
  under a list shows the next 50, until every suggestion is listed.
- If a list cannot be loaded it says "Could not load the suggestions."

### Reviewing a suggestion

Choosing a suggestion opens the page "Suggested file changes".

- Under the title: the summary, "suggested by {name}" and the state "Open",
  "Closed" or "Expired".
- While items are pending, a line says "Nothing changes until you apply it."
  A plain member in the organization folder reads "Organization owners and
  admins apply the organization folder's suggestions." instead.
- Each item is one sentence, for example "Rename mark.png to Brand
  mark.png", "Add tag badges to seal.png", "Remove tag draft from
  beta.png", "Move beta.png to Brand / Logos", "Move beta.png to the top
  level", "Set the alt text of stamp.png to Rubber stamp" or "Clear the alt
  text of stamp.png". The item's rationale, if it has one, is below it.
- The file name in the sentence is the file's current name.

For someone who may decide, each pending item has a checkbox and two
buttons:

1. Tick the items to apply. With more than one pending item, "Select all
   changes" ticks them all.
2. To apply an item with another value, choose "Change it" and type into
   "New value for {file name}". For a move, type the folder names with `/`
   between them; an empty value is the top level. Escape restores the
   suggested value.
3. Choose "Apply". The button reads "Apply 1 change" or "Apply 2 changes"
   once items are ticked. Until then it is disabled and the page says
   "Select the changes to apply or reject."
4. The page then says what happened: "2 applied", or "1 applied, 1 changed
   since suggested".

- "Skip" on an item rejects that one item. The page says "1 rejected".
- "Reject selected" rejects the ticked items.
- Decided items stay on the page with their state at the end of the row:
  "Applied", "Rejected", "Changed since suggested" or, when the suggestion
  expired before anyone decided the item, "Expired". An applied item reads
  in the past tense with the value that was applied, for example "Added tag
  emblems to seal.png".
- When the last item is decided, the state under the title becomes "Closed"
  and the buttons disappear.
- A member who may not decide sees the same items with their states, and no
  checkbox, "Change it", "Skip", "Apply" or "Reject selected".

Messages when something is refused:

| Message | When |
| --- | --- |
| "This suggestion is closed or expired, so nothing more applies." | The suggestion closed or expired while the page was open. |
| "Someone decided some of these items already. The list is up to date now." | Somebody else applied or rejected one of the ticked items first. Nothing of your request was applied. Tick again and repeat. |
| "That would make 1 file public. Only an owner or admin can make files public." | A plain member applied a move into a shared folder. Nothing was applied. |
| "Could not update the suggestion." | The request failed for a reason that is not yours, for example a lost connection. Other refusals show the reason the service gives. |
| "This suggestion does not exist, or you do not have access to it." | The address names no suggestion of this place. |
| "Could not load the suggestion." | The page could not be loaded. |

The page does not reload when you come back to its window, so the items
stay as you were reviewing them. What others changed in the meantime shows
when you apply: files that changed come back as "Changed since suggested".

### Duplicate files on the Suggestions page

Under the queue, the Suggestions page has the table "Duplicate files": the
[duplicate groups](#duplicate-groups) of the place that is open, newest
first, one group a row. Its columns are "Files", "Copies" and "Size", then
the group's button. On a narrow screen each row stacks its cells.

- "Files" names the group's copies, one a line: the file's name as a link to its
  page, then "in" and where it is, such as "in Sorrel Copies / Brand" or "in
  Organization folder". The place is the workspace's name or "Organization
  folder", then the folders from the top down.
- Copies of the open place come first, then the organization folder's, then
  those of your other workspaces.
- "Copies" reads, for example, "2 copies", and "Size" "18.4 kB each". A
  group of more than 20 copies names the first 20 and adds a line with how
  many are not listed, such as "4 more not listed".
- A copy in another workspace opens in that workspace.
- "Hide" at the end of a row hides the group's warning for you. The group
  leaves the table, the number beside "Suggestions" drops by one, and the app says
  "Duplicate warning hidden" with "Undo".
- "Undo" shows the group again. So does Ctrl+Z, or Cmd+Z on a Mac, while
  the message is on screen.
- With no group left to look at, it reads "No duplicate files."
- The table shows 50 groups. "Show more" under it shows the next 50.
- While it loads it says "Loading duplicate files". If it cannot be loaded
  it says "Could not load the duplicate files." with "Retry".

Below the table, "Hidden (2)" opens the groups you have hidden. The number
is how many there are.

- It is closed when the page opens, and it is not there at all while you
  have hidden nothing.
- Each hidden group shows its copies as above, with "Show again" in place
  of "Hide".
- "Show again" returns the group to "Duplicate files" and to the number
  beside "Suggestions". The app says "Duplicate warning shown again".
- Hidden groups are yours alone. Nobody else sees what you have hidden.
- A plain member can hide and show again in the organization folder too.
  Hiding changes no file.
- If a hide or a show fails, the app says "Could not hide the duplicate
  warning. Try again." or "Could not show the duplicate warning again. Try
  again." and the lists stay as they were.

### The duplicate notice on a file's page

A file with copies elsewhere shows a notice marked "Duplicate" under its
name. See [Uploading](uploading.md#the-already-in--notice).

- "Hide" at the end of the notice hides the warning for you. The notice
  disappears and the app says "Duplicate warning hidden" with "Undo".
- "Undo" brings the notice back.
- The hide is for the whole group. The notice is gone from every copy's
  page, and the group moves under "Hidden" on the Suggestions page.
- The notice comes back when a new copy appears, as the rules under
  [Hiding a duplicate warning](#hiding-a-duplicate-warning) say, or when
  you choose "Show again" on the Suggestions page.
- Everyone who can open the file gets "Hide", also a plain member on an
  organization folder file's page.
- A hide does not change "Filter" > "Show" > "Duplicates" in a listing. It
  lists the file as before.

### Suggestion cards

The details beside the file listing start with a card for each open
suggestion of the place that is open.

- Each card is labelled "Suggestion", shows the number of pending changes,
  for example "3 changes", the summary and the button "Review", which opens
  the suggestion.
- At most three cards are shown, newest first. Below them a link such as
  "2 more suggestions" opens the Suggestions page.
- With no open suggestion there is no card.
- If the cards cannot be loaded, one card says "Could not load suggestions."
  with a way to retry.

## For agents

Every operation exists twice: for a workspace and for the organization
folder. The organization folder ones take `organizationID` where the
workspace ones take `workspaceID`. Inputs and answers are the same.

| Operation | Capability ID (workspace / organization folder) | MCP tool | Scope |
| --- | --- | --- | --- |
| `POST .../library-proposals` | `workspace.library_proposals.create` / `library.library_proposals.create` | `workspace_library_proposals_create` / `library_library_proposals_create` | `files:write` |
| `GET .../library-proposals` | `workspace.library_proposals.list` / `library.library_proposals.list` | `workspace_library_proposals_list` / `library_library_proposals_list` | `files:read` |
| `GET .../library-proposals/{proposalID}` | `workspace.library_proposals.get` / `library.library_proposals.get` | `workspace_library_proposals_get` / `library_library_proposals_get` | `files:read` |
| `POST .../library-proposals/{proposalID}/reject` | `workspace.library_proposals.reject` / `library.library_proposals.reject` | `workspace_library_proposals_reject` / `library_library_proposals_reject` | `files:write` |
| `POST .../library-proposals/{proposalID}/apply` | `workspace.library_proposals.apply` / `library.library_proposals.apply` | none | session only |

`...` is `/v1/workspaces/{workspaceID}` or
`/v1/organizations/{organizationID}/library`. The arguments and the shape of
a proposal are listed in [MCP](../agents/mcp.md#library-proposals). A
proposal can also be read as an MCP resource.

### Reaching the organization folder

- A credential reaches the organization folder of its own organization, whatever
  workspaces it lists. `workspaces_list` gives the `organizationID` to pass.
- Every file, folder, tag and upload tool has an organization folder twin:
  `library_files_search`, `library_files_get`, `library_folders_list`,
  `library_tags_list`, `library_uploads_create` and so on. See
  [MCP](../agents/mcp.md#how-tools-are-named).
- Reading the organization folder works for every member's credential with
  `files:read`.
- Changing the organization folder works only when the credential's member
  is an owner or admin of the organization. A plain member's credential gets
  `403 FORBIDDEN` there, also with `files:write`. Such a credential cannot
  make a library proposal either: the organization folder takes proposals
  from owners and admins only.

### Make a proposal

Over REST, in a workspace:

```sh
curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21/library-proposals" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Organize the launch assets",
    "requestID": "launch-assets-1",
    "items": [
      {
        "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
        "action": "rename",
        "payload": { "name": "alpha-logo.png" },
        "rationale": "Say what it is"
      },
      {
        "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
        "action": "add_tag",
        "payload": { "tag": "Logo" }
      },
      {
        "fileID": "0192f0b2-9c10-7e41-a2d5-6b1f0c3d4e02",
        "action": "move",
        "payload": { "folderPath": ["Brand", "Logos"] }
      },
      {
        "fileID": "0192f0b2-b7d4-7a90-9e13-0c5a8d6f7b03",
        "action": "set_alt_text",
        "payload": { "altText": "Gamma product shot on white" }
      }
    ]
  }'
```

The answer is `201` with the proposal:

```json
{
  "id": "0192f1aa-3c5e-7b6d-8f20-4a9d1e2c3b40",
  "summary": "Organize the launch assets",
  "state": "open",
  "allowedActions": ["reject"],
  "createdAt": "2026-11-14T09:30:00Z",
  "createdBy": { "id": "0192e7c1-2f4b-7c10-9a8e-1d2c3b4a5f60", "fullName": "Ravi Admin" },
  "expiresAt": "2026-11-28T09:30:00Z",
  "closedAt": null,
  "items": [
    {
      "id": "0192f1aa-3c5f-7001-8a11-000000000001",
      "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "fileName": "alpha.png",
      "action": "rename",
      "payload": { "name": "alpha-logo.png" },
      "appliedPayload": null,
      "rationale": "Say what it is",
      "baseLockVersion": 1,
      "resultLockVersion": null,
      "state": "pending",
      "decidedAt": null,
      "decidedBy": null
    },
    {
      "id": "0192f1aa-3c5f-7001-8a11-000000000002",
      "fileID": "0192f0b2-7a3f-7d22-8b66-3a7e1d2f8c01",
      "fileName": "alpha.png",
      "action": "add_tag",
      "payload": { "tag": "logo" },
      "appliedPayload": null,
      "rationale": null,
      "baseLockVersion": 1,
      "resultLockVersion": null,
      "state": "pending",
      "decidedAt": null,
      "decidedBy": null
    }
  ]
}
```

(The other two items are left out here.)

- The tag came back as "logo": payloads are normalized.
- Both items for `alpha.png` have `baseLockVersion` 1. Both apply.
- `createdBy` is the member the credential acts for.

The same over MCP, in the organization folder:

```json
{
  "name": "library_library_proposals_create",
  "arguments": {
    "organizationID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17",
    "summary": "Tidy the library",
    "requestID": "tidy-library-1",
    "items": [
      {
        "fileID": "0192f0c4-1a2b-7c3d-8e4f-5a6b7c8d9e01",
        "action": "rename",
        "payload": { "name": "Brand mark.png" }
      },
      {
        "fileID": "0192f0c4-2b3c-7d4e-9f50-6b7c8d9e0f02",
        "action": "add_tag",
        "payload": { "tag": "badges" }
      },
      {
        "fileID": "0192f0c4-3c4d-7e5f-a061-7c8d9e0f1a03",
        "action": "set_alt_text",
        "payload": { "altText": "Rubber stamp" }
      }
    ]
  }
}
```

This works when the credential's member is an owner or admin of the
organization.

Good practice for an agent:

- Read each file first and send its `lockVersion` as `baseLockVersion`.
  Then the item is applied only if the file is still what you looked at.
- Write a `summary` a person understands at a glance, and a `rationale`
  where the reason is not obvious.
- Keep one topic per proposal. A person decides item by item, but reads the
  summary first.
- Use `[]` as `folderPath` to move a file to the top level.
- Do not wait for an answer in the same call. The proposal is applied when
  a person gets to it, within 14 days, or not at all.

### Read it back

```sh
curl -s \
  "$TALEWRIGHT/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21/library-proposals/0192f1aa-3c5e-7b6d-8f20-4a9d1e2c3b40" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

After a person applied the rename and the tag, changed the alt text before
applying it and left the move undecided, the items read (shortened):

```json
{
  "state": "open",
  "allowedActions": ["reject"],
  "closedAt": null,
  "items": [
    {
      "action": "rename",
      "fileName": "alpha-logo.png",
      "payload": { "name": "alpha-logo.png" },
      "appliedPayload": null,
      "baseLockVersion": 1,
      "resultLockVersion": 2,
      "state": "applied",
      "decidedAt": "2026-11-15T08:02:11Z",
      "decidedBy": { "id": "0192e7c1-55aa-7d20-8b9f-2e3d4c5b6a70", "fullName": "Olga Owner" }
    },
    {
      "action": "add_tag",
      "fileName": "alpha-logo.png",
      "payload": { "tag": "logo" },
      "appliedPayload": null,
      "baseLockVersion": 1,
      "resultLockVersion": 3,
      "state": "applied"
    },
    {
      "action": "move",
      "fileName": "beta.png",
      "payload": { "folderPath": ["Brand", "Logos"] },
      "resultLockVersion": null,
      "state": "pending",
      "decidedAt": null,
      "decidedBy": null
    },
    {
      "action": "set_alt_text",
      "fileName": "gamma.png",
      "payload": { "altText": "Gamma product shot on white" },
      "appliedPayload": { "altText": "Gamma on white" },
      "resultLockVersion": 2,
      "state": "applied"
    }
  ]
}
```

- `fileName` is the file's name now, so the first two items show the new
  name.
- `resultLockVersion` went 2, then 3: one step per applied item.
- `appliedPayload` holds what the person applied instead of the suggested
  alt text.
- The proposal is still `open`, because the move is pending.

To follow many proposals, list them:

- `GET .../library-proposals` returns a page, newest first. Each entry has
  `id`, `summary`, `state`, `allowedActions`, `createdAt`, `createdBy`,
  `expiresAt`, `closedAt` and the counts `pending`, `applied`, `rejected`
  and `stale`. It does not hold the items.
- `state` filters by `open`, `closed` or `expired`.
- Beside `items` and `nextCursor` the answer holds `totalCount`: the number
  of proposals in the `state` asked for, over all pages. Without `state` it
  counts every proposal of the workspace or organization folder.
- `limit` is 1 to 100, 50 when left out. `cursor` takes the `nextCursor` of
  the page before. See [Paging](../agents/rest-api.md#paging).

### Reject

Withdraw what is left of a proposal:

```sh
curl -s -X POST \
  "$TALEWRIGHT/v1/workspaces/0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21/library-proposals/0192f1aa-3c5e-7b6d-8f20-4a9d1e2c3b40/reject" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

- `{}` rejects every pending item. `{"itemIDs": ["..."]}` rejects only
  those.
- The answer is `200` with the proposal. Here the move is now `rejected`,
  the state is `closed` and `closedAt` is set.
- The MCP tools are `workspace_library_proposals_reject` and
  `library_library_proposals_reject`, with `proposalID` and optionally
  `itemIDs`.

### Apply (a person, in a browser)

There is no tool that applies. For completeness, the session-only operation
takes:

```json
{
  "items": [
    { "itemID": "0192f1aa-3c5f-7001-8a11-000000000001" },
    {
      "itemID": "0192f1aa-3c5f-7001-8a11-000000000004",
      "payload": { "altText": "Gamma on white" }
    }
  ]
}
```

and answers `200` with `{"applied": 2, "stale": 0, "proposal": {...}}`.

### Listing and hiding duplicates

| Operation | Capability ID (workspace / organization folder) | MCP tool | Scope |
| --- | --- | --- | --- |
| `GET .../duplicates` | `workspace.duplicates.list` / `library.duplicates.list` | `workspace_duplicates_list` / `library_duplicates_list` | `files:read` |
| `PUT .../files/{fileID}/duplicates/hidden` | `workspace.duplicates.hide` / `library.duplicates.hide` | none | `files:read` |
| `DELETE .../files/{fileID}/duplicates/hidden` | `workspace.duplicates.show` / `library.duplicates.show` | none | `files:read` |

- The list takes `hidden` (`true` or `false`, optional), `cursor` and
  `limit` (1 to 100, default 50).
- Hiding and showing take no body and answer `204` with no content. They
  act for the member the credential belongs to.
- Hiding and showing are not MCP tools: they are a person's own preference.
  An agent reads the groups, and each group's `hidden`, with the list tool.

```sh
curl -s "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/duplicates?hidden=false" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

```json
{
  "items": [
    {
      "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "hidden": false,
      "fileCount": 3,
      "files": [
        {
          "id": "0192f1aa-3c5f-7001-8a11-0000000000a1",
          "name": "logo.png",
          "workspaceID": "0192e7c4-0b10-7a11-9c01-000000000001",
          "fileSpaceName": "Brand",
          "folderPath": [{ "id": "0192e7c4-0d20-7b12-8c02-000000000007", "name": "Logos" }],
          "sizeBytes": 48211
        },
        {
          "id": "0192f1aa-3c5f-7001-8a11-0000000000a2",
          "name": "logo-final.png",
          "workspaceID": "0192e7c4-0b10-7a11-9c01-000000000001",
          "fileSpaceName": "Brand",
          "folderPath": [],
          "sizeBytes": 48211
        },
        {
          "id": "0192f1aa-3c5f-7001-8a11-0000000000a3",
          "name": "Logo.png",
          "workspaceID": null,
          "fileSpaceName": "Library",
          "folderPath": [],
          "sizeBytes": 48211
        }
      ]
    }
  ],
  "nextCursor": null,
  "totalCount": 1,
  "hiddenCount": 0
}
```

Hide that group for the member, through any of its live copies in the
workspace:

```sh
curl -s -X PUT \
  "$TALEWRIGHT/v1/workspaces/$WORKSPACE_ID/files/0192f1aa-3c5f-7001-8a11-0000000000a1/duplicates/hidden" \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

- The answer is `204`. The list then reads `totalCount` 0 and
  `hiddenCount` 1, and the group reads `hidden: true`.
- `DELETE` on the same path shows the warning again.
- To clean up a group, trash the copies that are not needed
  (`workspace_files_trash`, `library_files_trash`). A copy in the trash
  leaves its group at once.

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| A plain member of the organization renames, trashes or restores an organization folder file, creates or renames a folder of the organization folder, or renames or deletes an organization folder tag | `403 FORBIDDEN`. Nothing changes. | Only organization owners and admins change the organization folder. |
| A member who is owner of a workspace changes the organization folder | `403 FORBIDDEN`. | The role in the organization counts in the organization folder, not a workspace role. |
| A member of the organization who belongs to no workspace reads the organization folder through the API | It works. | Reading the organization folder needs only membership of the organization. |
| Someone outside the organization asks for the organization folder, an organization folder file or a folder of the organization folder | `404 NOT_FOUND`, exactly as for an organization that does not exist. | Outsiders cannot tell the organization folder exists. |
| An organization folder file's ID is used in a workspace path, or a workspace file's ID in the library path | `404 NOT_FOUND`. | A file belongs to one place. |
| A workspace file is moved into a folder of the organization folder | `422 VALIDATION_FAILED`. The file stays. | Files do not move between places. |
| A key that lists one workspace reads the organization folder | It works, for the organization folder of the key's own organization. | Every credential reaches its organization folder. |
| A plain member's key with `files:write` uploads to the organization folder or creates a folder of the organization folder | `403 FORBIDDEN`. | The key acts for its member, who only reads the organization folder. |
| An owner is made a plain member while an organization folder page is open | Their next change is refused and the app says "Only organization owners and admins can change the organization folder." | The role is checked at each change. |
| A plain member makes a library proposal | `403 FORBIDDEN`. An owner's or admin's is created. | The organization folder takes proposals from owners and admins only. |
| A proposal names a file in the trash | `422 VALIDATION_FAILED` on `items`. No proposal is made. | Items must name live files. |
| A proposal names a file of another workspace, or an unknown ID | `422 VALIDATION_FAILED` on `items`, the same answer for both. | A foreign file must not be told apart from one that does not exist. |
| One of 300 items names a trashed file | The whole proposal is refused. | A proposal is made whole or not at all. |
| A `rename` item carries `{"tag": "x"}` | `422 VALIDATION_FAILED` on `payload`. | The payload must fit the action. |
| A payload has an extra key, such as `{"name": "a.png", "note": "..."}` | `422 VALIDATION_FAILED` on `payload`. | Unknown keys are refused. |
| A `folderPath` names 17 folders | `422 VALIDATION_FAILED` on `payload`. | Folders nest at most 16 levels. |
| A folder name in `folderPath` contains `/`, or is blank | `422 VALIDATION_FAILED` on `name`. | The folder naming rules. |
| `rationale` is an empty string, or holds a line break | `422 VALIDATION_FAILED` on `rationale`. | It is 1 to 2,000 characters on one line; leave it out when there is none. |
| A proposal has no items, or 501 | `422 VALIDATION_FAILED` on `items`. | A proposal holds 1 to 500 items. |
| `baseLockVersion` is 0 | `422 VALIDATION_FAILED` on `items`. | It must be at least 1. |
| `baseLockVersion` is older than the file's `lockVersion` | The proposal is made. The item ends `stale` when it is applied. | The value is checked at apply, not at creation. |
| Two items rename the same file to two different names | Both are accepted. If both are applied, the later item in the proposal's order wins. | Items for one file apply one after the other. |
| The same `requestID` is sent again with the same body within 24 hours | `201` with the proposal the first request made, as it is now. No second proposal. | Safe retries. |
| The same `requestID` is sent with another body, or for another workspace | `409 CONFLICT`, reason `REQUEST_REUSED`. | A `requestID` names one request. |
| A `requestID` used for a workspace proposal is used for a library proposal | `201` with a new proposal. | Proposing in a workspace and proposing in the organization folder are two operations, and each keeps its own request IDs. |
| A request is retried with its `requestID` after one of its files was trashed | `201` with the proposal the first request made, as it is now. | A retry is matched to the first request before its files are looked at. |
| A key tries to apply a proposal | `403 FORBIDDEN`, reason `HUMAN_APPROVAL_REQUIRED`. | Applying needs a person in a browser. |
| A file was renamed after the proposal was made, and an item for it is applied | The item becomes `stale`: "Changed since suggested". The newer name stays. | The file is no longer what the item was based on. |
| A file got a new version after the proposal was made | Its items still apply. | A new version does not raise the file's `lockVersion`. |
| A file was moved to the trash after the proposal was made | Its items become `stale` when applied. The file stays in the trash, unchanged. | Only live files are changed. |
| That file is restored before the items are applied | The items still become `stale`. | Trashing and restoring both raise the file's `lockVersion`. |
| A file named by a proposal is deleted for good | Its items are removed from the proposal. If no pending item is left, the proposal closes at that moment. A proposal can end up `closed` with no items at all. | Nothing of a deleted file is kept, and a proposal with nothing to decide is not left open. |
| Two items for one file are applied together | Both apply. The file's `lockVersion` rises by two. | Each item expects the `lockVersion` the one before left. |
| One item for a file is applied today and the other tomorrow, and nobody touched the file in between | Both apply. | The second expects what the first left. |
| Between those two, somebody edits the file | The second item becomes `stale`. | The file changed outside the proposal. |
| `add_tag` for a tag the file already has | The item is applied. The tags are the same. The file's `lockVersion` still rises. | Applying is recorded as a change. |
| `add_tag` on a file that already has 50 tags | `422 VALIDATION_FAILED` on `tags`. Nothing of the request is applied. | A file has at most 50 tags, and a refused item refuses the request. |
| `remove_tag` for a tag the file does not have | The item is applied. Nothing is removed. | There is nothing to take off. |
| `move` to `["brand", "Logos"]` while a folder "Brand" exists | The file goes to Brand / Logos. "Logos" is created once; "Brand" is reused. | Folder names match ignoring case. |
| `move` into a folder that is in the trash | A new folder with that name is created and the file goes there. | Trashed folders do not count; their name is free. |
| `move` to the folder the file is already in | The item is applied. The file stays where it is. | The destination is what was asked for. |
| A plain workspace member applies a `move` into a public folder, for a file whose status allows public use | `403 FORBIDDEN`, reason `MAKES_FILES_PUBLIC`. Nothing of the request is applied. An owner or admin applying the same item makes the file public. | Only owners and admins make files public. |
| A plain workspace member applies a `move` that takes a file out of a public folder | It is applied. The file's public link stops. | Stopping links needs no special role, and applying confirms the move. |
| A `rename` is applied to a file with a public link | The link keeps working. | The name in a public link is only decoration. |
| The person applying changes a tag to "Emblems" with "Change it" | The file gets the tag "emblems". The item keeps its `payload` and gets `appliedPayload` `{"tag": "emblems"}`. | What was applied is recorded next to what was suggested. |
| The changed value is not valid, for example an empty name | `422 VALIDATION_FAILED`. Nothing of the request is applied. | A changed payload must fit its action. |
| Two people apply the same item at the same moment | One applies it. The other gets `409 CONFLICT`, reason `ITEM_DECIDED`, and nothing of their request is applied. | Decisions on one proposal are handled one after the other. |
| A request names five pending items and one decided item | `409 CONFLICT`, reason `ITEM_DECIDED`. The five stay pending. | A request with a decided item is refused whole. |
| A request names an item of another proposal, or an unknown item ID | `422 VALIDATION_FAILED` on `items`. | Items must belong to the proposal. |
| A request names the same item twice, or no item | `422 VALIDATION_FAILED` on `items`. | 1 to 500 distinct items. |
| `reject` is sent with `"itemIDs": []` | `422 VALIDATION_FAILED` on `items`. | Leave `itemIDs` out to reject everything pending. |
| The last pending item is rejected | The proposal is `closed`. | A proposal closes when nothing is pending. |
| A closed proposal is applied or rejected | `409 CONFLICT`, reason `CLOSED`. | Nothing is left to decide. |
| A proposal passes its 14 days with items pending | It reads `expired` and answers `CLOSED` to apply and reject. Its pending items turn `stale` within about an hour. | Proposals do not stay open forever. |
| A proposal was fully decided on day 3 | It reads `closed` on day 3 and on day 30. | Only a proposal with pending items expires. |
| A proposal of another workspace is read, applied or rejected through your own workspace | `404 NOT_FOUND`, as for an unknown ID. | A proposal belongs to one place. |
| A plain member opens an organization folder suggestion in the app | They read every item and its state. No checkbox, "Apply" or "Reject selected" is offered. | Members read the organization folder. |
| A workspace is deleted while it has open suggestions | They are unreachable with the workspace, like everything in it. A restore brings them back; their 14 days are not paused meanwhile. | See [Workspaces](../organizations/workspaces.md#what-deletion-does-at-once). |
| The same bytes are in your workspace and in a workspace you cannot open | No group is listed for you, and the file reads no duplicates. | A group needs two copies the reader can open. |
| The same bytes are in your workspace and in the organization folder | The workspace and the organization folder both list the group, each with its own copy first. | A place lists a group when one copy is there. |
| You hide a group, then a colleague uploads the same bytes again | The group reads `hidden: false` again and counts in `totalCount`. | A hide covers the copies you could open when hiding. |
| You hide a group of three copies, then one copy is trashed | The group stays hidden, with two copies. | A copy that leaves does not end a hide. |
| That copy is restored from the trash | The group stays hidden. | The restored copy was one of the copies hidden. |
| A copy that was already in the trash when you hid the group is restored | The group shows the warning again. | That copy was not among the copies hidden. |
| You hide a group, then join a workspace that holds another copy | The group shows the warning again. | You can now open a copy you could not when hiding. |
| One of two copies gets a new version with other bytes | The group is gone. Each file reads no duplicates. | Only current versions are compared. |
| Two people hide the same group, and one shows it again | It stays hidden for the other. | Hides are per person. |
| An owner looks at a member's duplicate groups | The owner sees their own `hidden` values, never the member's. | Nobody reads or changes another person's hides. |
| A key that lists one workspace hides a group whose third copy is in another workspace of its member | The key sees the group hidden. The member's browser session still sees the warning. | The key hid the copies it can open. |
| A hide is asked for a file in the trash, a file of another place, or an unknown ID | `404 NOT_FOUND`, the same answer for all three. | Only a live file of the place can be named. |
| A member of the organization who is in no workspace hides an organization folder file's warning | It works. | Reading the organization folder is enough. |
| A group has 30 copies | `fileCount` is 30 and `files` names the first 20. | A group names at most 20 copies. |
| In the app, you hide a group on the Suggestions page of a workspace, and one copy is in the organization folder | The group moves under "Hidden" on the organization folder's Suggestions page too, and the number beside "Suggestions" drops there as well. | A hide is for the whole group, in every place you open. |
| In the app, you choose "Hide" on a file's notice and then "Undo" | The notice is back, and so is the group in "Duplicate files". | "Undo" shows the warning again. |
| In the app, you hid a warning yesterday and want it back | Open "Suggestions", then "Hidden", and choose "Show again". | The message with "Undo" is gone after a few seconds; the hidden list stays. |
| In the app, a place has 3 open suggestions and 2 duplicate groups, one of them hidden | The number beside "Suggestions" is 4. | Hidden groups do not count. |
| In the app, your colleague hid a group you have not | You still see the notice and the group, and your number counts it. | Hides are per person. |

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | Not signed in, or an invalid credential. | Sign in or use a valid credential. |
| `FORBIDDEN` | 403 | A plain member changes the organization folder, or makes, applies or rejects a library proposal. | Ask an organization owner or admin. |
| `FORBIDDEN`, reason `HUMAN_APPROVAL_REQUIRED` | 403 | A credential applies a proposal. Message: "Approvals need a person signed in with a browser". | A person applies it in the app. |
| `FORBIDDEN`, reason `INSUFFICIENT_SCOPE` | 403 | The credential lacks `files:read` (list and read proposals; list duplicate groups, hide and show their warning) or `files:write` (create, reject). `details.requiredScopes` names the scope. | Use a credential with that scope. |
| `FORBIDDEN`, reason `MAKES_FILES_PUBLIC` | 403 | A plain workspace member applies a move that would make files public. `details.becomePublic` counts them. Nothing was applied. Message: "This would make files public; only an owner or admin can do that". | Have an owner or admin apply the item, or reject it and apply the rest. |
| `NOT_FOUND` | 404 | The workspace, organization or proposal is unknown or out of your reach. A duplicate warning is hidden or shown for a file that is unknown, in the trash or not in this workspace or organization folder. | Check the IDs with `workspaces_list` and a proposal list. |
| `CONFLICT`, reason `CLOSED` | 409 | A closed or expired proposal is applied or rejected. Message: "This suggestion is closed or expired". | Make a new proposal. |
| `CONFLICT`, reason `ITEM_DECIDED` | 409 | A named item is no longer pending. Message: "Some selected items were already decided". Nothing was applied or rejected. | Read the proposal again and name only pending items. |
| `CONFLICT`, reason `REQUEST_REUSED` | 409 | A `requestID` is repeated with another body or for another workspace within 24 hours. | Use a new `requestID` for a new request. |
| `VALIDATION_FAILED` on `summary` | 422 | The summary is blank, over 500 characters or holds a control character. | Correct it. |
| `VALIDATION_FAILED` on `items` | 422 | Creating: not 1 to 500 items; an item names a file that is not live in this place; `baseLockVersion` below 1. Applying or rejecting: not 1 to 500 distinct items; an item that is not of this proposal. | Correct the list. |
| `VALIDATION_FAILED` on `payload` | 422 | A payload does not fit its action, or `folderPath` names more than 16 folders. | Send the payload the action takes. |
| `VALIDATION_FAILED` on `tags` | 422 | A tag is blank, over 50 characters or holds a control character or a comma; or applying would give a file more than 50 tags. | Correct the tag, or free a tag on the file. |
| `VALIDATION_FAILED` on `name` | 422 | A file name or a folder name in `folderPath` is blank, over 200 characters or holds a control character; a file name holds `/` or `\`, or a folder name holds `/`. | Correct the name. |
| `VALIDATION_FAILED` on `altText` | 422 | The alt text is over 1,000 characters or holds a control character. | Shorten it. |
| `VALIDATION_FAILED` on `rationale` | 422 | The rationale is blank, over 2,000 characters or holds a control character. | Correct it, or leave it out. |
| `VALIDATION_FAILED` on `requestID` | 422 | Not 1 to 64 letters, digits, `-` or `_`. | Correct it. |
| `VALIDATION_FAILED` | 422 | The body is not the expected JSON, `action` is not one of the five, a `fileID` or an item ID in the body is not a UUID, or a list request has an invalid `state`, `hidden`, `cursor` or `limit`. | Correct the request. |
| `RATE_LIMITED` | 429 | A credential passed its request limit. | Wait for `Retry-After` seconds. |

See [Errors](../reference/errors.md) for the shape of every error, and
[`CONFLICT`](../reference/errors.md#conflict-409) for every reason.

## Limits

| What | Value |
| --- | --- |
| Organization folders per organization | 1 |
| Items in one suggestion | 1 to 500 |
| Summary | 1 to 500 characters, one line |
| Rationale of an item | 1 to 2,000 characters, one line; optional |
| Tag in `add_tag` and `remove_tag` | 1 to 50 characters once normalized, no comma |
| Tags on one file | Up to 50 |
| File name in `rename` | 1 to 200 characters, no `/` or `\` |
| Folders in a `folderPath` | Up to 16; each name 1 to 200 characters, no `/` |
| Alt text in `set_alt_text` | Up to 1,000 characters |
| Items in one apply or reject request | 1 to 500, each once |
| A suggestion stays open | 14 days from when it was made |
| Pending items of an expired suggestion turn stale | Within about an hour after the expiry |
| `requestID` | 1 to 64 letters, digits, `-` or `_`; remembered for 24 hours |
| Page size of a proposal list | 1 to 100, default 50 |
| Suggestions shown per list in the app | The 50 newest, and 50 more with each "Load more" |
| Suggestion cards beside the file listing | Up to 3 |
| Copies needed for a duplicate group | 2 or more that the reader can open, at least 1 of them in the place |
| Copies named in one duplicate group | Up to 20; `fileCount` gives the full number |
| Page size of a duplicate group list | 1 to 100, default 50 |
| Hides of one duplicate group per person | 1 |

See [Limits](../reference/limits.md#library-proposals-suggestions).

## Questions and answers

**What is the organization folder for?**
Files the whole organization uses, whatever the workspace: logos, brand
guides, fonts, templates. Put a file there once instead of copying it into
every workspace.

**Who can see the organization folder?**
Every member of the organization, including members who belong to only one
workspace.

**Who can change the organization folder?**
The organization's owners and admins. Everyone else reads and downloads.

**I am owner of my workspace. Why can I not upload to the organization folder?**
The organization folder belongs to the organization. Only your role in the
organization counts there, and that is member.

**Why is there no "Upload" or "New folder" in the organization folder?**
You are a plain member of the organization. Ask an owner or admin to add the
file, or to make you an admin.

**Where is the organization folder in the app?**
In Files & Assets, choose the organization's name at the top of the tree
"Folders". Or run "Go to Organization folder" from the command palette.

**Is the organization folder different in each workspace?**
No. There is one organization folder per organization. Every workspace shows
the same one.

**Can I move a file from my workspace into the organization folder?**
No. Files do not move between a workspace and the organization folder, or
between workspaces. Download the file and have an owner or admin upload it
to the organization folder. That makes a new file there, with its own
history and its own link; the file's details then name the other copy as a
duplicate.

**Are tags and folders shared between the organization folder and workspaces?**
No. Each has its own folders and tags, and its own statuses and custom
fields.

**What does "Every workspace" mean in the organization folder?**
The organization folder, or a folder in it, is not public.
Everyone in the organization can open it, from any workspace. An
organization folder file's "Sharing" section says the same in words: "Only
people in the organization can open it."

**Can an organization folder file have a public link?**
Yes, with the same rules as any file. An organization owner or admin shares
it, and its status must allow public use. See
[Sharing and public links](sharing.md).

**Does the organization folder have its own trash?**
Yes. Organization owners and admins trash, restore and delete for good
there. See [Trash and restore](trash.md).

**Can I delete the organization folder?**
No. It goes with the organization.

**Can an agent work in the organization folder?**
Yes. Every credential reaches the organization folder of its organization
and can read it with `files:read`. It can change it only when its member is
an owner or admin of the organization.

**What is a suggestion?**
A list of proposed changes to files that waits for a person. Nothing changes
until someone applies it.

**What is the difference between a suggestion and a library proposal?**
None. "Suggestion" is the word in the app. "Library proposal" is the name in
the API and in MCP.

**Is a "library proposal" only for the organization folder?**
No. Despite the name, every workspace has them too.

**What can a suggestion change?**
Tags, the folder a file is in, a file's name and its alt text. Nothing else:
not statuses, not sharing, not descriptions, captions or custom fields, and
it cannot trash or delete anything.

**How do I make a suggestion in the app?**
You do not. The app reviews suggestions; it has no form to write one. They
come in through the API or MCP, usually from an agent.

**Can an agent apply its own suggestion?**
No. Applying needs a person signed in with a browser. An agent can make
suggestions, read them and reject them.

**Why would an agent suggest instead of just changing the files?**
With `files:write` it can change them directly. A suggestion is for changes
a person should look at first, or for the organization folder when the
reviewer should decide item by item.

**Who can apply a suggestion?**
In a workspace, everyone who can open it. In the organization folder,
organization owners and admins.

**Do I have to apply everything?**
No. Tick the items you want. The others stay pending until someone applies
or rejects them, or the suggestion expires.

**Can I change what is suggested before applying?**
Yes. "Change it" lets you type another value for that item. The suggestion
keeps both what was suggested and what you applied.

**What does "Changed since suggested" mean?**
The file was changed after the suggestion was made, or is in the trash, so
the item was not applied. It is the API's `stale`. The file is as it was;
make a new suggestion if the change is still wanted.

**I applied two changes and the page says "1 applied, 1 changed since
suggested". What happened?**
One file was edited by someone after the suggestion was made. That item was
skipped to avoid overwriting their work. The other was applied.

**Can I undo an applied suggestion?**
There is no undo for a suggestion. Each applied item is an ordinary change
to a file: rename it back, move it back or change the tags again.

**What happens to a suggestion nobody looks at?**
It expires 14 days after it was made. Its undecided items are marked as not
applied and nothing changes.

**Where did my expired suggestion go?**
It is under "Handled" > "Expired" on the Suggestions page. Its address still
opens it, and the API lists it with `state=expired`.

**Can a suggestion make a file public?**
Not by itself: it cannot change a status or general access. A move into a
shared folder makes a file public if its status allows public use. Only an
owner or admin can apply such a move.

**I am a member and applying says "That would make 1 file public. Only an
owner or admin can make files public." What now?**
Nothing was applied. Untick that move and apply the rest, or ask an owner or
admin to apply it.

**Can I reject a suggestion somebody else made?**
Yes, if you may reject in that place: everyone in a workspace, owners and
admins in the organization folder.

**Does anyone get an email about a suggestion?**
No. Open suggestions show as a count on "Suggestions" and as cards beside
the file listing.

**Is applying recorded?**
Yes. The audit trail records who made, applied and rejected a suggestion,
and each applied item as a change to its file that names the suggestion.

**How many changes fit in one suggestion?**
500. Make several suggestions for more.

**What is a duplicate group?**
Live files whose current versions have exactly the same bytes, in places
you can open. Names do not matter.

**Where do I see the duplicate files of a workspace or the organization
folder?**
On its Suggestions page, under "Duplicate files". Each group names its
copies with where they are and links to each.

**Can I hide a duplicate warning I do not care about?**
Yes. Choose "Hide" on the notice on the file's page, or on the group under
"Duplicate files" on the Suggestions page. Through the API it is
`PUT .../files/{fileID}/duplicates/hidden` for any copy of the group. It
hides the warning for you alone.

**I hid a duplicate warning and it is back. Why?**
A new copy of the same file appeared. A hide covers the copies you could
open when you hid the group, so a new copy shows the warning again.

**How do I get a hidden warning back?**
Right after hiding, choose "Undo". Later, open "Suggestions", then "Hidden",
and choose "Show again". Through the API it is
`DELETE .../files/{fileID}/duplicates/hidden` for any live copy. Hidden
groups stay in the list with `hidden: true`, so they can be found.

**What does the number beside "Suggestions" count?**
The open suggestions of the place plus its duplicate groups you have not
hidden.

**Does hiding a duplicate warning hide it for my colleagues?**
No. Each person hides for themselves.

**Does hiding delete or merge anything?**
No. Every copy stays as it is. To get rid of a copy, move it to the trash.

**Which number is the count of duplicates I have not dealt with?**
`totalCount` of the duplicate group list: the groups you have not hidden.

## Related pages

- [Files & Assets overview](overview.md)
- [Uploading](uploading.md)
- [Folders, moving and finding](organizing.md)
- [Versions and history](versions.md)
- [Trash and restore](trash.md)
- [Statuses](statuses.md)
- [Sharing and public links](sharing.md)
- [Fields and tags](fields-and-tags.md)
- [Downloading](downloading.md)
- [Workspaces](../organizations/workspaces.md)
- [Members and roles](../organizations/members-and-roles.md)
- [Credentials and scopes](../agents/credentials.md)
- [MCP](../agents/mcp.md#library-proposals)
- [The REST API](../agents/rest-api.md)
- [Roles and permissions](../reference/permissions.md#library-proposals-suggestions-in-a-workspace)
- [Audit trail](../reference/audit-trail.md#library-proposals)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)

