nlweb-widget 0.9.12__tar.gz

nlweb_widget-0.9.12/.env.agentic.coding.example

@@ -0,0 +1,18 @@
+# Agentic coding credential classification template.
+# Copy to .env.agentic.coding locally; never commit the populated file.
+
+# OpenAI / Codex-compatible API
+OPENAI_API_KEY=
+
+# Anthropic / Claude-compatible API
+ANTHROPIC_API_KEY=
+
+# Other coding-agent provider API keys, if used by local tooling
+# CODE_AGENT_API_KEY=
+
+# GitHub CLI / API authentication should normally remain in the user's
+# OS credential store or `gh auth`; do not copy a personal token here.
+# GITHUB_TOKEN=
+
+# Optional package/release credentials should use CI trusted publishing instead.
+# PYPI_TOKEN=

nlweb_widget-0.9.12/.env.example

@@ -0,0 +1,56 @@
+# Core
+# Disabled by default: protects a fresh domain from accidental projection/retrieval.
+NLWEB_ENABLED=false
+NLWEB_PREFIX=/nlweb
+NLWEB_SITE=default
+NLWEB_RETRIEVAL_STORE=memory
+# Optional Haystack InMemory semantic retrieval
+# NLWEB_RETRIEVAL_STORE=haystack-memory
+NLWEB_CONTENT_SYNC_ENABLED=true
+NLWEB_CONTENT_SYNC_ON_STARTUP=false
+NLWEB_CONTENT_SOURCES_FILE=./nlweb-sources.json
+NLWEB_CONTENT_SYNC_STATE_FILE=.nlweb-sync-state.json
+NLWEB_CONTENT_SYNC_INTERVAL_SECONDS=900
+
+# Optional PostgreSQL + pgvector
+# NLWEB_RETRIEVAL_STORE=pgvector
+# NLWEB_POSTGRES_DATABASE_URL=postgresql+asyncpg://nlweb:nlweb@localhost:5432/nlweb
+# NLWEB_PGVECTOR_DIMENSIONS=384
+
+# Optional Neo4j
+# NLWEB_RETRIEVAL_STORE=neo4j
+# NLWEB_NEO4J_URI=neo4j://localhost:7687
+# NLWEB_NEO4J_USERNAME=neo4j
+# NLWEB_NEO4J_PASSWORD=
+# NLWEB_NEO4J_DATABASE=neo4j
+# NLWEB_NEO4J_VECTOR_DIMENSIONS=384
+
+# Optional Qdrant Server / Cloud
+# NLWEB_RETRIEVAL_STORE=qdrant
+# NLWEB_QDRANT_URL=http://localhost:6333
+# NLWEB_QDRANT_API_KEY=
+# NLWEB_QDRANT_COLLECTION=nlweb_documents
+# NLWEB_QDRANT_DIMENSIONS=384
+
+# Optional Qdrant Edge (embedded/local, no server required)
+# NLWEB_RETRIEVAL_STORE=qdrant_edge
+# NLWEB_QDRANT_EDGE_PATH=./.nlweb-qdrant-edge
+# NLWEB_QDRANT_EDGE_DIMENSIONS=384
+
+# Optional SQLite + sqlite-vec hybrid retrieval (FTS5 + vector KNN)
+# Install with: uv sync --extra sqlite
+# NLWEB_RETRIEVAL_STORE=sqlite
+# NLWEB_SQLITE_PATH=./.nlweb-sqlite/nlweb.db
+# NLWEB_SQLITE_DIMENSIONS=384
+
+# Optional local semantic embeddings (used by Haystack/Qdrant/PostgreSQL/Neo4j when
+# an embedding provider is not injected). The default is multilingual and light enough
+# for local development. For E5 models, query/passage prefixes are applied automatically.
+# NLWEB_EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+# NLWEB_EMBEDDING_QUERY_PREFIX=
+# NLWEB_EMBEDDING_DOCUMENT_PREFIX=
+# NLWEB_EMBEDDING_DEVICE=cpu
+
+# Optional unstructured document ingestion via Docling for ContentSourceKind.CUSTOM.
+# Install with: uv sync --extra documents
+NLWEB_TEST_ENV=dev # Indicates whether tests for governance tests (manifests) needed to be performed

nlweb_widget-0.9.12/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @maintainers

nlweb_widget-0.9.12/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Change summary
+
+## Manifest impact
+
+## Validation
+- [ ] pytest
+- [ ] ruff
+- [ ] build
+- [ ] docs updated

nlweb_widget-0.9.12/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 0

nlweb_widget-0.9.12/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+on: [push,pull_request]
+permissions: {contents: read}
+jobs:
+ core:
+  runs-on: ubuntu-latest
+  strategy: {matrix: {python: ["3.10","3.11","3.12","3.13","3.14"]}}
+  steps:
+   - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+     with:
+       persist-credentials: false
+   - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+   - run: uv python install ${{ matrix.python }}
+   - run: uv sync --dev --all-extras --python ${{ matrix.python }}
+   - run: uv run --python ${{ matrix.python }} pytest
+   - run: uv run --python ${{ matrix.python }} ruff check .
+   - run: uv run --python ${{ matrix.python }} ruff format --check .
+   - run: uv build

nlweb_widget-0.9.12/.github/workflows/release.yml

@@ -0,0 +1,124 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+# Default to read-only; grant write permissions only to jobs that need them.
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-release
+  queue: max
+
+jobs:
+  build:
+    name: Validate, test, and build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+
+      - name: Install release Python
+        run: uv python install 3.12
+
+      - name: Install release dependencies
+        run: uv sync --dev --all-extras --python 3.12
+
+      - name: Verify tag matches project version
+        shell: bash
+        run: |
+          VERSION=$(uv run --python 3.12 python - <<'PY'
+          import tomllib
+          with open("pyproject.toml", "rb") as f:
+              print(tomllib.load(f)["project"]["version"])
+          PY
+          )
+          test "v${VERSION}" = "${GITHUB_REF_NAME}"
+
+      - name: Test
+        run: uv run --python 3.12 pytest
+
+      - name: Lint
+        run: uv run --python 3.12 ruff check .
+
+      - name: Format check
+        run: uv run --python 3.12 ruff format --check .
+
+      - name: Build distributions
+        run: uv build --python 3.12
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 30
+
+  attest:
+    name: Attest build provenance
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@e8998f949152b193b063cb0ec769d69d929409be # v2.4.0
+        with:
+          subject-path: "dist/*"
+
+  github-release:
+    name: Create GitHub release
+    needs: [build, attest]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4
+        with:
+          generate_release_notes: true
+          files: "dist/*"
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, attest]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish to PyPI via trusted publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1 v1.14.3

nlweb_widget-0.9.12/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]
+dist/
+build/
+.env
+docs-private/
+governance-artifacts/
+
+.nlweb-sync-state.json
+
+.env.agentic.coding
+.env.agentic.coding.*
+!.env.agentic.coding.example

nlweb_widget-0.9.12/.nlweb-build-manifest.toml

@@ -0,0 +1,144 @@
+[manifest]
+kind = "canonical-build-manifest"
+schema_version = "2.0"
+package_version = "0.9.12"
+mutation_round = "release"
+mutation_candidate = "nlweb-widget-0.9.12"
+distribution_name = "nlweb-widget"
+import_namespace = "nlweb_widget"
+build_mode = "forward-only"
+genesis_baseline_immutable = true
+
+[governance]
+active_revision_manifest_sha256 = "a6417d4294d7e5d86ae21c7fa890d56d64bc60687625c80892e28379d248e3fb"
+active_revision_manifest = "revision-iteration-manifest-0.9.12.toml"
+active_revision_manifest_required = true
+active_revision_manifest_hash_required = true
+only_declared_iteration_changes_permitted = true
+unapproved_mutation_is_build_blocking = true
+release_approved = true
+
+[genesis]
+package_sha256 = "cf22dcb24707a22a2f34a7565b30da73b221bc359e42ad9f6f85a17293f59c02"
+docs_sha256 = "a2cfb30155bb3686ee0116266edeb4770e78fffd3c5718ae9389c9fa9ec53c0a"
+immutable = true
+
+[baseline_transition]
+success_action = "promote-successful-result-to-next-baseline"
+failure_action = "retain-current-baseline"
+rollback = "explicit-only"
+rollback_requires_hash_address = true
+
+[recovery]
+historical_capability_recovery = true
+protected_capability_inventory_required = true
+omission_point_recorded = true
+reference_implementation_internals_forbidden = true
+
+[providers]
+postgres_pgvector_optional = true
+neo4j_optional = true
+haystack_optional = true
+qdrant_optional = true
+qdrant_edge_optional = true
+sqlite_vec_optional = true
+sqlite_vec_pin = "0.1.8"
+docling_optional = true
+sentence_transformers_optional = true
+embedding_provider_injected = true
+provider_tests_conditional = true
+
+[protocol]
+ask = "/ask"
+mcp = "/mcp"
+discovery = "/.well-known/nlweb"
+health = "/health"
+ask_is_normative = true
+mcp_is_binding = true
+discovery_is_non_normative_metadata = true
+health_is_operational = true
+root_domain_default = true
+protocol_source_review_required = true
+
+[lifecycle]
+enabled_setting = "NLWEB_ENABLED"
+enabled_default = false
+projection_safeguard_only = true
+widget_owned_state = "effective_state"
+admin_lifecycle_extension_external = true
+
+[content_projection]
+source_registry_loading = true
+startup_projection = true
+relative_source_paths_resolved_against_registry = true
+
+[ecosystem]
+master_manifest = "nlweb-widget-ecosystem-manifest.toml"
+examples_repository = "nlweb-widget-examples"
+examples_are_published_to_pypi = false
+examples_dependencies_must_not_enter_runtime = true
+examples_are_independent_lifecycle = true
+
+[structure]
+framework_neutral_core = true
+integrations_are_thin_adapters = true
+adapter_pattern = "*_integration.py"
+
+[examples]
+repository = "nlweb-widget-examples"
+kept_out_of_widget_repository = true
+[tests]
+all_test_imports_must_be_satisfied_by_dev_group = true
+fresh_uv_sync_is_a_required_gate = true
+required = ["unit", "integration", "packaging"]
+python_minimum = "3.10"
+live_llm_required = false
+external_network_required = false
+examples_test_suite_is_external = true
+
+[docs]
+independent_pyproject_required = true
+static_docs_project_must_not_require_editable_build = true
+zensical_required = true
+role_based = true
+protocol_contract_required = true
+
+[vscode]
+package_test_tasks_required = true
+package_build_task_required = true
+example_tasks_forbidden = true
+aggregate_visibility_demo_task_forbidden = true
+
+[packaging]
+backend = "hatchling"
+uv_backed = true
+pyproject_required = true
+revision_manifest_shipped = true
+build_manifest_shipped = true
+sync_state_shipped = false
+
+[release]
+tag_pattern = "v{version}"
+tag_must_equal_project_version = true
+trusted_publishing = true
+provenance_attestation = true
+
+[forward_only]
+rules = [
+  "Never modify the genesis baseline.",
+  "Never introduce example-only dependencies into the published runtime graph.",
+  "Example applications and visibility infrastructure are governed by the examples repository.",
+  "Never apply undeclared revision changes.",
+  "A failed iteration cannot advance the baseline.",
+  "A successful iteration becomes the sole candidate next baseline.",
+  "Rollback is explicit, hash-addressed, and reviewable.",
+  "Build fails closed when governance metadata is inconsistent.",
+]
+
+[artifact_packaging]
+fail_closed = true
+forbidden_exact_names = [".env", ".nlweb-sync-state.json"]
+manifest = "nlweb-widget-ecosystem-manifest.toml"
+python_version_file = ".python-version"
+python_version = "3.10"
+forbidden_path_fragments = [".venv/", "__pycache__/", ".pytest_cache/", ".ruff_cache/", ".mypy_cache/", "*.pyc", "*.pyo", "dist/", "build/", ".env/", "node_modules/"]

nlweb_widget-0.9.12/.python-version

@@ -0,0 +1 @@
+3.10

nlweb_widget-0.9.12/.vscode/launch.json

@@ -0,0 +1,37 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: Current test file",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "${file}",
+        "-q"
+      ]
+    },
+    {
+      "name": "Python: Package tests",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "tests",
+        "-q"
+      ]
+    },
+    {
+      "name": "Python: SQLite provider test",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "tests/unit/test_optional_stores.py",
+        "-k",
+        "sqlite",
+        "-q"
+      ]
+    }
+  ]
+}

nlweb_widget-0.9.12/.vscode/tasks.json

@@ -0,0 +1,93 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "test-all",
+      "type": "shell",
+      "command": "uv run pytest",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-unit",
+      "type": "shell",
+      "command": "uv run pytest tests/unit",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-integration",
+      "type": "shell",
+      "command": "uv run pytest tests/integration",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-packaging",
+      "type": "shell",
+      "command": "uv run pytest tests/packaging",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-optional-haystack-memory",
+      "type": "shell",
+      "command": "uv run pytest tests/unit/test_optional_stores.py -k haystack",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-optional-qdrant-edge",
+      "type": "shell",
+      "command": "uv run pytest tests/unit/test_optional_stores.py -k qdrant_edge",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-optional-qdrant-server",
+      "type": "shell",
+      "command": "uv run pytest tests/unit/test_optional_stores.py -k 'qdrant and not qdrant_edge'",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-optional-postgres-pgvector",
+      "type": "shell",
+      "command": "uv run pytest tests/unit/test_optional_stores.py -k postgres",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "test-optional-neo4j",
+      "type": "shell",
+      "command": "uv run pytest tests/unit/test_optional_stores.py -k neo4j",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "build-package",
+      "type": "shell",
+      "command": "uv build",
+      "problemMatcher": [
+        "$python"
+      ]
+    },
+    {
+      "label": "Provider: sqlite \u2014 test",
+      "type": "shell",
+      "command": "uv run pytest tests/unit/test_optional_stores.py -k sqlite",
+      "problemMatcher": [
+        "$python"
+      ]
+    }
+  ]
+}

nlweb_widget-0.9.12/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Project
+`nlweb-widget` is a framework-neutral Python library that exposes an authoritative domain-data projection through the NLWeb protocol. The published runtime is intentionally lean; optional providers, framework adapters, and reference examples remain separated.
+
+## Authoritative references
+- Read the active `revision-iteration-manifest-*.toml` and `.nlweb-build-manifest.toml` before mutation work.
+- Treat `ARCHITECTURE.md`, `MUTATION.md`, `docs-provider-evaluations.md`, tests, and public docs as repository evidence; do not invent missing contracts.
+- Preserve the forward-only baseline and hash-addressed rollback policy.
+
+## Change boundaries
+- Do not modify an immutable baseline or historical candidate.
+- Do not introduce example-only dependencies into the runtime package.
+- Do not break public APIs/import paths/endpoints/configuration/provider contracts.
+- Protocol changes are limited to conformance corrections, normative failure semantics, or additive optional capabilities.
+- Keep framework integrations thin and keep authoritative application data separate from AI-facing retrieval projections.
+- Avoid opportunistic refactors, renames, dependency upgrades, or unrelated cleanup.
+
+## Commands
+- Install: `uv sync --dev`
+- Tests: `uv run pytest`
+- Lint: `uv run ruff check .`
+- Format check: `uv run ruff format --check .`
+- Build: `uv build`
+- Optional full dependency QA: `uv sync --dev --all-extras`
+
+## Verification
+Run the smallest relevant checks first, then the full declared gates for release work. Configured optional-provider tests must exercise the real configured backend; unconfigured providers are skipped. A configured-but-unavailable provider is a failure.
+
+## Security
+Never commit credentials, tokens, private keys, `.env`, or `.env.agentic.coding`. Use `.env.agentic.coding.example` only as a classification/template file. Never place production secrets in examples, tests, CI logs, or generated bundles.
+
+## Agent workflow
+For non-trivial work: inspect → plan → smallest coherent edit → synchronize manifests/docs/tests → validate → report hashes and remaining risks. Human approval remains required for release promotion, rollback, credential use, and changes to protected agent/governance files.

nlweb_widget-0.9.12/ARCHITECTURE.md

@@ -0,0 +1,43 @@
+# Architecture
+
+`nlweb-widget` is deliberately split into stable protocol/core abstractions and optional provider implementations.
+
+```text
+web framework adapter
+        |
+        v
+  NLWeb protocol core
+        |
+        +---- authoritative content ingestion
+        |
+        +---- RetrievalProvider boundary
+                 |
+                 +-- memory
+                 +-- Haystack InMemory (optional)
+                 +-- PostgreSQL + pgvector (optional)
+                 +-- Neo4j (optional)
+                 +-- Qdrant Server/Cloud (optional)
+                 +-- Qdrant Edge (optional, separate in-process path)
+```
+
+## Compatibility boundary
+
+The public `NLWebWidget`, request/response models, retrieval protocols, and framework adapters remain the stable consumer-facing surface. Provider libraries are implementation details behind those interfaces.
+
+## Retrieval
+
+All semantic providers receive an injected `EmbeddingProvider` or use the optional local sentence-transformers helper. This keeps model choice outside store implementation and prevents incompatible vector dimensions from being silently mixed.
+
+## Neo4j
+
+Schema and vector-index DDL remain explicit Cypher. On Neo4j 2026.01+ the store uses the `SEARCH` clause for vector retrieval; older supported servers use the legacy vector procedure as a compatibility path.
+
+## Content ingestion
+
+Structured Schema.org/JSON-LD, web-page JSON-LD, RSS/Atom, sitemap, database, and custom callable sources remain supported. `CUSTOM` additionally has an optional Docling-backed document adapter for common unstructured files. Optional parsing libraries are not part of the base runtime dependency set.
+
+## Protocol compliance
+
+The `/ask` core owns the complete NLWeb v0.55 request envelope (`query`, `context`, `prefer`, `meta`), applies site/domain filters, emits the `_meta` response envelope, and supports the two normative response formats additively. Streaming remains an explicit transport capability not claimed by this core; a complete response is returned with `_meta.streaming=false` when requested.
+
+`/mcp` has an independent MCP binding contract. `tools/list` exposes only capabilities actually implemented by the widget, `tools/call` maps application failures to `isError=true`, and unknown tools/invalid JSON-RPC requests use MCP protocol errors. NLWeb reference implementation internals are never imported.

nlweb_widget-0.9.12/AUTHORITATIVE-DOMAIN-DATA-CONTRACT.md

@@ -0,0 +1,55 @@
+# Shared NLWeb Widget authoritative domain data contract
+
+Status: approved planning baseline; implementation candidates are pending local-QA approval. This document is shared by the Widget and Examples mutation iterations. Official wire behavior is governed by the [NLWeb Specification](https://nlweb.ai/docs/specification), currently reviewed at v0.55 for the SSE event contract.
+
+## Authority and precedence
+
+1. Applicable official NLWeb and MCP protocol requirements govern wire behavior.
+2. The Widget owns correct protocol serialization and transport behavior. An Examples convention cannot force or justify a conflicting Widget behavior.
+3. The approved source-data contract governs how examples identify artifacts and retain source metadata.
+4. Consumer-selected manifests and optional metadata may extend behavior only when they do not override standardized field semantics or required response structures.
+
+Any suspected conflict must be recorded with the conflicting requirements, affected boundary, evidence, and proposed resolution. It is not silently considered approved.
+
+## Result serialization
+
+- For conversational-search responses, a requested `summarize` mode produces a result item with `@type: "SearchSummary"` (or a justified domain-specific type) and `text` containing the summary.
+- A top-level `summary` property must not substitute for that result item.
+- If the mode preference includes `summarize` among multiple comma-separated modes, the Widget must include a summary item.
+- Result objects should expose the relevant authoritative schema properties at the result level rather than a private implementation wrapper such as `schema_object`.
+- A suitable source `@type` is preserved. A manifest-declared type is a fallback only when the structured source has no suitable type.
+- Optional grounding metadata must not be used to replace or redefine protocol fields. Its allowed shape and placement must conform to the applicable official specification, not merely to the examples manifest.
+
+## Artifact identity and URL precedence
+
+- Artifact identity is independent from chunk identity. All chunks for one artifact share the same canonical artifact URL.
+- Chunk uniqueness remains in document IDs and internal chunk metadata. Synthetic `#chunk-N` fragments must not be added.
+- A suitable `url` wins over `@id` for the artifact URL when both are present. Preserve a distinct `@id` where it remains useful as schema identity.
+- Converter-provided URLs are retained. Configured registry URL fallbacks are only used when suitable document/converter URLs are absent.
+- A configured fallback that represents a base path receives the artifact filename. A filename alone never proves a public evidence URI exists.
+
+## Optional inbox evidence manifest
+
+The Examples candidate defines an optional version-1 `nlweb-evidence-manifest.json` control file. Each `artifacts[]` entry has a safe relative `artifact` key and may contain `type` and `grounding`.
+
+- The manifest is not ingested as ordinary prose.
+- Manifest type is a fallback only; suitable source type wins.
+- Grounding supplied by the consumer is persisted as a complete JSON object unchanged at the metadata boundary. If source-schema and metadata grounding are both present and differ, the Widget reports a source-metadata failure instead of silently overwriting either value.
+- Conflicting source and manifest grounding is an explicit ingestion error, not a silent overwrite.
+- No manifest entry means no manifest-declared evidence URI. Other valid source grounding remains possible.
+- A declared URI is a consumer assertion, not proof of public reachability or authenticity. Never expose private paths or fabricate public URLs.
+
+## HTTP streaming contract
+
+When `prefer.streaming` is true on HTTP `/ask`, the Widget must return `text/event-stream` using Server-Sent Events. The v0.55 specification defines `start` (with `_meta.streaming: true`), indexed `result` events whose `item` matches the non-streaming result-item shape, optional `error` events using the failure response structure, and one `complete` event. The completion `_meta` must preserve `session_context` when present. Non-streaming requests retain the single JSON response. Framework adapters must not claim streaming support unless they implement the actual SSE transport; MCP remains its own binding.
+
+## Independent mutation ownership
+
+Widget iteration owns `/ask`, response formats, result projection, summary item structure, grounding serialization, streaming transport, and MCP protocol behavior. Examples iteration owns URL normalization in example ingestion, optional manifest parsing, source type precedence, metadata persistence, sample data, and documentation. Both use the same contract revision but have independent candidates, QA records, hashes, and promotion gates.
+
+## Known limits requiring explicit QA status
+
+- This local sandbox has Python 3.13 but no Python 3.12 installation for the Examples project's declared environment; offline sync cannot provision it.
+- Haystack is declared in the Examples dependencies but is not installed in this sandbox. The actual MultiFileConverter path therefore remains unverified here; installation was attempted but blocked by DNS/network unavailability.
+- Streaming is implemented in the candidate, but only the FastAPI route has a direct end-to-end SSE test in this sandbox; the Starlette, Django, Flask, and stdlib adapters still require framework-specific conformance tests.
+- Before promotion, the maintainer must confirm exact applicable NLWeb/MCP specification revisions for the supported release matrix and rerun QA in the supported clean environment.