🕳️ The P.I.T. Protocol / spec

PIT-MANIFEST/0.1

One file = one pit. Export any P.I.T. as a single portable manifest — then talk to it.

status: living draft · v0.1 · 2026-07-28 license: CC0 — no rights reserved

1 · What a manifest is

A PIT-MANIFEST is a single YAML/JSON document that fully describes one P.I.T. instance: its identity and lineage, its consent posture, its source, its counts, and a complete session table — every session's title, date, speakers, duration, and pointers (never bulk payloads) to its Drive original, hosted audio, and plain-text transcript.

Pointers, not payloads: the manifest stays small (a 40-session pit ≈ 60 KB) while everything it references stays fetchable. An AI agent reads the manifest, picks sessions, and fetches transcripts on demand.

2 · Minimal example

spec: pit-manifest/0.1
pit:
  name: The ZuitzPIT
  slug: zuitzpit
  registry_number: 3
  url: https://shakaleikaumaka.github.io/zuitzpit/
  repository: https://github.com/shakaleikaumaka/zuitzpit
  forked_from: https://github.com/shakaleikaumaka/esmeralda-pit
  generation: 1
  event: Zuitzerland residency
  location: Swiss Alps
  dates: May 2025
license: CC0-1.0 · no rights reserved · fork it
consent:
  policy: consent-first
  status: demo · links to source Drive
  contact: consent@publicinform.com
  policy_url: https://publicinform.com/whitepaper/#consent
counts: { sessions: 40, transcripts: 38, hours: 42.3 }
sessions:
  - id: 1_XBfWl2J2hFI4SNswWCFeRfYIwHfSrm3
    title: From Vibes to Viability: Fixing Inequality…
    duration: "01:02:01"
    duration_seconds: 3721
    media:
      drive: https://drive.google.com/file/d/1_XBf…/view
      audio: https://pub-….r2.dev/audio/1_XBf….mp3
    transcript: https://shakaleikaumaka.github.io/zuitzpit/transcripts/1_XBf….txt
    transcript_format: pit-transcript/1 · plain text, [MM:SS] timestamps
hub: https://publicinform.com
registry: https://publicinform.com/pits.json

3 · Field reference

4 · Transcript format (pit-transcript/1)

Manifests point to transcripts, so the transcript shape is pinned here too. A pit-transcript/1 file is UTF-8 plain text: a header block (# Title, provenance lines, ---), then paragraphs opening with [MM:SS] or [HH:MM:SS] timestamps — the same timestamps the Knowledge Transponder glows on. Non-speech spans collapse to one honest marker paragraph (e.g. [non-speech — bio break, music & ambience]). No invented words, ever — unintelligible spans are marked [unclear].

5 · Talking to a pit (agent recipe)

1. Fetch {pit.url}/pit.json (or pit.yaml).
2. Read consent first. Honor it. This knowledge is transmitted, not taken.
3. Choose sessions from the table — by title, speaker, or the summary fields as pits adopt the digest layer.
4. Fetch transcript URLs as needed (plain text, cheap). Quote with [MM:SS] timestamps so humans can tap-to-seek in the pit's transponder.
5. Want the whole constellation? Start at the hub: publicinform.com/pits.json lists every living pit and its manifest.

6 · Rules of the road

• Both syntaxes, same content. pit.json and pit.yaml are generated from one source and MUST agree. JSON is the canonical serialization; YAML is the human door.
• Pointers, not payloads. Manifests reference transcripts/audio; they never embed them.
• Consent travels. Mirrors and importers MUST preserve the consent block and note fields. Revocations flow back through the pit's own governance (and, soon, ZK consent receipts — see the white paper).
• Regenerate, don't hand-edit. Manifests are derived data, produced from each pit's data/catalog.json by pit_export.py (CC0, in the protocol repo under ops/). Same-file conflicts resolve by regenerating — never hand-merge.
• Version honestly. Breaking changes bump the version string; parsers key on it.

7 · Living manifests

The first generated manifests, verifying the spec against real pits:

• 🏔️ The ZuitzPIT — pit.yaml (40 sessions · 38 transcripts · 42.3 h)
• 🕸️ pits.json — the constellation registry (all living pits)

More pits light up as the generator rolls across the forks — watch the registry.