# 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.