Skip to content

The open-source app everyone uses to manage agents at work

feat: organize skills with nested folders and My Skills (#9633)

Dotta52aea902632f
diff --git a/packages/db/src/migrations/0174_folders.sql b/packages/db/src/migrations/0174_folders.sql
new file mode 100644
index 0000000000..82abc7155f
--- /dev/null
+++ b/packages/db/src/migrations/0174_folders.sql
@@ -0,0 +1,46 @@
+CREATE TABLE IF NOT EXISTS "folders" (
+ "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+ "company_id" uuid NOT NULL,
+ "kind" text NOT NULL,
+ "name" text NOT NULL,
+ "color" text,
+ "position" integer DEFAULT 0 NOT NULL,
+ "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+ "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "company_skills" ADD COLUMN IF NOT EXISTS "folder_id" uuid;
+--> statement-breakpoint
+ALTER TABLE "routines" ADD COLUMN IF NOT EXISTS "folder_id" uuid;
+--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM "pg_constraint" WHERE "conname" = 'folders_company_id_companies_id_fk'
+ ) THEN
+ ALTER TABLE "folders" ADD CONSTRAINT "folders_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+ END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM "pg_constraint" WHERE "conname" = 'company_skills_folder_id_folders_id_fk'
+ ) THEN
+ ALTER TABLE "company_skills" ADD CONSTRAINT "company_skills_folder_id_folders_id_fk" FOREIGN KEY ("folder_id") REFERENCES "public"."folders"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM "pg_constraint" WHERE "conname" = 'routines_folder_id_folders_id_fk'
+ ) THEN
+ ALTER TABLE "routines" ADD CONSTRAINT "routines_folder_id_folders_id_fk" FOREIGN KEY ("folder_id") REFERENCES "public"."folders"("id") ON DELETE set null ON UPDATE no action;
+ END IF;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "folders_company_kind_position_idx" ON "folders" USING btree ("company_id","kind","position","name");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "folders_company_kind_name_uq" ON "folders" USING btree ("company_id","kind","name");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "company_skills_company_folder_idx" ON "company_skills" USING btree ("company_id","folder_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routines_company_folder_idx" ON "routines" USING btree ("company_id","folder_id");
diff --git a/packages/db/src/migrations/0175_nested_skill_folders.sql b/packages/db/src/migrations/0175_nested_skill_folders.sql
new file mode 100644
index 0000000000..7e4c8dee40
--- /dev/null
+++ b/packages/db/src/migrations/0175_nested_skill_folders.sql
@@ -0,0 +1,232 @@
+ALTER TABLE "folders" ADD COLUMN IF NOT EXISTS "parent_id" uuid;
+--> statement-breakpoint
+ALTER TABLE "folders" ADD COLUMN IF NOT EXISTS "slug" text;
+--> statement-breakpoint
+ALTER TABLE "folders" ADD COLUMN IF NOT EXISTS "system_key" text;
+--> statement-breakpoint
+WITH normalized AS (
+ SELECT
+ "id",
+ COALESCE(
+ NULLIF(TRIM(BOTH '-' FROM REGEXP_REPLACE(LOWER("name"), '[^a-z0-9]+', '-', 'g')), ''),
+ 'folder'
+ ) AS base_slug,
+ ROW_NUMBER() OVER (
+ PARTITION BY "company_id", "kind", COALESCE(
+ NULLIF(TRIM(BOTH '-' FROM REGEXP_REPLACE(LOWER("name"), '[^a-z0-9]+', '-', 'g')), ''),
+ 'folder'
+ )
+ ORDER BY "id"
+ ) AS duplicate_number
+ FROM "folders"
+ WHERE "slug" IS NULL
+)
+UPDATE "folders" AS folder
+SET "slug" = CASE
+ WHEN normalized.duplicate_number = 1 THEN normalized.base_slug
+ ELSE normalized.base_slug || '-' || LEFT(folder."id"::text, 8)
+END
+FROM normalized
+WHERE folder."id" = normalized."id";
+--> statement-breakpoint
+ALTER TABLE "folders" ALTER COLUMN "slug" SET NOT NULL;
+--> statement-breakpoint
+DROP INDEX IF EXISTS "folders_company_kind_name_uq";
+--> statement-breakpoint
+DO $$ BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM "pg_constraint" WHERE "conname" = 'folders_parent_id_folders_id_fk'
+ ) THEN
+ ALTER TABLE "folders" ADD CONSTRAINT "folders_parent_id_folders_id_fk"
+ FOREIGN KEY ("parent_id") REFERENCES "public"."folders"("id") ON DELETE restrict ON UPDATE no action;
+ END IF;
+END $$;
+--> statement-breakpoint
+ALTER TABLE "folders" DROP CONSTRAINT IF EXISTS "folders_company_kind_parent_slug_uq";
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "folders_company_kind_root_slug_uq"
+ ON "folders" USING btree ("company_id", "kind", "slug")
+ WHERE "parent_id" IS NULL;
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "folders_company_kind_parent_slug_uq"
+ ON "folders" USING btree ("company_id", "kind", "parent_id", "slug")
+ WHERE "parent_id" IS NOT NULL;
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "folders_company_kind_system_key_uq"
+ ON "folders" USING btree ("company_id", "kind", "system_key")
+ WHERE "system_key" IS NOT NULL;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "folders_company_kind_parent_position_idx"
+ ON "folders" USING btree ("company_id", "kind", "parent_id", "position", "name");
+--> statement-breakpoint
+UPDATE "folders" AS folder
+SET "slug" = 'bundled-' || LEFT(REPLACE(folder."id"::text, '-', ''), 8), "updated_at" = now()
+WHERE folder."kind" = 'skill'
+ AND folder."parent_id" IS NULL
+ AND folder."slug" = 'bundled'
+ AND folder."system_key" IS NULL
+ AND EXISTS (
+ SELECT 1
+ FROM "company_skills" AS skill
+ WHERE skill."company_id" = folder."company_id"
+ AND skill."folder_id" IS NULL
+ AND (skill."key" LIKE 'paperclipai/bundled/%' OR skill."metadata"->>'sourceKind' = 'paperclip_bundled')
+ );
+--> statement-breakpoint
+INSERT INTO "folders" ("company_id", "kind", "parent_id", "name", "slug", "system_key", "position")
+SELECT DISTINCT skill."company_id", 'skill', NULL::uuid, 'Bundled', 'bundled', 'bundled', 0
+FROM "company_skills" AS skill
+WHERE skill."folder_id" IS NULL
+ AND (skill."key" LIKE 'paperclipai/bundled/%' OR skill."metadata"->>'sourceKind' = 'paperclip_bundled')
+ AND NOT EXISTS (
+ SELECT 1 FROM "folders" AS folder
+ WHERE folder."company_id" = skill."company_id"
+ AND folder."kind" = 'skill'
+ AND folder."system_key" = 'bundled'
+ )
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+WITH bundled_categories AS (
+ SELECT DISTINCT ON (skill."company_id", category.slug)
+ skill."company_id",
+ category.name,
+ category.slug
+ FROM "company_skills" AS skill
+ CROSS JOIN LATERAL (
+ SELECT
+ COALESCE(NULLIF(SPLIT_PART(skill."key", '/', 3), ''), 'other') AS name,
+ COALESCE(
+ NULLIF(TRIM(BOTH '-' FROM REGEXP_REPLACE(LOWER(COALESCE(NULLIF(SPLIT_PART(skill."key", '/', 3), ''), 'other')), '[^a-z0-9]+', '-', 'g')), ''),
+ 'other'
+ ) AS slug
+ ) AS category
+ WHERE skill."folder_id" IS NULL
+ AND (skill."key" LIKE 'paperclipai/bundled/%' OR skill."metadata"->>'sourceKind' = 'paperclip_bundled')
+ ORDER BY skill."company_id", category.slug, category.name
+)
+INSERT INTO "folders" ("company_id", "kind", "parent_id", "name", "slug", "system_key", "position")
+SELECT category."company_id", 'skill', root."id", category."name", category."slug", 'bundled:' || category."slug", 0
+FROM bundled_categories AS category
+JOIN "folders" AS root
+ ON root."company_id" = category."company_id"
+ AND root."kind" = 'skill'
+ AND root."system_key" = 'bundled'
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+UPDATE "company_skills" AS skill
+SET "folder_id" = category_folder."id", "updated_at" = now()
+FROM "folders" AS root
+JOIN "folders" AS category_folder
+ ON category_folder."company_id" = root."company_id"
+ AND category_folder."kind" = 'skill'
+ AND category_folder."parent_id" = root."id"
+WHERE skill."company_id" = root."company_id"
+ AND root."kind" = 'skill'
+ AND root."system_key" = 'bundled'
+ AND skill."folder_id" IS NULL
+ AND (skill."key" LIKE 'paperclipai/bundled/%' OR skill."metadata"->>'sourceKind' = 'paperclip_bundled')
+ AND category_folder."system_key" = 'bundled:' || COALESCE(
+ NULLIF(TRIM(BOTH '-' FROM REGEXP_REPLACE(LOWER(COALESCE(NULLIF(SPLIT_PART(skill."key", '/', 3), ''), 'other')), '[^a-z0-9]+', '-', 'g')), ''),
+ 'other'
+ );
+--> statement-breakpoint
+UPDATE "folders" AS folder
+SET "slug" = 'projects-' || LEFT(REPLACE(folder."id"::text, '-', ''), 8), "updated_at" = now()
+WHERE folder."kind" = 'skill'
+ AND folder."parent_id" IS NULL
+ AND folder."slug" = 'projects'
+ AND folder."system_key" IS NULL
+ AND EXISTS (
+ SELECT 1
+ FROM "company_skills" AS skill
+ WHERE skill."company_id" = folder."company_id"
+ AND skill."folder_id" IS NULL
+ AND skill."metadata"->>'sourceKind' = 'project_scan'
+ AND skill."metadata"->>'projectId' IS NOT NULL
+ );
+--> statement-breakpoint
+INSERT INTO "folders" ("company_id", "kind", "parent_id", "name", "slug", "system_key", "position")
+SELECT DISTINCT skill."company_id", 'skill', NULL::uuid, 'Projects', 'projects', 'projects', 1
+FROM "company_skills" AS skill
+WHERE skill."folder_id" IS NULL
+ AND skill."metadata"->>'sourceKind' = 'project_scan'
+ AND skill."metadata"->>'projectId' IS NOT NULL
+ AND NOT EXISTS (
+ SELECT 1 FROM "folders" AS folder
+ WHERE folder."company_id" = skill."company_id"
+ AND folder."kind" = 'skill'
+ AND folder."system_key" = 'projects'
+ )
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+WITH project_sources AS (
+ SELECT DISTINCT ON (skill."company_id", skill."metadata"->>'projectId')
+ skill."company_id",
+ skill."metadata"->>'projectId' AS project_id,
+ COALESCE(project."name", NULLIF(skill."metadata"->>'projectName', ''), 'Project') AS project_name
+ FROM "company_skills" AS skill
+ LEFT JOIN "projects" AS project
+ ON project."id"::text = skill."metadata"->>'projectId'
+ AND project."company_id" = skill."company_id"
+ WHERE skill."folder_id" IS NULL
+ AND skill."metadata"->>'sourceKind' = 'project_scan'
+ AND skill."metadata"->>'projectId' IS NOT NULL
+ ORDER BY skill."company_id", skill."metadata"->>'projectId', skill."id"
+), project_folders AS (
+ SELECT
+ source."company_id",
+ source.project_id,
+ source.project_name,
+ container."id" AS parent_id,
+ COALESCE(
+ NULLIF(TRIM(BOTH '-' FROM REGEXP_REPLACE(LOWER(source.project_name), '[^a-z0-9]+', '-', 'g')), ''),
+ 'project'
+ ) AS base_slug
+ FROM project_sources AS source
+ JOIN "folders" AS container
+ ON container."company_id" = source."company_id"
+ AND container."kind" = 'skill'
+ AND container."system_key" = 'projects'
+), ranked_project_folders AS (
+ SELECT
+ source.*,
+ ROW_NUMBER() OVER (
+ PARTITION BY source."company_id", source.parent_id, source.base_slug
+ ORDER BY source.project_id
+ ) AS duplicate_number
+ FROM project_folders AS source
+)
+INSERT INTO "folders" ("company_id", "kind", "parent_id", "name", "slug", "system_key", "position")
+SELECT
+ source."company_id",
+ 'skill',
+ source.parent_id,
+ source.project_name,
+ CASE
+ WHEN sibling."id" IS NULL AND source.duplicate_number = 1 THEN source.base_slug
+ ELSE source.base_slug || '-' || LEFT(source.project_id, 8)
+ END,
+ 'project:' || source.project_id,
+ 0
+FROM ranked_project_folders AS source
+LEFT JOIN "folders" AS sibling
+ ON sibling."company_id" = source."company_id"
+ AND sibling."kind" = 'skill'
+ AND sibling."parent_id" = source.parent_id
+ AND sibling."slug" = source.base_slug
+WHERE NOT EXISTS (
+ SELECT 1 FROM "folders" AS existing
+ WHERE existing."company_id" = source."company_id"
+ AND existing."kind" = 'skill'
+ AND existing."system_key" = 'project:' || source.project_id
+)
+ON CONFLICT DO NOTHING;
+--> statement-breakpoint
+UPDATE "company_skills" AS skill
+SET "folder_id" = project_folder."id", "updated_at" = now()
+FROM "folders" AS project_folder
+WHERE project_folder."company_id" = skill."company_id"
+ AND project_folder."kind" = 'skill'
+ AND project_folder."system_key" = 'project:' || (skill."metadata"->>'projectId')
+ AND skill."folder_id" IS NULL
+ AND skill."metadata"->>'sourceKind' = 'project_scan';
diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.json
index 9f778c178b..0e0c76170c 100644
--- a/packages/db/src/migrations/meta/_journal.json
+++ b/packages/db/src/migrations/meta/_journal.json
@@ -1205,6 +1205,20 @@
"when": 1784210753027,
"tag": "0173_inbox_policy_agent_cleanup",
"breakpoints": true
+ },
+ {
+ "idx": 174,
+ "version": "7",
+ "when": 1784210754027,
+ "tag": "0174_folders",
+ "breakpoints": true
+ },
+ {
+ "idx": 175,
+ "version": "7",
+ "when": 1784210755027,
+ "tag": "0175_nested_skill_folders",
+ "breakpoints": true
}
]
}
diff --git a/packages/db/src/nested-skill-folders-migration.test.ts b/packages/db/src/nested-skill-folders-migration.test.ts
new file mode 100644
index 0000000000..64ba1cd904
--- /dev/null
+++ b/packages/db/src/nested-skill-folders-migration.test.ts
@@ -0,0 +1,123 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { afterEach, describe, expect, it } from "vitest";
+import postgres from "postgres";
+import { applyPendingMigrations } from "./client.js";
+import {
+ getEmbeddedPostgresTestSupport,
+ startEmbeddedPostgresTestDatabase,
+} from "./test-embedded-postgres.js";
+
+const MIGRATION_FILE = "0175_nested_skill_folders.sql";
+const cleanups: Array<() => Promise<void>> = [];
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+async function migrationHash() {
+ const content = await fs.promises.readFile(new URL(`./migrations/${MIGRATION_FILE}`, import.meta.url), "utf8");
+ return createHash("sha256").update(content).digest("hex");
+}
+
+describeEmbeddedPostgres("nested skill folders migration", () => {
+ afterEach(async () => {
+ await Promise.all(cleanups.splice(0).map((cleanup) => cleanup()));
+ });
+
+ it("backfills existing folders, bundled skills, and project scan skills", async () => {
+ const database = await startEmbeddedPostgresTestDatabase("paperclip-nested-folders-migration-");
+ cleanups.push(database.cleanup);
+ const sql = postgres(database.connectionString, { max: 1 });
+ cleanups.push(async () => sql.end());
+
+ await sql`DELETE FROM "drizzle"."__drizzle_migrations" WHERE "hash" = ${await migrationHash()}`;
+ await sql`DROP INDEX IF EXISTS "folders_company_kind_parent_position_idx"`;
+ await sql`DROP INDEX IF EXISTS "folders_company_kind_system_key_uq"`;
+ await sql`DROP INDEX IF EXISTS "folders_company_kind_root_slug_uq"`;
+ await sql`DROP INDEX IF EXISTS "folders_company_kind_parent_slug_uq"`;
+ await sql`ALTER TABLE "folders" DROP CONSTRAINT IF EXISTS "folders_company_kind_parent_slug_uq"`;
+ await sql`ALTER TABLE "folders" DROP CONSTRAINT IF EXISTS "folders_parent_id_folders_id_fk"`;
+ await sql`ALTER TABLE "folders" DROP COLUMN IF EXISTS "system_key"`;
+ await sql`ALTER TABLE "folders" DROP COLUMN IF EXISTS "slug"`;
+ await sql`ALTER TABLE "folders" DROP COLUMN IF EXISTS "parent_id"`;
+ await sql`CREATE UNIQUE INDEX IF NOT EXISTS "folders_company_kind_name_uq" ON "folders" ("company_id", "kind", "name")`;
+
+ const companyId = randomUUID();
+ const projectId = randomUUID();
+ const existingFolderId = randomUUID();
+ const squattedBundledId = randomUUID();
+ const squattedProjectsId = randomUUID();
+ const bundledSkillId = randomUUID();
+ const projectSkillId = randomUUID();
+ const unfiledSkillId = randomUUID();
+ await sql`
+ INSERT INTO "companies" ("id", "name", "issue_prefix")
+ VALUES (${companyId}, 'Paperclip', 'PAP')
+ `;
+ await sql`
+ INSERT INTO "projects" ("id", "company_id", "name")
+ VALUES (${projectId}, ${companyId}, 'Agent Platform')
+ `;
+ await sql`
+ INSERT INTO "folders" ("id", "company_id", "kind", "name", "position")
+ VALUES
+ (${existingFolderId}, ${companyId}, 'skill', 'Team Notes', 0),
+ (${squattedBundledId}, ${companyId}, 'skill', 'Bundled', 1),
+ (${squattedProjectsId}, ${companyId}, 'skill', 'Projects', 2)
+ `;
+ await sql`
+ INSERT INTO "company_skills" ("id", "company_id", "key", "slug", "name", "markdown", "metadata")
+ VALUES
+ (${bundledSkillId}, ${companyId}, 'paperclipai/bundled/software-development/review', 'review', 'Review', '# Review', '{"sourceKind":"paperclip_bundled"}'::jsonb),
+ (${projectSkillId}, ${companyId}, 'company/project-skill', 'project-skill', 'Project Skill', '# Project', ${sql.json({ sourceKind: "project_scan", projectId, projectName: "Agent Platform" })}),
+ (${unfiledSkillId}, ${companyId}, 'company/unfiled', 'unfiled', 'Unfiled', '# Unfiled', '{}'::jsonb)
+ `;
+
+ await applyPendingMigrations(database.connectionString);
+
+ const folderRows = await sql<{
+ id: string;
+ parent_id: string | null;
+ slug: string;
+ system_key: string | null;
+ }[]>`
+ SELECT "id", "parent_id", "slug", "system_key"
+ FROM "folders"
+ WHERE "company_id" = ${companyId}
+ ORDER BY "slug"
+ `;
+ expect(folderRows).toEqual(expect.arrayContaining([
+ expect.objectContaining({ id: existingFolderId, slug: "team-notes", parent_id: null }),
+ expect.objectContaining({ id: squattedBundledId, slug: `bundled-${squattedBundledId.replace(/-/g, "").slice(0, 8)}`, system_key: null }),
+ expect.objectContaining({ id: squattedProjectsId, slug: `projects-${squattedProjectsId.replace(/-/g, "").slice(0, 8)}`, system_key: null }),
+ expect.objectContaining({ slug: "bundled", system_key: "bundled", parent_id: null }),
+ expect.objectContaining({ slug: "software-development", system_key: "bundled:software-development" }),
+ expect.objectContaining({ slug: "projects", system_key: "projects", parent_id: null }),
+ expect.objectContaining({ slug: "agent-platform", system_key: `project:${projectId}` }),
+ ]));
+
+ const skills = await sql<{ id: string; folder_id: string | null; folder_slug: string | null }[]>`
+ SELECT skill."id", skill."folder_id", folder."slug" AS folder_slug
+ FROM "company_skills" AS skill
+ LEFT JOIN "folders" AS folder ON folder."id" = skill."folder_id"
+ WHERE skill."company_id" = ${companyId}
+ ORDER BY skill."id"
+ `;
+ expect(skills.find((skill) => skill.id === bundledSkillId)).toMatchObject({ folder_slug: "software-development" });
+ expect(skills.find((skill) => skill.id === projectSkillId)).toMatchObject({ folder_slug: "agent-platform" });
+ expect(skills.find((skill) => skill.id === unfiledSkillId)).toMatchObject({ folder_id: null, folder_slug: null });
+
+ const indexes = await sql<{ indexname: string; indexdef: string }[]>`
+ SELECT "indexname", "indexdef"
+ FROM "pg_indexes"
+ WHERE "tablename" = 'folders'
+ AND "indexname" IN ('folders_company_kind_root_slug_uq', 'folders_company_kind_parent_slug_uq')
+ ORDER BY "indexname"
+ `;
+ expect(indexes).toHaveLength(2);
+ expect(indexes.map((index) => index.indexdef).join("\n")).not.toContain("NULLS NOT DISTINCT");
+ expect(indexes.find((index) => index.indexname === "folders_company_kind_root_slug_uq")?.indexdef)
+ .toContain("WHERE (parent_id IS NULL)");
+ expect(indexes.find((index) => index.indexname === "folders_company_kind_parent_slug_uq")?.indexdef)
+ .toContain("WHERE (parent_id IS NOT NULL)");
+ }, 30_000);
+});
diff --git a/packages/db/src/schema/company_skills.ts b/packages/db/src/schema/company_skills.ts
index 7e6ad7d1d5..b1fd42d2af 100644
--- a/packages/db/src/schema/company_skills.ts
+++ b/packages/db/src/schema/company_skills.ts
@@ -13,12 +13,14 @@ import type { CompanySkillFileInventoryEntry, CompanySkillSharingScope } from "@
import { agents } from "./agents.js";
import { companies } from "./companies.js";
import { issues } from "./issues.js";
+import { folders } from "./folders.js";
export const companySkills = pgTable(
"company_skills",
{
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id),
+ folderId: uuid("folder_id").references(() => folders.id, { onDelete: "set null" }),
key: text("key").notNull(),
slug: text("slug").notNull(),
name: text("name").notNull(),
@@ -51,6 +53,7 @@ export const companySkills = pgTable(
(table) => ({
companyKeyUniqueIdx: uniqueIndex("company_skills_company_key_idx").on(table.companyId, table.key),
companyNameIdx: index("company_skills_company_name_idx").on(table.companyId, table.name),
+ companyFolderIdx: index("company_skills_company_folder_idx").on(table.companyId, table.folderId),
companyCategoriesIdx: index("company_skills_company_categories_idx").using("gin", table.categories),
companySharingScopeIdx: index("company_skills_company_sharing_scope_idx").on(table.companyId, table.sharingScope),
companyCurrentVersionIdx: index("company_skills_company_current_version_idx").on(table.companyId, table.currentVersionId),
diff --git a/packages/db/src/schema/folders.ts b/packages/db/src/schema/folders.ts
new file mode 100644
index 0000000000..c186ad759a
--- /dev/null
+++ b/packages/db/src/schema/folders.ts
@@ -0,0 +1,54 @@
+import {
+ type AnyPgColumn,
+ index,
+ integer,
+ pgTable,
+ text,
+ timestamp,
+ uniqueIndex,
+ uuid,
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import { companies } from "./companies.js";
+import type { FolderKind } from "@paperclipai/shared";
+
+export const folders = pgTable(
+ "folders",
+ {
+ id: uuid("id").primaryKey().defaultRandom(),
+ companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+ kind: text("kind").$type<FolderKind>().notNull(),
+ parentId: uuid("parent_id").references((): AnyPgColumn => folders.id, { onDelete: "restrict" }),
+ name: text("name").notNull(),
+ slug: text("slug").notNull(),
+ systemKey: text("system_key"),
+ color: text("color"),
+ position: integer("position").notNull().default(0),
+ createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+ updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+ },
+ (table) => ({
+ companyKindPositionIdx: index("folders_company_kind_position_idx").on(
+ table.companyId,
+ table.kind,
+ table.position,
+ table.name,
+ ),
+ companyKindRootSlugUniqueIdx: uniqueIndex("folders_company_kind_root_slug_uq")
+ .on(table.companyId, table.kind, table.slug)
+ .where(sql`${table.parentId} is null`),
+ companyKindParentSlugUniqueIdx: uniqueIndex("folders_company_kind_parent_slug_uq")
+ .on(table.companyId, table.kind, table.parentId, table.slug)
+ .where(sql`${table.parentId} is not null`),
+ companyKindSystemKeyUniqueIdx: uniqueIndex("folders_company_kind_system_key_uq")
+ .on(table.companyId, table.kind, table.systemKey)
+ .where(sql`${table.systemKey} is not null`),
+ companyKindParentPositionIdx: index("folders_company_kind_parent_position_idx").on(
+ table.companyId,
+ table.kind,
+ table.parentId,
+ table.position,
+ table.name,
+ ),
+ }),
+);
diff --git a/packages/db/src/schema/index.ts b/packages/db/src/schema/index.ts
index ab9b93281f..2d03e463dc 100644
--- a/packages/db/src/schema/index.ts
+++ b/packages/db/src/schema/index.ts
@@ -35,6 +35,7 @@ export { workspaceOperations } from "./workspace_operations.js";
export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
export { projectGoals } from "./project_goals.js";
export { goals } from "./goals.js";
+export { folders } from "./folders.js";
export { issues } from "./issues.js";
export { issueWatchdogs } from "./issue_watchdogs.js";
export { issuePlanDecompositions } from "./issue_plan_decompositions.js";
diff --git a/packages/db/src/schema/routines.ts b/packages/db/src/schema/routines.ts
index ba65082c16..5b171f07e5 100644
--- a/packages/db/src/schema/routines.ts
+++ b/packages/db/src/schema/routines.ts
@@ -17,6 +17,7 @@ import { issues } from "./issues.js";
import { projects } from "./projects.js";
import { goals } from "./goals.js";
import { heartbeatRuns } from "./heartbeat_runs.js";
+import { folders } from "./folders.js";
import type { RoutineEnvConfig, RoutineRevisionSnapshotV1, RoutineVariable } from "@paperclipai/shared";
export const routines = pgTable(
@@ -25,6 +26,7 @@ export const routines = pgTable(
id: uuid("id").primaryKey().defaultRandom(),
companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
projectId: uuid("project_id").references(() => projects.id, { onDelete: "cascade" }),
+ folderId: uuid("folder_id").references(() => folders.id, { onDelete: "set null" }),
goalId: uuid("goal_id").references(() => goals.id, { onDelete: "set null" }),
parentIssueId: uuid("parent_issue_id").references(() => issues.id, { onDelete: "set null" }),
title: text("title").notNull(),
@@ -56,6 +58,7 @@ export const routines = pgTable(
companyStatusIdx: index("routines_company_status_idx").on(table.companyId, table.status),
companyAssigneeIdx: index("routines_company_assignee_idx").on(table.companyId, table.assigneeAgentId),
companyProjectIdx: index("routines_company_project_idx").on(table.companyId, table.projectId),
+ companyFolderIdx: index("routines_company_folder_idx").on(table.companyId, table.folderId),
companyResponsibleUserIdx: index("routines_company_responsible_user_idx").on(table.companyId, table.responsibleUserId),
companyOriginIdx: index("routines_company_origin_idx").on(table.companyId, table.originKind, table.originId),
}),
diff --git a/packages/shared/src/api.ts b/packages/shared/src/api.ts
index 1635ceb3d1..d8ff3bf3dd 100644
--- a/packages/shared/src/api.ts
+++ b/packages/shared/src/api.ts
@@ -3,6 +3,10 @@ export const API_PREFIX = "/api";
export const API = {
health: `${API_PREFIX}/health`,
companies: `${API_PREFIX}/companies`,
+ companyFolders: `${API_PREFIX}/companies/:companyId/folders`,
+ companyFolder: `${API_PREFIX}/companies/:companyId/folders/:folderId`,
+ companyFolderMove: `${API_PREFIX}/companies/:companyId/folders/:folderId/move`,
+ companyFolderItemMove: `${API_PREFIX}/companies/:companyId/folders/items/move`,
agents: `${API_PREFIX}/agents`,
projects: `${API_PREFIX}/projects`,
environments: `${API_PREFIX}/environments`,
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index cf991c13f3..93947c96fc 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -2101,12 +2101,40 @@ export type {
} from "./environment-support.js";
export type { AdapterRegistryEntry } from "./types/adapter-registry.js";
+export type {
+ FolderKind,
+ Folder,
+ FolderListItem,
+ FolderListResult,
+ CreateFolderRequest,
+ UpdateFolderRequest,
+ MoveFolderRequest,
+ MoveFolderItemRequest,
+ EnsureMySkillFolderRequest,
+} from "./types/folder.js";
export {
adapterRegistryEntrySchema,
adapterRegistrySchema,
type AdapterRegistryEntryParsed,
} from "./validators/adapter-registry.js";
+export {
+ folderKindSchema,
+ folderSlugSchema,
+ folderSchema,
+ folderListItemSchema,
+ folderListResultSchema,
+ createFolderSchema,
+ updateFolderSchema,
+ moveFolderSchema,
+ moveFolderItemSchema,
+ ensureMySkillFolderSchema,
+ type CreateFolder,
+ type UpdateFolder,
+ type MoveFolder,
+ type MoveFolderItem,
+ type EnsureMySkillFolder,
+} from "./validators/folder.js";
export {
environmentCustomImageTemplateKindSchema,
diff --git a/packages/shared/src/types/company-skill.ts b/packages/shared/src/types/company-skill.ts
index 29ea6e3ddc..6e195f0e29 100644
--- a/packages/shared/src/types/company-skill.ts
+++ b/packages/shared/src/types/company-skill.ts
@@ -34,6 +34,8 @@ export interface CompanySkillVersionFileInventoryEntry extends CompanySkillFileI
export interface CompanySkill {
id: string;
companyId: string;
+ folderId?: string | null;
+ folderPath?: string | null;
key: string;
slug: string;
name: string;
@@ -67,6 +69,8 @@ export interface CompanySkill {
export interface CompanySkillListItem {
id: string;
companyId: string;
+ folderId?: string | null;
+ folderPath?: string | null;
key: string;
slug: string;
name: string;
@@ -140,6 +144,8 @@ export interface CompanySkillListQuery {
categories?: string[];
scope?: CompanySkillSharingScope;
include?: CompanySkillListInclude[];
+ folderId?: string;
+ includeSubtree?: boolean;
}
export interface CompanySkillCategoryCount {
@@ -374,6 +380,7 @@ export interface CompanySkillProjectScanResult {
}
export interface CompanySkillCreateRequest {
+ folderId?: string | null;
name: string;
slug?: string | null;
description?: string | null;
diff --git a/packages/shared/src/types/folder.ts b/packages/shared/src/types/folder.ts
new file mode 100644
index 0000000000..451856a672
--- /dev/null
+++ b/packages/shared/src/types/folder.ts
@@ -0,0 +1,59 @@
+export type FolderKind = "routine" | "skill";
+
+export interface Folder {
+ id: string;
+ companyId: string;
+ kind: FolderKind;
+ parentId: string | null;
+ name: string;
+ slug: string;
+ systemKey: string | null;
+ path: string;
+ depth: number;
+ color: string | null;
+ position: number;
+ createdAt: Date;
+ updatedAt: Date;
+}
+
+export interface FolderListItem extends Folder {
+ itemCount: number;
+}
+
+export interface FolderListResult {
+ kind: FolderKind;
+ folders: FolderListItem[];
+ allCount: number;
+ unfiledCount: number;
+}
+
+export interface CreateFolderRequest {
+ kind: FolderKind;
+ parentId?: string | null;
+ name: string;
+ slug?: string | null;
+ color?: string | null;
+ position?: number | null;
+}
+
+export interface UpdateFolderRequest {
+ name?: string;
+ slug?: string;
+ color?: string | null;
+ position?: number;
+}
+
+export interface MoveFolderRequest {
+ parentId?: string | null;
+ position: number;
+}
+
+export interface EnsureMySkillFolderRequest {
+ slug?: string | null;
+}
+
+export interface MoveFolderItemRequest {
+ kind: FolderKind;
+ itemId: string;
+ folderId?: string | null;
+}
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index 74537a5a33..da48529ed3 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -163,6 +163,17 @@ export type {
CompanySkillInstallCatalogRequest,
CompanySkillInstallCatalogResult,
} from "./company-skill.js";
+export type {
+ FolderKind,
+ Folder,
+ FolderListItem,
+ FolderListResult,
+ CreateFolderRequest,
+ UpdateFolderRequest,
+ MoveFolderRequest,
+ MoveFolderItemRequest,
+ EnsureMySkillFolderRequest,
+} from "./folder.js";
export type {
CatalogTeamKind,
CatalogTeamTrustLevel,
diff --git a/packages/shared/src/types/routine.ts b/packages/shared/src/types/routine.ts
index 571d7492ef..bab97b6d4e 100644
--- a/packages/shared/src/types/routine.ts
+++ b/packages/shared/src/types/routine.ts
@@ -71,6 +71,7 @@ export interface Routine {
id: string;
companyId: string;
projectId: string | null;
+ folderId?: string | null;
goalId: string | null;
parentIssueId: string | null;
title: string;
diff --git a/packages/shared/src/validators/company-skill.ts b/packages/shared/src/validators/company-skill.ts
index f458efaf3c..ac3a61fd1a 100644
--- a/packages/shared/src/validators/company-skill.ts
+++ b/packages/shared/src/validators/company-skill.ts
@@ -20,6 +20,8 @@ export const companySkillVersionFileInventoryEntrySchema = companySkillFileInven
export const companySkillSchema = z.object({
id: z.string().uuid(),
companyId: z.string().uuid(),
+ folderId: z.string().uuid().nullable().optional(),
+ folderPath: z.string().nullable().optional(),
key: z.string().min(1),
slug: z.string().min(1),
name: z.string().min(1),
@@ -106,6 +108,8 @@ export const companySkillListQuerySchema = z.object({
categories: z.array(z.string().min(1)).optional(),
scope: companySkillSharingScopeSchema.optional(),
include: z.array(companySkillListIncludeSchema).optional(),
+ folderId: z.string().uuid().optional(),
+ includeSubtree: z.boolean().optional(),
});
export const companySkillCategoryCountSchema = z.object({
@@ -320,6 +324,7 @@ export const companySkillProjectScanResultSchema = z.object({
});
export const companySkillCreateSchema = z.object({
+ folderId: z.string().uuid().nullable().optional(),
name: z.string().min(1),
slug: z.string().min(1).nullable().optional(),
description: z.string().nullable().optional(),
diff --git a/packages/shared/src/validators/folder.ts b/packages/shared/src/validators/folder.ts
new file mode 100644
index 0000000000..4f3e231029
--- /dev/null
+++ b/packages/shared/src/validators/folder.ts
@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+export const folderKindSchema = z.enum(["routine", "skill"]);
+export const folderSlugSchema = z.string().trim().min(1).max(120).regex(
+ /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+ "Folder slug must contain only lowercase letters, numbers, and single hyphens",
+);
+
+export const folderSchema = z.object({
+ id: z.string().uuid(),
+ companyId: z.string().uuid(),
+ kind: folderKindSchema,
+ parentId: z.string().uuid().nullable(),
+ name: z.string().min(1),
+ slug: folderSlugSchema,
+ systemKey: z.string().nullable(),
+ path: z.string().min(1),
+ depth: z.number().int().min(1),
+ color: z.string().nullable(),
+ position: z.number().int(),
+ createdAt: z.coerce.date(),
+ updatedAt: z.coerce.date(),
+});
+
+export const folderListItemSchema = folderSchema.extend({
+ itemCount: z.number().int().nonnegative(),
+});
+
+export const folderListResultSchema = z.object({
+ kind: folderKindSchema,
+ folders: z.array(folderListItemSchema),
+ allCount: z.number().int().nonnegative(),
+ unfiledCount: z.number().int().nonnegative(),
+});
+
+export const createFolderSchema = z.object({
+ kind: folderKindSchema,
+ parentId: z.string().uuid().optional().nullable(),
+ name: z.string().trim().min(1).max(120),
+ slug: folderSlugSchema.optional().nullable(),
+ color: z.string().trim().min(1).max(80).optional().nullable(),
+ position: z.number().int().min(0).optional().nullable(),
+});
+
+export const updateFolderSchema = z.object({
+ name: z.string().trim().min(1).max(120).optional(),
+ slug: folderSlugSchema.optional(),
+ color: z.string().trim().min(1).max(80).optional().nullable(),
+ position: z.number().int().min(0).optional(),
+}).refine((value) => Object.keys(value).length > 0, {
+ message: "At least one folder field is required",
+});
+
+export const moveFolderSchema = z.object({
+ parentId: z.string().uuid().optional().nullable(),
+ position: z.number().int().min(0),
+});
+
+export const ensureMySkillFolderSchema = z.object({
+ slug: folderSlugSchema.optional().nullable(),
+}).default({});
+
+export const moveFolderItemSchema = z.object({
+ kind: folderKindSchema,
+ itemId: z.string().uuid(),
+ folderId: z.string().uuid().optional().nullable(),
+});
+
+export type CreateFolder = z.infer<typeof createFolderSchema>;
+export type UpdateFolder = z.infer<typeof updateFolderSchema>;
+export type MoveFolder = z.infer<typeof moveFolderSchema>;
+export type MoveFolderItem = z.infer<typeof moveFolderItemSchema>;
+export type EnsureMySkillFolder = z.infer<typeof ensureMySkillFolderSchema>;
diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts
index 58853af7a9..3594b922e5 100644
--- a/packages/shared/src/validators/index.ts
+++ b/packages/shared/src/validators/index.ts
@@ -194,6 +194,23 @@ export {
type CompanySkillInstallUpdate,
type CompanySkillReset,
} from "./company-skill.js";
+export {
+ folderKindSchema,
+ folderSlugSchema,
+ folderSchema,
+ folderListItemSchema,
+ folderListResultSchema,
+ createFolderSchema,
+ updateFolderSchema,
+ moveFolderSchema,
+ moveFolderItemSchema,
+ ensureMySkillFolderSchema,
+ type CreateFolder,
+ type UpdateFolder,
+ type MoveFolder,
+ type MoveFolderItem,
+ type EnsureMySkillFolder,
+} from "./folder.js";
export {
catalogTeamKindSchema,
catalogTeamTrustLevelSchema,
diff --git a/packages/shared/src/validators/routine.ts b/packages/shared/src/validators/routine.ts
index 56629340fd..f0e4a92851 100644
--- a/packages/shared/src/validators/routine.ts
+++ b/packages/shared/src/validators/routine.ts
@@ -61,6 +61,7 @@ export const routineVariableSchema = z.object({
export const createRoutineSchema = z.object({
projectId: z.string().uuid().optional().nullable(),
+ folderId: z.string().uuid().optional().nullable(),
goalId: z.string().uuid().optional().nullable(),
parentIssueId: z.string().uuid().optional().nullable(),
title: z.string().trim().min(1).max(200),
@@ -85,6 +86,7 @@ export const routineRevisionSnapshotRoutineV1Schema = z.object({
id: z.string().uuid(),
companyId: z.string().uuid(),
projectId: z.string().uuid().nullable(),
+ folderId: z.string().uuid().nullable().optional(),
goalId: z.string().uuid().nullable(),
parentIssueId: z.string().uuid().nullable(),
title: z.string().trim().min(1).max(200),
diff --git a/server/src/__tests__/company-skills-catalog-service.test.ts b/server/src/__tests__/company-skills-catalog-service.test.ts
index c2fbe60176..b2b6b54902 100644
--- a/server/src/__tests__/company-skills-catalog-service.test.ts
+++ b/server/src/__tests__/company-skills-catalog-service.test.ts
@@ -4,7 +4,7 @@ import path from "node:path";
import { promises as fs } from "node:fs";
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
import { and, eq } from "drizzle-orm";
-import { companies, companySkills, createDb } from "@paperclipai/db";
+import { companies, companySkills, createDb, folders } from "@paperclipai/db";
import {
getEmbeddedPostgresTestSupport,
startEmbeddedPostgresTestDatabase,
@@ -132,6 +132,7 @@ describeEmbeddedPostgres("companySkillService.installFromCatalog", () => {
afterEach(async () => {
await db.delete(companySkills);
+ await db.delete(folders);
await db.delete(companies);
await Promise.all(Array.from(cleanupDirs, (dir) => fs.rm(dir, { recursive: true, force: true })));
cleanupDirs.clear();
@@ -154,6 +155,7 @@ describeEmbeddedPostgres("companySkillService.installFromCatalog", () => {
expect(result.action).toBe("created");
expect(result.skill).toMatchObject({
companyId,
+ folderId: expect.any(String),
key: sampleCatalogSkill.key,
slug: sampleCatalogSkill.slug,
sourceType: "catalog",
@@ -182,6 +184,37 @@ describeEmbeddedPostgres("companySkillService.installFromCatalog", () => {
packageName: "@paperclipai/skills-catalog",
packageVersion: "0.3.1",
});
+ const folder = await db
+ .select()
+ .from(folders)
+ .where(eq(folders.id, result.skill.folderId!))
+ .then((rows) => rows[0]);
+ expect(folder).toMatchObject({
+ name: "Software Development",
+ slug: "software-development",
+ systemKey: "bundled:software-development",
+ });
+ });
+
+ it("repairs an existing unfiled Paperclip catalog skill during inventory refresh", async () => {
+ const companyId = await createCompany();
+ const installed = await svc.installFromCatalog(companyId, { catalogSkillId: sampleCatalogSkill.id });
+ await db
+ .update(companySkills)
+ .set({ folderId: null })
+ .where(eq(companySkills.id, installed.skill.id));
+
+ const listed = await svc.list(companyId);
+ const repaired = listed.find((skill) => skill.id === installed.skill.id);
+ const folder = repaired?.folderId
+ ? await db.select().from(folders).where(eq(folders.id, repaired.folderId)).then((rows) => rows[0])
+ : null;
+
+ expect(repaired?.folderId).toEqual(expect.any(String));
+ expect(folder).toMatchObject({
+ name: "Software Development",
+ systemKey: "bundled:software-development",
+ });
});
it("materializes catalog asset files without UTF-8 rewriting", async () => {
diff --git a/server/src/__tests__/company-skills-service.test.ts b/server/src/__tests__/company-skills-service.test.ts
index 2d6035146a..6df5bab4e6 100644
--- a/server/src/__tests__/company-skills-service.test.ts
+++ b/server/src/__tests__/company-skills-service.test.ts
@@ -11,6 +11,7 @@ import {
companySkillVersions,
companySkills,
createDb,
+ folders,
projects,
projectWorkspaces,
} from "@paperclipai/db";
@@ -19,6 +20,7 @@ import {
startEmbeddedPostgresTestDatabase,
} from "./helpers/embedded-postgres.js";
import { companySkillService } from "../services/company-skills.ts";
+import { folderService } from "../services/folders.js";
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
@@ -63,6 +65,7 @@ describeEmbeddedPostgres("companySkillService.list", () => {
await db.delete(companySkills);
await db.delete(projectWorkspaces);
await db.delete(projects);
+ await db.delete(folders);
await db.delete(companies);
await db.delete(authUsers);
await Promise.all(Array.from(cleanupDirs, (dir) => fs.rm(dir, { recursive: true, force: true })));
@@ -310,6 +313,13 @@ describeEmbeddedPostgres("companySkillService.list", () => {
const bundledSkill = initialList.find((skill) => skill.key.startsWith("paperclipai/paperclip/"));
expect(bundledSkill).toBeDefined();
if (!bundledSkill) throw new Error("Expected bundled Paperclip skills fixture");
+ const bundledFolder = bundledSkill.folderId
+ ? await db.select().from(folders).where(eq(folders.id, bundledSkill.folderId)).then((rows) => rows[0])
+ : null;
+ expect(bundledFolder).toMatchObject({
+ name: "Paperclip Core",
+ systemKey: "bundled:paperclip-core",
+ });
const preservedUpdatedAt = new Date("2026-01-01T00:00:00.000Z");
await db
@@ -323,6 +333,34 @@ describeEmbeddedPostgres("companySkillService.list", () => {
expect(refreshedSkill?.updatedAt.toISOString()).toBe(preservedUpdatedAt.toISOString());
});
+ it("repairs a squatted bundled root during bundled-skill list refresh", async () => {
+ const companyId = randomUUID();
+ await db.insert(companies).values({
+ id: companyId,
+ name: "Paperclip",
+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ });
+ const [squatted] = await db.insert(folders).values({
+ companyId,
+ kind: "skill",
+ parentId: null,
+ name: "User Bundled",
+ slug: "bundled",
+ position: 0,
+ }).returning();
+
+ const listed = await svc.list(companyId);
+ const folderRows = await db.select().from(folders).where(eq(folders.companyId, companyId));
+ const bundledRoot = folderRows.find((folder) => folder.systemKey === "bundled");
+ const repairedSquat = folderRows.find((folder) => folder.id === squatted!.id);
+
+ expect(listed.some((skill) => skill.key.startsWith("paperclipai/paperclip/"))).toBe(true);
+ expect(bundledRoot).toMatchObject({ slug: "bundled", parentId: null, systemKey: "bundled" });
+ expect(repairedSquat).toMatchObject({ name: "User Bundled", systemKey: null });
+ expect(repairedSquat?.slug).toMatch(/^bundled-[a-f0-9]{8}$/);
+ });
+
it("does not retouch bundled skills with stale missing-source metadata during list refresh", async () => {
const companyId = randomUUID();
await db.insert(companies).values({
@@ -686,6 +724,97 @@ describeEmbeddedPostgres("companySkillService.list", () => {
await expect(svc.categoryCounts(companyId)).resolves.toEqual([]);
});
+ it("filters by folder subtree, keeps search global, and returns canonical folder paths", async () => {
+ const companyId = randomUUID();
+ await db.insert(companies).values({
+ id: companyId,
+ name: "Paperclip",
+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ });
+ const folderSvc = folderService(db);
+ const engineering = await folderSvc.create(companyId, { kind: "skill", name: "Engineering" });
+ const reviews = await folderSvc.create(companyId, { kind: "skill", parentId: engineering.id, name: "Reviews" });
+ const operations = await folderSvc.create(companyId, { kind: "skill", name: "Operations" });
+
+ const reviewDir = await createManagedSkillDir(companyId, "review-");
+ const deployDir = await createManagedSkillDir(companyId, "deploy-");
+ await fs.writeFile(path.join(reviewDir, "SKILL.md"), "# Review\n", "utf8");
+ await fs.writeFile(path.join(deployDir, "SKILL.md"), "# Deploy\n", "utf8");
+ await db.insert(companySkills).values([
+ {
+ companyId,
+ folderId: reviews.id,
+ key: `company/${companyId}/review`,
+ slug: "review",
+ name: "Review",
+ markdown: "# Review",
+ sourceType: "local_path",
+ sourceLocator: reviewDir,
+ categories: ["engineering"],
+ },
+ {
+ companyId,
+ folderId: operations.id,
+ key: `company/${companyId}/deploy`,
+ slug: "deploy",
+ name: "Deploy",
+ markdown: "# Deploy",
+ sourceType: "local_path",
+ sourceLocator: deployDir,
+ categories: ["operations"],
+ },
+ ]);
+
+ await expect(svc.list(companyId, {
+ folderId: engineering.id,
+ includeSubtree: true,
+ categories: ["engineering"],
+ })).resolves.toEqual([
+ expect.objectContaining({ name: "Review", folderPath: "engineering/reviews" }),
+ ]);
+ await expect(svc.list(companyId, { folderId: engineering.id })).resolves.toEqual([]);
+ await expect(svc.list(companyId, { folderId: engineering.id, q: "deploy" })).resolves.toEqual([
+ expect.objectContaining({ name: "Deploy", folderPath: "operations" }),
+ ]);
+ const review = (await svc.list(companyId)).find((skill) => skill.name === "Review");
+ await expect(svc.getById(companyId, review!.id)).resolves.toMatchObject({
+ name: "Review",
+ folderPath: "engineering/reviews",
+ });
+ });
+
+ it("creates skills in same-company folders and rejects cross-company folder references", async () => {
+ const companyId = randomUUID();
+ const otherCompanyId = randomUUID();
+ await db.insert(companies).values([
+ {
+ id: companyId,
+ name: "Paperclip",
+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ },
+ {
+ id: otherCompanyId,
+ name: "Other",
+ issuePrefix: `T${otherCompanyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ },
+ ]);
+ const folderSvc = folderService(db);
+ const folder = await folderSvc.create(companyId, { kind: "skill", name: "Personal" });
+ const otherFolder = await folderSvc.create(otherCompanyId, { kind: "skill", name: "Private" });
+
+ await expect(svc.createLocalSkill(companyId, {
+ name: "Filed Skill",
+ folderId: folder.id,
+ })).resolves.toMatchObject({ folderId: folder.id });
+ await expect(svc.createLocalSkill(companyId, {
+ name: "Cross Company Skill",
+ folderId: otherFolder.id,
+ })).rejects.toMatchObject({ status: 404, message: "Skill folder not found" });
+ });
+
it("resolves detail by unique skill slug for Studio deep links", async () => {
const companyId = randomUUID();
await db.insert(companies).values({
@@ -2327,4 +2456,60 @@ describeEmbeddedPostgres("companySkillService.list", () => {
const persisted = await db.select().from(companySkills).where(eq(companySkills.companyId, companyId));
expect(persisted.filter((skill) => skill.metadata?.sourceKind === "project_scan")).toEqual([]);
});
+
+ it("files new project imports without moving them back on re-import", async () => {
+ const companyId = randomUUID();
+ const projectId = randomUUID();
+ const workspaceId = randomUUID();
+ const folderSvc = folderService(db);
+ const workspaceDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skill-project-folder-"));
+ cleanupDirs.add(workspaceDir);
+ const skillDir = path.join(workspaceDir, "skills", "project-skill");
+ const skillFile = path.join(skillDir, "SKILL.md");
+ await fs.mkdir(skillDir, { recursive: true });
+ await fs.writeFile(skillFile, "---\nname: Project Skill\n---\n\nInitial content.\n", "utf8");
+ await db.insert(companies).values({
+ id: companyId,
+ name: "Paperclip",
+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ });
+ await db.insert(projects).values({ id: projectId, companyId, name: "Skills Project" });
+ await db.insert(projectWorkspaces).values({
+ id: workspaceId,
+ companyId,
+ projectId,
+ name: "Primary",
+ cwd: workspaceDir,
+ isPrimary: true,
+ });
+
+ const firstImport = await svc.scanProjectWorkspaces(companyId, { projectIds: [projectId] });
+
+ expect(firstImport.imported).toHaveLength(1);
+ const importedSkill = firstImport.imported[0]!;
+ const projectFolder = await folderSvc.getFolder(companyId, importedSkill.folderId!);
+ expect(projectFolder).toMatchObject({
+ path: "projects/skills-project",
+ systemKey: `project:${projectId}`,
+ });
+
+ const personalFolder = await folderSvc.create(companyId, { kind: "skill", name: "Personal" });
+ await folderSvc.moveItem(companyId, {
+ kind: "skill",
+ itemId: importedSkill.id,
+ folderId: personalFolder.id,
+ });
+ await fs.writeFile(skillFile, "---\nname: Project Skill\n---\n\nUpdated content.\n", "utf8");
+
+ const reimport = await svc.scanProjectWorkspaces(companyId, { projectIds: [projectId] });
+
+ expect(reimport.updated).toHaveLength(1);
+ expect(reimport.updated[0]).toMatchObject({
+ id: importedSkill.id,
+ folderId: personalFolder.id,
+ markdown: expect.stringContaining("Updated content."),
+ });
+ });
+
});
diff --git a/server/src/__tests__/folders-routes.test.ts b/server/src/__tests__/folders-routes.test.ts
new file mode 100644
index 0000000000..f0eff113f0
--- /dev/null
+++ b/server/src/__tests__/folders-routes.test.ts
@@ -0,0 +1,74 @@
+import express from "express";
+import request from "supertest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockFolderService = vi.hoisted(() => ({
+ list: vi.fn(),
+ create: vi.fn(),
+ update: vi.fn(),
+ moveFolder: vi.fn(),
+ moveItem: vi.fn(),
+ deleteFolder: vi.fn(),
+}));
+
+const mockLogActivity = vi.hoisted(() => vi.fn());
+
+vi.mock("../services/index.js", () => ({
+ folderService: () => mockFolderService,
+ logActivity: mockLogActivity,
+}));
+
+async function createApp() {
+ vi.resetModules();
+ const [{ errorHandler }, { folderRoutes }] = await Promise.all([
+ import("../middleware/index.js") as Promise<typeof import("../middleware/index.js")>,
+ import("../routes/folders.js") as Promise<typeof import("../routes/folders.js")>,
+ ]);
+ const app = express();
+ app.use(express.json());
+ app.use((req, _res, next) => {
+ (req as any).actor = {
+ type: "board",
+ userId: "user-1",
+ companyIds: ["company-1"],
+ source: "session",
+ isInstanceAdmin: false,
+ };
+ next();
+ });
+ app.use("/api", folderRoutes({} as any));
+ app.use(errorHandler);
+ return app;
+}
+
+describe("folder routes", () => {
+ beforeEach(() => {
+ for (const mock of Object.values(mockFolderService)) mock.mockReset();
+ mockLogActivity.mockReset();
+ });
+
+ it("routes item moves to the item move handler before the folder reorder route", async () => {
+ mockFolderService.moveItem.mockResolvedValue({
+ kind: "routine",
+ itemId: "11111111-1111-4111-8111-111111111111",
+ folderId: "22222222-2222-4222-8222-222222222222",
+ });
+
+ const app = await createApp();
+ const res = await request(app)
+ .post("/api/companies/company-1/folders/items/move")
+ .send({
+ kind: "routine",
+ itemId: "11111111-1111-4111-8111-111111111111",
+ folderId: "22222222-2222-4222-8222-222222222222",
+ });
+
+ expect(res.status).toBe(200);
+ expect(mockFolderService.moveItem).toHaveBeenCalledWith("company-1", {
+ kind: "routine",
+ itemId: "11111111-1111-4111-8111-111111111111",
+ folderId: "22222222-2222-4222-8222-222222222222",
+ });
+ expect(mockFolderService.moveFolder).not.toHaveBeenCalled();
+ });
+});
diff --git a/server/src/__tests__/folders-service.test.ts b/server/src/__tests__/folders-service.test.ts
new file mode 100644
index 0000000000..a141f9965d
--- /dev/null
+++ b/server/src/__tests__/folders-service.test.ts
@@ -0,0 +1,447 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { eq, sql } from "drizzle-orm";
+import {
+ folderSlugSchema,
+} from "@paperclipai/shared";
+import {
+ companies,
+ companySkills,
+ createDb,
+ folders,
+ routines,
+} from "@paperclipai/db";
+import {
+ getEmbeddedPostgresTestSupport,
+ startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { folderService } from "../services/folders.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+describeEmbeddedPostgres("folder service", () => {
+ let db!: ReturnType<typeof createDb>;
+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+ beforeAll(async () => {
+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-folders-");
+ db = createDb(tempDb.connectionString);
+ }, 20_000);
+
+ afterEach(async () => {
+ await db.delete(companySkills);
+ await db.delete(routines);
+ await db.delete(folders);
+ await db.delete(companies);
+ });
+
+ afterAll(async () => {
+ await tempDb?.cleanup();
+ });
+
+ async function seedCompany() {
+ const companyId = randomUUID();
+ await db.insert(companies).values({
+ id: companyId,
+ name: "Paperclip",
+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ requireBoardApprovalForNewAgents: false,
+ defaultResponsibleUserId: "responsible-user",
+ });
+ return companyId;
+ }
+
+ async function seedRoutine(companyId: string, title: string, folderId?: string | null) {
+ const [routine] = await db
+ .insert(routines)
+ .values({
+ companyId,
+ title,
+ folderId: folderId ?? null,
+ responsibleUserId: "responsible-user",
+ })
+ .returning();
+ return routine!;
+ }
+
+ async function seedSkill(companyId: string, slug: string, folderId?: string | null) {
+ const [skill] = await db
+ .insert(companySkills)
+ .values({
+ companyId,
+ folderId: folderId ?? null,
+ key: `company/${companyId}/${slug}`,
+ slug,
+ name: slug,
+ markdown: `# ${slug}`,
+ })
+ .returning();
+ return skill!;
+ }
+
+ it("creates, updates, reorders, and lists routine folders with counts", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+
+ const reporting = await svc.create(companyId, {
+ kind: "routine",
+ name: "Reporting",
+ color: "green",
+ });
+ const cleanup = await svc.create(companyId, {
+ kind: "routine",
+ name: "Cleanup",
+ color: null,
+ });
+ await seedRoutine(companyId, "Filed", reporting.id);
+ await seedRoutine(companyId, "Unfiled");
+
+ const renamed = await svc.update(companyId, cleanup.id, { name: "Ops", color: "cyan" });
+ expect(renamed).toMatchObject({ id: cleanup.id, name: "Ops", color: "cyan" });
+ const cleared = await svc.update(companyId, cleanup.id, { color: null });
+ expect(cleared).toMatchObject({ id: cleanup.id, color: null });
+
+ const movedFolder = await svc.moveFolder(companyId, reporting.id, { position: 10 });
+ expect(movedFolder).toMatchObject({ id: reporting.id, position: 10 });
+
+ const listed = await svc.list(companyId, "routine");
+ expect(listed.allCount).toBe(2);
+ expect(listed.unfiledCount).toBe(1);
+ expect(listed.folders).toEqual([
+ expect.objectContaining({ id: cleanup.id, name: "Ops", itemCount: 0 }),
+ expect.objectContaining({ id: reporting.id, name: "Reporting", itemCount: 1 }),
+ ]);
+ });
+
+ it("moves routines and skills to folders and back to virtual Unfiled", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const routineFolder = await svc.create(companyId, { kind: "routine", name: "Reports" });
+ const skillFolder = await svc.create(companyId, { kind: "skill", name: "Runtime" });
+ const routine = await seedRoutine(companyId, "Daily report");
+ const skill = await seedSkill(companyId, "review");
+
+ await expect(svc.moveItem(companyId, {
+ kind: "routine",
+ itemId: routine.id,
+ folderId: routineFolder.id,
+ })).resolves.toEqual({ kind: "routine", itemId: routine.id, folderId: routineFolder.id });
+ await expect(svc.moveItem(companyId, {
+ kind: "skill",
+ itemId: skill.id,
+ folderId: skillFolder.id,
+ })).resolves.toEqual({ kind: "skill", itemId: skill.id, folderId: skillFolder.id });
+
+ await expect(svc.moveItem(companyId, {
+ kind: "routine",
+ itemId: routine.id,
+ folderId: null,
+ })).resolves.toEqual({ kind: "routine", itemId: routine.id, folderId: null });
+
+ const [updatedRoutine] = await db.select().from(routines).where(eq(routines.id, routine.id));
+ const [updatedSkill] = await db.select().from(companySkills).where(eq(companySkills.id, skill.id));
+ expect(updatedRoutine?.folderId).toBeNull();
+ expect(updatedSkill?.folderId).toBe(skillFolder.id);
+ });
+
+ it("rejects moving an item into a folder of the wrong kind", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const skillFolder = await svc.create(companyId, { kind: "skill", name: "Runtime" });
+ const routine = await seedRoutine(companyId, "Daily report");
+
+ await expect(svc.moveItem(companyId, {
+ kind: "routine",
+ itemId: routine.id,
+ folderId: skillFolder.id,
+ })).rejects.toMatchObject({
+ status: 422,
+ message: "Folder kind must match item kind",
+ });
+ });
+
+ it("deletes folders without deleting contents by moving items to Unfiled", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const folder = await svc.create(companyId, { kind: "routine", name: "Reports" });
+ const routine = await seedRoutine(companyId, "Daily report", folder.id);
+
+ const deleted = await svc.deleteFolder(companyId, folder.id);
+ expect(deleted).toMatchObject({ id: folder.id, name: "Reports" });
+
+ const [updatedRoutine] = await db.select().from(routines).where(eq(routines.id, routine.id));
+ expect(updatedRoutine?.folderId).toBeNull();
+ expect(await db.select().from(folders).where(eq(folders.id, folder.id))).toHaveLength(0);
+ });
+
+ it("computes canonical paths and updates descendant paths after rename and move", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const root = await svc.create(companyId, { kind: "skill", name: "Engineering" });
+ const child = await svc.create(companyId, { kind: "skill", parentId: root.id, name: "Code Review" });
+ const destination = await svc.create(companyId, { kind: "skill", name: "Operations" });
+
+ expect(child).toMatchObject({ path: "engineering/code-review", depth: 2 });
+ await svc.update(companyId, root.id, { name: "Product Engineering" });
+ expect(await svc.getFolder(companyId, child.id)).toMatchObject({
+ path: "product-engineering/code-review",
+ depth: 2,
+ });
+
+ await svc.moveFolder(companyId, child.id, { parentId: destination.id, position: 0 });
+ expect(await svc.getFolder(companyId, child.id)).toMatchObject({
+ parentId: destination.id,
+ path: "operations/code-review",
+ depth: 2,
+ });
+ });
+
+ it("rejects invalid slugs, cycles, and folders deeper than four levels", async () => {
+ expect(folderSlugSchema.safeParse("../escape").success).toBe(false);
+ expect(folderSlugSchema.safeParse("Valid Slug").success).toBe(false);
+ expect(folderSlugSchema.safeParse("valid-slug-2").success).toBe(true);
+
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const level1 = await svc.create(companyId, { kind: "skill", name: "Level 1" });
+ const level2 = await svc.create(companyId, { kind: "skill", parentId: level1.id, name: "Level 2" });
+ const level3 = await svc.create(companyId, { kind: "skill", parentId: level2.id, name: "Level 3" });
+ const level4 = await svc.create(companyId, { kind: "skill", parentId: level3.id, name: "Level 4" });
+
+ await expect(svc.create(companyId, {
+ kind: "skill",
+ parentId: level4.id,
+ name: "Level 5",
+ })).rejects.toMatchObject({ status: 422, message: "Folder depth cannot exceed 4" });
+ await expect(svc.moveFolder(companyId, level1.id, {
+ parentId: level3.id,
+ position: 0,
+ })).rejects.toMatchObject({ status: 422, message: "A folder cannot be moved into its own subtree" });
+ });
+
+ it("creates stable personal roots and protects bundled folders", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const personal = await svc.ensureMyFolder(companyId, "user-1", "Ada Lovelace");
+ const repeated = await svc.ensureMyFolder(companyId, "user-1", "Ada Lovelace");
+ const bundled = await svc.ensureBundledCategory(companyId, "software-development");
+
+ expect(repeated.id).toBe(personal.id);
+ expect(personal).toMatchObject({ systemKey: "my:user-1", path: "my/ada-lovelace", depth: 2 });
+ expect(bundled.path).toBe("bundled/software-development");
+ await expect(svc.create(companyId, {
+ kind: "skill",
+ parentId: bundled.id,
+ name: "Nested",
+ })).rejects.toMatchObject({ status: 403, message: "Bundled folders are read-only" });
+ await expect(svc.update(companyId, bundled.id, { name: "Changed" })).rejects.toMatchObject({ status: 403 });
+ });
+
+ it("heals legacy bundled category names without changing folder identity", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const legacy = await svc.ensureBundledCategory(companyId, "software-development");
+
+ const reconciled = await svc.ensureBundledCategory(companyId, "Software Development");
+
+ expect(reconciled).toMatchObject({
+ id: legacy.id,
+ name: "Software Development",
+ path: "bundled/software-development",
+ systemKey: "bundled:software-development",
+ });
+ });
+
+ it("creates reserved folders idempotently under concurrent requests", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+
+ const [personalA, personalB] = await Promise.all([
+ svc.ensureMyFolder(companyId, "user-1", "Ada Lovelace"),
+ svc.ensureMyFolder(companyId, "user-1", "Ada Lovelace"),
+ ]);
+ const [projectA, projectB] = await Promise.all([
+ svc.ensureProjectFolder(companyId, "project-1", "Core App"),
+ svc.ensureProjectFolder(companyId, "project-1", "Core App"),
+ ]);
+ const [bundledA, bundledB] = await Promise.all([
+ svc.ensureBundledCategory(companyId, "software-development"),
+ svc.ensureBundledCategory(companyId, "software-development"),
+ ]);
+
+ expect(personalA.id).toBe(personalB.id);
+ expect(projectA.id).toBe(projectB.id);
+ expect(bundledA.id).toBe(bundledB.id);
+ });
+
+ it("reserves system skill roots from manual create, update, and move", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+
+ for (const slug of ["bundled", "my", "projects"]) {
+ await expect(svc.create(companyId, {
+ kind: "skill",
+ name: slug,
+ slug,
+ })).rejects.toMatchObject({ status: 403, message: "Reserved skill folders are system-managed" });
+ }
+
+ const editable = await svc.create(companyId, { kind: "skill", name: "Editable" });
+ await expect(svc.update(companyId, editable.id, { slug: "bundled" })).rejects.toMatchObject({ status: 403 });
+
+ const parent = await svc.create(companyId, { kind: "skill", name: "Parent" });
+ const nestedReserved = await svc.create(companyId, { kind: "skill", parentId: parent.id, name: "Projects" });
+ await expect(svc.moveFolder(companyId, nestedReserved.id, { parentId: null, position: 0 })).rejects.toMatchObject({
+ status: 403,
+ message: "Reserved skill folders are system-managed",
+ });
+ });
+
+ it("allows only system helpers to create children under personal and project roots", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const personal = await svc.ensureMyFolder(companyId, "user-1", "Ada Lovelace");
+ const project = await svc.ensureProjectFolder(companyId, "project-1", "Core App");
+ const myRoot = await svc.getFolder(companyId, personal.parentId!);
+ const projectsRoot = await svc.getFolder(companyId, project.parentId!);
+ const movable = await svc.create(companyId, { kind: "skill", name: "Movable" });
+
+ expect(myRoot?.systemKey).toBe("my");
+ expect(projectsRoot?.systemKey).toBe("projects");
+ await expect(svc.create(companyId, {
+ kind: "skill",
+ parentId: myRoot!.id,
+ name: "Spoofed User",
+ })).rejects.toMatchObject({ status: 403 });
+ await expect(svc.moveFolder(companyId, movable.id, {
+ parentId: projectsRoot!.id,
+ position: 0,
+ })).rejects.toMatchObject({ status: 403 });
+ });
+
+ it("moves squatted roots aside instead of adopting them as system containers", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const [squattedMy, squattedProjects] = await db.insert(folders).values([
+ { companyId, kind: "skill", parentId: null, name: "Attacker My", slug: "my", position: 0 },
+ { companyId, kind: "skill", parentId: null, name: "Attacker Projects", slug: "projects", position: 1 },
+ ]).returning();
+
+ const personal = await svc.ensureMyFolder(companyId, "user-1", "Ada Lovelace");
+ const project = await svc.ensureProjectFolder(companyId, "project-1", "Core App");
+ const myRoot = await svc.getFolder(companyId, personal.parentId!);
+ const projectsRoot = await svc.getFolder(companyId, project.parentId!);
+ const repairedMy = await svc.getFolder(companyId, squattedMy!.id);
+ const repairedProjects = await svc.getFolder(companyId, squattedProjects!.id);
+
+ expect(myRoot).toMatchObject({ slug: "my", systemKey: "my" });
+ expect(projectsRoot).toMatchObject({ slug: "projects", systemKey: "projects" });
+ expect(repairedMy).toMatchObject({ name: "Attacker My", systemKey: null });
+ expect(repairedMy?.slug).toMatch(/^my-[a-f0-9]{8}$/);
+ expect(repairedProjects).toMatchObject({ name: "Attacker Projects", systemKey: null });
+ expect(repairedProjects?.slug).toMatch(/^projects-[a-f0-9]{8}$/);
+ });
+
+ it("suffixes system children when legacy rows squat personal and project slugs", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const initialPersonal = await svc.ensureMyFolder(companyId, "seed-user", "Seed User");
+ const initialProject = await svc.ensureProjectFolder(companyId, "seed-project", "Seed Project");
+ const myRootId = initialPersonal.parentId!;
+ const projectsRootId = initialProject.parentId!;
+ await db.insert(folders).values([
+ { companyId, kind: "skill", parentId: myRootId, name: "Ada Squat", slug: "ada-lovelace", position: 1 },
+ { companyId, kind: "skill", parentId: projectsRootId, name: "Core Squat", slug: "core-app", position: 1 },
+ ]);
+
+ const personal = await svc.ensureMyFolder(companyId, "user-12345678", "Ada Lovelace");
+ const project = await svc.ensureProjectFolder(companyId, "project-12345678", "Core App");
+
+ expect(personal).toMatchObject({ path: "my/ada-lovelace-user-12345678", systemKey: "my:user-12345678" });
+ expect(project).toMatchObject({ path: "projects/core-app-project-12345678", systemKey: "project:project-12345678" });
+ });
+
+ it("does not adopt a legacy category row under the bundled root", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const initialCategory = await svc.ensureBundledCategory(companyId, "initial");
+ const bundledRootId = initialCategory.parentId!;
+ const [squatted] = await db.insert(folders).values({
+ companyId,
+ kind: "skill",
+ parentId: bundledRootId,
+ name: "User Software Development",
+ slug: "software-development",
+ position: 1,
+ }).returning();
+
+ const category = await svc.ensureBundledCategory(companyId, "software-development");
+
+ expect(category).toMatchObject({
+ path: "bundled/software-development-bundled",
+ systemKey: "bundled:software-development",
+ });
+ expect(await svc.getFolder(companyId, squatted!.id)).toMatchObject({
+ path: "bundled/software-development",
+ systemKey: null,
+ });
+ });
+
+ it("serializes concurrent system folder ensures", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ await db.insert(folders).values({
+ companyId,
+ kind: "skill",
+ name: "Squatted My",
+ slug: "my",
+ position: 0,
+ });
+
+ const personalFolders = await Promise.all(
+ Array.from({ length: 8 }, () => svc.ensureMyFolder(companyId, "user-123", "Ada Lovelace")),
+ );
+
+ expect(new Set(personalFolders.map((folder) => folder.id)).size).toBe(1);
+ const rows = await db.select().from(folders).where(eq(folders.companyId, companyId));
+ expect(rows.filter((row) => row.systemKey === "my")).toHaveLength(1);
+ expect(rows.filter((row) => row.systemKey === "my:user-123")).toHaveLength(1);
+ expect(rows.find((row) => row.systemKey === null)).toMatchObject({ name: "Squatted My" });
+ });
+
+ it("rechecks nested folders after waiting for the company mutation lock", async () => {
+ const companyId = await seedCompany();
+ const svc = folderService(db);
+ const parent = await svc.create(companyId, { kind: "routine", name: "Parent" });
+ let releaseLock!: () => void;
+ let markLockAcquired!: () => void;
+ const lockAcquired = new Promise<void>((resolve) => { markLockAcquired = resolve; });
+ const holdLock = new Promise<void>((resolve) => { releaseLock = resolve; });
+ const lockKey = `paperclip:folders:${companyId}`;
+ const blocker = db.transaction(async (tx) => {
+ await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${lockKey}, 0))`);
+ markLockAcquired();
+ await holdLock;
+ });
+ await lockAcquired;
+
+ const deletion = svc.deleteFolder(companyId, parent.id);
+ await db.insert(folders).values({
+ companyId,
+ kind: "routine",
+ parentId: parent.id,
+ name: "Child",
+ slug: "child",
+ position: 0,
+ });
+ releaseLock();
+ await blocker;
+
+ await expect(deletion).rejects.toMatchObject({
+ status: 409,
+ message: "Move or delete nested folders first",
+ });
+ await expect(svc.getFolder(companyId, parent.id)).resolves.toMatchObject({ id: parent.id });
+ });
+});
diff --git a/server/src/__tests__/openapi-routes.test.ts b/server/src/__tests__/openapi-routes.test.ts
index 290b6ed6a1..33b3e1b218 100644
--- a/server/src/__tests__/openapi-routes.test.ts
+++ b/server/src/__tests__/openapi-routes.test.ts
@@ -30,6 +30,7 @@ const apiPrefixes: Record<string, string> = {
"environments.ts": "/api",
"execution-workspaces.ts": "/api",
"file-resources.ts": "/api",
+ "folders.ts": "/api",
"goals.ts": "/api",
"health.ts": "/api/health",
"inbox-dismissals.ts": "/api",
@@ -181,6 +182,10 @@ describe("openapi routes", () => {
name: { type: "string" },
},
});
+ expect(res.body.paths["/api/companies/{companyId}/folders"].post.responses["201"]).toBeDefined();
+ expect(res.body.paths["/api/companies/{companyId}/folders/items/move"].post.summary).toBe(
+ "Move an item into or out of a folder",
+ );
expect(JSON.stringify(res.body.paths["/api/tool-gateway/tools"].get)).not.toContain("sessionToken");
expect(JSON.stringify(res.body.paths["/api/tool-gateway/tools/call"].post)).not.toContain("sessionToken");
});
diff --git a/server/src/__tests__/routines-service.test.ts b/server/src/__tests__/routines-service.test.ts
index 9dccbabc0c..0cd39660f7 100644
--- a/server/src/__tests__/routines-service.test.ts
+++ b/server/src/__tests__/routines-service.test.ts
@@ -12,6 +12,7 @@ import {
documentRevisions,
documents,
executionWorkspaces,
+ folders,
heartbeatRuns,
instanceSettings,
issueInboxArchives,
@@ -68,6 +69,7 @@ describeEmbeddedPostgres("routine service live-execution coalescing", () => {
await db.delete(routineRuns);
await db.delete(routineTriggers);
await db.delete(routines);
+ await db.delete(folders);
await db.delete(routineDocuments);
await db.delete(documents);
await db.delete(documentRevisions);
@@ -271,6 +273,39 @@ describeEmbeddedPostgres("routine service live-execution coalescing", () => {
expect(allRoutines.map((entry) => entry.id)).toEqual(expect.arrayContaining([routine.id, otherRoutine.id]));
});
+ it("does not reveal folders owned by another company", async () => {
+ const { companyId, agentId, projectId, svc } = await seedFixture();
+ const otherCompanyId = randomUUID();
+ await db.insert(companies).values({
+ id: otherCompanyId,
+ name: "Other company",
+ issuePrefix: `T${otherCompanyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+ defaultResponsibleUserId: randomUUID(),
+ requireBoardApprovalForNewAgents: false,
+ });
+ const [otherFolder] = await db.insert(folders).values({
+ companyId: otherCompanyId,
+ kind: "routine",
+ name: "Private folder",
+ slug: "private-folder",
+ position: 0,
+ }).returning();
+
+ await expect(svc.create(companyId, {
+ projectId,
+ folderId: otherFolder!.id,
+ goalId: null,
+ parentIssueId: null,
+ title: "cross-company folder probe",
+ description: null,
+ assigneeAgentId: agentId,
+ priority: "medium",
+ status: "active",
+ concurrencyPolicy: "coalesce_if_active",
+ catchUpPolicy: "skip_missed",
+ }, {})).rejects.toMatchObject({ status: 404, message: "Folder not found" });
+ });
+
it("defaults activity gates to always at company scope", async () => {
const { routine } = await seedFixture();
diff --git a/server/src/app.ts b/server/src/app.ts
index 68663296a5..1af6fb930b 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -16,6 +16,7 @@ import { companyRoutes } from "./routes/companies.js";
import { companySkillRoutes } from "./routes/company-skills.js";
import { companySkillPolicyRoutes } from "./routes/company-skill-policy.js";
import { builtInAgentRoutes } from "./routes/built-in-agents.js";
+import { folderRoutes } from "./routes/folders.js";
import { teamsCatalogRoutes } from "./routes/teams-catalog.js";
import { agentRoutes } from "./routes/agents.js";
import { projectRoutes } from "./routes/projects.js";
@@ -235,6 +236,7 @@ export async function createApp(
api.use(openApiRoutes());
api.use("/companies", companyRoutes(db, opts.storageService));
api.use(llmRoutes(db));
+ api.use(folderRoutes(db));
api.use(companySkillRoutes(db));
api.use(companySkillPolicyRoutes(db));
api.use(builtInAgentRoutes(db));
diff --git a/server/src/routes/company-skills.ts b/server/src/routes/company-skills.ts
index 065f7b0464..7094d3a9a8 100644
--- a/server/src/routes/company-skills.ts
+++ b/server/src/routes/company-skills.ts
@@ -38,7 +38,7 @@ import {
listCatalogSkillsOrEmpty,
readCatalogSkillFile,
} from "../services/skills-catalog.js";
-import { forbidden, unauthorized } from "../errors.js";
+import { badRequest, forbidden, unauthorized } from "../errors.js";
import { assertAuthenticated, assertCompanyAccess, getActorInfo } from "./authz.js";
import { getTelemetryClient } from "../telemetry.js";
import {
@@ -115,6 +115,14 @@ export function companySkillRoutes(db: Db) {
return undefined;
}
+ function optionalQueryBoolean(value: unknown) {
+ const parsed = firstQueryString(value);
+ if (parsed === undefined) return undefined;
+ if (parsed === "true") return true;
+ if (parsed === "false") return false;
+ throw badRequest("Boolean query parameters must be true or false");
+ }
+
function queryStringArray(value: unknown): string[] {
if (typeof value === "string") return [value];
if (Array.isArray(value)) return value.filter((entry): entry is string => typeof entry === "string");
@@ -305,12 +313,17 @@ export function companySkillRoutes(db: Db) {
...queryStringArray(req.query.category),
...queryStringArray(req.query.categories),
...queryStringArray(req.query["categories[]"]),
+ ...queryStringArray(req.query.tag),
+ ...queryStringArray(req.query.tags),
+ ...queryStringArray(req.query["tags[]"]),
],
scope: firstQueryString(req.query.scope),
include: [
...queryStringArray(req.query.include),
...queryStringArray(req.query["include[]"]),
],
+ folderId: firstQueryString(req.query.folderId),
+ includeSubtree: optionalQueryBoolean(req.query.includeSubtree),
}));
res.json(result);
});
diff --git a/server/src/routes/folders.ts b/server/src/routes/folders.ts
new file mode 100644
index 0000000000..ad4859c166
--- /dev/null
+++ b/server/src/routes/folders.ts
@@ -0,0 +1,169 @@
+import { Router } from "express";
+import type { Db } from "@paperclipai/db";
+import {
+ createFolderSchema,
+ ensureMySkillFolderSchema,
+ folderKindSchema,
+ moveFolderItemSchema,
+ moveFolderSchema,
+ updateFolderSchema,
+} from "@paperclipai/shared";
+import { validate } from "../middleware/validate.js";
+import { badRequest, forbidden } from "../errors.js";
+import { folderService, logActivity } from "../services/index.js";
+import { assertCompanyAccess, getActorInfo } from "./authz.js";
+
+export function folderRoutes(db: Db) {
+ const router = Router();
+ const svc = folderService(db);
+
+ function parseKind(value: unknown) {
+ const result = folderKindSchema.safeParse(value);
+ if (!result.success) throw badRequest("Folder kind query parameter is required");
+ return result.data;
+ }
+
+ router.get("/companies/:companyId/folders", async (req, res) => {
+ const companyId = req.params.companyId as string;
+ assertCompanyAccess(req, companyId);
+ res.json(await svc.list(companyId, parseKind(req.query.kind)));
+ });
+
+ router.post("/companies/:companyId/folders", validate(createFolderSchema), async (req, res) => {
+ const companyId = req.params.companyId as string;
+ assertCompanyAccess(req, companyId);
+ const created = await svc.create(companyId, req.body);
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "folder.created",
+ entityType: "folder",
+ entityId: created.id,
+ details: { kind: created.kind, name: created.name, path: created.path, parentId: created.parentId, position: created.position },
+ });
+ res.status(201).json(created);
+ });
+
+ router.post(
+ "/companies/:companyId/folders/ensure-my",
+ validate(ensureMySkillFolderSchema),
+ async (req, res) => {
+ const companyId = req.params.companyId as string;
+ assertCompanyAccess(req, companyId);
+ if (req.actor.type !== "board" || !req.actor.userId) {
+ throw forbidden("A signed-in board user is required to create a personal skill folder");
+ }
+ const folder = await svc.ensureMyFolder(companyId, req.actor.userId, req.actor.userName ?? null, req.body.slug);
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "folder.personal_ensured",
+ entityType: "folder",
+ entityId: folder.id,
+ details: { path: folder.path, systemKey: folder.systemKey },
+ });
+ res.json(folder);
+ },
+ );
+
+ router.patch("/companies/:companyId/folders/:folderId", validate(updateFolderSchema), async (req, res) => {
+ const companyId = req.params.companyId as string;
+ const folderId = req.params.folderId as string;
+ assertCompanyAccess(req, companyId);
+ const updated = await svc.update(companyId, folderId, req.body);
+ if (!updated) {
+ res.status(404).json({ error: "Folder not found" });
+ return;
+ }
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "folder.updated",
+ entityType: "folder",
+ entityId: updated.id,
+ details: { kind: updated.kind, name: updated.name, path: updated.path, position: updated.position },
+ });
+ res.json(updated);
+ });
+
+ router.post("/companies/:companyId/folders/items/move", validate(moveFolderItemSchema), async (req, res) => {
+ const companyId = req.params.companyId as string;
+ assertCompanyAccess(req, companyId);
+ const moved = await svc.moveItem(companyId, req.body);
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "folder.item_moved",
+ entityType: req.body.kind === "routine" ? "routine" : "company_skill",
+ entityId: moved.itemId,
+ details: { kind: moved.kind, folderId: moved.folderId },
+ });
+ res.json(moved);
+ });
+
+ router.post("/companies/:companyId/folders/:folderId/move", validate(moveFolderSchema), async (req, res) => {
+ const companyId = req.params.companyId as string;
+ const folderId = req.params.folderId as string;
+ assertCompanyAccess(req, companyId);
+ const updated = await svc.moveFolder(companyId, folderId, req.body);
+ if (!updated) {
+ res.status(404).json({ error: "Folder not found" });
+ return;
+ }
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "folder.moved",
+ entityType: "folder",
+ entityId: updated.id,
+ details: { kind: updated.kind, parentId: updated.parentId, path: updated.path, position: updated.position },
+ });
+ res.json(updated);
+ });
+
+ router.delete("/companies/:companyId/folders/:folderId", async (req, res) => {
+ const companyId = req.params.companyId as string;
+ const folderId = req.params.folderId as string;
+ assertCompanyAccess(req, companyId);
+ const deleted = await svc.deleteFolder(companyId, folderId);
+ if (!deleted) {
+ res.status(404).json({ error: "Folder not found" });
+ return;
+ }
+ const actor = getActorInfo(req);
+ await logActivity(db, {
+ companyId,
+ actorType: actor.actorType,
+ actorId: actor.actorId,
+ agentId: actor.agentId,
+ runId: actor.runId,
+ action: "folder.deleted",
+ entityType: "folder",
+ entityId: deleted.id,
+ details: { kind: deleted.kind, name: deleted.name },
+ });
+ res.json({ deleted });
+ });
+
+ return router;
+}
diff --git a/server/src/routes/index.ts b/server/src/routes/index.ts
index 5c04a1c104..08b28f8897 100644
--- a/server/src/routes/index.ts
+++ b/server/src/routes/index.ts
@@ -3,6 +3,7 @@ export { companyRoutes } from "./companies.js";
export { companySkillRoutes } from "./company-skills.js";
export { companySkillPolicyRoutes } from "./company-skill-policy.js";
export { builtInAgentRoutes } from "./built-in-agents.js";
+export { folderRoutes } from "./folders.js";
export { teamsCatalogRoutes } from "./teams-catalog.js";
export { agentRoutes } from "./agents.js";
export { projectRoutes } from "./projects.js";
diff --git a/server/src/routes/openapi.ts b/server/src/routes/openapi.ts
index 90bf5c2086..dc50b8095e 100644
--- a/server/src/routes/openapi.ts
+++ b/server/src/routes/openapi.ts
@@ -47,6 +47,13 @@ import {
updateRoutineTriggerSchema,
rotateRoutineTriggerSecretSchema,
runRoutineSchema,
+ // Folders
+ createFolderSchema,
+ ensureMySkillFolderSchema,
+ folderKindSchema,
+ moveFolderItemSchema,
+ moveFolderSchema,
+ updateFolderSchema,
// Goal
createGoalSchema,
updateGoalSchema,
@@ -862,6 +869,8 @@ const CREATED_OPERATIONS = new Set([
"POST /api/companies/{companyId}/projects",
"POST /api/projects/{id}/workspaces",
"POST /api/companies/{companyId}/routines",
+ "POST /api/companies/{companyId}/folders",
+ "POST /api/companies/{companyId}/folders/ensure-my",
"POST /api/routines/{id}/triggers",
"POST /api/companies/{companyId}/secrets",
"POST /api/companies/{companyId}/user-secret-definitions",
@@ -5168,6 +5177,61 @@ for (const route of [
});
}
+registerCurrentRoute({
+ method: "get",
+ path: "/api/companies/{companyId}/folders",
+ tags: ["folders"],
+ summary: "List folders for a company item kind",
+ query: z.object({ kind: folderKindSchema }),
+});
+
+registerCurrentRoute({
+ method: "post",
+ path: "/api/companies/{companyId}/folders",
+ tags: ["folders"],
+ summary: "Create a folder",
+ body: createFolderSchema,
+});
+
+registerCurrentRoute({
+ method: "post",
+ path: "/api/companies/{companyId}/folders/ensure-my",
+ tags: ["folders"],
+ summary: "Ensure the current user's personal skill folder exists",
+ body: ensureMySkillFolderSchema,
+});
+
+registerCurrentRoute({
+ method: "patch",
+ path: "/api/companies/{companyId}/folders/{folderId}",
+ tags: ["folders"],
+ summary: "Update a folder",
+ body: updateFolderSchema,
+});
+
+registerCurrentRoute({
+ method: "post",
+ path: "/api/companies/{companyId}/folders/items/move",
+ tags: ["folders"],
+ summary: "Move an item into or out of a folder",
+ body: moveFolderItemSchema,
+});
+
+registerCurrentRoute({
+ method: "post",
+ path: "/api/companies/{companyId}/folders/{folderId}/move",
+ tags: ["folders"],
+ summary: "Move or reorder a folder",
+ body: moveFolderSchema,
+});
+
+registerCurrentRoute({
+ method: "delete",
+ path: "/api/companies/{companyId}/folders/{folderId}",
+ tags: ["folders"],
+ summary: "Delete a folder",
+});
+
registerCurrentRoute({
method: "get",
path: "/api/issues/{id}/cost-summary",
diff --git a/server/src/services/company-skills.ts b/server/src/services/company-skills.ts
index da6049b256..033f291ebf 100644
--- a/server/src/services/company-skills.ts
+++ b/server/src/services/company-skills.ts
@@ -97,6 +97,7 @@ import { issueDocumentSelect, mapIssueDocumentRow } from "./documents.js";
import { toIssueWorkProduct } from "./work-products.js";
import { projectService } from "./projects.js";
import { normalizePortablePath } from "./portable-path.js";
+import { folderService } from "./folders.js";
import {
copyCatalogSkillFile,
getCatalogPackageMetadata,
@@ -119,6 +120,7 @@ type CompanySkillListDbRow = Pick<
CompanySkillRow,
| "id"
| "companyId"
+ | "folderId"
| "key"
| "slug"
| "name"
@@ -151,6 +153,8 @@ type CompanySkillListRow = Pick<
CompanySkill,
| "id"
| "companyId"
+ | "folderId"
+ | "folderPath"
| "key"
| "slug"
| "name"
@@ -213,6 +217,7 @@ type ImportedSkill = {
type ImportedSkillPersistValues = Pick<
CompanySkill,
| "companyId"
+ | "folderId"
| "key"
| "slug"
| "name"
@@ -376,6 +381,7 @@ function selectCompanySkillColumns() {
return {
id: companySkills.id,
companyId: companySkills.companyId,
+ folderId: companySkills.folderId,
key: companySkills.key,
slug: companySkills.slug,
name: companySkills.name,
@@ -1208,6 +1214,26 @@ function isPaperclipBundledSkillKey(key: string) {
return key.startsWith("paperclipai/paperclip/");
}
+function paperclipBundledFolderCategory(key: string, metadata?: unknown) {
+ const keyParts = key.split("/");
+ if (keyParts[0] === "paperclipai" && keyParts[1] === "bundled" && keyParts[2]) {
+ return keyParts[2];
+ }
+ if (isPaperclipBundledSkillKey(key)) return "paperclip-core";
+ if (isPlainRecord(metadata) && asString(metadata.sourceKind) === "paperclip_bundled") {
+ return "paperclip-core";
+ }
+ return null;
+}
+
+function bundledFolderLabel(category: string) {
+ return category
+ .split(/[-_\s]+/)
+ .filter(Boolean)
+ .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+ .join(" ");
+}
+
function stripDerivedPaperclipBundledMetadata(key: string, metadata: unknown): unknown {
if (metadata === null || metadata === undefined) return {};
const comparable = stableJsonComparable(metadata);
@@ -1239,6 +1265,7 @@ function importedSkillPersistValuesMatchExisting(
values: ImportedSkillPersistValues,
) {
return existing.companyId === values.companyId
+ && existing.folderId === values.folderId
&& existing.key === values.key
&& existing.slug === values.slug
&& existing.name === values.name
@@ -2643,6 +2670,8 @@ function toCompanySkillListItem(skill: CompanySkillListRow, attachedAgentCount:
return {
id: skill.id,
companyId: skill.companyId,
+ folderId: skill.folderId,
+ folderPath: skill.folderPath ?? null,
key: skill.key,
slug: skill.slug,
name: skill.name,
@@ -2743,6 +2772,7 @@ async function listLastEditorsBySkillId(
}
export function companySkillService(db: Db) {
+ const folderSvc = folderService(db);
const agents = agentService(db);
const projects = projectService(db);
@@ -2798,6 +2828,39 @@ export function companySkillService(db: Db) {
return [];
}
+ async function reconcilePaperclipSkillFolders(companyId: string) {
+ const shippedSkills = await db
+ .select({
+ id: companySkills.id,
+ key: companySkills.key,
+ folderId: companySkills.folderId,
+ metadata: companySkills.metadata,
+ })
+ .from(companySkills)
+ .where(eq(companySkills.companyId, companyId))
+ .then((rows) => rows.flatMap((skill) => {
+ const category = paperclipBundledFolderCategory(skill.key, skill.metadata);
+ return category ? [{ ...skill, category }] : [];
+ }));
+ const foldersByCategory = new Map<string, Awaited<ReturnType<typeof folderSvc.ensureBundledCategory>>>();
+ for (const skill of shippedSkills) {
+ let folder = foldersByCategory.get(skill.category);
+ if (!folder) {
+ folder = await folderSvc.ensureBundledCategory(companyId, bundledFolderLabel(skill.category));
+ foldersByCategory.set(skill.category, folder);
+ }
+ if (skill.folderId === folder.id) continue;
+ await db
+ .update(companySkills)
+ .set({ folderId: folder.id, updatedAt: new Date() })
+ .where(and(eq(companySkills.companyId, companyId), eq(companySkills.id, skill.id)));
+ }
+ await folderSvc.pruneEmptyBundledCategories(
+ companyId,
+ Array.from(foldersByCategory.keys(), bundledFolderLabel),
+ );
+ }
+
async function reconcileLocalPathSkillSources(companyId: string) {
const rows = await db
.select({
@@ -2889,6 +2952,7 @@ export function companySkillService(db: Db) {
throw notFound("Company not found");
}
await ensureBundledSkills(companyId);
+ await reconcilePaperclipSkillFolders(companyId);
await reconcileLocalPathSkillSources(companyId);
})();
@@ -2904,10 +2968,11 @@ export function companySkillService(db: Db) {
async function list(companyId: string, query: CompanySkillListQuery = {}): Promise<CompanySkillListItem[]> {
await ensureSkillInventoryCurrent(companyId);
- const rows = await db
+ const [dbRows, folderListing] = await Promise.all([db
.select({
id: companySkills.id,
companyId: companySkills.companyId,
+ folderId: companySkills.folderId,
key: companySkills.key,
slug: companySkills.slug,
name: companySkills.name,
@@ -2939,7 +3004,21 @@ export function companySkillService(db: Db) {
.from(companySkills)
.where(eq(companySkills.companyId, companyId))
.orderBy(asc(companySkills.name), asc(companySkills.key))
- .then((entries) => entries.map((entry) => toCompanySkillListRow(entry as CompanySkillListDbRow)));
+ .then((entries) => entries.map((entry) => toCompanySkillListRow(entry as CompanySkillListDbRow))),
+ folderSvc.list(companyId, "skill"),
+ ]);
+ const folderPaths = new Map(folderListing.folders.map((folder) => [folder.id, folder.path]));
+ const rows = dbRows.map((skill) => ({
+ ...skill,
+ folderPath: skill.folderId ? folderPaths.get(skill.folderId) ?? null : null,
+ }));
+ let selectedFolderIds: Set<string> | null = null;
+ if (query.folderId) {
+ await folderSvc.validateSkillFolder(companyId, query.folderId, { allowBundled: true });
+ selectedFolderIds = query.includeSubtree
+ ? await folderSvc.descendantIds(companyId, "skill", query.folderId)
+ : new Set([query.folderId]);
+ }
const agentRows = await agents.list(companyId);
const q = query.q?.trim().toLowerCase() ?? "";
const categories = new Set(
@@ -2950,6 +3029,7 @@ export function companySkillService(db: Db) {
);
const filtered = rows.filter((skill) => {
if (query.scope && skill.sharingScope !== query.scope) return false;
+ if (!q && selectedFolderIds && (!skill.folderId || !selectedFolderIds.has(skill.folderId))) return false;
if (categories.size > 0 && !skill.categories.some((category) => categories.has(categoryLookupKey(category)))) return false;
if (q) {
const haystack = [
@@ -3032,7 +3112,7 @@ export function companySkillService(db: Db) {
.from(companySkills)
.where(and(eq(companySkills.companyId, companyId), eq(companySkills.id, id)))
.then((rows) => rows[0] ?? null);
- return row ? toCompanySkill(row) : null;
+ return row ? enrichFolderPath(companyId, toCompanySkill(row)) : null;
}
async function getByKey(companyId: string, key: string) {
@@ -3041,7 +3121,7 @@ export function companySkillService(db: Db) {
.from(companySkills)
.where(and(eq(companySkills.companyId, companyId), eq(companySkills.key, key)))
.then((rows) => rows[0] ?? null);
- return row ? toCompanySkill(row) : null;
+ return row ? enrichFolderPath(companyId, toCompanySkill(row)) : null;
}
async function getBySlugIfUnique(companyId: string, slug: string) {
@@ -3049,7 +3129,13 @@ export function companySkillService(db: Db) {
.select(selectCompanySkillColumns())
.from(companySkills)
.where(and(eq(companySkills.companyId, companyId), eq(companySkills.slug, slug)));
- return rows.length === 1 ? toCompanySkill(rows[0]!) : null;
+ return rows.length === 1 ? enrichFolderPath(companyId, toCompanySkill(rows[0]!)) : null;
+ }
+
+ async function enrichFolderPath(companyId: string, skill: CompanySkill): Promise<CompanySkill> {
+ if (!skill.folderId) return { ...skill, folderPath: null };
+ const folder = await folderSvc.getFolder(companyId, skill.folderId);
+ return { ...skill, folderPath: folder?.kind === "skill" ? folder.path : null };
}
async function getByRouteRef(companyId: string, ref: string) {
@@ -3927,6 +4013,7 @@ export function companySkillService(db: Db) {
input: CompanySkillCreateRequest,
actor: SkillActor | null = null,
): Promise<CompanySkill> {
+ if (input.folderId) await folderSvc.validateSkillFolder(companyId, input.folderId);
const slug = normalizeSkillSlug(input.slug ?? input.name) ?? "skill";
const key = `company/${companyId}/${slug}`;
const existing = await getByKey(companyId, key);
@@ -4013,6 +4100,7 @@ export function companySkillService(db: Db) {
authorName: normalizeStoreText(input.authorName, 200) ?? forkSource?.authorName ?? created.authorName,
homepageUrl: normalizeStoreText(input.homepageUrl, 2000) ?? forkSource?.homepageUrl ?? created.homepageUrl,
categories: input.categories ? normalizeCategoryList(input.categories) : forkSource?.categories ?? created.categories,
+ folderId: input.folderId ?? null,
sharingScope,
forkedFromSkillId: forkSource?.id ?? null,
forkedFromCompanyId: forkSource?.companyId ?? null,
@@ -4557,6 +4645,15 @@ export function companySkillService(db: Db) {
existingSkillId: existingBySource.id,
reason: "This skill is already installed from the same path.",
});
+ if (mode === "preview" || !selected) continue;
+ const persisted = (await upsertImportedSkills(companyId, [{
+ ...nextSkill,
+ key: existingBySource.key,
+ slug: existingBySource.slug,
+ }]))[0];
+ if (!persisted) continue;
+ updated.push(persisted);
+ upsertAcceptedSkill(persisted);
continue;
}
@@ -5050,6 +5147,10 @@ export function companySkillService(db: Db) {
}
const markdown = await fs.readFile(path.join(originSnapshotLocator, catalogSkill.entrypoint), "utf8");
const metadata = buildCatalogSkillMetadata(catalogSkill, existingByKey, originSnapshotLocator);
+ const bundledCategory = paperclipBundledFolderCategory(catalogSkill.key, metadata);
+ const bundledFolder = bundledCategory
+ ? await folderSvc.ensureBundledCategory(companyId, bundledFolderLabel(bundledCategory))
+ : null;
const parsed = parseFrontmatterMarkdown(markdown);
const storeMetadata = readSkillStoreMetadata(parsed.frontmatter, {
...metadata,
@@ -5057,6 +5158,7 @@ export function companySkillService(db: Db) {
});
const values = {
companyId,
+ folderId: bundledFolder?.id ?? existingByKey?.folderId ?? null,
key: catalogSkill.key,
slug,
name: catalogSkill.name,
@@ -5446,8 +5548,18 @@ export function companySkillService(db: Db) {
};
const parsed = parseFrontmatterMarkdown(skill.markdown);
const storeMetadata = readSkillStoreMetadata(parsed.frontmatter, metadata);
+ const bundledCategory = paperclipBundledFolderCategory(skill.key, incomingMeta);
+ const bundledFolder = bundledCategory
+ ? await folderSvc.ensureBundledCategory(companyId, bundledFolderLabel(bundledCategory))
+ : null;
+ const projectId = asString(incomingMeta.projectId);
+ const projectName = asString(incomingMeta.projectName);
+ const projectFolder = !existing && incomingKind === "project_scan" && projectId && projectName
+ ? await folderSvc.ensureProjectFolder(companyId, projectId, projectName)
+ : null;
const values: ImportedSkillPersistValues = {
companyId,
+ folderId: bundledFolder?.id ?? projectFolder?.id ?? existing?.folderId ?? null,
key: skill.key,
slug: skill.slug,
name: skill.name,
diff --git a/server/src/services/folders.ts b/server/src/services/folders.ts
new file mode 100644
index 0000000000..b16f6ac5c6
--- /dev/null
+++ b/server/src/services/folders.ts
@@ -0,0 +1,619 @@
+import { and, asc, eq, max, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { companySkills, folders, routines } from "@paperclipai/db";
+import type {
+ CreateFolder,
+ Folder,
+ FolderKind,
+ FolderListResult,
+ MoveFolder,
+ MoveFolderItem,
+ UpdateFolder,
+} from "@paperclipai/shared";
+import { conflict, forbidden, notFound, unprocessable } from "../errors.js";
+
+const MAX_FOLDER_DEPTH = 4;
+const RESERVED_ROOT_SLUGS = new Set(["bundled", "my", "projects"]);
+const RESERVED_CHILD_ROOT_SYSTEM_KEYS = new Set(["my", "projects"]);
+
+type FolderRow = typeof folders.$inferSelect;
+
+function isPostgresError(error: unknown, code: string) {
+ return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function normalizeName(name: string) {
+ return name.trim();
+}
+
+function normalizeColor(color: string | null | undefined) {
+ if (color === undefined) return undefined;
+ const trimmed = color?.trim() ?? "";
+ return trimmed.length > 0 ? trimmed : null;
+}
+
+export function normalizeFolderSlug(value: string) {
+ const slug = value
+ .normalize("NFKD")
+ .replace(/[\u0300-\u036f]/g, "")
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, "-")
+ .replace(/^-+|-+$/g, "")
+ .replace(/-+/g, "-");
+ return slug || "folder";
+}
+
+function buildFolderViews(rows: FolderRow[]) {
+ const byId = new Map(rows.map((row) => [row.id, row]));
+ const views = new Map<string, Folder>();
+ const visiting = new Set<string>();
+
+ function resolve(row: FolderRow): Folder {
+ const existing = views.get(row.id);
+ if (existing) return existing;
+ if (visiting.has(row.id)) throw unprocessable("Folder hierarchy contains a cycle");
+ visiting.add(row.id);
+ const parent = row.parentId ? byId.get(row.parentId) : null;
+ if (row.parentId && !parent) throw unprocessable("Folder hierarchy contains an invalid parent");
+ const parentView = parent ? resolve(parent) : null;
+ const view: Folder = {
+ ...row,
+ parentId: row.parentId ?? null,
+ systemKey: row.systemKey ?? null,
+ color: row.color ?? null,
+ path: parentView ? `${parentView.path}/${row.slug}` : row.slug,
+ depth: (parentView?.depth ?? 0) + 1,
+ };
+ visiting.delete(row.id);
+ views.set(row.id, view);
+ return view;
+ }
+
+ for (const row of rows) resolve(row);
+ return views;
+}
+
+export function folderService(db: Db, mutationLockHeld = false) {
+ async function withCompanyFolderLock<T>(companyId: string, operation: (lockedDb: Db) => Promise<T>) {
+ if (mutationLockHeld) return operation(db);
+ return db.transaction(async (tx) => {
+ await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`paperclip:folders:${companyId}`}, 0))`);
+ return operation(tx as unknown as Db);
+ });
+ }
+
+ async function getRows(companyId: string, kind: FolderKind) {
+ return db
+ .select()
+ .from(folders)
+ .where(and(eq(folders.companyId, companyId), eq(folders.kind, kind)))
+ .orderBy(asc(folders.position), asc(folders.name), asc(folders.id));
+ }
+
+ async function getFolderRow(companyId: string, folderId: string) {
+ return db
+ .select()
+ .from(folders)
+ .where(and(eq(folders.companyId, companyId), eq(folders.id, folderId)))
+ .then((rows) => rows[0] ?? null);
+ }
+
+ async function getFolder(companyId: string, folderId: string) {
+ const row = await getFolderRow(companyId, folderId);
+ if (!row) return null;
+ const views = buildFolderViews(await getRows(companyId, row.kind));
+ return views.get(row.id) ?? null;
+ }
+
+ async function assertNoSlugConflict(
+ companyId: string,
+ kind: FolderKind,
+ parentId: string | null,
+ slug: string,
+ excludeFolderId?: string,
+ ) {
+ const existing = await db
+ .select({ id: folders.id })
+ .from(folders)
+ .where(and(
+ eq(folders.companyId, companyId),
+ eq(folders.kind, kind),
+ parentId === null ? sql`${folders.parentId} is null` : eq(folders.parentId, parentId),
+ eq(folders.slug, slug),
+ ))
+ .then((rows) => rows[0] ?? null);
+ if (existing && existing.id !== excludeFolderId) {
+ throw conflict("Folder slug already exists under this parent");
+ }
+ }
+
+ async function nextPosition(companyId: string, kind: FolderKind, parentId: string | null) {
+ const row = await db
+ .select({ value: max(folders.position) })
+ .from(folders)
+ .where(and(
+ eq(folders.companyId, companyId),
+ eq(folders.kind, kind),
+ parentId === null ? sql`${folders.parentId} is null` : eq(folders.parentId, parentId),
+ ))
+ .then((rows) => rows[0] ?? null);
+ return Number(row?.value ?? -1) + 1;
+ }
+
+ async function routineCounts(companyId: string) {
+ return db
+ .select({ folderId: routines.folderId, count: sql<number>`count(*)::int` })
+ .from(routines)
+ .where(eq(routines.companyId, companyId))
+ .groupBy(routines.folderId);
+ }
+
+ async function skillCounts(companyId: string) {
+ return db
+ .select({ folderId: companySkills.folderId, count: sql<number>`count(*)::int` })
+ .from(companySkills)
+ .where(eq(companySkills.companyId, companyId))
+ .groupBy(companySkills.folderId);
+ }
+
+ async function list(companyId: string, kind: FolderKind): Promise<FolderListResult> {
+ const [folderRows, countRows] = await Promise.all([
+ getRows(companyId, kind),
+ kind === "routine" ? routineCounts(companyId) : skillCounts(companyId),
+ ]);
+ const views = buildFolderViews(folderRows);
+ const countsByFolderId = new Map<string | null, number>();
+ for (const row of countRows) countsByFolderId.set(row.folderId ?? null, Number(row.count ?? 0));
+ return {
+ kind,
+ folders: folderRows.map((row) => ({
+ ...views.get(row.id)!,
+ itemCount: countsByFolderId.get(row.id) ?? 0,
+ })),
+ allCount: Array.from(countsByFolderId.values()).reduce((sum, count) => sum + count, 0),
+ unfiledCount: countsByFolderId.get(null) ?? 0,
+ };
+ }
+
+ function isReservedRootSlug(kind: FolderKind, parentId: string | null, slug: string) {
+ return kind === "skill" && parentId === null && RESERVED_ROOT_SLUGS.has(slug);
+ }
+
+ async function isBundledFolder(companyId: string, folderId: string) {
+ let current = await getFolder(companyId, folderId);
+ const visited = new Set<string>();
+ while (current) {
+ if (current.systemKey === "bundled") return true;
+ if (!current.parentId || visited.has(current.id)) return false;
+ visited.add(current.id);
+ current = await getFolder(companyId, current.parentId);
+ }
+ return false;
+ }
+
+ async function assertMutableFolder(companyId: string, folder: Folder) {
+ if (folder.systemKey || await isBundledFolder(companyId, folder.id)) {
+ throw forbidden("System-managed folders cannot be changed");
+ }
+ }
+
+ async function validateParent(companyId: string, kind: FolderKind, parentId: string | null) {
+ if (!parentId) return null;
+ const parent = await getFolder(companyId, parentId);
+ if (!parent || parent.kind !== kind) throw notFound("Parent folder not found");
+ if (await isBundledFolder(companyId, parent.id)) throw forbidden("Bundled folders are read-only");
+ if (
+ parent.kind === "skill"
+ && parent.parentId === null
+ && (RESERVED_CHILD_ROOT_SYSTEM_KEYS.has(parent.systemKey ?? "") || RESERVED_CHILD_ROOT_SYSTEM_KEYS.has(parent.slug))
+ ) {
+ throw forbidden("Reserved skill folders are system-managed");
+ }
+ return parent;
+ }
+
+ async function create(companyId: string, input: CreateFolder): Promise<Folder> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).create(companyId, input));
+ }
+ const parentId = input.parentId ?? null;
+ const parent = await validateParent(companyId, input.kind, parentId);
+ if ((parent?.depth ?? 0) + 1 > MAX_FOLDER_DEPTH) {
+ throw unprocessable(`Folder depth cannot exceed ${MAX_FOLDER_DEPTH}`);
+ }
+ const name = normalizeName(input.name);
+ const slug = input.slug ?? normalizeFolderSlug(name);
+ if (isReservedRootSlug(input.kind, parentId, slug)) {
+ throw forbidden("Reserved skill folders are system-managed");
+ }
+ await assertNoSlugConflict(companyId, input.kind, parentId, slug);
+ const position = input.position ?? await nextPosition(companyId, input.kind, parentId);
+ let row: FolderRow;
+ try {
+ row = await db
+ .insert(folders)
+ .values({ companyId, kind: input.kind, parentId, name, slug, color: normalizeColor(input.color) ?? null, position })
+ .returning()
+ .then((rows) => rows[0]!);
+ } catch (error) {
+ if (isPostgresError(error, "23505")) throw conflict("Folder slug already exists under this parent");
+ throw error;
+ }
+ return (await getFolder(companyId, row.id))!;
+ }
+
+ async function update(companyId: string, folderId: string, patch: UpdateFolder): Promise<Folder | null> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).update(companyId, folderId, patch));
+ }
+ const existing = await getFolder(companyId, folderId);
+ if (!existing) return null;
+ await assertMutableFolder(companyId, existing);
+ const name = patch.name === undefined ? existing.name : normalizeName(patch.name);
+ const slug = patch.slug ?? (patch.name === undefined ? existing.slug : normalizeFolderSlug(name));
+ if (isReservedRootSlug(existing.kind, existing.parentId, slug)) {
+ throw forbidden("Reserved skill folders are system-managed");
+ }
+ await assertNoSlugConflict(companyId, existing.kind, existing.parentId, slug, existing.id);
+ try {
+ await db
+ .update(folders)
+ .set({
+ name,
+ slug,
+ color: patch.color === undefined ? existing.color : normalizeColor(patch.color),
+ position: patch.position ?? existing.position,
+ updatedAt: new Date(),
+ })
+ .where(and(eq(folders.companyId, companyId), eq(folders.id, folderId)));
+ } catch (error) {
+ if (isPostgresError(error, "23505")) throw conflict("Folder slug already exists under this parent");
+ throw error;
+ }
+ return getFolder(companyId, folderId);
+ }
+
+ function descendantIdsFromRows(rows: FolderRow[], folderId: string) {
+ if (!rows.some((row) => row.id === folderId)) throw notFound("Folder not found");
+ const children = new Map<string, string[]>();
+ for (const row of rows) {
+ if (!row.parentId) continue;
+ children.set(row.parentId, [...(children.get(row.parentId) ?? []), row.id]);
+ }
+ const result = new Set([folderId]);
+ const queue = [folderId];
+ while (queue.length > 0) {
+ const current = queue.shift()!;
+ for (const childId of children.get(current) ?? []) {
+ if (result.has(childId)) throw unprocessable("Folder hierarchy contains a cycle");
+ result.add(childId);
+ queue.push(childId);
+ }
+ }
+ return result;
+ }
+
+ async function descendantIds(companyId: string, kind: FolderKind, folderId: string) {
+ return descendantIdsFromRows(await getRows(companyId, kind), folderId);
+ }
+
+ async function moveFolder(companyId: string, folderId: string, input: MoveFolder): Promise<Folder | null> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).moveFolder(companyId, folderId, input));
+ }
+ const existing = await getFolder(companyId, folderId);
+ if (!existing) return null;
+ await assertMutableFolder(companyId, existing);
+ const parentId = input.parentId === undefined ? existing.parentId : input.parentId;
+ if (parentId === existing.id) throw unprocessable("A folder cannot be its own parent");
+ const rows = await getRows(companyId, existing.kind);
+ const descendants = descendantIdsFromRows(rows, existing.id);
+ if (parentId && descendants.has(parentId)) throw unprocessable("A folder cannot be moved into its own subtree");
+ const parent = await validateParent(companyId, existing.kind, parentId);
+ const views = buildFolderViews(rows);
+ const relativeDepth = Math.max(...Array.from(descendants).map((id) => views.get(id)!.depth - existing.depth + 1));
+ if ((parent?.depth ?? 0) + relativeDepth > MAX_FOLDER_DEPTH) {
+ throw unprocessable(`Folder depth cannot exceed ${MAX_FOLDER_DEPTH}`);
+ }
+ if (isReservedRootSlug(existing.kind, parentId, existing.slug)) {
+ throw forbidden("Reserved skill folders are system-managed");
+ }
+ await assertNoSlugConflict(companyId, existing.kind, parentId, existing.slug, existing.id);
+ try {
+ await db
+ .update(folders)
+ .set({ parentId, position: input.position, updatedAt: new Date() })
+ .where(and(eq(folders.companyId, companyId), eq(folders.id, folderId)));
+ } catch (error) {
+ if (isPostgresError(error, "23505")) throw conflict("Folder slug already exists under this parent");
+ if (isPostgresError(error, "23503")) throw conflict("Parent folder changed during move");
+ throw error;
+ }
+ return getFolder(companyId, folderId);
+ }
+
+ async function deleteFolder(companyId: string, folderId: string): Promise<Folder | null> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).deleteFolder(companyId, folderId));
+ }
+ const existing = await getFolder(companyId, folderId);
+ if (!existing) return null;
+ await assertMutableFolder(companyId, existing);
+ const child = await db
+ .select({ id: folders.id })
+ .from(folders)
+ .where(and(eq(folders.companyId, companyId), eq(folders.parentId, folderId)))
+ .then((rows) => rows[0] ?? null);
+ if (child) throw conflict("Move or delete nested folders first");
+ try {
+ await db.delete(folders).where(and(eq(folders.companyId, companyId), eq(folders.id, folderId)));
+ } catch (error) {
+ if (isPostgresError(error, "23503")) throw conflict("Move or delete nested folders first");
+ throw error;
+ }
+ return existing;
+ }
+
+ async function validateSkillFolder(companyId: string, folderId: string, options?: { allowBundled?: boolean }) {
+ const folder = await getFolder(companyId, folderId);
+ if (!folder || folder.kind !== "skill") throw notFound("Skill folder not found");
+ if (!options?.allowBundled && await isBundledFolder(companyId, folder.id)) {
+ throw forbidden("Bundled folders are read-only");
+ }
+ return folder;
+ }
+
+ async function moveItem(companyId: string, input: MoveFolderItem) {
+ if (input.folderId) {
+ const target = await getFolder(companyId, input.folderId);
+ if (!target) throw notFound("Folder not found");
+ if (target.kind !== input.kind) throw unprocessable("Folder kind must match item kind");
+ if (await isBundledFolder(companyId, target.id)) throw forbidden("Bundled folders are read-only");
+ }
+ if (input.kind === "routine") {
+ const row = await db
+ .update(routines)
+ .set({ folderId: input.folderId ?? null, updatedAt: new Date() })
+ .where(and(eq(routines.companyId, companyId), eq(routines.id, input.itemId)))
+ .returning({ id: routines.id, folderId: routines.folderId })
+ .then((rows) => rows[0] ?? null);
+ if (!row) throw notFound("Routine not found");
+ return { kind: input.kind, itemId: row.id, folderId: row.folderId ?? null };
+ }
+ const existing = await db
+ .select({ id: companySkills.id, folderId: companySkills.folderId })
+ .from(companySkills)
+ .where(and(eq(companySkills.companyId, companyId), eq(companySkills.id, input.itemId)))
+ .then((rows) => rows[0] ?? null);
+ if (!existing) throw notFound("Skill not found");
+ if (existing.folderId && await isBundledFolder(companyId, existing.folderId)) {
+ throw forbidden("Bundled skills cannot be moved");
+ }
+ const row = await db
+ .update(companySkills)
+ .set({ folderId: input.folderId ?? null, updatedAt: new Date() })
+ .where(and(eq(companySkills.companyId, companyId), eq(companySkills.id, input.itemId)))
+ .returning({ id: companySkills.id, folderId: companySkills.folderId })
+ .then((rows) => rows[0]!);
+ return { kind: input.kind, itemId: row.id, folderId: row.folderId ?? null };
+ }
+
+ async function uniqueSiblingSlug(companyId: string, parentId: string | null, baseSlug: string, stableSuffix: string) {
+ const siblingSlugs = new Set(await db
+ .select({ slug: folders.slug })
+ .from(folders)
+ .where(and(
+ eq(folders.companyId, companyId),
+ eq(folders.kind, "skill"),
+ parentId === null ? sql`${folders.parentId} is null` : eq(folders.parentId, parentId),
+ ))
+ .then((rows) => rows.map((row) => row.slug)));
+ if (!siblingSlugs.has(baseSlug)) return baseSlug;
+ const suffix = normalizeFolderSlug(stableSuffix).slice(0, 24);
+ let candidate = `${baseSlug}-${suffix}`;
+ let duplicateNumber = 2;
+ while (siblingSlugs.has(candidate)) {
+ candidate = `${baseSlug}-${suffix}-${duplicateNumber}`;
+ duplicateNumber += 1;
+ }
+ return candidate;
+ }
+
+ async function findSystemFolder(companyId: string, systemKey: string) {
+ return db
+ .select()
+ .from(folders)
+ .where(and(
+ eq(folders.companyId, companyId),
+ eq(folders.kind, "skill"),
+ eq(folders.systemKey, systemKey),
+ ))
+ .then((rows) => rows[0] ?? null);
+ }
+
+ async function insertSystemFolder(input: {
+ companyId: string;
+ parentId: string | null;
+ name: string;
+ slug: string;
+ systemKey: string;
+ }) {
+ const inserted = await db
+ .insert(folders)
+ .values({
+ companyId: input.companyId,
+ kind: "skill",
+ parentId: input.parentId,
+ name: input.name,
+ slug: input.slug,
+ systemKey: input.systemKey,
+ position: await nextPosition(input.companyId, "skill", input.parentId),
+ })
+ .onConflictDoNothing()
+ .returning({ id: folders.id })
+ .then((rows) => rows[0] ?? null);
+ if (inserted) return (await getFolder(input.companyId, inserted.id))!;
+ const existing = await findSystemFolder(input.companyId, input.systemKey);
+ return existing ? (await getFolder(input.companyId, existing.id))! : null;
+ }
+
+ async function ensureContainer(companyId: string, slug: "bundled" | "my" | "projects", name: string) {
+ for (let attempt = 0; attempt < 3; attempt += 1) {
+ const existingSystem = await findSystemFolder(companyId, slug);
+ if (existingSystem) return (await getFolder(companyId, existingSystem.id))!;
+ const squatted = await db
+ .select({ id: folders.id })
+ .from(folders)
+ .where(and(
+ eq(folders.companyId, companyId),
+ eq(folders.kind, "skill"),
+ sql`${folders.parentId} is null`,
+ eq(folders.slug, slug),
+ ))
+ .then((rows) => rows[0] ?? null);
+ if (squatted) {
+ await db
+ .update(folders)
+ .set({ slug: await uniqueSiblingSlug(companyId, null, slug, squatted.id.slice(0, 8)), updatedAt: new Date() })
+ .where(and(eq(folders.companyId, companyId), eq(folders.id, squatted.id)));
+ }
+ const created = await insertSystemFolder({ companyId, parentId: null, name, slug, systemKey: slug });
+ if (created) return created;
+ }
+ throw conflict(`Could not create ${name} folder`);
+ }
+
+ async function uniqueSystemSlug(
+ companyId: string,
+ parentId: string,
+ baseSlug: string,
+ systemKey: string,
+ stableSuffix = systemKey.split(":").at(-1) ?? systemKey,
+ ) {
+ const existingSystem = await db
+ .select({ id: folders.id })
+ .from(folders)
+ .where(and(eq(folders.companyId, companyId), eq(folders.kind, "skill"), eq(folders.systemKey, systemKey)))
+ .then((rows) => rows[0] ?? null);
+ if (existingSystem) return { id: existingSystem.id, slug: null };
+ return {
+ id: null,
+ slug: await uniqueSiblingSlug(companyId, parentId, baseSlug, stableSuffix),
+ };
+ }
+
+ async function ensureMyFolder(companyId: string, userId: string, userName: string | null, requestedSlug?: string | null): Promise<Folder> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).ensureMyFolder(companyId, userId, userName, requestedSlug));
+ }
+ const parent = await ensureContainer(companyId, "my", "My Skills");
+ const systemKey = `my:${userId}`;
+ for (let attempt = 0; attempt < 3; attempt += 1) {
+ const resolved = await uniqueSystemSlug(companyId, parent.id, requestedSlug ?? normalizeFolderSlug(userName ?? userId), systemKey);
+ if (resolved.id) return (await getFolder(companyId, resolved.id))!;
+ const created = await insertSystemFolder({
+ companyId,
+ parentId: parent.id,
+ name: userName?.trim() || "My Skills",
+ slug: resolved.slug!,
+ systemKey,
+ });
+ if (created) return created;
+ }
+ throw conflict("Could not create personal skill folder");
+ }
+
+ async function ensureProjectFolder(companyId: string, projectId: string, projectName: string): Promise<Folder> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).ensureProjectFolder(companyId, projectId, projectName));
+ }
+ const parent = await ensureContainer(companyId, "projects", "Projects");
+ const systemKey = `project:${projectId}`;
+ for (let attempt = 0; attempt < 3; attempt += 1) {
+ const resolved = await uniqueSystemSlug(companyId, parent.id, normalizeFolderSlug(projectName), systemKey);
+ if (resolved.id) return (await getFolder(companyId, resolved.id))!;
+ const created = await insertSystemFolder({
+ companyId,
+ parentId: parent.id,
+ name: projectName,
+ slug: resolved.slug!,
+ systemKey,
+ });
+ if (created) return created;
+ }
+ throw conflict("Could not create project skill folder");
+ }
+
+ async function ensureBundledCategory(companyId: string, category: string): Promise<Folder> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).ensureBundledCategory(companyId, category));
+ }
+ const root = await ensureContainer(companyId, "bundled", "Bundled");
+ const name = normalizeName(category);
+ const slug = normalizeFolderSlug(category);
+ const systemKey = `bundled:${slug}`;
+ for (let attempt = 0; attempt < 3; attempt += 1) {
+ const resolved = await uniqueSystemSlug(companyId, root.id, slug, systemKey, "bundled");
+ if (resolved.id) {
+ const existing = await getFolder(companyId, resolved.id);
+ if (!existing) continue;
+ if (existing.name === name) return existing;
+ await db
+ .update(folders)
+ .set({ name, updatedAt: new Date() })
+ .where(and(eq(folders.companyId, companyId), eq(folders.id, existing.id)));
+ return (await getFolder(companyId, existing.id))!;
+ }
+ const created = await insertSystemFolder({
+ companyId,
+ parentId: root.id,
+ name,
+ slug: resolved.slug!,
+ systemKey,
+ });
+ if (created) return created;
+ }
+ throw conflict("Could not create bundled skill folder");
+ }
+
+ async function pruneEmptyBundledCategories(companyId: string, retainedCategories: string[]): Promise<void> {
+ if (!mutationLockHeld) {
+ return withCompanyFolderLock(companyId, (lockedDb) => folderService(lockedDb, true).pruneEmptyBundledCategories(companyId, retainedCategories));
+ }
+ const root = await findSystemFolder(companyId, "bundled");
+ if (!root) return;
+ const rows = await getRows(companyId, "skill");
+ const retainedSystemKeys = new Set(
+ retainedCategories.map((category) => `bundled:${normalizeFolderSlug(category)}`),
+ );
+ const usedFolderIds = new Set(
+ await db
+ .select({ folderId: companySkills.folderId })
+ .from(companySkills)
+ .where(eq(companySkills.companyId, companyId))
+ .then((skills) => skills.flatMap((skill) => skill.folderId ? [skill.folderId] : [])),
+ );
+ const parentIds = new Set(rows.flatMap((row) => row.parentId ? [row.parentId] : []));
+ for (const row of rows) {
+ if (row.parentId !== root.id || !row.systemKey?.startsWith("bundled:")) continue;
+ if (retainedSystemKeys.has(row.systemKey) || usedFolderIds.has(row.id) || parentIds.has(row.id)) continue;
+ await db.delete(folders).where(and(eq(folders.companyId, companyId), eq(folders.id, row.id)));
+ }
+ }
+
+ return {
+ list,
+ create,
+ update,
+ moveFolder,
+ deleteFolder,
+ moveItem,
+ getFolder,
+ descendantIds,
+ validateSkillFolder,
+ ensureMyFolder,
+ ensureProjectFolder,
+ ensureBundledCategory,
+ pruneEmptyBundledCategories,
+ };
+}
diff --git a/server/src/services/index.ts b/server/src/services/index.ts
index b7745b470f..4a9977cfdd 100644
--- a/server/src/services/index.ts
+++ b/server/src/services/index.ts
@@ -5,6 +5,7 @@ export { companySearchExtractService } from "./company-search-extract.js";
export { feedbackService } from "./feedback.js";
export { companySkillService } from "./company-skills.js";
export { companySkillPolicyService, normalizeSkillPolicySourceType } from "./company-skill-policy.js";
+export { folderService } from "./folders.js";
export { agentService, deduplicateAgentName } from "./agents.js";
export {
builtInAgentService,
diff --git a/server/src/services/routines.ts b/server/src/services/routines.ts
index e64da63290..6152ba10cc 100644
--- a/server/src/services/routines.ts
+++ b/server/src/services/routines.ts
@@ -12,6 +12,7 @@ import {
documentRevisions,
documents,
executionWorkspaces,
+ folders,
goals,
heartbeatRuns,
issueInboxArchives,
@@ -974,6 +975,17 @@ export function routineService(
if (parentIssue.companyId !== companyId) throw unprocessable("Parent issue must belong to same company");
}
+ async function assertRoutineFolder(companyId: string, folderId: string | null | undefined) {
+ if (!folderId) return;
+ const folder = await db
+ .select({ id: folders.id, kind: folders.kind })
+ .from(folders)
+ .where(and(eq(folders.companyId, companyId), eq(folders.id, folderId)))
+ .then((rows) => rows[0] ?? null);
+ if (!folder) throw notFound("Folder not found");
+ if (folder.kind !== "routine") throw unprocessable("Folder kind must match routine");
+ }
+
async function listTriggersForRoutineIds(companyId: string, routineIds: string[]) {
if (routineIds.length === 0) return new Map<string, RoutineTrigger[]>();
const rows = await db
@@ -2066,6 +2078,7 @@ export function routineService(
create: async (companyId: string, input: CreateRoutine, actor: Actor): Promise<Routine> => {
await assertProject(companyId, input.projectId ?? null);
+ await assertRoutineFolder(companyId, input.folderId ?? null);
await assertAssignableAgent(db, companyId, input.assigneeAgentId ?? null, { kind: "routine" });
if (input.goalId) await assertGoal(companyId, input.goalId);
if (input.parentIssueId) await assertParentIssue(companyId, input.parentIssueId);
@@ -2092,6 +2105,7 @@ export function routineService(
.values({
companyId,
projectId: input.projectId ?? null,
+ folderId: input.folderId ?? null,
goalId: input.goalId ?? null,
parentIssueId: input.parentIssueId ?? null,
title: input.title,
@@ -2130,6 +2144,7 @@ export function routineService(
const existing = await getRoutineById(id);
if (!existing) return null;
const nextProjectId = patch.projectId === undefined ? existing.projectId : patch.projectId;
+ const nextFolderId = patch.folderId === undefined ? existing.folderId : patch.folderId;
const nextAssigneeAgentId = patch.assigneeAgentId === undefined ? existing.assigneeAgentId : patch.assigneeAgentId;
const nextTitle = patch.title ?? existing.title;
const nextDescription = patch.description === undefined ? existing.description : patch.description;
@@ -2153,6 +2168,7 @@ export function routineService(
patch.variables === undefined ? existing.variables : sanitizeRoutineVariableInputs(patch.variables),
);
if (patch.projectId !== undefined) await assertProject(existing.companyId, nextProjectId);
+ if (patch.folderId !== undefined) await assertRoutineFolder(existing.companyId, nextFolderId);
if (patch.assigneeAgentId !== undefined || patch.status === "active") {
await assertAssignableAgent(db, existing.companyId, nextAssigneeAgentId, { kind: "routine" });
}
@@ -2202,6 +2218,7 @@ export function routineService(
const candidate: RoutineRow = {
...locked,
projectId: nextProjectId,
+ folderId: nextFolderId,
goalId: patch.goalId === undefined ? locked.goalId : patch.goalId,
parentIssueId: patch.parentIssueId === undefined ? locked.parentIssueId : patch.parentIssueId,
title: nextTitle,
@@ -2218,8 +2235,20 @@ export function routineService(
updatedByUserId: actor.userId ?? null,
};
+ const folderChanged = patch.folderId !== undefined && locked.folderId !== candidate.folderId;
if (locked.latestRevisionId && routineCurrentFieldsMatch(locked, candidate)) {
- return locked;
+ if (!folderChanged) return locked;
+ const [updated] = await txDb
+ .update(routines)
+ .set({
+ folderId: candidate.folderId,
+ updatedByAgentId: actor.agentId ?? null,
+ updatedByUserId: actor.userId ?? null,
+ updatedAt: new Date(),
+ })
+ .where(eq(routines.id, id))
+ .returning();
+ return updated ?? locked;
}
const nextSnapshot = await buildRoutineRevisionSnapshot(txDb, candidate);
@@ -2252,6 +2281,7 @@ export function routineService(
.update(routines)
.set({
projectId: candidate.projectId,
+ folderId: candidate.folderId,
goalId: candidate.goalId,
parentIssueId: candidate.parentIssueId,
title: candidate.title,
diff --git a/ui/src/api/folders.ts b/ui/src/api/folders.ts
new file mode 100644
index 0000000000..97bab9d34c
--- /dev/null
+++ b/ui/src/api/folders.ts
@@ -0,0 +1,39 @@
+import type {
+ CreateFolderRequest,
+ EnsureMySkillFolderRequest,
+ Folder,
+ FolderKind,
+ FolderListResult,
+ MoveFolderItemRequest,
+ MoveFolderRequest,
+ UpdateFolderRequest,
+} from "@paperclipai/shared";
+import { api } from "./client";
+
+export const foldersApi = {
+ list: (companyId: string, kind: FolderKind) =>
+ api.get<FolderListResult>(`/companies/${encodeURIComponent(companyId)}/folders?kind=${kind}`),
+ create: (companyId: string, payload: CreateFolderRequest) =>
+ api.post<Folder>(`/companies/${encodeURIComponent(companyId)}/folders`, payload),
+ ensureMy: (companyId: string, payload: EnsureMySkillFolderRequest = {}) =>
+ api.post<Folder>(`/companies/${encodeURIComponent(companyId)}/folders/ensure-my`, payload),
+ update: (companyId: string, folderId: string, payload: UpdateFolderRequest) =>
+ api.patch<Folder>(
+ `/companies/${encodeURIComponent(companyId)}/folders/${encodeURIComponent(folderId)}`,
+ payload,
+ ),
+ moveFolder: (companyId: string, folderId: string, payload: MoveFolderRequest) =>
+ api.post<Folder>(
+ `/companies/${encodeURIComponent(companyId)}/folders/${encodeURIComponent(folderId)}/move`,
+ payload,
+ ),
+ moveItem: (companyId: string, payload: MoveFolderItemRequest) =>
+ api.post<MoveFolderItemRequest>(
+ `/companies/${encodeURIComponent(companyId)}/folders/items/move`,
+ payload,
+ ),
+ delete: (companyId: string, folderId: string) =>
+ api.delete<{ deleted: Folder }>(
+ `/companies/${encodeURIComponent(companyId)}/folders/${encodeURIComponent(folderId)}`,
+ ),
+};
diff --git a/ui/src/components/RoutineList.tsx b/ui/src/components/RoutineList.tsx
index f2cf986cc5..29604651c1 100644
--- a/ui/src/components/RoutineList.tsx
+++ b/ui/src/components/RoutineList.tsx
@@ -64,6 +64,10 @@ export function RoutineListRow<TRoutine extends RoutineListRowItem>({
disableToggle = false,
hideArchiveAction = false,
divider = true,
+ selected = false,
+ selectMode = false,
+ extraMenuItems,
+ onSelectChange,
onRunNow,
onToggleEnabled,
onToggleArchived,
@@ -83,6 +87,10 @@ export function RoutineListRow<TRoutine extends RoutineListRowItem>({
hideArchiveAction?: boolean;
/** Render a bottom divider between consecutive rows. Off when the group is its own card. */
divider?: boolean;
+ selected?: boolean;
+ selectMode?: boolean;
+ extraMenuItems?: ReactNode;
+ onSelectChange?: (routine: TRoutine, selected: boolean) => void;
onRunNow: (routine: TRoutine) => void;
onToggleEnabled: (routine: TRoutine, enabled: boolean) => void;
onToggleArchived?: (routine: TRoutine) => void;
@@ -102,6 +110,23 @@ export function RoutineListRow<TRoutine extends RoutineListRowItem>({
divider ? " border-b border-border last:border-b-0" : ""
}`}
>
+ {selectMode ? (
+ <div
+ className="flex items-start pt-0.5 sm:pt-1"
+ onClick={(event) => {
+ event.preventDefault();
+ event.stopPropagation();
+ }}
+ >
+ <input
+ type="checkbox"
+ className="h-4 w-4 rounded border-border"
+ checked={selected}
+ aria-label={`Select ${routine.title}`}
+ onChange={(event) => onSelectChange?.(routine, event.target.checked)}
+ />
+ </div>
+ ) : null}
<div className="min-w-0 flex-1 space-y-1.5">
<div className="flex flex-wrap items-center gap-2">
<span className="truncate text-sm font-medium">{routine.title}</span>
@@ -178,6 +203,12 @@ export function RoutineListRow<TRoutine extends RoutineListRowItem>({
>
{runningRoutineId === routine.id ? "Running..." : "Run now"}
</DropdownMenuItem>
+ {extraMenuItems ? (
+ <>
+ <DropdownMenuSeparator />
+ {extraMenuItems}
+ </>
+ ) : null}
<DropdownMenuSeparator />
<DropdownMenuItem
onClick={() => onToggleEnabled(routine, enabled)}
diff --git a/ui/src/components/folders/FolderControls.test.tsx b/ui/src/components/folders/FolderControls.test.tsx
new file mode 100644
index 0000000000..d68324b2cd
--- /dev/null
+++ b/ui/src/components/folders/FolderControls.test.tsx
@@ -0,0 +1,480 @@
+// @vitest-environment jsdom
+
+import { flushSync } from "react-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { FolderListResult } from "@paperclipai/shared";
+import {
+ AllUnfiledBanner,
+ BulkBar,
+ DeleteFolderDialog,
+ FolderFormDialog,
+ FolderRail,
+ MobileFolderSheet,
+ MoveToMenu,
+ folderSearchValue,
+ normalizeFolderSelection,
+} from "./FolderControls";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+if (!globalThis.PointerEvent) {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (globalThis as any).PointerEvent = MouseEvent;
+}
+if (!Element.prototype.hasPointerCapture) {
+ Element.prototype.hasPointerCapture = () => false;
+}
+if (!Element.prototype.scrollIntoView) {
+ Element.prototype.scrollIntoView = () => undefined;
+}
+
+function act(callback: () => void | Promise<void>) {
+ let result: void | Promise<void> | undefined;
+ flushSync(() => {
+ result = callback();
+ });
+ return result;
+}
+
+const folderResult: FolderListResult = {
+ kind: "routine",
+ allCount: 4,
+ unfiledCount: 1,
+ folders: [
+ {
+ id: "folder-reporting",
+ companyId: "company-1",
+ kind: "routine",
+ parentId: null,
+ name: "Reporting",
+ slug: "reporting",
+ systemKey: null,
+ path: "reporting",
+ depth: 1,
+ color: "indigo",
+ position: 0,
+ itemCount: 3,
+ createdAt: new Date("2026-07-01T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-01T00:00:00.000Z"),
+ },
+ ],
+};
+
+const skillFolderResult: FolderListResult = {
+ kind: "skill",
+ allCount: 8,
+ unfiledCount: 1,
+ folders: [
+ {
+ ...folderResult.folders[0]!,
+ id: "my",
+ kind: "skill",
+ name: "my",
+ slug: "my",
+ systemKey: "my",
+ path: "my",
+ itemCount: 1,
+ },
+ {
+ ...folderResult.folders[0]!,
+ id: "engineering",
+ kind: "skill",
+ name: "Engineering",
+ slug: "engineering",
+ path: "engineering",
+ itemCount: 3,
+ },
+ {
+ ...folderResult.folders[0]!,
+ id: "code-review",
+ kind: "skill",
+ parentId: "engineering",
+ name: "Code Review",
+ slug: "code-review",
+ path: "engineering/code-review",
+ depth: 2,
+ itemCount: 2,
+ },
+ {
+ ...folderResult.folders[0]!,
+ id: "projects",
+ kind: "skill",
+ name: "projects",
+ slug: "projects",
+ systemKey: "projects",
+ path: "projects",
+ itemCount: 2,
+ },
+ {
+ ...folderResult.folders[0]!,
+ id: "bundled",
+ kind: "skill",
+ name: "bundled",
+ slug: "bundled",
+ systemKey: "bundled",
+ path: "bundled",
+ itemCount: 1,
+ },
+ ],
+};
+
+describe("FolderControls", () => {
+ let container: HTMLDivElement;
+ let root: Root | null;
+
+ beforeEach(() => {
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = null;
+ });
+
+ afterEach(() => {
+ if (root) {
+ act(() => {
+ root?.unmount();
+ });
+ }
+ container.remove();
+ document.body.innerHTML = "";
+ });
+
+ it("normalizes URL selection values for folder persistence", () => {
+ expect(normalizeFolderSelection(null)).toBe("all");
+ expect(normalizeFolderSelection("unfiled")).toBe("unfiled");
+ expect(normalizeFolderSelection("folder-reporting")).toBe("folder-reporting");
+ expect(folderSearchValue("all")).toBe("");
+ expect(folderSearchValue("unfiled")).toBe("unfiled");
+ expect(folderSearchValue("folder-reporting")).toBe("folder-reporting");
+ });
+
+ it("renders All, user folders, and Unfiled with counts and selection callbacks", () => {
+ const onSelect = vi.fn();
+ root = createRoot(container);
+
+ act(() => {
+ root?.render(
+ <FolderRail
+ result={folderResult}
+ selection="all"
+ itemLabelPlural="routines"
+ allLabel="All routines"
+ onSelect={onSelect}
+ onCreate={vi.fn()}
+ onRename={vi.fn()}
+ onEdit={vi.fn()}
+ onDelete={vi.fn()}
+ />,
+ );
+ });
+
+ expect(container.textContent).toContain("All routines");
+ expect(container.textContent).toContain("Reporting");
+ expect(container.textContent).toContain("Unfiled");
+ expect(container.textContent).toContain("4");
+ expect(container.textContent).toContain("3");
+ expect(container.textContent).toContain("1");
+
+ const reportingButton = Array.from(container.querySelectorAll("button")).find((button) =>
+ button.textContent?.includes("Reporting"),
+ );
+ expect(reportingButton).toBeTruthy();
+
+ act(() => {
+ reportingButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+
+ expect(onSelect).toHaveBeenCalledWith("folder-reporting");
+ });
+
+ it("marks the active row with aria-current, including virtual Unfiled", () => {
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <FolderRail
+ result={folderResult}
+ selection="unfiled"
+ itemLabelPlural="routines"
+ allLabel="All routines"
+ onSelect={vi.fn()}
+ onCreate={vi.fn()}
+ onRename={vi.fn()}
+ onEdit={vi.fn()}
+ onDelete={vi.fn()}
+ />,
+ );
+ });
+
+ const current = container.querySelector('[aria-current="page"]');
+ expect(current?.textContent).toContain("Unfiled");
+ });
+
+ it("renames a folder inline via double-click and Enter", () => {
+ const onRename = vi.fn();
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <FolderRail
+ result={folderResult}
+ selection="all"
+ itemLabelPlural="routines"
+ allLabel="All routines"
+ onSelect={vi.fn()}
+ onCreate={vi.fn()}
+ onRename={onRename}
+ onEdit={vi.fn()}
+ onDelete={vi.fn()}
+ />,
+ );
+ });
+
+ const nameButton = Array.from(container.querySelectorAll("button")).find((button) =>
+ button.textContent?.includes("Reporting"),
+ );
+ act(() => {
+ nameButton?.dispatchEvent(new MouseEvent("dblclick", { bubbles: true, cancelable: true }));
+ });
+
+ const input = container.querySelector<HTMLInputElement>("input");
+ expect(input).toBeTruthy();
+ expect(input?.value).toBe("Reporting");
+
+ act(() => {
+ if (!input) return;
+ const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+ setter?.call(input, "Monthly reports");
+ input.dispatchEvent(new Event("input", { bubbles: true }));
+ });
+ act(() => {
+ input?.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+ });
+
+ expect(onRename).toHaveBeenCalledWith(folderResult.folders[0], "Monthly reports");
+ });
+
+ it("moves via MoveToMenu: Unfiled, a folder, and new-folder chaining", () => {
+ const onMove = vi.fn();
+ const onCreateAndMove = vi.fn();
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <DropdownMenu open modal={false}>
+ <DropdownMenuTrigger asChild>
+ <button type="button">Row actions</button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent>
+ <MoveToMenu
+ folders={folderResult.folders}
+ currentFolderId={null}
+ onMove={onMove}
+ onCreateAndMove={onCreateAndMove}
+ />
+ </DropdownMenuContent>
+ </DropdownMenu>,
+ );
+ });
+
+ const subTrigger = Array.from(document.querySelectorAll("[data-radix-collection-item]")).find(
+ (element) => element.textContent?.includes("Move to"),
+ );
+ expect(subTrigger).toBeTruthy();
+ act(() => {
+ subTrigger?.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }));
+ });
+
+ const menuItems = Array.from(document.querySelectorAll('[role="menuitem"]'));
+ const unfiledItem = menuItems.find((element) => element.textContent?.includes("Unfiled"));
+ const folderItem = menuItems.find((element) => element.textContent?.includes("Reporting"));
+ const newFolderItem = menuItems.find((element) => element.textContent?.includes("New folder"));
+ expect(unfiledItem).toBeTruthy();
+ expect(folderItem).toBeTruthy();
+ expect(newFolderItem).toBeTruthy();
+
+ act(() => {
+ unfiledItem?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+ expect(onMove).toHaveBeenCalledWith(null);
+
+ act(() => {
+ folderItem?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+ expect(onMove).toHaveBeenCalledWith("folder-reporting");
+
+ act(() => {
+ newFolderItem?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+ expect(onCreateAndMove).toHaveBeenCalled();
+ });
+
+ it("creates a folder through FolderFormDialog and disables submit on empty name", () => {
+ const onSubmit = vi.fn();
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <FolderFormDialog
+ open
+ kind="routine"
+ folder={null}
+ onOpenChange={vi.fn()}
+ onSubmit={onSubmit}
+ />,
+ );
+ });
+
+ const submit = Array.from(document.querySelectorAll("button")).find(
+ (button) => button.textContent === "Create folder",
+ ) as HTMLButtonElement | undefined;
+ expect(submit).toBeTruthy();
+ expect(submit?.disabled).toBe(true);
+
+ const nameInput = document.querySelector<HTMLInputElement>("#folder-name");
+ act(() => {
+ if (!nameInput) return;
+ const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+ setter?.call(nameInput, "Reporting");
+ nameInput.dispatchEvent(new Event("input", { bubbles: true }));
+ });
+
+ expect(submit?.disabled).toBe(false);
+ act(() => {
+ submit?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+ expect(onSubmit).toHaveBeenCalledWith({ name: "Reporting", color: expect.any(String) });
+ });
+
+ it("states the forgiving delete behavior and confirms", () => {
+ const onConfirm = vi.fn();
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <DeleteFolderDialog
+ open
+ folder={folderResult.folders[0]!}
+ itemLabelPlural="routines"
+ onOpenChange={vi.fn()}
+ onConfirm={onConfirm}
+ />,
+ );
+ });
+
+ expect(document.body.textContent).toContain("3 routines in this folder won't be deleted");
+ expect(document.body.textContent).toContain("They'll move to Unfiled");
+
+ const confirmButton = Array.from(document.querySelectorAll("button")).find(
+ (button) => button.textContent === "Delete folder",
+ );
+ act(() => {
+ confirmButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+ expect(onConfirm).toHaveBeenCalled();
+ });
+
+ it("selects a folder from the mobile sheet and dismisses", () => {
+ const onSelect = vi.fn();
+ const onOpenChange = vi.fn();
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <MobileFolderSheet
+ open
+ onOpenChange={onOpenChange}
+ result={folderResult}
+ selection="all"
+ allLabel="All routines"
+ itemLabelPlural="Routines"
+ onSelect={onSelect}
+ onCreate={vi.fn()}
+ />,
+ );
+ });
+
+ expect(document.body.textContent).toContain("All routines");
+ expect(document.body.textContent).toContain("Unfiled");
+
+ const reportingRow = Array.from(document.querySelectorAll("button")).find(
+ (button) => button.textContent?.includes("Reporting"),
+ );
+ act(() => {
+ reportingRow?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+
+ expect(onSelect).toHaveBeenCalledWith("folder-reporting");
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+
+ it("preserves skill root grouping and child hierarchy in the mobile sheet", () => {
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <MobileFolderSheet
+ open
+ onOpenChange={vi.fn()}
+ result={skillFolderResult}
+ selection="all"
+ allLabel="All skills"
+ itemLabelPlural="Skills"
+ onSelect={vi.fn()}
+ onCreate={vi.fn()}
+ />,
+ );
+ });
+
+ const body = document.body.textContent ?? "";
+ expect(body.indexOf("My Skills")).toBeLessThan(body.indexOf("Company"));
+ expect(body.indexOf("Company")).toBeLessThan(body.indexOf("Engineering"));
+ expect(body.indexOf("Engineering")).toBeLessThan(body.indexOf("Code Review"));
+ expect(body.indexOf("Code Review")).toBeLessThan(body.indexOf("Projects"));
+ expect(body.indexOf("Projects")).toBeLessThan(body.indexOf("Bundled"));
+ expect(document.querySelector('[data-folder-id="engineering"] > .pl-3 [data-folder-id="code-review"]')).not.toBeNull();
+ });
+
+ it("persists AllUnfiledBanner dismissal across mounts", () => {
+ const storageKey = "paperclip:test-folder-nudge";
+ window.localStorage.removeItem(storageKey);
+ const onCreateFolder = vi.fn();
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <AllUnfiledBanner
+ storageKey={storageKey}
+ itemLabelPlural="routines"
+ onCreateFolder={onCreateFolder}
+ />,
+ );
+ });
+
+ expect(container.textContent).toContain("Create your first folder");
+
+ const dismissButton = container.querySelector<HTMLButtonElement>(
+ 'button[aria-label="Dismiss folder suggestion"]',
+ );
+ act(() => {
+ dismissButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+ });
+
+ expect(container.textContent).not.toContain("Create your first folder");
+ expect(window.localStorage.getItem(storageKey)).toBe("1");
+
+ act(() => {
+ root?.unmount();
+ });
+ root = createRoot(container);
+ act(() => {
+ root?.render(
+ <AllUnfiledBanner
+ storageKey={storageKey}
+ itemLabelPlural="routines"
+ onCreateFolder={onCreateFolder}
+ />,
+ );
+ });
+ expect(container.textContent).not.toContain("Create your first folder");
+ window.localStorage.removeItem(storageKey);
+ });
+});
diff --git a/ui/src/components/folders/FolderControls.tsx b/ui/src/components/folders/FolderControls.tsx
new file mode 100644
index 0000000000..2262769fc5
--- /dev/null
+++ b/ui/src/components/folders/FolderControls.tsx
@@ -0,0 +1,776 @@
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+import {
+ Check,
+ ChevronDown,
+ Folder as FolderIcon,
+ MoreHorizontal,
+ Plus,
+ Search,
+ Trash2,
+ X,
+} from "lucide-react";
+import type { FolderKind, FolderListItem, FolderListResult } from "@paperclipai/shared";
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuSub,
+ DropdownMenuSubContent,
+ DropdownMenuSubTrigger,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Input } from "@/components/ui/input";
+import {
+ AlertDialog,
+ AlertDialogAction,
+ AlertDialogCancel,
+ AlertDialogContent,
+ AlertDialogDescription,
+ AlertDialogFooter,
+ AlertDialogHeader,
+ AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import {
+ Sheet,
+ SheetContent,
+ SheetHeader,
+ SheetTitle,
+} from "@/components/ui/sheet";
+import { cn } from "@/lib/utils";
+import {
+ reservedRootLabel,
+ treeFromResult,
+ type FolderTreeNode,
+} from "./skill-folder-tree";
+
+export type FolderSelection = "all" | "unfiled" | string;
+
+export const FOLDER_COLORS = [
+ "indigo",
+ "violet",
+ "emerald",
+ "cyan",
+ "amber",
+ "slate",
+];
+
+const FOLDER_COLOR_VALUES: Record<(typeof FOLDER_COLORS)[number], string> = {
+ indigo: "var(--folder-color-indigo)",
+ violet: "var(--folder-color-violet)",
+ emerald: "var(--folder-color-emerald)",
+ cyan: "var(--folder-color-cyan)",
+ amber: "var(--folder-color-amber)",
+ slate: "var(--folder-color-slate)",
+};
+
+export function normalizeFolderSelection(value: string | null | undefined): FolderSelection {
+ if (!value) return "all";
+ if (value === "unfiled") return "unfiled";
+ return value;
+}
+
+export function folderSearchValue(selection: FolderSelection): string {
+ return selection === "all" ? "" : selection === "unfiled" ? "unfiled" : selection;
+}
+
+export function selectedFolderFromList(
+ folders: FolderListItem[],
+ selection: FolderSelection,
+): FolderListItem | null {
+ if (selection === "all" || selection === "unfiled") return null;
+ return folders.find((folder) => folder.id === selection) ?? null;
+}
+
+export function FolderSwatch({
+ color,
+ className,
+}: {
+ color: string | null | undefined;
+ className?: string;
+}) {
+ const backgroundColor = color
+ ? (FOLDER_COLOR_VALUES[color] ?? color)
+ : "var(--folder-color-slate)";
+ return (
+ <span
+ aria-hidden="true"
+ className={cn("h-2.5 w-2.5 shrink-0 rounded-sm border border-border/40", className)}
+ style={{ backgroundColor }}
+ />
+ );
+}
+
+function selectionLabel({
+ folders,
+ selection,
+ allLabel,
+}: {
+ folders: FolderListItem[];
+ selection: FolderSelection;
+ allLabel: string;
+}) {
+ if (selection === "all") return allLabel;
+ if (selection === "unfiled") return "Unfiled";
+ return folders.find((folder) => folder.id === selection)?.name ?? allLabel;
+}
+
+function selectionCount(result: FolderListResult | null | undefined, selection: FolderSelection) {
+ if (!result) return 0;
+ if (selection === "all") return result.allCount;
+ if (selection === "unfiled") return result.unfiledCount;
+ return result.folders.find((folder) => folder.id === selection)?.itemCount ?? 0;
+}
+
+export function FolderChip({
+ result,
+ selection,
+ allLabel,
+ onClick,
+}: {
+ result: FolderListResult | null | undefined;
+ selection: FolderSelection;
+ allLabel: string;
+ onClick: () => void;
+}) {
+ const folder = result ? selectedFolderFromList(result.folders, selection) : null;
+ return (
+ <Button variant="outline" size="sm" className="max-w-full justify-start" onClick={onClick}>
+ {selection === "all" ? <FolderIcon className="mr-2 h-3.5 w-3.5" /> : <FolderSwatch color={folder?.color} className="mr-2" />}
+ <span className="truncate">{selectionLabel({ folders: result?.folders ?? [], selection, allLabel })}</span>
+ <span className="ml-2 text-xs text-muted-foreground">{selectionCount(result, selection)}</span>
+ <ChevronDown className="ml-1 h-3.5 w-3.5 shrink-0" />
+ </Button>
+ );
+}
+
+export function FolderRail({
+ result,
+ selection,
+ itemLabelPlural,
+ allLabel,
+ loading = false,
+ onSelect,
+ onCreate,
+ onRename,
+ onEdit,
+ onDelete,
+}: {
+ result: FolderListResult | null | undefined;
+ selection: FolderSelection;
+ itemLabelPlural: string;
+ allLabel: string;
+ loading?: boolean;
+ onSelect: (selection: FolderSelection) => void;
+ onCreate: () => void;
+ onRename: (folder: FolderListItem, name: string) => void;
+ onEdit: (folder: FolderListItem) => void;
+ onDelete: (folder: FolderListItem) => void;
+}) {
+ const folders = result?.folders ?? [];
+ const [renamingFolderId, setRenamingFolderId] = useState<string | null>(null);
+ const [renameDraft, setRenameDraft] = useState("");
+
+ useEffect(() => {
+ if (!renamingFolderId) return;
+ const folder = folders.find((entry) => entry.id === renamingFolderId);
+ if (!folder) setRenamingFolderId(null);
+ }, [folders, renamingFolderId]);
+
+ function startRename(folder: FolderListItem) {
+ setRenamingFolderId(folder.id);
+ setRenameDraft(folder.name);
+ }
+
+ function commitRename(folder: FolderListItem) {
+ const name = renameDraft.trim();
+ if (name && name !== folder.name) onRename(folder, name);
+ setRenamingFolderId(null);
+ }
+
+ function renderVirtualRow(
+ key: FolderSelection,
+ label: string,
+ count: number,
+ icon: ReactNode,
+ ) {
+ const active = selection === key;
+ return (
+ <button
+ type="button"
+ className={cn(
+ "grid w-full grid-cols-(--gtc-folder-row) items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm transition-colors hover:bg-accent/40",
+ active ? "bg-accent/60 text-foreground" : "text-muted-foreground",
+ )}
+ aria-current={active ? "page" : undefined}
+ onClick={() => onSelect(key)}
+ >
+ <span className="h-4 w-4">{icon}</span>
+ <span className="truncate">{label}</span>
+ <span className="text-xs text-muted-foreground">{count}</span>
+ </button>
+ );
+ }
+
+ return (
+ <nav aria-label={`${itemLabelPlural} folders`} className="hidden w-(--sz-folder-rail) shrink-0 border-r border-border pr-3 md:block">
+ <div className="mb-2 flex items-center justify-between gap-2">
+ <div className="text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">Folders</div>
+ <Button variant="ghost" size="icon-sm" title="New folder" onClick={onCreate}>
+ <Plus className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+ {loading ? (
+ <div className="space-y-2">
+ <div className="h-7 rounded-md bg-muted/60" />
+ <div className="h-7 rounded-md bg-muted/40" />
+ <div className="h-7 rounded-md bg-muted/30" />
+ </div>
+ ) : (
+ <div className="space-y-0.5">
+ {renderVirtualRow("all", allLabel, result?.allCount ?? 0, <FolderIcon className="h-3.5 w-3.5" />)}
+ {folders.map((folder) => (
+ <FolderRailItem
+ key={folder.id}
+ folder={folder}
+ active={selection === folder.id}
+ renaming={renamingFolderId === folder.id}
+ renameDraft={renameDraft}
+ onRenameDraftChange={setRenameDraft}
+ onRenameCommit={() => commitRename(folder)}
+ onRenameCancel={() => setRenamingFolderId(null)}
+ onSelect={() => onSelect(folder.id)}
+ onStartRename={() => startRename(folder)}
+ onEdit={() => onEdit(folder)}
+ onDelete={() => onDelete(folder)}
+ />
+ ))}
+ <div className="px-2 pb-1 pt-3 text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ System
+ </div>
+ {renderVirtualRow("unfiled", "Unfiled", result?.unfiledCount ?? 0, <FolderSwatch color={null} className="mt-0.5" />)}
+ </div>
+ )}
+ </nav>
+ );
+}
+
+/**
+ * One selectable rail row. The leading 1rem grid column is the reserved
+ * disclosure/indent slot so nested folders can slot in later without relayout
+ * (ux-spec §3.1/§3.2 "nesting-ready").
+ */
+export function FolderRailItem({
+ folder,
+ active,
+ renaming,
+ renameDraft,
+ onRenameDraftChange,
+ onRenameCommit,
+ onRenameCancel,
+ onSelect,
+ onStartRename,
+ onEdit,
+ onDelete,
+}: {
+ folder: FolderListItem;
+ active: boolean;
+ renaming: boolean;
+ renameDraft: string;
+ onRenameDraftChange: (value: string) => void;
+ onRenameCommit: () => void;
+ onRenameCancel: () => void;
+ onSelect: () => void;
+ onStartRename: () => void;
+ onEdit: () => void;
+ onDelete: () => void;
+}) {
+ return (
+ <div
+ className={cn(
+ "group grid grid-cols-(--gtc-folder-row-actions) items-center gap-2 rounded-md px-2 py-1 text-sm transition-colors hover:bg-accent/40",
+ active ? "bg-accent/60 text-foreground" : "text-muted-foreground",
+ )}
+ >
+ <span className="h-4 w-4" />
+ <button
+ type="button"
+ className="flex min-w-0 items-center gap-2 text-left"
+ aria-current={active ? "page" : undefined}
+ onClick={onSelect}
+ onDoubleClick={onStartRename}
+ >
+ <FolderSwatch color={folder.color} />
+ {renaming ? (
+ <input
+ value={renameDraft}
+ onChange={(event) => onRenameDraftChange(event.target.value)}
+ onClick={(event) => event.stopPropagation()}
+ onKeyDown={(event) => {
+ if (event.key === "Enter") onRenameCommit();
+ if (event.key === "Escape") onRenameCancel();
+ }}
+ onBlur={onRenameCommit}
+ className="h-6 min-w-0 flex-1 rounded-sm border border-border bg-background px-1 text-sm outline-none"
+ autoFocus
+ />
+ ) : (
+ <span className="truncate">{folder.name}</span>
+ )}
+ </button>
+ <span className="text-xs text-muted-foreground">{folder.itemCount}</span>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button
+ variant="ghost"
+ size="icon-sm"
+ className="h-6 w-6 opacity-0 group-hover:opacity-100 data-[state=open]:opacity-100"
+ aria-label={`Folder actions for ${folder.name}`}
+ >
+ <MoreHorizontal className="h-3.5 w-3.5" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ <DropdownMenuItem onSelect={onStartRename}>Rename</DropdownMenuItem>
+ <DropdownMenuItem onSelect={onEdit}>Edit color</DropdownMenuItem>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem variant="destructive" onSelect={onDelete}>
+ <Trash2 className="h-3.5 w-3.5" />
+ Delete
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ </div>
+ );
+}
+
+/**
+ * Dismissible nudge shown when items exist but no folders do (ux-spec §6.3).
+ * Dismissal persists per storage key.
+ */
+export function AllUnfiledBanner({
+ storageKey,
+ itemLabelPlural,
+ onCreateFolder,
+}: {
+ storageKey: string;
+ itemLabelPlural: string;
+ onCreateFolder: () => void;
+}) {
+ const [dismissed, setDismissed] = useState(() => {
+ try {
+ return window.localStorage.getItem(storageKey) === "1";
+ } catch {
+ return false;
+ }
+ });
+
+ if (dismissed) return null;
+
+ function dismiss() {
+ setDismissed(true);
+ try {
+ window.localStorage.setItem(storageKey, "1");
+ } catch {
+ // Ignore storage failures; the banner just reappears next visit.
+ }
+ }
+
+ return (
+ <div className="mb-3 flex flex-wrap items-center gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-sm">
+ <FolderIcon className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+ <span className="min-w-0 flex-1 text-muted-foreground">
+ Group these {itemLabelPlural} into folders to keep things tidy.
+ </span>
+ <Button size="sm" variant="outline" onClick={onCreateFolder}>
+ Create your first folder
+ </Button>
+ <Button size="icon-sm" variant="ghost" aria-label="Dismiss folder suggestion" onClick={dismiss}>
+ <X className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+ );
+}
+
+export function MobileFolderSheet({
+ open,
+ onOpenChange,
+ result,
+ selection,
+ allLabel,
+ itemLabelPlural,
+ onSelect,
+ onCreate,
+}: {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ result: FolderListResult | null | undefined;
+ selection: FolderSelection;
+ allLabel: string;
+ itemLabelPlural: string;
+ onSelect: (selection: FolderSelection) => void;
+ onCreate: () => void;
+}) {
+ function select(next: FolderSelection) {
+ onSelect(next);
+ onOpenChange(false);
+ }
+
+ const model = useMemo(() => treeFromResult(result), [result]);
+
+ function renderBranch(node: FolderTreeNode, rootLabel?: string) {
+ return (
+ <div key={node.folder.id} data-folder-id={node.folder.id}>
+ <MobileFolderRow
+ id={node.folder.id}
+ label={rootLabel ?? node.folder.name}
+ count={node.folder.itemCount}
+ color={node.folder.color}
+ selected={selection === node.folder.id}
+ onSelect={select}
+ />
+ {node.children.length > 0 ? (
+ <div className="pl-3">
+ {node.children.map((child) => renderBranch(child))}
+ </div>
+ ) : null}
+ </div>
+ );
+ }
+
+ return (
+ <Sheet open={open} onOpenChange={onOpenChange}>
+ <SheetContent side="bottom" className="max-h-(--sz-folder-sheet-max) rounded-t-lg pb-4">
+ <SheetHeader className="border-b border-border px-4 py-3">
+ <SheetTitle>{itemLabelPlural} folders</SheetTitle>
+ </SheetHeader>
+ <div className="overflow-y-auto px-3">
+ <MobileFolderRow
+ id="all"
+ label={allLabel}
+ count={result?.allCount ?? 0}
+ selected={selection === "all"}
+ onSelect={select}
+ all
+ />
+ {result?.kind === "skill" ? (
+ <>
+ {model.my ? renderBranch(model.my, "My Skills") : null}
+ <div className="px-2 pb-0.5 pt-2 text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ Company
+ </div>
+ {model.company.map((node) => renderBranch(node))}
+ {model.projects ? renderBranch(model.projects, "Projects") : null}
+ {model.bundled ? renderBranch(model.bundled, "Bundled") : null}
+ </>
+ ) : (
+ model.roots.map((node) => renderBranch(node, reservedRootLabel(node.folder)))
+ )}
+ <MobileFolderRow
+ id="unfiled"
+ label="Unfiled"
+ count={result?.unfiledCount ?? 0}
+ selected={selection === "unfiled"}
+ onSelect={select}
+ />
+ </div>
+ <div className="border-t border-border px-4 pt-3">
+ <Button size="sm" variant="outline" className="w-full" onClick={onCreate}>
+ <Plus className="mr-2 h-3.5 w-3.5" />
+ New folder
+ </Button>
+ </div>
+ </SheetContent>
+ </Sheet>
+ );
+}
+
+function MobileFolderRow({
+ id,
+ label,
+ count,
+ color,
+ selected,
+ all = false,
+ onSelect,
+}: {
+ id: FolderSelection;
+ label: string;
+ count: number;
+ color?: string | null;
+ selected: boolean;
+ all?: boolean;
+ onSelect: (selection: FolderSelection) => void;
+}) {
+ return (
+ <button
+ type="button"
+ className="flex w-full items-center gap-2 rounded-md px-2 py-2 text-left text-sm hover:bg-accent/50"
+ onClick={() => onSelect(id)}
+ >
+ {all ? <FolderIcon className="h-3.5 w-3.5 text-muted-foreground" /> : <FolderSwatch color={color} />}
+ <span className="min-w-0 flex-1 truncate">{label}</span>
+ <span className="text-xs text-muted-foreground">{count}</span>
+ {selected ? <Check className="h-3.5 w-3.5" /> : null}
+ </button>
+ );
+}
+
+export function MoveToMenu({
+ folders,
+ currentFolderId,
+ onMove,
+ onCreateAndMove,
+}: {
+ folders: FolderListItem[];
+ currentFolderId: string | null | undefined;
+ onMove: (folderId: string | null) => void;
+ onCreateAndMove: () => void;
+}) {
+ return (
+ <DropdownMenuSub>
+ <DropdownMenuSubTrigger>Move to...</DropdownMenuSubTrigger>
+ <DropdownMenuSubContent className="w-56">
+ <MoveToMenuItems
+ folders={folders}
+ currentFolderId={currentFolderId}
+ onMove={onMove}
+ onCreateAndMove={onCreateAndMove}
+ />
+ </DropdownMenuSubContent>
+ </DropdownMenuSub>
+ );
+}
+
+function MoveToMenuItems({
+ folders,
+ currentFolderId,
+ onMove,
+ onCreateAndMove,
+}: {
+ folders: FolderListItem[];
+ currentFolderId: string | null | undefined;
+ onMove: (folderId: string | null) => void;
+ onCreateAndMove: () => void;
+}) {
+ const [query, setQuery] = useState("");
+ const visibleFolders = useMemo(() => {
+ const lowered = query.trim().toLowerCase();
+ if (!lowered) return folders;
+ return folders.filter((folder) => folder.name.toLowerCase().includes(lowered));
+ }, [folders, query]);
+
+ return (
+ <>
+ <div className="flex items-center gap-2 px-2 py-1.5">
+ <Search className="h-3.5 w-3.5 text-muted-foreground" />
+ <input
+ value={query}
+ onChange={(event) => setQuery(event.target.value)}
+ onKeyDown={(event) => event.stopPropagation()}
+ placeholder="Search folders"
+ className="h-7 min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+ />
+ </div>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem onSelect={() => onMove(null)}>
+ <FolderSwatch color={null} />
+ Unfiled
+ {currentFolderId == null ? <Check className="ml-auto h-3.5 w-3.5" /> : null}
+ </DropdownMenuItem>
+ {visibleFolders.map((folder) => (
+ <DropdownMenuItem key={folder.id} onSelect={() => onMove(folder.id)}>
+ <FolderSwatch color={folder.color} />
+ <span className="min-w-0 flex-1 truncate">{folder.name}</span>
+ {currentFolderId === folder.id ? <Check className="ml-auto h-3.5 w-3.5" /> : null}
+ </DropdownMenuItem>
+ ))}
+ {visibleFolders.length === 0 ? (
+ <div className="px-2 py-2 text-xs text-muted-foreground">No folders match.</div>
+ ) : null}
+ <DropdownMenuSeparator />
+ <DropdownMenuItem onSelect={onCreateAndMove}>
+ <Plus className="h-3.5 w-3.5" />
+ New folder...
+ </DropdownMenuItem>
+ </>
+ );
+}
+
+export function FolderFormDialog({
+ open,
+ kind,
+ folder,
+ onOpenChange,
+ onSubmit,
+ pending = false,
+}: {
+ open: boolean;
+ kind: FolderKind;
+ folder: FolderListItem | null;
+ onOpenChange: (open: boolean) => void;
+ onSubmit: (payload: { name: string; color: string | null }) => void;
+ pending?: boolean;
+}) {
+ const [name, setName] = useState("");
+ const [color, setColor] = useState<string | null>(FOLDER_COLORS[0] ?? null);
+ const isEdit = Boolean(folder);
+
+ useEffect(() => {
+ if (!open) return;
+ setName(folder?.name ?? "");
+ setColor(folder?.color ?? FOLDER_COLORS[0] ?? null);
+ }, [folder, open]);
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent className="sm:max-w-md">
+ <DialogHeader>
+ <DialogTitle>{isEdit ? "Edit folder" : "Create folder"}</DialogTitle>
+ <DialogDescription>
+ {kind === "routine" ? "Organize routines in this company." : "Organize installed company skills."}
+ </DialogDescription>
+ </DialogHeader>
+ <div className="space-y-4">
+ <div className="space-y-2">
+ <label className="text-sm font-medium" htmlFor="folder-name">Name</label>
+ <Input
+ id="folder-name"
+ value={name}
+ onChange={(event) => setName(event.target.value)}
+ autoFocus
+ onKeyDown={(event) => {
+ if (event.key === "Enter" && name.trim()) onSubmit({ name: name.trim(), color });
+ }}
+ />
+ </div>
+ <div className="space-y-2">
+ <div className="text-sm font-medium">Color</div>
+ <div className="flex flex-wrap gap-2">
+ {FOLDER_COLORS.map((swatch) => (
+ <button
+ key={swatch}
+ type="button"
+ aria-label={`Use folder color ${swatch}`}
+ className={cn(
+ "h-7 w-7 rounded-md border border-border",
+ color === swatch && "ring-2 ring-ring ring-offset-2 ring-offset-background",
+ )}
+ style={{ backgroundColor: FOLDER_COLOR_VALUES[swatch] }}
+ onClick={() => setColor(swatch)}
+ />
+ ))}
+ <button
+ type="button"
+ className={cn(
+ "h-7 rounded-md border border-border px-2 text-xs text-muted-foreground",
+ color == null && "ring-2 ring-ring ring-offset-2 ring-offset-background",
+ )}
+ onClick={() => setColor(null)}
+ >
+ None
+ </button>
+ </div>
+ </div>
+ </div>
+ <DialogFooter>
+ <Button variant="ghost" onClick={() => onOpenChange(false)} disabled={pending}>
+ Cancel
+ </Button>
+ <Button onClick={() => onSubmit({ name: name.trim(), color })} disabled={pending || !name.trim()}>
+ {pending ? "Saving..." : isEdit ? "Save" : "Create folder"}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+export function DeleteFolderDialog({
+ open,
+ folder,
+ itemLabelPlural,
+ onOpenChange,
+ onConfirm,
+ pending = false,
+}: {
+ open: boolean;
+ folder: FolderListItem | null;
+ itemLabelPlural: string;
+ onOpenChange: (open: boolean) => void;
+ onConfirm: () => void;
+ pending?: boolean;
+}) {
+ return (
+ <AlertDialog open={open} onOpenChange={onOpenChange}>
+ <AlertDialogContent>
+ <AlertDialogHeader>
+ <AlertDialogTitle>Delete folder</AlertDialogTitle>
+ <AlertDialogDescription>
+ The {folder?.itemCount ?? 0} {itemLabelPlural} in this folder won't be deleted. They'll move to Unfiled.
+ </AlertDialogDescription>
+ </AlertDialogHeader>
+ <AlertDialogFooter>
+ <AlertDialogCancel disabled={pending}>Cancel</AlertDialogCancel>
+ <AlertDialogAction
+ className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+ disabled={pending || !folder}
+ onClick={(event) => {
+ event.preventDefault();
+ onConfirm();
+ }}
+ >
+ {pending ? "Deleting..." : "Delete folder"}
+ </AlertDialogAction>
+ </AlertDialogFooter>
+ </AlertDialogContent>
+ </AlertDialog>
+ );
+}
+
+export function BulkBar({
+ selectedCount,
+ folders,
+ onMove,
+ onCreateAndMove,
+ onClear,
+ onDone,
+}: {
+ selectedCount: number;
+ folders: FolderListItem[];
+ onMove: (folderId: string | null) => void;
+ onCreateAndMove: () => void;
+ onClear: () => void;
+ onDone: () => void;
+}) {
+ if (selectedCount === 0) return null;
+ return (
+ <div className="sticky top-2 z-10 flex flex-wrap items-center gap-2 rounded-md border border-border bg-background/95 px-3 py-2 shadow-sm backdrop-blur">
+ <span className="mr-auto text-sm text-muted-foreground">{selectedCount} selected</span>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button size="sm" variant="outline">Move to...</Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" className="w-56">
+ <MoveToMenuItems
+ folders={folders}
+ currentFolderId={undefined}
+ onMove={onMove}
+ onCreateAndMove={onCreateAndMove}
+ />
+ </DropdownMenuContent>
+ </DropdownMenu>
+ <Button size="sm" variant="ghost" onClick={onClear}>Deselect all</Button>
+ <Button size="sm" onClick={onDone}>Done</Button>
+ </div>
+ );
+}
diff --git a/ui/src/components/folders/SkillFolderTree.test.tsx b/ui/src/components/folders/SkillFolderTree.test.tsx
new file mode 100644
index 0000000000..53caaea15b
--- /dev/null
+++ b/ui/src/components/folders/SkillFolderTree.test.tsx
@@ -0,0 +1,131 @@
+// @vitest-environment jsdom
+
+import { flushSync } from "react-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { FolderListResult } from "@paperclipai/shared";
+import { SkillFolderRail } from "./SkillFolderTree";
+
+function pointerEvent(type: string, clientX: number) {
+ const event = new MouseEvent(type, { bubbles: true, clientX });
+ Object.defineProperty(event, "pointerId", { value: 1 });
+ return event;
+}
+
+const result: FolderListResult = {
+ kind: "skill",
+ allCount: 12,
+ unfiledCount: 2,
+ folders: [
+ {
+ id: "my-root",
+ companyId: "company-1",
+ kind: "skill",
+ parentId: null,
+ name: "My Skills",
+ slug: "my",
+ systemKey: "my",
+ path: "my",
+ depth: 1,
+ color: null,
+ position: 0,
+ itemCount: 4,
+ createdAt: new Date("2026-07-16T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-16T00:00:00.000Z"),
+ },
+ {
+ id: "personal-root",
+ companyId: "company-1",
+ kind: "skill",
+ parentId: "my-root",
+ name: "Ada",
+ slug: "ada",
+ systemKey: "my:user-1",
+ path: "my/ada",
+ depth: 2,
+ color: null,
+ position: 0,
+ itemCount: 4,
+ createdAt: new Date("2026-07-16T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-16T00:00:00.000Z"),
+ },
+ ],
+};
+
+describe("SkillFolderRail", () => {
+ let container: HTMLDivElement;
+ let root: Root;
+ const onSelect = vi.fn<(selection: string) => void>();
+
+ beforeEach(() => {
+ window.localStorage.clear();
+ container = document.createElement("div");
+ document.body.appendChild(container);
+ root = createRoot(container);
+ onSelect.mockClear();
+ flushSync(() => {
+ root.render(
+ <SkillFolderRail
+ result={result}
+ selection="all"
+ tags={[]}
+ activeTag={null}
+ onSelect={onSelect}
+ onSelectTag={vi.fn()}
+ onCreateFolder={vi.fn()}
+ onRenameFolder={vi.fn()}
+ onEditFolder={vi.fn()}
+ onMoveFolder={vi.fn()}
+ onDeleteFolder={vi.fn()}
+ />,
+ );
+ });
+ });
+
+ afterEach(() => {
+ flushSync(() => root.unmount());
+ container.remove();
+ window.localStorage.clear();
+ });
+
+ it("uses the wider default and persists drag resizing", () => {
+ const rail = container.firstElementChild as HTMLDivElement;
+ const separator = container.querySelector('[role="separator"]') as HTMLDivElement;
+ expect(rail.style.width).toBe("288px");
+ separator.setPointerCapture = vi.fn();
+
+ flushSync(() => {
+ separator.dispatchEvent(pointerEvent("pointerdown", 288));
+ separator.dispatchEvent(pointerEvent("pointermove", 320));
+ separator.dispatchEvent(pointerEvent("pointerup", 320));
+ });
+
+ expect(rail.style.width).toBe("320px");
+ expect(window.localStorage.getItem("paperclip.skills.folderRail.width")).toBe("320");
+ });
+
+ it("keeps virtual and folder counts on the same grid column", () => {
+ const allRow = Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent?.includes("All skills"));
+ const myLabel = Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent?.includes("My Skills"));
+ const myRow = myLabel?.parentElement;
+
+ expect(allRow?.className).toContain("grid-cols-(--gtc-folder-row-actions)");
+ expect(myRow?.className).toContain("grid-cols-(--gtc-folder-row-actions)");
+ expect(allRow?.querySelector(".tabular-nums")?.textContent).toBe("12");
+ expect(myRow?.querySelector(".tabular-nums")?.textContent).toBe("4");
+ });
+
+ it("selects and toggles a folder when its row label is clicked", () => {
+ const myLabel = Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent?.includes("My Skills"));
+
+ expect(container.textContent).not.toContain("Ada");
+ flushSync(() => myLabel?.click());
+
+ expect(onSelect).toHaveBeenCalledWith("my-root");
+ expect(container.textContent).toContain("Ada");
+ expect(container.querySelector('[aria-label="Collapse folder"]')).not.toBeNull();
+ });
+});
diff --git a/ui/src/components/folders/SkillFolderTree.tsx b/ui/src/components/folders/SkillFolderTree.tsx
new file mode 100644
index 0000000000..7673299c17
--- /dev/null
+++ b/ui/src/components/folders/SkillFolderTree.tsx
@@ -0,0 +1,1066 @@
+import {
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type KeyboardEvent,
+ type PointerEvent,
+ type ReactNode,
+} from "react";
+import {
+ Boxes,
+ Check,
+ ChevronRight,
+ Folder as FolderIcon,
+ FolderPlus,
+ Hash,
+ Home,
+ Layers,
+ MoreHorizontal,
+ MoveRight,
+ Plus,
+ Search,
+ Trash2,
+ User,
+} from "lucide-react";
+import type { FolderListItem, FolderListResult } from "@paperclipai/shared";
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogContent,
+ DialogDescription,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+} from "@/components/ui/dialog";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import { FolderSwatch, type FolderSelection } from "./FolderControls";
+import {
+ buildSkillFolderTree,
+ folderBreadcrumbTrail,
+ isBundledFolder,
+ isProjectsFolder,
+ reservedRootLabel,
+ skillFolderDisplayPath,
+ skillFolderPathDisplayFallback,
+ subtreeFolderIds,
+ treeFromResult,
+ type FolderTreeNode,
+ type SkillFolderTreeModel,
+} from "./skill-folder-tree";
+
+export {
+ buildSkillFolderTree,
+ folderBreadcrumbTrail,
+ isBundledFolder,
+ isProjectsFolder,
+ reservedRootLabel,
+ skillFolderDisplayPath,
+ skillFolderPathDisplayFallback,
+ subtreeFolderIds,
+ treeFromResult,
+ type SkillFolderTreeModel,
+};
+
+export interface TagFacet {
+ slug: string;
+ count: number;
+}
+
+const DEFAULT_FOLDER_RAIL_WIDTH = 288;
+const MIN_FOLDER_RAIL_WIDTH = 224;
+const MAX_FOLDER_RAIL_WIDTH = 400;
+const FOLDER_RAIL_WIDTH_STEP = 16;
+const FOLDER_RAIL_STORAGE_KEY = "paperclip.skills.folderRail.width";
+
+function clampFolderRailWidth(width: number) {
+ return Math.min(MAX_FOLDER_RAIL_WIDTH, Math.max(MIN_FOLDER_RAIL_WIDTH, width));
+}
+
+function readStoredFolderRailWidth() {
+ if (typeof window === "undefined") return DEFAULT_FOLDER_RAIL_WIDTH;
+ try {
+ const stored = window.localStorage.getItem(FOLDER_RAIL_STORAGE_KEY);
+ if (!stored) return DEFAULT_FOLDER_RAIL_WIDTH;
+ const parsed = Number.parseInt(stored, 10);
+ return Number.isFinite(parsed) ? clampFolderRailWidth(parsed) : DEFAULT_FOLDER_RAIL_WIDTH;
+ } catch {
+ return DEFAULT_FOLDER_RAIL_WIDTH;
+ }
+}
+
+function writeStoredFolderRailWidth(width: number) {
+ if (typeof window === "undefined") return;
+ try {
+ window.localStorage.setItem(FOLDER_RAIL_STORAGE_KEY, String(clampFolderRailWidth(width)));
+ } catch {
+ // Resizing still works when browser storage is unavailable.
+ }
+}
+
+/** Whether a folder's own actions (rename/recolor/subfolder/delete) are offered. */
+function folderIsEditable(folder: FolderListItem): boolean {
+ return !folder.systemKey && !isBundledFolder(folder) && !isProjectsFolder(folder);
+}
+
+function ancestorIds(model: SkillFolderTreeModel, folderId: string): string[] {
+ return folderBreadcrumbTrail(model, folderId)
+ .map((folder) => folder.id)
+ .filter((id) => id !== folderId);
+}
+
+// ---------------------------------------------------------------------------
+// Rail
+// ---------------------------------------------------------------------------
+
+export function SkillFolderRail({
+ result,
+ selection,
+ loading = false,
+ tags,
+ activeTag,
+ onSelect,
+ onSelectTag,
+ onCreateFolder,
+ onRenameFolder,
+ onEditFolder,
+ onMoveFolder,
+ onDeleteFolder,
+ onEnsureMyFolder,
+}: {
+ result: FolderListResult | null | undefined;
+ selection: FolderSelection;
+ loading?: boolean;
+ tags: TagFacet[];
+ activeTag: string | null;
+ onSelect: (selection: FolderSelection) => void;
+ onSelectTag: (slug: string | null) => void;
+ onCreateFolder: (parentId: string | null) => void;
+ onRenameFolder: (folder: FolderListItem, name: string) => void;
+ onEditFolder: (folder: FolderListItem) => void;
+ onMoveFolder: (folder: FolderListItem, destination: "my" | "company") => void;
+ onDeleteFolder: (folder: FolderListItem) => void;
+ onEnsureMyFolder?: () => void;
+}) {
+ const model = useMemo(() => treeFromResult(result), [result]);
+ const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
+ const [renamingId, setRenamingId] = useState<string | null>(null);
+ const [renameDraft, setRenameDraft] = useState("");
+ const [width, setWidth] = useState(readStoredFolderRailWidth);
+ const [isResizing, setIsResizing] = useState(false);
+ const widthRef = useRef(width);
+ const dragState = useRef<{ startX: number; startWidth: number } | null>(null);
+
+ // Auto-expand the ancestors of the current selection so it's always visible.
+ useEffect(() => {
+ if (selection === "all" || selection === "unfiled") return;
+ const ancestors = ancestorIds(model, selection);
+ if (ancestors.length === 0) return;
+ setExpanded((current) => {
+ const next = new Set(current);
+ let changed = false;
+ for (const id of ancestors) {
+ if (!next.has(id)) {
+ next.add(id);
+ changed = true;
+ }
+ }
+ return changed ? next : current;
+ });
+ }, [model, selection]);
+
+ function toggle(id: string) {
+ setExpanded((current) => {
+ const next = new Set(current);
+ if (next.has(id)) next.delete(id);
+ else next.add(id);
+ return next;
+ });
+ }
+
+ function startRename(folder: FolderListItem) {
+ setRenamingId(folder.id);
+ setRenameDraft(folder.name);
+ }
+
+ function commitRename(folder: FolderListItem) {
+ const name = renameDraft.trim();
+ if (name && name !== folder.name) onRenameFolder(folder, name);
+ setRenamingId(null);
+ }
+
+ const allCount = result?.allCount ?? 0;
+ const unfiledCount = result?.unfiledCount ?? 0;
+
+ const commitWidth = useCallback((nextWidth: number) => {
+ const clamped = clampFolderRailWidth(nextWidth);
+ widthRef.current = clamped;
+ setWidth(clamped);
+ writeStoredFolderRailWidth(clamped);
+ }, []);
+
+ const handlePointerDown = useCallback((event: PointerEvent<HTMLDivElement>) => {
+ event.preventDefault();
+ event.currentTarget.setPointerCapture(event.pointerId);
+ dragState.current = { startX: event.clientX, startWidth: widthRef.current };
+ setIsResizing(true);
+ }, []);
+
+ const handlePointerMove = useCallback((event: PointerEvent<HTMLDivElement>) => {
+ if (!dragState.current) return;
+ const nextWidth = dragState.current.startWidth + event.clientX - dragState.current.startX;
+ const clamped = clampFolderRailWidth(nextWidth);
+ widthRef.current = clamped;
+ setWidth(clamped);
+ }, []);
+
+ const endResize = useCallback(() => {
+ if (!dragState.current) return;
+ dragState.current = null;
+ setIsResizing(false);
+ writeStoredFolderRailWidth(widthRef.current);
+ }, []);
+
+ const handleKeyDown = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
+ if (event.key === "ArrowLeft") {
+ event.preventDefault();
+ commitWidth(width - FOLDER_RAIL_WIDTH_STEP);
+ } else if (event.key === "ArrowRight") {
+ event.preventDefault();
+ commitWidth(width + FOLDER_RAIL_WIDTH_STEP);
+ } else if (event.key === "Home") {
+ event.preventDefault();
+ commitWidth(MIN_FOLDER_RAIL_WIDTH);
+ } else if (event.key === "End") {
+ event.preventDefault();
+ commitWidth(MAX_FOLDER_RAIL_WIDTH);
+ }
+ }, [commitWidth, width]);
+
+ return (
+ <div className="relative hidden h-full shrink-0 md:flex" style={{ width: `${width}px` }}>
+ <nav
+ aria-label="Skill folders"
+ className="flex min-w-0 flex-1 flex-col overflow-y-auto border-r border-border pr-3"
+ >
+ <div className="mb-2 flex items-center justify-between gap-2 pt-0.5">
+ <div className="text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ Folders
+ </div>
+ <Button variant="ghost" size="icon-sm" title="New folder" onClick={() => onCreateFolder(null)}>
+ <Plus className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+
+ {loading ? (
+ <div className="space-y-2">
+ <div className="h-7 rounded-md bg-muted/60" />
+ <div className="h-7 rounded-md bg-muted/40" />
+ <div className="h-7 rounded-md bg-muted/30" />
+ </div>
+ ) : (
+ <div className="space-y-0.5">
+ <VirtualRow
+ active={selection === "all"}
+ label="All skills"
+ count={allCount}
+ icon={<Layers className="h-3.5 w-3.5" />}
+ onSelect={() => onSelect("all")}
+ />
+
+ {/* My Skills — personal namespace */}
+ {model.my ? (
+ <TreeBranch
+ node={model.my}
+ depth={0}
+ selection={selection}
+ expanded={expanded}
+ renamingId={renamingId}
+ renameDraft={renameDraft}
+ rootLabel="My Skills"
+ rootIcon={<User className="h-3.5 w-3.5" />}
+ onToggle={toggle}
+ onSelect={onSelect}
+ onCreateFolder={onCreateFolder}
+ onEditFolder={onEditFolder}
+ onMoveFolder={onMoveFolder}
+ onDeleteFolder={onDeleteFolder}
+ onStartRename={startRename}
+ onRenameDraftChange={setRenameDraft}
+ onRenameCommit={commitRename}
+ onRenameCancel={() => setRenamingId(null)}
+ />
+ ) : onEnsureMyFolder ? (
+ <VirtualRow
+ active={false}
+ label="My Skills"
+ count={0}
+ icon={<User className="h-3.5 w-3.5" />}
+ muted
+ onSelect={onEnsureMyFolder}
+ />
+ ) : null}
+
+ {/* Company — plain top-level company folders */}
+ <RailHeading label="Company" onCreate={() => onCreateFolder(null)} />
+ {model.company.length > 0 ? (
+ model.company.map((node) => (
+ <TreeBranch
+ key={node.folder.id}
+ node={node}
+ depth={0}
+ selection={selection}
+ expanded={expanded}
+ renamingId={renamingId}
+ renameDraft={renameDraft}
+ onToggle={toggle}
+ onSelect={onSelect}
+ onCreateFolder={onCreateFolder}
+ onEditFolder={onEditFolder}
+ onMoveFolder={onMoveFolder}
+ onDeleteFolder={onDeleteFolder}
+ onStartRename={startRename}
+ onRenameDraftChange={setRenameDraft}
+ onRenameCommit={commitRename}
+ onRenameCancel={() => setRenamingId(null)}
+ />
+ ))
+ ) : (
+ <div className="px-2 py-1 text-xs text-muted-foreground">No company folders yet.</div>
+ )}
+
+ {/* Projects — auto-managed, read-only structure */}
+ {model.projects ? (
+ <TreeBranch
+ node={model.projects}
+ depth={0}
+ selection={selection}
+ expanded={expanded}
+ renamingId={renamingId}
+ renameDraft={renameDraft}
+ rootLabel="Projects"
+ rootIcon={<Boxes className="h-3.5 w-3.5" />}
+ onToggle={toggle}
+ onSelect={onSelect}
+ onCreateFolder={onCreateFolder}
+ onEditFolder={onEditFolder}
+ onMoveFolder={onMoveFolder}
+ onDeleteFolder={onDeleteFolder}
+ onStartRename={startRename}
+ onRenameDraftChange={setRenameDraft}
+ onRenameCommit={commitRename}
+ onRenameCancel={() => setRenamingId(null)}
+ />
+ ) : (
+ <VirtualRow
+ active={false}
+ label="Projects"
+ count={0}
+ icon={<Boxes className="h-3.5 w-3.5" />}
+ muted
+ disabled
+ onSelect={() => undefined}
+ />
+ )}
+
+ {/* Bundled — read-only */}
+ {model.bundled ? (
+ <TreeBranch
+ node={model.bundled}
+ depth={0}
+ selection={selection}
+ expanded={expanded}
+ renamingId={renamingId}
+ renameDraft={renameDraft}
+ rootLabel="Bundled"
+ rootIcon={<Boxes className="h-3.5 w-3.5" />}
+ onToggle={toggle}
+ onSelect={onSelect}
+ onCreateFolder={onCreateFolder}
+ onEditFolder={onEditFolder}
+ onMoveFolder={onMoveFolder}
+ onDeleteFolder={onDeleteFolder}
+ onStartRename={startRename}
+ onRenameDraftChange={setRenameDraft}
+ onRenameCommit={commitRename}
+ onRenameCancel={() => setRenamingId(null)}
+ />
+ ) : null}
+
+ <div className="px-2 pb-1 pt-3 text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ System
+ </div>
+ <VirtualRow
+ active={selection === "unfiled"}
+ label="Unfiled"
+ count={unfiledCount}
+ icon={<FolderSwatch color={null} />}
+ onSelect={() => onSelect("unfiled")}
+ />
+ </div>
+ )}
+
+ {/* Tags facet — folders locate, tags describe. Filters within the subtree. */}
+ {tags.length > 0 ? (
+ <div className="mt-4 border-t border-border pt-3">
+ <div className="mb-1.5 flex items-center gap-1.5 px-2 text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ <Hash className="h-3 w-3" />
+ Tags
+ </div>
+ <div className="flex flex-wrap gap-1.5 px-1">
+ {activeTag ? (
+ <button
+ type="button"
+ onClick={() => onSelectTag(null)}
+ className="inline-flex items-center gap-1 rounded-full border border-border bg-accent/60 px-2 py-0.5 text-xs text-foreground"
+ >
+ {activeTag}
+ <Check className="h-3 w-3" />
+ </button>
+ ) : null}
+ {tags
+ .filter((tag) => tag.slug !== activeTag)
+ .map((tag) => (
+ <button
+ key={tag.slug}
+ type="button"
+ onClick={() => onSelectTag(tag.slug)}
+ className="inline-flex items-center gap-1 rounded-full border border-border px-2 py-0.5 text-xs text-muted-foreground transition-colors hover:bg-accent/40 hover:text-foreground"
+ >
+ <span className="max-w-32 truncate">{tag.slug}</span>
+ <span className="text-(length:--text-micro) opacity-70">{tag.count}</span>
+ </button>
+ ))}
+ </div>
+ </div>
+ ) : null}
+ </nav>
+ <div
+ role="separator"
+ aria-label="Resize skill folders"
+ aria-orientation="vertical"
+ aria-valuemin={MIN_FOLDER_RAIL_WIDTH}
+ aria-valuemax={MAX_FOLDER_RAIL_WIDTH}
+ aria-valuenow={width}
+ tabIndex={0}
+ className={cn(
+ "absolute inset-y-0 right-0 z-20 w-3 cursor-col-resize touch-none outline-none",
+ "before:absolute before:inset-y-0 before:left-1/2 before:w-px before:-translate-x-1/2 before:bg-transparent before:transition-colors",
+ "hover:before:bg-border focus-visible:before:bg-ring",
+ isResizing && "before:bg-ring",
+ )}
+ onPointerDown={handlePointerDown}
+ onPointerMove={handlePointerMove}
+ onPointerUp={endResize}
+ onPointerCancel={endResize}
+ onLostPointerCapture={endResize}
+ onKeyDown={handleKeyDown}
+ />
+ </div>
+ );
+}
+
+function RailHeading({ label, onCreate }: { label: string; onCreate: () => void }) {
+ return (
+ <div className="group/heading flex items-center justify-between px-2 pb-0.5 pt-3">
+ <span className="text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ {label}
+ </span>
+ <button
+ type="button"
+ onClick={onCreate}
+ title={`New ${label.toLowerCase()} folder`}
+ className="opacity-0 transition-opacity group-hover/heading:opacity-100"
+ >
+ <Plus className="h-3 w-3 text-muted-foreground" />
+ </button>
+ </div>
+ );
+}
+
+function VirtualRow({
+ active,
+ label,
+ count,
+ icon,
+ muted = false,
+ disabled = false,
+ onSelect,
+}: {
+ active: boolean;
+ label: string;
+ count: number;
+ icon: ReactNode;
+ muted?: boolean;
+ disabled?: boolean;
+ onSelect: () => void;
+}) {
+ return (
+ <button
+ type="button"
+ className={cn(
+ "grid w-full grid-cols-(--gtc-folder-row-actions) items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm transition-colors hover:bg-accent/40",
+ active ? "bg-accent/60 text-foreground" : muted ? "text-muted-foreground/70" : "text-muted-foreground",
+ )}
+ aria-current={active ? "page" : undefined}
+ disabled={disabled}
+ onClick={onSelect}
+ >
+ <span className="flex h-4 w-4 items-center justify-center">{icon}</span>
+ <span className="truncate">{label}</span>
+ <span className="text-right text-xs tabular-nums text-muted-foreground">{count}</span>
+ <span className="h-6 w-6" aria-hidden="true" />
+ </button>
+ );
+}
+
+/** A folder node and (when expanded) its descendants, indented by depth. */
+function TreeBranch({
+ node,
+ depth,
+ selection,
+ expanded,
+ renamingId,
+ renameDraft,
+ rootLabel,
+ rootIcon,
+ onToggle,
+ onSelect,
+ onCreateFolder,
+ onEditFolder,
+ onMoveFolder,
+ onDeleteFolder,
+ onStartRename,
+ onRenameDraftChange,
+ onRenameCommit,
+ onRenameCancel,
+}: {
+ node: FolderTreeNode;
+ depth: number;
+ selection: FolderSelection;
+ expanded: Set<string>;
+ renamingId: string | null;
+ renameDraft: string;
+ rootLabel?: string;
+ rootIcon?: ReactNode;
+ onToggle: (id: string) => void;
+ onSelect: (selection: FolderSelection) => void;
+ onCreateFolder: (parentId: string | null) => void;
+ onEditFolder: (folder: FolderListItem) => void;
+ onMoveFolder: (folder: FolderListItem, destination: "my" | "company") => void;
+ onDeleteFolder: (folder: FolderListItem) => void;
+ onStartRename: (folder: FolderListItem) => void;
+ onRenameDraftChange: (value: string) => void;
+ onRenameCommit: (folder: FolderListItem) => void;
+ onRenameCancel: () => void;
+}) {
+ const { folder, children } = node;
+ const isOpen = expanded.has(folder.id);
+ const active = selection === folder.id;
+ const editable = folderIsEditable(folder);
+ const canNest = !isBundledFolder(folder) && !isProjectsFolder(folder) && folder.depth < 4;
+ const isInMySkills = folder.path.startsWith("my/");
+ const label = rootLabel ?? folder.name;
+
+ return (
+ <div>
+ <div
+ className={cn(
+ "group grid grid-cols-(--gtc-folder-row-actions) items-center gap-2 rounded-md pr-2 text-sm transition-colors hover:bg-accent/40",
+ active ? "bg-accent/60 text-foreground" : "text-muted-foreground",
+ )}
+ style={{ paddingLeft: `${depth * 0.75}rem` }}
+ >
+ <button
+ type="button"
+ aria-label={isOpen ? "Collapse folder" : "Expand folder"}
+ className={cn(
+ "flex h-6 w-4 items-center justify-center text-muted-foreground",
+ children.length === 0 && "invisible",
+ )}
+ onClick={() => onToggle(folder.id)}
+ >
+ <ChevronRight className={cn("h-3.5 w-3.5 transition-transform", isOpen && "rotate-90")} />
+ </button>
+ <button
+ type="button"
+ className="flex min-w-0 items-center gap-2 py-1 text-left"
+ aria-current={active ? "page" : undefined}
+ onClick={() => {
+ onSelect(folder.id);
+ if (children.length > 0) onToggle(folder.id);
+ }}
+ onDoubleClick={() => editable && onStartRename(folder)}
+ >
+ {rootIcon ? (
+ <span className="flex h-4 w-4 items-center justify-center text-muted-foreground">{rootIcon}</span>
+ ) : (
+ <FolderSwatch color={folder.color} />
+ )}
+ {renamingId === folder.id ? (
+ <input
+ value={renameDraft}
+ onChange={(event) => onRenameDraftChange(event.target.value)}
+ onClick={(event) => event.stopPropagation()}
+ onKeyDown={(event) => {
+ if (event.key === "Enter") onRenameCommit(folder);
+ if (event.key === "Escape") onRenameCancel();
+ }}
+ onBlur={() => onRenameCommit(folder)}
+ className="h-6 min-w-0 flex-1 rounded-sm border border-border bg-background px-1 text-sm outline-none"
+ autoFocus
+ />
+ ) : (
+ <span className="truncate">{label}</span>
+ )}
+ </button>
+ <span className="text-right text-xs tabular-nums text-muted-foreground">{folder.itemCount}</span>
+ {editable || canNest ? (
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button
+ variant="ghost"
+ size="icon-sm"
+ className="h-6 w-6 opacity-0 group-hover:opacity-100 data-[state=open]:opacity-100"
+ aria-label={`Folder actions for ${label}`}
+ >
+ <MoreHorizontal className="h-3.5 w-3.5" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ {canNest ? (
+ <DropdownMenuItem onSelect={() => onCreateFolder(folder.id)}>
+ <FolderPlus className="h-3.5 w-3.5" />
+ New subfolder
+ </DropdownMenuItem>
+ ) : null}
+ {editable ? (
+ <>
+ <DropdownMenuItem onSelect={() => onStartRename(folder)}>Rename</DropdownMenuItem>
+ <DropdownMenuItem onSelect={() => onEditFolder(folder)}>Edit color</DropdownMenuItem>
+ <DropdownMenuItem onSelect={() => onMoveFolder(folder, isInMySkills ? "company" : "my")}>
+ <MoveRight className="h-3.5 w-3.5" />
+ Move to {isInMySkills ? "Company" : "My Skills"}
+ </DropdownMenuItem>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem variant="destructive" onSelect={() => onDeleteFolder(folder)}>
+ <Trash2 className="h-3.5 w-3.5" />
+ Delete
+ </DropdownMenuItem>
+ </>
+ ) : null}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ ) : (
+ <span className="h-6 w-6" />
+ )}
+ </div>
+ {isOpen && children.length > 0 ? (
+ <div>
+ {children.map((child) => (
+ <TreeBranch
+ key={child.folder.id}
+ node={child}
+ depth={depth + 1}
+ selection={selection}
+ expanded={expanded}
+ renamingId={renamingId}
+ renameDraft={renameDraft}
+ onToggle={onToggle}
+ onSelect={onSelect}
+ onCreateFolder={onCreateFolder}
+ onEditFolder={onEditFolder}
+ onMoveFolder={onMoveFolder}
+ onDeleteFolder={onDeleteFolder}
+ onStartRename={onStartRename}
+ onRenameDraftChange={onRenameDraftChange}
+ onRenameCommit={onRenameCommit}
+ onRenameCancel={onRenameCancel}
+ />
+ ))}
+ </div>
+ ) : null}
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Breadcrumb
+// ---------------------------------------------------------------------------
+
+export function FolderBreadcrumb({
+ result,
+ selection,
+ onSelect,
+}: {
+ result: FolderListResult | null | undefined;
+ selection: FolderSelection;
+ onSelect: (selection: FolderSelection) => void;
+}) {
+ const model = useMemo(() => treeFromResult(result), [result]);
+ const trail = selection === "all" || selection === "unfiled"
+ ? []
+ : folderBreadcrumbTrail(model, selection);
+
+ return (
+ <nav aria-label="Folder path" className="flex flex-wrap items-center gap-1 text-sm">
+ <button
+ type="button"
+ onClick={() => onSelect("all")}
+ className={cn(
+ "inline-flex items-center gap-1 rounded px-1.5 py-0.5 transition-colors hover:bg-accent/40",
+ selection === "all" ? "font-medium text-foreground" : "text-muted-foreground",
+ )}
+ >
+ <Home className="h-3.5 w-3.5" />
+ All skills
+ </button>
+ {selection === "unfiled" ? (
+ <>
+ <ChevronRight className="h-3.5 w-3.5 text-muted-foreground/60" />
+ <span className="rounded px-1.5 py-0.5 font-medium text-foreground">Unfiled</span>
+ </>
+ ) : null}
+ {trail.map((folder, index) => {
+ const isLast = index === trail.length - 1;
+ const label = index === 0 ? reservedRootLabel(folder) : folder.name;
+ return (
+ <span key={folder.id} className="inline-flex items-center gap-1">
+ <ChevronRight className="h-3.5 w-3.5 text-muted-foreground/60" />
+ <button
+ type="button"
+ onClick={() => onSelect(folder.id)}
+ className={cn(
+ "inline-flex items-center gap-1 rounded px-1.5 py-0.5 transition-colors hover:bg-accent/40",
+ isLast ? "font-medium text-foreground" : "text-muted-foreground",
+ )}
+ >
+ {folder.color ? <FolderSwatch color={folder.color} /> : null}
+ {label}
+ </button>
+ </span>
+ );
+ })}
+ </nav>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Subfolder tiles (folder browser)
+// ---------------------------------------------------------------------------
+
+export function FolderTiles({
+ result,
+ selection,
+ onOpen,
+}: {
+ result: FolderListResult | null | undefined;
+ selection: FolderSelection;
+ onOpen: (folderId: string) => void;
+}) {
+ const model = useMemo(() => treeFromResult(result), [result]);
+ const children = useMemo<FolderTreeNode[]>(() => {
+ if (selection === "unfiled") return [];
+ if (selection === "all") return model.roots;
+ return model.childrenById.get(selection) ?? [];
+ }, [model, selection]);
+
+ if (children.length === 0) return null;
+
+ return (
+ <div className="mb-4">
+ <div className="mb-2 text-(length:--text-micro) font-medium uppercase tracking-wide text-muted-foreground">
+ Folders
+ </div>
+ <div className="grid gap-2 [grid-template-columns:repeat(auto-fill,minmax(11rem,1fr))]">
+ {children.map((node) => (
+ <button
+ key={node.folder.id}
+ type="button"
+ onClick={() => onOpen(node.folder.id)}
+ className="flex items-center gap-2 rounded-md border border-border bg-card px-3 py-2.5 text-left transition-colors hover:border-foreground/30 hover:bg-accent/30"
+ >
+ {node.folder.systemKey && ["my", "projects", "bundled"].includes(node.folder.systemKey) ? (
+ <FolderIcon className="h-4 w-4 shrink-0 text-muted-foreground" />
+ ) : (
+ <FolderSwatch color={node.folder.color} className="h-3.5 w-3.5" />
+ )}
+ <span className="min-w-0 flex-1 truncate text-sm font-medium text-foreground">
+ {reservedRootLabel(node.folder)}
+ </span>
+ <span className="text-xs text-muted-foreground">{node.folder.itemCount}</span>
+ </button>
+ ))}
+ </div>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Move-to-folder dialog (tree picker + inline new folder + path preview)
+// ---------------------------------------------------------------------------
+
+export function MoveToFolderDialog({
+ open,
+ onOpenChange,
+ result,
+ title,
+ subtitle,
+ currentFolderId,
+ pending = false,
+ onMove,
+ onCreateFolder,
+}: {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ result: FolderListResult | null | undefined;
+ title: string;
+ subtitle?: string | null;
+ currentFolderId: string | null | undefined;
+ pending?: boolean;
+ onMove: (folderId: string | null) => void;
+ /** Create a folder under `parentId` (null = top level); resolve to the new id. */
+ onCreateFolder: (parentId: string | null, name: string) => Promise<string | null>;
+}) {
+ const model = useMemo(() => treeFromResult(result), [result]);
+ const [query, setQuery] = useState("");
+ const [target, setTarget] = useState<string | null | undefined>(undefined);
+ const [creatingParent, setCreatingParent] = useState<string | null | undefined>(undefined);
+ const [newName, setNewName] = useState("");
+ const [creating, setCreating] = useState(false);
+
+ useEffect(() => {
+ if (open) {
+ setQuery("");
+ setTarget(undefined);
+ setCreatingParent(undefined);
+ setNewName("");
+ }
+ }, [open]);
+
+ const lowered = query.trim().toLowerCase();
+ const matches = (folder: FolderListItem) =>
+ !lowered || folder.name.toLowerCase().includes(lowered) || folder.path.toLowerCase().includes(lowered);
+
+ // The selected destination (undefined = nothing picked yet).
+ const chosen = target;
+ const chosenFolder = typeof chosen === "string" ? model.byId.get(chosen) ?? null : null;
+ const previewPath = chosen === undefined
+ ? null
+ : chosen === null
+ ? "Unfiled"
+ : chosenFolder?.path ?? null;
+
+ async function submitNewFolder() {
+ const name = newName.trim();
+ if (!name) return;
+ setCreating(true);
+ try {
+ const id = await onCreateFolder(creatingParent ?? null, name);
+ if (id) setTarget(id);
+ setCreatingParent(undefined);
+ setNewName("");
+ } finally {
+ setCreating(false);
+ }
+ }
+
+ function renderNode(node: FolderTreeNode, depth: number): ReactNode {
+ const { folder } = node;
+ const bundled = isBundledFolder(folder);
+ const selectable = !bundled;
+ const isChosen = chosen === folder.id;
+ const isCurrent = currentFolderId === folder.id;
+ const nestable = selectable && !isProjectsFolder(folder) && folder.depth < 4;
+ const visibleChildren = node.children;
+ const selfMatches = matches(folder);
+ // Keep a folder if it or any descendant matches the filter.
+ const childMatches = subtreeMatches(node, matches);
+ if (lowered && !selfMatches && !childMatches) return null;
+
+ return (
+ <div key={folder.id}>
+ <div
+ className={cn(
+ "group flex items-center gap-2 rounded-md px-2 py-1.5 text-sm",
+ selectable ? "cursor-pointer hover:bg-accent/40" : "cursor-not-allowed opacity-50",
+ isChosen && "bg-accent/70",
+ )}
+ style={{ paddingLeft: `${0.5 + depth * 0.9}rem` }}
+ onClick={() => selectable && setTarget(folder.id)}
+ >
+ {folder.systemKey && ["my", "projects", "bundled"].includes(folder.systemKey) ? (
+ <FolderIcon className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+ ) : (
+ <FolderSwatch color={folder.color} />
+ )}
+ <span className="min-w-0 flex-1 truncate">{reservedRootLabel(folder)}</span>
+ {isCurrent ? <span className="text-xs text-muted-foreground">current</span> : null}
+ {bundled ? <span className="text-xs text-muted-foreground">read-only</span> : null}
+ {isChosen ? <Check className="h-3.5 w-3.5" /> : null}
+ {nestable ? (
+ <button
+ type="button"
+ title="New folder inside…"
+ className="opacity-0 transition-opacity group-hover:opacity-100"
+ onClick={(event) => {
+ event.stopPropagation();
+ setCreatingParent(folder.id);
+ setNewName("");
+ }}
+ >
+ <FolderPlus className="h-3.5 w-3.5 text-muted-foreground" />
+ </button>
+ ) : null}
+ </div>
+ {creatingParent === folder.id ? (
+ <InlineNewFolder
+ depth={depth + 1}
+ value={newName}
+ pending={creating}
+ onChange={setNewName}
+ onSubmit={submitNewFolder}
+ onCancel={() => setCreatingParent(undefined)}
+ />
+ ) : null}
+ {visibleChildren.map((child) => renderNode(child, depth + 1))}
+ </div>
+ );
+ }
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent className="sm:max-w-lg">
+ <DialogHeader>
+ <DialogTitle>{title}</DialogTitle>
+ {subtitle ? <DialogDescription>{subtitle}</DialogDescription> : null}
+ </DialogHeader>
+
+ <div className="flex items-center gap-2 rounded-md border border-border px-2.5">
+ <Search className="h-3.5 w-3.5 text-muted-foreground" />
+ <input
+ value={query}
+ onChange={(event) => setQuery(event.target.value)}
+ placeholder="Search folders"
+ className="h-8 min-w-0 flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+ />
+ </div>
+
+ <div className="max-h-72 overflow-y-auto rounded-md border border-border p-1">
+ <div
+ className={cn(
+ "flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-accent/40",
+ chosen === null && "bg-accent/70",
+ )}
+ onClick={() => setTarget(null)}
+ >
+ <FolderSwatch color={null} />
+ <span className="min-w-0 flex-1 truncate">Unfiled</span>
+ {currentFolderId == null ? <span className="text-xs text-muted-foreground">current</span> : null}
+ {chosen === null ? <Check className="h-3.5 w-3.5" /> : null}
+ </div>
+ {model.roots.map((node) => renderNode(node, 0))}
+ <div className="mt-1 border-t border-border pt-1">
+ {creatingParent === null ? (
+ <InlineNewFolder
+ depth={0}
+ value={newName}
+ pending={creating}
+ onChange={setNewName}
+ onSubmit={submitNewFolder}
+ onCancel={() => setCreatingParent(undefined)}
+ />
+ ) : (
+ <button
+ type="button"
+ onClick={() => {
+ setCreatingParent(null);
+ setNewName("");
+ }}
+ className="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-sm text-muted-foreground hover:bg-accent/40 hover:text-foreground"
+ >
+ <Plus className="h-3.5 w-3.5" />
+ New top-level folder…
+ </button>
+ )}
+ </div>
+ </div>
+
+ <div className="min-h-5 text-xs text-muted-foreground">
+ {previewPath ? (
+ <span>
+ Moving to <span className="font-mono text-foreground">{previewPath}</span>
+ </span>
+ ) : (
+ <span>Pick a destination folder.</span>
+ )}
+ </div>
+
+ <DialogFooter>
+ <Button variant="ghost" onClick={() => onOpenChange(false)} disabled={pending}>
+ Cancel
+ </Button>
+ <Button
+ disabled={pending || chosen === undefined || chosen === currentFolderId}
+ onClick={() => chosen !== undefined && onMove(chosen)}
+ >
+ {pending ? "Moving…" : "Move here"}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+function subtreeMatches(node: FolderTreeNode, matches: (folder: FolderListItem) => boolean): boolean {
+ if (matches(node.folder)) return true;
+ return node.children.some((child) => subtreeMatches(child, matches));
+}
+
+function InlineNewFolder({
+ depth,
+ value,
+ pending,
+ onChange,
+ onSubmit,
+ onCancel,
+}: {
+ depth: number;
+ value: string;
+ pending: boolean;
+ onChange: (value: string) => void;
+ onSubmit: () => void;
+ onCancel: () => void;
+}) {
+ return (
+ <div className="flex items-center gap-2 py-1" style={{ paddingLeft: `${0.5 + depth * 0.9}rem` }}>
+ <FolderPlus className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+ <Input
+ value={value}
+ onChange={(event) => onChange(event.target.value)}
+ placeholder="Folder name"
+ autoFocus
+ className="h-7 flex-1 text-sm"
+ onKeyDown={(event) => {
+ if (event.key === "Enter") onSubmit();
+ if (event.key === "Escape") onCancel();
+ }}
+ />
+ <Button size="sm" variant="ghost" onClick={onCancel} disabled={pending}>
+ Cancel
+ </Button>
+ <Button size="sm" onClick={onSubmit} disabled={pending || !value.trim()}>
+ Add
+ </Button>
+ </div>
+ );
+}
diff --git a/ui/src/components/folders/skill-folder-tree.test.ts b/ui/src/components/folders/skill-folder-tree.test.ts
new file mode 100644
index 0000000000..2a8ebdffba
--- /dev/null
+++ b/ui/src/components/folders/skill-folder-tree.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import type { FolderListItem } from "@paperclipai/shared";
+import {
+ buildSkillFolderTree,
+ folderBreadcrumbTrail,
+ isBundledFolder,
+ isProjectsFolder,
+ reservedRootLabel,
+ skillFolderDisplayPath,
+ skillFolderPathDisplayFallback,
+ subtreeFolderIds,
+} from "./skill-folder-tree";
+
+function folder(partial: Partial<FolderListItem> & { id: string; slug: string; path: string }): FolderListItem {
+ return {
+ companyId: "co",
+ kind: "skill",
+ parentId: null,
+ name: partial.slug,
+ systemKey: null,
+ depth: 1,
+ color: null,
+ position: 0,
+ itemCount: 0,
+ createdAt: new Date(),
+ updatedAt: new Date(),
+ ...partial,
+ };
+}
+
+const folders: FolderListItem[] = [
+ folder({ id: "my", slug: "my", path: "my", systemKey: "my", name: "my", position: 0 }),
+ folder({ id: "mine", slug: "dotta", path: "my/dotta", parentId: "my", systemKey: "my:u1", depth: 2, position: 0 }),
+ folder({ id: "eng", slug: "engineering", path: "engineering", name: "Engineering", position: 1 }),
+ folder({ id: "eng-review", slug: "review", path: "engineering/review", parentId: "eng", depth: 2, name: "Review", position: 0 }),
+ folder({ id: "proj", slug: "projects", path: "projects", systemKey: "projects", name: "projects", position: 2 }),
+ folder({ id: "proj-a", slug: "acme", path: "projects/acme", parentId: "proj", systemKey: "project:a", depth: 2 }),
+ folder({ id: "bundled", slug: "bundled", path: "bundled", systemKey: "bundled", name: "bundled", position: 3 }),
+ folder({ id: "bundled-git", slug: "git", path: "bundled/git", parentId: "bundled", systemKey: "bundled:git", depth: 2 }),
+];
+
+describe("buildSkillFolderTree", () => {
+ it("groups reserved roots and company folders in order", () => {
+ const model = buildSkillFolderTree(folders);
+ expect(model.my?.folder.id).toBe("my");
+ expect(model.projects?.folder.id).toBe("proj");
+ expect(model.bundled?.folder.id).toBe("bundled");
+ expect(model.company.map((n) => n.folder.id)).toEqual(["eng"]);
+ // Ordered roots: My → company → Projects → Bundled.
+ expect(model.roots.map((n) => n.folder.id)).toEqual(["my", "eng", "proj", "bundled"]);
+ });
+
+ it("nests children under their parent", () => {
+ const model = buildSkillFolderTree(folders);
+ expect(model.my?.children.map((n) => n.folder.id)).toEqual(["mine"]);
+ expect(model.company[0]?.children.map((n) => n.folder.id)).toEqual(["eng-review"]);
+ expect(model.childrenById.get("bundled")?.map((n) => n.folder.id)).toEqual(["bundled-git"]);
+ });
+});
+
+describe("subtreeFolderIds", () => {
+ it("includes the folder and all descendants", () => {
+ const model = buildSkillFolderTree(folders);
+ expect([...subtreeFolderIds(model, "eng")].sort()).toEqual(["eng", "eng-review"]);
+ expect([...subtreeFolderIds(model, "my")].sort()).toEqual(["mine", "my"]);
+ expect([...subtreeFolderIds(model, "eng-review")]).toEqual(["eng-review"]);
+ });
+});
+
+describe("folderBreadcrumbTrail", () => {
+ it("walks from top-level root down to the target", () => {
+ const model = buildSkillFolderTree(folders);
+ expect(folderBreadcrumbTrail(model, "eng-review").map((f) => f.id)).toEqual(["eng", "eng-review"]);
+ expect(folderBreadcrumbTrail(model, "mine").map((f) => f.id)).toEqual(["my", "mine"]);
+ });
+});
+
+describe("reserved subtree detection", () => {
+ it("flags bundled root and descendants", () => {
+ expect(isBundledFolder({ path: "bundled", systemKey: "bundled" })).toBe(true);
+ expect(isBundledFolder({ path: "bundled/git", systemKey: "bundled:git" })).toBe(true);
+ expect(isBundledFolder({ path: "engineering", systemKey: null })).toBe(false);
+ });
+
+ it("flags projects root and descendants", () => {
+ expect(isProjectsFolder({ path: "projects", systemKey: "projects" })).toBe(true);
+ expect(isProjectsFolder({ path: "projects/acme", systemKey: "project:a" })).toBe(true);
+ expect(isProjectsFolder({ path: "my/dotta", systemKey: "my:u1" })).toBe(false);
+ });
+});
+
+describe("reservedRootLabel", () => {
+ it("renames reserved roots and passes through others", () => {
+ expect(reservedRootLabel({ systemKey: "my", name: "my" })).toBe("My Skills");
+ expect(reservedRootLabel({ systemKey: "projects", name: "projects" })).toBe("Projects");
+ expect(reservedRootLabel({ systemKey: "bundled", name: "bundled" })).toBe("Bundled");
+ expect(reservedRootLabel({ systemKey: null, name: "Engineering" })).toBe("Engineering");
+ });
+});
+
+describe("skillFolderDisplayPath", () => {
+ it("prefixes company folders and preserves reserved-root labels", () => {
+ const model = buildSkillFolderTree(folders);
+ expect(skillFolderDisplayPath(model, "eng-review")).toBe("Company / Engineering / Review");
+ expect(skillFolderDisplayPath(model, "mine")).toBe("My Skills / dotta");
+ expect(skillFolderDisplayPath(model, "bundled-git")).toBe("Bundled / git");
+ expect(skillFolderDisplayPath(model, null)).toBeNull();
+ });
+});
+
+describe("skillFolderPathDisplayFallback", () => {
+ it("humanizes cold detail paths before folder metadata loads", () => {
+ expect(skillFolderPathDisplayFallback("engineering/code-review")).toBe("Company / Engineering / Code Review");
+ expect(skillFolderPathDisplayFallback("my/local-board/drafts")).toBe("My Skills / Local Board / Drafts");
+ expect(skillFolderPathDisplayFallback("bundled/review-pr")).toBe("Bundled / Review Pr");
+ expect(skillFolderPathDisplayFallback(null)).toBeNull();
+ });
+});
diff --git a/ui/src/components/folders/skill-folder-tree.ts b/ui/src/components/folders/skill-folder-tree.ts
new file mode 100644
index 0000000000..e7ba740fe4
--- /dev/null
+++ b/ui/src/components/folders/skill-folder-tree.ts
@@ -0,0 +1,202 @@
+import type { FolderListItem, FolderListResult } from "@paperclipai/shared";
+
+/**
+ * Pure tree helpers for the skill folder browser (Idea A, PAP-14038).
+ *
+ * The server returns a *flat* {@link FolderListResult}; every folder carries a
+ * `parentId`, a canonical slug `path` (root = slug, children = `parent/slug`),
+ * a `depth`, and a `systemKey`. Reserved roots have a stable `systemKey`:
+ * - `my` → "My Skills" (personal folders live beneath it as `my:<userId>`)
+ * - `projects` → "Projects" (auto-created project folders `project:<id>`)
+ * - `bundled` → "Bundled" (read-only; categories `bundled:<slug>`)
+ * Everything else at the top level is a plain company folder and is grouped
+ * under the virtual "Company" heading in the rail.
+ */
+
+export interface FolderTreeNode {
+ folder: FolderListItem;
+ children: FolderTreeNode[];
+}
+
+export type ReservedRootKey = "my" | "projects" | "bundled";
+
+export interface SkillFolderTreeModel {
+ /** "My Skills" reserved root, or null when it hasn't been provisioned yet. */
+ my: FolderTreeNode | null;
+ /** Non-reserved top-level folders, shown under the "Company" heading. */
+ company: FolderTreeNode[];
+ /** "Projects" reserved root. */
+ projects: FolderTreeNode | null;
+ /** "Bundled" reserved root (read-only subtree). */
+ bundled: FolderTreeNode | null;
+ /** Every folder by id, for O(1) lookups. */
+ byId: Map<string, FolderListItem>;
+ /** Direct child nodes for a given folder id. */
+ childrenById: Map<string, FolderTreeNode[]>;
+ /** All top-level nodes in reserved-then-company order (for move pickers). */
+ roots: FolderTreeNode[];
+}
+
+const RESERVED_ROOT_SYSTEM_KEYS = new Set<string>(["my", "projects", "bundled"]);
+
+export function isReservedRootSystemKey(systemKey: string | null | undefined): boolean {
+ return Boolean(systemKey && RESERVED_ROOT_SYSTEM_KEYS.has(systemKey));
+}
+
+/** True for the Bundled root or anything nested inside it (read-only subtree). */
+export function isBundledFolder(folder: Pick<FolderListItem, "path" | "systemKey">): boolean {
+ if (folder.systemKey === "bundled" || folder.systemKey?.startsWith("bundled:")) return true;
+ return folder.path === "bundled" || folder.path.startsWith("bundled/");
+}
+
+/** True for the Projects root or anything nested inside it (auto-managed subtree). */
+export function isProjectsFolder(folder: Pick<FolderListItem, "path" | "systemKey">): boolean {
+ if (folder.systemKey === "projects" || folder.systemKey?.startsWith("project:")) return true;
+ return folder.path === "projects" || folder.path.startsWith("projects/");
+}
+
+function sortNodes(nodes: FolderTreeNode[]): void {
+ nodes.sort(
+ (a, b) => a.folder.position - b.folder.position || a.folder.name.localeCompare(b.folder.name),
+ );
+ for (const node of nodes) sortNodes(node.children);
+}
+
+export function buildSkillFolderTree(folders: FolderListItem[]): SkillFolderTreeModel {
+ const byId = new Map<string, FolderListItem>();
+ const nodeById = new Map<string, FolderTreeNode>();
+ for (const folder of folders) {
+ byId.set(folder.id, folder);
+ nodeById.set(folder.id, { folder, children: [] });
+ }
+
+ const roots: FolderTreeNode[] = [];
+ for (const folder of folders) {
+ const node = nodeById.get(folder.id)!;
+ const parent = folder.parentId ? nodeById.get(folder.parentId) : null;
+ if (parent) parent.children.push(node);
+ else roots.push(node);
+ }
+ sortNodes(roots);
+
+ let my: FolderTreeNode | null = null;
+ let projects: FolderTreeNode | null = null;
+ let bundled: FolderTreeNode | null = null;
+ const company: FolderTreeNode[] = [];
+ for (const node of roots) {
+ switch (node.folder.systemKey) {
+ case "my":
+ my = node;
+ break;
+ case "projects":
+ projects = node;
+ break;
+ case "bundled":
+ bundled = node;
+ break;
+ default:
+ company.push(node);
+ }
+ }
+
+ const childrenById = new Map<string, FolderTreeNode[]>();
+ for (const [id, node] of nodeById) childrenById.set(id, node.children);
+
+ // Ordered roots: reserved first (My → Projects → Bundled), then company folders.
+ const orderedRoots: FolderTreeNode[] = [];
+ if (my) orderedRoots.push(my);
+ orderedRoots.push(...company);
+ if (projects) orderedRoots.push(projects);
+ if (bundled) orderedRoots.push(bundled);
+
+ return { my, company, projects, bundled, byId, childrenById, roots: orderedRoots };
+}
+
+/** Folder id + every descendant id (the subtree rooted at `folderId`). */
+export function subtreeFolderIds(model: SkillFolderTreeModel, folderId: string): Set<string> {
+ const out = new Set<string>([folderId]);
+ const queue = [folderId];
+ while (queue.length > 0) {
+ const id = queue.pop()!;
+ for (const child of model.childrenById.get(id) ?? []) {
+ if (!out.has(child.folder.id)) {
+ out.add(child.folder.id);
+ queue.push(child.folder.id);
+ }
+ }
+ }
+ return out;
+}
+
+/** The chain of folders from the top-level root down to `folderId` (inclusive). */
+export function folderBreadcrumbTrail(
+ model: SkillFolderTreeModel,
+ folderId: string,
+): FolderListItem[] {
+ const trail: FolderListItem[] = [];
+ let current: FolderListItem | undefined = model.byId.get(folderId);
+ const guard = new Set<string>();
+ while (current && !guard.has(current.id)) {
+ guard.add(current.id);
+ trail.unshift(current);
+ current = current.parentId ? model.byId.get(current.parentId) : undefined;
+ }
+ return trail;
+}
+
+/** Human label for a reserved root, used when composing breadcrumb prefixes. */
+export function reservedRootLabel(folder: Pick<FolderListItem, "systemKey" | "name">): string {
+ switch (folder.systemKey) {
+ case "my":
+ return "My Skills";
+ case "projects":
+ return "Projects";
+ case "bundled":
+ return "Bundled";
+ default:
+ return folder.name;
+ }
+}
+
+/** Human-readable canonical path used by detail surfaces and breadcrumbs. */
+export function skillFolderDisplayPath(
+ model: SkillFolderTreeModel,
+ folderId: string | null | undefined,
+): string | null {
+ if (!folderId) return null;
+ const trail = folderBreadcrumbTrail(model, folderId);
+ if (trail.length === 0) return null;
+ const labels = trail.map((folder) => reservedRootLabel(folder));
+ if (!trail[0]?.systemKey) labels.unshift("Company");
+ return labels.join(" / ");
+}
+
+function humanizeFolderPathSegment(segment: string): string {
+ return segment
+ .replace(/[-_]+/g, " ")
+ .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+export function skillFolderPathDisplayFallback(folderPath: string | null | undefined): string | null {
+ if (!folderPath) return null;
+ if (folderPath.includes(" / ")) return folderPath;
+
+ const segments = folderPath.split("/").filter(Boolean);
+ if (segments.length === 0) return null;
+
+ const root = segments[0]?.toLowerCase();
+ const labels = segments.map(humanizeFolderPathSegment);
+ if (root === "my") labels[0] = "My Skills";
+ else if (root === "projects") labels[0] = "Projects";
+ else if (root === "bundled") labels[0] = "Bundled";
+ else labels.unshift("Company");
+ return labels.join(" / ");
+}
+
+export function emptySkillFolderTree(): SkillFolderTreeModel {
+ return buildSkillFolderTree([]);
+}
+
+export function treeFromResult(result: FolderListResult | null | undefined): SkillFolderTreeModel {
+ return buildSkillFolderTree(result?.folders ?? []);
+}
diff --git a/ui/src/index.css b/ui/src/index.css
index a850c8179a..fced100ebc 100644
--- a/ui/src/index.css
+++ b/ui/src/index.css
@@ -182,6 +182,17 @@
--status-task-icon-blocked: var(--status-task-blocked); /* #dc2626 both modes */
--status-task-icon-cancelled: #52585d;
--status-task-icon-in_queue: var(--status-task-in_progress); /* blocked shape, blue */
+
+ --folder-color-indigo: #6366f1;
+ --folder-color-violet: #8b5cf6;
+ --folder-color-emerald: #10b981;
+ --folder-color-cyan: #06b6d4;
+ --folder-color-amber: #f59e0b;
+ --folder-color-slate: #64748b;
+ --gtc-folder-row: 1rem minmax(0, 1fr) auto;
+ --gtc-folder-row-actions: 1rem minmax(0, 1fr) auto auto;
+ --sz-folder-rail: 13.25rem;
+ --sz-folder-sheet-max: 80dvh;
}
.dark {
diff --git a/ui/src/lib/company-skill-routes.test.ts b/ui/src/lib/company-skill-routes.test.ts
index 4eb3fb5dbc..5a9acfd60c 100644
--- a/ui/src/lib/company-skill-routes.test.ts
+++ b/ui/src/lib/company-skill-routes.test.ts
@@ -84,5 +84,11 @@ describe("company skill routes", () => {
expect(skillStudioNewRoute("skill/with spaces")).toBe(
"/skills/studio/new?forkFrom=skill%2Fwith%20spaces",
);
+ expect(skillStudioNewRoute(null, "folder/with spaces")).toBe(
+ "/skills/studio/new?folderId=folder%2Fwith%20spaces",
+ );
+ expect(skillStudioNewRoute("skill 1", "folder 1")).toBe(
+ "/skills/studio/new?forkFrom=skill%201&folderId=folder%201",
+ );
});
});
diff --git a/ui/src/lib/company-skill-routes.ts b/ui/src/lib/company-skill-routes.ts
index 66ab5b3515..a24ef75f05 100644
--- a/ui/src/lib/company-skill-routes.ts
+++ b/ui/src/lib/company-skill-routes.ts
@@ -191,9 +191,13 @@ export function skillStudioRoute(skillId: string) {
return `/skills/studio/${encodeURIComponent(skillId)}`;
}
-export function skillStudioNewRoute(forkFromSkillId?: string | null) {
+export function skillStudioNewRoute(forkFromSkillId?: string | null, folderId?: string | null) {
const basePath = "/skills/studio/new";
- return forkFromSkillId ? `${basePath}?forkFrom=${encodeURIComponent(forkFromSkillId)}` : basePath;
+ const params: string[] = [];
+ if (forkFromSkillId) params.push(`forkFrom=${encodeURIComponent(forkFromSkillId)}`);
+ if (folderId) params.push(`folderId=${encodeURIComponent(folderId)}`);
+ const query = params.join("&");
+ return query ? `${basePath}?${query}` : basePath;
}
export function withRouteSkill(
diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.ts
index d1c28321c7..010b49b157 100644
--- a/ui/src/lib/queryKeys.ts
+++ b/ui/src/lib/queryKeys.ts
@@ -193,6 +193,9 @@ export const queryKeys = {
documentAnnotations: (routineId: string, key: "description", status: "open" | "resolved" | "all" = "all") =>
["routines", "document-annotations", routineId, key, status] as const,
},
+ folders: {
+ list: (companyId: string, kind: string) => ["folders", companyId, kind] as const,
+ },
pipelines: {
list: (companyId: string) => ["pipelines", companyId] as const,
detail: (pipelineId: string) => ["pipelines", "detail", pipelineId] as const,
diff --git a/ui/src/lib/skill-create.test.ts b/ui/src/lib/skill-create.test.ts
index 0e9e3351ba..6634dbf2a6 100644
--- a/ui/src/lib/skill-create.test.ts
+++ b/ui/src/lib/skill-create.test.ts
@@ -83,7 +83,7 @@ describe("skill create helpers", () => {
});
it("builds fork drafts from the source skill metadata", () => {
- const draft = buildForkSkillDraft(skill({ color: "#123456" }));
+ const draft = buildForkSkillDraft(skill({ color: "#123456", folderId: "bundled-folder" }));
expect(draft.name).toBe("Demo Skill Fork");
expect(draft.slug).toBe("demo-skill-fork");
@@ -91,6 +91,7 @@ describe("skill create helpers", () => {
expect(draft.categories).toEqual(["engineering", "review"]);
expect(draft.forkedFromSkillId).toBe("skill-1");
expect(draft.forkedFromName).toBe("Demo Skill");
+ expect(draft.folderId).toBeNull();
expect(draft.markdown).toContain("name: Demo Skill Fork");
});
diff --git a/ui/src/lib/skill-create.ts b/ui/src/lib/skill-create.ts
index 6087fbcabc..9d09866c4c 100644
--- a/ui/src/lib/skill-create.ts
+++ b/ui/src/lib/skill-create.ts
@@ -21,6 +21,8 @@ export type SkillCreateDraft = {
sharingScope: Exclude<CompanySkillSharingScope, "public_link">;
forkedFromSkillId: string | null;
forkedFromName: string | null;
+ /** Destination folder for the new skill (null = Unfiled / top level). */
+ folderId: string | null;
};
export function normalizeSkillDraftSlug(value: string) {
@@ -92,6 +94,7 @@ export function buildBlankSkillDraft(): SkillCreateDraft {
sharingScope: "company",
forkedFromSkillId: null,
forkedFromName: null,
+ folderId: null,
};
}
@@ -109,6 +112,7 @@ export function buildForkSkillDraft(skill: CompanySkillDetail): SkillCreateDraft
sharingScope: "company",
forkedFromSkillId: skill.id,
forkedFromName: skill.name,
+ folderId: null,
};
}
@@ -128,5 +132,6 @@ export function skillCreateDraftToPayload(draft: SkillCreateDraft): CompanySkill
categories: draft.categories,
sharingScope: draft.sharingScope,
forkedFromSkillId: draft.forkedFromSkillId,
+ folderId: draft.folderId ?? undefined,
};
}
diff --git a/ui/src/pages/CompanySkills.test.tsx b/ui/src/pages/CompanySkills.test.tsx
index 0ef77bd7f5..5a1485df41 100644
--- a/ui/src/pages/CompanySkills.test.tsx
+++ b/ui/src/pages/CompanySkills.test.tsx
@@ -3,9 +3,16 @@
import type { ComponentProps, ReactNode } from "react";
import { flushSync } from "react-dom";
import { createRoot, type Root } from "react-dom/client";
-import type { CompanySkillDetail, CompanySkillVersion } from "@paperclipai/shared";
+import type { CompanySkillDetail, CompanySkillVersion, FolderListResult } from "@paperclipai/shared";
import { afterEach, describe, expect, it, vi } from "vitest";
-import { DiscoveryGrid, SkillDetailPage, getSkillVersionDiffSelection } from "./CompanySkills";
+import {
+ DiscoveryGrid,
+ SkillDetailPage,
+ getSkillVersionDiffSelection,
+ resolveDiscoveryTab,
+ withDiscoveryTab,
+ skillDetailBreadcrumbs,
+} from "./CompanySkills";
import { skillStudioNewRoute } from "../lib/company-skill-routes";
vi.mock("@/lib/router", () => ({
@@ -51,6 +58,9 @@ vi.mock("@/components/ui/dropdown-menu", () => ({
<button type="button" onClick={onSelect}>{children}</button>
),
DropdownMenuSeparator: () => <hr />,
+ DropdownMenuSub: ({ children }: { children: ReactNode }) => <>{children}</>,
+ DropdownMenuSubContent: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+ DropdownMenuSubTrigger: ({ children }: { children: ReactNode }) => <button type="button">{children}</button>,
DropdownMenuTrigger: ({ children }: { children: ReactNode }) => <>{children}</>,
}));
@@ -327,6 +337,171 @@ describe("DiscoveryGrid Studio entry points", () => {
expect(onCreate).toHaveBeenCalledTimes(2);
});
+
+ it("does not open a skill when keyboard-activating its actions button", async () => {
+ const onOpenCard = vi.fn();
+ const card = {
+ key: "demo-skill",
+ skillId: "skill-1",
+ folderId: null,
+ catalogRef: null,
+ name: "Demo Skill",
+ slug: "demo-skill",
+ author: "Paperclip",
+ version: null,
+ tagline: null,
+ description: null,
+ categories: [],
+ iconUrl: null,
+ color: null,
+ starCount: 0,
+ agentCount: 0,
+ forkCount: 0,
+ installed: true,
+ required: false,
+ forkedFrom: false,
+ updatedAt: 0,
+ };
+ const node = await renderDiscoveryGrid({
+ cards: [card],
+ totalCount: 1,
+ onOpenCard,
+ folderResult: { kind: "skill", folders: [], allCount: 1, unfiledCount: 1 },
+ onMoveCard: vi.fn(),
+ onCreateFolderAndMoveCard: vi.fn(),
+ });
+ const actionsButton = node.querySelector<HTMLButtonElement>('[aria-label="More actions for Demo Skill"]');
+
+ await act(async () => {
+ actionsButton?.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+ });
+
+ expect(onOpenCard).not.toHaveBeenCalled();
+ });
+
+ it("does not offer move actions for skills in the bundled folder", async () => {
+ const card = {
+ key: "bundled-skill",
+ skillId: "skill-1",
+ folderId: "bundled-folder",
+ catalogRef: null,
+ name: "Bundled Skill",
+ slug: "bundled-skill",
+ author: "Paperclip",
+ version: null,
+ tagline: null,
+ description: null,
+ categories: [],
+ iconUrl: null,
+ color: null,
+ starCount: 0,
+ agentCount: 0,
+ forkCount: 0,
+ installed: true,
+ required: false,
+ forkedFrom: false,
+ updatedAt: 0,
+ };
+ const node = await renderDiscoveryGrid({
+ cards: [card],
+ totalCount: 1,
+ selectMode: true,
+ folderResult: {
+ kind: "skill",
+ folders: [{
+ id: "bundled-folder",
+ companyId: "company-1",
+ kind: "skill",
+ parentId: null,
+ name: "Bundled",
+ slug: "bundled",
+ systemKey: "bundled",
+ path: "bundled",
+ depth: 1,
+ color: null,
+ position: 0,
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ updatedAt: new Date("2026-01-01T00:00:00Z"),
+ itemCount: 1,
+ }],
+ allCount: 1,
+ unfiledCount: 0,
+ },
+ onMoveCard: vi.fn(),
+ onCreateFolderAndMoveCard: vi.fn(),
+ onOpenMoveCard: vi.fn(),
+ });
+
+ expect(node.querySelector('[aria-label="More actions for Bundled Skill"]')).toBeNull();
+ expect(node.querySelector('input[type="checkbox"]')).toBeNull();
+ expect(node.textContent).not.toContain("Move to folder");
+ });
+});
+
+describe("skills discovery tab routing", () => {
+ it("opens the folder-first installed view when the URL has no tab", () => {
+ expect(resolveDiscoveryTab(null)).toBe("installed");
+ expect(resolveDiscoveryTab("all")).toBe("all");
+ });
+
+ it("keeps All explicit and makes Installed the canonical default URL", () => {
+ const allParams = withDiscoveryTab(new URLSearchParams("folder=my&category=writing"), "all");
+ expect(allParams.toString()).toBe("tab=all");
+
+ const installedParams = withDiscoveryTab(new URLSearchParams("tab=all&folder=my"), "installed");
+ expect(installedParams.toString()).toBe("folder=my");
+ });
+});
+
+describe("skill detail breadcrumbs", () => {
+ it("links each folder ancestor back to the installed folder view", () => {
+ const folders: FolderListResult = {
+ kind: "skill",
+ allCount: 1,
+ unfiledCount: 0,
+ folders: [
+ {
+ id: "my-root",
+ companyId: "company-1",
+ kind: "skill",
+ parentId: null,
+ name: "My Skills",
+ slug: "my",
+ systemKey: "my",
+ path: "my",
+ depth: 1,
+ color: null,
+ position: 0,
+ itemCount: 1,
+ createdAt: new Date("2026-07-16T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-16T00:00:00.000Z"),
+ },
+ {
+ id: "review-folder",
+ companyId: "company-1",
+ kind: "skill",
+ parentId: "my-root",
+ name: "Review",
+ slug: "review",
+ systemKey: null,
+ path: "my/review",
+ depth: 2,
+ color: null,
+ position: 0,
+ itemCount: 1,
+ createdAt: new Date("2026-07-16T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-16T00:00:00.000Z"),
+ },
+ ],
+ };
+
+ expect(skillDetailBreadcrumbs({ name: "Deal with PR", folderId: "review-folder" }, folders)).toEqual([
+ { label: "Skills", href: "/skills" },
+ { label: "My Skills", href: "/skills?folder=my-root" },
+ { label: "Review", href: "/skills?folder=review-folder" },
+ { label: "Deal with PR" },
+ ]);
+ });
});
describe("skillStudioNewRoute", () => {
@@ -366,6 +541,16 @@ describe("SkillDetailPage versions tab", () => {
});
describe("SkillDetailPage settings", () => {
+ it("humanizes the server folder path on a cold detail render", async () => {
+ const v1 = makeVersion(1, "# Demo Skill");
+ const node = await renderSkillDetail([v1], {
+ activeTab: "overview",
+ detail: makeDetail(v1, { folderPath: "engineering/code-review" }),
+ });
+
+ expect(node.textContent).toContain("Company / Engineering / Code Review");
+ });
+
it("shows a direct fork action for read-only skills", async () => {
const v1 = makeVersion(1, "# Demo Skill");
const onFork = vi.fn();
diff --git a/ui/src/pages/CompanySkills.tsx b/ui/src/pages/CompanySkills.tsx
index e272afc863..864f39a5f3 100644
--- a/ui/src/pages/CompanySkills.tsx
+++ b/ui/src/pages/CompanySkills.tsx
@@ -22,9 +22,10 @@ import type {
CompanySkillVersion,
} from "@paperclipai/shared";
import { companySkillsApi } from "../api/companySkills";
+import { foldersApi } from "../api/folders";
import { agentsApi } from "../api/agents";
import { useCompany } from "../context/CompanyContext";
-import { useBreadcrumbs } from "../context/BreadcrumbContext";
+import { useBreadcrumbs, type Breadcrumb } from "../context/BreadcrumbContext";
import { useToastActions } from "../context/ToastContext";
import { queryKeys } from "../lib/queryKeys";
import { EmptyState } from "../components/EmptyState";
@@ -90,6 +91,31 @@ import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";
import { Badge } from "@/components/ui/badge";
+import {
+ AllUnfiledBanner,
+ BulkBar,
+ DeleteFolderDialog,
+ FolderChip,
+ FolderFormDialog,
+ FolderSwatch,
+ MobileFolderSheet,
+ MoveToMenu,
+ folderSearchValue,
+ normalizeFolderSelection,
+ type FolderSelection,
+} from "../components/folders/FolderControls";
+import {
+ FolderBreadcrumb,
+ MoveToFolderDialog,
+ SkillFolderRail,
+ folderBreadcrumbTrail,
+ reservedRootLabel,
+ isBundledFolder,
+ skillFolderDisplayPath,
+ skillFolderPathDisplayFallback,
+ subtreeFolderIds,
+ treeFromResult,
+} from "../components/folders/SkillFolderTree";
import {
AlertTriangle,
ArrowUpCircle,
@@ -105,6 +131,7 @@ import {
FileCode2,
FileText,
Folder,
+ FolderInput,
FolderOpen,
FolderSearch,
GitFork,
@@ -116,6 +143,7 @@ import {
Lock,
ExternalLink,
FlaskConical,
+ MoreHorizontal,
Paperclip,
Pause,
Pencil,
@@ -130,9 +158,12 @@ import {
Star,
Trash2,
Users,
+ Hash,
History,
+ X,
XOctagon,
} from "lucide-react";
+import type { FolderListItem, FolderListResult } from "@paperclipai/shared";
type SkillTreeNode = {
name: string;
@@ -520,10 +551,42 @@ function formatBytes(bytes: number) {
// Skills Store discovery grid (PAP-10879)
// ---------------------------------------------------------------------------
-type DiscoveryTab = "all" | "installed" | "catalog" | "bundled";
+export type DiscoveryTab = "all" | "installed" | "catalog" | "bundled";
const DISCOVERY_TABS: DiscoveryTab[] = ["all", "installed", "catalog", "bundled"];
+export function resolveDiscoveryTab(tabParam: string | null): DiscoveryTab {
+ return DISCOVERY_TABS.includes(tabParam as DiscoveryTab)
+ ? (tabParam as DiscoveryTab)
+ : "installed";
+}
+
+export function withDiscoveryTab(current: URLSearchParams, tab: DiscoveryTab): URLSearchParams {
+ const params = new URLSearchParams(current);
+ if (tab === "installed") params.delete("tab");
+ else params.set("tab", tab);
+ params.delete("category");
+ if (tab !== "installed") params.delete("folder");
+ return params;
+}
+
+export function skillDetailBreadcrumbs(
+ detail: Pick<CompanySkillDetail, "name" | "folderId">,
+ folderResult: FolderListResult | null | undefined,
+): Breadcrumb[] {
+ const trail = detail.folderId
+ ? folderBreadcrumbTrail(treeFromResult(folderResult), detail.folderId)
+ : [];
+ return [
+ { label: "Skills", href: "/skills" },
+ ...trail.map((folder, index) => ({
+ label: index === 0 ? reservedRootLabel(folder) : folder.name,
+ href: `/skills?folder=${encodeURIComponent(folder.id)}`,
+ })),
+ { label: detail.name },
+ ];
+}
+
type DiscoverySort = "agents" | "stars" | "forks" | "recent" | "alphabetical";
const DISCOVERY_SORT_LABELS: Record<DiscoverySort, string> = {
@@ -539,6 +602,7 @@ const DISCOVERY_SORTS: DiscoverySort[] = ["agents", "stars", "forks", "recent",
export type DiscoveryCard = {
key: string;
skillId: string | null;
+ folderId?: string | null;
catalogRef: string | null;
name: string;
slug: string;
@@ -612,6 +676,7 @@ function buildDiscoveryCards(
cards.push({
key: skill.key,
skillId: skill.id,
+ folderId: skill.folderId ?? null,
catalogRef: catalogMatch ? catalogMatch.id : null,
name: skill.name,
slug: skill.slug,
@@ -640,6 +705,7 @@ function buildDiscoveryCards(
cards.push({
key: entry.key,
skillId: null,
+ folderId: null,
catalogRef: entry.id,
name: entry.name,
slug: entry.slug,
@@ -732,11 +798,49 @@ function SkillCategoryChip({ label }: { label: string }) {
);
}
-function SkillCard({ card, onOpen }: { card: DiscoveryCard; onOpen: (card: DiscoveryCard) => void }) {
+function SkillCard({
+ card,
+ folders,
+ selected = false,
+ selectMode = false,
+ showFolderBadge = false,
+ onOpen,
+ onSelectChange,
+ onMove,
+ onCreateFolderAndMove,
+ onOpenMove,
+}: {
+ card: DiscoveryCard;
+ folders?: FolderListItem[];
+ selected?: boolean;
+ selectMode?: boolean;
+ /** Show the card's folder so search results reveal where an item lives (user story 5). */
+ showFolderBadge?: boolean;
+ onOpen: (card: DiscoveryCard) => void;
+ onSelectChange?: (card: DiscoveryCard, selected: boolean) => void;
+ onMove?: (card: DiscoveryCard, folderId: string | null) => void;
+ onCreateFolderAndMove?: (card: DiscoveryCard) => void;
+ onOpenMove?: (card: DiscoveryCard) => void;
+}) {
+ const badgeFolder = showFolderBadge && card.installed
+ ? (card.folderId ? folders?.find((folder) => folder.id === card.folderId) ?? null : null)
+ : undefined;
+ const cardFolder = card.folderId ? folders?.find((folder) => folder.id === card.folderId) ?? null : null;
+ const canMove = card.installed
+ && !card.required
+ && !(cardFolder && isBundledFolder(cardFolder));
return (
- <button
- type="button"
+ <div
onClick={() => onOpen(card)}
+ onKeyDown={(event) => {
+ if (event.target !== event.currentTarget) return;
+ if (event.key === "Enter" || event.key === " ") {
+ event.preventDefault();
+ onOpen(card);
+ }
+ }}
+ role="button"
+ tabIndex={0}
className={cn(
// Quiet interactive-card affordance (DECISION-SHEET: one recipe for
// clickable cards): pointer cursor, border darkens, slight lift.
@@ -745,12 +849,28 @@ function SkillCard({ card, onOpen }: { card: DiscoveryCard; onOpen: (card: Disco
)}
>
<div className="flex items-start gap-3">
+ {selectMode && canMove ? (
+ <input
+ type="checkbox"
+ className="mt-1 h-4 w-4 rounded border-border"
+ checked={selected}
+ aria-label={`Select ${card.name}`}
+ onClick={(event) => event.stopPropagation()}
+ onChange={(event) => onSelectChange?.(card, event.target.checked)}
+ />
+ ) : null}
<SkillCardIcon card={card} />
<div className="min-w-0 flex-1">
<div className="truncate font-mono text-sm font-medium text-foreground">{card.name}</div>
<div className="truncate text-xs text-muted-foreground">
by {card.author}{card.version ? ` · ${card.version}` : ""}
</div>
+ {badgeFolder !== undefined ? (
+ <div className="mt-1 flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground">
+ <FolderSwatch color={badgeFolder?.color} className="h-2 w-2" />
+ <span className="truncate">{badgeFolder ? badgeFolder.name : "Unfiled"}</span>
+ </div>
+ ) : null}
</div>
{/* Where the skill came from (PAP-10907 E); native title gives a hover hint. */}
{(() => {
@@ -762,6 +882,38 @@ function SkillCard({ card, onOpen }: { card: DiscoveryCard; onOpen: (card: Disco
</span>
);
})()}
+ {canMove && folders && onMove && onCreateFolderAndMove ? (
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button
+ variant="ghost"
+ size="icon-sm"
+ className="-mr-1 -mt-1 opacity-70 group-hover:opacity-100"
+ aria-label={`More actions for ${card.name}`}
+ onClick={(event) => event.stopPropagation()}
+ >
+ <MoreHorizontal className="h-4 w-4" />
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end" onClick={(event) => event.stopPropagation()}>
+ {onOpenMove ? (
+ <>
+ <DropdownMenuItem onSelect={() => onOpenMove(card)}>
+ <FolderInput className="h-3.5 w-3.5" />
+ Move to folder…
+ </DropdownMenuItem>
+ <DropdownMenuSeparator />
+ </>
+ ) : null}
+ <MoveToMenu
+ folders={folders}
+ currentFolderId={card.folderId}
+ onMove={(folderId) => onMove(card, folderId)}
+ onCreateAndMove={() => onCreateFolderAndMove(card)}
+ />
+ </DropdownMenuContent>
+ </DropdownMenu>
+ ) : null}
</div>
{card.forkedFrom ? (
@@ -815,7 +967,7 @@ function SkillCard({ card, onOpen }: { card: DiscoveryCard; onOpen: (card: Disco
) : null}
</div>
</div>
- </button>
+ </div>
);
}
@@ -887,6 +1039,29 @@ export function DiscoveryGrid({
onScan,
scanPending,
scanStatus,
+ folderResult,
+ folderSelection = "all",
+ foldersLoading = false,
+ selectMode = false,
+ selectedSkillIds = [],
+ onFolderSelect,
+ onCreateFolder,
+ onRenameFolder,
+ onEditFolder,
+ onMoveFolder,
+ onDeleteFolder,
+ onToggleSelectMode,
+ onSelectCard,
+ onMoveCard,
+ onCreateFolderAndMoveCard,
+ onMoveSelected,
+ onCreateFolderAndMoveSelected,
+ onClearSelected,
+ onOpenMobileFolders,
+ onCreateFolderIn,
+ onEnsureMyFolder,
+ onOpenMoveCard,
+ folderNudgeStorageKey,
}: {
tab: DiscoveryTab;
tabCounts: Record<DiscoveryTab, number>;
@@ -911,6 +1086,33 @@ export function DiscoveryGrid({
onScan: () => void;
scanPending: boolean;
scanStatus: string | null;
+ folderResult?: FolderListResult | null;
+ folderSelection?: FolderSelection;
+ foldersLoading?: boolean;
+ selectMode?: boolean;
+ selectedSkillIds?: string[];
+ onFolderSelect?: (selection: FolderSelection) => void;
+ onCreateFolder?: () => void;
+ onRenameFolder?: (folder: FolderListItem, name: string) => void;
+ onEditFolder?: (folder: FolderListItem) => void;
+ onMoveFolder?: (folder: FolderListItem, destination: "my" | "company") => void;
+ onDeleteFolder?: (folder: FolderListItem) => void;
+ onToggleSelectMode?: () => void;
+ onSelectCard?: (card: DiscoveryCard, selected: boolean) => void;
+ onMoveCard?: (card: DiscoveryCard, folderId: string | null) => void;
+ onCreateFolderAndMoveCard?: (card: DiscoveryCard) => void;
+ onMoveSelected?: (folderId: string | null) => void;
+ onCreateFolderAndMoveSelected?: () => void;
+ onClearSelected?: () => void;
+ onOpenMobileFolders?: () => void;
+ /** Create a folder under `parentId` (null = top level), used by the tree rail. */
+ onCreateFolderIn?: (parentId: string | null) => void;
+ /** Provision the caller's personal "My Skills" root on demand. */
+ onEnsureMyFolder?: () => void;
+ /** Open the rich move-to-folder dialog for a single card. */
+ onOpenMoveCard?: (card: DiscoveryCard) => void;
+ /** When set and no folders exist yet, show the dismissible all-unfiled nudge (ux-spec §6.3). */
+ folderNudgeStorageKey?: string;
}) {
// Source filter (github / skills.sh / local / …) lives in the grid so it
// narrows whatever the parent already filtered by tab/category/search (PAP-10907 E).
@@ -930,15 +1132,40 @@ export function DiscoveryGrid({
[cards, sourceBadgeFilter],
);
const sourceFilterActive = sourceBadgeFilter !== "all";
+ const folderActionsReady = Boolean(
+ onCreateFolderIn && onRenameFolder && onEditFolder && onMoveFolder && onDeleteFolder,
+ );
+ // The nested folder tree owns the left rail whenever folders (reserved roots
+ // or user folders) exist for the installed view.
+ const showFolderRail = Boolean(folderResult && folderResult.folders.length > 0 && onFolderSelect && folderActionsReady);
return (
// On desktop the store is bounded to the viewport so the category sidebar
// and the results pane each scroll independently (PAP-10907). Mobile keeps
// the natural page flow.
<div className="flex min-h-(--sz-calc-30) md:h-(--sz-calc-33) md:min-h-0 md:overflow-hidden">
+ {showFolderRail ? (
+ <div className="hidden shrink-0 pl-4 pt-4 md:block">
+ <SkillFolderRail
+ result={folderResult}
+ selection={folderSelection}
+ loading={foldersLoading}
+ tags={categories}
+ activeTag={activeCategory}
+ onSelect={onFolderSelect!}
+ onSelectTag={onCategoryChange}
+ onCreateFolder={onCreateFolderIn!}
+ onRenameFolder={onRenameFolder!}
+ onEditFolder={onEditFolder!}
+ onMoveFolder={onMoveFolder!}
+ onDeleteFolder={onDeleteFolder!}
+ onEnsureMyFolder={onEnsureMyFolder}
+ />
+ </div>
+ ) : null}
{/* Secondary category sidebar — the main app nav collapses to a rail while
this is present (handled in Layout). */}
- <aside className="hidden w-60 shrink-0 flex-col overflow-hidden border-r border-border md:flex">
+ <aside className={cn("hidden w-60 shrink-0 flex-col overflow-hidden border-r border-border md:flex", showFolderRail && "md:hidden")}>
<div className="border-b border-border px-4 py-4">
<h2 className="text-sm font-semibold text-foreground">Skills Store</h2>
<p className="text-xs text-muted-foreground">Discover, install, fork, share</p>
@@ -1051,6 +1278,27 @@ export function DiscoveryGrid({
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
+ {folderResult && onFolderSelect ? (
+ <div className="w-full md:hidden">
+ <FolderChip
+ result={folderResult}
+ selection={folderSelection}
+ allLabel="All skills"
+ onClick={onOpenMobileFolders ?? (() => undefined)}
+ />
+ </div>
+ ) : null}
+ {onCreateFolder ? (
+ <Button variant="outline" size="sm" onClick={onCreateFolder}>
+ <Plus className="mr-1 h-3.5 w-3.5" />
+ New folder
+ </Button>
+ ) : null}
+ {onToggleSelectMode ? (
+ <Button variant="ghost" size="sm" onClick={onToggleSelectMode}>
+ {selectMode ? "Done" : "Select"}
+ </Button>
+ ) : null}
</div>
{/* Mobile category selector (sidebar is hidden below md) */}
@@ -1107,6 +1355,30 @@ export function DiscoveryGrid({
{/* Grid body */}
<div className="min-h-0 flex-1 overflow-auto p-4">
{scanStatus ? <p className="mb-3 text-xs text-muted-foreground">{scanStatus}</p> : null}
+ {showFolderRail && onFolderSelect ? (
+ <div className="mb-4">
+ <FolderBreadcrumb result={folderResult} selection={folderSelection} onSelect={onFolderSelect} />
+ </div>
+ ) : null}
+ {folderNudgeStorageKey && onCreateFolder && folderResult && folderResult.folders.length === 0 && !loading && cards.length > 0 ? (
+ <AllUnfiledBanner
+ storageKey={folderNudgeStorageKey}
+ itemLabelPlural="skills"
+ onCreateFolder={onCreateFolder}
+ />
+ ) : null}
+ {selectMode && onMoveSelected && onCreateFolderAndMoveSelected && onClearSelected ? (
+ <div className="mb-3">
+ <BulkBar
+ selectedCount={selectedSkillIds.length}
+ folders={folderResult?.folders ?? []}
+ onMove={onMoveSelected}
+ onCreateAndMove={onCreateFolderAndMoveSelected}
+ onClear={onClearSelected}
+ onDone={onToggleSelectMode ?? onClearSelected}
+ />
+ </div>
+ ) : null}
{loading ? (
<PageSkeleton variant="list" />
) : error ? (
@@ -1156,7 +1428,19 @@ export function DiscoveryGrid({
</p>
<div className="grid gap-3 [grid-template-columns:repeat(auto-fill,minmax(19rem,1fr))]">
{sourceFilteredCards.map((card) => (
- <SkillCard key={card.key} card={card} onOpen={onOpenCard} />
+ <SkillCard
+ key={card.key}
+ card={card}
+ folders={folderResult?.folders}
+ selected={selectedSkillIds.includes(card.skillId ?? "")}
+ selectMode={selectMode}
+ showFolderBadge={Boolean(folderResult && search.trim())}
+ onOpen={onOpenCard}
+ onSelectChange={onSelectCard}
+ onMove={onMoveCard}
+ onCreateFolderAndMove={onCreateFolderAndMoveCard}
+ onOpenMove={onOpenMoveCard}
+ />
))}
</div>
</>
@@ -2352,8 +2636,124 @@ function SkillVersionDiffDialog({
);
}
+/**
+ * Canonical-path block for the skill detail (wireframe screen 5): the folder
+ * location is a first-class element with Copy and Move actions. The `skill://`
+ * link and skill id survive folder moves, so the path is presentational.
+ */
+function SkillLocationCard({
+ folderPath,
+ onMove,
+}: {
+ folderPath: string | null | undefined;
+ onMove?: () => void;
+}) {
+ const [copied, setCopied] = useState(false);
+ const canonical = folderPath && folderPath.length > 0 ? folderPath : "Unfiled";
+ return (
+ <section>
+ <div className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">Location</div>
+ <div className="flex items-center gap-2 rounded-md border border-border bg-muted/30 px-2.5 py-1.5">
+ <FolderOpen className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+ <span className="min-w-0 flex-1 truncate font-mono text-xs text-foreground" title={canonical}>{canonical}</span>
+ </div>
+ <div className="mt-2 flex items-center gap-2">
+ <Button
+ size="sm"
+ variant="outline"
+ onClick={() => {
+ void navigator.clipboard?.writeText(canonical).then(() => {
+ setCopied(true);
+ window.setTimeout(() => setCopied(false), 1500);
+ });
+ }}
+ >
+ <Copy className="mr-1.5 h-3.5 w-3.5" />
+ {copied ? "Copied" : "Copy path"}
+ </Button>
+ {onMove ? (
+ <Button size="sm" variant="outline" onClick={onMove}>
+ <FolderInput className="mr-1.5 h-3.5 w-3.5" />
+ Move
+ </Button>
+ ) : null}
+ </div>
+ </section>
+ );
+}
+
+/**
+ * Inline tags editor for the skill detail. Tags are the skill's `categories[]`
+ * presented as first-class chips — there is no separate "tags" field.
+ */
+function SkillTagsEditor({
+ categories,
+ pending,
+ onSave,
+}: {
+ categories: string[];
+ pending: boolean;
+ onSave: (categories: string[]) => void;
+}) {
+ const [draft, setDraft] = useState("");
+ function addTag(raw: string) {
+ const tag = raw.trim().toLowerCase();
+ if (!tag || categories.includes(tag)) {
+ setDraft("");
+ return;
+ }
+ onSave([...categories, tag]);
+ setDraft("");
+ }
+ return (
+ <section>
+ <div className="mb-2 flex items-center gap-1.5 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+ <Hash className="h-3 w-3" />
+ Tags
+ </div>
+ <div className="flex flex-wrap gap-1.5">
+ {categories.map((tag) => (
+ <span
+ key={tag}
+ className="inline-flex items-center gap-1 rounded-full border border-border bg-accent/40 px-2 py-0.5 text-xs text-foreground"
+ >
+ {tag}
+ <button
+ type="button"
+ aria-label={`Remove tag ${tag}`}
+ disabled={pending}
+ onClick={() => onSave(categories.filter((entry) => entry !== tag))}
+ className="text-muted-foreground hover:text-foreground disabled:opacity-50"
+ >
+ <X className="h-3 w-3" />
+ </button>
+ </span>
+ ))}
+ {categories.length === 0 ? (
+ <span className="text-xs text-muted-foreground">No tags yet.</span>
+ ) : null}
+ </div>
+ <Input
+ value={draft}
+ onChange={(event) => setDraft(event.target.value)}
+ onKeyDown={(event) => {
+ if (event.key === "Enter") {
+ event.preventDefault();
+ addTag(draft);
+ }
+ }}
+ onBlur={() => draft.trim() && addTag(draft)}
+ placeholder="Add a tag…"
+ disabled={pending}
+ className="mt-2 h-8 text-sm"
+ />
+ </section>
+ );
+}
+
export function SkillDetailPage({
detail,
+ folderDisplayPath,
catalogSource,
routeSkills,
loading,
@@ -2389,11 +2789,13 @@ export function SkillDetailPage({
onFork,
onUpdateSettings,
updateSettingsPending,
+ onMoveToFolder,
onDelete,
deletePending,
studioHref,
}: {
detail: CompanySkillDetail | null | undefined;
+ folderDisplayPath?: string | null;
catalogSource?: CatalogSkillSource | null;
routeSkills?: CompanySkillRouteSubject[];
loading: boolean;
@@ -2429,6 +2831,8 @@ export function SkillDetailPage({
onFork: () => void;
onUpdateSettings: (payload: Pick<CompanySkillUpdateRequest, "categories" | "sharingScope">) => void;
updateSettingsPending: boolean;
+ /** Open the rich move-to-folder dialog for this skill. */
+ onMoveToFolder?: () => void;
onDelete: () => void;
deletePending: boolean;
studioHref?: string;
@@ -2923,6 +3327,15 @@ export function SkillDetailPage({
</main>
<aside className="min-w-0 space-y-6 border-t border-border pt-4 xl:border-l xl:border-t-0 xl:pl-5 xl:pt-0">
+ <SkillLocationCard
+ folderPath={folderDisplayPath ?? skillFolderPathDisplayFallback(detail.folderPath)}
+ onMove={onMoveToFolder}
+ />
+ <SkillTagsEditor
+ categories={detail.categories}
+ pending={updateSettingsPending}
+ onSave={(categories) => onUpdateSettings({ categories, sharingScope: detail.sharingScope === "public_link" ? "company" : detail.sharingScope })}
+ />
<section>
<div className="mb-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">Agents</div>
<div className="space-y-3">
@@ -3550,6 +3963,18 @@ export function CompanySkills() {
const [createError, setCreateError] = useState<string | null>(null);
const [importDialogOpen, setImportDialogOpen] = useState(false);
const [importFromProjectOpen, setImportFromProjectOpen] = useState(false);
+ const [folderDialogOpen, setFolderDialogOpen] = useState(false);
+ const [folderDialogTarget, setFolderDialogTarget] = useState<FolderListItem | null>(null);
+ const [folderDialogParentId, setFolderDialogParentId] = useState<string | null>(null);
+ const [deleteFolderTarget, setDeleteFolderTarget] = useState<FolderListItem | null>(null);
+ const [mobileFoldersOpen, setMobileFoldersOpen] = useState(false);
+ // Rich move-to-folder dialog (tree picker + inline new-folder + path preview).
+ const [moveDialog, setMoveDialog] = useState<
+ { skillIds: string[]; title: string; subtitle: string | null; currentFolderId: string | null } | null
+ >(null);
+ const [selectMode, setSelectMode] = useState(false);
+ const [selectedSkillIds, setSelectedSkillIds] = useState<string[]>([]);
+ const [moveAfterCreateSkillIds, setMoveAfterCreateSkillIds] = useState<string[]>([]);
const parsedRoute = useMemo(() => parseSkillRoute(routePath), [routePath]);
const isStudioNew = routePath === "studio/new";
const routeSkillToken = isStudioNew ? null : parsedRoute.skillToken;
@@ -3562,9 +3987,7 @@ export function CompanySkills() {
: "all";
const selectedCatalogRef = searchParams.get("catalog");
const tabParam = searchParams.get("tab");
- const discoveryTab: DiscoveryTab = DISCOVERY_TABS.includes(tabParam as DiscoveryTab)
- ? (tabParam as DiscoveryTab)
- : "all";
+ const discoveryTab = resolveDiscoveryTab(tabParam);
const detailTab: SkillDetailTab = (["overview", "files", "versions", "agents"] as SkillDetailTab[]).includes(tabParam as SkillDetailTab)
? (tabParam as SkillDetailTab)
: parsedRoute.hasExplicitFilePath || selectedPath !== "SKILL.md"
@@ -3572,20 +3995,35 @@ export function CompanySkills() {
: "overview";
const discoveryCategory = searchParams.get("category");
const studioForkFromId = isStudioNew ? searchParams.get("forkFrom")?.trim() || null : null;
+ const studioNewFolderId = isStudioNew ? searchParams.get("folderId")?.trim() || null : null;
// Discovery grid owns `/skills` whenever no specific skill or catalog entry is
// selected; selecting either drops into the existing master/detail surfaces.
const isDiscovery = !isStudioNew && !routeSkillToken && !selectedCatalogRef;
+ const folderSelection = normalizeFolderSelection(searchParams.get("folder"));
function setDiscoveryTab(tab: DiscoveryTab) {
+ setSearchParams((current) => withDiscoveryTab(current, tab));
+ }
+
+ function setFolderSelection(selection: FolderSelection) {
setSearchParams((current) => {
const params = new URLSearchParams(current);
- if (tab === "all") params.delete("tab");
- else params.set("tab", tab);
+ params.set("tab", "installed");
params.delete("category");
+ const value = folderSearchValue(selection);
+ if (value) params.set("folder", value);
+ else params.delete("folder");
return params;
});
}
+ function openCreateFolder(moveSkillIds: string[] = [], parentId: string | null = null) {
+ setMoveAfterCreateSkillIds(moveSkillIds);
+ setFolderDialogTarget(null);
+ setFolderDialogParentId(parentId);
+ setFolderDialogOpen(true);
+ }
+
function setDetailTab(tab: SkillDetailTab) {
setSearchParams((current) => {
const params = new URLSearchParams(current);
@@ -3628,13 +4066,6 @@ export function CompanySkills() {
setCreateError(null);
}, [isStudioNew, studioForkFromId]);
- useEffect(() => {
- setBreadcrumbs([
- { label: "Skills", href: "/skills" },
- ...(isStudioNew ? [{ label: studioForkFromId ? "Fork skill" : "New skill" }] : routeSkillToken ? [{ label: "Detail" }] : []),
- ]);
- }, [isStudioNew, routeSkillToken, setBreadcrumbs, studioForkFromId]);
-
// The old split catalog view no longer exists — catalog/bundled skills now open
// as a regular full page keyed by `?catalog=<ref>`. Strip the legacy `view`
// param so stale `?view=catalog` deep links land on the new surface (PAP-10907).
@@ -3655,6 +4086,11 @@ export function CompanySkills() {
queryFn: () => companySkillsApi.list(selectedCompanyId!),
enabled: Boolean(selectedCompanyId),
});
+ const skillFoldersQuery = useQuery({
+ queryKey: queryKeys.folders.list(selectedCompanyId ?? "", "skill"),
+ queryFn: () => foldersApi.list(selectedCompanyId!, "skill"),
+ enabled: Boolean(selectedCompanyId && ((isDiscovery && discoveryTab === "installed") || routeSkillToken)),
+ });
const installedSkills = skillsQuery.data ?? [];
const routeResolution = useMemo(
@@ -3692,11 +4128,25 @@ export function CompanySkills() {
const studioDraft = useMemo(() => {
if (!isStudioNew) return buildBlankSkillDraft();
- if (studioForkFromId) {
- return studioForkDetailQuery.data ? buildForkSkillDraft(studioForkDetailQuery.data) : buildBlankSkillDraft();
- }
- return buildBlankSkillDraft();
- }, [isStudioNew, studioForkDetailQuery.data, studioForkFromId]);
+ const base = studioForkFromId
+ ? (studioForkDetailQuery.data ? buildForkSkillDraft(studioForkDetailQuery.data) : buildBlankSkillDraft())
+ : buildBlankSkillDraft();
+ // New skills created from a folder context (e.g. My Skills) default their
+ // destination folder to that folder (PAP-14038).
+ return studioNewFolderId ? { ...base, folderId: studioNewFolderId } : base;
+ }, [isStudioNew, studioForkDetailQuery.data, studioForkFromId, studioNewFolderId]);
+
+ // The writable folder to seed a new skill into when creating from the browser.
+ const defaultNewSkillFolderId = useMemo(() => {
+ if (folderSelection === "all" || folderSelection === "unfiled") return null;
+ const model = treeFromResult(skillFoldersQuery.data);
+ const folder = model.byId.get(folderSelection);
+ if (!folder) return null;
+ // Never seed into read-only reserved subtrees (Bundled / Projects).
+ if (folder.path === "bundled" || folder.path.startsWith("bundled/")) return null;
+ if (folder.path === "projects" || folder.path.startsWith("projects/")) return null;
+ return folder.id;
+ }, [folderSelection, skillFoldersQuery.data]);
const updateStatusQuery = useQuery({
queryKey: queryKeys.companySkills.updateStatus(selectedCompanyId ?? "", selectedSkillId ?? ""),
@@ -3766,6 +4216,18 @@ export function CompanySkills() {
}, [selectedSkillId]);
const activeDetail = detailQuery.data ?? displayedDetail;
+ useEffect(() => {
+ setBreadcrumbs([
+ { label: "Skills", href: "/skills" },
+ ...(isStudioNew
+ ? [{ label: studioForkFromId ? "Fork skill" : "New skill" }]
+ : activeDetail
+ ? skillDetailBreadcrumbs(activeDetail, skillFoldersQuery.data).slice(1)
+ : routeSkillToken
+ ? [{ label: "Detail" }]
+ : []),
+ ]);
+ }, [activeDetail, isStudioNew, routeSkillToken, setBreadcrumbs, skillFoldersQuery.data, studioForkFromId]);
const activeFile = fileQuery.data ?? displayedFile;
function routeForSkill(skill: CompanySkillRouteSubject, path?: string | null) {
@@ -4031,13 +4493,28 @@ export function CompanySkills() {
.map(([slug, count]) => ({ slug, count }))
.sort((a, b) => b.count - a.count || a.slug.localeCompare(b.slug));
}, [discoveryTabCards]);
+ const discoverySearchActive = discoverySearch.trim().length > 0;
+ // Selecting a folder shows its whole subtree (folder + descendants), matching
+ // the folder-browser model. `null` means no subtree constraint (All/Unfiled).
+ const folderSubtreeIds = useMemo(() => {
+ if (folderSelection === "all" || folderSelection === "unfiled") return null;
+ const model = treeFromResult(skillFoldersQuery.data);
+ if (!model.byId.has(folderSelection)) return null;
+ return subtreeFolderIds(model, folderSelection);
+ }, [folderSelection, skillFoldersQuery.data]);
const visibleDiscoveryCards = useMemo(() => {
const filtered = discoveryTabCards.filter((card) => {
if (discoveryCategory && !card.categories.includes(discoveryCategory)) return false;
+ // Search spans all folders (user story 5): the folder filter only
+ // narrows when the user is browsing, never when searching.
+ if (discoveryTab === "installed" && !discoverySearchActive) {
+ if (folderSelection === "unfiled" && card.folderId) return false;
+ if (folderSubtreeIds && (!card.folderId || !folderSubtreeIds.has(card.folderId))) return false;
+ }
return discoveryMatchesSearch(card, discoverySearch.trim());
});
return sortDiscoveryCards(filtered, discoverySort, discoveryTab !== "bundled");
- }, [discoveryTabCards, discoveryCategory, discoverySearch, discoverySort, discoveryTab]);
+ }, [discoveryTabCards, discoveryCategory, discoverySearch, discoverySearchActive, discoverySort, discoveryTab, folderSelection, folderSubtreeIds]);
const selectedCatalogSkill = catalogDetailQuery.data
?? (catalogListQuery.data ?? []).find((entry) => entry.id === selectedCatalogRef || entry.key === selectedCatalogRef)
@@ -4105,6 +4582,247 @@ export function CompanySkills() {
policyDenial.capture(error, "Installing this skill");
},
});
+ const createFolder = useMutation({
+ mutationFn: (payload: { name: string; color: string | null }) =>
+ foldersApi.create(selectedCompanyId!, { kind: "skill", parentId: folderDialogParentId, ...payload }),
+ onSuccess: async (folder) => {
+ setFolderDialogOpen(false);
+ setFolderDialogTarget(null);
+ setFolderDialogParentId(null);
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") });
+ if (moveAfterCreateSkillIds.length > 0) {
+ const ids = moveAfterCreateSkillIds;
+ setMoveAfterCreateSkillIds([]);
+ try {
+ await Promise.all(ids.map((itemId) =>
+ foldersApi.moveItem(selectedCompanyId!, { kind: "skill", itemId, folderId: folder.id })
+ ));
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") }),
+ ]);
+ } catch (moveError) {
+ pushToast({
+ tone: "error",
+ title: "Folder created, move failed",
+ body: moveError instanceof Error ? moveError.message : "Failed to move the selected skills.",
+ });
+ return;
+ }
+ } else {
+ setFolderSelection(folder.id);
+ }
+ pushToast({ tone: "success", title: "Folder created", body: folder.name });
+ },
+ onError: (error) => {
+ pushToast({
+ tone: "error",
+ title: "Folder save failed",
+ body: error instanceof Error ? error.message : "Failed to save folder.",
+ });
+ },
+ });
+ const updateFolder = useMutation({
+ mutationFn: ({ folderId, payload }: { folderId: string; payload: { name?: string; color?: string | null } }) =>
+ foldersApi.update(selectedCompanyId!, folderId, payload),
+ onSuccess: async () => {
+ setFolderDialogOpen(false);
+ setFolderDialogTarget(null);
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") });
+ },
+ onError: (error) => {
+ pushToast({
+ tone: "error",
+ title: "Folder save failed",
+ body: error instanceof Error ? error.message : "Failed to update folder.",
+ });
+ },
+ });
+ const moveFolder = useMutation({
+ mutationFn: ({ folderId, parentId }: { folderId: string; parentId: string | null }) =>
+ foldersApi.moveFolder(selectedCompanyId!, folderId, { parentId, position: 0 }),
+ onSuccess: async (folder) => {
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") });
+ setFolderSelection(folder.id);
+ pushToast({
+ tone: "success",
+ title: "Folder moved",
+ body: skillFolderPathDisplayFallback(folder.path) ?? folder.name,
+ });
+ },
+ onError: (error) => {
+ pushToast({
+ tone: "error",
+ title: "Folder move failed",
+ body: error instanceof Error ? error.message : "Failed to move folder.",
+ });
+ },
+ });
+ const deleteFolder = useMutation({
+ mutationFn: (folderId: string) => foldersApi.delete(selectedCompanyId!, folderId),
+ onSuccess: async (_, folderId) => {
+ if (folderSelection === folderId) setFolderSelection("all");
+ setDeleteFolderTarget(null);
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") }),
+ ]);
+ pushToast({ tone: "success", title: "Folder deleted", body: "Skills moved to Unfiled." });
+ },
+ onError: (error) => {
+ pushToast({
+ tone: "error",
+ title: "Folder delete failed",
+ body: error instanceof Error ? error.message : "Failed to delete folder.",
+ });
+ },
+ });
+ const moveSkillToFolder = useMutation({
+ mutationFn: ({ itemId, folderId }: { itemId: string; folderId: string | null }) =>
+ foldersApi.moveItem(selectedCompanyId!, { kind: "skill", itemId, folderId }),
+ onSuccess: async () => {
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") }),
+ ]);
+ },
+ onError: (error) => {
+ pushToast({
+ tone: "error",
+ title: "Move failed",
+ body: error instanceof Error ? error.message : "Failed to move skill.",
+ });
+ },
+ });
+
+ async function moveSelectedSkills(folderId: string | null) {
+ const ids = selectedSkillIds;
+ if (ids.length === 0) return;
+ try {
+ await Promise.all(ids.map((itemId) => foldersApi.moveItem(selectedCompanyId!, { kind: "skill", itemId, folderId })));
+ setSelectedSkillIds([]);
+ setSelectMode(false);
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") }),
+ ]);
+ pushToast({ tone: "success", title: "Skills moved", body: `${ids.length} skill${ids.length === 1 ? "" : "s"} filed.` });
+ } catch (moveError) {
+ pushToast({
+ tone: "error",
+ title: "Failed to move skills",
+ body: moveError instanceof Error ? moveError.message : "Failed to move the selected skills.",
+ });
+ }
+ }
+
+ // Provision the signed-in user's personal "My Skills" root, then select it.
+ const ensureMyFolder = useMutation({
+ mutationFn: () => foldersApi.ensureMy(selectedCompanyId!),
+ onSuccess: async (folder) => {
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") });
+ setFolderSelection(folder.id);
+ },
+ onError: (error) => {
+ pushToast({
+ tone: "error",
+ title: "Couldn't open My Skills",
+ body: error instanceof Error ? error.message : "Failed to create your personal folder.",
+ });
+ },
+ });
+
+ async function openNewSkill() {
+ const model = treeFromResult(skillFoldersQuery.data);
+ const selectedFolder = folderSelection === "all" || folderSelection === "unfiled"
+ ? null
+ : model.byId.get(folderSelection) ?? null;
+ if (selectedFolder?.systemKey === "my") {
+ try {
+ const personalFolder = await ensureMyFolder.mutateAsync();
+ navigate(skillStudioNewRoute(null, personalFolder.id));
+ } catch {
+ return;
+ }
+ return;
+ }
+ navigate(skillStudioNewRoute(null, defaultNewSkillFolderId));
+ }
+
+ async function openCreateFolderIn(parentId: string | null) {
+ const parent = parentId ? treeFromResult(skillFoldersQuery.data).byId.get(parentId) : null;
+ if (parent?.systemKey === "my") {
+ try {
+ const personalFolder = await ensureMyFolder.mutateAsync();
+ openCreateFolder([], personalFolder.id);
+ } catch {
+ return;
+ }
+ return;
+ }
+ openCreateFolder([], parentId);
+ }
+
+ async function moveFolderBetweenScopes(folder: FolderListItem, destination: "my" | "company") {
+ if (destination === "company") {
+ moveFolder.mutate({ folderId: folder.id, parentId: null });
+ return;
+ }
+ try {
+ const personalFolder = await ensureMyFolder.mutateAsync();
+ moveFolder.mutate({ folderId: folder.id, parentId: personalFolder.id });
+ } catch {
+ return;
+ }
+ }
+
+ // Inline folder creation used by the move dialog's "New folder inside…" affordance.
+ async function createFolderInline(parentId: string | null, name: string): Promise<string | null> {
+ try {
+ const folder = await foldersApi.create(selectedCompanyId!, { kind: "skill", parentId, name, color: null });
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") });
+ return folder.id;
+ } catch (error) {
+ pushToast({
+ tone: "error",
+ title: "Folder create failed",
+ body: error instanceof Error ? error.message : "Failed to create folder.",
+ });
+ return null;
+ }
+ }
+
+ // Commit a move initiated from the rich move-to-folder dialog.
+ async function performDialogMove(folderId: string | null) {
+ if (!moveDialog) return;
+ const ids = moveDialog.skillIds;
+ try {
+ await Promise.all(ids.map((itemId) => foldersApi.moveItem(selectedCompanyId!, { kind: "skill", itemId, folderId })));
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "skill") }),
+ ...ids.map((itemId) =>
+ queryClient.invalidateQueries({ queryKey: queryKeys.companySkills.detail(selectedCompanyId!, itemId) }),
+ ),
+ ]);
+ setMoveDialog(null);
+ setSelectedSkillIds([]);
+ setSelectMode(false);
+ pushToast({
+ tone: "success",
+ title: ids.length === 1 ? "Skill moved" : "Skills moved",
+ body: folderId
+ ? `Filed under ${skillFolderResult?.folders.find((folder) => folder.id === folderId)?.name ?? "folder"}.`
+ : "Moved to Unfiled.",
+ });
+ } catch (moveError) {
+ pushToast({
+ tone: "error",
+ title: "Move failed",
+ body: moveError instanceof Error ? moveError.message : "Failed to move.",
+ });
+ }
+ }
const eligibleAgentsForAttach = useMemo(() => {
const data = agentsQuery.data ?? [];
@@ -4229,6 +4947,41 @@ export function CompanySkills() {
},
});
+ const skillFolderResult = skillFoldersQuery.data ?? null;
+ const showInstalledFolders = isDiscovery && discoveryTab === "installed";
+ // Rail counts reflect the current category/search scope, never the folder
+ // filter itself (ux-spec §5.3).
+ const railSkillFolderResult = useMemo(() => {
+ if (!skillFolderResult || discoveryTab !== "installed") return skillFolderResult;
+ const scoped = discoveryTabCards.filter((card) => {
+ if (discoveryCategory && !card.categories.includes(discoveryCategory)) return false;
+ return discoveryMatchesSearch(card, discoverySearch.trim());
+ });
+ const direct = new Map<string, number>();
+ let unfiled = 0;
+ for (const card of scoped) {
+ if (card.folderId) direct.set(card.folderId, (direct.get(card.folderId) ?? 0) + 1);
+ else unfiled += 1;
+ }
+ // Roll direct counts up through the tree so a collapsed parent reflects the
+ // number of skills anywhere in its subtree, not just its own level.
+ const model = treeFromResult(skillFolderResult);
+ return {
+ ...skillFolderResult,
+ allCount: scoped.length,
+ unfiledCount: unfiled,
+ folders: skillFolderResult.folders.map((folder) => {
+ let itemCount = 0;
+ for (const id of subtreeFolderIds(model, folder.id)) itemCount += direct.get(id) ?? 0;
+ return { ...folder, itemCount };
+ }),
+ };
+ }, [skillFolderResult, discoveryTab, discoveryTabCards, discoveryCategory, discoverySearch]);
+ const activeSkillFolderDisplayPath = useMemo(
+ () => skillFolderDisplayPath(treeFromResult(skillFolderResult), activeDetail?.folderId),
+ [skillFolderResult, activeDetail?.folderId],
+ );
+
if (!selectedCompanyId) {
return <EmptyState icon={Boxes} message="Select a company to manage skills." />;
}
@@ -4272,7 +5025,6 @@ export function CompanySkills() {
const studioDescription = studioForkFromId
? "Review the fork metadata and create an editable company copy."
: "Create an editable company skill in the Paperclip workspace.";
-
return (
<>
{policyDenial.denial ? (
@@ -4451,6 +5203,54 @@ export function CompanySkills() {
}}
/>
) : null}
+ <FolderFormDialog
+ open={folderDialogOpen}
+ kind="skill"
+ folder={folderDialogTarget}
+ pending={createFolder.isPending || updateFolder.isPending}
+ onOpenChange={(open) => {
+ setFolderDialogOpen(open);
+ if (!open) setFolderDialogParentId(null);
+ }}
+ onSubmit={(payload) => {
+ if (folderDialogTarget) updateFolder.mutate({ folderId: folderDialogTarget.id, payload });
+ else createFolder.mutate(payload);
+ }}
+ />
+ <DeleteFolderDialog
+ open={deleteFolderTarget !== null}
+ folder={deleteFolderTarget}
+ itemLabelPlural="skills"
+ pending={deleteFolder.isPending}
+ onOpenChange={(open) => {
+ if (!open) setDeleteFolderTarget(null);
+ }}
+ onConfirm={() => {
+ if (deleteFolderTarget) deleteFolder.mutate(deleteFolderTarget.id);
+ }}
+ />
+ <MobileFolderSheet
+ open={mobileFoldersOpen}
+ onOpenChange={setMobileFoldersOpen}
+ result={railSkillFolderResult}
+ selection={folderSelection}
+ allLabel="All skills"
+ itemLabelPlural="Skills"
+ onSelect={setFolderSelection}
+ onCreate={() => openCreateFolder()}
+ />
+ <MoveToFolderDialog
+ open={moveDialog !== null}
+ onOpenChange={(open) => {
+ if (!open) setMoveDialog(null);
+ }}
+ result={railSkillFolderResult}
+ title={moveDialog?.title ?? "Move to folder"}
+ subtitle={moveDialog?.subtitle ?? null}
+ currentFolderId={moveDialog?.currentFolderId ?? null}
+ onMove={(folderId) => void performDialogMove(folderId)}
+ onCreateFolder={createFolderInline}
+ />
{isStudioNew ? (
<div className="min-h-(--sz-calc-30)">
@@ -4501,17 +5301,80 @@ export function CompanySkills() {
loading={skillsQuery.isLoading || catalogListQuery.isLoading}
error={skillsQuery.error?.message ?? catalogListQuery.error?.message ?? null}
totalCount={discoveryCards.length}
- onCreate={() => navigate(skillStudioNewRoute())}
+ onCreate={() => void openNewSkill()}
onImport={() => setImportDialogOpen(true)}
onImportFromProject={() => setImportFromProjectOpen(true)}
onBrowseCatalog={() => setDiscoveryTab("catalog")}
onScan={() => scanProjects.mutate()}
scanPending={scanProjects.isPending}
scanStatus={scanStatusMessage}
+ folderResult={showInstalledFolders ? railSkillFolderResult : null}
+ folderSelection={folderSelection}
+ foldersLoading={skillFoldersQuery.isLoading}
+ selectMode={showInstalledFolders && selectMode}
+ selectedSkillIds={selectedSkillIds}
+ onFolderSelect={showInstalledFolders ? setFolderSelection : undefined}
+ onOpenMobileFolders={showInstalledFolders ? () => setMobileFoldersOpen(true) : undefined}
+ onCreateFolder={showInstalledFolders ? () => openCreateFolder() : undefined}
+ onCreateFolderIn={showInstalledFolders ? (parentId) => void openCreateFolderIn(parentId) : undefined}
+ onEnsureMyFolder={showInstalledFolders ? () => ensureMyFolder.mutate() : undefined}
+ onOpenMoveCard={showInstalledFolders ? (card) => {
+ if (!card.skillId) return;
+ setMoveDialog({
+ skillIds: [card.skillId],
+ title: `Move "${card.name}"`,
+ subtitle: "Choose a destination folder.",
+ currentFolderId: card.folderId ?? null,
+ });
+ } : undefined}
+ onRenameFolder={showInstalledFolders ? (folder, name) => updateFolder.mutate({ folderId: folder.id, payload: { name } }) : undefined}
+ onEditFolder={showInstalledFolders ? (folder) => {
+ setFolderDialogTarget(folder);
+ setFolderDialogOpen(true);
+ } : undefined}
+ onMoveFolder={showInstalledFolders ? (folder, destination) => void moveFolderBetweenScopes(folder, destination) : undefined}
+ onDeleteFolder={showInstalledFolders ? setDeleteFolderTarget : undefined}
+ onToggleSelectMode={showInstalledFolders ? () => {
+ setSelectMode((current) => !current);
+ if (selectMode) setSelectedSkillIds([]);
+ } : undefined}
+ onSelectCard={showInstalledFolders ? (card, selected) => {
+ if (!card.skillId) return;
+ setSelectedSkillIds((current) =>
+ selected
+ ? Array.from(new Set([...current, card.skillId!]))
+ : current.filter((id) => id !== card.skillId)
+ );
+ } : undefined}
+ onMoveCard={showInstalledFolders ? (card, folderId) => {
+ if (!card.skillId) return;
+ const skillId = card.skillId;
+ const previousFolderId = card.folderId ?? null;
+ moveSkillToFolder.mutate({ itemId: skillId, folderId });
+ pushToast({
+ tone: "success",
+ title: "Skill moved",
+ body: folderId
+ ? `Moved "${card.name}" to ${skillFolderResult?.folders.find((folder) => folder.id === folderId)?.name ?? "folder"}.`
+ : `Moved "${card.name}" to Unfiled.`,
+ action: {
+ label: "Undo",
+ onClick: () => moveSkillToFolder.mutate({ itemId: skillId, folderId: previousFolderId }),
+ },
+ });
+ } : undefined}
+ onCreateFolderAndMoveCard={showInstalledFolders ? (card) => {
+ if (card.skillId) openCreateFolder([card.skillId]);
+ } : undefined}
+ onMoveSelected={showInstalledFolders ? (folderId) => void moveSelectedSkills(folderId) : undefined}
+ onCreateFolderAndMoveSelected={showInstalledFolders ? () => openCreateFolder(selectedSkillIds) : undefined}
+ onClearSelected={showInstalledFolders ? () => setSelectedSkillIds([]) : undefined}
+ folderNudgeStorageKey={showInstalledFolders ? `paperclip:skills-folder-nudge:${selectedCompanyId ?? "none"}` : undefined}
/>
) : activeView === "installed" && selectedSkillId ? (
<SkillDetailPage
detail={activeDetail}
+ folderDisplayPath={activeSkillFolderDisplayPath}
catalogSource={catalogSourceForDetail}
routeSkills={installedSkills}
loading={skillsQuery.isLoading || detailQuery.isLoading}
@@ -4558,6 +5421,12 @@ export function CompanySkills() {
starPending={toggleStar.isPending}
onFork={() => activeDetail && navigate(skillStudioNewRoute(activeDetail.id))}
onUpdateSettings={(updates) => activeDetail && updateSkillSettings.mutate({ skillId: activeDetail.id, updates })}
+ onMoveToFolder={activeDetail ? () => setMoveDialog({
+ skillIds: [activeDetail.id],
+ title: `Move "${activeDetail.name}"`,
+ subtitle: "Choose a destination folder.",
+ currentFolderId: activeDetail.folderId ?? null,
+ }) : undefined}
updateSettingsPending={updateSkillSettings.isPending}
onDelete={openDeleteDialog}
deletePending={deleteSkill.isPending}
diff --git a/ui/src/pages/Routines.test.tsx b/ui/src/pages/Routines.test.tsx
index fb213cb2f4..bda84cbce5 100644
--- a/ui/src/pages/Routines.test.tsx
+++ b/ui/src/pages/Routines.test.tsx
@@ -4,7 +4,7 @@ import type { AnchorHTMLAttributes, ReactNode } from "react";
import { flushSync } from "react-dom";
import { createRoot } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { Issue, RoutineListItem } from "@paperclipai/shared";
+import type { FolderListResult, Issue, RoutineListItem } from "@paperclipai/shared";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { Routines, buildRoutineGroups, buildRoutineSections, sortRoutines } from "./Routines";
@@ -20,6 +20,7 @@ async function act(callback: () => void | Promise<void>) {
const navigateMock = vi.fn();
const routinesListMock = vi.fn<(companyId: string) => Promise<RoutineListItem[]>>();
+const foldersListMock = vi.fn<(companyId: string, kind: string) => Promise<FolderListResult>>();
const issuesListMock = vi.fn<(companyId: string, filters?: Record<string, unknown>) => Promise<Issue[]>>();
const markdownEditorRenderMock = vi.fn((props: { mentions?: Array<{ id: string; name: string }> }) => props);
const issuesListRenderMock = vi.fn(({ issues }: { issues: Issue[] }) => (
@@ -58,6 +59,16 @@ vi.mock("../api/routines", () => ({
},
}));
+vi.mock("../api/folders", () => ({
+ foldersApi: {
+ list: (companyId: string, kind: string) => foldersListMock(companyId, kind),
+ create: vi.fn(),
+ update: vi.fn(),
+ delete: vi.fn(),
+ moveItem: vi.fn(),
+ },
+}));
+
vi.mock("../api/issues", () => ({
issuesApi: {
list: (companyId: string, filters?: Record<string, unknown>) => issuesListMock(companyId, filters),
@@ -275,6 +286,7 @@ function createRoutine(overrides: Partial<RoutineListItem>): RoutineListItem {
triggers: [],
lastRun: null,
activeIssue: null,
+ folderId: null,
...overrides,
};
}
@@ -343,6 +355,13 @@ describe("Routines page", () => {
currentSearch = "";
navigateMock.mockReset();
routinesListMock.mockReset();
+ foldersListMock.mockReset();
+ foldersListMock.mockResolvedValue({
+ kind: "routine",
+ folders: [],
+ allCount: 0,
+ unfiledCount: 0,
+ });
issuesListMock.mockReset();
markdownEditorRenderMock.mockClear();
issuesListRenderMock.mockClear();
@@ -398,6 +417,22 @@ describe("Routines page", () => {
expect(groups[1]?.items.map((item) => item.title)).toEqual(["Reflection review"]);
});
+ it("uses a flat group when Folder grouping is active", () => {
+ const routines = [
+ createRoutine({ id: "routine-1", title: "Morning sync", projectId: "project-1" }),
+ createRoutine({ id: "routine-2", title: "Weekly digest", projectId: "project-2" }),
+ ];
+
+ const groups = buildRoutineGroups(
+ routines,
+ "folder",
+ new Map(),
+ new Map(),
+ );
+
+ expect(groups).toEqual([{ key: "__all", label: null, items: routines }]);
+ });
+
it("sorts routines by selected field and direction without mutating the source list", () => {
const routines = [
createRoutine({
@@ -489,7 +524,7 @@ describe("Routines page", () => {
});
});
- it("defaults the routines list to project groups sorted by title", async () => {
+ it("defaults the routines list to folder mode without rendering project groups", async () => {
routinesListMock.mockResolvedValue([
createRoutine({ id: "routine-1", title: "Weekly digest", projectId: "project-1" }),
createRoutine({ id: "routine-2", title: "Morning sync", projectId: "project-1" }),
@@ -513,17 +548,15 @@ describe("Routines page", () => {
await flush();
});
- for (let attempts = 0; attempts < 5 && !container.textContent?.includes("Project Alpha"); attempts += 1) {
+ for (let attempts = 0; attempts < 5 && !container.textContent?.includes("Morning sync"); attempts += 1) {
await act(async () => {
await flush();
});
}
const text = container.textContent ?? "";
- expect(text.indexOf("Project Alpha")).toBeLessThan(text.indexOf("Project Beta"));
expect(text.indexOf("Morning sync")).toBeLessThan(text.indexOf("Weekly digest"));
- expect(text.indexOf("Project Alpha")).toBeLessThan(text.indexOf("Morning sync"));
- expect(text.indexOf("Weekly digest")).toBeLessThan(text.indexOf("Project Beta"));
+ expect(text).toContain("New folder");
await act(async () => {
root.unmount();
@@ -546,7 +579,6 @@ describe("Routines page", () => {
}),
]);
issuesListMock.mockResolvedValue([]);
-
const root = createRoot(container);
const queryClient = new QueryClient({
defaultOptions: {
@@ -570,7 +602,6 @@ describe("Routines page", () => {
}
const text = container.textContent ?? "";
- expect(text.indexOf("Project Alpha")).toBeLessThan(text.indexOf("Morning sync"));
expect(text.indexOf("Morning sync")).toBeLessThan(text.indexOf("Built-in routines"));
expect(text.indexOf("Built-in routines")).toBeLessThan(text.indexOf("Reflection review"));
@@ -579,6 +610,109 @@ describe("Routines page", () => {
});
});
+ it("filters to Unfiled and shows the empty-folder state with a create CTA", async () => {
+ foldersListMock.mockResolvedValue({
+ kind: "routine",
+ allCount: 2,
+ unfiledCount: 1,
+ folders: [
+ {
+ id: "folder-reporting",
+ companyId: "company-1",
+ kind: "routine",
+ parentId: null,
+ name: "Reporting",
+ slug: "reporting",
+ systemKey: null,
+ path: "reporting",
+ depth: 1,
+ color: "#6366f1",
+ position: 0,
+ itemCount: 1,
+ createdAt: new Date("2026-07-01T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-01T00:00:00.000Z"),
+ },
+ {
+ id: "folder-empty",
+ companyId: "company-1",
+ kind: "routine",
+ parentId: null,
+ name: "Empty folder",
+ slug: "empty-folder",
+ systemKey: null,
+ path: "empty-folder",
+ depth: 1,
+ color: null,
+ position: 1,
+ itemCount: 0,
+ createdAt: new Date("2026-07-01T00:00:00.000Z"),
+ updatedAt: new Date("2026-07-01T00:00:00.000Z"),
+ },
+ ],
+ });
+ routinesListMock.mockResolvedValue([
+ createRoutine({ id: "routine-1", title: "Filed digest", folderId: "folder-reporting" }),
+ createRoutine({ id: "routine-2", title: "Loose routine", folderId: null }),
+ ]);
+ issuesListMock.mockResolvedValue([]);
+
+ currentSearch = "folder=unfiled";
+ const root = createRoot(container);
+ const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ },
+ });
+
+ await act(async () => {
+ root.render(
+ <QueryClientProvider client={queryClient}>
+ <Routines />
+ </QueryClientProvider>,
+ );
+ await flush();
+ });
+ for (let attempts = 0; attempts < 5 && !container.textContent?.includes("Loose routine"); attempts += 1) {
+ await act(async () => {
+ await flush();
+ });
+ }
+
+ // Unfiled filter: only the folderless routine renders; the rail still lists folders.
+ expect(container.textContent).toContain("Loose routine");
+ expect(container.textContent).not.toContain("Filed digest");
+ expect(container.textContent).toContain("Reporting");
+ expect(container.textContent).toContain("Empty folder");
+
+ await act(async () => {
+ root.unmount();
+ });
+
+ // Remount filtered to the empty folder: empty state + create-into-folder CTA.
+ currentSearch = "folder=folder-empty";
+ const secondRoot = createRoot(container);
+ await act(async () => {
+ secondRoot.render(
+ <QueryClientProvider client={queryClient}>
+ <Routines />
+ </QueryClientProvider>,
+ );
+ await flush();
+ });
+ for (let attempts = 0; attempts < 5 && !container.textContent?.includes("This folder is empty"); attempts += 1) {
+ await act(async () => {
+ await flush();
+ });
+ }
+
+ expect(container.textContent).toContain("This folder is empty");
+ expect(container.textContent).toContain("New routine in this folder");
+
+ await act(async () => {
+ secondRoot.unmount();
+ });
+ });
+
it("hides archived routines from the routines list", async () => {
routinesListMock.mockResolvedValue([
createRoutine({ id: "routine-1", title: "Morning sync", status: "active" }),
diff --git a/ui/src/pages/Routines.tsx b/ui/src/pages/Routines.tsx
index 58c02dce38..a3a3fedbfd 100644
--- a/ui/src/pages/Routines.tsx
+++ b/ui/src/pages/Routines.tsx
@@ -3,6 +3,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { Link, useNavigate, useSearchParams } from "@/lib/router";
import { ArrowUpDown, Check, ChevronDown, ChevronRight, Layers, Plus, Repeat } from "lucide-react";
import { routinesApi } from "../api/routines";
+import { foldersApi } from "../api/folders";
import { agentsApi } from "../api/agents";
import { projectsApi } from "../api/projects";
import { issuesApi } from "../api/issues";
@@ -12,6 +13,7 @@ import { useCompany } from "../context/CompanyContext";
import { useBreadcrumbs } from "../context/BreadcrumbContext";
import { useToastActions } from "../context/ToastContext";
import { buildMarkdownMentionOptions } from "../lib/company-members";
+import { cn } from "../lib/utils";
import { queryKeys } from "../lib/queryKeys";
import { groupBy } from "../lib/groupBy";
import { createIssueDetailLocationState } from "../lib/issueDetailBreadcrumb";
@@ -46,6 +48,22 @@ import {
} from "@/components/ui/select";
import { Tabs, TabsContent } from "@/components/ui/tabs";
import type { RoutineListItem, RoutineVariable } from "@paperclipai/shared";
+import type { FolderListItem } from "@paperclipai/shared";
+import {
+ AllUnfiledBanner,
+ BulkBar,
+ DeleteFolderDialog,
+ FolderChip,
+ FolderFormDialog,
+ FolderRail,
+ FolderSwatch,
+ MobileFolderSheet,
+ MoveToMenu,
+ folderSearchValue,
+ normalizeFolderSelection,
+ selectedFolderFromList,
+ type FolderSelection,
+} from "../components/folders/FolderControls";
const concurrencyPolicies = ["coalesce_if_active", "always_enqueue", "skip_if_active"];
const catchUpPolicies = ["skip_missed", "enqueue_missed_with_cap"];
@@ -66,7 +84,7 @@ function autoResizeTextarea(element: HTMLTextAreaElement | null) {
}
type RoutinesTab = "routines" | "runs";
-type RoutineGroupBy = "none" | "project" | "assignee";
+type RoutineGroupBy = "folder" | "none" | "project" | "assignee";
type RoutineSortField = "updated" | "created" | "title" | "lastRun";
type RoutineSortDir = "asc" | "desc";
@@ -88,7 +106,7 @@ const builtInRoutineGroupKey = "__built_in_routines";
const defaultRoutineViewState: RoutineViewState = {
sortField: "title",
sortDir: "asc",
- groupBy: "project",
+ groupBy: "folder",
collapsedGroups: [],
};
@@ -120,6 +138,7 @@ function buildRoutineMutationPayload(input: {
title: string;
description: string;
projectId: string;
+ folderId: string | null;
assigneeAgentId: string;
priority: string;
concurrencyPolicy: string;
@@ -130,6 +149,7 @@ function buildRoutineMutationPayload(input: {
...input,
description: input.description.trim() || null,
projectId: input.projectId || null,
+ folderId: input.folderId || null,
assigneeAgentId: input.assigneeAgentId || null,
};
}
@@ -140,7 +160,7 @@ export function buildRoutineGroups(
projectById: Map<string, { name: string }>,
agentById: Map<string, { name: string }>,
): RoutineGroup[] {
- if (groupByValue === "none") {
+ if (groupByValue === "none" || groupByValue === "folder") {
return [{ key: "__all", label: null, items: routines }];
}
@@ -267,12 +287,19 @@ export function Routines() {
const { setBreadcrumbs } = useBreadcrumbs();
const queryClient = useQueryClient();
const navigate = useNavigate();
- const [searchParams] = useSearchParams();
+ const [searchParams, setSearchParams] = useSearchParams();
const { pushToast } = useToastActions();
const descriptionEditorRef = useRef<MarkdownEditorRef>(null);
const titleInputRef = useRef<HTMLTextAreaElement | null>(null);
const assigneeSelectorRef = useRef<HTMLButtonElement | null>(null);
const projectSelectorRef = useRef<HTMLButtonElement | null>(null);
+ const [folderDialogOpen, setFolderDialogOpen] = useState(false);
+ const [folderDialogTarget, setFolderDialogTarget] = useState<FolderListItem | null>(null);
+ const [deleteFolderTarget, setDeleteFolderTarget] = useState<FolderListItem | null>(null);
+ const [mobileFoldersOpen, setMobileFoldersOpen] = useState(false);
+ const [selectMode, setSelectMode] = useState(false);
+ const [selectedRoutineIds, setSelectedRoutineIds] = useState<string[]>([]);
+ const [moveAfterCreateIds, setMoveAfterCreateIds] = useState<string[]>([]);
const [runningRoutineId, setRunningRoutineId] = useState<string | null>(null);
const [statusMutationRoutineId, setStatusMutationRoutineId] = useState<string | null>(null);
const [runDialogRoutine, setRunDialogRoutine] = useState<RoutineListItem | null>(null);
@@ -283,6 +310,7 @@ export function Routines() {
title: string;
description: string;
projectId: string;
+ folderId: string | null;
assigneeAgentId: string;
priority: string;
concurrencyPolicy: string;
@@ -292,6 +320,7 @@ export function Routines() {
title: "",
description: "",
projectId: "",
+ folderId: null,
assigneeAgentId: "",
priority: "medium",
concurrencyPolicy: "coalesce_if_active",
@@ -302,6 +331,7 @@ export function Routines() {
? `paperclip:routines-view:${selectedCompanyId}`
: "paperclip:routines-view";
const [routineViewState, setRoutineViewState] = useState<RoutineViewState>(() => getRoutineViewState(routineViewStateKey));
+ const folderSelection = normalizeFolderSelection(searchParams.get("folder"));
useEffect(() => {
setBreadcrumbs([{ label: "Routines" }]);
@@ -316,6 +346,11 @@ export function Routines() {
queryFn: () => routinesApi.list(selectedCompanyId!),
enabled: !!selectedCompanyId,
});
+ const { data: routineFolders, isLoading: foldersLoading } = useQuery({
+ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine"),
+ queryFn: () => foldersApi.list(selectedCompanyId!, "routine"),
+ enabled: !!selectedCompanyId && activeTab === "routines",
+ });
const { data: agents } = useQuery({
queryKey: queryKeys.agents.list(selectedCompanyId!),
queryFn: () => agentsApi.list(selectedCompanyId!),
@@ -374,6 +409,7 @@ export function Routines() {
title: "",
description: "",
projectId: "",
+ folderId: null,
assigneeAgentId: "",
priority: "medium",
concurrencyPolicy: "coalesce_if_active",
@@ -393,6 +429,97 @@ export function Routines() {
navigate(`/routines/${routine.id}?tab=triggers`);
},
});
+ const createFolder = useMutation({
+ mutationFn: (payload: { name: string; color: string | null }) =>
+ foldersApi.create(selectedCompanyId!, { kind: "routine", ...payload }),
+ onSuccess: async (folder) => {
+ setFolderDialogOpen(false);
+ setFolderDialogTarget(null);
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine") });
+ if (moveAfterCreateIds.length > 0) {
+ const ids = moveAfterCreateIds;
+ setMoveAfterCreateIds([]);
+ try {
+ await Promise.all(ids.map((itemId) =>
+ foldersApi.moveItem(selectedCompanyId!, { kind: "routine", itemId, folderId: folder.id })
+ ));
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine") }),
+ ]);
+ } catch (moveError) {
+ pushToast({
+ title: "Folder created, move failed",
+ body: moveError instanceof Error ? moveError.message : "Paperclip could not move the selected routines.",
+ tone: "error",
+ });
+ return;
+ }
+ } else {
+ setFolderSelection(folder.id);
+ }
+ pushToast({ title: "Folder created", body: folder.name, tone: "success" });
+ },
+ onError: (mutationError) => {
+ pushToast({
+ title: "Failed to save folder",
+ body: mutationError instanceof Error ? mutationError.message : "Paperclip could not save the folder.",
+ tone: "error",
+ });
+ },
+ });
+ const updateFolder = useMutation({
+ mutationFn: ({ folderId, payload }: { folderId: string; payload: { name?: string; color?: string | null } }) =>
+ foldersApi.update(selectedCompanyId!, folderId, payload),
+ onSuccess: async () => {
+ setFolderDialogOpen(false);
+ setFolderDialogTarget(null);
+ await queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine") });
+ },
+ onError: (mutationError) => {
+ pushToast({
+ title: "Folder save failed",
+ body: mutationError instanceof Error ? mutationError.message : "Paperclip could not update the folder.",
+ tone: "error",
+ });
+ },
+ });
+ const deleteFolder = useMutation({
+ mutationFn: (folderId: string) => foldersApi.delete(selectedCompanyId!, folderId),
+ onSuccess: async (_, folderId) => {
+ if (folderSelection === folderId) setFolderSelection("all");
+ setDeleteFolderTarget(null);
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine") }),
+ ]);
+ pushToast({ title: "Folder deleted", body: "Items moved to Unfiled.", tone: "success" });
+ },
+ onError: (mutationError) => {
+ pushToast({
+ title: "Folder delete failed",
+ body: mutationError instanceof Error ? mutationError.message : "Paperclip could not delete the folder.",
+ tone: "error",
+ });
+ },
+ });
+ const moveRoutineToFolder = useMutation({
+ mutationFn: ({ itemId, folderId }: { itemId: string; folderId: string | null }) =>
+ foldersApi.moveItem(selectedCompanyId!, { kind: "routine", itemId, folderId }),
+ onSuccess: async () => {
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine") }),
+ ]);
+ },
+ onError: (mutationError) => {
+ pushToast({
+ title: "Move failed",
+ body: mutationError instanceof Error ? mutationError.message : "Paperclip could not move the routine.",
+ tone: "error",
+ });
+ },
+ });
const updateIssue = useMutation({
mutationFn: ({ id, data }: { id: string; data: Record<string, unknown> }) =>
issuesApi.update(id, data),
@@ -495,9 +622,35 @@ export function Routines() {
() => (routines ?? []).filter((routine) => routine.status !== "archived"),
[routines],
);
+ const folderFilteredRoutines = useMemo(() => {
+ if (routineViewState.groupBy !== "folder") return visibleRoutines;
+ if (folderSelection === "all") return visibleRoutines;
+ if (folderSelection === "unfiled") return visibleRoutines.filter((routine) => !routine.folderId);
+ return visibleRoutines.filter((routine) => routine.folderId === folderSelection);
+ }, [folderSelection, routineViewState.groupBy, visibleRoutines]);
+ // Rail counts reflect the page's visible scope (archived hidden), not raw DB
+ // counts (ux-spec §5.3).
+ const railFolderResult = useMemo(() => {
+ if (!routineFolders) return routineFolders;
+ const counts = new Map<string, number>();
+ let unfiled = 0;
+ for (const routine of visibleRoutines) {
+ if (routine.folderId) counts.set(routine.folderId, (counts.get(routine.folderId) ?? 0) + 1);
+ else unfiled += 1;
+ }
+ return {
+ ...routineFolders,
+ allCount: visibleRoutines.length,
+ unfiledCount: unfiled,
+ folders: routineFolders.folders.map((folder) => ({
+ ...folder,
+ itemCount: counts.get(folder.id) ?? 0,
+ })),
+ };
+ }, [routineFolders, visibleRoutines]);
const sortedRoutines = useMemo(
- () => sortRoutines(visibleRoutines, routineViewState.sortField, routineViewState.sortDir),
- [routineViewState.sortDir, routineViewState.sortField, visibleRoutines],
+ () => sortRoutines(folderFilteredRoutines, routineViewState.sortField, routineViewState.sortDir),
+ [folderFilteredRoutines, routineViewState.sortDir, routineViewState.sortField],
);
const routineSections = useMemo(
() => buildRoutineSections(sortedRoutines, routineViewState.groupBy, projectById, agentById),
@@ -514,6 +667,9 @@ export function Routines() {
);
const currentAssignee = draft.assigneeAgentId ? agentById.get(draft.assigneeAgentId) ?? null : null;
const currentProject = draft.projectId ? projectById.get(draft.projectId) ?? null : null;
+ const activeFolder = selectedFolderFromList(routineFolders?.folders ?? [], folderSelection);
+ const hasRoutineFolders = (routineFolders?.folders.length ?? 0) > 0;
+ const showFolderRail = activeTab === "routines" && routineViewState.groupBy === "folder" && hasRoutineFolders;
function updateRoutineView(patch: Partial<RoutineViewState>) {
setRoutineViewState((current) => {
@@ -530,6 +686,51 @@ export function Routines() {
});
}
+ function setFolderSelection(selection: FolderSelection) {
+ setSearchParams((current) => {
+ const params = new URLSearchParams(current);
+ const value = folderSearchValue(selection);
+ if (value) params.set("folder", value);
+ else params.delete("folder");
+ return params;
+ });
+ }
+
+ function openCreateFolder(moveItemIds: string[] = []) {
+ setMoveAfterCreateIds(moveItemIds);
+ setFolderDialogTarget(null);
+ setFolderDialogOpen(true);
+ }
+
+ function openCreateRoutine() {
+ setDraft((current) => ({
+ ...current,
+ folderId: folderSelection === "all" || folderSelection === "unfiled" ? null : folderSelection,
+ }));
+ setComposerOpen(true);
+ }
+
+ async function moveSelectedRoutines(folderId: string | null) {
+ const ids = selectedRoutineIds;
+ if (ids.length === 0) return;
+ try {
+ await Promise.all(ids.map((itemId) => foldersApi.moveItem(selectedCompanyId!, { kind: "routine", itemId, folderId })));
+ setSelectedRoutineIds([]);
+ setSelectMode(false);
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: queryKeys.routines.list(selectedCompanyId!) }),
+ queryClient.invalidateQueries({ queryKey: queryKeys.folders.list(selectedCompanyId!, "routine") }),
+ ]);
+ pushToast({ title: "Routines moved", body: `${ids.length} routine${ids.length === 1 ? "" : "s"} filed.`, tone: "success" });
+ } catch (moveError) {
+ pushToast({
+ title: "Failed to move routines",
+ body: moveError instanceof Error ? moveError.message : "Paperclip could not move the selected routines.",
+ tone: "error",
+ });
+ }
+ }
+
function handleRunNow(routine: RoutineListItem) {
setRunDialogRoutine(routine);
}
@@ -575,7 +776,7 @@ export function Routines() {
Recurring work definitions that materialize into auditable execution tasks.
</p>
</div>
- <Button onClick={() => setComposerOpen(true)}>
+ <Button onClick={openCreateRoutine}>
<Plus className="mr-2 h-4 w-4" />
Create routine
</Button>
@@ -648,6 +849,7 @@ export function Routines() {
<PopoverContent align="end" className="w-44 p-0">
<div className="p-2 space-y-0.5">
{([
+ ["folder", "Folder"],
["project", "Project"],
["assignee", "Agent"],
["none", "None"],
@@ -668,8 +870,29 @@ export function Routines() {
</div>
</PopoverContent>
</Popover>
+ {routineViewState.groupBy === "folder" && !hasRoutineFolders ? (
+ <Button variant="outline" size="sm" onClick={() => openCreateFolder()}>
+ <Plus className="mr-2 h-3.5 w-3.5" />
+ New folder
+ </Button>
+ ) : null}
+ {showFolderRail ? (
+ <Button variant="ghost" size="sm" className="text-xs" onClick={() => setSelectMode((current) => !current)}>
+ {selectMode ? "Done" : "Select"}
+ </Button>
+ ) : null}
</div>
</div>
+ {routineViewState.groupBy === "folder" ? (
+ <div className="md:hidden">
+ <FolderChip
+ result={railFolderResult}
+ selection={folderSelection}
+ allLabel="All routines"
+ onClick={() => setMobileFoldersOpen(true)}
+ />
+ </div>
+ ) : null}
</TabsContent>
<TabsContent value="runs">
<IssuesList
@@ -844,6 +1067,26 @@ export function Routines() {
);
}}
/>
+ <span>filed in</span>
+ <Select
+ value={draft.folderId ?? "__unfiled"}
+ onValueChange={(value) => setDraft((current) => ({
+ ...current,
+ folderId: value === "__unfiled" ? null : value,
+ }))}
+ >
+ <SelectTrigger className="h-8 w-auto min-w-32 border-0 bg-muted/50 px-2 shadow-none">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="__unfiled">Unfiled</SelectItem>
+ {(routineFolders?.folders ?? []).map((folder) => (
+ <SelectItem key={folder.id} value={folder.id}>
+ {folder.name}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
</div>
</div>
</div>
@@ -950,7 +1193,56 @@ export function Routines() {
) : null}
{activeTab === "routines" ? (
- <div>
+ <div className={cn(showFolderRail && "flex gap-4")}>
+ {showFolderRail ? (
+ <FolderRail
+ result={railFolderResult}
+ selection={folderSelection}
+ allLabel="All routines"
+ itemLabelPlural="routines"
+ loading={foldersLoading}
+ onSelect={setFolderSelection}
+ onCreate={() => openCreateFolder()}
+ onRename={(folder, name) => updateFolder.mutate({ folderId: folder.id, payload: { name } })}
+ onEdit={(folder) => {
+ setFolderDialogTarget(folder);
+ setFolderDialogOpen(true);
+ }}
+ onDelete={setDeleteFolderTarget}
+ />
+ ) : null}
+ <div className="min-w-0 flex-1">
+ {routineViewState.groupBy === "folder" && hasRoutineFolders ? (
+ <div className="mb-3 flex flex-wrap items-center gap-2">
+ {folderSelection === "all" ? <FolderIconHeader label="All routines" count={sortedRoutines.length} /> : (
+ <div className="flex min-w-0 items-center gap-2 text-sm">
+ <FolderSwatch color={activeFolder?.color} />
+ <span className="truncate font-medium">{folderSelection === "unfiled" ? "Unfiled" : activeFolder?.name ?? "Folder"}</span>
+ <span className="text-muted-foreground">{sortedRoutines.length} routine{sortedRoutines.length === 1 ? "" : "s"}</span>
+ </div>
+ )}
+ </div>
+ ) : null}
+ {routineViewState.groupBy === "folder" && !hasRoutineFolders && !foldersLoading && visibleRoutines.length > 0 ? (
+ <AllUnfiledBanner
+ storageKey={`paperclip:routines-folder-nudge:${selectedCompanyId ?? "none"}`}
+ itemLabelPlural="routines"
+ onCreateFolder={() => openCreateFolder()}
+ />
+ ) : null}
+ {selectMode ? (
+ <BulkBar
+ selectedCount={selectedRoutineIds.length}
+ folders={routineFolders?.folders ?? []}
+ onMove={(folderId) => void moveSelectedRoutines(folderId)}
+ onCreateAndMove={() => openCreateFolder(selectedRoutineIds)}
+ onClear={() => setSelectedRoutineIds([])}
+ onDone={() => {
+ setSelectMode(false);
+ setSelectedRoutineIds([]);
+ }}
+ />
+ ) : null}
{visibleRoutines.length === 0 ? (
<div className="py-12">
<EmptyState
@@ -958,6 +1250,21 @@ export function Routines() {
message="No active routines. Use Create routine to define the first recurring workflow."
/>
</div>
+ ) : sortedRoutines.length === 0 ? (
+ <div className="py-12">
+ <EmptyState
+ icon={Repeat}
+ message={folderSelection === "all" ? "No routines match this view." : "This folder is empty."}
+ />
+ {folderSelection !== "all" ? (
+ <div className="mt-3 flex justify-center">
+ <Button size="sm" onClick={openCreateRoutine}>
+ <Plus className="mr-2 h-3.5 w-3.5" />
+ New routine in this folder
+ </Button>
+ </div>
+ ) : null}
+ </div>
) : (
<div className="flex flex-col gap-3">
{routineSections.map((group) => {
@@ -996,6 +1303,37 @@ export function Routines() {
onRunNow={handleRunNow}
onToggleEnabled={handleToggleEnabled}
onToggleArchived={handleToggleArchived}
+ selectMode={selectMode}
+ selected={selectedRoutineIds.includes(routine.id)}
+ onSelectChange={(selectedRoutine, selected) => {
+ setSelectedRoutineIds((current) =>
+ selected
+ ? Array.from(new Set([...current, selectedRoutine.id]))
+ : current.filter((id) => id !== selectedRoutine.id)
+ );
+ }}
+ extraMenuItems={
+ <MoveToMenu
+ folders={routineFolders?.folders ?? []}
+ currentFolderId={routine.folderId ?? null}
+ onMove={(folderId) => {
+ const previousFolderId = routine.folderId ?? null;
+ moveRoutineToFolder.mutate({ itemId: routine.id, folderId });
+ pushToast({
+ title: "Routine moved",
+ body: folderId
+ ? `Moved "${routine.title}" to ${routineFolders?.folders.find((folder) => folder.id === folderId)?.name ?? "folder"}.`
+ : `Moved "${routine.title}" to Unfiled.`,
+ tone: "success",
+ action: {
+ label: "Undo",
+ onClick: () => moveRoutineToFolder.mutate({ itemId: routine.id, folderId: previousFolderId }),
+ },
+ });
+ }}
+ onCreateAndMove={() => openCreateFolder([routine.id])}
+ />
+ }
/>
))}
</CollapsibleContent>
@@ -1004,9 +1342,44 @@ export function Routines() {
})}
</div>
)}
+ </div>
</div>
) : null}
+ <FolderFormDialog
+ open={folderDialogOpen}
+ kind="routine"
+ folder={folderDialogTarget}
+ pending={createFolder.isPending || updateFolder.isPending}
+ onOpenChange={setFolderDialogOpen}
+ onSubmit={(payload) => {
+ if (folderDialogTarget) updateFolder.mutate({ folderId: folderDialogTarget.id, payload });
+ else createFolder.mutate(payload);
+ }}
+ />
+ <DeleteFolderDialog
+ open={deleteFolderTarget !== null}
+ folder={deleteFolderTarget}
+ itemLabelPlural="routines"
+ pending={deleteFolder.isPending}
+ onOpenChange={(open) => {
+ if (!open) setDeleteFolderTarget(null);
+ }}
+ onConfirm={() => {
+ if (deleteFolderTarget) deleteFolder.mutate(deleteFolderTarget.id);
+ }}
+ />
+ <MobileFolderSheet
+ open={mobileFoldersOpen}
+ onOpenChange={setMobileFoldersOpen}
+ result={railFolderResult}
+ selection={folderSelection}
+ allLabel="All routines"
+ itemLabelPlural="Routines"
+ onSelect={setFolderSelection}
+ onCreate={() => openCreateFolder()}
+ />
+
<RoutineRunVariablesDialog
open={runDialogRoutine !== null}
onOpenChange={(next) => {
@@ -1028,3 +1401,13 @@ export function Routines() {
</div>
);
}
+
+function FolderIconHeader({ label, count }: { label: string; count: number }) {
+ return (
+ <div className="flex min-w-0 items-center gap-2 text-sm">
+ <Repeat className="h-3.5 w-3.5 text-muted-foreground" />
+ <span className="truncate font-medium">{label}</span>
+ <span className="text-muted-foreground">{count} routine{count === 1 ? "" : "s"}</span>
+ </div>
+ );
+}
diff --git a/ui/src/pages/SkillStudio.test.tsx b/ui/src/pages/SkillStudio.test.tsx
index 3ed0cb3afd..a8afa4b62f 100644
--- a/ui/src/pages/SkillStudio.test.tsx
+++ b/ui/src/pages/SkillStudio.test.tsx
@@ -368,6 +368,26 @@ describe("SkillStudio create mode", () => {
await waitFor(() => expect(mockNavigate).toHaveBeenCalledWith("/skills/studio/created-skill"));
});
+ it("forwards the folderId query param so the new skill is filed there (PAP-14086)", async () => {
+ routeState.search = "?folderId=folder-my-skills";
+
+ const node = await renderStudio();
+
+ await waitFor(() => expect(node.querySelector("#skill-name")).toBeTruthy());
+ await inputValue(node.querySelector("#skill-name") as HTMLInputElement, "Code Review");
+ await click(buttonsNamed(node, "Create skill")[0] as HTMLButtonElement);
+
+ await waitFor(() => expect(mockCompanySkillsApi.create).toHaveBeenCalled());
+
+ expect(mockCompanySkillsApi.create).toHaveBeenCalledWith(
+ "company-1",
+ expect.objectContaining({
+ name: "Code Review",
+ folderId: "folder-my-skills",
+ }),
+ );
+ });
+
it("keeps category commas and spaces editable while creating a skill", async () => {
const node = await renderStudio();
diff --git a/ui/src/pages/SkillStudio.tsx b/ui/src/pages/SkillStudio.tsx
index c77f5d72c4..953d43a4ee 100644
--- a/ui/src/pages/SkillStudio.tsx
+++ b/ui/src/pages/SkillStudio.tsx
@@ -277,6 +277,10 @@ export function SkillStudio() {
const companyId = selectedCompanyId ?? "";
const isCreateMode = location.pathname.replace(/\/+$/, "").endsWith("/skills/studio/new");
const forkFromSkillId = isCreateMode ? searchParams.get("forkFrom")?.trim() || null : null;
+ // New skills created from a folder context (e.g. My Skills) carry their
+ // destination folder through this query param; without it the created skill
+ // silently lands in Unfiled (PAP-14086).
+ const newSkillFolderId = isCreateMode ? searchParams.get("folderId")?.trim() || null : null;
const skillsQuery = useQuery({
queryKey: queryKeys.companySkills.list(companyId),
@@ -333,6 +337,7 @@ export function SkillStudio() {
skills={skillsQuery.data ?? []}
skillsLoading={skillsQuery.isLoading}
forkFromSkillId={forkFromSkillId}
+ folderId={newSkillFolderId}
forkSkill={forkDetailQuery.data ?? null}
forkLoading={forkDetailQuery.isLoading}
forkError={forkDetailQuery.isError}
@@ -373,6 +378,7 @@ function StudioCreateMode({
skills,
skillsLoading,
forkFromSkillId,
+ folderId,
forkSkill,
forkLoading,
forkError,
@@ -382,6 +388,7 @@ function StudioCreateMode({
skills: CompanySkillListItem[];
skillsLoading: boolean;
forkFromSkillId: string | null;
+ folderId: string | null;
forkSkill: CompanySkillDetail | null;
forkLoading: boolean;
forkError: boolean;
@@ -403,6 +410,7 @@ function StudioCreateMode({
<StudioNewSkillPanel
companyId={companyId}
forkFromSkillId={forkFromSkillId}
+ folderId={folderId}
forkSkill={forkSkill}
forkLoading={forkLoading}
forkError={forkError}
@@ -416,12 +424,14 @@ function StudioCreateMode({
function StudioNewSkillPanel({
companyId,
forkFromSkillId,
+ folderId,
forkSkill,
forkLoading,
forkError,
}: {
companyId: string;
forkFromSkillId: string | null;
+ folderId: string | null;
forkSkill: CompanySkillDetail | null;
forkLoading: boolean;
forkError: boolean;
@@ -429,10 +439,12 @@ function StudioNewSkillPanel({
const navigate = useNavigate();
const queryClient = useQueryClient();
const toast = useOptionalToastActions();
- const initialDraft = useMemo(
- () => (forkSkill ? buildForkSkillDraft(forkSkill) : buildBlankSkillDraft()),
- [forkSkill],
- );
+ const initialDraft = useMemo(() => {
+ const base = forkSkill ? buildForkSkillDraft(forkSkill) : buildBlankSkillDraft();
+ // An explicit folder context from the URL wins over a fork source's folder
+ // so the new skill is filed where the user launched creation (PAP-14086).
+ return folderId ? { ...base, folderId } : base;
+ }, [forkSkill, folderId]);
const [draft, setDraft] = useState<SkillCreateDraft>(initialDraft);
const [slugDirty, setSlugDirty] = useState(initialDraft.slug.trim().length > 0);
const [categoryDraft, setCategoryDraft] = useState(initialDraft.categories.join(", "));