---
name: timeback-ed-fi-1edtech
description: Build apps, reports, QA probes, and deliverables against the TimeBack platform3 Ed-Fi 1EdTech surface. Use for attendance, discipline, transcript, program, staff, calendar, descriptor, import/export, draft, and conformance workflows that must call the live Ed-Fi API without copying UDM schema tables, descriptor catalogs, roster reconciliation, idempotency, ETag, soft-delete, privacy, or business logic.
---

# TimeBack Ed-Fi 1EdTech

Use this skill when an AI agent is asked to build a working app, report, smoke check, migration proof, or customer deliverable against the platform3 Ed-Fi 1EdTech surface.

This skill is instructions only. It does not contain Ed-Fi data-processing code, schema parsers, copied descriptor tables, local roster reconciliation, soft-delete logic, idempotency replay logic, ETag calculation, privacy redaction, or Ed-Fi business rules. The live surface owns those behaviors.

## Install From The Hosted Pack

Install the whole folder, preserving `references/`, `agents/`, and `bin/`. If `ED_FI_SKILL_PACK_URL` is not already set, use the canonical URL:

```bash
export ED_FI_SKILL_PACK_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/skill_pack"
```

Codex install:

```bash
export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export ED_FI_SKILL_DIR="$CODEX_HOME/skills/timeback-ed-fi-1edtech"
mkdir -p "$ED_FI_SKILL_DIR/agents" "$ED_FI_SKILL_DIR/references" "$ED_FI_SKILL_DIR/bin"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/SKILL.md" -o "$ED_FI_SKILL_DIR/SKILL.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/openai.yaml" -o "$ED_FI_SKILL_DIR/agents/openai.yaml"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/codex-cli.md" -o "$ED_FI_SKILL_DIR/agents/codex-cli.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/claude-code.md" -o "$ED_FI_SKILL_DIR/agents/claude-code.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/perplexity-computer.md" -o "$ED_FI_SKILL_DIR/agents/perplexity-computer.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/bin/proof-replay.sh" -o "$ED_FI_SKILL_DIR/bin/proof-replay.sh"
chmod +x "$ED_FI_SKILL_DIR/bin/proof-replay.sh"
for file in source-contract worked-example app-build-protocol auth-and-headers leak-check; do
  curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/references/$file.md" -o "$ED_FI_SKILL_DIR/references/$file.md"
done
```

Claude Code install:

```bash
export ED_FI_SKILL_DIR="${ED_FI_SKILL_DIR:-$HOME/.claude/skills/timeback-ed-fi-1edtech}"
mkdir -p "$ED_FI_SKILL_DIR/agents" "$ED_FI_SKILL_DIR/references" "$ED_FI_SKILL_DIR/bin"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/SKILL.md" -o "$ED_FI_SKILL_DIR/SKILL.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/openai.yaml" -o "$ED_FI_SKILL_DIR/agents/openai.yaml"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/claude-code.md" -o "$ED_FI_SKILL_DIR/agents/claude-code.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/codex-cli.md" -o "$ED_FI_SKILL_DIR/agents/codex-cli.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/agents/perplexity-computer.md" -o "$ED_FI_SKILL_DIR/agents/perplexity-computer.md"
curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/bin/proof-replay.sh" -o "$ED_FI_SKILL_DIR/bin/proof-replay.sh"
chmod +x "$ED_FI_SKILL_DIR/bin/proof-replay.sh"
for file in source-contract worked-example app-build-protocol auth-and-headers leak-check; do
  curl -fsSLL "$ED_FI_SKILL_PACK_URL/pack/references/$file.md" -o "$ED_FI_SKILL_DIR/references/$file.md"
done
```

Perplexity Computer or other project-instruction hosts: read `agents/perplexity-computer.md`, pin the canonical skill-pack URL, attach the downloaded folder or zip, and paste this `SKILL.md` as the project instruction. Load reference files only when the current task needs them.

Run the proof replay after install:

```bash
"$ED_FI_SKILL_DIR/bin/proof-replay.sh"
```

## Source Of Truth

Open the hosted docs before making claims:

- Customer website: https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/customer_website
- Data dictionary: https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/data_dictionary
- Architecture: https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/architecture
- Surface QC: https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/surface_qc
- Integration proof: https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/integration
- Live API base URL: `https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/implementation/api`

The surface implements the complete Ed-Fi Data Standard v6.1 UDM as the 1EdTech-side source, plus platform gap fills GAP-A1 through GAP-A5. If public Ed-Fi docs, model memory, or older artifacts disagree with the approved platform3 docs, platform3 wins for this surface.

For endpoint, field, and behavior details, read `references/source-contract.md`. For credentials and headers, read `references/auth-and-headers.md`.

## Credential Flow

Set the base URL once:

```bash
export ED_FI_BASE_URL="${ED_FI_BASE_URL:-https://platform3-andymontgomery-9773s-projects.vercel.app/ed_fi/1edtech/implementation/api}"
```

For demo work, mint a public demo token:

```bash
export ED_FI_TOKEN="$(curl -fsS -X POST "$ED_FI_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"
```

For real-tenant or reviewer work, use an operator-supplied token such as `ED_FI_REVIEWER_JWT` or `ED_FI_TOKEN`. Never call `/dev/mint` for a non-demo tenant, never print a real token, and never persist a real token in public output.

Protected calls use:

```bash
-H "Authorization: Bearer $ED_FI_TOKEN"
```

Writes also require `Content-Type: application/json` and `Idempotency-Key`. PUT, PATCH, DELETE, and draft promotion require the current `ETag` in `If-Match`.

Attendance has one extra rule: ordinary teacher/SIS marks are append-only events. For daily or section attendance, use `POST /ed-fi/studentSchoolAttendanceEvents` or `POST /ed-fi/studentSectionAttendanceEvents`; treat `PUT`, `PATCH`, and `DELETE` detail calls as correction paths after an acknowledged row exists. The root descriptor publishes `attendanceWritePolicy` (`edfi.attendance.teacher_mark.v2026-06-22`): a successful mark returns `ack_id` plus ETag, and a 32-student daily+section classroom batch should run at no more than 8 concurrent POSTs.

## Surface Calls To Prefer

Use the customer website and endpoint catalog for the exact collection name. Common route shapes:

- `GET /` for implementation descriptor and route counts.
- `GET /ed-fi/{collection}?limit=...&offset=...` for Ed-Fi offset paging.
- `GET /ed-fi/{collection}?limit=...&cursor=...` for platform cursor paging.
- `POST /ed-fi/{collection}` to create canonical records with platform-minted `edfi_local_id`, `ack_id`, and `ETag`.
- `GET /ed-fi/{collection}/{edfi_local_id}` for detail read.
- `PUT|PATCH|DELETE /ed-fi/{collection}/{edfi_local_id}` with `If-Match` and `Idempotency-Key` for replace, update, and soft-delete.
- `GET|POST /ed-fi/descriptors/{descriptorCatalog}` for governed descriptor catalogs.
- `GET|POST /ed-fi/drafts` and `POST /ed-fi/drafts/{draft_id}/promote` for pre-canonical work state.
- `GET|POST /ed-fi/imports`, `GET|POST /ed-fi/exports`, and `GET /ed-fi/conformance/evidence` for bulk and evidence workflows.

Do not memorize descriptor route variants. Read the customer website or endpoint catalog, call the documented route, and follow returned links such as `links.canonicalEdFiRoute`. When testing the root descriptor with curl, call `$ED_FI_BASE_URL` without a trailing slash; the canonical hosted URL redirects when a slash is appended.

## Non-Negotiable Boundaries

Do not build or install any of these inside the agent, app, report, or generated deliverable:

- A local copy of the complete Ed-Fi UDM schema, descriptor catalogs, descriptor values, or field validation tables.
- A parser that infers Ed-Fi identity, descriptors, or domains from names or URLs.
- A local roster table, fallback roster identity, or platform3 sourcedId reconciliation layer.
- Client-side idempotency replay state, ETag calculation, soft-delete history, hard-delete workaround, or privacy-redaction logic.
- A local database for Ed-Fi domain data. Browser storage may hold UI preferences and temporary response handles only.
- Reads from implementation source, Supabase tables, or private loop artifacts to complete a customer-facing workflow.
- Alpha plain-language renaming or cut-to-demand behavior. This is the 1EdTech surface.

If the task appears to need one of those behaviors, stop and report a surface leak. Route the finding to the earliest upstream deliverable:

- Architecture if the needed primitive was never committed.
- Data dictionary if a field meaning, nullability, range, enum, route, or provenance is missing.
- Customer website if a cold integrator cannot follow the public docs.
- Implementation if the live API contradicts the approved docs.

## Standard Agent Workflow

1. Read the customer website quickstart and the data dictionary entry for each resource you will touch.
2. Set `ED_FI_BASE_URL` and acquire either a demo token or operator-provided token.
3. Call `GET /` to confirm the live surface descriptor and route counts.
4. For lists, choose one paging mode. Use offset+limit or cursor, never both.
5. For descriptor-dependent writes, read the governed descriptor catalog first.
6. For roster-touched writes, use platform3 OneRoster sourcedId overlay fields where the docs require them.
7. For writes, send one idempotency key per logical operation.
8. For attendance teacher marks, POST append-only rows at the published `attendanceWritePolicy.maxClientConcurrency` cap and report `ack_id` + ETag as the confirmation.
9. For updates and deletes, fetch detail first and send the returned `ETag` as `If-Match`.
10. Build the requested app, report, or probe from fields returned by the surface.
11. Cite the customer website and data dictionary next to claims about endpoints, fields, descriptors, errors, roster anchors, draft state, imports, exports, and conformance evidence.
12. Run the binary check in `references/leak-check.md` before delivering output.

## Worked Example

Read `references/worked-example.md` for end-to-end demos that regenerate an attendance workflow proof and a grades proof by calling only:

- `POST /dev/mint?tenantId=demo`
- `GET /`
- `GET /ed-fi/descriptors/attendanceEventCategoryDescriptors?codeValue=In%20Attendance&namespace=uri%3A%2F%2Fed-fi.org%2FAttendanceEventCategoryDescriptor`
- `POST /ed-fi/studentSchoolAttendanceEvents`
- `GET /ed-fi/studentSchoolAttendanceEvents/{edfi_local_id}`
- `PATCH /ed-fi/studentSchoolAttendanceEvents/{edfi_local_id}`
- `DELETE /ed-fi/studentSchoolAttendanceEvents/{edfi_local_id}`
- `GET /ed-fi/studentSchoolAttendanceEvents/{edfi_local_id}?includeDeleted=true`
- `POST /ed-fi/imports`
- `POST /ed-fi/exports`
- `GET /ed-fi/conformance/evidence?evidence_id={evidence_id}&limit=1&offset=0`
- `GET /ed-fi/descriptors/gradeTypeDescriptors?codeValue=Final&namespace=uri%3A%2F%2Fed-fi.org%2FGradeTypeDescriptor`
- `POST /ed-fi/grades`
- `GET /ed-fi/grades/{edfi_local_id}`
- `DELETE /ed-fi/grades/{edfi_local_id}`
- `GET /ed-fi/grades/{edfi_local_id}?includeDeleted=true`

Use `references/app-build-protocol.md` when building a full app or report. Use `references/auth-and-headers.md` when debugging credentials, Problem responses, ETags, idempotency, or list counts.

Use `bin/proof-replay.sh` as the runnable check. It reproduces the surface's own pinned answers for root counts, attendance, grades, soft-delete retention, import/export terminal job evidence, and conformance evidence by calling the live API only.

## Expected Output Quality

A deliverable built with this skill should show:

- Which canonical platform3 docs it used.
- Which live endpoints it called.
- Which tenant mode it used: demo or operator token.
- Which rows, headers, counts, and Problem codes came from the API.
- Which behavior was deliberately not implemented locally because the Ed-Fi surface owns it.