@platless/axom-cli 0.1.0

package/dist/workstation/update/watchdog.js

@@ -0,0 +1,311 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, promises as fs } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+export const RESTART_READY_TIMEOUT_MS = 120_000;
+const MARKER_FILE = 'restart-ready.json';
+/** The npm package this running binary was installed from. Never the retired `axom-workstation`. */
+const PACKAGE_NAME = '@platless/axom-cli';
+function safeId(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function updateDirectory(configDir) { return path.join(configDir, 'update'); }
+export function readinessMarkerPath(configDir) { return path.join(updateDirectory(configDir), MARKER_FILE); }
+async function atomicWrite(file, value) {
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.writeFile(temporary, value, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await fs.chmod(temporary, 0o600);
+        await fs.rename(temporary, file);
+        await fs.chmod(file, 0o600);
+    }
+    catch (error) {
+        await fs.rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+/** Writes evidence from a successfully encrypted management generation, never from a browser. */
+export async function writeReadinessMarker(configDir, record) {
+    if (!record.commandId || !record.version || !record.generation)
+        throw new Error('Readiness marker requires command, version, and generation');
+    const marker = readinessMarkerPath(configDir);
+    await atomicWrite(marker, `${JSON.stringify(record)}\n`);
+    return marker;
+}
+async function isReady(marker, commandId, targetVersion) {
+    try {
+        const value = JSON.parse(await fs.readFile(marker, 'utf8'));
+        return typeof value === 'object' && value !== null
+            && value.commandId === commandId
+            && value.version === targetVersion
+            && typeof value.generation === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+/**
+ * A watchdog process has exactly one recovery transition. A successful readiness record returns;
+ * otherwise it installs the immutable last-known-good archive once and persists the final result.
+ */
+export async function runWatchdog(options) {
+    const now = options.now ?? Date.now;
+    const wait = options.wait ?? delay;
+    const deadline = now() + RESTART_READY_TIMEOUT_MS;
+    while (now() < deadline) {
+        if (await isReady(options.marker, options.commandId, options.targetVersion))
+            return;
+        await wait(Math.min(1_000, Math.max(1, deadline - now())));
+    }
+    if (await isReady(options.marker, options.commandId, options.targetVersion))
+        return;
+    const priorError = (await options.loadState?.().catch(() => null))?.error;
+    const fail = (error) => options.saveState({
+        phase: 'FAILED', commandId: options.commandId, version: options.targetVersion, error,
+    }).catch(() => undefined);
+    try {
+        await options.install(options.archive);
+    }
+    catch (error) {
+        // Nothing was restored, so there is nothing to restart into either: this is the one case the
+        // words "Rollback failed" actually describe.
+        await fail(`Rollback failed: ${describe(error).slice(0, 512)}`);
+        return;
+    }
+    await options.saveState({ phase: 'ROLLED_BACK', commandId: options.commandId, version: options.targetVersion });
+    try {
+        await options.restart?.();
+    }
+    catch (error) {
+        // The package *is* rolled back; only putting it back under supervision failed. Calling that a
+        // failed rollback -- and overwriting the update's own error with a bare service-manager exit
+        // code -- is how `Rollback failed: service restart failed with exit 113` became the only thing
+        // two stranded workstations had to say for themselves.
+        await fail(rollbackRestartFailure(options.targetVersion, error, priorError));
+    }
+}
+const describe = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * The sentence that names the repair for a workstation whose service registration is gone. Shared
+ * with `runUpdate.ts`'s provisioning failure (which imports it) because it is the same end state
+ * reached from either side, and a machine nobody can restart deserves one wording, not two.
+ */
+export const SERVICE_UNREGISTERED_REMEDIATION = 'The workstation service may no longer be registered with the OS service manager, in which case '
+    + 'nothing will restart it. Run `axom workstation install` on this machine to restore it.';
+function rollbackRestartFailure(version, error, priorError) {
+    const original = priorError ? ` The update itself failed with: ${priorError}` : '';
+    return `Rolled back to ${version}, but the service could not be restarted: ${describe(error)}. `
+        .concat(SERVICE_UNREGISTERED_REMEDIATION, original)
+        .slice(0, 512);
+}
+/**
+ * Copies the executable watchdog out of the npm package before replacement, then starts it as an
+ * independent process. The staged plan contains only private local paths and no bearer material.
+ */
+export async function stageWatchdog(command, lastKnownGood, service, deps = {}) {
+    const staged = await prepareWatchdog(command, lastKnownGood, service, deps);
+    staged.arm();
+    return { program: staged.program, plan: staged.plan };
+}
+async function prepareWatchdog(command, lastKnownGood, service, deps = {}) {
+    const directory = updateDirectory(service.configDir);
+    const program = path.join(directory, 'watchdog.mjs');
+    const plan = path.join(directory, `watchdog-${safeId(command.commandId)}.json`);
+    const source = deps.source ?? fileURLToPath(import.meta.url);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    await fs.copyFile(source, program);
+    await fs.chmod(program, 0o700);
+    const value = {
+        commandId: command.commandId, targetVersion: command.release.version, archive: lastKnownGood,
+        marker: readinessMarkerPath(service.configDir), state: path.join(service.configDir, 'update-state.json'),
+        npmPath: service.npmPath, npmPrefix: service.npmPrefix, cliPath: service.cliPath,
+    };
+    await atomicWrite(plan, `${JSON.stringify(value)}\n`);
+    return {
+        program, plan,
+        arm: () => {
+            const child = (deps.spawn ?? ((exe, args, options) => nodeSpawn(exe, args, options)))(service.nodePath, [program, plan], {
+                detached: true, shell: false, stdio: 'ignore',
+            });
+            child?.unref?.();
+        },
+    };
+}
+/**
+ * Maintains the one archive allowed to roll the daemon back. A cache entry is reusable only when
+ * it was packed from this running package version; metadata is checked before npm can mutate it.
+ */
+export class LastKnownGoodCache {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get clientVersion() { return this.options.runningVersion; }
+    async prepare(command) {
+        const directory = path.join(updateDirectory(this.options.configDir), 'last-known-good');
+        const archive = await this.ensureArchive(directory);
+        const watchdog = await prepareWatchdog(command, archive, this.options, this.options);
+        return {
+            arm: async () => watchdog.arm(),
+            // An npm install failure happens while the old daemon is still alive. Restore synchronously
+            // here instead of arming a second watchdog, so no later timer can roll back twice.
+            restore: async () => npmInstall(this.options.npmPath, this.options.npmPrefix, archive),
+        };
+    }
+    /**
+     * A current-version release is already authenticated by management. Download it only in the
+     * background, then independently hash the cached bytes before atomically publishing metadata.
+     */
+    async promoteAuthenticatedRelease(release) {
+        if (release.version !== this.options.runningVersion || !this.options.download)
+            return;
+        const directory = path.join(updateDirectory(this.options.configDir), 'last-known-good');
+        const archive = path.join(directory, 'last-known-good.tgz');
+        if (await this.matchesCache(archive, path.join(directory, 'last-known-good.json'), release.version, release.sha512))
+            return;
+        const downloaded = await this.options.download(release);
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+        const temporary = path.join(directory, `.release-${process.pid}-${Date.now()}.tgz`);
+        try {
+            await fs.copyFile(downloaded.path, temporary);
+            if (await sha512(temporary) !== release.sha512.toLowerCase())
+                throw new Error('Authenticated release cache digest changed while promoting');
+            await fs.rename(temporary, archive);
+            await atomicWrite(path.join(directory, 'last-known-good.json'), `${JSON.stringify({ name: PACKAGE_NAME, version: release.version, sha512: release.sha512.toLowerCase() })}\n`);
+        }
+        finally {
+            await fs.rm(temporary, { force: true }).catch(() => undefined);
+            await downloaded.cleanup().catch(() => undefined);
+        }
+    }
+    async ensureArchive(directory) {
+        const archive = path.join(directory, 'last-known-good.tgz');
+        const metadata = path.join(directory, 'last-known-good.json');
+        try {
+            const saved = JSON.parse(await fs.readFile(metadata, 'utf8'));
+            await fs.access(archive);
+            if (await this.matchesCache(archive, metadata, this.options.runningVersion))
+                return archive;
+        }
+        catch { /* cache missing/corrupt: repack below */ }
+        const staging = path.join(directory, `.pack-${process.pid}-${Date.now()}`);
+        await fs.mkdir(staging, { recursive: true, mode: 0o700 });
+        try {
+            const packed = await this.options.pack(this.options.packageRoot, staging);
+            if (packed.name !== PACKAGE_NAME || packed.version !== this.options.runningVersion) {
+                throw new Error(`Refusing last-known-good package ${packed.name}@${packed.version}; expected ${PACKAGE_NAME}@${this.options.runningVersion}`);
+            }
+            if (!path.isAbsolute(packed.path) || path.dirname(packed.path) !== staging)
+                throw new Error('npm pack returned an unsafe archive path');
+            await fs.rename(packed.path, archive);
+            await atomicWrite(metadata, `${JSON.stringify({ name: packed.name, version: packed.version, sha512: await sha512(archive) })}\n`);
+            return archive;
+        }
+        finally {
+            await fs.rm(staging, { recursive: true, force: true }).catch(() => undefined);
+        }
+    }
+    async matchesCache(archive, metadata, version, expectedSha512) {
+        try {
+            const saved = JSON.parse(await fs.readFile(metadata, 'utf8'));
+            if (typeof saved !== 'object' || saved === null
+                || saved.name !== PACKAGE_NAME
+                || saved.version !== version
+                || typeof saved.sha512 !== 'string')
+                return false;
+            const digest = await sha512(archive);
+            const declared = saved.sha512.toLowerCase();
+            return digest === declared && (!expectedSha512 || digest === expectedSha512.toLowerCase());
+        }
+        catch {
+            return false;
+        }
+    }
+}
+async function sha512(file) {
+    const hash = createHash('sha512');
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(file);
+        stream.on('data', (chunk) => { hash.update(chunk); });
+        stream.once('error', reject);
+        stream.once('end', resolve);
+    });
+    return hash.digest('hex');
+}
+async function npmInstall(npmPath, npmPrefix, archive) {
+    await new Promise((resolve, reject) => {
+        // Same as NpmInstaller: no `--prefix`, so a rollback lands where the forward install did.
+        const child = nodeSpawn(npmPath, ['install', '--global', archive, '--ignore-scripts', '--no-audit', '--no-fund'], { shell: false, stdio: 'ignore' });
+        child.once('error', reject);
+        child.once('close', (code) => code === 0 ? resolve() : reject(new Error(`npm rollback failed with exit ${code ?? 'unknown'}`)));
+    });
+}
+/** How much of the child's own complaint is worth carrying into a 512-character status field. */
+const CAPTURED_STDERR_LIMIT = 300;
+async function defaultServiceRunner(command, args) {
+    await new Promise((resolve, reject) => {
+        // Not `stdio: 'ignore'`. This runs in a detached process whose only way of reporting anything
+        // is the status file, so discarding the child's stderr left a bare exit code standing in for a
+        // diagnosis -- which is precisely what `exit 113` was.
+        const child = nodeSpawn(command, args, { shell: false, stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            if (stderr.length < CAPTURED_STDERR_LIMIT)
+                stderr += String(chunk);
+        });
+        child.once('error', reject);
+        child.once('close', (code) => {
+            if (code === 0)
+                return resolve();
+            const said = stderr.trim().replace(/\s+/g, ' ').slice(0, CAPTURED_STDERR_LIMIT);
+            reject(new Error(`\`${path.basename(command)} ${args.slice(1).join(' ')}\` failed with exit ${code ?? 'unknown'}${said ? `: ${said}` : ''}`));
+        });
+    });
+}
+/** The subcommand a rollback re-provisions with; the same one a person is told to run by hand. */
+export const REPROVISION_ARGV = ['workstation', 'install'];
+/**
+ * Puts the rolled-back client back under service supervision.
+ *
+ * Deliberately **not** `launchctl kickstart` / `systemctl restart`, which was the previous
+ * behaviour and could not work in the very situation this watchdog exists for. Provisioning boots
+ * the old job out *before* bootstrapping its replacement, so an update that dies in between leaves
+ * the machine with no registered service at all -- and kickstarting a job the service manager does
+ * not have answers 113, "Could not find specified service", by construction. Both production
+ * workstations recorded exactly that, one after the other.
+ *
+ * Re-running the installed package's own `workstation install` is correct in both end states: it
+ * kickstarts a job that is still registered and bootstraps one that is not, it already carries the
+ * hardened launchd transition handling (see `service/installer.ts`), and it works out the platform
+ * for itself -- so the plan no longer has to carry one. By this point npm has restored the
+ * last-known-good package, so [cliPath] is the *rolled-back* CLI, which is the one we want to run.
+ *
+ * It is intentionally unbounded. `install` performs no network or npm work, its launchd retries are
+ * already bounded, and killing it part-way through a `bootstrap` is itself how a machine loses its
+ * service definition -- the same reason `runUpdate.ts` refuses to kill the provisioning child it
+ * gives up waiting on.
+ */
+export async function reprovisionManagedService(nodePath, cliPath, run = defaultServiceRunner) {
+    await run(nodePath, [cliPath, ...REPROVISION_ARGV]);
+}
+async function main() {
+    const planPath = process.argv[2];
+    if (!planPath)
+        return;
+    const plan = JSON.parse(await fs.readFile(planPath, 'utf8'));
+    await runWatchdog({
+        ...plan,
+        install: (archive) => npmInstall(plan.npmPath, plan.npmPrefix, archive),
+        saveState: async (status) => atomicWrite(plan.state, `${JSON.stringify(status)}\n`),
+        loadState: async () => JSON.parse(await fs.readFile(plan.state, 'utf8')),
+        // `process.execPath` is the node the daemon armed this watchdog with, which is the node the
+        // service definition itself runs -- never a `node` resolved from this process's PATH.
+        restart: () => reprovisionManagedService(process.execPath, plan.cliPath),
+    });
+}
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+    void main().catch(() => process.exitCode = 1);
+}

package/dist/workstation/version.js

@@ -0,0 +1,12 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const packageMetadata = require('../../package.json');
+/** Read once at process load from the installed npm package, never duplicated in source. */
+export const CLIENT_VERSION = packageMetadata.version;
+/**
+ * This package's own npm name, read from the same package.json as CLIENT_VERSION.
+ *
+ * Sent as the required `clientPackage` field on `management_hello` so the server can tell which
+ * npm package a connected workstation is running.
+ */
+export const CLIENT_PACKAGE_NAME = packageMetadata.name;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@platless/axom-cli",
+  "version": "0.1.0",
+  "description": "Axomwork CLI - manage Axomwork structures, records and executions over MCP",
+  "type": "module",
+  "bin": {
+    "axom": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.4.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@napi-rs/keyring": "^1.1.3",
+    "commander": "^15.0.0",
+    "js-yaml": "^4.1.0",
+    "semver": "^7.8.5",
+    "ws": "^8.18.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "@types/semver": "^7.8.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.2.2",
+    "vitest": "^2.1.9"
+  }
+}

package/skills/axom/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: axom
+description: "Work with Axomwork applications: inspect structures, query and mutate records, execute operations and services via Axomwork MCP tools"
+---
+
+# Axomwork
+
+Use this skill when an Axomwork MCP server is connected and you need to inspect application structure, read or change business records, or execute model operations and services.
+
+## Workflow
+
+Start by discovering structure before changing records. Use `axom__struct__list_applications()` to find applications, then `axom__struct__get_model({ applicationName, modelName })` to inspect fields, operations, and record shape. Only then query, create, update, delete, upsert, or execute.
+
+## Core Tools
+
+- `axom__system__whoami()` - returns the current authenticated user and role.
+- `axom__struct__list_applications()` - lists available applications.
+- `axom__struct__get_application({ applicationName })` - reads one application definition.
+- `axom__struct__list_models({ applicationName })` - lists models in an application.
+- `axom__struct__get_model({ applicationName, modelName })` - reads one model definition, including attributes and operations.
+- `axom__record__query({ applicationName, modelName, criteria?, page? })` - queries records using REST-compatible filters and sorts in `criteria`.
+- `axom__record__get({ applicationName, modelName, id })` - reads one record by id.
+- `axom__record__create({ applicationName, modelName, record })` - creates a record; `record` contains model field values.
+- `axom__record__update({ applicationName, modelName, id, changes })` - updates one record; `changes` contains only the fields to modify.
+- `axom__record__upsert({ applicationName, modelName, identityField, record })` - creates or updates a record matched by `identityField`; `record` must include that field. The model must declare a `unique` validation on `identityField`, or the call throws — check `get_model` for that before calling upsert on an unfamiliar model.
+- `axom__record__delete({ applicationName, modelName, id })` - deletes one record by id.
+- `axom__operation__execute({ applicationName, modelName, operationName, input })` - executes a model operation and waits for the result. Use `axom__operation__execute_async` with the same arguments when asynchronous continuation is intended; it returns a running status and a child run id.
+- `axom__service__execute({ applicationName?, serviceName, input })` - executes a reusable platform or application-scoped service, with `axom__service__execute_async` as its non-waiting counterpart.
+
+## Query Criteria
+
+For the complete filter, sort, and page contract, load guide
+`agent-integration/mcp/record-query-criteria.md` with `axom__guide__load`.
+
+Pass filters and sorts inside `criteria`, with `page` as a separate top-level field:
+
+```json
+{
+  "applicationName": "demo",
+  "modelName": "Article",
+  "criteria": {
+    "filters": [{"op":"eq","field":"status","value":"active"}],
+    "sorts": [{"field":"createdAt","direction":"DESC"}]
+  },
+  "page": {"number":1,"size":20}
+}
+```
+
+Filter `op` values are `eq|gt|lt|like|in|and|or`. Use nested `filters` for `and` and `or`; use `values` for `in`. Page `size` must be one of `20`, `50`, or `100`.
+
+## Upserting a Record
+
+Use `axom__record__upsert` when a stable external identifier should select an existing record or create a new one. Supply the canonical fields in this order, and include the identity value inside `record`:
+For create/update/upsert safety, load guide
+`agent-integration/operating-patterns/safe-record-mutations.md`; before deletion, load
+`agent-integration/operating-patterns/destructive-actions.md`.
+
+```json
+{
+  "applicationName": "demo",
+  "modelName": "Task",
+  "identityField": "externalId",
+  "record": {
+    "externalId": "task-42",
+    "title": "Reconcile invoices"
+  }
+}
+```
+
+## Execution Results
+
+`axom__operation__execute` and `axom__service__execute` return an OperationResult-style payload. Interpret `success` as the primary outcome, `text` as user-facing output, `data` as structured result data, `message` as diagnostic detail, `processing` as whether work continues asynchronously, and `runId` as the related run identifier when one is started.
+For asynchronous continuation, load guides
+`concepts/execution/synchronous-and-task-execution.md` and
+`agent-integration/operating-patterns/following-runs.md`.
+
+## Guide
+
+Axomwork ships an AI-first manual. Call `axom__guide__load` with no arguments for the table of
+contents, `axom__guide__load` with `path` (e.g. `script-language/sdk/records.md`) for one page, and
+`axom__guide__search` with `query` for ranked snippets. Guide references omit the locale and include
+`.md`, for example `script-language/sdk/records.md`. When a tool description references a guide
+path, load that page first.

package/skills/axom-definition/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: axom-definition
+description: "Develop Axomwork application definitions with independently callable canonical definition MCP tools (admin role required)"
+---
+
+# Axomwork Definition
+
+Use this skill to edit application definitions with the canonical `axom__definition__*` MCP tools. These tools require an ADMIN token. Check `tools/list` for the specific tool before calling it.
+
+Call each tool directly with camelCase arguments:
+
+```json
+{"applicationName":"demo","modelName":"Article"}
+```
+
+## ETag workflow
+
+Read the target resource or its list before a mutation, then send the returned `etag` as `expectedEtag`. Body updates use `expectedBodyEtag`. If a conflict occurs, reread the resource, merge intentionally, and retry. Confirm delete actions with the user.
+Load guides `agent-integration/operating-patterns/etag-write-workflow.md` and
+`agent-integration/operating-patterns/destructive-actions.md` for the complete safety contract.
+
+## Applications
+
+- `axom__definition__list_applications`
+- `axom__definition__get_application` — `applicationName`
+- `axom__definition__create_application` — `application`, `expectedEtag`
+- `axom__definition__update_application` — `applicationName`, `application`, `expectedEtag`
+- `axom__definition__delete_application` — `applicationName`, `expectedEtag`
+
+## Models
+
+- `axom__definition__list_models` — `applicationName`
+- `axom__definition__get_model` — `applicationName`, `modelName`
+- `axom__definition__create_model` — `applicationName`, `model`, `expectedEtag`
+- `axom__definition__update_model` — `applicationName`, `modelName`, `model`, `expectedEtag`
+- `axom__definition__delete_model` — `applicationName`, `modelName`, `expectedEtag`
+
+## Attributes and operations
+
+- `axom__definition__get_attribute` — `applicationName`, `modelName`, `attributeName`
+- `axom__definition__create_attribute` — `applicationName`, `modelName`, `attribute`, `expectedEtag`
+- `axom__definition__update_attribute` — `applicationName`, `modelName`, `attributeName`, `attribute`, `expectedEtag`
+- `axom__definition__delete_attribute` — `applicationName`, `modelName`, `attributeName`, `expectedEtag`
+- `axom__definition__get_operation` — `applicationName`, `modelName`, `operationName`
+- `axom__definition__create_operation` — `applicationName`, `modelName`, `operation`, `expectedEtag`
+- `axom__definition__update_operation` — `applicationName`, `modelName`, `operationName`, `operation`, `expectedEtag`
+- `axom__definition__delete_operation` — `applicationName`, `modelName`, `operationName`, `expectedEtag`
+- `axom__definition__get_operation_body` — `applicationName`, `modelName`, `operationName`
+- `axom__definition__update_operation_body` — `applicationName`, `modelName`, `operationName`, `content`, `expectedBodyEtag`
+
+## Triggers and lifecycle
+
+- `axom__definition__update_triggers` — `applicationName`, `modelName`, `triggers`, `expectedEtag`
+- `axom__definition__get_lifecycle` — `applicationName`, `modelName`
+- `axom__definition__update_lifecycle` — `applicationName`, `modelName`, `lifecycle`, `expectedEtag`
+- `axom__definition__delete_lifecycle` — `applicationName`, `modelName`, `expectedEtag`
+
+## Workflows
+
+- `axom__definition__list_workflows` — `applicationName`, `modelName`
+- `axom__definition__get_workflow` — `applicationName`, `modelName`, `workflowName`
+- `axom__definition__create_workflow` — `applicationName`, `modelName`, `workflow`, `expectedEtag`
+- `axom__definition__update_workflow` — `applicationName`, `modelName`, `workflowName`, `workflow`, `expectedEtag`
+- `axom__definition__delete_workflow` — `applicationName`, `modelName`, `workflowName`, `expectedEtag`
+- `axom__definition__get_workflow_body` — `applicationName`, `modelName`, `workflowName`
+- `axom__definition__update_workflow_body` — `applicationName`, `modelName`, `workflowName`, `content`, `expectedBodyEtag`
+
+## Guide
+
+Before authoring `.axom.kts` bodies, load the relevant guide pages with `axom__guide__load`:
+`script-language/sdk/index.md` (script SDK),
+`script-language/workflows/workflow-script.md` (workflow DSL),
+`script-language/patterns/index.md` (sync/task/streaming patterns), and
+`application-development/index.md` (definition semantics).

package/skills/axom-platform/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: axom-platform
+description: "Operate Axomwork platform configuration with independently callable canonical operations MCP tools (admin role required)"
+---
+
+# Axomwork Platform
+
+Use the canonical `axom__platform__*` MCP tools (platform skills, AI configuration, cowork agents, data sources, and platform settings). These tools require an ADMIN token. Check `tools/list` for the specific tool before calling it.
+
+Call each tool directly with camelCase arguments:
+
+```json
+{"dataSourceName":"analytics","expectedEtag":"current-etag"}
+```
+
+## ETag workflow
+
+Read the target resource or list before a mutation, then send its `etag` as `expectedEtag`. Prompt and workflow-body updates use `expectedBodyEtag`. On conflict, reread and merge intentionally. Confirm delete actions with the user. Report the returned `requiresRestart` value for every datasource or settings mutation.
+For the full concurrency workflow, load guide
+`agent-integration/operating-patterns/etag-write-workflow.md`.
+
+## Platform skills
+
+- `axom__platform__list_skills`
+- `axom__platform__get_skill`
+- `axom__platform__create_skill`
+- `axom__platform__update_skill`
+- `axom__platform__delete_skill`
+
+## AI configuration
+
+- `axom__platform__get_ai_config`
+- `axom__platform__upsert_ai_vendor`
+- `axom__platform__delete_ai_vendor`
+- `axom__platform__upsert_ai_profile`
+- `axom__platform__delete_ai_profile`
+- `axom__platform__update_ai_memory`
+
+## Cowork agents
+
+- `axom__platform__list_cowork_agents`
+- `axom__platform__get_cowork_agent`
+- `axom__platform__create_cowork_agent`
+- `axom__platform__update_cowork_agent`
+- `axom__platform__delete_cowork_agent`
+- `axom__platform__get_cowork_agent_prompt`
+- `axom__platform__update_cowork_agent_prompt`
+- `axom__platform__list_cowork_agent_skills`
+- `axom__platform__get_cowork_agent_skill`
+- `axom__platform__create_cowork_agent_skill`
+- `axom__platform__update_cowork_agent_skill`
+- `axom__platform__delete_cowork_agent_skill`
+- `axom__platform__list_cowork_agent_workflows`
+- `axom__platform__get_cowork_agent_workflow`
+- `axom__platform__create_cowork_agent_workflow`
+- `axom__platform__update_cowork_agent_workflow`
+- `axom__platform__delete_cowork_agent_workflow`
+- `axom__platform__get_cowork_agent_workflow_body`
+- `axom__platform__update_cowork_agent_workflow_body`
+
+## Datasources and platform settings
+
+- `axom__platform__list_data_sources`
+- `axom__platform__get_data_source`
+- `axom__platform__create_data_source`
+- `axom__platform__update_data_source`
+- `axom__platform__delete_data_source`
+- `axom__platform__get_settings`
+- `axom__platform__update_settings`
+
+## Guide
+
+Before editing, load the matching guide with `axom__guide__load`:
+`platform-operations/ai-vendors-and-profiles.md`,
+`platform-operations/cowork-agent-configuration.md`,
+`platform-operations/datasource-configuration.md`,
+`platform-operations/service-configuration.md`, or
+`platform-operations/platform-skills.md`.