@instruktlabs/kiln 1.0.0 → 1.2.0

package/scripts/workspace-transaction.mjs

@@ -0,0 +1,504 @@
+/** Recoverable setup writes. Private recovery data never enters diagnostics. */
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import {
+  chmod,
+  link,
+  lstat as nativeLstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  rmdir,
+  unlink,
+} from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+
+const active = new Set();
+const lstat = (path) => nativeLstat(path, { bigint: true });
+const maxFile = 2 * 1024 * 1024;
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+const key = (value) => (process.platform === 'win32' ? value.toLowerCase() : value);
+const inside = (parent, child) => {
+  const rel = relative(key(parent), key(child));
+  return !rel || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+};
+const equal = (a, b) => (a === undefined ? b === undefined : b !== undefined && a.equals(b));
+const maybeStat = async (path) => {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+};
+
+function safePath(value) {
+  if (
+    typeof value !== 'string' ||
+    !value ||
+    value.length > 1024 ||
+    value
+      .split('/')
+      .some(
+        (part) =>
+          !part ||
+          part === '.' ||
+          part === '..' ||
+          /[\\:*?"<>|]/.test(part) ||
+          [...part].some((character) => character.charCodeAt(0) < 32) ||
+          /[. ]$/.test(part) ||
+          /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(part) ||
+          /^\.git$/i.test(part),
+      )
+  )
+    throw new Error('Unsafe project path.');
+  return value;
+}
+
+async function inspectPath(root, name) {
+  safePath(name);
+  const rootInfo = await lstat(root);
+  if (rootInfo.isSymbolicLink()) throw new Error('Refusing symbolic link at the project root.');
+  if (!rootInfo.isDirectory()) throw new Error('Project root must remain a directory.');
+  let path = root;
+  const parts = name.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    path = join(path, parts[i]);
+    const info = await maybeStat(path);
+    if (!info) return undefined;
+    if (info.isSymbolicLink()) throw new Error(`Refusing symbolic link in project path: ${name}`);
+    if (i !== parts.length - 1 && !info.isDirectory())
+      throw new Error(`Not a directory in project path: ${name}`);
+    if (i === parts.length - 1) return info;
+  }
+}
+
+async function readSafe(root, name) {
+  const info = await inspectPath(root, name);
+  if (!info) return undefined;
+  if (!info.isFile() || info.nlink !== 1n)
+    throw new Error(`Expected a single regular file: ${name}`);
+  if (info.size > maxFile) throw new Error(`Project file exceeds setup size limit: ${name}`);
+  const handle = await open(join(root, name), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const current = await handle.stat({ bigint: true });
+    if (current.dev !== info.dev || current.ino !== info.ino || current.size > maxFile)
+      throw new Error(`Project file changed: ${name}`);
+    const data = await handle.readFile();
+    if (data.length > maxFile) throw new Error(`Project file exceeds setup size limit: ${name}`);
+    return data;
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function readProjectFile(root, name) {
+  if ((await lstat(root)).isSymbolicLink())
+    throw new Error('Refusing symbolic link at the project root.');
+  return readSafe(await realpath(root), name);
+}
+
+async function paths(root, stateDirectory) {
+  if ((await lstat(root)).isSymbolicLink())
+    throw new Error('Refusing symbolic link at the project root.');
+  root = await realpath(root);
+  const rootInfo = await lstat(root);
+  if (!rootInfo.isDirectory()) throw new Error('Project root must be a directory.');
+  const base =
+    process.platform === 'win32'
+      ? join(
+          process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'),
+          'InstruktLabs',
+          'Kiln',
+        )
+      : join(
+          process.env.XDG_DATA_HOME || join(homedir(), '.local', 'share'),
+          'instruktlabs',
+          'kiln',
+        );
+  const state = resolve(stateDirectory ?? join(base, 'setup-transactions'));
+  // A junction in any existing ancestor must not redirect private backups.
+  let current = parse(state).root;
+  for (const part of relative(current, state).split(sep).filter(Boolean)) {
+    current = join(current, part);
+    const info = await maybeStat(current);
+    if (info?.isSymbolicLink()) throw new Error('Refusing symbolic link in recovery storage.');
+    if (info && !info.isDirectory()) throw new Error('Recovery storage must be a directory.');
+  }
+  if (inside(root, state) || inside(state, root))
+    throw new Error('Recovery storage must be outside the project.');
+  const directory = join(state, digest(key(root)));
+  return { root, state, directory, rootInfo };
+}
+
+async function assertRoot(root, journal) {
+  const info = await lstat(root);
+  if (
+    !info.isDirectory() ||
+    info.isSymbolicLink() ||
+    String(info.dev) !== journal.rootDev ||
+    String(info.ino) !== journal.rootIno
+  )
+    throw new Error('Project root changed during setup.');
+}
+
+async function durableWrite(path, value, mode = 0o600) {
+  const handle = await open(path, 'wx', mode);
+  try {
+    await handle.writeFile(value);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+async function saveJournal(directory, journal) {
+  const pending = join(directory, 'journal.pending');
+  await unlink(pending).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+  });
+  await durableWrite(pending, JSON.stringify(journal));
+  await rename(pending, join(directory, 'journal.json'));
+}
+
+function bytes(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string' && !Buffer.isBuffer(value))
+    throw new Error('Setup edits require text or bytes.');
+  const result = Buffer.from(value);
+  if (result.length > maxFile) throw new Error('Setup edit exceeds size limit.');
+  return result;
+}
+
+async function ensureParents(root, name, journal, directory) {
+  const parts = name.split('/').slice(0, -1);
+  for (let i = 1; i <= parts.length; i++) {
+    const path = parts.slice(0, i).join('/');
+    const info = await inspectPath(root, path);
+    if (info) {
+      if (!info.isDirectory()) throw new Error(`Not a directory in project path: ${path}`);
+      continue;
+    }
+    await mkdir(join(root, path));
+    const created = await lstat(join(root, path));
+    journal.directories.push({ path, dev: String(created.dev), ino: String(created.ino) });
+    await saveJournal(directory, journal);
+  }
+}
+
+function stageName(journal, entry) {
+  return [
+    ...entry.path.split('/').slice(0, -1),
+    `.kiln-setup-${journal.id}-${entry.index}.tmp`,
+  ].join('/');
+}
+
+async function replaceFile(root, entry, before, after, journal, directory) {
+  await assertRoot(root, journal);
+  if (!equal(await readSafe(root, entry.path), before))
+    throw new Error(`Project file changed: ${entry.path}`);
+  if (after === undefined) {
+    await unlink(join(root, entry.path));
+    return;
+  }
+  await ensureParents(root, entry.path, journal, directory);
+  const temporary = stageName(journal, entry);
+  await inspectPath(root, temporary);
+  await durableWrite(join(root, temporary), after);
+  if (entry.mode !== undefined) await chmod(join(root, temporary), entry.mode);
+  // Recheck after staging. A new destination must not replace a concurrent arrival.
+  if (!equal(await readSafe(root, entry.path), before))
+    throw new Error(`Project file changed: ${entry.path}`);
+  if (before === undefined) {
+    await link(join(root, temporary), join(root, entry.path));
+    await unlink(join(root, temporary));
+  } else {
+    await rename(join(root, temporary), join(root, entry.path));
+  }
+}
+
+async function storedBytes(directory, entry, side) {
+  if (entry[side] === null) return undefined;
+  const value = await readSafe(directory, `${entry.index}.${side}`);
+  if (value === undefined || digest(value) !== entry[side])
+    throw new Error('Recovery data failed integrity verification.');
+  return value;
+}
+
+async function removeTemporary(root, journal, entry) {
+  const name = stageName(journal, entry);
+  const info = await inspectPath(root, name);
+  if (!info) return;
+  // Two links are possible if a process stopped between exclusive publication and unlink.
+  if (!info.isFile() || info.size > maxFile) throw new Error(`Recovery conflict at ${name}`);
+  const value = await readFile(join(root, name));
+  if (![entry.before, entry.after].includes(digest(value)))
+    throw new Error(`Recovery conflict at ${name}`);
+  await unlink(join(root, name));
+}
+
+async function cleanState(directory, journal, recovery = false) {
+  // Never recursively delete private storage.
+  const known = new Set([
+    'journal.pending',
+    'journal.json',
+    ...(recovery ? ['recovery.lock'] : []),
+  ]);
+  for (const entry of journal.entries)
+    for (const side of ['before', 'after']) known.add(`${entry.index}.${side}`);
+  if ((await readdir(directory)).some((name) => !known.has(name)))
+    throw new Error('Unexpected recovery file; private recovery data was retained.');
+  for (const entry of journal.entries) {
+    for (const side of ['before', 'after']) {
+      await unlink(join(directory, `${entry.index}.${side}`)).catch((error) => {
+        if (error.code !== 'ENOENT') throw error;
+      });
+    }
+  }
+  for (const name of ['journal.pending', 'journal.json', ...(recovery ? ['recovery.lock'] : [])]) {
+    await unlink(join(directory, name)).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+  await rmdir(directory);
+}
+
+async function rollback(root, directory, journal, recovery = false) {
+  await assertRoot(root, journal);
+  const restore = [];
+  for (const entry of journal.entries.filter((item) => item.started)) {
+    const before = await storedBytes(directory, entry, 'before');
+    const after = await storedBytes(directory, entry, 'after');
+    await removeTemporary(root, journal, entry);
+    const current = await readSafe(root, entry.path);
+    if (!equal(current, before) && !equal(current, after))
+      throw new Error(`Recovery conflict at ${entry.path}`);
+    restore.push({ entry, before, after, current });
+  }
+  // Check all target conflicts before restoring any target.
+  for (const { entry, before, after, current } of restore.reverse()) {
+    if (!equal(current, before)) await replaceFile(root, entry, after, before, journal, directory);
+  }
+  for (const created of [...journal.directories].reverse()) {
+    const info = await inspectPath(root, created.path);
+    if (!info || String(info.dev) !== created.dev || String(info.ino) !== created.ino) continue;
+    await rmdir(join(root, created.path)).catch((error) => {
+      if (!['ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error;
+    });
+  }
+  journal.phase = 'recovered';
+  await saveJournal(directory, journal);
+  await cleanState(directory, journal, recovery);
+}
+
+export async function applyProjectEdits(
+  root,
+  edits,
+  { stateDirectory, check = false, onStep } = {},
+) {
+  const location = await paths(root, stateDirectory);
+  root = location.root;
+  const { directory, state } = location;
+  if (!Array.isArray(edits) || edits.length > 1024) throw new Error('Invalid setup edit list.');
+  const names = new Set();
+  let size = 0;
+  const planned = [];
+  for (const edit of edits) {
+    const path = safePath(edit?.path).toLowerCase();
+    if (names.has(path)) throw new Error(`Duplicate setup path: ${edit.path}`);
+    names.add(path);
+  }
+  for (const path of names) {
+    const parts = path.split('/');
+    for (let i = 1; i < parts.length; i++)
+      if (names.has(parts.slice(0, i).join('/'))) throw new Error('Overlapping setup paths.');
+  }
+  for (const edit of edits) {
+    const path = safePath(edit.path);
+    const before = bytes(edit.before);
+    const after = bytes(edit.after);
+    size += (before?.length ?? 0) + (after?.length ?? 0);
+    if (size > 32 * maxFile) throw new Error('Setup transaction exceeds size limit.');
+    if (!equal(await readSafe(root, path), before))
+      throw new Error(`Project file changed: ${path}`);
+    const info = await inspectPath(root, path);
+    if (!equal(before, after))
+      planned.push({ path, before, after, mode: info ? Number(info.mode & 0o777n) : undefined });
+  }
+  planned.sort(
+    (a, b) => Number(a.path === '.kiln/workspace.json') - Number(b.path === '.kiln/workspace.json'),
+  );
+  if (await maybeStat(directory))
+    throw new Error(
+      'Project setup is locked; finish the active setup or recover the interrupted update.',
+    );
+  if (check) return { status: 'planned', paths: planned.map((entry) => entry.path) };
+  if (!planned.length) return { status: 'applied', paths: [] };
+  await mkdir(state, { recursive: true, mode: 0o700 });
+  try {
+    await mkdir(directory, { mode: 0o700 });
+  } catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Project setup is locked.');
+    throw error;
+  }
+  active.add(directory);
+  const { rootInfo } = location;
+  const journal = {
+    version: 1,
+    root,
+    rootDev: String(rootInfo.dev),
+    rootIno: String(rootInfo.ino),
+    pid: process.pid,
+    id: randomUUID(),
+    phase: 'preparing',
+    directories: [],
+    entries: [],
+  };
+  try {
+    await assertRoot(root, journal);
+    for (const [index, entry] of planned.entries()) {
+      journal.entries.push({
+        index,
+        path: entry.path,
+        mode: entry.mode,
+        before: entry.before === undefined ? null : digest(entry.before),
+        after: entry.after === undefined ? null : digest(entry.after),
+        started: false,
+      });
+      for (const side of ['before', 'after'])
+        if (entry[side] !== undefined)
+          await durableWrite(join(directory, `${index}.${side}`), entry[side]);
+    }
+    journal.phase = 'prepared';
+    await saveJournal(directory, journal);
+    await onStep?.({ phase: 'prepared' });
+    for (const [index, entry] of planned.entries()) {
+      if (!equal(await readSafe(root, entry.path), entry.before))
+        throw new Error(`Project file changed: ${entry.path}`);
+      journal.entries[index].started = true;
+      await saveJournal(directory, journal);
+      await replaceFile(
+        root,
+        journal.entries[index],
+        entry.before,
+        entry.after,
+        journal,
+        directory,
+      );
+      await onStep?.({ phase: 'written', path: entry.path });
+    }
+    journal.phase = 'committed';
+    await saveJournal(directory, journal);
+    await cleanState(directory, journal);
+    return { status: 'applied', paths: planned.map((entry) => entry.path) };
+  } catch {
+    if (journal.phase === 'committed')
+      throw new Error('Setup completed but private recovery cleanup is required.');
+    try {
+      await rollback(root, directory, journal);
+    } catch {
+      throw new Error(
+        'Setup stopped; recovery required. Existing user edits and private recovery data were retained.',
+      );
+    }
+    throw new Error('Setup stopped; previous files were restored.');
+  } finally {
+    active.delete(directory);
+  }
+}
+
+function validateJournal(journal, root) {
+  const identity = (value) => typeof value === 'string' && /^[0-9]{1,40}$/.test(value);
+  if (
+    journal?.version !== 1 ||
+    journal.root !== root ||
+    !Number.isSafeInteger(journal.pid) ||
+    journal.pid < 1 ||
+    !identity(journal.rootDev) ||
+    !identity(journal.rootIno) ||
+    !/^[a-f0-9-]{36}$/.test(journal.id) ||
+    !['prepared', 'committed', 'recovered'].includes(journal.phase) ||
+    !Array.isArray(journal.entries) ||
+    journal.entries.length > 1024 ||
+    !Array.isArray(journal.directories) ||
+    journal.directories.length > 8192
+  )
+    throw new Error('Invalid recovery journal.');
+  const names = new Set();
+  for (const [index, entry] of journal.entries.entries()) {
+    safePath(entry.path);
+    if (
+      entry.index !== index ||
+      names.has(entry.path.toLowerCase()) ||
+      typeof entry.started !== 'boolean' ||
+      (entry.mode !== undefined &&
+        (!Number.isSafeInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777)) ||
+      ![entry.before, entry.after].every(
+        (value) => value === null || (typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)),
+      )
+    )
+      throw new Error('Invalid recovery journal.');
+    names.add(entry.path.toLowerCase());
+  }
+  for (const dir of journal.directories) {
+    safePath(dir.path);
+    if (
+      !identity(dir.dev) ||
+      !identity(dir.ino) ||
+      !journal.entries.some((entry) => entry.path.startsWith(`${dir.path}/`))
+    )
+      throw new Error('Invalid recovery journal.');
+  }
+}
+
+export async function recoverProjectEdits(root, { stateDirectory } = {}) {
+  const location = await paths(root, stateDirectory);
+  const { directory } = location;
+  root = location.root;
+  if (active.has(directory)) throw new Error('Project setup is still active.');
+  const info = await maybeStat(directory);
+  if (!info) return { status: 'unchanged' };
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Invalid recovery storage.');
+  let journal;
+  try {
+    journal = JSON.parse((await readSafe(directory, 'journal.json')).toString('utf8'));
+  } catch {
+    throw new Error(
+      'Incomplete recovery journal; manual inspection is required. No project files were changed.',
+    );
+  }
+  validateJournal(journal, root);
+  await assertRoot(root, journal);
+  if (journal.pid !== process.pid) {
+    try {
+      process.kill(journal.pid, 0);
+      throw new Error('Project setup process is still active.');
+    } catch (error) {
+      if (error.code !== 'ESRCH') throw error;
+    }
+  }
+  const recoveryLock = join(directory, 'recovery.lock');
+  try {
+    await durableWrite(recoveryLock, String(process.pid));
+  } catch (error) {
+    if (error.code === 'EEXIST')
+      throw new Error('Project recovery is already active or requires manual inspection.');
+    throw error;
+  }
+  active.add(directory);
+  try {
+    if (journal.phase === 'committed' || journal.phase === 'recovered')
+      await cleanState(directory, journal, true);
+    else await rollback(root, directory, journal, true);
+    return { status: 'recovered' };
+  } finally {
+    active.delete(directory);
+    await unlink(recoveryLock).catch((error) => {
+      if (error.code !== 'ENOENT') throw error;
+    });
+  }
+}

package/skills/kiln-setup-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kiln-setup-workspace
-description: Create and verify a Kiln asset workspace for a chosen coding-agent harness. Use before authoring when the current directory is the engine repository, an empty folder, or any project without a working kiln_workspace server.
+description: Configure and verify Kiln in an existing project or a new asset workspace for the selected coding agent. Use before authoring when the project has no working kiln_workspace server or needs another agent integration; engine development stays in the engine checkout.
 license: MIT
 metadata:
   kiln-workflow: workspace
@@ -18,15 +18,18 @@ Do not author assets inside the engine checkout. The authoring skills assume a w
 
 ## Create the workspace
 
-When this skill comes from the **Kiln Engine local plugin**, its plugin root contains `runtime.json` and `scripts/setup-workspace.mjs`. Follow [plugin installation and upgrades](references/plugin-install.md) to install the pinned engine and configure a separate workspace. Do not run the checkout command below from a plugin cache. The plugin registers setup only; the workspace supplies its authoring skills and `kiln_workspace` server.
+When this skill comes from the **Kiln local plugin**, its plugin root contains `runtime.json` and `bin/kiln-setup-workspace.mjs` (plugin 1.0.0 used `scripts/setup-workspace.mjs`). Follow [plugin installation and upgrades](references/plugin-install.md) to install the pinned engine and configure a separate workspace. Do not run the checkout command below from a plugin cache. The plugin registers setup only; the workspace supplies its authoring skills and `kiln_workspace` server.
 
-Choose an absolute path to an empty directory outside the checkout.
+Choose the user's existing project or an absolute path for a new workspace outside the engine installation. Check the installed initializer's `--help`: this setup version supports `--adopt`; older engines support only empty destinations. Upgrade an older installation explicitly before adopting a populated project.
 
 ```bash
-node scripts/create-workspace.mjs /absolute/empty-workspace --harness claude
+node scripts/create-workspace.mjs /absolute/project --adopt --harness claude --check
+node scripts/create-workspace.mjs /absolute/project --adopt --harness claude
 ```
 
-From an installed package, the equivalent is `kiln-init /absolute/empty-workspace --harness claude`. Author, refine and QA skills are installed by default; `--skills compose,batch` adds the optional scene-composition and trial-dispatch workflows. Use the harness already selected by the user or current host; ask only when it is unknown. The choice writes different configuration and cannot be changed afterwards without a fresh workspace.
+From an installed package, use `kiln-init` with the same arguments. Check reports planned changes and exits 1 when changes are needed; it writes nothing. Adoption preserves existing instruction files, unrelated settings, assets and skills. Read the returned `instructions` file (`.kiln/AGENTS.md`) and `.kiln/START.md`, alongside the project's existing instructions. Conflicts stop setup before writes; do not delete or replace owner configuration to make the command pass.
+
+Author, refine and QA skills are installed by default; `--skills compose,batch` adds the optional workflows. Use the agent selected by the user or current host; ask only when it is unknown. Repeat `--adopt --harness codex` (or another supported adapter) to add that integration around the same program store. It explicitly migrates a legacy managed workspace while preserving assets. A combination whose config formats conflict is reported before changes; do not force one client's configuration into another. The plain empty-directory setup command remains compatible with older workflows.
 
 CLI/MCP workspaces use the shared skills under `skills/`. Kiln's optional built-in Strands agent adds its workflow internally, outside that directory. Do not copy its system prompt, native workflow skill or completion protocol into another harness's skills or instructions. This applies to manual setup and plugin installs too; the engine's `src/agent/` directory is not a skill source.
 
@@ -37,24 +40,18 @@ CLI/MCP workspaces use the shared skills under `skills/`. Kiln's optional built-
 | `cursor-agent` | `cursor-agent` |
 | `opencode` | `opencode` |
 | `agy` | `node agy.mjs` |
-| `codex` | `node codex.mjs` |
+| `codex` | `codex` after project trust; `node codex.mjs "TASK"` for a headless run |
 | `hermes` | `node hermes.mjs` |
 
-**Use the launcher where the table names one, and read the workspace's own START.md over this table.** Antigravity, Codex and Hermes keep all configuration in a user-level home and read nothing from a project directory, so their workspace configuration is applied per invocation by the generated launcher. Running their bare command inside the workspace reaches no Kiln tools at all. None of the three writes outside the workspace, and none touches the user's existing configuration or authentication.
+Read `.kiln/START.md` for an adopted project, or `START.md` in a legacy workspace. Codex reads trusted project configuration from `.codex/config.toml`; its optional headless launcher supplies the same settings per invocation without relocating authentication. Antigravity and Hermes use their generated launchers for the measured workspace flow. Setup does not grant project trust or edit global credentials. Skill registration is client-specific: Claude uses `.claude/skills`, Codex uses `.agents/skills`, and OpenCode uses its configured skills path, all copied from the same maintained Kiln skills.
 
 Hermes needs one user-level registration for the MCP server, because it has no project-scoped equivalent and no per-invocation flag for one. Its START.md prints the exact `hermes mcp add` command; offer to run it, and verify with `hermes mcp list`. Never redirect `HERMES_HOME` at the workspace: that one variable resolves the configuration path and the credential path together, so pointing it at a workspace leaves the run with no provider.
 
-## Start the GPU render service
-
-Setup asks for render mode `auto`: textured or metallic scenes use a compatible GPU service, starting one lazily when available. Ordinary untextured scenes with zero metalness and no advanced material extensions use CPU views, even with a GPU available. CPU views support silhouette, proportion and contact review, but cannot confirm PBR appearance. Use CLI `--render gpu` when material review is required, including roughness on nonmetallic surfaces.
-
-The renderer code is included with Kiln; its native GPU dependency is optional at the Kiln package root. For material-dependent tasks, check `node kiln.mjs service status` before starting the authoring session. If dependencies are missing or incompatible, reinstall the official Kiln package with optional dependencies enabled. npm 11 may print an `install-scripts` warning for the optional `webgpu` package; its postinstall only clears the macOS download quarantine from the prebuilt Dawn binary the package ships, so Windows and Linux need nothing and the warning is not an install failure. Read `runtime` from `.kiln/workspace.json` to identify the installation. A source checkout uses `bun install --frozen-lockfile` at that root. Setup checks dependency resolution without loading native code; ready dependencies alone do not prove the device can render.
+## Check rendering readiness
 
-Once dependencies are available, local CLI/MCP auto mode starts a managed service lazily for a view that needs PBR shading. Compatible clients share it; it survives the initiating session and exits after five minutes without admitted uploads, queued jobs or active renders. From the installation root, `node --import ./render-service/src/register-hooks.mjs render-service/src/server.mjs` starts a manual service that remains running while idle. It binds loopback; widening `HOST` requires `RENDER_SERVICE_TOKEN`.
+Setup selects render mode `auto`. Textured or metallic scenes use a compatible render service; plain scenes use CPU geometry views. CPU views cannot confirm PBR appearance. Check `node kiln.mjs service status` before material-dependent work and require a real `viewFidelity` result before claiming material evidence.
 
-`node kiln.mjs service status` reports installation, verified health and lifetime. `node kiln.mjs service start` joins a compatible service or starts a managed one the way an on-demand view does, and prints its port, renderer, pid, lifetime and build; it starts nothing when a stale, foreign or unknown listener holds the socket. After dependency repair or a cached startup failure, call `kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its existing route. It neither installs dependencies nor starts a renderer; the next view starts one if needed. CLI `service reprobe` checks only its own process. Restart the session after changing Kiln, environment variables or credentials. Unknown or incompatible listeners are reported and left alone. `service stop` explicitly stops a verified local service. If no usable GPU is available, report the material-review limitation and continue on CPU views when that fits the task.
-
-A `KILN_RENDER_PORT_URL` whose origin is exactly the shared local socket (`http://127.0.0.1:8000` by default) takes the local route: it starts on demand and restarts after an idle exit. For rendering on another device, configure the MCP server process's `KILN_RENDER_PORT_URL` and, when needed, `KILN_RENDER_TOKEN` through the chosen harness. CLI accepts `--render-port URL` and reads `KILN_RENDER_TOKEN`. Start a compatible Kiln renderer on that device; its wider bind requires `RENDER_SERVICE_TOKEN` unless an authenticated proxy is explicitly configured. Manage the remote service on its own device. Verify the selected route with capabilities and require an actual `viewFidelity` receipt for material evidence.
+Read [local renderer setup](references/renderer-setup.md) when dependencies are missing, a service is unavailable, or the task uses a renderer on another device. It covers dependency repair, shared-service lifetime, reprobe and authenticated remote rendering. Do not replace an unknown listener or install dependencies merely to clear a diagnostic.
 
 ## Verify the loadout before authoring
 
@@ -97,7 +94,9 @@ node /current/kiln/scripts/create-workspace.mjs /absolute/empty-workspace --repa
 
 Repair rewrites generated runtime paths only. It preserves copied skills, saved revisions and assets, refuses configuration that was edited by hand, and does not upgrade the skills.
 
-For an existing workspace, stop its harness/MCP session and run setup from the desired installation with `--check`, then `--upgrade`. Check returns JSON and exits 1 when an update is required. Upgrade refreshes unchanged configuration, instructions and all registered skill copies while preserving assets and source stores. Conflicting local edits stop the whole upgrade before writing. Older instruction files without ownership hashes also require explicit resolution: preserve them separately, compare against a fresh temporary workspace, then move them aside or supply the current version before retrying. Reapply compatible customizations after upgrading. Do not overwrite an edited file merely to clear a conflict.
+For an existing workspace, stop its harness/MCP session and run setup from the desired installation with `--check`, then `--upgrade`. Check returns JSON and exits 1 when an update is required. Upgrade refreshes unchanged owned configuration, instructions and registered skill copies while preserving assets and source stores. Conflicting local edits stop the whole upgrade before writing. Adopted projects preserve unrelated configuration changes and leave pre-existing instruction files alone. Legacy instruction files without ownership hashes can require explicit resolution; preserve them before resolving the named conflict. Do not overwrite an edited file merely to clear a diagnostic.
+
+If adopted-project setup stops partway through writing, it attempts rollback. When it reports recovery required, preserve the project and run `kiln-init /absolute/project --recover` after confirming setup has stopped. Recovery refuses conflicting edits and retains its private snapshots outside the project. Resolve named conflicts explicitly; do not delete a lock or journal to force another setup. Recovery is for interrupted setup, not a general asset backup.
 
 New managed launchers reject runtime/skill mismatches before serving tools; older workspaces need this explicit check first. Restart the harness/MCP session after upgrading so cached tool schemas and instructions match. `--repair` alone does not refresh copied skills or a running session. For independent model evaluations, create a fresh workspace from the candidate.
 
@@ -105,4 +104,4 @@ Discovery replaces the removed `kiln_list_primitives` tool; its old `name`, `nam
 
 ## What isolation means
 
-A separate workspace limits task context. It is not an operating-system sandbox, and it is not a git repository. User-level instructions, memory, authentication and filesystem permissions still apply. For comparing harnesses or models, read `skills/kiln-batch-dispatch/references/clean-room-evaluation.md` in the engine checkout, which covers recording inherited context and reporting trials.
+A separate workspace limits task context; an adopted project retains its existing application context and Git repository. Neither is an operating-system sandbox. User-level instructions, memory, authentication and filesystem permissions still apply. For comparing harnesses or models, use a fresh workspace and read `skills/kiln-batch-dispatch/references/clean-room-evaluation.md`, which covers inherited context and reporting trials.

package/skills/kiln-setup-workspace/references/plugin-install.md

@@ -4,19 +4,27 @@ The local `kiln-engine` plugin installs Kiln's exact pinned npm version and crea
 an asset workspace. It carries setup guidance and a small installer; the engine,
 source stores and authored assets live outside the plugin cache. It needs a
 supported Node.js installation with npm, network access for first installation,
-and no separate model API key.
+and no separate model API key. Use it in Claude Code or Codex; it requires a local
+shell and persistent filesystem and is not a Claude chat or Cowork plugin.
 
 Resolve the plugin root from this installed skill's absolute path: it is two
 directories above `skills/kiln-setup-workspace`. Confirm `runtime.json` and
-`scripts/setup-workspace.mjs` exist there. Do not assume plugin path variables are
+`bin/kiln-setup-workspace.mjs` exist there. Do not assume plugin path variables are
 available in an ordinary shell, and do not substitute an engine checkout.
 
+Plugin version 1.0.0 used `scripts/setup-workspace.mjs`; if using that older
+installation, confirm and use that file instead. Plugin and engine versions are
+independent. `runtime.json` always names the exact engine to install.
+
 For a fresh workspace, use an absolute empty destination outside both the plugin
-and its runtime data directory. Select `claude` or `codex` from the current host
-or the user's stated choice:
+and its runtime data directory. Select the current host or the user's stated
+adapter. New bundles list the engine's supported adapters in `runtime.json`;
+older bundles without that list accept `claude` or `codex` only. The plugin itself
+is installed in Claude Code or Codex, but its helper can configure another adapter
+supported by the pinned engine:
 
 ```sh
-node "/absolute/plugin/scripts/setup-workspace.mjs" "/absolute/my-assets" --harness codex
+node "/absolute/plugin/bin/kiln-setup-workspace.mjs" "/absolute/my-assets" --harness codex
 ```
 
 The installer verifies the package name and exact version from `runtime.json`.
@@ -27,11 +35,23 @@ or `$XDG_DATA_HOME/instruktlabs/kiln` on other systems, falling back to
 Do not place it or the asset workspace inside a removable plugin version directory.
 
 Read the returned workspace's `START.md`. Open Claude Code in that workspace, or
-launch Codex there with `node codex.mjs`. Accept the host's ordinary project/MCP
+launch Codex there with `codex`. The `node codex.mjs "TASK"` launcher is for
+headless execution with an explicit prompt. Accept the host's ordinary project/MCP
 trust prompts, then call `kiln_discover({capabilities:true})` on `kiln_workspace`.
 Compare its installation identity to `.kiln/workspace.json`; a config file alone
 does not prove the server loaded. The plugin itself starts no global MCP server.
 
+For an existing project, use a plugin whose helper advertises `--adopt` and whose
+pinned engine supports project adoption. The published engine 1.0.0 predates this
+feature. The helper checks the engine capability and refuses unsupported adoption
+instead of silently falling back to empty-folder setup. Preview with
+`--adopt --check --harness codex`, then apply with `--adopt --harness codex`.
+Use the same path with another `--harness` to add an integration around the same
+assets. Read the returned `instructions` path and `.kiln/START.md`; existing project
+instruction files remain intact. The helper still leaves normal client trust
+prompts to the host. No manual changes to a plugin's runtime pin are needed or
+appropriate.
+
 If the current workspace already has a working `kiln_workspace`, keep it. Do not
 create a second server. Use its installed authoring skills, which come from its
 engine version. The plugin supplies only setup, so authoring instructions are not
@@ -43,8 +63,8 @@ For an existing managed workspace, stop its harness session and run the new
 plugin's helper with `--check`, then `--upgrade` when an update is intended:
 
 ```sh
-node "/absolute/plugin/scripts/setup-workspace.mjs" "/absolute/my-assets" --check
-node "/absolute/plugin/scripts/setup-workspace.mjs" "/absolute/my-assets" --upgrade
+node "/absolute/plugin/bin/kiln-setup-workspace.mjs" "/absolute/my-assets" --check
+node "/absolute/plugin/bin/kiln-setup-workspace.mjs" "/absolute/my-assets" --upgrade
 ```
 
 Check is read-only and reports a missing pinned engine without installing it.