Merge remote-tracking branch 'origin/staging' into worktree-shadcn-cn-migrate

Author: waleedlatif1

.agents/skills/ship/SKILL.md

@@ -66,6 +66,10 @@ When the user runs `/ship`:
   # Runs every audit CI runs, concurrently, and replays the output of any that fail.
   # The audit list is derived in scripts/run-audits.ts — do not hand-list audits here.
   bun run check:audits || { echo "❌ audit(s) failed — do not ship"; exit 1; }
+  # CI's "Verify docs manifest is in sync" step is not a `check:*` script, so the runner above
+  # does not cover it. (CI's "Security audit" `bun audit` step is `continue-on-error` — advisory
+  # only, not a gate — so it is deliberately not run here.)
+  bun run docs-manifest:check || { echo "❌ docs manifest out of sync — do not ship"; exit 1; }
   ```
   If Phase A regenerated a file, its matching `:check` in Phase B now passes trivially — that parity is the point. Do not ship with any generator or audit failing; fix the cause (never silence it) and re-run. `check:migrations` and `type-check` are covered by steps 5 and CI respectively and are not repeated here.
 7. **Stage and commit** the changes with the generated message — including any files Phase A regenerated in step 6

apps/docs/content/docs/cli/configuration.mdx

@@ -114,15 +114,80 @@ shared profile cannot also set its own endpoint or API key.
 | `SIM_API_KEY` | API key — skips `sim login` entirely |
 | `SIM_WORKSPACE` | Workspace to target |
 | `SIM_OUTPUT` | Output format |
-| `SIM_CONFIG_DIR` | Relocate both files away from `~/.sim` |
+| `SIM_CONFIG_DIR` | Relocate the config directory and update cache; file-specific overrides below still win |
 | `SIM_CONFIG_FILE` | Relocate only the config file |
 | `SIM_CREDENTIALS_FILE` | Relocate only the credentials file |
 | `SIM_TIMEOUT_SECONDS` | Per-request timeout; `0` waits indefinitely. Defaults to `3600`, above every timeout the server itself applies |
 | `SIM_DEBUG` | Trace each request's method, URL, status and duration to stderr |
+| `SIM_NO_UPDATE_CHECK` | Turn off update checks |
 
-Node ignores `HTTPS_PROXY` unless you also set `NODE_USE_ENV_PROXY=1`, and only
-from Node 22.21 and 24.5. The CLI warns when a proxy is configured but will not
-be used.
+## Update notices
+
+On eligible invocations, the CLI uses a daily cache before asking
+`registry.npmjs.org` what is published under the `latest` tag. Prerelease
+installs are skipped entirely, so a `-preview` or `-dev` build is never told to
+upgrade. When a newer one exists, it prints a single line on stderr naming both
+versions and the command that upgrades:
+
+```
+Update available: sim 2.1.2 → 2.1.5. Run: npm install -g sim@latest
+```
+
+Apart from the configured registry URL, the request identifies only the CLI
+version — no Sim API key, workspace, or command — and it never follows a
+redirect away from the registry it asked.
+
+One caveat worth stating plainly: if you point `npm_config_registry` at a
+private mirror, the check goes to that mirror instead of npm. Query-string
+credentials (an Artifactory or Nexus `?token=…`, for example) are preserved and
+sent as part of the configured registry request — they have to be, or the
+mirror would reject it. As with other registry traffic, configured proxies or
+TLS inspection can observe what that network setup permits. A registry URL
+containing username/password userinfo, such as
+`https://user:password@registry.example`, is rejected and no update check is
+made.
+
+An empty or whitespace-only `npm_config_registry` is treated as unset, so the
+public registry remains the default. Non-empty malformed and non-HTTP(S) values
+disable the update check rather than making an unexpected public request.
+
+The notice is skipped entirely when:
+
+- `SIM_NO_UPDATE_CHECK` is set to anything but `0` or `false`
+- stderr is not a terminal, so redirected and piped output is never affected
+- a CI environment variable is present (`CI`, `GITHUB_ACTIONS`, `JENKINS_URL`,
+  `TEAMCITY_VERSION`, `BUILDKITE`)
+- the CLI is running under `npm exec` or `npx`, which may use a project-local or
+  ephemeral package where global-install advice is inappropriate
+- the CLI is running from a checkout of the sim repository, whose version
+  deliberately trails the published one
+- the installed version is a prerelease
+
+The daily pace comes from a timestamp in the config directory's
+`update-check.json`: `~/.sim/update-check.json` by default, or under
+`SIM_CONFIG_DIR` when that is set. `SIM_CONFIG_FILE` and
+`SIM_CREDENTIALS_FILE` do not move the cache, so it may not sit beside a file
+relocated with either of those variables.
+
+This throttle is best-effort across processes. Two commands that start together
+can both see a stale cache and check. Cache replacement is atomic, so either
+complete write can win without leaving a partially interleaved file. If the
+cache cannot be written — for example, because the config directory is
+read-only — every eligible invocation attempts a check because there is no
+timestamp to reuse.
+
+The registry check has a one-second deadline. On expiry, the CLI terminates its
+short-lived request process so stalled DNS, connection, or response work cannot
+remain active and delay the command. `SIM_NO_UPDATE_CHECK=1` still turns the
+check off.
+
+The command the notice prints matches how Sim was installed — `npm install -g`,
+`pnpm add -g`, `bun add -g`, or `yarn global add` — so running it updates the
+executable already on your `PATH` rather than installing a second copy under a
+different package manager.
+
+Node's `fetch` uses `HTTP(S)_PROXY` when opted in with `NODE_USE_ENV_PROXY=1`
+(Node 22.21+ or 24.0+) or `--use-env-proxy` (Node 22.21+ or 24.5+).
 
 For CI, set `SIM_API_KEY` and `SIM_WORKSPACE` and nothing needs to touch the
 filesystem at all.

apps/docs/content/docs/cli/files.mdx

@@ -108,6 +108,8 @@ Also available as `sim files folders ls`.
 | `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
+| `--recursive <value>` | No | Whether parentPath includes every descendant instead of direct children only. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
+| `--depth <value>` | No | Deepest level below parentPath to include when recursive is true. |
 
 </CommandTable>
 
@@ -172,6 +174,32 @@ sim files delete <fileId> [options]
 
 </CommandTable>
 
+## Apply one exact or anchor-based edit to a text file
+
+```bash
+sim files edit <fileId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `fileId` | Yes | File identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--edit <json\|@file>` | Yes | One edit object: &#123;"mode":"search_replace","search":"old","content":"new","replaceAll":false&#125;, &#123;"mode":"replace_between","beforeAnchor":"start line","afterAnchor":"end line","content":"new"&#125;, &#123;"mode":"insert_after","anchor":"line","content":"new"&#125;, or &#123;"mode":"delete_between","startAnchor":"first line deleted","endAnchor":"ending line kept"&#125;. Anchored modes also accept occurrence starting at 1 (JSON, or @path / @- to read a file or stdin). |
+
+</CommandTable>
+
 ## Show file metadata and sharing status
 
 ```bash
@@ -310,6 +338,8 @@ sim files read <fileId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
+| `--offset <value>` | No | First line to return, 1-based. Absent starts at the first line. |
+| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |
 
 </CommandTable>
 
@@ -355,6 +385,27 @@ sim files restore <fileId>
 
 </CommandTable>
 
+## Search file content
+
+```bash
+sim files search [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--query <value>` | Yes | Regular expression, or exact text when `mode` is `exact`. |
+| `--mode <value>` | No | How `query` is read. Accepted values: `exact`, `regex`. |
+| `--max-results <value>` | No | Maximum matching lines to return. |
+| `--folder <value...>` | No | Folders to search, by path as shown in the app; omit to search the whole workspace (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--include-subfolders` | No | Whether each folder scope includes nested folders; on by default. |
+| `--no-include-subfolders` | No | Send --include-subfolders as false. |
+
+</CommandTable>
+
 ## Unzip an archive into a new folder beside it
 
 ```bash

apps/docs/content/docs/cli/reference.mdx

@@ -788,6 +788,8 @@ Also available as `sim files folders ls`.
 | `--sort-by <value>` | No | Field used to sort the result. Sorting by `name` is case-sensitive and follows the storage collation, so do not rely on a case-insensitive order. Accepted values: `name`, `createdAt`, `updatedAt`. |
 | `--sort-order <value>` | No | Sort direction. Accepted values: `asc`, `desc`. |
 | `--scope <value>` | No | Which lifecycle set to list: `active` (default) returns live folders only; `archived` returns folders a recursive delete soft-deleted, which is how a caller finds a path to hand to the folder restore. Authorization is identical for both. Accepted values: `active`, `archived`. |
+| `--recursive <value>` | No | Whether parentPath includes every descendant instead of direct children only. Accepted values: `true`, `1`, `yes`, `on`, `y`, `enabled`, `false`, `0`, `no`, `off`, `n`, `disabled`. |
+| `--depth <value>` | No | Deepest level below parentPath to include when recursive is true. |
 
 </CommandTable>
 
@@ -858,6 +860,34 @@ sim files delete <fileId> [options]
 
 </CommandTable>
 
+### sim files edit
+
+Apply one exact or anchor-based edit to a text file
+
+```bash
+sim files edit <fileId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `fileId` | Yes | File identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--edit <json\|@file>` | Yes | One edit object: &#123;"mode":"search_replace","search":"old","content":"new","replaceAll":false&#125;, &#123;"mode":"replace_between","beforeAnchor":"start line","afterAnchor":"end line","content":"new"&#125;, &#123;"mode":"insert_after","anchor":"line","content":"new"&#125;, or &#123;"mode":"delete_between","startAnchor":"first line deleted","endAnchor":"ending line kept"&#125;. Anchored modes also accept occurrence starting at 1 (JSON, or @path / @- to read a file or stdin). |
+
+</CommandTable>
+
 ### sim files describe
 
 Show file metadata and sharing status
@@ -1006,6 +1036,8 @@ sim files read <fileId> [options]
 | Option | Required | Description |
 | --- | --- | --- |
 | `--max-bytes <value>` | No | Optional ceiling on the source bytes fed to the parser, lowering but never raising the server limit. |
+| `--offset <value>` | No | First line to return, 1-based. Absent starts at the first line. |
+| `--limit <value>` | No | How many lines to return from `offset`. Absent reads to the end. |
 
 </CommandTable>
 
@@ -1055,6 +1087,29 @@ sim files restore <fileId>
 
 </CommandTable>
 
+### sim files search
+
+Search File Content
+
+```bash
+sim files search [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--query <value>` | Yes | Regular expression, or exact text when `mode` is `exact`. |
+| `--mode <value>` | No | How `query` is read. Accepted values: `exact`, `regex`. |
+| `--max-results <value>` | No | Maximum matching lines to return. |
+| `--folder <value...>` | No | Folders to search, by path as shown in the app; omit to search the whole workspace (space-separated, or @path / @- with one value per line; @@value for a literal leading @). |
+| `--include-subfolders` | No | Whether each folder scope includes nested folders; on by default. |
+| `--no-include-subfolders` | No | Send --include-subfolders as false. |
+
+</CommandTable>
+
 ### sim files unzip
 
 Unzip an archive into a new folder beside it

apps/docs/content/docs/cli/troubleshooting.mdx

@@ -3,6 +3,8 @@ title: Troubleshooting
 description: The failures whose cause is not obvious from the error message
 ---
 
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
+
 Errors print one line to stderr, prefixed `Error:`, and exit `1` — except
 `sim whoami`, which exits `2` when it could not reach the API to check at all.
 Most say what to do next; the cases below are the ones that do not.
@@ -85,6 +87,50 @@ editing the file by hand:
 sim --output table configure --set-output json
 ```
 
+## A command is missing that the documentation describes
+
+The docs track the current release, so a command that exists here and not in
+`sim --help` usually means the installed CLI is older than the feature. Compare
+`sim --version` against the published version and upgrade:
+
+```bash
+sim --version
+```
+
+Then upgrade with the package manager you installed it with — using a different
+one installs a second copy instead of replacing the executable on your `PATH`:
+
+<Tabs items={['npm', 'pnpm', 'bun']}>
+  <Tab value="npm">
+    ```bash
+    npm install -g sim@latest
+    ```
+  </Tab>
+  <Tab value="pnpm">
+    ```bash
+    pnpm add -g sim@latest
+    ```
+  </Tab>
+  <Tab value="bun">
+    ```bash
+    bun add -g sim@latest
+    ```
+  </Tab>
+</Tabs>
+
+The CLI can also tell you this through a cached daily check on eligible
+invocations, and the command it prints already matches your installation. It
+stays quiet when stderr is redirected, in CI, and under `npm exec` or `npx`.
+
+## An update notice appears in output I am parsing
+
+It should not: the notice is written to stderr, never stdout, so `--output json`
+piped to `jq` is unaffected. If something merges the two streams, silence it:
+
+```bash
+export SIM_NO_UPDATE_CHECK=1
+```
+
 ## Anything else
 
 An unexpected error prints a stack trace. That is a bug in the CLI — please