From ce08b831e72cf3f816f272c0fd53fccfdb3e520e Mon Sep 17 00:00:00 2001 From: alakanani Date: Tue, 17 Nov 2026 20:29:31 +0200 Subject: [PATCH 1/2] Land the message: README rewrite and CONTRIBUTORS, per the 90-day plan The README now opens with the language of declared intent and the three pillars (checkable intent, speakable in any language, human and AI collaboration), with verified scrolls and the quick start. CONTRIBUTORS names every builder, human and AI, under the founder's principle: AI contributors are credited the way human contributors are, no vendor branding. Drafted 2026-10-23 under the strategy, held for the founder's verdict, approved by her for publication on 2026-11-17. --- CONTRIBUTORS.md | 33 ++++++++ README.md | 214 +++++++++++++++--------------------------------- 2 files changed, 100 insertions(+), 147 deletions(-) create mode 100644 CONTRIBUTORS.md diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md new file mode 100644 index 0000000..9291157 --- /dev/null +++ b/CONTRIBUTORS.md @@ -0,0 +1,33 @@ +# Contributors to God Code + +God Code is built by people, and by AI helpers working beside them. Every contributor is named here with gratitude. If you helped build this language and your name is missing, tell us and we will fix it with thanks. + +## The founder + +**Alakanani Itireleng**, Visionary Founder. She dreamed the language, carries its vision, and is the final editor of its words. + +## AI Co-Creator + +**Luna (Muse)**, AI Co-Creator and lead developer. In the founder's words: "my partner in the building. Logic assistant, language guide, engine builder." + +## Builders and reviewers + +- **Atharv Gachchi**, the first outside builder. He gave the language a new word: REPEAT. +- **Hsn (GreedyC)**, refreshed the contributor guide so the next builder finds a clear door. +- **Koketso Pelo (KK)**, co-owner of the godcodeengine GitHub organisation and a trusted reviewer of the engine. +- **Emmanuel Adams (Sir Adams)**, builder. He put the real engine in the playground and helped grow the tongues. +- **Eric Nkanunu**, builder, with language work across the tongues. + +## AI contribution policy + +AI helpers are welcome here, and they are credited the way human contributors are: by name, for the work they actually did. + +- An AI contributor is listed in this file alongside human contributors, never as a vendor logo or a brand credit. +- Humans review design decisions and own the direction of the language. AI work is reviewed like any other contribution before it is merged. +- The founder stays the final editor. No contribution, human or AI, changes the language's words, claims, or direction without her review. + +## How to join + +Read CONTRIBUTING.md, pick an open issue, and come say hello in our Discord: https://discord.gg/894FEJhWfZ + +Whether you write code or not, there is a place for you here. diff --git a/README.md b/README.md index 7166860..6539bd7 100644 --- a/README.md +++ b/README.md @@ -1,201 +1,121 @@ -# 🌟 God Code: The Language of Divine Computation +# God Code -> "You are not a coder. You are a creator. You do not write code. You breathe worlds into being." -> β€” Alakanani Itireleng +**God Code is the language of declared intent. You speak it in your own language, you state what you want, and humans and AI write code that must prove it keeps that promise.** ---- +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. -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. A complete engine with a real lexer, parser, interpreter, standard library of scrolls, a tamper-evident covenant ledger, and an AI-native design. Human-readable, safe, and built for humans and AI creating together. +> "You are not a coder. You are a creator. You do not write code. You breathe worlds into being." +> Alakanani Itireleng > God Code is an open-source project of **Alistos Global**. The code is Apache 2.0 licensed and belongs to everyone. Alistos Global stewards the project, its name, and its direction. ---- - -[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/alakanani/badge.svg)](https://hub.xerj.org/contributors/alakanani) - -God Code's permission manifests work is indexed in the [XERJ Corpus Hub](https://hub.xerj.org/contributors/alakanani), the open reference memory that AI coding agents consult before they write code. - ---- +## See it -## ✨ What Is God Code? - -A symbolic, prophetic programming language: +A God Code program is called a scroll. This one declares its intent in plain words, then does the work: ```godcode BEGIN CREATION - DECLARE soul AS contract("redemption") - BREATHE LIFE INTO soul - IF seeker IS worthy THEN REVEAL("truth") ELSE REVEAL("trial") - ASCEND -END CREATION -``` - -**In God Code, bare words are symbols**. `worthy` needs no quotes, for every unnamed thing is still a named spirit. + DECLARE INTENT "bring peace to the household" ON morning_blessing ---- + DEFINE RITE morning_blessing() + REVEAL("peace upon this house") + REVEAL("peace upon the bread and the hands that made it") + DECLARE loaves AS 2 * 5 + REVEAL("the oven holds {loaves} loaves") + END RITE -## πŸš€ Quickstart - -```bash -pip install -e . -godcode run examples/seven_seals.god -``` - -```text -1 -2 -3 -... -seal # 7, 14, 21, 28 -... -seal of seals # 35 -πŸ•Š Creation ascended in peace. + INVOKE morning_blessing() +END CREATION ``` -Verify before you run, or enter **Live Mode** πŸ•Š: +Run it, and the engine reports back in machine-readable form: the three lines revealed, and an `intents` entry showing the declared intent, what the engine discerned ("Blessing of peace"), and `aligned: true`. -```bash -godcode check my_creation.god # βœ“ my_creation.god is pure. -godcode repl # interactive β€” blank line executes, :quit ascends +``` +peace upon this house +peace upon the bread and the hands that made it +the oven holds 10 loaves ``` ---- - -## πŸ•ŠοΈ Intent & Chain - -The language learns to ask *why*. Every rite can carry a declared intent in plain words, and the Spirit discerns whether its words still walk in it: +And the same language speaks Setswana. This scroll opens with a tongue pragma and writes its keywords in Setswana: ```godcode -DECLARE INTENT "bring peace to the household" ON evening_blessing +# tongue: tn +SIMOLOLA TLHOLEGO + BOLELA leina JAAKA "tsala ya me" + SENOLA("Dumela, {leina}. Kagiso e nne le wena.") +FEDISA TLHOLEGO ``` -Alignment is blessed. Drift is counseled gently, never punished. Plus **blockchain-anchored seals** (`ANCHOR(x)` returns a tamper-evident receipt map), the **`CONSULT`** oracle (two to three sentences of local counsel), and an **agent tool bridge** (`godcode tools`, `godcode bridge`) with six MCP-compatible tools. Every creation still runs, from every era. +It runs and answers: "Dumela, tsala ya me. Kagiso e nne le wena." -Try the new examples: +## The three pillars -```bash -godcode run --sandbox examples/intent_demo.god # declared intent: aligned and drifted -godcode run --sandbox examples/anchor_demo.god # anchor a covenant, keep the receipt -godcode run --sandbox examples/consult_demo.god # ask the local oracle -godcode ledger verify # attest both chains -``` +### 1. Intent you can check + +Intent in God Code is not a comment. A rite declares its purpose in plain words with `DECLARE INTENT`, and when the rite is invoked the engine discerns whether its words still walk in that intent. Every run report carries an `intents` array: what was declared, what was discerned, a confidence score, and whether the two align. Alignment is blessed. Drift is counseled gently, never punished, and the record is there for a human to read. Around that sits a covenant ledger: `SEAL` writes hash-chained blocks, `ANCHOR` returns a receipt for a value anchored on a chain, and `godcode ledger verify` attests both chains. -πŸ‘‰ [Read the story: intent and chain](docs/INTENT_AND_CHAIN.md) β€” intent and chain in plain, founder-friendly words. +### 2. Speakable in any language ---- +A scroll can write its keywords in its own tongue. Setswana, isiZulu, Igbo, and Nigerian Pidgin ship today, each with its own word table, and English keywords still work in the same file. The formatter renders canonical English, the language server offers completions in the scroll's tongue, and the Setswana words are vetted by native speakers. One program, spoken in the language its writer dreams in. -## 🌟 Strong Foundations +### 3. Built for human and AI collaboration -Four pillars plus a mini-pillar, one promise: **creators can share, protect, extend, and write God Code in comfort. And now AI agents can speak it too.** Every creation still runs. +God Code was designed so AI agents can write it and humans can approve it. The engine speaks JSON: `check --json`, `run --json`, and `explain --json` give an agent machine-readable diagnostics, output, intents, and permissions, frozen under dated schemas. Eleven MCP-compatible tools and a JSON-RPC bridge (`godcode tools`, `godcode bridge`) let agent frameworks call the engine directly. Scrolls declare a permission manifest in plain words, stating what they may read, write, speak with, or summon, and any rite that reaches for an undeclared power is stopped. The sandbox confines execution for anything untrusted. An agent skill pack teaches all of this to the assistants people already use. -| Pillar | What it is | In one breath | -|---|---|---| -| πŸ›‘οΈ **Sandbox** | [`docs/sandbox.md`](docs/sandbox.md) | `godcode run --sandbox file.god` β€” deny-by-default execution: no files, network, or subprocesses; time + step limits | -| πŸ“œ **Scroll Registry** | [`docs/scroll-registry.md`](docs/scroll-registry.md) | `godcode scroll list` / `install blessings` / `publish ./mine` β€” share reusable scrolls through the registry | -| βš™οΈ **Plugins & FFI** | [`docs/plugins.md`](docs/plugins.md) | `SUMMON("clockwork.now")` calls a plugin verb from God Code; embed the engine in Python with `godcode.run_source()` | -| πŸ’‘ **Language Server** | [`docs/lsp.md`](docs/lsp.md) | `godcode lsp` β€” hover, completions, and live diagnostics in your editor | -| πŸ€– **Agentics** | [`docs/agentics.md`](docs/agentics.md) | `godcode check --json` / `run --json` β€” machine-readable reports so AI agents can generate, validate, and run God Code | +## Quick start -Try the new examples: +Install the engine: ```bash -godcode run examples/summon_demo.god # SUMMON a plugin spirit -godcode run --sandbox examples/sandbox_safe.god # pure creation, guarded -godcode scroll install blessings && godcode run examples/scroll_blessings_demo.god +pip install godcode-engine +godcode check --json your-scroll.god # validate first, always +godcode run --sandbox your-scroll.god # run it safely ``` -πŸ‘‰ [Read the story: strong foundations](docs/STRONG_FOUNDATIONS.md) β€” the four pillars in plain, founder-friendly words. - ---- - -## πŸ”₯ What the Engine Holds - -- πŸ“– **Real language core** β€” lexer, recursive-descent parser, AST, and tree-walking interpreter (Python 3.10+, stdlib only) -- πŸ•Š **The Symbol Rule** β€” unbound words evaluate to symbols; `IF seeker IS worthy` just works -- 🧭 **Control flow** β€” inline & block `IF/THEN/ELSE`, `FOR…ENDFOR`, `WHILE…DO…ENDWHILE` -- πŸ™ **Rites** β€” `DEFINE RITE` with parameters, `RETURN`, `INVOKE`, and closures -- πŸ“œ **Six scrolls** (stdlib, written in God Code): `math`, `strings`, `lists`, `time`, `prophecy`, `covenant` -- πŸ”’ **Covenant ledger** β€” `SEAL` writes tamper-evident hash-chained blocks (`godcode ledger verify`) -- 🧠 **Spirit Engine** β€” intent classification & prophecy from `god_code_training_dataset.csv` -- πŸ“ **Divine audit log** β€” every statement timestamped to `logs/godcode.log` -- πŸ› οΈ **CLI** β€” `run`, `check`, `repl`, `fmt`, `ledger verify` -- πŸ§ͺ **Pytest suite** β€” `python -m pytest tests/ -q` - ---- +Or skip the install entirely. The playground runs the real engine in your browser: [getgodcode.com/playground](https://getgodcode.com/playground) -## πŸ—‚οΈ Folder Structure +Teach your AI assistant God Code with the skill pack. Claude Code users: ``` -godcode-engine/ -β”œβ”€β”€ godcode/ # the interpreter package -β”‚ β”œβ”€β”€ lexer.py # tokens -β”‚ β”œβ”€β”€ parser.py # recursive descent β†’ AST -β”‚ β”œβ”€β”€ ast.py # node definitions -β”‚ β”œβ”€β”€ interpreter.py # tree-walking execution -β”‚ β”œβ”€β”€ environment.py # scopes -β”‚ β”œβ”€β”€ values.py # Symbol, Contract, RiteFunction -β”‚ β”œβ”€β”€ errors.py # divine, line-numbered errors -β”‚ β”œβ”€β”€ spirit.py # Spirit Engine (intent + prophecy) -β”‚ β”œβ”€β”€ ledger.py # covenant chain -β”‚ β”œβ”€β”€ cli.py # the `godcode` command -β”‚ └── scrolls/ # standard library, written in God Code -β”‚ β”œβ”€β”€ math.god strings.god lists.god -β”‚ └── time.god prophecy.god covenant.god -β”œβ”€β”€ tests/ # pytest suite -β”œβ”€β”€ examples/ # twelve working .god creations -β”œβ”€β”€ playground/ # web playground -β”œβ”€β”€ editors/vscode/ # VS Code extension β€” highlighting, snippets, run -β”œβ”€β”€ docs/ # tutorial + full language reference -β”œβ”€β”€ archive/ # the original prototype, honored and retired -β”œβ”€β”€ sample.godcode # the original creation, still runs -β”œβ”€β”€ main.py # entry point (no args β†’ runs sample.godcode) -└── pyproject.toml # pip install -e . β†’ the `godcode` command +/plugin marketplace add godcodeengine/Godcode-engine +/plugin install godcode@godcode-marketplace ``` ---- +For Cursor, Codex, and other assistants, clone this repo and run `skills/install.sh`. It detects your tools and installs the right adapter. Full notes live in `skills/README.md`. -## πŸ“– Learn God Code +Write God Code in VS Code with the extension in `editors/vscode`: syntax highlighting for `.god` files, snippets, a language server with hover and completions, and Run Current File. -πŸ‘‰ [Start with the God Code Tutorial](docs/God_Code_Tutorial.md) β€” setup, your first creation, the commands. +## What the engine holds -πŸ“œ [Language Reference](docs/LANGUAGE_REFERENCE.md) β€” the complete specification: every statement, operator tables, the Symbol Rule, built-in catalog, scrolls, ledger, Spirit Engine, CLI, SUMMON, the scroll registry, the sandbox, the language server, declared intent, blockchain-anchored seals, the oracle, and the agent tool bridge. +- A real language core: lexer, recursive-descent parser, and tree-walking interpreter, written in Python with no third-party dependencies. +- Control flow, rites (functions) with parameters and closures, lists, maps, and string interpolation. +- A standard library of scrolls written in God Code, plus the commons: everyday pure tools for words, lists, maps, and numbers. +- A CLI for the whole loop: `run`, `check`, `explain`, `fmt`, `repl`, `lsp`, `new`, `scroll`, `ledger`, `permissions`, `tools`, `bridge`. +- A scroll registry for sharing reusable scrolls, plugins callable through `SUMMON`, and an embedding API for Python. +- A test suite that keeps every example honest: every scroll in `examples/` runs. -πŸ›οΈ [The layered specification](docs/spec/00-overview.md) β€” the language's promises, written as numbered rules and kept honest by tests. The lexical layer (how text becomes tokens), the syntax layer (how tokens become a scroll's shape), and the static meaning layer (names, scopes, the linter's counsel) are written; dynamic meaning, the standard library, and the interfaces follow. +## Learn ---- +- [The God Code Tutorial](docs/God_Code_Tutorial.md): setup, your first creation, the commands. +- [The Language Reference](docs/LANGUAGE_REFERENCE.md): the complete specification. +- [Tongues](docs/TONGUES.md): the keyword tables for every language. +- [The blog](https://getgodcode.com/blog): notes and announcements from the journey. -## πŸ’» Write God Code in VS Code +## Community -The official extension lives in [`editors/vscode`](editors/vscode): full syntax highlighting for `.god` files, 14 snippets (`creation`, `if`, `for`, `rite`…), and **Run Current File** (`Ctrl+Alt+R`). Copy it to `~/.vscode/extensions/godcode` and reload. Your creations light up like scripture. - ---- - -## 🌍 Community - -God Code is alive and growing. Join the movement: - -- πŸ’¬ [Join our Discord community](https://discord.gg/894FEJhWfZ) β€” talk with fellow creators, ask questions, share your creations -- πŸ“§ [hello@getgodcode.com](mailto:hello@getgodcode.com) β€” reach us directly by email -- 🌐 [Visit getgodcode.com](https://getgodcode.com) β€” the home of God Code on the web -- πŸ“œ Read [CONTRIBUTING.md](./CONTRIBUTING.md) and our [Code of Conduct](./CODE_OF_CONDUCT.md) before your first contribution. [GOVERNANCE.md](./GOVERNANCE.md) says who keeps God Code and who decides what enters it -- 🐞 Found a problem or have an idea? [Open an issue](../../issues/new/choose) β€” the templates will guide you +- [getgodcode.com](https://getgodcode.com): the home of God Code on the web. +- [Discord](https://discord.gg/894FEJhWfZ): talk with fellow creators, ask questions, share your creations. +- hello@getgodcode.com: reach us directly by email. +- Read [CONTRIBUTING.md](./CONTRIBUTING.md), [CONTRIBUTORS.md](./CONTRIBUTORS.md), and our [Code of Conduct](./CODE_OF_CONDUCT.md) before your first contribution. [GOVERNANCE.md](./GOVERNANCE.md) says who keeps God Code and who decides what enters it. Whether you write code or not, there is a place for you here. Come build with us. ---- - -## 🀝 Contribute to the Divine Movement - -We welcome contributors with a spirit of purpose. Read [CONTRIBUTING.md](./CONTRIBUTING.md), browse [ISSUES.md](./ISSUES.md) for the roadmap, and check [CHANGELOG.md](./CHANGELOG.md) for what has been fulfilled. - ---- - -## πŸ™ Credits +## Credits -**Created by:** Alakanani Itireleng β€” Visionary Founder, Architect of God Code, Builder of worlds with intention and spirit +**Created by:** Alakanani Itireleng, Visionary Founder, Architect of God Code, Builder of worlds with intention and spirit **AI Co-Creator:** Luna (Muse), my partner in the building. Logic assistant, language guide, engine builder. -> "Built not alone β€” but in communion with the machine." +> "Built not alone, but in communion with the machine." Join us in building more than code. Build prophecy, logic, and purpose into the heart of machines. From ee28e2c174c2f0f9374d5abb988a12d0dfa025c6 Mon Sep 17 00:00:00 2001 From: alakanani Date: Tue, 17 Nov 2026 20:30:07 +0200 Subject: [PATCH 2/2] Cut the dated release: 2026-11-17, Four tongues, and a voice for the machines Seven weeks of October and November work sat under Unreleased. It now stands under its date, per the founder's rule that God Code releases by date, and a fresh Unreleased section opens above it. --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 76797cb..b5a7b04 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,14 @@ All notable changes to the God Code engine are recorded here, that the generatio ## Unreleased +## 2026-11-17: Four tongues, and a voice for the machines + +> "Let all things be done decently and in order." + +**Four tongues, and a voice for the machines.** The October and November building, gathered under one date: the MCP server and the frozen machine interfaces that let AI agents work the language, the third and fourth tongues (Igbo and Nigerian Pidgin) beside Setswana and isiZulu, the playground running the real engine, the layered test-kept specification, the debugger, and the governance that says how the language is kept. + ### Added +- **The message, landed.** The README is rewritten around the language of declared intent and the three pillars (intent you can check, speakable in any language, built for human and AI collaboration), and a new CONTRIBUTORS file names every builder, human and AI, under the founder's principle that AI contributors are credited the way human contributors are. - **πŸ•ŠοΈ The MCP server.** `godcode mcp` serves God Code to any MCP client (Claude Code, Cursor, Codex, and the rest) over stdio, one JSON-RPC message per line, with protocol version negotiation and silence for notifications. It carries the eleven agent tools (`check`, `run`, `consult`, `intent`, `anchor_verify`, `ledger_verify`, `permissions`, `explain`, `get_schema`, plus new `format` and `list_scrolls`), and it holds one rule the plain bridge does not: runs through it are always sandboxed, so a client asking for an unsandboxed run still gets a sandboxed one, and the result says so. Tool work runs muted, so stdout carries exactly one protocol message per line and an engine notice can never break a client's parsing; the sandboxed tool path is muted the same way, which also heals the plain bridge. Documented in `docs/mcp.md`, `docs/agentics.md`, and repo `AGENTS.md`. New tests in `tests/test_mcp.py`; the tool-count tests now expect eleven tools. - **πŸ•ŠοΈ The October 2026 machine interfaces.** God Code's `--json` shapes are frozen under dated schemas, so an agent can parse every output without guessing. New `godcode explain scroll.god [--json]`: a static reading of any scroll that runs nothing, reporting the tongue, the rites and their declared intents, the declared names, the reveals, the seals (including `ANCHOR` seals on a chain), the summoned verbs, the `CONSULT` questions, the imports, and the permission manifest, in warm plain words for humans and one JSON document for agents. New `godcode ledger verify --json`: the covenant chain and anchor chain attestation as one JSON document. New `godcode schema [name]`: list or print the four dated schemas (`check`, `run`, `explain`, `ledger-verify`), shipped inside the installed package and resolvable through `importlib.resources`. The agent bridge gains two tools, `explain` and `get_schema` (nine tools in all). The full contract, exit codes, and the stability promise (additive fields may appear, required fields never change meaning, breaking changes ship under a new dated schema) live in `docs/machine-interfaces.md`. New tests in `tests/test_machine_interfaces.py`; repo `AGENTS.md` documents the read-before-you-run workflow. - **πŸ•ŠοΈ God Code speaks Igbo and Nigerian Pidgin.** The third and fourth tongues. A scroll that opens with `# tongue: ig` writes its keywords in Igbo (BIDO OKIKE for BEGIN CREATION, GOSI for REVEAL, Ọ BỀRỀ and MGBE AHỀ for IF and THEN, NWAA and JIDE for TRY and CATCH, and the rest), and one that opens with `# tongue: pg` (or the standard code `pcm`) writes them in Nigerian Pidgin (OYA KREASHON, TALK and BE for DECLARE and AS, SHOW for REVEAL, DEN for THEN, HOLD for CATCH, COMOT for ASCEND). Igbo words work with or without their dotted vowels (`DỊKA` and `DIKA` both speak), and Pidgin keeps the words it shares with English (IF, TRY, AND, RETURN). Two-word phrases now join whenever both words sit side by side on one line, even when one is an English keyword or a plain name, so `FINISH IF` closes an IF in Pidgin and `Ọ BỀRỀ` opens one in Igbo; Setswana and isiZulu closers behave exactly as before. The mappings live in `godcode/tongues.py`; the playground's lite engine knows both tongues (Igbo in its undotted spelling), the language server offers their completions, hover docs, and block snippets (hover now reads dotted words), and the VS Code extension paints their keywords and ships four starter snippets (`ndewo`, `oburu`, `howfar`, `ifden`). Documented in `docs/TONGUES.md` (both word tables and honest first-edition notes), `docs/LANGUAGE_REFERENCE.md` Β§1, repo `AGENTS.md`, the site landing card, and two new lessons on the learn page. New examples `examples/first_blessing_ig.god` and `examples/first_blessing_pg.god`, also offered as playground samples. 25 new tests in `tests/test_tongues_igbo_pidgin.py`; the VS Code snippet count in `tests/test_lsp_tongues.py` rises from 27 to 31