@gethmy/mcp 2.5.6 → 2.6.0

package/dist/cli.js

@@ -1479,6 +1479,51 @@ class HarmonyApiClient {
   async updateMemoryEntity(entityId, updates) {
     return this.request("PUT", `/memory/entities/${entityId}`, updates);
   }
+  async harmonyRecall(options) {
+    const fetchLimit = Math.max(options.topK ?? 3, 50);
+    let entities = [];
+    if (options.query) {
+      const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
+        project_id: options.projectId,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        limit: fetchLimit
+      });
+      entities = search.entities ?? [];
+    } else {
+      const list = await this.listMemoryEntities({
+        workspace_id: options.workspaceId,
+        project_id: options.projectId,
+        scope: options.scope,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        tags: options.tags,
+        min_confidence: options.minConfidence,
+        limit: fetchLimit
+      });
+      entities = list.entities ?? [];
+    }
+    if (options.type && options.type.length > 1) {
+      const allowed = new Set(options.type);
+      entities = entities.filter((e) => allowed.has(e.type));
+    }
+    if (options.memory_tier) {
+      entities = entities.filter((e) => e.memory_tier === options.memory_tier);
+    }
+    if (options.scope) {
+      entities = entities.filter((e) => e.scope === options.scope);
+    }
+    if (options.tags?.length) {
+      const wanted = new Set(options.tags);
+      entities = entities.filter((e) => (e.tags ?? []).some((t) => wanted.has(t)));
+    }
+    if (typeof options.minConfidence === "number") {
+      const threshold = options.minConfidence;
+      entities = entities.filter((e) => typeof e.confidence === "number" && e.confidence >= threshold);
+    }
+    if (options.topK !== undefined) {
+      entities = entities.slice(0, options.topK);
+    }
+    return { entities };
+  }
   async deleteMemoryEntity(entityId) {
     return this.request("DELETE", `/memory/entities/${entityId}`);
   }
@@ -1785,11 +1830,8 @@ function resolveAgentIdentity(info) {
 var AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
   "harmony_update_card",
-  "harmony_move_card",
   "harmony_create_subtask",
-  "harmony_toggle_subtask",
-  "harmony_add_label_to_card",
-  "harmony_remove_label_from_card"
+  "harmony_toggle_subtask"
 ]);
 var INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var CHECK_INTERVAL_MS = 60 * 1000;
@@ -4957,6 +4999,7 @@ async function refreshSkills() {
 }
 
 // src/tui/setup.ts
+import { createHash as createHash3 } from "node:crypto";
 import {
   existsSync as existsSync7,
   lstatSync,
@@ -5729,7 +5772,13 @@ async function runDocsStep(cwd) {
 }
 
 // src/tui/writer.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "node:fs";
+import {
+  chmodSync,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync4
+} from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { dirname as dirname2 } from "node:path";
 import * as p2 from "@clack/prompts";
@@ -5745,8 +5794,12 @@ function writeFile(filePath, content, options = {}) {
   }
   try {
     ensureDir(dirname2(filePath));
-    const mode = filePath.includes(".harmony-mcp") ? 384 : 420;
+    const defaultMode = filePath.includes(".harmony-mcp") ? 384 : 420;
+    const mode = options.mode ?? defaultMode;
     writeFileSync4(filePath, content, { mode });
+    if (options.mode !== undefined) {
+      chmodSync(filePath, options.mode);
+    }
     return { path: filePath, action: exists ? "update" : "create" };
   } catch (error) {
     return {
@@ -5857,7 +5910,10 @@ async function writeFilesWithProgress(files, options = {}) {
     } else if (file.type === "toml" && file.tomlSection) {
       result = appendToToml(file.path, file.tomlSection, file.content, options);
     } else {
-      result = writeFile(file.path, file.content, options);
+      result = writeFile(file.path, file.content, {
+        ...options,
+        mode: file.mode
+      });
     }
     results.push(result);
     await new Promise((resolve2) => setTimeout(resolve2, 50));
@@ -5993,6 +6049,22 @@ async function fetchProjects(apiKey, workspaceId) {
   const data = await response.json();
   return data.projects || [];
 }
+async function resolveProjectSlug(apiKey, slug) {
+  const response = await fetch(`${API_URL}/v1/projects/resolve/${encodeURIComponent(slug)}`, {
+    method: "GET",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": apiKey
+    }
+  });
+  if (response.status === 404)
+    return null;
+  if (!response.ok) {
+    throw new Error(`Failed to resolve project slug: ${response.status}`);
+  }
+  const data = await response.json();
+  return { workspaceId: data.workspaceId, projectId: data.projectId };
+}
 async function getAgentFiles(agentId, cwd, installMode = "global") {
   const home = homedir4();
   const files = [];
@@ -6035,6 +6107,24 @@ async function getAgentFiles(agentId, cwd, installMode = "global") {
         throw new Error(`Failed to fetch ${skillFailures.length}/${installableNames.length} skill(s) from /v1/skills:
 ${summary}`);
       }
+      try {
+        const updateCheckFetched = await client3.fetchSkill("hmy-update-check");
+        const actualHash = createHash3("sha256").update(updateCheckFetched.content).digest("hex");
+        if (actualHash !== updateCheckFetched.sha256) {
+          throw new Error(`hmy-update-check integrity check failed: expected ${updateCheckFetched.sha256}, got ${actualHash}`);
+        }
+        files.push({
+          path: join5(home, ".hmy", "bin", "hmy-update-check"),
+          content: updateCheckFetched.content,
+          type: "text",
+          mode: 493
+        });
+        files.push({
+          path: join5(home, ".hmy", "VERSION"),
+          content: versionInfo.version,
+          type: "text"
+        });
+      } catch {}
       break;
     }
     case "codex": {
@@ -6227,7 +6317,7 @@ async function runSetup(options = {}) {
   let needsApiKey = !alreadyConfigured;
   let needsSkills = !skillsStatus.installed || options.force;
   let needsContext = !hasContext && !options.skipContext;
-  if (options.workspaceId || options.projectId) {
+  if (options.workspaceId || options.projectId || options.projectSlug) {
     needsContext = true;
   }
   let apiKey = options.apiKey || existingConfig.apiKey;
@@ -6449,6 +6539,21 @@ async function runSetup(options = {}) {
   let selectedProjectId = selectedProjectIdFromSignup || options.projectId;
   let selectedWorkspaceName = selectedWorkspaceNameFromSignup;
   let selectedProjectName = selectedProjectNameFromSignup;
+  if (options.projectSlug && apiKey && (!selectedWorkspaceId || !selectedProjectId)) {
+    spinner3.start(`Resolving project slug "${options.projectSlug}"...`);
+    try {
+      const resolved = await resolveProjectSlug(apiKey, options.projectSlug);
+      if (resolved) {
+        selectedWorkspaceId = selectedWorkspaceId || resolved.workspaceId;
+        selectedProjectId = selectedProjectId || resolved.projectId;
+        spinner3.stop(colors.success(`Resolved "${options.projectSlug}"`));
+      } else {
+        spinner3.stop(colors.warning(`No project found for slug "${options.projectSlug}"`));
+      }
+    } catch (error) {
+      spinner3.stop(colors.warning(`Could not resolve slug: ${error instanceof Error ? error.message : "unknown error"}`));
+    }
+  }
   if (createdNewAccount) {
     needsContext = false;
   }
@@ -6775,13 +6880,14 @@ program.command("reset").description("Remove stored configuration").action(() =>
   console.log(`
 To reconfigure, run: npx @gethmy/mcp setup`);
 });
-program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "API key (skips prompt)").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context").option("-p, --project <id>", "Set project context").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").action(async (options) => {
+program.command("setup").description("Smart setup wizard for Harmony MCP (recommended)").argument("[slug]", "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)").option("-f, --force", "Overwrite existing configuration files").option("-k, --api-key <key>", "API key (skips prompt)").option("-e, --email <email>", "Your email for auto-assignment").option("-a, --agents <agents...>", "Agents to configure: claude, codex, cursor, windsurf").option("-l, --local", "Install skills locally in project directory").option("-g, --global", "Install skills globally (recommended)").option("-w, --workspace <id>", "Set workspace context (UUID)").option("-p, --project <id>", "Set project context (UUID)").option("--skip-context", "Skip workspace/project selection").option("--skip-docs", "Skip project docs scaffold/verification").option("--new", "Create a new account (skip the choice prompt)").option("-n, --name <name>", "Full name (for account creation)").action(async (slug, options) => {
   await runSetup({
     force: options.force,
     apiKey: options.apiKey,
     userEmail: options.email,
     agents: options.agents,
     installMode: options.global ? "global" : options.local ? "local" : undefined,
+    projectSlug: slug,
     workspaceId: options.workspace,
     projectId: options.project,
     skipContext: options.skipContext,

package/dist/index.js

@@ -1475,6 +1475,51 @@ class HarmonyApiClient {
   async updateMemoryEntity(entityId, updates) {
     return this.request("PUT", `/memory/entities/${entityId}`, updates);
   }
+  async harmonyRecall(options) {
+    const fetchLimit = Math.max(options.topK ?? 3, 50);
+    let entities = [];
+    if (options.query) {
+      const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
+        project_id: options.projectId,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        limit: fetchLimit
+      });
+      entities = search.entities ?? [];
+    } else {
+      const list = await this.listMemoryEntities({
+        workspace_id: options.workspaceId,
+        project_id: options.projectId,
+        scope: options.scope,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        tags: options.tags,
+        min_confidence: options.minConfidence,
+        limit: fetchLimit
+      });
+      entities = list.entities ?? [];
+    }
+    if (options.type && options.type.length > 1) {
+      const allowed = new Set(options.type);
+      entities = entities.filter((e) => allowed.has(e.type));
+    }
+    if (options.memory_tier) {
+      entities = entities.filter((e) => e.memory_tier === options.memory_tier);
+    }
+    if (options.scope) {
+      entities = entities.filter((e) => e.scope === options.scope);
+    }
+    if (options.tags?.length) {
+      const wanted = new Set(options.tags);
+      entities = entities.filter((e) => (e.tags ?? []).some((t) => wanted.has(t)));
+    }
+    if (typeof options.minConfidence === "number") {
+      const threshold = options.minConfidence;
+      entities = entities.filter((e) => typeof e.confidence === "number" && e.confidence >= threshold);
+    }
+    if (options.topK !== undefined) {
+      entities = entities.slice(0, options.topK);
+    }
+    return { entities };
+  }
   async deleteMemoryEntity(entityId) {
     return this.request("DELETE", `/memory/entities/${entityId}`);
   }
@@ -1781,11 +1826,8 @@ function resolveAgentIdentity(info) {
 var AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
   "harmony_update_card",
-  "harmony_move_card",
   "harmony_create_subtask",
-  "harmony_toggle_subtask",
-  "harmony_add_label_to_card",
-  "harmony_remove_label_from_card"
+  "harmony_toggle_subtask"
 ]);
 var INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000;
 var CHECK_INTERVAL_MS = 60 * 1000;

package/dist/lib/api-client.js

@@ -1082,6 +1082,51 @@ class HarmonyApiClient {
   async updateMemoryEntity(entityId, updates) {
     return this.request("PUT", `/memory/entities/${entityId}`, updates);
   }
+  async harmonyRecall(options) {
+    const fetchLimit = Math.max(options.topK ?? 3, 50);
+    let entities = [];
+    if (options.query) {
+      const search = await this.searchMemoryEntities(options.workspaceId, options.query, {
+        project_id: options.projectId,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        limit: fetchLimit
+      });
+      entities = search.entities ?? [];
+    } else {
+      const list = await this.listMemoryEntities({
+        workspace_id: options.workspaceId,
+        project_id: options.projectId,
+        scope: options.scope,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        tags: options.tags,
+        min_confidence: options.minConfidence,
+        limit: fetchLimit
+      });
+      entities = list.entities ?? [];
+    }
+    if (options.type && options.type.length > 1) {
+      const allowed = new Set(options.type);
+      entities = entities.filter((e) => allowed.has(e.type));
+    }
+    if (options.memory_tier) {
+      entities = entities.filter((e) => e.memory_tier === options.memory_tier);
+    }
+    if (options.scope) {
+      entities = entities.filter((e) => e.scope === options.scope);
+    }
+    if (options.tags?.length) {
+      const wanted = new Set(options.tags);
+      entities = entities.filter((e) => (e.tags ?? []).some((t) => wanted.has(t)));
+    }
+    if (typeof options.minConfidence === "number") {
+      const threshold = options.minConfidence;
+      entities = entities.filter((e) => typeof e.confidence === "number" && e.confidence >= threshold);
+    }
+    if (options.topK !== undefined) {
+      entities = entities.slice(0, options.topK);
+    }
+    return { entities };
+  }
   async deleteMemoryEntity(entityId) {
     return this.request("DELETE", `/memory/entities/${entityId}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.5.6",
+  "version": "2.6.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -743,15 +743,101 @@ export class HarmonyApiClient {
       scope?: string;
       type?: string;
       memory_tier?: string;
-      // AGP lifecycle fields. Backend may not yet whitelist these — extra keys
-      // are dropped server-side, leaving the call as a no-op for those fields.
+      // Supersede semantics — used by Phase 1.5 review-reject back-fill to
+      // tombstone the original implement episode without hard-deleting it.
+      // The backend sets superseded_at automatically when superseded_by lands.
       superseded_by?: string | null;
+      superseded_at?: string | null;
       version?: number;
     },
   ): Promise<{ entity: unknown; warnings?: string[] }> {
     return this.request("PUT", `/memory/entities/${entityId}`, updates);
   }
 
+  /**
+   * Retrieve memories filtered by type/tier/scope, optionally ranked by a
+   * free-text query. Wraps `searchMemoryEntities` (when a query is given)
+   * or `listMemoryEntities` and applies client-side filters that the REST
+   * surface doesn't natively expose (multi-type, memory_tier).
+   *
+   * Used by the agent daemon's read hook to surface similar past episodes
+   * before building a new task prompt (Phase 1.5).
+   */
+  async harmonyRecall(options: {
+    workspaceId: string;
+    projectId?: string;
+    query?: string;
+    type?: string[];
+    memory_tier?: string;
+    scope?: string;
+    tags?: string[];
+    minConfidence?: number;
+    topK?: number;
+  }): Promise<{ entities: unknown[] }> {
+    // Over-fetch beyond topK so client-side filters (multi-type, memory_tier,
+    // tags) have headroom — matches the MCP server's recall path (server.ts).
+    const fetchLimit = Math.max(options.topK ?? 3, 50);
+    let entities: Array<Record<string, unknown>> = [];
+
+    if (options.query) {
+      // searchMemoryEntities accepts a single type — refine client-side
+      // when the caller passed multiple.
+      const search = await this.searchMemoryEntities(
+        options.workspaceId,
+        options.query,
+        {
+          project_id: options.projectId,
+          type: options.type?.length === 1 ? options.type[0] : undefined,
+          limit: fetchLimit,
+        },
+      );
+      entities = (search.entities ?? []) as Array<Record<string, unknown>>;
+    } else {
+      const list = await this.listMemoryEntities({
+        workspace_id: options.workspaceId,
+        project_id: options.projectId,
+        scope: options.scope,
+        type: options.type?.length === 1 ? options.type[0] : undefined,
+        tags: options.tags,
+        min_confidence: options.minConfidence,
+        limit: fetchLimit,
+      });
+      entities = (list.entities ?? []) as Array<Record<string, unknown>>;
+    }
+
+    // Client-side filters: REST surface lacks multi-type and memory_tier.
+    if (options.type && options.type.length > 1) {
+      const allowed = new Set(options.type);
+      entities = entities.filter((e) => allowed.has(e.type as string));
+    }
+    if (options.memory_tier) {
+      entities = entities.filter((e) => e.memory_tier === options.memory_tier);
+    }
+    if (options.scope) {
+      entities = entities.filter((e) => e.scope === options.scope);
+    }
+    if (options.tags?.length) {
+      const wanted = new Set(options.tags);
+      entities = entities.filter((e) =>
+        ((e.tags as string[]) ?? []).some((t) => wanted.has(t)),
+      );
+    }
+    if (typeof options.minConfidence === "number") {
+      const threshold = options.minConfidence;
+      entities = entities.filter(
+        (e) =>
+          typeof e.confidence === "number" &&
+          (e.confidence as number) >= threshold,
+      );
+    }
+
+    if (options.topK !== undefined) {
+      entities = entities.slice(0, options.topK);
+    }
+
+    return { entities };
+  }
+
   async deleteMemoryEntity(entityId: string): Promise<{ success: boolean }> {
     return this.request("DELETE", `/memory/entities/${entityId}`);
   }

package/src/auto-session.ts

@@ -65,15 +65,19 @@ export function resolveAgentIdentity(info: ClientInfo | null): {
   return { agentIdentifier: key, agentName: displayName };
 }
 
-/** Tools that trigger auto-start of a session */
+/**
+ * Tools that trigger auto-start of a session.
+ *
+ * Restricted to tools that signal real work on a card. Board-management ops
+ * (move, label add/remove) are excluded — they're routinely used for triage
+ * and would create false-positive sessions whose side effect (the auto-added
+ * `agent` label on the card) confuses both UI and humans.
+ */
 export const AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
   "harmony_update_card",
-  "harmony_move_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
-  "harmony_add_label_to_card",
-  "harmony_remove_label_from_card",
 ]);
 
 export const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes

package/src/cli.ts

@@ -139,6 +139,10 @@ program
 program
   .command("setup")
   .description("Smart setup wizard for Harmony MCP (recommended)")
+  .argument(
+    "[slug]",
+    "Project slug — resolves to workspace + project in one step (e.g. harmony-6590761b)",
+  )
   .option("-f, --force", "Overwrite existing configuration files")
   .option("-k, --api-key <key>", "API key (skips prompt)")
   .option("-e, --email <email>", "Your email for auto-assignment")
@@ -148,13 +152,13 @@ program
   )
   .option("-l, --local", "Install skills locally in project directory")
   .option("-g, --global", "Install skills globally (recommended)")
-  .option("-w, --workspace <id>", "Set workspace context")
-  .option("-p, --project <id>", "Set project context")
+  .option("-w, --workspace <id>", "Set workspace context (UUID)")
+  .option("-p, --project <id>", "Set project context (UUID)")
   .option("--skip-context", "Skip workspace/project selection")
   .option("--skip-docs", "Skip project docs scaffold/verification")
   .option("--new", "Create a new account (skip the choice prompt)")
   .option("-n, --name <name>", "Full name (for account creation)")
-  .action(async (options) => {
+  .action(async (slug, options) => {
     await runSetup({
       force: options.force,
       apiKey: options.apiKey,
@@ -165,6 +169,7 @@ program
         : options.local
           ? "local"
           : undefined,
+      projectSlug: slug,
       workspaceId: options.workspace,
       projectId: options.project,
       skipContext: options.skipContext,

package/src/tui/setup.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import {
   existsSync,
   lstatSync,
@@ -38,6 +39,7 @@ export interface SetupOptions {
   installMode?: InstallMode;
   workspaceId?: string;
   projectId?: string;
+  projectSlug?: string;
   skipContext?: boolean;
   skipDocs?: boolean;
   newAccount?: boolean;
@@ -211,11 +213,40 @@ async function fetchProjects(
   return data.projects || [];
 }
 
+/**
+ * Resolve a project slug to {workspaceId, projectId}. Used by
+ * `npx @gethmy/mcp setup <slug>` so users don't have to copy raw UUIDs.
+ */
+async function resolveProjectSlug(
+  apiKey: string,
+  slug: string,
+): Promise<{ workspaceId: string; projectId: string } | null> {
+  const response = await fetch(
+    `${API_URL}/v1/projects/resolve/${encodeURIComponent(slug)}`,
+    {
+      method: "GET",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": apiKey,
+      },
+    },
+  );
+
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(`Failed to resolve project slug: ${response.status}`);
+  }
+
+  const data = await response.json();
+  return { workspaceId: data.workspaceId, projectId: data.projectId };
+}
+
 export interface FileToWrite {
   path: string;
   content: string;
   type: "text" | "json" | "toml";
   tomlSection?: string;
+  mode?: number;
 }
 
 export interface SymlinkToCreate {
@@ -288,6 +319,36 @@ async function getAgentFiles(
         );
       }
 
+      // Pre-populate ~/.hmy/VERSION and ~/.hmy/bin/hmy-update-check so the
+      // lazy bootstrap inside the skill preamble is bypassed on first run.
+      // Without this, the bootstrap writes "1.0.0" as a fallback whenever the
+      // version fetch times out (edge function cold start) — triggering a
+      // spurious "upgrade to v6" prompt the moment the skill is first invoked.
+      try {
+        const updateCheckFetched = await client.fetchSkill("hmy-update-check");
+        const actualHash = createHash("sha256")
+          .update(updateCheckFetched.content)
+          .digest("hex");
+        if (actualHash !== updateCheckFetched.sha256) {
+          throw new Error(
+            `hmy-update-check integrity check failed: expected ${updateCheckFetched.sha256}, got ${actualHash}`,
+          );
+        }
+        files.push({
+          path: join(home, ".hmy", "bin", "hmy-update-check"),
+          content: updateCheckFetched.content,
+          type: "text",
+          mode: 0o755,
+        });
+        files.push({
+          path: join(home, ".hmy", "VERSION"),
+          content: versionInfo.version,
+          type: "text",
+        });
+      } catch {
+        // Non-fatal — bootstrap will install both on first skill invocation.
+      }
+
       // Note: MCP server registration is handled separately via `claude mcp add` CLI
       // in runSetup() after file writing, with fallback to settings.json if CLI unavailable
       break;
@@ -524,8 +585,8 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
   let needsSkills = !skillsStatus.installed || options.force;
   let needsContext = !hasContext && !options.skipContext;
 
-  // If workspace/project provided via flags, we'll set context
-  if (options.workspaceId || options.projectId) {
+  // If workspace/project/slug provided via flags or argument, we'll set context
+  if (options.workspaceId || options.projectId || options.projectSlug) {
     needsContext = true;
   }
 
@@ -806,6 +867,35 @@ export async function runSetup(options: SetupOptions = {}): Promise<void> {
     selectedWorkspaceNameFromSignup;
   let selectedProjectName: string | undefined = selectedProjectNameFromSignup;
 
+  // Resolve project slug shorthand (e.g. `npx @gethmy/mcp setup harmony-6590761b`).
+  // Slug wins over --workspace/--project flags only when those aren't already set
+  // from signup or explicit flags.
+  if (
+    options.projectSlug &&
+    apiKey &&
+    (!selectedWorkspaceId || !selectedProjectId)
+  ) {
+    spinner.start(`Resolving project slug "${options.projectSlug}"...`);
+    try {
+      const resolved = await resolveProjectSlug(apiKey, options.projectSlug);
+      if (resolved) {
+        selectedWorkspaceId = selectedWorkspaceId || resolved.workspaceId;
+        selectedProjectId = selectedProjectId || resolved.projectId;
+        spinner.stop(colors.success(`Resolved "${options.projectSlug}"`));
+      } else {
+        spinner.stop(
+          colors.warning(`No project found for slug "${options.projectSlug}"`),
+        );
+      }
+    } catch (error) {
+      spinner.stop(
+        colors.warning(
+          `Could not resolve slug: ${error instanceof Error ? error.message : "unknown error"}`,
+        ),
+      );
+    }
+  }
+
   // Skip context selection if we just created a new account
   if (createdNewAccount) {
     needsContext = false;

package/src/tui/writer.ts

@@ -1,4 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname } from "node:path";
 import * as p from "@clack/prompts";
@@ -15,6 +21,7 @@ export interface FileResult {
 interface WriteOptions {
   force?: boolean;
   merge?: boolean;
+  mode?: number;
 }
 
 /**
@@ -42,9 +49,12 @@ export function writeFile(
 
   try {
     ensureDir(dirname(filePath));
-    // Use restrictive permissions for config files
-    const mode = filePath.includes(".harmony-mcp") ? 0o600 : 0o644;
+    const defaultMode = filePath.includes(".harmony-mcp") ? 0o600 : 0o644;
+    const mode = options.mode ?? defaultMode;
     writeFileSync(filePath, content, { mode });
+    if (options.mode !== undefined) {
+      chmodSync(filePath, options.mode);
+    }
     return { path: filePath, action: exists ? "update" : "create" };
   } catch (error) {
     return {
@@ -183,6 +193,7 @@ export async function writeFilesWithProgress(
     type: "text" | "json" | "toml";
     jsonKey?: string;
     tomlSection?: string;
+    mode?: number;
   }>,
   options: WriteOptions = {},
 ): Promise<FileResult[]> {
@@ -201,7 +212,10 @@ export async function writeFilesWithProgress(
     } else if (file.type === "toml" && file.tomlSection) {
       result = appendToToml(file.path, file.tomlSection, file.content, options);
     } else {
-      result = writeFile(file.path, file.content, options);
+      result = writeFile(file.path, file.content, {
+        ...options,
+        mode: file.mode,
+      });
     }
 
     results.push(result);