# Use Armorial to select and render project-aware IconPark SVGs locally Armorial is a deterministic local icon-selection and rendering product for humans and Agents. It searches the pinned IconPark collection, applies one explicit project policy, reports unresolved semantic ambiguity, and returns a bounded structured result and SVG. ## Use Armorial for - finding an existing IconPark icon from an English or Simplified Chinese intent; - applying project defaults for theme, colors, size, stroke weight, cap, and join; - rendering one known `icon-park:*` id reproducibly; - comparing compact candidates when more than one icon is plausible; - opening a visual picker when taste or a rejected choice requires a human; - rendering up to 8 already-known ids while preserving order and per-item failures. Representative requests: - "Choose a settings icon for this toolbar using the project defaults." - "Find several notification icon alternatives without drawing new SVG." - "Render `icon-park:search` at size 32 with the current policy." - "Let me compare the ambiguous choices visually." ## Do not use Armorial for - drawing a logo, illustration, or new icon geometry; - editing arbitrary SVG paths or normalizing a different icon collection; - making a final aesthetic choice when the remaining difference is subjective; - treating a natural-language surface description as a configured policy context key; - inferring that a technically valid SVG is approved for a product or design system; - searching fonts, photos, emoji, or non-IconPark assets. ## Execution and data boundary - The CLI, local web workbench, Figma plugin, MCP server, and hosted workbench share the same deterministic kernel and pinned IconPark catalog. - Local CLI and MCP rendering need no network after dependencies and build artifacts are present. Queries and project policy values are not sent to an Armorial service. - Direct MCP search and render operations do not write files. Ordinary CLI results use stdout. An explicit batch `--output ` publishes one new, create-only sprite and reports `protectionLevel: non_overwriting_create`. Replacing an existing SVG requires explicit `--allow-optimistic-overwrite`; it can overwrite a non-cooperating writer in the final check-to-rename window, and every success reports `protectionLevel: optimistic_preflight_only` plus a warning. Passing that replacement-only flag for a new SVG is invalid and creates nothing. The default HTML route uses `--inline-from --output ` to create a distinct, non-overwriting candidate while leaving the source unchanged; same paths, hard-link aliases, and existing outputs are rejected. Inline admission bounds caller-owned HTML to 8 MiB and the Armorial-managed marker block to 512 KiB plus four framing bytes, so an accepted first insert remains retryable and replaceable. SVG and HTML publication is pinned to the admitted parent-directory inode; replacing that parent path cannot redirect writes through a new symlink. The helper stages and verifies bytes, then waits for a one-use commit from its still-live CLI parent. Parent death or the five-second deadline before that commit leaves no final output and normally removes private staging. If destination-parent permissions prevent cleanup, the surviving CLI preserves the cause and reports bounded publication effect, cleanup, and private `0600` residue metadata. Restore access and inspect/remove that sibling before retry. After commit, an interruption may leave a valid output without a success summary. A surviving CLI reports `PUBLICATION_OUTCOME_UNCERTAIN`; inspect the destination before retrying an interrupted carrier call. A create-only helper crash can also leave a private sibling hard link; verify the intended destination before treating it as stale. Successful candidate JSON reports source and candidate hashes plus `protectionLevel: non_overwriting_candidate`; hashes identify bytes but are not atomic commit credentials. The legacy in-place `--inline-into` route is also available only with `--allow-optimistic-overwrite`. It can overwrite a non-cooperating editor save in the final check-to-rename window, and every success reports `protectionLevel: optimistic_preflight_only` plus a warning. Browser download, clipboard, Figma insertion, and an explicit human decision are separate user-visible effects. - MCP tools do not accept paths, URLs, raw SVG, or source code. The server operator may select one policy file at startup. - A successful call establishes only the returned deterministic product result; it does not establish design approval, task success, or suitability outside the declared IconPark boundary. ## Cheapest correct route | Task | Route | | --- | --- | | Ordinary semantic icon request | Call `resolve_icon` once. | | Exact known id | Call `get_icon` once. | | Alternatives requested | Call `search_icons`; call `get_icon` only after selection. | | Up to 8 known ids needed in the current Agent turn | Call `get_icons` once. | | Larger structured batch automation or durable output | Call the CLI/library directly (up to 20 ids) so SVG payloads do not enter model context. | | Human visual decision needed | Call `choose_icon` once, then wait for the explicit selection. | Do not install Agent Host for one direct Armorial call. Agent Host becomes useful when the environment must keep several provider packages immutable, control which tools are active, enforce catalog budgets, preserve host bindings, or provide verified update and rollback behavior. ## Deployment-pinned source install and repeatable probe The current public distribution is the GitHub repository and static workbench. The workbench publishes the exact 40-character Git commit from which it was built. There is no public npm package or official MCP Registry entry yet. Prerequisites: Git, curl, and Node.js 22 or newer. The dependency install below disables lifecycle scripts; the following build command is the explicit source execution step. ```sh ARMORIAL_COMMIT="$(curl -fsSL https://tetracoralla.github.io/armorial/source-commit.txt)" printf '%s\n' "$ARMORIAL_COMMIT" | grep -Eq '^[0-9a-f]{40}$' git clone https://github.com/tetracoralla/armorial.git cd armorial git checkout --detach "$ARMORIAL_COMMIT" test "$(git rev-parse HEAD)" = "$ARMORIAL_COMMIT" node -e 'if (Number(process.versions.node.split(".")[0]) < 22) process.exit(1)' npm ci --ignore-scripts npm run build:node node dist/adapters/cli.js resolve settings ``` Expected observations from the last command: - stdout is one JSON result; - `status` is `ok` or `ambiguous`, never an invented fallback drawing; - an `ok` result names an `icon-park:*` id and includes the rendered asset, effective policy, byte count, and SHA-256; - an `ambiguous` result lists candidates and does not claim a chosen SVG. For complete source regression and the real CLI/MCP probe, run: ```sh npm run check ``` ## Integration surfaces - Human workbench: - Source and install details: - MCP configuration: - Product routing Skill: - Executable policy schema: - Product model: - Review boundary: The MCP Registry can become an additional discovery carrier after Armorial has an independently installable public MCP artifact. Registry namespace ownership would identify the publisher; it would not by itself establish security, quality, suitability, or successful execution. This GitHub Pages project intentionally does not publish a path-scoped `robots.txt`: crawler policy belongs at the origin root. The page itself is indexable, and its public Sitemap is available at .