foldcase: Instructions file for Codex

Working rules — Foldcase

Binding for humans and agents. Short on purpose. The reasoning lives in docs/adr/; this file is the rules that follow from it.

The stack is fixed

• Bun is the development toolchain: the package manager, the test runner, and the version mise pins. Not npm, not pnpm, not turbo. Vite builds one thing and one thing only — the documentation site under docs/site/, by declared exception (ADR-0003).
• Node and Bun both run the shipped tool. The core is runtime-agnostic Effect and each runtime gets one thin shell — src/main.ts (Node) and src/main.bun.ts (Bun). A shell binds a runtime, hands the program process.argv, and writes back the exit code; anything else in a shell is a bug. See ADR-0002 › Amendment 1.
• The build is tsc -b, and there is no bundler. mise run build compiles src/ to dist/ — one .js and one .d.ts per source file — and copies the coverage collector beside its caller. bun build --compile is not used and is not coming back: a compiled binary resolves import(path) inside its own /$bunfs, so it could never load an external *.showcase.ts, which is the whole job.
• Effect v4 for all non-trivial logic: typed errors, Layers, Schema for every contract. Not bare async/throw. Effect is a peer dependency — never promote it to a hard dependency, or a consumer ends up with two Effect instances. Both @effect/platform-* packages are optional peers: a consumer needs only the one their shell runs, and the library entry points need neither.
• Foldkit is the only framework this line supports. No React, no Solid, no Vue, no Svelte — not in source, not in tests, not in devDependencies.
• No CSF-3. No Meta, no StoryObj, no export default meta, no *.stories.ts. A catalog is export const showcases: ReadonlyArray<Showcase> in a *.showcase.ts file.
• TypeScript only under src/. The single exception is src/coverage/collector.mjs, the Node V8 coverage instrument, which is allowlisted by name in the stack gate.
• docs/site/ is the documentation site, a foldocs (Foldkit) application that Vite builds and mise run docs:build drives. It is the one place a bundler runs. Its pages are derived from README.md, CHANGELOG.md and docs/adr/ on every build and are gitignored, so the prose has exactly one home. Nothing there touches src/, dist/ or the tarball. See ADR-0003.