@bcelep/capint 0.4.2 → 0.7.0

package/docs/generated/explanation.v2.md

@@ -0,0 +1,142 @@
+# CapInt Route Explanation v2
+
+> Auto-generated from `schemas/explanation.v2.json`. Do not edit by hand.
+
+**$id:** `https://capint.dev/schemas/explanation.v2.json`
+
+## Properties
+
+| Field | Type | Required |
+|-------|------|----------|
+| `task_type_id` | string,null | yes |
+| `matched_keywords` | array | yes |
+| `winner` | object,null | yes |
+| `files_to_read` | array | yes |
+| `reason_summary` | string | yes |
+| `reason_plain` | string | no |
+| `tooltip` | string | no |
+| `locale` | tr \| en | no |
+| `alternatives_considered` | array | yes |
+| `resolver_order` | array | no |
+| `files_intended` | array | no |
+| `workspace_boundary` | object | no |
+
+## Raw schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://capint.dev/schemas/explanation.v2.json",
+  "title": "CapInt Route Explanation v2",
+  "type": "object",
+  "required": [
+    "task_type_id",
+    "matched_keywords",
+    "winner",
+    "files_to_read",
+    "reason_summary",
+    "alternatives_considered"
+  ],
+  "properties": {
+    "task_type_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "matched_keywords": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "winner": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "properties": {
+        "type": {
+          "type": "string"
+        },
+        "resource": {
+          "type": "string"
+        }
+      }
+    },
+    "files_to_read": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "reason_summary": {
+      "type": "string"
+    },
+    "reason_plain": {
+      "type": "string"
+    },
+    "tooltip": {
+      "type": "string"
+    },
+    "locale": {
+      "enum": [
+        "tr",
+        "en"
+      ]
+    },
+    "alternatives_considered": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "resource": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "confidence": {
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        }
+      }
+    },
+    "resolver_order": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "files_intended": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "workspace_boundary": {
+      "type": "object",
+      "properties": {
+        "violated": {
+          "type": "boolean"
+        },
+        "suspicious_paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "override_hint": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
+}
+```

package/docs/generated/ui-api.v1.md

@@ -0,0 +1,178 @@
+# CapInt UI Wizard API
+
+> Auto-generated from `schemas/ui-api.v1.json`. Do not edit by hand.
+
+**$id:** `https://capint.dev/schemas/ui-api.v1.json`
+
+## Properties
+
+| Field | Type | Required |
+|-------|------|----------|
+
+## Raw schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://capint.dev/schemas/ui-api.v1.json",
+  "title": "CapInt UI Wizard API",
+  "definitions": {
+    "RouteRequest": {
+      "type": "object",
+      "required": [
+        "task"
+      ],
+      "properties": {
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "locale": {
+          "enum": [
+            "tr",
+            "en"
+          ]
+        }
+      }
+    },
+    "RouteResponse": {
+      "type": "object",
+      "required": [
+        "result",
+        "text_report",
+        "chat_copy"
+      ],
+      "properties": {
+        "result": {
+          "type": "object",
+          "required": [
+            "execution_intent"
+          ],
+          "properties": {
+            "execution_intent": {
+              "$ref": "execution-intent.v1.json"
+            }
+          }
+        },
+        "text_report": {
+          "type": "string"
+        },
+        "chat_copy": {
+          "type": "string"
+        }
+      }
+    },
+    "HealthResponse": {
+      "type": "object",
+      "required": [
+        "ok",
+        "doctor",
+        "status"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "doctor": {
+          "type": "object"
+        },
+        "status": {
+          "type": "object",
+          "properties": {
+            "skills_on_disk": {
+              "type": "number"
+            },
+            "core_skills": {
+              "type": "number"
+            },
+            "matrix_version": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "capint_package": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "RecoverRequest": {
+      "type": "object",
+      "properties": {
+        "apply": {
+          "type": "boolean",
+          "default": false
+        },
+        "latest": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "FeedbackRequest": {
+      "type": "object",
+      "properties": {
+        "rating": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5
+        },
+        "comment": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "source": {
+          "type": "string",
+          "default": "ui"
+        }
+      }
+    }
+  },
+  "paths": {
+    "/api/health": {
+      "get": {
+        "response": {
+          "$ref": "#/definitions/HealthResponse"
+        }
+      }
+    },
+    "/api/route": {
+      "post": {
+        "request": {
+          "$ref": "#/definitions/RouteRequest"
+        },
+        "response": {
+          "$ref": "#/definitions/RouteResponse"
+        }
+      }
+    },
+    "/api/recover": {
+      "post": {
+        "request": {
+          "$ref": "#/definitions/RecoverRequest"
+        },
+        "response": {
+          "type": "object"
+        }
+      }
+    },
+    "/api/feedback": {
+      "post": {
+        "request": {
+          "$ref": "#/definitions/FeedbackRequest"
+        },
+        "response": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```

package/docs/kullanim-kilavuzu.md

@@ -0,0 +1,374 @@
+# CapInt Kullanım Kılavuzu
+
+> **Sürüm:** 0.4.2 · **CLI:** `@bcelep/capint`  
+> **Günlük kullanıcı:** [GUNLUK.md](../GUNLUK.md) — **3 adım, terminal yok**  
+> **Detay:** [conventions/daily-use.md](conventions/daily-use.md)
+
+---
+
+## 0. Günlük kullanım (çoğu insan — buradan başla)
+
+CapInt **zor bir uygulama değil** — terminal aracı gibi görünür ama asıl iş **IDE chat’inde** olur. CLI kurulum ve debug içindir.
+
+```
+1. Görevi chat'e yaz (+ screenshot)
+2. Kısa intenti gör: Intent → Capability → Resolution → Plan
+3. Hafif iş: soru yok, doğrudan uygula. Orta/ağır: `devam` / `plan` / `analiz` yeterli
+```
+
+| Yapma | Yap |
+|-------|-----|
+| Skill/workflow adı ezberleme | Agent capability seçsin |
+| Her seferinde `capint route` | Sadece merak/debug: `--verbose` |
+| Uzun prosedür yazdırma | Kısa intent; gerekirse `devam` / `plan` / `analiz` |
+| Init sonrası terminalde takılma | Yeni chat aç, görevi yaz |
+
+**Örnek mesaj:** *“Lang dosyaları uyumsuz. Tek kaynak lang/*.php. Önce plan, onaylayınca düzelt.”*
+
+Terminal: yalnızca **kurulum** (`init`), **sorun** (`doctor`), **IDE kuralı** (`ide sync`).  
+Aşağıdaki bölümler referans / ileri seviye içindir.
+
+---
+
+## 1. CapInt nedir?
+
+CapInt, IDE agent’ına (Cursor, Claude Code, Gemini, Antigravity, …) **tutarlı görev yönlendirme** verir:
+
+| Sorun | CapInt çözümü |
+|-------|----------------|
+| Agent her görevde farklı davranır | `AGENT.md` + IDE session kuralları |
+| Hangi playbook kullanılacak belirsiz | Capability router (chat içinde sessiz) |
+| “Önce plan mı kod mu?” karışır | Execution Intent + **adaptive confirm** (hafif = otomatik) |
+| Skill dosyası yok, route boşa | Init **bundle** (skills + workflows) |
+
+CapInt **PrismX kadar geniş değil** — bilinçli olarak hafif router; init ile **tam skill kütüphanesi** diskte, agent göreve göre okur.
+
+---
+
+## 2. İlk kurulum (bir kez)
+
+```bash
+cd your-project
+npx @bcelep/capint init
+```
+
+Bu komut kurar:
+
+| Çıktı | Ne işe yarar |
+|-------|----------------|
+| `GUNLUK.md` | Günlük 6 satır — **bunu oku** |
+| `AGENT.md`, `design.md`, `AGENTS.md` | Agent sözleşmesi |
+| `skill-routing-matrix.json` | Görev → capability haritası |
+| `registry.json` | Matrix’ten türetilmiş skill listesi |
+| `skills/*` | Tam skill kütüphanesi (~115) — init ile projeye kopyalanır |
+| `workflows/forge.md` | Orta/ağır görevler için fazlı workflow |
+| `.capint/` | Manifest, kurallar |
+| IDE dosyaları | Cursor `.mdc`, `CLAUDE.md`, … (**varsayılan açık**) |
+
+IDE sync istemezsen:
+
+```bash
+capint init --no-ide-sync
+capint ide sync   # sonra
+```
+
+PrismX uyumlu preset (HANDOFF + context):
+
+```bash
+capint init --preset prismx-compatible
+```
+
+### Kurulum sonrası — hemen yap
+
+1. **Yeni IDE sohbeti aç** (eski chat eski kuralları taşır)
+2. `GUNLUK.md` dosyasına göz at (30 saniye)
+3. Chat’e ilk görevini yaz — terminal gerekmez
+
+Global CLI (opsiyonel):
+
+```bash
+npm i -g @bcelep/capint
+```
+
+---
+
+## 3. Oturum akışı (her yeni sohbet)
+
+Agent (`capint ide sync` sonrası):
+
+```
+1. AGENT.md + design.md okur           → kısa startup (2–5 satır)
+2. Görev gelince → Execution Intent    → Intent/Capability/Resolution/Memory/Plan
+3. Adaptive confirm: light → uygula; medium/heavy → kısa soru (devam/plan/analiz)
+4. Seçime göre kod / plan / analiz
+5. Capability seçimi sessiz            → skill-routing-matrix.json
+```
+
+**Senin yapman gereken:** Görevi yaz — hafif işlerde ek adım yok; orta/ağırda `devam`, `plan` veya `analiz` yeterli.
+
+### Execution Intent örneği
+
+```
+Intent: lang dosyaları uyumsuz
+Capability: localization-hub
+Resolution: skill/localization-hub
+Memory: optional
+Plan: auto          # light görev — confirm yok
+
+# medium/heavy örneği:
+Plan: confirm
+Confirm: Nasıl ilerleyeyim? (1=uygula 2=plan 3=analiz)
+Default: uygula (devam / yap / tamam da geçerli)
+```
+
+---
+
+## 4. Complexity (🟢 🟡 🔴)
+
+Agent içsel ağırlık seçer; sen emoji görmezsin ama Confirm davranışı buna bağlıdır.
+
+| Ağırlık | Davranış | Örnek |
+|---------|----------|-------|
+| 🟢 Light | Confirm yok — Intent sonrası uygula | Tek dosya typo |
+| 🟡 Medium | Kısa soru; `devam` ile uygula | Birkaç dosya, test |
+| 🔴 Heavy | Kısa soru; `plan` önerilir | Yeni modül, mimari |
+
+Auth, payment, secret → **min 🟡**.
+
+---
+
+## 5. Görev → Capability
+
+Detaylı tablo: [conventions/task-to-capability-cheatsheet.md](conventions/task-to-capability-cheatsheet.md)
+
+| Sen dersen | Capability |
+|------------|------------|
+| bug, hata, fix | systematic-debugging |
+| i18n, çeviri | localization-hub |
+| refactor | refactor-simplify |
+| geçen karar, memory | memory-retrieval |
+
+### CLI önizleme (opsiyonel)
+
+```bash
+capint route "i18n çeviri"
+capint route --json "debug login"
+capint route --verbose "..."    # Skill Plan tablosu
+capint route --list             # referans
+```
+
+---
+
+## 6. IDE entegrasyonu
+
+CapInt tek kaynak (`projections/session-start.md`) + IDE projection modeli.
+
+```bash
+capint ide sync
+capint ide sync --targets cursor,claude,antigravity
+capint ide check
+capint ide check --json
+```
+
+| IDE | `ide sync` çıktısı |
+|-----|-------------------|
+| **Cursor** | `.cursor/rules/00-capint-session.mdc` (`alwaysApply`) |
+| **Claude Code** | `CLAUDE.md` |
+| **Gemini** | `GEMINI.md` |
+| **Antigravity** | `.agents/rules/`, `CAPINT.md`, `capint-router` skill |
+| **Codex** | Root `AGENTS.md` (init stub) |
+
+**Önemli:** Projection dosyalarını elle düzenleme — kaynak `capint ide sync`; değişiklikten sonra sync yenile.
+
+### Agent kuralları gelmiyorsa
+
+```bash
+capint ide check          # hangi dosya eksik?
+capint ide sync           # yeniden yaz
+# Yeni sohbet aç
+```
+
+---
+
+## 7. Sağlık ve sorun giderme
+
+```bash
+capint doctor
+capint status
+capint audit
+capint consult "..."      # dry-run, yan etkisiz
+```
+
+### `resolution_status: not_installed`
+
+Route veya agent şunu gösterirse skill bundle eksiktir:
+
+```
+Resolution status: not_installed
+Hint: Skill "localization-hub" not installed — run capint init ...
+```
+
+**Çözüm:**
+
+```bash
+capint init               # bundle tekrar kopyalanır (mevcut dosyalar korunur)
+capint doctor
+```
+
+### `installed` ≠ Cursor skill listesi
+
+Init sonrası `skills/` altında ~115 skill **diskte** vardır. Cursor’un global “Skills” panelinde hepsi **listelenmez** — bu normal.
+
+| Durum | Anlam |
+|-------|--------|
+| `capint route` → `installed` | `skills/<ad>/SKILL.md` var ve disable değil |
+| Cursor skill picker’da yok | Beklenen; agent görevde dosyayı okur |
+| Agent skill okumuyor | `AGENT.md` activation model + route **Explanation → Read** listesi |
+
+Önizleme:
+
+```bash
+capint route "prd hazırla"
+# Explanation → Read: skills/prd/SKILL.md ...
+```
+
+Skill geçici kapatma (silmeden):
+
+```bash
+capint skill disable localization-hub
+capint skill enable localization-hub
+capint skill pin prd                # öne çıkar → registry.project_added
+```
+
+**Minimal bundle (CI):**
+
+```bash
+capint init --bundle minimal
+```
+
+Matrix/registry bozulduysa:
+
+```bash
+capint recover --list
+capint recover --latest --apply
+```
+
+### capint ui (terminal istemeyenler)
+
+Proje kökünde:
+
+```bash
+capint ui --open
+```
+
+1. Proje / doctor kontrolü  
+2. Görev yaz → route  
+3. Explanation + confirm seç  
+4. Metni chat'e kopyala  
+
+### Çakışma (conflict)
+
+Init mevcut dosyayı **asla ezmez** (capint managed block yoksa). Yeni içerik `*.capint.new.md` sidecar’da kalır — karşılaştırıp birleştir.
+
+---
+
+## 8. Matrix güncelleme
+
+```bash
+capint upgrade --dry-run    # çakışmaları gör (package wins)
+capint upgrade --apply        # yedek + güncelle
+```
+
+Custom `task_types` korunur. Apply öncesi dry-run şart.
+
+---
+
+## 9. Kaldırma
+
+```bash
+capint uninstall --dry-run
+capint uninstall --yes
+capint uninstall --yes --keep-agent --keep-ide
+npm uninstall -g @bcelep/capint
+```
+
+| Flag | Etki |
+|------|------|
+| `--keep-agent` | AGENT.md, design.md, AGENTS.md kalır |
+| `--keep-ide` | Cursor/CLAUDE projection kalır |
+| `--include-sidecars` | `*.capint.new.md` temizlenir |
+
+---
+
+## 10. Opsiyonel: yerel context (v0.4.2)
+
+Route varsayılanında değişmez.
+
+```bash
+capint memory status
+set CAPINT_LOCAL_CONTEXT=1
+capint route "memory lookup ..."
+```
+
+---
+
+## 11. Dosya yapısı (init sonrası)
+
+```
+your-project/
+├── GUNLUK.md                 ← günlük kullanıcı buradan
+├── AGENT.md
+├── AGENTS.md
+├── design.md
+├── docs/
+│   ├── kullanim-kilavuzu.md
+│   └── conventions/
+│       ├── daily-use.md
+│       └── task-to-capability-cheatsheet.md
+├── skill-routing-matrix.json
+├── registry.json
+├── skills/
+├── workflows/
+├── .capint/
+│   ├── scaffold-manifest.json
+│   └── rules/core.md
+└── .cursor/rules/00-capint-session.mdc
+```
+
+---
+
+## 12. Sık sorulan sorular
+
+**CapInt kullanmak zor mu?**  
+Hayır — init’ten sonra chat yeterli. Terminal sadece kurulum/sorun için.
+
+**Her görevde `capint route` çalıştırmalı mıyım?**  
+Hayır. Agent IDE kurallarından Intent üretir. Route maintainer/debug içindir.
+
+**Skill adını bilmem gerekir mi?**  
+Hayır. Matrix + agent seçer.
+
+**Init yaptım, agent hâlâ eski davranıyor?**  
+Yeni sohbet aç. `capint ide check` → `ide sync`.
+
+**PrismX ile fark?**  
+CapInt daha hafif: capability router + minimal bundle. Tam playbook kütüphanesi yok.
+
+**Hangi IDE en iyi?**  
+Cursor: `alwaysApply` `.mdc` ile en tutarlı oturum başlangıcı.
+
+---
+
+## 13. İlgili dokümanlar
+
+| Doküman | Konu |
+|---------|------|
+| **GUNLUK.md** | Günlük 3 adım (herkes) |
+| conventions/daily-use.md | Chat şablonları + senaryolar |
+| conventions/task-to-capability-cheatsheet.md | Görev → capability |
+| execution-intent-contract.md | JSON şema (maintainer) |
+| manifest-schema.md | Uninstall/upgrade manifest |
+
+---
+
+*Son güncelleme: 2026-05-30 · @bcelep/capint 0.4.2*