From bd965b6397fa37b643d164e42fd1949cbf0f45da Mon Sep 17 00:00:00 2001 From: alakanani Date: Tue, 17 Nov 2026 20:24:20 +0200 Subject: [PATCH 1/2] Publish llms.txt: God Code, readable by AI systems The standard file that teaches chatbots and agents what God Code is and how to write, check and safely run it. Placed at the repo root and at getgodcode.com/llms.txt so any AI system that comes looking finds one true, canonical account: install, the check/run JSON loop, language essentials, declared intent, permission manifests, tongues, error codes, the tool bridge and safety rules. --- llms.txt | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++ site/llms.txt | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) create mode 100644 llms.txt create mode 100644 site/llms.txt diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..5ba938f --- /dev/null +++ b/llms.txt @@ -0,0 +1,128 @@ +# God Code + +> God Code is a programming language that reads like scripture. Write real software in words of faith, in your own language, and watch it run. Human-readable, safe, and built for humans and AI creating together. Created in Botswana, open to the world. + +This file teaches an AI model how to write, check, and safely run God Code. A God Code program is called a scroll and lives in a .god file. Everything here is the working truth of the engine: prefer the commands below over guessing, and prefer the JSON output over scraping prose. + +## Install + +Install the engine and CLI: + + pip install godcode-engine + +Confirm the CLI answers: + + godcode --help + +From a source checkout, `pip install -e .` gives the same `godcode` command. + +## The safe workflow + +Follow this loop every time you work with a scroll. + +1. Generate the scroll. Every program needs BEGIN CREATION ... END CREATION. Nothing outside that block runs. +2. Read before you run. `godcode explain scroll.god --json` reports static facts about a scroll (its tongue, rites and their intents, names, reveals, seals, summons, consults, imports, permissions) and executes nothing. Use it on any scroll you did not write. +3. Check. `godcode check --json scroll.god` returns one JSON document: {"tool":"godcode","command":"check","file":...,"ok":true|false,"diagnostics":[{line,col,code,severity,message,hint}]}. Exit 0 means pure, exit 1 means diagnostics, exit 2 is a usage error. Line and col are 1-based; col may be null. Fix every diagnostic before running. +4. Run safely. `godcode run --sandbox --json scroll.god` returns {"tool","command","file","ok","output":[...],"seals":[{block,hash}],"error":{...}|null,"stats":{"ms":...}}. The output array holds every line printed during the run (REVEAL lines plus engine notices such as [SEAL] and [INTENT]). On a runtime error, output holds the lines revealed before the error, and error carries line, col, code, and message. The report also carries an intents array and a permissions block, described below. +5. Iterate until check is clean and the run reveals what you intended. + +Never run an untrusted scroll without --sandbox. The sandbox confines execution: no files, no network, no subprocesses, with time and step limits. + +A minimal scroll, to prove the loop: + + BEGIN CREATION + DECLARE name AS "world" + REVEAL("Hello, {name}. Grace upon grace.") + END CREATION + +`godcode check --json hello.god` answers ok: true, and `godcode run --sandbox --json hello.god` reveals "Hello, world. Grace upon grace." + +## Language essentials + +- Assignment is `DECLARE x AS ...`. There is no other assignment form. +- Output is `REVEAL(expr)`. The language is input-free; there is no stdin. +- Comparisons use IS and IS NOT (== and != also work). IF takes THEN: `IF n IS 3 THEN`. +- Strings breathe values in: "grace upon {name}" interpolates any expression, including {a * b} and {UPPER(name)}. To write a literal brace, double it: "{{" writes { and "}}" writes }. +- Comments start with # and run to end of line. +- Keywords are case-insensitive. Canonical style is UPPER. +- Blocks close explicitly: ENDIF, ENDFOR, ENDWHILE, END RITE. +- FOR walks a list or a range: `FOR i IN RANGE(1, 6)`. +- A rite is a function: `DEFINE RITE name(params)` ... `END RITE`, invoked with `INVOKE name(args)`. Rites support parameters, RETURN, and closures. +- ASCEND ends a run peacefully. It is not an error. +- An unbound name evaluates to a Symbol and does not raise. This is the Symbol Rule: `IF seeker IS worthy THEN` works because worthy is a symbol. But `BREATHE LIFE INTO` an undeclared name does raise at runtime. +- Division by zero is rejected: "division by nothing is not permitted". +- Error messages may end with "Did you mean 'X'?" for a misspelled rite, variable, bless target, or map key. Take the hint. + +## Seals, anchors, and pure tools + +- `SEAL(expr)` appends a tamper-evident, hash-chained covenant block to the ledger. `godcode ledger verify` attests the covenant chain and the anchor chain. +- `ANCHOR(expr [, chain])` anchors a value's hash on a chain and returns a receipt map {chain, anchor_hash, height, timestamp, payload_hash}. Index it like receipt["anchor_hash"]; TYPE(receipt) is "map". The default chain is `simulated`, a local genesis-anchored chain. +- `SHA256(x)` fingerprints a word, number, or truth as 64 hex characters. `HMAC(key, message)` seals a message under a key (HMAC-SHA-256). `BASE64_ENCODE(x)` and `BASE64_DECODE(s)` veil and unveil words. All four are pure: they need no import and run unchanged under --sandbox. +- `CONSULT("question")` asks the local Spirit oracle. It answers in two or three sentences, works in the sandbox, and never fails the run. + +## The commons + +Everyday tools, always present, pure, and sandbox-safe. Words: TRIM, REPLACE, STARTS_WITH, ENDS_WITH, SUBSTRING, CONTAINS, COUNT, REPEAT. Lists: SORT (returns a new list), MIN_OF, MAX_OF, SUM_OF, FIRST, LAST, UNIQUE, INDEX_OF (returns -1 when absent). Maps: KEYS, VALUES, HAS_KEY, MERGE (returns a new map). Numbers: ABS, ROUND (half away from zero), FLOOR, CEIL, SQRT, POW. REPEAT(s, n) is a word function, not a loop. + +## Declared intent + +A rite can carry its purpose in plain words: + + DECLARE INTENT "bring peace to the household" ON morning_blessing + +At invocation, the engine discerns whether the rite's words still walk in its declared intent. The run report's intents array carries one entry per invoked rite with an intent: {declared, discerned, confidence, aligned}. Alignment is blessed; drift is counseled gently and can never fail a run. When you generate a rite, declare its intent, and after each run check the intents array for drift. + +## Permission manifests + +A scroll should declare what it may touch, at the top inside BEGIN CREATION: + + DECLARE PERMISSION TO READ "data/" + DECLARE PERMISSION TO WRITE "out/" + DECLARE PERMISSION TO SPEAK WITH "api.example.com" + DECLARE PERMISSION TO ASK THE WORLD + DECLARE PERMISSION TO SUMMON "reports.weekly" + +Any rite that reaches for an undeclared power is stopped. The manifest never widens the host policy: --sandbox still narrows everything. Read a scroll's manifest without running anything: `godcode permissions --json scroll.god`. The manifest is a promise; the sandbox is the wall. Keep both. + +## Tongues: write keywords in your own language + +A scroll may open with a tongue pragma and write its keywords in that language. English keywords still work in the same file. + +- `# tongue: tn` is Setswana: SIMOLOLA (BEGIN), SENOLA (REVEAL), FA (IF), FEDISA (END). +- `# tongue: zu` is isiZulu: QALA (BEGIN), VEZA (REVEAL), UMA (IF). +- `# tongue: ig` is Igbo: BIDO (BEGIN), GOSI (REVEAL). +- `# tongue: pg` (or pcm) is Nigerian Pidgin: OYA (BEGIN), SHOW (REVEAL), FINISH IF (ENDIF). + +Named tools (SHA256, UPPER, and the commons) never translate. `godcode fmt` renders canonical English. The language server reads the pragma and offers completions in the scroll's tongue. + +## Error codes + +- LEXER_ERROR: bad characters or an unterminated string. Check the quotes on the reported line. +- PARSE_ERROR: a grammar violation, usually a missing BEGIN/END CREATION or a missing block closer. +- RUNTIME_ERROR: the scroll failed while running. DECLARE names before use and re-read the reported line. +- FILE_ERROR: the scroll could not be read. Check the path. + +The human CLI (run, check, fmt) prints the offending source line beneath the message, with a caret at the column when known. + +## Projects, the registry, and the tool bridge + +- `godcode new my-scroll` raises a project: main.god, test_main.god, scroll.toml, README.md. Add --json for machine-readable output. +- `godcode scroll ...` installs, publishes, and verifies reusable scrolls in the registry. +- Nine MCP-compatible tools are exposed for agent frameworks: check, run, consult, intent, anchor_verify, ledger_verify, permissions, explain, get_schema. List them with `godcode tools --json`. Serve them to an agent host over stdio with `godcode bridge` (JSON-RPC). +- `godcode intent "words"` resolves the intent behind words. `godcode lsp` runs the language server. +- The four --json shapes (check, run, explain, ledger-verify) are frozen under dated schemas. `godcode schema` lists them and `godcode schema explain` prints one. Required fields never change meaning; additive fields may appear. + +## Safety rules for agents + +- Validate first, always. Never skip check. +- Never run untrusted scrolls without --sandbox. +- Read a scroll's permission manifest before running it. +- Production moves (real credentials, real money, signed contracts, regulator submissions) belong to the human. Demo in sandbox mode. + +## Links + +- Site: https://getgodcode.com +- Playground (runs in the browser, nothing to install): https://getgodcode.com/playground +- Blog: https://getgodcode.com/blog +- Repository: https://github.com/godcodeengine/Godcode-engine +- Discord: https://discord.gg/894FEJhWfZ diff --git a/site/llms.txt b/site/llms.txt new file mode 100644 index 0000000..5ba938f --- /dev/null +++ b/site/llms.txt @@ -0,0 +1,128 @@ +# God Code + +> God Code is a programming language that reads like scripture. Write real software in words of faith, in your own language, and watch it run. Human-readable, safe, and built for humans and AI creating together. Created in Botswana, open to the world. + +This file teaches an AI model how to write, check, and safely run God Code. A God Code program is called a scroll and lives in a .god file. Everything here is the working truth of the engine: prefer the commands below over guessing, and prefer the JSON output over scraping prose. + +## Install + +Install the engine and CLI: + + pip install godcode-engine + +Confirm the CLI answers: + + godcode --help + +From a source checkout, `pip install -e .` gives the same `godcode` command. + +## The safe workflow + +Follow this loop every time you work with a scroll. + +1. Generate the scroll. Every program needs BEGIN CREATION ... END CREATION. Nothing outside that block runs. +2. Read before you run. `godcode explain scroll.god --json` reports static facts about a scroll (its tongue, rites and their intents, names, reveals, seals, summons, consults, imports, permissions) and executes nothing. Use it on any scroll you did not write. +3. Check. `godcode check --json scroll.god` returns one JSON document: {"tool":"godcode","command":"check","file":...,"ok":true|false,"diagnostics":[{line,col,code,severity,message,hint}]}. Exit 0 means pure, exit 1 means diagnostics, exit 2 is a usage error. Line and col are 1-based; col may be null. Fix every diagnostic before running. +4. Run safely. `godcode run --sandbox --json scroll.god` returns {"tool","command","file","ok","output":[...],"seals":[{block,hash}],"error":{...}|null,"stats":{"ms":...}}. The output array holds every line printed during the run (REVEAL lines plus engine notices such as [SEAL] and [INTENT]). On a runtime error, output holds the lines revealed before the error, and error carries line, col, code, and message. The report also carries an intents array and a permissions block, described below. +5. Iterate until check is clean and the run reveals what you intended. + +Never run an untrusted scroll without --sandbox. The sandbox confines execution: no files, no network, no subprocesses, with time and step limits. + +A minimal scroll, to prove the loop: + + BEGIN CREATION + DECLARE name AS "world" + REVEAL("Hello, {name}. Grace upon grace.") + END CREATION + +`godcode check --json hello.god` answers ok: true, and `godcode run --sandbox --json hello.god` reveals "Hello, world. Grace upon grace." + +## Language essentials + +- Assignment is `DECLARE x AS ...`. There is no other assignment form. +- Output is `REVEAL(expr)`. The language is input-free; there is no stdin. +- Comparisons use IS and IS NOT (== and != also work). IF takes THEN: `IF n IS 3 THEN`. +- Strings breathe values in: "grace upon {name}" interpolates any expression, including {a * b} and {UPPER(name)}. To write a literal brace, double it: "{{" writes { and "}}" writes }. +- Comments start with # and run to end of line. +- Keywords are case-insensitive. Canonical style is UPPER. +- Blocks close explicitly: ENDIF, ENDFOR, ENDWHILE, END RITE. +- FOR walks a list or a range: `FOR i IN RANGE(1, 6)`. +- A rite is a function: `DEFINE RITE name(params)` ... `END RITE`, invoked with `INVOKE name(args)`. Rites support parameters, RETURN, and closures. +- ASCEND ends a run peacefully. It is not an error. +- An unbound name evaluates to a Symbol and does not raise. This is the Symbol Rule: `IF seeker IS worthy THEN` works because worthy is a symbol. But `BREATHE LIFE INTO` an undeclared name does raise at runtime. +- Division by zero is rejected: "division by nothing is not permitted". +- Error messages may end with "Did you mean 'X'?" for a misspelled rite, variable, bless target, or map key. Take the hint. + +## Seals, anchors, and pure tools + +- `SEAL(expr)` appends a tamper-evident, hash-chained covenant block to the ledger. `godcode ledger verify` attests the covenant chain and the anchor chain. +- `ANCHOR(expr [, chain])` anchors a value's hash on a chain and returns a receipt map {chain, anchor_hash, height, timestamp, payload_hash}. Index it like receipt["anchor_hash"]; TYPE(receipt) is "map". The default chain is `simulated`, a local genesis-anchored chain. +- `SHA256(x)` fingerprints a word, number, or truth as 64 hex characters. `HMAC(key, message)` seals a message under a key (HMAC-SHA-256). `BASE64_ENCODE(x)` and `BASE64_DECODE(s)` veil and unveil words. All four are pure: they need no import and run unchanged under --sandbox. +- `CONSULT("question")` asks the local Spirit oracle. It answers in two or three sentences, works in the sandbox, and never fails the run. + +## The commons + +Everyday tools, always present, pure, and sandbox-safe. Words: TRIM, REPLACE, STARTS_WITH, ENDS_WITH, SUBSTRING, CONTAINS, COUNT, REPEAT. Lists: SORT (returns a new list), MIN_OF, MAX_OF, SUM_OF, FIRST, LAST, UNIQUE, INDEX_OF (returns -1 when absent). Maps: KEYS, VALUES, HAS_KEY, MERGE (returns a new map). Numbers: ABS, ROUND (half away from zero), FLOOR, CEIL, SQRT, POW. REPEAT(s, n) is a word function, not a loop. + +## Declared intent + +A rite can carry its purpose in plain words: + + DECLARE INTENT "bring peace to the household" ON morning_blessing + +At invocation, the engine discerns whether the rite's words still walk in its declared intent. The run report's intents array carries one entry per invoked rite with an intent: {declared, discerned, confidence, aligned}. Alignment is blessed; drift is counseled gently and can never fail a run. When you generate a rite, declare its intent, and after each run check the intents array for drift. + +## Permission manifests + +A scroll should declare what it may touch, at the top inside BEGIN CREATION: + + DECLARE PERMISSION TO READ "data/" + DECLARE PERMISSION TO WRITE "out/" + DECLARE PERMISSION TO SPEAK WITH "api.example.com" + DECLARE PERMISSION TO ASK THE WORLD + DECLARE PERMISSION TO SUMMON "reports.weekly" + +Any rite that reaches for an undeclared power is stopped. The manifest never widens the host policy: --sandbox still narrows everything. Read a scroll's manifest without running anything: `godcode permissions --json scroll.god`. The manifest is a promise; the sandbox is the wall. Keep both. + +## Tongues: write keywords in your own language + +A scroll may open with a tongue pragma and write its keywords in that language. English keywords still work in the same file. + +- `# tongue: tn` is Setswana: SIMOLOLA (BEGIN), SENOLA (REVEAL), FA (IF), FEDISA (END). +- `# tongue: zu` is isiZulu: QALA (BEGIN), VEZA (REVEAL), UMA (IF). +- `# tongue: ig` is Igbo: BIDO (BEGIN), GOSI (REVEAL). +- `# tongue: pg` (or pcm) is Nigerian Pidgin: OYA (BEGIN), SHOW (REVEAL), FINISH IF (ENDIF). + +Named tools (SHA256, UPPER, and the commons) never translate. `godcode fmt` renders canonical English. The language server reads the pragma and offers completions in the scroll's tongue. + +## Error codes + +- LEXER_ERROR: bad characters or an unterminated string. Check the quotes on the reported line. +- PARSE_ERROR: a grammar violation, usually a missing BEGIN/END CREATION or a missing block closer. +- RUNTIME_ERROR: the scroll failed while running. DECLARE names before use and re-read the reported line. +- FILE_ERROR: the scroll could not be read. Check the path. + +The human CLI (run, check, fmt) prints the offending source line beneath the message, with a caret at the column when known. + +## Projects, the registry, and the tool bridge + +- `godcode new my-scroll` raises a project: main.god, test_main.god, scroll.toml, README.md. Add --json for machine-readable output. +- `godcode scroll ...` installs, publishes, and verifies reusable scrolls in the registry. +- Nine MCP-compatible tools are exposed for agent frameworks: check, run, consult, intent, anchor_verify, ledger_verify, permissions, explain, get_schema. List them with `godcode tools --json`. Serve them to an agent host over stdio with `godcode bridge` (JSON-RPC). +- `godcode intent "words"` resolves the intent behind words. `godcode lsp` runs the language server. +- The four --json shapes (check, run, explain, ledger-verify) are frozen under dated schemas. `godcode schema` lists them and `godcode schema explain` prints one. Required fields never change meaning; additive fields may appear. + +## Safety rules for agents + +- Validate first, always. Never skip check. +- Never run untrusted scrolls without --sandbox. +- Read a scroll's permission manifest before running it. +- Production moves (real credentials, real money, signed contracts, regulator submissions) belong to the human. Demo in sandbox mode. + +## Links + +- Site: https://getgodcode.com +- Playground (runs in the browser, nothing to install): https://getgodcode.com/playground +- Blog: https://getgodcode.com/blog +- Repository: https://github.com/godcodeengine/Godcode-engine +- Discord: https://discord.gg/894FEJhWfZ From 3c573ea2877ab97edb97a15a7d548704249592b5 Mon Sep 17 00:00:00 2001 From: alakanani Date: Tue, 17 Nov 2026 20:29:28 +0200 Subject: [PATCH 2/2] Correct the tool count in llms.txt: eleven MCP tools, not nine The MCP merge added format and list_scrolls. The file an AI system reads must be exact. --- llms.txt | 2 +- site/llms.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/llms.txt b/llms.txt index 5ba938f..412a4bc 100644 --- a/llms.txt +++ b/llms.txt @@ -108,7 +108,7 @@ The human CLI (run, check, fmt) prints the offending source line beneath the mes - `godcode new my-scroll` raises a project: main.god, test_main.god, scroll.toml, README.md. Add --json for machine-readable output. - `godcode scroll ...` installs, publishes, and verifies reusable scrolls in the registry. -- Nine MCP-compatible tools are exposed for agent frameworks: check, run, consult, intent, anchor_verify, ledger_verify, permissions, explain, get_schema. List them with `godcode tools --json`. Serve them to an agent host over stdio with `godcode bridge` (JSON-RPC). +- Eleven MCP-compatible tools are exposed for agent frameworks: check, run, consult, intent, anchor_verify, ledger_verify, permissions, explain, get_schema, format, list_scrolls. List them with `godcode tools --json`. Serve them to an agent host over stdio with `godcode bridge` (JSON-RPC). - `godcode intent "words"` resolves the intent behind words. `godcode lsp` runs the language server. - The four --json shapes (check, run, explain, ledger-verify) are frozen under dated schemas. `godcode schema` lists them and `godcode schema explain` prints one. Required fields never change meaning; additive fields may appear. diff --git a/site/llms.txt b/site/llms.txt index 5ba938f..412a4bc 100644 --- a/site/llms.txt +++ b/site/llms.txt @@ -108,7 +108,7 @@ The human CLI (run, check, fmt) prints the offending source line beneath the mes - `godcode new my-scroll` raises a project: main.god, test_main.god, scroll.toml, README.md. Add --json for machine-readable output. - `godcode scroll ...` installs, publishes, and verifies reusable scrolls in the registry. -- Nine MCP-compatible tools are exposed for agent frameworks: check, run, consult, intent, anchor_verify, ledger_verify, permissions, explain, get_schema. List them with `godcode tools --json`. Serve them to an agent host over stdio with `godcode bridge` (JSON-RPC). +- Eleven MCP-compatible tools are exposed for agent frameworks: check, run, consult, intent, anchor_verify, ledger_verify, permissions, explain, get_schema, format, list_scrolls. List them with `godcode tools --json`. Serve them to an agent host over stdio with `godcode bridge` (JSON-RPC). - `godcode intent "words"` resolves the intent behind words. `godcode lsp` runs the language server. - The four --json shapes (check, run, explain, ledger-verify) are frozen under dated schemas. `godcode schema` lists them and `godcode schema explain` prints one. Required fields never change meaning; additive fields may appear.