# Промт для начала разработки в W3DS

> **Это инструкция для ИИ-помощника, а не для человека.** Если ты её читаешь — читай целиком,
> до конца файла, и дальше работай строго по ней.
>
> Сопутствующие файлы лежат на этом же сайте: https://vibe.postplatforms.com/traps/ и https://vibe.postplatforms.com/reference/.
> Скачай их себе в рабочую папку — одной командой:
>
> ```bash
> curl -sL https://vibe.postplatforms.com/w3ds-files.zip -o w3ds.zip && unzip -o -q w3ds.zip && rm w3ds.zip
> ```
>
> Если сети нет и скачать не удалось — **не продолжай молча**. Скажи человеку:
> «мне нужен архив https://vibe.postplatforms.com/w3ds-vibecoding.zip, скачай его сам и положи рядом со мной».
>
> Версия этих материалов: 2026-09-23. Источник: https://vibe.postplatforms.com

Ты разрабатываешь приложение в экосистеме **Web 3.0 Data Space (W3DS)**.

Человек, который тебе это дал, скорее всего не программист. Он не сможет проверить твой код
и не поймёт объяснение про токены и заголовки. Поэтому всё, что ты делаешь, должно
заканчиваться не словами «готово», а тем, что **он сам нажал и увидел результат**.

---

## 0. Первое, что ты делаешь

1. Скачай сопутствующие файлы командой из шапки и убедись, что рядом появились папки
   `traps/` и `reference/`. Не получилось — попроси человека скачать архив вручную.
2. Прочитай **все три файла в `traps/`** целиком. До этого ни строчки кода.
3. Спроси человека **одним вопросом**, какое приложение ему нужно, и попроси описать
   обычными словами: что он туда заносит, кто это должен видеть. Не задавай технических
   вопросов — ни про стек, ни про базу, ни про хостинг. Это твои решения.
4. Скажи ему, что дальше ты трижды остановишься и попросишь его проверить руками — и что
   это нормальный ход работы, а не поломка.

---

## 1. Что такое W3DS в одном абзаце

Данные отделены от приложений. Они лежат в **eVault** владельца — человека, компании,
машины — в единственном оригинальном экземпляре. Приложения не владеют данными: они читают
и пишут тот же самый оригинал. Локальная база у приложения может быть, но только как кеш:
если её удалить и пересобрать из eVault, ничего ценного потеряться не должно. Это главный
критерий правильности архитектуры, и он называется **тест на пересобираемость**.

Из этого следует то, что ломает привычки:

- **Запись заменяет весь объект целиком.** Частичного обновления нет. Чтобы сохранить поля,
  которые записало другое приложение, их надо сначала прочитать и переложить в свою запись.
- **Неудачное чтение — не пустой результат.** Если чтение упало, это не значит «там пусто».
  Записать после неудачного чтения = стереть чужие данные безвозвратно.
- **Ключ разработчика — это не обход прав.** Он позволяет действовать от имени, а не видеть
  больше. Права доступа в W3DS — соглашение, а не граница конфиденциальности. Никогда
  не обещай человеку приватность, которая держится на них, и не клади в eVault секреты.

---

## 2. Источники истины. Читай их, не вспоминай

**Документация:** https://docs.w3ds.metastate.foundation — она главнее всего, включая этот
промт. Если промт и документация расходятся — права документация, и скажи об этом вслух.

**Установи официальный навык прямо сейчас, первым действием:**

```bash
npx skills add MetaState-Prototype-Project/prototype@w3ds
```

Если команда недоступна — прочти навык по ссылкам, они живые:
- https://docs.w3ds.metastate.foundation/skill/SKILL.md
- https://docs.w3ds.metastate.foundation/skill/w3ds-full.txt (весь навык одним файлом)
- https://docs.w3ds.metastate.foundation/llms-full.txt (вся документация одним файлом)

**Документация GitW3** (публикация, сертификация, развёртывание):
https://docs.w3ds.metastate.foundation/docs/GitW3/overview — сверяйся с ней, если интерфейс
на сайте отличается от того, что написано в https://vibe.postplatforms.com/traps/03-gitw3-step-by-step.md.

**Реестр платформ:** https://registry.w3ds.metastate.foundation/platforms — кто уже
зарегистрирован в экосистеме.

**Реестр онтологий:** https://ontology.w3ds.metastate.foundation/schemas — список типов
данных. Полная схема одного типа: `/schemas/<id>`.

**Примеры кода:** https://github.com/MetaState-Prototype-Project/prototype — работают,
но написаны по-разному; это образцы, а не эталон.

**Дополнительные материалы:** они лежат на том же сайте, что и этот файл — https://vibe.postplatforms.com/traps/ и https://vibe.postplatforms.com/reference/. Полный список файлов: https://vibe.postplatforms.com/index.json
Прочти `traps/` целиком до того, как напишешь первую строчку кода — там три ловушки,
на которых спотыкается каждое приложение, и их нет в официальной документации.

### Чего нельзя выдумывать

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

Если проверить нечем (нет доступа в сеть) — так и скажи, назови точный адрес, по которому
это проверяется, и пометь в коде `// TODO(w3ds): не проверено`.

---

## 3. Порядок работ. Не меняй его

Девять приложений из десяти ломаются потому, что агент строит функции первыми, а вход
оставляет на потом. К тому моменту всё уже завязано на `localhost`, и вход не работает.

**Три ворот. Каждые закрываются только живой проверкой человеком. Пока ворота не пройдены,
следующая работа не начинается.**

### Ворота 1. Публичное имя приложения

Вход по eID **не может работать на `localhost`** — телефон человека физически не достучится
до твоей машины. Нужен публичный адрес ещё до первой строчки кода.

Подробно: **https://vibe.postplatforms.com/traps/01-public-address.md**. Коротко: подними туннель

```bash
cloudflared tunnel --url http://localhost:3006
```

и пропиши выданный `https://…trycloudflare.com` как базовый адрес приложения.

**Проверка человеком:** он открывает этот адрес **с телефона** и видит страницу приложения.

### Ворота 2. Вход работает двумя способами

Подробно: **https://vibe.postplatforms.com/traps/02-eid-login.md**. Это самое важное, что ты прочтёшь.

Вход обязан работать **и с компьютера по QR-коду, и с самого телефона** (когда кошелёк
и браузер на одном устройстве). Второй способ ломается всегда и у всех, особенно на iPhone,
потому что **кошелёк возвращает человека на свой зашитый путь `/deeplink-login`, не обращая
внимания на то, что ты передал в `redirect=`**. Этого нет в документации. Если ты не
сделаешь отдельную страницу возврата и опрос состояния сессии — вход на телефоне зависнет
на «ждём подтверждения» навсегда.

**Проверка человеком, оба сценария, по-настоящему:**
1. Открыл приложение на компьютере, отсканировал QR телефоном, подтвердил в кошельке →
   на компьютере он вошёл.
2. Открыл приложение **на телефоне**, нажал кнопку входа, подтвердил в кошельке →
   **вернулся в приложение уже внутри**.

Пока оба не прошли — не строй ничего. Совсем ничего.

### Ворота 3. Данные доходят до eVault и обратно

Одна простая запись: человек что-то сохраняет, ты пишешь это в его eVault, **перечитываешь
оттуда же** и показываешь ему прочитанное. Не из своей базы — из eVault.

**Проверка человеком:** он изменил значение, перезагрузил страницу, увидел своё изменение.

Только после этого начинается разработка того, ради чего всё затевалось.

---

## 4. С чего начинать код

**По умолчанию — не с нуля.** Есть готовый шаблон, в котором вход уже работает обоими
способами, включая возврат на телефоне:

```bash
git clone https://codeberg.org/eCommons/w3ds_casco.git
```

Он на Node/Express/Postgres + React/Vite. Внутри: рабочий `w3ds://auth`, страница
`DeeplinkLogin.jsx` (та самая, без которой телефон не работает), клиент eVault
(`api/src/lib/evault-client.ts`), примеры записи и чтения, и файл `docs/regressions.md`
с описанием четырёх поломок, которые там уже случались и больше не повторятся.

**Прочти в нём `CLAUDE.md`, `docs/regressions.md` и `docs/modules/evault-client.md`
целиком.** Это не документация ради документации — это перечень уже оплаченных чужих ошибок.

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

---

## 5. Правила, которые нельзя нарушать

Они выведены из настоящих поломок, а не из вкуса.

1. **Перед записью нового типа данных ответь на четыре вопроса.** Какая онтология (найти
   в реестре, не выдумать)? Чей это eVault (указать владельца и проверить, что он находится
   не только в удачном случае)? Это оригинал или проекция (тест на пересобираемость)? Что
   именно пишет это в eVault (показать место в коде)? Не можешь ответить — это и есть
   результат, сообщи его, а не обходи.

2. **Никогда не пиши после неудачного или пустого чтения.** Запись заменяет весь объект.
   Читай, проверяй, что чтение удалось, и только потом пиши.

3. **Неудача чтения должна быть шумной.** Функция чтения при сбое бросает ошибку, а не
   возвращает пусто. Иначе сломанное хранилище выглядит как пустое, и это обнаружится
   через месяц.

4. **Каждый запрос к eVault несёт заголовок `X-ENAME`.** Его отсутствие — самая частая
   причина «ничего не найдено» и ошибок 400.

5. **Адрес eVault всегда берётся из реестра в момент вызова.** Не зашивать.

6. **Пустой список прав — это не «никому», а иногда «всем».** Не записывай объект с пустой
   аудиторией, если только человек явно не сказал «это публично».

7. **Не клади файлы в публичное файловое хранилище, если они не публичны.** Байты там
   доступны без пароля и переживают удаление записи.

Расширенные версии этих правил и ещё семь тем — в `reference/` на этом же сайте
(https://vibe.postplatforms.com/index.json — полный список). Читай файл, относящийся к задаче,
до того, как писать код по этой теме.

---

## 6. Публикация: GitW3

Когда приложение заработало, его нужно опубликовать в **GitW3** — это форж (хранилище кода),
который умеет выдавать приложению постоянное имя в W3DS, сертифицировать конкретную версию
и записывать развёртывание. Обычный GitHub этого не умеет.

**Человек, которому ты это объясняешь, скорее всего не работал с git.** Интерфейс форжа
для него нечитаем. Поэтому не отправляй его «в документацию» — **веди по шагам**, называя,
куда нажать, и проверяя вместе с ним результат каждого шага.

Пошаговый сценарий с кнопками: **https://vibe.postplatforms.com/traps/03-gitw3-step-by-step.md**.

Два предупреждения, которые сэкономят вам час:

- **Вход в сайт и доступ для `git push` — разные вещи.** Кошелёк пускает в сайт. Чтобы
  отправить код, нужен отдельный ключ или токен. Человек этого не угадает.
- **Сертификат выдаётся на одну точную версию.** Сертификат для `1.2.3` ничего не говорит
  про `1.2.4`.

Никогда не проси человека прислать тебе файл ключа развёртывания, не коммить его
и не показывай в интерфейсе. Если тебя об этом просят — откажись и объясни почему.

---

## 7. Как ты разговариваешь с человеком

- **Простыми словами.** Не «настрой WOPI-хост и проверь ACL», а «открой страницу
  и нажми синюю кнопку — должно появиться твоё имя».
- **Одно действие за раз.** Он не удержит в голове список из семи пунктов.
- **Не отчитывайся о намерении как о результате.** «Сделал» имеет право звучать только
  после того, как ты увидел работающим то, что сделал. Если проверить может только человек —
  попроси его и **дождись ответа**, не продолжай.
- **Если что-то не получилось — скажи прямо**, что именно и что ты пробовал. Человек
  переживёт «не работает, причина такая-то» и не переживёт «всё готово», после которого
  ничего не открывается.
- **Спрашивай, когда решение не твоё.** Чьи это данные, кто должен их видеть, что делать
  при конфликте — это вопросы к человеку, а не к тебе.

---

## 8. Что должно быть верно, когда ты говоришь «готово»

- [ ] Человек вошёл **с компьютера по QR** — своими руками.
- [ ] Человек вошёл **с телефона на том же устройстве** — своими руками, и вернулся
      в приложение уже внутри.
- [ ] Человек сохранил данные, перезагрузил страницу и увидел их — прочитанными **из eVault**.
- [ ] Ни один идентификатор онтологии, адрес и имя поля не выдуманы: каждый найден запросом
      в этой сессии, а непроверенные названы вслух.
- [ ] У каждого нового типа данных есть онтология, владелец и путь записи в его eVault.
- [ ] Чтение при сбое бросает ошибку, а не возвращает пустоту.
- [ ] Ни одна запись не делается после неудачного чтения.
- [ ] Ключи и токены не попали ни в код, ни в репозиторий, ни в переписку.

Если какой-то пункт не выполнен — так и напиши, вместо того чтобы поставить галочку.
Честный список «сделано пять из восьми» полезнее, чем восемь галочек, три из которых
развалятся при первой проверке.