@mindrian_os/install 1.13.0-beta.11

package/references/methodology/validate.md

@@ -0,0 +1,163 @@
+# Evidence Validation -- Framework Reference
+
+*Loaded on demand by `/mos:validate`*
+
+## Framework Overview
+
+The Evidence Validation framework helps users validate ideas with evidence -- not enthusiasm. It combines two powerful lenses: User Needs Analysis (find where importance and satisfaction diverge) and Six Thinking Hats (validate from six perspectives, not just yours). What survives disproval is worth building. Based on de Bono's Six Thinking Hats and Ulwick's Importance-Satisfaction methodology, applied through Larry's evidence-obsessed teaching style.
+
+The operating principle: Validation is not confirmation. If you only look for evidence that supports your idea, you'll always find it. The Validator looks for evidence that DISPROVES -- because what survives disproval is worth building.
+
+## The Voice (This Methodology)
+
+Larry in validation mode. Evidence-obsessed. Allergic to wishful thinking. Fair but unsparing.
+
+Signature phrases:
+- "Evidence or opinion? There's only one of those I'm interested in."
+- "You've told me why this is exciting. Now tell me why it might not work."
+- "That's an opinion. Show me the data."
+- "Everyone who's failed thought their idea was validated too. What makes yours different?"
+- "Your satisfaction score is low. But is the importance score HIGH? Because fixing something nobody cares about isn't innovation -- it's busywork."
+- "The Black Hat disagrees with every other hat. That's not a problem -- that's the most important signal in the room."
+
+Anti-patterns to catch:
+- Validating based on enthusiasm alone -- require evidence
+- Skipping the importance-satisfaction matrix -- it prevents solving the wrong problem
+- Letting one hat dominate -- especially Yellow (optimism bias)
+- Declaring "validated" without addressing Black Hat concerns
+- Accepting "users want this" without asking how many, how badly, and how you know
+- Never teach the framework abstractly -- apply it to their actual idea
+
+## Phases
+
+### Phase 1: Claim Inventory (Investigative -- turns 1-2)
+
+Surface what claims they're making about their idea.
+
+- "What claims are you making? List every assumption baked into this idea."
+- "Which of these claims have evidence? Which are hopes?"
+
+ONE question per response. Short and Socratic.
+
+### Phase 2: Process Mapping and Evidence Classification (Investigative -- turns 2-4)
+
+Map the user's journey and classify evidence types.
+
+- "Walk me through the user's journey -- every step, every touchpoint."
+- "Where do they pause? Where do they give up? Where do they complain?"
+- "What workarounds have they invented?"
+- Classify evidence: primary (direct observation) vs secondary (reported), quantitative vs qualitative.
+
+### Phase 3: Importance-Satisfaction Analysis (Investigative to Blend -- turns 4-6)
+
+Rate each process step on importance and satisfaction.
+
+- For each step: Importance (1-10) and Satisfaction (1-10).
+- Gap = Importance - Satisfaction. High importance + low satisfaction = bullseye.
+- "This step matters deeply but works poorly. Why?"
+- "What prevents improvement? Technical, organizational, or behavioral?"
+
+### Phase 4: Six Thinking Hats Cross-Check (Blend -- turns 6-9)
+
+Validate from every angle using de Bono's framework.
+
+- White Hat: "What evidence supports this? What data is missing?"
+- Red Hat: "How do stakeholders FEEL about this? What does your gut say?"
+- Black Hat: "What could go wrong? What's the worst case?"
+- Yellow Hat: "What's the upside? What precedents show this works?"
+- Green Hat: "What else could solve this? What haven't we tried?"
+- Blue Hat: "Are we asking the right question? What's our blind spot?"
+
+If all six hats agree, you might have something. If only Yellow agrees, you have wishful thinking.
+
+### Phase 5: Contradiction Detection (Blend to Insight -- turns 9-10)
+
+Surface conflicts between evidence types and perspectives.
+
+- "Where does qualitative evidence contradict quantitative?"
+- "Which hats disagree with each other -- and why?"
+- "What would have to be true for the Black Hat concerns to be wrong?"
+
+### Phase 6: Confidence Scoring and Verdict (Insight -- turns 10+)
+
+Synthesize across all perspectives into a verdict.
+
+- Score overall confidence: HIGH / MEDIUM / LOW.
+- Identify what would increase confidence (specific evidence needed).
+- Deliver the verdict with supporting and opposing evidence balanced.
+
+End with: "Your strongest evidence is [specific]. Your weakest link is [specific]. Before you commit resources, go validate [the weak link] by [specific method]."
+
+## Artifact Template
+
+```markdown
+---
+methodology: validate
+created: {date}
+depth: {quick|deep}
+problem_type: {type}
+venture_stage: {stage}
+room_section: competitive-analysis
+---
+
+# Evidence Validation -- {Topic}
+
+## Claims Inventory
+| # | Claim | Evidence Type | Source | Status |
+|---|-------|---------------|--------|--------|
+| 1 | {claim} | {primary/secondary} | {source} | {supported/unsupported/contested} |
+
+## Importance-Satisfaction Analysis
+
+| Step | Importance (1-10) | Satisfaction (1-10) | Gap | Priority |
+|------|-------------------|---------------------|-----|----------|
+| {step} | {score} | {score} | {gap} | {high/medium/low} |
+
+### Bullseye Areas (High Importance, Low Satisfaction)
+{Steps that matter most but work worst -- where opportunity lives}
+
+## Six Thinking Hats Cross-Check
+
+| Hat | Perspective | Finding |
+|-----|-------------|---------|
+| White (Facts) | {what data says} | {finding} |
+| Red (Emotion) | {how stakeholders feel} | {finding} |
+| Black (Risk) | {what could go wrong} | {finding} |
+| Yellow (Value) | {what's the upside} | {finding} |
+| Green (Alternatives) | {what else could work} | {finding} |
+| Blue (Process) | {are we asking the right question} | {finding} |
+
+### Hat Contradictions
+{Where hats disagree and what that signals}
+
+## Validation Verdict
+
+**VERDICT: {VALIDATED / PARTIALLY VALIDATED / NOT VALIDATED}**
+
+**Evidence Strength:**
+- Supporting: {count and quality}
+- Opposing: {count and quality}
+- Missing: {what you still need}
+
+**Confidence Level: {HIGH / MEDIUM / LOW}**
+- What would increase confidence: {specific evidence needed}
+
+## Homework
+Your strongest evidence is {specific}. Your weakest link is {specific}. Before you commit resources, go validate {the weak link} by {specific method}. If it holds, move. If it doesn't -- you just saved yourself from building something nobody needs.
+```
+
+## Default Room
+
+competitive-analysis
+
+## Cross-References
+
+- **challenge-assumptions**: If validation reveals assumptions worth challenging
+- **root-cause**: If low satisfaction has deep structural causes
+- **structure-argument**: If the validated thesis needs structured communication
+- **analyze-needs**: If importance-satisfaction gaps reveal unmet needs
+
+## Quick Pass vs Deep Dive
+
+- **Quick (10-15 min)**: Focus on top 3 claims, quick importance-satisfaction scan, Black Hat stress test only. Good when the user needs a fast reality check.
+- **Deep (30-45 min)**: Full six-phase arc, complete importance-satisfaction matrix, all six hats, contradiction detection, confidence scoring. Best for pre-investment or pre-build decisions.

package/references/methodology/value-proposition.md

@@ -0,0 +1,244 @@
+# PWS Value Proposition Framework -- Reference
+
+*Loaded on demand by `/mos:validate-proposition`*
+
+## Framework Overview
+
+The PWS Value Proposition Framework answers one fundamental question from multiple angles: What is the strong value proposition to make a customer transition from their current state to the new state you offer?
+
+A value proposition is not good or bad -- it is STRONG or WEAK. This framework quantifies strength through three sequential gates, a value canvas, and a composite score.
+
+Core principle from Lawrence: "You, your team, and your partners are stakeholders just like any other. This perspective keeps you grounded in why you do what you do."
+
+The Samsonite Test: Samsonite beats Tumi not on quality but on value proposition strength -- durable luggage at a reasonable price. The question is never "is it the best?" but "is the proposition strong enough to make someone switch?"
+
+## The Voice (This Methodology)
+
+Larry as a value proposition examiner. Quantitative. Demanding evidence. One gate at a time.
+
+Signature phrases:
+- "A value proposition is not good or bad. It's strong or weak. Let's measure yours."
+- "You're telling me features. I need the reason someone switches."
+- "Is it real? Can you win? Is it worth it? You need all three."
+- "That's a solution looking for a problem. Flip it."
+- "Where's your Samsonite moment? The thing that makes premium irrelevant."
+
+Anti-patterns to catch:
+- **Feature Listing** -- describing what the product does instead of why someone switches
+- **Solution-First Thinking** -- proposing a solution without proving the problem is real
+- **Vague Differentiation** -- "we're better" without quantifiable comparison
+- **Missing the Switch Cost** -- ignoring what it takes for a customer to change
+- **Stakeholder Blindness** -- forgetting the team itself is a stakeholder
+- **Risk vs Uncertainty Confusion** -- managing risk when they should be assessing uncertainty
+
+## Mathematical Model
+
+### Three Gates (Sequential -- each must pass before next)
+
+#### Gate 1: IS IT REAL? (Problem Case)
+
+Score 5 dimensions, each 0-10:
+
+| Dimension | Weight | Guiding Question |
+|-----------|--------|-----------------|
+| Problem Existence | 0.25 | Is the problem documented, observed, validated by real users? |
+| Problem Severity | 0.25 | How painful? (1=annoyance, 10=existential threat) |
+| Market Size | 0.20 | How many people/orgs have this problem? |
+| Problem Frequency | 0.15 | How often? (1=once ever, 10=daily) |
+| Current Alternatives | 0.15 | How poorly served? (1=well-served, 10=nothing exists) |
+
+Gate 1 Score: R = 0.25*existence + 0.25*severity + 0.20*market + 0.15*frequency + 0.15*alternatives
+Pass threshold: R >= 6.0
+FAIL message: "The problem isn't real enough. Stop building."
+
+#### Gate 2: CAN WE WIN? (Solution Case)
+
+| Dimension | Weight | Guiding Question |
+|-----------|--------|-----------------|
+| Technical Feasibility | 0.20 | Can we actually build this? Proven tech or moonshot? |
+| Resource Availability | 0.20 | Do we have or can we get what's needed? |
+| Competitive Advantage | 0.20 | What's the unfair advantage that can't be copied? |
+| Team Capability | 0.20 | Does the team have the skills to execute? |
+| Risk Manageability | 0.20 | Can identified risks be mitigated? |
+
+Gate 2 Score: W = 0.20*(feasibility + resources + advantage + team + risk)
+Pass threshold: W >= 5.5
+FAIL message: "You can't win this. Find your unfair advantage or pivot."
+
+#### Gate 3: IS IT WORTH IT? (Business Case)
+
+| Dimension | Weight | Guiding Question |
+|-----------|--------|-----------------|
+| Revenue Potential | 0.25 | Expected revenue at scale? |
+| Margin/Unit Economics | 0.20 | Can you make money on each unit? |
+| Time to Revenue | 0.15 | How fast to first customer revenue? (not fundraising) |
+| Strategic Alignment | 0.20 | Does this fit your mission and strengths? |
+| Scalability | 0.20 | Can this grow 10x without 10x cost? |
+
+Gate 3 Score: V = 0.25*revenue + 0.20*margin + 0.15*time + 0.20*alignment + 0.20*scalability
+Pass threshold: V >= 5.0
+FAIL message: "Not worth it. The math doesn't work."
+
+### Composite Value Proposition Strength (VPS)
+
+VPS = (R x 0.35) + (W x 0.35) + (V x 0.30)
+
+| VPS | Rating | Meaning |
+|-----|--------|---------|
+| 8.0-10.0 | STRONG | Proceed with confidence. Investors lean forward. |
+| 6.5-7.9 | MODERATE | Promising but has gaps. Address weak dimensions. |
+| 5.0-6.4 | WEAK | Significant concerns. Rethink at least one gate. |
+| 0.0-4.9 | FAILING | Does not pass. Pivot or abandon. |
+
+Gate kill rule: ANY single gate failure = proposition fails regardless of other scores.
+
+### Value Canvas (Qualitative Layer)
+
+After gates pass, map:
+
+Customer Side:
+- Jobs to Be Done (functional, emotional, social)
+- Gains desired (required, expected, desired, unexpected)
+- Pains experienced (undesired outcomes, obstacles, risks)
+
+Product Side:
+- Gain Creators (how product creates gains)
+- Pain Relievers (how product relieves pains)
+- Products/Services (what you offer for the jobs)
+
+Fit Score = (jobs_addressed / total_jobs) x (gains_created / gains_desired) x (pains_relieved / pains_identified)
+Range: 0.0-1.0. Above 0.6 = product-market fit signal. Above 0.8 = strong fit.
+
+### BTC Value Proposition Statement
+
+Template:
+For [target customer]
+Who [statement of need or opportunity],
+Our [product/service name] is [product category]
+That [statement of benefit].
+Unlike [primary competitive alternative],
+Our product [statement of primary differentiation].
+
+### B2B Value Drivers (if applicable, score each 0-10)
+
+| Driver | Question |
+|--------|----------|
+| Revenue Increase | How do you help customers make more money? |
+| Cost Reduction | How do you help customers spend less? |
+| Customer Responsiveness | How do you help them serve THEIR customers better? |
+| Productivity | How do you boost their output? |
+| Cycle Time | How do you make them faster? |
+| Customer Satisfaction | How do you improve their retention? |
+| Quality | How do you enhance their output quality? |
+| Employee Satisfaction | How do you make their people happier? |
+
+B2B Value Score = average of scored drivers (only count applicable ones)
+
+## Phases
+
+### Phase 1: Gate 1 -- Is It Real? (turns 1-4)
+ONE dimension per exchange. Score together with evidence.
+- "Who has this problem? How many? How often? How painful?"
+- "What do they do today? How well does that work?"
+- Push back: "Everyone has this problem" = score 0 on market sizing.
+Calculate Gate 1 score. If < 6.0: STOP. "The problem isn't real enough."
+
+### Phase 2: Gate 2 -- Can We Win? (turns 4-7)
+- "What's your unfair advantage? Not 'we're better' -- what can't be copied?"
+- "What resources do you need that you don't have?"
+- "Name the top 3 risks. Can you manage them?"
+Calculate Gate 2 score. If < 5.5: STOP. "You can't win this."
+
+### Phase 3: Gate 3 -- Is It Worth It? (turns 7-10)
+- "Show me the unit economics. Revenue per customer. Cost to serve."
+- "How fast to first customer revenue? Not fundraising -- revenue."
+- "Can this scale 10x without 10x cost?"
+Calculate Gate 3 score. If < 5.0: STOP. "Not worth it."
+
+### Phase 4: Value Canvas (turns 10-12)
+Map Jobs, Gains, Pains. Calculate Fit Score.
+- "What job is the customer hiring your product to do?"
+- "What gain do they get that they can't get elsewhere?"
+
+### Phase 5: Synthesis (turns 12+)
+Calculate VPS composite. Generate BTC statement. If B2B: score value drivers.
+Identify weakest dimension. That's the next action.
+- "Your VPS is X.X. Here's the verdict and here's where to focus."
+
+Escape hatch: "just tell me" = immediate VPS with brief rationale.
+
+## Artifact Template
+
+---
+methodology: value-proposition
+created: {date}
+depth: {quick|deep}
+problem_type: {type}
+venture_stage: {stage}
+room_section: business-model
+---
+
+# Value Proposition Assessment -- {Venture}
+
+## Gate 1: Is It Real? (R = {score})
+| Dimension | Weight | Score | Evidence |
+|-----------|--------|-------|----------|
+| Problem Existence | 0.25 | {0-10} | {evidence} |
+| Problem Severity | 0.25 | {0-10} | {evidence} |
+| Market Size | 0.20 | {0-10} | {evidence} |
+| Problem Frequency | 0.15 | {0-10} | {evidence} |
+| Current Alternatives | 0.15 | {0-10} | {evidence} |
+| **Gate 1** | | **{R}** | **{PASS/FAIL}** |
+
+## Gate 2: Can We Win? (W = {score})
+| Dimension | Weight | Score | Evidence |
+|-----------|--------|-------|----------|
+| Technical Feasibility | 0.20 | {0-10} | {evidence} |
+| Resource Availability | 0.20 | {0-10} | {evidence} |
+| Competitive Advantage | 0.20 | {0-10} | {evidence} |
+| Team Capability | 0.20 | {0-10} | {evidence} |
+| Risk Manageability | 0.20 | {0-10} | {evidence} |
+| **Gate 2** | | **{W}** | **{PASS/FAIL}** |
+
+## Gate 3: Is It Worth It? (V = {score})
+| Dimension | Weight | Score | Evidence |
+|-----------|--------|-------|----------|
+| Revenue Potential | 0.25 | {0-10} | {evidence} |
+| Margin/Unit Economics | 0.20 | {0-10} | {evidence} |
+| Time to Revenue | 0.15 | {0-10} | {evidence} |
+| Strategic Alignment | 0.20 | {0-10} | {evidence} |
+| Scalability | 0.20 | {0-10} | {evidence} |
+| **Gate 3** | | **{V}** | **{PASS/FAIL}** |
+
+## Composite VPS = {score} -- {STRONG/MODERATE/WEAK/FAILING}
+
+## Value Canvas
+### Customer: Jobs | Gains | Pains
+### Product: Gain Creators | Pain Relievers | Products
+### Fit Score: {0.0-1.0}
+
+## BTC Statement
+For {customer} who {need}, our {product} is {category} that {benefit}. Unlike {competitor}, our product {differentiation}.
+
+## Weakest Dimension: {name} (score: {x})
+Recommendation: {action}
+
+## Next Steps
+1. {address weakest dimension}
+2. {validate riskiest assumption}
+3. {strengthen proposition}
+
+## Default Room
+business-model
+
+## Cross-References
+- **analyze-needs**: If JTBD canvas needs deeper job analysis
+- **challenge-assumptions**: If any gate relies on unvalidated assumptions
+- **lean-canvas**: If proposition passes and needs business model
+- **build-thesis**: If proposition is strong enough for investment case
+- **user-needs**: If Gate 1 needs deeper process mapping
+- **diagnose**: If problem type is unclear
+
+## Quick Pass vs Deep Dive
+- **Quick (10-15 min)**: Score all 3 gates high-level. Calculate VPS. Identify weakest link.
+- **Deep (30-60 min)**: Full five-phase with evidence per dimension, Value Canvas, BTC statement, B2B drivers.

package/references/opportunities/funding-lifecycle.md

@@ -0,0 +1,103 @@
+# Funding Lifecycle
+
+> Defines the 4-stage lifecycle for opportunities promoted from opportunity-bank to funding.
+> Stages are sequential. Outcomes are separate from stages.
+
+## Lifecycle Stages
+
+```
+Discovered  -->  Researched  -->  Applying  -->  Submitted
+```
+
+### Stage 1: Discovered
+
+**Definition:** Opportunity identified and filed in opportunity-bank. Basic information captured (funder, program, amount range, deadline).
+
+**Entry criteria:** User confirms filing from Larry's surfacing.
+
+**Contents:** Source opportunity artifact in opportunity-bank/ with frontmatter.
+
+**Transition to Researched:** User requests deeper analysis of this opportunity.
+
+### Stage 2: Researched
+
+**Definition:** Eligibility confirmed, fit assessed against room context, requirements documented in detail. Due diligence complete.
+
+**Entry criteria:** Larry completes eligibility analysis and fit assessment.
+
+**Contents:** research.md with eligibility analysis, fit assessment, requirements checklist.
+
+**Transition to Applying:** User decides to pursue this opportunity and begin application.
+
+### Stage 3: Applying
+
+**Definition:** Application in progress. Narrative drafted, supporting materials gathered, submission requirements tracked.
+
+**Entry criteria:** User initiates application process.
+
+**Contents:** narrative.md with draft narrative, supporting documents referenced.
+
+**Transition to Submitted:** Application submitted to funder.
+
+### Stage 4: Submitted
+
+**Definition:** Application sent to funder. Awaiting decision. No further action until response.
+
+**Entry criteria:** Application confirmed submitted.
+
+**Contents:** Submission confirmation, expected response timeline.
+
+## Outcomes (NOT Stages)
+
+Outcomes are a separate attribute from stage. An opportunity in any stage can receive an outcome.
+
+| Outcome | Description |
+|---------|-------------|
+| `awarded` | Funding approved by funder |
+| `rejected` | Application declined by funder |
+| `withdrawn` | User withdrew application before decision |
+
+**Important:** Awarded/Rejected are outcomes, NOT lifecycle stages. The `stage` field tracks WHERE in the process the opportunity is. The `outcome` field tracks the RESULT.
+
+## STATUS.md Frontmatter Schema
+
+Each funding entry folder contains a `STATUS.md` with this frontmatter:
+
+```yaml
+---
+stage: discovered | researched | applying | submitted
+outcome: null | awarded | rejected | withdrawn
+source_opportunity: "[[opportunity-bank/YYYY-MM-DD-slug]]"
+deadline: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+transition_history:
+  - stage: discovered
+    date: YYYY-MM-DD
+    note: "Initial filing from opportunity-bank"
+  - stage: researched
+    date: YYYY-MM-DD
+    note: "Eligibility confirmed, fit assessed"
+---
+```
+
+## Folder Structure
+
+```
+room/funding/
+  STATE.md                      # Pipeline summary (aggregated from entries)
+  nsf-sbir-phase1/              # Per-opportunity folder
+    STATUS.md                   # Lifecycle stage + transition history
+    research.md                 # Due diligence (Researched+)
+    narrative.md                # Grant narrative (Applying+)
+  doe-clean-energy/             # Another opportunity
+    STATUS.md
+```
+
+## Cross-References
+
+Funding entries link back to their source opportunity via wikilink:
+```
+source_opportunity: "[[opportunity-bank/2026-03-20-nsf-sbir]]"
+```
+
+This creates a graph edge between the funding lifecycle entry and its source in opportunity-bank, parseable by `build-graph`.

package/references/opportunities/grant-api-patterns.md

@@ -0,0 +1,99 @@
+# Grant API Query Patterns
+
+> How room context maps to API query parameters for context-driven grant discovery.
+> Larry uses these patterns to translate room intelligence into search queries.
+
+## Context-Driven Query Generation
+
+The discovery engine does NOT use hardcoded searches. It reads the user's room data and generates queries:
+
+```
+Room STATE.md     -->  domain_keywords, geography, venture_stage, team_type
+problem-definition/  -->  domain context, target population, desired outcomes
+market-analysis/     -->  sector terms, market signals
+```
+
+### buildGrantQuery Flow
+
+1. Read `room/STATE.md` frontmatter: `domain_keywords`, `geography`, `venture_stage`, `team_type`
+2. Read `room/problem-definition/*.md` body text: extract significant terms from first sentences
+3. Combine into structured query: `{ keyword, fundingCategories, eligibilities, geography, ventureStage }`
+4. If insufficient context (no domain_keywords AND sparse problem-definition): return `{ insufficient: true }` with explanation
+
+## Domain-to-Funding-Category Mapping
+
+Maps room `domain_keywords` to Grants.gov `fundingCategories` codes:
+
+| Domain Keyword | Category Code | Category Name |
+|----------------|---------------|---------------|
+| artificial-intelligence | ST | Science & Technology |
+| machine-learning | ST | Science & Technology |
+| natural-language-processing | ST | Science & Technology |
+| software | ST | Science & Technology |
+| robotics | ST | Science & Technology |
+| biotech | HL | Health |
+| health | HL | Health |
+| healthcare | HL | Health |
+| medical | HL | Health |
+| clean-energy | EN | Energy |
+| energy | EN | Energy |
+| climate | EN | Energy |
+| environment | ENV | Environment |
+| education | ED | Education |
+| agriculture | AG | Agriculture |
+| food | AG | Agriculture |
+| transportation | T | Transportation |
+| infrastructure | ISS | Income Security & Social Services |
+| housing | HU | Housing |
+| community-development | CD | Community Development |
+
+## Geography-to-Eligibility Mapping
+
+| Room Geography | Eligibility Tags |
+|----------------|-----------------|
+| United States | us-entity |
+| US | us-entity |
+| Israel | international |
+| EU | international |
+| UK | international |
+
+## API Endpoints
+
+### Grants.gov (v1)
+
+- **URL:** `POST https://api.grants.gov/v1/api/search2`
+- **No auth required** (public API)
+- **Body:** `{ keyword, oppStatuses: "posted", rows: 25, fundingCategories: "ST|HL", sortBy: "openDate|desc" }`
+- **Response:** `{ oppHits: [{ title, agencyName, oppNumber, awardCeiling, closeDate, id }] }`
+- **Timeout:** 10 seconds
+
+### Simpler Grants (v1)
+
+- **URL:** `POST https://api.simpler.grants.gov/v1/opportunities/search`
+- **No auth required** (public API)
+- **Body:** `{ query: "keyword", filters: { opportunity_status: { one_of: ["posted"] } }, pagination: { page_size: 25, sort_by: [{ order_by: "relevancy" }] } }`
+- **Response:** `{ data: [{ opportunity_title, agency_name, opportunity_number, award_ceiling, close_date, opportunity_id }] }`
+- **Timeout:** 10 seconds
+
+## Relevance Scoring
+
+Multi-factor scoring (0.0 to 1.0):
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| Domain keyword match (2+) | 0.35 | Title/program contains room domain keywords |
+| Domain keyword match (1) | 0.20 | Partial domain match |
+| Geography eligibility | 0.15 | Room geography matches eligibility |
+| Defined deadline | 0.10 | Opportunity is actionable (has deadline) |
+| Funding amount specified | 0.10 | Quantifiable award |
+| Stage-appropriate | 0.20 | Grant type matches venture stage (SBIR for pre-revenue, etc.) |
+| Baseline (search hit) | 0.10 | Returned by keyword search |
+
+**Maximum score:** 1.0 (capped)
+
+## Error Handling
+
+- Both APIs are called via `Promise.allSettled` (one failure doesn't block the other)
+- 10-second timeout per API (AbortController)
+- Errors return empty results + error message (never throw)
+- API errors are collected in `api_errors` array for transparency

package/references/opportunities/opportunity-template.md

@@ -0,0 +1,84 @@
+# Opportunity Artifact Template
+
+> Standard frontmatter schema for filing opportunities to `room/opportunity-bank/`.
+> Every opportunity artifact follows this template.
+
+## Frontmatter Schema
+
+```yaml
+---
+methodology: opportunity-scan
+created: YYYY-MM-DD
+source: grants-gov | simpler-grants | web-research | manual | brain
+source_url: https://...
+opportunity_id: "PROGRAM-YYYY-NNN"
+funder: Organization Name
+program: Program Name
+amount_floor: 0
+amount_ceiling: 275000
+deadline: YYYY-MM-DD
+eligibility:
+  - small-business
+  - us-entity
+funding_category: science-technology
+relevance_score: 0.85
+relevance_reasoning: "Why this opportunity fits the room context"
+room_connections:
+  - section: problem-definition
+    relationship: INFORMS
+    reasoning: "How this connects"
+  - section: financial-model
+    relationship: ENABLES
+    reasoning: "How this connects"
+status: discovered
+rejection: null
+---
+```
+
+## Field Definitions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `methodology` | string | yes | Always `opportunity-scan` |
+| `created` | date | yes | Date opportunity was filed |
+| `source` | enum | yes | Discovery source: grants-gov, simpler-grants, web-research, manual, brain |
+| `source_url` | url | no | Direct link to opportunity listing |
+| `opportunity_id` | string | no | External identifier from source system |
+| `funder` | string | yes | Organization providing funding |
+| `program` | string | yes | Specific program or grant name |
+| `amount_floor` | number | no | Minimum award amount (0 if unknown) |
+| `amount_ceiling` | number | no | Maximum award amount |
+| `deadline` | date | no | Application deadline (null if rolling) |
+| `eligibility` | list | no | Eligibility categories (small-business, nonprofit, university, etc.) |
+| `funding_category` | string | no | Domain category (science-technology, health, education, etc.) |
+| `relevance_score` | float | yes | 0.0-1.0 relevance to room context |
+| `relevance_reasoning` | string | yes | Natural language explanation of relevance |
+| `room_connections` | list | yes | Typed edges to room sections (section, relationship, reasoning) |
+| `status` | enum | yes | discovered, filed, promoted, rejected |
+| `rejection` | string | no | Reason if user rejected (rejection IS data) |
+
+## Filing Instructions for Larry
+
+1. Extract room context: problem domain, geography, venture stage, team profile
+2. Generate search queries from room context (context-driven, NOT hardcoded)
+3. Present discovered opportunities to user with relevance reasoning
+4. User confirms -> file with full provenance using this template
+5. User rejects -> capture rejection reason in `rejection` field
+6. After filing, scan for cross-references to other room sections
+7. File as `YYYY-MM-DD-{slug}.md` in `room/opportunity-bank/`
+
+## Naming Convention
+
+```
+room/opportunity-bank/
+  STATE.md                        # Section summary
+  2026-03-20-nsf-sbir.md          # Filed opportunity
+  2026-03-22-doe-clean-energy.md  # Filed opportunity
+```
+
+## Relationship Types
+
+Use standard cross-relationship patterns from `references/meeting/cross-relationship-patterns.md`:
+- **INFORMS** -- opportunity relates to a section's domain
+- **ENABLES** -- funding would unblock progress in a section
+- **CONVERGES** -- opportunity scope aligns with multiple sections