Select and render project-aware IconPark SVGs locally

Armorial deterministically searches the pinned IconPark collection, applies one explicit project icon policy, reports unresolved ambiguity, and returns bounded structured results and SVG.

Use Armorial for

finding an existing IconPark icon from English or Simplified Chinese intent;
applying project theme, color, size, stroke, cap, and join defaults;
rendering a known icon-park:* id reproducibly;
returning compact alternatives or asking a human to make a visual choice.

Do not use Armorial for

drawing logos, illustrations, or new icon geometry;
editing arbitrary SVG paths or searching a different collection;
automatically making a subjective aesthetic or design-approval decision;
treating an unconfigured natural-language surface description as policy.

Cheapest correct route

Task	Route
Ordinary semantic request	`resolve_icon` once
Known id	`get_icon` once
Alternatives requested	`search_icons`, then render only the selected id
Known ids needed in the Agent turn	`get_icons`, at most 8
Structured batch automation	CLI/library direct route; keep SVG payloads out of model context
Subjective visual choice	`choose_icon`, then wait for the human decision

Execution boundary

Search and rendering are local after dependencies and build artifacts are present. Direct MCP tools do not write files or accept paths, URLs, raw SVG, or source code. Ordinary CLI results use stdout. An explicit batch --output <relative.svg> publishes one new, create-only sprite and reports protectionLevel: non_overwriting_create. Replacing an existing SVG requires --allow-optimistic-overwrite, can overwrite a non-cooperating writer in the final check-to-rename window, and 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 <source.html> --output <new-candidate.html> to create a distinct, non-overwriting candidate while leaving the source unchanged; same paths, hard-link aliases, and existing outputs are rejected. SVG and HTML publication is pinned to the admitted parent-directory inode, so replacing that parent path cannot redirect writes through a new symlink. The helper stages and verifies private 0600 bytes before its still-live CLI parent returns a one-use commit token. Parent death or the five-second deadline before commit creates no final output and normally removes private staging. If destination-parent permissions prevent cleanup, a surviving CLI preserves the cause and reports bounded publication effect, cleanup, and residue metadata. Restore access and inspect/remove that sibling before retrying. 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. 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 also requires --allow-optimistic-overwrite and carries the same disclosed final window. A successful result does not establish design approval or task success.

Deployment-pinned source probe

Requires Git, curl, and Node.js 22 or newer. The deployment publishes the exact Git commit it was built from; the probe checks out that commit rather than mutable main.

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