Clio | Generative Publishing Studio

A PedOS 1.1 Lumina Documentation Map

PedOS 1.1 Lumina is the platform and SDK release. App Runtime v2 is the installed-app compatibility layer inside Lumina: the app shell, window.PedOSApp, settings, storage, install gate, and approved evidence APIs.

Two Build PathsDeveloper ZIP upload or Agentic Studio natural-language build. Preflight AgentDeterministic SDK, KIV, prompt-quality, and credit checks before generation. Studio Dev TeamProduct, UX, architect, developer, QA, data, and release roles. Studio Output ContractWhat Agentic Studio must generate for every app. Runtime MatrixLocked PedOS 1.1 Lumina options and future-version KIV rule. Runtime APIsContext, settings, user storage, lifecycle hooks, and evidence capture. Package FormatRequired files, manifest metadata, app assets, and optional migrations. Package ModelPHP entry point, hooks, SQL migrations, namespacing, readme, and assets. Quality GatesUI, technical, security, privacy, analytics, and human-language checks. Submission ReviewPreview, iterate, submit, admin validate, install, run, and analyze. API ReferenceStable endpoints available to approved installed apps.

M PedOS 1.1 Lumina Runtime Matrix

Version lock: PedOS 1.1 Lumina is the platform release. PedOS App Runtime v2 is the installed-app compatibility layer inside that release. Agentic Studio, free-form prompts, and developer ZIP submissions must stay inside this matrix unless the feature is explicitly moved into a future PedOS version.

Area	Current Runtime v2 options	Rule
App placement after installation	`my_apps`, `course_space`, `student_activity`, `teacher_dashboard`, `analytics_dashboard`, `admin_tools`	Every placement must have a visible mount, manifest host surface, admin health check, and staging canary.
App capabilities	`auth_context`, `settings`, `user_storage`, `telemetry`, `analytics`, `file_upload`, `ai_generation`, `admin_review`	Every capability maps to manifest permissions, a runtime bridge service, review gates, and smoke coverage.
Expected views	`launch_view`, `main_activity`, `settings`, `analytics`, `review_queue`, `export`	Every selected view becomes a QA expectation.
Studio app types	`retrieval_practice`, `formative_assessment`, `peer_feedback`, `classroom_workflow`, `learning_analytics`, `adaptive_orchestration`, `research_study`, `custom`	Every app type must have prompt guidance, package validation, and staging canary coverage.

Free-form prompt guard: if a user asks for unsupported placements or capabilities, Studio notifies the user before generation. The user must remove the request or explicitly confirm that it should be recorded as future PedOS KIV and left out of the current build. The current build remains constrained to PedOS 1.1 Lumina / App Runtime v2.

P Deterministic Preflight Agent

Before Agentic Studio starts the AI development team, a deterministic preflight helper checks the user's brief without spending LearnAdapt credits. It is not a generative model. Users can start with a guided brief or a free-form prompt; either path is normalized into the committed PedOS 1.1 Lumina / App Runtime v2 matrix before planning and coding.

SDK fit

Checks app type, placement, capabilities, expected views, evidence boundary, and unsupported requests against the current versioned runtime matrix.

Prompt-to-brief sync

In free-form mode, Studio infers the matching app type, AI/file/analytics needs, views, users, workflow, and evidence boundary from the prompt so stale form defaults cannot override client intent.

Brief quality

Looks for audience, subject or context, user action, reviewer control, state/settings, data boundary, analytics, and non-goals before the agents plan the package.

KIV acceptance

Flags future-version requests in plain language, asks the user to accept the nearest supported equivalent, and records KIV items instead of letting the build silently invent unsupported SDK behavior.

Credit readiness

Shows the estimated LearnAdapt credit range and blocks generation when the account cannot cover the high-end estimate. Actual charges still come from completed metered AI usage.

Preview evidence

Requires builders to run the preview and attach screenshots before directory submission, so admin review can inspect the real app state across displays.

Research implication: preflight preserves the teacher's original intent while separating current-build requirements from future platform requests. This gives workshop researchers a cleaner trail from brief, to normalized contract, to generated package, to KIV product backlog.

B Two Ways to Build PedOS Apps

PedOS should feel as simple as installing an approved app: find it in the Plugins Directory, install it into My Apps, open it, configure it, use it, and see analytics. The difference is how the package is created before review.

Path 1: Developer ZIP upload

Developers create the package locally, include manifest.json, php/init.php, scoped assets, optional SQL migration, screenshots, and README, then upload the ZIP for validation and admin review.

Path 2: Agentic Studio build

Non-coders describe the app in natural language. The Studio agents act as developers for them: planning, coding, packaging, validating, previewing, and preparing the same ZIP-equivalent app package.

Same destination

Both paths must pass the same SDK, safety, evidence, UI, and runtime gates before the app can appear in the Plugins Directory or be installed into My Apps.

Developer ZIP

→

SDK validation

→

Admin review

→

C Agentic Studio as a Development Team

For non-coders, the Studio agents are the development team. The user supplies intent, constraints, and review feedback in natural language; the agents turn that into the same package a professional developer team would submit.

Development role	Studio responsibility	Output
Product / SRS analyst	Clarifies purpose, users, success criteria, non-goals, constraints, and review requirements.	Structured app brief and acceptance criteria.
Pedagogical designer	Aligns the workflow to teaching, learning, feedback, assessment, or facilitation goals.	Learning/activity flow and evidence rationale.
UX/UI designer	Designs the app screens in human-facing language for learners, educators, researchers, or admins.	Launch view, main activity, settings, analytics, and empty/error states.
Solution architect	Maps the brief to PedOS package structure, permissions, settings, storage, hooks, and data boundaries.	Manifest/runtime contract and implementation plan.
Full-stack developer	Writes `php/init.php`, `js/main.js`, `css/style.css`, and optional `migration.sql`.	SDK-compliant app package.
Data/evidence engineer	Selects the minimum evidence category and prevents over-collection.	App activity, learning progress, adaptive support, or research-study contract.
QA/security reviewer	Checks interactivity, validation, XSS, SQL safety, route guards, runtime bridge, and human-facing copy.	Validation report and required fixes.
Release manager	Prepares icon, screenshots, README, directory metadata, version, and admin review notes.	Submission-ready package for Plugins Directory review.

Agent sequence: Client brief first; pedagogy, UX, and architecture in parallel; package build and evidence design in parallel; then QA/security review, preview iteration, release packaging, admin approval, directory listing, and My Apps installation. Iteration requests are treated like scoped client change orders.

D From Prompt to Production

Watch the technical overview of how Agentic Studio turns a natural-language brief into a reviewable PedOS app package. The SDK is supplied by the LearnAdapt runtime; each generated app must conform to the SDK contract before it can be approved, installed, and allowed to record evidence.

0 Prompting Guide for Agentic Studio

Agentic Studio works best when the brief describes the app workflow, primary users, responsible reviewers, evidence boundary, and expected analytics. Studio then converts the brief into a complete SDK-compliant app package, not a loose mockup.

Build a [plugin type] for [audience] in [subject/context].

Primary users should:
- ...

Responsible reviewers should:
- ...

The app should show:
- ...

Evidence should be:
- App activity / Learning progress / Adaptive support

Do not:
- ...

Analytics I want:
- ...

For non-coders

Describe the goal, user task, responsible review controls, and analytics in plain language. Studio maps that into the SDK package contract.

For developers

Add SDK details such as host surfaces, settings, permissions, hooks, data schema, and runtime behavior when you need precise implementation control.

For researchers

State what evidence should be exportable, what should stay aggregated, and what consent or study boundaries apply.

Open Studio Prompt Guide Read Studio FAQ

1 What Agentic Studio Generates

Important: Agentic Studio does not copy the whole PedOS SDK into every plugin. It generates the complete app package that conforms to the SDK. LearnAdapt supplies the runtime SDK at launch through the platform shell and window.PedOSApp.

Whether an app is written by a developer or generated from a Studio brief, the final approved version must deploy to the same package layout and pass the same health checks.

plugins/{slug}/current/
├── manifest.json          ← app identity, permissions, evidence profile, settings, surfaces
├── php/init.php           ← app fragment rendered only on /plugin/{slug}
├── js/main.js             ← uses window.PedOSApp for context, storage, settings, evidence
├── css/style.css          ← scoped visual system for the app
├── migration.sql          ← optional approved durable tables
└── assets/                ← optional icons, screenshots, app assets

App fragment only. Generated PHP must not render a standalone HTML document.

Route guard. php/init.php must return silently unless the route is /plugin/{slug}.

Root marker. The rendered UI must include data-plugin-slug="{slug}" or id="{slug}-app".

Runtime bridge. JavaScript must use window.PedOSApp for context, settings, storage, evidence, analytics, files, AI generation, and review status.

First-class app behavior. Installed apps open from My Apps and keep the LearnAdapt shell, settings, and analytics surfaces.

Human-facing language. Learners and educators see plain evidence labels, not raw telemetry, BKT, xAPI, SDK, or profile tokens.

2 App Runtime v2 inside PedOS 1.1

PedOS 1.1 Lumina defines the overall SDK, review, directory, installation, and analytics release. Runtime v2 is the app-level contract within that release. It makes installed plugins behave like real apps by wrapping /plugin/{slug} in a PedOS app shell and exposing window.PedOSApp for context, settings, user-scoped storage, telemetry, analytics summaries, reviewed files, credit-metered AI generation, and release status. Apps should use these APIs instead of creating their own persistence, upload, analytics, or AI endpoints.

App shell

Consistent launch surface with My Apps, Settings, Analytics, and Plugins Directory navigation.

Runtime SDK

window.PedOSApp exposes the approved service for every selected app capability after installation.

Install gate

Settings, storage, analytics, files, AI calls, review status, and persistent telemetry require a logged-in user and an installed active app.

// Frontend JS inside an installed app
const context = await window.PedOSApp.getContext();
const settings = (await window.PedOSApp.getSettings()).settings;
await window.PedOSApp.storage.set('draft_state', { step: 2, updated_at: new Date().toISOString() });
await window.PedOSApp.telemetry('answer_submitted', statement, { require_bkt_ready: true });
const summary = await window.PedOSApp.analytics.summary();
const generated = await window.PedOSApp.ai.generate({ topic: 'fractions', level: 'Primary 6' });

3 Architecture

PedOS enforces a 3-tier subsumption guardrail. Your plugins live at Tier 3 — free to innovate, but bounded by ethics and BKT integrity.

TIER 1

Ethics & Safety — LOCKED

Core OS only. Plugins cannot override ethical guardrails.

TIER 2

Bayesian Knowledge Tracing — READ-ONLY

Plugins can read P(L) mastery but cannot manipulate the official BKT state.

TIER 3

Developer Zone — YOUR CODE

Custom scaffolding, assessments, visualizations, and LoRA weight adapters.

4 Package Structure

Manual SDK submissions and Studio-generated apps use the same package model:

my-plugin/
├── manifest.json          ← REQUIRED: metadata & permissions
├── php/init.php           ← REQUIRED: PHP entry point
├── js/main.js             ← REQUIRED for interactive Studio apps
├── css/style.css          ← REQUIRED for interactive Studio apps
├── migration.sql          ← Optional: CREATE TABLE statements
├── assets/                ← Optional: images, icons
├── screenshots/           ← Recommended for directory listing
└── README.md              ← Required for directory review

M

manifest.json

Declares name, slug, version, author, category, permissions, hooks, and table declarations. Required for all submissions.

PHP

php/init.php

The single entry point autoloaded by plugin_loader.php. Register hooks and actions here.

SEC

.htaccess (auto)

Auto-generated on deployment to disable directory listing. Runtime access is mediated by the LearnAdapt router and SAST validation.

5 PedOS Package Model

PedOS deliberately follows a mature plugin-package discipline because the host stack is PHP and SQL: a versioned plugin directory, one guarded PHP entry point, scoped frontend assets, optional SQL migrations, hooks/actions/filters, and a review process before directory distribution. Agentic Studio must behave like a careful plugin developer and produce the same artifacts a human developer would submit.

Single guarded PHP entry

php/init.php is loaded by the platform. It registers hooks and renders UI only when the route is /plugin/{slug}.

Hooks and lifecycle actions

Apps may use approved PedOS actions and filters for installation, uninstallation, launch, settings, learner-response events, and analytics hooks.

SQL migrations

Durable tables are created only through reviewed migrations. Table names must be slug-prefixed, idempotent, and limited to approved schema changes.

Namespaced assets

CSS classes, DOM ids, JS storage keys, and database tables must be prefixed with the plugin slug to avoid collisions.

Directory metadata

Every app needs a plain-language summary, icon, screenshots, version, author, support contact, permissions, evidence category, and review status.

No hidden tracking

Apps cannot collect evidence beyond the approved profile. Learner and educator screens must explain data use in human language.

Plugin package pattern	PedOS 1.1 Lumina equivalent	Agentic Studio obligation
Plugin folder	`plugins/{slug}/current/`	Create a complete package with stable slug and version.
Main PHP file	`php/init.php`	Render only an app fragment behind a route guard.
Hooks/actions/filters	`LearnAdapt_Hook_System`	Use approved lifecycle and learning hooks only.
Database activation routine	`migration.sql`	Create slug-prefixed, idempotent tables only when needed.
Readme and assets	`README.md`, icon, screenshots	Generate human-readable documentation and directory media.
Plugin review	Admin health check and SAST	Fail fast when package, safety, evidence, or UI gates are not met.

6 Manifest Runtime Contract

Every deployed app should declare a runtime block in manifest.json. Agentic Studio now writes this automatically during deployment, and manual SDK submissions should include it explicitly.

{
  "name": "Retrieval Sprint",
  "slug": "retrieval_sprint",
  "runtime": {
    "version": "pedos_app_runtime_v2",
    "launch": { "display": "app_shell", "route": "/plugin/retrieval_sprint" },
    "permissions": [
      "context:read",
      "settings:read",
      "settings:write",
      "storage:user",
      "telemetry:learning_evidence"
    ],
    "host_surfaces": ["standalone_app", "dashboard_my_apps", "settings_panel", "analytics_panel"],
    "settings_schema": [
      { "key": "default_mode", "label": "Default mode", "type": "select", "options": ["guided", "independent"], "default": "guided" },
      { "key": "save_progress", "label": "Save progress", "type": "boolean", "default": true }
    ]
  }
}

7 Hook System

Approved filters and actions intercept platform behavior through LearnAdapt_Hook_System:

Hook	Type	Description	Tier
`pedos_plugin_{slug}_activate`	Action	Recorded when an approved plugin is deployed into the directory runtime	3
`pedos_plugin_{slug}_deactivate`	Action	Recorded when an admin removes a plugin from active runtime loading	3
`pedos_plugin_{slug}_install`	Action	Runs after a user installs an approved directory plugin	3
`pedos_plugin_{slug}_uninstall`	Action	Runs after a user removes an installed plugin	3
`override_tutor_action`	Filter	Intercept Educational AI response	3
`after_learner_response`	Action	Fires after learner submits answer	3
`before_scaffold_display`	Filter	Modify scaffolding content	3
`on_mastery_update`	Action	BKT mastery probability changed	2 (RO)
`on_session_start`	Action	Learner session begins	3

// php/init.php — Example: Dyslexia scaffold override
LearnAdapt_Hook_System::add_filter('override_tutor_action', function($action, $ctx) {
    if (($ctx['time_elapsed_ms'] ?? 0) > 15000) {
        return ['agent' => 'DyslexiaBot', 'command' => 'SIMPLIFY_TEXT'];
    }
    return $action;
}, 20);

// Optional install lifecycle hook; no output during lifecycle execution.
LearnAdapt_Hook_System::add_action('pedos_plugin_my_plugin_install', function($ctx) {
    // Initialize user-scoped plugin defaults if needed.
}, 10);

// Page-rendering plugins must stay silent during global autoload
$path = parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH);
if ($path !== '/plugin/my_plugin') {
    return;
}
// Render plugin UI below this guard.

8 Evidence, Telemetry & xAPI

Human-facing evidence, technical enforcement. Studio users choose App activity, Learning progress, or Adaptive support. PedOS maps that choice to the approved telemetry profile. Preview uses local/mock events only. After admin approval and user installation, app evidence is accepted through the gated plugin endpoint.

App activity

Operational or workflow events such as launches, phase changes, notes, and button actions. No learning inference required.

Learning progress

Practice, formative, reflection, rubric, or assessment evidence. Internally maps to BKT-ready fields where appropriate.

Adaptive support

Hints, scaffolds, orchestration, agent handoffs, and support-mode changes. Internally maps to ES-LLMs-ready traces where approved.

Studio preview

Uses mock/local events for preview. Server-side evidence writes are blocked until directory approval and user installation.

Field	Where	Purpose
`skill_id`	`object.definition.extensions`	Maps the event to a knowledge component for BKT.
`item_id`	`object.definition.extensions`	Identifies the prompt, question, rubric item, or activity step.
`result.success`	`result`	Observed correct/incorrect evidence for mastery updates.
`timestamp` or `attempt_index`	Top-level statement or extensions	Preserves ordered learning traces for future model fitting.
`confidence`, `hint_count`, `difficulty`	Extensions	Optional covariates for richer research and adaptive models.

// Frontend JS — approved installed runtime telemetry, BKT-ready
await window.PedOSApp.telemetry('answer_submitted', {
      timestamp: new Date().toISOString(),
      verb:  { id: 'https://w3id.org/xapi/adl/verbs/answered' },
      object: {
        id: 'my_plugin:question_1',
        definition: {
          name: { 'en-US': 'Question 1' },
          type: 'https://learnadaptresearch.org/xapi/activities/pedos-plugin-interaction',
          extensions: {
            'http://learnadaptresearch.org/extensions/skill_id': 'fractions_equivalence',
            'http://learnadaptresearch.org/extensions/item_id': 'question_1',
            'http://learnadaptresearch.org/extensions/attempt_index': 1,
            'http://learnadaptresearch.org/extensions/response_time_ms': 1200,
            'http://learnadaptresearch.org/extensions/event_type': 'answer_submitted',
            'http://learnadaptresearch.org/extensions/confidence': 4
          }
        }
      },
      result: { score: { scaled: 0.8 }, success: true }
    },
    { require_bkt_ready: true }
);

9 Quality Gates

PedOS quality gates combine static code checks, user-experience review, and plugin package validation. These gates apply to both human developers and Agentic Studio's developer agents.

Banned functions

exec, eval, system, shell_exec, passthru, proc_open, unserialize, assert — instant rejection.

SAST validation

Automated static analysis scores 0–100. Minimum score: 60. Checks for SQL injection, XSS, banned functions, and convention violations.

Runtime contract

Validation checks route guard, app fragment rendering, root marker, asset paths, window.PedOSApp, installed-app behavior, and analytics surfaces.

Human-facing UI

Learner and educator screens must not expose raw telemetry, JSON traces, BKT, xAPI, SDK contract terms, or internal profile names.

Sandbox isolation

Plugins are published under a versioned directory and loaded through the main router. SAST validation rejects unsafe PHP, external access, and incompatible platform APIs before deployment.

Directory readiness

Approved apps need icon, screenshots, summary, version, author, support contact, permission summary, evidence category, and install instructions.

10 Submission Lifecycle

Directory review model: preview and iteration happen before submission; admin approval is required before directory listing, installation, persistent evidence capture, and analytics.

Brief

→

Build

→

Preview

→

Submit

→

Admin approve

→

Install

→

Run + analytics

#	Review Check	Required
1	Valid manifest.json with all required fields	Required
2	SAST score ≥ 60/100	Required
3	No banned functions in any file	Required
4	PedOS Runtime v2 gates pass: route guard, root marker, asset paths, `window.PedOSApp`	Required
5	CSS namespaced with plugin slug prefix	Required
6	JS uses IIFE or module pattern	Required
7	Persistent evidence matches the approved profile and user installation state	Required
8	User-facing UI hides raw telemetry, BKT, xAPI, internal profile names, and JSON traces	Required
9	DB tables prefixed with plugin slug when durable storage is approved	Required

11 Platform API Reference

Endpoint	Method	Auth	Description
`/api/plugins?action=telemetry`	POST	Session + installed plugin	Emit approved plugin xAPI telemetry
`/api/plugins?action=runtime-context`	GET	Session + installed app	Return runtime context, manifest summary, permissions, settings schema, and host URLs
`/api/plugins?action=app-settings`	GET/POST	Session + installed app	Read or update app-specific settings declared in the manifest schema
`/api/plugins?action=app-storage`	GET/POST/DELETE	Session + installed app	Read, write, list, or remove lightweight user-scoped app storage
`/api/plugins?action=analytics-summary`	GET	Session + installed app	Read human-facing activity and learning-progress summaries for apps approved for analytics
`/api/plugins?action=app-files`	GET/POST/DELETE	Session + installed app	List, upload, or remove reviewed user files for apps approved for file upload
`/api/plugins?action=ai-generate`	POST	Session + installed app + credits	Run approved AI generation through LearnAdapt credit metering; preview samples use 0 credits
`/api/plugins?action=review-status`	GET	Session + installed app	Return approved review, release, and installation status for the app
`/api/plugins?action=toggle`	POST	Session	Install or uninstall a directory plugin for the current user and record lifecycle hooks
`/api/xapi`	POST	Platform services	Core platform xAPI ingestion used outside the plugin sandbox
`/api/sensor_stream`	POST	—	EEG/eye-tracking sensor data
`/api/v1/analytics/risk`	GET	—	Learner risk assessment
`/api/v1/analytics/fairness`	GET	—	Algorithmic fairness audit
`/api/orchestrator`	POST	—	ES-LLM multi-agent orchestration
`/api/v1/studio/tasks`	POST	Session	Submit AI generation prompt

Plugin SDK