llm_workflow: high-level bundles for LLM sessions

New module omnimcode-core/src/llm_workflow.rs and 7 builtins giving
an LLM single-call access to common "I need a summary" operations:

  omc_cheatsheet(topic)         -> string  (markdown by category)
  omc_unique_overview()          -> string  (OMC-only surface)
  omc_python_translation()       -> string  (Python ↔ OMC table)
  omc_builtin_index_markdown()   -> string  (full index by category)
  omc_bootstrap_pack()           -> string  (~20KB session-start doc)
  omc_change_report(old, new)    -> dict    (diff + metrics + actions)
  omc_id(code)                   -> string  ("omcid-<fp>-<hash>")

The bootstrap_pack composes index + unique-overview + python-
translation + 4 cheatsheets (substrate / autograd / code_intel /
tokenizer). An LLM loads it once at session start and has enough
knowledge to write idiomatic OMC without further round-trips.

omc_id gives a stable string identifier for code regions —
"omcid-<substrate-fingerprint>-<canonical-hash>". Two alpha-
equivalent programs get the same id; the LLM's working-memory
key for "this is the same function I edited 10 messages ago".

Tests: 14 OMC + 6 Rust unit covering cheatsheet topics, unique
overview content, python-translation entries, index categories,
bootstrap-pack size, change-report dict keys + modification
detection, omc_id stability + format + change.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

OMC_REFERENCE.md

@@ -2,9 +2,9 @@
 
 Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFERENCE.md` to regenerate.
 
-**Total documented builtins**: 612
+**Total documented builtins**: 619
 
-**OMC-unique**: 61 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
+**OMC-unique**: 63 (no direct Python/NumPy equivalent — these are why you reach for OMC over numpy)
 
 ---
 
@@ -26,6 +26,7 @@ Auto-generated from `omnimcode-core/src/docs.rs`. Run `omc --gen-docs > OMC_REFE
 - [introspection](#introspection) (22 builtins)
 - [tokenizer](#tokenizer) (16 builtins)
 - [code_intel](#code_intel) (16 builtins)
+- [llm_workflow](#llm_workflow) (7 builtins)
 - [math](#math) (82 builtins)
 - [dicts](#dicts) (31 builtins)
 - [test_runner](#test_runner) (8 builtins)
@@ -4859,6 +4860,80 @@ omc_code_metrics(src)  // all stats at once
 
 ---
 
+## llm_workflow
+
+### `omc_cheatsheet`
+
+**Signature**: `(topic: string) -> string`
+
+Markdown cheatsheet for a category (substrate, autograd, tokenizer, ml_kernels, ...). Bundles ~10 builtins with examples.
+
+```omc
+omc_cheatsheet("substrate")  // markdown
+```
+
+### `omc_unique_overview` 🔱 *OMC-unique*
+
+**Signature**: `() -> string`
+
+Markdown list of every OMC-unique builtin, grouped by category.
+
+```omc
+omc_unique_overview()
+```
+
+### `omc_python_translation`
+
+**Signature**: `() -> string`
+
+Markdown table: Python op → OMC equivalent. Bootstrap reference.
+
+```omc
+omc_python_translation()
+```
+
+### `omc_builtin_index_markdown`
+
+**Signature**: `() -> string`
+
+Categorized Markdown index of all documented builtins.
+
+```omc
+omc_builtin_index_markdown()
+```
+
+### `omc_bootstrap_pack`
+
+**Signature**: `() -> string`
+
+Index + unique-overview + python-translation + 4 cheatsheets. Single ~20KB doc for session-start LLM bootstrapping.
+
+```omc
+omc_bootstrap_pack()
+```
+
+### `omc_change_report`
+
+**Signature**: `(old, new) -> dict`
+
+Diff + metrics + suggested next-actions in one dict.
+
+```omc
+omc_change_report(old, new)
+```
+
+### `omc_id` 🔱 *OMC-unique*
+
+**Signature**: `(code: string) -> string`
+
+Canonical OMC ID: 'omcid-<fp>-<short>'. Stable under cosmetic edits. Session-memory key for code.
+
+```omc
+omc_id(src)  // "omcid-12345-abcd"
+```
+
+---
+
 ## math
 
 ### `abs`

examples/tests/test_llm_workflow.omc

@@ -0,0 +1,98 @@
+# LLM workflow primitives.
+
+fn assert_eq(actual, expected, msg) {
+    if actual != expected {
+        test_record_failure(msg + ": expected " + to_string(expected) + " got " + to_string(actual));
+    }
+}
+
+fn assert_true(cond, msg) { if !cond { test_record_failure(msg); } }
+
+# Cheatsheets
+fn test_cheatsheet_substrate_has_entries() {
+    h s = omc_cheatsheet("substrate");
+    assert_true(str_len(s) > 100, "non-trivial cheatsheet");
+}
+
+fn test_cheatsheet_autograd() {
+    h s = omc_cheatsheet("autograd");
+    assert_true(str_len(s) > 100, "autograd cheatsheet non-empty");
+}
+
+fn test_cheatsheet_unknown_lists_topics() {
+    h s = omc_cheatsheet("nope_no_such_topic");
+    assert_true(re_match("Available topics", s) == 1, "lists topics on miss");
+}
+
+# Unique overview
+fn test_unique_overview_nonempty() {
+    h s = omc_unique_overview();
+    assert_true(str_len(s) > 100, "overview is substantive");
+}
+
+fn test_unique_overview_mentions_attractor() {
+    h s = omc_unique_overview();
+    assert_true(re_match("attractor", s) == 1, "mentions attractor");
+}
+
+# Python translation
+fn test_python_translation_mentions_arr_get() {
+    h s = omc_python_translation();
+    assert_true(re_match("arr_get", s) == 1, "has arr_get mapping");
+}
+
+fn test_python_translation_mentions_softmax() {
+    h s = omc_python_translation();
+    assert_true(re_match("softmax", s) == 1, "has softmax mapping");
+}
+
+# Builtin index
+fn test_builtin_index_lists_categories() {
+    h s = omc_builtin_index_markdown();
+    assert_true(re_match("## arrays", s) == 1, "has arrays section");
+    assert_true(re_match("## substrate", s) == 1, "has substrate section");
+}
+
+# Bootstrap pack — large composite
+fn test_bootstrap_pack_substantive() {
+    h s = omc_bootstrap_pack();
+    assert_true(str_len(s) > 5000, "bootstrap pack substantial");
+}
+
+# Change report
+fn test_change_report_keys() {
+    h r = omc_change_report(
+        "fn f(x) { return x; }",
+        "fn f(x) { return x + 1; } fn g() { return 0; }"
+    );
+    assert_true(dict_has(r, "added"), "has added");
+    assert_true(dict_has(r, "removed"), "has removed");
+    assert_true(dict_has(r, "modified"), "has modified");
+    assert_true(dict_has(r, "suggested_action"), "has suggested action");
+}
+
+fn test_change_report_detects_modification() {
+    h r = omc_change_report(
+        "fn f(x) { return x; }",
+        "fn f(x) { return x + 1; }"
+    );
+    assert_true(re_match("f", dict_get(r, "modified")) == 1, "f is in modified");
+}
+
+# omc_id stability
+fn test_omc_id_stable() {
+    h a = omc_id("fn f(x) { return x; }");
+    h b = omc_id("fn f(y) { return y; }");
+    assert_eq(a, b, "stable under alpha-rename");
+}
+
+fn test_omc_id_format() {
+    h a = omc_id("h x = 1;");
+    assert_true(re_match("^omcid-", a) == 1, "starts with omcid-");
+}
+
+fn test_omc_id_changes_on_real_diff() {
+    h a = omc_id("fn f(x) { return x; }");
+    h b = omc_id("fn f(x) { return x + 1; }");
+    assert_true(a != b, "different code → different id");
+}

omnimcode-core/src/docs.rs

@@ -1073,6 +1073,56 @@ pub const BUILTINS: &[BuiltinDoc] = &[
         example: "omc_code_metrics(src)  // all stats at once",
         unique_to_omc: false,
     },
+    // ---- LLM workflow bundles ----
+    BuiltinDoc {
+        name: "omc_cheatsheet", category: "llm_workflow",
+        signature: "(topic: string) -> string",
+        description: "Markdown cheatsheet for a category (substrate, autograd, tokenizer, ml_kernels, ...). Bundles ~10 builtins with examples.",
+        example: "omc_cheatsheet(\"substrate\")  // markdown",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_unique_overview", category: "llm_workflow",
+        signature: "() -> string",
+        description: "Markdown list of every OMC-unique builtin, grouped by category.",
+        example: "omc_unique_overview()",
+        unique_to_omc: true,
+    },
+    BuiltinDoc {
+        name: "omc_python_translation", category: "llm_workflow",
+        signature: "() -> string",
+        description: "Markdown table: Python op → OMC equivalent. Bootstrap reference.",
+        example: "omc_python_translation()",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_builtin_index_markdown", category: "llm_workflow",
+        signature: "() -> string",
+        description: "Categorized Markdown index of all documented builtins.",
+        example: "omc_builtin_index_markdown()",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_bootstrap_pack", category: "llm_workflow",
+        signature: "() -> string",
+        description: "Index + unique-overview + python-translation + 4 cheatsheets. Single ~20KB doc for session-start LLM bootstrapping.",
+        example: "omc_bootstrap_pack()",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_change_report", category: "llm_workflow",
+        signature: "(old, new) -> dict",
+        description: "Diff + metrics + suggested next-actions in one dict.",
+        example: "omc_change_report(old, new)",
+        unique_to_omc: false,
+    },
+    BuiltinDoc {
+        name: "omc_id", category: "llm_workflow",
+        signature: "(code: string) -> string",
+        description: "Canonical OMC ID: 'omcid-<fp>-<short>'. Stable under cosmetic edits. Session-memory key for code.",
+        example: "omc_id(src)  // \"omcid-12345-abcd\"",
+        unique_to_omc: true,
+    },
     // ---- Auto-generated docs for previously-undocumented builtins ----
     // Each entry covers one runtime builtin that lacked introspection.
     // Stubs are conservative — refine as you learn the actual signatures.

omnimcode-core/src/interpreter.rs

@@ -7705,6 +7705,52 @@ impl Interpreter {
                     .collect();
                 Ok(Value::Array(HArray::from_vec(out)))
             }
+            // ---- LLM workflow primitives (single-call bundles) ----
+            "omc_cheatsheet" => {
+                if args.is_empty() {
+                    return Err("omc_cheatsheet requires (topic: string)".to_string());
+                }
+                let topic = self.eval_expr(&args[0])?.to_display_string();
+                Ok(Value::String(crate::llm_workflow::cheatsheet(&topic)))
+            }
+            "omc_unique_overview" => {
+                Ok(Value::String(crate::llm_workflow::unique_overview()))
+            }
+            "omc_python_translation" => {
+                Ok(Value::String(crate::llm_workflow::python_translation()))
+            }
+            "omc_builtin_index_markdown" => {
+                Ok(Value::String(crate::llm_workflow::builtin_index_markdown()))
+            }
+            "omc_bootstrap_pack" => {
+                Ok(Value::String(crate::llm_workflow::bootstrap_pack()))
+            }
+            "omc_change_report" => {
+                if args.len() < 2 {
+                    return Err("omc_change_report requires (old, new)".to_string());
+                }
+                let a = self.eval_expr(&args[0])?.to_display_string();
+                let b = self.eval_expr(&args[1])?.to_display_string();
+                let r = crate::llm_workflow::change_report(&a, &b)
+                    .map_err(|e| format!("omc_change_report: {}", e))?;
+                let mut map = std::collections::BTreeMap::new();
+                for (k, v) in r {
+                    map.insert(k, Value::String(v));
+                }
+                Ok(Value::dict_from(map))
+            }
+            "omc_id" => {
+                // Canonical OMC ID: "omcid-<fp>-<short_hash>" — stable
+                // under cosmetic edits. The session-memory key for code.
+                if args.is_empty() {
+                    return Err("omc_id requires (code)".to_string());
+                }
+                let code = self.eval_expr(&args[0])?.to_display_string();
+                match crate::llm_workflow::omc_id(&code) {
+                    Ok(id) => Ok(Value::String(id)),
+                    Err(e) => Err(format!("omc_id: {}", e)),
+                }
+            }
             "omc_code_diff" => {
                 // Structural diff: returns {added, removed, modified, unchanged}.
                 // Compared after canonicalization so renames don't show.

omnimcode-core/src/lib.rs

@@ -10,6 +10,7 @@ pub mod errors;
 pub mod tokenizer;
 pub mod canonical;
 pub mod code_intel;
+pub mod llm_workflow;
 pub mod runtime;
 pub mod circuits;      // Genetic logic circuits
 pub mod evolution;     // Genetic operators