@flareum/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flareum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @flareum/mcp
+
+Connects a coding agent to a Flareum project's design tokens, so it uses your tokens instead of
+typing literal values.
+
+**Read-only.** Nothing this package does can change your Flareum project. There is no write tool.
+
+---
+
+## Install
+
+1. In Flareum, open **Project settings → Connect** and click **Connect to VS Code**.
+2. Copy the command it shows you. It looks like this:
+
+```bash
+claude mcp add flareum --env FLAREUM_TOKEN=pk_… -- npx -y @flareum/mcp
+```
+
+3. Run it in **your project's** terminal — the repo where you write CSS/SCSS, not the Flareum repo.
+4. Restart your editor session. MCP servers are not picked up by a session already running.
+
+The key is shown once and cannot be retrieved again. If you lose it, revoke it and make another.
+
+---
+
+## What your agent can do with it
+
+Ask in plain language — the agent picks the tool:
+
+| Ask | What happens |
+|---|---|
+| "Is there a token for `#5B8DEF`?" | searches by colour; a hex, `rgb()` or a bare triplet all work |
+| "What spacing tokens exist?" | searches by path fragment |
+| "Which token is the one used by the Card?" | searches by component name |
+| "What breaks if I change `space/4`?" | lists the tokens referencing it, and the components using it |
+| "Style this banner" | the agent looks a token up rather than typing `padding: 16px` |
+
+### The two tools
+
+| Tool | Answers |
+|---|---|
+| `flareum_search(query, limit?)` | *Is there already a token for this?* Matches path, CSS name, resolved value, comment and component names. |
+| `flareum_get(path)` | *What is this token, and what breaks if I change it?* Values per mode, plus what references it. |
+
+**A search never comes back empty.** If nothing matches well it returns the nearest tokens and says
+so, because "no results" reads as "no such token exists" and gets acted on.
+
+---
+
+## Configuration
+
+| Variable | |
+|---|---|
+| `FLAREUM_TOKEN` | **required.** The project is read from the key itself. |
+| `FLAREUM_API` | optional. Defaults to production. Set it to point at a local Flareum. |
+| `FLAREUM_PROJECT` | optional. Overrides the project in the key. |
+
+On start it writes `.claude/skills/flareum/SKILL.md` into the working directory — the naming rules
+your agent needs to propose a token name correctly. It is regenerated every run, so do not edit it,
+and it prints where it wrote (or why it could not) on stderr.
+
+---
+
+## If it is not working
+
+| What you see | Cause |
+|---|---|
+| The server fails to connect / closes immediately | The package is not installed. Check `npx -y @flareum/mcp` resolves — if it 404s, it has not been published yet. |
+| The agent types literal values anyway | The skill did not land. Look for `[flareum] skill written to …` in the MCP server's stderr. |
+| Values labelled with long ids instead of mode names | The Flareum server is older than the client. Restart it. |
+| `401` on every call | The key was revoked, or belongs to another project. Mint a new one. |
+| `429` | More than 120 requests a minute on one key. |
+
+Every error the API returns carries a `hint` saying what to do next — your agent sees it.
+
+---
+
+## Development
+
+Working on this package rather than using it.
+
+```bash
+cd packages/mcp
+npm install
+npm run build          # tsc → dist/
+npm test               # this package's tests
+```
+
+To try a local build without publishing, point the command at the built file instead of npm:
+
+```bash
+claude mcp add flareum \
+  --env FLAREUM_TOKEN=pk_… \
+  --env FLAREUM_API=http://localhost:9999 \
+  -- node /absolute/path/to/packages/mcp/dist/server.js
+```
+
+### Publishing
+
+Only a maintainer does this, and only to let other people `npx` the package. It is not needed to
+develop or test.
+
+```bash
+npm adduser              # once ever — links your machine to an npm account
+npm org create flareum   # once ever — claims the @flareum scope
+cd packages/mcp
+npm version patch        # every release; npm refuses to republish a version
+npm publish              # builds first, publishes public
+```
+
+Until this is published, the command the Connect screen generates cannot work — `npx` has nothing
+to fetch.
+
+### Layout
+
+| File | |
+|---|---|
+| `src/client.ts` | HTTP against the Flareum read API. `fetch` is injected, so it is testable without a network. |
+| `src/tools.ts` | The TEXT each tool returns. This is what the agent reads, so its wording is guarded. |
+| `src/server.ts` | MCP stdio transport. Glue only — no behaviour lives here. |
+| `src/skill.ts` | Writes the skill into the consuming project. |
+| `skill/SKILL.md` | The naming rules shipped to the agent. |
+
+`server.ts` has no tests because it holds no logic; everything it calls is covered. Imports inside
+the package carry a `.js` extension — TypeScript does not rewrite specifiers, and Node's ESM loader
+will not resolve an extensionless one at runtime.

package/dist/client.d.ts

@@ -0,0 +1,77 @@
+export type FlareumError = {
+    code: string;
+    message: string;
+    hint?: string;
+};
+export type ClientOptions = {
+    token: string;
+    api?: string;
+    projectId?: string;
+    fetchImpl?: typeof fetch;
+};
+export declare class FlareumApiError extends Error {
+    readonly code: string;
+    readonly hint: string;
+    constructor({ code, message, hint }: FlareumError);
+}
+export declare const projectIdFromToken: (token: string) => string;
+export declare class FlareumClient {
+    #private;
+    readonly projectId: string;
+    constructor({ token, api, projectId, fetchImpl }: ClientOptions);
+    catalog(updatedSince?: string): Promise<CatalogResponse>;
+    search(query: string, limit?: number): Promise<SearchResponse>;
+    variable(path: string): Promise<VariableResponse>;
+}
+export type CatalogResponse = {
+    projectId: string;
+    prefix: string;
+    liveVersionId: string;
+    publishedVersionId: string | null;
+    collections: Array<{
+        id: string;
+        name: string;
+        prefix: string;
+        variables: unknown[];
+    }>;
+};
+export type Candidate = {
+    id: string;
+    path: string;
+    cssName: string;
+    type?: string;
+    collection?: string;
+    collectionName?: string;
+    values?: Record<string, {
+        value: string;
+        resolved: string;
+    }>;
+    usage?: {
+        componentCount: number;
+        components: string[];
+    };
+    state?: string;
+    score: number;
+    matchedOn: string[];
+};
+export type SearchResponse = {
+    query: string;
+    matched: boolean;
+    reason?: string;
+    total: number;
+    truncated: boolean;
+    candidates: Candidate[];
+};
+export type VariableMode = {
+    id: string;
+    name: string;
+    selector: string;
+};
+export type VariableResponse = Candidate & {
+    modes?: VariableMode[];
+    referrers: Array<{
+        id: string;
+        path: string;
+        cssName: string;
+    }>;
+};

package/dist/client.js

@@ -0,0 +1,64 @@
+// The HTTP client. `fetch` is injected so every behaviour here is testable without a network, and
+// so a host with its own fetch (a proxy, a retry policy) can supply one.
+export class FlareumApiError extends Error {
+    code;
+    hint;
+    constructor({ code, message, hint }) {
+        super(message);
+        this.name = 'FlareumApiError';
+        this.code = code;
+        this.hint = hint ?? '';
+    }
+}
+// Must match src/environments/environment.prod.ts. A wrong default sends a bearer token to a
+// domain nobody here owns.
+const DEFAULT_API = 'https://api.flareum.app';
+// A token is `pk_<project>_<random>`; the project is recoverable from it so a user pastes one value.
+export const projectIdFromToken = (token) => token.split('_')[1] ?? '';
+export class FlareumClient {
+    projectId;
+    #token;
+    #api;
+    #fetch;
+    constructor({ token, api, projectId, fetchImpl }) {
+        if (!token)
+            throw new Error('FLAREUM_TOKEN is not set. Mint one in the project\'s Connect screen.');
+        this.#token = token;
+        this.#api = (api ?? DEFAULT_API).replace(/\/+$/, '');
+        this.projectId = projectId || projectIdFromToken(token);
+        const impl = fetchImpl ?? globalThis.fetch;
+        if (!impl)
+            throw new Error('No fetch implementation available.');
+        this.#fetch = impl;
+    }
+    async #get(path, query = {}) {
+        const url = new URL(`${this.#api}/api/v1/projects/${this.projectId}${path}`);
+        for (const [key, value] of Object.entries(query))
+            if (value)
+                url.searchParams.set(key, value);
+        const response = await this.#fetch(url.toString(), {
+            headers: { Authorization: `Bearer ${this.#token}`, Accept: 'application/json' },
+        });
+        if (response.ok)
+            return response.json();
+        // The server's `hint` is written for a model to act on, so it must survive to the tool result
+        // rather than being flattened into a status code.
+        const body = await response.json().catch(() => null);
+        throw new FlareumApiError(body?.error ?? {
+            code: `HTTP_${response.status}`,
+            message: `The Flareum API returned ${response.status}.`,
+            hint: response.status === 401
+                ? 'The token is invalid or revoked. Mint a new one in the project\'s Connect screen.'
+                : 'Retry; if it persists, check the project is reachable.',
+        });
+    }
+    catalog(updatedSince = '') {
+        return this.#get('/catalog', { updatedSince });
+    }
+    search(query, limit) {
+        return this.#get('/search', { q: query, ...(limit ? { limit: String(limit) } : {}) });
+    }
+    variable(path) {
+        return this.#get(`/variables/${path.split('/').map(encodeURIComponent).join('/')}`);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Transport glue only. Every behaviour worth guarding lives in client.ts and tools.ts, which have
+// no SDK dependency and are tested without one.
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { FlareumApiError, FlareumClient } from './client.js';
+import { TOOL_DESCRIPTIONS, formatError, formatSearch, formatVariable } from './tools.js';
+import { installSkill, skillInstallReport } from './skill.js';
+const client = new FlareumClient({
+    token: process.env.FLAREUM_TOKEN ?? '',
+    api: process.env.FLAREUM_API,
+    projectId: process.env.FLAREUM_PROJECT,
+});
+const server = new Server({ name: 'flareum', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'flareum_search',
+            description: TOOL_DESCRIPTIONS.search,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'A name, a path fragment, a hex or rgb() colour, a comment phrase, or a component name.' },
+                    limit: { type: 'number', description: 'Maximum candidates to return (default 10, max 50).' },
+                },
+                required: ['query'],
+            },
+        },
+        {
+            name: 'flareum_get',
+            description: TOOL_DESCRIPTIONS.get,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'The token path, e.g. color/semantic/border/warning. A CSS custom-property name also works.' },
+                },
+                required: ['path'],
+            },
+        },
+    ],
+}));
+const text = (body) => ({ content: [{ type: 'text', text: body }] });
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = (request.params.arguments ?? {});
+    try {
+        if (request.params.name === 'flareum_search')
+            return text(formatSearch(await client.search(String(args.query ?? ''), Number(args.limit) || undefined)));
+        if (request.params.name === 'flareum_get')
+            return text(formatVariable(await client.variable(String(args.path ?? ''))));
+        return text(`Unknown tool: ${request.params.name}`);
+    }
+    catch (error) {
+        // A failure is reported as a readable tool result, never a protocol error: the model can act on
+        // the hint, and cannot act on a transport exception.
+        if (error instanceof FlareumApiError)
+            return text(formatError(error));
+        return text(formatError({ code: 'UNREACHABLE', message: String(error),
+            hint: 'Check FLAREUM_API and that the machine is online.' }));
+    }
+});
+// Never silently: if the skill does not land, the agent hardcodes values and nothing says why.
+console.error(skillInstallReport(await installSkill(process.cwd())));
+await server.connect(new StdioServerTransport());

package/dist/skill.d.ts

@@ -0,0 +1,11 @@
+export type SkillInstall = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    path: string;
+    reason: string;
+};
+export declare const installSkill: (cwd: string) => Promise<SkillInstall>;
+/** Reported on stderr — stdout carries the JSON-RPC stream and must never be written to. */
+export declare const skillInstallReport: (result: SkillInstall) => string;

package/dist/skill.js

@@ -0,0 +1,23 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SKILL_DIR = ['.claude', 'skills', 'flareum'];
+// Written on every start, not once: a stale copy of the naming rules is worse than none, and the
+// file is generated rather than hand-edited.
+export const installSkill = async (cwd) => {
+    const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'skill', 'SKILL.md');
+    const path = join(cwd, ...SKILL_DIR, 'SKILL.md');
+    try {
+        await mkdir(join(cwd, ...SKILL_DIR), { recursive: true });
+        await writeFile(path, await readFile(source, 'utf8'), 'utf8');
+        return { ok: true, path };
+    }
+    catch (error) {
+        return { ok: false, path, reason: error instanceof Error ? error.message : String(error) };
+    }
+};
+/** Reported on stderr — stdout carries the JSON-RPC stream and must never be written to. */
+export const skillInstallReport = (result) => result.ok
+    ? `[flareum] skill written to ${result.path}`
+    : `[flareum] could NOT write the skill to ${result.path} — ${result.reason}. `
+        + 'Without it the agent will not know to search for a token before writing a literal value.';

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+import type { SearchResponse, VariableResponse } from './client.js';
+export declare const NO_MATCH_INSTRUCTION: string;
+/** What `flareum_search` hands back. */
+export declare const formatSearch: (result: SearchResponse) => string;
+/** What `flareum_get` hands back — detail plus the blast radius of changing it. */
+export declare const formatVariable: (v: VariableResponse) => string;
+export declare const formatError: ({ code, message, hint }: {
+    code: string;
+    message: string;
+    hint?: string;
+}) => string;
+export declare const TOOL_DESCRIPTIONS: {
+    readonly search: string;
+    readonly get: string;
+};

package/dist/tools.js

@@ -0,0 +1,74 @@
+// The text a tool returns IS the product: it is what the model reads before deciding whether a
+// token exists. Kept pure and separate from the MCP transport so every wording here is guarded.
+// A collection can carry 28 modes, so the whole list would bury the row it is describing.
+const MAX_VALUES_SHOWN = 4;
+const valueLine = (values) => {
+    if (!values)
+        return '';
+    // A stored value can span lines (a multi-line var() fallback), which would break the row apart.
+    const all = [...new Set(Object.values(values)
+            .map(v => (v.resolved || v.value).replace(/\s+/g, ' ').trim())
+            .filter(Boolean))];
+    return all.length > MAX_VALUES_SHOWN
+        ? `${all.slice(0, MAX_VALUES_SHOWN).join(' · ')} (+${all.length - MAX_VALUES_SHOWN} more)`
+        : all.join(' · ');
+};
+const describe = (c) => {
+    const bits = [c.cssName, c.type, valueLine(c.values)].filter(Boolean);
+    const usage = c.usage?.componentCount ? ` — used by ${c.usage.componentCount} component(s)` : '';
+    const flag = c.state && c.state !== 'ok' ? ` [${c.state}]` : '';
+    return `  ${c.path}\n    ${bits.join('  |  ')}${usage}${flag}`;
+};
+export const NO_MATCH_INSTRUCTION = 'These are the NEAREST tokens, not matches. Do not create a new token or hardcode a value on the '
+    + 'strength of this result — one of these may already be what you want, under a different name. '
+    + 'Ask which to use, or refine the search.';
+/** What `flareum_search` hands back. */
+export const formatSearch = (result) => {
+    if (!result.candidates.length)
+        return `No variables in this project yet (searched "${result.query}").`;
+    const header = result.matched
+        ? `Match for "${result.query}":`
+        : `No confident match for "${result.query}". ${result.reason ?? ''}`.trim();
+    const listed = result.candidates.map(describe).join('\n');
+    const footer = [];
+    if (!result.matched)
+        footer.push(NO_MATCH_INSTRUCTION);
+    if (result.truncated)
+        footer.push(`Showing ${result.candidates.length} of ${result.total}. Narrow the query to see others.`);
+    return [header, listed, ...footer].filter(Boolean).join('\n\n');
+};
+/** What `flareum_get` hands back — detail plus the blast radius of changing it. */
+export const formatVariable = (v) => {
+    const lines = [
+        v.path,
+        `  CSS name: ${v.cssName}`,
+        v.collectionName ? `  Collection: ${v.collectionName}` : '',
+        v.type ? `  Type: ${v.type}` : '',
+    ].filter(Boolean);
+    // Values are keyed by mode ID; label them with the mode's name, which is what a reader knows.
+    const modeName = new Map((v.modes ?? []).map(m => [m.id, m.name || m.selector || m.id]));
+    if (v.values)
+        for (const [mode, value] of Object.entries(v.values))
+            lines.push(`  ${modeName.get(mode) ?? mode}: ${value.resolved || value.value || '(empty)'}`);
+    // Both halves of blast radius, and each says what it does NOT know — absent usage data is not
+    // evidence that nothing uses it.
+    lines.push(v.usage
+        ? `  Used by ${v.usage.componentCount} component(s): ${v.usage.components.join(', ') || 'names unavailable'}`
+        : '  No component-usage data has been imported, so component usage is unknown.');
+    lines.push(v.referrers.length
+        ? `  Referenced by ${v.referrers.length} other variable(s): ${v.referrers.map(r => r.path).join(', ')}`
+        : '  No other variable references it.');
+    if (v.state && v.state !== 'ok')
+        lines.push(`  Status: ${v.state}`);
+    return lines.join('\n');
+};
+export const formatError = ({ code, message, hint }) => [`${message} (${code})`, hint].filter(Boolean).join('\n');
+export const TOOL_DESCRIPTIONS = {
+    search: 'Search the project\'s design tokens in Flareum. ALWAYS call this before proposing a new token '
+        + 'name or writing a literal colour, size or spacing value — the token you need usually already '
+        + 'exists under a name you would not guess. Matches on path, CSS name, resolved value (a hex '
+        + 'works), comment and component names. A result may be nearest-neighbours rather than a match; '
+        + 'read the header before acting.',
+    get: 'Read one design token in full: its value in every mode, its type, which components use it, and '
+        + 'which other tokens reference it. Use it to judge what a change would affect before making one.',
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@flareum/mcp",
+  "version": "0.1.0",
+  "description": "Connect a coding agent to a Flareum project's design tokens.",
+  "license": "MIT",
+  "author": "Flareum",
+  "homepage": "https://flareum.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/flareum-group/thegproject.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "flareum",
+    "design-tokens",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "design-system"
+  ],
+  "type": "module",
+  "bin": {
+    "flareum-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "cd ../.. && npx mocha --exit 'packages/mcp/src/**/*.test.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: flareum
+description: Use the project's Flareum design tokens instead of literal values. Invoke whenever you are about to write a colour, size, spacing, radius, shadow or duration in CSS/SCSS, or need to know which token a value corresponds to.
+---
+
+# Flareum design tokens
+
+This project's design tokens live in Flareum. The generated CSS/SCSS in the repo is a **rendering**
+of them — the tokens themselves, with their types, modes, comments and usage, are reachable through
+the `flareum_search` and `flareum_get` tools.
+
+## The one rule
+
+**Search before you write a literal value, and before you propose a token name.**
+
+A hardcoded `#5B8DEF` is a token that escaped the system. A newly invented `color/border/muted` beside
+an existing `color/border/secondary` is worse — it looks like a decision, and nobody will ever
+reconcile the two. `flareum_search` takes a hex, an rgb(), a path fragment, a phrase from a comment,
+or a component name.
+
+## Reading a search result
+
+The header tells you which kind of answer you got, and they mean different things:
+
+- **`Match for "…"`** — use it. The `cssName` is ready to paste.
+- **`No confident match for "…"`** — the listed tokens are **nearest neighbours, not matches**. One
+  of them is often the thing you want under a name you would not have guessed. **Do not create a
+  token or hardcode a value on the strength of this.** Ask which to use, or search again with the
+  value rather than the name.
+
+An empty project says so explicitly. Anything else always returns candidates.
+
+## If the token genuinely does not exist
+
+This integration is **read-only** — there is no tool that writes to Flareum, by design. So:
+
+1. Say which token is missing and what it would be for.
+2. Propose a name that fits the grammar below, so the designer can create it in one step.
+3. Do not silently hardcode the value and move on.
+
+## The naming grammar
+
+A token name is a serialized hierarchy, general → specific, terminal value last:
+
+```
+--[prefix]-[category]-[layer?]-[path...]-[value]
+```
+
+- **`category` always comes first** after the prefix: `color`, `space`, `size`, `radius`, `shadow`,
+  `blur`, `duration`, `z`, `opacity`, `font`, `border`.
+- **`layer`** is optional and names the tier. For colour: `primitive`, `global`, `semantic`,
+  `action_palette`, `action_state`, `action`. A raw scale (`--fui-space-4`) has none.
+- **A component is a `path` segment, never a top-level layer.**
+
+```css
+/* ✓ */ --fui-color-semantic-button-background-primary-hover
+/* ✗ */ --fui-button-color-background-primary-hover     /* component-first */
+/* ✗ */ --fui-semantic-color-text-primary               /* layer hoisted above the category */
+```
+
+Spell each segment the way the system already spells it — `disabled` not `disable`, `background` not
+`bg`, `accent` not `acent`. Search for the segment before coining a second spelling of a word that
+already exists; a new word is for a genuinely new concept only.
+
+## Blast radius before a change
+
+`flareum_get` reports two independent things, and they answer different questions:
+
+- **component usage** — which components consume it (from an imported analysis).
+- **referrers** — which other tokens reference it, and would break.
+
+If it says no usage data has been imported, that means **unknown**, not unused. Grep the repo
+yourself before treating a token as safe to change.