The Beskid Book

Informative guide. This Book page explains Beskid but does not define the standard. For normative requirements, use the Beskid Standard.

This book is the practical introduction to Beskid. It is written as a tutorial track first, with links into the normative spec when you want exact rules.

Canonical specification: Enforceable language and platform contracts live under the Platform specification, especially Language meta. This book is informative: use it to learn, then confirm rules in platform-spec.

Start here

• Why this exists: Why Beskid Exists (opinionated context; skip to install if you want binaries, not philosophy).
• Hands-on: 01. It works on my machine.

How to use this book

• Read chapters in order if you are new to Beskid.
• Treat each chapter as “learn, apply, verify”: read the concept, try it in a small file, then cross-check with linked spec pages.
• Keep the Platform specification open for details and edge cases.

Learning tracks

• Language user: 01. It works on my machine → 07. The compiler is not your therapist → 08. Green tests, red production → 19. Public API that survives review → 20. /// comments that are not lies
• Monorepo / packages: 03. Project.proj or it didn’t happen → 06. Monorepo as coping mechanism → 18. Packages without npm trauma → 19. Public API that survives review
• Spec collaborator: 12. The normative bible → 13. Reading the law → feature under test in platform-spec
• Compiler contributor: 13. Reading the law → 14. From source to something that runs → 15. Mods: plugins with consequences → 17. Execution → 22. So you want to contribute
• Philosophy optional: 00. Why Beskid exists, or jump straight to 01

Tutorial chapters (01–22)

#	Chapter
01	It works on my machine
02	PATH not found: tooling anyway
03	Project.proj or it didn’t happen
04	Where does this file even go?
05	Names nobody agreed on
06	Monorepo as coping mechanism
07	The compiler is not your therapist
08	Green tests, red production
09	Contracts, effects, and polite threats
10	Memory without another billion-dollar mistake
11	Fibers: cheaper than threads
12	The normative bible
13	Reading the law
14	From source to something that runs
15	Mods: plugins with consequences
16	Corelib: batteries with opinions
17	Execution: ABI, host, and runtime
18	Packages without npm trauma
19	Public API that survives code review
20	/// comments that are not lies
21	FFI and other forbidden friendships
22	So you want to contribute

Reference (workflows and commands)

Informative deep dives merged from the former guides tree:

• CLI and command reference
• Projects and manifests
• LSP
• Analysis
• Testing
• Workspace monorepo setup
• Publish your first package

What you should know after finishing

• How Beskid source layout maps to module and name-resolution behavior.
• How project/workspace manifests control build and dependency resolution.
• How to design stable public APIs with pub and pub use, document them with ///, and publish packages without manual version theatre.
• Where platform-spec, compiler crates, and CI fit when you contribute.