Generate the `.case/` folder

Generating turns the proposal into the contract. It writes the .case/ folder into a working directory and runs the structural validator over it until the tree passes.

Two boundaries hold the whole way through. It writes only inside the working directory — on a project you already had, .case/ is its business and your source files are not — and it pushes nowhere. It does not write the starter source code either: that is built outside Fito, guided by Plan the case source.

Before you begin

• A case proposal from Design a case. This step starts from that file, never from scratch.
• A pi session in a working directory of your own, with Fito installed there.

The three modes

The command picks its mode from what it finds, and says which one it chose.

Mode	When	What happens
Greenfield	No project tree yet	The directory is created and git-initialised
Reuse	--dir names an existing project	.case/ is generated into it; the project keeps its repo and history
Re-validate	The directory already has .case/	Everything is skipped except validation

Re-validate is the return trip. You come back to it after the source work, so the finished tree earns a fresh attestation.

Generate the contract

1. Run the command from the directory holding your proposal:

   /fito-case-generate

   Or name the proposal and the destination:

   /fito-case-generate ./case-proposal.md --dir ~/code/my-case

2. Confirm the plan it presents — the title, type, duration, directory and mode. Two things are settled here: the authors for the manifest, and any Open questions the proposal carried.

3. Let it write the files, then read the digest. It reports the objectives and prerequisites with their Bloom levels, each rubric criterion with its weight and evaluation method, the situation documents, whether a quiz rides along, and the optional fields the contract leaves empty.

4. Ask to see any file, and change anything you want, before the commit.

5. Let it commit. Greenfield commits to a new main; reuse commits to the branch you are on.

Flags

Flag	Required	What it does
(leading text)	No	The proposal file. Defaults to ./case-proposal.md
--dir <path>	No	The working directory the artifacts land in

What it writes

The fourteen required files, plus quiz.yaml exactly when the proposal carried quiz items, and task/steps.md for a tutorial. The full list is on What a case is.

A first generation fills the version-bearing fields for you:

Field	Value
manifest.yaml → version	1.0.0
manifest.yaml → status	draft
manifest.yaml → submission.method	pull_request
manifest.yaml → submission.target_branch	v1.0.0
manifest.yaml → submission.student_branch	solution
solution.yaml → branch	case/solution-v1.0.0

These are starting values, not names you may reuse later. Publishing sets status to published, and every version after the first has to move version, target_branch and the solution branch together — see Correct or retire a published case.

Two files are worth knowing about before you read them:

• starter_state/known_state.yaml — before the source exists, this states the contract that work must realise: which tests must fail, which errors must show. It is a promise, not an observation, until the re-validate pass.
• artifacts.yaml — on a reuse run it annotates the project’s real files. On a greenfield run it starts empty and is finalised at the re-validate pass.

Read the unused optional fields

A passing validation reports optionalFieldsNotUsed: the optional fields this case leaves empty, grouped by file.

Nothing is wrong with them. An optional field is the one thing the validator can never reject, so it would otherwise stay invisible forever. The report is there so you can fill one — or leave it — while the tree is still uncommitted.

The loop is edit, then validate

When the validator fails, fix the named files and run it again. Never regenerate the tree over a fixable error. Each error names the file and the field path that produced it, which is what makes the small fix possible.

The validator, its output and its rules have their own page: Validate the .case/ folder.

When generation stops

What you see	What it means	What to do
The proposal file is missing	This flow starts from the design step’s output	Run Design a case first
A required block is missing from the proposal	Parameters, learning objectives, prerequisites or rubric criteria did not make it	Finish the design step
Structural errors, grouped by file	The tree does not satisfy the ruleset	Fix the named files and re-run the validator

What’s next

1. Plan the case source — the spec and plan for the source work.
2. Build the starter source outside Fito, guided by those documents.
3. Re-run this command over the finished tree, for the fresh attestation.
4. Publish a case.

A structural pass does not prove the components you referenced exist. That is resolved by the Fito server when you publish.