feat: Remove auto encoding mode and associated reproduction scripts, and update CI and documentation for encoding examples.

Author: ronibhakta1

.github/workflows/ci.yml

@@ -37,17 +37,17 @@ jobs:
 
     - name: Verify examples generated
       run: |
-        if [ ! -f "examples/10_dirty_data.zonf" ]; then
+        if [ ! -f "examples/modes/10_dirty_data_compact.zonf" ]; then
           echo "Error: 10_dirty_data.zonf not generated"
           exit 1
         fi
-        if [ ! -f "examples/13_deep_recursion.zonf" ]; then
+        if [ ! -f "examples/modes/13_deep_recursion_compact.zonf" ]; then
           echo "Error: 13_deep_recursion.zonf not generated"
           exit 1
         fi
 
     - name: Verify roundtrip (examples)
-      run: npx ts-node scripts/verify_roundtrip.ts
+      run: npx ts-node scripts/verify_roundtrip_modes.ts
 
     - name: Verify roundtrip (comprehensive)
       run: node benchmarks/scripts/verify-comprehensive-roundtrip.js

.github/workflows/llm-evals.yml

@@ -37,7 +37,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
           cache: 'npm'
 
       - name: Install dependencies
@@ -130,7 +130,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
           cache: 'npm'
 
       - name: Install dependencies

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2025-12-04
+
+### Changed
+- **Code Quality**: Refactored entire codebase to remove inline implementation comments, relying on clear code structure and JSDoc.
+- **Documentation**: Updated `SPEC.md` and versioning utilities to reflect v1.3.0.
+
 ## [1.2.0] - 2025-12-03
 
 ### Major Release: Enterprise Features & Production Readiness

SPEC.md

@@ -2,7 +2,7 @@
 
 ## Zero Overhead Notation - Formal Specification
 
-**Version:** 1.1.0
+**Version:** 1.3.0
 
 **Date:** 2025-12-01
 

compare_deep_toon.ts

@@ -306,7 +306,7 @@ const data = {
 
 ## Performance Tips
 
-1. **Dictionary compression**: Best for repetitive strings (enums, categories)
+
 2. **Dictionary compression**: Best for categorical data (status, roles, countries)
 3. **Type coercion**: Enable when dealing with LLM outputs
 4. **Field ordering**: Use for retrieval-heavy applications

compare_toon.ts

@@ -87,10 +87,10 @@ F,2,Bob
 
  ### `encodeAdaptive(input: any, options?: AdaptiveOptions): string | AdaptiveResult`
 
- Automatically selects the best encoding mode based on data complexity and user preferences.
+ Encodes data using the specified mode (default: 'compact').
 
  **Options:**
- - `mode`: `'auto' | 'compact' | 'readable' | 'llm-optimized'` (default: `'auto'`)
+ - `mode`: `'compact' | 'readable' | 'llm-optimized'` (default: `'compact'`)
  - `indent`: `number` - Indentation spaces for readable mode (default: `2`)
  - `debug`: `boolean` - Return detailed analysis (default: `false`)
 
@@ -100,8 +100,7 @@ F,2,Bob
 
  | Mode | Description | Best For |
  |------|-------------|----------|
- | `auto` | Analyzes data and picks best mode automatically | General purpose, mixed data |
- | `compact` | Maximum compression (tables, T/F, delta encoding) | Production APIs, token efficiency |
+ | `compact` | Maximum compression (tables, T/F) | Production APIs, token efficiency |
  | `readable` | YAML-like syntax with indentation | Config files, human editing |
  | `llm-optimized` | Balances clarity and tokens (true/false not T/F) | AI workflows, prompts |
 
@@ -117,8 +116,7 @@ F,2,Bob
    ]
  };
 
- // Auto mode - let ZON decide
- const auto = encodeAdaptive(data, { mode: 'auto' });
+
 
  // Compact mode - maximum compression
  const compact = encodeAdaptive(data, { mode: 'compact' });
@@ -136,7 +134,7 @@ F,2,Bob
  **Debug Mode:**
 
  ```typescript
- const result = encodeAdaptive(data, { mode: 'auto', debug: true });
+ const result = encodeAdaptive(data, { mode: 'compact', debug: true });
  console.log(result.decisions);  // See why ZON chose this mode
  console.log(result.output);     // The encoded string
  ```

docs/advanced-features.md

@@ -11,7 +11,7 @@ Choose the right encoding mode for your use case to balance token efficiency, re
 | Production APIs | `compact` | Maximum token efficiency |
 | Config files | `readable` | Human-editable, git-friendly |
 | LLM prompts | `llm-optimized` | Best AI understanding |
-| Mixed/unknown data | `auto` | Adapts automatically |
+
 | Development/debugging | `readable` | Easiest inspection |
 | Caching for LLMs | `compact` or `llm-optimized` | Token efficiency + clarity |
 
@@ -29,8 +29,7 @@ const configFile = encodeAdaptive(config, { mode: 'readable', indent: 2 });
 // For LLM prompts (best comprehension)
 const llmPrompt = encodeAdaptive(context, { mode: 'llm-optimized' });
 
-// Let ZON decide
-const adaptive = encodeAdaptive(unknownData, { mode: 'auto' });
+
 ```
 
 ---
@@ -89,7 +88,7 @@ company{departments{engineering{employees[{id:1,name:Alice,role:Senior}]},sales{
 
 1. **Table Format Works**: Uniform data → table encoding → massive token savings
 2. **Key Compression**: Repeated keys eliminated via column headers
-3. **Delta Encoding**: Sequential IDs compressed efficiently (1, +1, +1)
+
 4. **LLM Friendly**: Tabular data is easier for AI to parse
 5. **human Readable**: Even compact mode is clearer with tables
 

docs/api-reference.md

@@ -19,7 +19,7 @@ Choose the right ZON mode for your LLM workflow:
 | **RAG context** | `llm-optimized` | Balances clarity and efficiency |
 | **Function calling** | `compact` | Minimal tokens |
 | **Human review needed** | `readable` | YAML-like, easy to verify |
-| **Mixed/unknown** | `auto` | Adapts automatically |
+
 
 ### Token Impact Examples