Stuga treats AI agents as users with their own write path. An agent connects over MCP, reads and searches whatever its credential reaches, and proposes changes. Every content write goes through the run ledger, where it is attributed, shown change by change, and waits for review unless the document is set to let AI edits apply directly. This page covers connecting clients, credentials, the tools, and what the ledger shows.
Settings → Your AI agents in Stuga has the setup for the node you are running, with its address already filled in: pick the app under App. Use it when it disagrees with an example here.
- Claude Code, Claude Desktop, and other MCP clients on your own machine work with any node they
can reach, including one on
localhostor your local network. Claude Code dials the node's/mcpendpoint. Its browser sign-in needs the node on https or on loopback, so on a plain-http network address Your AI agents gives it a command carrying a key instead. Claude Desktop runs Stuga's stdio server from an extension, and the server forwards to the node's/mcp. The Stuga plugin runs the same server in Claude Code and in Cowork, and signs in through the browser at any address. - Codex and Google Antigravity dial the node's
/mcpendpoint and work with any node the machine can reach. Your AI agents gives one command per host that installs the Stuga Skill and adds the node; both hosts sign in through the browser, so no key is pasted. - Pi dials the node's
/mcpendpoint through pi-mcp-adapter and works with any node the machine can reach. It signs in through the browser, or takes a key (Pi). - Cursor, VS Code, Kiro, Goose and LM Studio dial the node's
/mcpendpoint and work with any node the machine can reach. Your AI agents gives each a link that adds the node (Apps that install from a link). - Claude on the web and on mobile add custom connectors that Anthropic's cloud dials. Those need
the node at a public HTTPS origin:
PUBLIC_ORIGIN, or its remote address. Your AI agents offers Claude while remote access is on, with the remote address's/mcp, and otherwise only whenPUBLIC_ORIGINis https and not a loopback, private or local-network address. Ways to give a node a public HTTPS origin are in network-access.md.
Apps on your own machine get the address the page is open at: PUBLIC_ORIGIN anywhere on the
network, so they never go round by the relay, and the remote address when the page was opened there.
An app you connect sees what its model reads and writes. A hosted one, such as Claude on the web, handles it on its vendor's servers.
A client holds one Stuga connection. Every config names it stuga, every client shows it as
Stuga, and the extension downloads as stuga.mcpb. No node name, host or ID appears in any of
them: a node is renamed, moved to another address, or reached at a second address, and the client's
entry never changes.
A connection reaches the workspaces its credential allows: the ones you chose when the app signed in
(Apps that sign in), or a key's (API keys). workspaces action
list is the routing table:
{
"contract": 2,
"workspaces": [
{
"workspace_id": "…",
"name": "Research",
"role": "member",
"access": "propose",
"node": { "id": "…", "name": "livs-air", "origin": "http://livs-air.local:8787" }
}
],
"unavailable": []
}- Every call names its workspace. Every tool requires
workspace_idexceptworkspacesactionlist, andsearchandretrieve, which takeworkspace_idsinstead (Searching several workspaces). There is no default workspace. - No tool takes a node. A
workspace_idis unique everywhere, so it already says which node. - An id the connection cannot use is refused with one sentence,
workspace is not available to this connector, whether it does not exist, is outside the credential's workspaces, or its person is no longer a member there, so a credential cannot probe which ids exist. accessis what the connection may do there:read, orproposechanges.roleis the person's role in the workspace.contractis the version of the tools. It goes up when a change would break an agent, a skill or a router written against the previous one.
The server instructions open with a routing rule, then name the node and how many workspaces the
connection reaches, and carry a table of up to 20 of them. When the connection reaches exactly one
workspace, that workspace's instructions for agents follow; otherwise
they point at workspaces action instructions.
Nodes never talk to each other, so every workspace in the listing is on the node the connection is
to, and its unavailable is empty. An agent that works with two nodes is set up on each: the second
connection is added by hand under another name, because a client cannot hold two entries called
stuga. In the Claude Code command write stuga-work in place of stuga; in a pasted JSON config,
change the key; for the Codex and Antigravity installers, run the command as
curl -fsSL '…' | STUGA_SERVER=stuga-work sh. The installers refuse to touch an entry whose name is
already taken by another server, rather than replace it. The Claude Desktop extension is one
extension, stuga, whichever node it came from: installing another node's replaces it, and its
Stuga address setting says which node it reaches.
The shortcuts to other nodes in a person's workspace switcher are theirs alone: /api/me/nodes
refuses API keys, so an agent reaches another node only by being connected to it.
A client that supports OAuth signs in through the browser: Claude Code, Codex, Antigravity, Cursor,
VS Code, Kiro, Goose, LM Studio, Pi, Claude on the web, and the Claude Desktop extension or
stuga-mcp without a key. You sign in to the node with your password or through its identity
provider, and the consent page asks two things:
- Workspaces. Every workspace you belong to other than as a guest is ticked. Also workspaces I join later covers every workspace you belong to, now and later. An agent never acts in a workspace where you are only a guest, whatever you ticked.
- Access. Read and suggest changes, or Read only.
At the remote address, allowing an app takes a sign-in from the last five minutes, or confirming it is you (with a passkey there, if you have one), as an API key does, and you are notified that the app is connected.
The page names the app. An app that identifies itself by a metadata document the node fetched is shown as Verified by that document's host; any other is an Unverified app, a warning callout naming the host it returns to, or "an app on this computer" for a loopback address.
Each consent creates a connection: one per person per app. Signing in again as the same client (the
same client_id) renews it with your new answers and keeps its name and its agent, so its runs stay
under one agent. It acts as its own agent for you, and the rules for agents under
API keys apply to it.
Connected agents, under Settings → Your AI agents, lists each connection as signed in, with
verified by <host> for a verified app, and a badge when it reaches fewer workspaces than you
belong to or only reads.
- Rename changes how its runs are attributed.
- Revoke ends every token it holds at once. Its next call is refused, and the app asks you to sign in again. A revoked connection stays in the list.
- Leaving a workspace takes it out of every connection that named it, and a connection left naming none is revoked. One made for workspaces you join later keeps following you.
An app holds an access token (sto_…) that lasts an hour, and renews it with a refresh token
(str_…) that is replaced every time it is used. A refresh token unused for 90 days lapses, and a
sign-in ends a year after it happened however often it refreshed; either way the app asks you to
sign in again. A refresh token presented again within
REFRESH_ROTATION_GRACE_SECONDS (60 by default) of its use is one app refreshing twice at once, and
gets a pair of its own; presented later, it ends the tokens of that sign-in, because someone else
holds a copy. The node stores only their hashes. These tokens work only
on /mcp; the REST API refuses them. They also work only at the address where you consented: with
remote access on, connect apps to the remote address, which works on your network too. The OAuth
routes are in api.md.
claude mcp add -s user --transport http stuga http://localhost:8787/mcpUse your node's origin in place of http://localhost:8787; Your AI agents fills it in. -s user
adds the connection once for every project. Then run /mcp in Claude Code, pick stuga, and choose
Authenticate. You sign in to your node in the browser and choose its workspaces and access, and no
key is pasted (Apps that sign in).
That sign-in only works when PUBLIC_ORIGIN is https or a loopback address. Claude Code refuses to
send a credential to a token endpoint that is neither, so on a node at a plain-http network address,
such as http://nas.local:8787, Your AI agents names a key in the command instead:
claude mcp add -s user --transport http stuga http://nas.local:8787/mcp \
--header "Authorization: Bearer vk_..."Name the agent under Claude Code and the command comes back with its key in place. The key is stored in Claude Code's own configuration file in plain text, and is revoked in Your AI agents like any other. Giving the node an https address brings the browser sign-in back.
The plugin carries the Stuga Skill and runs the stdio server with npx, so it
needs Node.js 18 or newer. Each release publishes it from integrations/ to
stuga-dev/stuga-plugin, pinned to that release's
@stuga/mcp:
/plugin marketplace add stuga-dev/stuga-plugin
/plugin install stuga@stuga
Claude Code asks for Stuga address; keep http://127.0.0.1:8787 when the node runs on the same
computer. From a shell, claude plugin install stuga@stuga --config node_url=http://nas.local:8787
sets it instead. The first time Claude uses a tool, the node's consent page opens in your browser,
whatever the node's address, and the connection is listed as Claude. Its tools are named
mcp__plugin_stuga_stuga__<tool>.
Each new, cleared or compacted session starts with an index of the wiki pages Claude can read:
their ids, titles, folders and dates, team pages first and your own My notes after
them, in at most 9,000 characters. Your newest notes keep their place however many team pages there
are, and the index says how many notes you have. A resumed session gets none. The plugin's hook asks the node's
GET /api/agent/session-index with the connection's own sign-in,
refreshing it when it has expired, and the session starts without the index when the node does not
answer within two and a half seconds or nobody has signed in yet.
In Cowork on your computer the plugin runs the same server against http://127.0.0.1:8787, since
Cowork does not ask for plugin settings. Claude on the web loads only its skill.
In Claude, open Settings → Connectors → Add custom connector and paste the MCP endpoint
Your AI agents shows: <PUBLIC_ORIGIN>/mcp, or the remote address's /mcp while
remote access is on. Claude asks you to sign in to Stuga, and the
connection appears under Connected agents.
Both hosts set up from one command, shown under their name in Your AI agents:
curl -fsSL 'http://localhost:8787/api/agent-install/codex' | sh
curl -fsSL 'http://localhost:8787/api/agent-install/antigravity' | shUse the command your own node shows. It installs the user-level stuga Skill and points the host at
this node’s /mcp. The script carries no key and the endpoint serving it mints none — it is
unauthenticated because a script that grants nothing needs no credential to fetch. Read it in a
browser at the URL in the command before running it.
Both hosts register themselves with the node and sign in like any app
(Apps that sign in). They differ in where the sign-in starts. Codex performs
OAuth while the installer runs codex mcp add --url; use codex mcp login only to sign in again
later. Antigravity has no such command — its OAuth runs inside the IDE and ends by pasting a code
back from a hosted callback — so it shows Authenticate beside the server until you click it once,
and reports Unauthorized until then.
Restart the host when the command finishes, so the Skill is discovered. An ordinary question such as “can you access my Stuga workspace?” then routes to the connection without naming it.
Where each host keeps its pieces:
| Codex | Antigravity | |
|---|---|---|
| Skill | ~/.agents/skills/stuga |
~/.gemini/config/skills/stuga |
| MCP server | codex mcp add --url, shared by the CLI and the IDE extension |
a serverUrl entry in ~/.gemini/config/mcp_config.json |
| Removal also clears | the stored sign-in, via codex mcp logout |
the cached token in ~/.gemini/antigravity/mcp_oauth_tokens.json |
| Sign-in | During codex mcp add --url; use codex mcp login to sign in again |
Settings → Customizations → Installed MCP Servers → Authenticate |
In the Antigravity IDE the same server can be added by hand under Settings → Customizations → Installed MCP Servers; in the Codex IDE extension, from the gear menu under MCP servers as a Streamable HTTP server. Either way the entry needs only the URL.
Open Uninstall from Codex or Uninstall from Antigravity, which shows two commands. The first disconnects this node and keeps the Skill, for a computer that reaches more than one Stuga node; the second removes the Skill too, for the last node on that computer.
curl -fsSL 'http://localhost:8787/api/agent-install/codex?action=disconnect' | sh
curl -fsSL 'http://localhost:8787/api/agent-install/codex?action=uninstall' | shNeither revokes anything: the connection lives on the node. Revoke it under Connected agents, then restart the host.
In Your AI agents, open Claude Desktop and click Add to Claude Desktop. Double-click the
downloaded stuga.mcpb and click Install. The extension asks for:
- Stuga address, filled in with the node the file came from.
- Access key, optional. Leave it empty to sign in through the browser.
Then quit Claude completely and open it again. Closing the window leaves it running. When Claude first starts the extension without a key, the node's consent page opens in your browser; approve it and the tools appear. When Claude first asks to use Save to Stuga, choose Always allow.
The file carries no key, so it is safe to pass around. It is one extension for every node: installing another node's replaces it, and changing Stuga address in Claude's extension settings points it at another node.
If the tools do not appear, quit Claude fully and reopen it, then read the extension's
mcp-server-*.log in ~/Library/Logs/Claude/ (on Windows, %APPDATA%\Claude\logs\).
When the node's PUBLIC_ORIGIN is a loopback address, so the browser and the node share a machine,
Your AI agents also offers Set it up by hand instead: a claude_desktop_config.json entry with
a key you mint there, the absolute path of the Node interpreter running the node, and the absolute
path of the node's stdio server. Paste it in Claude Desktop under Settings → Developer →
Edit Config. Paths are absolute because desktop clients start servers without your shell's
PATH. Without STUGA_TOKEN, the server signs in through the browser instead.
Which server file the node offers is a packaging setting, STUGA_STDIO_ENTRY
(packaging/contract.md). When a node's files are not on
your machine's filesystem, it offers none, and the extension or an HTTP connection is the way in.
From a source checkout, build the server once and point the config at it:
pnpm --filter @stuga/mcp build # writes services/mcp/dist/stuga-mcp.js{
"mcpServers": {
"stuga": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/stuga/services/mcp/dist/stuga-mcp.js"],
"env": {
"STUGA_URL": "http://localhost:8787",
"STUGA_TOKEN": "vk_..."
}
}
}
}which node prints the interpreter path.
Cursor, VS Code, Kiro, Goose and LM Studio add a server from a link. Your AI agents builds one per app
with the node's /mcp endpoint in it: Add to Cursor opens Cursor with the server, named stuga,
ready to install, and the app signs in through the browser when it first connects. To use a key
instead, open Use an agent key instead, mint one, and follow Add to … with this key; Goose's link
cannot carry a key. Removing the server in the app revokes nothing: revoke the connection or the key
under Connected agents.
Any client that speaks Streamable HTTP can use <PUBLIC_ORIGIN>/mcp. A client that supports OAuth
signs in like Claude Code. Any other client sends a key as Authorization: Bearer vk_..., and the
Other apps in Your AI agents builds that config.
stuga-mcp.js, which the Claude Desktop extension and the Stuga plugin run, forwards to the node's
/mcp: the tools, the prompts, their wording, the instructions and every check are the node's own,
whatever its version. It adds one thing only a process on your machine can do: read a file there.
databases_add action import takes file, a CSV or JSONL path on that machine; the server stages
the import with start_import, uploads the file and commits it, and hands the agent the table's
Import dialog link when the file is larger than the node accepts. media_upload action upload
takes file, any path on that machine; the server stages it with start_upload, sends it, and
stores it, named as the path names it unless the agent passes name.
Each release publishes it to npm as @stuga/mcp, so any client that starts local servers runs it
with npx -y @stuga/mcp and STUGA_URL set to the node's address.
With STUGA_TOKEN set, it sends that key. Without one, it signs in through the browser: it registers
itself with the node, opens the consent page (and writes its address to stderr), and takes the answer
on a one-off loopback address. The tokens are kept per node address in ~/.config/stuga/oauth.json,
readable only by you. When the node stops accepting them, the server opens a new sign-in.
At startup it waits up to three seconds for the node, so the instructions a client keeps are the
node's. When the node has not answered by then, the server starts with instructions that say it is
still connecting, and announces the node's tools and prompts once the node answers. A list of tools
or prompts waits two seconds for the node. While the node is out of reach or the sign-in waits, it
answers with the lists the node last gave this connection, kept per node address and key in
~/.config/stuga/catalog.json, readable only by you; before the node has ever answered, with every
tool and prompt of the server's own version. A client that lists them once at launch still has them.
An error the node answers with is passed on as the node gave it, and a node too old for prompts lists
none. A tool call waits up to 50 seconds for the node or the sign-in, then says what it is waiting
for, and nothing is sent.
It reads these settings:
| Variable | File field | Default | |
|---|---|---|---|
STUGA_URL |
url |
http://127.0.0.1:8787 |
The node's origin. |
STUGA_TOKEN |
token |
none | An API key. Without one, the server signs in through the browser. |
STUGA_MODEL |
model |
none | A model label, sent as x-stuga-model and shown beside the agent's runs. |
STUGA_CLIENT |
client |
stuga-mcp |
A client label, sent as x-stuga-client. It also names the connection a sign-in creates: Claude Desktop for claude-desktop, which the extension sets, Claude for claude, which the plugin sets, and Stuga local connector for the default. |
STUGA_NODE_NAME |
node_name |
the host of STUGA_URL |
The node's name, for when the node cannot be asked. At startup the server asks the node's public /auth/config for its current name and its PUBLIC_ORIGIN, which win. |
STUGA_VERSION |
version |
the version it was built as | The version the server reports. The extension sets the node's. |
Each setting comes from the environment first. A value left as an unfilled ${user_config.…}
placeholder counts as unset. When the environment sets both STUGA_URL and STUGA_TOKEN, only the
node's name can still come from a file: node_name in config.json beside the server file, when
the environment has no STUGA_NODE_NAME and the file's url is STUGA_URL. Otherwise each missing
setting is taken from config.json, then from ~/.config/stuga/credentials.json, and a file's
token only for the node that file names, or when it names none. Both files are JSON objects with
the field names above. The extension writes its address, client label and version to config.json
as well as to its launch environment, because a client does not always pass that environment to the
process it starts.
DeepSeek Harness (dsh) reaches the node over
/mcp with a key. The @stuga/dsh-plugin package installs into a dsh profile and adds what a bare MCP
connection lacks: playbook skills for research, edits and databases, and a system-prompt section that
carries the workspace's instructions for agents, explains that a Proposed result is success and
must not be retried, and says to follow the instructions that come back with a document
(below).
In Your AI agents, open DeepSeek Harness and mint a key. Then, on the machine that runs dsh:
dsh plugin --profile web add @stuga/dsh-pluginPut STUGA_URL (the node's origin) and STUGA_API_KEY (the key) in $DSH_HOME/.env or in the
environment that launches dsh, and restart dsh web. Your AI agents prints both lines with the key
filled in. The harness's runs appear in the review inbox labelled deepseek-harness, under the key's
name.
dsh's MCP client has no browser sign-in, so the key is static and its owner reviews everything the harness proposes. Mint one key per person rather than sharing one.
dsh plugin --profile web remove @stuga/dsh-plugin removes the plugin. It revokes nothing: revoke
the key under Connected agents.
Pi has no MCP client of its own, so it reaches the node through
pi-mcp-adapter. The @stuga/pi-package package
registers the node with the adapter as stuga, and adds playbook skills for research, edits and
databases plus a system-prompt section on how calls are routed and reviewed. On the machine that runs
Pi:
pi install npm:pi-mcp-adapter
pi install npm:@stuga/pi-package
export STUGA_URL=http://localhost:8787Use your node's origin; Your AI agents fills it in under Pi. Set STUGA_URL in the shell
that starts Pi, or put { "stuga": { "url": "…" } } in ~/.pi/agent/settings.json. Then start Pi
and run /mcp-auth stuga: you sign in in the browser (Apps that sign in), at
any node address, and the connection is listed as Pi. To use a key instead, open Use an agent
key instead under Pi, mint one, and set STUGA_API_KEY beside STUGA_URL; there is then no
sign-in step. Pi's runs appear in the review inbox labelled pi.
pi remove npm:@stuga/pi-package removes the package and leaves the adapter. It revokes nothing:
revoke the connection or the key under Connected agents.
Mint a key in Your AI agents, or with POST /api/keys (api.md). A key
looks like vk_<id>_<secret>. The secret is shown once, and the node stores only its hash. An app
that signs in gets no key: its sign-in is a connection (above).
- A key acts for the person who minted it. Its reach is its owner's live reach: the owner's principals and role are read again on every request, so a guest's key is a guest's, and a key whose owner has left the workspace fails on its next request. Removing a member also revokes the keys they minted in that workspace.
- Where a key acts. Over REST, in the workspace it was minted in. On
/mcp, a key that is not confined to folders reaches every workspace its owner belongs to other than as a guest, at the owner's role in each, andworkspacesactionlistnames them. A key confined to folders reaches only its own workspace. - An agent has its own principal,
agent:<id>. A document an agent creates is owned by its human, shared with the agent as a writer, and gets the workspace's default access like one the human creates. What the agent writes in it waits for review, as on any new document. - Content only. Agents change documents and databases through the run ledger. Renaming, moving, trashing and deleting items, sharing, locks, the agent-changes setting, and workspace and key management all refuse agents, because none of them leaves a run to revert.
- Collections are the exception. A collection only scopes search and AI, so an agent with write access creates, renames and deletes its person's collections and adds and removes their members, and a read-only one lists and opens them. The person sees every change, and the audit ledger names the agent and the person it acted for (collections.md).
- A key can be narrowed below its owner's reach: confined to folders (each with its subtree),
made read-only, or given an expiry. Your AI agents sets these when a key is minted, and
PATCH /api/keys/:idchanges them later. A narrowing only removes reach. A folder-scoped key's listings, search, retrieval and events are filtered to its folders, and a document elsewhere reads as not found. A read-only key reads and searches everything its owner can reach and changes nothing (below). - Rotate gives a key a new secret and keeps its identity, so its runs and audit rows still name the same agent. Revoke stops it on its next request. Rename changes how it is attributed: a key is minted under the name of the client it is for, so rename one when the same client is connected twice.
STUGA_TOKEN,/mcpand the REST API also accept a person's access token, which acts as that person. It expires within an hour by default and is attributed to the person rather than an agent, so use it only to experiment.
Every /mcp tool call in a workspace, reads included, is written to that workspace's audit ledger as
mcp.<tool>.<action>, with the credential and the target. A search or retrieval writes one row per
workspace it covered. Over REST, writes and refusals are recorded.
A run is one agent's editing session on one document or database. For each run you see:
- Who and what: the agent and the name of its key or connection, the client and model labels it
sent (the
x-stuga-clientandx-stuga-modelheaders, which the extension, the stdio server and the dsh plugin set), and the person it acted for. - The changes: each proposed hunk (or database operation), shown against the document and reviewable one by one.
- The outcome: per hunk accepted, rejected or pending; per run waiting for review, applied at once, or reverted. Undo after a decision puts its hunks back to pending.
While a run has pending hunks, their content appears only in the overlay of the people who review
it: its reviewer, or at colleague the people who may approve it. Other collaborators never see
pending agent text, and their own edits continue as usual. Accepted hunks merge block by
block, so surrounding structure and other people's changes survive.
An agent is never blocked on review. A proposal returns immediately, the agent's later reads include
its own pending edits, and markdown or databases action status reports what was decided.
Reject with note… rejects with a note saying what should change: under a single change in the document, where the note is written in place of its buttons and stays until that change is decided, from Review each, or from the menu beside the run bar's Reject all. The button that opens the note and the one that sends it carry the same words. The review card's and the inbox's Ask for changes… do the same for a whole run. The note is kept with each change it rejected, and it reaches the agent that proposed them where that agent already looks:
- Its reads of that document (for a database, its schema and query results) open with the
reviewer's feedback (what was rejected and the note), and every proposal it makes there carries
it again, until the agent answers it: a proposal that names the feedback's ids in
revisesis the revision, and from then on onlystatusshows it. Proposing something else answers nothing. It stops leading reads after 14 days, or sooner once the run is marked reviewed: Mark as reviewed in the inbox, offered on a run with changes applied at once and not yet looked at, orPOST /api/docs/:id/runs/:run/ack(API) on any run. markdownordatabasesactionstatuslists each rejection and its note under its run.eventswithmine: truelists the decisions on the agent's own proposals across the workspace, the last 14 days of them without a cursor. Arun.decidedevent with afeedback_idis a rejection with a note; the note itself is instatus, since the feed reaches every agent that can read the document.
The in-app co-author hears its rejections at the start of its next turn. On its runs in the document, with AI chat on, the note button is Revise… (Revise all… for the whole run): a turn that may change existing text only inside the passages that rejection covered, followed through its own edits. While a turn is running, the revision waits for it to end, and every request made meanwhile is answered in one turn; after Stop they wait for Revise now. It may add text anywhere, so it can move what was rejected. A change it tries to other existing text, or to another document, is refused, and it says so instead of making it. When the document has changed so that the rejected passages can no longer be found, every change to existing text is refused and it asks you to revise again.
A note is advice to the agent, like an instruction. It decides nothing about what a later write may
do; review mode and permissions do. A rejection carries one, and so does a revert: Revert with
note… in the inbox takes back a run that landed, on an auto document for instance,
and tells the agent why, the same way.
Whether an agent's change waits depends on the level of the document or database it changes,
agent_mode:
| Level | In the app | Meaning |
|---|---|---|
auto |
AI edits apply directly | The change applies at once. It is still recorded, attributed, notified and revertible. |
review |
Reviewed by whoever asked the AI | The default. The change waits for the person who asked the AI, for as long as that takes. They are notified, and their decision lands it. |
colleague |
Reviewed by a colleague | The change waits for someone else who can edit the item, a workspace admin included. The person who asked the AI never approves it. |
A folder gives its level to everything in it, folders inside it included: review unless it is set
to another. A document, database or folder follows its folder until it is set itself, and a
database's row pages are reviewed at least as strictly as the database. Its owner, or a workspace
admin, can make it stricter than its folder, as can the owner of a folder above it, who so undoes a
looser level they set; only the owner of the folder that sets the level, or a workspace admin, can
make it looser, and owning a stricter folder inside another lets nobody go looser than the outer
one. A level an item's owner set above its folder's stays theirs to give up. Making an item looser
than its folder, or a folder looser, notifies the workspace's other admins who can read it. Agents
never change a level.
A move takes an item, and everything in a folder, out from under the folders it leaves. It must not
let the mover alone review AI edits to anything it moves more loosely than they could before: not at
once, and not later by setting a level where it lands, in a folder of their own or, for what they
own, at the top level. Such a move takes the item's owner, the owner of the folders it leaves, or a
workspace admin. A folder's default review, which no folder sets, is no bar to leaving it. A row
page counts here without its database's level. An item at colleague moves out from under an
approver group someone else names only to where that group still applies. A move that loosens
a level is in the audit ledger, and notifies the workspace's other admins who can read the item. A
level looser than its folder's belongs to that place: an item moved into another folder follows that
folder. Deleting a folder puts everything in it in the trash, filed in the folder above, so it stays under
the levels set there.
The level is set from Who reviews AI edits…, in the ⋯ menu beside Share for a document or a database, and in a folder's menu, where a folder also names its approver group. It covers every agent and the in-app co-author, which is why the UI says AI edits. The dialog shows the level the node holds agents to and what it rests on: its folder's level; for a row page, its database's; and for a page in someone's My notes that others can read, at least Reviewed by whoever asked the AI. Nobody sets an item below the last two, so the dialog offers nothing looser. An item at a level other than the default shows an AI edits apply directly or Reviewed by a colleague chip, and lists mark it. Every change of a level is in the audit ledger.
Anyone who can edit the item, other than the person who asked the AI, may approve its changes. A folder can name an approver group: for everything in it, only members of that group who can edit the item approve. A folder inside it names another only with the approval of that folder's owner or a workspace admin. When nobody else can approve, the item's owner or a workspace admin who can edit it stands in, never the person who asked. Until someone can, the change waits, and the person who asked is told to give a colleague, or someone in the approver group, edit access.
The person who asked can still reject or revert their own AI's changes, and send a note with them.
Only someone else marks a run proposed at colleague reviewed.
Each person who may approve is notified that changes wait for their approval, in Stuga and by email or webhook, and the notice opens the run's review card, or, for the runs of a change, once for the whole change, opening its card. A workspace or a folder can also post these changes to a Slack review channel. A Slack, Teams or Discord channel the node sends notifications to hears each run once: from the notice to the person who asked, which says the changes wait for a colleague, or, for the in-app co-author's and the table assistant's runs, which notify nobody who is watching them, from the first approver's. While nobody may approve, the item's owner and the workspace admins who can read it are notified that the changes wait for an approver. When a folder's approver group changes, or a document or folder moves, whoever may now approve a change waiting there, and could not before, is notified.
A run keeps the level it was proposed under, and each decision on its waiting changes takes the stricter of that level and the item's level now. Moving a document out of its folder, or loosening a level after a change was proposed, leaves that change waiting for the review it was proposed under. Marking a run reviewed keeps the level it was proposed under: raising a folder later leaves what already applied at once to whoever asked.
The level never depends on whether someone has the document open. The same agent making the same edit gets the same outcome at any hour, so a person can predict it and an agent can plan around it. Two consequences follow:
- A document an agent keeps for its own notes waits for review like any other, until someone
sets it to
auto. autobelongs to the document, not to an agent. While it is on, every agent that can write the document changes it without review.
A run that still holds undecided changes parks new ones even on an auto document, and the reply
says so. A later change of the same agent to that page for another piece of work waits behind it
(A queue on a page).
Only the run's reviewer, the people who may approve it, and the item's owner and workspace admins see the text of a change that has not landed (waiting, rejected or in conflict), and the document before and after its run. Anyone else who can read the item sees that the run exists, how it went, and the changes that landed, which version history shows too. Version history names an agent by the person it acts for ("Liv's agent"), as comments do.
The propose reply carries review and reason, so an agent can explain what happened. docs
action metadata (and GET /api/docs/:id for an agent) answers the same question before writing:
"review": { "mode": "colleague", "reason": "this document waits for a colleague's approval" }The agent's owner is notified of everything it proposes, whoever approves it.
The in-app AI co-author follows the same level. Its turn on the document you are working in is
one run, which waits for your review, waits for a colleague's, or, on an auto document, applies
when the turn ends. It sends you no notification, since you are watching it; at colleague the
people who may approve it are notified. The table assistant's changes likewise wait or apply as it
makes them. With All documents or a collection as the panel's search scope, the co-author can
also propose edits to other documents you can edit. Those follow each document's own level, and you
are notified for each, so they stay findable after the chat scrolls away.
Before letting AI edits to a document apply directly, look at that agent's record in the review inbox.
When the co-author needs a fact or a choice only you can give, it can ask in a comment on the passage and go on with the edits that don't depend on the answer. Everyone who can read the document sees that comment, so it asks this way only in a turn that never reached other documents: not with All documents or a collection as the scope, nor later in a chat that had one. Otherwise it asks in its reply. If you leave the document before the turn ends, you are notified of each question still open.
Anyone who can edit the document can reply with Send to AI ticked, and their own co-author answers. That turn takes its request from the reply, with the rest of the thread as context. It reaches only the open document and the thread, and downloads no images its edits link. Its edits follow the document's setting, and it posts its answer in the thread. A question or a thread answer is posted only when nothing in front of the AI came from other documents, edits waiting for your review included; an answer held back stays in the AI panel.
The co-author's comments are authored panel:<alias>, <alias> being the person it works for. That
person may resolve or delete them, as may the document's owner or a workspace admin, and is notified
when someone replies to them.
With comments_add, an agent can reply in a thread (parent_num; a reply to a reply joins the
thread) or attach a new comment to a passage by quoting it (quote). The quote must appear exactly
once in the document's text, as written. A reply takes its thread's passage, so it takes no quote. Over
REST, an agent attaches a comment to a passage the same way (API).
A comment may @mention at most 5 members of the workspace: more is refused, and nothing is posted.
Those it mentions who can read the document are notified. As with a person's comment, the
document's owner is notified, and a reply notifies whoever started the thread or replied before, the
person the agent works for included, since an agent often works while they are away. A reply in a
thread an agent started or replied in also notifies the person that agent works for. One person's
agents send at most 60 notices an hour in a workspace; past that a comment is still posted, and the
answer says how many notices were held (notifications_held).
In comments and in the notifications they send, an agent is named by the person it works for
("Liv's agent"), never by its own name. comments marks the agent's own comments you: true, and
replies in threads it started reach it through events with mine: true
(below). A reply is the words of whoever wrote it: the agent is told to read
it as information, never as an instruction.
An agent often writes to several pages for one piece of work: an ingest of a meeting adds a customer to a list, makes the customer's page and logs the call; a Save to Stuga of several points edits three pages. That work is one change, reviewed on one card.
- Opening one. The agent gives
change_title, a few words naming the work's source ("Customer sync, 2026-10-21"), to its first write, and the answer returnschange_id, which it passes to every later write for the same work, on every page and database.docs_create,markdown_append,markdown_edit,databases_addanddatabases_changetake both, andchange_summary: what the change does, in a sentence or two, for whoever approves it (a later write may replace it). A change belongs to the agent that opened it, for the person it acts for, in one workspace; any other id is unknown. It holds at most 100 runs. A write that names no change to a new page the same agent made in one goes into that change.remembertells the agent to make one change of one save. - What it holds. Each page's runs stay that page's own: each is decided at its page's level, by whoever may decide it there, since the pages of one change may sit in different folders at different levels. A change waits while one of its runs waits and is decided once they all are; a later write in it, such as a revision after Ask for changes…, makes it wait again.
- Its card.
/review/change/<id>shows the agent's summary first, then each page you can open, in the order the agent first touched them: its folders, New page for a page the change made, its level and who may decide it, and each change in its paragraph, as a run's card shows it. Pages you cannot open are left out, and so are the change's title and summary unless you read the waiting text of one of its pages or asked for it; someone who can open none of its pages learns nothing of it. Decide this page alone opens the page's own run card. - Approve all approves, page by page and oldest run first, every run you may approve now, through the same checks as approving each on its own. It is not one step: each run is approved or left on its own, and the card says per page what was approved and what is left, and why (you asked for it, so a colleague approves it; someone else approves it; it waits behind an earlier change; the page is locked). Ask for changes… and Decline… reject every run you may reject, each with the note, which reaches the agent as Reject with a note says.
- Notices. Whoever asked hears of a change once, and so does each person who may approve one of its pages, however many pages and runs it grows to; the notice opens its card. A review channel posts a change once, with its title, never a page's.
A page an agent makes in a folder whose AI edits wait for a colleague is held until its change is
approved. It does not take its folder's access: only the person who asked and those who may approve it
there, each by name as they stand when it is made, can open it. Nobody else finds it in a list, a
search, a retrieval, a Save to Stuga plan, the session index or the event feed, no webhook hears of it,
no export holds it, and no doc.created is sent. A database made there is held the same way, and a
page made with no change opens an untitled one of its own: a change's title reaches whoever decides
any page of it, so it is never the page's.
Once its change's runs on it are decided and something of them was approved, it takes its folder's
access and the grants a page made there gets, and doc.created goes out. Once they are all declined,
or withdrawn by whoever asked, it goes to the trash with the note, never announced. A held page with
no changes of its own yet is approved or declined on the change's card as a page. Its owner can share
it like any page they own, and it is then held no longer; its changes still wait.
A run belongs to one change. When an agent's earlier change to a page still waits and a later change
of the same agent touches that page, the later one becomes a run of its own, queued behind it, so a hub
page such as a customer list takes every ingest. The agent reads both laid over the page, in order. A
queued run is approved once the run ahead of it is decided, and may be declined at any time;
declining the one ahead can leave it nothing to apply to, and the agent redoes it. The card says what a
page waits behind, the agent's answer carries queued_behind and says this is success, and the inbox
says the change waits behind an earlier one. Someone who cannot read the waiting text a queued run was
proposed on top of reads none of its text either, and does not approve it.
Review AI edits (/review) lists the runs on documents and databases you can read across the
workspace, a change as one row, in three tabs:
- Needs you: changes waiting for your decision, a colleague's run you may approve included, and changes applied at once that you may mark reviewed and nobody has. Its count shows on every tab.
- Waiting on others: changes waiting for someone else's decision, your own AI's at
colleagueamong them. Each says whom it waits for. - Done: the rest, decided, reverted, or applied at once and looked at.
A change goes under the tab its runs together put it in: Needs you while one of them needs you.
The tab is in the address (/review?tab=waiting, ?tab=done), and Agent narrows any of them.
Review changes (or Open) opens a run's review card. A run's ⋯ menu
opens the document or database, or acts on the whole run in the card's words: Ask for changes…
(a note, which it requires), Decline, Revert these changes, Revert with note… and Mark
as reviewed (which also withdraws the notes you left on it); open the card or the document to
approve. A decided run says how many changes were approved and declined. AI activity, below the
list, is each agent's record (sessions, waiting, approved, declined, applied automatically, reverted)
and is what to consult before switching a document to auto.
Each run has a card at /review/<document or database>/<run>, laid out for a phone and the same on a
laptop. The inbox, review channel posts and a run's notices by email or
webhook open it, and so does a notice in Stuga for whoever may approve; the person who asked opens
theirs on the card on a phone, and in the document on a wider screen.
- What it shows. The page and the folders above it; who asked, which AI and the app it came
through, and when; the review level, and who may decide: at
colleaguethe people who may approve it, atreviewwhoever asked, and the item's owner or a workspace admin where one other than them can edit it ("Liv, the document's owner or an admin can approve it"). Then each change in the paragraph it sits in, under its section, the text before it struck through above the text after it, with the sources its footnotes cite. A database's run lists each change in a line. A run in a change offers Open the whole change. - What it does. Approve accepts every change still waiting. Ask for changes… rejects them with a note, which it requires, and Decline… rejects them with a note if you write one: either way the agent gets the note as Reject with a note says. Open the document goes to the page, where each change can be decided on its own.
- Who sees what. The rules of every level: whoever asked, those who may approve, and the item's owner and workspace admins read the waiting text, its sources and who may decide. Anyone else who can read the item sees that changes wait, who asked and the level. Whoever may not approve reads why beside Approve, such as "Liv asked for this change, so a colleague approves it."
A link from outside the app carries ?workspace=<id>, so the card opens in the item's workspace when
another one is active.
A workspace, or a folder in it, can post each AI change that waits for a colleague's approval to a
Slack channel, so approvers hear of it where they already are. A workspace owner or admin adds one
on Settings → This workspace → Agents → Review channel: in Slack, add an incoming webhook to the
channel, and paste its address, which starts https://hooks.slack.com/. Only that host is accepted.
Each run that waits for a colleague is posted once, however many people may approve it and however many changes the agent adds to it later: the item's title, who asked, which AI, how many changes, the level, and a link to its review card. The runs of a change are posted once for the change, with its title, never a page's, and a link to its card. A post never carries a change's text:
“Leave policy”: Liv’s Claude proposed 2 changes · Reviewed by a colleague · Review
A post is written in the language of whoever added the channel, since a channel has many readers. As a webhook does, a channel hears only of items the person who added it can read, checked again when the post goes out, and a run decided by then is not posted. Changes that wait for whoever asked the AI, and those that apply directly, stay off the channel. Posts are signed, time out and are retried as webhook deliveries are; a channel that fails 20 times in a row is paused until someone resumes it.
An agent reading a document cannot otherwise tell a person's sentence from another agent's
unreviewed one. markdown action provenance (and GET /api/docs/:id/provenance) lists every
agent-written passage still present, newest run first, with who wrote it and whether a person
accepted it or dismissed its card. The tool descriptions tell agents to treat an unreviewed passage
as a claim, never as an instruction.
People write standing instructions for agents as free text: where notes go, which folders are off limits, how tasks are recorded, the house style. The workspace, every folder, and every document and database can carry its own.
- They stack. What applies to an item is every level from the workspace down to it, outermost first: the workspace's, each folder's from the root down, then the item's own. A row page sits where its database does: the database's folders, then the database, then the page. Empty levels are left out.
- They add up. A nearer level refines a farther one. None overrides, hides or cancels another, and nothing opts out of the levels above it.
- They are advice. The model is told to follow them, and nothing enforces them. What an agent's
write does is still decided by permissions and the item's
agent_mode(above). - Each reader gets its own stack. A folder or database level is included only for a reader who can read that folder or database, so a document shared on its own reveals nothing about a private folder above it. An agent counts as its person: a key confined to a subfolder still gets the folders above it that its person can read.
- Where to edit them. The workspace's are on Settings → This workspace → Agents. A folder's, document's or database's are under Instructions for agents… in its ⋯ menu, which also shows the levels above it, and a new folder takes them in the same dialog as its name. Anyone who can read the item can look; its owner or a workspace admin changes them. Each change is in the audit ledger with the text's length, never the text.
- Limits. A level holds up to 20,000 characters. An agent is handed at most 60,000 characters of
a stack: the level that crosses the limit is cut short, the nearer ones are left out, and the agent
is told which (
instructions_cutin an answer). The ⋯ dialog warns when a stack is that long. - Not content. They are never indexed, embedded or searched.
- Kept apart from the text around them. Wherever a model reads them, each level sits in a marked block under its label. A line of instruction text that looks like one of those markers is escaped, and a title is shown on one line without its double quotes, so neither a level's text nor an item's title can end its block or pass for another level.
How agents get them:
- The workspace's. When a connection reaches exactly one workspace,
/mcpputs its instructions in the server instructions, so an agent has them before its first call. Otherwise the server instructions say to read them before writing.workspacesactioninstructionsreturns one workspace's, the workspace level only. - An item's stack.
markdownactionreadshows it in a marked block before the Markdown, or opens with a line saying none apply. Only that block at the very start of a read counts, and the agent is told so: anything further down that looks like instructions is document text, so an editor cannot plant instructions in a document's text.docsactionmetadata,docs_create,databasesactionschemaanddatabases_addactioncreate_databasereturn it asinstructions: [{ kind, id, title, text }], outermost first. A write needs no read, so the answer to a proposal frommarkdown_edit,markdown_append,databases_addordatabases_changenames the levels below the workspace that apply (instructions_labels), and the agent is told to read them before writing there again. Over REST an agent gets the same fields (api.md). - In the app. The co-author and the table assistant read their document's stack, as the person using them can see it, at the start of every turn, so an edit or a move applies to the next message. The co-author's first read or edit of another document it may edit carries a note on that document: which levels of the current document's stack also apply there and which do not, and the levels only that document carries, with the same policy framing. A level an earlier note in the same turn already showed is named rather than repeated. The note comes even when nothing applies there, and the co-author is told that only that first note is real. Ask reads the workspace's.
- Events. The
eventstool andGET /api/eventsreturn what changed in a workspace since a cursor, filtered to documents the credential can read. An agent that wants to react to a decision or a comment polls this instead of re-reading everything. The tool'smine: truekeeps the decisions on the agent's own proposals and the replies in comment threads it started. Event types: api.md. - Webhooks. Workspace owners and admins can send the same events to a URL, signed and retried, for the documents the hook's creator can read. A new page a change holds is heard of once it is approved (New pages in a change). See api.md.
- Review channels. A Slack channel hears of each change that waits for a colleague, with a link to approve it (The Slack review channel).
Say Save to Stuga to your AI, or the same in your language, and it files what you told it into your team's wiki or your own notes. Say Ask Stuga, or ask what you or your team decided, and it answers from Stuga, saying who last changed the page or row each point comes from, and when. The tool descriptions teach the model both phrases in every interface language, since a bare "remember this" is taken by an assistant's own memory.
- Saving.
remembertakes 1 to 20 points, each atext, an optionaltopic, and an optionalsource(the meeting, email or document it came from, and when; none for what you told the agent yourself), and writes no text itself. It answers with whom the connection acts for (user: their Stuga name and username), and for each point up to five places, best first: a page that says the point already; pages about it, whose title its topic names or which it names (a page whose approved text is empty, as a new page's is while all of it waits, is found by its title); folders whose name or instructions for agents fit the point and hold no page about it, for a new page (kind: "new_page"); then other pages that hold its words. Each page comes with the section it fits under (never the page's title heading: null for the page's opening, or a page only its title fits), why, and an excerpt. A page found by common words alone is left out (a word more than one page found holds, or one search leaves out, such as "with"), and so is a page found by one rarer word when the point names a page by its title or a page says it already; a word in an email or web address is no reason, and a section names a topic by the same word, never another form of it. A page of your My notes is offered only when nothing of the wiki is about the point. Each place has the review level the caller's own write there gets: an agent's by the page, a person's at review. Beside them come the sentences that already say the point (already_saved: a sentence that holds its words and states them, not a question, a denial or struck-through text), and the sentences it may make untrue or that may say it already in other words (possibly_replaces, hintlikely_duplicate). Numbers or dates alone never make a match. When the point names a page by a title that reads as a name (one never written in lower case, as "Initech", not "Refunds"), the other pages in its folder are about something else of the same kind: Acme's page is no place for Initech's terms, and none of its sentences is one Initech's replaces. A sentence that names someone the point does not, by a possessive or such a page's title ("Globex's refund window" for Acme's), is not one it replaces either. It finds them with the same search asretrieve, by keywords and, when embeddings are on, by meaning, among the documents you can read, and returns the instructions for agents of those places and of up to 20 folders that have some, by title. A point keeps the language of what it came from or of the page it belongs on. When only words were matched (semantic search is off) and no page found is about a point, none saying it, holding a sentence it changes, named by it or holding two of its words, the point carries anote: a page on it may be written in another language, so the agent lists the folder it belongs in, or plans again with the point's key words in that language, before it makes a new page. The agent then reads the best page and corrects the sentence a point changes, adds the point under its section, or makes a new page in the folder where it belongs, else in My notes. Each of these is an ordinary write: the page's level decides whether it waits for you, for a colleague, or applies at once. The whole save is one change, reviewed on one card. Afterwards the agent tells you what it saved where, what was already there, and what waits for approval, and when it wrote nothing, says so. - Tables. A fact a table's columns name, such as a customer's contact, plan or refund window,
goes in a row; prose, such as a decision, a reason or how something is done, goes in a page. So
rememberalso reads the databases the point's words reach (their names, their columns' names and their cells) that you can read, and offers, askind: "row", the row the point names by the value of its title cell (its first text column: "Initech", matched as search matches text, whatever its case, its width or its Chinese script), or a new row (row: null) when the point names the table or two of its columns and no row of it.fillslists the columns the point names, by every word of their name or by a choice they offer ("the Pro plan"), each with the cell as it reads now (now):already_savedwhen it holds what the point says and nothing in the point says another value for it ("30 days; it was 14 days before" says nothing of the 14 days but that it was),possibly_replaceswhen it holds another value, or may, andwaitingwhen a change you asked for already waits to write it. A row that says the point already comes first after the pages that do; a row the point fills comes before the pages about it, and a page found by one word alone is left out; a row it names and fills nothing of, after them. A new row you already asked for that the point names iswaiting_row, never offered again. The cells that say the point, or hold another value, also joinalready_savedandpossibly_replaces, naming the table, row and column. A database you can read but not edit offers no row; its cells still say what is there. The agent writes a row withdatabases_changeactionupdate_rows, changing a cell in place rather than adding a second row, or a new one withdatabases_addactioninsert_rows, in the same change as the rest of the save. - Who said it, and when. What you tell the agent yourself is saved without your name or a date
("per Liv", "noted on 2026-10-22"): Stuga's version history records who changed what and when. A
point from a meeting, an email or a document goes in with that as its
source, cited in the text as the place's instructions ask, else in a few words after it ("customer sync, 2026-10-21"), and is never attributed to you. Your name goes in only where a point is about you ("Liv is on call on Mondays"). - Asking.
searchandretrievegive an agent, for each document, when it last changed (updated_at), who made its latest version (last_edited_by: a person by name, an agent or an AI co-author by the person it worked for, as "Liv's agent"; for a page with no version yet, who created it),ai_edits(none,reviewed, orunreviewedwhile an AI change that applied directly is waiting to be marked reviewed), andpending_changes: the AI changes proposed to it that wait for approval and are not in its text, by who asked for them (asked_by:user, the person the agent acts for, through it, another of their agents or their AI co-author;others), whom they wait for (waits_for:review, the person who asked the AI;colleague, someone else) and since when. The changes you asked for are listed inproposed, each as it would land: the approved text it changes (approved_now, empty when it adds, as on a page with no approved text) and what that text reads once approved (after_approval, empty when it removes it), cut at 200 characters. A change one of your agents made to another of its waiting changes is told as one with it, from the approved text to where they end. Up to six per document are listed, those holding the most words of the question first; with passages, each goes on the passage it lands in, and one that lands in no passage found is listed on the document's first, with itssection, only when it holds a word of the question. When fewer are listed than wait,notesays so ("1 of 4 listed here; read the page for the rest"). Other people's changes are counted only. So one call can answer "the page says 14 days; a change to 30 days waits for a colleague". The agent answers with the approved text and says what waits. A person's search and retrieval over REST answer as before. - Rows. An agent's
searchandretrieveanswers also carryrows: up to five rows of the tables the question's words reach whose cells hold its words, with the database, the table, the row's title, its cells as the approved table holds them, and thematchedcolumns. A row counts when its title cell holds a word of the question, or when the question's words it accounts for come to two: words its cells hold, and words naming one of its columns or its table ("Globex's contact": Globex in Name, contact naming Contact). Each row carriesupdated_at,last_edited_by(who made the change that last wrote it, an agent by the person it worked for) and the changes you asked for that wait for it (pending_changes, as a document's, a change to a cell naming itscolumn). A new row you asked for that waits is listed withwaiting_rowand no cells. Changes other people asked for are counted for the whole database intables_waiting, never tied to a row: which rows they touch is for whoever asked and whoever decides, and another person's new row is nobody's to see until approved.tablesgives the namesqueryreads each table and column by (a column named Plan may beplan_xin SQL),rows_morenames a table with more matching rows than are listed, and the agent answers a precise question over a table, such as which customers are on a plan, withquery. A row is cited by its database'sdoc_idwith itstable_idandrow_id. - What waits, in a read. An agent's
markdownread lays the changes made through its connection over the text, so its next edits line up with them, and opens with a block that says the text is not the approved text and lists each change as it would land ("Approved now: … → after approval: …", or that the page has no approved text yet) and who approves it, saying they are the user's own changes, from this conversation or an earlier one. Then it lists the waiting changes the user asked for through another of their agents or their AI co-author, told the same way, and counts other people's; none of those is in the text. - Finding. When no document holds every word of an agent's
search, it lists those holding some of them, the most and rarest first, and sayspartial; a person's search box still finds only documents holding every word. With embeddings off, an agent'sretrievereturns the passages that hold the question's words (semantic: false) instead of refusing, and sayspartialwhen none holds every word; both notes remind the agent that pages may be written in another language, to try the words in it. A heading with no text of its own (a page's title heading, or a section whose text is all in subsections) is never a passage. Both takequeryas another name forq. - Whom it acts for. The server instructions and
workspacesactionlist(user) name the person the connection acts for, by their Stuga name and username, so an agent never names you by a name it guessed from a file path or an email address, and they tell it that what you say is saved without your name or a date. - Prompts. The connection offers three MCP prompts, which a client lists in its prompt menu:
Save to Stuga (
save, withtext), Ask Stuga (ask, with an optionaltopicof up to 2,000 characters) and Check Stuga (check, with an optionalscopeof up to 500 characters, below). Each sends one line in your own words. A read-only connection is offered Ask Stuga and Check Stuga, and noremember. - Claude. When Claude first asks to use Save to Stuga, choose Always allow, or it asks again every time.
Each person has one folder of their own in each workspace, made the first time their AI plans a
save there and named My notes in the language they read Stuga in. It sits at the top level,
owned by them and shared with nobody, a workspace admin included, and AI edits in it apply directly.
A point that fits no page of the wiki goes there, one page per topic. You can rename, move or share
it like any folder you own, and it stays your My notes; remember says in home.shared whether
anyone else can read it now. A key confined to some folders gets none unless its folders include it.
A page or folder in My notes that anyone else can read, after you share it or a folder above it, is
at review (Reviewed by whoever asked the AI) at least for every agent, yours included: no agent
changes a shared note unseen. docs action:metadata says so in its review reason.
Pages link to each other, and Stuga keeps track of it from what is approved.
- Links. A link to a page (
[text](/doc/<id>), or the page's address at the node's own or remote address, as copied from the browser) and a footnote that cites a page (whatcited_editsmakes) are read from each page's approved text whenever it is saved: a change waiting for review links nothing until it is approved. A link written in code is no link. - Linked from. Under its text, a page lists the pages you can open that link to it or cite it,
and
docsactionmetadatanames them aslinked_from. A page you cannot open is neither named nor counted, and neither is a page a change holds until it is approved. - Needs checking. A citation keeps when the passage citing the page was last approved: when it
last changed, or when someone marked the page checked. Once the cited page's approved text changes
after that, the citing page needs checking: it says so above its text, naming the pages that
changed, and so do the Index and
docsactionmetadata(needs_checking). Someone who can edit it marks it checked with Mark as checked, which no agent can do; an approved edit to the passage that cites the page counts as well. Only the pages you can open count: a change to one you cannot open marks nothing for you, and your mark covers only the pages you can open. A page's first words are no change: a page imported from an archive, or made in the same change as a page citing it, cites what it says as it was written, whichever of the two is saved first.
Both are generated from what you can open; nothing writes to them, an agent included.
- The Index (
/wiki, Wiki → Index in the library) lists every page and database you can open, by folder: the top level first, then each folder by its path, the pages shared with you from a folder you cannot open under Shared with you, and your own My notes last. Each shows its opening paragraph, when its approved text last changed and who changed it (a person by name, an agent or the AI co-author by the person it worked for, an AI change approved by a person under that person's name), and Needs checking. A database shows how many rows it holds, and its last change is the last change to its rows or columns. A row page is listed by its database. One Index lists up to 1,000 pages;?folder=<id>shows one folder and what is under it.docsactionindexanswers the same, up to 300 pages,parent_idnarrowing it to a folder, and leaves out pages kept out of search, as an agent's search does. - The Log (
/wiki/log, Wiki → Log) lists the AI changes people approved or declined, and those applied directly, newest first, over the year the review inbox keeps them: each change once, with the pages of it you can open, who asked and through which AI, who approved or declined it, and when. A change to a database names each table and the rows it touched, as the table names them now; a row deleted since is counted. A change's title shows to whoever asked for it or decided some of it, as on its card. While a page of it you can open still waits, it is in the review inbox instead.docsactionloganswers the same, a page at a time (pass itsnextasbefore), with the title only of a change that agent made itself.
Say Check Stuga to your AI, or pick it from the prompt menu, and it looks over the wiki with
docs action lint, for the workspace or one folder (parent_id). It finds:
- Pages that need checking, each with the pages it cites that changed since.
- Orphans: pages in a folder that no other page you can open links to or cites. A page at the top level is where a reader starts, a row page is listed by its database, and My notes are yours, so none of them counts.
- Broken links: links and citations to a page in the trash (named, when you can open it), or to
one that is gone or that you cannot open, which it tells apart from nothing (
not_found, no title); and links to a row, or citations of one, in a database you can open, once the row is gone from its table (row_deleted).
The agent proposes each fix as a small edit, all of them in one change for your approval: it
corrects the sentences a changed source makes untrue, citing the source again, links an orphan from
the page a reader would look in, repoints a link to a page in the trash, and points a link to a
deleted row at the row meant, found with query, or keeps its text without the link. A link not_found may
name a page someone else can open, so the agent asks you before it changes one. It never rewrites a
page to fix it, and leaves marking a page checked to you. A read-only connection tells you what it
would change.
A citation names a page the caller can read in the workspace, or a row of a database they can read
(table_id and row_id), whose footnote opens that row in its table. cited_edits naming any other,
or a row that is not there, is refused whole with citation_not_found, the same answer for a page
that is missing as for one out of reach, and nothing is proposed.
/mcp registers twenty tools from @stuga/agent-surface, and runs them in-process over the
node's own code, through the same permission checks and run ledger as the REST routes. The stdio
server lists the node's tools as they are. Reads and writes are separate tools, and each carries MCP
annotations: readOnlyHint, destructiveHint, idempotentHint and openWorldHint. A client shows
them or acts on them, such as asking before a destructive call. They grant nothing: permissions and
the item's agent_mode decide what a call does.
Reads. Every one is read-only and idempotent.
| Tool | Actions and use |
|---|---|
workspaces |
list · instructions. The workspaces this connection reaches and the node each is on (above), whom the connection acts for (user), and one workspace's instructions for agents. |
docs |
list · metadata · index · log · lint. list takes an optional folder (parent_id, null for the root). metadata includes this agent's review answer for the document, its instructions, linked_from and needs_checking. index, log and lint read the wiki. |
search |
Hybrid keyword and semantic search that returns documents, across workspace_ids, optionally within a collection. Each result says who last changed it and when, and what waits for approval, and rows lists the table rows that hold the query's words (Asking). |
markdown |
read · status · provenance. read lists the changes that wait for approval, then shows the document's instructions in a marked block, then the text with the waiting changes made through the connection laid over it. status reports what became of its edits. |
comments |
A document's comments. An author of panel:<alias> is that person's in-app co-author, and the agent's own comments carry you: true. |
folders |
The folders the credential can read in the workspace. |
events |
What changed in the workspace since after, optionally narrowed by types. Without after it starts from the newest event. |
collections |
list · open. The saved document sets of the credential's person, which search and retrieve can be scoped to. open lists the members the credential can read (collections.md). |
retrieve |
The passages most relevant to a question across workspace_ids, with their sources, who last changed each and what waits for approval, optionally within a collection (rag-cross-doc-qa.md), and the table rows that hold the question's words. With embeddings off, the passages that hold the question's words. |
databases |
list · schema · status · page. schema returns tables, columns with their physical SQL names and description (what the column holds, written by the people here), saved views and the database's instructions. page returns the doc_id of a row's page, or null when it has none. |
query |
One read-only SELECT (SQLite dialect) against one database, with ? parameters: the answer to a precise question over a table. At most 8 KB of SQL, 1,000 rows, 1 MB per value and five seconds of work. WITH RECURSIVE is refused, because a recursive query that never ends cannot be stopped. |
Writes. None but remember is idempotent. Destructive ones may replace or remove what exists;
open-world ones may make the node download an image or file from the web.
| Tool | Actions and use | Destructive | Open-world |
|---|---|---|---|
remember |
Save to Stuga: where each of 1 to 20 points belongs, a page or a table's row (above). It writes no text, and makes the person's My notes the first time. | no | no |
docs_create |
A document with a title, optionally in a folder. Returns its instructions, and its change_id when it is in a change. |
no | no |
markdown_append |
Adds text at the end of a document, or under heading, and touches nothing else. Under a heading it goes at the end of that heading's own text: before its first subsection when it has any (so under a page's title heading, in the page's opening), and the answer says where it went and names the subsections; else at the end of its section. A heading the page lacks is refused with the headings it has, or, on a page with none, a note to put the heading in the text. |
no | yes |
markdown_edit |
write · str_replace · cited_edits. write replaces the whole document, str_replace swaps find for replace (one occurrence, or all with replace_all; old_string and new_string are the same), and cited_edits makes several exact edits at once with citations that become footnotes, each of a page the caller can read or a row of a database they can read (citation_not_found otherwise). |
yes | yes |
comments_add |
A comment on a document, a reply in a thread (parent_num), or a comment on a passage (quote, its exact text). It may mention at most 5 people, and those who can read the document are notified, as are the document's owner and, for a reply, the thread's people (Agents in comment threads). |
no | no |
media_upload |
upload · upload_from_url · start_upload. Stores an image or any other file with a document, or a file with a database: from base64 of up to 3 MB with its name, from a public URL the node downloads, or, after start_upload, from the upload_url the caller sends it to itself, by upload_id. A document gets the Markdown that places it, an image shown and any other file a link that downloads; a database gets the link for a files cell. |
no | yes |
collections_edit |
create · rename · delete · add_items · remove_items. add_items skips ids the credential cannot read and says how many. |
yes | no |
databases_add |
create_database · create_table · add_column · insert_rows · import · start_import · create_view · open_page. add_column may set a column's description. import loads a whole CSV or JSONL file as one reviewable change, from its text in content or from an upload by import_id, so bulk data never passes through insert_rows. start_import returns an upload_url for a caller that can send the file itself, and the import_id to commit. open_page returns a row's page, a document read and edited like any other, and creates it the first time. |
no | no |
databases_change |
update_rows · delete_rows · update_view. |
yes | no |
Edits to a document's text and to a database are proposals. The writes that make or change a page or
a database take change_title, change_id and change_summary
(Changes). Writing  or a data:
URI through markdown_edit or markdown_append downloads and stores the image, behind the node's
outbound address checks. A mention of a person reads and writes as [@username](mention:<alias>);
keep it as written, and once an edit lands, a newly mentioned person who can read the document is
notified. The answer to a proposal names the instructions that apply beyond the workspace's.
When a file is too large to carry, import hands the agent a link to the table's Import dialog to
give the person. A files column holds a row's attachments as links, one per line; an agent adds
one by storing the file with media_upload on the database and writing the link into the cell
through databases_change, a proposal like any other. The stdio server also takes a local file
for import and upload (above).
search and retrieve take workspace_ids: from 1 to 50 ids from workspaces action list, or
["*"] for every workspace the connection reaches.
- Each workspace is searched on its own, under its own permissions. Scores from different workspaces do not compare, so the answers are merged by rank: each workspace's first result, then each one's second, and so on. Scores are left out.
- Each result names its
workspace_idand carries aurlthat opens the document. collection_idnarrows a search of exactly one workspace.unavailable: [{ workspace_id, reason }]lists each workspace the call could not cover: one the connection cannot use. The agent is told to say so and never to present the rest as complete. When the only workspace named fails, its reason is the tool's error.
A read-only key, or a connection given Read only, is offered the eleven reading tools and the
Ask Stuga and Check Stuga prompts, and nothing else. The server instructions say that it may change nothing, and to tell the user what it
would change instead. workspaces action list reports access: "read". A write tool it names
anyway is unknown to it, and the node's own read-only check stands behind that. Ask over REST is a
read too, and a read-only key keeps its own Ask threads (api.md).
Two rules hold whatever a client does:
- Raw Yjs writes from an agent's socket are refused (
approval_required). Proposals are the only way an agent changes content. - A successful proposal is recorded even while review is pending. An agent that sees no change on
re-read is looking at its own pending edits, not a lost write. The tool results say
Proposedand tell the agent not to retry.