docs(skills): align skills with production CLI and API behavior

.claude-plugin/plugin.json

@@ -1,15 +1,23 @@
 {
 	"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"
 	},
 	"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/"
 }

.codex-plugin/plugin.json

@@ -1,20 +1,28 @@
 {
 	"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"
 	},
 	"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"],

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": {

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 <workflowId>` 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 `<start.toolMode>` 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 <serverId>`. 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 `<block.field>` 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":"<uuid>","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.

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 <workflowId> --base <n> --target <n>`, which marks each
+  changed value as `value`, `redacted`, or `unset`.
+- `workflows revert create <workflowId> <version|active> --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 <n>]` 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 <workflowId>` and inspect with `workflows deployment status`.
+  `workflows deployment update <workflowId> --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 <workflowId>` shows the health of each live trigger.
+`workflows triggers update <workflowId> <blockId> --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

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 <path> <destination>`. Move known fil
 File names are leaf names, not paths. Use `files rename <fileId> --name <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 <json> --destination <json>` copies files or folders. `files unzip <fileId>
+--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 <fileId> <version> --expected-revision <rev>` 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 <ids...> --yes` archives several files. Use `files list --scope archived` or
+`files folders list --scope archived` to find deleted items (`files describe <fileId> --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 <fileId>`. `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 <fileId>`. `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

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 <knowledgeBaseId> <documentId>`.
 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 <id>` writes a bundle and `knowledge import <path>`
+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`: