memory-journal-mcp 7.7.0 → 8.0.0

package/skills/next-cache-components/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: next-cache-components
+description: |
+  Next.js 16 Cache Components guidance. Use when refactoring React Server Components for performance, debugging Partial Prerendering (PPR) issues, or applying the `use cache` directive, `cacheLife`, `cacheTag`, `updateTag`, and `revalidateTag`.
+  Also use when deciding whether data should be static, cached, or dynamic, or when addressing stale data and cache invalidation. For general Next.js performance, adversarial-performance may also apply.
+---
+
+# Cache Components (Next.js 16+)
+
+> **Note:** Cache Components are available in Next.js canary. Verify `cacheComponents` is supported in your target version before applying this guidance.
+
+Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.
+
+## Enable Cache Components
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+}
+
+export default nextConfig
+```
+
+This replaces the old `experimental.ppr` flag.
+
+---
+
+## Three Content Types
+
+With Cache Components enabled, content falls into three categories:
+
+### 1. Static (Auto-Prerendered)
+
+Synchronous code, imports, pure computations - prerendered at build time:
+
+```tsx
+export default function Page() {
+  return (
+    <header>
+      <h1>Our Blog</h1> {/* Static - instant */}
+      <nav>...</nav>
+    </header>
+  )
+}
+```
+
+### 2. Cached (`use cache`)
+
+Async data that doesn't need fresh fetches every request:
+
+```tsx
+async function BlogPosts() {
+  'use cache'
+  cacheLife('hours')
+
+  const posts = await db.posts.findMany()
+  return <PostList posts={posts} />
+}
+```
+
+### 3. Dynamic (Suspense)
+
+Runtime data that must be fresh - wrap in Suspense:
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <>
+      <BlogPosts /> {/* Cached */}
+      <Suspense fallback={<p>Loading...</p>}>
+        <UserPreferences /> {/* Dynamic - streams in */}
+      </Suspense>
+    </>
+  )
+}
+
+async function UserPreferences() {
+  const theme = (await cookies()).get('theme')?.value
+  return <p>Theme: {theme}</p>
+}
+```
+
+---
+
+## Selection Matrix: Static vs Cached vs Dynamic
+
+When designing a component, use this matrix to determine the correct caching strategy:
+
+| Data Type                    | Frequency of Change     | Strategy    | Implementation               |
+| ---------------------------- | ----------------------- | ----------- | ---------------------------- |
+| Marketing copy, Layouts, Nav | Build-time or rarely    | **Static**  | Default Server Component     |
+| Blog posts, Product catalog  | Periodic / CMS-driven   | **Cached**  | `'use cache'` + `cacheLife`  |
+| User profile, Shopping cart  | Per-user / Real-time    | **Dynamic** | Suspense + `await cookies()` |
+| Admin dashboard, Analytics   | High-frequency / Secure | **Dynamic** | Suspense + `await headers()` |
+
+---
+
+## `use cache` Directive
+
+### File Level
+
+```tsx
+'use cache'
+
+export default async function Page() {
+  // Entire page is cached
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Component Level
+
+```tsx
+export async function CachedComponent() {
+  'use cache'
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Function Level
+
+```tsx
+export async function getData() {
+  'use cache'
+  return db.query('SELECT * FROM posts')
+}
+```
+
+---
+
+## Cache Profiles
+
+### Built-in Profiles
+
+```tsx
+'use cache' // Default: 5m stale, 15m revalidate
+```
+
+```tsx
+'use cache: remote' // Platform-provided cache (Redis, KV)
+```
+
+```tsx
+'use cache: private' // For compliance, allows runtime APIs
+```
+
+### `cacheLife()` - Custom Lifetime
+
+```tsx
+import { cacheLife } from 'next/cache'
+
+async function getData() {
+  'use cache'
+  cacheLife('hours') // Built-in profile
+  return fetch('/api/data')
+}
+```
+
+Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
+
+### Inline Configuration
+
+```tsx
+async function getData() {
+  'use cache'
+  cacheLife({
+    stale: 3600, // 1 hour - serve stale while revalidating
+    revalidate: 7200, // 2 hours - background revalidation interval
+    expire: 86400, // 1 day - hard expiration
+  })
+  return fetch('/api/data')
+}
+```
+
+---
+
+## Cache Invalidation
+
+### `cacheTag()` - Tag Cached Content
+
+```tsx
+import { cacheTag } from 'next/cache'
+
+async function getProducts() {
+  'use cache'
+  cacheTag('products')
+  return db.products.findMany()
+}
+
+async function getProduct(id: string) {
+  'use cache'
+  cacheTag('products', `product-${id}`)
+  return db.products.findUnique({ where: { id } })
+}
+```
+
+### `updateTag()` - Immediate Invalidation
+
+Use when you need the cache refreshed within the same request:
+
+```tsx
+'use server'
+
+import { updateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+  await db.products.update({ where: { id }, data })
+  updateTag(`product-${id}`) // Immediate - same request sees fresh data
+}
+```
+
+### `revalidateTag()` - Background Revalidation
+
+Use for stale-while-revalidate behavior:
+
+```tsx
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost(data: FormData) {
+  await db.posts.create({ data })
+  revalidateTag('posts') // Background - next request sees fresh data
+}
+```
+
+---
+
+## Runtime Data Constraint
+
+**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.
+
+### Solution: Pass as Arguments
+
+```tsx
+// Wrong - runtime API inside use cache
+async function CachedProfile() {
+  'use cache'
+  const session = (await cookies()).get('session')?.value // Error!
+  return <div>{session}</div>
+}
+
+// Correct - extract outside, pass as argument
+async function ProfilePage() {
+  const session = (await cookies()).get('session')?.value
+  return <CachedProfile sessionId={session} />
+}
+
+async function CachedProfile({ sessionId }: { sessionId: string }) {
+  'use cache'
+  // sessionId becomes part of cache key automatically
+  const data = await fetchUserData(sessionId)
+  return <div>{data.name}</div>
+}
+```
+
+### Exception: `use cache: private`
+
+For compliance requirements when you can't refactor:
+
+```tsx
+async function getData() {
+  'use cache: private'
+  const session = (await cookies()).get('session')?.value // Allowed
+  return fetchData(session)
+}
+```
+
+---
+
+## Caching Security & Auth Boundaries
+
+> **CRITICAL FAILURE MODE:** Caching user-specific or authorization-bound data globally will leak PII (Personally Identifiable Information) across different users' sessions.
+
+**Rules for Auth Boundaries:**
+
+1. **Never use standard `'use cache'` for PII:** Standard cache entries are shared globally. If a component fetches user profile data using an auth token, you MUST NOT use the standard global `'use cache'`.
+2. **Explicitly include user identities in cache keys:** If you must cache per-user data, extract the user ID in a dynamic context and pass it as an argument so it becomes part of the automatic cache key (e.g., `async function CachedProfile({ userId }) { 'use cache'; ... }`).
+3. **Use `'use cache: private'` cautiously:** This ensures data isn't shared across requests, but relies heavily on correct platform caching configuration.
+4. **Dynamic by default for Auth:** For dashboards, settings, and secure data, default to **Dynamic** (Suspense) rather than Cached.
+
+---
+
+## Cache Key Generation
+
+Cache keys are automatic based on:
+
+- **Build ID** - invalidates all caches on deploy
+- **Function ID** - hash of function location
+- **Serializable arguments** - props become part of key
+- **Closure variables** - outer scope values included
+
+```tsx
+async function Component({ userId }: { userId: string }) {
+  const getData = async (filter: string) => {
+    'use cache'
+    // Cache key = userId (closure) + filter (argument)
+    return fetch(`/api/users/${userId}?filter=${filter}`)
+  }
+  return getData('active')
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+import { Suspense } from 'react'
+import { cookies } from 'next/headers'
+import { cacheLife, cacheTag } from 'next/cache'
+
+export default function DashboardPage() {
+  return (
+    <>
+      {/* Static shell - instant from CDN */}
+      <header>
+        <h1>Dashboard</h1>
+      </header>
+      <nav>...</nav>
+
+      {/* Cached - fast, revalidates hourly */}
+      <Stats />
+
+      {/* Dynamic - streams in with fresh data */}
+      <Suspense fallback={<NotificationsSkeleton />}>
+        <Notifications />
+      </Suspense>
+    </>
+  )
+}
+
+async function Stats() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('dashboard-stats')
+
+  const stats = await db.stats.aggregate()
+  return <StatsDisplay stats={stats} />
+}
+
+async function Notifications() {
+  const userId = (await cookies()).get('userId')?.value
+  const notifications = await db.notifications.findMany({
+    where: { userId, read: false },
+  })
+  return <NotificationList items={notifications} />
+}
+```
+
+---
+
+## Migration from Previous Versions
+
+| Old Config                  | Replacement                        |
+| --------------------------- | ---------------------------------- |
+| `experimental.ppr`          | `cacheComponents: true`            |
+| `dynamic = 'force-dynamic'` | Remove (default behavior)          |
+| `dynamic = 'force-static'`  | `'use cache'` + `cacheLife('max')` |
+| `revalidate = N`            | `cacheLife({ revalidate: N })`     |
+| `unstable_cache()`          | `'use cache'` directive            |
+
+### Migrating `unstable_cache` to `use cache`
+
+`unstable_cache` has been replaced by the `use cache` directive in Next.js 16. When `cacheComponents` is enabled, convert `unstable_cache` calls to `use cache` functions:
+
+**Before (`unstable_cache`):**
+
+```tsx
+import { unstable_cache } from 'next/cache'
+
+const getCachedUser = unstable_cache(async (id) => getUser(id), ['my-app-user'], {
+  tags: ['users'],
+  revalidate: 60,
+})
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const user = await getCachedUser(id)
+  return <div>{user.name}</div>
+}
+```
+
+**After (`use cache`):**
+
+```tsx
+import { cacheLife, cacheTag } from 'next/cache'
+
+async function getCachedUser(id: string) {
+  'use cache'
+  cacheTag('users')
+  cacheLife({ revalidate: 60 })
+  return getUser(id)
+}
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const user = await getCachedUser(id)
+  return <div>{user.name}</div>
+}
+```
+
+Key differences:
+
+- **No manual cache keys** - `use cache` generates keys automatically from function arguments and closures. The `keyParts` array from `unstable_cache` is no longer needed.
+- **Tags** - Replace `options.tags` with `cacheTag()` calls inside the function.
+- **Revalidation** - Replace `options.revalidate` with `cacheLife({ revalidate: N })` or a built-in profile like `cacheLife('minutes')`.
+- **Dynamic data** - `unstable_cache` did not support `cookies()` or `headers()` inside the callback. The same restriction applies to `use cache`, but you can use `'use cache: private'` if needed.
+
+---
+
+## Limitations
+
+- **Edge runtime not supported** - requires Node.js
+- **Static export not supported** - needs server
+- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`
+
+For request-time randomness outside cache:
+
+```tsx
+import { connection } from 'next/server'
+
+async function DynamicContent() {
+  await connection() // Defer to request time
+  const id = crypto.randomUUID() // Different per request
+  return <div>{id}</div>
+}
+```
+
+Sources:
+
+- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
+- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)
+- [unstable_cache (legacy)](https://nextjs.org/docs/app/api-reference/functions/unstable_cache)

package/skills/next-upgrade/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: next-upgrade
+description: |
+  Upgrade Next.js to a specific target version using safe dependency bumps, codemods, 
+  and diff reviews. Use when you need to execute major version bumps, resolve breaking changes, 
+  "upgrading Next.js", "migrate to Next.js 15 or 16", or safely "run @next/codemod" against the repository before upgrading.
+---
+
+# Upgrade Next.js
+
+Upgrade the current project to a targeted Next.js version following official migration guides.
+
+## Instructions
+
+1. **Detect current environment**:
+   - Read `package.json` to identify the current Next.js version, React version, and package manager (`npm`, `pnpm`, `yarn`).
+   - Read the lockfile to ensure you use the correct package manager.
+
+2. **Determine target version**:
+   - Do NOT blindly use `@latest`. Always determine the explicit target version (e.g., `15.0.0`) based on user request or current LTS.
+   - For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).
+
+3. **Consult Upgrade Decision Tree**:
+   - Read [references/decision-tree.md](references/decision-tree.md) to find the correct codemods and checklists for your target version.
+
+4. **Security Gate**:
+   - You MUST request explicit user confirmation before running any codemod that modifies source files.
+
+5. **Run codemods FIRST (before installing new versions)**:
+   - Next.js codemods should often be run against the _old_ codebase before upgrading to automate breaking changes.
+   - Example: `npx @next/codemod@<target-version> <transform> <path>`
+
+6. **Pin dependencies**:
+   - Upgrade Next.js and peer dependencies to the specific target version:
+   - Example: `pnpm install next@15.0.0 react@19.0.0 react-dom@19.0.0`
+
+7. **Review Diff**:
+   - After running codemods and installing new dependencies, you MUST run `git diff` or review the changes.
+   - Do NOT commit or ship without explicit user review of the codemod changes.
+
+8. **Test the upgrade**:
+   - Run `npm run build` (or equivalent) to check for build errors.
+   - If there are errors in `next.config.js` or routing, resolve them manually.

package/skills/next-upgrade/references/decision-tree.md

@@ -0,0 +1,33 @@
+# Next.js Upgrade Decision Tree
+
+When upgrading Next.js, follow this decision tree to determine which official migration guide to read and which codemods to run.
+
+## 1. Upgrade from Next.js 14 to 15
+
+If current version is 14.x and target is 15.x:
+
+1. Fetch guide: `https://nextjs.org/docs/app/guides/upgrading/version-15`
+2. **Major Breaking Change**: Async Request APIs (params, searchParams, cookies, headers are now Promises).
+3. **Run Codemod**: `npx @next/codemod@latest next-async-request-api .`
+4. **Other Codemods**:
+   - `next-request-geo-ip` (if using geo/ip in middleware)
+   - `next-dynamic-access-named-export` (if using dynamic imports)
+5. **Config Changes**: `experimental.ppr` is now `cacheComponents` (Next 15+).
+
+## 2. Upgrade from Next.js 13 to 14
+
+If current version is 13.x and target is 14.x:
+
+1. Fetch guide: `https://nextjs.org/docs/app/guides/upgrading/version-14`
+2. **Major Breaking Change**: Node.js minimum version is 18.17.
+3. **Run Codemod**: `npx @next/codemod@latest next-Image-experimental .` (if moving from legacy Image).
+
+## 3. General Codemod Workflow
+
+For any version upgrade:
+
+1. Ensure git working directory is clean.
+2. Run the specific codemod.
+3. Review the git diff.
+4. ONLY THEN run the `npm install` / `pnpm install` step to pin the new target version.
+5. Rebuild the app and manually fix TypeScript errors.

package/skills/nodejs/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: nodejs
+description: |
+  Node.js core runtime standards. Use when working with native Node.js APIs like streams, buffers, child_process, worker_threads, filesystem, or event loop tuning. Do NOT trigger for generic 'build a server' requests unless the platform/language is explicitly specified.
+---
+
+# Node.js Core Standards
+
+This skill provides best practices for utilizing native Node.js APIs safely and efficiently.
+
+## 1. Streams and Memory Management
+
+- **Streaming Data**: Always use streams (`fs.createReadStream`, `pipeline`) when handling files or network payloads larger than a few megabytes. Never buffer entire large files into memory using `fs.readFile`.
+- **Pipeline Utility**: Always use `stream/promises.pipeline` to chain streams together. It properly handles error propagation and stream destruction to prevent memory leaks.
+
+```typescript
+import { pipeline } from 'node:stream/promises'
+import { createReadStream, createWriteStream } from 'node:fs'
+
+await pipeline(
+  createReadStream('large-file.csv'),
+  processTransformStream,
+  createWriteStream('output.csv')
+)
+```
+
+## 2. Event Loop Blocking
+
+- **Synchronous APIs**: Never use synchronous native APIs (`fs.readFileSync`, `crypto.pbkdf2Sync`) in a web server context, as they block the main event loop and freeze all other requests. Only use them during application startup or in CLI scripts.
+- **CPU Intensive Tasks**: Offload CPU-intensive work (image processing, heavy cryptography, massive JSON parsing) to `worker_threads` or external processes.
+
+## 3. Child Processes
+
+- **exec vs spawn**: Avoid `child_process.exec()` for any dynamic input, as it executes in a shell and is vulnerable to command injection. Use `child_process.spawn()` or `execFile()` which bypass the shell and pass arguments directly.
+
+```typescript
+import { spawn } from 'node:child_process'
+
+// Safe: arguments are passed as an array
+const child = spawn('ls', ['-lh', '/usr'])
+```
+
+## 4. Modern APIs
+
+- **Native Fetch**: Use the native `fetch` API (Node 18+) instead of third-party libraries like `axios` or `node-fetch` unless specific interceptor functionality is required.
+- **Prefixes**: Always use the `node:` prefix when importing core modules (e.g., `import fs from 'node:fs'`). This explicitly bypasses `node_modules` lookup and improves security.

package/skills/opentelemetry/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: opentelemetry
+description: |
+  Observability standards using OpenTelemetry. Use when instrumenting applications for distributed tracing, metrics, and structured logging. NOT for Cloudflare Workers observability (use workers-best-practices). NOT for performance optimization - use adversarial-performance or web-perf. SECURITY: Ensure sensitive PII/secrets are scrubbed before logging.
+---
+
+# OpenTelemetry (OTel)
+
+Production standards for instrumenting applications to achieve high-fidelity observability.
+
+## 1. Distributed Tracing
+
+- **Trace Context Propagation**: Always propagate the `traceparent` and `tracestate` headers across HTTP and RPC boundaries (using W3C Trace Context).
+- **Span Granularity**: Create spans for logical units of work. Avoid creating spans for every single function call (which causes overhead). Focus on:
+  - Incoming HTTP requests
+  - Database queries
+  - External API/LLM calls
+  - Background task executions
+- **Semantic Conventions**: Use standardized span attributes (e.g., `http.method`, `http.status_code`, `db.system`). Do not invent custom attribute names when standard ones exist.
+
+## 2. Span Implementation Guidelines
+
+- **Status and Errors**: explicitly set the span status to `Error` when an exception occurs, and record the exception object on the span.
+- **Payloads**: Avoid logging sensitive PII or massive payloads in span attributes. Log structural identifiers (e.g., `user.id`, `tenant.id`).
+
+```typescript
+// Example: Creating a Span in Node.js
+tracer.startActiveSpan('database.query', (span) => {
+  try {
+    span.setAttribute('db.statement', queryText)
+    const result = db.execute(queryText)
+    span.setStatus({ code: SpanStatusCode.OK })
+    return result
+  } catch (error) {
+    span.recordException(error)
+    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
+    throw error
+  } finally {
+    span.end()
+  }
+})
+```
+
+## 3. Metrics
+
+- **RED Metrics**: Focus on Rate (requests/sec), Errors (error rate), and Duration (latency distribution).
+- **Histograms over Summaries**: Use Histograms for latency measurements to allow accurate percentile aggregations across distributed instances.
+
+## 4. Exporters and Infrastructure
+
+- **OTLP Exporters**: Always export telemetry using the OpenTelemetry Protocol (OTLP) via gRPC or HTTP to an OpenTelemetry Collector, rather than exporting directly to backend vendors (Datadog, Honeycomb) from the application.
+- **Batching**: Use batch span processors (`BatchSpanProcessor`) in production to minimize performance overhead. Only use `SimpleSpanProcessor` for local debugging.
+
+## 5. Cloudflare Workers Integration
+
+- **Trace Exporters**: When running on Cloudflare Workers, standard OTLP exporters may fail due to runtime constraints. Use `@microlabs/otel-cf-workers` or specifically tailored fetch-based HTTP exporters for compatibility.
+- **Context Preservation**: Always wrap the Worker's `fetch` handler or Scheduled handler using the telemetry wrapper to ensure trace context flows correctly through the V8 isolate.
+
+## 6. Structured Logging
+
+- **Correlated Logs**: Ensure all log lines emit the current `trace_id` and `span_id`. This allows bridging between logs and traces.
+- **JSON Format**: Output logs in JSON format in production. Avoid unstructured string logging.

package/skills/package.json

@@ -1,6 +1,6 @@
 {
     "name": "neverinfamous-agent-skills",
-    "version": "1.1.2",
+    "version": "1.2.2",
     "description": "Foundational AI agent metacognitive skills and workflows for the Adamic ecosystem.",
     "type": "module",
     "main": "README.md",
@@ -10,27 +10,62 @@
     "files": [
         "bin/",
         "README.md",
-        "autonomous-dev/",
+        "adversarial-performance/",
         "adversarial-planner/",
+        "adversarial-security/",
+        "adversarial-skill-audit/",
+        "adversarial-workflow-audit/",
+        "agents-sdk/",
+        "auth-identity/",
+        "autonomous-dev/",
+        "aws/",
+        "azure/",
+        "biome/",
         "bun/",
+        "cloudflare/",
         "docker/",
+        "docs-marketer/",
+        "drizzle-orm/",
+        "durable-objects/",
+        "gcp/",
         "github-actions/",
         "github-commander/",
         "github-copilot-cli/",
+        "github-repo-setup/",
         "gitlab/",
         "golang/",
+        "graphql/",
+        "hono/",
+        "journal-optimizer/",
+        "llm-app-engineering/",
+        "monorepo/",
+        "multi-agent-orchestration/",
         "mysql/",
+        "next-best-practices/",
+        "next-cache-components/",
+        "next-upgrade/",
+        "nodejs/",
+        "opentelemetry/",
         "playwright-standard/",
         "postgres/",
         "python/",
-        "react-best-practices/",
+        "rag-pipelines/",
+        "redis/",
+        "render/",
         "rust/",
+        "sandbox-sdk/",
         "shadcn-ui/",
         "skill-builder/",
         "sqlite/",
         "tailwind-css/",
+        "trpc/",
         "typescript/",
-        "vitest-standard/"
+        "vercel-ai-sdk/",
+        "vitest-standard/",
+        "web-perf/",
+        "workers-best-practices/",
+        "wrangler/",
+        "zod/"
     ],
     "scripts": {
         "sync": "node bin/sync.js"