@keystrokehq/cli 0.0.132 → 0.0.134

package/dist/index.mjs

@@ -1852,6 +1852,8 @@ const OrganizationSlugSchema = string().trim().toLowerCase().min(2, "Slug must b
 * fail to load.
 */
 const ClaimableOrganizationSlugSchema = OrganizationSlugSchema.refine((slug) => !RESERVED_ORGANIZATION_SLUGS.has(slug), "This slug is reserved");
+/** Same format as organization slugs — org-scoped, no global reserved list. */
+const ProjectSlugSchema = OrganizationSlugSchema;
 /** Browser→platform request budget (ping + small platform overhead). */
 const PROJECT_REACHABILITY_REQUEST_TIMEOUT_MS = 17e3;
 /** Normalize a public origin URL (no trailing slash). */
@@ -1891,6 +1893,7 @@ const serializedRouteManifestEntrySchema = discriminatedUnion("kind", [
 		kind: literal("agent"),
 		method: literal("POST"),
 		path: string(),
+		agentSlug: string(),
 		moduleFile: string(),
 		requestSchema: record(string(), unknown()),
 		responseSchema: record(string(), unknown())
@@ -1899,21 +1902,21 @@ const serializedRouteManifestEntrySchema = discriminatedUnion("kind", [
 		kind: literal("agent-sessions-list"),
 		method: literal("GET"),
 		path: string(),
-		agentId: string(),
+		agentSlug: string(),
 		moduleFile: string()
 	}),
 	object({
 		kind: literal("agent-session-detail"),
 		method: literal("GET"),
 		path: string(),
-		agentId: string(),
+		agentSlug: string(),
 		moduleFile: string()
 	}),
 	object({
 		kind: literal("workflow"),
 		method: literal("POST"),
 		path: string(),
-		workflowId: string(),
+		workflowSlug: string(),
 		workflowName: string().optional(),
 		moduleFile: string(),
 		requestSchema: record(string(), unknown()),
@@ -1923,7 +1926,7 @@ const serializedRouteManifestEntrySchema = discriminatedUnion("kind", [
 		kind: literal("workflow-runs-list"),
 		method: literal("GET"),
 		path: string(),
-		workflowId: string(),
+		workflowSlug: string(),
 		workflowName: string().optional(),
 		moduleFile: string()
 	}),
@@ -1931,7 +1934,7 @@ const serializedRouteManifestEntrySchema = discriminatedUnion("kind", [
 		kind: literal("workflow-run-detail"),
 		method: literal("GET"),
 		path: string(),
-		workflowId: string(),
+		workflowSlug: string(),
 		workflowName: string().optional(),
 		moduleFile: string()
 	}),
@@ -2053,6 +2056,17 @@ object({
 	slug: string().trim().min(1),
 	excludeOrganizationId: string().min(1).optional()
 });
+const ProjectSlugAvailabilityReasonSchema = _enum(["taken", "invalid"]);
+const ProjectSlugAvailabilityResponseSchema = object({
+	slug: string(),
+	available: boolean(),
+	reason: ProjectSlugAvailabilityReasonSchema.optional(),
+	suggestion: ProjectSlugSchema.optional()
+});
+object({
+	slug: string().trim().min(1),
+	excludeProjectId: string().min(1).optional()
+});
 const ProjectStatusSchema = _enum([
 	"inactive",
 	"starting",
@@ -2076,6 +2090,7 @@ const ProjectSchema = object({
 	id: string(),
 	organizationId: string(),
 	name: string(),
+	slug: ProjectSlugSchema,
 	description: string().nullable(),
 	status: ProjectStatusSchema,
 	baseUrl: string().nullable(),
@@ -2116,8 +2131,9 @@ const CreateProjectRequestSchema = object({
 });
 const UpdateProjectRequestSchema = object({
 	name: string().trim().min(1).optional(),
-	description: string().trim().optional()
-}).refine((data) => data.name !== void 0 || data.description !== void 0, { message: "At least one field is required" });
+	description: string().trim().optional(),
+	slug: ProjectSlugSchema.optional()
+}).refine((data) => data.name !== void 0 || data.description !== void 0 || data.slug !== void 0, { message: "At least one field is required" });
 const CreateProjectResponseSchema = object({ project: ProjectSchema });
 const ProjectResponseSchema = object({ project: ProjectSchema });
 const ProjectReachabilityResponseSchema = object({ reachable: boolean() });
@@ -2255,7 +2271,7 @@ const WorkflowRunSummarySchema = object({
 });
 const WorkflowRunRecordSchema = object({
 	id: string(),
-	workflowKey: string(),
+	workflowSlug: string(),
 	status: WorkflowRunStatusSchema,
 	trigger: WorkflowRunTriggerSchema,
 	triggeredAt: string(),
@@ -2290,7 +2306,7 @@ object({ include: string().optional() });
 const TriggerRunDetailSchema = object({
 	id: string(),
 	attachmentId: string(),
-	attachmentKey: string().nullable(),
+	attachmentSlug: string().nullable(),
 	triggerType: _enum([
 		"cron",
 		"webhook",
@@ -2309,10 +2325,10 @@ const WorkflowStepRunSchema = object({
 const TraceTriggerSummarySchema = object({
 	triggerType: string(),
 	triggerRunId: string(),
-	workflowKey: string().optional(),
-	agentKey: string().optional(),
+	workflowSlug: string().optional(),
+	agentSlug: string().optional(),
 	attachmentId: string().nullable().optional(),
-	attachmentKey: string().nullable().optional(),
+	attachmentSlug: string().nullable().optional(),
 	route: string().optional(),
 	sourcePath: string().nullable().optional()
 }).nullable();
@@ -2376,7 +2392,7 @@ const AgentSessionSummarySchema = object({
 });
 const AgentSessionRecordSchema = object({
 	id: string(),
-	agentKey: string(),
+	agentSlug: string(),
 	status: AgentSessionStatusSchema,
 	source: RunSourceKindSchema,
 	sourceId: string().nullable(),
@@ -2406,7 +2422,7 @@ object({ include: string().optional() });
 const GatewaySessionDetailSchema = object({
 	threadId: string(),
 	attachmentId: string(),
-	attachmentKey: string().nullable()
+	attachmentSlug: string().nullable()
 });
 const AgentEventSchema = object({
 	id: string(),
@@ -2501,11 +2517,11 @@ const TriggerRunTypeSchema = _enum([
 const TriggerRunWorkflowSummarySchema = object({
 	id: string(),
 	status: WorkflowRunStatusSchema,
-	workflowKey: string()
+	workflowSlug: string()
 });
 const TriggerRunAgentSessionSummarySchema = object({
 	id: string(),
-	agentKey: string()
+	agentSlug: string()
 });
 const TriggerRunSummarySchema = object({
 	id: string(),
@@ -2518,7 +2534,7 @@ const TriggerRunSummarySchema = object({
 const TriggerRunRecordSchema = object({
 	id: string(),
 	attachmentId: string(),
-	attachmentKey: string(),
+	attachmentSlug: string(),
 	triggerType: TriggerRunTypeSchema,
 	sourcePath: string().nullable(),
 	payload: unknown().nullable(),
@@ -2541,7 +2557,7 @@ _enum([
 object({ include: string().optional() });
 const TriggerRunAgentSessionDetailSchema = object({
 	id: string(),
-	agentKey: string()
+	agentSlug: string()
 });
 const TriggerRunDetailResponseSchema = object({
 	run: TriggerRunRecordSchema,
@@ -2684,6 +2700,7 @@ const optionalCount = number$1().int().nonnegative().nullable().optional();
 const optionalTimestamp = string().nullable().optional();
 const AgentSummarySchema = object({
 	id: string().min(1),
+	slug: string().min(1),
 	name: string().min(1),
 	projectId: string().min(1),
 	updatedAt: string().min(1),
@@ -2696,16 +2713,17 @@ const AgentSummarySchema = object({
 });
 const WorkflowSummarySchema = object({
 	id: string().min(1),
+	slug: string().min(1),
 	name: string().min(1),
 	projectId: string().min(1),
 	updatedAt: string().min(1),
 	description: string().optional(),
 	sourcePath: string().min(1).optional(),
-	stepCount: optionalCount,
 	lastRunAt: optionalTimestamp
 });
 const SkillSummarySchema = object({
 	id: string().min(1),
+	slug: string().min(1),
 	name: string().min(1),
 	projectId: string().min(1),
 	updatedAt: string().min(1),
@@ -2750,9 +2768,9 @@ const ProjectFileSummarySchema = object({
 	path: string().min(1),
 	hash: sha256Hex
 });
-/** Maps a runtime resource key (agent/workflow/skill) to its source file path. */
+/** Maps a runtime resource slug (agent/workflow/skill) to its source file path. */
 const ProjectSourceResourceRefSchema = object({
-	key: string().min(1),
+	slug: string().min(1),
 	path: string().min(1)
 });
 const ProjectSourceResourcesSchema = object({
@@ -5174,6 +5192,16 @@ function createProjectsResource(http) {
 			} catch (error) {
 				throw await toPlatformError(error);
 			}
+		},
+		async checkSlug(slug, options = {}) {
+			const searchParams = new URLSearchParams({ slug });
+			if (options.excludeProjectId) searchParams.set("excludeProjectId", options.excludeProjectId);
+			try {
+				const data = await http.get(`/api/projects/slug-available?${searchParams}`).json();
+				return ProjectSlugAvailabilityResponseSchema.parse(data);
+			} catch (error) {
+				throw await toPlatformError(error);
+			}
 		}
 	};
 }
@@ -5187,11 +5215,15 @@ function createProjectMetricsResource(http) {
 		}
 	} };
 }
+function listSearchParams$2(options) {
+	const projectId = options?.projectId?.trim();
+	return projectId ? { projectId } : void 0;
+}
 function createAgentsResource(http) {
 	return {
-		async list() {
+		async list(options) {
 			try {
-				const data = await http.get("/api/agents").json();
+				const data = await http.get("/api/agents", { searchParams: listSearchParams$2(options) }).json();
 				return AgentSummaryListResponseSchema.parse(data);
 			} catch (error) {
 				throw await toPlatformError(error);
@@ -5207,11 +5239,15 @@ function createAgentsResource(http) {
 		}
 	};
 }
+function listSearchParams$1(options) {
+	const projectId = options?.projectId?.trim();
+	return projectId ? { projectId } : void 0;
+}
 function createWorkflowsResource(http) {
 	return {
-		async list() {
+		async list(options) {
 			try {
-				const data = await http.get("/api/workflows").json();
+				const data = await http.get("/api/workflows", { searchParams: listSearchParams$1(options) }).json();
 				return WorkflowSummaryListResponseSchema.parse(data);
 			} catch (error) {
 				throw await toPlatformError(error);
@@ -5227,11 +5263,15 @@ function createWorkflowsResource(http) {
 		}
 	};
 }
+function listSearchParams(options) {
+	const projectId = options?.projectId?.trim();
+	return projectId ? { projectId } : void 0;
+}
 function createSkillsResource(http) {
 	return {
-		async list() {
+		async list(options) {
 			try {
-				const data = await http.get("/api/skills").json();
+				const data = await http.get("/api/skills", { searchParams: listSearchParams(options) }).json();
 				return SkillSummaryListResponseSchema.parse(data);
 			} catch (error) {
 				throw await toPlatformError(error);
@@ -6754,6 +6794,7 @@ const credentialSeed = [
 ];
 const agentSeed = [{
 	id: "agent-support",
+	slug: "support-agent",
 	name: "Support Agent",
 	projectId: "project_personal_repo",
 	updatedAt: "2026-06-02T14:20:00Z",
@@ -6765,6 +6806,7 @@ const agentSeed = [{
 	lastRunAt: "2026-06-02T14:20:00Z"
 }, {
 	id: "agent-research",
+	slug: "research-agent",
 	name: "Research Agent",
 	projectId: "project_personal_repo",
 	updatedAt: "2026-06-01T09:15:00Z",
@@ -6777,21 +6819,21 @@ const agentSeed = [{
 }];
 const workflowSeed = [{
 	id: "workflow-daily-digest",
+	slug: "daily-digest",
 	name: "Daily Digest",
 	projectId: "project_personal_repo",
 	updatedAt: "2026-06-02T11:05:00Z",
 	description: "Collect project updates and send a daily summary.",
 	sourcePath: "src/workflows/daily-digest.ts",
-	stepCount: 2,
 	lastRunAt: "2026-06-02T11:05:00Z"
 }, {
 	id: "workflow-email-triage",
+	slug: "email-triage",
 	name: "Email Triage",
 	projectId: "project_personal_repo",
 	updatedAt: "2026-05-31T16:40:00Z",
 	description: "Label, prioritize, and draft replies for inbound email.",
 	sourcePath: "src/workflows/email-triage.ts",
-	stepCount: 4,
 	lastRunAt: "2026-05-31T16:40:00Z"
 }];
 /** Review personas for mocked project members and API key authors (not org membership). */
@@ -7124,15 +7166,11 @@ function buildFailedUsage(durationMs) {
 		totalExcludingDurationUsd: .021
 	};
 }
-function workflowKeyFromId(workflowId) {
-	const row = workflowSeed.find((workflow) => workflow.id === workflowId);
-	if (!row?.sourcePath) return workflowId;
-	return row.sourcePath.match(/\/([^/]+)\.ts$/)?.[1] ?? workflowId;
+function workflowSlugFromId(workflowId) {
+	return workflowSeed.find((workflow) => workflow.id === workflowId)?.slug ?? workflowId;
 }
-function agentKeyFromId(agentId) {
-	const row = agentSeed.find((agent) => agent.id === agentId);
-	if (!row?.sourcePath) return agentId;
-	return row.sourcePath.match(/\/([^/]+)\.ts$/)?.[1] ?? agentId;
+function agentSlugFromId(agentId) {
+	return agentSeed.find((agent) => agent.id === agentId)?.slug ?? agentId;
 }
 const historyRunSeed = [
 	{
@@ -7141,7 +7179,7 @@ const historyRunSeed = [
 		traceId: "run-support-agent-001",
 		projectId: "project_personal_repo",
 		projectName: historyProjectNameById.project_personal_repo ?? "Project",
-		resourceKey: agentKeyFromId("agent-support"),
+		resourceKey: agentSlugFromId("agent-support"),
 		resourceId: "agent-support",
 		resourceName: "Support Agent",
 		status: "completed",
@@ -7164,7 +7202,7 @@ const historyRunSeed = [
 		traceId: "run-daily-digest-001",
 		projectId: "project_personal_repo",
 		projectName: historyProjectNameById.project_personal_repo ?? "Project",
-		resourceKey: workflowKeyFromId("workflow-daily-digest"),
+		resourceKey: workflowSlugFromId("workflow-daily-digest"),
 		resourceId: "workflow-daily-digest",
 		resourceName: "Daily Digest",
 		status: "running",
@@ -7187,7 +7225,7 @@ const historyRunSeed = [
 		traceId: "run-support-agent-000",
 		projectId: "project_personal_repo",
 		projectName: historyProjectNameById.project_personal_repo ?? "Project",
-		resourceKey: agentKeyFromId("agent-support"),
+		resourceKey: agentSlugFromId("agent-support"),
 		resourceId: "agent-support",
 		resourceName: "Support Agent",
 		status: "failed",
@@ -7210,7 +7248,7 @@ const historyRunSeed = [
 		traceId: "run-email-triage-002",
 		projectId: "project_personal_repo",
 		projectName: historyProjectNameById.project_personal_repo ?? "Project",
-		resourceKey: workflowKeyFromId("workflow-email-triage"),
+		resourceKey: workflowSlugFromId("workflow-email-triage"),
 		resourceId: "workflow-email-triage",
 		resourceName: "Email Triage",
 		status: "failed",
@@ -7233,7 +7271,7 @@ const historyRunSeed = [
 		traceId: "run-research-agent-003",
 		projectId: "project_personal_repo",
 		projectName: historyProjectNameById.project_personal_repo ?? "Project",
-		resourceKey: agentKeyFromId("agent-research"),
+		resourceKey: agentSlugFromId("agent-research"),
 		resourceId: "agent-research",
 		resourceName: "Research Agent",
 		status: "completed",
@@ -8587,6 +8625,33 @@ function createCliPlatformClient(config) {
 	});
 }
 //#endregion
+//#region src/resolve-resource-ref.ts
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function looksLikeUuid(value) {
+	return UUID_PATTERN.test(value);
+}
+function formatProjectLabel(project) {
+	return project.slug;
+}
+async function resolveProjectRef(platform, ref) {
+	if (looksLikeUuid(ref)) try {
+		return await platform.projects.get(ref);
+	} catch (error) {
+		if (error instanceof PlatformError && error.status === 404) throw new Error(`Project ${ref} not found in the active organization. Run \`keystroke project list\`, then \`keystroke config use project <slug>\`.`);
+		throw error;
+	}
+	const match = (await platform.projects.list()).find((project) => project.slug === ref);
+	if (!match) throw new Error(`Project "${ref}" not found in the active organization. Run \`keystroke project list\`.`);
+	return match;
+}
+function resolveOrganizationRef(organizations, ref) {
+	const byId = organizations.find((entry) => entry.organization.id === ref);
+	if (byId) return byId;
+	const bySlug = organizations.find((entry) => entry.organization.slug === ref);
+	if (bySlug) return bySlug;
+	throw new Error(`Organization "${ref}" was not found or you do not have access`);
+}
+//#endregion
 //#region src/organization/active-organization.ts
 function formatOrganization(membership) {
 	return `${membership.organization.name} (${membership.role})`;
@@ -8600,15 +8665,11 @@ async function activateOrganization(config, organizationId) {
 	platform.setActiveOrganizationId(membership.organization.id);
 	return membership;
 }
-async function pickOrganization(config, organizations, organizationId) {
-	if (organizationId) {
-		const membership = organizations.find((entry) => entry.organization.id === organizationId);
-		if (!membership) throw new Error(`Organization ${organizationId} was not found or you do not have access`);
-		return activateOrganization(config, membership.organization.id);
-	}
+async function pickOrganization(config, organizations, organizationRef) {
+	if (organizationRef) return activateOrganization(config, resolveOrganizationRef(organizations, organizationRef).organization.id);
 	if (!process.stdin.isTTY) {
-		const names = organizations.map((entry) => entry.organization.id).join(", ");
-		throw new Error(`Multiple organizations found. Run \`keystroke config use org <id>\`. Options: ${names}`);
+		const names = organizations.map((entry) => entry.organization.slug).join(", ");
+		throw new Error(`Multiple organizations found. Run \`keystroke config use org <slug>\`. Options: ${names}`);
 	}
 	return activateOrganization(config, await select({
 		message: "Select an organization",
@@ -8622,7 +8683,7 @@ async function selectActiveOrganization(config, options = {}) {
 	const organizations = await listOrganizations(config);
 	if (organizations.length === 0) throw new Error(`No organization found — create one at ${getWebUrl(config)}`);
 	if (organizations.length === 1) return activateOrganization(config, organizations[0].organization.id);
-	return pickOrganization(config, organizations, options.organizationId);
+	return pickOrganization(config, organizations, options.organizationRef ?? options.organizationId);
 }
 async function syncActiveOrganizationAfterLogin(config, options = {}) {
 	const organizations = await listOrganizations(config);
@@ -8638,8 +8699,8 @@ async function syncActiveOrganizationAfterLogin(config, options = {}) {
 		process.stdout.write(`Using organization ${membership.organization.name}\n`);
 		return membership;
 	}
-	if (options.organizationId) {
-		const membership = await pickOrganization(config, organizations, options.organizationId);
+	if (options.organizationRef ?? options.organizationId) {
+		const membership = await pickOrganization(config, organizations, options.organizationRef ?? options.organizationId);
 		process.stdout.write(`Using organization ${membership.organization.name}\n`);
 		return membership;
 	}
@@ -8712,19 +8773,19 @@ function resolveOrgPlatformTarget(config) {
 		mode: "platform"
 	};
 }
-async function resolvePlatformTarget(config, projectId) {
+async function resolvePlatformTarget(config, projectRef) {
 	const platform = createCliPlatformClient(config);
 	let project;
 	try {
-		project = await platform.projects.get(projectId);
+		project = await resolveProjectRef(platform, projectRef);
 	} catch (error) {
-		if (error instanceof PlatformError && error.status === 404) throw new Error(`Project ${projectId} not found in the active organization. Run \`keystroke config use project <id>\` or pass \`--project\` with a valid project id.`);
+		if (error instanceof Error) throw error;
 		throw error;
 	}
-	if (project.status !== "active") throw new Error(`Project ${projectId} is not active (${project.status})`);
+	if (project.status !== "active") throw new Error(`Project ${formatProjectLabel(project)} is not active (${project.status})`);
 	return {
-		baseUrl: `${getPlatformUrl(config).replace(/\/+$/, "")}/api/projects/${encodeURIComponent(projectId)}`,
-		projectId,
+		baseUrl: `${getPlatformUrl(config).replace(/\/+$/, "")}/api/projects/${encodeURIComponent(project.id)}`,
+		projectId: project.id,
 		mode: "platform"
 	};
 }
@@ -8742,9 +8803,9 @@ async function resolveApiTarget(config, options = {}) {
 	if (options.projectId) return resolvePlatformTarget(config, options.projectId);
 	if (getEffectiveApiTarget(config) === "local") return resolveLocalTarget(config);
 	if (!options.projectScoped) return resolveOrgPlatformTarget(config);
-	const projectId = options.projectId ?? config.get("activeProjectId");
-	if (!projectId) throw new Error("No project selected. Pass `--project <id>` or run `keystroke config use project <id>`.");
-	return resolvePlatformTarget(config, projectId);
+	const projectRef = options.projectId ?? config.get("activeProjectId");
+	if (!projectRef) throw new Error("No project selected. Pass `--project <slug>` or run `keystroke config use project <slug>`.");
+	return resolvePlatformTarget(config, projectRef);
 }
 //#endregion
 //#region src/target-options.ts
@@ -8755,9 +8816,6 @@ function setCliTargetOptions(options) {
 function getCliTargetOptions() {
 	return targetOptions;
 }
-function resolveActiveProjectId(config) {
-	return getCliTargetOptions().projectId ?? config.get("activeProjectId");
-}
 //#endregion
 //#region src/errors/example-input.ts
 function exampleValueFromValidationMessage(message) {
@@ -9232,7 +9290,7 @@ function resolveAuthLoginTargets(options, config) {
 //#endregion
 //#region src/commands/auth/login.ts
 function registerAuthLoginCommand(auth) {
-	auth.command("login").description("Authenticate via browser device flow").option("--web-url <url>", "Web dashboard origin (omit to use production defaults; local dev: http://localhost:3000)").option("--platform-url <url>", "Platform API origin (derived from web URL when omitted)").option("--org <id>", "Active organization id (skips prompt when you belong to several)").action(async (options) => {
+	auth.command("login").description("Authenticate via browser device flow").option("--web-url <url>", "Web dashboard origin (omit to use production defaults; local dev: http://localhost:3000)").option("--platform-url <url>", "Platform API origin (derived from web URL when omitted)").option("--org <slug>", "Active organization slug (skips prompt when you belong to several)").action(async (options) => {
 		const config = createCliConfig();
 		const { webUrl, platformUrl } = resolveAuthLoginTargets(options, config);
 		config.set("webUrl", webUrl);
@@ -9247,7 +9305,7 @@ function registerAuthLoginCommand(auth) {
 			const user = await getSessionWithBearer(platformUrl, result.accessToken);
 			if (user) process.stdout.write(`Logged in as ${user.name} (${user.email})\n`);
 			else process.stdout.write(`Logged in to ${webUrl}\n`);
-			await syncActiveOrganizationAfterLogin(config, { organizationId: options.org });
+			await syncActiveOrganizationAfterLogin(config, { organizationRef: options.org });
 		} catch (error) {
 			process.stderr.write(`${formatCliError(error, "Login failed", {
 				webUrl,
@@ -9425,9 +9483,9 @@ function collectModuleRefs(srcRoot, root, files, subdir, nestedEntry) {
 	const refs = [];
 	for (const file of files) {
 		if (!file.path.startsWith(prefix) || !/\.(ts|mts)$/.test(file.path)) continue;
-		const key = entryIdFromFile(dir, join(root, file.path), { nestedEntry });
-		if (key) refs.push({
-			key,
+		const slug = entryIdFromFile(dir, join(root, file.path), { nestedEntry });
+		if (slug) refs.push({
+			slug,
 			path: file.path
 		});
 	}
@@ -9439,9 +9497,9 @@ function collectSkillRefs(srcRoot, root, files) {
 	const refs = [];
 	for (const file of files) {
 		if (!file.path.startsWith(prefix) || !file.path.endsWith("SKILL.md")) continue;
-		const key = toPosix(relative(dir, join(root, file.path)).replace(/\/?SKILL\.md$/, ""));
-		if (key) refs.push({
-			key,
+		const slug = toPosix(relative(dir, join(root, file.path)).replace(/\/?SKILL\.md$/, ""));
+		if (slug) refs.push({
+			slug,
 			path: file.path
 		});
 	}
@@ -9467,6 +9525,18 @@ function collectProjectSource(root) {
 	};
 }
 //#endregion
+//#region src/resolve-project-target.ts
+async function resolveActiveProject(config, platform) {
+	const ref = getCliTargetOptions().projectId ?? config.get("activeProjectId");
+	if (!ref) return;
+	const client = platform ?? createCliPlatformClient(config);
+	if (!getCliTargetOptions().projectId && looksLikeUuid(ref)) return resolveProjectRef(client, ref);
+	return resolveProjectRef(client, ref);
+}
+async function resolveActiveProjectId(config) {
+	return (await resolveActiveProject(config))?.id;
+}
+//#endregion
 //#region src/commands/deploy.ts
 const POLL_INTERVAL_MS = 2e3;
 const DEPLOY_TIMEOUT_MS = 12e4;
@@ -9557,8 +9627,8 @@ async function runDeploy(options) {
 function registerDeployCommand(program) {
 	program.command("deploy").description("Build, upload, and deploy the project to the platform").option("--dir <path>", "Project directory", process.cwd()).option("--skip-build", "Upload the existing dist/ without rebuilding").action(async (options) => {
 		try {
-			const projectId = resolveActiveProjectId(createCliConfig());
-			if (!projectId) throw new Error("Usage: keystroke deploy --project <id>");
+			const projectId = await resolveActiveProjectId(createCliConfig());
+			if (!projectId) throw new Error("Usage: keystroke deploy --project <slug>");
 			await runDeploy({
 				dir: options.dir,
 				projectId,
@@ -10118,7 +10188,7 @@ function writeInactiveDeployHints(projects) {
 	const bin = cliBinaryName();
 	for (const project of projects) {
 		if (project.status !== "inactive") continue;
-		process.stderr.write(`Project ${project.id} is inactive. Deploy with: ${bin} deploy --project ${project.id}\n`);
+		process.stderr.write(`Project ${formatProjectLabel(project)} is inactive. Deploy with: ${bin} deploy --project ${formatProjectLabel(project)}\n`);
 	}
 }
 async function runProjectList(config) {
@@ -10136,13 +10206,19 @@ async function runProjectList(config) {
 async function runProjectMetrics(config, options) {
 	await withActivePlatformClient(config, async (platform) => {
 		const metrics = await platform.projectMetrics.list();
-		const output = options.projectId === void 0 ? metrics : Object.fromEntries(Object.entries(metrics).filter(([projectId]) => projectId === options.projectId));
+		if (options.projectRef === void 0) {
+			process.stdout.write(`${JSON.stringify(metrics, null, 2)}\n`);
+			return;
+		}
+		const project = await resolveProjectRef(platform, options.projectRef);
+		const output = Object.fromEntries(Object.entries(metrics).filter(([projectId]) => projectId === project.id));
 		process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 	});
 }
 async function runProjectDeploymentsList(config, options) {
 	await withActivePlatformClient(config, async (platform) => {
-		const deployments = await platform.deployments.listForProject(options.projectId);
+		const project = await resolveProjectRef(platform, options.projectRef);
+		const deployments = await platform.deployments.listForProject(project.id);
 		process.stdout.write(`${JSON.stringify({ deployments }, null, 2)}\n`);
 	});
 }
@@ -10206,10 +10282,10 @@ function registerProjectCommand(program) {
 			process.exitCode = 1;
 		}
 	});
-	project.command("metrics").description("List rollup metrics for projects in the active organization").option("--project <id>", "Return metrics for a single project").action(async (options) => {
+	project.command("metrics").description("List rollup metrics for projects in the active organization").option("--project <slug>", "Return metrics for a single project").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			await runProjectMetrics(config, { ...options.project ? { projectId: options.project } : {} });
+			await runProjectMetrics(config, { ...options.project ? { projectRef: options.project } : {} });
 		} catch (error) {
 			process.stderr.write(`${formatCliError(error, "List project metrics failed", {
 				serverUrl: getPlatformUrl(config),
@@ -10218,12 +10294,12 @@ function registerProjectCommand(program) {
 			process.exitCode = 1;
 		}
 	});
-	project.command("deployments").description("View deployment history for platform projects").command("list").description("List deployment history for a project").option("--project <id>", "Project ID").action(async (options) => {
+	project.command("deployments").description("View deployment history for platform projects").command("list").description("List deployment history for a project").option("--project <slug>", "Project slug").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			const projectId = options.project ?? resolveActiveProjectId(config);
-			if (!projectId) throw new Error("Usage: keystroke project deployments list --project <id>");
-			await runProjectDeploymentsList(config, { projectId });
+			const projectRef = options.project ?? getCliTargetOptions().projectId ?? config.get("activeProjectId");
+			if (!projectRef) throw new Error("Usage: keystroke project deployments list --project <slug>");
+			await runProjectDeploymentsList(config, { projectRef });
 		} catch (error) {
 			process.stderr.write(`${formatCliError(error, "List deployments failed", {
 				serverUrl: getPlatformUrl(config),
@@ -10250,8 +10326,8 @@ function registerProjectCommand(program) {
 	project.command("update").description("Update a platform project's name and/or description").option("--name <name>", "Project name").option("--description <description>", "Project description").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			const projectId = resolveActiveProjectId(config);
-			if (!projectId) throw new Error("Usage: keystroke --project <id> project update --name <name>");
+			const projectId = await resolveActiveProjectId(config);
+			if (!projectId) throw new Error("Usage: keystroke --project <slug> project update --name <name>");
 			if (!options.name && options.description === void 0) throw new Error("At least one of --name or --description is required");
 			await runProjectUpdate(config, {
 				projectId,
@@ -10269,8 +10345,8 @@ function registerProjectCommand(program) {
 	project.command("delete").description("Delete a platform project").option("-y, --yes", "Skip confirmation prompt").action(async (options) => {
 		const config = createCliConfig();
 		try {
-			const projectId = resolveActiveProjectId(config);
-			if (!projectId) throw new Error("Usage: keystroke --project <id> project delete");
+			const projectId = await resolveActiveProjectId(config);
+			if (!projectId) throw new Error("Usage: keystroke --project <slug> project delete");
 			if (!options.yes) throw new Error("Pass --yes to confirm project deletion");
 			await runProjectDelete(config, projectId);
 		} catch (error) {
@@ -10431,27 +10507,23 @@ function registerWorkflowCommand(program) {
 }
 //#endregion
 //#region src/commands/config/use-project.ts
-async function fetchProjectInOrg(config, projectId) {
-	const platform = createCliPlatformClient(config);
-	try {
-		return await platform.projects.get(projectId);
-	} catch (error) {
-		if (error instanceof PlatformError && error.status === 404) throw new Error(`Project ${projectId} not found in the active organization. Run \`keystroke project list\`, then \`keystroke config use project <id>\`.`);
-		throw error;
-	}
+async function fetchProjectInOrg(config, projectRef) {
+	return resolveProjectRef(createCliPlatformClient(config), projectRef);
 }
 function assertProjectReadyForConfig(project) {
-	if (project.status === "failed") throw new Error(project.lastError ? `Project ${project.id} deploy failed: ${project.lastError}` : `Project ${project.id} deploy failed`);
-	if (project.status === "starting") throw new Error(`Project ${project.id} is still starting. Wait for deploy to finish, then run \`keystroke config use project ${project.id}\`.`);
+	const label = formatProjectLabel(project);
+	if (project.status === "failed") throw new Error(project.lastError ? `Project ${label} deploy failed: ${project.lastError}` : `Project ${label} deploy failed`);
+	if (project.status === "starting") throw new Error(`Project ${label} is still starting. Wait for deploy to finish, then run \`keystroke config use project ${label}\`.`);
 }
-async function runConfigUseProject(config, projectId) {
-	const project = await fetchProjectInOrg(config, projectId);
+async function runConfigUseProject(config, projectRef) {
+	const project = await fetchProjectInOrg(config, projectRef);
 	assertProjectReadyForConfig(project);
-	config.set("activeProjectId", projectId);
+	config.set("activeProjectId", project.id);
 	config.set("apiTarget", "platform");
+	const label = formatProjectLabel(project);
 	return {
-		stdout: project.status === "active" ? `Using platform project ${projectId}\n` : `Using platform project ${projectId} (${project.status})\n`,
-		stderr: project.status === "inactive" ? `Project is not active yet. Deploy with: ${cliBinaryName()} deploy --project ${projectId}\n` : void 0
+		stdout: project.status === "active" ? `Using platform project ${label}\n` : `Using platform project ${label} (${project.status})\n`,
+		stderr: project.status === "inactive" ? `Project is not active yet. Deploy with: ${cliBinaryName()} deploy --project ${label}\n` : void 0
 	};
 }
 //#endregion
@@ -10480,7 +10552,7 @@ function registerConfigCommand(program) {
 			return;
 		}
 		if (mode === "org") {
-			const membership = await selectActiveOrganization(cliConfig, { organizationId: id });
+			const membership = await selectActiveOrganization(cliConfig, { organizationRef: id });
 			process.stdout.write(`Using organization ${membership.organization.name}\n`);
 			return;
 		}
@@ -10490,9 +10562,9 @@ function registerConfigCommand(program) {
 			process.stdout.write(activeProjectId ? `Using platform API (default project ${activeProjectId} for project-scoped commands)\n` : "Using platform API\n");
 			return;
 		}
-		if (mode !== "project") throw new Error("Usage: keystroke config use [local|cloud|project [projectId]|org [organizationId]]");
+		if (mode !== "project") throw new Error("Usage: keystroke config use [local|cloud|project [slug]|org [slug]]");
 		const targetProjectId = id ?? cliConfig.get("activeProjectId");
-		if (!targetProjectId) throw new Error("Usage: keystroke config use project <projectId>");
+		if (!targetProjectId) throw new Error("Usage: keystroke config use project <slug>");
 		const result = await runConfigUseProject(cliConfig, targetProjectId);
 		process.stdout.write(result.stdout);
 		if (result.stderr) process.stderr.write(result.stderr);
@@ -10566,7 +10638,7 @@ async function syncSkills(command) {
 //#endregion
 //#region src/program.ts
 function createProgram() {
-	const program = new Command().name("keystroke").description("Build, run, and manage keystroke projects").version(readCliVersion()).option("--project <id>", "Platform project id (deploy target or one-off API target)").option("--local", "Force local keystroke server URL").hook("preAction", async (thisCommand, actionCommand) => {
+	const program = new Command().name("keystroke").description("Build, run, and manage keystroke projects").version(readCliVersion()).option("--project <slug>", "Platform project slug (deploy target or one-off API target)").option("--local", "Force local keystroke server URL").hook("preAction", async (thisCommand, actionCommand) => {
 		const opts = thisCommand.opts();
 		setCliTargetOptions({
 			projectId: opts.project,