From 6660ca4d9beddae749ec21c2854da99a3457b30d Mon Sep 17 00:00:00 2001 From: Daniel Date: Wed, 29 Jul 2026 19:16:33 -0700 Subject: [PATCH 1/2] docs: promote AR-designed product identity (#252) --- .../waykin-ar-debug/references/REPO_CONTEXT.md | 2 +- .grok/skills/waykin-audio/SKILL.md | 2 +- .../skills/waykin-audio/references/REPO_CONTEXT.md | 2 +- .../skills/waykin-build/references/REPO_CONTEXT.md | 2 +- .../references/REPO_CONTEXT.md | 2 +- .../waykin-healthkit/references/REPO_CONTEXT.md | 2 +- .../waykin-performance/references/REPO_CONTEXT.md | 2 +- .../waykin-pr-review/references/REPO_CONTEXT.md | 2 +- .../waykin-release/references/REPO_CONTEXT.md | 2 +- .../waykin-ui-review/references/REPO_CONTEXT.md | 2 +- .../waykin-validate/references/REPO_CONTEXT.md | 2 +- ARCHITECTURE.md | 7 ++++--- App/AppAudioCuePlayer.swift | 2 +- App/Info.plist | 2 +- Demo/main.swift | 2 +- README.md | 6 +++--- WAYKIN_SPEC.md | 14 ++++++++------ docs/SOLO_MVP_SCOPE.md | 8 ++++---- .../ADR-0003-local-first-swiftdata-persistence.md | 2 +- docs/design/ART_DIRECTION_SIGN_OFF.md | 2 +- docs/design/AR_MVP_FREEZE.md | 2 +- docs/design/AR_PRODUCT_REDESIGN_MAP.md | 14 +++++++------- docs/design/AR_SESSION_IA_CONFLICTS.md | 12 ++++++------ docs/design/CONTINUATION_PLAN.md | 2 +- docs/design/LIRA_ANIMATION_PLAN.md | 2 +- docs/design/LIRA_PRODUCTION_ART_PIPELINE.md | 2 +- docs/design/README.md | 2 +- docs/legal/TERMS.md | 2 +- docs/plans/AR_APP_REDESIGN_PLAN.md | 4 ++-- project.yml | 2 +- skills/_shared/references/REPO_CONTEXT.md | 2 +- skills/waykin-audio/SKILL.md | 2 +- 32 files changed, 59 insertions(+), 56 deletions(-) diff --git a/.grok/skills/waykin-ar-debug/references/REPO_CONTEXT.md b/.grok/skills/waykin-ar-debug/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-ar-debug/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-ar-debug/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-audio/SKILL.md b/.grok/skills/waykin-audio/SKILL.md index f8f59e6..8e6c1fe 100644 --- a/.grok/skills/waykin-audio/SKILL.md +++ b/.grok/skills/waykin-audio/SKILL.md @@ -12,7 +12,7 @@ metadata: # waykin-audio -Waykin is **audio-first**. Semantic cues are Core; filenames and AVAudioSession are App. +Waykin is **AR-designed**, with audio as a required supporting channel for presence, accessibility, safety, and pocket use. Semantic cues are Core; filenames and AVAudioSession are App. ## 0. Ownership diff --git a/.grok/skills/waykin-audio/references/REPO_CONTEXT.md b/.grok/skills/waykin-audio/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-audio/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-audio/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-build/references/REPO_CONTEXT.md b/.grok/skills/waykin-build/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-build/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-build/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-device-testing/references/REPO_CONTEXT.md b/.grok/skills/waykin-device-testing/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-device-testing/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-device-testing/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-healthkit/references/REPO_CONTEXT.md b/.grok/skills/waykin-healthkit/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-healthkit/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-healthkit/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-performance/references/REPO_CONTEXT.md b/.grok/skills/waykin-performance/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-performance/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-performance/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-pr-review/references/REPO_CONTEXT.md b/.grok/skills/waykin-pr-review/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-pr-review/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-pr-review/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-release/references/REPO_CONTEXT.md b/.grok/skills/waykin-release/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-release/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-release/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-ui-review/references/REPO_CONTEXT.md b/.grok/skills/waykin-ui-review/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-ui-review/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-ui-review/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/.grok/skills/waykin-validate/references/REPO_CONTEXT.md b/.grok/skills/waykin-validate/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/.grok/skills/waykin-validate/references/REPO_CONTEXT.md +++ b/.grok/skills/waykin-validate/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a254d34..9c0c0c0 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Waykin Architecture -Waykin is currently a solo-developer MVP vertical slice, not a platform. The architecture is bounded around one walking loop and five primary runtime systems. +Waykin is an AR-designed solo-developer MVP vertical slice, not a platform. Movement remains gameplay authority. AR is the primary designed session surface when capability allows, while audio, 2D presence, map, and HUD are supporting presentation channels over the same semantic state. ## Runtime Flow @@ -36,10 +36,11 @@ SessionMemory + Bond - Movement Engine: owns session transitions, elapsed and active time, distance, speed, route points, simulation, and accepted real walking samples. - World State: derives serializable session context from local movement signals, Bond, time context, familiarity, energy, and pressure. - Event Generator: emits zero or one deterministic semantic event per tick using a seeded, weighted, cooldown-aware configuration. -- Companion presentation matrix: single source for behavior + relative distance + AR presentation string mapping (`CompanionPresentationMatrix`). +- Companion presentation matrix: single source for behavior + relative distance + shared presentation mapping (`CompanionPresentationMatrix`). - Companion Runtime: applies experience commands (and event overlays) into Lira’s small behavior vocabulary. - Audio Experience Layer: maps world events and companion behavior transitions onto the seven semantic cue kinds (priority + cooldown); path soft cues use the same kinds via `PathAudioCoupling` when event/behavior audio is silent. -- App Audio Adapter: maps cue kinds to bundled produced WAVs, enforces a two-channel playback bound, and owns Apple audio-session lifecycle behavior. +- AR Presentation Adapter: maps semantic state through `ARWorldCommand` into the primary designed session surface on capable devices without owning gameplay truth. +- App Audio Adapter: maps cue kinds to bundled produced WAVs, enforces a two-channel playback bound, and owns pocket-safe Apple audio-session lifecycle behavior. - Path progress: semantic on-path / strained / offPath presentation (not navigation). Persistence supports Bond and concise memories. It is not a generalized backend or content platform. diff --git a/App/AppAudioCuePlayer.swift b/App/AppAudioCuePlayer.swift index 948a481..16845fb 100644 --- a/App/AppAudioCuePlayer.swift +++ b/App/AppAudioCuePlayer.swift @@ -148,7 +148,7 @@ extension AVAudioSession: AudioSessionControlling { } func configureAmbientMixing() throws { - // `.playback`, not `.ambient`. Waykin is an audio-first walking experience: + // `.playback`, not `.ambient`. Audio is a required pocket-safe supporting channel: // - `.ambient` is silenced by the hardware ring/silent switch (cues inaudible). // - `.ambient` stops on backgrounding, so audio died whenever the screen locked // or the phone went in a pocket β€” i.e. during the actual walk. diff --git a/App/Info.plist b/App/Info.plist index d0d9b9b..0dbfec6 100644 --- a/App/Info.plist +++ b/App/Info.plist @@ -34,7 +34,7 @@ UIApplicationSupportsIndirectInputEvents - UIBackgroundModes diff --git a/Demo/main.swift b/Demo/main.swift index ba44fa0..30970e3 100644 --- a/Demo/main.swift +++ b/Demo/main.swift @@ -2,7 +2,7 @@ import Foundation import WaykinCore print("=== WAYKIN SOLO MVP DEMO ===") -print("Deterministic audio-first walking loop; no GPS or permissions required.\n") +print("Deterministic AR-designed walking loop with semantic presentation output; no GPS, camera, or permissions required.\n") let movement = MovementEngine() let companion = Companion(id: UUID(), name: "Lira", archetype: "explorer", bondLevel: 12, lastSessionID: nil, memories: []) diff --git a/README.md b/README.md index 5b42402..4aad879 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@

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

@@ -48,9 +48,9 @@ The launch product remains intentionally small enough for one developer to under | | 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. | +| ✨ | **AR companion presence** | Lira is the single companion and AR is her primary designed session surface when capability allows. | | 🌎 | **Adaptive world** | Seeded events emerge from movement, context, familiarity, energy, and pressure. | -| 🎧 | **Semantic audio** | Audio communicates presence, discovery, pressure, transition, and Bond. | +| 🎧 | **Supporting semantic audio** | Audio preserves presence, discovery, pressure, transition, accessibility, and pocket-safe continuity. | | πŸƒ | **Bounded pursuit** | Tension exists without punishment, coercion, or an enemy-platform expansion. | | ❀️ | **Bond** | One persistent progression measure represents the relationship with Lira. | diff --git a/WAYKIN_SPEC.md b/WAYKIN_SPEC.md index e94d37b..69cf2dc 100644 --- a/WAYKIN_SPEC.md +++ b/WAYKIN_SPEC.md @@ -9,7 +9,7 @@ ## Product Contract -Waykin is an audio-first adaptive walking experience in which one persistent companion, Lira, and one bounded pursuit-pressure state respond to how the user moves. +Waykin is an AR-designed adaptive walking experience in which one persistent companion, Lira, and one bounded pursuit-pressure state respond to how the user moves. Movement is gameplay authority; AR is the primary designed session surface when capability allows, with audio, 2D presence, map, and HUD as supporting presentation channels. The current product is a solo-developer MVP vertical slice. Complexity belongs in deterministic data and configuration, not in additional platforms or generalized systems. @@ -19,10 +19,10 @@ The current product is a solo-developer MVP vertical slice. Complexity belongs i 2. World State and deterministic Event Generator 3. Lira Companion Runtime 4. Bounded Pursuit State -5. Semantic Audio Experience -6. Local Bond and concise Session Memory persistence -7. Privacy-filtered local field-test receipts -8. Platform-neutral AR presentation contracts and milestone-scoped app adapters +5. AR Presentation Contracts and milestone-scoped app adapters +6. Semantic Audio Experience +7. Local Bond and concise Session Memory persistence +8. Privacy-filtered local field-test receipts ## Binding Invariants @@ -32,7 +32,9 @@ The current product is a solo-developer MVP vertical slice. Complexity belongs i - Pursuit is bounded pressure, not a generalized enemy framework. - Seeded behavior must remain reproducible. - `WaykinCore` must not gain **new** dependencies on ARKit, RealityKit, SwiftUI, MapKit, or audio filenames. Existing isolation baseline exceptions (today: SwiftData persistence + CoreLocation sample adapter seams checked by `scripts/check_core_framework_isolation.sh`) are grandfathered only; do not expand them without an explicit issue. -- Presentation adapters may realize semantic state but may not become alternate gameplay authorities. +- AR, audio, 2D, map, and HUD adapters may realize semantic state but may not become alternate gameplay authorities. +- AR is the primary designed session surface on capable devices; a walk must remain safe and completable when AR is denied, unavailable, or degraded. +- Semantic audio remains required supporting presentation for presence, pocket use, accessibility, and safety. - Physical-device behavior is not validated without direct device evidence. - Safety, pause, and stop behavior take precedence over dramatic pressure. diff --git a/docs/SOLO_MVP_SCOPE.md b/docs/SOLO_MVP_SCOPE.md index d4408f8..a307611 100644 --- a/docs/SOLO_MVP_SCOPE.md +++ b/docs/SOLO_MVP_SCOPE.md @@ -2,7 +2,7 @@ ## Product Promise -Waykin is an audio-first adaptive walking experience where the real world quietly appears to notice, remember, and respond through Lira, Bond, bounded phenomena, and concise session memories. +Waykin is an AR-designed adaptive walking experience where Lira meets the user in the world as they walk. Movement remains gameplay authority; AR is the primary designed session surface when capability allows, while audio, 2D presence, map, and HUD preserve continuity, accessibility, and safety. The first release should make a user finish a walk and want to go out again tomorrow to see what happens. @@ -12,7 +12,7 @@ The first release should make a user finish a walk and want to go out again tomo 2. World State 3. Event Generator 4. Companion Runtime -5. Audio Experience Layer +5. Multi-channel Presentation Layer (AR primary when capable; semantic audio required) Persistence may support these systems by storing Bond, companion identity, and concise memories. It must not become a generalized platform. @@ -26,7 +26,7 @@ Local field-test receipts may observe existing runtime signals for bounded engin - One coherent world interpretation: the world quietly responds to movement. - One persistent progression measure: Bond. - One deterministic event-generation mechanism. -- One audio-first semantic presentation path. +- One shared semantic presentation path across AR, audio, 2D presence, map, and HUD, with AR as the primary designed surface when capability allows. - One deterministic Demo Mode. - One physical-device walk path. - Minimal session, summary, and memory UI. @@ -59,7 +59,7 @@ Presentation quality must communicate current metrics and pressure through natur ## Expansion Gate -No major system may be added until repeated physical-device sessions demonstrate that the existing loop creates return intent and the current limitation cannot be solved through configuration, audio, tuning, or simplification. +No major system may be added until repeated physical-device sessions demonstrate that the existing loop creates return intent and the current limitation cannot be solved through configuration, presentation, tuning, or simplification. Legacy Orc Pursuit and Future Self compatibility models may be deleted only after no repository references remain outside their declarations, no persisted production data depends on their Codable representation, and migration or versioning behavior is explicitly tested. Until then, they remain inert compatibility state. diff --git a/docs/decisions/ADR-0003-local-first-swiftdata-persistence.md b/docs/decisions/ADR-0003-local-first-swiftdata-persistence.md index e98e992..1788b63 100644 --- a/docs/decisions/ADR-0003-local-first-swiftdata-persistence.md +++ b/docs/decisions/ADR-0003-local-first-swiftdata-persistence.md @@ -7,7 +7,7 @@ ## Context -Waykin is a solo-developer, audio-first adaptive movement application. Its MVP must complete walks without a network dependency and currently persists a small amount of durable state: Lira, Bond, and concise session memories. Preferences and field-test evidence already use separate storage mechanisms appropriate to their semantics. +At the time of this persistence decision, Waykin was described as a solo-developer, audio-first adaptive movement application. The current product identity is AR-designed; the local-first persistence decision is unchanged. Its MVP must complete walks without a network dependency and currently persists a small amount of durable state: Lira, Bond, and concise session memories. Preferences and field-test evidence already use separate storage mechanisms appropriate to their semantics. The current SwiftData implementation proves file-backed reopen behavior, but the persistent schema is not explicitly versioned, production initialization can fall back without adequately exposing degraded durability, companion retrieval is based on unspecified fetch order, and the one-memory-per-session invariant is enforced primarily in application code. diff --git a/docs/design/ART_DIRECTION_SIGN_OFF.md b/docs/design/ART_DIRECTION_SIGN_OFF.md index 7f02c7e..86abc7d 100644 --- a/docs/design/ART_DIRECTION_SIGN_OFF.md +++ b/docs/design/ART_DIRECTION_SIGN_OFF.md @@ -28,7 +28,7 @@ The **spectral Living Familiar** generated pack is accepted as the locked visual ## Locked constraints - Product name **Lira**; one companion; no marketplace multi-companion. -- Audio-first; stills support presence, not gameplay expansion. +- AR-designed; stills and audio support presence without gameplay expansion. - Night climate is indigo-earth Echo, not inverted day mist. - AR mid-LOD may remain procedural until sculpted USDZ lands; stills direction is binding for materials and silhouette. diff --git a/docs/design/AR_MVP_FREEZE.md b/docs/design/AR_MVP_FREEZE.md index 9cc9a0e..558efa1 100644 --- a/docs/design/AR_MVP_FREEZE.md +++ b/docs/design/AR_MVP_FREEZE.md @@ -84,7 +84,7 @@ When this freeze is accepted: ## Related - [CONTINUATION_PLAN.md](CONTINUATION_PLAN.md) v5.0 -- [AR_PRODUCT_REDESIGN_MAP.md](AR_PRODUCT_REDESIGN_MAP.md) β€” SUPPORTING redesign planning (does not lift freeze) +- [AR_PRODUCT_REDESIGN_MAP.md](AR_PRODUCT_REDESIGN_MAP.md) and [AR_APP_REDESIGN_PLAN.md](../plans/AR_APP_REDESIGN_PLAN.md) β€” Phase 0 promotes AR-designed identity without lifting frozen production paths - [LIRA_AR_PRODUCTION_RIG.md](LIRA_AR_PRODUCTION_RIG.md) - [AR_REPLAY_VALIDATION.md](../AR_REPLAY_VALIDATION.md) - [ACTIVE_WORK.md](../collaboration/ACTIVE_WORK.md) diff --git a/docs/design/AR_PRODUCT_REDESIGN_MAP.md b/docs/design/AR_PRODUCT_REDESIGN_MAP.md index f0f8326..2a1726c 100644 --- a/docs/design/AR_PRODUCT_REDESIGN_MAP.md +++ b/docs/design/AR_PRODUCT_REDESIGN_MAP.md @@ -76,7 +76,7 @@ Precedence (from `docs/governance/DOCUMENT_AUTHORITY.md`): 5. ADRs 6. … lower tiers … -This map and `docs/plans/AR_APP_REDESIGN_PLAN.md` are **SUPPORTING / NEAR_TERM**. They cannot silently override binding audio-first language until Phase 0 lands. +This map and `docs/plans/AR_APP_REDESIGN_PLAN.md` remain **SUPPORTING / NEAR_TERM**. Phase 0 product-law reconciliation is complete via issue #252; later UX and runtime phases still require their own evidence gates and scoped issues. ## 4. Whole-product map @@ -255,16 +255,16 @@ Session Summary β†’ Memory β†’ Home | Conflict | Severity | Resolution owner | | -------- | -------- | ---------------- | -| Binding **audio-first** vs AR design intent | High | Phase 0 binding docs | +| Prior binding audio-first identity vs AR design intent | **Resolved in Phase 0** | Issue #252 binding docs | | **AR MVP freeze** vs redesign work | High | Ring A vs issue-scoped Ring B | | UIUX β€œpresence OR AR not both animating” | Med | Keep; AR cover replaces active 2D animation | | Outdoor PARTIAL vs AR marketing | High | #41 before PASS claims | -| Skills `REPO_CONTEXT` audio-first | Med | Phase 0 agent pack | +| Prior skill-pack audio-first identity | **Resolved in Phase 0** | Issue #252 agent pack | | Continuous follow expectation vs world-plant | Med | Product education + optional later ADR | -## 11. Binding doc delta map (Phase 0) +## 11. Binding doc delta map (Phase 0 complete, issue #252) -| Document | Today | Target edit | +| Document | Prior state | Phase 0 result | | -------- | ----- | ----------- | | `docs/SOLO_MVP_SCOPE.md` | audio-first promise; audio-only presentation path | AR-designed promise; multi-channel presentation with AR primary design target | | `WAYKIN_SPEC.md` | audio-first contract; AR as #8 | AR-designed contract; AR presentation elevated; audio remains MVP system | @@ -324,8 +324,8 @@ Active Session today is **2D-rooted** with AR as optional cover. AR-designed pro | Label | Claim | | ----- | ----- | -| OBSERVED | AR command spine, freeze, optional fullScreenCover entry, audio-first binding language | -| INFERRED | Product feels multi-modal; audio-first under-describes ship | +| OBSERVED | AR command spine, freeze, optional fullScreenCover entry, and Phase 0 AR-designed binding language | +| INFERRED | AR-designed identity now describes the intended channel order; shipped session IA remains 2D-rooted pending later gated work | | NOT_COMPUTABLE | Whether session-default AR will increase return intent (needs outdoor/device product evidence; not inventable) | | NOT_COMPUTABLE | Outdoor AR quality PASS until #41 re-walk | diff --git a/docs/design/AR_SESSION_IA_CONFLICTS.md b/docs/design/AR_SESSION_IA_CONFLICTS.md index 29ffcad..f46d027 100644 --- a/docs/design/AR_SESSION_IA_CONFLICTS.md +++ b/docs/design/AR_SESSION_IA_CONFLICTS.md @@ -66,14 +66,14 @@ Session Summary | Source | Says | | ------ | ---- | -| Binding law (`SOLO_MVP_SCOPE`, `WAYKIN_SPEC`) | Audio-first product | +| Binding law (`SOLO_MVP_SCOPE`, `WAYKIN_SPEC`) | **AR-designed**; movement authority; AR primary when capable; audio supporting | | UIUX B1 | β€œAudio is the primary channel; the screen confirms” | | UIUX B2 + shipped | Screen-first session; AR optional | | Operator + redesign map | AR-designed; AR primary session surface | -**Conflict:** Three competing β€œprimaries” (audio / 2D screen / AR) without one ordered channel stack. +**Phase 0 status:** Binding law now defines the ordered channel stack. The remaining conflict is implementation/UIUX alignment: shipped 2D root and legacy UIUX wording have not yet been promoted to AR-default UX. -**Resolution direction:** Phase 0 law + UIUX B1 rewrite: AR primary **designed** surface when capable; audio required **support**; 2D fallback/HUD. +**Resolution direction:** Phase 0 law is complete via issue #252. Phase 2 must amend UIUX B1 and the session tree: AR primary **designed** surface when capable; audio required **support**; 2D fallback/HUD. --- @@ -266,18 +266,18 @@ Glance adapter publishes from `activePresencePresentation` when enabled, indepen | Doc class | Session stance | | ---------- | -------------- | -| BINDING scope/spec | Audio-first | +| BINDING scope/spec | **AR-designed**; Phase 0 complete | | DESIGN_REFERENCE UIUX | 2D root; AR cover; β€œdon’t redesign session” | | SUPPORTING redesign map + this file | AR root when capable | | AR MVP freeze | No silent `App/AR/**` feature expansion | -Agents and PRs will follow UIUX/binding until Phase 0 + UIUX B1–B4 amendment. +Agents and PRs now follow AR-designed binding law. Production UX remains frozen until Phase 1 evidence and a scoped Phase 2 issue authorize UIUX B1–B4 and session-shell changes. ## 4. Conflict graph ```text β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Product law β”‚ audio-first + β”‚ Product law β”‚ AR-designed β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ C1 β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” diff --git a/docs/design/CONTINUATION_PLAN.md b/docs/design/CONTINUATION_PLAN.md index 0ba30a2..a0a9021 100644 --- a/docs/design/CONTINUATION_PLAN.md +++ b/docs/design/CONTINUATION_PLAN.md @@ -76,7 +76,7 @@ DEVICE LANE (on frozen lineage only) BUILD-ON-TOP LANE (only after freeze + device honesty) 9. Recover PR #245 docs onto freeze tip (SUPPORTING; never merge stale branch) -10. Phase 0 binding product-law reconciliation +10. Phase 0 binding product-law reconciliation β€” issue #252 11. AR session shell in bounded PRs 12. State animations incrementally (preserve base mesh) ``` diff --git a/docs/design/LIRA_ANIMATION_PLAN.md b/docs/design/LIRA_ANIMATION_PLAN.md index 3c03f43..40a1d25 100644 --- a/docs/design/LIRA_ANIMATION_PLAN.md +++ b/docs/design/LIRA_ANIMATION_PLAN.md @@ -27,7 +27,7 @@ procedural_mesh_mid_lod: SHIPPED ## Purpose -Define how Lira **moves** across session UI and AR without expanding product scope (one companion, audio-first, no multiplayer/marketplace). +Define how Lira **moves** across session UI and AR without expanding product scope (one companion, AR-designed presentation, no multiplayer/marketplace). This plan binds animation to existing state machines: diff --git a/docs/design/LIRA_PRODUCTION_ART_PIPELINE.md b/docs/design/LIRA_PRODUCTION_ART_PIPELINE.md index d513306..d2f6cc1 100644 --- a/docs/design/LIRA_PRODUCTION_ART_PIPELINE.md +++ b/docs/design/LIRA_PRODUCTION_ART_PIPELINE.md @@ -16,7 +16,7 @@ direction_lock: Echo + Lira spectral Living Familiar (DIRECTION_ACCEPTED) Move Lira from **procedural Echo placeholder** (session silhouette + AR sphere-rig) to **production-quality art** without expanding product scope. -Authoritative product rules: one companion, audio-first, no multi-companion, no marketplace-driven skins, hunter without gore. +Authoritative product rules: one companion, AR-designed presentation, no multi-companion, no marketplace-driven skins, hunter without gore. ## Current state (OBSERVED in app) diff --git a/docs/design/README.md b/docs/design/README.md index c5d1e33..3188d0a 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -15,7 +15,7 @@ Visual system imports and production follow-ons for the app repository. **Authority:** these docs **do not** override binding product law or AR MVP freeze. Phase 0 binding edits are a separate PR. Implementation waits for freeze + device honesty (see CONTINUATION_PLAN). -**Operator direction (intent):** design for **AR** as primary session surface when capable; movement remains gameplay authority; audio is supporting/fallback. Binding docs may still say audio-first until Phase 0. +**Operator direction (intent):** design for **AR** as primary session surface when capable; movement remains gameplay authority; audio is supporting/fallback. Phase 0 promotes this identity into binding docs. ## UI product vs engineering practice diff --git a/docs/legal/TERMS.md b/docs/legal/TERMS.md index ece65dc..5e90640 100644 --- a/docs/legal/TERMS.md +++ b/docs/legal/TERMS.md @@ -18,7 +18,7 @@ That license governs **copyright in the software**, not your walking activity or ## 2. The experience -Waykin is an **audio-first adaptive walking experience** with a companion (Lira). It is entertainment / experiential software. +Waykin is an **AR-designed adaptive walking experience** with a companion (Lira). AR is a presentation surface, not navigation or safety authority, and the experience remains entertainment / experiential software. **Not medical advice.** Waykin is not a medical device, not a diagnostic tool, and not a substitute for professional advice. Do not rely on it for health, navigation safety, or emergency response. diff --git a/docs/plans/AR_APP_REDESIGN_PLAN.md b/docs/plans/AR_APP_REDESIGN_PLAN.md index 61cb1b7..62b6d8e 100644 --- a/docs/plans/AR_APP_REDESIGN_PLAN.md +++ b/docs/plans/AR_APP_REDESIGN_PLAN.md @@ -46,9 +46,9 @@ Redesign Waykin as an **AR-designed walking companion app** while **preserving** --- -## Phase 0 β€” Product law (docs / agents only) +## Phase 0 β€” Product law (docs / agents only) β€” COMPLETE via issue #252 -**Objective:** Make β€œAR-designed” the written product contract so humans and agents stop optimizing for audio-first identity. +**Objective:** Make β€œAR-designed” the written product contract so humans and agents stop optimizing for the prior audio-first identity. **Status:** complete via issue #252; no production paths were unfrozen. ### Work items diff --git a/project.yml b/project.yml index a2e86e7..746e03e 100644 --- a/project.yml +++ b/project.yml @@ -79,7 +79,7 @@ targets: UIColorName: LaunchBackground UIImageName: Lira_Glyph_Dawn UIImageRespectsSafeAreaInsets: true - # Audio-first: cues must survive screen lock / phone-in-pocket during a walk. + # Pocket-safe supporting audio: cues must survive screen lock / phone-in-pocket during a walk. UIBackgroundModes: [audio] dependencies: - package: Waykin diff --git a/skills/_shared/references/REPO_CONTEXT.md b/skills/_shared/references/REPO_CONTEXT.md index cd82f23..9d3cf1d 100644 --- a/skills/_shared/references/REPO_CONTEXT.md +++ b/skills/_shared/references/REPO_CONTEXT.md @@ -4,7 +4,7 @@ Read this once at skill start. Prefer absolute repo paths from `git rev-parse -- ## Product -- Audio-first **walking** companion app (Lira). Solo MVP. +- AR-designed **walking** companion app (Lira). Solo MVP. Movement is gameplay authority; AR is the primary designed session surface when capable; audio is a required supporting channel. - Binding scope: `docs/SOLO_MVP_SCOPE.md`, `WAYKIN_SPEC.md`, `ARCHITECTURE.md`, `AGENTS.md`, `docs/governance/DOCUMENT_AUTHORITY.md`. - One activity: walking. Not run/cycle expansion without scope promotion. diff --git a/skills/waykin-audio/SKILL.md b/skills/waykin-audio/SKILL.md index f8f59e6..8e6c1fe 100644 --- a/skills/waykin-audio/SKILL.md +++ b/skills/waykin-audio/SKILL.md @@ -12,7 +12,7 @@ metadata: # waykin-audio -Waykin is **audio-first**. Semantic cues are Core; filenames and AVAudioSession are App. +Waykin is **AR-designed**, with audio as a required supporting channel for presence, accessibility, safety, and pocket use. Semantic cues are Core; filenames and AVAudioSession are App. ## 0. Ownership From f79f713cad12229b0a140012cb3dab133df3e5f0 Mon Sep 17 00:00:00 2001 From: Daniel Date: Fri, 7 Aug 2026 11:25:35 -0700 Subject: [PATCH 2/2] docs: keep distinct presentation owners in solo MVP scope Address PR review: do not invent a Multi-channel Presentation Layer. Retain Audio Experience Layer and AR adapter as separate owners while keeping AR as the primary designed surface when capable. --- docs/SOLO_MVP_SCOPE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/SOLO_MVP_SCOPE.md b/docs/SOLO_MVP_SCOPE.md index a307611..d784d6c 100644 --- a/docs/SOLO_MVP_SCOPE.md +++ b/docs/SOLO_MVP_SCOPE.md @@ -12,7 +12,7 @@ The first release should make a user finish a walk and want to go out again tomo 2. World State 3. Event Generator 4. Companion Runtime -5. Multi-channel Presentation Layer (AR primary when capable; semantic audio required) +5. Audio Experience Layer (required) with AR presentation adapter as the primary designed session surface when capability allows; 2D presence, map, and HUD remain distinct supporting presentation owners β€” not a generalized multi-channel platform Persistence may support these systems by storing Bond, companion identity, and concise memories. It must not become a generalized platform. @@ -26,7 +26,7 @@ Local field-test receipts may observe existing runtime signals for bounded engin - One coherent world interpretation: the world quietly responds to movement. - One persistent progression measure: Bond. - One deterministic event-generation mechanism. -- One shared semantic presentation path across AR, audio, 2D presence, map, and HUD, with AR as the primary designed surface when capability allows. +- One semantic presentation path with AR as the primary designed surface when capability allows; Audio Experience Layer remains required; 2D presence, map, and HUD stay supporting channels under their existing owners. - One deterministic Demo Mode. - One physical-device walk path. - Minimal session, summary, and memory UI.