- **pnpm :** `10.33.x`. Le repo fixe `pnpm@10.33.2` via `packageManager` ; utilisez Corepack pour que la bonne version soit sélectionnée automatiquement.
- **OS :** macOS, Linux et WSL2 sont les environnements principaux pris en charge. Windows natif devrait fonctionner pour la plupart des workflows, mais WSL2 reste l’option la plus fiable.
- **CLI d’agent locale optionnelle :** Claude Code, Codex, Devin for Terminal, Gemini CLI, OpenCode, Cursor Agent, Qwen, GitHub Copilot CLI, etc. Si aucune n’est installée, utilisez le mode BYOK API depuis Settings.
`nvm` / `fnm` sont des outils de confort optionnels, pas une étape obligatoire de la configuration du projet. Si vous en utilisez un, installez/sélectionnez Node 24 avant de lancer pnpm :
Au premier chargement, l’app détecte votre CLI de coding agent installée (Claude Code / Codex / Devin for Terminal / Gemini / OpenCode / Cursor Agent / Qwen), la sélectionne automatiquement, puis utilise par défaut le Skill `web-prototype` et le Design System `Neutral Modern`. Tapez un prompt et cliquez sur **Send**. Les sorties de l’agent s’affichent en streaming dans le panneau gauche ; la balise `<artifact>` est extraite et le HTML s’affiche en direct à droite. Une fois la génération terminée, cliquez sur **Save to disk** pour enregistrer l’artifact sous `./.od/artifacts/<timestamp>-<slug>/index.html`.
Le menu déroulant **Design System** charge les Design Systems depuis `design-systems/*/DESIGN.md` : starters écrits à la main, product systems intégrés et design skills normalisés. Choisissez-en un pour habiller chaque prototype dans l’esthétique de cette marque.
Le menu déroulant **Skill** regroupe les entrées par `mode` / `surface` et affiche le Skill par défaut de chaque mode avec un suffixe `· default`. Le catalogue live vient de [`skills/`](skills/) et couvre les workflows web, deck, Design System, image, vidéo et audio. Exemples inclus :
- **Deck / PPT** — `simple-deck` (swipe horizontal single-file) et `magazine-web-ppt` (le bundle `guizang-ppt` depuis [`op7418/guizang-ppt-skill`](https://github.com/op7418/guizang-ppt-skill), par défaut en mode deck, avec ses propres assets/template + 4 références). Les Skills avec side files reçoivent automatiquement un préambule "Skill root (absolute)" pour que l’agent puisse résoudre `assets/template.html` et `references/*.md` depuis le vrai chemin disque au lieu de son CWD.
`pnpm tools-dev` est le seul point d’entrée du lifecycle local. N’utilisez pas les anciens alias root supprimés (`pnpm dev`, `pnpm dev:all`, `pnpm daemon`, `pnpm preview`, `pnpm start`).
Pendant le développement local, `tools-dev` démarre d’abord le daemon, transmet son port à `apps/web`, puis `apps/web/next.config.ts` réécrit `/api/*`, `/artifacts/*` et `/frames/*` vers ce port daemon. L’app App Router peut ainsi parler au processus Express voisin sans configuration CORS.
Les Skills image, vidéo, audio et HyperFrames appellent la CLI locale `od` via des variables d’environnement injectées par le daemon lorsqu’il lance un agent :
Si la génération média échoue avec `OD_BIN: parameter not set`, `apps/daemon/dist/cli.js` manquant, ou `failed to reach daemon at http://127.0.0.1:0`, rebuildez la CLI daemon et redémarrez le runtime géré :
Ouvrez ensuite de nouveau le projet depuis l’app Open Design au lieu de reprendre une ancienne session agent dans le terminal. Un agent lancé par le daemon devrait voir des valeurs comme :
`OD_DAEMON_URL` doit être un vrai port daemon comme `http://127.0.0.1:7457`, pas `http://127.0.0.1:0`. La valeur `:0` est seulement une indication interne "choisir un port libre" au lancement et ne doit pas se retrouver dans les sessions agent.
En mode production daemon-only, le daemon sert lui-même l’export static Next.js à `http://localhost:7456`; aucun reverse proxy n’est impliqué.
Si vous placez nginx devant le daemon, gardez les routes SSE non bufferisées et non compressées. Un échec courant : la console navigateur affiche `net::ERR_INCOMPLETE_CHUNKED_ENCODING 200 (OK)` après 80-90 secondes, parce que `gzip on` dans nginx bufferise les réponses SSE chunked même quand le daemon envoie `X-Accel-Buffering: no`.
Les deux modes alimentent le **même** parser `<artifact>` et la **même** iframe sandboxée. Seuls le transport et la livraison du system prompt changent : les CLI locales n’ont pas de canal système séparé, donc le prompt composé est intégré au message utilisateur.
## Composition du prompt
À chaque envoi, l’app construit un system prompt à partir de trois couches et l’envoie au provider :
```
BASE_SYSTEM_PROMPT (contrat de sortie : wrap in <artifact>, no code fences)
+ active design system body (DESIGN.md — palette/type/layout)
+ active skill body (SKILL.md — workflow and output rules)
Changez le Skill ou le Design System dans la barre supérieure : le prochain envoi utilise le nouveau stack. Les contenus sont mis en cache en mémoire par session, donc un choix ne coûte qu’un fetch daemon.
- **"no agents found on PATH"** — installez une CLI compatible, par exemple `claude`, `codex`, `gemini`, `opencode`, `cursor-agent`, `qwen` ou `copilot`. La liste exacte des adapters détectés vit dans `apps/daemon/src/agents.ts`. Ou passez au mode API/BYOK dans la barre supérieure et collez une clé dans **Settings**.
- **daemon 500 sur /api/chat** — vérifiez la fin de stderr dans le terminal daemon ; la CLI a généralement rejeté ses args. Les CLIs n’acceptent pas toutes la même forme d’argv ; consultez `apps/daemon/src/agents.ts``buildArgs` si vous devez ajuster.
- **la génération média dit que `OD_BIN` manque ou que l’URL daemon vaut `:0`** — exécutez les checks du dispatcher média ci-dessus. Ne reprenez pas l’ancienne session CLI ; rouvrez le projet depuis l’app Open Design pour que le daemon injecte des variables `OD_*` fraîches.
- **Codex charge trop de contexte plugin** — démarrez Open Design avec `OD_CODEX_DISABLE_PLUGINS=1 pnpm tools-dev` pour que les processus Codex lancés par le daemon tournent avec `--disable plugins`.
- **l’artifact ne rend jamais** — le modèle a produit du texte sans wrapper `<artifact>`. Vérifiez que le system prompt passe bien (log daemon) et envisagez un modèle plus capable ou un Skill plus strict.
## Retour à la vision
Ce Quickstart est la graine exécutable de la spec dans [`docs/`](docs/). La spec décrit vers quoi le projet grandit (voir [`docs/roadmap.md`](docs/roadmap.md)). Points clés :
-`docs/architecture.md` décrit le stack livré : Next.js 16 App Router devant, daemon local derrière, et rewrites `apps/web/next.config.ts` en dev pour que le navigateur parle toujours à la même surface `/api`.
-`docs/skills-protocol.md` décrit le schéma `od:` complet. Le daemon lit les métadonnées runtime utiles depuis `SKILL.md` pour router les Skills, composer le prompt, afficher les exemples et configurer les surfaces web / image / vidéo / audio ; le protocole reste la référence pour les champs avancés.
-`docs/agent-adapters.md` anticipe un dispatch plus riche (capability detection, streaming tool-calls). Notre `apps/daemon/src/agents.ts` est un dispatcher minimal : suffisant pour prouver le câblage.
-`docs/modes.md` décrit les workflows prototype / deck / template / design-system. Le catalogue runtime peut aussi exposer des Skills pour les surfaces image, vidéo et audio ; le picker filtre les entrées par `mode` et `surface`.
