docs(instructions): add security & metafile guidance

Add security checklist for module-loading and dynamic execution.
Provide guidance for inspecting build metafiles when bundle or
dependency changes increase bundle size.

- Add security checklist to `AGENTS.md` and instruction files.
- Add metafile / bundle-size guidance for production builds.
- Clarify localization notes and slow/flaky test guidance.
- Update TypeScript and commit-message instructions with examples.

Keeps agent and contributor guidance up to date.

Author: polyipseity

.github/instructions/agents.instructions.md

@@ -16,12 +16,14 @@ This short guide contains focused rules and examples to help AI coding agents ma
   - Reuse `PluginLocales` (`assets/locales.ts`) for translation resources and formatters.
 - Build & scripts:
   - `scripts/build.mjs` uses esbuild `context()`; production builds write `metafile.json`. Use `process.argv[2] === 'dev'` to enable watch mode (tests mock this behavior in `tests/scripts/build.test.mjs`).
+    - Metafile guidance: production builds emit `metafile.json`. After dependency or bundle changes, inspect `metafile.json` for large/new imports, attach it to the PR when relevant, and add a short rationale if the bundle grows significantly.
   - `scripts/obsidian-install.mjs` reads `manifest.json` for `id` and copies `manifest`, `main`, and `styles` to `<dest>/.obsidian/plugins/<id>`; it exits non-zero with a concise message when the manifest is missing—mirror these behaviors in integration tests (`tests/scripts/obsidian-install.test.mjs`).
 - Tests & naming:
   - Unit tests: `*.spec.*` — fast, hermetic, BDD-style.
   - Integration tests: `*.test.*` — TDD-style; may use tmp dirs, child processes, or spawn/exec like `obsidian-install` tests.
   - Put tests under `tests/` mirroring `src/` layout. Follow the **one test file per source file** convention.
   - **Agent note:** the `vitest` CLI defaults to interactive/watch mode when invoked without a subcommand. Agents must use `vitest run <options>` or append `--run` so tests run non-interactively.
+  - Flaky / slow-test policy: Avoid adding slow or flaky tests to the default suite. Mark slow or long-running tests clearly (place under `tests/slow/`, add a `.slow` suffix, or document in the test header), include a justification in the PR description, and add a separate integration-only run where appropriate. CI maintainers may request you to split, mock, or move tests out of the default fast suite.
 - Localization:
   - Add keys by editing `assets/locales/en/translation.json` first. Keep `{{...}}` and `$t(...)` intact and **do not** translate placeholders.
   - Add a test when adding user-facing strings (or a localization note) so translators and CI can detect missing or bad keys.
@@ -30,6 +32,14 @@ This short guide contains focused rules and examples to help AI coding agents ma
   - Add a changeset for public API or release-impacting changes.
 - When changing infra (build, tests, versioning), update `AGENTS.md` with concise rationale and local verification steps (include the exact commands you ran).
 
+**Security note (short checklist):** edits that affect module-loading or dynamic execution (for example `src/require/**`, `eval`, or dynamic imports) are high-risk and require extra review. Quick PR checklist for these changes:
+
+- Add unit and integration tests that validate sanitization, failure modes, and sandboxing assumptions.
+- Include a short threat-model note in the PR describing attacker capabilities and mitigations.
+- Tag the PR with `security` and request at least one reviewer with security expertise.
+- Avoid `eval`/untrusted dynamic execution; if unavoidable, provide input validation/whitelisting and tests.
+- Add manual verification steps or CI checks if loader behavior or resolution rules changed.
+
 If anything here is unclear or incomplete, open a short issue or suggest a direct edit to `AGENTS.md` so agents that follow can stay up to date.
 
 ---

.github/instructions/commit-message.instructions.md

@@ -43,6 +43,7 @@ Refs: dependabot config improvement
 - **Header should be ≤ 72 characters (use 72 as a human-friendly buffer; tooling still accepts up to 100).**
 - **Body lines must be hard-wrapped at 100 characters or less.** Prefer 72 for body lines intended for human readers.
 - All agents and contributors must comply; see `AGENTS.md` for enforcement policy.
+  - Example changeset workflow (releases / public API): run `pnpm changeset` to create a changeset, choose the appropriate release type, then run `pnpm version` or `pnpm build` to verify the change.
 - Example (compliant):
 
   ```text

.github/instructions/localization.instructions.md

@@ -15,7 +15,7 @@ description: Rules for translation and localization files
 
 ## Practical guidance
 
-- When adding a new user-facing string, add an entry in `assets/locales/en/translation.json` and add/adjust tests that reference `language.value.t('your.key')` to help detect regressions.
+- When adding a new user-facing string, add an entry in `assets/locales/en/translation.json` and add/adjust tests that reference `language.value.t('your.key')` to help detect regressions. Also include a short "localization note" in the PR when adding or removing keys so translators can easily track changes and reviewers can verify intent.
 - Avoid changing interpolation tokens or `$t()` usage inside translation values—these are runtime references and translators should not modify structural tokens.
 - If you add a new translation key, add a short test or documentation note so CI and reviewers can validate the change.
 

.github/instructions/typescript.instructions.md

@@ -10,6 +10,7 @@ description: Guidelines for TypeScript files in obsidian-plugin-template
 
 - Use the strictest TypeScript configuration (`tsconfig.json`).
 - Validate and normalize all settings and local settings via `.fix()` functions (see `src/settings-data.ts`).
+- When using dynamic imports (`await import(...)`) or editing module-loading code (for example `src/require/**`), include tests and document the security rationale — see `AGENTS.md` for the Security checklist.
 - Prefer type-safe patterns; **never** use the `any` type. **Prefer `unknown` over `any`.** When accepting unknown inputs, validate or narrow `unknown` with type guards or runtime validators before use. If `any` is truly unavoidable, document the reason and add a test asserting safety.
 - Reference translation keys via `language.value.t(...)` or `$t(key)` in UI code. Avoid hardcoding user-facing strings.
 - Use the project managers (`LanguageManager`, `SettingsManager`, `StorageSettingsManager`) as in `src/main.ts` to ensure consistent lifecycle and persistence behaviour.
@@ -19,6 +20,7 @@ description: Guidelines for TypeScript files in obsidian-plugin-template
 - When creating new settings, add a `fix()` entry and default in `Settings.DEFAULT` / `LocalSettings` and add a test that validates malformed data is corrected by `fix()`.
 - When writing UI code, prefer the i18n accessor from `context.language.value.t(...)` rather than importing `i18next` directly.
 - For lifecycle-sensitive managers, call `.load()` and ensure `.unload()` tasks are registered (see `PLACEHOLDERPlugin.onload()` pattern in `src/main.ts`).
+- Bundle / dependency changes: if a change introduces new runtime dependencies or increases bundle size, run a production build, inspect `metafile.json`, and add a short justification in the PR (attach the `metafile.json` when useful).
 
 ## Do / Don't
 

AGENTS.md

@@ -35,6 +35,7 @@ This guide provides clear, actionable instructions for AI coding agents working
 
 - **Versioning**
   - Use `changesets` for PRs; version lifecycle scripts are configured (`version` / `postversion`).
+  - Example changeset workflow: run `pnpm changeset` to add a changeset, choose the appropriate release type, then run `pnpm version` or `pnpm build` to verify the change. Add a changeset whenever you change public APIs or prepare a release.
 
 - **Localization**
   - Add locales by copying `assets/locales/en/translation.json` and updating `assets/locales/*/language.json` as needed. See `assets/locales/README.md` for conventions.
@@ -64,6 +65,8 @@ Quick reference for scripts in `package.json`. Use `pnpm` (preferred).
 
 > CI tip: Use `pnpm install --frozen-lockfile` in CI for deterministic installs.
 
+- Metafile guidance: production builds write a `metafile.json` (see `scripts/build.mjs`). After significant bundle or dependency changes, inspect `metafile.json` for large/new imports and consider adding a size‑budget note or rationale in the PR if the bundle grows.
+
 ## Testing ✅
 
 - **Test runner:** Vitest (fast, TypeScript support).
@@ -119,6 +122,16 @@ Helpful local resources:
 
 If you need help designing a test or mocking a dependency, ask for a short example to be added to `tests/fixtures/`.
 
+### Security checklist — changes to module-loading or dynamic execution 🔐
+
+- Scope: applies when editing `src/require/**`, dynamic loaders, `eval`, or any code that alters runtime module resolution.
+- Required for PRs touching these areas:
+  - Add unit and integration tests that validate input sanitization, failure modes, and sandboxing assumptions.
+  - Provide a short threat-model note in the PR describing possible attack vectors and mitigations.
+  - Tag the PR with `security` and request at least one reviewer with security expertise.
+  - Avoid `eval`/untrusted dynamic execution; if unavoidable, document justification and show input validation/whitelisting.
+  - Add manual verification steps or CI checks if loader behavior or resolution rules changed.
+
 ## 3. Coding Conventions
 
 **TypeScript Types:**
@@ -267,7 +280,7 @@ This section contains concise, actionable rules and project-specific examples to
 - Start by inspecting `src/main.ts`, `src/settings-data.ts`, and `assets/locales.ts` to learn core patterns: Manager classes (LanguageManager, SettingsManager), `.fix()` validators, and `PluginLocales` usage.
 - Settings pattern: always prefer `.fix()` functions (see `Settings.fix`/`LocalSettings.fix`) to validate/normalize external inputs before persisting or mutating settings.
 - I18n: use `createI18n(PluginLocales.RESOURCES, ...)` and `language.value.t(...)` for translations. Never hardcode translatable strings—use existing translation keys in `assets/locales/`.
-- Build/Dev pattern: `scripts/build.mjs` uses esbuild `context()`; pass `dev` as argv[2] to enable watch mode. Tests mock `esbuild` in `tests/scripts/build.test.mjs`—use those tests as canonical examples for safe refactors.
+- Build/Dev pattern: `scripts/build.mjs` uses esbuild `context()`; pass `dev` as `argv[2]` to enable watch mode. Tests mock `esbuild` in `tests/scripts/build.test.mjs`—use those tests as canonical examples for safe refactors.
 - Script behavior: `scripts/obsidian-install.mjs` exits 1 with a short error message when `manifest.json` is missing. Make changes in scripts with tests mirroring error conditions (see `tests/scripts/obsidian-install.test.mjs`).
 - Test conventions: `*.spec.*` = unit (fast, isolated); `*.test.*` = integration (may use filesystem or child processes). Follow the one-test-file-per-source-file convention and place tests under `tests/` mirroring `src/`.
 - Formatting & linting: run `pnpm run format` and `pnpm run check` before committing. CI uses `pnpm install --frozen-lockfile`.