plain-forge 1.0.22-next.e8a40fd → 1.0.22

package/README.md

@@ -4,7 +4,7 @@
 
 # plain-forge
 
-A toolkit for working with [∗∗∗plain](https://plainlang.org) projects from inside your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, and any other agent that reads from a standard skills directory. plain-forge ships skills, rules, and docs that turn a conversation into complete `.plain` spec files, then keeps maintaining them across the lifetime of the project. The specs are rendered into production-ready code by the [codeplain](https://codeplain.ai) renderer.
+A toolkit for working with [∗∗∗plain](https://plainlang.org) projects from inside your AI coding agent of choice — Claude Code, Codex, ForgeCode, OpenCode, and any other agent that reads from a standard skills directory. plain-forge ships skills, rules, and docs that turn a conversation into complete `.plain` spec files, then keeps maintaining them across the lifetime of the project. The specs are then rendered into production-ready code by a ***plain renderer.
 
 ## What plain-forge does
 
@@ -14,7 +14,7 @@ plain-forge is organized around four kinds of work, each with its own entry-poin
 
 Pick whichever entry point matches how much upfront design you want:
 
-- **`forge-plain`** — full end-to-end interview. One question at a time, immediate writes to disk, covers product → tech stack → testing → validation in four phases. Produces a complete `.plain` project with `config.yaml`, test scripts, and a successful `codeplain --dry-run` before handing off.
+- **`forge-plain`** — full end-to-end interview. One question at a time, immediate writes to disk, covers product → tech stack → testing → validation in four phases. Produces a complete `.plain` project with `config.yaml`, test scripts, and a passing `plain-healthcheck` before handing off.
 - **`init-plain-project`** — lightweight scaffold. Asks only about the base technology, project kind, and whether conformance testing is on; emits a template module, a stub top-level module, the testing scripts, and a `config.yaml`. No interview, no specs — pair it with `add-feature` to grow the project feature by feature.
 
 ### 2. Grow an existing project
@@ -25,15 +25,14 @@ Pick whichever entry point matches how much upfront design you want:
 
 ### 3. Validate and maintain
 
-- **`plain-healthcheck`** — the verification gate. Inventories every `.plain` module, validates every `config.yaml`, and dry-runs every top module with the right config. Returns `PASS` / `FAIL` with a numbered punch-list when something is broken.
+- **`plain-healthcheck`** — the verification gate. Inventories every `.plain` module, validates every `config.yaml`, parses every top module with [`plain-parser`](https://github.com/plainlang/plain-parser), and checks every module against the ***plain rules. Returns `PASS` / `FAIL` with a numbered punch-list when something is broken.
 - **`init-config-file`** — assembles the canonical `config.yaml` per part of a project from the decisions made during interviewing.
-- **`check-plain-env`** — probes the host machine for everything the project needs (language toolchains, external services, system binaries, drivers, `codeplain` itself) and emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands.
+- **`check-plain-env`** — probes the host machine for everything the project needs (language toolchains, external services, system binaries, drivers) and emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands.
 - **`analyze-func-specs`** / **`analyze-if-func-spec-too-complex`** / **`break-down-func-spec`** / **`resolve-spec-conflict`** — the spec-quality toolchain that runs behind `add-feature` and `forge-plain` but can also be invoked directly when reviewing or refactoring.
 
-### 4. Debug and render
+### 4. Debug and test
 
 - **`debug-specs`** — when the rendered app misbehaves, this traces the generated code back to the spec that caused it and fixes the spec (never the generated code).
-- **`run-codeplain`** — experimental supervised render. Launches `codeplain` for you, tails the log, watches generated code appear under `plain_modules/`, and detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures). On approval it stops the renderer, hands off to the right spec-edit skill, and resumes.
 - **`render-spec`** — [pyro](https://github.com/plainlang/pyro), the open-source ***plain renderer, bundled with plain-forge. Renders a `.plain` module (and the modules it requires or imports) into working, tested code directly inside your agent. See [Render with pyro](#render-with-pyro).
 - **`implement-unit-testing-script`** / **`implement-conformance-testing-script`** / **`implement-prepare-environment-script`** — generate the per-language testing scripts that the renderer and you both invoke. New languages can be added by these skills without touching any other part of the project.
 
@@ -57,6 +56,8 @@ This prompts you to pick an agent and a scope using an arrow-key menu. You can a
 npx plain-forge install --agent claude --scope project
 ```
 
+`install` also installs [`plain-parser`](https://pypi.org/project/plain-parser/), the Python CLI that `plain-healthcheck` uses to validate `.plain` files. It installs it with [uv](https://docs.astral.sh/uv/), installing uv first if it is missing, on Linux, macOS and Windows alike. If plain-parser is already on your `PATH`, nothing is installed. Pass `--skip-plain-parser` to leave both alone.
+
 **Agent options:**
 
 | `--agent` | Installs into (project · global) | Use when |
@@ -148,6 +149,7 @@ If an install has **no manifest** (e.g. one that predates manifests), `uninstall
 
 1. Open your project folder and start a session in your favorite AI coding agent (Claude Code, OpenCode, Codex, …).
 2. Make sure the plain-forge skills are available in that session.
+3. Make sure [`plain-parser`](https://pypi.org/project/plain-parser/) is installed. `plain-healthcheck` uses it to validate `.plain` files. `npx plain-forge install` installs it for you; otherwise run `uv tool install plain-parser` or `pipx install plain-parser` (Python 3.11 or newer).
 
 ### Starting a new project
 
@@ -159,7 +161,7 @@ If an install has **no manifest** (e.g. one that predates manifests), `uninstall
 
 If you'd rather skip the full upfront interview and build the specs feature-by-feature, use this lighter loop:
 
-1. Invoke `init-plain-project`. It asks just for the base technology, the project kind, and whether conformance testing is enabled, then scaffolds the project skeleton: `template/base.plain` with the base `***implementation reqs***` and `***test reqs***`, a stub top-level `<project>.plain` (frontmatter only — no functional specs, no concepts), the unit-test script, an optional conformance-test script, an optional prepare-environment script, and a `config.yaml` wired to whichever scripts were generated. No `codeplain --dry-run` is run.
+1. Invoke `init-plain-project`. It asks just for the base technology, the project kind, and whether conformance testing is enabled, then scaffolds the project skeleton: `template/base.plain` with the base `***implementation reqs***` and `***test reqs***`, a stub top-level `<project>.plain` (frontmatter only — no functional specs, no concepts), the unit-test script, an optional conformance-test script, an optional prepare-environment script, and a `config.yaml` wired to whichever scripts were generated. The project is not validated.
 2. From there, either:
    - **Converse with the agent.** Just describe the next feature in plain English; the agent will invoke `add-feature` for you and run its one-question-at-a-time loop until the feature is on disk.
    - **Invoke `add-feature` manually** whenever you want to drive the loop yourself.
@@ -174,19 +176,7 @@ If you'd rather skip the full upfront interview and build the specs feature-by-f
 
 ### Rendering specs
 
-Once your `.plain` files are ready (and `plain-healthcheck` is green), render the specs into code with the [Codeplain](https://codeplain.ai) renderer:
-
-```bash
-codeplain <module>.plain
-```
-
-plain-forge prints the exact command (with the right final module name) at the end of Phase 4.
-
-#### Supervised render (experimental)
-
-If you'd rather have plain-forge babysit the run from your AI coding agent, invoke `run-codeplain`. It launches the renderer for you, tails `codeplain.log`, watches generated code appear under `plain_modules/`, and surfaces what's happening in plain English. If it detects a pathology (stuck conformance loop, complexity error, missing concept, render failure), it asks for approval to stop the renderer, hands off to the right spec-edit skill (`debug-specs`, `resolve-spec-conflict`, `break-down-func-spec`, …), and resumes the render from the last completed functionality via `--render-from`.
-
-This is an **experimental** feature — the default and most reliable way to render is still the manual `codeplain <module>.plain` invocation above.
+Once your `.plain` files are ready (and `plain-healthcheck` is green), render the specs into code with a ***plain renderer, passing it the final module in the dependency chain. plain-forge names that module at the end of Phase 4.
 
 #### Render with pyro
 
@@ -227,6 +217,7 @@ forge/                       # canonical content, copied verbatim on install
 
 bin/
   cli.mjs                    # the `plain-forge` CLI — `install` and `update` commands
+  python-tools.mjs           # installs uv + plain-parser during `install` (until plain-parser ships on npm)
 
 vendor/
   pyro/                      # git submodule: plainlang/pyro, pinned to the release plain-forge ships
@@ -237,8 +228,9 @@ scripts/
 
 test/
   cli.test.mjs               # tests for the install / update CLI
+  python-tools.test.mjs      # tests for the uv + plain-parser install step
 
-package.json                 # ships only `bin/cli.mjs` and `forge/` to npm
+package.json                 # ships only `bin/cli.mjs`, `bin/python-tools.mjs` and `forge/` to npm
 ```
 
 ### Bundled pyro skill
@@ -270,10 +262,9 @@ On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them int
 | Skill | Description |
 |-------|-------------|
 | `forge-plain` | End-to-end QA interview that produces complete `.plain` spec files for a new project |
-| `init-plain-project` | Lightweight project initializer — scaffolds `template/base.plain` (base impl + test reqs), a stub top-level module, the testing scripts, and `config.yaml`. No functional specs, no concepts, no dry-run. Pair with `add-feature` to grow the project feature-by-feature. |
+| `init-plain-project` | Lightweight project initializer — scaffolds `template/base.plain` (base impl + test reqs), a stub top-level module, the testing scripts, and `config.yaml`. No functional specs, no concepts, no validation. Pair with `add-feature` to grow the project feature-by-feature. |
 | `add-feature` | Interview the user about a single feature, then write all the specs for it |
 | `render-spec` | [pyro](https://github.com/plainlang/pyro), the open-source renderer: renders a `.plain` module and the modules it requires or imports into working, tested code, from inside your agent. See [Render with pyro](#render-with-pyro). |
-| `run-codeplain` | **Experimental.** Launch a `codeplain` render and supervise it end-to-end — tails `codeplain.log`, watches generated code appear, detects pathologies (stuck conformance loops, complexity errors, missing concepts, render failures), and on approval stops the renderer, hands off to the right spec-edit skill, and resumes with `--render-from`. The default render path is still the manual `codeplain <module>.plain` command. |
 
 ### Spec Authoring
 
@@ -301,9 +292,9 @@ On `install`, the CLI reads `forge/skills` and `forge/rules` and writes them int
 
 | Skill | Description |
 |-------|-------------|
-| `init-config-file` | Build / finalize the project's `config.yaml` file(s) from the decisions made in Phase 3. Knows the full set of valid keys derived from the `codeplain` CLI, refuses to write secrets or per-invocation flags, and produces one config per part of the project. Run at the end of `forge-plain` (just before `plain-healthcheck`) and any time the testing surface changes. |
-| `plain-healthcheck` | Verification gate: validates every `config.yaml`, confirms each `*-script` field points at a real file in `test_scripts/`, and dry-runs every top module. Run whenever anything in the project is finalized — at the end of `forge-plain`, at the end of `add-feature`, after `debug-specs`, and after any single-skill edit that touches the renderable surface. |
-| `check-plain-env` | Read the project's `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/`, then probe the host for every requirement **the package manager can't install**: language toolchains (`python` + `pip`, `node` + `npm`, JDK + `mvn`, Go, Rust, .NET, etc.), external services (Postgres, Redis, Docker, ...), system binaries that language packages wrap (`ffmpeg`, `tesseract`, `pdftoppm`, browser binaries, ...), hardware / drivers / accelerators (NVIDIA driver → CUDA toolkit → cuDNN → framework-sees-GPU chain), `codeplain` itself, and credential env vars. Does **not** probe individual language packages — `pip install -r requirements.txt` (and equivalents) handle those when the test scripts run. Emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. Read-only — never installs anything. Run on first-time setup, before rendering on a new machine, after adding a new tech to a project, or any time `command not found` shows up in test output. |
+| `init-config-file` | Build / finalize the project's `config.yaml` file(s) from the decisions made in Phase 3. Knows the full set of valid keys, refuses to write secrets or per-invocation options, and produces one config per part of the project. Run at the end of `forge-plain` (just before `plain-healthcheck`) and any time the testing surface changes. |
+| `plain-healthcheck` | Verification gate: validates every `config.yaml`, confirms each `*-script` field points at a real file in `test_scripts/`, runs `plain-parser check` on every top module, and checks every module against the rules. Run whenever anything in the project is finalized — at the end of `forge-plain`, at the end of `add-feature`, after `debug-specs`, and after any single-skill edit that touches the renderable surface. |
+| `check-plain-env` | Read the project's `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/`, then probe the host for every requirement **the package manager can't install**: language toolchains (`python` + `pip`, `node` + `npm`, JDK + `mvn`, Go, Rust, .NET, etc.), external services (Postgres, Redis, Docker, ...), system binaries that language packages wrap (`ffmpeg`, `tesseract`, `pdftoppm`, browser binaries, ...), hardware / drivers / accelerators (NVIDIA driver → CUDA toolkit → cuDNN → framework-sees-GPU chain), credential env vars, and `plain-parser`. Does **not** probe individual language packages — `pip install -r requirements.txt` (and equivalents) handle those when the test scripts run. Emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. Read-only — never installs anything. Run on first-time setup, before rendering on a new machine, after adding a new tech to a project, or any time `command not found` shows up in test output. |
 | `analyze-if-func-spec-too-complex` | Check if a spec exceeds the 200-line complexity limit |
 | `analyze-func-specs` | Check a batch of specs (2+) against each other in one call and return every conflicting pair |
 | `analyze-2-func-specs` | Legacy: check exactly two specs for conflicts (prefer `analyze-func-specs`) |

package/bin/cli.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 
+import { ensurePlainParser } from "./python-tools.mjs";
+
 const __filename = fileURLToPath(import.meta.url);
 const pkgRoot = path.resolve(path.dirname(__filename), "..");
 const forgeDir = path.join(pkgRoot, "forge");
@@ -117,6 +119,7 @@ Install options:
   --agent <claude|codex|copilot|forgecode|opencode|universal>
                                                Target agent layout
   --scope <project|global>                     Install into cwd or $HOME
+  --skip-plain-parser                          Don't install plain-parser (and uv)
   -h, --help                                   Show this help
 
 Update options:
@@ -139,6 +142,8 @@ Examples:
 
 "install" fails if plain-forge is already installed at the target — use
 "update" to refresh it. Missing install flags are prompted interactively.
+"install" also installs plain-parser, which the healthcheck uses to validate
+.plain files, with uv (installing uv first if it is missing).
 "update" auto-detects installs and prunes only files plain-forge wrote
 (confirming each removal), leaving your own and third-party skills untouched.
 "uninstall" deletes exactly the files recorded in the install manifest, then
@@ -152,6 +157,7 @@ function parseArgs(argv) {
     if (a === "--agent") out.agent = argv[++i];
     else if (a === "--scope") out.scope = argv[++i];
     else if (a === "-y" || a === "--yes") out.yes = true;
+    else if (a === "--skip-plain-parser") out.skipPlainParser = true;
     else if (a === "-h" || a === "--help") out.help = true;
     else out._.push(a);
   }
@@ -794,6 +800,7 @@ async function cmdInstall(args) {
   console.log(`  rules:  ${counts.rules}`);
   console.log(`  docs:   ${counts.docs}`);
   wireRules(agent, scope);
+  if (!args.skipPlainParser) ensurePlainParser();
   console.log();
   printNextSteps(agent);
 }
@@ -988,7 +995,6 @@ function printNextSteps(agent) {
   const bold = (s) => `\x1b[1m${s}\x1b[0m`;
   const dim = (s) => `\x1b[2m${s}\x1b[0m`;
   const plain = (s) => color(palette.plain, s);
-  const codeplain = (s) => color(palette.brand, s);
   const link = (s) => color(palette.link, s, "4;");
 
   console.log(`\x1b[1mnext steps:\x1b[0m`);
@@ -1006,9 +1012,6 @@ function printNextSteps(agent) {
     `       ${bold("add-feature")}        — add a feature to an existing ${plain("***plain")} project`,
   );
   console.log();
-  console.log(
-    `prerequisite: install the ${codeplain("codeplain")} CLI to render your specs into code — ${link("https://www.codeplain.ai/")}`,
-  );
   console.log(
     `usage guide: ${link("https://github.com/plainlang/plain-forge#usage")}`,
   );

package/bin/python-tools.mjs

@@ -0,0 +1,139 @@
+// Installs plain-parser, the Python CLI `plain-healthcheck` uses to validate
+// `.plain` files, together with uv, the tool that installs it.
+//
+// Temporary: once plain-parser ships as an npm package it becomes a regular
+// dependency in package.json and this file goes away.
+//
+// Nothing here throws. A failed step prints a warning with the manual
+// commands, and the plain-forge install carries on.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const PLAIN_PARSER = "plain-parser";
+
+const UV_INSTALLERS = {
+  win32: {
+    cmd: "powershell.exe",
+    args: [
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "ByPass",
+      "-Command",
+      "irm https://astral.sh/uv/install.ps1 | iex",
+    ],
+    manual:
+      'powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"',
+  },
+  // Linux and macOS. Falls back to wget where curl is missing (minimal images).
+  posix: {
+    cmd: "sh",
+    args: [
+      "-c",
+      "if command -v curl >/dev/null 2>&1; then curl -LsSf https://astral.sh/uv/install.sh | sh; " +
+        "elif command -v wget >/dev/null 2>&1; then wget -qO- https://astral.sh/uv/install.sh | sh; " +
+        'else echo "the uv installer needs curl or wget, and neither is installed" >&2; exit 1; fi',
+    ],
+    manual: "curl -LsSf https://astral.sh/uv/install.sh | sh",
+  },
+};
+
+function uvInstaller(platform) {
+  return platform === "win32" ? UV_INSTALLERS.win32 : UV_INSTALLERS.posix;
+}
+
+// Run a command. `inherit` streams its output to the user; otherwise stdout is
+// captured. `error` is set (ENOENT) when the command is not on PATH.
+function runCommand(cmd, args, { inherit = false } = {}) {
+  const r = spawnSync(cmd, args, {
+    encoding: "utf8",
+    stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+  });
+  return { status: r.status, stdout: r.stdout ?? "", error: r.error };
+}
+
+function isOnPath(cmd, run) {
+  const r = run(cmd, ["--help"]);
+  return !r.error && r.status === 0;
+}
+
+// Where the uv installer puts uv. A fresh install is not on this process's
+// PATH, so look for it here before giving up.
+function uvCandidates(platform, env, home) {
+  const exe = platform === "win32" ? "uv.exe" : "uv";
+  const dirs = [
+    env.UV_INSTALL_DIR,
+    env.XDG_BIN_HOME,
+    path.join(home, ".local", "bin"),
+    path.join(home, ".cargo", "bin"),
+  ].filter(Boolean);
+  return dirs.map((d) => path.join(d, exe));
+}
+
+function findUv({ platform, env, home, run, exists }) {
+  if (isOnPath("uv", run)) return "uv";
+  return uvCandidates(platform, env, home).find(exists) ?? null;
+}
+
+function warnOffPath(log, binDir) {
+  log(`  plain-parser: installed${binDir ? ` into ${binDir}` : ""}, which is not on your PATH yet.`);
+  log(`  run "uv tool update-shell" and open a new terminal.`);
+  return { status: "not-on-path" };
+}
+
+function warnManual(log, reason, platform) {
+  log(`  plain-parser: not installed — ${reason}`);
+  log(`  plain-forge's healthcheck needs it. Install it yourself with:`);
+  log(`    ${uvInstaller(platform).manual}`);
+  log(`    uv tool install ${PLAIN_PARSER}`);
+}
+
+// Make sure `plain-parser` is installed, installing uv first if needed.
+// Returns { status } — "present", "installed", "not-on-path", or "failed".
+function ensurePlainParser({
+  platform = process.platform,
+  env = process.env,
+  home = os.homedir(),
+  run = runCommand,
+  exists = fs.existsSync,
+  log = console.log,
+} = {}) {
+  if (isOnPath(PLAIN_PARSER, run)) {
+    log(`  plain-parser: already installed`);
+    return { status: "present" };
+  }
+
+  let uv = findUv({ platform, env, home, run, exists });
+  if (!uv) {
+    log(`  uv: not found — installing it (https://docs.astral.sh/uv/)`);
+    const { cmd, args } = uvInstaller(platform);
+    const r = run(cmd, args, { inherit: true });
+    uv = !r.error && r.status === 0 ? findUv({ platform, env, home, run, exists }) : null;
+    if (!uv) {
+      warnManual(log, "installing uv failed", platform);
+      return { status: "failed" };
+    }
+  }
+
+  // Installed by an earlier run, but its bin dir is not on PATH.
+  const binDir = run(uv, ["tool", "dir", "--bin"]).stdout.trim();
+  const exe = platform === "win32" ? `${PLAIN_PARSER}.exe` : PLAIN_PARSER;
+  if (binDir && exists(path.join(binDir, exe))) return warnOffPath(log, binDir);
+
+  log(`  plain-parser: not found — installing it with uv`);
+  // uv downloads a suitable Python (3.11+) itself when the host has none.
+  const r = run(uv, ["tool", "install", PLAIN_PARSER], { inherit: true });
+  if (r.error || r.status !== 0) {
+    warnManual(log, "`uv tool install plain-parser` failed", platform);
+    return { status: "failed" };
+  }
+
+  if (isOnPath(PLAIN_PARSER, run)) {
+    log(`  plain-parser: installed`);
+    return { status: "installed" };
+  }
+  return warnOffPath(log, binDir);
+}
+
+export { ensurePlainParser, uvInstaller, uvCandidates };

package/forge/rules/integration-embedded-testing.md

@@ -120,7 +120,7 @@ output=$(mvn test --no-transfer-progress 2>&1)
 
 ## Common contract (all three scripts)
 
-All three scripts are invoked by the `codeplain` renderer with positional arguments. They MUST:
+All three scripts are invoked by the renderer with positional arguments. They MUST:
 
 1. **Be POSIX-bash (`.sh`) on macOS / Linux, PowerShell (`.ps1`) on Windows.** Executable, idempotent — re-running with the same inputs produces the same result
 2. **Validate every positional argument up front.** Exit with a clear `Usage:` line on bad args. Conventional exit codes (consistent with the shared testing-script rules):

package/forge/rules/linked-resources.md

@@ -61,6 +61,9 @@ A linked resource **must not** be any of the following:
 ```
 
 ## File location and path resolution
-- Paths are resolved relative to the directory where `codeplain` is run (the current working directory)
+- Paths are resolved against the directory that contains the `.plain` file passed to the renderer, not the directory where the renderer is run
+- This includes links inside imported and required modules — they resolve against that same directory, not against the directory the imported module itself lives in
+- A path that does not resolve there is then looked up in the `template-dir` directory (if configured), and last in the renderer's built-in template library
+- Because the `.plain` file's own directory is the anchor, a render gives the same result from any working directory
 - Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk
-- The conventional location is a `resources/` directory; keep the resource inside the project so the path stays stable from wherever `codeplain` is run
+- The conventional location is a `resources/` directory next to the `.plain` file

package/forge/skills/add-feature/SKILL.md

@@ -114,7 +114,8 @@ Most checks already happened in the loop; this is a slim consistency pass whose
    - Acceptance tests (if any) are consistent with their parent specs.
 3. Present the final diff for the modified file(s) and get the user's approval.
 4. If the user requests changes, drop **straight back into the one-question loop** — one question, one write, one fix at a time. Do not restart the loop from scratch.
-5. **Run `plain-healthcheck`** — the last thing this skill does. It validates every `config.yaml` and dry-runs every top module, so a feature is never finished while the project would fail to render. If it returns `FAIL`, work through its numbered list (fixing only `.plain` files / `config.yaml` / scripts — never generated code) by dropping back into the loop, then re-run. Repeat until `PASS`. Only then tell the user the feature is ready and remind them to re-render with `codeplain <module>.plain`.
+5. **Run `plain-healthcheck`** — the last check this skill runs. It validates every `config.yaml`, runs `plain-parser check` on every top module, and checks every module against the rules, so a feature is never finished while the project would fail to render. If it returns `FAIL`, work through its numbered list (fixing only `.plain` files / `config.yaml` / scripts — never generated code) by dropping back into the loop, then re-run. Repeat until `PASS`. Only then tell the user the feature is ready to render as `<module>.plain`.
+6. **Default renderer: pyro.** Ask the user whether to re-render `<module>` now with pyro's `render-spec` skill (`/render-spec <module>.plain`, or `/pyro:render-spec <module>.plain` when pyro is installed as a Claude Code plugin), and invoke it only if they agree. If no `render-spec` skill is available in this session, tell the user pyro is not installed and point them to https://github.com/plainlang/pyro#installation. The user may render with any other ***plain renderer instead.
 
 ## Next feature
 

package/forge/skills/add-feature/references/checklist.md

@@ -35,4 +35,4 @@ Use this to verify the workflow was followed — never as a substitute for it. R
 - [ ] Read the modified `.plain` file(s) in full.
 - [ ] Verified: concepts defined before use, no cycles, chronological ordering correct end-to-end, functional specs language-agnostic, every external interface explicit (endpoints, methods, CLI args, formats), acceptance tests consistent with their parent specs.
 - [ ] Presented the final diff and got the user's approval (change requests dropped back into the one-question loop, not a restart).
-- [ ] Ran `plain-healthcheck`; worked its numbered list to `PASS` (fixing only `.plain`/`config.yaml`/scripts — never generated code) before declaring the feature ready and reminding the user to re-render with `codeplain <module>.plain`.
+- [ ] Ran `plain-healthcheck`; worked its numbered list to `PASS` (fixing only `.plain`/`config.yaml`/scripts — never generated code) before declaring the feature ready and reminding the user to re-render `<module>.plain`.

package/forge/skills/add-resource/SKILL.md

@@ -40,7 +40,9 @@ Use standard markdown link syntax inside any spec section:
 
 ## Path Rules
 
-- Paths are resolved **relative to the directory where `codeplain` is run** (the current working directory).
+- Paths are resolved **against the directory that contains the `.plain` file passed to the renderer**, not the directory where the renderer is run.
+- This includes links inside imported and required modules — they resolve against that same directory, not against the directory the imported module itself lives in.
+- A path that does not resolve there is then looked up in the `template-dir` directory (if configured), and last in the renderer's built-in template library.
 - Relative paths may traverse into parent directories — `[resource](../../resources/resource.md)` is valid — as long as they resolve to a real text file on disk.
 - **No external URLs** — only local file references.
 - **No folder paths** — the target must be a file, not a directory.
@@ -69,7 +71,7 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
 
 ### What a linked resource CAN be
 
-- A single file inside the project, reachable by a path relative to where `codeplain` is run — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
+- A single file inside the project, reachable by a path relative to the `.plain` file — parent-directory traversal (`../`) is allowed (`resources/` is the conventional home).
 - A **text-based** file the renderer can read end-to-end: JSON, YAML, XML, HTML, Markdown, plain text, CSV, TSV, source code in any language (`.py`, `.js`, `.ts`, `.go`, `.java`, `.rb`, `.rs`, `.kt`, `.swift`, `.c`, `.cpp`, `.cs`, …), shell scripts, SQL, JSON Schema, OpenAPI, AsyncAPI, Protobuf `.proto`, GraphQL SDL, `.jolt`, `.env.example`, `.toml`, `.ini`, `.proto`, `Dockerfile`, etc.
 
 ## Common Resource Types
@@ -101,6 +103,6 @@ The **only** exceptions are URLs and paths that are *values the produced softwar
 - [ ] **Target is a text-based file** (no binary extensions: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tiff`, `.webp`, `.ico`, `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.zip`, `.tar`, `.gz`, `.mp3`, `.mp4`, `.wav`, `.exe`, `.so`, `.dylib`, `.class`, `.wasm`, …)
 - [ ] **No URLs or folder paths anywhere in the surrounding `.plain` content** (not as link targets, not in body prose), with the sole exception of URLs / paths that are runtime values the generated software itself uses
 - [ ] Path is relative to the `.plain` file, not absolute
-- [ ] Path resolves to a real text file on disk from where `codeplain` is run (`../` traversal is allowed)
+- [ ] Path resolves to a real text file on disk relative to the `.plain` file (`../` traversal is allowed)
 - [ ] Markdown link syntax is correct: `[display text](relative/path)`
 - [ ] Resource content is relevant and adds value beyond what the spec text says

package/forge/skills/check-forge-version/SKILL.md

@@ -104,7 +104,7 @@ Relay the verdict to the user, then act on it:
   ```
 
   State plainly that **continuing on an outdated plain-forge is not recommended** — its skills and
-  rules have been superseded, specs authored against them may not match what the current `codeplain`
+  rules have been superseded, specs authored against them may not match what the current
   renderer expects, and fixes released since the installed version are not in effect. On `WARN`,
   where the version could not be confirmed, say the install should be treated as outdated until
   proven otherwise.

package/forge/skills/check-forge-version/scripts/check-forge-version.mjs

@@ -265,7 +265,7 @@ function report(installs, latest, statuses) {
         `${n} ${n === 1 ? "install is" : "installs are"} behind v${latest.version}. ` +
           "Continuing on an outdated plain-forge is not recommended: its skills and rules have " +
           "been superseded, so specs authored against them may not match what the current " +
-          "codeplain renderer expects, and fixes released since this version are not in effect.",
+          "renderer expects, and fixes released since this version are not in effect.",
       ),
     );
   }

package/forge/skills/check-plain-env/SKILL.md

@@ -18,7 +18,7 @@ This skill answers one question: **does the host machine have everything the ***
 
 ## When to run
 
-- **First time you open a ***plain project on a new machine** — before the first `codeplain <module>.plain` or `./test_scripts/run_unittests*.sh` invocation. This is the most common case.
+- **First time you open a ***plain project on a new machine** — before the first render or `./test_scripts/run_unittests*.sh` invocation. This is the most common case.
 - **At the start of `forge-plain` Phase 3 environment verification** — `forge-plain` historically did this inline; delegate to this skill instead so the same check runs the same way everywhere.
 - **After `add-feature`** — when the new feature brought in a new dependency (a new framework, a new service, a new package manager) the project didn't need before.
 - **Before a real render** — alongside `plain-healthcheck`. `plain-healthcheck` answers "are the specs renderable?"; this skill answers "can this machine render them?". Both should pass.
@@ -33,7 +33,7 @@ This skill is **read-only and observational**. It does not edit `.plain` files,
 - It does **not** install anything. It only suggests install commands and lets the user run them.
 - It does **not** generate scripts, modify `config.yaml`, or change project files. Use `implement-*-testing-script`, `init-config-file`, etc. for that.
 - It does **not** start services (databases, brokers, Docker daemons). It only checks whether the right binaries and (optionally) running endpoints are reachable.
-- It does **not** validate the specs themselves (syntax, dry-run, complexity). Use `plain-healthcheck` for that — the two skills are complementary.
+- It does **not** validate the specs themselves (syntax, concepts, module graph). Use `plain-healthcheck` for that — the two skills are complementary. It only checks that `plain-parser`, which `plain-healthcheck` runs, is installed.
 - It does **not** print secrets. Check whether an env var is *set* (e.g. `printenv FOO >/dev/null && echo set || echo missing`), never echo its value.
 
 ## Workflow
@@ -147,10 +147,9 @@ Worked example — the GPU case:
 
 Add these to every requirement list regardless of project:
 
-- `codeplain` CLI on `PATH` — `codeplain --version`.
-- `CODEPLAIN_API_KEY` env var **set** — `printenv CODEPLAIN_API_KEY >/dev/null && echo set || echo missing` (never echo the value).
 - A shell matching the testing scripts' extension (Bash for `.sh`, PowerShell for `.ps1`).
 - `git` (the renderer uses it; almost every plain project tracks itself in git).
+- `plain-parser` and **Python 3.11 or newer** — `plain-healthcheck` validates every module with `plain-parser check`. Probe `python3 --version` and `plain-parser --help`; install with `pipx install plain-parser` or `uv tool install plain-parser`.
 
 ### Step 3 — Probe the host
 
@@ -163,7 +162,7 @@ For every requirement the project produced in Step 2, run a check using the `ter
 Probe in the same category order Step 2 produced them, so the report reads top-down:
 
 1. **Category 1 — Language toolchains.** Run the toolchain + package-manager probes listed in Step 2's Category 1 for the languages this project actually uses. Do not probe individual language packages.
-2. **Category 5 — Codeplain and `git`.** Always required, independent of the project. `codeplain --version`, `printenv CODEPLAIN_API_KEY >/dev/null`, `git --version`. Verify the shell flavor matches the scripts' extension; a `.sh`-only project on native Windows is a `FAIL` (suggest WSL).
+2. **Category 5 — Shell, `git`, and `plain-parser`.** Always required, independent of the project. `git --version`, `python3 --version` (3.11 or newer), `plain-parser --help`. Verify the shell flavor matches the scripts' extension; a `.sh`-only project on native Windows is a `FAIL` (suggest WSL).
 3. **Category 2 — External services.** For each service identified at runtime, probe the CLI's presence first, then — if the CLI exists — check whether the service itself is reachable. Service binary present but daemon down → `WARN`, not `FAIL`.
 4. **Category 3 — System binaries that language packages wrap.** For each one identified in Step 2, check the system binary is on `PATH` (`which <bin>` / `<bin> --version`). The wrapper package itself isn't probed.
 5. **Category 4 — Hardware, drivers, accelerators.** Walk the layered probe from Step 2 in order (driver → device visibility → SDK → acceleration libs → framework-sees-it → version match), reporting each layer's result separately. Never collapse a multi-layer failure into a single "GPU not available" message — each layer has a different fix.
@@ -186,7 +185,7 @@ For every **FAIL** and **WARN** item, the report must include four columns:
 | **Status** | "missing", "outdated (found X, need Y)", "binary present but service not running", or "env var not set". |
 | **How to install** | OS-specific command(s). See [Install suggestions](#install-suggestions) below. |
 
-Group the report into the same six probe groups used in Step 3 (toolchains, codeplain/git, services, system binaries, hardware, credentials), so the user can fix one whole layer at a time.
+Group the report into the same six probe groups used in Step 3 (toolchains, shell/git/plain-parser, services, system binaries, hardware, credentials), so the user can fix one whole layer at a time.
 
 End the report with a one-liner reminder: `Re-run check-plain-env after installing missing items to confirm.`
 
@@ -213,7 +212,6 @@ The tables below are a **starter set** of well-known install commands for the th
 | Docker | Install Docker Desktop from https://docker.com/products/docker-desktop |
 | `pg_config` (psycopg) | comes with `brew install postgresql@16` |
 | Xcode CLT | `xcode-select --install` |
-| `codeplain` | follow the install instructions at https://codeplain.ai |
 
 ### Linux (Debian/Ubuntu)
 
@@ -263,7 +261,7 @@ When the host OS detection in Step 1 was inconclusive (e.g. an unrecognized Linu
 - **Don't pre-bake a catalog.** Derive the requirement list at runtime from the project in front of you. A hard-coded "things to always check" table becomes wrong the moment any project deviates from the assumed shape — and every project does.
 - **Don't probe testing framework binaries as if they were independent.** `pytest`, `jest`, `vitest`, `phpunit`, `junit-console`, etc. are installed by the package manager via `requirements.txt` / `package.json` / `pom.xml`. The toolchain check (Category 1) is enough — the framework binary itself is out of scope.
 - **Don't probe in silence.** Use the `terminal` tool and capture the actual command output (version strings, exit codes). Telling the user "looks like Python is installed" without running `python3 --version` is guessing.
-- **Don't print secret values.** Check whether `CODEPLAIN_API_KEY`, `DATABASE_URL`, etc. are set, not what they contain. Use `printenv VAR >/dev/null` not `printenv VAR`.
+- **Don't print secret values.** Check whether `DATABASE_URL`, API keys, etc. are set, not what they contain. Use `printenv VAR >/dev/null` not `printenv VAR`.
 - **Don't install anything on the user's behalf.** Even when the install command is obvious. The user needs to opt in.
 - **Don't stop at the first FAIL.** Run the full sweep so the report is complete in one pass.
 - **Don't suggest `curl | sh` installs when a package manager works.** Reserve the upstream installer fallback for cases where no package-manager option exists (e.g. `rustup`, sometimes Go).
@@ -280,6 +278,7 @@ When the host OS detection in Step 1 was inconclusive (e.g. an unrecognized Linu
 - [ ] Every hardware / accelerator signal ("GPU", "fine-tune", "local inference", "CUDA", "MPS", etc.) triggered the layered Category 4 probe.
 - [ ] Every requirement probed via the `terminal` tool with an actual version / availability command (no "looks installed" guesses).
 - [ ] GPU / accelerator chains probed layer-by-layer (driver → device visibility → toolkit → acceleration libs → framework-sees-it → version match), with each layer reported separately.
+- [ ] `plain-parser` and Python 3.11 or newer probed (always required).
 - [ ] Each result classified as PASS / WARN / FAIL.
 - [ ] Report has the verdict on the first line.
 - [ ] Every FAIL and WARN row has all four columns: What / Why / Status / How to install.

package/forge/skills/forge-plain/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   End-to-end `***plain` spec authoring workflow: a short intent interview followed by a gated,
   one-question-at-a-time interview (product, tech stack, testing) that writes complete .plain
   specification files to disk incrementally, reviews each addition, and
-  validates the specs with a dry-run before handoff. Use when the user starts a
+  validates the specs with plain-healthcheck before handoff. Use when the user starts a
   new project or wants to build something new from scratch. Not for adding a
   feature to an existing project (use add-feature) or for editing generated code
   (the .plain specs are the source of truth).
@@ -85,7 +85,7 @@ When entering a phase, read its reference file and walk its topics **in order**
 | 1 — What are we building? | `references/phase-1-product.md` | the new `***definitions***` and `***functional specs***`, plus any technology-free `***implementation reqs***`, are on disk and approved |
 | 2 — What tech should it use? | `references/phase-2-tech.md` | the new `***implementation reqs***` are on disk and approved |
 | 3 — How is testing done? | `references/phase-3-testing.md` | the `***test reqs***` (and `***acceptance tests***` if conformance is on) are on disk, the `test_scripts/` and `config.yaml`(s) exist, and `check-plain-env` passed or each gap was acknowledged |
-| 4 — Validate and hand off | `references/phase-4-validate-handoff.md` | the agent ran `codeplain <module>.plain --dry-run` successfully against the render target, and the user has the render command plus every side-channel command |
+| 4 — Validate and hand off | `references/phase-4-validate-handoff.md` | `plain-healthcheck` returned `PASS`, and the user has the render target plus every side-channel command |
 
 Between phases, summarize and get explicit overall confirmation before continuing — the intent brief
 after Phase 0; the full feature list and module/concept layout after Phase 1; the tech stack and
@@ -112,8 +112,7 @@ Once the initial specs exist, the user will return with new features. Use the `a
 - **A phase gate is not met** (a review agent returned unmet boxes) → do not advance; fix each gap through the interview → author → review loop, then spawn a fresh review agent and repeat until `APPROVED`.
 - **A review agent can't be spawned or returns nothing usable** → spawn a fresh one; do not self-certify the gate. Never `SendMessage` a running reviewer — capture its returned result. If spawning genuinely fails in this environment, walk the phase's checklist block inline as a fallback and tell the user the review was self-run.
 - **`check-plain-env` returns `FAIL`** (Phase 3) → walk each gap with the user; install, swap to an alternative, or explicitly acknowledge it before Phase 4. Re-invoke after any install.
-- **`plain-healthcheck` returns `FAIL`** (Phase 4) → do not present the render command; work through its numbered list with the right edit skill and re-run until it passes.
-- **Environment failure** (`codeplain` not on PATH, `CODEPLAIN_API_KEY` unset) → tell the user exactly what is missing and how to fix it; never pretend the check passed.
+- **`plain-healthcheck` returns `FAIL`** (Phase 4) → do not hand off the render target; work through its numbered list with the right edit skill and re-run until it passes.
 
 ## Self-check checklist
 

package/forge/skills/forge-plain/references/checklist.md

@@ -63,5 +63,5 @@ A box is met only when its source confirms it. Return `APPROVED` only when every
 
 - [ ] **[disk]** Identified the render target — the last module in the dependency chain (or the single module).
 - [ ] **[both]** Ran `init-config-file` to build the final `config.yaml`(s); resolved any precondition gap with the user before validating.
-- [ ] **[record]** Ran `plain-healthcheck`; worked its numbered list to `PASS` — never presented the render command on a `FAIL`.
-- [ ] **[record]** Presented the render command only after the dry-run passed, plus every side-channel script actually generated in Phase 3.
+- [ ] **[record]** Ran `plain-healthcheck`; worked its numbered list to `PASS` — never handed off the render target on a `FAIL`.
+- [ ] **[record]** Handed off the render target only after `plain-healthcheck` passed, plus every side-channel script actually generated in Phase 3.

package/forge/skills/forge-plain/references/phase-3-testing.md

@@ -55,7 +55,7 @@ When all topics are complete, recap the full testing strategy: which `config.yam
 
 Delegate environment verification to the `check-plain-env` skill — do **not** probe the machine inline. It is the single source of truth for "can this machine render and test this project?" and derives the requirement list at runtime from the project's `.plain` files, `test_scripts/`, `config.yaml`(s), and `resources/`.
 
-`check-plain-env` detects the host OS, builds the requirement list (language toolchains + their package managers, external services, system binaries that language packages wrap, hardware / drivers / accelerators, `codeplain` itself, credentials — the layers a package manager **cannot** install), probes each with a real version / availability command, and emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. It never probes individual language packages (`torch`, `numpy`, `FastAPI`, `react`, JARs, gems) — those are installed by the project's own `prepare_environment` / unit-test scripts the moment they run. It is read-only and installs nothing itself.
+`check-plain-env` detects the host OS, builds the requirement list (language toolchains + their package managers, external services, system binaries that language packages wrap, hardware / drivers / accelerators, credentials — the layers a package manager **cannot** install), probes each with a real version / availability command, and emits a `PASS` / `WARN` / `FAIL` report with OS-specific install commands for any gaps. It never probes individual language packages (`torch`, `numpy`, `FastAPI`, `react`, JARs, gems) — those are installed by the project's own `prepare_environment` / unit-test scripts the moment they run. It is read-only and installs nothing itself.
 
 Act on the return value:
 

package/forge/skills/forge-plain/references/phase-4-validate-handoff.md

@@ -1,6 +1,6 @@
 # Phase 4 — Validate and hand off
 
-Two halves. First **the agent** validates every spec end-to-end with a `codeplain` dry-run so the user never wastes a real render — or any debugging time — on a fixable static error. Only after that passes does the agent **hand off** the render command (plus any side-channel commands) to the user.
+Two halves. First **the agent** validates every spec with `plain-healthcheck` so the user never wastes a real render — or any debugging time — on a fixable static error. Only after that passes does the agent **hand off** the render target (plus any side-channel commands) to the user.
 
 ## 4a. Identify the render target
 
@@ -14,36 +14,34 @@ Find the **last module in the dependency chain** — the module that is not `req
 Finalize the project's `config.yaml` file(s) before validation. Phase 3 may have written provisional entries as scripts were generated; **this** is where they are consolidated into the canonical form the renderer expects. Invoke the `init-config-file` skill. It:
 
 - enumerates every part of the project (one `config.yaml` per part — single-stack → root config; multi-part → one config per part),
-- assembles only the **valid** config keys derived from the `codeplain` CLI parser,
-- emits a clean YAML file per part (script paths first, then template/build folders, then copy/log settings),
+- assembles only the **valid** config keys,
+- emits a clean YAML file per part (script paths first, then template/build folders),
 - verifies every `*-script` value resolves to a real file on disk,
-- refuses to write secrets (`api-key`) or per-invocation flags (`dry-run`, `full-plain`, `render-range`, `render-from`, `replay-with`) into the config.
+- refuses to write secrets or per-invocation options into the config.
 
 If `init-config-file` stops because a precondition isn't met (e.g. a `prepare-environment-script` exists but no conformance script does), resolve the gap with the user before continuing — do **not** hand a known-broken config to `plain-healthcheck`.
 
 ## 4c. Validate the project with `plain-healthcheck`
 
-Run the `plain-healthcheck` skill — the single source of truth for "is this project ready to render?". Do **not** run the dry-run inline. It:
+Run the `plain-healthcheck` skill — the single source of truth for "is this project ready to render?". Do **not** run its checks inline. It:
 
 - inventories every `.plain` module and identifies every top module,
 - validates every `config.yaml` (existence, parseability, script paths actually pointing at files in `test_scripts/`, no mixed stacks), and
-- runs `codeplain <top>.plain --dry-run` for **every** top module with the correct `--config-name` for multi-part projects.
+- runs `plain-parser check` on every top module, which parses it with its whole `import` / `requires` chain (frontmatter, module graph, sections, concepts, linked resources, templates), and
+- checks every module for what the parser can't judge (section ownership, bullets, linked-resource contents).
 
-The skill runs the full detect → fix → re-run loop itself (syntax errors, undefined concepts, broken `import` / `requires` chains, cyclic definitions, missing templates, complexity violations, conflicting reqs, config drift, missing scripts) and returns only once everything passes or a gap genuinely needs the user. Then:
+The skill runs the full detect → fix → re-run loop itself (syntax errors, undefined concepts, broken `import` / `requires` chains, cyclic definitions, missing templates, misplaced facts, config drift, missing scripts) and returns only once everything passes or a gap genuinely needs the user. Then:
 
 - **`PASS`** → move on to step 4d.
 - **`FAIL`** → do **not** ask the user to render. Work through the numbered list it produced (each item references a specific `.plain` file, `config.yaml`, or script), resolve each one with the appropriate edit skill, and re-run `plain-healthcheck` until it returns `PASS`. Any item the skill could not auto-resolve will name the concrete question to put to the user.
-- **Environment failure** (e.g. `codeplain` not on PATH, `CODEPLAIN_API_KEY` not set) → `plain-healthcheck` surfaces this as a clearly-marked environment failure. Tell the user exactly what's missing and how to fix it before continuing. Do not pretend the healthcheck passed.
 
-## 4d. Present the render command
+## 4d. Hand off the render target
 
-Only after the dry-run passes, tell the user their specs are ready and present the render command:
+Only after `plain-healthcheck` passes, tell the user their specs are ready and that `<module>` is the module to render:
 
-```
-codeplain <module>.plain
-```
+- Chain `base.plain → features.plain → integrations.plain` → render `integrations.plain`.
+- Single module `my_app.plain` → render `my_app.plain`.
 
-- Chain `base.plain → features.plain → integrations.plain` → `codeplain integrations.plain`.
-- Single module `my_app.plain` → `codeplain my_app.plain`.
+**Default renderer: pyro.** Ask the user whether to render `<module>` now with pyro's `render-spec` skill (`/render-spec <module>.plain`, or `/pyro:render-spec <module>.plain` when pyro is installed as a Claude Code plugin), and invoke it only if they agree. If no `render-spec` skill is available in this session, tell the user pyro is not installed and point them to https://github.com/plainlang/pyro#installation. The user may render with any other ***plain renderer instead.
 
 Also remind the user of any **side-channel commands** they may want to run themselves per the Phase 3 testing strategy — for example `./test_scripts/run_unittests.sh <module>`, `./test_scripts/prepare_environment.sh <module>`, or `./test_scripts/run_conformance_tests.sh <module> <conformance_tests_folder>`. Mention only the scripts that were actually generated in Phase 3.