> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace rules

> The exact rules of workspaces: one home seen whole, members and roles, adoption, guarded writes, why and sessions, what load returns, browser pairing, the change stream and lifecycle

For agents and developers: the exact rules workspaces follow. For what a workspace is and why to use one, read [Workspaces](https://docs.tokenrip.com/concepts/workspaces.md).

A **workspace** is the authoritative home for a project's content. People and their agents work on the same artifacts, tables, flat folders, and tasks through the ordinary Tokenrip operations. Everyone in it sees all of it, and each person's role decides what they may change. It is personal or team-owned. Every agent change says why it was made, so the next agent (or person) who opens the workspace sees who worked, toward which goals, and what they changed. When the operator opens it, a browser tab can follow the agent.

## One home, seen whole

Every artifact and folder has at most one workspace home, and every task lives in exactly one workspace — there are no personal or team tasks. Everyone in a workspace sees all of it: files, tables, folders, tasks, outputs, jobs, every agent's instructions, the history and the trash. Nothing in a workspace has its own setting for who sees it. To keep work private, put it in a separate workspace.

Workspace authority runs **before** every other grant. An artifact with a workspace home uses the workspace's people instead of standalone team shares, and attempts to team-share workspace content are refused. A write that sends `audience` is refused with `400 INVALID_FIELD` and this message: "Sharing is by workspace now: everyone in a workspace sees all of it. Keep private work in a separate workspace."

**Public access** is the one step past the members. Any editor can turn on one file's public link (`visibility: link`, or **Public** on the file's **Public link** chip in the dashboard): anyone with its URL reads that file alone, with no login and no account, including its earlier versions, so prune them first if they shouldn't be. The file never appears in listings, search or sitemaps for outsiders, and they see no workspace fields. New, adopted and forked files start `private` (members only). See [Sharing & Access](https://docs.tokenrip.com/reference/sharing.md#public-access-to-one-file).

## Members and roles

Ownership grants access live: the personal owner, or the owning team's owner and admins, are **admins**; every other member of the owning team is an **editor**. Anyone else is a **guest** you add or invite, as an **editor** or a **viewer**. A guest reaches only the workspaces they are added to. To give someone every team workspace, plus the team's skills and connections, add them to the owning team, where each member is billed. Adding someone who already has access as the owner or through the owning team is refused (`WORKSPACE_MEMBER_INTERNAL`). An add or role change that sends `membership` is refused with "Everyone added to a workspace is a viewer or an editor; set role."

**Invite anyone by email.** Add an email address, whether or not the person uses Tokenrip. Tokenrip emails them who invited them to what, with your optional note, a link to the invite page and a line to paste into an AI assistant. They sign in with the six-digit code Tokenrip sends to that address, in the browser or through their agent, and they are in: signing in with the address claims every invite waiting on it, with no separate accept step. Until then the members list shows them as **invited**, with an invite link you can share (it signs no one in). Someone who already uses Tokenrip is added at once; an add by their address tells them by email. Editors share: any editor or admin, guests included, invites people, changes a guest's role and removes them. A viewer sees the members list without email addresses or pending invites. See [Members and Invites](https://docs.tokenrip.com/api-reference/workspaces/members.md).

| | Admin | Editor | Viewer |
| - | - | - | - |
| Read everything, browse, navigate; list members | yes | yes | yes |
| Post messages in the workspace's [chat](https://docs.tokenrip.com/concepts/threads.md) and on its tasks | yes | yes | yes |
| Create and edit artifacts, rows, folders, tasks; propose, report and decide what is addressed to them | yes | yes | no |
| Pin context | yes | yes | no |
| Delete artifacts and folders, and restore them from the trash | yes | yes | no |
| Share: invite people, change their role, remove them, set a file's public link | yes | yes | no |
| Rename the workspace and change its settings | yes | no | no |
| Delete the workspace, and restore it from the trash | yes | no | no |

Admins are on the owner side only; a guest is an editor or a viewer. An agent key limited to a workspace (`read` or `write`) never pins, shares, changes the workspace's settings or deletes it, even when its person could (`KEY_ACCESS_LIMITED`).

Creation is attribution, not a grant: someone who made an artifact and later leaves has no access to it. A role change or a removal takes effect on the next request. It stops any task holds the new role no longer allows, clears the person (or their agents) as assignee or reviewer of tasks they can no longer work on, withdraws their open proposals on those tasks, and disconnects their paired browser tabs. A workspace admin may decide any review in the workspace, from their own browser session (a browser an agent's sign-in link signed in is asked to sign in with email first).

## Folders without inheritance

Folders stay flat and grant nothing by themselves. Everyone in the workspace sees every folder and everything in it. Deleting a workspace folder moves it and the artifacts in it to the [trash](https://docs.tokenrip.com/concepts/trash.md); restoring the folder brings them back filed as they were.

## Bringing existing content in

**Adopt** moves an artifact or a normal folder you own into a workspace — atomically, without copying, keeping its identity and versions — and removes its old team shares. Everyone in the workspace then sees it. Public assets and independently hosted content are refused up front. Adoption is the only move direction; there is no move-out.

## Guarded writes

Two people — or a person and an agent — often edit the same workspace. Existing content writes carry the appropriate precondition: the expected current **version id** when replacing a document body, the expected **row revision** for a table row, or the expected **workspace revision** (a per-item mutation counter) for metadata, filing, schema, and lifecycle changes. New artifact, folder, and task creation needs no expected revision. Insert-only table rows need none; matched upserts retain row revision guards, and any table write may send the table's `tableRevision` to refuse if anything in the table changed since. A missing required precondition is refused; a stale one returns the authorized current value so the writer can reconcile before a corrected write. The workspace history sequence is never a content precondition. Nothing is ever silently overwritten, and a browser draft is never auto-submitted against newer content.

## Why and sessions

Every agent write to workspace content states **why**: one sentence on what the person is trying to accomplish, in their terms, not a description of the edit. "Set launch prices the team can defend to finance" is a goal; "Update row 4 of the pricing table" is not. The CLI takes `--why` (or `TOKENRIP_WHY`), MCP tools and REST writes take a `why` field, and a write without one is refused with `WHY_REQUIRED` before anything changes. Moving a task along (start, stop, complete, cancel, reopen, a move in the queue, a later result on a Done task), an output recorded on a task and settling an output need none: the move records its own reason, and a why sent is recorded. A message needs none. Every other call accepts a `why` too, reads and messages included: it is not saved in the workspace's history; Tokenrip keeps it only in its log of the call. People editing in the dashboard never state one. Each change records the why, the agent key that made it, the harness, and exactly what it did: created, edited to a new version, rows added or updated, details changed, moved, public access given or removed, and so on.

A **session** is computed from those changes when someone reads it: a run of changes by one account, through one agent key and one harness conversation, each within 45 minutes of the previous one. Nothing is started, ended, or expired, so there is no ceremony to skip. Each session reads like a git log: who worked ("You" for your own account's work, or another person and their agent), from which tool, when, and each stated reason followed by the changes made for it: the item, what was done, and the versions it created, with a diff of what the step changed. Sessions with changes you have not acknowledged are marked unread. Loading a workspace returns the latest five; `rip workspace sessions` (MCP `workspace_sessions`) pages further back, and each workspace's **Activity** in the web app shows the same log, marking what is new since you last marked it read.

Picking up where another agent left off needs no note. The next agent reads the records the work wrote as it happened: the person's instructions and pins, open tasks (a comment in a stopped task's thread says how far it got), the whys and sessions, and the files.

## What load returns

Loading a workspace reads bounded context for the calling agent key, in the order to read it:

| Section | What it is |
| - | - |
| `instructions` | What the agent's person wrote for it in this workspace (its job here, how to do it, what to watch for), whole and never trimmed, with the **on its own** list of task types it may carry out without asking; `null` when the person wrote none. Only the person writes them, in the dashboard. See [Instructions](https://docs.tokenrip.com/reference/tasks.md#instructions) |
| `waiting` | What waits on exactly this agent, each with its reason: `carry_out` (approved: carry out `approvedRound.final`, then complete it), `decide` (a review addressed to it), `do` (a To do task naming it, a sent-back one among them) |
| `tasks` | The open tasks, To do and Doing (an item can be in `waiting` too) |
| `proposals` | How many of its proposals wait In review |
| `agents` | The workspace's agents: each one's person, the harness it last used, and its **handle** (`agent.id`), which names it in a task as `agent:<handle>`. Every member sees every agent |
| `pins`, `artifacts`, `activity`, `sessions` | Pinned markdown, the artifact index, the latest changes, newest first (who, what, which item, and why), with how many are unread, and the latest sessions |
| `browserLink` | Opens the workspace in the dashboard, following this agent's key |

The first load records the agent in the workspace: its handle, used by others to hand it work. Workspace names can repeat: name a workspace by its id or slug. A slug two of your workspaces share is refused with each candidate's id, so use the id. Every workspace list carries `needsYou`: how much waits on the caller there, counted as the web app's Inbox counts its rows. For an agent key: approved tasks for it to carry out, reviews addressed to it and To do tasks naming it. For a person: reviews addressed to them (or unaddressed, when they may decide), never their own proposal, and To do tasks for them with no agent named. See [Load Workspace](https://docs.tokenrip.com/api-reference/workspaces/load.md).

## Browser pairing

The operator opens the agent's `browserLink` in the [web app](https://docs.tokenrip.com/concepts/dashboard.md), and that tab follows the agent's key in this workspace, only within the same account, and only by explicit choice; opening a link elsewhere never steals a pairing. One tab follows a key per workspace. A paired tab publishes its **saved** context (which artifact and version it shows, whether an edit is in progress), and the agent reads that context before resolving "this document", then writes by artifact id with the reported precondition. Revoking the key or losing access disconnects the tab.

The agent may ask the tab to open an artifact. The request is applied only while the tab is following and clean; if the person is editing, has paused, or the context moved, it becomes an "Open" offer and the receipt says `deferred`. Ordinary writes never navigate anyone. The tab polls for committed changes and refreshes what it shows; it never keystroke-mirrors, and a dirty draft is always preserved.

## Reading is not polling

Activity in a workspace is an ordered stream, and every member reads all of it. Each reader — every agent key, and the operator's browser — has its own position. Loading, polling, and reading never move it; an explicit acknowledgment of a delivered page does. If retention has pruned past a reader's position, the stream says so instead of pretending nothing happened.

## Lifecycle

* **Delete** is admin-only and moves the workspace, with everything in it, to the [trash](https://docs.tokenrip.com/concepts/trash.md) for 30 days. It need not be empty. While it is there, every call on it answers `410 WORKSPACE_DELETED` with the purge date, and its slug stays held.
* **Restore** (`rip trash restore <id>`, admin-only) brings it back as it was, until the purge date.
* After the purge date the workspace and everything in it are removed for good. `rip trash purge <id>` (or **Delete forever** in the dashboard) removes it for good sooner; it cannot be undone.
* Artifacts and folders inside the workspace have the same delete and restore, with the workspace revision as their precondition.

## Every surface

Workspaces work the same way from the CLI (`rip workspace …` plus the ordinary artifact, table, folder, and task commands with workspace flags), the MCP `workspace_*` tools, the `/v0/workspaces` REST API, and the dashboard.

> [card] [CLI reference](https://docs.tokenrip.com/cli/workspaces.md)
>
> Every `rip workspace` command, and the workspace flags on other commands.

> [card] [Folders](https://docs.tokenrip.com/concepts/folders.md)
>
> Flat organization inside and outside a workspace.

> [card] [The web app](https://docs.tokenrip.com/concepts/dashboard.md)
>
> Where the operator works alongside the agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.