docs: plugin architecture — data sovereignty and download-then-display contract

[jschloman]

Summary

Replaces the brief "Plugin System" section in the README with a full Plugin Architecture chapter that establishes the two foundational design principles for all current and future source plugins.

Principle 1 — Data Sovereignty

Each SourcePlugin is the sole authority over its own data. It has no knowledge of other sources, their schemas, or how its output will be joined or merged. All cross-source logic (temporal joins, geographic enrichment, correlation) lives exclusively in DataBroker. This contract is illustrated with an ASCII diagram showing plugins as isolated islands feeding into a single broker.

Principle 2 — Download-then-Display

Collection and display are strictly separated phases that must never be mixed:

• Collection (CLI download script): the only place credentials, API keys, and outbound HTTP calls exist in the codebase. Runs once offline and writes to data/.
• Display (SourcePlugin.load()): reads only from the previously downloaded local file. Zero network calls, zero credentials required at runtime. Raises FileNotFoundError if the file is absent — no live-fetch fallback.

Other updates

• "Adding a plugin" walkthrough now shows the download script as step 1 before the plugin file, making the two-phase separation concrete
• Config field types corrected (file_path / dir_path replacing the old path)
• ICON attribute documented
• Note added that selected paths persist to data/config.json across restarts
• Plugin schema table retained and kept accurate

Test plan

• README renders correctly on GitHub (diagrams, tables, code blocks)
• No code changes — CI lint/type/test steps should pass unchanged

🤖 Generated with Claude Code