docs(demos): add a docs/demos folder, move the guided demo into it, and add the remote-sandbox walkthrough - #199
Merged
pdettori merged 2 commits intoSep 1, 2026
Conversation
The repo root held exactly one walkthrough, `serverless-harness-demo.md`, while every other documentation genre already had a home under `docs/` — `adrs/`, `specs/`, `notes/`, `plans/`. A second demo was about to land, so the choice was to add another root-level markdown file or to give demos the folder the other genres have. This does the latter. Rewrites the one relative link inside the moved file (`deploy/knative/README-kind.md` -> `../../deploy/knative/README-kind.md`) and the single inbound reference from the root README. `git grep` confirms there were no others. No prose changes: this commit is a pure move, so it can be reviewed by inspecting the rename and the two link edits alone. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
The remote-sandbox path had a one-command script (`make demo-remote-sandbox`, rossoctl#195) and a reference section in `README-worker.md`, but nothing you could drive by hand. Those two serve different purposes: a script optimizes for an unattended pass/fail, while performing the claim in front of someone needs the commands separated so each can be explained as it runs. This adds that walkthrough, in the acts-and-callouts shape the existing demo uses. Every command was executed end-to-end against `fc757a7` before being written down, and the outputs shown are real. Three things surfaced only by running it: - **The harness ksvc carries three `ANTHROPIC_*` `secretKeyRef` entries.** `kubectl set env` does not work on a Knative `Service` at all, and a blind env-array replace flattens `valueFrom` to an empty string — after which the model call fails looking exactly like an unreachable endpoint. The flip step therefore shows those three entries *before* touching them and upserts by name with jq, mirroring `lib.sh`'s `set_ksvc_env`. Act 2d explains the whole patch, since a copy-paste demo is precisely where that trap gets sprung. - **`docker logs` does not show individual execs** — the worker logs its attach and then only anomalies (dedup, req-id reuse, dropped terminal frames). Recorded under "Notes and limits" so nobody promises a live exec log they cannot deliver. - **A planted marker beats the OS fingerprint as a closer.** Act 3 has you write a random string into the container by hand, confirm the in-cluster pool returns ENOENT for that path, then ask the leaf to read it. A verdict on `/etc/os-release` can be argued with; a string the audience watched you create cannot. Also adds `docs/demos/README.md`, matching the index the other `docs/` genres already carry (`adrs/`, `specs/`, `plans/`). It states the demo/smoke-test/spec distinction, since the overlap is the thing most likely to send a future contributor to the wrong genre, and records the structural conventions both demos follow so the next one does not have to reverse-engineer them. Refs rossoctl#174, rossoctl#198. Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Gives demos the folder every other documentation genre in
docs/already has, and adds ahand-driven walkthrough of the remote-sandbox path.
What this does
git mv serverless-harness-demo.md docs/demos/— it was the only walkthrough at the reporoot while
adrs/,specs/,notes/andplans/all live underdocs/. Rewrites the onerelative link inside it and the single inbound reference from the root README;
git grepconfirms there were no others.
docs/demos/remote-sandbox-demo.md— a sandbox outside the cluster, zero inboundrules, executing a leaf's tool calls. Same acts-and-callouts shape as the existing demo.
docs/demos/README.md— matching the indexadrs/,specs/andplans/carry.Split into two commits: the move is mechanical and reviewable on its own, and no intermediate
state has a broken link.
Why a hand-driven demo when
make demo-remote-sandboxexistsThey serve different purposes. The script optimizes for an unattended pass/fail. Performing the
claim in front of someone needs the commands separated so each can be explained as it runs — and
needs to say what to look at and which trap the step defends against, which an assertion
cannot. The new doc points at the script as its scripted sibling, and
docs/demos/README.mdrecords the demo / smoke-test / spec distinction so the next contributor picks the right genre.
Every command was executed before being written down
Run end-to-end against
fc757a7; the outputs in the doc are real. Three things surfaced only byrunning it, none of which were visible from reading
demo-remote-worker.sh:The harness ksvc carries three
ANTHROPIC_*secretKeyRefentries.kubectl set envdoesnot work on a Knative
Serviceat all, and a blind env-array replace flattensvalueFromto anempty string — after which the model call fails looking exactly like an unreachable endpoint. The
flip step shows those three entries before touching them and upserts by name with jq, mirroring
lib.sh'sset_ksvc_env. Act 2d explains the whole patch, because a copy-paste demo is exactlywhere that trap gets sprung.
docker logsdoes not show individual execs — the worker logs its attach and then onlyanomalies (
session/loop.go: dedup, req-id reuse, dropped terminal frames). Recorded under"Notes and limits" so nobody promises a live exec log they can't deliver.
A planted marker is a better closer than the OS fingerprint. Act 3 has you write a random
string into the container by hand, confirm the in-cluster pool returns ENOENT for that path, then
ask the leaf to read it back:
A verdict on
/etc/os-releasecan be argued with; a string the audience watched you createcannot.
The doc also carries forward the two defenses that make the proof non-vacuous — the zero-Running-pods
structural guard and the both-directions fingerprint — with the
select-sandbox.tscandidates = [...pods, ...grpcRecs]reasoning stated inline, since a reader who skips that willhappily demo the wrong backend.
Verification
git grep)Rwith the intra-file link fixDocs-only; no code, scripts or CI touched.
Refs #174, #198.
Assisted-By: Claude Code