docs: add Hedera Harness under Solutions developer tools

docs.json

@@ -2890,6 +2890,12 @@
                   "solutions/tools/scaffold-hbar/scaffold-ui"
                 ]
               },
+              {
+                "group": "Hedera Harness",
+                "pages": [
+                  "solutions/tools/hedera-harness/index"
+                ]
+              },
               "solutions/tools/code-repo",
               "solutions/tools/custodians-library",
               "solutions/tools/custodians-library-usage",

solutions/index.mdx

@@ -193,6 +193,16 @@ mode: wide
       </div>
     </a>
 
+    <a href="/solutions/tools/hedera-harness/index" className="landing-card">
+      <div className="landing-card-icon">
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#fff" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 2v4 M12 18v4 M4.93 4.93l2.83 2.83 M16.24 16.24l2.83 2.83 M2 12h4 M18 12h4 M4.93 19.07l2.83-2.83 M16.24 7.76l2.83-2.83"/><circle cx="12" cy="12" r="4"/></svg>
+      </div>
+      <div>
+        <div className="landing-card-title">Hedera Harness</div>
+        <div className="landing-card-desc">Turn a Hedera product brief into a Scaffold HBAR template and check that it actually runs.</div>
+      </div>
+    </a>
+
     <a href="/solutions/tools/hiero-cli/overview" className="landing-card">
       <div className="landing-card-icon">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#fff" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M4 17l6-6-6-6 M12 19h8"/></svg>

solutions/tools/hedera-harness/index.mdx

@@ -0,0 +1,239 @@
+---
+title: "Hedera Harness"
+description: "Describe a Hedera demo in a PRD, then let an agent build a Scaffold HBAR template and check that it works."
+---
+
+## What is Hedera Harness?
+
+Hedera Harness helps you turn a product idea into a working [Scaffold HBAR](/solutions/tools/scaffold-hbar/index) template — and prove that template actually runs.
+
+You write a short product brief (PRD) and a few validation rules for *your* Hedera demo. The harness seeds a clean workspace, asks an AI coding agent to build the template, then checks the result. If something fails, it feeds the failures back to the agent and tries again until the checks pass or the attempt budget runs out.
+
+Use it to:
+
+- Go from PRD → runnable Scaffold HBAR workspace without hand-writing the whole template
+- **Extend** an already-scaffolded app in place (`.harness/` + `yarn harness:extend`) without re-seeding
+- Catch structural, UI, semantic, and optional on-chain issues before you share the template
+- Keep each attempt isolated under `runs/` (or `.harness/runs/` for extend) so you can inspect what the agent produced
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="#quick-start">
+    Clone the harness, copy the skeleton, and run your first Tier 0–1 loop
+  </Card>
+  <Card title="Extend in place" icon="screwdriver-wrench" href="#extend-an-existing-app">
+    Scaffold once, then `yarn harness:extend` against `.harness/`
+  </Card>
+  <Card title="How it works" icon="diagram-project" href="#how-it-works">
+    Seed, vendor, generate, validate, and repair at a glance
+  </Card>
+  <Card title="GitHub" icon="github" href="https://github.com/hedera-dev/hedera-harness">
+    Source, examples, and authoring guide
+  </Card>
+</CardGroup>
+
+---
+
+## How it relates to Scaffold HBAR
+
+| Tool | Role |
+|------|------|
+| **[Scaffold HBAR](/solutions/tools/scaffold-hbar/index)** | Interactive CLI that scaffolds a Hedera monorepo (contracts, Next.js, network config) from templates |
+| **Hedera Harness** | Takes your PRD, asks an agent to build or extend a Hedera demo compatible with scaffold-hbar templates, then validates the result |
+
+Scaffold provisions apps for humans. The harness asks an agent to produce (or extend) a template from your brief, then checks whether it works. Skills default to the public [hedera-skills](https://github.com/hedera-dev/hedera-skills) repo; greenfield `run` seeds from public [scaffold-hbar](https://github.com/hedera-dev/scaffold-hbar).
+
+---
+
+## Prerequisites
+
+Before using Hedera Harness, ensure you have:
+
+- **Node.js** ≥ 20 — [nodejs.org](https://nodejs.org/)
+- **Git** — [git-scm.com](https://git-scm.com/)
+- **Yarn** (seeded workspaces are Yarn-based):
+  ```bash
+  corepack enable && corepack prepare yarn@stable --activate
+  ```
+- **Cursor CLI** (`agent` on your `PATH`, authenticated) — or another agent CLI you configure in the spec
+- A **product idea** written as a PRD (start from the skeleton in the repo)
+
+<Info>
+Tier 3.5 on-chain validation is optional. It needs a funded Hedera **testnet** account created with an **ECDSA** key (not ED25519). Export `HEDERA_OPERATOR_ID` and `HEDERA_OPERATOR_KEY` in the shell that runs the harness — never write those into a generated workspace.
+</Info>
+
+---
+
+## Quick Start
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/hedera-dev/hedera-harness.git
+cd hedera-harness
+npm install
+```
+
+### 2. Copy the skeleton for your idea
+
+```bash
+NAME=my-hedera-demo
+
+cp skeletons/new-template/prd.md              docs/prds/${NAME}.md
+cp skeletons/new-template/spec.yaml           specs/${NAME}.yaml
+cp skeletons/new-template/acceptance-contract.json contracts/${NAME}-acceptance.json
+cp skeletons/new-template/static.json         validators/${NAME}-static.json
+cp skeletons/new-template/yarn.json           validators/${NAME}-yarn.json
+cp skeletons/new-template/playwright-smoke.yaml playwright/${NAME}-smoke.yaml
+
+# Align internal paths / names with $NAME (macOS; on Linux drop the '').
+sed -i '' "s/my-template/${NAME}/g" \
+  specs/${NAME}.yaml \
+  validators/${NAME}-static.json \
+  validators/${NAME}-yarn.json \
+  contracts/${NAME}-acceptance.json \
+  playwright/${NAME}-smoke.yaml
+```
+
+### 3. Write the PRD and fill remaining placeholders
+
+1. Rewrite `docs/prds/${NAME}.md` for your product (goal, journeys, Hedera services, non-goals).
+2. Edit `specs/${NAME}.yaml`: fill remaining `REPLACE_ME` stubs. `seed.repo` already defaults to the public scaffold-hbar remote.
+3. Keep Tier 2 / 3 / 3.5 commented until Tier 0–1 passes.
+
+### 4. Run the harness
+
+```bash
+npm run harness -- run specs/${NAME}.yaml --max-attempts 3
+```
+
+Artifacts land under `runs/` (workspace, logs, report).
+
+<Tip>
+Example PRDs and specs ship in the repo (Proof Wall, HTS precompile, x402) as **inspiration only**. You do not need to run them to use the harness. See the [repository README](https://github.com/hedera-dev/hedera-harness) for the full CLI reference.
+</Tip>
+
+---
+
+## Extend an existing app
+
+Prefer this path when a Scaffold HBAR template already ships a `.harness/` recipe (for example the Learn-page pilot on `hedera-demo`).
+
+### 1. Scaffold and install
+
+```bash
+npx create-scaffold-hbar@latest
+cd my-app
+yarn install
+```
+
+### 2. Confirm the extend recipe
+
+Templates that support in-place extend include:
+
+- `.harness/spec.yaml` — no `seed`; includes `extend.baseline`
+- `.harness/prd.md` — product brief for the delta
+- `.harness/validators/` — static + yarn gates
+- `package.json` script: `"harness:extend": "hedera-harness extend .harness/spec.yaml"`
+- Dev dependency: `hedera-harness` (optional peers `playwright` / `@hiero-ledger/sdk` only if you enable Tier 2 / 3.5)
+
+### 3. Run extend
+
+```bash
+yarn harness:extend
+```
+
+The harness uses the project directory as the workspace (no re-seed), runs baseline commands, asks the agent to implement the PRD, then validates enabled tiers. Artifacts land under `.harness/runs/`.
+
+Author a new extend recipe with the [hedera-skills hedera-harness plugin](https://github.com/hedera-dev/hedera-skills) (`/create-harness-spec` detects scaffolded apps and emits under `.harness/`).
+
+<Info>
+Greenfield `run` (clone the harness repo) and in-place `extend` share the same validation tiers. Only layout and CLI entrypoint differ.
+</Info>
+
+---
+
+## How it works
+
+Each run follows a vertical happy path. Skip validation tiers that are not enabled in the spec. On validation failure with attempts remaining, the harness repairs and returns to **Generate**.
+
+<Frame>
+  <img src="/images/solutions/tools/hedera-harness/harness-flow.png" alt="Hedera Harness vertical run graph: Inputs, Seed, Vendor, Generate, Oracle audit, Validate tiers, Outcome, with repair loop" />
+</Frame>
+
+| Stage | What happens |
+|-------|----------------|
+| **Seed** | Clone pinned scaffold-hbar ref into an isolated workspace; optional yarn preflight |
+| **Vendor** | Fetch skills (default: hedera-skills) and copy PRD / contract context into the workspace |
+| **Generate** | Agent CLI builds the template from the PRD |
+| **Oracle audit** | Informational check for peeking — never blocks a pass |
+| **Validate** | Enabled tiers in order (see below) |
+| **Outcome** | Pass, fail (budget exhausted), or infra abort → `runs/` |
+
+<Accordion title="Detailed sequence (who talks to whom)">
+
+Actors: CLI, Harness, Git sources, Workspace, Generator, Validators.
+
+<Frame>
+  <img src="/images/solutions/tools/hedera-harness/harness-sequence.png" alt="Hedera Harness sequence diagram showing messages between CLI, Harness, Git sources, Workspace, Generator, and Validators" />
+</Frame>
+
+</Accordion>
+
+---
+
+## Validation tiers
+
+**Pass condition:** every validation tier enabled in the spec must pass.
+
+| Tier | Spec fields | What it checks |
+|------|-------------|----------------|
+| **0–1 Deterministic** | `validators.static`, `validators.commands`, `requiredFiles`, `forbiddenFiles`, `secretScan` | Files, JSON/text assertions, secrets, yarn install/lint/build (or your commands) |
+| **2 Playwright gate** | `validators.playwright` | Dev server boots; configured routes return OK; optional console / forbidden-text checks |
+| **3 Semantic** | `contract` + `validator` | Read-only agent drives the live app and grades numbered acceptance assertions |
+| **3.5 On-chain** | `chainValidation` (+ Tier 3) | Ephemeral funded ECDSA test signer injected as burner wallet; real txs verified via mirror node |
+
+Tier 0–1 is the minimum. Tier 2–3 are optional but recommended for UI demos. The skeleton ships with Tier 2 / 3 / 3.5 commented out so first runs stay simple.
+
+<Warning>
+Semantic infrastructure failures (for example MCP or browser unavailable) **abort** the repair loop — the harness does not ask the generator to “fix” a missing browser.
+</Warning>
+
+---
+
+## Author your own idea
+
+The harness is template-agnostic: start from the skeleton (greenfield) or from `.harness/` (extend), not from forking the example demos.
+
+1. Copy skeletons as in [Quick Start](#quick-start), **or** author under `.harness/` as in [Extend an existing app](#extend-an-existing-app).
+2. Follow the checklist in the repo: [authoring-a-template.md](https://github.com/hedera-dev/hedera-harness/blob/main/docs/authoring-a-template.md).
+3. Enable higher tiers only after Tier 0–1 is green (`npx playwright install chromium` for Tier 2; Playwright MCP + acceptance contract for Tier 3).
+
+Private WIP PRDs can live under `docs/prds/local/` in a local clone (that path is gitignored).
+
+---
+
+## Ecosystem
+
+<CardGroup cols={2}>
+  <Card title="Scaffold HBAR" icon="layer-group" href="/solutions/tools/scaffold-hbar/index">
+    Scaffold Hedera dApps from the CLI—templates, contracts, Next.js, and Hedera Skills
+  </Card>
+  <Card title="Scaffold UI" icon="palette" href="/solutions/tools/scaffold-hbar/scaffold-ui">
+    Shared React components, hooks, and MCP server for AI-assisted development
+  </Card>
+  <Card title="Hedera Skills" icon="wand-magic-sparkles" href="https://github.com/hedera-dev/hedera-skills">
+    AI coding assistant skills fetched by the harness into each run
+  </Card>
+  <Card title="AI Studio" icon="robot" href="/solutions/ai/index">
+    Broader toolkit for building verifiable AI agents on Hedera
+  </Card>
+</CardGroup>
+
+---
+
+## Resources
+
+- [GitHub: hedera-harness](https://github.com/hedera-dev/hedera-harness) — CLI source, examples, and issues
+- [GitHub: scaffold-hbar](https://github.com/hedera-dev/scaffold-hbar) — Seed templates repository
+- [Hedera Portal](https://portal.hedera.com/) — Account creation and testnet faucet
+- [HashScan](https://hashscan.io/) — Block explorer for Hedera

solutions/tools/scaffold-hbar/index.mdx

@@ -22,6 +22,9 @@ Scaffold HBAR is an interactive CLI tool (similar to `create-next-app` or `creat
   <Card title="Scaffold UI" icon="puzzle-piece" href="/solutions/tools/scaffold-hbar/scaffold-ui">
     Shared components, hooks, and MCP server for AI agents
   </Card>
+  <Card title="Hedera Harness" icon="diagram-project" href="/solutions/tools/hedera-harness/index">
+    Turn a product brief into a Scaffold HBAR template and check that it runs
+  </Card>
   <Card title="GitHub" icon="github" href="https://github.com/hedera-dev/create-scaffold-hbar">
     Source code and contributing guide
   </Card>
@@ -404,6 +407,9 @@ npx create-scaffold-hbar@latest --yes --skip-hedera-skills
   <Card title="Scaffold UI" icon="palette" href="/solutions/tools/scaffold-hbar/scaffold-ui">
     Shared React components and hooks for Hedera dApps, plus an MCP server for AI-assisted development
   </Card>
+  <Card title="Hedera Harness" icon="diagram-project" href="/solutions/tools/hedera-harness/index">
+    Turn a product brief into a Scaffold HBAR template and check that it runs
+  </Card>
   <Card title="Hedera Skills" icon="wand-magic-sparkles" href="https://github.com/hedera-dev/hedera-skills">
     AI coding assistant skills for Hedera development
   </Card>