@flareum/mcp 0.2.2 → 0.2.4

package/README.md

@@ -50,6 +50,24 @@ npm install -g @flareum/mcp@latest
 
 ---
 
+## Removing it
+
+```bash
+claude mcp remove flareum
+```
+
+Run it in the same project directory you added it from — `claude mcp add` registers the server for
+that directory, so a removal elsewhere finds nothing. `claude mcp list` shows what is registered. If
+you added it with `-s user` or `-s project`, pass the same scope to remove it.
+
+That takes the key with it: it lived in the `--env FLAREUM_TOKEN=…` of the entry it just deleted.
+There is nothing else on disk unless you wrote a `.flareum/config.json` yourself.
+
+**The key still works.** Removing the server is a local change — anyone holding that string can
+still read the project's tokens. If it leaked, or the machine is gone, revoke it too.
+
+---
+
 ## What your agent can do with it
 
 Ask in plain language — the agent picks the tool:
@@ -108,6 +126,40 @@ nothing; only a Push does.
 
 ---
 
+## Revoking a key
+
+A key grants read access to one project's tokens until you revoke it. Revoke as soon as one is
+pasted into a chat, a ticket, a screenshot, or a repository — and when a laptop or a contractor
+leaves.
+
+**1. In Flareum**, open **Project settings → Connect**. Each connected editor is a row showing the
+last four characters of its key, when it was added and when it was last used. Click the delete
+button on the row you want gone.
+
+It takes effect immediately: every later call with that key answers `401`, and the key cannot be
+un-revoked. A revoked row disappears from the list rather than lingering as history — it is not a
+connection any more.
+
+If you cannot tell two rows apart, the key hint matches the last four characters of the key the
+editor is using, and **Last used** tells you which one is live.
+
+**2. On the machine that had it**, remove what is still holding the key — revoking stops it
+working, it does not delete the copy:
+
+```bash
+claude mcp remove flareum        # the entry, and the key inside it
+rm .flareum/config.json          # only if you wrote one by hand
+```
+
+Skip this and everything keeps trying the dead key, which reads as a broken integration rather than
+a revoked one.
+
+**3. To reconnect**, mint a new key from the same Connect screen and run the command it gives you.
+Keys are per editor, not per person — connecting a second machine means minting a second key, so
+losing one never means rotating the other.
+
+---
+
 ## Configuration
 
 | Variable | |
@@ -115,10 +167,24 @@ nothing; only a Push does.
 | `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. |
+| `FLAREUM_OUT` | optional. Where stylesheets are written. Same meaning as `out` in the config file, which it beats. |
+| `FLAREUM_AUTO_PULL` | optional. `off` stops the first-connection pull below. Anything else leaves it on. |
+
+On start it writes `.claude/skills/flareum/` into the working directory — the rules your agent needs
+to apply the tokens correctly. `SKILL.md` is the workflow and the router: how to read a search
+result, and where to go for the area being worked in. Each `references/*.md` beside it is one such
+area — `naming.md` for how a token name is built, `typography.md` for applying a text style with
+its class rather than the mixin behind it. The whole folder is rewritten every run, so do not edit
+it, and it prints where it wrote (or why it could not) on stderr.
+
+On the first connection it also **pulls the stylesheets**, once. It looks for the folder this project
+already keeps its styles in — `src/styles`, `app/styles`, `scss`, and the rest — and writes them to
+`<that folder>/flareum`, falling back to `styles/flareum` in a project that has none. It says on
+stderr where they landed.
 
-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.
+It runs only when that folder does not exist yet. After that the files are yours: `flareum pull`
+updates them on demand and `flareum watch` on every Push, both into the same folder. A failed pull
+is reported and nothing else — the token tools work without it. `FLAREUM_AUTO_PULL=off` turns it off.
 
 ---
 
@@ -181,7 +247,9 @@ to fetch.
 | `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. |
+| `src/first-pull.ts` | Chooses the styles folder, and pulls into it on a first connection. |
+| `skill/SKILL.md` | The router shipped to the agent: the workflow, and where each rule lives. |
+| `skill/references/` | One page per rule area. Every file here must be linked from SKILL.md. |
 
 `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

package/dist/cli.js

@@ -1,64 +1,93 @@
 #!/usr/bin/env node
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
-import { FlareumClient } from './client.js';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { FlareumApiError, FlareumClient } from './client.js';
 import { CONFIG_PATH, cliErrorReport, parseArgs, resolveConfig } from './config.js';
-import { pullReport, pullStyles } from './pull.js';
-import { DEFAULT_INTERVAL_MS, watchPublished, watchStartedReport } from './watch.js';
-const DEFAULT_OUT = 'src/styles/flareum';
+import { chooseStylesDir, fileWriter } from './first-pull.js';
+import { isRetryable, pullReport, pullStyles } from './pull.js';
+import { watchIntervalMs, watchPublished, watchStartedReport } from './watch.js';
+// Where the styles go is decided in ONE place, so the CLI and the server never disagree about it.
+const defaultOut = () => chooseStylesDir(path => existsSync(resolve(process.cwd(), path)));
 // Read rather than restated: a hardcoded version is wrong the moment `npm version` runs.
 const VERSION = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
 const HELP = `flareum — read a Flareum project's design tokens
 
   flareum pull [--out <dir>] [--token pk_…] [--api <url>]
       Write the stylesheets the last push published into <dir>
-      (default: ${DEFAULT_OUT}).
+      (default: the folder this project keeps its styles in — here, ${defaultOut()}).
 
   flareum watch [--out <dir>] [--interval <seconds>]
       Stay running and pull again every time you Push in Flareum.
 
 The key is taken from --token, then FLAREUM_TOKEN, then "token" in ${CONFIG_PATH}.
 Mint one in the project's Connect screen in Flareum.`;
-const readConfigFile = async () => readFile(join(process.cwd(), CONFIG_PATH), 'utf8').then(JSON.parse).catch(() => null);
-const { command, flags } = parseArgs(process.argv.slice(2));
+// An absent config is normal; one that fails to parse is a typo the user is staring at, and
+// collapsing both to null reported "No Flareum key" about the file holding the key.
+const readConfigFile = async () => {
+    const raw = await readFile(join(process.cwd(), CONFIG_PATH), 'utf8').catch(() => null);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Could not read ${CONFIG_PATH} — ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
 const COMMANDS = ['pull', 'watch'];
-// Read from flags, not `command`: parseArgs takes every leading `--x` as a flag, so checking the
-// command alone printed the help instead.
-if (flags.version || command === '-v') {
-    console.log(VERSION);
-    process.exit(0);
-}
-if (flags.help || command === '-h') {
-    console.log(HELP);
-    process.exit(0);
-}
-if (!COMMANDS.includes(command)) {
-    console.log(HELP);
-    process.exit(command ? 1 : 0);
-}
+// Everything the user can get wrong lives inside this one try, argument parsing included: a throw
+// above it printed a Node stack trace, which is the failure cliErrorReport exists to prevent.
 try {
+    const { command, flags } = parseArgs(process.argv.slice(2));
+    // Read from flags, not `command`: parseArgs takes every leading `--x` as a flag, so checking the
+    // command alone printed the help instead.
+    if (flags.version || command === '-v') {
+        console.log(VERSION);
+        process.exit(0);
+    }
+    if (flags.help || command === '-h') {
+        console.log(HELP);
+        process.exit(0);
+    }
+    if (!COMMANDS.includes(command)) {
+        console.log(HELP);
+        process.exit(command ? 1 : 0);
+    }
     const config = resolveConfig({ flags, env: process.env, file: await readConfigFile() });
-    const outDir = config.out ?? DEFAULT_OUT;
-    const root = resolve(process.cwd(), outDir);
+    const outDir = config.out ?? defaultOut();
     const client = new FlareumClient({ token: config.token, api: config.api });
-    const write = async (path, contents) => {
-        const target = join(root, path);
-        await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, contents, 'utf8');
-    };
+    const write = fileWriter(resolve(process.cwd(), outDir));
     const runPull = async () => {
         const result = await pullStyles(client, write);
         console.log(pullReport(result, outDir));
         return result;
     };
     if (command === 'watch') {
-        const intervalMs = Number(flags.interval) > 0 ? Number(flags.interval) * 1000 : DEFAULT_INTERVAL_MS;
+        const intervalMs = watchIntervalMs(flags.interval);
         console.log(watchStartedReport(outDir, intervalMs));
         let running = true;
         process.on('SIGINT', () => { running = false; console.log('\nStopped watching.'); process.exit(0); });
         await watchPublished({
-            publishedVersion: async () => (await client.files()).publishedVersionId,
-            onPublish: async () => { await runPull(); },
+            // watch treats null as "nothing published yet, wait quietly". Without this the CLI threw
+            // the 409 instead, so a never-pushed project printed an error on every tick forever.
+            publishedVersion: async () => {
+                try {
+                    return (await client.published()).publishedVersionId;
+                }
+                catch (error) {
+                    if (error instanceof FlareumApiError && error.code === 'NOT_PUBLISHED')
+                        return null;
+                    throw error;
+                }
+            },
+            // Throwing is what stops watch marking the version done: a file that failed for a
+            // retryable reason must be fetched again, not skipped until the next push.
+            onPublish: async () => {
+                const result = await runPull();
+                if (isRetryable(result))
+                    throw new Error(`${result.failed.length} file(s) failed — retrying on the next tick.`);
+            },
             onError: error => console.error(error instanceof Error ? error.message : String(error)),
             sleep: ms => new Promise(done => { setTimeout(done, ms); }),
             keepGoing: () => running,

package/dist/client.d.ts

@@ -22,6 +22,7 @@ export declare class FlareumClient {
     catalog(updatedSince?: string): Promise<CatalogResponse>;
     search(query: string, limit?: number): Promise<SearchResponse>;
     /** The stylesheets the last push published. They exist only after a push, never from a save. */
+    published(): Promise<PublishedResponse>;
     files(): Promise<FilesResponse>;
     file(path: string): Promise<string>;
     variable(path: string): Promise<VariableResponse>;
@@ -69,6 +70,9 @@ export type FilesResponse = {
     publishedVersionId: string;
     files: string[];
 };
+export type PublishedResponse = {
+    publishedVersionId: string;
+};
 export type VariableMode = {
     id: string;
     name: string;

package/dist/client.js

@@ -60,6 +60,8 @@ export class FlareumClient {
         const url = `${this.#api}/api/v1/projects/${this.projectId}${path}`;
         const response = await this.#fetch(url, {
             headers: { Authorization: `Bearer ${this.#token}`, Accept: 'text/plain' },
+        }).catch(error => {
+            throw new Error(`Could not reach ${this.#api} — ${error instanceof Error ? error.message : String(error)}`);
         });
         if (response.ok)
             return response.text();
@@ -75,6 +77,19 @@ export class FlareumClient {
         return this.#get('/search', { q: query, ...(limit ? { limit: String(limit) } : {}) });
     }
     /** The stylesheets the last push published. They exist only after a push, never from a save. */
+    // The watch's every-tick question. `/files` answers it too, but lists the whole bucket first — so
+    // ask the cheap endpoint, and fall back for a server older than it.
+    async published() {
+        try {
+            return await this.#get('/published');
+        }
+        catch (error) {
+            if (!(error instanceof FlareumApiError) || error.code !== 'HTTP_404')
+                throw error;
+            const { publishedVersionId } = await this.files();
+            return { publishedVersionId };
+        }
+    }
     files() {
         return this.#get('/files');
     }

package/dist/config.d.ts

@@ -12,6 +12,9 @@ export declare const CONFIG_PATH = ".flareum/config.json";
 export declare class MissingToken extends Error {
     constructor();
 }
+export declare class BareFlag extends Error {
+    constructor(name: string);
+}
 /** A flag beats the environment beats the file — nearest to the command wins. */
 export declare const resolveConfig: ({ flags, env, file }: ConfigSources) => Resolved;
 /** `--out dir --token x` and `--out=dir`, both. Anything else is a positional. */

package/dist/config.js

@@ -11,17 +11,29 @@ export class MissingToken extends Error {
         this.name = 'MissingToken';
     }
 }
+export class BareFlag extends Error {
+    constructor(name) {
+        super(`--${name} needs a value, e.g. --${name} <value> or --${name}=<value>.`);
+        this.name = 'BareFlag';
+    }
+}
 /** A flag beats the environment beats the file — nearest to the command wins. */
 export const resolveConfig = ({ flags, env, file }) => {
     const token = flags.token || env.FLAREUM_TOKEN || file?.token;
     if (!token)
         throw new MissingToken();
+    // The file's host travels only with the file's token. A checked-in config is somebody else's
+    // input, and pointing an ambient FLAREUM_TOKEN at their host is how the key leaves the machine.
+    const fileApi = file?.token && token === file.token ? file.api : undefined;
     return {
         token,
-        api: flags.api || env.FLAREUM_API || file?.api,
+        api: flags.api || env.FLAREUM_API || fileApi,
         out: flags.out || file?.out,
     };
 };
+// Flags that mean nothing without a value. --version / --help are deliberately absent: a bare one
+// is the whole point of them.
+const VALUE_FLAGS = new Set(['out', 'token', 'api', 'interval']);
 /** `--out dir --token x` and `--out=dir`, both. Anything else is a positional. */
 export const parseArgs = (argv) => {
     const flags = {};
@@ -42,6 +54,8 @@ export const parseArgs = (argv) => {
             flags[name] = next;
             i += 1;
         }
+        else if (VALUE_FLAGS.has(name))
+            throw new BareFlag(name);
         else
             flags[name] = 'true';
     }

package/dist/first-pull.d.ts

@@ -0,0 +1,31 @@
+import type { FlareumClient } from './client.js';
+import { type PullResult } from './pull.js';
+/** Does this path exist, relative to the project root? Injected so the choice is testable. */
+export type Probe = (path: string) => boolean;
+/**
+ * Where this project's Flareum stylesheets belong. ONE decision, used by the CLI's default and by
+ * the server's first pull — two answers would write the same files to two places.
+ */
+export declare const chooseStylesDir: (exists: Probe, configured?: string) => string;
+export declare const autoPullEnabled: (env: Record<string, string | undefined>) => boolean;
+/** Only ever the FIRST time: an existing directory is the developer's, and `flareum pull` owns updates. */
+export declare const needsFirstPull: (exists: Probe, dir: string) => boolean;
+export type FirstPull = {
+    ran: false;
+    reason: 'disabled' | 'already-pulled';
+    dir: string;
+} | {
+    ran: true;
+    dir: string;
+    result: PullResult;
+} | {
+    ran: false;
+    reason: 'failed';
+    dir: string;
+    error: string;
+};
+export declare const firstPullReport: (outcome: FirstPull) => string | null;
+/** Writes under `root`, refusing nothing the pull already refuses (see isWritablePath). */
+export declare const fileWriter: (root: string) => (path: string, contents: string) => Promise<void>;
+export declare const configuredOut: (cwd: string, env: Record<string, string | undefined>) => string | undefined;
+export declare const runFirstPull: (client: Pick<FlareumClient, "files" | "file">, cwd: string, env: Record<string, string | undefined>, configuredOut?: string) => Promise<FirstPull>;

package/dist/first-pull.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { CONFIG_PATH } from './config.js';
+import { pullStyles } from './pull.js';
+// Most specific first. A repo that keeps stylesheets in app/styles gets them there rather than in a
+// src/styles nobody in that project looks at.
+const STYLE_ROOTS = [
+    'src/styles', 'src/style', 'src/assets/styles', 'src/scss', 'src/css',
+    'app/styles', 'app/assets/styles', 'assets/styles', 'styles', 'scss', 'css',
+];
+const LEAF = 'flareum';
+/**
+ * Where this project's Flareum stylesheets belong. ONE decision, used by the CLI's default and by
+ * the server's first pull — two answers would write the same files to two places.
+ */
+export const chooseStylesDir = (exists, configured) => {
+    if (configured)
+        return configured;
+    // An earlier pull already answered this. Re-deciding would strand those files and pull a second copy.
+    const pulled = STYLE_ROOTS.map(root => `${root}/${LEAF}`).find(exists);
+    if (pulled)
+        return pulled;
+    const root = STYLE_ROOTS.find(exists);
+    if (root)
+        return `${root}/${LEAF}`;
+    return exists('src') ? `src/styles/${LEAF}` : `styles/${LEAF}`;
+};
+// Opt-out, not opt-in: a project with no stylesheets is the case this exists for, and a stdio server
+// has nobody to ask at startup. Anything but an explicit off means on.
+export const autoPullEnabled = (env) => !['off', 'false', '0', 'no'].includes((env.FLAREUM_AUTO_PULL ?? '').trim().toLowerCase());
+/** Only ever the FIRST time: an existing directory is the developer's, and `flareum pull` owns updates. */
+export const needsFirstPull = (exists, dir) => !exists(dir);
+export const firstPullReport = (outcome) => {
+    // Silence is right for a start that did nothing — this prints on every server start.
+    if (!outcome.ran && outcome.reason !== 'failed')
+        return null;
+    if (!outcome.ran)
+        return `[flareum] could NOT pull the stylesheets into ${outcome.dir} — ${outcome.error}. `
+            + 'The token tools still work; run `npx -p @flareum/mcp flareum pull` to retry.';
+    const { written, failed } = outcome.result;
+    const head = `[flareum] no local stylesheets — pulled ${written.length} into ${outcome.dir}. `
+        + 'Run `npx -p @flareum/mcp flareum watch` to keep them current, or set FLAREUM_AUTO_PULL=off.';
+    return failed.length ? `${head}\n[flareum] ${failed.length} could not be written: `
+        + failed.map(({ path, reason }) => `${path} — ${reason}`).join('; ') : head;
+};
+/** Writes under `root`, refusing nothing the pull already refuses (see isWritablePath). */
+export const fileWriter = (root) => async (path, contents) => {
+    const target = join(root, path);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, contents, 'utf8');
+};
+// The same `out` the CLI honours, read the same way — otherwise the server pulls into one folder and
+// `flareum pull` updates another.
+export const configuredOut = (cwd, env) => {
+    if (env.FLAREUM_OUT)
+        return env.FLAREUM_OUT;
+    try {
+        return JSON.parse(readFileSync(resolve(cwd, CONFIG_PATH), 'utf8')).out || undefined;
+    }
+    catch {
+        // No config file, or an unreadable one: fall through to the folder probe rather than failing.
+        return undefined;
+    }
+};
+export const runFirstPull = async (client, cwd, env, configuredOut) => {
+    const exists = path => existsSync(resolve(cwd, path));
+    const dir = chooseStylesDir(exists, configuredOut);
+    if (!autoPullEnabled(env))
+        return { ran: false, reason: 'disabled', dir };
+    if (!needsFirstPull(exists, dir))
+        return { ran: false, reason: 'already-pulled', dir };
+    try {
+        return { ran: true, dir, result: await pullStyles(client, fileWriter(resolve(cwd, dir))) };
+    }
+    catch (error) {
+        // A project with nothing published, an expired key, no network — none of them may stop the server.
+        return { ran: false, reason: 'failed', dir, error: error instanceof Error ? error.message : String(error) };
+    }
+};

package/dist/pull.d.ts

@@ -5,8 +5,11 @@ export type PullResult = {
     failed: Array<{
         path: string;
         reason: string;
+        permanent: boolean;
     }>;
 };
 export type Writer = (path: string, contents: string) => Promise<void>;
+export declare const isWritablePath: (path: string) => boolean;
 export declare const pullStyles: (client: Pick<FlareumClient, "files" | "file">, write: Writer) => Promise<PullResult>;
+export declare const isRetryable: ({ failed }: PullResult) => boolean;
 export declare const pullReport: ({ publishedVersionId, written, failed }: PullResult, outDir: string) => string;

package/dist/pull.js

@@ -1,3 +1,15 @@
+const STYLESHEET = /\.s?css$/i;
+// The server says where to write, and a --api flag lets anyone be the server. Refused rather than
+// normalised: repairing a path that climbs out of the output directory is how traversal gets through.
+export const isWritablePath = (path) => {
+    if (!path || !STYLESHEET.test(path))
+        return false;
+    if (path.startsWith('/') || path.includes('\\') || path.includes('\0'))
+        return false;
+    if (/^[a-zA-Z]:/.test(path))
+        return false;
+    return !path.split('/').includes('..');
+};
 // Copies the ARTIFACT a push generated; never rebuilds CSS from the catalog, so a name here and a
 // name the API reports cannot disagree.
 export const pullStyles = async (client, write) => {
@@ -6,15 +18,24 @@ export const pullStyles = async (client, write) => {
     const failed = [];
     for (const path of files)
         try {
+            if (!isWritablePath(path)) {
+                failed.push({ path, reason: 'refused — not a stylesheet inside the output directory',
+                    permanent: true });
+                continue;
+            }
             await write(path, await client.file(path));
             written.push(path);
         }
         catch (error) {
-            // One unreadable file must not lose the rest, and must not be reported as written.
-            failed.push({ path, reason: error instanceof Error ? error.message : String(error) });
+            // One unreadable file must not lose the rest, and must not be reported as written. Marked
+            // retryable: unlike a refusal, a read or write that failed once can succeed next time.
+            failed.push({ path, reason: error instanceof Error ? error.message : String(error),
+                permanent: false });
         }
     return { publishedVersionId, written, failed };
 };
+// A refusal will fail identically forever; anything else is worth another attempt.
+export const isRetryable = ({ failed }) => failed.some(f => !f.permanent);
 export const pullReport = ({ publishedVersionId, written, failed }, outDir) => {
     const lines = [`Pulled ${written.length} stylesheet(s) from version ${publishedVersionId} into ${outDir}`];
     for (const path of written)

package/dist/server.js

@@ -8,6 +8,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { FlareumApiError, FlareumClient } from './client.js';
 import { TOOL_DESCRIPTIONS, formatError, formatSearch, formatVariable } from './tools.js';
 import { installSkill, skillInstallReport } from './skill.js';
+import { configuredOut, firstPullReport, runFirstPull } from './first-pull.js';
 const client = new FlareumClient({
     token: process.env.FLAREUM_TOKEN ?? '',
     api: process.env.FLAREUM_API,
@@ -64,4 +65,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 // Never silently: if the skill does not land, the agent hardcodes values and nothing says why.
 console.error(skillInstallReport(await installSkill(process.cwd())));
+// First connection with no stylesheets pulled yet: fetch them now, into the folder this project
+// already keeps its styles in. Reported, never asked — a stdio server has nobody to prompt.
+const firstPull = firstPullReport(await runFirstPull(client, process.cwd(), process.env, configuredOut(process.cwd(), process.env)));
+if (firstPull)
+    console.error(firstPull);
 await server.connect(new StdioServerTransport());

package/dist/skill.js

@@ -1,15 +1,24 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, 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.
+// Every file under skill/, not just SKILL.md: it is a router now, and a reference it points at but
+// never wrote is a rule the agent silently never reads. One failure fails the whole install.
+const copyTree = async (from, to) => {
+    await mkdir(to, { recursive: true });
+    for (const entry of await readdir(from, { withFileTypes: true }))
+        if (entry.isDirectory())
+            await copyTree(join(from, entry.name), join(to, entry.name));
+        else
+            await writeFile(join(to, entry.name), await readFile(join(from, entry.name), 'utf8'), 'utf8');
+};
+// Written on every start, not once: a stale copy of the rules is worse than none, and the files are
+// generated rather than hand-edited.
 export const installSkill = async (cwd) => {
-    const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'skill', 'SKILL.md');
+    const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'skill');
     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');
+        await copyTree(source, join(cwd, ...SKILL_DIR));
         return { ok: true, path };
     }
     catch (error) {

package/dist/watch.d.ts

@@ -7,5 +7,7 @@ export type WatchDeps = {
     keepGoing: () => boolean;
 };
 export declare const DEFAULT_INTERVAL_MS = 15000;
+export declare const MIN_INTERVAL_MS = 2000;
+export declare const watchIntervalMs: (seconds: string | undefined) => number;
 export declare const watchPublished: ({ publishedVersion, onPublish, onError, sleep, keepGoing }: WatchDeps, intervalMs?: number) => Promise<void>;
 export declare const watchStartedReport: (outDir: string, intervalMs: number) => string;

package/dist/watch.js

@@ -1,4 +1,13 @@
 export const DEFAULT_INTERVAL_MS = 15_000;
+export const MIN_INTERVAL_MS = 2_000;
+// A floor, not a default: `--interval 0.001` asked for a thousand polls a second, which the API
+// answers with 429s rather than data.
+export const watchIntervalMs = (seconds) => {
+    const asked = Number(seconds) * 1000;
+    if (!Number.isFinite(asked) || asked <= 0)
+        return DEFAULT_INTERVAL_MS;
+    return Math.max(asked, MIN_INTERVAL_MS);
+};
 // Re-pulls when the PUBLISHED version changes — a push, never a save, so a designer mid-edit cannot
 // rewrite a file the developer is looking at.
 export const watchPublished = async ({ publishedVersion, onPublish, onError, sleep, keepGoing }, intervalMs = DEFAULT_INTERVAL_MS) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flareum/mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Connect a coding agent to a Flareum project's design tokens.",
   "license": "MIT",
   "author": "Flareum",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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, duration or text style in CSS/SCSS/HTML, or need to know which token a value corresponds to.
 ---
 
 # Flareum design tokens
@@ -9,6 +9,9 @@ This project's design tokens live in Flareum. The generated CSS/SCSS in the repo
 of them — the tokens themselves, with their types, modes, comments and usage, are reachable through
 the `flareum_search` and `flareum_get` tools.
 
+Every name here is written with **`[prefix]`** where your project's own token prefix goes — the
+string every `cssName` in a search result starts with. Substitute it; never write `[prefix]` itself.
+
 ## The one rule
 
 **Search before you write a literal value, and before you propose a token name.**
@@ -18,6 +21,16 @@ an existing `color/border/secondary` is worse — it looks like a decision, and
 reconcile the two. `flareum_search` takes a hex, an rgb(), a path fragment, a phrase from a comment,
 or a component name.
 
+## The rules, by topic
+
+This page is the workflow. Open the one below that covers what you are about to write — each is a
+page, and it is worth reading in full before the first line of code.
+
+| Writing | Read |
+|---|---|
+| Any text — a heading, a label, body copy, a pseudo-element's `content` | [references/typography.md](references/typography.md) |
+| A token name, or judging one that already exists | [references/naming.md](references/naming.md) |
+
 ## Reading a search result
 
 The header tells you which kind of answer you got, and they mean different things:
@@ -35,33 +48,9 @@ An empty project says so explicitly. Anything else always returns candidates.
 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.
+2. Propose a name that fits [the grammar](references/naming.md), 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:

package/skill/references/naming.md

@@ -0,0 +1,36 @@
+# Token naming
+
+Read this before proposing a token name, or when judging whether a name that already exists is the
+one you want.
+
+## The 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 (`--[prefix]-space-4`) has none.
+- **A component is a `path` segment, never a top-level layer.**
+
+```css
+/* ✓ */ --[prefix]-color-semantic-button-background-primary-hover
+/* ✗ */ --[prefix]-button-color-background-primary-hover     /* component-first */
+/* ✗ */ --[prefix]-semantic-color-text-primary               /* layer hoisted above the category */
+```
+
+Build the tree first, then serialize it — `color → semantic → input → border → error` is what makes
+`--[prefix]-color-semantic-input-border-error` the only possible spelling of it.
+
+## One word per concept
+
+Spell each segment the way the system already spells it — `disabled` not `disable`, `background` not
+`bg`, `accent` not `acent`. Two spellings of one word mean nobody can find every token for it, or
+trust that they have.
+
+So `flareum_search` for the segment before coining a word. A new word is for a genuinely new concept
+only; a shorter way to write one that exists is not a new concept.

package/skill/references/typography.md

@@ -0,0 +1,55 @@
+# Text styles
+
+Read this before styling any text — a heading, a label, body copy, a value in a table cell, or a
+pseudo-element's `content`.
+
+## The class, not the mixin
+
+Flareum exports every text style twice — a ready-made **class** in `typography/_styles.scss`, and the
+**mixin** it is built from in `typography/_mixins.scss`. They are not two ways of doing the same
+thing. **The class is how a text style is applied; the mixin is a fallback for the few elements a
+class cannot reach.**
+
+Put the pair on the element that holds the text — the base class plus the style class:
+
+```html
+<h2 class="[prefix]-typography [prefix]-h5">Export settings</h2>
+<p class="[prefix]-typography [prefix]-t2">Choose which collections ship to Figma.</p>
+<span class="[prefix]-typography [prefix]-t2 [prefix]-bold">12 variables</span>
+```
+
+Both halves are required. The base class declares the shared properties (`--line-height` among them)
+and the style class re-points them, so a style class on its own applies nothing. A variant slot —
+`bold`, `regular`, `highlight` — is a third class beside the style, never a replacement for it.
+
+Why the class wins: it names the style in the markup, where the next person reading the template can
+see which style an element uses and change it without opening a stylesheet; and one rule serves every
+element that carries it, instead of each component compiling its own copy of the same declarations.
+
+## The exception
+
+**Reach for the mixin only where no class can be placed** — a pseudo-element, or markup you do not
+render (a third-party widget, generated HTML) and therefore cannot add an attribute to.
+
+```scss
+// ::after has no class attribute — the only way to give it the style
+.field::after {
+  content: attr(data-hint);
+  @include [prefix]-typography-t3;
+}
+```
+
+That is the whole list. "It was easier from SCSS" is not on it: a mixin reached for out of convenience
+hides the style from the markup and duplicates the declarations into every component that includes it.
+
+## When a style looks like it is not applying
+
+Check these before overriding anything — each one silently beats the class rather than erroring:
+
+- **A lone style class.** `[prefix]-h5` with no `[prefix]-typography` beside it applies nothing.
+- **A `font:` shorthand on the same element.** It resets family, size, weight and line-height in one
+  go, and component styles load after the global ones. Use the longhand for the one thing you meant
+  to change.
+- **A missing `--line-height`.** Padding computed from it resolves to an invalid `calc()`, and the
+  property falls back to its initial value with nothing in the console. The typography class has to
+  be on the element that reads the variable, or an ancestor of it.