PubLedge

Open recordkeeping protocol for fact-specific written interpretations between two parties — Joint Interpretation Agreements (JIAs), Regulatory Mitigation Agreements (RMAs), no-action letters, private letter rulings, advisory opinions, and analogous civic instruments (HOA decision logs, co-op governance records, flying-club asset agreements, and the like).

Plain markdown with structured frontmatter. Hash-pinned for integrity. Bound to the Semantic Arts gist upper ontology so records from different authorities can be queried together.

Public. Current release v0.1.1-pre (2026-05-30). Drafting continues in public toward v0.2.

Who this is for

Regulators, regulated parties, and civic bodies that issue or rely on fact-specific written interpretations and need them recorded in a portable, queryable form.

What problem it solves

Fact-specific interpretations (no-action letters, private rulings, JIAs, HOA decisions) live in scattered, unstructured records that can't be compared across authorities. PubLedge is an open protocol that records them as hash-pinned markdown bound to a shared ontology.

Canonical URL

https://publedge.org/

Part of the PAICE legal graph

PubLedge is one component of the PAICE legal graph (with EveryAILaw, AI Incident Law, and Obligation First). It is intentionally open: code under Apache 2.0, protocol and content under CC BY 4.0, commercial use permitted with attribution. The open siblings are funded by EveryAILaw Pro, the graph's single restricted layer; openness here is a deliberate PBC-charter choice. The canonical model is in the PAICE Foundation INTENT.

What this repo is

Three things in one place:

1. The protocol — the PROTOCOL.md specification and the PRIOR-ART.md survey that motivates it.
2. Utah-shaped reference content — 5 JIA/RMA templates anchored to Utah's AI Policy Act (Utah Code §13-72a) and GenAI safe-harbor (§13-75-104), plus 14 demonstration instruments under data/examples/instruments/ spanning 7 authorities (Utah OAIP, SEC, CFPB, IRS Chief Counsel, IRS TEGE, CFTC, Utah Legislature) and 6 instrument types (JIA, RMA, no-action letter, advisory opinion, private letter ruling, interpretive letter, statute). 26 first-class obligation records under data/examples/obligations/ are mapped to the instruments via data/examples/mapping/index.yml.
3. The published site — rendered HTML under docs/, served by GitHub Pages from main /docs. Regenerate with node scripts/build.js && node scripts/build-extras.js before committing; CI fails if docs/ drifts from sources.

Machine-readable endpoints

Every record and index is published in parallel HTML + structured form so agents can walk the registry without scraping:

Surface	Shape
/	WebSite + Organization + DataCatalog JSON-LD (@graph); links to every dataset distribution
/us/{jurisdiction}/{authority}/{type}/{instance}/	Canonical hierarchical URL per record; inline Schema.org LegalDocument JSON-LD; PDF + OCR text co-located
/us/{jurisdiction}/{authority}/{type}/{instance}/record.json	Same record as JSON; shape validated by /schema/json/record.schema.json
/instruments.html, /obligations.html, /authorities.html	ItemList JSON-LD; human-readable filter + sort
/matrix.html	Dataset JSON-LD + coverage matrix; DataDownload distribution at /api/v1/matrix.json
/definitions/	DefinedTermSet with instrument types + statuses as DefinedTerms
/api/v1/*.json	Machine manifests: containers, primaries, authorities, mappings, matrix, upcoming, recently-changed
/api/v1/of/*.json	Obligation-First v0.1 binding records for authorities, instruments, terms, obligations, and determinations
/calendar.ics	Enforcement calendar (iCal)
/feed.xml, /atom.xml, /feed.json	RSS 2.0, Atom 1.0, JSON Feed 1.1
/sitemap.xml	Sitemap index → per-section sitemaps (records, authorities, statutes, reference, templates, bridges, meta)
/llms.txt, /agents.json	Agent-discovery briefing + capabilities
/robots.txt	Explicit allow for 17 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended, etc.)
mcp-server.js	MCP server exposing 13 read-only tools: list_<legal-instruments> (with jurisdiction/authority/type/status filters), get_<legal-instrument>, list_obligations, get_obligation, list_authorities, get_authority, search, search_obligations, get_matrix, get_mappings, fetch_by_url, get_upcoming, get_recently_changed

What this repo is not

• Not a regulator. PubLedge does not issue rulings.
• Not a law firm. Templates here are prior art, not legal advice.
• Not a CMS. Editors edit markdown in git.
• Not a blockchain. The integrity layer is plain SHA-256 over plain files.

Quickstart

git clone https://github.com/snapsynapse/publedge.git
cd publedge
./scripts/validate-hashes.sh           # verify integrity
node scripts/validate.js               # cross-reference checks
node scripts/build.js                  # regenerate docs/ entity pages + API
node scripts/build-extras.js           # copy reference HTML, feeds, discovery files

To validate the Obligation-First binding, check out snapsynapse/obligation-first beside this repo or set OBLIGATION_FIRST_DIR, then run npm run validate:of.

After intentional content edits, refresh hashes:

./scripts/validate-hashes.sh --update

CI runs all of the above, plus a pa11y-ci WCAG 2.1 AA pass across every URL in the sitemap, on every push and pull request.

Repository layout

Path	Purpose
PROTOCOL.md	The PubLedge specification
PRIOR-ART.md	Survey of analogous instrument programs
DEFINITIONS.md	Canonical vocabulary (status values, instrument types, obligation kinds)
MANIFEST.yaml	SHA-256 hashes for every canonical file
_templates/jia/, _templates/rma/	Fill-in templates with {{variable}} placeholders
data/examples/instruments/	14 demonstration instruments; filename = stable id (e.g. us-ut-oaip-rma-2025-001.md)
data/examples/authorities/	Authority records for each issuing body
data/examples/obligations/	Obligation definitions linked from instruments
data/examples/mapping/	Obligation-to-statute mapping index
about/	Hand-crafted /about/ source page (copied verbatim into docs/)
reference/	Hand-crafted reference HTML (prior-art, disclaimer, vocabulary)
schema/json/	JSON Schemas + JSON-LD context
vendor/gist/	Pinned snapshot of the Semantic Arts gist core ontology
scripts/	Validators (validate.js, verify.js), build (build.js, build-extras.js), hash check
_workshop/	Site ontology workshop output (taxonomy, sitemap, content guide, roadmap)

The _workshop/ directory documents the design decisions behind the layout above. Read _workshop/TAXONOMY.md, _workshop/SITEMAP.md, and _workshop/CONTENT-GUIDE.md before proposing structural changes.

Contributing an instrument

1. Pick template under _templates/jia/ or _templates/rma/.
2. Replace every {{variable_name}} with applicable values.
3. Set id to {jurisdiction}-{authority}-{type}-{YYYY-NNN} (e.g. us-ut-oaip-rma-2025-003). Filename must match: us-ut-oaip-rma-2025-003.md.
4. Set status: draft. Add parties under parties:.
5. Place file under data/examples/instruments/.
6. Run ./scripts/validate-hashes.sh --update to refresh MANIFEST.yaml.
7. Run node scripts/build.js && node scripts/build-extras.js to verify site regenerates cleanly.
8. Open a pull request.

See CONTRIBUTING.md for full conventions including obligation entries, source PDFs, and OCR workflow.

License

PubLedge is dual-licensed:

• Content (markdown, YAML, HTML) — CC-BY 4.0
• Code (scripts, schemas, build tooling) — Apache 2.0

See LICENSE for the split. Vendored snapshots retain their upstream licenses; the pinned gist core ontology is CC-BY 4.0 (Semantic Arts). Full credits in ATTRIBUTION.md.

Built on

• Knowledge as Code — the four-role entity pattern (Authority / Container / Secondary / Primary) PubLedge inherits.
• gist (Semantic Arts) — open upper ontology bound to PubLedge entities.
• Every AI Law — preferred source for statute-anchor URLs in statute_anchors[].
• skill-provenance — hash-mechanism pattern adapted for validate-hashes.sh. PubLedge does not adopt the full skill-provenance protocol.

Status and roadmap

Milestone	Status
Workshop, taxonomy, sitemap, content guide	done
Protocol specification (PROTOCOL.md)	done
Prior-art survey (PRIOR-ART.md)	done
Initial Utah templates (3 JIA, 2 RMA)	done
First registry instance (us-ut-oaip-jia-2026-001)	done
Hash-pinned integrity + CI verification	done
Discovery files (llms.txt, agents.json, feed.xml)	done
MCP server (mcp-server.js)	done
CLI validators (scripts/validate.js, scripts/verify.js)	done
JSON Schemas + JSON-LD context (schema/json/)	done
Unified site generator (build.js + build-extras.js)	done
Frontmatter spec v0.2	done
9 federal + Utah demonstration remaps	done
4 Utah statutes as first-class instrument records	done
Canonical URL architecture (/{country}/{jurisdiction}/{authority}/{type}/{YYYY-NNN}/)	done
record.json per instrument (Schema.org LegalDocument JSON-LD)	done
calendar.ics, api/v1/upcoming.json, api/v1/recently_changed.json	done
Status vocabulary (9 values) + DEFINITIONS.md + /definitions/ page	done
publedge-source-ingest skill for authored ingestion	done
Disclaimer & Source Policy at /reference/disclaimer/	done
Obligations + mapping curation pass (26 obligations, 14 mappings)	done
JSON-LD on top-level pages (home @graph, ItemList indexes, DefinedTermSet, Dataset)	done
Split sitemap index + 7 section sitemaps	done
JSON Feed 1.1 + Atom 1.0 feeds alongside RSS	done
/schema/json/record.schema.json (JSON Schema draft 2020-12)	done
Extended MCP tool surface (13 tools; filters, URL-based fetch, upcoming, recently-changed)	done
Explicit AI-crawler allowlist in robots.txt	done
Agent-readiness + a11y audit artifacts in audits/ + .a11y-audit/	done
Axe-core WCAG 2.1 AA remediation (4 rules, 70 instances → 0)	done
Private snapshot for pre-release review	sent
Lawyer review (SLC attorney)	pending
repo-polish	done
Repository public	done
promo-orchestrator + public announcement	pending
Browser-side registry browser + comparison tooling	planned for v0.2
Branch-and-strip to reusable protocol template	planned for v0.2

See ROADMAP.md for phasing and _workshop/ROADMAP.md for the original workshop plan.