TimeBack Events Alpha Skill Pack

One-Line Install

Claude Code personal skill install:

sh -c 'd="$HOME/.claude/skills/timeback-events-alpha"; b="https://platform3-andymontgomery-9773s-projects.vercel.app/events/alpha/skill_pack"; mkdir -p "$d/references" "$d/agents"; for f in SKILL.md references/canonical-surface.md references/worked-example.md references/runnable-check.md references/leak-check.md agents/openai.yaml; do curl --max-time 20 --retry 3 --retry-all-errors --retry-delay 2 -fsSL "$b/pack/$f" -o "$d/$f"; done'

Codex personal skill install:

sh -c 'd="${CODEX_HOME:-$HOME/.codex}/skills/timeback-events-alpha"; b="https://platform3-andymontgomery-9773s-projects.vercel.app/events/alpha/skill_pack"; mkdir -p "$d/references" "$d/agents"; for f in SKILL.md references/canonical-surface.md references/worked-example.md references/runnable-check.md references/leak-check.md agents/openai.yaml; do curl --max-time 20 --retry 3 --retry-all-errors --retry-delay 2 -fsSL "$b/pack/$f" -o "$d/$f"; done'

After install, restart the agent runtime and ask: Use timeback-events-alpha to read demo activity for student-ada-001.

First Live Call

This is the smallest copy-paste proof for a cold developer: mint a demo Events token and read one student's activity stream.

export EVENTS_BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/events/alpha/implementation/api"
MINT=$(curl --max-time 20 --retry 3 --retry-all-errors --retry-delay 2 -fsS -X POST "$EVENTS_BASE_URL/dev/mint?tenantId=demo")
TOKEN=$(printf '%s' "$MINT" | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>process.stdout.write(JSON.parse(s).token))')
TENANT_ID=$(printf '%s' "$MINT" | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>process.stdout.write(JSON.parse(s).tenantId))')
curl --max-time 20 --retry 3 --retry-all-errors --retry-delay 2 -fsS "$EVENTS_BASE_URL/events?studentId=student-ada-001&pageSize=5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Timeback-Tenant: $TENANT_ID"

For the teacher-report workflow, run the worked example. It writes one content-view event for seeded id student-ada-001, reads it back, and prints report JSON from the public surface.

Register a Producer Source

With an operator-supplied token carrying events:sources:write, call POST /activity-sources with only sourceIri and name. The platform generates the UUID; an identical retry returns the same registration. Never derive an id in the producer or reuse another app's source.

curl -fsS -X POST "$EVENTS_BASE_URL/activity-sources" \
  -H "Authorization: Bearer $EVENTS_SOURCE_ADMIN_TOKEN" \
  -H "X-Timeback-Tenant: $TENANT_ID" \
  -H "Content-Type: application/json" \
  --data '{"sourceIri":"https://producer.example.edu","name":"Producer Web"}'

The response is 201 for a new source or 200 for an identical replay. Store data.id as the producer's activitySourceId.

Pack Files

SKILL.md

Concise installable skill with `name` and `description` frontmatter plus Instructions, Examples, and Guidelines.

worked-example.md

One end-to-end teacher report workflow with expected statuses and output shape.

runnable-check.md

Acceptance check that compares returned Events platform facts at runtime.

canonical-surface.md

Endpoint, credential, status, source-import, attendance, discipline, and deferred-behavior reference.

leak-check.md

Binary stop checklist for avoiding local platform logic.

skill-pack.json

Machine-readable manifest for install paths, docs, proof commands, and route verification.

Runnable Proof

The check mints Events demo credentials, writes one event, imports one source-shaped TimeBack row, reads both back through public Events endpoints, and probes attendance and discipline read lists. It carries no local answer table; expected facts come from the platform at runtime.

# After installing the pack, open references/runnable-check.md and run its command block.
# Passing output ends with:
{
  "result": "pass",
  "studentId": "student-ada-001",
  "contentId": "content-fractions-video-01",
  "listedCreatedEvent": true,
  "listedImportedEvent": true,
  "checkedBySurfaceCallsOnly": true
}

Live proof is generated from the command in runnable-check.md and uses only the canonical Events API demo tenant.

No Local Platform Work

No event-kind map, Caliper tuple map, source-import adapter map, descriptor table, or dedupe/hash logic.
No Results, mastery, content-effectiveness, NWEA, XP, school-day, or minutes math.
No direct reads from `caliper.*`, Supabase, Postgres, private logs, implementation source, raw Caliper payloads, or raw Ed-Fi payloads.
Attendance and discipline are read-only Events views; Ed-Fi owns writes and corrections.

Install the Events skill and get one live activity call fast.