docs: how to publish a library to mcpp-index, and the generated= path asymmetry

[Sunrisepeak]

Two gaps found by walking the chain end to end while publishing libxpkg 0.0.48 (consumed by openxlings/xlings 2026.8.5.1).

1. Publishing a library was undocumented

mcpp publish and mcpp emit xpkg appear in --help and nowhere in docs/. 09 covers releasing mcpp itself, 02 covers mcpp pack bundling an application — neither says how a library becomes something [dependencies] can name.

New 10 - Publishing a Library to mcpp-index writes down the chain (tag → gitcode mirror → index entry → artifact → consumer bump) and, more usefully, the four places it fails quietly:

• gitcode answers HEAD with 401. An asset checked with HEAD reads as broken; one checked by existence alone can still be the wrong bytes. GET it and cmp against the GitHub tarball.
• An entry in one platform block resolves on that platform and fails on the others as "no such version" — which reads like a typo in the consumer's manifest, not a missing index row.
• The index is an artifact, not a git clone. Merging to main publishes nothing until publish-artifact.yml runs, and clients hold a TTL on top of that. Hand-editing a cached pkgs/** does nothing.
• A seeded local copy of the unreleased version is indistinguishable from a published one — and it is exactly what is still sitting there when the publish silently failed. Delete it before believing a cold resolve.

It also documents the seeding recipe for testing against an unreleased version (the build sandbox is network-isolated, so file:// and 127.0.0.1 index URLs cannot be fetched), and warns against the registry-pruning one-liner that deletes data/xpkgs — xpkgs sits at depth 2 and is not named data, so a careless second pass takes the whole ~800 MB payload store with it.

2. generated= resolves against two different roots

The directive table said "relative to the project root". That is true for the root package; the dependency section separately says a dependency's build.mcpp resolves the same path against MCPP_OUT_DIR. Both statements are correct and the combination is a trap: a library plays both roles, so no relative path is right in both.

Writing into MCPP_OUT_DIR and emitting the bare filename works as a dependency and fails at the root with:

error: build.mcpp declared generated source 'foo.cppm' but it does not exist after the run

Documents the form that is correct in both roles (write to MCPP_OUT_DIR, emit out.string().c_str() — mcpp::out_dir() is always absolute), and adds one line the examples were missing: a generated .cppm module interface works, since .cppm goes through the same scan as any other source.

Both files updated in docs/ and docs/zh/, and both READMEs indexed.