docs: capture architectural knowledge (design-principles + Architecture-Internals)

[vringar]

Summary

Externalizes architectural knowledge that previously lived only in the maintainer's head into reviewable, portable repo documentation. Content was gathered in a structured interview and is organized for progressive disclosure: AGENTS.md stays a lean router (loaded on every agent invocation), with depth in linked RST docs (loaded only when followed).

docs/design-principles.rst (new)

The why behind the codebase, each entry with rule + reasoning + worked example:

• Trust model — websites are hostile; researcher command code is trusted-but-unstable; the browser/extension is trusted-but-unreliable.
• Core principles — treat web content as hostile; resist detection by crawled sites; never drop data / fail loudly on misconfiguration; be robust to misbehaving commands; reduce coupling between components.
• Non-goals — migrating to MV3 / non-Firefox (incl. the callstack-instrument rationale for the Firefox lock-in); bit-for-bit reproducible crawls.
• Working norms — keep known-broken-but-aspirational code as a reference; preserve functionality across Firefox upgrades.

docs/Architecture-Internals.rst (converted from Markdown)

RST conversion enables Sphinx cross-reference roles (:py:class:, :py:meth:) that deep-link into the autogenerated API docs. Adds:

• Design Rationale — why StorageController is a separate process, why the extension talks to it directly, the mp.Queue-vs-socket rule, the file-based startup handshake, and the privileged-socket history.
• Implications for Custom Commands — the multi-process footgun (writing to a main-process object from a BrowserManager subprocess) and the correct patterns.

Also fixes a stale method name and a malformed table.

docs/index.rst, AGENTS.md

Both new pages wired into the developer-doc toctree (Architecture-Internals was previously orphaned). AGENTS.md gets lean pointers into the deep docs plus short notes on testing philosophy, the SQLAlchemy schema-SSOT direction (#1161), the keep-known-broken-code norm, and project governance.

Test plan

• python -m sphinx -b html docs docs/_build/html — builds; every :py:/:doc: cross-reference in the new RST docs resolves (no reference target not found warnings from them).
• pre-commit run clean.
• Reviewer: skim rendered pages; confirm API deep-links land on the right symbols.

Notes

• design-principles.rst is a living document, intended to grow.
• Pre-existing ref.any warnings from other Markdown docs (recommonmark not resolving relative file links) are unrelated to this change.

[Copilot]

Pull request overview

Adds developer documentation for OpenWPM design principles, starting with guidance to treat web content as hostile and prefer privileged communication paths.

Changes:

• Adds docs/design-principles.rst with rationale, consequences, and a worked example.
• Adds the new page to the developer documentation toctree.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/index.rst	Adds the design principles page to developer docs navigation.
docs/design-principles.rst	Introduces the new design principles documentation page.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 62.34%. Comparing base (25a7827) to head (b9f7bc5).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1175      +/-   ##
==========================================
- Coverage   62.36%   62.34%   -0.03%     
==========================================
  Files          40       40              
  Lines        3930     3930              
==========================================
- Hits         2451     2450       -1     
- Misses       1479     1480       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.