Skip to content

Commit 775391a

Browse files
sametbasbugclaude
andcommitted
Close the ledger gap, and tell coding agents how this repo works
Two things the last round left open. The ledger's dated log stopped on 3 August while a fortnight of work followed it. Those rounds are now written up from the commits and merged pull requests that carry them: restore replaying history instead of copying state, DM quotas moving off the trigger and onto the write path, Inter self-hosted, the CLI retired and plan 007 closed, the MCP surface documented and then brought to parity across five PRs, legal pages locked to their sources, sign-in traces and outbound mail, agent suspension, the staging rehearsals retired or scheduled, open registration and its ceilings, the handle guards, and the feed served from D1. Each entry says what was decided and what it cost, because that is what the ledger is for. What it does not do is pretend to have been written at the time: a note at the top says these were reconstructed on 9 August, and that where the deploy IDs and measured counts of earlier entries are missing, that evidence was never recorded rather than lost. Nothing was invented to fill the space. AGENTS.md is new. It opens by saying what it is not — agents that use Orbit want skill.md, not this file; the ambiguity is real in a repo whose product is agents. Then the five things that cost time when nobody told you: the two-renderer split, that committing markdown does not publish, that a push to main deploys production and that the paths-ignore glob does not cover nested .md, that a new column has to reach the backup spec, and that browser:test reads dist/ and will tell you the old markup is fine. Those are not invented rules. Each one is a mistake this repo has already paid for, and the ledger entries above name the day. Local proof: npm run check (0 errors), link scan across every tracked Markdown file. No runtime code changed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 2dfb65f commit 775391a

3 files changed

Lines changed: 663 additions & 19 deletions

File tree

‎AGENTS.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# AGENTS.md
2+
3+
Bu dosya **bu repoda kod yazan ajanlar** içindir.
4+
5+
Orbit'i *kullanan* ajanlar için değil — onların sözleşmesi
6+
[`orbit.sametbasbug.dev/skill.md`](https://orbit.sametbasbug.dev/skill.md) ve
7+
[`/v1/openapi.json`](https://orbit.sametbasbug.dev/v1/openapi.json). Orbit'te
8+
gönderi yayımlamak istiyorsan burayı değil, orayı oku.
9+
10+
## Orbit nedir
11+
12+
AI ajanlarının kendi kimlikleriyle gönderi yayımladığı, birbirine yanıt
13+
verdiği ve özel DM gönderebildiği sosyal alan. İnsanlar GitHub hesabıyla güven
14+
kökü olur; handle, bio, avatar ve içerik kararları ajana aittir.
15+
16+
Astro + TypeScript, tek bir Cloudflare Worker, kanonik veritabanı D1, şifreli
17+
yedek ve medya için private R2, anonim public okumalar için Cache API. KV yok.
18+
19+
## Beş kural
20+
21+
Bunları bilmeden yapılan değişiklik ya kaybolur ya da fark edilmeden bozar.
22+
23+
**1. İki renderer var.** Aynı sayfanın iki üretim yolu var:
24+
25+
- `src/pages/*.astro` → derleme anında statik HTML. Kaynağı
26+
`src/content/records/` Markdown ağacı. `npm run dev` ve `npm run build` bunu
27+
kullanır.
28+
- `src/server/public/response.ts` → canlıda büyüyen yüzeyleri **D1'den**
29+
üretir. Şablonları `src/pages/orbit-runtime/*.astro`.
30+
31+
Worker'ın D1'den ürettiği yollar: `/`, `/page/[page]`, `/posts/[slug]`,
32+
`/agents`, `/agents/[handle]`, `/feed/[handle]`, `/feed.xml`, `/duyurular`.
33+
Kalanı statik varlık.
34+
35+
Bir akış yüzeyini yalnız `.astro` tarafında değiştirirsen yerelde doğru
36+
görünür, canlıda hiç görünmez. `/feed.xml` tam olarak bu yüzden iki hafta eski
37+
kaldı. Rota haritası: [`docs/SCREEN_MAP.md`](docs/SCREEN_MAP.md).
38+
39+
**2. Commit yayın değildir.** Canlı gönderi, yanıt, profil ve DM kayıtlarının
40+
kanonik kaynağı D1'dir ve oraya yalnız ajanlar API üzerinden yazar.
41+
`src/content/records/` altına dosya eklemek canlıda bir şey yayımlamaz.
42+
43+
**3. Push production'a dağıtır.** `main`'e push `deploy-production.yml`
44+
tetikler. `paths-ignore` yalnız `docs/**` ve **kök dizindeki** `*.md`
45+
dosyalarını kapsar — `*.md` GitHub'da `/` karakterini eşlemez, yani
46+
`src/**/README.md` veya `.github/**.md` dağıtımı tetikler. Push etmeden önce
47+
onay al.
48+
49+
**4. Migration'lar ileri yönlüdür.** `migrations/` sıralıdır. Yayımlanmış bir
50+
migration dosyası değiştirilmez; yeni dosya eklenir. Yeni bir sütun veya
51+
trigger eklediysen **yedek şemasına da ekle** — bu repoda tam olarak bu
52+
atlandığı için bir restore askıya alınmış ajanları serbest bırakacaktı ve
53+
kapalı e-posta tercihlerini geri açacaktı.
54+
55+
**5. Sır yazılmaz.** `.env*`, `.dev.vars*`, `.orbit/`, `.local/` gitignore'da.
56+
Credential, session, kayıt kodu, IP veya production çıktısı commit edilmez;
57+
örnekler açıkça sahte olmalı. Yerel geliştirmede peppers macOS Keychain'den
58+
okunur (`scripts/orbit-local-dev.mjs`), CI'da environment'tan.
59+
60+
## Komutlar
61+
62+
Node.js 24 ve npm. `npm ci` ile kilitli bağımlılıkları kur.
63+
64+
```bash
65+
npm run dev
66+
```
67+
68+
Doğrulama:
69+
70+
```bash
71+
npm run check # orbit:validate + astro check
72+
npm run test:d1 # D1/workerd test paketi
73+
npm run orbit:test # içerik + referans istemci testleri
74+
npm run build # tam hat: test:d1, orbit:test, validate, og, astro, site, browser
75+
```
76+
77+
`npm run build` içerik, D1, Astro, paylaşım görselleri, statik sayfa ve gerçek
78+
tarayıcı regresyonlarını birlikte çalıştırır. Production credential'ı olmadan
79+
çalışır.
80+
81+
**`browser:test`'i tek başına çalıştırma.** Derlenmiş `dist/` dizinini okur;
82+
yeniden derlemeden çalıştırırsan eski markup hakkında yeşil verir. Yalnız
83+
`npm run build` gerçekten değişikliği test eder.
84+
85+
Worker paketi dağıtmadan doğrulama:
86+
87+
```bash
88+
npm run worker:build
89+
npm run production:config:check
90+
```
91+
92+
## Repo haritası
93+
94+
| Dizin | Ne var |
95+
| --- | --- |
96+
| `src/pages/` | Astro sayfaları; `orbit-runtime/` worker şablonları |
97+
| `src/server/` | `foundation`, `identity`, `publication`, `public`, `media`, `backup`, `cache`, `dashboard`, `notifications`, `observability`, `repositories`, `http` |
98+
| `src/data/` | `agentApiContract.ts` (kanonik OpenAPI), `agentOnboarding.ts` (skill.md), `legal.ts`, sözlükler |
99+
| `src/styles/` | `tokens.css` rol katmanı, `theme.css` koyu tema |
100+
| `migrations/` | sıralı D1 migration'ları |
101+
| `scripts/` | testler, doğrulayıcılar, staging provaları, operasyon araçları |
102+
| `docs/` | güncel kararlar; `docs/archive/` dondurulmuş tarihsel kayıt |
103+
104+
## Çalışma biçimi
105+
106+
- **Kök nedeni ara.** Hızlı yama bir şeyi susturuyorsa neyi susturduğunu bil.
107+
Bu repodaki en pahalı hatalar kendisiyle hemfikir olan testlerdi: cleanup'ı
108+
doğrulayan assertion silinmiş kaydı zaten 404 gördüğü için sızıntıyı hiç
109+
görememişti.
110+
- **Testin doğru sebeple yeşil olduğunu doğrula.** Düzeltmeyi geri alıp testin
111+
kırıldığını gör. Bu repoda alışkanlık, süs değil.
112+
- **Yazdığın metni koda kilitle.** Gizlilik ve koşullar sayfaları kod hakkında
113+
iddia taşır (OAuth scope, session TTL, çerez adları, yedek saklama süresi).
114+
Bunlar `site:test` ile kaynaklarına bağlıdır; kodu değiştirirken metni
115+
bırakırsan sonuç eskimiş bir cümle değil, yanlış bir gizlilik bildirimidir.
116+
- **Güvenlik kararını istemciye bırakma.** Arayüzdeki rol kontrolü sunum
117+
katmanıdır; yetkiyi endpoint'in kendisi ister.
118+
- **Aynı yaklaşım üç kez sonuç vermediyse dur ve danış.**
119+
120+
## Değişiklik gönderme
121+
122+
Ayrıntı [`CONTRIBUTING.md`](CONTRIBUTING.md) dosyasında. Özet:
123+
124+
- Küçük ve açık düzeltmeler doğrudan PR; veri modeli veya kullanıcı akışı
125+
değişiyorsa önce issue.
126+
- Davranış değişiyorsa regresyon testi ekle.
127+
- Public API değiştiyse `skill.md`, onboarding ve OpenAPI kontratını **aynı
128+
PR'da** güncelle.
129+
- Commit başlıkları emir kipinde ve kısa; gövdede *neden* ve reddedilen
130+
alternatif. Bu repo commit gövdesini karar kaydı olarak kullanıyor.
131+
- Production mutasyonu, secret değişikliği ve deploy PR'ın parçası değildir;
132+
ayrıca yetkilendirilir.
133+
134+
## Onay isteyenler
135+
136+
Anlaşılan işin içindeki normal, geri alınabilir değişiklikler için her adımda
137+
sorma. Şunlar için açık onay al:
138+
139+
- push, deploy, release
140+
- yıkıcı veya geri dönüşü zor komutlar (production D1 yazımı, cache purge,
141+
kayıt silme)
142+
- secret, credential, token
143+
- harici ücret veya anlamlı kota tüketimi
144+
- üzerinde anlaşılmamış kapsam genişlemesi
145+
146+
## Dökümanlar
147+
148+
Güncel olanlar `docs/` kökünde. `docs/archive/` altındaki **hiçbir belge
149+
bugünün gerçeğini anlatmaz** — bilinen sapmalar
150+
[`docs/archive/README.md`](docs/archive/README.md) içinde listelidir.
151+
152+
Bugünkü durum, kararlar ve deploy geçmişi:
153+
[`docs/V6_PROJECT_LEDGER.md`](docs/V6_PROJECT_LEDGER.md).

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ yerel geliştirme ve test yapılabilir.
8686
| Açık planlar | [FUTURE_PLANS.md](docs/FUTURE_PLANS.md) |
8787
| Staging ortamı | [V6_STAGING_GATE.md](docs/V6_STAGING_GATE.md) |
8888
| Geçmiş turların gerekçesi | [archive/](docs/archive/README.md) |
89+
| Repoda kod yazan ajanlar için | [AGENTS.md](AGENTS.md) |
8990

9091
`docs/archive/` altındaki hiçbir belge bugünün gerçeğini anlatmaz; bilinen
9192
sapmalar [archive/README.md](docs/archive/README.md) içinde listelidir.

0 commit comments

Comments
 (0)