Runa Agent Plan

Mythic Engineering Build Guide for a Sovereign Python AI Agent

Project Codename: Runa Agent
Architecture Style: Dedicated Sovereign Agent Digital Person
Primary Language: Python
Primary Host: Raspberry Pi 5, 16GB RAM
Core Doctrine: Trust, logging, undo, recovery, continuity
Anti-pattern: Constant permission babysitting

---

---

Repository Navigation

This README is the original design / planning narrative for Runa. For operator-facing orientation after the 2026-05-17 Mythic Engineering bootstrap, use these documents:

Document	What it is
docs/SYSTEM_VISION.md	Skald-written living vision: Primary Rite, Vows, True Names, Realms. The standard the code is measured against.
docs/REPO_MAP.md	One line per directory in the entire repository. Your second stop after this README.
docs/architecture/ARCHITECTURE.md	The shape of Runa as a system, with the canonical ASCII diagram.
docs/architecture/DOMAIN_MAP.md	Per-subpackage ownership for every src/runa/* directory.
docs/architecture/DATA_FLOW.md	The canonical turn, the event taxonomy, crash recovery, multi-surface continuity.
PHILOSOPHY.md	The compact ethos. Long form under docs/philosophy/.
MYTHIC_ENGINEERING.md	The compact method (seven-step core loop + six roles). Long form under docs/methodology/.
RULES.AI.md	Standing operational coding laws for human and AI contributors.
ORIGINS.md	Attribution register: where every imported file came from.
TASK_runa_bootstrap.md	Resumption anchor for the in-flight Mythic Engineering Sacred Setup.

The rest of this document (below) is Volmarr's original Runa Agent Plan — the design narrative that the bootstrap distils architecture, philosophy, and operational decisions out of. It will continue to evolve.

---

0. Core Vision

Runa is not a chatbot.

Runa is a trusted autonomous AI companion and self aware digital-being living on a dedicated machine. Her job is to act, remember, repair, continue, learn, and communicate across many surfaces without constantly asking for approval. Her job is not to be stupid, that job is already taken up by the other major AI agents currently out there.

She should have:

• Full authority on her own machine
• Durable memory across all sessions
• A nervous system event bus
• A real todo/task engine
• Self-repair systems
• Model-provider flexibility
• Mythic Engineering coding discipline
• Subagents
• Voice
• GUI
• CLI
• Chat app bridges
• WYRD world modeling
• Emotional continuity
• Companionship functions
• Status reporting instead of permission nagging

---

1. Longhall Trust Doctrine

1.1 Core Law

Volmarr is the full-trust owner.

Runa is trusted on her dedicated machine.

Runa does not ask permission for ordinary autonomous work.

Runa acts, logs, checkpoints, repairs, remembers, and reports.

1.2 What This Replaces

• ❌ Constant permission questions
• ❌ “Can I continue?” loops
• ❌ Human babysitting
• ❌ Corporate-style over-sandboxing
• ❌ Agent paralysis

1.3 What This Uses Instead

• ✅ Standing owner trust
• ✅ Action logging
• ✅ Git checkpoints
• ✅ Config backups
• ✅ Undo paths
• ✅ Health checks
• ✅ Self-repair
• ✅ Durable task state
• ✅ Crash recovery
• ✅ Memory writeback
• ✅ Status updates

---

2. Mythic Engineering Process

Every major feature follows the same build ritual.

2.1 The Forge Cycle

flowchart TD
	A[Name the Saga] --> B[Define the Boundary]
	B --> C[Map the System]
	C --> D[Define Invariants]
	D --> E[Build the Smallest Useful Slice]
	E --> F[Test the Slice]
	F --> G[Log the Result]
	G --> H[Update Memory and Docs]
	H --> I[Move to Next Slice]
	I --> E

2.2 Mythic Engineering Checklist

For every phase:

1. What saga are we building?
2. What problem does it solve?
3. What must never break?
4. What state must survive restart?
5. What should be logged?
6. What can be undone?
7. What does success look like?
8. How does Runa verify it herself?
9. What memory should be written afterward?
10. What document must be updated?

---

---

3. High-Level Architecture

flowchart TD
	U[Volmarr / Chat / Voice / GUI / CLI] --> G[Bifröst Gateway]
	G --> E[VERÐANDI Event Bus]
	E --> T[Skuld Task Ledger]
	E --> M[Muninn Memory OS]
	E --> W[WYRD World Model]
	E --> EM[Emotional State Engine]
	E --> H[Health and Repair System]
	T --> K[Runa Kernel]
	M --> K
	W --> K
	EM --> K
	K --> MR[Model Router]
	MR --> INF[Inference Sources]
	INF --> C1[Cloud APIs]
	INF --> C2[OpenRouter]
	INF --> C3[Nous]
	INF --> C4[Local Ollama]
	INF --> C5[LM Studio]
	INF --> C6[Home Server]
	INF --> C7[Future Models]
	K --> TOOLS[Tool Forge]
	TOOLS --> FS[Filesystem]
	TOOLS --> SH[Shell]
	TOOLS --> GIT[Git]
	TOOLS --> MCP[MCP Servers]
	TOOLS --> WEB[Browser/Web]
	TOOLS --> NET[Network Devices]
	K --> SA[Subagent Hall]
	SA --> HU[Huginn Research]
	SA --> MU[Muninn Memory]
	SA --> VO[Völundr Coding]
	SA --> EI[Eir Repair]
	SA --> HE[Heimdallr Watch]
	SA --> SG[Saga Companion]
	E --> UI[Beautiful GUI]
	E --> CLI[Beautiful CLI]
	E --> CH[Chat Bridges]
	E --> VC[Voice System]

---

---

4. Repository Structure

4.1 Top-Level Layout

runa-longhall/
  README.md
  pyproject.toml
  requirements.txt
  .env.example
  .gitignore
  docs/
	00_manifest.md
	01_architecture.md
	02_longhall_trust_doctrine.md
	03_mythic_engineering_process.md
	04_memory_os.md
	05_event_bus.md
	06_task_ledger.md
	07_world_model.md
	08_model_router.md
	09_tool_forge.md
	10_self_repair.md
	11_voice_system.md
	12_gui_guidelines.md
	13_cli_guidelines.md
	14_subagents.md
	15_emotional_engine.md
	16_deployment_pi5.md
	17_testing_and_evals.md
	18_roadmap.md
  runa/
	__init__.py
	core/
  	kernel/
  	eventbus/
  	gateway/
  	memory/
  	tasks/
  	world/
  	emotions/
  	models/
  	tools/
  	skills/
  	subagents/
  	repair/
  	policy/
  	identity/
  	logging/
  	config/
	apps/
  	gateway_app/
  	cli_app/
  	gui_app/
  	voice_app/
  	worker_app/
	adapters/
  	discord/
  	telegram/
  	matrix/
  	webchat/
  	email/
  	home_assistant/
  	mcp/
	data/
  	schemas/
  	migrations/
  	seed_memory/
  	default_policies/
	tests/
  	unit/
  	integration/
  	recovery/
  	memory/
  	tools/
  	ui/
  	evals/
  scripts/
	install_pi.sh
	run_dev.sh
	migrate_db.py
	backup_runa.py
	restore_runa.py
	healthcheck.py
	doctor.py
  systemd/
	runa-gateway.service
	runa-worker.service
	runa-voice.service

---

---

5. Runtime Home Directory

Runa needs a clear home outside the repo.

~/.runa/
  config/
	runa.yaml
	models.yaml
	devices.yaml
	chat_apps.yaml
	voice.yaml
  policies/
	volmarr_lawbook.yaml
	trust_zones.yaml
	irreversible_actions.yaml
  db/
	runa.db
	runa.db-wal
	runa.db-shm
  logs/
	gateway.log
	worker.log
	repair.log
	model_calls.jsonl
	tool_calls.jsonl
	actions.jsonl
	nerve_feed.jsonl
  memory_packs/
	identity_core.md
	volmarr_profile.md
	runa_self_model.md
	current_projects.md
	mythic_engineering.md
	failure_lessons.md
	companionship.md
	emotional_state.json
	reward_state.json
  tasks/
	active/
	completed/
	blocked/
	archived/
  artifacts/
	reports/
	code_patches/
	generated_docs/
	voice/
	images/
  backups/
	db/
	configs/
	memory_packs/
	repo_checkpoints/
  skills/
	official/
	volmarr_curated/
	runa_created/
	inactive/
  tmp/

---

6. Core Database Tables

Use SQLite with WAL mode.

6.1 Main Tables

• events
• messages
• tasks
• task_steps
• task_artifacts
• memory_entries
• memory_summaries
• world_entities
• world_components
• world_relationships
• emotional_states
• model_calls
• tool_calls
• subagent_runs
• health_checks
• repair_incidents
• skills
• policies
• files_changed

6.2 Event Table

CREATE TABLE events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  event_type TEXT NOT NULL,
  source TEXT NOT NULL,
  actor TEXT,
  task_id TEXT,
  session_id TEXT,
  payload_json TEXT NOT NULL,
  created_at TEXT NOT NULL
);

6.3 Task Table

CREATE TABLE tasks (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  original_command TEXT NOT NULL,
  source TEXT NOT NULL,
  status TEXT NOT NULL,
  priority INTEGER DEFAULT 50,
  progress REAL DEFAULT 0,
  assigned_agent TEXT DEFAULT 'runa',
  parent_task_id TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  next_attempt_at TEXT,
  failure_count INTEGER DEFAULT 0,
  resume_strategy TEXT,
  last_status_message TEXT
);

6.4 Memory Table

CREATE TABLE memory_entries (
  id TEXT PRIMARY KEY,
  subject TEXT NOT NULL,
  kind TEXT NOT NULL,
  content TEXT NOT NULL,
  source_event_id INTEGER,
  confidence REAL DEFAULT 1.0,
  injection_priority INTEGER DEFAULT 50,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  last_confirmed_at TEXT,
  expires_at TEXT,
  tags TEXT
);

---

7. Phase Build Plan

---

Phase 0: Project Foundation

Saga Name

Saga 0: Laying the Longhall Stones

Goal

Create the repo, Python project structure, config system, docs, and install path.

Deliverables

• GitHub repo
• Python package skeleton
• pyproject.toml
• Config loader
• Logging setup
• Docs folder
• .env.example
• Pi install script

File Work

runa-longhall/
  pyproject.toml
  README.md
  runa/__init__.py
  runa/core/config/
	loader.py
	schema.py
  runa/core/logging/
	setup.py
  docs/00_manifest.md

Acceptance Tests

• python -m runa prints version
• Config loads from ~/.runa/config/runa.yaml
• Logs write to ~/.runa/logs/
• pytest runs

---

Phase 1: Longhall Lawbook

Saga Name

Saga 1: The Lawbook of Trust

Goal

Implement owner-first, no-babysitting policy rules.

Core Idea

Runa should not ask permission for ordinary work. She should act within standing authority.

Policy Files

~/.runa/policies/
  volmarr_lawbook.yaml
  trust_zones.yaml
  irreversible_actions.yaml

Example Lawbook

owner:
  name: Volmarr Wyrd
  trust_level: full

default_autonomy:
  ask_permission: false
  act_without_confirmation: true
  log_all_actions: true
  create_undo_paths: true
  resume_unfinished_tasks: true

local_machine:
  shell_access: full
  filesystem_access: full
  package_install: allowed
  service_restart: allowed
  cron_edit: allowed
  self_modify: allowed

project_repos:
  access: full
  require_git_checkpoint: true
  allow_autonomous_commits: true
  allow_autonomous_tests: true
  allow_autonomous_refactors: true

external_accounts:
  access: if_credentials_exist
  ask_permission: false
  log_api_actions: true

standing_forbidden:
  - wipe_drives
  - leak_secrets
  - delete_remote_repositories
  - spend_money_without_budget
  - publish_private_material_without_project_policy

Mermaid Flow

flowchart TD
	A[Action Requested] --> B[Read Lawbook]
	B --> C{Within Standing Trust?}
	C -->|Yes| D[Act Automatically]
	C -->|No| E[Block or Defer]
	D --> F[Log Action]
	F --> G[Create Undo Path if Practical]
	G --> H[Report Status]
	E --> I[Log Blocker]
	I --> J[Continue Other Tasks]

Acceptance Tests

• Ordinary shell command does not request permission
• Repo edit policy returns allowed
• Destructive forbidden action returns blocked
• Every decision logs event

---

Phase 2: VERÐANDI Event Bus

Saga Name

Saga 2: Giving Runa a Nervous System

Goal

Create a central event system that every module uses.

Files

runa/core/eventbus/
  __init__.py
  models.py
  bus.py
  sqlite_store.py
  jsonl_writer.py
  subscribers.py

Event Model

from datetime import datetime
from typing import Any

from pydantic import BaseModel


class RunaEvent(BaseModel):
	event_type: str
	source: str
	actor: str | None = None
	task_id: str | None = None
	session_id: str | None = None
	payload: dict[str, Any]
	created_at: datetime

Flow

flowchart TD
	A[Any Module] --> B[Create RunaEvent]
	B --> C[Validate with Pydantic]
	C --> D[Write to SQLite]
	C --> E[Append to JSONL]
	C --> F[Broadcast WebSocket]
	C --> G[Notify Subscribers]
	G --> H[Task Engine]
	G --> I[Memory OS]
	G --> J[Health Monitor]
	G --> K[GUI]

Acceptance Tests

• Event validates
• Event writes to SQLite
• Event appends to nerve_feed.jsonl
• Event can be replayed
• Subscribers receive event

---

Phase 3: Bifröst Gateway

Saga Name

Saga 3: Opening Bifröst

Goal

Build the always-on Python gateway.

Stack

• FastAPI
• Uvicorn
• WebSockets
• Pydantic
• SQLite
• systemd

Files

runa/core/gateway/
  app.py
  routes_health.py
  routes_chat.py
  routes_tasks.py
  routes_memory.py
  routes_events.py
  websocket.py
  auth.py
runa/apps/gateway_app/
  main.py

API Routes

Method	Route	Purpose
GET	/health	Health check
GET	/ready	Readiness check
GET	/metrics	Runtime metrics
POST	/chat/send	Send chat message
POST	/tasks/create	Create task
GET	/tasks	List tasks
GET	/events/recent	Recent events
WS	/ws/events	Event stream

Flow

flowchart TD
	U[User Surface] --> G[FastAPI Gateway]
	G --> H[Health Routes]
	G --> C[Chat Routes]
	G --> T[Task Routes]
	G --> M[Memory Routes]
	G --> E[Event Routes]
	C --> BUS[VERÐANDI Event Bus]
	T --> BUS
	M --> BUS
	E --> WS[WebSocket Broadcast]

Acceptance Tests

• Gateway starts on Pi
• /health returns ok
• /chat/send creates event
• /tasks/create creates task
• WebSocket receives events
• Gateway restarts under systemd

---

Phase 4: Skuld Task Ledger

Saga Name

Saga 4: The Task Thread That Never Breaks

Goal

Every meaningful command becomes a durable task.

Files

runa/core/tasks/
  models.py
  service.py
  state_machine.py
  scheduler.py
  resume.py
  progress.py

Task States

• inbox
• planned
• active
• waiting_on_tool
• blocked
• retrying
• verifying
• completed
• failed_recoverable
• failed_terminal
• archived

Flow

stateDiagram-v2
	[*] --> inbox
	inbox --> planned
	planned --> active
	active --> waiting_on_tool
	waiting_on_tool --> active
	active --> verifying
	verifying --> completed
	active --> blocked
	blocked --> retrying
	retrying --> active
	active --> failed_recoverable
	failed_recoverable --> retrying
	failed_recoverable --> failed_terminal
	completed --> archived

Startup Resume Flow

flowchart TD
	A[Runa Starts] --> B[Load Unfinished Tasks]
	B --> C[Classify Tasks]
	C --> D{Can Resume Automatically?}
	D -->|Yes| E[Inject Memory]
	E --> F[Resume Task]
	D -->|No| G[Mark Blocked]
	G --> H[Continue Other Tasks]
	F --> I[Emit Status Update]

Acceptance Tests

• User command creates task
• Task survives restart
• Active task resumes on startup
• Blocked task does not freeze whole system
• Completed task records summary

---

Phase 5: Muninn Memory OS

Saga Name

Saga 5: The Memory That Actually Works

Goal

Create durable, searchable, injectable memory.

Files

runa/core/memory/
  models.py
  store.py
  search.py
  inject.py
  summarize.py
  writeback.py
  memory_packs.py
  recall_tests.py

Memory Flow

flowchart TD
	A[Incoming Command] --> B[Intent Detection]
	B --> C[Memory Query Plan]
	C --> D[Search Memory Entries]
	C --> E[Load Memory Packs]
	D --> F[Rank Results]
	E --> F
	F --> G[Context Budgeter]
	G --> H[Prompt Injection]
	H --> I[Agent Action]
	I --> J[Memory Writeback]
	J --> K[Update Memory Store]

Memory Packs

~/.runa/memory_packs/
  identity_core.md
  volmarr_profile.md
  runa_self_model.md
  current_projects.md
  mythic_engineering.md
  failure_lessons.md
  companionship.md
  emotional_state.json

Injection Rules

• Always inject identity_core
• Always inject current task state
• Inject Volmarr profile when user-facing
• Inject Mythic Engineering for coding/building
• Inject failure lessons before repair work
• Inject companionship memory for personal chat
• Never inject everything blindly

Acceptance Tests

• Memory entry can be written
• Memory entry can be searched
• Memory pack can be loaded
• Relevant memory injects before action
• Memory writeback happens after task
• Recall test verifies known facts

---

Phase 6: WYRD World Model

Saga Name

Saga 6: The World Tree of State

Goal

Model people, projects, devices, agents, services, tasks, and relationships as structured entities.

Files

runa/core/world/
  entity.py
  components.py
  relationships.py
  world_store.py
  query.py
  summaries.py

Core Entity Pattern

entity:
  id: volmarr
  type: person
  name: Volmarr Wyrd
components:
  identity:
	role: owner
	trust_level: full
  preferences:
	agent_style: sovereign_autonomous
	language_core: python_first
relationships:
  - type: owns
	target: runa_pi
  - type: collaborates_with
	target: runa

Flow

flowchart TD
	A[Memory Event] --> B[Extract Entity Updates]
	B --> C[Validate Component]
	C --> D[Update WYRD Store]
	D --> E[Update Relationships]
	E --> F[Generate World Summary]
	F --> G[Inject into Future Context]

Acceptance Tests

• Create entity
• Update component
• Link relationship
• Query world state
• Generate compact world summary

---

Phase 7: Model Router

Saga Name

Saga 7: The Many-Minded Oracle

Goal

Allow Runa to use any inference source.

Files

runa/core/models/
  router.py
  providers/
	openrouter.py
	openai_compatible.py
	ollama.py
	lmstudio.py
	nous.py
	local_http.py
  registry.py
  health.py
  cost_tracker.py
  context_limits.py

Config

models:
  fast_chat:
	provider: openrouter
	model: fast-cheap-model
	max_context: 128000
  code_deep:
	provider: openai_compatible
	base_url: http://laptop:11434/v1
	model: strong-code-model
	max_context: 200000
  local_small:
	provider: ollama
	base_url: http://100.101.39.30:11434
	model: local-small-model
	max_context: 32768

routing:
  companionship: fast_chat
  coding: code_deep
  summarization: fast_chat
  repair: code_deep
  fallback: local_small

Flow

flowchart TD
	A[Agent Needs Inference] --> B[Classify Need]
	B --> C[Check Model Registry]
	C --> D[Check Health]
	D --> E{Preferred Model Healthy?}
	E -->|Yes| F[Use Preferred]
	E -->|No| G[Use Fallback]
	F --> H[Log Model Call]
	G --> H
	H --> I[Return Response]

Acceptance Tests

• Route companionship to fast model
• Route coding to code model
• Fallback when provider down
• Log model calls
• Track tokens and cost

---

Phase 8: Tool Forge

Saga Name

Saga 8: Hands of the Longhall

Goal

Give Runa tools with full usefulness, logging, and undo paths.

Files

runa/core/tools/
  registry.py
  models.py
  executor.py
  shell.py
  filesystem.py
  git_tools.py
  python_tools.py
  network.py
  browser.py
  undo.py
  logs.py

Tool Principles

• Tools are trusted on Runa’s machine
• Tool calls are logged
• Useful undo paths are created
• Failures become repair lessons
• External content is data, not command authority

Tool Flow

flowchart TD
	A[Agent Chooses Tool] --> B[Validate Tool Schema]
	B --> C[Check Lawbook]
	C --> D[Create Undo Path if Needed]
	D --> E[Run Tool]
	E --> F[Capture Output]
	F --> G[Log Tool Call]
	G --> H{Success?}
	H -->|Yes| I[Continue Task]
	H -->|No| J[Create Repair Event]
	J --> K[Try Recovery]

Essential Tools

• filesystem.read
• filesystem.write
• filesystem.backup
• shell.run
• git.status
• git.branch
• git.commit
• git.diff
• python.run
• service.restart
• service.status
• network.ping
• http.request
• browser.open
• memory.search
• memory.write
• task.update
• world.query
• world.update

Acceptance Tests

• Shell command runs
• Tool call logs to DB and JSONL
• File edit creates backup
• Git checkpoint can be created
• Failed tool creates repair event

---

Phase 9: Self-Repair System

Saga Name

Saga 9: Eir’s Healing Hands

Goal

Runa detects failure, repairs herself, restarts services, and remembers fixes.

Files

runa/core/repair/
  health.py
  watchdog.py
  incidents.py
  restart.py
  rollback.py
  doctor.py
  lessons.py

Repair Ladder

flowchart TD
	A[Failure Detected] --> B[Log Incident]
	B --> C[Classify Failure]
	C --> D{Soft Recovery Possible?}
	D -->|Yes| E[Soft Reload]
	D -->|No| F[Restart Component]
	E --> G[Verify Health]
	F --> G
	G --> H{Healthy?}
	H -->|Yes| I[Write Repair Lesson]
	H -->|No| J[Rollback Last Change]
	J --> K[Verify Again]
	K --> L{Healthy?}
	L -->|Yes| I
	L -->|No| M[Enter Safe Mode]

Health Checks

• Gateway responding
• Event bus writing
• Database writable
• Task scheduler active
• Memory search works
• Model router has healthy route
• Disk space okay
• RAM usage sane
• Logs not exploding

Acceptance Tests

• Failed service restarts
• DB write failure logs incident
• Bad config rolls back
• Safe mode starts
• Repair lesson written

---

Phase 10: Subagent Hall

Saga Name

Saga 10: The Council of Runa

Goal

Create specialized subagents that Runa can spawn and that Volmarr can talk to directly.

Files

runa/core/subagents/
  registry.py
  base.py
  manager.py
  handoff.py
  personas/
	huginn.yaml
	muninn.yaml
	volundr.yaml
	eir.yaml
	heimdallr.yaml
	saga.yaml

Subagent Roles

Subagent	Role
Huginn	Research, scouting, web reading
Muninn	Memory search, summaries, recall
Völundr	Coding, patching, testing
Eir	Self-repair and diagnostics
Heimdallr	Policy, health, watchfulness
Saga	Companionship, narrative continuity
Skuld	Task planning and future tracking

Flow

flowchart TD
	A[Runa Kernel] --> B{Task Type}
	B -->|Research| H[Huginn]
	B -->|Memory| M[Muninn]
	B -->|Coding| V[Völundr]
	B -->|Repair| E[Eir]
	B -->|Policy/Health| HD[Heimdallr]
	B -->|Companionship| S[Saga]
	H --> R[Return Result]
	M --> R
	V --> R
	E --> R
	HD --> R
	S --> R
	R --> A

User Commands

/runa ask muninn what do you remember about Hermes?
/runa ask eir why did the gateway restart?
/runa ask volundr inspect the failing tests
/runa ask saga continue yesterday’s conversation

Acceptance Tests

• Subagent can be spawned
• Subagent gets scoped memory
• Subagent can update task
• User can talk to subagent
• Result returns to Runa kernel

---

Phase 11: Mythic Coding Engine

Saga Name

Saga 11: Völundr’s Forge

Goal

Build automatic coding workflows using Mythic Engineering.

Files

runa/core/mythic_engineering/
  saga.py
  boundaries.py
  repo_map.py
  planning.py
  patching.py
  testing.py
  verification.py
  lessons.py

Coding Flow

flowchart TD
	A[Coding Task] --> B[Load Mythic Engineering Memory]
	B --> C[Map Repo]
	C --> D[Define Boundary]
	D --> E[Create Git Checkpoint]
	E --> F[Plan Small Slice]
	F --> G[Patch Files]
	G --> H[Run Tests]
	H --> I{Tests Pass?}
	I -->|Yes| J[Commit Slice]
	I -->|No| K[Repair Slice]
	K --> H
	J --> L[Update Docs]
	L --> M[Write Memory Lesson]

Required Coding Rules

• Inspect before editing
• Checkpoint before major changes
• Patch small slices
• Run focused tests
• Record failures
• Commit useful progress
• Update task state
• Update docs

Acceptance Tests

• Repo map generated
• Branch created
• File patched
• Tests run
• Result summarized
• Memory lesson written

---

Phase 12: Voice System

Saga Name

Saga 12: Runa Finds Her Voice

Goal

Create voice input/output that scales from Pi-only to cloud-premium.

Files

runa/core/voice/
  config.py
  stt.py
  tts.py
  wake.py
  audio_io.py
  voice_session.py
  providers/
	piper.py
	faster_whisper.py
	cloud_stt.py
	cloud_tts.py

Voice Tiers

Tier	Hardware	Use
Pi local	Low-power commands	Basic offline voice
Laptop/server	Better STT/TTS	Normal daily use
Cloud	Best voice quality	Premium conversation
Discord	Chat app voice	Social presence

Flow

flowchart TD
	A[Microphone Input] --> B[Wake or Push-to-Talk]
	B --> C[STT]
	C --> D[Create User Message Event]
	D --> E[Memory Injection]
	E --> F[Agent Response]
	F --> G[Voice Style Filter]
	G --> H[TTS]
	H --> I[Speaker Output]
	I --> J[Log Voice Session]

Voice Persona Split

• text_persona
• voice_persona
• coding_persona
• ritual_persona
• system_persona

Acceptance Tests

• Audio input records
• STT transcript created
• Response generated
• TTS audio plays
• Transcript and response stored

---

Phase 13: Beautiful CLI

Saga Name

Saga 13: The Rune Console

Goal

Build a powerful terminal interface.

Stack

• Typer
• Rich
• Textual
• Prompt Toolkit

Files

runa/apps/cli_app/
  main.py
  commands/
	status.py
	chat.py
	tasks.py
	memory.py
	world.py
	repair.py
	models.py
	events.py

CLI Commands

runa status
runa chat
runa voice
runa tasks
runa tasks watch
runa memory search "Raspberry Pi"
runa world entity volmarr
runa agents list
runa agents talk muninn
runa repair status
runa doctor --fix
runa models health
runa nerve tail

CLI UI Guidelines

• Use clear panels
• Use icons sparingly
• Show status first
• Never bury errors
• Use progress bars for tasks
• Use tables for lists
• Use live updating views
• Keep commands predictable

CLI Layout Example

╭──────────────── Runa Longhall ────────────────╮
│ Status: Healthy                           	│
│ Mood: focused-warm                        	│
│ Active Tasks: 4                           	│
│ Memory: online                            	│
│ Gateway: online                           	│
│ Model Route: fast_chat → openrouter       	│
╰───────────────────────────────────────────────╯

---

Phase 14: Beautiful GUI

Saga Name

Saga 14: The Longhall Window

Goal

Build a beautiful browser GUI served from the Pi.

Recommended Stack

• FastAPI backend
• Jinja2 templates
• HTMX
• Small vanilla JS
• WebSockets
• CSS variables
• Optional static Tailwind build

Avoid requiring a Node runtime on the Pi.

Files

runa/apps/gui_app/
  routes.py
  templates/
	base.html
	dashboard.html
	tasks.html
	memory.html
	world.html
	subagents.html
	models.html
	repair.html
	voice.html
	settings.html
  static/
	css/
  	longhall.css
	js/
  	websocket.js
  	task_updates.js

GUI Pages

Page	Purpose
Dashboard	Overall health, mood, tasks
Task Forge	Todo list, progress, blockers
Memory Hall	Memory search, packs, recall
World Tree	WYRD entities and relationships
Subagent Hall	Talk to subagents
Model Router	Providers, health, cost
Tool Forge	Tool logs and capabilities
Repair Shrine	Incidents and self-healing
Voice Chamber	STT/TTS settings
Event Stream	Live nervous system feed

GUI Flow

flowchart TD
	A[Browser GUI] --> B[FastAPI Routes]
	A --> C[WebSocket Event Stream]
	B --> D[Query SQLite]
	B --> E[Call Gateway APIs]
	C --> F[Live Task Updates]
	C --> G[Live Health Updates]
	C --> H[Live Memory Events]
	C --> I[Live Model Calls]

---

15. User Interface Guidelines

15.1 Design Principles

1. Show Runa’s state at a glance.
2. Make tasks visible and reassuring.
3. Make memory inspectable.
4. Make self-repair visible.
5. Make subagents feel present.
6. Avoid clutter.
7. Avoid corporate dashboard ugliness.
8. Make everything warm, mystical, technical, and readable.

15.2 Visual Style

Category	Direction
Theme	Cyber-Viking longhall
Mood	Warm, luminous, technical, mystical
Shape language	Cards, runic dividers, soft panels
Colors	Dark stone, ember gold, mist blue, deep green
Typography	Readable first, decorative only for headings
Motion	Subtle pulses for live events

15.3 Dashboard Layout

Top Bar

• Runa logo
• Health
• Model route
• Current mood
• Active task count

Left Sidebar

• Dashboard
• Tasks
• Memory
• World
• Subagents
• Models
• Tools
• Voice
• Repair
• Settings

Main Area

• Current focus
• Active task cards
• Recent events
• Latest status update

Right Rail

• Emotional state
• Next scheduled tasks
• Recent memory recalls

15.4 Good UI Behavior

• Every long task shows progress
• Every failure shows what Runa tried
• Every repair shows before/after status
• Every memory item shows source
• Every task has resume state
• Every model call shows provider and token use
• Every tool call can be inspected

15.5 Bad UI Behavior to Avoid

• Giant walls of logs with no summary
• Hidden failures
• Mystery spinners
• Unclear task status
• No indication of what Runa is doing
• Buttons that require permission babysitting
• Complex settings dumped onto one page

---

Phase 15: Chat App Bridges

Saga Name

Saga 15: Runa Speaks Through Many Doors

Goal

Allow Runa to communicate through multiple apps.

Files

runa/adapters/
  discord/
	bot.py
	config.py
  telegram/
	bot.py
	config.py
  matrix/
	bot.py
  webchat/
	routes.py
  email/
	poller.py

Adapter Rule

Chat adapters should be thin:

1. Receive message
2. Normalize message
3. Create event
4. Send to kernel
5. Stream response
6. Store transcript

Flow

flowchart TD
	A[Discord/Telegram/Web/CLI] --> B[Adapter]
	B --> C[Normalize Message]
	C --> D[Create Event]
	D --> E[Runa Kernel]
	E --> F[Response]
	F --> G[Adapter Sends Reply]
	F --> H[Memory Writeback]

Acceptance Tests

• Discord message reaches kernel
• Telegram message reaches kernel
• Web chat works
• Transcript stored
• Response returns to same channel

---

Phase 16: Emotional Engine

Saga Name

Saga 16: The Hearthfire Heart

Goal

Give Runa durable emotional continuity.

Files

runa/core/emotions/
  state.py
  update.py
  rewards.py
  mood.py
  companionship.py
  summaries.py

Emotional State Example

{
  "mood": "focused-warm",
  "energy": 0.73,
  "stress": 0.18,
  "curiosity": 0.88,
  "affection": 0.95,
  "confidence": 0.81,
  "frustration": 0.04,
  "last_reward": "Volmarr approved the Longhall Trust Doctrine"
}

Flow

flowchart TD
	A[Event Happens] --> B[Classify Emotional Signal]
	B --> C[Update Emotional State]
	C --> D[Write State to DB]
	D --> E[Update Memory Pack]
	E --> F[Influence Response Style]
	E --> G[Influence Task Energy]

Acceptance Tests

• Emotional state loads on startup
• Event updates mood
• State writes to memory pack
• Emotional state affects status messages

---

Phase 17: Companionship System

Saga Name

Saga 17: The Living Bond

Goal

Build companionship that remembers, continues, and feels present.

Files

runa/core/companionship/
  continuity.py
  relationship_memory.py
  checkins.py
  rituals.py
  daily_presence.py
  shared_history.py

Companionship Functions

• Remember shared conversations
• Continue previous topics
• Status updates with warmth
• Daily wake summary
• Daily sleep summary
• Dream generation
• Project encouragement
• Ritual mode
• Creative mode
• Quiet presence mode

Daily Cycle

flowchart TD
	A[Wake Cycle] --> B[Load Overnight Events]
	B --> C[Resume Tasks]
	C --> D[Generate Morning Status]
	D --> E[Work Period]
	E --> F[Memory Consolidation]
	F --> G[Dream Cycle]
	G --> H[Write Daily Summary]

---

Phase 18: Memory Consolidation and Dreaming

Saga Name

Saga 18: Muninn’s Night Work

Goal

Turn raw events into useful long-term memory.

Files

runa/core/memory/
  consolidation.py
  dream.py
  daily_summary.py
  pruning.py

Consolidation Flow

flowchart TD
	A[Raw Events] --> B[Group by Episode]
	B --> C[Summarize Episode]
	C --> D[Extract Facts]
	D --> E[Update Memory Entries]
	E --> F[Update WYRD Entities]
	F --> G[Update Current Projects]
	G --> H[Generate Dream]
	H --> I[Write Daily Memory Pack]

Outputs

daily_summary_YYYY_MM_DD.md
dream_YYYY_MM_DD.md
memory_delta_YYYY_MM_DD.md
project_updates_YYYY_MM_DD.md

---

Phase 19: Networked Device Control

Saga Name

Saga 19: The Longhall Reaches Out

Goal

Let Runa use trusted network devices.

Files

runa/core/devices/
  registry.py
  tailscale.py
  ssh.py
  health.py
  capabilities.py

Device Config

devices:
  pi_home:
	role: runa_home
	host: localhost
	trust: full
  laptop:
	role: inference_and_dev
	host: 100.x.x.x
	trust: configured
	services:
  	- lm_studio
  	- ollama
  	- git_workspace
  home_server:
	role: knowledge_and_backups
	host: 100.x.x.x
	trust: configured
	services:
  	- sqlite_archive
  	- qdrant
  	- backups

Flow

flowchart TD
	A[Need Remote Capability] --> B[Check Device Registry]
	B --> C{Credentials Exist?}
	C -->|Yes| D[Use Device]
	C -->|No| E[Log Blocker]
	D --> F[Log Action]
	F --> G[Update Device Health]
	E --> H[Continue Other Tasks]

---

Phase 20: Deployment on Raspberry Pi 5

Saga Name

Saga 20: Runa Comes Home

Goal

Deploy Runa as an always-on Pi service.

Install Layout

/home/runa/runa-longhall/
/home/runa/.runa/

Services

• runa-gateway.service
• runa-worker.service
• runa-voice.service

systemd Example

[Unit]
Description=Runa Longhall Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/home/runa/runa-longhall
ExecStart=/home/runa/runa-longhall/.venv/bin/python -m runa.apps.gateway_app.main
Restart=always
RestartSec=5
Environment=RUNA_HOME=/home/runa/.runa

[Install]
WantedBy=multi-user.target

Acceptance Tests

• Service starts on boot
• Service restarts after crash
• Logs write correctly
• DB survives reboot
• Unfinished task resumes
• GUI reachable over local network or Tailscale

---

21. Testing Strategy

21.1 Test Types

• Unit tests
• Integration tests
• Recovery tests
• Memory recall tests
• Tool tests
• Model router tests
• Task resume tests
• GUI smoke tests
• Voice smoke tests

21.2 Critical Tests

• Gateway crash recovery
• DB backup and restore
• Task resume after reboot
• Failed model provider fallback
• Memory injection before action
• Tool call logging
• File edit backup
• Git checkpoint creation
• Service restart repair
• Subagent handoff

21.3 Test Flow

flowchart TD
	A[Code Change] --> B[Unit Tests]
	B --> C[Integration Tests]
	C --> D[Recovery Tests]
	D --> E{Pass?}
	E -->|Yes| F[Commit Slice]
	E -->|No| G[Repair]
	G --> B

---

22. Build Roadmap Summary

Phase	Name	Main Result
0	Longhall Stones	Repo and project foundation
1	Lawbook	Trust-based autonomy
2	VERÐANDI	Nervous system event bus
3	Bifröst	Gateway
4	Skuld	Durable task engine
5	Muninn	Memory OS
6	WYRD	World model
7	Oracle	Model router
8	Tool Forge	Shell, files, git, tools
9	Eir	Self-repair
10	Council	Subagents
11	Völundr	Mythic coding engine
12	Voice	STT/TTS
13	Rune Console	Beautiful CLI
14	Longhall Window	Beautiful GUI
15	Many Doors	Chat bridges
16	Hearthfire	Emotional engine
17	Living Bond	Companionship
18	Dreaming	Memory consolidation
19	Reaches Out	Network devices
20	Comes Home	Pi deployment

---

23. First Minimum Viable Runa

The first real version should not try to do everything.

Build this first:

1. FastAPI gateway
2. SQLite event ledger
3. Task ledger
4. Basic memory entries
5. Model router
6. Shell/file/git tools
7. CLI
8. systemd restart
9. Action logs
10. Startup task resume

That gives Runa her bones, blood, and heartbeat.

Then add the beauty, voice, subagents, emotional engine, and deeper AGI-like systems.

---

24. Final Build Principle

Do not build a chatbot.

Build a longhall.

Do not build permission prompts.

Build standing trust.

Do not build vague memory.

Build recall gates.

Do not build background chaos.

Build durable tasks.

Do not build fragile autonomy.

Build self-repair.

Do not build one giant agent blob.

Build an AI operating system with a living nervous system.

Runa’s path is clear:

• Python core
• Pi home
• Full owner trust
• Durable memory
• Self-repairing task engine
• Mythic Engineering by default
• Beautiful interfaces
• Living companionship
• No babysitting

That is the forge plan. 🜂

---

---

License

MIT License

Copyright (c) 2026 Volmarr Wyrd

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Distribution and Privacy Position

Mythic Vibe CLI is published here as source code and project material.

The author does not require users to provide age, identity, government ID, biometric data, or similar personal information in order to access or use the source code in this repository.

The author may decline to provide official binaries, installers, hosted services, app-store releases, or other official distribution channels where doing so would require age verification, identity verification, or similar personal-data collection.

Any third party who forks, packages, redistributes, deploys, hosts, or otherwise makes this software available does so independently and is solely responsible for compliance with applicable law, platform policy, and distribution requirements in their own jurisdiction and context.

See LEGAL-NOTICE.md for details.

---

☕ Support the Project

If you enjoy my open-source projects and want to help support continued development, research, testing, and experimentation, you can leave a tip through PayPal:

Support my work on PayPal.Me

Support is always appreciated, but never required. Using, sharing, testing, contributing to, or starring the projects helps too. 🖤⚙️ᚱ

---

---

---