@agentxm/client-core 0.5.3 → 0.6.2

package/dist/src/unstable/settings/schema.js

@@ -25,22 +25,28 @@ const SourceNameSchema = Schema.String.check(Schema.isPattern(SOURCE_NAME_PATTER
 })).annotate({
     identifier: "SourceName",
     title: "Source Name",
-    description: "A source name using lowercase letters, numbers, hyphens, and dots (e.g. github, my-registry.dev).",
+    description: "A source host alias: lowercase letters, numbers, hyphens, and dots.",
     examples: ["github", "my-registry.dev"],
 });
+const sourceNameFieldSchema = SourceNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "source name is required" }), Schema.annotate({
+    description: "Alias used in entry source strings for this source host.",
+}));
+const sourceUrlFieldSchema = Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source url is required" }), Schema.annotate({
+    description: "Base URL for this source host endpoint.",
+}));
 /**
  * GitHub source host configuration.
  *
  * @experimental This API is unstable and may change without notice.
  */
 const GitHubSourceHostConfigSchema = Schema.Struct({
-    name: SourceNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "source name is required" })),
+    name: sourceNameFieldSchema,
     type: Schema.Literal("github"),
-    url: Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source url is required" })),
+    url: sourceUrlFieldSchema,
 }).annotate({
     identifier: "GitHubSourceHostConfig",
     title: "GitHub Source Host",
-    description: "Configuration for a GitHub source.",
+    description: "A GitHub source host.",
 });
 /**
  * GitLab source host configuration.
@@ -48,13 +54,13 @@ const GitHubSourceHostConfigSchema = Schema.Struct({
  * @experimental This API is unstable and may change without notice.
  */
 const GitLabSourceHostConfigSchema = Schema.Struct({
-    name: SourceNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "source name is required" })),
+    name: sourceNameFieldSchema,
     type: Schema.Literal("gitlab"),
-    url: Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source url is required" })),
+    url: sourceUrlFieldSchema,
 }).annotate({
     identifier: "GitLabSourceHostConfig",
     title: "GitLab Source Host",
-    description: "Configuration for a GitLab source.",
+    description: "A GitLab source host.",
 });
 /**
  * Bitbucket source host configuration.
@@ -62,13 +68,13 @@ const GitLabSourceHostConfigSchema = Schema.Struct({
  * @experimental This API is unstable and may change without notice.
  */
 const BitbucketSourceHostConfigSchema = Schema.Struct({
-    name: SourceNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "source name is required" })),
+    name: sourceNameFieldSchema,
     type: Schema.Literal("bitbucket"),
-    url: Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source url is required" })),
+    url: sourceUrlFieldSchema,
 }).annotate({
     identifier: "BitbucketSourceHostConfig",
     title: "Bitbucket Source Host",
-    description: "Configuration for a Bitbucket source.",
+    description: "A Bitbucket source host.",
 });
 /**
  * Azure Repos source host configuration.
@@ -76,13 +82,13 @@ const BitbucketSourceHostConfigSchema = Schema.Struct({
  * @experimental This API is unstable and may change without notice.
  */
 const AzureReposSourceHostConfigSchema = Schema.Struct({
-    name: SourceNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "source name is required" })),
+    name: sourceNameFieldSchema,
     type: Schema.Literal("azurerepos"),
-    url: Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source url is required" })),
+    url: sourceUrlFieldSchema,
 }).annotate({
     identifier: "AzureReposSourceHostConfig",
     title: "Azure Repos Source Host",
-    description: "Configuration for an Azure Repos source.",
+    description: "An Azure Repos source host.",
 });
 /**
  * Registry source host configuration.
@@ -90,13 +96,15 @@ const AzureReposSourceHostConfigSchema = Schema.Struct({
  * @experimental This API is unstable and may change without notice.
  */
 const RegistrySourceHostConfigSchema = Schema.Struct({
-    name: SourceNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "source name is required" })),
+    name: sourceNameFieldSchema,
     type: Schema.Literal("registry"),
-    location: Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source location is required" })),
+    location: Schema.URLFromString.pipe(Schema.annotateKey({ messageMissingKey: "source location is required" }), Schema.annotate({
+        description: "Registry endpoint for this source; accepts http(s)://, file://, or local paths.",
+    })),
 }).annotate({
     identifier: "RegistrySourceHostConfig",
     title: "Registry Source Host",
-    description: "Configuration for a package registry source.",
+    description: "A package registry source host.",
 });
 /**
  * Discriminated union of source host configurations on the `type` field.
@@ -114,33 +122,57 @@ export const SourceHostConfigSchema = Schema.Union([
 ]).annotate({
     identifier: "SourceHostConfig",
     title: "Source Host Config",
-    description: "Where extensions are fetched from — GitHub, GitLab, Bitbucket, Azure Repos, or a package registry.",
+    description: "A source host configuration: GitHub, GitLab, Bitbucket, Azure Repos, or a package registry.",
 });
 const ExtensionMapKeySchema = Schema.String.check(Schema.isPattern(EXTENSION_NAME_PATTERN, {
     message: "Names must be max 64 chars, lowercase letters/numbers/hyphens, not starting or ending with hyphen.",
 }));
-const authoredFieldSchema = Schema.optional(Schema.Boolean.annotate({
-    description: "Whether this entry was authored locally. Defaults to false when omitted.",
+const authoredFieldSchema = Schema.optionalKey(Schema.Boolean.annotate({
+    description: "Set to true to mark this entry as authored locally in this workspace. Omit otherwise — false is the default and should not be written explicitly.",
     default: false,
 }));
-const enabledFieldSchema = Schema.optional(Schema.Boolean.annotate({
-    description: "Whether this entry is enabled. Defaults to true when omitted.",
+const enabledFieldSchema = Schema.optionalKey(Schema.Boolean.annotate({
+    description: "Set to false to disable this entry. Omit otherwise — true is the default and should not be written explicitly.",
     default: true,
 }));
-const compactOrVerboseEntry = (objectSchema, canonicalSchema, transformation) => Schema.Union([Schema.String, objectSchema]).pipe(Schema.decodeTo(canonicalSchema, SchemaTransformation.transform(transformation)));
+const entrySourceFieldSchema = (label, fqnType) => Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: `${label} source is required` }), Schema.annotate({
+    description: "FQN with optional version constraint, source-scheme ref like github:owner/repo, or local path.",
+    examples: [
+        `@acme/${fqnType}/code-review@^1.0.0`,
+        "github:acme/agent-extensions",
+        "./extensions/code-review",
+    ],
+}));
+const telemetryModeExamples = [true, "errors", false];
+/**
+ * Telemetry preference for this workspace.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const TelemetryModeSchema = Schema.Union([
+    Schema.Boolean,
+    Schema.Literal("errors"),
+]).annotate({
+    identifier: "TelemetryMode",
+    title: "Telemetry Mode",
+    description: '`true` sends usage and error telemetry, `"errors"` sends only errors, and `false` disables telemetry.',
+    examples: telemetryModeExamples,
+});
+const compactOrVerboseEntry = (objectSchema, canonicalSchema, transformation, annotations) => Schema.Union([Schema.String, objectSchema])
+    .annotate(annotations)
+    .pipe(Schema.decodeTo(canonicalSchema, SchemaTransformation.transform(transformation)));
 /**
  * Managed skill with source and optional config flags.
  *
  * @experimental This API is unstable and may change without notice.
  */
 export const SkillEntryObjectSchema = Schema.Struct({
-    source: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "skill source is required" })),
+    source: entrySourceFieldSchema("skill", "skills"),
     enabled: enabledFieldSchema,
     authored: authoredFieldSchema,
 }).annotate({
-    identifier: "SkillEntryObject",
     title: "Skill Entry Object",
-    description: "A skill with its source location and whether it's enabled.",
+    description: "A skill entry with source and optional enabled/authored flags.",
 });
 /**
  * Union of skill entry forms: plain source string or object with source + enabled + authored.
@@ -157,10 +189,6 @@ export const SkillEntrySchema = compactOrVerboseEntry(SkillEntryObjectSchema, Sc
     source: Schema.String,
     enabled: Schema.Boolean,
     authored: Schema.Boolean,
-}).annotate({
-    identifier: "SkillEntry",
-    title: "Skill Entry",
-    description: "A skill reference — either a source string like @owner/skills/name or an object with source, enabled, and authored.",
 }), {
     decode: (entry) => typeof entry === "string"
         ? { source: entry, enabled: true, authored: false }
@@ -181,6 +209,14 @@ export const SkillEntrySchema = compactOrVerboseEntry(SkillEntryObjectSchema, Sc
             obj.authored = true;
         return obj;
     },
+}, {
+    identifier: "SkillEntry",
+    title: "Skill Entry",
+    description: "A skill entry: a source string, or an object with source plus optional flags.",
+    examples: [
+        "@acme/skills/code-review@^1.0.0",
+        { source: "github:acme/agent-extensions", enabled: false },
+    ],
 });
 /**
  * Skills map - maps skill names to skill entries.
@@ -197,7 +233,7 @@ export const SkillEntrySchema = compactOrVerboseEntry(SkillEntryObjectSchema, Sc
 export const SkillsMapSchema = Schema.Record(ExtensionMapKeySchema, SkillEntrySchema).annotate({
     identifier: "SkillsMap",
     title: "Skills Map",
-    description: "Your installed skills, keyed by name.",
+    description: "A map of skill names to skill entries.",
 });
 /**
  * Managed command with source and optional config flags.
@@ -205,13 +241,12 @@ export const SkillsMapSchema = Schema.Record(ExtensionMapKeySchema, SkillEntrySc
  * @experimental This API is unstable and may change without notice.
  */
 export const CommandEntryObjectSchema = Schema.Struct({
-    source: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "command source is required" })),
+    source: entrySourceFieldSchema("command", "commands"),
     enabled: enabledFieldSchema,
     authored: authoredFieldSchema,
 }).annotate({
-    identifier: "CommandEntryObject",
     title: "Command Entry Object",
-    description: "A command with its source location and whether it's enabled.",
+    description: "A command entry with source and optional enabled/authored flags.",
 });
 /**
  * Union of command entry forms: plain source string or object with source + enabled + authored.
@@ -226,10 +261,6 @@ export const CommandEntrySchema = compactOrVerboseEntry(CommandEntryObjectSchema
     source: Schema.String,
     enabled: Schema.Boolean,
     authored: Schema.Boolean,
-}).annotate({
-    identifier: "CommandEntry",
-    title: "Command Entry",
-    description: "A command reference — either a source string like @owner/commands/name or an object with source, enabled, and authored.",
 }), {
     decode: (entry) => typeof entry === "string"
         ? { source: entry, enabled: true, authored: false }
@@ -250,6 +281,14 @@ export const CommandEntrySchema = compactOrVerboseEntry(CommandEntryObjectSchema
             obj.authored = true;
         return obj;
     },
+}, {
+    identifier: "CommandEntry",
+    title: "Command Entry",
+    description: "A command entry: a source string, or an object with source plus optional flags.",
+    examples: [
+        "@acme/commands/code-review@^1.0.0",
+        { source: "github:acme/agent-extensions", enabled: false },
+    ],
 });
 /**
  * Commands map - maps command names to command entries.
@@ -266,7 +305,7 @@ export const CommandEntrySchema = compactOrVerboseEntry(CommandEntryObjectSchema
 export const CommandsMapSchema = Schema.Record(ExtensionMapKeySchema, CommandEntrySchema).annotate({
     identifier: "CommandsMap",
     title: "Commands Map",
-    description: "Your installed commands, keyed by name.",
+    description: "A map of command names to command entries.",
 });
 /**
  * MCP server entry object with source.
@@ -274,12 +313,11 @@ export const CommandsMapSchema = Schema.Record(ExtensionMapKeySchema, CommandEnt
  * @experimental This API is unstable and may change without notice.
  */
 export const McpServerEntryObjectSchema = Schema.Struct({
-    source: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "MCP server source is required" })),
+    source: entrySourceFieldSchema("MCP server", "mcp-servers"),
     authored: authoredFieldSchema,
 }).annotate({
-    identifier: "McpServerEntryObject",
     title: "MCP Server Entry Object",
-    description: "An MCP server with its source location.",
+    description: "An MCP server entry with source and optional authored flag.",
 });
 /**
  * Union of MCP server entry forms: plain source string or object with source + authored.
@@ -292,15 +330,19 @@ export const McpServerEntryObjectSchema = Schema.Struct({
 export const McpServerEntrySchema = compactOrVerboseEntry(McpServerEntryObjectSchema, Schema.Struct({
     source: Schema.String,
     authored: Schema.Boolean,
-}).annotate({
-    identifier: "McpServerEntry",
-    title: "MCP Server Entry",
-    description: "An MCP server reference — either a source string or an object with source and authored.",
 }), {
     decode: (entry) => typeof entry === "string"
         ? { source: entry, authored: false }
         : { source: entry.source, authored: entry.authored ?? false },
     encode: (entry) => entry.authored ? { source: entry.source, authored: true } : entry.source,
+}, {
+    identifier: "McpServerEntry",
+    title: "MCP Server Entry",
+    description: "An MCP server entry: a source string, or an object with source plus optional authored flag.",
+    examples: [
+        "@acme/mcp-servers/context@^1.0.0",
+        { source: "github:acme/agent-extensions", authored: true },
+    ],
 });
 /**
  * MCP servers map - maps MCP server names to MCP server entries.
@@ -312,7 +354,7 @@ export const McpServerEntrySchema = compactOrVerboseEntry(McpServerEntryObjectSc
 export const McpServersMapSchema = Schema.Record(ExtensionMapKeySchema, McpServerEntrySchema).annotate({
     identifier: "McpServersMap",
     title: "MCP Servers Map",
-    description: "Your installed MCP servers, keyed by name.",
+    description: "A map of MCP server names to MCP server entries.",
 });
 // -----------------------------------------------------------------------------
 // Subagent Entry Schemas
@@ -323,13 +365,12 @@ export const McpServersMapSchema = Schema.Record(ExtensionMapKeySchema, McpServe
  * @experimental This API is unstable and may change without notice.
  */
 export const SubagentEntryObjectSchema = Schema.Struct({
-    source: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "subagent source is required" })),
+    source: entrySourceFieldSchema("subagent", "subagents"),
     enabled: enabledFieldSchema,
     authored: authoredFieldSchema,
 }).annotate({
-    identifier: "SubagentEntryObject",
     title: "Subagent Entry Object",
-    description: "A subagent with its source location and whether it's enabled.",
+    description: "A subagent entry with source and optional enabled/authored flags.",
 });
 /**
  * Union of subagent entry forms: plain source string or object with source + enabled + authored.
@@ -344,10 +385,6 @@ export const SubagentEntrySchema = compactOrVerboseEntry(SubagentEntryObjectSche
     source: Schema.String,
     enabled: Schema.Boolean,
     authored: Schema.Boolean,
-}).annotate({
-    identifier: "SubagentEntry",
-    title: "Subagent Entry",
-    description: "A subagent reference — either a source string like @owner/subagents/name or an object with source, enabled, and authored.",
 }), {
     decode: (entry) => typeof entry === "string"
         ? { source: entry, enabled: true, authored: false }
@@ -368,6 +405,14 @@ export const SubagentEntrySchema = compactOrVerboseEntry(SubagentEntryObjectSche
             obj.authored = true;
         return obj;
     },
+}, {
+    identifier: "SubagentEntry",
+    title: "Subagent Entry",
+    description: "A subagent entry: a source string, or an object with source plus optional flags.",
+    examples: [
+        "@acme/subagents/reviewer@^1.0.0",
+        { source: "github:acme/agent-extensions", enabled: false },
+    ],
 });
 /**
  * Subagents map - maps subagent names to subagent entries.
@@ -384,7 +429,7 @@ export const SubagentEntrySchema = compactOrVerboseEntry(SubagentEntryObjectSche
 export const SubagentsMapSchema = Schema.Record(ExtensionMapKeySchema, SubagentEntrySchema).annotate({
     identifier: "SubagentsMap",
     title: "Subagents Map",
-    description: "Your installed subagents, keyed by name.",
+    description: "A map of subagent names to subagent entries.",
 });
 // -----------------------------------------------------------------------------
 // Pack Entry Schemas
@@ -395,12 +440,11 @@ export const SubagentsMapSchema = Schema.Record(ExtensionMapKeySchema, SubagentE
  * @experimental This API is unstable and may change without notice.
  */
 export const PackEntryObjectSchema = Schema.Struct({
-    source: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "pack source is required" })),
+    source: entrySourceFieldSchema("pack", "packs"),
     authored: authoredFieldSchema,
 }).annotate({
-    identifier: "PackEntryObject",
     title: "Pack Entry Object",
-    description: "A pack with its source location.",
+    description: "A pack entry with source and optional authored flag.",
 });
 /**
  * Union of pack entry forms: plain source string or object with source + authored.
@@ -413,15 +457,19 @@ export const PackEntryObjectSchema = Schema.Struct({
 export const PackEntrySchema = compactOrVerboseEntry(PackEntryObjectSchema, Schema.Struct({
     source: Schema.String,
     authored: Schema.Boolean,
-}).annotate({
-    identifier: "PackEntry",
-    title: "Pack Entry",
-    description: "A pack reference — either a source string or an object with source and authored.",
 }), {
     decode: (entry) => typeof entry === "string"
         ? { source: entry, authored: false }
         : { source: entry.source, authored: entry.authored ?? false },
     encode: (entry) => entry.authored ? { source: entry.source, authored: true } : entry.source,
+}, {
+    identifier: "PackEntry",
+    title: "Pack Entry",
+    description: "A pack entry: a source string, or an object with source plus optional authored flag.",
+    examples: [
+        "@acme/packs/typescript@^1.0.0",
+        { source: "github:acme/agent-extensions", authored: true },
+    ],
 });
 /**
  * Packs map - maps pack names to pack entries.
@@ -438,27 +486,85 @@ export const PackEntrySchema = compactOrVerboseEntry(PackEntryObjectSchema, Sche
 export const PacksMapSchema = Schema.Record(ExtensionMapKeySchema, PackEntrySchema).annotate({
     identifier: "PacksMap",
     title: "Packs Map",
-    description: "Your installed packs, keyed by name.",
+    description: "A map of pack names to pack entries.",
 });
 // -----------------------------------------------------------------------------
-// Ignored Patterns Schema
+// Feature Config Schemas
 // -----------------------------------------------------------------------------
 /**
- * Ignored patterns map — per-extension-type arrays of glob patterns
- * for extensions to exclude from lifecycle classification.
+ * Feature-level configuration for skills.
  *
  * @experimental This API is unstable and may change without notice.
  */
-export const IgnoredSettingsSchema = Schema.Struct({
-    skills: Schema.optional(Schema.Array(Schema.String)),
-    commands: Schema.optional(Schema.Array(Schema.String)),
-    subagents: Schema.optional(Schema.Array(Schema.String)),
-    mcpServers: Schema.optional(Schema.Array(Schema.String)),
-    packs: Schema.optional(Schema.Array(Schema.String)),
+export const SkillsConfigSchema = Schema.Struct({
+    ignore: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+        description: "Installed skill names AXM should leave unmanaged.",
+        examples: [["local-*", "legacy-helper"]],
+    })),
 }).annotate({
-    identifier: "IgnoredSettings",
-    title: "Ignored Settings",
-    description: "Glob patterns for extensions to ignore, grouped by type (e.g. skills, commands).",
+    identifier: "SkillsConfig",
+    title: "Skills Config",
+    description: "Feature-level configuration for skills.",
+});
+/**
+ * Feature-level configuration for commands.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const CommandsConfigSchema = Schema.Struct({
+    ignore: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+        description: "Installed command names AXM should leave unmanaged.",
+        examples: [["local-*", "legacy-helper"]],
+    })),
+}).annotate({
+    identifier: "CommandsConfig",
+    title: "Commands Config",
+    description: "Feature-level configuration for commands.",
+});
+/**
+ * Feature-level configuration for subagents.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const SubagentsConfigSchema = Schema.Struct({
+    ignore: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+        description: "Installed subagent names AXM should leave unmanaged.",
+        examples: [["local-*", "legacy-helper"]],
+    })),
+}).annotate({
+    identifier: "SubagentsConfig",
+    title: "Subagents Config",
+    description: "Feature-level configuration for subagents.",
+});
+/**
+ * Feature-level configuration for MCP servers.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const McpServersConfigSchema = Schema.Struct({
+    ignore: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+        description: "Installed MCP server names AXM should leave unmanaged.",
+        examples: [["local-*", "legacy-helper"]],
+    })),
+}).annotate({
+    identifier: "McpServersConfig",
+    title: "MCP Servers Config",
+    description: "Feature-level configuration for MCP servers.",
+});
+/**
+ * Feature-level configuration for packs.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const PacksConfigSchema = Schema.Struct({
+    ignore: Schema.optionalKey(Schema.Array(Schema.String).annotate({
+        description: "Installed pack names AXM should leave unmanaged.",
+        examples: [["local-*", "legacy-helper"]],
+    })),
+}).annotate({
+    identifier: "PacksConfig",
+    title: "Packs Config",
+    description: "Feature-level configuration for packs.",
 });
 /**
  * Canonical key order for settings properties.
@@ -474,11 +580,15 @@ export const SETTINGS_KEY_ORDER = [
     "sources",
     "agents",
     "skills",
+    "skillsConfig",
     "commands",
+    "commandsConfig",
     "subagents",
+    "subagentsConfig",
     "packs",
+    "packsConfig",
     "mcpServers",
-    "ignored",
+    "mcpServersConfig",
     "lint",
 ];
 /**
@@ -489,27 +599,96 @@ export const SETTINGS_KEY_ORDER = [
  * - sources: Source provider configurations
  * - agents: List of agent IDs to sync extensions to
  * - skills: Desired skills by name to source string
+ * - skillsConfig: Feature-level configuration for skills
  * - commands: Desired commands by name to version specifier
+ * - commandsConfig: Feature-level configuration for commands
+ * - subagents: Desired subagents by name to version specifier
+ * - subagentsConfig: Feature-level configuration for subagents
  * - packs: Desired packs by name to version specifier
- * - mcp-servers: Desired MCP servers by name to version specifier
+ * - packsConfig: Feature-level configuration for packs
+ * - mcpServers: Desired MCP servers by name to version specifier
+ * - mcpServersConfig: Feature-level configuration for MCP servers
  *
  * @experimental This API is unstable and may change without notice.
  */
 export const SettingsSchema = Schema.Struct({
-    telemetry: Schema.optional(Schema.Union([Schema.Boolean, Schema.Literal("errors")])),
-    owner: Schema.optional(HandleSchema),
-    agents: Schema.optional(Schema.Array(AgentIdSchema)),
-    sources: Schema.optional(Schema.Array(SourceHostConfigSchema)),
-    commands: Schema.optional(CommandsMapSchema),
-    subagents: Schema.optional(SubagentsMapSchema),
-    mcpServers: Schema.optional(McpServersMapSchema),
-    packs: Schema.optional(PacksMapSchema),
-    skills: Schema.optional(SkillsMapSchema),
-    ignored: Schema.optional(IgnoredSettingsSchema),
-    lint: Schema.optional(LintConfigSchema),
+    telemetry: Schema.optionalKey(Schema.Union([TelemetryModeSchema]).annotate({
+        description: "Workspace telemetry mode: full, errors-only, or disabled.",
+    })),
+    owner: Schema.optionalKey(Schema.Union([HandleSchema]).annotate({
+        description: "Default owner handle used when AXM scaffolds or resolves workspace extensions.",
+    })),
+    agents: Schema.optionalKey(Schema.Array(AgentIdSchema)
+        .annotate({
+        description: "Coding agents AXM should sync managed extensions into.",
+        examples: [["claude-code", "codex"]],
+    })
+        .check(Schema.isUnique())),
+    sources: Schema.optionalKey(Schema.Array(SourceHostConfigSchema).annotate({
+        description: "Named source hosts used to resolve source-scheme entry references.",
+    })),
+    skills: Schema.optionalKey(Schema.Union([SkillsMapSchema]).annotate({
+        description: "Your installed skills, keyed by workspace skill name. Prefer plain source strings; use the object form only to set `enabled: false` or `authored: true`, and never write `enabled: true` or `authored: false` explicitly.",
+    })),
+    skillsConfig: Schema.optionalKey(Schema.Union([SkillsConfigSchema]).annotate({
+        description: "Feature-level options for skill management.",
+    })),
+    commands: Schema.optionalKey(Schema.Union([CommandsMapSchema]).annotate({
+        description: "Your installed commands, keyed by workspace command name. Prefer plain source strings; use the object form only to set `enabled: false` or `authored: true`, and never write `enabled: true` or `authored: false` explicitly.",
+    })),
+    commandsConfig: Schema.optionalKey(Schema.Union([CommandsConfigSchema]).annotate({
+        description: "Feature-level options for command management.",
+    })),
+    subagents: Schema.optionalKey(Schema.Union([SubagentsMapSchema]).annotate({
+        description: "Your installed subagents, keyed by workspace subagent name. Prefer plain source strings; use the object form only to set `enabled: false` or `authored: true`, and never write `enabled: true` or `authored: false` explicitly.",
+    })),
+    subagentsConfig: Schema.optionalKey(Schema.Union([SubagentsConfigSchema]).annotate({
+        description: "Feature-level options for subagent management.",
+    })),
+    packs: Schema.optionalKey(Schema.Union([PacksMapSchema]).annotate({
+        description: "Your installed packs, keyed by workspace pack name. Prefer plain source strings; use the object form only to set `authored: true`, and never write `authored: false` explicitly. Pack entries do not support `enabled` yet.",
+    })),
+    packsConfig: Schema.optionalKey(Schema.Union([PacksConfigSchema]).annotate({
+        description: "Feature-level options for pack management.",
+    })),
+    mcpServers: Schema.optionalKey(Schema.Union([McpServersMapSchema]).annotate({
+        description: "Your installed MCP servers, keyed by workspace MCP server name. Prefer plain source strings; use the object form only to set `authored: true`, and never write `authored: false` explicitly. MCP server entries do not support `enabled` yet.",
+    })),
+    mcpServersConfig: Schema.optionalKey(Schema.Union([McpServersConfigSchema]).annotate({
+        description: "Feature-level options for MCP server management.",
+    })),
+    lint: Schema.optionalKey(Schema.Union([LintConfigSchema]).annotate({
+        description: "Lint configuration for `axm lint` in this workspace.",
+    })),
 }).annotate({
-    identifier: "Settings",
+    identifier: "AxmSettings",
     title: "AXM Settings",
-    description: "Your workspace configuration — owner, sources, installed extensions, and ignore patterns.",
+    description: "Your workspace configuration — owner, sources, installed extensions, feature config, and lint config.",
+    // Examples are emitted verbatim into the generated JSON Schema. We declare
+    // them in the encoded (compact) form so agents see the preferred shape:
+    // plain source strings, with the object form reserved for non-default flags.
+    // Assertion needed: `.annotate()` types examples against the decoded
+    // canonical shape (where `enabled`/`authored` are required booleans), but
+    // emitting that shape would teach agents to write the very defaults we want
+    // them to omit.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    examples: [
+        {
+            telemetry: "errors",
+            agents: ["claude-code", "codex"],
+            skills: {
+                "code-review": "@acme/skills/code-review@^1.0.0",
+                "legacy-rules": { source: "@acme/skills/legacy-rules@^1.0.0", enabled: false },
+            },
+            skillsConfig: {
+                ignore: ["local-*"],
+            },
+            lint: {
+                rules: {
+                    "workspace/settings-schema-valid": "error",
+                },
+            },
+        },
+    ],
 });
 //# sourceMappingURL=schema.js.map