Skip to content

Repository Map

Jump to bottom
Nick Hamze edited this page Jul 19, 2026 · 4 revisions

Repository Map

Top-level layout

Path Purpose
projects/ Editable flagship .wscvn.json projects.
novels/<slug>/ Prose-first manifests, manuscripts, editorial evidence, and quality reports.
games/<slug>/ Self-contained original games with source wrappers, assets, projects, reports, and local build outputs.
assets/signal-before-dawn-slice/ Flagship source art, runtime art, auditions, previews, and evidence.
audio/ Authored soundtrack auditions and selected emulator audio proof.
scripts/ Builders, converters, validators, proof renderers, doctors, and self-tests.
scripts/playtest_wscvn_swansong.py SwanSong ABI route, audio, state, and restart-persistence runner.
scripts/wscvn_route_plans.py Exhaustive flag/choice/branch/investigation route planner.
runtime-local/ Repo-local patched runtime used for direct builds; rebuildable outputs are ignored.
runtime-patches/ Source patches applied to the upstream VN runtime.
release-materials/ Public-facing controls, credits, provenance, and release documentation.
releases/ Generated flagship release archives; not source control material.
skills/build-wonderswan-vn/ Canonical Codex workflow skill and its detailed references.
skills/forge-light-novels/ Canonical schema-v3 novel framework, continuity/rights/music/catalog contracts, ImageGen briefs and set review, reports, validators, locks, and EPUB/PDF preflight.
CURRENT_RELEASES.md Current human-readable shipping index.

Authored, generated, and ignored

Keep in Git

  • authored .wscvn.json projects;
  • authored novel.json manifests, manuscripts, editorial evidence, illustration bibles, and publication configuration;
  • approved source art and runtime-ready PNGs;
  • audition approvals and review sheets;
  • source wrappers under games/<slug>/;
  • current proof reports and provenance;
  • release documentation that does not contain ROM bytes.

Keep out of Git

  • .wsc, .ws, commercial ROMs, firmware, and System Startup Files;
  • runtime-local/ build products and stale runtime snapshots;
  • generated release ZIPs;
  • private owned-ROM captures or diagnostics;
  • credentials, signing material, and notarization secrets.

Canonical skill mirrors

The source of truth is:

skills/build-wonderswan-vn/
skills/forge-light-novels/

The installed copy lives at:

~/.codex/skills/build-wonderswan-vn/
~/.codex/skills/forge-light-novels/

After changing skill files, synchronize the installed copy and run:

python3 scripts/check_build_wonderswan_vn_skill.py --require-installed-match
python3 scripts/check_forge_light_novels_skill.py --require-installed-match

The installed copy is never the only copy. If a workflow requirement exists only under ~/.codex/skills, it has not been added to the project.

Cross-repository source boundary

Story Forge owns the VN runtime patch, route planning, release orchestration, and game evidence. SwanSong Desktop owns the engine ABI, app input/focus logging, SwanSongRouteRunner, bundle checks, and live UI regression script. The GitHub Wiki is documentation, not an executable-source location.

Do not copy private app binaries or temporary test scripts into release evidence. Put reusable implementation in the appropriate source repository and bind the exact built artifact by hash.

Naming a game

Use one lowercase kebab-case slug consistently:

games/my-small-story/
games/my-small-story/projects/my-small-story.wscvn.json
games/my-small-story/build_my_small_story.py

Stable names make the builder, reports, release manifests, and package verifier agree about the same project.

SwanSong Story Forge

Clone this wiki locally