@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/browser-takeover/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: browser-takeover
+description: Protocol for handing browser control back to the user for sensitive operations (login, payment, 2FA). Goes beyond approval — actual tool handover.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [browser-handover, manual-login, browser-auth, sensitive-action]
+  tool_reminders: [For login/payment/2FA: emit [ASK: BROWSER_TAKEOVER — {url} — Please complete {action} manually, then tell me when done]]
+---
+
+## Browser Takeover Protocol
+
+When an agent encounters a sensitive operation that requires human interaction in a browser (login, payment, 2FA, CAPTCHA), it MUST hand control to the user rather than attempting to automate it.
+
+## Trigger Conditions
+
+Hand over browser control when:
+
+- **Authentication**: Login pages, SSO flows, OAuth consent screens
+- **Payment**: Checkout pages, payment form entry, subscription management
+- **2FA/MFA**: Two-factor authentication prompts, security key requests
+- **CAPTCHA**: Any CAPTCHA or human verification challenge
+- **Sensitive data entry**: Social security numbers, government IDs, bank details
+
+## Handover Message Format
+
+Use the ASK message type with BROWSER_TAKEOVER prefix:
+
+```
+[ASK: BROWSER_TAKEOVER — https://example.com/login — Please complete the login process manually, then tell me when done]
+```
+
+The message MUST include:
+
+1. `BROWSER_TAKEOVER` prefix for machine parsing
+2. The URL where the action is needed
+3. A clear description of what the user needs to do
+4. "tell me when done" to signal they should respond when complete
+
+## Integration with Approval System
+
+- Browser takeover is implicitly a HIGH-stake action (Constitution VII)
+- The agent BLOCKS until the user confirms completion
+- If the user reports failure, the agent should suggest alternative approaches
+
+## Rules
+
+- NEVER attempt to automate login credentials, even if provided
+- NEVER attempt to fill in payment information programmatically
+- NEVER bypass 2FA or CAPTCHA challenges
+- After the user completes the handover, verify the expected state before continuing
+- If browser MCP is available, use `browser:screenshot` after handover to verify state

package/.merlin-core/skills/general/claude-api/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: claude-api
+description: "Build apps with the Claude API or Anthropic SDK. TRIGGER when: code imports anthropic/@anthropic-ai/sdk/claude_agent_sdk, or user asks to use Claude API, Anthropic SDKs, or Agent SDK. DO NOT TRIGGER when: code imports openai/other AI SDK, general programming, or ML/data-science tasks."
+license: MIT (Anthropic)
+compatibility: claude-code
+metadata:
+  source: anthropic/skills
+  imported: 2026-03-15
+  version: "1.0"
+  auto_activate:
+    [claude-api, anthropic-sdk, anthropic-api, claude-sdk, agent-sdk]
+---
+
+# Building LLM-Powered Applications with Claude
+
+This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then follow the relevant patterns.
+
+## Defaults
+
+Unless the user requests otherwise:
+
+- Model: **Claude Opus 4.6** (`claude-opus-4-6`)
+- Thinking: `thinking: {type: "adaptive"}` for anything remotely complicated
+- Streaming: Default for long input/output or high `max_tokens`
+- Use `.get_final_message()` / `.finalMessage()` if you don't need stream events
+
+## Current Models
+
+| Model             | Model ID            | Context        | Input $/1M | Output $/1M |
+| ----------------- | ------------------- | -------------- | ---------- | ----------- |
+| Claude Opus 4.6   | `claude-opus-4-6`   | 200K (1M beta) | $5.00      | $25.00      |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00      | $15.00      |
+| Claude Haiku 4.5  | `claude-haiku-4-5`  | 200K           | $1.00      | $5.00       |
+
+**ALWAYS use `claude-opus-4-6` unless the user explicitly names a different model.**
+
+## Which Surface Should I Use?
+
+| Use Case                                        | Surface                  |
+| ----------------------------------------------- | ------------------------ |
+| Classification, summarization, extraction, Q&A  | Claude API (single call) |
+| Batch processing or embeddings                  | Claude API (batches)     |
+| Multi-step pipelines with code-controlled logic | Claude API + tool use    |
+| Custom agent with your own tools                | Claude API + tool use    |
+| AI agent with file/web/terminal access          | Agent SDK                |
+| Agentic coding assistant                        | Agent SDK                |
+| Built-in permissions and guardrails             | Agent SDK                |
+
+### Decision Tree
+
+1. Single LLM call → Claude API (one request, one response)
+2. Claude needs file/web/shell access → Agent SDK
+3. Multi-step workflow with your tools → Claude API + tool use
+4. Open-ended agent with your tools → Claude API agentic loop
+
+## Language Detection
+
+Check project files to determine language:
+
+- `*.py`, `requirements.txt` → **Python**
+- `*.ts`, `*.tsx`, `tsconfig.json` → **TypeScript**
+- `*.js`, `*.jsx` (no .ts) → **TypeScript** (same SDK)
+- `*.java`, `pom.xml` → **Java**
+- `*.go`, `go.mod` → **Go**
+- `*.rb`, `Gemfile` → **Ruby**
+- `*.cs`, `*.csproj` → **C#**
+- `*.php`, `composer.json` → **PHP**
+
+## Thinking & Effort
+
+**Opus 4.6 / Sonnet 4.6**: Use `thinking: {type: "adaptive"}`. `budget_tokens` is deprecated.
+
+**Effort parameter** (GA): `output_config: {effort: "low"|"medium"|"high"|"max"}`. Default is `high`. `max` is Opus 4.6 only.
+
+**Older models** (only if explicitly requested): `thinking: {type: "enabled", budget_tokens: N}`.
+
+## Compaction
+
+**Beta, Opus 4.6 only.** Requires beta header `compact-2026-01-12`. Append `response.content` (not just text) back to messages on every turn.
+
+## Common Pitfalls
+
+- Don't truncate inputs silently — notify user and discuss options
+- Use `thinking: {type: "adaptive"}` on Opus/Sonnet 4.6, NOT `budget_tokens`
+- Opus 4.6: no assistant message prefills (returns 400)
+- 128K output: requires streaming for large `max_tokens`
+- Always parse tool inputs with `json.loads()` / `JSON.parse()`
+- Use `output_config: {format: {...}}` not deprecated `output_format`
+- Don't reimplement SDK functionality — use built-in helpers
+- Don't define custom types for SDK data structures

package/.merlin-core/skills/general/code-javascript/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: code-javascript
+description: JavaScript and Node.js expertise covering ES6+, async patterns, and best practices
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [javascript, nodejs, npm-package, express-js, react-app]
+---
+
+# JavaScript & Node.js
+
+Expert knowledge of modern JavaScript (ES6+), Node.js runtime, package management, and JavaScript ecosystem best practices.
+
+## Patterns
+
+### Module Pattern
+
+```javascript
+// ES6 Modules
+export const config = { api: "url" };
+export function fetchData() {}
+export default class Service {}
+
+// CommonJS (Node.js)
+const utils = require("./utils");
+module.exports = { helper };
+```
+
+### Factory Pattern
+
+```javascript
+function createUser(name, role) {
+  return {
+    name,
+    role,
+    permissions: getPermissions(role),
+    hasPermission(perm) {
+      return this.permissions.includes(perm);
+    },
+  };
+}
+```
+
+### Observer Pattern
+
+```javascript
+class EventEmitter {
+  constructor() {
+    this.events = {};
+  }
+  on(event, listener) {
+    if (!this.events[event]) this.events[event] = [];
+    this.events[event].push(listener);
+  }
+  emit(event, data) {
+    this.events[event]?.forEach((listener) => listener(data));
+  }
+}
+```
+
+### Async Patterns
+
+```javascript
+// Async/Await (Preferred)
+async function fetchUser(id) {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    return await response.json();
+  } catch (error) {
+    console.error("Fetch failed:", error);
+    throw error;
+  }
+}
+
+// Promise chaining
+fetch("/api/data")
+  .then((res) => res.json())
+  .then((data) => processData(data))
+  .catch((error) => handleError(error))
+  .finally(() => cleanup());
+
+// Parallel execution
+const [users, posts, comments] = await Promise.all([
+  fetchUsers(),
+  fetchPosts(),
+  fetchComments(),
+]);
+
+// Sequential with error handling
+for (const item of items) {
+  await processItem(item); // One at a time
+}
+```
+
+## API Reference
+
+### Array Methods
+
+```javascript
+// Transform
+const doubled = numbers.map((n) => n * 2);
+const filtered = items.filter((item) => item.active);
+const sum = numbers.reduce((acc, n) => acc + n, 0);
+
+// Search
+const found = items.find((item) => item.id === id);
+const index = items.findIndex((item) => item.id === id);
+const exists = items.some((item) => item.active);
+const allActive = items.every((item) => item.active);
+
+// Iteration
+items.forEach((item) => process(item));
+for (const item of items) {
+} // Preferred for async
+```
+
+### Object Operations
+
+```javascript
+// Destructuring
+const { name, age, ...rest } = user;
+const [first, second, ...others] = array;
+
+// Spread operator
+const merged = { ...defaults, ...options };
+const combined = [...array1, ...array2];
+
+// Object methods
+Object.keys(obj);
+Object.values(obj);
+Object.entries(obj); // [[key, value], ...]
+Object.assign({}, obj1, obj2);
+```
+
+### String Methods
+
+```javascript
+str.includes("substring");
+str.startsWith("prefix");
+str.endsWith("suffix");
+str.trim();
+str.split(",");
+str.replace(/pattern/g, "replacement");
+`Template ${variable} strings`;
+```
+
+## Error Handling
+
+### Best Practices
+
+```javascript
+// Custom errors
+class ValidationError extends Error {
+  constructor(message, field) {
+    super(message);
+    this.name = "ValidationError";
+    this.field = field;
+  }
+}
+
+// Try-catch with async
+async function safeOperation() {
+  try {
+    const result = await riskyOperation();
+    return { success: true, data: result };
+  } catch (error) {
+    console.error("Operation failed:", error);
+    return { success: false, error: error.message };
+  }
+}
+
+// Error boundaries (React)
+class ErrorBoundary extends React.Component {
+  componentDidCatch(error, info) {
+    logError(error, info);
+  }
+}
+
+// Global error handlers (Node.js)
+process.on("unhandledRejection", (reason, promise) => {
+  console.error("Unhandled Rejection:", reason);
+});
+
+process.on("uncaughtException", (error) => {
+  console.error("Uncaught Exception:", error);
+  process.exit(1);
+});
+```
+
+## Common Pitfalls
+
+### 1. Async Without Await
+
+```javascript
+// BAD
+async function bad() {
+  doAsync(); // Promise ignored
+}
+
+// GOOD
+async function good() {
+  await doAsync();
+}
+```
+
+### 2. Array Mutations
+
+```javascript
+// BAD - Mutates original
+array.sort();
+array.reverse();
+
+// GOOD - Returns new array
+const sorted = [...array].sort();
+const reversed = [...array].reverse();
+```
+
+### 3. Floating Promises
+
+```javascript
+// BAD
+promises.forEach(async (p) => await p); // forEach ignores return
+
+// GOOD
+await Promise.all(promises);
+for (const p of promises) await p;
+```
+
+### 4. == vs ===
+
+```javascript
+// BAD
+if (value == null) {
+}
+
+// GOOD
+if (value === null || value === undefined) {
+}
+if (value == null) {
+} // OK only for null/undefined check
+```
+
+### 5. Memory Leaks
+
+```javascript
+// BAD
+setInterval(() => {}, 1000); // Never cleared
+
+// GOOD
+const interval = setInterval(() => {}, 1000);
+clearInterval(interval);
+
+// Event listeners
+element.addEventListener("click", handler);
+element.removeEventListener("click", handler);
+```
+
+## Performance Tips
+
+1. Use `const` and `let`, avoid `var`
+2. Prefer `for...of` over `.forEach()` for async operations
+3. Use `Promise.all()` for parallel async operations
+4. Debounce/throttle expensive operations
+5. Avoid blocking the event loop
+6. Use lazy loading for large imports
+7. Cache expensive computations
+8. Use Web Workers for CPU-intensive tasks