@bcelep/capint 0.4.2 → 0.6.5

package/skills/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/skills/vercel-react-best-practices/rules/server-dedup-props.md

@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/skills/vercel-react-best-practices/rules/server-hoist-static-io.md

@@ -0,0 +1,142 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect: reads font file on every request**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+  
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Alternative: synchronous file reads with Node.js fs**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**General Node.js example: loading config or templates**
+
+```typescript
+// Incorrect: reads config on every call
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+  
+  return render(template, data, config)
+}
+
+// Correct: loads once at module level
+const configPromise = fs.readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise
+  ])
+  
+  return render(template, data, config)
+}
+```
+
+**When to use this pattern:**
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+**When NOT to use this pattern:**
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** Module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+**In traditional serverless:** Each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

package/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/skills/verdent-image-cli/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: verdent-image-cli
+description: |
+  Generate and edit images via the `verdent-image` tool. Use this skill
+  whenever the user asks for image generation, image editing based on
+  reference images, posters, illustrations, covers, UI mocks, social
+  creatives, or style variations. The CLI returns a JSON payload; bash
+  automatically decodes the base64 result, writes it to disk, and returns
+  a short path-based text result to the model.
+metadata:
+  version: '1.0.3'
+origin: verdent
+prismx_bundle: verdent
+prismx_imported_at: 2026-05-27
+---
+
+# Verdent Image CLI
+
+Single skill for generating and editing images through the `verdent-image` tool. The bash layer automatically handles base64 decoding and file saving; you only need to craft a good prompt and pass reference image paths when editing.
+
+## When to Use
+
+Invoke this skill whenever the user wants to:
+
+- generate a brand-new image from a description
+- edit an existing image with one or more reference images
+- produce posters, illustrations, hero images, covers, social creatives, UI mock visuals, or stylistic variants
+- regenerate an image with changed style, composition, subject, or palette
+
+Do **not** use this skill to analyze or describe an existing image. Use a vision-capable read path instead.
+
+## CLI Shape
+
+```bash
+verdent-image <generate | edit> --model <model> --prompt "<prompt>" [--size <WxH>] [--n <count>] [--image <path> ...] [--mask <path>]
+```
+
+Two subcommands:
+
+- `verdent-image generate` — create a new image from the prompt alone
+- `verdent-image edit` — edit/transform based on reference images
+
+`--model` is **always required**. The default model to use is `gpt-image-2` unless the user explicitly asks for a different one.
+
+### Generate image
+
+```bash
+verdent-image generate --model gpt-image-2 --prompt "<agent-crafted prompt>" --size 1024x1024 --n 1
+```
+
+### Edit image
+
+```bash
+verdent-image edit --model gpt-image-2 --prompt "<agent-crafted prompt>" --image path1 --image path2 --image path3
+```
+
+Flags:
+
+| Flag | Required | Purpose |
+|------|----------|---------|
+| `--model` | **yes** | Model id. Default to `gpt-image-2` unless the user specifies another one. |
+| `--prompt` | **yes** | Agent-authored prompt string. |
+| `--size` | optional | Image size, e.g. `1024x1024`, `1792x1024`. Default `1024x1024`. |
+| `--n` | optional | Number of images to produce. Default `1`. |
+| `--image` | **required for `edit`** | Absolute path to a reference image. Repeat the flag once per image (the CLI accepts multiple `--image` flags). |
+| `--mask` | optional for `edit` | Absolute path to a mask image. When provided, edits are constrained to the masked region. Omit it for a normal image edit. |
+
+## Prompt Authoring Rules
+
+- **Do not parrot the user verbatim.** Translate intent into an image prompt: subject, composition, style, color, lighting, framing, camera or medium, quality cues when relevant.
+- **Do not over-invent.** Preserve every concrete requirement the user gave (subject, scene, palette, aspect ratio, characters, text overlays, product details). Do not add subjects, brands, or style shifts the user never asked for.
+- Keep the prompt focused and sentence-like. No bullet lists inside `--prompt`.
+- Quote the prompt with double quotes and escape internal quotes if needed.
+- Write the prompt in English by default. Match another language only if the user's creative explicitly requires it (for example, on-image text in that language).
+
+## Reference Images Rules
+
+Only applies to `verdent-image edit`:
+
+- `--image` takes an **image file path**, not a URL and not base64.
+- Pass one `--image` flag per reference image. The flag is repeatable. Do **not** pass a comma-separated list to a single `--image`.
+  - Correct: `--image /a/b.png --image /a/c.jpg`
+  - Wrong:   `--image /a/b.png,/a/c.jpg`
+- Prefer absolute paths. If you only have a relative path, resolve it before calling.
+- When the user dragged in or `@mentioned` images, use those exact paths as provided. They are surfaced by the preprocessor alongside the image content. Do not invent, rename, or summarize them.
+- Do not embed base64 in `--image`. Bash only accepts paths here.
+- `--mask` is optional and takes an **image file path**. Use it only when the user provides or asks to use a mask image.
+- A mask tells `gpt-image-2` which region to modify. Areas outside the mask should be preserved as much as possible.
+- Do not pass `--mask` unless you have an actual mask image path. Normal edits should use `--image` without `--mask`.
+
+## Output Handling
+
+`verdent-image` writes a JSON string to stdout. The raw CLI payload looks like:
+
+```json
+{
+  "images": [
+    {
+      "image_media_type": "image/png",
+      "size": "1024x1024",
+      "quality": "high",
+      "result": "<very large base64 string>"
+    }
+  ]
+}
+```
+
+You do **not** parse this raw JSON yourself and you do **not** save the image yourself. Bash intercepts the command and does all of the following automatically:
+
+1. Parse the CLI JSON.
+2. Decode each `result` from base64.
+3. Derive the file extension from `image_media_type`.
+4. Write each image to the appropriate directory (see below).
+5. Replace the tool result you see with a **fixed JSON schema** describing the saved files:
+
+   ```json
+   {
+     "status": "ok",
+     "operation": "generate",
+     "count": 1,
+     "images": [
+       {
+         "path": "/absolute/path/to/generate_20260101_120000_ab12cd34.png",
+         "image_media_type": "image/png",
+         "size": "1024x1024",
+         "quality": "high"
+       }
+     ]
+   }
+   ```
+
+   - `status` is `"ok"` on success or `"empty"` if no image came back.
+   - `operation` is `"generate"` or `"edit"`.
+   - `count` is the number of saved images (matches `len(images)`).
+   - Each `images[i].path` is the absolute path on disk.
+
+Treat this JSON as the ground truth. Parse `images[*].path` and tell the user the image was generated or edited and report the path(s). Do not attempt to dump base64 back to the user.
+
+### Save directories
+
+| Context | Directory |
+|---------|-----------|
+| Default (worker or global usage) | `~/.verdent/generate_images` |
+| When invoked inside the Verdent manager or base workspace | `~/.verdent/workspace/base/generated_images` |
+
+Bash chooses the directory automatically based on the current skill context. You do not need to specify it.
+
+## End-to-End Patterns
+
+### Pattern 1. Simple generation
+
+User asks for a cyberpunk cat illustration.
+
+```bash
+verdent-image generate --model gpt-image-2 --prompt "A cyberpunk cat sitting on a rain-soaked rooftop at night, neon signs reflecting in puddles, cinematic lighting, shallow depth of field, high detail" --size 1024x1024 --n 1
+```
+
+Then tell the user the image was generated and show the saved path from the tool result.
+
+### Pattern 2. Photorealistic product shot
+
+User wants a glossy red apple product photo.
+
+```bash
+verdent-image generate --model gpt-image-2 --prompt "A giant gleaming red apple, hyper-realistic, dewdrops on glossy skin, vibrant saturated red with subtle yellow highlights, fresh green leaf still attached to the stem, dramatic studio lighting on pure white background, ultra detailed macro photography, 8k quality" --size 1024x1024 --n 1
+```
+
+### Pattern 3. Edit with a single reference
+
+User dragged `cover.png` and asked to recolor it with warm tones and add subtle grain.
+
+```bash
+verdent-image edit --model gpt-image-2 --prompt "Recolor this cover with warm tones (amber, soft red, gold), add subtle film grain, preserve original composition and subjects" --image /Users/me/cover.png
+```
+
+### Pattern 4. Edit with multiple references
+
+User `@mentioned` `ref1.jpg` and `ref2.jpg` and asked to keep the subject of the first image while using the color palette of the second.
+
+```bash
+verdent-image edit --model gpt-image-2 --prompt "Create a composite that keeps the subject and composition of the first image while adopting the color palette and mood of the second image" --image /path/to/ref1.jpg --image /path/to/ref2.jpg
+```
+
+### Pattern 5. Edit with a mask
+
+User provided an indoor lounge photo and a mask image, then asked to add a pink flamingo only inside the masked pool area while preserving the original architecture.
+
+```bash
+verdent-image edit --model gpt-image-2 --prompt "A sunlit indoor lounge area with a pool containing a pink flamingo floating gracefully on the water surface, warm natural lighting, maintaining original architecture" --image /path/to/indoor-lounge.jpg --mask /path/to/pool-mask.png
+```
+
+## Do and Don't
+
+**Do**
+
+- Always include `--model`. Use `gpt-image-2` unless the user specifies another one.
+- Craft a faithful, tight image prompt from the user's intent.
+- Pass drag or `@`-mentioned image paths verbatim into `--image` (one `--image` per path).
+- Use `--mask` only when the user provides a mask image path or explicitly asks for masked-region editing.
+- Trust the bash short text result and forward the saved path to the user.
+
+**Don't**
+
+- Don't omit `--model`.
+- Don't use the old flag form `--generate` / `--edit`. They are subcommands now: `verdent-image generate` / `verdent-image edit`.
+- Don't decode or re-save the base64 yourself.
+- Don't dump JSON or base64 back to the user.
+- Don't spawn a subagent to call this CLI. Call it directly from bash.
+- Don't invent unsupported flags. Only `--model`, `--prompt`, `--size`, `--n`, `--image`, and `--mask` are valid. In particular, **`--reference_images` does not exist** — use repeated `--image` flags instead.
+- Don't copy `image_media_type`, `size`, or `quality` verbatim from an unrelated example. They come from the CLI response for the current call.
+
+## Troubleshooting
+
+- **Bash returned JSON text instead of the short saved-path message.** The command string was probably wrapped in a way that hid the `verdent-image generate` / `verdent-image edit` token (for example, inside a subshell with an alias). Call the top-level command directly.
+- **`edit` appears to fail with exit code 1 and no error message, and no saved path is returned.** You probably used `--reference_images`. That flag does not exist; the CLI rejects it as an unknown argument without a friendly error. Switch to one or more `--image <path>` flags and retry.
+- **Error about reference path not found.** Verify the path exists with a lightweight check (for example `ls <path>`) before retrying. Do not retry with the same path.
+- **Very long edits.** The CLI call may take tens of seconds. Bash already uses an extended timeout for this command. Do not retry on the first wait.
+- **Error about unknown model.** Fall back to `gpt-image-2`.

package/skills/verdent-image-cli/agents/verdent.yaml

@@ -0,0 +1,11 @@
+category: Media
+min_client_version: '2.2.0'
+interface:
+  display_name: 'Verdent Image Cli'
+  short_description: 'Generate and edit images via the verdent_image_cli tool.'
+  default_prompt: 'Generate an image of a scene I describe, or edit this image with my instructions.'
+  icon_dark: './assets/icon-dark.png'
+  icon_light: './assets/icon-light.png'
+  builtin: true
+  hidden: false
+  undeletable: true