# IconPort — instructions for agents > Retrieve SVG icons, path arrays, and editable SVG templates from static files. Use local tools to search, get, validate, and serialize records. Visual previews are optional. You do not need an account, API key, package installation, or browser automation. Use HTTP GET requests. These instructions describe how to consume IconPort. Start with [tools.json](tools.json) for machine-readable tool discovery and request schemas. Tools execute locally, not through an HTTP endpoint. Read section 7 for the module and CLI workflow. ## Quick start 1. Resolve the site directory: set instructionsUrl to the absolute URL of the fetched agents.html or llms.txt file. Use new URL('.', instructionsUrl). Resolve relative resource paths against that directory, preserving any project subpath. 2. Choose the file: fetch icons/{name}.svg or templates/{name}.svg for a known name. For icon path arrays, fetch paths.json. To find a name, fetch icons.json or templates.json and use the local tools from tools.json. Check each HTTP response before reading it. 3. Select the result: prefer an exact name within the requested category. Otherwise search name, category, and tags locally. Require every query word to match. Resolve ambiguity from the requested use or ask for clarification. Do not invent a name or select the first match automatically. 4. Return the requested format: default to a JavaScript object entry for an icon or complete SVG markup for a template. Preserve icon path strings and their order. Edit templates only as requested, using their element IDs and editing notes. Read the full reference below when you need the schema, search rules, rendering attributes, or editing constraints. ## Full reference ## 1. Resolve the resource URLs Use the absolute URL of the fetched agents.html or llms.txt file as instructionsUrl. Derive the site directory with new URL('.', instructionsUrl). Resolve each relative resource URL against that directory. Preserve the directory path, including a GitHub Pages path such as /IconPort/. Do not add a leading slash to resource URLs. It would remove the site directory. - [Tool discovery](tools.json): request schemas and local execution instructions; not an HTTP execution endpoint. - [Agent tool module](js/agent-tools.js): synchronous runTool(request, catalog). Download all four execution.moduleFiles from tools.json into a new, dedicated tools directory. - [Path map](paths.json): a JSON object with icon names as keys and path arrays as values. - [Catalog](icons.json): metadata, search keywords, rendering defaults, and all path arrays. - [SVG example](icons/search.svg): one standalone SVG file for each name at icons/{name}.svg. - [Template catalog](templates.json): template metadata, search keywords, drawing elements, and editing notes. - Template SVG files: fetch templates/{name}.svg using an exact name from [the template catalog](templates.json). - [Template previews](./#/template): optional SVG previews and copying. - [SVG preview](./#/preview): paste and edit SVG, then copy or download it. - [Agent instructions](agents.html): concise quick start and expandable reference with worked examples. - [License](https://www.gnu.org/licenses/gpl-3.0.html): the full license text. There is no search API. Query parameters do not filter these files. Search a downloaded catalog locally. Reuse a fetched catalog or path map for multiple icons in the same task. ## 2. Choose the retrieval method 1. For a known name and SVG output, fetch icons/{name}.svg. Require a successful HTTP response containing SVG markup. 2. For a known name and path output, fetch paths.json. Require a non-null JSON object, not an array. Check Object.hasOwn(pathMap, name) before reading pathMap[name]. Validate the path array with the rule in section 3. 3. For an unknown name or a description, fetch icons.json. Use the search procedure below. Trim the name request. Convert it to lowercase. Remove a final .svg suffix. Use the exact catalog name in filenames and output keys. Preserve its hyphens. Do not silently replace an explicitly requested icon with a different icon. ## 3. Search the catalog The catalog is a JSON object with these fields: - version: 1. Report an unsupported version instead of assuming this schema still applies. - license: "GPL-3.0-only". - viewBox: "0 0 24 24". - defaults: fill, stroke, strokeWidth, strokeLinecap, and strokeLinejoin. - icons: an array of icon records. Each icon record has name and category strings, a tags array of search keywords, and a paths array of SVG path strings. Reject malformed records and duplicate names before selecting a result. Validate path arrays with validPaths from the downloaded catalog.js module (see section 7). Arrays must be nonempty, with complete SVG commands, finite numbers, valid separators, and binary arc flags. Paths must start with moveto; only XML-compatible ASCII whitespace is accepted. The tags describe synonyms, appearance, and uses. For example, search includes the keyword "find". 1. If the request names a category, restrict the candidates to that category. Ignore letter case and surrounding spaces in category names. 2. Prefer an exact name match among those candidates after normalizing the request. 3. Otherwise, combine each icon's name, category, and tags into searchable text. Convert the query and searchable text to lowercase. 4. Treat hyphens and underscores as spaces for this keyword search. 5. Split the query on whitespace. Require every nonempty word to occur in the searchable text. 6. Keep only candidates that match every word. 7. Compare the matching names, categories, and tags with the requested use. For an empty query, obtain a name or description before searching. If several candidates match, choose one only when the requested use distinguishes it. If the distinction remains unclear, present a short candidate list or ask for clarification. Do not select the first match automatically. If no candidate matches, report that no matching icon exists in the fetched catalog. Do not invent a name or path geometry. ## 4. Return the requested format - Path array: return the selected icon's paths array. - JavaScript object entry: return name: [path strings]. Quote names that contain hyphens. This entry is not a complete JSON object. - JSON: return a complete object mapping the selected name to its path array. Use JSON.stringify({ [icon.name]: icon.paths }). - SVG: return the fetched SVG markup or a local .svg file containing that markup. - URL: return the resolved icons/{name}.svg URL only when the user requests a link. For icons, if the user does not specify a format, return a JavaScript object entry. Preserve every path string and the array order. Return data from the fetched files. Do not redraw, simplify, or reconstruct an icon from its appearance. Example JavaScript object entry, generated from the current catalog: ```javascript search: [ 'M21 21l-5-5', 'M18 10a8 8 0 1 1-16 0 8 8 0 0 1 16 0' ] ``` For a complete retrieval example, read [Fetch a known icon](agents.html#retrieve-example). It checks HTTP success, validates the path map, checks the exact key, and prepares JavaScript and JSON output. ## 5. Render paths correctly Create one element per path string. Set each element's d attribute to that string. Use an SVG wrapper with these attributes: ```text xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" ``` The catalog uses camelCase keys for strokeWidth, strokeLinecap, and strokeLinejoin. SVG markup uses the hyphenated attribute names above. Set width and height to the requested display size. Keep the viewBox and path geometry unchanged. Use the rendering defaults unless the user requests a different appearance. For decorative inline SVG, add aria-hidden="true". Give an icon-only button an accessible name. For an external image, use an appropriate alt attribute. External images cannot inherit the page's text color through currentColor. Use inline SVG when the icon must follow the surrounding text color. ## 6. Retrieve and edit SVG templates Use templates for complete visual components, such as a status label, metric card, table, statistical figure, progress indicator, workflow, or empty state. Use the fetched template catalog as the authoritative list of names. Resolve templates/{name}.svg with the selected record's exact name. For a known name, fetch templates/{name}.svg. For an unknown name, fetch templates.json and search its templates array. Normalize names and search name, title, category, and tags with the same procedure as icons in section 3. Apply the same ambiguity and no-match rules. The template catalog has version: 1, license: "GPL-3.0-only", and a templates array. Report an unsupported version or invalid response. Each record has name, title, category, tags, description, width, height, editable, and elements. Each editable entry has id and note. Each drawing element has tag, attrs, and optional text. Drawing tags are rect, circle, line, path, and text. Return the complete SVG markup or a local .svg file by default. Templates do not use the icon path-array format. Preserve the template's own viewBox and aspect ratio. The icon defaults and 24-by-24 viewBox do not apply to templates. For requested edits, use the element IDs and editable notes. Change only the content or geometry needed for the requested result. Use an XML API or textContent to set labels so characters such as & and < are escaped. When values or meaning change, update the root SVG's aria-label, its title element, and its desc element to describe the edited result. When a progress value or chart data changes, update both its label and the corresponding drawing geometry. For statistical figures, read the scale formulas and definitions in editable. Update values, marks, tick labels, units, and summaries together. Preserve or explicitly change histogram bin conventions, box-plot whisker definitions, and interval types. Use supplied or calculated statistics; the examples do not calculate uncertainty or fit a model. SVG tables are visual figures. Provide an HTML table or equivalent text when users need structured access to the data. Prefix all IDs and their references, including aria-labelledby references, when placing multiple inline copies on one page. Template labels and values are sample data, not measured results. Replace them with supplied data or clearly retain them as examples. Templates contain explicit colors. Gallery and inspector previews adapt their surfaces and labels to the selected website style while preserving chart colors. Cards match the website's light or dark style by default. The Reverse contrast button switches cards to the opposite appearance; click again to restore matching cards. This relationship is preserved when the website style changes. Copied, downloaded, and editor SVGs retain the original colors; edit their SVG colors when a different appearance is requested. There is no template engine, placeholder syntax, or required JavaScript import. Fetch and edit the SVG directly. The optional SVG preview URL is ./#/template?name={name}. ## 7. Run local agent tools The js/agent-tools.js module exports synchronous runTool(request, catalog). Each request requires action (search, get, validate, or render) and kind (icon or template). - search: provide a nonempty query and optional category. Returns {matches, count}; each match includes name, category, tags, and title for templates. It returns metadata only and does not select a result. Category matching ignores letter case and surrounding spaces. - get: provide an exact lowercase catalog name, without .svg. Returns the full record, including icon paths or template elements and editing notes. - validate: provide the complete record. Returns {valid: true, name} when the structure and allowed values pass validation. - render: provide the complete record. Validates it and returns {name, svg}. Every operation returns {ok: true, result} or {ok: false, error: {code, message}}. Check ok before reading result. Pass the fetched icons.json or templates.json as catalog for search and get. No catalog is required for validate or render. Download all four files listed in tools.json under execution.moduleFiles: js/agent-tools.js, js/catalog.js, js/templates.js, and js/package.json. Save their basenames together in a new, dedicated tools directory. The supplied package.json sets that directory's module scope, so the files also work inside a CommonJS project without changing its existing package.json. No npm install is needed. Run this example as a Node.js 24 module beside those files. Set instructionsUrl to the absolute URL of the fetched agents.html or llms.txt. The example changes metadata and preserves icon geometry. ```javascript import { runTool } from './agent-tools.js'; const baseUrl = new URL('.', instructionsUrl); const response = await fetch(new URL('icons.json', baseUrl)); if (!response.ok) throw new Error(`Catalog request failed: ${response.status}`); const catalog = await response.json(); const unwrap = reply => { if (!reply.ok) throw new Error(`${reply.error.code}: ${reply.error.message}`); return reply.result; }; const original = unwrap(runTool({ action: 'get', kind: 'icon', name: 'search' }, catalog)); const record = structuredClone(original); record.tags = [...new Set([...record.tags, 'site search'])]; unwrap(runTool({action: 'validate', kind: 'icon', record})); const { svg } = unwrap(runTool({action: 'render', kind: 'icon', record})); console.log(svg); ``` For templates, get an exact name from a search result, clone the full record, and make requested edits using the editable notes and element IDs. Then validate and render with kind: 'template'. Errors within elements or editable entries identify their index and, when present, their ID. The serializer escapes text and derives the SVG title and description from the record. Record fields are case-sensitive. Unsupported fields fail validation, including fields on template elements and editing notes. Set a shape's color with element.attrs.fill and its label with element.text; misplaced fields such as element.fill or element.Text are errors. Keep your own task metadata outside the record. In a repository clone, use the CLI: ```sh echo '{"action":"get","kind":"icon","name":"search"}' | npm run --silent agent # Or: npm run --silent agent < request.json ``` The CLI accepts one JSON request from standard input and writes one JSON envelope to standard output. It rejects invalid requests before reading the database, and reads the database for valid search and get requests. It exits with status 0 for success or 1 for failure and does not write files. render validates path syntax and serializes SVG source; it does not rasterize images, check text layout, or verify statistical correctness. Validation accepts structured records, not arbitrary pasted SVG markup. ## 8. SVG preview Agents use the tools above without browser automation. Offer the [SVG preview](./#/preview) only when the user wants to inspect or edit complete SVG markup, then copy or download the current source. Clear removes the source and preview. To load an original catalog SVG, use ./#/preview?icon=search or ./#/preview?template=box-plot, resolved against the site directory. Supply exactly one selector with an exact lowercase catalog name. Missing names produce an error. Arbitrary source URLs are not supported. Icon links may include numeric size and strokeWidth options, for example ./#/preview?icon=search&size=48&strokeWidth=2.5. They use the same bounds as icon exports: size 12–256 and stroke width 0.5–4. The inspector’s Edit SVG link preserves its current settings. Preview links load the original SVG; they do not contain edits. Drafts remain in the current tab when you switch between Icons, Templates, and Preview, and restore after reload when browser storage is available. Clear removes the saved draft. They are not uploaded or written to the database. The preview renders SVG as an image. It does not sanitize copied or downloaded source. Review supplied markup before using it inline elsewhere. ## 9. Handle failures and preserve provenance - For a failed HTTP request, report the retrieval failure. Do not report an empty catalog. - For invalid JSON or unexpected content, report an invalid response. Do not treat an HTML error page as icon or template data. - For a missing exact key, report that the requested name is unavailable. Offer verified alternatives separately if they help. - If an SVG URL returns 404, check the catalog for that exact name. Report any mismatch between the catalog and file. - Browser cross-origin requests require host CORS permission. Use server-side HTTP access when available. Include the selected name and source URL when reporting provenance. The optional SVG preview URL is index.html#{name}. The code, icon catalog, and SVG templates use GPL-3.0-only. Preserve the license and attribution notices when reusing or redistributing them.