@cursor/july 0.1.95 → 0.1.96

package/src/internal/cursor/backend-client.ts

@@ -17,14 +17,15 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import type { McpToolAnnotations } from "../../types.js";
 import { boundedToolAnnotations } from "../mcp-host.js";
+import {
+  CURSOR_SESSION_EXCHANGE_PATH,
+  CursorSessionExchangeError,
+  exchangeCursorApiKeyForSession,
+  SESSION_TOKEN_EXPIRY_LEEWAY_MS,
+} from "./session-token.js";
 
 const CLIENT_VERSION = "agent-serve-0.1.0";
-const EXCHANGE_PATH = "/auth/exchange_user_api_key";
 const SERVICE_PREFIX = "/aiserver.v1.DashboardService";
-/** Re-exchange when the cached token is within this window of expiry. */
-const TOKEN_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
-/** Fallback token lifetime when the JWT `exp` claim cannot be parsed. */
-const FALLBACK_TOKEN_LIFETIME_MS = 30 * 60 * 1000;
 const LIST_TIMEOUT_MS = 60_000;
 /** Backend-executed tools call out to third-party servers; be generous. */
 const EXECUTE_TIMEOUT_MS = 120_000;
@@ -550,7 +551,7 @@ export class CursorBackendClient {
     }
     if (
       this.token !== undefined &&
-      Date.now() < this.token.expiresAtMs - TOKEN_EXPIRY_LEEWAY_MS
+      Date.now() < this.token.expiresAtMs - SESSION_TOKEN_EXPIRY_LEEWAY_MS
     ) {
       return Promise.resolve(this.token.value);
     }
@@ -565,44 +566,39 @@ export class CursorBackendClient {
 
   private async exchangeApiKey(): Promise<string> {
     const apiKey = this.currentApiKey();
-    let response: Response;
+    let session: { token: string; expiresAtMs: number };
     try {
-      response = await this.fetchImpl(`${this.backendUrl}${EXCHANGE_PATH}`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${apiKey}`,
-        },
-        body: "{}",
-        signal: AbortSignal.timeout(30_000),
+      session = await exchangeCursorApiKeyForSession({
+        exchangeUrl: `${this.backendUrl}${CURSOR_SESSION_EXCHANGE_PATH}`,
+        apiKey,
+        fetchImpl: this.fetchImpl,
       });
     } catch (error) {
-      throw new CursorBackendError(
-        `Could not reach the Cursor backend at ${this.backendUrl}: ${describeError(error)}`
-      );
-    }
-    const text = await response.text();
-    if (!response.ok) {
-      throw new CursorBackendError(
-        response.status === 401
-          ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
-          : `Cursor API key exchange failed (${response.status}).`,
-        response.status
-      );
-    }
-    const body = accessTokenResponseSchema.safeParse(safeJsonParse(text));
-    if (!body.success || body.data.accessToken === "") {
-      throw new CursorBackendError(
-        "Cursor API key exchange returned no access token."
-      );
+      if (error instanceof CursorSessionExchangeError) {
+        if (error.status === undefined) {
+          throw new CursorBackendError(
+            `Could not reach the Cursor backend at ${this.backendUrl}: ${error.message}`
+          );
+        }
+        if (error.status >= 200 && error.status < 300) {
+          // 2xx without a token in the body.
+          throw new CursorBackendError(
+            "Cursor API key exchange returned no access token."
+          );
+        }
+        throw new CursorBackendError(
+          error.status === 401
+            ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
+            : `Cursor API key exchange failed (${error.status}).`,
+          error.status
+        );
+      }
+      throw error;
     }
-    this.token = {
-      value: body.data.accessToken,
-      expiresAtMs: jwtExpiryMs(body.data.accessToken),
-    };
+    this.token = { value: session.token, expiresAtMs: session.expiresAtMs };
     this.lastExchangedApiKey = apiKey;
     this.logger("[agent-sdk] cursor account: minted a fresh access token");
-    return body.data.accessToken;
+    return session.token;
   }
 }
 
@@ -705,8 +701,6 @@ export async function revokeMintedUserApiKey(args: {
 // Helpers
 // ============================================================================
 
-const accessTokenResponseSchema = z.object({ accessToken: z.string() });
-
 function safeJsonParse(text: string): unknown {
   try {
     return JSON.parse(text) as unknown;
@@ -883,24 +877,6 @@ function retryAfterMsFromResponse(response: Response): number | undefined {
   return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
 }
 
-function jwtExpiryMs(token: string): number {
-  try {
-    const payload = token.split(".")[1];
-    if (payload === undefined) {
-      throw new Error("not a JWT");
-    }
-    const claims = JSON.parse(
-      Buffer.from(payload, "base64url").toString("utf8")
-    ) as { exp?: unknown };
-    if (typeof claims.exp === "number") {
-      return claims.exp * 1000;
-    }
-  } catch {
-    // Opaque token — assume a conservative lifetime.
-  }
-  return Date.now() + FALLBACK_TOKEN_LIFETIME_MS;
-}
-
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/internal/cursor/session-token.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared `CURSOR_API_KEY` → Cursor session-token exchange primitive
+ * (`POST /auth/exchange_user_api_key`, ~1h session).
+ *
+ * Both `CursorBackendClient` (dashboard RPCs) and the Origin channel's
+ * session provider (`cursorSessionTokenProvider` in
+ * `../../channels/origin/api.ts`) mint through this module, so the URL,
+ * request shape, response parsing, JWT-expiry handling, and renewal
+ * constants cannot drift between the two. Callers own their caching and
+ * retry policies; this module owns exactly one exchange round trip.
+ */
+
+export const CURSOR_SESSION_EXCHANGE_PATH = "/auth/exchange_user_api_key";
+/** Re-exchange when the cached session is within this window of expiry. */
+export const SESSION_TOKEN_EXPIRY_LEEWAY_MS: number = 5 * 60 * 1000;
+/** Fallback session lifetime when the JWT `exp` claim cannot be parsed. */
+export const SESSION_TOKEN_FALLBACK_LIFETIME_MS: number = 30 * 60 * 1000;
+const EXCHANGE_TIMEOUT_MS = 30_000;
+
+/**
+ * Exchange failure. `status` is the HTTP status when the backend answered,
+ * and undefined for network/transport errors. `detail` carries the server's
+ * `error` field when present so callers can surface the reason verbatim.
+ */
+export class CursorSessionExchangeError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly detail?: string
+  ) {
+    super(message);
+    this.name = "CursorSessionExchangeError";
+  }
+}
+
+/** Epoch-ms expiry from a JWT `exp` claim, or undefined when unparsable. */
+export function jwtExpiryMs(token: string): number | undefined {
+  try {
+    const payload = token.split(".")[1];
+    if (payload === undefined) {
+      return undefined;
+    }
+    const claims = JSON.parse(
+      Buffer.from(payload, "base64url").toString("utf8")
+    ) as { exp?: unknown };
+    return typeof claims.exp === "number" ? claims.exp * 1000 : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One exchange round trip. Throws {@link CursorSessionExchangeError} on
+ * transport failure, a non-2xx response, or a token-free body. `expiresAtMs`
+ * comes from the session JWT's `exp` claim, falling back to
+ * {@link SESSION_TOKEN_FALLBACK_LIFETIME_MS} for opaque tokens.
+ */
+export async function exchangeCursorApiKeyForSession(args: {
+  /** Full exchange URL (base + {@link CURSOR_SESSION_EXCHANGE_PATH}). */
+  exchangeUrl: string;
+  apiKey: string;
+  fetchImpl?: typeof fetch;
+  nowMs?: number;
+}): Promise<{ token: string; expiresAtMs: number }> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  let response: Response;
+  try {
+    response = await fetchImpl(args.exchangeUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${args.apiKey}`,
+      },
+      body: "{}",
+      signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw new CursorSessionExchangeError(
+      `Could not reach the Cursor session exchange at ${args.exchangeUrl}: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+  const body: unknown = await response.json().catch(() => undefined);
+  const record =
+    typeof body === "object" && body !== null && !Array.isArray(body)
+      ? (body as Record<string, unknown>)
+      : {};
+  const detail =
+    typeof record.error === "string" && record.error !== ""
+      ? record.error
+      : undefined;
+  if (!response.ok) {
+    throw new CursorSessionExchangeError(
+      `Cursor session exchange failed with HTTP ${response.status}${
+        detail === undefined ? "" : ` (${detail})`
+      }.`,
+      response.status,
+      detail
+    );
+  }
+  const token = record.accessToken;
+  if (typeof token !== "string" || token === "") {
+    throw new CursorSessionExchangeError(
+      "Cursor session exchange returned no access token.",
+      response.status
+    );
+  }
+  const nowMs = args.nowMs ?? Date.now();
+  return {
+    token,
+    expiresAtMs:
+      jwtExpiryMs(token) ?? nowMs + SESSION_TOKEN_FALLBACK_LIFETIME_MS,
+  };
+}

package/src/internal/cursor-agent-template.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 const MAX = 64;
 const TEMPLATE_NAMES = [
   "agentic-owners",
+  "code-wiki",
   "demo",
   "pr-autofixer",
   "security-help",

package/src/internal/framework-file-storage.ts

@@ -0,0 +1,222 @@
+/**
+ * Framework-level file storage for v2 hosted engines.
+ *
+ * Hosted deployments carry two file stores with different audiences:
+ *
+ * - the **user-level** store (`AGENT_SERVE_STORE_SOURCE_ID`) holds
+ *   author-facing bytes — `ctx.host.files`, skills, memory, artifacts — and
+ *   is browsable from the dashboard and mountable on cloud-runtime VMs;
+ * - the **framework-level** store (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`)
+ *   holds engine-owned session state — session records, event transcripts,
+ *   the continuation index, and the SDK conversation mirror — and is never
+ *   exposed to authors or models.
+ *
+ * This module puts framework session state on the framework store. The
+ * {@link storageKeys} scheme was designed for exactly this: keys are a
+ * stable versioned contract that sinks may route on, so
+ * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
+ * kind — `session` / `session-events` / `continuation` go to the framework
+ * file store (file-shaped; the store accepts values up to 64 MiB per
+ * object without chunking, versus the KV proxy's 1 MiB row cap), while
+ * author `kv`, eval runs, A/B samples, and conditional writes stay on the
+ * control-plane KV proxy (the dashboard reads them there, and CAS needs a
+ * database).
+ *
+ * v2 only, by construction: the composite is selected in
+ * framework-storage-selection.ts, which v1 never reaches with a
+ * platform-selected definition.
+ */
+
+import type { FileSink } from "../files.js";
+import type { StorageConfig, StorageEntry } from "../storage.js";
+import { STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import type { JsonValue } from "../types.js";
+import { mapBounded } from "./bounded.js";
+
+/**
+ * Key kinds (`agentkit/v1/{agent}/{kind}/…`) that live on the framework
+ * file store. Everything else stays on the KV sink.
+ */
+const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
+  "session",
+  "session-events",
+  "continuation",
+]);
+
+/**
+ * Whether a framework-minted key (or list prefix) belongs on the framework
+ * file store. Prefixes used by the coordinator are always at least
+ * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
+ */
+export function isFrameworkFileKey(key: string): boolean {
+  if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+    return false;
+  }
+  const rest = key.slice(STORAGE_KEY_ROOT.length + 1);
+  const agentEnd = rest.indexOf("/");
+  if (agentEnd === -1) {
+    return false;
+  }
+  const afterAgent = rest.slice(agentEnd + 1);
+  const kindEnd = afterAgent.indexOf("/");
+  const kind = kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+  return FRAMEWORK_FILE_KINDS.has(kind);
+}
+
+/** The KV core over a {@link FileSink}: one JSON document per key. */
+export type FileSinkStorageCore = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+>;
+
+/**
+ * Adapt a {@link FileSink} to the `defineStorage` KV core. Storage keys are
+ * framework-minted (URI-encoded, length-bounded segments — see
+ * {@link storageKeys}), so they are used as file keys verbatim; values are
+ * stored as JSON bytes. Parse failures throw: on the lazy-restore path a
+ * corrupt document must fail the follow-up rather than read as a miss, and
+ * the startup bulk restore already logs-and-skips a throwing `list`.
+ */
+/** Parallel per-key reads backing `list` (each is presign + object GET). */
+const LIST_READ_CONCURRENCY = 8;
+
+/**
+ * A storage key whose path the file store cannot represent (an empty, `.`,
+ * or `..` segment — possible only through caller-controlled segments such
+ * as continuation tokens or a caller-supplied session id). Such an object
+ * can never exist in the store, so reads are a definitive miss rather than
+ * a per-request 400 that the lazy-restore path would propagate forever.
+ */
+function isUnrepresentableFileKey(key: string): boolean {
+  return key
+    .split("/")
+    .some((segment) => segment === "" || segment === "." || segment === "..");
+}
+
+export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
+  return {
+    async put(key, value): Promise<void> {
+      if (isUnrepresentableFileKey(key)) {
+        // Loud rather than silent: the coordinator logs and drops failed
+        // mirror writes (at-most-once), and awaited callers must not
+        // believe an impossible write landed.
+        throw new Error(
+          `framework file storage: key "${key}" has a path segment the store cannot represent`
+        );
+      }
+      await sink.put(key, new TextEncoder().encode(JSON.stringify(value)));
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      if (isUnrepresentableFileKey(key)) {
+        return undefined;
+      }
+      const body = await sink.get(key);
+      if (body === undefined) {
+        return undefined;
+      }
+      return decodeDocument(key, body instanceof Uint8Array ? body : body.body);
+    },
+    async delete(key): Promise<void> {
+      if (isUnrepresentableFileKey(key)) {
+        return;
+      }
+      await sink.delete(key);
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const entries = await sink.list(prefix);
+      // FileSink.list returns metadata only, so each value is its own
+      // read; bound the fan-out — a bulk read here sits on restore paths.
+      const bodies = await mapBounded(entries, LIST_READ_CONCURRENCY, (entry) =>
+        sink.get(entry.key)
+      );
+      const out: StorageEntry[] = [];
+      for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        const body = bodies[index];
+        if (entry === undefined || body === undefined) {
+          // Deleted between list and read; a miss is not corruption.
+          continue;
+        }
+        out.push({
+          key: entry.key,
+          value: decodeDocument(
+            entry.key,
+            body instanceof Uint8Array ? body : body.body
+          ),
+        });
+      }
+      return out;
+    },
+  };
+}
+
+function decodeDocument(key: string, bytes: Uint8Array): JsonValue {
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes)) as JsonValue;
+  } catch (error) {
+    throw new Error(
+      `framework file storage: stored document at "${key}" is not JSON (${
+        error instanceof Error ? error.message : String(error)
+      })`
+    );
+  }
+}
+
+/**
+ * Split one storage core by key kind: framework session state to `files`,
+ * everything else to `kv`. Spread over the KV backend when building the
+ * full definition so its `evals` / `abs` groups (and the cursor-hosted
+ * marker) ride along untouched; wrap the KV `cas` group with
+ * {@link frameworkGuardedCas} rather than spreading it as-is.
+ */
+export function composeFrameworkStorage(input: {
+  kv: FileSinkStorageCore;
+  files: FileSinkStorageCore;
+}): FileSinkStorageCore {
+  const route = (key: string): FileSinkStorageCore =>
+    isFrameworkFileKey(key) ? input.files : input.kv;
+  return {
+    put: (key, value, ctx) => route(key).put(key, value, ctx),
+    get: (key, ctx) => route(key).get(key, ctx),
+    delete: (key, ctx) => route(key).delete(key, ctx),
+    list: (prefix, ctx) => route(prefix).list(prefix, ctx),
+  };
+}
+
+/**
+ * The KV backend's conditional writes, refusing framework-file keys.
+ *
+ * CAS runs on the KV proxy (a database row version); the plain core routes
+ * framework session state to the file store. A future coordination path
+ * that CASes a `session/` or `continuation/` key would otherwise read and
+ * write a different store than the plain path — silent split-brain. Fail
+ * loudly instead; nothing in the package CASes those kinds today.
+ */
+export function frameworkGuardedCas(
+  cas: NonNullable<StorageConfig["cas"]>
+): NonNullable<StorageConfig["cas"]> {
+  const refuse = (key: string): void => {
+    if (isFrameworkFileKey(key)) {
+      throw new Error(
+        `framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`
+      );
+    }
+  };
+  return {
+    getWithVersion: (key, ctx) => {
+      refuse(key);
+      return cas.getWithVersion(key, ctx);
+    },
+    putIfAbsent: (key, value, ctx) => {
+      refuse(key);
+      return cas.putIfAbsent(key, value, ctx);
+    },
+    putIfVersion: (key, value, expectedVersion, ctx) => {
+      refuse(key);
+      return cas.putIfVersion(key, value, expectedVersion, ctx);
+    },
+    listKeys: (prefix, ctx) => {
+      refuse(prefix);
+      return cas.listKeys(prefix, ctx);
+    },
+  };
+}

package/src/internal/framework-storage-selection.ts

@@ -17,11 +17,17 @@
  *
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
- *   the Cursor-hosted backend, so session records, event chunks, `host.kv`,
- *   eval runs, and A/B samples land in the control plane and survive pod
- *   replacement. The API key resolves through the full credential chain on
- *   every call because hosted freeze snapshots listen unsigned and the
- *   binder drops the key file after restore.
+ *   the Cursor-hosted backend. When the deployment carries a
+ *   **framework-level file store**
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), session records, event
+ *   transcripts, and the continuation index live there — file-shaped state
+ *   on file storage, apart from the author-facing user store — while
+ *   `host.kv`, eval runs, A/B samples, and conditional writes stay on the
+ *   control-plane KV proxy (see framework-file-storage.ts). Without one
+ *   (a deploy predating framework-store provisioning), everything goes to
+ *   the KV proxy as before. The API key resolves through the full
+ *   credential chain on every call because hosted freeze snapshots listen
+ *   unsigned and the binder drops the key file after restore.
  * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
  *   is correct when the operator owns the disk.
  *
@@ -34,11 +40,20 @@
  * pod's filesystem.
  */
 
+import {
+  cursorFrameworkStoreSourceId,
+  cursorHostedFiles,
+} from "../files-backends/cursor-hosted.js";
 import { defineStorage, type StorageDefinition } from "../storage.js";
 import { cursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { AgentArchitecture } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import {
+  composeFrameworkStorage,
+  fileSinkStorageCore,
+  frameworkGuardedCas,
+} from "./framework-file-storage.js";
 
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
@@ -75,13 +90,38 @@ export function selectFrameworkStorageDefinition(
     // Self-hosted v2: the state root is the durable copy.
     return undefined;
   }
+  // Hosted v2 pods wake per delivery: bulk-restoring up to the default
+  // 1000 sessions on every boot is waste (and against the file-store
+  // backend it is per-key HTTP round trips before the listener even
+  // comes up). Follow-ups restore lazily by continuation or session id;
+  // GET /v1/sessions lists from the sink either way.
+  const policy = { restore: "off" } as const;
+  // Full chain (env → key file → stored login): frozen engines listen
+  // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
+  // definition is constructed.
+  const resolveApiKey = (): string | undefined => resolveApiKeySync()?.apiKey;
+  const kv = cursorHostedStorage({ resolveApiKey });
+  const frameworkStoreId = cursorFrameworkStoreSourceId(
+    env as NodeJS.ProcessEnv
+  );
+  if (frameworkStoreId === undefined) {
+    return defineStorage({ name: "cursor-hosted", policy, ...kv });
+  }
+  // Framework session state on the framework-level file store; author kv,
+  // evals, and A/B tables stay on the KV proxy (spread from `kv`, which
+  // also carries the cursor-hosted marker for GET /v1/sessions).
   return defineStorage({
-    name: "cursor-hosted",
-    ...cursorHostedStorage({
-      // Full chain (env → key file → stored login): frozen engines listen
-      // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
-      // definition is constructed.
-      apiKey: () => resolveApiKeySync()?.apiKey,
+    name: "cursor-hosted (framework files)",
+    policy,
+    ...kv,
+    ...composeFrameworkStorage({
+      kv,
+      files: fileSinkStorageCore(
+        cursorHostedFiles({ storeSourceId: frameworkStoreId, resolveApiKey })
+      ),
     }),
+    // CAS stays on the KV proxy but must refuse framework-file keys, or a
+    // future coordination path would split-brain against the plain core.
+    cas: frameworkGuardedCas(kv.cas),
   });
 }

package/src/internal/hosted-delivery.ts

@@ -245,6 +245,13 @@ export function registerHostedDeliveryRoute(input: {
     channelId: string,
     sessionPublicId?: string
   ): ChannelHandlerArgs;
+  /**
+   * Await the session's durable mirror (dispatch chain + storage queue)
+   * before the execution reply: the control plane may park the pod the
+   * moment the reply lands, and a shed session-record flush would strand
+   * the conversation on the next wake.
+   */
+  drainSessionDurability?(sessionId: string): Promise<void>;
 }): void {
   const pending = new Map<
     string,
@@ -387,6 +394,9 @@ export function registerHostedDeliveryRoute(input: {
           },
         });
         const outcome = await session.waitForCompletion();
+        // Failed turns drain too: their record/continuation updates must
+        // survive the park just like a finished turn's.
+        await input.drainSessionDurability?.(session.id);
         if (outcome.status !== "finished") {
           return {
             status: 503,

package/src/internal/init-project.ts

@@ -74,6 +74,7 @@ type TemplateEntry = {
 
 const TEMPLATES: Readonly<Record<TemplateName, TemplateEntry>> = {
   "agentic-owners": { dir: "agentic-owners" },
+  "code-wiki": { dir: "code-wiki" },
   demo: { dir: "demo" },
   "pr-autofixer": { dir: "pr-autofixer" },
   "security-help": { dir: "security-help" },
@@ -709,6 +710,7 @@ export function printInitGuide(): void {
 Scaffold a project, then open the playground:
   npx ${PACKAGE_NAME} init ./my-agent   # installs deps + links agent-sdk onto PATH
   npx ${PACKAGE_NAME} init ./my-demo --template demo              # record a PR walkthrough
+  npx ${PACKAGE_NAME} init ./code-wiki --template code-wiki       # keep wiki pages current after merge
   npx ${PACKAGE_NAME} init ./my-reviewer --template security-reviewer   # review PRs for security bugs
   npx ${PACKAGE_NAME} init ./security-help --template security-help   # answer security questions in Slack
   npx ${PACKAGE_NAME} init ./my-triage --template triage-linear   # comment on Linear issues

package/src/internal/install-cursor-skills.ts

@@ -31,9 +31,6 @@ import { CLI_COMMAND_NAME, packageRootDir } from "./distribution.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { stdoutPalette } from "./terminal-style.js";
 
-/** Monorepo-only skill; excluded from the published package. */
-const SKIP_SKILL_DIRS = new Set(["operate"]);
-
 /** Category folder under ~/.cursor/skills (Cursor discovers nested skills). */
 export const CURSOR_SKILLS_NAMESPACE = "agentsdk";
 
@@ -122,7 +119,7 @@ export async function listShippedPackageSkills(
 
   const skills: PackageSkill[] = [];
   for (const entry of entries) {
-    if (!entry.isDirectory() || SKIP_SKILL_DIRS.has(entry.name)) {
+    if (!entry.isDirectory()) {
       continue;
     }
     const sourceDir = join(skillsRoot, entry.name);