@hasna/instructions 0.7.1 → 0.7.4

package/README.md

@@ -67,6 +67,19 @@ instructions package-manager-scan --fail-on-findings .
 instructions package-manager-scan --home --fail-on-findings .
 ```
 
+Skills are managed through the Skills CLI. Profile application and bootstrap do
+not inspect, install or repair native Inbox skill payloads, and do not send
+Conversations heartbeats. Their legacy `--from` and `--delivery-verified` flags
+remain accepted for compatibility but perform no verification.
+
+`instructions managed-skills status` and `instructions managed-skills apply`
+are deprecated, read-only migration reports. They return a failure when legacy
+Inbox paths remain and preserve those paths, including symlinks. Use the Skills
+CLI to review `skills migrate native`, then sync and load the selected skills.
+An empty legacy inventory does not verify hosted skill selection or runtime
+delivery. The exported inspection/reconciliation helpers behave the same way;
+an explicit legacy `assetPath` no longer enables native payload writes.
+
 Collection commands are compact by default to keep agent terminals and context
 small. Human output is capped at 20 rows unless you pass `--limit`; use
 `--cursor` to continue from the next page. Detail is explicit:
@@ -83,6 +96,24 @@ envelope. Its top-level fields are `configs`, `profiles`, `drift`, `secrets`,
 `secrets.policy` is `redacted_on_ingest`. Run `instructions report` without
 `--json` for the human-readable report.
 
+### Conditional config updates
+
+Read the current config version before preparing an edit, then pass that
+`expected_version` to `updateConfig` (store/public SDK), `update_config` (MCP), or:
+
+```bash
+instructions add ./rule.md --kind reference --name example-rule --update --expected-version 7
+```
+
+Guarded clients use `POST /v1/configs/:id/conditional-update`, which requires
+`expected_version`. The generated SDK also exposes `conditionalUpdateConfig` for
+this operation. An older server returns 404 without mutation; clients never fall
+back to an unconditional update. A version mismatch returns HTTP 409 with code
+`CONFIG_VERSION_CONFLICT`, changing neither the config nor its snapshots. Refresh
+and review the newer version before trying again. Calls without a precondition
+retain their existing behavior. New servers also accept `expected_version` on
+PATCH/PUT; use the dedicated conditional route when server capabilities are unknown.
+
 ## Package-Manager Secret Guard
 
 `instructions package-manager-scan` blocks package-manager credential ingress without
@@ -361,13 +392,20 @@ upgrade.
 
 `instructions session plan` and `instructions session apply` render
 OpenIdentities and instruction sources into provider-native files for Claude,
-Codex, Cursor, OpenCode, Codewith, Qwen, aicopilot, and Google Antigravity.
+Codex, Cursor, OpenCode, Sumi, Codewith, Qwen, aicopilot, and Google Antigravity.
 The old Google agent target is removed; Antigravity is the only Google coding
 agent render target. Antigravity workspace rules are rendered to
 `.agents/rules/*.md`; its current global rules and MCP files use Google's
 legacy-named `~/.gemini/GEMINI.md` and `~/.gemini/config/mcp_config.json`
 paths but remain owned by the `antigravity` target.
 
+Sumi renders one flattened `AGENTS.md`. Pass its actual config directory from
+`sumi debug paths config` as `--target-home`, or use `--project-root` for
+repository instructions. Global plans return `SUMI_CONFIG_DIR`; project plans
+do not change the global config environment. No OpenCode config or fragment
+imports are written. See [session rendering](docs/session-rendering.md) for
+capability limits and examples.
+
 Qwen Code session rendering writes `QWEN.md` instructional context with
 `QWEN_HOME` pointing at the rendered profile home. Known config sync also
 tracks Qwen Code `QWEN.md` and `settings.json` files at `~/.qwen/...` and
@@ -536,14 +574,16 @@ and prior on-box-only evidence must be explicitly reconciled before use.
 
 ## Machine-aware Profiles
 
-`instructions init` seeds two platform profiles:
+`instructions init` seeds two empty platform profiles:
 
-- `linux-arm64` for `linux-node-a` / `linux-node-b`
-- `macos-arm64` for `macos-node-a` / `macos-node-b`
+- `linux-arm64` for Linux arm64
+- `macos-arm64` for macOS arm64
 
-These profiles resolve machine variables like `{{WORKSPACE_ROOT}}`,
-`{{BUN_BIN_DIR}}`, `{{BUN_PATH}}`, and `{{PATH_PREFIX}}`, so synced configs can be
-portable across Linux and macOS arm64 machines.
+The public presets contain no fleet hostnames or workspace paths. They resolve
+portable tool variables such as `{{BUN_BIN_DIR}}`, `{{BUN_PATH}}`, and
+`{{PATH_PREFIX}}`. Instruction membership is never bulk-copied from the config
+registry; bind reviewed provider/project/role sources explicitly before compiling
+a prompt profile.
 
 They also include the project channel variable used by agent-managed project
 workflows:

package/dist/chunks/{apply-c3sd4agz.js → apply-1gyr8r0x.js}

@@ -8,10 +8,10 @@ import {
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-ypcef3a2.js";
-import"./index-aj66f6xr.js";
+} from "./index-n9arv47w.js";
+import"./index-dwagz53p.js";
 import"./index-35z65jsa.js";
-import"./index-3djthcm6.js";
+import"./index-27az1qb1.js";
 import"./index-nnwp92tk.js";
 export {
   previewConfigs,

package/dist/chunks/{apply-pnn7a3y7.js → apply-fyfzqc7s.js}

@@ -8,9 +8,9 @@ import {
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-r7nfef2g.js";
-import"./index-6jncnnw7.js";
-import"./index-n3fjspr0.js";
+} from "./index-6sbmg1vc.js";
+import"./index-enh4yv85.js";
+import"./index-preyvj8n.js";
 import"./index-fpeyzn3n.js";
 import"./index-bsan4c16.js";
 export {

package/dist/chunks/{index-3djthcm6.js → index-27az1qb1.js}

@@ -4,6 +4,7 @@ var CONFIG_AGENTS = [
   "claude",
   "codex",
   "opencode",
+  "sumi",
   "cursor",
   "codewith",
   "aicopilot",
@@ -28,6 +29,32 @@ var ASSET_DESTINATION_STRATEGIES = ["emit-file", "install-local", "install-marke
 var ASSET_SCOPES = ["global", "project", "session"];
 var ASSET_UNINSTALL_POLICIES = ["remove-managed", "retain"];
 var ASSET_ROLLBACK_POLICIES = ["snapshot", "installer-receipt", "none"];
+class InvalidExpectedVersionError extends Error {
+  code = "INVALID_EXPECTED_VERSION";
+  constructor() {
+    super("expected_version must be a positive safe integer");
+    this.name = "InvalidExpectedVersionError";
+  }
+}
+function validateExpectedConfigVersion(value) {
+  if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)) {
+    throw new InvalidExpectedVersionError;
+  }
+}
+
+class ConfigVersionConflictError extends Error {
+  config_id;
+  expected_version;
+  code = "CONFIG_VERSION_CONFLICT";
+  status = 409;
+  constructor(config_id, expected_version) {
+    super(`Config version conflict: ${config_id} no longer has expected version ${expected_version}`);
+    this.config_id = config_id;
+    this.expected_version = expected_version;
+    this.name = "ConfigVersionConflictError";
+  }
+}
+
 class ConfigNotFoundError extends Error {
   constructor(id) {
     super(`Config not found: ${id}`);
@@ -114,4 +141,4 @@ function isTemplate(content) {
   return VAR_PATTERN.test(content);
 }
 
-export { CONFIG_AGENTS, PROFILE_CONFIG_BINDING_SCHEMA, INSTRUCTION_ACTIVATION_MODES, INSTRUCTION_FALLBACKS, PROFILE_ASSET_BINDING_SCHEMA, ASSET_KINDS, ASSET_DESTINATION_STRATEGIES, ASSET_SCOPES, ASSET_UNINSTALL_POLICIES, ASSET_ROLLBACK_POLICIES, ConfigNotFoundError, ProfileNotFoundError, ConfigApplyError, parseTemplateVars, extractTemplateVars, renderTemplate, renderTemplatePreview, isTemplate };
+export { CONFIG_AGENTS, PROFILE_CONFIG_BINDING_SCHEMA, INSTRUCTION_ACTIVATION_MODES, INSTRUCTION_FALLBACKS, PROFILE_ASSET_BINDING_SCHEMA, ASSET_KINDS, ASSET_DESTINATION_STRATEGIES, ASSET_SCOPES, ASSET_UNINSTALL_POLICIES, ASSET_ROLLBACK_POLICIES, validateExpectedConfigVersion, ConfigVersionConflictError, ConfigNotFoundError, ProfileNotFoundError, ConfigApplyError, parseTemplateVars, extractTemplateVars, renderTemplate, renderTemplatePreview, isTemplate };

package/dist/chunks/{index-r7nfef2g.js → index-6sbmg1vc.js}

@@ -18,11 +18,11 @@ import {
   resolveProfileVariables,
   scanSecrets,
   stampCursorGlobalAuthorityMarker
-} from "./index-6jncnnw7.js";
+} from "./index-enh4yv85.js";
 import {
   ConfigApplyError,
   parseTemplateVars
-} from "./index-n3fjspr0.js";
+} from "./index-preyvj8n.js";
 
 // src/lib/apply.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync, writeFileSync } from "fs";
@@ -529,4 +529,4 @@ function sessionRendererOwnsCanonicalTarget(normalized, opts) {
   return sessionRenderOwnsPath(normalized);
 }
 
-export { getConfigHome, expandPath, compactPathForConfigHome, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };
+export { sessionRenderOwnsPath, getConfigHome, expandPath, compactPathForConfigHome, normalizeTargetPath, applyConfig, applyConfigs, applyConfigsWithReport, previewConfigs };

package/dist/chunks/{index-pdpg8a44.js → index-axs3yftz.js}

@@ -5,7 +5,7 @@ import {
   expandPath,
   getConfigHome,
   normalizeTargetPath
-} from "./index-r7nfef2g.js";
+} from "./index-6sbmg1vc.js";
 import {
   applyTransform,
   detectMachineContext,
@@ -16,7 +16,7 @@ import {
   resolveConfigStore,
   retiredOrUnsupportedAgentReason,
   templateizeMachineContent
-} from "./index-6jncnnw7.js";
+} from "./index-enh4yv85.js";
 
 // src/lib/sync.ts
 import { existsSync as existsSync2, readdirSync as readdirSync2, readFileSync as readFileSync2 } from "fs";

package/dist/chunks/{index-aj66f6xr.js → index-dwagz53p.js}

@@ -14,8 +14,9 @@ import {
   ProfileNotFoundError,
   isTemplate,
   renderTemplate,
-  renderTemplatePreview
-} from "./index-3djthcm6.js";
+  renderTemplatePreview,
+  validateExpectedConfigVersion
+} from "./index-27az1qb1.js";
 import {
   __export,
   __require
@@ -114,6 +115,9 @@ function buildCodexAgentsMd(source, context = {}) {
 function buildOpenCodeAgentsMd(source, context = {}) {
   return flattenWithRules(source, context);
 }
+function buildSumiAgentsMd(source, context = {}) {
+  return flattenWithRules(source, context);
+}
 function buildCursorMdc(source) {
   const stem = source.target_path ? basename(source.target_path, extname(source.target_path)) : source.slug;
   const description = source.name || stem;
@@ -142,6 +146,8 @@ function applyTransform(source, output, context = {}) {
       return buildCodexAgentsMd(source, context);
     case "opencode-flat":
       return buildOpenCodeAgentsMd(source, context);
+    case "sumi-flat":
+      return buildSumiAgentsMd(source, context);
     case "cursor-mdc":
       return buildCursorMdc(source);
     case "skill-neutral":
@@ -367,6 +373,7 @@ function assetCapability(provider, surface, kind, support, strategies, note, pro
 var ASSET_CAPABILITY_DESCRIPTORS = Object.freeze([
   assetCapability("claude", "code", "skill", "supported", ["emit-file"], "Claude Code project or profile skill files."),
   assetCapability("claude", "code", "workflow", "supported", ["emit-file"], "Claude Code command and workflow files."),
+  assetCapability("claude", "code", "custom-agent", "supported", ["emit-file"], "Claude Code Markdown subagents with native frontmatter in agents/.", ">=2.1.276 <3.0.0"),
   assetCapability("claude", "code", "hook", "supported", ["emit-file"], "Claude Code hook configuration fragments."),
   assetCapability("claude", "code", "plugin", "conditional", ["install-marketplace"], "Claude marketplace installation requires an explicit installer."),
   assetCapability("codex", "cli", "skill", "supported", ["emit-file"], "Codex skill bundle files."),
@@ -377,6 +384,7 @@ var ASSET_CAPABILITY_DESCRIPTORS = Object.freeze([
   assetCapability("opencode", "cli", "workflow", "supported", ["emit-file"], "OpenCode command/workflow files."),
   assetCapability("opencode", "cli", "plugin", "supported", ["emit-file"], "OpenCode local plugin modules."),
   assetCapability("opencode", "cli", "custom-agent", "supported", ["emit-file"], "OpenCode custom agent files."),
+  assetCapability("sumi", "cli", "custom-agent", "supported", ["emit-file"], "Sumi Markdown agent definitions in its explicit resolved config or project directory.", ">=0.2.22 <0.3.0"),
   assetCapability("codewith", "cli", "skill", "supported", ["emit-file"], "Codewith skill bundle files."),
   assetCapability("codewith", "cli", "plugin", "conditional", ["install-local", "install-marketplace"], "Codewith plugin installation requires an explicit installer."),
   assetCapability("aicopilot", "cli", "skill", "supported", ["emit-file"], "AICopilot discovered skill files."),
@@ -409,6 +417,7 @@ var DEFAULT_ASSET_SURFACES = Object.freeze({
   codex: "cli",
   cursor: "ide",
   opencode: "cli",
+  sumi: "cli",
   codewith: "cli",
   qwen: "cli",
   aicopilot: "cli",
@@ -458,6 +467,10 @@ function normalizeProfileAssetBinding(value) {
   const rollback = record["rollback"];
   if (!ASSET_ROLLBACK_POLICIES.includes(rollback))
     throw new Error(`Invalid asset rollback policy: ${String(rollback)}`);
+  const nativeAgent = record["nativeAgent"] === undefined ? undefined : normalizeNativeAgentMetadata(record["nativeAgent"]);
+  if (nativeAgent && (kind !== "custom-agent" || strategy !== "emit-file" || !["claude", "sumi", "opencode"].includes(provider))) {
+    throw new Error("nativeAgent metadata requires a supported emitted custom-agent definition.");
+  }
   return {
     schema: PROFILE_ASSET_BINDING_SCHEMA,
     assetKey,
@@ -477,10 +490,65 @@ function normalizeProfileAssetBinding(value) {
       root,
       relativePath: nonEmptyString(destinationRecord["relativePath"], "destination.relativePath")
     },
+    ...nativeAgent ? { nativeAgent } : {},
     uninstall,
     rollback
   };
 }
+function normalizeNativeAgentMetadata(value) {
+  const record = objectRecord(value, "nativeAgent");
+  if (Object.keys(record).some((key) => !["name", "description", "frontmatter"].includes(key)))
+    throw new Error("Unknown nativeAgent metadata field.");
+  const name = nonEmptyString(record["name"], "nativeAgent.name");
+  const description = nonEmptyString(record["description"], "nativeAgent.description");
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name) || name.length > 128)
+    throw new Error("Invalid nativeAgent.name.");
+  if (description.length > 4096 || /[\r\n\0]/.test(description))
+    throw new Error("Invalid nativeAgent.description.");
+  if (record["frontmatter"] === undefined)
+    return { name, description };
+  const frontmatter = record["frontmatter"];
+  if (typeof frontmatter !== "string" || frontmatter.length > 16384 || frontmatter.includes("\x00"))
+    throw new Error("Invalid nativeAgent.frontmatter.");
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n$/.exec(frontmatter);
+  if (!match)
+    throw new Error("nativeAgent.frontmatter requires one complete newline-terminated YAML header.");
+  const scalar = (raw) => {
+    if (raw.startsWith('"')) {
+      try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "string" ? parsed : undefined;
+      } catch {
+        return;
+      }
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9 _.,:;()/?@+-]*$/.test(raw) || /:(?:\s|$)/.test(raw))
+      return;
+    if (/^(?:true|yes|on|y)$/i.test(raw))
+      return true;
+    if (/^(?:false|no|off|n)$/i.test(raw))
+      return false;
+    if (/^null$/i.test(raw))
+      return null;
+    if (/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(raw))
+      return Number(raw);
+    if (/^[0-9]/.test(raw))
+      return;
+    return raw;
+  };
+  const fields = new Map;
+  for (const line of match[1].split(/\r?\n/)) {
+    if (!line.trim() || line.startsWith("#"))
+      continue;
+    const field = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]+(.+)$/.exec(line);
+    if (!field || fields.has(field[1]) || scalar(field[2]) === undefined)
+      throw new Error("nativeAgent.frontmatter requires unambiguous, unique flat scalar fields.");
+    fields.set(field[1], scalar(field[2]));
+  }
+  if (fields.get("name") !== name || fields.get("description") !== description)
+    throw new Error("nativeAgent.frontmatter name and description must match explicit metadata.");
+  return { name, description, frontmatter };
+}
 function parseJson(value) {
   try {
     return JSON.parse(value);
@@ -534,6 +602,7 @@ var DEFAULT_PROVIDER_CAPABILITIES = Object.freeze({
   codex: capability("codex", ">=0.1.0", "flattened", "AGENTS.md", { asset_surface: "cli" }),
   cursor: capability("cursor", ">=1.0.0", "cursor-rule", ".cursor/rules/*.mdc", { activation_modes: ["always", "glob"], conditional_artifacts: true, asset_surface: "ide" }),
   opencode: capability("opencode", ">=1.0.0", "managed-fragment", "opencode.json instructions", { provider_variant: "v1-instructions", session_surface: "opencode-config-instructions" }),
+  sumi: capability("sumi", ">=0.2.22 <0.3.0", "flattened", "AGENTS.md"),
   codewith: capability("codewith", ">=0.1.0", "flattened", "CODEWITH.md"),
   qwen: capability("qwen", ">=0.1.0", "flattened", "QWEN.md"),
   aicopilot: capability("aicopilot", ">=0.1.0", "flattened", "AICOPILOT.md"),
@@ -2115,7 +2184,7 @@ function isNotFoundHttpError2(err) {
 var localStoreModulePromise = null;
 function localStoreModule() {
   if (!localStoreModulePromise)
-    localStoreModulePromise = import("./local-0a9gja58.js");
+    localStoreModulePromise = import("./local-5dsm856v.js");
   return localStoreModulePromise;
 }
 
@@ -2396,7 +2465,9 @@ class CloudConfigStore {
     return data.config;
   }
   async updateConfig(idOrSlug, input) {
-    const { data } = await this.request("PATCH", `/configs/${encodeURIComponent(idOrSlug)}`, input);
+    validateExpectedConfigVersion(input.expected_version);
+    const conditional = input.expected_version !== undefined;
+    const { data } = await this.request(conditional ? "POST" : "PATCH", `/configs/${encodeURIComponent(idOrSlug)}${conditional ? "/conditional-update" : ""}`, input);
     return data.config;
   }
   async deleteConfig(idOrSlug) {
@@ -2473,7 +2544,7 @@ class CloudConfigStore {
       throw new ProfileNotFoundError(idOrSlug);
     return parseBoundedOrLegacyPage(data.configs, data.profile.configs, normalized, "profile membership");
   }
-  async getProfileConfigBindings(idOrSlug) {
+  async getProfileConfigBindings(idOrSlug, options = {}) {
     let routeMissing = false;
     const bindings = await aggregateBoundedCollection("profile config bindings", async (cursor) => {
       const normalized = normalizeBoundedReadOptions({ limit: 100, cursor });
@@ -2486,6 +2557,8 @@ class CloudConfigStore {
     }, (binding) => `${binding.profile_id}\x00${binding.config_id}`);
     if (!routeMissing)
       return bindings;
+    if (options.requireExplicit)
+      throw new Error("HOSTED_BINDINGS_REQUIRED: profile config binding route is unavailable; refusing legacy activation fallback.");
     const profile = await this.getProfile(idOrSlug);
     const configs = await this.getProfileConfigs(idOrSlug);
     return configs.map((config, sort_order) => ({
@@ -2550,7 +2623,7 @@ class CloudConfigStore {
   async removeConfigFromProfile(profileIdOrSlug, configId) {
     await this.request("DELETE", `/profiles/${encodeURIComponent(profileIdOrSlug)}/configs/${encodeURIComponent(configId)}`, undefined, { allow404: true });
   }
-  async getProfileAssetBindings(profileIdOrSlug) {
+  async getProfileAssetBindings(profileIdOrSlug, options = {}) {
     let routeMissing = false;
     const assets = await aggregateBoundedCollection("profile asset bindings", async (cursor) => {
       const normalized = normalizeBoundedReadOptions({ limit: 100, cursor });
@@ -2563,6 +2636,8 @@ class CloudConfigStore {
     }, (asset) => `${asset.profile_id}\x00${asset.binding.assetKey}`);
     if (!routeMissing)
       return assets;
+    if (options.requireExplicit)
+      throw new Error("HOSTED_ASSETS_REQUIRED: profile asset binding route is unavailable; refusing an empty asset fallback.");
     await this.getProfile(profileIdOrSlug);
     return [];
   }
@@ -7199,6 +7274,15 @@ var SESSION_TOOL_ADAPTERS = {
     description: "OpenCode AGENTS.md plus opencode.json instructions pointing at managed fragments.",
     providerSurface: "legacy-dual"
   },
+  sumi: {
+    tool: "sumi",
+    mode: "flattened-markdown",
+    indexFile: "AGENTS.md",
+    managedDir: SESSION_RENDER_INSTRUCTIONS_MANAGED_DIR,
+    envVar: "SUMI_CONFIG_DIR",
+    nativeImports: false,
+    description: "Sumi native AGENTS.md in the explicit resolved config directory or project root."
+  },
   aicopilot: {
     tool: "aicopilot",
     mode: "flattened-markdown",
@@ -7321,7 +7405,7 @@ function detectMachineContext(overrides = {}) {
     created_at: "",
     os_family: osFamily,
     home_dir: homeDir4,
-    workspace_root: overrides.workspace_root ?? join5(homeDir4, osFamily === "macos" ? "Workspace" : "workspace"),
+    workspace_root: overrides.workspace_root ?? "",
     bun_bin_dir: bunBinDir,
     bun_path: overrides.bun_path ?? defaultBunPath,
     path_prefix: overrides.path_prefix ?? (osFamily === "macos" ? `${join5("/opt", "homebrew", "bin")}:${bunBinDir}` : bunBinDir)
@@ -7334,7 +7418,7 @@ function machineContextToVariables(machine) {
     OS_FAMILY: machine.os_family,
     ARCH: machine.arch ?? "",
     HOME_DIR: machine.home_dir,
-    WORKSPACE_ROOT: machine.workspace_root,
+    ...machine.workspace_root ? { WORKSPACE_ROOT: machine.workspace_root } : {},
     BUN_BIN_DIR: machine.bun_bin_dir,
     BUN_PATH: machine.bun_path,
     PATH_PREFIX: machine.path_prefix