Add 10 newcomer and safety guides

docs/evidence/GUIDE_EVIDENCE_BOUNDARY.md

@@ -0,0 +1,20 @@
+# Evidence Boundary Explainer
+
+What counts as evidence in the OpenAMP Foundry pipeline, and what does not.
+
+## Computational Evidence (Levels 0-4)
+- Valid sequence syntax
+- Reproducible features
+- Baseline heuristic scores
+- Multi-model consensus
+- Leakage-resistant benchmark results
+
+## Biological Evidence (Levels 5-6)
+- Lab assay results
+- Independent replication
+
+## The Boundary
+Computational evidence is sufficient for triage and nomination.
+Biological evidence is required for any claim of activity, safety, or efficacy.
+Crossing the boundary without wet-lab data is the most common and
+most serious form of overclaiming in AI-driven discovery.

docs/evidence/GUIDE_FIRST_PR.md

@@ -0,0 +1,32 @@
+# First Successful PR Guide
+
+Steps to get your first PR merged.
+
+## Choose an Issue
+Pick an issue labeled `good-first-issue`. These are small, well-scoped tasks.
+
+## Set Up
+```bash
+git clone https://github.com/Open-Problem-Lab/OpenAMP-Foundry.git
+cd OpenAMP-Foundry
+git checkout -b your-branch-name
+```
+
+## Make Changes
+1. Make your change.
+2. Add or update tests.
+3. Verify: `python3 -m pytest -q`
+4. Verify: `python scripts/check_doc_links.py`
+
+## Submit
+```bash
+git add -A
+git commit -m "Brief description of the change"
+git push origin your-branch-name
+```
+Then create a PR on GitHub referencing the issue number.
+
+## After Submission
+- Respond to review comments.
+- Make requested changes.
+- Once approved, your PR will be merged.

docs/evidence/GUIDE_LOCAL_SETUP.md

@@ -0,0 +1,27 @@
+# Local Setup Troubleshooting Guide
+
+## Quick Check
+```bash
+python3 --version        # Should be 3.11+
+python3 -m venv .venv    # Should create a virtual environment
+source .venv/bin/activate
+pip install -e ".[dev]"  # Should install without errors
+python3 -m pytest -q     # Should pass
+```
+
+## Common Issues
+
+### `pip install` fails
+- Try: `pip install --upgrade pip setuptools wheel`
+- Try: `pip install -e ".[dev]" --no-build-isolation`
+
+### Tests fail with import error
+- Make sure you're in the virtual environment: `source .venv/bin/activate`
+- Make sure PYTHONPATH includes `src`: `export PYTHONPATH=src`
+
+### `make demo` fails
+- Check that input files exist: `ls examples/sequences/demo_candidates.csv`
+- Check that reference files exist: `ls examples/known_reference/demo_known_amps.csv`
+
+### Still stuck?
+Open an issue with the full error message and your OS/Python version.

docs/evidence/GUIDE_MISUSE_SCENARIOS.md

@@ -0,0 +1,16 @@
+# Misuse Scenarios and Mitigations
+
+Potential misuse scenarios and how the project mitigates them.
+
+| Scenario | Risk | Mitigation |
+|----------|:----:|------------|
+| Overclaiming computational results as biological proof | High | `check_claims.py`, review process, AGENTS.md rules |
+| Using pipeline to design toxins | High | No toxicity optimization, safety penalties, safety review |
+| Releasing unscreened candidate lists | Medium | Gate process, human review, embargoed release |
+| Misinterpreting safety scores as guarantees | Medium | LIMITATIONS_OVERVIEW.md, disclaimer in all outputs |
+| Using pipeline without understanding limitations | Low | Honest limitations documented, quickstart guides |
+
+## Principles
+- Mitigations must not rely on users reading all documentation.
+- Safety-relevant mitigations should be enforced by code or process.
+- When code cannot prevent misuse, documentation and review must.

docs/evidence/GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md

@@ -0,0 +1,23 @@
+# Safe Contribution Boundary Guide
+
+What contributions are safe to make without maintainer discussion,
+and what requires discussion first.
+
+## Safe (No Discussion Needed)
+- Typo fixes and formatting improvements
+- Adding tests for existing functionality
+- Adding documentation for existing features
+- Updating example data or demo files
+
+## Discussion Recommended
+- Adding new features or modifying existing behavior
+- Adding new documentation categories
+- Changing test infrastructure
+- Adding new dependencies
+
+## Discussion Required
+- Changes to safety policy
+- Changes to scoring weights
+- Changes to calibration pipeline
+- Any change that affects claims or releases
+- Adding new benchmarks that affect the gate

docs/evidence/GUIDE_TRUST_MODEL.md

@@ -0,0 +1,19 @@
+# Trust Model Overview
+
+How trust is established in the OpenAMP Foundry project.
+
+## Trust Layers
+1. **Code transparency** — all code is open source (Apache 2.0)
+2. **Evidence transparency** — all results include caveats and limitations
+3. **Process transparency** — decisions are logged in decision logs
+4. **Reproducibility** — all outputs can be regenerated from versioned inputs
+5. **Review** — expert review is required before release
+
+## What Trust Does NOT Mean
+- Trust in the pipeline does not mean trust in the predictions as biological proof.
+- Trust in the code does not mean the code is bug-free.
+- Trust in the process does not mean the process guarantees correct results.
+
+## Related
+- `docs/trust/TRUST_CENTER.md` — trust architecture
+- `docs/evidence/LIMITATIONS_OVERVIEW.md` — honest limitations

docs/evidence/MAP_READER_BY_PERSONA.md

@@ -0,0 +1,18 @@
+# Reader Map by Persona
+
+How different readers should navigate the documentation.
+
+## Newcomer
+Start at README.md → QUICKSTART.md → CONTRIBUTOR_CURRICULUM.md
+
+## Scientist
+Start at LIMITATIONS_OVERVIEW.md → METRICS_CURRENT.md → EVIDENCE_CERTIFICATE.md
+
+## Engineer
+Start at ARCHITECTURE.md → COMMAND_SURFACE.md → src/openamp_foundry/
+
+## Reviewer
+Start at EXPERT_REVIEW_PACK.md → LIMITATIONS_OVERVIEW.md → PR_REVIEW_RUBRIC.md
+
+## Agent (AI)
+Start at AGENTS.md → AGENT_TASKS.json → CURRICULUM_AGENT.md

docs/evidence/PAGE_NON_GOALS.md

@@ -0,0 +1,17 @@
+# Non-Goals Page
+
+What the project explicitly does NOT aim to do.
+
+## Non-Goals
+1. **Replace wet-lab validation** — computational scores are predictions, not proof.
+2. **Discover drugs** — the pipeline nominates candidates, not drugs.
+3. **Guarantee safety** — safety scores are heuristics, not guarantees.
+4. **Replace domain experts** — expert review is required for all releases.
+5. **Optimize for toxicity** — that would violate the safety charter.
+6. **Operate autonomously** — human review is required for all decisions.
+
+## Why Document Non-Goals
+- Prevents mission creep.
+- Sets clear expectations for users and contributors.
+- Makes it easier to say no to out-of-scope work.
+- Aligns the project with its safety and honesty constraints.

docs/evidence/SAFETY_CHARTER.md

@@ -0,0 +1,22 @@
+# One-Page Safety Charter
+
+## Our Commitment
+OpenAMP Foundry is a dry-lab computational project. It does not conduct
+biological experiments. It does not provide protocols for handling
+dangerous organisms. It does not optimize for toxicity or harmful outcomes.
+
+## Safety Rules
+1. No wet-lab protocols in this repository.
+2. No optimization for mammalian toxicity.
+3. No instructions for pathogen enhancement.
+4. No release of unscreened high-risk candidate lists.
+5. Human review required before any release or public claim.
+
+## Enforcement
+- `scripts/safety/check_claims.py` scans for overclaiming language.
+- All PRs are reviewed for safety implications.
+- Safety-critical changes require a designated safety reviewer.
+
+## Related
+- `SAFETY.md` — full safety policy
+- `RESPONSIBLE_USE.md` — allowed and forbidden uses

docs/evidence/TOUR_COMMANDS.md

@@ -0,0 +1,30 @@
+# Command Tour for New Users
+
+A guided tour of the most important CLI commands.
+
+## 1. Rank Candidates
+```bash
+openamp-foundry rank --candidates examples/sequences/demo_candidates.csv \
+  --references examples/known_reference/demo_known_amps.csv \
+  --out outputs/demo_ranked.jsonl --report outputs/demo_report.md
+```
+This scores candidates, ranks them, and generates evidence certificates.
+
+## 2. Validate Certificates
+```bash
+openamp-foundry validate --certificate outputs/evidence/AMPF-000001.json \
+  --schema schemas/candidate.schema.json
+```
+This validates a candidate's evidence certificate against the schema.
+
+## 3. Build a Lab Pack
+```bash
+make lab-batch-pack
+```
+This creates a zip file with everything a lab partner needs.
+
+## 4. Check Pipeline Health
+```bash
+make full-reproducibility-report
+```
+This generates a report summarizing pipeline state and readiness.

tests/test_newcomer_guides.py

@@ -0,0 +1,20 @@
+"""Tests for newcomer guides batch."""
+from pathlib import Path
+
+FILES = [
+    "MAP_READER_BY_PERSONA.md",
+    "GUIDE_TRUST_MODEL.md",
+    "GUIDE_EVIDENCE_BOUNDARY.md",
+    "SAFETY_CHARTER.md",
+    "PAGE_NON_GOALS.md",
+    "GUIDE_MISUSE_SCENARIOS.md",
+    "GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md",
+    "GUIDE_FIRST_PR.md",
+    "GUIDE_LOCAL_SETUP.md",
+    "TOUR_COMMANDS.md",
+]
+
+
+def test_all_exist():
+    for f in FILES:
+        assert Path("docs/evidence", f).exists(), f"Missing: {f}"