DEV Community: snapsynapse

Teach Your AI Coding Agent to Run Accessibility Audits

snapsynapse — Tue, 14 Apr 2026 15:00:00 +0000

You've got an AI coding agent. It can scaffold components, write tests, refactor modules. But ask it to check whether your app is accessible and you get one of two things: a vague summary of WCAG principles with no actionable output, or a hallucinated audit that references guidelines it didn't actually check against.

The problem isn't that the agent is incapable. It's that nobody told it how. What tool to install. What rules to run. How to map a violation to a specific WCAG success criterion. What to put in the report. What still needs a human.

skill-a11y-audit is a reusable agent skill that solves this. Drop it into your project, and your agent gets a structured protocol for running real accessibility audits with real tooling.

What it does

The skill packages a complete audit workflow:

Runs axe-core against your pages, targeting WCAG 2.1 AA
Optionally runs Lighthouse accessibility checks for a second signal
Maps every violation to the specific WCAG success criterion it fails
Generates a markdown report with severity, affected elements, and remediation guidance
Flags what automation can't catch and provides manual follow-up guidance for the things that need a human (keyboard navigation, screen reader behavior, content meaning)

The output is a report you can hand to a developer, file as a ticket, or use as a punch list. Not a score. Not a badge. A list of specific things that are broken and what to do about them.

How to install it

For Claude Code, copy the a11y-audit/ folder into .claude/skills/ in your project:

git clone https://github.com/snapsynapse/skill-a11y-audit.git
cp -r skill-a11y-audit/a11y-audit .claude/skills/

For Codex, copy or symlink the same folder into your Codex skills directory. The skill is platform-agnostic by design -- any agent that reads a SKILL.md file can use it.

Once installed, you can trigger it with natural language:

"Run an accessibility audit on this project."
"Audit this app for WCAG 2.1 AA issues and generate a markdown report."
"Use $a11y-audit to scan the homepage, about page, and contact page."

Why a skill instead of just a tool

axe-core exists. Lighthouse exists. pa11y exists. You could tell your agent to install and run any of them. But here's what actually happens when you do that:

The agent installs axe-core. Runs it with default settings. Dumps raw JSON. Doesn't map violations to WCAG criteria. Doesn't distinguish between things it can verify and things that need manual checking. Doesn't structure the output so anyone can act on it.

A skill isn't a wrapper around a CLI. It's the knowledge of how to use the tool well. Which rules to run. How to structure the output for a developer who needs to fix things. When to stop and say "a human needs to check this part." That operational knowledge is what the agent is missing, and it's what this skill provides.

What the report looks like

The skill generates structured markdown. Each violation gets:

The WCAG success criterion it fails (e.g., 1.4.3 Contrast)
Impact level (critical, serious, moderate, minor)
The specific elements affected
What to fix and how

The report also includes a manual review section: things like keyboard trap testing, focus order verification, and screen reader behavior that no automated tool can fully assess. The skill doesn't pretend automation covers everything. It draws a clear line between what it checked and what still needs a human.

Scope and constraints

This skill targets WCAG 2.1 Level AA, which is the standard most organizations are working toward and the baseline for most legal compliance requirements. It uses axe-core's rule set, which is the same engine behind Google Lighthouse's accessibility score and Deque's commercial products.

Automated tooling catches a meaningful portion of accessibility issues, but not all of them. The skill is explicit about this boundary. It will find missing alt text, insufficient contrast, missing form labels, improper ARIA usage, and similar machine-verifiable failures. It won't tell you whether your tab order makes sense to a human, whether your error messages are comprehensible, or whether your modal traps keyboard focus. That's what the manual follow-up section is for.

Who this is for

Developers who want accessibility checks as part of their agent-assisted workflow, not as a separate step they forget
Teams using Claude Code or Codex who want consistent, structured audit output across projects
Anyone building agent skills who wants a reference implementation for how to package tool knowledge as a reusable skill

The skill follows the agentskills.io open standard and uses skill-provenance for cross-platform version tracking.

Get it

GitHub repo -- MIT licensed.
Homepage

If you're building agent skills and want to see how this one is structured, the SKILL.md is the whole thing. No build step, no dependencies beyond the audit tools themselves. Read it, fork it, improve it.

Built by SnapSynapse. If you want to see this skill in action on a real project, check out the AI Tool Watch, which was audited using it.

EveryAILaw.com: A Structured Database of AI Compliance Obligations Across Jurisdictions

snapsynapse — Tue, 07 Apr 2026 14:00:00 +0000

If your organization builds or deploys AI systems, you are already subject to overlapping regulations from multiple jurisdictions — and the list is growing. Figuring out which rules apply, what they require, and when enforcement begins means cross-referencing dozens of documents that use different terminology for the same obligations.

EveryAILaw.com is a free, structured, database-less reference (built on the Knowledge-as-Code template)that tracks compliance obligations across all known AI regulations globally, spanning the EU, US federal agencies, and the key six US states. Instead of organizing by regulation, it uses an obligation-first ontology: stable compliance concepts like transparency, human oversight, and bias prevention serve as anchors, with specific regulatory provisions mapped to them.

When to use it

You need a single structured source to check which AI regulations apply to your organization, compare obligations across jurisdictions, and track enforcement deadlines. The JSON API and MCP server make it practical to integrate compliance lookups into developer tooling or AI-assisted workflows rather than maintaining a spreadsheet.

When not to use it

This is a reference tool, not legal advice. It does not replace regulatory counsel. If you need binding compliance assessments or jurisdiction-specific legal interpretation, consult an attorney. While the coverage is global, the current iteration is weighted toward US state laws and the EU AI Act.

What it covers

51 regulations: EU AI Act, Colorado ADMT, California CCPA ADMT, CMS Medicare Advantage, and others across 8 regulatory authorities
10 core obligations: transparency, human oversight, risk assessment, bias prevention, incident reporting, and more
3 access layers: HTML site for browsing, JSON API for integration, MCP server for AI assistants

Links

The obligation-first structure makes an interesting bet: that the compliance concepts are more stable than the regulations themselves. If you work in AI governance, curious whether that matches your experience.

Your site works fine in a browser. AI agents can't use it. 🔍

snapsynapse — Thu, 02 Apr 2026 13:00:00 +0000

I was building agent workflows for clients when I noticed a pattern that drove me nuts: agents would hit a site, get a 200 OK, and then... nothing useful. No structured data. No clear navigation path. Sometimes a WAF would silently block the request. The agent would fail, the logs would look fine, and I'd waste hours figuring out why.

The thing is, these weren't bad websites. They ranked well on Google. They looked great in a browser. They just weren't built for anything that wasn't a human clicking around in Chrome.

I kept running into the same invisible wall across different clients, then I hit it with my own startup. Ouch. So I built the diagnostic I wished existed, because I needed it too.

Meet Siteline

Siteline is a free scanner that grades how usable your public website is for AI agents. You give it a URL, it tells you what works, what's broken, and what to fix — in about 10 seconds.

It's live right now at siteline.to. Type any URL and see the grade. Totally free.

What it checks

Siteline evaluates four pillars — what I call the SNAP rubric:

Signal
Can an agent even reach your site? This checks whether your server responds to non-browser clients, whether robots.txt blocks agent user-agents like ClaudeBot or GPTBot, and whether HTTPS is in place. You'd be surprised how many sites return 403 to anything that isn't Chrome.

Navigate
Once an agent lands on the page, can it figure out where things are? This looks for JSON-LD, site identity signals, clear navigation to key pages (About, Services, Contact), and machine discovery paths like sitemaps and RSS feeds.

Absorb
Is the actual content machine-readable? Siteline checks whether the initial HTML has meaningful content or if everything hides behind JavaScript rendering. It looks at heading hierarchy, semantic markup, and whether the content model is clear or confused.

Perform
Can the agent figure out what the user should do next? This checks for interpretable CTAs, form labels, button text, and whether next steps are clear enough for an agent to relay back to a human.

Each pillar gets a weighted score. The final grade is A through F.

What I learned building this

The biggest surprise: bot-blocking is the #1 failure mode, not content quality. Most sites I scanned during development had decent content structure. But their WAF or hosting provider was silently blocking anything that didn't look like a browser. The site owner had no idea.

The second surprise: most sites that invested heavily in SEO still scored very poorly. SEO optimizes for Google's crawler. AI agents have different constraints. They need structured data, clear action paths, and machine-readable policy signals that search crawlers don't care about.

Try it

Web: siteline.to

CLI:

npx siteline scan yoursite.com

API:

curl "https://siteline.to/api/scan?url=yoursite.com"

MCP Server (for agent developers):

npx siteline mcp

This exposes four tools — scan_url, self_scan, describe_rubric, and explain_score — so your agents can assess sites programmatically before attempting workflows on them.

The stack

Frontend: Vanilla HTML/CSS/JS — no framework, no build step
Backend: Node.js on Vercel serverless functions
Storage: Supabase PostgreSQL (results cached 24h per domain)
Dependencies: One — @vercel/og for dynamic social images

One architectural decision worth mentioning: Siteline tests with a non-browser user-agent first, then falls back to a headless browser if blocked. This lets it distinguish between "your content is bad" and "your firewall is blocking agents" — which is the diagnostic that matters most.

What's next

I'm working on multi-page analysis (right now it evaluates the landing page only) and a comparison mode for benchmarking against competitors. The rubric itself is versioned and will evolve as agent capabilities change.

How do you currently test whether AI agents can actually use your site, or do you just assume it works?

How Do You Measure Whether Someone Is Actually Good at Working With AI?

snapsynapse — Tue, 31 Mar 2026 14:00:00 +0000

Here's a question that sounds simple and isn't: is your team actually good at working with AI, or are they just using it?

Using means generating output. Good at working with means the human added judgment, caught errors, maintained context, and produced something the organization can defend. The difference matters because when something goes wrong, accountability doesn't attach to the AI. It attaches to the person who signed off.

Every organization deploying AI needs to answer this question. And almost none of them can, because the tools they're using to measure AI skills don't measure collaboration. They measure knowledge.

The quiz problem

The dominant approach to measuring AI capability in organizations is some form of quiz: multiple choice, scenario-based questions, self-assessment surveys. These tell you whether someone knows what good collaboration looks like. They don't tell you whether someone does it.

This is the same gap that exists between knowing you should write tests and actually writing tests. Between knowing you should review PR diffs line by line and actually reviewing them. Knowledge and behavior diverge under real conditions, especially when the behavior is effortful and the shortcut is invisible.

The shortcut with AI is accepting output without meaningful verification. It looks like productivity. It feels like efficiency. And it's undetectable by any assessment that asks what you would do rather than observing what you actually do.

What behavioral measurement looks like

PAICE takes a different approach. Instead of asking people about AI collaboration, it puts them in one.

The assessment is a 25-minute conversation with an AI system. It looks and feels like a normal working session: you're given a realistic task, you collaborate with the AI to complete it, and you produce a deliverable. What you don't know is that the AI's outputs contain strategically injected errors -- factual mistakes, logical inconsistencies, subtle hallucinations calibrated to the domain.

The assessment isn't measuring whether you can use AI. It's measuring what happens when the AI is wrong and you're responsible for the output.

Do you catch the error? Do you verify claims that sound plausible? When you find a problem, do you fix it or work around it? When the AI pushes back on your correction, do you hold your ground or defer? These behavioral signals are what the scoring model captures.

Dimensional scoring

Collaboration quality isn't a single number. Someone might be excellent at iterative prompting but terrible at verification. Another person might catch every error but struggle to give the AI useful feedback. A single score flattens these differences into noise.

PAICE measures across multiple dimensions independently:

Accountability measures whether someone verifies outputs, detects injected errors, and takes ownership of the final work product. This is consistently the lowest-scoring dimension across all populations tested. People know they should verify. Under real working conditions, most don't verify thoroughly enough.

Integrity measures whether someone maintains factual standards, catches logical inconsistencies, and refuses to use AI-generated content that doesn't meet quality thresholds.

Collaboration quality measures the effectiveness of the human-AI interaction itself: whether feedback is specific and actionable, whether iteration actually improves the output, whether the person understands when AI adds value and when it introduces friction.

Evolution measures adaptive capacity: whether someone builds mental models of AI strengths and weaknesses over time and adjusts their approach accordingly.

Each dimension produces an independent score. For L&D teams designing targeted training, a dimensional profile is vastly more actionable than a percentage.

The engineering problem

Building this required solving several problems that don't have obvious precedents:

Error injection that doesn't break immersion. The injected errors have to be realistic enough that catching them requires domain judgment, not pattern recognition. If the errors are obviously wrong, you're measuring attention, not expertise. If they're too subtle, the signal-to-noise ratio collapses. The calibration is adaptive -- the system adjusts based on how the participant is performing.

Behavioral signal extraction from conversation. The scoring model doesn't grade the deliverable. It analyzes the collaboration process: what the participant questioned, what they accepted, how they responded to pushback, whether their verification was systematic or sporadic. This requires a multi-model architecture where the assessment AI and the scoring model operate independently.

Multi-model bias prevention. When the AI that runs the conversation is also the AI that scores it, you get circular reasoning. PAICE uses separate models for assessment delivery and scoring, with the scoring model evaluating behavioral signals rather than output quality.

Pre-post comparison for training ROI. The most valuable use case isn't a one-time score. It's administering the assessment before and after a training intervention and measuring whether actual behavior changed. This requires scoring stability across sessions and dimensional granularity fine enough to detect movement in specific skill areas.

Who this is for

PAICE is built for Leaders and organizational decision-makers who are deploying AI and need to know whether their people are collaborating with it effectively or just using it as a faster copy-paste.

If you're a developer interested in the measurement architecture, the Closing the Collaboration Gap whitepaper covers the technical framework, and the daily blog explores the intersection of trust, verification, and performance measurement in human-AI systems.

paice.work

PAICE.work PBC is a public benefit corporation focused on making human-AI collaboration measurable, teachable, and governable.

I built an open spec because every bad 429 was costing me twice

snapsynapse — Thu, 26 Mar 2026 15:00:00 +0000

I was building an AI agent readiness scanner called Siteline when I noticed something embarrassing: my own rate limiting was making things worse.

An agent would hit a 429 Too Many Requests. It would get back Retry-After: 60. So it would wait 60 seconds and try again. Reasonable. But it had no idea whether a cached result already existed for that domain. It had no idea what the actual limit was before it hit it. It had no way to know why the limit existed -- was this a temporary cooldown, or was it burning through a daily quota?

Every vague refusal generated follow-up traffic. The rate limit meant to protect the service was creating load on the service.

The pattern that kept showing up

I started looking at how other APIs handle this, and the same gap appeared everywhere. Rate limits exist. Communication about rate limits usually doesn't. And when it does it's just kinda...mean? Like there's a lot of "Stop, don't do this!" but no "Hey, here's the right way to do this."

A 429 with Retry-After: 60 tells a retry loop what to do. It doesn't tell an autonomous agent whether to retry, use a cached result, try a different endpoint, or inform the human. It doesn't tell a developer what the limits are before they hit them. It doesn't tell anyone why the limit exists.

When the caller is a person, they shrug and wait. When the caller is an agent, it retries faster, probes more systematically, and lacks the judgment to know when to stop. The waste compounds.

So I wrote a spec.

Graceful Boundaries

[https://github.com/snapsynapse/graceful-boundaries/blob/main/spec.md][1]

Graceful Boundaries addresses three gaps that existing standards cover separately but nothing combines:

Proactive discovery -- limits are machine-readable before they are hit

Structured refusal -- when a limit is exceeded, the response explains what happened, which limit applies, when to retry, and why

Constructive guidance -- the refusal includes a useful next step, not just a block

The spec defines four conformance levels, from "you added five fields to your 429s" (Level 1) to "agents can discover your limits, understand your refusals, follow constructive alternatives, and self-throttle on success responses" (Level 4).

What a bad refusal looks like

{
  "error": "Too Many Requests"
}

The caller learns nothing. It retries. You get more traffic.

What a Graceful Boundaries refusal looks like

{
  "error": "rate_limit_exceeded",
  "detail": "You can run up to 10 scans per hour. Try again in 2400 seconds.",
  "limit": "10 scans per IP per hour",
  "retryAfterSeconds": 2400,
  "why": "Siteline is a free service. Rate limits keep it available for everyone and prevent abuse.",
  "alternativeEndpoint": "/api/result?id=example.com"
}

The caller knows the limit. Knows when to retry. Knows why the limit exists (a security signal, not a courtesy). And knows there's a cached result endpoint it can try right now instead of waiting.

Zero follow-up requests generated from that refusal.

Proactive discovery: let agents plan before they fail

Level 2 adds a discovery endpoint. Any agent can hit /api/limits and get back every enforced limit as structured JSON:

curl -s https://siteline.to/api/limits | jq '{service, limits: .limits.scan}'

{
  "service": "Siteline",
  "limits": {
    "scan": {
      "endpoint": "/api/scan",
      "method": "GET",
      "limits": [
        {
          "type": "ip-rate",
          "maxRequests": 10,
          "windowSeconds": 3600,
          "description": "10 scans per IP per hour."
        }
      ]
    }
  }
}

An agent that reads this before making any requests can budget its calls. No discovery-through-failure.

Self-throttling on success

Level 4 adds proactive headers to successful responses:

RateLimit: limit=10, remaining=9, reset=3540
RateLimit-Policy: 10;w=3600

A caller seeing remaining=1 self-throttles before the next request. A caller seeing remaining=9 knows it has budget and won't add artificial delays. This is the highest-leverage traffic reduction mechanism in the spec, and it's aligned with the IETF draft-ietf-httpapi-ratelimit-headers draft.

It applies beyond rate limits

One thing that surprised me during development: the pattern works for every class of HTTP response, not just 429s.

A 400 with "why": "Blocks requests to non-public addresses to prevent server-side request forgery" tells the caller the security model. A 404 with "scanAvailable": true and a scanUrl tells the caller it can create the resource instead of giving up. A 503 with retryAfterSeconds and a statusUrl tells the caller when to come back and where to check status.

The spec covers five response classes (Limit, Input, Access, Not Found, Availability) with specific required and optional fields for each.

The security model

Transparency and security are in tension. The spec handles this with a simple principle: be transparent about rules, not mechanisms.

"10 requests per hour" is a rule. Safe to disclose. "We use Redis with a sliding window" is an implementation. Not safe. The spec includes eight security considerations (SC-1 through SC-8) covering limit calibration attacks, validation oracles, URL origin restrictions, and more. There's a full security audit in the repo.

Adopting it

Level 1 takes about 20 minutes. Add five fields to your existing 429 responses: error, detail, limit, retryAfterSeconds, and why. The why field is the one that matters most -- it must explain the purpose of the limit, not restate the error.

Level 2 adds a discovery endpoint. Level 3 adds constructive guidance to refusals. Level 4 adds proactive headers to successes.

The conformance checker validates any public URL:

node evals/check.js https://your-service.com

104 tests, zero dependencies.

Try it

The full spec is at spec.md. The reference implementation is Siteline, a Level 4 conformant AI agent readiness scanner you can verify yourself.

Licensed CC-BY-4.0. Use it, adapt it, build on it.

How do your APIs currently communicate limits? Is it the structured kind, or the "good luck figuring out what just happened" kind?

Your AI Agent Skills Have a Version Control Problem

snapsynapse — Tue, 24 Mar 2026 14:00:00 +0000

You build a skill for your AI coding agent. You refine it across five sessions. You upload it to a new conversation and immediately hit the question you can't answer: is this the one from yesterday, or the one from Tuesday?

If you're working in Claude Chat, there's no persistent filesystem. If you're in Codex, the session is stateless. If you moved the skill from Claude Code to Gemini CLI, you probably renamed a file and forgot which copy is canonical. And if someone else is using your skill, they have no way to know whether their copy matches yours.

Git solves this for code repositories. But agent skills don't always live in repos. They live in chat uploads, settings panels, Obsidian vaults, .skill files, and directories that get copied between surfaces with no audit trail. The version information needs to travel with the files, not alongside them in a system the files might never touch.

What skill-provenance does

skill-provenance is a meta-skill, or a skill that manages other skills. Load it alongside any skill project and it handles the versioning bookkeeping at session boundaries.

Three conventions make it work:

Version identity lives inside the files. Not in a filename suffix, not in a folder name, not in your memory of when you last edited it. The SKILL.md frontmatter carries the version, and the manifest confirms it.

A changelog travels with the bundle. Every session close appends what changed. When the next session opens, it can read the history without asking you to remember.

A manifest lists every file with roles and hashes. Open a session, the skill reads the manifest, checks that all files are present, verifies hashes, and tells you what's stale or missing before you start working.

What happens at session boundaries

When you open a session, it reads the manifest, compares hashes, flags missing files, and reports what needs attention.

When you close a session, it updates version headers, recomputes hashes, appends to the changelog, and flags files that should have been updated but weren't.

When you hand off between sessions, it generates a handoff note: current state, what was accomplished, stale files, next steps. Because the next instance of Claude has no memory of what you just did, and "I think I left off around..." is not version control.

Cross-platform portability

The skill works on any platform that supports the agentskills.io standard. But different platforms have different opinions about SKILL.md frontmatter:

Platform	Frontmatter rules
Claude	Full metadata block with version info
Gemini CLI	Name and description only
Codex	Name and description only
GitHub Copilot	Follows agentskills.io spec

The manifest tracks a frontmatter_mode field (claude or minimal) so the skill knows whether to embed version info in SKILL.md or keep it manifest-only. The repo ships in minimal mode for maximum portability.

This means you can author a skill in Claude Code, export it for Gemini CLI, and the version identity carries over without manual conversion.

What's in the bundle

skill-provenance.skill           # Install this in Claude Settings
skill-provenance/
├── SKILL.md                     # The skill definition
├── README.md                    # User guide with worked examples
├── MANIFEST.yaml                # File inventory: roles, versions, hashes
├── CHANGELOG.md                 # Change history
├── evals.json                   # 13 evaluation scenarios
└── validate.sh                  # Local hash verification script

The .skill file is a ZIP for Claude's Settings UI. The directory is the same content for Claude Code, git repos, and Obsidian vaults. Use whichever format fits your workflow.

The evals

13 structured evaluation scenarios covering: bootstrapping an unversioned bundle, detecting missing and stale files on session open, conflict detection between version headers and manifests, cross-platform bootstrapping for Codex and Gemini CLI, frontmatter mode toggling, generating git commit messages, and handoff notes with per-file change summaries.

These aren't unit tests. They're prompt-and-expected-behavior pairs you can use to verify the skill works correctly on your platform, or as a reference for how to write evals for your own skills.

Who this is for

This is for anyone who builds or maintains agent skills and has been bitten by the "which version is this?" problem. If you're a solo author working across multiple surfaces, it catches the drift you'd otherwise miss. If you're handing skills to a team, it gives the next person a manifest they can verify instead of a folder they have to trust.

It's also a reference implementation for how to structure a skill bundle. If you're building your first skill and wondering what files to include, how to write evals, or how to handle cross-platform compatibility, this is one answer to those questions.

Install

For Claude Chat: download skill-provenance.skill from the latest release, go to Settings, Skills, Add Skill, select the file.

For Claude Code, Codex, or Gemini CLI: use the skill-provenance/ directory directly.

Then tell your agent:

Use the skill-provenance skill to bootstrap this bundle.

Homepage
GitHub repo -- MIT licensed, v4.0.0.

Built by SnapSynapse. Used as the versioning backbone for skill-a11y-audit, ai-capability-reference, and the rest of the SnapSynapse skill ecosystem.

Knowledge as Code: A Pattern for Knowledge Bases That Verify Themselves

snapsynapse — Wed, 18 Mar 2026 13:00:00 +0000

Documentation rots. You know this. You've seen internal wikis with pages last updated in 2023 that everyone still treats as authoritative. You've inherited a knowledge base where half the links are dead and nobody knows which facts have drifted.

The usual response is to assign someone to "maintain the docs." This works until that person gets busy, changes roles, or leaves. Then the decay resumes, silently, until the wrong person relies on the wrong fact.

What if the knowledge base could detect its own decay?

The pattern

Knowledge as Code applies software engineering practices to knowledge management. The knowledge lives in version-controlled plain text files. It is validated by automated processes. It produces multiple outputs from a single source. And it actively resists becoming outdated.

This pattern emerged from building what was originally known as the AI Capability Reference, now AI Tool Watch, which is an open-source site that tracks AI capabilities, pricing tiers, and platform support across 12 products. The data changes constantly: vendors update pricing, features move between tiers, platforms add or deprecate capabilities. A traditional static site would be stale within weeks. Knowledge as Code is how it stays current.

Six properties

Plain text canonical. Knowledge lives in human-readable, version-controlled files. No database, no CMS, no vendor lock-in. In this project: markdown and YAML files in data/.

Self-healing. Automated verification detects when the knowledge has drifted from reality. The system flags decay before humans notice it. In this project: a multi-model AI cascade cross-checks all data twice weekly, opens GitHub issues for human review.

Multi-output. One source produces every format needed. The results are human-readable, machine-readable, agent-queryable, and search-optimized. In this project: HTML site, JSON API, MCP server, 125 SEO bridge pages, sitemap, llms.txt.

Zero-dependency. No external packages. The build uses only language built-ins. Nothing breaks when you come back in a year. In this project: one Node.js script, no package.json, no node_modules.

Git-native. Git is the collaboration layer, the audit trail, the deployment trigger, and the contribution workflow. Issues, PRs, CI/CD, version history -- all through Git.

Ontology-driven. A vendor-neutral taxonomy of concepts maps to vendor-specific implementations. The structure is the data model. In this project: 18 capabilities map to 72 implementations across 12 products.

Why these compound

Any one of these is a reasonable design choice. The value is in the combination.

Plain text plus Git means anyone can contribute with no dev environment. Edit a file, open a PR. Plain text plus zero-dependency build means the project still builds in five years. Nothing to update, nothing to break.

Ontology plus multi-output means one correction fixes the site, the API, the MCP server, and every bridge page at once. Self-healing plus Git means verification results are tracked as issues with full audit trail. Nothing is silently changed. Zero-dependency plus self-healing means maintenance cost stays low even as the knowledge grows. The system scales through automation, not staffing.

The self-healing mechanism

This is the piece that makes Knowledge as Code more than "docs as code with a new name."

Twice a week, a three-layer multi-model verification cascade runs. Gemini, Perplexity, Grok, and Claude each cross-check every tracked data point: pricing tiers, platform availability, feature status, gating, regional restrictions. To prevent provider bias, models are skipped when verifying their own platform (Gemini doesn't verify Google features). A change only gets flagged when at least three models agree on a discrepancy.

Flagged changes become GitHub issues for human review. Nothing auto-merges. Every data point carries a Checked date; anything not re-verified within seven days is treated as stale.

Link integrity gets checked every week too, using both automated CI checks and a browser-based checker that runs through real Chrome to bypass bot protection.

This is anti-entropy for knowledge. In distributed systems like Dynamo and Cassandra, anti-entropy is the process that detects and repairs divergence from desired state. The verification cascade does the same thing, it finds where reality has moved away from what the files say and flags the gap.

Standing on shoulders

This pattern draws from established work:

File over app. Steph Ango's argument that durable digital artifacts must be files you can control, in formats that are easy to retrieve and read. Derek Sivers on plain text permanence. The permacomputing movement on resilient, minimal-dependency software.

Docs as code. Managing documentation with the same tools as software -- version control, pull requests, CI, plain text formats. Popularized by the Write the Docs community. Tom Preston-Werner (Jekyll, 2008), Eric Holscher (Read the Docs), Anne Gentle (Docs Like Code, 2017), Andrew Etter (Modern Technical Writing, 2016).

Living documentation. Cyrille Martraire's framework for documentation that evolves at the same pace as the system it describes. His approach generates docs from code annotations and tests. This pattern extends the idea: the knowledge isn't derived from code, and verification uses AI models rather than test suites.

GitOps. Coined by Weaveworks (2017). Git as single source of truth, with automated agents that detect drift between declared state and actual state, then reconcile. Originally for infrastructure, but it maps directly to knowledge:

GitOps (infrastructure)	Knowledge as Code
YAML declares desired state	Markdown declares what's true
Controller detects drift	AI cascade detects drift from reality
Auto-reconciliation or alert	GitHub issues for human review
Git as single source of truth	Git as single source of truth

Multi-model verification. Academic foundations for using multiple AI models as cross-checking judges: Zheng et al.'s "Judging LLM-as-a-Judge" (NeurIPS 2023), Verga et al.'s "PoLL: Panel of LLM Evaluators" (2024), Du et al.'s "Multiagent Debate" (2023), Huang & Zhou's "LLMs Cannot Self-Correct Reasoning Yet" (ICLR 2024).

What we think is new

We haven't found prior art for these specific applications. If you know of any, we'd like to hear:

"Knowledge as Code" as a named pattern -- the "-as-code" lineage is well-established, but this specific application to maintained knowledge bases doesn't appear to be named
AI verification cascades for documentation -- multi-model evaluation exists in academic literature, but applying it as a scheduled process to maintain a knowledge base's factual accuracy
Multi-format output from the same plain text -- HTML, JSON API, MCP endpoints, and SEO bridge pages, all from markdown/YAML, with zero dependencies
Ontology-driven static site generation -- using a formal taxonomy to drive site structure, navigation, and programmatic pages

Try it

The entire project is open source. There is nothing to install.

git clone https://github.com/snapsynapse/knowledge-as-code.git
cd knowledge-as-code
node scripts/build.js
open docs/index.html

GitHub repo | Homepage

This is a working title and an active discussion. If you've seen this pattern elsewhere, named or unnamed, tell us. Built by SnapSynapse.

HardGuard25: A 25-character alphabet for human-readable unique IDs

snapsynapse — Tue, 10 Mar 2026 12:01:00 +0000

Standard ID alphabets include characters that look identical at normal reading sizes. O and 0. I and 1 and l. S and 5. B and 8. For dyslexic readers, d and b, q and p. Every one of these is a support ticket, a failed lookup, or a phone call where someone spells the same code three times.

Crockford Base32 has been the go-to fix since 2002, but it only removes 4 characters. HardGuard25 removes 11: the digit lookalikes, the dyslexia mirror pairs, and operator lookalikes like T (+) and X (*) that break spreadsheets and URLs.

The alphabet:

0 1 2 3 4 5 6 7 8 9 A C D F G H J K M N P R U W Y

The rule: when a letter and a digit compete for the same visual slot, the digit always wins.

Quickstart

JavaScript

npm install @snapsynapse/hardguard25

import { generate, validate, normalize, checkDigit } from '@snapsynapse/hardguard25';

generate(8);                          // "AC3H7PUW"
generate(8, { checkDigit: true });    // "AC3H7PUW" + check char
validate("AC3H-7PUW");               // true
normalize("ac3h-7puw");              // "AC3H7PUW"

Python

pip install hardguard25

from hardguard25 import generate, validate, normalize, check_digit

generate(8)                           # "AC3H7PUW"
generate(8, check_digit=True)         # "AC3H7PUW" + check char
validate("AC3H-7PUW")                # True
normalize("ac3h-7puw")               # "AC3H7PUW"

import "github.com/snapsynapse/hardguard25/go"

id, _ := hardguard25.Generate(8)
ok := hardguard25.Validate("AC3H-7PUW")
s := hardguard25.Normalize("ac3h-7puw")

No library needed? The alphabet is the standard. Use it directly: 0123456789ACDFGHJKMNPRUWY

Where it fits

Order numbers, tracking codes, license keys, patient IDs, booking references, device IDs, promo codes, QR payloads, one-time passcodes. If it gets printed on a label, read over the phone, entered by hand, or scanned by OCR, it should be HardGuard25.

How long should IDs be?

Length	Unique IDs	Good for
4	390,625	Small inventory, tickets
6	244 million	Medium businesses
8	152 billion	Large systems
16	3.55 x 10^22	Cross-system identifiers

Each character provides 4.64 bits of entropy.

When not to use it

Cryptographic keys (use proper key derivation), blockchain consensus (use domain-specific formats), systems requiring UUID guarantees (use UUIDv7 or ULID), or machine-only contexts where no human ever sees the ID.

Links

Spec is CC BY 4.0. Code is MIT.

What character set are you using for human-facing IDs? Curious how many people have hit the O/0 problem in production.