@flareum/mcp 0.2.11 → 0.5.0

package/README.md

@@ -182,7 +182,7 @@ nothing runs until you open a session — or run `claude mcp list`, which connec
 and is why the skill sometimes appears then. `flareum pull` writes it too, so one pull sets the
 project up without waiting for a connection.
 
-On the first connection it also **pulls the stylesheets**, once. It looks for the folder this project
+On connection it also **pulls the stylesheets** whenever the published version has moved. 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.

package/dist/cli.js

@@ -6,6 +6,8 @@ import { FlareumApiError, FlareumClient } from './client.js';
 import { CONFIG_PATH, cliErrorReport, parseArgs, resolveConfig } from './config.js';
 import { chooseStylesDir, fileWriter } from './first-pull.js';
 import { isRetryable, pullReport, pullStyles } from './pull.js';
+import { makeLock, writeLock } from './lock.js';
+import { projectIdFromToken } from './client.js';
 import { installSkill, skillInstallReport } from './skill.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.
@@ -64,6 +66,10 @@ try {
     console.log(skillInstallReport(await installSkill(process.cwd())));
     const runPull = async () => {
         const result = await pullStyles(client, write);
+        // The server reads this lock to decide whether to pull. Without it a CLI pull was invisible,
+        // and the next connection fetched the same version again.
+        if (!isRetryable(result))
+            await writeLock(process.cwd(), makeLock(projectIdFromToken(config.token), result.publishedVersionId, outDir, new Date().toISOString()));
         console.log(pullReport(result, outDir));
         return result;
     };

package/dist/client.d.ts

@@ -23,6 +23,7 @@ export declare class FlareumClient {
     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>;
+    changes(since?: string): Promise<ChangesResponse>;
     files(): Promise<FilesResponse>;
     file(path: string): Promise<string>;
     variable(path: string): Promise<VariableResponse>;
@@ -73,6 +74,46 @@ export type FilesResponse = {
 export type PublishedResponse = {
     publishedVersionId: string;
 };
+export type ChangeEntry = {
+    kind: string;
+    change: string;
+    id: string;
+    before?: {
+        path?: string;
+        cssName?: string;
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    after?: {
+        path?: string;
+        cssName?: string;
+        name?: string;
+        value?: string;
+        type?: string;
+    };
+    replacement?: {
+        cssName?: string;
+        value?: string;
+    };
+    viaFolder?: {
+        from: string;
+        to: string;
+    };
+    mode?: string;
+    collection?: {
+        id: string;
+        name: string;
+    };
+};
+export type ChangesResponse = {
+    since: string | null;
+    liveVersionId: string;
+    publishedVersionId: string | null;
+    totalChanges: number;
+    entries: ChangeEntry[];
+    truncated: boolean;
+};
 export type VariableMode = {
     id: string;
     name: string;

package/dist/client.js

@@ -90,6 +90,9 @@ export class FlareumClient {
             return { publishedVersionId };
         }
     }
+    changes(since = '') {
+        return this.#get('/changes', { since });
+    }
     files() {
         return this.#get('/files');
     }

package/dist/config.js

@@ -28,7 +28,7 @@ export const resolveConfig = ({ flags, env, file }) => {
     return {
         token,
         api: flags.api || env.FLAREUM_API || fileApi,
-        out: flags.out || file?.out,
+        out: flags.out || env.FLAREUM_OUT || file?.out,
     };
 };
 // Flags that mean nothing without a value. --version / --help are deliberately absent: a bare one

package/dist/first-pull.d.ts

@@ -9,11 +9,12 @@ export type Probe = (path: string) => boolean;
 export declare const chooseStylesDir: (exists: Probe, configured?: string) => string;
 export declare const autoPullEnabled: (env: Record<string, string | undefined>) => boolean;
 export declare const STAMP = ".flareum-version";
-export declare const pulledVersion: (read: (path: string) => string | null, dir: string) => string | null;
-export declare const needsPull: (exists: Probe, read: (path: string) => string | null, dir: string, published: string | null) => boolean;
+export declare const PENDING = "pending";
+export declare const needsPull: (exists: Probe, claimed: boolean, synced: string | null, dir: string, published: string | null, isEmpty?: Probe) => boolean;
+export declare const unclaimed: (exists: Probe, claimed: boolean, dir: string, isEmpty: Probe) => boolean;
 export type FirstPull = {
     ran: false;
-    reason: 'disabled' | 'up-to-date';
+    reason: 'disabled' | 'up-to-date' | 'unclaimed';
     dir: string;
 } | {
     ran: true;
@@ -29,4 +30,4 @@ 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" | "published">, cwd: string, env: Record<string, string | undefined>, configuredOut?: string) => Promise<FirstPull>;
+export declare const runFirstPull: (client: Pick<FlareumClient, "files" | "file" | "published">, cwd: string, env: Record<string, string | undefined>, configuredOut?: string, knownVersion?: string | null, now?: () => string) => Promise<FirstPull>;

package/dist/first-pull.js

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
+import { projectIdFromToken } from './client.js';
 import { CONFIG_PATH } from './config.js';
+import { IN_FLIGHT, LEGACY_STAMP, legacyVersion, makeLock, owns, readLock, syncedVersion, writeLock, } from './lock.js';
 import { isRetryable, 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.
@@ -30,18 +32,27 @@ export const chooseStylesDir = (exists, configured) => {
 // 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());
 // A stamp beside the files, not in config.json: config is the developer's, this is bookkeeping.
-export const STAMP = '.flareum-version';
-export const pulledVersion = (read, dir) => read(join(dir, STAMP))?.trim() || null;
-// Pull when there is nothing here, or when what is published is not what is on disk. Connecting
-// used to be a one-time event, so a project pulled once never saw another push.
-export const needsPull = (exists, read, dir, published) => {
+// Kept only so a 0.2.x stamp can be adopted; the anchor is .flareum/lock.json now.
+export const STAMP = LEGACY_STAMP;
+export const PENDING = IN_FLIGHT;
+// Pull when the folder is ours and stale, or absent. A folder holding files we never stamped is
+// somebody else's — this repo's own read-only src/styles/flareum is exactly that.
+export const needsPull = (exists, claimed, synced, dir, published, isEmpty = () => true) => {
     if (!exists(dir))
         return true;
     if (!published)
         return false;
-    return pulledVersion(read, dir) !== published;
+    if (!claimed)
+        return isEmpty(dir);
+    return synced !== published;
 };
+// Present, not ours, and not to be written over. Ownership is the lock naming this folder.
+export const unclaimed = (exists, claimed, dir, isEmpty) => exists(dir) && !claimed && !isEmpty(dir);
 export const firstPullReport = (outcome) => {
+    // Said once, because leaving a folder alone silently looks like a broken pull.
+    if (!outcome.ran && outcome.reason === 'unclaimed')
+        return `[flareum] ${outcome.dir} already holds files this did not write, so it was left alone. `
+            + 'Run `npx -p @flareum/mcp flareum pull` to replace them deliberately.';
     // Silence is right for a start that did nothing — this prints on every server start.
     if (!outcome.ran && outcome.reason !== 'failed')
         return null;
@@ -57,9 +68,21 @@ export const firstPullReport = (outcome) => {
     return failed.length ? `${head}\n[flareum] ${failed.length} could not be written: `
         + failed.map(({ path, reason }) => `${path} — ${reason}`).join('; ') : head;
 };
+// isWritablePath checks the path STRING; writeFile follows what is on DISK. A symlink already at
+// the target wrote straight through it, out of the directory — refused rather than followed.
+const isSymlink = (path) => {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
 /** Writes under `root`, refusing nothing the pull already refuses (see isWritablePath). */
 export const fileWriter = (root) => async (path, contents) => {
     const target = join(root, path);
+    if (isSymlink(target))
+        throw new Error(`refused — ${path} is a symlink`);
     await mkdir(dirname(target), { recursive: true });
     await writeFile(target, contents, 'utf8');
 };
@@ -76,28 +99,41 @@ export const configuredOut = (cwd, env) => {
         return undefined;
     }
 };
-export const runFirstPull = async (client, cwd, env, configuredOut) => {
+export const runFirstPull = async (client, cwd, env, configuredOut, knownVersion, now = () => new Date().toISOString()) => {
     const exists = path => existsSync(resolve(cwd, path));
-    const read = (path) => {
+    const isEmpty = path => {
         try {
-            return readFileSync(resolve(cwd, path), 'utf8');
+            return readdirSync(resolve(cwd, path)).length === 0;
         }
         catch {
-            return null;
+            return true;
         }
     };
     const dir = chooseStylesDir(exists, configuredOut);
     if (!autoPullEnabled(env))
         return { ran: false, reason: 'disabled', dir };
+    const lock = readLock(cwd);
+    // A 0.2.x project recorded the version beside the stylesheets. Adopted, so an upgrade does not
+    // re-pull what is already on disk, and the folder is recognised as ours rather than a stranger's.
+    const adopted = legacyVersion(cwd, dir);
+    const claimed = owns(lock, dir) || adopted !== null;
+    const synced = syncedVersion(lock, dir) ?? adopted;
     try {
-        const published = await client.published().then(r => r.publishedVersionId).catch(() => null);
-        if (!needsPull(exists, read, dir, published))
-            return { ran: false, reason: 'up-to-date', dir };
+        const published = knownVersion !== undefined
+            ? knownVersion
+            : await client.published().then(r => r.publishedVersionId).catch(() => null);
+        if (!needsPull(exists, claimed, synced, dir, published, isEmpty))
+            return { ran: false, reason: unclaimed(exists, claimed, dir, isEmpty) ? 'unclaimed' : 'up-to-date', dir };
+        const projectId = projectIdFromToken(env.FLAREUM_TOKEN ?? '');
+        // Claimed BEFORE the first write: an interrupted pull leaves files with no completed version,
+        // and without this it would read as somebody else's folder and never be finished.
+        await mkdir(resolve(cwd, dir), { recursive: true });
+        await writeLock(cwd, makeLock(projectId, IN_FLIGHT, dir, now()));
         const result = await pullStyles(client, fileWriter(resolve(cwd, dir)));
-        // Stamped only when the WHOLE version landed. pullStyles resolves even when files failed, so
-        // stamping on its return recorded a half-pulled folder as complete and never retried it.
+        // Recorded only when the WHOLE version landed: pullStyles resolves even when files failed, so
+        // stamping on its return marked a half-pulled folder complete and never retried it.
         if (!isRetryable(result))
-            await writeFile(resolve(cwd, dir, STAMP), `${result.publishedVersionId}\n`, 'utf8');
+            await writeLock(cwd, makeLock(projectId, result.publishedVersionId, dir, now()));
         return { ran: true, dir, result };
     }
     catch (error) {

package/dist/key-check.d.ts

@@ -1,14 +1,16 @@
 export type KeyCheck = {
     usable: true;
+    version?: string | null;
 } | {
     usable: false;
     fatal: true;
     message: string;
+    version?: undefined;
 } | {
     usable: false;
     fatal: false;
     message: string;
+    version?: undefined;
 };
 export declare const classifyKeyCheck: (error: unknown) => KeyCheck;
-/** One cheap authenticated call, so "connected" cannot mean "holding a key the server rejects". */
-export declare const checkKey: (probe: () => Promise<unknown>) => Promise<KeyCheck>;
+export declare const checkKey: (probe: () => Promise<string | null>) => Promise<KeyCheck>;

package/dist/key-check.js

@@ -22,11 +22,11 @@ export const classifyKeyCheck = (error) => {
             + 'Starting anyway; the token tools will report their own errors.',
     };
 };
-/** One cheap authenticated call, so "connected" cannot mean "holding a key the server rejects". */
+// One cheap authenticated call, so "connected" cannot mean "holding a key the server rejects". The
+// answer is carried out: startup needs the same version, and asking twice can cost two bucket lists.
 export const checkKey = async (probe) => {
     try {
-        await probe();
-        return { usable: true };
+        return { usable: true, version: await probe() };
     }
     catch (error) {
         return classifyKeyCheck(error);

package/dist/lock.d.ts

@@ -0,0 +1,18 @@
+export declare const LOCK_PATH = ".flareum/lock.json";
+export type Lock = {
+    projectId: string;
+    syncedVersionId: string;
+    syncedAt: string;
+    out: string;
+    prefix?: string;
+};
+export declare const IN_FLIGHT = "pending";
+export declare const readLock: (cwd: string) => Lock | null;
+/** The folder is ours when the lock names it — a pull in flight counts, so it can be finished. */
+export declare const owns: (lock: Lock | null, dir: string) => boolean;
+export declare const syncedVersion: (lock: Lock | null, dir: string) => string | null;
+export declare const writeLock: (cwd: string, lock: Lock) => Promise<void>;
+export declare const makeLock: (projectId: string, syncedVersionId: string, out: string, at: string, prefix?: string) => Lock;
+export declare const LEGACY_STAMP = ".flareum-version";
+export declare const legacyVersion: (cwd: string, dir: string) => string | null;
+export declare const legacyStampExists: (cwd: string, dir: string) => boolean;

package/dist/lock.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export const LOCK_PATH = '.flareum/lock.json';
+export const IN_FLIGHT = 'pending';
+export const readLock = (cwd) => {
+    try {
+        const lock = JSON.parse(readFileSync(join(cwd, LOCK_PATH), 'utf8'));
+        return lock.out ? lock : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** The folder is ours when the lock names it — a pull in flight counts, so it can be finished. */
+export const owns = (lock, dir) => !!lock && lock.out === dir;
+export const syncedVersion = (lock, dir) => owns(lock, dir) && lock.syncedVersionId !== IN_FLIGHT ? lock.syncedVersionId : null;
+export const writeLock = async (cwd, lock) => {
+    const path = join(cwd, LOCK_PATH);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+};
+export const makeLock = (projectId, syncedVersionId, out, at, prefix) => ({ projectId, syncedVersionId, syncedAt: at, out, ...(prefix ? { prefix } : {}) });
+// A project pulled by 0.2.x recorded the version in a stamp beside the stylesheets. Adopted rather
+// than ignored, so an upgrade does not re-pull a version already on disk.
+export const LEGACY_STAMP = '.flareum-version';
+export const legacyVersion = (cwd, dir) => {
+    try {
+        const raw = readFileSync(join(cwd, dir, LEGACY_STAMP), 'utf8').trim();
+        return !raw || raw === IN_FLIGHT ? null : raw;
+    }
+    catch {
+        return null;
+    }
+};
+export const legacyStampExists = (cwd, dir) => existsSync(join(cwd, dir, LEGACY_STAMP));

package/dist/project-config.d.ts

@@ -6,5 +6,6 @@ export type ConfigWrite = {
     path: string;
     gitignored: boolean;
 };
+export declare const repoRoot: (from: string, exists: (path: string) => boolean) => string | null;
 export declare const writeProjectConfig: (cwd: string, env: Record<string, string | undefined>, out?: string) => Promise<ConfigWrite>;
 export declare const projectConfigReport: (result: ConfigWrite) => string | null;

package/dist/project-config.js

@@ -1,18 +1,39 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { appendFile, mkdir, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, join, parse } from 'node:path';
 import { CONFIG_PATH } from './config.js';
-const IGNORE_LINE = '.flareum/';
+// The KEY, not the directory: lock.json lives beside it and is committed deliberately — it makes
+// "which token version is this branch built against" a reviewable fact in the pull request.
+const IGNORE_LINE = '.flareum/config.json';
+const BLANKET = '.flareum/';
+const KEEP_LOCK = '!.flareum/lock.json';
+// The repo ROOT, not cwd: a nested package has no .git of its own, and a bare pattern there matches
+// at any depth. `.git` may be a file — worktrees and submodules write one.
+export const repoRoot = (from, exists) => {
+    let dir = from;
+    for (;;) {
+        if (exists(join(dir, '.git')))
+            return dir;
+        const up = dirname(dir);
+        if (up === dir || dir === parse(dir).root)
+            return null;
+        dir = up;
+    }
+};
 // Appended only when the pattern is absent: this file holds a key, and a project that commits it
 // has published one. Never rewrites an existing .gitignore beyond that one line.
 const ensureGitignored = async (cwd) => {
-    const path = join(cwd, '.gitignore');
     try {
-        if (existsSync(path) && readFileSync(path, 'utf8').split('\n').some(l => l.trim() === IGNORE_LINE))
-            return true;
-        if (!existsSync(join(cwd, '.git')))
+        const root = repoRoot(cwd, existsSync);
+        if (!root)
             return false;
-        await appendFile(path, `\n# Holds a Flareum API key\n${IGNORE_LINE}\n`, 'utf8');
+        const path = join(root, '.gitignore');
+        const lines = existsSync(path) ? readFileSync(path, 'utf8').split('\n').map(l => l.trim()) : [];
+        if (lines.includes(IGNORE_LINE) || lines.includes(KEEP_LOCK))
+            return true;
+        // An earlier version ignored the whole directory, which would now hide the committed lock too.
+        const rescue = lines.includes(BLANKET) ? `${KEEP_LOCK}\n` : `${IGNORE_LINE}\n`;
+        await appendFile(path, `\n# The key is private; the lock is committed.\n${rescue}`, 'utf8');
         return true;
     }
     catch {

package/dist/server.js

@@ -6,11 +6,15 @@ 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 { TOOL_DESCRIPTIONS, formatChanges, formatError, formatSearch, formatVariable } from './tools.js';
 import { installSkill, skillInstallReport } from './skill.js';
 import { configuredOut, firstPullReport, runFirstPull } from './first-pull.js';
 import { projectConfigReport, writeProjectConfig } from './project-config.js';
 import { checkKey } from './key-check.js';
+import { readLock } from './lock.js';
+// The agent should not have to be told which version to diff from — the lock in the project is the
+// answer, and asking the model to supply it invites a guess.
+const lockedVersion = () => readLock(process.cwd())?.syncedVersionId ?? '';
 // A missing key threw at module load, and an editor shows that as a Node stack trace with the
 // message buried in it. Say it in one line and exit, the way the CLI already does.
 let client;
@@ -42,6 +46,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ['query'],
             },
         },
+        {
+            name: 'flareum_changes_since',
+            description: TOOL_DESCRIPTIONS.changes,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    since: { type: 'string', description: 'The syncedVersionId from .flareum/lock.json. Omit to list everything this project has.' },
+                },
+            },
+        },
         {
             name: 'flareum_get',
             description: TOOL_DESCRIPTIONS.get,
@@ -61,6 +75,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     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_changes_since')
+            return text(formatChanges(await client.changes(String(args.since ?? '')), lockedVersion()));
         if (request.params.name === 'flareum_get')
             return text(formatVariable(await client.variable(String(args.path ?? ''))));
         return text(`Unknown tool: ${request.params.name}`);
@@ -74,24 +90,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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())));
-// 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.
-// The CLI reads its key from the project, the server from its environment — two sources that can
-// disagree, and did: `flareum pull` said "no key" in a project whose server was connected.
 // "Connected" only means this process started, so a revoked key looked healthy while every lookup
-// failed. One authenticated call decides it before anything else runs.
-const key = await checkKey(() => client.published());
+// failed. One request, before anything else, so the editor is told rather than the tools failing.
+const key = await checkKey(() => client.published().then(r => r.publishedVersionId));
 if (!key.usable) {
     console.error(key.message);
     if (key.fatal)
         process.exit(1);
 }
-const configWritten = projectConfigReport(await writeProjectConfig(process.cwd(), process.env, configuredOut(process.cwd(), process.env)));
+// The handshake goes FIRST. Provisioning used to run before it, so a slow pull delayed the reply
+// and a client that gave up killed the process mid-write — 12 of 24 stylesheets, stamped as whole.
+await server.connect(new StdioServerTransport());
+const out = configuredOut(process.cwd(), process.env);
+// Never silently: if the skill does not land, the agent hardcodes values and nothing says why.
+console.error(skillInstallReport(await installSkill(process.cwd())));
+const configWritten = projectConfigReport(await writeProjectConfig(process.cwd(), process.env, out));
 if (configWritten)
     console.error(configWritten);
-const firstPull = firstPullReport(await runFirstPull(client, process.cwd(), process.env, configuredOut(process.cwd(), process.env)));
+// The version the key check already fetched, so a start asks for it once rather than twice — and
+// on a server without /published each ask costs a whole bucket listing.
+const firstPull = firstPullReport(await runFirstPull(client, process.cwd(), process.env, out, key.version));
 if (firstPull)
     console.error(firstPull);
-await server.connect(new StdioServerTransport());

package/dist/tools.d.ts

@@ -1,4 +1,4 @@
-import type { SearchResponse, VariableResponse } from './client.js';
+import type { ChangesResponse, SearchResponse, VariableResponse } from './client.js';
 export declare const NO_MATCH_INSTRUCTION: string;
 /** What `flareum_search` hands back. */
 export declare const formatSearch: (result: SearchResponse) => string;
@@ -12,4 +12,6 @@ export declare const formatError: ({ code, message, hint }: {
 export declare const TOOL_DESCRIPTIONS: {
     readonly search: string;
     readonly get: string;
+    readonly changes: string;
 };
+export declare const formatChanges: ({ since, totalChanges, entries, truncated, liveVersionId }: ChangesResponse, lockedVersion?: string) => string;

package/dist/tools.js

@@ -71,4 +71,51 @@ export const TOOL_DESCRIPTIONS = {
         + '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.',
+    changes: 'List what changed in Flareum since the version this project last synced. Call it when the user '
+        + 'asks to update, sync or migrate tokens, and at the start of a session in a project that has a '
+        + '.flareum/lock.json. A rename reads as a rename with both names, so rewrite the call sites '
+        + 'rather than deleting and adding. A removed token carries what to use instead. Read every '
+        + 'entry before editing anything, and say what you are about to change.',
+};
+// Written for a model that is about to EDIT files: the CSS names first, because those are what it
+// greps for, and the action stated per line so a rename is never applied as a delete plus an add.
+export const formatChanges = ({ since, totalChanges, entries, truncated, liveVersionId }, lockedVersion = '') => {
+    if (!totalChanges)
+        return since
+            ? `No changes since ${since}. The project is at ${liveVersionId}.`
+            : `This project has no tokens yet.`;
+    const lines = [
+        since
+            ? `${totalChanges} change(s) since ${since}. The project is now at ${liveVersionId}.`
+            : `${totalChanges} change(s). No baseline was given, so this is everything the project has.`,
+        '',
+    ];
+    if (lockedVersion && since && lockedVersion !== since)
+        lines.push(`NOTE: .flareum/lock.json says ${lockedVersion}, which is not what was asked for.`, '');
+    for (const entry of entries)
+        lines.push(`  ${changeLine(entry)}`);
+    if (truncated)
+        lines.push('', `Only the first ${entries.length} are listed. Apply these, sync, then ask again.`);
+    lines.push('', 'A rename is a RENAME: rewrite the call sites, never delete and re-add.');
+    return lines.join('\n');
+};
+const nameOf = (side) => side?.cssName ?? side?.path ?? side?.name ?? '?';
+const changeLine = (entry) => {
+    const { kind, change, before, after } = entry;
+    const via = entry.viaFolder ? `  (folder ${entry.viaFolder.from} → ${entry.viaFolder.to})` : '';
+    const mode = entry.mode ? ` [${entry.mode}]` : '';
+    if (change === 'renamed' || change === 'moved')
+        return `${kind} ${change}: ${nameOf(before)} → ${nameOf(after)}${via}`;
+    if (change === 'deleted')
+        return `${kind} removed: ${nameOf(before)}`
+            + (entry.replacement?.value ? `  — use instead: ${entry.replacement.value}` : '');
+    if (change === 'added')
+        return `${kind} added: ${nameOf(after)}`;
+    if (change === 'typeChanged')
+        return `${kind} type: ${nameOf(before)} is now ${after?.type} (was ${before?.type})`;
+    if (change === 'valueChanged')
+        return `${kind} value${mode}: ${nameOf(before)}  ${before?.value} → ${after?.value}`;
+    if (change === 'movedCollection')
+        return `${kind} moved collection: ${nameOf(before)} → ${nameOf(after)}`;
+    return `${kind} ${change}: ${nameOf(after ?? before)}`;
 };

package/package.json

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

package/skill/SKILL.md

@@ -30,6 +30,7 @@ page, and it is worth reading in full before the first line of code.
 |---|---|
 | 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) |
+| Applying what `flareum_changes_since` returned — a sync, an update, a migration | [references/applying.md](references/applying.md) |
 
 ## Before the first token: check the stylesheets are imported
 
@@ -67,6 +68,17 @@ that is imported but still not applying is usually the `font:` shorthand or a mi
 If the pulled folder does not exist at all, the project has never pulled: say so and give the
 command — `npx -p @flareum/mcp flareum pull` — rather than writing tokens that cannot resolve.
 
+## When the project is behind
+
+A project with a `.flareum/lock.json` was synced at a particular version. `flareum_changes_since`
+says what has changed since — a rename reads as a rename, a removed token carries what to use
+instead. Reach for it when the user asks to sync, update or migrate tokens, and at the start of a
+session in a project that has a lock.
+
+**Applying those entries has an order that matters**, and getting it wrong leaves a project that
+reports itself synced while still referencing dead tokens:
+[references/applying.md](references/applying.md).
+
 ## Reading a search result
 
 The header tells you which kind of answer you got, and they mean different things:

package/skill/references/applying.md

@@ -0,0 +1,70 @@
+# Applying what changed
+
+Read this when `flareum_changes_since` returns entries, or the user asks to sync, update or migrate
+tokens.
+
+## The order is the safety
+
+**Rewrite the call sites first. Pull last.**
+
+`flareum pull` brings the new stylesheets AND stamps `.flareum/lock.json`, which is what records the
+project as synced. Pull first and a rewrite that fails halfway leaves the lock advanced over a
+codebase still referencing dead tokens — the next session reports nothing to do, and the breakage is
+invisible. Pull last and a failed rewrite simply leaves the project where it was.
+
+```
+1. flareum_changes_since        read every entry before editing anything
+2. show the developer           what you are about to change, and what you cannot
+3. rewrite the call sites       names only
+4. npx -p @flareum/mcp flareum pull      the new tree, and the lock
+```
+
+Do not update `lock.json` by hand. It is stamped by a successful pull, and stamping it any other way
+is claiming work that did not happen.
+
+## What you may change, and what you may not
+
+| You may | You may not |
+|---|---|
+| Rewrite `var(--old)` → `var(--new)` across the repo | Change a **value**. Only a name. |
+| Substitute a removed token's recorded replacement | Guess a replacement when none is recorded |
+| Replace the pulled `variables/` tree by pulling | Hand-edit anything inside it — it is generated |
+| Report what you could not resolve | Silently skip an entry |
+
+## Entry by entry
+
+**`renamed` / `moved`** — one entry carries both names. Rewrite every occurrence of `before.cssName`
+to `after.cssName`. It is a rename: do not delete the old and add the new, and do not touch the value.
+
+**`viaFolder`** — this rename is part of a whole folder moving. Apply it as one prefix rewrite across
+the members rather than N independent edits, and say so once rather than N times.
+
+**`deleted` with a replacement** — substitute it. The replacement is what the designer recorded as
+the successor, and it may be a token, a formula or a literal.
+
+**`deleted` with NO replacement** — **report it and leave it alone.** You have no basis for choosing
+a successor, and a plausible-looking guess is how a design system quietly acquires wrong semantics.
+Name the token, name the files that use it, and let the developer decide.
+
+**`valueChanged`** — nothing to do in the code. The value lives in the stylesheets the pull replaces;
+a call site referencing the token gets the new value for free. Mention it only if the change is large
+enough that someone should look at the result.
+
+**`typeChanged`** — the token still exists under the same name, but it is a different kind of value
+now (a colour that became a number). The call sites may still compile and be wrong. Report each one;
+do not rewrite them silently.
+
+**`added`** — nothing to apply. Worth mentioning only if it replaces something you are about to
+report as removed.
+
+**`reordered`** — ignore. It affects the order tokens are emitted in, not any call site.
+
+## Before you touch a file
+
+Say what you are about to do, in the developer's terms: how many call sites, in how many files, and
+what you will not be touching. A migration nobody agreed to is a migration nobody can review.
+
+## When it does not go cleanly
+
+Report what failed and **do not pull**. A partial rewrite with the old stylesheets still in place is
+a working project; a partial rewrite with the lock advanced is a broken one that claims to be current.