Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
145 commits
Select commit Hold shift + click to select a range
9c380a2
Just making new folders for seperate work.
thedamian Sep 12, 2026
e69d274
The "parts"
thedamian Sep 12, 2026
12545eb
Readme
thedamian Sep 12, 2026
53a63ed
Partial Robot Part
thedamian Sep 12, 2026
df476a8
Merge branch 'main' of github.com:thedamian/agents-everywhere-starter…
thedamian Sep 12, 2026
e24f7c1
it's working.
thedamian Sep 12, 2026
6b3fd3b
movie
edilma Sep 12, 2026
f98f217
mergingMerge branch 'main' of https://github.com/thedamian/agents-eve…
edilma Sep 12, 2026
6042d04
Add MagicPitch orchestration API and teammate interface handoff
dngoins Sep 12, 2026
b4e225b
Merge origin/main into MagicPitch orchestration branch
dngoins Sep 12, 2026
7e79dc1
Merge pull request #1 from thedamian/jmfqynl-jmf-local-development-setup
dngoins Sep 12, 2026
d0bdbab
Created the assets
edilma Sep 12, 2026
00cc72b
Merge branch 'main' of https://github.com/thedamian/agents-everywhere…
edilma Sep 12, 2026
e0bdb08
mergd
thedamian Sep 12, 2026
544931b
Merge branch 'main' of github.com:thedamian/agents-everywhere-starter…
thedamian Sep 12, 2026
04c670a
Add Tiya movie studio, kiosk and media-service integration
dngoins Sep 12, 2026
2555225
merged
thedamian Sep 12, 2026
08fc867
Integrate Tiya kiosk and media service with MagicPitch
dngoins Sep 12, 2026
fde6f84
Fixing race condition.
thedamian Sep 12, 2026
adf5d31
Merge origin/main into Tiya movie integration
dngoins Sep 12, 2026
2b0db1e
Merge pull request #2 from thedamian/jmfqynl-jmf-tiya-movie-magic
dngoins Sep 12, 2026
5ca9dce
Upload the created video
edilma Sep 12, 2026
39d63b2
Magic Pitch Robot - movie part
dngoins Sep 12, 2026
075a202
Merge branch 'main' of https://github.com/thedamian/agents-everywhere…
edilma Sep 12, 2026
9afe01e
Merge pull request #3 from thedamian/jmfqynl-jmf-tiya-movie-magic
dngoins Sep 12, 2026
eb912e0
Merge branch 'main' of https://github.com/thedamian/agents-everywhere…
edilma Sep 12, 2026
7ec4a44
Merge latest team updates into kiosk integration
dngoins Sep 12, 2026
65bfce0
Updated Readme
dngoins Sep 12, 2026
e4186dd
Merge pull request #4 from thedamian/jmfqynl-jmf-tiya-movie-magic
dngoins Sep 12, 2026
5dfeb06
updated orchstrator
dngoins Sep 12, 2026
b75b01b
Merge pull request #5 from thedamian/jmfqynl-jmf-local-development-setup
dngoins Sep 12, 2026
2afcaab
fixed the storyboard creation
dngoins Sep 13, 2026
d4fe1f9
Merge pull request #6 from thedamian/jmfqynl-jmf-tiya-movie-magic
dngoins Sep 13, 2026
2f3d3cf
Magic Pitch Robot - movie part
dngoins Sep 13, 2026
f7f1618
fixing movie rendering w/o audio
dngoins Sep 13, 2026
8709ce8
remove zip
dngoins Sep 13, 2026
9b9ccf6
Merge pull request #7 from thedamian/jmfqynl-jmf-tiya-movie-magic
dngoins Sep 13, 2026
7372093
Magic Pitch Robot - movie part - using Veo instead
dngoins Sep 13, 2026
df5ca76
updated docs
dngoins Sep 13, 2026
a69c976
doc update start on API update
dngoins Sep 13, 2026
081acb1
Magic Pitch Robot - movie part - using Veo instead
dngoins Sep 13, 2026
3b2a7b5
Merge pull request #8 from thedamian/jmfqynl-jmf-tiya-movie-magic
dngoins Sep 13, 2026
cb53c7f
Add speaking robot face to the showroom kiosk
dngoins Sep 13, 2026
b6923b6
Add speaking robot face to the showroom kiosk
dngoins Sep 13, 2026
3c057c1
Define shared showroom, studio and bridge contracts
dngoins Sep 13, 2026
fec85f8
Define shared showroom, studio and bridge contracts
dngoins Sep 13, 2026
ee565db
Define shared showroom, studio and bridge contracts
dngoins Sep 13, 2026
4c59c04
Define shared showroom, studio and bridge contracts
dngoins Sep 13, 2026
6073cde
Add isolated Google Calendar scheduling and OAuth core
dngoins Sep 13, 2026
cd42dfd
Extract reusable Live voice, PadBot and vision runtime
dngoins Sep 13, 2026
90867ee
Extract reusable Live voice, PadBot and vision runtime
dngoins Sep 13, 2026
53fdba1
Add isolated Google Calendar scheduling and OAuth core
dngoins Sep 13, 2026
21ee8d2
Extract reusable Live voice, PadBot and vision runtime
dngoins Sep 13, 2026
31e3300
Export portable showroom interfaces and finalize scoped workflow cont…
dngoins Sep 13, 2026
553f8e5
Wire MoviePart to shared voice and local vision assets
dngoins Sep 13, 2026
949fc14
Export portable showroom interfaces and finalize scoped workflow cont…
dngoins Sep 13, 2026
2e4f949
Add owned studio cancellation and upload reconciliation
dngoins Sep 13, 2026
6f32ee8
Export portable showroom interfaces and finalize scoped workflow cont…
dngoins Sep 13, 2026
cfec12e
Wire MoviePart to shared voice and local vision assets
dngoins Sep 13, 2026
a90257f
Add backend photo validation and bridge dependencies
dngoins Sep 13, 2026
351f2f7
Export portable showroom interfaces and finalize scoped workflow cont…
dngoins Sep 13, 2026
d49dbed
Add bounded showroom gateway and opt-in kiosk launcher
dngoins Sep 13, 2026
f9f2846
Add bounded showroom gateway and opt-in kiosk launcher
dngoins Sep 13, 2026
242254e
Preserve canonical voice SDP limits through showroom gateway
dngoins Sep 13, 2026
e24aecb
Lock MoviePart shared runtime and vision dependencies
dngoins Sep 13, 2026
2c40c07
Lock MoviePart shared runtime and vision dependencies
dngoins Sep 13, 2026
fc0d2c8
Preserve canonical voice SDP limits through showroom gateway
dngoins Sep 13, 2026
5cadbe4
Resolve shared showroom TypeScript modules in Next
dngoins Sep 13, 2026
3253605
Align showroom readiness and generation-scoped voice teardown
dngoins Sep 13, 2026
8ffea4d
Resolve shared showroom TypeScript modules in Next
dngoins Sep 13, 2026
b7630b9
Add authenticated bridge broker and fail-closed local motion safety
dngoins Sep 13, 2026
fe50332
Align showroom readiness and generation-scoped voice teardown
dngoins Sep 13, 2026
c62a0c2
Resolve shared showroom TypeScript modules in Next
dngoins Sep 13, 2026
7ea9024
Add authenticated bridge broker and fail-closed local motion safety
dngoins Sep 13, 2026
c1553c5
google calendar integration
dngoins Sep 13, 2026
fe8b685
Exercise built showroom gateway over isolated HTTP
dngoins Sep 13, 2026
ad651b0
Define shared showroom, studio and bridge contracts
dngoins Sep 13, 2026
a8a4fe2
Export portable showroom interfaces and finalize scoped workflow cont…
dngoins Sep 13, 2026
75f4d88
Add isolated Google Calendar scheduling and OAuth core
dngoins Sep 13, 2026
199bb22
Extract reusable Live voice, PadBot and vision runtime
dngoins Sep 13, 2026
584b7ef
Add owned studio cancellation and upload reconciliation
dngoins Sep 13, 2026
66ae3b7
Add backend photo validation and bridge dependencies
dngoins Sep 13, 2026
84400e7
Wire MoviePart to shared voice and local vision assets
dngoins Sep 13, 2026
6e6c2fa
Lock MoviePart shared runtime and vision dependencies
dngoins Sep 13, 2026
834a8d5
Add authenticated bridge broker and fail-closed local motion safety
dngoins Sep 13, 2026
d6e4044
Implement immersive iPad showroom face and consented guided capture
dngoins Sep 13, 2026
3af664c
Integrate authoritative showroom workflow, studio adapter and live voice
dngoins Sep 13, 2026
bf03659
Integrate authoritative showroom workflow, studio adapter and live voice
dngoins Sep 13, 2026
b941d4d
Merge pull request #9 from thedamian/jmfqynl-jmf-google-calendar-invi…
dngoins Sep 13, 2026
43852f3
Add backend photo validation and bridge dependencies
dngoins Sep 13, 2026
5c8be1e
Add authenticated bridge broker and fail-closed local motion safety
dngoins Sep 13, 2026
acc208b
Integrate authoritative showroom workflow, studio adapter and live voice
dngoins Sep 13, 2026
cb321bf
Implement immersive iPad showroom face and consented guided capture
dngoins Sep 13, 2026
f90aa0f
Showroom foundation
dngoins Sep 13, 2026
aaacfde
Add isolated Google Calendar scheduling and OAuth core
dngoins Sep 13, 2026
b6989ad
Keep bridge acknowledgements session-scoped and fail on delivery loss
dngoins Sep 13, 2026
099d37a
Add local Windows operator bridge with explicit role pairing and Stop
dngoins Sep 13, 2026
091c0e6
Merge branch 'main' into jmfqynl-jmf-showroom-foundation
dngoins Sep 13, 2026
b7687b5
Merge pull request #10 from thedamian/jmfqynl-jmf-showroom-foundation
dngoins Sep 13, 2026
3ccb5da
Keep bridge acknowledgements session-scoped and fail on delivery loss
dngoins Sep 13, 2026
4c36a31
Preserve native browser loading for the standalone PadBot adapter
dngoins Sep 13, 2026
4f384c3
Dispatch showroom Stop and consent withdrawal outside workflow queues
dngoins Sep 13, 2026
9817947
Movie Orchestration
dngoins Sep 13, 2026
80fb4a8
Keep bridge acknowledgements session-scoped and fail on delivery loss
dngoins Sep 13, 2026
0fb8dcc
Add local Windows operator bridge with explicit role pairing and Stop
dngoins Sep 13, 2026
4b9455e
Dispatch showroom Stop and consent withdrawal outside workflow queues
dngoins Sep 13, 2026
81a2f8a
Preserve native browser loading for the standalone PadBot adapter
dngoins Sep 13, 2026
c90906a
Dispatch showroom Stop and consent withdrawal outside workflow queues
dngoins Sep 13, 2026
3d8a59f
robot voice and bridge
dngoins Sep 13, 2026
2e0f046
Preserve showroom action receipts across lost responses
dngoins Sep 13, 2026
49278ec
Merge branch 'main' into jmfqynl-jmf-robot-voice-and-bridge
dngoins Sep 13, 2026
21dedc1
Merge pull request #11 from thedamian/jmfqynl-jmf-robot-voice-and-bridge
dngoins Sep 13, 2026
73dd1e2
Preserve showroom action receipts across lost responses
dngoins Sep 13, 2026
ce5a18a
Merge branch 'main' into jmfqynl-jmf-movie-orchestration
dngoins Sep 13, 2026
c3572f9
Merge pull request #12 from thedamian/jmfqynl-jmf-movie-orchestration
dngoins Sep 13, 2026
afddfc4
Verify studio reconciliation and retain exact calendar confirmation r…
dngoins Sep 13, 2026
ffe1e25
Verify studio reconciliation and retain exact calendar confirmation r…
dngoins Sep 13, 2026
eb0e878
movie orchestration
dngoins Sep 13, 2026
78bed52
Import studio transport regression tests
dngoins Sep 13, 2026
d547069
Verify studio reconciliation and retain exact calendar confirmation r…
dngoins Sep 13, 2026
8f8e78f
movie orchestration
dngoins Sep 13, 2026
c6cd788
Verify complete showroom HTTP flow and document integrated architecture
dngoins Sep 13, 2026
06472db
Merge pull request #13 from thedamian/jmfqynl-jmf-movie-orchestration
dngoins Sep 13, 2026
185000f
showroom integration
dngoins Sep 13, 2026
0b1885a
Merge branch 'main' into jmfqynl-jmf-showroom-integration
dngoins Sep 13, 2026
fcd0e69
Merge pull request #14 from thedamian/jmfqynl-jmf-showroom-integration
dngoins Sep 13, 2026
db8a647
Preserve definitive showroom revision conflicts without leaking errors
dngoins Sep 13, 2026
faf3b38
Preserve definitive showroom revision conflicts without leaking errors
dngoins Sep 13, 2026
bff3f2d
ipad showroom face
dngoins Sep 13, 2026
cb808f4
Preserve private studio identity across launcher restarts
dngoins Sep 13, 2026
ce65e64
Scope operator origin middleware to bridge routes
dngoins Sep 13, 2026
958844b
Keep calendar receipt failures uncertain after verified remote outcomes
dngoins Sep 13, 2026
354b6bc
Bind pending studio cleanup receipts to their original authenticated …
dngoins Sep 13, 2026
614220e
Merge branch 'main' into jmfqynl-jmf-ipad-showroom-face
dngoins Sep 13, 2026
b2a1b15
Integrate final iPad presentation and recovery fixes
dngoins Sep 13, 2026
7d5c079
Rehearse studio recovery with persisted launcher credentials
dngoins Sep 13, 2026
6854fd7
Include colocated safety tests and exclude them from production output
dngoins Sep 13, 2026
8ad3cc1
Vendor showroom runtime in portable demo archive
dngoins Sep 13, 2026
e9c5e10
Merge pull request #15 from thedamian/jmfqynl-jmf-ipad-showroom-face
dngoins Sep 13, 2026
ca30d2d
Verify unpaired bridge composition and bounded credential reads
dngoins Sep 13, 2026
59f70a4
showroom integration
dngoins Sep 13, 2026
4271887
showroom int
dngoins Sep 13, 2026
a85a1dd
Merge pull request #17 from thedamian/jmfqynl-jmf-showroom-integration
dngoins Sep 13, 2026
f6059be
Fixed to the robot's probramming fixing an issue that was still there.
thedamian Sep 13, 2026
cb8373a
updated author credits
dngoins Sep 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
103 changes: 103 additions & 0 deletions .github/workflows/magicpitch-ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
name: MagicPitch offline checks

on:
pull_request:
paths:
- "FinalProject/**"
- "MoviePart/**"
- ".github/workflows/magicpitch-ci.yml"
push:
branches: [main]
paths:
- "FinalProject/**"
- "MoviePart/**"
- ".github/workflows/magicpitch-ci.yml"
workflow_dispatch:

permissions:
contents: read

concurrency:
group: magicpitch-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
verify:
name: Offline verification (${{ matrix.os }})
runs-on: ${{ matrix.os }}
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
defaults:
run:
working-directory: FinalProject
env:
MOCK_ONLY: "true"
BRIEF_PROVIDER: mock
PROFILE_PROVIDER: mock
MEDIA_PROVIDER: mock
JOB_PROVIDER: local
FOLLOWUP_PROVIDER: disabled
ALLOW_DEMO_FALLBACKS: "false"
steps:
- name: Check out source
uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
with:
persist-credentials: false
- name: Set up pinned Node
uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
with:
node-version: "24.11.0"
cache: npm
cache-dependency-path: FinalProject/package-lock.json
- name: Pin npm
run: npm install --global npm@11.6.2 --ignore-scripts
- name: Show toolchain
run: |
node --version
npm --version
- name: Restore lockfile dependencies
run: npm ci
- name: Typecheck, test, build, and smoke
run: npm run verify
- name: Package synthetic demo
if: runner.os == 'Linux'
run: npm run package:demo
- name: Upload allowlisted runtime package
if: runner.os == 'Linux'
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
with:
name: magicpitch-synthetic-demo
path: |
FinalProject/artifacts/magicpitch-demo.tgz
FinalProject/artifacts/magicpitch-demo.sha256
if-no-files-found: error
retention-days: 7

moviepart-integration:
name: Kiosk and media integration
runs-on: windows-latest
timeout-minutes: 15
steps:
- name: Check out source
uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
with:
persist-credentials: false
- name: Set up pinned Node
uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
with:
node-version: "24.11.0"
cache: npm
cache-dependency-path: |
FinalProject/package-lock.json
MoviePart/package-lock.json
- name: Pin npm
run: npm install --global npm@11.6.2 --ignore-scripts
- name: Restore orchestrator dependencies
run: npm --prefix FinalProject ci
- name: Restore MoviePart dependencies
run: npm --prefix MoviePart ci
- name: Exercise kiosk and media HTTP boundary without provider credentials
run: npm --prefix FinalProject run test:moviepart
26 changes: 12 additions & 14 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
node_modules/
.env
.env.local
*.log
dist/
.DS_Store
.turbo/
*.tsbuildinfo
.next/
next-env.d.ts
assets/fonts/
apps/mobile/.expo/

# Web approval and attempt metadata (not task storage)
.data/
**/node_modules/
**/.env
**/.env.*
!**/.env.example
**/dist/
**/.data/
**/coverage/
**/*.tsbuildinfo
**/*.log
FinalProject/artifacts/
FinalProject/.runtime/
**/.next/
1 change: 1 addition & 0 deletions .impeccable/hook.cache.json

Large diffs are not rendered by default.

61 changes: 61 additions & 0 deletions FinalProject/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Default offline demo: no external API credentials required.
HOST=127.0.0.1
PORT=3101
BRIEF_PROVIDER=mock
PROFILE_PROVIDER=mock
MEDIA_PROVIDER=mock
JOB_PROVIDER=local
FOLLOWUP_PROVIDER=disabled
ALLOW_DEMO_FALLBACKS=false
MOCK_ONLY=false

# If blank, startup writes a generated pairing token to .runtime/device-token.
DEMO_DEVICE_TOKEN=
# Exact browser origins. Default is the server's loopback origin.
ALLOWED_ORIGINS=
# Non-loopback binding requires an explicit token, trusted hosts and origins.
ALLOWED_HOSTS=

# Required only for explicitly selected live providers. Keep these server-side.
OPENAI_API_KEY=
MODEL=
EXA_API_KEY=
MEDIA_SERVICE_URL=
MEDIA_SERVICE_TOKEN=

# Authoritative showroom: disabled, explicit offline fixture, or full studio.
# The kiosk launcher selects fixture by default; live capabilities require flags.
SHOWROOM_MODE=disabled
MOVIE_STUDIO_URL=http://127.0.0.1:3200
MOVIE_API_TOKEN=
VOICE_ENABLED=false
VOICE_MODEL=gpt-live-1
REASONING_MODEL=gpt-5.6-luna
REGULAR_MODEL=gpt-5.6-luna

# Local Windows operator bootstrap only; never send this master token to iPad.
# Enabling the bridge is not permission to pair BLE or enable physical movement.
SHOWROOM_OPERATOR_TOKEN=
SHOWROOM_BRIDGE_ENABLED=false
SHOWROOM_BRIDGE_ORIGINS=http://127.0.0.1:3200

# Google Calendar is a separate opt-in. OAuth setup runs on the operator host.
CALENDAR_PROVIDER=disabled
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REFRESH_TOKEN=
GOOGLE_OAUTH_REDIRECT_URI=http://127.0.0.1:3101/oauth/google/callback
GOOGLE_CALENDAR_ID=primary
SCHEDULING_TIME_ZONE=America/New_York
SCHEDULING_DURATION_MINUTES=60
SCHEDULING_STAFF_EMAILS=
SCHEDULING_LOCATION=

# Operational safety limits, separate from the advisory two-minute UX target.
# Keep the session alive while the robot talks and media is generated.
SESSION_TTL_MS=1800000
JOB_TIMEOUT_MS=900000
MAX_SESSIONS=32
MAX_QUEUED_JOBS=4
MAX_UPLOAD_BYTES=5242880
MAX_MEDIA_BYTES=20971520
2 changes: 2 additions & 0 deletions FinalProject/.npmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
engine-strict=true
save-exact=true
1 change: 1 addition & 0 deletions FinalProject/.nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
24.11.0
152 changes: 152 additions & 0 deletions FinalProject/PLAN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# MagicPitch - Dwight Agent Orchestrator + DevOps Plan

Approved direction: standalone TypeScript API in `FinalProject`, with separate teammate-owned clients. Preserve `OriginalRepo`. The full planning discussion is retained in the Copilot session; this repository copy records the approved architecture and implementation gates.

## 1. Current Repository Assessment

The inherited starter is under `OriginalRepo`. It supplies Next/CopilotKit, a shared agent, Exa and Ambiguous reference integrations, a voice example, and Node/TypeScript tests. It did not supply a MagicPitch orchestrator, robot implementation, media service, kiosk UI, or CI pipeline. Team-part directories contained placeholders.

`FinalProject` now contains the independently runnable API, executable schemas, offline providers, job runner, synthetic media, development harness, tests and tooling. It does not import or alter the inherited starter.

Tiya's committed MoviePart kiosk and dedicated media service are now integrated
through `dev:kiosk` and cross-part HTTP tests. The older attached ZIP contains a
different creator-studio client, not the renderer. See
[MoviePart integration](docs/moviepart-integration.md) for exact startup, modes
and remaining live-provider/robot gates.

## 2. Dwight Scope

Dwight owns orchestration, contracts, typed configuration, provider boundaries, API integration, local job state, developer smoke/recovery, and CI/build/package automation. Damian owns robot/voice/capture. Tiya owns customer UI, image generation, FFmpeg/video, and reveal. Edilma owns scope, permissions, acceptance coordination and submission.

## 3. Proposed Architecture

Single long-running Node/Hono API -> consent/session state -> profile/brief providers -> bounded local media runner -> authorized MP4 result -> UI/robot playback acknowledgement. The development harness is not Tiya's kiosk design. P0 is local, in-memory, one process.

The selected reproducible runtime is Node 24.11.0 with npm 11.6.2, matching the inspected demo host and exceeding the starter's Node >=22 requirement. This makes the preliminary Node 22 proposal concrete without requiring a second runtime on the demo machine.

## 4. API and Event Contracts

See [contracts](docs/contracts.md) and `src\contracts\index.ts`.

Capabilities: `identify_customer`, `enrich_profile`, `create_ad_brief`, `start_media_job`, `get_media_status`, and an explicitly disabled `schedule_followup`.

Inputs: customer presence, scoped consent, confirmed context, reveal acknowledgement, cancellation. Every event is versioned and deduplicated; every media submission uses stable idempotency.

## 5. Data Models

Zod schemas define consent, synthetic customer profile, versioned context, product facts, immutable AdBrief, jobs, result provenance and typed errors. Session capabilities and image/video bytes never appear in snapshots or logs.

Only `demo-alex`, `demo-sam`, and the synthetic `demo-car` are registered today. Real participant enrollment/product assets require a separate agreed integration; labels such as `enrolled` are not face recognition.

## 6. Provider Strategy

Default: mock brief/profile/media, local jobs, disabled follow-up. Real provider selection requires explicit configuration.

Opt-in OpenAI supplies structured storyboard content. Opt-in Exa retrieves an explicitly supplied, separately consented public source without inferring preferences. The HTTP media adapter connects to Tiya's dedicated MoviePart service; live generation requires operator-provided credentials and renderer readiness.

Fallbacks are off by default and visibly labeled when enabled. Unknown media acceptance is never automatically retried. HTTP media requires cancellation/deletion capabilities and uses globally unique upstream job keys; failed cleanup retains private reconciliation metadata. Trigger and Ambiguous selections fail startup rather than silently pretending to work.

## 7. Golden Path

Pair device -> create session -> record presence/consent -> select roster identity -> confirm preferences -> upload image -> create immutable brief -> start idempotent media job -> poll -> retrieve MP4 bytes -> play -> acknowledge reveal -> revoke/cleanup.

Offline success proves the protocol using synthetic images/video. Live-demo success additionally requires the actual robot, participant permissions, personalized media, and customer UI.

## 8. Failure Paths

Missing consent blocks effects. Invalid identity requires reselection. Malformed provider outputs fail validation. Deadlines and cancellation suppress late completion. Queues, uploads, sessions and histories are bounded.

An explicitly selected synthetic fallback never becomes a claim of freshly personalized media. Process restart loses session/job memory. External copies and jobs are not guaranteed cancelled by a local abort.

## 9. DevOps / CI/CD Architecture

One isolated npm package/lock, strict NodeNext build, Node/tsx tests, compiled-process offline smoke, and a root GitHub Actions workflow. No Docker, cloud account, provider keys, database service or FFmpeg installation is required to run offline.

## 10. Pipeline Definition

Working directory: `FinalProject`.

| Stage | Command |
|---|---|
| Restore | `npm ci` |
| Typecheck | `npm run typecheck` |
| Unit/contract/HTTP tests | `npm test` |
| Runnable build | `npm run build` |
| Compiled offline smoke | `npm run smoke` |
| Combined gate | `npm run verify` |
| Allowlisted demo package | `npm run package:demo` |

The workflow targets Windows/Linux with the pinned toolchain. There is no invented lint command. CI uses synthetic fixtures and no provider secrets; deployment is not wired into PR validation.

## 11. Environment and Secret Strategy

Copy `.env.example` locally only when needed; `.env`, `.runtime`, build outputs, logs and private data are ignored. Provider keys remain server-side. A generated device token is stored in `.runtime\device-token`, not printed into logs or put in a URL.

Begin loopback-only. LAN mode requires explicit token, allowed hosts and origins. Browser capture may need trusted HTTPS. Exposed credentials must be rotated and replacements entered locally, never copied from chat into source.

## 12. Dwight Implementation Tasks

These task IDs correspond to the detailed session plan and task database. Effort is relative, not a completion-time promise.

| Task | Priority / effort | Owner / files | Dependency | Success / test method |
|---|---|---|---|---|
| DW-APP-01 | P0 / M | Dwight; `src\contracts`, `docs\contracts.md` | Team contract review | Strict schemas and matching robot/media fixtures |
| DW-DEVOPS-01 | P0 / M | Dwight; manifest/lock/runtime/ignore/tsconfigs | None | Clean restore and runnable build |
| DW-APP-02 | P0 / M | Dwight; `src\orchestrator` | Contracts/toolchain | Consent/session state, isolation, expiry tests |
| DW-APP-03 | P0 / S | Dwight; mock brief provider | Session/context | Deterministic validated immutable brief |
| DW-APP-04 | P0 / L | Dwight; local job lifecycle/assets | Brief/synthetic fixture | Bounded idempotent job and retrievable media |
| DW-APP-05 | P0 / M | Dwight; `src\http`, harness | State/jobs | Authenticated commands, polling, upload/reveal |
| DW-DEVOPS-02 | P0 / M | Dwight; tests/smoke scripts | API | Compiled offline process flow without external requests |
| DW-DEVOPS-03 | P1 / M | Dwight; root workflow | Reproducible scripts | PR/main/manual Windows/Linux validation |
| DW-DEVOPS-04 | P0 / M | Dwight; config/auth/startup/docs | API/toolchain | Explicit modes, safe defaults, pairing and LAN gates |
| DW-APP-06 | P0-demo / L | Dwight integrates Damian/Tiya | Real teammate interfaces/assets | Actual robot -> personalized MP4 -> observed playback |
| DW-APP-07 | P1 / M | Dwight; OpenAI adapter/tests | Brief interface/account | Structured output and error/fallback tests; live opt-in separately |
| DW-APP-08 | P1 / M | Dwight; Exa adapter/tests | Context/consent/account | Supplied-source evidence, no inferred identity/interests |
| DW-APP-09 | P1 / L | Dwight; future Trigger adapter | Reachable renderer/assets/project | Same lifecycle, proven reconciliation, local fallback |
| DW-APP-10 | P0 / M | Dwight; state/errors/logging | API/jobs | Cancellation, timeout, output validation, fallback and redaction tests |
| DW-DEVOPS-05 | P0/P1 / M | Dwight; package/runbook | Offline gate | Extracted package starts; private data excluded |
| DW-DEVOPS-06 | P1 conditional / M | Dwight; future Trigger deploy | Actual Trigger integration | Protected task deployment and local recovery |
| DW-APP-11 | P2 / L | Dwight; future Ambiguous adapter | Live demo/permissions | Immutable approval, real record read-back, no blind write retry |
| DW-DEVOPS-07 | P2 / L | Dwight; future cloud deployment | Proven need/auth/durability | Protected release and tested local recovery |

## 13. Timeline

Use dependency gates: architecture freeze -> offline foundation -> complete mock workflow -> real teammate integration -> optional intelligence -> optional async provider -> feature freeze -> recovery rehearsal -> release handoff.

Do not treat the original hackathon window as a guarantee that missing hardware/media/UI can be delivered by Dwight alone.

## 14. Testing Strategy

Unit/state tests, strict contract fixtures, bounded provider-response tests, authenticated HTTP tests, compiled-process mock smoke and explicit child-process cleanup. Provider tests use controlled responses, never paid APIs.

CI acknowledgement is simulated. Manual acceptance must observe actual audiovisual playback, confirm the correct participant/product, and measure the requested under-90-second demo criterion.

## 15. Merge Strategy

Keep the current app-managed branch. Dwight owns FinalProject API/contracts/manifests and root CI; do not edit Damian/Tiya parts. Integrate schemas and fixtures first, then robot, then media/UI, then optional providers. Re-run the same smoke after each merge. Do not rewrite unrelated starter code or reset teammates' work.

## 16. Deployment Strategy

No cloud deployment is required now. Use the loopback API, then authenticated local-network access. Cloud Run remains gated on a genuine need plus private asset storage, authentication, durable state and an appropriate long-running worker model. Trigger workers cannot read laptop-local files automatically.

## 17. Demo Recovery Plan

Use the [runbook](docs/runbook.md). Keep a known-good local build, deterministic brief, local runner, synthetic MP4 and developer harness. Failed real submissions require reconciliation rather than duplicate work. No false claims of booking, personalized generation, hardware operation or green CI.

## 18. Demo Readiness Checklist

Offline gate: clean install/build, secret-safe config, authenticated flow, byte-valid synthetic MP4, honest provenance, cancellation/expiry, smoke and reproducible startup.

Live gate: real enrolled consent, camera/voice/robot events, real customer image and product assets, personalized render, Tiya UI playback, robot acknowledgement, recovery rehearsal and measured interaction limit. These are separate gates.

## 19. Risks / Blockers

Critical: actual teammate implementations and permitted demo assets are absent. High: live provider availability, secure tablet connectivity, uncertain media acceptance, and mistaking mocks for personalization. Medium: cross-platform runtime/build drift and shared-file conflicts.

No supplied live API key has been saved or used. Exa/OpenAI/HTTP-media adapters require operator configuration and separately consented live validation. The workflow file is not evidence of a completed GitHub run until pushed/executed.

## 20. Recommended Implementation Order

Contracts/toolchain -> session/context -> deterministic brief -> local jobs/assets -> authenticated API -> compiled offline smoke -> CI/package -> actual teammate integration -> OpenAI/Exa live acceptance -> optional Trigger -> recovery/freeze -> optional Ambiguous/cloud.

Protect consent, authorization, idempotency, truthful provenance and offline smoke. Cut cloud, Ambiguous, Trigger and optional enrichment before those foundations.
Loading