prole/docs/layout.md

Repository layout (first-pass)

This repo is being refactored toward a clearer separation between runtime scripts, reusable shell libraries, operator validation scripts, and tests.

Top-level conventions

• etc/
  • Runtime/bootstrap/config scripts only.
  • May contain thin compatibility shims that forward to new locations.
• etc/lib/shell/
  • Reusable shell helper libraries intended to be sourced by CLI/runtime scripts.
  • Lives under etc/ so the runtime layout does not rely on gitignored $KNOE_HOME/lib.
  • Prefer keeping logic here deterministic/testable; keep entrypoint scripts thin.
• scripts/validation/
  • Operator-run validation/check scripts.
  • These may invoke cluster tooling (kubectl, etc.), but should source shared helpers from etc/lib/shell/.
• tests/shellspec/
  • Shellspec tests for deterministic helper behavior only (no cluster access).
  • Focus areas: config parsing, env fallback resolution, realm normalization, secret precedence, guardrails, command assembly.
• authority/
  • Minimal Maven-backed Spring Boot service.
  • Provides application startup and a basic health endpoint.