### Minimal Example: Start and Cancel DelayTask

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/delay-task-api-contract.md

Demonstrates how to create a DelayTask, add a delay, start it, and then cancel it if it's active. Use this when you need to initiate a delayed task and potentially abort it before it executes.

```java
DelayTask delayTask = DelayTaskKit.of(taskId, () -> runLater())
        .plusTime(Duration.ofSeconds(2))
        .task();

if (delayTask.isActive()) {
    delayTask.cancel();
}
```

--------------------------------

### Troubleshoot MCP Client Server Start

Source: https://github.com/iohao/ionet-ai/blob/main/docs/user-installation.md

Synchronize MCP and attempt to start the MCP client server. Use this if the MCP client fails to start the server.

```bash
uv sync --extra mcp
uv run --project /path/to/ionet-ai --extra mcp ionet-ai serve mcp
```

--------------------------------

### Disallowed Default Starter Example

Source: https://github.com/iohao/ionet-ai/blob/main/stable/faq/ionet-example-evidence-calibration-faq.md

Demonstrates what should not be used as a default starter for new projects. This includes copying specific configurations like fixed ports, helper factories, and sample modules from examples.

```text
Copy ionet-multi-process with one-client, fixed ports, helper factories, and sample author/book modules for every new project.
```

--------------------------------

### RunOne Startup Assembly

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/run-one-startup-api-contract.md

Use `new RunOne()` for startup assembly when the code is in scope. This example shows a basic setup for aggregate startup.

```java
new RunOne()
    .setAeron(aeron)
    .setExternalServer(externalServer)
    .setLogicServerList(logicServerList)
    .startup();
```

--------------------------------

### ExternalServer Startup

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/external-server-builder-api-contract.md

Starts the ExternalServer with a provided NetServer.

```APIDOC
## ExternalServer Startup

### Description
Starts the `ExternalServer`.

### Method
`void ExternalServer.startup(NetServer netServer)`

### Parameters
#### `startup(NetServer netServer)`
- **netServer** (NetServer) - Required - The NetServer instance to use for startup.
```

--------------------------------

### Route Definition File Example

Source: https://github.com/iohao/ionet-ai/blob/main/rules/project-structure-rules.md

Shows a positive example of a route definition file adhering to conventions for command routing, constant declaration, and broadcast route handling.

```java
public interface XxxCmd {
    int cmd = CmdModule.broadcastCmd;
    int hello = 1;

    AtomicInteger inc = new AtomicInteger(50);
    // ---------- broadcast ----------
    CmdInfo broadcastUserEmpty = ofBroadcastCmd();
    CmdInfo broadcastUserInt = ofBroadcastCmd();

    static CmdInfo ofCmdInfo(int subCmd) {
        return CmdInfo.of(cmd, subCmd);
    }

    private static CmdInfo ofBroadcastCmd() {
        return CmdInfo.of(cmd, inc.getAndIncrement());
    }
}
```

--------------------------------

### Minimal Example

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/on-external-api-contract.md

A minimal example demonstrating the implementation of an `OnExternal` handler, a template ID interface, and the registration process.

```APIDOC
## Minimal Example

### Description
A minimal example demonstrating the implementation of an `OnExternal` handler, a template ID interface, and the registration process.

### Handler Implementation Example
```java
public final class UserIpOnExternal implements OnExternal {
    @Override
    public void process(byte[] payload, int payloadLength, OnExternalContext context) {
        UserSession userSession = context.getUserSession();
        ActionErrorEnum.dataNotExist.assertNonNull(userSession);
        context.response().setPayload(userSession.getIp());
    }

    @Override
    public int getTemplateId() {
        return MyOnExternalTemplateId.userIp;
    }
}
```

### Template ID Interface Example
```java
public interface MyOnExternalTemplateId {
    int userIp = 1;
}
```

### Registration Example
```java
OnExternalManager.register(new UserIpOnExternal());
```
```

--------------------------------

### Install Project with Bash

Source: https://github.com/iohao/ionet-ai/blob/main/docs/architecture-summary.md

Installs the ionet-ai project into a target project using the provided bash script. Ensure the project path is correctly specified.

```bash
bash scripts/install-project.sh --project /path/to/project
```

--------------------------------

### Install ionet-ai and Wire Target Project

Source: https://context7.com/iohao/ionet-ai/llms.txt

Clone the ionet-ai repository, install MCP runtime dependencies, and then wire ionet-ai into your existing ionet project. This script writes several configuration and agent files into your project directory.

```bash
# Clone ionet-ai and install MCP runtime dependencies
git clone https://github.com/iohao/ionet-ai
cd ionet-ai
uv sync --extra mcp

# Wire ionet-ai into your ionet project
bash scripts/install-project.sh --project /path/to/your-ionet-project
# Writes:
#   /path/to/your-ionet-project/.codex/skills/ionet-ai/
#   /path/to/your-ionet-project/.mcp.json
#   /path/to/your-ionet-project/codex-ionet.sh
#   /path/to/your-ionet-project/AGENTS.md   (managed block)
#   /path/to/your-ionet-project/CLAUDE.md   (managed block)
```

--------------------------------

### Local Source Installation Command

Source: https://github.com/iohao/ionet-ai/blob/main/stable/faq/ionet-framework-installation-boundary-faq.md

Use this command to install the ionet framework from a local source checkout. This is typically for maintainers or users needing unreleased fixes.

```text
clone the ionet framework source, then run Maven install from that source tree
```

--------------------------------

### Custom FlowContext Factory Binding

Source: https://github.com/iohao/ionet-ai/blob/main/docs/framework-extension-naming-examples.md

Demonstrates how to install a custom FlowContext by binding its factory during application startup.

```java
CoreGlobalConfig.setting.flowContextFactory = MyFlowContext::new;
```

--------------------------------

### Install Project Script

Source: https://github.com/iohao/ionet-ai/blob/main/README.md

Run this script from the repository root to install ionet-ai knowledge sources into a target project. It configures Codex CLI, Claude Code CLI, and generates a local launcher.

```bash
bash scripts/install-project.sh --project /path/to/your-project
```

--------------------------------

### Minimal Example - ObjectProperty

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/property-listener-api-contract.md

Demonstrates adding a listener to an ObjectProperty and setting a new object value.

```APIDOC
```java
ObjectProperty<UserState> current = new ObjectProperty<>(oldState);
current.addListener((observable, oldValue, newValue) -> {
    log.info("state reference changed");
});
current.set(newState);
```
```

--------------------------------

### Run Minimal ionet Starter

Source: https://github.com/iohao/ionet-ai/blob/main/assets/minimal-ionet-starter/README.md

Execute the packaged JAR file from the command line. Ensure to include the necessary JVM arguments for opening specific modules and enabling native access.

```bash
java \
--add-opens java.base/jdk.internal.misc=ALL-UNNAMED \
--enable-native-access=ALL-UNNAMED \
-jar target/minimal-ionet-starter.jar
```

--------------------------------

### Aggregate Startup Example

Source: https://github.com/iohao/ionet-ai/blob/main/rules/project-structure-rules.md

Illustrates the correct structure for an aggregate startup class, emphasizing naming conventions and avoiding business logic mixing.

```java
package app;

public final class MainApplication {
    static void main() {
        new RunOne().startup();
    }

    LoginMessage login(LoginMessage message) {
        return message;
    }
}
```

--------------------------------

### Domain Event Application Lifecycle and Publishing

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/domain-event-api-contract.md

Register handlers, start the application, publish an event, and stop the application. This example demonstrates the basic lifecycle and event publishing for `StudentEo`.

```java
DomainEventSetting setting = new DomainEventSetting();
setting.addEventHandler(new StudentEmailEventHandler());

DomainEventApplication application = new DomainEventApplication();
application.startup(setting);

new StudentEo(1).send();
application.stop();
```

--------------------------------

### RunOne Startup Execution Chain

Source: https://github.com/iohao/ionet-ai/blob/main/candidate/source-analysis/run-one-assembly-boundary.md

This outlines the sequence of operations performed by the `RunOne.startup()` method. It covers Aeron requirements, default settings, server building, logic server integration, and duplicate route detection.

```text
RunOne.startup()
  -> require aeron
  -> defaultSetting() 
     -> publisher startup
     -> NetServerBuilder defaults
     -> optional CenterServerBuilder startup
  -> netServerBuilder.build()
  -> optional externalServer.startup(netServer)
  -> for each LogicServer:
       LogicServerApplication.startup(logicServer)
       netServer.addServer(server)
  -> netServer.onStart()
  -> ActionCommandRegionGlobalCheckKit.detectGlobalDuplicateRoutes()
```

--------------------------------

### LogicServerApplication Startup Assembly

Source: https://github.com/iohao/ionet-ai/blob/main/candidate/source-analysis/logic-server-application-assembly-boundary.md

Illustrates the sequence of operations in LogicServerApplication.startup, showing the creation and configuration of BarSkeleton and Server from a LogicServer.

```java
package com.iohao.net.server.logic;

import com.iohao.net.framework.protocol.ServerBuilder;
import com.iohao.net.server.BarSkeleton;
import com.iohao.net.server.BarSkeletonBuilder;
import com.iohao.net.server.LogicServer;
import com.iohao.net.server.LogicServerManager;
import com.iohao.net.server.NetServerAbout;
import com.iohao.net.server.Server;

public class LogicServerApplication {

    public void startup(LogicServer logicServer) {
        // 1. Create BarSkeleton builder and let LogicServer configure it
        BarSkeletonBuilder barSkeletonBuilder = BarSkeleton.builder();
        logicServer.settingBarSkeletonBuilder(barSkeletonBuilder);
        BarSkeleton barSkeleton = barSkeletonBuilder.build();

        // 2. Create Server builder, attach skeleton, and let LogicServer configure it
        ServerBuilder serverBuilder = new ServerBuilder();
        logicServer.settingServerBuilder(serverBuilder);
        serverBuilder.setBarSkeleton(barSkeleton);
        Server server = serverBuilder.build();

        // 3. Record route regions for global duplicate checks
        ActionCommandRegionGlobalCheckKit.putActionCommandRegions(server.id(), server.getActionCommandRegions());

        // 4. Store LogicServer for later startup callback and register with BarSkeletonManager
        BarSkeletonManager.putBarSkeleton(server.id(), barSkeleton);
        barSkeleton.server = server;
        LogicServerManager.put(server.id(), logicServer);

        // 5. NetServerAgent handles further startup steps (communication, runners, callbacks)
        // This part is handled by NetServerAgent.registerServerToCenter() and related components
        // which are out of scope for this direct assembly analysis.
    }
}
```

--------------------------------

### Start the aggregation service (one-application)

Source: https://github.com/iohao/ionet-ai/blob/main/assets/multi-process-ionet-starter/README.md

This command starts the main aggregation service, which includes the embedded Aeron MediaDriver, CenterServer, and Netty WebSocket external service. Ensure this is started first.

```bash
java --add-opens java.base/jdk.internal.misc=ALL-UNNAMED \
     --enable-native-access=ALL-UNNAMED \
     -jar one-application/target/one-application.jar
```

--------------------------------

### Custom Protocol Implementation Example

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/external-message-api-contract.md

Example of implementing a custom message and codec for the external protocol.

```APIDOC
## Custom Protocol Implementation Example

### Description
This section provides a minimal example of how to implement a custom message class and its corresponding codec.

### Custom Message Example
```java
@ProtobufClass
public final class MyExternalMessage extends AbstractCommunicationMessage {
    @Protobuf(fieldType = FieldType.INT32, order = 1)
    int cmdMerge;

    @Protobuf(fieldType = FieldType.BYTES, order = 2)
    byte[] data;
}
```

### Custom Codec Example
```java
public final class MyCommunicationMessageCodec implements CommunicationMessageCodec {
    @Override
    public CommunicationMessage createCommunicationMessage() {
        return new MyExternalMessage();
    }

    @Override
    public CommunicationMessage decode(byte[] bytes) {
        return DataCodecManager.decode(bytes, MyExternalMessage.class);
    }
}
```

### Codec Configuration Example
```java
CommunicationMessageKit.communicationMessageCodec = new MyCommunicationMessageCodec();
```
```

--------------------------------

### ionet-ai CLI Examples

Source: https://github.com/iohao/ionet-ai/blob/main/README.md

Demonstrates various commands for interacting with the ionet-ai knowledge base via its CLI. Includes searching, verifying upstream facts, diagnosing issues, assembling features, and validating projects.

```bash
uv run ionet-ai kb search "FlowContext"
```

```bash
uv run ionet-ai kb verify-upstream --fact artifact-version --coordinate com.iohao.net:run-one
```

```bash
uv run ionet-ai diagnose "generate an ionet Action feature"
```

```bash
uv run ionet-ai assemble "generate an ionet Action feature" --mode Generate
```

```bash
uv run ionet-ai validate-project --project /path/to/your-project
```

--------------------------------

### Required Startup Wiring for External Server

Source: https://github.com/iohao/ionet-ai/blob/main/rules/external-server-generation-rules.md

Demonstrates how to wire the generated external server into the application's startup process using `RunOne.setExternalServer(...)`. The `.build()` call should be at the startup site.

```java
class OneApplication {
    static void main() {
        var externalServer = MyExternalServer.builder(
                ExternalGlobalConfig.externalPort,
                ExternalJoinEnum.WEBSOCKET
        ).build();

        new RunOne()
                .setExternalServer(externalServer)
                .startup();
    }
}
```

--------------------------------

### Allowed Distillation Example

Source: https://github.com/iohao/ionet-ai/blob/main/stable/faq/ionet-example-evidence-calibration-faq.md

Illustrates a conclusion that can be distilled from an example for use in generation. Focuses on specific aspects like room operation handling.

```text
The example shows that room operation handling should preserve Action entry and operation-handler ownership.
```

--------------------------------

### Start the author logic service

Source: https://github.com/iohao/ionet-ai/blob/main/assets/multi-process-ionet-starter/README.md

Starts the independent author logic server. This service also communicates with the aggregation service via Aeron IPC.

```bash
java --add-opens java.base/jdk.internal.misc=ALL-UNNAMED \
     --enable-native-access=ALL-UNNAMED \
     -jar logic-author/target/logic-author.jar
```

--------------------------------

### RunOne Startup Assembly

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/run-one-startup-api-contract.md

Demonstrates the chain-style setters and the terminal `startup()` method for assembling and launching an application using `RunOne`.

```APIDOC
## RunOne Startup Assembly

### Description
This section details the API surface for `RunOne`, including its import, chain-style setters generated by Lombok, an explicit center-server toggle, and the terminal `startup()` method.

### API Surface
- Startup class import: `com.iohao.net.app.RunOne`
- Aeron import: `io.aeron.Aeron`
- External server import: `com.iohao.net.external.core.ExternalServer`
- Logic server import: `com.iohao.net.server.LogicServer`
- Collection imports: `java.util.List`

### Chain-Style Setters (Generated by Lombok)
- `RunOne setAeron(Aeron aeron)`
- `RunOne setExternalServer(ExternalServer externalServer)`
- `RunOne setLogicServerList(List<LogicServer> logicServerList)`
- `RunOne setNetServerBuilder(NetServerBuilder netServerBuilder)`
- `RunOne setCenterServerBuilder(CenterServerBuilder centerServerBuilder)`
- `RunOne setPublisher(Publisher publisher)`
- `RunOne setServerShutdownHookList(List<ServerShutdownHook> serverShutdownHookList)`

### Explicit Center-Server Toggle
- `RunOne enableCenterServer()`

### Startup Terminal Method
- `void startup()`

### External Server Builder Shape
- `ExternalMapper.builder(port).build()`
- `ExternalMapper.builder(port, ExternalJoinEnum.WEBSOCKET).build()`

### Usage Example (Conceptual)
```java
// In a single-process or quick-start scenario:
RunOne runOne = new RunOne()
    .setAeron(aeronInstance)
    .setExternalServer(externalServerInstance)
    .setLogicServerList(listOfLogicServers)
    .enableCenterServer(); // If this process owns the center server

runOne.startup();
```

```java
// In a local multi-process scenario, for an independent logic-process:
RunOne runOne = new RunOne()
    .setLogicServerList(listOfLogicServers);

runOne.startup();
```
```

--------------------------------

### Start the test client

Source: https://github.com/iohao/ionet-ai/blob/main/assets/multi-process-ionet-starter/README.md

Launches the test client which connects to the external port of the one-application service via WebSocket and sends test requests.

```bash
java -jar one-client/target/one-client.jar
```

--------------------------------

### RunOne Startup: Single-process and Multi-process Assembly

Source: https://context7.com/iohao/ionet-ai/llms.txt

Use `enableCenterServer()` for single-process aggregate startup. Omit it for multi-process independent logic-process entry.

```java
import com.iohao.net.app.RunOne;
import com.iohao.net.external.core.config.ExternalGlobalConfig;
import com.iohao.net.external.core.config.ExternalJoinEnum;
import com.iohao.net.external.core.netty.ExternalMapper;
import java.util.List;

// Single-process aggregate startup
public final class OneApplication {
    static void main() {
        var aeron = new EmbeddedAeronRuntime().getAeron();
        var externalServer = ExternalMapper
                .builder(ExternalGlobalConfig.externalPort, ExternalJoinEnum.WEBSOCKET)
                .build();

        new RunOne()
                .setAeron(aeron)
                .enableCenterServer()           // owns the single CenterServer
                .setExternalServer(externalServer)
                .setLogicServerList(List.of(new HallLogicServer()))
                .startup();
    }
}

// Multi-process: independent logic-process entry
public final class HallApplication {
    static void main() {
        new RunOne()
                .setAeron(aeron)
                .setLogicServerList(List.of(new HallLogicServer()))
                .startup();                     // no enableCenterServer() here
    }
}
```

--------------------------------

### Start the book library logic service

Source: https://github.com/iohao/ionet-ai/blob/main/assets/multi-process-ionet-starter/README.md

Starts the independent book library logic server. This service communicates with the aggregation service via Aeron IPC.

```bash
java --add-opens java.base/jdk.internal.misc=ALL-UNNAMED \
     --enable-native-access=ALL-UNNAMED \
     -jar logic-book-library/target/logic-book-library.jar
```

--------------------------------

### Positive Example: Correct Server Boundary Structure

Source: https://github.com/iohao/ionet-ai/blob/main/rules/server-boundary-rules.md

Demonstrates the correct separation of concerns where OneApplication handles startup assembly, LogicServer manages module-local builder configuration, and Action handles runtime execution. Use this structure to ensure clear ownership and distinct responsibilities.

```java
public final class OneApplication {
    void start(UserLogicServer logicServer) {
        new RunOne()
                .setLogicServerList(List.of(logicServer))
                .startup();
    }
}
```

```java
public class UserLogicServer implements LogicServer {
    @Override
    public void settingBarSkeletonBuilder(BarSkeletonBuilder builder) {
        builder.scanActionPackage(UserAction.class);
    }

    @Override
    public void settingServerBuilder(ServerBuilder builder) {
        // module-local builder configuration only
    }
}
```

```java
@ActionController(UserCmd.cmd)
public class UserAction {
    @ActionMethod(UserCmd.login)
    private LoginMessage login(LoginMessage message) {
        return message;
    }
}
```

--------------------------------

### Install MCP Runtime Dependencies

Source: https://github.com/iohao/ionet-ai/blob/main/README.md

Synchronizes and installs the necessary runtime dependencies for the MCP service. This command ensures that all required packages are available for MCP operations.

```bash
uv sync --extra mcp
```

--------------------------------

### Start with Claude Code CLI

Source: https://context7.com/iohao/ionet-ai/llms.txt

Initiate the Claude Code CLI. It automatically reads the CLAUDE.md file and starts the ionet-ai MCP server using the configuration in .mcp.json.

```bash
# From your ionet project root
claude
# Claude Code reads CLAUDE.md and auto-starts ionet-ai MCP via .mcp.json
```

--------------------------------

### Disallowed Default Generation Example

Source: https://github.com/iohao/ionet-ai/blob/main/stable/faq/ionet-example-evidence-calibration-faq.md

Shows an example of what should not be copied directly into default generation. This includes full module layouts, client runners, and demo class names.

```text
Copy the full room demo module layout, client runner, and all demo class names into every room feature.
```

--------------------------------

### Promotion Flow Example

Source: https://github.com/iohao/ionet-ai/blob/main/docs/knowledge-engineering-playbook.md

Illustrates the narrow promotion path for knowledge assets, emphasizing distillation into reviewable assets before direct use in generation.

```text
source material
  -> candidate note
  -> reviewed conclusion
  -> stable rule, concept, pattern, template, checklist, FAQ, or source policy
  -> task assembly through skill-defs
```

--------------------------------

### Delayed User Broadcast Example

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/communication-kit-api-contract.md

This example demonstrates how to schedule a delayed broadcast to a user using DelayTaskKit. It extracts the userId and schedules the broadcast to occur after a specified duration.

```java
long userId = flowContext.getUserId();

DelayTaskKit.of(taskId, () -> CommunicationKit.getCommunication()
        .broadcastUser(userId, UserCmd.broadcastSelfMessage, text))
        .plusTime(Duration.ofSeconds(2))
        .task();
```

--------------------------------

### Multi-Process Aggregate Entry Layout

Source: https://github.com/iohao/ionet-ai/blob/main/rules/project-structure-rules.md

Example directory structure for a multi-process project. It distinguishes the aggregate entry point (`OneApplication`) from independent logic-process startup classes (`AuthorApplication`, `BookLibraryApplication`), clarifying the three-layer relationship.

```text
one-application/
  src/main/java/com/example/project/OneApplication.java
logic-author/
  src/main/java/com/example/project/AuthorApplication.java
  src/main/java/com/example/project/AuthorLogicServer.java
logic-book/
  src/main/java/com/example/project/BookLibraryApplication.java
  src/main/java/com/example/project/BookLibraryLogicServer.java
```

--------------------------------

### Claude Code CLI Startup

Source: https://github.com/iohao/ionet-ai/blob/main/docs/user-installation.md

Starts Claude Code CLI, which reads the project's CLAUDE.md and starts the ionet-ai MCP server via .mcp.json. Run from the target project root.

```bash
claude
```

--------------------------------

### External Server Builder with Port

Source: https://github.com/iohao/ionet-ai/blob/main/stable/api-contracts/run-one-startup-api-contract.md

Demonstrates constructing an external server using `ExternalMapper.builder(port)`. This is a common pattern for setting up external server boundaries.

```java
ExternalMapper.builder(port).build()
```

--------------------------------

### Action Controller Structure Example

Source: https://github.com/iohao/ionet-ai/blob/main/rules/action-rules.md

Demonstrates a standard Action controller with multiple methods handling different commands. Shows how to use custom FlowContext and handle request/response, request/void, and request/broadcast patterns.

```java
package feature.action;

@ActionController(FeatureCmd.cmd)
public class FeatureAction {
    @ActionMethod(FeatureCmd.query)
    private FeatureResultMessage query(FeatureQueryMessage message) {
        var result = new FeatureResultMessage();
        result.id = message.id;
        return result;
    }

    @ActionMethod(FeatureCmd.sync)
    private List<FeatureResultMessage> sync(FeatureQueryMessage message, FlowContext flowContext) {
        return List.of(query(message));
    }

    @ActionMethod(FeatureCmd.online)
    private boolean online(FlowContext flowContext) {
        return flowContext != null;
    }

    @ActionMethod(FeatureCmd.profile)
    private String profile(MyFlowContext flowContext) {
        return flowContext.currentAttachment() != null ? "ok" : "empty";
    }
}
```