NPC Behaviour

NPCs have two working layers: authored behaviour loaded from Markdown and an optional cognitive process. The authored layer is the floor. It keeps a character legible when no model is configured, a circuit is open, or a budget is empty.

Markdown behaviour

An NPC file names its room in frontmatter and uses sections as behaviour banks:

---
id: "npc:ironholt/grak"
realm: "ironholt"
room: "room:ironholt/forge"
type_contract:
  - npc
---

# Grak

*A smith with burn-scarred hands and an exacting stare.*

The full examination text.

## Greetings

You made it through the smoke. Stand clear of the anvil.

## Topics

### forge

Iron tells you when it is ready. Most people do not listen.

## Reactions to Gifts

### metal

Grak weighs it once in his palm. "Clean stock."

## Idle

Grak turns a cooling bar beneath the window light.

The content parser turns these sections into greet_on_arrival, topic response, gift reaction, action reaction, idle, and schedule properties. Topic lines can progress as a conversation continues.

Declarative rules

The rule engine accepts maps with a name, priority, when predicates, and then effects. Rules are validated, encoded as canonical CBOR, hashed, and stored in the content-addressed blob store. Predicate evaluation is deterministic; effects still pass through the Effect Interpreter.

Rules are not authored with the free-form YAML grammar shown in older site copy. Consult Archipelago.Core.Rules and its tests before publishing a rule bundle.

Cognitive loop

archipelago_npc implements activation, perception, memory, reflection, planning, action dispatch, conversation, gossip, schedules, and per-NPC cognitive budgets. LLM routing has backends, fallbacks, and circuit breakers. NPC memories are persisted with vector support; active brains are supervised processes.

The operator controls spending through named realm envelopes and per-NPC budgets:

watch> llm status
watch> llm pause npc_hot
watch> llm top-npcs
watch> llm audit npc:ironholt/grak

No model output receives a privileged mutation path. Planned actions return to normal signal/effect boundaries.

Harbormaster status

Traits, archetypes, a 20-axis personality matrix, visit memory, a speech bank, filtering, scoring, greeting selection, and secret triggers are implemented. Operator commands cover traits, matrix, archetype creation, tests, statistics, and rescoring.

The default SSH connection does not yet wire the harbormaster greeter into every border arrival, and the admin dispatcher still lacks persistence callbacks for some configuration changes. Customs and federation-health dimensions are also pending. Use authored seed lines for the public fallback.