From de5068d355ac942dfc7396e13bf5d39c88f3b009 Mon Sep 17 00:00:00 2001 From: Waleed Latif Date: Wed, 11 Nov 2026 14:04:22 -0800 Subject: [PATCH] docs(skills): align skills with production CLI and API behavior Correct stale claims against the production CLI reference and v2 contracts: stored deployment versions keep credentials (only versions get is sanitized), manual runs and tool calls accept OAuth logins, lint now checks block-output references, and table groups default to autoRun and deployed mode. Add short guidance for wait-timeout, run pauses and exit codes, async deploys, chat access resets, trigger health, file revisions and versions, search completeness, connector secrets, and bulk table operations. List files and run-tool in the plugin manifests and bump to 0.1.1. --- .claude-plugin/plugin.json | 14 +++++++-- .codex-plugin/plugin.json | 16 ++++++++--- package.json | 2 +- skills/build-workflow/SKILL.md | 33 ++++++++++++++++------ skills/deploy-workflow/SKILL.md | 50 ++++++++++++++++++++++----------- skills/files/SKILL.md | 28 +++++++++++++----- skills/knowledge-base/SKILL.md | 32 +++++++++++++++++---- skills/run-tool/SKILL.md | 15 ++++++---- skills/run-workflow/SKILL.md | 42 ++++++++++++++++++--------- skills/sync-workspaces/SKILL.md | 10 +++++-- skills/table/SKILL.md | 36 +++++++++++++++++++----- 11 files changed, 205 insertions(+), 73 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index d6694b2..20f594b 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "sim", "displayName": "Sim", - "version": "0.1.0", - "description": "Build, run, deploy, and sync Sim workflows; operate tables and knowledge bases.", + "version": "0.1.1", + "description": "Build, run, deploy, and sync Sim workflows; operate tables, knowledge bases, and workspace files; call integration tools directly.", "author": { "name": "Sim", "url": "https://sim.ai" @@ -10,6 +10,14 @@ "homepage": "https://docs.sim.ai", "repository": "https://github.com/simstudioai/skills", "license": "Apache-2.0", - "keywords": ["sim", "workflows", "automation", "tables", "knowledge-bases"], + "keywords": [ + "sim", + "workflows", + "automation", + "tables", + "knowledge-bases", + "files", + "integrations" + ], "skills": "./skills/" } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index e6cebd9..56b95eb 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "sim", - "version": "0.1.0", - "description": "Build, run, deploy, and sync Sim workflows; operate tables and knowledge bases.", + "version": "0.1.1", + "description": "Build, run, deploy, and sync Sim workflows; operate tables, knowledge bases, and workspace files; call integration tools directly.", "author": { "name": "Sim", "url": "https://sim.ai" @@ -9,12 +9,20 @@ "homepage": "https://docs.sim.ai", "repository": "https://github.com/simstudioai/skills", "license": "Apache-2.0", - "keywords": ["sim", "workflows", "automation", "tables", "knowledge-bases"], + "keywords": [ + "sim", + "workflows", + "automation", + "tables", + "knowledge-bases", + "files", + "integrations" + ], "skills": "./skills/", "interface": { "displayName": "Sim", "shortDescription": "Build and operate Sim workflows", - "longDescription": "Use the Sim CLI to build, test, deploy, and debug workflows, import and sync workspaces, and manage tables and knowledge bases.", + "longDescription": "Use the Sim CLI to build, test, deploy, and debug workflows, import and sync workspaces, manage tables, knowledge bases, and workspace files, and call integration tools directly.", "developerName": "Sim", "category": "Productivity", "capabilities": ["Read", "Write"], diff --git a/package.json b/package.json index a49e87b..3efcc2b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sim-skills", - "version": "0.1.0", + "version": "0.1.1", "description": "Official Sim plugin and Agent Skills for building workflows and operating Sim resources", "type": "module", "bin": { diff --git a/skills/build-workflow/SKILL.md b/skills/build-workflow/SKILL.md index 3a87bcf..37d9a81 100644 --- a/skills/build-workflow/SKILL.md +++ b/skills/build-workflow/SKILL.md @@ -20,6 +20,9 @@ are regenerated; do not recreate that flow with a sequence of graph edits. - Use the profile the user named. If none was named, inspect configured profiles and current context; do not silently switch accounts, workspaces, or API origins. +- Graph edits need an OAuth login or personal API key with write access. `sim --output json meta + status` reports the credential's `keyType`, `scopes`, and `expiresAt`; a read-only key (only + `api:read`) is refused every mutation with `READ_ONLY_API_KEY`. - Find the intended workflow with `sim --output json workflows list`. Create one only when the user asked for a new workflow. - Read an existing draft with `sim --output json workflows state get ` before editing it. @@ -85,7 +88,9 @@ are regenerated; do not recreate that flow with a sequence of graph edits. - Put only workflow-author-fixed values in a tool's `params`; omit arguments the model should choose. Omit `usageControl` or use `auto` when the model may decide, `force` when every Agent run - must call it, and `none` to disable it. + must call it, and `none` to disable it. To decide per run, set `usageControlExpression` instead + (a reference such as `` resolving to `auto`, `force`, or `none`); send one of the + two, never both. - Resolve custom-tool ids with `custom-tools list` and `custom-tools get`. Resolve MCP server and tool names with `mcp-servers list` and `mcp-servers tools list `. New custom tools should use `customToolId`; preserve an existing legacy inline declaration but do not create another. @@ -132,9 +137,15 @@ are regenerated; do not recreate that flow with a sequence of graph edits. example text beside the code that uses it. - Before applying a batch, enumerate every `` reference in its inputs. Verify the normalized prefix against the exact upstream block name in workflow state, verify the field path - against the catalog output schema, and verify the source is reachable upstream. A clean workflow - operations lint does not prove block-output references resolve; its `unresolvedReferences` report - covers resource-like references such as credentials, tools, and skills. + against the catalog output schema, and verify the source is reachable upstream. +- Lint `unresolvedReferences` with kind `block-output` catches a reference to a block that does not + exist, an unknown top-level output field (`unknown-field`), an undeclared path below an MCP + block's `structuredContent`, and a text output written unquoted in a JSON field + (`unquoted-json-string`; build that JSON in a Function block instead). A clean lint proves nothing + else: it does not check reachability, nested paths on other blocks, references into trigger or + trigger-mode blocks, loop/parallel/table outputs, an Agent whose `responseFormat` does not parse, + blocks that declare no outputs, `loop.`/`parallel.`/`variable.` references, or tokens that do not + look like `name.path` (the `getP&L` case above). ## Discover before composing @@ -247,6 +258,10 @@ Use `--dry-run --atomic` to validate a proposed batch when needed. Validation ex and does not suppress writes during a later run. Dry-run `previewBlockIds` are provisional; later requests must use the committed response's `mintedBlockIds`. +Enable or disable blocks with `--set-block-enabled '[{"block_id":"","enabled":false}]'`, +applied after `--operations`; disabling a loop or parallel cascades to its unlocked children. +`--layout none` keeps supplied positions; the default `targeted` repositions the touched subgraph. + Pass the batch as inline JSON on the first attempt and apply it once with atomic behavior. Do not create a staging file preemptively: @@ -261,8 +276,10 @@ passed to the CLI. If the atomic apply is refused, fix the batch rather than retrying a partial or guessed alternative. Read the state again and verify the requested blocks, inputs, and edges. Treat skipped operations, -dropped inputs, unresolved references, and required-field lint issues as failures to correct. Report -minted ids and any other advisory lint that remains. Confirm that changed references resolve, every +dropped inputs, unresolved references, required-field lint issues, and `tableFieldIssues` (a Table +filter or sort naming no column) as failures to correct. `manualRunIssue` describes only the +editor's Run button; API runs do not apply it. Report minted ids and any other advisory lint that +remains. Confirm that changed references resolve, every branch reaches the intended destination, nested blocks remain in the correct loop or parallel scope, and no block was orphaned by a replaced connection set. Recompute reference prefixes from the persisted block names; do not infer them from request-local labels or reformat them as snake_case. @@ -273,6 +290,6 @@ a clickable link. Do not construct a workflow URL from ids or the profile's API When the request includes a working or tested workflow and execution is safe, use the run skill to manually test the saved draft with realistic input. Judge the returned values, not only the terminal -status, and fix then rerun when behavior is wrong. Manual runs require a personal API-key profile; -do not deploy merely to test. Do not execute a workflow whose external side effects have not been +status, and fix then rerun when behavior is wrong. Manual runs need an OAuth login or personal API +key with write access, never a workspace key; do not deploy merely to test. Do not execute a workflow whose external side effects have not been authorized. diff --git a/skills/deploy-workflow/SKILL.md b/skills/deploy-workflow/SKILL.md index b547644..3e6054e 100644 --- a/skills/deploy-workflow/SKILL.md +++ b/skills/deploy-workflow/SKILL.md @@ -10,7 +10,10 @@ post-deployment state. ## Preflight -- Read the draft and current deployment before changing anything. +- Deploy, activate, rollback, revert, undeploy, and chat publish need workspace admin and an OAuth + login or personal API key; a workspace key is refused. +- Read the draft and current deployment before changing anything. `workflows deployment status` + reports `needsRedeployment` (draft differs from live) and the live `webhooks[]` URLs. - Confirm the draft has no required-field lint issues or unresolved credentials and has completed an appropriate manual run. - Check prior edit responses for skipped operations and dropped inputs, then reread the saved draft @@ -20,22 +23,24 @@ post-deployment state. access configuration. - Never create, rotate, or reveal an API key unless the user separately asked for key management. -## What a stored version is not +## Versions, revert, and rollback -A stored workflow version nulls out `credential`, `oauthCredential`, resource selectors, and -related binding fields. Two consequences: - -- A diff against a version document is not a change report. Blocks whose only delta is a nulled - field show as changed, and selector changes do not show at all - the diff overstates and - understates simultaneously. Diff live state against live state instead. -- A revert restores the nulled document, stripping every credential and selector in the workflow. - Never present revert as a safe rollback; the reverted draft needs its bindings re-established - before it can run. +- `workflows versions get` returns a sanitized copy: credentials, inline secrets, and opaque + credential inputs are nulled, so diffing two of those documents both overstates and hides + changes. Use `workflows versions compare --base --target `, which marks each + changed value as `value`, `redacted`, or `unset`. +- `workflows revert create --yes` overwrites the draft with that + version's stored graph, credentials included, and cannot be undone. It does not change what + is live. +- `workflows activate create` and `workflows rollback [--to-version ]` change the live version + for every API and chat consumer and leave the draft alone. ## Choose one surface - **API:** for software calling a workflow as a pipeline. Publish with `sim --output json workflows deploy ` and inspect with `workflows deployment status`. + `workflows deployment update --is-public-api true` lets anyone with the URL run it on + the workspace's bill; change it only on explicit request. - **Chat:** for a person using a shareable conversation. Configure the actual output fields, slug, title, welcome message, and access policy with `workflows chat publish`; inspect with `workflows chat status`. A chat deployment also publishes the workflow API. @@ -48,9 +53,13 @@ Do not choose a surface from convenience. Ask when the intended caller does not ## Access invariants -- A protected chat must include the required password or allowed-email list. Fail instead of - publishing an unusable access policy. -- Use a lowercase hyphenated chat slug. +- `chat publish` replaces the whole access policy. Omitting `--auth-type` makes the chat public, + and omitted password or email settings reset, so republishing a protected chat without its auth + flags silently opens it. Always resend `--auth-type` (`public`, `password`, `email`, `sso`) with + `--password` (15-1024 characters) or `--allowed-emails`. Fail instead of publishing an unusable + or weaker policy. +- The chat `--identifier` slug matches `^[a-z0-9-]+$` and must be free across live deployments. +- Omitting `--output-configs` surfaces no block outputs to visitors. - Map chat outputs from real block output fields returned by the catalog or a successful run, not display labels. MCP generates its schema from deployed workflow inputs; parameter descriptions must name those real input fields, and unknown names are ignored. @@ -78,9 +87,16 @@ That flow owns mapping discovery, preview fingerprints, stable request IDs, and ## Verify and report -After publishing, read the deployment again. Confirm its active status and version and return the -real URL or MCP connection details from the response; never fabricate them. If the draft remains -ahead of the deployed version, say so. +Deployment is asynchronous: the deploy response accepts an attempt while the older version can stay +live. Poll `workflows deployment status` until `latestDeploymentAttempt` names the new version with +status `active` (or `failed`). Deploy has no idempotency key, so after a timeout read the status +before deploying again; a blind retry creates another version. Return the real URL or MCP +connection details from the response; never fabricate them. If the draft remains ahead of the +deployed version, say so. + +`workflows triggers list ` shows the health of each live trigger. +`workflows triggers update --enabled false` pauses one, but only until the +next deploy or version activation re-enables every trigger. Undeploy only on an explicit request. Use `workflows undeploy`, `workflows chat unpublish`, or `workflow-mcp-servers tools delete` for the matching surface, supplying confirmation where the CLI diff --git a/skills/files/SKILL.md b/skills/files/SKILL.md index 94c9359..3c2c374 100644 --- a/skills/files/SKILL.md +++ b/skills/files/SKILL.md @@ -46,6 +46,10 @@ sim --output json files search \ Use `--mode exact` for literal text and `--no-include-subfolders` when only the selected folders should be searched. Do not fetch every file and search locally when the server-side query suffices. +`files search` returns at most `--max-results` lines (default 50); `truncated: true` means more +exist. No match proves absence only when `complete` is true and `indexStatus.skippedFiles` and +`indexStatus.partialFiles` are both zero; otherwise report the result as inconclusive. + ## Create and organize deliberately Upload a local file or create textual content directly: @@ -62,6 +66,9 @@ folder atomically with `files folders move `. Move known fil File names are leaf names, not paths. Use `files rename --name ` to change one and `files move` to change its folder. Do not place path separators or dot segments in a file name. +`files copy --source --destination ` copies files or folders. `files unzip +--yes` writes every archive entry into the workspace, so confirm the destination first. + ## Read before editing For textual work, inspect only the needed lines: @@ -131,18 +138,25 @@ Delete from the start anchor through the line before the retained end anchor: ``` Use `files set-content` only when complete replacement is intentional. A targeted edit preserves -unrelated content and reduces stale-read overwrites. If an edit is rejected because the source -changed concurrently, read the current file and recompute the edit; do not replay the stale write. +unrelated content and reduces stale-read overwrites. Pass `--expected-revision` with the +`revision` from `files describe` (each write returns the new one) so a concurrent change answers +`409` instead of being overwritten. On `409`, read the current file and recompute the edit; do not +replay the stale write. + +File content is versioned. `files versions list`, `versions read`, and `versions download` +inspect history; `files versions revert --expected-revision ` is the undo +path. `files versions delete` permanently removes a version; use it only on explicit request. ## Treat deletion and sharing as explicit effects -File and folder deletion requires `--yes` and is soft-delete where the surface supports restore. -Use `files list --scope archived` or `files folders list --scope archived` to find deleted items, -then restore by exact file id or folder path. A recursive folder delete affects descendants, so use +File and folder deletion requires `--yes` and is soft-delete where the surface supports restore; +`files batch-delete --yes` archives several files. Use `files list --scope archived` or +`files folders list --scope archived` to find deleted items (`files describe --scope +archived` reads one), then restore by exact file id or folder path. A recursive folder delete affects descendants, so use it only when the requested scope is clear. -Before changing a share, inspect it with `files share get `. `files share set` requires a -personal API-key profile. Do not expose share passwords, profile credentials, or unrelated file +Before changing a share, inspect it with `files share get `. `files share set` requires an OAuth +login or personal API key; a workspace key is refused. Do not expose share passwords, profile credentials, or unrelated file content in output. ## Verify and report diff --git a/skills/knowledge-base/SKILL.md b/skills/knowledge-base/SKILL.md index 3a34920..81e552a 100644 --- a/skills/knowledge-base/SKILL.md +++ b/skills/knowledge-base/SKILL.md @@ -52,13 +52,22 @@ than guessing slot meanings. For files already stored in the workspace, use `knowledge from-workspace-files create` so the server reads the canonical file. For a continuously changing external source, use a connector: -1. Run `sim --output json connector-types list` and select an exact `connectorType`. +1. Run `sim --output json connector-types list --detail full` and select an exact + `connectorType`; the default summary omits the config schema. 2. Read its returned `auth` mode and `configFields`. Build `sourceConfig` using each field's id or `canonicalParamId`, honoring `required`, `dependsOn`, and `multi`. -3. Supply an existing OAuth `credentialId` or the required API key without writing the secret to a - committed file or output. -4. Create it with `knowledge connectors create`, then start an explicit sync with - `knowledge connectors sync` when needed. +3. Supply an existing OAuth `credentialId`, or `--api-key '{{SECRET_NAME}}'` as a whole-value + secret reference (`$SECRET_NAME` is sent literally). Never write the secret to a committed file + or output. +4. Create it with `knowledge connectors create` (`--sync-interval-minutes` defaults to 1440; `0` + disables scheduled syncs), then start an explicit sync with `knowledge connectors sync` when + needed. + +`knowledge connectors update --status paused|active` pauses or resumes a connector; a new +`--source-config` on a runnable connector queues a sync. `knowledge connectors documents update +--operation exclude|restore` hides or brings back individual synced documents. +`knowledge connectors delete --delete-documents` permanently deletes everything it synced; use it +only on explicit request. Never invent provider-specific `sourceConfig`. Do not use `--rehydrate` unless the user intends to re-fetch and re-index every existing connector document. @@ -76,6 +85,8 @@ For an exact item, use `knowledge documents get `. searchable only when it is enabled and `processingStatus` is `completed`. Treat `pending` and `processing` as nonterminal, and `failed` as a real failure. Use `documents update --retry-processing` alone only for a failed or stuck document; do not combine that flag with metadata changes. +`knowledge documents batch-update --operation enable|disable` toggles several documents' search +eligibility. For connectors, inspect `knowledge connectors list` and `knowledge connectors documents list` to distinguish connector sync state from individual document processing. Poll with a bounded stopping @@ -96,6 +107,17 @@ Search and document-list filters use the tag's display name, not its storage slo All filters in one request must match. A missing tag name or inconsistent definition across selected knowledge bases is an error, never an ignored filter. +`knowledge tags usage` shows which definitions documents still carry. `knowledge tags cleanup` +removes only unused definitions by default; `--no-unused` deletes every definition and clears its +values on every document and chunk, irreversibly. Never pass it without an explicit request. + +Edit chunk content directly with `knowledge chunks create`, `chunks update`, or +`chunks batch-update --operation enable|disable|delete` (delete is permanent). + +To copy a knowledge base, `knowledge export ` writes a bundle and `knowledge import ` +creates a new knowledge base from it; `--no-vectors` shrinks the bundle and makes the import +re-embed every chunk. + ## Verify retrieval Run a bounded search after documents reach `completed`: diff --git a/skills/run-tool/SKILL.md b/skills/run-tool/SKILL.md index 71c9959..e60cac4 100644 --- a/skills/run-tool/SKILL.md +++ b/skills/run-tool/SKILL.md @@ -10,8 +10,10 @@ Never put a live credential in the command. ## Preflight -- `tools execute` requires a personal API-key profile; a workspace API key is refused. -- Find the tool with `sim --output json tools list --search `, then read it with +- `tools execute` needs an OAuth login or personal API key and workspace write access. A workspace + key is refused, and a read-only key gets `403` with `READ_ONLY_API_KEY`. +- Find the tool with `sim --output json tools list --search ` (narrow with + `--oauth-provider ` or `--hosted-api-key always|conditional|none`), then read it with `sim --output json tools get `. Never guess a tool id or a parameter name. - An unversioned name resolves to the newest version visible in the workspace, and the response echoes the id that answered. Use that id in the call. @@ -24,7 +26,7 @@ Never put a live credential in the command. `tools get` labels every parameter with a `visibility`, and the label says where its value comes from: -- `user-or-llm` — you supply it in `--input`. +- `user-or-llm` or `llm-only` — you supply it in `--input`. - `user-only` — you supply it, but pass a reference instead of the secret: `{{VAR_NAME}}` as the whole value, resolved server-side. List the available names with `sim --output json secrets list`; values are never returned. Any other value is sent verbatim. @@ -58,13 +60,16 @@ sim --output json tools execute --credential-id --input '{"...": " ``` `--input` also accepts `@path` or `@-`, which is how a payload too large or too awkward to quote -reaches the command. +reaches the command. `--timeout ` bounds the wait (default 120, max 300). A timeout does +not cancel the third-party side effect; treat the outcome as unknown and check the service before +any retry. A tool result with `status: "failed"` exits non-zero and reports its reason in `error.message`. Read that reason to distinguish execution setup failure from a provider refusal; the status alone does not prove the service received the request. A `403` carrying `error.details.code` `INTEGRATION_NOT_ALLOWED` is a workspace policy decision, not a fixable -argument — say so and stop. +argument — say so and stop. A `402` `USAGE_LIMIT_EXCEEDED` means a Sim-hosted key hit the +workspace's usage limit; report it rather than switching credentials. Tool results follow the provider's pagination contract. When more pages remain, use the published cursor before reporting a total; the CLI's resource-list pagination does not paginate tool results. diff --git a/skills/run-workflow/SKILL.md b/skills/run-workflow/SKILL.md index d96eb01..ac1e5ae 100644 --- a/skills/run-workflow/SKILL.md +++ b/skills/run-workflow/SKILL.md @@ -12,7 +12,8 @@ than treating request acceptance as success. - Use `sim --output json workflows run ` to run the active deployment. - Add `--manual` to run the current saved draft without deploying it. Manual execution and - run-from-block require a personal API-key profile; a workspace API key is not permitted. + run-from-block need an OAuth login or personal API key with write access; a workspace key is + refused, and a read-only key gets `403` with `READ_ONLY_API_KEY` on any run. - Do not deploy a draft merely to test it. A workflow does not need a Start block for a plain manual run: @@ -44,17 +45,30 @@ sim --output json workflows run \ Do not guess a source run or synthesize upstream outputs. Confirm that the source run belongs to the workflow and contains the state the selected block needs. +`--stop-after ` ends the run after that block and fails it if the path skips the block. +With `--from-block` on the same block, it re-runs only that block. + ## Long runs and uncertain responses -Current CLI and server versions use heartbeat responses for ordinary synchronous runs, including -`--manual`. A long-running draft does not require deployment. Use `--follow` when live progress -helps; it does not make execution asynchronous. For an intended deployed run, use `--async` and -`workflows runs wait --workflow --wait-timeout 3600`, or another explicit bound. +A long-running draft does not require deployment. Bound a long synchronous run, manual or +deployed, with `--wait-timeout `: if the run is still going it continues in the +background, the CLI prints its run record and exits 4, and +`workflows runs wait --workflow ` keeps waiting. `--wait-timeout` cannot be +combined with `--async` or `--follow`, and `--execution-timeout-seconds` requires one of +`--async` or `--wait-timeout`. Use `--follow` when live progress helps; it does not make execution +asynchronous. + +`runs wait` exits 0 completed, 1 failed, 2 cancelled, 3 needs input, 4 timed out (default bound +3600 seconds). On 3, read `workflows runs get`: `paused.points[]` carries each pause's `contextId`, +then `workflows runs resume --workflow --context --input @input.json`. +`workflows runs list --workflow --status ` finds earlier runs; +`workflows runs cancel` stops one, and a cancelled paused run cannot be resumed. After a timeout or connection loss, inspect the known run before starting another execution; external actions may already have occurred. Ordinary runs without `--follow` accept `--run-id` -to choose the identifier before sending. It is not an idempotency key: a claimed ID conflicts -rather than replaying the result, and a missing run record does not prove nothing executed. +to choose the identifier before sending. It is not an idempotency key: a claimed ID fails with +`409` `RUN_ID_CONFLICT` rather than replaying the result, and a missing run record does not prove +nothing executed. Do not automatically retry with a fresh or omitted ID. ## Keep output focused @@ -84,13 +98,13 @@ of success. Four properties of runs and run records that mislead diagnosis when unknown: -- A run record has a lifecycle. `logs get` returns NOT_FOUND for a run that is still in flight and - for one that was cancelled, and a completed run can report a `redacting` status for a minute or - two before its content is readable. Poll with a bounded retry before concluding the run vanished. -- Firing a run immediately after `workflows deploy` reports the new version active can still - execute the previous deployment, silently. When a run exists to verify a deploy, confirm the - executed behavior from its outputs rather than trusting the deploy response, and re-run if the - outputs match the old version. +- A run record has a lifecycle. `logs get` returns NOT_FOUND until the run has a log row, which a + queued run does not yet have, and a completed run can report a `redacting` status for a minute or + two before its content is readable. Use `workflows runs get` for lifecycle state, and poll with a + bounded retry before concluding the run vanished. +- Deployment is asynchronous: `workflows deploy` accepts an attempt while the older version stays + live. Poll `workflows deployment status` until `latestDeploymentAttempt` names the new version + with status `active` before running to verify it, then confirm the behavior from the outputs. - Run traces nest: a child workflow's blocks appear inside its parent span, not at the top level. Reading only the top level of the span tree silently drops every block a child workflow ran, which can be most of the run. Walk the tree recursively before counting blocks or hunting the diff --git a/skills/sync-workspaces/SKILL.md b/skills/sync-workspaces/SKILL.md index e774a27..3c73ee6 100644 --- a/skills/sync-workspaces/SKILL.md +++ b/skills/sync-workspaces/SKILL.md @@ -18,6 +18,8 @@ operation; sync also requires target deployment readiness. Imports and forks com - Fork creation requires source admin. Sync and mapping changes require admin on both workspaces. Fork administration accepts personal API keys or OAuth, not workspace keys. Imports retain their existing workflow-write permissions; credential binding still requires an eligible acting user. +- Previews count as writes: OAuth needs `api:write`, and a read-only API key is refused even for + a preview. Check `sim --output json meta status` (`keyType`, `scopes`) before starting. - Inspect `workspaces fork-availability` before forking. Enterprise/self-hosting and workspace creation policies still apply. OAuth scopes and permission groups can further restrict access. - Use `--output json`. Single-resource CLI results are unwrapped objects; paged results contain @@ -151,8 +153,10 @@ sim --profile destination --workspace "$DESTINATION_WORKSPACE" --output json \ Use `--yes` within the user's authorized destructive sync scope. Review replacements, exclusions, resource selections, required configuration, and trigger URL changes before apply. If preview offers -trigger adoption choices, use its stable source workflow/block identities and offered paths; never -invent a path. Sync `ready` indicates commit readiness, not a live deployment. Scheduled or webhook +trigger adoption choices in `triggerSlots`, pass them with `--trigger-mappings` entries of +`{sourceWorkflowId, sourceBlockId, adoptPath}` using only offered paths; never invent a path. +`--drop-references` acknowledges removal of references whose source was deleted; live references +cannot be dropped. Sync `ready` indicates commit readiness, not a live deployment. Scheduled or webhook workflows can begin receiving traffic once admitted deployments activate. ## Completion and recovery @@ -177,6 +181,8 @@ workflows can begin receiving traffic once admitted deployments activate. arbitrary prior drafts or remove every copied resource. Use rollback/unlink/exclusion controls only for the requested recovery scope and verify their result. +`workspaces members update` and `members remove` exist; use them only on an explicit request. + For a new imported draft, use the `run-workflow` skill to test it and `deploy-workflow` only when publication is requested. Never copy secret values, signed URLs, arbitrary headers, or opaque credential payloads between environments to make a binding pass. diff --git a/skills/table/SKILL.md b/skills/table/SKILL.md index e754724..d07eec2 100644 --- a/skills/table/SKILL.md +++ b/skills/table/SKILL.md @@ -62,6 +62,10 @@ known row. Use `tables upsert --on email --data @row.json` only agains An upsert's update branch **replaces the complete row** and clears omitted columns, so always send the complete desired row. +For many rows: `tables rows update-each` applies a distinct patch per listed row, +`tables rows batch-update --filter` patches every matching row, and `tables rows batch-delete` +deletes matching or listed rows. The last two cannot be undone; count the filter's matches first. + For CSV input, prefer the import command over parsing client-side: ```bash @@ -71,7 +75,11 @@ sim --output json tables import ./updates.csv --table-id --mode append `--mode replace` is destructive for an existing table. Use it only when explicitly requested. Unless the caller deliberately chose `--no-wait`, require the import's terminal result rather than -treating queue acceptance as completion. +treating queue acceptance as completion. `tables imports cancel` keeps rows already written; +re-importing after a cancelled append duplicates them. + +Saved views live under `tables views`. A deleted table is archived; `tables restore ` +recovers it. ## Query on the server @@ -87,8 +95,10 @@ sim --output json tables rows query \ Use `tables rows count` when only a count is needed and `tables rows search` for a case-insensitive substring across cells. A negating filter may include null or absent values; add an explicit `isNotNull` or `isNotEmpty` condition when nulls must be excluded. Avoid `--limit 0` on -an unbounded table. Request `--include-run-state` only when workflow-group diagnostics are needed; -it is incompatible with `--limit 0` and caps a page at 200 rows. +an unbounded table; for a full pull use `tables exports create --format csv|json`, then +`exports get` until finished and `exports download`. Request `--include-run-state` only when +workflow-group diagnostics are needed; it caps a page at 200 rows (the CLI still pages under +`--limit 0`) and a page over 2 MiB of run state returns `413`. ## Connect a workflow or enrichment @@ -101,11 +111,18 @@ columns: "type": "manual", "workflowId": "", "name": "Score contacts", + "deploymentMode": "deployed", + "autoRun": false, "inputMappings": [{ "inputName": "email", "columnName": "email" }], "outputs": [{ "blockId": "", "path": "score", "columnName": "score" }] } ``` +Always set `autoRun` and `deploymentMode` in the group body. A group without `autoRun` defaults to +`true` and fires a metered run for every later row whose inputs fill. A group without +`deploymentMode` runs the active deployment (`deployed`) and refuses while the workflow is +undeployed; `live` runs the editable draft. + Create the group with both files: ```bash @@ -115,10 +132,15 @@ sim --output json tables groups create \ --no-auto-run ``` -`output-columns.json` is an array of typed column definitions. Group creation defaults to not -scheduling existing rows; opt into `--auto-run` only when the user intends that metered fan-out. -Afterward, use the group id returned by the API with the explicit row or batch dispatch command and -inspect dispatch and row run state until terminal. +`output-columns.json` is an array of typed column definitions; an entry naming an existing column +attaches it. The `--auto-run` flag only decides whether existing rows are scheduled now (default +no); it does not set the group's `autoRun`. Opt in only when the user intends that metered fan-out. + +Run explicitly with `tables dispatches create --group-ids `, narrowing with +`--run-mode incomplete`, `--row-ids`, `--filter`, or `--max-rows`; use `tables rows enrich` for one +row. Inspect `dispatches get` and row run state (`tables enrichment get` for one cell group) until +terminal. `dispatches cancel` stops dispatching, but cells already queued keep running; stop those +with `tables cancel-runs --scope all|row --yes`. Change a group with `tables groups update`. ## Verify and report