@mandujs/mcp 0.37.2 → 0.37.4

package/src/resources/skills/mandu-hydration/SKILL.md

@@ -10,14 +10,54 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Island Hydration
-
-Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.
-대부분의 페이지는 정적 HTML로 유지하고, 필요한 부분만 JavaScript를 로드합니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Island Hydration
+
+Island Hydration은 페이지의 일부분만 클라이언트에서 인터랙티브하게 만드는 기술입니다.
+대부분의 페이지는 정적 HTML로 유지하고, 필요한 부분만 JavaScript를 로드합니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects the hydration, island, partial, or route domain.
+
+Canonical workflow step: `plan -> apply -> verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.island.list` |
+| apply | `mandu.agent.apply`, `mandu.hydration.set`, `mandu.hydration.addClientSlot` |
+| verify | `mandu.agent.verify`, `mandu.build`, `mandu.build.status` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- `app/**/*.partial.tsx`, `app/**/*.island.tsx`, route-local client components
+- Page hydration metadata only when the plan names the route
+- Shared client utilities only after inspecting existing client boundaries
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Rendering page-level islands inline instead of using `partial().Render`
+- Forgetting route hydration metadata when a server page renders partials
+- Moving server-only imports into client bundles
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Creating interactive client components
 - Adding client-side state to pages
 - Implementing partial hydration
@@ -57,17 +97,25 @@ Reference these guidelines when:
 - `hydration-data-server` - Access server data with useServerData
 - `hydration-data-event` - Communicate between Islands with useIslandEvent
 
-## Hydration Strategies
-
-| Strategy | Description | Use Case |
-|----------|-------------|----------|
-| `none` | No JavaScript | Pure static pages |
-| `island` | Partial hydration (default) | Static + interactive mix |
-| `full` | Full hydration | SPA-style pages |
-
-## Client Hooks
-
-```typescript
+## Hydration Strategies
+
+| Strategy | Description | Use Case |
+|----------|-------------|----------|
+| `none` | No JavaScript | Pure static pages |
+| `island` | Partial hydration (default) | Static + interactive mix |
+| `full` | Full hydration | SPA-style pages |
+
+## Runtime API Constraints
+
+- `island()` / `Mandu.island()` takes one definition object: `island({ setup, render })`.
+- Do not call `island("visible", Component)`; use `wrapComponent(Component)` for a simple page-level island wrapper.
+- Islands are page-level client bundles. Do not render them as inline JSX like `<MyIsland />`.
+- For an embedded interactive region inside a server page, use `partial()`: put it in `*.partial.tsx`, export `partial({ id, component })`, and render the returned `.Render` component from the server page.
+- A server page that renders partials must opt into hydration, for example `export const hydration = { strategy: "island", priority: "visible", preload: false }`.
+
+## Client Hooks
+
+```typescript
 import {
   useServerData,
   useHydrated,

package/src/resources/skills/mandu-hydration/rules/hydration-island-setup.md

@@ -5,13 +5,60 @@ impactDescription: Proper Island structure
 tags: hydration, island, setup
 ---
 
-## Use Mandu.island() with Setup Function
-
-For complex Islands, use `Mandu.island()` API to separate state logic from rendering.
-
-**Incorrect (mixed concerns):**
-
-```tsx
+## Use Mandu.island() with Setup Function
+
+For complex Islands, use `Mandu.island()` API to separate state logic from rendering.
+`Mandu.island()` takes a single definition object. The shorthand
+`island("visible", Component)` is not a supported Mandu runtime API.
+
+Islands are page-level client bundles. They are discovered and rendered by
+the framework wrapper, not embedded directly as inline JSX. Use `partial()`
+when a server page needs an inline interactive region.
+
+```tsx
+// Simple page-level island wrapper
+"use client";
+
+import { wrapComponent } from "@mandujs/core/client";
+
+function Counter() {
+  return <button>Count</button>;
+}
+
+export default wrapComponent(Counter);
+```
+
+```tsx
+// Inline client region inside a server-rendered page
+// app/Counter.partial.tsx
+import { partial } from "@mandujs/core/client";
+import { Counter } from "./counter.client";
+
+export default partial({
+  id: "Counter",
+  component: Counter,
+  priority: "visible",
+});
+```
+
+```tsx
+// app/page.tsx
+import CounterPartial from "./Counter.partial";
+
+export const hydration = {
+  strategy: "island",
+  priority: "visible",
+  preload: false,
+};
+
+export default function Page() {
+  return <CounterPartial.Render initial={0} />;
+}
+```
+
+**Incorrect (mixed concerns):**
+
+```tsx
 "use client";
 
 export default function TodoList({ initialTodos }) {

package/src/resources/skills/mandu-hydration/rules/hydration-priority-visible.md

@@ -18,43 +18,66 @@ Set hydration priority based on when the component needs to be interactive.
 | `idle` | Browser idle | Non-critical features (analytics widgets) |
 | `interaction` | User action | Click-to-activate components |
 
-## Examples
-
-### Immediate: Always-visible interactions
-
-```tsx
-// Header with navigation - needs to work immediately
-<Island priority="immediate">
-  <HeaderNav />
-</Island>
-```
-
-### Visible: Below-fold content (default)
-
-```tsx
-// Comments section - load when scrolled into view
-<Island priority="visible">
-  <CommentsSection postId={postId} />
-</Island>
-```
-
-### Idle: Background features
-
-```tsx
-// Chat widget - can wait until browser is idle
-<Island priority="idle">
-  <ChatWidget />
-</Island>
-```
-
-### Interaction: On-demand activation
-
-```tsx
-// Video player - only hydrate when user clicks play
-<Island priority="interaction">
-  <VideoPlayer videoId={videoId} />
-</Island>
-```
+## Examples
+
+Inline client regions live in `*.partial.tsx` files and use
+`partial({ id, component, priority })`, then render the returned `.Render`
+component from the server page. The page must export a non-`none` hydration
+config.
+
+### Immediate: Always-visible interactions
+
+```tsx
+// Header with navigation - needs to work immediately
+import { partial } from "@mandujs/core/client";
+
+const HeaderNavPartial = partial({
+  id: "HeaderNav",
+  component: HeaderNav,
+  priority: "immediate",
+});
+
+<HeaderNavPartial.Render />
+```
+
+### Visible: Below-fold content (default)
+
+```tsx
+// Comments section - load when scrolled into view
+const CommentsPartial = partial({
+  id: "Comments",
+  component: CommentsSection,
+  priority: "visible",
+});
+
+<CommentsPartial.Render postId={postId} />
+```
+
+### Idle: Background features
+
+```tsx
+// Chat widget - can wait until browser is idle
+const ChatPartial = partial({
+  id: "Chat",
+  component: ChatWidget,
+  priority: "idle",
+});
+
+<ChatPartial.Render />
+```
+
+### Interaction: On-demand activation
+
+```tsx
+// Video player - only hydrate when user clicks play
+const VideoPartial = partial({
+  id: "Video",
+  component: VideoPlayer,
+  priority: "interaction",
+});
+
+<VideoPartial.Render videoId={videoId} />
+```
 
 ## Performance Impact
 

package/src/resources/skills/mandu-performance/SKILL.md

@@ -10,13 +10,53 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Performance
-
-Mandu 애플리케이션의 성능 최적화 가이드. 워터폴 제거, 번들 최적화, 캐싱 패턴, Bun 런타임 활용법을 다룹니다. Vercel의 React Best Practices를 Mandu 컨텍스트로 변환하여 적용합니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Performance
+
+Mandu 애플리케이션의 성능 최적화 가이드. 워터폴 제거, 번들 최적화, 캐싱 패턴, Bun 런타임 활용법을 다룹니다. Vercel의 React Best Practices를 Mandu 컨텍스트로 변환하여 적용합니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects performance, hydration, route, API, or runtime domains.
+
+Canonical workflow step: `plan -> verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.agent.context` |
+| apply | `mandu.agent.apply` |
+| verify | `mandu.agent.verify`, `mandu.build`, `mandu.run.tests` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- Route, slot, island, or cache code named in the plan
+- Import boundaries that reduce bundle/runtime cost
+- Benchmark/test files scoped to the performance claim
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Optimizing without a measurable route, bundle, or runtime target
+- Moving server-only code into client islands for convenience
+- Skipping typecheck or targeted tests after cache/import rewrites
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Optimizing slot handler response times
 - Reducing Island component bundle size
 - Implementing caching strategies

package/src/resources/skills/mandu-security/SKILL.md

@@ -10,13 +10,53 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Security
-
-Mandu 애플리케이션의 보안 모범 사례 가이드. slot guard를 통한 인증/인가, 입력 검증, CSRF/XSS 방어, 환경 변수 관리를 다룹니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Security
+
+Mandu 애플리케이션의 보안 모범 사례 가이드. slot guard를 통한 인증/인가, 입력 검증, CSRF/XSS 방어, 환경 변수 관리를 다룹니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects security, auth, slot, API, or runtime domains.
+
+Canonical workflow step: `plan -> verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.docs.search` |
+| apply | `mandu.agent.apply` |
+| verify | `mandu.agent.verify`, `mandu.guard.check`, `mandu.contract.validate` |
+| repair | `mandu.agent.repair`, `mandu.guard.explain` |
+
+Allowed file edits:
+
+- Auth/session slot logic named in the plan
+- Server-only validation and security header configuration
+- Environment templates, never secret values
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Exposing secrets through client bundles or sync artifacts
+- Changing auth behavior without route/API/slot verification
+- Treating guard findings as policy problems before checking source boundaries
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Implementing authentication in slots
 - Adding authorization guards
 - Validating user input

package/src/resources/skills/mandu-slot/SKILL.md

@@ -11,14 +11,54 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Slot
-
-Slot은 비즈니스 로직을 작성하는 파일입니다. `Mandu.filling()` API를 사용하여
-API 핸들러, 인증 가드, 라이프사이클 훅을 구현합니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Slot
+
+Slot은 비즈니스 로직을 작성하는 파일입니다. `Mandu.filling()` API를 사용하여
+API 핸들러, 인증 가드, 라이프사이클 훅을 구현합니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects the slot, API, or security domain.
+
+Canonical workflow step: `plan -> apply -> verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.slot.read`, `mandu.slot.constraints` |
+| apply | `mandu.agent.apply`, `mandu.generate` |
+| verify | `mandu.agent.verify`, `mandu.slot.validate`, `mandu.contract.validate` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- `spec/slots/**/*.slot.ts`
+- Route handlers that bind to the planned slot
+- Contract files only when the plan includes contract work
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Creating slot logic without checking `mandu.slot.constraints`
+- Mixing auth/security changes into slot edits without security verification
+- Returning untyped responses that drift from the linked contract
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Creating new API endpoints with business logic
 - Implementing authentication or authorization
 - Adding request/response lifecycle hooks

package/src/resources/skills/mandu-styling/SKILL.md

@@ -11,13 +11,53 @@ globs:
   - "app/globals.css"
 ---
 
-# Mandu Styling Skill
-
-Mandu Island 아키텍처에 최적화된 Tailwind CSS v4 스타일링 가이드입니다.
-
-## 핵심 원칙
-
-1. **Zero-Runtime**: 빌드 타임 CSS 생성 (SSR 호환)
+# Mandu Styling Skill
+
+Mandu Island 아키텍처에 최적화된 Tailwind CSS v4 스타일링 가이드입니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects styling, design, UI, hydration, or component domains.
+
+Canonical workflow step: `plan -> apply -> verify`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan`, `mandu.design.get` |
+| apply | `mandu.agent.apply`, `mandu.design.patch` |
+| verify | `mandu.agent.verify`, `mandu.design.check`, `mandu.lint` |
+| repair | `mandu.agent.repair` |
+
+Allowed file edits:
+
+- CSS files named in the plan, especially `app/globals.css`
+- Component className changes scoped to the target UI
+- Theme tokens only after inspecting the project's design source
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Installing or changing styling stacks before checking the existing project style
+- Editing broad theme tokens for a local component issue
+- Skipping design/lint verification after Tailwind v4 syntax changes
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## 핵심 원칙
+
+1. **Zero-Runtime**: 빌드 타임 CSS 생성 (SSR 호환)
 2. **CSS-First**: JavaScript 설정 대신 CSS에서 테마 정의
 3. **Island 격리**: 컴포넌트 간 스타일 충돌 방지
 4. **Auto Integration**: Mandu가 Tailwind v4 자동 감지 및 빌드
@@ -29,9 +69,11 @@ Primary:    Tailwind CSS v4 + clsx/tailwind-merge
 Alternative: CSS Modules (최소 의존성)
 ```
 
-## 빠른 시작
-
-### 1. 설치
+## Setup Examples
+
+Use these examples only after `mandu.agent.plan` selects styling setup or migration.
+
+### 1. 설치
 
 ```bash
 bun add -d tailwindcss@^4.1 @tailwindcss/cli@^4.1

package/src/resources/skills/mandu-testing/SKILL.md

@@ -10,13 +10,52 @@ metadata:
   version: "1.0.0"
 ---
 
-# Mandu Testing
-
-Mandu 애플리케이션의 테스트 패턴 가이드. Bun test를 활용한 단위 테스트, slot 테스트, Island 컴포넌트 테스트, Playwright E2E 테스트를 다룹니다.
-
-## When to Apply
-
-Reference these guidelines when:
+# Mandu Testing
+
+Mandu 애플리케이션의 테스트 패턴 가이드. Bun test를 활용한 단위 테스트, slot 테스트, Island 컴포넌트 테스트, Playwright E2E 테스트를 다룹니다.
+
+## Agent Workflow Contract
+
+This skill is a Domain addendum. It must not replace `mandu-agent-workflow`.
+Use it only after `mandu.agent.plan` selects testing or `mandu.agent.verify` asks for targeted test coverage.
+
+Canonical workflow step: `verify -> repair`.
+
+Preferred MCP tools:
+
+| Step | Tools |
+|------|-------|
+| plan | `mandu.agent.plan` |
+| verify | `mandu.agent.verify`, `mandu.run.tests`, `mandu.ate.generate`, `mandu.ate.run` |
+| repair | `mandu.agent.repair`, `mandu.ate.heal` |
+
+Allowed file edits:
+
+- Co-located `*.test.ts` / `*.test.tsx` files
+- `tests/e2e/**/*.spec.ts`
+- Test fixtures and mocks scoped to the planned domain
+
+Verification command:
+
+```bash
+mandu agent verify --changed --json --write
+```
+
+Common failures:
+
+- Running broad watch-mode tests as an agent default
+- Adding tests that bypass the route/slot/contract path under change
+- Applying ATE healing before reading the verify report
+
+Repair path:
+
+```bash
+mandu agent repair --from .mandu/agent-verify.json --json
+```
+
+## When to Apply
+
+Reference these guidelines when:
 - Writing unit tests for slots
 - Testing Island components
 - Setting up E2E tests with Playwright
@@ -57,21 +96,15 @@ Reference these guidelines when:
 - `test-mock-fetch` - Mock fetch requests
 - `test-mock-database` - Mock database operations
 
-## Bun Test Quick Start
-
-```bash
-# Run all tests
-bun test
-
-# Run specific test file
-bun test src/slots/user.test.ts
-
-# Watch mode
-bun test --watch
-
-# Coverage
-bun test --coverage
-```
+## Low-Level Test Commands
+
+Use these only after `agent plan` or `agent verify` identifies the target:
+
+```bash
+mandu agent verify --changed --json --write
+bun test src/slots/user.test.ts
+bun test --coverage
+```
 
 ## Test File Convention