Browse the published catalog as compact summaries: slug, name, summary, tags, audience, a font and palette glimpse, tier, and computed discovery facets covering use-case fitness from 0 to 100, moods, and industries. This is the main entry point for finding a design kit. Filter by what the user is actually building: use re-orders the catalogue for that surface rather than narrowing it, each kit carrying a fitness score measured on its own tokens, and q runs a synonym-aware ranked search that understands phrases like 'calm fintech dashboard'. Results are paginated and report the total plus the next offset, so page rather than assuming the first response is the whole catalog. Summaries carry no tokens, no DESIGN.md, and no font files; pull one kit with get_design_md or get_tokens, or apply_theme to write it into the project. Prefer search_themes when the brief is too subtle to rank against a lane and you want to weigh the entire catalog yourself. Read-only and free, and it lists Pro kits without exposing their contents.

Browse image directions, which decide how a project's photography and illustration should be made: the process, treatment, and subject matter. Use one when a kit is chosen but the imagery still has no direction, which is where most agent-built pages fall back to stock-looking filler. Returns judgment summaries with no export payload, so pick a slug and call get_image_direction for the implementable version. A direction sits alongside the design kit and never replaces it; the kit still owns color, type, and brand rules. Read-only and free, and Pro records appear in the list without exposing their contents.

Retrieve one image direction's full implementation export, as Markdown for reading and briefing or JSON for programmatic use. This is what you follow when generating, sourcing, or art-directing imagery for the project, and it pairs with the design kit rather than replacing any of it. Read-only: it returns the text and writes nothing to disk. Free records are public; a Pro record returns 403 with an upgrade path unless the key is entitled, without leaking the payload.

Browse interface styles, which decide how surfaces and hierarchy render: how panels stack, how density and depth read, how structure is expressed. A style is a neutral render grammar you apply through a design kit, not a second source of palettes, fonts, or brand rules, so it answers how the UI is built rather than what it looks like. Use one when the kit is settled but the layout still defaults to generic cards on a grid. Returns judgment summaries with no export payload; pick a slug and call get_interface_style for the implementable version. Read-only and free, and Pro records appear in the list without exposing their contents.

Retrieve one interface style's full implementation export, as Markdown for reading or JSON for programmatic use. The export holds render-grammar rules only, so combine it with a design kit's tokens, typography, motifs, and brand rules; on its own it will not give the UI an identity. Read-only: it returns the text and writes nothing to disk. Free records are public; a Pro record returns 403 with an upgrade path unless the key is entitled, without leaking the payload.

Browse page recipes, which decide how a page argues its case: what it leads with, in what order it earns belief, and what the reader should walk away knowing. Use one when you know what a page must achieve but not how to sequence it, which is the gap that produces hero-features-pricing pages by default. Returns judgment summaries with no export payload; pick a slug and call get_page_recipe for the implementable version. Each record carries a model field: most are legacy-sequence, which prescribes a section order, while communication-idea records state the argument and leave the sequencing to you. Read the model before following a record, since the two ask different things of you. This covers structure and argument, not visuals; the design kit still owns those. Read-only and free.

Retrieve one page recipe's full implementation export, as Markdown for reading or JSON for programmatic use. This is what you build the page's structure and argument from, and it pairs with a design kit, which still supplies the visual and interaction rules. Read-only: it returns the text and writes nothing to disk. Free records are public; a Pro record returns 403 with an upgrade path unless the key is entitled, without leaking the payload.

Return the entire catalog at once, unranked, as compact summaries carrying each kit's moodSummary, vibeTags, tags, audience, and a font and palette glimpse, so you can judge fit yourself. Despite the name it runs no server-side search: query is echoed back to keep your brief in context, and the ordering is neutral. Use it when the brief is subtle or cuts across categories and you would rather weigh every option than trust a ranking. Prefer list_themes when the brief maps cleanly onto a use case or search phrase, since it ranks the catalog for you and pages rather than returning everything. Neither tool narrows the catalog; the difference is ranked and paged against unranked and all at once. Read the summaries, pick one to three, then get_design_md to read the full brief or apply_theme to write it into the project. Read-only and free.

Find published kits close to one you already have, ranked by palette proximity, shared tags, and audience. Use it when the user likes a direction but wants options, or when a candidate is nearly right and you want neighbours to compare. It needs an existing slug, so start from list_themes or search_themes if you do not have one yet. Returns compact summaries with a similarity score; judge the actual fit yourself, since proximity in palette and tags is a starting point rather than a verdict. Read-only and free, and it lists Pro kits without exposing their contents.

Rank published kits by how close their palette sits to colors the user already owns, using perceptual color distance rather than string matching. Use it when a brand has existing colors that the design system has to live with, such as an established logo. This ranks on color alone and ignores mood, audience, and use case, so treat the result as a shortlist and check the rest of the fit with get_design_md before committing. When the user has no fixed colors, list_themes or search_themes will serve them better. Read-only and free.

Fetch the complete DESIGN.md brief for one design kit (theme) by slug: the palette in prose, typography, layout and surface rules, elevation and shape, distinctive motifs, iconography, imagery direction, and explicit do's and don'ts. This is the document you design from. Read it before implementing a kit, or when the user wants to review a direction before committing to it. Read-only: it returns the text and writes nothing to disk (apply_theme is the tool that writes it into a project). Free kits are public; a Pro kit returns 403 with an upgrade path unless the key is entitled, without leaking the brief.

Fetch one design kit's machine-readable tokens in the format that matches the target stack. It covers all 28 semantic color roles in both light and dark, plus typography and spacing. Use it to wire a kit into an existing styling layer when you do not need the written brief; pair it with get_design_md when you also need the rules. Read-only: it returns the file contents as text and writes nothing to disk. apply_theme writes tokens and DESIGN.md into a project in one step. Free kits are public; a Pro kit returns 403 unless the key is entitled.

Write a design kit into a project on disk: DESIGN.md, a tokens file named for the chosen format, and identityforge.json, a stamp recording the applied kit and a hash of every file written. This is the only tool here that touches the filesystem. It reads the stamp before writing, so it can tell its own output from the user's work. A file that already exists but is not recorded in the stamp, or one whose content changed since it was written, is a CONFLICT: by default the tool then writes NOTHING, names every conflicting file, and returns an error, so a hand-written DESIGN.md survives. Files whose content already matches the kit are left untouched. Set preview to plan without writing anything at all, and force to overwrite conflicting files, which destroys their current content permanently with no recovery path. Everything is computed before the first write, so a failed fetch cannot half-apply. Call it once the user has settled on a kit; get_design_md and get_tokens inspect a kit without writing. The stamp also records the kit's permanent id and its version as the export reported them, which is what a later apply diffs against: re-applying tells you whether the kit itself moved to a new version, or whether only the rendered file changed. A version of null means the export did not report one, and must never be read as version 0. Free kits are public, and a Pro kit returns 403 unless the key is entitled.

Read the identityforge.json stamp in a project on disk and report what has moved since apply_theme wrote it. Takes no kit and no version: the stamp holds both, which is what makes this the tool to reach for when returning to a project rather than reconstructing the arguments for diff_kit_versions by hand. It reports THREE independent movements and never conflates them. kitMoved: the server's own version count differs, so the design itself changed and the brief is worth re-reading. documentMoved: the rendered DESIGN.md bytes differ, which a serializer change alone does to every kit at once and is not by itself a reason to touch code. contractMoved: designMdContract differs, so the document's SHAPE changed and a section was added, renamed or removed. Each is null rather than false when one side cannot answer, with a note saying which. When the kit did move and both versions are numbers, the diff_kit_versions result is included, so one call answers both what moved and how. It also hashes every artifact the stamp recorded against what is on disk, so a DESIGN.md edited by hand shows as modified before anything overwrites it. Read-only: it writes nothing and touches no file, so it is safe to call at the start of any session. Losing a key or hitting a Pro gate degrades it to a local-only report with a note rather than failing.

List every public naming strategy Identity Forge can generate from, with each recipe's id, intent, generation instruction, and settings. Call it before generate_names so you pick 1-8 recipe ids that genuinely fit the brief instead of guessing at strategy names. Recipe ids are stable, so you can skip this once you already know the ones you want. Read-only, free, and needs no arguments.

List the persistent naming boards owned by the connected key, with each project's id, name, brief, researched TLDs, chosen name, and candidate counts. Start here to recover the projectId for an existing brief, since every other naming tool needs one, and only call create_naming_project when nothing here fits. Read-only, paginated, and free. Requires the naming:read scope.

Create one durable, project-owned naming board and return its id. Do this ONCE per real naming brief, never once per generation run: every other naming tool takes the resulting projectId, and the board persists the candidate kanban, research evidence, and generation ledger across sessions so the shortlist never lives only in chat. Call list_naming_projects first and reuse an existing board rather than creating a near-duplicate. Write the real brief into description, because generation quality depends on it. Requires the naming:write scope; creating a board spends no AI credits.

Generate brand names with Identity Forge's own operator-owned model and persist them to the project board's generated column with full model, prompt-version, and credit provenance. SPENDS the key owner's AI credits, one per uniquely persisted name, charged only after the rows commit, so a failed run costs nothing. Always pass a stable idempotencyKey so a retry after a timeout cannot bill twice. Use it when you want Identity Forge to author the names; if your own agent or an offline process produced them, use add_name_candidates instead, which is free. Requires the naming:write scope.

Read one project's candidate kanban. Returns each persisted name with its status, rank, notes, attached research evidence, originating recipe, generation provenance, and an updatedAt timestamp you pass back to move_name_candidates or rank_name_candidates to guard against stale writes. Filter by status to review a single column, such as just the shortlisted or finalist names. Read-only, paginated, and free. Requires the naming:read scope.

Persist 1-50 names your own agent, another model, or manual research produced onto the durable project board, so a shortlist never lives only in the chat transcript. This is the free counterpart to generate_names: it stores names rather than authoring them, and spends no AI credits. Each item needs a caller-generated UUID, which makes retries safe. Sending identical data again returns the same row; reusing an id with changed data returns a conflict instead of silently overwriting. Requires the naming:write scope.

Read the generation ledger for one project: every generate_names run with its request fingerprint, recipes and settings, model, prompt version, how many names it produced, how many credits it reserved and actually consumed, final status, and timestamps. Use it to answer where a given set of names came from, or to check whether a run that appeared to fail actually charged anything before retrying. Read-only, paginated, and free. Requires the naming:read scope.

Progress up to 100 candidates through the kanban in one atomic write, and optionally replace their notes and evidence at the same time. Columns run generated, reviewing, shortlisted, finalist, selected, and rejected. This is the tool for recording a decision and why you made it; rank_name_candidates only reorders and leaves status alone. A project can hold exactly one selected candidate, and selecting one also sets the project's chosen brand name, so treat that move as the final call. Pass expectedUpdatedAt from list_name_candidates to reject a write when the row changed underneath you. Requires the naming:write scope.

Assign explicit user-facing priority ranks to up to 100 candidates on one naming board in a single atomic write, so every ranking applies or none does. Rank 1 is the highest priority and ties are allowed. This changes ONLY the rank field: kanban status, notes, and evidence are left untouched, so use move_name_candidates when you want to progress a candidate or record a decision. Use it to express a deliberate shortlist order for the user, not to record research. Requires the naming:write scope; it spends no AI credits.

Load everything you need to plan naming research in one call: the project brief, up to 100 candidates with the evidence already attached to them, which factual checks are available, workflow guidance, and a template for handing bounded questions to sub-tasks. Call it before orchestrating substantial research so you do not re-run checks that already exist on the board. It deliberately does not rank candidates, score them, or tell you which model to delegate to, because that judgement stays with you. Read-only and free. Requires the naming:read scope.

Run up to 20 web searches you author yourself against a candidate name, for existing-company collisions, market context, meaning, unfortunate readings in another language, negative associations, or official registers. You write the queries because you know what would disqualify this particular name. Returns dated raw results and nothing else: it does not score, rank, decide whether a collision is real, or constitute trademark clearance. Read the results, form your own view, and attach both the evidence and your interpretation to the board with move_name_candidates. For domain registration and DNS evidence use check_domains instead. Requires the naming:read scope.

Screen one owned naming candidate against EUIPO's verbal-element register, optionally within up to 10 Nice classes. This uses Identity Forge's shared EUIPO daily, burst, fair-share, and provider-cooldown quota; a 429 includes the allowance and retry timing. Results are preliminary evidence, not a similarity verdict or legal clearance. Requires naming:read.

Check up to 20 bare domains and return four independent kinds of evidence: RDAP registration records via IANA bootstrap, live DNS, real-time Cloudflare Registrar availability with pricing, and optional search results showing who else already occupies the name. Each is reported separately rather than collapsed into one available or taken verdict, because a domain with no DNS can still be registered and parked. Results are a snapshot: they reserve nothing, and a domain can be taken between this call and checkout. Use search_name_evidence for broader name research that is not domain specific. Requires the naming:read scope.

Author a new design kit, either from scratch by passing a kit JSON or by forking a published catalog kit with base and applying overrides for tokens, colors, fonts, and facet presets. Use base whenever a catalog kit is close to what you want, since a fork inherits a complete, coherent system and you only state the differences. Authoring from scratch means supplying the whole thing. The result is always PRIVATE and visible only to your key until you publish it from the web Studio; this tool cannot publish. Forking a Pro catalog kit needs an entitled key. Use remix_theme instead when you want several quick variations off one direction. Requires the kits:write scope, so regenerate your key with identityforge login if you get a 403 naming it.

Copy an existing kit into a new private kit with overrides applied. The source can be your own kit, a catalog kit, or another user's public kit. This is the fast path when you want three or four variations on one direction: call it repeatedly against the same source with different overrides. The original is never modified. Reach for create_theme instead when you are authoring a kit rather than varying one. A Pro-tier source needs an entitled key, and the copy is private until you publish it from the web Studio. Requires the kits:write scope.

Create the container that holds brand variations and the client share link. Do this once per client brief, then attach several directions with add_brand_variation and send the client a link with share_brand_project. Creating a project on its own shows the client nothing, so it is only the first of those three steps. Call list_brand_projects first to avoid making a second project for a client who already has one. Requires the kits:write scope.

Attach one brand proposal to a project: a kit plus an optional brand name, domain, label, and notes. Call it four or five times per project with deliberately contrasting kits, because a client choosing between similar directions cannot tell you much. The kit must be one you can resolve, meaning your own, a catalog kit, or another user's public kit, and a Pro catalog kit needs an entitled key. Variations become visible to the client only once you call share_brand_project. Requires the kits:write scope.

Publish a project to a client and return the full /p/ URL to send them. The page is read-only, serves only this project's kits, and lets the client cycle the variations and leave comments without an account. Anyone holding the link can open it, so set a password for sensitive work. Calling it again returns the existing link unchanged unless you pass rotate, which mints a new token and permanently breaks any link already sent. Add the variations before sharing, since the client sees whatever is attached at the moment they open it. Requires the kits:write scope.

Read one board in full: every variation with its kit, brand name, domain, label and notes, plus the state of the client share and a URL for each direction. list_brand_projects gives you summaries and a variation COUNT; this is how you see what is actually on the board. Use it to check your own work after attaching variations, to answer 'what did we send them' without keeping notes of your own, and to read the share state before you change it — whether a link exists, whether it is still serving, whether it has a password, and how many times the client opened it. A project that is not yours, and an id that could never be one, both answer 404 alike, so this cannot be used to find out what exists for somebody else. Read-only and free. Requires the kits:read scope.

Change an existing client link WITHOUT reissuing it. enabled: false pauses it, so the client sees nothing until you resume; password sets one after the fact, and null removes it. The token is untouched, so a link already with the client starts working again the moment you resume. This is the tool to reach for when work is mid-revision and the client should not be looking yet, or when you shared something before realising it was confidential. It takes effect immediately for anyone holding the URL, including a client with the page already open. A project with no share yet answers 404: create one with share_brand_project first. Requires the kits:write scope.

Withdraw the client's access permanently. The /p/ URL stops resolving wherever it was pasted, including in an email already sent. NOT UNDOABLE: sharing again mints a new token and deliberately never the old one, so a withdrawn link can not be brought back to life. This tool requires confirm: true; without it nothing changes. Reach for update_brand_share with enabled: false instead when the client should see it again later — that is the reversible one, and it is almost always what is wanted. Revoking is for a link that leaked or an engagement that ended. The project, its variations and the comments the client already left all survive; only the access is withdrawn. Requires the kits:write scope.

Permanently delete one of your saved design kits. This cannot be undone, so pass confirm: true only after you are sure. A kit referenced by a brand project is refused with 409 kit_in_use; retire or repoint those references before trying again. Requires the kits:write scope.

List every brand project owned by the connected key, each with its name, brief, variation count, and whether a client share link already exists. Start here to find a projectId before add_brand_variation or share_brand_project, and to check whether a board for this client already exists instead of creating a duplicate. Read-only and free: it takes no arguments, returns all projects at once (no pagination), and changes nothing. Requires the kits:read scope.

Queue photographic mockups for selected variations and template scenes. This spends one AI credit for every variation and scene combination after the server resolves the selected kits; failed enqueue attempts are refunded. The response contains the job id and polling URL. Requires kits:write.

List one brand project's mockup jobs newest first, including status, progress, errors, and completed result URLs. Read-only. Requires kits:read.

Poll one mockup job in its project for status, completed count, errors, and result URLs. Read-only. Requires kits:read.

Edit a design kit you already saved, in place. This OVERWRITES the stored kit without asking: the slug, id and publication state all stay the same, so everything already pointing at that kit follows the edit, including brand variations that reference it, any client share link that serves it, and a repo that installed its registry entry. The overwrite itself has no undo, but it is recorded: every save mints a version, so the state you replaced stays readable through list_kit_versions and get_kit_version, and diff_kit_versions shows exactly what your edit moved. Reach for remix_theme instead when you want the original left alone, which is usually the right call while you are still exploring directions; use this one when the kit is the brand and the brand has genuinely changed. It only edits kits saved under your key. A catalog kit, another user's kit, or an unknown slug all return 404 alike. kit is deep merged over the stored payload, so you state only what moves and everything else survives, and overrides applies on top of that merge. The one thing you cannot change is the slug itself: it is the kit's public handle and moving it would break every link already using it, so a payload carrying a different slug is rejected with 400 rather than quietly ignored. Pass expectedUpdatedAt from the last read to get a 409 instead of silently overwriting a change someone else made in between; the 409 body carries the current marker so you can re-read, reapply and retry. Requires the kits:write scope.

Edit one brand proposal already attached to a project, in place. This OVERWRITES the stored variation, and the client sees the new version the moment they next load the share link, including a client who has the page open right now, so treat it as publishing rather than drafting. Send only the fields that move; passing null for brandName, domain, label or notes clears that field rather than leaving it. Changing kitSlug repoints the proposal at a different design kit, which re-checks that you can resolve that kit and that a Pro kit has an entitled key behind it. Use it to act on client feedback from list_client_comments without making the client re-review a whole new set of directions. Add a new direction with add_brand_variation instead when the old one should stay on the board. Requires the kits:write scope.

Permanently DELETE one brand proposal from a project. The client stops seeing that direction on their next share view, and the comments they left on it go with it. This cannot be undone, there is no archive, and confirm: true is required, so read list_client_comments first if the feedback on that direction still matters. The surviving variations keep the positions they already had, which leaves a gap in the sequence rather than closing it, so follow with reorder_brand_variations when the order the client meets them in matters. Use update_brand_variation instead when the direction should be revised rather than retired. Requires the kits:write scope.

Set the order the client meets the directions in. The share page walks the variations in this order, so the first id is the direction the client sees first, which is worth deciding deliberately rather than leaving on the order you happened to attach them in. This OVERWRITES the stored order of the whole project and takes effect on the client's next view. You must list every variation in the project exactly once: a partial list is rejected with 400 and the expected id set, because writing positions for only some of them would collide with the ones left behind. Get the current ids from the response of add_brand_variation, or from a previous call to this tool, which returns the variations in their new order. Requires the kits:write scope.

Read what the client wrote on a project's variations through the share link, oldest first, with the variation each comment is attached to and the author's display name. This is the return leg of the share loop: without it you can build a brand project, attach directions and send the link, but never learn what the client actually said about them. Call it before revising, then act on it with update_brand_variation, update_theme, or remove_brand_variation. Anonymous commenters appear as 'Guest' rather than an id, and deleted comments are omitted. Read-only, changes nothing, takes no pagination. Requires the kits:read scope.

The kit's VERSION timeline, newest first: which version, when, by whom, and the author's note. Use it to answer the question a repo built against this kit actually has, which is whether the kit has moved since. It is not the full history: a version is minted only when the kit is created or saved, so applying the kit to a brand appears nowhere here. list_kit_history is the wider record and includes those. Metadata only, so no tokens come back; get_kit_version returns a whole snapshot and diff_kit_versions says what changed between two. Versions exist only for kits saved under an API key: a curated catalog kit is shipped rather than edited, so its timeline is empty and meta.currentVersion is 0. That 0 means no version has been minted, which is a real state and not a missing value. Paginated newest-first through meta.nextBefore. For a Pro kit you are not entitled to, rows still come back but the free-text label is null, because an author's note can restate a token you may not read. Free to call, needs kits:read.

The full snapshot a given version recorded, as it was at that moment. Reach for this when you need the old values themselves, for example to see what a token was before an edit replaced it; diff_kit_versions is the cheaper answer when you only need to know what moved. The response is a whole design kit, so it is large. A version number is permanent: version 3 is version 3 forever. This returns the entire payload, so it is gated exactly like an export, and a Pro kit without an entitled key answers 403 rather than a redacted body. Needs kits:read.

What changed between two versions of a kit: a list of paths with the old and new value, the CSS custom property a token change drives, and a mechanical summary. This is the tool for taking a brand change into a codebase, because it tells you the handful of things to update rather than making you re-read a whole DESIGN.md. Pass from alone to compare against the current version, which is the usual question: from is the version your repo recorded in identityforge.json. Pass both to pin a range. It reports what moved and does not judge how big the change is; whether a token shift matters to your UI is your call, not a number we invent. For a Pro kit you are not entitled to, every change comes back with redacted: true carrying the path, kind and CSS variable but no before or after, and redactedChanges counts them, so you can still see the shape of the change and know exactly what is withheld. Needs kits:read.

Everything that has happened to one of your saved kits, newest first: its creation, every save, and every time it was applied to a brand. Wider than list_kit_versions, which only sees the events that minted a version — an apply-to-brand event appears here and nowhere else, so this is the tool that answers whether a kit was ever actually used rather than merely edited. Each row carries an event id; pass it to get_kit_history_event for the full kit as it stood at that moment. Metadata only, so no tokens come back here. Only kits saved under an API key have a ledger: a curated catalog kit is shipped rather than edited, and asking for one answers 404 rather than an empty list, because you do not own it. Paged by an OPAQUE cursor, not by a number — hand meta.nextCursor back unchanged rather than constructing one, and a cursor this endpoint did not issue is rejected rather than silently restarting from the top. Free to call, needs kits:read.

The full kit recorded at one line of the ledger, which is what makes the timeline useful rather than decorative: with it you can diff a past state against the current kit, or PATCH the payload back through update_theme to restore it. The response is a whole design kit, so it is large — call list_kit_history first and fetch only the entry you want. Knowing an event id is never sufficient on its own: the event must be yours AND on a kit you still own, and either test failing answers 404 identically, so a 404 here does not tell you which of the two it was. Needs kits:read.

The brand project's history, newest first: what changed, when, and by whom. Owner-scoped, so a project you do not own answers 404 exactly as a missing one does, and there is no tier gate. The timeline records the whole brand: its name and domain, its fonts, its pinned layers, its project context, and its variations, including a reorder. Sharing is deliberately absent, because who may see a brand is not what the brand is. An empty timeline means the project has not been written since versioning was wired, not that nothing has happened to it. Free to call, needs kits:read.

The full snapshot a given version of a brand project recorded. Owner-scoped, like the rest of the brand-project surface. A brand snapshot references its kit rather than embedding it, so this never hands back a Pro kit's tokens by another door. Needs kits:read.

What changed between two versions of a brand project. Pass from alone to compare against the current version. Owner-scoped, so nothing is redacted: you are reading your own brand. Variation edits appear here as variations.<id>.<field> rather than as a wholesale swap, because a variation is identified by id and can be followed across a reorder. Needs kits:read.

Your plan, the scopes this key holds and the ones it lacks, how much of the monthly quota is left, your AI credit balance, and how many saved-kit slots remain. Call it before promising a user something the key cannot deliver: every one of these limits is otherwise discoverable only by hitting it, as a 403 for a missing scope or a locked Pro kit, a 429 for quota, a 402 for credits, or a refused save at the free tier's kit cap. This call is free. It spends no quota units and no AI credits, and it is deliberately never refused for being over quota, so it still answers after a 429 has already happened and is safe to call first. Any valid key may read its own entitlements, whatever scopes it holds.

What this brand project's product actually is: what it does, who it is for, what the design must respect, what has already been ruled out, which screens it has, and what it is built on. Read it before proposing anything for an existing project, and read it before set_project_context, because that call replaces rather than merges. A project that exists but has no context yet answers null, which is a different fact from a project that does not exist; that one is a 404. Free, needs kits:read.

Store what the product is, so every later proposal is grounded in it and you never re-send a paragraph of prose. This REPLACES the whole context: nothing is merged, so any field you leave out is deleted, not kept. That is deliberate — a merging update would let you drop a surface from the list and silently keep the old one — but it means the safe way to edit is get_project_context first, then send the whole object back with your change applied. product is the only required field and must be a real sentence rather than a label; a description under 12 characters is refused, because a proposal built on one reads as grounded while being generic. Every string is bounded and an over-long field is refused by name rather than truncated, so nothing is silently cut. Requires the kits:write scope; reading needs only kits:read.

Kit candidates for a specific product, grounded in the context stored on its project rather than in a description you re-send. Each candidate comes back with the kit's own case for itself — what it is for, its motifs, its do's and don'ts, its moods and industries, and its computed fitness for the surfaces this product actually has — so you can rank them yourself. With a Pro account and a kits:write key you also get a model-authored ranking with a reason per candidate written against this product; meta.depth says which you got, ranked or candidates, and meta.order says plainly that the free ordering is computed lane fitness and not a recommendation. Two things that differ from the rest of discovery: this costs 3 quota units where list_themes and search_themes cost 1, and it requires an API key where every other discovery route works anonymously. Call set_project_context first: a project with no stored context returns 400 rather than guessing. Creates nothing.

The brand as ONE document, ready to build from: its design kit's DESIGN.md with every catalogue layer the user pinned written into it. Use this instead of assembling get_design_md plus get_image_direction plus get_interface_style plus get_page_recipe yourself, because merging those four is the part you cannot do correctly — when an interface style asks for translucent panels and the kit specifies flat opaque cards, only we know which wins. The rule is stated in the document itself: the kit owns IDENTITY (its colour tokens, typefaces, spacing and motifs, which nothing below overrides) and a layer owns APPLICATION (what a panel is made of, how a photograph is treated, how a page orders its argument). Follow it rather than re-deciding it, and where a layer would need a kit token changed, keep the token and say so. A brand with nothing pinned returns its kit's DESIGN.md unchanged, which is the honest answer and not an error. A layer this key cannot open is NAMED with its judgment page and an upgrade path, and only its implementation is withheld: build what the kit and the present layers give you and do not invent the missing one, because a guessed implementation looks finished and is not. A brand that has not chosen a kit answers 409 — there is no design system yet, and the placeholder the workspace shows is nobody's choice. Owner-scoped, so the key must own the project; read-only, mints no version, writes nothing. Requires the kits:read scope.

What a brand project is composed of on top of its design kit: its image direction, its interface style, and its page recipes. Read this BEFORE changing any of them, because it is the only place that tells you what the user already chose and whether it still says what it said. Every reference resolves to the revision the catalogue serves now and carries both numbers — revision is current, chosenRevision is what the project pinned — and drift appears only when they differ, carrying the author's note for what moved. meta.drifted counts them, so a brand with nothing to report answers 0 and you can stop. A record withdrawn from the catalogue since it was pinned comes back with resolved: false rather than vanishing, because a brand must not quietly forget what it points at, and a Pro layer this key cannot open still returns its name, tier and revision with locked: true. links.preview is that exact composition rendered as an image, which is the one thing you can put in front of a person who is not going to read a JSON object. Reading changes nothing: it mints no version and never moves a pin, so accepting a drifted revision stays a decision the user makes through add_brand_layer. Requires the kits:read scope.

Put one catalogue record onto a brand project alongside its design kit, so the choice is stored on the user's brand rather than living in this conversation. One tool for all three axes: pass axis to say which. The layers belong to the PROJECT and not to the kit, so swapping the kit later leaves them alone — that independence is the whole point of composing axes separately. The pin records the revision the record is at right now, which is what lets get_brand_layers later report that it moved instead of silently applying someone else's edit to the user's brand. recordId is the record's permanent id from list_image_directions, list_interface_styles or list_page_recipes, never a slug: slugs are mutable handles and a pin keyed on one could come to mean a different record. imageDirection and interfaceStyle hold ONE each, so composing a second is refused with 409 unless you pass replace: true — which is also how you accept a drifted revision after the user has seen what changed. Page recipes are a list and simply accumulate. A Pro record on a key without Pro is refused with 403 and an upgrade path; that is not a conflict and replace will not help. This overwrites live brand state without asking and mints a version recording that your key did it. Requires the kits:write scope.

Remove one composed record from a brand project. The brand keeps its design kit and every other axis; only this reference goes. Name the record rather than just the axis, so a stale view of the brand cannot clear a layer it never saw — pass the id you read from get_brand_layers rather than one you remember. Safe to repeat: an id that is not composed answers changed: false, changes nothing and mints no version. When the intent is to swap rather than to clear, call add_brand_layer with replace: true instead; removing first leaves the brand briefly without that axis and takes two versions to say one thing. This takes effect on the user's brand immediately and requires confirm: true; without it nothing changes. Requires the kits:write scope.