Privacy & sync
Your voice home contains personal writing. Keep it outside the app repository and use a verified private remote if you want backup.
Two folders, two purposes
| Location | Contents |
|---|---|
App checkout, such as ~/voice-forge |
Skill instructions, helper scripts and synthetic examples |
Voice home, normally ~/.voice-forge |
Base rules, profiles, rounds, analyses, samples, holdouts, evaluations and feedback |
The voice home lookup order is VOICE_FORGE_HOME, the path saved in ~/.config/voice-forge/config.json, then ~/.voice-forge. Do not place a personal profiles/ directory in the app checkout.
The complete file reference documents each file. Public examples on this site are the repo's intended invented examples and synthetic guide excerpts.
What automatic sync does
The skill calls vf.py sync once before the first voice-home read in a session. It calls vf.py save after changes. These commands can commit voice-home changes and push to a remote verified as private.
Offline work can keep a local commit for the next successful push. A conflict stops further changes until it is resolved. The helper never force pushes or rewrites history. It refuses to push to an unverified or public remote.
To inspect or disable automatic pushing, run from the app checkout:
python3 skills/voice-forge/scripts/vf.py settings
python3 skills/voice-forge/scripts/vf.py settings --auto-push off
Setup asks before creating a private GitHub repository. Local-only use works without one. The privacy guard protects the helper's push path; your chosen agent and model still process the text you supply under that client's own settings.
Use a second computer
- Install the app and its skills there.
- Clone your private voice-home repository into the location you want, normally
~/.voice-forge. - Run
/vf-setupin that computer's agent and point it to the existing folder.
Your location setting is per computer. Linked skills refer to that computer's app folder. Do not solve a conflict by overwriting one machine's voice home with another.
Plain chat packets
cd ~/voice-forge
python3 scripts/build.py packet --profile explainer-en
A packet includes the main skill, reference instructions, base rules and one profile's rules, lessons and topics. It can include samples and recent rewrite excerpts. It is private data, not a public plugin distribution.
A chat app cannot run the helper scripts or save your local files. Training returns round and lesson blocks for you to save. Mechanical checks are manual; a same-agent review is labeled as such. Rebuild the packet after training or rule updates.
Keep packets out of public websites, issues and repositories. The app's root dist/ is ignored for this reason. The documentation deployment uses a separate website/dist/ containing only reviewed public documentation.
Holdouts and feedback
Holdouts are for tests you start, never for training, drafting or analysis. Listing them returns names only. The overlap check compares paragraphs against samples, rounds and analyses.
Feedback is saved privately in feedback.md. If you report a plugin problem publicly, remove excerpts, samples, profile rules and other personal material first. No website feature sends your voice home to the documentation site.
What this website publishes
The public artifact includes these guides, the sixteen skill entry points, the seventeen current reference documents, generated command help, credits and three invented profile examples. Search runs in your browser over the same public text.
It excludes your voice home, root chat packets, manuscripts, evaluation records, development plans, tests, legacy code and repository history. The exact source allowlist is enforced by the build. New skills or reference files require review before publication; existing approved sources are rendered afresh on every build.