@hasna/instructions 0.7.0 → 0.7.2

package/README.md

@@ -52,9 +52,13 @@ existing row.
 
 ```bash
 instructions --help
-instructions list                    # compact, paged summary
-instructions list --verbose          # expanded metadata, still paged
-instructions list --json             # full machine-readable records
+instructions list                                      # compact, paged summary
+instructions list --verbose                            # expanded metadata, still paged
+instructions list --json                               # legacy complete full-record array
+instructions list --json --detail compact --limit 20   # bounded identity envelope
+instructions list --json --detail compact --fields id,slug,name,version
+instructions list --json --detail full --limit 20      # explicit bounded content read
+instructions list --json --detail compact --all        # explicit complete metadata read
 instructions show <slug>             # full metadata + content
 instructions inspect <slug>          # alias for show
 instructions profile resolve
@@ -68,7 +72,9 @@ small. Human output is capped at 20 rows unless you pass `--limit`; use
 `--cursor` to continue from the next page. Detail is explicit:
 
 - `--verbose` expands list rows with descriptions, tags, and paths.
-- `--json` preserves full machine-readable records for automation.
+- Legacy `--json` with no modern detail flags preserves the complete full-record array for automation. Explicit `--limit`/`--cursor` now bound that legacy array.
+- `--detail compact` returns a content-free `{ configs, _meta }` identity envelope through the already-deployed `/v1/configs?view=identity` projection. Add `--fields` (including immutable `id`), `--all`, or `--pretty` as needed.
+- `--detail full` is the explicit content-bearing envelope; it is bounded unless `--all` is supplied.
 - `show`/`inspect` and `snapshot show` print full config or snapshot content.
 
 `instructions report --json` emits the stable `schema_version: 1` report
@@ -77,6 +83,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
@@ -330,6 +354,14 @@ credentials may come from Bun's standard AWS chain (including an ECS task role);
 explicit static credentials are optional and must be a complete pair. Status
 never prints credential values or the bucket name.
 
+The production deployment runs the immutable predeploy backup push and verify
+as direct Bun commands in the exact candidate image. The GitHub runner alone
+parses the push receipt, then supplies the recorded payload and manifest version
+IDs to verification; it also checks the receipt digest and size, COMPLIANCE
+Object Lock retention for both versions, and an exact versioned-payload
+readback. Every backup gate completes before any ECR push, database migration,
+or ECS update.
+
 The public importable surface is available at `@hasna/instructions/storage`.
 
 ## Data Directory
@@ -347,13 +379,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
@@ -522,14 +561,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-7svah2qm.js → apply-ps6jjt6k.js}

@@ -8,10 +8,10 @@ import {
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-fwbs6tma.js";
-import"./index-4pfq42t5.js";
+} from "./index-ape24zc0.js";
+import"./index-pq18fdbj.js";
 import"./index-35z65jsa.js";
-import"./index-3djthcm6.js";
+import"./index-27az1qb1.js";
 import"./index-nnwp92tk.js";
 export {
   previewConfigs,

package/dist/chunks/{apply-jp13sa1e.js → apply-wj7wh5km.js}

@@ -8,9 +8,9 @@ import {
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-z3ma4aqk.js";
-import"./index-7m4j8a33.js";
-import"./index-n3fjspr0.js";
+} from "./index-y8410ve0.js";
+import"./index-n6nh6f5r.js";
+import"./index-preyvj8n.js";
 import"./index-fpeyzn3n.js";
 import"./index-bsan4c16.js";
 export {

package/dist/chunks/{index-1cnyjnd7.js → index-18j7x3xw.js}

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

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-fwbs6tma.js → index-ape24zc0.js}

@@ -15,7 +15,7 @@ import {
   resolveConfigStore,
   resolveProfileVariables,
   stampCursorGlobalAuthorityMarker
-} from "./index-4pfq42t5.js";
+} from "./index-pq18fdbj.js";
 import {
   isSecretVarName,
   redactFormatForTarget,
@@ -24,7 +24,7 @@ import {
 import {
   ConfigApplyError,
   parseTemplateVars
-} from "./index-3djthcm6.js";
+} from "./index-27az1qb1.js";
 
 // src/lib/apply.ts
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, realpathSync, writeFileSync } from "fs";

package/dist/chunks/{index-bzyxvwcd.js → index-ek15201v.js}

@@ -5,7 +5,7 @@ import {
   expandPath,
   getConfigHome,
   normalizeTargetPath
-} from "./index-fwbs6tma.js";
+} from "./index-ape24zc0.js";
 import {
   applyTransform,
   detectMachineContext,
@@ -13,7 +13,7 @@ import {
   resolveConfigStore,
   retiredOrUnsupportedAgentReason,
   templateizeMachineContent
-} from "./index-4pfq42t5.js";
+} from "./index-pq18fdbj.js";
 import {
   isSecretVarName,
   redactContent,

package/dist/chunks/{index-arrrx0ed.js → index-mvckkf15.js}

@@ -73,18 +73,20 @@ function createInstructionsS3ObjectStore(config, createClient = (options) => new
   return {
     async putIfAbsent(key, bytes, options) {
       assertSafeInstructionsObjectKey(key);
+      let credentials;
+      try {
+        credentials = resolveRequestCredentials(config);
+      } catch {
+        throw new Error("Instructions S3 conditional object creation failed");
+      }
       for (let attempt = 1;attempt <= CONDITIONAL_CREATE_ATTEMPTS; attempt += 1) {
         let response;
         const controller = new AbortController;
         try {
-          const url = client.presign(key, { method: "PUT", expiresIn: 60 });
-          response = await runWithDeadline(() => requestFetch(url, {
+          const signed = signConditionalCreateRequest(config, key, bytes, options.contentType, credentials, new Date);
+          response = await runWithDeadline(() => requestFetch(signed.url, {
             method: "PUT",
-            headers: {
-              "content-type": options.contentType,
-              "content-md5": createHash("md5").update(bytes).digest("base64"),
-              "if-none-match": "*"
-            },
+            headers: signed.headers,
             body: Uint8Array.from(bytes),
             redirect: "error",
             signal: controller.signal
@@ -220,7 +222,7 @@ function resolveRequestCredentials(config) {
   const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY?.trim();
   const sessionToken = process.env.AWS_SESSION_TOKEN?.trim();
   if (!accessKeyId || !secretAccessKey) {
-    throw new Error("Instructions S3 exact-version reads require explicit or AWS environment credentials");
+    throw new Error("Instructions S3 signed requests require explicit or AWS environment credentials");
   }
   return { accessKeyId, secretAccessKey, ...sessionToken ? { sessionToken } : {} };
 }
@@ -235,25 +237,43 @@ function signVersionedRequest(config, key, versionId, method, credentials, now)
     "x-amz-date": amzDate,
     ...credentials.sessionToken ? { "x-amz-security-token": credentials.sessionToken } : {}
   });
-  const signedHeaderNames = [
-    "host",
-    "x-amz-content-sha256",
-    "x-amz-date",
-    ...credentials.sessionToken ? ["x-amz-security-token"] : []
-  ].sort();
-  const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${headers.get(name).trim()}
-`).join("");
   const canonicalQuery = `versionId=${awsEncode(versionId)}`;
+  authorizeRequest(method, url, canonicalQuery, headers, EMPTY_SHA256, credentials, config.region, shortDate, amzDate);
+  return { url: url.toString(), headers };
+}
+function signConditionalCreateRequest(config, key, bytes, contentType, credentials, now) {
+  const url = buildObjectUrl(config, key);
+  const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+  const shortDate = amzDate.slice(0, 8);
+  const payloadHash = createHash("sha256").update(bytes).digest("hex");
+  const headers = new Headers({
+    "content-md5": createHash("md5").update(bytes).digest("base64"),
+    "content-type": contentType,
+    host: url.host,
+    "if-none-match": "*",
+    "x-amz-content-sha256": payloadHash,
+    "x-amz-date": amzDate,
+    ...credentials.sessionToken ? { "x-amz-security-token": credentials.sessionToken } : {}
+  });
+  authorizeRequest("PUT", url, "", headers, payloadHash, credentials, config.region, shortDate, amzDate);
+  return { url: url.toString(), headers };
+}
+function authorizeRequest(method, url, canonicalQuery, headers, payloadHash, credentials, region, shortDate, amzDate) {
+  const signedHeaderNames = [];
+  headers.forEach((_value, name) => signedHeaderNames.push(name));
+  signedHeaderNames.sort();
+  const canonicalHeaders = signedHeaderNames.map((name) => `${name}:${headers.get(name).trim().replace(/\s+/g, " ")}
+`).join("");
   const canonicalRequest = [
     method,
     url.pathname,
     canonicalQuery,
     canonicalHeaders,
     signedHeaderNames.join(";"),
-    EMPTY_SHA256
+    payloadHash
   ].join(`
 `);
-  const scope = `${shortDate}/${config.region}/s3/aws4_request`;
+  const scope = `${shortDate}/${region}/s3/aws4_request`;
   const stringToSign = [
     "AWS4-HMAC-SHA256",
     amzDate,
@@ -262,12 +282,11 @@ function signVersionedRequest(config, key, versionId, method, credentials, now)
   ].join(`
 `);
   const dateKey = hmac(`AWS4${credentials.secretAccessKey}`, shortDate);
-  const regionKey = hmac(dateKey, config.region);
+  const regionKey = hmac(dateKey, region);
   const serviceKey = hmac(regionKey, "s3");
   const signingKey = hmac(serviceKey, "aws4_request");
   const signature = createHmac("sha256", signingKey).update(stringToSign).digest("hex");
   headers.set("authorization", `AWS4-HMAC-SHA256 Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaderNames.join(";")}, Signature=${signature}`);
-  return { url: url.toString(), headers };
 }
 function buildObjectUrl(config, key) {
   const encodedKey = key.split("/").map(awsEncode).join("/");