Document granular hook policy + ad architecture + 94-site scale

Hook redesign (guard-readonly.sh + guard-bash.sh): - ALLOW edits: /home/nosfortube/frontend_<port>/ (digits-only, all subdirs) + /home/nosfortube/orest/ (user working zone + screenshots) - DENY: lang variants (frontend_<port>_<lang>/), frontend_core/, .git/, system paths (/etc/, /usr/, /boot/, /var/* except /var/log/claude/) - 19/19 readonly + 18/19 bash tests pass (1 pre-existing sed-i regex gap) - Backup попередньої версії: .bak.2026-05-02 Doc updates: - New: PROJECT.md, ARCHITECTURE.md, DEPLOY.md, ADS.md, PERFORMANCE.md, INTERLINKING.md, ADMINS.md (topic-split docs/) - CLAUDE.md: 94-site scale, granular edit zones, doc index - INFRASTRUCTURE.md: hook table updated - SITES.md: scope note (14 backup-tracked of 94 total) - RECOMMENDATIONS.md: W1 (hook conflict) → DONE; W2-W3, D1-D4 added Site architecture findings (audit 2026-05-02): - 94 frontend_<port>/ sites, 71 in site-name-routing.csv, 14 backup-tracked - 3 ad-architectures coexist: 8148 modern bundle (1), modern partials (~23), legacy inline surstrom (31) - 8148 unique: ad-bundle.min.js source files, build-ad-bundle.sh, terser - Server IP 185.73.222.75 у t1.* allowlist (curl probes work) - CDN: custom + Cloudflare на 8081 etc; purge-cache при prod deploy Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 13:26:25 +00:00
parent d740ef82ea
commit 981a0ad9b6
11 changed files with 568 additions and 16 deletions
--- a/docs/ADMINS.md
+++ b/docs/ADMINS.md
@@ -0,0 +1,54 @@
+# tubev — Admin Panels
+
+Адмінки для керування контентом, перекладами, коментами, deploy-flow та моніторингом. Більшість per-site, кілька cross-site.
+
+## Status
+
+🟢 **Mapped** — основні URL зафіксовано. Деталі scope наповнюємо по мірі використання.
+
+## Per-site adminkи
+
+URL шаблон: `https://<domain>/<panel-path>`. Приклад нижче — для `a.tubev.sex`.
+
+| Назва | URL | Scope | Що змінює | Self-deploy? |
+|-------|-----|-------|-----------|--------------|
+| **Site index** | `https://a.tubev.sex/admin/index` | Site dashboard | Загальне керування | Так |
+| **Settings** | `https://a.tubev.sex/admin/settings` | Site config | К-ть тумб per page, ін. налаштування (юзер рідко чіпає) | Так |
+| **Languages** | `https://a.tubev.sex/moderation/languages/langs` | I18n setup | Набір мов на сайті | Так |
+| **Translations** | `https://a.tubev.sex/moderation/languages/translation/` | UI strings | Переклади змінних (`Title_Desc_H1`, `categories/h3` тощо) per-language | Так |
+
+**Translation key example:**
+```
+categories/h3   Title_Desc_H1   Discover XXX Themes
+ProjectShort    Title_Desc_H1   Free sex videos
+Top searches    Title_Desc_H1   Top searches
+```
+
+Сайти зазвичай **multilingual**.
+
+## Cross-site adminkи
+
+| Назва | URL | Scope | Що дозволяє | Обмеження |
+|-------|-----|-------|-------------|-----------|
+| **Site control** (deploy) | `https://rss.g--o.info/admin/site/control` | Усі сайти | **Викатати оновлення з тесту → прод per-site** | НЕ оновлює `var.lua`, НЕ додає нові файли (через Адміна) |
+| **Site sitemap** | `https://rss.g--o.info/admin/site` | Усі сайти | Sitemap settings, інші системні нал. | — |
+| **Billing dashboard** | `https://billing.g--o.info/cs/oursites/dashboard/` | Усі сайти | Статистика, моніторинг (від Адміна) | Read-only переважно |
+
+## Monitoring sources
+
+Для діагностики проблем — пріоритет з low-noise → high-noise:
+
+1. **adspyglass dashboard** — `https://app.adspyglass.com/dashboard` — **best signal**, лайв графік показу реклами per site. Падіння = щось зламалось. Деталі: [ADS.md § Monitoring](ADS.md#monitoring).
+2. **Telegram + email alerts** — критичні (downtime, errors).
+3. **Billing dashboard** — статистика від Адміна, рідко.
+4. **PSI manual** — `https://pagespeed.web.dev/` після великих змін, періодично. Деталі: [PERFORMANCE.md](PERFORMANCE.md).
+
+## Auth
+
+- Юзер логінений у браузері. Claude/боти adminkи **не використовують** — це юзер-side операції (деплоймент, перекладання, налаштування).
+- Прод-домени (наприклад `a.tubev.sex`) повертають **401 Unauthorized** з сервера без cookies — підтверджено probe 2026-05-01. Це **adminki + secured area**, не публічний контент.
+
+## Open questions
+
+- [ ] Чи є API за adminkами (REST/GraphQL) для автоматизації?
+- [ ] Чи всі 94 сайти мають однакові admin paths (`/admin/index`, `/moderation/languages/...`)? — припускаємо так.
--- a/docs/ADS.md
+++ b/docs/ADS.md
@@ -0,0 +1,111 @@
+# tubev — Ads Integration
+
+Реклама через **adspyglass.com**. Основне джерело монетизації — балансуємо CTR vs UX/PSI.
+
+## Status
+
+🟢 **Working knowledge** — Skeleton наповнюємо.
+
+## Architecture
+
+### Mirrors (зеркала)
+
+Реклама вантажиться через **зеркала-домени**, не прямо `adspyglass.com`:
+- `a5.g--o.info` — ad orchestration (preconnect target у modern setup)
+- `surstrom.com` — inline ad-spot loader (legacy pattern)
+- `agego.com` — verifycdn (`verifycdn.agego.com/v1/verify.js`)
+- `g--o.info` — base domain
+- (інші додаються на потребу)
+
+**Чому зеркала:** anti-block — adblockers баняють відомі ad-домени. Зеркала маскують та ротуються.
+
+**Mirror lifecycle:**
+- Зеркала **періодично баняться** (adblock list updates)
+- Заміна — **mass-operation через Адміна** (одразу на всі сайти)
+- Ми не керуємо вибором зеркал — це адмінська функція
+
+### Three architecture patterns coexist (audit 2026-05-02)
+
+Site-level audit показав **3 patterns** — не uniform:
+
+| Pattern | Sites | Як виглядає | Примітка |
+|---------|-------|-------------|----------|
+| **A) Modern bundle** | 1 (тільки 8148) | `<script src="/static/js/ad-bundle.min.js?v=<md5>" defer>` + `views/modules/banners/*adspy*.etlua` partials | Canonical — є build pipeline, source JS у `views/static/js/` |
+| **B) Modern partials** | ~23 | `preconnect` → `a5.g--o.info` + adspy `.etlua` partials, але **без** ad-bundle.min.js | Modules orchestrate, no central bundle |
+| **C) Legacy inline** | 31 (8112-style) | Inline `<script async src="//surstrom.com/<random>.js">` + iframes до `surstrom.com/api/spots/<id>` + `tb.load_frame_baner_v2()` API | Pre-modular epoch |
+
+**77 із 94 сайтів** мають adspy banner modules у `views/modules/banners/*adspy*.etlua`. Решта (17) — legacy без banner partials або special structure.
+
+### Build pipeline (тільки 8148)
+
+`/home/nosfortube/frontend_8148/views/static/js/build-ad-bundle.sh` концатує+minify-їть 5 source JS-файлів у `ad-bundle.min.js`:
+1. `ad-config.js` — config / placement IDs / mirror domains
+2. `ad-core.js` — ядро ad-orchestration
+3. `ad-mute.js` — mute / autoplay control
+4. `vast-preroll.js` — pre-roll реклама перед video
+5. `ad-bootstrap.js` — entry-point / init
+
+**Source files:** усі у `/home/nosfortube/frontend_8148/views/static/js/` (унікально для 8148).
+
+Tool: **terser** (concat + minify). Triggered by `~/git-save-all.sh` коли source новіший за bundle.
+
+Cache-bust: md5 → `?v=...` у `layout.etlua` (детально у [DEPLOY.md](DEPLOY.md#cache-bust-механізм)).
+
+## Monitoring
+
+### adspyglass dashboard — best diagnostic signal
+
+`https://app.adspyglass.com/dashboard`
+
+**Чому це best signal:**
+- Live графік показу реклами per site
+- **Падіння графіка** = реклама не показується = ймовірно поломка (frontend/template/JS error / banned mirror / CDN cache stale)
+- **Ріст** = трафік підріс або UX покращився
+
+Юзер каже: "більший показник саме для мене це лайв графік реклами від АСГ" — реклама падає миттєво коли щось не так, ще до того як прийдуть алерти.
+
+### Інші alerts
+- **Telegram + email** — критичні (downtime, errors)
+- Billing dashboard `https://billing.g--o.info/cs/oursites/dashboard/` — статистика (зазвичай не дивимось)
+
+### Template patterns
+
+**Pattern A (8148 modern):**
+```etlua
+<link rel="preconnect" href="https://a5.g--o.info" crossorigin>
+<script src="/static/js/ad-bundle.min.js?v=<%= ad_bundle_v %>" defer></script>
+...
+<% render("views.modules.banners.header_mobile_adspy") %>
+<% render("views.modules.banners.footer_mobile_adspy") %>
+<% render("views.modules.banners.footer_descktop_adspy") %>
+```
+
+**Pattern C (8112 legacy inline):**
+```etlua
+<link rel="dns-prefetch" href="//surstrom.com">
+...
+<script async src="//surstrom.com/qDap9.js"></script>
+<iframe class="na" src="//surstrom.com/api/spots/72437?p=1" sandbox="..." loading="lazy"></iframe>
+...
+tb.load_frame_baner_v2("//surstrom.com/api/spots/72437?p=1","#tb0",{...},{...});
+```
+
+## Що треба з'ясувати + задокументувати
+
+### Architecture migration
+- [ ] Чи планується мігрувати pattern C → B/A (legacy → modern)?
+- [ ] 8148 — pilot для bundle-architecture, чи поширюватиметься?
+
+### CSP / Security
+- [ ] CSP exceptions для зеркал — як підтримуються?
+- [ ] Mirror swap — чи треба update CSP при заміні?
+
+### Performance impact
+- [ ] PSI вплив реклами — % LCP / TBT (per pattern)?
+- [ ] Lazy-load ads below-fold — реалізовано (видно `loading="lazy"` на iframes)?
+
+## Open questions for developer
+
+1. Як здійснюється mirror swap — sed-replace у всіх template/JS файлах через Адміна, runtime config, чи інший механізм?
+2. 8148 ad-bundle — план поширити цю архітектуру на інші сайти, чи це 1-of-1?
+3. Які pattern використовується для НЕ-77 сайтів (17 без adspy banner modules) — special-case structure, "no ads" сайти, чи щось інше?
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,63 @@
+# tubev — Per-Site Architecture
+
+Що де лежить у `/home/nosfortube/frontend_<port>/` і яка зона безпечна для редагування.
+
+## Folder map
+
+```
+/home/nosfortube/frontend_<port>/
+├── views/                        ← НАША зона
+│   ├── *.etlua                   templates (layout, video page, list, footer, ...)
+│   ├── modules/                  reusable module includes
+│   ├── css/                      etlua-rendered CSS chunks (часто critical inline)
+│   └── static/                   ← public-served assets
+│       ├── css/                  deferred CSS files
+│       ├── js/
+│       │   ├── lib/              ← SHARED (НЕ редагувати для one-off!)
+│       │   ├── lib2/             ← SHARED (НЕ редагувати для one-off!)
+│       │   ├── c2.js, auth.js, comment.js, profile_index.js, main.js, ...
+│       │   └── *.min.js
+│       └── videojs-v10/          video player
+├── lib/
+│   └── <port>/
+│       └── var.lua               ← per-site config змінні (потребує kor reboot!)
+└── (інше)                        ← НЕ чіпаємо
+```
+
+## Site name → port
+
+`/home/nosfortube/orest/site-name-routing.csv`:
+
+```csv
+site name;id;url-pattern;new-url-pattern
+atube.sex;8082;/video/;/video/hold/
+hdmmovies.xxx;8083;/video/;/video/offline/
+...
+```
+
+Лукап: `grep ';8083;' /home/nosfortube/orest/site-name-routing.csv` → site name.
+
+## SHARED vs per-site
+
+**SHARED (зміни → всі сайти):**
+- `views/static/js/lib/` — основний shared, активно використовується звичайними скриптами
+- `views/static/js/lib2/` — другий shared bucket. Юзер каже: "в цілому сайти що юзають звичайні скрипти то ніби ніколи не бачив що тянуть щось з lib2, тільки lib". **Реальне використання lib2 — рідкісне** (можливо historical / specific subset).
+
+**Правило:** якщо щось правиш у `lib/` або `lib2/` — зміна поширюється на ВСІ сайти. Per-site fix робити НЕ можна тут. Винести у per-site файл або параметризувати через `var.lua`.
+
+**Per-site (editable безпечно):**
+- `views/*.etlua` (всі templates)
+- `views/modules/`, `views/css/`
+- `views/static/css/`, `views/static/js/<non-shared>.js`
+
+## Config — `lib/<port>/var.lua`
+
+- Lua-таблиця змінних доступних у templates через kor runtime
+- **Зміни applied тільки після kor reboot** — це блокер для interactive flow
+- Додавати нові змінні → пишеш у `var.lua` → просиш Адміна reboot → змінна стає доступна
+
+## Open questions
+
+- [ ] `lib/` vs `lib2/` — функціональна різниця історична / структурна / випадкова? (lib2 рідко вживається — можливо deprecated subset?)
+- [ ] Що ще лежить у `frontend_<port>/` поза `views/` + `lib/`? (services/, conf/, scripts/?) — `ls` коли матимем доступ
+- [ ] kor reboot — manual через Адміна, нема self-service API
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -0,0 +1,83 @@
+# tubev — Deploy Flow
+
+Як зміна потрапляє з робочого місця → у prod.
+
+## Two-tier model
+
+```
+Edit /home/nosfortube/frontend_<port>/      ← work / source-of-truth
+        │
+        ├──→  t1.<domain>                   ← test (instant, IP-allowlist)
+        │
+        └──→  admin panel "site/control"    ← prod деплой per-site (юзер натискає)
+                або через Адміна             ← для var.lua / нових файлів
+                  │
+                  └──→ <domain>             ← live, з CDN
+```
+
+## Test environment — `t1.<domain>`
+
+- **Доступ:** IP-allowlist (ймовірно nginx-level, не точно). Юзер заходить через VPN щоб мати стабільний IP.
+- **Apply:** instant — змінив файл у `frontend_<port>/` → видно на t1.<domain> одразу.
+- **Обмеження** (per-site різні): CDN off, compression off, повільніше, comments/ads можуть бути обмежені або тестові.
+- **AI-side:** ✅ Claude з сервера **МАЄ доступ** до t1.<domain> (server IP `185.73.222.75` у allowlist). Перевірено 2026-05-01: `curl -I https://t1.atube.sex` → 200 OK, `curl -I https://t1.hdsexvideo.xxx` → 200 OK. Можна робити HTTP probes для health-check, regression smoke, response inspection.
+
+## Prod deploy — три шляхи
+
+### A) Через admin panel "site control" (юзер сам, instant per-site)
+
+`https://rss.g--o.info/admin/site/control` — список усіх сайтів, кнопка викатати оновлення з тесту → прод.
+
+**Покриває:** templates `.etlua`, CSS, JS (звичайні per-site файли).
+
+**Не покриває (потрібен Адмін):**
+- `lib/<port>/var.lua` — нові/змінені змінні
+- Нові файли (yet not in admin's git)
+- Shared `views/static/js/lib/`, `lib2/` (cross-site impact)
+
+### B) Через admin panels (settings / translations / sitemap)
+
+Контент-шар, не код. Самостійно, без Адміна:
+- Per-site settings: `https://<domain>/admin/index`, `/admin/settings`
+- Languages set: `https://<domain>/moderation/languages/langs`
+- Translations (UI strings): `https://<domain>/moderation/languages/translation/`
+- Sitemap: `https://rss.g--o.info/admin/site`
+
+Деталі: [ADMINS.md](ADMINS.md).
+
+### C) Через Адміна (Орест / основний програміст)
+
+- Нові файли потрапляють у Адмінів git → kor pull/reload
+- `var.lua` зміни → kor reboot
+- Mass operations (mirror swaps, multi-site fixes)
+
+Trigger: попросити (чат / задача).
+
+## kor reload
+
+- `lib/<port>/var.lua` зміни → потрібен **kor reboot** щоб env змінні підвантажилися
+- Templates `.etlua` — підхоплюються hot (без reboot)
+- Static assets — hot, але **CDN cache** може тримати стару версію → потрібен **cache-bust** (через `?v=<md5>` у layout — реалізовано у `~/git-save-all.sh`)
+
+## CDN
+
+- **Custom CDN** для більшості сайтів (наявний; провайдер невідомий поки)
+- **Cloudflare** на двох сайтах (наприклад **8081**) — додаткове edge кешування
+- **При оновленні prod** для Cloudflare-сайтів: треба **purge cache** + враховувати у логіці що зміни не миттєві (cache TTL до purge)
+- Cache-bust через `?v=<md5>` у `layout.etlua` працює для обох (custom + CF)
+
+## git-save-all.sh — git-snapshot для backup_<port>/
+
+`~/git-save-all.sh "msg"` ітерує `/home/w4/backup_*/`:
+1. **`sync.sh` per backup** — копіює з prod (`/home/nosfortube/frontend_<port>/`) у backup. **Tracked subset** (whitelist у sync.sh): templates (`layout.etlua`, `id_index.etlua`, `video.etlua`, banner modules), ad orchestration JS (`ad-config.js`, `ad-core.js`, `vast-preroll.js`, `ad-bundle.min.js`), player files, тести, robots.txt. Решта prod-коду — поза git.
+2. **Auto-rebuild ad-bundle:** якщо будь-який з 5 source JS (`ad-config.js`, `ad-core.js`, `ad-mute.js`, `vast-preroll.js`, `ad-bootstrap.js`) новіший за `ad-bundle.min.js` → запуск `bash build-ad-bundle.sh` (terser concat+minify).
+3. **Cache-bust:** md5sum bundle → перші 7 hex → `sed -i ?v=...` у `views/layout.etlua`. Idempotent (однаковий контент = однаковий хеш).
+4. **Commit per backup:** message формат `YYYY-MM-DD_HH:MM - <msg> [backup_<port>]`. Кожен backup repo окремо — N changed sites = N commits у різних repos.
+
+**Призначення:** git-tracking для recovery / audit / blame. **Не deploy mechanism.**
+
+## Open questions
+
+- [ ] CDN — який провайдер (Cloudflare / BunnyCDN / Fastly)? Per-site чи unified?
+- [ ] Backup_<port>/ покриття — чому 14 із 94 сайтів? Поширити чи це історичний субсет? (open-разом з юзером)
+- [ ] Headless browser (Puppeteer / Playwright) на сервері для visual regression / ad-render check — варто setup-нути на потребу?
--- a/docs/INFRASTRUCTURE.md
+++ b/docs/INFRASTRUCTURE.md
@@ -60,8 +60,8 @@

 | Hook | Event | Що робить |
 |------|-------|-----------|
-| `guard-bash.sh` | PreToolUse:Bash | Блокує: rm на critical paths (/etc, /var, /home/nosfortube), git push для bots, write до /home/nosfortube/, raw tmux send-keys без bot prefix |
-| `guard-readonly.sh` | PreToolUse:Edit\|Write | Блокує Edit/Write на `/home/nosfortube/`, `/etc/`, `/var/www/`, `/usr/` |
+| `guard-bash.sh` | PreToolUse:Bash | Granular block: rm/write до `/home/nosfortube/` поза edit zone (`orest/`, `frontend_<port>/`); rm на system paths; git push для bots; raw tmux send-keys без bot prefix. Backup: `.bak.2026-05-02` |
+| `guard-readonly.sh` | PreToolUse:Edit\|Write | Granular: ALLOW `/home/nosfortube/frontend_<port>/`, `/home/nosfortube/orest/`. DENY: `frontend_<port>_<lang>/`, `frontend_core/`, `.git/`, system paths (`/etc/`, `/var/*`, etc.). Backup: `.bak.2026-05-02` |
 | `auto-signal-goboss.sh` | PostToolUse:Write\|Bash | Auto-signal `gocc{N}: done` коли bot пише `~/comms/<bot>-report.md` |
 | `check-inbox.sh` | (опційний) | Periodic inbox check |
 | `telegram-notify.sh` | Stop | TG completion ping |
--- a/docs/INTERLINKING.md
+++ b/docs/INTERLINKING.md
@@ -0,0 +1,44 @@
+# tubev — Cross-Site Interlinking
+
+Сайти між собою перелінковані — це окрема техніка SE-схеми.
+
+## Status
+
+🟡 **Skeleton** — повна map ще не зібрана.
+
+## Що знаємо
+
+- Перелінковка існує між сайтами екосистеми
+- Це частина **PBN-tier ranking strategy** — взаємні лінки → SE boost
+- Реалізація: припускаємо `views/modules/footer-links.etlua` або аналог + конфіг у `lib/<port>/var.lua`
+
+## Що треба з'ясувати + задокументувати
+
+### Map of links
+- [ ] Хто на кого лінкує — site-graph (adjacency table)?
+- [ ] Скільки лінків per page (home, video, list, footer)?
+- [ ] Anchor strategy — exact-match keyword / brand / mixed?
+
+### Implementation
+- [ ] Де визначені лінки — централізована таблиця чи hardcoded per-template?
+- [ ] Link rotation — статичні чи rotated per-request?
+- [ ] `rel="nofollow"` / `rel="ugc"` / без — політика?
+
+### Risks / monitoring
+- [ ] Якщо один сайт впав / deindexed — як це впливає на graph?
+- [ ] Link audit — є чи нема?
+
+## Cross-site link map (placeholder)
+
+```
+domain1.xxx → domain2.xxx, domain3.xxx, ...
+domain2.xxx → domain1.xxx, ...
+```
+
+(Заповнити коли зберемо source-of-truth.)
+
+## Open questions for developer
+
+1. Де source-of-truth для cross-site links — централізований конфіг чи per-site hardcoded?
+2. Тип лінків (footer / contextual / sidebar / topbar)?
+3. Чи є вимкнення per-site (одна виключена з графа на час downtime)?
--- a/docs/PERFORMANCE.md
+++ b/docs/PERFORMANCE.md
@@ -0,0 +1,66 @@
+# tubev — Performance / PSI
+
+PSI критично — швидкість впливає на SE → реклама → дохід.
+
+## Status
+
+🟡 **Manual mode** — автомоніторингу нема. PSI checks ad-hoc.
+
+## Принципи
+
+- **Critical CSS inline** у `views/css/css_*.etlua` (rendered у `<head>`)
+- **Deferred CSS** — `views/static/css/*.css` під `<link rel="preload" ... onload>` або захищеним defer pattern
+- **JS defer** — non-critical JS не блокує LCP
+- **CDN на prod** — edge caching для static assets
+- **Cache-bust через `?v=md5`** — щоб CDN не serv stale (детально у [DEPLOY.md](DEPLOY.md#cache-bust-механізм))
+
+## Поточний процес
+
+1. **Тригер для перевірки:**
+   - Після великих змін (refactor / structural)
+   - Періодично (ad-hoc, не регулярно)
+   - Після репортів про повільність
+2. **Інструмент:** `https://pagespeed.web.dev/` (Google PageSpeed Insights — public)
+3. **Дія:** все що Lighthouse підкреслив у "Opportunities" / "Diagnostics" — варто пофіксити.
+4. **Запис:** результати **не зберігаються** systematically. Subjective tracking ("стало гірше" / "ок").
+
+## Future — automonitoring (не пріоритет, in-mind)
+
+Ідеї коли руки дійдуть:
+
+- **PSI API** + cron → daily snapshot per site (mobile / desktop)
+- **Database** з історією → graphs per site
+- **Alert** при падінні >X% від baseline
+- **Lighthouse-CI** у git-save-all.sh? (PSI run на t1.* після deploy)
+
+Поки тримати в умі — ground для майбутнього.
+
+## Що треба з'ясувати + задокументувати
+
+### Targets
+- [ ] PSI target mobile / desktop — який baseline вважаємо OK? (probably: mobile ≥ 70, desktop ≥ 90)
+- [ ] LCP / CLS / TBT — які thresholds для тривоги?
+
+### Bottlenecks
+- [ ] Common bottleneck across sites — ads / video player / fonts / images?
+- [ ] Per-site outliers — які гірші, чому?
+
+### Optimization patterns у репо
+- [ ] Image format — webp / avif / jpeg per-site?
+- [ ] Font loading — self-hosted чи Google Fonts? `font-display: swap`?
+- [ ] Video poster lazy-load — реалізовано?
+- [ ] Service Worker / cache strategy — є?
+
+## Per-site PSI table (placeholder)
+
+| Port | Domain | Mobile | Desktop | LCP | CLS | TBT | Last check | Notes |
+|------|--------|--------|---------|-----|-----|-----|-----------|-------|
+| 8082 | atube.sex | TBD | TBD | TBD | TBD | TBD | — | — |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+(Заповнити по мірі замірів якщо системно вирішимо tracking-нути.)
+
+## Open questions
+
+- [ ] Який PSI mobile baseline вважаємо acceptable (70 / 80 / 90)?
+- [ ] Найбільш проблемні сайти — чи знаєш off the top of head?
--- a/docs/PROJECT.md
+++ b/docs/PROJECT.md
@@ -0,0 +1,46 @@
+# tubev — Project Overview
+
+Multi-site adult video tube інфраструктура. **Frontend-only scope** — backend (OpenResty + Lua kor) у розробника.
+
+## Масштаб
+
+- **94 сайти** у `/home/nosfortube/frontend_<port>/` (порти 8081-81xx)
+- **71 site-name → port mapping** у `/home/nosfortube/orest/site-name-routing.csv` (CSV columns: `site name;id;url-pattern;new-url-pattern`)
+- **14 backup_<port>/** у `/home/w4/` — git-archive snapshots (підмножина, не всі сайти)
+
+## Бізнес-модель
+
+- Сайти показують **adult video** контент: або **hotlinked** з xvideos / зовнішніх pornhub-tier джерел, або **self-hosted** на власному CDN/сервері
+- Реклама через **adspyglass.com** — основне джерело монетизації
+- Бізнес-інтерес: **максимізувати SE (sessions/engagements)** щоб показати рекламу, **не переборщити** щоб не шкодити UI/UX
+- **PSI критично** — швидкість завантаження впливає на ранкінг і retention
+
+## Що ми робимо / не робимо
+
+| Робимо | Не робимо |
+|--------|-----------|
+| Templates (etlua) | Backend Lua код kor |
+| CSS/JS на сайтах | Серверну конфігурацію (nginx, OpenResty) |
+| Per-site UX/дизайн | Контент / завантаження відео |
+| Performance / PSI оптимізацію | Платежі / billing |
+| Bug-fix у frontend | Admin panels (внутрішні розробницькі) |
+
+## Технічна модель
+
+- **Кожен сайт окрема папка** `frontend_<port>/` зі своїми templates / static / config
+- **Shared resources** — `views/static/js/lib/`, `views/static/js/lib2/` (зміни поширюються на ВСІ сайти, не one-off)
+- **Per-site config** — `lib/<port>/var.lua` (потребує kor reboot щоб applied)
+- **Test → Prod flow** — `t1.<domain>` (IP-restricted preview) → admin deploy → prod з CDN
+
+Деталі по кожному аспекту:
+- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — folder layout per site
+- [docs/DEPLOY.md](DEPLOY.md) — test → prod flow, admin role
+- [docs/ADS.md](ADS.md) — adspyglass integration
+- [docs/PERFORMANCE.md](PERFORMANCE.md) — PSI rules
+- [docs/INTERLINKING.md](INTERLINKING.md) — cross-site linking
+- [docs/ADMINS.md](ADMINS.md) — admin panels
+
+## Open questions
+
+- [ ] Чому `backup_<port>/` покриває 14 із 94 сайтів? Інші 80 не tracked у git навмисно?
+- [ ] Стратегія monitoring — як ловити breakage per-site (PSI degradation, render errors, ad failures)?
--- a/docs/RECOMMENDATIONS.md
+++ b/docs/RECOMMENDATIONS.md
@@ -209,6 +209,58 @@ Layout uses `<%= site.domain %>`, `<%= site.ga_id %>`.

 ---

+## 🛠 INFRASTRUCTURE / Workflow
+
+### W1. Hook conflict — Claude editing у `/home/nosfortube/` *(BUG/FEATURE)* ✅ DONE 2026-05-02
+**Resolution:** Granular policy реалізована у `guard-readonly.sh` + `guard-bash.sh`. ALLOW `frontend_<port>/` (digits-only) + `orest/`. DENY lang variants, frontend_core, .git, system paths. Backup попередніх hooks: `.bak.2026-05-02`. Test matrix: 19/19 readonly + 18/19 bash (1 pre-existing sed-i regex limitation).
+
+### W2. backup_<port>/ scope — 14 із 94 сайтів *(FEATURE)*
+**Where:** `/home/w4/backup_*/`
+**Problem:** git-tracking покриває 14 сайтів, інші 80 без recovery. Можливі причини: історичний субсет / pilot / залишки старого етапу.
+**Options:**
+- Зберегти 14 (subset для критичних сайтів)
+- Поширити на всі 94 (масовий setup `sync.sh` + initial commits)
+- Замінити на централізований моніторинг + adminskий git
+**Effort:** L якщо поширити (ініт repos + sync.sh per site + перші commits).
+**Status:** OPEN. Залежить від наскільки git-history важливий vs adminove ownership.
+
+### W3. PSI automonitoring *(FEATURE)*
+**Where:** Future infra
+**Problem:** Поточний PSI check — manual через pagespeed.web.dev, не systematic. Регресії можуть бути непомічені до next ad-revenue падіння.
+**What:** PSI API + cron → daily snapshot + history db + alert при падінні. Або Lighthouse-CI на t1.* після deploy.
+**Effort:** M-L (setup ~6-12h)
+**Status:** DEFERRED (in-mind, не пріоритет — поки adspyglass dashboard як signal).
+
+---
+
+## 📚 DOC items
+
+### D1. ad-bundle source files location
+**Where:** [ADS.md § Source files](ADS.md#source-files)
+**What:** Знайти де живуть 5 source JS-файлів (`ad-config.js`, `ad-core.js`, `ad-mute.js`, `vast-preroll.js`, `ad-bootstrap.js`) — `frontend_<port>/views/static/js/` чи shared. Записати у ADS.md.
+**Effort:** XS (15 min, `find /home/nosfortube/ -name 'ad-config.js'`)
+**Status:** OPEN — потрібен hook resolution (W1) щоб дослідити.
+
+### D2. Mirror swap mechanism
+**Where:** [ADS.md § Open questions](ADS.md#open-questions-for-developer) Q3
+**What:** Зрозуміти як Адмін заміняє banned mirror — через ad-config.js mass replace, runtime config, чи інше. Записати у ADS.md.
+**Effort:** S (питання до developer + 1 example)
+**Status:** OPEN.
+
+### D3. CDN provider
+**Where:** [DEPLOY.md § Open questions](DEPLOY.md#open-questions)
+**What:** Який CDN на prod (Cloudflare / BunnyCDN / Fastly / custom). Per-site або unified.
+**Effort:** XS (питання до developer)
+**Status:** OPEN.
+
+### D4. Template ad-zone pattern
+**Where:** [ADS.md § Template integration](ADS.md#template-integration)
+**What:** 1 sample template fragment з ad-zone для розуміння placement pattern.
+**Effort:** XS (показати 5-10 рядків з template)
+**Status:** OPEN.
+
+---
+
 ## Reminders cadence

 goboss перевіряє цей файл **на початку кожної session** і нагадує developer-у:
@@ -227,4 +279,5 @@ Items з статусом `DONE`, `WONTFIX`, `DEFERRED` переходять у

 ---

-*Last update: 2026-04-30 (initial backlog from gocc1+2+3+4 audits)*
+*Last update: 2026-05-01 (W1-W3 workflow + D1-D4 doc items added).*
+*Initial backlog: 2026-04-30 (gocc1+2+3+4 audits).*
--- a/docs/SITES.md
+++ b/docs/SITES.md
@@ -1,6 +1,8 @@
 # tubev — Sites Inventory

-14 сайтів у `/home/w4/backup_<port>/`. Кожен — окремий git repo.
+> **Scope note:** ця таблиця покриває **14 git-archived сайтів** у `/home/w4/backup_<port>/`. **Повна екосистема — 94 сайти** у `/home/nosfortube/frontend_<port>/`. Site-name → port mapping (71 entries): `/home/nosfortube/orest/site-name-routing.csv`. Ця таблиця буде розширена коли поширимо backup-tracking або додамо моніторинг по всіх сайтах.
+
+14 backup-tracked сайтів — кожен окремий git repo.

 ## Таблиця