memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/zaraz/gotchas.md

@@ -0,0 +1,88 @@
+# Zaraz Gotchas
+
+## Events Not Firing
+
+**Check:**
+
+1. Tool enabled in dashboard (green dot)
+2. Trigger conditions met
+3. Consent granted for tool's purpose
+4. Tool credentials correct (GA4: `G-XXXXXXXXXX`, FB: numeric only)
+
+**Debug:**
+
+```javascript
+zaraz.debug = true
+console.log('Tools:', zaraz.tools)
+console.log('Consent:', zaraz.consent.getAll())
+```
+
+## Consent Issues
+
+**Modal not showing:**
+
+```javascript
+// Clear consent cookie
+document.cookie = 'zaraz-consent=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;'
+location.reload()
+```
+
+**Tools firing before consent:** Map tool to consent purpose with "Do not load until consent granted".
+
+## SPA Tracking
+
+**Route changes not tracked:**
+
+1. Configure History Change trigger in dashboard
+2. Hash routing (`#/path`) requires manual tracking:
+
+```javascript
+window.addEventListener('hashchange', () => {
+  zaraz.track('pageview', { page_path: location.pathname + location.hash })
+})
+```
+
+**React fix:**
+
+```javascript
+const location = useLocation()
+useEffect(() => {
+  zaraz.track('pageview', { page_path: location.pathname })
+}, [location]) // Include dependency
+```
+
+## Performance
+
+**Slow page load:**
+
+- Audit tool count (50+ degrades performance)
+- Disable blocking triggers unless required
+- Reduce event payload size (<100KB)
+
+## Tool-Specific Issues
+
+| Tool       | Issue                      | Fix                                  |
+| ---------- | -------------------------- | ------------------------------------ |
+| GA4        | Events not in real-time    | Wait 5-10 min, use DebugView         |
+| Facebook   | Invalid Pixel ID           | Use numeric only (no `fbpx_` prefix) |
+| Google Ads | Conversions not attributed | Include `send_to: 'AW-XXX/LABEL'`    |
+
+## Data Layer
+
+- Properties persist per page only - set on each page load
+- Nested access: `{{client.__zarazTrack.user.plan}}`
+
+## Limits
+
+| Resource         | Limit        |
+| ---------------- | ------------ |
+| Request size     | 100KB        |
+| Consent purposes | 20           |
+| API rate         | 1000 req/sec |
+
+## When NOT to Use Zaraz
+
+- Server-to-server tracking (use Workers)
+- Real-time bidirectional communication
+- Binary data transmission
+- Authentication flows

package/skills/cloudflare/references/zaraz/patterns.md

@@ -0,0 +1,77 @@
+# Zaraz Patterns
+
+## SPA Tracking
+
+**History Change Trigger (Recommended):** Configure in dashboard - no code needed, Zaraz auto-detects route changes.
+
+**Manual tracking (React/Vue/Next.js):**
+
+```javascript
+// On route change
+zaraz.track('pageview', { page_path: pathname, page_title: document.title })
+```
+
+## User Identification
+
+```javascript
+// Login
+zaraz.set({ userId: user.id, email: user.email, plan: user.plan })
+zaraz.track('login', { method: 'oauth' })
+
+// Logout - set to null (cannot clear)
+zaraz.set('userId', null)
+```
+
+## E-commerce Funnel
+
+| Event       | Method                                                              |
+| ----------- | ------------------------------------------------------------------- |
+| View        | `zaraz.ecommerce('Product Viewed', { product_id, name, price })`    |
+| Add to cart | `zaraz.ecommerce('Product Added', { product_id, quantity })`        |
+| Checkout    | `zaraz.ecommerce('Checkout Started', { cart_id, products: [...] })` |
+| Purchase    | `zaraz.ecommerce('Order Completed', { order_id, total, products })` |
+
+## A/B Testing
+
+```javascript
+zaraz.set('experiment_checkout', variant)
+zaraz.track('experiment_viewed', { experiment_id: 'checkout', variant })
+// On conversion
+zaraz.track('experiment_conversion', { experiment_id, variant, value })
+```
+
+## Worker Integration
+
+**Context Enricher** - Modify context before tools execute:
+
+```typescript
+export default {
+  async fetch(request, env) {
+    const body = await request.json()
+    body.system.userRegion = request.cf?.region
+    return Response.json(body)
+  },
+}
+```
+
+Configure: Zaraz > Settings > Context Enrichers
+
+**Worker Variables** - Compute dynamic values server-side, use as `{{worker.variable_name}}`.
+
+## GTM Migration
+
+| GTM                                   | Zaraz                                       |
+| ------------------------------------- | ------------------------------------------- |
+| `dataLayer.push({event: 'purchase'})` | `zaraz.ecommerce('Order Completed', {...})` |
+| `{{Page URL}}`                        | `{{system.page.url}}`                       |
+| `{{Page Title}}`                      | `{{system.page.title}}`                     |
+| Page View trigger                     | Pageview trigger                            |
+| Click trigger                         | Click (selector: `*`)                       |
+
+## Best Practices
+
+1. Use dashboard triggers over inline code
+2. Enable History Change for SPAs (no manual code)
+3. Debug with `zaraz.debug = true`
+4. Implement consent early (GDPR/CCPA)
+5. Use Context Enrichers for sensitive/server data

package/skills/docker/SKILL.md

@@ -1,11 +1,9 @@
 ---
 name: docker
 description: |
-  Production-grade Docker and container best practices. Use when writing
-  Dockerfiles, configuring Docker Compose, optimizing image size and build
-  speed, implementing security hardening, or debugging container issues.
-  Triggers on "Docker", "Dockerfile", "container", "Compose", "BuildKit",
-  "multi-stage build", "image size", "docker-compose".
+  Production-grade Docker and container best practices. Use when containerizing apps with Docker, 
+  writing Dockerfiles, or managing Docker Compose environments.
+  "multi-stage build", "image size", "docker-compose". Use ONLY when a Dockerfile or container registry is the explicit target for deployment. NOT for serverless or Cloudflare Workers. NOT for generic app deployment without containers. NOT for orchestrating CI/CD pipelines natively (use github-actions instead). Do NOT trigger for generic "deploy my app" requests without clarifying the target platform.
 ---
 
 # Docker & Container Engineering Standards
@@ -43,35 +41,7 @@ Place this as the **first line** of every Dockerfile. It enables:
 ## 2. Multi-Stage Builds (Required for Production)
 
 Multi-stage builds are **mandatory** for any production image. They separate build-time dependencies from runtime.
-
-```dockerfile
-# syntax=docker/dockerfile:1
-
-# ── Stage 1: Build ─────────────────────────────
-FROM node:22-slim AS builder
-WORKDIR /app
-COPY package.json pnpm-lock.yaml ./
-RUN corepack enable && pnpm install --frozen-lockfile
-COPY . .
-RUN pnpm run build
-
-# ── Stage 2: Runtime ───────────────────────────
-FROM node:22-slim AS runtime
-WORKDIR /app
-ENV NODE_ENV=production
-
-# Create non-root user
-RUN groupadd -r appgroup && useradd -r -g appgroup appuser
-
-# Copy ONLY production artifacts
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/package.json ./
-
-USER appuser
-EXPOSE 3000
-CMD ["node", "dist/index.js"]
-```
+See **[templates.md](references/templates.md)** for the full annotated Multi-Stage Build template.
 
 ### Key Rules
 
@@ -178,75 +148,11 @@ coverage/
 - **ALWAYS** exclude `node_modules` — reinstall inside the container
 - **ALWAYS** exclude `.env*` — prevents secret leaks
 
-## 5. Docker Compose v2
-
-### Structure
-
-```yaml
-# docker-compose.yml
-services:
-  app:
-    build:
-      context: .
-      dockerfile: Dockerfile
-      target: runtime # Target a specific stage
-    ports:
-      - '3000:3000'
-    environment:
-      NODE_ENV: production
-    depends_on:
-      db:
-        condition: service_healthy
-    restart: unless-stopped
-
-  db:
-    image: postgres:17-alpine
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-    environment:
-      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
-    secrets:
-      - db_password
-    healthcheck:
-      test: ['CMD-SHELL', 'pg_isready -U postgres']
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  pgdata:
-
-secrets:
-  db_password:
-    file: ./secrets/db_password.txt
-```
-
-### Best Practices
+## 5. Advanced Examples & CI/CD
 
-- **Use `depends_on` with health checks** — not just service start order
-- **Use named volumes** for persistent data — never bind-mount the entire project in production
-- **Use environment files** (`env_file:`) for non-secret config
-- **Use `secrets:`** for credentials — they are mounted as files, not env vars
-- **Pin image versions** — `postgres:17-alpine`, not `postgres:latest`
-
-## 6. CI/CD Integration
-
-### GitHub Actions Pattern
-
-```yaml
-- name: Build and push
-  uses: docker/build-push-action@<sha>
-  with:
-    context: .
-    push: true
-    tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
-    cache-from: type=gha
-    cache-to: type=gha,mode=max
-```
+For advanced Docker Compose configurations and GitHub Actions CI/CD workflows, see the reference file:
 
-- **Use GitHub Actions cache** (`type=gha`) for CI builds
-- **Tag with commit SHA** — never `:latest` for production
-- **Scan before push** — run vulnerability scanning as a build step
+**[Read: references/advanced-examples.md](references/advanced-examples.md)**
 
 ## 7. Anti-Patterns (Never Do These)
 

package/skills/docker/references/advanced-examples.md

@@ -0,0 +1,71 @@
+# Advanced Docker & Compose Examples
+
+## Docker Compose v2
+
+### Structure
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: runtime # Target a specific stage
+    ports:
+      - '3000:3000'
+    environment:
+      NODE_ENV: production
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
+
+  db:
+    image: postgres:17-alpine
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    environment:
+      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
+    secrets:
+      - db_password
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:
+
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+```
+
+### Best Practices
+
+- **Use `depends_on` with health checks** — not just service start order
+- **Use named volumes** for persistent data — never bind-mount the entire project in production
+- **Use environment files** (`env_file:`) for non-secret config
+- **Use `secrets:`** for credentials — they are mounted as files, not env vars
+- **Pin image versions** — `postgres:17-alpine`, not `postgres:latest`
+
+## CI/CD Integration
+
+### GitHub Actions Pattern
+
+```yaml
+- name: Build and push
+  uses: docker/build-push-action@<sha>
+  with:
+    context: .
+    push: true
+    tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+- **Use GitHub Actions cache** (`type=gha`) for CI builds
+- **Tag with commit SHA** — never `:latest` for production
+- **Scan before push** — run vulnerability scanning as a build step

package/skills/docker/references/templates.md

@@ -0,0 +1,34 @@
+# Docker Templates
+
+## Multi-Stage Build
+
+Multi-stage builds are **mandatory** for any production image. They separate build-time dependencies from runtime.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
+# ── Stage 1: Build ─────────────────────────────
+FROM node:22-slim AS builder
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm run build
+
+# ── Stage 2: Runtime ───────────────────────────
+FROM node:22-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+# Create non-root user
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+
+# Copy ONLY production artifacts
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./
+
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```

package/skills/docs-marketer/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: docs-marketer
+description: |
+  Documentation marketability audit for repository README, Docker Hub README,
+  Wiki, and registry listings. Evaluates feature visibility, first impressions,
+  competitive differentiation, onboarding friction, and cross-document
+  consistency. Use when improving README quality, surfacing under-marketed
+  features, preparing docs for a launch, or when the user says "improve my
+  README", "market my docs", "make my docs better", "README audit",
+  "under-marketed features", "improve discoverability", or "README review".
+  NOT for structural compliance or source-of-truth parity (use /doc-audit).
+---
+
+# Docs Marketer
+
+A documentation marketability audit system that evaluates whether accurate
+documentation is _effectively marketed_. While `/doc-audit` answers "are the
+docs correct?", this skill answers "are the docs compelling?"
+
+Surfaces under-promoted features, evaluates first impressions, identifies
+onboarding friction, and scores competitive differentiation across all
+documentation surfaces (README, Docker Hub, Wiki, MCP Registry, npm).
+
+## When to Load
+
+Load this skill when any of these apply:
+
+- Improving documentation to better market a project's capabilities
+- Preparing documentation for a product launch or major release
+- Auditing whether powerful features are adequately surfaced in docs
+- Evaluating README first impressions and competitive positioning
+- Reviewing documentation tone, voice, and consistency across surfaces
+- The user asks to "improve my README", "market my docs", "what features am
+  I under-marketing", "make my docs more compelling", "README review",
+  "audit my docs for marketing", or "improve discoverability"
+
+**Do NOT load** for:
+
+- Structural compliance checks (use `/doc-audit` instead)
+- Source-of-truth parity against source code (use `/doc-audit` instead)
+- Code quality audits (use `adversarial-performance` or `autonomous-dev`)
+
+## Target Resolution
+
+Before starting, resolve which repository to audit. If the user did not
+specify a repository:
+
+1. **Check workspace context** — look at the active workspace roots and any
+   `PROJECT_REGISTRY` configuration. If there is exactly one candidate
+   repository, use it.
+2. **Infer from conversation** — if the user recently discussed a specific
+   project or the briefing identifies an active repository, prefer that.
+3. **Ask the user** — if the target is still ambiguous (e.g., multiple
+   registered workspaces, no clear context), ask which repository to audit
+   before proceeding. Do not guess.
+
+Once resolved, confirm the target repository and its absolute path in your
+first output so the user can verify before the audit begins.
+
+## Audit Modes
+
+### Standard Mode (Default)
+
+Single-pass structured audit. Agent A (The Marketer) inventories all
+documentation surfaces, scores each against 10 categories, and produces a
+prioritized improvement plan. Fast and practical — best for routine docs
+reviews.
+
+### Adversarial Mode (`AUDIT_DEPTH: adversarial`)
+
+Full dual-agent pipeline. After Agent A's baseline profile, Agent B (The
+Skeptical Reader) simulates a developer discovering the project for the first
+time — evaluating the 30-second impression, identifying friction, and
+challenging marketing claims. Produces deeper insights at the cost of more
+time and tokens.
+
+## Audit Categories
+
+The 10 marketability categories evaluated per document surface:
+
+| #   | Category                    | Focus                                                     |
+| --- | --------------------------- | --------------------------------------------------------- |
+| 1   | Feature Visibility          | Are all capabilities discoverable in docs?                |
+| 2   | First Impression            | Does the repo sell itself in the first 30 seconds?        |
+| 3   | Information Architecture    | Heading hierarchy, scannability, progressive disclosure   |
+| 4   | Visual Assets               | Mermaid diagrams, badges, screenshots, callouts           |
+| 5   | Competitive Differentiation | Does the value proposition clearly stand out?             |
+| 6   | Onboarding Friction         | Quick Start clarity, copy-paste readiness                 |
+| 7   | Platform Presence           | Docker Hub, npm, MCP Registry, GitHub description/topics  |
+| 8   | Cross-Document Consistency  | Feature counts, naming, version alignment across surfaces |
+| 9   | Tone & Voice                | Confident, consistent, audience-appropriate               |
+| 10  | SEO & Discoverability       | Keywords, GitHub topics, heading keyword density          |
+
+For the full rubric with scoring guides, checklists, and anti-patterns, read
+[references/audit-categories.md](references/audit-categories.md).
+
+## Adversarial Protocol
+
+This skill follows the standard dual-agent adversarial pattern (Agent A: The
+Marketer, Agent B: The Skeptical Reader) when `AUDIT_DEPTH` is set to
+`adversarial`.
+
+For the core pipeline rules, phase definitions, and agent switching protocols,
+read:
+**[../adversarial-security/references/adversarial-base-protocol.md](../adversarial-security/references/adversarial-base-protocol.md)**
+
+For the docs-marketer-specific protocol with scoring, templates, and the
+Skeptical Reader review dimensions, read:
+**[references/multi-pass-docs-protocol.md](references/multi-pass-docs-protocol.md)**
+
+## External Validation (Phase 4)
+
+Phase 4 triggers an independent validation pass using the GitHub CLI
+(`gh copilot`). The `copilot` subcommand is built into modern `gh` CLI — no
+separate extension is needed. This provides a fundamentally different model's
+perspective on documentation quality, catching marketing blind spots that
+internal review normalizes.
+
+For prompts, read
+[references/copilot-docs-prompts.md](references/copilot-docs-prompts.md).
+
+**Prerequisites:** `gh` CLI v2.x+ with `gh auth status` passing. If
+`gh copilot` is not available, skip Phase 4 gracefully and note the skip in
+the journal entry.
+
+Read [references/copilot-usage.md](references/copilot-usage.md) for critical
+non-interactive execution requirements.
+
+## Feedback Loop
+
+Every phase creates a journal entry for future retrieval. For templates and
+tag conventions, read
+[references/feedback-loop.md](references/feedback-loop.md).
+
+## Prompt Improvement
+
+If during any phase you notice an opportunity to improve the audit — a
+category checklist that missed an important signal, a Copilot prompt that
+produced weak results, or a scoring rubric that didn't capture real quality
+differences — note it as a `### Prompt Improvement Opportunity` in your
+journal entry for that phase. Include:
+
+- **What happened**: The specific gap or weak result
+- **Suggested fix**: Concrete wording change, new checklist item, or
+  revised prompt
+- **Category affected**: Which of the 10 categories or Copilot prompts
+
+These observations accumulate in the journal and inform future skill
+refinement cycles via `skill-builder`.
+
+## Configuration
+
+| Variable             | Default    | Description                                                                |
+| -------------------- | ---------- | -------------------------------------------------------------------------- |
+| `AUDIT_DEPTH`        | `standard` | Depth: `standard` (single-pass) or `adversarial` (dual-agent)              |
+| `MAX_AUDIT_PASSES`   | `2`        | Maximum adversarial cycles (phases 2–3 repeat). Ignored in standard mode.  |
+| `COPILOT_VALIDATION` | `true`     | Enable/disable Copilot extension validation phase                          |
+| `TARGET_DOCS`        | `auto`     | Auto-detect surfaces or explicit list (e.g., `README.md,DOCKER_README.md`) |
+
+### Audit Depth Profiles
+
+- **Standard**: All 10 categories scored per surface. Agent A only. Best for
+  routine checks and quick improvement passes. Produces a prioritized
+  improvement plan directly.
+- **Adversarial**: Full dual-agent pipeline with Skeptical Reader stress
+  testing. Agent B simulates first-time discovery, competitive evaluation,
+  and friction audits. Best for launch preparation, major releases, or when
+  you want the deepest analysis.
+
+## Synergies
+
+| Skill/Workflow                   | Relationship                                                                |
+| -------------------------------- | --------------------------------------------------------------------------- |
+| `/doc-audit`                     | Structural compliance — run first, then `docs-marketer` for marketing       |
+| `skill-builder`                  | Defines quality standards for skill docs; this skill applies marketing lens |
+| `adversarial-planner`            | Parent adversarial pattern — plan-level review                              |
+| `adversarial-skill-audit`        | Sibling — audits skill quality; this audits doc marketability               |
+| MCP Documentation Standards (KI) | Badge standards, wiki structure, release notes patterns                     |