Repo Upgrade Pack: README, community health files, CI, pilot-kit

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What does this change?
+
+<!-- Briefly describe the change and which layer it touches: research, framework, or prototype. -->
+
+## Why?
+
+<!-- Link the related issue, if any. -->
+
+## Checklist
+
+- [ ] Contains **no real student data** — synthetic or de-identified examples only
+- [ ] Follows the trust-first safety boundary (human validation stays final, no financial/token speculation)
+- [ ] Markdown/JSON changes pass the repo's automated checks
+- [ ] Folder-level README updated if this adds/renames files in a documented folder
+- [ ] ROADMAP.md updated if this completes or changes a roadmap item

.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  python-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Compile-check all Python prototypes
+        run: |
+          find . -name "*.py" -print0 | xargs -0 -n1 python -m py_compile
+
+  validate-badge-schemas:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install jsonschema
+        run: pip install jsonschema
+      - name: Validate example badges against the schema
+        run: |
+          python - <<'PY'
+          import json
+          import sys
+          from pathlib import Path
+
+          from jsonschema import Draft202012Validator
+
+          schema = json.loads(Path("badges/badge-metadata-schema.json").read_text())
+          validator = Draft202012Validator(schema)
+
+          examples = sorted(Path("badges").glob("*-example.json"))
+          if not examples:
+              sys.exit("No badge example files found under badges/")
+
+          failed = False
+          for example in examples:
+              instance = json.loads(example.read_text())
+              errors = sorted(validator.iter_errors(instance), key=str)
+              if errors:
+                  failed = True
+                  print(f"::error file={example}::{len(errors)} schema violation(s)")
+                  for error in errors:
+                      print(f"  - {error.message}")
+              else:
+                  print(f"OK: {example}")
+
+          sys.exit(1 if failed else 0)
+          PY

CITATION.cff

@@ -2,12 +2,21 @@ cff-version: 1.2.0
 title: "OpenLab Agentic Education"
 message: "If you use this framework, please cite it as below."
 type: software
+version: "0.1.0"
+date-released: "2026-07-08"
 authors:
   - family-names: Vargas
     given-names: Roger
 abstract: "A research and prototype framework for preserving human agency, evidence, and teacher judgment in AI-supported learning."
-license: "LicenseRef-TBD"
-repository-code: "https://github.com/porroto/openlab-agentic-education"
+license: "MIT"
+repository-code: "https://github.com/porroto/Agentic-Education"
+preferred-citation:
+  type: article
+  title: "From Co-Intelligence to Proof-of-Learning"
+  authors:
+    - family-names: Vargas
+      given-names: Roger
+  year: 2026
 keywords:
   - agentic education
   - proof-of-learning

CODE_OF_CONDUCT.md

@@ -0,0 +1,61 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community — one that reflects the trust-first,
+human-governed values of this project.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Focusing on what is best for learners, educators, and the community, not
+  just individual contributors
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Uploading or requesting real, identifiable student data in violation of this
+  project's [safety boundary](README.md#safety--ethics-boundary)
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior deemed inappropriate, threatening, offensive, or
+harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (issues, pull requests,
+discussions) and when an individual is officially representing the project in
+public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer listed in [SECURITY.md](SECURITY.md). All
+complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thanks for your interest in OpenLab Agentic Education. This is a research and prototype project — contributions from educators, researchers, and builders are welcome.
+
+## Ways to contribute
+
+- **Educators & researchers** — open an issue with feedback on the concept paper, rubrics, or governance documents. Use the "Research Note" or "Idea" issue templates.
+- **Builders** — improve or extend prototypes in `agents/` and `prototypes/`. Open an issue first for anything beyond a small fix.
+- **Everyone** — report unclear docs, broken links, or gaps between the framework and real classroom practice.
+
+## The synthetic-data rule
+
+This is the one rule that overrides everything else:
+
+> **No real student data, ever.** No real names, identifiable student work, school records, private conversations, or any personally identifiable information from a minor.
+
+All examples, sample evidence packages, and prototype inputs/outputs must be synthetic or fully de-identified. Pull requests that add real student data will be closed, not merged with edits. See [`governance/student-data-rules.md`](governance/student-data-rules.md) and [`data/README.md`](data/README.md).
+
+## Workflow
+
+1. Open an issue describing the change (see [`gh600/github-workflow-lab.md`](gh600/github-workflow-lab.md) for the suggested pattern).
+2. Create a branch and draft or revise the file(s).
+3. Make sure any markdown changes pass the repo's markdown check.
+4. Review your change against the [OLA trust rules](docs/05-ola-trust-layer.md) and the safety boundary in the [README](README.md#safety--ethics-boundary).
+5. Open a pull request using the PR template. A human maintainer reviews and merges — AI-assisted contributions are welcome but final merge decisions are made by a person.
+
+## Code of Conduct
+
+Participation in this project is governed by our [Code of Conduct](CODE_OF_CONDUCT.md).

README.md

@@ -1,51 +1,124 @@
-# OpenLab Agentic Education
+# 🌐 OpenLab Agentic Education
 
-**OpenLab Agentic Education** is a research and prototype framework for preserving human agency in AI-supported learning.
+**Preserving human agency in AI-supported learning.**
 
-It explores how students, teachers, families, communities, institutions, and AI agents can co-create learning evidence while keeping human judgment, ethics, privacy, and proof-of-learning at the center.
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Markdown Check](https://github.com/porroto/Agentic-Education/actions/workflows/markdown-check.yml/badge.svg)](https://github.com/porroto/Agentic-Education/actions/workflows/markdown-check.yml)
+[![Data Policy: Synthetic Only](https://img.shields.io/badge/data-synthetic--only-critical.svg)](data/README.md)
+[![Status: Research Prototype](https://img.shields.io/badge/status-research--prototype-yellow.svg)](ROADMAP.md)
 
-> **AI assists. Humans govern. Evidence speaks. Communities validate.**
+**AI assists. Humans govern. Evidence speaks. Communities validate.**
 
-## Why this exists
+*Not robot-first. Trust-first.*
 
-Generative AI is changing how learners create, research, communicate, design, and demonstrate understanding. If AI can generate polished artifacts, education needs better ways to validate the human learning journey behind those artifacts.
+## What is this?
 
-OpenLab shifts the question from:
+**OpenLab Agentic Education** is a research and prototype framework exploring how students, teachers, families, communities, institutions, and AI agents can **co-create learning evidence** — without surrendering human judgment to automation.
 
-> Did the learner use AI?
+It is the public home of the OpenLab / S.A.T. Labs research line on:
 
-To:
+- 📜 **Proof-of-learning** — verifiable evidence of real learning, owned by the learner
+- 🤝 **Human-governed AI agents** — AI that assists review; humans validate meaning
+- 🎖 **Learner-owned credentials** — portable, community-validated recognition
+- 🛡 **Trust-first governance** — ethics, consent, and accountability by design
 
-> What happened to the learner's thinking, agency, evidence, and growth while working with AI?
+> **Anchor paper:** [*From Co-Intelligence to Proof-of-Learning*](papers/from-co-intelligence-to-proof-of-learning.md) — the conceptual foundation for everything in this repo.
 
-## Core idea
+## How the repo is organized
 
-OpenLab proposes **Agentic Education**: a learning model where students use AI responsibly to build real-world projects, document process evidence, reflect on decisions, and receive human validation for growth.
+The project moves through three connected layers, with a human-governance loop running through all of them:
 
-The final artifact is not the only proof.
+```mermaid
+flowchart LR
+    subgraph Research["🔬 Research"]
+        A[papers/]
+        B[proposals/]
+        C[docs/]
+    end
+    subgraph Framework["🧭 Framework"]
+        D[framework/]
+        E[governance/]
+        F[missions/]
+    end
+    subgraph Prototype["⚙️ Prototype"]
+        G[agents/]
+        H[badges/]
+        I[prototypes/]
+        J[data/]
+    end
 
-**The transformation process becomes the proof.**
+    Research --> Framework --> Prototype
+    Prototype -. human validation .-> Framework
+    Framework -. human validation .-> Research
+```
+
+| Layer | What lives here | Folders |
+|---|---|---|
+| 🔬 **Research** | Concept papers, proposals, references | `papers/` · `proposals/` · `docs/` |
+| 🧭 **Framework** | Rubrics, learning loops, governance, ethics | `framework/` · `governance/` · `missions/` |
+| ⚙️ **Prototype** | Agent specs, badge schemas, synthetic evidence review | `agents/` · `badges/` · `prototypes/` · `data/` |
+
+`gh600/` bridges an external agentic-AI certification track to the OpenLab framework — see [`gh600/certification-to-openlab-map.md`](gh600/certification-to-openlab-map.md).
+
+Start here:
 
-## Repository layers
+1. [`VISION.md`](VISION.md) — why this exists
+2. [`MANIFESTO.md`](MANIFESTO.md) — the principles we won't compromise
+3. [`ROADMAP.md`](ROADMAP.md) — where this is going
+4. [`papers/`](papers/) — the concept paper and research grounding
 
-```text
-Research Layer     -> papers, proposals, references
-Framework Layer    -> rubrics, learning loops, governance, ethics
-Prototype Layer    -> agents, badge schemas, synthetic evidence review
+## Quick start (researchers & educators)
+
+```bash
+git clone https://github.com/porroto/Agentic-Education.git
+cd Agentic-Education
 ```
 
-## Quick start
+- **Educators** → start with [`framework/`](framework/) for rubrics and learning-loop designs
+- **Researchers** → start with [`papers/`](papers/) and [`proposals/`](proposals/)
+- **Builders** → start with [`agents/`](agents/) and [`prototypes/`](prototypes/) (synthetic data only)
 
-Start here:
+## Safety & Ethics Boundary
+
+This project follows a strict trust-first boundary:
+
+- ✅ **Synthetic and de-identified examples only** — no real student data lives in this repo
+- ✅ **Human validation is final** — AI suggests; teachers and communities decide
+- ✅ **Classroom pilots require** school policy compliance, parent/guardian consent, and ethics review
+- ✅ **Recognition, not speculation** — tokens and badges represent learning evidence, never financial instruments in school contexts
+
+## Who is this for?
+
+- **Teachers** designing evidence-based, project-driven classrooms
+- **Researchers** studying human-AI co-intelligence in K–12 education
+- **EdTech builders** who believe student agency is non-negotiable
+- **Communities & families** who want a seat at the validation table
+
+## Roadmap (high level)
+
+- [x] Concept paper: *From Co-Intelligence to Proof-of-Learning*
+- [x] Three-layer architecture (Research → Framework → Prototype)
+- [ ] Evidence Review Agent v0 (synthetic artifacts, rubric alignment, audit trail)
+- [ ] Badge schema v1 + mock digital wallet workflow
+- [ ] Classroom-safe pilot kit (consent templates, teacher guide, rubrics)
+- [ ] Community validation protocol
+- [ ] Public research brief + call for collaborators
+
+See [ROADMAP.md](ROADMAP.md) for details.
+
+## Contributing
+
+Contributions, critiques, and classroom perspectives are welcome — especially from educators and researchers. Please read [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md) first.
+
+## Citing this work
+
+If you use this framework in research, please cite it via [CITATION.cff](CITATION.cff).
 
-1. Read [`VISION.md`](VISION.md)
-2. Read the concept paper: [`papers/from-co-intelligence-to-proof-of-learning.md`](papers/from-co-intelligence-to-proof-of-learning.md)
-3. Review the learning loop: [`framework/openlab-learning-loop.md`](framework/openlab-learning-loop.md)
-4. Try a mission template: [`missions/environmental-sensor-mission.md`](missions/environmental-sensor-mission.md)
-5. Review governance before using any student data: [`governance/student-data-rules.md`](governance/student-data-rules.md)
+## License
 
-## Safety boundary
+MIT — see [LICENSE](LICENSE).
 
-This repository uses **synthetic examples only**. Do not upload real student names, identifiable student work, school records, private conversations, or sensitive data.
+---
 
-Any future classroom pilot should follow school policy, parent/guardian consent requirements, and appropriate research ethics review.
+**Built by [Roger Vargas](https://github.com/porroto)** · STEM educator & founder, S.A.T. Labs / OpenLab
+*A Colombian heart with a global mind.* 🌎

REPO_TREE.md

@@ -7,7 +7,7 @@ openlab-agentic-education/
 ├── ROADMAP.md
 ├── MANIFESTO.md
 ├── CITATION.cff
-├── LICENSE.md
+├── LICENSE
 ├── papers/
 ├── proposals/
 ├── docs/

SECURITY.md

@@ -0,0 +1,33 @@
+# Security & Data Safety Policy
+
+## Reporting a concern
+
+This is a research and prototype repository, not a production system. If you
+find a security issue in a prototype (for example, in
+[`prototypes/evidence-review-agent/`](prototypes/evidence-review-agent/)), or
+you spot real student data or other personally identifiable information
+anywhere in this repository, please open a private report:
+
+- Open a [GitHub security advisory](../../security/advisories/new) for this repository, or
+- Contact the maintainer, [Roger Vargas](https://github.com/porroto), directly.
+
+Please do not open a public issue for reports that involve real student data —
+report it privately so it can be removed before wider attention draws to it.
+
+## No real student data, ever
+
+This repository's governing rule: **no real student data lives here.** Every
+example, sample evidence package, badge, and prototype input/output must be
+synthetic or fully de-identified. See
+[`governance/student-data-rules.md`](governance/student-data-rules.md) and
+[`data/README.md`](data/README.md) for the full policy.
+
+If you discover real student data committed to this repository, please report
+it immediately using the private channel above so it can be removed and the
+history scrubbed.
+
+## Supported scope
+
+Prototypes in this repository are research demos, not hardened software. Do
+not connect them to real student information systems or production
+credential-issuing infrastructure without a full security and privacy review.