An audio-first adaptive walking experience.
You move. Lira moves with you. The world responds. Bond grows.

Concept visual. The hero communicates product direction and is not evidence of implemented application graphics or AR functionality. See docs/assets/BRAND_GUIDE.md.

---

Why Waykin?

Waykin transforms an ordinary walk into a shared journey with a persistent digital companion. Rather than reducing movement to scores or competition, it focuses on presence, relationship, discovery, tension, and memory.

A walk produces semantic world state. That state generates bounded events. Events shape Lira, pursuit pressure, audio cues, session memories, and Bond—without requiring a backend or generative-AI runtime.

The launch product remains intentionally small enough for one developer to understand, test, and ship.

Core Experience

	Pillar	Current contract
🚶	Real movement	Walking is the launch activity and primary gameplay input.
✨	Persistent companion	Lira is the single companion and responds through a bounded behavior vocabulary.
🌎	Adaptive world	Seeded events emerge from movement, context, familiarity, energy, and pressure.
🎧	Semantic audio	Audio communicates presence, discovery, pressure, transition, and Bond.
🏃	Bounded pursuit	Tension exists without punishment, coercion, or an enemy-platform expansion.
❤️	Bond	One persistent progression measure represents the relationship with Lira.

The binding product contract is WAYKIN_SPEC.md. Future-state documents do not authorize implementation unless promoted through the repository’s governance process.

Current Product Loop

Home
  → Begin Walk (real) / Demo Walk
  → Active Session
  → Session Summary
  → Memory

Demo Mode runs the same deterministic loop without physical movement or location permission.

Current MVP

Capability	State	Evidence boundary
Walking session loop	✅ Implemented	Package and native tests
Lira companion runtime	✅ Implemented	Deterministic runtime tests
Bond progression	✅ Implemented	Local persistence tests
Semantic audio cues	✅ Implemented	Device playback still requires direct evidence
Deterministic Demo Mode	✅ Implemented	Package-testable
Local session memories	✅ Implemented	Concise, privacy-bounded facts
Real-walk Core Location wiring	🟡 Validation	Outdoor GPS requires device receipts (#41)
AR app adapter (MVP)	✅ Implemented (frozen)	Presentation-only; outdoor tracking PARTIAL / re-walk (#41)
Packaged companion (Ember Fox)	✅ Implemented (#246)	Async load + procedural fallback + live replace; device outdoor evidence still open
Path progress + session map	✅ Implemented	Semantic path, not navigation-grade
HealthKit read enrichment	✅ Implemented	Soft context; physical HK evidence open
Multiplayer, marketplace, LiveOps	🔒 Deferred	Outside current scope
Generalized AI Director	🔒 Future reference	Not current implementation authority

See the complete Current Capability Matrix. AR redesign planning (supporting only): AR Product Redesign Map · long-term North Star · MVP → Vision Ladder.

Quick Start

Requirements

• macOS with a compatible Xcode installation
• Swift 6 toolchain
• XcodeGen
• An iOS Simulator for simulator validation

Build and Validate

git clone https://github.com/scrimshawlife-ctrl/Waykin.git
cd Waykin

make build
make test
make validate
make validate-simulator

make validate-simulator targets iPhone 17 Pro by default. Override it with:

WAYKIN_SIMULATOR_NAME="iPhone 17 Pro" make validate-simulator

Run the Deterministic Demo

make demo

Runtime Architecture

WaykinCore owns semantic gameplay truth. SwiftUI, MapKit, SwiftData, Core Location, AVFoundation, ARKit, and RealityKit remain adapters or presentation concerns.

The core knows semantic state and semantic audio cue kinds. It does not know UI layout, asset filenames, route-provider details, AR entities, or platform persistence implementation.

See ARCHITECTURE.md for ownership, dependency direction, AR boundaries, and deferred seams.

Implemented Surface

• Deterministic walking-session state machine
• Real-sample movement integrity processing
• Seeded, weighted, cooldown-aware event generation
• Lira companion runtime
• Bounded pursuit state
• Seven semantic audio cue kinds
• App-target AVAudioPlayer adapter with safe-silence fallback
• SwiftData persistence for Bond and concise session memories
• Deterministic Demo Mode
• When-In-Use Core Location wiring for physical-device walks
• Privacy-filtered local field-test receipts
• Platform-neutral AR presentation contracts

Compatibility values for running, cycling, hiking, and climbing may remain in source models, but walking is the only current product activity.

Scope Boundaries

Waykin does not currently include:

• Accounts, authentication, or backend infrastructure
• Multiplayer or social graphs
• Marketplace or creator systems
• Generative-AI runtime behavior
• Generalized narrative engines
• LiveOps, currencies, inventory, or skill trees
• Wearable dependence
• AR-glasses dependence
• Live weather integration

Future-state specifications are reference material until promoted through an accepted issue, architecture review, and—when necessary—an ADR. See DOCUMENT_AUTHORITY.md and SPEC_PROMOTION_PROCESS.md.

Safety and Privacy

Legal and safety documents live under docs/legal/ (Privacy, Terms, Safety brief, Notices). Source code is Apache 2.0.

• Waykin is not safety equipment or medical advice.
• Location is requested only during an active real walk.
• Demo Mode requires no location permission.
• Pause and stop behavior remain available.
• Pursuit must never pressure a user to continue through distress or unsafe conditions.
• Memories are concise deterministic facts, not precise route archives.
• Field receipts exclude coordinates and personal memory text, retain at most 20 files, and never upload automatically.
• First-run onboarding includes a safety acknowledgment; Settings → Legal can reopen notices.

Validation Status

Workflow badges report the current main branch state. Re-run locally:

make validate          # package + generation + native app build
make test              # Swift package tests (count changes over time)
# optional: make validate-simulator

Layer	Command or protocol	How to read
Swift package	make build / make test	CI + local; counts are not frozen in this table
Canonical harness	make validate	Required before merge claims
Simulator UI	make validate-simulator / UITests	Sim evidence only
Outdoor AR (historical)	Device receipt 2026-07-20	PARTIAL — continuity/audio notes; not GPS FAIL
Outdoor COH PASS	Issue #41 re-walk on tip SHA	Open until daylight device evidence

Do not claim GPS, outdoor audio loudness, battery, thermal, outdoor usability, interruption recovery, or outdoor AR quality without direct device evidence on a named build.

Roadmap

Waykin progresses by proving one bounded layer before promoting the next:

1. Physical loop proof — outdoor GPS, audio audibility, and interruption evidence (#41).
2. AR outdoor evidence — re-walk continuity + COH after code mitigations (app-target AR already frozen for engineering).
3. Experience tuning — outdoor balance of produced cues and event weights from device receipts (engineering tones already replaced).
4. Future systems — Watch / AI Directors only through explicit promotion after MVP evidence gates.

See ROADMAP.md for milestones, status labels, and promotion gates.

Repository Guide

Waykin/
├── App/                  iOS presentation and platform adapters
├── AppTests/             Native app tests
├── Sources/WaykinCore/   Platform-neutral semantic runtime
├── Tests/                Swift package tests
├── docs/                 Documentation, evidence, governance, and assets
├── scripts/              Canonical validation harnesses
├── WAYKIN_SPEC.md        Binding product contract
├── ARCHITECTURE.md       System ownership and dependency direction
├── AGENTS.md             Coding-agent operating contract
├── CONTRIBUTING.md       Human collaboration workflow
└── ROADMAP.md            Evidence-gated product progression

Where to Start

1. Read WAYKIN_SPEC.md.
2. Read ARCHITECTURE.md.
3. Open the Documentation Portal.
4. Contributors read CONTRIBUTING.md.
5. Coding agents also read AGENTS.md.

Contributor Flow

Every pull request states its authority context, allowed and frozen systems, validation evidence, device-evidence status, risk, and rollback path.

Documentation Portal

Area	Start here
Product	WAYKIN_SPEC.md · SOLO_MVP_SCOPE.md · ROADMAP.md
Engineering	ARCHITECTURE.md · CURRENT_CAPABILITY_MATRIX.md
Validation	KNOWN_LIMITATIONS.md · PHYSICAL_DEVICE_WALK_VALIDATION.md · FIELD_TEST_PROTOCOL.md
Collaboration	CONTRIBUTING.md · AGENTS.md
Governance	DOCUMENT_AUTHORITY.md · SPEC_PROMOTION_PROCESS.md · MASTER_PACK_INDEX.md
Visual identity	BRAND_GUIDE.md

Browse the complete Waykin Documentation Portal.

Contributing

Waykin uses issue-scoped branches, small draft pull requests, explicit scope boundaries, and evidence-backed validation.

Start with CONTRIBUTING.md. Coding agents must also read AGENTS.md before modifying the repository.

License

Licensed under the Apache License 2.0.