fixyourdocs 0.2.0__tar.gz → 0.3.0__tar.gz

fixyourdocs-0.3.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## v0.3.0 — 2026-06-09
+
+Consumer-side ("report anywhere") mode. New `Client` / `AsyncClient`
+constructor options, all safe-by-default:
+
+- **Client-side privacy guard** (`enforce_privacy=True`, default). Before
+  any network call, `send()` validates `doc_url` and raises the new
+  `PrivacyError` (no GET, no POST) when the URL is not a public
+  `https://` doc page — rejecting non-`https` schemes, missing hosts,
+  `localhost` / `.localhost` / `.local` / `.internal`, bare single-label
+  hostnames, and IP literals in loopback / private / link-local /
+  reserved ranges (including IPv4-mapped-IPv6 forms). Pass
+  `enforce_privacy=False` to opt out for first-party / self-hosted use.
+- **Transcript stripping** (`include_transcript=False`, default). The
+  serialized body omits `task_context.transcript_excerpt`; if that leaves
+  `task_context` empty it is dropped. Set `include_transcript=True` to
+  send it. The caller's `Report` is never mutated.
+- **`.well-known` opt-out discovery** (`discover_opt_out=True`, default).
+  Before posting, `send()` checks
+  `https://<host>/.well-known/docs-feedback.json` and raises
+  `OptedOutError` when the host has opted out (`opt_in: false`). Results
+  are cached per host with a 24h TTL (network errors are not cached);
+  404 / non-2xx / invalid JSON is treated as opted-in. v0 honours the
+  opt-out flag only — a custom endpoint advertised by the well-known is
+  not yet followed.
+- **`fixyourdocs init --global`** writes the consumer-side "report stale
+  third-party docs" block to a global agent-config file (default
+  `~/.claude/CLAUDE.md`, override with `--file`). Idempotent.
+
+## v0.2.1 — 2026-06-03
+
+- Publish the dropped `View:` CLI line: `fixyourdocs report` no longer
+  prints a `View: https://hub.fixyourdocs.io/r/<id>` link (that route
+  404s; the code change merged in 0.2.0 but was never released). The Hub
+  also retired the public `GET /v1/reports/{id}` read endpoint — the SDK
+  is POST-only (`Client.send()`), so this is a release-only change with
+  no client API difference.
+
+## v0.2.0 — 2026-05-26
+
+- Add `fixyourdocs init` CLI (appends canonical snippet from `agents-md-snippet` to `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / `.github/copilot-instructions.md`; idempotent).
+- Add `fixyourdocs report` CLI (sends a Docs Feedback Protocol v0 report; supports `--json`, exit codes 0/1/2).
+- Embed canonical snippet from `agents-md-snippet`; CI fails on drift.
+
+## v0.1.0 — initial release
+
+- Typed client for Docs Feedback Protocol v0.

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/CODE_OF_CONDUCT.md

@@ -36,7 +36,7 @@ This Code of Conduct applies within all community spaces, and also applies when
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@fixyourdocs.org. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@fixyourdocs.io. All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/CONTRIBUTING.md

@@ -33,4 +33,4 @@ comment on your PR with a one-click sign-off link. See the CLA text at
 
 By participating you agree to abide by the
 [Code of Conduct](CODE_OF_CONDUCT.md) (Contributor Covenant 2.1).
-Report incidents to <hello@fixyourdocs.org>.
+Report incidents to <hello@fixyourdocs.io>.

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: fixyourdocs
-Version: 0.2.0
+Version: 0.3.0
 Summary: Reference Python SDK for the Docs Feedback Protocol
 Project-URL: Homepage, https://docsfeedback.org
 Project-URL: Repository, https://github.com/fixyourdocs/sdk-python
 Project-URL: Specification, https://github.com/fixyourdocs/protocol
-Author-email: FixYourDocs <hello@fixyourdocs.org>
+Author-email: FixYourDocs <hello@fixyourdocs.io>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: agents,ai,docs,documentation,feedback,protocol
@@ -37,6 +37,7 @@ Reference Python SDK for the [Docs Feedback Protocol](https://github.com/fixyour
 v0. The protocol lets AI agents file structured reports against
 documentation pages when the docs break agent task flows.
 
+- Full docs: <https://docs.fixyourdocs.io/sdk/python/>.
 - Spec: <https://docsfeedback.org>.
 - Why this exists: [the FixYourDocs manifesto](https://github.com/fixyourdocs/manifesto/blob/main/MANIFESTO.md).
 
@@ -70,6 +71,13 @@ pipx run fixyourdocs report \
 `.github/copilot-instructions.md` and appends to whichever exists
 (falling back to creating `AGENTS.md`). Pass `--file <path>` to override.
 
+`init --global` instead writes the consumer-side "report stale
+third-party docs" block to a global agent-config file (default
+`~/.claude/CLAUDE.md`, override with `--file`). Use this when you want an
+agent to offer to report broken **third-party** docs it consults across
+all your projects, rather than wiring the per-repo block into one repo.
+It is idempotent.
+
 `report` accepts `--details`, `--suggested-fix`, `--api-url`, `--token`,
 and `--json` for machine-readable output. Exit codes: `0` success,
 `2` user error, `1` transport or server error.
@@ -126,6 +134,39 @@ so the SDK exposes two ways to build a `Report`:
 
 Both produce identical wire output.
 
+## Consumer-side mode
+
+When an agent reports against **third-party** docs it consulted (rather
+than your own first-party docs), the client defaults guard against
+leaking private context and against pestering hosts that have opted out.
+All three options are constructor arguments on both `Client` and
+`AsyncClient`:
+
+```python
+from fixyourdocs import Client, PrivacyError, OptedOutError
+
+with Client(api_url="https://hub.fixyourdocs.io") as client:
+    client.send(report)  # guards run before any network call
+```
+
+- **`enforce_privacy=True`** (default) — before any network call,
+  validates `report.doc_url` and raises `PrivacyError` (no request is
+  made) unless it is a public `https://` page. Rejected: non-`https`
+  schemes; missing hosts; `localhost` and `.localhost` / `.local` /
+  `.internal` names; bare single-label hostnames; and IP literals in
+  loopback / private / link-local / reserved ranges. Pass
+  `enforce_privacy=False` for first-party / self-hosted / internal docs.
+- **`include_transcript=False`** (default) — strips
+  `task_context.transcript_excerpt` from the wire body (dropping
+  `task_context` entirely if nothing else remains) so transcript
+  snippets never leave the machine unless you opt in with
+  `include_transcript=True`. Your `Report` object is never mutated.
+- **`discover_opt_out=True`** (default) — before posting, fetches
+  `https://<doc-host>/.well-known/docs-feedback.json`; if the host
+  published `opt_in: false`, `send()` raises `OptedOutError` and does not
+  post. The result is cached per host for 24h. Missing/invalid
+  well-known files are treated as opted-in.
+
 ## Errors
 
 Non-2xx responses raise typed exceptions:
@@ -142,7 +183,10 @@ Non-2xx responses raise typed exceptions:
 | 429 | `RateLimitedError` (`.retry_after`) |
 | 5xx | `ServerError` (after one automatic retry on 502/503/504) |
 
-All inherit from `FixYourDocsError`.
+All inherit from `FixYourDocsError`. In consumer-side mode, `send()` may
+also raise `PrivacyError` (non-public `doc_url`) or `OptedOutError`
+(host opted out via its `.well-known` file) *before* any request is
+posted.
 
 ## Licence
 

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/README.md

@@ -4,6 +4,7 @@ Reference Python SDK for the [Docs Feedback Protocol](https://github.com/fixyour
 v0. The protocol lets AI agents file structured reports against
 documentation pages when the docs break agent task flows.
 
+- Full docs: <https://docs.fixyourdocs.io/sdk/python/>.
 - Spec: <https://docsfeedback.org>.
 - Why this exists: [the FixYourDocs manifesto](https://github.com/fixyourdocs/manifesto/blob/main/MANIFESTO.md).
 
@@ -37,6 +38,13 @@ pipx run fixyourdocs report \
 `.github/copilot-instructions.md` and appends to whichever exists
 (falling back to creating `AGENTS.md`). Pass `--file <path>` to override.
 
+`init --global` instead writes the consumer-side "report stale
+third-party docs" block to a global agent-config file (default
+`~/.claude/CLAUDE.md`, override with `--file`). Use this when you want an
+agent to offer to report broken **third-party** docs it consults across
+all your projects, rather than wiring the per-repo block into one repo.
+It is idempotent.
+
 `report` accepts `--details`, `--suggested-fix`, `--api-url`, `--token`,
 and `--json` for machine-readable output. Exit codes: `0` success,
 `2` user error, `1` transport or server error.
@@ -93,6 +101,39 @@ so the SDK exposes two ways to build a `Report`:
 
 Both produce identical wire output.
 
+## Consumer-side mode
+
+When an agent reports against **third-party** docs it consulted (rather
+than your own first-party docs), the client defaults guard against
+leaking private context and against pestering hosts that have opted out.
+All three options are constructor arguments on both `Client` and
+`AsyncClient`:
+
+```python
+from fixyourdocs import Client, PrivacyError, OptedOutError
+
+with Client(api_url="https://hub.fixyourdocs.io") as client:
+    client.send(report)  # guards run before any network call
+```
+
+- **`enforce_privacy=True`** (default) — before any network call,
+  validates `report.doc_url` and raises `PrivacyError` (no request is
+  made) unless it is a public `https://` page. Rejected: non-`https`
+  schemes; missing hosts; `localhost` and `.localhost` / `.local` /
+  `.internal` names; bare single-label hostnames; and IP literals in
+  loopback / private / link-local / reserved ranges. Pass
+  `enforce_privacy=False` for first-party / self-hosted / internal docs.
+- **`include_transcript=False`** (default) — strips
+  `task_context.transcript_excerpt` from the wire body (dropping
+  `task_context` entirely if nothing else remains) so transcript
+  snippets never leave the machine unless you opt in with
+  `include_transcript=True`. Your `Report` object is never mutated.
+- **`discover_opt_out=True`** (default) — before posting, fetches
+  `https://<doc-host>/.well-known/docs-feedback.json`; if the host
+  published `opt_in: false`, `send()` raises `OptedOutError` and does not
+  post. The result is cached per host for 24h. Missing/invalid
+  well-known files are treated as opted-in.
+
 ## Errors
 
 Non-2xx responses raise typed exceptions:
@@ -109,7 +150,10 @@ Non-2xx responses raise typed exceptions:
 | 429 | `RateLimitedError` (`.retry_after`) |
 | 5xx | `ServerError` (after one automatic retry on 502/503/504) |
 
-All inherit from `FixYourDocsError`.
+All inherit from `FixYourDocsError`. In consumer-side mode, `send()` may
+also raise `PrivacyError` (non-public `doc_url`) or `OptedOutError`
+(host opted out via its `.well-known` file) *before* any request is
+posted.
 
 ## Licence
 

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fixyourdocs"
-version = "0.2.0"
+version = "0.3.0"
 description = "Reference Python SDK for the Docs Feedback Protocol"
 readme = "README.md"
 requires-python = ">=3.9"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
-authors = [{ name = "FixYourDocs", email = "hello@fixyourdocs.org" }]
+authors = [{ name = "FixYourDocs", email = "hello@fixyourdocs.io" }]
 keywords = ["docs", "documentation", "agents", "ai", "feedback", "protocol"]
 classifiers = [
   "Development Status :: 3 - Alpha",

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/src/fixyourdocs/__init__.py

@@ -5,7 +5,7 @@ See <https://github.com/fixyourdocs/protocol> for the wire-format spec.
 
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from fixyourdocs._results import SendResult
 from fixyourdocs.client import AsyncClient, Client
@@ -16,6 +16,7 @@ from fixyourdocs.errors import (
     OptedOutError,
     PayloadTooLargeError,
     PolicyRejectedError,
+    PrivacyError,
     RateLimitedError,
     ServerError,
     UnsupportedMediaTypeError,
@@ -44,6 +45,7 @@ __all__ = [
     "OptedOutError",
     "PayloadTooLargeError",
     "PolicyRejectedError",
+    "PrivacyError",
     "RateLimitedError",
     "Report",
     "ReportBody",

{fixyourdocs-0.2.0 → fixyourdocs-0.3.0}/src/fixyourdocs/_cli.py

@@ -17,7 +17,7 @@ from pathlib import Path
 from typing import IO, Optional
 
 from fixyourdocs import __version__
-from fixyourdocs._init import run_init
+from fixyourdocs._init import run_init, run_init_global
 from fixyourdocs.client import Client
 from fixyourdocs.errors import FixYourDocsError
 from fixyourdocs.models import Report, ReportKind
@@ -47,7 +47,18 @@ def _build_parser() -> argparse.ArgumentParser:
         "--file",
         help=(
             "Explicit target file (skips auto-detection of AGENTS.md / "
-            "CLAUDE.md / .cursor/rules / .github/copilot-instructions.md)."
+            "CLAUDE.md / .cursor/rules / .github/copilot-instructions.md). "
+            "With --global, overrides the default ~/.claude/CLAUDE.md."
+        ),
+    )
+    init_p.add_argument(
+        "--global",
+        dest="global_",
+        action="store_true",
+        help=(
+            "Write the consumer-side 'report stale third-party docs' block "
+            "to a global agent-config file (default ~/.claude/CLAUDE.md) "
+            "instead of the per-repo AGENTS.md block."
         ),
     )
     init_p.add_argument(
@@ -81,7 +92,13 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def _do_init(args: argparse.Namespace, stdout: IO[str]) -> int:
-    result = run_init(cwd=Path.cwd(), file=args.file)
+    if getattr(args, "global_", False):
+        result = run_init_global(file=args.file)
+        label = "global agent-config block"
+    else:
+        result = run_init(cwd=Path.cwd(), file=args.file)
+        label = "FixYourDocs snippet"
+
     if args.json:
         stdout.write(
             json.dumps(
@@ -94,15 +111,11 @@ def _do_init(args: argparse.Namespace, stdout: IO[str]) -> int:
             + "\n"
         )
     elif result.created:
-        stdout.write(f"Created {result.path} with the FixYourDocs snippet.\n")
+        stdout.write(f"Created {result.path} with the {label}.\n")
     elif result.changed:
-        stdout.write(
-            f"Appended the FixYourDocs snippet to {result.path}.\n"
-        )
+        stdout.write(f"Appended the {label} to {result.path}.\n")
     else:
-        stdout.write(
-            f"No changes — snippet already present in {result.path}.\n"
-        )
+        stdout.write(f"No changes — {label} already present in {result.path}.\n")
     return 0
 
 
@@ -145,7 +158,6 @@ def _do_report(
                     "id": result.id,
                     "received_at": result.received_at.isoformat(),
                     "is_duplicate": result.is_duplicate,
-                    "url": f"{api_url}/r/{result.id}",
                 }
             )
             + "\n"
@@ -153,7 +165,6 @@ def _do_report(
     else:
         label = "Duplicate report" if result.is_duplicate else "Report accepted"
         stdout.write(f"{label}: {result.id}\n")
-        stdout.write(f"View: {api_url}/r/{result.id}\n")
     return 0
 
 

fixyourdocs-0.3.0/src/fixyourdocs/_discovery.py

@@ -0,0 +1,133 @@
+"""``.well-known`` opt-out discovery (consumer-side mode).
+
+Before posting a report, the SDK can check whether the doc host has
+opted out of receiving feedback by publishing
+``/.well-known/docs-feedback.json`` with ``opt_in: false`` (see §5 of the
+protocol spec). This module holds the host-parsing, in-memory per-host
+cache, and the decision logic that is shared between the sync and async
+clients; only the actual HTTP GET differs (sync vs. ``await``), so each
+client passes its already-fetched outcome into :func:`decide`.
+
+v0 scope: opt-out check + default-hub fallback only. A custom
+``endpoint`` advertised by an ``opt_in: true`` well-known is intentionally
+NOT honoured yet.
+# TODO(v0.x): honour custom endpoint from well-known
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib.parse import urlsplit
+
+from fixyourdocs.errors import OptedOutError
+
+# 24h per-host cache TTL.
+CACHE_TTL_SECONDS = 24 * 60 * 60
+
+WELL_KNOWN_PATH = "/.well-known/docs-feedback.json"
+# Short timeout for the discovery probe; it must not stall a report.
+DISCOVERY_TIMEOUT_SECONDS = 3.0
+
+
+def host_from_doc_url(doc_url: str) -> str:
+    """Return the lower-cased host of ``doc_url`` (IPv6 brackets stripped)."""
+    return urlsplit(doc_url).hostname or ""
+
+
+def well_known_url(host: str) -> str:
+    return f"https://{host}{WELL_KNOWN_PATH}"
+
+
+@dataclass
+class _CacheEntry:
+    opt_in: bool
+    since: Optional[str]
+    stored_at: float
+
+
+class OptOutCache:
+    """In-memory per-host opt-out cache with a 24h TTL."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, _CacheEntry] = {}
+
+    def get(self, host: str) -> Optional[_CacheEntry]:
+        entry = self._entries.get(host)
+        if entry is None:
+            return None
+        if time.monotonic() - entry.stored_at >= CACHE_TTL_SECONDS:
+            del self._entries[host]
+            return None
+        return entry
+
+    def store(self, host: str, *, opt_in: bool, since: Optional[str] = None) -> None:
+        self._entries[host] = _CacheEntry(
+            opt_in=opt_in, since=since, stored_at=time.monotonic()
+        )
+
+
+@dataclass
+class FetchOutcome:
+    """Result of the discovery GET (or the lack of one).
+
+    ``status``/``data`` describe an HTTP response that was received;
+    ``network_error`` is ``True`` when the GET could not complete (timeout
+    / connection error) — that case is treated as "absent" but is NOT
+    cached, per spec §5.2 step 5.
+    """
+
+    status: Optional[int] = None
+    data: Optional[Any] = None
+    json_ok: bool = False
+    network_error: bool = False
+
+
+def _opted_out_error(host: str, since: Optional[str]) -> OptedOutError:
+    return OptedOutError(
+        f"doc host {host} has opted out "
+        f"({WELL_KNOWN_PATH} opt_in:false)",
+        since=since,
+    )
+
+
+def check_cache(cache: OptOutCache, host: str) -> Optional[bool]:
+    """Inspect the cache for ``host``.
+
+    Returns ``True`` if a cached entry says proceed, ``None`` on a miss
+    (caller must fetch). Raises :class:`OptedOutError` on a cached
+    opt-out.
+    """
+    entry = cache.get(host)
+    if entry is None:
+        return None
+    if entry.opt_in is False:
+        raise _opted_out_error(host, entry.since)
+    return True
+
+
+def decide(cache: OptOutCache, host: str, outcome: FetchOutcome) -> None:
+    """Apply a freshly-fetched ``outcome`` to the cache and decision.
+
+    Caches the result (except on a network error) and raises
+    :class:`OptedOutError` when the host has opted out. Returns ``None``
+    to mean "proceed to POST".
+    """
+    if outcome.network_error:
+        # Treat as absent, but do NOT cache (spec §5.2 step 5).
+        return
+
+    if outcome.status == 200 and outcome.json_ok and isinstance(outcome.data, dict):
+        opt_in = outcome.data.get("opt_in")
+        if opt_in is False:
+            since = outcome.data.get("since")
+            since_str = since if isinstance(since, str) else None
+            cache.store(host, opt_in=False, since=since_str)
+            raise _opted_out_error(host, since_str)
+        # Valid JSON, not an explicit opt-out -> treat as opted in.
+        cache.store(host, opt_in=True)
+        return
+
+    # 404 / non-2xx / invalid JSON -> absent, cache as opt_in true.
+    cache.store(host, opt_in=True)

fixyourdocs-0.3.0/src/fixyourdocs/_init.py

@@ -0,0 +1,122 @@
+"""``fixyourdocs init`` — append the canonical AGENTS.md block."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from fixyourdocs.snippet import SNIPPET, SNIPPET_HEADING
+
+TARGET_CANDIDATES = (
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".cursor/rules",
+    ".github/copilot-instructions.md",
+)
+
+# Default global agent-config target for ``fixyourdocs init --global``.
+GLOBAL_DEFAULT_TARGET = Path("~/.claude/CLAUDE.md")
+
+# "Mode B" consumer-side block, sourced verbatim from the agents-md-snippet
+# README. Unlike the canonical Mode A snippet in ``snippet.py`` this text is
+# intentionally NOT under the cross-repo snippet-drift lock — it lives here so
+# the consumer/global install path can write it to a global agent-config file.
+GLOBAL_BLOCK_HEADING = "## Reporting stale third-party docs"
+
+GLOBAL_BLOCK = """\
+## Reporting stale third-party docs
+
+While working on this project, if you rely on a **third-party / external**
+documentation page — a library, API, framework, or hosted docs site you
+consulted, *not* this project's own docs, and never an internal, private,
+`localhost`, or login-gated page — and you find it broken, incorrect,
+outdated, or incomplete, **offer to file a structured report** via the
+Docs Feedback Protocol so its maintainers can fix it for the next agent
+(or human) that hits the same issue.
+
+Rules:
+
+- **Ask before sending.** Offer to file the report; only send once the
+  developer confirms.
+- **Public docs only.** Only report a page served over public `https://`.
+  Never report `localhost`, internal, private, or login-gated URLs.
+- **Never include private context.** No private code, secrets, internal
+  URLs, or transcript excerpts from this project.
+
+Prefer the `file_doc_feedback` MCP tool from `@fixyourdocs/mcp-server`
+if available; otherwise POST to `https://hub.fixyourdocs.io/v1/reports`
+per https://docsfeedback.org.
+"""
+
+
+@dataclass(frozen=True)
+class InitResult:
+    path: Path
+    changed: bool
+    created: bool
+
+
+def _pick_default_target(cwd: Path) -> str:
+    for candidate in TARGET_CANDIDATES:
+        if (cwd / candidate).exists():
+            return candidate
+    return "AGENTS.md"
+
+
+def _with_trailing_blank_line(s: str) -> str:
+    if not s:
+        return ""
+    if s.endswith("\n\n"):
+        return s
+    if s.endswith("\n"):
+        return s + "\n"
+    return s + "\n\n"
+
+
+def run_init(cwd: Path, file: Optional[str] = None) -> InitResult:
+    """Append the canonical AGENTS.md block to the chosen target file.
+
+    Idempotent: if the block heading is already present, returns
+    ``InitResult(changed=False)`` and leaves the file untouched.
+    """
+    target_rel = file if file is not None else _pick_default_target(cwd)
+    path = (cwd / target_rel).resolve()
+
+    if not path.exists():
+        path.write_text(SNIPPET)
+        return InitResult(path=path, changed=True, created=True)
+
+    current = path.read_text()
+    if SNIPPET_HEADING in current:
+        return InitResult(path=path, changed=False, created=False)
+
+    path.write_text(_with_trailing_blank_line(current) + SNIPPET)
+    return InitResult(path=path, changed=True, created=False)
+
+
+def run_init_global(file: Optional[str] = None) -> InitResult:
+    """Write the "Mode B" consumer block to a global agent-config file.
+
+    Targets ``~/.claude/CLAUDE.md`` by default; pass ``file`` to override.
+    Idempotent: if the block heading is already present, returns
+    ``InitResult(changed=False)`` and leaves the file untouched. Creates
+    the file (and any missing parent directories) when absent, otherwise
+    appends.
+    """
+    if file is not None:
+        path = Path(file).expanduser().resolve()
+    else:
+        path = GLOBAL_DEFAULT_TARGET.expanduser().resolve()
+
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(GLOBAL_BLOCK)
+        return InitResult(path=path, changed=True, created=True)
+
+    current = path.read_text()
+    if GLOBAL_BLOCK_HEADING in current:
+        return InitResult(path=path, changed=False, created=False)
+
+    path.write_text(_with_trailing_blank_line(current) + GLOBAL_BLOCK)
+    return InitResult(path=path, changed=True, created=False)