Context
The current `demo/demo.sh` walkthrough has three related UX gaps that make it harder to follow as a teaching tool:
1. No per-command intent narration. Steps 7–9 fire 5+ `basectl` commands back-to-back with only a step header. A learner watching the scroll cannot tell which output belongs to which concept. The demo prints the command (with `$`) but nothing that says why it is being run.
2. No before/after activation contrast. Step 4 shows `basectl check` failing pre-activation as a diagnostic. Step 5 sources `activate.sh`. But the demo never re-runs `check` post-activation to show it passing. A learner must infer the connection rather than observe it.
3. Sparse closing. The walkthrough ends with `printf 'base-demo walkthrough complete.\n'`. There is no summary of the Base concepts demonstrated, no pointer to next steps (docs, banyanlabs, deeper commands), and no call to action.
Bonus: `capture_command` output lacks a visual separator. The function prints the `$ command` line, then the output appears immediately below with no blank line or separator, making it hard to see where command invocation ends and output begins.
Scope
- Add a one-line `printf` before each command in the inspection and representative-environment steps that states what the command demonstrates (e.g. "Checking that all required environment variables are set...").
- After the activation step, re-run `basectl check` and show it passing as an explicit confirmation of the before/after contrast.
- Add a closing block that lists the Base manifest fields exercised and suggests `docs/representative-environment.md` and `banyanlabs` as next steps.
- Add a blank line between `capture_command`'s `$ ...` line and the output it prints.
- Update `tests/demo_test.bats` for any new output assertions.
Validation
- `./demo/demo.sh --non-interactive` output includes per-command explanations and a closing summary.
- Post-activation `basectl check` output appears in the walkthrough and is confirmed healthy.
- `./tests/validate.sh`
Context
The current `demo/demo.sh` walkthrough has three related UX gaps that make it harder to follow as a teaching tool:
1. No per-command intent narration. Steps 7–9 fire 5+ `basectl` commands back-to-back with only a step header. A learner watching the scroll cannot tell which output belongs to which concept. The demo prints the command (with `$`) but nothing that says why it is being run.
2. No before/after activation contrast. Step 4 shows `basectl check` failing pre-activation as a diagnostic. Step 5 sources `activate.sh`. But the demo never re-runs `check` post-activation to show it passing. A learner must infer the connection rather than observe it.
3. Sparse closing. The walkthrough ends with `printf 'base-demo walkthrough complete.\n'`. There is no summary of the Base concepts demonstrated, no pointer to next steps (docs, banyanlabs, deeper commands), and no call to action.
Bonus: `capture_command` output lacks a visual separator. The function prints the `$ command` line, then the output appears immediately below with no blank line or separator, making it hard to see where command invocation ends and output begins.
Scope
Validation