digitalcredentials · jchartrand · Dec 22, 2025 · Dec 22, 2025 · Dec 22, 2025 · Dec 22, 2025
diff --git a/.gitignore b/.gitignore
@@ -25,12 +25,6 @@ coverage
 # nyc test coverage
 .nyc_output
 
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
 # node-waf configuration
 .lock-wscript
 
@@ -41,12 +35,6 @@ build/Release
 node_modules/
 jspm_packages/
 
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
-*.tsbuildinfo
-
 # Optional npm cache directory
 .npm
 
@@ -62,78 +50,17 @@ web_modules/
 # Output of 'npm pack'
 *.tgz
 
-# Yarn Integrity file
-.yarn-integrity
-
 # dotenv environment variable files
 .env
 .env.*
 !.env.example
 
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp and cache directory
-.temp
-.cache
-
-# Sveltekit cache directory
-.svelte-kit/
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
 # Serverless directories
 .serverless/
 
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Firebase cache directory
-.firebase/
-
-# TernJS port file
-.tern-port
-
 # Stores VSCode versions used for testing VSCode extensions
 .vscode-test
 
-# yarn v3
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
-
-# Vite logs files
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
+
+playwright-report/
+test-results/
diff --git a/README.md b/README.md
@@ -1,2 +1,132 @@
 # veri-good
-web component for verifying Verifiable Credentials
+
+A [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) for verifying [Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/).
+
+Web components are custom HTML tags that work natively with all modern browsers, and can therefore be dropped into any HTML page, which you'd do like so for the veri-good element:
+
+```
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>veri-good!</title>
+  </head>
+  <body>
+    <div style="font-size: 20px"></div>
+    <div style="padding: 5em">
+      <veri-good></veri-good>
+    </div>
+    <script type="module" src="=bundle.js"></script>
+  </body>
+</html>
+```
+
+You'll therefore need to have saved that bundle.js (which is in the dist directory of this repository) to your server.
+
+If you are using a bundler (webpack, rollup, etc.) import the module which we've published to npm:
+
+`import '@digitalcredentials/veri-good'`
+
+The import automagically registers the component with the browser. Use the tag wherever you like.
+
+We also provide a separate package that wraps the web component in a react element:
+
+* [@digitalcredentials/veri-good-react github repo](https://github.com/digitalcredentials/veri-good-react)
+* [@digitalcredentials/veri-good-react npm package](https://github.com/digitalcredentials/veri-good-react)
+
+TODO: fix above links to react packages once published
+
+### Issuer List
+
+ The signing DID for each credential is looked up in the issuer list. For the moment it defaults to the above list, i.e.,
+
+ ```https://digitalcredentials.github.io/dcc-known-registries/known-did-registries.json```
+
+You can look at that list as an example of how to build your own.
+
+You set the issuer list in a template inside the `veri-good` tag like so:
+
+  ```
+ <body>
+    <veri-good>
+        <template id="issuer-dids">
+          {
+            "did:web:digitalcredentials.github.io:testDID": {
+                "issuerName": "Department of Chemistry",
+                "url": "https://chemistry.uni.edu"
+            },
+            "did:key:z6MkjoriXdbyWD25YXTed114F8hdJrLXQ567xxPHAUKxpKkS": {
+                "issuerName": "Department of Economics",
+                "url": "https://econ.uni.edu"
+            }
+          }
+        </template>
+    </veri-good>
+    <script type="module" src="=bundle.js"></script>
+</body>
+ ```
+
+Use the same json structure for your own list.
+
+The issuerName and url are displayed when verifying a credential issued by that DID.
+
+### Programmatic Verification
+
+You can programmatically set the VC to be verified by calling the 'verify' method on the element, like so:
+
+ ```
+ <body>
+    <veri-good registry-list="https://digitalcredentials.github.io/dcc-known-registries/known-did-registries.json"></veri-good>
+    <script type="module" src="=bundle.js"></script>
+    <script>
+      const verifier = document.querySelector('veri-good')
+        verifier.addEventListener('veri-good-is-ready', (e) => {
+          verifier.verify("https://digitalcredentials.github.io/vc-test-fixtures/verifiableCredentials/v1/bothSignatureTypes/didKey/legacy-noStatus-noExpiry-basicOBv3.json")
+      });
+    </script>
+</body>
+ ```
+
+Notice that we have to wait for the web component to finish intializing, and fire the 'veri-good-is-ready' event before we can call the 'verify' method on it.
+
+You can of course also (and more likely) directly use the call in your own javascript that you bundle up with webpack or the like.
+
+You might use the 'verify' call for cases like:
+
+* immediately verifying a credential whose url has been passed in as a request parameter on your html page.
+* verifying a credential that the end user selects from a list of credentials on the page, like say in a web wallet
+
+### Customization
+
+#### Slots
+
+There are three 'slots' in the web component into which you can place custom html content:
+
+* header
+* wasAwarded
+* awardedBy
+
+Use them by including your custom content inside the `<veri-good>` tag like so:
+
+```
+<veri-good registry-list="https://digitalcredentials.github.io/dcc-known-registries/known-did-registries.json">
+    <div slot="header">
+        <div style="margin:.2em">University of Wonderful</div>
+        <div style="font-size:1.2em">Course Credential Verification</div>
+    </div>
+    <div slot="wasAwarded">earned</div>
+    <div slot="awardedBy">awarded byyyy</div>
+</veri-good>
+```
+
+The slots map into the verifier like so:
+
+TODO: add image of verifier with slots circled, arrows pointing to each with a label.
+
+You'll of course likely have to play with the css on your slots.
+
+If you don't provide content for the slots, the defaults will be used which look like so:
+
+TODO: add image with default content.
+
+