oh-my-obsidian-setup

name	oh-my-obsidian-setup
description	Use this skill when the user wants to initialize oh-my-obsidian, create or attach an Obsidian vault, configure persistent vault resolution, or prepare Obsidian Git integration.

Oh My Obsidian Setup

Use this skill when the user wants to initialize oh-my-obsidian, create an Obsidian vault, attach an existing vault, configure persistent vault resolution, or prepare Obsidian Git integration.

Non-Negotiable Contracts

• Use the selected vault directory as vaultRoot.
• Do not mutate a vault before a dry-run summary and explicit user approval.
• Before any non-bootstrap vault artifact mutation, write vaultRoot/.oh-my-obsidian/setup-state.json with status: "in_progress" and planned managedArtifacts.
• The only bootstrap exception before setup state exists is creating vaultRoot and vaultRoot/.oh-my-obsidian.
• Mutating follow-up skills must resolve the vault through explicit OBSIDIAN_VAULT first, then approved Codex hook pointers (<repo>/.codex/oh-my-obsidian.local.json and ~/.codex/oh-my-obsidian.local.json), then the approved Codex config pointer at ~/.oh-my-obsidian/config.json.
• If neither resolver works, report action_required_env and stop mutation.
• Do not depend on repository root scripts, root bin/, or legacy Claude-only environment variables.

Helper Scripts

Resolve the plugin directory from this skill location, then use plugin-local helpers:

node scripts/obsidian-app-preflight.mjs check
node scripts/setup-vault.mjs dry-run --preflight-json "<json-or-file>" --vault "<path>" --project-name "<name>" --domain "<domain-a>" --domain "<domain-b>"
node scripts/setup-vault.mjs apply --preflight-json "<json-or-file>" --vault "<path>" --project-name "<name>" --domain "<domain-a>" --domain "<domain-b>"
node scripts/setup-vault.mjs attach --preflight-json "<json-or-file>" --vault "<path>" --project-name "<name>" --domain "<domain-a>" --domain "<domain-b>"
node scripts/setup-vault.mjs validate --vault "<path>"
node scripts/codex-hooks.mjs plan --mode repo-local --repo-root "<repo>" --vault "<path>"
node scripts/codex-hooks.mjs apply --mode repo-local --repo-root "<repo>" --vault "<path>"
node scripts/obsidian-git-setup.mjs check "<path>"

Only add --create-config-pointer, --git init, Obsidian Git apply, package manager installs, Codex hooks apply, shell profile edits, remote changes, or push commands after separate explicit approval.

Bundled References

Resolve bundled references relative to the directory that contains this SKILL.md before searching anywhere else.

• For interview strategy, read ./references/interviewer.md.
• For vault structure planning, read ./references/vault-architect.md.
• If a reference is not found on the first attempt, derive its absolute path from the current SKILL.md location and retry there before searching the plugin root, repository root, installed cache root, or current working directory.

Interactive Question Mode

When the setup flow needs a user decision, approval, or missing project detail, imitate Claude Ask mode or Codex Plan mode as closely as Codex skills allow.

• Keep one question or one decision per turn.
• Present exactly four numbered choices whenever a branch or approval is needed.
• Options 1, 2, and 3 should be concrete choices for the current step.
• Option 1 should be the recommended or default path when one exists.
• Option 4 must always be 직접 입력 and allow any free-form answer.
• Accept 1, 2, 3, 4, 4: ..., or the exact option label as valid replies.
• If the user asks a side question or gives an ambiguous answer, answer briefly, then restate the same four choices before proceeding.
• Do not ask the user to respond with an empty message or implicit confirmation.

Use this exact interaction shape:

<짧은 현재 상황 요약>

다음 중 하나로 답해주세요.
1. <권장 선택지>
2. <대안 1>
3. <대안 2 또는 이번 단계 건너뛰기/중단>
4. 직접 입력

Guidance by question type:

• For install/approval questions, option 3 should usually mean 지금은 건너뛰기 or 여기서 중단.
• For interview questions, options 1 to 3 should be plausible common answers, and option 4 should capture custom project details.
• If the decision is effectively binary, still keep four choices by using: recommended path, safe alternative, skip for now, direct input.

Setup Flow

1. Run Obsidian app preflight.

   • If Obsidian is installed, summarize path/version when available.
   • If it is missing and auto-install is available, show method and command, then ask before running install with the four-choice interaction mode.
   • If preflight reports git.status != "usable", explain the issue before any git-related setup. On macOS broken developer tools paths, show git.fixCommand when present.
   • If running in a container, never install a desktop app. Ask whether to continue and install Obsidian on the desktop host later.
   • In WSL, only use the Windows host check/install path after approval.
   • Preserve the successful preflight JSON and pass it to setup-vault.mjs --preflight-json ... so setup-state records the real preflight outcome.

2. Interview the user.

   • Ask one focused Korean or English question at a time.
   • Gather project name, project purpose, existing/greenfield status, tech stack, team context, workflow, and at least two knowledge domains.
   • Read ./references/interviewer.md for question strategy.
   • Even during the interview, present three plausible choices plus 4. 직접 입력 whenever possible instead of using only open-ended prose.
   • If subagents are unavailable or unnecessary, continue as a single agent.

3. Propose the vault structure.

   • Read ./references/vault-architect.md before proposing the vault structure.
   • Include a service layer under a project/service folder, the required 작업기록 layer, and scripts/team-setup.
   • Show rationale, vault path, and exact managed artifact list.
   • Regenerate if the user asks for changes.

4. Dry run.

   • Run setup-vault.mjs dry-run --preflight-json "<saved-json-or-file>".
   • Present planned artifacts and approvals still required.
   • If resolver completion is missing, prefer the official repo-local Codex hooks step later in this flow instead of asking beginners to configure OBSIDIAN_VAULT or a global config pointer first.

5. Apply after approval.

   • Run setup-vault.mjs apply --preflight-json "<saved-json-or-file>".
   • Add --create-config-pointer only if the user approved that pointer.
   • Add --git init only if the user approved git initialization.
   • Do not add --git init if preflight reported git.status != "usable".
   • If the result is action_required_env, explain that vault files are ready but Codex still needs a project-local connection. Continue to the Codex hooks choice unless the user explicitly wants to stop or configure OBSIDIAN_VAULT manually.

6. Obsidian Git choice.

   • Offer safe, manual, team-sync, or skip.
   • Explain that third-party download, community plugin enablement, and auto-sync are separate approvals.
   • For safe, apply plugin files only without enablement.
   • For manual, require approval before enabling the community plugin.
   • For team-sync, require approval and verify git remote/upstream first.
   • Do not offer automatic team-sync while preflight reports git.status != "usable".
   • If team sync is blocked, do not add remotes or push automatically. Show commands or offer safe/manual fallback.

7. Validate.

   • Run setup-vault.mjs validate.
   • If Obsidian Git was applied, run obsidian-git-setup.mjs validate.
   • Report project name, vault path, resolver source, setup-state status, Obsidian Git status, and remaining manual actions.

8. Official Codex hooks choice.

   • Explain that Codex hooks are officially supported but still modify Codex project or user config files.
   • Recommend repo-local because oh-my-obsidian is designed around a project-specific vault.
   • Offer repo-local, user-global, skip for now, or direct input.
   • For repo-local, run from the user's project directory or pass that directory with --repo-root; the helper normalizes it to the Git worktree root: node scripts/codex-hooks.mjs plan --mode repo-local --repo-root "<project-directory>" --vault "<vault-path>"
   • For user-global, run: node scripts/codex-hooks.mjs plan --mode user-global --vault "<vault-path>"
   • Summarize that config.toml enables [features].codex_hooks = true, hooks.json stores the SessionStart and Stop command hooks, .codex/oh-my-obsidian.local.json stores the user's approved vault pointer, and .codex/.gitignore prevents that machine-specific pointer from being committed.
   • If setup-state is action_required_env only because no resolver exists, repo-local hooks may complete setup by creating this project-local pointer.
   • Use this beginner-facing final guidance: 마지막 단계입니다. Codex가 이 프로젝트의 .codex 설정을 사용하도록 허용해 주세요. 그래야 이 프로젝트와 Obsidian vault가 자동으로 연결됩니다. 개인 vault 경로는 Git에 커밋되지 않습니다.
   • If automatic memory does not appear later, tell the user to allow this project's .codex/ settings in Codex, start a new Codex session from the project directory, then ask Show me the vault health check.
   • Apply only after explicit approval.
   • After apply, run setup-vault.mjs validate --vault "<vault-path>" again and report the codexHooks status.

9. Optional History Restore (non-blocking).

   • After validation, check if Codex session data exists by running: node scripts/codex-history.mjs scan --cwd "<current-working-dir>"
   • If sessions are found, offer restore using the four-choice interaction mode:

     Codex 세션 기록 N개를 발견했습니다. 볼트에 복원할까요?
     
     다음 중 하나로 답해주세요.
     1. 네, 복원해주세요 (권장)
     2. 나중에 $oh-my-obsidian-restore-history로 복원
     3. 건너뛰기
     4. 직접 입력
     

   • If user approves, run: node scripts/codex-history.mjs restore --vault "<vault-path>" --cwd "<current-working-dir>"
   • Report the result (number restored, number skipped, git commit status).
   • If any error occurs, print a warning and continue to the success message.
   • This entire step is non-blocking: failures do not affect setup status.

Re-Run Behavior

• If setup state is missing and the vault already exists, offer setup-vault.mjs attach --preflight-json "<saved-json-or-file>" only for a compatible no-overwrite attach. If the vault already has conflicting managed files or a stray .oh-my-obsidian directory, explain that manual cleanup or a fresh vault path is required before attach.
• If setup state is in_progress or failed, offer resume.
• If managed artifacts are missing, run reconcile dry-run first.
• Deletions, moves, overwrites, shell profile mutation, and .obsidian changes require a diff/dry-run and separate approval.
• Codex hooks installation and changes to .codex/config.toml, .codex/hooks.json, .codex/hooks/, or .codex/oh-my-obsidian.local.json require codex-hooks.mjs plan output and separate approval.

Output Style

Keep setup summaries concise and decision-oriented. Show the user what will be created or changed, what requires approval, and what remains manual.