Skip to content

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 into
rossoctl:mainfrom
pdettori:docs/demos-folder-remote-sandbox
Sep 1, 2026
Merged

docs(demos): add a docs/demos folder, move the guided demo into it, and add the remote-sandbox walkthrough#199
pdettori merged 2 commits into
rossoctl:mainfrom
pdettori:docs/demos-folder-remote-sandbox

Conversation

@pdettori

@pdettori pdettori commented Sep 1, 2026

Copy link
Copy Markdown
Member

Gives demos the folder every other documentation genre in docs/ already has, and adds a
hand-driven walkthrough of the remote-sandbox path.

What this does

  1. git mv serverless-harness-demo.md docs/demos/ — it was the only walkthrough at the repo
    root while adrs/, specs/, notes/ and plans/ all live under docs/. Rewrites the one
    relative link inside it and the single inbound reference from the root README; git grep
    confirms there were no others.
  2. Adds docs/demos/remote-sandbox-demo.md — a sandbox outside the cluster, zero inbound
    rules, executing a leaf's tool calls. Same acts-and-callouts shape as the existing demo.
  3. Adds docs/demos/README.md — matching the index adrs/, specs/ and plans/ carry.
  4. Root README — both demos referenced, plus a pointer at the folder.

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-sandbox exists

They 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.md
records 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 by
running it, none of which were visible from reading demo-remote-worker.sh:

  • 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 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, because a copy-paste demo is exactly
    where that trap gets sprung.

  • docker logs does not show individual execs — the worker logs its attach and then only
    anomalies (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:

    verdict=FLAGGED
    The pattern tuscan-lentils-29765 is present in the file /tmp/proof.txt as a secret marker.
    

    A verdict on /etc/os-release can be argued with; a string the audience watched you create
    cannot.

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.ts
candidates = [...pods, ...grpcRecs] reasoning stated inline, since a reader who skips that will
happily demo the wrong backend.

Verification

Check Result
All 23 relative links in the four touched files resolve
Stale references to the old root path none (git grep)
Rename detected by git (not add+delete) yes — R with the intra-file link fix
DCO sign-off on both commits present

Docs-only; no code, scripts or CI touched.

Refs #174, #198.

Assisted-By: Claude Code

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>
@pdettori
pdettori merged commit 4030f4b into rossoctl:main Sep 1, 2026
11 checks passed
@pdettori
pdettori deleted the docs/demos-folder-remote-sandbox branch September 1, 2026 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant