Strengthen export-based pilot workflow

.gitignore

@@ -4,3 +4,5 @@ dist
 .env
 .env.*
 !.env.example
+.local/
+AGENTS.md

README.md

@@ -63,7 +63,7 @@ The target end-user experience is:
 5. Review findings and decide whether each item is in scope or needs a change request.
 6. Export or share the review with sales, finance and delivery.
 
-The hosted pilot is live as a private early browser release. It is local-first: uploaded content is processed in the browser and the current pilot does not persist projects or decisions after a page reload. Contributors can run the local development surface below.
+The hosted pilot is live as a private early browser release. It is local-first: uploaded content is processed in the browser and the current pilot saves the active workspace on this device only. It does not provide shared team storage or sign-in yet. Contributors can run the local development surface below.
 
 ### 1. Clone and start the local app
 
@@ -89,11 +89,11 @@ http://127.0.0.1:5173/
 
 ### 2. Choose a project
 
-The current UI includes a small project switcher for the product surface. The active demo project is **Acme launch site**. The other project names are visual placeholders for the future multi-project workspace.
+The current UI uses one local project at a time. **New local project** clears the current device-local workspace and lets you name the next pilot project; shared multi-project workspaces are not enabled yet.
 
 ### 3. Add the source of truth
 
-Use **Add a source** to upload a scope document and communication export. The current supported formats are:
+Use **Add a source** to upload a scope document and communication export. You can remove a source or correct its classification before running the analysis. The current supported formats are:
 
 | Format | Typical use | Current support |
 | --- | --- | --- |
@@ -169,7 +169,7 @@ Click **Run analysis** after both source types are loaded. ScopeGuard then:
 - extracts bullet points from the scope source;
 - extracts messages from the communication source;
 - applies the configured rules;
-- calculates the current finding list, scope coverage, message count and estimated hours at risk.
+- calculates the current finding list, the share of messages with a scope basis, message count and preliminary exposure hours.
 
 The analysis is deterministic: the same source text and the same rules produce the same findings.
 
@@ -188,7 +188,7 @@ Use the filters to focus on **All findings**, **High risk** or **Unreviewed**. O
 
 ### 6. Decide what happens next
 
-Use **Mark in scope** when the request is genuinely covered by the agreement. Use **Create change request** when it needs clarification, a price, a new estimate or formal approval. The decision is currently held in the running app state; persistent project storage is part of the next technical slice.
+Use **Mark in scope** when the request is genuinely covered by the agreement. Use **Create change request** when it needs clarification, a price, a new estimate or formal approval. Decisions and notes are saved in this browser only; shared project storage is part of the next technical slice.
 
 ## The demo scenario
 
@@ -230,7 +230,7 @@ Example:
   pattern: "dashboard|partner portal|mobile app"
   titleStyle: subject_not_in_scope
   severity: high
-  confidence: 94
+  confidence: 94 # rule signal, not a measured probability
   minHours: 32
   maxHours: 40
   scopeTerms:
@@ -262,15 +262,15 @@ The intended operating habit is simple: review the queue before accepting new wo
 
 - Source files are parsed locally in the browser in this prototype.
 - No client content is sent to an external API by the current implementation.
-- The app does not yet save projects, uploaded files, review notes or decisions across a page reload. The “Saved locally” label is part of the current product surface, not a completed persistence layer.
+- The app saves the current project, uploaded files, review notes and decisions in versioned browser storage on this device. It is not a shared backend and should not be treated as team history or backup.
 - PDF and DOCX files are recognized but intentionally rejected until extraction adapters are added.
 - Direct Slack, Gmail and WhatsApp integrations are not implemented yet; export adapters are available and live pilot connectors are the next open-source slice. Facebook Messenger, additional mailbox providers, CRM and ERP integrations are not part of the open-source pilot.
 - The JSON parser supports common Telegram, Facebook Messenger and Slack-style arrays and objects with a `messages` array. It looks for fields such as `text`, `message`, `body` or `content`, including Telegram's array-of-text-fragments format.
 - WhatsApp text exports are treated as message sources when their filename includes `WhatsApp`, `chat` or a similar channel hint.
 - Scope extraction currently focuses on Markdown-style headings and bullet or numbered list items.
-- Rule matching is lexical and deterministic. It does not yet understand full contractual context, negation, speaker authority or conversation history.
-- “Scope coverage” is currently a simple prototype metric based on message count versus extracted scope-item count. It should not be interpreted as a percentage of contractual compliance.
-- The export button and project switcher are visual product-surface placeholders in this slice.
+- Rule matching is lexical and deterministic. The pilot now handles basic negation, sender role hints, included/excluded clauses, stable finding IDs and multiple rule matches, but it does not understand full contractual context or conversation history.
+- “With scope basis” is the share of parsed messages for which at least one configured rule found a related scope clause. It is not a percentage of contractual compliance.
+- Direct API integrations, shared workspaces and project switching remain outside this pilot slice.
 
 ## Technical shape
 
@@ -320,7 +320,7 @@ The next useful steps are:
 
 1. Add PDF and DOCX extraction adapters.
 2. Add rule-level tests with labelled scope-drift fixtures.
-3. Persist projects, sources, findings, notes and decisions in local SQLite or another explicit local store.
+3. Add shared authenticated workspaces and audit history; device-local persistence is already available for the pilot.
 4. Turn a `Change request` decision into an editable, exportable draft.
 5. Improve clause matching and conversation context.
 6. Add optional live OAuth/API connectors for Slack, Gmail and WhatsApp after the export-based pilot.

docs/implementation-notes.md

@@ -10,17 +10,20 @@ The current slice is a responsive React/Vite local-first review workspace, a det
 - Sources are normalized into `SourceDocument` records with a scope/messages/unknown kind and an explicit format.
 - TXT/MD, EML and common Telegram, WhatsApp, Facebook Messenger and Slack JSON exports are parsed locally in `src/analysis.ts`.
 - The analyzer runs deterministic rules for new deliverables, acceptance criteria, extra revisions and unpriced commitments.
-- Rule patterns, confidence, severity and hour ranges are configured in `src/rules.yaml` and parsed at build time.
-- “Run analysis” now recomputes findings, coverage, message count and hours at risk from the current sources.
+- Rule patterns, rule signal strength, severity and hour ranges are configured in `src/rules.yaml` and validated at build time.
+- “Run analysis” now recomputes findings, the percentage of messages with a scope basis, message count and preliminary exposure from the current sources.
 - PDF/DOCX are rejected with an explicit next-adapter message instead of pretending they were parsed. CSV/XLSX and CRM/ERP records are deferred to private add-ons; Slack/Gmail/WhatsApp connectors are the next open-source pilot slice.
 - Findings are explicitly evidence-backed and use “potential” language.
 - A reviewer can add a note, mark a finding in scope, create a change request decision, reopen it, and use the unreviewed filter as a queue.
 - A first-run onboarding tour explains the scope, source upload, analysis, evidence review, decisions and local-first privacy model. The tour can be skipped, replayed from the help button and navigated with the keyboard.
+- The current local workspace is persisted in browser storage under a versioned key, including sources, findings, analysis metrics, review notes and decisions. This is intentionally device-local and does not replace a shared backend.
+- Review reports and approved change requests can be exported as Markdown files without sending project data to an external service.
+- Pilot safeguards include a 10 MB source limit, required scope/message source validation, source reclassification and removal, stable finding IDs, basic negation and sender-role handling, included/excluded scope matching, and multipart email/plain-text Slack fallbacks.
 
 ## Next technical slice
 
 1. Add PDF/DOCX extraction adapters.
 2. Add rule-level tests against a labelled fixture set.
-3. Persist projects, sources, review decisions and findings in local SQLite.
-4. Turn the change-request decision into an editable/exportable draft.
-5. Build and test the open-source Slack, Gmail and WhatsApp pilot connectors.
+3. Add a shared server-side workspace and explicit authentication for team use.
+4. Turn the change-request export into an editable, provider-specific draft.
+5. Build and test live Slack, Gmail and WhatsApp connectors behind the approved privacy boundary.

docs/page-strategy.md

@@ -16,7 +16,7 @@ ScopeGuard is a local-first evidence review tool for small agencies. It compares
 
 - project context and saved-local status;
 - clear analysis state;
-- amount of scope coverage and hours at risk;
+- share of messages with a scope basis and preliminary exposure hours;
 - evidence list with filters for all, high risk and unreviewed;
 - source list with add/drop affordance;
 - local-first privacy reassurance;

docs/product-status.md

@@ -25,7 +25,7 @@ The product has two distinct surfaces:
 1. **Hosted user-facing app** — for finance, sales, account and delivery teams. It must work in a browser with a shared link, sign-in and no terminal usage.
 2. **Open-source repository** — for developers, contributors and technical operators who inspect, extend or self-host the core.
 
-Finance and sales users are not expected to use GitHub, Node.js or npm. The hosted browser pilot is now available at https://scopeguard.atvbox.chatgpt.site. The current release is private, local-first and intentionally limited: it does not yet persist projects, decisions or team history.
+Finance and sales users are not expected to use GitHub, Node.js or npm. The hosted browser pilot is now available at https://scopeguard.atvbox.chatgpt.site. The current release is private, local-first and intentionally limited: it persists the active workspace on the current device, but does not yet provide shared projects, authentication or team history.
 
 ## 2. How the current MVP works
 
@@ -100,7 +100,7 @@ Each finding contains:
 - source;
 - closest scope clause;
 - severity;
-- confidence;
+- rule signal strength;
 - estimated hours at risk.
 
 ### Human-in-the-loop review
@@ -204,7 +204,7 @@ This is the next commercial layer after the Slack/Gmail/WhatsApp pilot.
 
 - Direct Slack, Gmail and WhatsApp integrations are planned as the next open-source pilot slice; export adapters are already available.
 - Multi-user invites, persistent workspaces and team access controls.
-- Persistent project, source and review storage.
+- Shared persistent project, source and review storage.
 - Backend and authentication.
 - Persistent storage after a page reload.
 - Team collaboration.
@@ -216,7 +216,7 @@ This is the next commercial layer after the Slack/Gmail/WhatsApp pilot.
 - CRM/ERP functionality in the open-source repository.
 - Billing and enterprise controls.
 
-The current `Saved locally` label is part of the product surface; a complete persistence layer is not connected yet.
+The current `Saved on this device` label reflects versioned browser persistence. It is intentionally not a shared backend or a backup system.
 
 ## 8. Technical status
 

reports/browser-qa.md

@@ -40,7 +40,42 @@ Date: 2026-08-02
 
 ## Remaining prototype limitations
 
-- Export report, help, workspace switcher, account menu and new project are visual placeholders.
+- Shared workspace switching, account menus and team collaboration are intentionally outside the local pilot; export report, help and new local project are functional.
 - Uploaded source content and review decisions remain in React state and are not persisted across a page reload.
 - Direct Telegram, WhatsApp Business and Facebook Messenger integrations are not implemented; the current workflow uses exported files.
 - PDF/DOCX extraction adapters are still pending.
+# ScopeGuard browser QA
+
+Date: 2026-08-02
+
+## Scope
+
+- Route: `/`
+- Local URL: `http://127.0.0.1:4173/`
+- Desktop viewport: 1280 × 720
+- Mobile viewport: iPhone 13 emulation
+
+## Checks completed
+
+- Production build starts and serves the application.
+- Desktop render shows the workspace, evidence cards, source panel and onboarding tour.
+- Mobile render shows the responsive brand bar, breadcrumbs, action buttons and onboarding card without a blank page.
+- Initial demo workspace shows four findings.
+- Two source classification controls are present.
+- The onboarding tour can be skipped.
+- `Run analysis` completes and returns `Analysis complete`.
+- Console errors: none during the smoke test.
+- Source validation and source management are covered by unit tests; browser automation used the demo workspace for the smoke test.
+
+## Result
+
+PASS for the local pilot slice. The application is ready for a controlled export-based pilot, with the documented limitations that analysis remains deterministic and local, shared workspaces are not available, and PDF/DOCX extraction is not enabled.
+
+## Frontend pilot flow
+
+- Demo mode is visibly labelled and offers a direct path to an empty project.
+- A named local project can be created from the sidebar.
+- Two in-memory test files (scope TXT + Slack JSON) were uploaded through the real file input.
+- The source list showed both files, the status changed to `Ready to analyse`, and the analysis completed with one finding.
+- No console errors occurred during the full flow.
+- The onboarding dialog receives focus when opened and remains dismissible with `Escape`.