Identity Forge

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.

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.

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.

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.

Assess up to 20 domains for a stated acquisition intent: new registration, an aftermarket listing, or either. New-registration evidence comes only from the registrar result. Aftermarket evidence comes from a bounded, SSRF-protected public landing-page probe and reports literal sale, marketplace, reserved-page, and visible-price signals without validating a seller or guaranteeing purchase. Basic research costs one monthly unit per unique domain, aftermarket evidence adds one, and optional SERP adds one. A successful exact repeat within ten minutes is charged zero units and says so in meta.billing. Requires naming:read.

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.

Check up to 20 bare domains and return separate RDAP, DNS, Cloudflare Registrar, and optional self-hosted SERP evidence. Basic research spends one account-wide monthly API unit per unique domain; SERP adds one more. Results are a snapshot and reserve nothing. Use search_name_evidence for broader name research. Requires naming:read.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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 export instead of substituting text-to-image generation. This 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.

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. Requires the kits:read scope.

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 cutout over a separately generated background. 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.

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.

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 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 through meta.nextBefore. Needs kits:read.

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

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 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 for one lane and you want to weigh the entire catalog yourself. 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.

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

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.

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

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.