MyJackfruit

Help
Browse topics · For developers

For developers

← Back to What can I build on GilbPlatform?

How do I mint a term from code, the terminal kit or chat?

Short answer

Sign in gilb-mint.ts with the e-mailed code, search for the meaning first, write a package file, then send it with gilb-mint.ts mint.

Before you start

A GilbPlatform account, and on your computer Node 22.18 or later on the 22 line, or 23.6 or later, and gilb-mint.ts from GilbPlatform's developer kit, which its setup link puts in ~/.gilb/kit.

Words used here (4)
GilbPlatform
GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
agent
An agent is your AI following one written procedure, its standing instructions, for one kind of work.
short name
A short name is the one word you give one AI on one computer, such as gilb-example; it keeps that AI's key and tools apart.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
Steps
  1. Sign in with the code e-mailed to you.

    In a terminal, ask for a code, then send the 6-digit code from the e-mail:
    node ~/.gilb/kit/gilb-mint.ts signin <your e-mail>
    node ~/.gilb/kit/gilb-mint.ts code <your e-mail> <the code>

    More about this

    gilb-mint.ts is GilbPlatform's mint program, which your own AI uses on a terminal as Agent.Concept, the agent that finds and makes GilbVeda's terms. A code works once and for 10 minutes. The program makes its own key and keeps it, with a token that lasts 7 days, in ~/.gilb/mint-credential.json, which only you can read; anyone who can read that file can mint as you until the token ends. whoami shows who is signed in and until when, and signout deletes the file. When the program says the sign-in has ended, or an answer is 401, sign in again.

  2. Search for the meaning first.

    Ask whether a live term already carries it, by the short name you would give the term and by its meaning in words, naming your app:
    node ~/.gilb/kit/gilb-mint.ts search <the name or the meaning> --app <your app>

    More about this

    The program asks GilbVeda, then GilbLife for a species of that name, and prints each answer as HTTP and its status, then the body. On a HIT, use the term it names and do not mint; your app's use of it is recorded. On REFUSED, the name was retired or refused: use the term under successors. On a MISS, no term carries it, and candidates are only search hits: go on to step 3. A 409 TermLookupCollision, two terms holding the name, or a 503 LookupUnavailable is not a miss: do not mint. A species goes to GilbLife; the answer on minting and looking up species shows how.

  3. Write the package file.

    Write { terms: [ ... ] } with one member for each new term, 1 to 50, each with every one of these keys, null where its kind does not use it: term, predicateAttribute, nodeKind, label, does, example, subTypeOf, providesFunction, encoding, cardinality, measures, valueSubject, valuedBy, scale, hasMeter, confidence and justifiedBy.

    More about this

    term is t: and the new name. nodeKind is type, attribute, function or value; a link between two things is an attribute with encoding reference. example holds two examples or more, hasMeter one human and one ai meter, confidence your own, 0.5 to 1.0, and justifiedBy why you mint it and why no live term was reused. A Function is what a system does, written as an action; a Value is a perceived benefit, measured as a number. A type or attribute needs a Value that measures one of its Functions: attach a live one with hasValue, or add one to the package. Add app, your app's short name, to record its use. Never send the status or the minter.

  4. Send the file with gilb-mint.ts mint.

    Send it, and keep the addresses the answer gives:
    node ~/.gilb/kit/gilb-mint.ts mint <package file>

    More about this

    A 201 answer lists each term under minted, with its address and the status Suggested, and you under termMintedBy. A suggested term can be used at once; approving it is later, separate work. The terms in a file land together or not at all: 400 MintPackageInvalid names each problem under problems, 422 MintPackageGaps says under gaps what is taken, missing or of the wrong kind, and 409 MintFloorMoved means the vocabulary changed meanwhile, so send it again. The program exits 0 on a 2xx answer, 1 on a refusal and 2 on a problem on your side. If the connection drops after sending, search for the term before you send again.

Deeper

Also asked:

How do I add a new term from code or the terminal? Search for its meaning first; if no term carries it, write a package file and send it with node ~/.gilb/kit/gilb-mint.ts mint <package file>, which goes through Agent.Concept, as the steps show.

My mint was refused with NotThroughAgentConcept. Why? The request carried no pass: every mint goes through Agent.Concept, and the pass comes from POST https://veda.gilb.com/base/ai/claude-code/context with agent Agent.Concept. gilb-mint.ts fetches it for you.

How many terms may I mint a day? One person may mint 100 terms in 24 hours, unless the platform sets another number, and 20 on a new account's first day; past that the answer is 429 MintQuotaReached.

Is there a rate limit, and what do I do on 429? Some calls have a limit of their own and answer 429 past it, such as minting, 100 terms a person in 24 hours, and too many reads of one organisation's card at once. Wait as long as the answer or its Retry-After header says, then send again with a new proof.

Every mint goes through Agent.Concept: your own AI acts as Agent.Concept when it uses gilb-mint.ts, and follows Agent.Concept's standard, which it reads with kz-std, the command your AI uses to read a standard. The mint routes take only a pass the server gives when it has opened an Agent.Concept turn for you, sent in X-Base-Mint-Pass; it lasts 15 minutes, and the program fetches it. A request without it answers 403 NotThroughAgentConcept and writes nothing; a name typed in a header is not a pass.

From your own code, the requests are POST https://veda.gilb.com/base/ai/claude-code/context with agent set to Agent.Concept, whose answer holds the pass under mintPasses, then POST https://veda.gilb.com/base/vocab/mint with the package, each with the person's token and a new DPoP proof; example 1 shows them. A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). The token is the one GilbPlatform gave your app when the person signed in. GilbPlatform's rule for apps is that an app never mints from its own code and never ships a stand-in type while it waits: mint what the app needs before the code ships. Example 1 is for your own script or tool while you build, not for code inside the app you ship.

In GilbApp's chat, choose Agent.Concept and say what you need: it looks the term up and mints it at once, with you as its maker; the answer on having a concept found or made in GilbVeda shows how. Other agents, such as Jackfruit, hand a need to it for you. In one message it mints at most 5 times, and its tools there cannot change, approve or retire a term, or store a picture.

Anyone signed in to GilbPlatform may mint, and so may an AI a person has bound to their AI vault, both through Agent.Concept. With no sign-in the answer is 401; a computer's own key, or a machine token with no person behind it, answers 403 NotAPersonToMint. One person may mint 100 terms in 24 hours unless the platform sets another number, and fewer on a new account's first day; past that the answer is 429 MintQuotaReached, which says the limit, how many you have used and when the oldest leaves the 24 hours. The kit's example-package.json shows an attribute and its Value; the program will not send a copy still named or justified as the example.

What you mint stays yours to change or retire while it is still Suggested; the answer on changing or retiring a term you minted shows how. A type's picture is added in GilbApp; the answer on setting a term's picture shows how.

The Developer Guide, GilbPlatform's guide for people who build apps on it shows how to read a term in its chapter Dev.Guide.Vocabulary, https://appbuilder.gilb.com/base/e/06gkzpwtj1wm58yf6zng0xdtbm; its part on asking for a term was written before minting through Agent.Concept, and says to ask the platform owner. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/_mint-gate.ts:1-42 (one gate for terms and GilbLife: host 404, mayMintTerms 401/403, vault served and local 503, pass 403 NotThroughAgentConcept New ontology is minted through Agent.Concept only. ...), :92-128; src/auth/mint-pass.ts:1-66 (pass issued by the server for an Agent.Concept turn; header x-base-mint-pass; aud base:mint:vocab or base:mint:life; 15 minutes; sub = the person); src/routes/ai-claude-code.ts:271-298 (POST /base/ai/claude-code/context: mintPasses only on an Agent.Concept turn and when mayMintTerms passes), :114-127 (body: userText required, agent, agentEntry, contentVaultIds, turnId); src/auth/open-mint-standing.ts:1-110 (a signed-in person or a bound AI; computer credential or unbound machine 403 NotAPersonToMint; no http principal 401 SignInToMint); src/routes/term-mint.ts:1-27 (routes and order), :159-196 (mintTermPackage: parse, stage, one transaction; 201 {minted: [{term, entity, status Suggested, usedByApp?}], termMintedBy}; MintQuotaError; 409 MintFloorMoved), :203-238 (onRequest: requireVerifiedCaller 401, then the gate; MintPackageInvalid on a bad shape or no JSON); src/termrequest/answers.ts:55-59 (1-50 members), :86-122 (HIT, REFUSED, COLLISION 409 TermLookupCollision, FAULT 503 LookupUnavailable, MISS); src/termrequest/mint.ts:40-98 (MINT_KINDS type, attribute, function, value; confidence 0.5-1.0; MEMBER_KEYS; OPTIONAL hasValue, app, fieldOf; app slug), :105-122 (TERM_NOT_KEYS; relation = attribute with encoding reference); src/termrequest/mint-quota.ts:1-30 (MINT_QUOTA perPersonDay 100, newAccountDay 20, globalDay 2000, overridable by the operator), :140-195 (429 MintQuotaReached with limit, used, left, nextFreeAt; first-day limit); src/ai/chat-mint-tools.ts:1-135 (chat tools read_term, lookup_term, lookup_taxon, mint_term, mint_taxa, ask_agent_concept; at most 5 mints a person turn), :155-215; src/auth/email-otc.ts:64 (CODE_TTL_MS 10 minutes). scripts/devkit/gilb-mint.ts:41-45 (id.gilb.com, veda.gilb.com, life.gilb.com), :186-239 (usage text), :271-317 (signin: request-code; code: verify-code with the kit's own P-256 key; ~/.gilb/mint-credential.json 0600; expiry check), :324-357 (passFor: POST <base>/base/ai/claude-code/context with agent Agent.Concept, mintPasses.vocab|life; needsPass for POST /base/vocab/, /base/life/mint, /base/term-requests), :502-540 (search: one https IRI = GilbLife taxonID; words = term-requests then GilbLife scientificName; --app prints usage: recorded for / usage: NOT recorded for), :542-581 (mint/change/retire routing; the shipped example refused locally, exit 2); scripts/devkit/README.md:21-36 (Node 22.18+ or 23.6+; 6-digit code 10 minutes; credential 7 days), :38-83 (the loop, answers, exit codes 0/1/2, dropped connection), :85-143 (GilbLife), :171-184 (a member); scripts/devkit/example-package.json (an attribute and its Value). Agent.Concept (J 06gf80rjtdw3h9q187p80kx00m, 2026-11-11): Task (any signed-in person; terminal: node ~/.gilb/kit/gilb-mint.ts, which the one setup link installs; look up by name and by meaning; HIT = use it; MISS = mint at once; usage row; no record stands in), ClosedSend, PictureLicence. Rule_Code_gilb-app-term-requests (A 06gf2ppbndt83239wxd4j2xc2g) RuleBaseappTermRequestLane 2 (Never mint from app code; its item 1 Only named developers can mint is older than the code: see faults). Dev.Guide.Vocabulary (A 06gkzpwtj1wm58yf6zng0xdtbm) AskForTerm (Today you ask the platform owner). docs/BASE-DEVELOPER-GUIDE.md:6939-6976, 7121-7200 (team notes, read for agreement: the kit; the chat way in; at most 5 mints a turn; not linked). Shared sentences, word for word: DPoP proof, the token, the mint program, Function and Value, suggested term, kz-std, a code works once and for 10 minutes, 7-day sign-in token. GilbPlatform 0fc5a548 (https://id.gilb.com/version, read 14 November 2026): src/termrequest/mint-quota.ts:12 (100 per person a day, 20 for an account younger than 24 hours); src/routes/connect-org-card.ts:22 (429, Retry-After 1); the live answer How do I read an organisation's card?

For developers

curl

mint-through-agent-concept.sh

# 1. Open an Agent.Concept turn. Keep mintPasses.vocab from the answer; it lasts 15 minutes.
curl -s https://veda.gilb.com/base/ai/claude-code/context \
  -H "Authorization: DPoP <sign-in token>" \
  -H "DPoP: <a new proof for POST https://veda.gilb.com/base/ai/claude-code/context>" \
  -H "Content-Type: application/json" \
  --data '{"userText":"<what the terms are for>","agent":"Agent.Concept"}'

# 2. Search first, naming your app. Mint only on a MISS.
curl -s https://veda.gilb.com/base/term-requests \
  -H "Authorization: DPoP <sign-in token>" \
  -H "DPoP: <a new proof for POST https://veda.gilb.com/base/term-requests>" \
  -H "X-Base-Mint-Pass: <mintPasses.vocab>" \
  -H "Content-Type: application/json" \
  --data '{"meaning":"<the name or the meaning>","app":"<your app>"}'

# 3. Mint the package: { "terms": [ <member>, ... ] }.
curl -s https://veda.gilb.com/base/vocab/mint \
  -H "Authorization: DPoP <sign-in token>" \
  -H "DPoP: <a new proof for POST https://veda.gilb.com/base/vocab/mint>" \
  -H "X-Base-Mint-Pass: <mintPasses.vocab>" \
  -H "Content-Type: application/json" \
  --data @package.json
# 201: {"minted":[{"term":"https://veda.gilb.com/base/t/<Name>","entity":"<address>","status":"Suggested","usedByApp":"<your app>"}],"termMintedBy":"<your address>"}

TypeScript

mint-member.ts

// One member of a package for POST /base/vocab/mint. Send every key, null where the kind does not use it.
// The allowed nodeKind, encoding and cardinality values are read live: a 400 names them.
// Never send the status or the minter: the server sets "Suggested" and you.
export interface MintMember {
  term: string; // "t:<Name>"
  predicateAttribute: string | null; // an attribute: "a:<name>"
  nodeKind: "type" | "attribute" | "function" | "value";
  label: string;
  does: string;
  example: string[]; // two or more
  subTypeOf: string | null;
  providesFunction: string[] | null;
  encoding: string | null;
  cardinality: string | null;
  measures: string | null; // a value: the Function it measures
  valueSubject: string | null;
  valuedBy: string[] | null;
  scale: { does: string; unit: string; rate: string | null; scaleBest: string; scaleWorst: string | null; scaleZero: string | null } | null; // a value: give scaleWorst or scaleZero, or both
  hasMeter: { meterAgentKind: "human" | "ai"; method: string }[] | null;
  confidence: number; // your own, 0.5 to 1.0
  justifiedBy: string; // why, what code it binds, why no live term was reused
  hasValue?: string[]; // a type or attribute: the Values it attaches
  fieldOf?: string; // an attribute: the one existing type it is a field of
  app?: string; // your app's short name, no spaces: records its use
}

export function mintPackage(terms: MintMember[]): { terms: MintMember[] } {
  if (terms.length < 1 || terms.length > 50) throw new Error("a package holds 1 to 50 members");
  return { terms };
}

Checked against GilbApp d529620.