@olives/devos 2.1.0

package/.agents/skills/modern-web-guidance/guides/built-in-ai/language-detection.md

@@ -0,0 +1,89 @@
+The **Language Detector API** is a client-side web API designed to identify the language of a given text string. By performing detection locally in the browser, it enhances user privacy and reduces the need for heavy external libraries or costly server-side calls.
+
+## Key Use Cases
+
+- **Translation Prep:** Identifying the source language before sending text to a translator.
+- **Safety & Filtering:** Loading specific models for tasks like toxicity detection.
+- **Accessibility:** Labeling content with the correct `lang` attribute for screen readers.
+- **UI Localization:** Adjusting application interfaces based on the user's input language.
+
+## Hardware & System Requirements
+
+- **OS:** Windows 10/11, macOS 13+, Linux, or Chromebook Plus.
+- **Storage:** 22 GB free space (model is removed if space drops below 10 GB).
+- **RAM/CPU:** 16 GB RAM and 4+ CPU cores.
+- **VRAM:** 4 GB+ if using a GPU.
+
+## Implementation Guide
+
+### 1. Model Management & User Activation
+
+Check model availability before attempting to instantiate the detector or trigger download.
+
+**MANDATORY:** Instantiating the language detector or triggering a model download with `LanguageDetector.create()` **MUST** be initiated by a user gesture (such as a button click) to prevent a `NotAllowedError` when the model is in a `downloadable` or `downloading` state.
+
+```javascript
+// Check if the model is available or downloadable
+const availability = await LanguageDetector.availability();
+
+if (availability !== 'unavailable') {
+  button.addEventListener('click', async () => {
+    const detector = await LanguageDetector.create({
+      monitor(m) {
+        m.addEventListener('downloadprogress', (e) => {
+          console.log(`Downloaded ${e.loaded * 100}%`);
+        });
+      },
+    });
+  });
+}
+```
+
+### 2. Running Detection
+
+The API returns a ranked list of potential languages with a confidence score between `0.0` and `1.0`.
+
+```javascript
+const someUserText = 'Hallo und herzlich willkommen!';
+const results = await detector.detect(someUserText);
+
+for (const result of results) {
+  // result.detectedLanguage (e.g., 'de')
+  // result.confidence (e.g., 0.999)
+  console.log(result.detectedLanguage, result.confidence);
+}
+```
+
+Avoid using the detector on very short phrases or single words, as accuracy drops significantly.
+
+## Security and Environment
+
+- **Iframes:** Cross-origin iframes require an explicit Permissions Policy to access the API.
+  ```html
+  <iframe
+    src="https://cross-origin.example.com/"
+    allow="language-detector"
+  ></iframe>
+  ```
+- **Web Workers:** The API is **not** currently available in Web Workers due to Permission Policy complexities.
+- **Privacy:** No data is sent to Google or third parties during the detection process.
+
+## Fallback Strategy
+
+Language detector has limited availability.
+Supported by: Chrome 138 (Jun 2025) and Edge 148 (May 2026).
+Unsupported in: Firefox and Safari.
+
+Before use, check if the `LanguageDetector` object is available in the global scope:
+
+```javascript
+if ('LanguageDetector' in self) {
+  // The Language Detector API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the `LanguageDetector` API is unsupported or availability checks return `'unavailable'`, you must gracefully fall back:
+1. **Remote API Fallback**: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API) to identify the language.
+2. **Graceful Degradation**: Disable language detection elements/buttons and inform the user that client-side detection is currently unsupported in this browser, preventing any unhandled exceptions or crashes.

package/.agents/skills/modern-web-guidance/guides/built-in-ai/language-model.md

@@ -0,0 +1,189 @@
+The Prompt API allows developers to run natural language processing tasks directly in the browser using **Gemini Nano**. This built-in AI approach ensures user privacy, reduces server costs, and enables offline functionality.
+
+## 1. Getting Started and Hardware Requirements
+
+The Prompt API is currently available in Chrome as of version 148 (Desktop) for Windows, macOS, Linux, and Chromebook Plus.
+
+### Hardware Prerequisites
+
+- **Storage**: 22 GB free space (for the initial profile and model).
+- **Memory/CPU**: 16 GB RAM and 4+ CPU cores.
+- **GPU**: 4 GB VRAM or more (Required for audio input).
+- **Network**: Required only for the initial model download.
+
+### Initializing the API
+
+Check model availability before triggering a download:
+
+```javascript
+const availability = await LanguageModel.availability();
+
+// Do not call create() when unavailable — the model cannot run on this device.
+if (availability !== 'unavailable') {
+	const session = await LanguageModel.create({
+		monitor(m) {
+			// Inform the user while the model downloads so the UI doesn't appear frozen.
+			m.addEventListener('downloadprogress', (e) => {
+				console.log(`Downloaded ${e.loaded * 100}%`);
+			});
+		},
+	});
+}
+```
+
+## 2. Core Prompting Capabilities
+
+Session examples in this section omit `session.destroy()` for brevity. Always call `session.destroy()` when a session is no longer needed to free device memory (see Section 5).
+
+### Basic and Streamed Output
+
+For short responses, use `prompt()`. For longer content, use `promptStreaming()` to provide a more responsive UI.
+
+**MANDATORY**: Never assign model output to `innerHTML`. Model output is untrusted and can contain injected markup. Always use `textContent` or a sanitizer.
+
+```javascript
+const session = await LanguageModel.create();
+
+// prompt() accumulates the full response before resolving — use for short, one-shot output.
+const result = await session.prompt('Write a haiku about coding.');
+// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
+outputEl.textContent = result;
+
+// promptStreaming() yields independent chunks that must be concatenated;
+// use for longer content so each chunk can be rendered progressively.
+const stream = session.promptStreaming('Write a long story about a robot.');
+let completeResult = '';
+for await (const chunk of stream) {
+	completeResult += chunk;
+	outputEl.append(chunk);
+}
+console.log('Full story:', completeResult);
+```
+
+### Multimodal Input
+
+The Prompt API supports text, audio, and visual inputs (images, canvas, video frames).
+
+```javascript
+const session = await LanguageModel.create({
+	// Declaring expected input types lets the browser optimize model loading.
+	expectedInputs: [{ type: 'text' }, { type: 'image' }],
+	expectedOutputs: [{ type: 'text' }],
+});
+
+const response = await session.prompt([
+	{
+		role: 'user',
+		content: [
+			{ type: 'text', value: 'What is in this image?' },
+			{ type: 'image', value: document.querySelector('canvas') },
+		],
+	},
+]);
+```
+
+## 3. Advanced Session Management
+
+Sessions allow the model to maintain context across multiple interactions.
+
+### Context and Quota
+
+Each session has a maximum token limit. You can monitor usage via `session.contextUsage` and `session.contextWindow`. If the window overflows, the oldest messages (except the system prompt) are dropped.
+
+### Cloning Sessions
+
+Cloning is efficient for starting parallel conversations that share the same initial context (like a "system" personality) without re-initializing.
+
+```javascript
+const mainSession = await LanguageModel.create({
+	initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
+});
+
+const branchA = await mainSession.clone();
+const branchB = await mainSession.clone();
+// Destroy the base after cloning — the clones own their own context from here.
+mainSession.destroy();
+```
+
+### Restoring Past Sessions
+
+While a native "restore" feature is in development, you can recreate a session by feeding previous history into `initialPrompts`.
+
+**Note**: `localStorage` is unencrypted and persistent. Stored conversation history may include user PII — consider the privacy implications before persisting chat history.
+
+```javascript
+// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
+const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
+const session = await LanguageModel.create({
+	initialPrompts: history, // Array of {role, content} objects
+});
+```
+
+## 4. Structured Output with JSON Schema
+
+To prevent the model from adding "chatter" (e.g., "Sure, here is your JSON:"), use a **JSON Schema** via the `responseConstraint` field. This ensures the output is valid JSON that can be parsed immediately.
+
+### Example: Sentiment Classification
+
+```javascript
+// Pass the schema as a plain object — do not JSON.stringify() it first.
+const schema = {
+	type: 'object',
+	properties: {
+		rating: { type: 'number', minimum: 1, maximum: 5 },
+		is_positive: { type: 'boolean' },
+	},
+	required: ['rating', 'is_positive'],
+};
+
+const result = await session.prompt(
+	"Rate the following feedback: 'The food was great!'",
+	{ responseConstraint: schema },
+);
+
+const data = JSON.parse(result);
+console.log(data.rating); // 5
+```
+
+### Constraints and Prefixes
+
+You can guide the model further by prefilling the assistant's response using `prefix: true`.
+
+````javascript
+const character = await session.prompt([
+	{ role: 'user', content: 'Create a character sheet' },
+	{ role: 'assistant', content: '```json\n', prefix: true },
+]);
+````
+
+## 5. Best Practices and Safety
+
+- **Resource Cleanup**: Always call `session.destroy()` when a conversation is finished to free up memory.
+- **Output Safety**: Model output is untrusted. Always write results to `textContent`, not `innerHTML`, to prevent XSS injection from malicious model output.
+- Use a sanitizer like the native Sanitizer API or DOMPurify if you need to allow limited HTML.
+- **Aborting Tasks**: Use `AbortController` to allow users to stop long-running generations. Pass the `signal` to `prompt()` or `promptStreaming()`, not to `LanguageModel.create()`.
+- **Security**: Use Permission Policies to control access in iframes: `<iframe src="..." allow="language-model"></iframe>`.
+- **Design**: Review the [People + AI Guidebook](https://pair.withgoogle.com/guidebook/) to ensure responsible AI implementation.
+
+By combining structured outputs with robust session management, developers can build complex, stateful AI applications that run entirely on the user's device.
+
+## 6. Fallback strategies
+
+LanguageModel has limited availability.
+Supported by: Chrome 148 (May 2026).
+Unsupported in: Edge, Firefox, and Safari.
+
+Before use, check if the LanguageModel object is available in the global scope:
+
+```js
+if ('LanguageModel' in self) {
+  // The Prompt API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the Prompt API is unsupported or availability checks return 'unavailable', you must gracefully fall back:
+
+* Remote API Fallback: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API).
+* Local API Fallback: Redirect the detection request to a local endpoint, for example, using Transformers.js. 

package/.agents/skills/modern-web-guidance/guides/built-in-ai/prompt-api.md

@@ -0,0 +1,189 @@
+The Prompt API allows developers to run natural language processing tasks directly in the browser using **Gemini Nano**. This built-in AI approach ensures user privacy, reduces server costs, and enables offline functionality.
+
+## 1. Getting Started and Hardware Requirements
+
+The Prompt API is currently available in Chrome as of version 148 (Desktop) for Windows, macOS, Linux, and Chromebook Plus.
+
+### Hardware Prerequisites
+
+- **Storage**: 22 GB free space (for the initial profile and model).
+- **Memory/CPU**: 16 GB RAM and 4+ CPU cores.
+- **GPU**: 4 GB VRAM or more (Required for audio input).
+- **Network**: Required only for the initial model download.
+
+### Initializing the API
+
+Check model availability before triggering a download:
+
+```javascript
+const availability = await LanguageModel.availability();
+
+// Do not call create() when unavailable — the model cannot run on this device.
+if (availability !== 'unavailable') {
+	const session = await LanguageModel.create({
+		monitor(m) {
+			// Inform the user while the model downloads so the UI doesn't appear frozen.
+			m.addEventListener('downloadprogress', (e) => {
+				console.log(`Downloaded ${e.loaded * 100}%`);
+			});
+		},
+	});
+}
+```
+
+## 2. Core Prompting Capabilities
+
+Session examples in this section omit `session.destroy()` for brevity. Always call `session.destroy()` when a session is no longer needed to free device memory (see Section 5).
+
+### Basic and Streamed Output
+
+For short responses, use `prompt()`. For longer content, use `promptStreaming()` to provide a more responsive UI.
+
+**MANDATORY**: Never assign model output to `innerHTML`. Model output is untrusted and can contain injected markup. Always use `textContent` or a sanitizer.
+
+```javascript
+const session = await LanguageModel.create();
+
+// prompt() accumulates the full response before resolving — use for short, one-shot output.
+const result = await session.prompt('Write a haiku about coding.');
+// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
+outputEl.textContent = result;
+
+// promptStreaming() yields independent chunks that must be concatenated;
+// use for longer content so each chunk can be rendered progressively.
+const stream = session.promptStreaming('Write a long story about a robot.');
+let completeResult = '';
+for await (const chunk of stream) {
+	completeResult += chunk;
+	outputEl.append(chunk);
+}
+console.log('Full story:', completeResult);
+```
+
+### Multimodal Input
+
+The Prompt API supports text, audio, and visual inputs (images, canvas, video frames).
+
+```javascript
+const session = await LanguageModel.create({
+	// Declaring expected input types lets the browser optimize model loading.
+	expectedInputs: [{ type: 'text' }, { type: 'image' }],
+	expectedOutputs: [{ type: 'text' }],
+});
+
+const response = await session.prompt([
+	{
+		role: 'user',
+		content: [
+			{ type: 'text', value: 'What is in this image?' },
+			{ type: 'image', value: document.querySelector('canvas') },
+		],
+	},
+]);
+```
+
+## 3. Advanced Session Management
+
+Sessions allow the model to maintain context across multiple interactions.
+
+### Context and Quota
+
+Each session has a maximum token limit. You can monitor usage via `session.contextUsage` and `session.contextWindow`. If the window overflows, the oldest messages (except the system prompt) are dropped.
+
+### Cloning Sessions
+
+Cloning is efficient for starting parallel conversations that share the same initial context (like a "system" personality) without re-initializing.
+
+```javascript
+const mainSession = await LanguageModel.create({
+	initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
+});
+
+const branchA = await mainSession.clone();
+const branchB = await mainSession.clone();
+// Destroy the base after cloning — the clones own their own context from here.
+mainSession.destroy();
+```
+
+### Restoring Past Sessions
+
+While a native "restore" feature is in development, you can recreate a session by feeding previous history into `initialPrompts`.
+
+**Note**: `localStorage` is unencrypted and persistent. Stored conversation history may include user PII — consider the privacy implications before persisting chat history.
+
+```javascript
+// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
+const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
+const session = await LanguageModel.create({
+	initialPrompts: history, // Array of {role, content} objects
+});
+```
+
+## 4. Structured Output with JSON Schema
+
+To prevent the model from adding "chatter" (e.g., "Sure, here is your JSON:"), use a **JSON Schema** via the `responseConstraint` field. This ensures the output is valid JSON that can be parsed immediately.
+
+### Example: Sentiment Classification
+
+```javascript
+// Pass the schema as a plain object — do not JSON.stringify() it first.
+const schema = {
+	type: 'object',
+	properties: {
+		rating: { type: 'number', minimum: 1, maximum: 5 },
+		is_positive: { type: 'boolean' },
+	},
+	required: ['rating', 'is_positive'],
+};
+
+const result = await session.prompt(
+	"Rate the following feedback: 'The food was great!'",
+	{ responseConstraint: schema },
+);
+
+const data = JSON.parse(result);
+console.log(data.rating); // 5
+```
+
+### Constraints and Prefixes
+
+You can guide the model further by prefilling the assistant's response using `prefix: true`.
+
+````javascript
+const character = await session.prompt([
+	{ role: 'user', content: 'Create a character sheet' },
+	{ role: 'assistant', content: '```json\n', prefix: true },
+]);
+````
+
+## 5. Best Practices and Safety
+
+- **Resource Cleanup**: Always call `session.destroy()` when a conversation is finished to free up memory.
+- **Output Safety**: Model output is untrusted. Always write results to `textContent`, not `innerHTML`, to prevent XSS injection from malicious model output.
+- Use a sanitizer like the native Sanitizer API or DOMPurify if you need to allow limited HTML.
+- **Aborting Tasks**: Use `AbortController` to allow users to stop long-running generations. Pass the `signal` to `prompt()` or `promptStreaming()`, not to `LanguageModel.create()`.
+- **Security**: Use Permission Policies to control access in iframes: `<iframe src="..." allow="language-model"></iframe>`.
+- **Design**: Review the [People + AI Guidebook](https://pair.withgoogle.com/guidebook/) to ensure responsible AI implementation.
+
+By combining structured outputs with robust session management, developers can build complex, stateful AI applications that run entirely on the user's device.
+
+## 6. Fallback strategies
+
+LanguageModel has limited availability.
+Supported by: Chrome 148 (May 2026).
+Unsupported in: Edge, Firefox, and Safari.
+
+Before use, check if the LanguageModel object is available in the global scope:
+
+```js
+if ('LanguageModel' in self) {
+  // The Prompt API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the Prompt API is unsupported or availability checks return 'unavailable', you must gracefully fall back:
+
+* Remote API Fallback: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API).
+* Local API Fallback: Redirect the detection request to a local endpoint, for example, using Transformers.js. 

package/.agents/skills/modern-web-guidance/guides/built-in-ai/summarizer.md

@@ -0,0 +1,154 @@
+The **Summarizer API** allows web developers to offer local, AI-powered text distillation directly within the browser using **Gemini Nano in Chrome or Phi in Edge**. This API supports various formats, including key points, headlines, and TL;DRs, while operating entirely on-device to ensure user privacy.
+
+---
+
+## Getting Started
+
+The Summarizer API is available starting in **Chrome and Edge 138**. It requires a one-time model download of Gemini Nano or Phi (respectively).
+
+
+### Hardware & Software Requirements
+
+- **OS**: Windows 10/11, macOS 13+, Linux, or ChromeOS (Chromebook Plus).
+- **Storage**: 22GB free space for the profile volume.
+- **RAM/CPU**: 16GB+ RAM and 4+ CPU cores.
+- **VRAM**: 4GB+ (if using GPU).
+
+### Model Download and Availability
+
+Check if the model is ready, needs downloading, or is unavailable. 
+
+**Mandatory Options Passing:** You must pass the identical configuration options object to both `Summarizer.availability(options)` and `Summarizer.create(options)`. Do NOT use the deprecated `window.ai.summarizer` API surface.
+
+**Mandatory Progress Monitoring:** You MUST implement a monitor for model download progress by providing a `monitor(m)` callback to `Summarizer.create()` and adding a listener for the `downloadprogress` event.
+
+**User Gesture Requirement:** When `availability` is `'downloadable'` or `'downloading'`, triggering the actual download via `Summarizer.create()` requires a user gesture (such as a user click). You must place the creation call inside an event listener rather than calling it unconditionally on page load to prevent `NotAllowedError`.
+
+```javascript
+const options = {
+  type: 'key-points',
+  format: 'plain-text',
+  length: 'medium'
+};
+
+const availability = await Summarizer.availability(options);
+
+if (availability === 'available') {
+  const summarizer = await Summarizer.create(options);
+  // Ready to use immediately
+} else if (availability === 'downloadable') {
+  // A user gesture is strictly required to start the download
+  document.getElementById('start-download-btn').addEventListener('click', async () => {
+    const summarizer = await Summarizer.create({
+      ...options,
+      monitor(m) {
+        m.addEventListener('downloadprogress', (e) => {
+          console.log(`Downloaded ${Math.round((e.loaded / e.total) * 100)}%`);
+        });
+      },
+    });
+  });
+}
+```
+
+## API Functions & Configuration
+
+When creating a summarizer via `Summarizer.create(options)`, you can customize
+the output:
+
+| Parameter    | Options                                    | Description                             |
+| :----------- | :----------------------------------------- | :-------------------------------------- |
+| `type`       | `key-points`, `tldr`, `teaser`, `headline` | Defines the summary strategy.           |
+| `format`     | `markdown`, `plain-text`                   | Output syntax style.                    |
+| `length`     | `short`, `medium`, `long`                  | Target length (e.g., 1 vs 5 sentences). |
+| `preference` | `auto`, `speed`, `capability`              | Balances latency vs. quality.           |
+
+### Example Configuration
+
+```javascript
+const options = {
+  sharedContext: 'This is a scientific article',
+  type: 'key-points',
+  format: 'markdown',
+  length: 'medium',
+};
+
+if (navigator.userActivation.isActive) {
+  const summarizer = await Summarizer.create(options);
+}
+```
+
+### Language Support
+
+You can specify expected languages to ensure the browser can handle the specific
+summary request.
+
+```javascript
+const summarizer = await Summarizer.create({
+  type: 'key-points',
+  expectedInputLanguages: ['en', 'ja'],
+  outputLanguage: 'es',
+});
+```
+
+## Summarization Methods
+
+### 1. Batch Summarization
+
+Processes the entire text at once and returns the result.
+
+```javascript
+const longText = document.querySelector('article').innerText;
+const summary = await summarizer.summarize(longText, {
+  context: 'This article is intended for a tech-savvy audience.',
+});
+console.log(summary);
+```
+
+### 2. Stream Summarization
+
+Returns results in real-time as the model generates them, providing a more
+responsive UI.
+
+```javascript
+const stream = summarizer.summarizeStreaming(longText);
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Security and Permissions
+
+- **Data Privacy**: No data is sent to Google; processing happens on the local
+  device.
+- **Cross-Origin**: Access can be granted to iframes using the Permission
+  Policy.
+  ```html
+  <iframe src="https://example.com/" allow="summarizer"></iframe>
+  ```
+- **Web Workers**: Currently not supported.
+
+## Fallback Strategy
+
+Summarizer has limited availability.
+Supported by: Chrome 138 (Jun 2025) and Edge 138 (Jun 2025).
+Unsupported in: Firefox and Safari.
+
+Before initializing or querying availability, check if the browser supports the `Summarizer` API:
+
+```javascript
+if ('Summarizer' in self) {
+  // The Summarizer API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the `Summarizer` API is unsupported or availability checks return `'unavailable'`, you must gracefully fall back.
+
+Recommended options:
+1. **Remote API Fallback**: Direct the distillation request to a server endpoint or remote API (such as the Vertex AI Gemini API) so that users still get summaries.
+2. **Graceful Degradation**: Visually disable the summarization controls in the UI, or hide the button while displaying a friendly message (e.g., `"Local summarization is currently unsupported in this browser"`). Do not allow interaction to trigger generic unhandled runtime exceptions.
+3. **Polyfill Fallback**: You can use community-maintained polyfills like `built-in-ai-task-apis-polyfills` or `prompt-api-polyfill` to emulate the API surface using remote services with models in the cloud or on-device inference with local models.
+
+> **Privacy and Cost Implications:** These polyfills possibly proxy requests to remote servers (such as Gemini API over the cloud). This completely nullifies the on-device privacy guarantees of the native Built-in AI APIs and will incur server-side API usage costs.