pip-install-python
diff --git a/‎lib/network_directory.py‎
Lines changed: 221 additions & 0 deletions b/‎lib/network_directory.py‎
Lines changed: 221 additions & 0 deletions
diff --git a/‎requirements.txt‎
Lines changed: 5 additions & 1 deletion b/‎requirements.txt‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎run.py‎
Lines changed: 41 additions & 3 deletions b/‎run.py‎
Lines changed: 41 additions & 3 deletions
diff --git a/‎scripts/_compat_runner.py‎
Lines changed: 27 additions & 0 deletions b/‎scripts/_compat_runner.py‎
Lines changed: 27 additions & 0 deletions
@@ -0,0 +1,221 @@
+"""Cross-host directory for the 2plot network — one definition, every satellite.
+
+Why this file exists
+--------------------
+Search engines follow links between hosts weakly; agents don't follow them at
+all. A model answering "what does this ecosystem provide?" fetches one or two
+URLs and reasons from what came back. Landing on ``leaflet.2plot.dev`` it sees
+one library, with nothing in the markup saying the other eleven hosts exist.
+``sitemap.xml`` cannot fix that — a sitemap is scoped to its own origin by
+design — so ``dash-improve-my-llms`` 2.1 emits an explicit machine-readable
+directory instead: ``<link rel="related">`` tags in ``<head>``, a ``## Network``
+section in ``/llms.txt``, and followed links in the prerendered body.
+
+Keep the definition **here**, in the template, and import it. Twelve
+hand-maintained copies of the same peer list will drift, and a directory that
+disagrees with itself across hosts is worse than no directory at all.
+
+Three tiers, and the distinction is load-bearing:
+
+``PEERS``
+    Same network, same operator. These build the cross-host graph you own.
+``AFFILIATED``
+    Yours, on unrelated domains. Findable when asked "what else did you
+    build?" without being swept into "what is the 2plot network?".
+``EXTERNAL``
+    Third-party docs you reference but don't own. Emitted ``rel="nofollow"``
+    — references, not endorsements.
+
+Usage in a satellite's ``run.py``, before ``add_llms_routes(app)``::
+
+    from lib.constants import BASE_URL
+    from lib import network_directory
+
+    app._base_url = BASE_URL
+    network_directory.apply(BASE_URL)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+# Only list hosts that are actually live. A directory entry pointing at a
+# subdomain with no site is a dead link an agent will follow once and then
+# distrust the rest of the list for. muicharts.2plot.dev and
+# flexlayout.2plot.dev have no docs site yet — add them in the same change
+# that ships them, not before.
+# UPSTREAM DIVERGENCE — the only edit this file carries, and it is temporary.
+#
+# pannellum.2plot.dev and emojimart.2plot.dev are commented out below because
+# they are NXDOMAIN as of 2026-07-31 (verified via DNS, not just a failed
+# request — email/flows returned 000 on a first curl too, but that was a Render
+# free-tier cold start and they serve fine on retry).
+#
+# The rule this enforces is the module's own, three paragraphs up: "a directory
+# entry pointing at a subdomain with no site is a dead link an agent will follow
+# once and then distrust the rest of the list for." Shipping them would publish
+# two dead links from a live docs site.
+#
+# The real fix belongs in dash-documentation-boilerplate, which is the single
+# definition every satellite copies — otherwise each repo rediscovers this
+# independently. Once those hosts resolve, delete this note and re-copy the file
+# from the boilerplate rather than un-commenting by hand.
+PEERS: List[Dict[str, str]] = [
+    {
+        "name": "2plot.ai",
+        "url": "https://2plot.ai",
+        "description": "Network hub and account origin.",
+    },
+    {
+        "name": "2plot.dev",
+        "url": "https://2plot.dev",
+        "description": "Package index for every open-source component in the network.",
+    },
+    {
+        "name": "Documentation boilerplate",
+        "url": "https://boilerplate.2plot.dev",
+        "description": "The markdown-driven documentation template every satellite site is built from.",
+    },
+    {
+        "name": "dash-leaflet2",
+        "url": "https://leaflet.2plot.dev",
+        "description": "Leaflet 2 maps as Dash components.",
+    },
+    {
+        "name": "dash-mui-scheduler",
+        "url": "https://muischeduler.2plot.dev",
+        "description": "MUI X Scheduler — calendars and event scheduling for Dash.",
+    },
+    {
+        "name": "dash-flows",
+        "url": "https://flows.2plot.dev",
+        "description": "Node-graph editors built on React Flow.",
+    },
+#    {
+#        "name": "dash-pannellum",
+#        "url": "https://pannellum.2plot.dev",
+#        "description": "360° panorama and virtual-tour viewer.",
+#    },
+#    {
+#        "name": "dash-emoji-mart",
+#        "url": "https://emojimart.2plot.dev",
+#        "description": "Emoji picker component.",
+#    },
+    {
+        "name": "dash-email",
+        "url": "https://email.2plot.dev",
+        "description": "Email composition and delivery components.",
+    },
+]
+
+AFFILIATED: List[Dict[str, str]] = [
+    {
+        "name": "Pip Install Python",
+        "url": "https://pip-install-python.com",
+        "description": "The original component documentation site.",
+    },
+    {
+        "name": "Pirate's Bargain",
+        "url": "https://piratesbargain.com",
+        "description": "Deal aggregator built on the same Dash stack.",
+    },
+    {
+        "name": "ai-agent.buzz",
+        "url": "https://ai-agent.buzz",
+        "description": "Agent tooling directory.",
+    },
+]
+
+EXTERNAL: List[Dict[str, Any]] = [
+    {
+        "name": "Dash Mantine Components",
+        "url": "https://www.dash-mantine-components.com",
+        "description": "The UI component layer these docs are built with.",
+        "llms_txt": "https://www.dash-mantine-components.com/llms.txt",
+    },
+    {
+        "name": "Plotly Dash documentation",
+        "url": "https://dash.plotly.com",
+        "description": "Upstream framework documentation.",
+    },
+]
+
+NETWORK_NAME = "The 2plot network"
+NETWORK_DESCRIPTION = (
+    "Open-source Dash component libraries by Pip Install Python. Each component "
+    "has its own documentation site and its own llms.txt; 2plot.dev indexes all "
+    "of them, and 2plot.ai is the hub."
+)
+HUB_URL = "https://2plot.dev"
+
+# The mark drawn in the header of the rendered llms.txt view: "2" + morse
+# encoding of "plot" + "ai", as columns of dots and dashes.
+#
+# No period glyph between the halves — the morse block already separates them,
+# and a literal "." next to it reads as punctuation dropped into a graphic.
+# The renderer turns a suffix ending in "i" into an upward flourish, so "ai"
+# draws as "a" plus that mark; `label` carries the real domain for screen
+# readers and the SVG <title>, which is the only place the dot belongs.
+#
+# Defined here rather than per-app because this module is copied verbatim into
+# every satellite — that is what keeps one mark across the network instead of
+# twelve slightly different ones.
+WORDMARK = {
+    "morse": "plot",
+    "prefix": "2",
+    "suffix": "ai",
+    "label": "2plot.ai",
+}
+
+
+def peers_for(app_url: str) -> List[Dict[str, str]]:
+    """`PEERS` with this app removed.
+
+    A site listing itself as its own peer reads as generated rather than
+    curated, and it wastes a slot in a list an agent may only skim.
+    """
+    own = app_url.rstrip("/")
+    return [p for p in PEERS if p["url"].rstrip("/") != own]
+
+
+def apply(app_url: str) -> None:
+    """Publish the directory for the app served at ``app_url``.
+
+    Degrades rather than fails on older releases of the package. A satellite
+    pinned behind this file should still boot: losing the directory, or losing
+    the wordmark, is a degradation — refusing to start is not.
+
+    That matters during a staged rollout, when this module reaches satellites
+    before the new package does. ``register_network`` arrived in 2.1 and its
+    ``wordmark`` argument in 2.2, and Python raises ``TypeError`` on an unknown
+    keyword, so the argument is only passed when the installed signature
+    actually accepts it.
+    """
+    try:
+        from dash_improve_my_llms import register_network
+    except ImportError:  # pragma: no cover - only on <2.1
+        import warnings
+
+        warnings.warn(
+            "dash-improve-my-llms is older than 2.1, so the cross-host network "
+            "directory will not be published. Upgrade to publish it.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return
+
+    import inspect
+
+    extra: Dict[str, Any] = {}
+    if "wordmark" in inspect.signature(register_network).parameters:
+        extra["wordmark"] = WORDMARK
+
+    register_network(
+        name=NETWORK_NAME,
+        description=NETWORK_DESCRIPTION,
+        hub_url=HUB_URL,
+        peers=peers_for(app_url),
+        affiliated=AFFILIATED,
+        external=EXTERNAL,
+        **extra,
+    )
@@ -30,7 +30,11 @@ dash_mantine_components==2.7.0
 dash-iconify==0.1.2
 markdown2dash
 python-frontmatter
-dash-improve-my-llms>=2.0.0
+# 2.3.3, not 2.0: the upgrade alone fixes the assign-vs-merge home-page stub
+# (2.2.0 merge semantics), directive leakage into agent markdown (2.3.3), and
+# the OAI/Anthropic robots taxonomy (2.3.2/2.3.3). The [flask] extra is just
+# flask>=2.0, already present via Dash.
+dash-improve-my-llms[flask]>=2.3.3
 python-dotenv>=1.0
 pydantic>=2.0
 requests>=2.31
 
@@ -45,10 +45,11 @@
     LLMSConfig,
     RobotsConfig,
     add_llms_routes,
+    mark_hidden,
     register_page_metadata,
 )
 
-from lib import auth, satellite_analytics
+from lib import auth, network_directory, satellite_analytics
 from lib.backend import get_backend_info, resolve_backend
 from lib.constants import APP_VERSION, BASE_URL, LEAFLET_VERSION, SITE_TITLE
 
@@ -140,6 +141,19 @@
 # ----------------------------------------------------------------------------
 app._base_url = BASE_URL
 app._robots_config = RobotsConfig(
+    # DELIBERATE open posture, reviewed against dash-improve-my-llms 2.3.3.
+    #
+    # 2.3.3 makes `True` safe — it blocks the real training crawlers (GPTBot,
+    # ClaudeBot, CCBot) while still allowing Claude-User, Claude-SearchBot and
+    # ChatGPT-User, so the old reason to run `False` (blocking broke claude.ai
+    # fetches through the legacy aliases) is gone. We stay `False` anyway,
+    # because for MIT-licensed component documentation being in the training
+    # corpus is the point: it is how a model recommends this library to someone
+    # who never visits the site. Flip to `True` if that calculus changes.
+    #
+    # Note this diverges from the fleet fingerprint in
+    # handoff/existing_subdomains.md, whose verification expects
+    # `ClaudeBot -> Disallow`. The divergence is intentional, not drift.
     block_ai_training=False,
     allow_ai_search=True,
     allow_traditional=True,
@@ -165,13 +179,37 @@
 # are not supported" errors when the search dropdown re-rendered).
 # ----------------------------------------------------------------------------
 
+# Cross-host network directory. A sitemap is scoped to its own origin by
+# design, so nothing in this site's markup would otherwise say the other 2plot
+# hosts exist — an agent landing here sees one library and no ecosystem. This
+# emits <link rel="related"> tags, a "## Network" section in /llms.txt, and
+# followed links in the prerendered body. Must run BEFORE add_llms_routes.
+#
+# The peer list is kept in one place (copied verbatim from the boilerplate) and
+# self-excludes by URL, so there is nothing app-specific to edit here — editing
+# it per repo is how twelve copies drift apart.
+network_directory.apply(BASE_URL)
+
+# /admin/control-board is an admin surface, not documentation. It is the one
+# registered page with no llms.txt prose, so it must be marked hidden BEFORE
+# add_llms_routes — otherwise it is the sole reason the missing-prose warning
+# below can never reach zero. mark_hidden also keeps it out of the sitemap and
+# out of /llms.txt, which matches the robots `disallowed_paths` above.
+mark_hidden("/admin/control-board")
+
 # Wire up /llms.txt, /<page>/llms.txt, /robots.txt, /sitemap.xml + bot
-# middleware. dash-improve-my-llms 2.0 auto-detects the active backend
+# middleware. dash-improve-my-llms auto-detects the active backend
 # (flask / fastapi / quart) and dispatches to the matching adapter, so we
 # no longer have to gate this on the backend. Per-page prose is registered
 # through lib.page_visibility.register_llms_doc (see pages/markdown.py) so the
 # control board's llms.txt switch can swap a page's body for a stub.
-add_llms_routes(app, LLMSConfig(warn_missing_llms_doc=False))
+#
+# warn_missing_llms_doc is deliberately TRUE. It was silenced while the home
+# page still lost its prose to the assign-semantics bug in 2.0; 2.2.0 made
+# register_page_metadata MERGE, so every page now keeps the llms_doc the
+# markdown loader gave it and the warning should stay at zero. If it starts
+# firing, a page has genuinely lost its prose — which is worth hearing about.
+add_llms_routes(app, LLMSConfig(warn_missing_llms_doc=True))
 
 # ----------------------------------------------------------------------------
 # 2plot.ai satellite analytics: /healthz for the hub's hourly health sweep,
 
@@ -15,6 +15,10 @@
 
 Env:
     DL2_EXTRA_SITE   donor site-packages directory
+    DL2_PIN_MODULES  comma-separated modules to import BEFORE the donor path is
+                     appended, so the target interpreter's copy wins. `dash` is
+                     always pinned; add others when the target holds the version
+                     under test (e.g. dash_improve_my_llms).
     DL2_SMOKE_ARGS   arguments to forward to smoke_test.py, newline-separated
 """
 import os
@@ -30,13 +34,36 @@
 _resolved = dash.__version__
 _origin = Path(dash.__file__).resolve()
 
+# Any other module whose TARGET version is the thing under test has to be
+# imported here too, for the same reason: once it is in sys.modules the donor
+# path appended below cannot shadow it.
+_pinned = []
+for _name in (os.environ.get("DL2_PIN_MODULES") or "").split(","):
+    _name = _name.strip()
+    if not _name:
+        continue
+    try:
+        _mod = __import__(_name)
+        _ver = getattr(_mod, "__version__", None)
+        if _ver is None:
+            import importlib.metadata as _md
+            try:
+                _ver = _md.version(_name.replace("_", "-"))
+            except Exception:
+                _ver = "?"
+        _pinned.append(f"{_name}=={_ver}")
+    except Exception as _exc:
+        _pinned.append(f"{_name} FAILED ({_exc})")
+
 # 2. Now lend the target the docs-site libraries it is missing.
 extra = os.environ.get("DL2_EXTRA_SITE")
 if extra and extra not in sys.path:
     sys.path.append(extra)
 
 # Report what actually got used, so a silently-wrong measurement is visible.
 print(f"[runner] dash {_resolved} from {_origin.parent.parent.parent.parent}")
+if _pinned:
+    print(f"[runner] pinned from target: {', '.join(_pinned)}")
 print(f"[runner] donor site-packages: {extra or '(none)'}")
 
 sys.argv = ["smoke_test.py"] + [