arckode-ui 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Frontend framework con .ark SFCs, signals, file-system router y analyzer estático con sugerencias concretas de fix. Diseñado para máxima predictibilidad de output de IA.",
   "keywords": [
@@ -38,7 +38,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ark": "./dist/cli.js"
+    "ark": "dist/cli.js"
   },
   "files": [
     "dist",

package/skills/SKILL.md

@@ -0,0 +1,866 @@
+# SKILL: Arckode UI — AI Development Protocol
+
+> Leé esto COMPLETO antes de escribir una sola línea de `.ark` o de código que use `arckode-ui`.
+> Este skill se activa cuando: hay archivos `.ark`, se importa de `arckode-ui` o `arckode-ui/vite`,
+> se usa `defineComponent`, `signal`, `computed`, `defineStore`, `createService`, `ark analyze`, `ark generate`.
+
+## SUB-SKILLS DISPONIBLES (publicados con el paquete npm)
+
+Cuando necesités detalle profundo de un área, leer el sub-skill correspondiente.
+Los sub-skills están en `./node_modules/arckode-ui/skills/` (si el proyecto usa npm/bun install):
+
+| Contexto | Sub-skill a leer |
+|----------|------------------|
+| Escribir un `.ark` para usuario, patrones de UI (modal con slot, form con validación, lista con curried action, `:class` reactivo) | `./node_modules/arckode-ui/skills/components/SKILL.md` |
+| Signals, computed, watch, effect, lifecycle, renderer, comunicación padre↔hijo | `./node_modules/arckode-ui/skills/runtime/SKILL.md` |
+| Parser, template-compiler, vite-plugin, agregar directiva nueva | `./node_modules/arckode-ui/skills/compiler/SKILL.md` |
+| Agregar regla nueva al analyzer, fix suggestions, mensajes | `./node_modules/arckode-ui/skills/analyzer/SKILL.md` |
+| CLI `ark`, plantillas del generator, build del bin | `./node_modules/arckode-ui/skills/cli/SKILL.md` |
+| Vitest + happy-dom, mockear fetch, testar componentes | `./node_modules/arckode-ui/skills/testing/SKILL.md` |
+
+> Si el proyecto está desarrollando el framework (no usándolo como dep), los sub-skills están en `./skills/` directamente.
+
+---
+
+## 1. QUÉ ES ARCKODE UI (entiendelo ANTES de codear)
+
+Framework frontend **architected FOR AI** — su objetivo no es ser flexible sino **predecible**.
+Un componente `.ark` SIEMPRE tiene la misma estructura. El analizador detecta cuando la rompés
+y SIEMPRE sugiere el fix concreto en el campo `violation.fix`.
+
+**Pila obligatoria:**
+- TypeScript strict (no `any`)
+- Vite con `arkcodeUi()` plugin
+- Signals (no ref/reactive)
+- HTML declarativo compilado (no JSX)
+- Bun (recomendado) o Node ≥ 18
+
+**El composition root es `main.ts` + el `App.ark` root.** Si un componente no está importado en alguna chain desde App, no existe.
+
+---
+
+## 2. PROTOCOLO OBLIGATORIO (antes de escribir código)
+
+```
+PASO 1 — IDENTIFICAR ALCANCE
+  ¿La tarea toca 1 componente nuevo?            → Seguir
+  ¿La tarea toca 1 componente existente?        → Leer el .ark primero, no asumir
+  ¿La tarea toca varios componentes hermanos?   → Identificar si necesita un store
+  ¿La tarea toca el routing?                    → Trabajar en src/pages/
+  ¿La tarea toca HTTP a un backend?             → Crear/modificar service, NO tocar componente
+  ¿La tarea toca estado global compartido?      → defineStore en src/stores/
+  ¿La tarea toca el framework en sí?            → DETENERSE. Ese es trabajo del repo del framework.
+
+PASO 2 — VERIFICAR REGLAS (ver §3)
+  ¿Estoy poniendo lógica en template?           → REGLA #11 — extraer a computed/action
+  ¿Estoy usando ref()/reactive()?               → REGLA #8 — usar signal()
+  ¿Estoy haciendo fetch() en el componente?     → REGLA #10 — mover a service
+  ¿Estoy usando provide/inject/v-model?         → NO EXISTEN. Reglas #7 y #9
+  ¿Mi handler @click no empieza con actions.?   → REGLA #4
+  ¿Mi v-for tiene colección sin namespace?      → REGLA #5
+  ¿Mi return de setup tiene llaves extra?       → REGLA #3
+  ¿Mi prop no tiene type?                       → REGLA #1
+  ¿Mi emit usa camelCase?                       → REGLA #2
+
+PASO 3 — GENERAR
+  Si es componente nuevo: copiar la PLANTILLA CANÓNICA (§5) y adaptar
+  Si es modificación: respetar el orden del setup() (§4)
+  Si es estado global: copiar PATRÓN DE STORE (§7)
+  Si es service HTTP: copiar PATRÓN DE SERVICE (§8)
+
+PASO 4 — VERIFICAR (NO ASUMIR que funciona)
+  npx ark analyze          → 0 errors. Si hay errors, leer violation.fix y aplicar
+  bun test                 → si trabajás en el framework
+  Probar en navegador      → npx vite (o bun dev) y verificar que la feature funciona
+```
+
+---
+
+## 3. REGLAS INMUTABLES (no negociables — el analyzer las detecta)
+
+Cada regla tiene un código que aparece en el output del analyzer. La IA puede referenciarlas
+diciendo "esto viola REGLA #N" para ser explícita.
+
+### ⚠ REGLA #1 — Toda prop DEBE tener `type` (clase nativa)
+
+```typescript
+// ❌
+props: { name: { required: true } }                  // PROP_MISSING_TYPE
+props: { name: { type: 'string' } }                  // string en vez de String
+
+// ✅
+props: { name: { type: String, required: true } }
+```
+
+Tipos válidos: `String | Number | Boolean | Array | Object | Function` (clases nativas).
+
+### ⚠ REGLA #2 — `emits` SIEMPRE en kebab-case
+
+```typescript
+// ❌
+emits: ['userSaved', 'formCancelled']                // EMIT_CAMELCASE
+
+// ✅
+emits: ['user-saved', 'form-cancelled']
+```
+
+Al escuchar: `<Child @user-saved="actions.x">`. Al emitir: `emit('user-saved', payload)`.
+
+### ⚠ REGLA #3 — `setup()` retorna SOLO `state`, `computed`, `actions`
+
+```typescript
+// ❌
+return { state: {}, computed: {}, actions: {}, methods: {} }  // SETUP_UNKNOWN_RETURN_KEY
+return { signals: {}, ... }                                    // signals no es válido
+
+// ✅
+return { state, computed, actions }
+```
+
+Llaves OK: `state` (signals mutables), `computed` (derivados readonly), `actions` (functions).
+NO se permite otra. Si tu return tiene una llave extra, mover su contenido a una de las 3.
+
+### ⚠ REGLA #4 — Handlers de eventos SIEMPRE `actions.xxx`
+
+```html
+<!-- ❌ -->
+<button @click="handleClick">                        <!-- HANDLER_NOT_IN_ACTIONS -->
+<button @click="state.count.value++">                <!-- LOGIC_IN_TEMPLATE + HANDLER_NOT_IN_ACTIONS -->
+<button @click="submit()">
+
+<!-- ✅ -->
+<button @click="actions.handleClick">
+<button @click="actions.increment">
+<button @click="actions.toggleTodo(todo.id)">        <!-- curried OK -->
+```
+
+### ⚠ REGLA #5 — `v-for` colección SIEMPRE namespaced
+
+```html
+<!-- ❌ -->
+<li v-for="item in items">                           <!-- VFOR_NOT_NAMESPACED -->
+<li v-for="x in getList()">                          <!-- llamada a función -->
+
+<!-- ✅ -->
+<li v-for="item in state.items.value">
+<li v-for="tab in computed.tabs.value">
+<li v-for="opt in props.options">
+<li v-for="(item, idx) in state.items.value">        <!-- con índice -->
+```
+
+### ⚠ REGLA #6 — `v-if` y `v-else-if` deben usar acceso namespaced (con `.`)
+
+```html
+<!-- ⚠ warning -->
+<div v-if="visible">                                  <!-- VIF_NOT_NAMESPACED -->
+
+<!-- ✅ -->
+<div v-if="state.visible.value">
+<div v-if="computed.isReady.value">
+<div v-if="props.active">
+<div v-if="todo.done">                                <!-- variable de loop con dot -->
+<div v-if="state.count.value > 0">
+```
+
+### ⚠ REGLA #7 — NO existe `v-model`. Input controlado explícito
+
+```html
+<!-- ❌ -->
+<input v-model="state.email" />
+
+<!-- ✅ -->
+<input :value="state.email.value" @input="actions.onEmailInput" />
+```
+
+```typescript
+function onEmailInput(e: Event) {
+  email.value = (e.target as HTMLInputElement).value
+}
+```
+
+### ⚠ REGLA #8 — NO existe `ref()` ni `reactive()`. Solo `signal`/`computed`
+
+```typescript
+// ❌
+const x = ref(0)                                     // REF_REACTIVE_USAGE
+const s = reactive({ a: 1, b: 2 })                   // REF_REACTIVE_USAGE
+
+// ✅
+const x = signal(0)
+const a = signal(1); const b = signal(2)             // un signal por propiedad
+```
+
+### ⚠ REGLA #9 — NO existe `provide`/`inject`. Estado compartido = `defineStore`
+
+```typescript
+// ❌
+provide('key', value)                                // PROVIDE_INJECT_USAGE
+const v = inject('key')
+
+// ✅
+// stores/auth.store.ts
+export const useAuthStore = defineStore('auth', { state, getters, actions })
+// componente
+const auth = useAuthStore()
+```
+
+### ⚠ REGLA #10 — `fetch()` PROHIBIDO en componente. Siempre via service
+
+```typescript
+// ❌
+onMount(() => fetch('/api/users'))                   // DIRECT_FETCH_IN_COMPONENT
+
+// ✅
+// services/user.service.ts
+export const UserService = createService(
+  { baseUrl: '/api/users' },
+  { async getAll() { return this.get<User[]>('/') } },
+)
+// componente
+import { UserService } from '../services/user.service'
+function load() { UserService.getAll().then(...) }
+```
+
+### ⚠ REGLA #11 — NO lógica en directivas (`++`, `--`, ternario complejo)
+
+```html
+<!-- ❌ -->
+<button @click="state.count.value++">                <!-- LOGIC_IN_TEMPLATE -->
+<div :class="state.x.value > 0 ? 'a' : 'b'">         <!-- ternario en :class -->
+
+<!-- ✅ -->
+<button @click="actions.increment">
+<div :class="computed.xClass.value">                  <!-- mover a computed -->
+```
+
+### ⚠ REGLA #12 — Actions como `function declaration`, no arrow
+
+```typescript
+// ❌
+actions: { submit: () => { ... } }                   // ARROW_FUNCTION_ACTION
+const submit = () => { ... }
+return { actions: { submit } }                       // ARROW_FUNCTION_ACTION
+
+// ✅
+function submit() { ... }
+return { actions: { submit } }
+```
+
+### ⚠ REGLA #13 — Componentes hijos: PascalCase + import explícito
+
+```html
+<!-- ❌ -->
+<usercard :prop="x" />                                <!-- minúscula = elemento HTML -->
+
+<!-- ✅ -->
+<UserCard :prop="state.x.value" />
+```
+
+```typescript
+// import obligatorio
+import UserCard from './UserCard.ark'
+```
+
+### ⚠ REGLA #14 — `mount(component, selector)` toma string, no HTMLElement
+
+```typescript
+// ❌
+mount(App, document.getElementById('app')!)
+
+// ✅
+mount(App, '#app')
+```
+
+### ⚠ REGLA #15 — Imports SOLO de `'arckode-ui'` o `'arckode-ui/vite'`
+
+```typescript
+// ❌
+import { ref } from 'vue'
+import { useState } from 'react'
+import { defineStore } from 'arckode-ui/store'        // no existe ese subpath
+
+// ✅
+import { defineComponent, signal, computed, defineStore, createService } from 'arckode-ui'
+import { arkcodeUi } from 'arckode-ui/vite'
+```
+
+Plugin se llama **`arkcodeUi`** (no `arckodeUi`, no `arckodePlugin`).
+
+### ⚠ REGLA #16 — Orden recomendado del `setup()` (convención, no enforced)
+
+```
+1. signals       → const x = signal(...)
+2. computed      → const y = computed(...)
+3. lifecycle     → onMount(...)
+4. watch         → watch(x, ...)
+5. actions       → function doSomething() {}
+6. return        → return { state, computed, actions }
+```
+
+El analyzer NO enforza este orden. Es para legibilidad y para que la IA prediga la posición.
+
+---
+
+## 4. ÁRBOLES DE DECISIÓN (Si te piden X, hacé Y)
+
+### ¿Te piden CREAR un componente nuevo?
+
+```
+¿Qué tipo de componente?
+
+  → Página (URL accesible)
+    Comando: ark generate page <kebab/o/[id]>
+    Path: src/pages/<name>.ark
+    Mountable directamente desde el file-system router
+
+  → Layout (wrapper de carpeta)
+    Comando: ark generate layout <name>
+    Path: src/pages/<name>/_layout.ark
+    Tiene <slot /> obligatorio
+
+  → Componente de dominio (UserCard, ProductList, etc.)
+    Comando: ark generate component <PascalCase>
+    Path: src/components/features/<Name>.ark
+
+  → Primitivo de UI (Button, Input, Modal)
+    Manual: src/components/ui/<Name>.ark
+    Igual estructura que componente de dominio
+
+  → Wrapper con contenido inyectable
+    Manual: usar <slot /> en el template, ver patrón en §6
+```
+
+### ¿Te piden AGREGAR estado a un componente?
+
+```
+¿El dato es local al componente?
+  SÍ → signal() en setup() — REGLA #8
+
+¿El dato se deriva de otro signal? (transformación pura)
+  SÍ → computed() — readonly, sin side effects
+
+¿El dato es controlado por el padre?
+  SÍ → prop con type — REGLA #1
+
+¿El padre necesita saber cuándo cambia?
+  SÍ → emit (kebab-case) — REGLA #2
+
+¿Otros componentes sin relación padre↔hijo lo necesitan?
+  SÍ → defineStore() — REGLA #9 (no provide/inject)
+
+¿Necesita disparar side effect cuando cambia un signal?
+  SÍ → watch(signal, callback)
+
+¿Necesita side effect con auto-suscripción a múltiples signals?
+  SÍ → effect(() => ...)
+```
+
+### ¿Te piden COMUNICAR componentes?
+
+```
+¿Padre → Hijo?
+  → prop con type (datos)
+  → callback como prop (acciones que el hijo invoca)
+
+¿Hijo → Padre?
+  Opción A (canónica): emit + @event en el padre
+    Hijo: emits: ['save'], emit('save', payload)
+    Padre: <Child @save="actions.onSave" />
+    El handler del padre recibe el payload directo (sin Event)
+
+  Opción B (callback como prop): cuando el hijo no "owns" el evento
+    Padre: <Child :onSave="actions.handle" />
+    Hijo: props.onSave declarado como Function
+
+¿Hermanos (sin relación)?
+  → defineStore() — signals globales compartidos
+
+¿Más de 2 niveles de props drilling?
+  → defineStore()
+```
+
+### ¿Te piden RENDERIZAR una lista?
+
+```
+1. La colección DEBE ser state.x.value / computed.x.value / props.x — REGLA #5
+2. Sintaxis: v-for="item in <colección>"  o  v-for="(item, idx) in <colección>"
+3. Si el handler necesita el item: curried action
+     function toggle(id: string) { return () => { ... } }
+     @click="actions.toggle(item.id)"
+4. Si :class depende de un signal Y del item: computed que retorna closure con SNAPSHOT
+     const itemClass = computed(() => {
+       const active = state.activeId.value     // ← lee la dep ACÁ
+       return (item) => item.id === active ? 'A' : 'B'
+     })
+     :class="computed.itemClass.value(item)"
+```
+
+### ¿Te piden HACER UN FETCH?
+
+```
+NUNCA en el componente — REGLA #10
+
+PASO 1: crear/modificar service en src/services/<dominio>.service.ts
+  export const UserService = createService(
+    { baseUrl: '/api/users' },
+    {
+      async getAll() { return this.get<User[]>('/') },
+      async getById(id: string) { return this.get<User>(`/${id}`) },
+    },
+  )
+
+PASO 2: en el componente, import y llamar desde action u onMount
+  import { UserService } from '../services/user.service'
+
+  const users = signal<User[]>([])
+  onMount(async () => {
+    users.value = await UserService.getAll()
+  })
+```
+
+### ¿Te piden MODIFICAR un componente existente?
+
+```
+PASO 1: Leer el .ark completo (no asumir su shape)
+PASO 2: Identificar dónde va el cambio según el ORDEN del setup() (§3 REGLA #16):
+  - Nuevo signal     → bloque 1
+  - Nuevo computed   → bloque 2
+  - Nuevo onMount    → bloque 3
+  - Nuevo watch      → bloque 4
+  - Nuevo action     → bloque 5
+  - Nueva prop       → en props: {} con type
+  - Nuevo emit       → en emits: [] kebab-case
+  - Nuevo slot       → en el template (cuidado, suma una API pública nueva)
+PASO 3: Si agregás un signal/computed/action, registrarlo en el return
+PASO 4: Correr ark analyze para confirmar 0 errors nuevos
+```
+
+### ¿El analyzer reportó un error?
+
+```
+PASO 1: Leer el message Y el campo `Fix:` (siempre viene con sugerencia concreta)
+PASO 2: Si el fix dice "Reemplazar X por Y": aplicar literal
+PASO 3: Si el fix dice "Crear un X y referenciarlo": crear primero, luego referenciar
+PASO 4: Re-correr ark analyze para confirmar que el error desapareció
+PASO 5: Si aparece OTRO error: repetir (a veces un fix expone uno latente)
+
+NO ignorar errors. NO desactivar reglas. NO ignorar warnings sin entender por qué aparecen.
+```
+
+---
+
+## 5. PLANTILLA CANÓNICA — componente completo
+
+Copiar y adaptar. Toda IA debe partir de esta plantilla para crear un componente nuevo.
+
+```html
+<template>
+  <div class="user-card">
+    <!-- Interpolación -->
+    <h2>{{ props.name }}</h2>
+    <p>{{ state.bio.value }}</p>
+    <span>{{ computed.followLabel.value }}</span>
+
+    <!-- Evento — SIEMPRE actions.xxx (REGLA #4) -->
+    <button @click="actions.follow">{{ computed.followLabel.value }}</button>
+
+    <!-- Input controlado — REGLA #7 -->
+    <input :value="state.bio.value" @input="actions.onBioInput" />
+
+    <!-- Condicional -->
+    <div v-if="state.following.value">Siguiendo</div>
+    <div v-else>No seguido</div>
+
+    <!-- Lista — colección namespaced (REGLA #5) -->
+    <div v-for="tag in state.tags.value">{{ tag }}</div>
+
+    <!-- v-show — mantiene en DOM -->
+    <div v-show="state.panelVisible.value">Panel</div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, signal, computed, watch, onMount } from 'arckode-ui'
+
+export default defineComponent({
+  name: 'UserCard',                       // REGLA: PascalCase obligatorio
+
+  props: {                                // REGLA #1
+    name:   { type: String, required: true },
+    userId: { type: String, required: true },
+  },
+
+  emits: ['follow', 'unfollow'],          // REGLA #2: kebab-case
+
+  setup(props, { emit }) {
+    // ── 1. signals ──
+    const bio       = signal('')
+    const following = signal(false)
+    const tags      = signal<string[]>([])
+    const panelVisible = signal(true)
+
+    // ── 2. computed ──
+    const followLabel = computed(() =>
+      following.value ? 'Dejar de seguir' : 'Seguir'
+    )
+
+    // ── 3. lifecycle ──
+    onMount(() => {
+      bio.value = 'Cargando...'
+      return () => { /* cleanup opcional */ }
+    })
+
+    // ── 4. watch ──
+    watch(following, (newVal) => { console.log('following:', newVal) })
+
+    // ── 5. actions — REGLA #12: function declaration ──
+    function follow() {
+      following.value = !following.value
+      emit(following.value ? 'follow' : 'unfollow', { userId: props.userId })
+    }
+    function onBioInput(e: Event) {
+      bio.value = (e.target as HTMLInputElement).value
+    }
+
+    // ── 6. return — REGLA #3: SOLO state/computed/actions ──
+    return {
+      state:    { bio, following, tags, panelVisible },
+      computed: { followLabel },
+      actions:  { follow, onBioInput },
+    }
+  },
+})
+</script>
+
+<style scoped>
+  .user-card { padding: 1rem; }
+</style>
+```
+
+---
+
+## 6. PLANTILLAS POR TIPO
+
+### 6.1 — Componente atómico (Badge, Button)
+
+```html
+<template>
+  <span :class="computed.classes.value"><slot /></span>
+</template>
+<script lang="ts">
+import { defineComponent, computed } from 'arckode-ui'
+const VARIANTS: Record<string, string> = { low: '...', high: '...' }
+export default defineComponent({
+  name: 'Badge',
+  props: { variant: { type: String, required: true } },
+  emits: [],
+  setup(props) {
+    const classes = computed(() => VARIANTS[props.variant as string] ?? VARIANTS['low'])
+    return { state: {}, computed: { classes }, actions: {} }
+  },
+})
+</script>
+```
+
+### 6.2 — Wrapper con slot (Modal, Card)
+
+```html
+<template>
+  <div v-show="props.visible" class="modal">
+    <div class="header">
+      <h2>{{ props.title }}</h2>
+      <button @click="actions.close">✕</button>
+    </div>
+    <div class="body"><slot /></div>
+  </div>
+</template>
+<script lang="ts">
+import { defineComponent } from 'arckode-ui'
+export default defineComponent({
+  name: 'Modal',
+  props: {
+    visible: { type: Boolean, required: true },
+    title:   { type: String,  required: true },
+    onClose: { type: Function, required: true },
+  },
+  emits: [],
+  setup(props) {
+    function close() { (props.onClose as () => void)() }
+    return { state: {}, computed: {}, actions: { close } }
+  },
+})
+</script>
+```
+
+### 6.3 — Lista con curried action
+
+```html
+<template>
+  <div v-for="item in state.items.value">
+    <button @click="actions.toggle(item.id)">{{ item.done ? '✓' : '○' }}</button>
+    <span>{{ item.text }}</span>
+  </div>
+</template>
+<script lang="ts">
+import { defineComponent, signal } from 'arckode-ui'
+interface Item { id: string; text: string; done: boolean }
+export default defineComponent({
+  name: 'ItemList',
+  props: {},
+  emits: [],
+  setup() {
+    const items = signal<Item[]>([])
+    function toggle(id: string) {
+      return () => {
+        items.value = items.value.map(i => i.id === id ? { ...i, done: !i.done } : i)
+      }
+    }
+    return { state: { items }, computed: {}, actions: { toggle } }
+  },
+})
+</script>
+```
+
+---
+
+## 7. STORE — estado global compartido
+
+```typescript
+// stores/user.store.ts
+import { defineStore, signal, computed } from 'arckode-ui'
+
+interface UserDTO { id: string; name: string }
+
+export const useUserStore = defineStore('user', {
+  state: {
+    current: signal<UserDTO | null>(null),
+    loading: signal(false),
+  },
+  getters: {
+    isLoggedIn: computed(() => useUserStore().state.current.value !== null),
+  },
+  actions: {
+    async login(email: string, password: string) {
+      const store = useUserStore()
+      store.state.loading.value = true
+      // ...
+    },
+    logout() { useUserStore().state.current.value = null },
+  },
+})
+```
+
+Uso en componente:
+```typescript
+const userStore = useUserStore()
+return {
+  state:    { current: userStore.state.current },
+  computed: { isLoggedIn: userStore.getters.isLoggedIn },
+  actions:  { logout: userStore.actions.logout },
+}
+```
+
+**Patrón clave:** dentro de getters/actions, llamar `useUserStore()` para acceder al state. Es feo pero es la API real verificada en tests.
+
+---
+
+## 8. SERVICE — HTTP
+
+```typescript
+// services/product.service.ts
+import { createService } from 'arckode-ui'
+
+interface Product { id: string; name: string; price: number }
+
+export const ProductService = createService(
+  { baseUrl: '/api/products', timeout: 5000 },
+  {
+    async getAll() { return this.get<Product[]>('/') },
+    async getById(id: string) { return this.get<Product>(`/${id}`) },
+    async create(data: Omit<Product, 'id'>) { return this.post<Product>('/', data) },
+    async update(id: string, data: Partial<Product>) { return this.put<Product>(`/${id}`, data) },
+    async remove(id: string) { return this.delete<void>(`/${id}`) },
+  },
+)
+```
+
+**Firma del createService: DOS ARGUMENTOS (options, definition).** Verificado en tests.
+
+---
+
+## 9. CLI — comandos exactos
+
+```bash
+ark new <nombre>                     # scaffold proyecto nuevo
+ark generate component <PascalCase>  # alias: ark g c
+ark generate page <name>             # alias: ark g p — name puede ser kebab o users/[id]
+ark generate store <camelCase>       # alias: ark g s
+ark generate service <PascalCase>    # alias: ark g sv
+ark generate layout <name>           # alias: ark g l
+ark analyze [--json]                 # detecta violations en .ark
+ark routes                           # lista rutas detectadas en src/pages/
+```
+
+Naming OBLIGATORIO (el generator lo enforza):
+- Component: PascalCase (Button, UserCard)
+- Store: camelCase (cart, userPreferences)
+- Service: PascalCase (Product, User)
+- Page/Layout: kebab-case con segmentos
+
+---
+
+## 10. VITE — setup del proyecto consumidor
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import { arkcodeUi } from 'arckode-ui/vite'           // REGLA #15: nombre EXACTO
+
+export default defineConfig({
+  plugins: [
+    arkcodeUi({
+      analyzer: {
+        failOnWarnings: false,    // dev: no bloquea. prod: bloquea errors.
+        ignore: [],               // códigos a ignorar
+      },
+    }),
+  ],
+})
+```
+
+```html
+<!-- index.html -->
+<div id="app"></div>
+<script type="module" src="/src/main.ts"></script>
+```
+
+```typescript
+// src/main.ts
+import { mount } from 'arckode-ui'
+import App from './App.ark'
+
+mount(App, '#app')                                     // REGLA #14: selector string
+```
+
+---
+
+## 11. ANALYZER OUTPUT — cómo leerlo
+
+Cada violation viene con `Fix:` cuando es determinístico. **Leer el Fix y aplicarlo literal.**
+
+```
+[arckode-ui] UserCard.ark:5
+  HANDLER_NOT_IN_ACTIONS: El handler "handleClick" no está namespaced.
+
+  > 5 | <button @click="handleClick">
+  Fix: Reemplazar "handleClick" por "actions.handleClick" y asegurarse de que la función esté declarada en setup() y exportada en el return.actions.
+```
+
+Códigos del analyzer (16):
+
+| Código | Severity | Regla violada |
+|--------|----------|---------------|
+| MISSING_TEMPLATE | error | — (estructura) |
+| MISSING_SCRIPT | error | — |
+| MISSING_LANG_TS | error | — |
+| WRONG_TEMPLATE_ORDER | error | — |
+| MISSING_COMPONENT_NAME | error | — |
+| PROP_MISSING_TYPE | error | REGLA #1 |
+| EMIT_CAMELCASE | error | REGLA #2 |
+| SETUP_UNKNOWN_RETURN_KEY | error | REGLA #3 |
+| HANDLER_NOT_IN_ACTIONS | error | REGLA #4 |
+| VFOR_NOT_NAMESPACED | error | REGLA #5 |
+| VIF_NOT_NAMESPACED | warning | REGLA #6 |
+| REF_REACTIVE_USAGE | error | REGLA #8 |
+| PROVIDE_INJECT_USAGE | error | REGLA #9 |
+| DIRECT_FETCH_IN_COMPONENT | error | REGLA #10 |
+| LOGIC_IN_TEMPLATE | error | REGLA #11 |
+| ARROW_FUNCTION_ACTION | warning | REGLA #12 |
+
+---
+
+## 12. CHECKLIST POST-CÓDIGO (antes de declarar "listo")
+
+```
+□ npx ark analyze                                     → 0 errors
+□ Si tocaste el framework: bun test                   → todos verdes
+□ Si tocaste UI: arrancar dev server y probar en navegador
+□ Si agregaste prop/emit nuevo: actualizar consumidores
+□ Si modificaste un componente que tenía tests: re-correr esos tests
+□ ¿Toqué exports del barrel src/index.ts del framework? → es breaking change
+□ ¿Cambié el código o severity de una violation? → es breaking change
+```
+
+**Si el analyzer reporta errors → corregirlos según el campo Fix.**
+**Si los tests fallan → corregir antes de continuar.**
+**No declarar "listo" hasta que los 2 estén verdes.**
+
+---
+
+## 13. ANTI-PATTERNS — referencia rápida (todo viola alguna regla numerada)
+
+```typescript
+// ❌ REGLA #1
+props: { name: { required: true } }
+props: { name: { type: 'string' } }
+
+// ❌ REGLA #2
+emits: ['userSaved']
+
+// ❌ REGLA #3
+return { state: {}, computed: {}, actions: {}, methods: {} }
+
+// ❌ REGLA #4
+@click="handleClick"
+@click="state.count.value++"
+
+// ❌ REGLA #5
+v-for="item in items"
+v-for="x in getList()"
+
+// ❌ REGLA #6 (warning)
+v-if="visible"
+
+// ❌ REGLA #7
+<input v-model="state.name" />
+
+// ❌ REGLA #8
+const x = ref(0)
+const s = reactive({})
+
+// ❌ REGLA #9
+provide('key', val)
+inject('key')
+
+// ❌ REGLA #10
+onMount(() => fetch('/api/x'))
+
+// ❌ REGLA #11
+@click="state.count.value++"
+:class="state.x.value ? 'a' : 'b'"
+
+// ❌ REGLA #12
+actions: { submit: () => {} }
+
+// ❌ REGLA #13
+<usercard :prop="x" />
+
+// ❌ REGLA #14
+mount(App, document.getElementById('app')!)
+
+// ❌ REGLA #15
+import { ref } from 'vue'
+import { arckodePlugin } from 'arckode-ui/vite'   // nombre incorrecto
+```
+
+---
+
+## 14. ESTADO ACTUAL DEL FRAMEWORK (v0.1.1)
+
+- ✅ 314 tests passing
+- ✅ 16 reglas del analyzer con `Fix:` field
+- ✅ APIs exportadas: signal, computed, watch, effect, defineComponent, onMount, onUnmount, onUpdate, h, mount, mountComponent, defineStore, createService, ArkServiceError, createRouter, navigate, useRoute, getCurrentPath
+- ✅ Subpath `arckode-ui/vite` exporta `arkcodeUi`
+- ✅ CLI `ark` con shebang ejecutable
+- ✅ 6 sub-skills distribuidos en `skills/`
+- ✅ 2 ejemplos completos: `kitchen-sink` (demo de features), `tasks` (app real con sidebar/modal/form)