danbri

Tidy a messy SPARQL query into the house style WITHOUT changing what it means, and prove the meaning is unchanged. Use whenever you are cleaning up, reformatting, commenting, or de-duplicating a SPARQL query (e.g. the queries embedded in the api.parliament.uk procedure-browser pages) and need a repeatable methodology plus a checker that confirms the before/after pair is equivalent. Bundles the cleanup rules, a worked before/after example, and `bin/sparql-equiv.sh` — an equivalence checker using Apache Jena ARQ (canonical algebra) plus optional live-endpoint result-set comparison.

Bulk-export the UK Parliament Thesaurus — the SKOS concept scheme used to subject-tag debates, papers, written questions, and other parliamentary records. Crawls the legacy Linked Data API at lda.data.parliament.uk/terms (no SPARQL endpoint exposed for it) into a single N-Quads file split across topical named graphs. Use when a question needs the thesaurus as RDF (e.g. for joining into a local SPARQL store, building a faceted UI, or exporting subject hierarchies). The thesaurus is the canonical subject vocabulary at parliament.uk; pair with `linked-data-api` for the document-level metadata that references these terms.

Research dossier + method for reconciling UK Bills across every surface that records them — the Bills REST API, the UK Parliament Thesaurus (LEG terms), the DDP SPARQL store (ActOfParliament / StatutoryInstrumentPaper), legislation.gov.uk, Wikidata (via QLever), modern Hansard and Historic Hansard (1803–2005), and the Journals of the House. Use when you need to know WHERE a bill (especially a pre-2015 historical one) is recorded, how complete each source is, whether matching them is a SPARQL/ETL job or an AI/fuzzy one, and how to build a bill-identity crosswalk graph (billId ↔ LEG term ↔ Hansard stages ↔ resulting Act ↔ legislation.gov.uk ↔ Wikidata QID). Complements the `bills` skill (which just wraps the live Bills API).

Query the forgetmenot RSS/Atom feed catalogue — a concrete, metadata-rich index of every syndication feed across the UK Parliament web estate (House of Commons Library and House of Lords Library WordPress archives, exposed as <archive>/feed/, plus the first-party Bills API RSS), built by this repo and served on the fpkg demo app at https://fpkg.fly.dev/kgx/feeds. Use when the question is "what RSS/Atom feeds exist for Parliament", to enumerate per-topic / per-type / per-tag / per-author Library feeds with chamber + subject metadata, to track new Library briefings or Bills, or to cross-walk Library subject feeds against a controlled vocabulary (EuroVoc / GEMET) via the skosdex skill. Distinct from `library-feeds` (which wraps the official api.parliament.uk/library-feeds Rails aggregator); this is our own derived catalogue with a richer taxonomy and a live reader UI.

Search and query skosdex (skosdex.fly.dev) — a skills-first index of ~648 openly-licensed SKOS concept schemes (controlled vocabularies / thesauri) from around the world: AGROVOC, EuroVoc, GEMET, LCSH, Getty AAT/ULAN, IPTC NewsCodes, Loterre, Finto/YSO and many more, ~2.5M concepts with cross-vocabulary skos:exactMatch / closeMatch mappings. Two surfaces: a Solr full-text index (the fast, populated search surface) and a SPARQL 1.1 endpoint (Oxigraph) where each scheme is its OWN NAMED GRAPH — the default graph is empty, so SPARQL patterns must use GRAPH ?g { … }. Third-party, NOT UK Parliament. Use when you need to look up a subject term / concept, walk a broader/narrower thesaurus hierarchy, or bridge a term across controlled vocabularies (e.g. tag parliamentary material against EuroVoc or GEMET).

kgx node-flow lib — the canonical implementation of the daisychain / pivcab / studio op-node API. Use when wiring a new chain, adding an op kind, exposing a new SPARQL endpoint, writing tests against the library chain spec, generating a TriG manifest from a chain, or debugging why a saved chain isn't replaying. Read this before touching `demos/parliament-live/web/kgx/lib/*.mjs`, `demos/parliament-live/web/kgx/daisychain/index.html` op-table or starter-list, `bin/kgx.mjs` SPARQL routing, or the LIBRARY iteration tests.

Fetch, parse and recurse XML sitemaps (the Sitemaps 0.9 protocol — sitemap.xml / sitemapindex.xml) for the UK Parliament web presence, enumerate every public page URL (~1.09M across the estate), and track updates via the RSS/Atom feeds. Use when you need the inventory of public web pages rather than structured API records — especially the many pages with NO JSON/REST API (corporate "About"/living-heritage, visiting, get-involved, site-information, Library landing pages, guidance), to know what the wrapped Members/Bills/Hansard/SPARQL facilities do NOT cover. Entry: www.parliament.uk/sitemapindex.xml; publications via www.publications.parliament.uk/sitemap_index.xml (21 child sitemaps, ~1.04M URLs). A cached snapshot, a concrete 918-feed catalogue, a liveness survey, a D3 web-estate map (/kgx/sitemap-tree) and a feed reader (/kgx/feeds) are all committed — see docs/data-state.md. Parses offline from a saved file too. Generic — works on any site's sitemap.

Notes, gotchas and utility recipes for the cloud-platform / container infrastructure this repo uses — fly.io (the fpkg demo app), Docker multi-stage builds bundling RDF / Oxigraph stores, GitHub Actions workflow patterns (dispatch + path triggers + flyctl), and the tiny mobile-only operational reality the repo runs in. Use when you're touching a Dockerfile, a fly.toml, a GHA workflow, or hitting an "it should be easy but…" cloud-tooling surprise.

Run and interpret every test suite in the Factoidal project — W3C conformance (SPARQL 1.1, RDF 1.1/1.2 syntax, rdf-mt, RDF canonicalization, OWL 2), local regression scripts, cross-runtime parity (native/JS/wasm), Apache Jena ARQ comparison probes, running only the suites a diff touches (`tools/affected-tests.sh`), regression-pinning discipline (write the failing test before the fix, confirm it fails for the right reason), and the policy for importing external suites. Use when the user asks to "run the tests", "check conformance", "compare against Jena", to investigate a score change, when landing a bug fix and deciding which regression to write, or before claiming any change is done. Testing (with perf measured separately — see perf-benchmarking) drives everything in this project.

Markdown formatting + prose register for Claude-generated text in this repository — chat replies, design docs, READMEs, PR bodies, commit messages. Two load-bearing rules. (1) Links must be unambiguously clickable — bold/italic emphasis around URLs and link syntax frequently breaks the click target. (2) No sycophantic adjectives — drop "honest", "genuine", "important", "critical", "big picture", "key insight", "headline", and similar candor-performance words. Use whenever generating user-facing markdown that may be rendered in different clients (CLI, web, mobile chat, GitHub).

How Factoidal stores RDF data on disk — the COTTAS/Parquet base file, its 11 sidecars, the durable-UPDATE delta log, the compacted-epoch marker, and the symlink-current versioning layout. Use when asked how data is stored on disk, when adding a new on-disk companion file, when a magic-number/framing question comes up (DLE1/DLB1/DLOG/CEP1/COTD/COTP/COTO/COPO/COTS), when running import/query/compact/serve against a COTTAS store, or when auditing rule

How to write subagent prompts for the Factoidal repo so the agent's work actually lands cleanly. Use whenever you dispatch a subagent with the Agent tool, especially with `isolation: "worktree"`. Two load-bearing rules. (1) Path discipline — agents must use only paths under their worktree, not absolute paths from your prompt context. (2) Post-condition checks — agent must verify its main-worktree footprint is zero before reporting back. Also carries MANDATORY brief inclusions for build-list edits (only while `.build-running` is absent), the F*/OCaml comment-nesting trap, and iron rule #11 (no hand-editing extracted `.ml`) — plus the one-agent-one-commit and ship-code-sketches rules. Pairs with workflow-gotchas-debugging (which catalogues recovery steps when these rules are violated).

Set up or repair the F* / opam / z3 toolchain for the Factoidal project. Use when the user asks to install or set up F*, when `fstar.exe` is missing from PATH, when z3 has the wrong version (must be 4.13.3), when `make verify` or `build-ocaml.sh` fails with toolchain errors, when starting on a fresh clone that hasn't been bootstrapped, or when an agent has been "burning time on partial builds" because the opam switch isn't activated.

Restore a fresh or recycled VM/container/session to full working state in minutes, not hours — the cache inventory (toolchain-cache branch, .checked verification cache, pycottas venv, skill symlinks), what the bootstrap hook restores automatically vs what needs a command, the wasm_of_ocaml/binaryen ≥116 install path (proxy-blocked release binaries, conda-forge fallback), and the never-again rules from the 2026-07-03 session that burned ~90 minutes compiling F* from source twice. Use on any fresh clone, restored VM, new sandbox, when fstar.exe or test data is missing, when a wasm build fails on a missing `wasm-merge`, when a session is about to do something expensive that a previous session already did, or when adding a new cache-worthy artifact.

Post-feature-landing sweep for statements the landing just made false — stale "not yet / out of scope / parked / later stage" claims in docs, hub notebooks, skills, .fst header comments, test-suite yamls, the ledger, and dashboard prose. Use IMMEDIATELY AFTER landing any feature, capability, or score change; when writing any "we don't have X / can't do X" sentence (verify against the tree first — negative claims rot fastest); or when a reader reports prose contradicting behavior. Ships tools/obsolescence-sweep.sh, the stale-claim lexicon, the target-surface list, and the 2026-07-10 war stories (VC "crypto is a later stage", "Protocol/GSP parked", ShExC "out of scope indefinitely" — all asserted from stale text while the features sat in the tree).

How Factoidal's F* source is organized and written — the semantic-core vs implementation-pragmatics split, module naming, the planned stratification of RDF.Graph.Executable and SPARQL11.Algebra, interface-file (.fsti) policy, verification requirements (no --lax, no --admit_smt_queries, z3 4.13.3), F* syntax traps (comment nesting, reserved words), extraction-semantics traps (F*-verified totality is NOT OCaml totality — List.Tot.splitAt, split-brained string primitives, fixed fuel constants, accumulator order), and KaRaMeL-compatible style. Use when creating or reorganizing .fst modules, when an F* "Syntax error" makes no sense, when a function that verifies as Tot crashes at runtime after extraction, when deciding where a definition belongs, or when writing F* that should later extract to C.

Use when (re)building skosdex concept embeddings for many or all schemes at once — a one-off GPU batch box to embed the whole corpus ASAP, or a parallel CI matrix for incremental per-scheme additions. Covers the embed pipeline, where to run it (and why not the prod box), model parity, committing + deploying the vectors with no blackout, and — critically — tearing the GPU box down afterwards so it stops billing.

Use when working with skosdex concept embeddings — the per-scheme and combined vectors, their JSON formats, the in-browser "similar by meaning" / viz consumers, or the server-side similarity REST API (tools/embed_api.mjs). Covers how to build, combine, query, and extend them.

Use when redeploying the live skosdex stack (skosdex.fly.dev — Oxigraph + Solr + web) on Fly.io, choosing between a direct deploy and the zero-downtime cutover, forcing/monitoring a deploy, or recovering a broken one. The deploy is CI-driven from claude/main.

Use when adding a new SKOS concept scheme / vocabulary / thesaurus to the skosdex repository (creating its third_party/skos/<slug>/ folder and meta.ttl), or when deciding whether a scheme's data may be committed and bundled given its license.

Use when discovering, researching, triaging, or maintaining the list of candidate SKOS vocabularies for skosdex — i.e. updating third_party/skos/CANDIDATES.md, verifying a scheme's license, or deciding whether a vocabulary can be bundled or must stay metadata-only.

Use when producing the shippable skosdex dataset — merging openly-licensed canonical N-Quads into dist/bundle.nq.gz, generating dist/solr-docs.json, building the docs/ site, or understanding which schemes are included/excluded and why.

Use when fetching, parsing, normalizing, or canonicalizing a SKOS scheme into N-Quads in skosdex — i.e. running the scripts/skosdex fetch/normalize/canonicalize pipeline or debugging its normalized.nq.gz / canonical.nq.gz output, including the gzip + Git LFS storage and zip/gz source decompression.

Use when bringing up, configuring, or troubleshooting the skosdex services — the Oxigraph SPARQL endpoint, the Solr index, and the web frontend via docker compose (or swapping Oxigraph for Apache Jena Fuseki).

Work across Lucid's two rendering backends — Mayfly (WebGL/GLSL, lucid/mayfly/) and Stinkyfish (WebGPU/WGSL, lucid/stinkyfish/) — and the code that unifies them: the shared JSON→shader codegen (core/json-codegen.js, core/wgsl-codegen.js), the <lucid-renderer backend="auto"> web component, and the uniform/param plumbing. Use this when a scene looks right in one backend but wrong/blank in the other, when adding a node type or expression operator (it must be implemented in BOTH codegens), when touching the renderer public API or backend switching, or when deciding which backend a feature can rely on. Includes the GLSL↔WGSL capability parity matrix.

Work with Lucid's constraint/rig layer (core/rig-evaluator.js) and its physics stacks (core/physics/*.js) — the systems that drive scene parameters from expressions, phase-coupled animation, bounds, and XPBD simulation, and feed the results into the renderer as uniforms. Use this when authoring or debugging a scene's `rig` or `physics` block, when a physics scene behaves oddly (jitter, double simulation), when wiring parameters to be driven/constrained, or when you need to know what the rig binding-state badges (phys/constrained/driver/ expr) actually mean. Covers the integration points between rig, physics, params, and the render loop — including two known architectural rough edges.

Author, edit, and debug Lucid SDF/CSG scene JSON files (lucid/scenes/**/*.json). Use this whenever you are creating a new scene, adding or modifying primitives, CSG boolean operations, transforms, modifiers (round/shell/displace), reusable definitions (defs/ref), scene parameters, or driven-value expressions for the Lucid renderer. Also use it when a scene renders as an empty frame, a param has no visible effect, or you need to know which node types, transform modes, or expression operators are supported. Covers the shared scene format consumed by BOTH the Mayfly (WebGL/GLSL) and Stinkyfish (WebGPU/WGSL) backends.

Work on time, animation, looping, the timeline scrubber, and camera/gesture interaction in the Lucid SDF viewer. Use this when driving scene parameters over time, wiring or debugging the node-editor timeline (play/pause/loop/ scrub), controlling the render clock, adding orbit/pan/zoom or touch/tap interaction, or connecting a tap to a physics impulse or picking. Covers how the two backends derive time, how the timeline drives the preview, and the camera-interaction paths (the reusable <lucid-orbit-controls> component vs the hand-rolled handlers in index.html).