Application development workbench

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.

Understand what is observed

The observed input is the application’s compiled companion-facing surfaces. Unsaved edits and source changes that have not been emitted are outside that view. A successful query says an answer was served; it does not certify completion of the latest build.

Watcher registration follows successful attachment. Periodic reconciliation provides a check alongside filesystem events; losing the watcher authority returns the service to observation on reads. Warm reuse is conditional, not a promise that every read is only a lookup.

Publish changes at the resource boundary

This selected excerpt from introspection-resource-notifier.companion.service.ts follows the guard requiring a previous result. Formatting is expanded to make the before/after comparison visible:

const resourceTypes =
  this.resourceSource.resolveResourceTypesByBehavior().get(outcome.behavior) ?? [];

for (const resourceType of resourceTypes) {
  const identityField = this.resourceSource.resolveRowIdentityField(resourceType);
  const before = this.resourceSource.projectRowsForResource(
    resourceType,
    outcome.previous.result.data,
  );
  const after = this.resourceSource.projectRowsForResource(
    resourceType,
    outcome.next.result.data,
  );
  if (!after || !before) continue;

  const diff = diffProjectedRows(before, after, identityField);
  this.publishDiff(
    resourceType,
    identityField,
    diff,
    outcome.next.generation,
  );
}

The projections turn a behavior’s derived answer into the relevant resource rows. The identity field lets the comparison distinguish created, changed and removed rows. Publication supplies row-level updates and a collection refresh for their respective consumers.

This is framework implementation, not extra subscription code an application author must write. It explains why changing one projected row need not be represented as a replacement of every row.

Diagnose an old-looking answer in the right order

# Confirm that the intended companion is reachable.
wildo context health

# After the application's compile/publication has completed:
# discover the available views and inspect the resolved resource model.
wildo context list
wildo context info resources-registry

# Compare its declared specification view when investigating a change.
wildo context info resource-specifications

Read the response’s provenance and freshness information. Explicit cache reuse is useful evidence about the answer; an absent cache flag is not proof of a fresh subprocess import. If the expected model is absent, investigate the compiled publication and serving process before repeatedly editing a declaration that may already be correct.

Finally, exercise the consumer you care about. A server-side change notification and a browser applying that change are different observations; model inspection alone does not establish the latter.

Query from the application workspace

The following inspection sequence assumes that this application’s companion is running. These behavior identifiers exist in the companion catalogue; the live menu remains the source for service keys and available views:

# Check that this application's companion answers.
wildo context health

# Discover behaviors and their available service keys.
wildo context list

# Inspect resolved resources and their specifications.
wildo context info resources-registry

# Read the declared contracts alongside the registry.
wildo context info resource-specifications

# Inspect the exposed specification artifacts.
wildo context info specification-artifacts

# Read creation state and cross-family coherence.
wildo context journey
wildo context coherence

The sequence is a set of read-only questions, not a generation or acceptance workflow. Its results help select the next action; they do not execute that action.

Turn retrieved context into an editing decision

The following is an illustrative reasoning record, not a captured response or an automatic decision made by the companion:

The companion supplies context; the agent makes the coding decision. Carry the relevant returned names, contracts and provenance into the editing task. Compare them with source files rather than treating either a partial file search or one model response as the entire application.

For selecting a service, supplying behavior input and reading the output format, follow terminal inspection. For creation-state and cross-family checks, use the dedicated journey and coherence queries described in the application context workflow.

Preserve the provenance when using an answer

The human/tool output includes a provenance line followed by a formatted payload. It is not a pure JSON stdout contract to feed blindly into a JSON parser.

For compiled-model queries, the CLI explains that unemitted source edits are absent. A response reporting servedFromCache: true establishes reuse of a held derivation; missing reuse information does not establish that a fresh subprocess ran. Journey and coherence answers have different source semantics, so keep the provenance attached when passing information into a coding task.

Read-only does not mean every HTTP request is GET

The introspection call used by context info is a read-only POST. The CLI supplies the machine-local token that the custom companion router requires for that request. This access contract is separate from production API permissions or human approval of a code change.

The wider context command family also contains other tools, including assurance-related commands. The companion-backed sequence above is not an exhaustive claim about every subcommand or about all of them requiring a running companion.

Turn the answer into a checked change

Use the returned names and contracts to ground the edit, then compile and test the relevant application behavior. Re-querying a registry can show that the expected declaration is exposed; it cannot show that the full operation works for a particular user’s role and data.

Open the workbench for the intended application

Run these commands from a configured application root using a local Docker Compose environment. The development command stays in its own terminal:

# Terminal 1: start the supervised local development environment.
wildo local dev

# Terminal 2: check the companion and discover its inspection views.
wildo context health
wildo context list

# Read the separate companion, semantic and frontend readiness fields.
wildo workbench status

# Open the application-specific local browser destination.
wildo workbench open

A successful status command means the status was read, not that every field says ready. Opening the URL does not start a missing frontend process. The workbench has its own local origin; its development server proxies /api and /health to the companion.

Reuse application contracts in the development interface

The workbench is an ordinary Wildo frontend. Its bootstrap supplies resource configurations, relationships and UI behavior to ApplicationMainProvider. This selected excerpt from the workbench’s main.tsx shows that connection; surrounding environment setup and the provider’s remaining options are omitted:

ReactDOM.createRoot(rootElement).render(
  <React.StrictMode>
    <ApplicationMainProvider
      options={{
        env: workbenchEnvironment,
        customShared_ResourcesConfigurationsFactoryMap: workbenchComposedResourcesConfigurationsFactoryMap,
        customShared_ResourceFieldIdentifier: workbenchComposedResourceFieldIdentifier,
        customShared_ResourcesRelationships: workbenchComposedResourcesRelationships,
        excludedResourceTypes: WORKBENCH_EXCLUDED_RESOURCE_TYPES,
        baseFrontendConfig: APP_STANDARD,
        resourceUIBehavior: workbenchModuleRegistry.resourceUIBehavior,
        // Additional shell options omitted from this reduced excerpt.
      }}
    />
  </React.StrictMode>,
);

The highlighted resource contracts define what the workbench can represent and connect. The UI behavior controls how those resources are presented. This is framework implementation evidence, not a new bootstrap the application author must copy.

Separate identity, resource actions and local commands

Authentication establishes the operator’s identity; inspect each resource operation’s authorization and application context when evaluating access. Do not infer universal cross-application isolation from the login screen alone.

Read the result as well as its status

The workbench provides representations of specification artifacts and development activity. A completed activity is useful navigation into its output; it does not prove that the resulting application satisfies its requirements. Inspect the artifact or diff and the verification relevant to that change.

The execution trace explains recorded inputs and events. The companion interface explains how development surfaces reach their services.

See where tracing enters generation

This excerpt is from the generation loop in playbook-generation-run.application-creation.service.ts, with formatting expanded and commentary omitted. It shows an attempt’s event and saved brief; model invocation and validation follow it:

while (attempts < maximumAttempts) {
  attempts += 1;
  const prompt = attempts === 1
    ? output.brief
    : `${output.brief}\n\n# YOUR PREVIOUS ANSWER WAS REJECTED\n${rejectedFindings.at(-1) ?? ""}\n`
      + "Correct exactly those points. Everything else about the contract is unchanged.";

  await trace.event({
    type: PlaybookExecutionTraceEvent.GENERATION_REQUESTED,
    summary: `Ask the model for "${output.family}" (attempt ${attempts} of ${maximumAttempts})`,
    payload: {
      playbookRef: input.playbookRef,
      family: output.family,
      schemaRef: output.schemaRef,
      attempt: attempts,
    },
  });
  await trace.artifact({
    fileName: `${output.family}.attempt-${attempts}.brief.md`,
    content: prompt,
    format: PlaybookExecutionTraceArtifactFormat.TEXT,
  });
  // Model invocation and answer validation follow.

The retry brief includes the preceding rejection findings. The event’s family, schema and attempt identify the work being requested; the artifact stores the prompt that attempt receives. Those are related diagnostic records, not an extra acceptance state.

Read sessions and their artifacts

The colon-prefixed segments are identifiers obtained from the preceding reads. The reader restricts their characters rather than accepting arbitrary filesystem paths. The session-list limit accepts integers from 1 to 200; omission uses its default.

Briefs are saved as Markdown; structured answers can be JSON. Do not assume every artifact is raw model prose, or parse the artifact route as a JSON response solely because its filename ends in .json.

Distinguish evidence of a run from correctness of its output

Tracing is optional and best effort. The default trace port discards events; companion integration supplies file-backed tracing for a request session. A missing trace does not prove that no work happened. A present trace is not an application audit log, a guarantee of successful publication or a replacement for verification.

Choose the route by its contract

The companion’s custom controller is not its entire HTTP surface. Startup also mounts the resource and support controllers needed by the workbench. CLI and browser calls can use different routes to reach related services.

Understand the custom router’s local-token check

The following selected functions come from companion-token-floor.policy.ts. They show the decision at this router only; the constants and token validator are defined elsewhere:

export function companionRequestRequiresLocalToken(method: string, path: string): boolean {
  if (COMPANION_TOKEN_FLOOR_UNGATED_METHODS.has(method.toUpperCase())) return false;
  return !COMPANION_TOKEN_FLOOR_BROWSER_EXEMPT_PATHS.includes(path);
}

export function companionRequestIsAdmittedByTokenFloor(
  request: { readonly method: string; readonly path: string; readonly presentedToken: string | string[] | undefined },
  isValidToken: (presented: string | undefined) => boolean,
): boolean {
  if (!companionRequestRequiresLocalToken(request.method, request.path)) return true;
  return isValidToken(typeof request.presentedToken === 'string' ? request.presentedToken : undefined);
}

The first decision selects whether the request requires the token. The second validates one string header value when it does. Repeated header values are not searched for a matching token.

GET, HEAD and OPTIONS bypass this particular token check. Other methods require it unless the mount-relative path is one of the explicit browser exceptions: /playbooks/refresh-board, /compliance/governance-facts or /coding-agent/cancel. These are exceptions to this floor, not a claim that every browser action has the same authorization contract.

Let the CLI handle its local credential

The CLI reads the application’s machine-local companion token and attaches it to requests that need it. A read-only introspection operation can use POST and therefore require that token: HTTP method and business side effect are different questions.

Token possession establishes access to a local file, not a human approval or an application role. The resource-operation plane has its own identity and authorization checks. Keep these boundaries separate when adding an integration or diagnosing a refused request.

Discover an inspection contract before using it

# Is the companion serving this application?
wildo context health

# Which behaviors and service keys are available?
wildo context list

# Read one supported model view through the CLI client.
wildo context info resources-registry

Use the documented command or workbench operation for normal development. If implementing a client, inspect the exact endpoint’s request, response and error contract; there is no universal “every route is an unauthenticated read” or “every route is a resource operation” rule.