Identity Forge

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.

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…

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…

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.

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…

Retrieve one image direction's full implementation export, as Markdown for reading and briefing or JSON for programmatic use. Follow it when generating, sourcing, or art-directing imagery, and adapt it into the project's repeatable production brief. For an existing product or other supplied subject, use its approved image as the identity source in a reference-preserving editor, apply the direction to the presentation around it, and compare every result with the source at full resolution. If the current agent cannot perform reference-led image editing, save or hand off the source plus this expo…

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.

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 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.

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

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.

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.

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.

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.

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.

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.

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. R…

Browse reusable image directions for how a project's photography and illustration should be presented and repeated. 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. If the user supplied a product, person, or object, its approved image is fixed input: shortlist suitable foundations, then use a reference-preserving image editor to change the setting, supporting elements, composition, light, surfaces, crop, and finish around that same reference. Never recreate an existing product from text or place its cu…

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 …

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 ship…

The kit's VERSION timeline, newest first: which version, when, by whom, and the author's note. Use it to ask whether a repo's applied kit has moved. Saved kits and managed catalog kits accumulate versions; static catalog fallbacks remain at version 0 until they are promoted into the managed catalog. This is not the wider usage ledger: applying an owned kit to a brand appears in list_kit_history, not here. Metadata only; get_kit_version returns a snapshot and diff_kit_versions returns changed fields. For an unentitled Pro kit, rows remain visible but author labels are withheld. Paginated throug…

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

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.

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.

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.

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.

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 y…

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. `use` narrows every lane to kits whose authored audience or bestFor names that product use, then ranks the eligible kits by measured fit. Visual tags help search but never establish product fit. `q` runs a synonym-aware ranked search that understands phrases like 'calm fintech dashboard'. Results are paginated and report the to…

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.

Progress up to 100 candidates through the kanban in one atomic write, and optionally replace their notes or merge top-level evidence keys at the same time. Existing evidence from other sources is preserved unless the same key is supplied. 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 ex…

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.

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…

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.

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 …

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 r…

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 respo…

Withdraw the client's access permanently. The /p/<token> 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 a…

Search the Google Fonts catalog by name or category, or ask for fonts that resemble one you already have. `like` is the way to find a font by resemblance: pass a family you know and get back neighbours ranked by category, popularity, the partners they share in the curated pairing table, and whether published kits use them together, each with a `why` naming the signals that placed it. Nothing here reads a letterform, so `like` is a shortlist to confirm visually, not a verdict on how a face looks. Results are compact metadata — name, family, category, designer, popularity rank, available weights…

Run up to 20 web searches you author yourself against a candidate name through Identity Forge's self-hosted SearXNG. Each query spends one account-wide monthly API unit. Returns dated raw results and nothing else: it does not score, rank, decide whether a collision is real, or constitute trademark clearance. Attach evidence and interpretation with move_name_candidates. For domain registration and DNS evidence use check_domains. Requires naming:read.

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 narrows and ranks the catalog for you and pages rather than returning e…

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 …

Publish a project to a client and return the full /p/<token> 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.

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.

Heading, body and mono faces that work together. Called with no arguments it returns the curated table, each entry carrying the label a person would recognise it by, such as 'Modern tech' or 'Quiet luxury'. Called with a family it answers what goes beside that one: the curated entries naming it, then category-contrast suggestions for the cases the table does not cover. `role` says which slot the family occupies; omit it and both are searched. The suggestions are contrast rules and are not ranked by quality, so read them as candidates. A design kit already carries a chosen trio, so reach for th…

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: crea…

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…

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 whe…

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 happ…