docs: close the framework onboarding gap

[codeforester]

Summary

Add a documentation index, framework resource links, a copyable minimal Click consumer with a runnable example/test, and repository-specific contributor skills.

Issue

#20

Validation

• uv run --extra dev pytest -q — 35 passed, 2 skipped.
• git diff --check.

Notes

Merge after #18 and #19; the documentation index links to both new guides.

[codeforester]

Multi-angle review of this PR (closes the framework onboarding gap). Four findings, ranked by severity:

1. docs/README.md links to two files that don't exist on this branch. The new doc index links why-base-cli.md and should-i-use-base-cli.md, but this PR is branched directly from main (merge-base 2de6b83) and doesn't include either file — I confirmed docs/why-base-cli.md/docs/should-i-use-base-cli.md only exist on sibling PRs #31 and #32, not here. If #33 merges before (or without being rebased onto) #31/#32, main ships a documentation index with two dead links, and there's no link-checker in CI to catch it. This likely resolves cleanly if #31/#32 merge first and #33 rebases onto them — but as filed right now it isn't self-contained.

2. skills.md prescribes commands inconsistent with the rest of the repo. It instructs uv run --extra dev pytest -q and uv run --extra dev tests/package.sh, but every other place that documents these steps — CI (tests.yml, release-package.yml), docs/release-process.md, and the existing package.sh/validate.sh themselves — invokes them as plain python -m pytest / ./tests/package.sh, with no uv anywhere else in the repo. An agent following skills.md's uv run recipe could get a locally-green result that doesn't match how CI actually resolves/runs the suite.

3. Two skills.md sections lost content in the rewrite with no replacement. The old "Development workflow" bullet included a cleanup step (remove worktree/branch after merge) that isn't present in the new "Development workflow" section — the only cleanup language left in the repo is release-specific and won't be consulted for an ordinary PR. Separately, the old "Domain workflow" bullet (demo-specific checks/expectations agents "should not have to rediscover") was replaced by "Product boundary" (an architectural ownership rule, not a verification checklist) — there's no successor telling an agent what demo-specific behavior to verify before calling a change safe.

4. The same "framework resources" paragraph is now duplicated across three files (README.md, docs/README.md, docs/use-in-your-project.md) with no cross-reference, and skills.md restates guidance from CONTRIBUTING.md (branch-naming/worktree convention) and docs/release-process.md (guarded release steps) instead of linking to them — which contradicts skills.md's own stated rule two lines away ("Link to external guidance or copy only repo-owned instructions"). Each copy is now a separate place that can go stale independently.

Minor/lower-confidence, not blocking: tests/test_minimal_starter.py's env-isolation (HOME/USERPROFILE/BASE_CLI_CACHE_DIR) duplicates and slightly diverges from the existing run_installed_command helper in test_readme_examples.py (missing LOCALAPPDATA), though BASE_CLI_CACHE_DIR already takes priority in base_cli/paths.py so this isn't currently reachable.