diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..e571614
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,80 @@
+name: Bug report
+description: Report a reproducible problem with boundver.
+title: "bug: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve boundver. Remove secrets and proprietary source before submitting.
+  - type: input
+    id: version
+    attributes:
+      label: boundver version
+      description: Paste the output of `boundver --version`.
+      placeholder: boundver 0.10.0
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Include Python, operating system, and Git versions.
+      placeholder: Python 3.12, Ubuntu 24.04, Git 2.43
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Describe the observed behavior and its impact.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Provide the smallest repository layout, sanitized config, and commands that reproduce the problem.
+      placeholder: |
+        1. Create ...
+        2. Run `boundver ...`
+        3. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Relevant output
+      description: Paste logs, tracebacks, or JSON output. Remove credentials and sensitive paths.
+      render: shell
+  - type: dropdown
+    id: interface
+    attributes:
+      label: Where did this occur?
+      options:
+        - CLI
+        - GitHub Action
+        - Python API
+        - Packaging or installation
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Submission checks
+      options:
+        - label: I searched existing issues for this problem.
+          required: true
+        - label: I removed secrets and proprietary content from this report.
+          required: true
+        - label: This is not a vulnerability; security reports belong in private vulnerability reporting.
+          required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..a2d00f6
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://github.com/yzm1/boundver#readme
+    about: Read the overview, quick start, and links to detailed guides.
+  - name: Private security report
+    url: https://github.com/yzm1/boundver/security/advisories/new
+    about: Report suspected vulnerabilities privately; do not open a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..1828733
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,43 @@
+name: Feature request
+description: Suggest an improvement to boundver.
+title: "feature: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Describe the user problem first. Concrete workflows help evaluate the smallest useful solution.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or workflow
+      description: Who encounters this problem, and what are they trying to accomplish?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed outcome
+      description: Describe the behavior you would like, including a CLI or config example when relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What workarounds or other designs have you tried?
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: Compatibility considerations
+      description: Note any effect on lockfiles, config, exit codes, providers, or CI integrations.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Submission checks
+      options:
+        - label: I searched existing issues and documentation for this request.
+          required: true
+        - label: I can help test or document this change if it is accepted.
+          required: false
diff --git a/.github/actions/boundver/action.yml b/.github/actions/boundver/action.yml
deleted file mode 100644
index 6fe8277..0000000
--- a/.github/actions/boundver/action.yml
+++ /dev/null
@@ -1,68 +0,0 @@
-name: "boundver verify"
-description: "Zero-setup boundver verification with optional diff-on-failure"
-inputs:
-  config:
-    description: "Path to boundary config"
-    required: false
-    default: "boundary.config.json"
-  lock:
-    description: "Path to lockfile"
-    required: false
-    default: "boundary.lock.json"
-  source:
-    description: "Fingerprint source mode"
-    required: false
-    default: "head"
-  components:
-    description: "Optional comma-separated component subset"
-    required: false
-    default: ""
-  python-version:
-    description: "Python version used by action"
-    required: false
-    default: "3.12"
-  version:
-    description: "boundver version to install (default: latest from PyPI, or '.' for local)"
-    required: false
-    default: "boundver"
-  show-diff-on-failure:
-    description: "Generate and print lockfile diff on verify failure"
-    required: false
-    default: "true"
-runs:
-  using: "composite"
-  steps:
-    - name: Setup Python
-      uses: actions/setup-python@v6
-      with:
-        python-version: ${{ inputs.python-version }}
-
-    - name: Install boundver
-      shell: bash
-      run: |
-        python -m pip install --upgrade pip
-        pip install "${{ inputs.version }}"
-
-    - name: Verify lockfile
-      shell: bash
-      run: |
-        set -euo pipefail
-        EXTRA_ARGS=()
-        if [ -n "${{ inputs.components }}" ]; then
-          EXTRA_ARGS+=(--components "${{ inputs.components }}")
-        fi
-        boundver verify \
-          --config "${{ inputs.config }}" \
-          --lock "${{ inputs.lock }}" \
-          --source "${{ inputs.source }}" \
-          "${EXTRA_ARGS[@]}"
-
-    - name: Diff on failure
-      if: ${{ failure() && inputs.show-diff-on-failure == 'true' }}
-      shell: bash
-      run: |
-        set -euo pipefail
-        boundver generate --config "${{ inputs.config }}" --out /tmp/boundary.lock.new.json --source "${{ inputs.source }}" || true
-        if [ -f "/tmp/boundary.lock.new.json" ]; then
-          boundver diff "${{ inputs.lock }}" /tmp/boundary.lock.new.json || true
-        fi
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..51f1370
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,17 @@
+## What changed
+
+Describe the problem and the resulting behavior. Link related issues with
+`Fixes #...` when appropriate.
+
+## How it was verified
+
+List the tests or manual checks you ran.
+
+## Checklist
+
+- [ ] The change is focused and does not include unrelated generated files.
+- [ ] Tests cover new behavior or the reason tests are unnecessary is explained.
+- [ ] User-facing CLI, config, schema, exit-code, or lockfile changes are documented.
+- [ ] Compatibility and migration impact has been considered.
+- [ ] `CHANGELOG.md` is updated for a user-visible change.
+- [ ] No secrets, private data, or proprietary fixtures are included.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3539962..09c7041 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -82,17 +82,36 @@ jobs:
       - name: Build package
         run: |
           python -m pip install --upgrade pip
-          pip install build
-          python -m build
-
-      - name: Install and smoke-test
-        run: |
-          pip install dist/*.whl
-          boundver --help
-          boundver init --out /tmp/test.config.json --force
+          bash scripts/packaging_smoke.sh
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
+
+  action:
+    name: Public Action contract
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Verify with the public interface
+        uses: ./
+        with:
+          facets: boundary,compat
+
+      - name: Exercise hostile input as data
+        id: hostile
+        continue-on-error: true
+        uses: ./
+        with:
+          components: 'boundver; touch /tmp/boundver-action-injected'
+
+      - name: Confirm input was not executed
+        shell: bash
+        run: test ! -e /tmp/boundver-action-injected
diff --git a/.github/workflows/manual-test.yml b/.github/workflows/manual-test.yml
deleted file mode 100644
index 93cd8c7..0000000
--- a/.github/workflows/manual-test.yml
+++ /dev/null
@@ -1,39 +0,0 @@
-name: Test manually
-
-on:
-  workflow_dispatch:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.8", "3.12"]
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Install dev deps
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e .[dev]
-
-      - name: Run tests
-        run: pytest -q
-
-      - name: Build package
-        run: python -m build
-
-      - name: Install built wheel
-        run: pip install dist/*.whl
-
-      - name: CLI smoke
-        run: |
-          boundver --help
-          boundver init --out /tmp/boundary.config.json --force
diff --git a/.github/workflows/pr-lite.yml b/.github/workflows/pr-lite.yml
deleted file mode 100644
index a32cc87..0000000
--- a/.github/workflows/pr-lite.yml
+++ /dev/null
@@ -1,33 +0,0 @@
-name: PR lite checks
-
-on:
-  pull_request:
-    paths:
-      - "src/**"
-      - "tests/**"
-      - "pyproject.toml"
-      - "boundary.config.schema.json"
-      - ".github/workflows/pr-lite.yml"
-
-jobs:
-  lite:
-    runs-on: ubuntu-latest
-    concurrency:
-      group: pr-lite-${{ github.ref }}
-      cancel-in-progress: true
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.12"
-
-      - name: Install
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e .[dev]
-
-      - name: Test
-        run: pytest -q
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index f5e471d..79384b6 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -6,26 +6,110 @@ on:
       - "v[0-9]+.[0-9]+.[0-9]+"
 
 jobs:
-  publish:
+  verify-release:
     runs-on: ubuntu-latest
-    environment: pypi
     permissions:
-      id-token: write
       contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
-      - name: Build package
+      - name: Validate tag and package version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          python - "$RELEASE_TAG" <<'PY'
+          import pathlib
+          import sys
+          import tomllib
+
+          expected = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"]
+          actual = sys.argv[1]
+          if actual != f"v{expected}":
+              raise SystemExit(f"tag {actual!r} does not match package version v{expected}")
+          PY
+
+      - name: Test and build
         run: |
           python -m pip install --upgrade pip
-          pip install build
+          python -m pip install -e '.[dev]' twine
+          pytest -q
           python -m build
+          python -m twine check dist/*
+          python -m zipfile --list dist/*.whl
+          tar -tzf dist/*.tar.gz
+
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: verify-release
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    runs-on: ubuntu-latest
+    needs: publish
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout the released commit
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Download verified distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+
+      - name: Advance the stable v0 tag
+        shell: bash
+        env:
+          RELEASE_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          git tag --force v0 "$RELEASE_SHA"
+          git push origin refs/tags/v0 --force
+          remote_sha=$(git ls-remote origin refs/tags/v0 | awk '{print $1}')
+          test "$remote_sha" = "$RELEASE_SHA"
+
+      - name: Create the GitHub Release from verified artifacts
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+            gh release upload "$RELEASE_TAG" dist/* --clobber
+          else
+            gh release create "$RELEASE_TAG" dist/* \
+              --verify-tag \
+              --title "boundver ${RELEASE_TAG#v}" \
+              --generate-notes
+          fi
diff --git a/.pre-commit-hooks.yaml b/.pre-commit-hooks.yaml
index e89878a..ebddfa3 100644
--- a/.pre-commit-hooks.yaml
+++ b/.pre-commit-hooks.yaml
@@ -2,11 +2,12 @@
   name: boundver verify
   language: python
   entry: boundver
-  args: [verify, --source, head]
+  args: [verify, --source, index]
   pass_filenames: false
   description: >
-    Verify that boundary.lock.json is up to date with the current HEAD.
-    Fails (exit 1) when fingerprints drift; blocks the commit until you run
+    Verify that boundary.lock.json is up to date with the staged snapshot.
+    Fails with the documented facet-specific exit code when fingerprints drift;
+    blocks the commit until you run
     `boundver generate` and stage the updated lockfile.
   additional_dependencies: []
   always_run: true
@@ -16,10 +17,10 @@
   name: boundver generate
   language: python
   entry: boundver
-  args: [generate, --source, head]
+  args: [generate, --source, index]
   pass_filenames: false
   description: >
-    Regenerate boundary.lock.json from HEAD. Use this hook on the
+    Regenerate boundary.lock.json from the staged snapshot. Use this hook on the
     pre-commit stage to auto-update the lockfile before committing.
   additional_dependencies: []
   always_run: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7721dc6..2f88e5a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,54 +2,119 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on Keep a Changelog.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+No changes yet.
+
+## [0.10.0] - 2026-08-12
+
+### Breaking changes
+
+- Lockfiles now use `boundary-lock/v2` and a length-delimited, domain-separated
+  hashing format. This removes ambiguous byte framing in v1.
+- **Migration:** v1 fingerprints cannot be converted safely. Regenerate them from
+  repository content with `boundver generate` after upgrading. The
+  `migrate-lock` command reports this requirement instead of relabeling old
+  fingerprints.
+- Git-backed source modes enumerate tracked files only. Untracked working-tree
+  files no longer enter fingerprints implicitly.
+
 ### Added
-- Behavior tier: fourth fingerprint (`behavior`) forming containment hierarchy `exact ⊇ behavior ⊇ boundary`; hashes user-declared behavioral-contract files; `behavior` slice mode; advisory warning when `behavior.paths` is not a superset of `boundary.paths`.
-- Provider architecture Phases 1–3: `BoundaryProvider` protocol with `resolve()`, `validate_config()`, `explain_diff()`; `JsonCanonicalProvider` (RFC 8785); `OpenApiCanonicalProvider` (strips non-contract content).
-- Custom provider loading: `--allow-custom-providers` flag; `custom.*` namespace enforcement; module/class validation.
-- `boundver why <component>`: shows which facets drifted, change classification, modified files.
-- `boundver discover`: detects npm/pnpm workspaces, pyproject.toml, Cargo.toml, go.mod.
-- `boundver init --discover`: auto-generates config from discovered components.
-- Shell completions (bash/zsh/fish) via `boundver completions` subcommand.
-- Glob patterns in boundary source paths (`*`, `?`, `[`).
-- Config format support: `boundary.config.yaml` and `boundary.config.toml` alongside JSON.
-- Config includes/extends design (not yet implemented).
-- Batch git reads: `git cat-file --batch` for O(1) subprocess count.
-- Standalone `.pyz` build via `scripts/build_standalone.py`.
-- Docker image for CI without Python.
-- GitHub Action (`action.yml`) for marketplace.
-- Pre-commit hooks: `boundver-verify` and `boundver-generate`.
-- Lockfile migration: `boundver migrate-lock [--dry-run]`.
-- JSON schemas for CLI outputs (`spec/cli-output.*.schema.json`).
-- `--fail-fast` flag on `verify`.
-- Color TTY output with automatic suppression for piped/JSON output.
 
-### Fixed
-- Source-purity: all three modes (head/index/working-tree) are fully source-pure for enumeration and content reading.
-- Binary blob reads: `_git_cat_blob` and `_git_batch_cat` use bytes mode (no text-mode CRLF conversion).
-- Version extraction is source-aware via `_SourceAccessor.version_read_file`.
-- Option injection guards on git subprocess calls.
-- Size guardrails on file reads (10 MiB hash, 50 MiB blob).
-- Path traversal prevention with `_is_within` checks.
-- Structured exception hierarchy replacing broad `except Exception`.
+- Facet-scoped verification with `verify --facets` and
+  `defaults.verify_facets`. Drift outside the selected gate is reported as an
+  observation instead of failing the gate.
+- Severity-aware verification exit codes: `1` for exact or metadata drift, `3`
+  for behavior drift, `4` for boundary drift, and `5` for compatibility drift;
+  `2` remains reserved for usage or input errors.
+- `verify --update` for reviewing drift and refreshing the lockfile in one
+  command.
+- A `behavior` fingerprint and behavior-mode slices for declared behavioral
+  contracts such as defaults, configuration, and migrations.
+- Glob patterns in `boundary.paths` and `behavior.paths`; newly tracked matching
+  files change the corresponding fingerprint.
+- Validated component `consumers` relationships. Boundary and compatibility
+  drift now identifies declared downstream consumers.
+- Git-aware `discover` and `init --discover` support for npm, Python, Cargo, and
+  Go manifests. Discovery uses tracked files, skips duplicate component
+  directories, and emits ecosystem-specific version fields.
+- Built-in and custom boundary-provider protocols, including JSON canonical and
+  OpenAPI canonical providers, provider validation, metadata, and diff
+  explanations.
+- `why`, `discover`, shell-completion, `validate-config`, `check-config`, and
+  `migrate-lock` commands, plus `--fail-fast` verification.
+- JSON, YAML, and TOML config loading, with a conditional `tomli` dependency for
+  Python 3.9-3.10.
+- JSON schemas for configuration, v2 lockfiles, and machine-readable CLI output.
+- Distribution options for PyPI, a standalone `.pyz`, Docker, pre-commit, and a
+  hardened composite GitHub Action suitable for Marketplace use.
+- Public project metadata and community files for security reports, support,
+  contributions, issue reports, and pull requests.
 
 ### Changed
-- Exit code semantics: 1 = drift detected, 2 = usage/input error (config, missing files).
-- `generated_at` removed from lockfiles; deterministic output always.
-- `--json` flag replaced with `--format json|text`.
+
+- Lockfile output is deterministic and no longer includes `generated_at`.
+- Machine-readable commands use `--format json`; color is limited to interactive
+  text output.
+- Partial component generation reconciles removed components and recomputes all
+  configured slices, preventing stale aggregate fingerprints.
+- Config mutation commands refuse YAML or TOML output instead of silently
+  rewriting those files as JSON.
+- Strict config validation uses the schema bundled in installed wheels, not only
+  a schema found in a source checkout.
+- The GitHub Action now accepts structured inputs, installs the tagged action
+  source, preserves JSON output, and exposes issues, observations, and the
+  severity exit code.
+- The supported Python floor is now 3.9. Python 3.8 is upstream-EOL and cannot
+  use the Setuptools version required for modern SPDX package metadata.
+
+### Fixed
+
+- Generation now fails when exact, behavior, boundary, or compatibility inputs
+  cannot be computed; verification no longer accepts matching null digests.
+- Invalid `--changed-from` refs fail closed, and config-file changes select all
+  components for verification.
+- Hash framing no longer permits different path/content layouts to produce the
+  same digest.
+- NUL-delimited Git parsing preserves non-ASCII and unusual filenames across
+  HEAD, index, status, and diff operations.
+- Missing, malformed, truncated, oversized, and non-blob Git objects are
+  reported instead of being hashed as empty content.
+- OpenAPI canonicalization removes documentation fields only where they are
+  annotations; schema properties named `description`, `example`, or `x-*`
+  remain contract-significant.
+- Verification now checks component metadata, digest errors, filtered slices,
+  removed components, and removed slices as well as fingerprint values.
+- Custom providers use an isolated registry per operation and cannot be enabled
+  by repository configuration alone; callers must opt in explicitly.
+- Malformed non-object config and lockfile roots produce usage errors instead of
+  uncaught attribute errors.
+- Version extraction is source-aware, binary and symlink content remains
+  byte-accurate, and large-file guardrails fail with actionable errors.
+- GitHub Action inputs are passed through environment variables and shell arrays
+  to prevent command injection and JSON/stderr corruption.
 
 ## [0.9.1] - 2026-05-03
 
 ### Fixed
-- TOML regex fallback: anchor end-of-line to reject invalid TOML on Python 3.8–3.10 (no built-in `tomllib`).
-- Symlink hash parity: working-tree accessor now reads `os.readlink()` for symlinks, matching git blob storage.
+
+- TOML regex fallback: anchor end-of-line to reject invalid TOML on Python
+  3.8-3.10 when the built-in `tomllib` is unavailable.
+- Symlink hash parity: working-tree access reads `os.readlink()`, matching Git
+  blob storage.
 - Python 3.8 type annotation compatibility in test helpers.
-- CI: use `source=head` in examples test to avoid CRLF/LF hash mismatch across platforms.
+- CI examples use `source=head` to avoid cross-platform checkout conversion
+  differences.
 
 ### Added
-- Boundary extraction status model (`ok` / `partial` / `error`) per component in generated lockfiles.
-- Basic project governance docs: `LICENSE`, `CONTRIBUTING.md`.
+
+- Boundary extraction status (`ok`, `partial`, or `error`) for generated
+  component entries.
+- Basic project governance documents: `LICENSE` and `CONTRIBUTING.md`.
 - Tests for boundary extraction status behavior.
+
+[Unreleased]: https://github.com/yzm1/boundver/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/yzm1/boundver/releases/tag/v0.10.0
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..077853b
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,37 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in boundver welcoming and harassment-free for
+everyone, regardless of background, identity, experience, or level of
+contribution.
+
+## Expected behavior
+
+Examples of behavior that supports a healthy community include:
+
+- being respectful, patient, and constructive;
+- giving and accepting specific technical feedback in good faith;
+- acknowledging mistakes and correcting them;
+- focusing on what is best for users and the project.
+
+Unacceptable behavior includes harassment, discriminatory language, personal
+attacks, threats, sexualized content, deliberate disruption, or publishing
+someone else's private information without permission.
+
+## Scope and enforcement
+
+This code applies in project spaces and when representing the project elsewhere.
+The maintainer may edit or remove contributions that violate it and may warn,
+temporarily restrict, or permanently ban participants when necessary.
+
+To report a conduct concern, contact the maintainer through the
+[maintainer's GitHub profile](https://github.com/yzm1) and request a private
+conversation. Do not include sensitive details in a public issue. Reports will
+be handled as privately and promptly as practical. For abuse that occurs on
+GitHub, you may also use [GitHub's abuse reporting](https://support.github.com/contact/report-abuse).
+
+## Attribution
+
+This policy is adapted from the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9e6d8bf..f45b212 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ Thanks for your interest in improving boundver.
 
 ## Development setup
 
-- Python 3.8+
+- Python 3.9+
 - Git
 
 Run tests:
diff --git a/IMPLEMENTATION_PLAN.md b/IMPLEMENTATION_PLAN.md
deleted file mode 100644
index ad54ef7..0000000
--- a/IMPLEMENTATION_PLAN.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# Implementation Plan: boundver
-
-_Updated 2026-05-03 — 771 tests passing, 2 skipped (symlinks on Windows). Near-term, CLI polish, code health, distribution, provider Phases 1–3 complete. Behavior tier implemented. PyPI live._
-
----
-
-## Near-term
-
-### Portability
-
-- [x] Decouple `service-definition` boundary kind from core validation — dead code removed.
-- [x] Fail with actionable guidance when config references unavailable boundary sources — `version_source` validated in `validate_config`; boundary path error now includes `component/file` path and actionable hint; tests added.
-
-### Testing
-
-- [x] Per-module unit tests (canonical JSON, sha256, semver, TOML/YAML extraction) — `tests/test_versions.py` (parse_semver, JSON/TOML/YAML extraction, extract_version) and `tests/test_hashing.py` (canonical_json, sha256_hex, source_tree_digest) created; 65 new tests.
-- [x] Integration tests using temporary git repos (`git init` + commits in tmp dirs).
-- [x] Edge cases: no version source, vendored copy drift, repo with no commits.
-- [x] Parser coverage: 3-level TOML paths (`tool.poetry.version`), representative YAML patterns — covered in `tests/test_versions.py`.
-
-### Publishing
-
-- [x] Publish to PyPI — tag-triggered workflow (`on: push: tags: v*`); OIDC trusted publishing via `pypa/gh-action-pypi-publish`; `environment: pypi` with `id-token: write`; package live on PyPI as `boundver>=0.9.0`.
-
----
-
-## CLI polish
-
-- [x] `--format json|text` for all commands (`--json` replaced with `--format json|text`, `table` deferred).
-- [x] Document `--exit-code` behavior for `verify` — exit code table (0/1/2) added to README; `verify` subparser description updated with structured exit code semantics.
-- [x] Color output in TTY mode — `_green`, `_red`, `_yellow`, `_bold` helpers; applied to verify ok/fail, validate-config ok/fail, diff +/-/~, status warnings. Suppressed automatically for piped/JSON output.
-- [x] Shell completions (bash, zsh, fish) — `completions` subcommand added; static scripts for bash/zsh/fish embedded in `core.py`; works without a git repo; 6 tests added.
-
----
-
-## Code health
-
-- [x] Split `core.py` into modules: `_git.py`, `_hashing.py`, `_config.py`, `_lockfile.py`, `_diff.py`, `_output.py`, `_completions.py`. `core.py` is now a 406-line re-export shim + `main()`. All 297 tests pass.
-- [x] Batch git reads — `_git_batch_cat` implemented using `git cat-file --batch`; `source_tree_digest`, `boundary_paths_digest`, and `_content_only_digest` all use it for `head`/`index` sources, replacing O(N) subprocesses with O(1).
-- [x] Binary blob reads — `_git_cat_blob` uses binary subprocess (no text-mode CRLF conversion); `_read_path_content` for head/index uses it. Working-tree reads normalize CRLF→LF for cross-platform consistency.
-- [x] Shared utilities module — `_utils.py`: `SourceMode` enum (`head`/`index`/`working-tree`) inheriting from `str` for transparent string comparison; structured exception hierarchy (`BoundverError` → `ConfigError`, `LockfileError`, `ProviderError`, `GuardrailError`); `_is_glob`, `boundary_provider_name`, `_short` helpers migrated from scattered modules.
-
----
-
-## Documentation
-
-- [x] README: badges, comparison table, fixed stale `--json` flag references, docs index section.
-- [x] `docs/getting-started.md` — install → first config → first lockfile → CI step.
-- [x] `docs/gradual-adoption.md` — staged adoption from implicit provider to full boundary + compat coverage.
-- [x] `docs/ci-cookbook.md` — GitHub Actions, GitLab, cache keys, pre-commit, JSON output scripting.
-- [~] Docs site (mkdocs-material): rendered site with nav, search, and versioning — **DEFERRED**.
-
----
-
-## Distribution
-
-- [x] GitHub Action (`action.yml`) — composite action; `uses: yzm1/boundver@main`; inputs: `command`, `args`, `version`; outputs: `exit-code`, `issues`.
-- [x] Standalone single-file download option — `scripts/build_standalone.py` produces `dist/boundver.pyz` (26 KB, no deps).
-- [x] Docker image for CI without Python — `Dockerfile` + `.dockerignore`; `docker run --rm -v "$(pwd):/repo" -w /repo boundver verify`.
-- [ ] Homebrew formula (stretch).
-- [x] Publish GitHub Action to marketplace — `action.yml` has all required fields (`name`, `description`, `author`, `branding: {icon: lock, color: blue}`); file is at repo root. **One manual step remaining:** create a versioned GitHub release and check "Publish this Action to the GitHub Marketplace" in the release UI. No code changes needed.
-
----
-
-## Future (v0.10.0+)
-
-- [ ] `boundver watch` — regenerate on save.
-
-  **Design:** Poll/watch the working tree for changes to any file under a declared component path or to the config file itself, then re-run `generate --source working-tree` with debounce.
-
-  - **Dependency:** optional `watchdog>=3` via `pip install boundver[watch]`; fall back to polling (`--poll`, 1 s interval) when unavailable.
-  - **Watched paths:** all component paths in config + the config file itself. Re-read config on config-file change so new components are picked up without restart.
-  - **Debounce:** 500 ms quiet period after last event before regenerating (configurable via `--debounce MS`).
-  - **Interface:** `boundver watch [--config FILE] [--out FILE] [--source working-tree] [--debounce MS] [--poll]`
-  - **Output:** on each regeneration, print a timestamped one-line summary of which component(s) changed and the resulting classification (`implementation-only` / `behavioral` / `boundary` / `breaking`). Full status on first run.
-  - **Exit:** clean on `SIGINT`/`SIGTERM`; non-zero if config is invalid at startup.
-  - **Scope:** generates only; does not verify against a committed lockfile (that is `pre-commit`'s job).
-  - **Implementation path:** thin wrapper around `generate_lockfile_for_components()` triggered by watchdog `FileSystemEventHandler`; no new core logic needed.
-
-- [ ] Config includes/extends.
-
-  **Design:** Two distinct mechanisms with separate semantics.
-
-  **`includes`** (additive merge):
-  ```json
-  {
-    "project": "platform",
-    "includes": ["services/billing/boundary.config.json", "services/auth/boundary.config.json"],
-    "slices": { "all": { "mode": "boundary", "components": ["billing", "auth"] } }
-  }
-  ```
-  - Paths are relative to the file containing `includes`.
-  - Included files' `components` and `slices` are merged into the root config.
-  - Conflict (same component or slice name) is a hard error at load time.
-  - Included files may themselves use `includes` (recursive); circular includes are detected and rejected.
-  - Included files' `defaults` are ignored — root `defaults` win.
-  - Max depth: 8 levels.
-
-  **`extends`** (inheritance / override):
-  ```json
-  {
-    "extends": "../../base.config.json",
-    "project": "billing",
-    "components": { "billing": { "path": ".", "boundary": { "provider": "openapi", "paths": ["openapi.yaml"] } } }
-  }
-  ```
-  - Inherits `defaults` and `providers` list from base; local values override.
-  - Does **not** inherit `components` or `slices` — those are always local to the extending file.
-  - Cannot extend a file that itself uses `extends` (single-level inheritance only; avoids deep chains).
-  - Primary use case: shared `defaults.compat_mode` and shared `providers` list across a monorepo.
-
-  **Security constraints (both mechanisms):**
-  - Included/extended paths must resolve within the repository root (`_is_within` check); escaping with `..` is a hard error.
-  - Paths are resolved relative to the referencing file, not `cwd`.
-
-  **Load-time implementation:** `load_config_file()` resolves includes/extends before returning; `validate_config()` operates on the merged result and sees no `includes`/`extends` keys. No changes to any downstream function signatures.
-- [x] Glob patterns in boundary sources — `fnmatch`-based glob support in `PathHashProvider.resolve()` and `_config.validate_config()`; `*`/`?`/`[` patterns expand against component files; `..` rejected; 10 new tests.
-- [x] Pre-commit hook integration — `.pre-commit-hooks.yaml` at repo root; `boundver-verify` and `boundver-generate` hooks; `language: python`; `always_run: true`.
-- [x] `boundver why <component>` — compares current fingerprints against the lockfile; shows which facets drifted (exact/behavior/boundary/compat), change-type classification, modified files under component path; exits 0 (up to date) / 1 (drifted) / 2 (error); shell completions updated; 8 new tests.
-- [x] Support `boundary.config.yaml` / `.toml` — `find_config_file()` probes alternatives when default `.json` is absent; `load_config_file()` dispatches on extension (JSON built-in, YAML via PyYAML, TOML via `tomllib`/`tomli`); all config-loading sites in `core.py` updated; 11 new tests. **474 tests pass**.
-
----
-
-## Product-model maturity (post-v1)
-
-- [x] Real provider architecture: `extract`, `normalize`, `digest`, `validate_config`, `explain_diff` interface — designed in `docs/design/07-provider-architecture.md`. Protocol: `BoundaryProvider` (resolve/validate_config/explain_diff), `ProviderContext`, `ResolvedBoundary`; registry; 3-phase migration plan; security constraints for custom providers.
-- [x] **Phase 1 — Protocol + built-in wrappers** (`src/boundver/providers.py`): `ProviderContext`, `ResolvedBoundary`, `BoundaryProvider` protocol; `PathHashProvider`, `ImplicitProvider`, `LeafProvider`, `OpenApiProvider`, `JsonFileProvider`, `PythonExportsProvider`, `TypeScriptExportsProvider`; provider registry; `compute_boundary()` (only SHA-256 call for boundary digests); `generate_lockfile()` now delegates to `compute_boundary()`. Added `tests/test_providers.py` (34 tests). **Zero digest drift — 352 tests pass**.
-- [x] **Phase 2 — `options` + custom provider loading**: `boundary.options` added to config schema; `providers` top-level config key validated; `load_custom_providers()` in `providers.py`; `--allow-custom-providers` flag on `generate`/`verify`/`validate-config`/`check-config`/`status`; `BOUNDVER_ALLOW_CUSTOM_PROVIDERS` env var; `custom.*` namespace enforced; `generate_lockfile()` raises if providers declared without flag; registry isolation in tests. **463 tests pass**.
-- [x] **Phase 3 — Semantic built-ins**: `JsonCanonicalProvider` (`json-canonical`) re-serialises JSON as RFC 8785 canonical form — stable across key reordering and whitespace. `OpenApiCanonicalProvider` (`openapi-canonical`) strips `info`/`servers`/`tags` top-level blocks and recursively removes `description`, `summary`, `externalDocs`, `example`, `examples`, and `x-*` extension keys — digest stable across docs edits, changes on endpoint/parameter/schema changes. Both registered at import time; `known_providers` updated in `_config.py`. 22 new tests (14 unit + 8 integration). **438 tests pass**.
-- [x] **Behavior tier** — fourth fingerprint (`behavior`) forming containment hierarchy `exact ⊇ behavior ⊇ boundary`; hashes user-declared behavioral-contract files (config, migrations, contract tests); `behavior` slice mode; `config_warnings()` emits non-fatal advisory when `behavior.paths` is not a superset of `boundary.paths`; `validate-config` surfaces warnings in yellow without failing; `_diff.py` classifies `exact+behavior` changes as "behavioral contract changed (API shape stable)"; lockfile schema, config schema, spec, and examples all updated; 30+ new tests. **771 tests pass**.
-- [ ] Semantic/canonical providers: TS/public API, Python/public symbol.
-- [ ] Multi-boundary components (REST/events/CLI/schema per component).
-- [ ] Dependency/impact model: component graph, `impact`, `affected`, `why` commands.
-- [ ] Richer identity model: clarify exact/boundary/compat/api-version separation.
-
----
-
-## Governance & contracts (post-v1)
-
-- [x] Migration policy: `migrate_lockfile()` in `_lockfile.py`; `MigrationError` for unknown schemas; `boundver migrate-lock [--lock FILE] [--dry-run]` CLI subcommand — reads, migrates, writes in-place (strips legacy `generated_at`); dry-run prints without writing; 12 new tests. **486 tests pass**.
-- [x] Stable machine contracts: JSON schemas for CLI outputs (verify, status, diff, discover) in `spec/cli-output.*.schema.json`; 6 conformance tests added (`tests/test_cli_output_schemas.py`).
-- [ ] Security model: custom provider execution policy, CI allowlists, path escape constraints.
-- [ ] Custom provider execution model: config shape (`type: command`/`type: python`), sandboxing, `--allow-custom-providers` flag.
-- [x] Resolve `generated_at` in deterministic mode — removed entirely; lockfiles are always deterministic; `git log` provides timestamps.
-- [ ] Maintainer sustainability: ownership/triage expectations, bus factor > 1.
-
----
-
-## Strategic checkpoints
-
-- Confirm at least one real team using boundver in CI; treat their friction as top priority.
-- Validate persona: CI/platform users → prioritize Action/docs over runtime rewrites.
-- [x] Dogfood boundver on itself — `boundary.config.json` tracks `src/boundver/` with all 11 source files as boundary paths; `boundary.lock.json` committed. Validated and generates cleanly.
-- Re-evaluate quarterly against Nx/Turborepo/Bazel/Pants overlap.
-
-## Non-goals (for now)
-
-- No rewrite (Go/Rust) before spec + adoption proven.
-- No plugin marketplace before provider interface and demand are clear.
-- No over-splitting modules before contracts stabilized.
-- No docs-site ceremony before spec + examples + CI path are solid.
-
----
-
-## Decisions
-
-- **CI cost control:** automated CI re-enabled at v0.9.0; see `docs/CI_REENABLE_PLAN.md`.
-- **Schema validation:** optional `jsonschema` for strict mode; stdlib fallback for zero-dep baseline.
-- **Terminology:** `boundary` is the only mode name. No `api` alias exists in schema or runtime.
-- **Lockfile determinism:** `generated_at` removed entirely. Lockfiles are always deterministic. Use `git log` for generation timestamps.
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..cc03a63
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,12 @@
+include CHANGELOG.md
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include LICENSE
+include README.md
+include SECURITY.md
+include SUPPORT.md
+include boundary.config.schema.json
+recursive-include docs *.md
+recursive-include examples *.json *.md *.py *.toml *.ts *.yaml
+recursive-include spec *.json *.md
+recursive-include tests *.py
diff --git a/README.md b/README.md
index ba61191..08eb941 100644
--- a/README.md
+++ b/README.md
@@ -1,294 +1,113 @@
-# boundver
+# boundver — know whether a change is internal, behavioral, API-facing, or breaking
 
+[![CI](https://github.com/yzm1/boundver/actions/workflows/ci.yml/badge.svg)](https://github.com/yzm1/boundver/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/boundver)](https://pypi.org/project/boundver/)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue)](https://pypi.org/project/boundver/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![No runtime dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](pyproject.toml)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/boundver)](https://pypi.org/project/boundver/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://github.com/yzm1/boundver/blob/main/LICENSE)
 
-**Automated change-type classification for components that lack static verification.**
+**boundver is Git-aware API contract and breaking-change detection for polyglot repositories.** It classifies component drift into exact, behavior, boundary, and compatibility facets, so CI can block consumer-impacting changes without rejecting every internal refactor.
 
-boundver answers four questions per component — *did anything change?*, *did the behavioral contract change?*, *did the declared boundary change?*, *is it still compatible?* — using content-addressed fingerprints derived from Git state and declared boundary files. No external dependencies. No build system required.
+## Try it in one minute
 
-## Why
-
-When a component has consumers but no compiler or type system verifying its interface — services exposing OpenAPI specs, Python libraries, config-driven systems, internal platforms — there's no machine that tells you whether a change is internal, boundary-affecting, or breaking.
-
-boundver fills that gap. It lets you **declare** what constitutes your component's boundary, then **automatically classifies every change** into one of four categories:
-
-- **Implementation-only** — internals changed, boundary stable, consumers unaffected.
-- **Behavioral contract change** — defaults/config/migrations changed, API shape stable, consumers may need to re-verify.
-- **Boundary change** — the declared contract changed, consumers should re-verify.
-- **Compatibility break** — the compatibility family changed, deployment coordination required.
-
-This is the information that CI, consumers, and operators each need — derived deterministically from repo state, not from human discipline or commit-message conventions.
-
-### When to use boundver
-
-boundver is for any component whose boundary has consumers but **no static verification** — no compiler checking signatures, no type system enforcing contracts. That includes most services, most Python/Go libraries, most YAML/JSON-defined APIs, and most internal platforms.
-
-| Tool | Sweet spot | Skip if… |
-|---|---|---|
-| **Nx / Turborepo** | JS/TS monorepos with task graphs and caching | You have a polyglot repo or can't adopt a full task runner |
-| **Bazel / Pants** | Large-scale build + dependency graph orchestration | Adoption cost exceeds value for your team size |
-| **TypeScript / Rust compiler** | Statically verified API contracts within a single language | Your entire stack is one statically-typed language |
-| **boundver** | Any language — automated change classification where no static verifier exists | You already have affected-graph + cache-key tooling that satisfies all four questions |
-
-For full tool-selection guidance, see [docs/WHY_BOUNDVER.md](docs/WHY_BOUNDVER.md).
-
-## How it works
-
-Each component gets four fingerprints forming a strict containment hierarchy (`exact ⊇ behavior ⊇ boundary`):
-
-| Fingerprint | Question it answers | What it hashes |
-|---|---|---|
-| `exact` | Did anything change? | All tracked files in the component path |
-| `behavior` | Did the behavioral contract change? | Declared contract files: boundary + config + migrations + contract tests |
-| `boundary` | Did the API surface shape change? | Only the declared boundary files (e.g. `openapi.yaml`, `__init__.py`) |
-| `compat` | Is it still in the same compatibility family? | Derived from SemVer major version |
-
-This gives you four distinct change classifications:
-
-| What changed | Meaning |
-|---|---|
-| Only `exact` | Pure internal refactor — consumers unaffected |
-| `exact` + `behavior` | Behavioral contract changed (defaults, config, migrations) — API shape stable but consumers may be affected |
-| `exact` + `behavior` + `boundary` | API surface changed — consumers must re-verify |
-| All four | Breaking change — compatibility family changed |
-
-Components are grouped into **slices** — named subsets with their own stable fingerprints. Adding an unrelated component changes the full-project hash but leaves existing slice fingerprints untouched.
-
-> **Note:** `boundary` and `behavior` are **declared-file fingerprints**, not semantic analysis. They detect changes in files you declare as contract-relevant. The `openapi-canonical` and `json-canonical` providers go further — they strip non-contract content (descriptions, comments, formatting) so only structural changes trigger the fingerprint.
-
-Each component also reports `boundary_status` in lock output:
-- `ok`: boundary paths were declared and hashed successfully
-- `partial`: boundary provider is `implicit` and no boundary paths are declared (API fingerprint is `null`)
-- `error`: explicit boundary provider has no paths, or declared paths produced no API digest
-
-## What it detects (and what you do about it)
-
-When you run `boundver verify` (e.g. in a PR CI check), it compares the current repo state against `boundary.lock.json`. If fingerprints diverge, it exits non-zero and tells you which tier changed:
-
-| Detection | Meaning | Action |
-|---|---|---|
-| Only `exact` changed | Internal refactor (e.g. handler logic, comments) | Safe to merge — no consumer impact |
-| `behavior` changed | Config/defaults/migrations shifted | Consumers may be affected — review needed but not necessarily breaking |
-| `boundary` changed | API surface moved (e.g. new endpoint in OpenAPI spec, new export in `__init__.py`) | Consumers must re-verify compatibility |
-| `compat` changed | Major version bumped | Deployment coordination required |
-
-### Concrete scenarios
-
-- **Someone edits an API spec without updating the frontend** — PR CI fails `boundver verify`, reviewer sees "auth-service boundary changed" and knows to check frontend compatibility.
-
-- **Shared library adds/removes a public export** — slice fingerprint changes. Any downstream deploy pipeline keyed on that slice hash knows to rebuild.
-
-- **Service schema changes** — boundary fingerprint changes. The consuming team knows to verify their integration still works.
-
-- **Safe internal refactor** — someone rewrites a handler's internals. Only `exact` changes. Slice fingerprints are stable. CI passes. No false alarm.
-
-### The workflow in practice
-
-The lockfile commit becomes an explicit acknowledgment: *"yes, I intentionally changed this boundary."* Reviewers see the diff in `boundary.lock.json` and immediately know the blast radius without reading every file.
-
-**What it does NOT do:** It doesn't block merges automatically or run consumer tests. It's a signal — the enforcement policy (required check, Slack alert, auto-trigger downstream CI) is up to you.
-
-## Quick start
+Run these commands from your repository root:
 
 ```bash
-# Install
-pip install boundver
-
-# Create a starter config
-boundver init
-# Or auto-discover components from common manifests
+python -m pip install boundver
 boundver init --discover
-# Custom path / overwrite existing
-boundver init --out boundary.config.json --force
-
-# Or create manually (see Config Reference below)
-cat > boundary.config.json << 'EOF'
-{
-  "project": "my-project",
-  "components": {
-    "auth-service": {
-      "path": "services/auth",
-      "version_source": { "file": "package.json", "field": "version" },
-      "boundary": {
-        "provider": "openapi",
-        "paths": ["openapi.yaml"]
-      },
-      "behavior": {
-        "paths": ["openapi.yaml", "config/defaults.json"]
-      }
-    }
-  },
-  "slices": {
-    "auth-api": {
-      "description": "Auth service public API",
-      "mode": "boundary",
-      "components": ["auth-service"]
-    }
-  }
-}
-EOF
-
-# Generate the lockfile
-boundver generate
-
-# Regenerate only selected components (and affected slices)
-boundver generate --components auth-service,billing-service
-
-# Preview generation without writing boundary.lock.json
-boundver generate --dry-run
-
-# Check current status
-boundver status
-
-# Verify lockfile matches repo state
-boundver verify
-
-# Verify only selected components
-boundver verify --components auth-service,billing-service
+boundver validate-config
+boundver generate --source working-tree
+boundver verify --source working-tree --facets boundary,compat
+```
 
-# Verify only components changed since main
-boundver verify --changed-from origin/main
+Review and commit `boundary.config.json` and `boundary.lock.json`. In CI, verify the committed snapshot with `source: head`.
 
-# JSON output for automation
-boundver verify --format json
+No useful manifests discovered? `boundver init` creates a minimal scaffold you can edit.
 
-# Logging controls
-boundver --quiet status
-boundver --verbose verify
+## Why teams use it
 
-# Diff two lockfiles
-boundver diff old.lock.json boundary.lock.json
+A service, package, schema, or config-driven component often has consumers that no compiler can verify. A generic “files changed” check is too noisy; a handwritten list of affected systems is easy to forget. boundver records deterministic fingerprints for the parts that matter and reports the direct consumers of a changed contract.
 
-# Inspect a specific slice
-boundver slice auth-api
+- Gate only on the risk you care about: `boundver verify --facets boundary,compat`.
+- Match contract families with globs such as `*.service-definition.json`; newly added matching files cannot stay invisible.
+- Declare `consumers` beside each producer to expose the immediate blast radius.
+- Refresh an intentional change with `boundver verify --update` after review.
+- Use severity-specific exit codes without parsing console text.
+- Keep polyglot monorepos on one small, Git-based contract.
 
-# Preview discovered components
-boundver discover --format json
-```
+## The four facets
 
-## Behavior matrix
-
-| Event | exact | behavior | boundary | compat |
-|---|---|---|---|---|
-| Bug fix (no API change) | ✓ changes | unchanged | unchanged | unchanged |
-| Config/default/migration change | ✓ changes | ✓ changes | unchanged | unchanged |
-| New API endpoint added | ✓ changes | ✓ changes | ✓ changes | unchanged |
-| Breaking change + major bump | ✓ changes | ✓ changes | ✓ changes | ✓ changes |
-| Internal refactor | ✓ changes | unchanged | unchanged | unchanged |
-| New unrelated component added | slice unchanged | slice unchanged | slice unchanged | n/a |
-
-## Config reference
+| Facet | Question | Input |
+|---|---|---|
+| `exact` | Did any tracked component content change? | Every tracked file below the component path |
+| `behavior` | Did declared observable behavior change? | Boundary files plus config, migrations, contract tests, or other declared paths |
+| `boundary` | Did a declared API or contract artifact change? | Provider output for `boundary.paths` |
+| `compat` | Did the compatibility family change? | The configured version and compatibility mode |
 
-### `boundary.config.json`
+The facets let an internal edit remain visible without making it a merge blocker. For example, a team can record exact drift while requiring only boundary and compatibility stability in CI.
 
-Schema file: `boundary.config.schema.json` (Draft 2020-12).
+> boundver detects drift in **declared artifacts**. It is not proof that two implementations are semantically compatible, and it does not replace consumer tests. Canonical providers can remove non-contract noise, but a passing fingerprint check means the declared inputs stayed stable—not that every runtime behavior is equivalent.
 
-> **Config format:** boundver accepts `.json`, `.yaml`/`.yml`, and `.toml` config files.
-> When no explicit `--config` is given, it probes `boundary.config.json`, then
-> `boundary.config.yaml` / `.yml` / `.toml` in order.
+## A practical configuration
 
 ```json
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/boundary.config.schema.json",
-  "project": "my-project",
+  "project": "payments-platform",
   "defaults": {
-    "compat_mode": "major"
+    "compat_mode": "major",
+    "verify_facets": ["boundary", "compat"]
   },
   "components": {
-    "component-name": {
-      "path": "relative/path/from/repo/root",
-      "ecosystem": "python | typescript | cloudformation",
-      "version_source": {
-        "file": "package.json",
-        "field": "version"
-      },
+    "payment-api": {
+      "path": "services/payment",
+      "version_source": {"file": "package.json", "field": "version"},
       "boundary": {
-        "provider": "openapi | python-exports | typescript-exports | leaf | implicit",
-        "paths": ["openapi.yaml"],
-        "note": "optional explanation"
+        "provider": "openapi",
+        "paths": ["openapi/*.yaml", "*.service-definition.json"]
       },
       "behavior": {
-        "paths": ["openapi.yaml", "config/defaults.json"]
+        "paths": ["openapi/*.yaml", "*.service-definition.json", "config/*.json"]
       },
-      "vendored_copies": ["path/to/vendored/copy/"]
+      "consumers": ["admin-portal", "checkout-web"]
     }
   },
   "slices": {
-    "slice-name": {
-      "description": "Human-readable purpose",
-      "mode": "exact | behavior | boundary | compat",
-      "components": ["component-a", "component-b"]
+    "checkout-contracts": {
+      "description": "Contracts required by checkout",
+      "mode": "boundary",
+      "components": ["payment-api"]
     }
   }
 }
 ```
 
-### Version source options
-
-```json
-// From a JSON/TOML/YAML file field:
-"version_source": { "file": "pyproject.toml", "field": "project.version" }
-
-// From git tags:
-"version_source": { "git_tag_prefix": "auth-service-v" }
-
-// No version tracking:
-"version_source": null
-```
-
-### Boundary providers
-
-| Provider | Meaning |
-|---|---|
-| `openapi` | OpenAPI/Swagger spec defines the API surface |
-| `python-exports` | `__init__.py` or `__all__` exports define the boundary |
-| `typescript-exports` | `.d.ts` or `index.ts` exports define the boundary |
-| `json-file` | Generic JSON boundary artifact defines the contract |
-| `custom.example.service-definition.v1` | Example custom provider namespace |
-| `leaf` | No downstream consumers — boundary is the component itself |
-| `implicit` | No explicit boundary artifact yet (`boundary` fingerprint will be `null`) |
-
-### Provider capability matrix
-
-| Provider | Semantic parser? | Requires `paths` | Empty `paths` allowed | Output |
-|---|---:|---:|---:|---|
-| `openapi` | No (raw file digest) | Yes | No | Raw boundary digest |
-| `python-exports` | No (raw file digest) | Yes | No | Raw boundary digest |
-| `typescript-exports` | No (raw file digest) | Yes | No | Raw boundary digest |
-| `json-file` | No (raw file digest) | Yes | No | Raw boundary digest |
-| `leaf` | n/a | No | Yes | No boundary digest required |
-| `implicit` | n/a | No | Yes | `boundary_status=partial` |
-| `custom.*` | Depends on implementation | Usually | Depends | Raw digest by default |
-
-> Built-in providers are currently raw-boundary artifact hashers, not semantic API diff engines.
-
+Paths are relative to the component. `*`, `?`, character classes, and recursive `**` patterns are supported by path-hashing providers. A glob that matches nothing is an error, making accidental omissions visible. Canonical JSON/OpenAPI providers currently require explicit files.
 
-## Near-term implementation focus
+`behavior.paths` normally includes every boundary path plus runtime-relevant configuration. `consumers` names direct downstream systems; boundary and compatibility failures report them so reviewers know whom to re-verify.
 
-boundver remains a public, language-agnostic tool. Near-term work is focused on:
+## Choose the CI policy
 
-- strict config validation and no silent fingerprint fallback
-- explicit source mode behavior (`head`, `index`, `working-tree`)
-- portability for external users (no implicit dependency on internal/proprietary boundary artifacts)
+The command line overrides `defaults.verify_facets`:
 
-Short term deliverables: `validate-config`, strict digest selection, explicit source modes, and public examples that avoid proprietary dependencies.
-
-## CI integration
+```bash
+# Recommended starting gate: internal refactors do not fail CI
+boundver verify --facets boundary,compat
 
-For lockfile merge conflict handling, see [docs/LOCKFILE_MERGE.md](docs/LOCKFILE_MERGE.md).
+# Stricter contract gate
+boundver verify --facets behavior,boundary,compat
 
-### GitHub Actions — PR verification
+# Audit every recorded facet
+boundver verify --facets exact,behavior,boundary,compat
+```
 
-For a full set of patterns (conditional builds, cache keys, GitLab, pre-commit), see [docs/ci-cookbook.md](docs/ci-cookbook.md).
+Drift outside the selected gate is reported as a non-gating observation. Config, lockfile structure, digest errors, and metadata integrity remain safety checks.
 
-#### Option A: use bundled composite action
+## GitHub Actions
 
 ```yaml
-name: Boundary check
+name: Contract boundary
 on: [pull_request]
+
 jobs:
   verify:
     runs-on: ubuntu-latest
@@ -296,163 +115,99 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: ./.github/actions/boundver
+      - uses: yzm1/boundver@v0
         with:
           config: boundary.config.json
           lock: boundary.lock.json
           source: head
-          show-diff-on-failure: "true"
+          facets: boundary,compat
 ```
 
-#### Option B: explicit steps
-
-```yaml
-name: Boundary check
-on: [pull_request]
-jobs:
-  verify:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-      - run: boundver verify
-      - name: Show diff on failure
-        if: failure()
-        run: |
-          boundver generate --out boundary.lock.new.json
-          boundver diff boundary.lock.json boundary.lock.new.json
-```
+The Action installs the version bundled with its release and exposes issues, observations, and the exit code. See the [CI cookbook](https://github.com/yzm1/boundver/blob/main/docs/ci-cookbook.md) for changed-component checks, GitLab, pre-commit, and cache recipes.
 
-### Conditional builds using slice fingerprints
+## Review and accept intentional drift
 
 ```bash
-# Only rebuild if the API slice actually changed
-NEW_FP=$(python -c "
-import json
-lock = json.load(open('boundary.lock.json'))
-print(lock['slices']['my-api']['fingerprint'][:12])
-")
-
-if [ "$NEW_FP" != "$CACHED_FP" ]; then
-  echo "API changed — rebuilding consumers"
-  # ... trigger downstream builds
-fi
-```
-
-### Shell verifier (portability proof)
+# See the affected facet and direct consumers
+boundver verify --source working-tree --facets boundary,compat
+boundver why payment-api --source working-tree
 
-```bash
-# Verifies exact/boundary fingerprints against HEAD using git + jq + sha256sum
-scripts/boundver-verify.sh boundary.config.json boundary.lock.json
+# After review, regenerate in the same source mode
+boundver verify --source working-tree --facets boundary,compat --update
+git diff -- boundary.lock.json
 ```
 
-## Environment variables
-
-| Variable | Effect |
-|----------|--------|
-| `BOUNDVER_ALLOW_CUSTOM_PROVIDERS=1` | Equivalent to passing `--allow-custom-providers` on every invocation. Accepts `1`, `true`, or `yes`. |
-
-## Exit codes
+Use the same source mode for generation and verification. If you want to refresh non-gating exact or behavior drift too, include those facets in the update command.
 
-`boundver verify` uses structured exit codes for reliable CI scripting:
-
-| Code | Meaning |
-|------|---------|
-| `0` | Lockfile matches current repo state |
-| `1` | Lockfile is out of date (fingerprint mismatches found) |
-| `2` | Usage error (unknown component, config missing, etc.) |
+## Source modes
 
-`validate-config` exits `0` on success, `1` on validation errors.
-`generate` exits `0` on success, `1` on config/generation error.
+| Mode | Snapshot | Typical use |
+|---|---|---|
+| `head` | Files committed at `HEAD` | CI and clean local checkouts |
+| `index` | Files staged in Git | Pre-commit workflows |
+| `working-tree` | On-disk content of tracked files | Reviewing local edits |
 
-## Design decisions
+Untracked files are intentionally excluded after the repository has its first commit. In an unborn repository, `working-tree` uses a bounded filesystem fallback so initial setup can succeed; review and stage those files before committing the lock. Stage a new contract file before using `index`, or `git add` it before relying on tracked working-tree discovery.
 
-- **No external dependencies.** Only Git and Python stdlib. Runs anywhere Python 3.8+ and Git are available.
-- **Deterministic output.** Canonical JSON (sorted keys, compact separators) ensures two machines produce identical hashes from identical repo state.
-- **Canonical exact hashing across source modes.** `exact` uses one canonical SHA-256 file-content digest model for `head`, `index`, and `working-tree`, enabling direct cross-source comparison.
-- **Config/lockfile split.** Config is human-maintained (what exists). Lockfile is machine-generated (current state). Mirrors `package.json` / `package-lock.json`.
-- **Language-agnostic boundaries.** Instead of parsing ASTs, you declare which files constitute the public boundary. Works with any language or artifact format.
+## Providers
 
-## Examples
+| Provider | Use it for |
+|---|---|
+| `openapi` | Raw OpenAPI or Swagger artifacts |
+| `openapi-canonical` | OpenAPI structure with documentation noise removed |
+| `json-file` | Raw JSON contracts |
+| `json-canonical` | Formatting-insensitive JSON contracts |
+| `python-exports` | Python export files such as `__init__.py` |
+| `typescript-exports` | TypeScript declarations or export barrels |
+| `leaf` | A component with no downstream contract |
+| `implicit` | Exact tracking before a boundary is declared |
 
-- `examples/openapi/`
-- `examples/json-file/`
-- `examples/implicit-and-leaf/`
-- `examples/python-package/`
-- `examples/typescript-package/`
+Custom providers are supported only with an explicit trusted-code opt-in. See [public and custom providers](https://github.com/yzm1/boundver/blob/main/docs/public-vs-custom-providers.md).
 
-## Documentation
+## Exit codes
 
-- [Getting started](docs/getting-started.md) — install, first config, first lockfile, CI setup
-- [Gradual adoption guide](docs/gradual-adoption.md) — incremental adoption from one component to full coverage
-- [CI cookbook](docs/ci-cookbook.md) — GitHub Actions, cache keys, GitLab, pre-commit
-- [Why boundver?](docs/WHY_BOUNDVER.md) — tool comparison and positioning
-- [Custom vs public providers](docs/public-vs-custom-providers.md) — when to use `custom.*`
-- [Lockfile merge handling](docs/LOCKFILE_MERGE.md) — resolving merge conflicts
+| Code | Highest selected failure |
+|---:|---|
+| `0` | Clean; selected facets match |
+| `1` | Exact or metadata drift |
+| `2` | Usage or configuration error |
+| `3` | Behavior drift |
+| `4` | Boundary drift |
+| `5` | Compatibility drift |
 
-## Validation dependencies
+When several selected facets drift, the highest-severity code wins.
 
-- **Runtime dependencies:** none (stdlib + git only).
-- **Optional enhanced schema validation:** install `jsonschema` for stricter JSON Schema engine checks in `validate-config`.
-- **Optional enhanced YAML extraction:** install `PyYAML` for robust YAML parsing in version extraction.
+## Useful commands
 
 ```bash
-pip install "boundver[schema]"
-pip install "boundver[yaml]"
+boundver discover                    # preview Git-tracked manifest discovery
+boundver status                      # summarize a lockfile
+boundver verify --changed-from main  # show changed components; verify the full lock
+boundver verify --update             # accept reviewed drift in one step
+boundver diff old.lock.json boundary.lock.json
+boundver slice checkout-contracts
+boundver completions --shell bash
 ```
 
-Without `jsonschema`, boundver still runs and applies built-in semantic validation checks.
-
-## Release
+## Installation and requirements
 
-- PyPI publish workflow: `.github/workflows/publish.yml`
-- Trigger: push a version tag matching `v*` (for example `v0.3.0`)
+boundver supports Python 3.9+ and Git. It has no third-party dependency on Python 3.11+; Python 3.9–3.10 install `tomli` for TOML support.
 
-## Source modes
-
-| Mode | File list | Content read from | Default for |
-|------|-----------|-------------------|-------------|
-| `head` | `git ls-tree HEAD` | committed git blobs | `generate`, `verify`, `status`, `why` |
-| `index` | `git ls-files --cached` | staged blobs | — |
-| `working-tree` | `git ls-files` (tracked) | disk bytes (CRLF→LF) | `explain` |
-
-### Important: `working-tree` only sees tracked files
-
-`--source=working-tree` hashes the **on-disk content** of files that are already tracked by git.
-It does **not** include untracked files.  If you just created a new file but haven't run
-`git add`, that file will not appear in any fingerprint until it is tracked.
-
-This matters most during:
-
-- **Initial setup** — run `git add .` before `boundver generate --source working-tree`.
-- **Adding new boundary files** — a new `openapi.yaml` won't affect digests until tracked.
-- **CI with uncommitted generated files** — prefer `--source head` (the default) in CI.
-
-### Ignore behavior
-
-`--source=working-tree` prefers Git-backed tracked-file enumeration (`git ls-files`) when available.
-In non-git fallback contexts, local file traversal is used.
-Symlinks are hashed as link-target text (not dereferenced bytes) for cross-source consistency.
-
-## Requirements
-
-- Python 3.8+
-- Git
-- No pip packages needed
-
-## Hash guardrails
-
-To avoid pathological repository scans, hashing enforces built-in guardrails:
+```bash
+python -m pip install boundver
+python -m pip install "boundver[schema,yaml]"  # optional validation/YAML support
+```
 
-- maximum files hashed per digest: `50,000`
-- maximum size per hashed file: `50 MiB`
+## Learn more
 
-If exceeded, boundver records explicit digest errors on affected components.
+- [Getting started](https://github.com/yzm1/boundver/blob/main/docs/getting-started.md)
+- [Examples](https://github.com/yzm1/boundver/blob/main/examples/README.md)
+- [CI cookbook](https://github.com/yzm1/boundver/blob/main/docs/ci-cookbook.md)
+- [Gradual adoption](https://github.com/yzm1/boundver/blob/main/docs/gradual-adoption.md)
+- [Why boundver?](https://github.com/yzm1/boundver/blob/main/docs/WHY_BOUNDVER.md)
+- [Lockfile merge strategy](https://github.com/yzm1/boundver/blob/main/docs/LOCKFILE_MERGE.md)
+- [Changelog](https://github.com/yzm1/boundver/blob/main/CHANGELOG.md)
 
-## License
+For questions and ideas, see [support](https://github.com/yzm1/boundver/blob/main/SUPPORT.md); bugs belong in [GitHub Issues](https://github.com/yzm1/boundver/issues). Contributions are welcome—start with the [contributing guide](https://github.com/yzm1/boundver/blob/main/CONTRIBUTING.md) and [security policy](https://github.com/yzm1/boundver/blob/main/SECURITY.md).
 
-MIT
+MIT licensed.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..b48f6bc
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,35 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest release and the 0.10 release line.
+
+| Version | Supported |
+| --- | --- |
+| Latest release | Yes |
+| 0.10.x | Yes |
+| Earlier versions | No |
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities through GitHub's
+[private vulnerability reporting](https://github.com/yzm1/boundver/security/advisories/new).
+Do not disclose security-sensitive details in a public issue, discussion, or
+pull request.
+
+Include, when possible:
+
+- the affected boundver version and environment;
+- a minimal reproduction or proof of concept;
+- the impact and any known prerequisites;
+- suggested mitigations, if you have them.
+
+The maintainer will acknowledge the report as soon as practical, investigate it,
+and coordinate disclosure and a fix with the reporter. Please allow a reasonable
+amount of time for remediation before publishing details.
+
+## Scope
+
+Reports about boundver's source, packaged CLI, GitHub Action, and release
+artifacts are in scope. Vulnerabilities in third-party services should be
+reported to the service owner unless boundver's integration is the cause.
diff --git a/SUPPORT.md b/SUPPORT.md
new file mode 100644
index 0000000..57e701a
--- /dev/null
+++ b/SUPPORT.md
@@ -0,0 +1,22 @@
+# Support
+
+boundver is maintained as an open source project on a best-effort basis.
+
+Before requesting help:
+
+1. Check the [README](README.md) and the guides in [`docs/`](docs/).
+2. Search [existing issues](https://github.com/yzm1/boundver/issues) for the same
+   error or use case.
+3. Retry with the latest supported release when practical.
+
+For reproducible bugs, open a
+[bug report](https://github.com/yzm1/boundver/issues/new/choose) and include a
+minimal repository layout, sanitized config, command, output, boundver version,
+Python version, operating system, and Git version. For product ideas, use the
+feature request template. A blank issue is available for focused usage
+questions that do not fit either template.
+
+Please do not use public issues for vulnerabilities. Follow
+[`SECURITY.md`](SECURITY.md) to report them privately. Questions about third-party
+services or unsupported versions may need to be handled by those providers or by
+the wider community.
diff --git a/action.yml b/action.yml
index a6f72af..a6242b9 100644
--- a/action.yml
+++ b/action.yml
@@ -1,76 +1,153 @@
 name: boundver
-description: >
-  Detect whether component changes are internal, behavioral, boundary-affecting,
-  or compatibility-breaking.
+description: Detect API boundary, behavioral contract, and component changes in CI.
 author: yzm1
 
 branding:
-  icon: lock
+  icon: shield
   color: blue
 
 inputs:
-  command:
-    description: >
-      boundver command to run. One of: verify, generate, validate-config,
-      status, diff, discover. Default is 'verify'.
+  config:
+    description: Path to boundary.config.json.
     required: false
-    default: verify
-
-  args:
-    description: >
-      Additional arguments passed directly to the boundver command.
-      Example: "--source head --components svc,worker"
+    default: boundary.config.json
+  lock:
+    description: Path to boundary.lock.json.
+    required: false
+    default: boundary.lock.json
+  source:
+    description: Snapshot to verify (head, index, or working-tree).
+    required: false
+    default: head
+  facets:
+    description: Comma-separated facets that fail the gate.
+    required: false
+    default: boundary,compat
+  components:
+    description: Optional comma-separated component subset.
     required: false
     default: ""
-
-  version:
-    description: >
-      pip install specifier for boundver. Defaults to installing from the
-      main branch on GitHub. Once published on PyPI, set to e.g. "boundver==0.9.0".
+  changed-from:
+    description: Optional Git ref used to report changed components while verifying the full lock.
+    required: false
+    default: ""
+  fail-fast:
+    description: Report only the highest-severity gated issue.
+    required: false
+    default: "false"
+  update:
+    description: Refresh the lockfile after reporting drift.
+    required: false
+    default: "false"
+  python-version:
+    description: Python version used by the action.
     required: false
-    default: "boundver>=0.9.0"
+    default: "3.12"
 
 outputs:
   exit-code:
-    description: Exit code from the boundver command (0=ok, 1=drift, 2=usage error).
-    value: ${{ steps.run.outputs.exit-code }}
-
+    description: "0 clean, 1 exact/metadata, 2 usage, 3 behavior, 4 boundary, 5 compatibility."
+    value: ${{ steps.verify.outputs.exit-code }}
   issues:
-    description: >
-      Newline-separated list of issues found (verify command only).
-      Empty when the lockfile is up to date.
-    value: ${{ steps.run.outputs.issues }}
+    description: Newline-separated gated issues.
+    value: ${{ steps.verify.outputs.issues }}
+  observations:
+    description: Newline-separated drift outside the selected gate.
+    value: ${{ steps.verify.outputs.observations }}
 
 runs:
   using: composite
   steps:
-    - name: Install boundver
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install this boundver release
       shell: bash
-      run: pip install --quiet ${{ inputs.version }}
+      env:
+        BOUNDVER_ACTION_PATH: ${{ github.action_path }}
+      run: python -m pip install --disable-pip-version-check --quiet "$BOUNDVER_ACTION_PATH"
 
-    - name: Run boundver
-      id: run
+    - name: Verify declared facets
+      id: verify
       shell: bash
+      env:
+        BOUNDVER_CONFIG: ${{ inputs.config }}
+        BOUNDVER_LOCK: ${{ inputs.lock }}
+        BOUNDVER_SOURCE: ${{ inputs.source }}
+        BOUNDVER_FACETS: ${{ inputs.facets }}
+        BOUNDVER_COMPONENTS: ${{ inputs.components }}
+        BOUNDVER_CHANGED_FROM: ${{ inputs.changed-from }}
+        BOUNDVER_FAIL_FAST: ${{ inputs.fail-fast }}
+        BOUNDVER_UPDATE: ${{ inputs.update }}
       run: |
+        set -euo pipefail
+
+        case "$BOUNDVER_SOURCE" in
+          head|index|working-tree) ;;
+          *) echo "Invalid source: $BOUNDVER_SOURCE" >&2; exit 2 ;;
+        esac
+        case "$BOUNDVER_FAIL_FAST" in
+          true|false) ;;
+          *) echo "fail-fast must be true or false" >&2; exit 2 ;;
+        esac
+        case "$BOUNDVER_UPDATE" in
+          true|false) ;;
+          *) echo "update must be true or false" >&2; exit 2 ;;
+        esac
+
+        command=(
+          boundver verify
+          --config "$BOUNDVER_CONFIG"
+          --lock "$BOUNDVER_LOCK"
+          --source "$BOUNDVER_SOURCE"
+          --facets "$BOUNDVER_FACETS"
+          --format json
+        )
+        if [[ -n "$BOUNDVER_COMPONENTS" ]]; then
+          command+=(--components "$BOUNDVER_COMPONENTS")
+        fi
+        if [[ -n "$BOUNDVER_CHANGED_FROM" ]]; then
+          command+=(--changed-from "$BOUNDVER_CHANGED_FROM")
+        fi
+        if [[ "$BOUNDVER_FAIL_FAST" == true ]]; then
+          command+=(--fail-fast)
+        fi
+        if [[ "$BOUNDVER_UPDATE" == true ]]; then
+          command+=(--update)
+        fi
+
+        result_file="${RUNNER_TEMP:-/tmp}/boundver-result.json"
         set +e
-        output=$(boundver ${{ inputs.command }} ${{ inputs.args }} --format json 2>&1)
+        "${command[@]}" >"$result_file"
         code=$?
+        set -e
         echo "exit-code=$code" >> "$GITHUB_OUTPUT"
-        # Extract issues array from JSON output when available
-        issues=$(echo "$output" | python3 -c "
-        import json, sys
+
+        for field in issues observations; do
+          delimiter="BOUNDVER_${field}_${RANDOM}_${RANDOM}"
+          {
+            echo "$field<<$delimiter"
+            python - "$result_file" "$field" <<'PY'
+        import json
+        import pathlib
+        import sys
+
+        path = pathlib.Path(sys.argv[1])
+        field = sys.argv[2]
         try:
-            data = json.load(sys.stdin)
-            for issue in data.get('issues', []):
-                print(issue)
-        except Exception:
-            pass
-        " 2>/dev/null || true)
-        {
-          echo "issues<<EOF"
-          echo "$issues"
-          echo "EOF"
-        } >> "$GITHUB_OUTPUT"
-        # Re-run in text mode for human-readable CI log output
-        boundver ${{ inputs.command }} ${{ inputs.args }} || true
-        exit $code
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            payload = {}
+        for item in payload.get(field, []):
+            print(item)
+        PY
+            echo "$delimiter"
+          } >> "$GITHUB_OUTPUT"
+        done
+
+        if [[ -s "$result_file" ]]; then
+          python -m json.tool "$result_file"
+        fi
+        exit "$code"
diff --git a/boundary.config.json b/boundary.config.json
index 85e5b61..60469fd 100644
--- a/boundary.config.json
+++ b/boundary.config.json
@@ -2,14 +2,16 @@
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/boundary.config.schema.json",
   "project": "boundver",
   "defaults": {
-    "compat_mode": "major"
+    "compat_mode": "major",
+    "verify_facets": [
+      "boundary",
+      "compat"
+    ]
   },
   "components": {
     "boundver": {
       "path": "src/boundver",
-      "version_source": {
-        "git_tag_prefix": "v"
-      },
+      "version_source": null,
       "boundary": {
         "provider": "python-exports",
         "paths": [
@@ -20,6 +22,9 @@
     },
     "spec": {
       "path": "spec",
+      "consumers": [
+        "boundver"
+      ],
       "boundary": {
         "provider": "json-file",
         "paths": [
diff --git a/boundary.config.schema.json b/boundary.config.schema.json
index d8f52f8..a9b50b2 100644
--- a/boundary.config.schema.json
+++ b/boundary.config.schema.json
@@ -5,84 +5,120 @@
   "type": "object",
   "required": ["project", "components"],
   "properties": {
-    "project": { "type": "string", "minLength": 1 },
+    "$schema": {"type": "string"},
+    "project": {"type": "string", "minLength": 1},
     "providers": {
       "type": "array",
-      "description": "Custom provider registrations. Requires allow_custom_providers: true or --allow-custom-providers at runtime.",
+      "description": "Custom providers. Loading requires an explicit --allow-custom-providers flag or trusted environment opt-in.",
       "items": {
         "type": "object",
         "required": ["module", "class"],
         "properties": {
-          "module": { "type": "string", "minLength": 1 },
-          "class": { "type": "string", "minLength": 1 }
+          "module": {"type": "string", "minLength": 1},
+          "class": {"type": "string", "minLength": 1},
+          "name": {"type": "string", "pattern": "^custom\\."}
         },
         "additionalProperties": false
       }
     },
-    "allow_custom_providers": {
-      "type": "boolean",
-      "description": "When true, custom providers declared in 'providers' are loaded without requiring the --allow-custom-providers CLI flag.",
-      "default": false
-    },
     "defaults": {
       "type": "object",
       "properties": {
         "compat_mode": {
           "type": "string",
           "enum": ["major", "semver_major", "semver_major_minor"]
+        },
+        "verify_facets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["exact", "behavior", "boundary", "compat"]
+          }
         }
       },
-      "additionalProperties": true
+      "additionalProperties": false
     },
     "components": {
       "type": "object",
+      "minProperties": 1,
       "additionalProperties": {
         "type": "object",
         "required": ["path", "boundary"],
         "properties": {
-          "path": { "type": "string", "minLength": 1 },
-          "ecosystem": { "type": "string" },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!\\.?/?$)(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+          },
+          "ecosystem": {"type": "string"},
           "version_source": {
             "oneOf": [
               {"type": "null"},
-              {"type": "object"}
+              {
+                "type": "object",
+                "required": ["file", "field"],
+                "properties": {
+                  "file": {"type": "string", "minLength": 1},
+                  "field": {"type": "string", "minLength": 1}
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": ["git_tag_prefix"],
+                "properties": {
+                  "git_tag_prefix": {"type": "string", "minLength": 1}
+                },
+                "additionalProperties": false
+              }
             ]
           },
           "boundary": {
             "type": "object",
             "required": ["provider"],
             "properties": {
-              "provider": { "type": "string", "minLength": 1 },
+              "provider": {"type": "string", "minLength": 1},
               "paths": {
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\\\).+$"}
               },
               "options": {
                 "type": "object",
-                "description": "Provider-specific options passed to the provider via ProviderContext.",
+                "description": "Provider-specific options passed through ProviderContext.",
                 "additionalProperties": true
               },
-              "note": { "type": "string" }
+              "note": {"type": "string"}
             },
-            "additionalProperties": true
+            "additionalProperties": false
           },
           "behavior": {
             "type": "object",
-            "description": "Behavioral contract paths — a superset of boundary that includes config, migrations, contract tests, etc.",
+            "description": "Behavior-relevant paths, normally a superset of boundary paths.",
             "properties": {
               "paths": {
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\\\).+$"}
               }
             },
             "additionalProperties": false
           },
           "vendored_copies": {
             "type": "array",
-            "items": { "type": "string" }
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+            }
+          },
+          "consumers": {
+            "type": "array",
+            "items": {"type": "string"},
+            "uniqueItems": true
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     },
     "slices": {
@@ -91,16 +127,16 @@
         "type": "object",
         "required": ["components"],
         "properties": {
-          "description": { "type": "string" },
-          "mode": { "type": "string", "enum": ["exact", "behavior", "boundary", "compat"] },
+          "description": {"type": "string"},
+          "mode": {"type": "string", "enum": ["exact", "behavior", "boundary", "compat"]},
           "components": {
             "type": "array",
-            "items": { "type": "string" }
+            "items": {"type": "string"}
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     }
   },
-  "additionalProperties": true
+  "additionalProperties": false
 }
diff --git a/boundary.lock.json b/boundary.lock.json
index 78f65c2..8c079aa 100644
--- a/boundary.lock.json
+++ b/boundary.lock.json
@@ -1,17 +1,19 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "boundver",
   "components": {
     "boundver": {
       "version": null,
       "path": "src/boundver",
       "boundary_provider": "python-exports",
+      "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "28ec2585699ec4823aff8568615dcdeaaab634a675c3cf318c7327a01ef4a9ef",
+        "exact": "fa117a8c7cdb96eb0147fcaef4bec9cfed038c5b63ba676ec05dd6ae2f4f28c0",
         "behavior": null,
-        "boundary": "9ffd37eb7eafd3db1a30c562d3e63bc4efec8f478bb17a0f2a8f3e1c51db2862",
+        "boundary": "3cec60f18f8753487958a060f9b166a20ebd5b4a79e5cb8228bd232e76177343",
         "compat": null
       },
       "semver": {
@@ -24,11 +26,15 @@
       "version": null,
       "path": "spec",
       "boundary_provider": "json-file",
+      "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [
+        "boundver"
+      ],
       "fingerprints": {
-        "exact": "b573703461d2fad8de397bd085302935974ff3c3ef9087d31353e410f59537c8",
+        "exact": "1d5782f2f165d797d1c380ae0eb25f926182b01433f9877845d05c6739a64948",
         "behavior": null,
-        "boundary": "23b615d0a98a22b3a6c2d4f625b004dd02ae80ff81b35fd675250e3c3e4996ae",
+        "boundary": "cc3665b68205d96779234f047fa195a5988a26e7ae1bcf645c2a3d80509a13c0",
         "compat": null
       },
       "semver": {
@@ -45,9 +51,9 @@
       "components": [
         "boundver"
       ],
-      "fingerprint": "85929c659c9ce419aaef218933d8c5eed42f382404dd1327bf4f95f4e57ce783",
+      "fingerprint": "65f50aad6677a19bc1b0550ac38eba682910be3d1da06936cbf1321c4268ee3b",
       "component_digests": {
-        "boundver": "9ffd37eb7eafd3db1a30c562d3e63bc4efec8f478bb17a0f2a8f3e1c51db2862"
+        "boundver": "3cec60f18f8753487958a060f9b166a20ebd5b4a79e5cb8228bd232e76177343"
       }
     },
     "spec": {
@@ -56,9 +62,9 @@
       "components": [
         "spec"
       ],
-      "fingerprint": "7297a30943da98ffa81c71454ee2098cd491c90d0032bd1d889212f2b77b948d",
+      "fingerprint": "dbfdc0d193b641a99471b577e357a57d47332f2efccfd20826a9d46af8d7ed72",
       "component_digests": {
-        "spec": "b573703461d2fad8de397bd085302935974ff3c3ef9087d31353e410f59537c8"
+        "spec": "1d5782f2f165d797d1c380ae0eb25f926182b01433f9877845d05c6739a64948"
       }
     },
     "all": {
@@ -68,10 +74,10 @@
         "boundver",
         "spec"
       ],
-      "fingerprint": "3bc32c4007f42c248a18bda13fc84e7ffd2a69872555a261cbf6f1c765826b74",
+      "fingerprint": "8634efcdfc2fe16f63d764808a84c30352c622210aad0e8adea5dbc945fd1561",
       "component_digests": {
-        "boundver": "28ec2585699ec4823aff8568615dcdeaaab634a675c3cf318c7327a01ef4a9ef",
-        "spec": "b573703461d2fad8de397bd085302935974ff3c3ef9087d31353e410f59537c8"
+        "boundver": "fa117a8c7cdb96eb0147fcaef4bec9cfed038c5b63ba676ec05dd6ae2f4f28c0",
+        "spec": "1d5782f2f165d797d1c380ae0eb25f926182b01433f9877845d05c6739a64948"
       }
     }
   }
diff --git a/docs/CI_REENABLE_PLAN.md b/docs/CI_REENABLE_PLAN.md
deleted file mode 100644
index 22f2ddc..0000000
--- a/docs/CI_REENABLE_PLAN.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# CI Re-enable Plan (v1.0.0 Gate)
-
-## Current State (as of 2026-05-02)
-- `.github/workflows/ci.yml` stays manual-only (`workflow_dispatch`).
-- Automated PR/push CI is intentionally disabled to prevent runaway GitHub Actions costs during rapid development.
-
-## Re-enable Preconditions
-1. **Release gate reached**: version branch/tag for `v1.0.0` is being cut.
-2. **Budget controls set**:
-   - Monthly Actions spend alert configured.
-   - Workflow concurrency enabled to cancel superseded runs.
-   - Path filters and trigger scope reviewed to avoid unnecessary runs.
-3. **Owner assigned**: one maintainer accountable for CI cost/health rollback decisions.
-
-## Re-enable Steps
-1. Restore PR/push triggers for `main`.
-2. Enable required checks:
-   - `pytest -q`
-   - packaging smoke build/install (`wheel` + `sdist` + `boundver --help`)
-3. Keep optional checks (lint/type) non-blocking for initial rollout week.
-4. Add weekly spend review for first 4 weeks post-enable.
-
-## Rollback Policy
-- If spend exceeds expected weekly envelope or queue contention impacts productivity,
-  revert to manual-only dispatch and open a follow-up issue with run breakdown.
-
-## Success Criteria
-- CI is auto-triggered on PR/push with stable pass/fail signal.
-- Spend remains within budget envelope for 4 consecutive weeks.
-- Required checks block regressions without repeated emergency disablement.
diff --git a/docs/LOCKFILE_MERGE.md b/docs/LOCKFILE_MERGE.md
index 0ae8841..bca73c9 100644
--- a/docs/LOCKFILE_MERGE.md
+++ b/docs/LOCKFILE_MERGE.md
@@ -1,37 +1,98 @@
-# Lockfile Merge Strategy
+# Lockfile merge strategy
 
-`boundary.lock.json` is a generated artifact. When parallel branches both regenerate it, Git conflicts are expected.
+`boundary.lock.json` is generated from the repository's source and configuration. When branches change components concurrently, regenerate the complete lockfile from the real merged tree instead of combining fingerprint JSON by hand.
 
-## Future-proof rule
-Do **not** hand-edit lockfile conflict hunks.
-Always regenerate from `boundary.config.json`.
+## Why not use a merge driver?
+
+A Git merge driver runs while Git is still constructing the merge. It receives individual conflict stages, not a guaranteed materialization of the final source tree, and it may run on a machine without the expected boundver version. Regenerating there can bless fingerprints from the wrong snapshot.
+
+Keep the lockfile as ordinary text in `.gitattributes`. Perform regeneration only after the source and `boundary.config.json` represent the intended merged result.
+
+## Resolve a lockfile conflict
+
+From the repository root:
+
+```bash
+# 1. Resolve source and configuration conflicts first.
+git status --short
+
+# 2. Regenerate the whole lock from the materialized merged tree.
+boundver validate-config
+boundver generate --source working-tree
+
+# 3. Check the exact same snapshot and inspect the generated diff.
+boundver verify \
+  --source working-tree \
+  --facets exact,behavior,boundary,compat
+git diff -- boundary.lock.json
+
+# 4. Mark the generated file resolved, then finish the merge.
+git add boundary.config.json boundary.lock.json
+git status --short
+git commit
+```
+
+Only add `boundary.config.json` in step 4 if the merge actually changed it. Add every resolved source file separately as usual.
+
+After the merge commit exists, verify the committed snapshot:
 
-## Manual resolution
 ```bash
-# After merge conflict appears
-boundver generate
+boundver verify --source head --facets exact,behavior,boundary,compat
+```
+
+The source pairing matters: use `working-tree` before the merge commit, then `head` after it. `head` during conflict resolution still names the pre-merge commit and cannot represent both branches.
 
-git add boundary.lock.json
+## Clean merge but stale lockfile
+
+Git may merge the JSON without a textual conflict even though the combined source requires a different aggregate or slice fingerprint. Run the same regeneration after every merge that touches components, configuration, or the lockfile:
+
+```bash
+boundver generate --source working-tree
+boundver verify \
+  --source working-tree \
+  --facets exact,behavior,boundary,compat
+git diff --exit-code -- boundary.lock.json || {
+  echo "Review and commit the regenerated boundary.lock.json"
+}
 ```
 
-## Optional Git merge driver (recommended)
+## Optional post-merge hook
 
-1. Add to `.gitattributes`:
+A local post-merge hook runs after Git has materialized the merged tree. It can regenerate and leave any required lockfile update visible for review:
 
-```gitattributes
-boundary.lock.json merge=boundver-lock
+```sh
+#!/bin/sh
+# .git/hooks/post-merge
+set -eu
+
+if command -v boundver >/dev/null 2>&1 && test -f boundary.config.json; then
+  boundver generate --source working-tree
+  boundver verify \
+    --source working-tree \
+    --facets exact,behavior,boundary,compat
+
+  if ! git diff --quiet -- boundary.lock.json; then
+    echo "boundver regenerated boundary.lock.json; review and commit it."
+  fi
+fi
 ```
 
-2. Register merge driver locally:
+Make the hook executable:
 
 ```bash
-git config merge.boundver-lock.name "boundver lockfile regenerate"
-git config merge.boundver-lock.driver "scripts/boundver-merge-driver.sh %A"
+chmod +x .git/hooks/post-merge
 ```
 
-3. Ensure `boundver` is available in your environment.
+Hooks are local and are not cloned with the repository. Treat this as a convenience, not enforcement. The authoritative safeguard is a CI job that runs:
+
+```bash
+boundver verify --source head --facets boundary,compat
+```
 
-Now when `boundary.lock.json` conflicts, Git invokes the driver, which regenerates deterministic lock output and writes `%A`.
+## Rules of thumb
 
-## CI note
-If your CI runs `boundver verify`, merge-driver output is naturally validated during PR checks.
+- Resolve configuration and source before regenerating the lockfile.
+- Regenerate the full lockfile; a partial refresh is inappropriate for a merge.
+- Never hand-edit fingerprint values.
+- Review direct consumer changes and slice changes in the generated diff.
+- Keep CI on `head` so it verifies exactly what the pull request commits.
diff --git a/docs/PROJECT_REVIEW.md b/docs/PROJECT_REVIEW.md
new file mode 100644
index 0000000..4bd8a12
--- /dev/null
+++ b/docs/PROJECT_REVIEW.md
@@ -0,0 +1,171 @@
+# Project review and remediation record
+
+- Date: 2026-08-12
+- Baseline: `55dd961` (`main`, package version `0.9.1`)
+- Remediation target: current working tree (planned package version `0.10.0`)
+
+This document records the pre-release review of boundver's correctness,
+security, packaging, onboarding, documentation, automation, and public project
+surface. “Resolved” means the repository now contains the implementation,
+regression coverage, or repeatable source-level verification named below. It
+does not mean the release candidate has passed external CI or been published.
+
+## Executive summary
+
+All findings identified in the baseline review and the subsequent focused
+security/correctness passes are resolved in the current tree. Fingerprint
+generation and verification now fail closed, hashing uses an unambiguous v2
+wire format, Git paths are handled as NUL-delimited literal data, custom Python
+providers require caller-controlled opt-in, and the public Action treats inputs
+as data. Lock/config validation, partial updates, metadata/provider checks,
+source modes, and OpenAPI canonicalization have focused regression coverage.
+
+The usability and visibility work is also represented in the repository: the
+README has an immediate workflow, examples use the installed CLI, one public
+Action is documented, package metadata and community files are present, and
+the supported Python floor is consistently 3.9. Release readiness remains
+conditional on the unchecked execution and publication gates at the end of
+this document; no claim is made here that external CI, GitHub Marketplace, or
+PyPI has completed those gates.
+
+## Baseline findings (BV-001–BV-042)
+
+| ID | Severity | Area | Resolution evidence | Status |
+|---|---|---|---|---|
+| BV-001 | Critical | Generation | Strict generation rejects `version_errors`, `exact_errors`, `behavior_errors`, and boundary errors; missing/oversized/raced-file regressions are in `tests/test_hashing_contract.py` and `tests/test_boundary_lock.py`. | Resolved |
+| BV-002 | Critical | Verification | `changed_components_since_ref` rejects invalid refs and conservatively covers config/unmapped changes and slices; see `test_verify_invalid_changed_from_exits_usage` and changed-from tests in `tests/test_cli_main.py`. | Resolved |
+| BV-003 | Critical | Hashing | `_hash_framed_entries` uses a versioned, domain-separated, length-prefixed binary frame; collision and known-vector tests are in `tests/test_hashing_contract.py`. | Resolved |
+| BV-004 | High | Git paths | Git filenames use NUL-delimited byte output plus filesystem decoding; Unicode, newline, non-UTF-8, and literal-backslash regressions are in `tests/test_hashing_contract.py`. | Resolved |
+| BV-005 | High | Canonical OpenAPI | `_strip_openapi` distinguishes annotation fields from user-named maps; `tests/test_provider_contract.py` covers annotation-looking schema/property names. | Resolved |
+| BV-006 | High | Guardrails | `_git_batch_cat` rejects missing, malformed, truncated, non-blob, and oversized responses; focused tests are in `tests/test_hashing_contract.py` and `tests/test_coverage_gaps.py`. | Resolved |
+| BV-007 | High | Custom providers | `_resolve_allow_custom` accepts only caller flag/environment authorization; `load_custom_providers` validates module/class/name inputs. Coverage is in `tests/test_providers.py`, `tests/test_edge_cases.py`, and `tests/test_cli_main.py`. | Resolved |
+| BV-008 | High | GitHub Actions | Root `action.yml` passes inputs through environment variables and a quoted Bash array, validates enums, and installs from `github.action_path`; `.github/workflows/ci.yml` contains a hostile-input contract check. | Resolved |
+| BV-009 | High | Source modes | `_list_files_for_source` treats the successful Git index as authoritative and working-tree mode as tracked-only; see the corresponding tests in `tests/test_hashing_contract.py`. | Resolved |
+| BV-010 | High | Lock semantics | `COMPONENT_METADATA_FIELDS`, structure validation, and `verify_lockfile` cover path, version, provider identity/version, status, SemVer, consumers, metadata, vendored data, and recorded errors. | Resolved |
+| BV-011 | High | Partial generation | `generate_lockfile_for_components` requires a valid v2 base, recomputes current entries, rejects stale unselected entries, reconciles removals, and recomputes all slices; see partial-generation tests in `tests/test_core_branches.py`. | Resolved |
+| BV-012 | Medium | Installed validation | The config schema is package data under `src/boundver/`; `scripts/packaging_smoke.sh` inspects the wheel and validates an installed copy in an unrelated repository. | Resolved |
+| BV-013 | Medium | Config loading | Config and lock loaders reject non-object roots, and hand validation covers malformed nested data; see `tests/test_core_branches.py`, `tests/test_boundary_lock.py`, and `tests/test_cli_main.py`. | Resolved |
+| BV-014 | Medium | Config mutation | `_ensure_json_mutation_path` prevents `init`, `add`, and `remove` from serializing JSON into YAML/TOML paths. | Resolved |
+| BV-015 | Medium | Discovery | Git-aware discovery uses manifest-specific version sources and deduplicates directories; see `test_discover_components_uses_tracked_manifests_and_deduplicates_dirs`. | Resolved |
+| BV-016 | Medium | First run | `init --discover` discloses an empty result instead of inventing `src`, and working-tree validation rejects missing component roots; covered in discovery/init and config-validation tests. | Resolved |
+| BV-017 | Medium | Status UX | `print_status` shows component identity, path, version, provider/status, short fingerprints, consumers, and all error categories with corrected guidance; status tests cover text and JSON. | Resolved |
+| BV-018 | Medium | Action contract | The duplicate repository-local Action was removed; root `action.yml` is the documented interface and emits command-aware JSON outputs. | Resolved |
+| BV-019 | Medium | CLI protocol | Runtime JSON and schemas agree, including status warnings; `tests/test_cli_output_schemas.py` validates real command payloads. | Resolved |
+| BV-020 | Medium | Provider protocol | Provider metadata, validation, and explanations are wired, and operations use isolated registries; contract tests are in `tests/test_provider_contract.py`. | Resolved |
+| BV-021 | Medium | Completions | Completion scripts cover every parser subcommand and supported options; see completion tests in `tests/test_boundary_lock.py` and `tests/test_cli_main.py`. | Resolved |
+| BV-022 | Medium | Module entry point | `src/boundver/__main__.py` exists, and `scripts/packaging_smoke.sh` exercises installed `python -m boundver --version`. | Resolved |
+| BV-023 | Medium | Python support | `tomli` is conditional for Python below 3.11, and the supported/build/test floor is consistently Python 3.9 in `pyproject.toml`, docs, and workflow matrices. External matrix execution remains a release gate. | Resolved |
+| BV-024 | Medium | Release safety | `.github/workflows/publish.yml` validates exact tag/package-version equality, runs tests, builds, checks distributions, and publishes only the verified artifact job output. | Resolved |
+| BV-025 | Medium | Documentation | `README.md` leads with the canonical workflow; `docs/ci-cookbook.md` uses the public Action or explicit installation, and packaging smoke covers the installed workflow. | Resolved |
+| BV-026 | Medium | Documentation accuracy | README/getting-started/CI guidance pairs source modes and describes declared-artifact drift rather than semantic compatibility proof. | Resolved |
+| BV-027 | Medium | Examples | Example READMEs use `boundver`; `test_examples_expected_lockfiles_are_current` verifies their expected lockfiles. | Resolved |
+| BV-028 | Medium | Package metadata | `pyproject.toml` contains keywords, classifiers, project URLs, and publication-safe documentation links. Rendered PyPI verification remains a publication gate. | Resolved |
+| BV-029 | Medium | Public repository | `SECURITY.md`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, issue forms, and the pull-request template are present. | Resolved |
+| BV-030 | Low | Test portability | Subprocess tests use the active interpreter (`sys.executable`) or platform-appropriate installed commands instead of assuming a `python` shim. | Resolved |
+| BV-031 | Low | Distribution contents | Package-data/MANIFEST configuration includes runtime schema, type marker, specs, policies, and tests needed by the sdist; `scripts/packaging_smoke.sh` inspects wheel and sdist members. | Resolved |
+| BV-032 | Low | Packaging lifecycle | `pyproject.toml` uses the SPDX `license = "MIT"` form plus `license-files`, and its Python 3.9 floor is compatible with the security-patched `setuptools>=78.1.1` build requirement. | Resolved |
+| BV-033 | Medium | Diff reporting | `_diff.py` compares the shared `COMPONENT_METADATA_FIELDS` as well as fingerprints and reports metadata-only changes. | Resolved |
+| BV-034 | Medium | Shell verifier | The divergent standalone shell verifier was retired; `spec/HASHING.md` and Python v2 hashing are the supported contract. | Resolved |
+| BV-035 | Medium | Line endings | All source modes use the same text CRLF normalization while preserving binary bytes; cross-source and CRLF tests are in `tests/test_hashing.py`, `tests/test_hashing_contract.py`, and `tests/test_providers.py`. | Resolved |
+| BV-036 | High | CI policy | CLI/config `verify_facets`, non-gating observations, JSON output, and Action inputs separate exact-only observations from gated facets; see facet/update tests in `tests/test_cli_main.py`. | Resolved |
+| BV-037 | High | Exit protocol | `core.py` defines distinct usage, behavior, boundary, and compatibility exit codes and chooses the highest gated severity; CLI tests cover boundary, behavior, and compatibility exits. | Resolved |
+| BV-038 | High | Consumer impact | Config validation and lock metadata support `consumers`; verify/why report affected consumers. `MainSeverityAndConsumerTests` provides end-to-end coverage. | Resolved |
+| BV-039 | Medium | Discovery scale | Discovery prefers NUL-safe `git ls-files`, deduplicates directories, excludes known dependency/build/vendor directories, and retains a bounded non-Git fallback; `test_discover_components_excludes_ignored_dirs` covers the exclusions. | Resolved |
+| BV-040 | Medium | Contract additions | Glob behavior is documented and tested for matching, traversal rejection, newly added files, and content changes in `tests/test_providers.py`. | Resolved |
+| BV-041 | Medium | Merge workflow | The unsound merge-driver script was retired; `docs/LOCKFILE_MERGE.md` specifies post-merge full regeneration and verification. | Resolved |
+| BV-042 | Medium | Update UX | `verify --update` recomputes successfully before atomically replacing the lock via `_write_text_atomic`; update behavior is covered in `tests/test_cli_main.py`. | Resolved |
+
+## Follow-up security and correctness findings (BV-043 onward)
+
+These findings were discovered during adversarial re-review after the baseline
+remediation. They are listed separately to preserve the audit trail rather than
+folding them invisibly into the broader baseline items.
+
+| ID | Severity | Area | Finding and resolution evidence | Status |
+|---|---|---|---|---|
+| BV-043 | High | Changed selection | A component configured at `.` was not selected for root-file changes. `_git.py::changed_components_since_ref` now handles root paths; `ChangedFromRootComponentTests` verifies the mapping. | Resolved |
+| BV-044 | High | Provider path identity | Root-component label slicing could drop the first filename character, making a rename hash-insensitive. `_component_relative_path` now derives exact labels; `RootPathBoundaryIdentityTests` verifies rename sensitivity. | Resolved |
+| BV-045 | High | POSIX filenames | Replacing backslashes in Git-returned paths collapsed distinct POSIX names such as `a\b` and `a/b`. Labels now preserve literal backslashes; `test_literal_backslash_filename_is_not_treated_as_a_separator` covers it. | Resolved |
+| BV-046 | High | Git pathspecs | Component names beginning with Git pathspec magic, such as `:(literal)foo`, could select a different tree. Hashing and diagnostics now pass `--literal-pathspecs` in `_git.py` and `_output.py`. | Resolved |
+| BV-047 | High | Partial locks | Component-scoped generation could create an incomplete first lock or relabel v1 digests as v2. It now requires an existing structurally valid v2 lock; `test_missing_existing_lockfile_requires_full_generation` and `test_non_v2_existing_lockfile_requires_full_generation` cover both cases. | Resolved |
+| BV-048 | High | Partial locks | A valid-looking partial update could retain stale unselected component/config/provider data. Partial generation now recomputes the full current lock and rejects stale unselected entries before merging, then rebuilds every slice. | Resolved |
+| BV-049 | High | Declared paths | Providers treated the declaration set as valid when one path matched even if another literal/glob did not. Raw and canonical providers now track every unmatched declaration and return an error; provider tests cover missing literals and globs. | Resolved |
+| BV-050 | High | Versions | A configured version source that was missing, unparsable, or non-SemVer could produce `null` compatibility data without failing strict generation. `_compute_component_entry` records `version_errors`, and `parse_semver` uses full-string validation; version-source and trailing-junk tests cover it. | Resolved |
+| BV-051 | High | Tag versions | `--changed-from` could omit tag-derived components because tags do not appear in a file diff. `_git.py` always includes components using `git_tag_prefix`; the tagged selector assertion in `test_verify_changed_from_checks_unselected_component_metadata` exercises it. | Resolved |
+| BV-052 | High | Verification preflight | Unknown explicit `--components` entries could be intersected away by `--changed-from` and return clean. `_cmd_verify` validates requested names before selection; `test_verify_unknown_components_exits_2` covers the controlled error. | Resolved |
+| BV-053 | High | Verification preflight | Unknown facets, malformed locks, component/slice set drift, and recorded lock errors could be bypassed by an empty changed set. `_cmd_verify` performs these preflight checks before changed-path scheduling; CLI malformed/facet/ref tests cover the paths. | Resolved |
+| BV-054 | Medium | Malformed locks | Nested v2 fields such as fingerprints, SemVer, consumers, error arrays, vendored metadata, and slice members could crash verify/status/slice/why. `_lockfile_structure_issues` now validates consumed types and command handlers use it; `MainMalformedV2LockTests` verifies controlled errors. | Resolved |
+| BV-055 | Medium | Malformed config | Nested non-object/non-string config values could reach provider/path logic when optional `jsonschema` was absent. Hand validation now guards defaults, providers, components, boundaries, behaviors, versions, consumers, vendored paths, and slices; malformed-config tests run with the schema engine disabled. | Resolved |
+| BV-056 | High | Source modes | Public/core API source typos silently behaved like working-tree mode. `_normalize_source` now accepts only `head`, `index`, or `working-tree`, and all lock operations/accessors call it. | Resolved |
+| BV-057 | High | Self-referential locks | A lock output inside a component, especially a root component, became part of its own exact fingerprint. Config rejects root components and `_ensure_lock_outside_components` guards CLI and public API generate/verify paths. | Resolved |
+| BV-058 | High | Traversal and symlinks | Component, boundary, behavior, version-source, and vendored paths could traverse or follow working-tree symlinks outside the repository. `_config.py`, `_SourceAccessor`, and hashing containment checks reject unsafe paths or hash Git symlink blobs as link text; focused containment tests cover component roots, version files, vendored paths, boundary paths, and cross-source symlink-blob parity. | Resolved |
+| BV-059 | High | Public API | `boundver.generate()` and `boundver.verify()` bypassed full config/source validation, robust lock loading, and self-lock guards. `src/boundver/__init__.py` now shares `validate_config`, `_load_lockfile`, and `_ensure_lock_outside_components` with the CLI. | Resolved |
+| BV-060 | Medium | Source-aware validation | `head`/`index` operations validated required files only against the working disk, rejecting valid committed snapshots after local deletion. `validate_config(source=...)` now defers snapshot existence to Git; `SourceAwareValidationTests` covers a deleted working-tree component still present at HEAD. | Resolved |
+| BV-061 | High | Project metadata | A missing or changed lockfile project could pass when fingerprints matched. Lock structure requires a non-empty project and verification compares it with config before component work. | Resolved |
+| BV-062 | High | Changed-from integrity | With no selected path changes, `--changed-from` returned before current metadata/provider versions were recomputed. It now falls through to full integrity verification; `test_verify_changed_from_no_paths_still_checks_provider_version` covers the failure. | Resolved |
+| BV-063 | High | Changed-from integrity | The first fix still skipped unselected entries whenever any component was selected (for example, a tag-versioned component). Changed paths are now reporting-only while all entries are recomputed; `test_verify_changed_from_checks_unselected_component_metadata` covers the two-component tagged/tampered case. | Resolved |
+| BV-064 | High | Canonical OpenAPI | Additional arbitrary-name maps—including paths/webhooks, component maps, security requirements, callbacks, links, server variables, schema maps, headers, encodings, and mappings—could lose keys named `description`, `example`, or `x-*`. `_OPENAPI_COMPONENT_MAPS` and `_OPENAPI_NAMED_MAP_KEYS` enumerate those contexts; `tests/test_provider_contract.py` explicitly exercises schema/property/definition and callback/link/variable names. | Resolved |
+| BV-065 | Medium | Fail-fast severity | `--fail-fast` could return a lower-severity first component drift while a later component had compatibility drift. Verification now evaluates all selected entries, chooses the global highest-severity issue, and only then limits the report. | Resolved |
+| BV-066 | Medium | Slice exits | Slice mismatches omitted their mode, so the exit-code mapper could not assign behavior/boundary/compatibility severity. Slice messages now include `<slice>.<mode>` and `_drift_exit_code` applies the same severity contract. | Resolved |
+| BV-067 | High | Git failure handling | A Git listing failure inside a real repository could fall back to approximate filesystem enumeration and produce a false-clean fingerprint. `_list_files_for_source` now re-raises in real repositories and reserves the bounded fallback for non-Git/unborn setup. | Resolved |
+| BV-068 | Medium | Diagnostics | Explain/why diagnostics used line-delimited Git names and non-literal pathspecs, corrupting quoted, newline, or pathspec-magic filenames. `_output.py` now uses `--name-status -z`, `_parse_name_status_z`, filesystem decoding, and `--literal-pathspecs`. | Resolved |
+| BV-069 | Medium | Schema-independent identity | Project type and component/slice key types depended on optional `jsonschema`, allowing schema-invalid identities on a base install. Explicit checks were added; `SchemaIndependentConfigValidationTests` patches out the schema engine and verifies rejection. | Resolved |
+| BV-070 | Medium | Build/runtime floor | The earlier Python 3.8 support claim conflicted with the setuptools build-backend floor. `pyproject.toml`, CI matrices, README, maintained guides, and `CHANGELOG.md` now consistently declare Python 3.9+. External matrix execution remains a release gate. | Resolved |
+| BV-071 | Medium | Atomic writes | Direct lock/config replacement could leave truncated JSON if writing failed. `_write_text_atomic` writes and fsyncs a sibling temporary file before `os.replace`, and generate, verify-update, migration, init, add, and remove route mutations through it. | Resolved |
+| BV-072 | Medium | Documentation lifecycle | The historical implementation plan described a retired Action interface and linked deleted design/CI files, while a provider docstring repeated one stale link. The obsolete plan is retired and the provider points to the maintained custom-provider guide. | Resolved |
+
+## Verification index
+
+The main repeatable local evidence is grouped here to keep the finding tables
+readable:
+
+- `tests/test_hashing_contract.py`: v2 framing, filename byte safety, tracked
+  source semantics, guardrails, malformed Git batch data, and read races.
+- `tests/test_provider_contract.py` and `tests/test_providers.py`: provider
+  framing/metadata/hooks, registry isolation, OpenAPI named maps, declared path
+  matching, canonicalization, and globs.
+- `tests/test_security_regressions.py`: root-path identity and selection,
+  schema-independent identity validation, and source-aware validation.
+- `tests/test_cli_main.py`: verification preflight, changed-from full integrity,
+  malformed nested locks, facets/update behavior, exit severity, and consumers.
+- `tests/test_boundary_lock.py`, `tests/test_core_branches.py`, and
+  `tests/test_edge_cases.py`: lock generation/verification, partial locks,
+  metadata, discovery, versions, config validation, source modes, and commands.
+- `tests/test_cli_output_schemas.py`: real JSON payloads against the published
+  command schemas.
+- `scripts/packaging_smoke.sh`: distribution membership and installed CLI/module
+  entry-point workflow.
+
+The committed release candidate passed all 834 unit/integration tests in four
+balanced shards without an environment shim. Fresh wheel and sdist builds from
+that exact commit contained the required runtime/audit assets; the extracted
+wheel passed module-entry-point, config validation, generate, verify, and status
+smoke checks in an unrelated Git repository. These local results do not
+substitute for the supported-version CI matrix or the publication workflow.
+
+## Visibility and adoption baseline
+
+At review time, the public repository had one star, no forks, no GitHub
+Releases, and an existing Marketplace listing at version `0.9.1`. PyPI's latest
+release was also `0.9.1`, published through trusted publishing. The remediation
+tree now configures project links, discovery keywords, clearer outcome-led
+messaging, an immediate copyable workflow, and one canonical Action. Those
+changes are not described as publicly released until the publication gates
+below complete.
+
+The intended audience is teams maintaining polyglot repositories, services,
+or dynamically typed libraries whose consumer-facing contracts are represented
+by files such as OpenAPI, JSON Schema, or public export modules. Messaging makes
+clear that boundver detects drift in declared artifacts; it does not prove
+semantic or backward compatibility.
+
+## Release gate
+
+- [x] Every finding above is marked resolved with a verification reference.
+- [x] Unit and integration suites pass without environment shims (834 tests).
+- [ ] Supported Python versions pass in external CI.
+- [ ] Root Action passes its external workflow test with safe input handling.
+- [x] Wheel and sdist inspection plus installed-package smoke tests pass for the exact local release commit.
+- [ ] Tag exactly matches `pyproject.toml` and `boundver.__version__`.
+- [ ] GitHub branch/PR checks pass before the release tag is created.
+- [ ] GitHub Release, Marketplace tag, and PyPI publication all point to the same commit.
diff --git a/docs/WHY_BOUNDVER.md b/docs/WHY_BOUNDVER.md
index 6310866..44efeed 100644
--- a/docs/WHY_BOUNDVER.md
+++ b/docs/WHY_BOUNDVER.md
@@ -21,7 +21,7 @@ boundver provides **machine-verifiable change classification** at these boundari
 ### You probably **do** need boundver if…
 - Your components have consumers but lack static verification of their interface.
 - You want to distinguish "internals changed" from "behavior changed" from "boundary changed" from "compatibility broke" — automatically, not via commit messages.
-- You need a portable, source-controlled lockfile (`boundary-lock/v1`) that CI, scripts, and downstream tools can consume.
+- You need a portable, source-controlled lockfile (`boundary-lock/v2`) that CI, scripts, and downstream tools can consume.
 - You want stable CI cache keys and verification signals without migrating your entire build stack.
 
 ## Positioning
@@ -62,7 +62,7 @@ These are **conscious scope boundaries**, not bugs:
 | **Behavioral change in an undeclared file** | If a file changes behavior but isn't in `behavior.paths`, boundver can't know about it. The user must declare what matters. |
 | **Protocol/wire-format semantic change** | If the `.proto` or schema file type is unchanged but the runtime interpretation differs, no file content changes. |
 
-For the last case — where no static file analysis can detect the change — a custom provider that hashes test output can bridge the gap. See [design/08-behavior-tier.md](design/08-behavior-tier.md#extension-test-output-fingerprinting-via-custom-provider).
+For the last case — where no static file analysis can detect the change — a trusted custom provider can hash a deterministic test-output artifact. Treat such providers as executable code and enable them only through the explicit trusted-code opt-in.
 
 ## Adoption pattern
 
diff --git a/docs/ci-cookbook.md b/docs/ci-cookbook.md
index 7c08ff1..9f5804d 100644
--- a/docs/ci-cookbook.md
+++ b/docs/ci-cookbook.md
@@ -1,16 +1,12 @@
-# CI Cookbook
+# CI cookbook
 
-Practical recipes for integrating boundver into CI/CD pipelines.
+These recipes keep the source snapshot, lockfile, and enforcement policy explicit. For pull requests, `head` compares the committed PR tree with the committed lockfile.
 
-## GitHub Actions
-
-### Basic PR verification
-
-Blocks merging if the lockfile is stale. Shows a diff when it fails.
+## GitHub Actions: recommended boundary gate
 
 ```yaml
 # .github/workflows/boundary-check.yml
-name: Boundary check
+name: Contract boundary
 on: [pull_request]
 
 jobs:
@@ -21,205 +17,172 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: yzm1/boundver@v0
         with:
-          python-version: '3.11'
-
-      - run: pip install boundver
-
-      - name: Verify lockfile
-        run: boundver verify
-
-      - name: Show diff on failure
-        if: failure()
-        run: |
-          boundver generate --out boundary.lock.new.json
-          boundver diff boundary.lock.json boundary.lock.new.json
+          config: boundary.config.json
+          lock: boundary.lock.json
+          source: head
+          facets: boundary,compat
 ```
 
-### Verify only components that changed in this PR
+This gate permits exact-only internal refactors while failing declared boundary and compatibility changes. The public Action installs the boundver version bundled with `yzm1/boundver@v0`; no separate Python setup or install step is needed.
 
-Skips components that weren't touched, which is faster for large repos:
+The four shown inputs are the portable baseline:
 
-```yaml
-- name: Verify changed components only
-  run: |
-    boundver verify --changed-from origin/${{ github.base_ref }}
-```
+- `config`: configuration path relative to the checkout root
+- `lock`: lockfile path relative to the checkout root
+- `source`: `head`, `index`, or `working-tree`
+- `facets`: comma-separated fingerprints that should fail the job
 
-If no components changed, the command exits 0 immediately. If a changed component's lockfile entry is stale, it exits 1.
+The Action also supports `components`, `changed-from`, `fail-fast`, `update`, and `python-version` for specialized workflows.
 
-### Generate and commit the lockfile in CI (for auto-update workflows)
+## Pick a signal-to-noise policy
 
-Some teams prefer a CI job that regenerates and commits the lockfile automatically rather than requiring developers to regenerate locally:
+The most useful first gate is usually:
 
 ```yaml
-name: Update boundary lockfile
-on:
-  push:
-    branches: [main]
-
-jobs:
-  update-lockfile:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+facets: boundary,compat
+```
 
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
+Other common policies are:
 
-      - run: pip install boundver
+| Policy | Facets | What fails |
+|---|---|---|
+| Consumer-facing | `boundary,compat` | Declared API and compatibility drift |
+| Behavior-sensitive | `behavior,boundary,compat` | Runtime contract, API, and compatibility drift |
+| Full lock hygiene | `exact,behavior,boundary,compat` | Any tracked component drift |
 
-      - name: Regenerate lockfile
-        run: boundver generate
+You can keep policy in the repository instead of the workflow:
 
-      - name: Commit if changed
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add boundary.lock.json
-          git diff --cached --quiet || git commit -m "chore: regenerate boundary lockfile [skip ci]"
-          git push
+```json
+{
+  "defaults": {
+    "verify_facets": ["boundary", "compat"]
+  }
+}
 ```
 
-> **Note:** Lockfiles are always deterministic (no timestamps). The lockfile only changes when actual content changes.
-
----
+Then omit `facets` when invoking the CLI directly. The Action intentionally defaults to `boundary,compat`.
 
-## Using slice fingerprints as cache keys
+Drift outside the gate is returned as a non-gating observation. Structural, metadata, and digest errors remain failures because they make the comparison unreliable.
 
-### GitHub Actions cache
+## Verify only components touched by a pull request
 
-Gate downstream jobs on whether the relevant API slice changed:
+Fetch history and compare with the base branch:
 
 ```yaml
-jobs:
-  check-api-change:
-    runs-on: ubuntu-latest
-    outputs:
-      api-fingerprint: ${{ steps.fp.outputs.fingerprint }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-      - run: pip install boundver
-      - name: Extract slice fingerprint
-        id: fp
-        run: |
-          FP=$(python -c "
-          import json
-          lock = json.load(open('boundary.lock.json'))
-          print(lock['slices']['auth-api']['fingerprint'][:16])
-          ")
-          echo "fingerprint=$FP" >> "$GITHUB_OUTPUT"
-
-  build-consumers:
-    needs: check-api-change
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/cache@v4
-        with:
-          path: consumer-build/
-          key: consumer-build-${{ needs.check-api-change.outputs.api-fingerprint }}
-      - name: Build consumers (only runs if cache miss)
-        run: make build-consumers
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+
+- uses: yzm1/boundver@v0
+  with:
+    config: boundary.config.json
+    lock: boundary.lock.json
+    source: head
+    facets: boundary,compat
+    changed-from: origin/${{ github.base_ref }}
 ```
 
-The build step is a no-op on cache hit. The cache key rotates automatically when the `auth-api` boundary fingerprint changes — and only then.
+`--changed-from` reports which components and slices are affected by Git-tracked
+paths, while still recomputing the full lock for integrity. This deliberately
+prevents an unchanged path set from hiding stale provider metadata or a tampered
+entry. An invalid or unavailable ref is a usage error rather than a silent pass,
+and configuration changes affect every component because they can add, remove,
+or redefine contracts independently of source-file paths.
 
-### Conditional downstream trigger
+## Explicit install instead of the Action
 
-```bash
-# Read fingerprint from lockfile
-CURRENT_FP=$(python -c "
-import json
-lock = json.load(open('boundary.lock.json'))
-print(lock['slices']['auth-api']['fingerprint'])
-")
-
-# Compare to last-known fingerprint stored as a CI artifact or env var
-if [ "$CURRENT_FP" != "$LAST_KNOWN_FP" ]; then
-  echo "API boundary changed — triggering downstream pipeline"
-  # curl to trigger another pipeline, dispatch a workflow, etc.
-fi
+Pin the package version for reproducibility:
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+    with:
+      fetch-depth: 0
+  - uses: actions/setup-python@v6
+    with:
+      python-version: "3.12"
+  - run: python -m pip install "boundver==0.10.0"
+  - run: boundver verify --source head --facets boundary,compat
 ```
 
----
+Use this form when your organization mirrors PyPI or centrally manages Python environments.
 
-## GitLab CI
+## Inspect failures without regenerating in CI
+
+Lockfile updates are review decisions, so a PR gate should normally report drift and leave the checkout unchanged:
 
 ```yaml
-boundary-verify:
-  stage: validate
-  image: python:3.11-slim
-  script:
-    - pip install boundver
-    - boundver verify
-  only:
-    - merge_requests
+- name: Verify contracts
+  run: boundver verify --source head --facets boundary,compat
+
+- name: Print machine-readable details
+  if: failure()
+  run: boundver verify --source head --facets boundary,compat --format json
 ```
 
----
+Locally, the author can inspect and accept a gated change in one step:
 
-## Handling merge conflicts in the lockfile
+```bash
+boundver verify --source working-tree --facets boundary,compat
+boundver why payment-api --source working-tree
+boundver verify --source working-tree --facets boundary,compat --update
+git diff -- boundary.lock.json
+```
 
-The lockfile is a JSON file. Merge conflicts happen when two branches update different components concurrently. See [LOCKFILE_MERGE.md](LOCKFILE_MERGE.md) for the recommended merge driver setup.
+To refresh non-gating exact and behavior drift too, pass all four facets to the update command.
 
-Quick summary: use `boundver generate` on the merged result and let the tool recompute from source truth rather than trying to resolve JSON conflicts by hand.
+## Exit-code-aware automation
 
----
+`verify` returns the highest selected severity:
 
-## JSON output for scripting
+| Code | Meaning |
+|---:|---|
+| `0` | Clean |
+| `1` | Exact or metadata drift |
+| `2` | Usage or configuration error |
+| `3` | Behavior drift |
+| `4` | Boundary drift |
+| `5` | Compatibility drift |
 
-All commands that produce output support `--format json` for machine-readable results:
+For example, a shell job can distinguish an invalid invocation from contract drift:
 
 ```bash
-# Check if lockfile is up to date and capture result
-RESULT=$(boundver verify --format json)
-OK=$(echo "$RESULT" | python -c "import json,sys; print(json.load(sys.stdin)['ok'])")
-
-if [ "$OK" != "True" ]; then
-  echo "Lockfile out of date"
-  echo "$RESULT" | python -c "import json,sys; [print(i) for i in json.load(sys.stdin)['issues']]"
-  exit 1
-fi
-```
+set +e
+boundver verify --source head --facets behavior,boundary,compat --format json > boundver-result.json
+code=$?
+set -e
 
-```bash
-# Get slice fingerprint as a single value
-python -c "
-import json
-lock = json.load(open('boundary.lock.json'))
-print(lock['slices']['my-slice']['fingerprint'])
-"
+case "$code" in
+  0) echo "Declared contracts are current" ;;
+  2) echo "boundver could not perform a reliable check" >&2; exit 2 ;;
+  3) echo "Behavior contract changed" >&2; exit 3 ;;
+  4) echo "Boundary changed; re-verify consumers" >&2; exit 4 ;;
+  5) echo "Compatibility family changed" >&2; exit 5 ;;
+  *) echo "Unexpected boundver result: $code" >&2; exit "$code" ;;
+esac
 ```
 
----
+The Action exposes `exit-code`, newline-separated `issues`, and `observations` outputs for workflows that use `continue-on-error` and apply their own policy.
 
-## Pre-commit hook
-
-Add a pre-commit hook to catch stale lockfiles before they're pushed:
+## GitLab CI
 
-```bash
-# .git/hooks/pre-commit
-#!/bin/bash
-set -e
-if [ -f boundary.config.json ]; then
-  boundver verify --source working-tree || {
-    echo "Lockfile is stale. Run: boundver generate --source working-tree"
-    exit 1
-  }
-fi
+```yaml
+boundary-verify:
+  stage: test
+  image: python:3.12-slim
+  before_script:
+    - python -m pip install "boundver==0.10.0"
+  script:
+    - boundver verify --source head --facets boundary,compat
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
 ```
 
-Or use the pre-commit framework:
+## Pre-commit
+
+Working-tree verification should be paired with working-tree updates:
 
 ```yaml
 # .pre-commit-config.yaml
@@ -227,22 +190,54 @@ repos:
   - repo: local
     hooks:
       - id: boundver-verify
-        name: Verify boundary lockfile
-        entry: boundver verify --source working-tree
+        name: Verify declared boundaries
+        entry: boundver verify --source working-tree --facets boundary,compat
         language: system
         pass_filenames: false
         always_run: true
 ```
 
----
+If the hook finds intentional drift, review it and run:
+
+```bash
+boundver verify --source working-tree --facets boundary,compat --update
+git add boundary.lock.json
+```
+
+New files must already be known to Git for working-tree and index modes.
 
-## Skipping verification for non-component changes
+## Use a slice fingerprint as a cache key
 
-If your repo has docs, CI config, or root-level files that shouldn't trigger a lockfile update, scope your `verify` call to components actually relevant to the change:
+A slice combines one facet from several components. Read its committed fingerprint into a workflow output:
 
-```bash
-# Only verify components changed since the base branch
-boundver verify --changed-from origin/main
+```yaml
+jobs:
+  contract-key:
+    runs-on: ubuntu-latest
+    outputs:
+      fingerprint: ${{ steps.key.outputs.fingerprint }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: key
+        shell: bash
+        run: |
+          value=$(python -c 'import json; print(json.load(open("boundary.lock.json"))["slices"]["checkout-contracts"]["fingerprint"])')
+          echo "fingerprint=$value" >> "$GITHUB_OUTPUT"
+
+  build-consumers:
+    needs: contract-key
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with:
+          path: consumer-build
+          key: consumer-${{ needs.contract-key.outputs.fingerprint }}
+      - run: make build-consumers
 ```
 
-Components whose paths weren't touched are silently skipped, so unrelated PRs (e.g., README edits) pass without needing a lockfile update.
+A boundary-mode slice rotates only when one of its member boundaries changes. It is a deterministic cache key, not a substitute for running consumer tests after a contract change.
+
+## Concurrent lockfile updates
+
+Do not hand-edit JSON conflict hunks and do not run generation inside a Git merge driver. Finish merging source and configuration, then regenerate from the materialized working tree. See [Lockfile merge strategy](LOCKFILE_MERGE.md) for the command sequence and an optional post-merge hook.
diff --git a/docs/design/01-correctness-portability.md b/docs/design/01-correctness-portability.md
deleted file mode 100644
index c4077dc..0000000
--- a/docs/design/01-correctness-portability.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# 01 — Correctness & Portability Design
-
-## Goal
-Make boundary fingerprinting behavior explicit, deterministic, and portable for public users.
-
-## Scope
-- Normalize boundary extraction outcomes (`ok`, `partial`, `error`) and publish behavior contract.
-- Eliminate assumptions tied to internal/proprietary artifacts.
-- Provide actionable failures when configured boundaries are unavailable.
-
-## Design
-1. **Boundary status contract**
-   - `ok`: declared boundary paths exist and API digest is produced.
-   - `partial`: boundary intentionally implicit (`kind=implicit`) and no boundary paths are declared.
-   - `error`: boundary is explicit but no paths or no digest can be produced.
-2. **Provider portability layer**
-   - Separate public providers (`openapi`, `python-exports`, `typescript-exports`, `json-schema`) from optional org-specific providers.
-   - Unknown/custom providers can be registered through config-driven adapters (see doc 05).
-3. **Strict diagnostics**
-   - Include `boundary_errors` in lock output and `status` command.
-   - Preserve strict mode behavior in slices; `--allow-partial` remains explicit escape hatch.
-
-## Deliverables
-- Documented status model in README and config reference.
-- Provider capability matrix with public-first defaults.
-- Clear CLI warnings and failure messages.
diff --git a/docs/design/02-testing-strategy.md b/docs/design/02-testing-strategy.md
deleted file mode 100644
index ce4e656..0000000
--- a/docs/design/02-testing-strategy.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# 02 — Testing Strategy Design
-
-## Goal
-Raise confidence from smoke-level checks to production-grade coverage.
-
-## Scope
-- Unit, integration, snapshot, and edge-case testing for fingerprint correctness.
-
-## Design
-1. **Unit tests**
-   - Canonical JSON and hash determinism.
-   - SemVer parsing modes.
-   - TOML/YAML/JSON version extraction.
-2. **Integration tests (temp git repos)**
-   - `git init` + commits and tag workflows.
-   - Source mode behavior (`head`, `index`, `working-tree`).
-3. **Snapshot tests**
-   - Golden lockfile fixtures for representative repositories.
-4. **Edge cases**
-   - Missing/implicit boundaries, empty slices, no commits, unknown components.
-
-## Deliverables
-- Test matrix with required cases and expected outcomes.
-- Stable fixture generators for temporary repos.
-- Coverage targets for critical modules.
diff --git a/docs/design/03-ci-quality-gates.md b/docs/design/03-ci-quality-gates.md
deleted file mode 100644
index 351ff73..0000000
--- a/docs/design/03-ci-quality-gates.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# 03 — CI Quality Gates Design
-
-## Goal
-Provide predictable quality gates while controlling cost during rapid development.
-
-## Scope
-- Define staged CI re-enable plan and required checks.
-
-## Design
-1. **Stage A (current / cost-controlled)**
-   - Manual (`workflow_dispatch`) CI only.
-   - Keep tests runnable locally and in ad hoc CI.
-2. **Stage B (pre-v1 hardening)**
-   - PR-triggered tests on key versions.
-   - Lint/type checks as non-blocking signals.
-3. **Stage C (v1.0 and after)**
-   - Required PR checks (test + lint + type).
-   - Optional nightly broader matrix.
-
-## Deliverables
-- Cost-aware CI schedule.
-- Policy for when checks become required.
-- Rollback/fallback if CI spend spikes.
diff --git a/docs/design/04-runtime-version-support.md b/docs/design/04-runtime-version-support.md
deleted file mode 100644
index e981bc3..0000000
--- a/docs/design/04-runtime-version-support.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# 04 — Runtime Version Support Design
-
-## Goal
-Define supported Python versions and upgrade cadence.
-
-## Scope
-- Current supported floor (3.8+) and future expansion.
-
-## Design
-1. **Support tiers**
-   - **Tier 1 (required CI)**: Python 3.8–3.12.
-   - **Tier 2 (forward-compat validation)**: Python 3.13–3.14.
-2. **Compatibility policy**
-   - Avoid runtime dependencies where possible.
-   - Keep stdlib-only runtime behavior.
-3. **Release criteria**
-   - Any v1.0 release must pass Tier 1 and Tier 2 smoke tests.
-
-## Deliverables
-- Version support table in README/docs.
-- CI matrix plan including 3.13 and 3.14 before v1.0 finalization.
diff --git a/docs/design/05-custom-boundary-extension.md b/docs/design/05-custom-boundary-extension.md
deleted file mode 100644
index 1aa7fe9..0000000
--- a/docs/design/05-custom-boundary-extension.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# 05 — Custom Boundary Extension Design
-
-## Goal
-Make custom boundaries first-class so users can extend boundver without modifying core logic.
-
-## Problem statement
-Users need a clear way to hash API boundaries that are not built-in provider types.
-
-## Design
-1. **Provider interface contract**
-   - Input: component root, boundary config, source mode.
-   - Output: `digest`, `status`, `errors`, optional metadata.
-2. **Config-driven provider registration**
-   - Add `boundary.provider` and `boundary.options` in config.
-   - Support built-ins and local plugin providers.
-3. **Execution model**
-   - Provider resolves concrete files/content.
-   - Core canonicalizes resolved payload and hashes deterministically.
-4. **Safety constraints**
-   - Providers are pure/read-only.
-   - Fail closed (explicit `error`) if provider cannot resolve artifacts.
-
-## Example config sketch
-```json
-{
-  "components": {
-    "billing": {
-      "path": "services/billing",
-      "boundary": {
-        "kind": "custom",
-        "provider": "jsonpath-extract",
-        "options": {
-          "file": "contract.json",
-          "select": ["$.paths", "$.components.schemas"]
-        }
-      }
-    }
-  }
-}
-```
-
-## Deliverables
-- Provider API doc.
-- Two reference custom providers.
-- End-to-end examples showing custom boundary setup.
diff --git a/docs/design/06-config-schema-validation.md b/docs/design/06-config-schema-validation.md
deleted file mode 100644
index 26d6e01..0000000
--- a/docs/design/06-config-schema-validation.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# 06 — Config Schema & Validation Design
-
-## Goal
-Prevent invalid configurations early with schema + semantic validation.
-
-## Scope
-- JSON Schema publishing, editor support, and runtime validation messages.
-
-## Design
-1. **Schema layer**
-   - Publish `boundary.config.schema.json` with `$schema` support.
-   - Validate structure, required fields, enums, and types.
-2. **Semantic validation layer**
-   - Cross-reference slices/components.
-   - Detect duplicate component paths.
-   - Validate provider requirements and boundary path existence.
-3. **DX improvements**
-   - Actionable error messages with component/slice names and remediation hints.
-
-## Deliverables
-- Schema file versioned with releases.
-- Validation command output contract.
-- IDE autocompletion setup instructions.
diff --git a/docs/design/07-provider-architecture.md b/docs/design/07-provider-architecture.md
deleted file mode 100644
index 6ce8aa5..0000000
--- a/docs/design/07-provider-architecture.md
+++ /dev/null
@@ -1,334 +0,0 @@
-# 07 — Provider Architecture Design
-
-## Problem
-
-Today `boundary.provider` is a validation label only. Every provider (`openapi`,
-`python-exports`, `typescript-exports`, `json-file`, `leaf`, `implicit`) runs the
-same code path: list `boundary.paths`, read raw bytes, hash. No provider can
-normalize its content, explain a diff, or carry options beyond a path list.
-
-Consequences:
-- A comment added to an OpenAPI file changes the boundary digest even when the
-  API contract is identical.
-- Custom provider logic lives outside boundver and must own its own hashing,
-  removing the guarantee that fingerprints are computed consistently.
-- `explain_diff` can only say "bytes changed", not "endpoint `/billing` removed".
-
----
-
-## Goals
-
-1. Each provider controls **what content** is hashed, not how it is hashed.
-2. Core always owns the **canonical digest step** — same algorithm, same encoding.
-3. Providers are **pure/read-only** — no side effects.
-4. Built-in providers are thin wrappers; their current behavior is preserved
-   exactly until a semantic provider replaces them.
-5. Custom providers plug in without modifying core.
-
----
-
-## Core types
-
-```python
-from __future__ import annotations
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Callable, Dict, List, Optional, Protocol, runtime_checkable
-
-
-# ------------------------------------------------------------------
-# Passed to every provider method
-# ------------------------------------------------------------------
-@dataclass
-class ProviderContext:
-    repo_root: Path
-    component_path: str            # repo-relative, e.g. "services/billing"
-    boundary_cfg: dict             # full boundary config dict
-    source: str                    # "head" | "index" | "working-tree"
-    # Injected by core so providers never call git directly
-    read_file: Callable[[str], bytes]   # repo_rel_path → bytes
-    list_files: Callable[[str], List[str]]  # repo_rel_prefix → [repo_rel_path, ...]
-
-
-# ------------------------------------------------------------------
-# What a provider returns from resolve()
-# ------------------------------------------------------------------
-@dataclass
-class ResolvedBoundary:
-    # Ordered list of (label, content) pairs.
-    # Core hashes them as: sha256(concat("entry:<label>\n", content, ...))
-    # Labels must be deterministic; providers must sort them.
-    entries: List[tuple[str, bytes]] = field(default_factory=list)
-
-    status: str = "ok"            # "ok" | "partial" | "error"
-    errors: List[str] = field(default_factory=list)
-
-    # Optional structured metadata stored in the lockfile alongside the digest.
-    # Passed back to explain_diff() when available.
-    metadata: Optional[dict] = None
-```
-
-**Design note:** `entries` replaces the implicit `file:{path}\n{content}` format
-in the current code. The label is still `file:{rel_path}` for path-based providers,
-so all existing lockfile digests are preserved when built-ins are migrated.
-
----
-
-## Provider protocol
-
-```python
-@runtime_checkable
-class BoundaryProvider(Protocol):
-    # Stable identifier. Must match boundary.provider values in config.
-    name: str
-
-    def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
-        """Return the normalized content to be hashed.
-
-        Providers MUST:
-        - Return entries in deterministic (sorted) order.
-        - Not call subprocesses beyond what ctx.read_file / ctx.list_files provide.
-        - Not mutate any file on disk.
-        - Produce status="error" rather than raising for expected failure modes.
-        """
-        ...
-
-    def validate_config(
-        self,
-        boundary_cfg: dict,
-        component_path: str,
-        repo_root: Path,
-    ) -> List[str]:
-        """Return validation error strings. Empty list = valid."""
-        ...
-
-    def explain_diff(
-        self,
-        old_metadata: Optional[dict],
-        new_metadata: Optional[dict],
-        ctx: ProviderContext,
-    ) -> str:
-        """One-line human summary of what changed between two digests.
-
-        Receives the metadata blobs stored at generate-time.
-        If metadata is None (old lockfiles), return a generic message.
-        """
-        ...
-```
-
----
-
-## How core uses a provider
-
-```python
-def compute_boundary(
-    provider: BoundaryProvider,
-    ctx: ProviderContext,
-) -> tuple[Optional[str], str, List[str]]:
-    """Returns (digest | None, status, errors)."""
-    resolved = provider.resolve(ctx)
-    if resolved.status == "error" or not resolved.entries:
-        return None, resolved.status, resolved.errors
-    # Core owns hashing — providers never touch hashlib directly
-    h = hashlib.sha256()
-    for label, content in resolved.entries:
-        h.update(f"entry:{label}\n".encode("utf-8"))
-        h.update(content)
-    return h.hexdigest(), resolved.status, resolved.errors
-```
-
-This is the **only** place SHA-256 is called for boundary digests.
-
----
-
-## Provider registry
-
-```python
-_REGISTRY: Dict[str, BoundaryProvider] = {}
-
-def register_provider(p: BoundaryProvider) -> None:
-    _REGISTRY[p.name] = p
-
-def get_provider(name: str) -> Optional[BoundaryProvider]:
-    return _REGISTRY.get(name)
-```
-
-Built-in providers are registered at module import time. Custom providers are
-registered by loading a Python module path specified in the config (see §Custom
-providers below).
-
----
-
-## Built-in providers under the new model
-
-Each built-in is a thin class that replicates current raw-bytes behavior. No
-existing lockfile digests change.
-
-### `PathHashProvider` (base for `openapi`, `json-file`, `python-exports`, etc.)
-
-```python
-class PathHashProvider:
-    """Hash declared boundary paths as raw normalized bytes — current behavior."""
-    name: str  # set per subclass
-
-    def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
-        paths = ctx.boundary_cfg.get("paths", [])
-        if not paths:
-            return ResolvedBoundary(
-                status="error",
-                errors=["No boundary paths declared for explicit boundary provider"],
-            )
-        entries = []
-        for rel in sorted(paths):
-            full_base = f"{ctx.component_path}/{rel}".lstrip("/")
-            for repo_rel in sorted(ctx.list_files(full_base)):
-                content = ctx.read_file(repo_rel)
-                # CRLF normalisation preserved from current _read_path_content
-                if b"\r\n" in content and b"\x00" not in content:
-                    content = content.replace(b"\r\n", b"\n")
-                child_rel = repo_rel[len(ctx.component_path) + 1:]
-                entries.append((f"file:{child_rel}", content))
-        if not entries:
-            return ResolvedBoundary(
-                status="error",
-                errors=["Declared boundary paths produced no digest"],
-            )
-        return ResolvedBoundary(entries=entries)
-
-    def validate_config(self, boundary_cfg, component_path, repo_root):
-        errors = []
-        paths = boundary_cfg.get("paths", [])
-        for rel in paths:
-            full = repo_root / component_path / rel
-            if not full.exists():
-                errors.append(
-                    f"Boundary path not found: {component_path}/{rel}"
-                    " — ensure the file exists before running generate"
-                )
-        return errors
-
-    def explain_diff(self, old_meta, new_meta, ctx):
-        return "declared boundary artifact changed"
-```
-
-`ImplicitProvider` and `LeafProvider` mirror their current inline logic but as
-proper classes with `status="partial"` and `status="ok"` respectively.
-
----
-
-## Semantic providers (future built-ins)
-
-These live in `boundver/providers/` as opt-in imports (no mandatory dependencies).
-
-| Provider name | What `resolve()` does |
-|---|---|
-| `openapi-canonical` | Parse YAML/JSON, emit sorted paths+schemas as canonical JSON, strip `description`/`x-*` fields |
-| `json-canonical` | Parse JSON, emit RFC 8785 canonical form |
-| `python-exports` (semantic) | Parse `__all__` and public symbol signatures via `ast`, emit sorted symbol list |
-| `typescript-exports` (semantic) | Parse `.d.ts` public surface, emit sorted declaration list |
-
-These providers produce digests that are **stable across formatting changes** but
-change when the logical API changes. They are additive — existing raw providers
-remain available.
-
----
-
-## Custom providers
-
-A custom provider is a Python class in a file the user owns:
-
-```python
-# my_team/boundver_providers.py
-from boundver.providers import BoundaryProvider, ProviderContext, ResolvedBoundary
-
-class ServiceDefinitionProvider:
-    name = "custom.acme.service-definition.v1"
-
-    def resolve(self, ctx):
-        contract_file = ctx.boundary_cfg.get("options", {}).get("file", "contract.json")
-        content = ctx.read_file(f"{ctx.component_path}/{contract_file}")
-        normalized = _extract_stable_contract(content)  # team-owned logic
-        return ResolvedBoundary(entries=[("contract", normalized)])
-
-    def validate_config(self, boundary_cfg, component_path, repo_root):
-        return []
-
-    def explain_diff(self, old_meta, new_meta, ctx):
-        return "service contract changed"
-```
-
-**Config registration:**
-
-```json
-{
-  "providers": [
-    {"module": "my_team.boundver_providers", "class": "ServiceDefinitionProvider"}
-  ],
-  "components": {
-    "billing": {
-      "boundary": {
-        "provider": "custom.acme.service-definition.v1",
-        "options": {"file": "contract.json"}
-      }
-    }
-  }
-}
-```
-
-Core loads `providers` entries at startup, before processing components.
-The `custom.*` namespace is required for all user-defined providers; core
-refuses to load a class whose `name` does not start with `custom.`.
-
----
-
-## Security constraints
-
-- Custom provider modules are only loaded when `--allow-custom-providers` is
-  passed on the CLI (or `BOUNDVER_ALLOW_CUSTOM_PROVIDERS=1`). Without it, core
-  errors out if config references a `custom.*` provider with a `module` key.
-- Providers must not call `subprocess`, `os.system`, or write files. Core
-  enforces this in test mode via a restricted `ProviderContext` that replaces
-  `read_file`/`list_files` with sandboxed implementations.
-- Path arguments passed to `ctx.list_files` and `ctx.read_file` are validated
-  by core against the component root before the provider is invoked.
-
----
-
-## Migration plan
-
-1. **Phase 1 — Protocol in place, built-ins as thin wrappers** (no behavior change)
-   - Introduce `ProviderContext`, `ResolvedBoundary`, `BoundaryProvider` in
-     `boundver/providers.py`.
-   - Port `PathHashProvider`, `ImplicitProvider`, `LeafProvider` as classes.
-   - Replace inline hashing in `generate_lockfile()` with `compute_boundary()`.
-   - All 176 existing tests must pass unchanged (lockfile digests stable).
-
-2. **Phase 2 — `options` field + custom provider loading**
-   - Add `boundary.options` to config schema.
-   - Add `providers` top-level config key + loading logic.
-   - Add `--allow-custom-providers` flag.
-
-3. **Phase 3 — Semantic built-ins (opt-in)**
-   - Ship `openapi-canonical` and `json-canonical` in `boundver/providers/`.
-   - Gated behind explicit provider name; no existing lockfile affected.
-
----
-
-## What changes in lockfile output
-
-Phase 1: **nothing** — digests identical, `boundary_provider` field unchanged.
-
-Phase 2+: lockfile gains optional `boundary_metadata` per component when the
-provider returns non-null metadata. `verify` ignores it (does not hash it).
-`explain` uses it for richer diffs.
-
----
-
-## Files to create/modify
-
-| File | Action |
-|---|---|
-| `src/boundver/providers.py` | New: `ProviderContext`, `ResolvedBoundary`, `BoundaryProvider` protocol, built-in classes, registry |
-| `src/boundver/core.py` | Modify: replace inline boundary hashing with `compute_boundary()` call |
-| `boundary.config.schema.json` | Add: `providers` array, `boundary.options` object |
-| `tests/test_providers.py` | New: unit tests per provider class |
diff --git a/docs/design/08-behavior-tier.md b/docs/design/08-behavior-tier.md
deleted file mode 100644
index 4a0bc6f..0000000
--- a/docs/design/08-behavior-tier.md
+++ /dev/null
@@ -1,206 +0,0 @@
-# 08 — Behavior Tier
-
-## Problem
-
-The current three-tier fingerprint model (exact/boundary/compat) has a gap between "exact" and "boundary":
-
-- **exact** catches every file change — but does not distinguish an internal refactor from a behavioral contract change.
-- **boundary** only tracks declared surface files (openapi.yaml, `__init__.py`) — so it misses changes to defaults, config, migrations, error behavior, or any semantic change that doesn't alter the API *shape*.
-
-The result: a change that modifies a timeout default, replaces a retry policy, alters a database migration, or changes an error code is reported identically to a harmless refactor — "exact changed, boundary stable." Consumers have no signal that behavior affecting them has changed.
-
-## Solution: `behavior` fingerprint
-
-A fourth fingerprint tier — `behavior` — that hashes a user-declared set of files representing the component's **behavioral contract**: everything that affects observable behavior for consumers, beyond just the API surface shape.
-
-### Containment hierarchy
-
-```
-exact ⊇ behavior ⊇ boundary
-```
-
-- Every change that affects `boundary` also affects `behavior` and `exact`.
-- A change that affects `behavior` but not `boundary` is a **behavioral contract change with stable API shape** — the signal this tier provides.
-- A change that affects only `exact` is a pure internal refactor.
-
-### Config
-
-```json
-{
-  "components": {
-    "billing-service": {
-      "path": "services/billing",
-      "boundary": {
-        "provider": "openapi",
-        "paths": ["openapi.yaml"]
-      },
-      "behavior": {
-        "paths": [
-          "openapi.yaml",
-          "config/defaults.json",
-          "migrations/",
-          "tests/contract/"
-        ]
-      }
-    }
-  }
-}
-```
-
-`behavior.paths` follows the same rules as `boundary.paths`:
-- Relative to the component path.
-- Supports glob patterns.
-- Files are sorted, CRLF-normalized, and hashed identically to boundary paths.
-
-The `behavior.paths` list SHOULD be a superset of `boundary.paths`. If it isn't, a config validation warning is emitted (not an error — users may have reasons).
-
-### Lockfile output
-
-```json
-"fingerprints": {
-  "exact": "a1b2c3...",
-  "behavior": "d4e5f6...",
-  "boundary": "g7h8i9...",
-  "compat": "j0k1l2..."
-}
-```
-
-When `behavior` is not configured for a component, the field is `null`.
-
-### Change classification
-
-| exact | behavior | boundary | compat | Classification |
-|---|---|---|---|---|
-| changed | unchanged | unchanged | unchanged | Pure internal refactor |
-| changed | changed | unchanged | unchanged | **Behavioral contract change** (API shape stable) |
-| changed | changed | changed | unchanged | Boundary shape change |
-| changed | changed | changed | changed | Breaking change |
-
-### Slice support
-
-Slices gain a new mode: `"behavior"`.
-
-```json
-"slices": {
-  "billing-contract": {
-    "mode": "behavior",
-    "components": ["billing-service"]
-  }
-}
-```
-
-### What `behavior` paths should include
-
-Guidance for users:
-
-- **Always include boundary paths** — behavior is a superset of surface.
-- **Config/defaults files** — `config/defaults.json`, `.env.example`, feature flag definitions.
-- **Database migrations** — `migrations/`, `alembic/versions/`.
-- **Contract test fixtures** — `tests/contract/`, `tests/fixtures/responses/`.
-- **Wire format examples** — sample request/response files used as golden tests.
-- **Error code definitions** — error catalogs, status code mappings.
-
-### What `behavior` paths should NOT include
-
-- Implementation files (use `exact` for that).
-- Test files that test internals, not contracts.
-- Documentation (use `boundary` for doc-linked API files).
-
-## Limitations
-
-The `behavior` tier reduces the gap but does not eliminate it. It detects behavioral changes **only if the change touches a file the user declared in `behavior.paths`**.
-
-Changes that are invisible to all four tiers:
-
-| Change type | Why invisible |
-|---|---|
-| Transitive dependency behavior change | The component's files are unchanged. Boundver does not model a dependency graph. |
-| Environment/infrastructure change | External to the repository. |
-| Build toolchain change | Boundver tracks source, not artifacts. |
-| Behavioral change in an undeclared file | The user didn't include it in `behavior.paths`. |
-
-These are **conscious scope boundaries**, not bugs. Boundver provides declared-file-based change classification. It does not (and should not) attempt to understand runtime semantics.
-
-For teams that need runtime behavioral verification, see the custom provider approach below.
-
-## Extension: test-output fingerprinting via custom provider
-
-For teams that want to detect behavioral changes that no static file analysis can catch, a custom provider can hash the output of a deterministic test suite:
-
-```json
-{
-  "providers": [
-    { "module": "my_providers", "class": "TestOutputProvider" }
-  ],
-  "components": {
-    "billing-service": {
-      "boundary": {
-        "provider": "custom.test-output",
-        "paths": [],
-        "options": {
-          "command": "pytest tests/contract/ --snapshot-update && cat tests/contract/snapshots/*.json",
-          "timeout": 30
-        }
-      }
-    }
-  }
-}
-```
-
-The custom provider would:
-1. Execute the declared command in a subprocess.
-2. Capture stdout.
-3. Return the output as a single `ResolvedBoundary` entry for hashing.
-
-This crosses from "static file analysis" into "requires running code," which is why it's a custom provider rather than a built-in. The core stays fast and side-effect-free; teams that need runtime verification opt in explicitly.
-
-### Provider implementation sketch
-
-```python
-class TestOutputProvider:
-    name = "custom.test-output"
-
-    def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
-        command = ctx.boundary_cfg.get("options", {}).get("command")
-        timeout = ctx.boundary_cfg.get("options", {}).get("timeout", 30)
-        if not command:
-            return ResolvedBoundary(status="error", errors=["No command specified"])
-        try:
-            result = subprocess.run(
-                command, shell=True, capture_output=True, timeout=timeout,
-                cwd=str(ctx.repo_root / ctx.component_path),
-            )
-        except subprocess.TimeoutExpired:
-            return ResolvedBoundary(status="error", errors=["Command timed out"])
-        if result.returncode != 0:
-            return ResolvedBoundary(
-                status="error",
-                errors=[f"Command failed (exit {result.returncode}): {result.stderr.decode()[:200]}"],
-            )
-        return ResolvedBoundary(
-            entries=[("test-output:stdout", result.stdout)],
-            status="ok",
-        )
-
-    def validate_config(self, boundary_cfg, component_path, repo_root):
-        if not boundary_cfg.get("options", {}).get("command"):
-            return ["custom.test-output requires options.command"]
-        return []
-
-    def explain_diff(self, old_metadata, new_metadata, ctx):
-        return "test output changed — behavioral contract may have changed"
-```
-
-**Security note:** This provider executes arbitrary commands. It requires `--allow-custom-providers` and the `custom.` name prefix, same as any custom provider. It should never be enabled in untrusted contexts.
-
-## Implementation plan
-
-1. Add `behavior` to config schema (`boundary.config.schema.json`).
-2. Add `behavior` to lockfile schema (`spec/boundary.lock.schema.json`).
-3. Update `_lockfile.py:generate_lockfile()` to compute behavior digest using the same `PathHashProvider` mechanism.
-4. Update `_diff.py:_summarize_change()` to recognize the new tier.
-5. Update `verify_lockfile()` to check behavior fingerprint.
-6. Add `"behavior"` as a valid slice mode.
-7. Update `_output.py:why_component()` to report behavior drift.
-8. Add tests.
-9. Update spec.md.
diff --git a/docs/design/README.md b/docs/design/README.md
deleted file mode 100644
index 6edd2c4..0000000
--- a/docs/design/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Design Docs Index
-
-This folder contains one design document per active workstream:
-
-1. `01-correctness-portability.md`
-2. `02-testing-strategy.md`
-3. `03-ci-quality-gates.md`
-4. `04-runtime-version-support.md` (includes Python 3.13 and 3.14 planning)
-5. `05-custom-boundary-extension.md` (how to extend with custom boundaries)
-6. `06-config-schema-validation.md`
-7. `07-provider-architecture.md` (real provider protocol: resolve/validate_config/explain_diff, registry, migration plan)
-8. `08-behavior-tier.md` (fourth fingerprint tier for behavioral contract changes, limitations, test-output provider)
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 45a6756..90df963 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,166 +1,146 @@
-# Getting Started with boundver
+# Getting started with boundver
 
-This guide walks you from zero to a committed lockfile and a passing CI check in one sitting.
+This guide takes a Git repository from no configuration to a reviewed lockfile and a useful pull-request gate.
 
 ## Prerequisites
 
-- Python 3.8+
-- Git (any recent version)
-- A repository with at least one component directory
+- Python 3.9 or newer
+- Git
+- At least one tracked component or manifest
 
-No other dependencies are required.
+Run every command below from the repository root.
 
 ## 1. Install
 
 ```bash
-pip install boundver
+python -m pip install boundver
+boundver --version
 ```
 
-Verify the install:
+Optional extras add a full JSON Schema validator and robust YAML parsing:
 
 ```bash
-boundver --help
+python -m pip install "boundver[schema,yaml]"
 ```
 
-Optional extras for enhanced validation:
+## 2. Discover components
 
-```bash
-pip install "boundver[schema]"   # jsonschema — stricter config validation
-pip install "boundver[yaml]"     # PyYAML — robust YAML version extraction
-```
-
-## 2. Create your config
-
-### Option A — Auto-discover (recommended for new adopters)
+For an existing repository, start with tracked manifests:
 
 ```bash
+boundver discover
 boundver init --discover
 ```
 
-boundver scans for `package.json`, `pyproject.toml`, `Cargo.toml`, and `go.mod` and creates a starter `boundary.config.json` with one component per discovered manifest. Review and adjust the output before committing.
+Discovery uses Git instead of crawling ignored dependency trees. It recognizes common Python, JavaScript/TypeScript, Rust, and Go manifests. Review the generated `boundary.config.json`; discovery cannot decide which files form your public contract.
 
-### Option B — Interactive scaffold
+If discovery finds nothing useful, create a minimal scaffold:
 
 ```bash
 boundver init
 ```
 
-Creates a minimal config with a placeholder `example-component`. Edit it to match your repo.
+`init` is non-interactive. Edit the placeholder component before continuing.
 
-### Option C — Write it yourself
+## 3. Declare the contract and its consumers
 
-Create `boundary.config.json` at the repository root:
+Here is a useful starting configuration:
 
 ```json
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/boundary.config.schema.json",
-  "project": "my-project",
+  "project": "checkout-platform",
   "defaults": {
-    "compat_mode": "major"
+    "compat_mode": "major",
+    "verify_facets": ["boundary", "compat"]
   },
   "components": {
-    "auth-service": {
-      "path": "services/auth",
-      "version_source": { "file": "package.json", "field": "version" },
+    "payment-api": {
+      "path": "services/payment",
+      "version_source": {"file": "package.json", "field": "version"},
       "boundary": {
         "provider": "openapi",
-        "paths": ["openapi.yaml"]
+        "paths": ["openapi/*.yaml", "*.service-definition.json"]
       },
       "behavior": {
-        "paths": ["openapi.yaml", "config/*.json"]
-      }
+        "paths": ["openapi/*.yaml", "*.service-definition.json", "config/*.json"]
+      },
+      "consumers": ["checkout-web", "admin-portal"]
     }
   },
   "slices": {
-    "auth-api": {
-      "description": "Auth service public API contract",
+    "checkout-contracts": {
+      "description": "Contracts used by checkout",
       "mode": "boundary",
-      "components": ["auth-service"]
+      "components": ["payment-api"]
     }
   }
 }
 ```
 
-### Adding behavior tracking
+Component `path` values are relative to the repository root. Boundary and behavior paths are relative to the component; they may be literal files or glob patterns. `**` matches recursively. A pattern that matches nothing stops generation instead of silently hashing an empty contract.
 
-The `behavior` key declares files whose content affects your component's observable behavior — configuration, feature flags, routing rules, middleware, etc. It should be a **superset** of `boundary.paths`:
+The four facets have different jobs:
 
-```json
-"behavior": {
-  "paths": ["openapi.yaml", "config/*.json", "middleware.py"]
-}
-```
+| Facet | Tracks | Typical policy |
+|---|---|---|
+| `exact` | All tracked component content | Observe or gate release hygiene |
+| `behavior` | Declared behavior-relevant artifacts | Gate runtime-contract-sensitive systems |
+| `boundary` | Declared public contract artifacts | Gate consumer-facing changes |
+| `compat` | The configured version family | Gate coordinated breaking changes |
 
-When behavior paths change but boundary paths don't, boundver classifies it as a behavioral change — the API shape is stable but runtime behavior shifted. This gives reviewers a clear signal to check for regressions without triggering a full breaking-change workflow.
+`behavior.paths` should normally be a superset of `boundary.paths`. `consumers` declares direct downstream systems. When a producer's boundary or compatibility facet changes, boundver names those consumers in the verification result.
 
-## 3. Validate the config
+`defaults.verify_facets` controls what fails a plain `boundver verify`. Starting with `boundary` and `compat` prevents internal refactors from making the check noisy. A command-line `--facets` value overrides the default.
 
-Before generating anything, confirm the config is valid:
+## 4. Validate before hashing
 
 ```bash
 boundver validate-config
 ```
 
-A clean run prints `Config is valid.` If there are errors, they describe exactly what to fix — missing fields, unknown providers, path traversal, etc.
-
-## 4. Generate the lockfile
+Fix every reported error. Validation checks the schema, component roots, providers, unsafe paths, slices, consumers, and source declarations.
 
-```bash
-boundver generate --source working-tree
-```
+## 5. Generate a local baseline
 
-This creates `boundary.lock.json` next to your config. Commit both files.
-
-> **Note:** In CI you'll typically use `--source head` (the default) to hash committed content. `--source working-tree` is convenient locally when files aren't committed yet.
-
-### Inspect the lockfile
+Use `working-tree` for both local generation and local verification:
 
 ```bash
+boundver generate --source working-tree
 boundver status
+boundver verify --source working-tree --facets boundary,compat
 ```
 
-Sample output:
+Working-tree mode reads on-disk content but only for files known to Git. If you added a component or contract file, stage it before generating:
 
+```bash
+git add services/payment/openapi/new-route.yaml
+boundver generate --source working-tree
 ```
-  Project: my-project
-  Components: 1
-  Slices: 1
-
-  Versioned: 1  |  Unversioned: 0
 
-  Boundary coverage:
-    openapi: 1
+Inspect the generated `boundary.lock.json`; it should contain non-null exact and declared boundary fingerprints. Generation fails if a required digest cannot be computed.
 
-  Boundary extraction status:
-    ok: 1
-
-  Slices:
-    auth-api [boundary] (1 components) = a3f9b12c4e1d...
-```
-
-## 5. Verify the lockfile
+## 6. Commit the baseline
 
 ```bash
-boundver verify
+git add boundary.config.json boundary.lock.json
+git commit -m "chore: add boundver contract baseline"
 ```
 
-`Lockfile is up to date.` means the current repo state matches what was recorded. If something drifted, you'll see which component and which fingerprint facet (`exact`, `behavior`, `boundary`, or `compat`) changed.
-
-## 6. Commit and push
+After the commit, a source-consistent HEAD check should pass:
 
 ```bash
-git add boundary.config.json boundary.lock.json
-git commit -m "feat: add boundver config and initial lockfile"
-git push
+boundver verify --source head --facets boundary,compat
 ```
 
-## 7. Add a CI check
+Do not compare a lock generated from uncommitted working-tree content against `head`; the snapshots intentionally differ.
+
+## 7. Add the pull-request gate
 
-Add a step to your PR pipeline that rejects stale lockfiles:
+Create `.github/workflows/boundary-check.yml`:
 
 ```yaml
-# .github/workflows/boundary-check.yml
-name: Boundary check
+name: Contract boundary
 on: [pull_request]
 
 jobs:
@@ -170,23 +150,66 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
+      - uses: yzm1/boundver@v0
         with:
-          python-version: '3.11'
-      - run: pip install boundver
-      - run: boundver verify
-      - name: Show what changed (on failure)
-        if: failure()
-        run: |
-          boundver generate --out boundary.lock.new.json
-          boundver diff boundary.lock.json boundary.lock.new.json
+          config: boundary.config.json
+          lock: boundary.lock.json
+          source: head
+          facets: boundary,compat
+```
+
+`head` is correct here because both the source and lockfile are committed in the pull request. The selected gate passes for an internal-only refactor and fails when a declared boundary or compatibility family drifts.
+
+## Daily workflow
+
+First inspect a local change against the matching snapshot:
+
+```bash
+boundver verify --source working-tree --facets boundary,compat
+boundver why payment-api --source working-tree
+```
+
+If the gated change is intentional, review its consumer impact and update in one step:
+
+```bash
+boundver verify --source working-tree --facets boundary,compat --update
+git diff -- boundary.lock.json
+```
+
+To refresh exact and behavior observations even when they are not part of your normal gate, explicitly include all facets:
+
+```bash
+boundver verify \
+  --source working-tree \
+  --facets exact,behavior,boundary,compat \
+  --update
 ```
 
-The CI check fails if a PR changes a component without regenerating the lockfile. The diff step shows exactly which fingerprints changed and why.
+Commit the source change and updated lockfile together. After committing, verify them together with `--source head`.
+
+## Understand exit codes
+
+The highest-severity selected drift determines the process status:
+
+| Code | Meaning |
+|---:|---|
+| `0` | Selected facets match |
+| `1` | Exact or metadata drift |
+| `2` | Usage or configuration error |
+| `3` | Behavior drift |
+| `4` | Boundary drift |
+| `5` | Compatibility drift |
+
+This lets CI warn or fail differently without parsing human-readable output. `--format json` also returns structured issues, non-gating observations, selected facets, and update status.
+
+## Important limitation
+
+boundver proves that the declared files produced the same fingerprints. It does not prove semantic compatibility, exercise consumers, or replace contract tests. The canonical JSON and OpenAPI providers reduce formatting and documentation noise, but you still decide which artifacts represent the real boundary and which consumer checks to run when it moves.
 
 ## Next steps
 
-- **Add more components.** See the [config reference](../README.md#config-reference) for all options.
-- **Use slice fingerprints as cache keys.** See [CI cookbook](ci-cookbook.md).
-- **Adopt incrementally.** See [Gradual adoption guide](gradual-adoption.md).
-- **Use `implicit` provider first** if you don't have explicit API boundary files yet — you'll get `exact` fingerprinting right away and can upgrade providers later.
+- Choose a provider in the [provider guide](public-vs-custom-providers.md).
+- Add components gradually with the [adoption guide](gradual-adoption.md).
+- Copy a pipeline pattern from the [CI cookbook](ci-cookbook.md).
+- Explore runnable configurations in the [examples index](../examples/README.md).
+- Resolve concurrent updates with the [lockfile merge strategy](LOCKFILE_MERGE.md).
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..5274e0f
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,31 @@
+# boundver examples
+
+These small repositories-in-a-repository demonstrate each built-in boundary style. Run every command from the **boundver repository root** so component paths resolve consistently.
+
+Install the CLI first:
+
+```bash
+python -m pip install boundver
+```
+
+| Example | What it demonstrates |
+|---|---|
+| [Behavior tier](behavior/) | Separate runtime-behavior and API-boundary fingerprints |
+| [OpenAPI](openapi/) | A raw OpenAPI artifact as a service boundary |
+| [JSON file](json-file/) | A generic JSON contract |
+| [Python package](python-package/) | Public Python exports |
+| [TypeScript package](typescript-package/) | A TypeScript export barrel |
+| [Implicit and leaf](implicit-and-leaf/) | Gradual adoption and components with no consumers |
+
+Each example contains a config, sample component files, and `expected.boundary.lock.json`. Its README uses the same source mode for generation and verification:
+
+```bash
+boundver generate --config examples/EXAMPLE/boundary.config.json \
+  --out examples/EXAMPLE/expected.boundary.lock.json \
+  --source working-tree
+boundver verify --config examples/EXAMPLE/boundary.config.json \
+  --lock examples/EXAMPLE/expected.boundary.lock.json \
+  --source working-tree
+```
+
+The examples show declared-artifact drift, not proof of semantic compatibility. Edit a tracked example file, rerun `verify`, and inspect which facet changes; regenerate afterward to restore the expected lockfile.
diff --git a/examples/behavior/README.md b/examples/behavior/README.md
index df8ca66..babf1d6 100644
--- a/examples/behavior/README.md
+++ b/examples/behavior/README.md
@@ -1,35 +1,39 @@
 # Behavior tier example
 
-Demonstrates the behavior fingerprint — a broader contract hash that covers configuration and runtime-relevant files in addition to the API boundary.
+This example separates a service's observable behavior from its narrower API boundary.
 
 ## Files
 
-- `boundary.config.json` — declares both `boundary` (OpenAPI spec) and `behavior` (spec + config)
-- `service/openapi.yaml` — API boundary file
-- `service/config.json` — behavioral config (retry policy, rate limits, feature flags)
-- `service/version.json` — version source
-- `expected.boundary.lock.json` — generated lockfile with all four fingerprints
+- `boundary.config.json` declares the component and two slices.
+- `service/openapi.yaml` belongs to both the behavior and boundary facets.
+- `service/config.json` belongs only to the behavior facet.
+- `service/version.json` supplies the compatibility version.
+- `expected.boundary.lock.json` records the expected fingerprints.
 
-## Key concepts
+## Expected classifications
 
-The `behavior.paths` list is a **superset** of `boundary.paths`. This gives three useful change classifications:
+| Change | Facets that drift |
+|---|---|
+| Internal tracked file | `exact` |
+| `service/config.json` | `exact`, `behavior` |
+| `service/openapi.yaml` | `exact`, `behavior`, `boundary` |
+| Major version in `service/version.json` | `exact`, `compat` |
 
-| What changed | Fingerprint drift | Classification |
-|---|---|---|
-| Internal implementation only | `exact` | Refactor / internal |
-| `config.json` (behavior file, not boundary) | `exact` + `behavior` | Behavioral contract changed (API shape stable) |
-| `openapi.yaml` (both boundary and behavior) | `exact` + `behavior` + `boundary` | API contract changed |
+The `payment-boundary` slice follows API shape; `payment-behavior` follows the broader observable contract.
 
-## Slices
+## Generate and verify
 
-- `payment-boundary` — tracks API shape only (mode `boundary`)
-- `payment-behavior` — tracks observable behavior (mode `behavior`)
-
-## Re-generate expected lockfile
+Install `boundver`, then run from the **boundver repository root**:
 
 ```bash
-PYTHONPATH=src python -m boundver.core generate \
+boundver generate \
   --config examples/behavior/boundary.config.json \
   --out examples/behavior/expected.boundary.lock.json \
   --source working-tree
+boundver verify \
+  --config examples/behavior/boundary.config.json \
+  --lock examples/behavior/expected.boundary.lock.json \
+  --source working-tree
 ```
+
+These fingerprints detect changes in the declared files; they do not prove runtime compatibility.
diff --git a/examples/behavior/expected.boundary.lock.json b/examples/behavior/expected.boundary.lock.json
index 9f84260..165b7e5 100644
--- a/examples/behavior/expected.boundary.lock.json
+++ b/examples/behavior/expected.boundary.lock.json
@@ -1,17 +1,19 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "example-behavior",
   "components": {
     "payment-svc": {
       "version": "2.1.0",
       "path": "examples/behavior/service",
       "boundary_provider": "openapi",
+      "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "8ec50d3ee3220130fe624a51e69e50b5a91d7d3e9ae7d7ec5af0a7531c7fcbe6",
-        "behavior": "088402eb53f284046ec8116988673f0e68c67ea8338a40ed65b3a13d824fd401",
-        "boundary": "6f10dcca6f288ecc437f05ec3482891eb8103c54ba5301e138a5701778817900",
+        "exact": "594d9c612e92e5bf3a27fc0a22c8ef57269b20892055d71b836dfa807211260b",
+        "behavior": "012d972cc8ff71a38a53a3c7c4c5f58457bbf9b3e2cea108f5a1bcf7f5007e20",
+        "boundary": "8dd1227ff4b1976de354c54be9528271d18f448d2f34f8adb079d70114fe6d03",
         "compat": "85e5cd77fa1a3e08ce7e859a1326c924c6b43db9d3dfdda278f92c3d33fa43a0"
       },
       "semver": {
@@ -28,9 +30,9 @@
       "components": [
         "payment-svc"
       ],
-      "fingerprint": "50bb9a59b2d41c1f3dbbd976189fea30aebb7461240b527fd211aa0e93f28aa0",
+      "fingerprint": "c90def6f626c94609b92f3282897f2b6a406e0d56b9f4e836234dadb9e917caf",
       "component_digests": {
-        "payment-svc": "6f10dcca6f288ecc437f05ec3482891eb8103c54ba5301e138a5701778817900"
+        "payment-svc": "8dd1227ff4b1976de354c54be9528271d18f448d2f34f8adb079d70114fe6d03"
       }
     },
     "payment-behavior": {
@@ -39,9 +41,9 @@
       "components": [
         "payment-svc"
       ],
-      "fingerprint": "7aa0f63f1ba5b3ac13c1109663ae1f3a1d88e24cb7362d27b7dd420e0615d0d0",
+      "fingerprint": "ef542653a39c823b4b261962b5bd5f7723a689098830bae019fb922f642addec",
       "component_digests": {
-        "payment-svc": "088402eb53f284046ec8116988673f0e68c67ea8338a40ed65b3a13d824fd401"
+        "payment-svc": "012d972cc8ff71a38a53a3c7c4c5f58457bbf9b3e2cea108f5a1bcf7f5007e20"
       }
     }
   }
diff --git a/examples/implicit-and-leaf/README.md b/examples/implicit-and-leaf/README.md
index 48c2ad7..2b013c2 100644
--- a/examples/implicit-and-leaf/README.md
+++ b/examples/implicit-and-leaf/README.md
@@ -1,17 +1,25 @@
-# Implicit and leaf example
+# Implicit and leaf boundaries
 
-## Files
-- `boundary.config.json`
-- `worker/main.py` (`implicit` boundary)
-- `leafsvc/main.py` (`leaf` boundary)
-- `expected.boundary.lock.json`
+This example contrasts two intentionally lightweight providers:
 
-## Re-generate expected lockfile
+- `worker` uses `implicit`, which records exact content while its boundary remains undeclared and reports partial boundary coverage.
+- `leafsvc` uses `leaf`, meaning the component has no downstream contract to fingerprint.
+
+Both are useful during gradual adoption, but neither provides an API compatibility guarantee.
+
+## Generate and verify
+
+Install `boundver`, then run from the **boundver repository root**:
 
 ```bash
-PYTHONPATH=src python -m boundver.core generate \
+boundver generate \
   --config examples/implicit-and-leaf/boundary.config.json \
   --out examples/implicit-and-leaf/expected.boundary.lock.json \
-  --source working-tree \
-
+  --source working-tree
+boundver verify \
+  --config examples/implicit-and-leaf/boundary.config.json \
+  --lock examples/implicit-and-leaf/expected.boundary.lock.json \
+  --source working-tree
 ```
+
+Use `boundver status --lock examples/implicit-and-leaf/expected.boundary.lock.json` to see the provider coverage states.
diff --git a/examples/implicit-and-leaf/expected.boundary.lock.json b/examples/implicit-and-leaf/expected.boundary.lock.json
index b64ca18..e078421 100644
--- a/examples/implicit-and-leaf/expected.boundary.lock.json
+++ b/examples/implicit-and-leaf/expected.boundary.lock.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "example-implicit-leaf",
   "components": {
     "worker": {
@@ -9,8 +9,9 @@
       "boundary_provider": "implicit",
       "boundary_provider_version": "1",
       "boundary_status": "partial",
+      "consumers": [],
       "fingerprints": {
-        "exact": "4ead1526ad5ee4087940e33712e6006cea6967a13ec58060041bf95e3383aeca",
+        "exact": "e5787fbcf50fc81bcfe35f09dd08e3fc9148403fa7a9c9a7ebfbb72d95812a61",
         "behavior": null,
         "boundary": null,
         "compat": null
@@ -30,8 +31,9 @@
       "boundary_provider": "leaf",
       "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "3c3a7b65bc88a63285a90cf5c612b589cc5c0d1327023a40daeb1ff8783f4fa5",
+        "exact": "87c0393e4c11fdd0b4f8070f3f2088a1f62c67e0c8b592a3045307d99a72ccf7",
         "behavior": null,
         "boundary": null,
         "compat": null
@@ -50,9 +52,9 @@
       "components": [
         "worker"
       ],
-      "fingerprint": "c6eef65d8d3d69e4d2ac0fae54e949a13ad88793ca0bb6f9b6083d557928cdc7",
+      "fingerprint": "bf87bd0a4be3b4479228ebfeae0014040db7db60f429e87e0dd64b5d4260a845",
       "component_digests": {
-        "worker": "4ead1526ad5ee4087940e33712e6006cea6967a13ec58060041bf95e3383aeca"
+        "worker": "e5787fbcf50fc81bcfe35f09dd08e3fc9148403fa7a9c9a7ebfbb72d95812a61"
       }
     },
     "leaf-exact": {
@@ -61,9 +63,9 @@
       "components": [
         "leafsvc"
       ],
-      "fingerprint": "48eac8ad3f0355cb4dda4a6225eb1d7919342231c1d188504d23bede7e218d29",
+      "fingerprint": "dee3ec0c6ed4cee820be76f1b052fc8e4f6308c76a4f688a5334c30c53a41d7b",
       "component_digests": {
-        "leafsvc": "3c3a7b65bc88a63285a90cf5c612b589cc5c0d1327023a40daeb1ff8783f4fa5"
+        "leafsvc": "87c0393e4c11fdd0b4f8070f3f2088a1f62c67e0c8b592a3045307d99a72ccf7"
       }
     }
   }
diff --git a/examples/json-file/README.md b/examples/json-file/README.md
index 6ac8b3d..4082723 100644
--- a/examples/json-file/README.md
+++ b/examples/json-file/README.md
@@ -1,16 +1,26 @@
-# JSON file boundary example
+# JSON file boundary
+
+This example treats `service/boundary.json` as the declared contract for `svc`. The raw `json-file` provider detects content and formatting changes; choose `json-canonical` when formatting-insensitive structural hashing is more appropriate.
 
 ## Files
-- `boundary.config.json`
-- `service/boundary.json`
-- `expected.boundary.lock.json`
 
-## Re-generate expected lockfile
+- `boundary.config.json` declares the `svc` component.
+- `service/boundary.json` is the boundary artifact.
+- `expected.boundary.lock.json` records the expected fingerprints.
+
+## Generate and verify
+
+Install `boundver`, then run from the **boundver repository root**:
 
 ```bash
-PYTHONPATH=src python -m boundver.core generate \
+boundver generate \
   --config examples/json-file/boundary.config.json \
   --out examples/json-file/expected.boundary.lock.json \
-  --source working-tree \
-
+  --source working-tree
+boundver verify \
+  --config examples/json-file/boundary.config.json \
+  --lock examples/json-file/expected.boundary.lock.json \
+  --source working-tree
 ```
+
+A stable digest means the declared artifact is stable; it is not a semantic compatibility proof.
diff --git a/examples/json-file/expected.boundary.lock.json b/examples/json-file/expected.boundary.lock.json
index 55bd486..b50b299 100644
--- a/examples/json-file/expected.boundary.lock.json
+++ b/examples/json-file/expected.boundary.lock.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "example-json-file",
   "components": {
     "svc": {
@@ -9,10 +9,11 @@
       "boundary_provider": "json-file",
       "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "2c3a31b2ddfa54b401cf05ba846a17d47a082e48663a725eeba7f7dcd0a7696e",
+        "exact": "ec5cd447b2a435e1dd27481d14b7a7496565e7aeab26f09b698dab2d5eb0b70f",
         "behavior": null,
-        "boundary": "8a9ce9465d4da4c97b1fa3d6d51fc8f078917990a71c6219829937085c498ba7",
+        "boundary": "22de2604a7c75b4c97b2f49105f7660e06a16f3e2888552c865f429ccb3526b0",
         "compat": null
       },
       "semver": {
@@ -29,9 +30,9 @@
       "components": [
         "svc"
       ],
-      "fingerprint": "6af6618ae0fffae3b4f4e9d39aade95009548d8a1234d918abfb905262c8e5b0",
+      "fingerprint": "29a9b50e7814f9ab3e737af63812f58e15a12b5d482972f03f5d97311ad279fa",
       "component_digests": {
-        "svc": "8a9ce9465d4da4c97b1fa3d6d51fc8f078917990a71c6219829937085c498ba7"
+        "svc": "22de2604a7c75b4c97b2f49105f7660e06a16f3e2888552c865f429ccb3526b0"
       }
     }
   }
diff --git a/examples/openapi/README.md b/examples/openapi/README.md
index f6a9d52..2abddcf 100644
--- a/examples/openapi/README.md
+++ b/examples/openapi/README.md
@@ -1,17 +1,22 @@
-# OpenAPI example
+# OpenAPI boundary
 
-## Files
-- `boundary.config.json`
-- `service/openapi.yaml`
-- `service/version.json`
-- `expected.boundary.lock.json`
+This example uses `service/openapi.yaml` as a service's declared API boundary and `service/version.json` as its compatibility version source.
 
-## Re-generate expected lockfile
+The raw `openapi` provider reports any artifact change. For a structural fingerprint that ignores selected documentation-only fields, use `openapi-canonical` and explicit boundary files.
+
+## Generate and verify
+
+Install `boundver`, then run from the **boundver repository root**:
 
 ```bash
-PYTHONPATH=src python -m boundver.core generate \
+boundver generate \
   --config examples/openapi/boundary.config.json \
   --out examples/openapi/expected.boundary.lock.json \
-  --source working-tree \
-
+  --source working-tree
+boundver verify \
+  --config examples/openapi/boundary.config.json \
+  --lock examples/openapi/expected.boundary.lock.json \
+  --source working-tree
 ```
+
+Edit `service/openapi.yaml` to see exact and boundary drift. A detected structural change tells consumers to re-verify; boundver does not itself prove that a client remains compatible.
diff --git a/examples/openapi/expected.boundary.lock.json b/examples/openapi/expected.boundary.lock.json
index 7cb2ddd..7ca9ad5 100644
--- a/examples/openapi/expected.boundary.lock.json
+++ b/examples/openapi/expected.boundary.lock.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "example-openapi",
   "components": {
     "svc": {
@@ -9,10 +9,11 @@
       "boundary_provider": "openapi",
       "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "7822e6e64efbe27b028201aeb820ed8512fd02f7499c31bac0aba5e84da638d6",
+        "exact": "ff636631455b5223037e8fefe5fbc35b1199a1e6636113ffd87aea13268476a5",
         "behavior": null,
-        "boundary": "c24922524d395fb6cb71f3d96fd39b5c584cc93d058b2a31da943800573c57e9",
+        "boundary": "9c6453b101c59359d5ae830523b2d02e72760acbede505480720153d0793008b",
         "compat": "2b76e797e89bf0561229aa6249cdc899acef599712c928f7824203cbc93d644d"
       },
       "semver": {
@@ -29,9 +30,9 @@
       "components": [
         "svc"
       ],
-      "fingerprint": "9db5c15b34fbdf5a04324a234c6e3ad21ba327be5fc40ab0e1f8ae6d19378a87",
+      "fingerprint": "a249cdf09d2e2743d665182203b814f4ddedf24969a870aad84740ad95d8b12a",
       "component_digests": {
-        "svc": "c24922524d395fb6cb71f3d96fd39b5c584cc93d058b2a31da943800573c57e9"
+        "svc": "9c6453b101c59359d5ae830523b2d02e72760acbede505480720153d0793008b"
       }
     }
   }
diff --git a/examples/python-package/README.md b/examples/python-package/README.md
index 6a145eb..1faa665 100644
--- a/examples/python-package/README.md
+++ b/examples/python-package/README.md
@@ -1,9 +1,22 @@
-# Python package boundary example
+# Python package boundary
+
+This example models `pkg/__init__.py` as the public export surface of a Python package. Its component version comes from `pkg/version.json`; discovery examples for standard manifests are covered in the getting-started guide.
+
+The `python-exports` provider fingerprints the declared export file as an artifact. It does not import the package or infer semantic compatibility.
+
+## Generate and verify
+
+Install `boundver`, then run from the **boundver repository root**:
 
 ```bash
-PYTHONPATH=src python -m boundver.core generate \
+boundver generate \
   --config examples/python-package/boundary.config.json \
   --out examples/python-package/expected.boundary.lock.json \
-  --source working-tree \
-
+  --source working-tree
+boundver verify \
+  --config examples/python-package/boundary.config.json \
+  --lock examples/python-package/expected.boundary.lock.json \
+  --source working-tree
 ```
+
+Adding or removing a declared export changes the boundary fingerprint; a major version change also changes the compatibility facet.
diff --git a/examples/python-package/boundary.config.json b/examples/python-package/boundary.config.json
index 214e76a..993deae 100644
--- a/examples/python-package/boundary.config.json
+++ b/examples/python-package/boundary.config.json
@@ -4,7 +4,7 @@
   "components": {
     "pkg": {
       "path": "examples/python-package/pkg",
-      "version_source": {"file": "../pyproject.toml", "field": "project.version"},
+      "version_source": {"file": "version.json", "field": "version"},
       "boundary": {"provider": "python-exports", "paths": ["__init__.py"]}
     }
   },
diff --git a/examples/python-package/expected.boundary.lock.json b/examples/python-package/expected.boundary.lock.json
index 7f99e52..1ea2c71 100644
--- a/examples/python-package/expected.boundary.lock.json
+++ b/examples/python-package/expected.boundary.lock.json
@@ -1,24 +1,25 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "example-python-package",
   "components": {
     "pkg": {
-      "version": null,
+      "version": "1.4.0",
       "path": "examples/python-package/pkg",
       "boundary_provider": "python-exports",
       "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "39a16012010725841bd6db8c056a6dd4018fac6b63706b5023796b367001e01e",
+        "exact": "157c507dfc4f54694dbc2327f49775b561e30caf691816490392adf45c147258",
         "behavior": null,
-        "boundary": "06954c1b4c8d497fa14cef9f6d68ab5b90355a91a8b0191106958f6b4981a501",
-        "compat": null
+        "boundary": "f293c0c0eddf96fbf973617c8b22c320e7f11bef04194d45ffc3639625f528d7",
+        "compat": "25a26a7d0679ba49343fd94ad6d43f57fb09ca144c2c5bf614185e2e4a10ebe9"
       },
       "semver": {
-        "compat_family": null,
-        "api_surface": null,
-        "exact_version": null
+        "compat_family": "1",
+        "api_surface": "1.4",
+        "exact_version": "1.4.0"
       }
     }
   },
@@ -29,9 +30,9 @@
       "components": [
         "pkg"
       ],
-      "fingerprint": "5e0b43e709e7e12df4bb991437c617c1041fa6311207134665a5e7800e8b779e",
+      "fingerprint": "2593c5002b532eb246852dba4ed649390d4dc7c3ccca730d32dcf2a9f55b0083",
       "component_digests": {
-        "pkg": "06954c1b4c8d497fa14cef9f6d68ab5b90355a91a8b0191106958f6b4981a501"
+        "pkg": "f293c0c0eddf96fbf973617c8b22c320e7f11bef04194d45ffc3639625f528d7"
       }
     }
   }
diff --git a/examples/python-package/pkg/version.json b/examples/python-package/pkg/version.json
new file mode 100644
index 0000000..d19a958
--- /dev/null
+++ b/examples/python-package/pkg/version.json
@@ -0,0 +1,3 @@
+{
+  "version": "1.4.0"
+}
diff --git a/examples/typescript-package/README.md b/examples/typescript-package/README.md
index a8d9421..cbeb0b4 100644
--- a/examples/typescript-package/README.md
+++ b/examples/typescript-package/README.md
@@ -1,9 +1,22 @@
-# TypeScript package boundary example
+# TypeScript package boundary
+
+This example treats `src/index.ts` as a TypeScript package's public export barrel. Its component version comes from `src/version.json`; discovery still recognizes the package's root `package.json`.
+
+The `typescript-exports` provider fingerprints the declared artifact. It complements rather than replaces TypeScript compilation or consumer tests.
+
+## Generate and verify
+
+Install `boundver`, then run from the **boundver repository root**:
 
 ```bash
-PYTHONPATH=src python -m boundver.core generate \
+boundver generate \
   --config examples/typescript-package/boundary.config.json \
   --out examples/typescript-package/expected.boundary.lock.json \
-  --source working-tree \
-
+  --source working-tree
+boundver verify \
+  --config examples/typescript-package/boundary.config.json \
+  --lock examples/typescript-package/expected.boundary.lock.json \
+  --source working-tree
 ```
+
+Edit `src/index.ts` to see exact and boundary drift, then regenerate the expected lockfile after reviewing the change.
diff --git a/examples/typescript-package/boundary.config.json b/examples/typescript-package/boundary.config.json
index afa2f9e..7550ace 100644
--- a/examples/typescript-package/boundary.config.json
+++ b/examples/typescript-package/boundary.config.json
@@ -4,7 +4,7 @@
   "components": {
     "pkg": {
       "path": "examples/typescript-package/src",
-      "version_source": {"file": "../package.json", "field": "version"},
+      "version_source": {"file": "version.json", "field": "version"},
       "boundary": {"provider": "typescript-exports", "paths": ["index.ts"]}
     }
   },
diff --git a/examples/typescript-package/expected.boundary.lock.json b/examples/typescript-package/expected.boundary.lock.json
index e08f945..8ec6bbf 100644
--- a/examples/typescript-package/expected.boundary.lock.json
+++ b/examples/typescript-package/expected.boundary.lock.json
@@ -1,24 +1,25 @@
 {
   "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json",
-  "schema": "boundary-lock/v1",
+  "schema": "boundary-lock/v2",
   "project": "example-typescript-package",
   "components": {
     "pkg": {
-      "version": null,
+      "version": "2.1.0",
       "path": "examples/typescript-package/src",
       "boundary_provider": "typescript-exports",
       "boundary_provider_version": "1",
       "boundary_status": "ok",
+      "consumers": [],
       "fingerprints": {
-        "exact": "bad956d7f9651d1acb1d6898c7c2894ea93a3bbbd47fd5e214ad9407d92ee6a7",
+        "exact": "301f6b4f605e7b1777f7198461d0a5ae4a36aa680fee87a78bec55d7f82370be",
         "behavior": null,
-        "boundary": "b79d90df58aa3f22203444e990efe416f3836d5d677c3d98b89fd4e3ce2ce38e",
-        "compat": null
+        "boundary": "fc78a4eeeef6d431a74e42bdf96129f1c8701b1ae6b15e1a237115cda8d8cd85",
+        "compat": "e04ddbe80dd1edeab55821dbe157943486507534b7baaeacdeb225347fd10682"
       },
       "semver": {
-        "compat_family": null,
-        "api_surface": null,
-        "exact_version": null
+        "compat_family": "2",
+        "api_surface": "2.1",
+        "exact_version": "2.1.0"
       }
     }
   },
@@ -29,9 +30,9 @@
       "components": [
         "pkg"
       ],
-      "fingerprint": "7d3c0383e354181b2bc3d603f043be903e9fe5ea97c1bbc03f88a601b4d7494c",
+      "fingerprint": "800bb1bb9fd3bab50e2119c9751d3c717a06857d3e4bfac1b6257f38b3863b56",
       "component_digests": {
-        "pkg": "b79d90df58aa3f22203444e990efe416f3836d5d677c3d98b89fd4e3ce2ce38e"
+        "pkg": "fc78a4eeeef6d431a74e42bdf96129f1c8701b1ae6b15e1a237115cda8d8cd85"
       }
     }
   }
diff --git a/examples/typescript-package/src/version.json b/examples/typescript-package/src/version.json
new file mode 100644
index 0000000..87032da
--- /dev/null
+++ b/examples/typescript-package/src/version.json
@@ -0,0 +1,3 @@
+{
+  "version": "2.1.0"
+}
diff --git a/pyproject.toml b/pyproject.toml
index 563bf1e..082aad7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,16 +1,58 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=78.1.1", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "boundver"
-version = "0.9.1"
-description = "Automated change-type classification for components that lack static verification"
+version = "0.10.0"
+description = "Detect API boundary, behavioral contract, and component changes in CI"
 readme = "README.md"
-requires-python = ">=3.8"
-license = { text = "MIT" }
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
 authors = [{ name = "boundver contributors" }]
-dependencies = []
+keywords = [
+  "api-contract",
+  "api-compatibility",
+  "breaking-changes",
+  "change-detection",
+  "ci",
+  "contract-testing",
+  "developer-tools",
+  "git",
+  "lockfile",
+  "monorepo",
+  "openapi",
+  "polyglot",
+  "semantic-versioning",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = ["tomli>=2.0; python_version < '3.11'"]
+
+[project.urls]
+Homepage = "https://github.com/yzm1/boundver"
+Documentation = "https://github.com/yzm1/boundver/tree/main/docs"
+Changelog = "https://github.com/yzm1/boundver/blob/main/CHANGELOG.md"
+Issues = "https://github.com/yzm1/boundver/issues"
+Repository = "https://github.com/yzm1/boundver"
+"GitHub Action" = "https://github.com/marketplace/actions/boundver"
 
 [project.optional-dependencies]
 schema = ["jsonschema>=4"]
@@ -23,5 +65,8 @@ boundver = "boundver.cli:main"
 [tool.setuptools]
 package-dir = {"" = "src"}
 
+[tool.setuptools.package-data]
+boundver = ["py.typed", "boundary.config.schema.json"]
+
 [tool.setuptools.packages.find]
 where = ["src"]
diff --git a/scripts/boundver-merge-driver.sh b/scripts/boundver-merge-driver.sh
deleted file mode 100755
index cf01644..0000000
--- a/scripts/boundver-merge-driver.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Git merge driver interface:
-#   %O = ancestor file, %A = current file (must write result), %B = other file
-# We intentionally ignore file inputs and regenerate canonical lockfile from config.
-
-LOCKFILE_PATH="${1:-boundary.lock.json}"
-CONFIG_PATH="${BOUNDVER_CONFIG:-boundary.config.json}"
-SOURCE_MODE="${BOUNDVER_SOURCE:-head}"
-
-boundver generate \
-  --config "$CONFIG_PATH" \
-  --out "$LOCKFILE_PATH" \
-  --source "$SOURCE_MODE" \
-
-
-exit 0
diff --git a/scripts/boundver-verify.sh b/scripts/boundver-verify.sh
deleted file mode 100755
index 6b10f44..0000000
--- a/scripts/boundver-verify.sh
+++ /dev/null
@@ -1,85 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-CONFIG_PATH="${1:-boundary.config.json}"
-LOCK_PATH="${2:-boundary.lock.json}"
-
-if ! command -v jq >/dev/null 2>&1; then
-  echo "ERROR: jq is required" >&2
-  exit 2
-fi
-if ! command -v sha256sum >/dev/null 2>&1; then
-  echo "ERROR: sha256sum is required" >&2
-  exit 2
-fi
-
-repo_root="$(git rev-parse --show-toplevel)"
-cd "$repo_root"
-
-hash_from_paths() {
-  local -a paths=("$@")
-  if [ ${#paths[@]} -eq 0 ]; then
-    printf ""
-    return 0
-  fi
-  local tmp
-  tmp="$(mktemp)"
-  : > "$tmp"
-  for rel in "${paths[@]}"; do
-    local content
-    content="$(git show "HEAD:${rel}" 2>/dev/null || true)"
-    if [ -z "$content" ] && ! git cat-file -e "HEAD:${rel}" 2>/dev/null; then
-      continue
-    fi
-    printf "file:%s\n" "${rel}" >> "$tmp"
-    git show "HEAD:${rel}" >> "$tmp"
-  done
-  if [ ! -s "$tmp" ]; then
-    rm -f "$tmp"
-    printf ""
-    return 0
-  fi
-  sha256sum "$tmp" | awk '{print $1}'
-  rm -f "$tmp"
-}
-
-status=0
-
-mapfile -t component_names < <(jq -r '.components | keys[]' "$CONFIG_PATH")
-
-for name in "${component_names[@]}"; do
-  comp_path="$(jq -r --arg n "$name" '.components[$n].path' "$CONFIG_PATH")"
-  mapfile -t exact_files < <(git ls-tree -r --name-only HEAD "$comp_path" | sed '/^$/d')
-  exact_hash="$(hash_from_paths "${exact_files[@]}")"
-
-  mapfile -t boundary_rel < <(jq -r --arg n "$name" '.components[$n].boundary.paths[]? // empty' "$CONFIG_PATH")
-  boundary_files=()
-  for rel in "${boundary_rel[@]}"; do
-    joined="${comp_path%/}/${rel}"
-    while IFS= read -r f; do
-      [ -n "$f" ] && boundary_files+=("$f")
-    done < <(git ls-tree -r --name-only HEAD "$joined")
-    if [ ${#boundary_files[@]} -eq 0 ] && git cat-file -e "HEAD:${joined}" 2>/dev/null; then
-      boundary_files+=("$joined")
-    fi
-  done
-  boundary_hash="$(hash_from_paths "${boundary_files[@]}")"
-
-  lock_exact="$(jq -r --arg n "$name" '.components[$n].fingerprints.exact // ""' "$LOCK_PATH")"
-  lock_boundary="$(jq -r --arg n "$name" '.components[$n].fingerprints.boundary // ""' "$LOCK_PATH")"
-
-  if [ "$exact_hash" != "$lock_exact" ]; then
-    echo "MISMATCH ${name}.exact"
-    status=1
-  fi
-  if [ "$boundary_hash" != "$lock_boundary" ]; then
-    echo "MISMATCH ${name}.boundary"
-    status=1
-  fi
-
-done
-
-if [ $status -eq 0 ]; then
-  echo "OK: lockfile matches HEAD for exact/boundary"
-fi
-exit $status
diff --git a/scripts/build_standalone.py b/scripts/build_standalone.py
index ce2647c..ba1a7d6 100644
--- a/scripts/build_standalone.py
+++ b/scripts/build_standalone.py
@@ -6,7 +6,7 @@
     python scripts/build_standalone.py
     python scripts/build_standalone.py --output dist/boundver.pyz
 
-The resulting .pyz file is self-contained (no external deps beyond Python 3.8+
+The resulting .pyz file is self-contained (no external deps beyond Python 3.9+
 stdlib) and can be run directly:
 
     python3 boundver.pyz generate
@@ -17,8 +17,9 @@
     ./dist/boundver.pyz verify
 
 Requires:
-  - Python 3.8+
-  - No external packages (boundver itself has none)
+  - Python 3.9+ for JSON configs
+  - Python 3.11+ for TOML configs in the standalone archive; YAML support is
+    optional
 """
 
 import argparse
diff --git a/scripts/packaging_smoke.sh b/scripts/packaging_smoke.sh
index ca76fd7..19cb22a 100755
--- a/scripts/packaging_smoke.sh
+++ b/scripts/packaging_smoke.sh
@@ -3,7 +3,87 @@ set -euo pipefail
 
 python -m pip install build
 python -m build
-python -m venv /tmp/boundver-smoke
-/tmp/boundver-smoke/bin/pip install dist/*.whl
-/tmp/boundver-smoke/bin/boundver --help
-/tmp/boundver-smoke/bin/boundver init --out /tmp/boundary.config.json --force
+
+set -- dist/*.whl
+if [[ $# -ne 1 || ! -f "$1" ]]; then
+  echo "Expected exactly one wheel in dist/" >&2
+  exit 1
+fi
+wheel_path="$PWD/$1"
+
+set -- dist/*.tar.gz
+if [[ $# -ne 1 || ! -f "$1" ]]; then
+  echo "Expected exactly one source distribution in dist/" >&2
+  exit 1
+fi
+sdist_path="$PWD/$1"
+
+smoke_root=$(mktemp -d)
+trap 'rm -rf "$smoke_root"' EXIT
+python -m venv "$smoke_root/venv"
+venv_python="$smoke_root/venv/bin/python"
+"$venv_python" -m pip install "$wheel_path"
+
+"$venv_python" - "$wheel_path" "$sdist_path" <<'PY'
+import sys
+import tarfile
+from pathlib import Path
+from zipfile import ZipFile
+
+wheel = Path(sys.argv[1])
+sdist = Path(sys.argv[2])
+with ZipFile(wheel) as archive:
+    wheel_members = set(archive.namelist())
+required_wheel = {
+    "boundver/__main__.py",
+    "boundver/boundary.config.schema.json",
+    "boundver/py.typed",
+}
+missing_wheel = required_wheel - wheel_members
+if missing_wheel:
+    raise SystemExit(f"wheel missing: {sorted(missing_wheel)}")
+
+with tarfile.open(sdist) as archive:
+    sdist_members = set(archive.getnames())
+prefix = next(name.split("/", 1)[0] for name in sdist_members if "/" in name)
+required_sdist = {
+    f"{prefix}/CODE_OF_CONDUCT.md",
+    f"{prefix}/SECURITY.md",
+    f"{prefix}/SUPPORT.md",
+    f"{prefix}/docs/PROJECT_REVIEW.md",
+    f"{prefix}/spec/HASHING.md",
+    f"{prefix}/tests/conftest.py",
+}
+missing_sdist = required_sdist - sdist_members
+if missing_sdist:
+    raise SystemExit(f"sdist missing: {sorted(missing_sdist)}")
+PY
+
+repo="$smoke_root/repo"
+mkdir "$repo"
+git -C "$repo" init -q
+git -C "$repo" config user.email smoke@example.com
+git -C "$repo" config user.name "Packaging Smoke"
+mkdir "$repo/svc"
+printf '{"contract": 1}\n' > "$repo/svc/api.json"
+git -C "$repo" add svc/api.json
+git -C "$repo" commit -qm baseline
+printf '%s\n' \
+  '{' \
+  '  "project": "packaging-smoke",' \
+  '  "components": {' \
+  '    "svc": {' \
+  '      "path": "svc",' \
+  '      "version_source": null,' \
+  '      "boundary": {"provider": "json-file", "paths": ["api.json"]}' \
+  '    }' \
+  '  },' \
+  '  "slices": {}' \
+  '}' > "$repo/boundary.config.json"
+
+cd "$repo"
+"$venv_python" -m boundver --version
+"$venv_python" -m boundver validate-config
+"$venv_python" -m boundver generate --source head --format json >/dev/null
+"$venv_python" -m boundver verify --source head --format json >/dev/null
+"$venv_python" -m boundver status --source head --format json >/dev/null
diff --git a/spec/HASHING.md b/spec/HASHING.md
index a4309c5..717d89d 100644
--- a/spec/HASHING.md
+++ b/spec/HASHING.md
@@ -1,42 +1,107 @@
-# HASHING Contract (v1)
+# Hashing contract (v2)
 
-This document defines the deterministic hashing contract for `boundary-lock/v1`.
+This document defines the deterministic hashing contract used by Boundver for
+newly generated lockfiles. Hashes created with the earlier unframed v1 contract
+must be regenerated: v2 intentionally changes every exact, content-only, raw
+boundary, and behavior digest.
 
 ## Core rules
-- Hash algorithm: SHA-256 (hex lowercase output).
-- Content basis: raw bytes.
-- Path basis: POSIX-normalized path separators (`\\` -> `/`).
-- Per-file contribution bytes:
 
-  `b"file:{posix_path}\\n" + file_bytes`
+- Hash algorithm: SHA-256 (lowercase hexadecimal output).
+- Path basis: repository-relative Git paths, which use POSIX separators.
+  Filesystem fallback paths use `Path.as_posix()`; a literal backslash in a
+  POSIX filename is content, not a separator, and remains a backslash.
+- Text line endings: CRLF is canonicalized to LF in every source mode when the
+  content contains no NUL byte.
+- Binary content: bytes containing a NUL byte are hashed without line-ending
+  conversion.
+- Ordering: entries are sorted by their UTF-8 label bytes, then by content.
+- Duplicate labels remain separate entries and are included in the entry count.
 
-- Component digest input is the concatenation of all per-file contribution bytes in lexicographic path order.
+Every digest over labeled entries uses the following binary wire format. `u64`
+means an unsigned, big-endian 64-bit integer, and `||` means byte
+concatenation:
+
+```text
+u64(len(magic)) || magic
+u64(len(domain)) || domain
+u64(entry_count)
+for each entry:
+  u64(len(label)) || label
+  u64(len(content)) || content
+```
+
+The magic value is the ASCII bytes `boundver-hash/v2`. Domains and labels are
+UTF-8 encoded. On POSIX, undecodable Git filename bytes are preserved through
+Python's `surrogateescape` mapping and re-emitted byte-for-byte. Explicit
+lengths and the entry count make the representation unambiguous even when a
+filename or file content resembles framing data.
+
+## Domains and labels
+
+| Purpose | Domain | Label |
+| --- | --- | --- |
+| Exact component tree | `exact-tree` | `file:{repository-relative path}` |
+| Vendored/content-only tree | `content-only-tree` | `file:{path relative to compared tree}` |
+| Boundary and behavior providers | `boundary` | Provider-supplied deterministic label |
+
+Domain separation prevents equal entry sets used for different purposes from
+producing the same digest. Provider implementations must use the shared framed
+entry helper and must return deterministic labels and raw byte content.
 
 ## File enumeration by source mode
-- `head`: files from `git ls-tree -r --name-only HEAD <component_path>`.
-- `index`: tracked file set for the path from index (current implementation reads blob bytes from `git show :<path>`).
-- `working-tree`: tracked files in the repository for the path (excluding untracked files).
 
-> Note: this document defines the target deterministic contract. Any implementation detail drift should be treated as a bug.
+- `head`: tracked files from `git ls-tree -r -z --name-only HEAD -- <path>`;
+  content comes from the corresponding `HEAD` blobs.
+- `index`: tracked files from `git ls-files --cached -z -- <path>`; content
+  comes from the corresponding index blobs.
+- `working-tree`: the same tracked file set as `index`, excluding tracked files
+  currently absent from disk; content comes from disk.
 
-## Derived digests
-- `exact`: digest over all tracked files under component path.
-- `boundary`: same digest algorithm, but restricted to declared `boundary.paths` expansion.
-- `compat`: SHA-256 of UTF-8 text identity string:
+Git filename output is NUL-delimited and decoded with the platform filesystem
+codec, so whitespace, newlines, and non-ASCII names are not confused with Git's
+human-readable C quoting. A successful empty Git result is authoritative.
+Filesystem enumeration is used for `working-tree` only when the Git listing
+command itself fails, such as in a non-Git directory, or when the repository
+has no first commit and therefore no tracked-file snapshot. It emits a warning.
+`head` and `index` require a readable Git source.
 
-  `{component_name}@compat:{compat_identity}`
+## Failure contract
 
-- `behavior`: same digest algorithm, but restricted to declared `behavior.paths` expansion. `null` when not configured.
-- `slice`: SHA-256 over canonical JSON of `{component_name: selected_digest}` where `selected_digest` is chosen by slice mode (`exact`, `behavior`, `boundary`, `compat`).
+Hashing fails closed. A missing, malformed, truncated, non-blob, or oversized
+Git object is an error, as is a working-tree file that disappears between
+enumeration and reading. These states never contribute empty bytes. A real
+zero-byte file remains valid and hashes normally.
+
+The guardrails are 50,000 files per digest and 50 MiB per file.
+
+## Derived digests
+
+- `exact`: the `exact-tree` digest over all tracked files below the component
+  path.
+- `boundary`: the `boundary` digest over the provider's resolved
+  entries.
+- `behavior`: the `boundary` digest over declared behavior entries;
+  `null` when not configured.
+- `compat`: SHA-256 of the UTF-8 identity string
+  `{component_name}@compat:{compat_identity}`. This single-value digest does not
+  use entry framing.
+- `slice`: SHA-256 over canonical JSON of `{component_name: selected_digest}`,
+  where the selected digest is chosen by slice mode (`exact`, `behavior`,
+  `boundary`, or `compat`).
 
 ## Canonical JSON
+
 - UTF-8 encoded.
 - Object keys sorted.
 - Compact separators: `,` and `:` (no insignificant whitespace).
 
-## Edge-case contract
-- Binary files: included (raw bytes).
-- Empty directories: excluded (not tracked by Git).
-- File permissions/mode bits: excluded from digest input.
-- Symlinks: hashed as symlink link-target text (not dereferenced file contents).
-- Git LFS: pointer blobs are hashed from the selected source state; cross-mode parity can differ when working tree is smudged.
+## Edge cases
+
+- Empty directories are excluded because Git does not track them.
+- File permissions and mode bits are excluded from digest input.
+- Symlinks are hashed as link-target text, not dereferenced content.
+- Git LFS pointer blobs are hashed from `head` and `index`; a smudged
+  `working-tree` file can therefore differ by design.
+- Other clean/smudge filters can likewise make working-tree content differ
+  from Git blobs. Line-ending canonicalization is the one built-in conversion.
diff --git a/spec/boundary.lock.schema.json b/spec/boundary.lock.schema.json
index 3ccaa62..4aa57b2 100644
--- a/spec/boundary.lock.schema.json
+++ b/spec/boundary.lock.schema.json
@@ -6,19 +6,24 @@
   "required": ["schema", "project", "components", "slices"],
   "properties": {
     "$schema": {"type": "string", "format": "uri"},
-    "schema": {"const": "boundary-lock/v1"},
+    "schema": {"const": "boundary-lock/v2"},
     "project": {"type": "string"},
-    "generated_at": {"type": "string", "format": "date-time"},
     "components": {
       "type": "object",
       "additionalProperties": {
         "type": "object",
-        "required": ["version", "path", "boundary_provider", "boundary_status", "fingerprints", "semver"],
+        "required": ["version", "path", "boundary_provider", "boundary_provider_version", "boundary_status", "consumers", "fingerprints", "semver"],
         "properties": {
           "version": {"type": ["string", "null"]},
           "path": {"type": "string"},
           "boundary_provider": {"type": "string"},
+          "boundary_provider_version": {"type": ["string", "null"]},
           "boundary_status": {"type": "string", "enum": ["ok", "partial", "error"]},
+          "consumers": {
+            "type": "array",
+            "items": {"type": "string"},
+            "uniqueItems": true
+          },
           "fingerprints": {
             "type": "object",
             "required": ["exact", "behavior", "boundary", "compat"],
@@ -41,7 +46,10 @@
             "additionalProperties": false
           },
           "boundary_errors": {"type": "array", "items": {"type": "string"}},
+          "version_errors": {"type": "array", "items": {"type": "string"}},
+          "behavior_errors": {"type": "array", "items": {"type": "string"}},
           "exact_errors": {"type": "array", "items": {"type": "string"}},
+          "boundary_metadata": {"type": ["object", "null"]},
           "warnings": {"type": "array", "items": {"type": "string"}},
           "vendored_copies": {"type": "array", "items": {"type": "string"}},
           "vendored_digests": {"type": "object", "additionalProperties": {"type": "string"}}
diff --git a/spec/cli-output.diff.schema.json b/spec/cli-output.diff.schema.json
index 31fe2b8..7b16df9 100644
--- a/spec/cli-output.diff.schema.json
+++ b/spec/cli-output.diff.schema.json
@@ -38,7 +38,7 @@
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["name", "old_version", "new_version", "changed_facets", "summary"],
+            "required": ["name", "old_version", "new_version", "changed_facets", "changed_metadata", "summary"],
             "properties": {
               "name": { "type": "string" },
               "old_version": { "type": ["string", "null"] },
@@ -55,6 +55,19 @@
                     "new": { "type": ["string", "null"] }
                   }
                 }
+              },
+              "changed_metadata": {
+                "type": "object",
+                "description": "Map of metadata field name to old/new values.",
+                "additionalProperties": {
+                  "type": "object",
+                  "required": ["old", "new"],
+                  "properties": {
+                    "old": {},
+                    "new": {}
+                  },
+                  "additionalProperties": false
+                }
               }
             }
           }
diff --git a/spec/cli-output.status.schema.json b/spec/cli-output.status.schema.json
index e991190..7d3e061 100644
--- a/spec/cli-output.status.schema.json
+++ b/spec/cli-output.status.schema.json
@@ -4,7 +4,7 @@
   "title": "boundver status --format json output",
   "description": "Schema for the JSON object printed to stdout by `boundver status --format json`.",
   "type": "object",
-  "required": ["lockfile", "issues"],
+  "required": ["lockfile", "issues", "warnings"],
   "additionalProperties": false,
   "properties": {
     "lockfile": {
@@ -15,6 +15,11 @@
       "type": "array",
       "description": "Drift issues between the lockfile and current repo state. Empty when up to date.",
       "items": { "type": "string" }
+    },
+    "warnings": {
+      "type": "array",
+      "description": "Non-drift warnings and recorded computation errors.",
+      "items": { "type": "string" }
     }
   }
 }
diff --git a/spec/cli-output.verify.schema.json b/spec/cli-output.verify.schema.json
index 000c901..1d74277 100644
--- a/spec/cli-output.verify.schema.json
+++ b/spec/cli-output.verify.schema.json
@@ -4,7 +4,7 @@
   "title": "boundver verify --format json output",
   "description": "Schema for the JSON object printed to stdout by `boundver verify --format json`.",
   "type": "object",
-  "required": ["ok", "issues", "components_filter"],
+  "required": ["ok", "updated", "issues", "observations", "facets", "components_filter"],
   "additionalProperties": false,
   "properties": {
     "ok": {
@@ -16,6 +16,22 @@
       "description": "Human-readable issue strings. Empty when ok=true.",
       "items": { "type": "string" }
     },
+    "updated": {
+      "type": "boolean",
+      "description": "true when --update successfully wrote a refreshed lockfile."
+    },
+    "observations": {
+      "type": "array",
+      "description": "Detected drift outside the selected gating facets.",
+      "items": { "type": "string" }
+    },
+    "facets": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["exact", "behavior", "boundary", "compat"]
+      }
+    },
     "components_filter": {
       "type": "array",
       "description": "Component names actually verified. Empty list means all components were checked.",
diff --git a/spec/spec.md b/spec/spec.md
index d808c61..fc80df7 100644
--- a/spec/spec.md
+++ b/spec/spec.md
@@ -1,7 +1,7 @@
-# boundver Spec Overview (v1)
+# boundver Spec Overview (v2)
 
 ## Lockfile schema
-- Lockfile schema identifier: `boundary-lock/v1`.
+- Lockfile schema identifier: `boundary-lock/v2`.
 - Canonical schema file: `spec/boundary.lock.schema.json`.
 
 ## Component facets
diff --git a/src/boundver/__init__.py b/src/boundver/__init__.py
index a538e5a..97a7739 100644
--- a/src/boundver/__init__.py
+++ b/src/boundver/__init__.py
@@ -60,19 +60,29 @@ def generate(
     """
     import json
     from pathlib import Path
-    from ._config import load_config_file, find_config_file
+    from ._config import load_config_file, find_config_file, validate_config
     from ._lockfile import generate_lockfile
     from ._git import git_root
+    from .core import _ensure_lock_outside_components, _write_text_atomic
 
     repo_root = git_root()
     config = load_config_file(find_config_file(repo_root, config_path))
+    config_errors = validate_config(
+        config,
+        repo_root,
+        allow_custom_providers=allow_custom_providers,
+        source=source,
+    )
+    if config_errors:
+        raise ConfigError("Config is invalid:\n" + "\n".join(config_errors))
     lockfile = generate_lockfile(
         config, repo_root, source=source, strict=True,
         allow_custom_providers=allow_custom_providers,
     )
     if out_path is not None:
         dest = repo_root / out_path
-        dest.write_text(json.dumps(lockfile, indent=2) + "\n", encoding="utf-8")
+        _ensure_lock_outside_components(repo_root, dest, config)
+        _write_text_atomic(dest, json.dumps(lockfile, indent=2) + "\n")
     return lockfile
 
 
@@ -87,15 +97,24 @@ def verify(
 
     Returns a list of mismatch strings. Empty list means up to date.
     """
-    import json
-    from pathlib import Path
-    from ._config import load_config_file, find_config_file
+    from ._config import load_config_file, find_config_file, validate_config
     from ._lockfile import verify_lockfile
     from ._git import git_root
+    from .core import _ensure_lock_outside_components, _load_lockfile
 
     repo_root = git_root()
     config = load_config_file(find_config_file(repo_root, config_path))
-    lf = json.loads((repo_root / lock_path).read_text(encoding="utf-8"))
+    config_errors = validate_config(
+        config,
+        repo_root,
+        allow_custom_providers=allow_custom_providers,
+        source=source,
+    )
+    if config_errors:
+        raise ConfigError("Config is invalid:\n" + "\n".join(config_errors))
+    resolved_lock_path = repo_root / lock_path
+    _ensure_lock_outside_components(repo_root, resolved_lock_path, config)
+    lf = _load_lockfile(resolved_lock_path)
     return verify_lockfile(
         config, lf, repo_root, source=source,
         components_filter=components,
diff --git a/src/boundver/__main__.py b/src/boundver/__main__.py
new file mode 100644
index 0000000..4c5d5dc
--- /dev/null
+++ b/src/boundver/__main__.py
@@ -0,0 +1,7 @@
+"""Run boundver with ``python -m boundver``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/boundver/_completions.py b/src/boundver/_completions.py
index 9ce0f5a..2fbd244 100644
--- a/src/boundver/_completions.py
+++ b/src/boundver/_completions.py
@@ -1,255 +1,121 @@
-"""Shell completion scripts for boundver."""
+"""Shell completion scripts for the public boundver CLI."""
 
 from typing import Dict
 
-_BASH_COMPLETION = """\
-# boundver bash completion
-# Source this file or add to ~/.bash_completion.d/
-_boundver_completions() {
-    local cur prev words cword
-    _init_completion 2>/dev/null || {
-        COMP_WORDS=("${COMP_WORDS[@]}")
-        cword=$COMP_CWORD
-        cur="${COMP_WORDS[$cword]}"
-        prev="${COMP_WORDS[$cword-1]}"
-    }
 
-    local commands="generate verify diff slice validate-config init status explain why discover completions"
-    local global_opts="--quiet --verbose --help"
+_COMMANDS = (
+    "generate verify diff slice validate-config check-config init add remove "
+    "status explain why discover migrate-lock completions"
+)
 
-    case "${COMP_WORDS[1]}" in
-        generate)
-            case "$prev" in
-                --source)   COMPREPLY=($(compgen -W "head index working-tree" -- "$cur")); return ;;
-                --format)   COMPREPLY=($(compgen -W "json text" -- "$cur")); return ;;
-                --config|--out) COMPREPLY=($(compgen -f -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--config --out --source --allow-partial --dry-run --components --format --allow-custom-providers --quiet --verbose" -- "$cur")) ;;
-        verify)
-            case "$prev" in
-                --source)       COMPREPLY=($(compgen -W "head index working-tree" -- "$cur")); return ;;
-                --format)       COMPREPLY=($(compgen -W "json text" -- "$cur")); return ;;
-                --config|--lock) COMPREPLY=($(compgen -f -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--config --lock --source --components --changed-from --format --allow-custom-providers --quiet --verbose" -- "$cur")) ;;
-        diff)
-            case "$prev" in
-                --format) COMPREPLY=($(compgen -W "json text" -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--format" -- "$cur")) ;;
-        slice)
-            case "$prev" in
-                --lock) COMPREPLY=($(compgen -f -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--lock" -- "$cur")) ;;
-        validate-config)
-            COMPREPLY=($(compgen -W "--config --allow-custom-providers" -- "$cur")) ;;
-        init)
-            COMPREPLY=($(compgen -W "--out --force --discover" -- "$cur")) ;;
-        status)
-            case "$prev" in
-                --source) COMPREPLY=($(compgen -W "head index working-tree" -- "$cur")); return ;;
-                --format) COMPREPLY=($(compgen -W "json text" -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--config --lock --source --format --quiet" -- "$cur")) ;;
-        explain)
-            case "$prev" in
-                --config) COMPREPLY=($(compgen -f -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--config --base-ref" -- "$cur")) ;;
-        why)
-            case "$prev" in
-                --source) COMPREPLY=($(compgen -W "head index working-tree" -- "$cur")); return ;;
-                --config|--lock) COMPREPLY=($(compgen -f -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--config --lock --source" -- "$cur")) ;;
-        discover)
-            case "$prev" in
-                --format) COMPREPLY=($(compgen -W "json text" -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--format" -- "$cur")) ;;
-        completions)
-            case "$prev" in
-                --shell) COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur")); return ;;
-            esac
-            COMPREPLY=($(compgen -W "--shell" -- "$cur")) ;;
-        *)
-            if [[ $cword -eq 1 ]]; then
-                COMPREPLY=($(compgen -W "$commands $global_opts" -- "$cur"))
-            fi ;;
+_BASH_COMPLETION = r"""# boundver bash completion
+_boundver_completions() {
+    local cur prev command options
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    command="${COMP_WORDS[1]}"
+    case "$prev" in
+        --source) COMPREPLY=($(compgen -W "head index working-tree" -- "$cur")); return ;;
+        --format) COMPREPLY=($(compgen -W "text json" -- "$cur")); return ;;
+        --shell) COMPREPLY=($(compgen -W "bash zsh fish" -- "$cur")); return ;;
+        --config|--lock|--out) COMPREPLY=($(compgen -f -- "$cur")); return ;;
+    esac
+    case "$command" in
+        generate) options="--config --out --source --allow-partial --dry-run --components --format --allow-custom-providers --quiet --verbose" ;;
+        verify) options="--config --lock --source --components --changed-from --facets --fail-fast --update --format --allow-custom-providers --quiet --verbose" ;;
+        diff) options="--format" ;;
+        slice) options="--lock" ;;
+        validate-config|check-config) options="--config --allow-custom-providers" ;;
+        init) options="--out --force --discover" ;;
+        add) options="--provider --paths --config" ;;
+        remove) options="--config" ;;
+        status) options="--config --lock --source --format --strict --allow-custom-providers --quiet --verbose" ;;
+        explain) options="--config --base-ref --source" ;;
+        why) options="--config --lock --source --allow-custom-providers" ;;
+        discover) options="--format" ;;
+        migrate-lock) options="--lock --dry-run" ;;
+        completions) options="--shell" ;;
+        *) options="" ;;
     esac
+    if [[ $COMP_CWORD -eq 1 ]]; then
+        COMPREPLY=($(compgen -W "generate verify diff slice validate-config check-config init add remove status explain why discover migrate-lock completions --quiet --verbose --version --help" -- "$cur"))
+    else
+        COMPREPLY=($(compgen -W "$options" -- "$cur"))
+    fi
 }
 complete -F _boundver_completions boundver
 """
 
-_ZSH_COMPLETION = """\
-#compdef boundver
-# boundver zsh completion — place in a $fpath directory as _boundver
-
+_ZSH_COMPLETION = r"""#compdef boundver
 _boundver() {
     local -a commands
     commands=(
-        'generate:Generate or update the lockfile'
-        'verify:Check lockfile matches current repo state'
-        'diff:Diff two lockfiles'
-        'slice:Show fingerprint for a specific slice'
-        'validate-config:Validate config for strict boundary rules'
-        'init:Create a starter boundary.config.json'
-        'status:Show lockfile summary and warnings'
-        'explain:Explain changed files for a component'
-        'why:Explain why a component lockfile is out of date'
-        'discover:Print discovered components as JSON'
-        'completions:Emit shell completion scripts'
+      'generate:Generate or update the lockfile'
+      'verify:Check selected facets against the lockfile'
+      'diff:Diff two lockfiles'
+      'slice:Show a slice fingerprint'
+      'validate-config:Validate configuration'
+      'check-config:Alias for validate-config'
+      'init:Create a starter JSON config'
+      'add:Add a component'
+      'remove:Remove a component'
+      'status:Show status and drift'
+      'explain:Explain changed files'
+      'why:Explain component drift'
+      'discover:Discover tracked manifests'
+      'migrate-lock:Check or migrate a lock schema'
+      'completions:Emit a completion script'
     )
-    case "$words[2]" in
-        generate)
-            _arguments \\
-                '--config[Config file path]:file:_files' \\
-                '--out[Output lockfile path]:file:_files' \\
-                '--source[Fingerprint source]:source:(head index working-tree)' \\
-                '--allow-partial[Allow missing digests]' \\
-
-                '--dry-run[Do not write output]' \\
-                '--components[Component names (comma-separated)]:components:' \\
-                '--format[Output format]:format:(json text)' \\
-                '--allow-custom-providers[Allow loading external provider modules]' \\
-                '--quiet[Suppress output]' \\
-                '--verbose[Extra diagnostics]' ;;
-        verify)
-            _arguments \\
-                '--config[Config file path]:file:_files' \\
-                '--lock[Lockfile path]:file:_files' \\
-                '--source[Fingerprint source]:source:(head index working-tree)' \\
-                '--components[Component names (comma-separated)]:components:' \\
-                '--changed-from[Auto-select changed components since ref]:ref:' \\
-                '--format[Output format]:format:(json text)' \\
-                '--allow-custom-providers[Allow loading external provider modules]' \\
-                '--quiet[Suppress output]' \\
-                '--verbose[Extra diagnostics]' ;;
-        diff)
-            _arguments \\
-                ':old lockfile:_files' \\
-                ':new lockfile:_files' \\
-                '--format[Output format]:format:(json text)' ;;
-        slice)
-            _arguments \\
-                ':slice name:' \\
-                '--lock[Lockfile path]:file:_files' ;;
-        validate-config)
-            _arguments '--config[Config file path]:file:_files' \\
-                        '--allow-custom-providers[Allow loading external provider modules]' ;;
-        init)
-            _arguments \\
-                '--out[Output config path]:file:_files' \\
-                '--force[Overwrite existing]' \\
-                '--discover[Auto-discover components]' ;;
-        status)
-            _arguments \\
-                '--config[Config file path]:file:_files' \\
-                '--lock[Lockfile path]:file:_files' \\
-                '--source[Fingerprint source]:source:(head index working-tree)' \\
-                '--format[Output format]:format:(json text)' \\
-                '--quiet[Suppress output]' ;;
-        explain)
-            _arguments \\
-                ':component name:' \\
-                '--config[Config file path]:file:_files' \\
-                '--base-ref[Git ref to diff against]:ref:' ;;
-        why)
-            _arguments \\
-                ':component name:' \\
-                '--config[Config file path]:file:_files' \\
-                '--lock[Lockfile path]:file:_files' \\
-                '--source[Fingerprint source]:source:(head index working-tree)' ;;
-        discover)
-            _arguments '--format[Output format]:format:(json text)' ;;
-        completions)
-            _arguments '--shell[Shell type]:shell:(bash zsh fish)' ;;
-        *)
-            _describe 'command' commands ;;
+    _arguments -C '--quiet[Reduce output]' '--verbose[Extra diagnostics]' '--version[Show version]' '1:command:->command' '*::arg:->args'
+    case $state in
+      command) _describe command commands ;;
+      args)
+        case $words[2] in
+          generate) _arguments '--config[Config]:file:_files' '--out[Lockfile]:file:_files' '--source[Source]:(head index working-tree)' '--allow-partial' '--dry-run' '--components[Names]' '--format[Format]:(text json)' '--allow-custom-providers' '--quiet' '--verbose' ;;
+          verify) _arguments '--config[Config]:file:_files' '--lock[Lockfile]:file:_files' '--source[Source]:(head index working-tree)' '--components[Names]' '--changed-from[Git ref]' '--facets[Gate facets]' '--fail-fast' '--update' '--format[Format]:(text json)' '--allow-custom-providers' '--quiet' '--verbose' ;;
+          diff) _arguments '1:old lock:_files' '2:new lock:_files' '--format[Format]:(text json)' ;;
+          slice) _arguments '1:slice' '--lock[Lockfile]:file:_files' ;;
+          validate-config|check-config) _arguments '--config[Config]:file:_files' '--allow-custom-providers' ;;
+          init) _arguments '--out[Config]:file:_files' '--force' '--discover' ;;
+          add) _arguments '1:name' '2:path:_files' '--provider[Provider]' '--paths[Boundary paths]' '--config[Config]:file:_files' ;;
+          remove) _arguments '1:name' '--config[Config]:file:_files' ;;
+          status) _arguments '--config[Config]:file:_files' '--lock[Lockfile]:file:_files' '--source[Source]:(head index working-tree)' '--format[Format]:(text json)' '--strict' '--allow-custom-providers' '--quiet' '--verbose' ;;
+          explain) _arguments '1:component' '--config[Config]:file:_files' '--base-ref[Git ref]' '--source[Source]:(head index working-tree)' ;;
+          why) _arguments '1:component' '--config[Config]:file:_files' '--lock[Lockfile]:file:_files' '--source[Source]:(head index working-tree)' '--allow-custom-providers' ;;
+          discover) _arguments '--format[Format]:(text json)' ;;
+          migrate-lock) _arguments '--lock[Lockfile]:file:_files' '--dry-run' ;;
+          completions) _arguments '--shell[Shell]:(bash zsh fish)' ;;
+        esac ;;
     esac
 }
 _boundver
 """
 
-_FISH_COMPLETION = """\
-# boundver fish completion
-# Place in ~/.config/fish/completions/boundver.fish
-
-set -l __boundver_cmds generate verify diff slice validate-config init status explain why discover completions
-
-# subcommands
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a generate        -d 'Generate or update the lockfile'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a verify          -d 'Check lockfile matches current repo state'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a diff            -d 'Diff two lockfiles'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a slice           -d 'Show fingerprint for a specific slice'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a validate-config -d 'Validate config'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a init            -d 'Create a starter boundary.config.json'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a status          -d 'Show lockfile summary and warnings'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a explain         -d 'Explain changed files for a component'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a why            -d 'Explain why a component lockfile is out of date'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a discover        -d 'Print discovered components as JSON'
-complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a completions     -d 'Emit shell completion scripts'
-
-# generate
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l config      -d 'Config file path'         -F
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l out         -d 'Output lockfile path'     -F
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l source      -d 'Fingerprint source'       -a 'head index working-tree'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l format      -d 'Output format'            -a 'json text'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l components  -d 'Component names'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l allow-partial -d 'Allow missing digests'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l dry-run     -d 'Do not write output'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l allow-custom-providers -d 'Allow loading external provider modules'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l quiet       -d 'Suppress output'
-complete -c boundver -n "__fish_seen_subcommand_from generate" -l verbose     -d 'Extra diagnostics'
-
-# verify
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l config       -d 'Config file path'             -F
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l lock         -d 'Lockfile path'                -F
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l source       -d 'Fingerprint source'           -a 'head index working-tree'
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l format       -d 'Output format'                -a 'json text'
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l components   -d 'Component names'
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l changed-from -d 'Auto-select changed since ref'
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l allow-custom-providers -d 'Allow loading external provider modules'
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l quiet        -d 'Suppress output'
-complete -c boundver -n "__fish_seen_subcommand_from verify" -l verbose      -d 'Extra diagnostics'
-
-# diff
-complete -c boundver -n "__fish_seen_subcommand_from diff" -l format -d 'Output format' -a 'json text'
-
-# slice
-complete -c boundver -n "__fish_seen_subcommand_from slice" -l lock -d 'Lockfile path' -F
-
-# validate-config
-complete -c boundver -n "__fish_seen_subcommand_from validate-config" -l config              -d 'Config file path' -F
-complete -c boundver -n "__fish_seen_subcommand_from validate-config" -l allow-custom-providers -d 'Allow loading external provider modules'
-
-# init
-complete -c boundver -n "__fish_seen_subcommand_from init" -l out      -d 'Output config path' -F
-complete -c boundver -n "__fish_seen_subcommand_from init" -l force    -d 'Overwrite existing'
-complete -c boundver -n "__fish_seen_subcommand_from init" -l discover -d 'Auto-discover components'
-
-# status
-complete -c boundver -n "__fish_seen_subcommand_from status" -l config -d 'Config file path'     -F
-complete -c boundver -n "__fish_seen_subcommand_from status" -l lock   -d 'Lockfile path'        -F
-complete -c boundver -n "__fish_seen_subcommand_from status" -l source -d 'Fingerprint source'   -a 'head index working-tree'
-complete -c boundver -n "__fish_seen_subcommand_from status" -l format -d 'Output format'        -a 'json text'
-complete -c boundver -n "__fish_seen_subcommand_from status" -l quiet  -d 'Suppress output'
-
-# explain
-complete -c boundver -n "__fish_seen_subcommand_from explain" -l config   -d 'Config file path'       -F
-complete -c boundver -n "__fish_seen_subcommand_from explain" -l base-ref -d 'Git ref to diff against'
-
-# why
-complete -c boundver -n "__fish_seen_subcommand_from why" -l config -d 'Config file path'     -F
-complete -c boundver -n "__fish_seen_subcommand_from why" -l lock   -d 'Lockfile path'        -F
-complete -c boundver -n "__fish_seen_subcommand_from why" -l source -d 'Fingerprint source'   -a 'head index working-tree'
-
-# discover
-complete -c boundver -n "__fish_seen_subcommand_from discover" -l format -d 'Output format' -a 'json text'
-
-# completions
-complete -c boundver -n "__fish_seen_subcommand_from completions" -l shell -d 'Shell type' -a 'bash zsh fish'
+_FISH_COMPLETION = """# boundver fish completion
+set -l __boundver_cmds generate verify diff slice validate-config check-config init add remove status explain why discover migrate-lock completions
+complete -c boundver -f -n "not __fish_seen_subcommand_from $__boundver_cmds" -a "$__boundver_cmds"
+complete -c boundver -l quiet -d 'Reduce output'
+complete -c boundver -l verbose -d 'Extra diagnostics'
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l source -a 'head index working-tree'
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l config -F
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l out -F
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l allow-partial
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l dry-run
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l components
+complete -c boundver -n '__fish_seen_subcommand_from generate' -l format -a 'text json'
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l source -a 'head index working-tree'
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l config -F
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l lock -F
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l components
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l changed-from
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l facets
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l fail-fast
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l update
+complete -c boundver -n '__fish_seen_subcommand_from verify' -l format -a 'text json'
+complete -c boundver -n '__fish_seen_subcommand_from status' -l strict
+complete -c boundver -n '__fish_seen_subcommand_from status' -l format -a 'text json'
+complete -c boundver -n '__fish_seen_subcommand_from explain why status' -l source -a 'head index working-tree'
+complete -c boundver -n '__fish_seen_subcommand_from completions' -l shell -a 'bash zsh fish'
 """
 
 _COMPLETION_SCRIPTS: Dict[str, str] = {
diff --git a/src/boundver/_config.py b/src/boundver/_config.py
index 1e92c8c..13f3326 100644
--- a/src/boundver/_config.py
+++ b/src/boundver/_config.py
@@ -2,12 +2,21 @@
 
 import fnmatch
 import json
+import os
+import subprocess
+from importlib import resources
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
 
-from ._git import _to_posix
+from ._git import _decode_nul_paths, _git_run_bytes, _to_posix
 from ._hashing import _is_within
 from ._utils import _is_glob, boundary_provider_name, ConfigError
+from .providers import (
+    create_registry,
+    get_provider,
+    load_custom_providers,
+    validate_provider_config,
+)
 
 # Ordered preference when auto-discovering config (first match wins)
 _CONFIG_CANDIDATES = [
@@ -59,10 +68,10 @@ def load_config_file(path: Path) -> dict:
     text = path.read_text(encoding="utf-8")
     if suffix == ".json":
         try:
-            return json.loads(text)
+            result = json.loads(text)
         except json.JSONDecodeError as exc:
             raise ConfigError(f"JSON parse error in {path}: {exc}") from exc
-    if suffix in (".yaml", ".yml"):
+    elif suffix in (".yaml", ".yml"):
         try:
             import yaml  # type: ignore
             result = yaml.safe_load(text)
@@ -75,10 +84,7 @@ def load_config_file(path: Path) -> dict:
             raise
         except Exception as exc:
             raise ConfigError(f"YAML parse error in {path}: {exc}") from exc
-        if not isinstance(result, dict):
-            raise ConfigError(f"Config file {path} must contain a YAML mapping, got {type(result).__name__}")
-        return result
-    if suffix == ".toml":
+    elif suffix == ".toml":
         try:
             import tomllib  # type: ignore  # Python 3.11+
         except ImportError:
@@ -90,25 +96,39 @@ def load_config_file(path: Path) -> dict:
                     "Install tomli: pip install tomli"
                 )
         try:
-            return tomllib.loads(text)
+            result = tomllib.loads(text)
         except (MemoryError, RecursionError):
             raise
         except Exception as exc:
             raise ConfigError(f"TOML parse error in {path}: {exc}") from exc
-    raise ConfigError(
-        f"Unsupported config file extension '{suffix}' for {path}. "
-        "Supported formats: .json, .yaml, .yml, .toml"
-    )
+    else:
+        raise ConfigError(
+            f"Unsupported config file extension '{suffix}' for {path}. "
+            "Supported formats: .json, .yaml, .yml, .toml"
+        )
+    if not isinstance(result, dict):
+        raise ConfigError(
+            f"Config file {path} must contain an object/mapping, "
+            f"got {type(result).__name__}"
+        )
+    return result
 
 
 
 def _load_config_schema(repo_root: Path) -> Optional[dict]:
+    """Load the packaged schema, falling back to a checkout-local override."""
     schema_path = repo_root / "boundary.config.schema.json"
-    if not schema_path.exists():
-        return None
+    if schema_path.exists():
+        try:
+            return json.loads(schema_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            pass
     try:
-        return json.loads(schema_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError:
+        bundled = resources.read_text(
+            "boundver", "boundary.config.schema.json", encoding="utf-8"
+        )
+        return json.loads(bundled)
+    except (FileNotFoundError, OSError, json.JSONDecodeError):
         return None
 
 
@@ -130,6 +150,7 @@ def _validate_component_path_entries(
     component_path: Optional[str],
     field_name: str,
     paths: List[str],
+    check_exists: bool = True,
 ) -> None:
     """Validate a component-relative path list for boundary/behavior config."""
     if component_path is None:
@@ -137,6 +158,12 @@ def _validate_component_path_entries(
 
     component_root = repo_root / component_path
     for rel in paths:
+        if "\\" in rel:
+            errors.append(
+                f"Component '{component_name}' {field_name} path must use '/' "
+                f"separators for portability: {rel}"
+            )
+            continue
         if _is_glob(rel):
             if ".." in rel:
                 errors.append(
@@ -151,7 +178,7 @@ def _validate_component_path_entries(
         if not _is_within(repo_root, full):
             errors.append(f"Component '{component_name}' {field_name} path escapes repository root: {rel}")
             continue
-        if not full.exists():
+        if check_exists and not full.exists():
             errors.append(
                 f"Component '{component_name}' {field_name} path not found: {component_path}/{rel}"
                 f" — ensure the file exists before running generate"
@@ -232,10 +259,17 @@ def _schema_engine_errors(config: dict, schema: Optional[dict]) -> List[str]:
     return sorted(errors)
 
 
-def validate_config(config: dict, repo_root: Path) -> List[str]:
+def validate_config(
+    config: dict,
+    repo_root: Path,
+    allow_custom_providers: bool = False,
+    source: str = "working-tree",
+) -> List[str]:
     errors: List[str] = []
     if not isinstance(config, dict):
         return ["Config root must be a JSON object"]
+    if source not in {"head", "index", "working-tree"}:
+        return [f"Unknown source mode: {source!r}"]
 
     schema = _load_config_schema(repo_root)
     errors.extend(_schema_engine_errors(config, schema))
@@ -243,20 +277,50 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
         if required_key not in config:
             errors.append(f"Missing required top-level field: {required_key}")
 
+    project = config.get("project")
+    if not isinstance(project, str) or not project.strip():
+        errors.append("Field 'project' must be a non-empty string")
+
     supported_modes = {"exact", "behavior", "boundary", "compat"}
-    compat_mode = config.get("defaults", {}).get("compat_mode", "major")
-    if compat_mode not in {"major", "semver_major", "semver_major_minor"}:
+    defaults = config.get("defaults", {})
+    if not isinstance(defaults, dict):
+        errors.append("Field 'defaults' must be an object")
+        defaults = {}
+    compat_mode = defaults.get("compat_mode", "major")
+    if not isinstance(compat_mode, str) or compat_mode not in {
+        "major", "semver_major", "semver_major_minor"
+    }:
         errors.append(f"Unsupported defaults.compat_mode: {compat_mode}")
+    verify_facets = defaults.get("verify_facets")
+    if verify_facets is not None:
+        if not _is_str_list(verify_facets) or not verify_facets:
+            errors.append("defaults.verify_facets must be a non-empty array of strings")
+        else:
+            invalid = sorted(set(verify_facets) - supported_modes)
+            if invalid:
+                errors.append(
+                    "defaults.verify_facets contains unknown facets: "
+                    + ", ".join(invalid)
+                )
 
     components = config.get("components", {})
     slices = config.get("slices", {})
     if not isinstance(components, dict):
         errors.append("Field 'components' must be an object")
         components = {}
+    elif not components:
+        errors.append("Field 'components' must define at least one component")
     if not isinstance(slices, dict):
         errors.append("Field 'slices' must be an object")
         slices = {}
 
+    if "allow_custom_providers" in config:
+        errors.append(
+            "Top-level 'allow_custom_providers' is not supported: repository config "
+            "cannot authorize Python imports; pass --allow-custom-providers or set "
+            "BOUNDVER_ALLOW_CUSTOM_PROVIDERS=1 in trusted automation"
+        )
+
     seen_component_paths: Dict[str, str] = {}
     known_providers = {
         "openapi", "python-exports", "typescript-exports", "json-file", "leaf", "implicit",
@@ -302,8 +366,8 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                         )
                     else:
                         declared_custom_names.add(declared_name)
-                elif isinstance(cls_name, str) and cls_name.strip():
-                    declared_custom_names.add(f"custom.{cls_name.strip()}")
+                # Without an explicit name, the provider instance determines
+                # its registered custom.* identifier after trusted loading.
 
     for name, comp in components.items():
         if not isinstance(comp, dict):
@@ -316,7 +380,12 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
         if component_path is None:
             errors.append(f"Component '{name}' field 'path' must be a non-empty string")
         else:
-            normalized_path = component_path.rstrip("/")
+            if "\\" in component_path:
+                errors.append(
+                    f"Component '{name}' path must use '/' separators for portability: "
+                    f"{component_path}"
+                )
+            normalized_path = _to_posix(os.path.normpath(component_path.strip()))
             if ".." in normalized_path.replace("\\", "/").split("/"):
                 errors.append(
                     f"Component '{name}' path must not contain '..': {normalized_path}"
@@ -325,6 +394,25 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                 errors.append(
                     f"Component '{name}' path must be relative: {normalized_path}"
                 )
+            elif normalized_path in {"", "."}:
+                errors.append(
+                    f"Component '{name}' cannot use the repository root as its path: "
+                    "the generated lockfile would become part of its own exact fingerprint. "
+                    "Place the component in a subdirectory."
+                )
+            elif source == "working-tree" and (repo_root / normalized_path).is_symlink():
+                errors.append(
+                    f"Component '{name}' path must not be a symlink: {normalized_path}"
+                )
+            elif source == "working-tree" and not _is_within(repo_root, repo_root / normalized_path):
+                errors.append(
+                    f"Component '{name}' path escapes the repository: {normalized_path}"
+                )
+            elif source == "working-tree" and not (repo_root / normalized_path).is_dir():
+                errors.append(
+                    f"Component '{name}' path not found or not a directory: "
+                    f"{normalized_path}"
+                )
             if normalized_path in seen_component_paths:
                 other = seen_component_paths[normalized_path]
                 errors.append(
@@ -353,7 +441,7 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                     f"Component '{name}' uses '{provider_name}' but no 'providers' list is "
                     "declared in the config — add a top-level 'providers' array"
                 )
-            elif provider_name not in declared_custom_names:
+            elif declared_custom_names and provider_name not in declared_custom_names:
                 errors.append(
                     f"Component '{name}' uses '{provider_name}' which is not declared in the "
                     f"'providers' list — add an entry with \"class\": \"{provider_name[7:]}\""
@@ -369,6 +457,7 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
             component_path,
             "boundary",
             paths,
+            check_exists=(source == "working-tree"),
         )
 
         behavior = comp.get("behavior")
@@ -387,10 +476,43 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                     component_path,
                     "behavior",
                     behavior_paths,
+                    check_exists=(source == "working-tree"),
                 )
         vendored = comp.get("vendored_copies")
         if vendored is not None and not _is_str_list(vendored):
             errors.append(f"Component '{name}' field 'vendored_copies' must be an array of strings")
+        elif vendored is not None:
+            for vendored_path in vendored:
+                normalized_vendored = vendored_path.replace("\\", "/")
+                if (
+                    not vendored_path.strip()
+                    or "\\" in vendored_path
+                    or Path(vendored_path).is_absolute()
+                    or ".." in normalized_vendored.split("/")
+                    or not _is_within(repo_root, repo_root / vendored_path)
+                ):
+                    errors.append(
+                        f"Component '{name}' vendored copy must be a safe repo-relative "
+                        f"path using '/' separators: {vendored_path!r}"
+                    )
+                elif source == "working-tree" and not (repo_root / vendored_path).exists():
+                    errors.append(
+                        f"Component '{name}' vendored copy not found: {vendored_path}"
+                    )
+        consumers = comp.get("consumers")
+        if consumers is not None:
+            if not _is_str_list(consumers):
+                errors.append(f"Component '{name}' field 'consumers' must be an array of strings")
+            else:
+                if len(consumers) != len(set(consumers)):
+                    errors.append(f"Component '{name}' field 'consumers' contains duplicates")
+                for consumer in consumers:
+                    if consumer == name:
+                        errors.append(f"Component '{name}' cannot consume its own boundary")
+                    elif consumer not in components:
+                        errors.append(
+                            f"Component '{name}' references unknown consumer: {consumer}"
+                        )
 
         # Validate version_source — check file exists and has a supported extension.
         version_source = comp.get("version_source")
@@ -405,6 +527,15 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                 if not isinstance(vs_file, str) or not vs_file.strip():
                     errors.append(f"Component '{name}' version_source.file must be a non-empty string")
                 else:
+                    if (
+                        "\\" in vs_file
+                        or Path(vs_file).is_absolute()
+                        or ".." in vs_file.replace("\\", "/").split("/")
+                    ):
+                        errors.append(
+                            f"Component '{name}' version_source.file must be a safe "
+                            f"component-relative path using '/' separators: {vs_file!r}"
+                        )
                     _supported_vs_exts = {".json", ".toml", ".yaml", ".yml"}
                     if Path(vs_file).suffix not in _supported_vs_exts:
                         errors.append(
@@ -412,7 +543,17 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                             f" — supported: {', '.join(sorted(_supported_vs_exts))}"
                         )
                     vs_full = (repo_root / component_path / vs_file) if component_path is not None else None
-                    if vs_full is not None and not vs_full.exists():
+                    if source == "working-tree" and vs_full is not None and vs_full.is_symlink():
+                        errors.append(
+                            f"Component '{name}' version_source.file must not be a symlink: "
+                            f"'{vs_file}'"
+                        )
+                    elif source == "working-tree" and vs_full is not None and not _is_within(repo_root, vs_full):
+                        errors.append(
+                            f"Component '{name}' version_source.file escapes the repository: "
+                            f"'{vs_file}'"
+                        )
+                    if source == "working-tree" and vs_full is not None and not vs_full.exists():
                         errors.append(
                             f"Component '{name}' version_source.file not found: '{vs_file}'"
                             f" (looked for {component_path}/{vs_file})"
@@ -422,17 +563,24 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                             f"Component '{name}' version_source has 'file' but no 'field' — "
                             "specify which field to read, e.g. \"field\": \"version\""
                         )
+                    elif not isinstance(version_source.get("field"), str) or not version_source["field"].strip():
+                        errors.append(
+                            f"Component '{name}' version_source.field must be a non-empty string"
+                        )
             else:
                 errors.append(
                     f"Component '{name}' version_source must have either 'file' or 'git_tag_prefix'"
                 )
 
     for sname, sdef in slices.items():
+        if not isinstance(sname, str) or not sname.strip():
+            errors.append("Slice names must be non-empty strings")
+            continue
         if not isinstance(sdef, dict):
             errors.append(f"Slice '{sname}' must be an object")
             continue
         mode = sdef.get("mode", "exact")
-        if mode not in supported_modes:
+        if not isinstance(mode, str) or mode not in supported_modes:
             errors.append(f"Slice '{sname}' has unknown mode: {mode}")
         slice_components = sdef.get("components", [])
         if not _is_str_list(slice_components):
@@ -452,6 +600,39 @@ def validate_config(config: dict, repo_root: Path) -> List[str]:
                 elif kind not in {"leaf", "implicit"} and not paths:
                     errors.append(f"Slice '{sname}' in {mode} mode includes '{cname}' with no boundary paths")
 
+    registry = create_registry()
+    provider_load_errors = load_custom_providers(
+        config.get("providers", []),
+        allow_custom=allow_custom_providers,
+        registry=registry,
+    )
+    if allow_custom_providers:
+        errors.extend(provider_load_errors)
+    for name, comp in components.items():
+        if not isinstance(name, str) or not name.strip():
+            errors.append("Component names must be non-empty strings")
+            continue
+        if not isinstance(comp, dict):
+            continue
+        boundary = comp.get("boundary")
+        component_path = comp.get("path")
+        if not isinstance(boundary, dict) or not isinstance(component_path, str):
+            continue
+        provider_name = boundary_provider_name(boundary)
+        provider = get_provider(provider_name, registry=registry)
+        if provider is None:
+            if allow_custom_providers and provider_name.startswith("custom."):
+                errors.append(
+                    f"Component '{name}' provider '{provider_name}' was not registered "
+                    "by the configured provider module"
+                )
+            continue
+        if source == "working-tree" or provider_name.startswith("custom."):
+            for provider_error in validate_provider_config(
+                provider, boundary, component_path, repo_root
+            ):
+                errors.append(f"Component '{name}': {provider_error}")
+
     return errors
 
 
@@ -501,18 +682,45 @@ def config_warnings(config: dict, repo_root: Path) -> List[str]:
 
 
 def discover_components(repo_root: Path) -> Dict[str, dict]:
-    """Best-effort component discovery from common manifest files."""
-    manifests = ("package.json", "pyproject.toml", "Cargo.toml", "go.mod")
-    _ignored_dirs = {".git", "node_modules", "__pycache__", ".venv", "venv", "dist", "build"}
+    """Discover components from tracked manifests, with a bounded non-Git fallback."""
+    manifest_specs = (
+        ("package.json", "version"),
+        ("pyproject.toml", "project.version"),
+        ("Cargo.toml", "package.version"),
+        ("go.mod", None),
+    )
+    _ignored_dirs = {
+        ".git", "node_modules", "__pycache__", ".venv", "venv",
+        "dist", "build", "vendor",
+    }
     _MAX_DISCOVER = 1000  # Cap discovered components to prevent runaway on huge monorepos
     found: Dict[str, dict] = {}
-    for manifest in manifests:
-        for mf in sorted(repo_root.rglob(manifest)):
+    seen_directories: Set[str] = set()
+    try:
+        tracked = _git_run_bytes(repo_root, ["ls-files", "-z", "--"])
+        candidate_paths = [repo_root / p for p in _decode_nul_paths(tracked.stdout)]
+        if not candidate_paths:
+            try:
+                _git_run_bytes(repo_root, ["rev-parse", "--verify", "HEAD"])
+            except subprocess.CalledProcessError:
+                for manifest, _field in manifest_specs:
+                    candidate_paths.extend(repo_root.rglob(manifest))
+    except (OSError, subprocess.CalledProcessError):
+        candidate_paths = []
+        for manifest, _field in manifest_specs:
+            candidate_paths.extend(repo_root.rglob(manifest))
+
+    for manifest, version_field in manifest_specs:
+        for mf in sorted(p for p in candidate_paths if p.name == manifest):
             if _ignored_dirs & set(mf.relative_to(repo_root).parts):
                 continue
             rel_dir = mf.parent.relative_to(repo_root)
             if str(rel_dir) == ".":
                 continue
+            rel_path = _to_posix(str(rel_dir))
+            if rel_path in seen_directories:
+                continue
+            seen_directories.add(rel_path)
             comp_name = rel_dir.name
             base_name = comp_name
             idx = 2
@@ -520,9 +728,14 @@ def discover_components(repo_root: Path) -> Dict[str, dict]:
                 comp_name = f"{base_name}-{idx}"
                 idx += 1
             provider, paths = _detect_provider(mf.parent)
+            version_source = (
+                {"file": mf.name, "field": version_field}
+                if version_field is not None
+                else None
+            )
             found[comp_name] = {
-                "path": _to_posix(str(rel_dir)),
-                "version_source": {"file": mf.name, "field": "version"},
+                "path": rel_path,
+                "version_source": version_source,
                 "boundary": {"provider": provider, "paths": paths},
             }
             if len(found) >= _MAX_DISCOVER:
diff --git a/src/boundver/_diff.py b/src/boundver/_diff.py
index cc7820e..9aa6fd8 100644
--- a/src/boundver/_diff.py
+++ b/src/boundver/_diff.py
@@ -2,6 +2,8 @@
 
 from typing import Dict, List
 
+from ._lockfile import COMPONENT_METADATA_FIELDS
+
 
 def diff_lockfiles(old: dict, new: dict) -> dict:
     """Produce a human-readable diff between two lockfiles."""
@@ -40,14 +42,25 @@ def diff_lockfiles(old: dict, new: dict) -> dict:
                 nv = new_fp.get(facet)
                 if ov != nv:
                     changes[facet] = {"old": ov, "new": nv}
-            if changes:
+            metadata_changes: Dict[str, dict] = {}
+            for field in COMPONENT_METADATA_FIELDS:
+                old_value = old_entry.get(field)
+                new_value = new_entry.get(field)
+                if old_value != new_value:
+                    metadata_changes[field] = {"old": old_value, "new": new_value}
+            if changes or metadata_changes:
                 entry = {
                     "name": name,
                     "old_version": old_entry.get("version"),
                     "new_version": new_entry.get("version"),
                     "changed_facets": changes,
+                    "changed_metadata": metadata_changes,
                 }
-                entry["summary"] = _summarize_change(changes)
+                entry["summary"] = (
+                    _summarize_change(changes)
+                    if changes
+                    else "component metadata changed"
+                )
                 result["components"]["changed"].append(entry)
             else:
                 result["components"]["unchanged"].append(name)
@@ -90,11 +103,11 @@ def diff_lockfiles(old: dict, new: dict) -> dict:
 def _summarize_change(changes: dict) -> str:
     facets = list(changes.keys())
     if facets == ["exact"]:
-        return "implementation-only change (API stable)"
+        return "implementation-only by declaration: exact content changed; declared behavior and boundary artifacts are unchanged"
     elif set(facets) == {"exact", "behavior"}:
-        return "behavioral contract changed (API shape stable)"
+        return "behavioral artifacts changed; declared boundary artifacts are unchanged"
     elif "boundary" in facets and "compat" not in facets:
-        return "declared boundary changed (compatibility unchanged)"
+        return "declared boundary changed; compatibility family is unchanged"
     elif "compat" in facets:
-        return "BREAKING: compatibility family changed"
+        return "BREAKING-policy signal: declared compatibility family changed"
     return "changed: " + ", ".join(facets)
diff --git a/src/boundver/_git.py b/src/boundver/_git.py
index db3f1a9..5198a40 100644
--- a/src/boundver/_git.py
+++ b/src/boundver/_git.py
@@ -5,6 +5,11 @@
 from pathlib import Path
 from typing import Dict, List, Optional
 
+from ._utils import GuardrailError
+
+
+MAX_GIT_BLOB_BYTES = 50 * 1024 * 1024
+
 
 def git_root() -> Path:
     """Find the repository root."""
@@ -23,17 +28,29 @@ def _git_run(repo_root: Path, args: List[str]) -> subprocess.CompletedProcess:
     )
 
 
+def _git_run_bytes(repo_root: Path, args: List[str]) -> subprocess.CompletedProcess:
+    """Run Git with byte output for NUL-delimited, filename-safe commands."""
+    return subprocess.run(
+        ["git", "-C", str(repo_root), *args],
+        capture_output=True, text=False, check=True,
+    )
+
+
+def _decode_nul_paths(data: bytes) -> List[str]:
+    """Decode Git's NUL-delimited path output without C-quote mangling."""
+    return [os.fsdecode(raw) for raw in data.split(b"\0") if raw]
+
+
 def _git_cat_blob(repo_root: Path, ref: str) -> bytes:
     """Read a single git blob at the given ref as raw bytes (no text-mode CRLF conversion)."""
     result = subprocess.run(
         ["git", "-C", str(repo_root), "show", ref],
         capture_output=True, text=False, check=True,
     )
-    # Guardrail: reject blobs larger than the per-file limit (50 MiB).
-    _MAX_BLOB = 50 * 1024 * 1024
-    if len(result.stdout) > _MAX_BLOB:
-        raise ValueError(
-            f"Git blob too large ({len(result.stdout)} bytes) for ref {ref!r}"
+    if len(result.stdout) > MAX_GIT_BLOB_BYTES:
+        raise GuardrailError(
+            f"Hash guardrail exceeded: Git blob too large "
+            f"({len(result.stdout)} bytes) for ref {ref!r}"
         )
     return result.stdout
 
@@ -42,74 +59,106 @@ def _git_batch_cat(repo_root: Path, refs: List[str]) -> Dict[str, bytes]:
     """Batch-read multiple git objects via ``git cat-file --batch``.
 
     All objects are fetched in a single subprocess, replacing O(N) ``git show``
-    calls with O(1).  Returns ``{ref: raw_bytes}``.  Missing objects map to
-    ``b""``.  Raises ``subprocess.CalledProcessError`` on git failure.
+    calls with O(1).  Returns ``{ref: raw_bytes}``.  Missing, malformed,
+    truncated, non-blob, and oversized responses raise instead of being
+    confused with a valid empty blob.
     """
     if not refs:
         return {}
-    # Reject refs containing newlines — they would desynchronize the batch
-    # protocol (git uses newline as the request delimiter).
-    sanitized = []
+    # The widely supported batch protocol uses newline-delimited requests.
+    # Read the rare refs containing CR/LF individually so valid Git filenames
+    # never desynchronize the protocol.
+    batch_refs: List[str] = []
+    blobs: Dict[str, bytes] = {}
     for r in refs:
         if "\n" in r or "\r" in r:
-            raise ValueError(
-                f"git cat-file ref contains newline (possible filename with embedded newline): {r!r}"
-            )
-        sanitized.append(r)
-    inp = "\n".join(sanitized) + "\n"
+            try:
+                blobs[r] = _git_cat_blob(repo_root, r)
+            except subprocess.CalledProcessError as exc:
+                raise ValueError(
+                    f"Git blob not found for ref containing a newline: {r!r}"
+                ) from exc
+        else:
+            batch_refs.append(r)
+    if not batch_refs:
+        return blobs
+    inp = b"\n".join(os.fsencode(ref) for ref in batch_refs) + b"\n"
     proc = subprocess.run(
         ["git", "-C", str(repo_root), "cat-file", "--batch"],
-        input=inp.encode("utf-8"),
+        input=inp,
         capture_output=True,
     )
     if proc.returncode != 0:
         raise subprocess.CalledProcessError(
             proc.returncode, ["git", "cat-file", "--batch"], proc.stderr
         )
-    blobs: Dict[str, bytes] = {}
     data = proc.stdout
     pos = 0
-    for i, ref in enumerate(refs):
+    for ref in batch_refs:
         try:
             nl = data.index(b"\n", pos)
-        except ValueError:
-            # Truncated output — remaining refs get empty bytes.
-            for remaining in refs[i:]:
-                blobs.setdefault(remaining, b"")
-            break
+        except ValueError as exc:
+            raise ValueError(
+                f"Truncated git cat-file response before header for {ref!r}"
+            ) from exc
         header = data[pos:nl].decode("ascii", errors="replace")
         pos = nl + 1
         # Header format: "<ref> SP <type> SP <size>" or "<ref> SP missing".
         # Refs may contain spaces (e.g. paths with spaces), so split from the
         # right where we know the fixed-format suffix lives.
         if header.endswith(" missing"):
-            blobs[ref] = b""
-            continue
+            raise ValueError(f"Git blob not found for ref {ref!r}")
         # Expect "<ref> <type> <size>" — size is always the last token.
         last_space = header.rfind(" ")
         if last_space < 0:
-            blobs[ref] = b""
-            continue
+            raise ValueError(
+                f"Malformed git cat-file header for {ref!r}: {header!r}"
+            )
+        type_space = header.rfind(" ", 0, last_space)
+        if type_space < 0:
+            raise ValueError(
+                f"Malformed git cat-file header for {ref!r}: {header!r}"
+            )
+        object_type = header[type_space + 1:last_space]
+        if object_type != "blob":
+            raise ValueError(
+                f"Expected a Git blob for {ref!r}, got {object_type!r}"
+            )
         try:
             size = int(header[last_space + 1:])
-        except ValueError:
-            # Cannot determine content size; stream is now desynchronized.
-            for remaining in refs[i:]:
-                blobs.setdefault(remaining, b"")
-            break
-        # Guardrail: skip objects exceeding per-file limit.
-        _MAX_BLOB = 50 * 1024 * 1024
-        if size > _MAX_BLOB:
-            blobs[ref] = b""
-            pos += size + 1
-            continue
-        blobs[ref] = data[pos : pos + size]
-        pos += size + 1  # skip trailing LF after content
+        except ValueError as exc:
+            raise ValueError(
+                f"Malformed git cat-file size for {ref!r}: {header!r}"
+            ) from exc
+        if size < 0:
+            raise ValueError(f"Negative git blob size for {ref!r}: {size}")
+        if size > MAX_GIT_BLOB_BYTES:
+            raise GuardrailError(
+                f"Hash guardrail exceeded: Git blob too large "
+                f"({size} bytes) for ref {ref!r}"
+            )
+        end = pos + size
+        if end >= len(data):
+            raise ValueError(
+                f"Truncated git cat-file content for {ref!r}: "
+                f"expected {size} bytes"
+            )
+        blobs[ref] = data[pos:end]
+        if data[end:end + 1] != b"\n":
+            raise ValueError(
+                f"Malformed git cat-file terminator for {ref!r}"
+            )
+        pos = end + 1
+    if pos != len(data):
+        raise ValueError("Unexpected trailing data from git cat-file --batch")
     return blobs
 
 
 def _to_posix(rel_path: str) -> str:
-    return rel_path.replace("\\", "/")
+    # ``Path.as_posix`` converts native Windows separators while preserving a
+    # literal backslash in a POSIX filename. A blind string replacement would
+    # collapse two distinct Git paths on POSIX.
+    return Path(rel_path).as_posix()
 
 
 def _is_ignored(path: Path) -> bool:
@@ -247,11 +296,14 @@ def _matches_gitignore(rel_path: str, patterns: "_GitignoreRules") -> bool:
 def list_head_files(repo_root: Path, path: str) -> List[str]:
     """List files at a repo-relative path as represented in HEAD."""
     try:
-        result = _git_run(repo_root, ["ls-tree", "-r", "--name-only", "HEAD", path])
+        result = _git_run_bytes(
+            repo_root,
+            ["--literal-pathspecs", "ls-tree", "-r", "-z", "--name-only", "HEAD", "--", path],
+        )
     except subprocess.CalledProcessError:
         return []
 
-    files = [_to_posix(line.strip()) for line in result.stdout.splitlines() if line.strip()]
+    files = _decode_nul_paths(result.stdout)
     if files:
         return files
 
@@ -265,32 +317,53 @@ def list_head_files(repo_root: Path, path: str) -> List[str]:
 def _list_files_for_source(repo_root: Path, repo_rel_path: str, source: str) -> List[str]:
     if source == "head":
         return list_head_files(repo_root, repo_rel_path)
-    args = ["ls-files"]
-    if source == "index":
-        args.append("--cached")
-    else:
-        # working-tree: include tracked AND untracked (but not ignored) files,
-        # but exclude deleted tracked files (--deleted lists them for removal).
-        args.extend(["--cached", "--others", "--exclude-standard"])
+    # Index and working-tree use the same tracked file set.  The selected
+    # source only controls whether content comes from the index or from disk.
+    args = ["--literal-pathspecs", "ls-files", "--cached", "-z"]
     args.extend(["--", repo_rel_path])
     try:
-        result = _git_run(repo_root, args)
+        result = _git_run_bytes(repo_root, args)
     except subprocess.CalledProcessError:
-        result_files: List[str] = []
+        if source == "index":
+            raise
+        # Do not turn a Git failure inside a real repository into an
+        # approximate filesystem fingerprint. Fallback is reserved for
+        # non-Git/unborn first-run environments.
+        try:
+            _git_run(repo_root, ["rev-parse", "--git-dir"])
+        except subprocess.CalledProcessError:
+            git_failed = True
+            result_files: List[str] = []
+        else:
+            raise
     else:
-        result_files = [_to_posix(line.strip()) for line in result.stdout.splitlines() if line.strip()]
+        git_failed = False
+        result_files = _decode_nul_paths(result.stdout)
 
     # For working-tree source, exclude files that are tracked but deleted on disk.
     if result_files and source == "working-tree":
-        result_files = [f for f in result_files if (repo_root / f).exists()]
-
-    if result_files:
+        result_files = [
+            f
+            for f in result_files
+            if (repo_root / f).exists() or (repo_root / f).is_symlink()
+        ]
+
+    # An empty successful result is authoritative (for example, a legitimate
+    # empty index). The one usability exception is an unborn repository in
+    # working-tree mode: before the first commit there is no tracked-file view,
+    # so use the bounded filesystem fallback to support initial setup.
+    if not result_files and source == "working-tree":
+        try:
+            _git_run(repo_root, ["rev-parse", "--verify", "HEAD"])
+        except subprocess.CalledProcessError:
+            git_failed = True
+    if not git_failed:
         return result_files
 
     # Fallback for non-git test/runtime environments: local filesystem enumeration.
     import sys as _sys
     print(
-        "WARNING: git file listing returned no results; falling back to filesystem enumeration. "
+        "WARNING: git file listing failed; falling back to filesystem enumeration. "
         "Fingerprints may differ from git-based computation.",
         file=_sys.stderr,
     )
@@ -306,6 +379,9 @@ def _list_files_for_source(repo_root: Path, repo_rel_path: str, source: str) ->
         if not f.is_file():
             continue
         rel = _to_posix(str(f.relative_to(repo_root)))
+        rel_parts = Path(rel).parts
+        if any(_is_ignored(Path(part)) for part in rel_parts):
+            continue
         if gitignore_patterns is not None:
             if _matches_gitignore(rel, gitignore_patterns):
                 continue
@@ -341,29 +417,55 @@ def git_latest_tag(repo_root: Path, prefix: str) -> Optional[str]:
 def changed_components_since_ref(config: dict, repo_root: Path, base_ref: str) -> List[str]:
     """Return component names with tracked changes since `base_ref`."""
     if not base_ref or not base_ref.strip():
-        return []
+        raise ValueError("--changed-from requires a non-empty Git ref")
     ref = base_ref.strip()
     if ref.startswith("-"):
-        return []
+        raise ValueError(f"Invalid Git ref: {ref!r}")
     try:
-        result = _git_run(repo_root, ["diff", "--name-only", ref, "--"])
-    except subprocess.CalledProcessError:
-        import sys as _sys
-        print(
-            f"WARNING: git diff failed for ref {ref!r}; assuming no changes.",
-            file=_sys.stderr,
-        )
-        return []
-    changed_files = [_to_posix(line.strip()) for line in result.stdout.splitlines() if line.strip()]
+        _git_run(repo_root, ["rev-parse", "--verify", f"{ref}^{{commit}}"])
+        result = _git_run_bytes(repo_root, ["diff", "--name-only", "-z", ref, "--"])
+    except subprocess.CalledProcessError as exc:
+        raise ValueError(f"Unable to diff from Git ref {ref!r}") from exc
+    changed_files = _decode_nul_paths(result.stdout)
     changed: List[str] = []
-    for cname, comp in config.get("components", {}).items():
-        cpath = _to_posix(str(comp.get("path", "")).rstrip("/"))
-        if not cpath:
+    config_names = {
+        "boundary.config.json", "boundary.config.yaml", "boundary.config.yml",
+        "boundary.config.toml",
+    }
+    if any(Path(f).name in config_names for f in changed_files):
+        return sorted(config.get("components", {}))
+    tag_versioned = {
+        name
+        for name, component in config.get("components", {}).items()
+        if isinstance(component, dict)
+        and isinstance(component.get("version_source"), dict)
+        and "git_tag_prefix" in component["version_source"]
+    }
+    components = config.get("components", {})
+    matched_files: set = set()
+    for cname, comp in components.items():
+        raw_path = str(comp.get("path", "")).strip()
+        cpath = _to_posix(os.path.normpath(raw_path)) if raw_path else ""
+        if cpath in {"", "."}:
+            if changed_files:
+                changed.append(cname)
+                matched_files.update(changed_files)
             continue
         prefix = f"{cpath}/"
-        if any(f == cpath or f.startswith(prefix) for f in changed_files):
+        component_matches = {
+            f for f in changed_files if f == cpath or f.startswith(prefix)
+        }
+        if component_matches:
             changed.append(cname)
-    return sorted(changed)
+            matched_files.update(component_matches)
+
+    # A changed path outside every currently configured component may be a
+    # deleted/moved component or another config input.  Selecting everything is
+    # conservative, but avoids a false-clean result when the old path is no
+    # longer available to map precisely.
+    if changed_files and matched_files != set(changed_files):
+        return sorted(components)
+    return sorted(set(changed) | tag_versioned)
 
 
 def dirty_component_paths(repo_root: Path, component_paths: List[str]) -> List[str]:
@@ -373,27 +475,29 @@ def dirty_component_paths(repo_root: Path, component_paths: List[str]) -> List[s
     modified locally.
     """
     try:
-        result = _git_run(repo_root, ["status", "--porcelain", "-u", "--"])
+        result = _git_run_bytes(
+            repo_root,
+            ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--"],
+        )
     except subprocess.CalledProcessError:
         return []
-    dirty_files = []
-    for line in result.stdout.splitlines():
-        if len(line) > 3:
-            # porcelain format: XY <path> or XY <old> -> <new>
-            fpath = line[3:].split(" -> ")[-1].strip()
-            if fpath.startswith('"') and fpath.endswith('"'):
-                # Git C-quotes: octal escapes represent raw bytes (usually UTF-8).
-                try:
-                    fpath = (
-                        fpath[1:-1]
-                        .encode("utf-8")
-                        .decode("unicode_escape")
-                        .encode("latin-1")
-                        .decode("utf-8")
-                    )
-                except (UnicodeDecodeError, UnicodeEncodeError):
-                    fpath = fpath[1:-1]
-            dirty_files.append(_to_posix(fpath))
+    records = [raw for raw in result.stdout.split(b"\0") if raw]
+    dirty_files: List[str] = []
+    index = 0
+    while index < len(records):
+        record = records[index]
+        if len(record) < 3:
+            raise ValueError("Malformed NUL-delimited git status output")
+        status = record[:2]
+        if record[2:3] != b" ":
+            raise ValueError("Malformed NUL-delimited git status output")
+        dirty_files.append(os.fsdecode(record[3:]))
+        if b"R" in status or b"C" in status:
+            index += 1
+            if index >= len(records):
+                raise ValueError("Truncated rename in git status output")
+            dirty_files.append(os.fsdecode(records[index]))
+        index += 1
     dirty: List[str] = []
     for cpath in component_paths:
         cpath_norm = cpath.rstrip("/")
diff --git a/src/boundver/_hashing.py b/src/boundver/_hashing.py
index 1775b7d..b10bb18 100644
--- a/src/boundver/_hashing.py
+++ b/src/boundver/_hashing.py
@@ -3,23 +3,29 @@
 import hashlib
 import json
 import os
+import struct
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Iterable, List, Optional, Tuple
 
 from ._git import (
     _git_batch_cat,
     _git_cat_blob,
     _list_files_for_source,
-    _to_posix,
-)
-from ._utils import (
-    GuardrailError,
-    _is_within,
 )
+from ._utils import GuardrailError, _is_within
 
 MAX_HASH_FILES = 50000
 MAX_HASH_FILE_BYTES = 50 * 1024 * 1024  # 50 MiB per file guardrail
 
+# ``boundary-lock/v1`` originally concatenated labels and content without
+# lengths.  That allowed one file's content to be interpreted as the framing
+# for another file.  v2 uses an explicit magic value, a purpose-specific
+# domain, an entry count, and uint64 lengths for every variable-size field.
+HASH_FRAME_VERSION = "boundver-hash/v2"
+HASH_DOMAIN_EXACT = "exact-tree"
+HASH_DOMAIN_CONTENT_ONLY = "content-only-tree"
+HASH_DOMAIN_BOUNDARY = "boundary"
+
 
 def canonical_json(obj) -> str:
     """Deterministic JSON for hashing. Sorted keys, compact separators."""
@@ -30,6 +36,57 @@ def sha256_hex(data: str) -> str:
     return hashlib.sha256(data.encode("utf-8")).hexdigest()
 
 
+def _u64(value: int) -> bytes:
+    """Encode a non-negative integer for the v2 hashing wire format."""
+    if value < 0 or value >= 2 ** 64:
+        raise ValueError(f"Hash frame length is out of range: {value}")
+    return struct.pack(">Q", value)
+
+
+def _hash_framed_entries(
+    entries: Iterable[Tuple[str, bytes]],
+    *,
+    domain: str,
+) -> str:
+    """Hash labeled byte entries using the unambiguous v2 wire format.
+
+    ``domain`` separates hashes produced for different purposes (for example,
+    an exact tree and a provider boundary) even when their entries happen to
+    be identical.  Sorting by encoded label and then content makes the helper
+    deterministic for every caller, including boundary providers.
+    """
+    domain_bytes = domain.encode("utf-8")
+    prepared: List[Tuple[bytes, bytes]] = []
+    for label, content in entries:
+        if not isinstance(label, str):
+            raise TypeError("Hash entry labels must be strings")
+        if not isinstance(content, bytes):
+            raise TypeError("Hash entry content must be bytes")
+        prepared.append((label.encode("utf-8", errors="surrogateescape"), content))
+    prepared.sort(key=lambda entry: (entry[0], entry[1]))
+
+    digest = hashlib.sha256()
+    magic = HASH_FRAME_VERSION.encode("ascii")
+    digest.update(_u64(len(magic)))
+    digest.update(magic)
+    digest.update(_u64(len(domain_bytes)))
+    digest.update(domain_bytes)
+    digest.update(_u64(len(prepared)))
+    for label_bytes, content in prepared:
+        digest.update(_u64(len(label_bytes)))
+        digest.update(label_bytes)
+        digest.update(_u64(len(content)))
+        digest.update(content)
+    return digest.hexdigest()
+
+
+def _normalize_hash_content(content: bytes) -> bytes:
+    """Canonicalize text line endings consistently across source modes."""
+    if b"\r\n" in content and b"\x00" not in content:
+        return content.replace(b"\r\n", b"\n")
+    return content
+
+
 def _enforce_hash_guardrails(full_path: Path, file_count: int) -> None:
     if file_count > MAX_HASH_FILES:
         raise GuardrailError(f"Hash guardrail exceeded: >{MAX_HASH_FILES} files")
@@ -44,11 +101,11 @@ def _enforce_content_size(content: bytes, path_label: str) -> None:
 
 
 def _read_path_content(repo_root: Path, full_path: Path, source: str) -> bytes:
-    rel = _to_posix(str(full_path.relative_to(repo_root)))
+    rel = full_path.relative_to(repo_root).as_posix()
     if source == "index":
-        return _git_cat_blob(repo_root, f":{rel}")
+        return _normalize_hash_content(_git_cat_blob(repo_root, f":{rel}"))
     if source == "head":
-        return _git_cat_blob(repo_root, f"HEAD:{rel}")
+        return _normalize_hash_content(_git_cat_blob(repo_root, f"HEAD:{rel}"))
     if full_path.is_symlink():
         # Hash symlink link-target text (matches what Git stores for symlink blobs).
         try:
@@ -57,49 +114,54 @@ def _read_path_content(repo_root: Path, full_path: Path, source: str) -> bytes:
             raise ValueError(
                 f"Cannot read symlink at {full_path.relative_to(repo_root)}: {exc}"
             ) from exc
-        return target.encode("utf-8") if isinstance(target, str) else target
+        encoded = target.encode("utf-8") if isinstance(target, str) else target
+        return _normalize_hash_content(encoded)
     try:
         sz = full_path.stat().st_size
         if sz > MAX_HASH_FILE_BYTES:
-            raise ValueError(
+            raise GuardrailError(
                 f"Hash guardrail exceeded: file too large ({sz} bytes) at "
                 f"{full_path.relative_to(repo_root)}"
             )
         raw = full_path.read_bytes()
-    except FileNotFoundError:
-        # File was listed (e.g. by ls-files) but removed before read — treat as empty.
-        return b""
-    # Normalize CRLF → LF so working-tree hashes match what git stores (git strips CR on commit).
-    # This keeps fingerprints stable across platforms and git autocrlf configurations.
-    if b"\r\n" in raw and b"\x00" not in raw:
-        raw = raw.replace(b"\r\n", b"\n")
-    return raw
+    except FileNotFoundError as exc:
+        # A listed file disappearing is an incomplete snapshot, not an empty
+        # file.  Failing closed prevents a transient race from being blessed.
+        raise ValueError(
+            f"File disappeared while hashing: {full_path.relative_to(repo_root)}"
+        ) from exc
+    _enforce_content_size(raw, rel)
+    return _normalize_hash_content(raw)
 
 
 def source_tree_digest(repo_root: Path, path: str, source: str = "head") -> Optional[str]:
     """Canonical SHA-256 digest for a path from HEAD, index, or working tree."""
+    if source not in {"head", "index", "working-tree"}:
+        raise ValueError(f"Unknown source mode: {source!r}")
     files = sorted(_list_files_for_source(repo_root, path, source))
     if not files:
         return None
     for i, rel in enumerate(files):
         _enforce_hash_guardrails(repo_root / rel, i + 1)
-    content_parts: List[bytes] = []
+    entries: List[Tuple[str, bytes]] = []
     if source in ("head", "index"):
         obj_prefix = "HEAD:" if source == "head" else ":"
         refs = [f"{obj_prefix}{rel}" for rel in files]
         blobs = _git_batch_cat(repo_root, refs)
         for rel, ref in zip(files, refs):
-            content = blobs.get(ref, b"")
+            content = _normalize_hash_content(blobs[ref])
             _enforce_content_size(content, rel)
-            content_parts.append(f"file:{rel}\n".encode("utf-8"))
-            content_parts.append(content)
+            entries.append((f"file:{rel}", content))
     else:
         for rel in files:
             content = _read_path_content(repo_root, repo_root / rel, source)
             _enforce_content_size(content, rel)
-            content_parts.append(f"file:{rel}\n".encode("utf-8"))
-            content_parts.append(content)
-    return hashlib.sha256(b"".join(content_parts)).hexdigest() if content_parts else None
+            entries.append((f"file:{rel}", content))
+    return (
+        _hash_framed_entries(entries, domain=HASH_DOMAIN_EXACT)
+        if entries
+        else None
+    )
 
 
 def _content_only_digest(repo_root: Path, path: str, source: str = "head") -> Optional[str]:
@@ -108,6 +170,8 @@ def _content_only_digest(repo_root: Path, path: str, source: str = "head") -> Op
     Used for vendored copy comparison so the same files at different repo paths
     hash identically when their content is identical.
     """
+    if source not in {"head", "index", "working-tree"}:
+        raise ValueError(f"Unknown source mode: {source!r}")
     files = _list_files_for_source(repo_root, path, source)
     if not files:
         return None
@@ -115,28 +179,30 @@ def _content_only_digest(repo_root: Path, path: str, source: str = "head") -> Op
     sorted_files = sorted(files)
     for i, repo_rel in enumerate(sorted_files):
         _enforce_hash_guardrails(repo_root / repo_rel, i + 1)
-    content_parts: List[bytes] = []
+    entries: List[Tuple[str, bytes]] = []
     if source in ("head", "index"):
         obj_prefix = "HEAD:" if source == "head" else ":"
         refs = [f"{obj_prefix}{repo_rel}" for repo_rel in sorted_files]
         blobs = _git_batch_cat(repo_root, refs)
         for repo_rel, ref in zip(sorted_files, refs):
             try:
-                local_rel = _to_posix(str(Path(repo_rel).relative_to(base)))
+                local_rel = Path(repo_rel).relative_to(base).as_posix()
             except ValueError:
-                local_rel = _to_posix(repo_rel)
-            content = blobs.get(ref, b"")
+                local_rel = repo_rel
+            content = _normalize_hash_content(blobs[ref])
             _enforce_content_size(content, repo_rel)
-            content_parts.append(f"file:{local_rel}\n".encode("utf-8"))
-            content_parts.append(content)
+            entries.append((f"file:{local_rel}", content))
     else:
         for repo_rel in sorted_files:
             try:
-                local_rel = _to_posix(str(Path(repo_rel).relative_to(base)))
+                local_rel = Path(repo_rel).relative_to(base).as_posix()
             except ValueError:
-                local_rel = _to_posix(repo_rel)
+                local_rel = repo_rel
             content = _read_path_content(repo_root, repo_root / repo_rel, source)
             _enforce_content_size(content, repo_rel)
-            content_parts.append(f"file:{local_rel}\n".encode("utf-8"))
-            content_parts.append(content)
-    return hashlib.sha256(b"".join(content_parts)).hexdigest() if content_parts else None
+            entries.append((f"file:{local_rel}", content))
+    return (
+        _hash_framed_entries(entries, domain=HASH_DOMAIN_CONTENT_ONLY)
+        if entries
+        else None
+    )
diff --git a/src/boundver/_lockfile.py b/src/boundver/_lockfile.py
index c338dd3..b1c1dd7 100644
--- a/src/boundver/_lockfile.py
+++ b/src/boundver/_lockfile.py
@@ -4,7 +4,7 @@
 import os
 import subprocess
 from pathlib import Path
-from typing import Dict, List, Optional, Union
+from typing import Dict, List, Optional, Set, Union
 
 from ._git import _git_cat_blob, _list_files_for_source, _to_posix, git_latest_tag
 from ._hashing import (
@@ -16,24 +16,57 @@
     source_tree_digest,
 )
 from ._utils import _short, boundary_provider_name, ConfigError, GuardrailError, ProviderError, SourceMode
-from .providers import PathHashProvider, ProviderContext, compute_boundary, get_provider, load_custom_providers
+from .providers import (
+    PathHashProvider,
+    ProviderContext,
+    compute_boundary,
+    create_registry,
+    get_provider,
+    load_custom_providers,
+)
 from .versions import extract_version, parse_semver
 
-LOCKFILE_SCHEMA = "boundary-lock/v1"
+LOCKFILE_SCHEMA = "boundary-lock/v2"
 LOCKFILE_SCHEMA_URL = "https://raw.githubusercontent.com/yzm1/boundver/main/spec/boundary.lock.schema.json"
 
+# Persisted fields whose integrity matters independently of the four digests.
+# Keep this list shared by verify/diff/why so none of those views can report a
+# stale entry as current merely because its fingerprints happen to match.
+COMPONENT_METADATA_FIELDS = (
+    "version", "path", "boundary_provider", "boundary_provider_version",
+    "boundary_status", "semver", "consumers", "boundary_metadata",
+    "version_errors", "exact_errors", "behavior_errors", "boundary_errors", "warnings",
+    "vendored_copies", "vendored_digests",
+)
+
+
+def _normalize_source(source: Union[str, SourceMode]) -> str:
+    value = source.value if isinstance(source, SourceMode) else source
+    if value not in {"head", "index", "working-tree"}:
+        raise ConfigError(
+            f"Unknown source mode {value!r}; expected head, index, or working-tree"
+        )
+    return value
+
 
 def generate_lockfile(
     config: dict, repo_root: Path, source: Union[str, SourceMode] = "head", strict: bool = True,
     allow_custom_providers: bool = False,
 ) -> dict:
     """Generate the full lockfile from config + repo state."""
+    source = _normalize_source(source)
+    if not isinstance(config, dict):
+        raise ConfigError("Config root must be an object")
+    components_config = config.get("components")
+    if not isinstance(components_config, dict) or not components_config:
+        raise ConfigError("Config must define at least one component")
+    registry = create_registry()
     provider_errors = load_custom_providers(
-        config.get("providers", []), allow_custom=allow_custom_providers
+        config.get("providers", []), allow_custom=allow_custom_providers,
+        registry=registry,
     )
     if provider_errors:
         raise ProviderError("Custom provider loading failed:\n" + "\n".join(provider_errors))
-    components_config = config["components"]
     slices_config = config.get("slices", {})
     defaults = config.get("defaults", {})
 
@@ -50,7 +83,13 @@ def generate_lockfile(
     # --- Components ---
     for name, comp in components_config.items():
         lockfile["components"][name] = _compute_component_entry(
-            name, comp, repo_root, source, defaults, accessor,
+            name, comp, repo_root, source, defaults, accessor, registry,
+        )
+
+    generation_errors = _generation_errors(lockfile)
+    if strict and generation_errors:
+        raise ConfigError(
+            "Lockfile generation failed:\n" + "\n".join(generation_errors)
         )
 
     # --- Slices ---
@@ -71,7 +110,7 @@ class _SourceAccessor:
 
     def __init__(self, repo_root: Path, source: str):
         self.repo_root = repo_root
-        self.source = source
+        self.source = _normalize_source(source)
 
     def read_file(self, repo_rel: str) -> bytes:
         """Read file content for hashing."""
@@ -108,6 +147,16 @@ def version_read_file(self, repo_rel: str) -> bytes:
             return _git_cat_blob(self.repo_root, f":{repo_rel}")
         else:
             fpath = self.repo_root / repo_rel
+            if fpath.is_symlink():
+                raise ConfigError(
+                    f"Version source must not be a symlink: {repo_rel}"
+                )
+            try:
+                fpath.resolve().relative_to(self.repo_root.resolve())
+            except (ValueError, OSError) as exc:
+                raise ConfigError(
+                    f"Version source escapes repository: {repo_rel}"
+                ) from exc
             size = fpath.stat().st_size
             if size > MAX_HASH_FILE_BYTES:
                 raise GuardrailError(
@@ -127,17 +176,26 @@ def _compute_component_entry(
     source: str,
     defaults: dict,
     accessor: "_SourceAccessor",
+    registry: Optional[dict] = None,
 ) -> dict:
     """Compute the lockfile entry for a single component."""
     raw_path = comp.get("path")
     if not isinstance(raw_path, str) or not raw_path.strip():
         raise ConfigError(f"Component '{name}' has invalid or missing 'path'")
-    comp_path = raw_path.rstrip("/")
+    comp_path = _to_posix(os.path.normpath(raw_path.strip()))
     version = extract_version(
         repo_root, comp_path, comp.get("version_source"), git_latest_tag,
         read_file_fn=accessor.version_read_file,
     )
     compat, api_ver, exact_ver = parse_semver(version)
+    version_errors: List[str] = []
+    if comp.get("version_source") is not None:
+        if version is None:
+            version_errors.append("Configured version source did not produce a version")
+        elif compat is None:
+            version_errors.append(
+                f"Configured version is not valid SemVer: {version!r}"
+            )
     compat_mode = defaults.get("compat_mode", "major")
 
     # Exact fingerprint: git tree hash of the whole component directory
@@ -160,7 +218,8 @@ def _compute_component_entry(
     # API fingerprint: resolve via registered provider
     boundary = comp.get("boundary", {})
     bp_name = boundary_provider_name(boundary)
-    provider = get_provider(bp_name)
+    provider = get_provider(bp_name, registry=registry)
+    provider_metadata = None
     if provider is None:
         api_digest = None
         boundary_status = "error"
@@ -175,11 +234,14 @@ def _compute_component_entry(
             list_files=accessor.list_files,
         )
         try:
-            api_digest, boundary_status, boundary_errors = compute_boundary(provider, ctx)
+            api_digest, boundary_status, boundary_errors, provider_metadata = compute_boundary(
+                provider, ctx, include_metadata=True
+            )
         except (OSError, subprocess.CalledProcessError, ValueError) as exc:
             api_digest = None
             boundary_status = "error"
             boundary_errors = [f"Boundary digest failed: {exc}"]
+            provider_metadata = None
 
     # Behavior fingerprint: broader contract files (superset of boundary)
     behavior_cfg = comp.get("behavior")
@@ -197,9 +259,12 @@ def _compute_component_entry(
         )
         try:
             behavior_digest, _bstatus, _berrs = compute_boundary(behavior_provider, behavior_ctx)
+            behavior_errors = list(_berrs) if _bstatus == "error" else []
         except (OSError, subprocess.CalledProcessError, ValueError) as exc:
             behavior_digest = None
-            boundary_errors.append(f"behavior computation failed: {exc}")
+            behavior_errors = [f"Behavior digest failed: {exc}"]
+    else:
+        behavior_errors = []
 
     # Compatibility fingerprint: derived from semver major (or major.minor)
     compat_digest = None
@@ -218,6 +283,7 @@ def _compute_component_entry(
         "boundary_provider": bp_name,
         "boundary_provider_version": getattr(provider, "version", "1") if provider else None,
         "boundary_status": boundary_status,
+        "consumers": sorted(set(comp.get("consumers", []))),
         "fingerprints": {
             "exact": exact_digest,
             "behavior": behavior_digest,
@@ -232,8 +298,14 @@ def _compute_component_entry(
     }
     if boundary_errors:
         entry["boundary_errors"] = boundary_errors
+    if provider_metadata is not None:
+        entry["boundary_metadata"] = provider_metadata
+    if version_errors:
+        entry["version_errors"] = version_errors
     if exact_errors:
         entry["exact_errors"] = exact_errors
+    if behavior_errors:
+        entry["behavior_errors"] = behavior_errors
 
     # Flag vendored copies
     if "vendored_copies" in comp:
@@ -250,6 +322,23 @@ def _compute_component_entry(
     return entry
 
 
+def _generation_errors(lockfile: dict) -> List[str]:
+    """Return fingerprint computation failures that make a lock unsafe to bless."""
+    errors: List[str] = []
+    for name, entry in lockfile.get("components", {}).items():
+        for message in entry.get("version_errors", []):
+            errors.append(f"{name}: {message}")
+        for message in entry.get("exact_errors", []):
+            errors.append(f"{name}: {message}")
+        for message in entry.get("behavior_errors", []):
+            errors.append(f"{name}: {message}")
+        if entry.get("boundary_status") == "error":
+            messages = entry.get("boundary_errors", []) or ["Boundary computation failed"]
+            for message in messages:
+                errors.append(f"{name}: {message}")
+    return errors
+
+
 def _recompute_slice_entry(
     slice_name: str,
     slice_def: dict,
@@ -300,35 +389,59 @@ def generate_lockfile_for_components(
     allow_custom_providers: bool = False,
 ) -> dict:
     """Generate/update lockfile only for selected components and impacted slices."""
+    source = _normalize_source(source)
     selected = sorted(set(selected_components))
     components_cfg = config.get("components", {})
     missing = [n for n in selected if n not in components_cfg]
     if missing:
         raise ConfigError(f"Unknown component(s): {', '.join(missing)}")
 
-    subset_config = dict(config)
-    subset_config["components"] = {n: components_cfg[n] for n in selected}
-    subset_config["slices"] = {}
-    subset_lock = generate_lockfile(
-        subset_config, repo_root, source=source, strict=strict,
+    if not out_path.exists():
+        raise ConfigError(
+            "Cannot generate a component subset without an existing v2 lockfile. "
+            "Run a full `boundver generate` first."
+        )
+    try:
+        merged = json.loads(out_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ConfigError(
+            f"Existing lockfile at {out_path} is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(merged, dict):
+        raise ConfigError(
+            f"Existing lockfile at {out_path} must contain a JSON object"
+        )
+    if merged.get("schema") != LOCKFILE_SCHEMA:
+        raise ConfigError(
+            f"Cannot partially update schema {merged.get('schema')!r}; "
+            f"run a full `boundver generate` to create {LOCKFILE_SCHEMA}."
+        )
+    structure_issues = _lockfile_structure_issues(merged)
+    if structure_issues:
+        raise ConfigError(
+            "Cannot partially update a malformed lockfile:\n"
+            + "\n".join(structure_issues)
+        )
+    if merged.get("project") != config.get("project", "unknown"):
+        raise ConfigError(
+            "Cannot partially update after the project name changed. "
+            "Run a full `boundver generate`."
+        )
+
+    # Recompute every component before merging. This makes component-scoped
+    # generation an output-selection convenience, not a way to preserve stale
+    # digests after config/default/provider changes.
+    current_lock = generate_lockfile(
+        config, repo_root, source=source, strict=strict,
         allow_custom_providers=allow_custom_providers,
     )
-
-    if out_path.exists():
-        try:
-            merged = json.loads(out_path.read_text(encoding="utf-8"))
-        except json.JSONDecodeError as exc:
+    for name in set(components_cfg) - set(selected):
+        if merged.get("components", {}).get(name) != current_lock["components"][name]:
             raise ConfigError(
-                f"Existing lockfile at {out_path} is not valid JSON: {exc}"
-            ) from exc
-    else:
-        merged = {
-            "$schema": LOCKFILE_SCHEMA_URL,
-            "schema": LOCKFILE_SCHEMA,
-            "project": config.get("project", "unknown"),
-            "components": {},
-            "slices": {},
-        }
+                f"Cannot partially generate because unselected component '{name}' "
+                "is stale. Run a full `boundver generate`."
+            )
+    merged["$schema"] = LOCKFILE_SCHEMA_URL
     merged["schema"] = LOCKFILE_SCHEMA
     merged["project"] = config.get("project", "unknown")
     if not isinstance(merged.get("components"), dict):
@@ -337,19 +450,39 @@ def generate_lockfile_for_components(
         merged["slices"] = {}
 
     for name in selected:
-        merged["components"][name] = subset_lock["components"][name]
+        merged["components"][name] = current_lock["components"][name]
+
+    # A partial refresh must still reconcile config removals and every slice.
+    configured_names = set(components_cfg)
+    merged["components"] = {
+        name: entry
+        for name, entry in merged["components"].items()
+        if name in configured_names
+    }
+    missing_entries = sorted(configured_names - set(merged["components"]))
+    if missing_entries:
+        raise ConfigError(
+            "Cannot partially generate because the existing lockfile has no entry for: "
+            + ", ".join(missing_entries)
+            + ". Run a full `boundver generate`."
+        )
 
+    merged["slices"] = {}
     for sname, sdef in config.get("slices", {}).items():
-        slice_components = sdef.get("components", [])
-        if any(c in selected for c in slice_components):
-            merged["slices"][sname] = _recompute_slice_entry(
-                sname, sdef, merged["components"], strict=strict
-            )
+        merged["slices"][sname] = _recompute_slice_entry(
+            sname, sdef, merged["components"], strict=strict
+        )
+
+    errors = _generation_errors(merged)
+    if strict and errors:
+        raise ConfigError("Lockfile generation failed:\n" + "\n".join(errors))
 
     return merged
 
 
 def _lockfile_schema_issues(lockfile: dict) -> List[str]:
+    if not isinstance(lockfile, dict):
+        return ["LOCKFILE malformed: root must be an object"]
     schema = lockfile.get("schema")
     if schema is None:
         return [f"LOCKFILE schema missing (expected {LOCKFILE_SCHEMA})"]
@@ -360,6 +493,10 @@ def _lockfile_schema_issues(lockfile: dict) -> List[str]:
 
 def _lockfile_structure_issues(lockfile: dict) -> List[str]:
     issues: List[str] = []
+    if not isinstance(lockfile, dict):
+        return ["LOCKFILE malformed: root must be an object"]
+    if not isinstance(lockfile.get("project"), str) or not lockfile.get("project"):
+        issues.append("LOCKFILE malformed: project must be a non-empty string")
     if not isinstance(lockfile.get("components"), dict):
         issues.append("LOCKFILE malformed: components must be an object")
         return issues
@@ -369,13 +506,133 @@ def _lockfile_structure_issues(lockfile: dict) -> List[str]:
         if not isinstance(comp, dict):
             issues.append(f"LOCKFILE malformed: component '{name}' must be an object")
             continue
+        for field in ("version", "boundary_provider_version"):
+            value = comp.get(field)
+            if field not in comp or (value is not None and not isinstance(value, str)):
+                issues.append(
+                    f"LOCKFILE malformed: component '{name}' {field} "
+                    "must be a string or null"
+                )
+        for field in ("path", "boundary_provider"):
+            if not isinstance(comp.get(field), str) or not comp.get(field):
+                issues.append(
+                    f"LOCKFILE malformed: component '{name}' {field} "
+                    "must be a non-empty string"
+                )
+        if comp.get("boundary_status") not in {"ok", "partial", "error"}:
+            issues.append(
+                f"LOCKFILE malformed: component '{name}' boundary_status must be "
+                "one of ok, partial, or error"
+            )
+        consumers = comp.get("consumers")
+        if (
+            not isinstance(consumers, list)
+            or not all(isinstance(item, str) for item in consumers)
+            or len(consumers) != len(set(consumers))
+        ):
+            issues.append(
+                f"LOCKFILE malformed: component '{name}' consumers must be an "
+                "array of unique strings"
+            )
         fps = comp.get("fingerprints")
         if not isinstance(fps, dict):
             issues.append(f"LOCKFILE malformed: component '{name}' missing fingerprints object")
-            continue
-        for required in ("exact", "behavior", "boundary", "compat"):
-            if required not in fps:
-                issues.append(f"LOCKFILE malformed: component '{name}' missing fingerprints.{required}")
+        else:
+            for required in ("exact", "behavior", "boundary", "compat"):
+                if required not in fps:
+                    issues.append(f"LOCKFILE malformed: component '{name}' missing fingerprints.{required}")
+                elif fps[required] is not None and not isinstance(fps[required], str):
+                    issues.append(
+                        f"LOCKFILE malformed: component '{name}' fingerprints.{required} "
+                        "must be a string or null"
+                    )
+        semver = comp.get("semver")
+        if not isinstance(semver, dict):
+            issues.append(
+                f"LOCKFILE malformed: component '{name}' semver must be an object"
+            )
+        else:
+            for field in ("compat_family", "api_surface", "exact_version"):
+                value = semver.get(field)
+                if field not in semver or (
+                    value is not None and not isinstance(value, str)
+                ):
+                    issues.append(
+                        f"LOCKFILE malformed: component '{name}' semver.{field} "
+                        "must be a string or null"
+                    )
+        for field in (
+            "version_errors", "exact_errors", "behavior_errors",
+            "boundary_errors", "warnings", "vendored_copies",
+        ):
+            value = comp.get(field)
+            if value is not None and (
+                not isinstance(value, list)
+                or not all(isinstance(item, str) for item in value)
+            ):
+                issues.append(
+                    f"LOCKFILE malformed: component '{name}' {field} must be an array of strings"
+                )
+        boundary_metadata = comp.get("boundary_metadata")
+        if boundary_metadata is not None and not isinstance(boundary_metadata, dict):
+            issues.append(
+                f"LOCKFILE malformed: component '{name}' boundary_metadata "
+                "must be an object or null"
+            )
+        vendored_digests = comp.get("vendored_digests")
+        if vendored_digests is not None and (
+            not isinstance(vendored_digests, dict)
+            or not all(
+                isinstance(key, str) and isinstance(value, str)
+                for key, value in vendored_digests.items()
+            )
+        ):
+            issues.append(
+                f"LOCKFILE malformed: component '{name}' vendored_digests must "
+                "be an object with string values"
+            )
+    if isinstance(lockfile.get("slices"), dict):
+        for name, slice_entry in lockfile["slices"].items():
+            if not isinstance(slice_entry, dict):
+                issues.append(f"LOCKFILE malformed: slice '{name}' must be an object")
+                continue
+            fingerprint = slice_entry.get("fingerprint")
+            if not isinstance(fingerprint, str):
+                issues.append(
+                    f"LOCKFILE malformed: slice '{name}' fingerprint must be a string"
+                )
+            if not isinstance(slice_entry.get("description"), str):
+                issues.append(
+                    f"LOCKFILE malformed: slice '{name}' description must be a string"
+                )
+            if slice_entry.get("mode") not in {
+                "exact", "behavior", "boundary", "compat",
+            }:
+                issues.append(
+                    f"LOCKFILE malformed: slice '{name}' mode must be one of "
+                    "exact, behavior, boundary, or compat"
+                )
+            slice_components = slice_entry.get("components")
+            if (
+                not isinstance(slice_components, list)
+                or not all(isinstance(item, str) for item in slice_components)
+            ):
+                issues.append(
+                    f"LOCKFILE malformed: slice '{name}' components must be an array of strings"
+                )
+            component_digests = slice_entry.get("component_digests")
+            if (
+                not isinstance(component_digests, dict)
+                or not all(
+                    isinstance(key, str)
+                    and (value is None or isinstance(value, str))
+                    for key, value in component_digests.items()
+                )
+            ):
+                issues.append(
+                    f"LOCKFILE malformed: slice '{name}' component_digests must "
+                    "be an object with string or null values"
+                )
     return issues
 
 
@@ -387,16 +644,36 @@ def verify_lockfile(
     components_filter: Optional[List[str]] = None,
     allow_custom_providers: bool = False,
     fail_fast: bool = False,
+    facets: Optional[List[str]] = None,
+    observations: Optional[List[str]] = None,
 ) -> List[str]:
     """Check if the lockfile matches current repo state. Returns list of mismatches.
 
-    When *fail_fast* is True, returns after the first mismatch is found. This avoids
-    computing fingerprints for remaining components, significantly reducing verification
-    time in large monorepos when you only need a pass/fail signal.
+    When *fail_fast* is True, all selected components are still evaluated so the
+    process can return the globally highest-severity exit condition; only the
+    returned mismatch report is limited to one item.
     """
+    source = _normalize_source(source)
+    # Compute all selected entries even when only one issue is requested. This
+    # is necessary to preserve the global highest-severity exit-code contract
+    # across components; ``fail_fast`` limits the returned report, not safety
+    # evaluation.
+    limit_report = fail_fast
+    fail_fast = False
+
     # Load custom providers once up front.
+    if not isinstance(config, dict):
+        return ["Config root must be an object"]
+    if not isinstance(lockfile, dict):
+        return ["LOCKFILE malformed: root must be an object"]
+    if not isinstance(config.get("components"), dict) or not config.get("components"):
+        return ["Config malformed: components must be a non-empty object"]
+    if not isinstance(config.get("slices", {}), dict):
+        return ["Config malformed: slices must be an object"]
+    registry = create_registry()
     provider_errors = load_custom_providers(
-        config.get("providers", []), allow_custom=allow_custom_providers
+        config.get("providers", []), allow_custom=allow_custom_providers,
+        registry=registry,
     )
     if provider_errors:
         return [f"Custom provider loading failed: {e}" for e in provider_errors]
@@ -405,12 +682,30 @@ def verify_lockfile(
     issues.extend(_lockfile_structure_issues(lockfile))
     if issues:
         return issues
+    if lockfile.get("project") != config.get("project", "unknown"):
+        issues.append(
+            f"METADATA MISMATCH project: lockfile={lockfile.get('project')!r} "
+            f"current={config.get('project', 'unknown')!r}"
+        )
+        if fail_fast:
+            return issues
 
     selected = set(components_filter or [])
     use_filter = len(selected) > 0
+    gated_facets: Set[str] = set(facets or ("exact", "behavior", "boundary", "compat"))
+    unknown_facets = gated_facets - {"exact", "behavior", "boundary", "compat"}
+    if unknown_facets:
+        return [f"Unknown verification facet(s): {', '.join(sorted(unknown_facets))}"]
+    non_gating = observations if observations is not None else []
 
     # Determine which components to check.
     all_components = config.get("components", {})
+    unknown_components = selected - set(all_components)
+    if unknown_components:
+        return [
+            "Unknown verification component(s): "
+            + ", ".join(sorted(unknown_components))
+        ]
     if use_filter:
         check_components = {n: all_components[n] for n in components_filter if n in all_components}
     else:
@@ -422,7 +717,9 @@ def verify_lockfile(
     # Per-component verification with optional early exit.
     computed_entries: Dict[str, dict] = {}
     for name, comp_cfg in check_components.items():
-        current_comp = _compute_component_entry(name, comp_cfg, repo_root, source, defaults, accessor)
+        current_comp = _compute_component_entry(
+            name, comp_cfg, repo_root, source, defaults, accessor, registry
+        )
         computed_entries[name] = current_comp
         locked_comp = lockfile.get("components", {}).get(name)
         if locked_comp is None:
@@ -430,13 +727,42 @@ def verify_lockfile(
             if fail_fast:
                 return issues
             continue
-        for facet in ("exact", "behavior", "boundary", "compat"):
+        current_errors = _generation_errors({"components": {name: current_comp}})
+        locked_errors = _generation_errors({"components": {name: locked_comp}})
+        for message in current_errors:
+            issues.append(f"CURRENT DIGEST ERROR {message}")
+            if fail_fast:
+                return issues
+        for message in locked_errors:
+            issues.append(f"LOCKED DIGEST ERROR {message}")
+            if fail_fast:
+                return issues
+        # Highest policy severity first keeps --fail-fast compatible with the
+        # documented exit-code contract.
+        for facet in ("compat", "boundary", "behavior", "exact"):
             cv = current_comp["fingerprints"].get(facet)
             locked_fps = locked_comp.get("fingerprints", {})
             lv = locked_fps.get(facet)
             if cv != lv:
+                message = f"MISMATCH {name}.{facet}: lockfile={_short(lv)} current={_short(cv)}"
+                if facet in gated_facets:
+                    issues.append(message)
+                    if facet in {"boundary", "compat"}:
+                        consumers = sorted(set(comp_cfg.get("consumers", [])))
+                        if consumers:
+                            issues.append(
+                                f"AFFECTED CONSUMERS {name}: {', '.join(consumers)}"
+                            )
+                    if fail_fast:
+                        return issues
+                else:
+                    non_gating.append(message)
+
+        for field in COMPONENT_METADATA_FIELDS:
+            if locked_comp.get(field) != current_comp.get(field):
                 issues.append(
-                    f"MISMATCH {name}.{facet}: lockfile={_short(lv)} current={_short(cv)}"
+                    f"METADATA MISMATCH {name}.{field}: "
+                    f"lockfile={locked_comp.get(field)!r} current={current_comp.get(field)!r}"
                 )
                 if fail_fast:
                     return issues
@@ -448,38 +774,63 @@ def verify_lockfile(
                 return issues
 
     for name in lockfile.get("components", {}):
-        if use_filter and name not in selected:
-            continue
         if name not in check_components:
+            if name in all_components:
+                continue
             issues.append(f"REMOVED component still in lockfile: {name}")
             if fail_fast:
                 return issues
 
-    # Check slice fingerprints (skip when using component filter, as slices
-    # are not regenerated in that case).
-    if not use_filter:
-        slices_config = config.get("slices", {})
-        if slices_config:
-            for sname, sdef in slices_config.items():
-                current_slice = _recompute_slice_entry(sname, sdef, computed_entries, strict=False)
-                locked_slice = lockfile.get("slices", {}).get(sname)
-                if locked_slice is None:
-                    issues.append(f"NEW slice not in lockfile: {sname}")
-                    if fail_fast:
-                        return issues
-                elif locked_slice.get("fingerprint") != current_slice.get("fingerprint"):
-                    issues.append(
-                        f"SLICE MISMATCH {sname}: lockfile={_short(locked_slice.get('fingerprint'))} "
-                        f"current={_short(current_slice.get('fingerprint'))}"
-                    )
-                    if fail_fast:
-                        return issues
-            for sname in lockfile.get("slices", {}):
-                if sname not in slices_config:
-                    issues.append(f"REMOVED slice still in lockfile: {sname}")
+    # Check every slice affected by the selected components. This prevents a
+    # component-filtered verify from silently ignoring its aggregate contract.
+    slices_config = config.get("slices", {})
+    if slices_config:
+        slice_component_names = set()
+        for sdef in slices_config.values():
+            slice_component_names.update(sdef.get("components", []))
+        for cname in sorted(slice_component_names):
+            if cname not in computed_entries and cname in all_components:
+                computed_entries[cname] = _compute_component_entry(
+                    cname, all_components[cname], repo_root, source, defaults, accessor, registry
+                )
+        for sname, sdef in slices_config.items():
+            if use_filter and not (selected & set(sdef.get("components", []))):
+                continue
+            current_slice = _recompute_slice_entry(sname, sdef, computed_entries, strict=False)
+            locked_slice = lockfile.get("slices", {}).get(sname)
+            if locked_slice is None:
+                issues.append(f"NEW slice not in lockfile: {sname}")
+                if fail_fast:
+                    return issues
+            elif locked_slice != current_slice:
+                message = (
+                    f"SLICE MISMATCH {sname}.{sdef.get('mode', 'exact')}: "
+                    f"lockfile={_short(locked_slice.get('fingerprint'))} "
+                    f"current={_short(current_slice.get('fingerprint'))}"
+                )
+                if sdef.get("mode", "exact") in gated_facets:
+                    issues.append(message)
                     if fail_fast:
                         return issues
+                else:
+                    non_gating.append(message)
+    for sname in lockfile.get("slices", {}):
+        if sname not in slices_config:
+            issues.append(f"REMOVED slice still in lockfile: {sname}")
+            if fail_fast:
+                return issues
 
+    if limit_report and issues:
+        def _severity(message: str) -> int:
+            if ".compat:" in message or ".compat " in message:
+                return 5
+            if ".boundary:" in message or ".boundary " in message:
+                return 4
+            if ".behavior:" in message or ".behavior " in message:
+                return 3
+            return 1
+
+        return [max(issues, key=_severity)]
     return issues
 
 
@@ -488,7 +839,7 @@ def verify_lockfile(
 # ---------------------------------------------------------------------------
 
 # All schema versions this tool can read and migrate from.
-KNOWN_SCHEMAS = frozenset({"boundary-lock/v1"})
+KNOWN_SCHEMAS = frozenset({"boundary-lock/v1", "boundary-lock/v2"})
 
 
 class MigrationError(ValueError):
@@ -501,10 +852,8 @@ def migrate_lockfile(lockfile: dict) -> dict:
     Returns a new dict; does not mutate the input.
     Raises ``MigrationError`` if the schema is absent or unrecognised.
 
-    Today only ``boundary-lock/v1`` exists so this normalises in-place:
-    strips the legacy ``generated_at`` field, ensures ``schema`` is the
-    current value, and defaults ``components``/``slices`` to empty dicts.
-    When a v2 is introduced, add a migration step here before normalising.
+    Hash contract v1 lockfiles cannot be mechanically upgraded because their
+    fingerprints must be recomputed from repository content.
     """
     schema = lockfile.get("schema")
     if schema is None:
@@ -517,10 +866,15 @@ def migrate_lockfile(lockfile: dict) -> dict:
             f"Supported: {', '.join(sorted(KNOWN_SCHEMAS))}. "
             "You may need to upgrade boundver."
         )
+    if schema == "boundary-lock/v1":
+        raise MigrationError(
+            "boundary-lock/v1 uses the ambiguous v1 hash framing and cannot be "
+            "migrated without repository content. Run `boundver generate` with "
+            "boundver 0.10 or newer to create a v2 lockfile."
+        )
     migrated = dict(lockfile)
     migrated.pop("generated_at", None)          # legacy field removed in v1 final
     migrated["schema"] = LOCKFILE_SCHEMA        # normalise to current constant
     migrated.setdefault("components", {})
     migrated.setdefault("slices", {})
     return migrated
-
diff --git a/src/boundver/_output.py b/src/boundver/_output.py
index 5961dc6..d032704 100644
--- a/src/boundver/_output.py
+++ b/src/boundver/_output.py
@@ -1,12 +1,13 @@
 """Output / pretty-printing helpers for boundver."""
 
 import json
+import os
 import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from ._git import _git_run, _to_posix
+from ._git import _git_run, _git_run_bytes, _to_posix
 from ._utils import _is_glob, _short, boundary_provider_name
 
 
@@ -34,6 +35,25 @@ def _bold(s: str) -> str:
     return f"\033[1m{s}\033[0m" if _is_tty() else s
 
 
+def _parse_name_status_z(data: bytes) -> List[Tuple[str, str]]:
+    """Parse ``git diff --name-status -z`` without filename ambiguity."""
+    fields = [field for field in data.split(b"\0") if field]
+    changed: List[Tuple[str, str]] = []
+    index = 0
+    while index < len(fields):
+        status = os.fsdecode(fields[index])
+        index += 1
+        if index >= len(fields):
+            break
+        path = os.fsdecode(fields[index])
+        index += 1
+        if status.startswith(("R", "C")) and index < len(fields):
+            path = os.fsdecode(fields[index])
+            index += 1
+        changed.append((status, path))
+    return changed
+
+
 def print_diff(diff: dict) -> None:
     comps = diff["components"]
 
@@ -57,6 +77,8 @@ def print_diff(diff: dict) -> None:
             print(f"      {c['summary']}")
             for facet, vals in c["changed_facets"].items():
                 print(f"      {facet}: {_short(vals['old'])} -> {_short(vals['new'])}")
+            for field, vals in c.get("changed_metadata", {}).items():
+                print(f"      {field}: {vals['old']!r} -> {vals['new']!r}")
 
     if comps["unchanged"]:
         print(f"\n  UNCHANGED: {len(comps['unchanged'])} components")
@@ -92,6 +114,21 @@ def print_status(lockfile: dict) -> None:
     unversioned = len(comps) - versioned
     print(f"\n  Versioned: {versioned}  |  Unversioned: {unversioned}")
 
+    print("\n  Component details:")
+    for name, component in sorted(comps.items()):
+        fps = component.get("fingerprints", {})
+        version = component.get("version") or "unversioned"
+        provider = component.get("boundary_provider", "unknown")
+        state = component.get("boundary_status", "unknown")
+        print(
+            f"    {name}: {component.get('path', '?')} @ {version}  "
+            f"{provider}/{state}  exact={_short(fps.get('exact'))}  "
+            f"boundary={_short(fps.get('boundary'))}"
+        )
+        consumers = component.get("consumers", [])
+        if consumers:
+            print(f"      consumers: {', '.join(consumers)}")
+
     # Boundary coverage
     boundary_kinds: Dict[str, int] = {}
     boundary_states: Dict[str, int] = {}
@@ -115,8 +152,7 @@ def print_status(lockfile: dict) -> None:
     if implicit_partial:
         print(f"\n  Note: {len(implicit_partial)} component(s) use the 'implicit' provider (boundary fingerprint = null).")
         print("    This is expected — implicit tracks exact changes only.")
-        print("    To track API boundaries, switch to a specific provider:")
-        print("      boundver add <name> <path> --provider openapi")
+        print("    To track a declared boundary, edit the component's boundary provider and paths in the config.")
 
     # Warnings
     warnings = []
@@ -125,6 +161,12 @@ def print_status(lockfile: dict) -> None:
             warnings.append(f"    {name}: {w}")
         for e in c.get("boundary_errors", []):
             warnings.append(f"    {name}: boundary {c.get('boundary_status', 'unknown')} - {e}")
+        for e in c.get("version_errors", []):
+            warnings.append(f"    {name}: version error - {e}")
+        for e in c.get("behavior_errors", []):
+            warnings.append(f"    {name}: behavior error - {e}")
+        for e in c.get("exact_errors", []):
+            warnings.append(f"    {name}: exact error - {e}")
     if warnings:
         print(_yellow(f"\n  WARNINGS ({len(warnings)}):"))
         for w in warnings:
@@ -170,7 +212,7 @@ def analyze_explain_changes(
             pass
 
     # Choose diff target based on source
-    diff_args = ["diff", "--name-status"]
+    diff_args = ["diff", "--name-status", "-z"]
     if source == "working-tree":
         diff_args.append(effective_base)
     elif source == "index":
@@ -180,17 +222,11 @@ def analyze_explain_changes(
     diff_args.extend(["--", component_path])
 
     try:
-        diff = _git_run(repo_root, diff_args)
+        diff = _git_run_bytes(repo_root, ["--literal-pathspecs", *diff_args])
     except subprocess.CalledProcessError as exc:
         return {"error": f"failed to diff '{component_name}' against {effective_base}: {exc}"}
 
-    changed: List[Tuple[str, str]] = []
-    for line in diff.stdout.splitlines():
-        parts = line.split("\t")
-        if len(parts) < 2:
-            continue
-        filepath = parts[-1]
-        changed.append((parts[0].strip(), _to_posix(filepath.strip())))
+    changed = _parse_name_status_z(diff.stdout)
 
     component_prefix = f"{_to_posix(component_path)}/"
     normalized_boundary_paths: List[str] = []
@@ -326,12 +362,13 @@ def why_component(
     if result["version"]:
         print(f"Version:    {result['version']}")
 
-    if not result["changes"]:
-        print(_green("\nStatus: UP TO DATE — no fingerprint drift detected."))
+    if not (result["changes"] or result["metadata_changes"] or result["digest_errors"]):
+        print(_green("\nStatus: UP TO DATE — no fingerprint or metadata drift detected."))
         return 0
 
     changes = result["changes"]
-    print(_red(f"\nStatus: DRIFTED — {len(changes)} facet(s) changed"))
+    drift_count = len(changes) + len(result["metadata_changes"]) + len(result["digest_errors"])
+    print(_red(f"\nStatus: DRIFTED — {drift_count} issue(s) detected"))
 
     print("\nFingerprint changes:")
     for facet in ("exact", "behavior", "boundary", "compat"):
@@ -344,6 +381,16 @@ def why_component(
 
     print(f"\n{_yellow('Change type:')}  {result['summary']}")
 
+    if result["metadata_changes"]:
+        print("\nMetadata changes:")
+        for field, values in result["metadata_changes"].items():
+            print(f"  {field}: {values['locked']!r} → {values['current']!r}")
+
+    if result["digest_errors"]:
+        print(_red("\nFingerprint errors:"))
+        for message in result["digest_errors"]:
+            print(f"  {message}")
+
     if result["changed_files"]:
         print(f"\nModified files under {comp_path}:")
         seen: set = set()
@@ -363,6 +410,12 @@ def why_component(
     boundary_paths = comp_cfg.get("boundary", {}).get("paths", [])
     if boundary_paths and "boundary" in changes:
         print(f"\nBoundary paths:  {', '.join(boundary_paths)}")
+    if result.get("provider_explanation"):
+        print(f"Provider detail: {result['provider_explanation']}")
+
+    consumers = comp_cfg.get("consumers", [])
+    if consumers and ({"boundary", "compat"} & set(changes)):
+        print(f"\nAffected consumers: {', '.join(sorted(set(consumers)))}")
 
     print(f"\n{_bold('Recommendation:')} run `boundver generate --components {component_name}` to update the lockfile.")
     return 1
@@ -388,7 +441,19 @@ def analyze_component_drift(
         current_fps: dict
     """
     from ._diff import _summarize_change
-    from ._lockfile import generate_lockfile
+    from ._lockfile import (
+        COMPONENT_METADATA_FIELDS,
+        _SourceAccessor,
+        _generation_errors,
+        generate_lockfile,
+    )
+    from .providers import (
+        ProviderContext,
+        create_registry,
+        explain_provider_diff,
+        get_provider,
+        load_custom_providers,
+    )
 
     comp_cfg = config.get("components", {}).get(component_name)
     if not comp_cfg:
@@ -428,7 +493,59 @@ def analyze_component_drift(
         if lv != cv:
             changes[facet] = {"locked": lv, "current": cv}
 
-    summary = _summarize_change(changes) if changes else ""
+    metadata_changes: Dict[str, dict] = {}
+    for field in COMPONENT_METADATA_FIELDS:
+        locked_value = locked_comp.get(field)
+        current_value = current_comp.get(field)
+        if locked_value != current_value:
+            metadata_changes[field] = {
+                "locked": locked_value,
+                "current": current_value,
+            }
+    digest_errors = [
+        *(f"current {message}" for message in _generation_errors(
+            {"components": {component_name: current_comp}}
+        )),
+        *(f"locked {message}" for message in _generation_errors(
+            {"components": {component_name: locked_comp}}
+        )),
+    ]
+
+    if changes:
+        summary = _summarize_change(changes)
+    elif digest_errors:
+        summary = "fingerprint computation failed"
+    elif metadata_changes:
+        summary = "component metadata changed"
+    else:
+        summary = ""
+
+    provider_explanation = ""
+    if "boundary" in changes or "boundary_metadata" in metadata_changes:
+        registry = create_registry()
+        load_errors = load_custom_providers(
+            config.get("providers", []),
+            allow_custom=allow_custom_providers,
+            registry=registry,
+        )
+        provider_name = boundary_provider_name(comp_cfg.get("boundary", {}))
+        provider = get_provider(provider_name, registry=registry)
+        if provider is not None and not load_errors:
+            accessor = _SourceAccessor(repo_root, source)
+            ctx = ProviderContext(
+                repo_root=repo_root,
+                component_path=comp_cfg.get("path", "").rstrip("/"),
+                boundary_cfg=comp_cfg.get("boundary", {}),
+                source=source,
+                read_file=accessor.read_file,
+                list_files=accessor.list_files,
+            )
+            provider_explanation = explain_provider_diff(
+                provider,
+                locked_comp.get("boundary_metadata"),
+                current_comp.get("boundary_metadata"),
+                ctx,
+            )
 
     # Get changed files via git diff
     comp_path = comp_cfg.get("path", "?").rstrip("/")
@@ -436,21 +553,16 @@ def analyze_component_drift(
     if changes:
         if source == "working-tree":
             try:
-                diff = _git_run(repo_root, ["diff", "HEAD", "--name-status", "--", comp_path])
-                staged = _git_run(repo_root, ["diff", "--cached", "--name-status", "--", comp_path])
-                for line in (diff.stdout + staged.stdout).splitlines():
-                    parts = line.split("\t")
-                    if len(parts) >= 2:
-                        changed_files.append((parts[0].strip(), _to_posix(parts[-1].strip())))
+                diff = _git_run_bytes(repo_root, ["--literal-pathspecs", "diff", "HEAD", "--name-status", "-z", "--", comp_path])
+                staged = _git_run_bytes(repo_root, ["--literal-pathspecs", "diff", "--cached", "--name-status", "-z", "--", comp_path])
+                changed_files.extend(_parse_name_status_z(diff.stdout))
+                changed_files.extend(_parse_name_status_z(staged.stdout))
             except subprocess.CalledProcessError:
                 pass
         elif source == "index":
             try:
-                staged = _git_run(repo_root, ["diff", "--cached", "--name-status", "--", comp_path])
-                for line in staged.stdout.splitlines():
-                    parts = line.split("\t")
-                    if len(parts) >= 2:
-                        changed_files.append((parts[0].strip(), _to_posix(parts[-1].strip())))
+                staged = _git_run_bytes(repo_root, ["--literal-pathspecs", "diff", "--cached", "--name-status", "-z", "--", comp_path])
+                changed_files.extend(_parse_name_status_z(staged.stdout))
             except subprocess.CalledProcessError:
                 pass
 
@@ -458,9 +570,12 @@ def analyze_component_drift(
 
     return {
         "changes": changes,
+        "metadata_changes": metadata_changes,
+        "digest_errors": digest_errors,
         "summary": summary,
         "changed_files": changed_files,
         "version": version,
         "locked_fps": locked_fps,
         "current_fps": current_fps,
+        "provider_explanation": provider_explanation,
     }
diff --git a/src/boundver/boundary.config.schema.json b/src/boundver/boundary.config.schema.json
new file mode 100644
index 0000000..a9b50b2
--- /dev/null
+++ b/src/boundver/boundary.config.schema.json
@@ -0,0 +1,142 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/yzm1/boundver/main/boundary.config.schema.json",
+  "title": "boundver config",
+  "type": "object",
+  "required": ["project", "components"],
+  "properties": {
+    "$schema": {"type": "string"},
+    "project": {"type": "string", "minLength": 1},
+    "providers": {
+      "type": "array",
+      "description": "Custom providers. Loading requires an explicit --allow-custom-providers flag or trusted environment opt-in.",
+      "items": {
+        "type": "object",
+        "required": ["module", "class"],
+        "properties": {
+          "module": {"type": "string", "minLength": 1},
+          "class": {"type": "string", "minLength": 1},
+          "name": {"type": "string", "pattern": "^custom\\."}
+        },
+        "additionalProperties": false
+      }
+    },
+    "defaults": {
+      "type": "object",
+      "properties": {
+        "compat_mode": {
+          "type": "string",
+          "enum": ["major", "semver_major", "semver_major_minor"]
+        },
+        "verify_facets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": ["exact", "behavior", "boundary", "compat"]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "components": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["path", "boundary"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!\\.?/?$)(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+          },
+          "ecosystem": {"type": "string"},
+          "version_source": {
+            "oneOf": [
+              {"type": "null"},
+              {
+                "type": "object",
+                "required": ["file", "field"],
+                "properties": {
+                  "file": {"type": "string", "minLength": 1},
+                  "field": {"type": "string", "minLength": 1}
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": ["git_tag_prefix"],
+                "properties": {
+                  "git_tag_prefix": {"type": "string", "minLength": 1}
+                },
+                "additionalProperties": false
+              }
+            ]
+          },
+          "boundary": {
+            "type": "object",
+            "required": ["provider"],
+            "properties": {
+              "provider": {"type": "string", "minLength": 1},
+              "paths": {
+                "type": "array",
+                "items": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\\\).+$"}
+              },
+              "options": {
+                "type": "object",
+                "description": "Provider-specific options passed through ProviderContext.",
+                "additionalProperties": true
+              },
+              "note": {"type": "string"}
+            },
+            "additionalProperties": false
+          },
+          "behavior": {
+            "type": "object",
+            "description": "Behavior-relevant paths, normally a superset of boundary paths.",
+            "properties": {
+              "paths": {
+                "type": "array",
+                "items": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*\\\\).+$"}
+              }
+            },
+            "additionalProperties": false
+          },
+          "vendored_copies": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+            }
+          },
+          "consumers": {
+            "type": "array",
+            "items": {"type": "string"},
+            "uniqueItems": true
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "slices": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["components"],
+        "properties": {
+          "description": {"type": "string"},
+          "mode": {"type": "string", "enum": ["exact", "behavior", "boundary", "compat"]},
+          "components": {
+            "type": "array",
+            "items": {"type": "string"}
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}
diff --git a/src/boundver/core.py b/src/boundver/core.py
index a1f9e4c..28a9682 100644
--- a/src/boundver/core.py
+++ b/src/boundver/core.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-boundary-lock: Semantic version manifest with faceted fingerprints.
+boundver: Git-aware, faceted contract-change detection.
 
 Generates a lockfile where each component has:
     - exact fingerprint     (did anything change?)
@@ -11,7 +11,13 @@
 Slices group components and produce their own stable fingerprints.
 Adding an unrelated component does NOT change existing slice fingerprints.
 
-Usage:
+Start here:
+    boundver init --discover
+    boundver validate-config
+    boundver generate --source working-tree
+    boundver verify --source working-tree --facets boundary,compat
+
+Common commands:
     boundver generate [--config boundary.config.json] [--out boundary.lock.json]
     boundver verify  [--config boundary.config.json] [--lock boundary.lock.json]
     boundver diff    <old.lock.json> <new.lock.json>
@@ -19,8 +25,7 @@
     boundver validate-config [--config boundary.config.json]
     boundver status  [--config boundary.config.json] [--lock boundary.lock.json]
 
-Requires: git (for tree hashes), Python 3.8+
-No external dependencies.
+Requires: Git and Python 3.9+.
 """
 
 import argparse
@@ -28,6 +33,7 @@
 import os
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -123,8 +129,11 @@
 # Exit code constants
 # ---------------------------------------------------------------------------
 EXIT_OK = 0
-EXIT_DRIFT = 1       # Drift/mismatch detected (lockfile out of date, config invalid)
+EXIT_DRIFT = 1       # Gated drift detected
 EXIT_USAGE = 2       # Usage/config error (missing file, parse error, unknown name)
+EXIT_BEHAVIOR = 3    # Highest gated drift is behavioral
+EXIT_BOUNDARY = 4    # Highest gated drift is boundary
+EXIT_COMPAT = 5      # Compatibility-family drift
 
 
 def _get_version() -> str:
@@ -137,10 +146,115 @@ def _get_version() -> str:
 
 
 def _resolve_allow_custom(args, config: dict) -> bool:
-    """Merge CLI flag, env var, and config-level allow_custom_providers."""
-    if getattr(args, "allow_custom_providers", False):
-        return True
-    return bool(config.get("allow_custom_providers", False))
+    """Return caller-controlled custom-provider authorization.
+
+    Repository configuration is deliberately not an authorization boundary:
+    checking out an untrusted branch must never be enough to import its Python.
+    """
+    return bool(getattr(args, "allow_custom_providers", False))
+
+
+def _parse_facets_arg(raw: str, config: dict) -> List[str]:
+    value = raw.strip() if isinstance(raw, str) else ""
+    configured = config.get("defaults", {}).get("verify_facets", [])
+    facets = [p.strip() for p in value.split(",") if p.strip()] if value else configured
+    return sorted(set(facets or ["exact", "behavior", "boundary", "compat"]))
+
+
+def _drift_exit_code(issues: List[str]) -> int:
+    """Return an exit code for the highest-severity gated fingerprint drift."""
+    joined = "\n".join(issues)
+    safety_prefixes = (
+        "Config root", "LOCKFILE", "Custom provider loading failed",
+        "Unknown verification facet", "Unknown verification component",
+        "CURRENT DIGEST ERROR",
+        "LOCKED DIGEST ERROR",
+    )
+    if any(issue.startswith(safety_prefixes) for issue in issues):
+        return EXIT_USAGE
+    if ".compat:" in joined:
+        return EXIT_COMPAT
+    if ".boundary:" in joined:
+        return EXIT_BOUNDARY
+    if ".behavior:" in joined:
+        return EXIT_BEHAVIOR
+    return EXIT_DRIFT
+
+
+def _load_lockfile(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise LockfileError(f"Lockfile is not valid JSON: {exc}") from exc
+    if not isinstance(value, dict):
+        raise LockfileError(
+            f"Lockfile root must be an object, got {type(value).__name__}"
+        )
+    return value
+
+
+def _require_valid_lockfile(lockfile: dict) -> None:
+    issues = [
+        *_lockfile_schema_issues(lockfile),
+        *_lockfile_structure_issues(lockfile),
+    ]
+    if issues:
+        raise LockfileError("Lockfile validation failed:\n" + "\n".join(issues))
+
+
+def _ensure_lock_outside_components(
+    repo_root: Path, lock_path: Path, config: dict
+) -> None:
+    absolute_lock = lock_path if lock_path.is_absolute() else repo_root / lock_path
+    for name, component in config.get("components", {}).items():
+        if not isinstance(component, dict):
+            continue
+        component_path = component.get("path")
+        if not isinstance(component_path, str):
+            continue
+        component_root = repo_root / os.path.normpath(component_path.strip())
+        try:
+            absolute_lock.resolve().relative_to(component_root.resolve())
+        except (ValueError, OSError):
+            continue
+        raise ConfigError(
+            f"Lockfile path {absolute_lock} is inside component '{name}' "
+            f"({component_path}); choose an output outside every component to "
+            "avoid self-referential fingerprints"
+        )
+
+
+def _ensure_json_mutation_path(path: Path, command: str) -> None:
+    if path.suffix.lower() != ".json":
+        raise ConfigError(
+            f"`boundver {command}` only writes JSON configs. "
+            "Use boundary.config.json or edit your YAML/TOML config directly."
+        )
+
+
+def _write_text_atomic(path: Path, text: str) -> None:
+    """Replace *path* only after the complete UTF-8 payload is durable.
+
+    The temporary file lives beside the target so ``os.replace`` is atomic on
+    the target filesystem.  This prevents an interrupted generation/update
+    from leaving a truncated lockfile behind.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".tmp", dir=str(path.parent)
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+    except Exception:
+        try:
+            os.unlink(temp_name)
+        except OSError:
+            pass
+        raise
 
 
 # ---------------------------------------------------------------------------
@@ -159,9 +273,9 @@ def _cmd_migrate_lock(args) -> None:
         print(f"error: lockfile not found: {lock_path}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     try:
-        old_lock = json.loads(lock_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        print(f"error: could not parse lockfile as JSON: {exc}", file=sys.stderr)
+        old_lock = _load_lockfile(lock_path)
+    except LockfileError as exc:
+        print(f"error: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     try:
         migrated = migrate_lockfile(old_lock)
@@ -172,7 +286,7 @@ def _cmd_migrate_lock(args) -> None:
     if args.dry_run:
         sys.stdout.write(out)
     else:
-        lock_path.write_text(out, encoding="utf-8")
+        _write_text_atomic(lock_path, out)
         if migrated.get("schema") == old_lock.get("schema"):
             _log("Already at current schema, no changes written.")
         else:
@@ -191,9 +305,9 @@ def _cmd_diff(args) -> None:
             print(f"ERROR: {label} lockfile not found: {fpath}", file=sys.stderr)
             sys.exit(EXIT_USAGE)
     try:
-        old = json.loads(Path(args.old).read_text(encoding="utf-8"))
-        new = json.loads(Path(args.new).read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
+        old = _load_lockfile(Path(args.old))
+        new = _load_lockfile(Path(args.new))
+    except LockfileError as exc:
         print(f"ERROR: Failed to parse lockfile: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     result = diff_lockfiles(old, new)
@@ -214,6 +328,22 @@ def _cmd_generate(args, repo_root: Path) -> None:
         print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     allow_custom = _resolve_allow_custom(args, config)
+    config_errors = validate_config(
+        config,
+        repo_root,
+        allow_custom_providers=allow_custom,
+        source=args.source,
+    )
+    if config_errors:
+        print(f"ERROR: Config is invalid ({len(config_errors)} issues):", file=sys.stderr)
+        for error in config_errors:
+            print(f"  - {error}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:
+        _ensure_lock_outside_components(repo_root, repo_root / args.out, config)
+    except ConfigError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
     # Warn when --source head but working tree has uncommitted changes
     if args.source == "head" and not args.quiet:
         comp_paths = [c.get("path", "") for c in config.get("components", {}).values()]
@@ -258,7 +388,7 @@ def _cmd_generate(args, repo_root: Path) -> None:
     if args.dry_run:
         _log(f"Dry run: lockfile not written ({out_path})", quiet=(args.quiet or args.format == "json"))
     else:
-        out_path.write_text(json.dumps(lockfile, indent=2) + "\n", encoding="utf-8")
+        _write_text_atomic(out_path, json.dumps(lockfile, indent=2) + "\n")
         _log(f"Generated {out_path}", quiet=(args.quiet or args.format == "json"))
     if args.verbose and not args.quiet and args.format != "json":
         print(f"Generation source={args.source} strict={not args.allow_partial}")
@@ -285,56 +415,252 @@ def _cmd_verify(args, repo_root: Path) -> None:
         print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     allow_custom = _resolve_allow_custom(args, config)
+    config_errors = validate_config(
+        config,
+        repo_root,
+        allow_custom_providers=allow_custom,
+        source=args.source,
+    )
+    if config_errors:
+        print(f"ERROR: Config is invalid ({len(config_errors)} issues):", file=sys.stderr)
+        for error in config_errors:
+            print(f"  - {error}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
     lock_path = repo_root / args.lock
+    try:
+        _ensure_lock_outside_components(repo_root, lock_path, config)
+    except ConfigError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
     if not lock_path.exists():
         print(f"ERROR: Lockfile not found: {lock_path} \u2014 run 'boundver generate' first.", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     try:
-        lockfile = json.loads(lock_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        print(f"ERROR: Lockfile is not valid JSON: {exc}", file=sys.stderr)
+        lockfile = _load_lockfile(lock_path)
+    except LockfileError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     components_filter = _parse_components_arg(args.components)
+    unknown = [
+        name for name in components_filter
+        if name not in config.get("components", {})
+    ]
+    if unknown:
+        print(
+            f"ERROR: unknown --components entries: {', '.join(unknown)}",
+            file=sys.stderr,
+        )
+        sys.exit(EXIT_USAGE)
+    gated_facets = _parse_facets_arg(args.facets, config)
+    unknown_facets = sorted(
+        set(gated_facets) - {"exact", "behavior", "boundary", "compat"}
+    )
+    if unknown_facets:
+        print(
+            f"ERROR: unknown --facets entries: {', '.join(unknown_facets)}",
+            file=sys.stderr,
+        )
+        sys.exit(EXIT_USAGE)
+    structural_issues = [
+        *_lockfile_schema_issues(lockfile),
+        *_lockfile_structure_issues(lockfile),
+    ]
+    preflight_issues = list(structural_issues)
+    if not structural_issues and lockfile.get("project") != config.get("project", "unknown"):
+        preflight_issues.append(
+            f"METADATA MISMATCH project: lockfile={lockfile.get('project')!r} "
+            f"current={config.get('project', 'unknown')!r}"
+        )
+    locked_names = set(lockfile.get("components", {})) if isinstance(lockfile.get("components"), dict) else set()
+    configured_names = set(config.get("components", {}))
+    if not structural_issues and locked_names != configured_names:
+        preflight_issues.append(
+            "LOCKFILE component set differs from config: "
+            f"locked={sorted(locked_names)} configured={sorted(configured_names)}"
+        )
+    locked_slices = set(lockfile.get("slices", {})) if isinstance(lockfile.get("slices"), dict) else set()
+    configured_slices = set(config.get("slices", {}))
+    if not structural_issues and locked_slices != configured_slices:
+        preflight_issues.append(
+            "LOCKFILE slice set differs from config: "
+            f"locked={sorted(locked_slices)} configured={sorted(configured_slices)}"
+        )
+    if not structural_issues:
+        for name, entry in lockfile["components"].items():
+            for field in ("version_errors", "exact_errors", "behavior_errors"):
+                for message in entry.get(field, []):
+                    preflight_issues.append(
+                        f"LOCKED DIGEST ERROR {name}: {message}"
+                    )
+            if entry.get("boundary_status") == "error" and not entry.get("boundary_errors"):
+                preflight_issues.append(
+                    f"LOCKED DIGEST ERROR {name}: boundary computation failed"
+                )
+            elif entry.get("boundary_status") == "error":
+                for message in entry.get("boundary_errors", []):
+                    preflight_issues.append(
+                        f"LOCKED DIGEST ERROR {name}: {message}"
+                    )
+    if preflight_issues and args.update and not structural_issues:
+        try:
+            updated = generate_lockfile(
+                config, repo_root, source=args.source, strict=True,
+                allow_custom_providers=allow_custom,
+            )
+        except ValueError as exc:
+            print(f"ERROR: update failed: {exc}", file=sys.stderr)
+            sys.exit(EXIT_USAGE)
+        _write_text_atomic(lock_path, json.dumps(updated, indent=2) + "\n")
+        if args.format == "json":
+            _print_json({
+                "ok": True,
+                "updated": True,
+                "issues": preflight_issues,
+                "observations": [],
+                "facets": gated_facets,
+                "components_filter": components_filter,
+            })
+        elif not args.quiet:
+            print(_green(f"Updated {lock_path} after successful preflight repair."))
+        return
+    if preflight_issues:
+        if args.format == "json":
+            _print_json({
+                "ok": False,
+                "updated": False,
+                "issues": preflight_issues,
+                "observations": [],
+                "facets": gated_facets,
+                "components_filter": components_filter,
+            })
+        else:
+            print("ERROR: lockfile preflight failed:", file=sys.stderr)
+            for issue in preflight_issues:
+                print(f"  - {issue}", file=sys.stderr)
+        sys.exit(_drift_exit_code(preflight_issues))
     if args.changed_from:
-        auto = changed_components_since_ref(config, repo_root, args.changed_from)
+        try:
+            auto = changed_components_since_ref(config, repo_root, args.changed_from)
+        except ValueError as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            sys.exit(EXIT_USAGE)
         if components_filter:
             auto_set = set(auto)
             components_filter = [c for c in components_filter if c in auto_set]
         else:
             components_filter = auto
-        # If --changed-from resolved to no components, nothing needs verification.
-        if not components_filter:
-            if args.format == "json":
-                _print_json({"ok": True, "issues": [], "components_filter": []})
-            elif not args.quiet:
-                print(_green("No components changed — nothing to verify."))
-            return
-    unknown = [n for n in components_filter if n not in config.get("components", {})]
-    if unknown:
-        print(f"ERROR: unknown --components entries: {', '.join(unknown)}", file=sys.stderr)
-        sys.exit(EXIT_USAGE)
+        # A path diff is only a scheduling hint, not proof that unselected lock
+        # entries are internally current. Recompute every component so stale
+        # metadata, provider upgrades, and digest errors cannot pass merely
+        # because another component happened to be selected. Keep the resolved
+        # selection in JSON for observability.
+        if args.verbose and not args.quiet and args.format != "json":
+            if components_filter:
+                print(
+                    "Changed component paths: " + ", ".join(components_filter)
+                    + "; validating full lock integrity."
+                )
+            else:
+                print("No component paths changed; validating full lock integrity.")
+        reported_components_filter = list(components_filter)
+        components_filter = []
+    else:
+        reported_components_filter = list(components_filter)
+    observations: List[str] = []
     try:
         issues = verify_lockfile(
             config, lockfile, repo_root, source=args.source, components_filter=components_filter,
             allow_custom_providers=allow_custom,
             fail_fast=getattr(args, "fail_fast", False),
+            facets=gated_facets,
+            observations=observations,
         )
     except ValueError as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
-    if args.format == "json":
-        _print_json({"ok": len(issues) == 0, "issues": issues, "components_filter": components_filter})
     if issues:
         if args.format != "json" and not args.quiet:
             print(_red(f"LOCKFILE OUT OF DATE ({len(issues)} issues):") + "\n")
             for issue in issues:
                 print(f"  {issue}")
-        sys.exit(EXIT_DRIFT)
+            if observations:
+                print(_yellow("\nNON-GATING DRIFT:"))
+                for observation in observations:
+                    print(f"  {observation}")
+            if not args.update:
+                print("\nInspect with `boundver why <component>`, then run `boundver verify --update` after review.")
+        if args.update:
+            try:
+                updated = generate_lockfile(
+                    config, repo_root, source=args.source, strict=True,
+                    allow_custom_providers=allow_custom,
+                )
+            except ValueError as exc:
+                print(f"ERROR: update failed: {exc}", file=sys.stderr)
+                sys.exit(EXIT_USAGE)
+            _write_text_atomic(lock_path, json.dumps(updated, indent=2) + "\n")
+            if args.format == "json":
+                _print_json({
+                    "ok": True,
+                    "updated": True,
+                    "issues": issues,
+                    "observations": observations,
+                    "facets": gated_facets,
+                    "components_filter": reported_components_filter,
+                })
+            if args.format != "json" and not args.quiet:
+                print(_green(f"Updated {lock_path} after successful generation."))
+            return
+        if args.format == "json":
+            _print_json({
+                "ok": False,
+                "updated": False,
+                "issues": issues,
+                "observations": observations,
+                "facets": gated_facets,
+                "components_filter": reported_components_filter,
+            })
+        sys.exit(_drift_exit_code(issues))
     else:
+        if args.update and observations:
+            try:
+                updated = generate_lockfile(
+                    config, repo_root, source=args.source, strict=True,
+                    allow_custom_providers=allow_custom,
+                )
+            except ValueError as exc:
+                print(f"ERROR: update failed: {exc}", file=sys.stderr)
+                sys.exit(EXIT_USAGE)
+            _write_text_atomic(lock_path, json.dumps(updated, indent=2) + "\n")
+            if args.format == "json":
+                _print_json({
+                    "ok": True,
+                    "updated": True,
+                    "issues": [],
+                    "observations": observations,
+                    "facets": gated_facets,
+                    "components_filter": reported_components_filter,
+                })
+            elif not args.quiet:
+                print(_green(f"Updated {lock_path} after successful generation."))
+            return
+        if args.format == "json":
+            _print_json({
+                "ok": True,
+                "updated": False,
+                "issues": [],
+                "observations": observations,
+                "facets": gated_facets,
+                "components_filter": reported_components_filter,
+            })
         if args.verbose and not args.quiet:
             print(_green(f"Verified source={args.source} with 0 issues."))
         elif args.format != "json" and not args.quiet:
             print(_green("Lockfile is up to date."))
+            if observations:
+                print(_yellow(f"Non-gating drift observed ({len(observations)}):"))
+                for observation in observations:
+                    print(f"  {observation}")
 
 
 def _cmd_slice(args, repo_root: Path) -> None:
@@ -343,9 +669,14 @@ def _cmd_slice(args, repo_root: Path) -> None:
         print(f"ERROR: Lockfile not found: {lock_path} \u2014 run 'boundver generate' first.", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     try:
-        lockfile = json.loads(lock_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        print(f"ERROR: Lockfile is not valid JSON: {exc}", file=sys.stderr)
+        lockfile = _load_lockfile(lock_path)
+    except LockfileError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:
+        _require_valid_lockfile(lockfile)
+    except LockfileError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     sl = lockfile.get("slices", {}).get(args.name)
     if sl is None:
@@ -373,7 +704,10 @@ def _cmd_validate_config(args, repo_root: Path) -> None:
     except ValueError as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
-    errors = validate_config(config, repo_root)
+    allow_custom = _resolve_allow_custom(args, config)
+    errors = validate_config(
+        config, repo_root, allow_custom_providers=allow_custom
+    )
     warnings = config_warnings(config, repo_root)
     if errors:
         print(_red(f"CONFIG INVALID ({len(errors)} issues):"))
@@ -389,15 +723,26 @@ def _cmd_validate_config(args, repo_root: Path) -> None:
 
 def _cmd_init(args, repo_root: Path) -> None:
     config_path = repo_root / args.out
+    try:
+        _ensure_json_mutation_path(config_path, "init")
+    except ConfigError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
     if config_path.exists() and not args.force:
         print(f"ERROR: Config already exists: {config_path}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     discovered = discover_components(repo_root) if args.discover else {}
+    if args.discover and not discovered:
+        print(
+            "WARNING: No tracked nested manifests were discovered. "
+            "Creating an empty config; add a real component before generation.",
+            file=sys.stderr,
+        )
     starter = {
         "$schema": "https://raw.githubusercontent.com/yzm1/boundver/main/boundary.config.schema.json",
         "project": repo_root.name,
         "defaults": {"compat_mode": "major"},
-        "components": discovered or {
+        "components": discovered if args.discover else {
             "example-component": {
                 "path": "src",
                 "version_source": None,
@@ -405,9 +750,9 @@ def _cmd_init(args, repo_root: Path) -> None:
             }
         },
     }
-    config_path.write_text(json.dumps(starter, indent=2) + "\n", encoding="utf-8")
-    print(f"Created starter config: {config_path}")
-    print("  Tip: slices are optional. Add them later for multi-component grouping.")
+    _write_text_atomic(config_path, json.dumps(starter, indent=2) + "\n")
+    print(f"Created {config_path} with {len(starter['components'])} component(s).")
+    print(f"Next: review the config, then run `boundver validate-config` and `boundver generate`.")
 
 
 def _cmd_add(args, repo_root: Path) -> None:
@@ -416,6 +761,11 @@ def _cmd_add(args, repo_root: Path) -> None:
         print(f"ERROR: Config file not found: {config_path}", file=sys.stderr)
         print("Run: boundver init", file=sys.stderr)
         sys.exit(EXIT_USAGE)
+    try:
+        _ensure_json_mutation_path(config_path, "add")
+    except ConfigError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
     try:
         config = load_config_file(config_path)
     except ValueError as exc:
@@ -436,7 +786,7 @@ def _cmd_add(args, repo_root: Path) -> None:
         "boundary": {"provider": args.provider, "paths": boundary_paths},
     }
     config["components"] = components
-    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    _write_text_atomic(config_path, json.dumps(config, indent=2) + "\n")
     print(f"Added component '{args.name}' at path '{args.path}'")
     print(f"Run: boundver generate --components {args.name}")
 
@@ -446,6 +796,11 @@ def _cmd_remove(args, repo_root: Path) -> None:
     if not config_path.exists():
         print(f"ERROR: Config file not found: {config_path}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
+    try:
+        _ensure_json_mutation_path(config_path, "remove")
+    except ConfigError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
     try:
         config = load_config_file(config_path)
     except ValueError as exc:
@@ -462,7 +817,7 @@ def _cmd_remove(args, repo_root: Path) -> None:
         comp_list = slice_def.get("components", [])
         if args.name in comp_list:
             comp_list.remove(args.name)
-    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    _write_text_atomic(config_path, json.dumps(config, indent=2) + "\n")
     print(f"Removed component '{args.name}'")
     print("Run: boundver generate")
 
@@ -482,22 +837,48 @@ def _cmd_status(args, repo_root: Path) -> None:
     lock_path = repo_root / args.lock
     if lock_path.exists():
         try:
-            lockfile = json.loads(lock_path.read_text(encoding="utf-8"))
-        except json.JSONDecodeError as exc:
-            print(f"ERROR: Lockfile is not valid JSON: {exc}", file=sys.stderr)
+            lockfile = _load_lockfile(lock_path)
+        except LockfileError as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
             sys.exit(EXIT_USAGE)
-        status_payload = {"lockfile": lockfile, "issues": [], "warnings": []}
+        structure_issues = [
+            *_lockfile_schema_issues(lockfile),
+            *_lockfile_structure_issues(lockfile),
+        ]
+        status_payload = {
+            "lockfile": lockfile,
+            "issues": structure_issues,
+            "warnings": [],
+        }
         if args.format != "json" and not args.quiet:
-            print_status(lockfile)
+            if structure_issues:
+                print(_red("LOCKFILE INVALID:"))
+                for issue in structure_issues:
+                    print(f"  {issue}")
+            else:
+                print_status(lockfile)
         # Collect component warnings
         has_warnings = False
-        for name, comp in lockfile.get("components", {}).items():
+        components = lockfile.get("components", {})
+        if not isinstance(components, dict):
+            components = {}
+        for name, comp in components.items():
+            if not isinstance(comp, dict):
+                continue
             for w in comp.get("warnings", []):
                 status_payload["warnings"].append(f"{name}: {w}")
                 has_warnings = True
             for e in comp.get("boundary_errors", []):
                 status_payload["warnings"].append(f"{name}: boundary {comp.get('boundary_status', 'unknown')} - {e}")
                 has_warnings = True
+            for error_field, label in (
+                ("version_errors", "version"),
+                ("behavior_errors", "behavior"),
+                ("exact_errors", "exact"),
+            ):
+                for e in comp.get(error_field, []):
+                    status_payload["warnings"].append(f"{name}: {label} error - {e}")
+                    has_warnings = True
         # Also verify if config exists
         config_path = find_config_file(repo_root, args.config)
         if config_path.exists():
@@ -506,14 +887,25 @@ def _cmd_status(args, repo_root: Path) -> None:
             except ValueError as exc:
                 print(f"WARNING: Config parse error: {exc}", file=sys.stderr)
                 config = None
-            if config is not None:
+            if config is not None and not structure_issues:
                 allow_custom = _resolve_allow_custom(args, config)
-                try:
-                    issues = verify_lockfile(config, lockfile, repo_root, source=args.source,
-                                             allow_custom_providers=allow_custom)
-                except ValueError as exc:
-                    issues = [f"Verification error: {exc}"]
-                status_payload["issues"] = issues
+                config_errors = validate_config(
+                    config,
+                    repo_root,
+                    allow_custom_providers=allow_custom,
+                    source=args.source,
+                )
+                if config_errors:
+                    issues = [f"Config invalid: {error}" for error in config_errors]
+                else:
+                    try:
+                        issues = verify_lockfile(
+                            config, lockfile, repo_root, source=args.source,
+                            allow_custom_providers=allow_custom,
+                        )
+                    except ValueError as exc:
+                        issues = [f"Verification error: {exc}"]
+                status_payload["issues"].extend(issues)
                 if issues:
                     if not args.quiet and args.format != "json":
                         print(f"\n  DRIFT DETECTED ({len(issues)} issues):")
@@ -523,7 +915,7 @@ def _cmd_status(args, repo_root: Path) -> None:
             _print_json(status_payload)
         # --strict: exit non-zero if any drift or warnings
         if getattr(args, "strict", False) and (status_payload["issues"] or has_warnings):
-            sys.exit(EXIT_DRIFT)
+            sys.exit(_drift_exit_code(status_payload["issues"]))
     else:
         print(f"No lockfile found at {lock_path}. Run 'generate' first.")
         sys.exit(EXIT_USAGE)
@@ -555,9 +947,14 @@ def _cmd_why(args, repo_root: Path) -> None:
         print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     try:
-        lockfile = json.loads(lock_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        print(f"ERROR: Lockfile is not valid JSON: {exc}", file=sys.stderr)
+        lockfile = _load_lockfile(lock_path)
+    except LockfileError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(EXIT_USAGE)
+    try:
+        _require_valid_lockfile(lockfile)
+    except LockfileError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
         sys.exit(EXIT_USAGE)
     allow_custom = _resolve_allow_custom(args, config)
     rc = why_component(config, lockfile, repo_root, args.component, source=args.source,
@@ -567,8 +964,15 @@ def _cmd_why(args, repo_root: Path) -> None:
 
 
 def main():
+    # argparse normally accepts global options only before the subcommand.
+    # Normalize the two verbosity flags so documented/completed post-command
+    # forms work as well (for example `boundver status --quiet`).
+    for option in ("--quiet", "--verbose"):
+        if option in sys.argv[2:]:
+            sys.argv.remove(option)
+            sys.argv.insert(1, option)
     parser = argparse.ArgumentParser(
-        description="boundary-lock: semantic version manifest with faceted fingerprints",
+        description="Detect declared component, behavior, boundary, and compatibility drift",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=__doc__,
     )
@@ -594,7 +998,10 @@ def main():
     )
     gen.add_argument("--config", default="boundary.config.json", help="Config file path")
     gen.add_argument("--out", default="boundary.lock.json", help="Output lockfile path")
-    gen.add_argument("--source", choices=["head", "index", "working-tree"], default="head", help="Fingerprint source")
+    gen.add_argument(
+        "--source", choices=["head", "index", "working-tree"], default="head",
+        help="Snapshot to fingerprint: last commit, staged index, or tracked files on disk",
+    )
     gen.add_argument("--allow-partial", action="store_true", help="Allow missing boundary/compat digests in slices")
     gen.add_argument("--dry-run", action="store_true", help="Compute lockfile and print status without writing output")
     gen.add_argument("--components", default="", help="Comma-separated component names to regenerate")
@@ -610,9 +1017,12 @@ def main():
         description=(
             "Verify the lockfile is up to date with the current repo state.\n\n"
             "Exit codes:\n"
-            "  0  Lockfile matches current repo state\n"
-            "  1  Lockfile is out of date (fingerprint mismatches found)\n"
-            "  2  Usage error (unknown component name, config missing, etc.)\n"
+            "  0  Selected facets match\n"
+            "  1  Exact or metadata drift\n"
+            "  2  Usage, configuration, or digest error\n"
+            "  3  Behavioral drift\n"
+            "  4  Boundary drift\n"
+            "  5  Compatibility-family drift\n"
         ),
         epilog=(
             "Examples:\n"
@@ -626,11 +1036,22 @@ def main():
     ver.add_argument("--config", default="boundary.config.json")
     ver.add_argument("--lock", default="boundary.lock.json")
     ver.add_argument("--source", choices=["head", "index", "working-tree"], default="head",
-                     help="Fingerprint source to compare against locked values")
+                     help="Snapshot to compare: last commit, staged index, or tracked files on disk")
     ver.add_argument("--components", default="", help="Comma-separated component names to verify")
-    ver.add_argument("--changed-from", default="", help="Auto-select changed components since git ref")
+    ver.add_argument(
+        "--changed-from", default="",
+        help="Report components changed since a Git ref while verifying full lock integrity",
+    )
     ver.add_argument("--fail-fast", action="store_true",
-                     help="Stop after first mismatch (faster for large repos in CI)")
+                     help="Report only the highest-severity mismatch")
+    ver.add_argument(
+        "--facets", default="",
+        help="Comma-separated facets that fail the gate (default: config defaults.verify_facets or all)",
+    )
+    ver.add_argument(
+        "--update", action="store_true",
+        help="After reporting drift, atomically regenerate the lockfile if computation succeeds",
+    )
     ver.add_argument("--format", choices=["json", "text"], default="text", help="Output format")
     ver.add_argument(
         "--allow-custom-providers", action="store_true",
@@ -757,7 +1178,7 @@ def main():
         help="Allow loading external provider modules declared in the config 'providers' key",
     )
 
-    disc = sub.add_parser("discover", help="Print discovered components as JSON")
+    disc = sub.add_parser("discover", help="Find Git-tracked component manifests")
     disc.add_argument("--format", choices=["json", "text"], default="text", help="Output format")
 
     # migrate-lock
diff --git a/src/boundver/providers.py b/src/boundver/providers.py
index 8b257e3..4e1d710 100644
--- a/src/boundver/providers.py
+++ b/src/boundver/providers.py
@@ -1,8 +1,8 @@
 """
 Provider protocol for boundver boundary extraction.
 
-Phase 1: protocol types, built-in wrappers that replicate current raw-byte
-behavior exactly (zero digest drift), registry, and compute_boundary().
+Phase 1: protocol types, raw-byte built-in wrappers, registry, and
+compute_boundary().
 
 Phase 2: load_custom_providers() — loads and registers custom providers from
 the `providers` config key. Requires --allow-custom-providers at runtime.
@@ -12,12 +12,12 @@
   change when the logical API contract changes. They are opt-in (activated only
   by explicit provider name) and have zero impact on existing lockfiles.
 
-The design is specified in docs/design/07-provider-architecture.md.
+The public extension and trust model is documented in
+docs/public-vs-custom-providers.md.
 """
 from __future__ import annotations
 
 import fnmatch
-import hashlib
 import importlib
 import json as _json_mod
 import re
@@ -25,9 +25,41 @@
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Protocol, runtime_checkable
 
+from ._hashing import HASH_DOMAIN_BOUNDARY, _hash_framed_entries
 from ._utils import ProviderError, _is_glob
 
 
+def _join_repo_path(component_path: str, relative_path: str) -> str:
+    """Join config paths without treating a root component as ``./``."""
+    prefix = component_path.strip().replace("\\", "/").strip("/")
+    while prefix.startswith("./"):
+        prefix = prefix[2:]
+    if prefix in {"", "."}:
+        return relative_path.lstrip("/")
+    return f"{prefix}/{relative_path.lstrip('/')}"
+
+
+def _component_relative_path(component_path: str, repo_relative_path: str) -> str:
+    """Return a stable component-relative label for a repo-relative path."""
+    prefix = component_path.strip().replace("\\", "/").strip("/")
+    while prefix.startswith("./"):
+        prefix = prefix[2:]
+    # Git already emits '/' as its separator on every platform.  A backslash
+    # returned here is therefore a literal filename byte on POSIX and must not
+    # be rewritten into a separator (which would collapse distinct labels).
+    path = repo_relative_path.lstrip("/")
+    if prefix in {"", "."}:
+        return path
+    expected = prefix + "/"
+    if path.startswith(expected):
+        return path[len(expected):]
+    if path == prefix:
+        return Path(path).name
+    raise ProviderError(
+        f"Provider returned path outside component '{component_path}': {repo_relative_path}"
+    )
+
+
 def _fnmatch_case_sensitive(name: str, pattern: str) -> bool:
     """Case-sensitive fnmatch regardless of platform.
 
@@ -64,13 +96,11 @@ class ResolvedBoundary:
     """What a provider returns from resolve().
 
     ``entries`` is an ordered list of (label, content) pairs.
-    Core hashes them as::
-
-        sha256(b"entry:<label>\\n" + content + ...)
+    Core hashes them with boundver's length-delimited, domain-separated wire
+    format.
 
     Labels MUST be deterministic and sorted by the provider.
-    For path-based providers the label is ``file:<component-relative-path>``,
-    preserving backwards-compatibility with the pre-Phase-1 digest format.
+    For path-based providers the label is ``file:<component-relative-path>``.
     """
 
     entries: List[tuple] = field(default_factory=list)  # List[tuple[str, bytes]]
@@ -128,6 +158,9 @@ def explain_diff(
         ...  # pragma: no cover
 
 
+ProviderRegistry = Dict[str, BoundaryProvider]
+
+
 # ---------------------------------------------------------------------------
 # Core hashing function — the ONLY place SHA-256 is called for boundary digests
 # ---------------------------------------------------------------------------
@@ -135,29 +168,81 @@ def explain_diff(
 def compute_boundary(
     provider: BoundaryProvider,
     ctx: ProviderContext,
-) -> tuple:  # tuple[Optional[str], str, List[str]]
+    *,
+    include_metadata: bool = False,
+) -> tuple:
     """Ask the provider to resolve content, then hash it.
 
-    Returns ``(digest_or_None, status, errors)``.
+    By default, returns the historical three-item tuple
+    ``(digest_or_None, status, errors)``.  Callers that persist or explain
+    provider metadata can pass ``include_metadata=True`` to receive
+    ``(digest_or_None, status, errors, metadata)`` instead.
 
-    The label format ``"entry:<label>\\n"`` matches the per-entry prefix used in
-    the pre-Phase-1 ``boundary_paths_digest`` function (which used
-    ``"file:<rel>\\n"``), so labels like ``"file:openapi.yaml"`` produce
-    identical digests.
+    Hashing uses the shared, length-delimited boundary domain so entry content
+    cannot be confused with the framing for a later entry.
     """
     resolved = provider.resolve(ctx)
+    result: tuple
     if resolved.status == "error" or not resolved.entries:
-        return None, resolved.status or "error", resolved.errors
-    # Hash format mirrors pre-Phase-1 boundary_paths_digest:
-    #   sha256( ("file:child_rel\n" + content) * N )
-    # Labels produced by path-based providers are "file:<child_rel>",
-    # so we append "\n" and then the content — identical wire format.
-    parts: List[bytes] = []
-    for label, content in resolved.entries:
-        parts.append(label.encode("utf-8"))
-        parts.append(b"\n")
-        parts.append(content)
-    return hashlib.sha256(b"".join(parts)).hexdigest(), resolved.status, resolved.errors
+        result = (None, resolved.status or "error", resolved.errors)
+    else:
+        result = (
+            _hash_framed_entries(resolved.entries, domain=HASH_DOMAIN_BOUNDARY),
+            resolved.status,
+            resolved.errors,
+        )
+    if include_metadata:
+        return result + (resolved.metadata,)
+    return result
+
+
+def validate_provider_config(
+    provider: BoundaryProvider,
+    boundary_cfg: dict,
+    component_path: str,
+    repo_root: Path,
+) -> List[str]:
+    """Invoke a provider's optional validation hook with stable error handling.
+
+    Older third-party providers that predate the hook remain usable.  A broken
+    hook becomes an actionable validation error rather than crashing the CLI.
+    """
+    validator = getattr(provider, "validate_config", None)
+    if not callable(validator):
+        return []
+    provider_name = getattr(provider, "name", provider.__class__.__name__)
+    try:
+        errors = validator(boundary_cfg, component_path, repo_root)
+    except Exception as exc:
+        return [f"Provider '{provider_name}' config validation failed: {exc}"]
+    if errors is None:
+        return []
+    if not isinstance(errors, list):
+        return [
+            f"Provider '{provider_name}' validate_config() must return a list of errors"
+        ]
+    return [str(error) for error in errors]
+
+
+def explain_provider_diff(
+    provider: BoundaryProvider,
+    old_metadata: Optional[dict],
+    new_metadata: Optional[dict],
+    ctx: ProviderContext,
+) -> str:
+    """Return a provider-specific diff summary with a useful fallback."""
+    provider_name = getattr(provider, "name", provider.__class__.__name__)
+    fallback = f"{provider_name} boundary changed"
+    explainer = getattr(provider, "explain_diff", None)
+    if not callable(explainer):
+        return fallback
+    try:
+        explanation = explainer(old_metadata, new_metadata, ctx)
+    except Exception as exc:
+        return f"{fallback} (provider explanation unavailable: {exc})"
+    if isinstance(explanation, str) and explanation.strip():
+        return explanation.strip()
+    return fallback
 
 
 # ---------------------------------------------------------------------------
@@ -167,8 +252,8 @@ def compute_boundary(
 class PathHashProvider:
     """Hash declared boundary paths as raw normalised bytes.
 
-    Replicates the pre-Phase-1 ``boundary_paths_digest`` behavior exactly so
-    existing lockfile digests are preserved.
+    Replicates the historical provider's content selection; core applies the
+    current unambiguous hashing wire format.
 
     Subclasses set ``name`` to the provider identifier string.
     """
@@ -185,6 +270,7 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
             )
         seen: set = set()
         ordered: List[tuple] = []  # List[tuple[str, bytes]]
+        unmatched: List[str] = []
 
         # Lazily enumerate all component files once when any glob pattern is present.
         _all_component_files: Optional[List[str]] = None
@@ -197,12 +283,15 @@ def _component_files() -> List[str]:
 
         for rel in sorted(paths):
             rel = rel.strip()
+            matched = False
             if _is_glob(rel):
                 # Expand glob against all files in the component directory.
                 # fnmatch treats * as matching any characters incl. path separators,
                 # so 'api/*.yaml' matches files at any depth under api/.
                 for repo_rel in _component_files():
-                    child_rel = repo_rel[len(ctx.component_path) + 1:]
+                    child_rel = _component_relative_path(ctx.component_path, repo_rel)
+                    if _fnmatch_case_sensitive(child_rel, rel):
+                        matched = True
                     if _fnmatch_case_sensitive(child_rel, rel) and repo_rel not in seen:
                         seen.add(repo_rel)
                         content = ctx.read_file(repo_rel)
@@ -210,8 +299,9 @@ def _component_files() -> List[str]:
                             content = content.replace(b"\r\n", b"\n")
                         ordered.append((f"file:{child_rel}", content))
             else:
-                full_base = f"{ctx.component_path}/{rel}".lstrip("/")
+                full_base = _join_repo_path(ctx.component_path, rel)
                 for repo_rel in sorted(ctx.list_files(full_base)):
+                    matched = True
                     if repo_rel in seen:
                         continue
                     seen.add(repo_rel)
@@ -219,10 +309,21 @@ def _component_files() -> List[str]:
                     # CRLF normalisation — preserved from _read_path_content
                     if b"\r\n" in content and b"\x00" not in content:
                         content = content.replace(b"\r\n", b"\n")
-                    child_rel = repo_rel[len(ctx.component_path) + 1:]
-                    # Label uses "file:" prefix to match pre-Phase-1 format.
+                    child_rel = _component_relative_path(ctx.component_path, repo_rel)
+                    # Keep the stable, provider-independent path label.
                     ordered.append((f"file:{child_rel}", content))
 
+            if not matched:
+                unmatched.append(rel)
+
+        if unmatched:
+            return ResolvedBoundary(
+                status="error",
+                errors=[
+                    f"Declared boundary path matched no tracked files: {rel}"
+                    for rel in unmatched
+                ],
+            )
         if not ordered:
             return ResolvedBoundary(
                 status="error",
@@ -373,23 +474,80 @@ class TypeScriptExportsProvider(PathHashProvider):
 # Top-level OpenAPI keys that are metadata only, not API contract.
 _OPENAPI_DROP_TOP = frozenset({"info", "servers", "tags"})
 
+# Maps whose direct keys are user-defined identifiers rather than OpenAPI
+# annotation fields.  Preserve those keys, then resume normal annotation
+# stripping inside each referenced object.
+_OPENAPI_COMPONENT_MAPS = frozenset({
+    "schemas", "responses", "parameters", "examples", "requestBodies",
+    "headers", "securitySchemes", "links", "callbacks", "pathItems",
+})
+_OPENAPI_NAMED_MAP_KEYS = frozenset({
+    "paths", "webhooks", "scopes", "patternProperties", "dependentSchemas",
+    "dependentRequired", "parameters", "headers", "encoding", "mapping",
+    "callbacks", "links", "variables",
+})
+
+
+def _is_openapi_named_schema_map(path: tuple, key: Any) -> bool:
+    """Return whether ``key`` introduces a map of user-defined schema names.
+
+    Annotation-looking names are legal property/schema identifiers.  For
+    example, ``properties.description`` describes a property named
+    ``description``; it is not the Schema Object's documentation field.
+    """
+    if key in {"properties", "definitions", "$defs"} | _OPENAPI_NAMED_MAP_KEYS:
+        return True
+    return path == ("components",) and key in _OPENAPI_COMPONENT_MAPS
+
 
-def _strip_openapi(obj: Any) -> Any:
+def _strip_openapi(
+    obj: Any,
+    *,
+    path: tuple = (),
+    preserve_keys: bool = False,
+) -> Any:
     """Recursively remove non-contract fields from an OpenAPI object.
 
     Drops:
     - All ``x-*`` extension keys (vendor-specific, non-standard).
     - ``description``, ``summary``, ``externalDocs``, ``example``, ``examples``
       at any nesting level (documentation-only fields).
+
+    Keys inside Schema Object ``properties``/``definitions``/``$defs`` maps
+    and ``components.schemas`` are user-defined identifiers.  Those map keys
+    are retained even when their spelling looks like an annotation; annotation
+    fields within the schema value are still removed.
     """
     if isinstance(obj, dict):
-        return {
-            k: _strip_openapi(v)
-            for k, v in obj.items()
-            if k not in _OPENAPI_STRIP_KEYS and not (isinstance(k, str) and k.startswith("x-"))
-        }
+        stripped = {}
+        for key, value in obj.items():
+            is_annotation = key in _OPENAPI_STRIP_KEYS or (
+                isinstance(key, str) and key.startswith("x-")
+            )
+            if is_annotation and not preserve_keys:
+                continue
+
+            # A named-map entry's value is a schema object.  Its arbitrary key
+            # must not make that schema object itself behave like a named map.
+            child_preserves_keys = (
+                not preserve_keys and _is_openapi_named_schema_map(path, key)
+            )
+            stripped[key] = _strip_openapi(
+                value,
+                path=path + (key,),
+                preserve_keys=child_preserves_keys,
+            )
+        return stripped
     if isinstance(obj, list):
-        return [_strip_openapi(item) for item in obj]
+        return [
+            _strip_openapi(
+                item,
+                path=path,
+                # Security Requirement Object keys are arbitrary scheme names.
+                preserve_keys=(path and path[-1] == "security"),
+            )
+            for item in obj
+        ]
     return obj
 
 
@@ -436,6 +594,7 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
                 errors=["No boundary paths declared for json-canonical provider"],
             )
         entries: List[tuple] = []
+        unmatched: List[str] = []
         for rel in sorted(paths):
             rel = rel.strip()
             if _is_glob(rel):
@@ -443,10 +602,13 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
                     status="error",
                     errors=[f"Glob patterns not supported by json-canonical provider: {rel}"],
                 )
-            full_base = f"{ctx.component_path}/{rel}".lstrip("/")
-            for repo_rel in sorted(ctx.list_files(full_base)):
+            full_base = _join_repo_path(ctx.component_path, rel)
+            matched_files = sorted(ctx.list_files(full_base))
+            if not matched_files:
+                unmatched.append(rel)
+            for repo_rel in matched_files:
                 raw = ctx.read_file(repo_rel)
-                child_rel = repo_rel[len(ctx.component_path) + 1:]
+                child_rel = _component_relative_path(ctx.component_path, repo_rel)
                 try:
                     obj = _json_mod.loads(raw.decode("utf-8"))
                 except (_json_mod.JSONDecodeError, UnicodeDecodeError) as exc:
@@ -458,6 +620,14 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
                     obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False
                 )
                 entries.append((f"canonical:{child_rel}", canonical.encode("utf-8")))
+        if unmatched:
+            return ResolvedBoundary(
+                status="error",
+                errors=[
+                    f"Declared boundary path matched no tracked files: {rel}"
+                    for rel in unmatched
+                ],
+            )
         if not entries:
             return ResolvedBoundary(
                 status="error",
@@ -513,7 +683,8 @@ class OpenApiCanonicalProvider:
     """
 
     name = "openapi-canonical"
-    version = "1"
+    # v2 preserves annotation-looking user-defined schema/property names.
+    version = "2"
 
     def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
         paths = ctx.boundary_cfg.get("paths", [])
@@ -523,6 +694,7 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
                 errors=["No boundary paths declared for openapi-canonical provider"],
             )
         entries: List[tuple] = []
+        unmatched: List[str] = []
         for rel in sorted(paths):
             rel = rel.strip()
             if _is_glob(rel):
@@ -530,10 +702,13 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
                     status="error",
                     errors=[f"Glob patterns not supported by openapi-canonical provider: {rel}"],
                 )
-            full_base = f"{ctx.component_path}/{rel}".lstrip("/")
-            for repo_rel in sorted(ctx.list_files(full_base)):
+            full_base = _join_repo_path(ctx.component_path, rel)
+            matched_files = sorted(ctx.list_files(full_base))
+            if not matched_files:
+                unmatched.append(rel)
+            for repo_rel in matched_files:
                 raw = ctx.read_file(repo_rel)
-                child_rel = repo_rel[len(ctx.component_path) + 1:]
+                child_rel = _component_relative_path(ctx.component_path, repo_rel)
                 try:
                     obj = _parse_yaml_or_json(raw, child_rel)
                 except ValueError as exc:
@@ -546,6 +721,14 @@ def resolve(self, ctx: ProviderContext) -> ResolvedBoundary:
                     contract, sort_keys=True, separators=(",", ":"), ensure_ascii=False
                 )
                 entries.append((f"canonical:{child_rel}", canonical.encode("utf-8")))
+        if unmatched:
+            return ResolvedBoundary(
+                status="error",
+                errors=[
+                    f"Declared boundary path matched no tracked files: {rel}"
+                    for rel in unmatched
+                ],
+            )
         if not entries:
             return ResolvedBoundary(
                 status="error",
@@ -582,10 +765,32 @@ def explain_diff(
 # Provider registry
 # ---------------------------------------------------------------------------
 
-_REGISTRY: Dict[str, BoundaryProvider] = {}
+_BUILTIN_PROVIDER_TYPES = (
+    OpenApiProvider,
+    JsonFileProvider,
+    PythonExportsProvider,
+    TypeScriptExportsProvider,
+    ImplicitProvider,
+    LeafProvider,
+    JsonCanonicalProvider,
+    OpenApiCanonicalProvider,
+)
+
+# Raw-hash aliases make the behavior explicit while preserving short names.
+_ALIASES = {
+    "openapi-raw": "openapi",
+    "json-file-raw": "json-file",
+    "python-exports-raw": "python-exports",
+    "typescript-exports-raw": "typescript-exports",
+}
+
+_REGISTRY: ProviderRegistry = {}
 
 
-def register_provider(p: BoundaryProvider, registry: Optional[Dict[str, "BoundaryProvider"]] = None) -> None:
+def register_provider(
+    p: BoundaryProvider,
+    registry: Optional[ProviderRegistry] = None,
+) -> None:
     """Register a provider instance. Overwrites any existing entry with the same name.
 
     If *registry* is provided, registers into that dict instead of the global registry.
@@ -594,7 +799,10 @@ def register_provider(p: BoundaryProvider, registry: Optional[Dict[str, "Boundar
     target[p.name] = p
 
 
-def get_provider(name: str, registry: Optional[Dict[str, "BoundaryProvider"]] = None) -> Optional[BoundaryProvider]:
+def get_provider(
+    name: str,
+    registry: Optional[ProviderRegistry] = None,
+) -> Optional[BoundaryProvider]:
     """Return the registered provider for *name*, or None.
 
     If *registry* is provided, looks up from that dict instead of the global registry.
@@ -603,21 +811,13 @@ def get_provider(name: str, registry: Optional[Dict[str, "BoundaryProvider"]] =
     return target.get(name)
 
 
-def create_registry() -> Dict[str, BoundaryProvider]:
+def create_registry() -> ProviderRegistry:
     """Create a fresh registry populated with builtins. Useful for isolated testing or
     running multiple configs with different custom providers in the same process."""
-    reg: Dict[str, BoundaryProvider] = {}
-    for cls in (
-        OpenApiProvider,
-        JsonFileProvider,
-        PythonExportsProvider,
-        TypeScriptExportsProvider,
-        ImplicitProvider,
-        LeafProvider,
-        JsonCanonicalProvider,
-        OpenApiCanonicalProvider,
-    ):
-        reg[cls().name] = cls()
+    reg: ProviderRegistry = {}
+    for cls in _BUILTIN_PROVIDER_TYPES:
+        provider = cls()
+        reg[provider.name] = provider
     for alias, target in _ALIASES.items():
         if target in reg:
             reg[alias] = reg[target]
@@ -625,33 +825,11 @@ def create_registry() -> Dict[str, BoundaryProvider]:
 
 
 def _register_builtins() -> None:
-    for cls in (
-        OpenApiProvider,
-        JsonFileProvider,
-        PythonExportsProvider,
-        TypeScriptExportsProvider,
-        ImplicitProvider,
-        LeafProvider,
-        JsonCanonicalProvider,
-        OpenApiCanonicalProvider,
-    ):
-        register_provider(cls())
+    _REGISTRY.update(create_registry())
 
 
 _register_builtins()
 
-# Aliases: raw-hash providers get explicit "-raw" names for clarity.
-# Users can write "openapi-raw" or "openapi" interchangeably.
-_ALIASES = {
-    "openapi-raw": "openapi",
-    "json-file-raw": "json-file",
-    "python-exports-raw": "python-exports",
-    "typescript-exports-raw": "typescript-exports",
-}
-for _alias, _target in _ALIASES.items():
-    if _target in _REGISTRY:
-        _REGISTRY[_alias] = _REGISTRY[_target]
-
 
 # ---------------------------------------------------------------------------
 # Custom provider loading (Phase 2)
@@ -660,7 +838,7 @@ def _register_builtins() -> None:
 def load_custom_providers(
     providers_list: list,
     allow_custom: bool,
-    registry: Optional[Dict[str, "BoundaryProvider"]] = None,
+    registry: Optional[ProviderRegistry] = None,
 ) -> List[str]:
     """Load and register custom providers declared in the config ``providers`` key.
 
@@ -677,7 +855,7 @@ def load_custom_providers(
     if not allow_custom:
         return [
             "Config declares custom providers but loading is not enabled. "
-            "Set \"allow_custom_providers\": true in your config or pass --allow-custom-providers."
+            "Pass --allow-custom-providers (or the equivalent trusted API argument)."
         ]
     errors: List[str] = []
     # Validate module names before importing anything to prevent injection via
@@ -685,9 +863,19 @@ def load_custom_providers(
     _VALID_MODULE_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$")
     _VALID_IDENT_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
     for entry in providers_list:
+        if not isinstance(entry, dict):
+            errors.append(
+                f"Provider entry must be an object, got {type(entry).__name__}"
+            )
+            continue
         module_name = entry.get("module", "")
         class_name = entry.get("class", "")
-        if not module_name or not class_name:
+        if (
+            not isinstance(module_name, str)
+            or not module_name
+            or not isinstance(class_name, str)
+            or not class_name
+        ):
             errors.append(
                 f"Provider entry missing required fields 'module'/'class': {entry!r}"
             )
diff --git a/src/boundver/versions.py b/src/boundver/versions.py
index c528e32..ffeb264 100644
--- a/src/boundver/versions.py
+++ b/src/boundver/versions.py
@@ -59,7 +59,12 @@ def extract_version(
     # Reject path traversal in version_source.file
     if ".." in file_rel.replace("\\", "/").split("/"):
         return None
-    repo_rel = f"{component_path}/{file_rel}"
+    component_prefix = component_path.strip().strip("/")
+    repo_rel = (
+        file_rel.lstrip("/")
+        if component_prefix in {"", "."}
+        else f"{component_prefix}/{file_rel.lstrip('/')}"
+    )
     if read_file_fn is not None:
         try:
             raw = read_file_fn(repo_rel)
@@ -318,7 +323,12 @@ def _extract_yaml_field(path: Path, field_path: str) -> Optional[str]:
 def parse_semver(version: Optional[str]) -> Tuple[Optional[str], Optional[str], Optional[str]]:
     if not version:
         return (None, None, None)
-    match = re.match(r"^v?(\d+)\.(\d+)(?:\.(\d+))?", version)
+    match = re.fullmatch(
+        r"v?(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\.(0|[1-9]\d*))?"
+        r"(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+        r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?",
+        version,
+    )
     if not match:
         return (None, None, version)
     major = match.group(1)
diff --git a/tests/test_boundary_lock.py b/tests/test_boundary_lock.py
index 33e213b..81cd88a 100644
--- a/tests/test_boundary_lock.py
+++ b/tests/test_boundary_lock.py
@@ -5,6 +5,7 @@
 import os
 import json
 import io
+import sys
 from contextlib import redirect_stdout
 
 import boundver.core as boundary_lock
@@ -33,7 +34,7 @@ def _run_cli(self, root: Path, *args: str) -> subprocess.CompletedProcess:
         repo_src = str(Path(__file__).resolve().parents[1] / "src")
         env["PYTHONPATH"] = repo_src + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else "")
         return subprocess.run(
-            ["python", "-m", "boundver.core", *args],
+            [sys.executable, "-m", "boundver", *args],
             cwd=root,
             capture_output=True,
             text=True,
@@ -265,7 +266,9 @@ def test_generate_lockfile_marks_partial_when_no_boundary_paths(self):
                 },
                 "slices": {},
             }
-            lock = boundary_lock.generate_lockfile(cfg, root, source="working-tree")
+            lock = boundary_lock.generate_lockfile(
+                cfg, root, source="working-tree", strict=False
+            )
             entry = lock["components"]["svc"]
             self.assertEqual(entry["boundary_status"], "partial")
             self.assertIn("No boundary paths declared for implicit boundary", entry.get("boundary_errors", []))
@@ -389,7 +392,54 @@ def test_discover_components_finds_common_manifests(self):
             self.assertEqual(comps["core"]["path"], "libs/core")
             # version_source.file must be relative to component path, not repo root
             self.assertEqual(comps["auth"]["version_source"]["file"], "package.json")
+            self.assertEqual(comps["auth"]["version_source"]["field"], "version")
             self.assertEqual(comps["core"]["version_source"]["file"], "pyproject.toml")
+            self.assertEqual(comps["core"]["version_source"]["field"], "project.version")
+
+    def test_discover_components_uses_tracked_manifests_and_deduplicates_dirs(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            (root / ".gitignore").write_text("ignored/\n")
+            (root / "packages" / "real").mkdir(parents=True)
+            (root / "packages" / "real" / "package.json").write_text(
+                '{"version":"2.0.0"}'
+            )
+            (root / "packages" / "real" / "pyproject.toml").write_text(
+                "[project]\nversion='2.0.0'\n"
+            )
+            (root / "crates" / "engine").mkdir(parents=True)
+            (root / "crates" / "engine" / "Cargo.toml").write_text(
+                "[package]\nversion='3.1.4'\n"
+            )
+            (root / "cmd" / "tool").mkdir(parents=True)
+            (root / "cmd" / "tool" / "go.mod").write_text(
+                "module example.com/tool\n"
+            )
+            (root / "ignored" / "dep").mkdir(parents=True)
+            (root / "ignored" / "dep" / "package.json").write_text(
+                '{"version":"9.9.9"}'
+            )
+            subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
+            subprocess.run(
+                ["git", "commit", "-m", "manifests"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+
+            components = boundary_lock.discover_components(root)
+
+            self.assertEqual(set(components), {"real", "engine", "tool"})
+            self.assertEqual(
+                components["real"]["version_source"],
+                {"file": "package.json", "field": "version"},
+            )
+            self.assertEqual(
+                components["engine"]["version_source"],
+                {"file": "Cargo.toml", "field": "package.version"},
+            )
+            self.assertIsNone(components["tool"]["version_source"])
 
     def test_discover_components_excludes_ignored_dirs(self):
         with tempfile.TemporaryDirectory() as td:
@@ -400,6 +450,8 @@ def test_discover_components_excludes_ignored_dirs(self):
             (root / ".venv" / "lib" / "pkg" / "pyproject.toml").write_text("[project]\nversion='0.1.0'\n")
             (root / "__pycache__" / "cached").mkdir(parents=True)
             (root / "__pycache__" / "cached" / "pyproject.toml").write_text("[project]\nversion='0.1.0'\n")
+            (root / "vendor" / "copied").mkdir(parents=True)
+            (root / "vendor" / "copied" / "package.json").write_text('{"version":"9.9.9"}')
             (root / "packages" / "real").mkdir(parents=True)
             (root / "packages" / "real" / "package.json").write_text('{"version":"2.0.0"}')
             comps = boundary_lock.discover_components(root)
@@ -536,7 +588,9 @@ def test_generate_lockfile_marks_error_for_explicit_kind_without_paths(self):
                 },
                 "slices": {},
             }
-            lock = boundary_lock.generate_lockfile(cfg, root, source="working-tree")
+            lock = boundary_lock.generate_lockfile(
+                cfg, root, source="working-tree", strict=False
+            )
             entry = lock["components"]["svc"]
             self.assertEqual(entry["boundary_status"], "error")
             self.assertIn(
@@ -921,7 +975,16 @@ def test_verify_lockfile_detects_new_removed_and_stale_components(self):
             self.assertTrue(any("NEW component not in lockfile: b" in i for i in new_issues), new_issues)
 
             # removed component
-            cfg_removed = {"project": "p", "components": {}, "slices": {}}
+            cfg_removed = {
+                "project": "p",
+                "components": {
+                    "b": {
+                        "path": "b",
+                        "boundary": {"provider": "openapi", "paths": ["api.yaml"]},
+                    }
+                },
+                "slices": {},
+            }
             removed_issues = boundary_lock.verify_lockfile(cfg_removed, lock, root, source="working-tree")
             self.assertTrue(any("REMOVED component still in lockfile: a" in i for i in removed_issues), removed_issues)
 
@@ -942,7 +1005,7 @@ def test_diff_lockfiles_uses_boundary_first_summary(self):
         self.assertEqual(len(diff["components"]["changed"]), 1)
         self.assertEqual(
             diff["components"]["changed"][0]["summary"],
-            "declared boundary changed (compatibility unchanged)",
+            "declared boundary changed; compatibility family is unchanged",
         )
 
     def test_generate_lockfile_reports_boundary_digest_failures(self):
@@ -1251,7 +1314,9 @@ def test_component_without_version_source_has_none_version(self):
                 },
                 "slices": {},
             }
-            lock = boundary_lock.generate_lockfile(cfg, root, source="working-tree")
+            lock = boundary_lock.generate_lockfile(
+                cfg, root, source="working-tree", strict=False
+            )
             self.assertIsNone(lock["components"]["svc"]["version"])
 
     def test_vendored_copy_drift_reported_as_warning(self):
@@ -2434,7 +2499,9 @@ def test_generate_lockfile_explicit_provider_no_paths_is_error(self):
                 },
                 "slices": {},
             }
-            lock = boundary_lock.generate_lockfile(cfg, root, source="working-tree")
+            lock = boundary_lock.generate_lockfile(
+                cfg, root, source="working-tree", strict=False
+            )
             self.assertEqual(lock["components"]["svc"]["boundary_status"], "error")
 
     # ------------------------------------------------------------------
@@ -2746,8 +2813,8 @@ def test_yaml_config_generates_lockfile(self):
     # changed_components_since_ref: git failure path
     # ------------------------------------------------------------------
 
-    def test_changed_components_since_ref_bad_ref_returns_empty(self):
-        """changed_components_since_ref returns [] when git diff fails (bad ref)."""
+    def test_changed_components_since_ref_bad_ref_raises(self):
+        """An invalid baseline must fail closed instead of skipping verification."""
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
             self._init_git_repo(root)
@@ -2760,8 +2827,10 @@ def test_changed_components_since_ref_bad_ref_returns_empty(self):
                 "components": {"svc": {"path": "svc", "boundary": {"provider": "implicit"}}},
                 "slices": {},
             }
-            result = boundary_lock.changed_components_since_ref(cfg, root, "nonexistent-ref-12345")
-            self.assertEqual(result, [])
+            with self.assertRaisesRegex(ValueError, "nonexistent-ref-12345"):
+                boundary_lock.changed_components_since_ref(
+                    cfg, root, "nonexistent-ref-12345"
+                )
 
     # ------------------------------------------------------------------
     # _lockfile_schema_issues
@@ -2779,7 +2848,7 @@ def test_lockfile_schema_issues_wrong_schema(self):
 
     def test_lockfile_schema_issues_correct_schema_passes(self):
         """_lockfile_schema_issues returns empty for correct schema."""
-        issues = boundary_lock._lockfile_schema_issues({"schema": "boundary-lock/v1"})
+        issues = boundary_lock._lockfile_schema_issues({"schema": "boundary-lock/v2"})
         self.assertEqual(issues, [])
 
 
@@ -2962,35 +3031,52 @@ def _minimal_v1(self, **extra):
         base.update(extra)
         return base
 
+    def _minimal_v2(self, **extra):
+        base = self._minimal_v1()
+        base["schema"] = "boundary-lock/v2"
+        base["components"]["svc"]["provider"] = {
+            "name": "implicit",
+            "version": "2",
+        }
+        base["components"]["svc"]["consumers"] = []
+        base.update(extra)
+        return base
+
     # ------------------------------------------------------------------
     # Unit tests for migrate_lockfile()
     # ------------------------------------------------------------------
 
-    def test_migrate_v1_schema_preserved(self):
-        from boundver._lockfile import LOCKFILE_SCHEMA, migrate_lockfile
-        result = migrate_lockfile(self._minimal_v1())
-        self.assertEqual(result["schema"], LOCKFILE_SCHEMA)
+    def test_migrate_v1_requires_regeneration(self):
+        from boundver._lockfile import MigrationError, migrate_lockfile
+
+        with self.assertRaises(MigrationError) as cm:
+            migrate_lockfile(self._minimal_v1())
+
+        message = str(cm.exception)
+        self.assertIn("cannot be migrated", message)
+        self.assertIn("boundver generate", message)
 
     def test_migrate_strips_generated_at(self):
         from boundver._lockfile import migrate_lockfile
-        lf = self._minimal_v1(generated_at="2024-01-01T00:00:00Z")
+        lf = self._minimal_v2(generated_at="2024-01-01T00:00:00Z")
         result = migrate_lockfile(lf)
         self.assertNotIn("generated_at", result)
 
     def test_migrate_does_not_mutate_input(self):
-        from boundver._lockfile import migrate_lockfile
+        from boundver._lockfile import MigrationError, migrate_lockfile
         lf = self._minimal_v1(generated_at="x")
-        migrate_lockfile(lf)
+        with self.assertRaises(MigrationError):
+            migrate_lockfile(lf)
         self.assertIn("generated_at", lf)  # original untouched
 
     def test_migrate_preserves_components(self):
         from boundver._lockfile import migrate_lockfile
-        result = migrate_lockfile(self._minimal_v1())
+        result = migrate_lockfile(self._minimal_v2())
         self.assertEqual(result["components"]["svc"]["fingerprints"]["exact"], "aaa")
 
     def test_migrate_adds_missing_components_and_slices(self):
         from boundver._lockfile import migrate_lockfile
-        lf = {"schema": "boundary-lock/v1", "project": "x"}
+        lf = {"schema": "boundary-lock/v2", "project": "x"}
         result = migrate_lockfile(lf)
         self.assertEqual(result["components"], {})
         self.assertEqual(result["slices"], {})
@@ -3011,7 +3097,7 @@ def test_migrate_no_schema_raises(self):
     def test_migrate_idempotent(self):
         """Running migrate twice gives the same result as running it once."""
         from boundver._lockfile import migrate_lockfile
-        lf = self._minimal_v1(generated_at="ts")
+        lf = self._minimal_v2(generated_at="ts")
         once = migrate_lockfile(lf)
         twice = migrate_lockfile(once)
         self.assertEqual(once, twice)
@@ -3053,21 +3139,20 @@ def test_cli_unknown_schema_exits_1(self):
             rc = self._run_migrate_cli(p)
             self.assertEqual(rc, 2)
 
-    def test_cli_writes_in_place_strips_generated_at(self):
+    def test_cli_v1_requires_regeneration_and_does_not_write(self):
         with tempfile.TemporaryDirectory() as td:
             p = Path(td) / "boundary.lock.json"
-            p.write_text(json.dumps(self._minimal_v1(generated_at="2020-01-01T00:00:00Z")))
+            original = json.dumps(self._minimal_v1(generated_at="2020-01-01T00:00:00Z"))
+            p.write_text(original)
             rc = self._run_migrate_cli(p)
-            self.assertEqual(rc, 0)
-            rewritten = json.loads(p.read_text())
-            self.assertNotIn("generated_at", rewritten)
-            self.assertEqual(rewritten["schema"], "boundary-lock/v1")
+            self.assertEqual(rc, 2)
+            self.assertEqual(p.read_text(), original)
 
     def test_cli_dry_run_does_not_write(self):
         import io, sys as _sys
         with tempfile.TemporaryDirectory() as td:
             p = Path(td) / "boundary.lock.json"
-            original = json.dumps(self._minimal_v1(generated_at="ts"))
+            original = json.dumps(self._minimal_v2(generated_at="ts"))
             p.write_text(original)
             buf = io.StringIO()
             old_stdout = _sys.stdout
diff --git a/tests/test_cli_main.py b/tests/test_cli_main.py
index 71dc6c9..2f74a88 100644
--- a/tests/test_cli_main.py
+++ b/tests/test_cli_main.py
@@ -275,7 +275,7 @@ def test_migrate_lock_relative_path(self):
         """migrate-lock accepts a relative path, resolves against cwd."""
         import os
         with tempfile.TemporaryDirectory() as td:
-            lf = {"schema": "boundary-lock/v1", "project": "x", "components": {}, "slices": {}}
+            lf = {"schema": "boundary-lock/v2", "project": "x", "components": {}, "slices": {}}
             (Path(td) / "boundary.lock.json").write_text(json.dumps(lf))
             old_dir = os.getcwd()
             os.chdir(td)
@@ -420,6 +420,378 @@ def test_verify_changed_from_with_components_filter_intersection(self):
             )
             self.assertEqual(code, 0)
 
+    def test_verify_facets_turn_exact_drift_into_observation(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            self._setup(root)
+            _run_main("generate", "--source", "working-tree", repo_root=root)
+            (root / "svc" / "main.py").write_text("internal refactor\n")
+
+            code, out, err = _run_main(
+                "verify",
+                "--source",
+                "working-tree",
+                "--facets",
+                "boundary,compat",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_OK, err)
+            payload = json.loads(out)
+            self.assertTrue(payload["ok"])
+            self.assertEqual(payload["issues"], [])
+            self.assertTrue(
+                any(".exact:" in observation for observation in payload["observations"]),
+                payload,
+            )
+
+    def test_verify_update_refreshes_observation_only_drift(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            self._setup(root)
+            _run_main("generate", "--source", "working-tree", repo_root=root)
+            (root / "svc" / "main.py").write_text("internal refactor\n")
+
+            code, out, err = _run_main(
+                "verify",
+                "--source",
+                "working-tree",
+                "--facets",
+                "boundary,compat",
+                "--update",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_OK, err)
+            payload = json.loads(out)
+            self.assertTrue(payload["ok"])
+            self.assertTrue(payload["updated"])
+            self.assertTrue(payload["observations"])
+
+            verify_code, _, verify_err = _run_main(
+                "verify",
+                "--source",
+                "working-tree",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+            self.assertEqual(verify_code, core.EXIT_OK, verify_err)
+
+    def test_verify_invalid_changed_from_exits_usage(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            self._setup(root)
+            subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
+            subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
+            _run_main("generate", "--source", "working-tree", repo_root=root)
+
+            code, _, err = _run_main(
+                "verify",
+                "--source",
+                "working-tree",
+                "--changed-from",
+                "not-a-real-ref",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_USAGE)
+            self.assertIn("not-a-real-ref", err)
+
+    def test_verify_changed_from_no_paths_still_checks_provider_version(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            self._setup(root)
+            subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
+            subprocess.run(
+                ["git", "commit", "-m", "baseline"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            code, _, err = _run_main(
+                "generate", "--source", "head", repo_root=root
+            )
+            self.assertEqual(code, core.EXIT_OK, err)
+            config = json.loads((root / "boundary.config.json").read_text())
+            self.assertEqual(
+                core.changed_components_since_ref(config, root, "HEAD"), []
+            )
+            lock_path = root / "boundary.lock.json"
+            lock = json.loads(lock_path.read_text())
+            lock["components"]["svc"]["boundary_provider_version"] = "tampered"
+            lock_path.write_text(json.dumps(lock) + "\n")
+
+            code, out, err = _run_main(
+                "verify",
+                "--source",
+                "head",
+                "--changed-from",
+                "HEAD",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_DRIFT, err)
+            payload = json.loads(out)
+            self.assertFalse(payload["ok"])
+            self.assertTrue(
+                any(
+                    "METADATA MISMATCH svc.boundary_provider_version" in issue
+                    for issue in payload["issues"]
+                ),
+                payload,
+            )
+
+    def test_verify_changed_from_checks_unselected_component_metadata(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            config = {
+                "project": "p",
+                "components": {
+                    "tagged": {
+                        "path": "tagged",
+                        "version_source": {"git_tag_prefix": "tagged-v"},
+                        "boundary": {"provider": "implicit"},
+                    },
+                    "other": {
+                        "path": "other",
+                        "boundary": {"provider": "implicit"},
+                    },
+                },
+                "slices": {},
+            }
+            (root / "boundary.config.json").write_text(json.dumps(config) + "\n")
+            for name in ("tagged", "other"):
+                (root / name).mkdir()
+                (root / name / "main.py").write_text(f"{name}\n")
+            subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
+            subprocess.run(
+                ["git", "commit", "-m", "baseline"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            subprocess.run(
+                ["git", "tag", "tagged-v1.0.0"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            code, _, err = _run_main("generate", "--source", "head", repo_root=root)
+            self.assertEqual(code, core.EXIT_OK, err)
+
+            lock_path = root / "boundary.lock.json"
+            lock = json.loads(lock_path.read_text())
+            lock["components"]["other"]["boundary_provider_version"] = "tampered"
+            lock_path.write_text(json.dumps(lock) + "\n")
+            subprocess.run(
+                ["git", "add", "boundary.lock.json"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            subprocess.run(
+                ["git", "commit", "-m", "stale metadata"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            self.assertEqual(
+                core.changed_components_since_ref(config, root, "HEAD"), ["tagged"]
+            )
+
+            code, out, err = _run_main(
+                "verify",
+                "--source",
+                "head",
+                "--changed-from",
+                "HEAD",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_DRIFT, err)
+            payload = json.loads(out)
+            self.assertEqual(payload["components_filter"], ["tagged"])
+            self.assertTrue(
+                any(
+                    "METADATA MISMATCH other.boundary_provider_version" in issue
+                    for issue in payload["issues"]
+                ),
+                payload,
+            )
+
+
+class MainMalformedV2LockTests(unittest.TestCase):
+    def _init_git_repo(self, root: Path) -> None:
+        subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
+        subprocess.run(["git", "config", "user.email", "t@t.com"], cwd=root, check=True, capture_output=True)
+        subprocess.run(["git", "config", "user.name", "T"], cwd=root, check=True, capture_output=True)
+
+    def _make_lock(self, root: Path) -> Path:
+        self._init_git_repo(root)
+        (root / "svc").mkdir()
+        (root / "svc" / "main.py").write_text("x=1\n")
+        config = {
+            "project": "p",
+            "components": {
+                "svc": {
+                    "path": "svc",
+                    "boundary": {"provider": "implicit"},
+                }
+            },
+            "slices": {
+                "all": {"mode": "exact", "components": ["svc"]},
+            },
+        }
+        (root / "boundary.config.json").write_text(json.dumps(config) + "\n")
+        code, _, err = _run_main(
+            "generate", "--source", "working-tree", repo_root=root
+        )
+        self.assertEqual(code, core.EXIT_OK, err)
+        return root / "boundary.lock.json"
+
+    def _assert_controlled_usage_error(self, mutator, expected_message: str) -> None:
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            lock_path = self._make_lock(root)
+            lock = json.loads(lock_path.read_text())
+            mutator(lock)
+            lock_path.write_text(json.dumps(lock) + "\n")
+
+            code, out, err = _run_main(
+                "verify", "--source", "working-tree", repo_root=root
+            )
+
+            combined = out + err
+            self.assertEqual(code, core.EXIT_USAGE, combined)
+            self.assertIn(expected_message, combined)
+            self.assertNotIn("Traceback", combined)
+
+    def test_non_string_consumer_is_a_controlled_usage_error(self):
+        self._assert_controlled_usage_error(
+            lambda lock: lock["components"]["svc"].__setitem__(
+                "consumers", ["client", 7]
+            ),
+            "consumers must be an array of unique strings",
+        )
+
+    def test_non_string_slice_component_is_a_controlled_usage_error(self):
+        self._assert_controlled_usage_error(
+            lambda lock: lock["slices"]["all"].__setitem__(
+                "components", ["svc", 7]
+            ),
+            "slice 'all' components must be an array of strings",
+        )
+
+
+class MainSeverityAndConsumerTests(unittest.TestCase):
+    def _init_git_repo(self, root: Path) -> None:
+        subprocess.run(["git", "init"], cwd=root, check=True, capture_output=True)
+        subprocess.run(["git", "config", "user.email", "t@t.com"], cwd=root, check=True, capture_output=True)
+        subprocess.run(["git", "config", "user.name", "T"], cwd=root, check=True, capture_output=True)
+
+    def test_boundary_drift_uses_exit_4_and_lists_consumers(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            (root / "api").mkdir()
+            (root / "api" / "openapi.yaml").write_text("openapi: 3.0.0\npaths: {}\n")
+            (root / "client").mkdir()
+            (root / "client" / "main.py").write_text("pass\n")
+            cfg = {
+                "project": "p",
+                "components": {
+                    "api": {
+                        "path": "api",
+                        "boundary": {"provider": "openapi", "paths": ["openapi.yaml"]},
+                        "consumers": ["client"],
+                    },
+                    "client": {"path": "client", "boundary": {"provider": "leaf"}},
+                },
+                "slices": {},
+            }
+            (root / "boundary.config.json").write_text(json.dumps(cfg) + "\n")
+            code, _, err = _run_main(
+                "generate", "--source", "working-tree", repo_root=root
+            )
+            self.assertEqual(code, core.EXIT_OK, err)
+            generated = json.loads((root / "boundary.lock.json").read_text())
+            self.assertEqual(generated["components"]["api"]["consumers"], ["client"])
+            (root / "api" / "openapi.yaml").write_text(
+                "openapi: 3.0.0\npaths:\n  /widgets: {}\n"
+            )
+
+            code, out, err = _run_main(
+                "verify",
+                "--source",
+                "working-tree",
+                "--facets",
+                "boundary,compat",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_BOUNDARY, err)
+            payload = json.loads(out)
+            self.assertTrue(any("MISMATCH api.boundary" in issue for issue in payload["issues"]))
+            self.assertTrue(
+                any("AFFECTED CONSUMERS api: client" in issue for issue in payload["issues"]),
+                payload,
+            )
+
+    def test_compat_drift_uses_exit_5(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            self._init_git_repo(root)
+            (root / "svc").mkdir()
+            (root / "svc" / "version.json").write_text('{"version": "1.0.0"}\n')
+            cfg = {
+                "project": "p",
+                "defaults": {"compat_mode": "major"},
+                "components": {
+                    "svc": {
+                        "path": "svc",
+                        "boundary": {"provider": "leaf"},
+                        "version_source": {"file": "version.json", "field": "version"},
+                    }
+                },
+                "slices": {},
+            }
+            (root / "boundary.config.json").write_text(json.dumps(cfg) + "\n")
+            code, _, err = _run_main(
+                "generate", "--source", "working-tree", repo_root=root
+            )
+            self.assertEqual(code, core.EXIT_OK, err)
+            (root / "svc" / "version.json").write_text('{"version": "2.0.0"}\n')
+
+            code, out, err = _run_main(
+                "verify",
+                "--source",
+                "working-tree",
+                "--format",
+                "json",
+                repo_root=root,
+            )
+
+            self.assertEqual(code, core.EXIT_COMPAT, err)
+            self.assertTrue(
+                any("MISMATCH svc.compat" in issue for issue in json.loads(out)["issues"])
+            )
+
 
 class MainDiffTests(unittest.TestCase):
     def test_diff_identical_lockfiles_text(self):
@@ -904,7 +1276,7 @@ def test_migrate_lock_unknown_schema_exits_1(self):
     def test_migrate_lock_dry_run_prints_json_no_write(self):
         with tempfile.TemporaryDirectory() as td:
             p = Path(td) / "boundary.lock.json"
-            lf = {"schema": "boundary-lock/v1", "project": "x", "components": {}, "slices": {}, "generated_at": "ts"}
+            lf = {"schema": "boundary-lock/v2", "project": "x", "components": {}, "slices": {}, "generated_at": "ts"}
             original = json.dumps(lf)
             p.write_text(original)
             code, out, _ = _run_main("migrate-lock", "--lock", str(p), "--dry-run")
@@ -916,7 +1288,7 @@ def test_migrate_lock_dry_run_prints_json_no_write(self):
     def test_migrate_lock_writes_in_place(self):
         with tempfile.TemporaryDirectory() as td:
             p = Path(td) / "boundary.lock.json"
-            lf = {"schema": "boundary-lock/v1", "project": "x", "components": {}, "slices": {}, "generated_at": "ts"}
+            lf = {"schema": "boundary-lock/v2", "project": "x", "components": {}, "slices": {}, "generated_at": "ts"}
             p.write_text(json.dumps(lf))
             code, _, _ = _run_main("migrate-lock", "--lock", str(p))
             self.assertEqual(code, 0)
@@ -1237,7 +1609,7 @@ def test_generate_json_includes_behavior_fingerprint(self):
             self.assertEqual(len(fp["behavior"]), 64)
 
     def test_verify_detects_behavior_drift_via_cli(self):
-        """verify exits 1 when behavior fingerprint drifts."""
+        """verify uses the behavior-specific exit code when behavior drifts."""
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
             self._init_git_repo(root)
@@ -1247,7 +1619,7 @@ def test_verify_detects_behavior_drift_via_cli(self):
             # Change behavior-relevant file
             (root / "svc" / "config.json").write_text('{"timeout": 5}\n')
             code, out, _ = _run_main("verify", "--source", "working-tree", repo_root=root)
-            self.assertEqual(code, 1)
+            self.assertEqual(code, core.EXIT_BEHAVIOR)
 
     def test_verify_json_reports_behavior_mismatch(self):
         """verify --format json reports behavior mismatch in issues."""
@@ -1260,7 +1632,7 @@ def test_verify_json_reports_behavior_mismatch(self):
             code, out, _ = _run_main(
                 "verify", "--source", "working-tree", "--format", "json", repo_root=root
             )
-            self.assertEqual(code, 1)
+            self.assertEqual(code, core.EXIT_BEHAVIOR)
             payload = json.loads(out)
             behavior_issues = [i for i in payload["issues"] if "behavior" in i]
             self.assertGreater(len(behavior_issues), 0)
diff --git a/tests/test_cli_output_schemas.py b/tests/test_cli_output_schemas.py
index 4ecca6c..0189ec4 100644
--- a/tests/test_cli_output_schemas.py
+++ b/tests/test_cli_output_schemas.py
@@ -6,6 +6,7 @@
 declares as required is actually present in live output.
 """
 import json
+import os
 import subprocess
 import sys
 import tempfile
@@ -72,30 +73,44 @@ def _make_repo(self) -> tuple:
         _commit_all(root)
         return root, cfg
 
+    def _run_cli(self, root: Path, *args: str) -> subprocess.CompletedProcess:
+        env = os.environ.copy()
+        env["PYTHONPATH"] = str(ROOT / "src")
+        return subprocess.run(
+            [sys.executable, "-m", "boundver", *args],
+            cwd=root,
+            env=env,
+            capture_output=True,
+            text=True,
+        )
+
     def test_verify_output_schema(self):
         schema = _load_schema("cli-output.verify.schema.json")
-        root, cfg = self._make_repo()
+        root, _cfg = self._make_repo()
         try:
-            from boundver.core import generate_lockfile, verify_lockfile
-            lock = generate_lockfile(cfg, root, source="head")
-            issues = verify_lockfile(cfg, lock, root, source="head")
-            output = {"ok": len(issues) == 0, "issues": issues, "components_filter": []}
-            _assert_valid(schema, output)
-            # also with components_filter populated
-            output2 = {"ok": True, "issues": [], "components_filter": ["svc"]}
-            _assert_valid(schema, output2)
+            generated = self._run_cli(root, "generate", "--format", "json")
+            self.assertEqual(generated.returncode, 0, generated.stderr)
+            verified = self._run_cli(root, "verify", "--format", "json")
+            self.assertEqual(verified.returncode, 0, verified.stderr)
+            _assert_valid(schema, json.loads(verified.stdout))
+
+            filtered = self._run_cli(
+                root, "verify", "--components", "svc", "--format", "json"
+            )
+            self.assertEqual(filtered.returncode, 0, filtered.stderr)
+            _assert_valid(schema, json.loads(filtered.stdout))
         finally:
             import shutil; shutil.rmtree(root, ignore_errors=True)
 
     def test_status_output_schema(self):
         schema = _load_schema("cli-output.status.schema.json")
-        root, cfg = self._make_repo()
+        root, _cfg = self._make_repo()
         try:
-            from boundver.core import generate_lockfile, verify_lockfile
-            lock = generate_lockfile(cfg, root, source="head")
-            issues = verify_lockfile(cfg, lock, root, source="head")
-            output = {"lockfile": lock, "issues": issues}
-            _assert_valid(schema, output)
+            generated = self._run_cli(root, "generate", "--format", "json")
+            self.assertEqual(generated.returncode, 0, generated.stderr)
+            status = self._run_cli(root, "status", "--format", "json")
+            self.assertEqual(status.returncode, 0, status.stderr)
+            _assert_valid(schema, json.loads(status.stdout))
         finally:
             import shutil; shutil.rmtree(root, ignore_errors=True)
 
diff --git a/tests/test_core_branches.py b/tests/test_core_branches.py
index 2102aa2..fad9bca 100644
--- a/tests/test_core_branches.py
+++ b/tests/test_core_branches.py
@@ -62,7 +62,9 @@ def test_semver_major_minor_no_tag_gives_null_compat(self):
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
             # No tag → version = None → compat = None
-            lockfile = core.generate_lockfile(cfg, root, source="head")
+            lockfile = core.generate_lockfile(
+                cfg, root, source="head", strict=False
+            )
             fp = lockfile["components"]["svc"]["fingerprints"]
             self.assertIsNone(fp["compat"])
 
@@ -87,7 +89,9 @@ def test_unknown_boundary_provider_recorded_as_error(self):
                 },
                 "slices": {},
             }
-            lockfile = core.generate_lockfile(cfg, root, source="working-tree")
+            lockfile = core.generate_lockfile(
+                cfg, root, source="working-tree", strict=False
+            )
             comp = lockfile["components"]["svc"]
             self.assertEqual(comp["boundary_status"], "error")
             self.assertIsNone(comp["fingerprints"]["boundary"])
@@ -218,20 +222,49 @@ def test_unknown_component_raises(self):
                 )
             self.assertIn("Unknown", str(cm.exception))
 
-    def test_creates_fresh_lockfile_when_none_exists(self):
-        """Line 247: generate_lockfile_for_components starts fresh when out_path missing."""
+    def test_missing_existing_lockfile_requires_full_generation(self):
+        """A subset cannot silently create an incomplete first lockfile."""
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
             _init_git_repo(root)
             cfg = self._setup(root)
             out_path = root / "boundary.lock.json"
             self.assertFalse(out_path.exists())
-            result = core.generate_lockfile_for_components(
-                cfg, root, ["svc"],
-                out_path=out_path,
-                source="working-tree",
+            with self.assertRaisesRegex(ValueError, "full `boundver generate`"):
+                core.generate_lockfile_for_components(
+                    cfg,
+                    root,
+                    ["svc"],
+                    out_path=out_path,
+                    source="working-tree",
+                )
+
+    def test_non_v2_existing_lockfile_requires_full_generation(self):
+        """Partial updates must not mix v1 and v2 hashing contracts."""
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_git_repo(root)
+            cfg = self._setup(root)
+            out_path = root / "boundary.lock.json"
+            out_path.write_text(
+                json.dumps(
+                    {
+                        "schema": "boundary-lock/v1",
+                        "project": "p",
+                        "components": {},
+                        "slices": {},
+                    }
+                )
             )
-            self.assertIn("svc", result["components"])
+
+            with self.assertRaisesRegex(ValueError, "boundary-lock/v2"):
+                core.generate_lockfile_for_components(
+                    cfg,
+                    root,
+                    ["svc"],
+                    out_path=out_path,
+                    source="working-tree",
+                )
 
     def test_merges_into_existing_lockfile(self):
         """generate_lockfile_for_components merges into an existing lockfile."""
@@ -580,13 +613,14 @@ class ValidateConfigMiscBranchTests(unittest.TestCase):
     """Additional validate_config branches for coverage."""
 
     def test_load_config_schema_invalid_json(self):
-        """_load_config_schema returns None when schema file is invalid JSON."""
+        """An invalid repository schema falls back to the bundled schema."""
         from boundver._config import _load_config_schema
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
             (root / "boundary.config.schema.json").write_text("not valid json {{{")
             result = _load_config_schema(root)
-            self.assertIsNone(result)
+            self.assertIsInstance(result, dict)
+            self.assertIn("components", result.get("properties", {}))
 
     def test_validate_config_non_dict_returns_error(self):
         """validate_config with non-dict input returns an error immediately."""
@@ -1065,16 +1099,21 @@ def test_why_shows_version_when_present(self):
             self._init_git_repo(root)
             (root / "svc").mkdir()
             (root / "svc" / "api.yaml").write_text("openapi: 3.0.0\n")
+            (root / "svc" / "version.json").write_text('{"version": "1.0.0"}\n')
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
             cfg = {
                 "project": "p",
-                "components": {"svc": {"path": "svc", "boundary": {"provider": "openapi", "paths": ["api.yaml"]}}},
+                "components": {
+                    "svc": {
+                        "path": "svc",
+                        "boundary": {"provider": "openapi", "paths": ["api.yaml"]},
+                        "version_source": {"file": "version.json", "field": "version"},
+                    }
+                },
                 "slices": {},
             }
             lockfile = core.generate_lockfile(cfg, root)
-            # Manually inject a version
-            lockfile["components"]["svc"]["version"] = "1.0.0"
             out = io.StringIO()
             with redirect_stdout(out):
                 rc = core.why_component(cfg, lockfile, root, "svc")
@@ -1106,10 +1145,10 @@ def test_all_components_missing_gives_all_none(self):
 
 
 class ValidateConfigCustomProviderListTests(unittest.TestCase):
-    """Validate provider declared in component but not in providers list."""
+    """Validate explicit custom-provider names against component references."""
 
-    def test_custom_provider_in_component_not_in_providers_list(self):
-        """Component uses custom.X but providers list doesn't include it (lines 234-235)."""
+    def test_implicit_provider_name_is_resolved_only_after_loading(self):
+        """A class-only declaration cannot be name-checked before trusted loading."""
         import tempfile
         from boundver._config import validate_config
         with tempfile.TemporaryDirectory() as td:
@@ -1127,11 +1166,37 @@ def test_custom_provider_in_component_not_in_providers_list(self):
                 "slices": {},
             }
             errors = validate_config(cfg, root)
-            self.assertTrue(
+            self.assertFalse(
                 any("not declared in the" in e for e in errors),
-                f"Expected 'not declared in the' error, got: {errors}",
+                f"Unexpected name cross-reference error: {errors}",
             )
 
+    def test_explicit_provider_name_must_match_component_reference(self):
+        from boundver._config import validate_config
+
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            (root / "svc").mkdir()
+            cfg = {
+                "project": "p",
+                "providers": [
+                    {
+                        "module": "custom_pkg",
+                        "class": "OtherProvider",
+                        "name": "custom.OtherProvider",
+                    }
+                ],
+                "components": {
+                    "svc": {
+                        "path": "svc",
+                        "boundary": {"provider": "custom.MyProvider"},
+                    }
+                },
+                "slices": {},
+            }
+            errors = validate_config(cfg, root)
+            self.assertTrue(any("not declared in the" in e for e in errors), errors)
+
 
 class ExplainGitDiffFailureTests(unittest.TestCase):
     """explain_component_changes returns exit 2 when git diff fails."""
@@ -1450,41 +1515,30 @@ def test_list_head_files_cat_file_fallback_via_mock(self):
         from unittest.mock import patch, MagicMock
         from boundver._git import list_head_files
 
-        call_count = [0]
-
-        def fake_git_run(repo_root, args, **kw):
-            call_count[0] += 1
-            result = MagicMock()
-            if "ls-tree" in args:
-                result.stdout = ""  # Empty → triggers cat-file fallback
-            else:
-                # cat-file -t → returns "blob"
-                result.stdout = "blob"
-            return result
-
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
-            with patch("boundver._git._git_run", side_effect=fake_git_run):
+            ls_tree = MagicMock(stdout=b"")
+            cat_file = MagicMock(stdout="blob")
+            with patch("boundver._git._git_run_bytes", return_value=ls_tree) as run_bytes, patch(
+                "boundver._git._git_run", return_value=cat_file
+            ) as run_text:
                 result = list_head_files(root, "readme.txt")
             self.assertEqual(result, ["readme.txt"])
-            self.assertEqual(call_count[0], 2)  # ls-tree + cat-file
+            run_bytes.assert_called_once()
+            run_text.assert_called_once()
 
     def test_list_head_files_cat_file_not_blob_returns_empty(self):
         """When cat-file -t returns 'tree' (not 'blob'), returns [] (line 139 false branch)."""
         from unittest.mock import patch, MagicMock
         from boundver._git import list_head_files
 
-        def fake_git_run(repo_root, args, **kw):
-            result = MagicMock()
-            if "ls-tree" in args:
-                result.stdout = ""
-            else:
-                result.stdout = "tree"  # Not a blob
-            return result
-
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
-            with patch("boundver._git._git_run", side_effect=fake_git_run):
+            with patch(
+                "boundver._git._git_run_bytes", return_value=MagicMock(stdout=b"")
+            ), patch(
+                "boundver._git._git_run", return_value=MagicMock(stdout="tree")
+            ):
                 result = list_head_files(root, "somedir")
             self.assertEqual(result, [])
 
@@ -1494,20 +1548,14 @@ def test_list_head_files_cat_file_raises_returns_empty(self):
         import subprocess as _sp
         from boundver._git import list_head_files
 
-        call_count = [0]
-
-        def fake_git_run(repo_root, args, **kw):
-            call_count[0] += 1
-            if "ls-tree" in args:
-                result = MagicMock()
-                result.stdout = ""
-                return result
-            # cat-file -t → raises
-            raise _sp.CalledProcessError(128, "git")
-
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
-            with patch("boundver._git._git_run", side_effect=fake_git_run):
+            with patch(
+                "boundver._git._git_run_bytes", return_value=MagicMock(stdout=b"")
+            ), patch(
+                "boundver._git._git_run",
+                side_effect=_sp.CalledProcessError(128, "git"),
+            ):
                 result = list_head_files(root, "missingfile.txt")
             self.assertEqual(result, [])
 
@@ -1793,7 +1841,9 @@ def test_behavior_generation_survives_unknown_boundary_provider(self):
                 "slices": {},
             }
 
-            lockfile = core.generate_lockfile(cfg, root, source="head")
+            lockfile = core.generate_lockfile(
+                cfg, root, source="head", strict=False
+            )
 
             self.assertEqual(lockfile["components"]["svc"]["boundary_status"], "error")
             self.assertIsNone(lockfile["components"]["svc"]["fingerprints"]["boundary"])
@@ -2197,7 +2247,7 @@ def test_behavior_only_change_summary(self):
         changed = result["components"]["changed"]
         self.assertEqual(len(changed), 1)
         self.assertIn("behavioral", changed[0]["summary"].lower())
-        self.assertIn("stable", changed[0]["summary"].lower())
+        self.assertIn("unchanged", changed[0]["summary"].lower())
 
     def test_exact_only_still_impl_only(self):
         """diff with only exact changed still says implementation-only."""
@@ -2433,10 +2483,10 @@ def test_behavior_digest_null_on_subprocess_error(self):
             from boundver import _lockfile
             original_fn = _lockfile.compute_boundary
 
-            def _raising_compute(provider, ctx):
+            def _raising_compute(provider, ctx, **kwargs):
                 if provider.name == "behavior":
                     raise subprocess.CalledProcessError(128, "git")
-                return original_fn(provider, ctx)
+                return original_fn(provider, ctx, **kwargs)
 
             with patch.object(_lockfile, "compute_boundary", side_effect=_raising_compute):
                 lockfile = _lockfile.generate_lockfile(cfg, root, source="head", strict=False)
@@ -2469,10 +2519,10 @@ def test_behavior_digest_null_on_oserror(self):
             }
             original_fn = _lockfile.compute_boundary
 
-            def _raising_compute(provider, ctx):
+            def _raising_compute(provider, ctx, **kwargs):
                 if provider.name == "behavior":
                     raise OSError("disk error")
-                return original_fn(provider, ctx)
+                return original_fn(provider, ctx, **kwargs)
 
             with patch.object(_lockfile, "compute_boundary", side_effect=_raising_compute):
                 lockfile = _lockfile.generate_lockfile(cfg, root, source="head", strict=False)
@@ -2503,10 +2553,10 @@ def test_behavior_digest_null_on_value_error(self):
             }
             original_fn = _lockfile.compute_boundary
 
-            def _raising_compute(provider, ctx):
+            def _raising_compute(provider, ctx, **kwargs):
                 if provider.name == "behavior":
                     raise ValueError("bad config")
-                return original_fn(provider, ctx)
+                return original_fn(provider, ctx, **kwargs)
 
             with patch.object(_lockfile, "compute_boundary", side_effect=_raising_compute):
                 lockfile = _lockfile.generate_lockfile(cfg, root, source="head", strict=False)
diff --git a/tests/test_coverage_gaps.py b/tests/test_coverage_gaps.py
index 5c07660..694b8cd 100644
--- a/tests/test_coverage_gaps.py
+++ b/tests/test_coverage_gaps.py
@@ -153,21 +153,20 @@ def setUp(self):
             cwd=self.tmpdir, capture_output=True, check=True,
         )
 
-    def test_missing_ref_returns_empty_bytes(self):
-        result = _git_batch_cat(Path(self.tmpdir), ["HEAD:nonexistent.txt"])
-        self.assertEqual(result["HEAD:nonexistent.txt"], b"")
+    def test_missing_ref_raises(self):
+        with self.assertRaisesRegex(ValueError, "not found"):
+            _git_batch_cat(Path(self.tmpdir), ["HEAD:nonexistent.txt"])
 
     def test_existing_ref_returns_content(self):
         result = _git_batch_cat(Path(self.tmpdir), ["HEAD:hello.txt"])
         self.assertEqual(result["HEAD:hello.txt"], b"hello world\n")
 
-    def test_mixed_existing_and_missing(self):
-        result = _git_batch_cat(
-            Path(self.tmpdir),
-            ["HEAD:hello.txt", "HEAD:missing.txt"],
-        )
-        self.assertEqual(result["HEAD:hello.txt"], b"hello world\n")
-        self.assertEqual(result["HEAD:missing.txt"], b"")
+    def test_mixed_existing_and_missing_raises(self):
+        with self.assertRaisesRegex(ValueError, "not found"):
+            _git_batch_cat(
+                Path(self.tmpdir),
+                ["HEAD:hello.txt", "HEAD:missing.txt"],
+            )
 
     def test_empty_refs_returns_empty_dict(self):
         result = _git_batch_cat(Path(self.tmpdir), [])
diff --git a/tests/test_edge_cases.py b/tests/test_edge_cases.py
index a58514d..1e2e022 100644
--- a/tests/test_edge_cases.py
+++ b/tests/test_edge_cases.py
@@ -52,16 +52,16 @@ def test_ref_with_carriage_return_raises(self):
                 _git_batch_cat(root, ["HEAD:some\rfile"])
             self.assertIn("newline", str(cm.exception))
 
-    def test_missing_object_returns_empty_bytes(self):
-        """Non-existent paths return empty bytes."""
+    def test_missing_object_raises(self):
+        """Non-existent paths fail closed."""
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
             _init_git_repo(root)
             (root / "x.txt").write_text("hello\n")
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
-            result = _git_batch_cat(root, ["HEAD:nonexistent.txt"])
-            self.assertEqual(result["HEAD:nonexistent.txt"], b"")
+            with self.assertRaisesRegex(ValueError, "not found"):
+                _git_batch_cat(root, ["HEAD:nonexistent.txt"])
 
     def test_empty_refs_returns_empty_dict(self):
         """Empty refs list returns empty dict immediately."""
@@ -257,8 +257,8 @@ def test_tag_on_other_branch_via_fallback(self):
 class ChangedComponentsSinceRefTests(unittest.TestCase):
     """Tests for changed_components_since_ref."""
 
-    def test_invalid_ref_returns_empty(self):
-        """Non-existent ref returns empty list."""
+    def test_invalid_ref_raises(self):
+        """A non-existent ref fails closed instead of selecting no components."""
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
             _init_git_repo(root)
@@ -266,8 +266,8 @@ def test_invalid_ref_returns_empty(self):
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
             config = {"components": {"svc": {"path": "svc"}}}
-            result = changed_components_since_ref(config, root, "nonexistent_ref_xyz")
-            self.assertEqual(result, [])
+            with self.assertRaisesRegex(ValueError, "Unable to diff"):
+                changed_components_since_ref(config, root, "nonexistent_ref_xyz")
 
     def test_detects_changed_component(self):
         """Correctly identifies component with changed files."""
@@ -853,18 +853,27 @@ def test_verify_detects_removed_component(self):
             _init_git_repo(root)
             (root / "svc").mkdir()
             (root / "svc" / "main.py").write_text("x=1\n")
+            (root / "keep").mkdir()
+            (root / "keep" / "main.py").write_text("y=1\n")
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
             cfg = {
                 "project": "p",
                 "components": {
                     "svc": {"path": "svc", "boundary": {"provider": "implicit"}},
+                    "keep": {"path": "keep", "boundary": {"provider": "implicit"}},
                 },
                 "slices": {},
             }
             lockfile = _lockfile.generate_lockfile(cfg, root, source="head")
             # Now verify with config that removed 'svc'
-            cfg_without = {"project": "p", "components": {}, "slices": {}}
+            cfg_without = {
+                "project": "p",
+                "components": {
+                    "keep": {"path": "keep", "boundary": {"provider": "implicit"}},
+                },
+                "slices": {},
+            }
             issues = _lockfile.verify_lockfile(cfg_without, lockfile, root, source="head")
             self.assertTrue(any("REMOVED" in i for i in issues))
 
diff --git a/tests/test_hashing.py b/tests/test_hashing.py
index 7fc70c9..a9a4938 100644
--- a/tests/test_hashing.py
+++ b/tests/test_hashing.py
@@ -457,8 +457,8 @@ def test_reads_committed_blob(self):
             blobs = _git_batch_cat(root, ["HEAD:hello.txt"])
             self.assertEqual(blobs["HEAD:hello.txt"], b"hello world\n")
 
-    def test_missing_object_maps_to_empty_bytes(self):
-        """_git_batch_cat maps missing objects to b''."""
+    def test_missing_object_raises(self):
+        """_git_batch_cat fails closed for a missing object."""
         from boundver.core import _git_batch_cat
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
@@ -466,8 +466,8 @@ def test_missing_object_maps_to_empty_bytes(self):
             (root / "f.txt").write_text("x\n")
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
-            blobs = _git_batch_cat(root, ["HEAD:nonexistent.txt"])
-            self.assertEqual(blobs["HEAD:nonexistent.txt"], b"")
+            with self.assertRaisesRegex(ValueError, "not found"):
+                _git_batch_cat(root, ["HEAD:nonexistent.txt"])
 
     def test_multiple_refs_returned_correctly(self):
         """_git_batch_cat returns correct content for each ref in a batch."""
@@ -490,8 +490,8 @@ def test_git_batch_cat_error_raises_called_process_error(self):
         with self.assertRaises(subprocess.CalledProcessError):
             _git_batch_cat(Path("/nonexistent-repo-xyz"), ["HEAD:file.txt"])
 
-    def test_git_batch_cat_missing_object_maps_to_empty_bytes(self):
-        """_git_batch_cat returns b'' for objects marked 'missing' in batch output."""
+    def test_git_batch_cat_missing_object_raises(self):
+        """_git_batch_cat raises for objects marked missing in batch output."""
         from boundver.core import _git_batch_cat
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
@@ -499,8 +499,8 @@ def test_git_batch_cat_missing_object_maps_to_empty_bytes(self):
             (root / "f.txt").write_text("x\n")
             subprocess.run(["git", "add", "."], cwd=root, check=True, capture_output=True)
             subprocess.run(["git", "commit", "-m", "init"], cwd=root, check=True, capture_output=True)
-            blobs = _git_batch_cat(root, ["HEAD:no-such-file.txt"])
-            self.assertEqual(blobs["HEAD:no-such-file.txt"], b"")
+            with self.assertRaisesRegex(ValueError, "not found"):
+                _git_batch_cat(root, ["HEAD:no-such-file.txt"])
 
 
 class ReadPathContentTests(unittest.TestCase):
diff --git a/tests/test_hashing_contract.py b/tests/test_hashing_contract.py
new file mode 100644
index 0000000..2249889
--- /dev/null
+++ b/tests/test_hashing_contract.py
@@ -0,0 +1,300 @@
+"""Regression tests for the v2 hash wire format and Git-backed sources."""
+
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from boundver._git import (
+    _git_batch_cat,
+    _git_cat_blob,
+    _list_files_for_source,
+    list_head_files,
+)
+from boundver._hashing import (
+    HASH_DOMAIN_CONTENT_ONLY,
+    HASH_DOMAIN_EXACT,
+    _content_only_digest,
+    _hash_framed_entries,
+    _read_path_content,
+    source_tree_digest,
+)
+from boundver._utils import GuardrailError
+
+
+def _init_repo(root: Path) -> None:
+    subprocess.run(["git", "init", "-q"], cwd=root, check=True)
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.invalid"],
+        cwd=root,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Boundver Test"],
+        cwd=root,
+        check=True,
+    )
+
+
+def _commit_all(root: Path, message: str = "test") -> None:
+    subprocess.run(["git", "add", "--all"], cwd=root, check=True)
+    subprocess.run(["git", "commit", "-qm", message], cwd=root, check=True)
+
+
+class FramedHashContractTests(unittest.TestCase):
+    def test_known_v2_wire_format_vector(self):
+        digest = _hash_framed_entries(
+            [("file:svc/a.txt", b"A\n")],
+            domain=HASH_DOMAIN_EXACT,
+        )
+        self.assertEqual(
+            digest,
+            "222b93488c0dc17649cb52a813dcbcde9a916d0b7cee0a16d84f7d577404b9bf",
+        )
+
+    def test_length_framing_prevents_file_content_ambiguity(self):
+        one_file = [("file:svc/a", b"Xfile:svc/b\nY")]
+        two_files = [("file:svc/a", b"X"), ("file:svc/b", b"Y")]
+        self.assertNotEqual(
+            _hash_framed_entries(one_file, domain=HASH_DOMAIN_EXACT),
+            _hash_framed_entries(two_files, domain=HASH_DOMAIN_EXACT),
+        )
+
+    def test_domains_separate_identical_entries(self):
+        entries = [("file:a", b"same")]
+        self.assertNotEqual(
+            _hash_framed_entries(entries, domain=HASH_DOMAIN_EXACT),
+            _hash_framed_entries(entries, domain=HASH_DOMAIN_CONTENT_ONLY),
+        )
+
+    def test_input_order_does_not_change_digest(self):
+        entries = [("file:b", b"B"), ("file:a", b"A")]
+        self.assertEqual(
+            _hash_framed_entries(entries, domain=HASH_DOMAIN_EXACT),
+            _hash_framed_entries(reversed(entries), domain=HASH_DOMAIN_EXACT),
+        )
+
+
+class GitSourceContractTests(unittest.TestCase):
+    def test_unicode_filename_hashes_and_matches_all_clean_sources(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            (root / "svc" / "café.txt").write_bytes(b"line 1\r\nline 2\r\n")
+            _commit_all(root)
+
+            self.assertEqual(list_head_files(root, "svc"), ["svc/café.txt"])
+            head = source_tree_digest(root, "svc", source="head")
+            index = source_tree_digest(root, "svc", source="index")
+            working = source_tree_digest(root, "svc", source="working-tree")
+            self.assertEqual(head, index)
+            self.assertEqual(index, working)
+
+    def test_unicode_filename_content_change_changes_head_digest(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            target = root / "svc" / "café.txt"
+            target.write_bytes(b"before")
+            _commit_all(root, "before")
+            before = source_tree_digest(root, "svc", source="head")
+            target.write_bytes(b"after")
+            _commit_all(root, "after")
+            after = source_tree_digest(root, "svc", source="head")
+            self.assertNotEqual(before, after)
+
+    @unittest.skipIf(os.name == "nt", "Windows paths cannot contain backslashes")
+    def test_literal_backslash_filename_is_not_treated_as_a_separator(self):
+        with tempfile.TemporaryDirectory() as td1, tempfile.TemporaryDirectory() as td2:
+            root1 = Path(td1)
+            root2 = Path(td2)
+            _init_repo(root1)
+            _init_repo(root2)
+            (root1 / "svc").mkdir()
+            (root1 / "svc" / "a\\b").write_bytes(b"same")
+            (root2 / "svc" / "a").mkdir(parents=True)
+            (root2 / "svc" / "a" / "b").write_bytes(b"same")
+            _commit_all(root1)
+            _commit_all(root2)
+            self.assertNotEqual(
+                source_tree_digest(root1, "svc", source="head"),
+                source_tree_digest(root2, "svc", source="head"),
+            )
+
+    @unittest.skipIf(os.name == "nt", "Windows paths cannot contain newlines")
+    def test_newline_filename_hashes_without_batch_protocol_ambiguity(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            (root / "svc" / "line\nbreak.txt").write_bytes(b"content")
+            _commit_all(root)
+            head = source_tree_digest(root, "svc", source="head")
+            index = source_tree_digest(root, "svc", source="index")
+            working = source_tree_digest(root, "svc", source="working-tree")
+            self.assertEqual(head, index)
+            self.assertEqual(index, working)
+
+    @unittest.skipIf(os.name == "nt", "Test requires POSIX byte filenames")
+    def test_non_utf8_filename_bytes_round_trip_from_git(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            raw_path = os.fsencode(root / "svc") + b"/invalid-\xff.txt"
+            fd = os.open(raw_path, os.O_WRONLY | os.O_CREAT, 0o600)
+            try:
+                os.write(fd, b"content")
+            finally:
+                os.close(fd)
+            _commit_all(root)
+            head = source_tree_digest(root, "svc", source="head")
+            index = source_tree_digest(root, "svc", source="index")
+            working = source_tree_digest(root, "svc", source="working-tree")
+            self.assertEqual(head, index)
+            self.assertEqual(index, working)
+
+    def test_working_tree_uses_tracked_files_only(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            (root / "svc" / "tracked.txt").write_bytes(b"tracked")
+            _commit_all(root)
+            before = source_tree_digest(root, "svc", source="working-tree")
+            (root / "svc" / "untracked.txt").write_bytes(b"untracked")
+            after = source_tree_digest(root, "svc", source="working-tree")
+            self.assertEqual(before, after)
+
+    def test_successful_empty_index_does_not_fallback_to_untracked_disk_file(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "baseline.txt").write_bytes(b"committed")
+            _commit_all(root)
+            subprocess.run(
+                ["git", "read-tree", "--empty"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            (root / "untracked.txt").write_bytes(b"not in the index")
+            self.assertEqual(
+                _list_files_for_source(root, ".", source="index"),
+                [],
+            )
+            self.assertEqual(
+                _list_files_for_source(root, ".", source="working-tree"),
+                [],
+            )
+
+    def test_unborn_working_tree_uses_filesystem_for_initial_setup(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "first-file.txt").write_bytes(b"not committed yet")
+
+            files = _list_files_for_source(root, ".", source="working-tree")
+
+            self.assertIn("first-file.txt", files)
+            self.assertFalse(
+                any(path == ".git" or path.startswith(".git/") for path in files),
+                files,
+            )
+
+    def test_content_only_digest_matches_all_clean_sources(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            (root / "svc" / "a.txt").write_bytes(b"one\r\ntwo\r\n")
+            _commit_all(root)
+            digests = {
+                _content_only_digest(root, "svc", source=source)
+                for source in ("head", "index", "working-tree")
+            }
+            self.assertEqual(len(digests), 1)
+
+
+class FailClosedGitBlobTests(unittest.TestCase):
+    def test_real_missing_batch_blob_raises(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "present.txt").write_bytes(b"present")
+            _commit_all(root)
+            with self.assertRaisesRegex(ValueError, "not found"):
+                _git_batch_cat(root, ["HEAD:missing.txt"])
+
+    def test_real_empty_blob_remains_valid(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "empty.txt").write_bytes(b"")
+            _commit_all(root)
+            self.assertEqual(
+                _git_batch_cat(root, ["HEAD:empty.txt"]),
+                {"HEAD:empty.txt": b""},
+            )
+
+    def test_truncated_batch_header_raises(self):
+        completed = subprocess.CompletedProcess(
+            args=["git", "cat-file"],
+            returncode=0,
+            stdout=b"unterminated header",
+            stderr=b"",
+        )
+        with patch("boundver._git.subprocess.run", return_value=completed):
+            with self.assertRaisesRegex(ValueError, "Truncated"):
+                _git_batch_cat(Path("."), ["HEAD:file.txt"])
+
+    def test_truncated_batch_content_raises(self):
+        completed = subprocess.CompletedProcess(
+            args=["git", "cat-file"],
+            returncode=0,
+            stdout=b"object-id blob 5\nabc\n",
+            stderr=b"",
+        )
+        with patch("boundver._git.subprocess.run", return_value=completed):
+            with self.assertRaisesRegex(ValueError, "Truncated"):
+                _git_batch_cat(Path("."), ["HEAD:file.txt"])
+
+    def test_oversized_batch_blob_raises_before_reading_content(self):
+        completed = subprocess.CompletedProcess(
+            args=["git", "cat-file"],
+            returncode=0,
+            stdout=b"object-id blob 52428801\n",
+            stderr=b"",
+        )
+        with patch("boundver._git.subprocess.run", return_value=completed):
+            with self.assertRaises(GuardrailError):
+                _git_batch_cat(Path("."), ["HEAD:file.txt"])
+
+    def test_oversized_single_blob_raises(self):
+        completed = subprocess.CompletedProcess(
+            args=["git", "show"],
+            returncode=0,
+            stdout=b"12345",
+            stderr=b"",
+        )
+        with patch("boundver._git.MAX_GIT_BLOB_BYTES", 4):
+            with patch("boundver._git.subprocess.run", return_value=completed):
+                with self.assertRaises(GuardrailError):
+                    _git_cat_blob(Path("."), "HEAD:file.txt")
+
+    def test_filesystem_read_race_raises_instead_of_hashing_empty_bytes(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            target = root / "file.txt"
+            target.write_bytes(b"present")
+            with patch.object(Path, "read_bytes", side_effect=FileNotFoundError):
+                with self.assertRaisesRegex(ValueError, "disappeared"):
+                    _read_path_content(root, target, source="working-tree")
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_provider_contract.py b/tests/test_provider_contract.py
new file mode 100644
index 0000000..9012db1
--- /dev/null
+++ b/tests/test_provider_contract.py
@@ -0,0 +1,406 @@
+"""Focused regression tests for the public provider contract."""
+
+import json
+import sys
+import types
+import unittest
+from pathlib import Path
+
+from boundver._hashing import HASH_DOMAIN_BOUNDARY, _hash_framed_entries
+from boundver.providers import (
+    OpenApiCanonicalProvider,
+    ProviderContext,
+    ResolvedBoundary,
+    compute_boundary,
+    create_registry,
+    explain_provider_diff,
+    get_provider,
+    load_custom_providers,
+    register_provider,
+    validate_provider_config,
+)
+
+
+ROOT = Path("/repo")
+
+
+def _context(document=None):
+    files = {}
+    if document is not None:
+        files["svc/openapi.json"] = json.dumps(document).encode("utf-8")
+
+    return ProviderContext(
+        repo_root=ROOT,
+        component_path="svc",
+        boundary_cfg={"paths": ["openapi.json"]},
+        source="working-tree",
+        read_file=lambda path: files[path],
+        list_files=lambda prefix: sorted(
+            path for path in files if path == prefix or path.startswith(prefix + "/")
+        ),
+    )
+
+
+def _openapi_digest(document):
+    digest, status, errors = compute_boundary(
+        OpenApiCanonicalProvider(), _context(document)
+    )
+    if status != "ok" or errors:
+        raise AssertionError((status, errors))
+    return digest
+
+
+class TestOpenApiNamedMaps(unittest.TestCase):
+    def test_annotation_looking_property_names_are_contract(self):
+        before = {
+            "openapi": "3.1.0",
+            "paths": {},
+            "components": {
+                "schemas": {
+                    "Record": {
+                        "type": "object",
+                        "properties": {
+                            "description": {
+                                "type": "string",
+                                "description": "documentation is ignored",
+                            },
+                            "example": {"type": "string"},
+                            "x-internal": {"type": "boolean"},
+                        },
+                    }
+                }
+            },
+        }
+        after = json.loads(json.dumps(before))
+        after["components"]["schemas"]["Record"]["properties"]["description"][
+            "type"
+        ] = "integer"
+
+        self.assertNotEqual(_openapi_digest(before), _openapi_digest(after))
+
+        resolved = OpenApiCanonicalProvider().resolve(_context(before))
+        canonical = json.loads(resolved.entries[0][1].decode("utf-8"))
+        properties = canonical["components"]["schemas"]["Record"]["properties"]
+        self.assertEqual(
+            set(properties), {"description", "example", "x-internal"}
+        )
+        self.assertNotIn("description", properties["description"])
+
+    def test_annotation_looking_component_schema_names_are_contract(self):
+        before = {
+            "openapi": "3.1.0",
+            "paths": {},
+            "components": {
+                "schemas": {
+                    "description": {"type": "string"},
+                    "example": {"type": "number"},
+                    "x-private": {"type": "boolean"},
+                }
+            },
+        }
+        after = json.loads(json.dumps(before))
+        after["components"]["schemas"]["x-private"]["type"] = "integer"
+
+        self.assertNotEqual(_openapi_digest(before), _openapi_digest(after))
+
+        resolved = OpenApiCanonicalProvider().resolve(_context(before))
+        canonical = json.loads(resolved.entries[0][1].decode("utf-8"))
+        self.assertEqual(
+            set(canonical["components"]["schemas"]),
+            {"description", "example", "x-private"},
+        )
+
+    def test_annotation_looking_definition_names_are_contract(self):
+        before = {
+            "swagger": "2.0",
+            "paths": {},
+            "definitions": {
+                "description": {"type": "string"},
+                "x-private": {"type": "boolean"},
+            },
+        }
+        after = json.loads(json.dumps(before))
+        after["definitions"]["description"]["type"] = "integer"
+        self.assertNotEqual(_openapi_digest(before), _openapi_digest(after))
+
+    def test_real_annotation_changes_remain_ignored(self):
+        before = {
+            "openapi": "3.1.0",
+            "paths": {
+                "/widgets": {
+                    "description": "old docs",
+                    "get": {
+                        "summary": "old summary",
+                        "x-internal": True,
+                        "responses": {"204": {"description": "No content"}},
+                    },
+                }
+            },
+        }
+        after = json.loads(json.dumps(before))
+        after["paths"]["/widgets"]["description"] = "new docs"
+        after["paths"]["/widgets"]["get"]["summary"] = "new summary"
+        after["paths"]["/widgets"]["get"]["x-internal"] = False
+        self.assertEqual(_openapi_digest(before), _openapi_digest(after))
+
+    def test_annotation_named_callback_link_and_variable_entries_are_contract(self):
+        document = {
+            "openapi": "3.1.0",
+            "paths": {
+                "/widgets": {
+                    "post": {
+                        "callbacks": {
+                            "description": {
+                                "{$request.body#/callbackUrl}": {
+                                    "post": {
+                                        "operationId": "descriptionCallback",
+                                        "responses": {
+                                            "204": {"description": "received"}
+                                        },
+                                    }
+                                }
+                            },
+                            "x-partner": {
+                                "{$request.body#/partnerUrl}": {
+                                    "post": {
+                                        "operationId": "partnerCallback",
+                                        "responses": {
+                                            "204": {"description": "received"}
+                                        },
+                                    }
+                                }
+                            },
+                        },
+                        "responses": {
+                            "200": {
+                                "description": "success",
+                                "links": {
+                                    "description": {
+                                        "operationId": "getDescription"
+                                    },
+                                    "x-related": {"operationId": "getRelated"},
+                                },
+                            }
+                        },
+                        "servers": [
+                            {
+                                "url": "https://{description}.{x-region}.example.test",
+                                "variables": {
+                                    "description": {"default": "api"},
+                                    "x-region": {"default": "us"},
+                                },
+                            }
+                        ],
+                    }
+                }
+            },
+        }
+        resolved = OpenApiCanonicalProvider().resolve(_context(document))
+        canonical = json.loads(resolved.entries[0][1].decode("utf-8"))
+        operation = canonical["paths"]["/widgets"]["post"]
+
+        self.assertEqual(
+            set(operation["callbacks"]), {"description", "x-partner"}
+        )
+        self.assertEqual(
+            set(operation["responses"]["200"]["links"]),
+            {"description", "x-related"},
+        )
+        self.assertEqual(
+            set(operation["servers"][0]["variables"]),
+            {"description", "x-region"},
+        )
+
+        mutations = [
+            (
+                ("paths", "/widgets", "post", "callbacks", "x-partner",
+                 "{$request.body#/partnerUrl}", "post", "operationId"),
+                "changedPartnerCallback",
+            ),
+            (
+                ("paths", "/widgets", "post", "responses", "200", "links",
+                 "description", "operationId"),
+                "changedDescriptionLink",
+            ),
+            (
+                ("paths", "/widgets", "post", "servers", 0, "variables",
+                 "x-region", "default"),
+                "eu",
+            ),
+        ]
+        baseline_digest = _openapi_digest(document)
+        for path, value in mutations:
+            with self.subTest(path=path):
+                changed = json.loads(json.dumps(document))
+                target = changed
+                for part in path[:-1]:
+                    target = target[part]
+                target[path[-1]] = value
+                self.assertNotEqual(baseline_digest, _openapi_digest(changed))
+
+
+class TestBoundaryComputationContract(unittest.TestCase):
+    class MetadataProvider:
+        name = "custom.metadata-test"
+        version = "1"
+
+        def resolve(self, ctx):
+            return ResolvedBoundary(
+                entries=[("contract", b"value")],
+                metadata={"symbols": ["Widget"]},
+            )
+
+    def test_default_return_shape_remains_three_items(self):
+        result = compute_boundary(self.MetadataProvider(), _context())
+        self.assertEqual(len(result), 3)
+        self.assertEqual(
+            result[0],
+            _hash_framed_entries(
+                [("contract", b"value")], domain=HASH_DOMAIN_BOUNDARY
+            ),
+        )
+
+    def test_metadata_can_be_requested_without_affecting_digest(self):
+        ordinary = compute_boundary(self.MetadataProvider(), _context())
+        with_metadata = compute_boundary(
+            self.MetadataProvider(), _context(), include_metadata=True
+        )
+        self.assertEqual(with_metadata[:3], ordinary)
+        self.assertEqual(with_metadata[3], {"symbols": ["Widget"]})
+
+    def test_metadata_is_available_for_an_error_resolution(self):
+        class ErrorProvider(self.MetadataProvider):
+            def resolve(self, ctx):
+                return ResolvedBoundary(
+                    status="error",
+                    errors=["invalid contract"],
+                    metadata={"parser": "v2"},
+                )
+
+        self.assertEqual(
+            compute_boundary(ErrorProvider(), _context(), include_metadata=True),
+            (None, "error", ["invalid contract"], {"parser": "v2"}),
+        )
+
+
+class TestProviderRegistryIsolation(unittest.TestCase):
+    class IsolatedProvider:
+        name = "custom.provider-contract-isolated"
+        version = "1"
+
+        def resolve(self, ctx):
+            return ResolvedBoundary(entries=[("contract", b"value")])
+
+    def test_registration_can_be_scoped_to_one_registry(self):
+        first = create_registry()
+        second = create_registry()
+        provider = self.IsolatedProvider()
+
+        register_provider(provider, registry=first)
+
+        self.assertIs(get_provider(provider.name, registry=first), provider)
+        self.assertIsNone(get_provider(provider.name, registry=second))
+        self.assertIsNone(get_provider(provider.name))
+
+    def test_fresh_registry_contains_builtin_aliases(self):
+        registry = create_registry()
+        self.assertIs(registry["openapi"], registry["openapi-raw"])
+        self.assertIs(registry["json-file"], registry["json-file-raw"])
+
+    def test_custom_loader_registers_only_in_supplied_registry(self):
+        module_name = "_boundver_provider_contract_fixture"
+        module = types.ModuleType(module_name)
+        module.IsolatedProvider = self.IsolatedProvider
+        sys.modules[module_name] = module
+        registry = create_registry()
+        try:
+            errors = load_custom_providers(
+                [{"module": module_name, "class": "IsolatedProvider"}],
+                allow_custom=True,
+                registry=registry,
+            )
+            self.assertEqual(errors, [])
+            self.assertIsNotNone(
+                get_provider(self.IsolatedProvider.name, registry=registry)
+            )
+            self.assertIsNone(get_provider(self.IsolatedProvider.name))
+        finally:
+            del sys.modules[module_name]
+
+    def test_custom_loader_reports_non_object_entries(self):
+        errors = load_custom_providers(
+            ["not-an-object"], allow_custom=True, registry=create_registry()
+        )
+        self.assertEqual(len(errors), 1)
+        self.assertIn("must be an object", errors[0])
+
+
+class TestProviderHooks(unittest.TestCase):
+    class HookProvider:
+        name = "custom.hooks"
+
+        def validate_config(self, boundary_cfg, component_path, repo_root):
+            return [f"{component_path}: {boundary_cfg['problem']}"]
+
+        def explain_diff(self, old_metadata, new_metadata, ctx):
+            return f"{old_metadata['count']} -> {new_metadata['count']}"
+
+    def test_validation_helper_invokes_provider_hook(self):
+        self.assertEqual(
+            validate_provider_config(
+                self.HookProvider(), {"problem": "bad option"}, "svc", ROOT
+            ),
+            ["svc: bad option"],
+        )
+
+    def test_validation_helper_converts_hook_exception_to_error(self):
+        class BrokenProvider(self.HookProvider):
+            def validate_config(self, boundary_cfg, component_path, repo_root):
+                raise RuntimeError("boom")
+
+        errors = validate_provider_config(BrokenProvider(), {}, "svc", ROOT)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("boom", errors[0])
+
+    def test_validation_helper_rejects_a_malformed_result(self):
+        class BrokenProvider(self.HookProvider):
+            def validate_config(self, boundary_cfg, component_path, repo_root):
+                return "not a list"
+
+        errors = validate_provider_config(BrokenProvider(), {}, "svc", ROOT)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("must return a list", errors[0])
+
+    def test_explanation_helper_passes_metadata(self):
+        self.assertEqual(
+            explain_provider_diff(
+                self.HookProvider(), {"count": 1}, {"count": 2}, _context()
+            ),
+            "1 -> 2",
+        )
+
+    def test_explanation_helper_survives_hook_exception(self):
+        class BrokenProvider(self.HookProvider):
+            def explain_diff(self, old_metadata, new_metadata, ctx):
+                raise RuntimeError("boom")
+
+        explanation = explain_provider_diff(
+            BrokenProvider(), None, None, _context()
+        )
+        self.assertIn("custom.hooks boundary changed", explanation)
+        self.assertIn("boom", explanation)
+
+    def test_missing_hooks_have_backward_compatible_fallbacks(self):
+        class LegacyProvider:
+            name = "custom.legacy"
+
+        provider = LegacyProvider()
+        self.assertEqual(validate_provider_config(provider, {}, "svc", ROOT), [])
+        self.assertEqual(
+            explain_provider_diff(provider, None, None, _context()),
+            "custom.legacy boundary changed",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_providers.py b/tests/test_providers.py
index 47edaeb..13b7267 100644
--- a/tests/test_providers.py
+++ b/tests/test_providers.py
@@ -102,7 +102,10 @@ def test_paths_with_no_matching_files_returns_error(self):
         ctx = _make_ctx(boundary_cfg={"paths": ["missing.yaml"]}, files={})
         rb = self.p.resolve(ctx)
         self.assertEqual(rb.status, "error")
-        self.assertIn("Declared boundary paths produced no digest", rb.errors)
+        self.assertTrue(
+            any("matched no tracked files" in error for error in rb.errors),
+            rb.errors,
+        )
 
     def test_single_file_produces_ok_entry(self):
         ctx = _make_ctx(
@@ -191,15 +194,13 @@ def test_duplicate_paths_deduplicated(self):
 
 class TestComputeBoundary(unittest.TestCase):
     def test_digest_stability(self):
-        """compute_boundary must produce the same hash as pre-Phase-1 boundary_paths_digest format.
-
-        Pre-Phase-1 format: sha256( concat("file:child_rel\\n" + content) )
-        """
-        import hashlib
+        """compute_boundary must use the shared framed boundary digest."""
+        from boundver._hashing import HASH_DOMAIN_BOUNDARY, _hash_framed_entries
 
         content = b"openapi: 3.0\n"
-        expected_input = b"file:api.yaml\n" + content
-        expected_digest = hashlib.sha256(expected_input).hexdigest()
+        expected_digest = _hash_framed_entries(
+            [("file:api.yaml", content)], domain=HASH_DOMAIN_BOUNDARY
+        )
 
         p = PathHashProvider()
         p.name = "test"
@@ -212,15 +213,15 @@ def test_digest_stability(self):
         self.assertEqual(status, "ok")
         self.assertEqual(errors, [])
 
-    def test_multi_file_digest_matches_pre_phase1(self):
-        """Multi-file digest must match concatenated pre-Phase-1 format."""
-        import hashlib
+    def test_multi_file_digest_matches_framed_contract(self):
+        """Multi-file digest must match the framed boundary format."""
+        from boundver._hashing import HASH_DOMAIN_BOUNDARY, _hash_framed_entries
 
         files = {"svc/a.yaml": b"A\n", "svc/b.yaml": b"B\n"}
-        expected = hashlib.sha256(
-            b"file:a.yaml\nA\n"
-            b"file:b.yaml\nB\n"
-        ).hexdigest()
+        expected = _hash_framed_entries(
+            [("file:a.yaml", b"A\n"), ("file:b.yaml", b"B\n")],
+            domain=HASH_DOMAIN_BOUNDARY,
+        )
 
         p = PathHashProvider()
         p.name = "test"
@@ -564,7 +565,10 @@ def test_no_matching_files_returns_error(self):
         )
         rb = p.resolve(ctx)
         self.assertEqual(rb.status, "error")
-        self.assertIn("Declared boundary paths produced no digest", rb.errors)
+        self.assertTrue(
+            any("matched no tracked files" in error for error in rb.errors),
+            rb.errors,
+        )
 
     def test_digest_differs_from_raw_provider(self):
         """json-canonical digest must not collide with raw json-file digest for same file."""
@@ -747,7 +751,10 @@ def test_no_matching_files_returns_error(self):
         )
         rb = p.resolve(ctx)
         self.assertEqual(rb.status, "error")
-        self.assertIn("Declared boundary paths produced no digest", rb.errors)
+        self.assertTrue(
+            any("matched no tracked files" in error for error in rb.errors),
+            rb.errors,
+        )
 
     def test_validate_config_missing_file(self):
         """validate_config reports error for missing boundary path."""
@@ -838,7 +845,10 @@ def test_glob_no_matches_returns_error(self):
         ctx = _make_ctx(boundary_cfg={"paths": ["*.yaml"]}, files=files)
         result = PathHashProvider().resolve(ctx)
         self.assertEqual(result.status, "error")
-        self.assertTrue(any("no digest" in e.lower() for e in result.errors))
+        self.assertTrue(
+            any("matched no tracked files" in error for error in result.errors),
+            result.errors,
+        )
 
     def test_glob_digest_changes_when_matched_file_changes(self):
         """Digest must change when a glob-matched file's content changes."""
diff --git a/tests/test_security_regressions.py b/tests/test_security_regressions.py
new file mode 100644
index 0000000..97cebf1
--- /dev/null
+++ b/tests/test_security_regressions.py
@@ -0,0 +1,373 @@
+"""Regressions for fail-closed validation, selection, and source handling."""
+
+import json
+import shutil
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from boundver._config import validate_config
+from boundver._git import changed_components_since_ref
+from boundver._lockfile import generate_lockfile
+from boundver.providers import PathHashProvider, ProviderContext, compute_boundary
+
+
+def _init_repo(root: Path) -> None:
+    subprocess.run(
+        ["git", "init"], cwd=root, check=True, capture_output=True, text=True
+    )
+    subprocess.run(
+        ["git", "config", "user.email", "test@example.com"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        ["git", "config", "user.name", "Test User"],
+        cwd=root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+class ChangedFromRootComponentTests(unittest.TestCase):
+    def test_root_component_is_selected_for_root_file_change(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            readme = root / "README.md"
+            readme.write_text("before\n")
+            subprocess.run(
+                ["git", "add", "README.md"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            subprocess.run(
+                ["git", "commit", "-m", "baseline"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            readme.write_text("after\n")
+            config = {
+                "project": "root-project",
+                "components": {
+                    "root": {
+                        "path": ".",
+                        "boundary": {"provider": "implicit"},
+                    }
+                },
+                "slices": {},
+            }
+
+            selected = changed_components_since_ref(config, root, "HEAD")
+
+            self.assertEqual(selected, ["root"])
+
+
+class SchemaIndependentConfigValidationTests(unittest.TestCase):
+    @staticmethod
+    def _valid_config(root: Path) -> dict:
+        (root / "svc").mkdir(exist_ok=True)
+        return {
+            "project": "project",
+            "components": {
+                "svc": {
+                    "path": "svc",
+                    "boundary": {"provider": "leaf"},
+                }
+            },
+            "slices": {},
+        }
+
+    def test_project_must_be_a_non_empty_string_without_schema_engine(self):
+        with tempfile.TemporaryDirectory() as td, patch(
+            "boundver._config._schema_engine_errors", return_value=[]
+        ):
+            root = Path(td)
+            for project in (None, "", "   ", 7, [], {}):
+                with self.subTest(project=project):
+                    config = self._valid_config(root)
+                    config["project"] = project
+                    errors = validate_config(config, root)
+                    self.assertIn(
+                        "Field 'project' must be a non-empty string", errors
+                    )
+
+    def test_component_and_slice_keys_must_be_strings_without_schema_engine(self):
+        with tempfile.TemporaryDirectory() as td, patch(
+            "boundver._config._schema_engine_errors", return_value=[]
+        ):
+            root = Path(td)
+            for invalid_name in ("", 7):
+                with self.subTest(kind="component", name=invalid_name):
+                    config = self._valid_config(root)
+                    component = config["components"].pop("svc")
+                    config["components"][invalid_name] = component
+                    errors = validate_config(config, root)
+                    self.assertIn(
+                        "Component names must be non-empty strings", errors
+                    )
+
+                with self.subTest(kind="slice", name=invalid_name):
+                    config = self._valid_config(root)
+                    config["slices"] = {
+                        invalid_name: {
+                            "mode": "exact",
+                            "components": ["svc"],
+                        }
+                    }
+                    errors = validate_config(config, root)
+                    self.assertIn("Slice names must be non-empty strings", errors)
+
+
+class SourceAwareValidationTests(unittest.TestCase):
+    def test_head_uses_committed_files_deleted_from_working_tree(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _init_repo(root)
+            (root / "svc").mkdir()
+            (root / "svc" / "boundary.json").write_text('{"contract": 1}\n')
+            (root / "svc" / "version.json").write_text(
+                '{"version": "1.2.3"}\n'
+            )
+            config = {
+                "project": "source-aware",
+                "components": {
+                    "svc": {
+                        "path": "svc",
+                        "boundary": {
+                            "provider": "json-file",
+                            "paths": ["boundary.json"],
+                        },
+                        "version_source": {
+                            "file": "version.json",
+                            "field": "version",
+                        },
+                    }
+                },
+                "slices": {},
+            }
+            (root / "boundary.config.json").write_text(json.dumps(config) + "\n")
+            subprocess.run(
+                ["git", "add", "."], cwd=root, check=True, capture_output=True
+            )
+            subprocess.run(
+                ["git", "commit", "-m", "baseline"],
+                cwd=root,
+                check=True,
+                capture_output=True,
+            )
+            shutil.rmtree(root / "svc")
+
+            head_errors = validate_config(config, root, source="head")
+            head_lock = generate_lockfile(config, root, source="head")
+            working_tree_errors = validate_config(
+                config, root, source="working-tree"
+            )
+
+            self.assertEqual(head_errors, [])
+            self.assertEqual(head_lock["components"]["svc"]["version"], "1.2.3")
+            self.assertIsNotNone(
+                head_lock["components"]["svc"]["fingerprints"]["exact"]
+            )
+            self.assertIsNotNone(
+                head_lock["components"]["svc"]["fingerprints"]["boundary"]
+            )
+            self.assertTrue(
+                any("path not found or not a directory" in error for error in working_tree_errors),
+                working_tree_errors,
+            )
+            self.assertTrue(
+                any("version_source.file not found" in error for error in working_tree_errors),
+                working_tree_errors,
+            )
+
+
+class RepositoryContainmentValidationTests(unittest.TestCase):
+    @staticmethod
+    def _config(component: dict) -> dict:
+        return {
+            "project": "containment",
+            "components": {"svc": component},
+            "slices": {},
+        }
+
+    @staticmethod
+    def _symlink_or_skip(
+        test_case: unittest.TestCase,
+        link: Path,
+        target: Path,
+        *,
+        target_is_directory: bool,
+    ) -> None:
+        try:
+            link.symlink_to(target, target_is_directory=target_is_directory)
+        except (OSError, NotImplementedError) as exc:
+            test_case.skipTest(f"symlinks are unavailable: {exc}")
+
+    def test_component_root_symlink_escaping_repository_is_rejected(self):
+        with tempfile.TemporaryDirectory() as td:
+            base = Path(td)
+            root = base / "repo"
+            outside = base / "outside-component"
+            root.mkdir()
+            outside.mkdir()
+            self._symlink_or_skip(
+                self,
+                root / "svc",
+                outside,
+                target_is_directory=True,
+            )
+            config = self._config(
+                {
+                    "path": "svc",
+                    "boundary": {"provider": "leaf"},
+                }
+            )
+
+            errors = validate_config(config, root, source="working-tree")
+
+            self.assertTrue(
+                any("path must not be a symlink: svc" in error for error in errors),
+                errors,
+            )
+
+    def test_version_source_symlink_escaping_repository_is_rejected(self):
+        with tempfile.TemporaryDirectory() as td:
+            base = Path(td)
+            root = base / "repo"
+            component = root / "svc"
+            component.mkdir(parents=True)
+            outside_version = base / "outside-version.json"
+            outside_version.write_text('{"version": "1.2.3"}\n')
+            self._symlink_or_skip(
+                self,
+                component / "version.json",
+                outside_version,
+                target_is_directory=False,
+            )
+            config = self._config(
+                {
+                    "path": "svc",
+                    "boundary": {"provider": "leaf"},
+                    "version_source": {
+                        "file": "version.json",
+                        "field": "version",
+                    },
+                }
+            )
+
+            errors = validate_config(config, root, source="working-tree")
+
+            self.assertTrue(
+                any(
+                    "version_source.file must not be a symlink" in error
+                    for error in errors
+                ),
+                errors,
+            )
+
+    def test_vendored_copy_parent_traversal_is_rejected(self):
+        with tempfile.TemporaryDirectory() as td:
+            base = Path(td)
+            root = base / "repo"
+            (root / "svc").mkdir(parents=True)
+            (base / "outside-vendor").mkdir()
+            config = self._config(
+                {
+                    "path": "svc",
+                    "boundary": {"provider": "leaf"},
+                    "vendored_copies": ["../outside-vendor"],
+                }
+            )
+
+            errors = validate_config(config, root, source="working-tree")
+
+            self.assertTrue(
+                any(
+                    "vendored copy must be a safe repo-relative path" in error
+                    for error in errors
+                ),
+                errors,
+            )
+
+    def test_vendored_copy_symlink_escaping_repository_is_rejected(self):
+        with tempfile.TemporaryDirectory() as td:
+            base = Path(td)
+            root = base / "repo"
+            (root / "svc").mkdir(parents=True)
+            outside = base / "outside-vendor"
+            outside.mkdir()
+            self._symlink_or_skip(
+                self,
+                root / "vendored-svc",
+                outside,
+                target_is_directory=True,
+            )
+            config = self._config(
+                {
+                    "path": "svc",
+                    "boundary": {"provider": "leaf"},
+                    "vendored_copies": ["vendored-svc"],
+                }
+            )
+
+            errors = validate_config(config, root, source="working-tree")
+
+            self.assertTrue(
+                any(
+                    "vendored copy must be a safe repo-relative path" in error
+                    for error in errors
+                ),
+                errors,
+            )
+
+
+class RootPathBoundaryIdentityTests(unittest.TestCase):
+    @staticmethod
+    def _context(filename: str) -> ProviderContext:
+        files = {filename: b"same contract bytes\n"}
+        return ProviderContext(
+            repo_root=Path("/repo"),
+            component_path=".",
+            boundary_cfg={"paths": [filename]},
+            source="working-tree",
+            read_file=lambda path: files[path],
+            list_files=lambda prefix: sorted(
+                path
+                for path in files
+                if path == prefix or path.startswith(prefix + "/")
+            ),
+        )
+
+    def test_root_file_label_preserves_filename_and_rename_changes_digest(self):
+        provider = PathHashProvider()
+        before_context = self._context("old-name.json")
+        after_context = self._context("new-name.json")
+
+        before_entries = provider.resolve(before_context).entries
+        after_entries = provider.resolve(after_context).entries
+        before_digest, before_status, before_errors = compute_boundary(
+            provider, before_context
+        )
+        after_digest, after_status, after_errors = compute_boundary(
+            provider, after_context
+        )
+
+        self.assertEqual(before_entries[0][0], "file:old-name.json")
+        self.assertEqual(after_entries[0][0], "file:new-name.json")
+        self.assertEqual((before_status, before_errors), ("ok", []))
+        self.assertEqual((after_status, after_errors), ("ok", []))
+        self.assertNotEqual(before_digest, after_digest)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_versions.py b/tests/test_versions.py
index a109617..5124476 100644
--- a/tests/test_versions.py
+++ b/tests/test_versions.py
@@ -42,13 +42,24 @@ def test_major_zero(self):
     def test_large_version_numbers(self):
         self.assertEqual(parse_semver("10.20.300"), ("10", "10.20", "10.20.300"))
 
-    def test_prerelease_suffix_ignored_in_semver_parts(self):
-        # parse_semver extracts leading numeric parts; suffix after patch is ignored
+    def test_prerelease_suffix_ignored_in_derived_semver_parts(self):
         major, api, exact = parse_semver("1.2.3-alpha")
         self.assertEqual(major, "1")
         self.assertEqual(api, "1.2")
         self.assertEqual(exact, "1.2.3")
 
+    def test_trailing_junk_is_not_accepted_as_semver(self):
+        major, api, exact = parse_semver("1.2.3-not valid")
+        self.assertIsNone(major)
+        self.assertIsNone(api)
+        self.assertEqual(exact, "1.2.3-not valid")
+
+    def test_build_metadata_is_valid_semver(self):
+        self.assertEqual(
+            parse_semver("1.2.3-alpha.1+build.9"),
+            ("1", "1.2", "1.2.3"),
+        )
+
 
 class ExtractJsonFieldTests(unittest.TestCase):
     def _write(self, tmp: Path, content: dict) -> Path: