From ff0a6f01f354ac3fc40bbf38c03065eb6ef2c3ee Mon Sep 17 00:00:00 2001 From: Ladislas de Toldi Date: Tue, 3 Mar 2026 11:25:39 +0100 Subject: [PATCH 1/7] =?UTF-8?q?=F0=9F=93=9D=20(AGENTS.md,=20opencode):=20A?= =?UTF-8?q?dd=20content=20system=20knowledge=20base=20and=20update=20AI=20?= =?UTF-8?q?agent=20config?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive content system schema reference to Modules/ContentKit/Resources/Content/AGENTS.md covering all YAML schemas (activity v2, curriculum, story, curation), interface types, gameplay types, choice types, actions, and global definitions - Update root AGENTS.md to reference the new hierarchical content knowledge file - Update opencode.json instructions to auto-load Content/AGENTS.md for content-related work Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus --- AGENTS.md | 7 + .../ContentKit/Resources/Content/AGENTS.md | 492 ++++++++++++++++++ opencode.json | 3 + 3 files changed, 502 insertions(+) create mode 100644 Modules/ContentKit/Resources/Content/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index b07acab405..af54fd7717 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -154,3 +154,10 @@ bundle exec fastlane release target:LekaApp - Minimum iOS version is 17.4. - Destinations include iPad and Mac (Catalyst via iPad design). + +## Content System + +The educational content system is documented in detail in the hierarchical AGENTS.md file: +- `Modules/ContentKit/Resources/Content/AGENTS.md` - Full content schema reference (activities, curriculums, stories, curations, definitions) + +This file is auto-loaded by oh-my-opencode when working on content files. It is also referenced in `opencode.json` instructions for global access. diff --git a/Modules/ContentKit/Resources/Content/AGENTS.md b/Modules/ContentKit/Resources/Content/AGENTS.md new file mode 100644 index 0000000000..7f29a383ca --- /dev/null +++ b/Modules/ContentKit/Resources/Content/AGENTS.md @@ -0,0 +1,492 @@ +# ContentKit Content System + +This document describes the educational content system used by the Leka app. All content lives in `Modules/ContentKit/Resources/Content/` and is defined in YAML files. + +**Important:** Only the v2 activity format (`.new_activity.yml`, `version: 2.0.0`) is current. The old v1 format (`.activity.yml`, `version: 1.0.0`) is deprecated and will be removed. + +## Directory Structure + +``` +Content/ +├── definitions/ # Global taxonomies (skills, tags, authors, etc.) +│ ├── skills.yml # Hierarchical skill definitions +│ ├── tags.yml # Flat topic tags +│ ├── authors.yml # Content author profiles +│ ├── activity_types.yml # one_on_one, group +│ ├── hmi.yml # Interaction mediums +│ ├── robot_assets.yml # Magic card / robot screen asset hex IDs +│ ├── cardAssets/ # Card PNG images per locale (en/, fr/) +│ └── icons/ # Skill icon PNGs +│ +├── interaction/ # Icon PNGs for interaction classification +│ ├── attention/ # listen, look, mixed +│ ├── input/ # drag_and_drop, magic_card, touch_to_select, mixed +│ └── medium/ # robot, tablet, tablet_robot +│ +├── curations/ # UI layout/navigation files (.curation.yml) +│ ├── home-*.curation.yml +│ ├── explore-*.curation.yml +│ ├── curriculums-*.curation.yml +│ ├── educational_games-*.curation.yml +│ ├── stories-*.curation.yml +│ ├── gamepads-*.curation.yml +│ ├── sandbox-*.curation.yml +│ ├── learning_objectives-*.curation.yml +│ └── subcurations/ # ~30 themed subcurations (animals, emotions, colors, etc.) +│ +├── newActivities/ # Standalone/template v2 activities +│ ├── new_standalones/ # Standalone activities (dance_freeze, melody, etc.) +│ ├── new_templates/ # Template activities for reference +│ └── new_gamepads/ # Gamepad controller activities +│ +├── curriculums/ # ~70 curriculum directories +│ └── curriculum_-/ +│ ├── -.curriculum.yml +│ ├── new_activities/ # v2 activities belonging to this curriculum +│ │ ├── icons/ # Activity icon PNGs +│ │ └── assets/ # Activity asset PNGs +│ └── activities/ # DEPRECATED v1 activities (ignore) +│ +└── stories/ # Interactive story files (.story.yml) +``` + +## ID and Reference System + +Every content item has an ID in the format: `-<32_CHAR_HEX_UUID>` + +Examples: +- `curriculum_recognition_body_parts-80761A1D62BF4C6980BF20E7D9BE52B8` +- `recognition_body_parts_1-756B84801C32483FABEA6E5BC5DF7081` +- `dance_freeze-6E2F7D56726C419EA534C614F777D934` + +The UUID is a 32-character uppercase hex string (no hyphens). File names follow the same pattern: `-..yml`. + +### Reference Chain + +``` +Curation --[items.value]--> Curriculum | Activity | Curation (subcuration) +Curriculum --[activities]--> Activity (by name-UUID) +Story --[pages.items.action]--> Activity (inline) | Robot actions +Activity --[authors]--> authors.yml IDs +Activity --[skills]--> skills.yml IDs (slash-path like "sensory_integration/vision") +Activity --[tags]--> tags.yml IDs +Activity --[types]--> activity_types.yml IDs +Activity --[interaction.medium]--> hmi.yml IDs +``` + +## Localization (l10n) + +All content supports two locales: `fr_FR` and `en_US`. Localized data appears in `l10n` arrays: + +```yaml +l10n: + - locale: fr_FR + details: + title: Les parties du corps + subtitle: 1 image + ... + - locale: en_US + details: + title: Body Parts + subtitle: 1 image + ... +``` + +## YAML File Header + +All YAML files must start with: + +```yaml +# Leka - iOS Monorepo +# Copyright APF France handicap +# SPDX-License-Identifier: Apache-2.0 +``` + +--- + +## Activity Schema (v2 - `.new_activity.yml`) + +```yaml +version: 2.0.0 + +uuid: <32_CHAR_HEX_UUID> +name: + +created_at: "" +last_edited_at: "" +status: published # published | draft | template + +authors: + - leka # References authors.yml + +skills: # References skills.yml (slash-path for subskills) + - recognition + - sensory_integration/vision + +tags: # References tags.yml + - body_parts + +interaction: + medium: tablet # tablet | robot | tablet_robot + input: touch_to_select # touch_to_select | drag_and_drop | magic_card | mixed + attention: listen # listen | look | mixed (optional) + +types: + - one_on_one # one_on_one | group + +locales: + - en_US + - fr_FR + +l10n: + - locale: fr_FR + details: + icon: # PNG filename (no extension) in icons/ + title: + subtitle: + short_description: | + + description: | + + instructions: | + + - locale: en_US + details: ... + +payload: + options: + shuffle_exercises: true # Shuffle order of exercises + shuffle_groups: false # Shuffle order of exercise groups + + exercise_groups: + - group: + - # See Exercise Schema below + - + - group: + - +``` + +### Exercise Schema + +Each exercise within a group has this structure: + +```yaml +instructions: # Optional, per-locale instructions for this exercise + - locale: fr_FR + value: + - locale: en_US + value: + +interface: # See Interface Types below +gameplay: # See Gameplay Types below + +action: # Optional, triggered action + type: ipad | robot + value: + type: speech | color | motion | random | activity + value: # Speech: l10n utterances, Color: color name, etc. + +options: # Optional + shuffle_choices: true + +payload: + choices: # For general interfaces + - value: # Image name, emoji, SF Symbol, or color name + type: image | emoji | sfsymbol | color + is_right_answer: true # Optional, marks correct answer + is_dropzone: true # Optional, for drag-and-drop zones + category: catA # Optional, for association/memory (catA, catB, catC...) + dropZone: zoneA # Optional, target zone for drag-and-drop + songs: # For danceFreeze interface + - audio: + labels: + - locale: fr_FR + value: + name: + icon: +``` + +### Interface Types + +**General (tablet-based):** +- `touchToSelect` - Tap the correct choice from options +- `dragAndDropIntoZones` - Drag items into labeled drop zones +- `dragAndDropGrid` - Drag items into a grid layout +- `dragAndDropOneToOne` - Drag items to order them sequentially +- `dragAndDropGridWithZones` - Grid-based drag with category zones +- `memory` - Flip cards to find matching pairs +- `magicCards` - Use physical NFC magic cards scanned by robot + +**Specialized (robot-integrated):** +- `danceFreeze` - Robot dances to music, freezes randomly +- `superSimon` - Simon Says color memory game with robot LEDs +- `hideAndSeek` - Robot plays hide and seek with sound/light +- `melody` - Music creation/playback +- `musicalInstruments` - Xylophone (pentatonic/heptatonic) +- `colorMusicPad` - Color-sound association pad +- `colorMediator` - Robot lights up colors for group games +- `gamepadArrowPad` - Directional control of robot movement +- `gamepadColorPad` - Color-button control of robot +- `gamepadJoyStickColorPad` - Joystick + color control +- `gamepadArrowPadColorPad` - Arrow + color pad combined +- `pairing` - Pairing interaction +- `discoverLeka` - Introduction to the robot + +### Gameplay Types + +- `findTheRightAnswers` - Select correct answers from choices +- `findTheRightOrder` - Arrange items in correct sequence +- `associateCategories` - Match items by category (used with memory, drag-and-drop zones) +- `openPlay` - Free play without scoring + +### Choice Types + +- `image` - PNG asset reference (filename without extension, located in curriculum's assets/) +- `emoji` - Unicode emoji character (e.g., `🍌`) +- `sfsymbol` - SF Symbols name (e.g., `circle`, `square`) +- `color` - Color name (e.g., `red`, `yellow`, `blue`, `green`, `pink`) + +### Action Types + +**iPad actions:** +```yaml +action: + type: ipad + value: + type: speech + value: + - locale: fr_FR + utterance: "le bras" + - locale: en_US + utterance: "the arm" +``` + +**Robot actions:** +```yaml +action: + type: robot + value: + type: color # color | motion | random + value: blue # color name, motion name, or "color" +``` + +--- + +## Curriculum Schema (`.curriculum.yml`) + +```yaml +uuid: <32_CHAR_HEX_UUID> +name: curriculum_ +status: published # published | draft | template + +created_at: "" +last_edited_at: "" + +authors: + - leka + +skills: + - recognition + +tags: + - body_parts + +locales: + - en_US + - fr_FR + +l10n: + - locale: fr_FR + details: + icon: + title: + subtitle: + abstract: | + + description: | + + - locale: en_US + details: ... + +activities: # Ordered list of activity name-UUID references + - - + - - +``` + +Curriculums live in `curriculums/curriculum_-/` directories. Their activities live in the `new_activities/` subdirectory within. + +--- + +## Story Schema (`.story.yml`) + +```yaml +version: 1.0.0 + +uuid: <32_CHAR_HEX_UUID> +name: + +created_at: "" +last_edited_at: "" +status: published + +authors: + - hanna_and_nagib + - leka + +skills: + - familiarization_with_leka + +interaction: + medium: tablet_robot + input: touch_to_select + +types: + - one_on_one + +tags: + - hanna + - story + +locales: + - en_US + - fr_FR + +l10n: + - locale: fr_FR + details: + icon: + title: + subtitle: + short_description: | + + description: | + + instructions: | + + - locale: en_US + details: ... + +pages: + - background: + l10n: + - locale: fr_FR + items: + - type: text # text | image | button_image + payload: + text: "Some text" + - type: button_image + payload: + idle: # Image when not pressed + pressed: # Image when pressed + text: