"""Bundled agent-facing examples; no filesystem reads or user-selected paths."""


def documentation():
    """Return a fresh documentation payload, independent of mutable virtual files."""
    return {
        "language": "Aegis",
        "version": "0.1",
        "workflow": [
            "Choose an example and copy its content into create_file(filename, content). "
            "Example filenames are suggestions, not files already in your virtual store.",
            "Call run_ag_file(filename) with the .aeg extension. Use write_file to revise "
            "an existing script; scripts can be run repeatedly with fresh variables.",
            "When status is input_required, call provide_ag_input(value) on your next "
            "response. Each value must be a string. Continue for each requested input.",
            "Output is cumulative across pauses. An input request extends the wake to "
            "20 total model responses, including those already used; it never resets the cap.",
        ],
        "rules": [
            "One statement per line; consistent two or four spaces per indent; no tabs. "
            "Use # comments and lowercase names matching [a-z][a-z0-9_]*.",
            'Strings use double quotes and JSON escapes. Values are int, finite float, '
            'bool (true/false), or string. input() always returns string.',
            "print(expression) accepts one value and appends a newline. Print a label "
            "and a number separately: there is no string conversion or numeric input parser.",
            "Precedence high to low: parentheses; unary not/minus; ^; * /; + -; "
            "comparisons; and; or. Power is right-associative: 2 ^ 3 ^ 2 is 512. "
            "Unary minus binds first: -2 ^ 2 is 4. Use parentheses for clarity.",
            "Arithmetic excludes bools. Mixed int/float arithmetic promotes to float. "
            "Division returns float. + also concatenates two strings. Unlike-type "
            "equality is false, so 1 == 1.0 is false. Do not chain comparisons.",
            "if, and, or, not require bools; and/or short-circuit. All branches are "
            "checked before execution. Assign variables on every branch before reading them.",
            "No loops, functions, imports, collections, host files, terminal, network, "
            "environment or dynamic execution. Programs have bounded resources. "
            "Errors include safe source positions; fix the script and run again.",
        ],
        "examples": [
            {
                "filename": "hello.aeg",
                "purpose": "Print literal text and concatenate strings.",
                "content": 'greeting = "Hello"\nname = "Astra"\nprint(greeting + ", " + name)\n',
                "inputs": [],
                "expected_output": "Hello, Astra\n",
            },
            {
                "filename": "calculate.aeg",
                "purpose": "Calculate with numbers and print labels separately.",
                "content": 'width = 8\nheight = 3.5\narea = width * height\n'
                           'print("Area:")\nprint(area)\nprint(7 / 2)\n'
                           'print(2 ^ 3 ^ 2)\nprint(-2 ^ 2)\nprint(2 ^ -2)\n',
                "inputs": [],
                "expected_output": "Area:\n28.0\n3.5\n512\n4\n0.25\n",
            },
            {
                "filename": "policy.aeg",
                "purpose": "Combine booleans and comparisons; assign a result in both branches.",
                "content": 'approved = true\nrisk = 2\n'
                           'if approved and risk < 5:\n  decision = "allow"\n'
                           'else:\n  decision = "deny"\nprint(decision)\n',
                "inputs": [],
                "expected_output": "allow\n",
            },
            {
                "filename": "greet_input.aeg",
                "purpose": "Pause for one input string, then resume with provide_ag_input.",
                "content": 'print("Supply a name")\nname = input()\nprint("Hello, " + name)\n',
                "inputs": ["Astra"],
                "expected_output": "Supply a name\nHello, Astra\n",
            },
            {
                "filename": "approve_input.aeg",
                "purpose": "Request two strings in sequence and branch on an explicit text answer.",
                "content": 'print("Supply a name")\nname = input()\n'
                           'print("Supply yes to approve")\nanswer = input()\n'
                           'if answer == "yes":\n  print("Approved: " + name)\n'
                           'else:\n  print("Denied: " + name)\n',
                "inputs": ["Astra", "yes"],
                "expected_output": "Supply a name\nSupply yes to approve\nApproved: Astra\n",
            },
            {
                "filename": "nested_policy.aeg",
                "purpose": "Nest conditionals and safely skip a division using short-circuiting.",
                "content": '# Both paths assign a message before it is read.\n'
                           'enabled = true\ncount = 0\nif enabled:\n'
                           '  if count != 0 and 10 / count > 2:\n    message = "high"\n'
                           '  else:\n    message = "low or empty"\n'
                           'else:\n  message = "disabled"\nprint(message)\n'
                           'print(not false)\nprint("line one\\nline two")\n',
                "inputs": [],
                "expected_output": "low or empty\ntrue\nline one\nline two\n",
            },
        ],
    }