Toilville Rituals — Consumer Prompting Dojo

Architecture: Schema-first, Universal Design Grammar Philosophy: Inert by default, progressive consent, ethical transparency

A personal automation tool that makes AI-powered workflows safe, ethical, and accessible through progressive consent tiers and ritualized workflows.

UDG Validity Rule: This spec is valid only if it can be losslessly lowered into Toilville's Universal Design Grammar without platform-specific logic.

Overview

Rituals teaches prompting as a disciplined practice through structured progression from Zero AI to Federation mode. Every action produces auditable lineage records, making ethical boundaries and system limitations visible rather than hidden.

Core Principles:

• All features require explicit invitation and consent
• Users learn through structured, ritualized workflows
• Safety checks block risky automation attempts
• Complete transparency about data sources, model usage, and decision-making
• Universal design grammar ensures consistent behavior across platforms

Non-Goals:

• Maximize AI power or performance
• Replace professional automation tools
• Hide ethical incompleteness or system limitations
• Platform-specific optimizations (handled by JTBD extensions)

Project Status

Project Board →

Phase	Description	Status
Phase 0	Foundation & Architecture	Complete
Phase 1	Tier 0 (Zero AI)	Complete — ritual CRUD, library, creation form, execution, Tier 0 enforcement
Phase 2	Consent System & Safety	Complete — ConsentGate, tier enforcement, SafetyEngine, override ceremony, audit trail
Phase 3	Ritual Execution System	Complete — template engine, lineage ledger, streaming execution path
Phase 4	Lineage & Audit System	Complete — SQLite ledger (schema v11), hash integrity, export, DecisionLogScreen
Phase 5	Tier 1 (Local Model)	Partial — Apple Foundation Models (iOS 27+ / macOS 27+), Apple Silicon MLX, Anthropic-compatible, Kagi, and OpenAI-compatible runners wired; runtime selection and full platform testing in progress
Phase 6	Error Handling & Polish	Complete — error state, recovery actions, SafetyEngine overlay
Phase 7	Accessibility	Complete — keyboard navigation (ArrowKeyListNavigator), WCAG 2.1 AA contrast, screen reader labels
Phase 8	Tier 2 & 3 (Federation)	Active — lineage sync (/api/lineage/sync), pattern federation (/api/patterns), safety audit (/api/lineage/safety-audit), and SSE stream wired; Tier 2–3 full flow in testing

For open issues and sprint state see the Forgejo project board.

User Stories

• Primary user: Individual exploring personal automation with ethical guardrails
• Primary job-to-be-done: Learn and safely practice prompting through structured progression from zero-AI to limited automation

Scenario A: First-time user completes onboarding, declares first wish, selects Observatory mode to observe without execution.

Scenario B: User progresses from Tier 0 (Zero AI) to Tier 1 (Local Model) after understanding consent implications, creates first ritual, reviews lineage artifacts.

Acceptance Criteria

All criteria are deterministic — expressible as boolean UI states, explicit constraints, or deterministic outcomes.

• AC1: Given a new user opens Rituals, when the system loads, then all features remain disabled until onboarding completes and a mode is selected.
• AC2: Given user completes onboarding, when they attempt to create a ritual, then the system blocks execution until consent tier is explicitly granted.
• AC3: Given user grants Tier 1 consent, when they execute a ritual, then the system produces a ledger entry with inputs, resolved prompt, consent tier, mode, and lineage hash.
• AC4: Given user edits an existing ritual, when they save changes, then the system creates a new versioned lineage record without mutating the original.
• AC5: Given SafetyEngine detects risky intent, when user attempts execution, then the system blocks with reason and suggested mitigation.
• AC6: Given user operates in Tier 0, when they interact with the system, then no AI models load and only ritual templates, rubrics, and governance tools are accessible.
• AC6a: Given user is in Tier 0 Workshop mode, when they fill all required template fields and execute a ritual, then the system produces a lineage entry with engine: "template", tier: 0, and a resolved_output containing the interpolated prompt string — no model is invoked.
• AC6b: Given a ritual has required template fields, when user attempts execution with any required field missing or empty, then the system blocks execution and reports which fields are missing — no lineage entry is written.
• AC7: Given user completes a ritual run, when results display, then a Dojo Feedback Card appears with dimensions exercised, consent posture, lineage clarity score, and next steps.

Architecture: Consumer Client + Forge Integration

Toilville Rituals follows an offline-first consumer client architecture that integrates with the ~/.spel forge infrastructure for Tier 2–3 features.

Client-Server Boundary

Responsibility	Client	Server (~/.spel forge)
Ritual Definitions	Local CRUD + cache	Federation registry
Tier 0 Execution	100% local	None
Tier 1 Execution	100% local (Apple/PWA)	None
Tier 2 Execution	Local state + API calls	LLM proxy orchestration
Tier 3 Execution	Local state + sync	Federation coordination
Lineage Tracking	Primary (SQLite)	Backup (PostgreSQL)
Authorization	Consent tier enforcement	Zone-based trust scoring

Data Model Mapping

Client Concept	Server Concept	Mapping
Ritual	Pattern (type=ritual)	Local → Federated registry
Lineage Entry	Lineage Event	Client primary → Server backup
Consent Tier (0–3)	Zone (Z0–Z4)	Tier 0→Z0, Tier 1→Z1, Tier 2→Z2, Tier 3→Z3–Z4
Operating Mode	Request Context	Metadata in API calls

Forge Endpoints

Endpoint	Purpose	Tier	Status
GET /health	Health check	Tier 2+	Live
GET /api/patterns	Federated ritual catalog	Tier 3	Live
POST /api/patterns	Publish ritual to federation	Tier 3	Live
POST /api/lineage/sync	Federation lineage sync (CBOR)	Tier 3	Live
GET /api/lineage/safety-audit	Fetch remote safety audit trail	Tier 3	Live
GET /api/actor/identity	Fetch actor identity + trust score	Tier 3	Planned

Authentication: Bearer token in device keychain; forge handles dev vs prod routing via manifest context.

Codebase Structure

packages/
├── udg/                    # Universal Design Grammar (shared package)
│   └── lib/src/
│       ├── tokens.dart         # ColorToken, TypeToken, SpaceToken, RadiusToken enums + resolvers
│       ├── token_registry.dart # Canonical hex/numeric values (light + dark)
│       ├── token_manifest.dart # Dotted-name → enum map (round-trip validation)
│       ├── udg_theme.dart      # ThemeData builder (UDGTheme.light() / .dark())
│       ├── udg_constraints.dart # UDGConstraints, KeyboardFocusIndicator, ArrowKeyListNavigator
│       └── udg_context.dart    # context.udg extension (color, space, breakpoint, …)
├── rituals_core/           # Shared pure-Dart logic (SafetyEngine, TemplateEngine, LineageHasher, domain models)
├── forge_auth_config/      # Keycloak PKCE configuration
├── forge_client/           # Typed Forge SDK HTTP client + auth
├── ritual_engine/          # Rust KV cache FFI library (compiled via Cargokit)
├── ritual_engine_builder/  # Cargokit build helper — compiles ritual_engine.a
└── ritual_cli/             # ritual CLI package (forge tooling)

lib/
├── core/
│   ├── state_machine.dart       # AppStateMachine (17 UIStates)
│   ├── safety_engine.dart       # Risk detection + blocking
│   ├── safety_ledger.dart       # SafetyDecisionRecord persistence
│   ├── template_engine.dart
│   ├── prompt_execution_engine.dart  # Tier 1+ model dispatch + response handling
│   ├── ritual_shell.dart        # Execution shell wrapping model runners
│   └── lineage/                 # LineageLedger, LineageHasher
├── data/
│   ├── database.dart            # SQLite schema (v11), migrations
│   ├── models.dart              # Ritual, Lineage, Consent, Sync models
│   ├── repositories.dart        # Typed repository classes
│   ├── forge_api_client.dart    # Forge HTTP client (auth + endpoints)
│   ├── forge_event_stream.dart  # SSE stream (Tier 2+, eventflux)
│   ├── forge_background_sync.dart  # Background sync via workmanager
│   ├── forge_join_client.dart   # Federation device identity (Tier 3)
│   ├── apple_foundation_models_runner.dart  # Tier 1: Apple Foundation Models (iOS 27+ / macOS 27+)
│   ├── mlx_localllm_runner.dart             # Tier 1: Apple Silicon MLX
│   ├── anthropic_model_runner.dart          # Tier 1+: Anthropic-compatible endpoint
│   ├── kagi_model_runner.dart               # Tier 1+: Kagi
│   ├── openai_compatible_model_runner.dart  # Tier 1+: OpenAI-compatible local/remote
│   ├── ritual_engine_bridge.dart            # Rust FFI bridge (ritual_engine KV cache)
│   ├── ritual_engine_model_runner.dart      # Rust-engine-backed runner
│   ├── lineage_cbor_encoder.dart            # CBOR serialisation for lineage sync
│   ├── guise_repository.dart                # Guise (persona/context profile) persistence
│   ├── guise_store.dart                     # In-memory guise cache
│   ├── guise_audit_buffer.dart              # Guise audit event buffer
│   ├── guise_audit_publisher.dart           # Guise audit event publisher
│   ├── schema_cache.dart                    # Ritual schema caching
│   ├── telemetry_client.dart                # Analytics event emission
│   └── sso_repository.dart                  # SSO session management
├── app/
│   ├── rituals_app.dart    # Root widget + state router (17-case switch)
│   └── state/
│       ├── app_controller.dart  # ChangeNotifier, all business logic
│       └── models.dart          # OperatingMode, ConsentTier, AppError
├── ui/screens/             # 20 screens — one per UIState + token gallery + chronicle + guise list
└── widgets/
    ├── ambient/            # UdgAmbientLayer (shader-backed ambient; GLSL shaders in assets/shaders/)
    └── ...                 # ModeCard, RitualCard, ConsentTierBadge, DecisionLogScreen

Platform Toolchains (Phase 6+)

Platform-specific extensions are added as Git submodules after MVP and communicate via Flutter platform channels. Core app degrades gracefully when toolchains are absent.

Design Philosophy

Inert by Default

No automation runs without explicit human consent. The system defaults to the most restrictive state and requires progressive unlocking.

Progressive Consent

Users advance through 4 tiers:

• Tier 0: No AI, governance tools only
• Tier 1: On-device AI (Apple Foundation Models on iOS 27+ / macOS 27+; Apple Silicon MLX; OpenAI-compatible local endpoints)
• Tier 2: Remote LLM via Forge proxy
• Tier 3: Federation & external systems

Ethical Transparency

Every action produces auditable lineage records. Limitations are visible, not hidden. Safety boundaries are explicit and educational.

Universal Design

The system compiles to Universal Design Grammar (UDG) without platform-specific logic. All constraints are deterministic and machine-inspectable.

Universal Design Grammar

Tokens

Category	Tokens
Color	color.text.primary, color.text.secondary, color.bg.surface, color.bg.surface.raised, color.border.default, color.accent.consent, color.accent.warning, color.accent.success
Typography	type.heading.lg, type.heading.md, type.body.md, type.body.sm, type.code.sm
Spacing	space.2 (8px), space.3 (12px), space.4 (16px), space.6 (24px), space.8 (32px)
Radius	radius.sm (4px), radius.md (8px)

Source: packages/udg/lib/src/tokens.dart, packages/udg/lib/src/token_registry.dart

Layout Primitives

• Structure: Column (primary container), Row (action bars, metadata strips), Grid (ritual library, consent matrix)
• Gaps: gap: space.4 for vertical flows, gap: space.3 for horizontal action groups
• Sizing: Max container width 1200px, max primary content column 840px, min touch target 44px, fill-available for full-bleed modals

Universal Constraints

Constraint	Rule
Layout	Max width 1200px
Layout	Min touch target 44×44px
Interaction	Execute disabled if consent tier insufficient
Interaction	Mode selection disabled until onboarding complete
Interaction	Consent revocation disabled during active ritual execution
Typography	Scale step ≤ 1 between body and heading sizes
Safety	External actions require SafetyEngine review

Allowed / Forbidden (§7a)

Allowed: Solid fills, solid strokes, tokenized corner radius, single drop shadow for raised surfaces

Forbidden: Gradients, blur or blend modes, freeform positioning, ad-hoc typography

UI States

Seventeen machine-inspectable states drive the app via AppStateMachine (lib/core/state_machine.dart):

State	Description
inert	System default — all features disabled, splash only
onboarding	6-step guided flow, collects identity at step 3
modeSelection	Mode cards (Observatory, Workshop, Pilgrimage, Sanctum, Federation)
consentRequest	Tier upgrade ceremony — grant / cancel
ritualLibrary	Grid of user rituals, filter/search, create action
ritualCreation	Creation form — title, description, input params, tier selector
ritualExecution	Dynamic input fields + live preview, safety status, execute
lineageReview	Timeline of lineage entries, hash verification, export, safety audit nav
lineageVisualization	Inbox+thread lineage graph view
forgeJoin	Device identity ceremony for forge federation (Tier 3)
rubricList	Rubric library grid
rubricCreation	New rubric form
rubricDetail	Single rubric detail view
wishEntry	Wish form — the white room
decisionLog	Safety audit trail — list of all SafetyEngine decisions
settings	App settings, consent tier management, and feature flag controls
error	Inline (field validation) or modal (system errors) with recovery actions

State Transitions (abbreviated)

inert → onboarding → modeSelection ↔ consentRequest
modeSelection → ritualLibrary → ritualCreation → ritualLibrary
ritualLibrary → ritualExecution → lineageReview → lineageVisualization
lineageReview → decisionLog
modeSelection → rubricList → rubricDetail / rubricCreation
modeSelection → wishEntry / forgeJoin / settings
settings → modeSelection
Any → error

Error Handling

• Error conditions: Insufficient consent tier, SafetyEngine block, invalid ritual schema, network unavailable (Tier 2+), lineage verification failure
• Placement: Inline for field validation, modal for system errors, toast for non-blocking warnings
• Recovery actions: Grant higher consent tier / Review and modify ritual / Retry with adjusted inputs / View lineage details
• Errors must use tokenized styling, deterministic layout, max 3 lines (truncate with "View details" link)

Accessibility

• Focus order: Logical reading order, modal traps focus until dismissed
• Keyboard: Tab navigates all elements, Enter activates, Escape cancels modals, arrow keys for timeline
• Screen reader: role="dialog" for modals, aria-label for icon-only buttons, aria-live="polite" for status updates
• Contrast: Minimum 4.5:1 for body text, 3:1 for large text and UI components

Outstanding accessibility work → #29 Touch & Interaction

Analytics & Telemetry

Events: onboarding_completed, mode_selected, consent_granted, consent_revoked, ritual_executed, ritual_blocked, lineage_exported

Properties: consent_tier, mode, ritual_id, safety_decision, execution_duration_ms

Success metrics: Onboarding completion rate, consent progression rate (Tier 0 → Tier 1), ritual execution success rate, SafetyEngine block rate

Implementation → #25 Analytics & Telemetry

Dependencies & Feature Flags

Backend dependencies:

• SQLite for ledger storage (Tier 0–1)
• On-device model runtime (Tier 1): Apple Foundation Models, Apple Silicon MLX, or compatible local endpoint → #19
• HTTP client + SSE stream for Forge access (Tier 2) → #30
• Forge SDK client + Keycloak PKCE auth (Tier 3) → #31

Feature flags → #32:

• federation_mode_enabled (default: false)
• tier_3_external_apis_enabled (default: false)

Performance constraints: Lineage queries < 500ms, ritual execution < 5s (local model)

Open Questions

• How granular should lineage export formats be (JSON, CSV, human-readable markdown)? → #17 (export decisions)
• Should SafetyEngine allow user overrides with additional consent ceremony? → Tier 2+ override ceremony is implemented; question is how far Tier 0–1 enforcement should go → #89
• Lineage archival strategy after growth → #18

Risks:

• Users may perceive progressive consent as friction rather than safety — mitigate by framing as "leveling up" in dojo progression
• Lineage artifacts may grow large over time — mitigate with archival/summarization after 90 days → #18
• Local model performance may not meet expectations — set clear expectations in onboarding and Tier 1 consent ceremony

Getting Started

Prerequisites

• Flutter 3.47.5 (pinned in .fvmrc; dart run tool/check_toolchain_pins.dart enforces it)
• Rust toolchain (rustup target add aarch64-apple-darwin) — required for ritual_engine native build
• Network access to git.toilville.dev — forge-kv-cache and mlx-rs-mirror are public HTTPS git dependencies (no account needed)

See QUICKSTART.md for full per-platform setup instructions.

Setup

flutter pub get
flutter run -d macos

Testing

flutter test

Native macOS / iOS app (Xcode) — first run

The native SwiftUI app lives in apps/rituals-macos. These are the steps for running it in Xcode for the first time. The full guide, including troubleshooting, is apps/rituals-macos/DEVELOPER_GUIDE.md.

1. Select Xcode 27 and accept its license (one time):

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -license accept
   sudo xcodebuild -runFirstLaunch
   

2. Install the tools: brew install xcodegen cmake sccache fvm, plus Rust via rustup.
3. Check the forge git dependencies: the Rust engine fetches forge-kv-cache and mlx-rs-mirror from public HTTPS repos, so no key is needed. git ls-remote https://git.toilville.dev/Toilville/forge-kv-cache.git HEAD should print a ref; if it doesn't, the build fails.
4. Prepare the repo (from the repo root):

   git config core.hooksPath .githooks
   fvm use
   flutter pub get
   

5. Check the machine: bash tool/check_runner_host.sh lists every missing prerequisite at once. You can ignore the Docker warning on a dev machine.
6. Open the project, not the workspace: open apps/rituals-macos/Rituals.xcodeproj. Wait for Swift package resolution to finish; the first time can take about 10 minutes.
7. Sign in: in Xcode → Settings → Accounts, add an Apple ID on the Toilville LLC team (72D54NN2X5). Signing is automatic, and Xcode creates your profile on the first build.
8. Run: choose scheme Rituals and destination My Mac, then press ⌘R. The first build also compiles the Rust ritual_engine and exports the UDG tokens and schema. Two notes in the build log are expected: "ritual CLI not found" and "RITUAL_ENGINE_FORCE_NO_MLX=1".
9. Test (optional): press ⌘U. UI tests need you logged in at the machine.

Change build settings in apps/rituals-macos/project.yml and run xcodegen generate, not in Xcode's Build Settings editor. Rituals.xcodeproj is generated from project.yml, so regenerating it discards anything set only in Xcode.

§11a Validation Targets

spec.txt §11a defines two validation targets that verify the UDG spec is correctly implemented.

Linebender Render Validation

Validates geometry & token correctness: all colors, radii, and spacing resolve to UDG token values; §7a forbidden constructs (gradients, blurs, freeform positioning) are absent.

# Static analysis — runs in CI on every PR
dart run tool/tokens_enforcer.dart

# Token export correctness (Linebender JSON payload)
dart run tool/udg_validate.dart

# §7a forbidden list — also covered by flutter test
flutter test test/udg/spec_7a_forbidden_test.dart

ImGui Semantic Validation

Validates structure & intent: onboarding flow transitions, consent gate enforcement, ritual execution invariants.

# Run all semantic suites (onboarding, consent, execution)
dart run tool/imgui_semantic_validate.dart

# Or run the underlying test suites directly
flutter test test/core/state_machine_test.dart
flutter test test/app/consent_tier_enforcement_test.dart
flutter test test/app/app_controller_test.dart

Both validators run automatically in CI on every pull request to main.

References

• Architecture Plan: ARCHITECTURE_PLAN.md — forge integration model, sync protocols
• Rust Engine: RUST_ENGINE_ARCHITECTURE.md — server-side implementation plan
• Extensions: EXTENSIONS.md — platform toolchain guide
• Project Board: Forgejo — toilville_rituals
• SPELWork Framework: Progressive consent, 18 dimensions, ritualized workflows

---

Appendix A: Component Inventory

OnboardingFlow

• Props: step: number, totalSteps: number, canProceed: boolean, onNext: () => void, onBack: () => void
• Slots: content, actions
• Variants: none

ConsentGate

• Props: currentTier: 0|1|2|3, requestedTier: 0|1|2|3, isRevocable: boolean, onGrant: () => void, onCancel: () => void
• Slots: description, warnings, actions
• Variants: tier-0, tier-1, tier-2, tier-3

RitualCard

• Props: id: string, title: string, mode: string, consentTierRequired: number, status: 'draft'|'active'|'archived', onExecute: () => void, onEdit: () => void
• Slots: metadata, actions
• Variants: compact, expanded

LineageTimeline → #133

• Props: entries: LineageEntry[], onSelectEntry: (id: string) => void
• Slots: entry (repeating)
• Variants: none

DojoFeedbackCard → #21

• Props: dimensions: string[], consentPosture: string, lineageScore: number, nextSteps: string
• Slots: none
• Variants: none

SafetyIndicator

• Props: status: 'allow'|'block'|'allow_with_review', reason?: string, mitigation?: string
• Slots: none
• Variants: allow, block, allow_with_review

---

Appendix B: UDG Lowering Notes

• Onboarding flow: Must render as sequential Column with enforced step progression (no skip-ahead). Each step is a discrete layout state.
• Consent gates: Must render with explicit visual hierarchy — warnings callout with distinct background token, action buttons with clear primary/secondary distinction.
• Lineage timeline: Must support both compact (list) and expanded (timeline with branching) representations. Branching logic must be deterministic based on ritual version ancestry.
• Modal overlays: Must use explicit z-index tokens and overlay background token. Focus trap must be enforced at layout level, not via JavaScript.
• Safety indicator states: Must use distinct color tokens per state (success, warning, error) with fallback icon representations for accessibility.

---

Appendix C: What We've Built and Why It Matters

This appendix is an executive summary for contributors, stakeholders, and anyone joining the project mid-stream. It answers the question: what actually exists in this repository, and how does it connect to the larger Toilville product vision?

The problem this solves

Most consumer AI tools give users a text box and a submit button. There is no record of what was sent, no audit trail of decisions, no way to understand what tier of capability is being invoked, and no ceremony around consent. Users don't know what they're agreeing to, can't trace what happened, and have no way to build a practice around it.

Toilville Rituals is a deliberate counterpoint to that. It treats AI-assisted workflows as something worth learning carefully — like a dojo teaches a martial art. The system is inert by default, tracks everything in an immutable lineage, and requires progressive consent to unlock higher tiers of capability. Every boundary the user crosses is explicit and auditable.

What's built

The foundation (Phase 0 — complete)

The state machine, UDG token system, SQLite schema, and SafetyEngine are all live. Seventeen UI states route correctly. The Universal Design Grammar is extracted as a shared package (packages/udg/) with a token registry, theme builder, and layout primitives used by every screen. The forge API client is wired and gated behind Tier 2+ consent. CI runs Linebender render validation and ImGui semantic validation on every PR.

Tier 0 execution (partially complete)

Template-based ritual execution works end-to-end: users create rituals with parameterized input fields, fill them at execution time, and the system interpolates the template and writes a lineage entry to SQLite with a SHA256 hash. No AI model is invoked. This is the entire Tier 0 value proposition — structured, auditable, zero-AI practice.

Consent infrastructure (complete)

ConsentGate, consent tier enforcement, and the ConsentRequest screen are built. The three-layer enforcement model works: the system checks the user's current tier at every execution boundary, gates mode selection, and routes to a consent upgrade flow when needed. Consent is revocable.

Safety layer (complete)

SafetyEngine runs pre-execution risk detection, blocks risky automation attempts, logs decisions, and supports an override ceremony with additional consent. Decision logs are written to lineage.

Onboarding (complete)

A single unified 6-step guided flow collects both conceptual context (consent tiers, lineage) and user identity (legal name, work email, preferred name) in one sequence. Identity is stored locally in app_settings; forge API sync defers to first Tier 2 consent grant.

UI foundations (complete)

Ritual CRUD, the library grid, creation form, and execution interface are all built as working screens. Token alignment passes have been run on the library and creation form. Keyboard navigation, screen reader support, and WCAG 2.1 AA color contrast are implemented across the app.

Federation device identity (complete)

The ForgeJoin screen and federation device identity flow exist. This is the UI entry point for Tier 3 — the ceremony where a device joins the forge federation.

What's in progress

Rubric system, wish entry flow, settings screen, and federation Tier 2–3 full-flow testing are all in active iteration. Guise (persona/context profile) infrastructure is wired in data layer. See the project board for current sprint state.

How this accrues to the Toilville product

Toilville Rituals is the consumer-facing proof of the SPELWork model. It exists to demonstrate — concretely, in a running app — that the principles behind SPELWork (progressive consent, lineage, inert-by-default, ethical transparency) are not just theoretical. They can be shipped.

Every architectural decision in this repo is a reusable pattern:

What's built here	How it accrues
UDG token system + shared package	Design system substrate for all Toilville products
Progressive consent tiers (0–3)	The consent model Rituals Web, Steward, and ToilMail will implement
Lineage ledger (SQLite → PostgreSQL sync)	The audit infrastructure for the full forge federation
SafetyEngine + decision logging	The safety substrate for any AI-assisted Toilville tool
Forge API client + federation device join	The Tier 3 integration pattern all consumer clients will follow
State machine (17 UIStates)	The navigation model for future screens and modes

The forge infrastructure (~/.spel) is the server-side counterpart — PostgreSQL, Kafka, Rust ritual-engine, Vault, Keycloak. Rituals is the first consumer client to wire against it. When Tier 2–3 features land, the lineage this app writes will sync to core.lineage_events on the forge, closing the loop between the consumer practice layer and the federated trust infrastructure.

The long arc

The dojo metaphor is not decorative. The system is designed so that a user who starts at Tier 0 — filling in templates, building a practice, reviewing their lineage — earns their way into higher tiers through deliberate progression. By the time they reach Tier 3 (Federation), they understand what they're consenting to because the system has taught them at every step.

That arc — from zero-AI governance practice to federated AI participation — is what Toilville is building. This repository is where the user experience of that arc lives.

---

Copyright © 2024-2026 Toilville LLC. Licensed under the Apache License, Version 2.0; third-party components are listed in NOTICE.