docs(examples): add multi-agent notepad demo

[zredlined]

Summary

Adds a runnable example that demonstrates a multi-agent shared notepad: isolated Codex agents run in separate OpenShell sandboxes, write markdown notes to a scoped GitHub path, and a synthesis agent reads those notes to produce a final summary.

The demo uses Codex as the agent runtime and GitHub as the durable notes backend, but the user-facing concept is a shared notepad for sandboxed agent coordination rather than a general-purpose agent memory system.

Related Issue

No issue yet. This PR captures the working demo for review.

Changes

• Adds examples/multi-agent-notepad/demo.sh to launch parallel worker sandboxes and a synthesis sandbox.
• Adds a scoped GitHub REST policy template for writes under runs/<run-id>/**.
• Adds worker and synthesis prompt templates for a markdown notepad workflow.
• Adds a concise README with setup, repo safety guidance, credential model, expected output, and network policy summary.
• Keeps sandbox uploads limited to the demo runner and prompt payload so workers do not inherit host logs or previous worker artifacts.

Testing

• mise run pre-commit passes locally; attempted after installing missing local tools, but the Rust test sandbox_create_keeps_sandbox_with_forwarding failed because port 8080 is already in use by the local gateway/Docker process
• bash -n examples/multi-agent-notepad/demo.sh
• Extracted generated sandbox runner and ran bash -n
• Parsed policy.template.yaml with Ruby YAML
• git diff --check -- examples/multi-agent-notepad
• markdownlint-cli2 over the new README and prompt templates, after isolating unrelated untracked local docs
• mise run pre-commit partial pass before the local port conflict: license check, markdownlint, Mermaid lint, Python format/lint/typecheck/tests, Helm lint, Rust format/check all completed successfully
• E2E smoke test with DEMO_AGENT_COUNT=2 against disposable private repo zredlined/openshell-codex-memory-demo-20260427-102752
• Verified generated agent-1.md, agent-2.md, and summary.md exist through the GitHub Contents API
• Verified temporary demo sandboxes and providers were cleaned up

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[carltonawong]

This is a useful demo shape. One small thing I would consider adding to the notepad contract is a bit more state metadata per note, even if the backing store stays plain markdown.

For example: source_agent, observed_at, status (active, stale, superseded, consumed), and needs_verification. In multi-agent runs the hard part is often not just sharing notes, it is keeping the synthesis agent from treating yesterday's scratch context as current authority.

That would keep the example simple while showing the boundary between durable notes and live coordination state.

[zredlined]

This is a useful demo shape. One small thing I would consider adding to the notepad contract is a bit more state metadata per note, even if the backing store stays plain markdown.

For example: source_agent, observed_at, status (active, stale, superseded, consumed), and needs_verification. In multi-agent runs the hard part is often not just sharing notes, it is keeping the synthesis agent from treating yesterday's scratch context as current authority.

That would keep the example simple while showing the boundary between durable notes and live coordination state.

@carltonawong Good feedback. Our focus here was to keep it brutally simple, and to build a more detailed reference example with different personas and collaboration between agents. Will plan to add the state metadata concepts in there. Thanks

[carltonawong]

Thanks, that makes sense. Keeping the first demo brutally simple is the right call.

The reference example feels like the better place to show status / observed_at / needs_verification, especially because it teaches downstream agents which notes are current operating state vs old scratch context.

[h-network]

For the record:
parallel agents coordinating via markdown on git branches was proposed in NVIDIA/NeMo-Agent-Toolkit#1793 (2026-03-12), together with the lifecycle, abort, signed-results, and crash-recovery primitives. The proposal was rescoped to "Redis Integration for Orchestration" on 2026-03-12. The original proposal describes the production application: architect + N teams, per-team branches, ANNOUNCEMENT.md / REPLY.md over Redis pub/sub.

[carltonawong]

Thanks for the pointer. That proposal is a useful adjacent reference.

The part I’d still want any branch/markdown coordination pattern to make explicit is what state is durable evidence vs current authority: last verified result, abort/crash reason, and what the receiving agent has to recheck before acting.

[h-network]

@carltonawong Your follow-up listed three specifics under "durable evidence vs current authority": last verified result, abort/crash reason, and what the receiving agent has to recheck before acting. Those map to the lifecycle / signed-results / abort / crash-recovery primitives specified in NVIDIA/NeMo-Agent-Toolkit#1793. If you consider that proposal "adjacent" rather than the precursor, which public, citeable proposal does specify them in the form you'd view as precursor?

[carltonawong]

I don’t think #1793 is the precursor to this suggestion. This PR is a markdown/GitHub notepad demo, and my comment was about lightweight note-level metadata so synthesis agents don’t confuse stale scratch context with current authority. #1793 proposes a Redis-backed orchestration/runtime layer with lifecycle, abort, pub/sub, signed-results, and crash-recovery primitives. Those are adjacent concerns, but not the same proposal.

[h-network]

@carltonawong NVIDIA/NeMo-Agent-Toolkit#1793 issue body, verbatim:
"The architect breaks it into scoped tasks, writes an ANNOUNCEMENT.md for each team, pushes branches, and notifies teams via Redis. Each expert reads its task, implements it in its own directory, pushes a branch with a REPLY.md, and signals done."

PR #991 README, verbatim:
"separate coding agents communicate by reading and writing scoped markdown notes... The GitHub repository is the shared notepad and coordination layer."

Both: N agents writing markdown to scoped git locations, single synthesizer/architect reading them, no inter-agent communication. The runtime concerns are conceded as in #1793. The markdown coordination layer is also in #1793 — quoted above.

Which technical distinction between (ANNOUNCEMENT.md/REPLY.md over per-team branches) and (agent-N.md/summary.md over scoped paths) makes them adjacent rather than the same primitive?

[carltonawong]

@h-network I think this has drifted a bit beyond what I was trying to comment on.

My original note was just a small observation about the notepad demo in this PR — specifically around adding lightweight metadata so a synthesis agent can distinguish stale vs current notes.

I wasn’t trying to propose or compare full coordination models like #1793.

Appreciate the discussion though — helpful context.