Share business modules

From the empty directory that will become your application, this illustrative command sequence uses the shipped CLI flags. The administrator details are requested interactively; no credentials belong in the example or committed configuration.

wildo init --check
wildo init --name service-desk \
  --runtime docker-compose \
  --database postgresql

wildo align-deps --write
wildo assets sync
wildo config sync
wildo dev start

init --check verifies development tools without scaffolding. The ordinary init path renders files, installs dependencies and performs initial compilation unless --skip-install is selected. Follow the command’s reported next steps if installation or initial compilation needs attention. --config-only has a different purpose: it writes the application configuration rather than the complete skeleton.

Know which decisions the scaffold connects

The generator derives dependency pins from framework metadata and development package lists from the workspace it actually creates. Framework-developer mode links to a checkout; application-creator mode uses published packages. The selected delivery mode changes dependency resolution, not the business role of each package.

Give each local application its own space

Initialization registers the local environment, provisions its secret material and allocates a port block by inspecting authored sibling application configurations under the framework checkout’s examples/ directory. --port-base supplies an explicit starting port when the workspace needs a deliberate allocation. It is still the operator’s responsibility to resolve unrelated processes already listening on a chosen port.

Administrator identity belongs to local initialization, not a reusable module. Optional --admin-email, --admin-first-name and --admin-last-name flags must be supplied together to bypass identity prompts. Keep passwords in the supported local secret flow; omit --admin-password to let initialization generate one.

Distinguish repair from regeneration

Re-running wildo init inside the application it created uses a repair path: it reuses administrator identity from usable saved secrets and backfills missing secret material without rotating existing credentials. If usable secrets are absent, it resolves the administrator identity again from supplied flags or interactive input. It does not overwrite your application with a fresh skeleton. Initial scaffolding refuses an unrelated non-empty target directory.

After a framework upgrade, dependency alignment and wildo assets sync refresh the delivered inputs. Configuration synchronization derives environment artifacts from your current declarations. A working platform registration is required for the deployment-related synchronization phase; it is separate from creating the local application structure.

Run wildo compose inside an application to discover its available scenarios. The following is an illustrative add-module invocation using every required variable from the shipped manifest. Replace @service-desk/shared-lib with the actual shared-library package name.

wildo compose
wildo compose add-module \
  --var moduleId=customer-support \
  --var moduleCamel=customerSupport \
  --var modulePascal=CustomerSupport \
  --var 'purpose=Organize customer requests and their resolution' \
  --var 'businessCapability=Resolve customer requests' \
  --var businessDomain=customer-service \
  --var sharedLibPackage=@service-desk/shared-lib \
  --dry-run

The preview lists file writes, declared edits, already-present elements and conflicting files. It includes required engine peer declarations and applicable provider overrides, showing dependency names and values alongside the affected paths. Review that plan, then repeat the same invocation without --dry-run to apply it. Required variables and naming patterns are validated before planning the file changes.

Follow one module through the application

Example: the customer-support module produced by the command above, using the shipped skeleton layout with backend-api, frontend, shared-lib and specifications packages. The scenario creates a connected starting point. It does not implement a support feature: the initial resource, operation and view registries are empty.

You supply the module identity and business purpose. The scenario renders its descriptors and edits the host registrations below. The framework then consumes those registrations; your application code supplies the resources and behavior you add afterward.

Give the shared model one module identity

In shared-lib/src/modules/customer-support/index.ts, the generated descriptor connects the module’s field identifiers, resource configurations and relationships. The imports point to registries created alongside it:

import type { SharedSaaSModule } from '@wildo-ai/saas-models';

import { CustomerSupport_ResourceFieldIdentifier } from './resources/customer-support.resources-types';
import { moduleResourcesConfigurationsFactoryMap } from './resources/customer-support.resource-configs';
import { moduleResourcesRelationships } from './resources/customer-support.relationships';

const customerSupportModule: SharedSaaSModule = {
  moduleId: 'customer-support',
  kind: 'domain',
  resourceConfigurations: moduleResourcesConfigurationsFactoryMap,
  resourceFieldIdentifiers: CustomerSupport_ResourceFieldIdentifier,
  resourceRelationships: moduleResourcesRelationships,
};

export * from './resources';
export default customerSupportModule;

The identity is customer-support in every layer. Adding a resource later fills these registries; naming a module alone does not create an API or a form.

Keep the business meaning alongside the model

The specification declaration in specifications/src/modules/customer-support/index.ts explains the purpose behind the module. This selected declaration uses the variables supplied to the scenario:

import {
  type ModuleBusinessSemantics,
} from '@wildo-ai/saas-specifications';

export const customerSupportModuleBusinessSemantics: ModuleBusinessSemantics = {
  relatedModuleId: 'customer-support',
  purpose: 'Organize customer requests and their resolution',
  businessCapability: 'Resolve customer requests',
  businessDomain: 'customer-service',
  primaryActors: [
    'organization member',
    'organization admin',
  ],
  mainResources: [],
  supportingResources: [],
  integrationSurfaces: [],
};

The empty resource lists are intentional at this stage. As resources are added, the specifications explain which are central to the module and how they support its purpose.

Connect interface contributions and backend behavior

In frontend/src/modules/customer-support/index.ts, the generated frontend descriptor collects resource UI behavior, composite views and shell contributions:

import type { FrontendModule } from '@wildo-ai/saas-frontend-lib';

import moduleResourcesUIBehavior from './resources/index.js';
import moduleAppLevelViewsCompositeViews from './app-level-views/index.js';
import moduleAppShellModuleConfig from './app-shell.module.frontend.js';

const customerSupportFrontendModule: FrontendModule = {
  moduleId: 'customer-support',
  resourceUIBehavior: moduleResourcesUIBehavior,
  compositeViews: moduleAppLevelViewsCompositeViews,
  ...moduleAppShellModuleConfig,
};

export default customerSupportFrontendModule;

The shell contribution starts with an empty navigation group. Creating this descriptor does not add a customer-support screen; actual resources and view contributions provide the visible experience.

The backend has a different owner. backend-api/src/modules/customer-support/index.ts supplies the descriptor discovered by the existing backend directory scan:

import type { BackendOwnedModule } from '../../backend-owned-module.js';
import moduleResources from './resources/index.js';

const customerSupportBackendModule: BackendOwnedModule = {
  moduleId: 'customer-support',
  kind: 'domain',
  backendModule: moduleResources,
};

export default customerSupportBackendModule;

backendModule starts with the module’s empty resource-operation collection. Later additions supply implementations here; the module directory is the discovery boundary.

Register the module in the host that will use it

These are selected resulting declarations from separate files, not one file to paste over the application’s existing registries. The scenario adds the corresponding imports and preserves existing entries.

// shared-lib/src/modules-registry.shared.ts
export const applicationSharedModules: SharedSaaSModule[] = [
  customerSupportModule,
];

// specifications/src/module-registry.specification.ts
export const applicationModuleBusinessSemantics: ModuleBusinessSemantics[] = [
  customerSupportModuleBusinessSemantics,
];

// frontend/src/modules/index.ts
export const applicationFrontendModules: FrontendModule[] = [
  customerSupportFrontendModule,
];

// wildo.saas.config.ts — the service keys in this skeleton
export const applicationModules = {
  'customer-support': { services: ['backendApi', 'app'] },
};

The shared registry includes the module in the model, the specification registry includes its business meaning, and the frontend registry includes its interface contributions. The service binding declares which configured services use the module. Source registration and service selection answer different questions; both matter.

Backend discovery already exists in backend-api/src/modules/index.ts. This selected existing code scans child module exports and assembles their backend contributions; the scenario does not append a separate backend array entry:

const applicationBackendOwners = await scanSubdirDefaultExports<BackendOwnedModule>({
  importMetaUrl: import.meta.url,
});

const applicationBackendDomainModules: BackendDomainModule[] = applicationBackendOwners.flatMap((ownedModule) =>
  ownedModule.backendModule ? [ownedModule.backendModule] : []
);

const backendModules = mergeBackendDomainModules(...applicationBackendDomainModules);

Carry the registration into the companion’s observed model

The shared package’s existing companion-exports.ts already loads the assembled sharedModules. This loader stays unchanged when the scenario adds the module upstream:

async function loadSharedCompanionData() {
  return import('./modules-registry.shared.js');
}

export async function loadSharedModules(): Promise<SharedSaaSModule[]> {
  const { sharedModules } = await loadSharedCompanionData();
  return sharedModules;
}

The existing sharedCompanionExports object exposes loadSharedModules. The package’s ./companion entry points to the emitted companion surface. Let the application’s development watchers compile the changed packages, then synchronize changed configuration for the selected environment. The companion resolves the requested service and the targets required by that introspection behavior; it does not infer them from a newly created directory.

Use the running companion’s menu to choose a service key and an available behavior:

# Discover the actual serving surface and its supported queries.
wildo context health
wildo context list

# In this skeleton, backendApi is the backend service key.
wildo context info resources-registry --service backendApi
wildo context coherence

These are verification commands to run in your application, not captured output from a deployed support feature. A health response establishes availability. An empty new module contributes no resources to resources-registry, so the absence of a support resource is expected until one is declared. Once a resource and its behavior are added, check their presence in the resolved model and exercise the actual API or screen. A successful compilation or coherence report alone does not demonstrate that business flow.

Choose the right scenario boundary

Scenario selection is per reference: an application-delivered scenario takes precedence over the same reference in the framework checkout. References found only in the checkout remain available as a fallback. add-module supplies a connected empty shape; add-resource adds its business records afterwards.

Keep later edits under application ownership

Planning skips byte-identical generated files and edits whose required elements are already present. A generated target with different content becomes a collision, and apply refuses that plan before starting its writes. Reconcile deliberate application changes through version control rather than expecting a scenario to merge them.

This preflight protects against known conflicts; applying a plan performs filesystem writes sequentially. Keep the change reviewable in version control, including recovery from an interrupted write or a later post-apply failure. After a successful addition, let the development watchers compile the affected packages and synchronize configuration when runtime bindings change.

Start with the installed tool’s own help. The listing is derived from registered command metadata, including descriptions, arguments and flags.

# Discover commands and inspect a specific operation.
wildo help
wildo config sync --help

# Inspect the local and live-context command contracts.
wildo local dev --help
wildo local doctor --help
wildo context info --help

Command availability depends on workspace scope. Run application commands from that application’s workspace; framework-maintenance commands additionally require a framework checkout. A command unavailable in the current scope reports why instead of attempting to operate on an unrelated directory.

Keep the stages of application work distinct

context health, list, info, coherence and journey query the companion. context jurisdictions and context assurance-basis inspect local configuration, specifications and installed authority definitions without it. Those local checks are separate commands, not fallbacks for a failed companion request.

These families share the CLI context, but their effects differ. A context query reads; configuration sync writes generated artifacts; a lifecycle command starts or stops processes. Consult the specific command’s help when automating it rather than assuming every family accepts the same flags.

Understand what the tool automates

Commands declare a phrase-shaped name such as config sync. The registry resolves the longest matching command name, which supports nested command families without a separate parser for each one. Discovery loads command files, and duplicate names fail instead of allowing one implementation to silently replace another.

The tool coordinates framework-owned operations. It does not turn artifact generation into a deployment: config sync produces deployment inputs. Generated workflows build images; the Kubernetes workflow also applies manifests, while Compose rollout requires your host-transfer and deployment steps. Application behavior, release review and the operating environment remain explicit decisions.

From a configuration change to an application query

Use one application workspace and its configured local Docker Compose environment. First inspect the command help, validate the declaration, synchronize derived files and read the diagnosis:

# Discover the flags supported by this installed command.
wildo config sync --help

# Check, regenerate, then diagnose the local environment.
wildo config validate --env local
wildo config sync --env local
wildo local doctor

Resolve reported failures before starting wildo local dev in that terminal. If a development session already owns the workspace, use it rather than creating a second owner. From a second terminal in the same application, run wildo context health, then wildo context journey to inspect eligibility and work in flight. Health establishes reachability; the specific query and compiled-output freshness establish what application information is available.

Keep delivered assets aligned with their source

wildo assets sync replaces the framework-owned template mirror under .wildo-saas/templates/; keep application customizations out of that replaceable mirror. Templates follow the CLI’s framework assets. Documentation, skills and rules instead come from the application’s installed @wildo-ai/framework-knowledge package.

If the command reports version skew, align the CLI installer with the application’s knowledge-package version using its reported --cli-version value, then run wildo assets sync again. Synchronizing assets does not upgrade the CLI. A missing knowledge package requires installation before its documentation and skills can be delivered.

Run these commands from an application workspace with its environment configured. The first command performs the normal sync for the local environment. The narrower command refreshes process environment files when that is the only output needed.

# Refresh the normal set of derived outputs.
wildo config sync --env local

# Or select a specific output domain.
wildo config sync --env local --domain env-files

# Check configuration and, for Kubernetes, rendered manifests.
wildo config validate --env local

The --env value is your configured environment name. Generated CI workflows build images. The Kubernetes workflow also applies manifests; the Compose workflow leaves host transfer and rollout to your deployment setup. Generating these files does not itself deploy the application.

Know which outputs are regenerated

The normal local selection is config and env-files. Select manifest or cicd explicitly when regenerating those outputs; CI adds workflow generation when an application root is available. Provider runtime artifacts are synchronized through the same application generation path.

Missing framework-managed material is provisioned additively before dependent generation; existing material is not rotated merely because new configuration needs another secret.

--force permits overwriting generated files without the normal confirmation. It does not authorize secret rotation: that requires --rotate-secrets. Changing the initialized platform’s database engine is also a separate decision, not a consequence silently authorized by --force.

Separate authored changes from regeneration

config sync projects declarations into generated outputs. config mutate changes supported existing values in the application declaration, with a dry-run option. These are the actual command forms for changing a service’s local port; use a service key present in your application:

# Preview a proposed declaration change.
wildo config mutate set-service-port --service main_backend_api --port 4302 --dry-run

# Apply that declaration change after reviewing it.
wildo config mutate set-service-port --service main_backend_api --port 4302

This is an illustrative port choice, not a required Wildo port. Mutations reject unknown paths and name the failing segment. Regenerate relevant outputs after changing the declaration. config reapply-declaration handles another job: refreshing declaration-managed application configuration stored on the platform, without recreating its credentials or data.

Read validation at the right level

Validation checks configuration coherence. For Kubernetes, the default manifest check renders infrastructure and platform manifests into a temporary sandbox and parses them. For other runtimes, it reports a successful skip; this is not a Docker Compose render/parse check.

For an environment configured to use Kubernetes, check the application’s deployment artifacts after generating them. The example uses an environment named local; choose the registered environment that owns your output:

# Inspect the application Kubernetes output already written by sync.
wildo config validate --env local --domain manifest --deployment-artifacts

This reads the generated application manifests and reports missing output rather than regenerating it. Neither validation mode applies anything to a cluster. Application deployment generation has its own platform and registration prerequisites; if sync reports that generation was skipped, a successful sandbox check does not establish that application workloads were produced.

In CI, --ci changes the credential source to the pipeline’s flat environment variables. It does not change the deployment output directory. Treat generated secret-bearing files as derived private output, not as a replacement for the authored configuration.

Keep local overrides outside generated files

The frontend’s .env and .env.example are both generated. Put deliberate frontend-only overrides in .env.local, which Vite reads with higher precedence and this generator leaves alone. Do not carry that filename rule over to unrelated backend or specialized outputs.

For the env-files domain, existing files require confirmation unless --force is given. Declining, or running non-interactively without force, can skip that environment successfully. Read the reported writes and skips; a successful exit does not mean every existing file was regenerated.

Recover from a failed synchronization

A synchronization can leave successful phase writes in place when another phase fails. Read the phase outcomes and the named error, fix its cause, then retry the needed domain. Exceptions or prerequisite failures may return before the final phase summary.

For example, after correcting an env-file problem, use wildo config sync --env local --domain env-files. This narrows the requested output, but can still perform prerequisite configuration reconciliation, missing-material provisioning and provider-runtime refresh. It is not a rollback or a promise to touch only one file. Inspect the result before restarting consumers.

From the application workspace, use this supervised sequence with a local Docker Compose environment. The inspection commands are independent reads; run them in another terminal while the session remains active.

# Own the development session in this terminal.
wildo local dev

# In another terminal, inspect what is running.
wildo local status
wildo local doctor

local dev claims ownership before replacing stale root-scoped processes, checks startup prerequisites, prepares infrastructure and waits for readiness. Application runtimes start after their prerequisites. The supervised session is more than a command that launches several processes simultaneously.

local dev-status adds build, runtime-gate, supervisor and endpoint detail when a framework checkout and its diagnostic collector (local-dev-status.mjs) are available for the targeted application. It is not a prerequisite for ordinary status and doctor inspection. local status addresses infrastructure status. local doctor combines shared startup preconditions with runtime diagnostics, so a health problem can be located at the appropriate layer.

Choose the effect on processes and data

Reset and reinitialization require destructive confirmation. They are not backup or restore operations. The shared data-wipe path is used for both supported local runtime lanes so removing containers or volume handles is not mistaken for removing their underlying host files.

Diagnose before changing the workspace

# Read the diagnosis, including structured output when needed.
wildo local doctor
wildo local doctor --json

# Read infrastructure logs; optionally name a service.
wildo local logs

The doctor reports findings; it does not kill orphaned watchers or repair stale files. Its checks distinguish prerequisites from observations that require a running stack. A stopped daemon can therefore be reported alongside another actionable environment problem.

If the intent is to stop the whole development stack, wildo dev stop-all combines development-process cleanup with infrastructure shutdown. wildo dev force-stop targets development processes, including orphaned root-scoped watchers. These are explicit mutation commands, separate from the diagnostic reads.

The lifecycle commands operate on local development. Remote environment deployment has its own generated artifacts and pipeline; a healthy local session is not evidence that a remote release has been applied.

Initialize without interrupting another owner

local up brings infrastructure up. local init also converges setup, application registration and generated runtime environment files, then checks the registered application’s managed configuration. Runtime targets are derived from the same prepared registration snapshot. This postcondition is narrower than proving every application process or business workflow healthy.

Full initialization can stop processes and refuses while a live development session owns the shared platform. Stop that owner first when full convergence is needed. If the platform is already running and only this application needs registration, use wildo local init --register-only; it reconciles the application without rebuilding the shared infrastructure. Preserving backing data does not mean preserving running processes.

Check the application and its development surface separately

Run these commands inside the intended application. Keep the foreground development process in its own terminal:

For this supervised startup sequence, select a local Docker Compose environment.

# Terminal 1: prepare and supervise local application development.
wildo local dev

# Terminal 2: inspect the companion serving that application.
wildo context health
wildo context list

# Separate companion readiness from frontend availability.
wildo workbench status

# Open the local workbench destination after startup.
wildo workbench open

dev start is the narrower delegation to the application’s development script. local dev owns broader local preparation and supervision. Follow the workspace’s existing process ownership rather than launching competing supervisors to repair a missing response.

Keep its responsibilities explicit

The observed application registry does not mean that every business resource API is exposed on the companion. Startup uses explicit controller/resource exposure. Inspect those contracts when integrating a new development surface.

Recover interrupted work without hiding the changes

This selected startup excerpt from start-companion-application.service.ts shows reconciliation before the HTTP server starts. Logging is retained; surrounding startup stages are omitted:

try {
  const { reconciledTaskIds } =
    await this.codingAgentDispatchService.reconcileInterruptedApplicationCodingTasks();
  this.logDebug('Startup coding-task reconciliation completed', { interrupted: reconciledTaskIds.length });
  if (reconciledTaskIds.length > 0) {
    this.logger.warn(
      'Startup reconciliation terminalized interrupted application-coding task(s) as '
        + 'INTERRUPTED_REQUIRES_REVIEW — a previous companion process left them PROCESSING. '
        + 'Review their captured change sets before retrying.',
      { reconciledTaskIds },
    );
  }
} catch (error) {
  this.logger.warn('Startup coding-task reconciliation failed; continuing (non-fatal by design).', {
    error: describeCaughtError(error),
  });
}
await this.initializePlatformHttpServer(config.customControllers);

Reconciliation makes the interrupted task reviewable and captures the worktree state. It does not revert the files or assert that the unfinished work succeeded. It is best effort so a reconciliation problem does not prevent the companion from starting and making diagnosis possible.

Keep locality and identity separate

The companion refuses a non-loopback HTTP host. Its protected custom routes use a machine-local token stored under the application state directory with restrictive permissions. Reading that token is not the same as a person’s approval or an application role.

The workbench’s platform-operator identity and resource authorization are separate again. The same email address in the business application’s user store does not make the two identities equivalent.

Check compiled publication when the model looks old

The companion observes compiled application surfaces. Let an edited declaration reach those surfaces before expecting inspection to reflect it. Health checks establish reachability, not that the latest source was successfully compiled or the feature was verified.

The model-refresh mechanism explains that boundary; the development interfaces explain how commands and the browser reach the companion.

Run from an application workspace whose development companion is running. These are actual command forms, not a simulated response:

# Check the companion and read its current query menu.
wildo context health
wildo context list

# Ask about the application's resolved resources and specifications.
wildo context info resources-registry
wildo context info specification-artifacts

# Inspect cross-family coherence.
wildo context coherence

context list fetches behavior identifiers, supported service kinds and service keys from the companion. It does not keep a second catalogue in the CLI. This matters when the installed command line and companion were built at different times.

Target a service and supply the behavior’s input

context info accepts --service to select a service key published by the menu. Without it, the CLI uses the companion’s reported default backend. If no backend is reported, the command asks for an explicit service instead of guessing.

For a parameterized behavior, --input supplies JSON. Select the behavior and its expected input from the live menu and the corresponding contract. Invalid JSON is rejected before the introspection request.

The client’s request is a selected excerpt from ContextInfoCommand, with its response type annotation omitted; input parsing and service selection happen before it:

const result = await CompanionClient.post(
  '/api/companion/_meta/introspect',
  { serviceKey, behavior, ...(input !== undefined ? { input } : {}) },
  options,
);

This POST asks for a derivation. The context family is read-only: it does not apply a configuration change or repair a reported inconsistency.

Read a concrete output without overstating it

This illustrative source line follows the CLI’s formatter. The address and service key are examples, not a captured run. The application-specific payload follows it:

source: dev-companion http://localhost:4302 · introspection resources-registry on backend · freshness: compiled application packages; companion reused a held derivation

An absent resource calls for a service, registration and compilation check. A present resource shifts the investigation toward its configuration and actual behavior. Neither result is a substitute for running the feature.

Interpret the answer and its provenance

The CLI prints a source line identifying the companion address and queried surface, followed by plain text or pretty-printed JSON. Introspection materializes application packages through their compiled ./companion exports. A source edit must reach those emitted surfaces before an answer can reflect it; the terminal’s source label is not proof that an unbuilt change is already available.

For the connected module example, the new shared descriptor reaches the companion through the existing shared-registry loader. Its initial resource registry is empty: a resource query cannot prove or disprove that empty module’s registration merely by looking for a support resource. After adding a resource, check its resolved declaration and service context, then verify the behavior through the application.

The companion can reuse a successful held derivation or join an identical derivation already in flight. Its watcher observes emitted application files and injected framework bytes, triggering refresh when those inputs change. Without an active watcher, per-read observation provides the fallback. A query therefore need not spawn another subprocess to answer the same question. Journey and coherence reads combine specification exports with working-tree file and Git state. Their provenance therefore differs from a resource introspection result; neither header establishes that every source edit has compiled.

Use the reported service and behavior to identify what was inspected. A successful answer establishes that result, not the freshness of unrelated packages or the success of the business feature.

The output includes provenance text as well as structured payloads; a consumer should not treat the entire stdout stream as a bare JSON document. Catalogue and journey reads have a bounded read timeout, while subprocess-based introspection has a longer one.

A companion failure is reported with a direction to context health; there is no fallback to a CLI-authored approximation of the application. Coherence reporting explains problems but does not itself block a release or mutate the definitions.