cue-ai 0.9.0 → 0.9.2

package/src/lib/repos.ts

@@ -0,0 +1,167 @@
+/**
+ * Source-repo provenance for the studio Profiles "Repos" tab — the GitHub
+ * repositories a profile's skills, MCPs, plugins and workflows originate from,
+ * with live star counts.
+ *
+ * cue has no machine-readable repo field per component, so the mapping is a
+ * curated catalog: each entry declares what it `provides` (namespaces / MCP ids
+ * / plugin names), and `reposForProfile` keeps only the entries a given profile
+ * actually contains. Every repo is a real GitHub repo so its star count is a
+ * live fetch (cached + fail-soft), satisfying the "auto-update the stars" ask.
+ */
+
+export type RepoKind = "profile" | "skill" | "mcp" | "plugin" | "workflow" | "cli";
+
+interface RepoProvides {
+  /** Skill namespaces (first path segment) this repo is the source of. */
+  ns?: string[];
+  /** MCP server ids this repo ships. */
+  mcps?: string[];
+  /** Plugin names (bare, no @marketplace) this repo ships. */
+  plugins?: string[];
+}
+
+export interface RepoCatalogEntry {
+  /** "owner/name" — the GitHub slug. */
+  repo: string;
+  desc: string;
+  provides: RepoProvides;
+  kinds: RepoKind[];
+}
+
+export interface RepoEntry {
+  repo: string;
+  url: string;
+  desc: string;
+  kinds: RepoKind[];
+  /** Live GitHub stargazer count, or null when it couldn't be fetched. */
+  stars: number | null;
+}
+
+/**
+ * Curated provenance catalog. Every `repo` is a real GitHub slug so the star
+ * fetch resolves; entries the active profile doesn't contain are filtered out.
+ */
+export const REPO_CATALOG: RepoCatalogEntry[] = [
+  {
+    repo: "opencue/cuecards",
+    desc: "The cue runtime — profiles, the meta toolkit and smart-loader.",
+    provides: { ns: ["meta", "caveman", "plan", "review", "gstack", "github", "design"] },
+    kinds: ["profile", "skill"],
+  },
+  {
+    repo: "anthropics/skills",
+    desc: "npx skill bundle — pdf, docx and pptx authoring.",
+    provides: { ns: ["npx"] },
+    kinds: ["skill"],
+  },
+  {
+    repo: "lightpanda-io/browser",
+    desc: "Fast headless browser, exposed as an MCP server.",
+    provides: { ns: ["browser"], mcps: ["lightpanda"] },
+    kinds: ["mcp", "skill"],
+  },
+  {
+    repo: "upstash/context7",
+    desc: "Up-to-date, version-specific library docs as an MCP server.",
+    provides: { ns: ["tools"], mcps: ["context7"] },
+    kinds: ["mcp", "skill"],
+  },
+  {
+    repo: "thedotmack/claude-mem",
+    desc: "Persistent memory plugin — skills under the plugin/ namespace.",
+    provides: { plugins: ["claude-mem"] },
+    kinds: ["plugin"],
+  },
+  {
+    repo: "coollabsio/coolify",
+    desc: "Self-hosted deploy platform — the upstream behind cue's coolify MCP.",
+    provides: { mcps: ["coolify"] },
+    kinds: ["mcp", "skill"],
+  },
+  {
+    repo: "supabase/supabase",
+    desc: "Open-source Postgres backend — exposed as an MCP server.",
+    provides: { mcps: ["supabase"] },
+    kinds: ["mcp", "skill"],
+  },
+  {
+    repo: "vercel/vercel",
+    desc: "Deploy + host web apps — the vercel Claude Code plugin's upstream.",
+    provides: { plugins: ["vercel"] },
+    kinds: ["plugin"],
+  },
+];
+
+/** Strip a plugin id's `@marketplace` suffix → its bare name. */
+function pluginName(id: string): string {
+  const at = id.indexOf("@");
+  return at > 0 ? id.slice(0, at) : id;
+}
+
+/**
+ * Keep only catalog entries the profile actually contains: a repo matches when
+ * it provides a namespace the profile has, an MCP it connects, or a plugin it
+ * wires. Pure + exported so it's unit-testable without a network round-trip.
+ */
+export function reposForProfile(opts: {
+  namespaces: Iterable<string>;
+  mcpIds: Iterable<string>;
+  pluginIds: Iterable<string>;
+}): RepoCatalogEntry[] {
+  const ns = new Set(opts.namespaces);
+  const mcps = new Set(opts.mcpIds);
+  const plugins = new Set([...opts.pluginIds].map(pluginName));
+  return REPO_CATALOG.filter((r) => {
+    const p = r.provides;
+    if (p.ns?.some((n) => ns.has(n))) return true;
+    if (p.mcps?.some((m) => mcps.has(m))) return true;
+    if (p.plugins?.some((pl) => plugins.has(pl))) return true;
+    return false;
+  });
+}
+
+// ── live star counts ────────────────────────────────────────────────────────
+// One GitHub API GET per repo, cached 6h, fail-soft. The unauthenticated rate
+// limit (60/hr) is ample for a handful of repos behind the cache.
+
+const STAR_TTL_MS = 6 * 60 * 60 * 1000;
+const starCache = new Map<string, { ts: number; stars: number | null }>();
+
+/** Fetch one repo's stargazer count, cached + fail-soft (null on any error). */
+export async function fetchStars(repo: string, now: number): Promise<number | null> {
+  const cached = starCache.get(repo);
+  if (cached && now - cached.ts < STAR_TTL_MS) return cached.stars;
+  let stars: number | null = null;
+  try {
+    const res = await fetch(`https://api.github.com/repos/${repo}`, {
+      headers: { "User-Agent": "cue-studio", Accept: "application/vnd.github+json" },
+      signal: AbortSignal.timeout(3000),
+    });
+    if (res.ok) {
+      const body = (await res.json()) as { stargazers_count?: number };
+      if (typeof body.stargazers_count === "number") stars = body.stargazers_count;
+    }
+  } catch {
+    // offline / timeout / rate-limited → null this cycle. Keep any prior value
+    // so a transient failure doesn't blank a previously-known count.
+    if (cached) return cached.stars;
+  }
+  starCache.set(repo, { ts: now, stars });
+  return stars;
+}
+
+/** Resolve a matched catalog into display rows with live star counts. */
+export async function resolveRepoStars(matched: RepoCatalogEntry[], now: number): Promise<RepoEntry[]> {
+  const settled = await Promise.allSettled(matched.map((r) => fetchStars(r.repo, now)));
+  return matched.map((r, i) => {
+    const s = settled[i];
+    return {
+      repo: r.repo,
+      url: `https://github.com/${r.repo}`,
+      desc: r.desc,
+      kinds: r.kinds,
+      stars: s && s.status === "fulfilled" ? s.value : null,
+    };
+  });
+}

package/src/lib/resolver-npx.ts

@@ -29,7 +29,6 @@ import { ProfileError } from "../../profiles/_types";
 import {
   cacheChildren,
   cacheHit,
-  cachePath,
   cachePut,
   cacheSkillPath,
   type CacheLayout,
@@ -125,10 +124,20 @@ export const npxFetch: NpxFetchFn = async (repo, pin, skill, destDir) => {
     const ref = pin.replace(/^git@/, "").replace(/^tag@/, "");
     args.push("--ref", ref);
   }
+  // Defense-in-depth: a single wedged `npx skills add` must never hang the
+  // whole run. On timeout spawnSync sets res.error (ETIMEDOUT), which maps to
+  // NpxFetchFailed below. CUE_NPX_TIMEOUT_MS overrides; a non-positive or
+  // non-numeric value (incl. "" → 0, which would DISABLE the timeout) falls
+  // back to the 45s default rather than silently defeating the guard.
+  const envTimeout = Number(process.env.CUE_NPX_TIMEOUT_MS);
+  const npxTimeoutMs = Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : 45000;
   const res = spawnSync("npx", args, {
     cwd: destDir,
     stdio: ["ignore", "pipe", "pipe"],
     encoding: "utf8",
+    timeout: npxTimeoutMs,
+    killSignal: "SIGKILL",
+    windowsHide: true,
   });
   if (res.error) {
     throw new NpxFetchFailed(repo, res.error.message, res.error);

package/src/lib/runtime-materializer.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test, beforeEach, afterEach } from "bun:test";
-import { mkdtemp, mkdir, writeFile, readFile, stat, lstat, rm, readlink } from "node:fs/promises";
+import { mkdtemp, mkdir, writeFile, readFile, stat, lstat, rm, readlink, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -96,10 +96,54 @@ describe("materializeRuntime", () => {
       mcpRegistry: {},
       userClaudeMd: "",
     });
-    const link = await readlink(join(out.runtimeDir, "skills", "design", "ui-ux-pro-max"));
+    // Flat layout (skills/<slug>) so Claude Code's one-level discovery finds it.
+    const link = await readlink(join(out.runtimeDir, "skills", "ui-ux-pro-max"));
     expect(link).toBe("/fake/source/design/ui-ux-pro-max");
   });
 
+  test("writes a .cue-skills manifest of <category>/<slug> ids for smart-loader", async () => {
+    const out = await materializeRuntime({
+      profile: sampleProfile,
+      agent: "claude-code",
+      runtimeRoot: join(root, "runtime"),
+      skillSourceLookup: async (id) => `/fake/source/${id}`,
+      mcpRegistry: {},
+      userClaudeMd: "",
+    });
+    const manifest = await readFile(join(out.runtimeDir, ".cue-skills"), "utf8");
+    expect(manifest.split("\n").filter(Boolean)).toContain("design/ui-ux-pro-max");
+  });
+
+  test("slug collisions resolve last-wins; both ids stay in the manifest", async () => {
+    const collide: ResolvedProfile = {
+      ...sampleProfile,
+      skills: {
+        ...sampleProfile.skills,
+        local: [
+          { id: "plan/investigate" },
+          { id: "gstack/investigate" },
+        ],
+      },
+    };
+    const out = await materializeRuntime({
+      profile: collide,
+      agent: "claude-code",
+      runtimeRoot: join(root, "runtime"),
+      skillSourceLookup: async (id) => `/fake/source/${id}`,
+      mcpRegistry: {},
+      userClaudeMd: "",
+    });
+    // The later entry (gstack/investigate) wins the flat /investigate link.
+    const link = await readlink(join(out.runtimeDir, "skills", "investigate"));
+    expect(link).toBe("/fake/source/gstack/investigate");
+    // Both remain in the manifest so smart-loader knows the lean one is loaded too.
+    const manifest = (await readFile(join(out.runtimeDir, ".cue-skills"), "utf8"))
+      .split("\n")
+      .filter(Boolean);
+    expect(manifest).toContain("plan/investigate");
+    expect(manifest).toContain("gstack/investigate");
+  });
+
   test("excludes resources whose agents list does not include current agent", async () => {
     const filtered: ResolvedProfile = {
       ...sampleProfile,
@@ -238,7 +282,7 @@ describe("materializeRuntime", () => {
   test("credentialsSource: refreshes settings on cache hit + repoints symlinks on account switch", async () => {
     const credSrcA = join(root, "credsA");
     const credSrcB = join(root, "credsB");
-    const { mkdir, writeFile, readlink } = await import("node:fs/promises");
+    const { mkdir, writeFile } = await import("node:fs/promises");
     await mkdir(credSrcA, { recursive: true });
     await mkdir(credSrcB, { recursive: true });
     await writeFile(join(credSrcA, ".credentials.json"), '{"token":"A"}');
@@ -280,6 +324,78 @@ describe("materializeRuntime", () => {
     expect(s2.permissions.allow).toEqual(["B"]);
   });
 
+  test("credentialsSource: rebuild keeps the freshest token (no logged-out-after-relaunch)", async () => {
+    // Regression: Anthropic rotates the refresh token on every refresh. The old
+    // preserve step blindly resurrected the runtime's own .credentials.json on a
+    // rebuild — even when it held a dead, rotated token while the freshly-synced
+    // source had the live one — booting the relaunched profile into a logged-out
+    // state. The preserve step must keep whichever token has the higher expiresAt.
+    const stale = join(root, "src-stale");
+    const fresh = join(root, "src-fresh");
+    await mkdir(stale, { recursive: true });
+    await mkdir(fresh, { recursive: true });
+    const STALE = 1_000;
+    const FRESH = 9_000_000_000_000;
+    await writeFile(join(stale, ".credentials.json"), JSON.stringify({ claudeAiOauth: { expiresAt: STALE, refreshToken: "dead" } }));
+    await writeFile(join(fresh, ".credentials.json"), JSON.stringify({ claudeAiOauth: { expiresAt: FRESH, refreshToken: "live" } }));
+
+    const base = {
+      agent: "claude-code" as const,
+      runtimeRoot: join(root, "runtime"),
+      skillSourceLookup: async (id: string) => `/fake/source/${id}`,
+      mcpRegistry: { "claude-mem": { command: "claude-mem" } },
+      userClaudeMd: "",
+    };
+    const p1: ResolvedProfile = { ...sampleProfile, name: "rotate" };
+    // Extra skill → different hash → forces a REBUILD (exercises the preserve step).
+    const p2: ResolvedProfile = { ...sampleProfile, name: "rotate", skills: { local: [{ id: "design/ui-ux-pro-max" }, { id: "design/extra" }], npx: [] } };
+
+    // First launch: runtime ends up with the (then-current) STALE source token.
+    const first = await materializeRuntime({ ...base, profile: p1, credentialsSource: stale });
+    expect(first.rebuilt).toBe(true);
+
+    // syncFreshestToSource has since healed source to the live token. Relaunch
+    // with a changed profile → rebuild path runs the preserve step.
+    const second = await materializeRuntime({ ...base, profile: p2, credentialsSource: fresh });
+    expect(second.rebuilt).toBe(true);
+
+    const creds = JSON.parse(await readFile(join(second.runtimeDir, ".credentials.json"), "utf8"));
+    expect(creds.claudeAiOauth.expiresAt).toBe(FRESH);
+    expect(creds.claudeAiOauth.refreshToken).toBe("live");
+  });
+
+  test("credentialsSource: rebuild keeps the runtime token when source is half-logged-out", async () => {
+    // Inverse guard: if SOURCE is stale/half-logged-out (no/low expiresAt) but the
+    // runtime is logged in (fresh token), a rebuild must NOT clobber the live
+    // runtime token with the dead source one. Preserves the original intent.
+    const fresh = join(root, "src-fresh");
+    const loggedOut = join(root, "src-loggedout");
+    await mkdir(fresh, { recursive: true });
+    await mkdir(loggedOut, { recursive: true });
+    const FRESH = 9_000_000_000_000;
+    await writeFile(join(fresh, ".credentials.json"), JSON.stringify({ claudeAiOauth: { expiresAt: FRESH, refreshToken: "live" } }));
+    await writeFile(join(loggedOut, ".credentials.json"), JSON.stringify({ claudeAiOauth: { refreshToken: "" } }));
+
+    const base = {
+      agent: "claude-code" as const,
+      runtimeRoot: join(root, "runtime"),
+      skillSourceLookup: async (id: string) => `/fake/source/${id}`,
+      mcpRegistry: { "claude-mem": { command: "claude-mem" } },
+      userClaudeMd: "",
+    };
+    const p1: ResolvedProfile = { ...sampleProfile, name: "rotate2" };
+    const p2: ResolvedProfile = { ...sampleProfile, name: "rotate2", skills: { local: [{ id: "design/ui-ux-pro-max" }, { id: "design/extra" }], npx: [] } };
+
+    const first = await materializeRuntime({ ...base, profile: p1, credentialsSource: fresh });
+    expect(first.rebuilt).toBe(true);
+    const second = await materializeRuntime({ ...base, profile: p2, credentialsSource: loggedOut });
+    expect(second.rebuilt).toBe(true);
+
+    const creds = JSON.parse(await readFile(join(second.runtimeDir, ".credentials.json"), "utf8"));
+    expect(creds.claudeAiOauth.expiresAt).toBe(FRESH);
+    expect(creds.claudeAiOauth.refreshToken).toBe("live");
+  });
+
   test("CLAUDE.md stamp uses real ISO timestamp, not literal $(date)", async () => {
     const out = await materializeRuntime({
       profile: sampleProfile,
@@ -421,6 +537,31 @@ describe("materializeRuntime", () => {
     expect(link).toContain("resources/hooks/bash-quality-preflight.json");
   });
 
+  test("hooks: auto-review Stop hook + its .sh companion both land in the runtime", async () => {
+    const profile: ResolvedProfile = {
+      ...sampleProfile,
+      name: "test-auto-review",
+      inheritanceChain: ["test-auto-review"],
+      rules: [], commands: [],
+      hooks: ["auto-review.json"],
+    };
+    const out = await materializeRuntime({
+      profile, agent: "claude-code",
+      runtimeRoot: join(root, "runtime"),
+      skillSourceLookup: async (id) => `/fake/source/${id}`,
+      mcpRegistry: {},
+      userClaudeMd: "",
+    });
+    const settings = JSON.parse(await readFile(join(out.runtimeDir, "settings.json"), "utf8"));
+    expect(settings.hooks.Stop).toBeArray();
+    expect(settings.hooks.Stop[0].hooks[0].id).toBe("cue:stop:auto-review");
+    expect(settings.hooks.Stop[0].hooks[0].command).toContain("auto-review.sh");
+    // The reviewer script companion must be symlinked too, else the hook fires
+    // `bash $CLAUDE_CONFIG_DIR/hooks/auto-review.sh` against a missing file.
+    const script = await readlink(join(out.runtimeDir, "hooks", "auto-review.sh"));
+    expect(script).toContain("resources/hooks/auto-review.sh");
+  });
+
   // Claude Code reads MCP servers from .claude.json (top-level `mcpServers`),
   // NOT from settings.json. The materializer must therefore merge profile MCPs
   // into .claude.json — and copy (not symlink) it so mutations don't leak back
@@ -675,6 +816,62 @@ describe("isRuntimeStale", () => {
     await writeFile(join(profilesRoot, "p3", "profile.yaml"), "name: x\n");
     expect(await isRuntimeStale("p3", "claude-code", runtimeRoot)).toBe(false);
   });
+
+  async function writeRuntimeSkill(name: string, runtimeRoot: string, slug: string): Promise<string> {
+    const skillDir = join(runtimeRoot, name, "claude", "skills", slug);
+    await mkdir(skillDir, { recursive: true });
+    const md = join(skillDir, "SKILL.md");
+    await writeFile(md, `# ${slug}\n`);
+    return md;
+  }
+
+  test("returns true when a resolved SKILL.md is newer than .cue-hash (yaml older)", async () => {
+    const runtimeRoot = join(root, "runtime");
+    const { yamlPath, hashPath } = await setup("p4", runtimeRoot);
+    const mdPath = await writeRuntimeSkill("p4", runtimeRoot, "alpha");
+    await utimes(yamlPath, new Date(Date.now() - 120_000), new Date(Date.now() - 120_000));
+    await utimes(hashPath, new Date(Date.now() - 60_000), new Date(Date.now() - 60_000));
+    await utimes(mdPath, new Date(), new Date());
+    expect(await isRuntimeStale("p4", "claude-code", runtimeRoot)).toBe(true);
+  });
+
+  test("returns false when every SKILL.md is older than .cue-hash", async () => {
+    const runtimeRoot = join(root, "runtime");
+    const { yamlPath, hashPath } = await setup("p5", runtimeRoot);
+    const mdPath = await writeRuntimeSkill("p5", runtimeRoot, "alpha");
+    const old = new Date(Date.now() - 60_000);
+    await utimes(yamlPath, old, old);
+    await utimes(mdPath, old, old);
+    await utimes(hashPath, new Date(), new Date());
+    expect(await isRuntimeStale("p5", "claude-code", runtimeRoot)).toBe(false);
+  });
+
+  test("skips a slug dir with no SKILL.md (broken symlink is non-fatal)", async () => {
+    const runtimeRoot = join(root, "runtime");
+    const { yamlPath, hashPath } = await setup("p6", runtimeRoot);
+    await mkdir(join(runtimeRoot, "p6", "claude", "skills", "broken"), { recursive: true });
+    await utimes(yamlPath, new Date(Date.now() - 60_000), new Date(Date.now() - 60_000));
+    await utimes(hashPath, new Date(), new Date());
+    expect(await isRuntimeStale("p6", "claude-code", runtimeRoot)).toBe(false);
+  });
+
+  test("detects a newer SKILL.md through a symlinked skill dir (production layout)", async () => {
+    const runtimeRoot = join(root, "runtime");
+    const { yamlPath, hashPath } = await setup("p7", runtimeRoot);
+    // Production materialize symlinks skills/<slug> → the source skill dir; the
+    // SKILL.md inside is a real file, so lstat resolves through to its mtime.
+    const src = join(profilesRoot, "src-skill-p7");
+    await mkdir(src, { recursive: true });
+    const srcMd = join(src, "SKILL.md");
+    await writeFile(srcMd, "# s\n");
+    const skillsDir = join(runtimeRoot, "p7", "claude", "skills");
+    await mkdir(skillsDir, { recursive: true });
+    await symlink(src, join(skillsDir, "s"));
+    await utimes(yamlPath, new Date(Date.now() - 120_000), new Date(Date.now() - 120_000));
+    await utimes(hashPath, new Date(Date.now() - 60_000), new Date(Date.now() - 60_000));
+    await utimes(srcMd, new Date(), new Date());
+    expect(await isRuntimeStale("p7", "claude-code", runtimeRoot)).toBe(true);
+  });
 });
 
 describe("linkPluginCache", () => {

package/src/lib/runtime-materializer.ts

@@ -74,25 +74,58 @@ function profilesDir(): string {
 
 /**
  * Staleness predicate shared with `cue doctor`'s D5 check: a materialized
- * runtime is stale when the profile's source `profile.yaml` was modified more
- * recently than the stored `.cue-hash`. Mirror, not duplicate — doctor reports
- * it, launch acts on it (auto-rebuild). Returns false when either file is
- * absent (no runtime yet, or no source to compare against): the normal
- * content-hash path in materializeRuntime handles those cases.
+ * runtime is stale when the profile's source `profile.yaml` OR any resolved
+ * skill's `SKILL.md` was modified more recently than the stored `.cue-hash`.
+ * Mirror, not duplicate — doctor reports it, launch acts on it (auto-rebuild).
+ *
+ * The SKILL.md check makes "edit a skill → relaunch → see the change" work:
+ * the materialized runtime's own `skills/<slug>` entries are symlinks to the
+ * source skill dirs, so lstat'ing `skills/<slug>/SKILL.md` resolves through to
+ * the real source file's mtime (only the final path component is treated
+ * specially by lstat, and SKILL.md is never itself a symlink). This is
+ * automatically scoped to the agent and to any conditional/subset pruning.
+ *
+ * Returns false when there's no runtime yet (no `.cue-hash`): the content-hash
+ * path in materializeRuntime handles a fresh build. Fail-open per entry — a
+ * deleted skill source (broken symlink) is skipped, not fatal (the profile.yaml
+ * edit that removed it already trips the yaml branch).
  */
 export async function isRuntimeStale(
   profileName: string,
   agent: AgentKind,
   runtimeRoot: string,
 ): Promise<boolean> {
-  const hashFile = join(runtimeRoot, profileName, agentSubdir(agent), ".cue-hash");
-  const yamlPath = join(profilesDir(), profileName, "profile.yaml");
+  const runtimeDir = join(runtimeRoot, profileName, agentSubdir(agent));
+  const hashFile = join(runtimeDir, ".cue-hash");
+  let hashMtime: number;
   try {
-    const [hashStat, yamlStat] = await Promise.all([lstat(hashFile), lstat(yamlPath)]);
-    return yamlStat.mtimeMs > hashStat.mtimeMs;
+    hashMtime = (await lstat(hashFile)).mtimeMs;
   } catch {
-    return false;
+    return false; // no runtime yet — materializeRuntime's content hash handles it
   }
+
+  // (a) Source profile.yaml newer than the hash. Its own try/catch so a missing
+  //     yaml doesn't short-circuit the skill check below.
+  try {
+    if ((await lstat(join(profilesDir(), profileName, "profile.yaml"))).mtimeMs > hashMtime) {
+      return true;
+    }
+  } catch { /* no source yaml — fall through to the skill check */ }
+
+  // (b) Any resolved SKILL.md newer than the hash.
+  const skillsDir = join(runtimeDir, "skills");
+  let slugs: string[];
+  try {
+    slugs = await readdir(skillsDir);
+  } catch {
+    return false; // no skills/ dir → nothing more to compare
+  }
+  for (const slug of slugs) {
+    try {
+      if ((await lstat(join(skillsDir, slug, "SKILL.md"))).mtimeMs > hashMtime) return true;
+    } catch { /* broken symlink / no SKILL.md under this slug — skip */ }
+  }
+  return false;
 }
 
 function appliesToAgent(scoped: { agents?: AgentKind[] }, agent: AgentKind): boolean {
@@ -108,8 +141,15 @@ function sortedJson(value: unknown): string {
   return "{" + keys.map((k) => JSON.stringify(k) + ":" + sortedJson(obj[k])).join(",") + "}";
 }
 
+// Bump when the on-disk runtime layout changes in a way the profile content
+// doesn't capture (e.g. flat vs nested skills, new manifest files). Folding it
+// into the hash forces every profile to rebuild once on its next launch, so
+// layout fixes roll out without a manual `--rematerialize` per profile.
+//   v2: flat skill layout + .cue-skills manifest (was nested <category>/<slug>)
+const MATERIALIZER_VERSION = 2;
+
 function computeHash(profile: ResolvedProfile, agent: AgentKind): string {
-  const canonical = sortedJson({ agent, profile });
+  const canonical = sortedJson({ v: MATERIALIZER_VERSION, agent, profile });
   return createHash("sha256").update(canonical).digest("hex");
 }
 
@@ -175,19 +215,58 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
   await mkdir(skillsDir, { recursive: true });
   const skippedSkills: string[] = [];
   let attemptedSkills = 0;
+  // Skills are linked FLAT — skills/<slug>, not skills/<category>/<slug>.
+  // Claude Code (and Codex) only register a personal skill one level deep, by
+  // its directory name (skills/<name>/SKILL.md → /<name>); a nested category
+  // dir is invisible to that scan. Flattening matches `activate-profile.sh`'s
+  // manual installer and lets every profile skill be invoked via the Skill
+  // tool — including the slug==category cases (caveman/caveman, github/github,
+  // colony/colony) that a nested layout can't expose. smart-loader's dedup no
+  // longer reads the dir tree; it reads the `.cue-skills` manifest written
+  // below, which preserves the <category>/<slug> identity.
+  const loadedSkillIds: string[] = [];
+  // Resolve first, link second, so slug collisions resolve by LAST-WINS: when
+  // two skills share a slug (e.g. plan/investigate lean vs gstack/investigate
+  // full), the later entry wins the flat /<slug> name. Skill lists merge
+  // parent→child (core first, profile last), so last-wins = the more-specific
+  // profile's choice overrides the inherited one — the standard override rule.
+  // The loser is still in the manifest, so smart-loader can surface it.
+  const slugToSrc = new Map<string, string>();
+  const slugToId = new Map<string, string>();
+  const overridden: string[] = [];
   for (const skill of profile.skills.local) {
     if (!appliesToAgent(skill, agent)) continue;
     if (skill.when && !evaluateCondition(skill.when, process.cwd())) continue;
     attemptedSkills++;
     try {
       const src = await input.skillSourceLookup(skill.id);
-      const target = join(skillsDir, skill.id);
-      await mkdir(dirname(target), { recursive: true });
-      await symlink(src, target);
+      loadedSkillIds.push(skill.id);
+      const slug = basename(skill.id);
+      const prevId = slugToId.get(slug);
+      if (prevId !== undefined && prevId !== skill.id) {
+        overridden.push(`${slug}: ${prevId} → ${skill.id}`);
+      }
+      slugToSrc.set(slug, src);
+      slugToId.set(slug, skill.id);
     } catch (err) {
       skippedSkills.push(skill.id);
     }
   }
+  for (const [slug, src] of slugToSrc) {
+    await symlink(src, join(skillsDir, slug));
+  }
+  if (overridden.length > 0) {
+    process.stderr.write(
+      `[cue] ${overridden.length} skill slug collision(s) resolved last-wins ` +
+      `(loser still smart-loadable): ${overridden.join("; ")}\n`,
+    );
+  }
+  // Manifest for smart-loader's --exclude-loaded: the resolved <category>/<slug>
+  // ids, decoupled from the (now flat) on-disk layout.
+  await writeFile(
+    join(tmpDir, ".cue-skills"),
+    loadedSkillIds.length > 0 ? `${loadedSkillIds.join("\n")}\n` : "",
+  );
   if (skippedSkills.length > 0) {
     process.stderr.write(
       `[cue] skipped ${skippedSkills.length} missing skill(s): ${skippedSkills.slice(0, 5).join(", ")}` +
@@ -643,12 +722,26 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
     const newPath = join(tmpDir, name);
     try {
       const st = await lstat(oldPath);
-      if (st.isFile() || st.isDirectory()) {
-        // Remove whatever overlay put here (likely a symlink for .claude.json
-        // or a copy for .credentials.json) so rename can replace it cleanly.
-        await rm(newPath, { force: true, recursive: true });
-        await rename(oldPath, newPath);
+      if (!(st.isFile() || st.isDirectory())) continue;
+      if (name === ".credentials.json") {
+        // Freshness guard — fixes "logged-out after relaunch". Anthropic rotates
+        // the refresh token on every refresh, so only the copy with the highest
+        // expiresAt still holds a live refresh token. Step 5's overlay already
+        // placed the freshly-synced SOURCE creds in tmpDir (and
+        // resolveClaudeCredentialsSource healed source from the freshest sibling
+        // runtime first). Resurrect the OLD runtime's creds ONLY when they are
+        // strictly newer than source — otherwise keep source, so a rebuild can't
+        // drag a dead, rotated token back into the runtime. When source is
+        // half-logged-out its expiresAt is 0/old, so a logged-in runtime still
+        // wins and stays logged in (the original intent of this preserve step).
+        const oldExp = await credentialsExpiresAt(oldPath);
+        const newExp = await credentialsExpiresAt(newPath);
+        if (oldExp <= newExp) continue; // source as-fresh-or-fresher → keep it
       }
+      // Remove whatever overlay put here (likely a symlink for .claude.json
+      // or a copy for .credentials.json) so rename can replace it cleanly.
+      await rm(newPath, { force: true, recursive: true });
+      await rename(oldPath, newPath);
     } catch { /* doesn't exist — skip */ }
   }
   await rm(runtimeDir, { recursive: true, force: true });
@@ -661,6 +754,22 @@ export async function materializeRuntime(input: MaterializeInput): Promise<Mater
   return { runtimeDir, rebuilt: true, hash };
 }
 
+/**
+ * Read `claudeAiOauth.expiresAt` (ms epoch) from a `.credentials.json`. Returns
+ * 0 when the file is missing, unparseable, or carries no expiry — so anything
+ * with a real token sorts as fresher in the rebuild preserve comparison.
+ */
+async function credentialsExpiresAt(path: string): Promise<number> {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw) as { claudeAiOauth?: { expiresAt?: number } };
+    const exp = parsed?.claudeAiOauth?.expiresAt;
+    return typeof exp === "number" ? exp : 0;
+  } catch {
+    return 0;
+  }
+}
+
 function collectProfileMcps(
   profile: ResolvedProfile,
   agent: AgentKind,
@@ -970,7 +1079,7 @@ function tomlRender(obj: { mcp_servers: Record<string, unknown> }): string {
 // ---------------------------------------------------------------------------
 
 import { homedir } from "node:os";
-import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { readdirSync, existsSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 
 async function getLastSessionSummary(profileName: string): Promise<string | null> {

package/src/lib/shared-profiles.ts

@@ -16,6 +16,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { cacheDir } from "./config-paths";
 
 export interface SharedRef {
   /** Originating GitHub user / org. */
@@ -279,9 +280,7 @@ export function registryIndexUrl(): string {
 
 /** Path of the cached index.json on disk. */
 export function indexCachePath(): string {
-  const xdg = process.env.XDG_CACHE_HOME;
-  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".cache");
-  return join(base, "cue", "registry-index.json");
+  return join(cacheDir(), "registry-index.json");
 }
 
 export interface IndexCacheEntry {