pipulate 2.74__tar.gz → 2.76__tar.gz

{pipulate-2.74 → pipulate-2.76}/.agents/skills/journal/references/index.md

@@ -1,8 +1,8 @@
 # The Pipulate journal, indexed
 
-> Auto-generated on 2026-10-01 by `scripts/articles/generate_ai_context.py` and
+> Auto-generated on 2026-10-02 by `scripts/articles/generate_ai_context.py` and
 > rewritten from scratch on every release. If this date looks stale, assume
-> the rest of the repo is newer than this map. 1508 entries indexed.
+> the rest of the repo is newer than this map. 1510 entries indexed.
 
 This repository holds the *machinery*. The *reasoning*, the running journal
 that explains why every piece exists, lives on a separate website and not in
@@ -27,6 +27,8 @@ The first 20 entries include full `index.md` URLs to establish
 the link pattern. All remaining entries are bare slugs. Reconstruct any full
 URL as: `https://mikelev.in/futureproof/{slug}/index.md`
 
+- [2026-10-02] [The Clear Cups Protocol: Auditing MCP Calls with Replayable Receipts](https://mikelev.in/futureproof/clear-cups-protocol-auditing-mcp-calls/index.md)
+- [2026-10-02] [The Door Table and the Moving Twig: Replayable Installs and the Stick Bug Secret](https://mikelev.in/futureproof/the-door-table-and-the-moving-twig/index.md)
 - [2026-10-01] [The Scrollback Rule: Engineering Full-Width Terminal Dividers for Replayable Logs](https://mikelev.in/futureproof/scrollback-rule-clear-x-receipts/index.md)
 - [2026-10-01] [The Prefix Ladder and the Unalias Guard: Replayable Shell Ergonomics in the Age of AI](https://mikelev.in/futureproof/prefix-ladders-and-the-unalias-guard/index.md)
 - [2026-09-30] [Forever-Commands and the Talk Toggle: Replayable CLI Habits in the Age of AI](https://mikelev.in/futureproof/forever-commands-and-the-talk-toggle/index.md)
@@ -45,13 +47,13 @@ URL as: `https://mikelev.in/futureproof/{slug}/index.md`
 - [2026-09-24] [Local Chrome Profile Inventory and Typed Matrix Resolution](https://mikelev.in/futureproof/local-chrome-profile-inventory-and-typed-matrix-resolution/index.md)
 - [2026-09-21] [Local-First Development and Resilience in the Age of AI](https://mikelev.in/futureproof/local-first-resilience-age-of-ai/index.md)
 - [2026-09-20] [The Letting-Go Moment: Building Vim Training Wheels for the Age of AI](https://mikelev.in/futureproof/vim-training-wheels-and-the-letting-go-moment/index.md)
-- [2026-09-20] [Disciplined Forgetting: Scaling AI Context Through a Two-Tier Memory Hierarchy](https://mikelev.in/futureproof/disciplined-forgetting-and-the-memory-hierarchy/index.md)
-- [2026-09-19] [Four Models, One Matchbook: Multi-Model Consensus in the Age of AI](https://mikelev.in/futureproof/four-models-one-matchbook-prompt-fanout/index.md)
 
 ## Compact slug index -- pattern: https://mikelev.in/futureproof/{slug}/index.md
 
 Format: `[date] [size] slug` -- fetch any entry as `https://mikelev.in/futureproof/{slug}/index.md`
 
+- [2026-09-20] [327k] disciplined-forgetting-and-the-memory-hierarchy
+- [2026-09-19] [175k] four-models-one-matchbook-prompt-fanout
 - [2026-09-19] [48k] dual-model-failover-independent-backoff
 - [2026-09-19] [193k] playing-pinball-in-the-age-of-ai-replayable-workflow-guide
 - [2026-09-19] [72k] color-blue-pipe-inspecting-code

{pipulate-2.74 → pipulate-2.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.74
+Version: 2.76
 Summary: The context compiler that helps you prompt well -- local-first, Nix-reproducible, replayable. The successor to AI SEO software.
 Author-email: Mike Levin <pipulate@gmail.com>
 License-Expression: AGPL-3.0-or-later

{pipulate-2.74 → pipulate-2.76}/__init__.py

@@ -12,7 +12,7 @@ Usage:
     pipulate
 """
 
-__version__ = "2.74"
+__version__ = "2.76"
 # APOSTROPHES RESTORED (2026-08-04). They were stripped as a workaround for
 # flake.nix's descMatch regex, whose character class excluded ' from the
 # CAPTURE and truncated the banner to "(So)". That regex was fixed in the same
@@ -23,7 +23,7 @@ __version__ = "2.74"
 # is not a property of the system; the regex is. Blast radius is one banner:
 # nothing but flake.nix reads this name -- version_sync.py syncs __version__
 # and __description__, never this. So'wI' chu' -- "engage the cloaking device."
-__version_description__ = "Doorways"
+__version_description__ = "Release Robustness"
 # SPDX expression, single source of truth, synced into pyproject.toml by
 # scripts/release/version_sync.py. "-or-later" (not bare AGPL-3.0, which is
 # deprecated SPDX) because the header below grants "any later version".

{pipulate-2.74 → pipulate-2.76}/imports/voice_synthesis.py

@@ -11,6 +11,8 @@ import os
 import wave
 import subprocess
 import tempfile
+import re
+import shutil
 import signal
 import sys
 from pathlib import Path
@@ -244,6 +246,136 @@ FIRST_CONTACT_INTRO = ("This workshop can read its steps aloud with Piper, "
 FIRST_CONTACT_LINE = ("This is Piper, reading a script. If you can hear this, "
                       "press Enter. Type n to keep it quiet.")
 
+# THE DOOR SPEAKS (2026-10-02, half two; half one is install.sh's door_row,
+# which writes .door into every install made through a door). first_contact()
+# reads .door and says that door's words. With no .door, as in a git clone,
+# nothing below is used and the card is the one above, unchanged. The
+# operator's five rulings of 2026-10-02, and where each one lives:
+#   1. the 60 MB line stays, printed only when a download happens: that is
+#      setup_voice_model's own line already, so nothing here repeats it;
+#   2. the welcome lines print either way and are spoken only when the
+#      voice is on: _show_welcome;
+#   3. the welcome shows once per install, even on a computer that answered
+#      the voice question in an earlier install: _mark_door_welcomed writes
+#      welcomed= into .door, and flake.nix's gate opens until it is there;
+#   4. "No local AI found yet." rather than "installed", because found is
+#      what a lookup knows: local_ai_line;
+#   5. the folder spelled a letter at a time in the spoken install message:
+#      flake.nix, TTS_DIR_SPELLED.
+DOOR_FILE = Path(__file__).resolve().parent.parent / ".door"
+DOOR_ASK_LINE = "If you can hear this, press Enter. Type n to keep it quiet."
+
+
+def read_door(path=None) -> Dict[str, Any]:
+    """The .door at the repo root as a dict, or {} when there is none.
+
+    One key=value per line, the way install.sh writes it. Lines starting
+    with # are skipped and an empty value counts as absent. welcome repeats,
+    so it is a list in file order; any other key keeps its last value.
+    """
+    door: Dict[str, Any] = {}
+    try:
+        text = Path(path or DOOR_FILE).read_text(encoding="utf-8")
+    except OSError:
+        return door
+    for line in text.splitlines():
+        if line.lstrip().startswith("#") or "=" not in line:
+            continue
+        key, value = (part.strip() for part in line.split("=", 1))
+        if not key or not value:
+            continue
+        if key == "welcome":
+            door.setdefault("welcome", []).append(value)
+        else:
+            door[key] = value
+    return door
+
+
+def local_ai_line() -> str:
+    """One sentence about local AI that claims only what this lookup found.
+
+    ATTRIBUTED-VOICE: detected names an act, so the act is here, and it is
+    only a lookup: an ollama on PATH, or the Ollama app in /Applications.
+    Nothing is started, asked or sent.
+    """
+    if shutil.which("ollama") or Path("/Applications/Ollama.app").exists():
+        return "Local AI detected but not used."
+    return "No local AI found yet."
+
+
+def door_card(door: Dict[str, Any], local_ai: str = "") -> tuple:
+    """(intro, ask lines, welcome lines) for first contact. Pure: no file, no sound.
+
+    A door with no workshop line, or no door at all, gets today's intro and
+    line exactly and no welcome. The ask lines print one per line and are
+    spoken as one.
+    """
+    workshop = door.get("workshop", "")
+    if not workshop:
+        return FIRST_CONTACT_INTRO, [FIRST_CONTACT_LINE], []
+    first = f"This is only text-to-speech. {local_ai}".strip()
+    return workshop, [first, DOOR_ASK_LINE], list(door.get("welcome", []))
+
+
+def _spoken(lines) -> str:
+    """A door's welcome lines as one spoken sentence; the screen keeps them as printed.
+
+    A line that ends with no punctuation gets a comma, so the voice pauses
+    where the screen breaks, and Q/A loses its slash. Read 2026-10-02 in a
+    sandbox through the espeak phonemizer inside piper-tts 1.6.0, the version
+    requirements.txt pins, and not heard on any computer here: Q/A comes out
+    as "queue slash uh", and QA as Q, A.
+    """
+    last = len(lines) - 1
+    text = " ".join(line if i == last or line[-1:] in ".!?,;:" else line + ","
+                    for i, line in enumerate(lines))
+    return re.sub(r"\b([A-Z])/([A-Z])\b", r"\1\2", text)
+
+
+def _mark_door_welcomed(path=None):
+    """Append welcomed=<date> to .door. Returns None, or the OSError."""
+    import datetime
+    target = Path(path or DOOR_FILE)
+    try:
+        text = target.read_text(encoding="utf-8")
+        lead = "" if not text or text.endswith("\n") else "\n"
+        with target.open("a", encoding="utf-8") as handle:
+            handle.write(lead + "# Written by first_contact() the day this door's welcome was shown. "
+                         "Delete the welcomed line to see it again.\n"
+                         "welcomed=" + datetime.date.today().isoformat() + "\n")
+    except OSError as exc:
+        return exc
+    return None
+
+
+def _show_welcome(door: Dict[str, Any], speak: bool) -> None:
+    """Print the door's welcome lines, speak them only if speak, then mark .door.
+
+    Nothing happens without a .door, or once welcomed= is in it. The voice
+    loads before the lines print, so a 60 MB line, when there is one, comes
+    first, and the words on screen arrive with the words spoken. A door with
+    no welcome lines is marked all the same, so the flake's gate shuts for it.
+    """
+    if not door or door.get("welcomed"):
+        return
+    lines = list(door.get("welcome", []))
+    voice = chip_voice_system if (speak and lines) else None
+    unheard = None
+    if voice is not None and not voice.ensure_voice():
+        unheard = voice.last_error or "the voice did not load"
+        voice = None
+    for line in lines:
+        print(line, flush=True)
+    if voice is not None:
+        result = voice.speak_text(_spoken(lines))
+        if not result.get("success") and not result.get("declined"):
+            unheard = result.get("error") or "nothing was heard"
+    if unheard:
+        print(f"(the welcome was printed but not heard: {str(unheard).splitlines()[0][:120]})")
+    error = _mark_door_welcomed()
+    if error is not None:
+        print(f"(could not mark the welcome as shown, so it shows again next time: {error})")
+
 
 def first_contact() -> str:
     """Ask by voice, once per machine, right before the first menu.
@@ -259,22 +391,42 @@ def first_contact() -> str:
     nothing, so the question returns next time. The one line spoken before any
     answer exists is the question itself, which is why synthesize_and_play
     takes ceremony=True from here and from nowhere else. Returns env,
-    recorded, unavailable, silent, interrupted, yes or no.
+    recorded, unavailable, silent, interrupted, yes, no or welcomed.
+
+    AMENDED 2026-10-02 (THE DOOR SPEAKS): an install made through a door has
+    a .door, and the card says that door's words (door_card, above): its
+    workshop line where the intro was, then "This is only text-to-speech."
+    with what a lookup found about local AI, then the same question. The
+    door's welcome lines follow the answer, printed always and spoken only
+    on yes. Where this computer answered the question in an earlier install,
+    flake.nix's gate still opens once for a .door with no welcomed= line:
+    nothing is asked, the workshop line and the welcome print, the welcome
+    is spoken if the recorded answer is yes, welcomed= is written, and the
+    return is welcomed.
     """
     if os.environ.get("PIPULATE_VOICE", "").strip():
         return "env"
-    if voice_consent() != "unset":
+    door = read_door()
+    recorded = voice_consent()
+    if recorded != "unset" and (not door or door.get("welcomed")):
         return "recorded"
     if not (sys.stdin.isatty() and sys.stdout.isatty()):
         return "unavailable"
     logger.setLevel(logging.CRITICAL)
+    if recorded != "unset":
+        if door.get("workshop"):
+            print(door["workshop"], flush=True)
+        _show_welcome(door, speak=recorded == "yes")
+        return "welcomed"
     voice = chip_voice_system
+    intro, ask_lines, _ = door_card(door, local_ai_line() if door.get("workshop") else "")
     try:
-        print(FIRST_CONTACT_INTRO, flush=True)
+        print(intro, flush=True)
         played = False
         if voice is not None and voice.ensure_voice():
-            print(FIRST_CONTACT_LINE, flush=True)
-            played = voice.synthesize_and_play(FIRST_CONTACT_LINE, ceremony=True)
+            for line in ask_lines:
+                print(line, flush=True)
+            played = voice.synthesize_and_play(" ".join(ask_lines), ceremony=True)
         if not played:
             reason = (voice.last_error if voice is not None else None) or "the voice did not load"
             reason = reason.splitlines()[0][:120]
@@ -282,6 +434,7 @@ def first_contact() -> str:
             print(f"The voice could not play here ({reason}), so it stays off. Type talk to try again.")
             if error is not None:
                 print(f"(could not record that, so this runs again next time: {error})")
+            _show_welcome(door, speak=False)
             return "silent"
         with open("/dev/tty", "r", encoding="utf-8") as tty:
             print("Enter or n: ", end="", flush=True)
@@ -303,6 +456,7 @@ def first_contact() -> str:
         print("Voice on. Type talk any time to turn it off.")
     else:
         print("Staying quiet. Type talk any time to turn the voice on.")
+    _show_welcome(door, speak=decision == "yes")
     return decision
 
 
@@ -850,7 +1004,8 @@ if __name__ == "__main__" and sys.argv[1:2] == ["talk"]:
     raise SystemExit(talk_command(sys.argv[2:]))
 if __name__ == "__main__" and sys.argv[1:2] == ["first"]:
     # flake.nix's runScript calls this once per machine, right before the first
-    # menu; it exits 0 whatever happened, so the menu always prints after it.
+    # menu, and once more in an install made through a door, for its welcome;
+    # it exits 0 whatever happened, so the menu always prints after it.
     try:
         first_contact()
     except Exception as _exc:

{pipulate-2.74 → pipulate-2.76}/pipulate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.74
+Version: 2.76
 Summary: The context compiler that helps you prompt well -- local-first, Nix-reproducible, replayable. The successor to AI SEO software.
 Author-email: Mike Levin <pipulate@gmail.com>
 License-Expression: AGPL-3.0-or-later

{pipulate-2.74 → pipulate-2.76}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "pipulate"
 # VERSION NOTE: Synced from pipulate/__init__.py.__version__ via python version_sync.py
-version = "2.74"
+version = "2.76"
 authors = [
   { name="Mike Levin", email="pipulate@gmail.com" },
 ]

{pipulate-2.74 → pipulate-2.76}/tools/scraper_tools.py

@@ -268,7 +268,13 @@ def _document_candidates(cdp_events: list, domain: str, final_url: str = "") ->
 
 
 def _capture_checkpoint(stdin=None, stdout=None, before_prompt=None) -> dict:
-    """Require an explicit CAPTURE token from the human's keyboard.
+    """Wait for Enter from the human's keyboard: the page has settled.
+
+    ENTER, NOT A WORD (2026-10-02, the operator's ruling). The fence used to
+    want the token CAPTURE, and one wrong letter ended the whole walk. Its
+    only job is a signal that the page has settled, and Enter is that signal;
+    Ctrl+C is the way out, as everywhere else. EOF still refuses, so a pipe
+    or a dead descriptor can never save a page.
 
     /DEV/TTY PREFERENCE (convicted 2026-07-29, public_walk stop 1): the
     inherited sys.stdin returned INSTANT EOF at the CAPTURE> prompt -- the
@@ -316,13 +322,25 @@ def _capture_checkpoint(stdin=None, stdout=None, before_prompt=None) -> dict:
                     output_stream.write(f"\n(checkpoint narration unavailable: {exc})\n")
             else:
                 output_stream.write(
-                    "\nWhen the page you want is ready, type CAPTURE and press Enter.\n"
+                    "\nWhen the page you want is ready, press Enter here.\n"
+                    "Ctrl+C stops without saving it.\n"
                 )
-            output_stream.write(
-                "Any other response aborts without capturing artifacts.\n"
-                "CAPTURE> "
-            )
+            # A CALLER'S HOOK OWNS EVERYTHING BEFORE THE PROMPT (2026-10-02):
+            # the default sentences print only when no hook was given, and
+            # the prompt itself says what Enter does.
+            output_stream.write("Press Enter to save the page. ")
             output_stream.flush()
+            # TYPE-AHEAD IS NOT THE SIGNAL (2026-10-02, read off a walk whose
+            # third page printed "Press Enter to save the page. Saved." on one
+            # line): an Enter pressed while the page was still loading waited
+            # in the terminal and answered this prompt the moment it appeared.
+            # Keys typed before the prompt are dropped, so only an Enter after
+            # the bell counts. A stream that is not a terminal is left alone.
+            try:
+                import termios
+                termios.tcflush(input_stream.fileno(), termios.TCIFLUSH)
+            except Exception:
+                pass
             response = input_stream.readline()
         except KeyboardInterrupt:
             return {
@@ -340,23 +358,9 @@ def _capture_checkpoint(stdin=None, stdout=None, before_prompt=None) -> dict:
                 "success": False,
                 "error": "interactive checkpoint reached EOF",
             }
-        # CASE-INSENSITIVE ON PURPOSE (banked 2026-08-01). The token's safety
-        # comes entirely from being IMPOSSIBLE TO PRODUCE BY ACCIDENT: no pipe,
-        # no EOF, no stray Enter, no dead descriptor and no automation emits
-        # these seven letters. Lowercase is exactly as impossible as uppercase,
-        # so the shift key was a tax with no revenue -- and it was collected at
-        # the newcomer's first handshake, where a refusal reads as "this thing
-        # is broken" rather than "you missed a key."
-        # DELIBERATELY NOT A RETRY LOOP. A retry gives the fence a SECOND STATE,
-        # and "nothing was written" stops being provable in one sentence. One
-        # read, one comparison, one branch, and every non-match returns before
-        # mkdir. A wrong answer still costs the ENTIRE ride, because a non-token
-        # answer is the human's ABORT, and abort must be as instant as consent.
-        if response.strip().upper() != "CAPTURE":
-            return {
-                "success": False,
-                "error": "interactive checkpoint was not confirmed",
-            }
+
+        # ANY LINE IS THE SIGNAL (2026-10-02): whatever was typed before Enter
+        # is ignored, so there is no wrong answer to end a walk on.
         return {"success": True}
     finally:
         if tty_handle is not None:
@@ -604,7 +608,9 @@ async def _selenium_capture(params: dict, checkpoint=None) -> dict:
             temp_profile = True
             logger.info(f"👻 Using temporary profile: {profile_path}")
         
-        if verbose:
+        # A guided walk's own step line says the browser is opening, so this
+        # prints only for unattended captures (2026-10-02, say a thing once).
+        if verbose and not interactive:
             print("Opening the browser; waiting for the page...", flush=True)
         music_proc = _start_scrape_music(verbose=verbose)
         logger.info(f"🚀 Initializing undetected-chromedriver (Headless: {headless})...")
@@ -645,10 +651,22 @@ async def _selenium_capture(params: dict, checkpoint=None) -> dict:
             else:
                 raise
 
+        # THE PAGE THE SERVER SENDS NOW (2026-10-02, read off a walk whose
+        # headers.json carried the Date and ETag of a fetch three hours older
+        # than the walk): a persistent profile keeps an HTTP cache, and a page
+        # sent without Cache-Control is reused from it, without asking the
+        # server, for a tenth of its age since Last-Modified. The walk saved
+        # that copy and called it the wire. The cache is off for every capture;
+        # cookies and sign-ins are kept elsewhere and are untouched.
+        try:
+            driver.execute_cdp_cmd("Network.enable", {})
+            driver.execute_cdp_cmd("Network.setCacheDisabled", {"cacheDisabled": True})
+        except Exception as exc:
+            logger.warning(f"⚠️ Could not turn off the browser cache; this page may come from it: {exc}")
         logger.info(f"Navigating to: {url}")
         driver.get(url)
 
-        # A human-guided ride already has the CAPTURE fence as its settle
+        # A human-guided ride already has the Enter fence as its settle
         # detector. The 20-second staleness wait exists for unattended sigil
         # scrapes, where a security interstitial may reload underneath us.
         if not interactive: