docs: add NJS-GROWTH-05 comparison guides

Author: SebaSOFT

README.md

@@ -23,6 +23,7 @@ Use it when hardcoded `if/else` logic is too rigid, but a heavyweight workflow o
 - Examples: [`examples/`](examples/) with pricing, eligibility, and workflow-routing scenarios
 - Schemas and validation docs: [`docs/schemas-validation-explainability.md`](docs/schemas-validation-explainability.md)
 - AI-readable docs: [`docs/ai-coding-assistants.md`](docs/ai-coding-assistants.md), [`docs/public/llms.txt`](docs/public/llms.txt), and the official [`neuron-js` AI skill](docs/public/skills/neuron-js/SKILL.md)
+- Comparison and migration guides: [`docs/comparisons/`](docs/comparisons/) for json-rules-engine, JsonLogic, node-rules, and if/else migrations
 
 ---
 
@@ -158,12 +159,9 @@ Available adoption assets:
 
 - Runnable examples: [`examples/`](examples/)
 - JSON Schemas, validation, and explain output: [`docs/schemas-validation-explainability.md`](docs/schemas-validation-explainability.md)
+- Comparison and migration guides: [`docs/comparisons/`](docs/comparisons/) for choosing and migrating from json-rules-engine, JsonLogic, node-rules, and hand-written if/else
 - AI-readable docs: [`docs/ai-coding-assistants.md`](docs/ai-coding-assistants.md), [`docs/public/llms.txt`](docs/public/llms.txt), [`docs/public/llms-full.txt`](docs/public/llms-full.txt), and [`docs/public/skills/neuron-js/SKILL.md`](docs/public/skills/neuron-js/SKILL.md)
 
-Planned next adoption assets:
-
-- Comparison and migration pages: `NJS-GROWTH-05`
-
 ---
 
 ## 🛠 Development

content-drafts/njs-growth-05/neuron-js-vs-json-rules-engine.md

@@ -0,0 +1,182 @@
+# Drafting fields
+
+Title: Neuron-JS vs json-rules-engine: choosing the right JSON rules engine
+
+Alias: neuron-js-vs-json-rules-engine
+
+Description: A practical migration guide for teams comparing Neuron-JS with json-rules-engine, focused on TypeScript ownership, validation, explainability, and deterministic JSON business rules.
+
+Tags: neuron-js, typescript, rules-engine, json-rules-engine, migration, business-rules, ai-agents
+
+# Markdown body
+
+## The short version
+
+`json-rules-engine` is the established Node.js default for JSON rules. It is mature, recognizable, and built around facts, conditions, events, and rule priorities.
+
+Neuron-JS takes a narrower position: **JSON business rules for TypeScript systems that need validation before runtime and explanation after execution**.
+
+That difference matters when business rules become product infrastructure instead of a helper library.
+
+Use `json-rules-engine` when your system already thinks in facts and events, and the existing ecosystem fit is more important than a built-in validation and explanation contract.
+
+Use Neuron-JS when the rule layer must be:
+
+- stored as JSON,
+- generated or edited outside deployment cycles,
+- validated before runtime,
+- executed through an approved TypeScript registry,
+- explained for support, audit, or tests.
+
+## What each tool is optimized for
+
+`json-rules-engine` gives teams a known model:
+
+- facts describe the current world,
+- conditions decide whether something matches,
+- events describe what happened,
+- priorities help control rule order.
+
+That is a good model. If your business logic already lives there and works, migration is not automatically valuable.
+
+Neuron-JS is optimized for a different pressure point: **safe dynamic logic in TypeScript applications**.
+
+The core model is:
+
+- `Neuron` owns the approved rule vocabulary,
+- `Synapse` executes a serializable script,
+- schemas validate generated or stored JSON,
+- output summaries and explanation traces make the decision reviewable.
+
+That makes it useful when rules become a governance problem, not only an execution problem.
+
+## When Neuron-JS is the better fit
+
+Choose Neuron-JS when you need a tighter contract around JSON business rules.
+
+Good signs:
+
+- AI agents generate candidate rules and you need to reject malformed scripts before execution.
+- Product or operations teams need rule changes without a code deployment.
+- The application must keep a constrained vocabulary of approved conditions and actions.
+- Support needs to answer “why did this decision happen?” with a trace, not a guess.
+- Backend and browser code need the same deterministic rule definition.
+
+The point is not to be more abstract. The point is to make dynamic logic safer.
+
+## When json-rules-engine is the better fit
+
+Keep or choose `json-rules-engine` when:
+
+- facts, events, and priorities match your mental model,
+- your current rule assets are stable,
+- the team values ecosystem familiarity over a different contract,
+- validation and explanation can remain project-owned,
+- migration would add risk without real operational gain.
+
+A migration that does not improve safety, clarity, or operating speed is not engineering. It is churn.
+
+## Migration pattern
+
+Do not translate keywords mechanically. Translate the decision.
+
+A `json-rules-engine` rule often looks like this:
+
+```json
+{
+  "conditions": {
+    "all": [
+      { "fact": "customerTier", "operator": "equal", "value": "gold" },
+      { "fact": "cartTotal", "operator": "greaterThanInclusive", "value": 100 }
+    ]
+  },
+  "event": {
+    "type": "apply-discount",
+    "params": { "percent": 15 }
+  }
+}
+```
+
+In Neuron-JS, the same business decision becomes a script with explicit rule, condition, parameter, and action types:
+
+```json
+{
+  "id": "gold-customer-discount",
+  "rules": [
+    {
+      "id": "gold-order-over-threshold",
+      "type": "simple_rule",
+      "options": {},
+      "conditions": [
+        {
+          "id": "cart-total-threshold",
+          "type": "compare_two_numbers",
+          "options": {},
+          "params": [
+            { "id": "cart-total", "name": "op1", "type": "simple_number", "value": "125", "options": {} },
+            { "id": "comparison", "name": "comp", "type": "comparator", "value": ">=", "options": {} },
+            { "id": "threshold", "name": "op2", "type": "simple_number", "value": "100", "options": {} }
+          ]
+        }
+      ],
+      "actions": [
+        {
+          "id": "discount-score",
+          "type": "add_two_numbers",
+          "options": {},
+          "params": [
+            { "id": "base-discount", "name": "op1", "type": "simple_number", "value": "10", "options": {} },
+            { "id": "tier-bonus", "name": "op2", "type": "simple_number", "value": "5", "options": {} }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Then validate and explain it:
+
+```typescript
+import {
+  Neuron,
+  Synapse,
+  explainExecution,
+  summarizeExecutionOutput,
+  validateExecutionContext,
+  validateScript,
+} from '@sebasoft/neuron-js';
+
+const context = { messages: [], state: { customerTier: 'gold', cartTotal: 125 } };
+
+const scriptValidation = validateScript(script);
+const contextValidation = validateExecutionContext(context);
+
+if (!scriptValidation.ok || !contextValidation.ok) {
+  throw new Error('Invalid migrated rule input');
+}
+
+const result = new Synapse(new Neuron()).execute(script, context);
+const output = summarizeExecutionOutput(result);
+const explanation = explainExecution({ script, result });
+```
+
+## Migration checklist
+
+- Map each fact to a parameter or context field.
+- Map each operator to an approved condition type.
+- Map each event to an approved action type.
+- Preserve rule order, priority, and conflict behavior with tests.
+- Validate every migrated script before execution.
+- Snapshot explanation traces for high-value rules.
+- Keep `json-rules-engine` if the existing model is already doing the job cleanly.
+
+## Documentation
+
+The full migration page is here:
+
+[Neuron-JS vs json-rules-engine](https://sebasoft.github.io/neuron-js/comparisons/json-rules-engine.html)
+
+Start with the comparison hub if you are deciding between multiple rules approaches:
+
+[Neuron-JS comparison and migration guides](https://sebasoft.github.io/neuron-js/comparisons/)

content-drafts/njs-growth-05/neuron-js-vs-jsonlogic.md

@@ -0,0 +1,182 @@
+# Drafting fields
+
+Title: Neuron-JS vs JsonLogic: predicate format or TypeScript rules engine?
+
+Alias: neuron-js-vs-jsonlogic
+
+Description: A practical guide for deciding between JsonLogic and Neuron-JS when JSON predicates grow into validated, explainable TypeScript business decisions.
+
+Tags: neuron-js, jsonlogic, json-logic-js, typescript, rules-engine, migration, ai-agents
+
+# Markdown body
+
+## The short version
+
+JsonLogic is excellent when the problem is a portable JSON predicate.
+
+Neuron-JS is a better fit when that predicate has grown into a business decision that needs an owned TypeScript vocabulary, validation before runtime, approved actions, and explanation after execution.
+
+The clean rule is this:
+
+- Use JsonLogic for compact boolean logic.
+- Use Neuron-JS for governed JSON business decisions.
+
+Both are useful. They solve different pressure points.
+
+## JsonLogic is not the enemy
+
+JsonLogic earned its place because it is small and portable. A rule like this is easy to store, transmit, and evaluate:
+
+```json
+{
+  "and": [
+    { ">=": [{ "var": "cart.total" }, 100] },
+    { "==": [{ "var": "customer.tier" }, "gold"] }
+  ]
+}
+```
+
+That is a strong shape when the output is mostly true or false.
+
+It becomes weaker when the system needs named rule components, approved actions, review workflows, generated rule validation, or explanation traces.
+
+That is where Neuron-JS belongs.
+
+## Where Neuron-JS changes the model
+
+Neuron-JS does not only ask “is this predicate true?”
+
+It asks:
+
+- Is this script structurally valid?
+- Are the condition and action types approved by the application?
+- Can the runtime execute it deterministically?
+- Can the result be summarized?
+- Can a human review why it happened?
+
+That is the difference between a predicate format and a rules engine contract.
+
+## When to stay with JsonLogic
+
+Stay with JsonLogic when:
+
+- the rule is a compact boolean expression,
+- cross-language portability is the main requirement,
+- the team already has stable JsonLogic rules and operators,
+- the decision does not need approved actions,
+- validation and explanation can remain project-owned.
+
+Do not migrate a clean predicate just to use a larger abstraction.
+
+## When to move to Neuron-JS
+
+Move to Neuron-JS when the rule becomes product logic.
+
+Good triggers:
+
+- business rules are edited or reviewed outside normal deployments,
+- AI agents generate rules and malformed JSON must be rejected safely,
+- the rule needs conditions and actions, not only true or false,
+- support or audit teams need explanation traces,
+- frontend and backend code need the same TypeScript-owned rule vocabulary.
+
+## Migration pattern
+
+Start by separating the predicate from the business action.
+
+JsonLogic predicate:
+
+```json
+{
+  "and": [
+    { ">=": [{ "var": "cart.total" }, 100] },
+    { "==": [{ "var": "customer.tier" }, "gold"] }
+  ]
+}
+```
+
+Neuron-JS script:
+
+```json
+{
+  "id": "gold-cart-eligibility",
+  "rules": [
+    {
+      "id": "cart-over-threshold",
+      "type": "simple_rule",
+      "options": {},
+      "conditions": [
+        {
+          "id": "cart-total-check",
+          "type": "compare_two_numbers",
+          "options": {},
+          "params": [
+            { "id": "cart-total", "name": "op1", "type": "simple_number", "value": "125", "options": {} },
+            { "id": "operator", "name": "comp", "type": "comparator", "value": ">=", "options": {} },
+            { "id": "minimum", "name": "op2", "type": "simple_number", "value": "100", "options": {} }
+          ]
+        }
+      ],
+      "actions": [
+        {
+          "id": "eligibility-score",
+          "type": "add_two_numbers",
+          "options": {},
+          "params": [
+            { "id": "base-score", "name": "op1", "type": "simple_number", "value": "1", "options": {} },
+            { "id": "tier-score", "name": "op2", "type": "simple_number", "value": "1", "options": {} }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Validation and execution:
+
+```typescript
+import {
+  Neuron,
+  Synapse,
+  explainExecution,
+  summarizeExecutionOutput,
+  validateExecutionContext,
+  validateScript,
+} from '@sebasoft/neuron-js';
+
+const context = {
+  messages: [],
+  state: { cart: { total: 125 }, customer: { tier: 'gold' } },
+};
+
+const scriptValidation = validateScript(script);
+const contextValidation = validateExecutionContext(context);
+
+if (!scriptValidation.ok || !contextValidation.ok) {
+  throw new Error('Invalid migrated rule input');
+}
+
+const result = new Synapse(new Neuron()).execute(script, context);
+const output = summarizeExecutionOutput(result);
+const explanation = explainExecution({ script, result });
+```
+
+## Migration checklist
+
+- Keep pure predicates in JsonLogic when portability is the point.
+- Move only governed business decisions into Neuron-JS.
+- Replace anonymous operator trees with named conditions and actions.
+- Preserve null, missing value, string, and number coercion behavior in tests.
+- Validate scripts before runtime.
+- Use explanation traces for reviewer confidence.
+
+## Documentation
+
+Full guide:
+
+[Neuron-JS vs JsonLogic / json-logic-js](https://sebasoft.github.io/neuron-js/comparisons/json-logic-js.html)
+
+Comparison hub:
+
+[Neuron-JS comparison and migration guides](https://sebasoft.github.io/neuron-js/comparisons/)