Skip to content

Development and Verification

macOS build

The repository-supported verification build is:

./tools/run_macos_app.sh --build-only

Build and launch the native application with:

./tools/run_macos_app.sh

The wrapper performs a clean debug rebuild of RAMAL-EBX.app, installs the bundle metadata and icon, places matching debug symbols in the standard adjacent RAMAL-EBX.app.dSYM, removes obsolete root-level build outputs, and ad-hoc signs the complete local development bundle: tools/run_macos_app.sh. Direct odin build or odin run is not the project build workflow.

Run the isolated one-time legacy Execution Profile conversion with:

./tools/run_macos_app.sh --migrate-execution-profiles

The migration build exits before application initialization. Normal RAMAL-EBX startup reads only execution-profiles.json.

Tests and checks

Run the package-level Odin tests with:

odin test .

Run patch hygiene with:

git diff --check

The repository documents vet/static checking as part of non-trivial completion, but it does not define a separate repository-owned vet command. Do not invent one; use checks supported by the installed Odin toolchain in addition to the explicit commands above.

Python backend tests are standalone unittest entry points. There is no aggregate repository test script. Run affected modules directly:

python3 tools/test_phits_dose_io.py

The current test modules are in tools. Some require scientific Python dependencies or fixtures. Passing unit tests and building the bundle do not replace native GUI verification.

For a non-trivial implementation, complete the relevant tests, supported static checks, debug app build, git diff --check, source cleanup audit, and the real GUI boundary where practical.

Documentation maintenance

Regenerate the Paper 1 research pages and C4 views, then strictly validate the complete knowledge base:

./tools/generate_knowledge_base.py

The generator:

  1. snapshots all shared pages and custom assets into a recoverable tmp/knowledge-base-*/before directory;
  2. extracts supplied PDFs into page-separated text;
  3. asks a read-only AI pass to update only the Paper 1 research pages from the snapshot and approved sources;
  4. regenerates C4 pages from the reviewed Structurizr model;
  5. removes host-home prefixes from public Markdown;
  6. performs strict MkDocs validation; and
  7. replaces live documentation only if it was not edited during generation.

Implementation: tools/generate_knowledge_base.py. The authoritative C4 model is knowledge/architecture/workspace.dsl.

Generate only the C4 pages:

./tools/generate_architecture_docs.sh

Preview the existing knowledge base locally:

./tools/view_knowledge_base.sh

Incomplete path: the currently present --update-paper1 branch references tools/generate_paper1_knowledge.py, which is not in the live repository. Do not document that option as working. Use the complete knowledge-base generator for research-page regeneration: tools/view_knowledge_base.sh.

Build and publish the complete site:

./tools/publish_knowledge_base.sh

This regenerates and validates the complete knowledge base, builds the strict MkDocs snapshot, deploys it to Cloudflare Pages, and verifies key public URLs: tools/publish_knowledge_base.sh.

Publish already edited pages without either AI-regeneration step:

./tools/publish_knowledge_base.sh --publish-only

Software documentation is edited directly and points to executable owners for current behavior. Research generation must preserve direct owner edits and scientific reasoning, reconcile factual descriptions against code and immutable records, and never treat generated prose, successful execution, or deterministic descriptive statistics as scientific acceptance.