Setup

Set up the user's voice home: a private folder that holds their profiles, rounds, lessons, feedback and holdout texts. Run this the first time the user uses Voice Forge, when no voice home is found, or when the user asks for vf-setup.

All steps use python3 <skill>/scripts/vf.py. Without a shell, explain the steps and give the user the commands to run.

1. Choose the folder

Ask: "Where should your private voice folder live? Press enter for ~/.voice-forge, or type another path."

2. Create or find it

Run vf.py setup --path <path>. Add --profile default-en or --profile default-es if the user wants a first profile now (ask which language they write in most). The command:

creates the folder, a first commit and the settings file, or
finds an existing voice home (for example a clone of the user's private repo) and changes nothing in it, and
saves the location in ~/.config/voice-forge/config.json, so every agent finds it, even apps that do not read shell variables.

If it reports that the folder holds unrelated files, ask for another path. Never move or delete the user's files.

If the output says a GitHub repo is already linked and private, go to step 5.

If it says privacy could not be checked, ask: "Is the repo at <address> private on GitHub?" Only on a clear yes, run vf.py github --confirm-private. If the user is not sure, ask them to check on GitHub first. Never push to a repo that might be public.

3. Offer a private GitHub repo

If no repo is linked, explain in two or three short sentences: a private GitHub repo backs up the voice home and lets the user train on several computers. Everything still works without it. Then ask: "Create a private GitHub repo now? (yes / no)"

no: fine. Say they can run vf-setup again anytime. Go to step 5.
yes: go to step 4.

4. Create the repo

Ask for the name, default voice-forge-private.
Run vf.py github --name <name>.
If it says the GitHub CLI is missing or the user is not signed in, give the user the exact steps it prints (gh auth login opens a browser to sign in), wait for them, and run it again. If the user prefers not to install the CLI, give the manual route the command prints.
Confirm from the output that the repo is private. If it reports a public repo, stop and tell the user to make it private before anything else.

5. Explain what happens from now on

Tell the user, briefly:

Before each Voice Forge session, the skill gets the latest version (vf.py sync).
After every change (a round, a lesson, a rule, feedback, a holdout text), it saves and pushes (vf.py save).
Auto push is on. They can turn it off with vf.py settings --auto-push off.
On another computer: install the skill, clone the private repo (git clone <address> ~/.voice-forge), then run vf-setup. It finds the folder and links everything.

Then suggest the next step: vf-new to create a profile, or vf-train default-en.