docs(schema): clarify that Option.insights may cite findings (companion to astra-tools#89)

docs/specification.md

@@ -277,6 +277,8 @@ findings:
 
 Evidence is what lets a reader check a claim instead of simply accepting it. It can cite a paper, identify a passage in a source document, or point to an artifact produced by the analysis. The same structure works for prior insights and findings: a decision can say which insight supports it, and each insight can say exactly which source or output supports the claim. With evidence verification enabled, tools can check whether quoted text actually appears in the cited source.
 
+An option's `insights:` list may cite either a `prior_insight` (external evidence motivating the choice) or a `finding` (a claim produced by this analysis that in turn justifies a downstream choice). Both kinds of `Insight` are equally valid evidence — the distinction is which side of the analysis the claim originated on.
+
 ### Excluded options
 
 A rejected option can still be scientifically important. ASTRA lets authors keep it in the record while marking it as unavailable for valid universes.

src/astra/datamodel/astra_pydantic.py

@@ -629,7 +629,7 @@ class Option(ConfiguredBaseModel):
                        'Analysis']} })
     label: str = Field(default=..., description="""Human-readable name for the option""", json_schema_extra = { "linkml_meta": {'domain_of': ['Insight', 'Input', 'Output', 'Option', 'Decision']} })
     description: Optional[str] = Field(default=None, description="""Detailed description of the option""", json_schema_extra = { "linkml_meta": {'domain_of': ['Universe', 'Input', 'Output', 'Option']} })
-    insights: Optional[list[str]] = Field(default=None, description="""Insight IDs supporting this option""", json_schema_extra = { "linkml_meta": {'domain_of': ['InsightCollection', 'Option']} })
+    insights: Optional[list[str]] = Field(default=None, description="""Insight IDs supporting this option. May reference entries from either ``prior_insights`` (external/literature claims that motivate the choice) or ``findings`` (claims produced by this analysis that in turn justify it). The semantic validator resolves bare ids against the union of those two maps at the node-local scope, and ``../id`` / ``../../id`` against the corresponding union at an ancestor scope (matching the ``../`` grammar used by ``Input.from`` and ``Decision.from``).""", json_schema_extra = { "linkml_meta": {'domain_of': ['InsightCollection', 'Option']} })
     incompatible_with: Optional[list[str]] = Field(default=None, description="""Decision.option pairs that cannot be selected together""", json_schema_extra = { "linkml_meta": {'domain_of': ['Option']} })
     requires: Optional[list[str]] = Field(default=None, description="""Decision.option pairs that must also be selected""", json_schema_extra = { "linkml_meta": {'domain_of': ['Option']} })
     excluded: Optional[bool] = Field(default=None, description="""Whether this option was considered and rejected""", json_schema_extra = { "linkml_meta": {'domain_of': ['Option']} })

src/astra/schema/analysis.yaml

@@ -491,7 +491,15 @@ classes:
         description: Detailed description of the option
       insights:
         multivalued: true
-        description: Insight IDs supporting this option
+        description: >-
+          Insight IDs supporting this option. May reference entries from
+          either ``prior_insights`` (external/literature claims that
+          motivate the choice) or ``findings`` (claims produced by this
+          analysis that in turn justify it). The semantic validator
+          resolves bare ids against the union of those two maps at the
+          node-local scope, and ``../id`` / ``../../id`` against the
+          corresponding union at an ancestor scope (matching the ``../``
+          grammar used by ``Input.from`` and ``Decision.from``).
       incompatible_with:
         multivalued: true
         description: Decision.option pairs that cannot be selected together