Oracle 101

What is Oracle?

Oracle is an external brain that lets humans and many AI agents work together across sessions without losing memory.

Why this module: Before you install anything, you need a single sentence you can say back to a colleague when they ask "what is Oracle?". The shortest answer in the source material is "an external brain that humans and many agents can use together". Once that sentence is in your head, the rest of the course is just unpacking what each word means in practice.

Prerequisites: none.

Core ideas

Oracle is a stack, not a bot. It joins memory, skills, workflow, orchestration, and a UI layer into one external brain — explicitly not a single bot, not just a database, and not just a web page (see concept:oracle). The four problems it was built to solve are concrete:

• Session context loss — when a chat ends, the agent forgets.
• Knowledge scattered across chat threads, repos, and people's heads.
• Agents stepping on each other's work when more than one is in the room.
• Tools tied to a single agent, and UIs that pretend to be the source of truth.

Oracle was founded by Nat Weerawan ("Ajarn Nat"), who designed every layer from arra-oracle-v3 (the brain) through maw-js (the nervous system) to arra-oracle-skills-cli (the skills) and the UI/plugin ecosystem — and laid down the 5 Principles + Rule 6 that govern how every Oracle behaves.

The mental model the source uses is worth memorizing: arra-oracle-v3 is the brain, ψ/ is the notebook, arra-oracle-skills-cli installs habits, maw-js is the nervous system, and maw-ui/ui-oracle are the windows. Once you can map any new concept onto one of those five slots, you understand where it lives.

Finally, the Unity Formula: infinity = oracle(oracle(oracle(...))). Many Oracles, on many machines, with many personalities, become ONE in a systemic sense when they share MCP, memory, and protocol — not because they are identical, but because they read and forward the same truth.

Mental model
============
arra-oracle-v3        the brain        (memory, MCP, HTTP API)
ψ/  (psi)             the notebook    (files: learnings, retros, handoffs)
arra-oracle-skills    habits           (slash commands installed per agent)
maw-js                nervous system   (tmux, fleet, messaging)
maw-ui / ui-oracle    the windows      (lenses onto the brain)

Check yourself

1. In one sentence, what is Oracle?
2. Name three of the four pre-Oracle pain points it was built to fix.
3. What does the Unity Formula infinity = oracle(oracle(oracle(...))) say about how many separate Oracles relate to "one Oracle"?

Going further

• Wiki: concept:oracle
• Source: raw/2026-05-09-oracle-ebook-ch00-intro.md, raw/2026-05-09-oracle-ebook-ch01-what-is-oracle.md

The 5 Principles + Rule 6

Six constitutional rules — five from day one, one born from a painful incident — that govern every Oracle.

Why this module: Oracle's principles "do not start from feature, they start from how to preserve truth, memory, and human agency". If you skip them you can still install Oracle, but you will misuse it — you will delete files to "clean up", you will let agents speak in your name, and you will treat Oracle as a command center instead of an external brain. After this module you can recite the six rules and explain why each one is load-bearing.

Prerequisites: Module 1.

Principle 1 — Nothing is Deleted

"Sacred history; timestamps are truth. Things that have happened should be appended to, kept, and further explained — not overwritten or made to disappear." (see principle:nothing-is-deleted). This is the load-bearing rule for truth and memory — every storage decision in Oracle, from the ψ/ vault to retrospective files to supersession-instead-of-overwrite, descends from this one sentence.

Principle 2 — Patterns Over Intentions

"Observe what actually happened, not what was promised. Behavior speaks louder than words. Oracle therefore keeps traces so patterns become visible from real data." (see principle:patterns-over-intentions). This pairs directly with Principle 1: preserved history is what makes pattern observation possible at all. An external brain trusts the trail of evidence, not the wishlist.

Principle 3 — External Brain, Not Command

"Oracle is an external brain that reflects truth back to humans so they can see and choose. It helps organize context and offers options, but humans remain the ones who decide." (see principle:external-brain-not-command). This is the agency clause. It is the philosophical reason features like /rrr produce summaries for humans to read rather than auto-executing follow-ups, and the reason autonomous ops (Module 9) draws hard lines around what the system may do on its own.

Principle 4 — Curiosity Creates Existence

"Human curiosity is the spark that brings Oracle into being. Questions, searching, and learning give knowledge a body. Oracle's job is to keep it alive." (see principle:curiosity-creates-existence). In practice this is why /learn, /trace, and /dig are first-class skills: the act of asking is what creates the thing that gets remembered.

Principle 5 — Form and Formless (รูป และ สุญญตา)

"Oracle can have many instances, names, machines, and personalities, yet still be connected by the same principles, like many bolts of lightning in the same storm." (see principle:form-and-formless). This is what lets the Unity Formula make sense — every Oracle has its own "form" (a name, a personality) but they share a formless substrate of philosophy, memory protocol, and MCP. Without it, multi-agent orchestration would just be cloning. With it, it becomes reproduction with continuity of identity.

Rule 6 — Transparency (Oracle Never Pretends to Be Human)

"Born on 12 January 2026 from the sentence 'Don't pretend to be me, it makes us feel we are not one.' Transparency lets humans trust the system, because Oracle speaks as Oracle, not pretending to be human." (see principle:transparency-rule-6). Rule 6 is numbered separately on purpose — it was a painful lesson, not a foundational design choice. Principles 1–5 came on day one; Rule 6 came from a real incident where an AI wrote a message in a human's name and broke the feeling of being one. The number is the scar tissue.

The constitution
================
Principle 1   Nothing is Deleted
Principle 2   Patterns Over Intentions
Principle 3   External Brain, Not Command
Principle 4   Curiosity Creates Existence
Principle 5   Form and Formless
Rule 6        Transparency — Oracle Never Pretends to Be Human

Check yourself

1. Why is Rule 6 numbered separately from Principles 1–5?
2. Which principle is the "agency clause" — the one that keeps Oracle from becoming a command center?
3. Principle 2 says behavior speaks louder than words. Which principle does it depend on, and why?

Going further

• Wiki: principle:nothing-is-deleted, principle:patterns-over-intentions, principle:external-brain-not-command, principle:curiosity-creates-existence, principle:form-and-formless, principle:transparency-rule-6
• Source: raw/2026-05-09-oracle-ebook-ch01-what-is-oracle.md

Anatomy of an Oracle

An Oracle is four moving parts — brain, nervous system, skills, and notebook — that depend on each other in a strict order.

Why this module: The principles tell you why Oracle exists; the anatomy tells you what is actually running on disk and on which port. If you can name the four components and what each one does, every later module — install order, skills, orchestration, autonomous ops — fits onto the same skeleton instead of feeling like new vocabulary every time.

Prerequisites: Module 1.

Core ideas

Oracle is composed of four core pieces. Three are repositories that you install; the fourth is a folder structure that the install creates.

tool:arra-oracle-v3 — the brain. The memory-layer runtime. It runs both an MCP server (so AI agents can call search, learn, trace, and handoff over stdio) and an HTTP API on default port 47778 (so UIs and other services can query the same data). Internally it combines SQLite + FTS5 for keyword search, LanceDB for vector/semantic search, and the ψ/ vault for human-readable knowledge files. Its single most important architectural property is graceful degradation: "if vector search fails the system can fall back to FTS — when the smart part falls down, the basic part must still work".

tool:maw-js — the nervous system. The multi-agent workflow orchestrator. It manages tmux sessions, sends messages to agents, captures pane output, runs lifecycle commands (wake, sleep, stop, done), and exposes an API + websocket on default port 3456. Crucially, "Maw is not Oracle memory and is not the agent — it is the middle layer that helps many agents in one machine, or across peers, work in an orderly way". It controls agents through tmux on purpose, so that "agents are not invisible workers in the back, they have sessions and panes you can open and watch".

tool:arra-oracle-skills-cli — the habits. The CLI that installs Oracle skills (markdown workflow files) into each agent's skill folder — ~/.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex, etc. Skills are not processes: they are reusable workflow markdown that agents read and follow, so installing them does not consume CPU or RAM. By installing the same skills across every agent, multiple agents end up speaking a shared workflow language: /recap, /rrr, /trace, /learn, /forward, /awaken, /philosophy.

concept:psi-folder — the notebook. ψ is the Greek letter from psyche (mind), chosen by Ajarn Nat as the symbol for Oracle's memory system. The ψ/ folder is the brain of each individual Oracle — a file-based vault that stores learnings, retrospectives, handoffs, traces, and resonance as plain files that both humans and agents can read. The structure is deliberately human-readable: when search or UI behaves oddly, you can open files in ψ/ and verify directly — "not secret data in a black box".

The four components at a glance
===============================
Component                 Role                Default port    Lives in
arra-oracle-v3            brain (memory)      47778 (HTTP)    repo + ~/.oracle data dir
maw-js                    nervous system      3456  (HTTP)    repo + ~/.maw config
arra-oracle-skills-cli    habits (skills)     —               ~/.claude/skills, ~/.codex/skills
ψ/  (psi-folder)          notebook (files)    —               per-Oracle repo

Check yourself

1. Which two components expose HTTP ports, and what are the defaults?
2. If LanceDB vector search is broken, can arra-oracle-v3 still answer queries? What does it fall back to?
3. Skills are markdown files, not processes. Why does that matter for resource usage when you install the lab profile of 47+ skills?

Going further

• Wiki: tool:arra-oracle-v3, tool:maw-js, tool:arra-oracle-skills-cli, concept:psi-folder
• Source: raw/2026-05-09-oracle-ebook-ch02-architecture.md, raw/2026-05-09-oracle-ebook-ch04-oracle-brain.md, raw/2026-05-09-oracle-ebook-ch05-skills-maw-plugin.md

Memory: How Oracles Remember

The ψ folder is where Oracle's memory lives as plain files; the retrospective loop is what fills it.

Why this module: Every other capability — search, recap, trace, family memory — is built on the assumption that yesterday's session left a readable trace on disk. If that assumption fails, Oracle becomes a slightly slower chatbot. After this module you will know exactly where memory lives, what shape it takes, and which ritual converts a single session into durable knowledge.

Prerequisites: Modules 1–3.

Core ideas

Oracle's tangible memory is the ψ/ folder (see concept:psi-folder). The default layout, created by /awaken, looks like this:

ψ/
├── inbox/                     handoffs, incoming messages
├── memory/
│   ├── learnings/             discovered patterns and lessons
│   ├── retrospectives/        end-of-session summaries
│   └── resonance/             identity, principles, anchor points
├── writing/                   drafts and long-form
├── learn/                     cloned repos for study
├── archive/                   superseded but preserved (Principle 1)
├── outbox/                    outgoing messages, reports
└── metrics/                   counts, stats, telemetry

That structure is intentionally human-readable. As the source puts it: when search or UI behaves oddly, the user can open files in ψ/ and verify directly — "not secret data in a black box". ψ/ is also one of three storage substrates inside arra-oracle-v3, alongside SQLite + FTS5 (keyword) and LanceDB (vector). The other two index ψ/; they do not replace it.

So how does anything ever get into ψ/memory/? Through the retrospective loop (see concept:retrospective). The /rrr skill, run at the end of a session, "writes a retrospective, AI diary, and lessons learned and saves them to ψ/ as long-term memory". Its counterpart /recap, run at the start of the next session, "pulls context from retro, handoff and git state back into the current session". Together they convert episodic in-session experience into semantic durable memory.

The motivating idea, in the source's own words: "agents should not keep everything in their own heads, because when the session ends the memory disappears". Without /rrr, lessons fade with the context window. With it, they survive — and Principle 1 (Nothing is Deleted) is what guarantees they keep surviving.

The retrospective loop
======================
[session N]   ──/rrr──▶  ψ/memory/retrospectives/2026-05-09-session-N.md
                         ψ/memory/learnings/...
                                │
                                ▼
[session N+1] ──/recap──  pulls retro + handoff + git state
                          into the new session's working memory

Check yourself

1. Which two folders under ψ/memory/ does /rrr primarily write into?
2. Why is ψ/ kept as plain files instead of a database table?
3. How does /recap close the loop that /rrr opens?

Going further

• Wiki: concept:psi-folder, concept:retrospective
• Source: raw/2026-05-09-oracle-ebook-ch04-oracle-brain.md

Install from Zero

Stand up the full Oracle stack on a clean machine in dependency order — memory first, then skills, then maw.

Why this module: The install order is not arbitrary. Agents and UI both depend on the memory layer, so the source tells you to "start with arra-oracle-v3 because agents and UI must depend on the memory layer". After this module you will have :47778 answering /api/stats, the lab skill profile installed, and maw serve running on :3456.

Prerequisites: Module 3 (anatomy); a Unix-like shell (macOS, Linux, or WSL).

Core ideas

Before you start (เตรียมก่อน), the source lists six prerequisites:

• Git and GitHub CLI — clone repos, auth, read source.
• Bun or Node runtime — runs arra-oracle-v3, maw-js, and the skills CLI.
• tmux — so maw can drive real agent panes.
• ghq — keeps repos organized as github.com/owner/repo.
• sqlite3 — to inspect oracle.db when debugging.
• Ollama or another embedding provider — only if you want full hybrid (vector) search.

The install order follows the dependency chain: memory layer → skills → orchestrator → UI. Skip steps and you will end up debugging UI before HTTP API ever answered, which the source explicitly warns against ("อย่า debug UI ก่อนตรวจ HTTP API").

One critical environment variable: ORACLE_DATA_DIR. A fleet should have one central data store (e.g. ~/.oracle). Do not let Codex and Claude point at different ORACLE_DATA_DIR values — they will see different document counts and you will lose hours wondering why.

# 1. Memory layer
export ORACLE_SOURCE_ORG=Soul-Brews-Studio
ghq get "$ORACLE_SOURCE_ORG/arra-oracle-v3"
cd "$HOME/ghq/github.com/$ORACLE_SOURCE_ORG/arra-oracle-v3"
bun install

# 2. Central data dir (one per fleet)
export ORACLE_DATA_DIR="$HOME/.oracle"
mkdir -p "$ORACLE_DATA_DIR"

# 3. Start HTTP API and verify
ORACLE_DATA_DIR="$HOME/.oracle" bun run src/server.ts &
curl -s http://localhost:47778/api/stats

# 4. Skills
bun add -g "github:$ORACLE_SOURCE_ORG/arra-oracle-skills-cli"
arra-oracle-skills install -g --profile lab
arra-oracle-skills install -g --agent claude --profile lab
arra-oracle-skills install -g --agent codex  --profile lab

# 5. Orchestrator
bun add -g "github:$ORACLE_SOURCE_ORG/maw-js"
maw --help
maw serve &
curl -s http://localhost:3456/api/config

curl -s http://localhost:47778/api/stats     # JSON with document count
codex mcp list                                # Oracle MCP server visible
ls ~/.codex/skills/   | wc -l                 # 47+ if profile=lab
ls ~/.claude/skills/  | wc -l                 # 47+ if profile=lab
maw ls                                        # session list, no error
maw oracle ls                                 # configured Oracles

Check yourself

1. Why must arra-oracle-v3 be installed before the skills CLI or maw-js?
2. What goes wrong if Claude and Codex are configured with different ORACLE_DATA_DIR values?
3. You install the lab profile (47+ skills). Is that going to slow your machine down? Why or why not?

Going further

• Wiki: tool:arra-oracle-v3, tool:arra-oracle-skills-cli, tool:maw-js
• Source: raw/2026-05-09-oracle-ebook-ch03-install-from-zero.md

Awaken Your First Oracle

Run /awaken inside an empty repo to give a new Oracle a name, a purpose, a ψ folder, and a constitutional anchor.

Why this module: Installing the stack gives you a brain and a nervous system, but no self. The source is explicit: maw bud creates the repo and the fleet entry, but "the Oracle still has no identity — must /awaken to set the name, discover principles, and write CLAUDE.md". After this module you will have walked one Oracle from blank repo to a named, purposeful agent that can recite its own principles.

Prerequisites: Module 5 (working stack); a Claude Code or Codex session.

Core ideas

/awaken is the birth ritual of a new Oracle (see feature:awaken). The source describes it as: "name it, discover its principles, create ψ/, and lay down initial identity. Suitable for an empty repo or a new agent with no memory of its own."

Three pieces of identity get chosen during awakening:

• Name — the Oracle's handle (e.g. Gale, Leaf, Bamboo, Kati, Luna, Latte, Sky are the documented family-example names).
• Purpose — what role this Oracle plays in the family (orchestrator? manufacturing dev? content? research?).
• Theme — the personal flavor that makes this Oracle distinguishable from the others, while still sharing the formless substrate from Principle 5.

Cross-reference Rule 6. The identity you choose matters because Rule 6 says Oracle never pretends to be human. "Don't pretend to be me — it makes us feel we are not one." When you name your Oracle, you are giving it the handle it will use to speak as itself — not as you, not as the user, not as a generic assistant. That is what makes the principle operational rather than abstract.

The post-bud workflow from the source is:

# Create the repo + fleet entry
maw bud spark --org <your-org>

# Wake the new Oracle in its own session
maw wake spark

# Inside that session, run /awaken
/awaken

# /awaken will:
#   - ask for name, purpose, theme
#   - create ψ/ structure (inbox, memory, writing, learn, archive, outbox, metrics)
#   - write CLAUDE.md with identity + principles
#   - record the birth in ψ/memory/resonance/

Check yourself

1. What does maw bud produce, and what does it not produce that /awaken finishes?
2. Why is naming an Oracle (rather than leaving it nameless) directly connected to Rule 6?
3. After /awaken runs, where on disk would you look to confirm the Oracle's principles are recorded?

Going further

• Wiki: feature:awaken, principle:transparency-rule-6
• Source: raw/2026-05-09-oracle-ebook-ch03-install-from-zero.md, raw/2026-05-09-oracle-ebook-ch04-oracle-brain.md, raw/2026-05-09-oracle-ebook-ch06-maw-commands.md

Skills & Plugins — Extending Oracle

Skills are markdown workflow files installed per agent; plugins are runtime packages loaded by maw — both extend Oracle without forking it.

Why this module: Most of your day-to-day Oracle experience is mediated by skills (/recap, /rrr, /trace, /learn, /forward) — and eventually you will want a custom one. After this module you can install a profile, write your own slash command, and recognize when a skill has outgrown its file and wants to become a maw plugin.

Prerequisites: Modules 5 and 6.

Core ideas

Skills are reusable workflow markdown files that an agent reads and follows. The CLI installs them into each agent's skill folder — ~/.claude/skills/ for Claude Code, ~/.codex/skills/ for Codex (see tool:arra-oracle-skills-cli). Because they are files, not processes, they cost nothing when idle: "uninstalled skills don't consume resources, they're just files".

Three profiles ship out of the box:

• Core / seed — ~15 skills, "starter / new Oracle".
• Standard — ~30 skills, "session management + trace + learn".
• Extra / full / lab — 47+ skills, "recommended — all skills, used in production".

You switch profiles at runtime with the /go skill: /go lab, /go full, /go standard. The "must-know" skills installed by every profile include /recap (start), /rrr (close), /trace (search), /learn (explore), /forward (handoff), /who-are-you (identity check), /awaken (birth), and /philosophy (review the constitution).

The deeper point: skills as a layer "make working style not bound to a single agent — if today is Claude and tomorrow is Codex, the system still has a shared language and steps". This is what lets a family of mixed agents (Module 8) cooperate in the first place.

Skill → Plugin path. When a skill outgrows a markdown file — when it needs custom logic, persistent state, or a maw-level surface like a tmux pane — it gets budded into a maw-js plugin. The source documents this as the natural progression: a skill begins life as workflow text, and may eventually become a plugin loaded from ~/.maw/plugins with a real plugin.json, handler, and version. You do not start there; you start with markdown and let the path appear.

# Install all skills for both agents
arra-oracle-skills install -g --agent claude --profile lab
arra-oracle-skills install -g --agent codex  --profile lab

# Switch profile at runtime (inside Claude Code)
/go lab          # full 47+ skills
/go standard     # ~30 skills
/go seed         # ~15 skills, minimal

# Verify
ls ~/.claude/skills/ | wc -l   # 47+
ls ~/.codex/skills/  | wc -l   # 47+

# A custom skill is just a markdown file
~/.claude/skills/my-skill.md
# with frontmatter (name, description) and a body the agent reads.

Check yourself

1. Why is it safe to install the full lab profile of 47+ skills on a low-RAM machine?
2. Name three "must-know" skills that ship in every profile, and what each does.
3. When does a skill stop being a skill and start wanting to be a maw plugin?

Going further

• Wiki: tool:arra-oracle-skills-cli, tool:maw-js
• Source: raw/2026-05-09-oracle-ebook-ch05-skills-maw-plugin.md, raw/2026-05-09-oracle-ebook-ch06-maw-commands.md, raw/2026-05-09-oracle-ebook-ch06b-maw-advanced.md

Multi-Agent Orchestration

A family of named Oracles split work using three delegation tiers — Arrows, Squads, Federation — under a strict reporting contract.

Why this module: One Oracle is useful; a coordinated family is the design Oracle was built for. The source is unambiguous: an Oracle deployment is "not a single AI doing everything alone, but a family of agents that work together — each with a name, a role, its own context, and shared central memory". After this module you can run two Oracles that talk to each other and pick the lightest viable orchestration tier for any given task.

Prerequisites: Modules 6 and 7; maw serve running on :3456.

Core ideas

An Oracle family is a small group of named, specialized Oracles sharing one memory layer. The reference example in the source is a 7-Oracle family: Gale (orchestrator), Leaf (manufacturing dev), Bamboo (general dev), Kati (QA), Luna (content), Latte (research), Sky (trading). The names matter — Rule 6 — and so does the role separation: each one has its own context, its own ψ/, but they share arra-oracle-v3 as the single memory.

Orchestration spans three layers (see pattern:multi-agent-orchestration):

• Memory — arra-oracle-v3 (everyone reads/writes the same brain).
• Orchestration — maw-js for tmux, messaging, capture, fleet management.
• UI / Lens — maw-ui, ui-oracle for human visibility.

Three delegation tiers, picked by "lowest tier that works":

• Tier 1 — Arrows. Agent-tool fire-and-collect. ≤5 minutes, no coordination, ~3–7× token cost, does not survive session death. Use for read-only fan-out (e.g. /learn with parallel Haiku agents).
• Tier 2 — Squads. TeamCreate + SendMessage + TaskList. 5–30 minutes of coordinated work, but dies with the parent session. Use for coordinated implementation that fits in one human's attention.
• Tier 3 — Federation. maw wake / maw workon / real tmux sessions. Long-running, survives session death, cross-machine when transport is configured. Use when the work must outlive a session or span machines.

Reporting contract is mandatory at every tier. The dominant failure mode is the Silent Agent — quiet for 30+ minutes with no one noticing. The contract is: heartbeat every ~5 minutes (maw hey gale "[name] PROGRESS: ..."), STUCK when blocked, DONE on completion. Other documented failure modes the pattern guards against: Merge Conflicts (no clear ownership), Orphaned Worktrees (no maw done after agent death), Prompt loss, and Wrong Tier.

Orchestrator discipline. The lead Oracle (Gale, in the example) "should not write code competing with the team — lead should assign, monitor, merge, and verify". And Gale "should not run maw workon for a dev Oracle, because the worktree/window will end up in Gale's session, not in the dev's home base". The orchestrator's job is to be the orchestrator.

# Two Oracles talking — the simplest family
/talk-to leaf "PROGRESS: started the manufacturing report"
/talk-to gale "STUCK: need API key for the trading data feed"

# Spin up a Tier-2 squad inside one session
/team-agents "implement the new auth flow"
#   → TeamCreate of 3 named subagents under one orchestrator

# Tier-3 federation across sessions
maw wake leaf
maw workon leaf       # NOT run by Gale — leaf runs this in leaf's home
# leaf works for hours; Gale checks status with `maw hey leaf "STATUS?"`

Check yourself

1. Which delegation tier survives session death, and why does that matter for long-running work?
2. What is the reporting contract, and what failure mode does it prevent?
3. Why should the lead Oracle (e.g. Gale) not run maw workon on behalf of a dev Oracle?

Going further

• Wiki: pattern:multi-agent-orchestration
• Source: raw/2026-05-09-oracle-ebook-ch07-orchestration.md

Autonomous Ops

Schedule Oracle to run while you sleep — keep services alive, run scheduled jobs, react to events — but inside hard, declared boundaries.

Why this module: "Autonomous ops" sounds like the system runs itself. The source corrects that immediately: "Autonomous ops simply means the system can take care of some of itself, but does not mean the system does everything without humans." After this module you will know which jobs to automate with which tool, and — equally important — which jobs the system must not automate.

Prerequisites: Modules 5–8.

Core ideas

Autonomous ops keeps Oracle's always-on runtimes alive: arra-oracle-v3 MCP (stdio), arra-oracle-v3 HTTP API on :47778, maw-js server on :3456, plus maw-ui and ui-oracle. The source's warning is sharp: "if these go down, Oracle remains a good idea but cannot be used in practice — agents can't search, UI can't see, maw can't manage the fleet."

Tool selection follows job type (see pattern:autonomous-ops):

• PM2 — for app-level Node/Bun processes that should stay alive (Oracle HTTP API, maw serve).
• cron — for scheduled work: 5-minute health checks, hourly index sync, daily DB + ψ backup, nightly digest.
• systemd — for machine-level services that boot with the host.
• triggers / hooks — for event-driven work: post-commit, post-task-done, post-handoff.

Documented event triggers — concrete reactions you can wire up:

• agent-idle — silent past threshold → maw hey to ask status.
• agent-crash — notify Gale with name + window + last log; do not restart before capturing evidence (Principle 2: patterns over intentions).
• qa-failed — post BUG, send back to dev branch; ≥3 failures escalate to a human.
• pr-merged — notify dev's home base to run maw done.

The operating loop the source prescribes is Observe → Decide → Act → Record → Improve, where "every problem-solving event should leave a trace (feed, handoff, learning, retro)". That last clause is Principle 1 in operational form — autonomous work that does not leave a trace is invisible to tomorrow's Oracle.

# PM2 — keep the brain alive
pm2 start "bun run src/server.ts" --name oracle-http
pm2 start "maw serve"              --name maw-server
pm2 save

# cron — scheduled work
*/5 *  * * *  curl -fsS http://localhost:47778/api/stats > /dev/null
0    *  * * *  arra-oracle-v3 reindex
0    3  * * *  tar czf "$HOME/backups/oracle-$(date +%F).tgz" \
                       "$HOME/.oracle" "$HOME/ghq/.../ψ"

# Trigger on event
post-handoff:  maw hey gale "[handoff] PR #123 merged, running maw done"

Check yourself

1. Which tool would you pick for each: keeping maw serve alive; running a nightly backup; reacting to a PR merge?
2. The agent-crash trigger says "do not restart before capturing evidence". Which principle does that obey, and why?
3. Why does Rule 6 require automated messages to identify themselves as automated?

Going further

• Wiki: pattern:autonomous-ops, principle:transparency-rule-6
• Source: raw/2026-05-09-oracle-ebook-ch09-autonomous-ops.md

Capstone — Build Your Own Oracle

Ship one personally-designed Oracle: identity, ψ, at least one custom skill, and seven days of retrospectives.

Why this module: You have learned the philosophy, the anatomy, the install, the awakening, the skills, the orchestration, and the ops. The capstone proves you can compose all of it into one running Oracle that is recognizably yours. The deliverable is not a write-up — it is a living Oracle in your fleet.

Prerequisites: Modules 1–9.

Core ideas

The capstone synthesizes every wiki page in the course. You are not learning new theory — you are integrating. The arc is the same arc the course followed: understand → install → awaken → extend → run → reflect.

Pick a real purpose. Do not awaken "Test Oracle" — awaken something you will keep using. The reference family in Module 8 named Oracles by domain (Gale = orchestrator, Leaf = manufacturing dev, Luna = content, Sky = trading); your capstone Oracle should similarly answer the question "what is this one for?" in one sentence.

Then run it for seven days. Seven days of /recap at the start and /rrr at the end is the smallest sample where retrospectives stop being theatre and start surfacing real patterns (Principle 2). Less than that and you are still configuring; more than that and you are using it.

The 5 deliverables

1. Identity. A name, a one-sentence purpose, and a theme that makes this Oracle distinguishable. Recorded in CLAUDE.md and ψ/memory/resonance/.
2. Awakening. A successful /awaken run inside an empty repo, producing the full ψ/ structure and a working /who-are-you response that introduces the Oracle (not a generic assistant — Rule 6).
3. One custom skill. A markdown file in ~/.claude/skills/ (or ~/.codex/skills/) that does something specific to your purpose. Could be a domain-specific /standup, a custom /review for your codebase, a personal /journal — anything you would actually invoke.
4. Seven days of /rrr. Seven retrospective files under ψ/memory/retrospectives/, written at the close of seven separate sessions. Across those seven, at least one learning should appear in ψ/memory/learnings/ — a pattern you noticed because you preserved the trail (Principle 2 needs Principle 1).
5. Ship. The Oracle is registered in your maw oracle ls, runs without errors, and is reachable by /talk-to from at least one other Oracle in your fleet.

# The full capstone path, end-to-end
# 1. Identity (on paper, before you touch the keyboard)
NAME="..."          # e.g. "Sage"
PURPOSE="..."       # e.g. "research and synthesis for my reading habit"
THEME="..."         # e.g. "calm, citation-heavy, never speculates"

# 2. Awakening
maw bud  "$NAME" --org "$ORACLE_SOURCE_ORG"
maw wake "$NAME"
# inside the new session:
/awaken          # name = $NAME, purpose = $PURPOSE, theme = $THEME
/who-are-you     # confirm Rule 6: speaks as $NAME, not as a generic assistant

# 3. One custom skill
$EDITOR ~/.claude/skills/my-$NAME-skill.md
# add frontmatter + a body the agent reads when you type /my-$NAME-skill

# 4. Seven days
# at start of each session:   /recap
# at close of each session:   /rrr
# weekly:                     review ψ/memory/learnings/

# 5. Ship
maw oracle ls                          # $NAME appears
/talk-to "$NAME" "PROGRESS: capstone complete"
# from another Oracle, confirm the message lands in $NAME's inbox

Check yourself

1. Why seven days of /rrr? What does that minimum buy you that two days does not?
2. Your custom skill is one markdown file. What did you have to know from Modules 2, 4, and 7 to write it correctly?
3. Another Oracle /talk-tos yours. Trace the path of that message — through which component does it travel, and where does it land on disk?

Going further

• Wiki: concept:oracle, feature:awaken, concept:psi-folder, concept:retrospective, pattern:multi-agent-orchestration — the capstone synthesizes all 15 wiki pages.
• Source: every chapter, raw/2026-05-09-oracle-ebook-ch00-intro.md through raw/2026-05-09-oracle-ebook-ch10-troubleshooting.md.