omkit 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -46,6 +46,47 @@
 
 ### Fixed
 
+- **`typescript` moved from `devDependencies` to `dependencies`.** Three shipped modules import
+  it at runtime, and one of them — discovery — runs on every command, so an install that did not
+  already happen to have TypeScript nearby failed with `ERR_MODULE_NOT_FOUND` on `omkit ls`. It
+  went unnoticed because a monorepo hoists it into place.
+- **A node's log file no longer spells its name out as directories.** A node's id is
+  `<name>_<shortId>`, ids are joined with `/` into node paths, and those paths become log file
+  paths — so a name carrying its own separators was read as tree nesting. A `command` node is
+  named after its whole command line, and one watcher's log ended up nine directories deep, with
+  `docs`, `packages` and `tskb` as real folders inside the run. Names are now sanitised where the
+  id is made, which is the only place the two kinds of separator are still distinguishable, and
+  the name's contribution to an id is capped so a long command line cannot push a log path past
+  Windows' 260-character limit. Displayed names are untouched: nodes are shown by name, never by
+  id.
+
+- **One project, one `logs/` tree.** A run's record now lands under the project that owns the
+  config, wherever the run was started from. It used to follow the working directory, and the
+  frontends chose different ones: `omkit run` set it to the om file's own directory, so a project
+  with oms in several folders accumulated a `logs/` beside each of them, while the MCP server used
+  the directory it happened to be launched in — with the result that a run started in the terminal
+  and a run started by an assistant wrote to two different trees, and neither could read the
+  other's record. The child's cwd is unchanged, so relative paths inside an om body still resolve
+  where their author reads them. Folder _names_ are unchanged; only their parent moves, so records
+  written before this land in the old location and stay readable there.
+- **A generated skill now documents commands that work.** `omkit skill` was given a config path and
+  dropped it from everything it wrote, so a project whose om files live in a subfolder got a file
+  whose every command failed at the root the file itself is read from. The `--tsconfig` the project
+  needs is now carried into each rendered command, including the `claude mcp add` line, and the run
+  folder is spelled from the root rather than as a bare `logs/`.
+- **An om name with a space is quoted** in the commands the skill writes. Names are free text, and
+  `omkit run DTF Tests` resolves the target as `DTF` and leaves `Tests` as a stray positional.
+- **The shell example is one that can actually be run.** It was whichever om sorted first, which for
+  one real project was a long-lived one — an example that hangs, two paragraphs above the heading
+  saying it never finishes. A settling om is preferred; when a project has none, the example says so
+  on the line itself.
+- **The `OMKIT_ARGS` example is built from the schema** instead of by pattern-matching the rendered
+  type sketch. The old reading recognised `{ field: type` and nothing else, so an om whose first
+  field was an enum silently produced `OMKIT_ARGS='{}'` — syntactically fine, and wrong about the
+  project. Examples now carry every required field (or one optional field when nothing is required),
+  take an enum's first member and a declared default where there is one, and are omitted entirely
+  when no complete example can be built.
+
 - **Two spellings of one path no longer mean two different things** (Windows). A
   case-insensitive filesystem let `d:\repo\om.ts` and `D:\repo\om.ts` name the same file, and
   omkit keyed on the string twice. Node caches ES modules by URL, so a child forked with one
@@ -59,6 +100,14 @@
 
 ### Changed
 
+- **`omkit skill --root` now defaults to the enclosing repository**, not to the tsconfig's own
+  directory. The root decides where `.claude/` goes and what the recorded paths are relative to,
+  and a skill file is read with the repository as the working directory — so the old default was
+  wrong for exactly the layout (`om/` beside the code it drives) that needed it, and had to be
+  corrected with a second flag. `--root` remains, for a project deliberately not at the top of its
+  checkout.
+- `RunOptions.env` now carries `OMKIT_ROOT` by default — the project owning the client's config.
+  A caller may still set its own; the MCP server does, naming the root it serves resources from.
 - `DiscoveredOm` gained `calls`, so `omkit ls --json` carries the outline. Additive, and derived
   statically, so `discover()` is still the pass that never executes user code.
 - The generated `description` in the skill's frontmatter is preserved across regeneration. It is

package/README.md

@@ -192,7 +192,7 @@ Every action's output, events, asserts, snapshots, and lifecycle land on **one t
 
 `ctx` also gives each action `assert(cond, msg)` (tallies into the run's verdict), `snapshot(name, value)` (captures JSON state to the run folder), and `artifact(name, file, opts?)` (labels a file the action wrote — name, optional description, MIME inferred from the extension — and returns its absolute path) — so a run is an inspectable artifact, not just an exit code. Write the files you label under `ctx.artifactsFolder`, the run's own output folder.
 
-Run folders have a **stable identity**: `logs/<name>-<hash8>/<date>/<time>/`, keyed by the om's name and the file that defines it. An assistant (or a script) can always find "the latest `tskb-dev` run" without parsing scrollback, diff two runs of the same pipeline, or answer questions with evidence instead of inference: _did the server actually pass its healthcheck? which process died first? what config did the build run with?_ It's all in the folder — attributed per action, timestamped, with a verdict.
+Run folders have a **stable identity**: `logs/<name>-<hash8>/<date>/<time>/`, keyed by the om's name and the file that defines it, under the project that owns the config — not under whichever directory the run happened to start in. An assistant (or a script) can always find "the latest `tskb-dev` run" without parsing scrollback, diff two runs of the same pipeline, or answer questions with evidence instead of inference: _did the server actually pass its healthcheck? which process died first? what config did the build run with?_ It's all in the folder — attributed per action, timestamped, with a verdict.
 
 ### Observing the real world, not assuming it
 
@@ -341,7 +341,7 @@ Point your client at the project:
 }
 ```
 
-The server takes its **project root from the working directory your client launches it in**, and resolves `logs/` under that root — so runs it starts are the runs its resources can serve. If your config lives at the repo root but the om project sits in a subfolder, point at the config explicitly rather than relying on a `cwd` field your client may not support: `["--no", "--", "omkit", "mcp", "--tsconfig", "om/tsconfig.omkit.json"]`.
+The server takes its **project root from the config it was given** — the directory holding your `tsconfig.omkit.json` — and resolves `logs/` under it, so the runs it starts are the runs its resources can serve regardless of which directory your client launched it in. `omkit run` uses the same root, so a run you start in the terminal and a run an assistant starts land in one tree and each can read the other's record. If the om project sits in a subfolder, name the config rather than relying on a `cwd` field your client may not support: `["--no", "--", "omkit", "mcp", "--tsconfig", "om/tsconfig.omkit.json"]`.
 
 ### Inspecting it
 

package/dist/cli/commands/help.js

@@ -24,7 +24,8 @@ export function helpText() {
         "  --describe          import the oms to show their summaries (ls) — slower, runs no workflow",
         "  --check             report drift and exit non-zero instead of writing (skill)",
         "  --out <path>        write somewhere else (skill)",
-        "  --root <path>       the project the skill describes, if the tsconfig sits below it (skill)",
+        "  --root <path>       where the skill is written and what its paths are relative to (skill)",
+        "                      — defaults to the enclosing repository",
         "  --inspect[=port]    run the om in a forked child with the Node inspector open (default port 9229)",
         "  -h, --help          show this help",
         "",

package/dist/cli/commands/skill.d.ts

@@ -1,4 +1,5 @@
 import type { OmkitClient } from "../../client/index.ts";
+export { skillRoot } from "../../skill/index.ts";
 export interface SkillOptions {
     /** Project root the skill is written relative to — the directory owning the tsconfig. */
     readonly root: string;

package/dist/cli/commands/skill.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { buildSkillModel, readExisting, renderSkill, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH, } from "../../skill/index.js";
+export { skillRoot } from "../../skill/index.js";
 const EMPTY_REGISTRY = { oms: [], actions: [], warnings: [] };
 /**
  * The `skill` command: generate `.claude/skills/omkit-runs/SKILL.md` from what this project's
@@ -11,7 +12,12 @@ const EMPTY_REGISTRY = { oms: [], actions: [], warnings: [] };
 export async function skillCommand(client, opts) {
     const file = path.resolve(opts.root, opts.out ?? SKILL_RELATIVE_PATH);
     const registrations = await client.discoverRegistrations();
-    const model = buildSkillModel(registrations, registrations.registry ?? EMPTY_REGISTRY, opts.root);
+    // The client's tsconfig is the one discovery actually ran against, so the commands the file
+    // renders are the commands that produced it — not a guess at what the reader should type.
+    const model = buildSkillModel(registrations, registrations.registry ?? EMPTY_REGISTRY, {
+        root: opts.root,
+        tsconfig: path.resolve(client.tsconfig),
+    });
     const existing = readExisting(file);
     if (opts.check) {
         reportCheck(file, existing.hash, model.hash);

package/dist/cli/index.d.ts

@@ -13,7 +13,7 @@ export interface Cli {
     check: boolean;
     /** `skill --out <path>`: write somewhere other than `.claude/skills/omkit-runs/SKILL.md`. */
     out?: string;
-    /** `skill --root <path>`: the project the skill describes, when the tsconfig sits below it. */
+    /** `skill --root <path>`: override the repository the skill is written for and relative to. */
     root?: string;
     /** The Node inspector, if requested via `--inspect[=port]`. */
     inspect?: InspectOptions;

package/dist/cli/index.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 import { createOmkitClient } from "../client/index.js";
+import { DEFAULT_TSCONFIG } from "../client/types.js";
 /**
  * Pull the Node-style inspector flag out of argv, returning the options plus the remaining args.
  * Matches Node's own syntax: `--inspect`, `--inspect=PORT` (default port 9229); an explicit port
@@ -31,7 +32,7 @@ export function parseCli(argv) {
         args: rest,
         options: {
             json: { type: "boolean", default: false },
-            tsconfig: { type: "string", default: "tsconfig.omkit.json" },
+            tsconfig: { type: "string", default: DEFAULT_TSCONFIG },
             help: { type: "boolean", short: "h", default: false },
             describe: { type: "boolean", default: false },
             check: { type: "boolean", default: false },
@@ -100,12 +101,14 @@ async function initCommand() {
 }
 /** The `skill` command: generate the runnable-workflow map for an assistant to read. */
 async function generateSkill(client, cli) {
-    const { skillCommand } = await import("./commands/skill.js");
+    const { skillCommand, skillRoot } = await import("./commands/skill.js");
     // The root decides two things at once — where `.claude/` goes, and what the recorded paths are
-    // relative to — so it is one setting, not two. It defaults to the tsconfig's directory (the
-    // common layout, where they are the same place); `--root` covers the repo that keeps its om
-    // project in a subfolder, where the reader's cwd is the repo and so the paths must be too.
-    const root = cli.root ? path.resolve(cli.root) : path.dirname(path.resolve(cli.tsconfig));
+    // relative to — so it is one setting, not two. It defaults to the enclosing repository, which
+    // is both where `.claude/` belongs and where the file's reader will be standing; `--root`
+    // remains for the project that is deliberately not at the top of its checkout.
+    const root = cli.root
+        ? path.resolve(cli.root)
+        : skillRoot(path.dirname(path.resolve(cli.tsconfig)));
     await skillCommand(client, { root, check: cli.check, ...(cli.out ? { out: cli.out } : {}) });
 }
 /**
@@ -116,9 +119,12 @@ const COMMANDS = {
     init: () => initCommand(),
     ls: (client, cli) => lsCommand(client, cli),
     check: (client) => checkCommand(client),
-    mcp: async (client) => {
+    mcp: async (client, cli) => {
         const { mcpCommand } = await import("./commands/mcp.js");
-        await mcpCommand(client, { root: process.cwd() });
+        // The project owning the config, not the directory the server was launched from: run
+        // folders are written under it, so reading them back has to use the same answer. An
+        // assistant that starts the server from anywhere still sees the project's own runs.
+        await mcpCommand(client, { root: path.dirname(path.resolve(cli.tsconfig)) });
     },
     skill: (client, cli) => generateSkill(client, cli),
     run: async (client, cli) => {

package/dist/client/index.js

@@ -1,20 +1,28 @@
+import path from "node:path";
 import { discover, discoverRegistrations } from "./discovery.js";
 import { runOm, spawnBare } from "./runner.js";
 import { runCheck } from "./check.js";
 export { readRegistrations, discoverRegistrations } from "./discovery.js";
 /** Build the headless engine: discovery + supervised/bare run + typecheck over one config. */
 export function createOmkitClient(config) {
-    // A per-call inspect wins; the client's construction-time inspect is the fallback.
-    const withInspect = (opts) => ({
+    // The project every run of this client belongs to: the directory owning the config it was
+    // built from. Injected here rather than at each frontend because "which project is this?" has
+    // one answer per client, and three call sites remembering it separately is how the terminal
+    // and the MCP server ended up writing their run folders to two different trees.
+    const root = path.dirname(path.resolve(config.tsconfig));
+    // A per-call inspect wins; the client's construction-time inspect is the fallback. Likewise
+    // a caller may name its own root — the injected one is a default, not an override.
+    const withDefaults = (opts) => ({
         ...opts,
         inspect: opts?.inspect ?? config.inspect,
+        env: { OMKIT_ROOT: root, ...opts?.env },
     });
     return {
         tsconfig: config.tsconfig,
         discover: async () => discover(config.tsconfig),
         discoverRegistrations: async () => discoverRegistrations(config.tsconfig),
-        run: (omFile, opts) => runOm(omFile, withInspect(opts)),
-        runBare: (omFile, opts) => spawnBare(omFile, withInspect(opts)),
+        run: (omFile, opts) => runOm(omFile, withDefaults(opts)),
+        runBare: (omFile, opts) => spawnBare(omFile, withDefaults(opts)),
         check: async () => runCheck(config.tsconfig),
     };
 }

package/dist/client/types.d.ts

@@ -1,6 +1,11 @@
 import type { LogEntry } from "../foundation/LogEntry.ts";
 import type { PromptSpec } from "../core/interaction.ts";
 import type { Registry, RegistrationSet } from "./registry.ts";
+/**
+ * The config file omkit looks for when nobody names one — resolved against the working
+ * directory, which is why anything generated for a reader elsewhere has to say so explicitly.
+ */
+export declare const DEFAULT_TSCONFIG = "tsconfig.omkit.json";
 /** A run's terminal verdict, resolved when the child settles. */
 export interface Verdict {
     readonly ok: boolean;

package/dist/client/types.js

@@ -1 +1,5 @@
-export {};
+/**
+ * The config file omkit looks for when nobody names one — resolved against the working
+ * directory, which is why anything generated for a reader elsewhere has to say so explicitly.
+ */
+export const DEFAULT_TSCONFIG = "tsconfig.omkit.json";

package/dist/core/ExecutionTree.d.ts

@@ -124,8 +124,14 @@ export declare class ExecutionTree {
     private curatedArtifacts;
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
-     * prefix. Each id segment is sanitized so names with filesystem-illegal characters
-     * (e.g. `TSKB:root:watch:docs`) still produce a valid path.
+     * prefix. One directory level per ancestor, mirroring the tree.
+     *
+     * Every `/` here is a level, and that holds only because ids are sanitised where they are
+     * made (see `makeId`): a name that carried its own separators would be split here into
+     * levels it never had, and the run folder would grow directories spelling out a command's
+     * arguments. `fsSafe` stays as the second line of defence for anything that reaches a
+     * segment by another route; it cannot be the first, since by this point a separator from a
+     * name and a separator from the tree are the same character.
      */
     private logFile;
     private rawStreamPath;

package/dist/core/ExecutionTree.js

@@ -418,8 +418,14 @@ export class ExecutionTree {
     }
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
-     * prefix. Each id segment is sanitized so names with filesystem-illegal characters
-     * (e.g. `TSKB:root:watch:docs`) still produce a valid path.
+     * prefix. One directory level per ancestor, mirroring the tree.
+     *
+     * Every `/` here is a level, and that holds only because ids are sanitised where they are
+     * made (see `makeId`): a name that carried its own separators would be split here into
+     * levels it never had, and the run folder would grow directories spelling out a command's
+     * arguments. `fsSafe` stays as the second line of defence for anything that reaches a
+     * segment by another route; it cannot be the first, since by this point a separator from a
+     * name and a separator from the tree are the same character.
      */
     logFile(nodePath) {
         const rel = nodePath === "main" ? "main" : nodePath.slice("main/".length);

package/dist/foundation/ids.d.ts

@@ -5,6 +5,18 @@ export declare const shortId: (uuid: string) => string;
 /**
  * A node's id: `${name}_${shortId}` → `chromePage_9f3c`. The root passes its own
  * plain name (`main`) and skips this.
+ *
+ * The name is sanitised **here**, at the point the id is made, because an id is a path
+ * segment everywhere it is used: node paths join ids with `/`, and log file names are those
+ * paths mapped onto directories. A name carrying its own separators — `command("npx tsk
+ * ./docs/**\/*.tsx …")` is an ordinary one — is then indistinguishable from tree nesting, and
+ * one action's log went nine directories deep, spelling out the command's path arguments as
+ * real folders. Sanitising downstream cannot fix that: by the time a joined path is split
+ * back into segments, the separator that came from a name and the one that came from the tree
+ * are the same character.
+ *
+ * Uniqueness never depended on the name — that is the uuid's job — so truncating is safe and
+ * the readable form survives anyway: nodes are displayed by their `name`, not by their id.
  */
 export declare const makeId: (name: string, uuid: string) => string;
 /**

package/dist/foundation/ids.js

@@ -1,13 +1,34 @@
 import { createHash, randomUUID } from "node:crypto";
+import { fsSafe } from "./fsSafe.js";
 /** A fresh v4 uuid for a node. */
 export const newUuid = () => randomUUID();
 /** The short form used in ids/paths — first 8 hex of the uuid. */
 export const shortId = (uuid) => uuid.slice(0, 8);
+/**
+ * How much of a name an id keeps. A node's name is free text and can be long — a `command`
+ * node is named after its whole command line — while the id it seeds ends up inside a file
+ * path, where Windows still stops at 260 characters for the whole path.
+ */
+const MAX_NAME_IN_ID = 64;
 /**
  * A node's id: `${name}_${shortId}` → `chromePage_9f3c`. The root passes its own
  * plain name (`main`) and skips this.
+ *
+ * The name is sanitised **here**, at the point the id is made, because an id is a path
+ * segment everywhere it is used: node paths join ids with `/`, and log file names are those
+ * paths mapped onto directories. A name carrying its own separators — `command("npx tsk
+ * ./docs/**\/*.tsx …")` is an ordinary one — is then indistinguishable from tree nesting, and
+ * one action's log went nine directories deep, spelling out the command's path arguments as
+ * real folders. Sanitising downstream cannot fix that: by the time a joined path is split
+ * back into segments, the separator that came from a name and the one that came from the tree
+ * are the same character.
+ *
+ * Uniqueness never depended on the name — that is the uuid's job — so truncating is safe and
+ * the readable form survives anyway: nodes are displayed by their `name`, not by their id.
  */
-export const makeId = (name, uuid) => `${name}_${shortId(uuid)}`;
+export const makeId = (name, uuid) => `${clip(fsSafe(name))}_${shortId(uuid)}`;
+/** Trim to the cap, then drop any separator the cut left dangling. */
+const clip = (name) => name.slice(0, MAX_NAME_IN_ID).replace(/[-_.]+$/, "");
 /**
  * A run's stable identity: first 8 hex of sha256 over the defining file's absolute
  * path + the om name. Same file + name ⇒ same hash on every run; the same name

package/dist/mcp/tools.js

@@ -158,24 +158,28 @@ export function registerTools(server, ctx) {
     /**
      * Launch an entry as a supervised run.
      *
-     * cwd is the project **root**, not the om file's directory. `omkit run` uses the file's
-     * directory, but resources here resolve under `<root>/logs` — a run launched elsewhere
-     * writes its folder somewhere this same server cannot serve, so `get_run`'s resource
-     * links would point at nothing.
+     * `OMKIT_ROOT` is this server's own root, stated rather than inherited: resources here
+     * resolve under `<root>/logs`, so a run that writes its folder anywhere else is a run this
+     * same server cannot serve, and `get_run`'s resource links would point at nothing. The
+     * client would default it to the project owning the tsconfig — the same directory in
+     * practice — but "the server serves what it writes" should not rest on the two agreeing.
      */
     const launch = (entry, args) => {
         // An action cannot run standalone, so an action-backed tool forks omkit's shipped host
         // om instead of the action's own file — which defines no om at all.
         const isAction = entry.kind === "action";
         const file = isAction ? hostFile() : entry.file;
-        const env = isAction
-            ? {
-                OMKIT_ACTION_FILE: entry.file,
-                OMKIT_ACTION_NAME: entry.name,
-                OMKIT_ACTION_EXPORT: entry.exportName,
-                OMKIT_ACTION_ARGS: JSON.stringify(args),
-            }
-            : { OMKIT_ARGS: JSON.stringify(args) };
+        const env = {
+            OMKIT_ROOT: ctx.root,
+            ...(isAction
+                ? {
+                    OMKIT_ACTION_FILE: entry.file,
+                    OMKIT_ACTION_NAME: entry.name,
+                    OMKIT_ACTION_EXPORT: entry.exportName,
+                    OMKIT_ACTION_ARGS: JSON.stringify(args),
+                }
+                : { OMKIT_ARGS: JSON.stringify(args) }),
+        };
         const folderName = isAction
             ? hostFolderName(entry.name, entry.file)
             : (entry.folderName ?? entry.name);

package/dist/output/folder/RunFolder.js

@@ -5,6 +5,21 @@ import { fsSafe } from "../../foundation/fsSafe.js";
 import { newUuid, shortId } from "../../foundation/ids.js";
 /** Suffixed attempts (`-02` … `-99`) before falling back to a random, certainly-unique one. */
 const MAX_NUMBERED_ATTEMPTS = 99;
+/**
+ * Where `logs/` goes: the project root a frontend named, or the working directory when nobody
+ * named one.
+ *
+ * A run's cwd is not a statement about which project it belongs to — `omkit run` sets it to the
+ * om file's own directory so relative paths in a body resolve the way their author reads them,
+ * which meant one project scattered its records across every folder that happened to contain an
+ * om, while the MCP server wrote them wherever the server was started. Two names for one thing.
+ * The root is passed explicitly and separately so the record's location is a property of the
+ * project, and the cwd stays free to mean what it already meant.
+ */
+function logsRoot() {
+    const root = process.env.OMKIT_ROOT;
+    return root ? path.resolve(root, "logs") : path.resolve("logs");
+}
 /**
  * Owns this run's single output directory — `logs/<name>-<hash>/<date>/<time>/` —
  * where `raw.jsonl`, the per-action `.log` files, rollups, and `result.json` all
@@ -61,7 +76,7 @@ export class RunFolder {
      */
     claim() {
         const now = new Date();
-        const parent = path.resolve("logs", this.name(), ymd(now));
+        const parent = path.resolve(logsRoot(), this.name(), ymd(now));
         mkdirSync(parent, { recursive: true });
         const base = hms(now, "-");
         for (let attempt = 0; attempt <= MAX_NUMBERED_ATTEMPTS; attempt += 1) {

package/dist/skill/index.d.ts

@@ -5,7 +5,8 @@
  * take data and return data, which is what makes determinism testable without touching a disk.
  */
 export { buildSkillModel, registryHash } from "./model.ts";
-export type { SkillCall, SkillEntry, SkillModel } from "./model.ts";
+export type { SkillCall, SkillEntry, SkillModel, SkillProject } from "./model.ts";
+export { skillRoot } from "./root.ts";
 export { renderSkill, generatedBy, SKILL_NAME } from "./render.ts";
 export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.ts";
 export type { ExistingSkill } from "./file.ts";

package/dist/skill/index.js

@@ -5,5 +5,6 @@
  * take data and return data, which is what makes determinism testable without touching a disk.
  */
 export { buildSkillModel, registryHash } from "./model.js";
+export { skillRoot } from "./root.js";
 export { renderSkill, generatedBy, SKILL_NAME } from "./render.js";
 export { readExisting, writeSkill, DEFAULT_DESCRIPTION, SKILL_RELATIVE_PATH } from "./file.js";

package/dist/skill/model.d.ts

@@ -16,6 +16,8 @@ export interface SkillEntry {
     readonly argHint?: string;
     /** The raw schema, present only when `shapeHint` could not sketch it (per C7). */
     readonly argSchema?: JsonSchema;
+    /** A concrete, complete `OMKIT_ARGS` value. Absent when no honest one can be built. */
+    readonly argExample?: Record<string, unknown>;
     /** The static outline of the body. Absent when the walk found nothing recognisable. */
     readonly calls?: readonly SkillCall[];
     /** Why this entry cannot be called — carried through from discovery, rendered as a warning. */
@@ -25,10 +27,22 @@ export interface SkillEntry {
     /** Actions only: true when the chain includes `.ref<…>()`, so it publishes a capability. */
     readonly publishesCapability?: boolean;
 }
+/** The project the skill describes: where its reader stands, and what config omkit was given. */
+export interface SkillProject {
+    /** Directory the file is written for — `.claude/` lives here, and paths are relative to it. */
+    readonly root: string;
+    /** Absolute path of the tsconfig discovery ran against, when the caller knows it. */
+    readonly tsconfig?: string;
+}
 /** Everything the renderer needs, plus the hash that detects drift against it. */
 export interface SkillModel {
     readonly oms: readonly SkillEntry[];
     readonly actions: readonly SkillEntry[];
+    /**
+     * The `--tsconfig` value every rendered command needs, relative to the root. Absent when the
+     * CLI's own default already finds it — the flag would then be noise on every line.
+     */
+    readonly tsconfig?: string;
     /** First 8 hex of sha256 over the registry data below — never over the rendered markdown. */
     readonly hash: string;
 }
@@ -42,7 +56,7 @@ export interface SkillModel {
  * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
  * server, so generating a skill can never widen what an assistant will attempt.
  */
-export declare function buildSkillModel(registrations: RegistrationSet, registry: Registry, root: string): SkillModel;
+export declare function buildSkillModel(registrations: RegistrationSet, registry: Registry, project: SkillProject): SkillModel;
 /**
  * The staleness hash: first 8 hex of sha256 over the registry data, deliberately **not** over
  * the rendered markdown, so reformatting the file does not read as drift.
@@ -52,4 +66,4 @@ export declare function buildSkillModel(registrations: RegistrationSet, registry
  * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
  * different property order cannot masquerade as a change.
  */
-export declare function registryHash(entries: readonly SkillEntry[]): string;
+export declare function registryHash(entries: readonly SkillEntry[], tsconfig?: string): string;

package/dist/skill/model.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { shapeHint } from "../core/schema-hint.js";
+import { DEFAULT_TSCONFIG } from "../client/types.js";
 /**
  * Fold a project's registrations and its AST scan into the model the skill renders from.
  *
@@ -11,7 +12,8 @@ import { shapeHint } from "../core/schema-hint.js";
  * Only `.mcp()`-marked entries survive — exposure is opt-in, exactly as it is for the MCP
  * server, so generating a skill can never widen what an assistant will attempt.
  */
-export function buildSkillModel(registrations, registry, root) {
+export function buildSkillModel(registrations, registry, project) {
+    const { root } = project;
     const outlines = new Map(registry.oms.map((o) => [key(o.name, o.file), o.calls]));
     const capabilities = new Map(registry.actions.map((a) => [key(a.name, a.file), a.publishesCapability]));
     const oms = registrations.oms
@@ -22,7 +24,26 @@ export function buildSkillModel(registrations, registry, root) {
         .filter(isExposed)
         .map((a) => actionEntry(a, capabilities.get(key(a.name, a.file)), root))
         .sort(byName);
-    return { oms, actions, hash: registryHash([...oms, ...actions]) };
+    const tsconfig = tsconfigFlag(project);
+    return {
+        oms,
+        actions,
+        ...(tsconfig ? { tsconfig } : {}),
+        hash: registryHash([...oms, ...actions], tsconfig),
+    };
+}
+/**
+ * What a reader standing at the root must pass as `--tsconfig`, or `undefined` when they need
+ * pass nothing. omkit looks for `tsconfig.omkit.json` in the working directory, so a project
+ * whose config sits anywhere else — the common case once an om project lives in a subfolder —
+ * has commands that only work with the flag. Rendering it is the difference between a file
+ * that documents how to run this project and one that documents how to run some other project.
+ */
+function tsconfigFlag({ root, tsconfig }) {
+    if (tsconfig === undefined)
+        return undefined;
+    const rel = relative(tsconfig, root);
+    return rel === DEFAULT_TSCONFIG ? undefined : rel;
 }
 function isExposed(r) {
     return r.mcp !== undefined;
@@ -60,16 +81,75 @@ function actionEntry(action, publishesCapability, root) {
         ...(action.unavailable ? { unavailable: action.unavailable } : {}),
     };
 }
-/**
- * Sketch a schema, falling back to the schema itself. `shapeHint` is all-or-nothing by design,
- * so a `undefined` return means the shape would have been misleading — the honest answer then
- * is the raw JSON Schema the caller actually has to satisfy, not a partial sketch.
- */
 function describeArgs(schema) {
     if (!schema)
         return {};
     const hint = shapeHint(schema);
-    return hint === undefined ? { argSchema: schema } : { argHint: hint };
+    const example = argExample(schema);
+    return {
+        ...(hint === undefined ? { argSchema: schema } : { argHint: hint }),
+        ...(example ? { argExample: example } : {}),
+    };
+}
+/**
+ * A complete, valid `OMKIT_ARGS` object for this schema, or `undefined` when one cannot be
+ * built honestly.
+ *
+ * "Complete" is the whole point: an example missing a required field does not demonstrate the
+ * call, it demonstrates the prompt the reader gets instead. So every required field must be
+ * sampleable or there is no example — and when nothing is required, one optional field is
+ * enough to show the shape without implying the rest are needed.
+ */
+function argExample(schema) {
+    const properties = schema.properties;
+    if (typeof properties !== "object" || properties === null)
+        return undefined;
+    const entries = Object.entries(properties);
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const mandatory = entries.filter(([key]) => required.has(key));
+    if (mandatory.length > 0) {
+        const example = {};
+        for (const [key, field] of mandatory) {
+            const value = sample(field);
+            if (value === undefined)
+                return undefined;
+            example[key] = value;
+        }
+        return example;
+    }
+    for (const [key, field] of entries) {
+        const value = sample(field);
+        if (value !== undefined)
+            return { [key]: value };
+    }
+    return undefined;
+}
+/**
+ * One plausible value for a field, or `undefined` when the type has no short literal form.
+ * A declared default wins over an invented value — it is both valid and the author's own
+ * choice, which reads better in an example than a zero or an ellipsis.
+ */
+function sample(field) {
+    if (typeof field !== "object" || field === null)
+        return undefined;
+    const enumValues = field.enum;
+    if (Array.isArray(enumValues) && enumValues.length > 0)
+        return enumValues[0];
+    if (field.default !== undefined)
+        return field.default;
+    switch (field.type) {
+        case "string":
+            return "…";
+        case "number":
+        case "integer":
+            return 0;
+        case "boolean":
+            return false;
+        // Objects and arrays have no one-line stand-in: `{}` and `[]` are as likely to be rejected
+        // by the schema as accepted by it, and a rejected example is worse than none.
+        default:
+            return undefined;
+    }
 }
 /** Project-relative with forward slashes; absolute only if the file lies outside the root. */
 function relative(file, root) {
@@ -88,8 +168,8 @@ const posix = (p) => p.split(path.sep).join("/").split("\\").join("/");
  * drift the hash exists to catch. Keys are sorted before hashing so a schema serialised in a
  * different property order cannot masquerade as a change.
  */
-export function registryHash(entries) {
-    const material = entries.map((e) => [
+export function registryHash(entries, tsconfig) {
+    const declarations = entries.map((e) => [
         e.kind,
         e.name,
         e.file,
@@ -101,6 +181,10 @@ export function registryHash(entries) {
         e.argSchema ?? e.argHint ?? "",
         (e.calls ?? []).map((c) => [c.name, c.tag ?? ""]),
     ]);
+    // The invocation is hashed beside the declarations because it is part of what the file
+    // claims: move a project's tsconfig and every command in it becomes wrong, while not one
+    // om has changed. Drift is "the file no longer describes this project", not "an om changed".
+    const material = [declarations, tsconfig ?? ""];
     return createHash("sha256").update(canonical(material)).digest("hex").slice(0, 8);
 }
 /** JSON with object keys sorted at every depth, so key order can never change the hash. */

package/dist/skill/render.js

@@ -26,21 +26,40 @@ export function renderSkill(model, opts) {
         ...howToRun(model),
         ...workflows(model),
         ...actions(model),
-        ...whereOutputLands(),
+        ...whereOutputLands(model),
     ];
     return `${lines.join("\n")}\n`;
 }
 function howToRun(model) {
-    const example = model.oms[0]?.name ?? "<om>";
-    const withArgs = model.oms.find((o) => o.argHint !== undefined) ?? model.oms[0];
+    // A long-lived om is the wrong thing to demonstrate `run` with: it never returns, and the
+    // entry's own heading says so a few lines further down. Prefer one that settles, and fall
+    // back to the long-lived one only when the project has nothing else — annotated, so the
+    // command still reads as deliberate rather than as an example that hangs.
+    const settling = model.oms.filter((o) => o.mode !== "long-lived");
+    const pool = settling.length ? settling : model.oms;
+    const example = pool[0];
+    const withArgs = pool.find((o) => o.argExample !== undefined);
+    const name = example?.name ?? "<om>";
+    const holds = example?.mode === "long-lived" ? "  # long-lived: runs until you stop it" : "";
+    // Appended to every command, because omkit resolves its config against the working directory
+    // and this file's reader is at the project root, which is not necessarily where the config is.
+    const config = model.tsconfig ? ` --tsconfig ${model.tsconfig}` : "";
     return [
         "## How to run",
         "",
-        "**Shell — always available:**",
+        "**Shell — always available.** Run these from the project root (the directory holding",
+        "`.claude/`); every path here is relative to it.",
         "",
         "```bash",
-        `npx omkit run ${example}`,
-        `OMKIT_ARGS='${exampleArgs(withArgs)}' npx omkit run ${withArgs?.name ?? example}`,
+        `npx omkit run ${shellName(name)}${config}${holds}`,
+        // Only when there is a real one to show. An `OMKIT_ARGS='{}'` line teaches the syntax and
+        // nothing else, and reads as though this project's runs take no arguments — which is the
+        // opposite of what it means when a project's args could not be sampled.
+        ...(withArgs
+            ? [
+                `OMKIT_ARGS='${JSON.stringify(withArgs.argExample)}' npx omkit run ${shellName(withArgs.name)}${config}`,
+            ]
+            : []),
         "```",
         "",
         "Arguments travel as one JSON object in `OMKIT_ARGS`. Anything an om declares but does not",
@@ -50,24 +69,25 @@ function howToRun(model) {
         "completion and returns its verdict; `start_om` starts a long-lived one and returns a run id",
         "to poll with `get_run`, read with `tail_run`, and end with `cancel_run`.",
         "",
-        "To wire it up: `claude mcp add omkit -- npx omkit mcp`",
+        `To wire it up: \`claude mcp add omkit -- npx omkit mcp${config}\``,
         "",
         "At runtime `list_oms` is authoritative — this file is orientation, and can drift.",
         "",
     ];
 }
 /**
- * A plausible `OMKIT_ARGS` value built from the first declared field, so the example shows the
- * real shape rather than a placeholder. Falls back to an empty object when nothing is declared.
+ * An om's name as one shell argument.
+ *
+ * A name is free text — `om("DTF Tests")` is legal, and reads well in a log — but written bare
+ * into a command it stops being one argument: `omkit run DTF Tests` resolves the target as
+ * "DTF" and leaves "Tests" as a stray positional. So the file carries the quotes rather than
+ * leaving the reader to notice they are missing.
+ *
+ * Double quotes, not single, because cmd.exe and PowerShell understand them too. Names built
+ * from shell metacharacters beyond a quote or a backslash (`$`, backticks) are the author's to
+ * avoid — there is no quoting form that is literal in every shell at once.
  */
-function exampleArgs(entry) {
-    const match = entry?.argHint?.match(/\{ (\w+)\??: (\w+)/);
-    if (!match)
-        return "{}";
-    const [, field, type] = match;
-    const value = type === "string" ? '"…"' : type === "boolean" ? "false" : "0";
-    return `{"${field}":${value}}`;
-}
+const shellName = (name) => /^[\w:.@/-]+$/.test(name) ? name : `"${name.replace(/([\\"])/g, "\\$1")}"`;
 function workflows(model) {
     if (model.oms.length === 0) {
         return ["## Workflows", "", "_None exposed. Mark an om with `.mcp()` to list it here._", ""];
@@ -114,12 +134,18 @@ function entry(e, heading) {
     lines.push("");
     return lines;
 }
+/** The model's paths are already posix, so the directory half is a plain string operation. */
+const posixDirname = (file) => file.slice(0, Math.max(0, file.lastIndexOf("/")));
 const renderCall = (c) => c.tag ? `\`${c.name}\` [${c.tag}]` : `\`${c.name}\``;
-function whereOutputLands() {
+function whereOutputLands(model) {
+    // Spelled from the root the reader stands at, not as a bare `logs/`: the folder belongs to
+    // the project that owns the config, which in a subfolder layout is not where they are.
+    const dir = model.tsconfig ? posixDirname(model.tsconfig) : "";
+    const logs = dir ? `${dir}/logs` : "logs";
     return [
         "## Where output lands",
         "",
-        "`logs/<name>-<hash8>/<date>/<time>/` — `main.log`, `result.json`, `artifacts.log`,",
+        `\`${logs}/<name>-<hash8>/<date>/<time>/\` — \`main.log\`, \`result.json\`, \`artifacts.log\`,`,
         "`events.log`, `asserts.log`, `raw.jsonl`. A run's identity is its name plus its defining",
         'file, so "the latest run of X" is always resolvable without parsing scrollback.',
         "",

package/dist/skill/root.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The directory a generated skill is written for: the nearest enclosing repository, or the
+ * project itself when there is none.
+ *
+ * The root is not really a free choice. A skill file lives at `.claude/skills/<name>/SKILL.md`,
+ * an assistant reads it with the repository as its working directory, and so every path and
+ * command inside has to be relative to *that* — not to wherever the om project's tsconfig
+ * happens to sit. Defaulting to the tsconfig's own directory made the common monorepo layout
+ * (an `om/` folder beside the code it drives) wrong by default, and needed a second flag to
+ * correct what the first flag had just decided.
+ *
+ * `.git` is checked as an entry, not as a directory: a worktree or submodule records it as a
+ * file containing a `gitdir:` pointer, and that is still the top of the checkout.
+ */
+export declare function skillRoot(projectDir: string): string;

package/dist/skill/root.js

@@ -0,0 +1,27 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The directory a generated skill is written for: the nearest enclosing repository, or the
+ * project itself when there is none.
+ *
+ * The root is not really a free choice. A skill file lives at `.claude/skills/<name>/SKILL.md`,
+ * an assistant reads it with the repository as its working directory, and so every path and
+ * command inside has to be relative to *that* — not to wherever the om project's tsconfig
+ * happens to sit. Defaulting to the tsconfig's own directory made the common monorepo layout
+ * (an `om/` folder beside the code it drives) wrong by default, and needed a second flag to
+ * correct what the first flag had just decided.
+ *
+ * `.git` is checked as an entry, not as a directory: a worktree or submodule records it as a
+ * file containing a `gitdir:` pointer, and that is still the top of the checkout.
+ */
+export function skillRoot(projectDir) {
+    let dir = path.resolve(projectDir);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".git")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return path.resolve(projectDir);
+        dir = parent;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omkit",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "A tiny runtime for developer workflows: typed actions that pass runtime capabilities and emit typed events, under one run and one shared log. The operational/runtime layer to tskb's knowledge layer.",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,6 +59,7 @@
     "playwright-core": "^1.49.0",
     "react": "^19.2.8",
     "tsx": "4.23.1",
+    "typescript": "^5.9.3",
     "zod": "^4.4.3",
     "zx": "^8.8.5"
   },
@@ -66,7 +67,6 @@
     "@types/node": "^24",
     "@types/react": "^19.2.17",
     "ink-testing-library": "^4.0.0",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.9.3"
+    "rimraf": "^6.0.1"
   }
 }