@studiolxd/lxd-cli 0.1.0-next.0

package/dist/core/schema/design-direction.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/design-direction.schema.json",
+  "title": "DesignDirection",
+  "description": "First-class, multi-level design model (FR-011/012/013). Package-level, shared by experiences. 'level' gates which inputs are expected.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["level"],
+  "properties": {
+    "level": { "enum": ["brief", "tokens", "patterns", "design-system", "full-constraints"] },
+    "brief": { "type": "string" },
+    "tone": { "type": "string" },
+    "tokens": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "colors": { "type": "object", "additionalProperties": { "type": "string" } },
+        "typography": { "type": "object" },
+        "spacing": { "type": "object" },
+        "density": { "enum": ["compact", "comfortable", "spacious"] }
+      }
+    },
+    "patterns": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ui": { "type": "array", "items": { "type": "string" } },
+        "interaction": { "type": "array", "items": { "type": "string" } },
+        "componentUsage": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "accessibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "considered": { "type": "boolean" },
+        "targets": { "type": "array", "items": { "type": "string" }, "description": "e.g., WCAG level chosen per project" },
+        "notes": { "type": "string" }
+      }
+    },
+    "responsive": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "approach": { "enum": ["mobile-first", "desktop-first", "fluid"] },
+        "breakpoints": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "animation": { "type": "string" },
+    "designSystemRefs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "ref"],
+        "properties": {
+          "kind": { "enum": ["url", "file"] },
+          "ref": { "type": "string" }
+        }
+      }
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "do": { "type": "array", "items": { "type": "string" } },
+        "dont": { "type": "array", "items": { "type": "string" } },
+        "implementation": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "output": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "e.g., light-mode, dark-mode, mobile-first, corporate, playful, minimal"
+    }
+  },
+  "allOf": [
+    { "if": { "properties": { "level": { "const": "brief" } }, "required": ["level"] }, "then": { "required": ["brief"] } },
+    { "if": { "properties": { "level": { "const": "tokens" } }, "required": ["level"] }, "then": { "required": ["tokens"] } },
+    { "if": { "properties": { "level": { "const": "patterns" } }, "required": ["level"] }, "then": { "required": ["patterns"] } },
+    { "if": { "properties": { "level": { "const": "design-system" } }, "required": ["level"] }, "then": { "required": ["designSystemRefs"] } },
+    { "if": { "properties": { "level": { "const": "full-constraints" } }, "required": ["level"] }, "then": { "required": ["constraints"] } }
+  ]
+}

package/dist/core/schema/experience.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/experience.schema.json",
+  "title": "Experience",
+  "description": "An interactive learning experience inside a package (FR-007). Exactly one mechanic (FR-010).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "title", "learningPurpose", "scenario", "mechanicRef", "feedback"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "learningPurpose": { "type": "string", "minLength": 1 },
+    "scenario": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary"],
+      "properties": {
+        "summary": { "type": "string", "minLength": 1 },
+        "context": { "type": "string" },
+        "roles": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "mechanicRef": { "type": "string", "description": "MechanicManifest.id; MUST resolve in the mechanic registry" },
+    "mechanicInputs": { "type": "object", "description": "MUST satisfy the mechanic manifest's requiredInputs" },
+    "interfaceIntent": { "type": "string" },
+    "evaluation": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "assessed": { "type": "boolean" },
+        "scoreRules": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["method"],
+          "properties": {
+            "method": { "enum": ["percentage", "points", "scaled"] },
+            "passThreshold": { "type": "number" },
+            "max": { "type": "number" }
+          }
+        },
+        "criteria": { "type": "array", "items": { "type": "string" } }
+      },
+      "if": { "properties": { "assessed": { "const": true } }, "required": ["assessed"] },
+      "then": { "required": ["scoreRules"] }
+    },
+    "feedback": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["model"],
+      "properties": {
+        "model": { "enum": ["immediate", "delayed", "summary", "adaptive"] },
+        "messages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["on", "message"],
+            "properties": {
+              "on": { "type": "string", "description": "meaningful learner action" },
+              "message": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "required": { "type": "boolean", "default": true, "description": "counts toward package completion roll-up" },
+    "weight": { "type": "number", "exclusiveMinimum": 0, "default": 1 },
+    "signals": {
+      "type": "array",
+      "description": "signals this experience emits (subset of the canonical signal set)",
+      "items": { "enum": ["progress", "score", "completion", "interaction", "feedback", "suspend"] },
+      "uniqueItems": true
+    }
+  }
+}

package/dist/core/schema/export-config.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/export-config.schema.json",
+  "title": "ExportConfig",
+  "description": "Adapter-driven export configuration (FR-022/024). adapterId is an open enum; unknown ids without an adapter must be reported clearly (FR-025).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["targets"],
+  "properties": {
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["adapterId"],
+        "properties": {
+          "adapterId": {
+            "type": "string",
+            "description": "v1 in-tree adapters: web | scorm-1.2 | scorm-2004. Open to future adapters (xapi, cmi5, ...).",
+            "examples": ["web", "scorm-1.2", "scorm-2004"]
+          },
+          "options": {
+            "type": "object",
+            "description": "Adapter-specific options, validated against the adapter's own option schema",
+            "properties": {
+              "identifier": { "type": "string", "description": "SCORM manifest identifier" },
+              "masteryScore": { "type": "number", "description": "SCORM 1.2 mastery score / 2004 scaled passing score" },
+              "title": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "framework": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "adapterId": { "type": "string", "examples": ["webcomponents"] },
+        "options": { "type": "object" }
+      }
+    }
+  }
+}

package/dist/core/schema/mechanic-manifest.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/mechanic-manifest.schema.json",
+  "title": "MechanicManifest",
+  "description": "Declarative, REQUIRED contract for an experience mechanic (FR-008a). Official assets authored by Studio LXD in v1. An optional code plugin (FR-008b) may supplement but never replaces this manifest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "version", "description", "requiredInputs", "trackingContract"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "category": { "type": "string" },
+    "description": { "type": "string", "minLength": 1 },
+    "requiredInputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["key", "type"],
+        "properties": {
+          "key": { "type": "string" },
+          "type": { "enum": ["string", "number", "boolean", "array", "object"] },
+          "description": { "type": "string" },
+          "required": { "type": "boolean", "default": true }
+        }
+      }
+    },
+    "evaluationContract": {
+      "type": "object",
+      "description": "shape the experience's evaluation must satisfy when this mechanic is assessable",
+      "properties": { "assessable": { "type": "boolean" } }
+    },
+    "feedbackContract": {
+      "type": "object",
+      "description": "shape of feedback this mechanic expects"
+    },
+    "trackingContract": {
+      "type": "array",
+      "description": "signals the mechanic is expected to emit",
+      "items": { "enum": ["progress", "score", "completion", "interaction", "feedback", "suspend"] },
+      "uniqueItems": true
+    },
+    "agentGuidance": {
+      "type": "string",
+      "description": "instructions injected into agent handoff materials for this mechanic"
+    },
+    "pluginRef": {
+      "type": "string",
+      "description": "OPTIONAL reference to a code plugin implementing mechanic-plugin.contract.md (FR-008b)"
+    }
+  }
+}

package/dist/core/schema/package-spec.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/package-spec.schema.json",
+  "title": "PackageSpec",
+  "description": "Top-level elearning package. The package is the unit of delivery (FR-002); a single experience is never top-level.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "schemaVersion",
+    "learningGoal",
+    "audience",
+    "duration",
+    "structure",
+    "experienceRefs",
+    "designRef",
+    "completionRules",
+    "trackingRef",
+    "exportRef"
+  ],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "schemaVersion": { "type": "string" },
+    "learningGoal": { "type": "string", "minLength": 1 },
+    "title": { "type": "string" },
+    "audience": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["description"],
+      "properties": {
+        "description": { "type": "string", "minLength": 1 },
+        "priorKnowledge": { "type": "string" },
+        "roles": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "duration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["expectedMinutes"],
+      "properties": {
+        "expectedMinutes": { "type": "number", "exclusiveMinimum": 0 },
+        "note": { "type": "string" }
+      }
+    },
+    "context": { "type": "string" },
+    "constraints": { "type": "array", "items": { "type": "string" } },
+    "tone": { "type": "string" },
+    "structure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["navigation", "order"],
+      "properties": {
+        "navigation": { "enum": ["linear", "free", "guided"] },
+        "order": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "experienceIds"],
+            "properties": {
+              "id": { "type": "string" },
+              "title": { "type": "string" },
+              "experienceIds": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "experienceRefs": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "description": "experience id (file in experiences/)" }
+    },
+    "designRef": { "type": "string" },
+    "evaluationRules": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "assessed": { "type": "boolean" },
+        "scoreRules": { "$ref": "#/$defs/scoreRules" },
+        "criteria": { "type": "array", "items": { "type": "string" } }
+      },
+      "if": { "properties": { "assessed": { "const": true } }, "required": ["assessed"] },
+      "then": { "required": ["scoreRules"] }
+    },
+    "completionRules": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rule"],
+      "properties": {
+        "rule": { "enum": ["all-required", "selected-required"] },
+        "requiredExperienceIds": { "type": "array", "items": { "type": "string" } }
+      },
+      "if": { "properties": { "rule": { "const": "selected-required" } } },
+      "then": { "required": ["requiredExperienceIds"] }
+    },
+    "trackingRef": { "type": "string" },
+    "exportRef": { "type": "string" },
+    "assetRefs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "scormLibraryVersion": { "type": "string" },
+        "scormSkillsSnapshot": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "version": { "type": "string" }, "ref": { "type": "string" } }
+        },
+        "cliVersion": { "type": "string" }
+      }
+    }
+  },
+  "$defs": {
+    "scoreRules": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["method"],
+      "properties": {
+        "method": { "enum": ["percentage", "points", "scaled"] },
+        "passThreshold": { "type": "number" },
+        "max": { "type": "number" }
+      }
+    }
+  }
+}

package/dist/core/schema/tracking-config.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/tracking-config.schema.json",
+  "title": "TrackingConfig",
+  "description": "Two-level tracking (FR-027): per-experience signals + explicit package roll-up rules (FR-027a). The roll-up produces the single LMS-reported state (FR-027b).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["experienceSignals", "rollUp"],
+  "properties": {
+    "experienceSignals": {
+      "type": "object",
+      "description": "map of experienceId -> declared signals",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "enum": ["progress", "score", "completion", "interaction", "feedback", "suspend"] },
+        "uniqueItems": true
+      }
+    },
+    "rollUp": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["completion", "score", "reportedFields"],
+      "properties": {
+        "completion": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["rule"],
+          "properties": {
+            "rule": { "enum": ["all-required-complete", "selected-required-complete"] },
+            "requiredExperienceIds": { "type": "array", "items": { "type": "string" } }
+          },
+          "if": { "properties": { "rule": { "const": "selected-required-complete" } } },
+          "then": { "required": ["requiredExperienceIds"] }
+        },
+        "score": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["rule"],
+          "properties": {
+            "rule": { "enum": ["weighted-average", "final-assessment-only"] },
+            "finalAssessmentExperienceId": { "type": "string" }
+          },
+          "if": { "properties": { "rule": { "const": "final-assessment-only" } } },
+          "then": { "required": ["finalAssessmentExperienceId"] }
+        },
+        "success": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "scoreThreshold": { "type": "number" },
+            "requireRequiredExperiencesComplete": { "type": "boolean", "default": true }
+          }
+        },
+        "reportedFields": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "enum": ["completion", "success", "score", "suspend_data", "lesson_location"] },
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/dist/core/schema/validation-report.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://studiolxd.dev/lxd-cli/validation-report.schema.json",
+  "title": "ValidationReport",
+  "description": "Output of the validation subsystem (FR-032/033). Every check is actionable: it identifies what failed and where.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["checks", "summary"],
+  "properties": {
+    "checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "category", "status", "message"],
+        "properties": {
+          "id": { "type": "string", "description": "stable check id, e.g., 'learning-goal-present'" },
+          "category": {
+            "enum": ["instructional", "design", "accessibility", "technical", "tracking", "export", "maintainability", "portability"]
+          },
+          "status": { "enum": ["pass", "fail", "warn", "skip"] },
+          "message": { "type": "string" },
+          "location": { "type": "string", "description": "artifact path / field pointer the result refers to" },
+          "fix": { "type": "string", "description": "suggested remediation" }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pass", "fail", "warn", "skip", "overall"],
+      "properties": {
+        "pass": { "type": "integer", "minimum": 0 },
+        "fail": { "type": "integer", "minimum": 0 },
+        "warn": { "type": "integer", "minimum": 0 },
+        "skip": { "type": "integer", "minimum": 0 },
+        "overall": { "enum": ["pass", "fail"] }
+      }
+    },
+    "generatedAt": { "type": "string", "format": "date-time" }
+  }
+}

package/dist/mechanics/manifests/branching-narrative.yml

@@ -0,0 +1,25 @@
+id: branching-narrative
+name: Branching Narrative
+version: 0.1.0
+category: scenario
+description: >-
+  Learner moves through a branching story, making choices that lead to different
+  nodes and outcomes. Good for judgement, ethics, and consequence-based learning.
+requiredInputs:
+  - key: nodes
+    type: array
+    description: Story nodes with choices and the node each choice leads to.
+    required: true
+  - key: start
+    type: string
+    description: The id of the starting node.
+    required: true
+trackingContract:
+  - progress
+  - completion
+  - interaction
+  - suspend
+agentGuidance: >-
+  Render the narrative as a Web Component; persist the visited path in suspend
+  data so the learner can resume; emit completion when a terminal node is reached.
+pluginRef: branching-narrative

package/dist/mechanics/manifests/decision-simulation.yml

@@ -0,0 +1,25 @@
+id: decision-simulation
+name: Decision Simulation
+version: 0.1.0
+category: simulation
+description: >-
+  Learner makes a sequence of decisions in a scenario and sees consequences,
+  building judgement under realistic constraints.
+requiredInputs:
+  - key: scenario
+    type: string
+    description: The situation the learner is placed in.
+    required: true
+  - key: decisions
+    type: array
+    description: Decision points with options and consequences.
+    required: true
+trackingContract:
+  - progress
+  - score
+  - completion
+  - interaction
+  - suspend
+agentGuidance: >-
+  Render branching decision points as a Web Component; track the chosen path in
+  suspend data; score against the defined consequences.

package/dist/mechanics/manifests/diagnostic-challenge.yml

@@ -0,0 +1,24 @@
+id: diagnostic-challenge
+name: Diagnostic Challenge
+version: 0.1.0
+category: assessment
+description: >-
+  Learner diagnoses a problem from evidence, selecting causes or next actions.
+  Good for troubleshooting and clinical-style reasoning.
+requiredInputs:
+  - key: case
+    type: object
+    description: The presenting evidence/symptoms.
+    required: true
+  - key: answerKey
+    type: object
+    description: Correct diagnosis/actions and acceptable alternatives.
+    required: true
+trackingContract:
+  - progress
+  - score
+  - completion
+  - interaction
+agentGuidance: >-
+  Present evidence and a structured response as a Web Component; evaluate the
+  learner's diagnosis against the answer key; emit score and completion.

package/dist/mechanics/manifests/risk-detection.yml

@@ -0,0 +1,24 @@
+id: risk-detection
+name: Risk / Error Detection
+version: 0.1.0
+category: assessment
+description: >-
+  Learner inspects a scene, interface, or document and identifies hazards,
+  errors, or risks. Good for safety, compliance, and review skills.
+requiredInputs:
+  - key: items
+    type: array
+    description: The inspectable items and which are hazards/errors.
+    required: true
+  - key: prompt
+    type: string
+    description: What the learner is asked to find.
+    required: true
+trackingContract:
+  - progress
+  - score
+  - completion
+  - interaction
+agentGuidance: >-
+  Render an inspectable scene as a Web Component. Let the learner mark items;
+  evaluate against the hazard set; emit score and completion signals.

package/docs/agent-agnostic-verification.md

@@ -0,0 +1,52 @@
+# Agent-agnosticism verification (manual)
+
+The product must work with **any** external AI coding agent (FR-017, SC-010). Two layers verify
+this:
+
+1. **Automated (CI):** the `checkHandoffAgnostic` check (`src/core/validation/handoff-agnostic.ts`)
+   asserts generated handoff materials contain no provider-specific assumptions or credentials. It
+   runs in the `handoff` command (warns) and in `tests/contract/handoff-agnostic.test.ts`.
+2. **Manual (this procedure):** confirm the *same* handoff materials can be implemented by **two
+   different agents** to a passing package. This is inherently manual (real agents, human judgement)
+   and is **not** a CI gate.
+
+## Procedure
+
+1. **Author one package once.**
+   ```bash
+   lxd init course-x && cd course-x
+   # ... goal / audience / structure / experience / design / evaluation / tracking ...
+   lxd validate          # expect overall: pass
+   lxd handoff           # produces .agent/** (the shared materials)
+   ```
+   Snapshot `.agent/` (e.g., copy it aside) so both agents get identical inputs.
+
+2. **Agent A.** In a clean checkout of the project (same `.agent/`, empty `generated/`), run your
+   first agent (e.g., Claude Code) against `.agent/**`. Then:
+   ```bash
+   lxd preview            # interactive?  ✅/❌
+   lxd validate           # overall: pass?  ✅/❌
+   lxd export --target web --target scorm-1.2
+   ```
+
+3. **Agent B.** Repeat step 2 in a *fresh* clean checkout with the **same** `.agent/`, using a
+   different agent (e.g., Cursor or Codex).
+
+4. **Record results** in the table below. The criterion (SC-010): both agents reach a previewable,
+   validated package and conformant exports from the same handoff materials.
+
+## Results log
+
+| Date | Agent | Preview OK | Validate pass | Export web | Export SCORM | Notes |
+|------|-------|-----------|---------------|------------|--------------|-------|
+|      | A: …  |           |               |            |              |       |
+|      | B: …  |           |               |            |              |       |
+
+## What counts as a failure
+
+- Handoff materials assume a specific provider/model, or contain credentials (caught automatically).
+- One agent succeeds and another cannot, due to provider-specific phrasing in the materials.
+- The materials require tools only one agent has.
+
+If any occur, generalize the affected prompt/instruction templates in
+`src/agent/handoff/producer.ts` and re-verify.