Kavramlar

ivralo'nun çalıştığı yer

Çalışma alanı

ivralo'nun üzerinde çalıştığı tek dizin (workspace). ivralo bir git repo'sunun içinde başlatılırsa çalışma alanı o repo'dur: hiçbir şey kopyalanmaz, ivralo kendi durumunu .ivralo/ klasöründe tutar ve bu klasörü .git/info/exclude'a ekler. Repo dışında başlatılırsa çalışma alanı ana dizindeki workspace/ klasörüdür. IVRALO_WORKSPACE ikisini de geçersiz kılar. Ayrıntılar: Repo'da çalışmak.

Ana dizin

ivralo'nun kendi dosyalarını tuttuğu dizin (home): gelen skill'ler, brand.json, veritabanının compose dosyası, ana dizinin .env'i ve trusted.json ile API token'ı gibi kayıtlar. IVRALO_HOME hangi dizini gösteriyorsa ana dizin odur; ayarlı değilse ivralo'yu başlattığınız checkout'tur. Kurulu program, bir ana dizinin başlangıç dosyalarının kopyalarını içinde taşır; ivralo init --home <dizin> bunları sizin dizininize yerleştirir. Ayrıntılar: Hızlı başlangıç.

Geri dönüş ana dizini

ivralo'ya açıkça söylenmemiş, yalnızca bulunmuş bir ana dizin (fallback home). Örneğin ivralo'nun içinde çalıştığı checkout; klonlanmış herhangi bir repo da tam böyle görünebilir. Bu yüzden dosyaları size değil, klasörün kendisine ait sayılır: .env'i, skill'leri ve ayar dosyaları okunmaz, permissions.json'ı yalnızca reddedebilir ve içine yazacak her komut reddedilir. IVRALO_HOME'u export ettiğinizde gerçek bir ana dizin olur. Ayrıntılar: Checkout'tan çalıştırmak.

Güvenilen klasör

ivralo içindeki dosyalara güvenip güvenmediğinizi sorduğunda evet dediğiniz çalışma alanı. Repo'nun kendi tanımları yalnızca güvenilen bir klasörde devreye girer: IVRALO.md'deki komutlar, dil sunucuları, .ivralo/permissions.json'daki izin satırları ve .ivralo/.env. Cevap klasörün içinde değil, ana dizindeki trusted.json'da, klasörün yoluyla saklanır; ivralo trust ile kaydedilir ya da geri alınır. Ayrıntılar: Repo'da çalışmak.

IVRALO.md

Repo'nun kökünde duran ve projenin nasıl işlediğini ivralo'ya anlatan dosya; yoksa AGENTS.md okunur. Birkaç bölümünü kod okur: örneğin projenin kontrolleri için # Commands, log tutan ve git'in yok saydığı klasörler için # Evidence. Geri kalan her şey, projenin kendi talimatları olarak her ajana verilir. Bu dosya ivralo'nun yapabileceklerini yalnızca daraltabilir; izinlere karar veren hiçbir kod onu okumaz. Ayrıntılar: Repo'da çalışmak.

Ajanlar

Ana ajan

Konuştuğunuz ajan. İşin çoğunu kendisi yapar, ekibin yetkilerini aynı onaylar altında kullanır ve işi yalnızca temiz bir bağlam ya da daha dar bir yetki gerektiğinde bir uzmana devreder. E-postanız ya da Google gibi bir hesabı okuma yetkisi hiçbir zaman onda olmaz; bu yetki hesabın sahibi olan uzmanda kalır. Ayrıntılar: Repo'da çalışmak.

Preset

Bir ajanın tarifi: coder ya da investigator gibi bir anahtar, bir görünen ad, bir yetki kümesi, ajanın ne işe yaradığını anlatan tek cümlelik bir ipucu ve araç çağrıları için bir sınır. Preset'lerin kendi prompt'u yoktur; uzmanlık skill'lerde birikir. ivralo agents hepsini listeler.

Uzman

Bir preset'ten kurulan ajan (specialist): bir model, kendi sürecinde çalışan bir Python worker'ı ve skill rafının tamamı, kendi skill'leri en önde. Code Engineer (coder) kodu düzenler; Incident Investigator (investigator) bir incident'ın kanıtını okuyup rapor yazar. Birkaç Code Engineer aynı anda, her biri kendi git worktree'sinde çalışabilir. Ayrıntılar: Paralel coder'lar.

Skill

Markdown olarak paketlenmiş bilgi: bir SKILL.md ile isteğe bağlı scripts/ ve references/ klasörlerinden oluşan bir dizin. Bir skill, bir tekniğin ne zaman kullanılacağını, kesin kuralları ve çalışan kod örneklerini öğretir. ivralo 18 skill ile gelir; sizin kurduğunuz ya da yazdığınız skill'ler ana dizindeki ikinci bir rafta, skills.local/ içinde tutulur.

Neye izin var

Yetki

domain.grade biçiminde adlandırılan bir izin (grant), örneğin code.edit, shell.full ya da git.push. Her uzmanın sekiz yetkilik bir temeli vardır; Python çalıştırmak, dosya okuyup yazmak, size soru sormak ve işi bir ekip arkadaşına devretmek (team.run) bunların arasındadır. Preset, bunun ötesinde neye ihtiyacı olduğunu kendisi bildirir. Yetki, bir ajanın hangi araçlara sahip olacağını belirler; bir çağrının yine de sorup sormayacağını asla belirlemez. Yetkiler ne derse desin, her düzenleme onayınızı ister. Ayrıntılar: Onaylar.

Mod

Başında kimsenin olmadığı çalıştırmalar için tanımlı bir yetki kümesi. Varsayılan geliştirici modu, bu çalıştırmalara soru sormayı gerektiren hiçbir yetki vermez; bu yüzden sormak yerine reddederler. Server modu iki yetki ekler: başında kimse olmayan bir çalıştırma commit atabilir ve taslak bir pull request açmak için ivralo'nun kendi açtığı branch'i push'layabilir. Mod repo'ya göre değil, ana dizinin .env'indeki IVRALO_MODE ile belirlenir. Ayrıntılar: Server modu ve incident'lar.

Changeset

Bir turdaki düzenlemelerin tek bir birim olarak ele alınması. Düzenlemeler ağacınızın hazırlanmış bir kopyasında yapılır, orada projenin kontrolleriyle doğrulanır, sonra ya hepsi birden ağacınıza uygulanır ya da hepsi atılır. Siz açmadıkça kapalıdır ve her düzenleme yine onay ister. Ayrıntılar: Changeset'ler.

Incident'lar ve uzun işler

Bundle

Çalışma alanının içinde, bir incident'ın kanıtlarını tutan klasör: log'lar, bir deploy log'u, metrikler, alarmın kendisi. İçindeki her dosya kanıttır, dışındaki hiçbir şey kanıt değildir. ivralo bir bundle'ın içine hiçbir zaman yazmaz; tek istisna, API üzerinden gelen bir alarmın önce tek dosyalık küçük bir bundle olarak yazılmasıdır. Ayrıntılar: Kanıt bundle'ı.

Rapor

Bir incelemenin sonunda çıkan belge: .ivralo/incidents/<id>/ altında report.md, yanında report.json ve digest.json. Gözlenenle çıkarılanı ayrı tutar, içindeki her sayıyı kod hesaplar. Sonuç, dört sonuçtan biridir ve buna Investigator'ın yargısına bakarak kod karar verir. Ayrıntılar: Raporu okumak.

Job

Uzun süren bir iş birimi: bir plan çalıştırması, tek bir istek ya da bir alarmın incelemesi gibi. Kaydı PostgreSQL'de tutulduğu için onu başlatan süreç bittikten sonra da yaşar. Durumu queued, running, waiting_for_approval, blocked arasında ilerler ve sonunda completed, failed ya da cancelled olur. Bir kişinin cevabını gerektiren bir çağrıya gelen job o soruda bekler ve biri cevap verince kaldığı yerden devam eder. Ayrıntılar: Alarm alımı.

Oturum

Bir konuşma (session): aynı geçmişi paylaşan ve PostgreSQL'de saklanan çalıştırmalar dizisi. Aksi belirtilmedikçe iki terminal aynı etkin oturumu kullanır; her incident incelemesi ise bundle'ın adını ve o anın zamanını taşıyan kendi oturumunu açar. ivralo sessions oturumları listeler, -s <id> birini seçer. Ayrıntılar: Oturum.