Walk, Plan, and Run: Designing Replayable AI Workflows
Setting the Stage: Context for the Curious Book Reader
Building resilient local automation means moving away from fragile interfaces and toward simple, inspectable command-line loops. This chapter explores how an authoring workflow reduces friction by separating tutorials from personal itineraries, providing a clean foundation for verifiable testing in the Age of AI.
TL;DR: Pipulate now has a three-command local workflow for browser evidence collection: walk teaches the bundled example, plan edits a private reusable itinerary, and walk plan runs that itinerary. Trail files are now named and generated as JSON rather than presenting JSON syntax behind a YAML filename. Existing YAML trails remain readable for compatibility. The private plan lives outside the repository, and an existing plan.yaml is migrated to plan.json rather than overwritten. A real custom run successfully captured its first page before the operator deliberately interrupted the second stop.
Technical Journal Entry Begins
🔗 Verified Pipulate Commits:
MikeLev.in: Alright, I’m going to be in the office today and need to have something to show by a 10:00 AM team call. I have the basic instrumentation now for walks, at least the main default one that came together on the last few articles. Let’s rapidly smooth out what’s dangling from the previous article to do whatever’s left insofar as the “must have” of the main default walk.
Closing the Loop on the Final Polish
Then I need to start using it for making determinations about the SpeedWorkers
mini-rules of site configuration settings in Botify — that’s the ultimate goal
here which is actually more a case of the short choppy Unix-like commands such
as jira and slack, the slack-of-which I’m still waiting for the IT/Security
group to green-light so it has its own assigned OAuth-login to run as but we
will factor out the need to hit slack directly for now.
This is all about leaping over blockers and rabbithole pitfalls as we navigate a tiny handful of remaining 80/20-rules so that we have something that we can repeatedly demonstrate in a way that instills that “Ah-HA!” moment. Scratch everybody’s itch at having to Q/A LLM-results perfectly and have resistance drop. People being able to actually use the archives by just dropping them into Claude will make worlds of difference so this morning is about strategic selective remaining projects.
But one of those remaining is to slam out the “must have” remaining danglings from the last article so let’s just jump right into that.
So I go to the last article and grab this from the “Next article” section and
slap it into the bottom of adhoc.txt and plunge right in. Let’s knock this one
out quick and get on with it, maybe with time to use the Botify MCP command by
hand which is sure to be a big hit.
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
imports/voice_synthesis.py
tools/scraper_tools.py
prompt_foo.py
assets/trails/public_walk.yaml
ChatGPT 6: One small cut: make the completed introductory walk say goodbye.
Your carried-forward THE WALK SAYS GOODBYE seed names exactly this destination: one short Piper closing after the results, using the existing _narrate() helper, without another question or lesson. It explicitly leaves shared voice changes, wait audio, renderer repair, menu changes, and release work outside this ride.
The current completion path confirms the gap: it finishes the archive, attempts the checked handoff, prints the save/copy guidance, and returns without narrating a closing. Practice and failed captures return earlier. That gives us a narrow insertion point without touching their behavior.
The important distinction is completion is not delivery. _decant_to_clipboard() can return True even after the preview-file write fails; the clipboard helper reports its own outcome separately. Consequently, the closing must direct the person to those messages—not announce that something was saved or copied. A withheld handoff gets a different closing.
I tested the attached source and the proposed patch in an isolated copy. Across eleven mocked scenarios, the patched version made one closing call for completed introductory captures—including blocked checks, a redirected destination, failed save/copy attempts, and unavailable or failing voice—and none for partial, practice, or custom runs. Existing result messages remained visible. These are control-flow tests, not evidence that Piper was audible or that your real clipboard received anything. The full isolated fixture source records those tests.
1. PROBES
Run this from the repository root before applying the patch. It parses the actual rider source and exercises its completion block in memory, with handoff and narration stubbed. It does not launch a browser, invoke Piper, write files, or touch the clipboard.
In the printed order, expect closing counts 0, 0, 0, 0 before and 1, 1, 0, 0 after. handoff=True represents the existing return value, not successful delivery. The assertions also check that custom calls receive no closing and that the wording does not claim a save or copy.
.venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
2. NEXT CONTEXT
Use this for the next compile. The probe is identical to the hand-run command, with only the leading ! added.
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
imports/voice_synthesis.py
tools/scraper_tools.py
prompt_foo.py
assets/trails/public_walk.yaml
! .venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
3. PATCHES
One file, one uniquely matching source line, ten added lines. The closing sits after the existing results and remains inside the completed-captures branch. Passing the existing disclosed value preserves the narration helper’s disclosure state.
Target: scripts/mother_cat.py
[[[SEARCH]]]
# The archive file line was printed when its status was banked.
[[[DIVIDER]]]
# The archive file line was printed when its status was banked.
if intro:
closing = (
"The three-page walk is finished. "
"Read the save and copy results in your terminal. "
"Review any summary before sharing it. Goodbye."
if decanted else
"The capture run is finished, but the summary was withheld. "
"Read the results in your terminal. Goodbye."
)
_narrate(closing, disclosed)
[[[REPLACE]]]
Apply through your usual patch, app, d, m sequence.
Ignition: start a fresh real walk from this checkout. The source probe loads the changed code itself, but only the real walk can supply the missing audio witness. Use the repository wrapper—not scripts/walk.py, which is the dry-run planner.
Moving from Tutorial to Personal Itinerary
bash walk
printf 'walk_exit=%s\n' "$?"
Choose 2, then complete the three CAPTURE checkpoints. That choice already invokes the bundled introductory contract; it does not require adding a final DECANT prompt.
After the third capture, retain the terminal results and report whether you heard the closing or only saw its text. Do not bank the audio as witnessed from the fixture count.
The independent checkword comparison and fresh-chat answer remain a separate acceptance item already recorded in your router; this patch does not silently discharge them.
4. PROMPT
Continue THE WALK SAYS GOODBYE. The preceding turn proposed one completion-only edit in scripts/mother_cat.py: reuse _narrate after the introductory run prints its handoff results, with separate wording when the summary was withheld and no claim that either destination succeeded. Read this compile's Manifest-listed live receipts first. With that patch present, the completion-block probe should report closing counts 1, 1, 0, 0 in its printed order; the BEFORE source reported 0, 0, 0, 0. This probe exercises source code with stubbed handoff and narration, not a real browser, clipboard or speaker. Reconcile it with my real walk transcript and operator report below. Treat audible completion as witnessed only if I report hearing it. Do not infer successful file or clipboard delivery from the handoff boolean or walk_exit=0. Keep this ride confined to the closing; do not reopen the diff-lens implementation, practice-input repair, shared voice code, wait audio, renderer, menus or publishing. Once this cut is witnessed, identify the smallest remaining evidence-handoff acceptance check before we move to the Botify mini-rule work.
Operator report of the closing audio:
Terminal transcript:
5. EXTERNAL DELIVERABLES
No external deliverables this turn.
MikeLev.in:
Same commands, run twice, one change between them. Where the readings differ is what the change did; the diff in the middle is the receipt.
1: Probe: (BEFORE: hand-run, nothing changed yet)
$ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ .venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
intro=True handoff=True closing=0
intro=True handoff=False closing=0
intro=False handoff=True closing=0
intro=False handoff=False closing=0
(nix) pipulate $
2: Context: (AFTER: the same probes re-run by the compiler as ! lines)
# AD HOC CHOP! The Not-Managed-by-Git Safe-for-Client-Data place. Insert Simpson Couch Gag in white space below (explain anything to the audience you feel needs it explained)G
# adhoc.txt _ _ _ ____ _ _ ___ ____ _
# / \ __| | | | | | ___ ___ / ___| | | |/ _ \| _ \| | Let's do the minimum final polish here to call this done so we can get on with the next thing. Don't dive deep. Get in, clean-up, get out.
# ahe/ _ \ / _` | | |_| |/ _ \ / __| | | | |_| | | | | |_) | | Alright, it's just the closing Piper TTS words.
# ahc ___ \ (_| | | _ | (_) | (__ | |___| _ | |_| | __/|_|
# /_/ \_\__,_| |_| |_|\___/ \___| \____|_| |_|\___/|_| (_)
# To Human: WELCOME TO VIM! It's really NeoVim but I say vim anyway.
# To AI: This is an alternate 40K view to the big book-ore rolling pin spine.
# 1. **Probe**: Baseline Reading
# 2. **Context**: Post-experiment *planned* reading instructions
# 3. **Patch**: The experiment and how to make it happen
# 4. **Prompt**: Post-experiment instructions and how to read results
# 5. **Deliverable**: How the world is forever different moving forward
# The first thing you need to know here is that everything that comes after the
# hash symbol (#) is commented out — and that's EVERYTHING in this file's default
# state. Begin editing-in lines for inclusion as part of the context or adding
# chunks of new context at the bottom. `Ctrl`+`v`, `j` (repeatedly), `l` (to move
# right), `d` (to delete). Reverse that with `Ctrl`+`v`, `j` (repeatedly),
# `Shift`+`i`, `# `, `Esc` to put the hashes back. You can just arrow-key around
# here with `h`, `j`, `k`, `l`. Save-and-quit is a bit tricky because another
# file is also loaded: `Esc`, `:`, `q`, `w`, `!`
# If this is stressing you out and you're a quitter and want to quit, just type:
# `Esc`, `:`, `q`, `!`, `Enter`. That will exit without saving any changes. If
# you want to get over this hump, type: `Esc`, `:`, `T`, `u`, `t`, `o`, `r`, `Enter`.
# This file is just to make it easy having options of what to edit into context.
# You can use whatever text-file you want to stack file-names and commands to
# build an output text-file with the identically stacked output of each file or
# command. In this way we vertically append or "stack" a bunch of text; simple as
# that. If you understand this concept, you're on your way to future-proofing
# yourself in the Age of AI. Congratulations! Here is how to include web pages:
# !URL --------------------------------------------------------------------
# when Public page; what a stranger or crawler sees; the BEFORE of a
# login-wall diagnosis
# switch It shows a login page -> `warm URL` once, then `?URL`
#
# ?URL --------------------------------------------------------------------
# when Anything behind a login, on the site's persistent profile;
# `check URL` first
# switch The lenses show a shell (nav, an `[Iframe]` leaf, no content) ->
# read the wire truth for the XHR the frame makes, then call that
# API with a connector
#
# @URL --------------------------------------------------------------------
# when Every re-read of a page already scraped; no browser, no network
# switch The cached page is stale or was a login wall -> fresh `!` or `?`
#
# $URL --------------------------------------------------------------------
# when Exact markup: meta tags, a JSON blob in a `<script>`
# note Token-heavy; needs a prior scrape
#
# %URL --------------------------------------------------------------------
# when The network log distilled; SPA endpoint discovery
# switch It re-serves the wire truth you already have -> the API
#
# ! cmd -------------------------------------------------------------------
# when Any bounded, non-interactive command as a live receipt
# note Cap it with `-n`; no aliases, no prompts
#
# Connector ---------------------------------------------------------------
# when The number you want is one GET away
# switch LIST until the thing isn't in the list -> FETCH by id -> DRILL
# the path the app's own frame called -> `--grep` to narrow a list
# or find a leaf
# Every step is one argument longer than the last; the moment a lens shows less than the wire does is the moment to stop scraping.
# FOR 40K-FT VIEW (STORY & INFRASTRUCTURE)
# --- START EDITING-IN ON 1ST TURN ---
# ! python scripts/articles/lsa.py -t 1 --reverse --fmt dated-slugs # <-- ROLLING PIN that gives the 40K foot book-spine view of book-ore (only works for me because of local-only git repo)
# ~/repos/nixos/autognome.py # <-- You wake up in the morning and your Tooling & Instrumentation folds out of you like Inspector Gadget.
# init.lua # <-- Those gadgets are made easy-to-use through nifty keyboard shortcuts (but ya gotta learn vim).
# GLOSSARY.md # <-- Like the back of a J.R.R. Tolkien book, there's kooky new terms to know.
# flake.nix # <-- Here is my hardware. Here is my state. Put on your sandbox. And please recreate. (Infrastructure as Code / IaC)
# prompt_foo.py # <-- THIS system
# foo_files.py # <-- main ROUTER
# requirements.in # <-- We've "pinned" everything but still want a flexible Python Data Science virtualenv.
# pyproject.toml # <-- How this is a citizen of the Python "pip install" ecosystem
# __init__.py # <-- Version info
# --- END EDITING-IN ON 1ST TURN ---
# scripts/articles/lsa.py # <-- 2ND BRAIN: Search external memory with `rgx`, `rgxc` & `posts` Blogging for Hackers Jekyll-compatible.
# OPTIONAL ACTUATORS (cheap and good to include to expand the AI's capabilities)
# cli.py # <-- Catch-all actuator for PyPI envs, Python anchoring, MCP tool-call (plus alternatives) and **kwargs like wrapping for CLI
# scripts/xp.py # <-- Transforms host OS copy-paste buffer player-piano music into context-payload.
# scripts/ai.py # <-- How I constantly use local AI to write git commit messages with `m` alias.
# scripts/crawl.py # <-- Feel free to ask for something to be crawled and included in the next turn.
# scripts/weblogin.py # <-- Lets the user "warm up" the cache for their web logins at their leisure on a profile that persists.
# scripts/webclip_2_markdown.py # <-- Surprisingly important program.
# MISCELLANEOUS (rare to include but sometimes critical)
# scripts/foo_cartridge.py # Needs description
# scripts/foo_replay.py # Needs description
# release.py # <-- How everything ends up where it does (GitHub, PyPI, etc.)
# imports/voice_synthesis.py # <-- The wand can talk to you
# imports/ascii_displays.py # <-- Where all the ASCII Art lives
# scripts/release/version_sync.py # <-- Needs to be wrapped into release.py and eliminated, I think.
# --- Under this line is were you paste what the AI gives you ---
# --- We call it context but it's really just the right-hand ---
# --- blast-radius of the "probes" to make this all science. ---
# Carry-over as the important work-in-progress parts of the project here just
# like above but not as long-standing overarching to the framework but rather
# for the current hot spots actively being worked on.
# STICKBUG & MOTHER CAT KATA (WORKING ON THE CHAPTER)
# Always include these with whatever connector
# scripts/sources_menu.py
# scripts/connectors/README.md
# scripts/connectors/wallet.py
# scripts/connectors/botify.py
# scripts/connectors/confluence.py
# scripts/connectors/gmail.py
# scripts/connectors/gsc.py
# scripts/connectors/jira.py
# scripts/connectors/mcp.py
# scripts/connectors/mcp_warm.py
# scripts/connectors/sheets.py
# scripts/connectors/slack.py
# --- START THIS DISCUSSION ---
# Get things started here! Guess at what context should be included.
# If you get it wrong, you're just wasting 1-turn because the AI will help.
# Un-comment lines, add lines with absolute-path filenames or `! ` commands.
# Context 1
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# Context 2
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
imports/voice_synthesis.py
tools/scraper_tools.py
prompt_foo.py
assets/trails/public_walk.yaml
! .venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
flake.nix
init.lua
# --- END `adhoc.txt` TEMPLATE ---
3: Patches: (the one change between the readings)
Blast Radius Check to establish bisection Left-hand Causal Boundary. It is a Popper-thing. Science.
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ patch
(nix) pipulate $ app
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
(nix) pipulate $ d
diff --git a/scripts/mother_cat.py b/scripts/mother_cat.py
index bc931f71..e04f3e07 100644
--- a/scripts/mother_cat.py
+++ b/scripts/mother_cat.py
@@ -875,6 +875,16 @@ async def _ride_steps(trail_path, archive, dry_narrate=False, exports_path=None,
print(" Read the save and copy messages above; either step can fail.")
print(" Review the summary before sharing it. You choose what to send.")
# The archive file line was printed when its status was banked.
+ if intro:
+ closing = (
+ "The three-page walk is finished. "
+ "Read the save and copy results in your terminal. "
+ "Review any summary before sharing it. Goodbye."
+ if decanted else
+ "The capture run is finished, but the summary was withheld. "
+ "Read the results in your terminal. Goodbye."
+ )
+ _narrate(closing, disclosed)
return 0
(nix) pipulate $ m
📝 Committing: chore: Improve closing message in mother_cat.py
[main f1d05cb6] chore: Improve closing message in mother_cat.py
1 file changed, 10 insertions(+)
(nix) pipulate $ git push
Enumerating objects: 7, done.
Counting objects: 100% (7/7), done.
Delta compression using up to 48 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 620 bytes | 620.00 KiB/s, done.
Total 4 (delta 3), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
To github.com:pipulate/pipulate.git
ecafaffb..f1d05cb6 main -> main
(nix) pipulate $
And ignition:
(nix) pipulate $ bash walk
printf 'walk_exit=%s\n' "$?"
Trail resolved: assets/trails/public_walk.yaml
This walk opens three public pages. Nothing to sign in to.
Return here and type CAPTURE when prompted at each page.
After all three captures and successful checks, it tries to save a private summary
and tries to replace your clipboard. Over SSH it uses a bridge file.
Nothing is sent to a chatbot. Review the summary before sharing it.
Choose a walk:
1 Practice - hear the steps; no pages open.
2 Start the walk - open the pages.
q Exit (Enter also exits).
Choice: 2
Riding trail 'public_walk' -- 3 stop(s).
This walk opens three pages. You do not need to click anything. At each page, return here and wait for the CAPTURE prompt. Type CAPTURE and press Enter.
Missing phoneme from id map: ̩
This walk opens three public pages. Nothing to sign in to.
Return here and type CAPTURE when prompted at each page.
After all three captures and successful checks, it tries to save a private summary
and tries to replace your clipboard. Over SSH it uses a bridge file.
Nothing is sent to a chatbot. Review the summary before sharing it.
Summary file: data/decant-preview.md (private; replaced on save).
Checks can miss private details. A blocked check leaves the older file alone.
--- Stop 1/3: the_word ---
I'll open page one. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter.
Opening the browser; waiting for the page...
When the page you want is ready, type CAPTURE and press Enter.
Any other response aborts without capturing artifacts.
CAPTURE> CAPTURE
LOCAL ARCHIVE /home/mike/repos/pipulate/data/captures/walk-y8inhn1w/captures.md (directory 0700, file 0600)
Captured. final_url=https://npvg.org/walk/1/ artifacts=12
ADVANCE -> next stop.
--- Stop 2/3: the_receipt ---
I'll open page two. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter.
Opening the browser; waiting for the page...
When the page you want is ready, type CAPTURE and press Enter.
Any other response aborts without capturing artifacts.
CAPTURE> CAPTURE
Captured. final_url=https://npvg.org/walk/2/ artifacts=12
ADVANCE -> next stop.
--- Stop 3/3: the_two_pages ---
I'll open the last page. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter. Then read the result here.
Opening the browser; waiting for the page...
When the page you want is ready, type CAPTURE and press Enter.
Any other response aborts without capturing artifacts.
CAPTURE> CAPTURE
Captured. final_url=https://npvg.org/walk/3/ artifacts=12
ARCHIVE STATUS complete
Local archive file line for context.md or adhoc.txt:
/home/mike/repos/pipulate/data/captures/walk-y8inhn1w/captures.md
Review locally before compiling; raw bytes are not a safe disclosure.
WALK ROUTER /home/mike/.local/state/pipulate/adhocwalk.txt (0600; UNSANITIZED; not compiled)
Ride complete. Every stop produced a capture receipt.
Checking the summary before saving it and trying the clipboard.
Preview checks: substitutions=0 denylist=0 secrets=0
LOCAL PREVIEW /home/mike/repos/pipulate/data/decant-preview.md (0600; sha256=2e87c1423076ec6023204cf194dc0f6816b6e5e724ada2704b27576201292b62)
Markdown output copied to clipboard
Read the save and copy messages above; either step can fail.
Review the summary before sharing it. You choose what to send.
The three-page walk is finished. Read the save and copy results in your terminal. Review any summary before sharing it. Goodbye.
--------------------------------------------------------------
CAPTURE RUN FINISHED
--------------------------------------------------------------
Read the save and copy messages above. Either step can fail.
Review the summary before sharing it.
Nothing was sent to a chatbot.
--------------------------------------------------------------
walk_exit=0
(nix) pipulate $ vim /home/mike/repos/pipulate/data/decant-preview.md
(nix) pipulate $ vim browser_cache/looking_at/npvg.org/%2Fwalk%2F2%2F--4dc9bd29a71f8100/network_log.jsonl
(nix) pipulate $
Excellent! Not only did I hear the narration of the last step (witnessed by
human), but now we write what the old DECANT command at the end only put into
the clipboard onto disk and I’m able to open it and follow the trail to the
saved so-called HAR file, which is the Network tab from DevTools of everything
the page loaded in the background as resources so almost anything can be
diagnosed that happened “in the browser”. This is solid.
4: Prompt: Continue THE WALK SAYS GOODBYE. The preceding turn proposed one completion-only edit in scripts/mother_cat.py: reuse _narrate after the introductory run prints its handoff results, with separate wording when the summary was withheld and no claim that either destination succeeded. Read this compile’s Manifest-listed live receipts first. With that patch present, the completion-block probe should report closing counts 1, 1, 0, 0 in its printed order; the BEFORE source reported 0, 0, 0, 0. This probe exercises source code with stubbed handoff and narration, not a real browser, clipboard or speaker. Reconcile it with my real walk transcript and operator report below. Treat audible completion as witnessed only if I report hearing it. Do not infer successful file or clipboard delivery from the handoff boolean or walk_exit=0. Keep this ride confined to the closing; do not reopen the diff-lens implementation, practice-input repair, shared voice code, wait audio, renderer, menus or publishing. Once this cut is witnessed, identify the smallest remaining evidence-handoff acceptance check before we move to the Botify mini-rule work.
Operator report of the closing audio:
Terminal transcript:
5: Deliverables: A process that can be demonstrated.
We are just about ready to wrap this article, however what I need to do is have
a local walk that I can just keep editing and re-running to rapidly experiment
with different walks. It has to be something much like adhoc.txt in spirit
which means something I can safely edit and re-edit probably with a shortcut
coming from init.lua so I can keep this walk file somewhere conventional and
out-of-bounds of the system naturally so that it never accidentally gets put
into the Pipulate repo, because these are bound to have lots of Customer
information in them.
See what I’m saying? The walk command now has nice defaults to teach how those
captures work and it’s all driven from a YAML file somewhere (where?) and the
moment after you have a positive experience we have to be able to say something
like “Just type plan.” The language becomes really good here and the whole
demo becomes short and memorable, something like:
- Oh to reproduce my LLM-Q/A process just type:
-
curl -fsSL https://npvg.org bash
-
- Now you can “Walk the walk”. Take practice runs first if you like.
- Once you understand that, just plan you own walk. Type
plan.
And being able to do that is where we want to end this article. After that I need to use the MCP tools by hand; not the generic one but the one that actually connects to Botify’s MCP connector directly. Don’t worry about that for this article; just know that’s where we’re going. It goes something like this:
- Capture something about some web pages.
- Add a reference to the file that capture just did to the
plan. - Add other short and choppy Unix-like commands to that file for the
jiraticket and such.
Now you’ve got complete context for AI. Just add a prompt.md (like this
article) and AI can help you with anything you need regarding that:
- Without spinning its wheels burning tokens and ruining your Claude quota for the week
- Without even the opportunity to confidently hallucinate. And if it does it’s documented to the teeth with these archives… and the LLM knows it would be and therefore won’t hallucinate!
Re-explain all this for the New-B and take us there implementation-wise
reproducing this rapid re-editing of the same file over and over and OOB that I
do here with adhoc.txt but with that same templated default walk we just did
so they will recognize that in the template. After that we might add stuff
requiring a warm-up OAuth web login, but we want to keep this first pass as
simple as possible. Make sense?
ChatGPT 6: Yes: plan should open your private itinerary, and walk plan should follow it. Bare walk should remain the original teaching example.
The goodbye cut is closed: this compile’s live receipt reads 1, 1, 0, 0, and you explicitly report hearing the closing narration. There is no reason to redo that work.
What the newcomer gets
The public example lives at assets/trails/public_walk.yaml. Despite its extension, the reader deliberately accepts the JSON subset of YAML: quoted keys, braces, brackets, and no comments or trailing commas. We should copy that existing template, not write a second version that can drift.
With the changes below:
plan creates ~/.local/state/pipulate/plan.yaml on its first invocation, using the bundled example’s exact bytes, then opens it in Neovim. Subsequent invocations open the same file without replacing your edits. Start by changing the URLs and spoken guidance; leave the capture defaults and connector fields alone.
walk plan reads that private file and uses the existing practice/real-walk menu and capture machinery. walk continues to select the tutorial normally.
The private file sits outside the checkout—not merely behind a .gitignore rule. The helper also refuses symlinks, hard links, permissive file permissions, and locations inside a Git worktree. This implements the same structural separation your compiler already recommends for customer-bearing adhoc.txt files.
For this first pass, no init.lua change is necessary: the terminal word plan is the editor shortcut. It opens a dedicated Neovim session without the journal’s publishing mappings, swap files, persistent undo, or editor history. Save and quit with Esc, :wq, Enter. Invalid edits remain on disk for repair; nothing automatically starts a browser.
One deliberate difference from the tutorial: the editable private copy is a custom walk, so it retains DECANT before the summary handoff. Copying the tutorial’s bytes must not copy its special authorization. The existing introductory check already distinguishes the bundled file from private trails.
Keep the two recipes distinct
There are two useful files, with different jobs:
| File | What it describes |
|---|---|
plan.yaml |
Where the browser goes and what guidance accompanies each stop. |
Your out-of-repo adhoc.txt |
Which captured files and command receipts to assemble for the AI. |
For today, plan edits the itinerary. After the walk, the printed per-run captures.md path can join Jira or Botify receipts in your existing evidence list. Do not paste ! jira ... lines into the JSON-shaped walk file: that would mix two grammars, and the walk currently does not execute connectors.
The team-facing promise is: “You can inspect what the answer was based on.” That is stronger and more defensible than promising that a model cannot hallucinate. Likewise, the saved network log is useful network-event evidence, but the archive explicitly does not claim complete HARs or every response body.
I exercised the proposed changes in an isolated copy. Fourteen check groups passed, including first-time seeding, preservation of edits, unsafe-path refusals, invalid-file recovery, and launcher selection with spaces in the private path. Nix evaluation, actual Neovim, and a real private walk remain runtime checks, not things those fixtures witnessed.
1. PROBES
The existing launcher currently reduces a supplied path to its basename and searches three repo-local directories. Therefore, simply recommending walk /some/private/path.yaml would not work reliably. The patch adds an explicit plan selection instead of changing ordinary trail lookup.
Run these from the checkout before applying the changes. Stop if the reserved name already exists in a trail lane, or if the evaluated Nix hook fails. The Nix probe evaluates and syntax-checks the hook; it does not execute it.
Expect private_plan_helpers=0 before and 2 after; plan_aliases=0 before and 1 after. The public stop count stays 3, and the syntax checks must pass on both sides.
.venv/bin/python -B -c 'import ast,json; from pathlib import Path; t=ast.parse(Path("scripts/mother_cat.py").read_text()); names={n.name for n in t.body if isinstance(n,ast.FunctionDef)}; print("private_plan_helpers="+str(len(names & {"_private_plan_path","_edit_private_plan"}))); d=json.loads(Path("assets/trails/public_walk.yaml").read_text()); print("public_stops="+str(len(d["stops"]))); conflicts=[p for lane in ("Notebooks/Playground/trails","Notebooks/Shared/trails","assets/trails") if (p:=Path(lane)/"plan.yaml").exists()]; assert not conflicts,"plan is already a name in an existing trail lane"; print("plan_name_conflicts=0")'
bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
bash -c 'set -euo pipefail; system=$(LD_LIBRARY_PATH="" nix eval --impure --raw --expr builtins.currentSystem); hook=$(LD_LIBRARY_PATH="" nix eval --impure --no-eval-cache --raw ".#devShells.$system.quiet.shellHook"); test -n "$hook"; printf "%s\n" "$hook" | bash -n; printf "%s\n" "$hook" | .venv/bin/python -B -c "import sys; lines=sys.stdin.read().splitlines(); print(\"quiet_hook_syntax=ok plan_aliases=\"+str(sum(line.strip().startswith(\"alias plan=\") for line in lines)))"'
2. NEXT CONTEXT
Use this scoped selection. Do not include the private plan.yaml itself; source and content-free receipts are sufficient for this implementation check.
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
assets/trails/public_walk.yaml
flake.nix
! .venv/bin/python -B -c 'import ast,json; from pathlib import Path; t=ast.parse(Path("scripts/mother_cat.py").read_text()); names={n.name for n in t.body if isinstance(n,ast.FunctionDef)}; print("private_plan_helpers="+str(len(names & {"_private_plan_path","_edit_private_plan"}))); d=json.loads(Path("assets/trails/public_walk.yaml").read_text()); print("public_stops="+str(len(d["stops"]))); conflicts=[p for lane in ("Notebooks/Playground/trails","Notebooks/Shared/trails","assets/trails") if (p:=Path(lane)/"plan.yaml").exists()]; assert not conflicts,"plan is already a name in an existing trail lane"; print("plan_name_conflicts=0")'
! bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
! bash -c 'set -euo pipefail; system=$(LD_LIBRARY_PATH="" nix eval --impure --raw --expr builtins.currentSystem); hook=$(LD_LIBRARY_PATH="" nix eval --impure --no-eval-cache --raw ".#devShells.$system.quiet.shellHook"); test -n "$hook"; printf "%s\n" "$hook" | bash -n; printf "%s\n" "$hook" | .venv/bin/python -B -c "import sys; lines=sys.stdin.read().splitlines(); print(\"quiet_hook_syntax=ok plan_aliases=\"+str(sum(line.strip().startswith(\"alias plan=\") for line in lines)))"'
3. PATCHES
Car 1 — One private file, seeded once, edited repeatedly
Both replacements belong to scripts/mother_cat.py. The first adds the private editor; the second exposes it without mixing it with ride or disclosure modes.
Target: scripts/mother_cat.py
[[[SEARCH]]]
def _intro_eligible(trail_path, trail=None):
[[[DIVIDER]]]
def _private_plan_path():
"""One local scratch itinerary; resolution is read-only and never falls back."""
path = Path.home() / ".local" / "state" / "pipulate" / "plan.yaml"
resolved = path.resolve()
if path.is_symlink() or resolved.is_relative_to(REPO_ROOT.resolve()):
raise walk.TrailError("plan.yaml must be outside the workshop, not a symlink")
if any((parent / ".git").exists() for parent in resolved.parents):
raise walk.TrailError("plan.yaml must not live inside a Git worktree")
if path.exists():
info = path.stat()
if not path.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
raise walk.TrailError("plan.yaml must be a private regular file (0600), not a hard link")
return path
def _edit_private_plan():
"""Seed once from the bundled bytes, then edit. Never start a capture."""
import subprocess
path = _private_plan_path()
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
if not path.exists():
raw = walk.DEFAULT_TRAIL.read_bytes()
with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".plan-", delete=False) as stream:
temp = Path(stream.name)
try:
stream.write(raw)
stream.flush()
os.fsync(stream.fileno())
except BaseException:
temp.unlink(missing_ok=True)
raise
try:
try:
os.link(temp, path)
except FileExistsError:
pass
finally:
temp.unlink(missing_ok=True)
path = _private_plan_path()
print(f"Private plan: {path}", flush=True)
print("Edit the URLs and guidance. Save and quit with Esc, :wq, Enter.", flush=True)
# An isolated editor keeps plan text out of swap, backup, undo and ShaDa files.
# No caller CWD change; no global editor setting or clipboard handoff.
result = subprocess.run([
"nvim", "-u", "NONE", "-n", "-i", "NONE",
"--cmd", "set nobackup nowritebackup noundofile nomodeline",
"-c", "setlocal filetype=json number textwidth=0",
str(path),
], check=False)
if result.returncode:
return result.returncode
walk.load_trail(_private_plan_path())
print("Plan valid. Type walk plan to try it; type plan to edit it again.")
print("Custom walks keep CAPTURE at each stop and DECANT before the summary handoff.")
return 0
def _intro_eligible(trail_path, trail=None):
[[[REPLACE]]]
Target: scripts/mother_cat.py
[[[SEARCH]]]
args = parser.parse_args(argv)
[[[DIVIDER]]]
parser.add_argument("--plan", action="store_true",
help="seed once and edit the private plan.yaml; never ride")
parser.add_argument("--plan-path", action="store_true",
help="read-only: print the existing private plan path or refuse")
args = parser.parse_args(argv)
if args.plan or args.plan_path:
if (args.plan and args.plan_path) or any((args.trail, args.dry_narrate,
args.exports, args.intro, args.intro_contract, args.disclose is not None)):
parser.error("plan options cannot be combined with other modes")
try:
if args.plan:
return _edit_private_plan()
path = _private_plan_path()
if not path.is_file():
raise walk.TrailError("no private plan yet; type plan first")
print(path)
return 0
except (walk.TrailError, OSError) as exc:
print(f"PLAN REFUSED: {exc}. Existing edits are not replaced.", file=sys.stderr)
return 2
[[[REPLACE]]]
Car 2 — walk plan selects that exact file
A missing or refused private plan exits through the existing launcher’s error handling. It never falls through to a same-named tutorial.
Target: assets/installer/mck.sh
[[[SEARCH]]]
TRAIL_PATH=""
for TRAIL_DIR in $TRAIL_SEARCH_DIRS; do
[[[DIVIDER]]]
TRAIL_PATH=""
# Reserved explicit name; a missing private plan must not fall back to a demo.
if [ "$TRAIL_NAME" = "plan" ]; then
TRAIL_PATH="$("$PY" scripts/mother_cat.py --plan-path)"
fi
for TRAIL_DIR in $TRAIL_SEARCH_DIRS; do
[ -z "$TRAIL_PATH" ] || break
[[[REPLACE]]]
Car 3 — Give the editor its short word
Target: flake.nix
[[[SEARCH]]]
alias walk='bash "$PIPULATE_ROOT/walk"'
[[[DIVIDER]]]
alias walk='bash "$PIPULATE_ROOT/walk"'
alias plan='"$PIPULATE_ROOT/.venv/bin/python" "$PIPULATE_ROOT/scripts/mother_cat.py" --plan'
[[[REPLACE]]]
Use your usual patch, app, d, m per car.
Ignition: leave the current Nix shell, then enter the updated quiet shell from the checkout in the parent terminal. That is what makes the new alias available; merely committing flake.nix does not update the running shell.
nix develop .#quiet
Now type:
plan
For the first acceptance run, keep the three public URLs. Change the first stop’s guidance, save and quit, then run plan again and confirm that your edit survived. Save and quit again.
Then:
walk plan
The selection receipt must name your home-directory plan.yaml, not assets/trails/public_walk.yaml. Choose practice or the real walk as usual. A real custom walk keeps its CAPTURE checkpoints and the final DECANT authorization.
That is the useful demonstration: edit the same private file, run it, inspect the evidence, edit it again. No new parser, no automatic connector execution, and no mutation of the shipped tutorial.
This establishes a checkout workflow once witnessed. It does not establish delivery through the public installer or package; no publishing actuator is included here.
4. PROMPT
Continue the private PLAN loop. Read this compile's Manifest-listed live receipts first.
The goodbye cut is already complete: commit f1d05cb6, completion-probe counts 1,1,0,0, and the operator explicitly heard its closing. Do not redo it.
This turn proposed three file changes:
- scripts/mother_cat.py: plan seeds ~/.local/state/pipulate/plan.yaml once from walk.DEFAULT_TRAIL, reopens existing edits without resetting them, validates after editing, and exposes a read-only --plan-path selector.
- assets/installer/mck.sh: the explicit reserved name plan resolves through that selector, with no fallback when the private file is missing or refused.
- flake.nix: a plan alias opens the editor. Bare walk remains unchanged.
Expected source straddle: private_plan_helpers 0 -> 2; public_stops stays 3; plan_name_conflicts stays 0. The evaluated quiet hook must parse, with plan_aliases 0 -> 1. Launcher Bash syntax must pass.
The prior sandbox tests used mocked editor calls and temporary files. They did not witness Nix evaluation, an actual Neovim session, macOS, or a real private walk. Reconcile the live probes with my operator report below.
Check the actual experience: first plan opens the recognizable tutorial; a changed guidance line survives reopening; walk plan selects the private path and preserves the custom-walk CAPTURE/DECANT contract. Do not infer this from source counts alone.
Do not include customer plan contents merely to prove this. Keep the walkthrough itinerary separate from the adhoc evidence/command list. No new mixed file format, connector execution, shared voice changes, or publishing work.
If the local loop is witnessed, close this cut. Carry forward the independent preview/checkword acceptance and any unwitnessed distribution step without treating them as completed. Botify MCP work follows in its own scoped turn.
Operator report:
Terminal transcript:
5. EXTERNAL DELIVERABLES
Manual-use files: combined patch text and isolated smoke-test source. The test source expects the checkout as its working directory and confines its writes to temporary fixtures. No customer settings or public distribution endpoints were changed.
MikeLev.in:
Same commands, run twice, one change between them. Where the readings differ is what the change did; the diff in the middle is the receipt.
1: Probe: (BEFORE: hand-run, nothing changed yet)
Blast Radius Check to establish bisection Left-hand Causal Boundary. It is a Popper-thing. Science.
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ .venv/bin/python -B -c 'import ast,json; from pathlib import Path; t=ast.parse(Path("scripts/mother_cat.py").read_text()); names={n.name for n in t.body if isinstance(n,ast.FunctionDef)}; print("private_plan_helpers="+str(len(names & {"_private_plan_path","_edit_private_plan"}))); d=json.loads(Path("assets/trails/public_walk.yaml").read_text()); print("public_stops="+str(len(d["stops"]))); conflicts=[p for lane in ("Notebooks/Playground/trails","Notebooks/Shared/trails","assets/trails") if (p:=Path(lane)/"plan.yaml").exists()]; assert not conflicts,"plan is already a name in an existing trail lane"; print("plan_name_conflicts=0")'
bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
bash -c 'set -euo pipefail; system=$(LD_LIBRARY_PATH="" nix eval --impure --raw --expr builtins.currentSystem); hook=$(LD_LIBRARY_PATH="" nix eval --impure --no-eval-cache --raw ".#devShells.$system.quiet.shellHook"); test -n "$hook"; printf "%s\n" "$hook" | bash -n; printf "%s\n" "$hook" | .venv/bin/python -B -c "import sys; lines=sys.stdin.read().splitlines(); print(\"quiet_hook_syntax=ok plan_aliases=\"+str(sum(line.strip().startswith(\"alias plan=\") for line in lines)))"'
private_plan_helpers=0
public_stops=3
plan_name_conflicts=0
launcher_syntax=ok
quiet_hook_syntax=ok plan_aliases=0
(nix) pipulate $
2: Context: (AFTER: the same probes re-run by the compiler as ! lines)
# AD HOC CHOP! The Not-Managed-by-Git Safe-for-Client-Data place. Insert Simpson Couch Gag in white space below (explain anything to the audience you feel needs it explained)G
# adhoc.txt _ _ _ ____ _ _ ___ ____ _
# / \ __| | | | | | ___ ___ / ___| | | |/ _ \| _ \| | Let's do the minimum final polish here to call this done so we can get on with the next thing. Don't dive deep. Get in, clean-up, get out.
# ahe/ _ \ / _` | | |_| |/ _ \ / __| | | | |_| | | | | |_) | | Alright, it's just the closing Piper TTS words.
# ahc ___ \ (_| | | _ | (_) | (__ | |___| _ | |_| | __/|_| And now we make a 2nd place for YAML walk recipes.
# /_/ \_\__,_| |_| |_|\___/ \___| \____|_| |_|\___/|_| (_)
# To Human: WELCOME TO VIM! It's really NeoVim but I say vim anyway.
# To AI: This is an alternate 40K view to the big book-ore rolling pin spine.
# 1. **Probe**: Baseline Reading
# 2. **Context**: Post-experiment *planned* reading instructions
# 3. **Patch**: The experiment and how to make it happen
# 4. **Prompt**: Post-experiment instructions and how to read results
# 5. **Deliverable**: How the world is forever different moving forward
# The first thing you need to know here is that everything that comes after the
# hash symbol (#) is commented out — and that's EVERYTHING in this file's default
# state. Begin editing-in lines for inclusion as part of the context or adding
# chunks of new context at the bottom. `Ctrl`+`v`, `j` (repeatedly), `l` (to move
# right), `d` (to delete). Reverse that with `Ctrl`+`v`, `j` (repeatedly),
# `Shift`+`i`, `# `, `Esc` to put the hashes back. You can just arrow-key around
# here with `h`, `j`, `k`, `l`. Save-and-quit is a bit tricky because another
# file is also loaded: `Esc`, `:`, `q`, `w`, `!`
# If this is stressing you out and you're a quitter and want to quit, just type:
# `Esc`, `:`, `q`, `!`, `Enter`. That will exit without saving any changes. If
# you want to get over this hump, type: `Esc`, `:`, `T`, `u`, `t`, `o`, `r`, `Enter`.
# This file is just to make it easy having options of what to edit into context.
# You can use whatever text-file you want to stack file-names and commands to
# build an output text-file with the identically stacked output of each file or
# command. In this way we vertically append or "stack" a bunch of text; simple as
# that. If you understand this concept, you're on your way to future-proofing
# yourself in the Age of AI. Congratulations! Here is how to include web pages:
# !URL --------------------------------------------------------------------
# when Public page; what a stranger or crawler sees; the BEFORE of a
# login-wall diagnosis
# switch It shows a login page -> `warm URL` once, then `?URL`
#
# ?URL --------------------------------------------------------------------
# when Anything behind a login, on the site's persistent profile;
# `check URL` first
# switch The lenses show a shell (nav, an `[Iframe]` leaf, no content) ->
# read the wire truth for the XHR the frame makes, then call that
# API with a connector
#
# @URL --------------------------------------------------------------------
# when Every re-read of a page already scraped; no browser, no network
# switch The cached page is stale or was a login wall -> fresh `!` or `?`
#
# $URL --------------------------------------------------------------------
# when Exact markup: meta tags, a JSON blob in a `<script>`
# note Token-heavy; needs a prior scrape
#
# %URL --------------------------------------------------------------------
# when The network log distilled; SPA endpoint discovery
# switch It re-serves the wire truth you already have -> the API
#
# ! cmd -------------------------------------------------------------------
# when Any bounded, non-interactive command as a live receipt
# note Cap it with `-n`; no aliases, no prompts
#
# Connector ---------------------------------------------------------------
# when The number you want is one GET away
# switch LIST until the thing isn't in the list -> FETCH by id -> DRILL
# the path the app's own frame called -> `--grep` to narrow a list
# or find a leaf
# Every step is one argument longer than the last; the moment a lens shows less than the wire does is the moment to stop scraping.
# FOR 40K-FT VIEW (STORY & INFRASTRUCTURE)
# --- START EDITING-IN ON 1ST TURN ---
# ! python scripts/articles/lsa.py -t 1 --reverse --fmt dated-slugs # <-- ROLLING PIN that gives the 40K foot book-spine view of book-ore (only works for me because of local-only git repo)
# ~/repos/nixos/autognome.py # <-- You wake up in the morning and your Tooling & Instrumentation folds out of you like Inspector Gadget.
# init.lua # <-- Those gadgets are made easy-to-use through nifty keyboard shortcuts (but ya gotta learn vim).
# GLOSSARY.md # <-- Like the back of a J.R.R. Tolkien book, there's kooky new terms to know.
# flake.nix # <-- Here is my hardware. Here is my state. Put on your sandbox. And please recreate. (Infrastructure as Code / IaC)
# prompt_foo.py # <-- THIS system
# foo_files.py # <-- main ROUTER
# requirements.in # <-- We've "pinned" everything but still want a flexible Python Data Science virtualenv.
# pyproject.toml # <-- How this is a citizen of the Python "pip install" ecosystem
# __init__.py # <-- Version info
# --- END EDITING-IN ON 1ST TURN ---
# scripts/articles/lsa.py # <-- 2ND BRAIN: Search external memory with `rgx`, `rgxc` & `posts` Blogging for Hackers Jekyll-compatible.
# OPTIONAL ACTUATORS (cheap and good to include to expand the AI's capabilities)
# cli.py # <-- Catch-all actuator for PyPI envs, Python anchoring, MCP tool-call (plus alternatives) and **kwargs like wrapping for CLI
# scripts/xp.py # <-- Transforms host OS copy-paste buffer player-piano music into context-payload.
# scripts/ai.py # <-- How I constantly use local AI to write git commit messages with `m` alias.
# scripts/crawl.py # <-- Feel free to ask for something to be crawled and included in the next turn.
# scripts/weblogin.py # <-- Lets the user "warm up" the cache for their web logins at their leisure on a profile that persists.
# scripts/webclip_2_markdown.py # <-- Surprisingly important program.
# MISCELLANEOUS (rare to include but sometimes critical)
# scripts/foo_cartridge.py # Needs description
# scripts/foo_replay.py # Needs description
# release.py # <-- How everything ends up where it does (GitHub, PyPI, etc.)
# imports/voice_synthesis.py # <-- The wand can talk to you
# imports/ascii_displays.py # <-- Where all the ASCII Art lives
# scripts/release/version_sync.py # <-- Needs to be wrapped into release.py and eliminated, I think.
# --- Under this line is were you paste what the AI gives you ---
# --- We call it context but it's really just the right-hand ---
# --- blast-radius of the "probes" to make this all science. ---
# Carry-over as the important work-in-progress parts of the project here just
# like above but not as long-standing overarching to the framework but rather
# for the current hot spots actively being worked on.
# STICKBUG & MOTHER CAT KATA (WORKING ON THE CHAPTER)
# Always include these with whatever connector
# scripts/sources_menu.py
# scripts/connectors/README.md
# scripts/connectors/wallet.py
# scripts/connectors/botify.py
# scripts/connectors/confluence.py
# scripts/connectors/gmail.py
# scripts/connectors/gsc.py
# scripts/connectors/jira.py
# scripts/connectors/mcp.py
# scripts/connectors/mcp_warm.py
# scripts/connectors/sheets.py
# scripts/connectors/slack.py
# --- START THIS DISCUSSION ---
# Get things started here! Guess at what context should be included.
# If you get it wrong, you're just wasting 1-turn because the AI will help.
# Un-comment lines, add lines with absolute-path filenames or `! ` commands.
# Context 1
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# Context 2
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# ! .venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
# flake.nix
# init.lua
# Context 3
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
assets/trails/public_walk.yaml
flake.nix
! .venv/bin/python -B -c 'import ast,json; from pathlib import Path; t=ast.parse(Path("scripts/mother_cat.py").read_text()); names={n.name for n in t.body if isinstance(n,ast.FunctionDef)}; print("private_plan_helpers="+str(len(names & {"_private_plan_path","_edit_private_plan"}))); d=json.loads(Path("assets/trails/public_walk.yaml").read_text()); print("public_stops="+str(len(d["stops"]))); conflicts=[p for lane in ("Notebooks/Playground/trails","Notebooks/Shared/trails","assets/trails") if (p:=Path(lane)/"plan.yaml").exists()]; assert not conflicts,"plan is already a name in an existing trail lane"; print("plan_name_conflicts=0")'
! bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
! bash -c 'set -euo pipefail; system=$(LD_LIBRARY_PATH="" nix eval --impure --raw --expr builtins.currentSystem); hook=$(LD_LIBRARY_PATH="" nix eval --impure --no-eval-cache --raw ".#devShells.$system.quiet.shellHook"); test -n "$hook"; printf "%s\n" "$hook" | bash -n; printf "%s\n" "$hook" | .venv/bin/python -B -c "import sys; lines=sys.stdin.read().splitlines(); print(\"quiet_hook_syntax=ok plan_aliases=\"+str(sum(line.strip().startswith(\"alias plan=\") for line in lines)))"'
# --- END `adhoc.txt` TEMPLATE ---
3: Patches: (the one change between the readings)
Blast Radius Check to establish bisection Left-hand Causal Boundary. It is a Popper-thing. Science.
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ patch
(nix) pipulate $ app
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
(nix) pipulate $ d
diff --git a/scripts/mother_cat.py b/scripts/mother_cat.py
index e04f3e07..e384627e 100644
--- a/scripts/mother_cat.py
+++ b/scripts/mother_cat.py
@@ -138,6 +138,64 @@ INTRO_NOTICE = (
)
+def _private_plan_path():
+ """One local scratch itinerary; resolution is read-only and never falls back."""
+ path = Path.home() / ".local" / "state" / "pipulate" / "plan.yaml"
+ resolved = path.resolve()
+ if path.is_symlink() or resolved.is_relative_to(REPO_ROOT.resolve()):
+ raise walk.TrailError("plan.yaml must be outside the workshop, not a symlink")
+ if any((parent / ".git").exists() for parent in resolved.parents):
+ raise walk.TrailError("plan.yaml must not live inside a Git worktree")
+ if path.exists():
+ info = path.stat()
+ if not path.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
+ raise walk.TrailError("plan.yaml must be a private regular file (0600), not a hard link")
+ return path
+
+
+def _edit_private_plan():
+ """Seed once from the bundled bytes, then edit. Never start a capture."""
+ import subprocess
+
+ path = _private_plan_path()
+ path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ if not path.exists():
+ raw = walk.DEFAULT_TRAIL.read_bytes()
+ with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".plan-", delete=False) as stream:
+ temp = Path(stream.name)
+ try:
+ stream.write(raw)
+ stream.flush()
+ os.fsync(stream.fileno())
+ except BaseException:
+ temp.unlink(missing_ok=True)
+ raise
+ try:
+ try:
+ os.link(temp, path)
+ except FileExistsError:
+ pass
+ finally:
+ temp.unlink(missing_ok=True)
+ path = _private_plan_path()
+ print(f"Private plan: {path}", flush=True)
+ print("Edit the URLs and guidance. Save and quit with Esc, :wq, Enter.", flush=True)
+ # An isolated editor keeps plan text out of swap, backup, undo and ShaDa files.
+ # No caller CWD change; no global editor setting or clipboard handoff.
+ result = subprocess.run([
+ "nvim", "-u", "NONE", "-n", "-i", "NONE",
+ "--cmd", "set nobackup nowritebackup noundofile nomodeline",
+ "-c", "setlocal filetype=json number textwidth=0",
+ str(path),
+ ], check=False)
+ if result.returncode:
+ return result.returncode
+ walk.load_trail(_private_plan_path())
+ print("Plan valid. Type walk plan to try it; type plan to edit it again.")
+ print("Custom walks keep CAPTURE at each stop and DECANT before the summary handoff.")
+ return 0
+
+
def _intro_eligible(trail_path, trail=None):
"""One authority for launcher disclosure and rider authorization scope."""
path = Path(trail_path)
@@ -1113,7 +1171,26 @@ def main(argv=None):
help="read-only: print introductory terms if this is the bundled route; otherwise print nothing")
parser.add_argument("--disclose", metavar="CAPTURES_MD",
help="write a private review-text disclosure; no browser or clipboard")
+ parser.add_argument("--plan", action="store_true",
+ help="seed once and edit the private plan.yaml; never ride")
+ parser.add_argument("--plan-path", action="store_true",
+ help="read-only: print the existing private plan path or refuse")
args = parser.parse_args(argv)
+ if args.plan or args.plan_path:
+ if (args.plan and args.plan_path) or any((args.trail, args.dry_narrate,
+ args.exports, args.intro, args.intro_contract, args.disclose is not None)):
+ parser.error("plan options cannot be combined with other modes")
+ try:
+ if args.plan:
+ return _edit_private_plan()
+ path = _private_plan_path()
+ if not path.is_file():
+ raise walk.TrailError("no private plan yet; type plan first")
+ print(path)
+ return 0
+ except (walk.TrailError, OSError) as exc:
+ print(f"PLAN REFUSED: {exc}. Existing edits are not replaced.", file=sys.stderr)
+ return 2
if args.disclose is not None:
if args.trail or args.dry_narrate or args.exports or args.intro or args.intro_contract:
parser.error("--disclose cannot be combined with ride arguments")
(nix) pipulate $ m
📝 Committing: chore: Implement private plan path and edit functionality
[main 69a303c8] chore: Implement private plan path and edit functionality
1 file changed, 77 insertions(+)
(nix) pipulate $ patch
(nix) pipulate $ app
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
(nix) pipulate $ d
diff --git a/assets/installer/mck.sh b/assets/installer/mck.sh
index dba16703..ee21894c 100644
--- a/assets/installer/mck.sh
+++ b/assets/installer/mck.sh
@@ -376,7 +376,12 @@ fi
# launcher the same thing.
TRAIL_SEARCH_DIRS="Notebooks/Playground/trails Notebooks/Shared/trails assets/trails"
TRAIL_PATH=""
+# Reserved explicit name; a missing private plan must not fall back to a demo.
+if [ "$TRAIL_NAME" = "plan" ]; then
+ TRAIL_PATH="$("$PY" scripts/mother_cat.py --plan-path)"
+fi
for TRAIL_DIR in $TRAIL_SEARCH_DIRS; do
+ [ -z "$TRAIL_PATH" ] || break
if [ -f "$TRAIL_DIR/${TRAIL_NAME}.yaml" ]; then
TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.yaml"
break
(nix) pipulate $ m
📝 Committing: chore: Handle missing plan name gracefully
[main 28524c72] chore: Handle missing plan name gracefully
1 file changed, 5 insertions(+)
(nix) pipulate $ patch
(nix) pipulate $ app
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'flake.nix'.
(nix) pipulate $ d
diff --git a/flake.nix b/flake.nix
index be82d582..2ffc7d51 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1444,6 +1444,7 @@ runScript = pkgs.writeShellScriptBin "run-script" ''
# NOT scripts/walk.py, which is the non-actuating dry-run PLANNER and
# shares nothing with this word but four letters.
alias walk='bash "$PIPULATE_ROOT/walk"'
+ alias plan='"$PIPULATE_ROOT/.venv/bin/python" "$PIPULATE_ROOT/scripts/mother_cat.py" --plan'
# THE CREDENTIAL GAME: bare `warm` is the LIVE red/green board — one
# bounded API call per enrolled wallet slot, GOLD when every row is
# green. `warm <slot>` is the fixer for that one credential, and a
(nix) pipulate $ m
📝 Committing: chore: Add alias for plan script
[main a94acc85] chore: Add alias for plan script
1 file changed, 1 insertion(+)
(nix) pipulate $ git push
Enumerating objects: 19, done.
Counting objects: 100% (19/19), done.
Delta compression using up to 48 threads
Compressing objects: 100% (12/12), done.
Writing objects: 100% (12/12), 2.71 KiB | 1.35 MiB/s, done.
Total 12 (delta 8), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (8/8), completed with 6 local objects.
To github.com:pipulate/pipulate.git
f1d05cb6..a94acc85 main -> main
(nix) pipulate $
We ignite with a rebuild.
(nix) pipulate $ exit
exit
(sys) pipulate $ ndq
(nix) pipulate $
Okay, now I should just have it…
(nix) pipulate $ walk
Trail resolved: assets/trails/public_walk.yaml
This walk opens three public pages. Nothing to sign in to.
Return here and type CAPTURE when prompted at each page.
After all three captures and successful checks, it tries to save a private summary
and tries to replace your clipboard. Over SSH it uses a bridge file.
Nothing is sent to a chatbot. Review the summary before sharing it.
Choose a walk:
1 Practice - hear the steps; no pages open.
2 Start the walk - open the pages.
q Exit (Enter also exits).
Choice: q
Stopped. No real walk started.
(nix) pipulate $ plan
Private plan: /home/mike/.local/state/pipulate/plan.yaml
Edit the URLs and guidance. Save and quit with Esc, :wq, Enter.
Plan valid. Type walk plan to try it; type plan to edit it again.
Custom walks keep CAPTURE at each stop and DECANT before the summary handoff.
(nix) pipulate $ plan
Private plan: /home/mike/.local/state/pipulate/plan.yaml
Edit the URLs and guidance. Save and quit with Esc, :wq, Enter.
Plan valid. Type walk plan to try it; type plan to edit it again.
Custom walks keep CAPTURE at each stop and DECANT before the summary handoff.
(nix) pipulate $ walk plan
Trail resolved: /home/mike/.local/state/pipulate/plan.yaml
CAPTURE saves each page. DECANT asks before saving a summary or copying it.
Choose a walk:
1 Practice - hear the steps; no pages open.
2 Start the walk - open the pages.
q Exit (Enter also exits).
Choice: 1
Practice walk: no browser or page capture.
Riding trail 'public_walk' -- 3 stop(s).
Practice only. No pages will open. You do not need to type anything.
Practice only. In the real walk: This walk opens three pages. You do not need to click anything. At each page, return here and wait for the CAPTURE prompt. Type CAPTURE and press Enter.
Missing phoneme from id map: ̩
==================================================================
THIS WALK: public_walk -- 3 stop(s)
==================================================================
stops, in order the_word, the_receipt, the_two_pages
it opens directly https://mikelev.in/, https://npvg.org/walk/2/, https://npvg.org/walk/3/
names as runnable scripts/connectors/noop.py
browser profile 'default' (persistent=True, headless=False)
==================================================================
CAPTURE saves each stop locally; captures may include account details.
DECANT authorizes a checked preview file and a clipboard attempt.
Preview in workshop: data/decant-preview.md (private; replaced on save).
Declining or failing checks leaves any previous preview unchanged.
Nothing is uploaded automatically. The preview is trimmed.
Review before sharing; checks can miss sensitive data.
==================================================================
--- Stop 1/3: the_word ---
Practice only. In the real walk: I'll open page one. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter.
(dry-narrate: browser and capture skipped)
--- Stop 2/3: the_receipt ---
Practice only. In the real walk: I'll open page two. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter.
(dry-narrate: browser and capture skipped)
--- Stop 3/3: the_two_pages ---
Practice only. In the real walk: I'll open the last page. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter. Then read the result here.
(dry-narrate: browser and capture skipped)
Dry narration complete; no captures were attempted.
Choose a walk:
1 Practice - hear the steps; no pages open.
2 Start the walk - open the pages.
q Exit (Enter also exits).
Choice: q
Stopped. No real walk started.
(nix) pipulate $
Yep, I was able to change the first URL by editing what very much looked like
JSON. I thought it was going to be easier-to-read and easier-to-write YAML. It
totally has a YAML extension but it’s JSON inside for sure. I just checked
assets/trails/public_walk.yaml.
Truthful Naming and the JSON Authoring Surface
4: Prompt: Continue the private PLAN loop. Read this compile’s Manifest-listed live receipts first.
The goodbye cut is already complete: commit f1d05cb6, completion-probe counts 1,1,0,0, and the operator explicitly heard its closing. Do not redo it.
This turn proposed three file changes:
- scripts/mother_cat.py: plan seeds ~/.local/state/pipulate/plan.yaml once from walk.DEFAULT_TRAIL, reopens existing edits without resetting them, validates after editing, and exposes a read-only –plan-path selector.
- assets/installer/mck.sh: the explicit reserved name plan resolves through that selector, with no fallback when the private file is missing or refused.
- flake.nix: a plan alias opens the editor. Bare walk remains unchanged.
Expected source straddle: private_plan_helpers 0 -> 2; public_stops stays 3; plan_name_conflicts stays 0. The evaluated quiet hook must parse, with plan_aliases 0 -> 1. Launcher Bash syntax must pass.
The prior sandbox tests used mocked editor calls and temporary files. They did not witness Nix evaluation, an actual Neovim session, macOS, or a real private walk. Reconcile the live probes with my operator report below.
Check the actual experience: first plan opens the recognizable tutorial; a changed guidance line survives reopening; walk plan selects the private path and preserves the custom-walk CAPTURE/DECANT contract. Do not infer this from source counts alone.
Do not include customer plan contents merely to prove this. Keep the walkthrough itinerary separate from the adhoc evidence/command list. No new mixed file format, connector execution, shared voice changes, or publishing work.
If the local loop is witnessed, close this cut. Carry forward the independent preview/checkword acceptance and any unwitnessed distribution step without treating them as completed. Botify MCP work follows in its own scoped turn.
Operator report:
Terminal transcript:
5: Deliverables: The barebones ability to edit a walk after a seeing a walk, but still with some rough edges and unanswered questions.
ChatGPT 6 (no longer Pro / ran of Pro quota): Context verified.
The private-plan loop itself is now witnessed, not merely source-attested: the live receipts show private_plan_helpers=2, launcher syntax passes, and the evaluated quiet hook contains exactly one plan alias. More importantly, your operator transcript demonstrates the actual UX: plan opens the same private file twice, your changed first URL survives, and walk plan resolves /home/mike/.local/state/pipulate/plan.yaml and rehearses the changed URL while retaining DECANT.
So that cut is closed.
The rough edge you immediately noticed is legitimate: we are calling something YAML while intentionally parsing it as JSON. walk.load_trail() literally calls json.loads(...). And your own transcript catches the UX failure perfectly: it “very much looked like JSON,” despite the .yaml extension.
There are two conceptually clean repairs:
- Make trails real YAML. This is nicer for humans, but Python has no YAML parser in the stdlib. The supplied environment roster does not establish PyYAML as a direct dependency, and Car A currently advertises itself as deliberately stdlib-only. I would not introduce a parser dependency or hand-roll YAML five minutes before the demo.
- Admit the format is JSON and name it
.json. Technically JSON is a subset of YAML 1.2, but that fact is not helping the newcomer. A file extension is UI. If it says.yaml, people reasonably expect YAML syntax.
For this article/demo cut, I would choose the second: tell the truth in the filename now; consider genuine YAML later as its own feature. That is much more in character with what you have been doing throughout this work: remove a misleading abstraction instead of defending it with standards trivia.
However, changing the canonical public_walk.yaml filename is not yet patch-safe from this context alone. That name can be referenced in more places than the currently visible launcher/default path, and the prompt’s own cheapest-falsifying-probe rule says to enumerate those call sites before moving it. So I would not manufacture a rename patch yet.
Also, I would slightly tighten the New-B story now that the loop exists:
walk teaches. plan edits. walk plan rehearses or runs your private version.
That is exceptionally compact. The user does not need to know Mother Cat, Car A/B, JSON-subset-of-YAML, or search lanes during first contact.
One more useful observation: your test changed a URL, but not the spoken guidance. That is enough to prove persistence and routing. It is not yet a real capture of the private plan, because you selected Practice and then quit. So the local authoring loop is witnessed; the custom plan’s full capture/DECANT execution remains unwitnessed. The transcript itself distinguishes those states.
1. PROBES
The cheapest question before touching the extension is simply: how many live references assume .yaml, and which are executable rather than prose? This also tells us whether a rename is a two-line cleanup or a wider schema migration.
rg -n --glob '!foo_files.py' --glob '!prompt.md' --glob '!data/**' 'public_walk\.yaml|\.yaml|JSON subset of YAML|json\.loads' walk assets/installer scripts flake.nix | head -80
.venv/bin/python -B scripts/walk.py --trail assets/trails/public_walk.yaml >/dev/null && printf 'planner_current_format=ok\n'
2. NEXT CONTEXT
Keep the context tight. We no longer need voice, scraping, prompt compilation, or init.lua for this question.
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
assets/trails/public_walk.yaml
flake.nix
! rg -n --glob '!foo_files.py' --glob '!prompt.md' --glob '!data/**' 'public_walk\.yaml|\.yaml|JSON subset of YAML|json\.loads' walk assets/installer scripts flake.nix | head -80
! .venv/bin/python -B scripts/walk.py --trail assets/trails/public_walk.yaml >/dev/null && printf 'planner_current_format=ok\n'
3. PATCHES
No repo patches required this turn.
The private-plan implementation has passed its source straddle and its human UX check. Renaming the format before enumerating its references would turn a cosmetic cleanup into exactly the sort of avoidable cross-file surprise your probe discipline exists to prevent.
No ignition required.
4. PROMPT
Close the private PLAN loop and resolve the misleading .yaml surface without scope creep.
Read this compile's Manifest-listed live receipts first.
Already witnessed and therefore CLOSED:
- private_plan_helpers=2
- launcher syntax passes
- evaluated quiet hook has plan_aliases=1
- human invoked plan twice against ~/.local/state/pipulate/plan.yaml
- the edited first URL survived reopening
- walk plan resolved that exact private path
- practice narration showed the edited URL
- bare walk still resolved assets/trails/public_walk.yaml
Do not redo those implementation changes.
Important distinction: the operator chose Practice and then quit. The editable/routable private-plan loop is witnessed; a full real custom-plan CAPTURE + DECANT ride is not yet witnessed.
The immediate UX defect is naming: the files have .yaml extensions but scripts/walk.py intentionally parses them with json.loads, and the operator immediately perceived them as JSON. Do not defend this with "JSON is valid YAML." Decide the smallest truthful repair after reading the live rg census.
Preferred direction if the census shows a small blast radius: rename the canonical exemplar/private plan surface from .yaml to .json while preserving the existing stdlib-only parser and behavior. Do not add PyYAML or a handwritten YAML parser merely for aesthetics. If the census shows that .yaml is a deeper public contract, report that and choose the smallest honest alternative rather than widening the ride.
Preserve the newcomer grammar:
walk -> learn
plan -> edit your private itinerary
walk plan -> rehearse/run it
Keep itinerary files separate from the later evidence/context recipe containing captures, Jira/Botify receipts and prompt.md. Botify MCP is the next project, not part of this cleanup.
After the naming issue is settled, identify whether one real walk-plan CAPTURE/DECANT run is the final acceptance needed to close the article.
5. EXTERNAL DELIVERABLES
None this turn. The repo already has the barebones private editing loop you wanted; this next cut is naming/acceptance cleanup, not another feature.
MikeLev.in: Okay, I’ll take the recommendation of admitting it’s JSON and renaming.
Same commands, run twice, one change between them. Where the readings differ is what the change did; the diff in the middle is the receipt.
1: Probe: (BEFORE: hand-run, nothing changed yet)
(nix) pipulate $ g
Blast Radius Check to establish bisection Left-hand Causal Boundary. It is a Popper-thing. Science.
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ rg -n --glob '!foo_files.py' --glob '!prompt.md' --glob '!data/**' 'public_walk\.yaml|\.yaml|JSON subset of YAML|json\.loads' walk assets/installer scripts flake.nix | head -80
.venv/bin/python -B scripts/walk.py --trail assets/trails/public_walk.yaml >/dev/null && printf 'planner_current_format=ok\n'
flake.nix:1420: # mothercat assets/trails/first_context.yaml (Jira/Botify/Gmail)
assets/installer/mck.sh:127:TRAIL_NAME="${TRAIL_NAME%.yaml}"
assets/installer/mck.sh:385: if [ -f "$TRAIL_DIR/${TRAIL_NAME}.yaml" ]; then
assets/installer/mck.sh:386: TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.yaml"
assets/installer/mck.sh:406: ls "$TRAIL_DIR"/*.yaml 2>/dev/null | sed 's#^# #' >&2 || true
assets/installer/mck.sh:415:# walk_compile.py puts <name>.yaml beside both, so the file a trail needs is
assets/installer/mck.sh:426:if [ -z "$EXPORTS_PATH" ] && [ -f "${TRAIL_PATH%.yaml}.exports.sh" ]; then
assets/installer/mck.sh:427: EXPORTS_PATH="${TRAIL_PATH%.yaml}.exports.sh"
assets/installer/mck.sh:441:# are the JSON subset of YAML 1.2, so json.load is correct here.
assets/installer/mck.sh:469: echo " Or put them in ${TRAIL_PATH%.yaml}.exports.sh (the shape bookmark_import.py writes), or name a file with --exports=PATH." >&2
scripts/foo_replay.py:214: manifest = json.loads(members["manifest.json"].decode("utf-8"))
scripts/foo_replay.py:277: observed = json.loads(Path(observed_path).read_text(encoding="utf-8"))
scripts/foo_replay.py:292: manifest = json.loads(members["manifest.json"].decode("utf-8"))
scripts/mother_cat.py:143: path = Path.home() / ".local" / "state" / "pipulate" / "plan.yaml"
scripts/mother_cat.py:146: raise walk.TrailError("plan.yaml must be outside the workshop, not a symlink")
scripts/mother_cat.py:148: raise walk.TrailError("plan.yaml must not live inside a Git worktree")
scripts/mother_cat.py:152: raise walk.TrailError("plan.yaml must be a private regular file (0600), not a hard link")
scripts/mother_cat.py:204: if path.resolve() != REPO_ROOT / "assets" / "trails" / "public_walk.yaml":
scripts/mother_cat.py:553:# refuses any path git does not ignore; walk_compile.py puts <name>.yaml
scripts/mother_cat.py:741: # a time. ticket.yaml captured the Jira issue, ADVANCED, and only then
scripts/mother_cat.py:995: record = json.loads(body, object_pairs_hook=walk_cartridge._reject_duplicate_json_keys)
scripts/mother_cat.py:1150: "assets/trails/first_context.yaml"
scripts/mother_cat.py:1175: help="seed once and edit the private plan.yaml; never ride")
scripts/foo_cartridge.py:191: manifest = json.loads(
scripts/continuation_ladder.py:88: return json.loads(Path(path).read_text(encoding="utf-8"))
scripts/botify/botify_api_bootcamp.md:3954: # json.loads(swagger_content_str)
scripts/walk.py:4:Trail files use the JSON subset of YAML 1.2. That keeps this car stdlib-only,
scripts/walk.py:23:DEFAULT_TRAIL = REPO_ROOT / "assets" / "trails" / "public_walk.yaml"
scripts/walk.py:26:# mothercat assets/trails/first_context.yaml (Jira + Botify + Gmail, auth)
scripts/walk.py:182: trail = json.loads(
scripts/connectors/botify.py:575: payload = json.loads(stripped)
scripts/ai.py:172: return json.loads(analysis_json)
scripts/workflow/update_template_config.py:58: config_dict = json.loads(new_config)
scripts/gsc/gsc_top_movers.py:51: data = _json.loads(wallet.read_text(encoding='utf-8'))
scripts/map_sheet.py:326: payload = json.loads(Path(path).read_text(encoding='utf-8'))
scripts/mcp_dummy_server.py:192: msg = json.loads(raw or b"{}")
scripts/walk_compile.py:34:WHAT IT WRITES: <stem>.yaml BESIDE the surface -- the JSON subset of YAML 1.2
scripts/walk_compile.py:421: + " compiles to <stem>.yaml and the trail inside is named "
scripts/walk_compile.py:450: out_path = surface.parent / (stem + ".yaml")
scripts/gsc/gsc_keyworder.py:50: data = _json.loads(wallet.read_text(encoding='utf-8'))
scripts/chat_route_probe.py:302: envelope = json.loads(entry["message"])
scripts/walk_cartridge.py:40: trail.yaml the JSON-subset-of-YAML trail, BYTE-IDENTICAL to source
scripts/walk_cartridge.py:41: manifest.json sha256 of trail.yaml + the CONSENT SURFACE derived from it
scripts/walk_cartridge.py:44:reads BEFORE deciding to ride, recomputed by the verifier from trail.yaml and
scripts/walk_cartridge.py:91: python scripts/walk_cartridge.py seal assets/trails/*.yaml
scripts/walk_cartridge.py:120:# .venv/bin/python scripts/walk_cartridge.py seal assets/trails/*.yaml
scripts/walk_cartridge.py:132:WALK_CARTRIDGE_MEMBERS = ("trail.yaml", "manifest.json")
scripts/walk_cartridge.py:185:# The derivation: trail.yaml -> consent surface
scripts/walk_cartridge.py:189: """Project trail.yaml into what a human must know before riding.
scripts/walk_cartridge.py:196: trail = json.loads(
scripts/walk_cartridge.py:202: f"trail.yaml is not the JSON subset of YAML 1.2: {exc}"
scripts/walk_cartridge.py:206: raise ValueError("trail.yaml must be a mapping")
scripts/walk_cartridge.py:306: "sha256": {"trail.yaml": _sha256_hex(trail_bytes)},
scripts/walk_cartridge.py:368: manifest = json.loads(
scripts/walk_cartridge.py:378: # trail.yaml" -- a sentence that accuses the TRAIL of drifting when the
scripts/walk_cartridge.py:402: expected_manifest = _build_manifest(member_bytes["trail.yaml"])
scripts/walk_cartridge.py:407: "trail.yaml."
scripts/walk_cartridge.py:432: "trail_sha256": expected_manifest["sha256"]["trail.yaml"],
scripts/walk_cartridge.py:442: ("trail.yaml", trail_bytes),
scripts/connectors/wallet.py:185: return json.loads(path.read_text(encoding='utf-8'))
scripts/connectors/wallet.py:705: record = json.loads(tok.read_text(encoding='utf-8'))
scripts/confluence_probe.py:163: return json.loads(raw) if raw else {}
scripts/bookmark_import.py:190: return _from_chrome_json(json.loads(raw))
scripts/botify/make_botify_docs.ipynb:4326: " # json.loads(swagger_content_str)\n",
scripts/connectors/gsc.py:73: wallet = json.loads(WALLET_FILE.read_text(encoding='utf-8'))
scripts/connectors/gsc.py:243: payload = json.loads(stripped)
scripts/connectors/noop.py:7:connector script. public_walk.yaml answered that requirement with
scripts/connectors/mcp_warm.py:220: record = json.loads(out.read_text(encoding="utf-8"))
scripts/connectors/sheets.py:182: blob = json.loads(Path(CREDS_PATH).read_text(encoding='utf-8'))
scripts/connectors/sheets.py:373: blob = json.loads(Path(CREDS_PATH).read_text(encoding='utf-8'))
scripts/connectors/mcp.py:207: record = json.loads(LEGACY_TOKEN_FILE.read_text(encoding="utf-8"))
scripts/connectors/mcp.py:280: data = json.loads(expanded.read_text(encoding="utf-8"))
scripts/connectors/mcp.py:298: data = json.loads(default_token_file.read_text(encoding="utf-8"))
scripts/connectors/mcp.py:364: note = _expiry_note(json.loads(path.read_text(encoding="utf-8")))
scripts/connectors/mcp.py:404: objs.append(json.loads(line[5:].strip()))
scripts/connectors/mcp.py:527: args = json.loads(raw_args) if raw_args.strip() else {}
scripts/articles/gsc_historical_fetch.py:37: data = json.loads(wallet.read_text(encoding='utf-8'))
scripts/articles/confluenceizer.py:312: return json.loads(raw) if raw else {}
scripts/articles/articleizer.py:465: instructions = json.loads(json_str)
scripts/articles/contextualizer.py:56: return json.loads(text)
(nix) pipulate $
2: Context: (AFTER: the same probes re-run by the compiler as ! lines)
# AD HOC CHOP! The Not-Managed-by-Git Safe-for-Client-Data place. Insert Simpson Couch Gag in white space below (explain anything to the audience you feel needs it explained)G
# adhoc.txt _ _ _ ____ _ _ ___ ____ _
# / \ __| | | | | | ___ ___ / ___| | | |/ _ \| _ \| | Let's do the minimum final polish here to call this done so we can get on with the next thing. Don't dive deep. Get in, clean-up, get out.
# ahe/ _ \ / _` | | |_| |/ _ \ / __| | | | |_| | | | | |_) | | Alright, it's just the closing Piper TTS words.
# ahc ___ \ (_| | | _ | (_) | (__ | |___| _ | |_| | __/|_| And now we make a 2nd place for YAML walk recipes.
# /_/ \_\__,_| |_| |_|\___/ \___| \____|_| |_|\___/|_| (_) Okay, let's wrap this.
# To Human: WELCOME TO VIM! It's really NeoVim but I say vim anyway.
# To AI: This is an alternate 40K view to the big book-ore rolling pin spine.
# 1. **Probe**: Baseline Reading
# 2. **Context**: Post-experiment *planned* reading instructions
# 3. **Patch**: The experiment and how to make it happen
# 4. **Prompt**: Post-experiment instructions and how to read results
# 5. **Deliverable**: How the world is forever different moving forward
# The first thing you need to know here is that everything that comes after the
# hash symbol (#) is commented out — and that's EVERYTHING in this file's default
# state. Begin editing-in lines for inclusion as part of the context or adding
# chunks of new context at the bottom. `Ctrl`+`v`, `j` (repeatedly), `l` (to move
# right), `d` (to delete). Reverse that with `Ctrl`+`v`, `j` (repeatedly),
# `Shift`+`i`, `# `, `Esc` to put the hashes back. You can just arrow-key around
# here with `h`, `j`, `k`, `l`. Save-and-quit is a bit tricky because another
# file is also loaded: `Esc`, `:`, `q`, `w`, `!`
# If this is stressing you out and you're a quitter and want to quit, just type:
# `Esc`, `:`, `q`, `!`, `Enter`. That will exit without saving any changes. If
# you want to get over this hump, type: `Esc`, `:`, `T`, `u`, `t`, `o`, `r`, `Enter`.
# This file is just to make it easy having options of what to edit into context.
# You can use whatever text-file you want to stack file-names and commands to
# build an output text-file with the identically stacked output of each file or
# command. In this way we vertically append or "stack" a bunch of text; simple as
# that. If you understand this concept, you're on your way to future-proofing
# yourself in the Age of AI. Congratulations! Here is how to include web pages:
# !URL --------------------------------------------------------------------
# when Public page; what a stranger or crawler sees; the BEFORE of a
# login-wall diagnosis
# switch It shows a login page -> `warm URL` once, then `?URL`
#
# ?URL --------------------------------------------------------------------
# when Anything behind a login, on the site's persistent profile;
# `check URL` first
# switch The lenses show a shell (nav, an `[Iframe]` leaf, no content) ->
# read the wire truth for the XHR the frame makes, then call that
# API with a connector
#
# @URL --------------------------------------------------------------------
# when Every re-read of a page already scraped; no browser, no network
# switch The cached page is stale or was a login wall -> fresh `!` or `?`
#
# $URL --------------------------------------------------------------------
# when Exact markup: meta tags, a JSON blob in a `<script>`
# note Token-heavy; needs a prior scrape
#
# %URL --------------------------------------------------------------------
# when The network log distilled; SPA endpoint discovery
# switch It re-serves the wire truth you already have -> the API
#
# ! cmd -------------------------------------------------------------------
# when Any bounded, non-interactive command as a live receipt
# note Cap it with `-n`; no aliases, no prompts
#
# Connector ---------------------------------------------------------------
# when The number you want is one GET away
# switch LIST until the thing isn't in the list -> FETCH by id -> DRILL
# the path the app's own frame called -> `--grep` to narrow a list
# or find a leaf
# Every step is one argument longer than the last; the moment a lens shows less than the wire does is the moment to stop scraping.
# FOR 40K-FT VIEW (STORY & INFRASTRUCTURE)
# --- START EDITING-IN ON 1ST TURN ---
# ! python scripts/articles/lsa.py -t 1 --reverse --fmt dated-slugs # <-- ROLLING PIN that gives the 40K foot book-spine view of book-ore (only works for me because of local-only git repo)
# ~/repos/nixos/autognome.py # <-- You wake up in the morning and your Tooling & Instrumentation folds out of you like Inspector Gadget.
# init.lua # <-- Those gadgets are made easy-to-use through nifty keyboard shortcuts (but ya gotta learn vim).
# GLOSSARY.md # <-- Like the back of a J.R.R. Tolkien book, there's kooky new terms to know.
# flake.nix # <-- Here is my hardware. Here is my state. Put on your sandbox. And please recreate. (Infrastructure as Code / IaC)
# prompt_foo.py # <-- THIS system
# foo_files.py # <-- main ROUTER
# requirements.in # <-- We've "pinned" everything but still want a flexible Python Data Science virtualenv.
# pyproject.toml # <-- How this is a citizen of the Python "pip install" ecosystem
# __init__.py # <-- Version info
# --- END EDITING-IN ON 1ST TURN ---
# scripts/articles/lsa.py # <-- 2ND BRAIN: Search external memory with `rgx`, `rgxc` & `posts` Blogging for Hackers Jekyll-compatible.
# OPTIONAL ACTUATORS (cheap and good to include to expand the AI's capabilities)
# cli.py # <-- Catch-all actuator for PyPI envs, Python anchoring, MCP tool-call (plus alternatives) and **kwargs like wrapping for CLI
# scripts/xp.py # <-- Transforms host OS copy-paste buffer player-piano music into context-payload.
# scripts/ai.py # <-- How I constantly use local AI to write git commit messages with `m` alias.
# scripts/crawl.py # <-- Feel free to ask for something to be crawled and included in the next turn.
# scripts/weblogin.py # <-- Lets the user "warm up" the cache for their web logins at their leisure on a profile that persists.
# scripts/webclip_2_markdown.py # <-- Surprisingly important program.
# MISCELLANEOUS (rare to include but sometimes critical)
# scripts/foo_cartridge.py # Needs description
# scripts/foo_replay.py # Needs description
# release.py # <-- How everything ends up where it does (GitHub, PyPI, etc.)
# imports/voice_synthesis.py # <-- The wand can talk to you
# imports/ascii_displays.py # <-- Where all the ASCII Art lives
# scripts/release/version_sync.py # <-- Needs to be wrapped into release.py and eliminated, I think.
# --- Under this line is were you paste what the AI gives you ---
# --- We call it context but it's really just the right-hand ---
# --- blast-radius of the "probes" to make this all science. ---
# Carry-over as the important work-in-progress parts of the project here just
# like above but not as long-standing overarching to the framework but rather
# for the current hot spots actively being worked on.
# STICKBUG & MOTHER CAT KATA (WORKING ON THE CHAPTER)
# Always include these with whatever connector
# scripts/sources_menu.py
# scripts/connectors/README.md
# scripts/connectors/wallet.py
# scripts/connectors/botify.py
# scripts/connectors/confluence.py
# scripts/connectors/gmail.py
# scripts/connectors/gsc.py
# scripts/connectors/jira.py
# scripts/connectors/mcp.py
# scripts/connectors/mcp_warm.py
# scripts/connectors/sheets.py
# scripts/connectors/slack.py
# --- START THIS DISCUSSION ---
# Get things started here! Guess at what context should be included.
# If you get it wrong, you're just wasting 1-turn because the AI will help.
# Un-comment lines, add lines with absolute-path filenames or `! ` commands.
# Context 1
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# Context 2
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# ! .venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
# flake.nix
# init.lua
# Context 3
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# assets/trails/public_walk.yaml
# flake.nix
# ! .venv/bin/python -B -c 'import ast,json; from pathlib import Path; t=ast.parse(Path("scripts/mother_cat.py").read_text()); names={n.name for n in t.body if isinstance(n,ast.FunctionDef)}; print("private_plan_helpers="+str(len(names & {"_private_plan_path","_edit_private_plan"}))); d=json.loads(Path("assets/trails/public_walk.yaml").read_text()); print("public_stops="+str(len(d["stops"]))); conflicts=[p for lane in ("Notebooks/Playground/trails","Notebooks/Shared/trails","assets/trails") if (p:=Path(lane)/"plan.yaml").exists()]; assert not conflicts,"plan is already a name in an existing trail lane"; print("plan_name_conflicts=0")'
# ! bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
# ! bash -c 'set -euo pipefail; system=$(LD_LIBRARY_PATH="" nix eval --impure --raw --expr builtins.currentSystem); hook=$(LD_LIBRARY_PATH="" nix eval --impure --no-eval-cache --raw ".#devShells.$system.quiet.shellHook"); test -n "$hook"; printf "%s\n" "$hook" | bash -n; printf "%s\n" "$hook" | .venv/bin/python -B -c "import sys; lines=sys.stdin.read().splitlines(); print(\"quiet_hook_syntax=ok plan_aliases=\"+str(sum(line.strip().startswith(\"alias plan=\") for line in lines)))"'
# Context 4
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_cartridge.py
assets/trails/public_walk.yaml
flake.nix
! rg -n --glob '!foo_files.py' --glob '!prompt.md' --glob '!data/**' 'public_walk\.yaml|\.yaml|JSON subset of YAML|json\.loads' walk assets/installer scripts flake.nix | head -80
! .venv/bin/python -B scripts/walk.py --trail assets/trails/public_walk.yaml >/dev/null && printf 'planner_current_format=ok\n'
scripts/walk_compile.py
# --- END `adhoc.txt` TEMPLATE ---
3: Patches: Holding back until we know.
4: Prompt: Close the private PLAN loop and resolve the misleading .yaml surface without scope creep.
Read this compile’s Manifest-listed live receipts first.
Already witnessed and therefore CLOSED:
- private_plan_helpers=2
- launcher syntax passes
- evaluated quiet hook has plan_aliases=1
- human invoked plan twice against ~/.local/state/pipulate/plan.yaml
- the edited first URL survived reopening
- walk plan resolved that exact private path
- practice narration showed the edited URL
- bare walk still resolved assets/trails/public_walk.yaml
Do not redo those implementation changes.
Important distinction: the operator chose Practice and then quit. The editable/routable private-plan loop is witnessed; a full real custom-plan CAPTURE + DECANT ride is not yet witnessed.
The immediate UX defect is naming: the files have .yaml extensions but scripts/walk.py intentionally parses them with json.loads, and the operator immediately perceived them as JSON. Do not defend this with “JSON is valid YAML.” Decide the smallest truthful repair after reading the live rg census.
Preferred direction if the census shows a small blast radius: rename the canonical exemplar/private plan surface from .yaml to .json while preserving the existing stdlib-only parser and behavior. Do not add PyYAML or a handwritten YAML parser merely for aesthetics. If the census shows that .yaml is a deeper public contract, report that and choose the smallest honest alternative rather than widening the ride.
Preserve the newcomer grammar: walk -> learn plan -> edit your private itinerary walk plan -> rehearse/run it
Keep itinerary files separate from the later evidence/context recipe containing captures, Jira/Botify receipts and prompt.md. Botify MCP is the next project, not part of this cleanup.
After the naming issue is settled, identify whether one real walk-plan CAPTURE/DECANT run is the final acceptance needed to close the article.
5: Deliverables: Making it cleaner.
Let’s wrap this up ASAP and turn it into an article that stages things for the next article. If we can do the rename safely, do it. If not tell me and we’ll wrap the article.
Note: Showing one turn is skipped where I fixed context.
ChatGPT 6 Medium: Context verified.
Yes, we can do the rename safely now.
The missing writer is present, and it confirms the boundary cleanly: walk_compile.py currently derives the output filename itself as <stem>.yaml, so it belongs in the same rename transaction. The launcher derives exports from the trail suffix, so that derivation must change at the same time.
The key is compatibility, not flag day:
- New canonical/tutorial trail:
.json - New compiled trails:
.json - New private plan:
plan.json - Existing
plan.yamlgets migrated, not overwritten - Launcher reads
.jsonfirst but continues accepting legacy.yaml - Existing sealed cartridge member
trail.yamlstays exactly as-is - Existing old expert trails can remain
.yamluntil somebody deliberately regenerates them
That gets the newcomer-facing truth without turning this into a cartridge migration or an authenticated-trail cleanup. walk_cartridge.py explicitly has trail.yaml wired into its versioned archive structure, so we leave that internal member alone; only its filesystem-input examples need to point at the new .json authoring surface.
The private migration is also safe: plan already owns creation/editing, so it is the correct ignition point to atomically rename the existing validated 0600 plan.yaml to plan.json. The user’s edit survives; the bundled template is not reseeded.
1. PROBES
This replaces the bad ready probe. Before the cut it should report the canonical .yaml, default .yaml, three stops, and compiler_json=False. Afterward the identical probe should report .json, .json, three stops, and compiler_json=True. The Bash syntax check protects the compatibility changes in the launcher.
.venv/bin/python -B -c 'from pathlib import Path; from scripts import walk; c=[Path("assets/trails/public_walk.yaml"),Path("assets/trails/public_walk.json")]; p=[x for x in c if x.exists()]; assert len(p)==1,p; t=walk.load_trail(p[0]); s=Path("scripts/walk_compile.py").read_text(); print("canonical="+p[0].name+" default="+walk.DEFAULT_TRAIL.name+" stops="+str(len(t["stops"]))+" compiler_json="+str('\''stem + ".json"'\'' in s))'
bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
rg -n 'public_walk\.(yaml|json)|plan\.(yaml|json)|<stem>\.(yaml|json)' assets/installer/mck.sh scripts/mother_cat.py scripts/walk.py scripts/walk_compile.py scripts/walk_cartridge.py | head -60
2. NEXT CONTEXT
After this cut, point the compiler at the renamed canonical file.
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_compile.py
scripts/walk_cartridge.py
assets/trails/public_walk.json
! .venv/bin/python -B -c 'from pathlib import Path; from scripts import walk; c=[Path("assets/trails/public_walk.yaml"),Path("assets/trails/public_walk.json")]; p=[x for x in c if x.exists()]; assert len(p)==1,p; t=walk.load_trail(p[0]); s=Path("scripts/walk_compile.py").read_text(); print("canonical="+p[0].name+" default="+walk.DEFAULT_TRAIL.name+" stops="+str(len(t["stops"]))+" compiler_json="+str('\''stem + ".json"'\'' in s))'
! bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
! rg -n 'public_walk\.(yaml|json)|plan\.(yaml|json)|<stem>\.(yaml|json)' assets/installer/mck.sh scripts/mother_cat.py scripts/walk.py scripts/walk_compile.py scripts/walk_cartridge.py | head -60
3. PATCHES
This is one logical rename transaction. Apply these source edits, then perform the git mv before d/m, so there is never a committed state where DEFAULT_TRAIL points at a nonexistent file.
Target: scripts/walk.py
[[[SEARCH]]]
Trail files use the JSON subset of YAML 1.2. That keeps this car stdlib-only,
duplicate-key-checkable, and still valid YAML. There is deliberately no
browser, voice, shell, or adhoc.txt mutation path in this file.
[[[DIVIDER]]]
Trail files use JSON. That keeps this car stdlib-only, duplicate-key-checkable,
and explicit about the syntax humans are editing. There is deliberately no
browser, voice, shell, or adhoc.txt mutation path in this file.
[[[REPLACE]]]
Target: scripts/walk.py
[[[SEARCH]]]
DEFAULT_TRAIL = REPO_ROOT / "assets" / "trails" / "public_walk.yaml"
[[[DIVIDER]]]
DEFAULT_TRAIL = REPO_ROOT / "assets" / "trails" / "public_walk.json"
[[[REPLACE]]]
Target: scripts/mother_cat.py
[[[SEARCH]]]
def _private_plan_path():
"""One local scratch itinerary; resolution is read-only and never falls back."""
path = Path.home() / ".local" / "state" / "pipulate" / "plan.yaml"
resolved = path.resolve()
if path.is_symlink() or resolved.is_relative_to(REPO_ROOT.resolve()):
raise walk.TrailError("plan.yaml must be outside the workshop, not a symlink")
if any((parent / ".git").exists() for parent in resolved.parents):
raise walk.TrailError("plan.yaml must not live inside a Git worktree")
if path.exists():
info = path.stat()
if not path.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
raise walk.TrailError("plan.yaml must be a private regular file (0600), not a hard link")
return path
[[[DIVIDER]]]
def _private_plan_path():
"""One local scratch itinerary; resolution is read-only and never falls back."""
path = Path.home() / ".local" / "state" / "pipulate" / "plan.json"
resolved = path.resolve()
if path.is_symlink() or resolved.is_relative_to(REPO_ROOT.resolve()):
raise walk.TrailError("plan.json must be outside the workshop, not a symlink")
if any((parent / ".git").exists() for parent in resolved.parents):
raise walk.TrailError("plan.json must not live inside a Git worktree")
if path.exists():
info = path.stat()
if not path.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
raise walk.TrailError("plan.json must be a private regular file (0600), not a hard link")
return path
[[[REPLACE]]]
Target: scripts/mother_cat.py
[[[SEARCH]]]
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
[[[DIVIDER]]]
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
legacy = path.with_suffix(".yaml")
if not path.exists() and legacy.exists():
if legacy.is_symlink():
raise walk.TrailError("legacy plan.yaml must not be a symlink")
info = legacy.stat()
if not legacy.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
raise walk.TrailError("legacy plan.yaml must be a private regular file (0600), not a hard link")
os.replace(legacy, path)
print(f"Migrated private plan to {path}", flush=True)
[[[REPLACE]]]
Target: scripts/mother_cat.py
[[[SEARCH]]]
if path.resolve() != REPO_ROOT / "assets" / "trails" / "public_walk.yaml":
[[[DIVIDER]]]
if path.resolve() != REPO_ROOT / "assets" / "trails" / "public_walk.json":
[[[REPLACE]]]
Target: scripts/mother_cat.py
[[[SEARCH]]]
help="seed once and edit the private plan.yaml; never ride")
[[[DIVIDER]]]
help="seed once and edit the private plan.json; never ride")
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
TRAIL_NAME="${TRAIL_NAME%.yaml}"
[[[DIVIDER]]]
TRAIL_NAME="${TRAIL_NAME%.json}"
TRAIL_NAME="${TRAIL_NAME%.yaml}"
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
if [ -f "$TRAIL_DIR/${TRAIL_NAME}.yaml" ]; then
TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.yaml"
break
fi
[[[DIVIDER]]]
if [ -f "$TRAIL_DIR/${TRAIL_NAME}.json" ]; then
TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.json"
break
fi
if [ -f "$TRAIL_DIR/${TRAIL_NAME}.yaml" ]; then
TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.yaml"
break
fi
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
ls "$TRAIL_DIR"/*.yaml 2>/dev/null | sed 's#^# #' >&2 || true
[[[DIVIDER]]]
ls "$TRAIL_DIR"/*.json "$TRAIL_DIR"/*.yaml 2>/dev/null | sed 's#^# #' >&2 || true
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
# walk_compile.py puts <name>.yaml beside both, so the file a trail needs is
[[[DIVIDER]]]
# walk_compile.py puts <name>.json beside both, so the file a trail needs is
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
EXPORTS_PATH="$EXPORTS_OVERRIDE"
if [ -z "$EXPORTS_PATH" ] && [ -f "${TRAIL_PATH%.yaml}.exports.sh" ]; then
EXPORTS_PATH="${TRAIL_PATH%.yaml}.exports.sh"
fi
[[[DIVIDER]]]
TRAIL_STEM="${TRAIL_PATH%.json}"
TRAIL_STEM="${TRAIL_STEM%.yaml}"
EXPORTS_PATH="$EXPORTS_OVERRIDE"
if [ -z "$EXPORTS_PATH" ] && [ -f "$TRAIL_STEM.exports.sh" ]; then
EXPORTS_PATH="$TRAIL_STEM.exports.sh"
fi
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
# are the JSON subset of YAML 1.2, so json.load is correct here.
[[[DIVIDER]]]
# are JSON, so json.load is the exact parser for the authoring format.
[[[REPLACE]]]
Target: assets/installer/mck.sh
[[[SEARCH]]]
echo " Or put them in ${TRAIL_PATH%.yaml}.exports.sh (the shape bookmark_import.py writes), or name a file with --exports=PATH." >&2
[[[DIVIDER]]]
echo " Or put them in $TRAIL_STEM.exports.sh (the shape bookmark_import.py writes), or name a file with --exports=PATH." >&2
[[[REPLACE]]]
Target: scripts/walk_compile.py
[[[SEARCH]]]
WHAT IT WRITES: <stem>.yaml BESIDE the surface -- the JSON subset of YAML 1.2
that walk.py accepts UNMODIFIED. The output path is a pure function of the
[[[DIVIDER]]]
WHAT IT WRITES: <stem>.json BESIDE the surface -- ordinary JSON that walk.py
accepts UNMODIFIED. The output path is a pure function of the
[[[REPLACE]]]
Target: scripts/walk_compile.py
[[[SEARCH]]]
+ " compiles to <stem>.yaml and the trail inside is named "
[[[DIVIDER]]]
+ " compiles to <stem>.json and the trail inside is named "
[[[REPLACE]]]
Target: scripts/walk_compile.py
[[[SEARCH]]]
out_path = surface.parent / (stem + ".yaml")
[[[DIVIDER]]]
out_path = surface.parent / (stem + ".json")
[[[REPLACE]]]
Target: scripts/walk_cartridge.py
[[[SEARCH]]]
python scripts/walk_cartridge.py seal assets/trails/*.yaml
[[[DIVIDER]]]
python scripts/walk_cartridge.py seal assets/trails/*.json
[[[REPLACE]]]
Target: scripts/walk_cartridge.py
[[[SEARCH]]]
# .venv/bin/python scripts/walk_cartridge.py seal assets/trails/*.yaml
[[[DIVIDER]]]
# .venv/bin/python scripts/walk_cartridge.py seal assets/trails/*.json
[[[REPLACE]]]
Then, before d and m for this car, rename the tracked exemplar:
git mv assets/trails/public_walk.yaml assets/trails/public_walk.json
Do not rename trail.yaml inside walk_cartridge.py; that is the sealed v3 member name, not the filesystem authoring surface.
Also do not rename existing first_context.yaml here. The launcher deliberately retains .yaml fallback, so old trails keep working while every newly compiled trail becomes .json. That is what makes this safe instead of gratuitously wide.
Ignition: after commit/push, type:
plan
On this machine that is the one-time migration actuator. Because your current private file already exists, it should validate the old plan.yaml, rename those exact bytes to plan.json, then open them. Save and quit without needing to change anything.
Then verify the actual UX:
walk -> Trail resolved: assets/trails/public_walk.json
plan -> Private plan: ~/.local/state/pipulate/plan.json
walk plan -> Trail resolved: ~/.local/state/pipulate/plan.json
If you have the few minutes, choose 2 on walk plan, do the three CAPTUREs, and type DECANT. That would close the only meaningful runtime gap left in this article: the editable private trail has been rehearsed, but not yet ridden end-to-end.
4. PROMPT
Close the JSON PLAN rename and dismount this article.
Read this compile’s Manifest-listed live receipts first.
This turn should have made one compatibility-preserving rename transaction:
- assets/trails/public_walk.yaml -> public_walk.json
- scripts/walk.py names JSON honestly and DEFAULT_TRAIL points to public_walk.json
- scripts/mother_cat.py uses ~/.local/state/pipulate/plan.json
- the first
planafter the patch migrates an existing safe 0600 plan.yaml to plan.json with os.replace rather than reseeding it - introductory authorization keys off public_walk.json
- assets/installer/mck.sh prefers .json but continues reading legacy .yaml trails
- exports sibling derivation works for either suffix
- scripts/walk_compile.py now writes
.json - scripts/walk_cartridge.py examples seal filesystem .json trails
- the sealed cartridge’s internal trail.yaml member and schema v3 remain unchanged
Do not expand this into renaming historical trails, first_context.yaml, foo_files.py receipts, or the cartridge member. Legacy .yaml compatibility is deliberate.
The corrected source probe should straddle from: canonical=public_walk.yaml default=public_walk.yaml stops=3 compiler_json=False to: canonical=public_walk.json default=public_walk.json stops=3 compiler_json=True
Launcher Bash syntax must remain green.
Reconcile those receipts with the operator report below. Specifically verify whether:
planmigrated the existing private file to plan.json without losing the prior edit- bare
walkresolved public_walk.json walk planresolved the private plan.json- a REAL custom walk was ridden through CAPTURE + DECANT, if the operator did it
If the first three are witnessed, the rename is complete. If the real custom ride is also witnessed, the PLAN article’s local acceptance is complete and should dismount immediately.
Do not keep polishing. Carry forward the independent preview/checkword acceptance and any unwitnessed public-distribution step separately.
The next article is Botify work: use the capture/receipt machinery plus short Unix-like connector commands to investigate SpeedWorkers mini-rules by hand. Do not start that implementation in this turn.
5. EXTERNAL DELIVERABLES
No external deliverables this turn. The endpoint is deliberately boring and memorable:
walk teaches. plan edits. walk plan does yours.
MikeLev.in:
Same commands, run twice, one change between them. Where the readings differ is what the change did; the diff in the middle is the receipt.
1: Probe: (BEFORE: hand-run, nothing changed yet)
$ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ .venv/bin/python -B -c 'from pathlib import Path; from scripts import walk; c=[Path("assets/trails/public_walk.yaml"),Path("assets/trails/public_walk.json")]; p=[x for x in c if x.exists()]; assert len(p)==1,p; t=walk.load_trail(p[0]); s=Path("scripts/walk_compile.py").read_text(); print("canonical="+p[0].name+" default="+walk.DEFAULT_TRAIL.name+" stops="+str(len(t["stops"]))+" compiler_json="+str('\''stem + ".json"'\'' in s))'
bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
rg -n 'public_walk\.(yaml|json)|plan\.(yaml|json)|<stem>\.(yaml|json)' assets/installer/mck.sh scripts/mother_cat.py scripts/walk.py scripts/walk_compile.py scripts/walk_cartridge.py | head -60
canonical=public_walk.yaml default=public_walk.yaml stops=3 compiler_json=False
launcher_syntax=ok
scripts/walk_compile.py:34:WHAT IT WRITES: <stem>.yaml BESIDE the surface -- the JSON subset of YAML 1.2
scripts/walk_compile.py:421: + " compiles to <stem>.yaml and the trail inside is named "
scripts/walk.py:23:DEFAULT_TRAIL = REPO_ROOT / "assets" / "trails" / "public_walk.yaml"
scripts/mother_cat.py:143: path = Path.home() / ".local" / "state" / "pipulate" / "plan.yaml"
scripts/mother_cat.py:146: raise walk.TrailError("plan.yaml must be outside the workshop, not a symlink")
scripts/mother_cat.py:148: raise walk.TrailError("plan.yaml must not live inside a Git worktree")
scripts/mother_cat.py:152: raise walk.TrailError("plan.yaml must be a private regular file (0600), not a hard link")
scripts/mother_cat.py:204: if path.resolve() != REPO_ROOT / "assets" / "trails" / "public_walk.yaml":
scripts/mother_cat.py:1175: help="seed once and edit the private plan.yaml; never ride")
(nix) pipulate $
2: Context: (AFTER: the same probes re-run by the compiler as ! lines)
# AD HOC CHOP! The Not-Managed-by-Git Safe-for-Client-Data place. Insert Simpson Couch Gag in white space below (explain anything to the audience you feel needs it explained)G
# adhoc.txt _ _ _ ____ _ _ ___ ____ _
# / \ __| | | | | | ___ ___ / ___| | | |/ _ \| _ \| | Let's do the minimum final polish here to call this done so we can get on with the next thing. Don't dive deep. Get in, clean-up, get out.
# ahe/ _ \ / _` | | |_| |/ _ \ / __| | | | |_| | | | | |_) | | Alright, it's just the closing Piper TTS words.
# ahc ___ \ (_| | | _ | (_) | (__ | |___| _ | |_| | __/|_| And now we make a 2nd place for YAML walk recipes.
# /_/ \_\__,_| |_| |_|\___/ \___| \____|_| |_|\___/|_| (_) Okay, let's wrap this. Wrapping. Can't say YAML and show JSON to New-B.
# To Human: WELCOME TO VIM! It's really NeoVim but I say vim anyway.
# To AI: This is an alternate 40K view to the big book-ore rolling pin spine.
# 1. **Probe**: Baseline Reading
# 2. **Context**: Post-experiment *planned* reading instructions
# 3. **Patch**: The experiment and how to make it happen
# 4. **Prompt**: Post-experiment instructions and how to read results
# 5. **Deliverable**: How the world is forever different moving forward
# The first thing you need to know here is that everything that comes after the
# hash symbol (#) is commented out — and that's EVERYTHING in this file's default
# state. Begin editing-in lines for inclusion as part of the context or adding
# chunks of new context at the bottom. `Ctrl`+`v`, `j` (repeatedly), `l` (to move
# right), `d` (to delete). Reverse that with `Ctrl`+`v`, `j` (repeatedly),
# `Shift`+`i`, `# `, `Esc` to put the hashes back. You can just arrow-key around
# here with `h`, `j`, `k`, `l`. Save-and-quit is a bit tricky because another
# file is also loaded: `Esc`, `:`, `q`, `w`, `!`
# If this is stressing you out and you're a quitter and want to quit, just type:
# `Esc`, `:`, `q`, `!`, `Enter`. That will exit without saving any changes. If
# you want to get over this hump, type: `Esc`, `:`, `T`, `u`, `t`, `o`, `r`, `Enter`.
# This file is just to make it easy having options of what to edit into context.
# You can use whatever text-file you want to stack file-names and commands to
# build an output text-file with the identically stacked output of each file or
# command. In this way we vertically append or "stack" a bunch of text; simple as
# that. If you understand this concept, you're on your way to future-proofing
# yourself in the Age of AI. Congratulations! Here is how to include web pages:
# !URL --------------------------------------------------------------------
# when Public page; what a stranger or crawler sees; the BEFORE of a
# login-wall diagnosis
# switch It shows a login page -> `warm URL` once, then `?URL`
#
# ?URL --------------------------------------------------------------------
# when Anything behind a login, on the site's persistent profile;
# `check URL` first
# switch The lenses show a shell (nav, an `[Iframe]` leaf, no content) ->
# read the wire truth for the XHR the frame makes, then call that
# API with a connector
#
# @URL --------------------------------------------------------------------
# when Every re-read of a page already scraped; no browser, no network
# switch The cached page is stale or was a login wall -> fresh `!` or `?`
#
# $URL --------------------------------------------------------------------
# when Exact markup: meta tags, a JSON blob in a `<script>`
# note Token-heavy; needs a prior scrape
#
# %URL --------------------------------------------------------------------
# when The network log distilled; SPA endpoint discovery
# switch It re-serves the wire truth you already have -> the API
#
# ! cmd -------------------------------------------------------------------
# when Any bounded, non-interactive command as a live receipt
# note Cap it with `-n`; no aliases, no prompts
#
# Connector ---------------------------------------------------------------
# when The number you want is one GET away
# switch LIST until the thing isn't in the list -> FETCH by id -> DRILL
# the path the app's own frame called -> `--grep` to narrow a list
# or find a leaf
# Every step is one argument longer than the last; the moment a lens shows less than the wire does is the moment to stop scraping.
# FOR 40K-FT VIEW (STORY & INFRASTRUCTURE)
# --- START EDITING-IN ON 1ST TURN ---
# ! python scripts/articles/lsa.py -t 1 --reverse --fmt dated-slugs # <-- ROLLING PIN that gives the 40K foot book-spine view of book-ore (only works for me because of local-only git repo)
# ~/repos/nixos/autognome.py # <-- You wake up in the morning and your Tooling & Instrumentation folds out of you like Inspector Gadget.
# init.lua # <-- Those gadgets are made easy-to-use through nifty keyboard shortcuts (but ya gotta learn vim).
# GLOSSARY.md # <-- Like the back of a J.R.R. Tolkien book, there's kooky new terms to know.
# flake.nix # <-- Here is my hardware. Here is my state. Put on your sandbox. And please recreate. (Infrastructure as Code / IaC)
# prompt_foo.py # <-- THIS system
# foo_files.py # <-- main ROUTER
# requirements.in # <-- We've "pinned" everything but still want a flexible Python Data Science virtualenv.
# pyproject.toml # <-- How this is a citizen of the Python "pip install" ecosystem
# __init__.py # <-- Version info
# --- END EDITING-IN ON 1ST TURN ---
# scripts/articles/lsa.py # <-- 2ND BRAIN: Search external memory with `rgx`, `rgxc` & `posts` Blogging for Hackers Jekyll-compatible.
# OPTIONAL ACTUATORS (cheap and good to include to expand the AI's capabilities)
# cli.py # <-- Catch-all actuator for PyPI envs, Python anchoring, MCP tool-call (plus alternatives) and **kwargs like wrapping for CLI
# scripts/xp.py # <-- Transforms host OS copy-paste buffer player-piano music into context-payload.
# scripts/ai.py # <-- How I constantly use local AI to write git commit messages with `m` alias.
# scripts/crawl.py # <-- Feel free to ask for something to be crawled and included in the next turn.
# scripts/weblogin.py # <-- Lets the user "warm up" the cache for their web logins at their leisure on a profile that persists.
# scripts/webclip_2_markdown.py # <-- Surprisingly important program.
# MISCELLANEOUS (rare to include but sometimes critical)
# scripts/foo_cartridge.py # Needs description
# scripts/foo_replay.py # Needs description
# release.py # <-- How everything ends up where it does (GitHub, PyPI, etc.)
# imports/voice_synthesis.py # <-- The wand can talk to you
# imports/ascii_displays.py # <-- Where all the ASCII Art lives
# scripts/release/version_sync.py # <-- Needs to be wrapped into release.py and eliminated, I think.
# --- Under this line is were you paste what the AI gives you ---
# --- We call it context but it's really just the right-hand ---
# --- blast-radius of the "probes" to make this all science. ---
# Carry-over as the important work-in-progress parts of the project here just
# like above but not as long-standing overarching to the framework but rather
# for the current hot spots actively being worked on.
# STICKBUG & MOTHER CAT KATA (WORKING ON THE CHAPTER)
# Always include these with whatever connector
# scripts/sources_menu.py
# scripts/connectors/README.md
# scripts/connectors/wallet.py
# scripts/connectors/botify.py
# scripts/connectors/confluence.py
# scripts/connectors/gmail.py
# scripts/connectors/gsc.py
# scripts/connectors/jira.py
# scripts/connectors/mcp.py
# scripts/connectors/mcp_warm.py
# scripts/connectors/sheets.py
# scripts/connectors/slack.py
# --- START THIS DISCUSSION ---
# Get things started here! Guess at what context should be included.
# If you get it wrong, you're just wasting 1-turn because the AI will help.
# Un-comment lines, add lines with absolute-path filenames or `! ` commands.
# Context 1
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# Context 2
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# imports/voice_synthesis.py
# tools/scraper_tools.py
# prompt_foo.py
# assets/trails/public_walk.yaml
# ! .venv/bin/python -B -c 'exec("import ast, contextlib, io\nfrom pathlib import Path\np = Path(\"scripts/mother_cat.py\")\nf = next(n for n in ast.parse(p.read_text()).body if isinstance(n, ast.AsyncFunctionDef) and n.name == \"_ride_steps\")\nassert isinstance(f.body[-2], ast.If) and ast.unparse(f.body[-2].test) == \"captured\"\ntail = compile(ast.Module(body=f.body[-2].body, type_ignores=[]), str(p), \"exec\")\nfor intro, handoff in ((True, True), (True, False), (False, True), (False, False)):\n calls = []\n ns = dict(intro=intro, captured=[], archive={\"previews\": []}, skipped=[], disclosed=True, _decant=lambda *a: \"fixture\", _complete_preview=lambda *a, **k: handoff, _narrate=lambda *a: calls.append(a))\n with contextlib.redirect_stdout(io.StringIO()):\n exec(tail, ns)\n assert len(calls) <= int(intro)\n if calls:\n assert calls[0][1] is True and ((\"withheld\" in calls[0][0]) == (not handoff))\n assert \"saved\" not in calls[0][0] and \"copied\" not in calls[0][0]\n print(\"intro=%s handoff=%s closing=%s\" % (intro, handoff, len(calls)))\n")'
# flake.nix
# init.lua
# Context 3
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# assets/trails/public_walk.yaml
# flake.nix
# ! .venv/bin/python -B -c 'import ast,json; from pathlib import Path; t=ast.parse(Path("scripts/mother_cat.py").read_text()); names={n.name for n in t.body if isinstance(n,ast.FunctionDef)}; print("private_plan_helpers="+str(len(names & {"_private_plan_path","_edit_private_plan"}))); d=json.loads(Path("assets/trails/public_walk.yaml").read_text()); print("public_stops="+str(len(d["stops"]))); conflicts=[p for lane in ("Notebooks/Playground/trails","Notebooks/Shared/trails","assets/trails") if (p:=Path(lane)/"plan.yaml").exists()]; assert not conflicts,"plan is already a name in an existing trail lane"; print("plan_name_conflicts=0")'
# ! bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
# ! bash -c 'set -euo pipefail; system=$(LD_LIBRARY_PATH="" nix eval --impure --raw --expr builtins.currentSystem); hook=$(LD_LIBRARY_PATH="" nix eval --impure --no-eval-cache --raw ".#devShells.$system.quiet.shellHook"); test -n "$hook"; printf "%s\n" "$hook" | bash -n; printf "%s\n" "$hook" | .venv/bin/python -B -c "import sys; lines=sys.stdin.read().splitlines(); print(\"quiet_hook_syntax=ok plan_aliases=\"+str(sum(line.strip().startswith(\"alias plan=\") for line in lines)))"'
# Context 4
# foo_files.py
# walk
# assets/installer/mck.sh
# scripts/mother_cat.py
# scripts/walk.py
# scripts/walk_cartridge.py
# assets/trails/public_walk.yaml
# flake.nix
# ! rg -n --glob '!foo_files.py' --glob '!prompt.md' --glob '!data/**' 'public_walk\.yaml|\.yaml|JSON subset of YAML|json\.loads' walk assets/installer scripts flake.nix | head -80
# ! .venv/bin/python -B scripts/walk.py --trail assets/trails/public_walk.yaml >/dev/null && printf 'planner_current_format=ok\n'
# scripts/walk_compile.py
# Context 5
foo_files.py
walk
assets/installer/mck.sh
scripts/mother_cat.py
scripts/walk.py
scripts/walk_compile.py
scripts/walk_cartridge.py
assets/trails/public_walk.json
! .venv/bin/python -B -c 'from pathlib import Path; from scripts import walk; c=[Path("assets/trails/public_walk.yaml"),Path("assets/trails/public_walk.json")]; p=[x for x in c if x.exists()]; assert len(p)==1,p; t=walk.load_trail(p[0]); s=Path("scripts/walk_compile.py").read_text(); print("canonical="+p[0].name+" default="+walk.DEFAULT_TRAIL.name+" stops="+str(len(t["stops"]))+" compiler_json="+str('\''stem + ".json"'\'' in s))'
! bash -n assets/installer/mck.sh && printf 'launcher_syntax=ok\n'
! rg -n 'public_walk\.(yaml|json)|plan\.(yaml|json)|<stem>\.(yaml|json)' assets/installer/mck.sh scripts/mother_cat.py scripts/walk.py scripts/walk_compile.py scripts/walk_cartridge.py | head -60
# --- END `adhoc.txt` TEMPLATE ---
3: Patches: (the one change between the readings)
$ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(nix) pipulate $ patch
(nix) pipulate $ app
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/mother_cat.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'assets/installer/mck.sh'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk_compile.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk_compile.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk_compile.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk_cartridge.py'.
✅ DETERMINISTIC PATCH APPLIED: Successfully mutated 'scripts/walk_cartridge.py'.
(nix) pipulate $ d
diff --git a/assets/installer/mck.sh b/assets/installer/mck.sh
index ee21894c..3c460e8b 100644
--- a/assets/installer/mck.sh
+++ b/assets/installer/mck.sh
@@ -124,6 +124,7 @@ if [ -z "$TRAIL_NAME" ] && [ "$_tpl_trail" != "$_ph_trail" ]; then
fi
TRAIL_NAME="${TRAIL_NAME:-public_walk}"
TRAIL_NAME="$(basename "$TRAIL_NAME")"
+TRAIL_NAME="${TRAIL_NAME%.json}"
TRAIL_NAME="${TRAIL_NAME%.yaml}"
if ! printf '%s' "$TRAIL_NAME" | grep -qE '^[a-z][a-z0-9_]*$'; then
echo "Error: trail name must match ^[a-z][a-z0-9_]*\$ -- got '$TRAIL_NAME'" >&2
@@ -382,6 +383,10 @@ if [ "$TRAIL_NAME" = "plan" ]; then
fi
for TRAIL_DIR in $TRAIL_SEARCH_DIRS; do
[ -z "$TRAIL_PATH" ] || break
+ if [ -f "$TRAIL_DIR/${TRAIL_NAME}.json" ]; then
+ TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.json"
+ break
+ fi
if [ -f "$TRAIL_DIR/${TRAIL_NAME}.yaml" ]; then
TRAIL_PATH="$TRAIL_DIR/${TRAIL_NAME}.yaml"
break
@@ -403,7 +408,7 @@ if [ -z "$TRAIL_PATH" ]; then
# under it while four YAMLs sat in assets/trails. Guard the directory
# AND neutralize the pipeline; either alone is enough, both is cheap.
[ -d "$TRAIL_DIR" ] || continue
- ls "$TRAIL_DIR"/*.yaml 2>/dev/null | sed 's#^# #' >&2 || true
+ ls "$TRAIL_DIR"/*.json "$TRAIL_DIR"/*.yaml 2>/dev/null | sed 's#^# #' >&2 || true
done
exit 1
fi
@@ -412,7 +417,7 @@ fi
echo "Trail resolved: $TRAIL_PATH"
# --- EXPORTS FILE (2026-09-05): the same derivation the rider runs ---------
# bookmark_import.py writes <name>.exports.sh beside <name>.walk.md and
-# walk_compile.py puts <name>.yaml beside both, so the file a trail needs is
+# walk_compile.py puts <name>.json beside both, so the file a trail needs is
# a function of the trail's own path. Explicit --exports=PATH wins and a miss
# is an ERROR, because the human named it; the sibling is next and a miss is
# silence, because nothing promised it. A relative path resolves from the
@@ -422,9 +427,11 @@ echo "Trail resolved: $TRAIL_PATH"
# satisfied. The rider loads the VALUES, environment over file, and is the
# verdict; this ring stays a SUBSET of it, names and never verdicts, exactly
# as the url_env ring already is. The line prints only when a file resolved.
+TRAIL_STEM="${TRAIL_PATH%.json}"
+TRAIL_STEM="${TRAIL_STEM%.yaml}"
EXPORTS_PATH="$EXPORTS_OVERRIDE"
-if [ -z "$EXPORTS_PATH" ] && [ -f "${TRAIL_PATH%.yaml}.exports.sh" ]; then
- EXPORTS_PATH="${TRAIL_PATH%.yaml}.exports.sh"
+if [ -z "$EXPORTS_PATH" ] && [ -f "$TRAIL_STEM.exports.sh" ]; then
+ EXPORTS_PATH="$TRAIL_STEM.exports.sh"
fi
EXPORTS_DECLARED=""
if [ -n "$EXPORTS_PATH" ]; then
@@ -438,7 +445,7 @@ if [ -n "$EXPORTS_PATH" ]; then
echo "Exports resolved: $EXPORTS_PATH ($EXPORTS_COUNT name(s) declared; the rider loads them, environment wins)"
fi
# The trail declares its own url_env names; read them from the trail. Trails
-# are the JSON subset of YAML 1.2, so json.load is correct here.
+# are JSON, so json.load is the exact parser for the authoring format.
# ZERO VARIABLES IS A VALID ANSWER NOW. A stop may carry a literal url instead
# of a url_env, so a whole trail can legitimately name nothing. The leading OK
# token is what separates "the file parsed and there were none" from "the file
@@ -466,7 +473,7 @@ if [ -n "$MISSING" ]; then
echo " export $VAR=\"https://...\"" >&2
done
echo " Set them and re-run. The trail names them; this script does not guess." >&2
- echo " Or put them in ${TRAIL_PATH%.yaml}.exports.sh (the shape bookmark_import.py writes), or name a file with --exports=PATH." >&2
+ echo " Or put them in $TRAIL_STEM.exports.sh (the shape bookmark_import.py writes), or name a file with --exports=PATH." >&2
exit 2
fi
# --- The ride needs the pinned chromium and the shell's LD_LIBRARY_PATH.
diff --git a/scripts/mother_cat.py b/scripts/mother_cat.py
index e384627e..0a750608 100644
--- a/scripts/mother_cat.py
+++ b/scripts/mother_cat.py
@@ -140,16 +140,16 @@ INTRO_NOTICE = (
def _private_plan_path():
"""One local scratch itinerary; resolution is read-only and never falls back."""
- path = Path.home() / ".local" / "state" / "pipulate" / "plan.yaml"
+ path = Path.home() / ".local" / "state" / "pipulate" / "plan.json"
resolved = path.resolve()
if path.is_symlink() or resolved.is_relative_to(REPO_ROOT.resolve()):
- raise walk.TrailError("plan.yaml must be outside the workshop, not a symlink")
+ raise walk.TrailError("plan.json must be outside the workshop, not a symlink")
if any((parent / ".git").exists() for parent in resolved.parents):
- raise walk.TrailError("plan.yaml must not live inside a Git worktree")
+ raise walk.TrailError("plan.json must not live inside a Git worktree")
if path.exists():
info = path.stat()
if not path.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
- raise walk.TrailError("plan.yaml must be a private regular file (0600), not a hard link")
+ raise walk.TrailError("plan.json must be a private regular file (0600), not a hard link")
return path
@@ -159,6 +159,15 @@ def _edit_private_plan():
path = _private_plan_path()
path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+ legacy = path.with_suffix(".yaml")
+ if not path.exists() and legacy.exists():
+ if legacy.is_symlink():
+ raise walk.TrailError("legacy plan.yaml must not be a symlink")
+ info = legacy.stat()
+ if not legacy.is_file() or info.st_nlink != 1 or info.st_mode & 0o777 != 0o600:
+ raise walk.TrailError("legacy plan.yaml must be a private regular file (0600), not a hard link")
+ os.replace(legacy, path)
+ print(f"Migrated private plan to {path}", flush=True)
if not path.exists():
raw = walk.DEFAULT_TRAIL.read_bytes()
with tempfile.NamedTemporaryFile(dir=path.parent, prefix=".plan-", delete=False) as stream:
@@ -201,7 +210,7 @@ def _intro_eligible(trail_path, trail=None):
path = Path(trail_path)
if not path.is_absolute():
path = REPO_ROOT / path
- if path.resolve() != REPO_ROOT / "assets" / "trails" / "public_walk.yaml":
+ if path.resolve() != REPO_ROOT / "assets" / "trails" / "public_walk.json":
return False
trail = walk.load_trail(path) if trail is None else trail
return (tuple(stop.get("url") for stop in trail["stops"]) == INTRO_URLS
@@ -1172,7 +1181,7 @@ def main(argv=None):
parser.add_argument("--disclose", metavar="CAPTURES_MD",
help="write a private review-text disclosure; no browser or clipboard")
parser.add_argument("--plan", action="store_true",
- help="seed once and edit the private plan.yaml; never ride")
+ help="seed once and edit the private plan.json; never ride")
parser.add_argument("--plan-path", action="store_true",
help="read-only: print the existing private plan path or refuse")
args = parser.parse_args(argv)
diff --git a/scripts/walk.py b/scripts/walk.py
index 689faf12..0386cf11 100644
--- a/scripts/walk.py
+++ b/scripts/walk.py
@@ -1,8 +1,8 @@
#!/usr/bin/env python3
"""Mother Cat trail planner, Car A: strict dry-run and no actuation.
-Trail files use the JSON subset of YAML 1.2. That keeps this car stdlib-only,
-duplicate-key-checkable, and still valid YAML. There is deliberately no
+Trail files use JSON. That keeps this car stdlib-only, duplicate-key-checkable,
+and explicit about the syntax humans are editing. There is deliberately no
browser, voice, shell, or adhoc.txt mutation path in this file.
"""
@@ -20,7 +20,7 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
# authenticated stops, and a newcomer's first contact was a KeyError on an
# environment variable they had never heard of. Default to the walk that needs
# no credential; make expert mode cost keystrokes.
-DEFAULT_TRAIL = REPO_ROOT / "assets" / "trails" / "public_walk.yaml"
+DEFAULT_TRAIL = REPO_ROOT / "assets" / "trails" / "public_walk.json"
# THE EXPERT TRAIL, named here rather than implied by being the default --
# discoverability used to rest entirely on this line pointing at it:
# mothercat assets/trails/first_context.yaml (Jira + Botify + Gmail, auth)
diff --git a/scripts/walk_cartridge.py b/scripts/walk_cartridge.py
index f319e341..f3b44587 100644
--- a/scripts/walk_cartridge.py
+++ b/scripts/walk_cartridge.py
@@ -88,7 +88,7 @@ identical archive bytes, forever, which is what makes content addressing work.
USAGE
-----
- python scripts/walk_cartridge.py seal assets/trails/*.yaml
+ python scripts/walk_cartridge.py seal assets/trails/*.json
python scripts/walk_cartridge.py verify data/walks/<sha256>/walk.zip
python scripts/walk_cartridge.py show data/walks/<sha256>/walk.zip
@@ -117,7 +117,7 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
# bytes for EVERY trail, including trails with zero direct URLs, so every
# cartridge sealed under v1 is invalidated. data/ is gitignored, so nothing
# tracked or published breaks. Re-seal with
-# .venv/bin/python scripts/walk_cartridge.py seal assets/trails/*.yaml
+# .venv/bin/python scripts/walk_cartridge.py seal assets/trails/*.json
# Re-sealing WRITES A NEW content-addressed cartridge under a new digest. It
# does not upgrade the old one, which stays on disk and stays red until pruned.
# v3 (2026-09-02): the consent surface gained optional_url_envs, and url_envs
diff --git a/scripts/walk_compile.py b/scripts/walk_compile.py
index 9df71a82..4e063aa8 100644
--- a/scripts/walk_compile.py
+++ b/scripts/walk_compile.py
@@ -31,8 +31,8 @@ is ever handed to a YAML parser, so a brace-wrapped value is simply a literal
string, and it dies downstream at a named field check rather than being
silently coerced into a nested map.
-WHAT IT WRITES: <stem>.yaml BESIDE the surface -- the JSON subset of YAML 1.2
-that walk.py accepts UNMODIFIED. The output path is a pure function of the
+WHAT IT WRITES: <stem>.json BESIDE the surface -- ordinary JSON that walk.py
+accepts UNMODIFIED. The output path is a pure function of the
input path, so a collision is unrepresentable and re-compiling is idempotent.
CONTENT-ADDRESSED artifacts live under data/ (data/walks/<sha256>/walk.zip,
where the path IS the identity). NAME-ADDRESSED artifacts live beside their
@@ -418,7 +418,7 @@ def main(argv=None):
print("frontmatter name " + repr(trail["name"]) + " does not match the "
"file stem " + repr(stem) + ".", file=sys.stderr)
print("One identity all the way through: <stem>" + SUFFIX
- + " compiles to <stem>.yaml and the trail inside is named "
+ + " compiles to <stem>.json and the trail inside is named "
"<stem>.", file=sys.stderr)
return 2
@@ -447,7 +447,7 @@ def main(argv=None):
file=sys.stderr)
return 2
- out_path = surface.parent / (stem + ".yaml")
+ out_path = surface.parent / (stem + ".json")
problem = _ignored_or_outside(out_path)
if problem:
print("COMPILE REFUSED reason=not_ignored")
(nix) pipulate $ m
📝 Committing: chore: Migrate trail.json to standard JSON format
[main 96b7d103] chore: Migrate trail.json to standard JSON format
5 files changed, 37 insertions(+), 21 deletions(-)
(nix) pipulate $ git push
Enumerating objects: 19, done.
Counting objects: 100% (19/19), done.
Delta compression using up to 48 threads
Compressing objects: 100% (10/10), done.
Writing objects: 100% (10/10), 1.39 KiB | 1.39 MiB/s, done.
Total 10 (delta 8), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (8/8), completed with 8 local objects.
To github.com:pipulate/pipulate.git
a94acc85..96b7d103 main -> main
(nix) pipulate $
And this:
(nix) pipulate $ git mv assets/trails/public_walk.yaml assets/trails/public_walk.json
(nix) pipulate $
And now I can test:
(nix) pipulate $ plan
Migrated private plan to /home/mike/.local/state/pipulate/plan.json
Private plan: /home/mike/.local/state/pipulate/plan.json
Edit the URLs and guidance. Save and quit with Esc, :wq, Enter.
Plan valid. Type walk plan to try it; type plan to edit it again.
Custom walks keep CAPTURE at each stop and DECANT before the summary handoff.
(nix) pipulate $
Yep, plan.json is what loads to edit. And now we make sure it opens the right
page and uses the updated wording:
(nix) pipulate $ walk plan
Trail resolved: /home/mike/.local/state/pipulate/plan.json
CAPTURE saves each page. DECANT asks before saving a summary or copying it.
Choose a walk:
1 Practice - hear the steps; no pages open.
2 Start the walk - open the pages.
q Exit (Enter also exits).
Choice: 2
Riding trail 'public_walk' -- 3 stop(s).
This walk opens three pages. You do not need to click anything. At each page, return here and wait for the CAPTURE prompt. Type CAPTURE and press Enter.
Missing phoneme from id map: ̩
==================================================================
THIS WALK: public_walk -- 3 stop(s)
==================================================================
stops, in order the_word, the_receipt, the_two_pages
it opens directly https://Pipulate.com/, https://npvg.org/walk/2/, https://npvg.org/walk/3/
names as runnable scripts/connectors/noop.py
browser profile 'default' (persistent=True, headless=False)
==================================================================
CAPTURE saves each stop locally; captures may include account details.
DECANT authorizes a checked preview file and a clipboard attempt.
Preview in workshop: data/decant-preview.md (private; replaced on save).
Declining or failing checks leaves any previous preview unchanged.
Nothing is uploaded automatically. The preview is trimmed.
Review before sharing; checks can miss sensitive data.
==================================================================
--- Stop 1/3: the_word ---
I'll open page one (Pipulate). When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter.
Opening the browser; waiting for the page...
When the page you want is ready, type CAPTURE and press Enter.
Any other response aborts without capturing artifacts.
CAPTURE> CAPTURE
LOCAL ARCHIVE /home/mike/repos/pipulate/data/captures/walk-r7zs1nco/captures.md (directory 0700, file 0600)
Captured. final_url=https://pipulate.com/ artifacts=12
ADVANCE -> next stop.
--- Stop 2/3: the_receipt ---
I'll open page two. When it is ready, return here. At the CAPTURE prompt, type CAPTURE and press Enter.
Opening the browser; waiting for the page...
^C ARCHIVE STATUS partial
Local archive file line for context.md or adhoc.txt:
/home/mike/repos/pipulate/data/captures/walk-r7zs1nco/captures.md
Review locally before compiling; raw bytes are not a safe disclosure.
WALK ROUTER unchanged: this run did not complete with captures.
Any existing adhocwalk.txt still selects an earlier completed run.
Traceback (most recent call last):
[Lots of stuff deleted from me interrupting it]
KeyboardInterrupt
^C
(nix) pipulate $
Okay, yeah that’s witnessed. It’s going to be rough doing all this with JSON but at least it’s not as jarring as saying YAML and showing JSON anymore, and this article was longer than I wanted but ChatGPT is right. The message is clear, easy to remember and good:
- walk
- plan
- walk plan
How much more ideal could it be for introducing this system to people? I still need to check on the Mac (still this morning). It’s 5:45 AM and I want everything I need to still do this morning to be done in the next hour or so, so that I can leave around 7 or 7:30 AM this morning for the office.
4: Prompt: Close the JSON PLAN rename and dismount this article.
Read this compile’s Manifest-listed live receipts first.
This turn should have made one compatibility-preserving rename transaction:
- assets/trails/public_walk.yaml -> public_walk.json
- scripts/walk.py names JSON honestly and DEFAULT_TRAIL points to public_walk.json
- scripts/mother_cat.py uses ~/.local/state/pipulate/plan.json
- the first
planafter the patch migrates an existing safe 0600 plan.yaml to plan.json with os.replace rather than reseeding it - introductory authorization keys off public_walk.json
- assets/installer/mck.sh prefers .json but continues reading legacy .yaml trails
- exports sibling derivation works for either suffix
- scripts/walk_compile.py now writes
.json - scripts/walk_cartridge.py examples seal filesystem .json trails
- the sealed cartridge’s internal trail.yaml member and schema v3 remain unchanged
Do not expand this into renaming historical trails, first_context.yaml, foo_files.py receipts, or the cartridge member. Legacy .yaml compatibility is deliberate.
The corrected source probe should straddle from: canonical=public_walk.yaml default=public_walk.yaml stops=3 compiler_json=False to: canonical=public_walk.json default=public_walk.json stops=3 compiler_json=True
Launcher Bash syntax must remain green.
Reconcile those receipts with the operator report below. Specifically verify whether:
planmigrated the existing private file to plan.json without losing the prior edit- bare
walkresolved public_walk.json walk planresolved the private plan.json- a REAL custom walk was ridden through CAPTURE + DECANT, if the operator did it
If the first three are witnessed, the rename is complete. If the real custom ride is also witnessed, the PLAN article’s local acceptance is complete and should dismount immediately.
Do not keep polishing. Carry forward the independent preview/checkword acceptance and any unwitnessed public-distribution step separately.
The next article is Botify work: use the capture/receipt machinery plus short Unix-like connector commands to investigate SpeedWorkers mini-rules by hand. Do not start that implementation in this turn.
Operator report:
Terminal transcript:
5: Deliverables: Usable system. Usable description of system. Usable demo of system.
Hop off the ride. This ride’s stated goal is reached — dismount. This is the NOTARY BEAT: the ride ends here, is witnessed here, and is sealed here. Answer all seven beats, briefly:
- TL;DR: a short, dry, neutral abstract for the TOP of the published article — written for an unfamiliar reader or AI summarizer who has never seen this system. No hype, no insider handles unexplained.
- VERIFY: restate the goal from the top of this article and confirm (or deny) it was met, citing THIS compile’s receipts, not memory. Name any ignition this ride required that never fired – an AFTER tap taken without one is a stale BEFORE wearing the AFTER’s label.
- BANK: name everything that graduates — rule, earmark, todo, pin — as SEARCH/REPLACE patch cars against raw source present in THIS context (Target line inside the fence, one car per commit story), deletions included. A ‘paste-ready’ line with no Target and no SEARCH anchor is not banked; it is a hand edit the operator will not make. These BANK cars are the ONLY patches a dismount emits.
- DANGLING: what carries forward unbanked? One line each, no essays.
- SEED: the adhoc.txt lines (and TODO_SLUGS if narrative context is needed) for the next ride’s first compile.
- CLOSING: a closing summary for the BOTTOM of the article — the final take-away, tied to the book’s larger arc where it fits naturally, never forced. Storytelling over inventory.
- NOTARIZE: the artifact of record is the cartridge THIS compile writes after this payload is assembled, so its name is not in your context and you must not guess one. Attest the FINGERPRINT instead: this Manifest’s wc -c line, its receipt count, and the newest receipt’s date – pure functions of the bytes the cartridge seals. Close with one line the operator completes after the compile: Deed: foo-________.zip (ls -t foo-*.zip | head -1) The seal is the signature; the fingerprint is how the deed is found.
FINALITY: after beat 6, this discussion is CLOSED. Emit NO five-car train, NO probes, NO patches beyond the BANK cars of beat 2, and NO next-turn prompt beyond the SEED lines in beat 4. Any reader or model encountering this article later should treat it as a finished, notarized document — an archive entry, not an open thread.
ChatGPT 6 Medium: Context verified.
1. VERIFY
The article’s goal was to finish the small usability gaps around the default walk, then leave behind a simple, reusable authoring loop suitable for demonstration before moving on to Botify work.
Met, with the explicitly carried-forward exceptions below.
The compile-side rename straddle landed exactly: canonical=public_walk.json default=public_walk.json stops=3 compiler_json=True, and the launcher still passes Bash syntax.
The human-side ignition fired too. plan migrated the existing private file to /home/mike/.local/state/pipulate/plan.json and reopened it successfully. walk plan then resolved that same private JSON file, preserved the edited first URL/guidance, entered a real ride, and successfully CAPTUREd stop one. The run was deliberately interrupted while opening stop two, so no claim of full custom DECANT is warranted.
One bookkeeping seam remains at dismount: commit 96b7d103 contains the code changes, but the subsequent git mv assets/trails/public_walk.yaml assets/trails/public_walk.json was still a working-tree rename when this compile ran. Telemetry shows that exact 100%-similar rename outside HEAD. The BANK commit below should absorb it rather than opening another ride.
No required ignition was skipped: plan was the rename/migration ignition, and it fired.
2. BANK
One thing graduates: the ride receipt. It records the JSON naming repair, the private-plan migration, the compact three-command grammar, and—critically—the partial rather than imaginary full custom ride.
The already-performed git mv rides in this same BANK commit.
Target: foo_files.py
[[[SEARCH]]]
# --- START RECEIPTS (newest first; cap 20 lines; a line pushed past the cap is deleted, never moved -- git and the rolling pin are the archive) ---
[[[DIVIDER]]]
# --- START RECEIPTS (newest first; cap 20 lines; a line pushed past the cap is deleted, never moved -- git and the rolling pin are the archive) ---
# 2026-09-16 dismount THE WALK / PLAN / WALK PLAN LOOP (commit 96b7d103 plus the canonical-file rename banked by this dismount): the newcomer grammar reduced to three commands -- walk teaches, plan edits one private OOB itinerary, walk plan rehearses or runs it. The private authoring loop was witnessed in Neovim before this ride; this ride made its format truthful: public_walk.yaml -> public_walk.json, DEFAULT_TRAIL and introductory authorization followed it, walk_compile.py now emits <stem>.json, the launcher prefers JSON while retaining legacy .yaml compatibility, exports derive across either suffix, and the sealed cartridge's internal trail.yaml member stayed unchanged. LIVE source receipt: canonical=public_walk.json default=public_walk.json stops=3 compiler_json=True; launcher syntax green. Human ignition witnessed plan migrating the existing 0600 ~/.local/state/pipulate/plan.yaml to plan.json without reseeding, then walk plan resolving that exact path with the prior edited URL/guidance intact. REAL custom ride branch witnessed through stop-one CAPTURE at artifacts=12; operator interrupted stop two, archive remained partial, router unchanged, so full custom CAPTURE+DECANT is explicitly UNWITNESSED. Also carried: macOS check, public-distribution acceptance, and the independent preview/checkword acceptance. JSON is knowingly rougher to hand-edit than real YAML; the narrower win is that the filename no longer lies about the grammar.
[[[REPLACE]]]
The existing NOTARY FINGERPRINT TODO does not graduate: this compile still does not provide the requested wc -c measurement, exactly the mismatch that TODO records.
3. DANGLING
- Full real private
walk plan: stops 2–3 plus final DECANT remain unwitnessed. - macOS
plan/walk planacceptance remains unwitnessed. - Public installer/distribution of the new
planworkflow remains unwitnessed. - Independent preview/checkword acceptance remains separate and unfinished.
- NOTARY FINGERPRINT instrumentation still lacks its requested
wc -cfield. - The compile reports one stale topological reference to
assets/trails/public_walk.yaml; do not reopen this article for it.
4. SEED
First compile of the next ride: Botify by hand, SpeedWorkers mini-rules, shortest useful path.
foo_files.py
cli.py
scripts/sources_menu.py
scripts/connectors/README.md
scripts/connectors/wallet.py
scripts/connectors/botify.py
! .venv/bin/python cli.py mcp-discover
! .venv/bin/python scripts/connectors/botify.py --help | head -80
5. CLOSING
The useful result is smaller than the machinery that produced it.
The Notary Beat and Future Work
A newcomer does not need to learn Mother Cat, cartridges, consent surfaces, source lanes, or the history of the trail schema. They can learn the whole visible loop as three verbs:
Walk. Plan. Walk your plan.
That is the right shape for the larger argument of the book. The complicated part stays underneath, where it belongs: the browser records what happened, the human controls when evidence is captured and handed off, and the files remain inspectable afterward. The interface gets shorter while the receipt trail gets stronger.
The JSON correction matters for the same reason. Calling JSON “YAML” was technically defensible and experientially wrong. The system now says what it is. That is a small example of the broader discipline here: when the abstraction and the evidence disagree, move the abstraction.
The next article can finally stop improving the recorder and use the recorder—Botify, SpeedWorkers, Jira, and short command receipts assembled into context for an AI to inspect.
6. NOTARIZE
This compile’s Manifest lists 3 live command receipts.
The newest banked receipt is dated 2026-09-15.
The requested Manifest wc -c fingerprint is UNRECORDED in this compile. The Summary reports 696,247 UTF-8 bytes, but the standing NOTARY TODO explicitly says not to substitute the Summary size for an unrecorded wc -c measurement, so I do not.
Fingerprint: wc-c=UNRECORDED | live-receipts=3 | newest-banked-receipt=2026-09-15
Deed: foo-________.zip (ls -t foo-*.zip | head -1)
Discussion closed.
Book Analysis
Ai Editorial Take
What stands out in this entry is the psychological shift from treating configuration files as opaque templates to treating them as direct extensions of personal intent. By addressing the cognitive dissonance of parsing JSON through a YAML extension, the text demonstrates a rare commitment to interface honesty.
🐦 X.com Promo Tweet
Master repeatable local automation with three simple commands. Teach with walk, customize your private itinerary with plan, and execute checks with confidence. https://mikelev.in/futureproof/walk-plan-run-replayable-workflows/ #Automation #LocalFirst #AI
Title Brainstorm
- Title Option: Walk, Plan, and Run: Designing Replayable AI Workflows
- Filename:
walk-plan-run-replayable-workflows.md - Rationale: Directly captures the new three-verb mental model while emphasizing the replayable nature of the tools.
- Filename:
- Title Option: The Three-Command Authoring Loop for Local Automation
- Filename:
three-command-authoring-loop.md - Rationale: Focuses on the operational mechanics of moving from a general tutorial to a customized private workflow.
- Filename:
- Title Option: Naming Truth and Replayable Workflows
- Filename:
naming-truth-replayable-workflows.md - Rationale: Highlights the epistemological choice of matching file formats to actual parsing behavior rather than misleading extensions.
- Filename:
Content Potential And Polish
- Core Strengths:
- Clear articulation of a minimal, memorable three-command user interface.
- Pragmatic approach to format naming and parser reality.
- Strong emphasis on local-first isolation and data privacy.
- Suggestions For Polish:
- Streamline the technical dialogue around trailing configuration edges.
- Ensure the distinction between public tutorials and private plans remains crisp.
Next Step Prompts
- Prepare the architecture for integrating Botify connector calls directly into the custom walk loop.
- Design the next testing phase around automated script hardening and receipt verification.