obsidian-dev-skills 1.2.0 → 1.2.2

package/obsidian-ops/references/scorecard-compliance.md

@@ -92,6 +92,7 @@ on:
   push:
     tags:
       - "*"
+  workflow_dispatch:
 
 permissions:
   contents: write
@@ -110,6 +111,8 @@ jobs:
           cache: "pnpm"
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
+      - id: version
+        run: echo "version=$(jq -r .version manifest.json)" >> "$GITHUB_OUTPUT"
       - uses: actions/attest-build-provenance@v2
         with:
           subject-path: |
@@ -118,10 +121,10 @@ jobs:
             manifest.json
       - env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ github.ref_name }}
+          VERSION: ${{ steps.version.outputs.version }}
         run: |
-          gh release create "$TAG" \
-            --title="$TAG" \
+          gh release create "$VERSION" \
+            --title="$VERSION" \
             --generate-notes \
             main.js styles.css manifest.json
 ```
@@ -134,6 +137,62 @@ Then cut releases by pushing a tag (e.g. `git tag 0.1.0 && git push origin 0.1.0
 
 **Fix**: merge the two rule blocks. If they target the same selector and have non-overlapping properties, combine into one block. If they target the same selector and one is meant to override the other (e.g. inside a media query), wrap the override in a more specific selector or use a CSS variable.
 
+### `!important` declarations
+
+> Avoid `!important`. Override styles by increasing selector specificity or using CSS variables instead.
+
+The fix is almost never to keep `!important` and hope the scorecard ignores it. Instead, scope the rule with a parent class so it wins the cascade naturally.
+
+```css
+/* Wrong: leans on !important to beat Obsidian's defaults */
+.my-plugin-btn {
+  border: none !important;
+  background: none !important;
+}
+
+/* Right: parent class boosts specificity, no !important needed */
+.my-plugin-panel .my-plugin-btn {
+  border: none;
+  background: none;
+}
+```
+
+The parent class is whatever wrapper the plugin's UI lives inside (e.g. the panel root, settings container). For toggle classes that need to beat an element's natural display, chain the toggle class with the base class for the same specificity boost: `.my-plugin-panel .my-toggle-hidden { display: none; }`.
+
+### `:has()` selector
+
+> Avoid `:has()`. It can cause significant performance issues due to broad selector invalidation.
+
+Most uses of `:has()` are stylistic preferences that can be rewritten as descendant selectors targeting the child element directly.
+
+```css
+/* Wrong: re-styles the parent based on a descendant */
+.result:has(a[href*="http"]) {
+  word-break: break-all;
+}
+
+/* Right: targets the child directly */
+.result a[href*="http"] {
+  word-break: break-all;
+}
+```
+
+If the rule genuinely needs to style a parent based on a child's presence, fall back to adding a marker class via TypeScript when the child is appended (e.g. `parentEl.addClass('has-external-link')`).
+
+### Don't override global Obsidian UI selectors
+
+A plugin's `styles.css` is loaded globally. Rules targeting Obsidian's built-in classes affect every other plugin and Obsidian itself, not just yours.
+
+```css
+/* Wrong: forces flex layout on every menu in Obsidian, not just this plugin's */
+.menu .menu-item {
+  display: flex !important;
+  justify-content: space-between !important;
+}
+```
+
+**Fix**: either remove the rule and accept Obsidian's default styling, or scope it. Menus appended outside your plugin's panel (via `new Menu()`) can't be scoped via parent class, so the rule has to be removed, or a marker class added when the menu is opened. The scorecard does not specifically flag this leak, but it's a hygiene rule that prevents conflicts with other plugins.
+
 ### `obsidianmd` ESLint rules (Warnings and Risks)
 
 `eslint-plugin-obsidianmd` enforces Obsidian-idiomatic patterns. Common signals and fixes:
@@ -154,6 +213,18 @@ this.countEl.setText('0 Selected');
 
 **Never disable this rule.** The scorecard explicitly flags `eslint-disable-next-line obsidianmd/ui/sentence-case` as a Risk and counts each occurrence. If a string genuinely cannot be sentence case (e.g. it embeds a proper noun or product name), fix the casing instead of disabling.
 
+**Configure the rule for domain-specific acronyms.** The rule accepts `acronyms`, `brands`, `ignoreWords`, and `ignoreRegex` options. Use these when your plugin legitimately uses acronyms or quoted button names that the rule otherwise rejects.
+
+```js
+// eslint.config.mjs
+"obsidianmd/ui/sentence-case": ["error", {
+  acronyms: ["SEO", "MDX", "URL", "CSV", "H1", "H2", "H3", "H4", "H5", "H6"],
+  ignoreRegex: ['"[^"]+"'],  // ignore content inside double quotes (referenced button/control names)
+}]
+```
+
+This is the right answer when the autofix expected output is something like `'Open seo audit panel'` (downcased acronym) but the string genuinely should read `'Open SEO audit panel'`. Configuring the rule is preferred over per-line disables, which are forbidden, or awkward rephrasing.
+
 #### `obsidianmd/prefer-create-el-shorthand` (Warning)
 
 Use `createDiv()` and `createSpan()` instead of `createEl('div')` and `createEl('span')`.

package/obsidian-ops/references/versioning-releases.md

@@ -31,6 +31,7 @@ on:
   push:
     tags:
       - "*"
+  workflow_dispatch:
 
 permissions:
   contents: write
@@ -49,6 +50,8 @@ jobs:
           cache: "pnpm"
       - run: pnpm install --frozen-lockfile
       - run: pnpm build
+      - id: version
+        run: echo "version=$(jq -r .version manifest.json)" >> "$GITHUB_OUTPUT"
       - uses: actions/attest-build-provenance@v2
         with:
           subject-path: |
@@ -57,18 +60,60 @@ jobs:
             manifest.json
       - env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TAG: ${{ github.ref_name }}
+          VERSION: ${{ steps.version.outputs.version }}
         run: |
-          gh release create "$TAG" \
-            --title="$TAG" \
-            --generate-notes \
-            main.js styles.css manifest.json
+          if gh release view "$VERSION" >/dev/null 2>&1; then
+            gh release upload "$VERSION" main.js styles.css manifest.json --clobber
+          else
+            gh release create "$VERSION" \
+              --title="$VERSION" \
+              --generate-notes \
+              main.js styles.css manifest.json
+          fi
 ```
 
+**Why read the version from `manifest.json`**: the workflow runs from either a tag push (where `github.ref_name` is the tag) or a `workflow_dispatch` from a branch (where `github.ref_name` is the branch name, e.g. `master`). Using `github.ref_name` directly would title a manually-triggered release after the branch. Reading from `manifest.json` is consistent across both triggers and matches what Obsidian's plugin loader actually reads.
+
 Cut releases by pushing a tag (`git tag 0.1.0 && git push origin 0.1.0`). The workflow attaches the three required assets and registers the attestation. The scorecard's "Build verified" signal also fires once the workflow has run, because the attested artifacts can be reproduced byte-for-byte from source.
 
 For the full set of scorecard signals and their fixes, see [scorecard-compliance.md](scorecard-compliance.md).
 
+### Pushing tags so the workflow actually fires
+
+Push order matters. Push commits to the default branch **first**, in a separate command, then push the tag. If you push both in a single batch (`git push --tags --follow-tags` or some GUIs), GitHub occasionally processes the tag webhook before indexing the workflow file at that ref, and the trigger silently drops.
+
+```bash
+git push origin master           # commits first
+# pause a few seconds
+git push origin 0.1.0            # tag in a separate command
+```
+
+If the workflow does not fire on a tag push, diagnose with:
+
+```bash
+gh api repos/:owner/:repo/actions/runs --jq '.workflow_runs[0:5] | .[] | {id, event, status, conclusion, head_branch, created_at}'
+gh workflow list
+gh api repos/:owner/:repo/actions/permissions/workflow
+```
+
+If `gh api .../runs` is empty for the tag, the trigger was dropped. Recovery options:
+
+- **Add `workflow_dispatch:` to the trigger** so you can re-run from the Actions tab without a re-push.
+- **Re-push the tag**: `git push origin :refs/tags/0.1.0 && git push origin 0.1.0`.
+- **Manually create the release** in the GitHub UI. The release will exist but it will not have the build provenance attestation, which costs scorecard points until the next release.
+
+### Recovery trigger
+
+It is worth adding a manual trigger alongside the tag-push trigger so future "the workflow didn't fire" situations have a one-click fix:
+
+```yaml
+on:
+  push:
+    tags:
+      - "*"
+  workflow_dispatch:
+```
+
 > [!NOTE]
 > Themes and plugins have different asset requirements and submission paths. Ensure you follow the correct flow for your project type.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-dev-skills",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Agent skills for Obsidian plugin and theme development, including community scorecard compliance, release workflow attestation, and dependency vulnerability hygiene.",
   "keywords": [
     "obsidian",