pipulate 2.73__tar.gz → 2.75__tar.gz

{pipulate-2.73 → pipulate-2.75}/.agents/skills/journal/references/index.md

@@ -1,8 +1,8 @@
 # The Pipulate journal, indexed
 
-> Auto-generated on 2026-09-29 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. 1505 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,11 @@ 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)
 - [2026-09-29] [Layered Reality and Operator Overloading: Reading the Physics of CPython in the Age of AI](https://mikelev.in/futureproof/layered-reality-operator-overloading-cpython/index.md)
 - [2026-09-29] [The Three-Door Installer: Named Prompts, Split DNS, and Verifiable Releases](https://mikelev.in/futureproof/the-three-door-installer-and-named-prompts/index.md)
 - [2026-09-29] [The Deed Is Named for the Door: Engineering Replayable QA Archives for AI](https://mikelev.in/futureproof/the-deed-is-named-for-the-door-qa-archive-zip/index.md)
@@ -42,16 +47,16 @@ 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)
-- [2026-09-19] [Dual-Model Failover: Engineering Independent Backoff Clocks for LLM APIs](https://mikelev.in/futureproof/dual-model-failover-independent-backoff/index.md)
-- [2026-09-19] [Playing Pinball in the Age of AI: A Replayable Workflow Guide](https://mikelev.in/futureproof/playing-pinball-in-the-age-of-ai-replayable-workflow-guide/index.md)
-- [2026-09-19] [The Color Blue and the Pipe: Inspecting Code Before Execution](https://mikelev.in/futureproof/color-blue-pipe-inspecting-code/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
 - [2026-09-19] [294k] edna-mode-rules-for-ai-workflows
 - [2026-09-18] [207k] the-one-door-threshold-replayable-ai-workflows
 - [2026-09-18] [292k] the-first-ten-minutes-reproducible-ai-workflows

{pipulate-2.73 → pipulate-2.75}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.73
+Version: 2.75
 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
@@ -86,7 +86,7 @@ Under both sits `flake.nix` with its `flake.lock`: the dependency inventory an S
 
 ## Quick Start: Be Running in 5 Minutes
 
-**Want to skip the philosophy and just see what this does? Paste this into your terminal:**
+**Want to skip the philosophy and just see what this does? Open the command line (on a Mac, the app called Terminal) and paste this:**
 
 ```bash
 curl -fsSL https://pipulate.com/install.sh | bash
@@ -113,8 +113,8 @@ These few commands:
 
 ### 4. Run It Again!
 
-1. You can just forcibly exit out of that Terminal it's running from.
-2. Open a new Terminal, and once again:
+1. You can just close the window it's running in.
+2. Open a new one, and once again:
 
 ```bash
 cd ~/pipulate
@@ -242,7 +242,7 @@ Pipulate is a **local-first, single-tenant desktop app framework** featuring AI-
                 │                                  │
                 ▼                                  ▼
     ┌─────────────────────────┐        ┌─────────────────────────┐  This is new.
-    │   📱 Native Window      │        │ 🖥️ Terminal Console     │    ,       O
+    │   📱 Native Window      │        │ 🖥️ The Command Line     │    ,       O
     │  ┌─────────────────┐    │        │ ┌─────────────────────┐ │    \\  .  O
     │  │  Web Browser    │    │        │ │ nix develop (./run) │ │    |\\/| o
     │  │  (Bundled)      │    │        │ │ Starting servers... │ │    / " '\
@@ -628,7 +628,7 @@ Type `jn` at the `(nix)` prompt, wait for the JupyterLab tab to open, then run t
 
 | Problem | Solution |
 |---------|----------|
-| `nix: command not found` | You didn't restart your terminal after Nix installation |
+| `nix: command not found` | Close the window and open a new one; Nix needs a fresh window after it installs |
 | Browser doesn't open automatically | Manually visit `http://localhost:5001` and `http://localhost:8888` |
 | `Permission denied` errors | Make sure you can write to `~/pipulate` directory |
 | Port conflicts | Kill processes on ports 5001/8888: `lsof -ti:5001 \| xargs kill -9` |
@@ -656,7 +656,7 @@ If you are a developer comfortable with tools like Homebrew and `pipx`, you can
 brew install pipx
 ```
 
-**Step 2: Install the Pipulate CLI**
+**Step 2: Install the `pipulate` command**
 
 Use `pipx` to install the `pipulate` command-line tool. This will not cause conflicts with your system Python.
 
@@ -871,7 +871,7 @@ Traditional development follows DRY principles, creating abstract, complex syste
 
 ## Developer Setup & Environment Notes
 
-**Nix Environment Activation:** Always run `nix develop` from the `~/pipulate` directory *before* running any project commands (`python server.py`, `pip install`, etc.) in a new terminal. This ensures you are using the correct dependencies defined in `flake.nix`.
+**Nix Environment Activation:** Always run `nix develop` from the `~/pipulate` directory *before* running any project commands (`python server.py`, `pip install`, etc.) in a new window. This ensures you are using the correct dependencies defined in `flake.nix`.
 
 **Interactive vs. Quiet Shell:**
 

{pipulate-2.73 → pipulate-2.75}/README.md

@@ -29,7 +29,7 @@ Under both sits `flake.nix` with its `flake.lock`: the dependency inventory an S
 
 ## Quick Start: Be Running in 5 Minutes
 
-**Want to skip the philosophy and just see what this does? Paste this into your terminal:**
+**Want to skip the philosophy and just see what this does? Open the command line (on a Mac, the app called Terminal) and paste this:**
 
 ```bash
 curl -fsSL https://pipulate.com/install.sh | bash
@@ -56,8 +56,8 @@ These few commands:
 
 ### 4. Run It Again!
 
-1. You can just forcibly exit out of that Terminal it's running from.
-2. Open a new Terminal, and once again:
+1. You can just close the window it's running in.
+2. Open a new one, and once again:
 
 ```bash
 cd ~/pipulate
@@ -185,7 +185,7 @@ Pipulate is a **local-first, single-tenant desktop app framework** featuring AI-
                 │                                  │
                 ▼                                  ▼
     ┌─────────────────────────┐        ┌─────────────────────────┐  This is new.
-    │   📱 Native Window      │        │ 🖥️ Terminal Console     │    ,       O
+    │   📱 Native Window      │        │ 🖥️ The Command Line     │    ,       O
     │  ┌─────────────────┐    │        │ ┌─────────────────────┐ │    \\  .  O
     │  │  Web Browser    │    │        │ │ nix develop (./run) │ │    |\\/| o
     │  │  (Bundled)      │    │        │ │ Starting servers... │ │    / " '\
@@ -571,7 +571,7 @@ Type `jn` at the `(nix)` prompt, wait for the JupyterLab tab to open, then run t
 
 | Problem | Solution |
 |---------|----------|
-| `nix: command not found` | You didn't restart your terminal after Nix installation |
+| `nix: command not found` | Close the window and open a new one; Nix needs a fresh window after it installs |
 | Browser doesn't open automatically | Manually visit `http://localhost:5001` and `http://localhost:8888` |
 | `Permission denied` errors | Make sure you can write to `~/pipulate` directory |
 | Port conflicts | Kill processes on ports 5001/8888: `lsof -ti:5001 \| xargs kill -9` |
@@ -599,7 +599,7 @@ If you are a developer comfortable with tools like Homebrew and `pipx`, you can
 brew install pipx
 ```
 
-**Step 2: Install the Pipulate CLI**
+**Step 2: Install the `pipulate` command**
 
 Use `pipx` to install the `pipulate` command-line tool. This will not cause conflicts with your system Python.
 
@@ -814,7 +814,7 @@ Traditional development follows DRY principles, creating abstract, complex syste
 
 ## Developer Setup & Environment Notes
 
-**Nix Environment Activation:** Always run `nix develop` from the `~/pipulate` directory *before* running any project commands (`python server.py`, `pip install`, etc.) in a new terminal. This ensures you are using the correct dependencies defined in `flake.nix`.
+**Nix Environment Activation:** Always run `nix develop` from the `~/pipulate` directory *before* running any project commands (`python server.py`, `pip install`, etc.) in a new window. This ensures you are using the correct dependencies defined in `flake.nix`.
 
 **Interactive vs. Quiet Shell:**
 

{pipulate-2.73 → pipulate-2.75}/__init__.py

@@ -12,7 +12,7 @@ Usage:
     pipulate
 """
 
-__version__ = "2.73"
+__version__ = "2.75"
 # 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.73"
 # 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__ = "Follow the White Rabbit"
+__version_description__ = "Refined Walk"
 # 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.73 → pipulate-2.75}/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
@@ -92,6 +94,13 @@ def _quiet_hub():
 # to fetch the voice and spend seconds before anyone had asked to speak or
 # been asked whether it may; that was also the import tax the tool roster
 # measured at ~3.8 s.
+# AMENDED 2026-10-01 (THE VOICE ASKS ONCE, OUT LOUD): first_contact() below,
+# run once per machine right before the first menu, prints what the voice is,
+# fetches the model with setup_voice_model's own one-line disclosure, and lets
+# the voice ask the question itself, because a voice nobody has heard is a
+# voice nobody can answer for (CONSENT CANNOT PRECEDE ITS OBJECT). The download
+# is disclosed, never asked, and still never at import. The walk's card asks
+# before it downloads, as before, and stays quiet once any answer is recorded.
 # ---------------------------------------------------------------------------
 VOICE_CONSENT_FILE = Path.home() / ".config" / "pipulate" / "voice"
 VOICE_CARD = (
@@ -120,7 +129,7 @@ def voice_consent() -> str:
     return "unset"
 
 
-def ask_voice_consent(later_hint: str = "voice", force: bool = False) -> str:
+def ask_voice_consent(later_hint: str = "talk", force: bool = False) -> str:
     """Ask on /dev/tty and record the answer. Returns 'yes', 'no' or 'unavailable'.
 
     Asks only when nothing is recorded, unless force is set (the `voice` word),
@@ -150,15 +159,307 @@ def ask_voice_consent(later_hint: str = "voice", force: bool = False) -> str:
     finally:
         tty.close()
     decision = "yes" if answer.strip().lower() in ("y", "yes") else "no"
+    error = _record_voice_answer(decision)
+    if error is not None:
+        print(f"(could not record the answer, so it will be asked again: {error})")
+    if decision == "no":
+        print(f"Staying quiet. To turn the voice on later, type: {later_hint}")
+    return decision
+
+TALK_ON_WORDS = ("on", "yes", "y", "1", "true")
+TALK_OFF_WORDS = ("off", "no", "n", "0", "false")
+
+
+def _record_voice_answer(decision: str):
+    """Write 'yes' or 'no' as the recorded answer. Returns None, or the OSError.
+
+    THE ONE WRITER (2026-09-30): the card and `talk` both record here, so the
+    format voice_consent() reads has one spelling, the word and a newline.
+    """
     try:
         VOICE_CONSENT_FILE.parent.mkdir(parents=True, exist_ok=True)
         VOICE_CONSENT_FILE.write_text(decision + "\n", encoding="utf-8")
     except OSError as exc:
-        print(f"(could not record the answer, so it will be asked again: {exc})")
-    if decision == "no":
-        print(f"Staying quiet. To turn the voice on later, type: {later_hint}")
+        return exc
+    return None
+
+
+def talk_command(args) -> int:
+    """`talk` flips narration; `talk on` and `talk off` set it. Returns an exit code.
+
+    THE TALK FLIP (2026-09-30). The recorded answer is one word, yes or no,
+    in VOICE_CONSENT_FILE, and voice_consent() reads it fresh on every call,
+    so a flip holds at the next spoken line in every process, a running
+    server included, with nothing restarted. Nothing recorded runs the card
+    first, whatever the argument: the card carries the download disclosure,
+    and talk writes only over an answer the card has recorded, so a flip to
+    on never downloads the voice undisclosed. PIPULATE_VOICE set to a word
+    voice_consent() reads outranks the file, so talk names it and writes
+    nothing. The state printed is read back through the barrier after the
+    write, never inferred from the request. Exit 0 when a state was
+    printed, 1 when nothing could be recorded, 2 for a word talk does not
+    know.
+    """
+    words = [arg.strip().lower() for arg in args]
+    if len(words) > 1 or (words and words[0] not in TALK_ON_WORDS + TALK_OFF_WORDS):
+        print("usage: talk [on|off]   (bare talk flips narration)")
+        return 2
+    want = None
+    if words:
+        want = "yes" if words[0] in TALK_ON_WORDS else "no"
+    raw = os.environ.get("PIPULATE_VOICE", "").strip()
+    if raw.lower() in ("0", "no", "off", "false", "1", "yes", "on", "true"):
+        state = "on" if voice_consent() == "yes" else "off"
+        print(f"narration: {state}  (PIPULATE_VOICE={raw!r} decides in this shell, so the "
+              "recorded answer was not read or changed; unset it to use talk)")
+        return 0
+    if raw:
+        print(f"(PIPULATE_VOICE={raw!r} is not a word the speaker reads; the recorded answer decides)")
+    error = None
+    recorded = voice_consent()
+    if recorded == "unset":
+        if ask_voice_consent(later_hint="talk") == "unavailable":
+            print("talk: nothing is recorded yet and there is no keyboard to ask on; type talk at the command line.")
+            return 1
+    else:
+        decision = want or ("no" if recorded == "yes" else "yes")
+        if decision != recorded:
+            error = _record_voice_answer(decision)
+            if error is not None:
+                print(f"talk: could not record the answer: {error}")
+    after = voice_consent()
+    if after == "unset":
+        print("talk: no answer is recorded, so narration stays off.")
+        return 1
+    state = "on" if after == "yes" else "off"
+    note = ", unchanged" if after == recorded else ""
+    print(f"narration: {state}{note}  (recorded in {VOICE_CONSENT_FILE})")
+    if after == "yes" and chip_voice_system is not None:
+        result = chip_voice_system.speak_text("This is Piper, reading a script. Narration is on.")
+        if not result.get("success"):
+            print(f"talk: nothing was heard: {result.get('error')}")
+    return 1 if error is not None else 0
+
+
+FIRST_CONTACT_INTRO = ("This workshop can read its steps aloud with Piper, "
+                       "a small voice that runs on this computer.")
+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.
+
+    THE VOICE ASKS ONCE, OUT LOUD (2026-10-01). flake.nix's runScript calls
+    this before the menu prints, only where no answer is recorded. One line
+    says what the voice is; setup_voice_model prints its own 60 MB line before
+    it fetches a model that is absent; then the voice speaks FIRST_CONTACT_LINE,
+    printed at the same moment, and one answer is read from the keyboard.
+    Enter keeps the voice and n turns it off. A voice that cannot load or play
+    records no and says why in one line, so the question does not repeat on
+    every entry and talk tries again later. Ctrl+C or an empty read records
+    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, 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"
+    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(intro, flush=True)
+        played = False
+        if voice is not None and voice.ensure_voice():
+            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]
+            error = _record_voice_answer("no")
+            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)
+            answer = tty.readline()
+    except KeyboardInterrupt:
+        print("\nNothing recorded; the question comes back next time.")
+        return "interrupted"
+    except OSError as exc:
+        print(f"\nNothing recorded ({exc}); the question comes back next time.")
+        return "interrupted"
+    if not answer:
+        print("\nNothing recorded; the question comes back next time.")
+        return "interrupted"
+    decision = "no" if answer.strip().lower().startswith("n") else "yes"
+    error = _record_voice_answer(decision)
+    if error is not None:
+        print(f"(could not record the answer, so it will be asked again: {error})")
+    if decision == "yes":
+        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
 
+
 class ChipVoiceSystem:
     """
     Voice synthesis system for Chip O'Theseus
@@ -233,8 +534,9 @@ class ChipVoiceSystem:
     def ensure_voice(self) -> bool:
         """Load the voice on first use, never at import. Returns readiness.
 
-        Reached only after voice_consent() read yes, so the download the card
-        announces happens after the answer and not before it.
+        Reached after voice_consent() read yes, or from first_contact() after
+        its printed line, where the download comes before the question so the
+        question can be heard.
         """
         if self.voice_ready:
             return True
@@ -286,7 +588,7 @@ class ChipVoiceSystem:
 
 
 
-    def synthesize_and_play(self, text: str) -> bool:
+    def synthesize_and_play(self, text: str, ceremony: bool = False) -> bool:
         """
         Synthesize text and play audio (Mike's tested approach)
         
@@ -296,9 +598,11 @@ class ChipVoiceSystem:
         Returns:
             bool: True if successful, False otherwise
         """
-        if voice_consent() != "yes":
+        if voice_consent() != "yes" and not ceremony:
             # THE BARRIER. Every path to sound passes here, and the answer is
             # read fresh each time, so a no recorded mid-session holds at once.
+            # ceremony=True has one caller, first_contact(), and one line: the
+            # question that asks whether the voice may speak, before any answer.
             self.last_error = "voice not allowed"
             logger.info("🎤 Voice not allowed; nothing spoken")
             return False
@@ -695,16 +999,28 @@ def test_memory_voice_integration():
         print("❌ No memories found to test")
         return False
 
+if __name__ == "__main__" and sys.argv[1:2] == ["talk"]:
+    # `talk`, the word the menu lists under walk: flip, or set with on/off.
+    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, 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:
+        print(f"(the voice question was skipped: {type(_exc).__name__}: {_exc})")
+    raise SystemExit(0)
 if __name__ == "__main__" and sys.argv[1:2] == ["ask"]:
-    # `voice`, the word the card names: re-ask and record, then speak one
+    # `voice`: re-ask the whole card and record the answer, then speak one
     # sentence on yes so the audio path is heard rather than assumed.
     _env = os.environ.get("PIPULATE_VOICE", "").strip()
     if _env:
         print(f"voice: PIPULATE_VOICE={_env!r} decides; unset it to be asked.")
         raise SystemExit(0)
-    _decision = ask_voice_consent(later_hint="voice", force=True)
+    _decision = ask_voice_consent(later_hint="talk", force=True)
     if _decision == "unavailable":
-        print("voice: no terminal to ask on; run this from a terminal.")
+        print("voice: no keyboard to ask on; type voice at the command line.")
         raise SystemExit(1)
     print(f"voice: {_decision}  (recorded in {VOICE_CONSENT_FILE})")
     if _decision == "yes" and chip_voice_system is not None:

{pipulate-2.73 → pipulate-2.75}/pipulate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.73
+Version: 2.75
 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
@@ -86,7 +86,7 @@ Under both sits `flake.nix` with its `flake.lock`: the dependency inventory an S
 
 ## Quick Start: Be Running in 5 Minutes
 
-**Want to skip the philosophy and just see what this does? Paste this into your terminal:**
+**Want to skip the philosophy and just see what this does? Open the command line (on a Mac, the app called Terminal) and paste this:**
 
 ```bash
 curl -fsSL https://pipulate.com/install.sh | bash
@@ -113,8 +113,8 @@ These few commands:
 
 ### 4. Run It Again!
 
-1. You can just forcibly exit out of that Terminal it's running from.
-2. Open a new Terminal, and once again:
+1. You can just close the window it's running in.
+2. Open a new one, and once again:
 
 ```bash
 cd ~/pipulate
@@ -242,7 +242,7 @@ Pipulate is a **local-first, single-tenant desktop app framework** featuring AI-
                 │                                  │
                 ▼                                  ▼
     ┌─────────────────────────┐        ┌─────────────────────────┐  This is new.
-    │   📱 Native Window      │        │ 🖥️ Terminal Console     │    ,       O
+    │   📱 Native Window      │        │ 🖥️ The Command Line     │    ,       O
     │  ┌─────────────────┐    │        │ ┌─────────────────────┐ │    \\  .  O
     │  │  Web Browser    │    │        │ │ nix develop (./run) │ │    |\\/| o
     │  │  (Bundled)      │    │        │ │ Starting servers... │ │    / " '\
@@ -628,7 +628,7 @@ Type `jn` at the `(nix)` prompt, wait for the JupyterLab tab to open, then run t
 
 | Problem | Solution |
 |---------|----------|
-| `nix: command not found` | You didn't restart your terminal after Nix installation |
+| `nix: command not found` | Close the window and open a new one; Nix needs a fresh window after it installs |
 | Browser doesn't open automatically | Manually visit `http://localhost:5001` and `http://localhost:8888` |
 | `Permission denied` errors | Make sure you can write to `~/pipulate` directory |
 | Port conflicts | Kill processes on ports 5001/8888: `lsof -ti:5001 \| xargs kill -9` |
@@ -656,7 +656,7 @@ If you are a developer comfortable with tools like Homebrew and `pipx`, you can
 brew install pipx
 ```
 
-**Step 2: Install the Pipulate CLI**
+**Step 2: Install the `pipulate` command**
 
 Use `pipx` to install the `pipulate` command-line tool. This will not cause conflicts with your system Python.
 
@@ -871,7 +871,7 @@ Traditional development follows DRY principles, creating abstract, complex syste
 
 ## Developer Setup & Environment Notes
 
-**Nix Environment Activation:** Always run `nix develop` from the `~/pipulate` directory *before* running any project commands (`python server.py`, `pip install`, etc.) in a new terminal. This ensures you are using the correct dependencies defined in `flake.nix`.
+**Nix Environment Activation:** Always run `nix develop` from the `~/pipulate` directory *before* running any project commands (`python server.py`, `pip install`, etc.) in a new window. This ensures you are using the correct dependencies defined in `flake.nix`.
 
 **Interactive vs. Quiet Shell:**
 

{pipulate-2.73 → pipulate-2.75}/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.73"
+version = "2.75"
 authors = [
   { name="Mike Levin", email="pipulate@gmail.com" },
 ]

{pipulate-2.73 → pipulate-2.75}/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: