@mawaru/sdk 0.5.0

package/dist/init.js

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+// このファイルは dev では src/sdk/init.ts・配布物では dist/init.js に居る。
+// templates/ 等は package root 直下なので、package.json まで遡って解決する
+const packageRoot = () => {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (!existsSync(join(dir, "package.json"))) {
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error("@mawaru/sdk の package root が見つかりません");
+        }
+        dir = parent;
+    }
+    return dir;
+};
+const template = (name) => readFileSync(join(packageRoot(), "templates", name), "utf-8");
+// スキルポインタ：本体（skills/<name>/SKILL.md）の frontmatter を写して Claude Code に
+// 発見させ、中身は node_modules 内の本体へ誘導する（repo に焼くものは最小・本体は npm で解決）
+const skillPointer = (name, body) => {
+    const m = body.match(/^---\n[\s\S]*?\n---\n/);
+    const frontmatter = m?.[0];
+    if (!frontmatter) {
+        throw new Error(`skills/${name}/SKILL.md に frontmatter がありません`);
+    }
+    return `${frontmatter}
+このスキルの本体は \`node_modules/@mawaru/sdk/skills/${name}/SKILL.md\` にある
+（\`npx @mawaru/sdk init\` が生成するポインタ。本体は npm パッケージの更新で配布される）。
+**必ず本体を読み、その手順に従うこと。**
+`;
+};
+export const runInit = (root) => {
+    const written = [];
+    const skipped = [];
+    const notes = [];
+    const write = (path, content) => {
+        const abs = join(root, path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+        written.push(path);
+    };
+    // ユーザーが育てるファイル：無ければ生成・あれば触らない
+    const writeIfAbsent = (path, content) => {
+        if (existsSync(join(root, path))) {
+            skipped.push(path);
+            return;
+        }
+        write(path, content);
+    };
+    // mawaru 所有：毎回テンプレートで上書き
+    write(".github/workflows/mawaru-runner.yml", template("mawaru-runner.yml"));
+    // nodes/ の骨組みとサンプル
+    writeIfAbsent("nodes/program/echo/config.json", template("echo/config.json"));
+    writeIfAbsent("nodes/program/echo/main.ts", template("echo/main.ts"));
+    writeIfAbsent("nodes/ai/.gitkeep", "");
+    // AI 開発の足場（スキルポインタは mawaru 所有＝毎回上書き。SDK にスキルが増えたら
+    // init 再実行でポインタも増える）
+    const skillsDir = join(packageRoot(), "skills");
+    for (const name of readdirSync(skillsDir)) {
+        const bodyPath = join(skillsDir, name, "SKILL.md");
+        if (!existsSync(bodyPath))
+            continue;
+        write(`.claude/skills/${name}/SKILL.md`, skillPointer(name, readFileSync(bodyPath, "utf-8")));
+    }
+    writeIfAbsent("CLAUDE.md", template("CLAUDE.md"));
+    writeIfAbsent("README.md", template("README.md"));
+    // package.json：@mawaru/sdk を devDependencies に（ポインタ・docs の参照解決と
+    // typegen / validate CLI のため）。バージョンはこのパッケージ自身から取る
+    const sdkVersion = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf-8")).version;
+    writeIfAbsent("package.json", `${JSON.stringify({
+        name: "mawaru",
+        private: true,
+        type: "module",
+        devDependencies: { "@mawaru/sdk": `^${sdkVersion}` },
+    }, null, 2)}\n`);
+    // runner yml の `npm ci` とポインタの参照解決は node_modules / lockfile が前提
+    if (!existsSync(join(root, "package-lock.json"))) {
+        notes.push("npm install を実行して package-lock.json を commit してください（runner の npm ci と node_modules 参照に必要です）");
+    }
+    return { written, skipped, notes };
+};

package/dist/typegen.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from "./_schemas/node.js";
+import { type ProgramManifest } from "./_schemas/program-manifest.js";
+export declare const CONFIG_HASH_PREFIX = "// mawaru:config-hash=";
+export declare const configHash: (rawConfig: string) => string;
+export declare const tsTypeFromJsonSchema: (schema: JsonSchema, indent?: number) => string;
+export declare const renderTypesFile: (manifest: ProgramManifest, rawConfig: string) => string;
+export type TypegenResult = {
+    written: string[];
+    errors: {
+        dir: string;
+        message: string;
+    }[];
+};
+export declare const runTypegen: (root: string) => TypegenResult;

package/dist/typegen.js

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { programManifestSchema, } from "./_schemas/program-manifest.js";
+// 生成ファイルに刻む config.json 内容のハッシュ。validate が drift（config を変えて
+// typegen し忘れ）の検出に使う
+export const CONFIG_HASH_PREFIX = "// mawaru:config-hash=";
+export const configHash = (rawConfig) => createHash("sha256").update(rawConfig).digest("hex").slice(0, 16);
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const propertyKey = (key) => IDENTIFIER_RE.test(key) ? key : JSON.stringify(key);
+const literalType = (value) => value === null ? "null" : (JSON.stringify(value) ?? "unknown");
+// union / tuple の要素は結合子と混ざらないよう括弧で包む
+const wrapIfUnion = (type) => type.includes(" | ") || type.includes(" & ") ? `(${type})` : type;
+const objectType = (schema, indent) => {
+    const properties = schema.properties;
+    if (typeof properties !== "object" ||
+        properties === null ||
+        Array.isArray(properties)) {
+        const additional = schema.additionalProperties;
+        if (typeof additional === "object" && additional !== null) {
+            return `Record<string, ${tsTypeFromJsonSchema(additional, indent)}>`;
+        }
+        if (additional === false) {
+            return "Record<string, never>";
+        }
+        return "Record<string, unknown>";
+    }
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const inner = "  ".repeat(indent + 1);
+    const lines = [];
+    for (const [key, propSchema] of Object.entries(properties)) {
+        const description = typeof propSchema === "object" &&
+            propSchema !== null &&
+            !Array.isArray(propSchema)
+            ? propSchema.description
+            : undefined;
+        if (typeof description === "string" && description.length > 0) {
+            lines.push(`${inner}/** ${description} */`);
+        }
+        const optional = required.has(key) ? "" : "?";
+        lines.push(`${inner}${propertyKey(key)}${optional}: ${tsTypeFromJsonSchema(propSchema, indent + 1)}`);
+    }
+    if (lines.length === 0) {
+        return "Record<string, unknown>";
+    }
+    return `{\n${lines.join("\n")}\n${"  ".repeat(indent)}}`;
+};
+const namedType = (typeName, schema, indent) => {
+    switch (typeName) {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array": {
+            const items = schema.items;
+            if (Array.isArray(items)) {
+                return `[${items.map((i) => tsTypeFromJsonSchema(i, indent)).join(", ")}]`;
+            }
+            if (typeof items === "object" && items !== null) {
+                return `${wrapIfUnion(tsTypeFromJsonSchema(items, indent))}[]`;
+            }
+            return "unknown[]";
+        }
+        case "object":
+            return objectType(schema, indent);
+        default:
+            return "unknown";
+    }
+};
+// JSON Schema（zodFromJsonSchema が扱うサブセット）を TS 型の文字列に写す。
+// 解釈できない形は unknown に落とす（型が付かないだけで、実行時検証は ports 側が担う）
+export const tsTypeFromJsonSchema = (schema, indent = 0) => {
+    if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+        return "unknown";
+    }
+    if ("const" in schema) {
+        return literalType(schema.const);
+    }
+    if (Array.isArray(schema.enum)) {
+        return schema.enum.length > 0
+            ? schema.enum.map(literalType).join(" | ")
+            : "unknown";
+    }
+    const variants = schema.oneOf ?? schema.anyOf;
+    if (Array.isArray(variants) && variants.length > 0) {
+        return variants
+            .map((v) => tsTypeFromJsonSchema(v, indent))
+            .join(" | ");
+    }
+    if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        return schema.allOf
+            .map((v) => wrapIfUnion(tsTypeFromJsonSchema(v, indent)))
+            .join(" & ");
+    }
+    const type = schema.type;
+    if (Array.isArray(type)) {
+        return type.length > 0
+            ? type.map((t) => namedType(String(t), schema, indent)).join(" | ")
+            : "unknown";
+    }
+    if (typeof type === "string") {
+        return namedType(type, schema, indent);
+    }
+    return "unknown";
+};
+// Output（run の戻り値）＝「ちょうど1つの出口ポートのキーで返す封筒」の union。
+// 他ポートのキーを ?: never で締めるのは excess property check の穴
+// （union の他メンバーにあるキーは許される）を塞ぐため。複数キー封筒は
+// エンジン（resolveOutputEnvelope）が実行時に拒否する契約で、それを tsc に前倒しする
+const envelopeUnionType = (outputKeys) => {
+    const member = (key) => {
+        const props = [
+            `${propertyKey(key)}: Outputs[${JSON.stringify(key)}]`,
+            ...outputKeys
+                .filter((k) => k !== key)
+                .map((k) => `${propertyKey(k)}?: never`),
+        ];
+        return `{ ${props.join("; ")} }`;
+    };
+    const first = outputKeys[0];
+    if (outputKeys.length === 1 && first !== undefined) {
+        return `export type Output = ${member(first)}`;
+    }
+    return `export type Output =\n${outputKeys.map((k) => `  | ${member(k)}`).join("\n")}`;
+};
+export const renderTypesFile = (manifest, rawConfig) => {
+    const inputSchema = manifest.inputs.in ?? {};
+    const outputEntries = Object.entries(manifest.outputs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`);
+    // refs＝ループ変数の袋（実行時に refs.json で渡される）。config の refs はループ定義
+    // からの転写（キー→推定型）なので、宣言が無ければ型も出さない
+    const refEntries = Object.entries(manifest.refs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`);
+    return [
+        "// このファイルは mawaru typegen が config.json から自動生成した（手で編集しない）",
+        `${CONFIG_HASH_PREFIX}${configHash(rawConfig)}`,
+        "",
+        `export type Input = ${tsTypeFromJsonSchema(inputSchema)}`,
+        "",
+        `export type Outputs = {\n${outputEntries.join("\n")}\n}`,
+        "",
+        "// run の戻り値：ちょうど1つの出口ポートのキーで返す封筒",
+        envelopeUnionType(Object.keys(manifest.outputs)),
+        "",
+        ...(refEntries.length > 0
+            ? [`export type Refs = {\n${refEntries.join("\n")}\n}`, ""]
+            : []),
+    ].join("\n");
+};
+// nodes/program/ 直下の各 dir の config.json から types.d.ts を生成する
+export const runTypegen = (root) => {
+    const programsDir = join(root, "nodes", "program");
+    if (!existsSync(programsDir)) {
+        return {
+            written: [],
+            errors: [
+                {
+                    dir: "nodes/program",
+                    message: "nodes/program/ ディレクトリがありません",
+                },
+            ],
+        };
+    }
+    const written = [];
+    const errors = [];
+    for (const entry of readdirSync(programsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) {
+            continue;
+        }
+        const configPath = join(programsDir, entry.name, "config.json");
+        if (!existsSync(configPath)) {
+            errors.push({ dir: entry.name, message: "config.json がありません" });
+            continue;
+        }
+        const rawConfig = readFileSync(configPath, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(rawConfig);
+        }
+        catch {
+            errors.push({
+                dir: entry.name,
+                message: "config.json が JSON として不正です",
+            });
+            continue;
+        }
+        const manifest = programManifestSchema.safeParse(parsed);
+        if (!manifest.success) {
+            const detail = manifest.error.issues
+                .map((i) => i.path.length > 0 ? `${i.path.join(".")}: ${i.message}` : i.message)
+                .join(" / ");
+            errors.push({
+                dir: entry.name,
+                message: `config.json が規約に合いません（${detail}）`,
+            });
+            continue;
+        }
+        const typesPath = join(programsDir, entry.name, "types.d.ts");
+        writeFileSync(typesPath, renderTypesFile(manifest.data, rawConfig));
+        written.push(typesPath);
+    }
+    return { written, errors };
+};

package/dist/validate.d.ts

@@ -0,0 +1,6 @@
+export type Issue = {
+    level: "error" | "warning";
+    path: string;
+    message: string;
+};
+export declare const validateRepo: (root: string) => Issue[];

package/dist/validate.js

@@ -0,0 +1,130 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { z } from "zod";
+import { convertJsonSchemaToZod } from "zod-from-json-schema";
+import { programManifestSchema } from "./_schemas/program-manifest.js";
+import { CONFIG_HASH_PREFIX, configHash } from "./typegen.js";
+// エディタ・オーケストレータは zod-from-json-schema（common の zodFromJsonSchema）で
+// スキーマを解釈する。ここで通らないスキーマは実行時にも使えない
+const checkPortSchemas = (ports, group, path, issues) => {
+    for (const [key, schema] of Object.entries(ports)) {
+        try {
+            // 未知の type は例外でなく ZodNever（どんな値も受け付けない）に変換されるので、それも弾く
+            if (convertJsonSchemaToZod(schema) instanceof z.ZodNever) {
+                issues.push({
+                    level: "error",
+                    path,
+                    message: `${group}.${key} のスキーマがどんな値も受け付けません（type の綴りを確認してください）`,
+                });
+            }
+        }
+        catch (e) {
+            issues.push({
+                level: "error",
+                path,
+                message: `${group}.${key} のスキーマを解釈できません（${e instanceof Error ? e.message : e}）`,
+            });
+        }
+    }
+};
+const checkTypegenDrift = (programDir, rawConfig, path, issues) => {
+    const typesPath = join(programDir, "types.d.ts");
+    if (!existsSync(typesPath)) {
+        issues.push({
+            level: "warning",
+            path,
+            message: "types.d.ts がありません（mawaru typegen で生成すると main.ts に型が付きます）",
+        });
+        return;
+    }
+    const stampLine = readFileSync(typesPath, "utf8")
+        .split("\n")
+        .find((line) => line.startsWith(CONFIG_HASH_PREFIX));
+    if (!stampLine) {
+        issues.push({
+            level: "warning",
+            path: `${path}/types.d.ts`,
+            message: "typegen 管理外の types.d.ts です（ハッシュスタンプがありません）",
+        });
+        return;
+    }
+    if (stampLine.slice(CONFIG_HASH_PREFIX.length) !== configHash(rawConfig)) {
+        issues.push({
+            level: "error",
+            path: `${path}/types.d.ts`,
+            message: "config.json と乖離しています（mawaru typegen を再実行してください）",
+        });
+    }
+};
+const validateProgram = (programsDir, dir, root) => {
+    const issues = [];
+    const programDir = join(programsDir, dir);
+    const path = relative(root, programDir);
+    const configPath = join(programDir, "config.json");
+    if (!existsSync(configPath)) {
+        issues.push({ level: "error", path, message: "config.json がありません" });
+        return issues;
+    }
+    if (!existsSync(join(programDir, "main.ts"))) {
+        issues.push({ level: "error", path, message: "main.ts がありません" });
+    }
+    const rawConfig = readFileSync(configPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(rawConfig);
+    }
+    catch {
+        issues.push({
+            level: "error",
+            path: `${path}/config.json`,
+            message: "JSON として不正です",
+        });
+        return issues;
+    }
+    const manifest = programManifestSchema.safeParse(parsed);
+    if (!manifest.success) {
+        for (const issue of manifest.error.issues) {
+            const at = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+            issues.push({
+                level: "error",
+                path: `${path}/config.json`,
+                message: `${at}${issue.message}`,
+            });
+        }
+        return issues;
+    }
+    checkPortSchemas(manifest.data.inputs, "inputs", `${path}/config.json`, issues);
+    checkPortSchemas(manifest.data.outputs, "outputs", `${path}/config.json`, issues);
+    // refs はループ定義からの転写（生成物）だが、手編集や転写前の古い形が
+    // 残っている可能性があるので inputs / outputs と同じ基準で検査する
+    checkPortSchemas(manifest.data.refs, "refs", `${path}/config.json`, issues);
+    checkTypegenDrift(programDir, rawConfig, path, issues);
+    return issues;
+};
+// リポジトリ規約の構造検証。error が1つでもあれば CI を落とす想定（cli.ts が exit 1）
+export const validateRepo = (root) => {
+    const issues = [];
+    const programsDir = join(root, "nodes", "program");
+    if (!existsSync(programsDir)) {
+        issues.push({
+            level: "warning",
+            path: ".",
+            message: "nodes/program/ ディレクトリがありません",
+        });
+    }
+    else {
+        for (const entry of readdirSync(programsDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                issues.push(...validateProgram(programsDir, entry.name, root));
+            }
+        }
+    }
+    if (!existsSync(join(root, ".github", "workflows", "mawaru-runner.yml"))) {
+        issues.push({
+            level: "warning",
+            path: ".github/workflows",
+            message: "mawaru-runner.yml がありません（Actions 実行に必要です）",
+        });
+    }
+    return issues;
+};

package/docs/development.md

@@ -0,0 +1,59 @@
+# mawaru 実行 repo の loop / node 開発ガイド
+
+mawaru の実行 repo（`npx @mawaru/sdk init` で初期化された repo）で Program / AI ノードと
+loop（回路）を開発するためのガイド。**契約の正はこのパッケージの `_schemas/`（Zod スキーマ。
+日本語コメント付き）**。この文書と食い違ったらスキーマが正。
+
+## repo の位置づけ
+
+- この repo に置くのは**ユーザーのカスタマイズ**（ノードの実装・定義）とその履歴だけ
+- 実行基盤の実態（runner・ラッパー）は npm パッケージ（`@mawaru/agent-runner`）にあり、
+  mawaru が dispatch payload でバージョンを指定して実行する。repo 側の更新は不要
+- `.github/workflows/mawaru-runner.yml` は mawaru 所有の薄いシム。**編集しない**
+  （改訂は `npx @mawaru/sdk init` の再実行で配布される）
+
+## ディレクトリ規約
+
+```
+nodes/
+  program/<dir>/   # Program ノード：config.json ＋ main.ts（＋任意で package.json）
+  ai/<dir>/        # AI ノード定義：config.json
+  hook/<dir>/      # NodeIOHook：config.json ＋ main.ts（ノードに付く観測フック）
+skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
+```
+
+## Program ノード（`nodes/program/<dir>/`）
+
+- `config.json` — 入出力スキーマ等の宣言。正は `_schemas/program-manifest.ts`
+  （`inputs` は `"in"` の1件だけ・`outputs` は1件以上・`env` は必要な secret 名の宣言）
+- `main.ts` — `run(input, ctx)` を export する。`ctx.refs` にループ変数が入る。戻り値：
+  - `{ <出口ポートのkey>: <データ> }` の**単一キー封筒**（どの出口から出るかを戻り値自身が運ぶ）
+  - `"pending"` — 完了保留（外部イベントで後から end が届く）
+- 型生成：`npx mawaru typegen` が config.json から `types.d.ts`（Input / Outputs 型）を生成する
+- **ノード単位の npm 依存**：`<dir>/package.json` を置けば実行前にそのディレクトリで
+  `npm ci` される。`package-lock.json` の commit が必須（無いと明瞭に失敗する）
+- 環境変数：`config.json` の `env` に宣言した secret（repo の Actions secrets）だけが
+  実行時に渡される（最小権限）
+
+## AI ノード（`nodes/ai/<dir>/`）
+
+- `config.json` — 正は `_schemas/ai-manifest.ts`。`prompt`（必須）・`model`・
+  `skills`（トップレベル `skills/` 配下のディレクトリ名）・`env`・`inputs` / `outputs`
+- 実行時はラッパーが Claude Code（headless）を起動し、`outputs` のスキーマに適合する
+  output を検証して報告する。出口が複数あれば AI が1つ選ぶ（複数出口＝分岐）
+
+## フック（`nodes/hook/<dir>/`）
+
+- ノードの入出力・外部シグナルを観測する独立実行。正は `_schemas/hook-manifest.ts`
+  （`on`: input / output / signal の宣言・`env`）
+
+## loop（回路）の作成・更新
+
+- `.claude/skills/create-loop` スキルに従う（graph API の契約は `_schemas/graph.ts` が正）
+- ノードのポートは repo の config.json から取り込まれる（repo が正・エディタ保存時に
+  書き戻し同期される）
+
+## 検証
+
+- `npx mawaru validate` — リポジトリ規約の検証（CI 向け。error で exit 1）
+- config.json を変えたら `npx mawaru typegen` で型を更新し、ズレをコンパイルで検出する

package/index.ts

@@ -0,0 +1,9 @@
+// mawaru の契約スキーマ（実行 repo の config.json 規約＋ループ graph API のボディ）。
+// 正はここ（npm 公開）で、@mawaru/common（private）が re-export して
+// backend / frontend が使う。CLI（typegen / validate）の実装は export しない
+export * from "./_schemas/ai-manifest.js"
+export * from "./_schemas/graph.js"
+export * from "./_schemas/hook-manifest.js"
+export * from "./_schemas/node.js"
+export * from "./_schemas/port-spec.js"
+export * from "./_schemas/program-manifest.js"

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@mawaru/sdk",
+  "version": "0.5.0",
+  "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
+  "type": "module",
+  "bin": {
+    "mawaru": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "templates",
+    "docs",
+    "_schemas",
+    "index.ts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "zod-from-json-schema": "^0.5.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}

package/skills/create-loop/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: create-loop
+description: mawaru のループ（回路）を API 経由で作成・更新するスキル。「◯◯するループを作って」「mawaru にループを定義して」「このプログラムをループにつないで」などのリクエストで発動する。実行 repo（nodes/program・nodes/ai を持つリポジトリ）の中で使う。
+---
+
+# create-loop — mawaru のループを API で作成する
+
+mawaru のループ（Program / AI / Human / Wait ノードを connection でつないだ回路）を、
+エディタを使わず REST API で作成・更新する手順。
+
+## セットアップ（初回のみ。揃っていればスキップ）
+
+repo ルートの `.env` に以下の4変数が揃っているか確認する。足りなければ**このスキルの中で
+セットアップまで面倒を見る**（ユーザーに手作業のセットアップを求めない）：
+
+1. `.gitignore` に `.env` が入っていることを確認する。無ければ追加する（API キーをコミットさせない）。
+2. `.env` を作成・追記する：
+   - `MAWARU_API_URL` — API のベース URL（例: `https://api.mawaru.ai`。ローカル開発は `http://localhost:9000`）
+   - `MAWARU_APP_URL` — フロントの URL（例: `https://app.mawaru.ai`。ローカル開発は `http://localhost:3000`）
+   - `MAWARU_TENANT_ID` — tenant の ID
+   - `MAWARU_API_KEY` — tenant の API キー
+   接続先が本番かローカルかはユーザーに確認する。API キーは mawaru のテナント設定画面
+   （`{MAWARU_APP_URL}/settings` の「API キー」。admin のみ）で発行・コピーできるので、
+   ユーザーに案内して値を入力してもらう。**キーの値をチャット・ログ・コミットに出さない。**
+3. 疎通確認：`GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/loops` が 200 を返せば完了。
+   401 なら API キー、404 なら tenant ID を疑う。
+
+認証は全リクエスト共通でヘッダ `x-api-key: $MAWARU_API_KEY`。
+
+## 契約の読み方（最重要）
+
+**API のボディ形をこの文書は説明しない。正はこのパッケージ内の Zod スキーマなので、必ずソースを読むこと**：
+
+- `node_modules/@mawaru/sdk/_schemas/graph.ts` — graph 保存ボディ（`saveGraphBodySchema`）。
+  ノード・接続・refs（ループ変数）・hooks の形と、superRefine 内の全整合性ルール（日本語コメント付き）
+- `node_modules/@mawaru/sdk/_schemas/node.ts` — ポートの形（`graphPortSchema`）と key の規則
+- `node_modules/@mawaru/sdk/_schemas/port-spec.ts` — **kind 別の必須ポート構成**（`kindPortsViolation`）と
+  接続の型規則（human の in はカタログ型 envelope、program の in はスキーマ包含 等）
+- `node_modules/@mawaru/sdk/_schemas/program-manifest.ts` / `ai-manifest.ts` — repo 側 config.json の規約
+- 同ディレクトリの `*.test.ts` — 通る graph / 弾かれる graph の実例集として読める
+
+## API（パスとボディは openapi.json が正）
+
+**パス・メソッド・リクエストボディを手書きで写さない。サーバが自己記述する OpenAPI を読む**：
+
+疎通確認のあと `GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/openapi.json`
+（ヘッダ `x-api-key: $MAWARU_API_KEY`）を取得すると、機械 API 面
+（loops の一覧・作成・詳細・graph PUT、runs/start、members、api-keys、steps の end / decision）の
+パス・メソッド・リクエストボディ（Zod 由来の JSON Schema）が載っている。ここが常に正。
+段階導入中で未掲載のエンドポイントもある（その場合だけ `api/index.ts` 相当を辿る）。
+
+すべて `{MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/` 配下。openapi.json のボディ schema は
+形（キー・型）まで。graph の詳細な整合性ルール（superRefine）は上の Zod ソースが正なので
+必ず併読すること。
+
+エラーは正直に返る：ボディ形の違反は 422（zod の issue が日本語で入っている）、意味の違反も 422、
+repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等な全量置換なので、
+エラーメッセージを読んで直して再送を繰り返せばよい。**
+
+## 手順
+
+1. **設計**：要件から必要なノード（program / ai / human / wait）と流れを決め、ユーザーに一言で確認する。
+2. **repo 側の準備**：足りない program / ai は `nodes/program/<dir>/` / `nodes/ai/<dir>/` に作る
+   （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
+   **作った・変えたものは GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で
+   読むため、未 push だと graph 保存の検証・書き戻しと食い違って 409 になる）。
+3. **ループ作成**：`POST loops`。
+4. **graph ボディを組む**：
+   - node / port の `id` はクライアント採番（`uuidgen` などで UUID を作る）
+   - program / ai ノードの ports は repo の config.json の inputs / outputs をそのまま写す
+     （in ポート key は `in`、out ポートは outputs の各 key）
+   - kind 別の固定ポート構成（human / wait / ai）は `port-spec.ts` の `kindPortsViolation` に従う
+   - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
+     ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
+     `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）
+   - `position_x` / `position_y` は左→右に流れる単純配置（例: x を 320 刻み、y は 240）
+5. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
+6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、
+   見た目の確認と run はユーザーに委ねる。
+
+## 注意
+
+- **graph PUT は全量置換**。既存ループを更新するときは、必ず先に `GET loops/{loopId}` で
+  現状を取り、何を変えるかの差分をユーザーに提示して確認してから PUT する。
+- ノードの `kind` は変更不可（変えたいときは別 id で置き直す）。run 履歴から参照されている
+  ノードは削除できない（409）。
+- 秘密情報（API キー）をコミットしない。`.env` は .gitignore されていることを確認する。