SKILL.md
embed-cli のトラブルシューティング
認証エラー
not logged in→embed loginを実行する- Auth0 のトークン refresh 失敗 →
embed logout && embed loginで入れ直す
solution-id エラー
solution ID は (1) --solution-id / -s の CLI 引数、(2) 現在の作業ディレクトリの solution.toml の solution_id フィールド、のどちらか（または両方。両方ある場合は一致していること）から解決される。
SolutionIdNotFoundError—--solution-idもsolution_id付きのsolution.tomlも見つからない。--solution-id <id>を渡すか、solution.tomlのあるディレクトリでコマンドを実行するSolutionIdMismatchError—--solution-idは渡されたがsolution.tomlのsolution_idと食い違っている。フラグを外すか、作業ディレクトリが正しいか確認する
HTTP エラー
- pull で
404→ solution が存在しないか権限がない 401→ トークン期限切れ。再ログインする5xx→ リトライ。継続するようなら Embed の運用担当に連絡
Pull conflict
conflict は「前回 pull 以降、ローカルとサーバーが同じファイルの同じ領域を別々に変更した」状態。embed pull が衝突ファイルに conflict マーカー（<<<<<<< local / ======= / >>>>>>> server）を書き込む。
重要: pull の再実行・マーカー除去だけでは収束しない
pull は実行のたびに base + local + server で 3-way merge を やり直す。衝突ファイルの base は解決まで前進しない（旧 base が次回の再マージ基準として据え置かれる）ため、ローカルがサーバーと衝突する変更を残したまま「マーカーを消して再 pull」しても、同じ衝突が毎回再生成され永久に確定しない。CLI に --ours / --theirs 相当の解決コマンドは無く、手動解決が唯一の道。
さらに衝突状態はファイル内容とは別に .embed/state.json の pendingPullConflicts（未解決衝突ファイル一覧）で管理される。push はこれが残っている限り Conflicts in N files で拒否する。これがクリアされる（フィールド自体が外れて undefined になる。スキーマ上は空配列ではなくキー省略で表現される）のは衝突ゼロの pull が完走したときだけで、ワークツリーからマーカーを消すだけではクリアされない。
収束する回復手順
収束の鍵は 衝突領域をサーバー内容と一致させること。そうすると 3-way merge が base=旧 / local=server / server=server となり false-conflict として除外され、次の pull がクリーンに通る。
- 各マーカーで
=======〜>>>>>>> server側（サーバー内容）を残し、<<<<<<< local〜=======側（自分の変更）を捨てる。捨てる前に自分の変更内容をメモする（マーカー内に閉じ込められているため） embed pullを実行 — 衝突ゼロで完走し、base が前進、pendingPullConflictsがクリアされる- メモした自分の変更を 改めて入れ直す
embed push
衝突していない他の編集はそのまま残してよい（片側だけの変更は衝突せず勝つ）。全ファイルをサーバー版で丸ごと上書きする必要はなく、衝突した領域だけサーバーに揃えればよい。
注意:
- pull の再実行自体は安全（state/base は解決まで更新されない）が、安全 ≠ 収束。ローカルに衝突する変更を残す限り何度やっても進まない。
- 末尾改行・空白だけの差分でも、その領域を両側が触っていれば衝突になり、サーバーとバイト一致するまで解けない（
od -c等でバイト確認すると早い）。 - アクティブな solution では server version がよく上がる（run 実行・GUI 編集・型再生成などで進む）ため、push 前に pull → conflict が頻発しうる。
- 詳細・なぜそうなるかは
embed-constraintsを参照。
symlink・バイナリファイル・不正パスが絡む conflict は専用の挙動・回復手順になる → embed-constraints を参照する。
app client を使うテストの deno test には --allow-env が要る
app client は constructor で process.env を読む。そのため new するだけのテストでも env 権限が要り、無いと NotCapable: Requires env access to ... で落ちる。test task に付ける（例: "test": "deno test --allow-env"）。読む変数はクライアント依存なので scope せず --allow-env を使う。tasks は user 編集可（所有境界は embed-overview 参照）なので pull で消えない。
（型チェックで TS2664: module '@anyflowinc/embed-types' cannot be found が出る場合は generated/types.ts の自動生成内容が古い。embed pull で再生成すれば解消する。user 側で対処する必要はない。）
初回 pull が「Directory is not empty」で失敗する
初回 pull（.embed/ がまだ無いディレクトリへの pull）は 空ディレクトリを要求する。許可される既存エントリは .embed / .git / .gitignore のみで、それ以外が 1 つでもあると Directory is not empty. Initial pull requires an empty directory ... で失敗する（.gitignore は見ない）。
このチェックは 初回 pull のときだけ 走る。.embed/ ができた後の更新 pull では走らないので、npx skills add・nodemodules・.denodir などが後から増えても問題ない。
典型例: 空ディレクトリで embed pull する前に npx skills add <origin> を実行し、生成ファイルで非空になって失敗する。
回避・回復: embed pull を先に（空ディレクトリで）実行して .embed/ を作り、その後で npx skills add 等を行う。すでに非空なら、.embed/.git/.gitignore 以外を一時退避 → embed pull → 戻す。
push 時の empty worktree エラー
push は空の worktree では動作を拒否する。誤ってサーバー側のファイルを全消ししないための防御。まず solution を作成するか pull してから push する。