How the Mesh should work

Working with Claude feels less like operating a system and more like thinking alongside a coworker. That difference matters. A coworker doesn't just execute what you ask — they help you plan, push back, generate options you hadn't considered, and make complex decisions legible. The quality of thinking that emerges from that relationship is different from what you get by querying a tool.

Planning complex work requires more than text. A coworker who can only communicate in paragraphs is limited. When Claude produces a structured comparison, a diagram that makes a tradeoff visible at a glance, a visual plan that couldn't exist in a chat message — that is the full bandwidth that real planning requires. HTML is the format that carries all of it: prose, structure, graphs, and spatial thinking in a single artefact that lives at a URL.

This starts solo: one person, thinking through a hard problem with Claude, producing something — a brief, a plan, a research synthesis — that is more than a conversation and more than a document. It extends to teams: that artefact enters the Mesh, and the thinking becomes shared ground. The Mesh is what makes the coworker relationship durable. Without it, every session starts from zero — the thinking is ephemeral, locked in a conversation that ends. With it, what was worked out, why, and what was decided persists. The coworker remembers.

The Mesh doesn't succeed because people are instructed to use it. It succeeds because using it is genuinely simpler than every alternative. If someone reaches for a Notion doc, a Slack thread, a hand-typed system prompt, or an email chain to capture working context, the Mesh has a friction problem — not a communication problem.

The north star: when you're in Claude, using the Mesh should be the natural move. Not a deliberate choice, not an extra step — just what happens when you work. Say something to Claude, it's in the Mesh. Want the team to know something, share it without leaving the conversation. Want to start a new session with full context, it's already there.

This means every design decision that adds a step, introduces a new interface to learn, or requires switching contexts is a threat to adoption. Frictionlessness isn't a feature — it's the adoption mechanism.

Most content creation and editing in the Mesh happens through Claude — not by someone sitting down to write a document from scratch. Claude writes a new section, refines an existing one, synthesises input from multiple sources, or updates a page because something changed. The human directs, reviews, and approves; Claude does the drafting and the typing.

This shifts the skill needed to maintain the Mesh from "willing to write documentation" to "willing to prompt Claude and review the output" — a much lower bar that scales to the whole team.

Concretely: a team member opens Claude Desktop or Claude.ai, has a conversation, and at the end says "save this to the Mesh" or "update the project brief with what we just decided." Claude writes it. The human confirms. It lands in the Mesh. No separate editing interface, no context switch, no documentation session.

The Mesh starts in single-player mode: one person, one Claude conversation, building context for themselves. This is the primary use case and it should be excellent on its own terms. A researcher building a personal knowledge base, a founder loading company context into a new session, an engineer grounding their agent in project decisions — all of this works without anyone else being involved.

But the architecture doesn't change when you go collaborative. The same Mesh that holds personal research holds shared team research. The same MCP a solo agent queries can be queried by a teammate's agent. Individual context can be promoted to team context deliberately, without rebuilding anything.

Collaboration happens across a spectrum of synchrony — from hours-apart async, to real-time-but-manual, to eventually automatic. The Mesh doesn't need to solve all three at once. Each tier builds on the one before it, and the first tier is already collaborative in a meaningful sense.

HTML has always been the most powerful format for human communication. A well-crafted HTML page is a better document than a Google Doc — richer layout, more expressive typography, purpose-built structure. An HTML presentation is a better artefact than a Keynote deck — not constrained by slide masters, not fighting a template. HTML with a canvas component is a better whiteboard than Miro — spatial, durable, shareable as a URL, no app required. These are not hypothetical claims. With a capable model, they are already demonstrable.

Markdown existed to solve a specific problem: authors who wanted structured content without learning to write markup. The tradeoff was deliberate — simpler input, simpler output. That was the right call when the alternative was typing HTML by hand.

But when Claude is the author, that tradeoff no longer exists. The input is natural language — equally easy regardless of what format Claude produces. The markup is not something the author writes; it's something the author reviews. At that point, Markdown's limitations become pure downside: it can't express rich layout, real diagrams, presentation structure, or spatial canvases. HTML can do all of these. The cost of the tradeoff disappears; the constraints remain.

This matters especially for people who have never used Markdown — which is the majority of knowledge workers. For them, "describe what you want, see an HTML page" feels exactly like "describe what you want, see a Google Doc." The output format is invisible when the author doesn't write it. What they feel is that the result is better.

When you prompt Claude to draft or update a section of the Mesh, what you're reviewing is an HTML document. Not a Markdown file — an HTML page with structure, visual hierarchy, tables, tree layouts, and spatial organisation that makes the content legible and useful. Editing it is closer to designing than writing. A schema definition, a process breakdown, a team structure — these have a graphic dimension: the way columns are laid out, the way a hierarchy is visualised, the way types are distinguished. That visual structure is part of the meaning. The HTML is the canonical thing. Claude edits it. You review it.

When an agent needs to load that content into context, it doesn't read the HTML markup. The system extracts clean Markdown from the document and delivers it without the tag overhead. The same content, leaner. This happens automatically — the agent asks for a section, it gets Markdown. No conversion the author has to manage, no separate source file to maintain.

This is not "Markdown source, HTML presentation." The HTML is the source. The Markdown is derived on demand at read-time. There is one document.

Today, Thibaut uses ClickUp Documents as an informal Markdown wiki — written and maintained by Claude via the ClickUp MCP. That's a workable starting point, and it validates the core model: agent as the author, shared document store as the backbone, human in the loop for review. The baseline works.

But ClickUp's MCP doesn't give the tools the Mesh actually requires. Section-level addressing, surgical edits, agent authentication, the protected-page review workflow, content freshness signals, three-level scope control, diff-only updates — none of these are available through ClickUp's API. The Mesh will outgrow ClickUp before it's fully built.

The canonical layer needs to be purpose-built around the Mesh's own requirements: HTML as the storage format with Markdown extracted on demand for agent consumption, section-level addressability as a first-class concept, controlled access at three levels, a clean agent-facing API, and a delivery path to Cloudflare. Given that Thibaut already builds on Cloudflare Workers and has established the pattern of building custom MCPs, the canonical layer is most likely a custom service on Cloudflare infrastructure — not a third-party platform the Mesh happens to be living in.

The Mesh is for the whole team — not only engineers, not only people comfortable with git or Markdown. Gating contribution to GitHub means the Mesh slowly becomes an engineering artefact, maintained by the people with commit access. Everyone else reads, but nobody updates it, and it drifts. You could technically give everyone a GitHub account, but that creates the exact friction the Mesh is designed to eliminate.

Anyone on the team should be able to prompt Claude to update a section, review a draft, or flag something that's out of date. That is the access model.

The Mesh is where content is created and edited — the purpose-built canonical layer that stores and serves HTML. GitHub is where that content gets versioned and backed up. The sync is one-directional and automatic — the Mesh pushes to GitHub on every write, nobody edits in GitHub. This gives the Mesh a full edit history, diffable changes over time, and a backup that survives any infrastructure incident or accidental deletion.

GitHub also enables future downstream hooks: regenerating static artifacts when content changes, notifying agents that a section has been updated, or triggering a review workflow for major changes.

Context is not one-size-fits-all. Some knowledge belongs to the whole organisation. Some is relevant only to a team. Some is a person's own working notes and research. The Mesh should support all three without conflating them — and without noise from lower levels polluting higher ones.

The principle: content does not propagate upward automatically. Moving something from individual to team, or from team to org, is a deliberate act. The org-level Mesh only contains what has been intentionally elevated. Everything else stays where it was created until someone decides otherwise.

The Mesh has two delivery surfaces — web and MCP — but those surfaces serve five distinct usage modes. Designing for the surfaces alone misses what each mode actually requires. The architecture must address all five explicitly.

The web surface is the team's read-only browser view of the Mesh — the same content accessible via MCP, surfaced in a browser instead of Claude. It is not open to the internet by default. Internal content is gated by authentication; external sharing happens only through specific, scoped, revocable links generated deliberately for named recipients. Those shared links work for both human reading and agent consumption — the recipient browses it in a browser or points an agent at the same URL. The MCP surface is internal, accessed via Claude, and serves three distinct modes: an agent loading context at session start, Claude answering a human's question, and Claude working alongside a human on a shared project. Same surface, different patterns, all requiring Markdown and section-level precision.

Some Mesh content is useful beyond the team — to customers, partners, contractors, or anyone being onboarded. That content should be shareable without requiring a Mesh account on the recipient's side, but the sharing should be deliberate and traceable. A link is generated for a specific purpose and a specific recipient. It can be revoked at any time, or given an expiry date. Nobody should be able to access internal Mesh content through an accidentally long-lived link.

Not all Mesh content should be editable by anyone at any time. Company policies, brand guidelines, and foundational "who we are" content carry real weight — an accidental or unconsidered edit can propagate to every agent and every person relying on that context. Those pages deserve a review gate.

The model: certain pages are designated as protected. Anyone can propose a change, but proposing means creating a draft version — a fork of the current page — editing it, and submitting it for review. A reviewer with merge rights sees what changed, decides whether to accept it, and either merges the draft or sends it back. The original page is untouched until a merge happens.

This is the pull request workflow — but designed for non-technical people who have never opened GitHub, built natively in the Mesh app.

The Mesh — both the MCP and the web surface — is not publicly accessible. It is an internal surface, reachable only by authenticated team members and their Claude sessions. A single authentication layer, Mesh Auth, controls access to both surfaces. The user authenticates once; their identity determines what they can see and do across MCP queries, web browsing, and edit operations.

An admin UI defines each user's rights — which scope levels they can access, and within those levels, which content is visible to them. Those rights are enforced identically whether the user is querying via MCP or browsing via the web. A user sees their individual content, their team's content, and org-level content — nothing from other individuals, nothing from teams they don't belong to.

The Mesh has two access points: the web UI for browsing without Claude, and Claude itself for everything else. That is the full footprint, by deliberate choice. No Slack bot, no Figma plugin, no ClickUp integration, no VS Code extension. Each additional integration surface is a maintenance commitment, a new failure mode, and a new context to design for. The Mesh stays small and focused.

For moments when someone isn't in Claude — a meeting, a Slack thread, a quick browse — the web UI is the answer. It requires no separate app, just a browser. For internal content, team members are authenticated via Mesh Auth. For shared external links, recipients access their scoped view without an account. The Mesh on a custom subdomain is the non-Claude surface, and it's designed to be good enough that reaching for something else isn't necessary.

The Mesh has two primary delivery mechanisms, and both must be designed for explicitly — not bolted on after the fact. Neither is a fallback for the other; they serve fundamentally different audiences with different expectations.

The first is a web surface: Mesh content on a custom subdomain, readable in any browser. Internal team members open it in a browser — Mesh Auth handles authentication. External stakeholders access only what has been explicitly shared with them, via a scoped, revocable link. The rendered page is what they experience — a new hire browsing the handbook, a partner reading what was shared with them, a recipient's agent consuming the same URL as Markdown.

The second is an agent surface: Markdown extracted from the canonical HTML, queryable via a Mesh-specific MCP. This is how Claude loads context at the start of a session, how an agent pulls the specific sections it needs, how the Mesh integrates into workflows without a human intermediary. The extracted content is the thing that matters here — readable by machines, lean by design.

Every token an agent loads from the Mesh is a token it can't spend on the actual task. A poorly structured Mesh that forces an agent to load 20,000 tokens of context to answer a simple question isn't a knowledge base — it's a tax. Token efficiency for agent consumption is a first-class design concern, not an optimisation to revisit later.

Markdown is the right format for agents — not HTML. HTML triples the token count for the same content with no added meaning for a language model. The agent surface stays in Markdown, always.

The web surface — what humans actually see — follows the team's brand guidelines. Not as a nice-to-have, but as a reflection that the Mesh is a first-class product surface, not a dumped wiki. Typography, colour, spacing, dark mode, and responsiveness are built in from the start.

The visual philosophy is essentialist: less is more. The Mesh does not try to display everything at once or make the structure visible by default. Content gets space to breathe. Navigation is available when needed, not always in the way. The experience should feel like reading, not like browsing a filing cabinet.

Structure alone isn't enough. The three-level scope model and clear section hierarchy make navigation possible, but they assume you already know where to look. A team member who needs to know what the Mesh says about a topic, or an agent that needs to ground itself in relevant context before starting a task, can't rely on browsing. They need search.

Search is a first-class feature on both surfaces. The web UI has full-text search for humans. The MCP surface has a dedicated search tool for agents. Both are fast, both return content at section granularity, and both are strictly scoped to what the caller is allowed to see. Search doesn't bypass the access model — it enforces it.

When a piece of content in the Mesh needs a one-word change, the system should not have to rewrite and re-emit the entire document. Surgical editing — updating a sentence, a paragraph, a value in a table — must be a first-class operation, not a workaround that forces fetching the whole page, making a change, and writing it all back.

This matters for efficiency (token cost, latency), for change tracking (a surgical edit produces a meaningful diff; a full rewrite produces noise), and for the review workflow (a reviewer should see exactly what changed, not reconcile two complete documents).

The natural way to work with the Mesh is not to write in one place and then check the result in another. It's to have the conversation and the document visible simultaneously — Claude on one side, the live content on the other. As Claude makes a change, it appears. The human reviews, redirects, or approves in the same view without switching contexts.

This is the editing experience that makes iterative refinement feel effortless rather than mechanical. It's what makes the difference between "Claude as a writing tool" and "Claude as a genuine co-author of the Mesh."

When something in the Mesh changes, the people affected by that change should find out. Today, this is manual: the person who made the change pings whoever needs to know. That relies entirely on the editor knowing who cares, remembering to tell them, and doing it promptly — three assumptions that degrade as the team and the Mesh grow.

The design direction is a subscription model: each person subscribes to the pages or sections they want to follow, and changes to those items reach them through a channel they already use. This scales better than scope-based broadcast (which becomes noise as the Mesh grows) and better than relying on the editor to notify (which requires them to know who cares). The right audience self-selects. The one exception is protected org-level changes — those always reach the whole team, regardless of subscriptions.

The Mesh is the context layer for the whole team's work — and work happens across multiple tools. A developer tracks progress in ClickUp. A designer works in Figma. Client communication runs through Missive. The Mesh provides the context that informs all of it, but the person doing the work shouldn't have to hold that connection in their head.

Any tool in the workflow can link to a Mesh page, and any Mesh page can surface what's linked to it from across the toolchain. A Missive thread handling a client's onboarding links to the onboarding Mesh page. A Figma file links to the brand guidelines section. A ClickUp engineering task links to the architecture decisions that govern it. From those Mesh pages, the associated work is visible and navigable in return.

This is not data sync. Nothing is duplicated. The link is the only thing that crosses the boundary — a URL on each side, with enough metadata to be useful. Each tool stays independent; the Mesh is the shared anchor.

Stale context is worse than no context. An agent or a person grounding themselves in a Mesh section that describes how something used to work will act on outdated information — confidently. A gap in the Mesh is visible and handleable. A wrong answer in the Mesh is invisible and dangerous.

There is no automated freshness system — for now. Keeping the Mesh current is a team responsibility and a cultural expectation. The mental model: updating the Mesh is part of completing a change, not an afterthought that follows it. A process changes → the Mesh page for that process is updated in the same motion. A decision is made → it lands in the relevant Mesh section before the meeting ends. A policy is revised → the old version is gone before anyone has a chance to read it.

The Mesh is only as good as its accuracy. The team is the last line of defence.

The Mesh starts empty. When it launches, each person responsible for a piece of content migrates it over — there is no automated bulk import. Migration is deliberate: each content owner reviews what they own, decides what belongs in the Mesh, and brings it in with Claude's help. This is not a limitation — it's an opportunity to discard outdated content rather than inherit the entropy of every existing document.

Most source content is already in ClickUp as Markdown. The migration process is: a human opens Claude, loads the relevant Mesh context, and asks Claude to convert and structure the content correctly. Claude does the conversion; the human reviews and confirms.

What makes this work is that the Mesh's own research and principles are the context Claude needs to migrate correctly. The format decision (Markdown source, HTML artifact), the brand guidelines, the section structure, the content matrix — all of it is already in the Mesh by the time migration starts. Claude reads the Mesh to learn how to contribute to the Mesh.

AI makes it trivially easy to generate content. That's part of the value — but without intentionality, a team can accumulate a vast, low-quality Mesh faster than anyone can maintain it. The Mesh should work against this. The goal is not a large Mesh; it's a useful one.

Intentionality shows up at every stage. During migration, it means resisting the urge to bring everything over and asking instead: what does someone actually need to know to do good work here? During creation, it means writing for an audience — being clear about who will read this, what they need, and how the content should serve them. During promotion, it means treating the act of sharing more broadly as a quality checkpoint: is this ready to be ground truth for the people who'll rely on it?

In the age of AI generation, the limiting factor shifts from effort to judgment. The Mesh is only as good as the quality of the decisions behind it.

Karri Saarinen put it plainly in Output isn't design: AI agents generate plausible outputs quickly, but they do not necessarily help you understand the underlying problem. In practice, they often do the opposite — they generate outputs instead of first trying to shape the problem to the real conditions. The risk is mistaking generated form for solved problems.

The value of working with Claude isn't primarily what it produces. It's the understanding you build along the way. Spend two hours talking through a strategic decision, a product direction, a customer situation — structuring ideas, weighing tradeoffs, doing research, stress-testing assumptions. Then produce something. The artifact is the last mile. The understanding is everything before that.

This is what the Mesh is designed to support and preserve. Not a faster way to generate documents, but a deeper way to think — and a way to make that thinking persistent and shared. The session ends; the understanding shouldn't have to.