sourcebound 1.2.1__py3-none-any.whl

clean_docs/visuals.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from clean_docs.errors import ConfigurationError
+from clean_docs.models import VisualProjection
+
+
+VISUAL_SCHEMA = "sourcebound.visual.v1"
+VISUAL_KEYS = {
+    "schema",
+    "id",
+    "kind",
+    "src",
+    "src_dark",
+    "width",
+    "height",
+    "alt",
+    "caption",
+    "description",
+    "annotations",
+}
+ANNOTATION_KEYS = {"id", "x", "y", "title", "description"}
+IDENTIFIER = re.compile(r"[a-z][a-z0-9]*(?:-[a-z0-9]+)*")
+REMOTE_SOURCE = re.compile(r"https://", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class VisualAnnotation:
+    id: str
+    x: float
+    y: float
+    title: str
+    description: str
+
+
+@dataclass(frozen=True)
+class VisualRecord:
+    id: str
+    kind: str
+    src: str
+    src_dark: str | None
+    width: int
+    height: int
+    alt: str
+    caption: str
+    description: str
+    annotations: tuple[VisualAnnotation, ...]
+    digest: str
+
+
+def _mapping(value: Any, where: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigurationError(f"{where} must be a mapping")
+    return value
+
+
+def _keys(value: dict[str, Any], allowed: set[str], where: str) -> None:
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise ConfigurationError(f"{where} has unknown key(s): {', '.join(unknown)}")
+
+
+def _identifier(value: Any, where: str) -> str:
+    if not isinstance(value, str) or IDENTIFIER.fullmatch(value) is None:
+        raise ConfigurationError(f"{where} must be a kebab-case identifier")
+    return value
+
+
+def _text(value: Any, where: str, *, one_line: bool = False) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigurationError(f"{where} must be non-empty text")
+    result = value.strip()
+    if one_line and ("\n" in result or "\r" in result):
+        raise ConfigurationError(f"{where} must be one line")
+    return result
+
+
+def _dimension(value: Any, where: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ConfigurationError(f"{where} must be a positive integer")
+    return value
+
+
+def _coordinate(value: Any, where: str) -> float:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not 0 <= float(value) <= 100
+    ):
+        raise ConfigurationError(f"{where} must be a number from 0 through 100")
+    return float(value)
+
+
+def _source(value: Any, where: str) -> str:
+    source = _text(value, where, one_line=True)
+    if any(character.isspace() for character in source) or any(
+        character in source for character in "<>()"
+    ):
+        raise ConfigurationError(
+            f"{where} must not contain whitespace or Markdown link delimiters"
+        )
+    if REMOTE_SOURCE.match(source):
+        return source
+    path = Path(source)
+    if path.is_absolute() or ".." in path.parts:
+        raise ConfigurationError(f"{where} must be HTTPS or repository-relative")
+    return path.as_posix()
+
+
+def load_visual_record(path: Path, expected_id: str) -> VisualRecord:
+    try:
+        content = path.read_bytes()
+    except OSError as exc:
+        raise ConfigurationError(f"cannot read visual record {path}: {exc}") from exc
+    try:
+        if path.suffix.lower() == ".json":
+            raw = json.loads(content)
+        else:
+            raw = yaml.safe_load(content)
+    except (json.JSONDecodeError, yaml.YAMLError, UnicodeError) as exc:
+        raise ConfigurationError(f"invalid visual record {path}: {exc}") from exc
+    data = _mapping(raw, f"visual record {path}")
+    _keys(data, VISUAL_KEYS, f"visual record {path}")
+    if data.get("schema") != VISUAL_SCHEMA:
+        raise ConfigurationError(
+            f"visual record {path} must use schema {VISUAL_SCHEMA}"
+        )
+    record_id = _identifier(data.get("id"), f"visual record {path}.id")
+    if record_id != expected_id:
+        raise ConfigurationError(
+            f"visual projection id {expected_id!r} does not match record id {record_id!r}"
+        )
+    kind = data.get("kind")
+    if kind not in {"diagram", "screenshot"}:
+        raise ConfigurationError(
+            f"visual record {path}.kind must be diagram or screenshot"
+        )
+    annotations_raw = data.get("annotations", [])
+    if not isinstance(annotations_raw, list):
+        raise ConfigurationError(f"visual record {path}.annotations must be a list")
+    annotations: list[VisualAnnotation] = []
+    annotation_ids: set[str] = set()
+    for index, raw_annotation in enumerate(annotations_raw):
+        where = f"visual record {path}.annotations[{index}]"
+        item = _mapping(raw_annotation, where)
+        _keys(item, ANNOTATION_KEYS, where)
+        annotation_id = _identifier(item.get("id"), f"{where}.id")
+        if annotation_id in annotation_ids:
+            raise ConfigurationError(f"duplicate visual annotation id: {annotation_id}")
+        annotation_ids.add(annotation_id)
+        annotations.append(
+            VisualAnnotation(
+                annotation_id,
+                _coordinate(item.get("x"), f"{where}.x"),
+                _coordinate(item.get("y"), f"{where}.y"),
+                _text(item.get("title"), f"{where}.title", one_line=True),
+                _text(item.get("description"), f"{where}.description"),
+            )
+        )
+    src_dark_raw = data.get("src_dark")
+    return VisualRecord(
+        id=record_id,
+        kind=kind,
+        src=_source(data.get("src"), f"visual record {path}.src"),
+        src_dark=(
+            _source(src_dark_raw, f"visual record {path}.src_dark")
+            if src_dark_raw is not None
+            else None
+        ),
+        width=_dimension(data.get("width"), f"visual record {path}.width"),
+        height=_dimension(data.get("height"), f"visual record {path}.height"),
+        alt=_text(data.get("alt"), f"visual record {path}.alt", one_line=True),
+        caption=_text(
+            data.get("caption"), f"visual record {path}.caption", one_line=True
+        ),
+        description=_text(
+            data.get("description"), f"visual record {path}.description"
+        ),
+        annotations=tuple(annotations),
+        digest=hashlib.sha256(content).hexdigest(),
+    )
+
+
+def _asset(root: Path, output: Path, source: str) -> str:
+    if REMOTE_SOURCE.match(source):
+        return source
+    asset = root / source
+    try:
+        asset.resolve().relative_to(root.resolve())
+    except ValueError as exc:
+        raise ConfigurationError(f"visual asset escapes the repository: {source}") from exc
+    if not asset.is_file():
+        raise ConfigurationError(f"visual asset does not exist: {source}")
+    return os.path.relpath(asset, (root / output).parent).replace(os.sep, "/")
+
+
+def _attribute(value: str) -> str:
+    return html.escape(value, quote=True)
+
+
+def _html_text(value: str) -> str:
+    return html.escape(value).replace("\n", "<br />\n")
+
+
+def _style(output: Path, html_value: str, mdx_value: str) -> str:
+    if output.suffix.lower() == ".mdx":
+        return f"style={{{{{mdx_value}}}}}"
+    return f'style="{html_value}"'
+
+
+def render_human_visual(
+    root: Path,
+    projection: VisualProjection,
+    record: VisualRecord,
+) -> str:
+    src = _asset(root, projection.human_output, record.src)
+    dark = (
+        _asset(root, projection.human_output, record.src_dark)
+        if record.src_dark
+        else None
+    )
+    visual_id = f"visual-{record.id}"
+    receipt = (
+        f"generated by Sourcebound from {projection.source.as_posix()}; "
+        f"sha256: {record.digest}"
+    )
+    comment = (
+        f"{{/* {receipt} */}}"
+        if projection.human_output.suffix.lower() == ".mdx"
+        else f"<!-- {receipt} -->"
+    )
+    lines = [
+        comment,
+        f'<figure id="{visual_id}" data-sourcebound-visual="{VISUAL_SCHEMA}">',
+        "  <div "
+        + _style(
+            projection.human_output,
+            "position: relative; display: inline-block; max-width: 100%;",
+            " position: 'relative', display: 'inline-block', maxWidth: '100%' ",
+        )
+        + ">",
+        "    <picture>",
+    ]
+    if dark:
+        source_set = "srcSet" if projection.human_output.suffix.lower() == ".mdx" else "srcset"
+        lines.append(
+            f'      <source media="(prefers-color-scheme: dark)" '
+            f'{source_set}="{_attribute(dark)}" />'
+        )
+    image_style = _style(
+        projection.human_output,
+        "display: block; max-width: 100%; height: auto;",
+        " display: 'block', maxWidth: '100%', height: 'auto' ",
+    )
+    lines.extend([
+        f'      <img src="{_attribute(src)}" alt="{_attribute(record.alt)}" '
+        f'width="{record.width}" height="{record.height}" '
+        f"{image_style} />",
+        "    </picture>",
+    ])
+    for number, annotation in enumerate(record.annotations, start=1):
+        anchor = f"{visual_id}-annotation-{annotation.id}"
+        marker_style = _style(
+            projection.human_output,
+            f"position: absolute; left: {annotation.x:g}%; top: {annotation.y:g}%; "
+            "transform: translate(-50%, -50%); display: inline-flex; "
+            "align-items: center; justify-content: center; width: 1.75rem; "
+            "height: 1.75rem; border: 2px solid currentColor; border-radius: 999px; "
+            "background: Canvas; color: CanvasText; font-weight: 700;",
+            " position: 'absolute', "
+            f"left: '{annotation.x:g}%', top: '{annotation.y:g}%', "
+            "transform: 'translate(-50%, -50%)', display: 'inline-flex', "
+            "alignItems: 'center', justifyContent: 'center', width: '1.75rem', "
+            "height: '1.75rem', border: '2px solid currentColor', "
+            "borderRadius: '999px', background: 'Canvas', color: 'CanvasText', "
+            "fontWeight: 700 ",
+        )
+        lines.append(
+            f'    <a href="#{anchor}" aria-label="{number}: '
+            f'{_attribute(annotation.title)}" {marker_style}>{number}</a>'
+        )
+    lines.extend([
+        "  </div>",
+        f"  <figcaption>{_html_text(record.caption)}</figcaption>",
+        f'  <p><strong>Description:</strong> {_html_text(record.description)}</p>',
+    ])
+    if record.annotations:
+        lines.append('  <ol aria-label="Annotation key">')
+        for annotation in record.annotations:
+            anchor = f"{visual_id}-annotation-{annotation.id}"
+            lines.append(
+                f'    <li id="{anchor}"><strong>{_html_text(annotation.title)}</strong>: '
+                f'{_html_text(annotation.description)}</li>'
+            )
+        lines.append("  </ol>")
+    lines.extend(["</figure>", ""])
+    return "\n".join(lines)
+
+
+def render_agent_visual(
+    root: Path,
+    projection: VisualProjection,
+    record: VisualRecord,
+) -> str:
+    src = _asset(root, projection.agent_output, record.src)
+    lines = [
+        f"# Visual: {record.id}",
+        "",
+        f"- Schema: `{VISUAL_SCHEMA}`",
+        f"- Kind: `{record.kind}`",
+        f"- Canonical record: `{projection.source.as_posix()}`",
+        f"- Record sha256: `{record.digest}`",
+        f"- Source image: [{record.src}]({src})",
+    ]
+    if record.src_dark:
+        dark = _asset(root, projection.agent_output, record.src_dark)
+        lines.append(f"- Dark source image: [{record.src_dark}]({dark})")
+    lines.extend([
+        f"- Intrinsic size: {record.width} × {record.height}",
+        f"- Alternative text: {record.alt}",
+        f"- Caption: {record.caption}",
+        "",
+        "## Complete text equivalent",
+        "",
+        record.description,
+    ])
+    if record.annotations:
+        lines.extend(["", "## Annotations", ""])
+        for number, annotation in enumerate(record.annotations, start=1):
+            lines.extend([
+                f"{number}. **{annotation.title}** "
+                f"(`x={annotation.x:g}%`, `y={annotation.y:g}%`)",
+                f"   {annotation.description}",
+            ])
+    lines.append("")
+    return "\n".join(lines)

clean_docs/write_gate.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from clean_docs.policy import PolicyFinding
+
+
+CODE_EXTENSIONS = {
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".sh", ".go", ".rs", ".rb", ".java",
+    ".sql", ".c", ".cpp", ".swift",
+}
+DATA_EXTENSIONS = {".json", ".jsonl", ".csv", ".yaml", ".yml", ".toml", ".lock", ".plist"}
+EXEMPT_PATH_PARTS = (
+    "narrative_content", "golden_corpus", "/gold/", "fixtures", "corpus", ".venv/",
+    "node_modules/", "quality-gate", "quality_gate",
+)
+SECRET_RULES = (
+    ("secret-aws-key", re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "all"),
+    ("secret-github-token", re.compile(r"\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})"), "all"),
+    # Fail closed: a long sk- kebab slug can be redacted rather than missed.
+    ("secret-openai-key", re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"), "all"),
+    ("secret-pem-private", re.compile(r"-----BEGIN [A-Z ]{0,20}PRIVATE KEY-----"), "all"),
+    ("secret-jwt", re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b"), "all"),
+    ("secret-auth-header-json", re.compile(r'"(authorization|api[_-]?key|apikey|token|secret|password)"\s*:\s*"(?=[^"]*[0-9])(Bearer |Basic |Token )?[A-Za-z0-9_./+=-]{16,}"', re.I), "all"),
+)
+RULES = (
+    ("delve", re.compile(r"\bdelv(e|es|ing)\b", re.I), "all"),
+    ("important-to-note", re.compile(r"\bit('| i)s important to note\b", re.I), "all"),
+    ("fast-paced", re.compile(r"in today's fast-paced", re.I), "all"),
+    ("as-an-ai", re.compile(r"\bas an ai\b", re.I), "all"),
+    ("assistant-voice", re.compile(r"\b(great question|i'd be happy to|certainly!)\B", re.I), "all"),
+    ("marketing-register", re.compile(r"\b(seamlessly integrat|game.chang|revolutioniz|rich tapestry)", re.I), "all"),
+    ("utilize-verb", re.compile(r"\butiliz(e|es|ed|ing)\b", re.I), "all"),
+    ("in-conclusion", re.compile(r"^\s*in conclusion,", re.I | re.M), "all"),
+    ("hedge-stack", re.compile(r"\b(might|may|could)\s+(potentially|possibly|perhaps)\b", re.I), "all"),
+    ("unverified-claim", re.compile(r"\bshould (now )?work\b", re.I), "all"),
+    ("bare-except", re.compile(r"^\s*except\s*:\s*(#.*)?$", re.M), "code"),
+    ("swallowed-exception", re.compile(r"except[^\n]*:\s*(\n\s*)?pass\b"), "code"),
+    ("placeholder-cred", re.compile(r"(your[_-]api[_-]key|changeme|<your_|sk-xxxx|lorem ipsum)", re.I), "code"),
+    ("deferred-work-marker", re.compile(r"\b(TODO|FIXME|XXX|HACK)\b"), "code"),
+    ("comment-meta-narration", re.compile(r"(#\s*this (function|method|class|file)\b|\"\"\"\s*This (function|method|class)\b)", re.I), "code"),
+    ("emoji-in-code", re.compile(r"[\U0001F300-\U0001FAFF✅❌✨]"), "code"),
+) + SECRET_RULES
+PRAGMA = re.compile(r"slop-ok:\s*\S+")
+
+
+@dataclass(frozen=True)
+class WriteGateResult:
+    path: str
+    findings: tuple[PolicyFinding, ...]
+    overridden: tuple[PolicyFinding, ...]
+
+
+def redact_secrets(text: str) -> tuple[str, tuple[str, ...]]:
+    redacted = text
+    rules: list[str] = []
+    for rule_id, pattern, _applies in SECRET_RULES:
+        if pattern.search(redacted):
+            rules.append(rule_id)
+            redacted = pattern.sub("[REDACTED]", redacted)
+    return redacted, tuple(rules)
+
+
+def _new_content(tool_name: str, tool_input: dict[str, Any]) -> str:
+    if tool_name == "Write":
+        return str(tool_input.get("content", ""))
+    if tool_name == "Edit":
+        return str(tool_input.get("new_string", ""))
+    if tool_name == "MultiEdit":
+        return "\n".join(str(edit.get("new_string", "")) for edit in tool_input.get("edits", []))
+    if tool_name == "NotebookEdit":
+        return str(tool_input.get("new_source", ""))
+    return ""
+
+
+def _file_class(path: str) -> str:
+    extension = Path(path).suffix.lower()
+    if extension in CODE_EXTENSIONS:
+        return "code"
+    if extension in DATA_EXTENSIONS:
+        return "data"
+    return "prose"
+
+
+def evaluate_write(payload: dict[str, Any]) -> WriteGateResult:
+    """Evaluate one pre-write hook payload without reading or writing the target file."""
+    tool_name = str(payload.get("tool_name", ""))
+    tool_input = payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    path = str(tool_input.get("file_path", "") or tool_input.get("notebook_path", ""))
+    if any(part in path for part in EXEMPT_PATH_PARTS) or _file_class(path) == "data":
+        return WriteGateResult(path, (), ())
+    content = _new_content(tool_name, tool_input)
+    if not content:
+        return WriteGateResult(path, (), ())
+    lines = content.splitlines()
+    findings: list[PolicyFinding] = []
+    overridden: list[PolicyFinding] = []
+    file_class = _file_class(path)
+    for rule_id, pattern, applies in RULES:
+        if applies == "code" and file_class != "code":
+            continue
+        for match in pattern.finditer(content):
+            line_number = content.count("\n", 0, match.start()) + 1
+            line = lines[line_number - 1] if line_number <= len(lines) else ""
+            finding = PolicyFinding(path, line_number, rule_id, line.strip()[:90])
+            (overridden if PRAGMA.search(line) else findings).append(finding)
+    return WriteGateResult(path, tuple(findings), tuple(overridden))
+
+
+def _log(path: Path, entry: dict[str, Any]) -> None:
+    try:
+        entry["ts"] = datetime.now(timezone.utc).isoformat()
+        entry["cwd"] = os.getcwd()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass
+
+
+def main() -> int:
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    if not isinstance(payload, dict):
+        return 0
+    result = evaluate_write(payload)
+    log_path = Path(os.path.expanduser("~/.claude/quality_gate_log.jsonl"))
+    if result.overridden:
+        _log(log_path, {
+            "file": result.path,
+            "action": "override",
+            "hits": [
+                {"rule": item.rule, "line": item.line, "snippet": item.detail}
+                for item in result.overridden
+            ],
+        })
+    if not result.findings:
+        return 0
+    _log(log_path, {
+        "file": result.path,
+        "action": "block",
+        "hits": [
+            {"rule": item.rule, "line": item.line, "snippet": item.detail}
+            for item in result.findings
+        ],
+    })
+    sys.stderr.write(
+        f"QUALITY GATE: {len(result.findings)} slop pattern(s) blocked this write to {result.path}.\n"
+        "Rewrite the flagged content without the pattern -- do not paraphrase around "
+        "it with equivalent filler; state things plainly or cut them.\n"
+    )
+    for finding in result.findings[:10]:
+        sys.stderr.write(f"  [{finding.rule}] line {finding.line}: {finding.detail}\n")
+    sys.stderr.write(
+        "If a flagged line is INTENTIONAL content (test data, authored persona text), "
+        "append `slop-ok: <reason>` to that exact line -- overrides are logged and "
+        "reviewed at retro.\n"
+    )
+    return 2

sourcebound-1.2.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owen Schoeniger.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sourcebound-1.2.1.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.2
+Name: sourcebound
+Version: 1.2.1
+Summary: Bind documentation claims to source evidence and fail CI when they drift.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: build==1.2.2.post1; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: setuptools==75.8.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: wheel==0.45.1; extra == "dev"
+
+# Sourcebound
+
+<!-- sourcebound:policy register-v2 -->
+<!-- sourcebound:purpose -->
+Sourcebound is a documentation engine and CLI for maintainers who need code and prose to change together. It binds selected claims to their defining sources, so drifted documentation fails locally and in CI instead of reaching readers.
+<!-- sourcebound:end purpose -->
+
+[![CI](https://github.com/owieschon/sourcebound/actions/workflows/ci.yml/badge.svg)](https://github.com/owieschon/sourcebound/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/owieschon/sourcebound?display_name=tag&sort=semver)](https://github.com/owieschon/sourcebound/releases/latest) [![License: MIT](https://img.shields.io/badge/license-MIT-25225f.svg)](LICENSE)
+
+**[Install the stable release and catch your first stale claim](docs/learn/tutorial-catch-a-lying-doc.md)**.
+
+The final `sourcebound verify` command prints a [`sourcebound.outcome.v2` receipt](docs/SUPPORT.md#record-local-outcomes) with `"ok": true`.
+
+Before adoption, `audit` reports bounded repository-neutral advisories. A manifest turns integrity checks into gates; policy markers opt compatible writing rules into specific documents. Neither authorizes Sourcebound to flatten repository-native forms.
+
+| If you need to... | Start with | You will leave with... |
+| --- | --- | --- |
+| Try the repair loop | [Runnable tutorial](docs/learn/tutorial-catch-a-lying-doc.md) | A failed drift check and a repaired page |
+| Choose a command | [CLI reference](docs/CLI.md) | The command and its write boundary |
+| Configure a binding | [Manifest reference](docs/REFERENCE.md) | A source-bound fact with the right depth |
+| Review a pull request | [Coverage-stating verdict](docs/CLI.md#pull-request-verdicts) | One pinned state with gaps, skips, and non-claims visible |
+| Turn a review issue into tests | [Improvement candidates](docs/IMPROVEMENTS.md) | Separate documentation and product tests without gate authority |
+| Evaluate human or agent tasks | [Evaluation guide](docs/EVALUATION.md) | A replayable result bound to its context and scorer |
+| Build grounded release notes | [Release guide](docs/RELEASES.md) | A factual delta with source evidence |
+| Measure recurring operational problems | [Opt-in feedback loop](docs/FEEDBACK.md) | Bounded envelopes and a receipted improvement case |
+| Understand trust boundaries | [Security model](docs/SECURITY_MODEL.md) | The process and host guarantees |
+
+## Why Sourcebound exists
+
+<!-- sourcebound:begin product-overview -->
+A stale sentence does not fail loudly. It keeps a straight face after the code has moved on, and reviewers have no mechanical way to identify the false claim. Sourcebound gives each protected fact a source, then checks that relationship again in CI.
+
+Declared sources own the protected facts. A packaged policy enforces the deterministic form floor; authored judgment still owns motivation, pedagogy, and voice. Static adapters read common code and schema formats, while declared commands run under explicit process controls. The engine can repair bound regions, rank static count and column candidates, enforce accepted source-claim relationships, and project canonical text and visual records into purpose-built human and agent surfaces with local receipts.
+<!-- sourcebound:end product-overview -->
+
+Human review can improve a sentence. It cannot make the sentence fail when its defining source changes. The [deterministic seam](docs/learn/deep-dive-the-deterministic-seam.md) explains how Sourcebound separates source evidence, optional phrasing, and gate authority.
+
+## Install in the repository you want to protect
+
+From that repository, download the latest stable wheel, install it in an isolated environment, and run the manifest-free audit:
+
+```bash
+release_dir="$(mktemp -d)"
+gh release download --repo owieschon/sourcebound \
+  --pattern 'sourcebound-*-py3-none-any.whl' --dir "$release_dir"
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install "$release_dir"/sourcebound-*.whl
+sourcebound audit
+```
+
+After reviewing the assessment, inspect the files that `init` proposes before accepting its gate:
+
+```bash
+sourcebound init --no-model
+git diff -- .sourcebound.yml .sourcebound/repository-surface.md README.md llms.txt
+sourcebound check
+sourcebound verify
+```
+
+An established, unregistered README stays byte-for-byte authored. Init writes its detected catalog to `.sourcebound/repository-surface.md`; a new README or one that adopted the register may own that region directly.
+
+After a bound source changes, run `check`, then use `drive` for a declared repair. Run `project` when a declared projection depends on the repaired document, then run `verify`. The [tutorial](docs/learn/tutorial-catch-a-lying-doc.md) shows the failure before the repair; the [support guide](docs/SUPPORT.md) covers mature-repository adoption.
+
+## How the pieces fit
+
+Three inputs stay separate before the deterministic core:
+
+- **Authored intent** records why a surface matters. Sourcebound preserves that purpose; it does not infer its priority or turn judgment into gate authority.
+- **Repository contract** declares sources, binding mechanisms, process limits, and projections. Policy markers scope compatible form checks; they do not certify voice.
+- **Change state** combines base and head refs with that contract to produce an immutable impact plan. Static adapters and bounded commands produce typed evidence. Each mechanism proves only its declared relationship; accepted source-claim checks are separate, and unbound prose stays visibly unknown.
+
+The core exposes four job-specific exits:
+
+1. **Repair bounded prose.** `drive` writes only planned regions. `project` runs separately when a declared output depends on changed documentation.
+2. **Reject stale changes.** `check` and `verdict` are read-only. The verdict names changed, bound, unbound, and skipped surfaces.
+3. **Publish agent context.** `project` writes declared outputs such as `llms.txt` and context bundles.
+4. **Record local state.** `verify` emits its own outcome receipt.
+
+`verdict` and `verify` produce independent receipts. Neither certifies unbound or judgment prose. The [product contract](SOURCEBOUND_SPEC.md) defines each authority boundary.
+
+## Current boundaries
+
+- Catalog coverage detects source additions, removals, and replacements; it does not validate prose.
+- Source-claim discovery ranks static count and identifier-set candidates. A candidate remains advisory until the repository accepts its exact document and source relationship.
+- Declared processes use time, I/O, and environment controls. The host owns network isolation; see the [security model](docs/SECURITY_MODEL.md).
+- The manifest decides what Sourcebound evaluates. Authored purpose records goals; Sourcebound does not infer or certify them.
+- Feedback is off by default. Enabled runs queue bounded local envelopes; only an explicit `feedback flush` contacts the configured sink, and delivery cannot change a gate result.
+
+Use the [learning path](docs/learn/index.md) for examples. The [product contract](SOURCEBOUND_SPEC.md) owns parser, write-boundary, and exit-code details.