MCP server and recordkeeping protocol for fact-specific written interpretations between two parties: JIAs, RMAs, no-action letters, advisory opinions, private letter rulings. Plain markdown, manifest-checked, gist-bound. The verifiable-records layer of th
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. SHA-256 manifest checks provide source-to-manifest consistency. Bound to the Semantic Arts gist upper ontology so records from different authorities can be queried together.
Public and maintained. Protocol specification v0.2.0; stable MCP server v0.2.1. The MCP server is dual-era: MCP spec 2026-07-28 stateless core plus the legacy 2024-11-05 handshake. Standalone product expansion is parked pending a concrete legal-graph or adopter demand signal.
Regulators, regulated parties, and civic bodies that issue or rely on fact-specific written interpretations and need them recorded in a portable, queryable form.
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 manifest-checked markdown bound to a shared ontology.
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.
Three things in one place:
data/examples/instruments/ spanning 8 authorities (Utah OAIP, Utah Legislature, Colorado Legislature, SEC, CFPB, IRS Chief Counsel, IRS TEGE, CFTC) and 7 instrument types (JIA, RMA, no-action letter, advisory opinion, private letter ruling, interpretive letter, statute). 35 first-class obligation records under data/examples/obligations/ are mapped to the instruments via data/examples/mapping/index.yml; legal lifecycle is tracked separately from editorial maturity.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.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; includes authority_response annotations when present |
/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 binding records for authorities, instruments, terms, obligations, and administrative issuance 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 |
/.well-known/mcp.json | Installable MCP server discovery for npx -y publedge |
/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 |
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.
Choose the surface that matches the job:
curl -sS https://publedge.org/api/v1/containers.json | jq '.[0]'
record.json to its canonical record URL:curl -sS https://publedge.org/us/federal/sec-corpfin/nal/2025-001/record.json | jq '.id, .status'
{
"mcpServers": {
"publedge": {
"command": "npx",
"args": ["-y", "publedge"]
}
}
}
search to discover records and fetch_by_url when you already have a canonical PubLedge URL. The complete endpoint and capability inventories are at api/v1/index.json and agents.json.Canonical markdown under data/examples/ is the maintained source. Published HTML, API indexes, and each record.json are generated representations and should not be edited directly.
| Path | Purpose |
|---|---|
PROTOCOL.md | The PubLedge specification |
INTENT.md | Authoritative repository disposition, active work, and revisit triggers |
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/ | 18 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.
_templates/jia/ or _templates/rma/.{{variable_name}} with applicable values.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.status: proposed and editorial_status: draft. Add parties under parties:.data/examples/instruments/../scripts/validate-hashes.sh --update to refresh MANIFEST.yaml.node scripts/build.js && node scripts/build-extras.js to verify site regenerates cleanly.See CONTRIBUTING.md for full conventions including obligation entries, source PDFs, and OCR workflow.
PubLedge is dual-licensed:
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.
statute_anchors[].validate-hashes.sh. PubLedge does not adopt the full skill-provenance protocol.| 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 (35 obligations, 16 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 |
| Authority response protocol field, rendering, schema, and validation | 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; demand-triggered |
| repo-polish | done |
| Repository public | done |
| Obligation-First v0.4.x naming profile | done |
| promo-orchestrator + public announcement | parked |
| Browser-side registry browser + comparison tooling | parked |
| Branch-and-strip to reusable protocol template | parked |
See ROADMAP.md for phasing and _workshop/ROADMAP.md for the original workshop plan.
FAQs
MCP server and recordkeeping protocol for fact-specific written interpretations between two parties: JIAs, RMAs, no-action letters, advisory opinions, private letter rulings. Plain markdown, manifest-checked, gist-bound. The verifiable-records layer of th
We found that publedge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
NIST disclosed an unreleased AI tool called V-etalon and opened a broad inquiry into NVD modernization after years of automation plans produced no public enrichment system.
Security News
In his AI Council 2026 talk, Feross Aboukhadijeh covers recent package compromises, vulnerability discovery, and a more automated security model.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.