plain-forge 1.0.1

package/forge/skills/implement-unit-testing-script/assets/run_unittests_golang.ps1

@@ -0,0 +1,68 @@
+#!/usr/bin/env pwsh
+
+$ErrorActionPreference = 'Stop'
+
+$UNRECOVERABLE_ERROR_EXIT_CODE = 69
+
+# Check if subfolder name is provided
+if (-not $args[0]) {
+    Write-Host "Error: No subfolder name provided."
+    Write-Host "Usage: $($MyInvocation.MyCommand.Name) <subfolder_name>"
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+$BuildFolder = $args[0]
+
+$GO_BUILD_SUBFOLDER = "go_$BuildFolder"
+
+if ($env:VERBOSE -eq "1") {
+    Write-Host "Preparing Go build subfolder: $GO_BUILD_SUBFOLDER"
+}
+
+# Check if the go build subfolder exists
+if (Test-Path $GO_BUILD_SUBFOLDER) {
+    # Delete all files and folders inside
+    Get-ChildItem -Path $GO_BUILD_SUBFOLDER -Force | Remove-Item -Recurse -Force
+
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Cleanup completed."
+    }
+} else {
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Subfolder does not exist. Creating it..."
+    }
+
+    New-Item -ItemType Directory -Path $GO_BUILD_SUBFOLDER -Force | Out-Null
+}
+
+Copy-Item -Path "$BuildFolder/*" -Destination $GO_BUILD_SUBFOLDER -Recurse -Force
+
+# Move to the subfolder
+if (-not (Test-Path $GO_BUILD_SUBFOLDER)) {
+    Write-Host "Error: Go build folder '$GO_BUILD_SUBFOLDER' does not exist."
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+Push-Location $GO_BUILD_SUBFOLDER
+
+try {
+    Write-Host "Running go get..."
+    # Temporarily allow stderr output without throwing (Go tools write to stderr)
+    # ForEach-Object converts ErrorRecord objects (from stderr) to plain strings to avoid verbose error formatting
+    $ErrorActionPreference = 'Continue'
+    $output = go get 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.Exception.Message } else { $_ } } | Out-String
+    $ErrorActionPreference = 'Stop'
+    if ($output.Trim()) { Write-Host $output }
+
+    # Execute all Golang unittests in the subfolder
+    Write-Host "Running Golang unittests in $BuildFolder..."
+    $ErrorActionPreference = 'Continue'
+    $output = go test 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.Exception.Message } else { $_ } } | Out-String
+    $exit_code = $LASTEXITCODE
+    $ErrorActionPreference = 'Stop'
+
+    Write-Host $output
+    exit $exit_code
+} finally {
+    Pop-Location
+}

package/forge/skills/implement-unit-testing-script/assets/run_unittests_java.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+# Check that Java 21 is installed
+if ! /usr/libexec/java_home -v 21 >/dev/null 2>&1; then
+  echo "Error: Java 21 is not installed."
+  exit 69
+fi
+
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+java --version
+
+# Check if subfolder name is provided
+if [ -z "$1" ]; then
+  echo "Error: No subfolder name provided."
+  echo "Usage: $0 <subfolder_name>"
+  exit 1
+fi
+
+# Define the path to the java build subfolder
+WORKING_FOLDER=.tmp/$1
+
+# Check if the java subfolder exists
+if [ -d "$WORKING_FOLDER" ]; then
+  # delete everything in the subfolder
+  rm -rf "$WORKING_FOLDER"/*
+else
+  echo "Subfolder '$WORKING_FOLDER' does not exist. Creating it now..."
+  mkdir -p "$WORKING_FOLDER"
+fi
+
+
+# copy all folders and files from the build folder to the subfolder
+cp -R $1/* $WORKING_FOLDER
+printf "Copied from $1 to $WORKING_FOLDER...\n"
+# Move to the subfolder
+cd "$WORKING_FOLDER" 2>/dev/null
+printf "Moved to $WORKING_FOLDER...\n"
+if [ $? -ne 0 ]; then
+  echo "Error: Subfolder '$1' does not exist."
+  exit 2
+fi
+
+# Execute all Java unittests in the subfolder
+echo "Running Java unittests in $(pwd)..."
+mvn test

package/forge/skills/implement-unit-testing-script/assets/run_unittests_python.ps1

@@ -0,0 +1,76 @@
+#!/usr/bin/env pwsh
+
+$ErrorActionPreference = 'Stop'
+
+$UNRECOVERABLE_ERROR_EXIT_CODE = 69
+
+# Check if subfolder name is provided
+if (-not $args[0]) {
+    Write-Host "Error: No subfolder name provided."
+    Write-Host "Usage: $($MyInvocation.MyCommand.Name) <subfolder_name>"
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+$BuildFolder = $args[0]
+
+# Try to find Python interpreter (python3 first, then python)
+if (Get-Command python3 -ErrorAction SilentlyContinue) {
+    $PYTHON_CMD = "python3"
+} elseif (Get-Command python -ErrorAction SilentlyContinue) {
+    $PYTHON_CMD = "python"
+} else {
+    Write-Host "Error: Python interpreter not found. Please install Python."
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+$PYTHON_BUILD_SUBFOLDER = "python_$BuildFolder"
+
+if ($env:VERBOSE -eq "1") {
+    Write-Host "Preparing Python build subfolder: $PYTHON_BUILD_SUBFOLDER"
+}
+
+# Check if the Python build subfolder exists
+if (Test-Path $PYTHON_BUILD_SUBFOLDER) {
+    # Delete all files and folders inside
+    Get-ChildItem -Path $PYTHON_BUILD_SUBFOLDER -Force | Remove-Item -Recurse -Force
+
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Cleanup completed."
+    }
+} else {
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Subfolder does not exist. Creating it..."
+    }
+
+    New-Item -ItemType Directory -Path $PYTHON_BUILD_SUBFOLDER -Force | Out-Null
+}
+
+Copy-Item -Path "$BuildFolder/*" -Destination $PYTHON_BUILD_SUBFOLDER -Recurse -Force
+
+# Move to the subfolder
+if (-not (Test-Path $PYTHON_BUILD_SUBFOLDER)) {
+    Write-Host "Error: Python build folder '$PYTHON_BUILD_SUBFOLDER' does not exist."
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+Push-Location $PYTHON_BUILD_SUBFOLDER
+
+try {
+    # Execute all Python unittests in the subfolder
+    Write-Host "Running Python unittests in $PYTHON_BUILD_SUBFOLDER..."
+
+    # Temporarily allow stderr output without throwing (Python unittest writes progress to stderr)
+    # ForEach-Object converts ErrorRecord objects (from stderr) to plain strings to avoid verbose error formatting
+    $ErrorActionPreference = 'Continue'
+    $output = & $PYTHON_CMD -m unittest discover -b 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.Exception.Message } else { $_ } } | Out-String
+    $exit_code = $LASTEXITCODE
+    $ErrorActionPreference = 'Stop'
+
+    # Echo the original output
+    Write-Host $output
+
+    # Return the exit code of the unittest command
+    exit $exit_code
+} finally {
+    Pop-Location
+}

package/forge/skills/implement-unit-testing-script/assets/run_unittests_python.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+
+UNRECOVERABLE_ERROR_EXIT_CODE=69
+
+# Check if subfolder name is provided
+if [ -z "$1" ]; then
+  echo "Error: No subfolder name provided."
+  echo "Usage: $0 <subfolder_name>"
+  exit $UNRECOVERABLE_ERROR_EXIT_CODE
+fi
+
+current_dir=$(pwd)
+echo "Current directory: $current_dir"
+echo "Build folder name: $1"
+echo "--------------------------------"
+
+PYTHON_BUILD_SUBFOLDER=.tmp/$1
+
+if [ "${VERBOSE:-}" -eq 1 ] 2>/dev/null; then
+  printf "Preparing Python build subfolder: $PYTHON_BUILD_SUBFOLDER\n"
+fi
+
+rm -rf $PYTHON_BUILD_SUBFOLDER
+mkdir -p $PYTHON_BUILD_SUBFOLDER
+
+cp -R $1/* $PYTHON_BUILD_SUBFOLDER
+
+# Move to the subfolder
+cd "$PYTHON_BUILD_SUBFOLDER" 2>/dev/null
+
+if [ $? -ne 0 ]; then
+  printf "Error: Python build folder '$PYTHON_BUILD_SUBFOLDER' does not exist.\n"
+  exit $UNRECOVERABLE_ERROR_EXIT_CODE
+fi
+
+printf "Creating and activating virtual environment...\n"
+
+# Time the virtual environment creation and activation
+start_time=$(date +%s.%N)
+
+VENV_DIR=".venv"
+
+if ! $PYTHON_CMD -m venv "$VENV_DIR"; then
+    printf "Error: Failed to create virtual environment in '$VENV_DIR'.\n"
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+fi
+
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+if [ $? -ne 0 ]; then
+    printf "Error: Failed to activate virtual environment at '$VENV_DIR/bin/activate'.\n"
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+fi
+
+# Install requirements if requirements.txt exists
+if [ -f "requirements.txt" ]; then
+    pip install --upgrade pip
+    pip install -r requirements.txt
+else
+    echo "Error: requirements.txt not found. Cannot proceed with setting up requirements."
+fi
+
+end_time=$(date +%s.%N)
+
+# Calculate and display the time taken
+duration=$(echo "$end_time - $start_time" | bc)
+printf "Requirements setup completed in %.2f seconds\n\n" "$duration"
+
+
+# Execute all Python unittests in the subfolder
+echo "Running Python unittests in $PYTHON_BUILD_SUBFOLDER..."
+
+output=$(timeout 120s python -m unittest discover -b -v 2>&1)
+exit_code=$?
+
+# Check if the command timed out
+if [ $exit_code -eq 124 ]; then
+    printf "\nError: Unittests timed out after 120 seconds.\n"
+    exit $exit_code
+fi
+
+# Echo the original output
+echo "$output"
+
+# Return the exit code of the unittest command
+exit $exit_code
+
+# Note: The 'discover' option automatically identifies and runs all unittests in the current directory and subdirectories
+# Ensure that your Python files are named according to the unittest discovery pattern (test*.py by default)

package/forge/skills/implement-unit-testing-script/assets/run_unittests_react.ps1

@@ -0,0 +1,83 @@
+#!/usr/bin/env pwsh
+
+$ErrorActionPreference = 'Stop'
+
+$UNRECOVERABLE_ERROR_EXIT_CODE = 69
+
+# ANSI escape code pattern to remove color codes and formatting from output
+$ANSI_ESCAPE_PATTERN = '\x1b\[[0-9;]*[mK]'
+
+# Check if subfolder name is provided
+if (-not $args[0]) {
+    Write-Host "Error: No subfolder name provided."
+    Write-Host "Usage: $($MyInvocation.MyCommand.Name) <subfolder_name>"
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+$BuildFolder = $args[0]
+
+# Define the path to the subfolder
+$NODE_SUBFOLDER = "node_$BuildFolder"
+
+if ($env:VERBOSE -eq "1") {
+    Write-Host "Preparing Node subfolder: $NODE_SUBFOLDER"
+}
+
+# Check if the node subfolder exists
+if (Test-Path $NODE_SUBFOLDER) {
+    # Delete all files and folders except "node_modules", "build", and "package-lock.json"
+    Get-ChildItem -Path $NODE_SUBFOLDER -Force |
+        Where-Object {
+            $_.Name -ne "node_modules" -and
+            $_.Name -ne "build" -and
+            $_.Name -ne "package-lock.json"
+        } | Remove-Item -Recurse -Force
+
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Cleanup completed, keeping 'node_modules' and 'package-lock.json'."
+    }
+} else {
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Subfolder does not exist. Creating it..."
+    }
+
+    New-Item -ItemType Directory -Path $NODE_SUBFOLDER -Force | Out-Null
+}
+
+Copy-Item -Path "$BuildFolder/*" -Destination $NODE_SUBFOLDER -Recurse -Force
+
+# Move to the subfolder
+if (-not (Test-Path $NODE_SUBFOLDER)) {
+    Write-Host "Error: Subfolder '$BuildFolder' does not exist."
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+Push-Location $NODE_SUBFOLDER
+
+try {
+    # Install libraries
+    npm install
+
+    # Execute all React unittests in the subfolder
+    Write-Host "Running React unittests in $BuildFolder..."
+    # Temporarily allow stderr output without throwing (npm/jest may write to stderr)
+    # ForEach-Object converts ErrorRecord objects (from stderr) to plain strings to avoid verbose error formatting
+    $ErrorActionPreference = 'Continue'
+    $output = npm test -- --runInBand --silent --detectOpenHandles 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.Exception.Message } else { $_ } } | Out-String
+    $TEST_EXIT_CODE = $LASTEXITCODE
+    $ErrorActionPreference = 'Stop'
+
+    # Strip ANSI escape codes
+    $output = $output -replace $ANSI_ESCAPE_PATTERN, ''
+    Write-Host $output
+
+    # Check if tests failed
+    if ($TEST_EXIT_CODE -ne 0) {
+        Write-Host "Error: Tests failed with exit code $TEST_EXIT_CODE"
+        exit $TEST_EXIT_CODE
+    }
+
+    exit $TEST_EXIT_CODE
+} finally {
+    Pop-Location
+}

package/forge/skills/init-config-file/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: init-config-file
+description: >-
+  Build / finalize the `config.yaml` file(s) that the `codeplain` renderer
+  consumes. Pulls together every decision made during Phase 3 of `forge-plain`
+  (script paths, template directory, build folders, copy/dest behavior, log
+  settings) and emits one canonical `config.yaml` per part of the project.
+  Run this at the **end of `forge-plain`** (just before `plain-healthcheck`),
+  at the end of `add-feature` whenever the testing surface or template
+  directory changed, and any time the user wants to regenerate / consolidate
+  a project's `config.yaml`.
+---
+
+# Init Config File
+
+This skill is the **single authoritative writer** of `config.yaml` for a ***plain project. Anything that ends up in `config.yaml` should go through this skill. The renderer (`codeplain`) reads each key listed below into the same argparse namespace it uses for CLI flags — so a value set in `config.yaml` is exactly equivalent to passing the corresponding `--flag` on the command line.
+
+## When to run
+
+- **End of `forge-plain` Phase 3 / start of Phase 4** — after every test-script decision is locked in (unit tests, conformance tests, prepare-environment), before delegating to `plain-healthcheck`.
+- **End of `add-feature`** — only when Phase 3 of the feature touched the testing surface (new script generated, script removed, template directory introduced).
+- **End of any single-skill workflow that finalizes a script or template** — e.g. after `implement-unit-testing-script`, `implement-conformance-testing-script`, `implement-prepare-environment-script`, `add-template`, or `create-import-module`.
+- **On demand** — when the user asks "rebuild my config", "what valid keys are there", or you discover the config file is hand-edited / inconsistent.
+
+If you only fixed a typo inside a `.plain` file and the testing surface didn't move, you do **not** need to re-run this skill — go straight to `plain-healthcheck`.
+
+## What this skill does
+
+1. Determines **how many** `config.yaml` files the project needs (one per part — see [Per-part split](#per-part-split)).
+2. For each config, gathers the decided values from the current project state (existing scripts under `test_scripts/`, the template directory, the build/dest folder choices).
+3. Emits a clean, alphabetically-grouped `config.yaml` containing **only** keys that are actually in use, using the canonical key names from the [Valid keys reference](#valid-keys-reference).
+4. Verifies that every `*-script` value points at a file that exists on disk under `test_scripts/` (or wherever the user placed it), using the same lookup rule the renderer uses: absolute path → path relative to the config file's directory → path relative to the renderer's directory.
+5. Hands off to `plain-healthcheck` for the full validation pass.
+
+## What this skill does NOT do
+
+- It does **not** generate testing scripts. Use `implement-unit-testing-script`, `implement-conformance-testing-script`, or `implement-prepare-environment-script` first; this skill only wires them in.
+- It does **not** decide *whether* the user wants conformance tests, a prepare-environment script, copy-build, etc. Those decisions belong to `forge-plain` Phase 3. This skill only **records** them.
+- It does **not** invent values for keys whose decisions weren't made — it leaves them out (the renderer falls back to its default) rather than guessing.
+- It does **not** write secrets. `api-key` belongs in the `CODEPLAIN_API_KEY` environment variable, never in `config.yaml`.
+
+## Valid keys reference
+
+The canonical list of keys is derived from the `codeplain` CLI argparse parser. Every key below corresponds to exactly one `--flag` and is read by the renderer through `update_args_with_config`. **No other keys are valid** — the renderer rejects unknown keys with `parser.error(f"Invalid argument: {key}")`.
+
+YAML keys use the **dashed** form (e.g. `unittests-script`, not `unittests_script`) to mirror the CLI flag spelling. The only exception that has historically appeared with underscores is `template_dir`; prefer `template-dir` for new configs but accept either when reading an existing file.
+
+### Keys you typically include
+
+These keys reflect choices made in Phase 3 of `forge-plain` and are the bread and butter of a project's `config.yaml`:
+
+| Key | Type | Default | When to include |
+|---|---|---|---|
+| `unittests-script` | path (string) | — | **Required.** Every project gets a unit-test runner. Path resolves relative to the config file's directory (preferred) or the renderer directory. |
+| `conformance-tests-script` | path (string) | — | Include when the user opted into conformance testing in Phase 3. |
+| `prepare-environment-script` | path (string) | — | Include only when both (a) the user opted into a prepare-environment script and (b) `conformance-tests-script` is also set. Setting prepare without conformance is a hard `plain-healthcheck` failure. |
+| `test-script-timeout` | int (seconds) | `120` | Include only when the user explicitly raised/lowered the default. |
+| `template-dir` | path (string) | — | Include whenever the project has an `import` module or a custom template directory (e.g. `template/`). Required for projects with shared templates. |
+| `logging-config-path` | path (string) | `logging_config.yaml` | Points at a **separate** YAML file consumed by Python's `logging.config.dictConfig`. This is the only knob that lets the user actually change log **levels** for the renderer and its dependencies. See [Logging configuration](#logging-configuration) below. Include the key explicitly whenever the project ships a non-default logging config; leave it out only when the user is happy with the renderer's defaults (`INFO` root, `WARNING` for `git`, `ERROR` for `transitions`). |
+| `conformance-tests-folder` | string | `conformance_tests` | Include only when the user picked a non-default folder name. |
+| `build-folder` | string | `plain_modules` | Include only when the user picked a non-default folder name. Must differ from `build-dest`. |
+| `build-dest` | string | `dist` | **Always include with the value `dist`.** This skill pins the copy destination explicitly so every project's `config.yaml` has the same, predictable target folder for the post-render copy. Even though `dist` matches the renderer's default, we still write it out so the choice is visible in the file and protected against future default changes. Must differ from `build-folder`. |
+| `base-folder` | string | — | Include when the user wants build output rooted somewhere other than the project root. |
+
+### Keys you occasionally include
+
+These are useful but the defaults are almost always fine. Only include them when the user explicitly changed the default during Phase 3:
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `copy-build` | bool | `true` | The renderer copies the rendered code to `build-dest` after a successful render. Set to `false` only when the user doesn't want this. |
+| `copy-conformance-tests` | bool | `false` | Requires `conformance-tests-script` to also be set. |
+| `conformance-tests-dest` | string | `dist_conformance_tests` | Target folder for the conformance-test copy. Must differ from `conformance-tests-folder`. |
+| `log-to-file` | bool | `true` | Disable only when the user explicitly does not want a log file. Controls whether logs are mirrored to disk — it does **not** set the log level (that's `logging-config-path`'s job). |
+| `log-file-name` | string | `codeplain.log` | If `log-to-file` is `false`, this key must be left out. Resolved relative to the `.plain` file directory. |
+| `render-machine-graph` | bool | `false` | Include only when the user wants the state-machine graph rendered. |
+| `headless` | bool | `false` | Include only when the project is meant to run in CI / non-interactive mode by default. |
+| `force-render` | bool | `false` | Almost never belongs in `config.yaml`; prefer the CLI flag for one-off forced renders. |
+| `verbose` | bool | `false` | Almost never belongs in `config.yaml`; prefer the CLI flag for one-off verbose runs. |
+| `api` | URL (string) | `https://api.codeplain.ai` | Include only when the user is pointing at a non-default API endpoint. |
+
+### Keys you must NEVER include
+
+These flags are **per-invocation** or **secret**. Putting them in `config.yaml` is always wrong:
+
+| Key | Why it doesn't belong |
+|---|---|
+| `api-key` | Secret. Belongs in the `CODEPLAIN_API_KEY` environment variable. Never in a file the user might commit. |
+| `dry-run` | Per-invocation. `plain-healthcheck` runs the dry-run explicitly; pinning it in the config would make a real render impossible. |
+| `full-plain` | Per-invocation preview. Mutually exclusive with `dry-run`. |
+| `render-range` | Per-invocation. Selects a slice of functionalities to (re)render. |
+| `render-from` | Per-invocation. Mutually exclusive with `render-range`. |
+| `replay-with` | Internal / debugging flag. |
+| `config-name` | Refers to the config file itself — the renderer ignores it when reading the config. |
+| `filename` | The `.plain` file to render is always passed positionally on the CLI. |
+
+If the user asks to put any of these in `config.yaml`, refuse and explain why.
+
+## Logging configuration
+
+Log **levels** are not controlled directly by `config.yaml` — they live in a separate YAML file that the renderer feeds to Python's `logging.config.dictConfig`. The `config.yaml` key `logging-config-path` is the pointer that wires the two together.
+
+### How the renderer assembles logging
+
+From `setup_logging` in the `codeplain` source:
+
+1. The renderer first installs a set of **baseline levels**:
+   - root logger → `INFO`
+   - `LOGGER_NAME` (the renderer's own logger) → `INFO`
+   - `git` → `WARNING`
+   - `transitions` → `ERROR`
+   - `transitions.extensions.diagrams` → `ERROR`
+2. **If** `args.logging_config_path` resolves to an existing file on disk, the renderer loads that YAML and calls `logging.config.dictConfig(...)` on it. This overlays anything from step 1 — the user can raise, lower, or add levels for any logger they care about, add handlers, change formatters, etc.
+3. The renderer then attaches its own handlers (TUI handler unless `headless`, file handler if `log-to-file`, crash buffer otherwise). Whatever **level** the root logger ended up at after step 2 is the level those handlers respect.
+
+In other words: `logging-config-path` is the **only** knob that changes the levels. `log-to-file` and `log-file-name` only control *whether and where* logs are written — not *what* gets written.
+
+### Default behavior
+
+- The CLI default value for `logging-config-path` is `logging_config.yaml`. If a file by that exact name exists in the current working directory, it will be loaded automatically — even without `logging-config-path` being set in `config.yaml`.
+- If the file does not exist, the renderer silently keeps the baseline levels from step 1 above (no warning).
+- If the file exists but fails to parse / apply, the renderer warns (`Failed to load logging configuration from …`) and falls back to the baseline.
+
+This means **the mere presence of a `logging_config.yaml` file is itself a config decision.** When you assemble a project's `config.yaml`, you have three cases:
+
+| Situation | What to do |
+|---|---|
+| The user is happy with the baseline levels and the project has no `logging_config.yaml` on disk. | Leave `logging-config-path` out of `config.yaml`. |
+| The user wants custom levels and is fine with the file being named `logging_config.yaml` next to the `.plain` file. | Create that file (see [Recommended logging config](#recommended-logging-config) below). Leaving `logging-config-path` out of `config.yaml` is fine — the default points at it already — but explicitly setting `logging-config-path: logging_config.yaml` is also acceptable and makes the dependency visible to anyone reading the config. |
+| The user wants the logging config file to live somewhere non-default (different filename or directory). | Create the file at the chosen path and set `logging-config-path: <that path>` in `config.yaml`. |
+
+When in doubt, ask the user: "Do you want to change the default log levels (INFO for the renderer, WARNING for git, ERROR for transitions), or stick with the defaults?" Only generate / pin the file when they say yes.
+
+### Recommended logging config
+
+When the user does want custom levels, write a minimal `dictConfig`-style YAML file. Example with two common knobs (verbose renderer logs, plus suppression of a chatty third-party logger):
+
+```/dev/null/logging_config.yaml.example#L1-15
+version: 1
+disable_existing_loggers: false
+formatters:
+  default:
+    format: "%(levelname)s:%(name)s:%(message)s"
+handlers:
+  console:
+    class: logging.StreamHandler
+    formatter: default
+    level: DEBUG
+loggers:
+  codeplain:
+    level: DEBUG
+  urllib3:
+    level: WARNING
+root:
+  level: INFO
+  handlers: [console]
+```
+
+Guidelines for what to put in this file:
+
+- Always set `version: 1` — `dictConfig` requires it.
+- Set `disable_existing_loggers: false` unless the user explicitly wants to silence loggers that were created before `dictConfig` ran. The renderer creates several before it loads this file, and disabling them by default leads to confusing dead silence.
+- Only override levels the user actually asked about. Don't preemptively add every logger the codebase touches — that creates ongoing maintenance for no benefit.
+- Don't put the `LoggingHandler` / `CrashLogHandler` / `FileHandler` here — the renderer attaches those itself after `dictConfig` runs. Adding them here will cause duplicate log lines.
+- This file is **not** validated by `plain-healthcheck`. If you change it, ask the user to confirm by reading it back to them.
+
+## Per-part split
+
+The rule, which mirrors what `forge-plain` Phase 3 already establishes, is **one `config.yaml` per part of the system that has its own testing scripts**:
+
+- **Single-stack project** (e.g. one Python service) → one `config.yaml` at the project root.
+- **Multi-part project** (e.g. Python backend + React frontend) → one `config.yaml` per part, placed next to the part's top module (e.g. `backend/config.yaml`, `frontend/config.yaml`). Each config references only its own scripts; **never mix stacks in a single config**.
+- A part's split should follow the module boundaries from Phase 1 / Phase 2: if a module has its own language, framework, and test scripts, it gets its own `config.yaml` next to that module.
+
+Before emitting anything, state the planned split to the user (e.g. "I'll emit `backend/config.yaml` and `frontend/config.yaml`") if there is more than one part.
+
+## Workflow
+
+### Step 1 — Inventory
+
+1. List every `.plain` file in the repo and identify the top modules (modules not `requires`-ed by anything else) — same procedure as `plain-healthcheck` Step 1.
+2. For each top module, determine which part it belongs to (single-stack → one part; multi-part → one part per top module).
+3. List every script under `test_scripts/` and group them by part (e.g. `*_python.sh` belongs to the backend part, `*_js.sh` belongs to the frontend part).
+4. Identify the template directory (typically `template/`) and any custom resource directories (typically `resources/`).
+5. Read any **existing** `config.yaml` in each part's directory — preserve any user-set fields not listed in [Valid keys reference](#valid-keys-reference) only with the user's explicit approval, and warn that unknown keys will be rejected by the renderer.
+
+### Step 2 — Assemble per-part values
+
+For each part:
+
+1. Start from an empty key set.
+2. Add `unittests-script: test_scripts/run_unittests_<lang>.<sh|ps1>` — required. If the script doesn't exist yet, stop and tell the caller to run `implement-unit-testing-script` first.
+3. If the part has a conformance script on disk → add `conformance-tests-script: …`.
+4. If the part has a prepare-environment script on disk → first verify `conformance-tests-script` is also being added; if not, stop and surface this to the user (offer to either generate the missing conformance script via `implement-conformance-testing-script` or drop the prepare-environment script).
+5. If the project has shared templates → add `template-dir: template` (or whatever path the user used).
+6. **Always add `build-dest: dist`.** This skill pins the copy destination on every config it writes, regardless of what Phase 3 said about it. If Phase 3 explicitly asked for a different `build-dest`, stop and surface the conflict to the user — do not silently honor the override.
+7. For every other key in [Valid keys reference](#valid-keys-reference), include it **only** if Phase 3 produced a non-default decision for that key.
+8. Cross-validate the assembled key set:
+   - `build-dest` is set to `dist`.
+   - `build-folder` ≠ `build-dest` (in particular, `build-folder` is never `dist`).
+   - `conformance-tests-folder` ≠ `conformance-tests-dest`.
+   - `copy-conformance-tests: true` requires `conformance-tests-script`.
+   - `log-file-name` is set ⇒ `log-to-file` is not `false`.
+   - All `*-script` paths resolve on disk (absolute → relative to config dir → relative to renderer dir).
+   - No script path crosses stacks (e.g. `backend/config.yaml` must not reference `run_unittests_js.sh`).
+
+### Step 3 — Emit `config.yaml`
+
+For each part, write a clean YAML file:
+
+- One key per line, in the order they appear in [Valid keys reference](#valid-keys-reference) (script paths first, then template/build folders, then copy/log settings).
+- Use dashed key names. Quote string values only when YAML requires it.
+- No comments inside the file — keep it machine-parseable. If the user needs a comment, put it in the surrounding spec or README.
+- Idempotent: re-running this skill on an unchanged project produces a byte-for-byte identical file.
+
+Example for a single-stack Python project with conformance testing and a prepare-environment script:
+
+```/dev/null/config.yaml.example#L1-5
+unittests-script: test_scripts/run_unittests_python.sh
+conformance-tests-script: test_scripts/run_conformance_tests_python.sh
+prepare-environment-script: test_scripts/prepare_environment_python.sh
+template-dir: template
+build-dest: dist
+```
+
+Example for a multi-part project (`backend/config.yaml`):
+
+```/dev/null/config.yaml.example#L1-4
+unittests-script: test_scripts/run_unittests_python.sh
+conformance-tests-script: test_scripts/run_conformance_tests_python.sh
+template-dir: ../template
+build-dest: dist
+```
+
+### Step 4 — Hand off
+
+Tell the caller exactly which file(s) were written and invoke `plain-healthcheck` to validate the project end-to-end. Do **not** declare success on your own — `plain-healthcheck` is the source of truth for "is this project ready to render?".
+
+## Anti-patterns
+
+- **Inventing values for keys the user never decided on.** Leave them out and let the renderer use its default.
+- **Mixing stacks in one config.** `backend/config.yaml` referencing a JS script is always a bug — split into per-part configs instead.
+- **Putting `api-key`, `dry-run`, `full-plain`, `render-range`, `render-from`, `replay-with`, `config-name`, or `filename` in `config.yaml`.** All of these are per-invocation or secret; the renderer treats them as command-line concerns.
+- **Emitting `prepare-environment-script` without `conformance-tests-script`.** A prepare-environment script only makes sense in service of conformance tests; without one, `plain-healthcheck` will fail.
+- **Hand-merging into an existing config.yaml without re-running this skill.** If the user edited the config manually, re-run the skill to re-derive a clean canonical version (after confirming any custom fields with the user).
+- **Reading the renderer's API key from a project file.** Always rely on `CODEPLAIN_API_KEY`.
+
+## Validation Checklist
+
+- [ ] One `config.yaml` exists per part of the system (single-stack → root; multi-part → per part).
+- [ ] Every `config.yaml` has at minimum `unittests-script`.
+- [ ] Every `*-script` value points at a file that exists on disk.
+- [ ] No `config.yaml` declares `prepare-environment-script` without also declaring `conformance-tests-script`.
+- [ ] No `config.yaml` mixes stacks (every script in it targets the same language).
+- [ ] `build-dest` is set to `dist` in every emitted `config.yaml`.
+- [ ] `build-folder` ≠ `build-dest`; `conformance-tests-folder` ≠ `conformance-tests-dest`.
+- [ ] `copy-conformance-tests: true` only when `conformance-tests-script` is set.
+- [ ] `log-file-name` only when `log-to-file` is not `false`.
+- [ ] No forbidden keys (`api-key`, `dry-run`, `full-plain`, `render-range`, `render-from`, `replay-with`, `config-name`, `filename`).
+- [ ] `template-dir` set whenever the project has shared templates or import modules.
+- [ ] `plain-healthcheck` returned `PASS` after the config(s) were written.