Add cloned WAV examples

.github/workflows/project-her.yml

@@ -0,0 +1,68 @@
+name: Project-Her validation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: project-her-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  offline-contract:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.9", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+
+      - name: Install harness and build tooling
+        run: python -m pip install --upgrade pip build && python -m pip install -e .
+
+      - name: Compile and test offline contracts
+        run: |
+          python -m compileall -q voforge tests
+          python -m unittest discover -s tests -v
+          python -m json.tool voforge/schemas/project-her.schema.json >/dev/null
+
+      - name: Exercise Project-Her starter workflow
+        run: |
+          project-her init .project-her-smoke
+          project-her validate --config .project-her-smoke/project-her.json
+          project-her plan --config .project-her-smoke/project-her.json
+          project-her validate --config examples/f5-project-her.json
+          project-her plan --config examples/f5-project-her.json
+
+      - name: Build distributions
+        if: matrix.python == '3.12'
+        run: python -m build
+
+      - name: Verify packaged Project-Her contracts
+        if: matrix.python == '3.12'
+        run: |
+          tar -tf dist/voforge-0.6.0.tar.gz | grep 'docs/PROJECT_HER.md'
+          tar -tf dist/voforge-0.6.0.tar.gz | grep 'voforge/schemas/project-her.schema.json'
+          tar -tf dist/voforge-0.6.0.tar.gz | grep 'examples/project-her/project-her.json'
+          tar -tf dist/voforge-0.6.0.tar.gz | grep 'examples/f5-project-her.json'
+
+      - name: Upload distributions
+        if: matrix.python == '3.12'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: project-her-python-${{ matrix.python }}
+          path: dist/*
+          if-no-files-found: error

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Protonmatter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MANIFEST.in

@@ -0,0 +1,14 @@
+include examples/cast.json
+include examples/lines.json
+include examples/f5-project-her.json
+include LICENSE
+recursive-include docs *.md
+recursive-include voforge/schemas *.json
+recursive-include examples/project-her *.json
+prune examples/audio
+include examples/audio/NOTICE.md
+include examples/audio/README.md
+include examples/audio/manifest.json
+include examples/audio/reference-kokoro-af-heart.wav
+include examples/audio/clone-f5-systems-online.wav
+include examples/audio/clone-f5-synthetic-disclosure.wav

README.md

@@ -1,4 +1,4 @@
-# voforge
+# Project-Her / VOForge
 
 Batch neural voice-over generator with **tones, emotional styles, and voice
 cloning**. Feed it a list of dialog lines and a cast sheet; it renders one
@@ -9,6 +9,19 @@ Network is needed at **build time only** — the rendered pack ships with your
 project and plays offline. This is the generator behind VENTFALL's
 fully-voiced campaign (139 lines, seven actors).
 
+**Project-Her** is the end-to-end harness layered on VOForge: versioned model
+and voice selection, explicit per-component licenses, clone-consent evidence,
+deterministic run manifests, upgrade workflows, and a local stdio MCP server
+that any MCP-capable AI can use. Start with
+[`docs/PROJECT_HER.md`](docs/PROJECT_HER.md).
+
+```bash
+project-her init my-voice-project
+project-her validate --config my-voice-project/project-her.json
+project-her plan --config my-voice-project/project-her.json
+project-her render --config my-voice-project/project-her.json --confirm
+```
+
 ```bash
 pip install ./tools/voforge          # or: pip install git+https://github.com/Protonmatter/ventfall#subdirectory=tools/voforge
 voforge --lines lines.json --cast cast.json --out vo/
@@ -269,6 +282,14 @@ voforge.render(..., backend=voforge.make_backend("azure"))
 python -m unittest discover -s tests    # fully offline (FakeBackend)
 ```
 
+## Cloned WAV examples
+
+[`examples/audio/`](examples/audio/) contains a synthetic Kokoro reference and
+two F5-cloned WAV demonstrations with exact transcripts, seeds, checkpoint and
+artifact hashes, PCM measurements, and an explicit asset notice. They use no
+natural-person or game-character reference audio and are excluded from the MIT
+code license because the official F5 checkpoint is CC-BY-NC-4.0.
+
 ## Fidelity and promotion evidence
 
 See [`docs/VOICE_FIDELITY.md`](docs/VOICE_FIDELITY.md) for the reusable findings
@@ -281,7 +302,7 @@ that evidence path.
 
 ## License
 
-MIT, same as the repository. Voice audio is generated through third-party models
+Project-Her and VOForge source are MIT under [`LICENSE`](LICENSE). Voice audio is generated through third-party models
 or services; review the selected backend's terms. In particular, F5-TTS code is
 MIT but its official pretrained weights are CC-BY-NC. The Kokoro Python package
 declares Apache-2.0; model and packaged-voice terms must still be checked for the

docs/PROJECT_HER.md

@@ -0,0 +1,178 @@
+# Project-Her
+
+Project-Her is VOForge's end-to-end orchestration harness for selecting,
+upgrading, validating, and exposing voice-generation technology. It is not a
+new foundation model and it does not relicense third-party weights. The harness
+is MIT-licensed; every model, service, voice, reference, and generated asset
+keeps its own explicit license and provenance record.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    A["Project JSON\nlicense and revision pins"] --> B["ProjectHerHarness\nvalidate and plan"]
+    B --> C["VOForge backend\nEdge, Azure, XTTS, F5, Kokoro, ElevenLabs"]
+    C --> D["Candidate audio"]
+    D --> E["Evidence manifest\nhashes, PCM metrics, sources"]
+    E --> F["Human listening review"]
+    F --> G["Versioned promotion\nwith rollback artifact"]
+    H["Any MCP-capable AI"] --> I["Local stdio MCP\nread-only by default"]
+    I --> B
+```
+
+The old `voforge` CLI and Python API remain available. Project-Her is an
+additive policy layer that supplies the project registry, license checks,
+root-confined paths, run evidence, and MCP controls.
+
+## Quick start
+
+```powershell
+python -m pip install -e .
+project-her init .\my-voice-project
+project-her validate --config .\my-voice-project\project-her.json
+project-her plan --config .\my-voice-project\project-her.json
+project-her render --config .\my-voice-project\project-her.json --confirm
+```
+
+The starter selects an Edge stock voice and declares evaluation-only use until
+the operator reviews the governing Microsoft service terms. Change the model,
+voice, and license records before using it for a different purpose.
+
+`render` writes audio and `out/project-her-run.json`. The run record contains:
+
+- exact Project-Her and VOForge versions;
+- project, model, and voice revision/license records;
+- canonical hashes of the config and dialogue source;
+- a voice-registry hash;
+- output hashes and PCM measurements for WAV files;
+- result counts and bounded render logs.
+
+## Project contract
+
+Each `project-her.json` chooses one backend/model revision and maps dialogue
+speakers to versioned voice profiles. See
+[`voforge/schemas/project-her.schema.json`](../voforge/schemas/project-her.schema.json) and the
+complete [`examples/project-her`](../examples/project-her) starter.
+
+The examples root also includes `f5-project-her.json`, a non-commercial,
+hash-pinned reproduction profile for the anonymous seed-1792 systems-online take.
+It reuses the synthetic Kokoro reference and records the official F5 checkpoint
+revision, checkpoint hash, exact reference transcript, inference speed, seed,
+asset notice, and consent boundary.
+
+The important fields are:
+
+- `intendedUse`: `evaluation`, `non-commercial`, or `commercial`;
+- `model.revision`: a model release, service-managed revision, or checkpoint;
+- `model.license.allowedUses`: uses permitted by the reviewed model terms;
+- `voices.<id>.revision`: the selected voice/profile revision;
+- `voices.<id>.sourceSha256`: mandatory exact reference hash for a clone;
+- `voices.<id>.license`: terms for the stock voice or authorized reference;
+- `voices.<id>.consent`: required for cloned voices, with a durable evidence
+  locator rather than a secret or raw credential;
+- `output.force`: disabled by default;
+- `mcp.allowRender`: disabled by default.
+
+Project-Her rejects embedded API keys, tokens, passwords, and secrets. Hosted
+backends continue to read credentials from their documented environment
+variables.
+
+## Choosing and upgrading voices
+
+1. Add a new voice profile or update `revision`; do not erase the previous
+   approved config/run manifest.
+2. Set `source`, `license.id`, `license.source`, and `allowedUses` from the
+   actual release or service terms.
+3. For a clone, set `kind: "clone"`, provide an authorized reference and exact
+   transcript when required, then set `consent.granted: true` with a durable
+   consent evidence locator.
+4. Use a new output directory or stable versioned line IDs for the candidate.
+5. Run `validate`, then `plan`, then `render --confirm`.
+6. Apply objective PCM/hash gates and a human listening test. Similarity,
+   warmth, accent, and emotion are human-review claims unless separately
+   calibrated.
+7. Promote only the approved hash with `voforge.promote_artifact`, retaining a
+   known rollback artifact.
+
+For F5, pin the checkpoint/revision and keep a fixed seed on every line. The
+official F5 checkpoint currently used by the examples is CC-BY-NC-4.0, so it
+cannot satisfy a Project-Her project declaring `intendedUse: "commercial"`.
+
+## Local MCP server
+
+Project-Her implements the MCP `2025-06-18` lifecycle and newline-delimited
+stdio transport without an additional Python dependency. Start it with:
+
+```powershell
+project-her-mcp --config C:\absolute\path\project-her.json
+```
+
+Generic client configuration:
+
+```json
+{
+  "mcpServers": {
+    "project-her": {
+      "command": "project-her-mcp",
+      "args": ["--config", "C:\\absolute\\path\\project-her.json"]
+    }
+  }
+}
+```
+
+Any MCP-capable AI can then discover these read-only tools:
+
+- `project_her_capabilities`
+- `project_her_validate`
+- `project_her_plan`
+- `project_her_voice_registry`
+
+Rendering is intentionally absent by default. To expose it, both conditions
+must be true:
+
+1. set `mcp.allowRender` to `true` in the fixed project config;
+2. start the server with `--allow-render`.
+
+Every render call must additionally contain exactly `{"confirm": true}`. MCP
+never force-overwrites an output, accepts no client-supplied config path, runs
+sequentially over local stdio, and rate-limits tool calls. These controls follow
+the official MCP guidance that tool inputs be validated and sensitive actions
+remain visible to a human:
+
+- <https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle>
+- <https://modelcontextprotocol.io/specification/2025-06-18/basic/transports>
+- <https://modelcontextprotocol.io/specification/2025-06-18/server/tools>
+
+## License matrix
+
+| Component | Governing boundary |
+|---|---|
+| Project-Her and VOForge source | Repository [`LICENSE`](../LICENSE), MIT |
+| F5-TTS source | Upstream F5-TTS source license |
+| Official F5 pretrained checkpoint | Upstream checkpoint terms; current examples record CC-BY-NC-4.0 |
+| Kokoro package | Upstream package license; the selected model/voice release must also be recorded |
+| Edge, Azure, ElevenLabs | Applicable service and voice terms, recorded per project |
+| XTTS | Upstream code/model terms plus the reference speaker's authorization |
+| Voice references and generated audio | Their own provenance, consent, model, and project-use terms; not automatically MIT |
+
+This is an engineering license boundary, not legal advice. A license identifier
+in a config records an operator's review; it does not create rights that the
+upstream terms do not grant.
+
+## CI and release workflow
+
+`.github/workflows/project-her.yml` performs offline syntax/tests, scaffolds and
+validates a starter project, exercises a dry plan and MCP lifecycle, builds the
+wheel/source distribution, and checks packaged files. It deliberately does not
+download heavyweight checkpoints, invoke paid APIs, or render a live service
+voice. Those belong in an explicitly authorized model-specific validation job.
+
+Release gate:
+
+1. offline unit and protocol tests pass;
+2. schema/config and license-use validation pass;
+3. source and wheel builds succeed;
+4. a model-specific candidate render completes in its pinned environment;
+5. artifact hashes and PCM gates pass;
+6. a named human reviewer approves the exact candidate hash;
+7. promotion is additive and retains a rollback hash.

examples/audio/NOTICE.md

@@ -0,0 +1,25 @@
+# Audio example notice
+
+The WAV files in this directory are demonstration assets, not natural-person
+identity samples and not StarCraft-derived audio. They are excluded from the MIT
+license covering VOForge's source code.
+
+`reference-kokoro-af-heart.wav` was synthesized from original VOForge text with
+Kokoro 0.9.4, voice `af_heart`, and the `hexgrad/Kokoro-82M` v1.0 model. The
+Kokoro model repository declares Apache-2.0.
+
+The two `clone-f5-*.wav` files were generated from that synthetic reference with
+F5-TTS 1.1.22 and the official `SWivid/F5-TTS` `F5TTS_v1_Base` checkpoint. That
+checkpoint repository declares CC-BY-NC-4.0. The cloned WAVs are provided solely
+as non-commercial technical demonstrations under that same conservative use
+boundary. Do not use them to imply a real speaker's identity, endorsement, or
+consent.
+
+Upstream terms:
+
+- Kokoro: <https://huggingface.co/hexgrad/Kokoro-82M>
+- F5-TTS checkpoint: <https://huggingface.co/SWivid/F5-TTS>
+- F5-TTS code: <https://github.com/SWivid/F5-TTS>
+
+This notice is an engineering boundary, not legal advice. Review current
+upstream terms before redistributing or using these assets.

examples/audio/README.md

@@ -0,0 +1,19 @@
+# Cloned WAV examples
+
+These files demonstrate VOForge reference-conditioned synthesis without using
+a natural person's voice or a game character. The reference was generated with
+the Apache-2.0 Kokoro model and the two new lines were cloned from that synthetic
+reference with the official F5-TTS checkpoint.
+
+- [Synthetic Kokoro reference](reference-kokoro-af-heart.wav) — the source
+  performance and exact transcript used by F5.
+- [F5 clone: systems online](clone-f5-systems-online.wav) — seed 1792, default
+  32 inference steps.
+- [F5 clone: synthetic disclosure](clone-f5-synthetic-disclosure.wav) — seed
+  4701, default 32 inference steps.
+
+[`manifest.json`](manifest.json) records the exact text, seeds, model revisions,
+checkpoint hashes, inference settings, output hashes, and PCM measurements.
+
+These audio assets are excluded from VOForge's MIT code license. Read
+[`NOTICE.md`](NOTICE.md) before reuse.