Getting Started

Prerequisites

Use a current Node.js LTS release and npm. The project is TypeScript, but ordinary CLI use happens through the published package or npx; you do not need a separate global installation.

git clone https://github.com/shashank-sn/holdyourvoice.git
cd holdyourvoice
npm install
npm test

npm test compiles the TypeScript and runs the regression suite. Run it before relying on a changed checkout.

Prepare your local files

Create a directory that never enters source control:

samples/
  one.md
  two.md
draft.md

The profile is only as useful as its samples. Prefer complete pieces from one writer. Do not mix ghostwritten, heavily edited, translated, or radically different-format samples unless that blend is genuinely the voice you want to reproduce.

1. Build a profile

npx holdyourvoice profile profile.json samples/one.md samples/two.md

This calculates a portable JSON profile. It records the number of samples, a schema version, 13 aggregate VoiceDNA measurements, and an optional avoid list. profile requires at least two sample paths; it fails clearly with fewer.

Keep profile.json local when it derives from private writing. A profile contains aggregates, not source text, but vocabulary and style signals can still be sensitive.

2. Inspect a draft

npx holdyourvoice analyze draft.md profile.json

The JSON result has two independent reports:

{
  "voiceDna": { "score": 93, "passed": true, "findings": [] },
  "aiEditor": { "score": 88, "passed": true, "findings": [] },
  "passed": true
}

Read each report before looking at the aggregate passed field. A good AI Editor result does not establish voice fidelity; a good VoiceDNA result does not excuse a red editorial problem.

3. Produce an editing brief

npx holdyourvoice rewrite-prompt draft.md profile.json > rewrite-brief.md

Give the resulting brief and draft to a human editor or the model you choose. The tool does not call that model. The brief says which sentences were flagged, why, and which constraints outrank others.

Do not request a “better version of everything.” Ask for only the replacement sentences keyed by sentence number. This makes the candidate reviewable and protects clean copy.

4. Verify a candidate

npx holdyourvoice verify draft.md candidate.md profile.json

verify reruns VoiceDNA and AI Editor on the candidate, compares it to the baseline draft, and calculates a coarse preservation score. It exits non-zero if either engine fails, a new red finding appears, or preservation drops below 70. Treat that exit code as a release gate in scripts and CI.

Useful commands

Command	Use it when
`profile <out.json> <samples...>`	You need a new local VoiceDNA profile.
`analyze <draft> <profile.json>`	You need independent reports before editing.
`rewrite-prompt <draft> <profile.json>`	You need a tiered, line-targeted brief.
`verify <original> <candidate> <profile.json>`	You need the candidate gate.
`patterns`	You need the exact currently executable AI Editor rules.

First-run mistakes

Using one sample. Add a second representative sample; the CLI intentionally rejects this.
Publishing inputs by accident. Add samples/, drafts, and profiles to your personal .gitignore.
Treating yellow as an automatic rewrite. Yellow is a review cue. Preserve a clean sentence if the suggested change would make it worse.
Skipping verification. The rewrite brief is the first check; verify is the release check.