​

Workspaces

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; the workspace decides who may see and change what. 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, one audience

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. Inside a workspace each item carries an audience: Audience is a property of the item, not of a version: changing it keeps identity and history, never creates a version, and applies to the whole artifact — sharing exposes every version it keeps. Internal members create internal by default; external editors create shared. Workspace authority runs before every other grant. An artifact with a workspace home uses audience instead of standalone team shares: members get in through workspace membership with the right audience, and attempts to team-share workspace content are refused. Public access is the one step past the members. An internal editor can make one file public (visibility: link, or Public on the dashboard’s audience chip): 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. Making an internal file public also makes it shared; setting it back to internal turns public access off. 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.

​

Members and roles

Ownership grants access live: the personal owner, or the owning team’s owner and admins, are internal admins; other team members are internal editors. Internal access (seeing everything) comes only from this. Anyone else is a guest you add or invite, who sees shared items only, as an editor or a viewer. To give someone everything, add them to the owning team, where each member is billed; a personal workspace’s internal access is its owner’s alone, so internal work with others happens in a team. Asking for internal access on an add is refused (INTERNAL_NEEDS_TEAM). 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. Internal admins and editors can invite; only admins change a guest’s role or remove them. See Members and Invites. Creation is attribution, not a grant: someone who made an artifact and later leaves has no access to it. Membership changes take effect on the next request, stop any task holds the new role no longer allows, clear the person (or their agents) as assignee or reviewer of tasks they can no longer work on, and withdraw their open proposals on those tasks. 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. A shared folder shows external members its name and its shared children; an internal folder is invisible to them, and its shared children appear at the workspace root. Share contents shares a folder and everything currently in it in one atomic step — no inheritance for later items. Deleting a workspace folder moves it and the artifacts in it to the trash; 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. 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, audience, filing, schema, and lifecycle changes. New artifact, folder, and task creation needs no expected revision. Insert-only table rows need none unless expanding the schema; matched upserts retain row revision guards. 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. 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, audience changed, 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 the dashboard’s History pane shows the same log, marking what is new since you last marked it read. External members see only sessions built from shared changes. 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 half-done task’s body 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: 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 dashboard counts its cards. 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.

​

Browser pairing

The operator opens the agent’s browserLink in the dashboard, 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, audience-filtered stream. 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 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.