Add 10 standards, privacy, and external guides

docs/evidence/GUIDE_ADAPTER_CAPABILITY.md

@@ -0,0 +1,23 @@
+# Adapter Capability Reading Guide
+
+How to understand what an external adapter can and cannot do.
+
+## Required Documentation
+Each adapter should document:
+- What it models (scope)
+- What it does NOT model (out of scope)
+- Calibration data available
+- Error handling behavior
+- Resource requirements
+
+## Reading the SimulationResult
+- `scope` — what was modeled (e.g., `bacterial_membrane_binding`)
+- `scores` — the actual output values
+- `uncertainty` — 0 = certain, 1 = completely uncertain
+- `calibration_set` — what data was used for calibration (None = no calibration)
+- `notes` — warnings, limitations, and context
+
+## Red Flags
+- `uncertainty` > 0.5 — do not use for decision-making
+- `calibration_set` is None — no evidence the adapter works
+- `notes` mention `SIMULATION_THEATER_RISK` — adapter is speculative

docs/evidence/GUIDE_ADAPTER_FAILURES.md

@@ -0,0 +1,22 @@
+# Adapter Failure Interpretation Guide
+
+How to interpret failures from external adapters.
+
+## Common Failure Modes
+| Error | Likely Cause | Action |
+|-------|-------------|--------|
+| Connection refused | External service is down | Retry later, check service status |
+| Timeout | Request took too long | Increase timeout or reduce request size |
+| Rate limited | Too many requests | Reduce request frequency |
+| Invalid response | Service returned unexpected data | Check adapter version compatibility |
+| Authentication failed | Credentials are invalid | Update credentials |
+
+## Response Format
+All adapters return a `SimulationResult` with:
+- `module` — adapter name
+- `version` — adapter version
+- `scope` — what was modeled
+- `scores` — dict of score key to value
+- `uncertainty` — 0-1 scale
+- `calibration_set` — reference to calibration data
+- `notes` — human-readable notes about the result

docs/evidence/GUIDE_EXTERNAL_CONSENT.md

@@ -0,0 +1,15 @@
+# External-Access Consent Note
+
+External adapters must not access network resources without explicit user consent.
+
+## Consent Rules
+1. Adapters must declare whether they require network access.
+2. Network access must be opt-in, not opt-out.
+3. Users must be informed before any data is sent externally.
+4. The purpose of the external access must be documented.
+5. No credentials may be stored or transmitted without explicit consent.
+
+## Implementation
+- Adapters should use `required_module` parameter in `ExternalSimulationAdapter`.
+- Network-dependent adapters should document this in their class docstring.
+- Local tests should not require network access.

docs/evidence/GUIDE_OFFLINE_MODE.md

@@ -0,0 +1,22 @@
+# Offline Mode Explanation
+
+OpenAMP Foundry tools are designed to work offline by default.
+
+## What Works Offline
+- All local checks: `check_doc_links.py`, `check_claims.py`, `check_pyproject.py`
+- Lab result validation: `validate_lab_data_return.py`, `check_wave1_pass_fail.py`
+- Negative archive validation: `validate_negative_archive.py`
+- Panel CSV validation: `validate_panel_csv.py`
+- Benchmark calculations
+- All tests (after initial `pip install`)
+
+## What Requires Network
+- Initial `pip install`
+- Downloading reference databases for novelty checks
+- External predictor submissions
+- Novelty database refresh
+
+## Why Offline Matters
+- Reproducibility — results should not depend on network availability
+- Security — no data leakage through network calls
+- Speed — local checks are faster than network-dependent ones

docs/evidence/GUIDE_OPTIONAL_DEPS.md

@@ -0,0 +1,27 @@
+# Optional Dependency Explanation
+
+Some dependencies are optional and only needed for specific features.
+
+## Optional Extras
+| Extra | Dependencies | Needed For |
+|-------|-------------|------------|
+| `dev` | pytest, ruff | Development and testing |
+| `docs` | — | Building documentation (currently none required) |
+| `external` | requests | External predictor submissions |
+
+## How to Install
+```bash
+# Core only
+pip install openamp-foundry
+
+# With dev tools
+pip install "openamp-foundry[dev]"
+
+# With everything
+pip install "openamp-foundry[dev,external]"
+```
+
+## Checking What's Installed
+```bash
+pip list | grep openamp-foundry
+```

docs/evidence/GUIDE_PRIVACY_MODEL.md

@@ -0,0 +1,23 @@
+# Privacy Model Overview
+
+How OpenAMP Foundry handles privacy and data.
+
+## Data Collected
+- Candidate sequences (provided by the user)
+- Lab result data (provided by the user)
+- Pipeline output files (stored locally)
+
+## Data NOT Collected
+- No telemetry
+- No analytics
+- No usage statistics
+- No personal information
+
+## Data Sharing
+- Adapters do not send data without explicit user consent.
+- External predictors require user-initiated submission.
+- No data is shared with third parties without user action.
+
+## Local-Only Guarantee
+All core pipeline operations run locally. No data leaves your machine
+unless you explicitly use an external adapter or predictor.

docs/evidence/GUIDE_SECRETS_HANDLING.md

@@ -0,0 +1,21 @@
+# Secret-Handling Warning Page
+
+OpenAMP Foundry does not handle secrets, credentials, or tokens.
+
+## What We Do NOT Store
+- API keys
+- Passwords
+- Tokens
+- Certificates
+- Any authentication material
+
+## If You Need Secrets
+Secrets for external services (e.g., predictor APIs) must be handled outside
+the pipeline. Use environment variables or a secrets manager.
+
+## Safety Rules
+1. Never commit secrets to the repository.
+2. Never hard-code credentials in scripts or adapters.
+3. Use environment variables for any required authentication.
+4. Document which environment variables are needed in the adapter docs.
+5. The `.env` file is git-ignored; use it for local development.

docs/evidence/STANDARD_ADAPTER_DOCS.md

@@ -0,0 +1,17 @@
+# Adapter Documentation Standard
+
+External adapters must document:
+
+## Required
+- What the adapter does
+- What external resource it connects to
+- Whether network access is required
+- Required dependencies
+- Version of the external resource
+
+## Recommended
+- Example usage
+- Expected output format
+- Known limitations
+- Error handling behavior
+- Rate limiting considerations

docs/evidence/STANDARD_CSV_INPUT.md

@@ -0,0 +1,19 @@
+# CSV Input Documentation Standard
+
+CSV input files must document:
+
+## Required Columns
+- `candidate_id` — unique identifier for each candidate
+- `sequence` — amino acid sequence (standard single-letter codes)
+- `source` — origin of the candidate (generated, imported, seed-derived)
+
+## Optional Columns
+- `batch` — batch name or ID
+- `family` — scaffold family name
+- Any score columns that were used for selection
+
+## Header
+CSV files must have a header row with column names. Column names should use snake_case.
+
+## Encoding
+UTF-8 with BOM is accepted. ASCII is preferred.

docs/evidence/STANDARD_JSONL_ARTIFACT.md

@@ -0,0 +1,18 @@
+# JSONL Artifact Documentation Standard
+
+JSONL (JSON Lines) files used by the pipeline must follow this standard.
+
+## Format
+- One JSON object per line
+- No separator between objects (newline only)
+- UTF-8 encoding
+- Each line must be valid JSON
+
+## Required Fields
+- `candidate_id`
+- `sequence`
+- `scores` — dict of score key to value
+
+## Naming
+- Use `.jsonl` extension
+- File name should describe the content (e.g., `demo_ranked.jsonl`)

tests/test_standards_external_batch.py

@@ -0,0 +1,20 @@
+"""Tests for standards and external guides batch."""
+from pathlib import Path
+
+FILES = [
+    "STANDARD_CSV_INPUT.md",
+    "STANDARD_JSONL_ARTIFACT.md",
+    "STANDARD_ADAPTER_DOCS.md",
+    "GUIDE_OFFLINE_MODE.md",
+    "GUIDE_OPTIONAL_DEPS.md",
+    "GUIDE_ADAPTER_FAILURES.md",
+    "GUIDE_EXTERNAL_CONSENT.md",
+    "GUIDE_ADAPTER_CAPABILITY.md",
+    "GUIDE_PRIVACY_MODEL.md",
+    "GUIDE_SECRETS_HANDLING.md",
+]
+
+
+def test_all_exist():
+    for f in FILES:
+        assert Path("docs/evidence", f).exists(), f"Missing: {f}"