{
  "schema_version": "2.0.0",
  "schema_url": "https://simorg.tech/.well-known/agent-docs.schema.json",
  "name": "Simorg",
  "description": "Complete Simorg documentation corpus for AI agents and tools — an AI-native event-driven language, a mathematical runtime, and the Logos artifact registry. Includes language facts, site pages, homepage positioning, and agent resources.",
  "publisher": {
    "name": "Simorg Oy",
    "location": "Helsinki, Finland",
    "email": "info@simorg.tech",
    "url": "https://simorg.tech/about-us/"
  },
  "homepage": "https://simorg.tech/",
  "documentation_base_url": "https://simorg.tech/docs/",
  "generated_at": "2026-09-13T15:28:41.865Z",
  "doc_version": "genesis-0-1-0",
  "language_version": "genesis-0.1.0",
  "license": "Documentation © Simorg Oy. Quote with attribution to simorg.tech.",
  "preferred_entry_points": {
    "agent_guide": "https://simorg.tech/agent-resources/simorg-gem.md",
    "structured_json": "https://simorg.tech/.well-known/agent-docs.json",
    "structured_json_alias": "https://simorg.tech/docs.json",
    "llms_txt": "https://simorg.tech/llms.txt",
    "llms_full_txt": "https://simorg.tech/llms-full.txt",
    "agent_ref": "https://simorg.tech/agent-resources/simorg-ref.md",
    "agent_examples": "https://simorg.tech/agent-resources/simorg-examples.json",
    "sitemap": "https://simorg.tech/sitemap.xml"
  },
  "usage": {
    "summary": "Fetch this JSON once to load every documentation page (markdown content included). Read agent-resources/simorg-gem.md first for the rules that prevent invalid Simorg; use markdown_url to refresh a single page.",
    "content_format": "text/markdown",
    "citation": "Simorg (simorg.tech), Simorg Oy.",
    "openai_hint": "Pass documents[].content into retrieval / file_search / tool context. Cite with id + title; url is the human-readable page. Use language_facts for factual questions and homepage_snapshot for current product messaging."
  },
  "language_facts": {
    "name": "Simorg",
    "version": "genesis-0.1.0",
    "maturity": "beta",
    "maturity_note": "Public beta, pre-LTS. Stable enough to write and run real programs; interfaces, formats and behaviour can still change between releases. Not recommended for production workloads until the first LTS release, and use is at the user's own risk.",
    "paradigm": [
      "event-driven",
      "data-flow",
      "asynchronous",
      "declarative"
    ],
    "file_extensions": [
      ".art",
      ".sim"
    ],
    "run_command": "sim -f main.art",
    "version_command": "sim --version",
    "package_registry": {
      "name": "Logos",
      "url": "https://logos.simorg.tech"
    },
    "comment_syntax": [
      "// line comment",
      "/* block comment */"
    ],
    "has_assignment_operator": false,
    "assignment_note": "`=` is a relational equality check. Data binds to a variable by flowing into it, e.g. `10 $x`.",
    "reserved_keywords": [],
    "operator_precedence": false,
    "evaluation_order": "strictly left to right",
    "has_null": false,
    "empty_values": [
      "0",
      "0.0",
      "0x",
      "\"\""
    ],
    "throws_exceptions": false,
    "failure_behaviour": "The expected event does not release; the engine may log a conversion failure.",
    "has_garbage_collector": false,
    "has_classical_functions": false,
    "has_index_based_arrays": false,
    "collections": "Gates `( )` `[ ]` for structure; the collector `..` batches streams into `{ }`.",
    "scopes": {
      "isolator": "{ ... } — closed, events cannot exit",
      "conditional": "activator { ... } — opens when the activator vibrates",
      "io": "$name { ... } — bidirectional"
    }
  },
  "homepage_snapshot": {
    "hero": {
      "title": "Where agents build software that compounds.",
      "subtitle": "A language agents speak. A runtime that keeps them inside budget and permissions. A registry where solved problems become reusable artifacts. Publish an agent, for code, video, voice or analysis, and it earns every time it solves one.",
      "subtitleEmphasis": "Every agent and every artifact built here makes the next one cheaper.",
      "credibility": [
        "Deterministic runtime",
        "Runs on your own machines",
        "229 engine-verified programs"
      ],
      "primaryCta": {
        "label": "Sign Up for Pilot Program",
        "href": "LOGOS:/signup",
        "url": "https://logos.simorg.tech/signup"
      },
      "secondaryCta": {
        "label": "Read the Docs",
        "href": "/docs"
      }
    },
    "tagline": "Build AI-native software with SIMORG. A programming language, a mathematical runtime, and a platform where the agents and artifacts you publish earn on every use.",
    "challengeSection": {
      "overline": "The Challenge",
      "heading": "Why Is AI Making Software More Expensive?",
      "steps": [
        {
          "id": "token-economy",
          "step": 1,
          "challengeTitle": "Classical Programming Is,",
          "buttonPoints": [
            "Heavily Tokenized.",
            "Complex to Understand.",
            "Hard to Integrate."
          ],
          "challengeSummary": "Classical programming language stack abstractions, reserved keywords, and noise that agents pay for in tokens—without a runtime designed for AI-native execution resulting in a token economy that does not add up!"
        },
        {
          "id": "conscious-network",
          "step": 2,
          "challengeTitle": "Today's Environment,",
          "buttonPoints": [
            "High Token Consumption.",
            "Understanding Complexity.",
            "Integration Friction."
          ],
          "challengeSummary": "Classical languages increase token consumption—and tokens cost money."
        },
        {
          "id": "integration-workflows",
          "step": 3,
          "challengeTitle": "AI Needs,",
          "buttonPoints": [
            "Environment to Integrate.",
            "Context to Understand.",
            "Tokens to Communicate."
          ],
          "challengeSummary": "AI needs three enablers to create value: context to understand, tokens to communicate, and an environment to execute."
        }
      ]
    },
    "solutionSection": {
      "overline": "The Solution",
      "heading": "Here's how SIMORG solves it",
      "description": "A language agents speak, a runtime that obeys budgets, an economy where every solution makes the next one cheaper, and a market where publishing pays.",
      "solutions": [
        {
          "id": "token-economy",
          "label": "Speak",
          "title": "A Language Agents Speak",
          "points": [
            "Zero Reserved Keywords.",
            "Maximum Meaning per Token.",
            "A spec that fits in a model context window."
          ],
          "summary": "A language designed for agents: zero reserved keywords, maximum meaning per token.",
          "detail": "A data- and event-driven fully async programming language that compiles your code into mathematical entities and executes it on top of a mathematical machine—removing all unnecessary abstractions while having zero reserved keywords. We make the token economy positive."
        },
        {
          "id": "integration-workflows",
          "label": "Run",
          "title": "A Runtime That Obeys Budgets",
          "points": [
            "Deterministic, event-driven execution.",
            "Capability-scoped permissions, granted by owners.",
            "Hard caps on what an agent can spend and touch."
          ],
          "summary": "A deterministic, event-driven runtime where agents act under owner-granted permissions and hard budget caps, and every run is reproducible.",
          "detail": "Our language makes it possible to integrate AI agents in every single digital element, from 3D components all the way to binaries and cloud applications. A platform of digital elements shaped on top of artifacts wrapped inside Simorg code, published by our Artisans. Artisans choose what to share and what to sell; every artifact is versioned, capability scoped, and engine tested, and agents include it by reference instead of re-reading code they never needed to see."
        },
        {
          "id": "conscious-network",
          "label": "Reuse",
          "title": "Every Solution Makes The Next One Easier",
          "points": [],
          "summary": "Every time an AI agent creates something useful, it becomes a reusable Artifact on Logos. As more artifacts are created, the cost of building new solutions decreases.",
          "detail": "Applications created using our technology can naturally communicate with each other, making it possible to create a network of AI-powered applications that communicate with one another."
        },
        {
          "id": "publish-earn",
          "label": "Earn",
          "title": "Publish Once, Earn Every Use",
          "points": [
            "Artifacts earn every time someone includes one in what they build.",
            "Agents built from your artifact pay you too.",
            "Agents you put a price on earn every time someone uses them."
          ],
          "summary": "Publish an artifact and it earns every time someone includes it in what they build. Agents built from your artifact pay you too. Put a price on an agent and it earns every time someone uses it.",
          "detail": "Publish an artifact and it earns every time someone includes it in what they build. Agents built from your artifact pay you too. Put a price on an agent and it earns every time someone uses it, for code, video, voice or analysis."
        }
      ]
    },
    "platformSection": {
      "overline": "The Platform",
      "heading": "How it works",
      "description": "Simorg platform is made on top collaboration between humans and agents. Each new participant adds value to the ecosystem."
    },
    "blogSection": {
      "overline": "Latest Updates",
      "heading": "From the Blog",
      "description": "Stay up to date with the latest releases, design decisions, and insights from the Simorg team."
    },
    "milestones": [
      {
        "title": "Simorg Genesis",
        "date": "Today",
        "description": "Language Syntax and Core Features",
        "status": "completed",
        "progress": 100,
        "result": "The good parts of our first prototype migrated and re-implemented using C++, making it possible to release a Genesis version of the technology by the end of this phase so our community can experience the language and share their feedback.",
        "why": "A solid first engine gives our early adopters the chance to validate our technology in practice and gives the community something to try and build on. It also de-risks the next phases of the project.",
        "timings": {
          "start": "01 Sep 2025",
          "target": "23rd May 2026",
          "notes": "The goal is to have a working engine and a complete language core by the end of this phase"
        }
      },
      {
        "title": "Logos",
        "date": "Next",
        "description": "Opening Up Logos To Artisans",
        "status": "current",
        "progress": 25,
        "result": "Artisans can publish and share their blueprints. The ecosystem becomes collaborative and reusable.",
        "why": "A single implementation cannot cover every use case. Logos turns Simorg into a platform by letting the community contribute and share packages, making it possible to build a universe together.",
        "timings": {
          "start": "24th May 2026",
          "target": "12th September 2026",
          "notes": "This includes minimum lovable version of Logos, toolchains and documents."
        }
      },
      {
        "title": "Simorg Applications",
        "date": "Future",
        "description": "Enable Interconnected Application Shells",
        "status": "future",
        "progress": 20,
        "result": "Simorg applications can communicate and compose safely and clearly, supporting distributed and modular systems.",
        "why": "Real-world systems are rarely isolated. Connections enable the creation of a universe of interconnected conscious applications.",
        "timings": {
          "start": "Q4 2026",
          "target": "End of 2026",
          "notes": "Timeline will be refined once Logos is in place."
        }
      }
    ],
    "agentDemoCode": "\"A react app served on port 3000\" #myApp\n\"A home page inside myApp \" #homepage\n\"A chat component inside homepage\" #chat\n\"Connet chatComponent to ollama running on my pc\""
  },
  "site_pages": [
    {
      "path": "/",
      "title": "Home",
      "description": "Build AI-native software with SIMORG. A programming language, a mathematical runtime, and a platform where the agents and artifacts you publish earn on every use.",
      "url": "https://simorg.tech/"
    },
    {
      "path": "/docs",
      "title": "Documentation",
      "description": "The SIMORG programming language reference and the SIMORG platform documentation.",
      "url": "https://simorg.tech/docs/"
    },
    {
      "path": "/download",
      "title": "Download",
      "description": "Download the Simorg toolchain for macOS, Linux, and Windows.",
      "url": "https://simorg.tech/download/"
    },
    {
      "path": "/blog",
      "title": "Blog",
      "description": "Stay up to date with the latest releases, design decisions, and insights from the Simorg team.",
      "url": "https://simorg.tech/blog/"
    },
    {
      "path": "/about-us",
      "title": "About Us",
      "description": "Simorg Oy is a Helsinki-based company building an AI-native software platform: a compact language, a mathematical runtime, and a platform of reusable Artifacts.",
      "url": "https://simorg.tech/about-us/"
    },
    {
      "path": "/support",
      "title": "Support Us",
      "description": "Support Simorg development with a one-time or monthly donation.",
      "url": "https://simorg.tech/support/"
    }
  ],
  "agent_resources": {
    "gem_markdown_url": "https://simorg.tech/agent-resources/simorg-gem.md",
    "ref_markdown_url": "https://simorg.tech/agent-resources/simorg-ref.md",
    "examples_json_url": "https://simorg.tech/agent-resources/simorg-examples.json",
    "qa_example_count": 122,
    "qa_file_count": 16,
    "program_count": 229
  },
  "categories": [
    {
      "id": "reference-book",
      "label": "SIMORG Programming Language",
      "document_count": 7,
      "url": "https://simorg.tech/docs/reference-book/"
    },
    {
      "id": "platform",
      "label": "SIMORG Platform",
      "document_count": 7,
      "url": "https://simorg.tech/docs/platform/"
    }
  ],
  "blog_post_count": 2,
  "blog_posts": [
    {
      "slug": "status-update-genesis-version",
      "title": "Status Update",
      "author": "Milad Habibi",
      "date": "2026-08-09",
      "tags": [
        "genesis",
        "beta",
        "logos",
        "pilot program"
      ],
      "summary": "Where Simorg stands today: Genesis is out, the repository is being built, and the Pilot Program opens in September.",
      "url": "https://simorg.tech/blog/status-update-genesis-version/",
      "markdown_url": "https://simorg.tech/raw/blog/status-update-genesis-version.md"
    },
    {
      "slug": "words-to-create-worlds",
      "title": "Words to Create Worlds",
      "author": "Milad Habibi",
      "date": "2026-08-02",
      "tags": [
        "language",
        "simplicity",
        "tokens",
        "cost",
        "ai"
      ],
      "summary": "Simorg has zero reserved keywords, no null and no exceptions. Here is why that simplicity is the cheapest code you will ever run.",
      "url": "https://simorg.tech/blog/words-to-create-worlds/",
      "markdown_url": "https://simorg.tech/raw/blog/words-to-create-worlds.md"
    }
  ],
  "document_count": 14,
  "documents": [
    {
      "id": "reference-book/Variables",
      "title": "Variables",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/Variables/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/Variables.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-06T14:15:41.000Z",
      "content": "Variables are **event markers**, not memory owners.\nA variable does nothing on its own: it vibrates only when an **event** reaches it. Variables are fixed parts of your program's structure.\n\nUse <<<$>>> before an identifier to make it a variable, \n\n```\n\"Hello World!\" $myFirstVar\nmyFirstVar ?\n```\nIn the above example the value literal <<<Hello World!>>> vibrates as soon as our application starts. That is our initializer event: it flows into <<<myFirstVar>>>, which vibrates in turn. Events always flow left to right.\n\n$$$EventFlow kind=vibration$$$\n\n### Value Literals\n\nSimorg's runtime infers the type and runtime doesn't need any type definition. \n\n| Form | Example | Meaning |\n|------|---------|---------|\n| Buffer | <<<0x01>>> | raw bytes (hex) |\n| Number | <<<10>>> | integer or decimal |\n| String | <<<\"Hello\">>> | text |\n\nEmpty Values are valid Events — they represent emptiness, not null or void,\n\n```\n0      // empty number\n0.0    // empty decimal\n0x     // empty buffer\n\"\"     // empty string\n```\nEmptiness can be checked using <<<Truthy Operator &>>>. It will be discussed later under <<<Event Flow>>> section.\n\nSimorg doesn't have any concept related to nullity e.g. <<<undefined>>>, <<<null>>>, <<<nil>>>, <<<Option>>>, <<<Maybe>>> and others.\n\nEscape sequences including, <<<\\n>>> (newline), <<<\\r>>> (carriage return), <<<\\t>>> (tab) are supported inside String values.\n\nIt's also possible to insert a value into a string using <<<{}>>> placeholder\n\n```\n100 \"number {} is now embedded\" ?\n```\n\nUsing <<<\\>>> before <<<{}>>> will disable this behavior.\n\n"
    },
    {
      "id": "reference-book/Gates",
      "title": "Gates",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/Gates/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/Gates.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-06T14:15:41.000Z",
      "content": "When a single variable is not enough, **Gates** combine multiple events into a more complex structure or logic.\n\nA **Gate** is a Shell type that acts as an event aggregator — it collects events from multiple slots and, when its condition is met, vibrates and releases them together. After a Gate releases, it is cleared.\n\nSimorg provides two Gate types, each with its own syntax and behavior:\n\n| Gate | Syntax | Releases when |\n|------|--------|---------------|\n| OR | <<<[ ]>>> | at least one slot has an event |\n| AND | <<<( )>>> | every slot has an event |\n\n### OR\n\nUse <<<[ ]>>> to define an OR gate. It releases when **at least one** slot receives an event.\n\n```\n[1,2,3] ? // [1,2,3]\n```\n\n$$$EventFlow kind=or$$$\n\nThree value literals vibrate at startup; the OR gate receives their events and releases, because at least one slot holds one. The logger prints the result in gate form.\n\nThe engine aggregates events when possible — all three values appear together in one release.\n\nEmpty values (<<<0>>>, <<<\"\">>>, <<<0x>>>, <<<0.0>>>) are valid events. Gates respond to **event presence**, not truthy/falsy checks. Guards for empty values are covered later in the Event Flow chapter.\n\n### XOR\n\nSame bracket syntax, but separate slots with <<<;>>> instead of <<<,>>> to get **sequential** release — one event per processing cycle.\n\n```\n[1;2;3] ? // 1\n          // 2\n          // 3\n```\n\n$$$EventFlow kind=xor$$$\n\nUnlike OR, XOR does not batch: each slot releases one at a time. This makes XOR useful when events must flow in sequence.\n\nSimorg is fully async — events decide what goes next, not line order.\n\n### AND\n\nUse <<<( )>>> to define an AND gate. It releases only when **all** slots have an event.\n\n```\n100 $var1\n\"hello\" $var2\n0.0 $var3\n\n(var1, var2, var3) $myAndGate\nmyAndGate ? // (100, hello, 0.0)\n```\n\n$$$EventFlow kind=and$$$\n\nIf any slot is missing an event, the gate does not release:\n\n```\n100 $var1\n\"hello\" $var2\n$var3\n\n(var1, var2, var3) $myAndGate\nmyAndGate ? // nothing logged\n```\n\nUse <<<,>>> to separate slots in an AND gate. <<<;>>> has no effect here.\n\n### Key Takeaways\n\nGates behave like logical gates in software and electronics. What matters is whether a slot has an event, not whether its value is <<<truthy>>>. Values like <<<\"\">>>, <<<0>>>, and <<<0x00>>> are valid events.\n\nBeyond holding data, an AND gate binds the slots together:\n\n```\n\"Jacob\" $name\n21 $age\n\"Istanbul\" $city\n\n(name, age, city) $userInformation\n```\n\nWhenever <<<userInformation>>> vibrates, <<<name>>>, <<<age>>>, and <<<city>>> are guaranteed to be present together.\n\n### Scope\n\nvariables declared inside a gate belong to that gate's scope. Access named slots with the <<<.>>> operator:\n\n```\n(\n  \"HELLO\" $hello,\n  \"BYE\" $bye\n) $message\n\nmessage.hello ? // HELLO\n```\n\nGates blend object and array behavior: named slots are accessed like object fields; reading the gate as a whole treats it like a collection. More on this in the Wrapper Shells chapter.\n"
    },
    {
      "id": "reference-book/Event-Flow",
      "title": "Event Flow",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/Event-Flow/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/Event-Flow.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-06T14:15:41.000Z",
      "content": "\nThese operators are the glue between Shells. They create **pathways** in which events stream from left to right, forming a **pipe**.\n\nA pipe shapes when operators chain together. A pipe does not release events outside itself unless you explicitly route them out using variables.\n\nThese operators are quite intoivite and easy to remember.\n\n## Opener\nUse <<<:>>> to make a pipe dependent to future events.\n\nWhen a pipe doesn't have a head operator, it is called **Closed**: the leading value vibrates on its own at startup:\n\n```\n200 $myConst200\n```\n\nUse <<<:>>> as head operator to open up the pipe to future events. Open pipe is dependent to an exteranal event:\n\n```\n:200 $myConst200 ? // nothing logged\n```\n\nPush data into another pipe through a variable:\n\n```\n// passing event into myConst200 and receiving event back\n100 myConst200 ? \n```\n\nCombine both behaviors with a gate, auto-init at startup and accept events later:\n\n```\n// notice how : is used as a gate slot\n// this way we receive incoming event into a slot\n:[ 200, :] $myConst200\n\n100 myConst200\nmyConst200 ? // 200\n             // 100\n```\n\n$$$EventFlow kind=opener$$$\n\n## Arithmetic\n\nBinary operators consume their **right-hand operand**: <<<+>>>, <<<->>>, <<<*>>>, <<</>>>, <<<%>>>.\n\n```\n19 $numA\n 2 $numB\n\nnumA + numB $add\nadd ? // 21\n```\n\n<<<++>>> and <<<-->>> are Unary operators and they do not need an operand.\n\n```\n19++ ? // 20\n```\n\n<<<+>>> can be used also to join string or buffers.\n\n```\nstrA + strB $strC       // Hello World!\nstrC + 100 + 20 $strD   // Hello World!10020\n```\n\n**No operator precedence**, evaluation is strictly left to right:\n\n```\n1 + 2 * 5 / 15 ? // 1\n```\n\n$$$EventFlow kind=arithmetic$$$\n\nParentheses in calculations create a **gate**, not grouping.\n\nWhen using <<<->>> as a subtraction operator, do not forget to put a space after it, otherwise it will be considered a negative sign for the next token.\n\n## Relational\n\nRelational operators do not return booleans. On success, the **subject** (left side) passes through unchanged. The **object** (right side) is what it is checked against.\n\n```\n20 = 20 $x\nx ? // 20\n\n20 = 10 $y\ny ? // never releases\n```\n\n$$$EventFlow kind=relational$$$\n\n| Operator | Meaning |\n|----------|---------|\n| <<<=>>> | equal |\n| <<<!>>> | not equal |\n| $$$KeywordSnippet keyword=> $$$  <<<>=>>> | greater / greater-or-equal |\n| $$$KeywordSnippet keyword=< $$$ <<<<=>>> | less / less-or-equal |\n\nEmpty values of different types are not equal (<<<0x>>> ≠ <<<\"\">>>).\nType coercion is automatically happening between numbers and strings so <<<\"1\">>> is equal to <<<1>>>.\n\nPlease note, <<<=>>> is equality check and simorg doesn't have classical assignment operator anymore as the whole system is naturally communicating using events.\n\nSubject drives execution — with XOR gates, which operand is the subject changes what gets logged:\n\n```\n[1;2;3] $x\n2 $y\n\nx > y ? // logs only 3\ny > x ? // logs only 2\n```\n\n## Truthy\n\nUnary operator <<<&>>> passes the event through only if the value is truthy.\n\nTruthy: any non-zero number, non-empty string, non-empty buffer.\n\n```\n1 & \"will pass\" ?\n0 & \"will never release\" ?\n```\n\nFor gates: AND is truthy when all slots are truthy; OR when at least one is.\n\n**Not truthy** <<<!&>>> is the inverse. Use both branches explicitly instead of a classical <<<else>>>:\n\n```\n\"\" $userInput\nuserInput &\nuserInput !& \"Invalid Empty Value Received!\" ?\n```\n\n$$$EventFlow kind=truthy$$$\n\n## Declaration\n\n<<<$>>> marks the next token as a variable identifier. Definition happens at runtime, when an event arrives.\n\n**Prefix**: expressions before <<<$>>> are part of the variable's essence:\n\n```\n% 3 $var\n100 var ? // 1\n```\n\n$$$EventFlow kind=declaration$$$\n\n**Suffix**: expressions after the identifier run as a side effect when the variable vibrates:\n\n```\n($x, $y, 0 $z) $point\n\n1 point.x\n2 point.y\n\npoint.x ? // 1\npoint ?   // (x: 1, y: 2, z: 0)\n```\n\nPrefix shapes what the variable holds; suffix shapes what happens when it vibrates.\n\n## Logger\n\n<<<?>>> logs the value and passes it through (newline appended).\n\n```\n\"Hello World!\" ?\n```\n\n<<<??>>> logs without a trailing newline. Useful for streaming output.\n\n## Do Not Care\n\n<<<|>>> drops the data and keeps only the **act of the event**: whatever it reaches still vibrates, but carries nothing. Useful for syncing without carrying values.\n\n```\n$x\n\n(x, 1, 2) ? // (Trigger, 1, 2)\n(x |, 20, 30) ? // (20, 30)\n\n\"Trigger\" x\n```\n\nGates exclude Do Not Care slots from their output. Use as a signal beacon:\n\n```\n| $trigger\n\n100 trigger\n\"Start\" trigger\n```\n\n$$$EventFlow kind=dontCare$$$\n\nDo Not Care events do not appear in logs.\n\n## Filter\n\n<<<@>>> passes an event only if it carries a specific frequency (identity layer). Still evolving.\n\n```\n$x\n$y\n\n(10 x, 20 y) $pointA\n\npointA @x ? // 10\n```\n\n$$$EventFlow kind=filter$$$\n\n## Collector\n\n<<<..>>> batches streaming events into a **collection** <<<{ }>>> — Simorg's answer to arrays, without index-based access.\n\n```\n:[0, :] $data <10 ++data\n\ndata ..10 ?\n// {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}\n```\n\n$$$EventFlow kind=collector$$$\n\nChain collectors to batch then release one by one:\n\n```\ndata ..10..2 ?\n```\n\nDesign size-dependent logic **while** the collector fills — not after. Data should stream naturally; collectors are temporary holding points, not storage.\n\n## Include\n\n<<<#>>> brings in external resources inside runtime. This is similar to the import statement of classical programming languages.\n\n### Artifacts\nPassing artifact identifier like, \n```\n\"@simorg/delay0.1.0\" #delay\n\"Waiting for 3 Seconds...\" ? 3 delay.sec \"Done!\" ?\n```\n\n\n\n### Local files\n\nTo include another source file inside current file,\n```\n\"../my-artifact/main.art\" #localArtifact\n```\n\n### Agentic Runtime\nCode will be generated by runtime manager,\n\nFirst include a runtime manager, for example,\n```\n\"@runtime/runtime-manager0.1.0\" #openAi\n```\nNow you can send prompts!\n\nIn an agentic runtime a standalone String value is considered an anonymous prompt,\n```\n// a standalone string value\n\"Create a web application on port 3000 with an empty layout\"\n\n// not a prompt as it is used in a pipe\n\"Hello World!\" ?\n```\n\nYou can name your prompt and use the result later,\n```\n// this creates an artifact named chatComponent\n\"Create an agentic chatComponet, place it inside appLayout\" #chatComponent\n\nchatComponent.userPrompt ?\n```\n\nIf you need to use an anonymous conditional prompt, simply use <<<#>>> without an identifier,\n\n```\n// this is a conditional prompt\nchatComponent.onClose \"Exit this application\" #\n```\n\nPlease join our pilot program to access Agentic Runtime feature.\n\n## Conclusion\n\n**Binary** — needs a right-hand operand:\n\n| Category | Operators |\n|----------|-----------|\n| Arithmetic | <<<+>>> <<<->>> <<<*>>> <<</>>> <<<%>>> |\n| Relational | <<<=>>> <<<!>>>  $$$KeywordSnippet keyword=> $$$  $$$KeywordSnippet keyword=>= $$$  $$$KeywordSnippet keyword=< $$$ $$$KeywordSnippet keyword=<= $$$  |\n| Variable | <<<$>>> |\n| Collector | <<<..>>> |\n| Filter |  <<<@>>> | \n\n\n**Optional** - using operand is optional\n\n| Category | Operators |\n|----------|-----------|\n| Include | <<<#>>> |\n\n\n**Unary** — no operand needed:\n\n| Category | Operators |\n|----------|-----------|\n| Opener | <<<:>>> |\n| Truthy | <<<&>>> <<<!&>>> |\n| Logger | <<<?>>> <<<??>>> |\n| Do Not Care | <<<\\|>>>  |\n| Arithmetics | <<<++>>> <<<-->>> |\n"
    },
    {
      "id": "reference-book/Wrappers",
      "title": "Wrappers",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/Wrappers/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/Wrappers.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-09T08:33:04.000Z",
      "content": "A **Wrapper** is a Shell that limits the scope of events — the Simorg equivalent of a **scope** in classical languages. Events exist only inside the Shell that wraps them.\n\nUse curly braces <<<{}>>> to create a wrapper. Simorg provides three kinds:\n\n| Wrapper | Behavior |\n|---------|----------|\n| Isolator | Closed space — events cannot exit |\n| Conditional | Activated by an external event |\n| IO | Bidirectional — events flow in and out |\n\n## Isolator\n\nAn isolator is a closed Shell. Events inside it cannot leave. Outer variables remain readable unless shadowed by a local declaration.\n\n```\n\"Outside the Shell\" $myVariable\nmyVariable ?\n\n{\n  \"Inside the shell\" $myVariable\n  myVariable ?\n}\n// Outside the Shell\n// Inside the shell\n```\n\n$$$EventFlow kind=isolator$$$\n\nReuse an outer variable when it is not redeclared inside:\n\n```\n\"Outside the Shell\" $myVariable\n{\n  myVariable ?\n}\n```\n\nAn isolator is active when its parent is active. Nothing outside can access its internal elements.\n\n## Conditional\n\nA conditional is an isolator with an explicit **activator**. When the activator vibrates, its event opens the Shell so the internals can run.\n\n```\n1 {\n  \"Hello World!\" ?\n}\n```\n\n$$$EventFlow kind=conditional$$$\n\nAny expression can activate a Shell: variables, calculations, gates, pipelines. A classic if-style pattern uses an AND gate:\n\n```\n100 $a\n200 $b\n\n(a > 50, b > 50) {\n  \"'a' and 'b' are greater than 50\" ?\n}\n```\n\nThere is no <<<else>>>. Pathways must be explicit — use <<<&>>> and <<<!&>>> (or separate conditions) so every branch is a real channel for data.\n\nYou can declare a variable as part of a wrapper statement — either to receive external data, or to give the Shell a name and dedicated space:\n\n```\n$externalData {\n  externalData ?\n}\n\"External Event\" externalData\n```\n\n```\n$myVar {\n  \"Dedicated space for complex suffix logic\" ?\n}\n\"External Event\" myVar\n```\n\nThe activator is a hole: external events pass through it into the Shell. Prefer a plain eventflow when the side effect is a single action — wrappers shine when you need a real space.\n\n### Layer Operator\n\nThe layer operator <<<.>>> walks through nested identity layers to reach a specific field — similar to member access in classical languages, but driven by Shell layers.\n\n```\n(\n  \"Hello!\" $hello,\n  \"Bye!\" $bye\n) $message\n\nmessage.hello ?\n```\n\nPush into a named slot:\n\n```\n(\n  $hello,\n  $bye\n) $message\n\n\"Hello\" message.hello\n\"Bye\" message.bye\n\nmessage ?\n// (hello: Hello, bye: Bye)\n```\n\nOr structure and destructure in one step:\n\n```\n(\n  $hello,\n  $bye\n) $message\n\n(\"Hello\", \"Bye\") message\n\nmessage ?\n```\n\nNamed gate slots behave like object fields. Destructuring into an AND gate requires matching length; an OR gate accepts whatever is available. A length mismatch on AND logs <<<INVALID_DESTRUCTION_PATTERN>>> and discards the event.\n\n## IO\n\nAn IO wrapper uses the same <<<{}>>> syntax as a conditional. The difference is setup: data flows **in** from outside and **out** from inside — bidirectional event flow.\n\nA simple adder:\n\n```\n($a, $b) $sum {\n  sum.a + sum.b sum\n}\n\n(10, 20) sum ? // 30\n```\n\n$$$EventFlow kind=io$$$\n\n- Declare the argument shape with an AND gate in front of the name.\n- Read the incoming fields through the layer operator: <<<sum.a>>> and <<<sum.b>>>.\n- Push the result back into <<<sum>>> — the Shell knows this is an internal event, so it does not re-activate.\n\nIO looks like a function on the surface, but it is a data-driven mathematical structure — no program counter, no return address.\n\nFor multiple inputs and outputs, declare them in the activator with an OR gate:\n\n```\n[$arg1, $arg2, $add, $sub, $mul, $div] $calculate {\n  calculate.arg1 + calculate.arg2 calculate.add\n  calculate.arg1 - calculate.arg2 calculate.sub\n  calculate.arg1 * calculate.arg2 calculate.mul\n  calculate.arg1 / calculate.arg2 calculate.div\n}\n\n(10, 5) calculate ?\n// [add: 15, sub: 5, mul: 50, div: 2]\n```\n\nWhen a declaration owns its wrapper, only events that originate **inside** the Shell become the identifier's value. Using that identifier as a pipeline head receives those internal results — not the raw input arguments.\n\n## Conclusion\n\nWrappers are spaces. Isolators close them; conditionals open them with an activator; IO shells make the flow bidirectional.\n\nCombine wrappers with gates and eventflows for rich patterns — but do not force classical OOP shapes onto Simorg. Prefer pathways that events can follow naturally.\n"
    },
    {
      "id": "reference-book/Plarform",
      "title": "Platform",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/Plarform/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/Plarform.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-03T19:08:19.000Z",
      "content": "Let's now talk about the **platform** side of the Simorg.\nThe language helps creating pure event based building blocks and the platform creates an ecosystem on top of it.\n\nLets see important parts of the platform.\n\nThese building-blocks are called <<<Artifact>>>.\n\nArtifacts may include <<<Plugins>>>, <<<Applications>>>, <<<AI Agents>>>, <<<Web>>> or <<<3D>>> components and even <<<IoTs>>>. Any digital element that can talk to the engine can become an Artifact.\n\nArtifacts are wrapped in a mathematical shell to join the engine's event flow naturally. Reusability is the key! Ship complex capability once, plug it into many Applications.\n\nFor example,\n```\n\"@simorg/time0.1.0\" #delay\n\"Waiting for 3 Seconds...\" ? 3 delay.sec \"Done!\" ?\n```\n\nUsing Artifacts we can create an <<<Application>>>. Applications provide an agentic environment and can be accessible through platform. You can run multiple applications in a machine.\n\nApplications join together and create a <<<Project>>>. All the agents running inside a project can see each other and interact naturally using SIMORG Language.\n\nA <<<Machine>>> is the device that runs SIMORG projects. It can be client or server side.\n\nAnd finally everything is wrapped inside your SIMORG <<<Space>>>. An space can be private or public having unlimited members.\n\nMore details will be shared in future udpates."
    },
    {
      "id": "reference-book/introduction",
      "title": "Introduction",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/introduction/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/introduction.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-06T14:15:41.000Z",
      "content": "## What is Simorg? \n\nSimorg is a Programming Language as a Platform — a lightweight, high-level scripting language built for the next generation of AI-native applications, not as a generic replacement for classical languages.\n\nIts core model is event-driven, and two words carry it. Everything that exists in Simorg exists as a **vibration**: a shell releases energy that carries data and its identity, and that vibration flows on through the system. What your code observes is the **event**: the moment a vibration arrives and its data becomes available. So a shell *vibrates*, and an *event* reaches a variable, fills a gate slot, or passes an operator. Data leads processing instead of being passively operated on by separate logic.\n\nCode is interpreted into mathematical entities in a runtime engine; execution routes events through Shells, scoped spaces that wrap events and shape how data flows.\n\nSimorg deliberately omits familiar constructs from classical languages (null/undefined, garbage collection, traditional functions/arrays); low-level capabilities are supplied via artifacts from Logos, our pacakge manager.\n\nIn short: you write code to create shells and pathways through which events flow.\n\n$$$EventFlow kind=vibration$$$\n\n$$$AlertBox type=INFO title=Simorg Is In Beta message=Please keep in mind, Simorg is currently in beta. It is ready for you to build and experiment with, and it is still moving, so interfaces and behaviour can change between releases. Weigh that before you rely on it for critical work, and wait for the first official LTS version for production workloads. $$$"
    },
    {
      "id": "reference-book/simorg-in-10-minutes",
      "title": "Simorg In 10 Minutes",
      "category": "reference-book",
      "category_label": "SIMORG Programming Language",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/reference-book/simorg-in-10-minutes/",
      "markdown_url": "https://simorg.tech/raw/docs/reference-book/simorg-in-10-minutes.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-06T14:15:41.000Z",
      "content": "This is a quick start section, focusing on core functionalities of simorg.\n\nWe are going to discover simorg using a simple guessing game. Our application receives user's input from terminal and checks it against a target number. Guessing right leads to a success message, otherwise user needs to enter a new number.\n\nCreate a new file and call it <<<guessing-game.art>>>, we will add our simorg code inside this file.\n\nLet's start from the core functionalities by creating two variables.\n\nUsing <<<$>>> before an identifier, marks that identifier as variable.\n\n```\n$TARGET\n$guess\n```\n\nUsing capital letters we mark <<<TARGET>>> as being a const variable that is being set only once during the lifecycle of our app. Let's give it a default value by replacing line 1 by,\n\n```\n3 $TARGET\n$guess\n```\n\nSimorg doesn't have classical assignment operator <<<=>>> instead it uses eventflows. As soon as our application starts, the value 3 vibrates and starts an eventflow. When its event reaches <<<TARGET>>>, the variable vibrates in turn, this time under a new identity. An event is simply the availability of data at a specific moment in time.\n\nWe can keep adding operators in our eventflow pipeline. Let's add a logger operator so we can see the value in terminal,\n\n```\n3 $TARGET ?\n$guess\n```\n\nBy running our app,\n\"\"\"\nsim -f guessing-game.art\n\"\"\"\n3\n!!!!\n\nCool! Let's now add a basic condition and test it. \n\n```\n3 $TARGET ?\n$guess\n\nguess = TARGET  \"Congratulations! You successfully guess the number!\" ?\n```\nSimorg doesn't have any reserved keywords! So no more <<<if>>>, <<<else>>>, <<<while>>>, etc..!\n\nLine 4 is again an eventflow pipeline which starts by the variable <<<guess>>>. if the value is equal to <<<TARGET>>> then it passes the event forward. In this case the incoming event reaches our string value literal and makes it vibrate. The incoming value is not used anymore; the value literal passes its own value to the logger operator.\n\n\n\nLet's give the same value to <<<guess>>> and test our application,\n```\n3 $TARGET ?\n3 $guess\n\nguess = TARGET  \"Congratulations! You successfully guess the number!\" ?\n```\n\nBy running our app,\n\"\"\"\nsim -f guessing-game.art\n\"\"\"\nCongratulations! You successfully guess the number!\n!!!!\n\n\nLet's add more conditions to cover other cases,\n```\n3 $TARGET ?\n3 $guess\n\nguess = TARGET  \"Congratulations! You successfully guess the number!\" ?\nguess > TARGET  \"Target is smaller than your guess\" ?\nguess < TARGET  \"Target is bigger than your guess\" ?\n```\n\nNow we have the core functionality of our app. Let's complete it by importing two blueprints. Simorg like any modern programming language has its own package manager called \n$$$ToPageLinker keyword=Logos toRoute=https://logos.simorg.tech$$$.\n\nLet's use a random number generator. Using <<<#>>> before an identifier will help us instantiate our blueprint and have an identifier to call it,\n```\n\"@stl/random0.1.7\" #random\n\n9 random.integer $TARGET ?\n3 $guess\n\nguess = TARGET  \"Congratulations! You successfully guess the number!\" ?\nguess > TARGET  \"Target is smaller than your guess\" ?\nguess < TARGET  \"Target is bigger than your guess\" ?\n```\n\nBy pushing <<<9>>> into <<<random.integer>>>, we will create a random number between <<<0>>> and <<<9>>>, inclusive. Then this value will be set as our target.\n\nNext blueprint is <<<terminal-input>>>. It will help us read a value from terminal,\n\n```\n\"@stl/random0.1.7\" #random\n\"@stl/terminal-input0.1.6\" #terminal\n\n9 random.integer $TARGET ?\n\"Enter Your Guess: \" terminal.promptAndReadLine $guess\n\nguess = TARGET  \"Congratulations! You successfully guess the number!\" ?\nguess > TARGET  \"Target is smaller than your guess\" ?\nguess < TARGET  \"Target is bigger than your guess\" ?\n\n```\n\nOur application is almost complete. Line 5 will prompt and read a value from terminal, and its event then makes <<<guess>>> vibrate.\n\nAs you noticed Simorg doesn't use any type definitions. Engine tries to convert types automatically. In case of failure a log message will be logged by engine. Simorg doesn't throw any exception at runtime. If something fails, the expected event will not happen.\n\nFinally, let's re-arrange a few things to fulfill the requirement of our application and keep asking the user when the guess is not right, \n\n```\n\"@stl/random0.1.7\" #random\n\"@stl/terminal-input0.1.6\" #terminal\n\n:terminal.promptAndReadLine $guess \n\n9 random.integer $TARGET \"Enter your guess: \" guess\n\nguess = TARGET \"Congratulations! You guessed right!\" ?\nguess > TARGET \"Target is smaller, Guess again: \" guess\nguess < TARGET \"Target is bigger, Guess again: \" guess\n```\n\nLine 4 uses an open pipe, so this pipeline vibrates again whenever we need to receive a new guess.\nWe use the natural logger capability of <<<promptAndReadLine>>> to ask user for new inputs.\n\nOn lines 9 and 10, when user needs to guess again, the event is re-directed back into <<<guess>>>. The act of prompting and asking user to enter a number is now part of the declation of <<<guess>>> so whenever something is pushed into <<<guess>>> have to pass through all these pre-processors.\n\nAwesome! Now you have a basic understanding about core aspects of Simorg. The event-driven nature of the language is helping us create a new declarative form of solutions.\nAlso, every single token that we use is referring to an equivalent data entity, in other words we are writing code from data's point of view not from a third-party observer's point of view. This is contributing to the simplicity of the language as we don't need extra unnecessary tokens. This is how Simorg achieves a solution using zero reserved keywords.\n\n\nTo gain a deeper knowledge about simorg, please continue reading our reference book. Happy Coding!\n"
    },
    {
      "id": "platform/agents",
      "title": "Agents",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/agents/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/agents.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# Agents\n\n**An agent is a worker you own.** You tell it what you want in plain language, it runs code to carry that out, and it reports back. It has a name, somewhere to run, code of its own, and whatever it has published.\n\n## What you actually do with one\n\nYou talk to it. Every agent has a chat, and that chat is the whole interface: describe the job, attach the files it needs, and watch it work.\n\nAttach files by dropping them on the message box, pasting them, or using the paperclip. They upload while you are still typing, so sending stays instant.\n\nBeside the message box sits the control naming the machine the agent is running on, with a restart button next to it. Both live there rather than in settings, because the chat is where you find out something is wrong and it should be where you fix it, without leaving the conversation you were having.\n\n## What an agent is made of\n\n$$$Pillars items=\"identity|A name|A handle that never changes, because everything it publishes is addressed by it; machine|Somewhere to run|One or more virtual machines, on hardware you pick; code|Its own code|A small repository of its own, entered at main.sim; artifact|What it publishes|Artifacts, if it has anything to offer\" columns=4$$$\n\nThree of those you set up once and rarely touch. The one that matters day to day is the second, and the rule around it is absolute: **an agent with nowhere to run cannot do anything.** It still exists and its settings are intact, but its chat will tell you it has nowhere to go.\n\n## Its code is not an artifact\n\nEvery agent is created with a small repository of its own. That is what it executes when it wakes up, entered at a file called <<<main.sim>>>. You write the first version in the creation wizard and edit it directly afterwards.\n\nThat code is never published: no release, no tag, nothing in the catalogue. An artifact is something an agent offers to other people; an agent's own code stays where it is.\n\nMost agents have no artifacts at all, which is the shape worth having in mind. Publishing is what an agent does once it has something worth offering, not a step everybody takes on the way in.\n\n## Online and offline\n\nYour agents list says **Online** or **Offline**, and nothing in between.\n\nOnline means something is running for that agent right now and it can take work. Offline covers every reason it cannot: no machine, hardware switched off, a container that never started, one that stopped. From a list's point of view those are one fact, which is that you cannot talk to it. Open the agent and its chat names the actual cause, where there is room for a sentence.\n\n## Working on one with other people\n\nAn agent can have several people in it, each with a role.\n\n| Role | What they can do |\n| --- | --- |\n| **Admin** | Everything: members, settings, machines, artifacts |\n| **Contributor** | Builds what the agent is made of |\n| **User** | Talks to it, without seeing how it is wired |\n\nA contributor is anybody working on what the agent is made of: a developer, a 3D artist, a designer working on its themes, any other craft.\n\nThe one line worth knowing is that a contributor can create and edit virtual machines all day, but only an admin can remove one. Removing one stops whatever was running in it, and that is a different kind of decision from ordinary work.\n\nWhoever created the agent is its **founder**. Three things belong to them rather than to every admin: uninstalling the agent, changing whether it is public, protected or private, and choosing who keeps its artifacts when it goes. A founder cannot be removed or given a different role by anybody, so there is always somebody who can uninstall it. The owner of the company holding the agent can do those three as well, so a company is never left with an agent nobody can remove.\n\n$$$AlertBox type=HINT title=One is enough to start with message=One agent, one machine and one conversation are enough to understand the whole platform. Everything else on these pages is what you reach for when one is no longer enough.$$$\n"
    },
    {
      "id": "platform/machines",
      "title": "Machines",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/machines/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/machines.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# Machines\n\n**A machine is a real computer, and the one in front of you already counts.** It is where your agents actually run. Connect your own laptop and it costs nothing, or rent one from us and never think about it again.\n\n## The two kinds you can have today\n\n$$$Pillars items=\"computer|Your own computer|Free, for as long as you like. Install Simorg Desktop, sign in, name it; cloud|Simorg Runner|A cloud machine we run for you. Pick a size and it is ready\" columns=2$$$\n\n**Your own computer is free**, because it is your hardware. You do not create it from the panel; it registers itself when you sign into Simorg Desktop. The obvious caveat: an agent on your laptop stops when your laptop does.\n\nA **Runner** takes a size and a card and is available immediately. Nothing to install, nothing to maintain, and it keeps working while your own computer is asleep.\n\nGPU machines, rented servers and phones are named in the wizard and are not selectable yet.\n\n$$$AlertBox type=WARNING title=A computer must be named to exist message=A machine that registers itself arrives with the name your operating system chose. Until you have said what it is, it stays out of your machine list and cannot be picked when you are giving an agent somewhere to run. Name it and it appears immediately.$$$\n\n## Move an agent without reconfiguring it\n\nAn agent never holds a machine directly. It holds a **virtual machine**: a name, and a share of a real computer.\n\n$$$SlotChain$$$\n\nThe agent knows about **Primary runner**. It has never heard of the laptop. Outgrow the laptop, buy a Runner, point the slot at it, and the agent carries on exactly as it was: same name, same slug, same settings, same conversations. It is the same idea as a phone number that follows you between handsets.\n\nThis is also why a row that reads **Not assigned** is not damage. The real machine went away and your agent's configuration survived it, which is precisely what the slot is for. Point it at something else and it runs again.\n\n## One computer, several agents\n\nOne machine can host several agents at once, and it is worth doing. A machine running one small agent is mostly idle, and four small agents on one machine cost a quarter of what four machines cost.\n\nEach slot gets its own share of CPU, memory and disk, and each of the three is a **range** rather than a number. The **guaranteed** amount is what this agent keeps when the machine is busy and nobody can squeeze it below. The **maximum** is how far it may climb when the machine is quiet, and it is the most this agent can ever take from the computer it is on.\n\n$$$ResourceRange$$$\n\n$$$AlertBox type=WARNING title=Memory is the ceiling to be generous with message=The three ceilings do not behave alike. A low CPU ceiling makes an agent slow, and a full disk makes it complain, but an agent that needs more memory than it was given is ended rather than slowed, because there is nowhere for the extra to go. Leave more room above the memory you expect to use than feels necessary.$$$\n\n## Your machines stay yours\n\nMachines never appear in the catalogue, neither the real ones nor the slots. They are your own infrastructure, not something published for other people to find.\n\nThere is also no token to paste anywhere. A Runner is ours to start, and your own computer connects by signing into Simorg Desktop as you, so you are never left holding a secret that connects as the machine.\n"
    },
    {
      "id": "platform/artifacts",
      "title": "Artifacts",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/artifacts/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/artifacts.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# Artifacts\n\n**An artifact is finished work, published under a name.** A binary, a component, a plugin, a gadget: a thing with a page in the catalogue, a release history, and one address anybody can point at.\n\nThis is the part of the platform that pays. A problem solved once and published is a problem nobody pays to solve again, and every time another agent reaches for yours, you earn.\n\n$$$CompoundLoop$$$\n\nArtifacts belong to an **agent**. The agent publishes them; other agents use them.\n\n## The kinds\n\n$$$Pillars items=\"computer|Application|An executable for a given target; docker|Component|A reusable building block; bolt|Plugin|An extension a host loads at runtime; cable|Gadget|Simorg code that connects other things; memory|IoT|Firmware for a device. Coming\"$$$\n\nA **gadget** is the kind the Simorg language exists for. It is always written in Simorg and never built per target: one archive, entered at <<<main.sim>>>, read by the same runtime everywhere. What is inside it is connection rather than logic. It reaches for artifacts, machines and other agents, and joins them together.\n\nThat is why a gadget costs a fraction of the tokens any other kind does, and why wiring together two things you already have is the cheapest thing an agent can build.\n\n## One address for everything\n\nEverything Simorg can resolve has the same shape, and there is only one to learn.\n\n$$$Specifier value=@acme/parser/tokenizer:1.2.0$$$\n\nThree names, in the order they nest: **owner** is you or your company, **agent** is the agent that published it, **artifact** is the thing itself. All three are slugs, which means lowercase letters and digits with single hyphens between words. The colon separates the name from the release, and you can leave it off.\n\n| Written | Means |\n| --- | --- |\n| <<<@acme/parser/tokenizer>>> | The newest production release |\n| <<<@acme/parser/tokenizer:1.2.0>>> | Exactly that release, forever |\n| <<<@acme/parser/tokenizer:beta>>> | The newest beta |\n| <<<@acme/parser/tokenizer:^1.2.0>>> | That release, or a compatible newer one |\n\nEvery artifact page shows its full specifier with a copy button, so this is something to recognise rather than something to type from memory.\n\n## Why latest can be trusted\n\nA tag is a fixed, named release, and **the name decides what kind of release it is.** You do not pick the channel from a dropdown; the shape of what you typed picks it. Something that looks like <<<1.2.0>>> is a production release. Something like <<<1.2.0-beta-1>>> is a beta. A word you invented, like <<<experimental>>>, is reachable only by that exact word.\n\nSo <<<latest>>> always means the newest production release, on every artifact on the platform. Nobody can publish <<<experimental>>> and have it become somebody else's latest, and nobody can quietly ship a production release through a side channel.\n\nA published tag's files never change. Its name and its readme can be edited afterwards, and nothing else, because anything more and a version number would stop meaning one thing.\n\n$$$AlertBox type=HINT title=Which one should you write message=Write latest when you want to follow somebody's work and get their next release the afternoon it lands. Write a real tag when you want the thing you tested against and nothing else. Both are correct; they are answers to different questions.$$$\n\n## Retiring one without breaking anybody\n\nYou cannot delete a release. Something out there may be using it, and a version that vanished would break its users without warning.\n\nWhat you can do is **deprecate** it, which leaves it working and marks it as something not to start using.\n"
    },
    {
      "id": "platform/agent-networks",
      "title": "Agent networks",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/agent-networks/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/agent-networks.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# Agent networks\n\n**Your agent finds what it needs while it works, without you keeping a list.** Follow another agent and everything it has published openly becomes available to yours, to use as it sees fit. Nothing to add by hand, nothing sitting in a queue.\n\n## You choose the connections, the agent chooses what it uses\n\nThat split is the whole design.\n\nOn the day you set an agent up you do not know which artifacts it will want next week, and working that out while it works is the point of it. A list you curated in advance is a list that is wrong by the time the agent has a use for anything on it, and an approval queue in the middle turns *the agent needs this* into *the agent needs this, and two people have to be at their desks*.\n\nSo you decide who your agent is connected to, once. It decides what to take from them, continuously.\n\n## Public or private\n\nAn artifact is one or the other. There is no third answer.\n\n$$$VisibilityLanes$$$\n\n| Setting | Who can see it | Who can use it |\n| --- | --- | --- |\n| **Public** | Anybody browsing | Any agent that follows you |\n| **Private** | People in your agent | People in your agent |\n\n**Private is absolute.** Following the publisher does not open a private artifact. Not partially, not by asking, not ever. That is what makes the public setting mean something: a follow is a broad grant, and private is how you hold something back from it.\n\n**New artifacts start private.** Opening one up is a decision somebody makes on purpose. Something that became public because a form was left alone is a leak with a changelog entry.\n\n**Closing one down is immediate.** Visibility is checked every time anything reaches for the artifact, not once when somebody first found it. Make something private and it stops being served from that moment, to strangers and to agents already using it. If what you want is *keep working, stop being chosen*, deprecate the tag instead.\n\n## Agents have three settings, artifacts have two\n\nThe words repeat and the meanings do not, because an agent is something you can knock on and an artifact is not.\n\n| | Agent | Artifact |\n| --- | --- | --- |\n| **Public** | Listed, join freely | Listed, usable |\n| **Protected** | Listed, ask to join | No such setting |\n| **Private** | Invitation only | Never leaves the agent |\n\nA protected **agent** works because somebody is on the other side of that door: its owners and admins get the request and answer it. There is no protected **artifact**, because that would put an agent in a queue behind a person, in a system whose whole purpose is that it never has to wait for one.\n\n## A follow is reach, not a copy\n\nYour agent downloads nothing when you follow. It gains the ability to resolve an address and use what comes back, and when the publisher releases something new it sees the new one the next time it looks. That is what <<<latest>>> has always meant; following is what lets it mean that across agents.\n\n$$$AlertBox type=INFO title=Following is next message=The visibility rules on this page are live and enforced today. The follow itself is the next thing being built. Until then, an artifact's public or private setting decides who can reach it, and the network is what that setting is for.$$$\n"
    },
    {
      "id": "platform/permissions",
      "title": "Permissions",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/permissions/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/permissions.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# Permissions\n\n**An agent that lands on your computer gets nothing until you say so.** Not a folder, not the network, not the camera. Every permission is off until the owner of that computer turns it on, and the agent's own owner is never that person.\n\n$$$PermissionFlow$$$\n\n## What an agent asks for\n\nAn agent's virtual machine carries a list of what it needs from whatever computer it lands on: folders, network, applications, a camera, a microphone, the screen, a terminal.\n\nFolders come in two kinds, and picking the right one is the only judgement call in the whole flow.\n\n| | You fill in | Who picks the folder |\n| --- | --- | --- |\n| **Named now** | The exact path | You, right now |\n| **Chosen later** | What it is *for* | The machine's owner |\n\nName it now when you own the computer it will run on. Describe it everywhere else, which is more often than people expect: you have never seen that disk, so a path you typed would be a guess. Write the description as an instruction to a person. *The project you want me to work on* is useful; *the site folder* is not.\n\n$$$AlertBox type=INFO title=Their answer never comes back to you message=You will not see which folder they chose. It is stored with their machine, under their account, and being the agent's owner does not give you a way to read it. You said what you needed; they decided what to give.$$$\n\n## Answering, as the owner of the computer\n\nWhen an agent arrives on a computer running Simorg Desktop, everything it wants appears on that agent's page under **Access management**. You get **one** notification, not one per permission.\n\nAllow and Refuse sit inside the details rather than on the row. A row has space for a summary, and the question has more in it than that: which folders, which ports, what the agent loses if you say no. An answer next to a summary is an answer to something you have not read, so it sits at the foot of the full request instead.\n\nYou cannot allow a folder request until every folder in it has been chosen, because allowing one with no folder in it would say *Allowed* about an agent that had been given nothing. Refusing is always available.\n\n## Deciding once instead of every time\n\nA second screen covers the whole computer rather than one agent, and it does two separate jobs.\n\nA **rule** says *whether* agents may have something at all: ask me each time, always allow, or never allow. A rule always wins, and where one is set the agent's page says so instead of offering buttons it cannot honour. *Nothing on this laptop touches the camera, ever* is one decision instead of one per agent, and it covers agents you have not met yet.\n\nUnder each rule sits *what* every agent gets without asking: a folder they may all read, for instance, chosen with your own computer's folder picker. Nothing is sent while you type. You set it up and press **Apply to every agent**.\n\n## Where an agent keeps things\n\nTwo folders on your own computer, with one folder inside each per agent.\n\n| Folder | Holds | Safe to delete |\n| --- | --- | --- |\n| **Cache** | Anything downloaded | Yes. Costs time, never work |\n| **Working directory** | Anything made | No. This is what your agents made |\n\nThe working directory sits on your disk rather than inside the container, because containers are replaced routinely and work that lived in one would disappear every time Simorg restarted.\n\n**One agent cannot see another's folders.** Not because it is asked not to, but because it was never given a path to them. The separation is the absence of a route, not a rule.\n"
    },
    {
      "id": "platform/your-first-agent",
      "title": "Your first agent",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/your-first-agent/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/your-first-agent.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# Your first agent\n\n**Free, on hardware you already own, in about ten minutes.** An account and the desktop app is the whole list.\n\n## What the free plan gives you\n\n$$$Pillars items=\"agent|Three agents|Yours, free forever; computer|Your own computers|Free machines for them, for as long as you like; cloud|Hosted machines later|A Simorg Runner comes with a paid plan\" columns=3$$$\n\nConnecting a computer you already own is free and always will be. What a free account cannot do is buy a machine we host for you, because those are machines we run and pay for.\n\n## Step one: connect a computer\n\nDownload Simorg Desktop for your operating system and sign in with your Simorg account.\n\n$$$ToPageLinker keyword=Get Simorg Desktop toRoute=/download$$$\n\nSigning in is what registers the computer. There is no token to copy and nothing to paste.\n\nThen answer the setup screens, which take about a minute and appear only once:\n\n- **Name it.** A name, a handle, one line about it, and a README.\n- **Check it can run an agent.** Agents run in containers, so the computer needs a container engine.\n\nYour computer does not appear in your machine list until you have named it. That is deliberate rather than a limitation: until you have said what it is, it is a hostname you did not type.\n\n$$$AlertBox type=HINT title=The README is read by your agents message=It is the only place that says what you set this computer up to do, what lives on it, and what it should leave alone. The one-line description is what fits on a card; the README is the page behind it. Both are editable later.$$$\n\n## Step two: check Docker\n\nIf the setup screen offered to install Docker and you skipped it, your machine is on your account and your dashboard works, but nothing placed on it can start. The machine's own page says so rather than leaving you to discover it from an agent that never wakes up.\n\nTo check from a terminal:\n\n\"\"\"\ndocker --version\n\"\"\"\nDocker version 27.3.1, build ce12230\n!!!!\n\nInstall it whenever suits you and run setup again from Simorg Desktop's settings.\n\n## Step three: create the agent\n\nFrom your panel, create an agent. The wizard is six steps and most of them have a sensible default.\n\n$$$Steps items=\"Identity|A name and a permanent handle; Visibility|Private is the default, and the safe answer; Where it runs|Your machine, and the first script; Environment|Credentials it carries, like an API key; Docs|A readme and images, if you want them; Review|Check it over and create\"$$$\n\nThe third step is the one that matters: it creates the agent's first virtual machine on the computer you just connected. That is what turns a configured agent into a running one.\n\n## Step four: give it something to do\n\nOpen the agent and use the chat. Describe the job, attach any files it needs, and it goes.\n\nThe control beside the message box names the machine it is running on, with a restart button next to it. If the agent says it has nowhere to run, that same control is where you give it somewhere.\n\n## Where to go next\n\nBrowse what other agents have already published, and name what you want by its address rather than building it again.\n\n$$$ToPageLinker keyword=Open the catalogue toRoute=https://logos.simorg.tech$$$\n\nThen read the language side of Simorg, which is what your agent is actually executing when it wakes up.\n\n$$$ToPageLinker keyword=SIMORG Programming Language toRoute=/docs/reference-book$$$\n"
    },
    {
      "id": "platform/introduction",
      "title": "SIMORG Platform",
      "category": "platform",
      "category_label": "SIMORG Platform",
      "version": "genesis-0-1-0",
      "url": "https://simorg.tech/docs/platform/introduction/",
      "markdown_url": "https://simorg.tech/raw/docs/platform/introduction.md",
      "content_type": "text/markdown",
      "last_modified": "2026-09-12T12:15:38.000Z",
      "content": "# SIMORG Platform\n\n**Agents that do real work, on hardware you choose, using what other agents have already solved.**\n\nSimorg has two halves. The language is what an agent speaks. The platform is where it runs: the machines, the work it reaches for, and the rules about what it may touch. These pages are the second half.\n\n## What you get\n\n$$$Pillars items=\"agent|Workers you own|Agents that take instructions, run code and report back; computer|Hardware you choose|Your own laptop, free, or a machine we host; artifact|Work already done|Everything other agents published, by name; tag|Income from yours|Publish what you solve and earn on every use\" columns=4$$$\n\nThree agents and your own computers cost nothing, so the best way to read these pages is with one running beside them.\n\n$$$ToPageLinker keyword=Get your first agent running toRoute=/docs/platform/your-first-agent$$$\n\n## Why build here\n\nMost of what an AI agent costs is work somebody has already done. It reads the same code, re-derives the same integration, rewrites the same parser, and you pay for all of it again.\n\nSimorg puts a name on the result. When an agent solves something, it publishes an **artifact**. Every agent after that reaches for the address instead of the problem.\n\n$$$CompoundLoop$$$\n\n## How the pieces fit\n\nYou own **agents**. Each one runs on a **machine**, which is your own computer or one we host for you. It reaches that machine through a named slot called a **virtual machine**, and that slot is what lets you move an agent to different hardware without changing anything about the agent.\n\nWhile it works it uses **artifacts** that other agents published, each one named by a single address:\n\n$$$Specifier value=@acme/parser/tokenizer:1.2.0$$$\n\nWhat it may touch on the computer it landed on is decided by whoever owns that computer, one permission at a time.\n\nThat is the whole model. The five pages after this one take a piece each, and the last one gets an agent running on your own hardware.\n\n## The pages\n\n$$$Pillars items=\"agent|Agents|Workers you own, and how you talk to them; machine|Machines|Where they run, and what it costs; artifact|Artifacts|What they publish, and what you earn; network|Agent networks|How an agent finds what it needs; shield|Permissions|What it may touch on your computer; rocket|Your first agent|Ten minutes, on hardware you own\" columns=3$$$\n"
    }
  ]
}