Underworld Writer

Release artwork: Rock-Hardened supplies changelog/release evidence; Underworld Writer owns the visual design contract in assets/branding/release-brand.json. The immutable visual template is assets/branding/underworld-writer-release-changelog-template.svg, imported byte-for-byte from ArtPatch. npm run release:art regenerates only the declared changelog-driven text zones; npm run release:art:check verifies the committed artwork is current.

Current version: 2.4.0
Multi-purpose character development, fact-sourced true-crime editorial tooling, and segment-first podcast/article production — with a full episode post-production pipeline.

What Underworld Writer does

Underworld Writer supports three primary workflows:

1. Creative fiction — three-phase character and narrative-world development.
2. True-crime / investigative editorial work — evidence-aware narrative construction with source attribution and PACER-informed verification workflows.
3. Podcast + article production — deterministic, segment-first editorial packages that can produce long-form scripts, articles, producer materials, and downstream audio inputs from a shared evidence package.

v2.4.0 highlights

• Deterministic post-production mixer (modal/audio/postproduction.py) — semantic cue markers so timing survives TTS duration changes, narration ducking, fades, music beds, stingers, and intro/outro cues; WAV master + 192 kbps MP3 delivery.
• Fail-closed music/SFX rights-clearance registry — a release render refuses to run until every referenced asset is approved with a recorded license/provenance record. Nothing fake ships as a placeholder.
• Self-generated music/SFX pipeline (modal/generate_production_audio.py) — a $0, open-weight alternative to licensing stock audio: ACE-Step 1.5 (Apache-2.0) for music, Stable Audio Open 1.0 (free under $1M annual revenue) for short SFX. Reproducible via committed prompt/seed manifests; a human still has to listen and approve before anything ships. See docs/ops/MODAL_PRODUCTION_AUDIO.md.
• Verified voice-reference intake for Chatterbox narration, with checksum-enforced sync into Modal storage. See docs/guides/VOICE_INTAKE.md.
• npx fix — dist/cli.js now ships with its executable bit set (npm run build chmods it automatically), fixing npx @h4shed/skill-underworld-writer and the linked underworld-writer bin.
• Claude Code plugin secrets onboarding — Modal/npm tokens are entered through the plugin's userConfig prompts (Claude's secure per-user storage), not committed placeholders; a SessionStart hook writes Modal credentials into ~/.modal.toml automatically. See Claude Code plugin below.
• Documentation reorganization: fixed broken links left by earlier moves, consolidated navigation, archived superseded plans.

v2.3.x highlights

The 2.3.x line hardens audio production, editorial quality, licensing, and the release/publish pipeline on top of the 2.2.x workspace contract.

• Two-pass loudness-normalized mastering — episode audio mastering now uses ffmpeg EBU R128 loudnorm true-peak limiting (targets read from modal/config/render_profiles/podcast-standard.json) instead of a sample-peak clip limiter.
• Configurable editorial language linter (src/editorial-lint.ts) — banned/discouraged/preferred-term checking, repeated-opening/transition/n-gram detection, driven by templates/editorial/style-dictionary.json and wired into npm run editorial:lint.
• Chunk-level synthesis cache (modal/cache/chunk_cache.py) — resumable episode rendering after a partial failure, keyed on chunk text + voice profile + reference-audio hash + backend revision.
• Local, scoped-token npm publish CLI (npm run publish:npm) — git/npm-auth safety checks, full release-evidence pipeline, then publish and tag; authenticates via a scoped UW_NPM_TOKEN (falling back to npm login). See docs/ops/PUBLISHING.md.
• Relicensed from Apache-2.0 to a custom non-commercial license (Unlicense base + Fused Gaming Non-Commercial Rights Amendment) — see License.
• PRIVACY.md added at the repository root and in .claude-plugin/, documenting the no-telemetry, mock-by-default PACER, and opt-in Modal audio posture.
• Root-directory cleanup — operational docs moved into docs/ops/ and historical reports into docs/archive/; see Documentation structure below.

v2.2.x highlights

The 2.2.x line moves Underworld Writer from a collection of generation utilities into a structured editorial workspace that can be used consistently by humans and agents such as Claude, ChatGPT, Codex, Cursor, Copilot, and MCP-based automation.

Canonical output workspace

Generated and producer-facing artifacts now have one canonical root:

output/
├── SERIES_REGISTRY.json
├── examples/
└── <series-slug>/
    ├── SERIES_CONFIG.json
    ├── production/
    └── season-<n>/
        ├── SEASON_CONFIG.json
        └── episode-<n>/
            ├── EPISODE_CONFIG.json
            ├── planning/
            ├── scripts/
            ├── producer-briefs/
            ├── published-assets/
            ├── verification/
            └── provenance/

Repository boundaries are explicit:

projects/   source material, research, evidence, and editorial package specifications
output/     generated editorial and production artifacts
src/        runtime and library implementation
scripts/    generators, validation, release tooling, and workspace automation

Legacy/demo output belongs under output/examples/ instead of competing root-level output directories.

Cross-agent workspace contract

The repository carries both human-readable and machine-readable rules so future agents do not invent new directory conventions.

• AGENTS.md — authoritative repository contract
• CLAUDE.md — Claude entry point referencing the shared contract
• .github/copilot-instructions.md — Copilot entry point
• output/SERIES_REGISTRY.json — registered podcast series
• schemas/podcast/ — registry, series, season, and episode schemas
• scripts/validate-output-structure.mjs — workspace validator
• validation-tests/workspace-contract.test.mjs — fixture-based positive/negative validation

Run preflight before agent-driven editorial work:

npm run agent:preflight

Series / season / episode scaffolding

Agents should scaffold canonical workspaces instead of manually creating directories.

npm run podcast:new-series -- my-series "My Series"
npm run podcast:new-season -- my-series 1
npm run podcast:new-episode -- my-series 1 1
npm run validate:workspace

Generated manifests carry generator/version metadata so workspaces can be traced back to the contract that produced them.

Segment-first editorial packages

Long-form podcast and article output is now built from composable editorial blocks instead of treating one giant Markdown file as the source of truth.

projects/<series>/episode-packages/season-<n>/episode-<n>.json
                         │
                         ▼
               editorial package engine
                    /           \
                   /             \
        podcast segments       article segments
              │                      │
              ▼                      ▼
      scripts/segments/      published-assets/articles/
              │                      │
              └──── assembled derivative views ────┘

The episode package is authoritative. Assembled scripts/articles are derived producer-facing views.

Generate an editorial package:

npm run editorial:generate -- --series insight-corruption --season 1 --episode 1

Validate without writing output:

npm run editorial:check -- --series insight-corruption --season 1 --episode 1

Reusable blocks

templates/editorial/shared-segments.json provides reusable blocks for recurring production material such as:

• series intros
• evidence/source disclosures
• transitions
• sponsor / house-ad slots
• outros
• calls to action
• article deks and source notes

Case-specific evidence remains in the episode package while repeatable editorial structure can be shared across episodes and seasons.

Insight Corruption reference implementation

Insight Corruption is the first full series using the v2.2.x workspace and editorial-package model.

Canonical locations:

projects/insight-corruption/                         # source/research/configuration
projects/insight-corruption/episode-packages/        # editorial source packages
projects/insight-corruption/production/voice/        # reusable audio-generation specification
output/insight-corruption/                           # generated series output
output/insight-corruption/season-1/episode-1/        # generated Episode 1 package

Episode 1 validation baseline

The Episode 1 reference package currently validates at:

• 13 podcast segments
• 4,092 scripted words
• 29.52 estimated minutes at 145 WPM, including the fixed 90-second mid-roll
• Runtime validation: PASS against a 30 ± 1 minute target
• 1,864-word LinkedIn article
• Article validation: PASS against the configured 1,800–2,300 word target

The podcast and LinkedIn article reuse the same vetted evidence/claim package rather than independently rewriting the case facts.

Authorized voice-production architecture

The reusable synthetic-voice production specification lives at:

projects/insight-corruption/production/voice/VOICE_PODCAST_GENERATION.md

It documents the intended Modal-based production architecture, authorized reference-voice handling, segment-level synthesis/retries, ASR critical-token verification, mastering, provenance, benchmarking, and cost controls.

The specification is project-level infrastructure and is not tied to a single episode.

Quick start

Install

npm install @h4shed/skill-underworld-writer

Run without installing (npx)

npx @h4shed/skill-underworld-writer create --name "Hades" --role "Lord" --faction "Olympian"

Development

npm install
npm run build
npm test

Character workflows

underworld-writer create --name "Hades" --role "Lord" --faction "Olympian"
underworld-writer export --file character.json --output character.md
underworld-writer validate-script --character character.json

The original character-development, true-crime adaptation, PACER verification, MCP tooling, Markdown export, and relationship-validation APIs remain supported alongside the newer editorial workspace.

Claude Code plugin

Underworld Writer is published to the Fused Gaming Claude Code marketplace (.claude-plugin/marketplace.json).

Install

/plugin marketplace add Fused-Gaming/underworld-writer
/plugin install underworld-writer@fused-gaming

Claude Code auto-discovers the root SKILL.md as the plugin's skill; character creation, true-crime verification, and podcast-production workflows all work immediately with no configuration.

Optional: audio production secrets

Character/narrative/editorial features need no configuration. If you also want episode audio synthesis, mastering, or the self-generated music/SFX pipeline (all Modal-based), enabling the plugin prompts for three optional, individually-optional values, defined in .claude-plugin/plugin.json's userConfig:

| Value | Needed for | Where to get it | | --- | --- | --- | | modal_token_id / modal_token_secret | Audio synthesis, mastering, self-generated music/SFX | modal.com/settings/tokens | | uw_npm_token | Cutting an npm release (maintainers only) | A scoped npm automation token — see docs/ops/PUBLISHING.md |

These are entered through Claude Code's own secure per-user configuration prompt — never committed to this repo, never written into a shared settings file. A SessionStart hook (scripts/plugin-onboard-secrets.sh) writes the Modal credentials into ~/.modal.toml (the real file Modal's own CLI/SDK reads) automatically once entered, via modal token set. See docs/ops/MODAL_SETUP.md for the equivalent manual flow if you're not using the plugin.

Validation and benchmarks

Workspace validation:

npm run validate:workspace
npm run test:workspace

Episode 1 editorial fixture:

npm run test:episode1

Benchmarks:

npm run benchmark:workspace

The v2.2.0 baseline recorded on Node 22 measured approximately:

| Workspace operation | Baseline | | --- | ---: | | Registry lookup | 0.000238 ms/op | | Canonical path construction | 0.001439 ms/op | | Config validation | 0.000249 ms/op |

These microbenchmarks are regression indicators, not cross-machine performance guarantees.

Release validation with Rock-Hardened

Underworld Writer uses @h4shed/rock-hardened for changelog validation and deterministic release evidence.

npm run version:check
npm run rock:validate
npm run rock:evidence     # manifest, SBOM, release cards, attestation
npm run rock:manifest
npm run release:art
npm run release:art:check
npm run validate:release
npm run release:evidence
npm run publish:npm       # local, scoped-token CLI publish (see docs/ops/PUBLISHING.md)

validate:release combines:

• release-version checks
• canonical workspace validation
• Rock-Hardened changelog validation
• workspace contract fixtures
• Episode 1 runtime/article validation
• TypeScript build
• Jest tests
• workspace benchmarks

Release artwork uses repository-owned branding: Rock-Hardened provides release/changelog data, while assets/branding/release-brand.json and the approved ArtPatch SVG control the Underworld Writer composition. Agents must not redraw the approved release design from primitive SVG shapes.

Versioning

The package follows Semantic Versioning.

• 2.2.0 — canonical workspace, cross-agent contract, scaffolding/validation, segment-first podcast/article packages, Rock-Hardened release evidence, and the Episode 1 long-form reference package.
• 2.2.1 — patch release branch for release-branding/version-alignment follow-up work and refreshed root documentation.
• 2.3.0 — two-pass loudness-normalized mastering, configurable editorial linter, chunk-level synthesis cache, local npm publish pipeline, relicense to a custom non-commercial license, PRIVACY.md, and root-directory doc cleanup.
• 2.3.1 — scoped UW_NPM_TOKEN publish-auth support for the CLI publish pipeline.
• 2.3.2 — root README refresh: current version tags, v2.3.x feature highlights, fixed doc links, documentation-structure overview.
• 2.4.0 — deterministic post-production mixer, fail-closed asset-clearance registry, self-generated music/SFX pipeline, verified voice-reference intake, npx executable fix, Claude Code plugin secrets onboarding, documentation link cleanup.

Primary release metadata is tracked through package.json, plugin.json, VERSION.json, source exports, and the changelog. Use the version tooling rather than manually changing only one surface:

npm run version:check
npm run version:sync

Repository map

AGENTS.md                       agent contract
CHANGELOG.md                    release history / release-art source
VERSION.json                    release ledger and benchmark evidence
assets/branding/                release-brand contract/assets
docs/                           deeper documentation
output/                         canonical generated content
projects/                       source research and editorial packages
schemas/podcast/                workspace schemas
scripts/                        generation/validation/release tooling
src/                            TypeScript package implementation
templates/editorial/            reusable editorial blocks
validation-tests/               workspace contract tests

MCP / agent integration

Underworld Writer remains MCP-compatible and can be registered with agent ecosystems for character development, validation, export, and editorial workflows.

import { Orchestrator } from '@h4shed/mcp-core';
import { registerUnderWorldWriterTools } from '@h4shed/skill-underworld-writer/mcp';

const orchestrator = new Orchestrator();
await registerUnderWorldWriterTools(orchestrator);

For any agent operating directly in this repository, read AGENTS.md first.

Documentation structure

Root-level docs are load-bearing (SKILL.md and README.md are referenced by test/core.test.ts and the Dockerfile validator stage) or govern cross-agent behavior; everything else lives under docs/:

README.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md,   root: load-bearing / entry-point docs
CLAUDE.md, AGENTS.md, SKILL.md, PRIVACY.md

docs/
├── INDEX.md                     documentation index and navigation
├── USE_CASES_OVERVIEW.md        Fiction / True Crime / Podcast Production overview
├── PODCAST_PROJECT_ARCHITECTURE.md
├── AUDIO_GENERATION_PLAN.md
├── EPISODE_PUBLISHING_SCHEMA.md
├── LENGTH_SPECIFICATIONS.md / TEMPLATES_LENGTH.md
├── MODAL_MCP_INTEGRATION.md
├── performance-guide.md
├── guides/
│   └── GETTING_STARTED.md       installation and quick start
├── ops/                         operational/setup runbooks
│   ├── PUBLISHING.md            npm publish CLI (UW_NPM_TOKEN, dry-run, tagging)
│   ├── DOCKER.md
│   └── MODAL_SETUP.md
├── use-cases/                   per-use-case docs (fiction, true-crime, podcast-production)
└── archive/                     historical reports, superseded plans, past release notes

• Getting Started
• Documentation Index
• Use Cases Overview
• Publishing (CLI, UW_NPM_TOKEN)
• Docker · Modal Setup
• Contributing
• Agent Contract
• Privacy
• Changelog
• Output Contract
• Insight Corruption Setup (archived)

License

Free for non-commercial use under the Fused Gaming Non-Commercial Unlicense Amendment. Commercial use requires a separate license from Fused Gaming LLC — contact [email protected]. See LICENSE.md.

Support

• Issues
• Discussions

Built by Fused Gaming.