OER Schema Integration Finder (Read-Only Diagnostic)

Scan HAX ecosystem code — webcomponents, themes, CMS backends, the VitePress plugin, and the Google Apps Script add-on — for surfaces that render or consume pedagogical content but do not emit or consume OER Schema metadata, and emit a per-file hit-list of integration opportunities. This skill diagnoses and recommends only — it does not edit source. It mirrors the oerschema-audit pattern but operates on code, not authored content: where oerschema-audit asks "does this page have the right microdata?", this skill asks "does this element emit the right microdata?"

The worldview in one paragraph

OER Schema only lands in authored content if the rendering elements emit it. A HAX quiz element that renders questions but no itemscope itemtype="http://oerschema.org/Quiz" means every page using that element is silently uncovered — a code gap, not a content gap. The HAX ecosystem has many elements that render pedagogical structures (quizzes, outlines, objectives, rubrics, media playlists, syllabi) and several surfaces that transform content (the VitePress plugin, the Apps Script add-on, the CMS backends). This skill scans those code surfaces for missing schema emission or consumption and produces a hit-list that hax-webcomponent-dev can act on. It is distinct from oerschema-audit (authored content), from hax-a11y-audit (accessibility), and from hax-webcomponent-dev (which implements the fixes this skill identifies). It does not invent classes/properties — every recommendation cites a real OER Schema class from the v1.2.0 vocabulary.

When to Use

Trigger conditions:

• "Which of my webcomponents should emit OER schema" / "find assessment code without schema support"
• "Where in my codebase should oerschema be wired in" / "does the quiz element emit microdata"
• "Audit my components for OER schema integration opportunities"
• "What elements in HAX could expose OER schema but don't"
• "Does the VitePress plugin cover all the OER classes" / "does the Google Docs add-on emit rubrics"
• even when the user does not say "finder" or "OER schema" — if they ask which code surfaces should carry educational schema metadata, this is the skill

When NOT to use (with redirect):

• A specific page is missing schema (the gap is in authored content, not the rendering element) → oerschema-audit
• Implementing the schema emission in a component (writing the LitElement template / haxProperties) → hax-webcomponent-dev
• The OER Schema vocabulary itself needs new classes/properties → oerschema-schema-author
• schema.ts internal consistency → oerschema-validation
• Accessibility of a component → hax-a11y-audit / hax-webcomponent-dev

Scope: this skill is READ-ONLY

This skill diagnoses and recommends only. It produces a hit-list. To implement, hand off to hax-webcomponent-dev (for webcomponents), hax-site-building (for themes), or the relevant backend/plugin maintainer. Never edit source files from within this skill.

Inputs

• A codebase path to scan. Typical targets:
  • the webcomponents monorepo (e.g. ~/Documents/git/haxtheweb/webcomponents)
  • a single element directory (e.g. elements/<tag-name>)
  • a HAXcms theme directory
  • a CMS backend (PHP: haxcms-php; NodeJS: haxcms-nodejs)
  • the VitePress plugin (oerschema/vitepress-plugin/)
  • the Google Apps Script add-on (oerschema/google-apps-script/)
• optional scope flag: --surface=webcomponents|theme|backend|plugin|appsscript to limit the scan

Methodology

1. Identify the scan target and surface. Determine whether the path is a webcomponent, a theme, a backend, the VitePress plugin, or the Apps Script add-on — each has a different schema-emission mechanism (see references/component-patterns.md).
2. Load the vocabulary. Consult oerschema-audit's references/vocabulary.md (the v1.2.0 class
   • property tables) as the source of truth for what classes/properties exist. This skill does not duplicate that file; it references it.
3. For webcomponents, for each element:
   • Read the element's src/<tag>.js (LitElement class) and its render() / template. Look for itemscope, itemtype, itemprop in the template — the microdata emission surface.
   • Read its haxProperties / haxProperties.json / HAXSchema — the HAX editor integration surface. Does it expose a schema-relevant gizmo type or properties that map to OER classes?
   • Classify the element by what it renders (see references/component-patterns.md candidate list): assessment/quiz, outline/navigation, objective, rubric, syllabus, media, reading, activity. If it renders a pedagogical structure and emits no microdata, it is a hit.
   • If it emits microdata with a wrong/invalid itemtype or a property outside its domain, it is a mis-classification hit (use the vocabulary + inheritance rule to verify).
4. For themes, check whether the theme wraps page content in an OER class wrapper (e.g. a Course/Unit wrapper around the rendered page) or emits a site-level JSON-LD block. A theme that renders pages/*.html content with no surrounding OER class is a structural hit.
5. For CMS backends (PHP/NodeJS HAXcms), check whether the backend exposes OER Schema in its data model / API responses (site.json, page JSON, outline endpoints). A backend that serves outline data with no OER class mapping is a hit. Per PRAW rules, only the siteRoutes api/v1 system is in scope for NodeJS — do not flag the legacy src/routes/* (v0) endpoints.
6. For the VitePress plugin, compare the directives it implements against the OER class vocabulary. The plugin currently implements learning-objective, assessment, practice, rubric, rubric-criterion, rubric-scale, rubric-level, learning-component, instructional-pattern. Missing directives: no dedicated course, unit, module, lesson, quiz, submission, task, activity, project, learning-objective (present), syllabus, topic. Each missing directive for a class that authors would reasonably use is a plugin hit.
7. For the Apps Script add-on, compare the components it can insert (LearningObjective, Assessment, Practice) against the vocabulary. Missing: Quiz, Rubric family, Lesson wrapper, Task/Activity. Each missing component is an add-on hit.
8. For each hit, record: file path, the element/surface, what it renders, the recommended OER class + properties it should emit, and the implementation handoff (hax-webcomponent-dev for components, hax-site-building for themes, the relevant maintainer for backends/plugins).
9. Apply the overlap / defer rules:
   • If the gap is actually in authored content (the element emits microdata but the page didn't use it), defer to oerschema-audit.
   • If the element needs new vocabulary to emit the right class, defer to oerschema-schema-author.
   • If the gap is a component-internal accessibility issue, defer to hax-a11y-audit / hax-webcomponent-dev.
10. Determine the overall rating:
    • Wired: the scanned surface emits/consumes schema for all pedagogical structures it renders.
    • Partial: some pedagogical structures emit schema, others don't; or some emit mis-classified schema.
    • Unwired: the surface renders pedagogical content but emits zero OER Schema metadata.
11. Emit the hit-list (format below), then an "Implementation handoff" block.

Expected Output Format

### 📊 OER Schema Integration Diagnostics
* **Integration Rating:** [Wired / Partial / Unwired]
* **Primary Gap:** [the worst offender — one sentence, e.g. "The quiz element renders assessments but emits no Assessment microdata, so every page using it is uncovered."]

### 🔍 Hit-list & integration recommendations

* **{file path} — {surface}**
  * **Renders:** [what pedagogical structure, e.g. "quiz questions with a points value"]
  * **Schema emitted:** [none / what it currently emits, e.g. "no itemscope/itemtype"]
  * **Recommended:** [exact class + properties to emit, e.g. "itemscope itemtype='http://oerschema.org/Quiz' on the wrapper; itemprop='gradingFormat' (range GradeFormat|Text) for points; itemprop='assessing' (range Activity) if linked to an activity."]
  * **Handoff:** [hax-webcomponent-dev / hax-site-building / plugin maintainer / add-on maintainer]

* **{file path} — {surface}**
  * ...

### 🛠 Implementation handoff
* [one-line action per hit → skill/maintainer, e.g. "Add Assessment microdata to the quiz element's render template (hax-webcomponent-dev)."]

Worked example

Input — scan the webcomponents monorepo, focusing on a quiz element at elements/quiz-element/src/quiz-element.js whose render() returns questions and a points display but contains no itemscope/itemtype/itemprop.

Output:

### 📊 OER Schema Integration Diagnostics
* **Integration Rating:** Unwired
* **Primary Gap:** quiz-element renders assessments (questions + points) but emits no OER Schema
  microdata, so every HAX page using <quiz-element> is silently uncovered.

### 🔍 Hit-list & integration recommendations

* **elements/quiz-element/src/quiz-element.js — webcomponent**
  * **Renders:** quiz questions with a `points` property and an optional `assessing` link.
  * **Schema emitted:** none — render() has no itemscope/itemtype/itemprop.
  * **Recommended:** wrap the quiz in `<div itemscope itemtype="http://oerschema.org/Quiz">`;
    emit `<meta itemprop="gradingFormat" content="${this.points} points">` for points;
    emit `<link itemprop="assessing" href="${this.assessingRef}">` when an activity is linked.
    `Quiz` subClassOf `Assessment` (domain of `assessing`/`gradingFormat`), so both properties are
    valid on it. Expose the class choice in `haxProperties` so authors can pick Quiz vs Assessment.
  * **Handoff:** hax-webcomponent-dev

### 🛠 Implementation handoff
* Add Quiz microdata to quiz-element's render template and surface a schema toggle in its
  haxProperties (hax-webcomponent-dev).
* After implementation, re-audit pages using <quiz-element> via oerschema-audit to confirm coverage.

Implementing the Recommendations

This finder is the diagnosis step. Implement with:

• hax-webcomponent-dev — add microdata emission to a component's render() template and surface schema-relevant options in its haxProperties / HAXSchema. This is the primary handoff.
• hax-site-building — for theme-level schema wrappers (Course/Unit wrappers, site JSON-LD).
• Plugin maintainer — for new VitePress directives (::: quiz, ::: lesson, etc.) in oerschema/vitepress-plugin/index.js.
• Add-on maintainer — for new Google Apps Script components in oerschema/google-apps-script/Code.js.
• oerschema-schema-author — if a needed class/property doesn't exist yet in the vocabulary.
• oerschema-audit — after implementation, re-audit authored pages to confirm end-to-end coverage.

CLI/rules reminders (from PRAW RULES.md):

• Per PRAW rules, when issues are found in minified build data for HAXcms PHP/NodeJS, fix in the webcomponents monorepo first; the user runs the ubiquity build (the agent does not).
• Do not run the ubiquity script. Do not run a top-of-monorepo build. Use the local hax command, not npx hax.

Acceptance criteria (for the hit-list itself)

• Every hit names a real OER Schema class/property (from the v1.2.0 vocabulary) and the exact emission surface (microdata in render(), haxProperties field, theme wrapper, plugin directive, add-on component, backend API field).
• Every recommended property is in the declared domain of the recommended class (accounting for subClassOf inheritance — see oerschema-audit's references/vocabulary.md).
• The rating is one of: Wired / Partial / Unwired.
• Authored-content gaps are handed to oerschema-audit, not double-reported as code hits.
• Missing-vocabulary needs are handed to oerschema-schema-author, not invented inline.
• NodeJS backend hits target only siteRoutes api/v1 (not the legacy v0 src/routes/*).

Gotchas

• Emission vs. editor integration are two surfaces. A component can emit microdata in its render() (the runtime surface) and/or expose schema-relevant fields in its haxProperties (the authoring surface). A hit on one is independent of the other — report both if both are missing.
• Don't confuse content gaps with code gaps. If an element emits microdata but a page using it is still uncovered, that is an oerschema-audit finding (the author didn't supply the property values), not a code hit.
• Verify domain with inheritance. Quiz is a valid assessing domain because Quiz→Assessment. Do not flag a component emitting assessing on a Quiz wrapper as a domain violation.
• The VitePress plugin maps ::: assessment to Assessment, not Quiz. A quiz in VitePress is ::: assessment type="Quiz". The lack of a dedicated ::: quiz directive is a plugin hit, but the content can still be correctly classed via type="Quiz" → additionalType. Report the missing directive as an authoring-ergonomics hit, not a correctness hit.
• NodeJS v0 routes are out of scope. Per PRAW rules, only siteRoutes api/v1 is in scope; do not flag src/routes/* (legacy v0) — those are left alone until v1 migration.
• Don't edit here. This skill emits a hit-list. Implementation belongs in hax-webcomponent-dev (components), hax-site-building (themes), or the relevant plugin/add-on/backend maintainer.

Dependencies

• Reads: webcomponent source (src/*.js, haxProperties.json, HAXSchema), theme templates, CMS backend route/data code, vitepress-plugin/index.js, google-apps-script/Code.js
• Consults: references/component-patterns.md (candidate elements + emission patterns) and oerschema-audit's references/vocabulary.md (class/property tables — single source of truth)
• Hands off to: hax-webcomponent-dev (components), hax-site-building (themes), oerschema-schema-author (missing vocabulary), oerschema-audit (post-implementation content re-audit)
• Defers to: oerschema-audit (authored-content gaps), hax-a11y-audit (component accessibility)

References

• references/component-patterns.md — candidate HAX elements by pedagogical structure, the two schema surfaces (render microdata + haxProperties), and per-surface emission patterns
• oerschema-audit skill's references/vocabulary.md — OER Schema v1.2.0 class/property tables (consult, do not duplicate)
• OER Schema vocabulary source: oerschema repo app/lib/schema.ts
• PRAW RULES.md: ~/Documents/git/haxtheweb/praw/RULES.md