@sdods/cli 0.5.2 → 0.7.0

package/dist/commands/init.js

@@ -6,6 +6,7 @@ import pc from 'picocolors';
 import { OrganizationSchema, SlugSchema, WorkspaceSchema } from '@sdods/contracts';
 import { SdodsError, VERSION, WORKSPACE_FILE } from '@sdods/core';
 import { globalOptions } from '../context.js';
+import { installSkills } from '../skills-catalog.js';
 import { json, ok, out, warn } from '../ui.js';
 /** Root of the SDODS monorepo this CLI runs from (used by --link, which needs a real checkout). */
 export function sourceRepoRoot() {
@@ -278,11 +279,12 @@ Docs: https://docs.sdods.com
     else {
         write('projects/.gitkeep', '');
     }
-    const skillsSrc = join(src, '.claude', 'skills');
-    if (existsSync(skillsSrc)) {
-        cpSync(skillsSrc, join(target, '.claude', 'skills'), { recursive: true });
-        files.push('.claude/skills/');
-    }
+    // The user-facing skills, for Claude Code (.claude/skills) and every agent that reads the shared
+    // .agents/skills. Copied from the bundled set, never from this repository's own .claude/skills,
+    // which also holds skills for releasing SDODS itself.
+    const skills = installSkills({ rootDir: target });
+    if (skills.some((s) => s.status !== 'skipped'))
+        files.push('.claude/skills/', '.agents/skills/');
     if (flags.from) {
         try {
             const analyze = (await import('@sdods/core/analyze'));

package/dist/commands/mcp.js

@@ -1,9 +1,9 @@
 import pc from 'picocolors';
 import { SdodsError } from '@sdods/core';
-import { ALL_CAPABILITIES, DEFAULT_CAPABILITIES } from '@sdods/mcp';
+import { ALL_CAPABILITIES, DEFAULT_CAPABILITIES, MCP_CLIENTS } from '@sdods/mcp';
 import { createContext } from '../context.js';
 import { json, ok, out } from '../ui.js';
-const CLIENTS = ['claude', 'codex', 'cursor', 'vscode', 'windsurf'];
+const CLIENTS = MCP_CLIENTS;
 /**
  * The default capability list, derived rather than restated. It used to be spelled out in three
  * places in this file — the fallback, the flag default and the "did the user change it" sentinel —
@@ -80,7 +80,7 @@ export function register(program) {
     });
     mcp
         .command('install <client>')
-        .description('Register the SDODS MCP server with a client: claude | codex | cursor | vscode | windsurf (merges, never clobbers)')
+        .description('Register the SDODS MCP server with a client: claude | codex | cursor | vscode | windsurf | gemini (merges, never clobbers)')
         .option('-p, --project <slug>')
         .option('-e, --env <name>')
         .option('--caps <list>')
@@ -167,12 +167,27 @@ async function registerViaClientCli(client, o, cwd) {
             });
         }
     };
+    // A remote server without credentials answers 401 to every call, so the token is part of the
+    // registration. Neither form writes the secret: Claude Code expands ${SDODS_TOKEN} from the
+    // environment when it reads .mcp.json, and Codex reads the variable named by
+    // --bearer-token-env-var at connect time.
     const addArgs = client === 'claude'
         ? o.httpUrl
-            ? ['mcp', 'add', '-s', 'project', '--transport', 'http', 'sdods', o.httpUrl]
+            ? [
+                'mcp',
+                'add',
+                '-s',
+                'project',
+                '--transport',
+                'http',
+                'sdods',
+                o.httpUrl,
+                '--header',
+                'Authorization: Bearer ${SDODS_TOKEN}',
+            ]
             : ['mcp', 'add', '-s', 'project', 'sdods', '--', ...stdio]
         : o.httpUrl
-            ? ['mcp', 'add', 'sdods', '--url', o.httpUrl]
+            ? ['mcp', 'add', 'sdods', '--url', o.httpUrl, '--bearer-token-env-var', 'SDODS_TOKEN']
             : ['mcp', 'add', 'sdods', '--', ...stdio];
     const ok1 = await run(addArgs);
     if (!ok1)

package/dist/commands/skills.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function register(program: Command): void;
+//# sourceMappingURL=skills.d.ts.map

package/dist/commands/skills.js

@@ -0,0 +1,69 @@
+import { relative } from 'node:path';
+import pc from 'picocolors';
+import { SdodsError } from '@sdods/core';
+import { createContext } from '../context.js';
+import { DEFAULT_SKILL_TARGETS, SKILL_TARGETS, installSkills, listBundledSkills, } from '../skills-catalog.js';
+import { info, json, ok, out, table } from '../ui.js';
+function parseList(raw) {
+    return (raw ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export function register(program) {
+    const skills = program
+        .command('skills')
+        .description('Agent Skills for Claude Code, Codex, Cursor, Copilot, Gemini CLI and others');
+    skills
+        .command('list')
+        .description('List the skills bundled with SDODS')
+        .action((_opts, cmd) => {
+        const ctx = createContext(cmd);
+        const rows = listBundledSkills().map(({ name, description }) => ({ name, description }));
+        if (ctx.opts.json)
+            return json(rows);
+        table(rows);
+    });
+    skills
+        .command('install')
+        .description('Copy the bundled skills where your coding agents read them (default: .claude/skills and .agents/skills)')
+        .option('--agent <list>', `comma-separated: ${Object.keys(SKILL_TARGETS).join(', ')} (default ${DEFAULT_SKILL_TARGETS.join(',')})`)
+        .option('-g, --global', 'install into your home directory instead of the project')
+        .option('--skill <names>', 'only these skills (comma-separated)')
+        .option('--force', 'replace skills that are already installed')
+        .action((opts, cmd) => {
+        const ctx = createContext(cmd);
+        const targets = parseList(opts.agent);
+        const bad = targets.filter((t) => !(t in SKILL_TARGETS));
+        if (bad.length)
+            throw new SdodsError('CONFIG_INVALID', `Unknown agent ${bad.join(', ')}.`, {
+                hint: `Use one or more of ${Object.keys(SKILL_TARGETS).join(', ')}.`,
+                exitCode: 2,
+            });
+        let results;
+        try {
+            results = installSkills({
+                rootDir: ctx.rootDir,
+                targets: targets,
+                global: opts.global === true,
+                skills: parseList(opts.skill),
+                force: opts.force === true,
+            });
+        }
+        catch (e) {
+            throw new SdodsError('CONFIG_INVALID', e.message, { exitCode: 2 });
+        }
+        if (ctx.opts.json)
+            return json(results);
+        const base = opts.global ? (process.env.HOME ?? '') : ctx.rootDir;
+        for (const r of results) {
+            const where = relative(base, r.path) || r.path;
+            if (r.status === 'skipped')
+                out(pc.dim(`- ${where} (already installed; --force replaces it)`));
+            else
+                ok(`${r.status === 'replaced' ? 'Replaced' : 'Installed'} ${where}`);
+        }
+        info('Restart or reload your agent so it picks the skills up.');
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/commands/users.js

@@ -1,11 +1,15 @@
 import { SdodsError } from '@sdods/core';
 import { MIN_PASSWORD_LENGTH } from '@sdods/contracts/names';
 import { createContext } from '../context.js';
-import { json, ok, table } from '../ui.js';
+import { info, json, ok, table, warn } from '../ui.js';
 async function openDb() {
     const db = await import('@sdods/db');
     return db.openDb();
 }
+function assertPassword(password) {
+    if (String(password).length < MIN_PASSWORD_LENGTH)
+        throw new SdodsError('CONFIG_INVALID', `Password must be at least ${MIN_PASSWORD_LENGTH} characters.`, { exitCode: 2 });
+}
 export function register(program) {
     const users = program
         .command('users')
@@ -21,10 +25,7 @@ export function register(program) {
         .option('--org-owner', 'grant organization owner on orgs without an owner')
         .action(async (opts, cmd) => {
         const ctx = createContext(cmd);
-        if (String(opts.password).length < 8)
-            throw new SdodsError('CONFIG_INVALID', 'Password must be at least 8 characters.', {
-                exitCode: 2,
-            });
+        assertPassword(opts.password);
         const adb = await openDb();
         try {
             const db = await import('@sdods/db');
@@ -132,6 +133,73 @@ export function register(program) {
             await adb.close();
         }
     });
+    users
+        .command('set-password <username>')
+        .description('Set a password and sign the user out everywhere; --activate re-enables the account')
+        .requiredOption('--password <password>', `new password (min ${MIN_PASSWORD_LENGTH} chars)`)
+        .option('--activate', 're-enable a deactivated account')
+        .action(async (username, opts, cmd) => {
+        const ctx = createContext(cmd);
+        assertPassword(opts.password);
+        const adb = await openDb();
+        try {
+            const db = await import('@sdods/db');
+            const { hashPassword } = await import('@sdods/server');
+            const u = await db.getUserByUsername(adb.db, username);
+            if (!u)
+                throw new SdodsError('CONFIG_NOT_FOUND', `User ${username} not found.`, {
+                    exitCode: 2,
+                });
+            await db.updateUser(adb.db, adb.driver, u.id, {
+                passwordHash: await hashPassword(opts.password),
+                ...(opts.activate ? { active: true } : {}),
+            });
+            await db.deleteSessionsForUser(adb.db, u.id);
+            await db.audit(adb.db, {
+                actorType: 'cli',
+                action: 'user.password',
+                targetType: 'user',
+                targetId: u.id,
+                details: { username, activated: Boolean(opts.activate) },
+            });
+            const active = opts.activate ? true : u.active;
+            if (ctx.opts.json)
+                return json({ id: u.id, username, active });
+            ok(`Password set for ${username}; existing sessions signed out`);
+            if (!active)
+                warn(`${username} is deactivated; pass --activate to let them sign in`);
+        }
+        finally {
+            await adb.close();
+        }
+    });
+    users
+        .command('reset')
+        .description('Remove every user, session, API token and membership; projects and runs stay (next serve offers /setup)')
+        .option('--yes', 'confirm')
+        .action(async (opts, cmd) => {
+        const ctx = createContext(cmd);
+        if (!opts.yes)
+            throw new SdodsError('NOT_SUPPORTED', 'users reset removes every user; pass --yes to confirm.', { exitCode: 2 });
+        const adb = await openDb();
+        try {
+            const db = await import('@sdods/db');
+            const removed = await db.deleteAllUsers(adb.db);
+            await db.audit(adb.db, {
+                actorType: 'cli',
+                action: 'users.reset',
+                targetType: 'user',
+                details: { removed },
+            });
+            if (ctx.opts.json)
+                return json({ removed });
+            ok(`Removed ${removed} user${removed === 1 ? '' : 's'}; projects, runs and schedules are kept`);
+            info('Restart `sdods serve` for a one-time /setup link, or run: sdods users create --admin --username <name> --password <pw>');
+        }
+        finally {
+            await adb.close();
+        }
+    });
     users
         .command('grant <username>')
         .description('Grant a membership role: --org <slug> --role owner|admin|member, or --workspace <slug> --role admin|editor|viewer')

package/dist/program.js

@@ -26,6 +26,7 @@ import { register as registerTrace } from './commands/trace.js';
 import { register as registerAgent } from './commands/agent.js';
 import { register as registerProposals } from './commands/proposals.js';
 import { register as registerMcp } from './commands/mcp.js';
+import { register as registerSkills } from './commands/skills.js';
 import { register as registerServe } from './commands/serve.js';
 import { register as registerUsers } from './commands/users.js';
 import { register as registerTokens } from './commands/tokens.js';
@@ -50,7 +51,9 @@ export function buildProgram() {
         .option('--no-color', 'disable colours')
         .showHelpAfterError('(add --help for usage)')
         .showSuggestionAfterError()
-        .configureHelp({ sortSubcommands: true });
+        .configureHelp({ sortSubcommands: true })
+        // Root help only: 'after' is not inherited by subcommands.
+        .addHelpText('after', '\nDocs: https://docs.sdods.com  ·  Sponsor: https://sdods.com/sponsor/');
     registerProjectCommands(program);
     registerEnvCommands(program);
     registerConfigCommands(program);
@@ -77,6 +80,7 @@ export function buildProgram() {
     registerAgent(program);
     registerProposals(program);
     registerMcp(program);
+    registerSkills(program);
     registerServe(program);
     registerUsers(program);
     registerTokens(program);

package/dist/skills-catalog.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The Agent Skills SDODS ships to users. `packages/cli/skills/` is the one source: `sdods init`
+ * copies it into new workspaces, `sdods skills install` copies it into any project or home
+ * directory, the npm tarball carries it, and scripts/build-agent-plugin.ts builds the public
+ * skills repository and Claude Code plugin from it.
+ */
+export declare function bundledSkillsDir(): string;
+export interface BundledSkill {
+    name: string;
+    description: string;
+    dir: string;
+}
+export declare function listBundledSkills(dir?: string): BundledSkill[];
+/** The `name:` and `description:` lines of a SKILL.md frontmatter block (single-line values). */
+export declare function frontmatter(text: string): Record<string, string>;
+/**
+ * Where each agent family looks for skills, relative to a project root (or to the home directory
+ * with `global`). `.agents/skills` is the shared location read by Codex, Cursor, Gemini CLI,
+ * GitHub Copilot, OpenCode, Amp and Goose; Claude Code reads `.claude/skills`.
+ */
+export declare const SKILL_TARGETS: {
+    readonly claude: ".claude/skills";
+    readonly agents: ".agents/skills";
+    readonly cursor: ".cursor/skills";
+    readonly copilot: ".github/skills";
+    readonly gemini: ".gemini/skills";
+};
+export type SkillTarget = keyof typeof SKILL_TARGETS;
+export declare const DEFAULT_SKILL_TARGETS: SkillTarget[];
+export interface InstallSkillsOptions {
+    rootDir: string;
+    targets?: SkillTarget[];
+    global?: boolean;
+    skills?: string[];
+    force?: boolean;
+    home?: string;
+    source?: string;
+}
+export interface InstalledSkill {
+    skill: string;
+    target: SkillTarget;
+    path: string;
+    status: 'installed' | 'replaced' | 'skipped';
+}
+export declare function installSkills(o: InstallSkillsOptions): InstalledSkill[];
+//# sourceMappingURL=skills-catalog.d.ts.map

package/dist/skills-catalog.js

@@ -0,0 +1,75 @@
+import { cpSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The Agent Skills SDODS ships to users. `packages/cli/skills/` is the one source: `sdods init`
+ * copies it into new workspaces, `sdods skills install` copies it into any project or home
+ * directory, the npm tarball carries it, and scripts/build-agent-plugin.ts builds the public
+ * skills repository and Claude Code plugin from it.
+ */
+export function bundledSkillsDir() {
+    // src/skills-catalog.ts and dist/skills-catalog.js both sit one level below packages/cli
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+}
+export function listBundledSkills(dir = bundledSkillsDir()) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, 'SKILL.md')))
+        .map((e) => {
+        const fm = frontmatter(readFileSync(join(dir, e.name, 'SKILL.md'), 'utf8'));
+        return { name: fm.name ?? e.name, description: fm.description ?? '', dir: join(dir, e.name) };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** The `name:` and `description:` lines of a SKILL.md frontmatter block (single-line values). */
+export function frontmatter(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    const out = {};
+    for (const line of (m?.[1] ?? '').split(/\r?\n/)) {
+        const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (kv)
+            out[kv[1]] = kv[2].replace(/^['"]|['"]$/g, '');
+    }
+    return out;
+}
+/**
+ * Where each agent family looks for skills, relative to a project root (or to the home directory
+ * with `global`). `.agents/skills` is the shared location read by Codex, Cursor, Gemini CLI,
+ * GitHub Copilot, OpenCode, Amp and Goose; Claude Code reads `.claude/skills`.
+ */
+export const SKILL_TARGETS = {
+    claude: '.claude/skills',
+    agents: '.agents/skills',
+    cursor: '.cursor/skills',
+    copilot: '.github/skills',
+    gemini: '.gemini/skills',
+};
+export const DEFAULT_SKILL_TARGETS = ['claude', 'agents'];
+/** GitHub Copilot's user-level directory is `~/.copilot/skills`, not `~/.github/skills`. */
+const GLOBAL_OVERRIDES = { copilot: '.copilot/skills' };
+export function installSkills(o) {
+    const available = listBundledSkills(o.source);
+    const wanted = o.skills?.length ? o.skills : available.map((s) => s.name);
+    const unknown = wanted.filter((w) => !available.some((s) => s.name === w));
+    if (unknown.length)
+        throw new Error(`Unknown skill ${unknown.join(', ')}. Bundled: ${available.map((s) => s.name).join(', ')}`);
+    const base = o.global ? (o.home ?? homedir()) : o.rootDir;
+    const results = [];
+    for (const target of o.targets?.length ? o.targets : DEFAULT_SKILL_TARGETS) {
+        const rel = (o.global && GLOBAL_OVERRIDES[target]) || SKILL_TARGETS[target];
+        for (const skill of available.filter((s) => wanted.includes(s.name))) {
+            const path = join(base, rel, skill.name);
+            const exists = existsSync(join(path, 'SKILL.md'));
+            if (exists && !o.force) {
+                results.push({ skill: skill.name, target, path, status: 'skipped' });
+                continue;
+            }
+            cpSync(skill.dir, path, { recursive: true, force: true });
+            results.push({ skill: skill.name, target, path, status: exists ? 'replaced' : 'installed' });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=skills-catalog.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/cli",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "SDODS command line: run, record, analyze, agents, MCP server, scheduler and the web server.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -17,14 +17,15 @@
   "files": [
     "dist",
     "bin",
-    "templates"
+    "templates",
+    "skills"
   ],
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.5.2",
-    "@sdods/core": "0.5.2",
+    "@sdods/contracts": "0.7.0",
+    "@sdods/core": "0.7.0",
     "commander": "^15.0.0",
     "execa": "^10.0.1",
     "picocolors": "^1.1.1",
@@ -33,12 +34,12 @@
     "zod": "^4.5.4",
     "@playwright/test": "^1.63.0",
     "playwright-core": "^1.63.0",
-    "@sdods/integrations": "0.5.2",
-    "@sdods/mcp": "0.5.2",
-    "@sdods/agents": "0.5.2",
-    "@sdods/db": "0.5.2",
+    "@sdods/integrations": "0.7.0",
+    "@sdods/mcp": "0.7.0",
+    "@sdods/agents": "0.7.0",
+    "@sdods/db": "0.7.0",
     "csv-parse": "^7.0.2",
-    "@sdods/server": "0.5.2"
+    "@sdods/server": "0.7.0"
   },
   "homepage": "https://sdods.com",
   "bugs": {

package/skills/sdods/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: sdods
+description: Work in an SDODS test-automation workspace — BDD features for UI, API and hybrid flows. Use when writing, fixing or reviewing Gherkin features, steps, page objects or project/env YAML, running suites, reading results, or using the sdods CLI or its MCP tools.
+---
+
+# SDODS
+
+SDODS runs BDD scenarios for UI, API and hybrid flows from one workspace. A workspace has
+`sdods.workspace.yaml` at its root; each project is `projects/<slug>/sdods.project.yaml` plus
+`envs/<env>.yaml`, and features live in `projects/<slug>/features/<module>/`.
+
+Commands below use `sdods`. Without a global install use `npx -y @sdods/cli` in its place; inside
+an SDODS source checkout use `bun run sdods`. When the `sdods` MCP server is connected, prefer its
+tools (`project_list`, `feature_list`, `step_find`, `run_tests`, `run_get`, `analyze_failure`, …)
+over shelling out.
+
+## Rules
+
+- Every scenario carries exactly one layer tag (`@ui`, `@api`, `@hybrid`) and exactly one suite tag
+  (`@smoke`, `@regression`, `@sanity`). Optional: `@visual @a11y @perf @mock @data-driven @pool`,
+  and value tags `@user:<role> @data:<dataset> @har:<name> @jira:KEY @skip:<browser>`.
+- Reuse existing steps first (`sdods steps list -p <slug>`, or `step_find`). Add a step only when no
+  phrasing fits, and name it in the same style.
+- Locator priority: role + name > label > test id > placeholder > text > CSS. Never XPath.
+- Page objects use step decorators (`@Fixture`, `@Given/@When/@Then`) and heal-aware locators:
+  `this.heal.locator(primary, { role, name, testId, description })`.
+- Keep scenarios independent and deterministic, with no sleeps. Seed through the API rather than the
+  UI, and clean up what you create.
+- Secrets are never literals; reference `${VAR}`.
+- When acting through SDODS agents or MCP write tools, changes are proposals (`feature_write`,
+  `proposals`) that a person accepts with `sdods proposals accept <id>`.
+
+## Quick reference
+
+| Task | Command |
+| --- | --- |
+| Projects and hierarchy | `sdods project list`, `sdods workspace tree` |
+| Resolved config, with where each value came from | `sdods config show -p <slug> -e <env> --explain` |
+| Validate features | `sdods lint -p <slug>` |
+| Run a slice | `sdods run -p <slug> -e <env> -l api` · `-l ui -b chromium -t @smoke` · `--process pr-check` |
+| Results | `sdods report --last`, `sdods heal report --last`, `sdods trace --last` |
+| Available steps | `sdods steps list -p <slug>` |
+| Record and replay | `sdods record -p <slug> -e <env> --user <role> --name <name>` |
+| Agents | `sdods agent plan\|generate\|heal\|upgrade\|review -p <slug> --dry-run`, `sdods proposals list` |
+| Health check | `sdods doctor` |
+
+## Writing a scenario
+
+1. Pick the module directory under `features/` and tag the Feature with one layer and one suite tag.
+2. Reuse steps from `sdods steps list`; add project steps in `steps/<module>.steps.ts` only if needed.
+3. Get data from datasets (`Given I load dataset "users" row 1`) or `@user:<role>`, never literals.
+4. `sdods lint -p <slug>`, then run just that scenario and check the before/after screenshots in
+   `.sdods/runs/<runId>/`.
+
+## Verify before claiming done
+
+```bash
+sdods lint -p <slug>
+```
+
+```bash
+sdods run -p <slug> -e <env> -l api
+```
+
+```bash
+sdods run -p <slug> -e <env> -l ui -b chromium -t @smoke
+```
+
+Exit codes: `0` passed · `1` test failures · `2` configuration or usage error · `3` lint errors.

package/{templates/.claude/skills → skills}/sdods-record/SKILL.md

@@ -7,12 +7,15 @@ description: Record a browser flow with SDODS for a given project, environment,
 
 Re-runnable recipe. Ask for the parameters you do not have, then follow the steps. Never edit `main` directly; recordings land in `projects/<project>/recorded/` and conversions become proposals.
 
+Commands below use `sdods`. Without a global install use `npx -y @sdods/cli` in its place; inside
+an SDODS source checkout use `bun run sdods`.
+
 ## Parameters
 
 | Name | Required | Example | Notes |
 |---|---|---|---|
-| `project` | yes | `demo-shop` | `bun run sdods project list` shows slugs |
-| `env` | yes | `staging`, `local` | `bun run sdods env list -p <project>` |
+| `project` | yes | `demo-shop` | `sdods project list` shows slugs |
+| `env` | yes | `staging`, `local` | `sdods env list -p <project>` |
 | `name` | yes | `checkout-standard` | becomes `recorded/<name>.spec.ts`; include the role in the name |
 | `role` | no | `standard`, `problem`, `admin` | leases a pool user of that role and starts logged in (storageState) |
 | `url` | no | `/inventory.html` | route path or absolute URL to open first |
@@ -24,38 +27,38 @@ Re-runnable recipe. Ask for the parameters you do not have, then follow the step
 
 1. **Check the environment** (fail fast on missing vars):
    ```bash
-   bun run sdods doctor -p <project>
-   bun run sdods env list -p <project>
+   sdods doctor -p <project>
+   sdods env list -p <project>
    ```
 2. **Make sure the role has login state** (skip when no role):
    ```bash
-   bun run sdods auth list -p <project> -e <env>
-   bun run sdods auth capture -p <project> -e <env> --user <role>      # only if missing or expired
+   sdods auth list -p <project> -e <env>
+   sdods auth capture -p <project> -e <env> --user <role>      # only if missing or expired
    ```
 3. **Record** (opens the recorder; the person performs the flow and closes the window):
    ```bash
-   bun run sdods record -p <project> -e <env> --name <name> [--user <role>] [--url <url>] [--device "<device>"] [--browser <browser>] [--save-har]
+   sdods record -p <project> -e <env> --name <name> [--user <role>] [--url <url>] [--device "<device>"] [--browser <browser>] [--save-har]
    ```
    Output: `projects/<project>/recorded/<name>.spec.ts`, post-processed (SDODS fixtures, routes instead of absolute URLs, tags `@recorded @ui @regression`, header comment with project/env/role/device).
 4. **Play it back** on the same environment, then on another one:
    ```bash
-   bun run sdods run -p <project> -e <env> -l recorded --grep "<name>"
-   bun run sdods run -p <project> -e <other-env> -l recorded --grep "<name>"
+   sdods run -p <project> -e <env> -l recorded --grep "<name>"
+   sdods run -p <project> -e <other-env> -l recorded --grep "<name>"
    ```
-   Look at `.sdods/runs/<runId>/` for screenshots and the HTML report (`bun run sdods report --last --open`).
+   Look at `.sdods/runs/<runId>/` for screenshots and the HTML report (`sdods report --last --open`).
 5. **Repeat for other roles, environments or devices** by changing only the parameters. Use distinct names (`checkout-standard`, `checkout-problem`, `checkout-standard-iphone`).
 6. **Convert to Gherkin** when the flow is stable (agent proposal, reviewed by a person):
    ```bash
-   bun run sdods record convert projects/<project>/recorded/<name>.spec.ts
-   bun run sdods proposals list
-   bun run sdods proposals show <id>
-   bun run sdods proposals accept <id> --branch sdods/<id>     # after review
-   bun run sdods lint -p <project>
+   sdods record convert projects/<project>/recorded/<name>.spec.ts
+   sdods proposals list
+   sdods proposals show <id>
+   sdods proposals accept <id> --branch sdods/<id>     # after review
+   sdods lint -p <project>
    ```
-   The proposal reuses existing steps first (`bun run sdods steps list -p <project>`), adds only unmatched steps, and creates a page object with heal-aware locators.
+   The proposal reuses existing steps first (`sdods steps list -p <project>`), adds only unmatched steps, and creates a page object with heal-aware locators.
 7. **Offline replay** (CI-friendly) when HAR was captured:
    ```bash
-   bun run sdods har replay -p <project> -e <env> --strict -t "@har:<name>"
+   sdods har replay -p <project> -e <env> --strict -t "@har:<name>"
    ```
 
 ## Matrix template

package/{templates/.claude/skills → skills}/sdods-run/SKILL.md

@@ -5,12 +5,15 @@ description: Run SDODS test suites for a project across environments, layers (ui
 
 # SDODS run skill
 
+Commands below use `sdods`. Without a global install use `npx -y @sdods/cli` in its place; inside
+an SDODS source checkout use `bun run sdods`.
+
 ## Parameters
 
 | Name | Default | Notes |
 |---|---|---|
-| `project` | only project if one exists | `bun run sdods project list` |
-| `env` | project `envs.default` | `bun run sdods env list -p <project>` |
+| `project` | only project if one exists | `sdods project list` |
+| `env` | project `envs.default` | `sdods env list -p <project>` |
 | `layer` | all layers in the project | `-l ui`, `-l api`, `-l hybrid`, `-l recorded` (repeatable) |
 | `browser` | project `browsers` | `-b chromium -b edge -b firefox -b webkit`, or `--project-matrix` for all |
 | `tags` | none | Cucumber expression, e.g. `"@smoke and not @mock"`, `@user:admin`, `@jira:DEMO-12` |
@@ -23,29 +26,29 @@ description: Run SDODS test suites for a project across environments, layers (ui
 
 1. Validate before running (cheap, catches config and tag mistakes):
    ```bash
-   bun run sdods config validate
-   bun run sdods lint -p <project>
-   bun run sdods run -p <project> -e <env> --list          # shows the run targets that would run
+   sdods config validate
+   sdods lint -p <project>
+   sdods run -p <project> -e <env> --list          # shows the run targets that would run
    ```
 2. Run the requested slice. Typical combinations:
    ```bash
-   bun run sdods run -p <project> -e <env> -l api                                  # API only, no browser
-   bun run sdods run -p <project> -e <env> -l ui -b chromium -t @smoke             # quick UI smoke
-   bun run sdods run -p <project> -e <env> -t @regression --project-matrix         # every browser in the yaml
-   bun run sdods run -p <project> -e <env> -t "@user:admin"                        # scenarios that lease admin users
-   bun run sdods run -p <project> -e <env> -l hybrid -w 2                          # API→UI chaining
-   bun run sdods run -p <project> -e <env> --har-replay --strict -t @smoke         # offline, CI-style
+   sdods run -p <project> -e <env> -l api                                  # API only, no browser
+   sdods run -p <project> -e <env> -l ui -b chromium -t @smoke             # quick UI smoke
+   sdods run -p <project> -e <env> -t @regression --project-matrix         # every browser in the yaml
+   sdods run -p <project> -e <env> -t "@user:admin"                        # scenarios that lease admin users
+   sdods run -p <project> -e <env> -l hybrid -w 2                          # API→UI chaining
+   sdods run -p <project> -e <env> --har-replay --strict -t @smoke         # offline, CI-style
    ```
 3. Read results:
    ```bash
-   bun run sdods report --last                    # summary: totals, failed, flaky, report paths
-   bun run sdods report --last --open             # HTML report + dashboard
-   bun run sdods heal report --last               # locators that were healed
+   sdods report --last                    # summary: totals, failed, flaky, report paths
+   sdods report --last --open             # HTML report + dashboard
+   sdods heal report --last               # locators that were healed
    ```
    Artifacts: `.sdods/runs/<runId>/<project>/<fingerprint>/r<retry>/` holds `scenario-start.png`, `NN-before.png`/`NN-after.png` per UI step (policy by suite tag), `api/*.json` per API call, `heal.jsonl`.
-4. If something failed, collect: the scenario name, the error from `summary.json`, the `failure.png`, and the trace (`bun run sdods trace --last`). Then either fix the feature/page object or hand it to the healer agent:
+4. If something failed, collect: the scenario name, the error from `summary.json`, the `failure.png`, and the trace (`sdods trace --last`). Then either fix the feature/page object or hand it to the healer agent:
    ```bash
-   bun run sdods agent heal -p <project> --scenario <fingerprint> --dry-run
+   sdods agent heal -p <project> --scenario <fingerprint> --dry-run
    ```
 5. Repeat for other environments or roles by changing `-e` / `-t "@user:<role>"` only.