toolfactory 0.3.1 → 0.4.2

package/README.md

@@ -22,7 +22,7 @@ generated and every surface still installs, builds and publishes.
 - **Gemini CLI extension** — `gemini extensions install https://github.com/GoatInAHat/toolfactory`
 - **OpenClaw plugin** — `openclaw plugins install --link hosts/openclaw` from a checkout
 - **Hermes plugin** — `hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes`
-- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.3.1.tgz`
+- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.4.2.tgz`
 - **Web app** — `npx -y toolfactory mcp --http --open` serves the operations page beside the
   MCP endpoint on one port and opens it; over MCP or a skill, the `web` operation does the same and
   returns the URL.

package/dist/bindings/typescript.test.js

@@ -88,6 +88,17 @@ describe("typescript binding", () => {
         const scripts = JSON.parse(text(scaffold(project(["cli"])), "package.json")).scripts;
         expect(scripts["test:live"]).toBe("node --env-file-if-exists=.env node_modules/vitest/vitest.mjs run tests/live.test.ts");
     });
+    it("supports a host-vault live gate without making credentials globally required config", () => {
+        const base = project(["cli"]);
+        base.tool.tests.live = { credentials: ["LIVE_VAULT_READY"], ci: false };
+        base.operations = [{ name: "read", inputSchema: { type: "object" }, requires: [] }];
+        const live = liveTest(base)[0];
+        if (live?.kind !== "region")
+            throw new Error("expected a region file");
+        expect(live.regions[0]?.content).toContain('const CREDENTIALS = ["LIVE_VAULT_READY"];');
+        expect(base.tool.config?.required).toBeUndefined();
+        expect(ToolConfigSchema.safeParse({ ...base.tool, tests: { live: { credentials: [] } } }).success).toBe(false);
+    });
     it("emits opt-in --http and --pair flags, defaulting to stdio, on the mcp module and the cli", () => {
         const files = [...kernel(project(["mcp", "cli"])), ...cliFiles(project(["mcp", "cli"]))];
         const mcp = text(files, "src/toolfactory/mcp.ts");

package/dist/commands.js

@@ -5,7 +5,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
 import { parseEnv } from "node:util";
 import { getBinding } from "./bindings/index.js";
 import { LIVE_TEST_COMMAND } from "./bindings/python.js";
@@ -72,6 +73,26 @@ function agentSetup(root) {
         .flatMap((line) => line.match(/^Generated ([^:]+):/)?.slice(1, 2) ?? []);
     return { setup: result.status === 0, harnesses };
 }
+/**
+ * The shared OpenClaw project registry (owner decision 2026-09-19, `docs/adoption.md`): a tool
+ * scaffolded under `~/.openclaw/projects/<id>` gets its project row at `init` time, best-effort
+ * the way `.agents/setup` is — no reachable gateway (or CLI) still leaves a scaffolded project,
+ * and the next step carries the exact call to run. Session creation stays with the calling agent.
+ * TOOLFACTORY_OPENCLAW_PROJECTS_ROOT overrides the registry root (deployments, tests).
+ */
+function registerOpenClawProject(root, dryRun) {
+    const registryRoot = process.env.TOOLFACTORY_OPENCLAW_PROJECTS_ROOT ?? join(homedir(), ".openclaw", "projects");
+    const beneath = relative(registryRoot, root);
+    if (!beneath || beneath.startsWith("..") || resolve(beneath) === beneath)
+        return undefined;
+    const args = ["gateway", "call", "projects.register", "--params", JSON.stringify({ path: root })];
+    if (dryRun)
+        return ("OpenClaw: run `openclaw " + args.join(" ") + "` to add it to the shared project registry.");
+    const registered = spawnSync("openclaw", args, { timeout: 60_000 });
+    return registered.status === 0
+        ? "OpenClaw: registered in the shared project registry; bind one visible dashboard session to it for ongoing work."
+        : "OpenClaw: registration did not succeed — run the `openclaw gateway call projects.register` step once the gateway is reachable.";
+}
 function nextSteps(project, agentConfig) {
     const cli = toolfactoryCli(project);
     const ops = project.tool.binding === "typescript"
@@ -194,10 +215,13 @@ export function init(options) {
             git(root, [...commitIdentity(root), "commit", "-q", "--no-verify", "-m", "toolfactory init"]);
         }
     }
+    const steps = nextSteps(built.project, agentConfig);
+    // Last, because registration wants the committed repository on record, not a bare scaffold.
+    const openclaw = registerOpenClawProject(root, options.dryRun === true);
     const result = {
         written,
         agentConfig,
-        nextSteps: nextSteps(built.project, agentConfig),
+        nextSteps: openclaw ? [...steps, openclaw] : steps,
     };
     if (options.repo) {
         const project = loadProject(root);

package/dist/commands.test.js

@@ -213,3 +213,33 @@ describe("unpublish", () => {
         expect(result.steps.some((step) => step.run.includes("npm deprecate probe@'*'"))).toBe(true);
     });
 });
+describe("registerOpenClawProject", () => {
+    it("reports the exact register call for a tool scaffolded under the shared registry (dry-run)", () => {
+        const registry = join(mkdtempSync(join(tmpdir(), "tf-home-")), ".openclaw", "projects");
+        process.env.TOOLFACTORY_OPENCLAW_PROJECTS_ROOT = registry;
+        const root = join(registry, "probe");
+        const result = commands.init({
+            root,
+            name: "probe",
+            binding: "typescript",
+            setup: false,
+            git: false,
+            dryRun: true,
+        });
+        const line = result.nextSteps.find((step) => step.startsWith("OpenClaw:"));
+        expect(line).toBe("OpenClaw: run `openclaw gateway call projects.register --params " +
+            JSON.stringify({ path: root }) +
+            "` to add it to the shared project registry.");
+    });
+    it("says nothing outside the shared registry", () => {
+        const result = commands.init({
+            root: join(tmpdir(), "tf-plain"),
+            name: "probe",
+            binding: "typescript",
+            setup: false,
+            git: false,
+            dryRun: true,
+        });
+        expect(result.nextSteps.some((step) => step.startsWith("OpenClaw:"))).toBe(false);
+    });
+});

package/dist/hosts/github.js

@@ -45,12 +45,11 @@ export function bootstrapRepo(project, options = {}) {
     const manual = (options.manual ?? []).filter((step) => !step.startsWith("npm:"));
     const envFile = options.envFile ?? join(project.root, ".env");
     const values = existsSync(envFile) ? parseEnv(readFileSync(envFile, "utf8")) : {};
-    const keys = liveCredentials(project);
+    const keys = project.tool.tests.live?.ci === false ? [] : liveCredentials(project);
     const commands = [];
     const written = [];
     const missing = [];
-    // The live tier's own environment, and only when the project has a live tier: a `tool.json`
-    // config key that is both required and sensitive is the whole trigger (§6 T4).
+    // A local-vault-only live tier does not need a GitHub environment or copied account secrets.
     if (keys.length) {
         const ids = reviewers.map((login) => {
             const args = ["api", `users/${login}`, "--jq", ".id"];

package/dist/hosts/openclaw.js

@@ -24,7 +24,8 @@ const PER_TOOL_KEYS = new Set(["name", "version", "description"]);
  */
 function overridden(project) {
     const openclaw = project.tool.openclaw;
-    const paths = new Set();
+    // The host development dependency is deliberately pinned to the recorded scaffold release.
+    const paths = new Set([".devDependencies.openclaw"]);
     for (const section of ["dependencies", "peerDependencies", "devDependencies"]) {
         for (const key of Object.keys(openclaw?.[section] ?? {}))
             paths.add(`.${section}.${key}`);
@@ -74,7 +75,7 @@ export function scaffoldDrift(project) {
     // The probe must run the exact openclaw this project pins (author override or the
     // scaffold default) - never whatever happens to be on PATH, which made the drift verdict
     // environment-dependent: the scaffold openclawVersion is the running CLI own version.
-    const pin = project.tool.openclaw?.devDependencies?.openclaw ?? OPENCLAW_SCAFFOLD.devDependencies.openclaw;
+    const pin = project.tool.openclaw?.devDependencies?.openclaw ?? OPENCLAW_SCAFFOLD.openclawVersion;
     const pinned = join(project.root, HOST_DIR, "node_modules/.bin/openclaw");
     try {
         const probe = existsSync(pinned)

package/dist/model.d.ts

@@ -89,6 +89,10 @@ export declare const ToolConfigSchema: z.ZodObject<{
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     tests: z.ZodDefault<z.ZodObject<{
         examples: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        live: z.ZodOptional<z.ZodObject<{
+            credentials: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ci: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     npm: z.ZodOptional<z.ZodObject<{
         scope: z.ZodOptional<z.ZodString>;

package/dist/model.js

@@ -102,7 +102,22 @@ export const ToolConfigSchema = z
         property.default === undefined), "A sensitive config property must not declare a default: it would be committed into every manifest.")
         .describe("JSON Schema 2020-12 object for the tool's configuration; mark secrets with x-toolfactory.sensitive."),
     tests: z
-        .object({ examples: z.record(z.string(), jsonObject).default({}) })
+        .object({
+        examples: z.record(z.string(), jsonObject).default({}),
+        live: z
+            .object({
+            credentials: z
+                .array(z.string().regex(/^[A-Z_][A-Z0-9_]*$/))
+                .min(1)
+                .optional()
+                .describe("Environment gates for live tests when auth is supplied outside tool config, such as a host vault. Names only, never values."),
+            ci: z
+                .boolean()
+                .optional()
+                .describe("Set false for live tests that require a local vault or browser unavailable on hosted CI. The native local live-test tier is still generated."),
+        })
+            .optional(),
+    })
         .default({ examples: {} })
         .describe("Example arguments per operation, used by the generated surface-smoke tests."),
     npm: z.object({ scope: z.string().optional() }).optional(),

package/dist/project/gate.js

@@ -258,11 +258,10 @@ export function packageSteps(project, options = {}) {
             run: [
                 `npm --prefix ${OPENCLAW_HOST_DIR} install`,
                 `npm --prefix ${OPENCLAW_HOST_DIR} run build`,
-                `v=$(node -p "require('./package.json').version")`,
                 `cp ${OPENCLAW_HOST_DIR}/package.json ${OPENCLAW_HOST_DIR}/package.json.prepack`,
-                `(cd ${OPENCLAW_HOST_DIR} && npm pkg set dependencies.toolfactory=$v)`,
-                `npm pack ./${OPENCLAW_HOST_DIR} --pack-destination ${RELEASE_DIR}`,
-                `mv ${OPENCLAW_HOST_DIR}/package.json.prepack ${OPENCLAW_HOST_DIR}/package.json`,
+                `(trap 'mv ${OPENCLAW_HOST_DIR}/package.json.prepack ${OPENCLAW_HOST_DIR}/package.json' EXIT; ` +
+                    `(cd ${OPENCLAW_HOST_DIR} && npm pkg set 'dependencies.${npmName(project)}=${project.identity.version}') && ` +
+                    `npm pack ./${OPENCLAW_HOST_DIR} --pack-destination ${RELEASE_DIR})`,
             ].join(" && "),
         });
     }

package/dist/project/history.d.ts

@@ -16,6 +16,10 @@ export declare function toolAtRef(root: string, ref: string): {
     };
     tests: {
         examples: Record<string, Record<string, unknown>>;
+        live?: {
+            credentials?: string[] | undefined;
+            ci?: boolean | undefined;
+        } | undefined;
     };
     $schema?: string | undefined;
     runtime?: "kernel" | "none" | undefined;

package/dist/surfaces/agents.js

@@ -519,7 +519,13 @@ function setupTail(project) {
                     "    exit 1",
                     "fi",
                 ]
-                : ["npm install --no-audit --no-fund"];
+                : [
+                    "if [ -f package-lock.json ]; then",
+                    "    npm ci --no-audit --no-fund",
+                    "else",
+                    "    npm install --no-audit --no-fund",
+                    "fi",
+                ];
     return [
         "",
         "# The pre-commit hook installed above converges agent config; toolfactory's drift gate goes in",

package/dist/surfaces/agents.test.js

@@ -106,6 +106,7 @@ describe("agents", () => {
         expect(setup).not.toContain("# Project setup goes here");
         // Owner ask #11: a commit cannot leave a generated file stale, with or without CI.
         expect(setup).toContain("npx toolfactory check >/dev/null");
+        expect(setup).toContain("if [ -f package-lock.json ]; then\n    npm ci --no-audit --no-fund");
         expect(setup).toContain("npm install --no-audit --no-fund");
     });
     it("installs uv before Python projects run the vendored setup workflow", () => {

package/dist/surfaces/openclaw-native.js

@@ -251,6 +251,7 @@ function packageJson(project, operations, kase) {
         dependencies: { ...OPENCLAW_SCAFFOLD.dependencies, ...core, ...extra?.dependencies },
         devDependencies: {
             ...OPENCLAW_SCAFFOLD.devDependencies,
+            openclaw: openclawVersion(project),
             ...(kase ? { "@copilotkit/aimock": OPENCLAW_ADDITIONS.aimock } : {}),
             ...extra?.devDependencies,
         },

package/dist/surfaces/openclaw-native.test.js

@@ -117,7 +117,10 @@ describe("openclaw-native", () => {
         expect(files[`${HOST_DIR}/README.md`]).toContain("excluded:implement-in-hosts");
         expect(files[`${HOST_DIR}/README.md`]).toContain("`shoot` — requires browser");
         const pkg = JSON.parse(files[`${HOST_DIR}/package.json`] ?? "{}");
-        expect(pkg.devDependencies).toMatchObject(OPENCLAW_SCAFFOLD.devDependencies);
+        expect(pkg.devDependencies).toMatchObject({
+            ...OPENCLAW_SCAFFOLD.devDependencies,
+            openclaw: OPENCLAW_SCAFFOLD.openclawVersion,
+        });
         expect(pkg.openclaw).toEqual({
             extensions: ["./dist/index.js"],
             compat: { pluginApi: OPENCLAW_SCAFFOLD.pluginApi },

package/dist/surfaces/shared.js

@@ -94,6 +94,8 @@ export function dataDirEnvName(project) {
  * A tool with none has nothing to gate a live tier on, so no live test and no `live` CI job.
  */
 export function liveCredentials(project) {
+    if (project.tool.tests.live?.credentials)
+        return project.tool.tests.live.credentials;
     const properties = configProperties(project);
     const required = new Set(requiredConfig(project));
     return Object.keys(properties).filter((key) => required.has(key) && isSensitive(properties[key]));

package/dist/surfaces/vscode-extension.js

@@ -239,7 +239,7 @@ export const surface = {
                 format: "json",
                 patch: {
                     compilerOptions: {
-                        module: "Node16",
+                        module: "NodeNext",
                         target: "ES2022",
                         lib: ["ES2022"],
                         types: ["node", "mocha"],

package/dist/surfaces/web.d.ts

@@ -36,8 +36,8 @@ export declare const WEB_SCAFFOLD: {
             readonly "@fontsource-variable/geist": "^5.3.0";
             readonly "@tailwindcss/vite": "^4.3.3";
             readonly "class-variance-authority": "^0.7.1";
-            readonly cn: "^0.3.0";
-            readonly "lucide-react": "^1.46.0";
+            readonly cn: "^0.4.0";
+            readonly "lucide-react": "^1.48.0";
             readonly react: "^19.2.8";
             readonly "react-dom": "^19.2.8";
             readonly shadcn: "^4.21.0";

package/dist/surfaces/web.js

@@ -149,8 +149,8 @@ export default defineConfig({
             "@fontsource-variable/geist": "^5.3.0",
             "@tailwindcss/vite": "^4.3.3",
             "class-variance-authority": "^0.7.1",
-            cn: "^0.3.0",
-            "lucide-react": "^1.46.0",
+            cn: "^0.4.0",
+            "lucide-react": "^1.48.0",
             react: "^19.2.8",
             "react-dom": "^19.2.8",
             shadcn: "^4.21.0",

package/dist/surfaces/workflows.js

@@ -150,10 +150,17 @@ function actionStep(step, matrix) {
  * (an environment gates deployments, not the checkout an untrusted PR ships).
  */
 function liveJob(project) {
+    if (project.tool.tests.live?.ci === false)
+        return undefined;
     if (liveCredentials(project).length === 0)
         return undefined;
     const properties = configProperties(project);
-    const secrets = Object.keys(properties).filter((key) => isSensitive(properties[key]));
+    const secrets = [
+        ...new Set([
+            ...Object.keys(properties).filter((key) => isSensitive(properties[key])),
+            ...liveCredentials(project),
+        ]),
+    ];
     const pmName = project.packageManager ?? "npm";
     const pm = PACKAGE_MANAGER_COMMANDS[pmName];
     const steps = project.tool.binding === "typescript"

package/dist/surfaces/workflows.test.js

@@ -1,5 +1,5 @@
 import { execFileSync, spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
@@ -365,6 +365,18 @@ describe("workflows", () => {
         expect(composeHermes.services.hermes.command[2]).toContain("hermes plugins doctor /work/hosts/hermes/hello_hermes --ci");
         expect(composeHermes.services.openclaw).toBeUndefined();
     });
+    it("supports explicit live credentials without making runtime configuration mandatory", () => {
+        const target = project(["cli"]);
+        target.tool.config = undefined;
+        target.tool.tests.live = { credentials: ["LIVE_ACCOUNT_READY"] };
+        const ci = yamlParse(emitted(target)[".github/workflows/ci.yml"]);
+        expect(ci.jobs.live.env).toEqual({ LIVE_ACCOUNT_READY: "${{ secrets.LIVE_ACCOUNT_READY }}" });
+        expect(ci.jobs.live.environment).toBe("live-tests");
+        target.tool.tests.live.ci = false;
+        const localOnly = yamlParse(emitted(target)[".github/workflows/ci.yml"]);
+        expect(localOnly.jobs.live).toBeUndefined();
+        expect(localOnly.on.workflow_dispatch).toBeUndefined();
+    });
     it("adds the T4 live job, and workflow_dispatch, iff a config key is required and sensitive", () => {
         const ci = yamlParse(emitted(project(["cli"]))[".github/workflows/ci.yml"]);
         expect(ci.on.workflow_dispatch).toEqual({});
@@ -513,6 +525,10 @@ describe("bootstrap-repo", () => {
         expect(release.manual.join(" ")).toContain("granular access tokens with bypass 2FA are unsupported");
         expect(release.manual.join(" ")).toContain("NPM_TRUSTED_PUBLISHER");
         expect(release.manual.filter((step) => step.startsWith("npm:"))).toHaveLength(1);
+        noCredential.tool.tests.live = { credentials: ["LOCAL_VAULT_READY"], ci: false };
+        const localOnly = bootstrapRepo(noCredential, { dryRun: true });
+        expect(localOnly.secrets).toEqual([]);
+        expect(localOnly.commands.some((command) => command.includes("live-tests"))).toBe(false);
     });
 });
 /**
@@ -546,6 +562,53 @@ describe("gate", () => {
             "openclaw end-to-end (scripted model, no LLM key)",
         ]);
     });
+    it("packs the actual core dependency and restores the host manifest after success or failure", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-plugin-pack-"));
+        mkdirSync(join(root, "hosts/openclaw"), { recursive: true });
+        mkdirSync(join(root, "bin"));
+        const manifest = {
+            name: "openclaw-plugin-example",
+            dependencies: { "@example/core": "file:../.." },
+        };
+        writeFileSync(join(root, "hosts/openclaw/package.json"), JSON.stringify(manifest));
+        writeFileSync(join(root, "bin/npm"), `#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const args = process.argv.slice(2);
+if (args[0] === 'pkg') {
+  const value = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+  const [key, version] = args[2].slice('dependencies.'.length).split('=');
+  value.dependencies[key] = version;
+  fs.writeFileSync('package.json', JSON.stringify(value));
+} else if (args[0] === 'pack') {
+  fs.copyFileSync('hosts/openclaw/package.json', 'packed.json');
+  process.exit(Number(process.env.PACK_EXIT || 0));
+}
+`, { mode: 0o755 });
+        const target = project(["npm", "openclaw-native"], {
+            identity: { name: "core", version: "1.2.3", description: "Example" },
+        });
+        // npmName is the publication mapping, not the Tool Factory package's name.
+        target.tool.npm = { scope: "@example" };
+        const command = packageSteps(target).find((step) => step.name === "OpenClaw plugin tarball")?.run;
+        if (!command)
+            throw new Error("OpenClaw packaging step is missing");
+        for (const code of [0, 7]) {
+            const result = spawnSync("sh", ["-c", command], {
+                cwd: root,
+                env: {
+                    ...process.env,
+                    PATH: `${join(root, "bin")}:${process.env.PATH}`,
+                    PACK_EXIT: String(code),
+                },
+            });
+            expect(result.status, result.stderr.toString()).toBe(code);
+            expect(JSON.parse(readFileSync(join(root, "packed.json"), "utf8")).dependencies).toEqual({
+                "@example/core": "1.2.3",
+            });
+            expect(JSON.parse(readFileSync(join(root, "hosts/openclaw/package.json"), "utf8"))).toEqual(manifest);
+        }
+    });
     it("packages one asset per selected distribution surface into dist/release", () => {
         const target = project([
             "npm",

package/dist/toolfactory/cli.js

@@ -11,7 +11,7 @@ const operations = [...authored, web];
 const program = new Command()
     .name("toolfactory")
     .description("Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.")
-    .version("0.3.1");
+    .version("0.4.2");
 for (const op of operations) {
     if (!serves(op, "cli"))
         continue;

package/dist/toolfactory/mcp.js

@@ -30,7 +30,7 @@ const operations = [...authored, web];
 const introspecting = Boolean(process.env.TOOLFACTORY_INTROSPECT);
 /** Builds one server instance with every servable operation registered; called once for stdio, once per HTTP request. */
 function createServer() {
-    const server = new McpServer({ name: "toolfactory", version: "0.3.1" });
+    const server = new McpServer({ name: "toolfactory", version: "0.4.2" });
     for (const op of operations) {
         if (!introspecting && !serves(op, "mcp"))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfactory",
-  "version": "0.3.1",
+  "version": "0.4.2",
   "description": "Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.",
   "license": "MIT",
   "repository": {

package/src/bindings/typescript.test.ts

@@ -120,6 +120,19 @@ describe("typescript binding", () => {
     );
   });
 
+  it("supports a host-vault live gate without making credentials globally required config", () => {
+    const base = project(["cli"]);
+    base.tool.tests.live = { credentials: ["LIVE_VAULT_READY"], ci: false };
+    base.operations = [{ name: "read", inputSchema: { type: "object" }, requires: [] }];
+    const live = liveTest(base)[0];
+    if (live?.kind !== "region") throw new Error("expected a region file");
+    expect(live.regions[0]?.content).toContain('const CREDENTIALS = ["LIVE_VAULT_READY"];');
+    expect(base.tool.config?.required).toBeUndefined();
+    expect(
+      ToolConfigSchema.safeParse({ ...base.tool, tests: { live: { credentials: [] } } }).success,
+    ).toBe(false);
+  });
+
   it("emits opt-in --http and --pair flags, defaulting to stdio, on the mcp module and the cli", () => {
     const files = [...kernel(project(["mcp", "cli"])), ...cliFiles(project(["mcp", "cli"]))];
     const mcp = text(files, "src/toolfactory/mcp.ts");

package/src/commands.test.ts

@@ -251,3 +251,37 @@ describe("unpublish", () => {
     expect(result.steps.some((step) => step.run.includes("npm deprecate probe@'*'"))).toBe(true);
   });
 });
+
+describe("registerOpenClawProject", () => {
+  it("reports the exact register call for a tool scaffolded under the shared registry (dry-run)", () => {
+    const registry = join(mkdtempSync(join(tmpdir(), "tf-home-")), ".openclaw", "projects");
+    process.env.TOOLFACTORY_OPENCLAW_PROJECTS_ROOT = registry;
+    const root = join(registry, "probe");
+    const result = commands.init({
+      root,
+      name: "probe",
+      binding: "typescript",
+      setup: false,
+      git: false,
+      dryRun: true,
+    });
+    const line = result.nextSteps.find((step) => step.startsWith("OpenClaw:"));
+    expect(line).toBe(
+      "OpenClaw: run `openclaw gateway call projects.register --params " +
+        JSON.stringify({ path: root }) +
+        "` to add it to the shared project registry.",
+    );
+  });
+
+  it("says nothing outside the shared registry", () => {
+    const result = commands.init({
+      root: join(tmpdir(), "tf-plain"),
+      name: "probe",
+      binding: "typescript",
+      setup: false,
+      git: false,
+      dryRun: true,
+    });
+    expect(result.nextSteps.some((step) => step.startsWith("OpenClaw:"))).toBe(false);
+  });
+});

package/src/commands.ts

@@ -5,7 +5,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
 import { parseEnv } from "node:util";
 import { getBinding } from "./bindings/index.js";
 import { LIVE_TEST_COMMAND } from "./bindings/python.js";
@@ -163,6 +164,29 @@ function agentSetup(root: string): InitResult["agentConfig"] {
   return { setup: result.status === 0, harnesses };
 }
 
+/**
+ * The shared OpenClaw project registry (owner decision 2026-09-19, `docs/adoption.md`): a tool
+ * scaffolded under `~/.openclaw/projects/<id>` gets its project row at `init` time, best-effort
+ * the way `.agents/setup` is — no reachable gateway (or CLI) still leaves a scaffolded project,
+ * and the next step carries the exact call to run. Session creation stays with the calling agent.
+ * TOOLFACTORY_OPENCLAW_PROJECTS_ROOT overrides the registry root (deployments, tests).
+ */
+function registerOpenClawProject(root: string, dryRun: boolean): string | undefined {
+  const registryRoot =
+    process.env.TOOLFACTORY_OPENCLAW_PROJECTS_ROOT ?? join(homedir(), ".openclaw", "projects");
+  const beneath = relative(registryRoot, root);
+  if (!beneath || beneath.startsWith("..") || resolve(beneath) === beneath) return undefined;
+  const args = ["gateway", "call", "projects.register", "--params", JSON.stringify({ path: root })];
+  if (dryRun)
+    return (
+      "OpenClaw: run `openclaw " + args.join(" ") + "` to add it to the shared project registry."
+    );
+  const registered = spawnSync("openclaw", args, { timeout: 60_000 });
+  return registered.status === 0
+    ? "OpenClaw: registered in the shared project registry; bind one visible dashboard session to it for ongoing work."
+    : "OpenClaw: registration did not succeed — run the `openclaw gateway call projects.register` step once the gateway is reachable.";
+}
+
 function nextSteps(project: Project, agentConfig: InitResult["agentConfig"]): string[] {
   const cli = toolfactoryCli(project);
   const ops =
@@ -290,10 +314,13 @@ export function init(options: InitOptions): InitResult {
       git(root, [...commitIdentity(root), "commit", "-q", "--no-verify", "-m", "toolfactory init"]);
     }
   }
+  const steps = nextSteps(built.project, agentConfig);
+  // Last, because registration wants the committed repository on record, not a bare scaffold.
+  const openclaw = registerOpenClawProject(root, options.dryRun === true);
   const result: InitResult = {
     written,
     agentConfig,
-    nextSteps: nextSteps(built.project, agentConfig),
+    nextSteps: openclaw ? [...steps, openclaw] : steps,
   };
   if (options.repo) {
     const project = loadProject(root);

package/src/hosts/github.ts

@@ -87,13 +87,12 @@ export function bootstrapRepo(project: Project, options: BootstrapOptions = {}):
   const manual = (options.manual ?? []).filter((step) => !step.startsWith("npm:"));
   const envFile = options.envFile ?? join(project.root, ".env");
   const values = existsSync(envFile) ? parseEnv(readFileSync(envFile, "utf8")) : {};
-  const keys = liveCredentials(project);
+  const keys = project.tool.tests.live?.ci === false ? [] : liveCredentials(project);
   const commands: string[] = [];
   const written: string[] = [];
   const missing: string[] = [];
 
-  // The live tier's own environment, and only when the project has a live tier: a `tool.json`
-  // config key that is both required and sensitive is the whole trigger (§6 T4).
+  // A local-vault-only live tier does not need a GitHub environment or copied account secrets.
   if (keys.length) {
     const ids = reviewers.map((login) => {
       const args = ["api", `users/${login}`, "--jq", ".id"];

package/src/hosts/openclaw.ts

@@ -29,7 +29,8 @@ const PER_TOOL_KEYS = new Set(["name", "version", "description"]);
  */
 function overridden(project: Project): Set<string> {
   const openclaw = project.tool.openclaw;
-  const paths = new Set<string>();
+  // The host development dependency is deliberately pinned to the recorded scaffold release.
+  const paths = new Set<string>([".devDependencies.openclaw"]);
   for (const section of ["dependencies", "peerDependencies", "devDependencies"] as const) {
     for (const key of Object.keys(openclaw?.[section] ?? {})) paths.add(`.${section}.${key}`);
   }
@@ -78,8 +79,7 @@ export function scaffoldDrift(project: Project): string[] {
   // The probe must run the exact openclaw this project pins (author override or the
   // scaffold default) - never whatever happens to be on PATH, which made the drift verdict
   // environment-dependent: the scaffold openclawVersion is the running CLI own version.
-  const pin =
-    project.tool.openclaw?.devDependencies?.openclaw ?? OPENCLAW_SCAFFOLD.devDependencies.openclaw;
+  const pin = project.tool.openclaw?.devDependencies?.openclaw ?? OPENCLAW_SCAFFOLD.openclawVersion;
   const pinned = join(project.root, HOST_DIR, "node_modules/.bin/openclaw");
   try {
     const probe = existsSync(pinned)

package/src/model.ts

@@ -131,7 +131,26 @@ export const ToolConfigSchema = z
         "JSON Schema 2020-12 object for the tool's configuration; mark secrets with x-toolfactory.sensitive.",
       ),
     tests: z
-      .object({ examples: z.record(z.string(), jsonObject).default({}) })
+      .object({
+        examples: z.record(z.string(), jsonObject).default({}),
+        live: z
+          .object({
+            credentials: z
+              .array(z.string().regex(/^[A-Z_][A-Z0-9_]*$/))
+              .min(1)
+              .optional()
+              .describe(
+                "Environment gates for live tests when auth is supplied outside tool config, such as a host vault. Names only, never values.",
+              ),
+            ci: z
+              .boolean()
+              .optional()
+              .describe(
+                "Set false for live tests that require a local vault or browser unavailable on hosted CI. The native local live-test tier is still generated.",
+              ),
+          })
+          .optional(),
+      })
       .default({ examples: {} })
       .describe("Example arguments per operation, used by the generated surface-smoke tests."),
     npm: z.object({ scope: z.string().optional() }).optional(),