# 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" \
  -H "$AUTH_HEADER" \
  | jq '{credentials:[.data[] | {app_id, has_credential, last_rotated_at, secret_ref_present:has("secret_ref")}]}'
```

`secret_ref_present` should be `false`. If a user asks for the credential value, stop: the surface intentionally never returns it.

## 8. Verify Against Platform-Owned Answers

```bash
node checks/verify-skill-pack.mjs
```

The verifier fetches the approved integration convergence answer from the hosted integration artifact, then reproduces the same answer through live API calls. It does not query the raw database.