WebChecker/USER_MANUAL.md

# Website Checker — User Manual

**Version 1.0** | For all users

---

## Table of Contents

1. [Getting Started](#1-getting-started)
2. [Logging In](#2-logging-in)
3. [My Shift — The Daily Checklist](#3-my-shift--the-daily-checklist)
4. [Checking Off a Website](#4-checking-off-a-website)
5. [Site Health Indicator](#5-site-health-indicator)
6. [Viewing Credentials](#6-viewing-credentials)
7. [Shift Reminder Notifications](#7-shift-reminder-notifications)
8. [AI Document Summary](#8-ai-document-summary)
9. [Evaluation Criteria](#9-evaluation-criteria)
10. [Analysis History](#10-analysis-history)
11. [Change Password](#11-change-password)
12. [Admin — Dashboard](#12-admin--dashboard)
13. [Admin — Website Management](#13-admin--website-management)
14. [Admin — User Management](#14-admin--user-management)
15. [Admin — Shift Management](#15-admin--shift-management)
16. [Admin — Reports](#16-admin--reports)
17. [Admin — Activity Log](#17-admin--activity-log)
18. [Admin — Email Report Settings](#18-admin--email-report-settings)
19. [Admin — AI Summary Settings](#19-admin--ai-summary-settings)
20. [Session Timeout](#20-session-timeout)
21. [Keyboard Shortcuts](#21-keyboard-shortcuts)
22. [Troubleshooting](#22-troubleshooting)

---

## 1. Getting Started

Website Checker is a desktop application that helps your team systematically
verify that assigned websites are operational each shift. Every team member
logs in, checks each site, and marks it complete. Administrators can see
team-wide progress in real time, run reports, and receive automated daily emails.

**Who sees what:**

| Feature | Regular User | Administrator |
|---|---|---|
| My Shift checklist | ✔ | ✔ |
| AI Document Summary | ✔ | ✔ |
| Change Password | ✔ | ✔ |
| Dashboard & Reports | — | ✔ |
| Manage Websites / Users / Shifts | — | ✔ |
| Email Settings & Activity Log | — | ✔ |
| AI API key & model selection | — | ✔ |
| Add/Edit Evaluation Criteria | — | ✔ |

---

## 2. Logging In

1. Launch the application by running `app.py` (or the desktop shortcut).
2. Enter your **Username** and **Password**.
3. Press **Enter** or click **Sign In**.

**If your account is locked:** After 5 failed attempts your account is locked
for 15 minutes. The login screen shows a countdown timer. Wait for it to reach
zero and try again with the correct password.

**If you forget your password:** Contact your administrator. They can reset it
from the User Management panel.

---

## 3. My Shift — The Daily Checklist

After logging in, regular users land on the **My Shift** panel. This shows all
websites you are expected to check during your current shift today.

### Layout

```
┌─────────────────────────────────────────────────────┐
│  My Shift        [ Search... ] [All ▾] [✓ Select All Unchecked]  │
├──────────────────────────────────────────────────────┤
│  ● [✓] Portal                  ↗ Open    🔑 Credentials │
│      https://portal.gov          Shift: Morning       │
│      Note: Check dashboard for alerts          [Edit] │
├──────────────────────────────────────────────────────┤
│  ● [ ] Vendor Hub              ↗ Open    🔑 Credentials │
│      https://vendor.example.com  Shift: Morning       │
├──────────────────────────────────────────────────────┤
│  Progress: ████████░░  1 / 2 checked (50%)            │
└─────────────────────────────────────────────────────┘
```

### Elements

- **Colour dot** — health status of the site (see §5)
- **Checkbox** — tick to mark the site as checked for today
- **Site name / URL** — click either to open the site in your browser
- **🔑 Credentials** — appears only if credentials are stored; click to view
- **Note field** — free-text area to leave a per-site note for the shift
- **Progress bar** — shows how many sites you have checked vs total

### Filtering and search

- **Search box** — type any part of a site name or URL to filter the list
- **Dropdown filter** — choose All, Checked, or Unchecked
- **✓ Select All Unchecked** — ticks all currently visible unchecked sites at once

---

## 4. Checking Off a Website

1. Open the website (click the name or URL).
2. Verify the site is operational.
3. Tick the **checkbox** on the site card, or press **Space** when the card is focused.
4. The checkbox turns green and the progress bar advances.

To **uncheck** a site, tick the checkbox again. You can re-check as many times
as needed throughout the shift.

**Weekly sites** appear only once per week. Once checked, they disappear from
your list until the following Monday.

---

## 5. Site Health Indicator

The coloured dot next to each site name is automatically refreshed in the
background when you open the checklist.

| Colour | Meaning |
|---|---|
| 🟢 Green | Site is reachable and responding quickly (under 3 seconds) |
| 🟡 Amber | Site is reachable but slow (over 3 seconds), OR responding with a 4xx access restriction |
| 🔴 Red | Site is unreachable — network error or server failure |

**Amber (restricted)** means the server responded — it is online — but rejected
the automated probe request. This is normal for sites that block automated checks.
Open the site manually to verify it is actually working.

Hover over the dot to see the tooltip with exact response time and status.

---

## 6. Viewing Credentials

If your administrator has stored login credentials for a site, a **🔑 Credentials**
button appears on that site's card.

1. Click **🔑 Credentials**.
2. A popup appears showing all stored credential sets for that site.
3. Click **📋** next to the username to copy it to the clipboard (flashes "Copied!" for 2 seconds).
4. Click **📋** next to the password to copy it (also clears the clipboard automatically after 15 seconds).
5. Click **👁** to reveal the password on screen.

The popup closes when you click outside it or press Escape.

---

## 7. Shift Reminder Notifications

If you have unchecked sites when your shift is about to end, the app sends a
desktop notification listing all unchecked sites together.

- The reminder fires **15 minutes before your shift end time** by default.
- One notification covers all unchecked sites in the shift — you will not receive
  a separate popup per site.
- Example: *"3 sites unchecked: Portal, Vendor Hub, SAM.gov. Shift ends at 17:00 (15 min remaining)."*

If the desktop notification system is unavailable, an in-app toast message appears
in the bottom-right corner instead.

---

## 8. AI Document Summary

The **🤖 AI Summary** panel lets you upload government solicitation documents
and receive an AI-generated extraction of key procurement fields, plus an
alignment recommendation based on your company's evaluation criteria.

### Uploading documents

1. Click **➕ Add Files** in the left pane.
2. Select one or more files. Supported formats:
   - PDF (`.pdf`)
   - Word documents (`.docx`, `.doc`)
   - Excel spreadsheets (`.xlsx`, `.xls`)
   - Text files (`.txt`, `.md`, `.csv`)
3. The file list shows each file name and size.
4. To remove a file, right-click it and choose **Remove selected**, or use **✕ Clear All**.

### Running the analysis

1. Click **✨ Analyze with AI**.
2. The status bar shows progress as each file is read and the AI processes them.
3. Results appear in the right pane when complete.

### What the AI extracts

For each document, the AI identifies and labels:

| Field | Example |
|---|---|
| Solicitation Number | W912DR-25-R-0042 |
| Solicitation Type | RFP, RFQ, IFB |
| Set-Aside | Small Business, 8(a), N/A |
| Description / Scope of Work | Summary of required services |
| Work Site / Location | Full address of performance site |
| Pre-Proposal Conference | Date, time, address, mandatory or optional |
| Point of Contact (POC) | Name, phone, email |
| Total Square Footage | If applicable |
| Driving Distance & Travel Time | From office to conference/site (AI estimate) |
| Last Day to Submit Questions | Date |
| Due Date & Time | Submission deadline |
| Other Notable Requirements | Bonding, insurance, certifications |

After the per-document breakdown, the AI produces an **Overall Summary** with:

- **A. Scope of Work** — what is being requested and key performance requirements
- **B. Contract Period** — base period, option years, anticipated start date
- **C. Proposal Submission Requirements** — documents, formatting, evaluation criteria
- **D. Key Deadlines & Action Items** — all critical dates in chronological order

### Saving and copying results

- **📋 Copy** — copies the full output text to the clipboard
- **💾 Save as TXT** — saves the output to a text file you choose
- **🗑 Clear** — resets the output panel

---

## 9. Evaluation Criteria

When your administrator has configured evaluation criteria, the AI automatically
assesses the solicitation against each one and issues a recommendation.

### The criteria panel

The **📋 Evaluation Criteria** panel sits below the page header and is collapsible.
It shows all currently configured criteria with their title, description, sort order,
and active status.

Criteria marked **✔ Active** are included in every AI analysis you run.
Criteria marked **✘ Inactive** are shown for reference but not sent to the AI.

### The alignment verdict

When active criteria exist, the analysis output includes a colour-coded banner:

| Banner | Meaning |
|---|---|
| ✅ Green — PURSUE | The opportunity strongly aligns with your criteria |
| 🚫 Red — PASS | The opportunity fails one or more key criteria |
| ⚠️ Amber — UNCLEAR | Insufficient information in the documents to decide |

Below the banner, the AI lists each criterion and explains whether the solicitation
**MEETS**, **DOES NOT MEET**, or **PARTIALLY MEETS** it, citing specific details
from the documents. It ends with a 2-3 sentence executive summary.

### For administrators — managing criteria

Click **＋ Add Criterion** in the criteria panel header to open the Add Criterion dialog.

| Field | Description |
|---|---|
| Title * | Short name shown in the treeview (e.g. "Geographic Range") |
| Description * | Full criterion text sent to the AI — be specific |
| Sort Order | Lower numbers appear first |
| Active | Uncheck to exclude from AI analysis without deleting |

**Tips for writing effective criteria:**

- Be specific and measurable: *"Work site must be within 50 miles of Falls Church, VA"*
  is better than *"Site must be nearby."*
- One criterion per idea — don't combine multiple requirements in one description.
- The description has a **500-character soft limit**. Longer descriptions consume
  token budget that would otherwise go to the document content.

To **edit** a criterion, select it in the list and click **✎ Edit**, or double-click the row.
To **delete** a criterion, select it and click **✕ Delete**. You will be asked to confirm.

---

## 10. Analysis History

Every analysis you run is automatically saved. Click the **🕑 History** tab to review past results.

### History tab features

- **Treeview** — shows Date/Time, Files analyzed, Model used, and Verdict for each analysis.
  Administrators see all users' analyses; regular users see only their own.
- **Verdict filter** — radio buttons let you filter by All / PURSUE / PASS / UNCLEAR / No verdict.
- **Detail strip** — selecting a row shows the criteria snapshot and other metadata at the bottom.
- **↻ Refresh** — reloads the history from the database.
- **🔍 View Result** — loads the full AI output for the selected analysis back into the
  Analyze tab output panel, including the verdict banner. You can then copy or save it.
- **Double-click** on any row does the same as View Result.

The History tab refreshes automatically whenever you switch to it.

---

## 11. Change Password

All users can change their own password at any time.

1. Click **Change Password** in the sidebar.
2. Enter your **Current Password**.
3. Enter and confirm your **New Password**.
4. Click **Change Password**.

Password requirements:
- At least 8 characters
- At least one uppercase letter
- At least one digit (0–9)
- At least one special character (`!@#$%^&*` etc.)

A strength indicator shows how strong the new password is as you type.

---

## 12. Admin — Dashboard

The Dashboard is the administrator's home screen. It refreshes automatically every 60 seconds.

### KPI cards (top row)

| Card | Description |
|---|---|
| Active Users | Number of users with active accounts |
| Sites Checked Today | Total site checks recorded today across all users |
| Team Completion | Percentage of expected checks completed today |
| Unchecked Sites | Number of sites not yet checked today |

### Per-user progress table

Shows each active user with their checked count, total expected sites today, and
completion percentage. Completion is colour-coded:
- 🟢 Green — 100% complete
- 🟡 Amber — partially complete
- 🔴 Red — not started

Users with no shifts scheduled today are excluded from the table automatically.

---

## 13. Admin — Website Management

Navigate to **Websites** in the sidebar.

### Adding a website

1. Click **＋ Add Website**.
2. Fill in the required fields:

| Field | Description |
|---|---|
| Name * | Display name shown on user dashboards |
| URL * | Full web address (https:// will be added if omitted) |
| Check Type | Daily (shown every shift day) or Weekly (once per week) |
| Visibility | All Users or Assigned Only |
| Note | Optional note shown on the user's site card |

3. If **Assigned Only** is selected, a user assignment panel appears — tick the users who should see this site.
4. Optionally expand **🔑 Credentials** to add login credentials for the site.
5. Click **Save**.

### Credentials

Each website can have multiple credential sets (e.g. Admin login, Read-only login).
Each set has a **Label**, **Username**, and **Password**.
Passwords are stored encrypted and are only revealed when the user clicks 👁 in the credentials popup.

### Editing a website

Select a website in the list and click **✎ Edit**, or double-click the row.
All fields can be changed, including credentials.

### Deactivating / deleting a website

- **Deactivate** (recommended): Uncheck **Active** in the edit dialog. The site is hidden from
  users but historical check records are preserved.
- **Delete**: Select and click **✕ Delete**. This is permanent.

---

## 14. Admin — User Management

Navigate to **Users** in the sidebar.

### Adding a user

1. Click **＋ Add User**.
2. Fill in Username, Full Name, Role (Admin or User), and Password.
3. Click **Save**.

### Editing a user

Select a user and click **✎ Edit** or double-click. You can change their name,
role, active status, and set a new password.

### Resetting a password

1. Select a user and click **🔑 Reset Password**.
2. Confirm the prompt.
3. A secure dialog appears with a randomly generated 16-character temporary password.
4. Click **📋 Copy** to copy it to the clipboard (the clipboard is wiped after 30 seconds).
5. Share the temporary password with the user securely (e.g. by phone).
6. The dialog auto-closes after 120 seconds.
7. The user should change this password immediately after logging in.

**Notes:**
- You cannot reset your own password here — use Change Password in the sidebar.
- The last active administrator account cannot be deleted.

### Deactivating vs deleting

- **Deactivate** (is_active = off): The user cannot log in but their records are preserved.
- **Delete**: Permanent. Use deactivate first if you want to keep audit history.

---

## 15. Admin — Shift Management

Navigate to **Shifts** in the sidebar.

### What is a shift?

A shift defines which websites a group of users should check, on which days of the week,
and during which time window. A user can belong to multiple shifts.

### Adding a shift

1. Click **＋ New Shift**.
2. Fill in:

| Field | Description |
|---|---|
| Shift Name | e.g. "Morning Team", "Weekend Check" |
| Days of Week | Tick each day this shift runs |
| Start Time | When the shift begins (HH:MM) |
| End Time | When the shift ends — used for reminder notifications |
| Note | Optional internal note |

3. On the **Users** tab, tick the users assigned to this shift.
4. On the **Websites** tab, tick the websites this shift should check (drag to reorder).
5. Click **Save**.

### Show inactive shifts

By default, deactivated shifts are hidden. Tick **Show inactive** in the toolbar
to display them (shown in grey).

### Exporting shifts to PDF

Click **⬇ Export PDF** to generate a printable PDF showing all active shifts,
their assigned users, and their website lists.

---

## 16. Admin — Reports

Navigate to **Reports** in the sidebar. There are four tabs.

### Shift Detail

Shows every check-in for a specific user and date range.
Select a user, set a date range, and click **Generate**.
Export to CSV or Excel with the export buttons.

### Unchecked Sites

Shows websites that were NOT checked on a given date, scoped to each user's actual shift.
If no date is selected, defaults to today.
Filter by a specific user or view all users.

### Summary

Shows per-user per-day statistics: sites checked, total expected, and completion percentage.
Total is based on that user's actual shift assignment for that day — not a global site count.

### Completion Chart

A bar chart showing today's completion percentage per user.
Bars are colour-coded: green ≥ 100%, amber ≥ 50%, red < 50%.

---

## 17. Admin — Activity Log

Navigate to **Activity Log** in the sidebar.

The log shows every significant action taken in the system, including:
logins, logouts, session timeouts, account lockouts, all create/edit/delete operations,
password changes and resets, website checks, exports, email setting changes,
and AI criterion changes.

Each entry shows: timestamp, acting user, action type, affected record, and detail notes.

Use the search bar to filter by username, action type, or any text in the detail field.
Use the date range pickers to narrow the time window.

---

## 18. Admin — Email Report Settings

Open **Settings** (gear icon in sidebar) → **Email Report Settings**, or click the
email icon if visible.

### Configuration fields

| Field | Description |
|---|---|
| Enable daily emails | Master on/off switch |
| SMTP Host | Your mail server address |
| Security | STARTTLS (port 587), SSL/TLS (port 465), or None (port 25) |
| SMTP Port | Auto-filled when Security mode is selected; can be changed manually |
| SMTP Username | Usually your full email address |
| SMTP Password | For Gmail, use an App Password — not your Gmail password |
| Recipients | Comma-separated email addresses to receive the report |
| Send Time | HH:MM (24-hour) — the time the report is sent each day |

### Testing the connection

**🔌 Test Connection** runs a step-by-step diagnostic:

1. **DNS** — can the server name be resolved?
2. **TCP** — can a connection be made to the port?
3. **TLS** — does the TLS/security handshake succeed?
4. **Auth** — are the username and password accepted?

The status line reports exactly which step failed and what to check.

**📧 Send Test Email** sends a real test message to the configured recipients.
Use this to confirm full end-to-end delivery after the connection test passes.

### Common setups

**Office 365 / Exchange Online:**
- Security: STARTTLS
- Port: 587
- Username: full email address
- Password: your Microsoft account password or app password

**Gmail (Google Workspace):**
- Security: SSL / TLS
- Port: 465
- Username: full Gmail address
- Password: App Password (not your Gmail password)
  → Enable 2-Step Verification → myaccount.google.com/apppasswords

**Internal relay:**
- Security: None
- Port: 25
- Username/Password: may not be required

### What the daily report contains

The report email lists every active user who had shifts today, showing:
- Number of sites checked
- Total sites expected for their shift
- Completion percentage (colour-coded)

Users with no shift scheduled today are excluded, with a footnote showing the count.

---

## 19. Admin — AI Summary Settings

### Setting up the API key

1. Get a free API key at **https://console.groq.com** (no credit card required).
2. Open **🤖 AI Summary** in the sidebar.
3. Enter the API key in the **Groq API Key** field.
4. Select a model (see below).
5. Click **💾 Save Settings**.

The API key is stored encrypted on your machine and is never shared with other users.

### Available models

| Model | Best for |
|---|---|
| llama-3.3-70b-versatile | Best overall quality — recommended default |
| llama-3.1-8b-instant | Faster responses, slightly lower quality |
| gemma2-9b-it | Good alternative for shorter documents |
| mixtral-8x7b-32768 | Large context window for very long documents |

### Managing evaluation criteria

See §9 above for full details on adding, editing, and deleting criteria.

**Key points for admins:**
- Criteria are shared — all users' analyses use the same active criteria.
- Deactivating a criterion (unchecking Active) removes it from future AI prompts
  without deleting it — useful for temporarily suspending a criterion.
- The full description text is saved in the audit log each time a criterion is updated,
  so you can always reconstruct what the AI was evaluating against at any historical date.

---

## 20. Session Timeout

The application automatically signs you out after **30 minutes of inactivity**
(no mouse movement, key presses, or clicks).

One minute before timeout, a warning dialog appears. Click **Stay Signed In** to
reset the timer. If you don't respond, you are signed out and must log in again.
Any unsaved work is lost.

---

## 21. Keyboard Shortcuts

Available on the My Shift dashboard:

| Shortcut | Action |
|---|---|
| `Ctrl+F` | Focus the search box |
| `Ctrl+A` | Select all unchecked sites |
| `Ctrl+Enter` | Mark selected site as checked |
| `Space` | Toggle checkbox on focused site card |
| `Escape` | Clear search / deselect |

---

## 22. Troubleshooting

### I can't log in

- Check Caps Lock — passwords are case-sensitive.
- After 5 failed attempts, your account is locked for 15 minutes.
  Wait for the countdown to finish and try again.
- Contact your administrator if you need a password reset.

### My shift shows no sites

- You may not be assigned to any active shift scheduled for today.
- Contact your administrator to verify your shift assignment and the days-of-week setting.

### The health dot is always red for a site

- The site may block automated probes (returns 4xx — shown as amber, not red).
- A red dot means a network error — the server is not responding at all.
- Check your internet connection. If other sites are green, the specific site may be down.

### The AI analysis fails with "401"

- Your Groq API key is invalid or expired.
- Log in to https://console.groq.com, generate a new key, and update it in AI Summary settings.

### The AI analysis says "No readable text found"

- The PDF may be a scanned image rather than a text-based PDF.
- Try using a version of the document that is copy-pasteable, or a Word/Excel version.

### Email test fails at Step 3 (TLS)

- You are using the wrong security mode for your mail server.
- Try switching from STARTTLS to SSL/TLS (port 465) or vice versa.
- Contact your IT department to confirm the correct SMTP settings.

### Email test fails at Step 4 (Auth)

- For Gmail/Google Workspace: you must use an **App Password**, not your regular password.
  Go to myaccount.google.com/apppasswords to create one.
- For Office 365: your account may require Modern Authentication or an app password.
  Contact your IT department.

### I can't see the Evaluation Criteria panel

- The panel is present for all users but may be collapsed. Click **▼ Expand** to open it.

### My analysis history is empty

- History is only saved for analyses run after the feature was deployed.
  Earlier analyses are not retroactively added.
- Check that you are on the 🕑 History tab (not the ✨ Analyze tab).
- Click **↻ Refresh** to reload from the database.

### The app freezes during AI analysis

- The AI call runs in a background thread — the UI should remain responsive.
- If the app appears frozen, wait up to 60 seconds. Long documents take time to process.
- If it remains unresponsive, close and reopen the application. The analysis may have failed silently — check `app.log`.

---

*For technical issues not covered here, ask your system administrator to check `app.log`
in the application directory for detailed error messages.*