Add full project documentation, CI workflow, and acceptance checklist

Author: baboonzero

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run full test loop
+        run: npm run test:all
+
+      - name: Upload Playwright report (failure only)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report

README.markdown

@@ -0,0 +1,275 @@
+# Chrome Activity Reader - Complete Build Documentation
+
+Last updated: 2026-02-26
+Repository: https://github.com/baboonzero/chrome-activity-reader
+
+## 1. Project Intent
+
+Build a product that can:
+- Track activity across hundreds of Chrome tabs in multiple windows.
+- Show what the user worked on in time windows: 1 hour, 4 hours, 1 day, 1 week.
+- Let the user click an entry and jump back to that tab (or reopen if closed).
+- Keep all data local and private for MVP.
+
+Primary product decision:
+- Build as a **Chrome Extension (MV3)** instead of standalone web page or desktop-only app.
+
+## 2. What Was The Process?
+
+The process followed these phases:
+
+1. Problem framing and architecture analysis.
+2. Option comparison (extension vs web page vs desktop app).
+3. MVP boundary definition (tab-level time activity only).
+4. Design doc creation and implementation plan creation.
+5. Repository initialization and baseline commits.
+6. Extension scaffold implementation.
+7. Test harness setup (Playwright).
+8. Hardening loop (session engine extraction, runtime recovery, DB boundary controls).
+9. Unit + E2E test expansion.
+10. CI pipeline setup and manual acceptance assets.
+11. Final verification and push to GitHub.
+
+All implementation was done in iterative loops:
+- implement,
+- test,
+- fix,
+- re-test,
+- commit,
+- push.
+
+## 3. What Were The Actions That We Took?
+
+Chronological execution log:
+
+1. Created initial architecture/design artifacts:
+   - `docs/plans/2026-02-26-chrome-activity-reader-design.md`
+   - `docs/plans/2026-02-26-chrome-activity-reader-implementation-plan.md`
+
+2. Initialized Git repository and committed baseline documentation.
+
+3. Installed multi-agent/testing-support skills in local Codex skill directory:
+   - `swarm-planner`
+   - `parallel-task`
+   - `super-swarm`
+   - `playwright`
+
+4. Enabled multi-agent feature flag in local Codex config:
+   - `C:/Users/anshu/.codex/config.toml` -> `[features] multi_agents = true`
+
+5. Implemented extension MVP foundation:
+   - Manifest + service worker
+   - IndexedDB data layer
+   - Dashboard UI and settings UI
+   - Session tracking event handling
+
+6. Added Playwright E2E coverage for dashboard behavior.
+
+7. Added swarm-style execution tracker:
+   - `docs/plans/2026-02-26-swarm-execution-plan.md`
+
+8. Refactored session logic into pure engine module:
+   - `background/session-engine.js`
+
+9. Added runtime recovery mechanism:
+   - Persist active session runtime context to `chrome.storage.local`
+   - Rehydrate on service worker boot
+
+10. Hardened DB layer:
+    - Settings normalization and safe defaults
+    - Range guards
+    - Deterministic retention pruning
+
+11. Added unit tests:
+    - `tests/unit/session-engine.test.js`
+    - `tests/unit/db.test.js`
+
+12. Expanded E2E tests:
+    - Open existing tab vs reopen closed URL
+    - Settings action from dashboard
+
+13. Added manual acceptance assets:
+    - `docs/testing/manual-acceptance-checklist.md`
+    - `scripts/manual-acceptance.ps1`
+
+14. Added GitHub Actions CI:
+    - `.github/workflows/ci.yml`
+    - Runs `npm run test:all` on push/PR.
+
+15. Repeated full verification:
+    - `npm run test:unit`
+    - `npm run test:e2e`
+    - `npm run test:all`
+
+16. Pushed final state to GitHub `main`.
+
+## 4. What Were The Decisions That We Took?
+
+### Product/Architecture Decisions
+
+1. **Platform:** Chrome extension (MV3) as core product.
+2. **MVP tracking scope:** Tab-level activity only (no in-page click/scroll/input capture).
+3. **Data storage:** IndexedDB for sessions/settings/snapshots.
+4. **Retention default:** 30 days.
+5. **Privacy stance:** Local-only storage; no cloud sync in MVP.
+6. **UI model:** Extension dashboard + settings page.
+
+### Engineering Decisions
+
+1. Extract pure session transition logic into `background/session-engine.js`.
+2. Persist runtime session state for service worker restart resilience.
+3. Add separate unit tests for pure logic plus Playwright E2E for behavior.
+4. Add CI pipeline to run full verification on pushes/PRs.
+5. Add manual acceptance checklist/script for real Chrome validation.
+
+## 5. What Did We Start By Building?
+
+First implementation slice:
+
+1. `manifest.json` with MV3 service worker and permissions.
+2. `background/service-worker.js` with event listeners for tabs/windows/idle/alarms.
+3. `shared/db.js` for IndexedDB stores and session/settings persistence.
+4. Dashboard + Settings pages:
+   - `ui/dashboard.html`, `ui/dashboard.js`, `ui/dashboard.css`
+   - `ui/settings.html`, `ui/settings.js`
+
+This delivered a runnable end-to-end MVP skeleton quickly.
+
+## 6. What Have We Built?
+
+### Core Functionality
+
+- Active-tab session tracking across windows.
+- Session end reasons (`tab_switch`, `window_blur`, `tab_closed`, `idle`, `lock`, etc.).
+- Dashboard timeline with:
+  - 1h / 4h / 1d / 7d filters
+  - search by title/domain/url
+  - click-to-focus existing tab
+  - fallback open URL if tab is closed
+- Settings:
+  - pause tracking
+  - excluded domains
+  - retention display (30 days default)
+
+### Reliability and Hardening
+
+- Debounce protection for rapid repeated transitions.
+- Runtime active-session persistence + recovery on worker restart.
+- Deterministic settings normalization and DB range handling.
+- Retention cleanup alarm and pruning logic.
+
+### Testing
+
+- Unit tests for session engine and DB boundaries.
+- Playwright E2E tests for timeline and action flows.
+- Combined test command (`npm run test:all`).
+
+### Tooling/Operations
+
+- `.gitignore`
+- npm-based project scripts
+- GitHub Actions CI workflow
+- Manual acceptance checklist + helper script
+
+## 7. What Have We Not Built?
+
+Not in MVP (intentionally out of scope):
+
+1. In-page behavior tracking (clicks, typing, scroll, content snapshots).
+2. Cloud sync/account/multi-device history.
+3. Cross-browser support (Edge/Firefox/Safari).
+4. Advanced analytics (project clusters, AI summaries, semantic categorization).
+5. Side panel UI (only dashboard/options pages currently).
+6. Packaging/publishing flow for Chrome Web Store.
+7. Formal migration/versioning strategy for future DB schema upgrades.
+
+## 8. Current Status
+
+### Delivery Status
+
+- MVP implementation: **complete**
+- Hardening loop: **complete**
+- Automated tests: **green**
+- CI workflow: **configured**
+- Manual acceptance assets: **present**
+- Repo pushed to GitHub: **yes**
+
+### Quality Status
+
+- `npm run test:unit`: passing
+- `npm run test:e2e`: passing
+- `npm run test:all`: passing
+
+### Branch/History Status
+
+Primary commits:
+- `249bc7c` Initialize project with approved MVP design and implementation plan
+- `0f2e6fc` Build MV3 Chrome Activity Reader MVP scaffold
+- `b1db2c7` Add Playwright test loop for dashboard behavior
+- `4fb4594` Complete MVP hardening, recovery, and full test loop
+
+## 9. File-Level Map Of What Exists
+
+### Product
+
+- `manifest.json`
+- `background/service-worker.js`
+- `background/session-engine.js`
+- `shared/db.js`
+- `shared/time.js`
+- `shared/url.js`
+- `ui/dashboard.html`
+- `ui/dashboard.js`
+- `ui/dashboard.css`
+- `ui/settings.html`
+- `ui/settings.js`
+
+### Tests
+
+- `tests/unit/session-engine.test.js`
+- `tests/unit/db.test.js`
+- `tests/e2e/dashboard.spec.js`
+- `playwright.config.mjs`
+
+### Documentation and Planning
+
+- `README.md` (quick start)
+- `README.markdown` (this full build document)
+- `docs/APPROACH_AND_PLAN.md`
+- `docs/plans/2026-02-26-chrome-activity-reader-design.md`
+- `docs/plans/2026-02-26-chrome-activity-reader-implementation-plan.md`
+- `docs/plans/2026-02-26-swarm-execution-plan.md`
+- `docs/testing/manual-acceptance-checklist.md`
+
+### Operations
+
+- `.github/workflows/ci.yml`
+- `scripts/manual-acceptance.ps1`
+- `package.json`
+- `package-lock.json`
+- `.gitignore`
+
+## 10. How To Validate Right Now
+
+1. Install dependencies:
+   - `npm install`
+2. Run full test loop:
+   - `npm run test:all`
+3. Load extension in Chrome:
+   - `chrome://extensions` -> Load unpacked -> project root
+4. Run manual acceptance helper:
+   - `pwsh ./scripts/manual-acceptance.ps1 -RunAutomatedTests`
+5. Walk through checklist:
+   - `docs/testing/manual-acceptance-checklist.md`
+
+## 11. Summary
+
+This project has moved from concept to a tested MVP with:
+- complete tab-level activity tracking,
+- timeline navigation UX,
+- privacy-first local storage,
+- hardening for service-worker lifecycle behavior,
+- automated and manual verification paths,
+- CI on GitHub.
+
+The current codebase is production-ready for MVP-level internal use and ready for the next phase (publishing hardening, side panel UX, and optional richer activity intelligence).

README.md

@@ -2,6 +2,9 @@
 
 Chrome extension MVP that tracks tab-level activity and shows what you worked on over the last 1 hour, 4 hours, 1 day, and 7 days.
 
+For complete project history, architecture decisions, execution timeline, built/not-built scope, and current status, see:
+- `README.markdown`
+
 ## MVP Features
 
 - Tracks active tab sessions across Chrome windows.