## このガイドの範囲

MAESTRO は認証なし（no-auth）でも動きますが、複数人で使う・外部に出す場合はログインを有効にします。 その際に最初に詰まるのが「まだ誰もログインできない状態で、どうやって最初の管理者を作るか」です。 本ガイドはローカル認証（ID + パスワード）を前提に、その初回ブートストラップ手順をまとめます。

setup-wizard とは別です
`npm run setup` のセットアップウィザードは LLM 接続先の設定だけが対象で、認証・初期管理者は対象外です。 認証まわりは本ガイドで手動設定します。

## 前提

- `config.yaml` が存在すること（無ければ `config.yaml.example` をコピー）。
- サーバーをビルド・起動できること（`scripts/server.sh start` 等）。

## ステップ 1 — ローカル認証を有効化し、初回 admin を seed する

初回管理者は「セルフ登録」ではなく、`config.yaml` に書いておくと起動時に自動作成（seed）される方式です。 `auth:` ブロックに次を追加します。

    auth:
      session_secret: "ランダムな長い文字列"     # 未設定だと再起動ごとにセッション失効
      local:
        enabled: true
        allow_signup: false                  # 後述。true で他ユーザーのセルフ登録を許可
        bootstrap_admin:                      # 起動時に id='local' の管理者を冪等 seed
          email: "admin"                      # ← ログインID（メール形式でなくてOK）
          password: "強いパスワードを設定"        # ← 平文で config に入る。初回ログイン後に変更推奨

キー | 意味
--- | ---
`auth.session_secret` | セッション署名鍵。未設定だとプロセスごとのランダム値になり、再起動でログインが切れる。安定運用では必ず設定。
`auth.local.enabled` | `true` でローカル（ID+パスワード）ログインを有効化。これだけで認証が有効になり、OAuth 無しでも保護される。
`auth.local.bootstrap_admin.email` | 初回管理者のログインID。後述の通りメール形式は不要。
`auth.local.bootstrap_admin.password` | 初回管理者のパスワード。config に平文で保存されるため、初回ログイン後に Settings から変更を推奨。
`auth.local.allow_signup` | `true` で 2人目以降のセルフ登録を許可（作成されるのは承認待ち状態）。

no-auth からの移行はそのまま引き継げる
seed される管理者は固定 ID `local` で作られます。これは no-auth 時代にデータの所有者として使われていた ID と同じなので、 認証なしで溜めたタスクやファイルを、そのまま初回 admin が引き継ぎます。

## ステップ 2 — 再起動してログイン

1. サーバーを再起動する。
2. 起動ログに `[auth] seeded local system admin id=local email=...` が出ることを確認する（seed は冪等。再起動のたびに config の値でパスワードが更新される）。
3. ブラウザで `/auth/login` を開き、ステップ1で設定した ID とパスワードでログインする。そのまま管理者として入れる。

## ログインID について（メール不要）

ローカル認証の識別子は内部的に「email」という名前のフィールドですが、メール形式の検証はしていません。 `admin` や `team-taro` のような自由な文字列をログインID として使えます。 ログイン／登録フォームの入力欄も `type="text"`・ラベル「ログインID」になっており、 ブラウザのメール形式チェックは外れています。

OAuth を併用する場合
Google / Gitea OAuth も使う構成では、そちら側はメールアドレスで識別され、管理者自動昇格は `auth.admin_emails` のメール一致で判定されます。 ローカル認証だけなら自由ID で問題ありません。

## ステップ 3 — 2人目以降のユーザー

方法は2通りです。

- セルフ登録を許可する: `auth.local.allow_signup: true` にすると、ログイン画面に登録フォームが出る。登録されたユーザーは承認待ち（pending）になり、そのままではアプリを使えない。管理者が Settings → ユーザー管理 で承認すると有効化される。
- 管理者が用意する: allow_signup を使わず、管理者がユーザーを作成・有効化する運用も可能。

## よくある詰まり

症状 | 原因 / 対処
--- | ---
起動時に `Cannot read properties of undefined (reading 'google')` で落ちる | 古いビルドで `auth.providers` 未設定だと発生した既知不具合（修正済み）。最新を pull・再ビルドすれば解消。暫定回避は `auth:` 直下に `providers: {}` を1行足す。
再起動のたびにログインが切れる | `auth.session_secret` 未設定。安定した値を設定する。
初回 admin でログインできない | 入力した ID/パスワードが `bootstrap_admin` の値と一致しているか確認。値を変えて再起動すればパスワードは上書き更新される（seed は冪等）。
UI 変更が反映されない | サーバー再起動だけでは UI は更新されない。`npm run build:ui` を実行してから再起動する。

## 背景・関連

- 設定の全項目は `config.yaml.example` の `auth:` ブロックのコメント参照。
- LLM 接続先の初期設定はセットアップウィザード（`npm run setup`）が担当。本ガイドの認証はウィザードの対象外。
- 関連変更: 自由ログインID 対応（PR #448）、`auth.providers` 未設定クラッシュ修正（PR #447）。