docs: fix examples README, README TS imports, and init-template skills (schedule/npm/ruby/gha-404) (#131)

Author: markovejnovic

.claude/skills/write-pipeline/SKILL.md

@@ -29,7 +29,7 @@ Write, modify, or extend Harmont CI pipelines defined in `.hm/pipeline.py` (Pyth
    Read it carefully. It covers correct vs. incorrect approaches, when to use toolchains vs. raw shell, and common anti-patterns.
 
 2. If you need the full API reference for a specific toolchain or feature, fetch the relevant page (append `.md` to any docs.harmont.dev URL for raw Markdown):
-   - Toolchain reference: `https://docs.harmont.dev/pipeline-sdk/reference/toolchains/<name>.md` (rust, python, npm, go, cmake, zig, elixir, ruby, etc.)
+   - Toolchain reference: `https://docs.harmont.dev/pipeline-sdk/reference/toolchains/<name>.md` (rust, python, js, go, cmake, zig, elixir, etc.)
    - Chains and steps: `https://docs.harmont.dev/pipeline-sdk/reference/chains.md`
    - Triggers: `https://docs.harmont.dev/pipeline-sdk/reference/triggers.md`
    - Caching: `https://docs.harmont.dev/pipeline-sdk/reference/cache.md`
@@ -40,15 +40,15 @@ Write, modify, or extend Harmont CI pipelines defined in `.hm/pipeline.py` (Pyth
    ```
    WebFetch https://docs.harmont.dev/examples/<language>.md
    ```
-   Available examples: rust, go, cmake, zig, nextjs, python-uv, ruby, elixir
+   Available examples: rust, go, cmake, zig, nextjs, python-uv, elixir
 
 ## Procedure
 
-1. **Identify the project's language and build system.** Look at the project root for `Cargo.toml` (Rust), `package.json` (JS/TS), `pyproject.toml` or `setup.py` (Python), `go.mod` (Go), `CMakeLists.txt` (C/C++), `mix.exs` (Elixir), `build.zig` (Zig), `Gemfile` (Ruby).
+1. **Identify the project's language and build system.** Look at the project root for `Cargo.toml` (Rust), `package.json` (JS/TS), `pyproject.toml` or `setup.py` (Python), `go.mod` (Go), `CMakeLists.txt` (C/C++), `mix.exs` (Elixir), `build.zig` (Zig).
 
 2. **Check for an existing pipeline.** Look for `.hm/pipeline.py` or `.hm/pipeline.ts`. If none exists, pick the DSL that matches the project's ecosystem before asking the user to confirm:
    - **TypeScript DSL** if the project already has `package.json`, `tsconfig.json`, or is primarily TypeScript/JavaScript (the team is already comfortable with the TS toolchain).
-   - **Python DSL** for everything else — Rust, Go, C/C++, Elixir, Zig, Ruby, Python, or mixed-language projects (Python is the simpler, more universal choice).
+   - **Python DSL** for everything else — Rust, Go, C/C++, Elixir, Zig, Python, or mixed-language projects (Python is the simpler, more universal choice).
    - Present your recommendation and rationale, then let the user override if they prefer the other DSL.
    Then either run `hm init --template <kind>` to scaffold or write the pipeline file directly.
 
@@ -57,7 +57,7 @@ Write, modify, or extend Harmont CI pipelines defined in `.hm/pipeline.py` (Pyth
 4. **Write or modify the pipeline.** Follow the patterns guide strictly:
    - Prefer toolchains over raw `sh()` calls when a toolchain exists for the language.
    - Use `.fork()` for steps that can run in parallel.
-   - Set triggers (`push`, `pull_request`, `schedule`) appropriate to the project.
+   - Set triggers (`push`, `pull_request`) appropriate to the project.
    - Use `default_image: "ubuntu:24.04"` unless the project needs something specific.
    - Set `env: {"CI": "true"}` on the pipeline.
 

README.md

@@ -132,8 +132,8 @@ def ci(project: hm.Target[PythonToolchain]) -> tuple[hm.Step, ...]:
 <summary><b>TypeScript</b></summary>
 
 ```typescript
-import { pipeline, push, type PipelineDefinition } from "harmont";
-import { python } from "harmont/toolchains";
+import { pipeline, push, type PipelineDefinition } from "@harmont/hm";
+import { python } from "@harmont/hm/toolchains";
 
 const project = python({ path: "." });
 

crates/hm/src/commands/init_templates/skill_convert_gha.md

@@ -31,15 +31,10 @@ Convert existing GitHub Actions workflows (`.github/workflows/*.yml` / `*.yaml`)
    WebFetch https://docs.harmont.dev/pipeline-sdk/patterns.md
    ```
 
-3. **Fetch the GHA migration example** if available:
-   ```
-   WebFetch https://docs.harmont.dev/examples/github-actions.md
-   ```
-
 ## Procedure
 
 1. **Inventory the GHA workflows.** For each `.yml` file, note:
-   - Workflow name and trigger events (`on: push`, `on: pull_request`, `on: schedule`, etc.)
+   - Workflow name and trigger events (`on: push`, `on: pull_request`, etc.; note any `on: schedule` — see the mapping table for why scheduled triggers don't map to a local pipeline)
    - Each job: its name, `runs-on`, and what it does
    - Dependencies between jobs (`needs:`)
    - Services used (`services:`)
@@ -53,11 +48,11 @@ Convert existing GitHub Actions workflows (`.github/workflows/*.yml` / `*.yaml`)
    | GHA concept | Harmont equivalent | Notes |
    |---|---|---|
    | `on: push` / `on: pull_request` | `push` / `pull_request` triggers | Direct mapping — same semantics |
-   | `on: schedule` (cron) | `schedule` trigger | Direct mapping |
+   | `on: schedule` (cron) | No local DSL trigger | Scheduled pipelines are a Harmont Cloud concern, not a local pipeline trigger; omit the schedule or configure it in cloud. |
    | `jobs.<id>.steps` | Chain of toolchain calls or `sh()` | Each meaningful step becomes a Harmont step |
    | `jobs.<id>.needs` | `.fork()` for parallel, sequential chain for dependencies | Harmont DAG is implicit from chain structure |
    | `actions/cache` | **Not needed — caching is implicit in Harmont** | Harmont automatically caches build artifacts, dependency installs, and toolchain outputs between runs. Remove all cache steps. |
-   | `actions/setup-*` (setup-node, setup-python, etc.) | Harmont toolchains (`hm.npm`, `hm.python`, etc.) | Toolchains handle installation. Specify version via toolchain config. |
+   | `actions/setup-*` (setup-node, setup-python, etc.) | Harmont toolchains (`hm.js`, `hm.python`, etc.) | Toolchains handle installation. Specify version via toolchain config. |
    | `actions/checkout` | **Not needed — source is always available** | Harmont automatically provides the source code to every step. |
    | `runs-on: ubuntu-latest` | `default_image: "ubuntu:24.04"` | Harmont runs steps in Docker containers |
    | `services:` (e.g., postgres) | Service containers in step config | Check docs for service container syntax |
@@ -69,7 +64,7 @@ Convert existing GitHub Actions workflows (`.github/workflows/*.yml` / `*.yaml`)
 3. **Be honest about differences.** After presenting the mapping, explain:
    - **What's simpler:** Caching is implicit — no `actions/cache` boilerplate. No `actions/checkout` needed. Toolchains replace `actions/setup-*` with cleaner configuration.
    - **What's different:** Matrix strategies don't have a direct equivalent — you may need multiple pipeline definitions or `.fork()`. Service containers have different syntax. Complex `if:` conditionals become DSL-level control flow.
-   - **What's a real gap:** Only mention a gap if functionality genuinely cannot be replicated. Do NOT invent problems — most GHA workflows map cleanly. Common real gaps: GHA marketplace actions that have no Harmont toolchain equivalent (use `sh()` with the underlying commands instead), GitHub-specific features like `github.event` context or `GITHUB_TOKEN` permissions.
+   - **What's a real gap:** Only mention a gap if functionality genuinely cannot be replicated. Do NOT invent problems — most GHA workflows map cleanly. Common real gaps: `on: schedule` cron triggers (the local DSL has only `push`/`pull_request`; scheduled runs are a Harmont Cloud concern), GHA marketplace actions that have no Harmont toolchain equivalent (use `sh()` with the underlying commands instead), GitHub-specific features like `github.event` context or `GITHUB_TOKEN` permissions.
 
 4. **Delegate to the `write-pipeline` skill.** Once the user understands the mapping, invoke the `write-pipeline` skill to create the actual Harmont pipeline. Tell it:
    - What language/build system the project uses (detected from the GHA workflow)

crates/hm/src/commands/init_templates/skill_write_pipeline.md

@@ -29,7 +29,7 @@ Write, modify, or extend Harmont CI pipelines defined in `.hm/pipeline.py` (Pyth
    Read it carefully. It covers correct vs. incorrect approaches, when to use toolchains vs. raw shell, and common anti-patterns.
 
 2. If you need the full API reference for a specific toolchain or feature, fetch the relevant page (append `.md` to any docs.harmont.dev URL for raw Markdown):
-   - Toolchain reference: `https://docs.harmont.dev/pipeline-sdk/reference/toolchains/<name>.md` (rust, python, npm, go, cmake, zig, elixir, etc.)
+   - Toolchain reference: `https://docs.harmont.dev/pipeline-sdk/reference/toolchains/<name>.md` (rust, python, js, go, cmake, zig, elixir, etc.)
    - Chains and steps: `https://docs.harmont.dev/pipeline-sdk/reference/chains.md`
    - Triggers: `https://docs.harmont.dev/pipeline-sdk/reference/triggers.md`
    - Caching: `https://docs.harmont.dev/pipeline-sdk/reference/cache.md`
@@ -57,7 +57,7 @@ Write, modify, or extend Harmont CI pipelines defined in `.hm/pipeline.py` (Pyth
 4. **Write or modify the pipeline.** Follow the patterns guide strictly:
    - Prefer toolchains over raw `sh()` calls when a toolchain exists for the language.
    - Use `.fork()` for steps that can run in parallel.
-   - Set triggers (`push`, `pull_request`, `schedule`) appropriate to the project.
+   - Set triggers (`push`, `pull_request`) appropriate to the project.
    - Use `default_image: "ubuntu:24.04"` unless the project needs something specific.
    - Set `env: {"CI": "true"}` on the pipeline.
 

examples/README.md

@@ -1,25 +1,24 @@
 # Harmont examples
 
-Minimal idiomatic starter projects, each wired up to a Harmont CI pipeline. Every example lives in its own subdirectory with a `.hm/pipeline.py` you can read, copy, and run via `hm run <slug> --local`.
+Minimal idiomatic starter projects, each wired up to a Harmont CI pipeline. Every example lives in its own subdirectory with a `.hm/pipeline.py` you can read, copy, and run via `hm run <slug>`.
 
 | Example | Toolchain | Pipeline |
 |---|---|---|
-| [react](./react) | npm + Vite + Vitest + ESLint | `hm.npm(...)` |
-| [nextjs](./nextjs) | npm + Jest + ESLint | `hm.npm(...)` |
-| [typescript](./typescript) | tsc + Vitest + ESLint | `hm.npm(...)` |
-| [bun](./bun) | Bun + tsc + bun:test + ESLint | `hm.bun(...)` |
+| [react](./react) | npm + Vite + Vitest + ESLint | `hm.js.project(...)` |
+| [nextjs](./nextjs) | npm + Jest + ESLint | `hm.js.project(...)` |
+| [typescript](./typescript) | tsc + Vitest + ESLint | `hm.js.project(...)` |
+| [bun](./bun) | Bun + tsc + bun:test + ESLint | `hm.js.project(runtime="bun")` |
 | [rust](./rust) | cargo + clippy + rustfmt | `hm.rust(...)` |
 | [python-uv](./python-uv) | uv + pytest + ruff + mypy | `hm.python(...)` |
 | [go](./go) | go build/test/vet/fmt | `hm.go(...)` |
 | [c](./c) | CMake + CTest + clang-format | `hm.cmake(lang="c")` |
 | [cpp](./cpp) | CMake + CTest + clang-format | `hm.cmake(lang="cpp")` |
-| [ruby](./ruby) | Bundler + RSpec + Rubocop | `hm.ruby(...)` |
 | [zig](./zig) | zig build/test/fmt | `hm.zig(version="0.13.0")` |
 
 ## How to run an example locally
 
 1. Install the Harmont CLI (`cli/` in this repo, or `cargo install harmont-cli` once published).
-2. `cd examples/<lang>` and run `hm run ci --local`. The CLI uses the project's `.hm/pipeline.py` and executes each step in a local Docker container, sharing caches across runs.
+2. `cd examples/<lang>` and run `hm run ci`. The CLI uses the project's `.hm/pipeline.py` and executes each step in a local Docker container (the default backend), sharing caches across runs. Use `--backend cloud` to submit the run to Harmont Cloud instead.
 
 Every pipeline uses `default_image="ubuntu:24.04"` and the apt-base / language-install steps are cached forever — only the action leaves (`test`, `lint`, etc.) re-run after a code change.