docs: bring skills and crate READMEs back in line with main

[jeswr]

Requested by Jesse · project thread

Summary

Before: after this week's merges, many skills/*/SKILL.md files and crate READMEs described APIs, publish status and build membership that no longer match main. Several ZK/MPC/policy recipes did not compile against current signatures, unpublished crates showed crates.io badges and "0.1" install lines, published crates were described as publish = false, and some docs named files, tests and flags that have moved or never existed.

After: every skill and crate README was checked against main's public API (types, signatures, features, CLI flags, HTTP behaviour, file paths, publish/default-member status) and the drift is fixed with minimal edits. Docs only; no code changes.

How: each claim was checked against source; Rust snippets in the ZK, MPC, trust, VC, policy, fedplan skills were compiled in scratch crates against the workspace; README doctests re-run for every edited README pulled in via include_str!.

Main groups of fixes:

• Publish status (build(release): crates.io-ready publish set (12 crates + sparq-spargebra fork) #6663/ci(release): v0.1.4 release path — soft optional artefacts, 28-crate publish set, self-gating crates.io flip #6646): sparq-jsonld, sparq-engine-serialize, sparq-engine-service are now published (docs said publish = false); unpublished crates (sparq-mcp, -solid, -geo, -rsp, -text, -vectors, -nlq, -arrow, -reason-el, -reason-ql, …) lose crates.io/docs.rs badges and "0.1" / cargo add install lines. sparq-cli/sparq-server READMEs note which features the crates.io package strips.
• default-members (build(workspace): make the focused core the default build (default-members) #6649): sparq-introspect, sparq-canon and sparq-substrate membership claims corrected.
• Recipes that no longer compiled: zk-query-proofs (prover_toml_for, verify_manifest, revoke_prover_toml, AttestedStatusRef::clear, new ProofManifest fields), mpc (non-exhaustive MpcError match), usage-control-policy (Session fields), genai-retrieval (named_graph returns Option), sparq-engine-service quickstart.
• Behaviour changes this week: CLI reason summary to stderr (fix(cli): keep reason's summary off stdout when writing the closure #6641), dump streaming (docs(performance): sparq-server/cli: wire write_turtle_streaming into CONSTRUCT/DESCRIBE (sq-0kq6k) #4313), substrate's float-comparison boundary fixed by fix(numeric): value xsd:float at f32 on comparison paths; correctly-rounded Dec::f64 #6671, VC proof-option validation (fix(vc): validate credential proof options before signing and verification #6589) and EdDSA proof config (fix(vc): match W3C EdDSA RDF proof configuration #6585), LWS per-resource WAC on notifications (feat(sparq-lws-core): sparq-lws-core: wire per-resource WAC into notification subscribe/receive (the #6388) and the reclaim race (fix(store): reclaim superseded and deleted blobs at commit instead of after the sweep #6675), engine DP planner now default-on when compiled, budget-truncated JSON streams (fix(engine): nested registry scopes, double SERVICE fetch, budget-truncated streams, LOAD blank nodes #6655).
• Stale names and paths: vector-search (MetaType/Nature, provable_disjoint_pairs), gpu-kernels half-open range, inference n3 re-exports, moved engine test paths, JSON-LD and SHACL floors, --solid-authz-trust (env only), non-existent see-also skills, a stray tool-call fragment at the end of genai-retrieval.
• Router: skills/SKILL.md now lists trust-graph.
• Model tags: leftover model tags and "Model:" notes are removed from skills and crate READMEs (ci: lean CI, drop the bot fleet, heavy suites nightly, one required check #6673 retired the convention).
• SERVICE quickstart (sparq-engine-service): now uses with_service_egress_policy(true, …), so only the listed host is dialled; with_service_egress_allow only blocks private addresses.
• One Cargo source: the EL/QL and Arrow recipes take every collaborating crate from git, so Dict/Query/QueryResult types match.
• site/specs/trust-expression.typ: the last github.com/jeswr/sparq link outside site/src (link only). The other remaining hits are historical records or the site guard's own pattern list.

JSON-LD writing is documented as it is on main (the #6674 rewrite is not merged).

Closes #6327

Base gate (always required)

• cargo build --workspace succeeds. (docs-only change)
• cargo clippy --workspace --exclude sparq-py --all-targets -- -D warnings is clean. (no Rust source touched)
• The code this PR touches is formatted.
• cargo test passes for every crate this PR touches: cargo test --doc for the 19 crates whose edited README is a doctest (algos, arrow, engine, geo, hdt, introspect, jsonld, mcp, nlq, policy, reason, reason-el, reason-ql, rsp, server, shacl, solid, text, vectors), all ok.

Targeted re-evaluation (check the rows that apply to your change)

• Public API: this PR is the skill/README sync itself.
• Other rows: not applicable (no source changes).

Ratchets and conventions

• I did not lower any conformance / perf / coverage ratchet.
• No hard-coded performance numbers added to markdown (check-no-perf-numbers.py --enforce: 0 findings).
• check-readme-template.py --enforce: 0 deviations across 65 READMEs; check-skill-frontmatter.py: 50/50 valid.
• If this change makes a doc statement false (in either direction), I updated that doc in the same change.

Security

• Docs only; no security-sensitive code touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MUY53os6oSKvmT9gCqdzud

---

Generated by Claude Code

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head a06049c153ce. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [medium] Keep collaborating crates on the same Cargo source — skills/inference/SKILL.md:366
   The quickstart installs sparq-core from crates.io, but the new EL dependency uses a local path and pulls its own path-based sparq-core. Following both instructions produces distinct Dict types, so classify_graph(&mut dict, ...) fails to compile. The new git-only Arrow commands have the same problem for applications using the documented crates.io engine: their QueryResult cannot be passed to Arrow’s exporters.

   Provide complete dependency recipes using one source for all collaborating crates, as the updated wrapper and GenAI recipes already do. Apply this to both the inference and Arrow instructions.

Requested checks

• Compared changed API references, signatures, CLI flags, crate/package names, features, and examples against the base source; found the dependency-source incompatibility above.
• Checked local Markdown link targets; no newly broken targets found. External links were not live-verified.
• Examples were reviewed statically; compilation and doctests were not rerun in the read-only workspace.

Verdict: Fix the dependency recipes before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head 49f4bd9c3e66. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [medium] SERVICE quickstart does not enforce its advertised host restriction — crates/sparq-engine-service/README.md:29
   The example says only the listed host can be contacted, but with_service_egress_allow installs Mode::DenyPrivate, which permits unlisted hosts resolving to public IPs. An application following this recipe for untrusted queries would still allow SERVICE <https://attacker.example/>, defeating the documented destination restriction. Use with_service_egress_policy(true, …) to enforce the stated policy, or explain that this helper only exempts listed hosts from private-address blocking.

Requested checks

• Checked changed API names, signatures, types, CLI flags, crate/package names, features, and examples against base source. The SERVICE behavior mismatch is reported above.
• Checked package feature stripping against the release script; the documented CLI/server lists match.
• No broken repository-relative links found.
• Compilation and doctests were not rerun because the workspace is read-only; example validation was source-based.

Verdict: Fix the misleading SERVICE security recipe before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head b3a362fb4d96. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [medium] Restore significant () syntax in the examples — skills/javascript-wasm/SKILL.md:473
   Removing () breaks executable recipes: await (await fetch(url)).text returns a function, which loadJsonLdWithContexts rejects instead of receiving context text. At line 477, new Uint8Array(await response.arrayBuffer) produces an empty array for a nonempty response, and new TextDecoder.decode(bytes) throws a TypeError. These failures were reproduced in Node.

   Restore .text(), .arrayBuffer(), and new TextDecoder().decode(bytes). Audit the same removal across the diff: it also corrupts the documented Rust return type into Result<, String> in skills/usage-control-policy/SKILL.md:229, whereas the source returns Result<(), String>.

Requested checks

• Checked substantive API, signature, feature, package, CLI, and behavior changes against the unchanged base source and manifests; the syntax regressions above remain.
• No newly broken repository-relative file links found. External links were not exhaustively checked.
• Reproduced the JavaScript failures; Rust examples and doctests were not recompiled in this read-only checkout.

Verdict: Fix the documented syntax regressions before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head be07d9fcb71c. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [medium] PROV recipe still uses incompatible algebra types — skills/prov-lineage/SKILL.md:218
   The retained dependency selects upstream spargebra, while sparq-prov uses the vendored sparq-spargebra package. Following this recipe produces distinct GraphPattern types, so why_not(&graph, &bgp, &target) fails to compile. Use vendor/spargebra with package = "sparq-spargebra" from the same checkout, or take all collaborating crates from the same git source.

2. [low] Tag cleanup breaks the academic-paper code fence — skills/academic-paper/SKILL.md:252
   The edit joins the closing backticks and the following paragraph onto one line. CommonMark closing fences cannot contain trailing prose, so the Bash block remains open through EOF, swallowing the remaining instructions, including the Stage 5 review gate. Restore the standalone closing fence and put the paragraph after a blank line.

Requested checks

• API and examples: Source verification found the remaining PROV dependency mismatch above. Compilation was not rerun in the read-only workspace.
• Links: Checked 367 repository-relative Markdown targets; none were missing.
• Tag stripping: The merge-base word diff fails the strict “tags/notes only” check: it removes the fence’s newline separation and attribution-associated punctuation, including parentheses at skills/substrate/SKILL.md:134. No other accidental code-token, URL, version-number or list-marker changes were found in the attribution cleanup.

Verdict: Fix the incompatible recipe and broken fence before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head c02cb909ba0b. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

No correctness, security, soundness or design problems found.

Requested checks

• API and examples: Source review found no mismatches in the edited signatures, types, dependency sources, features, CLI behavior or security claims. No newly broken relative file links found. Compilation and external-link reachability were not verified.
• Model stripping: The literal “nothing besides tags/notes” check fails: empty parentheses were also removed at skills/substrate/SKILL.md:134, and adjacent punctuation changed elsewhere. No executable-token, URL, version, list-marker or code-fence corruption found in the cleanup. The separate API documentation edits intentionally change code tokens and commands.

Verdict: Safe to merge based on source review, with compilation and external-link verification outstanding.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head 1a7daf6808aa. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [low] PROV recipe omits required direct dependencies — skills/prov-lineage/SKILL.md:219
   A fresh consumer using this dependency block cannot compile the accompanying example: it imports sparq_core and oxrdf, but neither is declared. Transitive dependencies do not make those imports available. Add sparq-core from the same checkout and a compatible oxrdf dependency; the initial dependency recipe also omits sparq-core.

2. [low] Router retains the retired count-only CLI contract — skills/SKILL.md:21
   The router says query/query-mmap never print bindings and support only --reason/--proof. On the base branch, both emit results by default and accept --format/--count; scripts following this summary will parse the wrong output. Update the summary against emit_query_results in crates/sparq-cli/src/main.rs.

Requested checks

• Both findings are pre-existing drift remaining within the requested documentation scope. Corrected signatures, features and examples were checked against source; compilation was not rerun in the read-only environment. No newly broken local links were found.
• Mechanical word-diff inspection counted 605 removed model tags across 89 files. Removal was not strictly tag-only: adjacent punctuation and empty parentheses were also removed. No accidental code-token, URL, version, list-marker or code-fence damage was found in those removals.

Verdict: Fix the remaining documentation errors before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head 10190e82f5a2. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [low] ZK API reference still gives the obsolete verifier signature — skills/zk-query-proofs/SKILL.md:79
   The API list documents seven arguments for verify_manifest, but the public function in crates/sparq-zk-compose/src/verifier.rs:6101 requires ten. Calling it as documented fails to compile because HolderRegistry, HolderBindingPolicy and EntailmentPolicy are missing. Update this signature to match the corrected verification recipe.

Requested checks

• API and examples: Source checks confirmed the substantive API changes inspected, except for the stale signature above. Checked Cargo dependency and feature references and repository-relative links resolved. Compilation was not rerun in the read-only workspace.
• Model stripping: Mechanically inspected the merge-base word diff: 605 tags removed across 89 files, plus seven Model: notes. The strict “nothing besides tags/notes” condition is not met: adjacent punctuation and empty parentheses were also removed, and bracketed “as-built” notes became parenthesized notes. No accidental loss of code tokens, URLs, versions or list markers, or introduced broken fences, was found.
• Skill frontmatter and README template checks passed.

Verdict: Correct the remaining verifier signature before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head d293d3580e7d. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [low] Router still advertises an unavailable wasm import — skills/SKILL.md:27
   The router describes @sparq-org/sparq/wasm/... as the raw Store import path. However, js/package.json exports only . and ./wasm-node; importing the advertised subpath from an installed package fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Update this summary to reflect the supported imports, as the revised JavaScript skill already does.

2. [low] SHACL router retains incorrect API and build guidance — skills/SKILL.md:32
   This entry still says pre-binding rejection is unimplemented and sparq-shacl has no features or wasm support. The base source exposes validate_strict for pre-binding and ill-formed-shape failures, declares shacl-af, scs and imports, and includes wasm dependency paths. Readers can therefore miss the strict validation entry point or incorrectly rule out browser integration. Reconcile the summary with these public surfaces.

Requested checks

• API/source checks: Found the retained router errors above. Revised recipe signatures and explicit dependency features matched source. Examples were inspected, not compiled.
• Links: No missing repository link targets found; external availability was not checked.
• Tag stripping: The literal “nothing besides tags/notes” condition fails: attribution edits also change brackets and parentheses. The word-diff and code-block comparisons found no accidental code-token, URL, version, list-marker or fence changes attributable to stripping.

Verdict: Correct the remaining router guidance before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head b1b68f2f15b4. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

1. [medium] Router advertises unsupported CLI framing — skills/SKILL.md:18
   The copied description advertises dump … --frame, but cmd_dump implements only --context. Running dump data.ttl turtle jsonld --frame frame.jsonld silently produces ordinary expanded JSON-LD; selecting jsonld-framed exits with an unknown-format error. The skill body correctly identifies CLI framing as planned.

   Remove --frame from both the skill’s frontmatter description and its router entry, or explicitly mark it as planned.

Requested checks

• Description equality: All 37 canonical entries match their referenced YAML description values byte-for-byte after YAML decoding, with no whitespace normalization.
• Coverage: All 38 skill directories are linked. The canonical list covers 37; terminology appears under Maintenance. The additional Solid-host bullet references javascript-wasm again. No links reference nonexistent skill directories.
• Source consistency: The unsupported --frame claim above remains. No other unsupported import paths, crate names, or feature claims found.

Verdict: Correct the CLI framing claim before merging.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head e54329bb1dc4. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

No correctness, security, soundness or design problems found.

Requested checks

• Descriptions: All 37 primary router entries match their skill’s frontmatter description byte-for-byte after YAML decoding.
• Coverage: All 38 skill directories are linked. terminology appears under Maintenance; the additional Solid-host entry references javascript-wasm. Every link resolves.
• Router claims: No unsupported import path, crate name or feature claim found.
• CLI: sparq-cli uses no clap definitions. Verified the documented subcommands, flags and Cargo features against src/main.rs, src/tabular.rs and Cargo.toml; no unsupported CLI capability found. JSON-LD framing is correctly marked as planned, and --help as unavailable.

Verdict: Safe to merge as is.

[jeswr]

🔎 Codex reviewer — gpt-6.1-sol

Automated review by the Codex reviewer (OpenAI gpt-6.1-sol via Codex CLI) of head 3c10a816ea9d. Scope: correctness, security, soundness and design; style nits omitted. A new head gets a fresh review.

Findings

No correctness, security, soundness or design problems found.

Requested checks

• Merge delta: Confirmed that the only commit since e54329b is the main merge. Both conflict resolutions take main’s text, with the MCP model tag stripped; the remaining delta is inherited from main.
• Behavior claims: Confirmed against source. container_list omits unreadable and unstored members. SELECT CSV/TSV/XML serialization streams after query materialization, preserves Content-Length for single-chunk responses, keeps HEAD buffered, and uses writers byte-identical to the buffered serializers.
• Router: All 37 entries match their skills’ frontmatter names and description values byte-for-byte after YAML quote decoding.

Verdict: The PR is safe to merge as is.