Crosswake Install Guide

View Source

Crosswake keeps one primary package surface: crosswake. Companion-ready and docs-only surfaces stay explicit, but there is still one primary install path for the Phoenix host and one scaffold-once path for host-owned native shells.

  1. mix crosswake.install
  2. mix crosswake.gen.shell ios|android
  3. mix crosswake.doctor --router Elixir.YourAppWeb.Router
  4. bash script/verify_phase5_example_hosts.sh
  5. mix crosswake.doctor --router Elixir.YourAppWeb.Router --native-checks

The generated Phoenix and native files are host-owned, reviewable, and editable after generation. Crosswake owns the DSL, manifest contract, doctor surface, support matrix, and release-boundary policy. It does not re-own your app files after scaffolding.

Package Surface

There is one primary crosswake package plus explicitly bounded companion-ready and docs-only surfaces. Package class does not override route ownership.

If you are deciding whether your app pressure is mostly LiveView, one explicit native route, or one honest offline island, read guides/adopter_profiles.md for the Phoenix SaaS Portal, Selective Native Flow, and Local-First Study Flow profiles before drilling into the deeper shell, offline, or pack contracts.

Step 1: Install Crosswake Into A Phoenix Host

Run:

mix crosswake.install

What it does:

  • patches lib/<app>_web/router.ex with explicit Crosswake marker lines
  • keeps LiveView router imports compatible with the Crosswake live macro
  • generates a host-owned policy module at lib/<app>_web/crosswake/policy.ex
  • writes priv/crosswake/install_manifest.json so later tooling can inspect what Crosswake created or reused
  • points follow-up diagnostics at mix crosswake.doctor, guides/compatibility.md, guides/support_matrix.md, guides/native_shell.md, guides/bridge.md, and guides/packs.md

Repeated installer runs are idempotent. Existing marker blocks are reused instead of duplicating router edits, and existing host-owned policy files are left alone.

Step 2: Generate Host-Owned Native Shells

Run one of:

mix crosswake.gen.shell ios
mix crosswake.gen.shell android

What it does:

  • creates a host-owned shell project under native/<platform>/crosswake_shell
  • bundles the canonical manifest, activation, route-unavailable, and declared-pack fixtures
  • scaffolds manifest-first activation, explicit route unavailable UI, and the bounded bridge channel

What it does not do:

  • it does not safely regenerate over host edits
  • it does not turn unsupported routes into generic container fallback
  • it does not widen support beyond explicit, proof-backed surfaces

Read guides/native_shell.md for the shell contract and guides/bridge.md for the bounded bridge contract.

Step 3: Verify Host And Manifest Truth

Run:

mix crosswake.doctor --router Elixir.YourAppWeb.Router

This checks install state, manifest truth, shell generation posture, bounded bridge truth, release policy posture, and fail-closed denial vocabulary.

Step 4: Run The Public Proof Lane

Run:

bash script/verify_phase5_example_hosts.sh

This is the primary proof artifact class Crosswake publishes for adopters.

Step 5: Re-Run Local Generated-Host Verification

Run:

mix crosswake.doctor --router Elixir.YourAppWeb.Router --native-checks

With --native-checks, doctor executes the generated-host verification hooks:

  • script/verify_generated_ios_shell.sh
  • script/verify_generated_android_shell.sh

Do I need to rebuild?

Use the four public change classes first, before raw version numbers:

  • docs-only -> read the updated guidance and run docs integrity only
  • core-only/no native rebuild -> update core and rerun core contract + doctor/support proof
  • compatibility-bump only -> confirm your compatibility window and run fail-closed compatibility fixtures
  • native or companion rebuild required -> rebuild the affected shell or companion and rerun generated-shell or companion verification lanes

The matching proof lanes are:

  • docs integrity only
  • core contract + doctor/support proof
  • fail-closed compatibility fixtures
  • generated-shell or companion verification lanes

The generated support matrix remains authoritative: guides/support_matrix.md

Docs-Only Install Boundary

The install walkthrough is useful product guidance, but it is not first-class supported as a separate package surface. It teaches the primary crosswake install path and the boundary between host-owned artifacts and Crosswake-owned contract surfaces.

Route owner

Install guidance does not change route ownership. Phoenix routes remain Phoenix-owned unless a route policy explicitly declares otherwise.

Why not core/companion

This walkthrough explains package and artifact boundaries. It is not itself a runtime package, and it does not promote host scaffolding into a companion surface.

Host-owned responsibilities

The host reviews generated files, owns shell project edits after generation, reruns proof hooks, and decides when local rebuilds are needed.

Prerequisites

A Phoenix host, explicit router wiring, generated policy module, and the proof scripts referenced by the support matrix.

Denial behavior

If install or compatibility truth is incomplete, mix crosswake.doctor reports blocking issues instead of inferring that the host is correctly wired.

Fallback behavior

Crosswake falls back to explicit diagnostics and route-unavailable posture, not silent package promotion or generic shell behavior.

Native rebuild required

Only when your change lands in the native or companion rebuild required class. Docs-only install guidance and core-only policy changes do not automatically imply a native rebuild.