684c87bc8a
Drop the unified 🌹 Pastebin in favor of one self-contained Apple Note per
campaign, each structured top-to-bottom as FACTS (per-note invariants) →
POLICY/CoT (decision tree: state ∧ signal-predicate → leaf) → LEAVES (message
bodies). Tree/leaf model: state.ts becomes a tree evaluator (signals computed
in code, policy+leaves+facts-text in the note) and the NextAction.reason chain
is persisted per send as the CoT path for the teach-loop. Self-contained leaves
let copy diverge per campaign (incall vs outcall vs leaving-NY urgency).
Campaign set, naming convention, priority-based selection, 2-way multi-note
sync, and voice-corpus split all updated to match.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||
|---|---|---|
| @packages | ||
| Config | ||
| designs | ||
| docs | ||
| mcp | ||
| migrations | ||
| scripts | ||
| Sources | ||
| src | ||
| web | ||
| .gitignore | ||
| .infra.yaml | ||
| CLAUDE.md | ||
| nest-cli.json | ||
| package-lock.json | ||
| package.json | ||
| PLAN.md | ||
| project.yml | ||
| README.md | ||
| run | ||
| tsconfig.json | ||
| vitest.config.ts | ||
@prospector (Quinn Prospector)
Canonical home for the Quinn Prospector system under the @applications convention.
Primary: Webapp (containerless Chrome PWA / installable app) at https://my.transquinnftw.com/prospector/app (SSO via the my. surface).
- Focused "app" experience (full viewport, clean or mac-window style from the designs, minimal browser UI when installed as Chrome app via PWA manifest + "Open as window").
- Runs in Chrome for instant access + "chrome toolkit" (full DevTools for easy control, network inspection, console to drive/test prospector flows, elements for live UI tweaks) — no Electron/container overhead ("containerless").
- Much faster/easier to build and iterate than Swift native OSX app.
- The 8 designs/ (interactive HTML prototypes) are the complete visual + behavior spec (main-view with segmented channels + bilingual + toolbar actions, reports-dashboard 4 reports, queued-tasks with sim + log, pastebin-panel, detail, index hub, etc.). Port/enhance them for the webapp + wire real LP data (existing prospector api in my/, mcp-prospector, quinn-inbox-ops dashboard stats for backlog 149 follow-ups + inbound/channel sourced prospects totals).
- Replicates the Executor "existing html,data" quinn-inbox-ops live-ops dashboard concepts (backlog stats, 7d inbound chart, channel sends) + supporting prospect review tools.
- SSO at the URL; also pushable via quinn-desktop for phone review on the road without iOS app.
- LP is the backend (prospect-runner ondemand GPU, pastebin from Notes/mac sync, engine_drafts, corrections, etc.). No reimpl.
- (Swift exploration + @packages/prospector-client/ui retained as reference / for potential iOS/cocottetech sharing; web is the central for speed.)
Implemented operator app — web/ (self-contained PWA on this repo's backend)
The full operator experience that replaces the Claude coworker is built and
running in web/ (Vite + React), served same-origin by this repo's NestJS
backend (src/) on its own DB. This is the fastest path: backend + UI + deploy
in one repo, no platform my/ round-trip. It installs as a standalone
Chrome/macOS window (manifest + app-shell service worker + icon in web/public/).
Nav-rail shell → seven views, all wired in the UI and backed by real /prospector/* endpoints:
| View | Status | What it does | Backend |
|---|---|---|---|
| Triage | ✅ wired | Life/Dates/Digital segmented roster + search → detail | GET /prospector/prospects |
| Detail | ✅ wired | thread, Mr. Number panel + request, signals/booking, draft-from-🌹 + send-via-outbox, teach-loop correction | GET /prospector/prospects/:handle, POST /prospector/{draft,send,mr-request,corrections} |
| Queue | ✅ wired | held-for-review backlog → open / release to outbox | GET /prospector/held-queue |
| Campaigns | ✅ wired | tag + market + first/last-msg-ago filter → audience preview → confirmed launch + history | GET /prospector/campaigns/facets, POST /prospector/campaigns/{preview,}, GET /prospector/campaigns |
| Reports | ✅ wired | auto-qualify funnel, 7d volume, band/market bars, backlog | GET /prospector/reports |
| Pastebin | ✅ wired | live 🌹 canon templates | GET /prospector/pastebin |
| Control | ✅ wired | original kill-switch / digest / activity / held | GET/PUT /prospector/settings, /activity, /digest |
| Markets | ✅ wired | tour-stop selector + per-market peak hours/days, conversion, locality | GET /prospector/markets, GET /prospector/market-stats |
Two distinct "market" notions (don't conflate): the campaign-targeting market is a coarse E.164 calling-code bucket (src/prospects/segment.ts, e.g. US/CA, MX) used in Campaigns/Reports; the tour-stop market is a metro Quinn physically works for a date window with a timezone (src/markets/registry.ts, currently NYC) used by the Markets stats.
Every send (manual, AFK runner, or campaign) goes through the macsync outbox,
keeps the human_owned hard floor, and writes one shared prospect_drafts
audit row. Campaigns never blast Life-band contacts unless life is explicitly
selected. The platform my/ surface (below) is the SSO/phone goal; the
in-repo web/ app is the implemented workhorse today.
Dev: cd web && npm run dev (proxies /api → backend, injecting the service
token from PROSPECTOR_SERVICE_TOKEN). Build: npm run build → web/dist/.
Prod is same-origin: main.ts serves web/dist (Express useStaticAssets)
with the API at /prospector/*; api.ts targets /prospector in prod and the
/api Vite proxy in dev. No SPA-fallback route is needed — the app hash-routes.
Open goals: in-browser visual pass + runtime same-origin check (needs the live
stack) · deploy behind the auth-injecting proxy on the DO droplet · the my/
SSO port.
MVP (Web PWA as Central Workhorse at my.transquinnftw.com/prospector/app)
See the consolidated session plan.md (for history) and especially @applications/@prospector/PLAN.md (the thorough, self-contained handoff for Claude Code / agent takeover) for full details, phases, verification steps, commands, and references.
Brief (see PLAN.md for exhaustive MVP scope, success criteria, and phased execution plan):
- Dedicated /prospector/app shell (PWA manifest for Chrome install as standalone app).
- 1-view main (Life/Dates/Digital) live from LP, bilingual, toolbar (Classify GPU, Request MR, Refresh Pastebin macsync).
- Full reports (4 from the prototype).
- Queued tasks / backlog manager (real or sim from engine_drafts, with the 149-style followups + totals).
- Pastebin panel + detail view + actions wired to real backend (MR, classify, draft, send, corrections).
- Inbox-ops dashboard style stats (backlog follow-ups/total, inbound chart, channel sourced).
- Uses existing my/ prospector components + api where possible + ports interactions from designs/.
- Fast iteration in web + Chrome devtools.
The webapp + any shared web client are surfaces on top of LP.
Handoff for Claude Code Takeover
Primary document: Read @applications/@prospector/PLAN.md in full. It includes:
- Executive summary, architecture (DO for webapp; mesh only for quinn-messenger/macsync Apple features: Notes pastebin, messages, phonecalls, calendar).
- The 8 designs/ as authoritative spec (summarized + "read the HTMLs" instructions).
- Current status (shell + basic port done in my/ frontend; see ProspectorApp.tsx, route, manifest).
- Detailed 10-phase plan for next agent (prep/verif → polish shell/PWA → port main 1-view + inbox-ops stats → wire actions → reports → queued/pastebin → detail → PWA polish → testing/health/verif → docs/cleanup/deploy).
- Exact commands, verification rules (read designs + code + health before edits/commits; side-by-side with prototypes; atomic commits with Co-Authored-By), references (mcp-prospector, my/ types/hooks/tabs, quinn-inbox-ops from Executor, handoffs, joker DNS pm todos + project_cloud-rebuild/BACKLOG.md, etc.).
- Risks, success criteria, how to explore (ls/grep/read everything first — anti-hallucination), post-MVP.
Update this README + PLAN.md + designs/ as you progress. The session plan.md has full prior history (Swift pivot, Executor context, web decision) but PLAN.md is the actionable takeover doc.
Deployment
- Webapp (frontend changes for /prospector/app PWA + my/ prospector enhancements) deploys to DO cloud as part of quinn.my:
./run deploy:my(or CI deploy-quinn-my.yml) builds my/frontend-public and serves from /var/www/quinn.my/public on the DO VPS (quinn-vps).- Accessible at my.transquinnftw.com/prospector/app once the my surface is live.
- Only quinn-messenger (quinn.m stack + MCP) depends on WG mesh:
- Used by prospector for macsync: Notes pastebin (templates/replies/followups), messages/iMessage, phonecalls, calendar sync.
- Deploy messenger separately (
deploy:m); macsync runs on the local Mac over mesh. - Core prospector (inbox stats, classification, drafts, sends, reports, queue views that don't hit Apple data) works purely on DO + LP without mesh.
- In the webapp code (ProspectorApp.tsx and platform prospector components): pastebin refresh, macsync message/calendar features are the mesh-dependent ones; document calls accordingly. Non-messenger paths are pure DO.
See PLAN.md (and session plan.md) for full details + joker DNS cross-refs (uvlava ct subdomains + live.transquinnftw.com for enabling related platform features).
CI/CD using DO infra runners on ct-forge
- Workflows in
.forgejo/workflows/ci.yml - Uses self-hosted Linux runners on ct-forge DO infra (labels: self-hosted, linux, do, ct-forge).
- Runners provisioned via terraform/cloud-init in
@projects/@cocottetech/infra/terraform/ci-runners/(updated with Swift toolchain support for prospector-client). - Verifies
prospector-client(Swift build/test on Linux). prospector-ui(SwiftUI) and macOS app noted as requiring macOS runner or remote Xcode (e.g. build-tools to plum-style host). See cloud-init for Swift pre-install on Linux runners.- Publishing: on tags (SPM via git + Forgejo Swift registry if used).
To apply runner changes: terraform apply in the ci-runners dir (re-provisions or updates existing runners on DO).
GPU / On-demand
LP provides the system. Provision GPU droplet anytime for prospect tasks:
See @projects/@lilith/lilith-platform.live/scripts/provision-raw-gpu-droplet.sh
create(dry-run first)- Post: install NVIDIA/vLLM, register with model-boss for prospect.*
- Then set backend flag; health script verifies.
The prospector-health.sh is the proof for the full pipeline (including optional model-boss/GPU).
Structure
See the plan for details.
Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com