stax

OmegaOS skill — the dashboard vision structure. Converts any app to the Stax panel grammar. Triggers /stax (and /omg-stax). The canonical framework lives at ~/.omega/repos/stax (a live checkout of github.com/agentik-os/stax main, kept current by the daily OMEGA-CRON-STAX-SYNC-v1 cron). Always read the live source under ~/.omega/repos/stax — it is the source of truth, this skill is the pilot.

What Stax is (the one mechanic)

The entire interface is a horizontal rail of in-page panels. Click anything with depth and a panel opens to its right; the parent stays visible. That panel can open another, to unbounded logical depth. Navigation is not routing — the whole UI is derived from one serializable state object. There are NO pages, NO modals, NO tabs:

• One mechanic — open-right (openDetail); sections switch the thread (openSpace).
• One action zone — the panel footer. Never floating buttons.
• One way back — close, Esc, or a breadcrumb crumb (derived from the state).

Everything else — breadcrumb, URL, persistence, agent context, the compact phone back-stack — derives from the state. Change the accent token and the whole system follows. Read references/canonical-context.md for the mental model and the 5 laws.

When NOT to use Stax (fit gate — do this first)

Stax fits relational, data-dense operational software where conventional route changes destroy context (CRMs, admin consoles, dashboards, ops tools, knowledge apps). It is not a universal replacement for pages/tabs/dialogs. Reject panelization where:

• data is shallow, sequential, or unrelated (a linear checkout, a marketing site);
• a blocking yes/no decision belongs in a dialog, not a panel;
• alternate representations of ONE record belong in tabs inside one panel, not siblings;
• a cross-context tool belongs in the UtilityDrawer (an overlay — never on the stack).

Run Phase 0 and end with GO / ADAPT / DO NOT USE before touching code (L2).

PRIMARY PATH — stax-migrate (the official engine)

The framework now ships stax-migrate — a zero-dep Node CLI that drives a provably-lossless refonte with two file-backed matrices (feature + pixel-level element) and a hard done gate that refuses to advance while any row is unmigrated. Prefer it over the manual pipeline below for any real conversion — it replaces "restyled by eye" with the canonical design-spec.md contract and greps the new app for drift. Full guide: references/stax-migrate.md; the pixel contract: references/design-spec.md.

M=~/.omega/repos/stax/frameword/packages/stax-migrate/index.mjs
node "$M" init /path/to/legacy-app     # 9 phase briefs + design-spec + matrices
cd /path/to/legacy-app && node "$M" next   # then: run . --agent claude → done → repeat

The manual pipeline below remains valid for a quick prototype, a teaching walk-through, or where a Node CLI can't run — but it carries no coverage guarantee.

The manual conversion pipeline (fallback)

Full detail + the paste-ready prompts are in references/conversion-playbook.md. The exact API is in references/api-reference.md. Summary:

Phase 2 — scaffold (mechanical, do this to unblock the port)

bash ~/.omega/skills/stax/scripts/stax-scaffold.sh <target-project-dir>

It vendors panels-core + panels-react (rewriting the @frameword/* import to a local path — zero deps beyond React), drops in a stax/ shell (Sidebar / breadcrumb Topbar / ColumnHost + PushHost Stage / Panel header-body-footer), the WhitePaper design system (tokens.css = palette + Inter/Newsreader/Geist Mono fonts, stax-ui.css = the shell/panel chrome: dot-grid stage, 14px card panels, mono eyebrows, serif titles, accent footers), and a registry.tsx stub. React 18/19 + TS. After it runs, the app both behaves AND looks like Stax; Phase 3 fills the registry with the real domain.

The design IS part of Stax, not just the mechanic. A conversion adopts the WhitePaper look by default (see references/design-system.md); you only swap the --accent token for the brand — the whole system follows (Law 5). Do NOT ship a bare/generic shell.

Phase 3 — the porting map (the heart of "convert any project")

Every params value must be JSON-only — never store JSX, callbacks, or fetched rows in navigation state (a hard engine invariant; validate() will catch it).

Verification gate (L1 / L4 — do not skip)

A conversion is "done" only when, at runtime:

1. validate(workspaceState) returns [] (run the panels-core laws test-kit too);
2. opening the same target from the same parent reveals, never duplicates;
3. the breadcrumb, URL hash, and on-screen rail always agree;
4. a shared URL restores the exact ContextPath (refresh + paste-in-new-tab);
5. browser Back/Forward reconcile (distinct from navigateUp);
6. focus transfers into the new panel on open, restores on close; Esc closes;
7. compact viewport collapses to one focused column (PushHost);
8. loading / empty / error / not-found / permission / deleted / dirty-edit states render;
9. no floating action buttons — every commit action lives in a footer.

Cite evidence for each (R-CITE). Documented-but-absent behavior is a FAIL, not a pass.

Scaffolding a brand-new Stax project (not a conversion)

# the specimen is the reference implementation to copy/learn from:
cp -r ~/.omega/repos/stax/frameword <your-new-project>/     # or start from crm-specimen

For a fresh OmegaOS-stack build (Next.js App Router + Tailwind), keep exactly one route (/) and make everything else panel state — see the Next.js adapter prompt (Prompt 6) in the playbook. Data/auth/payments (Convex + Clerk + Stripe) are deferred until the mechanic is locked.

Keeping current

The framework auto-syncs daily from github.com/agentik-os/stax main (OMEGA-CRON-STAX-SYNC-v1 → ~/.omega/logs/stax-sync.cron.log, Telegram-pings on change). To pull on demand: bash ~/.omega/skills/stax/scripts/stax-sync.sh. Because the checkout tracks latest main (not a frozen pin), always re-read the live source before a conversion — the API in references/ is a snapshot for orientation, the repo wins.