docs: extend README adventures (input editing, gates demo, private schema) + Path fix

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC

[IanMayo]

What

Two things in one branch:

1. Type-clean the autocomplete example — wrap the input filename in Path(...) in examples/explore_platform.py, since build_platform_from_file is annotated to take a Path. Removes a Pylance warning in the shipped learning file. (We chose to keep the builder API Path-strict rather than widen it.)

2. Extend the README "Self-guided adventures" — fold in the genuinely-missing hands-on material that the open PLAYGROUND.md proposal (docs: add PLAYGROUND.md hands-on guide #12) had but our README lacked:

   • Adventure 1: edit examples/calculation_input.xml and re-run to watch the validated output change; then break it on purpose (negative/non-numeric BandCount) to see the gate reject it, print the reason, exit non-zero, and write no stale artifact.
   • Adventure 2: show serialize.to_xml(platform) in the REPL — the same object, as XML.
   • Adventure 5 (new): point the CLI at the gitignored private/ real schema (generate/validate/compare against private/ paths), including the caveat that acoustic pipeline imports the committed models so it can't run end-to-end on real models without a reviewed change.

Verification

• python examples/explore_platform.py runs; mypy clean on it.
• ruff check src tests passes; full pytest suite (41 tests) passes.
• Every command and the break-it-on-purpose error output was run end-to-end before documenting. private/ is confirmed gitignored; the section avoids referencing files that don't exist yet.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-03 08:49 UTC