Hosted diagrams and plans

Organisations

Share a private library of diagrams with a team. An organisation is a named group of accounts. Its members publish to one library that only they can open, by hand in the portal or from an agent.

TL;DR

Question	Answer
What is an organisation?	A named group of accounts with one private library of diagrams. You can own some and belong to others. It works on the Free plan and the Pro plan.
Whose plan does it use?	Its owner's. A Pro owner gives the whole organisation the Pro limits, and a Free owner gives the Free ones. A member's own plan never matters, so the people you invite need no plan.
Who can see a diagram?	Only members, after they sign in, and API keys that belong to the organisation or to a member. An organisation diagram has no public link.
What are the roles?	Owner, admin, member and reader. A reader can look and download but change nothing. See Roles.
Can I keep a folder to some people?	Yes. The owner can restrict a folder to some roles and some named members. See Restrict a folder.
How do people join?	An owner or admin invites an email address. The person opens the link in the email, signs in with that address, and accepts. An invitation works for seven days.
Can an agent use it?	Yes. Pass the `organization` argument to `publish_diagram`, `list_diagrams` or `delete_diagram` on the hosted MCP server, or use an organisation API key. An agent deletes a diagram only after you have named it.
Who can delete a diagram?	The member who published it, an admin and the owner. A reader cannot. See Who may delete and lock.
Can we keep members' diagrams off public links?	Yes. The owner or an admin sets Publishing: members' diagrams go to the library by default, or, on Pro and Enterprise, always. See Where members publish.
Can I protect a diagram from being deleted?	Yes. The owner can lock it. Nobody can then rename, move or delete it, the owner included, until the owner unlocks it. A lock does not stop the plan's expiry.
Can I show an organisation diagram in a README?	No, because there is no public link to put there. Download the SVG and commit it, or publish the diagram to your own library when it may be public.
How do I delete an organisation?	The owner deletes it in its Settings tab. Every diagram in it goes too.
Can an organisation have a picture?	Yes, on every plan. Each one shows a mark made from it, and the owner or an admin can upload an SVG, PNG, GIF or WebP, still or animated. See The avatar.
Can I change a diagram in the browser?	Yes, when its picture carries its source. Choose Edit: the source and the live picture sit side by side, and Save replaces the diagram. Saving is on Pro. See Edit a diagram in the browser.

1. What an organisation is

An organisation holds a library of diagrams for a team. A person who makes one is its owner, and the owner invites the others. Plotwork keeps an organisation's diagrams apart from every member's own hosted diagrams, so joining a team never mixes its library with yours.

	Your own library	An organisation's library
Who can open a diagram	Anyone who has its link	Members who are signed in, and keys that belong to the organisation or to a member
How a diagram is addressed	A public link on `cdn.plotwork.dev`	A page of the portal that needs a sign-in
Where the file is stored	Public storage, served from its link	Private storage with no public address, read only through the API
What it counts against	Your plan	The organisation's own pool, against its owner's plan
Who can delete a diagram	You, unless you locked it	The member who published it, an admin, or the owner, unless the owner locked it

An organisation has a name and a handle. You can rename the organisation, but the handle never changes.

Part	Rule
Name	1 to 60 characters. This is what people read.
Handle	3 to 40 characters: lowercase letters, digits and hyphens, with no hyphen at either end. You choose it when you make the organisation. If you leave it out, Plotwork makes one from the name and adds a few characters when that handle is taken. The portal address uses it, and so does the `organization` option of `publish_diagram`.

There is no public page for an organisation and no way to search for one or for a person. The handle is a name for addresses and for agents, not a listing.

Names and the word filter

A name, and a handle you choose, must not hold a word from a list of English profanities and slurs. The filter reads through capital letters, look-alike characters, numbers used for letters, repeated letters, and a word spaced out one letter at a time. It lets through ordinary words that only contain one, such as the name of a town. A refused name is answered with orgs.name_not_allowed (status 422), which never says which word. The check runs when you make the organisation and when you rename it, before anything is saved. It is a word list, a filter for the obvious and not a moderator, so it decides nothing about meaning.

2. Plans and limits

An organisation has the plan of its owner. The owner is the account that made it. A Pro owner gives the organisation the Pro limits for people and for diagrams, and a Free owner gives it the Free ones. A member who belongs to a Pro organisation gets nothing for their own account from it, and a member's own plan changes nothing for the organisation.

These are the numbers the API holds each organisation to. The hosted rows apply to each organisation on its own, not to the owner's personal diagrams.

Limit	Free	Pro	Enterprise
Organisations you can own	1	5	Custom
People in one organisation (Owner, readers and pending invitations included)	3	25	Custom
Brand themes (The organisation's colors on every diagram the hosted service draws)	Not included	Included	Included
Saved style rules (The same rules for CI in every repository; a rules section in your own settings file is free)	Not included	Included	Included
Members publish only to the library (No member's diagram at a public link; sending them to the library by default is on every plan)	Not included	Included	Included
Hosted diagrams	25	2,000	Custom
Storage	10 MB	1 GB	Custom
Largest diagram	2 MB	2 MB	Custom
Kept after you last publish	30 days	Until you delete it	Custom

Rule	What it means
Organisations you can own	Only organisations you made count. An organisation you belong to does not.
People in one organisation	The owner, every member (readers too, because the limit is on people), and every invitation that has not been accepted all count. A full organisation cannot invite anyone until a member leaves or an invitation is revoked or expires.
Diagrams and storage	Counted for the organisation. When a publish would pass the limit, it is refused with `hosting.quota_exceeded`, and the numbers in the refusal are the organisation's.
How long a diagram is kept	The owner's plan decides. A Free owner's organisation keeps a diagram for the number of days in the table after it was last published. A Pro owner's keeps it until it is deleted. Publishing the same diagram again starts the time over.
Daily calls	There is one allowance for each account. A call made with an organisation key counts toward the owner's allowance, so a team on Free shares the owner's. A call made with a member's own key counts toward that member's. See the daily call limit.

When the owner's plan changes, the organisation follows it, as the owner's own diagrams do. Moving to Pro stops every expiry in the organisation's library at once, and moving to Free gives each diagram that had no expiry a full period from the change, the number of days in the table above. Nothing is deleted at once. Plans and billing shows how to upgrade.

3. Roles

Every member has one role. The owner is the account that made the organisation, and there is exactly one. A reader is for a person who may look and may not change anything, such as a stakeholder, an auditor or a contractor. A reader counts toward the limit on people like any other member.

Action	Owner	Admin	Member	Reader
See the organisation, its members and its diagrams, and download a diagram	Yes	Yes	Yes	Yes
Publish a diagram	Yes	Yes	Yes	No
Move, rename or delete a diagram	Yes	Yes	Their own only	No
Lock and unlock a diagram	Yes	No	No	No
Invite someone, and revoke an invitation	Yes	Yes, as member or reader only	No	No
Remove a member	Yes	Yes, members and readers, not admins	No	No
Change a member's role	Yes	No	No	No
Rename the organisation	Yes	Yes	No	No
Make, list and revoke the organisation's API keys	Yes	Yes	No	No
See the folder rules	Yes	Yes	No	No
Make and remove a folder rule	Yes	No	No	No
Save, preview and remove the brand theme	Yes	Yes	No	No
Save and remove the style rules	Yes	Yes	No	No
Upload, replace and delete custom icons	Yes	Yes	No	No
Upload, replace and remove the avatar	Yes	Yes	No	No
Keep diagrams editable	Yes	No	No	No
Choose where members publish, and move or unpublish their public diagrams	Yes	Yes	No	No
Read and export the audit log	Yes	Yes	No	No
Set up single sign-on	Yes	Yes	No	No
Send audit events and drift to your tools	Yes	Yes	No	No
Leave	No, delete the organisation instead	Yes	Yes	Yes
Delete the organisation	Yes	No	No	No

A restricted folder can narrow this table for a folder (see Restrict a folder), and never widens it: a rule that names a reader lets them see the folder and no more.

"Their own" means a diagram the member published. A diagram whose publisher has left, or whose account was deleted, can be changed only by an admin or the owner. The owner cannot be removed or demoted, so an organisation never has no owner. Ownership cannot be transferred yet, because it decides the plan.

Who may delete and lock

Question	Answer
Who may delete a diagram?	The member who published it, an admin and the owner. A member cannot delete a teammate's diagram, and a reader cannot delete any. An organisation API key deletes as an admin does. Plotwork checks the caller on every delete, whether it comes from the portal, from a script or from an agent, so nothing a caller says can widen it.
Who may lock a diagram?	Only the owner, in the portal. An admin cannot lock or unlock, and an organisation key never does.
What does a lock do?	A locked diagram cannot be renamed, moved or deleted by anyone, the owner and the admins included, until the owner unlocks it. Everyone who could see it still can, and can still download it.
How does a locked diagram look?	The portal shows it as locked. An agent's `list_diagrams` shows it as `locked`, and a delete is refused with `hosting.diagram_locked`.
Does a lock change publishing?	Publishing the same diagram again with no new name and no new folder still works, because it changes nothing a lock protects. A publish that would rename the diagram or file it in another folder is refused.
Does a lock keep a diagram past its expiry?	No. A lock does not stop the plan's expiry, so a diagram on a Free owner's organisation is still removed when its time is up.
Does a lock keep the organisation from being deleted?	No. Deleting the organisation deletes every diagram in it, locked or not.

4. Make an organisation and invite people

Make an organisation

Sign in at app.plotwork.dev (opens in a new tab) and open the Organisations page.
Enter a name, and a handle if you want to choose it.
Choose to make the organisation. You are its owner.

If you already own as many organisations as your plan allows, the form says so and points to the Plan page. The API answers orgs.limit_reached. If the handle is taken, it answers orgs.slug_taken.

Invite a person

Open the organisation and the Members tab.
Enter the person's email address, choose a role (admin, member or reader), and send the invitation.
The address gets an email that names who invited them, the organisation and the role, with a link.
The person opens the link, signs in with that same address, and accepts.

Question	Answer
Who can invite?	The owner, and admins. An admin can invite only as a member or a reader. Nobody is invited as the owner.
How long does an invitation work?	Seven days. After that it is deleted, and an admin sends a new one.
Can someone else use a forwarded link?	No. The person must sign in with the address that was invited, so a forwarded link is no use to anyone else. If they sign in with another address, the page says which address was invited and offers to sign in as another.
What does a link do?	It is used once. Accepting makes the person a member and deletes the invitation.
Can I take an invitation back?	Yes. An owner or admin revokes it from the Members tab, and the link stops working.
What if the organisation is full?	An invitation counts toward the limit on people the moment it is sent. If the organisation fills before the person accepts, accepting is refused with `orgs.member_limit_reached`.
Is there one invitation for each address?	Yes. Inviting an address that already has a pending invitation is refused with `orgs.already_invited`, and an address that is already a member with `orgs.already_member`.

Leave or remove a member

You do this	What happens
Leave	An admin, a member or a reader chooses Leave on the Members tab. Their member row goes. The diagrams they published stay, and no longer name them as the publisher.
Remove a member	An owner can remove anyone but themselves. An admin can remove members. Removing does not delete the member's diagrams, which no longer name the member as the publisher.
Change a role	The owner chooses admin, member or reader for any other member. Only the owner changes a role.

5. The private library

Every member sees the organisation's library on its Diagrams tab: a folder tree and a list, a preview of each diagram, and where the organisation stands against its limits. From there a member can download a diagram, and can publish, move, rename or delete the diagrams their role lets them change (see Roles); a reader can only look and download. Each diagram has a page of its own that shows it large, with the same actions. That page needs a sign-in, so it is never a link that anyone can open.

Folders work as they do for your own library: a slash nests folders up to five levels, each name can be forty characters or fewer, and a folder exists while it holds a diagram. See Hosted diagrams.

Private means no public link

An organisation's files are stored in a private place that has no public address. The API reads them and serves them only to a signed-in member, or to an API key that belongs to the organisation or to a member. Every answer says not to keep a copy in a shared cache, and a page on another site cannot embed it.

That has one practical result: you cannot put an organisation diagram in a README, a pull request or a web page by its address. A person who is not signed in would see a broken picture, and a README cannot sign anyone in. You have two ways to show the picture:

Way	When to use it
Download the SVG and commit it next to the README	The picture belongs in the repository, and the repository is as private as the organisation or less so on purpose.
Publish the diagram to your own library	The picture may be public. It gets a public link, and it is then a personal hosted diagram that anyone who has the link can see. See Hosted diagrams.

Download a diagram

A member downloads a diagram with Download in the portal. The file is named after the diagram, with .svg at the end. Code that holds a key can read it from GET /orgs/{org}/diagrams/{id}/svg, and adding ?download=1 makes the answer a file download.

How long a diagram is kept

The owner's plan decides. On a Free owner's organisation a diagram is deleted the number of days in the table above after it was last published, and publishing it again starts the time over. On a Pro owner's organisation it stays until someone deletes it. A clean-up that runs once a day removes expired diagrams, and the same clean-up deletes invitations that have run out.

Publishing the same source in the same theme to the same organisation finds the diagram that is already there, so an agent that repeats a step stores nothing twice.

6. Restrict a folder

By default every member can use every folder. The owner can restrict a folder to some roles and some people, for example to keep Payments to the admins and a few named members. Only the owner makes or removes a rule, in the portal. The owner and admins can read the rules.

Part of a rule	Meaning
Folder	A folder path such as `Payments`. The rule covers that folder and every folder inside it.
Roles	Any of admin, member, reader and key, which stands for the organisation's API keys. The owner is not a choice, because the owner is always allowed.
People	Named members, by account. Removing a member, or a member leaving, removes them from every rule.

Question	Answer
Who can use a restricted folder?	The owner, anyone whose role is named in the rule, and anyone named in it.
What does an empty rule do?	Only the owner can use the folder.
Is an admin special?	No. A rule applies to an admin like anyone else, so an admin who is not named cannot see the folder.
Which rule applies inside a restricted folder?	The nearest one. A rule on a deeper folder replaces the rule above it for that folder and everything in it, and does not add to it. A team can open `Payments/Public` inside a restricted `Payments`.
Can naming a reader let them change things?	No. A reader named in a rule can see the folder and download from it, and still cannot publish, move, rename or delete. A rule decides who may use a folder. It never gives a role a right the role lacks.
Do organisation keys need naming?	Yes. A key may use a restricted folder only when the rule names `key` among its roles. A pipeline or an agent that publishes with an organisation key to a restricted folder needs it.
Does a rule need a diagram?	No. A folder exists only while a diagram is in it, but a rule stays until the owner removes it, so a folder can be restricted before anything is published there.
How many rules can there be?	A limit on the rules in one organisation and on the people in one rule. Past it, the API answers `orgs.rule_limit_reached`.

This is what a person who is not allowed in a folder sees.

Action	What happens
List the diagrams	The folder's diagrams are left out. The counts of diagrams and storage still include them, because the limits belong to the organisation.
Open, download, rename, move or delete a diagram in it	The answer is not found (404 `not_found`), the same as for a diagram that does not exist.
Publish into it, or move a diagram into it	Refused with `orgs.folder_restricted` (403). The person named the folder, so the refusal reveals nothing they did not type.
Publish a diagram that is already stored in a folder they cannot use	Refused with `orgs.folder_restricted`. A publish never moves or shows a diagram the person may not reach.
Move a diagram out of it	Not found, as above. Moving a diagram needs access to both folders.

A person who is allowed into a restricted folder sees its diagrams marked as restricted, so they can tell which folders are locked without reading the rule. A rule is a setting of the signed-in portal: its routes take no API key, and they are listed in the API reference. A rule that names a person who is not a member is refused with orgs.rule_invalid, and one past the limits with orgs.rule_limit_reached.

An agent that publishes into a restricted folder is refused with orgs.folder_restricted. It should ask the person which folder they may use, and not publish somewhere else.

7. Publish from an agent

The hosted MCP server's publish_diagram tool takes an optional organization: the handle or the id of an organisation. Connect the hosted server with an API key or a browser sign-in, then name the organisation in plain words:

Publish this diagram to the acme-platform organisation.

The agent calls publish_diagram with the source it has and organization set to acme-platform. The diagram goes to that organisation's private library.

Question	Answer
When does an agent use `organization`?	Only when you name an organisation or ask for a team diagram. Without the option, a diagram goes to your own library at a public link, unless an organisation you belong to sends its members' diagrams to its library. See Where members publish.
What comes back?	`private: true`, the diagram's `id`, `viewUrl`, `name`, `folder`, `bytes` and `expiresAt`. There is no public `url` and no Markdown image, because there is no public link. `viewUrl` is a portal page that needs a sign-in.
Who may publish?	A member, through a browser sign-in or a key of their own, or an organisation key.
What if the key belongs to an organisation?	With no `organization`, the diagram goes to the key's own organisation, so a CI job set up with one key needs nothing else. A key for one organisation cannot publish to another: the call is refused with `orgs.key_wrong_org`.
What if I am not a member, or the organisation does not exist?	The call is refused as not found, with the same answer for both. The agent should ask you which organisation you mean, and not try another or fall back to your own library.
What if the organisation is full?	The refusal is `hosting.quota_exceeded`, with the organisation's numbers. Delete a diagram or ask the owner to upgrade.
What if the folder is restricted, or I am a reader?	A folder the owner restricted refuses the call with `orgs.folder_restricted`, and a reader cannot publish at all (`orgs.forbidden`). The agent should ask the person which folder they may use, and not publish somewhere else. See Restrict a folder.

The tool also takes source, theme, name and folder exactly as for your own library: see Hosted diagrams. The local MCP server has no publish_diagram and no organisations.

There is no MCP tool to read the file of an organisation's diagram. list_diagrams lists the diagrams and the portal page of each, but downloading a file is for people, in the portal, and for code that holds a key, over REST.

List and delete from an agent

Two more tools of the hosted MCP server take the same organization option: list_diagrams and delete_diagram. Name the organisation in plain words:

Show me the diagrams in the acme-platform organisation.

The agent calls list_diagrams with organization set to acme-platform. To remove one, name it:

Delete the Login flow diagram from acme-platform.

Question	Answer
What does `list_diagrams` return?	`private: true`, the organisation, and for each diagram its `id`, `name`, `folder`, `bytes`, `createdAt`, `publishedAt`, `expiresAt`, `viewUrl`, whether it is locked (`locked` and `lockedAt`) and whether you may delete it (`canDelete`). It also gives the number of diagrams the organisation holds and where it stands against its plan. There is no public link. A diagram in a folder you may not use is left out.
When does an agent delete?	Only after you have said, in the conversation, which diagram to delete, by name. The `delete_diagram` tool has a required `confirm` field that must be `true`, and the agent is told to set it only then, and never to delete on a guess, in bulk, or to make room for a new diagram.
Who is allowed?	Plotwork decides by the role behind the connection, exactly as in Roles. An agent that uses a member's sign-in or key deletes only what that member may. An agent that uses an organisation key deletes as an admin does. A reader's agent can list and cannot delete.
What if I am not allowed to delete it?	The call is refused with `orgs.forbidden`. The agent tells you, and does not try other diagrams or another organisation.
What if the owner locked it?	The call is refused with `hosting.diagram_locked`. The agent tells you that nobody can delete it until the owner unlocks it, and does not try to get around the lock. If you are the owner, it says you can unlock it in the portal.
What if the organisation, or the diagram, is not found?	The call is refused as not found, with the same answer for an organisation you are not in, one that does not exist, a diagram that is already deleted, and a diagram in a folder you may not use. The agent asks you which one you mean.
What if the key belongs to another organisation?	The call is refused with `orgs.key_wrong_org`, as for publishing. The agent asks you whether to use the key's own organisation or a key made for the other one.
Can an agent lock or unlock a diagram?	No. Only the owner locks and unlocks, in the portal.

8. API keys and REST for scripts and CI

An organisation has API keys of its own, so a pipeline can publish to the team's library without any person's key.

Question	Answer
Who makes them?	The owner and admins, on the Keys tab. A key is shown once when it is made, and can be revealed again by an owner or admin, as for your own keys. A key with no stored copy cannot be shown again.
Whose are they?	The organisation's. An organisation key does not appear in your own list of keys, and it keeps working when the member who made it leaves.
How many?	Up to ten active keys for each organisation.
What can a key do?	Read the library, publish to it, and move, rename or delete any diagram in it. It never invites, removes, renames, makes keys, or deletes the organisation. It acts only in its own organisation, and in a restricted folder only when the rule names `key`.
Can a key lock a diagram?	No. Only the owner locks and unlocks, in the portal, and nothing can move, rename or delete a locked diagram until the owner unlocks it, a key included.
Whose allowance does it spend?	The owner's daily calls. See Plans and limits.

Five routes of the API take a key as well as a sign-in. {org} is the organisation's handle or its id. A caller who is not a member, or whose key belongs to another organisation, gets 404, the same answer as for an organisation that does not exist.

Route	What it does
`GET /orgs/{org}/diagrams`	Lists at most 200 diagrams, most recently published first, with the organisation's usage and limits.
`POST /orgs/{org}/diagrams`	Publishes a diagram: `source`, and optionally `theme`, `name` and `folder`. Answers 201 for a new diagram and 200 for one that was already there, with the diagram and its `viewUrl`.
`GET /orgs/{org}/diagrams/{id}/svg`	Returns the file. `?download=1` makes it a download.
`PATCH /orgs/{org}/diagrams/{id}`	Changes `folder` or `name`. A key may change any diagram that is not locked.
`DELETE /orgs/{org}/diagrams/{id}`	Deletes the diagram, unless it is locked. Unlike your own library, a key may delete here.

The command below publishes from a pipeline. It reads the key from the environment variable PLOTWORK_API_KEY, so replace nothing in it except the handle.

1curl -s -X POST https://api.plotwork.dev/orgs/acme-platform/diagrams \2  -H "X-API-Key: $PLOTWORK_API_KEY" \3  -H "content-type: application/json" \4  -d '{"source":"flow \"Login\"\nnode user person \"User\"\nnode api service \"Auth API\"\nuser -> api : \"POST /login\"","name":"Login flow","folder":"Payments/Checkout"}'

These are the failures a client should expect. Every one uses the error envelope, and the errorCode is the field to branch on.

Status	`errorCode`	What it means and what to do
401	`auth.missing` or `auth.invalid`	There is no key, or it is wrong or revoked.
403	`orgs.forbidden`	The role may not do this. A member may change only their own diagrams, and a reader may change nothing.
403	`orgs.folder_restricted`	The folder is restricted and the caller, or the key, is not allowed in it. A key needs `key` in the rule.
403	`orgs.key_wrong_org`	The key belongs to an organisation, and the call went to the personal publish route. Publish with `POST /orgs/{org}/diagrams` instead.
403	`hosting.quota_exceeded`	The organisation holds no more diagrams or bytes. Delete one, or ask the owner to upgrade.
404	`not_found`	The organisation does not exist, you are not a member, the key belongs to another organisation, or the diagram is in a folder you may not use. The answer is the same for all of them.
409	`hosting.diagram_locked`	The owner locked the diagram, so it cannot be renamed, moved or deleted until the owner unlocks it. `details` has `lockedAt` and `canUnlock`, which is true only for the owner.
413	`hosting.too_large`	The diagram draws larger than the plan hosts. Simplify it.
422	`diagram.invalid`	The source has mistakes. `details` lists each with its line, column and hint.
429	`usage.daily_limit` or `rate_limited`	The owner's daily allowance is spent, or the per-minute limit is.
503	`orgs.unavailable`	Organisations are not set up on this server.

The other organisation routes (creating an organisation, members, invitations, keys) belong to the portal and need a browser sign-in. The API reference lists every route as the API describes it.

9. Delete an organisation

Only the owner can delete an organisation, from its Settings tab.

Event	What happens
The owner deletes the organisation	Every diagram is removed from storage first, then the records: diagrams, members, invitations, keys, and the organisation. If removing a file fails, the organisation stays so that you can try again.
The owner's account is deleted	The organisations it owns are deleted first, as above, then the account. Its memberships elsewhere are removed. Diagrams it published in other organisations stay, without its account id.
A member leaves or is removed	The member row goes. Their diagrams stay.
A diagram expires	The daily clean-up removes it, file first.
An invitation expires	The same clean-up deletes it.

Deleting an organisation cannot be undone, and a lock on a diagram does not stop it.

10. Privacy

An organisation stores a member row for each person (an account id, a role and a join date), a pending invitation for each address invited (the address, the role and who invited, until it is accepted, revoked, or seven days have passed), and each diagram's drawn picture with its name, folder, size, dates and publisher. A folder rule stores a folder name, which is text you chose, with the roles and the member accounts it names. A lock stores the time it was set and the account id of the owner who set it, and nothing else. A reader is a member and stores the same data as every other member. Members see each other's email addresses, because a team knows who is in it. Where members publish is one setting on the organisation, and a person's default organisation for publishing is one row with their account id and the organisation's id. An uploaded avatar is stored as the check rebuilt it until an owner or admin removes it or the organisation is deleted. Diagram source is still never stored.

The audit trail names account ids and organisation ids, including when a rule is set or cleared, and never an email address, a name, a folder or diagram text. The cookie policy does not change, because the portal uses the same session cookie it already used. The privacy policy lists all of it, with why each item is kept and for how long.

11. The avatar

Every organisation has a picture beside its name in the portal: in its own heading, in the list of organisations, in the account menu, on the dashboard, on a diagram's page, in the share box, in the choice of organisation style, and on the page that says you joined. Its frame has a second rule around it, so an organisation never looks like a person.

Question	Answer
What shows if nobody uploads one?	A small mark made from the organisation, the same everywhere. Nothing is stored for it.
Who can change it?	The owner and admins, in the Settings tab. Members and readers see it.
Which plans?	Every plan.
Which files?	SVG, PNG, GIF or WebP, still or animated. At most 256 KB, 512 pixels on a side, and 200 frames. A square of 256 pixels looks sharp everywhere.
What is checked?	The same check as custom icons. An SVG is rebuilt from drawing elements, and for an avatar also from animation that changes its own shapes and starts on a plain time such as `begin="1s"`. Scripts, links, and animation that waits for a click or another element are refused, with a reason for each. A PNG, GIF or WebP keeps only its frames, so text, EXIF and XMP are left out.
Does it move for everyone?	No. If your device asks for less motion, an animated avatar holds still on its first frame.
How do I go back to the generated mark?	Choose Remove avatar in the Settings tab.

The preview in the Settings tab shows the picture at every size it is drawn at, on a light and a dark ground, before you upload it.

12. Edit a diagram in the browser

A diagram can be changed in the portal, for a small fix without asking an agent: choose Edit on its page, in its row's menu, or on the viewer's toolbar. The editor changes the diagram's source, never its picture, and draws the picture again from the source as you type. An agent can go on editing the same diagram afterwards with read_diagram and edit_diagram. Your own hosted diagrams have the same editor.

Question	Answer
Which diagrams can I edit?	One whose picture carries its source: published with `embedSource` set to true, published while the organisation keeps diagrams editable, or saved in the editor before. Any other picture shows why it cannot be edited and what to do.
What is Keep diagrams editable?	A switch for the owner in the Settings tab. On, every publish to the organisation that does not set `embedSource` to false writes the source into the private picture. Pictures published before it was on are not changed.
Who can edit?	Whoever may change the diagram: the owner and admins any diagram, a member their own. A reader cannot. A locked diagram cannot be saved until the owner unlocks it.
Which plan?	Anyone who may change the diagram can open the editor, edit and preview. Saving needs Pro: the owner's plan for an organisation's diagram, your own for your own.
Is it sent anywhere while I type?	No. The picture is drawn in your browser with the organisation's brand and icons, so the preview is the picture Save stores. Only Save sends the source.
What if the source has a mistake?	The mistake is underlined with its hint, listed under the source, and the last picture that drew stays on screen until the source draws again. Save waits until there are no errors.
How do I save?	When you change something, a bar slides up over the picture with Unsaved changes, Discard and Save. It says Saved for a moment after a save and slides away. Cmd or Ctrl with S and the editor's menu save too, and the dot beside the diagram's name shows where saving stands. Discard puts back the saved version, and Undo brings your changes back.
What if someone saved while I was editing?	The save bar says so and offers to reload their version or keep yours and replace it. Nothing is lost without you choosing.
Can I go back?	Undo and Redo work while you edit. Each save keeps the picture it replaced, up to ten, and Restore a previous version in the editor's menu brings one back. They do not count toward the plan's storage, and they are deleted with the diagram.
Does the link change?	An organisation's diagram keeps its page, name and folder. Your own diagram gets a new public link, because a public picture is one picture; a stable link keeps its address and shows the new picture.
Keys	Cmd or Ctrl with S saves, with Z undoes, with Shift and Z redoes. Escape leaves the source. The keys for the picture are in Edit on the picture.

The editor fills the window: the page itself never scrolls, and the source, the inspector and the picture each scroll or pan inside. There is no page footer in the editor. On a phone the source and the picture are two tabs, and the save bar shows on whichever one is open.

Edit on the picture

You can also change the diagram on the picture itself. Every change there is written into the source as the smallest edit that makes it, the same edit_diagram operations an agent uses, so typing and editing on the picture share one Undo. Choose a box and its line in the source is chosen too; move the cursor in the source and its box is chosen on the picture.

To	Do this
Choose a box, a line or a group	Click it, or tap it on a phone. Hold Shift, Cmd or Ctrl as you click to add to the choice.
Change a label	Double click the box, or press Enter. Type, then Enter keeps it, Escape puts it back, and Tab goes on to the next box.
Change a type, an icon, a tone or a group	The inspector beside the picture shows the fields of what is chosen. On a phone it is a sheet from the bottom, and the picture moves so the box stays in sight above it.
Connect two boxes	Drag from a handle on a box's edge to another box. Let go on empty paper to add a new box joined to the first. On a phone, hold a finger on a box, then drag.
Add, duplicate or delete	The toolbar, or the commands (Cmd or Ctrl with K), which find any action and any box by name. A delete shows Undo for a few seconds.
See more of the picture	Fold the source or the inspector to a thin rail with the arrow button in its header, the toolbar, or the keys below. The editor remembers the choice in this browser. A folded source shows its error count on the rail.
Make the source wider or narrower	Drag the line between the source and the picture, or focus it and use the arrow keys. A double click puts it back. It only resizes and never folds a pane.

When the picture is drawn again after a change, its boxes glide to their new places. If you have asked your device for less motion, the new picture shows at once.

Key	On the picture
Tab, Shift and Tab	The next or previous box, in the order of the source
Arrow keys	The nearest box in that direction
Enter or F2	Change the chosen box's label
Delete or Backspace	Delete what is chosen, with its lines
C	Connect the chosen box to a box you pick from a list
N	Add a box
Cmd or Ctrl with D	Duplicate what is chosen
Cmd or Ctrl with A	Choose every box
Escape	Let go of the choice, or stop a connection
Shift and 2, Shift and 1	Zoom to what is chosen, fit the whole picture
Plus, minus, 0	Zoom in, zoom out, fit
Space, held	Drag the picture from anywhere, even over a box

Key	Anywhere in the editor
Cmd or Ctrl with K	Open the commands
Cmd or Ctrl with S	Save
Cmd or Ctrl with Z, with Shift and Z	Undo, redo
Cmd or Ctrl with a backslash (`\`)	Fold or open the source
Cmd or Ctrl with a full stop (`.`)	Fold or open the inspector

13. Where members publish

An organisation can decide where its members' diagrams go when they publish with an API key, an agent, the REST API or the GitHub Action. The owner or an admin sets it on the Settings tab, under Publishing.

Choice	What a member's publish does	Plans
Where each member chooses	Goes to the member's own library at a public link, unless they name this organisation. This is how every organisation starts.	Every plan
To this library by default	A publish that names no organisation comes to this library. A member can still ask for a public link.	Every plan
Always to this library	Nothing a member publishes gets a public link while they are a member. A request for a public link, a stable link, or a save over one of their own public diagrams is refused with `orgs.publish_required`, naming the organisation. Publishing to another organisation's private library still works.	Pro and Enterprise

Question	Answer
Who counts as a member?	Everyone in the organisation, every role, the owner included. With Always to this library, also anyone whose email address is on a domain the organisation verified for single sign-on, before they join. They cannot publish to the library until they join, so their publishes are refused.
How does a member ask for a public link?	With `personal: true` on `POST /v1/diagrams/publish` or on the agent's `publish_diagram`, or by asking for a stable link with `alias`. Under To this library by default that works; under Always to this library it is refused.
What does the answer say?	A publish the setting sent to the library has `private: true`, the organisation's id, handle and name, `routedBy` (`organisation-default` or `organisation-required`), and a `viewUrl` for members, with no public link. An agent tells you where the diagram went, and the GitHub Action's summary names the library.
What if I belong to several such organisations?	Choose a default organisation on the Organisations page, under Where my diagrams go. Without one, a publish that names no organisation is refused with `orgs.publish_ambiguous`, listing the organisations to choose from. Naming one with `organization` always works.
What about a reader?	A reader cannot publish to the library. Under To this library by default a reader's publishes stay personal; under Always to this library they are refused.
What about an organisation key?	Nothing changes. It publishes only to its own organisation.
What happens to diagrams members already made public?	Nothing is deleted when the setting changes. Under Always to this library the Settings tab lists the public diagrams each member published since they joined, with Move to library and Unpublish. Moving copies the picture into the library under a new id and removes the public link and the stable links that showed it. Unpublishing removes them without a copy, and cannot be undone. Both ask first, override the member's own lock, and are in the audit log.
What if the plan stops including Always to this library?	The choice is kept and works as To this library by default until the plan includes it again. Nothing becomes public by itself.

View links

A drawing answer from an agent or the REST API carries a viewUrl: an address of the portal's viewer with the diagram's source after #. It is not hosted and nothing is stored, because a browser never sends the part after # to a server. Anyone who has the address can see the diagram.

With Always to this library the owner or an admin can also tick Also hide view links from agents. The hosted MCP server and the REST drawing routes then leave viewUrl, svgUrl, pngUrl and saveCommand out of their answers for members and for the organisation's keys. This keeps an agent from offering a link that looks like a share link by default. It cannot stop a link from being made: the local MCP server, the CLI and anyone's own code build one from the source, which the member already holds.

What it does not cover

An account a member made with an address on a domain nobody verified is not held, because Plotwork cannot know it belongs to an employee. Verify your domains, and remove people who leave, by hand or through SCIM.

Doc	Why
Hosted diagrams	Publish to your own library at a public link, and how folders and keeping work
Plans and billing	What Free and Pro include, the daily call limit, and how to upgrade
Brand themes	Paint the organisation's diagrams in its own colors, on Pro
Audit log	Who changed what in the organisation, and the export to a SIEM on Enterprise
Custom icons	Upload the company's own logos for its diagrams, checked the way an avatar is
Editing existing diagrams	How an agent changes a diagram that already exists, which the browser editor works alongside
Connecting an agent	Connect the hosted server that has `publish_diagram`, `list_diagrams` and `delete_diagram`
MCP server	What the tools do, and how the local and the hosted server differ
API reference	Every route, and the error envelope
Single sign-on	Verify the domains whose people a required library holds before they join
Privacy policy	What is stored about accounts, organisations and diagrams