[Feat]: Ship examples/README.md in wheel; optional skillware examples --sync fallback #226

Feature Description

Improve offline / pip-only support for the examples index used by skillware examples and skillware list --examples.

Problem today

• PyPI wheel ships skillware + skills/ only (MANIFEST.in grafts skills; examples/ is excluded).
• CLI resolves examples/README.md from a checkout/cwd walk, else fetches from GitHub raw (raw.githubusercontent.com/.../examples/README.md) — added in 0.3.9.
• Pip-only users outside a repo often hit: Could not load examples/README.md from the repo or GitHub when raw CDN is blocked, slow, or flaky (even if github.com works in a browser).
• Example scripts (examples/*.py) are never in the wheel; only the index is needed for CLI listing — scripts stay on GitHub for copy/run.

Proposed solution (phased)

Phase A (preferred, minimal) — Ship examples/README.md only in the wheel:

• Add packaging hook (MANIFEST.in and/or pyproject.toml package-data) so the index installs under a stable path discoverable by _examples_readme_path() (e.g. adjacent to package root or under skillware resources).
• Update skillware/cli.py to check the installed copy before GitHub fetch.
• Keep GitHub fetch as fallback when wheel copy is missing (dev editable installs, old wheels).
• No new optional extra required for Phase A (zero-config for pip install skillware).

Phase B (fallback if Phase A is insufficient) — skillware examples --sync:

• Subcommand or flag to download/update the examples index (and optionally all examples/*.py) from a pinned GitHub ref (tag matching installed version or main).
• Cache under user data dir (e.g. %APPDATA%/skillware/ or ~/.cache/skillware/examples/).
• Subsequent skillware examples / list --examples reads cache first.
• Useful when wheel index is stale vs docs, or Phase A packaging path is awkward on some platforms.

Out of scope

• Shipping full docs/ tree (skillware[docs]) — docs remain on site/GitHub/clone.
• Shipping all example scripts in the default wheel (too large; optional [examples] extra could be a future RFC).

Rationale

• User expectation: After pip install skillware, skillware examples should work without cloning the repo or relying on raw GitHub CDN.
• Current design gap: 0.3.8 briefly shipped index in wheel; 0.3.9 moved to GitHub fetch for pip installs — correct for freshness, fragile for network policy.
• Minimal surface: examples/README.md is the CLI’s only hard dependency for listing; ~few KB, versioned with the release, no new runtime deps.
• Complements existing flow: Checkout users unchanged; GitHub fallback remains for edge cases.
• Does not affect skill identity: Registry skills, manifest, issuer, and card.json are unchanged — packaging/CLI resolution only.

Implementation Idea

Phase A — ship index in wheel

1. Packaging

   • MANIFEST.in: include include examples/README.md (or graft with prune of examples/*.py if safer).
   • Or add skillware package-data / importlib.resources bundle for examples_index/README.md.
   • Verify with pip wheel + inspect sdist/wheel contents in CI or release checklist.

2. CLI (skillware/cli.py)

   • Extend _examples_readme_path() candidates:
     • Installed wheel path (via importlib.resources.files("skillware") or Path(__file__).parent.parent / "examples" / "README.md" once laid out).
     • Existing: package_root parent, cwd walk.
   • Order: local checkout → wheel bundled index → GitHub raw.
   • Tests: mock no cwd file, assert wheel path used; keep existing GitHub fallback tests.

3. Docs

   • docs/usage/cli.md — note pip installs include bundled examples index; GitHub fallback when missing.
   • CHANGELOG.md [Unreleased] under Changed or Fixed.

Phase B — examples --sync (only if Phase A insufficient)

skillware examples --sync          # refresh index (+ optional scripts)
skillware examples --sync --scripts  # optional: download indexed .py files

• Fetch from https://raw.githubusercontent.com/ARPAHLS/skillware/v{version}/examples/... or release tarball.
• Write to cache dir; _examples_readme_path() checks cache after wheel, before GitHub.
• Exit codes + dim stderr on failure (mirror existing CLI patterns).
• Document network requirement explicitly for --sync.

Options considered

Acceptance criteria

• pip install skillware → skillware examples compliance/tos_evaluator works offline (no GitHub).
• skillware list --examples works offline with bundled index.
• Checkout / editable install behavior unchanged.
• GitHub fetch still works when bundled file absent.
• tests/test_cli.py covers wheel/local resolution path.
• CHANGELOG.md updated; cli.md updated.
• (Phase B) --sync documented and tested with mocked HTTP.

Scope note
Touches pyproject.toml, MANIFEST.in, skillware/cli.py, tests/test_cli.py, docs/usage/cli.md — not loader/skill bundles.