virtualmatter 0.1.0 → 0.2.0

package/dist/config.js

@@ -1,5 +1,7 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 /** Platform API base. Overridable so dev/staging environments work. */
 export function apiBase() {
     const raw = process.env.VIRTUALMATTER_API_BASE ?? "https://make.virtualmatter.ai";
@@ -18,5 +20,26 @@ export function configDir() {
 export function credentialsPath() {
     return path.join(configDir(), "credentials.json");
 }
+/** Where downloaded native client builds are unpacked: <configDir>/client/<build>. */
+export function clientInstallRoot() {
+    return process.env.VIRTUALMATTER_CLIENT_DIR ?? path.join(configDir(), "client");
+}
 /** Name of the per-directory sync state file. */
 export const STATE_FILE = ".virtualmatter.json";
+/** The package version, read from package.json so it can never drift from npm. */
+export function packageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        for (const candidate of [path.join(here, "..", "package.json"), path.join(here, "..", "..", "package.json")]) {
+            if (fs.existsSync(candidate)) {
+                const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"));
+                if (pkg.name === "virtualmatter" && typeof pkg.version === "string")
+                    return pkg.version;
+            }
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return "0.0.0";
+}

package/dist/ignore.js

@@ -15,7 +15,9 @@ export function isIgnoredPath(relPath) {
         return true;
     if (norm === STATE_FILE)
         return true;
-    if (norm === "AGENTS.md")
+    // Harness files the CLI drops into a pulled folder; they belong to the
+    // maker's machine, not the world.
+    if (norm === "AGENTS.md" || norm === "CLAUDE.md")
         return true;
     if (norm.endsWith(".remote-conflict"))
         return true;

package/dist/index.js

@@ -3,29 +3,59 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { resolveSession, sessionBaseUrl, fetchNativeClients, whoami } from "./api.js";
-import { clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
+import { createProject, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
+import { NotLoggedInError, clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
 import { openInBrowser } from "./browser.js";
+import { detectPlatform, ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
+import { apiBase, packageVersion } from "./config.js";
 import { FilesClient } from "./files.js";
-import { runMcpServer, resolveFramingId } from "./mcp.js";
+import { runMcpServer } from "./mcp.js";
 import { pullCommand } from "./pull.js";
-import { requireState } from "./state.js";
+import { NeedsChoiceError, formatProjectList, makeFramingOf, resolveImplicitTarget, resolveTarget, } from "./resolve.js";
+import { loadState, requireState } from "./state.js";
 import { SyncEngine, runSyncLoop } from "./sync.js";
-import { parseTarget, PROJECT_URL_HELP } from "./urls.js";
 const program = new Command();
 program
     .name("virtualmatter")
-    .description("Build with Virtual Matter from your terminal: sync montage files, run Lua, capture screenshots, and expose it all to coding agents over MCP.")
-    .version("0.1.0");
+    .description("Build with Virtual Matter from your terminal or coding agent: list and create worlds, mirror their files, live-sync edits, run Lua, capture screenshots, open the native client, and expose it all over MCP.")
+    .version(packageVersion());
 function fail(message) {
     console.error(message);
     process.exit(1);
 }
+/** The device-code sign-in, shared by `login` and the automatic first-use sign-in. */
+async function signIn() {
+    const { auth, tokenEndpoint } = await startDeviceFlow();
+    const url = auth.verification_uri_complete ?? auth.verification_uri;
+    console.log(`Sign in with Virtual Matter: open ${url}`);
+    console.log(`and enter the code: ${auth.user_code}`);
+    console.log("(waiting for you to approve it in the browser ...)");
+    openInBrowser(url);
+    const creds = await pollForToken(tokenEndpoint, auth);
+    saveCredentials(creds);
+    const me = await whoami();
+    console.log(`Signed in as ${me.username ?? me.email ?? me.id}.`);
+}
+/**
+ * Run a command. Not signed in yet? Sign in right here and run it again -
+ * a first-time user should never have to learn that `login` exists.
+ * Set VIRTUALMATTER_NO_AUTO_LOGIN=1 to get the old error instead.
+ */
 async function run(fn) {
     try {
         await fn();
     }
     catch (err) {
+        if (err instanceof NotLoggedInError && !process.env.VIRTUALMATTER_NO_AUTO_LOGIN) {
+            try {
+                await signIn();
+                await fn();
+                return;
+            }
+            catch (again) {
+                fail(again instanceof Error ? again.message : String(again));
+            }
+        }
         fail(err instanceof Error ? err.message : String(err));
     }
 }
@@ -35,20 +65,42 @@ async function clientForDir(dir) {
     const session = await resolveSession(state.framing_id);
     return { client: new FilesClient(sessionBaseUrl(session), state.framing_id), framingId: state.framing_id };
 }
+/** A target from the argument, else from the folder, else the only project. */
+async function resolveTargetOrImplicit(target, dir) {
+    if (target)
+        return resolveTarget(target);
+    try {
+        return await resolveImplicitTarget(dir);
+    }
+    catch (err) {
+        if (err instanceof NeedsChoiceError)
+            fail(err.message);
+        throw err;
+    }
+}
+function slugFor(name) {
+    const slug = name
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "world";
+}
+function reportPull(result, dest) {
+    console.log(`Pulled ${result.fileCount} files into ${dest}.`);
+    const files = result.agentFiles;
+    if (files && files.written.length > 0) {
+        console.log(`Wrote ${files.written.join(", ")} so Claude Code, Codex, and Cursor find their way around.`);
+    }
+    const rel = path.relative(process.cwd(), dest) || ".";
+    console.log(`Next: cd ${rel} && npx virtualmatter sync`);
+    console.log(`      (or open the folder in your agent - the MCP server is registered in .mcp.json)`);
+}
 program
     .command("login")
-    .description("Sign in with Virtual Matter using a device code")
-    .action(() => run(async () => {
-    const { auth, tokenEndpoint } = await startDeviceFlow();
-    const url = auth.verification_uri_complete ?? auth.verification_uri;
-    console.log(`Open ${url}`);
-    console.log(`and enter the code: ${auth.user_code}`);
-    openInBrowser(url);
-    const creds = await pollForToken(tokenEndpoint, auth);
-    saveCredentials(creds);
-    const me = await whoami();
-    console.log(`Signed in as ${me.username ?? me.email ?? me.id}.`);
-}));
+    .description("Sign in with Virtual Matter using a device code (other commands do this automatically)")
+    .action(() => run(signIn));
 program
     .command("logout")
     .description("Forget the stored credentials")
@@ -61,25 +113,91 @@ program
     .description("Show who is signed in")
     .action(() => run(async () => {
     if (!loadCredentials())
-        fail("Not signed in. Run `virtualmatter login` first.");
+        throw new NotLoggedInError();
     const me = await whoami();
     console.log(JSON.stringify(me, null, 2));
 }));
+program
+    .command("list")
+    .alias("ls")
+    .alias("projects")
+    .description("List your worlds (projects) with their editing framing ids and URLs")
+    .option("--json", "machine-readable output")
+    .action((opts) => run(async () => {
+    const projects = await listProjects();
+    if (opts.json) {
+        console.log(JSON.stringify(projects.map((p) => ({
+            name: p.name,
+            id: p.id,
+            region: p.region,
+            framing_id: p.make_framing_id,
+            edit_url: p.make_framing_id ? editUrl(p.make_framing_id, p.url_slug) : null,
+            play_url: p.play_framing_id ? playUrl(p.play_framing_id) : null,
+            updated_at: p.updated_at ?? null,
+        })), null, 2));
+        return;
+    }
+    if (projects.length === 0) {
+        console.log('No worlds yet. Create one: npx virtualmatter create "My world"');
+        return;
+    }
+    console.log(formatProjectList(projects));
+    console.log("");
+    console.log("Pull one: npx virtualmatter pull <framing id or URL>");
+}));
+program
+    .command("create")
+    .description("Create a new world and mirror its files into a local folder")
+    .argument("<name>", "the world's name")
+    .argument("[dir]", "destination folder (default: ./<name-as-slug>)")
+    .option("--region <region>", "NA, EU, or AS (default: nearest)")
+    .option("--description <text>", "one-line description")
+    .option("--track <track>", "engine track: stable or master", "stable")
+    .option("--no-pull", "create only; do not download the files")
+    .option("--open", "also open the new world in the native client")
+    .option("--json", "machine-readable output")
+    .action((name, dir, opts) => run(async () => {
+    const region = (opts.region ?? defaultRegion()).toUpperCase();
+    if (!["NA", "EU", "AS"].includes(region))
+        fail("--region must be NA, EU, or AS");
+    if (opts.track !== "stable" && opts.track !== "master")
+        fail("--track must be stable or master");
+    const project = await createProject({
+        name,
+        description: opts.description,
+        region,
+        engine_track: opts.track,
+    });
+    const framingId = makeFramingOf(project);
+    const url = editUrl(framingId, project.url_slug);
+    let pulled = null;
+    let dest = null;
+    if (opts.pull) {
+        dest = path.resolve(dir ?? slugFor(project.name));
+        pulled = await pullCommand(framingId, dest);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ name: project.name, id: project.id, region: project.region, framing_id: framingId, edit_url: url, dir: dest, file_count: pulled?.fileCount ?? null }, null, 2));
+    }
+    else {
+        console.log(`Created "${project.name}" in ${project.region}.`);
+        console.log(`Edit in the browser: ${url}`);
+        if (pulled && dest)
+            reportPull(pulled, dest);
+    }
+    if (opts.open)
+        await openNative(framingId, url);
+}));
 program
     .command("pull")
-    .description("Download a framing's file tree into a local folder")
-    .argument("<target>", "an /edit, /play, or /m URL - or a bare framing id")
-    .argument("[dir]", "destination folder (default: ./<framing-id>)")
+    .description("Download a world's file tree into a local folder")
+    .argument("[target]", "any Virtual Matter link (/edit, /play, /g, /p, /projects) or a framing id; omitted = your only world")
+    .argument("[dir]", "destination folder (default: ./<world name or framing id>)")
     .action((target, dir) => run(async () => {
-    const parsed = parseTarget(target);
-    if (parsed.kind === "project")
-        fail(PROJECT_URL_HELP);
-    if (parsed.kind === "invalid")
-        fail(parsed.reason);
-    const dest = path.resolve(dir ?? parsed.framingId);
-    const result = await pullCommand(parsed.framingId, dest);
-    console.log(`Pulled ${result.fileCount} files into ${dest}.`);
-    console.log(`Next: cd ${path.relative(process.cwd(), dest) || "."} && virtualmatter sync`);
+    const resolved = await resolveTargetOrImplicit(target, path.resolve("."));
+    const dest = path.resolve(dir ?? (resolved.project ? slugFor(resolved.project.name) : resolved.framingId));
+    const result = await pullCommand(resolved.framingId, dest);
+    reportPull(result, dest);
 }));
 program
     .command("sync")
@@ -127,32 +245,53 @@ program
     fs.writeFileSync(opts.out, png);
     console.log(`Wrote ${opts.out} (${png.length} bytes).`);
 }));
+/** Install the native client if needed, sign it in, and launch it into a world. */
+async function openNative(framingId, url, force = false) {
+    const installed = await ensureClientInstalled({ framingId, force });
+    const seeded = seedNativeAuth(installed);
+    if (seeded.length > 0)
+        console.log("Signed the native client in with your account.");
+    launchClient(installed, url);
+    console.log(`Opening ${url} in the Virtual Matter client (${installed.dir}).`);
+}
 program
-    .command("client")
-    .description("Print the native client download URL for this OS")
-    .action(() => run(async () => {
-    const clients = await fetchNativeClients();
-    const platform = process.platform === "darwin" ? "macos" : process.platform === "win32" ? "windows" : "linux";
-    const matches = clients.filter((c) => c.platform.toLowerCase().includes(platform));
-    if (matches.length === 0) {
-        console.log(`No native client published for ${platform} yet. All available:`);
-        for (const c of clients)
-            console.log(`  ${c.platform}${c.kind ? ` (${c.kind})` : ""}: ${c.url}`);
+    .command("open")
+    .alias("client")
+    .description("Open a world in the native desktop client - downloads and signs it in on first use")
+    .argument("[target]", "any Virtual Matter link or framing id; omitted = this folder's world, or your only one")
+    .option("--install-only", "download and unpack the client without launching it")
+    .option("--print", "only print the download URL for this OS")
+    .option("--force", "re-download the client even if this build is already unpacked")
+    .action((target, opts) => run(async () => {
+    if (opts.print) {
+        const catalog = await fetchNativeClientCatalog(loadState(path.resolve("."))?.framing_id);
+        const platform = detectPlatform();
+        const mine = catalog.clients.filter((c) => c.platform.toLowerCase() === platform);
+        const rows = mine.length > 0 ? mine : catalog.clients;
+        if (mine.length === 0)
+            console.log(`No native client published for ${platform} yet. All available:`);
+        for (const c of rows) {
+            const u = c.url.startsWith("http") ? c.url : `${apiBase()}${c.url}`;
+            console.log(`${c.platform} (${c.kind}): ${u}`);
+        }
         return;
     }
-    for (const c of matches)
-        console.log(`${c.platform}${c.kind ? ` (${c.kind})` : ""}: ${c.url}`);
+    if (opts.installOnly) {
+        const installed = await ensureClientInstalled({ force: opts.force });
+        const seeded = seedNativeAuth(installed);
+        console.log(`Installed the Virtual Matter client at ${installed.dir}${seeded.length ? " and signed it in." : "."}`);
+        return;
+    }
+    const resolved = await resolveTargetOrImplicit(target, path.resolve("."));
+    await openNative(resolved.framingId, editUrl(resolved.framingId, resolved.project?.url_slug), opts.force);
 }));
 program
     .command("mcp")
-    .description("Run the stdio MCP server for coding agents")
-    .argument("[dir]", "a synced folder whose state file names the framing", ".")
+    .description("Run the stdio MCP server for coding agents (works with or without a selected world)")
+    .argument("[dir]", "a synced folder whose state file names the world", ".")
     .option("--framing <id>", "framing id (overrides the state file)")
     .action((dir, opts) => run(async () => {
-    const abs = path.resolve(dir);
-    // Validate early so misconfiguration fails loudly at registration time.
-    resolveFramingId(abs, opts.framing);
-    await runMcpServer(abs, opts.framing);
+    await runMcpServer(path.resolve(dir), opts.framing);
 }));
 program.parseAsync(process.argv).catch((err) => {
     fail(err instanceof Error ? err.message : String(err));

package/dist/mcp.js

@@ -1,44 +1,77 @@
 /**
  * `virtualmatter mcp` - a stdio MCP server that gives a coding agent direct
- * hands on a live Virtual Matter session: montage files, Lua execution,
- * engine errors, and screenshots.
+ * hands on Virtual Matter: the account's projects, creating one, a live
+ * session's files, Lua execution, engine errors, screenshots, and the
+ * native client.
+ *
+ * The server starts without a world selected when the folder has no
+ * state file and no --framing was given; `list_projects`, `create_project`
+ * and `select_project` work in that state, and every world-bound tool says
+ * how to pick one.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { resolveSession, sessionBaseUrl } from "./api.js";
-import { apiBase } from "./config.js";
+import { createProject, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
+import { ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
+import { packageVersion } from "./config.js";
 import { ConflictError, FilesClient } from "./files.js";
+import { pullCommand } from "./pull.js";
+import { makeFramingOf, resolveTarget } from "./resolve.js";
 import { loadState } from "./state.js";
 export function resolveFramingId(dir, framingFlag) {
     if (framingFlag)
         return framingFlag;
     const state = loadState(dir);
-    if (state)
-        return state.framing_id;
-    throw new Error(`No .virtualmatter.json in ${dir} and no --framing flag. Run \`virtualmatter pull\` there first, or pass --framing <id>.`);
+    return state ? state.framing_id : null;
 }
+const NO_WORLD = "No world is selected. Call select_project with a Virtual Matter URL or id, create_project to make a new one, or list_projects to see what exists.";
 function makeContext(framingId) {
     let session = null;
     let client = null;
-    const getSession = async () => {
-        if (!session)
-            session = await resolveSession(framingId);
-        return session;
-    };
-    return {
+    const ctx = {
         framingId,
-        getSession,
+        project: null,
+        select(id, project) {
+            if (id !== ctx.framingId) {
+                session = null;
+                client = null;
+            }
+            ctx.framingId = id;
+            ctx.project = project ?? null;
+        },
+        requireFraming() {
+            if (!ctx.framingId)
+                throw new Error(NO_WORLD);
+            return ctx.framingId;
+        },
+        async getSession() {
+            if (!session)
+                session = await resolveSession(ctx.requireFraming());
+            return session;
+        },
         async getClient() {
             if (!client)
-                client = new FilesClient(sessionBaseUrl(await getSession()), framingId);
+                client = new FilesClient(sessionBaseUrl(await ctx.getSession()), ctx.requireFraming());
             return client;
         },
     };
+    return ctx;
 }
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
+function projectSummary(p) {
+    return {
+        name: p.name,
+        id: p.id,
+        region: p.region,
+        framing_id: p.make_framing_id,
+        edit_url: p.make_framing_id ? editUrl(p.make_framing_id, p.url_slug) : null,
+        play_url: p.play_framing_id ? playUrl(p.play_framing_id) : null,
+        updated_at: p.updated_at ?? null,
+    };
+}
 /**
  * write_file etag handling: look up the current etag from a listing, PUT with
  * If-Match (or If-None-Match: * for a new file), and on 412 retry ONCE with a
@@ -62,9 +95,55 @@ export async function writeWithRetry(client, filePath, body) {
     }
 }
 export async function runMcpServer(dir, framingFlag) {
-    const framingId = resolveFramingId(dir, framingFlag);
-    const ctx = makeContext(framingId);
-    const server = new McpServer({ name: "virtualmatter", version: "0.1.0" });
+    const ctx = makeContext(resolveFramingId(dir, framingFlag));
+    const server = new McpServer({ name: "virtualmatter", version: packageVersion() });
+    server.registerTool("list_projects", {
+        description: "List the signed-in maker's Virtual Matter projects (worlds): name, id, region, the editing framing id, and edit/play URLs. Call this to find a world to work in, then select_project.",
+        inputSchema: {},
+    }, async () => textResult(JSON.stringify((await listProjects()).map(projectSummary), null, 2)));
+    server.registerTool("create_project", {
+        description: "Create a new Virtual Matter world (project) for the signed-in maker and select it for this session. The world spins up live on Virtual Matter servers; its content is SDK Lua plus assets that hot-reload as you write them. Region defaults to the one nearest this machine.",
+        inputSchema: {
+            name: z.string().min(1).max(100).describe("Project name, e.g. \"Lava Arena\""),
+            description: z.string().max(1000).optional().describe("One-line description (optional)"),
+            region: z.enum(["NA", "EU", "AS"]).optional().describe("Hosting region (default: nearest)"),
+            pull_to: z
+                .string()
+                .optional()
+                .describe("Local folder to mirror the new world's files into (optional; sync works from there)"),
+        },
+    }, async ({ name, description, region, pull_to }) => {
+        const project = await createProject({ name, description, region: region ?? defaultRegion() });
+        const framingId = makeFramingOf(project);
+        ctx.select(framingId, project);
+        let pulled = null;
+        if (pull_to) {
+            const result = await pullCommand(framingId, pull_to);
+            pulled = { dir: result.dir, file_count: result.fileCount, agent_files: result.agentFiles };
+        }
+        return textResult(JSON.stringify({ ...projectSummary(project), selected: true, pulled }, null, 2));
+    });
+    server.registerTool("select_project", {
+        description: "Select the world this session works on. Accepts any Virtual Matter link (/edit, /play, /g, /p, /projects, with or without a readable slug) or a bare framing id. Optionally mirrors its files into a local folder.",
+        inputSchema: {
+            target: z.string().describe("A Virtual Matter URL or framing id"),
+            pull_to: z.string().optional().describe("Local folder to mirror the world's files into (optional)"),
+        },
+    }, async ({ target, pull_to }) => {
+        const resolved = await resolveTarget(target);
+        ctx.select(resolved.framingId, resolved.project);
+        let pulled = null;
+        if (pull_to) {
+            const result = await pullCommand(resolved.framingId, pull_to);
+            pulled = { dir: result.dir, file_count: result.fileCount, agent_files: result.agentFiles };
+        }
+        return textResult(JSON.stringify({
+            framing_id: resolved.framingId,
+            edit_url: editUrl(resolved.framingId, resolved.project?.url_slug),
+            project: resolved.project ? projectSummary(resolved.project) : null,
+            pulled,
+        }, null, 2));
+    });
     server.registerTool("list_files", {
         description: "List every file in the live Virtual Matter session's Montage tree. Returns path, size, mtime_ms, and etag per file. Call this before reading or writing to learn what exists. Lua scripts under this tree hot-reload in the engine when written.",
         inputSchema: {},
@@ -124,15 +203,28 @@ export async function runMcpServer(dir, framingFlag) {
             ],
         };
     });
+    server.registerTool("open_native_client", {
+        description: "Open the selected world on this machine in the Virtual Matter native desktop client (higher performance than the browser). Downloads and unpacks the client on first use, signs it in with the CLI's account, and launches it into the world. Returns where the client lives and the URL it opened.",
+        inputSchema: {},
+    }, async () => {
+        const framingId = ctx.requireFraming();
+        const installed = await ensureClientInstalled({ framingId, log: () => undefined });
+        const signedIn = seedNativeAuth(installed);
+        const url = editUrl(framingId);
+        launchClient(installed, url);
+        return textResult(JSON.stringify({ launched: true, url, client_dir: installed.dir, signed_in_via_cli: signedIn.length > 0 }, null, 2));
+    });
     server.registerTool("world_info", {
-        description: "Return the framing id plus the URLs for this session: the editor and play links a human can open, and the session API base this server talks to.",
+        description: "Return the selected world's framing id plus its URLs: the editor and play links a human can open, and the session API base this server talks to.",
         inputSchema: {},
     }, async () => {
+        const framingId = ctx.requireFraming();
         const session = await ctx.getSession();
         return textResult(JSON.stringify({
-            framing_id: ctx.framingId,
-            edit_url: `${apiBase()}/edit/${ctx.framingId}`,
-            play_url: `${apiBase()}/play/${ctx.framingId}`,
+            framing_id: framingId,
+            project: ctx.project ? projectSummary(ctx.project) : null,
+            edit_url: editUrl(framingId, ctx.project?.url_slug),
+            play_url: playUrl(framingId),
             session_api_base: sessionBaseUrl(session),
             voxel_host: session.voxel_host,
             session_id: session.session_id,

package/dist/pull.js

@@ -2,53 +2,61 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveSession, sessionBaseUrl } from "./api.js";
-import { apiBase } from "./config.js";
+import { fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
 import { saveState } from "./state.js";
-const AGENTS_MD_STUB = `# Working with Virtual Matter
-
-This folder is a live mirror of a Virtual Matter framing's Montage files.
-
-- \`virtualmatter sync\` keeps it in sync with the running session.
-- \`virtualmatter run-lua --code "..."\` executes Lua in the engine.
-- \`virtualmatter errors\` shows recent engine errors.
-- \`virtualmatter screenshot -o shot.png\` captures the current view.
-- Lua scripts under this tree hot-reload in the engine when saved.
-
-Do not edit \`.virtualmatter.json\` - it is sync bookkeeping.
-`;
-export async function fetchAgentsMd(fetchFn = fetch) {
-    try {
-        const res = await fetchFn(`${apiBase()}/AGENTS.md`);
-        if (res.ok) {
-            const text = await res.text();
-            if (text.trim().length > 0 && !text.trimStart().startsWith("<"))
-                return text;
-        }
-    }
-    catch {
-        /* fall through to the stub */
-    }
-    return AGENTS_MD_STUB;
+export { AGENTS_MD_STUB, fetchAgentsMd } from "./agentfiles.js";
+/** Download workers per pull. The tree is ~1000 small files; sequential
+ *  GETs left the command silent for minutes. Eight in flight keeps a
+ *  single origin comfortable while cutting wall clock roughly 6-8x. */
+const PULL_CONCURRENCY = 8;
+/** One mutable status line on a TTY (`\r`-overwritten); on a plain
+ *  pipe, a heartbeat line every 100 files instead of 1000 spam lines. */
+function makeProgress(total) {
+    const tty = process.stderr.isTTY === true;
+    let count = 0;
+    return {
+        tick(current) {
+            count++;
+            if (tty) {
+                const label = current.length > 60 ? `...${current.slice(-57)}` : current;
+                process.stderr.write(`\r\x1b[2K[${count}/${total}] ${label}`);
+            }
+            else if (count % 100 === 0 || count === total) {
+                process.stderr.write(`[${count}/${total}] files pulled\n`);
+            }
+        },
+        done() {
+            if (tty)
+                process.stderr.write("\r\x1b[2K");
+        },
+    };
 }
 export async function pullTree(client, dir, framingId) {
     fs.mkdirSync(dir, { recursive: true });
-    const remote = await client.list();
+    const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
     const state = { framing_id: framingId, etags: {} };
-    let count = 0;
-    for (const file of remote) {
-        if (isIgnoredPath(file.path))
-            continue;
-        const { bytes, etag } = await client.get(file.path);
-        const absPath = path.join(dir, file.path);
-        fs.mkdirSync(path.dirname(absPath), { recursive: true });
-        fs.writeFileSync(absPath, bytes);
-        state.etags[file.path] = etag ?? file.etag;
-        count++;
-    }
+    const progress = makeProgress(remote.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= remote.length)
+                return;
+            const file = remote[index];
+            const { bytes, etag } = await client.get(file.path);
+            const absPath = path.join(dir, file.path);
+            fs.mkdirSync(path.dirname(absPath), { recursive: true });
+            fs.writeFileSync(absPath, bytes);
+            state.etags[file.path] = etag ?? file.etag;
+            progress.tick(file.path);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(PULL_CONCURRENCY, remote.length) }, () => worker()));
+    progress.done();
     saveState(dir, state);
-    return { dir, framingId, fileCount: count };
+    return { dir, framingId, fileCount: remote.length };
 }
 export async function pullCommand(framingId, dir) {
     console.log(`Resolving session for framing ${framingId} (this can cold-start one) ...`);
@@ -56,7 +64,6 @@ export async function pullCommand(framingId, dir) {
     const client = new FilesClient(sessionBaseUrl(session), framingId);
     console.log(`Session ready at ${sessionBaseUrl(session)}. Downloading files ...`);
     const result = await pullTree(client, dir, framingId);
-    const agentsMd = await fetchAgentsMd();
-    fs.writeFileSync(path.join(dir, "AGENTS.md"), agentsMd);
+    result.agentFiles = writeAgentFiles(dir, await fetchAgentsMd());
     return result;
 }