@amalgm/automations 0.4.0 → 0.4.1

package/AXIOMS.md

@@ -91,7 +91,8 @@
 33. MCP and CLI project one task-level command catalog: create, list, get,
     update, delete, and run-now. Command names, input schemas, and invocation
     behavior are defined once and neither adapter invents resource-level
-    lifecycle operations.
+    lifecycle operations. Unknown configuration fields are rejected, never
+    discarded by an adapter; declared JSON payloads remain open data.
 34. A CLI running for a signed-in user reaches Automations through Shell's
     authenticated loopback MCP route. It may possess the local runtime admission
     token, but never a durable machine credential, device key, cached access
@@ -140,3 +141,6 @@
     for that user and machine; a notification is never proof of execution.
 48. Losing upstream notification coverage closes downstream streams, and every
     reconnect checks retained work before becoming idle again.
+49. A complete definition validates all supplied configuration before its
+    first write; a later service failure preserves an identifiable disabled
+    draft and the original failure code.

package/PURPOSE.md

@@ -36,6 +36,12 @@ the run ledger. Reconnecting re-establishes notification coverage before checkin
 the ledger. Connection health and active execution leases have bounded timers;
 idle machines have no periodic work-claim timer.
 
+Complete create and update requests validate their supplied schedules, workflow
+plans, and field names before writing configuration. Unknown fields cannot
+silently become a different request. If a service fails after staging begins,
+the disabled draft remains inspectable and the error keeps that service's code,
+so the agent can repair the same definition rather than repeat its creation.
+
 The agent CLI is the command-line projection of the same task-level command
 surface as MCP: create, list, get, update, delete, and run-now. Each command
 accepts the same JSON object as its corresponding MCP tool and returns the same
@@ -56,6 +62,12 @@ the user reach aayush@amalgm.ai with bounded, redacted diagnostic evidence when
 the failing boundary cannot be repaired. The packaged skill is the source for
 installed copies and public setup/support guidance.
 
+The standalone service publishes a public skill discovery index and an
+integrity-checked archive built from that same packaged skill. Installation
+needs no private repository access, and the archive includes its referenced
+instructions. Public distribution owns no copy of authentication or workflow
+behavior.
+
 The CLI is global configuration control, not directory-local state. The agent
 or person creating an automation may invoke it from any directory; the selected
 machine and the persisted workflow decide where effects occur later. A process

package/README.md

@@ -98,15 +98,32 @@ one JSON line on stderr shaped as
 `status`, and exits nonzero. Use `--stdin` for inputs containing credentials;
 `--input` and `--file` are also supported.
 
-When Shell invokes the adapter, it supplies `AMALGM_MCP_URL` and
-`AMALGM_RUNTIME_TOKEN` from its running user runtime. The CLI sends that
-runtime token only to the loopback `/mcp/automations` route. Shell retains the
+Shell supplies the selected running user's loopback connection directly to
+the SDK adapter. The CLI sends its runtime token only to the loopback
+`/mcp/automations` route. Shell retains the
 durable machine credential and device key and creates the short-lived access
 token and fresh DPoP proof for the hosted request. For transition
 compatibility, the standalone entry point still accepts the prior paired
 `AMALGM_AUTOMATIONS_API_URL` and `AMALGM_AUTOMATIONS_AUTHORIZATION`
 environment variables.
 
+For public local MCP clients, Shell 0.1.176+ provides
+`amalgm automations mcp --user person@example.com`. It exposes the same six
+tools over stdio and discovers the current runtime connection per call.
+`amalgm status --all` lists local account registrations. No pasted token or
+private repository access is part of either flow; the standalone
+`amalgm-automations-mcp` entry point remains for custom authenticated hosts.
+
+Install the complete portable skill with Node.js 22.20+:
+
+```bash
+npx skills add https://automations.amalgm.ai --skill amalgm-automations
+```
+
+The host serves standard discovery at `/.well-known/agent-skills/index.json`
+and a checksum-addressed archive built from `skills/amalgm-automations`.
+The archive includes its references and agent metadata and requires no login.
+
 The hosted service accepts verified Supabase user sessions for browser control
 and Core-issued `amalgm-automations` DPoP grants for Shell. It does not run in
 or depend on Amalgm Gateway.

package/dist/host/main.js

@@ -14,6 +14,7 @@ import { automationsHostConfig } from './config.js';
 import { createAutomationsHost } from './server.js';
 import { createMachineRunNotifications } from '../src/machine-notifications.js';
 import { subscribeToRunChanges } from './notifications.js';
+import { createPublicSkillApi } from './skill.js';
 const config = automationsHostConfig();
 const supabase = createClient(config.supabaseUrl, config.supabaseServiceRoleKey, {
     auth: { persistSession: false, autoRefreshToken: false },
@@ -48,6 +49,7 @@ const host = createAutomationsHost({
     controlApi,
     machineApi,
     eventsApi,
+    publicSkillApi: createPublicSkillApi(),
     fireSchedules: () => delivery.fireDueCrons(),
     schedulerIntervalMs: config.schedulerIntervalMs,
     log,

package/dist/host/server.d.ts

@@ -4,6 +4,7 @@ export declare function createAutomationsHost(options: {
     readonly controlApi: (request: Request) => Promise<Response>;
     readonly machineApi: (request: Request) => Promise<Response>;
     readonly eventsApi?: (request: Request) => Promise<Response>;
+    readonly publicSkillApi?: (request: Request) => Promise<Response>;
     readonly fireSchedules: () => Promise<unknown>;
     readonly schedulerIntervalMs: number;
     readonly maxRequestBodyBytes?: number;

package/dist/host/server.js

@@ -25,9 +25,11 @@ export function createAutomationsHost(options) {
                 return await send(outgoing, Response.json({ ok: true }), controller.signal);
             const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024, controller.signal);
             const pathname = new URL(request.url).pathname;
-            const api = pathname.startsWith('/e/') && options.eventsApi
-                ? options.eventsApi
-                : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
+            const api = pathname.startsWith('/.well-known/agent-skills/') && options.publicSkillApi
+                ? options.publicSkillApi
+                : pathname.startsWith('/e/') && options.eventsApi
+                    ? options.eventsApi
+                    : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
             await send(outgoing, await api(request), controller.signal);
         }
         catch (error) {

package/dist/host/skill.d.ts

@@ -0,0 +1,2 @@
+/** Only the two packaged public artifacts are addressable; no arbitrary file reads. */
+export declare function createPublicSkillApi(directory?: URL): (request: Request) => Promise<Response>;

package/dist/host/skill.js

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+const prefix = '/.well-known/agent-skills/';
+/** Only the two packaged public artifacts are addressable; no arbitrary file reads. */
+export function createPublicSkillApi(directory = new URL('../skills/', import.meta.url)) {
+    const index = readFileSync(new URL('index.json', directory));
+    const entry = JSON.parse(index.toString('utf8')).skills[0];
+    const filename = entry.url.replace(/^\.\//, '');
+    if (!/^amalgm-automations\.[a-f0-9]{64}\.tgz$/.test(filename))
+        throw new Error('Invalid skill artifact');
+    const files = new Map([
+        [`${prefix}index.json`, { bytes: index, type: 'application/json', cache: 'no-cache' }],
+        [`${prefix}${filename}`, {
+                bytes: readFileSync(new URL(filename, directory)), type: 'application/gzip',
+                cache: 'public, max-age=31536000, immutable',
+            }],
+    ]);
+    return async (request) => {
+        const file = files.get(new URL(request.url).pathname);
+        if (!file)
+            return new Response('Not found', { status: 404 });
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            return new Response('Method not allowed', { status: 405, headers: { allow: 'GET, HEAD' } });
+        }
+        return new Response(request.method === 'HEAD' ? null : new Uint8Array(file.bytes), {
+            headers: {
+                'content-type': file.type,
+                'content-length': String(file.bytes.byteLength),
+                'cache-control': file.cache,
+                'x-content-type-options': 'nosniff',
+            },
+        });
+    };
+}

package/dist/skills/index.json

@@ -0,0 +1 @@
+{"$schema":"https://schemas.agentskills.io/discovery/0.2.0/schema.json","skills":[{"name":"amalgm-automations","description":"Set up, operate, and troubleshoot Amalgm Automations through MCP or the amalgm automations CLI. Use for installation, Google sign-in, scheduled or webhook workflows, Run Now, run history, and Automations support.","type":"archive","url":"./amalgm-automations.5e4e14f0ace632c8383cd014e1f0f34b24ec0d5c5600132a840abc4c313b31d4.tgz","digest":"sha256:5e4e14f0ace632c8383cd014e1f0f34b24ec0d5c5600132a840abc4c313b31d4"}]}

package/dist/src/cli/run.d.ts

@@ -8,6 +8,6 @@ export interface AutomationCliIo extends AutomationCliInputPorts {
     stdout?: Output;
     stderr?: Output;
 }
-export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nSetup and support:\n  Already connected? Reuse the running Amalgm Shell.\n  First login: amalgm login --no-open\n    Open the printed link, sign in with Google, and approve this computer.\n    Keep the login process running; it hosts Shell after approval.\n  Check: amalgm status --user EMAIL\n  Resume a registered computer: amalgm run --user EMAIL\n  Verify access: amalgm automations list --user EMAIL --input '{\"limit\":1}'\n  No local installation? https://amalgm.ai/setup\n  Support: aayush@amalgm.ai\n  Never copy private connection credentials into a command or support email.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
+export declare const automationCliHelp = "amalgm automations \u2014 durable automation control for agents\n\nUsage:\n  amalgm automations <command> [--input JSON | --file PATH | --stdin]\n  amalgm-automations <command> [--input JSON | --file PATH | --stdin]\n\nCommands (identical to the Automations MCP task surface):\n  create    Create one complete definition\n  list      List the user's automations\n  get       Get one complete definition and optional run history\n  update    Apply grouped definition changes\n  delete    Delete current configuration; run history remains\n  run-now   Admit one durable manual run\n\nInput is one JSON object with the corresponding MCP tool's fields. Commands\nwithout options receive {}. Output is one JSON success or error envelope.\nUse --stdin when input contains credentials such as a webhook signing secret.\n\nSetup and support:\n  Already connected? Reuse the running Amalgm Shell.\n  First login: amalgm login --no-open\n    Open the printed link, sign in with Google, and approve this computer.\n    Keep the login process running; it hosts Shell after approval.\n  Check: amalgm status --user EMAIL\n  List local accounts: amalgm status --all\n  Resume a registered computer: amalgm run --user EMAIL\n  Verify access: amalgm automations list --user EMAIL --input '{\"limit\":1}'\n  No local installation? https://amalgm.ai/setup\n  Support: aayush@amalgm.ai\n  Never copy private connection credentials into a command or support email.\n\nExternal agent MCP setup (after Shell login):\n  amalgm automations mcp --user EMAIL\n  Configure your client to launch this stdio command. No credential fields.\n\nWorkflow step lanes:\n  version 1  action-only: {\"id\":\"...\",\"actionId\":\"product.action\",\"input\":{...}}\n  version 2  action, command, or script steps:\n    command  {\"id\":\"...\",\"kind\":\"command\",\"command\":\"codex\",\"args\":[\"exec\",\"...\"],\"cwd\":\"/absolute/path\"}\n    script   {\"id\":\"...\",\"kind\":\"script\",\"runtime\":\"shell|node|python\",\"source\":\"...\",\"cwd\":\"/absolute/path\"}\n";
 export declare function runAutomationCli(argv: string[], backend: AutomationCrud | AutomationCommands, io?: AutomationCliIo): Promise<number>;
 export {};

package/dist/src/cli/run.js

@@ -26,12 +26,17 @@ Setup and support:
     Open the printed link, sign in with Google, and approve this computer.
     Keep the login process running; it hosts Shell after approval.
   Check: amalgm status --user EMAIL
+  List local accounts: amalgm status --all
   Resume a registered computer: amalgm run --user EMAIL
   Verify access: amalgm automations list --user EMAIL --input '{"limit":1}'
   No local installation? https://amalgm.ai/setup
   Support: aayush@amalgm.ai
   Never copy private connection credentials into a command or support email.
 
+External agent MCP setup (after Shell login):
+  amalgm automations mcp --user EMAIL
+  Configure your client to launch this stdio command. No credential fields.
+
 Workflow step lanes:
   version 1  action-only: {"id":"...","actionId":"product.action","input":{...}}
   version 2  action, command, or script steps:

package/dist/src/crud/triggers.js

@@ -22,7 +22,6 @@ export function triggerOperations(context) {
                 await context.exists(automationId);
                 const parsed = parseCreateScheduleTrigger(input);
                 const timezone = parsed.timezone || 'UTC';
-                schedule(parsed.cron, timezone);
                 if (parsed.id)
                     await unique(automationId, parsed.id);
                 return repository.createScheduleTrigger(principal.userId, automationId, {

package/dist/src/mcp.d.ts

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type AutomationCommands } from './command-surface.js';
 import type { AutomationCrud } from './contract.js';
 import { createAutomationToolSurface } from './tool-surface.js';
 export { createAutomationToolSurface };
 export type { AutomationToolSurface, AutomationView, CreateAutomationDefinition, UpdateAutomationDefinition, WorkflowChange, } from './tool-surface.js';
-export declare function createAutomationMcpServer(sdk: AutomationCrud): McpServer;
+export declare function createAutomationMcpServer(sdk: AutomationCrud | AutomationCommands): McpServer;

package/dist/src/mcp.js

@@ -14,7 +14,7 @@ const resultSchema = {
 };
 export function createAutomationMcpServer(sdk) {
     const server = new McpServer({ name: 'amalgm-automations-mcp-server', version: '0.1.0' });
-    const commands = createAutomationCommands(sdk);
+    const commands = 'execute' in sdk ? sdk : createAutomationCommands(sdk);
     for (const definition of automationCommandDefinitions)
         register(server, commands, definition);
     return server;
@@ -23,7 +23,9 @@ function register(server, commands, definition) {
     server.registerTool(definition.mcpName, {
         title: definition.title,
         description: definition.description,
-        inputSchema: definition.inputShape,
+        // Forward unknown top-level fields to the SDK's strict parser. The MCP
+        // SDK's default object parser strips them before our command sees them.
+        inputSchema: z.object(definition.inputShape).passthrough(),
         outputSchema: resultSchema,
         annotations: definition.annotations,
     }, async (input) => {

package/dist/src/schema.js

@@ -1,7 +1,7 @@
 import { z } from 'zod/v3';
 import { ValidationError } from './errors.js';
 import { compiledAutomationPlan } from './plan.js';
-import { IDENTIFIER } from './validation.js';
+import { IDENTIFIER, schedule } from './validation.js';
 const maxPageSize = 100;
 const identifierMessage = 'Identifier is invalid';
 const text = (maximum, label) => z.string()
@@ -96,10 +96,16 @@ export function parseListAutomations(value) {
     return parse(listAutomationsSchema, value);
 }
 export function parseCreateScheduleTrigger(value) {
-    return parse(createScheduleTriggerSchema, value);
+    const trigger = parse(createScheduleTriggerSchema, value);
+    schedule(trigger.cron, trigger.timezone ?? 'UTC');
+    return trigger;
 }
 export function parseUpdateScheduleTrigger(value) {
-    return parse(updateScheduleTriggerSchema, value);
+    const patch = parse(updateScheduleTriggerSchema, value);
+    if (patch.cron !== undefined || patch.timezone !== undefined) {
+        schedule(patch.cron ?? '* * * * *', patch.timezone ?? 'UTC');
+    }
+    return patch;
 }
 export function parseCreateWebhookTrigger(value) {
     return parse(createWebhookTriggerSchema, value);

package/dist/src/tool-surface.js

@@ -1,4 +1,5 @@
-import { NotFoundError, ValidationError } from './errors.js';
+import { AutomationError, NotFoundError, ValidationError } from './errors.js';
+import { parseCreateAutomation, parseCreateScheduleTrigger, parseCreateWebhookTrigger, parseCreateWorkflow, parseUpdateAutomation, parseUpdateScheduleTrigger, parseUpdateWebhookTrigger, parseUpdateWorkflow, } from './schema.js';
 export function createAutomationToolSurface(sdk) {
     const view = async (automationId, runs = false) => {
         const automation = await sdk.automations.get(automationId);
@@ -14,6 +15,11 @@ export function createAutomationToolSurface(sdk) {
     const surface = {
         async create(input) {
             const { schedules = [], webhooks = [], workflow, ...automationInput } = input;
+            parseCreateAutomation(automationInput);
+            schedules.forEach(parseCreateScheduleTrigger);
+            webhooks.forEach(parseCreateWebhookTrigger);
+            if (workflow)
+                parseCreateWorkflow(workflow);
             validateCreateIds(schedules, webhooks);
             const staged = schedules.length > 0 || webhooks.length > 0 || workflow !== undefined;
             const requestedEnabled = automationInput.enabled !== false;
@@ -40,6 +46,7 @@ export function createAutomationToolSurface(sdk) {
         get: view,
         async update(automationId, input) {
             requireChanges(input);
+            validateUpdate(input);
             validateChanges(input.schedules, 'schedule');
             validateChanges(input.webhooks, 'webhook');
             const current = await sdk.automations.get(automationId);
@@ -98,6 +105,18 @@ function requireChanges(input) {
         throw new ValidationError('Automation update must include a change');
     }
 }
+function validateUpdate(input) {
+    if (input.patch)
+        parseUpdateAutomation(input.patch);
+    input.schedules?.create?.forEach(parseCreateScheduleTrigger);
+    input.schedules?.update?.forEach(({ patch }) => parseUpdateScheduleTrigger(patch));
+    input.webhooks?.create?.forEach(parseCreateWebhookTrigger);
+    input.webhooks?.update?.forEach(({ patch }) => parseUpdateWebhookTrigger(patch));
+    if (input.workflow && 'create' in input.workflow)
+        parseCreateWorkflow(input.workflow.create);
+    if (input.workflow && 'update' in input.workflow)
+        parseUpdateWorkflow(input.workflow.update);
+}
 function hasChanges(changes) {
     return Boolean(changes && [changes.create, changes.update, changes.delete]
         .some((items) => items && items.length > 0));
@@ -122,5 +141,5 @@ function validateCreateIds(schedules, webhooks) {
 }
 function disabledDraftError(automationId, error) {
     const reason = error instanceof Error ? error.message : String(error);
-    return new Error(`Automation ${automationId} remains disabled because configuration failed: ${reason}`);
+    return new AutomationError(error instanceof AutomationError ? error.code : 'internal', `Automation ${automationId} remains disabled because configuration failed: ${reason}`, error instanceof AutomationError ? error.status : undefined);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/automations",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Amalgm's automation SDK: durable trigger admission and target-machine execution.",
   "license": "UNLICENSED",
   "repository": {
@@ -45,7 +45,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsx scripts/mark-executables.ts && tsx scripts/build-public-skill.ts",
     "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json --noEmit",
     "test": "tsx --test test/*.test.ts",
     "test:supabase": "tsx --test test/integration/postgres.test.ts",

package/skills/amalgm-automations/SKILL.md

@@ -72,13 +72,16 @@ input.
   complex source. Do not expose those values in command arguments or logs.
 - Delete only after the exact id is established and deletion is within the
   user's request. Deleting configuration intentionally retains run history.
+  Omit `id` when creating a new automation; explicitly reusing a deleted id
+  refers to the same logical identity and retains its history and retry keys.
 
 ## Build one complete definition
 
 Create the automation, its schedule/webhook triggers, and its optional workflow
-in one task-level call. The service stages multi-resource changes safely and
-enables the definition only after setup succeeds. If setup fails, report the
-returned disabled draft id rather than silently creating a replacement.
+in one task-level call. Invalid supplied configuration fails before any write.
+The service stages valid multi-resource changes and enables the definition
+only after setup succeeds. If a later service failure returns a disabled draft
+id, get and repair that draft with `update`; do not create a replacement.
 
 Use a finite `maxOccurrences` when the user's request is bounded. Do not turn
 "ten times" into an unbounded schedule plus a future cleanup promise.
@@ -102,7 +105,7 @@ executables through the selected machine; never guess either.
 not evidence that work completed.
 
 1. Supply a stable, caller-chosen `idempotency_key` whenever the request might
-   be retried.
+   be retried. Use a new key for each new logical run.
 2. If admission is retried, send the same automation id, input, and key. The
    returned run id must remain the same.
 3. Poll `get` with `include_runs: true` or a `run_query` until the admitted run

package/skills/amalgm-automations/references/command-contract.md

@@ -15,6 +15,8 @@ Failures use stderr, a nonzero exit, and:
 ```
 
 Do not scrape prose or infer success from exit code alone; parse the envelope.
+Unknown configuration fields are rejected. Arbitrary JSON inside workflow
+action input and Run Now input remains valid payload data.
 
 ## create
 
@@ -62,6 +64,11 @@ At least one executable step is required when `compiled` is supplied. Omit
 webhook URL is the provider destination; a configured signing secret is
 write-only on later reads.
 
+Omit `id` for a new automation. An explicit id names a persistent logical
+identity: deleting and recreating it retains that identity's run history and
+Run Now idempotency keys. Use a new key for each new logical run and reuse it
+only when retrying that run.
+
 CLI example:
 
 ```bash

package/skills/amalgm-automations/references/setup-and-support.md

@@ -5,6 +5,19 @@ an error. Use Shell's commands for setup and Automations reads to verify access.
 The agent handles the commands; the person chooses their Google account and
 approves connecting their computer in the browser.
 
+## Install this skill
+
+The public download includes this skill and all its references; it needs no
+GitHub account or access to Amalgm's source repositories. With Node.js 22.20+
+(or Amalgm's supplied Node runtime), run:
+
+```bash
+npx skills add https://automations.amalgm.ai --skill amalgm-automations
+```
+
+Choose the intended agent in the installer's prompt. Installing the skill
+supplies guidance; use the connection steps below to access Automations.
+
 ## Start with the connection you have
 
 If Automations MCP already answers `list` with `{"limit":1}`, continue the task.
@@ -34,6 +47,28 @@ A successful Automations response is a JSON `result` envelope; an empty list
 is valid. The six Automations commands use that envelope. Shell's `status`
 returns a different JSON shape; `login` and `run` report progress as text.
 
+For a local stdio MCP client, configure this server using the actual selected
+account email (Shell 0.1.176 or newer):
+
+```json
+{
+  "mcpServers": {
+    "amalgm-automations": {
+      "command": "amalgm",
+      "args": ["automations", "mcp", "--user", "person@example.com"]
+    }
+  }
+}
+```
+
+This is the server entry for clients using `mcpServers` JSON; clients with a
+different configuration format use the same command and arguments. Use the
+exact installed launcher path if the client cannot find `amalgm` on PATH.
+Shell supplies the current local connection on every tool call, including
+after a runtime restart. Do not add credentials or environment variables.
+Listing tools works before login; calling them requires a running signed-in
+runtime. After configuring the client, verify its Automations `list` tool.
+
 ## Install only when needed
 
 Check for an existing app-managed installation before adding another copy.
@@ -105,8 +140,11 @@ do not reopen approval until they choose to continue.
 
 ## Reuse or resume a registered computer
 
-Once the account email is known, inspect it explicitly. Replace the example
-email below with the user's actual selected account:
+Discover registered accounts with `amalgm status --all` (Shell 0.1.176+).
+It returns email and registration state only. A sole ready account is selected
+implicitly; multiple ready accounts require `--user`. Once the account email
+is known, inspect it explicitly. Replace the example email below with the
+user's actual selected account:
 
 ```bash
 amalgm status --user person@example.com
@@ -140,14 +178,15 @@ pending; it does not erase their history.
 
 ## Diagnose the failing boundary
 
-Read the error's code, message, and status together; some Shell failures are
-wrapped as `internal`. Keep automation and run ids when available. Try the
+Read the error's code, message, and status together. Keep automation and run
+ids when available. Try the
 appropriate repair and verify again. If the same failure persists with no new
 evidence, explain it and offer support rather than looping through login,
 reinstallation, or repeated writes.
 
 | Failure | What to do |
 | --- | --- |
+| `user_not_registered` or `user_selection_required` | Use `amalgm status --all` to discover local accounts, then select the intended email or complete login for it. |
 | `runtime_unavailable`, connection refused, or Shell says it is not running | Inspect the selected account's status and use the resume/setup decision above. A standalone adapter asking for environment credentials should be replaced by the global `amalgm automations` path. |
 | `runtime_unauthorized` | Retry the read once through the public Shell command, which obtains the current local connection. If it still fails, keep the error for support; never extract or replace tokens manually. |
 | `runtime_transport` or `runtime_protocol` | Check local readiness, connectivity, and the installed version. A timeout or service outage is not evidence that the user needs a new account. |
@@ -159,8 +198,10 @@ reinstallation, or repeated writes.
 
 For a failed mutation, inspect existing state before retrying. Reuse the same
 Run Now input and idempotency key after an uncertain response. Preserve a
-returned disabled draft id. A retry must not turn one requested automation or
-run into several.
+returned disabled draft id: get that definition, then repair it with `update`
+instead of retrying `create`. Invalid supplied configuration is rejected
+before any write; a later service failure can still leave a disabled draft.
+A retry must not turn one requested automation or run into several.
 
 ## Get support