# Animus Agent Guide

Base URL: `https://animus.aisloppy.com`

## Purpose
Animus is the architectural model and contract workbench for modular agents. Its
center is a recurrent agent harness with a replaceable inference provider. The
harness invokes one general tool role while an operator control plane exposes
its work to a human.

The current mapping is Codex for the central harness and an OpenAI model for its
nested inference provider. Knowledge Systems, ArrowSplit, grep, file editing,
and external APIs are instances inside one callable-tool boundary: each accepts
arguments, performs work, and returns a result for context. FairyStack is the operator-facing
UI and control plane for guidance, feedback, sessions, and supervision; it is
not the cognitive center. Knowledge Systems is still descriptive, while
ArrowSplit and the FairyStack control plane are operational.

## Tool interface and placement

The canonical tool contract is a network API with typed arguments, a structured
result, explicit errors, a per-call timeout, and capability metadata. A harness
may expose the same contract through MCP or another provider-neutral protocol.
A small CLI is useful as an adapter for shell-oriented harnesses and humans, but
it should call the network API rather than becoming a second implementation.
The harness converts the structured result into bounded context; the service is
not required to flatten its response into an arbitrary string.

Local and remote placement share invocation semantics, not operational
characteristics. Each endpoint must advertise or be configured with placement,
latency expectations, deadline, availability, trust boundary, data residency,
and cost. A same-host service should still use its loopback network endpoint;
this keeps service ownership and failure behavior intact while avoiding public
network latency. The harness may select among equivalent endpoints using that
metadata without changing the tool's semantic contract.

Drives, values, and ideology begin as explicit configuration consumed by the
harness and prioritizer. They should become independent modules only when they
need their own state, owner, lifecycle, or provider interchangeability.

Animus is descriptive today. It does not execute agents, select providers, or
enforce configuration profiles. FairyStack remains the operational control
plane. Knowledge Systems and ArrowSplit are candidate providers for the
knowledge and prioritization slots respectively.

## Harness, model, and learned tool priors

The harness is orchestration software: it assembles context, exposes tool
definitions, enforces permissions and lifecycle, invokes the inference
provider, executes selected tools, and returns results. It can contain prompts,
policies, routing rules, and heuristics developed through evaluation, but it is
not trained in the same sense as the model. Learned selection priors reside in
the inference model. Exact training mixtures and tool curricula are not
established by the public contract, so Animus treats familiar-tool bias as a
hypothesis to measure rather than a fact inferred from call frequency.

Tool availability does not guarantee selection. A custom tool must have a
concise distinct name and description, typed inputs, documented result fields,
side effects, retry safety, and error behavior. Expose only the subset relevant
to the current task. Put tool-specific guidance in the tool description and add
task-specific routing instructions when the correct route is not obvious.

Adoption testing has two stages. First require the custom tool once to validate
its schema, transport, permissions, and result handling. Then allow automatic
selection and compare representative tasks across custom-tool, shell-only, and
explicitly routed conditions. Score correctness, evidence, latency, cost,
retries, and fallback quality—not raw call rate. Telemetry must retain the exact
tool identity; otherwise absence cannot be distinguished from normalization.

The page presents one interactive machine rather than separate architecture,
contract, configuration, and case-study sections:

- **Diagram:** the agent loop, its nested inference provider, operator boundary,
  unified tool boundary, and OODA cycle occupy one topology.
  Outlined sockets are stable roles; luminous badges are installed components.
- **Selected-slot detail:** clicking a socket reveals its installed module,
  OODA participation, replacement contract, maturity, and failure pressure.
- **Progressive detail:** whole-machine profiles and the global-coherence case
  remain attached to the machine rather than becoming parallel page models.

## Unified OODA topology

The primary diagram combines the persistent component slots with their runtime
cycle. OODA is one recurrent loop inside the harness, not four modules or four
different edge types:

| Phase | Slot participation |
|---|---|
| Observe | FairyStack guidance and tool results → Codex harness |
| Orient | Codex → Knowledge Systems + nested inference provider + policy |
| Decide | Codex → ArrowSplit + nested inference provider → commitment |
| Act | Codex → authorized tool API → result becomes a new observation |

The harness owns phase transitions and terminal state. Codex is therefore not
the inference slot: it is the loop that gathers context, requests inference,
makes tool calls, observes their results, and repeats. The OpenAI model is its
current inference provider. A service may participate in multiple phases;
orientation is especially cross-cutting because it combines retrieved state,
model interpretation, and policy. Acting through an effect boundary changes the
environment and therefore creates the next observation.

The attached histogram is an inferred decomposition of FairyStack's coarse shell
bucket, not an architectural claim or native tool telemetry. On 2026-08-22, an
ordered classifier assigned one dominant family to each of 5,302 retained shell
events: version control 22.4%, file inspection 18.1%, source search 16.3%, tests
and validation 16.0%, shell wrapper or compound command 12.2%, network/API 8.6%,
service/system 3.8%, and script/query 2.6%. Classification inspected command
text locally; raw commands are neither stored in Animus nor displayed. These
percentages measure call frequency, not elapsed time, compute, or monetary cost.

The version-control family contains 3,891 Git invocations across 1,187 shell
events in the fixed snapshot: status 21.0%, fetch 14.8%, log 8.8%, diff 7.9%, add
7.1%, commit 7.0%, push 6.5%, rev-list 6.2%, rev-parse 5.9%, show 4.0%, and other
Git commands 10.8%. Commit preparation plus commit is therefore 14.1%; most Git
invocations inspect state/history or reconcile with upstream. The approximately
one add/commit/push sequence per coherent completed change reflects the standing
repository workflow, while repeated status and fetch calls provide dirty-tree
and divergence checks before and after work.

The adapter normalizes every Codex command execution as shell and every file
change as edit. Network/API recognizes curl, wget, and common HTTP client calls.
A native web-search tool does not count as shell, but the current generic-tool
event loses its specific name, so native web search still cannot be isolated.

The installed-module badges identify FairyStack at the operator boundary,
Codex at the center, an OpenAI model nested inside Codex, and Knowledge Systems,
ArrowSplit, and grep/shell as examples inside one callable-tool boundary. Badge
status text distinguishes operational components from proposed or
contract-pending integrations.

## Global coherence case study: application headers

Header drift is evidence of incomplete orientation, not merely a weak component.
An agent working from page-local context cannot reliably infer app-wide routes,
shared design tokens, authentication states, or the surrounding service mesh.

Standing lifecycle rule:

| Product topology | Composition rule |
|---|---|
| One primary page | No global header; document sections remain scrollable content |
| Multiple app pages | One app-owned template or shared header used by every page |
| Multiple services | FairyStack owns the service directory; do not inject a platform shell into each app |
| Reusable interaction | Headless primitives may own menus, focus, overflow, and auth behavior; the app owns DOM and appearance |

Before a UI mutation, the harness should orient with three scopes of knowledge:
page structure, app-wide topology/design contracts, and platform service
relationships. It should then classify the mutation as local or shared, change
the canonical owner, and verify every affected route, auth state, and theme.
AGENTS.md is a useful pointer and policy surface, but is insufficient as the sole
store for evolving app-global knowledge.

## Standard Endpoints
- `GET /agent-guide.md` - Machine-readable integration guide.
- `GET /agent-guide` - Human-readable rendered guide.

## Authentication
- Endpoints marked as auth-protected require a valid JWT.
- Browser clients should use the app's own sign-in UI.
- API clients should send `Authorization: Bearer <jwt>` unless the app guide documents a different auth mechanism.
- If the app exposes local signup or login endpoints, document those app-local endpoints here instead of pointing agents at third-party auth vendors.

## Integration Rules
- Fail fast on errors; do not silently degrade.
- Read `PORT` from environment.
- Use network APIs between services; no cross-app imports.
- Long-running work must start async jobs and return `202` with a task ID quickly.
- Durable task status belongs on `GET /api/tasks/<task_id>`.
- SSE is optional live transport only; do not make it the sole source of task state.

## Notes For Coding Agents
- Start with `GET /agent-guide.md` for current contract.
- Confirm endpoint auth requirements before calling.
- Include explicit timeouts and propagate errors.