14 · Credentials System

14 — Credentials System

Versión: 0.1 Última actualización: 2026-04-23 Status: 🟡 Draft

Los certificados son el output tangible del assessment. Deben ser honestos (ganados, no dados), verificables (criptográficamente o vía URL pública), y útiles (linkables, shareables).

Specs de assessment que llevan al cert → 07-assessment.md. Catálogo de paths → 13-paths-catalog.md.

Las 3 capas de credenciales

LAYER 1: Micro-certificate
├── Granted per micro-course completed
├── Auto-generated on course pass
├── PDF + Badge image (LinkedIn ready)
└── Verification URL público

LAYER 2: Path Certificate
├── Granted cuando completes combination específica
├── Auto-generated
├── Superior visual (más dorado, diseño propio)
└── Incluye referencias a todos los micro-certs que lo componen

LAYER 3: Lane Mastery
├── Requires multiple paths + capstone integrador
├── Manual review mandatory
├── Premium visual
└── Invitación a comunidad avanzada (futuro)

Layer 1: Micro-certificate

Qué contiene

PDF (portrait, 1 página):

Logo de Academia Agentes (top)
Título: “Micro-Certificate of Completion”
Subtítulo con nombre del course: ej “Claude Code Pro: Lo que no sabías”
Course code: B1
Nombre completo del learner
Fecha de emisión
Scores (honestos — no genéricos):
- Quizzes passed: X/N
- Exercises completed: N/N with avg score Y%
- Capstone: Z/100
Capstone artefact link (si público): URL al repo/proyecto
Verification URL: academia-agentes.xyz/verify/{cert_id}
QR code que abre verification URL
Signature section (visual firma del curso creator)
Footer: “This certificate reflects completed work, not attendance.”

Badge image (PNG, 512×512):

Versión cuadrada compacta
Logo + course code + “Complete” + fecha
LinkedIn-optimized size
Fondo con color del lane (Builder: púrpura, Operator: azul, Cross: verde)

Visual design

Tipografía: Inter (display) + mono para codes
Colors: accent purple (Builder) / blue (Operator) / green (Cross)
Estilo: limpio, profesional — NO decorativo excesivo
Sello visual: hexágono con course code al centro

Generación técnica

Tools:

react-pdf o puppeteer para PDF render desde HTML template
Template en /templates/micro-cert.html con placeholders
Pipeline automático al pasar capstone

Pipeline:

capstone.passed(user, course)
  → generate_cert(user, course)
  → render_pdf + badge_png
  → upload_to_storage (CF R2)
  → store_metadata_in_db (certificates table)
  → notify_user (email + in-app)

Verification URL

Cada cert tiene URL pública: academia-agentes.xyz/verify/{cert_id}

La página verify muestra:

Cert PDF embebido
Metadata: learner name, course, fecha, scores
Links a artefactos del capstone
Public profile del learner (si opted-in)

Cryptographic signing (futuro):

Por ahora: verification by DB lookup (si el cert existe en nuestra DB, es válido)
v2: JWT firmado con private key, anyone puede verificar sin consultar nuestra DB

Layer 2: Path Certificate

Qué contiene

PDF (portrait, 1-2 páginas):

Título: “Path Certificate”
Subtítulo: nombre del path (ej “Claude Code Engineer”)
Path code: ej B-I
Nombre del learner
Fecha
Composición: los N micro-certs que componen este path, con sus dates
Aggregated scores: promedios de quiz, exercises, capstones
Portfolio: links a todos los capstone artefacts
Verification URL + QR
Signature

Badge (superior al micro):

Visual más premium — gradiente, sello elevado
Incluye sub-badges miniatura de los micro-certs que lo componen

Trigger

Auto-emitido cuando el learner completa los courses requeridos por path:

def check_path_completion(user_id):
  for path in PATHS:
    required_courses = path.required_courses
    user_completed = get_completed_courses(user_id)
    if all(c in user_completed for c in required_courses):
      if not has_path_cert(user_id, path.id):
        emit_path_cert(user_id, path)

Visual differentiation

Los 3 layers deben verse claramente distintos:

Micro: emblema circular, accent color del lane
Path: emblema hexagonal, gradiente con segundo color
Mastery: emblema grande con halo, diseño premium

Layer 3: Lane Mastery

Qué contiene

Similar al Path pero con:

Capstone integrador requerido (manual review)
Reflexión extendida (write-up de 1500+ palabras)
Portfolio curado (learner eligió sus 3 mejores artefactos)
Manual stamp of approval

Visual premium

PDF de 2-3 páginas
Incluye “reflection” del learner impresa (permitido personalizar)
Firma manual (eventualmente digital-signed por mí)
Invitación a comunidad privada (futuro)

Schema DB

certificates (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users,
  type TEXT CHECK (type IN ('micro', 'path', 'mastery')),
  course_id TEXT, -- for micro
  path_id TEXT,   -- for path
  lane_id TEXT,   -- for mastery

  issued_at TIMESTAMPTZ DEFAULT now(),
  issued_version TEXT, -- template version used

  -- Scores (micro)
  quiz_pass_rate FLOAT,
  exercise_avg_score FLOAT,
  capstone_score FLOAT,

  -- Artifacts
  capstone_artifact_url TEXT,
  pdf_url TEXT,  -- CF R2
  badge_url TEXT, -- CF R2

  -- Verification
  verification_slug TEXT UNIQUE, -- for URL
  signature TEXT, -- cryptographic sig (v2)

  -- Status
  status TEXT DEFAULT 'active' CHECK (status IN ('active', 'revoked', 'updated')),
  revoked_reason TEXT,

  -- Manual review (mastery only)
  manual_reviewed BOOL DEFAULT false,
  reviewer_notes TEXT,
  reviewed_at TIMESTAMPTZ
)

LinkedIn integration

Al emitir un cert, el learner recibe opción de:

Direct LinkedIn share — botón que pre-populates un post de LinkedIn con cert metadata
Add to profile — formato que LinkedIn reconoce (Certifications section):
- Organization: “Academia Agentes”
- Certificate URL: verification URL
- Issue date
- Credential ID: cert_id

Standard LinkedIn format supported.

Portfolio público (opcional per learner)

Si opts-in:

URL: academia-agentes.xyz/u/{username}
Lista todos sus certs earned
Links a capstone artifacts
Sobre el learner (self-written)

Si opts-out: sus certs existen pero no tiene página pública. La verification URL sigue funcionando (no lista pública).

Anti-falsificación

Medidas v0.1 (MVP)

Verification URL central (lookup DB)
QR code en cada cert
Cert IDs no predecibles (UUIDs)

Medidas v1.0 (future)

JWT signing con private key
Blockchain attestation (overkill probablemente, pero opción)
Merkle proof de completion events

Qué NO hacemos

❌ NFTs (performative, sin valor real)
❌ Pretender que es “accredited” por alguna entidad formal

Revocation

Un cert puede ser revocado si:

Se detecta fraude en el capstone (copia literal de otro learner)
El learner pide revocation voluntaria
Bug en el pipeline que emitió cert incorrectamente

Al revocar:

Status cambia a revoked en DB
Verification URL muestra “This certificate was revoked on {date}. Reason: {reason}”
Badge image se reemplaza por versión “REVOKED”

Pricing consideration (si se comercializa)

Principio: el cert no se compra. Se gana.

Pero el proceso de obtenerlo cuesta:

Free tier: sin certs, solo progreso tracked
Student tier ($29/mo simulated): micro-certs included
Professional tier ($69/mo): path certs + portfolio público + priority manual review
Cohort tier ($499/12 weeks): Mastery eligible + cohort community

Revocar un cert de alguien que pagó = refund proporcional (policy TBD).

Visual templates — mockups pending

Por ahora el diseño es conceptual. Próximas iteraciones:

HTML template para micro-cert PDF
HTML template para path-cert PDF
HTML template para mastery PDF
Badge design system (variaciones por lane + layer)
Verification page template

Estos van en apps/web/src/templates/certs/ cuando empecemos código.

Open questions

¿Cert expira después de X años? (AI cambia rápido — un cert B1 de 2026 puede ser irrelevante en 2030)
- Propuesta: certs no expiran pero se muestra “Issued on {date} · Content reflects AI landscape at that time”
¿Ofrecer “re-certification” al actualizar curriculum?
¿Permitimos que learners pongan nombre preferido vs legal? (importante inclusividad)
¿Multi-language support? (ES primary, pero eventual EN/PT)
¿Integración con Credly / Accredible / Open Badges? (standardized cred formats)