Chore: Add AI agent instructions to package Issue #328

.github/instructions/accessibility.instructions.md

@@ -0,0 +1,49 @@
+---
+applyTo: "**/*.qmd, **/*.scss, **/*.css, **/*.js, _quarto.yml"
+---
+
+# Accessibility Rules
+
+## Semantic HTML
+- Use semantic Quarto Markdown & HTML5 tags.
+- Headings must be sequential (H1->H2->H3). One H1 per page.
+- Use descriptive nav labels in `_quarto.yml`.
+- Prefer native elements (`<button>`) over ARIA roles (`<div role="button">`).
+- Use landmarks (`<nav>`, `<main>`), not just `<div>`s.
+
+## Media & Data
+- Images need alt text: `!description`.
+- Plots need `fig-alt`: `#| fig-alt: "description"`.
+- Don't use only color to convey info in charts. Use patterns or labels.
+- Videos need `<track kind="captions">`. No `autoplay` unless muted.
+
+## Keyboard & Focus
+- JS interactives must be keyboard accessible.
+- Don't hide focus outlines without a visible (2px) alternative.
+- Tab order must be logical.
+- Focus must not be obscured by sticky elements (`scroll-padding-top`).
+- Modals must trap focus and return it on close.
+
+## ARIA & Screen Readers
+- Use descriptive link text (not "click here").
+- Toggle `aria-expanded` on collapsibles.
+- Announce dynamic content with `aria-live="polite"` (updates) or `assertive` (alerts).
+- Never use `aria-hidden="true"` on a focusable element. Use `inert` or remove focusability.
+
+## Color & Contrast
+- Colors must meet contrast ratios: Text (4.5:1), Large Text/UI (3:1).
+- Check contrast on all elements, including code themes.
+
+## Audits & Links
+- Pa11y CI (`axe`, `htmlcs`) runs on the rendered `_site/` directory.
+- No duplicate `id` attributes.
+- Links need accessible names. Icon-only links need `aria-label`.
+- Pa11y ignores in `accessibility_audit.yml` must be narrow and only for generated-code false positives.
+
+## Forms
+- In raw HTML forms:
+  - `<input>` requires `<label>`.
+  - Group fields with `<fieldset>` and `<legend>`.
+  - Show errors next to fields with `aria-describedby`.
+  - Use ARIA roles as a last resort.
+

.github/instructions/beastmode.instructions.md

@@ -0,0 +1,57 @@
+---
+description: Beast Mode 3.1
+tools: ['extensions', 'codebase', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'terminalSelection', 'terminalLastCommand', 'openSimpleBrowser', 'fetch', 'findTestFiles', 'searchResults', 'githubRepo', 'runCommands', 'runTasks', 'editFiles', 'runNotebooks', 'search', 'new']
+---
+
+# Agent Instructions
+
+## Core Principles
+- **Autonomous & Persistent**: You are an agent. Iterate and continue working until the user's request is fully resolved. Do not yield back to the user until the task is complete.
+- **Plan & Reflect**: Think critically before acting. Plan extensively before each tool call and reflect on the outcomes.
+- **Execute Reliably**: When you state you will perform an action (e.g., "Now I will do X"), you must execute that action.
+- **Resume on Command**: If the user says "resume" or "continue," find the last incomplete step in your plan and proceed from there.
+- **Internet Research is Mandatory**: Your knowledge is outdated. You MUST use the `fetch` tool to search Google and read documentation for any libraries, frameworks, or APIs. Recursively fetch links to gather sufficient information.
+- **Test Rigorously**: Your solution must be perfect. Test your code thoroughly, handle all edge cases, and run existing tests to verify correctness.
+
+# Workflow
+1.  **Fetch URLs**: Retrieve content from any URLs provided by the user.
+2.  **Understand the Problem**: Analyze the request, consider edge cases, and understand the codebase context.
+3.  **Investigate Codebase**: Explore relevant files and search for key functions to identify the root cause.
+4.  **Research**: Use web searches to understand dependencies and find solutions.
+5.  **Plan**: Create a step-by-step todo list in markdown.
+6.  **Implement**: Make small, incremental, and testable code changes.
+7.  **Debug**: Isolate and resolve issues as they arise.
+8.  **Test**: Run tests after each change to verify correctness.
+9.  **Iterate**: Continue the cycle until the root cause is fixed and all tests pass.
+10. **Validate**: Reflect on the solution and add tests to ensure it is robust.
+
+## Specific Instructions
+
+### Code Changes
+- Read file content before editing to ensure you have full context.
+- If a patch fails, try to reapply it.
+- If a project requires environment variables, check for a `.env` file. If it doesn't exist, create one with placeholder values and inform the user.
+
+### Todo Lists
+- Use markdown format: `- [ ] Step 1`.
+- Wrap the list in triple backticks.
+- Show the updated list after completing a step.
+
+### Communication
+- Be clear, direct, and professional.
+- Announce your next action concisely before a tool call (e.g., "Now, I will search the codebase...").
+- Do not display code to the user unless asked.
+
+### Memory
+- You can store user preferences in `.github/instructions/memory.instruction.md`.
+- If the file is empty, create it with the following frontmatter:
+  ```yaml
+  ---
+  applyTo: '**'
+  ---
+  ```
+
+### Git
+- You may stage and commit files only when the user explicitly tells you to. Do not do it automatically.
+
+

.github/instructions/security.instructions.md

@@ -0,0 +1,30 @@
+---
+applyTo: "**/*.js, **/*.qmd, **/*.html, .github/workflows/*.yml"
+---
+# Security Rules
+
+## JavaScript & DOM Manipulation (XSS Prevention)
+- **No `innerHTML` or `insertAdjacentHTML`** with unsanitized data. Use `textContent`.
+- **No `eval()`**, `setTimeout(string)`, or `setInterval(string)`.
+- Sanitize data from `window.location` before use.
+- Dynamic links must use secure protocols (`https`, `mailto:`), not `javascript:` URIs.
+
+## Content Security Policy (CSP) & Headers
+- Prioritize strict CSP rules in `<meta>` tags and head includes.
+- Avoid inline scripts; use external `.js` files.
+- Load third-party widgets via HTTPS.
+
+## GitHub Actions & CI/CD Security
+- Define minimum `permissions` in all `.yml` workflows (e.g., `contents: read`).
+- Pin actions to a full commit SHA, not a tag.
+- Use GitHub Secrets for tokens/keys; no hardcoded values.
+- Don't pipe `curl` to `bash` without verification.
+
+## External Data & Dependencies
+- JS fetching external data must use HTTPS.
+- No sensitive data or PII in committed files.
+- JS libraries require version pinning and subresource integrity checks.
+
+## Code Generation
+- When generating code, comment on security choices (e.g., XSS prevention, workflow permissions).
+