codeplain 0.3.5__tar.gz → 0.3.7__tar.gz

codeplain-0.3.7/.claude/settings.local.json

@@ -0,0 +1,66 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr:*)",
+      "Bash(git diff *)",
+      "Bash(mypy . --check-untyped-defs)",
+      "Bash(flake8 .)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/test_git_utils.py -v --no-header)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key python *)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/_sandbox_check.py -v -s)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/test_partial_rendering.py -v)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/test_plain_modules.py -v)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/ -v)",
+      "Bash(flake8 tests/)",
+      "Bash(git stash *)",
+      "Bash(flake8 tests/test_git_utils.py)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key coverage run -m pytest tests/ -v)",
+      "Bash(.venv/bin/coverage run *)",
+      "Bash(.venv/bin/coverage report *)",
+      "Bash(.venv/bin/python -m coverage run -m pytest tests/)",
+      "Bash(.venv/bin/python -m coverage report)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/)",
+      "Bash(flake8 tests/test_partial_rendering.py tests/test_plain_modules.py)",
+      "Bash(MASTER_KEY=test-master-key GOOGLE_API_KEY=test-google-api-key pytest tests/test_partial_rendering.py tests/test_plain_modules.py tests/test_git_utils.py)",
+      "Bash(pytest tests *)",
+      "Bash(pytest tests/test_git_utils.py::test_diff_without_previous_frid_and_no_base_folder -x -v)",
+      "Bash(git checkout *)",
+      "Bash(python -c ' *)",
+      "Bash(python3 -c ' *)",
+      "Bash(/opt/homebrew/opt/python@3.11/bin/python3.11 -c ' *)",
+      "Bash(pytest tests/test_git_utils.py -x -v)",
+      "Bash(pytest tests/test_git_utils.py -v)",
+      "Bash(pytest -x -v)",
+      "Bash(pytest tests/test_partial_rendering.py -v)",
+      "Bash(pytest -v)",
+      "Bash(pytest)",
+      "Bash(python -m pytest tests/test_partial_rendering.py -x -v)",
+      "Bash(python -m pytest -x -v)",
+      "Bash(python -m pytest tests/test_partial_rendering.py -v)",
+      "Bash(python -m pytest)",
+      "Bash(python -m pytest tests/test_plain_modules.py -q)",
+      "Bash(python3 -m pytest tests/test_plain_modules.py -q)",
+      "Bash(.venv/bin/pytest tests/test_plain_modules.py -q)",
+      "Bash(git -C /Users/zanjonke/Work/codeplain/codeplain log --oneline -5)",
+      "Bash(git -C /Users/zanjonke/Work/codeplain/codeplain branch --show-current)",
+      "Bash(python -m pytest tests/test_git_utils.py::test_get_last_finished_frid_empty_repo -x)",
+      "Bash(python3 -m pytest tests/test_git_utils.py::test_get_last_finished_frid_empty_repo -x)",
+      "Bash(.venv/bin/python -m pytest tests/test_git_utils.py::test_get_last_finished_frid_empty_repo -x)",
+      "Bash(.venv/bin/python -m pytest tests/test_git_utils.py::test_get_last_finished_frid_without_module_name tests/test_git_utils.py::test_get_last_finished_frid_empty_repo -x)",
+      "Bash(.venv/bin/python -m pytest tests/test_git_utils.py)",
+      "Bash(python -m pytest tests/test_partial_rendering.py -x)",
+      "Bash(python3 -m pytest tests/test_partial_rendering.py)",
+      "Bash(/Users/zanjonke/Work/codeplain/codeplain/.venv/bin/python -m pytest tests/test_partial_rendering.py)",
+      "Bash(/Users/zanjonke/Work/codeplain/codeplain/.venv/bin/python -m pytest tests/test_plain_modules.py tests/test_partial_rendering.py)",
+      "Bash(git *)",
+      "Bash(python -m pytest tests/test_plain_modules.py -x --tb=short)",
+      "Bash(python3 -m pytest tests/test_plain_modules.py -x --tb=short)",
+      "Bash(/Users/zanjonke/Work/codeplain/codeplain/venv/bin/python -m pytest tests/test_plain_modules.py --tb=short)",
+      "Bash(/Users/zanjonke/Work/codeplain/codeplain/.venv/bin/python -m pytest tests/test_plain_modules.py --tb=short)",
+      "Bash(/Users/zanjonke/Work/codeplain/codeplain/.venv/bin/python -m pytest tests/test_partial_rendering.py tests/test_git_utils.py --tb=short)",
+      "Bash(.venv/bin/python *)",
+      "Bash(python *)",
+      "Bash(python3 *)"
+    ]
+  }
+}

codeplain-0.3.7/.zed/settings.json

@@ -0,0 +1,46 @@
+// Zed project-local settings, converted from .vscode/settings.json.
+// Docs: https://zed.dev/docs/configuring-zed
+{
+  "format_on_save": "on",
+  "languages": {
+    "Python": {
+      "tab_size": 4,
+      "hard_tabs": false,
+      "preferred_line_length": 120,
+      "wrap_guides": [120],
+      "format_on_save": "on",
+      // Run isort first (organize imports), then black (format).
+      // Matches `source.organizeImports: explicit` + black-formatter from VS Code.
+      "formatter": [
+        {
+          "external": {
+            "command": "isort",
+            "arguments": ["--profile", "black", "--filename", "{buffer_path}", "-"]
+          }
+        },
+        {
+          "external": {
+            "command": "black",
+            "arguments": ["--quiet", "--stdin-filename", "{buffer_path}", "-"]
+          }
+        }
+      ]
+    }
+  },
+  // Treat fixture files under tests/data as plain text (matches files.associations).
+  "file_types": {
+    "Plain Text": ["tests/data/**"]
+  },
+  // python.analysis.extraPaths -> Pyright (Zed's default Python LSP).
+  "lsp": {
+    "pyright": {
+      "settings": {
+        "python": {
+          "analysis": {
+            "extraPaths": ["."]
+          }
+        }
+      }
+    }
+  }
+}

codeplain-0.3.7/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: codeplain
+Version: 0.3.7
+Summary: Transform plain language specifications into working code
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: ==3.11.*
+Requires-Dist: gitpython==3.1.50
+Requires-Dist: mistletoe==1.5.1
+Requires-Dist: networkx==3.6.1
+Requires-Dist: python-frontmatter==1.3.0
+Requires-Dist: python-liquid2==0.4.0
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: requests==2.34.2
+Requires-Dist: rich==15.0.0
+Requires-Dist: sentry-sdk==2.63.0
+Requires-Dist: textual>=7.5.0
+Requires-Dist: tiktoken==0.13.0
+Requires-Dist: transitions==0.9.3
+Provides-Extra: dev
+Requires-Dist: black==26.5.1; extra == 'dev'
+Requires-Dist: flake8==7.3.0; extra == 'dev'
+Requires-Dist: isort==8.0.1; extra == 'dev'
+Requires-Dist: mypy==2.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# *codeplain renderer
+
+## What is \*codeplain?
+
+\*codeplain platform makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+This repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the *codeplain API.
+
+The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code.
+
+Schematic overview of the *codeplain's code rendering:
+
+<img src="https://raw.githubusercontent.com/Codeplain-ai/plain2code_client/main/resources/codeplain_overview.png">
+
+## Getting started
+
+Get started in 15 minutes.
+
+### 1. Install \*codeplain in the terminal
+
+macOS and Linux:
+
+```bash
+curl -fsSL https://codeplain.ai/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://codeplain.ai/install.ps1 | iex
+```
+
+**Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows.
+
+Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI, walks you through setting your `CODEPLAIN_API_KEY`, and offers to set up [plain-forge](#2-let-your-agent-work-in-specs-not-code) and the [plyn editor extension](#vs-code--cursor-extension) for you in the same session.
+
+If you'd rather not run the installer, sign up at [platform.codeplain.ai](https://platform.codeplain.ai) to get your API key and export it yourself:
+
+```bash
+export CODEPLAIN_API_KEY="your_actual_api_key_here"
+```
+
+### 2. Let your agent work in specs, not code
+
+You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. This is what [plain-forge](https://github.com/Codeplain-ai/plain-forge) sets up: a toolkit of skills, rules, and docs that plugs into your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, or any other agent that reads from a standard skills directory — and turns a conversation into a complete `.plain` spec, then keeps maintaining it across the lifetime of the project.
+
+If you didn't install it during step 1, run it any time:
+
+```bash
+npx plain-forge install
+```
+
+### 3. Convert specs into tested and validated code
+
+\*codeplain extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+```bash
+codeplain your-project.plain
+```
+
+### Try it now
+
+You can immediately test the system with a simple "Hello World" example:
+
+- Change to the example folder and run the example:
+
+  ```bash
+  cd examples/example_hello_world_python
+  codeplain hello_world_python.plain
+  ```
+
+  _Note: Rendering will take a few minutes to complete._
+
+- The system will generate a Python application in the `build` directory. You can run it with:
+  ```bash
+  cd build
+  python hello_world.py
+  ```
+
+### VS Code / Cursor extension
+
+If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn) for `***plain` syntax highlighting. The installer in step 1 offers to install it automatically if it detects `code` or `cursor` on your `PATH`.
+
+### Community and support
+
+Share what you're building! Join the [\*codeplain Discord](https://discord.gg/cgbynb9hFq) if you have questions, ideas, or want to share what you built.
+
+Hit an edge case or have feedback? Reach us at [support@codeplain.ai](mailto:support@codeplain.ai).
+
+## Abstracting Away Code Generation Complexity with \*\*\*plain
+
+\*\*\*plain is the language of spec-driven development — a specification language that combines the efficiency of natural language with the control and precision of code.
+
+Structured sections for definitions, functional specs, implementation requirements, test requirements, and acceptance tests let your specs (not scattered docs or ad hoc prompts) become the source of truth for your software's behavior, abstracting away the complexity of using large language models for code generation.
+
+Specs are plain text, so they fit into the workflows you already use — version control, pull requests, and code review.
+
+See the [\*\*\*plain language guide](https://www.plainlang.org/docs/language-guide/) to learn the full syntax.
+
+An example application in \*\*\*plain
+
+<img src="resources/plain_example.png" width="70%" height="70%">
+
+## Additional Resources
+
+### Examples and Sample Projects
+
+- See the [examples](examples) folder for sample projects in Golang, Python, React, and Flutter.
+- For an example of how to implement Pong in \*\*\*plain, see the [pong](https://github.com/Codeplain-ai/plainlang-examples/tree/main/pong) example.
+- For an example of how to implement a task manager in \*\*\*plain, see the [task-manager](https://github.com/Codeplain-ai/plainlang-examples/tree/main/task-manager) example.
+
+### Documentation
+
+- For more details on the ***plain format, see the [***plain language specification](https://www.plainlang.org/docs/).

codeplain-0.3.7/README.md

@@ -0,0 +1,114 @@
+# *codeplain renderer
+
+## What is \*codeplain?
+
+\*codeplain platform makes coding agents better by having them write and maintain specifications instead of code. It extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+This repository is the renderer that powers that last step, turning \*\*\*plain specs into software using the *codeplain API.
+
+The result is a software development workflow centered on specifications, which are faster and more efficient for AI to produce and easier for developers to review and maintain than raw code.
+
+Schematic overview of the *codeplain's code rendering:
+
+<img src="https://raw.githubusercontent.com/Codeplain-ai/plain2code_client/main/resources/codeplain_overview.png">
+
+## Getting started
+
+Get started in 15 minutes.
+
+### 1. Install \*codeplain in the terminal
+
+macOS and Linux:
+
+```bash
+curl -fsSL https://codeplain.ai/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://codeplain.ai/install.ps1 | iex
+```
+
+**Windows users:** Please install WSL (Windows Subsystem for Linux) as this is currently the supported environment for running plain code on Windows.
+
+Follow the installation instructions to complete setup. The installer installs the `codeplain` CLI, walks you through setting your `CODEPLAIN_API_KEY`, and offers to set up [plain-forge](#2-let-your-agent-work-in-specs-not-code) and the [plyn editor extension](#vs-code--cursor-extension) for you in the same session.
+
+If you'd rather not run the installer, sign up at [platform.codeplain.ai](https://platform.codeplain.ai) to get your API key and export it yourself:
+
+```bash
+export CODEPLAIN_API_KEY="your_actual_api_key_here"
+```
+
+### 2. Let your agent work in specs, not code
+
+You describe what you want in plain English, an agent helps you write a spec in \*\*\*plain language, and \*codeplain renders the actual code. This is what [plain-forge](https://github.com/Codeplain-ai/plain-forge) sets up: a toolkit of skills, rules, and docs that plugs into your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, or any other agent that reads from a standard skills directory — and turns a conversation into a complete `.plain` spec, then keeps maintaining it across the lifetime of the project.
+
+If you didn't install it during step 1, run it any time:
+
+```bash
+npx plain-forge install
+```
+
+### 3. Convert specs into tested and validated code
+
+\*codeplain extends coding agents with agentic skills for working at the specification layer, and with tools that convert specifications into tested and validated implementation code.
+
+```bash
+codeplain your-project.plain
+```
+
+### Try it now
+
+You can immediately test the system with a simple "Hello World" example:
+
+- Change to the example folder and run the example:
+
+  ```bash
+  cd examples/example_hello_world_python
+  codeplain hello_world_python.plain
+  ```
+
+  _Note: Rendering will take a few minutes to complete._
+
+- The system will generate a Python application in the `build` directory. You can run it with:
+  ```bash
+  cd build
+  python hello_world.py
+  ```
+
+### VS Code / Cursor extension
+
+If you're using Visual Studio Code or Cursor IDE, we also recommend installing the [plyn extension](https://marketplace.visualstudio.com/items?itemName=Codeplain.plyn) for `***plain` syntax highlighting. The installer in step 1 offers to install it automatically if it detects `code` or `cursor` on your `PATH`.
+
+### Community and support
+
+Share what you're building! Join the [\*codeplain Discord](https://discord.gg/cgbynb9hFq) if you have questions, ideas, or want to share what you built.
+
+Hit an edge case or have feedback? Reach us at [support@codeplain.ai](mailto:support@codeplain.ai).
+
+## Abstracting Away Code Generation Complexity with \*\*\*plain
+
+\*\*\*plain is the language of spec-driven development — a specification language that combines the efficiency of natural language with the control and precision of code.
+
+Structured sections for definitions, functional specs, implementation requirements, test requirements, and acceptance tests let your specs (not scattered docs or ad hoc prompts) become the source of truth for your software's behavior, abstracting away the complexity of using large language models for code generation.
+
+Specs are plain text, so they fit into the workflows you already use — version control, pull requests, and code review.
+
+See the [\*\*\*plain language guide](https://www.plainlang.org/docs/language-guide/) to learn the full syntax.
+
+An example application in \*\*\*plain
+
+<img src="resources/plain_example.png" width="70%" height="70%">
+
+## Additional Resources
+
+### Examples and Sample Projects
+
+- See the [examples](examples) folder for sample projects in Golang, Python, React, and Flutter.
+- For an example of how to implement Pong in \*\*\*plain, see the [pong](https://github.com/Codeplain-ai/plainlang-examples/tree/main/pong) example.
+- For an example of how to implement a task manager in \*\*\*plain, see the [task-manager](https://github.com/Codeplain-ai/plainlang-examples/tree/main/task-manager) example.
+
+### Documentation
+
+- For more details on the ***plain format, see the [***plain language specification](https://www.plainlang.org/docs/).

codeplain-0.3.7/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.7"

codeplain-0.3.7/docs/plain2code_cli.md

@@ -0,0 +1,133 @@
+# Plain2Code CLI Reference
+
+```text
+usage: generate_cli.py [-h] [--verbose] [--base-folder BASE_FOLDER]
+                       [--build-folder BUILD_FOLDER]
+                       [--log-to-file | --no-log-to-file]
+                       [--log-file-name LOG_FILE_NAME]
+                       [--config-name CONFIG_NAME]
+                       [--render-range RENDER_RANGE |
+                       --render-from RENDER_FROM] [--force-render]
+                       [--unittests-script UNITTESTS_SCRIPT]
+                       [--conformance-tests-folder CONFORMANCE_TESTS_FOLDER]
+                       [--conformance-tests-script CONFORMANCE_TESTS_SCRIPT]
+                       [--prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT]
+                       [--test-script-timeout TEST_SCRIPT_TIMEOUT]
+                       [--api [API]] [--api-key API_KEY] [--full-plain]
+                       [--dry-run] [--replay-with REPLAY_WITH]
+                       [--template-dir TEMPLATE_DIR] [--copy-build]
+                       [--build-dest BUILD_DEST] [--copy-conformance-tests]
+                       [--conformance-tests-dest CONFORMANCE_TESTS_DEST]
+                       [--render-machine-graph]
+                       [--logging-config-path LOGGING_CONFIG_PATH]
+                       [--headless]
+                       filename
+
+Render plain code to target code. Path arguments resolve based on where they
+were written: values given on the command line are resolved against the
+current working directory, values read from config.yaml are resolved against
+the config file's directory, and defaults are resolved against the directory
+containing the plain file. Absolute paths (and paths starting with '~') are
+used as-is.
+
+positional arguments:
+  filename              Path to the plain file to render. The directory
+                        containing this file has highest precedence for
+                        template loading, so you can place custom templates
+                        here to override the defaults. See --template-dir for
+                        more details about template loading.
+
+options:
+  -h, --help            show this help message and exit
+  --verbose, -v         Enable verbose output
+  --base-folder BASE_FOLDER
+                        Base folder for the build files
+  --build-folder BUILD_FOLDER
+                        Folder for build files
+  --log-to-file, --no-log-to-file
+                        Enable logging to a file. Defaults to True. Set to
+                        False to disable.
+  --log-file-name LOG_FILE_NAME
+                        Name of the log file. Defaults to 'codeplain.log'. If
+                        a file already exists at the resolved path, it will be
+                        overwritten by the current logs.
+  --render-range RENDER_RANGE
+                        Specify a range of functionalities to render (e.g. `1`
+                        , `2`, `3`). Use comma to separate start and end IDs.
+                        If only one functionality ID is provided, only that
+                        functionality is rendered. Range is inclusive of both
+                        start and end IDs.
+  --render-from RENDER_FROM
+                        Continue generation starting from this specific
+                        functionality (e.g. `2`). The functionality with this
+                        ID will be included in the output. The functionality
+                        ID must match one of the functionalities in your plain
+                        file.
+  --force-render        Force re-render of all the required modules.
+  --unittests-script UNITTESTS_SCRIPT
+                        Shell script to run unit tests on generated code.
+                        Receives the build folder path as its first argument
+                        (default: 'plain_modules').
+  --conformance-tests-folder CONFORMANCE_TESTS_FOLDER
+                        Folder for conformance test files
+  --conformance-tests-script CONFORMANCE_TESTS_SCRIPT
+                        Path to conformance tests shell script. Every
+                        conformance test script should accept two arguments:
+                        1) Path to a folder (e.g. `plain_modules/module_name`)
+                        containing generated source code, 2) Path to a
+                        subfolder of the conformance tests folder (e.g.
+                        `conformance_tests/subfoldername`) containing test
+                        files.
+  --prepare-environment-script PREPARE_ENVIRONMENT_SCRIPT
+                        Path to a shell script that prepares the testing
+                        environment. The script should accept the source code
+                        folder path as its first argument.
+  --test-script-timeout TEST_SCRIPT_TIMEOUT
+                        Timeout for test scripts in seconds. If not provided,
+                        the default timeout of 120 seconds is used.
+  --api [API]           Alternative base URL for the API. Default:
+                        `https://api.codeplain.ai`
+  --api-key API_KEY     API key used to access the API. If not provided, the
+                        `CODEPLAIN_API_KEY` environment variable is used.
+  --full-plain          Full preview ***plain specification before code
+                        generation.Use when you want to preview context of all
+                        ***plain primitives that are going to be included in
+                        order to render the given module.
+  --dry-run             Dry run preview of the code generation (without
+                        actually making any changes).
+  --replay-with REPLAY_WITH
+  --template-dir TEMPLATE_DIR
+                        Path to a custom template directory. Templates are
+                        searched in the following order: 1) Directory
+                        containing the plain file, 2) Custom template
+                        directory (if provided through this argument), 3)
+                        Built-in standard_template_library directory
+  --copy-build          If set, copy the rendered contents of code in `--base-
+                        folder` folder to `--build-dest` folder after
+                        successful rendering.
+  --build-dest BUILD_DEST
+                        Target folder to copy rendered contents of code to
+                        (used only if --copy-build is set).
+  --copy-conformance-tests
+                        If set, copy the conformance tests of code in
+                        `--conformance-tests-folder` folder to `--conformance-
+                        tests-dest` folder successful rendering. Requires
+                        --conformance-tests-script.
+  --conformance-tests-dest CONFORMANCE_TESTS_DEST
+                        Target folder to copy conformance tests of code to
+                        (used only if --copy-conformance-tests is set).
+  --render-machine-graph
+                        If set, render the state machine graph.
+  --logging-config-path LOGGING_CONFIG_PATH
+                        Path to the logging configuration file.
+  --headless            Run in headless mode: no TUI, no terminal output
+                        except a single render-started message. All logs are
+                        written to the log file.
+
+configuration:
+  --config-name CONFIG_NAME
+                        Name of the config file to look for. Looked up in the
+                        plain file directory and the current working
+                        directory. Defaults to config.yaml.
+
+```

{codeplain-0.3.5 → codeplain-0.3.7}/file_utils.py

@@ -293,7 +293,7 @@ def get_template_directories(plain_file_path, custom_template_dir=None, default_
     3. Default template directory - for standard/fallback templates
     """
     template_dirs = [
-        os.path.dirname(plain_file_path),  # Highest precedence - directory containing plain file
+        os.path.dirname(os.path.abspath(plain_file_path)),  # Highest precedence - directory containing plain file
     ]
 
     if custom_template_dir:

{codeplain-0.3.5 → codeplain-0.3.7}/install/bash/examples.sh

@@ -5,6 +5,7 @@ set -euo pipefail
 # Brand Colors (use exported colors if available, otherwise define them)
 YELLOW="${YELLOW:-\033[38;2;224;255;110m}"
 GREEN="${GREEN:-\033[38;2;121;252;150m}"
+WHITE="${WHITE:-\033[38;2;255;255;255m}"
 RED="${RED:-\033[38;2;239;68;68m}"
 GRAY="${GRAY:-\033[38;2;128;128;128m}"
 BOLD="${BOLD:-\033[1m}"
@@ -16,9 +17,9 @@ EXAMPLES_DOWNLOAD_URL="https://github.com/Codeplain-ai/plainlang-examples/archiv
 
 # Show current directory and ask for extraction path
 CURRENT_DIR=$(pwd)
-echo -e "  current folder: ${YELLOW}${CURRENT_DIR}${NC}"
+echo -e "  Current folder: ${WHITE}${CURRENT_DIR}${NC}"
 echo ""
-echo -e "  extract examples here, or enter a different path:"
+echo -e "  Extract examples here, or enter a different path:"
 echo ""
 read -r -p "  [Enter for current, or type path]: " EXTRACT_PATH < /dev/tty
 echo ""
@@ -35,24 +36,24 @@ SKIP_DOWNLOAD=false
 
 # Check if directory exists, create if not
 if [ ! -d "$EXTRACT_PATH" ]; then
-    echo -e "  ${GRAY}creating directory...${NC}"
+    echo -e "  ${GRAY}Creating directory...${NC}"
     mkdir -p "$EXTRACT_PATH" 2>/dev/null
     if [ $? -ne 0 ]; then
-        echo -e "  ${RED}✗${NC} failed to create directory: ${EXTRACT_PATH}"
-        echo -e "  ${GRAY}skipping example download.${NC}"
+        echo -e "  ${RED}✗ Failed to create directory: ${EXTRACT_PATH}${NC}"
+        echo -e "  ${GRAY}Skipping example download.${NC}"
         SKIP_DOWNLOAD=true
     fi
 fi
 
 if [ "$SKIP_DOWNLOAD" = false ]; then
-    echo -e "  ${GRAY}downloading examples...${NC}"
+    echo -e "  ${GRAY}Downloading examples...${NC}"
 
     # Download the zip file
     TEMP_ZIP=$(mktemp)
     curl -L -s -o "$TEMP_ZIP" "$EXAMPLES_DOWNLOAD_URL"
 
     if [ $? -eq 0 ] && [ -s "$TEMP_ZIP" ]; then
-        echo -e "  ${GRAY}extracting to ${EXTRACT_PATH}...${NC}"
+        echo -e "  ${GRAY}Extracting to ${EXTRACT_PATH}...${NC}"
 
         # Extract the zip file
         unzip -q -o "$TEMP_ZIP" -d "$EXTRACT_PATH" 2>/dev/null
@@ -71,22 +72,32 @@ if [ "$SKIP_DOWNLOAD" = false ]; then
                 rm -f "${EXTRACTED_DIR}/.gitignore"
             fi
 
+            clear
             echo ""
-            echo -e "  ${GREEN}✓${NC} examples downloaded successfully!"
+            echo -e "  ${GREEN}✓ Examples downloaded successfully!${NC}"
             echo ""
-            echo -e "  examples are in: ${YELLOW}${EXTRACTED_DIR}${NC}"
+            echo -e "  ${GRAY}Examples are in: ${EXTRACTED_DIR}${NC}"
+            echo ""
+            echo -e "  ${WHITE}${BOLD}Try the hello, world example:${NC}"
+            echo ""
+            echo -e "  ${GRAY}Example folder:${NC} ${WHITE}cd ${EXTRACTED_DIR}/hello-world/python${NC}"
+            echo ""
+            echo -e "  ${GRAY}Render the example:${NC} ${WHITE}codeplain hello-world-python.plain${NC}"
+            echo ""
+            echo -e "  ${GRAY}See hello-world/python/README.md for details.${NC}"
             echo ""
         else
-            echo -e "  ${RED}✗${NC} failed to extract examples."
+            echo -e "  ${RED}✗ Failed to extract examples.${NC}"
         fi
 
         # Clean up temp file
         rm -f "$TEMP_ZIP"
     else
-        echo -e "  ${RED}✗${NC} failed to download examples."
+        echo -e "  ${RED}✗ Failed to download examples.${NC}"
         rm -f "$TEMP_ZIP"
     fi
 
     echo ""
-    read -r -p "  press [Enter] to continue..." < /dev/tty
+    PROMPT=$(printf '%b' "  Press ${WHITE}[Enter]${NC} to continue...")
+    read -r -p "$PROMPT" < /dev/tty
 fi