diff --git a/.gitignore b/.gitignore
index 9f09a5a..24a1576 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@ node_modules
_site
dist
.vscode
+data/bookmarklets.json
+data/auditing.json
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..49726d8
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,153 @@
+# Contributing
+
+Thanks for your interest in contributing to this bookmarklet collection.
+
+## Quick start
+
+1. Run the scaffolding script:
+ ```bash
+ npm run new -- --name "My Tool" --author "Your Name" --description "What it does" --tags "accessibility"
+ ```
+
+2. Edit the generated JS file in `bookmarklets/`
+
+3. Add test content to the generated HTML file (if applicable)
+
+4. Run `npm start` to test locally
+
+5. Submit a PR
+
+## Manual setup
+
+If you prefer to create files manually:
+
+1. Create a JS file in `bookmarklets/` with a JSDoc metadata block
+2. Optionally create a matching HTML test page (no frontmatter needed)
+3. Run `npm start` to lint, build, and preview
+
+## Metadata fields
+
+Every bookmarklet needs a JSDoc comment block at the top of the file:
+
+```javascript
+/**
+ * @bookmarklet My Bookmarklet Name
+ * @description What the bookmarklet does
+ * @author Your Name
+ * @authorUrl https://example.com
+ * @tags accessibility, wcag:1.4.3
+ * @pageTest true
+ */
+(function() {
+ // Your bookmarklet code here
+})();
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `@bookmarklet` | Yes | Display name of the bookmarklet |
+| `@description` | Yes | Brief description of what it does |
+| `@author` | No | Original author's name |
+| `@authorUrl` | No | Link to author or source |
+| `@tags` | Yes | Comma-separated list of tags (see taxonomy below) |
+| `@auditing` | No | Set to `true` for auditing favorites |
+| `@pageTest` | No | `true`, `false`, or `self` (see test pages below) |
+
+## Tag taxonomy
+
+Tags are validated at build time. Each bookmarklet needs at least one category tag.
+
+### Category tags (required, pick one)
+
+| Tag | Description |
+|-----|-------------|
+| `accessibility` | Accessibility testing and visualization tools |
+| `diagnostic` | Page information and debugging tools |
+| `utility` | Convenience and productivity tools |
+
+### Modifier tags (optional)
+
+| Tag | Description |
+|-----|-------------|
+| `external` | Loads external scripts or redirects to external services |
+
+### WCAG tags (optional)
+
+Format: `wcag:X.X.X` where X.X.X is the success criterion number.
+
+Examples:
+- `wcag:1.4.3` (Contrast)
+- `wcag:2.4.7` (Focus Visible)
+- `wcag:4.1.2` (Name, Role, Value)
+
+### Tag examples
+
+```javascript
+// Accessibility tool for checking headings
+@tags accessibility, wcag:1.3.1, wcag:2.4.6
+
+// External accessibility tool
+@tags accessibility, external
+
+// Simple utility
+@tags utility
+```
+
+## Test pages
+
+Test pages let users try a bookmarklet on sample content.
+
+### `@pageTest` values
+
+| Value | Meaning | HTML file needed? |
+|-------|---------|-------------------|
+| `true` | Dedicated test page with specific content | Yes |
+| `self` | Works on any page, use the bookmarklet listing page | No |
+| `false` | No test needed (e.g., redirects to external service) | No |
+
+### Creating a test page
+
+If `@pageTest` is `true`, create an HTML file with the same base name:
+- `bookmarklets/my-tool.js` needs `bookmarklets/my-tool.html`
+
+The HTML file contains only the test content (no frontmatter needed):
+
+```html
+Test page for My Tool
+Content that exercises the bookmarklet's functionality.
+```
+
+## Build process
+
+The build process:
+1. Lints all JS files with ESLint and Prettier
+2. Extracts metadata from JS files
+3. Generates `data/bookmarklets.json` and `data/auditing.json`
+4. Minifies and encodes each bookmarklet
+5. Generates Netscape bookmark HTML files
+6. Validates metadata completeness and tag taxonomy
+7. Builds the static site with Eleventy
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Lint, build, and start dev server |
+| `npm test` | Lint and build (CI) |
+| `npm run build` | Build data files only |
+| `npm run new -- --name "Name"` | Scaffold a new bookmarklet |
+
+## Submitting a PR
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run `npm test` to verify linting and build pass
+5. Submit a pull request
+
+### PR checklist
+
+- [ ] Bookmarklet has all required metadata fields
+- [ ] Tags follow the taxonomy (category + optional WCAG)
+- [ ] Test page exists if `@pageTest` is `true`
+- [ ] `npm test` passes
diff --git a/README.md b/README.md
index 3387121..82557bc 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,50 @@ Tools for the browser.
## Adding a bookmarklet
-1. Edit [`data/bookmarklets.json`](/data/bookmarklets.json) and add a new entry, following the schema used on the rest of the file
-2. Create a new JS file (and optionally a test HTML page) for the new entry
-3. Add code
-4. Run `npm start` to lint JS, build data file, and generate static site
-5. New entry will be added to the table of bookmarklets in `index.html`
+Use the scaffolding script to create the required files:
+
+```bash
+npm run new -- --name "My Bookmarklet" --author "Your Name" --description "What it does" --tags "accessibility"
+```
+
+This creates:
+- `bookmarklets/my-bookmarklet.js` with metadata template
+- `bookmarklets/my-bookmarklet.html` test page stub
+
+Then edit the generated files and run `npm start` to test locally.
+
+### Manual setup
+
+Alternatively, create files manually:
+
+1. Create a JS file in `bookmarklets/` with a JSDoc metadata block:
+ ```javascript
+ /**
+ * @bookmarklet My Bookmarklet Name
+ * @description What the bookmarklet does
+ * @author Your Name
+ * @authorUrl https://example.com
+ * @tags accessibility, utility
+ * @pageTest true
+ */
+ (function() {
+ // Your bookmarklet code here
+ })();
+ ```
+2. Optionally create a test HTML page in `bookmarklets/` with the same base name (no frontmatter needed)
+3. Run `npm start` to lint JS, build data files, and generate the static site
+
+### Metadata fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `@bookmarklet` | Yes | Display name of the bookmarklet |
+| `@description` | Yes | Brief description of what it does |
+| `@author` | No | Original author's name |
+| `@authorUrl` | No | Link to author or source |
+| `@tags` | No | Comma-separated list of tags |
+| `@auditing` | No | Set to `true` for auditing favorites |
+| `@pageTest` | No | `true`, `false`, or `self` for test page behavior |
## Related web tools
diff --git a/bookmarklets/are-ya-hidden.html b/bookmarklets/are-ya-hidden.html
index 0f88cd7..e296f44 100644
--- a/bookmarklets/are-ya-hidden.html
+++ b/bookmarklets/are-ya-hidden.html
@@ -1,10 +1,3 @@
----
-permalink: "are-ya-hidden/"
-file: "are-ya-hidden.js"
-layout: test
-title: are ya hidden
----
-