@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/user-experience/visually-texture-content.md

@@ -0,0 +1,76 @@
+## Overview
+To apply realistic weathering or texture patterns (like grunge, noise, or paper texture) to an element, use CSS Masking (`mask-image`) with a repeating texture image. This allows you to make the content itself appear textured by making parts of it semi-transparent, rather than just overlaying a texture on top. This creates a more realistic physical material appearance.
+
+## Implementation
+To apply a texture pattern:
+
+### Method 1: Using a repeating raster image (Recommended for realistic textures)
+This is the most common method for realistic textures.
+
+```css
+.weathered-element {
+  /* MANDATORY: Use vendor prefix for wider support in older browsers */
+  -webkit-mask-image: url('grunge-pattern.png');
+  -webkit-mask-repeat: repeat; /* Repeat the pattern to fill the area */
+  -webkit-mask-size: 300px; /* Control the scale of the texture */
+
+  /* Standard property for modern browsers */
+  mask-image: url('grunge-pattern.png');
+  mask-repeat: repeat;
+  mask-size: 300px;
+}
+```
+
+### Method 2: Using CSS Gradients for geometric patterns
+You can generate patterns using CSS gradients. This is self-contained and does not require external image files.
+
+```css
+.patterned-element {
+  --checkerboard-gradient: 
+    linear-gradient(45deg, #000 25%, transparent 25%), 
+    linear-gradient(-45deg, #000 25%, transparent 25%), 
+    linear-gradient(45deg, transparent 75%, #000 75%), 
+    linear-gradient(-45deg, transparent 75%, #000 75%);
+
+  /* Apply a checkerboard pattern as a mask */
+  -webkit-mask-image: var(--checkerboard-gradient);
+  -webkit-mask-size: 20px 20px;
+  -webkit-mask-position: 0 0, 0 10px, 10px -10px, -10px 0px;
+  
+  mask-image: var(--checkerboard-gradient);
+  mask-size: 20px 20px;
+  mask-position: 0 0, 0 10px, 10px -10px, -10px 0px;
+}
+```
+
+### Alpha vs Luminance Masking Modes
+
+By default, CSS masks use `mask-mode: match-source`. This means the browser automatically decides whether to use the **alpha channel** (transparency) or the **luminance** (brightness) of the mask based on what kind of source you provide:
+
+| Mask Source Type | Default Mask Mode | Masking Behavior |
+| :--- | :--- | :--- |
+| **Inline SVG `<mask>` element** | `luminance` | Opacity is determined by the brightness of colors. **White** reveals content, **black** hides it, and **gray** creates semi-transparency. |
+| **Direct Image File** (e.g. PNG, SVG file) | `alpha` | Opacity is determined by transparency. **Opaque** parts reveal content, and **transparent** parts hide it. |
+| **CSS Gradient** | `alpha` | Opacity is determined by transparency. **Opaque** colors (like `black`) reveal content, and **transparent** colors hide it. |
+
+> **Note:** You can explicitly override the default mask mode using the `mask-mode` CSS property (e.g., `mask-mode: luminance;` or `mask-mode: alpha;`).
+
+## Fallback strategies
+Baseline status for Masks: Newly available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- The element will display without the texture (clean and solid fill).
+- Ensure the content is still readable without the texture (progressive enhancement).
+- You can use a background image or an overlay as a fallback to simulate the texture, although it will not affect the transparency of the content itself.
+
+```css
+/* Fallback: Use a background image for browsers without mask support */
+@supports (not (mask-image: url(x))) and (not (-webkit-mask-image: url(x))) {
+  .weathered-element {
+    /* Fallback adds texture on top or behind, depending on implementation */
+    background-image: url('grunge-pattern.svg');
+    background-color: #fff; /* Ensure background is solid if needed */
+  }
+}
+```

package/.agents/skills/modern-web-guidance/guides/webmcp/agentic-forms.md

@@ -0,0 +1,116 @@
+The Declarative API transforms standard HTML `<form>` elements into WebMCP tools via attributes. The browser synthesizes a JSON Schema from the form inputs and handles agent interactions.
+
+## Form Attributes
+
+*   `toolname`: Unique name for the tool.
+*   `tooldescription`: Purpose of the tool.
+*   `toolautosubmit`: (Optional) If present, the agent can submit the form without waiting for user interaction. 
+*   `toolparamdescription`: (Optional) Provides a way to define a property description within the JSON Schema.
+    *   **Resolution Order**: The browser uses `toolparamdescription` if present. In its absence, it uses the `textContent` of the associated `<label>` (skipping labelable descendants). If no label exists, it falls back to the `aria-description`.
+    *   **Grouping (Fieldsets)**: To attach a description to a group of related elements (like `<input type="radio">` buttons), place `toolparamdescription` on the nearest parent `<fieldset>` element so it applies to the parameter group as a whole.
+
+### Example
+
+```html
+<form toolname="search-cars" 
+      tooldescription="Perform a car make/model search" 
+      toolautosubmit>
+  <label for="make">Vehicle Make</label>
+  <input type="text" id="make" name="make" required>
+  
+  <label for="model">Vehicle Model</label>
+  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
+  
+  <button type="submit">Search</button>
+</form>
+```
+
+## Handling Submissions in JavaScript
+
+When an agent submits the form, the `SubmitEvent` includes `agentInvoked` (boolean) and `respondWith(promise)`.
+
+```javascript
+document.querySelector('form').addEventListener('submit', (event) => {
+  event.preventDefault();
+
+  // Validate the form
+  const formValidationErrors = myFormIsValid();
+
+  if (formValidationErrors.length > 0) {
+    if (event.agentInvoked) {
+      const errorString =
+        'Validation failed: ' +
+        formValidationErrors
+          .map((err) => `${err.field} (${err.message})`)
+          .join(', ');
+
+      event.respondWith(Promise.resolve(errorString));
+    }
+    return;
+  }
+
+  const resultPromise = performAsyncSearch(new FormData(event.target));
+
+  // Return the result directly to the agent without navigation
+  if (event.agentInvoked) {
+    event.respondWith(resultPromise);
+  }
+});
+```
+
+## Lifecycle Events
+
+The window emits events when agents start or stop interacting with a tool:
+
+```javascript
+window.addEventListener('toolactivated', ({ toolName }) => {
+  console.log(`Tool "${toolName}" was activated by the agent.`);
+});
+
+window.addEventListener('toolcancel', ({ toolName }) => {
+  console.log(`Tool "${toolName}" interaction was cancelled.`);
+});
+```
+
+## Visual Feedback (CSS)
+
+Use pseudo-classes to highlight forms when an agent interacts with them:
+
+*   `:tool-form-active`: Applied to the `<form>` element actively used by the agent.
+*   `:tool-submit-active`: Applied to the submit button when the browser pauses for user review (if `toolautosubmit` is omitted).
+
+```css
+form:tool-form-active {
+  outline: 2px dashed blue;
+  background-color: rgba(0, 0, 255, 0.05);
+}
+
+button:tool-submit-active {
+  outline: 2px dashed red;
+  animation: pulse 2s infinite;
+}
+```
+
+## Form Suitability (When to Avoid)
+
+The Declarative API is best for self-contained, standard forms. It is a poor choice in these scenarios:
+
+* **Highly Dependent Fields**: Forms where inputs change options or visibility based on other inputs. The synthesized schema cannot express these dependencies well.
+* **Custom UI Components**: Forms relying on non-standard inputs (e.g., canvas, rich text editors) that don't auto-serialize values.
+* **Multi-Step Wizards**: Complex workflows requiring multiple form submissions. The Imperative API or standard DOM interaction is better suited here.
+
+## When to use toolautosubmit
+* **Read-Only Operations & Queries**: Searches, filters, fetching details, or checking status (e.g., a car model search, searching a directory, checking stock availability).
+* **Low-Risk, Reversible Actions**: Form actions that can easily be undone or refined by the user manually (e.g., adding items to a cart, applying a coupon code, saving a draft, or setting temporary layout options).
+
+## When to omit toolautosubmit
+* **Destructive or Irreversible Actions**: Deleting records, resetting system configurations, or clearing databases.
+* **Financial & Transactional Actions**: Submitting a checkout form, transferring funds, authorizing subscription payments, or final order placements.
+* **High-Impact User Communication**: Submitting a final job application, sending emails/messages to other real users, or publishing public-facing content.
+* **Sensitive Account Settings**: Changing passwords, modifying user roles/permissions, or updating billing/profile info.
+
+## Fallback strategies
+
+Form-associated WebMCP attributes is not natively supported by any major browser yet.
+
+The WebMCP Declarative API is safe to use in all browsers. Browsers that do not support WebMCP will ignore the `tool*` attributes, and the `<form>` will continue to function as a normal HTML form. No feature detection is required.

package/.agents/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md

@@ -0,0 +1,116 @@
+The Imperative API uses `document.modelContext.registerTool()` to programmatically define JavaScript tools. This is ideal for Single Page Applications (SPAs) where tools need to be added or removed based on the current route or user state.
+
+## Registration and Lifecycle
+
+Tools are registered by passing a tool definition object and an optional options object containing an `AbortSignal`.
+
+### Lifecycle Handling with `AbortController`
+
+WebMCP does not provide an `unregisterTool()` method. To unregister a tool, you must pass an `AbortSignal` during registration and abort that signal when the tool is no longer needed.
+
+```javascript
+const controller = new AbortController();
+
+await document.modelContext.registerTool({
+  name: "get_user_preferences",
+  description: "Retrieves the user's saved preferences.",
+  inputSchema: { type: "object", properties: {} },
+  execute() {
+    const prefs = localStorage.getItem("user_prefs");
+    return prefs ? JSON.parse(prefs) : { theme: "light" };
+  },
+  annotations: { readOnlyHint: true }
+}, { signal: controller.signal });
+
+// To unregister the tool (e.g., on component unmount):
+controller.abort();
+```
+
+## Defining Parameters
+
+Parameters (params) are defined using the `inputSchema` property. This must be a **JSON Schema** object that describes the structured data the tool expects.
+
+```javascript
+await document.modelContext.registerTool({
+  name: "calculate_area",
+  description: "Calculates the area of a rectangle.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      width: { type: "number", description: "The width of the rectangle." },
+      height: { type: "number", description: "The height of the rectangle." }
+    },
+    required: ["width", "height"]
+  },
+  execute(input) {
+    // input is { width: 10, height: 20 }
+    return input.width * input.height;
+  },
+  annotations: { readOnlyHint: true }
+});
+```
+
+## Execution Patterns
+
+### When to use `async execute`
+Use `async` when the tool involves operations that return a Promise or take time to complete:
+- **Network calls**: Fetching data from an API.
+- **Asynchronous Storage**: Accessing IndexedDB.
+- **External Events**: Waiting for a specific state change or animation to finish.
+
+```javascript
+async execute(input) {
+  const response = await fetch(`/api/data/${input.id}`);
+  return await response.json();
+}
+```
+
+### When to use `execute` (Synchronous)
+Use a standard synchronous function for immediate operations:
+- **Pure logic**: Math, filtering, or sorting data already in memory.
+- **Synchronous state**: Reading from `localStorage` or a synchronous state manager.
+
+```javascript
+execute(input) {
+  return input.items.filter(item => item.active);
+}
+```
+
+## Tool Factory Pattern
+
+To pass context (like stores or application instances) to your tools, use factory functions.
+
+```javascript
+export function createInventoryTool(inventoryManager) {
+  return {
+    name: "get_inventory",
+    description: "Lists items in the inventory.",
+    inputSchema: { type: "object", properties: {} },
+    execute() {
+      return inventoryManager.getItems();
+    },
+    annotations: { readOnlyHint: true }
+  };
+}
+```
+
+## API Notes
+
+*   **annotations**: (Optional) A dictionary for tool metadata.
+    *   **readOnlyHint**: (Optional) Set to `true` if the tool does not modify any state and only reads data. This helps agents decide when it is safe to call the tool.
+*   **Return Format**: The `execute` function can return any value (object, array, string, number, boolean). Select a structure that best serves your specific use case while ensuring the content is optimized for the LLM to process. The output may encompass raw data, specific error logs, or direct instructions to influence the agent's next action.
+*   **Secure Context**: WebMCP requires HTTPS.
+*   **Deprecated/Removed**: `navigator.modelContext` (deprecated in Chromium 150), `unregisterTool()`, `provideContext()`, and `clearContext()` are no longer supported.
+
+## Fallback strategies
+
+document.modelContext is not natively supported by any major browser yet.
+
+The WebMCP Imperative API should be used with feature detection to ensure compatibility with browsers that do not yet support WebMCP.
+
+```javascript
+const modelContext = document.modelContext || navigator.modelContext;
+if (modelContext && 'registerTool' in modelContext) {
+  // Register tools
+}
+```

package/.agents/skills/modern-web-guidance/guides/webmcp/webmcp.md

@@ -0,0 +1,43 @@
+# WebMCP (Web Model Context Protocol)
+
+WebMCP is a browser-native JavaScript API that allows web pages to expose their client-side functionality as structured "tools" to AI agents, browser assistants, and assistive technologies. 
+
+IMPORTANT: WebMCP is currently in Early Preview on Chromium-based browsers (such as Chrome and Edge). It requires Chromium version `146.0.7672.0` or higher and the `#enable-webmcp-testing` flag.
+
+**Crucial Distinction:** WebMCP runs entirely **client-side** in the browser tab. It is *not* a backend server, and it does *not* use HTTP, Server-Sent Events (SSE), or `stdio` transports. The web page itself acts as the tool registry.
+
+Currently, WebMCP **only supports Tools**. It does not support the "Resources" or "Prompts" primitives found in the backend Model Context Protocol.
+
+## Quick Overview
+
+- **Imperative API**: Use `document.modelContext.registerTool()` for complex logic and dynamic interactions.
+- **Declarative API**: Annotate standard HTML `<form>` elements with `toolname` and `tooldescription` to turn them into tools.
+
+## Best Practices
+
+* **Naming and Semantics**: Use specific verbs describing exact behavior (e.g. `create-event` vs `start-event-creation-process`). Favor positive descriptions over listing limitations.
+* **Schema Design**: Accept raw user input (avoid agent math/calculation). Ensure all parameters have specific types and explain the purpose of options.
+* **Reliability**: Validate constraints in code and return descriptive errors for retries. Handle rate limiting gracefully. Ensure the function returns *after* UI state updates for consistency.
+* **Tool Strategy**: Tools should be atomic, composable, and distinct. Do not force flow control instructions ("Don't call B after A") — let the agent decide. Register/unregister tools dynamically depending on the current page context. Use `annotations: { readOnlyHint: true }` (placed after `execute`) for tools that do not modify state to inform the agent of safe execution.
+* **Clean Up**: Always use `AbortSignal` to unregister tools when pages transition or resources are released to avoid leaks and collisions. Do not use `unregisterTool`.
+* **Web Development Best Practices**: WebMCP tools run as client-side JavaScript in the browser tab. They must adhere to regular web development best practices (e.g., keeping secrets out of client-side code, accessing backend databases through secure API layers, and using Web Workers, WASM, or WebGPU for heavy compute).
+
+### When to Discourage WebMCP
+* **High-Risk Actions without Guardrails**: Avoid auto-submitting tools for destructive or irreversible actions (e.g., deleting data) unless the UI requires manual user confirmation outside the agent's control.
+* **Hyper-Dynamic State**: If data changes faster than the agent can react, it may work with stale context.
+
+### Anti-Patterns & Warnings (DO NOT DO THIS)
+
+* **Do not use backend transports.** WebMCP is for browser tabs, not Node.js background processes.
+* **Do not include Resources or Prompts.** These are not supported in the current WebMCP spec.
+* **Do not ignore `inputSchema` structure.** Always provide clear descriptions for every parameter to minimize agent hallucinations.
+* **Do not use outside of a Secure Context (HTTPS).**
+
+## Implementation Status
+
+WebMCP is currently in early preview in Chromium-based browsers (e.g., Chrome, Edge):
+
+* **Current Status**: Early preview.
+* **Required Version**: Chromium `146.0.7672.0` or higher.
+* **Activation**: Requires enabling the flag `chrome://flags/#enable-webmcp-testing` or `edge://flags/#enable-webmcp-testing`.
+* **Specification**: Evolving [Draft Community Group specification](https://webmachinelearning.github.io/webmcp/); not yet a standards-track recommendation.

package/.agents/skills/nextjs-app-router-patterns/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: nextjs-app-router-patterns
+description: Master Next.js 14+ App Router with Server Components, streaming, parallel routes, and advanced data fetching. Use when building Next.js applications, implementing SSR/SSG, or optimizing React Server Components.
+---
+
+# Next.js App Router Patterns
+
+Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.
+
+## When to Use This Skill
+
+- Building new Next.js applications with App Router
+- Migrating from Pages Router to App Router
+- Implementing Server Components and streaming
+- Setting up parallel and intercepting routes
+- Optimizing data fetching and caching
+- Building full-stack features with Server Actions
+
+## Core Concepts
+
+### 1. Rendering Modes
+
+| Mode                  | Where        | When to Use                               |
+| --------------------- | ------------ | ----------------------------------------- |
+| **Server Components** | Server only  | Data fetching, heavy computation, secrets |
+| **Client Components** | Browser      | Interactivity, hooks, browser APIs        |
+| **Static**            | Build time   | Content that rarely changes               |
+| **Dynamic**           | Request time | Personalized or real-time data            |
+| **Streaming**         | Progressive  | Large pages, slow data sources            |
+
+### 2. File Conventions
+
+```
+app/
+├── layout.tsx       # Shared UI wrapper
+├── page.tsx         # Route UI
+├── loading.tsx      # Loading UI (Suspense)
+├── error.tsx        # Error boundary
+├── not-found.tsx    # 404 UI
+├── route.ts         # API endpoint
+├── template.tsx     # Re-mounted layout
+├── default.tsx      # Parallel route fallback
+└── opengraph-image.tsx  # OG image generation
+```
+
+## Quick Start
+
+```typescript
+// app/layout.tsx
+import { Inter } from 'next/font/google'
+import { Providers } from './providers'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export const metadata = {
+  title: { default: 'My App', template: '%s | My App' },
+  description: 'Built with Next.js App Router',
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={inter.className}>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+
+// app/page.tsx - Server Component by default
+async function getProducts() {
+  const res = await fetch('https://api.example.com/products', {
+    next: { revalidate: 3600 }, // ISR: revalidate every hour
+  })
+  return res.json()
+}
+
+export default async function HomePage() {
+  const products = await getProducts()
+
+  return (
+    <main>
+      <h1>Products</h1>
+      <ProductGrid products={products} />
+    </main>
+  )
+}
+```
+
+## Detailed patterns and worked examples
+
+Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
+
+## Best Practices
+
+### Do's
+
+- **Start with Server Components** - Add 'use client' only when needed
+- **Colocate data fetching** - Fetch data where it's used
+- **Use Suspense boundaries** - Enable streaming for slow data
+- **Leverage parallel routes** - Independent loading states
+- **Use Server Actions** - For mutations with progressive enhancement
+
+### Don'ts
+
+- **Don't pass serializable data** - Server → Client boundary limitations
+- **Don't use hooks in Server Components** - No useState, useEffect
+- **Don't fetch in Client Components** - Use Server Components or React Query
+- **Don't over-nest layouts** - Each layout adds to the component tree
+- **Don't ignore loading states** - Always provide loading.tsx or Suspense