@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/cloudflare/references/zaraz/README.md

@@ -0,0 +1,360 @@
+# Cloudflare Zaraz Skill
+
+Expert guidance for Cloudflare Zaraz - server-side tag manager for loading third-party tools at the edge.
+
+## What is Zaraz?
+
+Zaraz offloads third-party scripts (analytics, ads, chat, marketing) to Cloudflare's edge, improving site speed, privacy, and security. Zero client-side performance impact.
+
+## Core Concepts
+
+- **Server-side execution** - Scripts run on Cloudflare, not user's browser
+- **Single HTTP request** - All tools loaded via one endpoint
+- **Privacy-first** - Control data sent to third parties
+- **No client-side JS** - Minimal browser overhead
+
+## Zaraz Dashboard Setup
+
+1. Navigate to domain > Zaraz
+2. Click "Start setup"
+3. Add tools (Google Analytics, Facebook Pixel, etc.)
+4. Configure triggers and actions
+
+## Web API
+
+Zaraz provides `zaraz` object in browser:
+
+### Track Events
+
+```javascript
+// Basic event
+zaraz.track('button_click');
+
+// Event with properties
+zaraz.track('purchase', {
+  value: 99.99,
+  currency: 'USD',
+  item_id: '12345'
+});
+
+// E-commerce events
+zaraz.track('add_to_cart', {
+  product_name: 'Widget',
+  price: 29.99,
+  quantity: 1
+});
+```
+
+### Set User Properties
+
+```javascript
+zaraz.set('userId', 'user_12345');
+zaraz.set('plan', 'premium');
+zaraz.set({
+  email: '[email protected]',
+  country: 'US',
+  age: 30
+});
+```
+
+### E-commerce Tracking
+
+```javascript
+// Product view
+zaraz.ecommerce('Product Viewed', {
+  product_id: 'SKU123',
+  name: 'Blue Widget',
+  price: 49.99,
+  currency: 'USD'
+});
+
+// Add to cart
+zaraz.ecommerce('Product Added', {
+  product_id: 'SKU123',
+  quantity: 2,
+  price: 49.99
+});
+
+// Purchase
+zaraz.ecommerce('Order Completed', {
+  order_id: 'ORD-789',
+  total: 149.98,
+  revenue: 149.98,
+  shipping: 10.00,
+  tax: 12.50,
+  currency: 'USD',
+  products: [
+    { product_id: 'SKU123', quantity: 2, price: 49.99 }
+  ]
+});
+```
+
+## Consent Management
+
+```javascript
+// Check consent status
+if (zaraz.consent.getAll().analytics) {
+  zaraz.track('page_view');
+}
+
+// Request consent
+zaraz.consent.modal = true; // Show consent modal
+
+// Set consent programmatically
+zaraz.consent.setAll({
+  analytics: true,
+  marketing: false,
+  preferences: true
+});
+
+// Listen for consent changes
+zaraz.consent.addEventListener('consentChanged', () => {
+  console.log('Consent updated:', zaraz.consent.getAll());
+});
+```
+
+## Workers Integration
+
+Access Zaraz data in Workers:
+
+```typescript
+export default {
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    
+    // Inject Zaraz tracking
+    if (url.pathname === '/checkout') {
+      const response = await fetch(req);
+      const html = await response.text();
+      
+      const tracking = `
+        <script>
+          zaraz.track('checkout_started', {
+            cart_value: 99.99
+          });
+        </script>
+      `;
+      
+      const modified = html.replace('</body>', tracking + '</body>');
+      return new Response(modified, response);
+    }
+    
+    return fetch(req);
+  }
+};
+```
+
+## Triggers
+
+Configure when tools fire:
+
+### Page Rules
+
+- **Pageview** - On every page load
+- **DOM Ready** - When DOM is ready
+- **Click** - Element clicks (CSS selector)
+- **Form submission** - Form submits
+- **Scroll depth** - User scrolls percentage
+- **Timer** - After time elapsed
+- **Variable match** - Custom conditions
+
+### Example Trigger
+
+```
+Trigger: Button Click
+Match rule: CSS Selector = .buy-button
+Action: Track event "purchase_intent"
+```
+
+## Common Tools
+
+### Google Analytics 4
+
+```javascript
+// Track page view (automatic)
+zaraz.track('pageview');
+
+// Custom event
+zaraz.track('sign_up', {
+  method: 'email'
+});
+```
+
+### Facebook Pixel
+
+```javascript
+zaraz.track('PageView');
+zaraz.track('Purchase', {
+  value: 99.99,
+  currency: 'USD'
+});
+```
+
+### Google Ads Conversion
+
+```javascript
+zaraz.track('conversion', {
+  send_to: 'AW-XXXXXXXXX/YYYYYY',
+  value: 1.00,
+  currency: 'USD'
+});
+```
+
+## Custom Managed Components
+
+Build custom tools:
+
+```javascript
+// Example: Custom analytics tool
+export default class CustomAnalytics {
+  async handleEvent(event) {
+    const { type, payload } = event;
+    
+    await fetch('https://analytics.example.com/track', {
+      method: 'POST',
+      body: JSON.stringify({
+        event: type,
+        properties: payload,
+        timestamp: Date.now()
+      })
+    });
+  }
+}
+```
+
+## Data Layer
+
+Use `zaraz.dataLayer` for structured data:
+
+```javascript
+// Set data layer
+window.zaraz.dataLayer = {
+  user_id: '12345',
+  page_type: 'product',
+  category: 'electronics'
+};
+
+// Access in triggers
+// Variable: {{client.__zarazTrack.page_type}}
+```
+
+## Server-Side Configuration
+
+### zaraz.toml
+
+```toml
+[settings]
+auto_inject = true
+debug_mode = false
+
+[[tools]]
+type = "google-analytics"
+id = "G-XXXXXXXXXX"
+
+[[tools.triggers]]
+match_rule = "Pageview"
+```
+
+## Privacy Features
+
+1. **IP anonymization** - Automatic
+2. **Cookie control** - Consent-based
+3. **Data minimization** - Send only necessary data
+4. **Regional compliance** - GDPR, CCPA support
+
+## Performance
+
+```javascript
+// Zaraz automatically:
+// - Batches requests
+// - Defers non-critical scripts
+// - Proxies third-party requests
+// - Caches tool configurations
+
+// Result: ~0ms client-side overhead
+```
+
+## Debugging
+
+```javascript
+// Enable debug mode in dashboard, then:
+zaraz.debug = true;
+
+// View events in console
+zaraz.track('test_event', { debug: true });
+
+// Check loaded tools
+console.log(zaraz.tools);
+```
+
+## Best Practices
+
+1. **Use triggers** instead of inline `zaraz.track()` when possible
+2. **Batch events** for related actions
+3. **Test with debug mode** before production
+4. **Implement consent** for GDPR compliance
+5. **Monitor performance** in dashboard analytics
+6. **Use data layer** for structured data
+
+## Common Patterns
+
+### SPA Tracking
+
+```javascript
+// On route change
+router.afterEach((to, from) => {
+  zaraz.track('pageview', {
+    page_path: to.path,
+    page_title: to.meta.title
+  });
+});
+```
+
+### User Identification
+
+```javascript
+// On login
+zaraz.set('user_id', user.id);
+zaraz.set('user_email', user.email);
+zaraz.track('login', { method: 'password' });
+```
+
+### A/B Testing
+
+```javascript
+const variant = Math.random() < 0.5 ? 'A' : 'B';
+zaraz.set('ab_test_variant', variant);
+zaraz.track('ab_test_view', { variant });
+```
+
+## Limits
+
+- **Tools**: Unlimited
+- **Events**: Unlimited
+- **Data retention**: Per tool's policy
+- **Request size**: 100KB per request
+
+## Troubleshooting
+
+### Events not firing
+
+- Check trigger conditions in dashboard
+- Verify tool is enabled
+- Enable debug mode
+- Check browser console for errors
+
+### Consent issues
+
+- Verify consent modal configuration
+- Check `zaraz.consent.getAll()` status
+- Ensure tools respect consent settings
+
+## Reference
+
+- [Zaraz Docs](https://developers.cloudflare.com/zaraz/)
+- [Web API](https://developers.cloudflare.com/zaraz/web-api/)
+- [Managed Components](https://developers.cloudflare.com/zaraz/advanced/load-custom-managed-component/)
+
+---
+
+This skill focuses exclusively on Zaraz. For Workers development, see `cloudflare-workers` skill.

package/dist/template/.opencode/skill/code-search-patterns/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: code-search-patterns
+description: Use when navigating unfamiliar code with search-first patterns, combining built-in/LSP navigation with tilth MCP (main agent) and tilth CLI (subagents)
+version: 1.0.0
+tags: [workflow, code-quality, context, subagent]
+dependencies: []
+---
+
+# Code Search Patterns
+
+Unified navigation skill for fast, low-waste code understanding across both execution modes:
+
+- **Main agent**: built-in tools + LSP + tilth MCP
+- **Subagents**: Bash + `npx -y tilth` CLI
+
+This skill merges practical navigation heuristics with concrete tool usage so you can locate behavior, trace impact, and edit safely with fewer calls.
+
+## When to Use
+
+- Exploring unfamiliar modules before editing
+- Tracing call chains across files and directories
+- Checking blast radius before signature/export changes
+- Dispatching subagents that need structural code navigation
+- Reducing token/tool-call waste during implementation
+
+## When NOT to Use
+
+- Trivial single-file edits where symbol location is already known
+- Pure docs/config reads with no dependency tracing
+- Tasks focused on external web research (use web research tools instead)
+
+## Core Principle
+
+> Collapse multiple tool calls into fewer, smarter ones. Every unnecessary read or search wastes tokens and turns.
+
+## Navigation Patterns
+
+### 1) Search First, Read Second
+
+Start with symbol/content search to find exact locations, then read only the needed slice.
+
+- **Good**: `search -> targeted read`
+- **Avoid**: `read many files -> search later`
+
+Use LSP (`findReferences`, `outgoingCalls`) or tilth search first; read deep only after narrowing scope.
+
+### 2) Multi-Symbol Search
+
+When flow spans multiple functions, query them together (`A,B,C`) instead of serial one-by-one lookups.
+
+- Faster call-chain reconstruction
+- Fewer repeated scans of the same files
+
+### 3) Don’t Re-Read What Search Already Returned
+
+If search output already includes definition body/context, proceed from it.
+Re-read only when you need:
+
+- exact edit anchors,
+- additional surrounding lines,
+- or untruncated content.
+
+### 4) Blast Radius Check (Before Breaking Changes)
+
+Before renaming/removing/changing signatures, inspect downstream impact first.
+
+- LSP: `findReferences`, `incomingCalls`
+- tilth: `tilth_tilth_deps` or `--deps`
+
+Then apply edits from dependents inward.
+
+### 5) Context Locality
+
+Prefer nearby package/module scope first.
+
+- built-in search: constrain `path`
+- tilth: pass `scope` / `context`
+
+Locality reduces irrelevant matches and token churn.
+
+### 6) Outline Before Deep Read
+
+For large files, inspect structure first (symbols/outline), then read only target sections.
+
+- LSP: `documentSymbol`
+- tilth read: smart outline by default, then section drill-in
+
+### 7) Follow Call Chain, Not File Tree
+
+Start at entry behavior and walk calls (`definition -> outgoing -> next definition`) instead of reading folders linearly.
+
+This exposes real execution flow with fewer reads.
+
+## tilth MCP (Main Agent)
+
+Use MCP variants when available in the main agent session:
+
+- `tilth_tilth_search`
+- `tilth_tilth_read`
+- `tilth_tilth_files`
+- `tilth_tilth_deps`
+
+### Built-in/LSP vs tilth MCP (when to choose which)
+
+| Need                    | Built-in / LSP                         | Prefer tilth MCP when                                       | Why tilth helps                     |
+| ----------------------- | -------------------------------------- | ----------------------------------------------------------- | ----------------------------------- |
+| Find symbols/usages     | `grep` / `lsp.findReferences`          | You want definitions + usages + expanded source in one call | Reduces search+read round trips     |
+| Read file content       | `read`                                 | File is large or you only need structure first              | Smart outline + section targeting   |
+| List candidate files    | `glob`                                 | You want quick glob results with token-aware relevance      | Faster triage for large directories |
+| Pre-change impact check | `lsp.incomingCalls` + manual follow-up | You need import + dependent view before breaking change     | Single blast-radius view via deps   |
+
+Guideline: if tilth MCP is active, use it as default for navigation; fall back to built-in/LSP when you need language-server-specific semantics or exact editor-position operations.
+
+## tilth CLI (Subagents)
+
+### Why this exists
+
+Subagents typically cannot call MCP tools directly. They can still use tilth through Bash:
+
+```bash
+npx -y tilth <query> [flags]
+```
+
+### Auto-detection
+
+| Query shape                       | Auto-detected action                 |
+| --------------------------------- | ------------------------------------ |
+| Existing file path (`src/foo.ts`) | Read file (smart outline/full)       |
+| Identifier (`initCommand`)        | Symbol search (definitions + usages) |
+| Glob (`*.test.ts`)                | List files                           |
+| Plain text / phrase               | Content search                       |
+
+Use `--kind` to force a specific mode when needed.
+
+### Core operations
+
+#### 1) Read file
+
+```bash
+npx -y tilth src/index.ts
+npx -y tilth src/index.ts --full
+npx -y tilth src/index.ts --section 45-89
+```
+
+#### 2) Search symbols
+
+```bash
+npx -y tilth initCommand --scope src/
+npx -y tilth "initCommand,detectMode" --scope src/
+```
+
+#### 3) Search text/regex
+
+```bash
+npx -y tilth --kind content "TODO" --scope src/
+npx -y tilth --kind regex "/TODO.*fix/" --scope src/
+```
+
+#### 4) Find callers
+
+```bash
+npx -y tilth --kind callers initCommand --scope src/
+```
+
+#### 5) List files
+
+```bash
+npx -y tilth "*.test.ts" --scope src/
+```
+
+#### 6) Blast radius / deps
+
+```bash
+npx -y tilth --deps src/commands/init.ts --scope src/
+```
+
+#### 7) Codebase map
+
+```bash
+npx -y tilth --map --scope src/
+```
+
+### Useful flags
+
+| Flag              | Purpose                        | Example                      |
+| ----------------- | ------------------------------ | ---------------------------- | ------------------- | ----------------- | ---------------- |
+| `--scope <dir>`   | Restrict scan area             | `--scope src/commands/`      |
+| `--section <range | heading>`                      | Targeted file slice          | `--section 120-180` |
+| `--full`          | Force full file output         | `--full`                     |
+| `--budget <n>`    | Limit output size              | `--budget 2000`              |
+| `--json`          | Machine-readable output        | `--json`                     |
+| `--map`           | Structural project skeleton    | `--map --scope src/`         |
+| `--kind <symbol   | content                        | regex                        | callers>`           | Force search mode | `--kind callers` |
+| `--deps <file>`   | Import/dependent blast radius  | `--deps src/utils/errors.ts` |
+| `--expand <n>`    | Expand top matches with source | `--expand 3`                 |
+
+### MCP vs CLI
+
+| Capability                   | MCP (main agent)                                   | CLI (subagents)                            |
+| ---------------------------- | -------------------------------------------------- | ------------------------------------------ |
+| Access mode                  | Tool call                                          | Bash command                               |
+| Session dedup/context carry  | Yes                                                | No                                         |
+| Hash-anchored edit flow      | Yes (via MCP edit tools)                           | No                                         |
+| Symbol/content/regex/callers | Yes                                                | Yes                                        |
+| Deps/blast-radius            | Yes                                                | Yes                                        |
+| Codebase map                 | Limited by toolset                                 | Yes (`--map`)                              |
+| Best for                     | Interactive main-agent navigation + edit workflows | Subagent discovery/exploration without MCP |
+
+### Example subagent dispatch
+
+```ts
+task({
+  subagent_type: "general",
+  prompt: `Use tilth CLI via Bash for navigation.
+
+1) Locate symbol and usages:
+npx -y tilth initCommand --scope src/
+
+2) Find callers:
+npx -y tilth --kind callers initCommand --scope src/
+
+3) Check blast radius before edits:
+npx -y tilth --deps src/commands/init.ts --scope src/
+
+4) Read only the relevant section:
+npx -y tilth src/commands/init.ts --section 500-620
+
+Then implement the requested change with minimal file edits.`,
+});
+```
+
+## Cost Awareness
+
+Navigation cost compounds quickly. Optimize for fewer, richer calls.
+
+- Prefer one structural search over multiple blind reads
+- Reuse search output; avoid duplicate reads of the same symbol body
+- Scope aggressively (`path`, `scope`) to cut noise
+- Use section reads for large files instead of full-file pulls
+
+Target heuristic: understand a symbol and its direct impact in **≤3 calls** whenever possible.
+
+## Common Mistakes
+
+| Mistake                                          | Better pattern                                                      |
+| ------------------------------------------------ | ------------------------------------------------------------------- |
+| Reading big files before locating symbol         | Search first, then section read                                     |
+| Re-reading code already shown in search output   | Work from returned snippet; re-read only if needed for edit anchors |
+| Serially tracing one function at a time          | Multi-symbol search + callers/deps                                  |
+| Ignoring blast radius before API/signature edits | Run references/incoming/deps first                                  |
+| Unscoped repository-wide search                  | Use `path`/`--scope` to localize                                    |
+| Using CLI defaults when mode is ambiguous        | Force with `--kind`                                                 |
+| Overusing `--full` on large files                | Outline first, then `--section`                                     |