Development

How to scaffold a new OwlMeans Common project — the @owlmeans/create-app CLI (npm/bun/yarn create), its flags, what it generates, and the manual alternative. Use when asked to create/bootstrap/start a new OwlMeans app or set up a fresh project.

How to use @owlmeans/router — the UI routing plugin HOST (RouterService registry + cascade selection + neutral route IR + pure matcher) and the hook types every plugin implements. Auto-invoked when importing router service types, the matcher, or implementing/registering a routing plugin.

How OwlMeans UI routing plugins work — the RouterPlugin contract, cascade selection, choosing/switching the router at context provisioning (default OwlMeans vs opt-in react-router), and authoring a new plugin (e.g. SSR). Read before wiring routing in an app or writing a routing plugin.

How to use @owlmeans/route — transport-neutral route declarations, frontend/backend/socket markers, HTTP methods, extensible protocol identifiers, and address helpers. Auto-invoked when importing route helpers or defining an entrypoint's URL path.

How to use @owlmeans/config — the application config every OwlMeans layer extends, service() declarations, plugin records, the config resource, brand and login-screen settings, and makeSecurityHelper for building URLs. Auto-invoked when importing from @owlmeans/config or writing a config.ts for a new app.

How to use @owlmeans/mui-panel — the LEGACY MUI v7 browser layer: makeContext, the render() entry point with the MUI ThemeProvider, the Block/Text/Link/Status/Form components and the auth-only subpaths. Superseded by @owlmeans/web-panel for new work. Auto-invoked when maintaining an app that already imports mui-panel or deciding how to migrate one off it.

How to use @owlmeans/mui-oidc-rp — the LEGACY MUI browser OIDC relying party: appendOidcGuard, oidcEntrypoints, the OidcAuthService round trip and the Dispatcher screen, plus the OIDC and Google client-auth plugins. Superseded by @owlmeans/web-oidc-rp (or @owlmeans/client-iam) for new work. Auto-invoked when maintaining an app that already imports mui-oidc-rp or migrating one off it.

How OwlMeans login plugins work — the LoginPlugin contract and its seven stages, cascade selection by LoginEnv (embedded / surrogate), the surrogate window and its own route, the redirect and hand-back flows, the resume fast path, framed logout, preconditions, and wiring sign-in with useLogin/useLogout. Read before touching login wiring, an OIDC dispatcher, or sign-in from an embedded app.

The identity-provider choice screen — how a sign-in method is declared, where methods come from, the configuration that decides what is offered, the terms confirmation and credit line, and how a dispatcher composes it. Read before touching a dispatcher, adding an authentication method, or changing what a sign-in screen shows.

OwlMeans localization conventions — tiered namespace model, compound-prefix keys, 7-language requirement, override pattern, and language switcher. Auto-invoked when adding UI strings, translation keys, language files, or working with i18n in any package.

How the OwlMeans LLM layer composes a system prompt from a role and skills, and the prompt-cache rules that layout exists to satisfy — block order, breakpoint budget, determinism invariants, and the provider facts behind them. Auto-invoked when touching prompt composition, skills, LlmPromptPlugin, patchSystem/patchCache, or anything that changes what a request sends before its first per-call byte.

How to use @owlmeans/i18n — the core localization registry (no runtime deps). Auto-invoked when adding translatable strings to a library package, importing from this package, or working with the tier/priority system.

How to use @owlmeans/error — ResilientError, the error class registry, marshalling errors across a service boundary and back, and the i18n namespace error messages resolve through. Auto-invoked when importing from this package, declaring a typed framework error, or normalizing a caught error.

How to declare immutable, typed @owlmeans/entrypoint protocols with protocol(), contract(), typed(), protocol trees, guards, gates, and route transports. Load before defining a shared API, socket, or screen contract.

How to use @owlmeans/did — the owlmk derivable key type, makeDidKeyModel and its derive() paths, and makeWallet over a three-resource DID store with mnemonic seed, key metadata and per-entity key provisioning. Auto-invoked when importing DID or wallet types, deriving keys, or implementing identity workflows.

Authoritative map of every @owlmeans/* package, its direct @owlmeans/* dependencies, the architecture layer it belongs to, and the topological build order. Auto-invoked when the agent needs to understand the dependency structure of the monorepo — for example, deciding which layer a new package belongs to, untangling a cyclic build, planning a refactor that crosses layers, or picking the right package to import from.

How to use @owlmeans/consent and @owlmeans/web-consent — the cookie-consent model, its categories and global-variable seam, the storage contract and its migration, Consent Mode v2 signalling, and the ordering rule that makes a tag manager honour any of it. Auto-invoked when touching consent categories, the dialog, the cookie policy page, or a tag-manager snippet.

How to use @owlmeans/client — the platform-agnostic React client framework (web and native) — makeClientContext, App/Router, useNavigate/Navigator, useEntrypoint/RoutedComponent, useStoreModel/useStoreList, useValue, the modal and debug services. Auto-invoked when importing client framework primitives, navigating between screens, or reading client state from React.

How to use @owlmeans/client-wl — the reserved platform-neutral slot in the white-label stack, currently empty. Auto-invoked when a dependency names client-wl or when deciding where shared white-label UI belongs.

How to use @owlmeans/client-socket — opening a self-restoring WebSocket Connection to a socket entrypoint from browsers and native clients, the reconnect policy and its options, the socket-status aggregator, the useWs hook and the system frames a carrier emits. Auto-invoked when importing client socket primitives or wiring a browser subscription.

How to use @owlmeans/client-payment — the browser-side PaymentService, which adds a cached shallow identity on top of @owlmeans/payment so a returning visitor keeps their profile without re-presenting a token. Auto-invoked when registering the payment service in a client context or calling shallowAuthentication from a browser.

How to use @owlmeans/client-panel — reusable cross-platform UI panel + form components (auth screens, layouts) and the headless navigation model (usePanelNav) shared by web-panel and native-panel. Auto-invoked when importing panel components or building a navigation menu.

How to use @owlmeans/client-i18n — React i18n context built on i18next. Auto-invoked when setting up translation in a React app, using translation hooks, or working with language switching.

How to use @owlmeans/client-flow — the platform-agnostic flow service (makeBasicFlowService) that loads @owlmeans/flow definitions from config records, createFlowClient(context, nav), the runner a screen drives to advance a flow and navigate to each step, and suspendFlow/resumeSuspendedFlow, the side-band landing that returns a person to where they started after sign-in. Auto-invoked when importing client flow primitives, registering a flow service, or moving a screen to the next flow step.