CC: prepare generic VISION package candidate

docs/VISION-HOST-ADAPTER-CANDIDATES.md

@@ -0,0 +1,29 @@
+# VISION Host Adapter Candidates
+
+Status: candidate only. These adapter manifests do not install into Seed and do
+not grant host access.
+
+## Intent
+
+Claude Code, Codex CLI, and Pi-Code should expose the same VISION package
+capabilities when Seed accepts the package. Each host adapter is thin: it maps
+host-specific command shape to the same package tool ids and the same disclosure
+contract.
+
+## Host Targets
+
+- `claude-code`
+- `codex-cli`
+- `pi-code`
+
+## Parity Rule
+
+Each host adapter candidate must expose the same current tool ids, the same
+planned tool ids, no wildcard grant, and the same Visual Evidence disclosure
+contract.
+
+## Candidate Manifests
+
+- `candidate-manifests/host-adapters/vision-claude-code-adapter.json`
+- `candidate-manifests/host-adapters/vision-codex-cli-adapter.json`
+- `candidate-manifests/host-adapters/vision-pi-code-adapter.json`

docs/VISION-PACKAGE-CANDIDATE.md

@@ -0,0 +1,70 @@
+# VISION Package Candidate
+
+Status: child-local candidate only. No Core promotion, Seed installation,
+Runtime start, Profile Exposure, or provider admission is authorized. No
+wildcard grant is authorized by this document.
+
+## Intent
+
+`svrnty-vision` is the generic visual-perception package candidate for the
+canonical Cortex OS sense `VISION`. It owns tools that inspect or produce pixels,
+images, screenshots, browser observations, layouts, charts, diagrams, grounded
+regions, segmentations, video frames, or generated/edited images.
+
+`research` is also under the `VISION` sense family, but it owns textual/source
+reading and research workflows. The boundary is by capability, not by sense name:
+Research reads sources; Vision sees media.
+
+## Current Route Adapters
+
+| Current route | Candidate tool id | Capability |
+| --- | --- | --- |
+| `POST /vlm/analyze` | `vision.image_analyze` | Analyze image input with a VLM and return a normalized observation. |
+| `POST /flux/render` | `vision.image_generate` | Generate image output through the existing FLUX route. |
+| `POST /palette/extract` | `vision.palette_extract` | Extract dominant colors from image input. |
+| `POST /rembg/cutout` | `vision.background_cutout` | Remove image background and return cutout output. |
+
+## Planned Tool Candidates
+
+The complete VISION visual-perception package should cover:
+
+- `vision.ocr_read`
+- `vision.screenshot_observe`
+- `vision.browser_observe`
+- `vision.document_layout_read`
+- `vision.chart_read`
+- `vision.table_read`
+- `vision.diagram_read`
+- `vision.object_detect`
+- `vision.visual_ground`
+- `vision.segment`
+- `vision.video_read`
+- `vision.image_edit`
+
+These are not implemented or granted by this slice. They are named so future
+work has a canonical target and does not duplicate Research capabilities.
+
+## Boundary
+
+Owned here:
+
+- Pixel/media perception.
+- Visual evidence production.
+- Image generation or editing.
+- Visual extraction from screenshots, browser views, image files, video frames,
+  charts, diagrams, and layouts.
+
+Not owned here:
+
+- Web search.
+- Page fetch.
+- PDF text extraction.
+- Research synthesis.
+- Deep research planning.
+- Capsule writing.
+- Profile Exposure.
+- Runtime startup.
+- Provider admission.
+
+Research can consume Visual Evidence only through an explicit handoff contract.
+Vision never becomes a research synthesizer by returning evidence.

docs/VISUAL-EVIDENCE-CONTRACT.md

@@ -0,0 +1,42 @@
+# Visual Evidence Contract
+
+Status: candidate contract. This is route-only evidence for Cortex OS and Seed
+review. It does not grant tools or promote the package.
+
+## Required Fields
+
+Every Visual Evidence record must include:
+
+- `producing_package_id`
+- `producing_tool_id`
+- `capability_surface`
+- `source_reference`
+- `provider_mode`
+- `retention_disclosure`
+- `observed_content_summary`
+- `extracted_claims`
+- `confidence`
+- `caveats`
+- `timestamp`
+- `validation_status`
+
+## First Vertical Proof
+
+The first proof adapts a raw-mode `POST /vlm/analyze` response into Visual
+Evidence through a pure Python adapter. It does not call a live provider.
+
+Proof module: `src/svrnty_vision/visual_evidence.py`
+
+Proof test: `tests/test_visual_evidence.py`
+
+## Research Handoff Rule
+
+Research may cite Visual Evidence as an input source if the record includes the
+required fields and validation status. Research owns synthesis and capsule writing.
+Vision owns the visual observation record only.
+
+## Provider And Retention Disclosure
+
+Provider mode and retention are mandatory because host agents must be able to
+disclose how the visual observation was produced. Missing disclosure invalidates
+the evidence record.