Build roster workflows by asking the surface, not rebuilding it.

# Claude Code
mkdir -p ~/.claude/skills/timeback-people-and-orgs-alpha
cp -R pack/* ~/.claude/skills/timeback-people-and-orgs-alpha/

# Codex
mkdir -p ~/.codex/skills/timeback-people-and-orgs-alpha
cp -R pack/* ~/.codex/skills/timeback-people-and-orgs-alpha/

# Perplexity Computer or another file-backed agent
mkdir -p ./skills/timeback-people-and-orgs-alpha
cp -R pack/* ./skills/timeback-people-and-orgs-alpha/

# Claude Code
curl -fsSLL https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/skill_pack/install.sh | bash -s -- claude

# Codex
curl -fsSLL https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/skill_pack/install.sh | bash -s -- codex

# Perplexity Computer or another file-backed agent
curl -fsSLL https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/skill_pack/install.sh | bash -s -- perplexity ./skills/timeback-people-and-orgs-alpha

# Worked Example: North Valley Roster Desk

This example regenerates the People & Orgs Alpha launch-gate roster answers by calling the live surface only.

It answers:

1. Who is on the North Valley student roster as of 2026-09-15?
2. Which guide/classes do the students belong to?
3. Which NWEA account boundary owns the school?
4. Is the North Valley school calendar readable for day, range, and remaining-days questions?
5. Does Ada have an app credential reference without leaking `secret_ref`?

## 1. Mint A Demo Token

```bash
export PEOPLE_AND_ORGS_BASE_URL="${PEOPLE_AND_ORGS_BASE_URL:-https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/implementation/api}"
export PEOPLE_AND_ORGS_TOKEN="$(curl -fsS -X POST "$PEOPLE_AND_ORGS_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')"
export AUTH_HEADER="Authorization: Bearer $PEOPLE_AND_ORGS_TOKEN"
```

## 2. Read The Descriptor

```bash
curl -fsS "$PEOPLE_AND_ORGS_BASE_URL" -H "$AUTH_HEADER" | jq '{module, surface, belongsHereIf, endpoints}'
```

Keep the descriptor's docs links beside the work. They are the source of truth for the module boundary.

## 3. Read The Student Roster

```bash
curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_north_valley_school/people?asOfDate=2026-09-15&roleKind=student" \
  -H "$AUTH_HEADER" \
  | jq '{count, students:[.data[] | {person_id, first_name, last_name, email, age_grade, membership:.membership.membership_id}]}'
```

The demo surface returns the four active North Valley student rows for Ada Lovelace, Luis Rivera, Maya Chen, and Nora Patel. Each API row includes the dated place membership. If the count differs, run the verifier; do not locally dedupe or hide rows.

## 4. Read Guide And Class Membership Evidence

```bash
curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_north_valley_school/people?asOfDate=2026-09-15&roleKind=guide" \
  -H "$AUTH_HEADER" \
  | jq '{count, guides:[.data[] | {person_id, first_name, last_name, membership:.membership.membership_id}]}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/school_periods/period_fall_2026/active_memberships?asOfDate=2026-09-15" \
  -H "$AUTH_HEADER" \
  | jq --arg school "place_north_valley_school" '{place_membership_ids:[.place_memberships[] | select(.place_id == $school) | .membership_id], class_membership_ids:[.class_memberships[] | select(.school_id == $school) | .membership_id]}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/guides/person_katherine_johnson/students?asOfDate=2026-09-15" \
  -H "$AUTH_HEADER" \
  | jq '.data[] | select(.student_person_id == "person_ada_lovelace") | {guide_person_id, student_person_id, learning_group_id, school_id, begin_date, end_date}'
```

Use the returned `role_kind`, `learning_group_id`, `school_id`, and `is_primary_guide`; do not infer guide status from a class title. The period endpoint returns period-wide active rows. For roster cards, use `/places/{schoolId}/people` as the roster source and attach class or guide evidence to those returned `person_id` values instead of treating the full period response as the roster. For inverse guide-to-students questions, use `/guides/{guidePersonId}/students`.

## 5. Read The NWEA District Boundary

```bash
curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_timeback_physical_district/schools" \
  -H "$AUTH_HEADER" \
  | jq '{district_id:.district.place_id, nwea_district_id:.district.nwea_district_id, brand:.district.brand, modality:.district.modality, school_ids:[.schools[].place_id]}'
```

The district row is the Brand x Modality NWEA account. The school does not carry a second source of truth for `nwea_district_id`.

## 6. Read School Calendar Facts

```bash
curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_north_valley_school/school_calendar/2025-08-13" \
  -H "$AUTH_HEADER" \
  | jq '{calendar_date, is_school_day, reason}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_north_valley_school/school_calendar/2025-11-24" \
  -H "$AUTH_HEADER" \
  | jq '{calendar_date, is_school_day, reason}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_north_valley_school/school_calendar?startDate=2025-08-13&endDate=2026-07-24" \
  -H "$AUTH_HEADER" \
  | jq '{calendar_days:.count, school_days_between:.school_days_in_range, reason_values:([.data[].reason] | unique | sort)}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/place_north_valley_school/school_days_remaining?asOfDate=2026-06-12" \
  -H "$AUTH_HEADER" \
  | jq '{school_days_remaining}'
```

Calendar facts come from the People & Orgs surface. Do not count weekdays, infer holidays, or maintain a copied reason list.

## 7. Read App Credential Status

```bash
curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/app_credentials?filter=studentSourcedId==person_ada_lovelace" \

POST /dev/mint?tenantId=demo
GET  /
GET  /people
GET  /people/{personId}
GET  /people/{personId}/memberships
GET  /places
GET  /places/{placeId}
GET  /places/{placeId}/people
GET  /places/{placeId}/schools
GET  /guides/{guidePersonId}/students?asOfDate=YYYY-MM-DD
GET  /places/{placeId}/school_calendar/{date}
GET  /places/{placeId}/school_calendar?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
GET  /places/{placeId}/school_days_between?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
GET  /places/{placeId}/school_days_remaining?asOfDate=YYYY-MM-DD
GET  /places/{placeId}/next_school_year_start?asOfDate=YYYY-MM-DD
GET  /place_memberships
GET  /class_memberships
GET  /school_periods
GET  /school_periods/{periodId}/active_memberships
GET  /person_sensitive_profiles
GET  /person_sensitive_profiles/{personId}
GET  /app_credentials
GET  /app_credentials/{studentSourcedId}/{appId}
GET  /tag_definitions
GET  /object_tags
GET  /policy_config

POST/PATCH/DELETE are available for per-resource writes with Idempotency-Key and If-Match.

node checks/verify-skill-pack.mjs
node checks/verify-skill-pack.mjs --write-evidence

# Binary Leak Check

Run this check before shipping any People & Orgs app, report, QA probe, migration check, or customer deliverable.

## Pass Conditions

The deliverable passes only if all statements are true:

- It calls the live People & Orgs Alpha API.
- It opens or cites the canonical customer website and data dictionary.
- Every roster answer has an explicit `asOfDate`.
- It uses returned `role_kind`, `place_id`, `school_id`, `learning_group_id`, `membership_id`, `brand`, `modality`, `nwea_district_id`, and `is_time_locatable` fields.
- It reads `policy_config` for policy numbers instead of hardcoding them.
- It treats `app_credential` as existence and rotation status only.
- It preserves Problem JSON when calls fail.
- It stores no People & Orgs domain rows outside the surface.

## Automatic Fail Conditions

Stop and report a surface gap if the deliverable contains any of these:

- local role inference from names, emails, titles, URLs, or class labels;
- school-period title parsing;
- tenure bucket math or school-year boundary constants in client code;
- NWEA account grouping reconstructed from school-level data;
- credential secret storage, display, or `secret_ref` exposure;
- client-side soft-delete dedupe, hygiene filtering, or real-student filtering;
- client-side point-in-time null rules for memberships;
- direct reads of `oneroster.*`, `alpha.*`, Supabase, Postgres, implementation source, or private logs;
- copied enum/value tables instead of reading descriptor, dictionary, or `tag_definitions`;
- Results, Events, Content, Curriculum, gradebook, mastery, MAP scoring, or content-effectiveness logic;
- local persistence of roster-shaped data.

## Pack Shape Check

The installed pack may contain Markdown instructions, OpenAI agent metadata, recorded evidence, and the verifier script. It must not contain:

- CSV, TSV, XLSX, XML, SQL, SQLite, or database files;
- schema/OpenAPI parser code;
- package dependencies or `node_modules`;
- scripts that transform roster data for app use.

`checks/verify-skill-pack.mjs` is allowed because it performs live-response assertions against platform-pinned answers and pack-shape checks only. It is not a reusable data-processing library.

---
name: timeback-people-and-orgs-alpha
description: Use when building apps, reports, QA probes, migration checks, or deliverables against the TimeBack platform3 People & Orgs Alpha surface. The skill teaches agents to read roster people, places, dated place/class memberships, school periods, first-class guide rosters, school calendar day/range counts, NWEA district boundaries, sensitive profiles, app credential status, governed tags, and policy config by calling the live surface only. Do not infer roles from names, parse school periods, compute tenure buckets or calendar rules, reconstruct NWEA account grain, expose secrets, dedupe soft deletes, read OneRoster/raw databases, or implement Results/Events/Content/Curriculum logic.
---

# TimeBack People & Orgs Alpha

Use this skill when the user asks for a working app, report, migration reconciliation, QA probe, or customer deliverable that uses the TimeBack platform3 People & Orgs Alpha surface.

Do not use it for generic SIS/OneRoster work, direct database access, Results, Events, Content, Curriculum, mastery, MAP scoring, report cards, gradebook rollups, or credential-secret retrieval.

## Install

Install the whole `pack/` directory as one skill. Do not split the reference files away from `SKILL.md`.

Hosted one-command installs:

Claude Code:

```bash
curl -fsSLL https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/skill_pack/install.sh | bash -s -- claude
```

Codex:

```bash
curl -fsSLL https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/skill_pack/install.sh | bash -s -- codex
```

Perplexity Computer or another file-backed agent:

```bash
curl -fsSLL https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/skill_pack/install.sh | bash -s -- perplexity ./skills/timeback-people-and-orgs-alpha
```

Local workspace install, when you already have this `OUT_DIR` checked out:

Claude Code:

```bash
mkdir -p ~/.claude/skills/timeback-people-and-orgs-alpha
cp -R pack/* ~/.claude/skills/timeback-people-and-orgs-alpha/
```

Codex:

```bash
mkdir -p ~/.codex/skills/timeback-people-and-orgs-alpha
cp -R pack/* ~/.codex/skills/timeback-people-and-orgs-alpha/
```

Perplexity Computer or another file-backed agent:

```bash
mkdir -p ./skills/timeback-people-and-orgs-alpha
cp -R pack/* ./skills/timeback-people-and-orgs-alpha/
```

The hosted installer fetches `SKILL.md`, all agent adapters, all references, the verifier, and the latest evidence. Set a custom install directory with the optional second argument, for example `bash -s -- codex /tmp/timeback-people-and-orgs-alpha`.

## People & Orgs In 60 Seconds

People & Orgs is the roster in school language. It answers who someone is and where they belong, as of a date.

Core objects:

- `person`: one human in the roster. A person's roles are memberships, not hidden inside the person row.
- `place`: a district, school, level, or other roster place. A district is the NWEA account boundary when it carries `nwea_district_id`.
- `place_membership`: dated link between a person and a place, with `role_kind`, `begin_date`, `end_date`, and `is_time_locatable`.
- `class_membership`: dated link between a person, a school, and a learning group.
- `school_period`: typed school-year or term. Use the typed fields; never parse the title.
- `school_calendar`: Ed-Fi CalendarDate-backed school-day facts exposed through People & Orgs reads.
- `person_sensitive_profile`: lawful sensitive profile fields behind the documented sensitive scope.
- `app_credential`: credential existence and rotation status only. The API never returns `secret_ref`.
- `tag_definition` and `object_tag`: governed reporting tags. Relationships are fields, not tags.
- `policy_config`: named `alpha.policy.*` config such as tenure buckets and school-year boundaries.

Alpha is views over OneRoster for renamed/cut/restricted roster objects. Only pure Alpha extensions add tables. The skill pack never reads those tables directly; it calls the public API.

## First Actions

1. Open the canonical docs before making claims:
   - Customer website: https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/customer_website
   - Data dictionary: https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/data_dictionary
   - Architecture decisions: https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/architecture
2. Use `PEOPLE_AND_ORGS_BASE_URL` if credentials supply it. Otherwise use:
   `https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/implementation/api`
3. Choose the credential path:
   - Demo: call `POST $PEOPLE_AND_ORGS_BASE_URL/dev/mint?tenantId=demo`, then use the returned bearer token.
   - Real or reviewer tenant: use the operator-supplied bearer token such as `PEOPLE_AND_ORGS_REVIEWER_JWT`. Never print or commit tokens.
4. Read `GET /` and keep its docs links and endpoint list next to you.
5. For roster, calendar, guide inverse, NWEA boundary, app credential, period membership, sensitive-profile, or migration checks, read `references/roster-recipes.md`.
6. To prove the pack is asking the platform correctly, run `node checks/verify-skill-pack.mjs`.
7. Before final output, read `references/leak-check.md` and confirm the binary leak check passes.

## Happy Path: North Valley Roster

```bash
export PEOPLE_AND_ORGS_BASE_URL="${PEOPLE_AND_ORGS_BASE_URL:-https://platform3-andymontgomery-9773s-projects.vercel.app/people_and_orgs/alpha/implementation/api}"
export PEOPLE_AND_ORGS_TOKEN="${PEOPLE_AND_ORGS_TOKEN:-$(curl -fsS -X POST "$PEOPLE_AND_ORGS_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')}"
export AS_OF_DATE="${AS_OF_DATE:-2026-09-15}"
export SCHOOL_ID="${SCHOOL_ID:-place_north_valley_school}"

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/places/$SCHOOL_ID/people?asOfDate=$AS_OF_DATE&roleKind=student" \
  -H "Authorization: Bearer $PEOPLE_AND_ORGS_TOKEN" \
  | jq '{count, students:[.data[] | {person_id, first_name, last_name, age_grade, membership_id:.membership.membership_id}]}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/school_periods/period_fall_2026/active_memberships?asOfDate=$AS_OF_DATE" \
  -H "Authorization: Bearer $PEOPLE_AND_ORGS_TOKEN" \
  | jq --arg school "$SCHOOL_ID" '{place_memberships:[.place_memberships[] | select(.place_id == $school) | .membership_id], class_memberships:[.class_memberships[] | select(.school_id == $school) | .membership_id]}'

curl -fsS "$PEOPLE_AND_ORGS_BASE_URL/guides/person_katherine_johnson/students?asOfDate=$AS_OF_DATE" \
  -H "Authorization: Bearer $PEOPLE_AND_ORGS_TOKEN" \
  | jq '.data[] | select(.student_person_id == "person_ada_lovelace") | {guide_person_id, student_person_id, learning_group_id, school_id, begin_date, end_date}'
```

Use the school-specific `/places/{schoolId}/people` response as the roster source. The period membership endpoint is period-wide; when a roster card needs class or guide evidence, attach returned membership rows to the `person_id` values already returned by the roster call. Use the returned `person_id`, `membership_id`, `learning_group_id`, `role_kind`, `brand`, `modality`, `nwea_district_id`, and `is_time_locatable` fields directly. Do not infer them from names or titles, and do not add a local dedupe layer to hide unexpected surface rows.

## Happy Path: North Valley School Calendar