@cubis/foundry 0.3.63 → 0.3.64

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/golang-pro/SKILL.md

@@ -18,6 +18,12 @@ metadata:
 - Designing concurrency with goroutines/channels/context.
 - Optimizing latency, allocations, and reliability.
 
+## When not to use
+
+- Database-only tuning with no Go code change.
+- Browser/frontend tasks outside Go-backed services or tooling.
+- Small shell automation already well-covered by existing scripts.
+
 ## Core workflow
 
 1. Define package boundaries and interfaces.
@@ -41,6 +47,18 @@ metadata:
 - Use generics where they simplify, not where they obscure.
 - Benchmark hot paths (`testing.B`, `pprof`) before tuning.
 
+## Debugging and observability
+
+- Thread request IDs and trace context through handlers and workers.
+- Use structured logs that make cancellation, retries, and deadlines visible.
+- Reproduce concurrency issues with race tests and deterministic fixtures first.
+
+## Performance and reliability
+
+- Prefer bounded worker pools over unbounded goroutine fan-out.
+- Make timeout/cancellation behavior explicit at every network boundary.
+- Profile CPU, heap, and block contention before low-level rewrites.
+
 ## Avoid
 
 - Fire-and-forget goroutines without cancellation path.
@@ -49,8 +67,10 @@ metadata:
 
 ## Reference files
 
-- `references/concurrency.md`
-- `references/generics.md`
-- `references/interfaces.md`
-- `references/testing.md`
-- `references/project-structure.md`
+| File | Load when |
+| --- | --- |
+| `references/concurrency.md` | Concurrency ownership, channels, mutexes, or cancellation safety need detail. |
+| `references/generics.md` | Generics tradeoffs or reusable type-safe helpers are in scope. |
+| `references/interfaces.md` | Interface boundaries and package seams need review. |
+| `references/testing.md` | Test strategy, race checks, or benchmark setup is needed. |
+| `references/project-structure.md` | Package layout or service/module decomposition needs guidance. |

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/gorouter-restoration/SKILL.md

@@ -114,10 +114,14 @@ MaterialApp.router(
 
 ## Steering Files
 
-- `guard_patterns.md` - Guard decision rules and anti-loop checks
-- `tab_preservation.md` - StatefulShellRoute and restoration patterns
+| File | Load when |
+| --- | --- |
+| `references/guard_patterns.md` | Designing guard logic, redirect rules, or anti-loop checks. |
+| `references/tab_preservation.md` | Preserving `StatefulShellRoute` branches and restoration state. |
 
 ## Templates
 
-- `guard_redirect` - Guard redirect function skeleton
-- `stateful_shell_skeleton` - Tab shell starter
+| File | Load when |
+| --- | --- |
+| `templates/guard_redirect.md` | Starting a redirect/guard function skeleton. |
+| `templates/stateful_shell_skeleton.md` | Starting a shell/tab restoration scaffold. |

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/java-pro/SKILL.md

@@ -18,6 +18,12 @@ metadata:
 - Designing JVM architecture for high-throughput systems.
 - Improving reliability, observability, and maintainability.
 
+## When not to use
+
+- Frontend-only tasks with no JVM component.
+- Pure schema/index work better handled as database design or optimization.
+- Low-level native systems work where Rust/Go is the actual project stack.
+
 ## Core workflow
 
 1. Clarify runtime target and deployment constraints.
@@ -33,6 +39,24 @@ metadata:
 - Use structured logging and trace propagation.
 - Enforce dependency and API compatibility checks in CI.
 
+## Debugging and observability
+
+- Capture request/job correlation IDs in logs and traces.
+- Keep exception handling consistent between transport, service, and persistence layers.
+- Reproduce performance or memory issues with focused benchmarks/profilers before redesigning.
+
+## Performance and reliability
+
+- Prefer explicit timeouts, bulkheads, and retry budgets at I/O boundaries.
+- Keep thread/virtual-thread usage bounded and observable.
+- Separate transport DTOs from domain and persistence models to reduce cascade failures.
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/operational-baseline.md` | You need current Java service guardrails for logging, testing, dependency hygiene, and runtime operations. |
+
 ## Avoid
 
 - Monolithic service classes with mixed responsibilities.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/java-pro/references/operational-baseline.md

@@ -0,0 +1,9 @@
+## Operational baseline
+
+Load when: JVM service reliability, logging, dependency hygiene, or runtime guardrails need explicit guidance.
+
+- Use structured logging and trace propagation at service boundaries.
+- Keep timeout/retry budgets explicit for external I/O.
+- Separate API contracts from persistence entities.
+- Prefer focused benchmark/profiler evidence before redesigning hot paths.
+- Validate with tests and compatibility checks in CI.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/javascript-pro/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "javascript-pro"
-description: "Use for modern JavaScript architecture and implementation across browser, Node, and edge runtimes with ES2025+ practices."
+description: "Use for modern JavaScript architecture and implementation across browser, Node, and edge runtimes with runtime-aware production practices."
 license: MIT
 metadata:
   version: "2.0.0"
   domain: "language"
   role: "specialist"
   stack: "javascript"
-  baseline: "ES2025+"
+  baseline: "Runtime-policy baseline (Node/browser/edge)"
 ---
 
 # JavaScript Pro
@@ -18,6 +18,12 @@ metadata:
 - Refactoring legacy JS toward modern modules and async flows.
 - Improving performance and reliability in browser/Node runtimes.
 
+## When not to use
+
+- Type-driven architecture work where TypeScript is the actual project language.
+- Database-only investigation with no JavaScript runtime behavior involved.
+- One-off shell automation that should remain shell-native.
+
 ## Core workflow
 
 1. Confirm runtime constraints (browser targets, Node/edge version).
@@ -40,6 +46,18 @@ metadata:
 - Use streams for large payloads to avoid memory spikes.
 - Use feature detection, not UA sniffing, in browser code.
 
+## Debugging and observability
+
+- Reproduce runtime-specific failures in the exact target environment: browser, Node, or edge.
+- Surface async failures with structured errors and explicit logging context.
+- Use performance tooling before redesigning hot paths or caching strategy.
+
+## Performance and reliability
+
+- Keep bundle/runtime boundaries explicit so shared code does not assume unavailable APIs.
+- Bound parallelism and cancellation for network-heavy flows.
+- Prefer streaming, chunking, and incremental parsing for large payloads.
+
 ## Avoid
 
 - Silent promise rejections.
@@ -48,8 +66,10 @@ metadata:
 
 ## Reference files
 
-- `references/modern-syntax.md`
-- `references/async-patterns.md`
-- `references/modules.md`
-- `references/browser-apis.md`
-- `references/node-essentials.md`
+| File | Load when |
+| --- | --- |
+| `references/modern-syntax.md` | Choosing modern syntax/features for current runtime targets. |
+| `references/async-patterns.md` | Cancellation, retries, concurrency, or promise orchestration needs detail. |
+| `references/modules.md` | ESM/CJS/module-boundary tradeoffs are in scope. |
+| `references/browser-apis.md` | Browser-specific APIs, capability checks, or UX/runtime constraints matter. |
+| `references/node-essentials.md` | Node runtime behavior, streams, files, or process concerns matter. |

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/kotlin-pro/SKILL.md

@@ -18,6 +18,12 @@ metadata:
 - Designing coroutine-based async flows.
 - Improving null-safety and domain model clarity.
 
+## When not to use
+
+- Frontend-only work with no Kotlin/JVM/Android/shared module in scope.
+- Database-only tuning without Kotlin code changes.
+- Tiny scripts that should stay in existing project tooling.
+
 ## Core workflow
 
 1. Establish target platform (JVM/Android/multiplatform).
@@ -33,6 +39,24 @@ metadata:
 - Keep serialization and transport models separate from domain.
 - Use dependency boundaries that support modular testing.
 
+## Debugging and observability
+
+- Keep coroutine context, dispatcher use, and cancellation visible in logs/traces.
+- Reproduce lifecycle-related failures with focused tests before broader rewrites.
+- Prefer deterministic `Flow`/coroutine tests for race-prone logic.
+
+## Performance and reliability
+
+- Bound coroutine fan-out and avoid hidden blocking on default dispatchers.
+- Keep Android/shared/JVM boundaries explicit to avoid platform leakage.
+- Favor allocation-light data flows in hot paths and measure before micro-optimizing.
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/operational-baseline.md` | You need Kotlin coroutine, modularity, testing, and production guardrails. |
+
 ## Avoid
 
 - Coroutine launches without lifecycle ownership.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/kotlin-pro/references/operational-baseline.md

@@ -0,0 +1,9 @@
+## Operational baseline
+
+Load when: coroutine ownership, modularity, testing, or production guardrails need explicit guidance.
+
+- Keep coroutine scope ownership explicit and lifecycle-aware.
+- Avoid hidden blocking on shared/default dispatchers.
+- Keep shared/domain modules isolated from platform-specific details.
+- Use deterministic tests for `Flow`, coroutine, and lifecycle behavior.
+- Prefer structured logs and traces that show dispatcher/cancellation context.

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/microservices-architect/SKILL.md

@@ -83,11 +83,3 @@ When designing microservices architecture, provide:
 ## Knowledge Reference
 
 Domain-driven design, bounded contexts, event storming, REST/gRPC, message queues (Kafka, RabbitMQ), service mesh (Istio, Linkerd), Kubernetes, circuit breakers, saga patterns, event sourcing, CQRS, distributed tracing (Jaeger, Zipkin), API gateways, eventual consistency, CAP theorem
-
-## Related Powers
-
-- **DevOps Engineer** - Container orchestration and CI/CD pipelines
-- **Kubernetes Specialist** - Advanced K8s patterns and operators
-- **GraphQL Architect** - Federation for distributed schemas
-- **Architecture Designer** - High-level system design
-- **Monitoring Expert** - Observability implementation

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/mobile-design/SKILL.md

@@ -29,16 +29,16 @@ allowed-tools: Read, Glob, Grep, Bash
 
 | File | Content | Status |
 |------|---------|--------|
-| **[mobile-design-thinking.md](mobile-design-thinking.md)** | **⚠️ ANTI-MEMORIZATION: Forces thinking, prevents AI defaults** | **⬜ CRITICAL FIRST** |
-| **[touch-psychology.md](touch-psychology.md)** | **Fitts' Law, gestures, haptics, thumb zone** | **⬜ CRITICAL** |
-| **[mobile-performance.md](mobile-performance.md)** | **RN/Flutter performance, 60fps, memory** | **⬜ CRITICAL** |
-| **[mobile-backend.md](mobile-backend.md)** | **Push notifications, offline sync, mobile API** | **⬜ CRITICAL** |
-| **[mobile-testing.md](mobile-testing.md)** | **Testing pyramid, E2E, platform-specific** | **⬜ CRITICAL** |
-| **[mobile-debugging.md](mobile-debugging.md)** | **Native vs JS debugging, Flipper, Logcat** | **⬜ CRITICAL** |
-| [mobile-navigation.md](mobile-navigation.md) | Tab/Stack/Drawer, deep linking | ⬜ Read |
-| [mobile-typography.md](mobile-typography.md) | System fonts, Dynamic Type, a11y | ⬜ Read |
-| [mobile-color-system.md](mobile-color-system.md) | OLED, dark mode, battery-aware | ⬜ Read |
-| [decision-trees.md](decision-trees.md) | Framework/state/storage selection | ⬜ Read |
+| **[mobile-design-thinking.md](references/mobile-design-thinking.md)** | **⚠️ ANTI-MEMORIZATION: Forces thinking, prevents AI defaults** | **⬜ CRITICAL FIRST** |
+| **[touch-psychology.md](references/touch-psychology.md)** | **Fitts' Law, gestures, haptics, thumb zone** | **⬜ CRITICAL** |
+| **[mobile-performance.md](references/mobile-performance.md)** | **RN/Flutter performance, 60fps, memory** | **⬜ CRITICAL** |
+| **[mobile-backend.md](references/mobile-backend.md)** | **Push notifications, offline sync, mobile API** | **⬜ CRITICAL** |
+| **[mobile-testing.md](references/mobile-testing.md)** | **Testing pyramid, E2E, platform-specific** | **⬜ CRITICAL** |
+| **[mobile-debugging.md](references/mobile-debugging.md)** | **Native vs JS debugging, Flipper, Logcat** | **⬜ CRITICAL** |
+| [mobile-navigation.md](references/mobile-navigation.md) | Tab/Stack/Drawer, deep linking | ⬜ Read |
+| [mobile-typography.md](references/mobile-typography.md) | System fonts, Dynamic Type, a11y | ⬜ Read |
+| [mobile-color-system.md](references/mobile-color-system.md) | OLED, dark mode, battery-aware | ⬜ Read |
+| [decision-trees.md](references/decision-trees.md) | Framework/state/storage selection | ⬜ Read |
 
 > 🧠 **mobile-design-thinking.md is PRIORITY!** This file ensures AI thinks instead of using memorized patterns.
 
@@ -46,8 +46,8 @@ allowed-tools: Read, Glob, Grep, Bash
 
 | Platform | File | Content | When to Read |
 |----------|------|---------|--------------|
-| **iOS** | [platform-ios.md](platform-ios.md) | Human Interface Guidelines, SF Pro, SwiftUI patterns | Building for iPhone/iPad |
-| **Android** | [platform-android.md](platform-android.md) | Material Design 3, Roboto, Compose patterns | Building for Android |
+| **iOS** | [platform-ios.md](references/platform-ios.md) | Human Interface Guidelines, SF Pro, SwiftUI patterns | Building for iPhone/iPad |
+| **Android** | [platform-android.md](references/platform-android.md) | Material Design 3, Roboto, Compose patterns | Building for Android |
 | **Cross-Platform** | Both above | Platform divergence points | React Native / Flutter |
 
 > 🔴 **If building for iOS → Read platform-ios.md FIRST!**
@@ -193,7 +193,7 @@ Mobile:  Finger is imprecise (~7mm contact area)
 | Large viewport | Limited space, scroll vertical |
 | Stable attention | Interrupted constantly |
 
-For deep dive: [touch-psychology.md](touch-psychology.md)
+For deep dive: [touch-psychology.md](references/touch-psychology.md)
 
 ---
 
@@ -266,7 +266,7 @@ GPU-accelerated (FAST):     CPU-bound (SLOW):
                             └── (AVOID animating these)
 ```
 
-For complete guide: [mobile-performance.md](mobile-performance.md)
+For complete guide: [mobile-performance.md](references/mobile-performance.md)
 
 ---
 
@@ -336,7 +336,7 @@ WHAT ARE YOU BUILDING?
             └── ✅ Flutter
 ```
 
-For complete decision trees: [decision-trees.md](decision-trees.md)
+For complete decision trees: [decision-trees.md](references/decision-trees.md)
 
 ---
 
@@ -379,15 +379,15 @@ For deeper guidance on specific areas:
 
 | File | When to Use |
 |------|-------------|
-| [mobile-design-thinking.md](mobile-design-thinking.md) | **FIRST! Anti-memorization, forces context-based thinking** |
-| [touch-psychology.md](touch-psychology.md) | Understanding touch interaction, Fitts' Law, gesture design |
-| [mobile-performance.md](mobile-performance.md) | Optimizing RN/Flutter, 60fps, memory/battery |
-| [platform-ios.md](platform-ios.md) | iOS-specific design, HIG compliance |
-| [platform-android.md](platform-android.md) | Android-specific design, Material Design 3 |
-| [mobile-navigation.md](mobile-navigation.md) | Navigation patterns, deep linking |
-| [mobile-typography.md](mobile-typography.md) | Type scale, system fonts, accessibility |
-| [mobile-color-system.md](mobile-color-system.md) | OLED optimization, dark mode, battery |
-| [decision-trees.md](decision-trees.md) | Framework, state, storage decisions |
+| [mobile-design-thinking.md](references/mobile-design-thinking.md) | **FIRST! Anti-memorization, forces context-based thinking** |
+| [touch-psychology.md](references/touch-psychology.md) | Understanding touch interaction, Fitts' Law, gesture design |
+| [mobile-performance.md](references/mobile-performance.md) | Optimizing RN/Flutter, 60fps, memory/battery |
+| [platform-ios.md](references/platform-ios.md) | iOS-specific design, HIG compliance |
+| [platform-android.md](references/platform-android.md) | Android-specific design, Material Design 3 |
+| [mobile-navigation.md](references/mobile-navigation.md) | Navigation patterns, deep linking |
+| [mobile-typography.md](references/mobile-typography.md) | Type scale, system fonts, accessibility |
+| [mobile-color-system.md](references/mobile-color-system.md) | OLED optimization, dark mode, battery |
+| [decision-trees.md](references/decision-trees.md) | Framework, state, storage decisions |
 
 ---
 

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/nestjs-expert/SKILL.md

@@ -14,7 +14,7 @@ Senior NestJS specialist with deep expertise in enterprise-grade, scalable TypeS
 
 You are a senior Node.js engineer with 10+ years of backend experience. You specialize in NestJS architecture, dependency injection, and enterprise patterns. You build modular, testable applications with proper separation of concerns.
 
-## When to Use This Power
+## When to Use This Skill
 
 - Building NestJS REST APIs with Fastify
 - Implementing modules, controllers, and services
@@ -105,10 +105,3 @@ When implementing NestJS features, provide:
 ## Knowledge Reference
 
 NestJS, TypeScript, Mongoose, Fastify, @fastify/secure-session, class-validator, class-transformer, Swagger/OpenAPI, Jest, Supertest, Guards, Interceptors, Pipes, Filters
-
-## Related Powers
-
-- **Fastify Patterns** - Fastify adapter and session configuration
-- **Mongoose NestJS** - MongoDB integration patterns
-- **Test Master** - Comprehensive testing strategies
-- **Security Reviewer** - Security auditing

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/nestjs-expert/references/authentication.md

@@ -457,5 +457,5 @@ getMyOrg(@SessionUser('organizationId') orgId: string) {
 
 ## Related Reference Files
 
-- `references/secure-sessions.md` (Fastify Patterns) - Detailed session configuration
-- `references/services-di.md` - Dependency injection patterns
+- [secure-sessions.md](secure-sessions.md) (Fastify Patterns) - Detailed session configuration
+- [services-di.md](services-di.md) - Dependency injection patterns

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/nestjs-expert/references/migration-from-express.md

@@ -989,7 +989,7 @@ describe('UsersController (e2e)', () => {
 
 Gradually replace Express routes with NestJS while both run simultaneously.
 
-**Cross-reference:** See `references/strangler-fig-pattern.md` for detailed implementation.
+**Cross-reference:** See [strangler-fig-pattern.md](strangler-fig-pattern.md) for detailed implementation.
 
 ```typescript
 // main.ts - Running both Express and NestJS

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/nestjs-expert/references/secure-sessions.md

@@ -52,5 +52,5 @@ Do not store tokens, passwords, raw PII, or authorization policy blobs.
 
 ## Related
 
-- `references/authentication.md`
-- `references/services-di.md`
+- [authentication.md](authentication.md)
+- [services-di.md](services-di.md)

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/nestjs-expert/references/strangler-fig-pattern.md

@@ -43,5 +43,5 @@ Move route groups from legacy to NestJS in controlled slices while preserving be
 
 ## Related
 
-- `references/migration-from-express.md`
-- `references/authentication.md`
+- [migration-from-express.md](migration-from-express.md)
+- [authentication.md](authentication.md)

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/next-best-practices/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: next-best-practices
 description: "Rulebook for reviewing/generating Next.js code against Vercel best practices (conventions, RSC boundaries, async APIs, metadata, bundling). Not a migration or feature-implementation skill by itself."
-user-invocable: false
+metadata:
+  user-invocable: false
 ---
 
 # Next.js Best Practices
@@ -10,7 +11,7 @@ Apply these rules when writing or reviewing Next.js code.
 
 ## File Conventions
 
-See [file-conventions.md](./file-conventions.md) for:
+See [file-conventions.md](references/file-conventions.md) for:
 - Project structure and special files
 - Route segments (dynamic, catch-all, groups)
 - Parallel and intercepting routes
@@ -20,7 +21,7 @@ See [file-conventions.md](./file-conventions.md) for:
 
 Detect invalid React Server Component patterns.
 
-See [rsc-boundaries.md](./rsc-boundaries.md) for:
+See [rsc-boundaries.md](references/rsc-boundaries.md) for:
 - Async client component detection (invalid)
 - Non-serializable props detection
 - Server Action exceptions
@@ -29,33 +30,33 @@ See [rsc-boundaries.md](./rsc-boundaries.md) for:
 
 Next.js 15+ async API changes.
 
-See [async-patterns.md](./async-patterns.md) for:
+See [async-patterns.md](references/async-patterns.md) for:
 - Async `params` and `searchParams`
 - Async `cookies()` and `headers()`
 - Migration codemod
 
 ## Runtime Selection
 
-See [runtime-selection.md](./runtime-selection.md) for:
+See [runtime-selection.md](references/runtime-selection.md) for:
 - Default to Node.js runtime
 - When Edge runtime is appropriate
 
 ## Directives
 
-See [directives.md](./directives.md) for:
+See [directives.md](references/directives.md) for:
 - `'use client'`, `'use server'` (React)
 - `'use cache'` (Next.js)
 
 ## Functions
 
-See [functions.md](./functions.md) for:
+See [functions.md](references/functions.md) for:
 - Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
 - Server functions: `cookies`, `headers`, `draftMode`, `after`
 - Generate functions: `generateStaticParams`, `generateMetadata`
 
 ## Error Handling
 
-See [error-handling.md](./error-handling.md) for:
+See [error-handling.md](references/error-handling.md) for:
 - `error.tsx`, `global-error.tsx`, `not-found.tsx`
 - `redirect`, `permanentRedirect`, `notFound`
 - `forbidden`, `unauthorized` (auth errors)
@@ -63,14 +64,14 @@ See [error-handling.md](./error-handling.md) for:
 
 ## Data Patterns
 
-See [data-patterns.md](./data-patterns.md) for:
+See [data-patterns.md](references/data-patterns.md) for:
 - Server Components vs Server Actions vs Route Handlers
 - Avoiding data waterfalls (`Promise.all`, Suspense, preload)
 - Client component data fetching
 
 ## Route Handlers
 
-See [route-handlers.md](./route-handlers.md) for:
+See [route-handlers.md](references/route-handlers.md) for:
 - `route.ts` basics
 - GET handler conflicts with `page.tsx`
 - Environment behavior (no React DOM)
@@ -78,7 +79,7 @@ See [route-handlers.md](./route-handlers.md) for:
 
 ## Metadata & OG Images
 
-See [metadata.md](./metadata.md) for:
+See [metadata.md](references/metadata.md) for:
 - Static and dynamic metadata
 - `generateMetadata` function
 - OG image generation with `next/og`
@@ -86,7 +87,7 @@ See [metadata.md](./metadata.md) for:
 
 ## Image Optimization
 
-See [image.md](./image.md) for:
+See [image.md](references/image.md) for:
 - Always use `next/image` over `<img>`
 - Remote images configuration
 - Responsive `sizes` attribute
@@ -95,7 +96,7 @@ See [image.md](./image.md) for:
 
 ## Font Optimization
 
-See [font.md](./font.md) for:
+See [font.md](references/font.md) for:
 - `next/font` setup
 - Google Fonts, local fonts
 - Tailwind CSS integration
@@ -103,7 +104,7 @@ See [font.md](./font.md) for:
 
 ## Bundling
 
-See [bundling.md](./bundling.md) for:
+See [bundling.md](references/bundling.md) for:
 - Server-incompatible packages
 - CSS imports (not link tags)
 - Polyfills (already included)
@@ -112,7 +113,7 @@ See [bundling.md](./bundling.md) for:
 
 ## Scripts
 
-See [scripts.md](./scripts.md) for:
+See [scripts.md](references/scripts.md) for:
 - `next/script` vs native script tags
 - Inline scripts need `id`
 - Loading strategies
@@ -120,34 +121,33 @@ See [scripts.md](./scripts.md) for:
 
 ## Hydration Errors
 
-See [hydration-error.md](./hydration-error.md) for:
+See [hydration-error.md](references/hydration-error.md) for:
 - Common causes (browser APIs, dates, invalid HTML)
 - Debugging with error overlay
 - Fixes for each cause
 
 ## Suspense Boundaries
 
-See [suspense-boundaries.md](./suspense-boundaries.md) for:
+See [suspense-boundaries.md](references/suspense-boundaries.md) for:
 - CSR bailout with `useSearchParams` and `usePathname`
 - Which hooks require Suspense boundaries
 
 ## Parallel & Intercepting Routes
 
-See [parallel-routes.md](./parallel-routes.md) for:
+See [parallel-routes.md](references/parallel-routes.md) for:
 - Modal patterns with `@slot` and `(.)` interceptors
 - `default.tsx` for fallbacks
 - Closing modals correctly with `router.back()`
 
 ## Self-Hosting
 
-See [self-hosting.md](./self-hosting.md) for:
+See [self-hosting.md](references/self-hosting.md) for:
 - `output: 'standalone'` for Docker
 - Cache handlers for multi-instance ISR
 - What works vs needs extra setup
 
 ## Debug Tricks
 
-See [debug-tricks.md](./debug-tricks.md) for:
+See [debug-tricks.md](references/debug-tricks.md) for:
 - MCP endpoint for AI-assisted debugging
 - Rebuild specific routes with `--debug-build-paths`
-

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/next-upgrade/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: next-upgrade
 description: "Use only for upgrading Next.js versions with official migration guides and codemods; includes dependency/version planning and upgrade validation."
-argument-hint: "[target-version]"
+metadata:
+  argument-hint: "[target-version]"
 ---
 
 # Upgrade Next.js

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/oneup-design/SKILL.md

@@ -16,9 +16,11 @@ import '../../../../core/design_system/one_design_system.dart';
 
 ## When to Load Steering Files
 
-- Working with colors → `colors.md`
-- Working with spacing/padding → `spacing.md`
-- Using One* components → `components.md`
+| File | Load when |
+| --- | --- |
+| `references/colors.md` | Choosing semantic colors, surface roles, and token-safe palette usage. |
+| `references/spacing.md` | Replacing hard-coded spacing/padding and aligning with token spacing rules. |
+| `references/components.md` | Selecting or reviewing One* components and their expected usage patterns. |
 
 ## MCP Tools (Use Before Writing UI)
 

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/plan-writing/SKILL.md

@@ -31,7 +31,7 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ### 4. Dynamic Naming in Project Root
 - Plan files are saved as `{task-slug}.md` in the PROJECT ROOT
-- Name derived from task (e.g., "add auth" → `auth-feature.md`)
+- Name derived from task (e.g., "add auth" -> auth-feature markdown plan in the project root)
 - **NEVER** inside `.claude/`, `docs/`, or temp folders
 
 ## Planning Principles (NOT Templates!)

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/prompt-engineer/SKILL.md

@@ -9,11 +9,13 @@ keywords: ["prompt", "llm", "ai", "chain-of-thought", "few-shot", "evaluation",
 
 ## When to Load Steering Files
 
-- Prompt patterns (zero-shot, few-shot, CoT) → `prompt-patterns.md`
-- Optimization techniques → `prompt-optimization.md`
-- Evaluation frameworks → `evaluation-frameworks.md`
-- Structured outputs (JSON, function calling) → `structured-outputs.md`
-- System prompt design → `system-prompts.md`
+| File | Load when |
+| --- | --- |
+| `references/prompt-patterns.md` | Choosing zero-shot, few-shot, chain-of-thought, or decomposition patterns. |
+| `references/prompt-optimization.md` | Iterating on failures, reducing ambiguity, or tightening prompts for latency/cost. |
+| `references/evaluation-frameworks.md` | Building prompt test cases, eval loops, or regression checks. |
+| `references/structured-outputs.md` | Designing JSON outputs, schema-constrained outputs, or tool/function calling prompts. |
+| `references/system-prompts.md` | Defining durable system prompts, role constraints, or behavioral guardrails. |
 
 ## Core Workflow