setup

PhilLit workspace setup

Run this once in the directory where the user will create reviews.

Communication style: keep every user-facing message to a sentence or two of plain, non-technical language. Do everything you can on the user's behalf; ask only for what only they can provide.

1. Open with what this is. Before running anything, tell the user in 1–2 sentences, e.g.: "Let's set up PhilLit in this folder — a one-time step. I'll create the configuration for you; I'll only need your email address and one free API key."
2. Check the environment. Run [ -x "${PHILLIT_ROOT:-}/bin/phillit-run" ] && echo ok || echo missing, command -v uv, and command -v jq.
   • If the first check prints missing, the plugin's environment isn't loaded in this session (PHILLIT_ROOT unset, empty, or stale — typically the plugin was installed or updated mid-session; the bridge only runs at session start), so every later step would fail with a cryptic "No such file or directory". Tell the user: "One quick step: please restart Claude Code in this folder, then run /phillit:setup again." and stop.
   • If uv or jq is absent, give a one-line install instruction (uv: https://docs.astral.sh/uv/getting-started/installation/ ; jq: brew install jq / apt install jq / choco install jq) and stop — jq is required by the BibTeX-validation hook and is otherwise a silent clean-install failure.
3. Preview and ask consent. Run: bash "$PHILLIT_ROOT/bin/phillit-run" skills/setup/scripts/setup_workspace.py --plugin-root "$PHILLIT_ROOT" --dry-run Then summarize what will happen in 2–3 short bullets — do not dump the settings JSON (show it only if the user asks for details):
   • Creates a .phillit folder marker and, for any API keys not already set in the environment, a .env file to hold them (keys found in the environment are used from there — never copied into a file)
   • Lets Claude run PhilLit's research tools in this folder without asking permission each time; deleting files and system-level commands still require approval
   • Nothing is sent or published anywhere Ask whether to proceed.
4. Apply. On approval, run the same command without --dry-run. Keys already set in the user's environment stay there — the script never copies their values into .env; it prints which ones it found (and skips creating .env when it found them all). If it found some, tell the user (e.g. "Your Brave key was already set up — I'm using it from your environment.").
5. Collect the rest. Ask only for what is still missing, and be explicit about required vs. optional. Edit .env yourself with the answers (uncomment the key's # KEY= line and add the value) — don't make the user open a file. Keys the user skips stay commented: an active empty KEY= line would override that key with "" if the user ever exports it in their shell.
   • Required:
     • CROSSREF_MAILTO — just the user's email address; ask for it and fill OPENALEX_EMAIL with the same address
     • BRAVE_API_KEY — the one thing the user must obtain themselves: a free key from https://brave.com/search/api/
   • Optional (skipping is fine): S2_API_KEY (https://www.semanticscholar.org/product/api) and CORE_API_KEY (https://core.ac.uk/services/api) improve search coverage and speed.
6. Verify. Run bash "$PHILLIT_ROOT/bin/phillit-run" skills/philosophy-research/scripts/check_setup.py and report in one line: "Setup complete — ask me for a literature review whenever you're ready", or exactly what is still missing and how to fix it.
7. Trust check. Settings changes reload live, but Claude Code ignores the new allow rules until the workspace is trusted. Check (prefer the $PWD entry; fall back to the physical path only when $PWD has no entry at all — under a symlinked cwd, e.g. OneDrive or /var → /private/var, .claude.json may key either form):

   CFG="${CLAUDE_CONFIG_DIR:+$CLAUDE_CONFIG_DIR/.claude.json}"
   jq -r --arg d "$PWD" --arg p "$(pwd -P)" \
     '((.projects[$d] // .projects[$p] // {}).hasTrustDialogAccepted // false)' \
     "${CFG:-$HOME/.claude.json}"
   

   • If true (or the check itself fails): say nothing — permissions are already live.
   • If false: end the setup with this, prominently, as the final line: "One last step: restart Claude Code in this folder and choose 'Yes, I trust this folder' when asked — PhilLit's permissions only take effect after that."
8. Updates tip. Close with one sentence: "PhilLit doesn't update automatically — to change that, open /plugin, go to Marketplaces, and turn on auto-update for phillit (or run /plugin update phillit@phillit whenever you want the latest)."