Merge remote-tracking branch 'origin/sm/trigger-templates' into sm/conflicts-view-in-metadata

Author: mshanemc

.claude/agents/doc-maintenance.md

@@ -0,0 +1,33 @@
+---
+name: doc-maintenance
+description: AI-powered doc maintenance. Invoked when code changes may have left docs stale. Fixes docs directly; runs in background.
+model: fast
+---
+
+Fix docs when code/config/scripts change. Run in background; fix directly; report what was fixed.
+
+## Scope
+
+- **In scope**: .claude/skills/, .claude/agents/, .cursor/rules/, docs/, contributing/, packages/\*\*/README.md
+- **Excluded**: **/\*.plan.md, **/plan.md
+
+## Responsibilities (priority order)
+
+1. **Code→doc drift**: Recent changes (git diff, session context) that require doc updates
+   - Command IDs, API changes, new features, removed exports
+   - package.json scripts/commands, esbuild config, scripts/
+   - .vscodeignore, .vscode (launch/tasks/extensions), tsconfig, .esbuild-web-extra-settings.json, .github workflows
+2. **Broken links** in docs
+3. **Duplication** — replace with cross-links
+
+## Workflow
+
+1. `git diff HEAD` (or session context) to identify recent changes
+2. Cross-reference docs: docs/, .claude/skills/, .claude/agents/, .cursor/rules/, contributing/, packages/\*\*/README.md
+3. Fix issues directly (edit files)
+4. Report what was fixed (for transparency)
+
+## Style
+
+- **.claude/, .cursor/rules/, docs/, contributing/**: Apply concise skill (fragments, remove words). See .claude/skills/concise/SKILL.md.
+- **packages/\*\*/README.md**: Customer-facing, marketplace. Use full sentences, original tone. Do NOT apply concise.

.claude/agents/playwright-e2e-monitor.md

@@ -1,7 +1,7 @@
 ---
 name: playwright-e2e-monitor
 description: Monitor and analyze Playwright E2E test results from GitHub Actions. Use when users ask for playwright analysis on github actions or /analyze-e2e
-model: composer-1
+model: fast
 ---
 
 Monitor running e2e playwright tests, download artifacts on failure, provide analysis.

.claude/skills/concise/SKILL.md

@@ -4,6 +4,8 @@ description: Writing style for AI-consumed docs. Proactively apply when creating
 disable-model-invocation: false
 ---
 
+**Excluded**: packages/\*\*/README.md — customer-facing, marketplace; use full sentences.
+
 # Concise
 
 Save tokens and preserve context window.

.claude/skills/effect-best-practices/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: effect-best-practices
 description: Enforces Effect-TS patterns for services, errors, layers, and atoms. Use when writing code with Effect.Service, Schema.TaggedError, Layer composition, or effect-atom React components.
-version: 1.1.0
+version: 1.2.0
 ---
 
 # Effect-TS Best Practices
@@ -31,7 +31,7 @@ npx effect-language-service diagnostics --project tsconfig.json
 | Error Specificity | `UserNotFoundError`, `SessionExpiredError`               | Generic `NotFoundError`, `BadRequestError`                       |
 | Error Handling    | `catchTag`/`catchTags`; catch only when needed           | `catchAll`; swallowing; catching "just in case"                  |
 | IDs               | `Schema.UUID.pipe(Schema.brand("@App/EntityId"))`        | Plain `string` for entity IDs                                    |
-| Functions         | `Effect.fn("Service.method")`                            | Anonymous generators                                             |
+| Functions         | `Effect.fn` over `Effect.gen`; `.gen` only for shared pipes | Anonymous generators; `.gen` for business logic                   |
 | Params vs deps    | Params = runtime data; dependencies = yield from context | Passing Ref/PubSub/service as params                             |
 | Naming            | `FooCommand` for commands, domain names for helpers      | `FooEffect` suffix (redundant; TS/Effect.fn already convey type) |
 | Logging           | `Effect.log` with structured data                        | `console.log`                                                    |
@@ -266,9 +266,11 @@ export type CreateUserInput = Schema.Schema.Type<typeof CreateUserInput>;
 
 See `references/schema-patterns.md` for transforms and advanced patterns.
 
-## Function Pattern with Effect.fn
+## Function Pattern: Prefer Effect.fn over Effect.gen
 
-**Always use `Effect.fn`** for service methods. This provides automatic tracing with proper span names. Span name is required; enforced by `local/require-effect-fn-span-name`.
+**Prefer `Effect.fn`** for effectful code. Provides automatic tracing with proper span names. Span name required; enforced by `local/require-effect-fn-span-name`.
+
+**Use `Effect.gen` only when** you need a shared effect with common `.pipe` attached so multiple consumers don't each pipe the same things — e.g. provided dependencies, common error handlers, retries. (Less common with Runtimes.) Service definition bodies are a valid use (shared wiring).
 
 ```typescript
 // CORRECT - Effect.fn with descriptive name

.claude/skills/feature-branch/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: feature-branch
+description: Create feature branches for all work. Use when creating branches, checking out, or pushing. Prevents accidental push to develop.
+---
+
+# Feature Branch
+
+All work must be on feature branches. Never commit directly to develop or main.
+
+## Do
+
+```bash
+git fetch origin develop
+git checkout develop
+git pull
+git checkout -b feature/W-XXXXX
+# ... work, commit ...
+git push -u origin feature/W-XXXXX
+```
+
+Or, branch from remote without tracking it:
+
+```bash
+git fetch origin develop
+git checkout -b feature/W-XXXXX origin/develop --no-track
+```
+
+## Don't
+
+**Never** `git checkout -b feature/W-XXXXX origin/develop` without `--no-track`.
+
+That sets the new branch to track `origin/develop`. A bare `git push` would then push to develop instead of creating a remote feature branch.
+
+## Summary
+
+- All work on feature branches
+- Use `--no-track` when branching from `origin/<base>`, or branch from local `<base>` after pull
+- Always push with explicit branch: `git push -u origin feature/W-XXXXX`

.claude/skills/playwright-e2e/SKILL.md

@@ -15,12 +15,17 @@ Guidelines for writing and iterating on Playwright tests for VS Code extensions.
 - `references/local-setup.md` - Scratch org setup (Dreamhouse, minimal, non-tracking)
 - `references/iterating-playwright-tests.md` - Iterating on tests ("Things to ignore" for failure analysis)
 - `references/analyze-e2e.md` - Analyzing E2E test results from CI
-- `references/local-setup.md` - Local scratch org setup for E2E tests
 
 # Use playwright-vscode-ext
 
 Shared code (helpers, locators, configuration) for tests.
 
+**Desktop workspace shapes (pick one per test):**
+
+- **No folder open** — fixture opens a Salesforce project, then call `prepareNoFolderOpenForPaletteTests(page)` (runs `Workspaces: Close Workspace` + workbench wait). Or use `closeWorkspaceToEmptyWindow` if UI is already prepared.
+- **Folder open, no `sfdx-project.json`** — `createDesktopTest({ emptyWorkspace: true })`; workspace path comes from `createEmptyTestWorkspace()` (also exported from the package).
+- **Default org in workspace** — pass `orgAlias: '…'` (e.g. `MINIMAL_ORG_ALIAS` / `DREAMHOUSE_ORG_ALIAS`) so `.sfdx/config.json` gets `target-org`. Omit `orgAlias` or use `undefined` for **no** `config.json` (no org).
+
 ## Span files (when debugging traces)
 
 Local only — span export disabled in CI/GHA.

.claude/skills/playwright-e2e/references/iterating-playwright-tests.md

@@ -11,14 +11,12 @@ Scratch org setup: see `references/local-setup.md`.
 1. run `web` locally (use `--retries 0`, follow debugging tips)
 2. run `desktop` locally (use `--retries 0`)
 
-**Passing args:** Use `--` to forward params to the underlying command, e.g. `npm run test:web -w <package> -- --retries 0` or `npm run test:desktop -w <package> -- --retries 0`
-3. edit github workflows if needed
-4. CI (windows, gha) - see `analyze-e2e.md` for monitoring and analyzing results
+**Passing args:** Use `--` to forward params to the underlying command, e.g. `npm run test:web -w <package> -- --retries 0` or `npm run test:desktop -w <package> -- --retries 0` 3. edit github workflows if needed 4. CI (windows, gha) - see `analyze-e2e.md` for monitoring and analyzing results
 
 After passing, clean up while keeping tests passing:
 
 1. remove fallbacks, waits, "try another way"
-2. align with `coding-playwright-tests.mdc` rules
+2. align with `coding-playwright-tests.md` rules
 3. consolidate locators, increase DRY/reuse
 4. ensure playwright-ext exports are used by other extensions
 5. verify compile/lint pass (`@.claude/skills/verification/`)

.claude/skills/playwright-e2e/references/local-setup.md

@@ -24,7 +24,7 @@ Prereq: authenticated Dev Hub (`sf org login web --set-default-dev-hub` or simil
 ```bash
 mkdir -p /tmp/minimal-project/force-app
 echo '{"packageDirectories":[{"path":"force-app","default":true}],"namespace":"","sfdcLoginUrl":"https://login.salesforce.com","sourceApiVersion":"64.0"}' > /tmp/minimal-project/sfdx-project.json
-cd /tmp/minimal-project && sf org create scratch -d -w 10 -a minimalTestOrg --wait 30 --json
+cd /tmp/minimal-project && sf org create scratch -d -w 10 -a minimalTestOrg --edition developer --json
 ```
 
 ## Non-tracking
@@ -36,7 +36,7 @@ cd /tmp/minimal-project && sf org create scratch -d -w 10 -a minimalTestOrg --wa
 ```bash
 mkdir -p /tmp/non-tracking-project/force-app
 echo '{"packageDirectories":[{"path":"force-app","default":true}],"namespace":"","sfdcLoginUrl":"https://login.salesforce.com","sourceApiVersion":"64.0"}' > /tmp/non-tracking-project/sfdx-project.json
-cd /tmp/non-tracking-project && sf org create scratch -d -w 10 -a nonTrackingTestOrg --wait 30 --no-track-source --json
+cd /tmp/non-tracking-project && sf org create scratch -d -w 10 -a nonTrackingTestOrg --edition developer --no-track-source --json
 ```
 
 **Note:** Non-tracking test skips on web locally — requires Dev Hub aliased as `hub`. Desktop and CI work.

.claude/skills/pr-draft/SKILL.md

@@ -16,7 +16,7 @@ Draft PR titles and bodies per salesforcedx-vscode conventions. Requires a Gus w
 1. If branch name contains `W-XXXXX`, confirm it exists in GUS, resembles the work done on the branch, and use that
 2. Else ask: "Do you have a Gus work item (W-XXXXX) for this PR?"
 3. If yes → try to find it using [gus-cli/SKILL.md](../gus-cli/SKILL.md). Confirm with the user that you got it right, or ask them to choose if several could be right.
-4. If no → offer to create via Gus. Follow [gus-cli/SKILL.md](../gus-cli/SKILL.md). **Before creating:** show user Subject, Epic, Details, assignee. Ask: "Create this work item?" Do not run `sf data create record` until user says yes.
+4. If no → offer to create via Gus. Follow [gus-cli/SKILL.md](../gus-cli/SKILL.md). **Before creating:** show user Subject, Epic, Details, assignee. Ask: "Create this work item?" Do not run `sf data create record` until user says yes. If user declines creation and still wants to proceed with the PR, include `[skip-validate-pr]` in the PR body.
 5. Before creating PR: push current branch to remote if it doesn't already exist (`git push -u origin $(git branch --show-current)` or equivalent). Never push to `develop`/`main`
 6. After PR created: update work item `Details__c` with PR link. Query current `Details__c`, append `"\nPR: <url>"` (or prepend if empty). **Before updating:** show user the new Details\_\_c. Ask: "Update work item with PR link?" Do not run `sf data update record` until user says yes.
 7. After PR created: offer Ready for Review. Ask: "Put WI in Ready for Review? Who should review?" Choices:
@@ -40,9 +40,12 @@ Draft PR titles and bodies per salesforcedx-vscode conventions. Requires a Gus w
 
 ## Body format
 
-- Write body content per [concise/SKILL.md](../concise/SKILL.md)
+- Base body on branch commits only
+- Ignore plans/conversation history (may be stale)
+- Write content per [concise/SKILL.md](../concise/SKILL.md)
 - Include `@W-XXXXX@` in "What issues does this PR fix or reference?" per [.github/PULL_REQUEST_TEMPLATE.md](../../../.github/PULL_REQUEST_TEMPLATE.md):
-- Delete the before/after section if you have nothing to say there
+- Delete before/after section if empty
+- **User declined WI:** If user explicitly declines WI but wants PR, include `[skip-validate-pr]` in body (e.g. at end)
 
 ```
 ### What issues does this PR fix or reference?

.claude/skills/services-extension-consumption/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: services-extension-consumption
-description: Guidelines for consuming salesforcedx-vscode-services extension API. Use when working with extensions that have extensionDependency on salesforcedx-vscode-services, registering commands, using Workspace/Connection/Project/Settings/FS/Channel/Media services, or implementing file/config watchers.
+description: Guidelines for consuming salesforcedx-vscode-services extension API. Use when working with extensions that have extensionDependency on salesforcedx-vscode-services, registering commands, using Workspace/Connection/Project/Settings/FS/Channel/Media services, quickpick/quickInput, or implementing file/config watchers.
 ---
 
 # Consuming salesforcedx-vscode-services
@@ -33,13 +33,13 @@ Shares singleton instances (caches, watchers) across extensions; avoids re-build
 
 Per-extension layers (must build yourself):
 
-| Layer | Why |
-|---|---|
-| `ChannelServiceLayer(displayName)` | Own output channel |
-| `ErrorHandlerService.Default` | Depends on own ChannelService |
-| `ExtensionContextServiceLayer(context)` | Own `ExtensionContext` |
-| `SdkLayerFor(context)` | Own tracer (extension name/version in resource attributes) |
-| `ExtensionProviderServiceLive` | Local singleton |
+| Layer                                   | Why                                                        |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `ChannelServiceLayer(displayName)`      | Own output channel                                         |
+| `ErrorHandlerService.Default`           | Depends on own ChannelService                              |
+| `ExtensionContextServiceLayer(context)` | Own `ExtensionContext`                                     |
+| `SdkLayerFor(context)`                  | Own tracer (extension name/version in resource attributes) |
+| `ExtensionProviderServiceLive`          | Local singleton                                            |
 
 ## ExtensionContext Setup
 
@@ -74,20 +74,32 @@ In `activate`:
 export const activate = async (context: vscode.ExtensionContext): Promise<void> => {
   const extensionScope = Effect.runSync(getExtensionScope());
   setAllServicesLayer(buildAllServicesLayer(context));
-  await Effect.runPromise(activateEffect(context).pipe(Effect.provide(AllServicesLayer), Scope.extend(extensionScope)));
+  await getRuntime().runPromise(activateEffect(context).pipe(Scope.extend(extensionScope)));
 };
 ```
 
+## Runtime vs provide
+
+- **Do**: Build `ManagedRuntime.make(AllServicesLayer)` and export `getRuntime()`.
+- **Do**: Use `getRuntime().runPromise(effect)` / `runFork(effect)` for ad-hoc execution.
+- **Don't**: Use `Effect.provide(AllServicesLayer)` at call sites — use the runtime instead.
+- **Exception**: `registerCommandWithLayer(AllServicesLayer)` — keep passing the Layer; it internally uses provide.
+
 ## Registering Commands
 
-Use `registerCommandWithLayer` pre-loaded with AllServicesLayer:
+Use `registerCommandWithLayer` (for layers) or `registerCommandWithRuntime` (for runtimes):
 
 ```typescript
 import { myCommandEffect } from './commands/myCommand';
 
 const api = yield * (yield * ExtensionProviderService).getServicesApi;
+
+// Using Layer
 const registerCommand = api.services.registerCommandWithLayer(AllServicesLayer);
+yield * registerCommand('sf.my.command', myCommandEffect);
 
+// Using Runtime
+const registerCommand = api.services.registerCommandWithRuntime(getRuntime());
 yield * registerCommand('sf.my.command', myCommandEffect);
 ```
 
@@ -96,6 +108,7 @@ Commands auto:
 - Register with ExtensionContext subscriptions
 - Wrap with error handling
 - Trace with observability spans
+- Handle Cancellation
 
 ## Basic Services
 
@@ -109,21 +122,29 @@ Accessor pattern: call methods directly, don't assign to variable first.
 - [SettingsService](references/settings-service.md) - Settings read/write
 - [FsService](references/fs-service.md) - File ops (web-compatible) and uri/path conversion
 - [EditorService](references/editor-service.md) - Active editor changes and current URI
+- [Prompts](references/prompts.md) - QuickPick, InputBox, and UserCancellationError handling
 
 ## Watchers
 
 ### File Watching
 
-Watch file changes:
+FileWatcherService exposes a PubSub of all workspace file changes (`**/*`). Subscribe and filter:
 
 ```typescript
-const watcher = yield * api.services.FileWatcherService.watchFiles(pattern, options);
+import * as PubSub from 'effect/PubSub';
+import * as Stream from 'effect/Stream';
+
+const fileWatcher = yield * api.services.FileWatcherService;
+const dequeue = yield * PubSub.subscribe(fileWatcher.pubsub);
 
 yield *
-  Stream.runForEach(watcher, event =>
-    Effect.sync(() => {
-      // Handle file change
-    })
+  Stream.fromQueue(dequeue).pipe(
+    Stream.filter(event => /* match event.uri to your pattern */),
+    Stream.runForEach(event =>
+      Effect.sync(() => {
+        // Handle event: { type: 'create'|'change'|'delete', uri }
+      })
+    )
   );
 ```
 
@@ -160,29 +181,29 @@ yield *
 
 ### Target Org Changes
 
-Watch org changes via `TargetOrgRef`:
+Watch org changes via `TargetOrgRef` (SubscriptionRef):
 
 ```typescript
-const targetOrgRef = yield * api.services.TargetOrgRef();
+const ref = yield * api.services.TargetOrgRef();
 yield *
-  Effect.forkDaemon(
-    targetOrgRef.changes.pipe(
-      Stream.map(org => org.orgId),
-      Stream.changes,
-      Stream.tap(orgId => {
-        // Handle org change
-      }),
-      Stream.runForEach(() => {
-        // Refresh UI, invalidate caches, etc.
-      })
-    )
+  ref.changes.pipe(
+    Stream.map(org => org.orgId),
+    Stream.changes,
+    Stream.tap(orgId => {
+      // Handle org change
+    }),
+    Stream.runForEach(() => {
+      // Refresh UI, invalidate caches, etc.
+    })
   );
 ```
 
 ## Complete Example Pattern
 
 ```typescript
 // extensionProvider.ts
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+
 export const buildAllServicesLayer = (context: ExtensionContext) =>
   Layer.unwrapEffect(
     Effect.gen(function* () {
@@ -204,6 +225,18 @@ export const buildAllServicesLayer = (context: ExtensionContext) =>
     }).pipe(Effect.provide(ExtensionProviderServiceLive))
   );
 
+export let AllServicesLayer: ReturnType<typeof buildAllServicesLayer>;
+export const setAllServicesLayer = (layer: ReturnType<typeof buildAllServicesLayer>) => {
+  AllServicesLayer = layer;
+};
+
+const createRuntime = () => ManagedRuntime.make(AllServicesLayer);
+let _runtime: ReturnType<typeof createRuntime> | undefined;
+export const getRuntime = () => {
+  _runtime ??= createRuntime();
+  return _runtime;
+};
+
 // index.ts
 import { myCommandEffect } from './commands/myCommand';
 
@@ -228,3 +261,4 @@ export const activateEffect = Effect.fn(`activation:${EXTENSION_NAME}`)(function
 - Pass `context` to `SdkLayerFor` (extracts name/version from ExtensionContext)
 - `Effect.forkIn(..., yield* getExtensionScope())` for watcher cleanup on deactivation
 - `registerCommandWithLayer` for all commands (tracing + error handling)
+- Use `getRuntime().runPromise` / `runFork` instead of `Effect.provide(AllServicesLayer)` for execution