Setting up without a terminal

Node.js is the runtime that powers Tusk's Tomes. One install, then you never see it again.

1. Go to https://nodejs.org.
2. Click the big green LTS button (LTS = "long-term support" = the stable version).
3. Run the installer. Defaults are fine — click Next, Next, Install.
4. Restart your computer if it asks you to.

That's it. You don't need to "do anything" with Node — just installing it makes the launcher scripts work.

---

Skip this step if you don't need audio transcription. You can always come back later when you decide you want it. The Audio Transcription add-on (which needs Python) unlocks Craig multitrack uploads and direct audio-to-text. If you're starting from YouTube .sbv captions or pasting transcripts directly, you'll never touch Python.

1. Go to https://python.org/downloads.
2. Click the big yellow Download Python 3.12 button (or 3.10 or 3.11 — any of those three).
3. Run the installer. Important: tick the box that says "Add python.exe to PATH" at the bottom of the first screen. Then click Install Now.
4. Restart your computer.

---

You have two options here. Option B is recommended because it gets you one-click updates from inside the app.

Option A — Download the ZIP (no Git needed)

1. Go to https://github.com/KochiTusker/Tusks-Tomes.
2. Click the green <> Code button at the top, then Download ZIP at the bottom of the dropdown.
3. Find the file in your Downloads folder. Right-click → Extract All… Pick a folder you'll remember, like Documents\Tusks-Tomes.

Trade-off: the in-app updater needs Git, so if you go the ZIP route you'll have to re-download a fresh ZIP whenever a new version drops. Most updates take 30 seconds; this isn't a big deal.

Option B — Clone with Git (one-click updates later)

1. Install Git for Windows from https://git-scm.com/download/win — defaults are fine.

2. Right-click in any folder where you want Tusk's Tomes to live, and click Open in Terminal (or open Command Prompt and cd to that folder).

3. Type this and press Enter:

   git clone https://github.com/KochiTusker/Tusks-Tomes.git
   

   This creates a Tusks-Tomes/ folder with the code in it.

About the folder name: if you're also using Tusk's Vault, keep both repos as siblings — for example, Documents\Tusks-Tomes\ and Documents\Tusks-Vault\. The two find each other automatically when they're sitting next to each other. Don't rename Tusks-Tomes to something else, or sibling auto-detection won't work.

---

1. Open the folder where you put Tusk's Tomes.
2. Double-click setup.bat. A black window opens. It will:
   • Confirm Node and Git are present (prints exact winget install commands for anything missing).
   • Detect your GPU (reports only — no install).
   • Copy .env.example to .env.
   • Install the Node packages (~1 minute).
3. When it says "Setup complete", close the window.

setup.bat is plain readable text — open it in Notepad first if you want to see exactly what it does. About 60 lines, no admin elevation, no system-wide installs.

---

1. Double-click Start_Tusks_Tomes.bat.
2. A black window opens and says "Starting on http://localhost:5173". Wait ~5 seconds.
3. Your browser auto-opens to the dashboard.
4. Leave the black window open — closing it stops the server.

---

Everything below happens in your browser. No code, no config files.

1. Add an LLM API key. Settings → Providers & models → paste a Gemini or OpenRouter key → Save.
   • Don't have one yet? See providers.md for paid-key sign-up walkthroughs. (Gemini Pro moved behind billing in 2026 — a paid key is required for the main pipeline; the project has been engineered to keep that bill small.)
   • Want to run fully offline? Install Ollama, start it, then use Detect in Settings → Providers & models. There is nothing to install on the Tomes side.
2. (Optional) Install Audio Transcription. If you want to upload Craig recordings or transcribe audio files directly: Settings → Transcription → Install. This downloads the Whisper sidecar (roughly 1.5 GB) and requires Python from Step 2. Restart Start_Tusks_Tomes.bat when prompted. This is the only module that installs anything.
3. Drop in your campaign lore. Tome of Lore tab → upload PDFs / Word docs / notes. Add Glossary entries for proper nouns the model would otherwise mangle.
4. List your players. Same tab → Speakers card → add a row per player with their player name + character name.
5. Chronicle a session. Either paste a transcript into the Chronicle tab, or follow one of the two workflows.

---

Same idea, terminal-flavoured:

# 1. Install Node 20+, Python 3.10-3.12 (optional), Git, ffmpeg
# macOS:  brew install node python git ffmpeg
# Debian: sudo apt install nodejs npm python3 python3-venv git ffmpeg
# Fedora: sudo dnf install nodejs npm python3 git ffmpeg
# Arch:   sudo pacman -S nodejs npm python git ffmpeg

# 2. Clone
git clone https://github.com/KochiTusker/Tusks-Tomes.git
cd Tusks-Tomes

# 3. One-time setup
bash setup.sh

# 4. Run any time
bash start.sh                       # or: npm run dev

setup.sh is optional — start.sh will install dependencies on first launch too. To stop: Ctrl+C in the terminal, or close the window.

---

• Stop: close the black window (Windows) or Ctrl+C in the terminal (macOS / Linux).
• Start: double-click Start_Tusks_Tomes.bat (Windows) or run bash start.sh (POSIX).

Your keys, lore, glossary, model profiles, and chronicles are all saved — Tomes picks up exactly where you left off.

---

The fastest way to get unstuck right now is the feedback form — the maintainer reads every submission. A community Discord with a #support channel of fellow DMs is on the roadmap; the form is what we have until enough interest signals it's worth spinning one up.

If you'd rather file a written issue, open one on GitHub — the templates ask for exactly the info needed.