# Ловушка 3. GitW3: публикация и сертификация, шаг за шагом

Этот файл — сценарий для **агента**, который ведёт по нему **человека**. Человек может
никогда не пользоваться git и не обязан начинать. Поэтому роли разделены жёстко:

| Кто | Что делает |
|---|---|
| **Агент** | всё, что в терминале: `git`, теги, отправка кода. Молча, без объяснений внутренностей |
| **Человек** | всё, что в браузере: нажимает кнопки, подтверждает в кошельке |

Надписи на кнопках взяты из документации GitW3 на 2026-09-23. Если на экране человека
что-то называется иначе — **права то, что он видит**: сверься с
https://docs.w3ds.metastate.foundation/docs/GitW3/overview и веди по фактическому
интерфейсу, а не по этому файлу. Попроси человека прочитать вслух, что написано на кнопке.

Правило на весь сценарий: **одно действие за раз**. Сказал, куда нажать → дождался ответа
«нажал, вижу вот это» → только потом следующий шаг. Список из семи пунктов человек не удержит,
а ошибётся на третьем и вы оба не поймёте, где.

---

## Что такое GitW3 и почему не GitHub

Приложению в W3DS нужно **имя** — постоянный eName платформы, по которому eVault'ы понимают,
кто к ним стучится. Это имя выдаёт не хостинг и не домен, а GitW3: хранилище кода, которое
дополнительно умеет три вещи, которых нет ни у GitHub, ни у GitLab:

1. выдать приложению постоянный **eName платформы**;
2. **сертифицировать конкретную версию** (PPA) — подтвердить, что вот этот код проверен;
3. записать **развёртывание** — что вот эта версия запущена вот там.

Без этого приложение остаётся личным экспериментом.

**Скажите человеку одной фразой:** «Сейчас мы зарегистрируем твоё приложение, чтобы у него
появилось собственное имя в W3DS. Это как получить паспорт: код у нас уже есть, теперь нужна
запись о нём».

---

## Что понадобится человеку

- телефон с eID-кошельком (тот же, которым он входит в приложение);
- компьютер с браузером;
- **публичный адрес приложения** — тот самый из ловушки 1. Без него сертификат не выдадут.

Больше ничего. Ни аккаунта, ни пароля: пароля в GitW3 у человека в принципе нет.

---

# Шаг 1. Вход на сайт

**Говорите человеку буквально так:**

> Открой в браузере адрес `git.w3ds.metastate.foundation`.
> На странице будет кнопка **Sign in with W3DS** — нажми её.

Дальше два варианта, и человеку надо назвать **его**:

- **Он на компьютере:** появится QR-код. Пусть откроет кошелёк на телефоне и отсканирует.
- **Он на телефоне:** рядом с QR есть кнопка **Open your wallet** — пусть нажмёт её.

> В кошельке появится запрос на вход — подтверди его.
> **И не закрывай вкладку в браузере**, пока страница сама не перебросит тебя внутрь.

Последнее предложение важно: закрытая вкладка = вход не завершился, и это выглядит как поломка.

**Проверка шага:** человек говорит, что видит свой значок/имя в правом верхнем углу.

**Если QR перестал работать** — он живёт недолго. Пусть перезагрузит страницу и начнёт заново.
Это не ошибка, это нормальное поведение.

---

# Шаг 2. Ключ для отправки кода

## Предупредите заранее, иначе человек решит, что всё сломалось

**Вход в сайт и право отправлять код — это две разные вещи.** Кошелёк пустил человека
на сайт, но когда агент попробует отправить туда код, у него спросят логин и пароль —
которых нет. Это самое непонятное место во всём сценарии, и оно ловит всех.

Нужен **отдельный ключ**. Два пути; выбирайте первый.

## Путь А (рекомендуется): SSH-ключ

**Делает агент, в терминале.** Сначала проверьте, есть ли ключ уже:

```bash
cat ~/.ssh/id_ed25519.pub
```

Если файла нет — создайте:

```bash
ssh-keygen -t ed25519 -C "w3ds" -f ~/.ssh/id_ed25519 -N ""
cat ~/.ssh/id_ed25519.pub
```

Получится одна строка, начинающаяся на `ssh-ed25519 AAAA…`. **Её и только её** передайте
человеку — это публичная половина, её показывать безопасно. Файл без `.pub` не показывайте
никому и никогда.

**Говорите человеку:**

> Сейчас я дам тебе строчку текста, её надо вставить на сайт.
> 1. Нажми на свой значок в правом верхнем углу → **Settings** (настройки).
> 2. В меню слева найди раздел **SSH / GPG Keys**.
> 3. Кнопка **Add Key** (добавить ключ).
> 4. В поле **Key Name** напиши что угодно, например `мой компьютер`.
> 5. В большое поле **Content** вставь строчку, которую я сейчас пришлю.
> 6. Нажми **Add Key**.

Затем пришлите строку отдельным сообщением, целиком, без переносов.

**Проверка шага (делает агент):**

```bash
ssh -T git@git.w3ds.metastate.foundation
```

Ответ вида «Hi <имя>! You've successfully authenticated» означает, что путь открыт.

## Путь Б: токен (если SSH не получился)

**Говорите человеку:**

> 1. Значок в правом верхнем углу → **Settings**.
> 2. Слева — раздел **Applications**.
> 3. Найди **Generate New Token**, дай ему имя, например `для разработки`.
> 4. Нажми кнопку создания и **скопируй показанную строку — её покажут один раз**.

Дальше — важное:

> Эту строку **не присылай мне в чат**. Она работает как пароль. Когда у тебя спросят
> пароль при отправке кода, вставишь её сам.

Агент: токен человека вы не запрашиваете, не храните и не вписываете в команды. Если человек
всё-таки его прислал — скажите об этом прямо и попросите отозвать токен и создать новый.

---

# Шаг 3. Создание платформы

**Говорите человеку, по одному пункту:**

> Вверху страницы есть кнопка **+** (плюс). Нажми её → в выпавшем меню выбери
> **New repository** (новое хранилище).

> Появится выбор из двух вариантов. Нам нужен **Make a new platform** —
> «создать новую платформу». Второй вариант (*Port an existing application*) —
> для переноса уже существующих приложений, он не наш.

## Экран 1 — Repository

> 1. **Owner** — оставь себя (там уже будет твоё имя).
> 2. Галочка «private» — если оставить, код будет виден только тебе. Для начала так и оставь.
> 3. **Display name** — **название приложения человеческими словами**. Например
>    `Учёт договоров`. Его будут видеть люди.
> 4. Ветка по умолчанию — оставь `main`, ничего не меняй.
> 5. Нажми кнопку «дальше».

**Скажите отдельно, чтобы человек не искал поле:** короткое техническое имя он **не выбирает**.
GitW3 сам сделает его из названия. И это имя потом **не меняется**, даже если название
поменять — поэтому название стоит придумать сразу нормальное.

## Экран 2 — Platform details

> 1. **Description** — одно-два предложения, что приложение делает.
> 2. **Application domains** — выбери из списка одну или несколько областей, к которым
>    относится приложение. Выбери хотя бы одну: без неё потом не дадут сертификат.
> 3. **Application URL** — публичный адрес приложения. Если он уже есть — впиши.
>    Если ещё нет — можно оставить пустым и вернуться сюда позже.
> 4. **Logo URL** — необязательно, пропусти.

Поля «версия» на этом экране нет и быть не должно: версия берётся из релизов, а не пишется руками.

## Экран 3 — AI setup

> Тут просто предложение показать команду для настройки ИИ-помощника.
> Ничего заполнять не надо, нажимай дальше.

> И последняя кнопка: **Create platform**.

## После создания

Человек увидит страницу с созданным хранилищем. **eName платформы появляется не сразу** —
он выдаётся в фоне.

**Говорите:**

> Наверху страницы есть вкладки. Найди вкладку **W3DS** и открой её.
> Там будет написано состояние — имя приложения появится там в течение нескольких минут.
> Если пока пусто, просто перезагрузи страницу через минуту.

**Не дайте человеку решить, что что-то сломалось.** Скажите заранее: «имя появляется
с задержкой, это нормально».

---

# Шаг 4. Код попадает в хранилище

**Это целиком работа агента.** Человеку сообщайте только результат.

Возьмите точный адрес из кнопки клонирования на странице хранилища (человек может
скопировать и прислать; попросите нажать кнопку **SSH** и скопировать строку).

**Важно:** символ `@` перед именем на сайте — украшение, он **не входит** в адрес.
Копируйте адрес как есть, не добавляя и не убирая ничего.

Если код ещё нигде не лежит:

```bash
cd <папка проекта>
git init
git add .
git commit -m "первая версия"
git branch -M main
git remote add origin <адрес из кнопки SSH>
git push -u origin main
```

Если проект уже был в другом хранилище:

```bash
git remote rename origin upstream
git remote add origin <адрес из кнопки SSH>
git push -u origin HEAD:main
```

**Перед первой отправкой проверьте, что в код не попали секреты:** файлы `.env`,
ключи, токены, `w3ds-deployment-key.json`. Убедитесь, что они перечислены в `.gitignore`.
Отправленный секрет считается скомпрометированным, даже если удалить его следующим коммитом.

**Говорите человеку:**

> Код загружен. Обнови страницу хранилища — ты должен увидеть там файлы проекта.

---

# Шаг 5. Публичный адрес приложения

Если на экране 2 адрес не заполнили — сейчас самое время, **без него сертификат не выдадут**.

**Говорите:**

> Открой вкладку **W3DS** в своём хранилище и впиши публичный адрес приложения
> в поле **Application URL**, потом сохрани.

Предупредите: сохранение с этой вкладки — это изменение в коде (GitW3 делает коммит сам).
Агенту после этого стоит сделать `git pull`, иначе получатся расходящиеся правки.

---

# Шаг 6. Публикация версии

Сертифицируют не приложение вообще, а **одну точную версию**. Значит версию надо объявить.

**Делает агент:**

```bash
git switch main
git pull --ff-only
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
```

Номер из трёх чисел через точку. Первая версия — обычно `v0.1.0`.

**Говорите человеку:**

> 1. В своём хранилище открой вкладку **Releases** (релизы).
> 2. Нажми **New release** (новый релиз).
> 3. В поле выбора тега выбери **v0.1.0** — я его только что создал.
> 4. Ниже можно написать пару слов, что в этой версии. Можно и пропустить.
> 5. **Ничего не отмечай галочками** — ни «draft», ни «pre-release».
>    Нам нужен обычный, окончательный релиз.
> 6. Нажми кнопку публикации.

Пункт 5 — здесь ломается сценарий: черновик и предварительный релиз **не становятся**
версией платформы, а выглядят в интерфейсе точно так же. Скажите про это явно.

**Проверка шага:**

> Вернись на вкладку **W3DS**. Через минуту там должна появиться версия `0.1.0`.

(Буква `v` в теге отбрасывается — так и должно быть, это не ошибка.)

---

# Шаг 7. Сертификат PPA

## Сначала проверьте чек-лист вместе

На вкладке **W3DS** есть раздел **PPA certificate** со списком условий. Попросите человека
прочитать его вслух, пункт за пунктом. Должно быть выполнено всё:

- имя платформы выдано;
- выбрана хотя бы одна область применения;
- указан публичный адрес приложения;
- опубликован обычный (не черновик) релиз с номером вида `0.1.0`;
- человек вошёл своим кошельком и он владелец хранилища.

Если какой-то пункт не выполнен — **вернитесь и закройте его**, а не пытайтесь подать заявку:
кнопка либо не сработает, либо заявку отклонят.

## Подача

**Говорите человеку, и предупредите, что будет таймер:**

> Сейчас будет подпись кошельком, и на неё даётся **15 минут**. Возьми телефон в руки заранее.
>
> 1. Проверь, что версия на экране — та самая, `0.1.0`.
> 2. Нажми **Sign and apply for PPA certificate**.
> 3. Появится QR-код — отсканируй его кошельком. Если ты на телефоне, откроется кошелёк сам.
> 4. В кошельке прочитай, что подписываешь, и подтверди.
> 5. **Не закрывай окно в браузере**, пока сайт не скажет, что подпись принята.

Пункт 5 повторите дважды. Человек, подтвердив в телефоне, инстинктивно закрывает вкладку —
и подпись не доходит.

## Что будет дальше

Заявка уходит на рассмотрение людям. Состояния, которые человек увидит:

| Надпись на экране | Что значит |
|---|---|
| **Ready to apply** | всё готово, можно подавать |
| **Application submitted** | подписано и ждёт очереди на проверку |
| **PPA certificate granted** | выдан — можно переходить к шагу 8 |
| **PPA application denied** | отказ, с причиной |

**Скажите человеку прямо: между «подал» и «выдан» проходит время, и это не ваша поломка.**
Не оставляйте его смотреть на экран.

При отказе: на той же вкладке пишется короткий ответ — что изменилось или почему версию
стоит пересмотреть — и нажимается **Sign and reapply**, с новой подписью кошельком.

**И главное, что забывают:** сертификат выдан на `0.1.0` и **только** на `0.1.0`.
Выпустили `0.1.1` — весь шаг 6 и шаг 7 делаются заново. Это не бюрократия, это смысл
сертификата: он подтверждает конкретный код, а не название.

---

# Шаг 8. Запись развёртывания и ключ

Этот шаг нужен, когда приложение уже где-то запущено по-настоящему. GitW3 **не размещает**
приложение — он только записывает, что такая-то версия запущена такими-то людьми.

**Говорите человеку:**

> 1. Открой вкладку **Deploy**.
> 2. **Шаг 1** — выбери релиз. В списке будут только версии с выданным сертификатом.
> 3. **Шаг 2** — дай развёртыванию понятное имя, например `рабочая версия`,
>    и выбери окружение: **Production** — боевое, **Development** — для разработки.
> 4. **Шаг 3** — выбери **Generate a deployment key** (создать ключ).

Дальше — самое ответственное место во всём сценарии:

> Браузер **скачает файл `w3ds-deployment-key.json`**. Он скачивается **один раз**.
> Восстановить его нельзя ни через сайт, ни через поддержку — никак.
>
> Найди его в папке загрузок и переложи туда, где ты хранишь важное.
> **Не присылай мне этот файл. Не открывай его в чате. Не выкладывай никуда.**

> 5. **Шаг 4** — проверь, что на экране правильные версия, имя и окружение,
>    и нажми **Create identities and continue to wallet**.
> 6. Снова подпиши в кошельке — одной подписью подтверждаются обе записи.
> 7. Дождись, пока карточка развёртывания не перейдёт в состояние «опубликовано».

## Агенту — жёсткие правила про этот файл

- **Никогда не просите прислать его.** Если человек прислал сам — скажите, что так делать
  нельзя, и что ключ надо считать скомпрометированным и выпустить новый.
- **Никогда не коммитьте его** и не кладите в папку проекта: добавьте
  `w3ds-deployment-key.json` в `.gitignore` заранее, до шага 8.
- На сервере он подключается **путём к файлу**, а не содержимым:
  переменная вида `W3DS_DEPLOYMENT_KEY_FILE=/путь/к/файлу`.
- Читать его может только серверный код. Во фронтенд он не попадает никогда.
- Потерян — не восстанавливается. Делается новое развёртывание с новым ключом.

---

# Если что-то пошло не так

| Что видит человек | Что это на самом деле |
|---|---|
| QR не сработал / «истёк» | QR живёт недолго — перезагрузить страницу и начать заново |
| Подтвердил в кошельке, а браузер не двинулся | вкладку закрыли или увели слишком рано; повторить с новым запросом |
| У агента при отправке кода спрашивают пароль | не сделан шаг 2: вход в сайт ≠ право отправлять код |
| Имя приложения не появилось | выдаётся в фоне, подождать и перезагрузить вкладку **W3DS** |
| Кнопка PPA не нажимается | не закрыт какой-то пункт чек-листа — прочитать его целиком |
| Версии нет в списке релизов на вкладке Deploy | нет сертификата на **эту** версию |
| Релиз опубликован, а версия не появилась | релиз остался черновиком или предварительным |
| Старое имя или аватар на сайте | выйти и войти заново — профиль подтягивается при входе |

---

# Словарик, если человек спросит

- **Репозиторий / хранилище** — папка с кодом, у которой хранится вся история изменений.
- **Коммит** — сохранённое состояние кода с подписью «что изменилось».
- **Ветка (`main`)** — основная линия разработки.
- **Тег** — метка на конкретном состоянии кода, вида `v1.2.3`.
- **Релиз** — объявление, что вот эта метка — готовая версия.
- **Push (отправка)** — перенос сделанного с компьютера в хранилище на сайте.
- **eName платформы** — постоянное имя приложения в W3DS.
- **PPA** — сертификат на одну точную версию.
- **Развёртывание** — запись, что эта версия запущена вот здесь.

---

# Проверка, которая закрывает этот этап

Всё сделано, когда человек **своими глазами** видит:

- [ ] свой значок в углу сайта (вошёл);
- [ ] файлы своего проекта на странице хранилища;
- [ ] eName платформы на вкладке **W3DS**;
- [ ] версию `0.1.0` там же;
- [ ] надпись **PPA certificate granted**;
- [ ] файл `w3ds-deployment-key.json` сохранённым у себя — и нигде больше.

Не ставьте галочку за человека. «Наверное, уже появилось» — это не проверка.