Problem

The current onboarding path still depends too much on reading README.md and manually piecing together build, test, and example commands. The repo already has the raw pieces (Makefile, build.sh, EXAMPLES/, test target), but they are not organized as executable documentation.

For a code like GORILLA, the best documentation is a small set of scripts or make targets that a new user can run directly and inspect. That lowers the barrier for learning and also gives us something CI can exercise.

Goal

Provide runnable, self-checking entrypoints for the core repo so a user can:

• build the code
• run tests
• run one or two representative examples
• get a small, tangible output without reading much prose

Suggested scope

• add one documented bootstrap entrypoint for the common path, based on existing build logic in Makefile and build.sh
• add one or two smoke-test example runners under EXAMPLES/ or scripts/ that:
  • build if needed
  • run a representative orbit example
  • fail loudly on missing outputs
• make the README point to these runnable entrypoints first, before longer explanatory sections
• keep the scripts minimal and repo-native; prefer shell over adding more tooling
• make at least one of these entrypoints suitable for CI use

Concrete starting points in the repo

• Makefile
• build.sh
• README.md
• EXAMPLES/example_1 to EXAMPLES/example_7

Acceptance criteria

• a new user can run a single documented command and get a built executable plus at least one finished example run
• the command is deterministic and exits nonzero on failure
• README onboarding is reorganized around runnable commands
• the executable documentation path is covered by CI or a dedicated test target

Notes

This should stay focused on the core repo. Synthetic geometry or higher-level diagnostics belong in separate issues.