Concepts

VegaStack is built around a handful of nouns: spaces, folders, pages, grants, teams, and review events. Everything else — comments, templates, audit, search, the agent surface — is layered on top.

Spaces, folders, and pages form a tree

A space is the top of the access tree. Every folder and page belongs to exactly one space; folders nest in folders and hold pages, all within the same space. Access resolves over this tree: a grant on a space or folder inherits down to everything beneath it. A workspace ships with a default My Space; admins can create more.

Source is authoritative

Pages store source (Markdown, MDX, or HTML). The renderer turns source into HTML; reads serve the rendered HTML, never raw source. Editing a page updates the source and re-renders. The rendered HTML is cached by content hash, so it refreshes automatically after a save — there is no frozen public snapshot. Public visitors and signed-in members serve the same live render. On save, the server stamps a vegastack_* metadata block into the source (markdown frontmatter or HTML <meta> tags) — round-trip output for backup and export only; the Postgres typed columns remain the source of truth for routing and queries.

Grants are how access works

A grant ties a subject — a user, a team, or the workspace ("everyone") — to a space, folder, or page at a role (viewer, commenter, or editor). Grants are additive and inherit down the tree; the strongest grant along a page's path wins. Membership is just holding a space-level grant — there is no join/leave. A space with an "everyone" grant is "open" (in everyone's sidebar); otherwise a space's visibility is discoverable (its name shows in Browse, but content stays locked until you're granted) or private (invisible to non-members). Workspace admins have full access everywhere; space creation and deletion are admin-only. See Permissions.

Teams group members

A team is an admin-managed, named set of workspace members (Settings → Teams). Teams can be the subject of a grant, so you can give a whole team access to a space or folder at once. Removing someone from a team removes the access it conferred.

Sharing — internal and external — is managed from one Share sheet, mountable on any space, folder, or page. It lists the "everyone" grant, people and teams with access, a space's discoverability, and the public link ("Anyone with the link": none/view/comment plus optional password, expiry, and search-engine indexing). The public link gates public access; the page is served live, so a public page always reflects the latest save. Anyone with view+ can copy the link; editing the sheet is editor+. See Public links.

Review events are the agent loop

Every comment created, resolved, or replied to emits a review event. The wait_for_review MCP tool blocks until a matching event appears, so an agent can update a page and wait for a human to approve before sharing it.

What ties it together

The nouns share the same audit log and the same renderer. Spaces sit at the top of the access tree and grants inherit down it, so the surface stays small for agents and predictable for reviewers.