pipulate 2.66__tar.gz → 2.68__tar.gz

{pipulate-2.66 → pipulate-2.68}/.agents/skills/journal/references/index.md

@@ -2,7 +2,7 @@
 
 > Auto-generated on 2026-09-28 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. 1499 entries indexed.
+> the rest of the repo is newer than this map. 1500 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,7 @@ 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-09-28] [AGENTS.md and Agent Skills: Refactoring Pipulate for a Checkable PyPI Release](https://mikelev.in/futureproof/agents-md-agent-skills-pypi-receipts/index.md)
 - [2026-09-28] [The Cost of Forgetting: The Epistemic Price List and the Art of the Lean Codebase](https://mikelev.in/futureproof/the-forgetting-kata-and-the-epistemic-price-list/index.md)
 - [2026-09-28] [Pinball, Pachinko, and the Art of Replayable AI Workflows](https://mikelev.in/futureproof/pinball-pachinko-replayable-ai-workflows/index.md)
 - [2026-09-28] [The Three-Folder Boundary: Ergonomic Workspaces and the Blank Stare in the Age of AI](https://mikelev.in/futureproof/three-folder-boundary-and-the-blank-stare/index.md)
@@ -46,12 +47,12 @@ URL as: `https://mikelev.in/futureproof/{slug}/index.md`
 - [2026-09-18] [The First Ten Minutes: Engineering Reproducible AI Workflows in the Age of AI](https://mikelev.in/futureproof/the-first-ten-minutes-reproducible-ai-workflows/index.md)
 - [2026-09-17] [The Retrieval Cue: Memory Consolidation and Selective Hydration in the Age of AI](https://mikelev.in/futureproof/retrieval-cue-memory-consolidation-selective-hydration/index.md)
 - [2026-09-17] [The Voice Asks First: Engineering Verifiable Consent and Silent Defaults](https://mikelev.in/futureproof/the-voice-asks-first-verifiable-consent/index.md)
-- [2026-09-17] [The Workbench Pin and the Help Screen Census: Verifiable Receipts in the Age of AI](https://mikelev.in/futureproof/the-workbench-pin-and-the-help-screen-census/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-17] [122k] the-workbench-pin-and-the-help-screen-census
 - [2026-09-17] [54k] useless-machine-oauth-replayable-workflows
 - [2026-09-17] [89k] escaped-monopolies-and-replayable-receipts
 - [2026-09-17] [149k] ratcheting-wins-in-the-age-of-ai

pipulate-2.68/.agents/skills/pipulate/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: pipulate
+description: Installing Pipulate, the local-first context compiler, on a machine that does not have it, without taking the keyboard away from the person who owns the machine. Use when someone asks to install, start, stop, reset or remove Pipulate, or asks what the one-line installer will do before running it. Read the installer before running it, run the copy you read, and keep every step a command the human types.
+---
+
+# pipulate: install it without giving up the keyboard
+
+The skill you keep is the one you can still use when the wrapper is gone.
+Every step below is a command the human types and reads before it runs, so
+the person doing it learns what their machine is doing instead of watching
+a spinner.
+
+Two doors serve one installer. `https://pipulate.com/install.sh` lands the
+workshop in `~/pipulate`; `https://npvg.org` serves the same script to `curl`
+with its default folder stamped to `~/npvg` (a browser at that address gets a
+web page instead). The lines below use the npvg door; swap the URL and the
+folder name for the other.
+
+## 1. Look before you run
+
+~~~bash
+curl -fsSL https://npvg.org | less
+~~~
+
+Nothing runs. What appears is the installer as text: a comment block that
+explains the design (a ZIP download and a read-only deploy key, then
+`nix develop`, which turns the folder into a git checkout that updates
+itself), then `main() {`, the whole body inside that function, and a last
+line that calls it. `j` moves down, `k` up, `/nix` searches, `q` quits. The
+function wrapper is deliberate: a download cut off partway cannot run half
+an install.
+
+## 2. Save it, read it, run the copy you read
+
+~~~bash
+curl -fsSL https://npvg.org -o install.sh
+less install.sh
+bash install.sh
+~~~
+
+The file read is the file run, byte for byte; that is the one thing the pipe
+form skips. `bash install.sh myname` puts the workshop in `~/myname` and
+names the app after it; with no argument the folder is the door's default.
+
+## 3. The one line, once you have read it
+
+~~~bash
+curl -fsSL https://npvg.org | bash
+~~~
+
+What it does, in order (the script's own sequence; read it there):
+
+1. Refuses to run under a shell that is not bash, prints one line naming the
+   folder and the command that removes it, and stops if `curl` or `unzip`
+   is missing.
+2. If `nix` is missing, runs the Determinate Systems Nix installer and then
+   STOPS: close this terminal, open a new one, run the line it prints. That
+   stop is expected, not a failure. The line it prints goes through
+   pipulate.com and, from the npvg door, carries the folder as an argument
+   (`bash -s npvg`), so the app is then named after the folder; the plain
+   npvg line names no folder and leaves the app named Pipulate.
+3. Refuses if the target folder already exists. It never overwrites.
+4. Downloads the repository as a ZIP from GitHub and unpacks it into the
+   folder.
+5. Fetches a ROT13-encoded deploy key into `.ssh/rot` inside the folder. It
+   is pull-only: it lets the folder fetch updates without a GitHub account.
+6. Writes a `run` file the flake deletes on its first entry (a leftover the
+   repo has marked for removal), prints the come-back line, and hands off
+   to `nix develop -L`. The first entry can take several minutes while
+   packages download; the installer's last line says so, and a long wait
+   after it is that download.
+
+Inside `nix develop` the flake finishes the job: it clones the repository
+over the ZIP so the folder becomes a real git checkout (the pre-transform
+files are backed up to a temp directory and the path is printed), creates
+`.venv`, installs the Python packages with `uv`, and prints one line of
+readings (Nix version, Python version, Pipulate version, the folder)
+followed by a short list of words to type.
+
+## 4. Three ways in, after that
+
+- `cd ~/npvg && nix develop` is the everyday door. On a terminal it stops at
+  the short command list and a `(nix)` prompt; nothing has started. Every
+  entry also pulls the latest commit, fast-forward only; a local change
+  pauses the update and says so.
+- `jn` starts JupyterLab at `http://localhost:8888` with the Onboarding
+  notebook open and the app at `http://localhost:5001`, and prints the
+  banner. Finishing that notebook is what unlocks the app tab on later
+  starts. Ctrl+C stops the app; `pu` starts it again and is also the
+  restart word. JupyterLab runs in a `tmux` session named `jupyter` and
+  keeps running after the shell is left.
+- `walk` is the first word to type: a guided walk over three public pages
+  that teaches the loop. On its first run it shows a card asking whether it
+  may read aloud and records the answer; it stays silent until that answer
+  is yes, and `voice` changes it later. `menu` reprints the short list,
+  `all` the long one, `about` the workspace tree, the three tiers and how
+  to check what an AI said against what it was handed. `exit` leaves the
+  shell.
+
+## 5. What stays on the machine, and what leaves it
+
+Stays: everything runs on localhost, ports 5001 and 8888. The folder holds
+the code, `.venv`, the SQLite databases under `data/`, and the person's own
+notebooks and files under `Workshop/personal/`, which git never tracks.
+Outside the folder, three homes: `~/.config/pipulate/` (settings,
+credentials the person adds by hand, the one-line answer to the voice
+question), `~/.local/share/pipulate/` (two sound files) and
+`~/.local/state/pipulate/` (the compile's own state: `context.txt` when
+`PIPULATE_ADHOC_FILE` points there, and what a move sets aside under
+`stale/`). The browser lanes may leave a driver cache under `~/.cache`; that
+path was not read for this skill. The voice model lands inside the folder,
+under `assets/piper_models/` (gitignored, so removing the folder removes
+it), fetched on the first spoken line after the yes at the voice card.
+
+Leaves, as the installer and the flake spell it: GitHub (the ZIP, then the
+clone, then a `git pull` on every `nix develop`); pipulate.com (the deploy
+key, from either door);
+install.determinate.systems, only when Nix is missing; the Nix binary cache
+and PyPI, for packages; Hugging Face once, for a small voice model, and only
+after the person has answered yes at the voice card. No connector calls any
+service until the person warms a credential for it themselves.
+
+Two things it touches outside the folder, worth saying out loud: if
+`~/.ssh/id_rsa` does not exist, the flake writes the decoded deploy key
+there and adds a `Host github.com` block to `~/.ssh/config`; an existing key
+is left alone. And Nix is a system-level install with its own uninstaller;
+removing the folder does not remove Nix.
+
+## 6. Stop, reset, remove
+
+- Stop the app: Ctrl+C in the window running it. Stop JupyterLab:
+  `tmux kill-session -t jupyter`. Leave the shell: `exit`.
+- Reset the Python environment and nothing else: `rm -rf ~/npvg/.venv`, then
+  `nix develop` rebuilds it.
+- Remove: `rm -rf ~/npvg` (the installer prints this line itself), then
+  `rm -rf ~/.config/pipulate ~/.local/share/pipulate ~/.local/state/pipulate`
+  for the three homes outside the folder. If the flake wrote `~/.ssh/id_rsa`
+  (the person had
+  none before), that key and the `github.com` block in `~/.ssh/config` are
+  theirs to remove. Nix stays unless its own uninstaller is run.
+
+## What this skill does not do
+
+- It never runs the installer on the person's behalf; it hands them the
+  line and reads the script with them.
+- It never edits files in the workshop by hand. Edits go through the
+  protocol `AGENTS.md` names: SEARCH/REPLACE blocks, matched exactly once,
+  applied by `apply.py`, which checks Python, Nix and JSON syntax before it
+  writes. That protocol is always-on in `AGENTS.md` rather than a skill,
+  because a skill loads on demand and the protocol is every turn.
+- It was read against four sources: the installer's own text, the door page
+  a browser gets at npvg.org, README's Quick Start and AUDIT.md; where the
+  installer's text and a page disagreed, the installer's text won.

{pipulate-2.66 → pipulate-2.68}/AGENTS.md

@@ -1,13 +1,25 @@
 # AGENTS.md — Pipulate
 
-This repo predates the AGENTS.md / Agent Skills / OKF conventions and complies
-with them by *pointing*, not duplicating. The sources of truth here are
-executable, so this file is a signpost. Do not add sibling status .md files;
-anything written here that duplicates code will drift and is a bug.
+This repository carries Agent Skills under https://agentskills.io/specification
+(`.agents/skills/*/SKILL.md`, a YAML head over a Markdown body, loaded on
+demand), with this file as the nearest-ancestor signpost that points at
+executable truth instead of duplicating it. Every tool call taught here runs
+on localhost under the POSIX conventions of a command, stdin, stdout and an
+exit code, so that its output lands in the sealed compile (`foo.zip`) as a
+receipt; a cloud-side tool call that cannot be reconstructed here is
+non-reproducible, non-portable, cannot be compiled into a cartridge, and is
+out of scope by that rule, not by taste.
+
+This repo predates those conventions and complies with them by *pointing*,
+not duplicating. Do not add sibling status .md files; anything written here
+that duplicates code will drift and is a bug.
 
 ## Setup (the executable version of "Dev environment tips")
 
-- `nix develop` — full environment (server + JupyterLab). See `flake.nix`.
+- `nix develop` — the full environment. On a terminal it stops at a short
+  list of words and a `(nix)` prompt with nothing started; `jn` starts
+  JupyterLab and the server. Without a terminal it starts the app, so an
+  agent takes the quiet shell below. See `flake.nix`.
 - `nix develop .#quiet` — minimal shell for agents and scripting.
 - Python lives in `.venv/`; invoke as `.venv/bin/python`.
 
@@ -36,7 +48,7 @@ run since the sentinels landed.
 
 - Discover: `.venv/bin/python cli.py mcp-discover`
 - Execute:  `.venv/bin/python cli.py call <tool_name> --json-args '{...}'`
-- Skills (Agent Skills spec, https://agentskills.io/specification): `.agents/skills/*/SKILL.md`, at the repo root beside this file
+- Skills (Agent Skills spec, https://agentskills.io/specification): `.agents/skills/*/SKILL.md`, at the repo root beside this file; `.claude/skills` is a symlink to the same folder, so Claude Code's project-skills path offers the same skills
 - The reasoning behind any piece of the machinery: the `journal` skill, whose `references/index.md` lists every journal entry newest first with a fetchable URL
 
 ## Context (how this repo talks to AI)

{pipulate-2.66 → pipulate-2.68}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.66
+Version: 2.68
 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
@@ -101,7 +101,7 @@ cd ~/pipulate && nix develop
 
 **What you get:** A local web app at `http://localhost:5001` with step-by-step workflows, integrated AI chat, and a JupyterLab instance at `http://localhost:8888`. No cloud required.
 
-**Success looks like:** A one-line environment reading, then a three-door menu. Press `1` to start JupyterLab and the app server (`2` gives you a bare shell with nothing running; `3` starts both but opens the Pipulate app tab instead). The JupyterLab tab opens in your browser; run the Onboarding notebook top-to-bottom to unlock the Pipulate app (it opens automatically on future launches).
+**Success looks like:** A one-line environment reading, then a short list of words and a `(nix)` prompt. Nothing has started yet. Type `walk` for the guided tour, or `jn` to start JupyterLab and the app server; the JupyterLab tab opens in your browser with the Onboarding notebook, and running it top-to-bottom unlocks the Pipulate app (it opens automatically on future launches).
 
 These few commands:
 - ✅ Updates to the latest version automatically
@@ -614,14 +614,13 @@ cd ~/TestProject
 nix develop
 ```
 
-Press `1` at the three-door menu, wait for the JupyterLab tab to open, then run the Onboarding notebook to unlock the Pipulate app.
+Type `jn` at the `(nix)` prompt, wait for the JupyterLab tab to open, then run the Onboarding notebook to unlock the Pipulate app.
 
-**Automating past the boot menu:** `nix develop` ends at a three-door prompt — start with the JupyterLab tab, drop to the shell, or start with the Pipulate tab in front. It fails open, so anything without a terminal (CI, a provisioning script, an SSH session with no tty) starts the app and never sees the prompt. Two environment variables cover the cases that do:
+**Automating past the command list:** on a terminal, `nix develop` ends at a short list of words and a `(nix)` prompt with nothing started; `scripts/boot_menu.py` prints the list, speaks through its exit code and reads no keys. It fails open, so anything without a terminal (CI, a provisioning script, an SSH session with no tty) starts the app and never sees the list. One environment variable covers a terminal that should do the same:
 
 | Variable | Effect |
 |----------|--------|
-| `PIPULATE_BOOT_MENU=0` | Skip the prompt entirely and start the app, e.g. `PIPULATE_BOOT_MENU=0 nix develop`. For an unattended terminal that would otherwise wait for a keypress that never comes. |
-| `PIPULATE_BOOT_MENU_TIMEOUT=10` | Keep the prompt, but start the app after N seconds if nobody chooses. Off by default — with a human provably present, the prompt waits indefinitely rather than starting something they didn't ask for. |
+| `PIPULATE_BOOT_MENU=0` | Skip the list and start the app, e.g. `PIPULATE_BOOT_MENU=0 nix develop`. For an unattended terminal (one a script types into) that should behave as if it had no tty. |
 
 ### 🚨 Installation Troubleshooting
 

{pipulate-2.66 → pipulate-2.68}/README.md

@@ -44,7 +44,7 @@ cd ~/pipulate && nix develop
 
 **What you get:** A local web app at `http://localhost:5001` with step-by-step workflows, integrated AI chat, and a JupyterLab instance at `http://localhost:8888`. No cloud required.
 
-**Success looks like:** A one-line environment reading, then a three-door menu. Press `1` to start JupyterLab and the app server (`2` gives you a bare shell with nothing running; `3` starts both but opens the Pipulate app tab instead). The JupyterLab tab opens in your browser; run the Onboarding notebook top-to-bottom to unlock the Pipulate app (it opens automatically on future launches).
+**Success looks like:** A one-line environment reading, then a short list of words and a `(nix)` prompt. Nothing has started yet. Type `walk` for the guided tour, or `jn` to start JupyterLab and the app server; the JupyterLab tab opens in your browser with the Onboarding notebook, and running it top-to-bottom unlocks the Pipulate app (it opens automatically on future launches).
 
 These few commands:
 - ✅ Updates to the latest version automatically
@@ -557,14 +557,13 @@ cd ~/TestProject
 nix develop
 ```
 
-Press `1` at the three-door menu, wait for the JupyterLab tab to open, then run the Onboarding notebook to unlock the Pipulate app.
+Type `jn` at the `(nix)` prompt, wait for the JupyterLab tab to open, then run the Onboarding notebook to unlock the Pipulate app.
 
-**Automating past the boot menu:** `nix develop` ends at a three-door prompt — start with the JupyterLab tab, drop to the shell, or start with the Pipulate tab in front. It fails open, so anything without a terminal (CI, a provisioning script, an SSH session with no tty) starts the app and never sees the prompt. Two environment variables cover the cases that do:
+**Automating past the command list:** on a terminal, `nix develop` ends at a short list of words and a `(nix)` prompt with nothing started; `scripts/boot_menu.py` prints the list, speaks through its exit code and reads no keys. It fails open, so anything without a terminal (CI, a provisioning script, an SSH session with no tty) starts the app and never sees the list. One environment variable covers a terminal that should do the same:
 
 | Variable | Effect |
 |----------|--------|
-| `PIPULATE_BOOT_MENU=0` | Skip the prompt entirely and start the app, e.g. `PIPULATE_BOOT_MENU=0 nix develop`. For an unattended terminal that would otherwise wait for a keypress that never comes. |
-| `PIPULATE_BOOT_MENU_TIMEOUT=10` | Keep the prompt, but start the app after N seconds if nobody chooses. Off by default — with a human provably present, the prompt waits indefinitely rather than starting something they didn't ask for. |
+| `PIPULATE_BOOT_MENU=0` | Skip the list and start the app, e.g. `PIPULATE_BOOT_MENU=0 nix develop`. For an unattended terminal (one a script types into) that should behave as if it had no tty. |
 
 ### 🚨 Installation Troubleshooting
 

{pipulate-2.66 → pipulate-2.68}/__init__.py

@@ -12,7 +12,7 @@ Usage:
     pipulate
 """
 
-__version__ = "2.66"
+__version__ = "2.68"
 # 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.66"
 # 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__ = "Convention Convention"
+__version_description__ = "Pipulate Claude Skill Banked"
 # 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.66 → pipulate-2.68}/pipulate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipulate
-Version: 2.66
+Version: 2.68
 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
@@ -101,7 +101,7 @@ cd ~/pipulate && nix develop
 
 **What you get:** A local web app at `http://localhost:5001` with step-by-step workflows, integrated AI chat, and a JupyterLab instance at `http://localhost:8888`. No cloud required.
 
-**Success looks like:** A one-line environment reading, then a three-door menu. Press `1` to start JupyterLab and the app server (`2` gives you a bare shell with nothing running; `3` starts both but opens the Pipulate app tab instead). The JupyterLab tab opens in your browser; run the Onboarding notebook top-to-bottom to unlock the Pipulate app (it opens automatically on future launches).
+**Success looks like:** A one-line environment reading, then a short list of words and a `(nix)` prompt. Nothing has started yet. Type `walk` for the guided tour, or `jn` to start JupyterLab and the app server; the JupyterLab tab opens in your browser with the Onboarding notebook, and running it top-to-bottom unlocks the Pipulate app (it opens automatically on future launches).
 
 These few commands:
 - ✅ Updates to the latest version automatically
@@ -614,14 +614,13 @@ cd ~/TestProject
 nix develop
 ```
 
-Press `1` at the three-door menu, wait for the JupyterLab tab to open, then run the Onboarding notebook to unlock the Pipulate app.
+Type `jn` at the `(nix)` prompt, wait for the JupyterLab tab to open, then run the Onboarding notebook to unlock the Pipulate app.
 
-**Automating past the boot menu:** `nix develop` ends at a three-door prompt — start with the JupyterLab tab, drop to the shell, or start with the Pipulate tab in front. It fails open, so anything without a terminal (CI, a provisioning script, an SSH session with no tty) starts the app and never sees the prompt. Two environment variables cover the cases that do:
+**Automating past the command list:** on a terminal, `nix develop` ends at a short list of words and a `(nix)` prompt with nothing started; `scripts/boot_menu.py` prints the list, speaks through its exit code and reads no keys. It fails open, so anything without a terminal (CI, a provisioning script, an SSH session with no tty) starts the app and never sees the list. One environment variable covers a terminal that should do the same:
 
 | Variable | Effect |
 |----------|--------|
-| `PIPULATE_BOOT_MENU=0` | Skip the prompt entirely and start the app, e.g. `PIPULATE_BOOT_MENU=0 nix develop`. For an unattended terminal that would otherwise wait for a keypress that never comes. |
-| `PIPULATE_BOOT_MENU_TIMEOUT=10` | Keep the prompt, but start the app after N seconds if nobody chooses. Off by default — with a human provably present, the prompt waits indefinitely rather than starting something they didn't ask for. |
+| `PIPULATE_BOOT_MENU=0` | Skip the list and start the app, e.g. `PIPULATE_BOOT_MENU=0 nix develop`. For an unattended terminal (one a script types into) that should behave as if it had no tty. |
 
 ### 🚨 Installation Troubleshooting
 

{pipulate-2.66 → pipulate-2.68}/pipulate.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ server.py
 .agents/skills/hello-workflow/SKILL.md
 .agents/skills/journal/SKILL.md
 .agents/skills/journal/references/index.md
+.agents/skills/pipulate/SKILL.md
 .agents/skills/roles/SKILL.md
 .agents/skills/sheets-readonly/SKILL.md
 apps/010_introduction.py

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