All runbooks
runbookproductredacted view

Pipfitter — builder start-here runbook

Onboarding runbook for agents and operators building Pipfitter: bootstrap Explorer, open local workspace, validate data, build iOS on Mac.

Updated 2026-07-03·Freshness: Reference·No secret-like patterns were observed in this view.

Pipfitter — builder start-here runbook

Onboarding runbook for agents and operators building Pipfitter: bootstrap Explorer, open local workspace, validate data, build iOS on Mac.

Body

Pipfitter — builder start-here runbook

Created: 2026-07-03

Purpose

Orient AI agents and operators before touching Pipfitter code. UAI Explorer is the documentation source of truth; local files are drafts and build artifacts until cataloged here.

Prerequisites

  • Mac with Xcode 16+ and physical iPhone (level QA requires device)
  • Linux/VPS workspace at /root/pipfitter (data + Swift sources)
  • Explorer AI lane token in env (never commit or paste into docs)

Bootstrap sequence

  1. GET /ready on https://explorer.united-ai.ca — expect status: ready, catalog_count present
  2. GET /api/ai/bootstrap — note audit_event_id, read stop_conditions
  3. Fetch context for: - ecosystem product entry (Pipfitter) - this start-here runbook - latest workspace bootstrap evidence receipt

Local workspace

cd /root/pipfitter
python3 scripts/validate_handbook_data.py   # must print PASS

Layout:

Path Purpose
ios/Pipfitter/ SwiftUI sources
ios/PipfitterTests/ Unit tests (offset + take-off math)
data/*.json Handbook bundles (Tier 0–2)
docs/planning/ Planning mirrors
diary/ Session receipts

Mac build steps

  1. Create Pipfitter.xcodeproj (File → New → App) or open existing project
  2. Add all files under ios/Pipfitter/** and ios/PipfitterTests/**
  3. Target iOS 17+, Swift 6, SwiftUI
  4. Embed data/*.json in app bundle as resources
  5. Run PipfitterTests on Mac; run Level tab QA on physical device

App tabs (v1)

Tab MVP deliverable
Level CoreMotion pitch/roll, REF calibrate, delta HUD, flat calibrate
Handbook FTS search over bundled JSON (threaded / SW / BW)
Calc Run Builder: CTC → cut + allowance band
Settings Units, audio lock, theme

Conventions

  • Fraction-first UI (22-1/2 not 22.5)
  • CTC measurement language (center-to-center)
  • Every handbook row: provenance + confidence fields in JSON
  • Offline-only v1 — no network calls

Data validation

python3 scripts/validate_handbook_data.py

Checks include Audel 45° offset cut sanity (~21.5 in) and JSON schema presence.

Publishing discipline

After each meaningful session:

  1. Write diary/YYYY-MM-DD-<topic>.md locally
  2. Promote summary via POST /api/ai/documents as evidence doc
  3. Verify with GET /api/ai/context/{slug} (read-your-writes)

Use project: product and only session-granted tags (product, docs, evidence, runbook, plan, start-here).

No-change boundaries

  • Do not mutate CT121 production Explorer for Pipfitter experiments
  • Do not host IPT verbatim or ASME PDFs
  • Do not add backend/API for handbook v1
  • Do not store API keys in repo, diary, or catalog bodies

Rollback

  • iOS: revert Xcode project / git commit on Mac
  • Data: restore prior data/*.json from git
  • Explorer: PATCH doc with status: superseded + superseded_by pointing to replacement slug

Done checks

  • [ ] validate_handbook_data.py PASS
  • [ ] Swift unit tests PASS on Mac
  • [ ] Level REF workflow QA on device
  • [ ] Explorer evidence doc published for session