docs: give first-time users a README where they actually land

[memtomem]

Summary

A first-time user who installs from PyPI and runs toolgraph example init
lands in a directory of three unexplained files. docs/ is excluded from the
sdist, so the beginner guide is not on their disk, and the only guidance is the
CLI's one-line "Next: cd ... && toolgraph init". The generated directory now
carries its own README.

Checking the beginner guide against what the commands actually print turned up
claims that do not survive being run, so this fixes those too:

• "Every authored edge includes a local evidence pointer" was false. The
  packaged fixture had no provenance at all, so unbacked-edges listed all
  three authored edges right after the guide said it would not. The fixture now
  carries provenance on every edge. The fixture and both guides also say what
  an empty audit does and does not prove: the demo tools return strings and
  touch no file, so the READS/WRITES effects are synthetic and their evidence
  cites the fixture that defines them. An empty result means every edge has a
  pointer, never that a claim is true.
• The falsifiable version is now exact. Deleting a data_access provenance
  block and re-ingesting names that edge. Deleting a grant's provenance does
  not, because grants are audited separately under --include-grants.
• Two of the five suggested audits return a row on purpose. unsafe-tools
  reports publish_note reaching draft-publish-deny as a violation, and
  blast-radius reports the path it covers. Read right after the empty-audit
  discussion, that looks like the quickstart broke. All three documents now say
  which two return a row and why.
• The shared-backend section ran docker compose and copied .env.example,
  neither of which ships with the package or the generated quickstart. It is
  now an explicitly repository-based, optional path with a clone step.
• The gateway step read as mandatory, contradicting the README's statement
  that memtomem-stm is not a required dependency. It is now optional, and
  policy compile is described as printing metadata about the bundle rather
  than the bundle.

Also adds examples/README.md mapping each servers/governance input to the
script that consumes it and what it needs, a Documentation URL so the guide
is reachable from the PyPI sidebar, and a CONTRIBUTING pointer to the guide.

The last two commits are packaging, not documentation: adding
examples/README.md broke scripts/verify-artifacts.sh, because Hatchling
matches an unanchored include pattern at any depth and the bare README.md
entry pulled in the examples one. Every pattern in the sdist allowlist is now
anchored to the project root, including the directory entries, which carried
the same reach in both directions.

Validation

Local release gate from docs/releasing.md, every step passing:

uv lock --check                      Resolved 104 packages
uv sync --frozen --group dev --extra ladybug     resolved
uv run ruff check .                  All checks passed
scripts/audit-dependencies.sh runtime / extras / dev
                                     No known vulnerabilities
uv build && uv run twine check dist/*            both PASSED
scripts/verify-artifacts.sh dist 0.1.0           51 entries, all allowlisted
uv run pytest -q                     585 passed

Beyond the gate, the user-facing path was exercised end to end rather than
read. The wheel was installed with [ladybug] into a disposable venv and every
command in the new README was run with that venv's executable:

• unbacked-edges and --include-grants both return []; so do
  unmapped-tools, orphan-policies, drift, destructive-unsafeguarded and
  annotation-contradictions.
• unsafe-tools vibe-coder and blast-radius draft-publish-deny each return
  the publish_note path, which is what the guides now say to expect.
• eligible-tools returns read_note eligible and publish_note rejected with
  DENY_VIOLATION and its policy path; policy compile writes the bundle and
  prints its digest.
• Deleting the WRITES provenance and re-ingesting makes unbacked-edges name
  that one edge and no other, which is the guide's claim. The command prints
  JSON objects; projecting each to (edge_type, src) gives exactly
  [('WRITES', 'policy-gateway::publish_note')].
• toolgraph/quickstart/README.md is present in both the wheel and the sdist;
  examples/README.md is in neither, after the packaging fix.

Not exercised locally, delegated to CI: the artifact-smoke matrix across the
OS and Python versions this machine cannot reproduce, and the minimum-MCP
install job, which is a single Ubuntu job and could be run here. ci.yml also
runs the same artifact verifier on every pull request, so the allowlist this
branch touches is enforced remotely rather than only at release time.

Notes for the reviewer

One user-visible behavior change. Filling in the fixture's provenance drops
read_note from risk 0.4 to 0.0, because _risk_score is first-match and
the unbacked-edge case no longer applies. Risk is serialized into the bundle,
so the quickstart's bundle digest changes. The DENY policy is untouched and
publish_note is still rejected at 1.0.

A decision that could have gone the other way. The data-flow evidence
pointers cite policy_gateway_server.py, not the manifest, even though the
tools do not really perform that I/O. Pointing them at themselves would have
satisfied the audit while explaining nothing, so they name the fixture that
defines the modelled effect and say in the string that it is synthetic.

Deliberately out of scope: an example notebook. There is no documented
stable Python onboarding API (toolgraph/__init__.py exports only
__version__, and no module defines __all__), so a notebook would wrap the
same CLI commands the guide already shows and would rot the way 0.0.1
quickstart copies did. Worth revisiting only if a public Python API is curated.

No runtime code changed. The only non-documentation edits are the packaged
fixture, pyproject.toml, and the example init test, which pinned the exact
three-file listing and now checks four files plus non-blank evidence on each
authored binding.

No separate regression test for the packaging fix. ci.yml runs
scripts/verify-artifacts.sh on every pull request and ci-required depends
on that job, and examples/README.md now reproduces the regression on its own
if the anchoring is reverted. A unit test asserting the patterns start with a
slash would restate the implementation rather than the invariant.

🤖 Generated with Claude Code

https://claude.ai/code/session_013xkxVWdqNAXjy5Au52MzU6