ForageFacebook 2.0.0__tar.gz → 2.2.0__tar.gz

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/.github/dependabot.yml

@@ -4,6 +4,11 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      dependencies:
+        patterns: ["*"]
     open-pull-requests-limit: 5
     labels:
       - "dependencies"
@@ -12,6 +17,11 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    cooldown:
+      default-days: 7
+    groups:
+      dependencies:
+        patterns: ["*"]
     open-pull-requests-limit: 5
     labels:
       - "dependencies"

foragefacebook-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+---
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_type != 'tag' }}
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0
+        with:
+          version: "0.12.17"
+          python-version: "3.14"
+      - run: uv sync --locked --all-extras --no-config
+      - name: Check source and lockfile
+        run: |
+          uv lock --check --no-config
+          uv run --locked --no-config ruff check src/ scripts/
+          uv run --locked --no-config ruff format --check src/ scripts/
+          uv run --locked --no-config ty check src/forage/
+      - name: Audit workflows and release helper
+        run: |
+          go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
+          uvx --no-config zizmor==1.30.1 --no-progress .github/workflows
+          shellcheck scripts/release.sh
+          go run mvdan.cc/sh/v3/cmd/shfmt@v3.14.1 -i 2 -d scripts/release.sh
+      - name: Build and install wheel
+        run: |
+          uv build --no-config
+          uv venv /tmp/forage-install-smoke
+          uv pip install --no-config --python /tmp/forage-install-smoke/bin/python dist/*.whl
+          /tmp/forage-install-smoke/bin/forage --version
+          /tmp/forage-install-smoke/bin/forage --help
+
+  check:
+    if: always()
+    needs: [quality]
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Require all checks
+        env:
+          QUALITY_RESULT: ${{ needs.quality.result }}
+        run: test "$QUALITY_RESULT" = success

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/.github/workflows/publish.yml

@@ -1,3 +1,4 @@
+---
 name: Publish to PyPI
 
 on:
@@ -13,34 +14,50 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
+  checks:
+    # actionlint 1.7.12 does not yet parse the new $/ syntax. This resolves the same commit.
+    uses: ./.github/workflows/ci.yml  # zizmor: ignore[self-repository]
   build:
+    needs: checks
+    timeout-minutes: 10
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0
         with:
           enable-cache: false
+          version: "0.12.17"
+          python-version: "3.14"
 
-      - name: Set up Python
-        run: uv python install 3.12
+      - name: Verify release version
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          uv run --no-project --no-config python -c 'import os, tomllib; from pathlib import Path; version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]; assert os.environ["RELEASE_TAG"] == "v" + version, "tag/package version mismatch"'
 
       - name: Build package
-        run: uv build
+        run: uv build --no-config
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
           name: dist
           path: dist/
 
   publish-test-pypi:
     needs: build
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     if: github.event_name == 'workflow_dispatch' && github.event.inputs.test_pypi == 'true'
 
@@ -53,18 +70,19 @@ jobs:
 
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
           name: dist
           path: dist/
 
       - name: Publish to Test PyPI
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
         with:
           repository-url: https://test.pypi.org/legacy/
 
   publish-pypi:
     needs: build
+    timeout-minutes: 10
     runs-on: ubuntu-latest
     if: github.event_name == 'release'
 
@@ -77,10 +95,10 @@ jobs:
 
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
         with:
           name: dist
           path: dist/
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/.gitignore

@@ -60,3 +60,8 @@ output/
 .env
 .env.local
 .env.*.local
+
+# CLI end-to-end runner
+/node_modules/
+/.e2e/
+!package-lock.json

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/AGENTS.md

@@ -12,11 +12,10 @@ Forage is a CLI tool for scraping private Facebook groups to analyze community d
 uv sync                              # Install deps (always use uv, not pip/python)
 uv run forage --help                 # Run CLI
 uv run ty check src/                 # Type check (Astral's ty)
-uv run pytest                        # Run all tests
-uv run pytest tests/test_parser.py   # Run a single test file
-uv run pytest -k "test_name"         # Run a single test by name
-uv run ruff check src/ tests/        # Lint
-uv run ruff format src/ tests/       # Auto-format (CI enforces this)
+make check                           # Lint, type check, and build
+make test                            # Read-only live Facebook checks
+uv run ruff check src/ scripts/       # Lint
+uv run ruff format src/ scripts/      # Format
 ```
 
 ## Manual Testing
@@ -59,7 +58,10 @@ Random viewport sizes, `human_delay()` with variance, real Chromium browser, ses
 
 ### Test Structure
 
-Tests in `tests/` with HTML fixtures in `tests/fixtures/` (realistic Facebook HTML snippets). `conftest.py` provides `create_mock_element()` for creating mock Playwright `ElementHandle` objects from HTML strings.
+Use `make test` for real CLI reads through the saved Facebook session. Install Chromium first.
+Set `FORAGE_E2E_GROUP` to test a group; otherwise the test searches Marketplace for computers.
+Keep unit tests, mock tests, and fake-server suites out of this repo. CI runs static checks and package builds.
+Live tests must not log in, change credentials, or write to Facebook.
 
 ## Fragile Code — Check Here First When Things Break
 
@@ -99,9 +101,9 @@ Steps:
 1. Update `version` in both `pyproject.toml` and `src/forage/__init__.py`
 2. Run `uv lock --no-config` — refresh locked editable package metadata without leaking user-level uv settings
 3. Update `CHANGELOG.md` — add version section under `## [Unreleased]`, update comparison links at bottom
-4. Run `uv lock --check --no-config` and `uv run ruff format src/ tests/` — CI enforces formatting
+4. Run `uv lock --check --no-config` and `uv run ruff format src/ scripts/` — CI enforces formatting
 5. Commit: `git commit -m "chore: release vX.Y.Z"`
-6. Push: `git push origin master`
+6. Push a feature branch and open a PR. Merge only after all required checks pass. Never push directly to `master`.
 7. Tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"` then `git push origin vX.Y.Z`
 8. Create GitHub release: `gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."`
    — This triggers `.github/workflows/publish.yml` which publishes to PyPI via OIDC (no tokens)

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-10
+
+### Changed
+
+- Replace unit and synthetic browser tests with read-only live CLI checks.
+- Keep lint, type checks, and package build/install checks in CI.
+- Remove pytest and the Node test harness.
+- Add common `make check`, `make test`, and `make build` entry points.
+- Add `forage version` beside the existing `--version` flag.
+
+## [2.1.0] - 2026-09-20
+
+### Fixed
+
+- Preserve native comment IDs and scope fallback IDs to their post to prevent SQLite collisions.
+- Preserve full visible post text, expand supported “See more” controls, and exclude nested comments.
+- Parse compact comment counts and retain query-based post permalinks.
+- Include the full `--until` day, reject invalid date ranges before login, and preserve “Yesterday” clock times.
+- Report missing feeds and Marketplace authentication failures instead of misleading empty results or timeouts.
+- Bind Marketplace coordinates to the requested listing ID; exclude unbound locations.
+- Skip full parsing for group posts whose reliable permalink ID is already present.
+- Count accepted Marketplace listings toward `--limit`; keep a separate `--max-candidates` cost bound.
+- Store session directories and authentication state with owner-only POSIX permissions.
+- Reject missing CSV/SQLite output arguments before browser work.
+
+### Added
+
+- JSON collection diagnostics and explicit content/comment completeness indicators.
+- `forage doctor` for local setup checks without Facebook access.
+- `forage export` to reuse existing exporters with saved group JSON.
+- Network-blocked Chromium regression tests and a documented capability contract.
+
+
 ## [2.0.0] - 2026-08-29
 
 ### Added
@@ -214,7 +247,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Sensitive files excluded via `.gitignore`
 - Security guidelines in SECURITY.md
 
-[Unreleased]: https://github.com/jwmoss/forage/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/jwmoss/forage/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/jwmoss/forage/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/jwmoss/forage/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/jwmoss/forage/compare/v1.2.1...v2.0.0
 [1.2.1]: https://github.com/jwmoss/forage/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/jwmoss/forage/compare/v1.1.0...v1.2.0

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/CONTRIBUTING.md

@@ -22,7 +22,8 @@ Thank you for your interest in contributing to Forage!
 
 4. Run tests:
    ```bash
-   uv run pytest tests/ -v
+   make check
+   make test
    ```
 
 5. Run type checker:
@@ -55,15 +56,16 @@ Example: `feat: add SQLite export option`
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feat/my-feature`)
 3. Make your changes
-4. Ensure tests pass (`uv run pytest tests/`)
+4. Ensure tests pass (`make check`; run `make test` with a saved session)
 5. Ensure type checking passes (`uv run ty check src/forage/`)
 6. Commit with a descriptive message
 7. Push and open a pull request
 
 ## Testing
 
-- Write tests for new functionality
-- Use pytest fixtures for common test data
+- Verify behavior through the real CLI against Facebook.
+- Keep live checks read-only and use the existing session.
+- Do not add unit tests, mock tests, or fake-server suites.
 - Mock external dependencies (Playwright, network)
 - Aim for good coverage of edge cases
 

foragefacebook-2.2.0/Makefile

@@ -0,0 +1,14 @@
+.PHONY: check test build
+
+check:
+	uv lock --check --no-config
+	uv run --locked --no-config ruff check src/ scripts/
+	uv run --locked --no-config ruff format --check src/ scripts/
+	uv run --locked --no-config ty check src/forage/
+	uv build --no-config
+
+test:
+	uv run --locked --no-config python scripts/live-e2e.py
+
+build:
+	uv build --no-config

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ForageFacebook
-Version: 2.0.0
+Version: 2.2.0
 Summary: CLI tool to scrape posts, comments, and reactions from private Facebook groups
 Project-URL: Homepage, https://github.com/jwmoss/forage
 Project-URL: Repository, https://github.com/jwmoss/forage
@@ -28,7 +28,6 @@ Requires-Dist: playwright>=1.40
 Requires-Dist: pydantic>=2.0
 Requires-Dist: rich>=13.0
 Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.8; extra == 'dev'
 Requires-Dist: ty>=0.0.1a6; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -38,7 +37,9 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/jwmoss/forage/actions/workflows/ci.yml/badge.svg)](https://github.com/jwmoss/forage/actions/workflows/ci.yml)
 [![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](LICENSE)
 
-CLI tool to scrape posts, comments, and reactions from private Facebook groups using browser automation.
+CLI tool to collect Facebook group posts and search Marketplace electronics through browser automation.
+
+Forage uses browser pages, not a public REST API. Results are partial observations. See the [capability contract](docs/capabilities.md).
 
 ## Table of Contents
 
@@ -124,7 +125,7 @@ uv run forage scrape your-group-slug --min-reactions 5
 uv run forage scrape your-group-slug --top-comments 10
 
 # Watch the browser (debugging)
-uv run forage scrape your-group-slug --no-headless -v
+uv run forage -v scrape your-group-slug --no-headless
 
 # Slower scraping to avoid rate limits
 uv run forage scrape your-group-slug --delay 5.0
@@ -148,6 +149,9 @@ Global Flags:
 Commands:
   login           Open browser for interactive Facebook login
   scrape          Scrape posts from a Facebook group
+  marketplace     Search Marketplace electronics
+  doctor          Check local browser and session setup
+  export          Convert saved group JSON without Facebook access
 ```
 
 #### scrape flags
@@ -156,7 +160,7 @@ Commands:
 |------|---------|-------------|
 | `--days` | `7` | Posts from last N days |
 | `--since` | - | Start date (ISO 8601: YYYY-MM-DD) |
-| `--until` | - | End date (ISO 8601: YYYY-MM-DD) |
+| `--until` | - | Inclusive end date (YYYY-MM-DD), in the local timezone |
 | `--limit` | `0` | Max posts (0 = unlimited) |
 | `--delay` | `2.0` | Seconds between page loads |
 | `--min-reactions` | `0` | Min reactions for comments |
@@ -169,6 +173,46 @@ Commands:
 | `--no-headless` | `false` | Show browser window |
 | `--browser` | `chromium` | Browser: chromium, firefox, webkit |
 
+### Marketplace search
+
+```bash
+uv run forage marketplace "rtx 4070" --city wilmington --radius 40 --limit 20 -o listings.json
+```
+
+`--limit` counts accepted listings. `--max-candidates` bounds the search cost, including rejected candidates; its default is 200.
+Forage excludes distant listings and listings whose coordinates it cannot verify. City is the search center, not a city-only filter.
+The current parser supports electronics with dollar prices or “Free” labels. Search relevance follows Facebook's results.
+
+### Local diagnosis and saved exports
+
+```bash
+# Check browser installation and session permissions without contacting Facebook
+uv run forage doctor
+
+# Convert an existing group result without another scrape or login
+uv run forage export posts.json --format sqlite --output posts.db
+uv run forage export posts.json --format csv --output posts.csv
+uv run forage export posts.json --format llm --output compact.json
+```
+
+`doctor` checks local files. It does not prove that a session remains valid. Install the selected browser before login:
+
+```bash
+uv run playwright install chromium
+# For --browser firefox or webkit, install that browser instead.
+```
+
+JSON and LLM JSON include collection diagnostics: stop reason, candidate count, rejected count, parse failures, and unknown timestamps.
+`partial: true` means the scraper cannot prove exhaustive coverage. A verified empty-page message produces `stop_reason: "empty"`.
+`content_truncated` identifies an unexpanded post. `comments_complete: false` means comment coverage is unverified.
+Keep the original JSON if you need these diagnostics beside CSV or SQLite output.
+
+Dates use the local system and browser timezone. `--until` includes the entire selected day. Reversed dates fail before login.
+The scraper retains posts with unknown timestamps and reports their count.
+
+Exit codes: `0` for a completed command, `1` for collection or output errors, `2` for invalid arguments,
+`3` for required authentication, and `4` for a recognized unavailable group. Empty results alone do not prove an empty group.
+
 ### SQLite Export
 
 Export directly to SQLite for easier analysis:
@@ -274,10 +318,23 @@ uv sync --extra dev
 # Run type checker
 uv run ty check src/
 
-# Run tests
-uv run pytest
+# Run static checks and build the package
+make check
+
+# Install Chromium for live reads
+uv run playwright install chromium
+
+# Read Marketplace through the saved Facebook session
+make test
+
+# Read one post from a group you can access
+FORAGE_E2E_GROUP=your-group-slug make test
 ```
 
+Live tests run the real CLI and Facebook pages. They do not use fixtures or mock servers.
+They need an existing login session. CI runs static checks and package build/install checks.
+
+
 ## Architecture
 
 ```
@@ -295,29 +352,14 @@ src/forage/
 - Facebook's HTML structure changes frequently
 - Rate limiting may require slower scraping
 - Individual reaction types not broken out (only total)
-- Session cookies expire after ~30 days
+- Session lifetime depends on Facebook; use `forage login` when authentication fails
+- English page labels define the supported parser scope
+- Previously overwritten SQLite comments require a new scrape; upgrades cannot recover them
 
 ## Roadmap
 
-Planned features and improvements:
-
-### High Priority
-- [ ] **Cookie import** - Import cookies from browser extensions (EditThisCookie, Netscape format)
-- [ ] **Incremental scraping** - Only fetch posts newer than last scrape
-- [ ] **Progress persistence** - Resume interrupted scrapes
-
-### Medium Priority
-- [ ] **Multiple groups** - Scrape multiple groups in one command
-- [ ] **Media extraction** - Download images/videos from posts
-- [ ] **Reaction breakdown** - Extract individual reaction types (like, love, etc.)
-- [ ] **Author statistics** - Aggregate stats per author
-- [ ] **Scheduled scraping** - Cron-friendly mode with locking
-
-### Nice to Have
-- [ ] **Web UI** - Local web interface for browsing scraped data
-- [ ] **Webhook notifications** - Notify on new posts matching criteria
-- [ ] **Public group support** - Scrape without login for public groups
-- [ ] **Parallel scraping** - Speed up multi-group scrapes
+Prioritize sanitized DOM fixtures and verified selector updates. Add incremental collection only after identity and completeness checks support it.
+Use shell loops for batches, system scheduling for recurring commands, and SQLite or jq for analysis.
 
 ### Contributing
 

{foragefacebook-2.0.0 → foragefacebook-2.2.0}/README.md

@@ -3,7 +3,9 @@
 [![CI](https://github.com/jwmoss/forage/actions/workflows/ci.yml/badge.svg)](https://github.com/jwmoss/forage/actions/workflows/ci.yml)
 [![License: MPL 2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](LICENSE)
 
-CLI tool to scrape posts, comments, and reactions from private Facebook groups using browser automation.
+CLI tool to collect Facebook group posts and search Marketplace electronics through browser automation.
+
+Forage uses browser pages, not a public REST API. Results are partial observations. See the [capability contract](docs/capabilities.md).
 
 ## Table of Contents
 
@@ -89,7 +91,7 @@ uv run forage scrape your-group-slug --min-reactions 5
 uv run forage scrape your-group-slug --top-comments 10
 
 # Watch the browser (debugging)
-uv run forage scrape your-group-slug --no-headless -v
+uv run forage -v scrape your-group-slug --no-headless
 
 # Slower scraping to avoid rate limits
 uv run forage scrape your-group-slug --delay 5.0
@@ -113,6 +115,9 @@ Global Flags:
 Commands:
   login           Open browser for interactive Facebook login
   scrape          Scrape posts from a Facebook group
+  marketplace     Search Marketplace electronics
+  doctor          Check local browser and session setup
+  export          Convert saved group JSON without Facebook access
 ```
 
 #### scrape flags
@@ -121,7 +126,7 @@ Commands:
 |------|---------|-------------|
 | `--days` | `7` | Posts from last N days |
 | `--since` | - | Start date (ISO 8601: YYYY-MM-DD) |
-| `--until` | - | End date (ISO 8601: YYYY-MM-DD) |
+| `--until` | - | Inclusive end date (YYYY-MM-DD), in the local timezone |
 | `--limit` | `0` | Max posts (0 = unlimited) |
 | `--delay` | `2.0` | Seconds between page loads |
 | `--min-reactions` | `0` | Min reactions for comments |
@@ -134,6 +139,46 @@ Commands:
 | `--no-headless` | `false` | Show browser window |
 | `--browser` | `chromium` | Browser: chromium, firefox, webkit |
 
+### Marketplace search
+
+```bash
+uv run forage marketplace "rtx 4070" --city wilmington --radius 40 --limit 20 -o listings.json
+```
+
+`--limit` counts accepted listings. `--max-candidates` bounds the search cost, including rejected candidates; its default is 200.
+Forage excludes distant listings and listings whose coordinates it cannot verify. City is the search center, not a city-only filter.
+The current parser supports electronics with dollar prices or “Free” labels. Search relevance follows Facebook's results.
+
+### Local diagnosis and saved exports
+
+```bash
+# Check browser installation and session permissions without contacting Facebook
+uv run forage doctor
+
+# Convert an existing group result without another scrape or login
+uv run forage export posts.json --format sqlite --output posts.db
+uv run forage export posts.json --format csv --output posts.csv
+uv run forage export posts.json --format llm --output compact.json
+```
+
+`doctor` checks local files. It does not prove that a session remains valid. Install the selected browser before login:
+
+```bash
+uv run playwright install chromium
+# For --browser firefox or webkit, install that browser instead.
+```
+
+JSON and LLM JSON include collection diagnostics: stop reason, candidate count, rejected count, parse failures, and unknown timestamps.
+`partial: true` means the scraper cannot prove exhaustive coverage. A verified empty-page message produces `stop_reason: "empty"`.
+`content_truncated` identifies an unexpanded post. `comments_complete: false` means comment coverage is unverified.
+Keep the original JSON if you need these diagnostics beside CSV or SQLite output.
+
+Dates use the local system and browser timezone. `--until` includes the entire selected day. Reversed dates fail before login.
+The scraper retains posts with unknown timestamps and reports their count.
+
+Exit codes: `0` for a completed command, `1` for collection or output errors, `2` for invalid arguments,
+`3` for required authentication, and `4` for a recognized unavailable group. Empty results alone do not prove an empty group.
+
 ### SQLite Export
 
 Export directly to SQLite for easier analysis:
@@ -239,10 +284,23 @@ uv sync --extra dev
 # Run type checker
 uv run ty check src/
 
-# Run tests
-uv run pytest
+# Run static checks and build the package
+make check
+
+# Install Chromium for live reads
+uv run playwright install chromium
+
+# Read Marketplace through the saved Facebook session
+make test
+
+# Read one post from a group you can access
+FORAGE_E2E_GROUP=your-group-slug make test
 ```
 
+Live tests run the real CLI and Facebook pages. They do not use fixtures or mock servers.
+They need an existing login session. CI runs static checks and package build/install checks.
+
+
 ## Architecture
 
 ```
@@ -260,29 +318,14 @@ src/forage/
 - Facebook's HTML structure changes frequently
 - Rate limiting may require slower scraping
 - Individual reaction types not broken out (only total)
-- Session cookies expire after ~30 days
+- Session lifetime depends on Facebook; use `forage login` when authentication fails
+- English page labels define the supported parser scope
+- Previously overwritten SQLite comments require a new scrape; upgrades cannot recover them
 
 ## Roadmap
 
-Planned features and improvements:
-
-### High Priority
-- [ ] **Cookie import** - Import cookies from browser extensions (EditThisCookie, Netscape format)
-- [ ] **Incremental scraping** - Only fetch posts newer than last scrape
-- [ ] **Progress persistence** - Resume interrupted scrapes
-
-### Medium Priority
-- [ ] **Multiple groups** - Scrape multiple groups in one command
-- [ ] **Media extraction** - Download images/videos from posts
-- [ ] **Reaction breakdown** - Extract individual reaction types (like, love, etc.)
-- [ ] **Author statistics** - Aggregate stats per author
-- [ ] **Scheduled scraping** - Cron-friendly mode with locking
-
-### Nice to Have
-- [ ] **Web UI** - Local web interface for browsing scraped data
-- [ ] **Webhook notifications** - Notify on new posts matching criteria
-- [ ] **Public group support** - Scrape without login for public groups
-- [ ] **Parallel scraping** - Speed up multi-group scrapes
+Prioritize sanitized DOM fixtures and verified selector updates. Add incremental collection only after identity and completeness checks support it.
+Use shell loops for batches, system scheduling for recurring commands, and SQLite or jq for analysis.
 
 ### Contributing