obsidian-dev-skills 1.1.4 → 1.2.1

package/README.md

@@ -49,6 +49,7 @@ node node_modules/obsidian-dev-skills/scripts/init.mjs
 - Obsidian API usage
 - Plugin lifecycle management
 - Command and settings implementation
+- `obsidianmd` ESLint rule patterns (`createDiv`/`createSpan`, `activeWindow`, `activeDocument`, sentence case)
 
 ### obsidian-theme-dev
 - CSS/SCSS development patterns
@@ -61,6 +62,9 @@ node node_modules/obsidian-dev-skills/scripts/init.mjs
 - Version management
 - Sync procedures
 - Testing and quality assurance
+- Obsidian community **scorecard compliance** mapping (vulnerable transitive dep handling via `pnpm.overrides`, duplicate CSS selector detection, ESLint rule violations)
+- Release workflow with **build provenance attestation** (`actions/attest-build-provenance@v2`)
+- Portable **`CONTRIBUTING.md` template** for the scorecard hygiene check
 
 ### obsidian-ref
 - API documentation
@@ -80,7 +84,10 @@ Each project should also have a `project/` skill in `.agent/skills/project/` tha
 
 ### Updating Skills
 
-When skills are updated in this repository, all linked projects automatically get the updates. No manual sync required.
+The update flow depends on how a project consumes this package:
+
+- **npm install (default)**: When this package publishes a new version, downstream projects pick up updates the next time they run `pnpm obsidian-dev-skills` (or the equivalent npx/manual command). The init script re-copies skill files into `.agent/skills/`.
+- **Sibling clone + symlinks (advanced)**: If a project symlinks `.agent/skills/<name>` to a sibling clone of this repository (e.g. via `scripts/setup-local.ps1`), updates appear instantly the moment files change here, with no per-project sync step.
 
 ### Tracking Sync Status
 

package/obsidian-ops/SKILL.md

@@ -29,7 +29,10 @@ This skill covers:
 
 - `references/build-workflow.md`: Standard build and development commands.
 - `references/release-readiness.md`: Checklist for ensuring a project is ready for release.
+- `references/scorecard-compliance.md`: Map of Obsidian community plugin scorecard signals to concrete fixes (vulnerability overrides, attestation workflow, CSS dedup, obsidianmd rules).
+- `references/contributing-template.md`: Portable CONTRIBUTING.md template for the scorecard hygiene check.
+- `references/security-privacy.md`: Developer policies, mandatory disclosures, and dependency vulnerability hygiene via `pnpm.overrides`.
 - `references/sync-procedure.md`: How to pull updates from reference repositories.
-- `references/versioning-releases.md`: Workflow for versioning and GitHub releases.
+- `references/versioning-releases.md`: Workflow for versioning and GitHub releases, including the build-provenance attestation pattern.
 - `references/troubleshooting.md`: Common issues and their resolutions.
 - `references/quick-reference.md`: One-page cheat sheet for common operations.

package/obsidian-ops/references/contributing-template.md

@@ -0,0 +1,96 @@
+<!--
+Source: Authored for Obsidian plugin scorecard compliance
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Update when the standard development setup changes
+Applicability: Plugin
+-->
+
+# CONTRIBUTING.md Template
+
+The Obsidian community scorecard's **Hygiene** check looks for a `CONTRIBUTING.md` at the repo root. The template below is portable across plugin repositories without modification, because it uses relative GitHub links (`../../issues`) and references generic plugin concepts.
+
+## When to drop in unmodified
+
+Use the template as-is when the repo:
+
+- Uses pnpm with the standard `pnpm dev`, `pnpm build`, `pnpm lint`, `pnpm lint:fix` scripts.
+- Builds `main.js`, `styles.css`, and `manifest.json` to the repo root.
+- Is licensed MIT.
+- Uses the house terminology rules (properties, Markdown capitalized).
+
+## When to customize
+
+Change the template only when:
+
+- The plugin uses npm/yarn/bun instead of pnpm (update the install/build commands).
+- The plugin has additional scripts the contributor needs to run (e.g. a separate test command).
+- The license is not MIT (update the License section).
+
+Do not customize the issue link — the relative `../../issues` form resolves correctly on any GitHub repo.
+
+## Template
+
+```markdown
+# Contributing
+
+Thanks for your interest in contributing. This document describes how to report issues, propose changes, and get a local development environment running.
+
+## Reporting issues
+
+- Search [existing issues](../../issues) before opening a new one.
+- For bugs, include: Obsidian version, plugin version, operating system, reproduction steps, and what you expected vs. what happened. Screenshots or a short screen recording help.
+- For feature requests, describe the use case and the problem the feature would solve, not just the proposed solution.
+
+## Development setup
+
+Requirements:
+
+- [Node.js](https://nodejs.org/) (LTS recommended)
+- [pnpm](https://pnpm.io/). This repo pins a specific version via `packageManager` in `package.json`.
+
+`​`​`bash
+pnpm install
+pnpm dev      # watch mode build
+pnpm build    # production build
+pnpm lint     # check code style
+pnpm lint:fix # auto-fix where possible
+`​`​`
+
+Build artifacts (`main.js`, `manifest.json`, `styles.css`) are produced at the repo root.
+
+To test against a real vault, point the build output at `<vault>/.obsidian/plugins/<plugin-id>/` (symlink the three files, or use a tool like [hot-reload](https://github.com/pjeby/hot-reload)).
+
+## Pull requests
+
+- Open an issue first for anything non-trivial so we can agree on direction before you spend time on it.
+- Keep PRs focused. One concern per PR is easier to review.
+- Run `pnpm lint` and `pnpm build` before submitting; CI will run these too.
+- Follow the existing code style. Use **"properties"** (not "frontmatter") when referring to YAML metadata. **"Markdown"** is always capitalized.
+- Update the README if you change user-facing behavior.
+
+## Code style
+
+- TypeScript strict mode, no `any` unless unavoidable.
+- Prefer Obsidian's API (`Vault`, `MetadataCache`, `Workspace`) over Node `fs` for vault access.
+- No network requests from the plugin runtime.
+
+## Releases
+
+Maintainers cut releases by bumping the version in `manifest.json`, `package.json`, and `versions.json`, committing, then tagging and pushing the tag. The release workflow builds and attaches `main.js`, `manifest.json`, and `styles.css` with build provenance attestation.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+```
+
+## Style notes
+
+- The template avoids em dashes (`—`); prefer periods, commas, or parentheses instead.
+- The template avoids the word "Claude" and any reference to AI assistance, since the file is user-facing documentation.
+- Headings use sentence case to match Obsidian UI conventions.
+
+## Related Documentation
+
+- [scorecard-compliance.md](scorecard-compliance.md) — covers every scorecard signal, not just the contributing guide.
+- [release-readiness.md](release-readiness.md) — broader pre-release checklist.
+- [versioning-releases.md](versioning-releases.md) — release workflow setup.

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

@@ -0,0 +1,376 @@
+<!--
+Source: Obsidian community plugin scorecard (community.obsidian.md/plugins/<id>)
+Last synced: See sync-status.json for authoritative sync dates
+Update frequency: Check the Obsidian community portal scorecard format for changes
+Applicability: Plugin
+-->
+
+# Community Plugin Scorecard Compliance
+
+The Obsidian community portal publishes an automated scorecard for every plugin. It scans the latest GitHub release plus the source repository and reports across four health categories (**Hygiene**, **Maintenance**, **Responsiveness**, **Adoption**) and a **Review** section that flags concrete issues from automated scans.
+
+This document maps the scorecard signals to concrete fixes you can apply. Use it when a user asks "why is my score low?" or "help me fix my plugin's scorecard."
+
+## Health Category Fixes
+
+### Hygiene
+
+The portal checks for four files at the repo root.
+
+| Signal                | Fix                                                                                                                                  |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Missing readme        | Add `README.md` describing the plugin's purpose, installation, usage, and screenshots.                                               |
+| Missing license       | Add `LICENSE` (MIT is typical).                                                                                                      |
+| Missing description   | Ensure `manifest.json` has a clear `description` field.                                                                              |
+| Missing contributing  | Add `CONTRIBUTING.md`. See [contributing-template.md](contributing-template.md) for a portable template.                             |
+
+### Maintenance, Responsiveness, Adoption
+
+These reflect commit cadence, issue close rate, install count, and stars. They are not directly fixable by editing files. Steer the user toward consistent maintenance habits rather than a one-shot fix.
+
+## Review Section Fixes
+
+The Review section is where most score improvement happens. Issues are grouped into **Risks**, **Warnings**, **Disclosures**, **Other**, and **Passed**.
+
+### Disclosures (informational, not fixable)
+
+Disclosures are not deductions, they are informational. Common ones for plugins:
+
+- **Vault Enumeration** — uses `vault.getFiles()`, `getMarkdownFiles()`, etc.
+- **Vault Read** — uses `vault.read()` or `vault.cachedRead()`.
+- **Vault Write** — uses `vault.modify()`, `vault.create()`, etc.
+- **Clipboard Access** — reads or writes the system clipboard.
+- **Malware scan not available** / **Vulnerable dependencies scan not available** — scanner-side limitations.
+
+Do not try to remove these. They reflect the plugin's actual API surface and the user should understand them when installing.
+
+### Vulnerable transitive dev dependencies
+
+The scanner reports advisories like:
+
+> Potentially vulnerable dependency `<pkg>` (via `<parent>`). Upgrade to version X or later.
+
+These are almost always **dev-only transitives** pulled in through `eslint`, `eslint-plugin-obsidianmd`, and `@typescript-eslint/*`. They never ship in `main.js`, but the scorecard still counts them.
+
+**Fix**: add a `pnpm.overrides` block to `package.json` that forces patched versions. Major-version-scoped ranges keep API compatibility while bumping the patch:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "minimatch@<3.1.3": "^3.1.3",
+      "minimatch@^4 || ^5 || ^6 || ^7 || ^8": "^8.0.5",
+      "minimatch@^9": "^9.0.6",
+      "picomatch@<2.3.2": "^2.3.2",
+      "picomatch@^3 || ^4": "^4.0.4",
+      "brace-expansion@<1.1.13": "^1.1.13",
+      "brace-expansion@^2": "^2.0.3",
+      "ajv@<6.14.0": "^6.14.0",
+      "ajv@^7 || ^8": "^8.18.0",
+      "flatted@<3.4.0": "^3.4.0",
+      "fast-uri@<3.1.1": "^3.1.1",
+      "yaml@<2.8.3": "^2.8.3"
+    }
+  }
+}
+```
+
+Then run `pnpm install` and `pnpm why <pkg>` to verify the patched version is resolved.
+
+**Why this format**: pnpm override selectors match against resolved versions. The `package@<range>` key form lets you target one major at a time. A bare `package: "version"` would force every consumer to the same major and break anything depending on a different one.
+
+### Missing GitHub artifact attestation
+
+> X release assets are missing a GitHub artifact attestation.
+
+**Fix**: add a release workflow that runs `actions/attest-build-provenance@v2` against the release files. Drop this at `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+  id-token: write
+  attestations: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: |
+            main.js
+            styles.css
+            manifest.json
+      - env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG" \
+            --title="$TAG" \
+            --generate-notes \
+            main.js styles.css manifest.json
+```
+
+Then cut releases by pushing a tag (e.g. `git tag 0.1.0 && git push origin 0.1.0`) instead of uploading files manually. The workflow attaches the assets and registers the attestation, which the scorecard checks against the source repo for byte-for-byte reproducibility.
+
+### Duplicate CSS selectors
+
+> Unexpected duplicate selector ".foo .bar", first used at line N.
+
+**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:
+
+#### `obsidianmd/ui/sentence-case` (Risk if disabled, Warning if violated)
+
+User-facing strings must follow sentence case. The rule auto-detects most static strings; template literals are sometimes missed but still violate the spirit of the rule.
+
+```ts
+// Wrong
+new Notice('Click Here To Continue');
+this.countEl.setText('0 selected');
+
+// Right
+new Notice('Click here to continue');
+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')`.
+
+```ts
+// Wrong
+const wrap = containerEl.createEl('div', { cls: 'my-wrap' });
+const label = wrap.createEl('span', { text: 'Hello' });
+
+// Right
+const wrap = containerEl.createDiv({ cls: 'my-wrap' });
+const label = wrap.createSpan({ text: 'Hello' });
+```
+
+#### `obsidianmd/prefer-active-doc` (Warning)
+
+Use `activeDocument` instead of `document` and `activeWindow.setTimeout/setInterval/clearTimeout/clearInterval` instead of the globals. This ensures behavior in Obsidian popout windows.
+
+```ts
+// Wrong
+this.registerDomEvent(document, 'click', handler);
+setTimeout(refresh, 500);
+clearInterval(this.intervalId);
+
+// Right
+this.registerDomEvent(activeDocument, 'click', handler);
+activeWindow.setTimeout(refresh, 500);
+activeWindow.clearInterval(this.intervalId);
+```
+
+#### `obsidianmd/no-eslint-disable-without-description` (Risk)
+
+> Unexpected undescribed directive comment. Include descriptions to explain why the comment is necessary.
+
+Every `eslint-disable*` comment must end with `--` and a reason.
+
+```ts
+// Wrong
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+
+// Right
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- third-party type is loose
+```
+
+This is the most common Risk-tier finding for plugins that accumulated `eslint-disable` comments before adopting the rule. Audit every existing disable comment and either add a reason or refactor the code to avoid the disable.
+
+#### `@typescript-eslint/no-unused-vars` (Warning)
+
+> 'foo' is defined but never used. Allowed unused args must match /^_/u.
+
+**Fix**: prefix unused parameters with `_` (e.g. `_file`, `_index`, `_settings`). For destructured properties you don't need, remove them.
+
+#### `@typescript-eslint/no-explicit-any` (Warning)
+
+> Unexpected `any`. Specify a different type.
+
+**Fix**: replace `any` with `unknown` and narrow at the use site, or with a proper type. If the API is genuinely typed loosely (e.g. `JSON.parse`), use `unknown` and validate. Reserve `any` only for cases where even `unknown` is infeasible and document with an inline disable that has a description.
+
+#### `@typescript-eslint/no-unnecessary-type-assertion` (Error after upgrading typescript-eslint)
+
+> This assertion is unnecessary since it does not change the type of the expression.
+
+**Fix**: run `pnpm lint:fix`. The autofix removes the redundant assertion.
+
+#### `@typescript-eslint/no-misused-promises` (Warning)
+
+> Promise returned in function argument where a void return was expected.
+
+**Fix**: explicitly `void` or `.catch()` the promise:
+
+```ts
+// Wrong
+button.onclick = async () => { await doThing(); };
+
+// Right (fire-and-forget)
+button.onclick = () => { void doThing(); };
+
+// Better (handle errors)
+button.onclick = () => { doThing().catch(console.error); };
+```
+
+#### `@typescript-eslint/no-floating-promises` (Warning)
+
+> Promises must be awaited, end with a call to .catch, or be explicitly marked as ignored with the `void` operator.
+
+Same fix as above.
+
+### `Plugin name should not be in all caps` (manifest.json)
+
+Lowercase the `name` field in `manifest.json`. Title case is fine; all caps is not.
+
+```json
+// Wrong
+"name": "SEO"
+
+// Right
+"name": "SEO Checker"   // proper noun is OK
+"name": "Search engine optimization"
+```
+
+## ESLint Config Pattern for the Type-Aware Rules
+
+When you bump `eslint-plugin-obsidianmd` to a version that adds type-aware rules (0.3.0+), the rules will fail on non-TypeScript files because there is no `parserOptions.project` for them. Scope the recommended config to TS only:
+
+```js
+import obsidianmd from "eslint-plugin-obsidianmd";
+
+export default defineConfig([
+  { ignores: ["main.js", "node_modules/**", "*.js", "scripts/**"] },
+  // Only run obsidianmd recommended rules on TypeScript files
+  ...obsidianmd.configs.recommended.map((config) => ({
+    ...config,
+    files: config.files ?? ["**/*.ts"],
+  })),
+  {
+    files: ["**/*.ts"],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: { project: "./tsconfig.json", sourceType: "module" },
+      // ...
+    },
+  },
+]);
+```
+
+## Verification Workflow
+
+After applying fixes:
+
+1. `pnpm install` to refresh the lockfile.
+2. `pnpm why <vulnerable-pkg>` for each advisory to confirm the patched version is resolved everywhere.
+3. `pnpm build` to confirm the production build still works.
+4. `pnpm lint` to confirm no new errors.
+5. Bump `version` in `manifest.json`, `package.json`, and `versions.json`.
+6. Commit, then tag and push the tag. The release workflow handles the rest.
+7. Wait for the scorecard to refresh (usually within an hour of the release).
+
+## What the Scorecard Doesn't Penalize
+
+- Plugin runtime API surface (vault read/write, clipboard, network) — these become **Disclosures** and inform the user, not deductions.
+- Obsidian API breadth — using lots of API is fine and expected.
+- Plugin file count or repo size.
+- The plugin's actual functionality or popularity (Maintenance and Adoption are reported separately and do not require code changes).
+
+## Related Documentation
+
+- [contributing-template.md](contributing-template.md) — canonical CONTRIBUTING.md text.
+- [versioning-releases.md](versioning-releases.md) — release workflow setup.
+- [security-privacy.md](security-privacy.md) — dependency vulnerability handling.
+- [release-readiness.md](release-readiness.md) — broader pre-release checklist.
+- [code-patterns.md](../../obsidian-dev/references/code-patterns.md) — idiomatic API usage that satisfies obsidianmd rules.
+- [ux-copy.md](../../obsidian-ref/references/ux-copy.md) — sentence case and other UI text rules.

package/obsidian-ops/references/security-privacy.md

@@ -51,9 +51,43 @@ If your theme requires any of the following, you **must** disclose it clearly in
 
 Themes are CSS-only and have minimal security surface area, but still follow privacy guidelines for any optional features.
 
+## Dependency Vulnerability Hygiene (Plugins)
+
+The community scorecard scans the lockfile and flags any package with a known advisory, even if the package is dev-only and never ships in `main.js`. Common offenders are transitives pulled in by `eslint`, `eslint-plugin-obsidianmd`, and `@typescript-eslint/*`: `minimatch`, `picomatch`, `brace-expansion`, `ajv`, `flatted`, `fast-uri`, `yaml`.
+
+Use `pnpm.overrides` in `package.json` to force patched versions of vulnerable transitives without changing direct dependencies. Major-version-scoped ranges avoid breaking consumers that depend on a specific major:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "minimatch@<3.1.3": "^3.1.3",
+      "minimatch@^4 || ^5 || ^6 || ^7 || ^8": "^8.0.5",
+      "minimatch@^9": "^9.0.6",
+      "picomatch@<2.3.2": "^2.3.2",
+      "picomatch@^3 || ^4": "^4.0.4",
+      "brace-expansion@<1.1.13": "^1.1.13",
+      "brace-expansion@^2": "^2.0.3",
+      "ajv@<6.14.0": "^6.14.0",
+      "ajv@^7 || ^8": "^8.18.0",
+      "flatted@<3.4.0": "^3.4.0",
+      "fast-uri@<3.1.1": "^3.1.1",
+      "yaml@<2.8.3": "^2.8.3"
+    }
+  }
+}
+```
+
+Verify with `pnpm install` then `pnpm why <pkg>` for each advisory. Every resolved version should be at or above the advisory's fix version.
+
+If a direct dependency (e.g. `eslint-plugin-obsidianmd`) has a newer release that already pulls in patched transitives, prefer bumping the direct dep before adding an override. Overrides are appropriate when no upstream release covers your case.
+
+See [scorecard-compliance.md](scorecard-compliance.md) for the full set of scorecard signals and their fixes.
+
 ## Related Documentation
 
 - [release-readiness.md](release-readiness.md) - Comprehensive release checklist including policy adherence
+- [scorecard-compliance.md](scorecard-compliance.md) - Mapping of scorecard signals to concrete fixes
 - [manifest.md](../../obsidian-ref/references/manifest.md) - Manifest requirements (includes security-related fields)
 - [Developer Policies](https://docs.obsidian.md/Developer+policies) - Official Obsidian Developer Policies
 - [Theme Guidelines](https://docs.obsidian.md/Themes/Releasing/Theme+guidelines) - Official Theme Guidelines

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

@@ -18,6 +18,93 @@ Update frequency: Check Obsidian Sample Theme repo for updates
 - Attach `main.js`, `manifest.json`, and `styles.css` to the release as individual assets.
 - Follow the plugin submission process to add/update your plugin in the community catalog.
 
+### Automated plugin releases with build provenance attestation
+
+The Obsidian community scorecard penalizes plugin releases whose assets are missing a GitHub artifact attestation. The recommended way to satisfy this signal is a tag-triggered release workflow that runs `actions/attest-build-provenance@v2` against the release files.
+
+Drop the following at `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+permissions:
+  contents: write
+  id-token: write
+  attestations: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: |
+            main.js
+            styles.css
+            manifest.json
+      - env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          gh release create "$TAG" \
+            --title="$TAG" \
+            --generate-notes \
+            main.js styles.css manifest.json
+```
+
+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,7 +1,7 @@
 {
   "name": "obsidian-dev-skills",
-  "version": "1.1.4",
-  "description": "Agent skills for Obsidian plugin and theme development",
+  "version": "1.2.1",
+  "description": "Agent skills for Obsidian plugin and theme development, including community scorecard compliance, release workflow attestation, and dependency vulnerability hygiene.",
   "keywords": [
     "obsidian",
     "plugin",
@@ -9,7 +9,9 @@
     "development",
     "skills",
     "ai",
-    "agent"
+    "agent",
+    "scorecard",
+    "compliance"
   ],
   "homepage": "https://github.com/davidvkimball/obsidian-dev-skills",
   "repository": {
@@ -18,12 +20,14 @@
   },
   "license": "MIT",
   "author": "David V. Kimball",
+  "funding": "https://patreon.com/davidvkimball",
   "files": [
     "obsidian-dev/",
     "obsidian-theme-dev/",
     "obsidian-ops/",
     "obsidian-ref/",
-    "scripts/"
+    "scripts/init.mjs",
+    "scripts/setup-local.ps1"
   ],
   "bin": {
     "obsidian-dev-skills": "./scripts/init.mjs"
@@ -32,6 +36,6 @@
     "postinstall": "node ./scripts/init.mjs"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   }
 }

package/scripts/setup-local.ps1

@@ -1,8 +1,11 @@
-# Setup skills symlinks for this repository
-# This script creates symlinks to the obsidian-dev-skills repository
+# Setup skills symlinks for a downstream project
+# This script creates symlinks to the obsidian-dev-skills repository.
+# Intended to be copied into a downstream project's scripts/ directory.
+# The default $SkillsRepoPath assumes obsidian-dev-skills is a sibling
+# of the downstream project's repository root.
 
 param(
-    [string]$SkillsRepoPath = "$PSScriptRoot\..\obsidian-dev-skills"
+    [string]$SkillsRepoPath = "$PSScriptRoot\..\..\obsidian-dev-skills"
 )
 
 $ErrorActionPreference = "Stop"

package/scripts/bulk-update.mjs

@@ -1,40 +0,0 @@
-import { execSync } from 'child_process';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const initScript = path.join(__dirname, 'init.mjs');
-
-const projects = [
-    "C:\\Users\\david\\Development\\obsidian-alias-filename-history",
-    "C:\\Users\\david\\Development\\obsidian-astro-composer",
-    "C:\\Users\\david\\Development\\obsidian-astro-modular-settings",
-    "C:\\Users\\david\\Development\\obsidian-bases-cms",
-    "C:\\Users\\david\\Development\\obsidian-custom-slides",
-    "C:\\Users\\david\\Development\\obsidian-disable-tabs",
-    "C:\\Users\\david\\Development\\obsidian-explorer-focus",
-    "C:\\Users\\david\\Development\\obsidian-home-base",
-    "C:\\Users\\david\\Development\\obsidian-image-manager",
-    "C:\\Users\\david\\Development\\obsidian-oxygen-settings",
-    "C:\\Users\\david\\Development\\obsidian-periodic-links",
-    "C:\\Users\\david\\Development\\obsidian-property-over-file-name",
-    "C:\\Users\\david\\Development\\obsidian-seo",
-    "C:\\Users\\david\\Development\\obsidian-ui-tweaker",
-    "C:\\Users\\david\\Development\\obsidian-vault-cms",
-    "C:\\Users\\david\\Development\\obsidian-zenmode"
-];
-
-for (const project of projects) {
-    console.log(`\n🔄 Updating skills for: ${path.basename(project)}`);
-    try {
-        execSync(`node "${initScript}"`, {
-            cwd: project,
-            stdio: 'inherit',
-            env: { ...process.env, INIT_CWD: project }
-        });
-        console.log(`✅ Success: ${path.basename(project)}`);
-    } catch (error) {
-        console.error(`❌ Failed: ${path.basename(project)} - ${error.message}`);
-    }
-}

package/scripts/check-status.mjs

@@ -1,45 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-
-const projects = [
-    "C:\\Users\\david\\Development\\obsidian-alias-filename-history",
-    "C:\\Users\\david\\Development\\obsidian-astro-composer",
-    "C:\\Users\\david\\Development\\obsidian-astro-modular-settings",
-    "C:\\Users\\david\\Development\\obsidian-bases-cms",
-    "C:\\Users\\david\\Development\\obsidian-custom-slides",
-    "C:\\Users\\david\\Development\\obsidian-disable-tabs",
-    "C:\\Users\\david\\Development\\obsidian-explorer-focus",
-    "C:\\Users\\david\\Development\\obsidian-home-base",
-    "C:\\Users\\david\\Development\\obsidian-image-manager",
-    "C:\\Users\\david\\Development\\obsidian-oxygen-settings",
-    "C:\\Users\\david\\Development\\obsidian-periodic-links",
-    "C:\\Users\\david\\Development\\obsidian-property-over-file-name",
-    "C:\\Users\\david\\Development\\obsidian-seo",
-    "C:\\Users\\david\\Development\\obsidian-ui-tweaker",
-    "C:\\Users\\david\\Development\\obsidian-vault-cms",
-    "C:\\Users\\david\\Development\\obsidian-zenmode"
-];
-
-console.log('| Project | Status | Last Sync | Source |');
-console.log('| --- | --- | --- | --- |');
-
-for (const project of projects) {
-    const name = path.basename(project);
-    let agentDir = path.join(project, '.agent');
-    if (!fs.existsSync(agentDir) && fs.existsSync(path.join(project, '.agents'))) {
-        agentDir = path.join(project, '.agents');
-    }
-
-    const syncStatusPath = path.join(agentDir, 'sync-status.json');
-
-    if (fs.existsSync(syncStatusPath)) {
-        try {
-            const status = JSON.parse(fs.readFileSync(syncStatusPath, 'utf8'));
-            console.log(`| ${name} | ✅ Found | ${status.lastFullSync || 'Unknown'} | ${status.lastSyncSource || 'Unknown'} |`);
-        } catch (e) {
-            console.log(`| ${name} | ⚠️ Parse Error | - | - |`);
-        }
-    } else {
-        console.log(`| ${name} | ❌ Missing | - | - |`);
-    }
-}