ARGUS × PromptBoard — Integration Specification v1.0

A locked spec for integrating the ARGUS research-capture extension with the PromptBoard visual canvas, by adding a peer mode to PromptBoard that consumes ARGUS captures live and overlays an academic-research methodology template.

1. Vision

ARGUS captures evidence while reading. PromptBoard plans what to do with it. Currently both exist, but the bridge between "I highlighted 80 things across 30 sources" and "here is the argument structure of my paper" is manual.

This integration closes that gap by giving PromptBoard a fourth appMode — research — that subscribes to ARGUS's running WebSocket server, ingests captures as they happen, maps them onto an academic methodology canvas (PRISMA or Toulmin), and produces a plan ready to hand to an LLM for drafting.

PromptBoard remains the planning tool. ARGUS remains the capture tool. Neither forks; the integration lives at the seams.

2. Locked Decisions

The four foundational decisions taken to lock this spec:

3. Repository Layout

c:/ARGUS/                           ← repo root (rename later if desired)
├── INTEGRATION_SPEC.md             ← this file
├── README.md                       ← top-level orientation (short)
├── .github/  .specify/  .vscode/  .claude/   ← project tooling, unchanged
│
├── argus/                          ← all ARGUS code, self-contained
│   ├── ARGUS_PLAN.md
│   ├── argus_spec.md
│   ├── README.md                   ← ARGUS user-facing readme
│   ├── config.json                 ← shared between extension + server
│   ├── extension/                  ← Edge MV3 extension (Vite/React)
│   └── server/                     ← Python WebSocket + state mgmt + keybinds
│       └── data/sessions/
│
└── promptboard/                    ← all PromptBoard code, self-contained
    ├── README.md
    ├── ROADMAP.md
    ├── docs/architecture.md
    ├── specs/                      ← per-epic spec history
    ├── src/
    │   ├── html/  css/
    │   ├── js/                     ← state, canvas, nodes, connectors, …
    │   └── templates/              ← prompt-eng templates today; +academic
    ├── build.py  build.ps1
    ├── archive/                    ← regression reference monolith
    ├── dist/                       ← build output
    └── process-canvas.html         ← zero-install monolith

Rationale: keeping both side-by-side without intermixing source trees lets each tool keep its own build pipeline (Vite vs. build.py), its own tests, and its own evolution. The integration surface is small and well-defined: an ARGUS WebSocket event protocol that PromptBoard's research mode consumes.

To be deleted from the working tree as part of the reorg: - promptboard.7z (extracted) - _promptboard_extract/ (extraction scratch dir)

4. What This IS (MVP scope)

4.1 A new appMode = 'research' in PromptBoard

• Toolbar button toggles into research mode, peer to existing design / review / execution.
• Mode state is transient (not persisted), matching the existing pattern in promptboard/src/js/state.js.
• Switching modes does not destroy the canvas; the canvas is shared. Mode changes which panels, palette, and review/export logic are active.

4.2 Live ARGUS subscription

• When the user enters research mode, PromptBoard opens ws://localhost:8765 (same port as the ARGUS server) and sends { "event": "SUBSCRIBE_PROMPTBOARD" }.
• The ARGUS server adds the connection to a broadcast set and pushes:
• CAPTURE_PUSH whenever a capture is created
• CONNECTION_PUSH whenever an ARGUS connection is added
• THEME_PUSH when themes/subtopics change
• STATE on subscribe (full hydration)
• PromptBoard reconciles each push into the canvas (see §6.2 mapping).
• Connection failure → silent fallback: the user can still drop in an exported session JSON via the existing PromptBoard "Load" button.

4.3 New node-type vocabulary for research mode

Added to the existing NODE_TYPES registry in promptboard/src/js/state.js. Old types remain.

Existing PromptBoard node types stay. A user can mix prompt and claim nodes in the same canvas if they want to, e.g. "for this claim, run this LLM prompt."

4.4 Two methodology templates (locked starter set)

PRISMA — promptboard/src/templates/prisma-systematic-review.json

Pre-laid-out flow for a systematic literature review, conforming to the PRISMA 2020 phases: Identification → Screening → Eligibility → Inclusion, with placeholder counter slots, plus a section for the synthesis. Wired so dragging an evidence node into the right phase visually slots it.

Toulmin Argument — promptboard/src/templates/toulmin-argument.json

The classical six-part structure: claim ← grounds (evidence) + warrant ← backing, plus qualifier and rebuttal. Renders as a Toulmin diagram with the connector types already typed (supports, qualifies, rebuts).

Both load via the existing template gallery. Adding more methodologies later is a templates-only change.

4.5 ARGUS-aware AI advisory pass

Reuses promptboard/src/js/review.js and the provider adapters in promptboard/src/js/execution.js.

The advisory adds research-specific deterministic checks: - claim nodes with no incoming evidence connections (unsupported claim) - evidence nodes orphaned from any claim (uncategorized capture) - Claims with only same-weight evidence (e.g., all-green — no counter-considered) - For Toulmin templates: claims without warrants - For PRISMA templates: phases with zero entries

The optional AI pass uses a research-tuned system prompt (separate from the existing prompt-engineering review prompt) — assesses argumentative coherence, methodology fit, and "is this plan thorough enough to write the paper from."

4.6 Research-mode export

A new export format alongside the existing JSON / Mermaid / Message Array:

• Outline export — a structured Markdown outline grouped by claim, with quoted evidence, source URLs, and counter-arguments inlined. Designed to paste into Claude/GPT as the seed for a paper draft.
• Bibliography stub — a flat list of unique source URLs/titles seen across all evidence and source nodes.

The existing PromptBoard JSON export continues to work; research-mode nodes serialize with their full annotation set.

5. What This IS NOT

• Not a writing tool. No rich-text essay editor, no Word/LaTeX surface, no inline drafting. Hands off to an LLM or a real document editor.
• Not a citation manager. Zotero/Mendeley already exist. Source URLs and quotes ride along on evidence nodes; bibliography formatting (APA/MLA/Chicago) is out of scope.
• Not a replacement for PromptBoard's prompt-engineering modes. Design / review / execution all keep working. Research is additive.
• Not a fork of ARGUS. The browser extension and Python server are unchanged in behaviour. The server gains new WS event types; existing ones are untouched.
• Not a PDF reader, web scraper, or annotation overlay. That is ARGUS's job.
• Not opinionated about epistemology. Templates are scaffolds, not enforcement. The deterministic review checks structural sanity, not whether your argument is right.
• Not a peer-review or collaboration tool. Single-user, single-browser, localStorage-backed, like PromptBoard today.
• Not a methodology encyclopedia. Two templates ship in MVP. More are user-authored or community contributions; we don't promise comprehensive coverage.
• Not a runtime for academic prompts. PromptBoard's execution mode stays scoped to prompt workflows. Research mode talks to LLMs only via the advisory review and the outline-export "discuss this plan" path — not as a chain runner.
• Not a database. No central server, no auth, no multi-session search across history. Each session is its own ARGUS JSON; each canvas is its own PromptBoard JSON.

6. Architecture & Data Flow

6.1 Live capture flow

Browser tab (any webpage / PDF)
   │  user highlights → presses macropad button
   ▼
ARGUS extension (content + background)
   │  WS: { event: "CAPTURE", data: {…} }
   ▼
ARGUS server (websocket_server.py)
   │  state_manager.add_capture()
   │  file_io.save_session()
   │  broadcast to ALL subscribers:
   │    - existing ARGUS panel (gets STATE update)
   │    - any subscribed PromptBoard (gets CAPTURE_PUSH)
   ▼
PromptBoard, research mode
   │  ws.onmessage → reconciler
   │  → upsert evidence node, refresh section grouping
   ▼
Canvas re-render

6.2 ARGUS-to-PromptBoard mapping

6.3 Reconciliation rules

• New argusCaptureId not on canvas → create node, place inside the matching theme section (auto-create section if absent).
• Existing argusCaptureId already on canvas → update annotation fields only; never move the node (user may have repositioned it intentionally).
• Capture deleted in ARGUS → soft-mark the PromptBoard node (stale: true, dimmed rendering); the user decides whether to remove it. We never auto-delete user canvas state.

7. WebSocket Protocol Additions

Existing ARGUS protocol (in argus/ARGUS_PLAN.md §"WebSocket Protocol") stays. The integration adds:

Client → Server

{ "event": "SUBSCRIBE_PROMPTBOARD" }
{ "event": "UNSUBSCRIBE_PROMPTBOARD" }

Server → Client (sent only to PromptBoard subscribers)

{ "event": "CAPTURE_PUSH",     "data": { /* full capture object */ } }
{ "event": "CAPTURE_DELETED",  "data": { "id": "cap_..." } }
{ "event": "CONNECTION_PUSH",  "data": { /* connection object */ } }
{ "event": "THEME_PUSH",       "data": { /* themes array */ } }
{ "event": "HYDRATE",          "data": { /* full session: themes, captures, connections */ } }

HYDRATE is sent once on subscribe so a freshly-opened PromptBoard catches up to the session state without replaying every event.

The existing ARGUS panel does not change. The server keeps two broadcast sets internally: {argus_panel_clients} and {promptboard_clients}. A client declares which set it belongs to via its first message (GET_STATE for the panel, SUBSCRIBE_PROMPTBOARD for the canvas).

8. Build Phases

Phase 0 — Reorganize (zero behavior change) ✅

• [x] Move extension/, server/, config.json, ARGUS_PLAN.md, argus_spec.md into argus/
• [x] Move existing top-level README.md to argus/README.md
• [x] Unpack PromptBoard tree into promptboard/
• [x] Delete promptboard.7z and _promptboard_extract/
• [x] New top-level README.md orienting visitors to the two subprojects
• [x] Verify ARGUS still builds + runs (cd argus/server && python main.py; cd argus/extension && npm run build)
• [x] Verify PromptBoard still builds (cd promptboard && python build.py)

Phase 1 — Research mode skeleton ✅

• [x] Add 'research' to appMode enum in promptboard/src/js/state.js
• [x] Toolbar mode toggle button + visual indicator
• [x] Research-mode panel shell (empty for now)
• [x] Mode-aware palette: hide prompt-engineering node types, show research types

Phase 2 — New node types ✅

• [x] Extend NODE_TYPES with claim, evidence, counter, warrant, source, question, gap, method
• [x] Annotation panel renders type-specific fields
• [x] Visual styling per type (color accents, icons)

Phase 3 — Live push ✅

• [x] PromptBoard WS client module (promptboard/src/js/argus_sync.js)
• [x] ARGUS server: subscriber set + new event vocabulary (SUBSCRIBE_PROMPTBOARD, HYDRATE, CAPTURE_PUSH, CAPTURE_DELETED, CONNECTION_PUSH, THEME_PUSH)
• [x] Reconciler: capture → evidence node, theme → section, with idempotent updates by argusCaptureId
• [x] HYDRATE on subscribe

Phase 4 — Templates ✅

• [x] prisma-systematic-review.json — 12 nodes, 10 connectors, 4 sections (4-phase PRISMA 2020 flow)
• [x] toulmin-argument.json — 7 nodes, 4 connectors, 1 section (six-part Toulmin scaffold)
• [x] Template gallery (existing ⊞ New from template toolbar button) auto-picks them up via build.py's template scan
• [x] Direct shortcut buttons in the research panel for one-click application

Phase 5 — Review + export tuned for research ✅

• [x] New deterministic checks in promptboard/src/js/review.js: unsupported_claim, orphan_evidence, single_sided_claim, empty_methodology_section
• [x] Research-tuned AI advisory system prompt — branches on baseMode === 'research'
• [x] Outline export (Markdown grouped by claim, with quoted evidence + sources + counter-arguments)
• [x] Bibliography stub export (de-duplicated unique sources from evidence + source nodes)

Phase 6 — Polish ✅

• [x] File-import fallback for ARGUS sessions — importArgusSessionFile() in argus_sync.js; reuses the live-push reconciler
• [x] "Stale capture" reconciliation UI — research-panel badge with count + "Remove N stale captures" button (pruneArgusStaleNodes())
• [x] Canvas-side reverse channel — maybePushConnectorToArgus() automatically mirrors user-drawn connectors between ARGUS-tracked evidence nodes back to the server as ADD_CONNECTION events (no toggle; on whenever the WS is connected)
• [ ] Citation styling (APA/MLA) — deferred (only on user request per the original spec)

9. Open Questions Parked (do not block MVP)

• Should the macropad ever talk directly to PromptBoard (e.g. button 6 = "create a new claim node from current ARGUS theme")? Probably yes, but defer until the live-push feedback loop is proven.
• Multi-session import: opening a 2nd ARGUS session JSON on top of an existing canvas — merge or fork? MVP says: each canvas is one session. Decide later.
• Citation manager bridge (Zotero export ↔ source nodes) — a real ask, but a separate epic.
• Desktop-app packaging (Electron/Tauri) so PromptBoard isn't tied to a browser tab — out of scope; the zero-install HTML is a deliberate constraint.

10. Success Criteria for MVP Sign-Off

The integration is done when a user can:

1. Run python argus/server/main.py, load the ARGUS extension in Edge, open promptboard/dist/index.html, switch to research mode, and pick the Toulmin template.
2. Highlight text on a webpage, press the green macropad button, and watch the quote appear as an evidence node inside the matching theme section on the PromptBoard canvas — without manual import.
3. Connect that evidence to a claim node with a typed supports connector, drag a warrant between them.
4. Run the AI advisory and get back research-flavored feedback ("claim X has no counter-evidence; consider whether the literature offers any").
5. Export an outline and paste it into Claude to draft a paper section.

If those five steps work end-to-end, MVP ships.