admin / Apex

# Synapse-Apex — User Guide

A practical, task-oriented guide for everyday users (Bid Managers, Contributors,
Finance and Approvers). For system setup and administration see the
[Admin Guide](ADMIN_GUIDE.md).

---

## 1. Signing in

1. Go to the application URL (default **http://localhost:3000**).
2. Enter your email and password. New accounts are created by an administrator with
   a temporary password — you will be asked to **set a new password** on first login.
3. If multi-factor authentication (MFA) is enabled or enforced, you will scan a QR
   code with an authenticator app (e.g. Microsoft/Google Authenticator) and enter a
   6-digit code. Store the **recovery codes** shown during setup somewhere safe —
   each can be used once if you lose your device.

Your name and roles are shown at the bottom of the left sidebar. **Sign out** is there too.

---

## 2. The dashboard

The landing page lists every bid in the workspace.

- **Summary tiles**: active bids, bids due within 14 days, and win rate.
- **Table columns**: reference, title, client, workflow state, submission date
  (with a countdown/overdue flag), completeness %, and the bid production cost
  (planned / actual).
- **View icon (👁)**: opens that bid's own **workspace** — this is where all work on a
  bid happens.
- **+ New bid** (Bid Managers): opens the create form.

### Creating a bid

Provide the title, client, **start date** and **submission date** (start must be
before submission), the **opportunity value (£)**, **contract duration (months)**,
an optional **opportunity web link** (e.g. the portal URL), the compliance
frameworks to align to, and any win themes. You are taken straight into the new
bid's workspace.

---

## 3. The bid workspace

Opened from the dashboard view icon. At the top sits the **workflow bar** (see §4),
followed by tabs for each stage of work.

### Overview
Shows and lets Bid Managers edit the opportunity details: client, value, duration,
web link (click to open), dates and win themes. Use **Edit** → change → **Save**.

### Documents
Upload the tender / ITT / RFP documents (PDF, DOCX, XLSX, TXT, MD). Uploaded files
are listed with their type and size. The system extracts their text ready for
analysis.

### Requirements (the review gate)
- **Extract from tender** reads the uploaded documents and produces a list of every
  response the tender demands. (If AI is not configured, a placeholder requirement
  is created so you can still work.)
- Review the list carefully — **edit** any field inline, **+ Add** missing
  requirements, or delete (✕) irrelevant ones. Set a **word limit** per requirement
  where the tender imposes one, and tick **mandatory** where applicable.
- This is a deliberate **human gate**: nothing is generated until you are happy with
  the requirement list.

### Responses
- **Generate all** drafts a response to every requirement, grounded in the approved
  capability library and aligned to the bid's frameworks and win themes. You can also
  **Generate** a single requirement's response.
- Each response shows a **live word count** against the requirement's word limit and
  turns red if you exceed it.
- **Edit** any response directly in the text box, then **Save edits**. Use
  **Mark in review** and **Approve** to move a response through its lifecycle, or
  **Regenerate** to redraft. AI-identified **gaps** ("no evidence for X") are flagged
  for a subject-matter expert.

### Plan
- **Generate / rebuild plan** creates milestones and one task per requirement,
  **back-scheduled** from the submission date using working days.
- A **Gantt chart** renders automatically: milestones as diamonds, tasks as bars,
  a dashed line for today, and colour by status (indigo = task, gold = milestone,
  green = done, red = overdue).
- Record **actual hours** and update task **status** in the table below.

### Cost
- Enter endpoint counts (servers, workstations, network devices, users, sites) and
  the contract **term**, then **Calculate**. The engine converts these into resource
  hours and licence costs using the effort rules and rate catalogue.
- Any cost line can be **overridden** by typing a new monthly/one-off value.
- **Non-people resource costs**: add hardware, travel, connectivity, facilities or
  any other cost directly (description + monthly and/or one-off amount). These persist
  across recalculations.
- Totals (monthly, one-off, total contract) are shown at the bottom.

### Pricing
- Enter **risk contingency %**, **management contingency %** and **target margin %**,
  name the scenario, and **Price it**. Margin is applied **on the sell price**, shown
  as a transparent waterfall (base → contingencies → total cost → margin → sell price).
- **AI justification** drafts the price narrative and value statements.
- Save several scenarios; **Select** the one that flows into the final package.

### Assistant ✦
The Assistant is an **optional AI advisory tool** that helps you produce the highest
quality, best-evidenced answers. It is layered on top of everything else — it never
changes anything on its own.

- **Availability:** it only works if an administrator has enabled **AI Integration**
  (Administration → Security). If they haven't, the tab tells you so.
- **Switch on per bid:** a Bid Manager turns the Assistant **on** or **off** for this
  specific bid using the button at the top of the tab.
- **Bid-level advice:** *Get bid-level advice* reviews the whole bid — coverage gaps,
  weak responses, win-theme opportunities, prioritisation — grounded only in the data
  in the application.
- **Enhance a response:** on the **Responses** tab, click **✦ Ask Assistant** on any
  response. The Assistant drafts an improved version and lists specific advice.
- **Align to a framework:** on the **Responses** tab, click **✦ Align to framework** to
  get suggestions that map a response more explicitly to the bid's active compliance
  framework(s) — which controls to reference and evidence to cite.
- **The thought cloud 💭:** the Assistant surfaces its latest idea in a floating
  **thought cloud** in the corner of the workspace. It **pings** when it appears (you
  can mute/unmute with the speaker icon on the cloud — your choice is remembered). The
  cloud **disappears once you acknowledge it** (*Got it*), and only comes back when the
  Assistant has **another** idea, or when **you summon it** with the ✦ button. You can
  **Approve & apply**, **View** (open the Assistant tab), or acknowledge, all from the
  cloud.
- **Guard-rail indicator:** every suggestion shows whether the Assistant
  **self-checked for hallucinations** and how many unsupported claims it removed
  (`✓ Self-checked for hallucinations — N removed`). Hover to see exactly what was
  removed. If AI is unavailable, it shows `⚠ Self-check unavailable`.
- **You are always in control:** an enhancement is applied to the response **only when
  you click _Approve & apply_**. You can **Dismiss** any suggestion. Every decision —
  toggled on/off, advice generated, suggestion applied or dismissed, and by which login
  — is recorded in the bid's **Activity** trail.

### Package
- **Assemble package** compiles the responses, compliance matrix, and selected
  pricing into a versioned package. Unapproved responses are flagged and block
  approval.
- **Export** the package as **DOCX** (main response), **XLSX** (cost & pricing) or
  **PDF** (summary).
- Approvers can **Approve** (locks the version) or **Request changes** (with a
  comment, which reopens the work).

### Activity
A complete **audit trail for this bid** — every action, who (which login) performed
it, and when. Use it to see progress and for governance.

---

## 3b. Answer Library (sidebar)

The **Answer Library** is a searchable catalogue of every tender question and its
response — your team's growing bank of proven answers. Open it from the left-hand menu.

- **It fills itself.** Every time a bid response is **approved**, that question and answer
  are automatically added to the Library. When a bid is marked **won** or **lost**, that
  outcome is stamped onto its answers so you can tell winners from cautionary examples.
- **Search & filter.** Type keywords (e.g. "security operations centre", "SLA",
  "transition") and filter by category, client, outcome (won/lost), or framework. Results
  rank **master** answers first, then **won** answers, then most-reused.
- **Reuse to win faster.** On each answer card, **Copy answer** puts it on your clipboard;
  **View** opens the full detail with provenance (which bid/client, won or lost) and reuse
  history.
- **Insert straight into a bid.** On a bid's **Responses** tab, click **"Find in Answer
  Library"** on any response to search proven answers for that question and **Insert** the
  best one directly into your draft — the reuse is logged automatically.
- **Curate the best.** Bid Managers and Contributors can **Add** answers manually, edit
  them, tag/categorise them, **mark an answer as "master"** (the recommended canonical
  answer), or **archive** weak ones. Administrators and Bid Managers can **Harvest
  approved** to back-fill the Library from existing approved responses in one click.

Why it matters: winning tenders is largely about reusing and refining what already won.
The Library turns every bid's best answers into an asset the whole team can draw on —
faster drafting, consistent quality, and fewer weak answers under deadline pressure.

---

## 4. The workflow bar

The coloured rounded boxes across the top of the workspace show the bid's lifecycle:

`Draft › Planning › In progress › In review › Approved › Submitted` → outcome
(`Won` / `Lost` / `Withdrawn`).

- The **current** stage is filled indigo; **completed** stages are green; upcoming
  stages are light grey.
- Boxes you are allowed to move to are **outlined in gold** and clickable — click one
  to advance (or step back) the bid. Only Bid Managers and Approvers can move the
  workflow; others see it read-only.

---

## 5. Roles at a glance

| You are a… | You can… |
|---|---|
| **Bid Manager** | Create/manage bids, upload docs, run generation, edit everything, move the workflow |
| **Contributor** | Edit/author responses, upload supporting docs, update plan tasks |
| **Finance** | Manage the cost sheet, non-people costs, pricing scenarios, and the rate catalogue |
| **Approver** | Review packages, approve or request changes, advance review/approval stages |
| **Read-Only** | View dashboards, bids and packages |

Administrators can do everything, plus manage users and system settings
(see the Admin Guide).

---

## 6. Tips

- **AI output is always a draft.** Review and edit before approving — the app never
  submits anything externally.
- If AI features are unavailable, the app still works end to end; AI steps produce
  clearly labelled placeholders for a human to complete.
- Assemble the package only once responses are approved — the package screen tells you
  how many are still outstanding.
- Exports reflect the **latest assembled** package, so re-assemble after changes.