← All sections

Brand Layer · Technical overview

Architecture

What the system is made of, how a brand becomes sixteen surfaces, an MCP server and tools a browser agent can call, and which files matter when you change something.

Tools
21
Surfaces
16
Pages
15
Brand files
12

01 · Shape

How the whole thing fits together

A brand lives in a folder of Markdown and JSON. One loader parses it into a single typed object. Three consumers project that object: a showcase site for people, sixteen machine-readable surfaces for anything that can fetch a URL, and an MCP server for agents that speak the protocol.

Nothing generates assets. Every tool returns knowledge, and the agent on the other end builds the thing.

THE BRANDtokenscomponentsrulesvoicelayoutsiconsassetsguided-mode defaultsRead onceparsedrefs resolvedBRANDone typedobjectUI13 pagesSURFACES16 routesMCP21 toolsEvery consumer reads the same parsed object, so no two of them can disagree about a token.
One parse, three consumers

02 · Stack

What it is built on

Small on purpose. Eleven runtime dependencies, no database, no CMS, no build step for the content.
Runtime
  • next^15.5.0

    The site and the routes. Nothing is pre-rendered: every response resolves its own origin and re-reads the brand, so one deployment serves whatever the brand says today.

  • react^19.1.0

    Server-rendered by default. Interactive pieces are the exception, not the rule.

  • typescript^5.7.0

    Strict. The build type-checks before anything ships.

The MCP server
  • @modelcontextprotocol/sdk^1.13.0

    The protocol itself: tools, resources and prompts.

  • mcp-handler^1.0.2

    Puts that server behind one HTTP route and owns the transport.

  • zod^3.25.0

    The input schema for every tool, which is what a client reads to know how to call it.

  • zod-to-json-schema^3.25.2

    Turns those same schemas into JSON Schema for the two transports that are not MCP: the plain-HTTP catalog at /api/tool, and the WebMCP tools the page hands to an agent inside the browser.

The rest
  • gray-matter^4.0.3

    Reads the brand: the structured half of each document is the tokens, the written half is the rules.

  • fflate^0.8.3

    Builds the offline package. It takes an explicit timestamp per file, which is what makes the archive byte-stable and therefore worth hashing.

  • tailwindcss^4.1.0

    Utilities only. Brand values reach the page as CSS variables, never through a config file.

03 · MCP

The server, and what it exposes

One route handler at /api/[transport]. The path segment picks the transport: /api/mcp is Streamable HTTP, stateless, the one to use. /api/sse is the legacy transport and only completes a round trip when a Redis is attached, so treat it as deprecated.

The server is rebuilt per request against the freshly parsed brand, which is why every tool schema, asset URL and version string reflects the live content and this deployment’s host rather than whatever was true at build time.

INITIALIZEServer replies with serverInfo and instructions. The instructions landin the client's context before the agent decides anything.GET_SKILLCalled first, once per session. The routing guide: which tool answerswhich kind of task.GET_BRAND_OVERVIEWIdentity, the critical rule, and the URL of every surface.TASK TOOLSget_voice_guide before copy. get_chart_palette before a chart.get_component before UI. get_fallback for anything undefined.AGENT BUILDSThe asset is produced by the agent, in its own tool.The server never renders anything.
A session, in order

04 · Tools

The 21 tools

All read-only, all idempotent. Every answer comes from the brand as written, so the same call twice gives the same result.
ToolReturns
get_skillFirstThe versioned orchestrator skill: the routing guide that maps any task to the right tools.
get_intakeGuided mode: each output type's parameters and defaults, the one question worth asking, the report block, and the self-check.
get_brand_overviewThe first call: identity, the essentials (accent, canvas, the TEXT system with its rule and classes, the light surface, the font, the logo), the section index, the voice with its prohibitions, the critical rule and every surface URL.
get_design_specWithout arguments, the section INDEX with sizes. With `part` or a section id, that slice. The whole ~80 kB document only on request.
list_tokensA category, one token by `ref`, or several by `refs` in a single call. Colour and type payloads carry the rules that govern them.
get_componentOne component raw, resolved, what changes on a light surface, and a pasteable HTML snippet. No name lists them all.
get_sectionOne prose rule section by id or exact title.
search_designFull-text hits across every loaded content file, each tagged with the tool that serves it.
list_assetsLogos, fonts and icons as absolute hotlinkable URLs, plus a pasteable @font-face.
get_voice_guideThe writing brief by default: essence, the hard prohibitions, the language rule, personality, principles and a pasteable AI brief. Every other part by name.
get_linkedin_playbookPost types, copy anatomy, hooks, formatting rules, example posts.
get_sound_guideThe sound library: every track with an absolute MP3 URL, length, tempo and vocals, the track to use for each job, and the rules (house tempo, what sits under a voice, the sound logo last).
list_layoutsThe fast index: every layout as one flat row with its example image and SVG source, no canvas and no geometry.
get_layoutWithout id, the shared canvas and its legends, the call to make once per session. With id, that layout: slots, measured geometry in px, the must list, a reference SVG and the slice of the canvas it uses.
list_carousel_recipesEvery carousel recipe: an ordered sequence of layout ids per post type.
list_presentation_slidesThe 16:9 deck index: every slide type with its intent, density, limits, variants and example images, plus the deck rules. For planning a deck.
get_presentation_slideWithout id, the 1920x1080 deck canvas: type scale, spacing, colours, footer, text metrics. With id, that slide type: slots, must list and measured geometry where it exists.
list_iconsThe fast index: every icon as one flat row with dark and light URLs, or the matching icons with their keywords.
get_fallbackThe fallback contract: primitives to derive from, and the ordered anti-hallucination protocol.
get_chart_paletteThe data-viz palette: categorical ramp, sequential ramp, semantic deltas, and the rules.
get_agent_rulesThe rules of engagement, and rules only: the colour and type rules, the fallback protocol, the voice prohibitions, the value-free starting prompts and the critical rule. The values themselves live in the tools that own them.
4 resources
  • brand://design.md

    The design spec verbatim, frontmatter and all.

  • brand://skill.md

    The orchestrator skill as a resource, for clients that prefer attaching over calling.

  • brand://brand-guide

    The long-form identity prose from brand.md.

  • brand://llms-full.txt

    The whole knowledge base as one file, for upload into a client with no MCP.

3 prompts
  • linkedin-carousel

    Guided flow: pick a post type, pull its recipe and layouts, draft in the brand voice.

  • brand-brief

    Guided mode as a slash command: a one-sentence request in, defaults filled, choices reported back.

  • on-brand-page

    Guided flow: pull tokens and components, then build UI that cannot drift off-brand.

05 · Access

Five ways in

Client capability decides the lane, and there are deliberately only five: speak MCP, fetch a URL, take an upload, read a folder, or be an agent that lives inside the browser looking at the page. That is the whole space of what a client can do. A second surface inside any one lane is how these systems start contradicting themselves, so each lane has exactly one entry point.
LANE AClient speaks MCP/api/mcpget_skill firstLANE B1Client can fetch a URL/llms.txtindex, then read on demandLANE B2Client takes an upload/llms-full.txteverything, one fileLANE CClient reads a folder/bundle.zipknowledge + asset filesLANE DAgent is in the browserWEBMCPthe page registers its toolsSAME KNOWLEDGEone source, five shapes
Five lanes, one per client capability

06 · Surfaces

The 16 machine-readable routes

One code path serves twelve of them, so the content type, the caching, the absolute URLs and the 404 policy are decided once rather than per route. A route the brand does not fill returns 404 rather than an empty document. Two stand apart: /integrity.json hashes what the others produce, and /bundle.zip is binary and streamed.
RouteTypeWhat it is for
/llms.txttext/plainThe index. Lane B1 starts here: what exists, and where to read it.
/llms-full.txttext/plainEverything in one file. Lane B2 uploads this into a client that cannot reach a URL.
/skill.mdtext/markdownThe orchestrator skill, same content as get_skill.
/intake.mdOptionaltext/markdownGuided mode: the parameters, defaults and report block behind get_intake.
/bundle.zipapplication/zipThe offline package. Lane C downloads this: the knowledge, the orchestrator skill and every asset file as one folder (audio only where marked offline), streamed so the archive is not capped at a buffered response.
/integrity.jsonapplication/jsonSize and SHA-256 of every other surface and of the offline package, as served. For the review that happens before a connector is allowed.
/design.mdtext/markdownThe design spec source, unmodified.
/brand.jsonapplication/jsonEvery token as structured data, refs already resolved.
/brand.csstext/cssThe tokens as custom properties, a `.bl-{component}` class per component, the `.bl-light` surface scope and the responsive type queries. Hotlink it and the values are live.
/snippets.jsonapplication/jsonPasteable component HTML, styled by brand.css.
/layouts.jsonOptionalapplication/jsonThe slide catalog with absolute asset URLs.
/presentations.jsonOptionalapplication/jsonThe 16:9 deck catalog: canvas, deck rules and every slide type with slots, geometry and absolute image URLs.
/icons.jsonOptionalapplication/jsonThe icon library with dark and light URLs.
/verbal-identity.mdOptionaltext/markdownThe voice source. /voice.md redirects here.
/linkedin.mdOptionaltext/markdownThe LinkedIn playbook source.
/sound.mdOptionaltext/markdownThe sound library source: tracks, jobs and rules. The MP3 files themselves live under /brand/sound/.

07 · Invariants

Rules that hold everywhere

Four promises the system keeps, each one because breaking it produced a specific failure.

  • Read-only knowledge, not a generator

    Every tool returns brand data. The agent produces the asset. A render pipeline existed early on and was deliberately removed, because a knowledge base that also generates has two ways to be wrong.

  • Exactly five agent access lanes

    Lane A is MCP, entered through get_skill. Lane B1 is /llms.txt for a client that can fetch a URL. Lane B2 is /llms-full.txt uploaded as a file. Lane C is /bundle.zip, the offline package, for a tool that can do neither and for anyone who needs the asset files themselves. Lane D is WebMCP: the page itself registers a subset of the same tools with an agent built into the browser, which is the only lane that asks the reader for no setup at all. One surface per lane, and the orchestration logic lives only in the skill: the package ships that same skill at its root rather than restating it.

  • Defaults are declared, not guessed

    A short request leaves most parameters unset. Guided mode fills them from the brand's own declared defaults, and the agent reports every filled value back to the user. Nothing is decided silently, and the values it fills still resolve against the spec: a default points at an existing token, never at a new one.

  • The critical rule is authored once

    It is one field in the brand, written once. Every surface interpolates it. No route or component restates the prose, so it cannot drift between what an agent reads over MCP and what a human reads on the page.