playbook/docs/tsl/syntax/00_agent_index.json

{
  "version": "2.0",
  "description": "Agent-optimized quick index for TSL syntax - read this FIRST",
  "total_tokens_saved_per_query": "~2000-3000",
  "changelog": {
    "2.0": "Extended coverage from 7 to 14 scenarios, added understand_code and optimize_code decision paths",
    "1.0": "Initial version with 7 high-frequency scenarios"
  },

  "intent_to_file": {
    "hello_world": {
      "file": "01_quickstart.md",
      "line": 182,
      "token_cost": 50,
      "example": "echo \"hello\";"
    },
    "function_basic": {
      "file": "05_functions_and_calls.md",
      "line": 103,
      "token_cost": 100,
      "example": "function Add(a, b);\nbegin\n    return a + b;\nend;"
    },
    "function_in_tsl": {
      "file": "05_functions_and_calls.md",
      "line": 82,
      "token_cost": 150,
      "example": "a := 1;\ntest();\n\nfunction test();\nbegin\n    echo \"test\";\nend;"
    },
    "procedure": {
      "file": "05_functions_and_calls.md",
      "line": 130,
      "token_cost": 80,
      "example": "procedure LogDone();\nbegin\nend;"
    },
    "for_loop": {
      "file": "07_control_flow.md",
      "line": 89,
      "token_cost": 100,
      "example": "for i := 0 to 2 do\n    sum := sum + i;"
    },
    "while_loop": {
      "file": "07_control_flow.md",
      "line": 64,
      "token_cost": 100,
      "example": "counter := 0;\nwhile counter < 3 do\n    counter := counter + 1;"
    },
    "if_condition": {
      "file": "07_control_flow.md",
      "line": 54,
      "token_cost": 120,
      "example": "if flag > 0 then\nbegin\n    value := 1;\nend"
    },
    "assignment": {
      "file": "06_expressions_and_operators.md",
      "line": 136,
      "token_cost": 60,
      "example": "a := 1;"
    },
    "variable_declaration": {
      "file": "04_variables_and_constants.md",
      "line": 75,
      "token_cost": 80,
      "example": "var a;\na := 1;"
    },
    "class_basic": {
      "file": "08_objects_and_classes.md",
      "line": 98,
      "token_cost": 200,
      "example": "type Person = class\npublic\n    name;\nend;"
    },
    "class_in_tsl": {
      "file": "08_objects_and_classes.md",
      "line": 118,
      "token_cost": 250,
      "example": "obj := new MyClass();\nobj.value := 5;\n\ntype MyClass = class\npublic\n    value;\nend;"
    },
    "unit_import": {
      "file": "09_units_and_scope.md",
      "line": 141,
      "token_cost": 60,
      "example": "uses DemoUnit;"
    },
    "unit_skeleton": {
      "file": "09_units_and_scope.md",
      "line": 56,
      "token_cost": 200,
      "example": "unit DemoUnit;\n\ninterface\n\nfunction Ping();\n\nimplementation\n\nfunction Ping();\nbegin\n    return 1;\nend;\n\nend."
    },
    "array_operations": {
      "file": "12_matrix_and_collections.md",
      "line": 46,
      "token_cost": 60,
      "example": "arr := array(10, 20, 30);"
    }
  },

  "syntax_quick_ref": {
    "assignment": {
      "correct": ":=",
      "wrong": "=",
      "error_if_wrong": "invalid statement"
    },
    "comparison": {
      "correct": "=",
      "context": "only in conditions/expressions"
    },
    "function_def": {
      "pattern": "function Name(args);\nbegin\n    ...\nend;",
      "notes": "use 'function' by default, not 'procedure'"
    },
    "class_def": {
      "pattern": "type Name = class\npublic\n    ...\nend;",
      "wrong": "class Name",
      "error_if_wrong": "invalid statement"
    },
    "for_loop": {
      "pattern": "for i := start to end do\nbegin\n    ...\nend;"
    },
    "if_statement": {
      "pattern": "if condition then\nbegin\n    ...\nend;"
    },
    "tsl_file_structure": {
      "order": ["statements first", "declarations after"],
      "wrong": "declarations before statements or after declarations"
    }
  },

  "common_errors": {
    "invalid statement": {
      "likely_causes": [
        {
          "pattern": "a = 1",
          "fix": "a := 1",
          "doc": "11_pitfalls.md",
          "line": 45
        },
        {
          "pattern": "class Person",
          "fix": "type Person = class",
          "doc": "11_pitfalls.md",
          "line": 34
        },
        {
          "pattern": "statements after function declarations",
          "fix": "move all statements before declarations",
          "doc": "02_core_model.md",
          "line": 34
        }
      ]
    },
    "compile error": {
      "check": "11_pitfalls.md for common syntax mistakes"
    }
  },

  "decision_tree": {
    "task_type": {
      "write_new_code": {
        "simple_script": "01_quickstart.md#L182",
        "function": "05_functions_and_calls.md#L103",
        "procedure": "05_functions_and_calls.md#L130",
        "class": "08_objects_and_classes.md#L98",
        "loop": "07_control_flow.md#L89",
        "condition": "07_control_flow.md#L54",
        "unit": "09_units_and_scope.md#L56",
        "array": "12_matrix_and_collections.md#L46"
      },
      "fix_error": {
        "invalid_statement": "11_pitfalls.md#L34-L59",
        "compile_error": "11_pitfalls.md",
        "runtime_error": "check error message details"
      },
      "understand_code": {
        "scan_file_structure": "02_core_model.md#L34",
        "trace_function": "05_functions_and_calls.md",
        "trace_class": "08_objects_and_classes.md",
        "check_unit_imports": "09_units_and_scope.md"
      },
      "optimize_code": {
        "check_profiler": "15_debug_and_profiler.md",
        "optimize_matrix": "22_matrix_deep_dive.md"
      }
    }
  },

  "file_model_rules": {
    "tsl_script": {
      "extension": ".tsl",
      "structure": "statements_first, then declarations",
      "usage": "executable scripts, one-time tasks"
    },
    "tsf_module": {
      "extension": ".tsf",
      "structure": "only declarations, no executable statements",
      "usage": "reusable functions/classes"
    }
  },

  "optimization_notes": {
    "agent_should": [
      "Read this file FIRST before any other docs",
      "Use 'intent_to_file' for direct line jumps (14 scenarios covered)",
      "Check 'common_errors' for error fixes",
      "Use 'syntax_quick_ref' for inline validation",
      "Use 'decision_tree' to determine task type before searching"
    ],
    "token_savings": {
      "without_this_file": "2000-4000 tokens per query",
      "with_this_file": "200-500 tokens per query",
      "reduction": "80-90%"
    },
    "coverage": {
      "v1.0": "7 scenarios (30% of common tasks)",
      "v2.0": "14 scenarios (70% of common tasks)",
      "target": "15-20 scenarios (80-90% of common tasks)"
    }
  }
}