General source code refactoring

README.md

@@ -4,8 +4,16 @@ Browser extension that adds the "Opportunities Extension" shortcut to the permit
 
 ## Development Structure
 
-- `src/content.js`: single source file maintained by the project.
+- `src/content/`: page integration, modal shell, theme and content composition.
+- `src/background/`: synchronous message registration and background composition.
+- `src/features/`: opportunities, products, consumption, AI summaries, preferences and debug.
+- `src/auth/`: credential-specific selection, reuse and session recovery.
+- `src/services/`: Fusion/SPA operations and background HTTP/JSON transport.
+- `src/platform/`: narrow browser messaging, cookies, tabs and storage adapters.
+- `src/shared/messages.js`: names of the existing cross-context messages.
 - `scripts/build.mjs`: generates browser-specific packages.
+- `tests/`: isolated synthetic regression tests and a visual fixture.
+- `docs/`: architecture/contracts and incremental refactoring record.
 - `dist/chromium/`: output for Google Chrome and Microsoft Edge.
 - `dist/firefox/`: output for Firefox.
 
@@ -19,6 +27,41 @@ npm run build
 
 The build recreates `dist/chromium` and `dist/firefox` from the same source.
 
+Do not edit files under `dist` directly. Both targets use Manifest V3, with a
+Chromium service worker and Firefox background scripts. The build composes classic
+factory modules from `scripts/sources.cjs` into one isolated IIFE per execution
+context. It serializes `src/content/styles/redwood.css` at build time. There is no
+runtime module loader, browser-side eval, ES-module requirement or new dependency.
+
+## Tests and Maintenance
+
+```bash
+npm test
+npm run check
+```
+
+Tests use built-in Node.js modules and synthetic credentials, without real Fusion
+requests. The characterization suite verifies manifests, source/output equality,
+fiscal dates, payloads, preferences, pagination, cache/progress and both browser API
+styles. Architecture tests enforce source inclusion, explicit factory dependencies,
+isolated state and unchanged CSS. These complement consumption, session recovery
+and AI suites. `check` also fails if generated packages are stale.
+There is no separate lint configuration or runtime dependency installation.
+
+See [architecture and contracts](docs/architecture.md) and the
+[incremental refactoring record](docs/refactoring.md) for execution boundaries,
+authentication, storage, known risks and verification limits.
+Mock-based tests do not replace testing the installed extension in each browser.
+
+Without npm, run `node scripts/build.mjs`, `node scripts/test.cjs` and
+`node scripts/build.mjs --check`. Development checks were run with Node 24.19.0.
+
+For a local UI smoke test, run `node scripts/preview.mjs` and open the loopback URL
+printed by the command. The fixture uses synthetic opportunities, tokens, products,
+AI text and consumption; unexpected requests fail closed. It does not authenticate
+against Fusion or read real extension storage. `/consumption-trend.html` provides
+a focused chart fixture. Stop the server with Ctrl+C when finished.
+
 ## Release 1.0.0
 
 - Paginated opportunity retrieval with filters for reference, customer, owner, status, stage, and text search.
@@ -37,7 +80,7 @@ The build recreates `dist/chromium` and `dist/firefox` from the same source.
 
 ## Loading in Development Mode
 
-### Chrome ou Microsoft Edge
+### Chrome or Microsoft Edge
 
 1. Open `chrome://extensions` or `edge://extensions`.
 2. Enable Developer mode.