hypertwist/docs/ops/project-file-setup-manual.codex.md

Codex Project File Setup Manual

This note records how HyperTwist should be represented in Visual Studio while the codebase is still being assembled.

Current Supersession - 2026-07-26

HyperTwist now has a real Unreal application root. The tracked authority is:

• UnrealHyperTwist/UnrealHyperTwist.uproject
• UnrealHyperTwist/Source/
• UnrealHyperTwist/Config/

The ignored repo-root HyperTwist.sln, HyperTwist.vcxproj, HyperTwist.vcxproj.filters, and HyperTwist.vcxproj.user files were retired after the root project became the exact giant file collector prohibited below. They indexed custody snapshots, mirrors, and generated Unreal output and were not a valid build surface.

For normal work, open the .uproject. Visual Studio or Unreal may generate UnrealHyperTwist/UnrealHyperTwist.sln and related Intermediate/ProjectFiles state on a Windows host when needed. Those generated files remain disposable IDE state and are not source authority.

The historical guidance below remains useful as the reason not to recreate a repo-root catch-all project.

Current Rule

The repo-root HyperTwist.vcxproj should be treated as a lightweight workspace shell, not as the real application project.

It should not be used to pull in large repository trees such as:

• mirrors/
• node_modules/
• generated output such as .vs/, x64/, Intermediate/, Binaries/, dist/, coverage/
• research, archives, downloads, or reference bundles

If the root .vcxproj turns into a giant file collector, Visual Studio indexing, Copilot context, RAM use, and build behavior all get worse.

What To Do Now

While the architecture is still being decided:

• Keep the solution small and intentional.
• Use the repo-root project only as a workspace placeholder or solution anchor.
• Keep real implementation in real language/project folders.
• Do not add vendored, mirrored, archived, or generated folders to the root .vcxproj.

When To Create Real Projects

Create a real project only when the corresponding codebase actually exists.

C++

Create or expand a real .vcxproj when there is an actual native code layout such as:

• src/
• include/
• app/
• engine/

At that point the .vcxproj should include only first-party native source files and headers.

C#

Create a .csproj when there is real C# application or library code. Let the .csproj represent the actual source tree instead of routing C# through the root .vcxproj.

Node / TypeScript

Create an .njsproj only when there is a real frontend, tool, server, or plugin root with files such as:

• package.json
• src/
• public/
• tests/

The Node project should point only at that app folder and should explicitly ignore node_modules, build output, caches, and mirrors.

Rust

Use Cargo.toml as the source of truth. Do not force Rust code into a C++ project. When the crate layout is real, wire Visual Studio around the Rust crate deliberately.

Unreal

If HyperTwist grows around Unreal, let Unreal-generated project structure remain the source of truth for Unreal modules and plugin code. Do not dump Unreal Intermediate or generated build output into the root .vcxproj.

When To Ask Codex To Set It Up

Come back and ask for setup when one of these is true:

• the first real app folder has been created
• the first real language-specific project exists
• you want the multi-project solution updated cleanly
• you want Copilot/Visual Studio indexing to recognize the app roots properly

Good examples:

• "Create a proper Node.js project for ui/."
• "Turn engine/src and engine/include into the real C++ project."
• "Add the Rust crate and keep it out of the root .vcxproj."
• "Wire the Unreal plugin/tooling folders into the solution without indexing generated output."

What Not To Do

• Do not use the repo-root .vcxproj as a catch-all for the entire repository.
• Do not include mirrors, archives, downloaded reference material, or generated folders.
• Do not rely on Show All Files plus a giant root project as the long-term structure.
• Do not assume Visual Studio will "organically" infer the right architecture later if the placeholder project is already polluted.

Practical Bootstrap Sequence

1. Decide the first real code roots.
2. Create the real language-native project files for those roots only.
3. Keep the repo-root project minimal.
4. Exclude generated, mirrored, vendored, and research-only directories from indexing.
5. Rebuild the solution index after structural changes.

Short Version

Until the real code layout exists, keep HyperTwist.vcxproj minimal.

Once real C++, C#, Node/TypeScript, Rust, or Unreal code roots exist, ask Codex to wire those folders into proper project files instead of expanding the root workspace project.