A plan can be internally consistent and still solve the wrong problem.

It can contain sensible milestones, a plausible architecture, and a thorough testing strategy while depending on an audience that has never been established, a capability that does not exist, or a requirement that nobody actually agreed to.

The problem is not necessarily poor planning. It is allowing planning to begin before there is a sufficiently developed understanding of what is being planned.

I treat that gap as a separate engineering problem: how do we turn an uncertain idea into a researched, bounded, inspectable input without prematurely converting it into implementation work?

My answer is a persistent brainstorming mode built around an explicit control loop. It has durable state, a fixed research team, stable identifiers, evidence requirements, validation rules, and a deliberate handoff to planning.

The important distinction is that this is not a request for an AI to “think harder.” It is a protocol governing what the system may do while understanding is still being developed.

Discovery Is Not Planning

Discovery, planning, and implementation answer different questions.

Discovery asks what the idea means, what supports it, what remains uncertain, and what a successful outcome would look like.

Planning asks how to reach that outcome under the established constraints.

Implementation performs the authorized work and produces evidence that the result meets its requirements.

The relationship is straightforward:

Uncertain idea  
    -> Clarification and research
    -> Plan-ready element
    -> Explicit selection for planning
    -> Authorized execution

The arrows are transitions, not automatic consequences.

A thoroughly researched idea does not authorize a plan. A plan does not authorize every operation required to implement it. A successful implementation does not, by itself, authorize publication or deployment.

This gives the discovery stage an important invariant:

While brainstorming is active:

    Discovery state may change.
    Delivery state must not change.

The system may capture ideas, ask questions, inspect permitted sources, conduct research, reconcile findings, and update its discovery document. It must not create implementation tasks, issues, delivery branches, commits, or pull requests. Existing delivery artifacts do not become writable merely because they already exist.

“Create a quick prototype to check the idea” also crosses this boundary. Discovery can establish that a prototype is needed and define the question it should answer. Building that prototype belongs to a separately authorized execution stage.

A Persistent Mode, Not a Conversational Mood

The mode must survive a new conversation, a context reset, and an agent restart.

That requires durable state rather than an instruction that exists only in the current transcript. A simple implementation uses a repository-root document named BRAINSTORM.md.

Its mode metadata might look like this:

## Mode
- Status: active
- Active session: BS-003
- Activated at: 2026-09-28T16:00:00Z
- Deactivated at: pending

There are two legitimate stored mode values: active and inactive. The loader also needs two operational outcomes: absent, when no discovery document exists, and malformed, when a document exists but cannot be safely interpreted.

These outcomes are not interchangeable.

An absent document means the optional discovery stage has not been established. Normal planning can follow its ordinary authorization rules. A malformed document means the system cannot establish whether discovery restrictions apply. It must not interpret that uncertainty as permission to proceed.

Absent:  
    Follow the normal workflow's authorization rules.

Active:  
    Permit discovery operations only.

Inactive:  
    Validate the retained document and its exit index
    before accepting a discovery-to-planning handoff.

Malformed:  
    Block state-changing operations until repaired.

This is an application of deny-by-default authorization. OWASP recommends both denying access by default and validating permissions on every request; checking mode only at session startup is insufficient when later operations can mutate state.[1]

Activation and deactivation must be explicit. A casual request to “brainstorm some names” is not necessarily a request to activate a persistent repository-wide restriction. Conversely, inactivity, a new conversation, or an apparently complete idea is not a request to deactivate one.

Repeated activation while already active should be idempotent: no new session, no reset, and no rewritten idea history. Reactivation after an explicit exit creates a new session identifier while retaining existing branches and ideas.

A session is an activation interval, not a chat window.

Figure 1. The outer loop is a persistent mode, not a chat session. Both researcher roles must be available before activation or resumed idea processing. New conversations reload the stored mode; readiness alone does not exit it.

The Team Has Exactly Three Participants

The research topology consists of one coordinator and two researchers.

The coordinator acts as the project manager. It owns clarification, branch placement, reconciliation, lifecycle decisions, and all writes to the canonical discovery document.

The first researcher investigates the problem side: audience, domain, comparable approaches, precedent, and whether the proposed idea addresses a recognizable need.

The second researcher investigates the feasibility side: technical constraints, dependencies, risks, prerequisites, and observable conditions for completion.

Figure 2. Both research returns feed a single reconciliation step. Researcher reports are evidence inputs, not write permissions or votes authorizing implementation. Only the coordinator publishes the validated synthesis.

The researchers are read-only. They return findings, not patches to shared state. Their intermediate reports remain temporary; the coordinator persists the reconciled result, including the evidence and uncertainty necessary to understand it later.

Both researcher slots must be available before activation or resumed idea processing. When the team cannot be established, processing blocks without changing the durable document. It does not silently degrade into a single researcher, sequential role impersonation, or unassisted coordinator research.

This is a workflow contract, not a claim that three participants are universally optimal. The purpose is to make the required perspectives predictable and to make a missing perspective visible.

The researcher roles persist throughout the active working session. After a restart, the host reconstitutes both roles from the durable state before processing another idea. Persistence does not mean an agent process somehow remains alive between disconnected conversations.

Independence Requires More Than Different Role Names

Both researchers should receive the same established understanding and relevant branch context, but different research questions.

For an initial pass, neither should receive the other's conclusions as instructions. Otherwise, the second pass risks becoming an elaboration of the first rather than a separate investigation.

However, procedural separation is not statistical independence. Two researchers may rely on the same upstream document, inherit the same mistaken premise, or interpret the same ambiguous requirement similarly.

The general probability relationship is:

P(both wrong) = P(first wrong) * P(second wrong | first wrong)  

Replacing the conditional term with an independent error rate requires an independence assumption. Merely spawning a second agent does not establish that assumption.

Consequently, agreement is not a substitute for evidence. The coordinator must examine source overlap, assumptions, and reasoning rather than counting matching conclusions.

The Unit of Work Is an Idea, Not a Task

Each materially distinct idea receives a stable identifier such as IDEA-017.

A clarification updates that idea. It does not silently create another element. A genuinely distinct proposal receives another identifier even when it shares an audience, component, or dependency with an existing idea.

For example:

IDEA-017: Let a document editor continue working offline.  
IDEA-018: Add real-time collaborative editing.  
IDEA-019: Display synchronization conflicts to users.  

These ideas are related, but they do not have identical completion boundaries. Offline editing might be useful without simultaneous collaboration. Conflict presentation may depend on the synchronization policy chosen elsewhere.

Stable identity allows those relationships to remain understandable even when titles change or ideas move between categories.

Identifiers must never be renumbered for presentation, reassigned to a replacement idea, or reused after an idea is parked. The identifier describes continuity of meaning, not position in a list.

Each element has a small metadata envelope:

Idea identifier  
Title  
Branch identifier  
Lifecycle status  
Created timestamp  
Updated timestamp  
Plan-readiness flag  
One-line summary  

The body then contains eight required sections:

User Idea  
Base Understanding  
Research Findings and Citations  
Dependencies  
Risks  
Open Questions  
Start Conditions  
Definition of Complete  

The original user idea and established understanding are deliberately separate. The first preserves what was requested. The second records the interpretation developed through clarification.

Without that separation, an agent can gradually rewrite the request until its own assumptions appear to have originated with the user.

Incomplete elements still contain the required sections, with missing work explicitly marked. An honest placeholder is preferable to plausible text inserted only to satisfy a schema.

The Inner Loop: Clarify, Research, Reconcile, Persist

The mode has an outer lifecycle loop and an inner idea-processing loop.

The outer loop remains active until an explicit exit request. The inner loop develops one idea to its next defensible state, which may be clarification, further research, readiness, or parking.

Conceptually:

Figure 3. The inner loop advances an idea to its next defensible state, not necessarily to readiness. A request for clarification, a bounded research gap, or a decision to park the idea can all be valid stopping points. Publication still requires validation and a current source revision.

Clarification Establishes a Researchable Question

The coordinator should not ask every conceivable requirements question before research begins. It should ask enough to prevent the researchers from investigating materially different interpretations of the idea.

For an offline editor, “offline support” could mean viewing cached content, editing one document, maintaining a local document library, or merging edits from multiple disconnected devices.

Those are different research problems.

Baseline understanding should establish the intended outcome, relevant users, meaningful constraints, and scope boundaries. Unknowns that research can resolve become research questions. Preferences and authority decisions that only the user can supply remain explicit questions for the user.

The output is not a full specification. It is a sufficiently bounded research packet.

Idea: IDEA-017

Intent:  
    Continue editing an existing document without connectivity.

Established scope:  
    Text documents only.
    Reconnection must not silently discard accepted local edits.

Unresolved decisions:  
    Whether simultaneous multi-device editing is required.
    Whether attachments belong to the first version.

Problem research:  
    Which interruption scenarios should this experience address?
    Which comparable interaction patterns are relevant?

Feasibility research:  
    What persistence and synchronization guarantees are required?
    Which conflict cases could invalidate the proposed scope?

Research Returns Evidence, Not Approval

A researcher should distinguish what a source directly establishes from what the researcher infers.

For example, documentation describing a persistence mechanism is evidence about that mechanism. It is not automatically evidence that users need offline editing, that the proposed user experience is appropriate, or that an entire synchronization architecture is correct.

This distinction is consistent with the W3C provenance model, which separates entities, activities, responsible agents, and derivation relationships. Knowing where a statement came from is different from knowing that the statement is true.[2]

For significant findings, the durable synthesis should retain the claim, supporting source, relevant scope or version, limitations, and its relationship to the idea. Current public claims require retrievable source URLs. A source that could not be inspected must not be represented as inspected evidence.

Useful labels include Evidence, Inference, Disagreement, and Uncertainty. They describe the status of a statement, not its rhetorical importance.

A design recommendation can be valuable while still being an inference. A disagreement can remain unresolved while still being accurately documented.

Reconciliation Is Not Concatenation

The coordinator must do more than append two reports.

It checks whether the researchers addressed the same scope, whether apparently independent sources share an origin, whether proposed dependencies are mandatory or optional, and whether conclusions contradict established constraints.

When the researchers disagree, the coordinator should preserve the disagreement and identify its cause. Perhaps they assumed different consistency requirements. Perhaps a capability is available only on one target platform. Perhaps the necessary evidence is missing.

The useful output is the decision boundary:

If simultaneous disconnected edits are in scope:  
    A merge or conflict-resolution policy is required.

If only one authoritative writer is permitted:  
    A simpler synchronization design may be sufficient.

Unresolved:  
    The user has not selected between these product constraints.

The coordinator can request focused follow-up research or further clarification. It must not manufacture consensus merely to make the element appear complete.

Persist the Reconciled State

Only the coordinator updates the canonical element.

The update preserves identity and original intent, records established understanding, incorporates sourced findings, exposes remaining disagreements, and sets a lifecycle status consistent with the evidence.

Validation follows each update. For a file-backed implementation, staging and validating a candidate before replacing the canonical document reduces the risk of exposing malformed intermediate content.

The loop then returns control. It does not automatically advance into a plan because the current idea happens to be ready.

Branches Organize Meaning, Not Execution

Ideas belong to stable branches such as BR-004. These are conceptual categories, not version-control branches.

An example hierarchy might be:

ROOT  
    BR-001: Product capabilities
        BR-004: Offline behavior
            IDEA-017: Offline document editing
            IDEA-019: Conflict presentation
        BR-005: Collaboration
            IDEA-018: Real-time collaborative editing

Each branch has a stable identifier, parent identifier, title, and summary. Each idea belongs to one canonical branch: the deepest existing branch that meaningfully fits its established scope.

The coordinator creates a new branch only when the existing hierarchy does not provide a suitable home. Initial placement supplies research context; research may justify a later move without changing the idea's identifier.

Structurally, this is a rooted hierarchy. Every non-root parent reference must resolve, and no chain of parent references may contain a cycle.

Dependency relationships are separate. IDEA-019 may depend on a synchronization decision in IDEA-018 without becoming its child in the category tree.

Conflating these relationships produces misleading implications: containment does not necessarily mean dependency, priority, or implementation order.

The visual mindmap is a projection of the canonical document. It should not become a second editable source of truth. A request for the full Markdown should return the full artifact, including incomplete and parked ideas, rather than a selectively shortened reconstruction.

Readiness Is a Contract, Not a Confidence Score

The element lifecycle uses five states:

Figure 4. Representative idea-state transitions. A plan-ready idea can lose that status when its scope or evidence changes. Parking preserves identity and prior findings. Only plan-ready carries a readiness flag of yes; none of these states authorizes planning by itself.

These are not a monotonic progress meter. New constraints may return a researched element to clarification. Contradictory evidence may invalidate previous readiness. A parked idea may later resume.

The explicit readiness flag must agree with lifecycle status:

status == plan-ready  -> plan readiness == yes  
status != plan-ready  -> plan readiness == no  

This redundancy is useful only when validated. Otherwise, it creates two contradictory answers to the same question.

Structural Validation

A deterministic validator can check identifier uniqueness, required fields, parent references, branch cycles, recognized statuses, timestamp syntax, required subsection presence, and consistency between status and readiness.

For a plan-ready element, it can also reject pending placeholders and require at least one HTTP or HTTPS citation in the research section.

These are structural checks. They do not establish that a citation supports a claim, that a source is authoritative, or that the supposedly measurable completion condition is actually meaningful.

A URL-shaped string is not a proof.

Semantic Readiness

The coordinator must separately evaluate whether the interpretation is coherent, material claims are supported, disagreements are visible, dependencies and risks are explicit, and start and finish boundaries are sufficiently concrete to support planning.

A useful conceptual predicate is:

PlanReady(idea) =  
    StructureValid(idea)
    AND UnderstandingEstablished(idea)
    AND RequiredResearchReconciled(idea)
    AND MaterialClaimsSupported(idea)
    AND UncertaintyExplicit(idea)
    AND StartBoundaryDefined(idea)
    AND CompletionBoundaryDefined(idea)
    AND NoUnboundedPlanningBlocker(idea)

Figure 5. Readiness combines deterministic checks with evidence-based reconciliation. Passing a schema or supplying a URL is not enough. Preconditions must be defined, but need not already be satisfied. A successful gate updates the idea; it does not start planning.

The last condition does not require zero uncertainty.

“Choose one of two documented storage approaches using a bounded evaluation” may be a legitimate planning decision. “We have not established whether the central capability is possible” may prevent meaningful planning altogether.

The question is whether the remaining uncertainty can be represented honestly inside a plan, rather than silently assumed away.

Defined Preconditions Are Not Satisfied Preconditions

Start conditions specify what must be true before implementation begins. Plan readiness requires those conditions to be understood; it does not necessarily require them to have been satisfied already.

Likewise, the definition of complete describes evidence the future deliverable must produce. It is not evidence that the deliverable already exists.

For the offline editor, hypothetical acceptance conditions might be:

After connectivity is removed:  
    The user can continue editing an already-open text document.

After a process restart:  
    Edits previously acknowledged as locally saved are recoverable.

After reconnection:  
    Local edits are synchronized or surfaced as an explicit conflict.
    Conflicting edits are not silently discarded.

Those conditions are more useful than “offline mode works well.” They describe observable behavior that planning can translate into implementation and verification work.

The distinction remains:

Plan-ready != implementation-ready  
Plan-ready != approved  
Plan-ready != complete  

Single-Writer Ownership and Runtime Safety

The write topology is intentionally narrow:

Researcher one write set: empty  
Researcher two write set: empty  
Coordinator write set: canonical discovery state  
Exit operation write set: final discovery state and derived index  

This avoids asking independent agents to merge competing edits to the same evolving interpretation.

However, a single coordinator inside one session does not prevent two application instances from opening the same repository. A production host still needs a locking or optimistic-concurrency strategy.

One approach is to bind an update to the revision originally read:

Read revision R.  
Perform clarification and research against R.  
Prepare a candidate update.  
Publish only if the current revision is still R.  
Otherwise reload and reconcile the changed context.  

The comparison and publication must be protected as one coordinated operation. An unprotected “check, then write” sequence still permits a competing writer between those steps. This is the same fundamental conflict-detection pattern illustrated by EF Core's concurrency-token checks.[3]

For an asynchronous host, I would also bind research responses to the session, idea, input revision, and request identifier. These are runtime hardening measures around the conversational protocol, not extra votes in the readiness decision.

A late report for an older interpretation must not overwrite a newer clarification. A report arriving after explicit exit must not reactivate the mode or mutate its final snapshot.

The host can retain applicable findings for deliberate reconsideration, but it must not blindly attach them to whichever idea currently occupies the conversation.

Policy Is Not a Sandbox

A role description saying “read-only” is a behavioral instruction. It is not an operating-system permission boundary.

Likewise, a creation command that checks mode protects that command. It does not automatically protect every shell command, API client, or editor available to the agent.

A stronger host enforces the same restrictions at tool dispatch, limits credentials and filesystem access, and treats retrieved content as data rather than executable instructions. OWASP's prompt-injection guidance specifically addresses indirect instructions arriving through external content and recommends tool restrictions and least-privilege access.[4]

Public research material must never be able to authorize exit, issue creation, or implementation. Those transitions come from the user through the trusted control path.

The durable artifact should also exclude credentials, personal data, and private-source extracts. Persistence is not a reason to copy every piece of material the researchers encountered.

Exit Produces a Snapshot Index, Not a Plan

The outer loop ends only after an explicit exit request.

Exit preserves every element, including incomplete and parked ideas. It marks the discovery mode inactive, closes the session interval, and generates BRAINSTORM_SUMMARY.md.

The summary is a branch-grouped index, not a replacement for the research document. Each element appears exactly once with its identifier, title, lifecycle status, readiness, concise summary, and reference to the full record.

It is important that this index be generated from the retained state rather than improvised as another narrative summary. Otherwise, less-developed ideas can disappear during compression.

The index is bound to the final source bytes:

sourceHash = SHA256(final BRAINSTORM.md bytes)

summary.SourceHash = sourceHash  

Cryptographic digests provide a mechanism for detecting changes relative to a recorded digest; that is the role described by NIST's Secure Hash Standard.[5]

For this design, the digest is a freshness and integrity check, not an approval token. It does not prove that the research is correct or that the index faithfully describes it. An actor able to rewrite both files can replace the digest as well.

Validation therefore needs more than a hash comparison:

Source is structurally valid and inactive.  
Recorded source hash matches the retained source bytes.  
Every source idea appears exactly once in the index.  
No unknown idea appears in the index.  

For stronger index verification, regenerate the expected index deterministically and compare its semantic fields or complete canonical bytes. That also detects altered titles, statuses, or summaries that leave the recorded source hash untouched.

Determinism requires stable ordering and stable metadata. The generation timestamp can use the recorded exit timestamp rather than the clock time of each regeneration.

Repeated exit with an already-valid index should be a no-op. When the source remains valid and inactive but its index is missing or stale, an explicit repair can regenerate the same index without rewriting the ideas.

Two Files Are Not Automatically One Transaction

Writing the final document and its index creates a multi-file consistency problem.

Staging both outputs, validating them, and keeping rollback copies helps with ordinary write failures. It does not make two separate file replacements indivisible across a process crash or power loss.

SQLite's atomic-commit documentation illustrates why durable all-or-nothing publication requires coordinated journaling and recovery rather than merely a sequence of successful writes.[6]

A file-backed host can fail closed whenever it finds an inactive source without a matching valid index. A more durable service can use a transactional store or immutable generations with a protected current-generation pointer.

The required observable behavior is the same: an interrupted exit must not expose a supposedly valid planning handoff assembled from mismatched generations.

After successful exit, the system waits.

Figure 6. Exit preserves every idea, including incomplete and parked elements. The index must match the final source hash and cover every idea exactly once. Planning then requires a separate explicit request, a selected plan-ready element, and valid checks against the same source revision. Execution remains separately authorized.

There is deliberately no automatic CreatePlan() call at the end.

Expressing the Handoff Gate in Code

The discovery-to-planning boundary should be explicit enough to test without invoking a model.

The following C# example represents the gate after parsing and validation. Its inputs must come from trusted host checks and authenticated user intent, not from a model asserting that its own work is valid.

using System;

public enum DiscoveryMode  
{
    Absent,
    Active,
    Inactive,
    Malformed
}

public sealed record HandoffChecks(  
    DiscoveryMode Mode,
    bool SourceValid,
    bool SummaryCurrentAndComplete,
    bool ExplicitPlanningRequest,
    string? SelectedIdeaId,
    bool SelectedIdeaExists,
    bool SelectedIdeaPlanReady);

public sealed record GateDecision(bool Allowed, string Reason);

public static class DiscoveryHandoff  
{
    public static GateDecision Evaluate(HandoffChecks checks)
    {
        ArgumentNullException.ThrowIfNull(checks);

        if (checks.Mode != DiscoveryMode.Inactive)
            return new(false, "Discovery has not been validly closed.");

        if (!checks.SourceValid)
            return new(false, "The retained discovery source is invalid.");

        if (!checks.SummaryCurrentAndComplete)
            return new(false, "The exit index is missing, stale, or invalid.");

        if (!checks.ExplicitPlanningRequest)
            return new(false, "Planning has not been explicitly requested.");

        if (string.IsNullOrWhiteSpace(checks.SelectedIdeaId)
            || !checks.SelectedIdeaExists)
            return new(false, "A retained idea must be explicitly selected.");

        if (!checks.SelectedIdeaPlanReady)
            return new(false, "The selected idea needs further discovery.");

        return new(true, "The selected idea may enter planning.");
    }
}

This gate applies specifically to a retained discovery-to-planning handoff. It does not require every ordinary assignment to create a brainstorm document first.

The checks must also describe the same source revision and selected identifier. Combining the source validity of one revision with the readiness of another would defeat the boundary.

Most importantly, the return value authorizes entry into planning only. Implementation, publication, and deployment still require their own authorization checks.

Testing the Protocol

The useful tests target invariants and failure paths, not whether an agent can produce an impressive-looking document.

For lifecycle behavior, test that casual ideation does not activate persistent mode, repeated activation does not rewrite state, a new conversation preserves an active restriction, and explicit exit retains incomplete ideas. Test that unavailable researcher capacity blocks new processing without mutating durable state.

For document integrity, test duplicate identifiers, missing parent references, branch cycles, missing sections, pending content in plan-ready elements, readiness mismatches, missing citations, and unexpected symbolic links at state-file paths.

For handoff integrity, test source-hash mismatches, missing or duplicate index entries, stale summaries after source edits, deterministic regeneration, and interruption between publishing the source and its index.

For runtime enforcement, test forbidden tool calls directly. A friendly conversation that happens not to create an issue is not proof that issue creation is blocked. Also test late research responses, concurrent coordinators, and external content attempting to change mode.

A valid negative result is often the most important result in this system:

The idea remains captured.  
The uncertainty remains visible.  
The implementation has not started.  
The durable state has not been damaged.  

The Output Is Preserved Understanding

The purpose of this loop is not to maximize the number of ideas, the number of researchers, or the volume of generated text.

It is to produce a durable element whose meaning can survive beyond the conversation that created it.

That element should preserve what the user asked for, what the team understood, what the evidence supports, what remains disputed, which prerequisites matter, and how a future result could be judged complete.

The architecture follows from that goal: persistent mode state prevents accidental transitions; two research perspectives expose different classes of uncertainty; single-writer reconciliation preserves one coherent record; stable identifiers preserve continuity; validation rejects malformed claims of readiness; and a hash-bound exit index provides an inspectable handoff without pretending to be approval.

A plan can then begin from an explicit body of understanding rather than an accumulated set of conversational assumptions.

Brainstorming is complete enough when an idea can be handed to planning without hiding what is known, what is assumed, and what still needs to be decided. It is not complete merely because the system has found something it could start building.

⚠️ This article is for educational, mathematical, and engineering purposes only. It does not constitute financial advice, an investment recommendation, or a trading signal. Cryptocurrency markets are volatile, leveraged markets can fail abruptly, and any implementation must be independently validated before it is used with real capital.

In the Ocean Model, we treated visible price movement as the surface of a much deeper system.

Tides represented observable trend. Underflows represented liquidity, order flow, and liquidation pressure. Storms represented sentiment events capable of transferring sudden energy into the entire market.

But there is another question hiding beneath those layers:

When two connected markets disagree, how much of that disagreement can their available liquidity absorb, how quickly can they absorb it, and which market is likely to move the most?

A counterflow heat exchanger gives us an interesting mathematical language for answering that question.

In a physical exchanger, two fluids travel in opposite directions while transferring heat through a shared boundary. The amount of heat transferred depends on their temperature difference, their heat-capacity rates, the conductance between them, the time available for exchange, and any fouling that obstructs the transfer.

In a crypto market, spot and perpetual futures can also behave like two connected streams.

When a perpetual future trades above its fair relationship to spot, arbitrage pressure may buy spot and short the perpetual. Those actions apply opposing price pressure to the two markets. When the perpetual trades below spot, the flow can reverse.

Markets do not literally obey thermodynamics. They are open, stochastic, reflexive systems filled with new orders, canceled orders, liquidations, funding payments, latency, changing leverage, and human behavior. The purpose of this model is not to claim otherwise.

The useful part is the structure:

• A difference creates pressure.
• Liquidity determines how much pressure each market can absorb.
• Coupling determines how quickly the pressure transfers.
• Friction weakens the transfer.
• A weak stream moves more than a strong stream.
• Under stress, convergence can fail and become amplification.

That gives us the Counterflow Market Model.

The Counterflow Market Model

Heat exchanger concept	Market interpretation	Symbol
Hot stream	The market currently priced above fair relationship	—
Cold stream	The market currently priced below fair relationship	—
Temperature difference	Fair-adjusted spot/perpetual basis
Heat-capacity rate	Candle-derived liquidity or price-impact capacity
Heat-transfer conductance	Cross-market convergence strength
Number of Transfer Units	Coupling relative to the weaker market
Effectiveness	Fraction of maximum transferable pressure
Heat transferred	Model-equivalent transferred notional
Fouling	Fees, latency, borrow limits, margin stress, and venue risk
Outlet states	Forecast spot and perpetual prices after partial convergence

The strongest initial application is a synchronized pair of candles for the same asset:

• One candle from the spot market.
• One candle from the perpetual-futures market.
• The same quote currency or a carefully normalized equivalent.
• The same opening time, closing time, and candle interval.

The model can later be adapted to two exchanges, two related instruments, or the bid and ask sides of a limit order book. Spot versus perpetual futures is simply the cleanest place to begin because the two markets have an explicit economic reason to remain connected.

Now, let’s break this down into its parts, and code!

Standard Candle Inputs

The candle-only implementation uses conventional OHLCV data:

public readonly record struct Candle(  
    DateTimeOffset OpenTime,
    DateTimeOffset CloseTime,
    double Open,
    double High,
    double Low,
    double Close,
    double Volume)
{
    public TimeSpan Duration => CloseTime - OpenTime;
    public double TypicalPrice => (High + Low + Close) / 3.0;
}

The spot and perpetual candles must be synchronized. The model also assumes that volume has been normalized into comparable base-asset units.

That last requirement matters!

Spot volume may already be expressed in BTC, ETH, or another base asset. Perpetual volume may instead be reported as contracts, quote currency, or inverse-contract notional. The model cannot compare those values until the exchange-specific contract definition has been normalized.

A linear contract can often be handled with a contract multiplier:

double baseVolume = candle.Volume * contractMultiplier;  
double quoteNotional = baseVolume * candle.TypicalPrice;  

Inverse and quanto contracts require instrument-specific conversion before entering this model.

The Pressure Difference

Let the logarithmic spot and perpetual states be:

The observed logarithmic basis is:

A raw basis is not automatically a dislocation. Funding, interest-rate differences, borrow costs, collateral demand, and persistent venue structure can support a nonzero relationship between the two prices.

We therefore define a fair basis:

and measure the residual pressure:

When , the perpetual is expensive relative to the estimated fair relationship. When , the perpetual is cheap relative to that relationship.

With only standard candles, we do not have enough information to calculate a full funding-and-carry model. The candle-only implementation therefore uses a slow, causal exponential moving average of the basis:

The current basis is compared against the previous EMA value before the current observation updates it. That prevents the present candle from partially explaining itself.

public sealed class FairBasisEstimator  
{
    private readonly Ema _ema;

    public FairBasisEstimator(int period)
    {
        _ema = new Ema(period);
    }

    public (double Basis, double FairBasis, double Residual) Update(
        double spotClose,
        double perpetualClose)
    {
        double basis = Math.Log(perpetualClose / spotClose);

        if (!_ema.HasValue)
        {
            _ema.Update(basis);
            return (basis, basis, 0.0);
        }

        double fairBasis = _ema.Value;
        double residual = basis - fairBasis;

        _ema.Update(basis);
        return (basis, fairBasis, residual);
    }
}

If funding, interest, and borrow data become available, the external fair-basis estimate should replace the EMA proxy rather than being added on top of it.

For display, a logarithmic ratio can be converted to basis points with:

public static double ToBasisPoints(double logRatio) =>  
    10_000.0 * (Math.Exp(logRatio) - 1.0);

Candle-Derived Liquidity Capacity

A physical heat-capacity rate describes how much energy is required to change a stream’s temperature.

The market equivalent should describe how much notional activity is associated with a unit of price movement.

At order-book resolution, this should be estimated from depth, spread, replenishment, cancellation, and realized price impact. Standard candles do not contain those fields, so we need an observable proxy.

First, calculate effective logarithmic movement:

This combines close-to-close movement with the candle’s intraperiod range.

Next, calculate approximate quote notional:

where converts reported volume into comparable base units.

The candle-derived capacity is then:

A market processing large notional with little movement receives a high capacity. A market moving sharply on modest notional receives a low capacity.

public sealed class CandleCapacityEstimator  
{
    private readonly Ema _notional;
    private readonly Ema _movement;
    private readonly double _minimumMovement;
    private double? _previousClose;

    public CandleCapacityEstimator(int period, double minimumMovement = 1e-6)
    {
        _notional = new Ema(period);
        _movement = new Ema(period);
        _minimumMovement = minimumMovement;
    }

    public double Update(Candle candle, double volumeMultiplier = 1.0)
    {
        double logRange = Math.Log(candle.High / candle.Low);

        double closeMove = _previousClose.HasValue
            ? Math.Abs(Math.Log(candle.Close / _previousClose.Value))
            : logRange;

        double effectiveMovement = Math.Max(
            _minimumMovement,
            Math.Max(logRange, closeMove));

        double quoteNotional = candle.Volume
                             * volumeMultiplier
                             * candle.TypicalPrice;

        double smoothedNotional = _notional.Update(quoteNotional);
        double smoothedMovement = _movement.Update(effectiveMovement);

        _previousClose = candle.Close;

        return smoothedNotional /
               Math.Max(smoothedMovement, _minimumMovement);
    }
}

This is a liquidity proxy, not literal order-book depth. It is still useful because it preserves the important relationship:

More notional with less movement implies greater resistance to transferred pressure.

It also gives the model a capacity with useful units:

Coupled Spot and Perpetual Dynamics

The exchanger analogy becomes clearer when the two markets are written as coupled differential equations:

where:

• is perpetual capacity.
• is spot capacity.
• is cross-market conductance.
• is external perpetual order pressure.
• is external spot order pressure.

When , the coupling term pushes the perpetual downward and spot upward. When , the signs reverse.

The residual basis evolves approximately as:

If external pressure and movement in fair basis are temporarily ignored, the residual has an exponential convergence form:

with:

The solution over horizon is:

and the theoretical half-life is:

The half-life tells us how long the current coupling regime would take to remove half of a dislocation if its estimated behavior remained stable.

Estimating Convergence from Candles

The candle stream can estimate basis persistence with a rolling autoregressive relationship:

Using a no-intercept rolling least-squares estimate:

For monotonic convergence:

and the continuous decay rate is:

public sealed class RollingBasisPersistence  
{
    private readonly Queue<(double Cross, double Square)> _samples = new();
    private readonly int _window;
    private double _sumCross;
    private double _sumSquares;

    public RollingBasisPersistence(int window)
    {
        _window = window;
    }

    public void Add(double previousResidual, double currentResidual)
    {
        var sample = (
            Cross: previousResidual * currentResidual,
            Square: previousResidual * previousResidual);

        _samples.Enqueue(sample);
        _sumCross += sample.Cross;
        _sumSquares += sample.Square;

        while (_samples.Count > _window)
        {
            var removed = _samples.Dequeue();
            _sumCross -= removed.Cross;
            _sumSquares -= removed.Square;
        }
    }

    public (double Phi, double Gamma, TimeSpan? HalfLife) Estimate(
        TimeSpan candleDuration)
    {
        if (_sumSquares <= 1e-24)
            return (double.NaN, 0.0, null);

        double phi = _sumCross / _sumSquares;

        if (phi < 0.0 || phi >= 1.0)
            return (phi, 0.0, null);

        double safePhi = Math.Max(phi, 1e-12);
        double gamma = -Math.Log(safePhi) /
                       candleDuration.TotalSeconds;

        double halfLifeSeconds = Math.Log(2.0) / gamma;

        return (
            phi,
            gamma,
            TimeSpan.FromSeconds(halfLifeSeconds));
    }
}

The value of also identifies the current regime:

Persistence estimate	Interpretation
	Monotonic convergence
	Oscillating convergence or repeated basis crossing
	Little decay or persistent oscillation
	Divergence or amplification

Only the first regime behaves like a passive heat exchanger.

A negative means the basis is crossing its estimated equilibrium while shrinking. A value with magnitude greater than one means the residual is growing. Liquidation cascades, collateral stress, exchange failures, or one-sided directional demand can all produce a market that amplifies pressure instead of absorbing it.

The model should report those regimes rather than forcing every observation into a convergence forecast.

Market Conductance

Once , , and are known, conductance follows directly:

double inverseCapacitySum = (1.0 / perpetualCapacity)  
                          + (1.0 / spotCapacity);

double conductance = gamma > 0.0  
    ? gamma / inverseCapacitySum
    : 0.0;

A high means the markets are strongly coupled relative to the price impact implied by their candles. A low means that basis pressure is transferring slowly.

Market Fouling

Physical fouling adds resistance to a heat exchanger. Market fouling can represent:

• Trading fees and spread.
• Execution latency.
• Borrow scarcity.
• Funding uncertainty.
• Margin requirements.
• Capital fragmentation across venues.
• Withdrawal restrictions.
• Exchange or stablecoin risk.

A convenient scenario penalty is:

double effectiveConductance = historicalConductance  
                            * Math.Exp(-scenarioFouling);

There is an important modeling detail here: a convergence rate estimated from historical candles already contains the friction that was present during those candles.

Therefore, should be the default when describing the observed market. A positive fouling value should be used only for additional scenario analysis or when the conductance estimate comes from a frictionless baseline. Applying historical friction twice would artificially suppress convergence.

Market NTU

The physical Number of Transfer Units is:

For the market model, becomes conductance accumulated over a forecast horizon :

where:

and the capacity ratio is:

A high means that coupling is strong relative to the weaker market’s ability to absorb pressure during the selected horizon. A low means that the two markets may remain disconnected long enough for the dislocation to persist.

double cMin = Math.Min(spotCapacity, perpetualCapacity);  
double cMax = Math.Max(spotCapacity, perpetualCapacity);  
double capacityRatio = cMin / cMax;

double horizonSeconds = candleDuration.TotalSeconds  
                      * forecastHorizonCandles;

double marketNtu = effectiveConductance  
                 * horizonSeconds
                 / cMin;

Counterflow Effectiveness

For a counterflow exchanger, effectiveness is:

When the two capacities are balanced and :

public static double CounterflowEffectiveness(  
    double ntu,
    double capacityRatio)
{
    if (!double.IsFinite(ntu) || ntu <= 0.0)
        return 0.0;

    double cr = Math.Clamp(capacityRatio, 0.0, 1.0);

    if (Math.Abs(1.0 - cr) < 1e-9)
        return Math.Clamp(ntu / (1.0 + ntu), 0.0, 1.0);

    double exponential = Math.Exp(-ntu * (1.0 - cr));
    double denominator = 1.0 - cr * exponential;

    return Math.Clamp(
        (1.0 - exponential) / denominator,
        0.0,
        1.0);
}

Effectiveness is not the probability that a trade succeeds.

It is also not automatically the percentage of basis expected to disappear. It describes transferred pressure relative to the maximum transfer allowed by the weaker-capacity stream.

Transferable Market Pressure

The maximum exchanger-style transfer is:

and the effectiveness-adjusted transfer is:

The resulting fractional reduction in the market gap would be:

Since:

we can also write:

A physical counterflow exchanger can produce outlet states that cross when the exchange is sufficiently effective. Markets can overshoot too, but predicting that crossing from candles alone would be aggressive.

The implementation therefore uses a conservative, bounded closure model.

The empirically observed exponential closure is:

The final forecast closure is the stricter of empirical decay and structural exchanger capacity:

double dynamicClosure = gamma > 0.0  
    ? 1.0 - Math.Exp(-gamma * horizonSeconds)
    : 0.0;

double exchangerClosure = Math.Clamp(  
    effectiveness
    * cMin
    * inverseCapacitySum,
    0.0,
    1.0);

double forecastClosure = Math.Clamp(  
    Math.Min(dynamicClosure, exchangerClosure),
    0.0,
    1.0);

This is deliberately conservative.

The exchanger equations are not allowed to claim more convergence than the recent basis-decay history supports, and the historical decay model is not allowed to claim more pressure transfer than the current capacity relationship supports.

Forecasting the Two Outlet Prices

The bounded model-equivalent transfer notional is:

The forecast logarithmic states are:

Converting back to prices:

double transferNotional = forecastClosure  
                        * residualBasis
                        / inverseCapacitySum;

double spotLogOut = Math.Log(spot.Close)  
                  + transferNotional / spotCapacity;

double perpetualLogOut = Math.Log(perpetual.Close)  
                       - transferNotional / perpetualCapacity;

double predictedSpot = Math.Exp(spotLogOut);  
double predictedPerpetual = Math.Exp(perpetualLogOut);  

The weaker market moves more because the same transferred pressure produces a larger logarithmic price change when divided by a smaller capacity.

If perpetual capacity is much smaller than spot capacity, most of a positive residual basis is expected to close through the perpetual moving downward. If spot capacity is much smaller, more of the adjustment is assigned to spot moving upward.

The value is a model-equivalent notional. It should not be interpreted as proof that an identical quantity of trades will execute during the horizon.

The Complete Candle Loop

The complete implementation maintains:

• A causal fair-basis estimator.
• Separate spot and perpetual capacity estimators.
• A rolling basis-persistence regression.
• A rolling residual z-score.
• Regime classification.
• Conductance, NTU, effectiveness, closure, transfer, and outlet forecasts.

A typical configuration for 15-minute candles might begin with:

var model = new CounterflowMarketModel(  
    new CounterflowParameters
    {
        FairBasisPeriod = 96,          // About one day
        CapacityPeriod = 32,           // About eight hours
        ConvergenceWindow = 128,       // About thirty-two hours
        MinimumConvergenceSamples = 32,
        ResidualZScoreWindow = 128,
        ForecastHorizonCandles = 4,    // One-hour horizon
        SpotVolumeMultiplier = 1.0,
        PerpetualVolumeMultiplier = 1.0
    });

The model is updated once for each synchronized candle pair:

foreach ((Candle spot, Candle perpetual) in alignedCandles)  
{
    CounterflowSnapshot state = model.Update(
        spot,
        perpetual,
        externalFairLogBasis: null,
        scenarioFouling: 0.0);

    if (!state.IsReady)
        continue;

    Console.WriteLine(
        $"{state.Time:u} " +
        $"Regime={state.Regime} " +
        $"Residual={state.ResidualBasisBps:F2}bps " +
        $"Z={state.ResidualZScore:F2} " +
        $"Phi={state.Phi:F4} " +
        $"HalfLife={state.HalfLife} " +
        $"NTU={state.MarketNtu:F4} " +
        $"Effectiveness={state.Effectiveness:P2} " +
        $"Closure={state.ForecastClosureFraction:P2} " +
        $"SpotOut={state.PredictedSpotClose:F2} " +
        $"PerpOut={state.PredictedPerpetualClose:F2}");
}

The full dependency-free .NET implementation accompanying this article includes validation and all helper classes in one source file.

Reading the Output

A positive residual does not mean that spot must rise, nor does it mean that the perpetual must fall.

It means that the pair is above its estimated fair basis. Capacity determines how the modeled adjustment is divided between the two markets. New directional pressure can still move both prices upward or downward while the basis closes between them.

That is an important distinction:

The Counterflow Market Model forecasts relative convergence, not the absolute direction of the entire crypto market.

Where the Model Breaks

A physical exchanger is passive. A market is not.

New information can enter at any moment. Traders can withdraw liquidity. Liquidations can force execution. Funding can change. Exchanges can become unavailable. A price gap can attract arbitrage capital, but that same gap can also signal genuine credit, collateral, or venue risk.

Standard candles create additional limitations:

• They do not reveal the bid–ask spread.
• They do not reveal order-book depth.
• They do not distinguish market orders from limit orders.
• They do not expose cancellation or replenishment rates.
• They do not contain funding, open interest, liquidations, borrow rates, or latency.
• Reported volume may be distorted or incomparable across venues.
• A candle close hides the path taken inside the interval.

The candle-derived capacities are therefore empirical proxies. They should be replaced with direct impact curves when full market microstructure data is available.

A production study should also use:

• Walk-forward rather than full-history calibration.
• Strictly causal feature construction.
• Exchange-specific volume normalization.
• Robust outlier handling.
• Fee, spread, slippage, and funding simulation.
• Separate validation across calm, trending, and liquidation regimes.
• Mark-price, index-price, and traded-price comparisons.
• Venue-failure and stale-data detection.

The most dangerous regime is amplification.

When , the residual magnitude is growing instead of decaying. For , the first-order differential equivalent has negative damping:

A value represents a growing sign-alternating process and cannot be represented by the simple monotonic exchanger equation at all. In either case, the heat-exchanger analogy is no longer the right local model. The system is behaving more like a feedback amplifier or runaway reaction. The implementation correctly reports divergence and suppresses the passive-convergence forecast.

Adding Counterflow to the Ocean Model

The Counterflow Market Model fits naturally beneath the Ocean Model as a microstructure absorption layer.

The Ocean Model asks:

• What direction is market energy moving?
• How are surface trend, underflow pressure, liquidation heat, and sentiment coupled?

The Counterflow Model asks:

• How much relative pressure can connected liquidity absorb?
• How quickly should a dislocation decay?
• Which market is structurally weaker?
• Is the pair converging, oscillating, or amplifying?

The combined interpretation becomes:

The Ocean Model can provide directional force. Counterflow can provide resistance, transfer capacity, and timing.

For example, a strong bullish surface and underflow state may still produce very different outcomes:

• High spot capacity and low perpetual capacity can push most relative adjustment into the perpetual.
• Low capacity on both streams can turn modest order pressure into large price movement.
• High NTU with a short half-life suggests that temporary basis dislocations should be absorbed quickly.
• Low NTU suggests that the markets are weakly coupled and the basis may persist.
• A divergent persistence estimate warns that liquidations or structural stress may be overwhelming ordinary arbitrage.

This gives the broader model something it did not previously have: a mathematically explicit estimate of how much incoming pressure the connected market structure can absorb before that pressure becomes visible movement.

The Exchanging Market

A counterflow heat exchanger does not predict where heat originated. It predicts how two streams exchange energy once a difference exists.

The Counterflow Market Model should be understood the same way.

It does not primarily answer:

Will Bitcoin go up?

It answers a narrower and more mechanically useful set of questions:

How large is the current spot–perpetual dislocation after fair basis is removed?

How much resistance does each market appear to have?

How strongly are the two markets coupled?

How much of the dislocation can plausibly transfer during the selected horizon?

Which market is likely to perform most of the relative adjustment?

Is the system absorbing pressure—or amplifying it?

That makes the model testable.

Each state can be calculated from synchronized candles. Each parameter can be measured walk-forward. Each forecast can be compared with the observed future basis and the realized contribution of spot and perpetual price movement.

The analogy provides the architecture.

The market data must determine whether the architecture is useful!

Engineering References

1. Damien Ackerer, Julien Hugonnier, and Urban Jermann, Perpetual Futures Pricing, arXiv:2310.11771.
2. Songrun He, Asaf Manela, Omri Ross, and Victor von Wachter, Fundamentals of Perpetual Futures, arXiv:2212.06888.
3. Rama Cont, Arseniy Kukanov, and Sasha Stoikov, The Price Impact of Order Book Events, arXiv:1011.6402.
4. NPTEL, Heat Exchangers, Module 7, Effectiveness–NTU Method.

One session would write tests. Another would skip them. One agent would update architecture notes. Another would leave the knowledge buried in chat history. One session would wait before opening a PR. Another would push ahead without the same level of verification.

That inconsistency is what led me to build OpenCaw.

OpenCaw is an open source framework library for AI-assisted development. I designed it to standardize agent instructions, roles, skills, reusable commands, architecture guidance, task tracking, verification, and project memory across tools such as Cursor, Codex, and Claude.

In simpler terms: OpenCaw gives your AI coding agents a consistent way to work. You can use it by speaking naturally about what you want, or you can call specific roles, skills, and commands when you want precision. The explicit names are there for control and repeatability, not because every user should have to memorize them.

What Is OpenCaw?

OpenCaw is not a traditional application framework. It does not dictate whether your app should use .NET, Node, Python, React, Angular, Terraform, Kubernetes, or any other stack.

Instead, OpenCaw is a shared AI development baseline that you mount inside an existing repository.

I built it around a simple idea: the reusable AI operating model should live in one place, while project-specific knowledge should stay inside the project.

OpenCaw gives agents a structured operating model that includes:

• Role definitions
• Skill instructions
• Reusable shell commands
• Architecture templates
• Task tracking conventions
• PR readiness rules
• Verification workflows
• Project-local memory files

The mounted OpenCaw folder acts as the shared configuration layer. The host repository keeps its own memory, rules, debug notes, tasks, goals, and project-specific context under .ai/.

That separation matters. I want teams to be able to improve their shared AI workflow without polluting the baseline with one repository's local quirks.

Why I Built It

I created OpenCaw because I wanted AI-assisted development to feel less like improvisation and more like engineering.

Prompting alone is not enough for long-lived repositories. A good prompt can get a useful answer once, but it does not automatically give you repeatable behavior across future sessions, other tools, or other team members.

Without a shared baseline, AI sessions tend to drift:

• One agent writes tests; another skips them.
• One agent updates architecture notes; another ignores them.
• One agent opens PRs too early; another waits for confirmation.
• One agent stores useful lessons in the wrong place.
• One agent understands the stack; another has to rediscover it.
• One agent verifies the work; another simply says it is done.

OpenCaw is my answer to that drift.

The goal is not to create one magic prompt. The goal is to create a durable operating manual for AI-assisted software work: how agents should plan, implement, verify, document, and hand off changes.

How OpenCaw Is Structured

I designed OpenCaw to be installed into a repository as a tool directory such as .codex, .cursor, or .claude.

A typical install looks like this:

your-repository/  
├── .codex/
│   ├── AGENTS.md
│   ├── .architecture/
│   ├── .roles/
│   ├── commands/
│   └── skills/
├── .ai/
│   ├── MEMORY.md
│   ├── RULES.md
│   ├── DEBUG.md
│   └── tasks/
├── AGENTS.md
└── ARCHITECTURE.md

The important separation is:

OpenCaw includes architecture templates under .architecture/, role definitions under .roles/, reusable task instructions under skills/, and shell automation under commands/.

The repository includes templates and conventions for many common engineering areas, including .NET, Node, Python, Playwright, React, Angular, Vue, Terraform, Kubernetes, Helm, GitHub Actions, Azure DevOps, Docker, databases, and more.

How to Install OpenCaw

Before installing OpenCaw into a project, I recommend forking the repository.

You can install directly from the public repository, but using your own fork gives your team control over updates, local customizations, release pinning, and upstream merges.

In the examples below, replace <your-org> with your GitHub user or organization.

Option 1: Install as a Git Submodule

This is the approach I recommend for most teams.

Use .codex if you want OpenCaw available to Codex-style agents:

git submodule add https://github.com/<your-org>/OpenCaw .codex  
git submodule update --init --recursive  

Use .cursor if you want OpenCaw available to Cursor:

git submodule add https://github.com/<your-org>/OpenCaw .cursor  
git submodule update --init --recursive  

Use .claude if you want OpenCaw available to Claude:

git submodule add https://github.com/<your-org>/OpenCaw .claude  
git submodule update --init --recursive  

A submodule is useful because your host repository can pin a known-good OpenCaw revision while still allowing controlled updates later.

Option 2: Install as a Clone

Use a plain clone when the repository needs a heavily customized copy of OpenCaw:

git clone https://github.com/<your-org>/OpenCaw .codex  

Or:

git clone https://github.com/<your-org>/OpenCaw .cursor  

Or:

git clone https://github.com/<your-org>/OpenCaw .claude  

This is easier to modify directly, but it also makes upstream updates less structured than a submodule.

How I Recommend Using OpenCaw

Once installed, OpenCaw should load through the repository's AGENTS.md bootstrap.

If your agent session does not appear to pick it up, explicitly ask it to read the instructions:

Read AGENTS.md instructions  

From there, the most important thing to know is this: you do not have to memorize every role, skill, command, task convention, or goal-flow phrase.

I include exact role names, skill names, and command paths because they are useful. They make workflows auditable, scriptable, repeatable, and easier to debug. But OpenCaw is also designed to work from normal human intent.

You can say what you want in plain English:

Review this project for security issues, create tasks for anything serious, and run whatever validation makes sense before summarizing the results.  

OpenCaw gives the agent enough structure to translate that into the right operating mode: likely a security role, task creation, issue management if relevant, validation commands, and an evidence-based final summary.

That means there are two equally valid ways to use OpenCaw:

My recommendation is to start with plain language. Add explicit roles, skills, or command paths only when you need more control.

1. Start With Intent

The most natural way to use OpenCaw is to describe the outcome you want.

For example:

Help me implement this feature safely. Plan the work, update the code, add tests, run the right checks, and tell me what changed.  

That is enough for an OpenCaw-aware agent to choose the right workflow. It can infer that this is implementation work, that task planning may be useful, that test and validation behavior matters, and that the final answer should include evidence.

This is the mode I want most people to use day to day. OpenCaw should make the agent easier to direct, not harder.

2. Use Roles When You Want a Specific Perspective

Roles tell the agent which perspective to use.

OpenCaw includes roles such as:

• backend-architect
• frontend-developer
• fullstack-engineer
• qa-engineer
• project-manager
• security-engineer
• sre
• devops-automator
• data-engineer
• technical-writer

The role index also supports aliases such as security, qa, frontend, backend, devops, sre, and pm.

You can be explicit:

use role security-engineer and review this repository for authentication, authorization, and dependency risks  

Or you can say the same thing naturally:

Review this repository like a security engineer. Focus on authentication, authorization, and dependency risks.  

Both are valid. The explicit version is useful when you want deterministic behavior. The natural-language version is easier to remember.

3. Compose Perspectives Without Memorizing Role Names

OpenCaw supports multi-role sessions. The first role acts as the primary perspective. Additional roles add specialist constraints or review lenses.

Explicit version:

use role backend-architect + security-engineer and review the payment API design before implementation  

Plain-language version:

Review the payment API design from both an architecture and security perspective before we implement it.  

I use this pattern often when I want implementation work to carry a second concern, such as quality, security, reliability, or documentation.

You do not have to know the exact role names. Describe the perspectives you want, and OpenCaw gives the agent a structure for mapping those perspectives into its role system.

4. Let Skills Stay Behind the Curtain

Skills are reusable instructions for common types of work.

I separate skills from commands on purpose:

• Skills define the reasoning workflow.
• Commands define repeatable execution.

You can call skills explicitly:

use skill create-task-file + manage-task-issues + test-dotnet  

But you can also just describe the work:

Turn this GitHub issue into a tracked task, implement the fix, link the task back to the issue, and run the relevant .NET tests.  

That plain-language prompt gives the agent enough signal to use the task-file, issue-management, and .NET testing workflows without requiring you to remember the internal skill names.

Useful skills include:

Skills make agent behavior less dependent on one-off prompt wording. The skill names are helpful labels, but they are not the only way to trigger the behavior.

5. Use Commands for Repeatable Execution

Commands are shell scripts inside the OpenCaw baseline.

Examples:

./.codex/commands/validate-opencaw.sh
./.codex/commands/generate-architecture.sh DOTNET NODE GITHUB_ACTIONS
./.codex/commands/dotnet-build.sh
./.codex/commands/dotnet-test.sh

I like showing the full command paths because they make it clear what is actually available in the repository. They are useful when you are running something manually, writing documentation, debugging a workflow, or wiring OpenCaw into automation.

But you do not need to remember those paths during normal agent usage.

Instead of saying this:

Run ./.codex/commands/dotnet-build.sh and ./.codex/commands/dotnet-test.sh  

You can say this:

Build the .NET project and run the relevant tests before summarizing the result.  

Instead of saying this:

Run ./.codex/commands/generate-architecture.sh DOTNET REACT GITHUB_ACTIONS  

You can say this:

Create an architecture document for this .NET and React project that uses GitHub Actions.  

OpenCaw includes commands for validation, architecture generation, .NET restore/build/test, Playwright evidence reporting, task files, issue linking, PR readiness, goal files, sub-agent planning, security scans, and database tooling.

The point is not to make users memorize shell scripts. The point is to give the agent reliable tools it can choose when you describe the outcome you want.

6. Let OpenCaw Create Durable Task Artifacts

For substantial work, OpenCaw uses .ai/tasks/ in the host repository.

A typical task structure looks like this:

.ai/tasks/
├── TODO.md
├── OPEN_ISSUES.md
└── checkout-refactor/
    ├── TASK.md
    └── SUBAGENTS.md

I use this structure because chat history is not enough for serious engineering work.

The task directory gives the repository a durable trail:

• What the task is
• What issue it maps to
• What needs to be done
• Which sub-agent lanes were planned
• What remains open
• What validation happened

You can request this explicitly:

use skill create-task-file and create a task under .ai/tasks for this refactor  

Or you can say it naturally:

This refactor is large enough that I want a durable task plan before implementation.  

Both should lead the agent toward task planning. The task system exists so work can be paused, resumed, reviewed, and handed off without relying only on chat history.

7. Use Architecture Templates Early

If your repository does not have an ARCHITECTURE.md, OpenCaw can generate one from selected templates.

Manual command version:

./.codex/commands/generate-architecture.sh DOTNET REACT GITHUB_ACTIONS

Explicit agent version:

use role software-architect and generate ARCHITECTURE.md for this repository using DOTNET, REACT, POSTGRESDB, and GITHUB_ACTIONS templates  

Plain-language version:

Create an architecture document for this repo. It is a .NET backend with a React frontend, Postgres storage, and GitHub Actions for CI.  

By default, I keep the generated architecture file concise by referencing selected templates instead of inlining all template content. The architecture generation script also supports an --inline option when full embedded template content is explicitly needed.

My recommendation is to create or update architecture documentation early. It gives the agent a contract to preserve instead of forcing every session to rediscover the system from scratch.

8. Use Sub-Agent Planning Only When Work Can Be Split Safely

OpenCaw includes project-manager and sub-agent orchestration support.

Sub-agent planning is useful when different lanes can work independently, such as:

• One lane investigates current behavior.
• One lane updates backend code.
• One lane updates frontend code.
• One lane writes tests.
• One lane reviews security or performance.

Explicit version:

use 4 agents with project-manager + fullstack-engineer + qa-engineer to split the checkout refactor into safe parallel lanes, keep write sets separate, then integrate and verify  

Plain-language version:

This checkout refactor may be too large for one linear pass. Split it into safe parallel work lanes if that makes sense, keep overlapping file changes to a minimum, then integrate and verify everything together.  

I do not recommend forcing parallel work just because multiple agents are available.

Good sub-agent planning should keep write sets narrow, avoid overlapping changes, and prefer fewer high-quality lanes over unnecessary fragmentation.

9. Use Goal Flow for Multi-Task Delivery, Not Auto-Merge

Goal flow is for explicit, multi-task automation.

It can move from task to task, raise PRs after validation, run post-PR QA, and produce a final approval report.

It does not mean automatic merge approval, and it does not skip QA.

Explicit version:

goal: modernize the reporting module across these five tasks. Automatically raise each task PR after validation, run post-PR QA, then continue to the next task. Do not merge PRs automatically.  

Plain-language version:

I want to work through these five reporting-module tasks as one coordinated goal. For each task, validate the work, open a PR when it is ready, run post-PR QA, and continue to the next task only if the checks pass. Do not merge anything automatically.  

Use goal flow when you have a clear sequence of tasks and want the agent to manage delivery discipline across them.

Do not use it when requirements are still vague or when each step still needs product approval.

Plain-Language Intent vs Explicit Controls

Here is the simplest way to think about it:

Tell OpenCaw what outcome you want. Use exact names only when exactness helps.  

The explicit names are still valuable. I keep them visible because teams need stable vocabulary for docs, automation, task files, pull requests, and repeatable workflows.

But the day-to-day user experience should feel natural.

This is the balance I wanted OpenCaw to strike: plain-language control for humans, explicit machinery for agents and teams.

Example Prompts

Here are practical prompts I use or recommend after installing OpenCaw. Each example is written in plain language first, with an explicit version where the extra precision may help.

Repository Onboarding

Plain-language version:

Read the project instructions, inspect this repository, summarize the stack, identify missing architecture documentation, and recommend what should be standardized.  

Explicit version:

Read AGENTS.md instructions. Then inspect this repository, summarize the stack, identify missing architecture documentation, and recommend the OpenCaw architecture templates that apply.  

Architecture Generation

Plain-language version:

Create an architecture document for this repo. It has a .NET backend, React frontend, Postgres database, and GitHub Actions CI. Keep the document concise and easy for future agents to follow.  

Explicit version:

use role software-architect and generate ARCHITECTURE.md using DOTNET, REACT, POSTGRESDB, and GITHUB_ACTIONS. Keep the generated file concise with template read directives.  

Security Review

Plain-language version:

Review this repository for security risks. Focus on authentication, authorization, secrets, dependencies, logging, and deployment. Create tracked tasks for high-priority fixes and verify anything you change.  

Explicit version:

use role security-engineer + sre and review this repository for authentication, authorization, secrets, dependency, logging, and deployment risks. Create a task file for each high-priority fix.  

Test Coverage

Plain-language version:

Improve test coverage for this feature. Include edge cases, regression coverage, and a clear summary of the verification you ran.  

Explicit version:

use role qa-engineer and generate full test coverage for the current feature, including edge cases, regression tests, and verification evidence.  

Full Feature Delivery

Plain-language version:

Build the user settings page end to end. Plan the work, implement the API integration, add UI validation, update documentation if needed, run the right checks, and summarize the evidence.  

Explicit version:

use role fullstack-engineer and build the user settings page with API integration, UI validation, tests, task tracking, architecture updates if needed, and final verification.  

Existing GitHub Issue

Plain-language version:

Work on issue #123. Turn it into a tracked OpenCaw task, implement the fix, link the task back to the issue, add tests, run validation, and prepare it for PR review.  

Explicit version:

work on #123. Import the issue into OpenCaw task tracking, implement the fix, add tests, run verification, and prepare PR readiness evidence.  

Parallel Refactor

Plain-language version:

This checkout refactor is large. Split it into safe parallel work lanes only if that reduces risk. Keep file ownership clear, integrate the result, and verify the whole flow before calling it done.  

Explicit version:

use 3 agents with project-manager + backend-architect + qa-engineer to plan and implement the checkout refactor. Split only safe parallel lanes, keep write sets separate, then integrate and verify.  

Multi-Task Goal

Plain-language version:

Treat these five reporting tasks as one coordinated goal. Complete them in order, validate each one, open a PR when each task is ready, run post-PR QA, and stop if any check fails. Do not merge automatically.  

Explicit version:

goal: complete the reporting modernization across the five tasks listed in TODO.md. Raise each task PR after validation, run post-PR QA, and stop if validation or QA fails. Do not merge PRs automatically.  

Keeping OpenCaw Updated

If you installed OpenCaw as a submodule, update it with:

git submodule update --remote .codex  

Or, for another mount name:

git submodule update --remote .cursor  
git submodule update --remote .claude  

For production repositories, I recommend pinning a known release tag rather than automatically following the latest commit.

Example:

cd .codex  
git fetch --tags  
git checkout 2.0.0  
cd ..  
git add .codex  
git commit -m "chore(opencaw): pin OpenCaw 2.0.0"  

Replace 2.0.0 with the release tag you want to pin.

This gives you the best of both worlds: centralized updates when you want them, and controlled changes when stability matters.

Best Practices

Keep OpenCaw Shared, Keep Memory Local

Do not put project-specific lessons inside the OpenCaw baseline unless you are intentionally changing the shared framework.

Store project memory in .ai/.

Good places for project-local knowledge:

.ai/MEMORY.md
.ai/RULES.md
.ai/DEBUG.md
.ai/FRAGMENTS/
.ai/LEARNINGS/
.ai/tasks/

This is one of the most important design choices in OpenCaw. The baseline should be reusable. The host repository should own its local truth.

Validate After Changing Roles, Skills, or Commands

Run validation after editing OpenCaw internals:

./.codex/commands/validate-opencaw.sh

This is especially important if you customize roles, add skills, or introduce new commands.

Prefer Clear Intent Over Memorized Syntax

Weak prompt:

fix this  

Better plain-language prompt:

Fix this bug like a senior developer. Find the root cause, make the smallest safe change, add regression coverage, run the relevant checks, and summarize the evidence.  

More explicit version:

use role senior-developer + qa-engineer and fix this bug. Find the root cause, implement the smallest safe change, add regression coverage, run verification, and summarize the evidence.  

Both improved prompts give the agent a perspective, a quality bar, and a definition of done. The explicit role name is helpful, but the intent matters more than the syntax.

Ask for Evidence, Not Just Completion

A strong OpenCaw workflow ends with proof.

Good verification requests include:

Run the relevant tests and include command output in the final summary.  

Verify the browser flow with Playwright and attach evidence to the PR comment.  

Compare behavior before and after the change and document the difference.  

I care about evidence because "done" is cheap. Verified is what matters.

Use Goal Flow Carefully

Goal flow is powerful, but it works best when the task sequence is already clear.

Use it for planned delivery, not open-ended discovery.

Good goal-flow prompt:

goal: complete the migration plan across the five tasks already listed in TODO.md. Raise each PR after local validation, run post-PR QA, and stop if validation or QA fails. Do not merge PRs automatically.  

Do Not Skip the PR Readiness Gate

In normal task flow, OpenCaw expects the agent to ask before pushing or opening a PR.

Goal flow is the explicit exception, and even then it still requires validation and post-PR QA.

That gate exists for a reason. AI-assisted development should move quickly, but it should not bypass engineering discipline.

When OpenCaw Is a Good Fit

OpenCaw is especially useful when:

• You use AI coding tools across multiple repositories.
• Your team wants consistent agent behavior.
• You want repeatable architecture and verification standards.
• You want durable task tracking instead of chat-only planning.
• You want role-based AI workflows for architecture, QA, DevOps, security, and full-stack work.
• You want a project memory system that does not pollute the shared baseline.
• You want controlled PR readiness and QA behavior.

It may be more structure than you need for a tiny throwaway project. But for long-lived repositories, especially team-owned codebases, that structure is the point.

Final Thoughts

I built OpenCaw because I wanted AI-assisted development to become more repeatable, more auditable, and more useful across real repositories.

OpenCaw does not replace your coding agent. It gives that agent better rails.

Installed as .codex, .cursor, or .claude, OpenCaw becomes a reusable baseline for how work should be planned, implemented, verified, documented, and handed off.

The result is a more governed AI workflow:

• Plain-language intent tells the agent what outcome you want.
• Roles define perspective when you need precision.
• Skills define reasoning workflows behind the scenes.
• Commands define repeatable execution.
• .ai/ stores project memory.
• Verification evidence keeps the process honest.

For teams trying to move from casual AI prompting to repeatable AI-assisted engineering, OpenCaw is the structure I wish I had earlier. That is why I built it.

Most developers underestimate how transferable enterprise engineering patterns really are.

A queue is still a queue.
A scheduler is still a scheduler.
A planner is still a planner.

Whether the environment is:

• a Fortune 500 logistics platform,
• a cloud-native orchestration system,
• an autonomous AI workflow,
• or a colony of programmable units inside a video game.

That is what makes Screeps uniquely valuable for developers trying to learn modern AI systems engineering.

At first glance, Screeps looks like a programming game.

In reality, it is a persistent distributed systems simulator disguised as a game engine.

More importantly, it allows developers to practice:

• enterprise software architecture,
• AI planning,
• autonomous orchestration,
• observability,
• and systems design,

in an environment where the results are visually observable in real time.

That combination is extremely rare.

A Missing Piece in AI Education

Most AI learning material focuses on:

• prompts,
• embeddings,
• vector databases,
• model APIs,
• inference pipelines,
• or neural architectures.

Very little focuses on:

• autonomous orchestration,
• long-running planning systems,
• failure recovery,
• distributed coordination,
• or AI-native software architecture.

But these are the exact problems enterprise teams are struggling with right now.

Modern AI systems increasingly resemble:

• operating systems,
• distributed schedulers,
• planner networks,
• asynchronous workflow engines,
• and event-driven ecosystems.

Ironically, Screeps teaches these concepts better than many enterprise tutorials because the systems and their execution become visually observable.

You can literally watch architecture decisions succeed or fail.

Screeps Is Closer to Enterprise Software Than Most Developers Realize

A mature Screeps colony resembles a production enterprise platform far more than a traditional game bot.

Consider the parallels.

Enterprise Platform

API Gateway  
 ├── Authentication Service
 ├── Billing Service
 ├── Notification Service
 ├── Queue Processors
 ├── Workflow Orchestrators
 └── Monitoring Pipelines

Screeps Colony

Global Colony Manager  
 ├── Spawn Planner
 ├── Logistics Planner
 ├── Harvest Scheduler
 ├── Defense Coordinator
 ├── Expansion Planner
 └── Telemetry System

Structurally, these are extremely similar systems.

Both involve:

• asynchronous work,
• constrained resources,
• event-driven behavior,
• state synchronization,
• priority management,
• fault handling,
• distributed execution,
• and long-term planning.

The difference is that Screeps allows you to see the orchestration.

Enterprise Coding Standards Translate Directly Into Screeps

One of the most valuable aspects of using Screeps as an AI engineering sandbox is that enterprise coding patterns map naturally into colony architecture.

This means developers can strengthen both skill sets simultaneously.

Dependency Injection

Enterprise systems rely heavily on dependency injection for:

• modularity,
• testing,
• abstraction,
• and lifecycle management.

The same pattern becomes useful in Screeps almost immediately.

Hardcoded Approach

const roleHarvester = require('role.harvester');  

Hardcoded logic scales poorly.

Enterprise-Inspired Approach

class HarvesterBehavior {  
    execute(context) {
        // behavior logic
    }
}

container.register("harvester", HarvesterBehavior);  

Now your colony architecture supports:

• runtime composition,
• strategy replacement,
• testing,
• behavior injection,
• planner abstraction.

Exactly like enterprise systems.

Event-Driven Architecture

Enterprise systems increasingly rely on:

• Kafka,
• Azure Service Bus,
• RabbitMQ,
• event sourcing,
• reactive pipelines.

Screeps naturally pressures developers toward the same patterns.

Instead of direct execution:

creep.transfer(storage, RESOURCE_ENERGY);  

You evolve toward event production:

eventBus.publish({  
    type: "ENERGY_DELIVERED",
    source: creep.name,
    amount: 100
});

Now the colony becomes:

• observable,
• decoupled,
• replayable,
• analyzable.

This mirrors modern enterprise architecture almost perfectly.

Queue Systems and Work Orchestration

Enterprise orchestration systems live and die by queue management.

So do Screeps colonies.

A naive Screeps colony directly assigns work:

builder.build(target);  

A mature colony evolves toward distributed work scheduling:

taskQueue.enqueue({  
    type: "build",
    priority: 40,
    target: target.id
});

Suddenly you are implementing:

• priority queues,
• distributed scheduling,
• work leasing,
• retry handling,
• dead-letter concepts,
• starvation prevention.

These are enterprise engineering problems.

AI Planning Maps Directly to Enterprise Workflow Systems

This is where the connection becomes especially important for modern AI development.

AI systems are increasingly becoming:

• planner-driven,
• goal-oriented,
• workflow-based,
• and stateful.

Screeps naturally teaches these concepts because every colony already behaves like an autonomous workflow engine.

Goal-Oriented Planning

Enterprise AI systems increasingly rely on declarative goals.

Instead of:

Run task A.  
Then run task B.  
Then run task C.  

Modern systems increasingly define desired outcomes:

Maintain warehouse inventory above threshold.  
Reduce queue latency below SLA.  
Maintain service health under traffic spikes.  

Screeps evolves in exactly the same direction.

Early Colony Logic

spawnHarvester();  
spawnBuilder();  
spawnUpgrader();  

Mature Colony Planning

roomGoals = {  
    reserveEnergy: 50000,
    minimumHarvestRate: 120,
    constructionBacklogLimit: 5,
    defenseReadiness: "HIGH"
};

Now the colony planner determines:

• what should exist,
• when it should exist,
• and how to maintain equilibrium.

This is extremely similar to enterprise AI orchestration systems.

Observability and Telemetry

Enterprise engineering eventually teaches every developer the same painful lesson:

If you cannot observe the system, you cannot control the system.

Screeps teaches this aggressively.

Without telemetry:

• planners silently fail,
• logistics systems oscillate,
• CPU budgets collapse,
• economies deadlock.

This naturally pushes developers toward enterprise observability patterns.

Enterprise Monitoring Stack

Application Insights  
Prometheus  
Grafana  
Elastic  
Distributed tracing  
Structured logging  

Screeps Equivalent

Colony telemetry  
Task diagnostics  
Path heatmaps  
Tick performance metrics  
Planner audit logs  
Economic trend analysis  

The patterns are nearly identical.

The difference is that Screeps provides immediate visual reinforcement.

You can watch bad telemetry architecture hurt the colony.

Screeps Teaches AI-Native State Management

One of the hardest transitions for enterprise developers entering AI engineering is understanding long-lived state systems.

Traditional enterprise applications are often request-driven:

Request → Process → Response  

AI systems are increasingly persistent:

Observe → Plan → Adapt → Persist → Recover  

Screeps operates entirely in the second model.

Every tick:

• inherits previous state,
• modifies future state,
• reacts to changing conditions,
• and persists long-term consequences.

This mirrors:

• autonomous agents,
• workflow planners,
• AI orchestration systems,
• robotic coordination systems,
• and distributed automation platforms.

Coding Standards Become More Important, Not Less

One misconception around AI-assisted development is that coding standards matter less.

The opposite is true.

AI systems perform dramatically better when:

• architecture is predictable,
• abstractions are stable,
• naming conventions are consistent,
• planners are isolated,
• and system boundaries are clear.

Screeps makes this painfully obvious.

A poorly organized colony rapidly becomes impossible for:

• humans,
• planners,
• and AI coding systems

to reason about.

This naturally reinforces enterprise patterns like:

• Clean Architecture
• CQRS
• Domain-Driven Design
• Event Sourcing
• Service Isolation
• Planner Modularization
• Strategy Patterns
• Finite State Machines
• Blackboard Systems

Enterprise Refactoring Skills Become Transferable

One of the most surprising discoveries is how well enterprise refactoring skills translate into Screeps AI systems.

Enterprise Refactor

Break monolith into services.  

Screeps Equivalent

Break colony manager into planners.  

Enterprise Refactor

Introduce queue-based processing.  

Screeps Equivalent

Introduce colony task scheduler.  

Enterprise Refactor

Improve observability and tracing.  

Screeps Equivalent

Add planner telemetry and tick analytics.  

These are fundamentally the same engineering exercises.

AI Coding Models Become More Useful in Screeps Than Traditional CRUD

Large coding models struggle with isolated snippets because there is little systemic context.

But they become extremely effective when reasoning about:

• planners,
• workflows,
• scheduling,
• coordination,
• recovery systems,
• and architecture evolution.

Screeps gives models exactly the kind of environment where they excel.

Instead of prompting:

Generate a CRUD controller.  

You begin prompting:

Refactor this logistics planner to avoid oscillation during energy shortages.

Reduce path recalculation overhead.

Improve colony recovery behavior after catastrophic spawn loss.

Convert direct role assignment into a distributed task queue.  

These prompts are far closer to real AI engineering problems.

Safe Simulation Is the Real Advantage

Perhaps the most important aspect of Screeps is this:

It is a safe systems laboratory.

You can experiment with:

• autonomous planning,
• AI-generated code,
• aggressive refactors,
• distributed coordination,
• planner hierarchies,
• adaptive scheduling,
• and multi-agent behavior

without:

• damaging infrastructure,
• risking production systems,
• impacting users,
• or creating expensive outages.

This creates an unusually powerful learning environment.

Especially for enterprise developers transitioning into AI engineering.

Bridging Enterprise Engineering and AI Systems

This is ultimately why Screeps is so valuable.

It acts as a translation layer between:

• traditional enterprise software engineering,
• and modern autonomous AI architecture.

It allows developers to:

• apply enterprise patterns,
• observe autonomous behavior,
• test planner architectures,
• experiment with AI orchestration,
• and visually understand distributed systems dynamics.

All inside an environment where failure is educational instead of catastrophic.

Final Thoughts

Most developers trying to learn AI engineering focus too heavily on:

• model APIs,
• prompts,
• or frameworks.

But the future of AI systems is not just about inference.

It is about:

• orchestration,
• planning,
• state management,
• observability,
• distributed coordination,
• resilience,
• and long-running autonomous behavior.

Screeps happens to be one of the best environments available for learning all of those skills simultaneously.

Not because it teaches AI directly.

But because it teaches the engineering patterns that modern AI systems increasingly depend on.

The same systems that enterprise engineering teams depend on every day.

During gameplay of Arc Raiders, private Discord Direct Message (DM) conversations between two users were found being written in plaintext to a local game log file. Additionally, a full Discord Bearer authentication token was found stored in the same log file. These findings represent serious privacy and security violations that affect all players using Discord integration with the game.

Correction:

I originally reported that the bearer token had the ability to send a message on the user behalf. This was in error due to my misunderstanding of the permission rpc.voice.write. This permission only allows the token holder to change the users voice settings. It does not allow them to send a message as the user. This has been corrected in the article below to give the correct abilities. This message serves as a retraction notice.

Update: This has now been patched.

Affected Files

• Log File Location:

C:\Users\<username>\AppData\Local\PioneerGame\Saved\Logs  

• Log File Name: discord.log
• Discord SDK Version: commit 3b8f3adce7dd1d85463aa700d9185676633e98a1, version 1.8.13395

Risk Summary

Private DM Conversation Content Logged to Disk

Description:
Private Discord Direct Messages exchanged between two users were captured by the game's Discord SDK gateway connection and written in full to a plaintext log file stored locally on the user's machine.

Evidence:

• MESSAGE_CREATE gateway events appearing in the game log file
• Channel type 1 confirmed - this is a private DM channel, not a game or public channel
• Messages between users captured in full
• Message content, timestamps, user IDs, channel IDs all logged in plaintext

The Arc Raiders Discord SDK connects using a full user Bearer token, opening a complete Discord gateway connection identical to the one used by the Discord desktop app itself. Discord's gateway pushes all events to this connection - including private DM messages. Rather than filtering sensitive events, the SDK logs everything it receives to disk.

Impact:

• Any private conversation received while the game is running is written to disk
  
• Log files may be included in crash reports or bug report uploads
  
• Log files may be accessible to other applications on the same machine
  
• Third parties with access to the machine or crash reports can read private conversations
  

Discord Bearer Token Stored in Plaintext Log File

Description:
The user's full Discord Bearer authentication token was found written in plaintext inside the game log file.

Evidence:

"token":"Bearer <redacted>"

(Full token redacted for this report - present in original log file)

A Discord Bearer token is functionally equivalent to account access. Anyone in possession of this token can:

• Read all your messages and DMs
• Access your friend list, servers, and account settings
• Change voice, or discord settings
• Remain logged in until the password is changed

Impact:

• If the log file is ever shared (e.g., in a bug report, on a forum, to a support team), the token is fully exposed
  
• Crash report systems that automatically upload logs would transmit this token to Embark Studios' servers
  
• Malicious software on the same machine could harvest this token from the log file
  

Entire Friends List Presence Data Logged

Description:
PRESENCE_UPDATE and READY_SUPPLEMENTAL gateway events containing the online/offline status, activity, and metadata of the user's entire Discord friends list were written to the log file.

Evidence:

• Multiple PRESENCE_UPDATE events logged for third-party users
  
• READY and READY_SUPPLEMENTAL events containing bulk friend presence data at connection time
  

Impact:

• Third-party users who have no relationship with Arc Raiders have their Discord presence data written to another user's game log file without their knowledge or consent
  
• This affects people who never agreed to Arc Raiders' terms of service
  

Broader Than Necessary Gateway Scope

Description:
The Discord SDK integration requests and maintains a full Discord gateway connection using the user's Bearer token. Discord's own Rich Presence SDK is designed to only require a limited OAuth scope for game activity display. Using a full gateway connection vastly exceeds what is needed for Rich Presence functionality.

Impact:

• Exposes far more user data than necessary for the stated purpose (showing game status in Discord)
  
• Violates the principle of least privilege
  
• Creates unnecessary attack surface for all the findings listed above

For Embark Studios / Arc Raiders

1. Immediately filter MESSAGE_CREATE, PRESENCE_UPDATE, and authentication events from SDK logging
2. Never log Bearer tokens or authentication credentials to any file
3. Reduce the Discord gateway connection scope to only what Rich Presence requires (OAuth, not full Bearer)
4. Audit all crash report and log upload systems to ensure tokens and message content are scrubbed before transmission

For Discord

1. Review SDK design that allows full gateway connections via Bearer tokens for third-party games
2. Enforce stricter OAuth scopes for game Rich Presence integrations
3. Investigate whether this violates Developer Terms of Service

For Affected Users (Immediate Steps)

1. Change your Discord password immediately - this invalidates your current Bearer token
2. Do not share your log files with anyone, including support teams, until the token is removed
3. Disable discord integration inside of Arc Raiders this will remove the information being written to discord.log

This report was prepared based on direct analysis of game log files. All findings are based on observed technical behavior of the Discord SDK integration within Arc Raiders.

“Is this identity allowed to perform this action?”

They are far less effective at answering:

“Is this action correct right now?”

Most real-world security failures occur in this gap. Actions are authenticated, authorized, schema-valid, and yet behaviorally wrong. Endpoints are invoked out of order, workflows are bypassed, state is replayed, and valid APIs are called at invalid times.

I am proposing in this paper that State-Based Access Control (SBAC) addresses this gap by enforcing interaction correctness using a server-authoritative model inspired by authoritative simulation systems.

The diagram above illustrates how SBAC layers alongside RBAC and ABAC.
RBAC answers who may act, ABAC answers under what conditions, and SBAC enforces when an action is valid based on authoritative system state.
Only actions reachable from the current state are permitted. All others are treated as behavioral anomalies.

Motivation and Intuition

1. The Gap Between Allowed and Correct

Traditional access control models focus on identity and permission. They assume that once a client is authenticated and authorized, it will behave correctly.

In practice, this assumption fails. Attackers do not need exploits when they can simply call valid endpoints in the wrong order or at the wrong time.

SBAC exists to make behavior itself a first-class security concern.

2. The Core Principle

SBAC is built on simple concepts:

• Clients do not execute workflows
• They submit inputs
• The server decides what is possible

This principle has been battle-tested in multiplayer game engines for decades. SBAC applies the same thinking to web applications, APIs, and real-time distributed systems.

3. Why SBAC Complements RBAC and ABAC

SBAC is not a replacement for existing access control models.

• RBAC determines who may act
• ABAC determines under what conditions they may act
• SBAC determines when and in what order actions are valid

All three layers are required for correct enforcement.

SBAC Technical Specification

4. Definition of State-Based Access Control

State-Based Access Control (SBAC) is an access control model in which the validity of an action is determined by the current authoritative state of the system and the set of transitions reachable from that state.

An action is permitted if and only if:

1. The client is authenticated (out of scope)
2. The client is authorized by RBAC or ABAC (out of scope)
3. The action corresponds to a valid transition from the current state
4. All transition guards evaluate to true

5. Formal Model of Interaction State

SBAC assumes that applications have security-relevant state, even when that state is implicit in application logic.

This state must be made explicit.

Let:

• S be the set of all security-relevant server states
• I be the set of all externally observable client inputs
• T ⊆ S × I × S be the set of valid transitions

The authoritative interaction model is defined as:

G = (S, T)  

This graph is not a developer workflow diagram.
It is a security artifact.

If an action is not represented in T, it does not exist from a security perspective.

C# example: modeling states and transitions

public enum StateId  
{
    Browsing,
    CheckoutPending,
    Complete
}

public enum OperationId  
{
    StartCheckout,
    ConfirmCheckout
}

/// <summary>
/// Canonical external input after transport normalization.
/// </summary>
public sealed record InputEnvelope(  
    OperationId Operation,
    string ClientId,
    string SessionId,
    long Sequence,
    string Nonce,
    IReadOnlyDictionary<string, string> Meta,
    JsonElement? Payload);

public sealed record Transition(  
    StateId From,
    OperationId Operation,
    StateId To);

6. Transitions, Guards, and Reducers

Each transition in T is defined by:

• a source state
• an operation identifier
• a guard predicate
• a reducer function

The guard determines whether the transition is valid.
The reducer determines how the server state evolves.

Authorization logic belongs in guards.
State mutation belongs in reducers.

C# example: guard and reducer separation

public delegate ValueTask<bool> GuardAsync(  
    StateId state,
    ClassifiedClient client,
    InputEnvelope input,
    CancellationToken ct);

public delegate ValueTask<StateId> ReducerAsync(  
    StateId state,
    ClassifiedClient client,
    InputEnvelope input,
    CancellationToken ct);

public sealed record TransitionDef(  
    Transition Transition,
    GuardAsync Guard,
    ReducerAsync Reduce);

7. Input Envelopes and Normalization

SBAC does not validate raw requests.

All client interactions are normalized into a canonical input envelope before evaluation.

An input envelope typically contains:

• operation identifier
• client classification
• monotonic sequence number
• nonce or uniqueness token
• request metadata
• payload (if applicable)
• transport identifier

Normalization ensures uniform enforcement across transports, replay detection, and ordering validation.

C# example: normalize HTTP into an input envelope (minimal)

public static class InputNormalization  
{
    public static InputEnvelope FromHttp(HttpRequest req, string clientId, string sessionId)
    {
        // Example: map endpoint to an SBAC operation
        var op = req.Path.Value switch
        {
            "/checkout/start"   => OperationId.StartCheckout,
            "/checkout/confirm" => OperationId.ConfirmCheckout,
            _ => throw new InvalidOperationException("Unknown operation")
        };

        // Sequence/nonce can be sent as headers or body fields (implementation choice)
        var seq = long.Parse(req.Headers["X-Sbac-Seq"]);
        var nonce = req.Headers["X-Sbac-Nonce"].ToString();

        var meta = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
        {
            ["method"] = req.Method,
            ["path"] = req.Path.Value ?? "",
            ["ua"] = req.Headers.UserAgent.ToString()
        };

        return new InputEnvelope(op, clientId, sessionId, seq, nonce, meta, payload: null);
    }
}

8. The Ghost (Reachability Envelope)

At any moment, only a subset of transitions is valid.

Gs = { t ∈ T | from(t) = s ∧ guard(t, s) = true }  

Gs defines what actions are valid right now.
It is never fully exposed to the client.

Any input outside of Gs is behaviorally inconsistent and constitutes an anomaly.

The ghost represents a strict security boundary.
Transitions outside of Gs are not deferred, sanitized, or conditionally evaluated.
They are categorically invalid for the current state.

C# example: compute the ghost and enforce it

public sealed class SbacEngine  
{
    private readonly IReadOnlyList<TransitionDef> _defs;

    public SbacEngine(IEnumerable<TransitionDef> defs) => _defs = defs.ToList();

    public async ValueTask<IReadOnlyList<TransitionDef>> ComputeGhostAsync(
        StateId current,
        ClassifiedClient client,
        InputEnvelope inputContext,
        CancellationToken ct)
    {
        var candidates = _defs.Where(d => d.Transition.From == current).ToList();
        var allowed = new List<TransitionDef>(capacity: candidates.Count);

        foreach (var d in candidates)
        {
            if (await d.Guard(current, client, inputContext, ct))
                allowed.Add(d);
        }

        return allowed;
    }

    public async ValueTask<StateId> ApplyAsync(
        StateId current,
        ClassifiedClient client,
        InputEnvelope input,
        CancellationToken ct)
    {
        var ghost = await ComputeGhostAsync(current, client, input, ct);

        var match = ghost.FirstOrDefault(d => d.Transition.Operation == input.Operation);
        if (match is null)
            throw new SbacAnomalyException(SbacAnomaly.InvalidTransitionAttempt, "Operation not in ghost");

        return await match.Reduce(current, client, input, ct);
    }
}

9. Bounded Lookahead and Predictive Disclosure

SBAC may optionally define bounded reachability:

Reachable(s, k)  

This represents the set of states reachable from s within k transitions.

Bounded reachability enables predictive asset loading, UI prefetching, capability pre-issuance, and latency hiding.

Predictive disclosure must never expand the ghost.

C# example: bounded lookahead for prefetch hints (conceptual)

public static class Reachability  
{
    public static ISet<StateId> ReachableWithin(
        StateId start,
        int k,
        IEnumerable<TransitionDef> defs)
    {
        var byFrom = defs.GroupBy(d => d.Transition.From)
                         .ToDictionary(g => g.Key, g => g.Select(x => x.Transition.To).ToArray());

        var reachable = new HashSet<StateId> { start };
        var frontier = new HashSet<StateId> { start };

        for (int depth = 0; depth < k; depth++)
        {
            var next = new HashSet<StateId>();
            foreach (var s in frontier)
            {
                if (!byFrom.TryGetValue(s, out var tos)) continue;
                foreach (var to in tos)
                    if (reachable.Add(to)) next.Add(to);
            }
            frontier = next;
            if (frontier.Count == 0) break;
        }

        return reachable;
    }
}

10. Client Model

SBAC replaces the ambiguous notion of “user” with client.

A client is any external entity that interacts with the system and may originate inputs or receive disclosures.

Client classification is assigned by the server, not claimed by the client.

C# example: classify a client (simplified)

public enum ClientClass  
{
    Human,
    Api,
    Seo,
    Unknown
}

public sealed record ClassifiedClient(  
    string ClientId,
    ClientClass Class,
    string? SubjectId,     // user id or service principal id
    string? TokenId);      // JTI or equivalent

11. Client Classes

SBAC recognizes four common client classes:

• Interactive Human Client
• Programmatic API Client
• Observational Client (SEO)
• Unknown Client

Each class receives a different projection of the system and interaction surface.

12. Authoritative Disclosure (SEO)

Observational clients do not traverse workflows.

They receive disclosure projections, which are read-only, server-authored views of the system.

Disclosure endpoints must never originate state transitions.

13. Capability Tokens and State Coupling

SBAC discourages implicit permission for stateful operations.

Instead, the server issues capability tokens that bind an operation to a specific state or resource and are time-limited.

Capabilities are proofs of reachability, not authentication.

C# example: capability token shape (conceptual)

public sealed record Capability(  
    string CapabilityId,
    string ClientId,
    OperationId Operation,
    StateId BoundState,
    DateTimeOffset ExpiresAt,
    string Signature); // HMAC or asymmetric signature

// Verify that the capability was issued by the server and is still valid
public static bool VerifyCapability(Capability cap, StateId currentState, DateTimeOffset nowUtc)  
{
    if (cap.ExpiresAt <= nowUtc) return false;
    if (cap.BoundState != currentState) return false;
    // Signature validation omitted here (implementation-specific)
    return true;
}

14. Transport-Agnostic Enforcement

All client inputs must pass through the same authoritative validation pipeline, regardless of transport.

Behavior must be enforced identically across HTTP, WebSockets, SignalR, gRPC, and message queues.

15. Temporal Integrity

SBAC assumes adversaries can replay requests.

The server must therefore detect duplicated, reordered, or delayed inputs using sequence numbers, nonces, or server-issued state versions.

C# example: basic sequence/nonce gate (per session)

public sealed class ReplayGate  
{
    private long _lastSeq;
    private readonly HashSet<string> _nonces = new(StringComparer.Ordinal);

    public bool Accept(long seq, string nonce)
    {
        if (seq <= _lastSeq) return false;
        if (!_nonces.Add(nonce)) return false;

        _lastSeq = seq;

        // Production: expire nonces over time to bound memory.
        return true;
    }
}

16. Anomaly Classification

SBAC defines a standard anomaly taxonomy:

• Invalid transition attempt
• Temporal violation
• Guard failure
• Enumeration or probing
• Integrity divergence

Anomalies are first-class security signals.

Anomaly classification is coupled with response policy.

SBAC does not mandate a specific response, but it requires that anomalies be observable and actionable.
Common responses include token revocation, forced re-authentication, progressive trust degradation, and temporary account lockout.

C# example: anomaly types and exception

public enum SbacAnomaly  
{
    InvalidTransitionAttempt,
    TemporalViolation,
    GuardFailure,
    EnumerationOrProbing,
    IntegrityDivergence
}

public sealed class SbacAnomalyException : Exception  
{
    public SbacAnomaly Type { get; }

    public SbacAnomalyException(SbacAnomaly type, string message) : base(message)
        => Type = type;
}

Example: Blocking a Real-World Workflow Bypass

17. Scenario Overview

Consider a common e-commerce checkout flow:

1. Browse catalog
2. Select item
3. Start checkout
4. Confirm payment

The system uses modern authentication (OAuth or JWT-based access tokens), RBAC for role enforcement, and ABAC for contextual checks such as region, device, or account state.

An attacker does not bypass authentication.

Instead, the attacker successfully exploits a client-side vulnerability (for example, reflected XSS in a product review field) and steals a legitimate user’s access token.

The attacker now possesses a valid, unexpired token issued by the system and begins using it programmatically.

18. Attack Without SBAC

Using the stolen access token, the attacker:

• presents a valid bearer token issued to a real user
• satisfies RBAC checks
• satisfies ABAC checks

Instead of following the intended state progression enforced by the client UI, the attacker directly invokes:

POST /checkout/confirm  

No item has been selected.
No checkout session has been initialized.
No prior server-side state transition has occurred.

From a traditional access-control perspective:

• authentication passes
• authorization passes
• the endpoint exists and is valid

Unless additional ad-hoc checks exist, the request is processed.

This is not an authentication failure.
This is not an authorization failure.

It is a behavioral failure.

19. Same Attack With SBAC

In an SBAC-enabled system, the authoritative interaction graph includes states such as:

• Browsing
• CheckoutPending
• Complete

The transition ConfirmCheckout is defined as valid only from CheckoutPending.

At the time the stolen token is used, the server’s authoritative state for that session is:

Browsing  

The computed ghost is:

Gs = { StartCheckout }  

When the attacker submits ConfirmCheckout, the server evaluates the request against Gs.

The transition is not reachable.

The request is rejected and classified as a behavioral anomaly.

As part of anomaly handling:

• the access token is immediately invalidated
• the active session is terminated
• the legitimate user is required to re-authenticate

This response assumes credential compromise and prioritizes containment over attribution.

This corresponds to the blocked transition path shown in the SBAC diagram, where an out-of-sequence action is rejected before any state mutation occurs.

C# example: anomaly response (revoke token, force re-auth, lockout)

public interface ITokenRevocation  
{
    ValueTask RevokeAsync(string tokenId, CancellationToken ct);
}

public interface IAccountLockout  
{
    ValueTask RegisterAnomalyAsync(string subjectId, SbacAnomaly anomaly, CancellationToken ct);
    ValueTask<bool> ShouldLockoutAsync(string subjectId, CancellationToken ct);
    ValueTask LockoutAsync(string subjectId, TimeSpan duration, CancellationToken ct);
}

public sealed class SbacResponsePolicy  
{
    private readonly ITokenRevocation _revocation;
    private readonly IAccountLockout _lockout;

    public SbacResponsePolicy(ITokenRevocation revocation, IAccountLockout lockout)
    {
        _revocation = revocation;
        _lockout = lockout;
    }

    public async ValueTask HandleAnomalyAsync(ClassifiedClient client, SbacAnomaly anomaly, CancellationToken ct)
    {
        // Always revoke the token used in the anomalous request (credential misuse assumption).
        if (!string.IsNullOrWhiteSpace(client.TokenId))
            await _revocation.RevokeAsync(client.TokenId!, ct);

        // Track anomalies for escalation decisions.
        if (!string.IsNullOrWhiteSpace(client.SubjectId))
        {
            var subject = client.SubjectId!;
            await _lockout.RegisterAnomalyAsync(subject, anomaly, ct);

            if (await _lockout.ShouldLockoutAsync(subject, ct))
                await _lockout.LockoutAsync(subject, duration: TimeSpan.FromMinutes(15), ct);
        }

        // “Force re-auth” is typically implemented by refusing future requests
        // until a fresh token is minted (e.g., 401 + prompt login).
    }
}

20. Why This Matters

This attack is realistic and common:

• tokens are stolen via XSS, malicious extensions, compromised devices, or leaked logs
• the attacker does not need to escalate privileges
• the attacker uses the system exactly as designed, just out of sequence

The request was:

• authenticated
• authorized
• syntactically valid

It was rejected solely because it was not correct in the current state.

SBAC treats this as more than a failed request.

A behavioral anomaly indicates likely credential misuse. As a result:

• the token is revoked
• the user is prompted to re-authenticate
• the event is logged and correlated

Repeated anomalies originating from the same identity, device, or network context may trigger:

• progressive trust degradation
• temporary account lockout
• secondary verification requirements

SBAC does not try to prevent token theft.
It assumes credentials will eventually be compromised.

SBAC ensures that compromised credentials cannot be used to violate system behavior silently.

In SBAC, invalid behavior is not only blocked, it is used as a signal to actively protect the user.

21. Relationship to RBAC and ABAC

RBAC and ABAC still apply.

They determine who may act and under what conditions.

SBAC determines when actions are possible.

22. Limitations

SBAC does not prevent server compromise.

It enforces correctness of client interaction, not the purity of execution.

23. Conclusion

State-Based Access Control formalizes a class of security checks that most systems already attempt informally.

By making interaction state explicit, server-authoritative, and enforceable, SBAC closes the gap between “allowed” and “correct.”

By assuming credential compromise and enforcing correctness at the interaction layer, SBAC shifts security from prevention alone to continuous behavioral enforcement.

Clients do not navigate reality.
They propose inputs.
The server decides what is reality.

⚠️This article is for educational and engineering purposes only. It does not constitute financial advice, investment recommendations, or trading signals. Use the information at your own risk. Currency markets are volatile, and you should do your own research before making any financial decisions.

In the first iteration called the tides model, we looked at market behavior as surface tides of predictable oscillations captured by NickRypock Trailing Reverse (NRTR) and NickRypock Moving Average (NRMA) indicators.

They expressed the visible rhythm of market movement, the waves, if you will, that traders "surf" on.

But beneath that surface lie deeper currents!

Liquidity pockets, order flow imbalances, and liquidation clusters act like thermohaline currents, quietly steering large-scale behavior long before it’s visible above.
Meanwhile, sentiment events and social cascades act as storms, transferring sudden bursts of energy into the market’s atmosphere.

The new model, called the ocean model now introduces three-layers inspired by fluid dynamics:

• Surface Layer (Tides) observable price motion
• Subsurface Layer (Underflows) liquidity, order flow, and liquidation dynamics
• Atmospheric Layer (Storms) sentiment and emotional energy

Together, these layers form a coupled system of forces that can explain how market energy builds, transfers, and releases!

The Roaring Ocean Model

Each layer exchanges energy with the others:

• Subsurface imbalances precede large moves.
• Surface waves translate deep motion into price.
• Sentiment perturbs the whole system from above.

This represents the hydrodynamic energy balance of the market in one large expressive formula. Now, let's break this down in it's parts, and code!

The Market Tides Composite Index

At each timestep _t, given by streaming candles, order data, and sentiment state, the total market energy can be represented as the Market Tides Composite Index:

where:

• T_t = surface tide strength
• U_t = subsurface underflow strength
• α_t = atmospheric sentiment pressure
• G_t = nonlinear coupling amplifier
• w_T, w_U, w_S = layer weights (w_T + w_U + w_S = 1)

Below is the equivalent C# implementation:

public sealed class MtciParams  
{
    public double wT = 0.5, wU = 0.35, wS = 0.15;
    public double wL = 0.6, wShrt = 0.4;
    public double OFP = 0.6, LHF = 0.4;
    public double cT = 1.25, cO = 1.0, cH = 1.0, cS = 1.0;
    public double g1 = 0.4, g2 = 0.6, gMax = 2.0;
    public double Eps = 1e-9; // ε safeguard
}

public sealed class MtciEngine  
{
    private readonly MtciParams _p;
    public MtciEngine(MtciParams p) => _p = p;

    public double Compute(double price,
                          double nrmaL, double nrtrL,
                          double nrmaS, double nrtrS,
                          double ofp, double lhf,
                          double alpha)
    {
        double T_L = Math.Tanh(_p.cT * ((nrmaL - nrtrL) / Math.Max(price, _p.Eps)));
        double T_S = Math.Tanh(_p.cT * ((nrmaS - nrtrS) / Math.Max(price, _p.Eps)));
        double T = _p.wL * T_L + _p.wShrt * T_S;

        double U = _p.OFP * ofp + _p.LHF * lhf;

        double G = 1.0 + _p.g1 * Math.Abs(ofp) + _p.g2 * Math.Max(0.0, lhf);
        G = Math.Min(G, _p.gMax);

        return _p.wT * G * T + _p.wU * U + _p.wS * alpha;
    }
}

Surface Layer (Tides)

The surface layer measures how NRMA and NRTR diverge the “height” of the market wave across long and short timeframes:

Below is the equivalent C# implementation:

public sealed class NRTR  
{
    public double K { get; }
    private double _trend;
    private double _h, _l, _rev;

    public double Reverse => _rev;
    public double Trend => _trend;

    public NRTR(double k, double initial)
    {
        K = k;
        _trend = +1;
        _h = initial;
        _l = initial;
        _rev = initial;
    }

    public double Update(double close)
    {
        if (_trend >= 0)
        {
            if (close > _h) _h = close;
            _rev = _h * (1.0 - K * 0.01);
            if (close <= _rev)
            {
                _trend = -1;
                _l = close;
                _rev = _l * (1.0 + K * 0.01);
            }
        }
        else
        {
            if (close < _l) _l = close;
            _rev = _l * (1.0 + K * 0.01);
            if (close >= _rev)
            {
                _trend = +1;
                _h = close;
                _rev = _h * (1.0 - K * 0.01);
            }
        }
        return _rev;
    }
}

public sealed class NRMA  
{
    public double K { get; }
    public int Fast { get; }
    public int Sharp { get; }
    private NRTR _nrtr;
    private double _prev;
    private readonly Queue<double> _recent = new();

    public double Value => _prev;

    public NRMA(double k, int fast, int sharp, double initial)
    {
        K = k; Fast = fast; Sharp = sharp;
        _nrtr = new NRTR(k, initial);
        _prev = initial;
    }

    public double Update(double close)
    {
        double r = _nrtr.Update(close);
        double osc = (100.0 * Math.Abs(close - r) / Math.Max(close, 1e-12)) / Math.Max(K, 1e-12);
        _recent.Enqueue(osc);
        while (_recent.Count > Math.Max(3, Fast)) _recent.Dequeue();

        double avg = 0.0;
        foreach (var v in _recent) avg += v;
        avg /= _recent.Count;

        double F = 2.0 / (1.0 + Fast);
        double rho = F * Math.Pow(avg, Sharp);

        _prev = _prev + rho * (close - _prev);
        return _prev;
    }
}

Subsurface Layer (Underflows)

The underflow layer models two invisible but powerful forces:

1. Order Flow Pressure (OFP_t):

where B_d and A_d are bid/ask volumes within depth d.

2. Liquidation Heat Flux (LHF_t):

These combine into:

Below is the equivalent C# implementation:

public static class Underflows  
{
    public static double Ofp(double cO, double bidsDepthSum, double asksDepthSum, double eps = 1e-9)
    {
        double num = (bidsDepthSum - asksDepthSum);
        double den = (bidsDepthSum + asksDepthSum + eps);
        return Math.Tanh(cO * (num / den));
    }

    public sealed record LiqEvent(bool IsShort, double Price, double Size, DateTime TimeUtc);

    public static double Lhf(double cH,
                             IEnumerable<LiqEvent> events,
                             double currentPrice,
                             double advVolume,
                             DateTime nowUtc,
                             double lambdaDist = 0.002,
                             double lambdaTime = 0.001,
                             double eps = 1e-9)
    {
        double up = 0.0, down = 0.0;
        foreach (var e in events)
        {
            double dist = Math.Abs(e.Price - currentPrice);
            double dtSec = Math.Max(0.0, (nowUtc - e.TimeUtc).TotalSeconds);
            double w = Math.Exp(-lambdaDist * dist) * Math.Exp(-lambdaTime * dtSec);
            if (e.IsShort && e.Price > currentPrice) up += e.Size * w;
            if (!e.IsShort && e.Price < currentPrice) down += e.Size * w;
        }

        double num = (up - down);
        double den = Math.Max(advVolume, eps);
        return Math.Tanh(cH * (num / den));
    }
}

Atmospheric Layer (Storms)

The storm layer captures exogenous sentiment energy:

where Z_ssst is the z-scored sentiment index from social sources (e.g., Twitter).

Below is the equivalent C# implementation:

public sealed class ZScore  
{
    private readonly int _win;
    private readonly Queue<double> _buf = new();
    private double _sum, _sum2;
    private readonly double _eps;

    public ZScore(int window = 300, double eps = 1e-9)
    { _win = window; _eps = eps; }

    public double Update(double x)
    {
        _buf.Enqueue(x);
        _sum += x;
        _sum2 += x * x;
        if (_buf.Count > _win)
        {
            double y = _buf.Dequeue();
            _sum -= y; _sum2 -= y * y;
        }

        int n = _buf.Count;
        double mu = _sum / Math.Max(1, n);
        double var = Math.Max(0.0, _sum2 / Math.Max(1, n) - mu * mu);
        double sigma = Math.Sqrt(var);
        return (x - mu) / Math.Max(_eps, sigma);
    }
}

public static class Storms  
{
    public static double Alpha(double cS, double zScore) => Math.Tanh(cS * zScore);
}

Coupling Amplifier

Just as deep currents magnify surface waves, the coupling term G_t modulates how underflows amplify tides:

Below is the equivalent C# implementation:

public static class Coupling  
{
    public static double Gain(double ofp, double lhf, double g1, double g2, double gMax = 2.0)
    {
        double g = 1.0 + g1 * Math.Abs(ofp) + g2 * Math.Max(0.0, lhf);
        return Math.Min(g, gMax);
    }
}

The roaring ocean

Once all layers are computed, we integrate them into an event / loop that runs each market tick (or candle close). This determines whether to enter, exit, or stay out based on the Market Tides Composite Index and the state of each layer!

Below is the equivalent C# implementation:

public sealed class Logic  
{
    private readonly MtciEngine _engine;
    private readonly double _entry, _exit, _halt;

    public Logic(MtciEngine engine, double entryThreshold = 0.7, double exitThreshold = 0.3, double haltThreshold = 0.85)
    {
        _engine = engine;
        _entry = entryThreshold;
        _exit = exitThreshold;
        _halt = haltThreshold;
    }

    public enum SignalType { None, Long, Short, Exit, Halt }

    public SignalType Evaluate(double price,
                               double nrmaL, double nrtrL,
                               double nrmaS, double nrtrS,
                               double ofp, double lhf,
                               double alpha)
    {
        double mtci = _engine.Compute(price, nrmaL, nrtrL, nrmaS, nrtrS, ofp, lhf, alpha);

        // Storm halt condition — too much sentiment pressure
        if (Math.Abs(alpha) >= _halt)
            return SignalType.Halt;

        bool longTrend = (nrmaL > nrtrL) && (nrmaS > nrtrS);
        bool shortTrend = (nrmaL < nrtrL) && (nrmaS < nrtrS);

        if (longTrend && mtci >= _entry) return SignalType.Long;
        if (shortTrend && mtci <= -_entry) return SignalType.Short;

        if (Math.Abs(mtci) < _exit) return SignalType.Exit;

        return SignalType.None;
    }
}

Evaluation:

// Test: called once per candle update
void OnNewCandle(Candle c)  
{
    var nrmaL = nrmaLong.Update(c.Close);
    var nrmaS = nrmaShort.Update(c.Close);
    var nrtrL = nrtrLong.Update(c.Close);
    var nrtrS = nrtrShort.Update(c.Close);

    var ofp = Underflows.Ofp(paramsOFP, totalBids, totalAsks);
    var lhf = Underflows.Lhf(paramsLHF, liquidationEvents, c.Close, advVolume, DateTime.UtcNow);
    var alpha = Storms.Alpha(paramsStorm, sentimentZ);

    var signal = logic.Evaluate(c.Close, nrmaL, nrtrL, nrmaS, nrtrS, ofp, lhf, alpha);

    Console.WriteLine($"{c.Time}: Signal={signal}");
}

⚠️This article is for educational and engineering purposes only. It does not constitute financial advice, investment recommendations, or trading signals. Use the information at your own risk. Currency markets are volatile, and you should do your own research before making any financial decisions.

Currency markets often feel like standing on a shoreline. Slow tides rise and fall, smaller waves crash on top, and sometimes storms disrupt everything! This is the biases for an idea i had called the tides, or ocean model.

• The Long Tide: The big swells that lift or lower all boats. In markets, this is the slow trend captured by an adaptive moving average.

• The Short Tide: The quick in-and-out waves. In markets, these are the short-term reversals we track with a trailing reverse line.

• The Storm Surges: Sudden shocks from the weather. In crypto, this is Twitter sentiment, where one influential tweet can make or break a trade.

The goal: align trades with both tides, but pause or adjust when a storm blows in!

We’ll break this down into math, C# implementations, and how to combine them across timeframes for assets like ETH, IMX, and GODS.

System Architecture

At a high level, the model has three components:

1. Price Indicators (NRMA, NRTR)

   • Run separately on long intervals (daily, weekly) and short intervals (3m, 5m).
   • Each produces trend and reversal markers.

2. Sentiment Layer

   • Tracks influencer Twitter accounts for each coin.
   • Produces a normalized “storm surge” score.

3. Composite Signal Logic

   • Combines long tide, short tide, and sentiment into actionable trades.

Indicator Engineering

Nick Rypock Trailing Reverse (NRTR)
The short tide is modeled with NRTR, a trailing stop algorithm that flips trend when price crosses a reversal line.

Formulas:

• In uptrend:
  
• In downtrend:
  

C# Implementation:

public class NRTR  
{
    public double K { get; private set; }
    public double Trend { get; private set; }
    public double HPrice { get; private set; }
    public double LPrice { get; private set; }
    public double Reverse { get; private set; }

    public NRTR(double k, double initialPrice)
    {
        K = k;
        Trend = 1; // assume initial uptrend
        HPrice = initialPrice;
        LPrice = initialPrice;
        Reverse = initialPrice;
    }

    public double Calculate(double close)
    {
        if (Trend >= 0)
        {
            if (close > HPrice)
                HPrice = close;

            Reverse = HPrice * (1 - K * 0.01);
            if (close <= Reverse)
            {
                Trend = -1;
                LPrice = close;
                Reverse = LPrice * (1 + K * 0.01);
            }
        }

        if (Trend <= 0)
        {
            if (close < LPrice)
                LPrice = close;

            Reverse = LPrice * (1 + K * 0.01);
            if (close >= Reverse)
            {
                Trend = 1;
                HPrice = close;
                Reverse = HPrice * (1 - K * 0.01);
            }
        }

        return Reverse;
    }
}

Nick Rypock Moving Average (NRMA)
The long tide is modeled with NRMA, an adaptive EMA where volatility is defined by deviations from NRTR.

Formulas:

Where:

C# Implementation:

public class NRMA  
{
    public double K { get; private set; }
    public int Fast { get; private set; }
    public int Sharp { get; private set; }
    public NRTR nrtr { get; private set; }
    public double prevNRMA { get; private set; }

    public NRMA(double k, int fast, int sharp, double initialPrice)
    {
        K = k;
        Fast = fast;
        Sharp = sharp;
        nrtr = new NRTR(k, initialPrice);
        prevNRMA = initialPrice;
    }

    public double Calculate(double close, double[] recentCloses)
    {
        if (recentCloses.Length <= Fast)
        {
            prevNRMA = close;
        }
        else
        {
            double oscSum = 0;
            var count = Math.Min(3, recentCloses.Length);

            for (var i = recentCloses.Length - count; i < recentCloses.Length; i++)
            {
                double deviation = 100 * Math.Abs(recentCloses[i] - nrtr.Calculate(recentCloses[i])) / recentCloses[i];
                oscSum += deviation / K;
            }

            double oscAvg = oscSum / count;
            var NRratio = Math.Pow(oscAvg, Sharp);
            double F = 2.0 / (1 + Fast);

            prevNRMA += NRratio * F * (close - prevNRMA);
        }

        return prevNRMA;
    }
}

Sentiment Scoring from Twitter

Instead of monitoring the entire internet, the model watches curated influencer accounts per coin (e.g., Vitalik for ETH, Immutable devs for IMX, Gods Unchained accounts for GODS).

Pareto Principle in Sentiment Design

Not all voices on Twitter move markets equally. In fact, by the Pareto principle, roughly 20% of accounts generate 80% of meaningful price impact.

Instead of processing millions of tweets, the model only tracks curated influencer accounts for each asset:

• For ETH, that might mean Ethereum core devs and Vitalik.
• For IMX, Immutable team members.
• For GODS, the Gods Unchained project leads.

This drastically reduces cost and noise, while retaining the majority of predictive power.
The result is a lightweight, event-driven storm surge model instead of a full-blown NLP pipeline.

Formulas:

C# Implementation:

public class TwitterSentiment  
{
    private readonly Dictionary<string, int> _weights;
    private readonly List<(DateTime, int, int)> _events;

    public TwitterSentiment(Dictionary<string, int> influencerWeights)
    {
        _weights = influencerWeights;
        _events = new List<(DateTime, int, int)>();
    }

    public void AddTweet(string account, string text)
    {
        int polarity = ClassifyPolarity(text);
        if (_weights.TryGetValue(account, out int weight))
            _events.Add((DateTime.UtcNow, polarity, weight));
    }

    public double CalculateScore(TimeSpan halfLife)
    {
        double sum = 0;
        foreach (var (timestamp, polarity, weight) in _events)
        {
            double ageHours = (DateTime.UtcNow - timestamp).TotalHours;
            double decay = Math.Pow(0.5, ageHours / halfLife.TotalHours);
            sum += weight * polarity * decay;
        }
        return sum;
    }

    private int ClassifyPolarity(string text)
    {
        string lower = text.ToLower();
        if (lower.Contains("hack") || lower.Contains("exploit") || lower.Contains("lawsuit"))
            return -1;
        if (lower.Contains("launch") || lower.Contains("upgrade") || lower.Contains("partnership"))
            return 1;
        return 0;
    }
}

Multi-Timescale Integration

We maintain two indicator sets per asset:

• Long Tide: NRMA-long, NRTR-long → daily/weekly candles.
• Short Tide: NRMA-short, NRTR-short → 3m/5m candles.

Composite Signal Logic:

• Long if both long + short are bullish and sentiment ≥ 0.
• Short if both long + short are bearish and sentiment ≤ 0.
• No trade otherwise.

Example (Eth):

double ethLong = nrmaLong.Calculate(dailyClose, dailyRecentCloses);  
double ethLongRev = nrtrLong.Calculate(dailyClose);

double ethShort = nrmaShort.Calculate(min5Close, min5RecentCloses);  
double ethShortRev = nrtrShort.Calculate(min5Close);

double ethSentiment = twitterEth.CalculateScore(TimeSpan.FromHours(3));

if (ethLong > ethLongRev && ethShort > ethShortRev && ethSentiment >= 0)  
    Console.WriteLine("ETH Long");
else if (ethLong < ethLongRev && ethShort < ethShortRev && ethSentiment <= 0)  
    Console.WriteLine("ETH Short");
else  
    Console.WriteLine("No Trade");

Closing

By structuring the market like an ocean system, tides, waves, and storms. We get a model that's both intuitive and implementable.

• NRTR and NRMA provide the price structure.
• Twitter sentiment adds a low-cost shock filter.
• Multi-timescale integration ensures coherence.

This is not a trading strategy by itself, but a blueprint for engineers to test, refine and learn. There are many variables in the algorithms above which are purposefully not explained. I also did not provide weights for the social scoring algorithm which is likely better replaced with an ai driven sentiment model rather than a simple word database! These are issues left to the reader to solve.

⚠️This article is for educational and engineering purposes only. It does not constitute financial advice, investment recommendations, or trading signals. Use the information at your own risk. Currency markets are volatile, and you should do your own research before making any financial decisions.

On 3/10/2024 the Council of Mortals asked me to audit the sealed portion of the Gods Unchained client to verify if it was actually possible to use cards that where not in your sealed pool, in your sealed deck. This audit was limited in scope to sealed, and validation that the exploit found only affected sealed.

This post is disclosure of that process. It's important to note that before disclosure. This exploit was fixed on 3/20. It's unknown if the method proposed in this audit was used to fix the exploit. However, testing after the 3/20 patch, i can validate this exploit is no longer working at this time.

TLDR

Question: Could you save your sealed deck with cards not in your pool?
Answer: Yes, if you know the proto id of the card, or cards you want.

Question: Can you still do this?
Answer: No.

Exploit

This exploit could be preformed by capturing and saving requests from inside the client, and then replaying those same requests with the new proto ids you want within the time period it's still valid (about 120 seconds).

Note: Fiddler Everywhere was used to capture, modify, and replay the traffic for this audit.

While the scope of this audit was the sealed api, i did take the time to validate if the same injection method was usable in ranked / casual, however, in those modes there is an "ownership" check that prevents this type of injection. Sealed mode does not contain that check so that you can play in sealed with cards you don't own if they are also assigned in your random pool.

Solution

The active sealed sessions API call list's ALL of the cards (proto's) in our random pool. There needs to be a check on the Save Deck API call that double checks that the proto id's (cards) saved in the array are in fact also in the array of proto's (cards) in our pool. If proto's (cards) are contained that DO NOT match, then, AccessDenied should be returned and the deck should not be saved.

Details

Full disclosure this audit was preformed on my personal GU account, no games where played with this modified sealed session. Once proof was gathered, the sealed run was abandoned (RIP 5 gods). This can be verified with the sealed session id in the JSON listed below.

Get Sealed Session

This API call will list the active sealed session for a player. It also includes our card_pool which has a list of all proto id's (cards) that we were randomly assigned at the time of buy in.

→ GET gamemode.prod.prod.godsunchained.com/user/{guid}/gamemode/7/session

• Requires
  • guid
    This is a players id in game. It can be retrieved through various methods.

← Returns

{"id":"0072e0cb-7c09-4e45-8e27-0726368b2dff","user_id":436860,"buy_in_id":"dd58db39-9cb2-4598-85ec-60fc0c2b85e4","game_mode_global_id":7,"god_pool":["nature","death","magic"],"card_pool":[1132,2002,1605,87061,1159,1680,87056,1215,1605,2325,1604,2328,1260,1165,1130,1154,1673,1616,1032,1293,2003,1245,1295,1122,1248,1294,1122,1011,1532,1751,1083,1122,1292,2263,1182,87069,1243,1245,87067,1698,1564,87049,1570,2257,1168,1668,1753,1045,1092,1043,1092,2313,2257,1676,2311,1081,1101,1551,1081,2311],"deck_id":9864282,"god":"","properties":{"paid":true,"max_wins":7,"max_losses":3,"buy_in_cost":5,"buy_in_currency":"gods"},"win":0,"loss":0,"status":"started","created_at":"2024-03-10T21:01:36.781066Z","updated_at":"2024-03-10T21:49:26.542857Z"}

Save Deck

This will save a deck with the information contained in the payload. There is no validation made that cards saved are in the pool list above, at the the time of this audit. I did also test trying to use a god you where not assigned at the time of buy in, but this did not work, if you try and use god not assigned you assigned your first god in the list of gods.

→ PUT deck.prod.prod.godsunchained.com/user/{guid}/deck/{deckid}

• Requires
  • guid
    This is a players id in game. It can be retrieved through various methods.
  • deckid
    This is the deck id assigned to the current active sealed session. You can get this id from the "Get Sealed Sessions API" response.

Payload

{"id":9864282,"name":"Nature Deck","god":"nature","deck_type":"restricted","ids":[233795109,228897085,78293701,198293435,73982871,209542666,225424635,142817595,221197551,97683802,192815310,64983360,151796170,33781472,226470054,190607562,247505996,193939540,33781468,222887919,233179866,205775320,64892233,64906060,196212367,206068833,168162048,21083152],"protos":[2003,2311],"timestamp":1710104643994,"game_mode_id":7}

← Returns

9864282  

Set Deck

This is used to set the current deck used in sealed. It's mostly a hold over from in the UI from the other modes where you can change decks. You can't actually give a deck id other than the one originally assigned when the session is created.

→ PUT gamemode.prod.prod.godsunchained.com/user/{guid}/session/{sessionid}/deck

• Requires
  • guid
    This is a players id in game. It can be retrieved through various methods.
  • sessionid
    This is the session id assigned to the current active sealed session. You can get this id from the "Get Sealed Sessions API" response.

Payload

{
    "deck_id": 9864282
}

← Returns

null  

Her hands, once busy with love's labor, teaching young minds,
In the chill of life's harsh winters, she was that warmth that binds.
A guardian angel, through struggles, she did veer,
In her eyes, a spark of kindness, in her voice, love clear.

Her life, a tapestry of courage, stitched with patience, thread by thread,
In her grandchildren, her spirit echoes, in every step ahead.
Though her presence now is missing, in hearts, she'll always dwell,
For in every act of kindness, her story I continue to tell.

Since this is the first post, this update will also contain a short summary of the project. Roughly 2 weeks ago, i decided i wanted to build a robot from Gods Unchained. This is something i used to do for fun, though, previously i had to stop building them due to time constraints.

The original plan was to build a glorified RC car, with a camera, self-balancing, and an android controller. However, with the ability, and expressed interest from outside parties in bidding for the robot. It's overall design evolved from an RC car, to a more "alive" design using a series of AI models to govern it's actions.

The current plan is to use an Nvidia Jetson Nano, potentially combined with an Intel Neural Compute Stick 2 to provide enough computing power to run YOLO, Urban Sound, and Gesture models in real time. Will also be adding a speaker, a mic, and some small 6v solar panels on the top of the robot.

Updates

1. Jetson nano base image has been updated to support the intel ncs2, was erroring on boot without first unplugging the ncs2. However a hotplug change seemed to resolve this! Now works rebooting without any issues.

2. New hardware showed up this week!

   • Raspberry PI 5
     Decided not to use this over the Jetson Nano, mostly due to power draw concerns. We want to keep the power draw as low as we can for battery life, and the PI 5 can draw up to 3 amps more than the Jetson Nano at full load.
   • USB Audio Dongle
     This is a simple dongle from Amazon by Adafruit. No issues, or quality problems with it.
   • Olympus ME-52W Microphone
     This is a microphone designed for recording audio in a room, it's often used in Olympus audio recorders which are common in corporate, and government environments due to there quality.

3. Work has started on 3d modeling the motor casing for the robot. Progress can be seen in the image below.

Goals

The main goals for next week are to bring the 3d modeling for the motor casing closer to completion. It would be great to have our first test prints by next stream, or the latest being the stream after next. I would also like to get the Jetson Nano image completed by next stream so that testing of the 3d models can begin. Ideally, we will need to monitor memory, and overall resource usage on the jetson with all 3 models running at once. This way if any resource problems arise we can start to plan for them early on!

That's it for this week. Make sure to check out my stream on Twitch every Saturday at 1pm - 5pm, or follow me on Twitter for more updates as the build progresses!

Microsoft .NET provides a host of ways to train, and consume AI models. This includes both online (azure), and offline (ml.net). By default all code samples will be utilizing CPU pipelines for maximum compatibility. However, if you have a modern GPU that supports CUDA you should be able to utilize GPU pipelines as well as CPU pipelines with minimal code changes.

Requirements

First we need to create an empty C# .NET 6 or higher project in your editor of choice (mine is often Visual Studio).

Next, we need to install the packages we require, in this tutorial that's only one package. You can install this using nuget console, or just searching out the package by name using manage packages in your ide.

Install-Package Microsoft.ML  

Models

Not to be confused with AI models, most modern programming paradigms also have a concept known as "models". These models are structures meant to represent how pieces of data look.

When working with AI models you will almost always need a minimum of two models.

1. A model that represents the structure of our input data.

public class InputData  
{
    [LoadColumn(0)]
    public string Text;

    [LoadColumn(1)]
    public string Label;
}

Note: LoadColumn specifies the order in which we intend the data to be in.

1. A model that represents the structure of our output data.

public class OutputData  
{
    [ColumnName("PredictedLabel")]
    public string Prediction { get; set; }
}

Note: ColumnName in our model also represents the column in the output data that we want.

Training

Model training requires data that matches our input structure we specified above. Normally this data is supplied through a data set that's often in the form of a spreadsheet, or database. This typically requires sanitizing, or shaping the data before it's use. However, in this article we will just be hard coding a training set of data for the purpose of education.

var data = new List<InputData>  
{
    new InputData { Text = "Hello", Label = "Greeting" },
    new InputData { Text = "Bye", Label = "Farewell" },
    new InputData { Text = "Can you check order", Label = "OrderStatus" }
};

Next, we need to load our data into a format that the Microsoft.ML pipeline can consume for training.

var context = new MLContext();  
var trainingData = context.Data.LoadFromEnumerable(data);  

Next, we need to fit, and train our model with the data we going to be giving it. Further, because pipelines are designed to be generic. We also need to set various settings letting the pipeline know what we are training, and finally which output columns we should be populating our results.

var pipeline = context.Transforms.Conversion.MapValueToKey(inputColumnName: "Label", outputColumnName: "Label")  
.Append(mlContext.Transforms.Text.FeaturizeText(inputColumnName: "Text", outputColumnName: "Features"))
.Append(mlContext.MulticlassClassification.Trainers.SdcaMaximumEntropy("Label", "Features"))
.Append(mlContext.Transforms.Conversion.MapKeyToValue("PredictedLabel"));

var model = pipeline.Fit(trainingData);  

Consuming

Finally, we can start testing our new model! We can do this by first creating an engine for our training model. In this case, a prediction engine.

var engine = context.Model.CreatePredictionEngine<InputData, OutputData>(model);  

Next, we can create a sample input and pass it to our model for classification (prediction).

var sentence = new InputData { Text = "Can you check order 12345?" };  
var intent = engine.Predict(sentence);

Console.WriteLine($"Text: {sentence.Text}");  
Console.WriteLine($"Intent: {intent.Prediction}");  

Lastly, we can see that our sentence contains an entity, or in this case an order number. Once we determine that the intent of the sentence to get the status of that order, we can then work on extracting that entity ourselves.

if (intent.Prediction == "OrderStatus") {  
    var orderIdRegex = new Regex(@"order\s(\d+)");
    var match = orderIdRegex.Match(sentence.Text);
    if (match.Success)
    {
        Console.WriteLine($"Entity: {match.Groups[1].Value}");
    }
}

This is a basic explanation of how this might work in an intelligent application.

Intent

When you receive text you need to parse the biggest question will always be, "What is the intent of this message?". This can be further compounded when multiple intents are expressed in the same message as, "What are all of the intents of this message?". Especially when speaking through speech to text were we often try and cram as much information as we can in a short period of time.

The illustration above shows extracting multiple intents from a single message. The first intent is a greeting. This indicates a polite person with a positive mood, it might mean returning a greeting in response. The second intent is the actual purpose of the message. In this case someone is requesting a status update for an order.

Entities

Once you have established intent for a message. You might find that you need to extract more detailed information that should otherwise exist. This might be an email, url, social handle, number etc.. These bits of information only have a clear meaning when attached to there supposed intent.

This illustration shows that the message has given us a "greeting" and is looking for an "order status" update. This establishes the intent of our message. The second intent, which is also the primary purpose of the message, and contains 2 parts of information we might need.

1. The first is a number which because we know the intent is to get a status update for an order, this number should be our order id.

2. The second part of the information is the location of that order. In this case the message is saying on a website we should know about.

Events

Mapping a series of intent's to an event is a common way of dealing with "What to do" once you have extracted the intention of a message with it's corresponding entities. This can be done by tagging each intent with an easy to understand name which also represents the method(s) that should trigger when the matching intent is found.

The first intention we have found can be labeled as a "Greeting". This can be mapped to an "OnGreet" event which selects a proper greeting based on the current time of day. Such as, "Good morning", "Good afternoon", or "Good evening".

The second intention we have found can be labeled as "OrderStatus". This can be mapped to an "OnOrderStatus" event which then checks the matching API, using the extracted entities found in the intent. Then constructing a response with the correct order status information, or an error if the order, or status can't be found.

Steam Deck

The steam deck is a powerful, by default Linux based handheld gaming system released by Valve. The price (at the time of writing) can range from $399 to $649. There is also likely a wait time before shipment as there just being released.

To me, the most powerful thing about the steam deck, is the fact that SteamOS is actually just Archlinux with Valve/Steam's logo on it. More importantly we have full root access to OS out of the box! Bravo Valve!

Gods Unchained

Gods Unchained is a blockchain based trading card game from Immutable. Currently, you can only play Gods Unchained on a PC, Mac, or Linux (unofficial support). You can read more about the game here. I highly recommend you check it out if you like trading card games!

Below are the steps required to install gods unchained on the steam deck using steam, and proton 7. Please note that while this "can" be done using the virtual keyboard in desktop mode. This method WILL NOT be covered here. Instead, the steam deck charge power also doubles as a USB-C hub. It's assumed that you have connected a mouse + keyboard.

Desktop Mode

The steam deck has 2 modes. Desktop Mode, and Game Mode. By default the steam deck will boot in Game Mode. In order to enter Desktop Mode you need to:

1. While running in Game Mode. Hold down the power button for 2 - 3 seconds. This will open a menu on the steam deck.
2. Navigate to Switch to Desktop. This will cause the steam deck to reboot into a windows looking desktop.

On the desktop you will see an icon labeled "Return to Game Mode". You can click on this to return to previous mode you where in. If you have not yet connected a keyboard to the USB-C power port using a USB-C hub, you should do so now.

Download Immutable

By default the steam deck comes with Firefox installed. You can also install Chrome. Ideally you can install which ever browser you plan to use Metamask, or another browser extension with in order to access the Immutable X market place. Both browsers can equally be added as a "non-steam" application for use in Game Mode.

1. Open a web browser, and navigate to godsunchained.com.
2. Click the Play Gods Unchained button, and download the Immutable exe to your downloads folder.
3. You may wish to search for "gods unchained logo" using an image search in the browser of your choice while you download. You may need it, and a background image later for steam launcher.

Install Immutable

You can install immutable, and most applications in steam as non-steam games. This is a two step process that requires first adding the installer, then, removing it. Then adding the exe that was just installed onto your steam deck with the installer as it's own non-steam game.

1. Open Steam, it's icon should be located on the desktop next to the Return to Game Mode icon.
2. In the bottom left of the steam interface, click the Add Game button. Scroll to the Add Non-Stream Game option in the menu.
3. Click Browse in the Add Game interface. Then navigate to the Immutable exe in your downloads folder located at /home/deck/Downloads.
4. Click Add Selected Program at the bottom of the Add Game interface.
5. Navigate to the steam library in steam. Library -> Home and search for "Immutable" you should see the immutable exe you added before.
6. Right click the exe in the library and select Properties.
7. Click the Compatibility tab on the left hand side.
8. Check off "Force the use of" option.
9. Select Proton 7.0-N where N is the larger number in the list for 7.0. Other versions may work but this is the only version I have tested.
10. Close the Properties window using the X in the upper right. Then click the Play button for the Immutable exe in your steam library.
11. Follow the install steps, do not change any paths during install, just use the defaults provided by the installer.
12. Once the installer completes and your at the login screen. Close the Gods Unchained application clicking the X in the upper right corner. While you shouldn't have any issues playing from here, it's unlikely to save your login information while still using the installer thread.
13. Right click on the Immutable installer in the steam library and select the remove non-steam game option. You don't need the installer anymore.

Note: Your screen may flicker, or flash while the Gods Unchained login screen is loading the Palis animation for the first time. It's unknown if this is Proton, or the steam deck causing this, however, if you just wait, it will self correct. This is also true for the first run in Game Mode.

Add Gods Unchained

Now that gods unchained is installed! We need to tell steam where it's located. We can then tell steam which version of proton to use, optionally which icon, and background image to use, and then finally, play!

1. If you closed steam before. You will need to reopen it. It's icon should be located on the desktop next to the Return to Game Mode icon.
2. In the bottom left of the steam interface, click the Add Game button. Scroll to the Add Non-Stream Game option in the menu.
3. Click Browse in the Add Game interface. Then navigate to the Immutable launcher exe in your steam folder located at: /home/deck/.local/share/Steam/steamapps/compatdata/4117854237/pfx/drive_c/users/steamuser/AppData/Local/Programs/immutable-launcher/immutable.exe.
   Note: The numbers in the path above are randomly created at the time install. They won't be the same as what's above. You can sort the compatdata folder by date/time to help locate which numbered folder contains the launcher you installed.
4. Click Add Selected Program at the bottom of the Add Game interface.
5. Navigate to the steam library in steam. Library -> Home and search for "Immutable" you should see the immutable launcher exe you added before.
6. Right click the exe in the library and select Properties.
7. Click the Compatibility tab on the left hand side.
8. Check off "Force the use of" option.
9. Select Proton 7.0-N where N is the larger number in the list for 7.0. Other versions may work but this is the only major version I have tested.
10. If you downloaded an icon before you now navigate to the Shortcut Tab and change the game icon. You may wish to do this even if you did not download a logo as you can also change the Shortcut name from Immutable to "Gods Unchained".
11. Close the Properties window using the X in the upper right.
12. If you downloaded a background image. Right click on the grey space in the library with the Gods Unchained (or Immutable if you did not rename it) application and select "Set Background Image".
13. Exit steam in desktop mode. Then click the Return to Game Mode icon. While you can play in Desktop Mode, ideally, you do not want too.

You should now see Gods Unchained (or Immutable if did not rename) in your Stream Library, and your Recent Games list in Games Mode. Steam will not record time played in this mode :( but you can still use the steam overlay, and chat with friends while in game.

You can use the touch screen to play!

There are some minor issues:

1. 50% of the time holding down your finger on a card in your hand, or on the board will show the popup showing what that card is, and 50% of the time it will do nothing at all.
2. The options, and report bug buttons at the upper right are very hard to click with your finger.
3. Mana pips can some times take a few taps to trigger due to there small button size. All, in all however, the game is extremely playable with little to no lag with High settings.

Facebook is a veritable giant in the AI modeling world. It has trained models to locate fringe, angry, and emotionally fragile people. Then, rather than remove, or help those people. They have decided it was best to experiment with them. To see how far they could manipulate these people into following, and interacting with content that they curated just for them. Further, they experimented with how long they could entice users to remain engaged with content of the same type. The content they where curating was not harmless. It was specifically curated to target emotions that AI models had detected in the previous groups of people that where easiest to stimulate into interacting with.

Basically, through extreme research, facebook found out you can get people who are on the fringe edges of society to click on content that validates, or re-enforces there world view. They, also, found out you can manipulate those same people into repeatedly click on content that continues to validate there views more aggressively if there are fewer sources outside of facebook that they can find the same level of re-assurance that they are not alone. That means, crazier the content. The more likely it was only on facebook, and that meant the people looking for re-enforcement from that type of content, would remain on facebook longer. The more people they could target, the more data they built up, and in turn, the more accurate the there ability to create curated content streams that can be interacted with for longer, and longer.

Regardless of why facebook was created, or what it offers us today. The main reason facebook now exists is to build a massive empire of data. The reason facebook is one of the worlds largest contributors to the artificial intelligence modeling in the world is because they needed advanced enough methods to harvest that much data. They want to target people with high enough accuracy that advertisers will pay them top dollar to have there ads placed with the highest chance for interaction. Regardless of what that interaction is! In the end, facebook is nothing more than a system for stimulating hate, fear, and depression because it's easy to make money.

Social media as a concept is not wrong. Companies, like facebook, who then use that information to target the easiest to manipulate among us, for profit! IS. NOT. RIGHT.