docs: clarify code SDK option contracts

Author: claude

sdk/node/generated.d.ts

@@ -409,7 +409,13 @@ export interface AutoDelegationOptions {
 export interface SessionOptions {
   /** Override the default model. Format: "provider/model" (e.g., "openai/gpt-4o"). */
   model?: string
-  /** Enable built-in skills (4 skills: code-search, code-review, explain-code, find-bugs). */
+  /**
+   * Compatibility flag for the built-in skill registry.
+   *
+   * Built-ins are already present in the default effective registry; `true`
+   * requests an explicit built-in registry, while `false` does not remove
+   * default built-ins.
+   */
   builtinSkills?: boolean
   /** Extra directories to scan for skill files (.md with YAML frontmatter). */
   skillDirs?: Array<string>
@@ -1264,8 +1270,9 @@ export declare class Agent {
    * @param dir - Path to the agent directory (prompt/skills/schedules/tools)
    * @param workspace - Workspace directory each scheduled turn operates in
    * @param options - Optional session overrides merged into every schedule session
-   *   (model, llmClient, sessionStore, …); `promptSlots`/`sessionId` set here are
-   *   NOT overridden so a host can pin them per schedule
+   *   (model, llmClient, sessionStore, …). `promptSlots` is honored when
+   *   provided; otherwise the AgentDir `instructions.md` slot is used.
+   *   `sessionId` is always owned by the daemon and set to `schedule:<name>`.
    */
   serveAgentDir(dir: string, workspace: string, options?: SessionOptions | undefined | null): Promise<ServeHandle>
 }

sdk/node/src/lib.rs

@@ -1779,7 +1779,11 @@ pub struct AutoDelegationOptions {
 pub struct SessionOptions {
     /// Override the default model. Format: "provider/model" (e.g., "openai/gpt-4o").
     pub model: Option<String>,
-    /// Enable built-in skills (4 skills: code-search, code-review, explain-code, find-bugs).
+    /// Compatibility flag for the built-in skill registry.
+    ///
+    /// Built-ins are already present in the default effective registry; `true`
+    /// requests an explicit built-in registry, while `false` does not remove
+    /// default built-ins.
     pub builtin_skills: Option<bool>,
     /// Extra directories to scan for skill files (.md with YAML frontmatter).
     pub skill_dirs: Option<Vec<String>>,
@@ -3033,8 +3037,9 @@ impl Agent {
     /// @param dir - Path to the agent directory (prompt/skills/schedules/tools)
     /// @param workspace - Workspace directory each scheduled turn operates in
     /// @param options - Optional session overrides merged into every schedule session
-    ///   (model, llmClient, sessionStore, …); `promptSlots`/`sessionId` set here are
-    ///   NOT overridden so a host can pin them per schedule
+    ///   (model, llmClient, sessionStore, …). `promptSlots` is honored when
+    ///   provided; otherwise the AgentDir `instructions.md` slot is used.
+    ///   `sessionId` is always owned by the daemon and set to `schedule:<name>`.
     #[napi]
     pub async fn serve_agent_dir(
         &self,

sdk/python/src/lib.rs

@@ -1146,7 +1146,8 @@ impl PyAgent {
     ///     workspace: Path to the workspace directory
     ///     options: Optional SessionOptions object
     ///     model: Optional model override, format "provider/model" (e.g., "openai/gpt-4o")
-    ///     builtin_skills: Optional bool to enable built-in skills (default: False)
+    ///     builtin_skills: Compatibility bool for the built-in skill registry.
+    ///         Built-ins are present by default; False does not remove them.
     ///     skill_dirs: Optional list of directories to scan for skill files
     ///     agent_dirs: Optional list of directories to scan for agent files
     ///     queue_config: Optional advanced SessionQueueConfig for explicit external/hybrid lane dispatch
@@ -5093,7 +5094,10 @@ impl PySessionOptions {
         self.model = value;
     }
 
-    /// Enable built-in skills.
+    /// Compatibility flag for the built-in skill registry.
+    ///
+    /// Built-ins are present by default. Setting this to False does not remove
+    /// them from the effective registry.
     #[getter]
     fn get_builtin_skills(&self) -> bool {
         self.builtin_skills