Agent scaffolding setup

AGENTS.md

@@ -0,0 +1,135 @@
+# OpenTag3D agent guide
+
+Guidance for AI coding agents working in this repository. This file owns routing, hard boundaries, co-change rules, and minimal verification. Deeper procedures live in `_docs/` and nested `AGENTS.md` files.
+
+## What this repo is
+
+OpenTag3D is an open, community-driven specification for RFID/NFC tags on 3D-printer filament spools. This repository is the public home for the spec and the source for the [opentag3d.info](https://opentag3d.info) Jekyll site.
+
+The repo is a website, but it publishes a binary data contract. Some edits are fixed by the next deploy; others are written onto physical tags or consumed by third-party firmware/apps. Match caution to blast radius.
+
+The spec defines hardware, mechanical placement, on-tag data structure, and an optional Web API. Tag data must remain authoritative offline; the Web API can never become required for reading a tag.
+
+Spec governance belongs to the OpenTag3D Consortium described in `about.md`. Site/code fixes are normal PR work; `core` field layout and version changes are standards decisions.
+
+## Where to start
+
+| If you're... | Read first | Key rule |
+| --- | --- | --- |
+| A new/outside contributor or their agent | `_docs/contributor-agent-guide.md` | Propose high-blast-radius changes; do not silently change the spec contract. |
+| The maintainer or a trusted maintainer-directed agent | `_docs/maintainer-runbooks.md` | Use runbooks for triage, review, release, and context upkeep. |
+| Editing site content/supporters | This file's gotchas and co-change map | Supporter data can live in two places. |
+| Editing `make.html` / `read.html` | `_docs/make-read-tools.md` and `assets/scripts/AGENTS.md` | Pages expect `globalThis.OpenTag3D.spec` before shared code runs. |
+| Touching `assets/scripts/opentag3d.js` | `assets/scripts/AGENTS.md` | Round-trip verify; Web NFC/config pages require extra caution. |
+| Touching `_data/spec.json` | `_data/AGENTS.md` | Classify the edit first; `core` layout is a proposal, not a casual commit. |
+| Cutting a version/release | `_docs/spec-change-process.md` | Maintainer-only unless explicitly delegated. |
+| "Fixing" something that seems missing | `_docs/known-gaps.md` | Known gaps are not unprompted work. |
+
+## Tech stack
+
+- Jekyll 4.4 with the `minimal-mistakes-jekyll` theme.
+- Markdown/YAML front matter plus a few raw HTML pages.
+- Vanilla browser ES modules; no JS bundler/framework.
+- Node/npm is used for Prettier formatting only.
+- Web NFC requires a secure browser context for real tag reads/writes.
+
+## The spec is data-driven
+
+Edit `_data/spec.json`, not root `spec.json`.
+
+- `_data/spec.json` is the source of truth for version, MIME type, `core` byte fields, and `web_api` fields.
+- `spec.md`, `_includes/spec_table.md`, and `_includes/memory_map.html` render human-readable spec pages from `site.data.spec`.
+- Root `spec.json` is a Jekyll page that publishes `site.data.spec` at `/spec.json`.
+- `assets/json/spec_v*.json` files are frozen legacy snapshots used by `opentag3d.js` to decode old major versions.
+
+## Directory map
+
+| Path | Purpose |
+| --- | --- |
+| `*.md`, `*.html` | Jekyll pages and tools |
+| `_docs/` | Unpublished agent/contributor reference docs |
+| `_data/` | Site/spec data; read `_data/AGENTS.md` before editing spec/supporter data |
+| `_includes/` | Liquid partials/templates |
+| `_sass/` | Theme overrides |
+| `assets/scripts/` | Shared browser JS; read `assets/scripts/AGENTS.md` before protocol edits |
+| `assets/json/` | Frozen legacy spec snapshots; do not edit casually |
+| `articles/` | Blog-style posts, linked manually |
+| `.github/workflows/` | Build, format, and Pages deploy workflows |
+
+## Build, dev, and verification
+
+Common commands:
+
+```bash
+bundle exec jekyll build
+npm run format:check
+npm run format
+```
+
+Local HTTPS dev server, per `README.md`:
+
+```bash
+./setup.sh
+npm start
+```
+
+Verify by change type:
+
+| Change type | Minimum verification |
+| --- | --- |
+| Markdown/content/Liquid | `bundle exec jekyll build`; browser check if rendered layout matters |
+| `js`/`scss`/`json`/`yml`/`yaml` | `npm run format:check` |
+| `make.html` / `read.html` UI | Jekyll build plus browser check of affected flow |
+| `opentag3d.js` protocol logic | Node round-trip recipe in `assets/scripts/AGENTS.md` plus browser check |
+| `_data/spec.json` | `_data/AGENTS.md` checklist, changelog, byte-map checks as applicable |
+| Web NFC write/config behavior | Ask first; verify with supported Chrome/Android/Web NFC and a disposable tag, or state not locally verified |
+
+CI runs Jekyll build and Prettier checks. GitHub Pages deploys `main` to production; there is no staging environment in this repo.
+
+## Boundaries
+
+Always:
+
+- Edit `_data/spec.json`, never root `spec.json`, when changing spec data.
+- Pair `_data/spec.json` changes with a `spec.md` changelog entry.
+- Keep Jekyll build and `npm run format:check` green for touched file types.
+- Keep tag data usable offline; the Web API is supplemental only.
+
+Ask first:
+
+- Any `core` field layout, requiredness, size, meaning, or top-level `version` change.
+- NTAG config-page, AUTH0/PWD/PACK, or Web NFC write-path edits.
+- Adding a supporter without matching issue/maintainer context.
+- Workflow, `Gemfile`, `package.json`, or release-process changes.
+
+Never:
+
+- Push directly to `main`; it is production.
+- Create or push git tags unless the maintainer explicitly instructs you.
+- Edit an existing `assets/json/spec_v*.json` casually.
+- Make the Web API required for tag interpretation.
+- Edit consortium/governance membership in `about.md` unprompted.
+
+## Co-change map
+
+| When you change... | Also update/check... |
+| --- | --- |
+| `_data/spec.json` anything | `spec.md` changelog |
+| `_data/spec.json` `version`, major bump | New frozen `assets/json/spec_v{oldMajor}.json` before current layout changes |
+| `_data/spec.json` `core` layout | Byte-map stamp/table in `_docs/spec-data-model.md` |
+| Supporter status/details | `_data/supporters.yml` and affected `getting-started.md` tables |
+| New article | A link from somewhere; articles are not auto-listed |
+| Workflows, scripts, directories, or agent-routing assumptions | This file and the owning `_docs/` page |
+
+## Gotchas
+
+- Root `spec.json` and `_data/spec.json` have different roles. The root file publishes data; `_data/spec.json` is the editable source.
+- `make.html` and `read.html` depend on an inline Jekyll script setting `globalThis.OpenTag3D.spec` before `opentag3d.js` evaluates.
+- Existing `assets/json/spec_v*.json` snapshots support tags already in the field.
+- `getting-started.md` duplicates some supporter/product data by hand.
+- New `articles/` pages are not discovered automatically.
+- There are no automated protocol tests yet; verification evidence matters.
+
+## Keeping context current
+
+If an agent doc is wrong, fix it in the same PR as the work that exposed the problem. If you add a rule, put it in the one place it belongs and link to it; see `_docs/decisions.md`.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -25,6 +25,8 @@ Want to provide a financial contribution? Donate to the Gooborg Studios' founder
 
 ## Website Development
 
+Contributor and AI-agent notes: see [`AGENTS.md`](./AGENTS.md) and [`_docs/`](./_docs/).
+
 To start a local version of the website for development, you will need Node.js and Ruby. Run the `setup.sh` script to run the setup commands, and then `npm start` to start the web server.
 
 > [!NOTE]

_config.yml

@@ -26,6 +26,12 @@ og_image: /assets/images/og_image.jpg
 atom_feed:
   hide: true
 
+exclude:
+  - AGENTS.md
+  - CLAUDE.md
+  - assets/scripts/AGENTS.md
+  - OpenTag3D-agent-scaffolding/
+
 defaults:
   - scope:
       path: ""

_data/AGENTS.md

@@ -0,0 +1,41 @@
+# `_data/` agent notes
+
+This file owns local rules for data files. Root `AGENTS.md` routes here before spec/supporter data edits.
+
+## `spec.json`: classify the edit first
+
+`_data/spec.json` is the editable source for the public spec data. The root `spec.json` page is generated from it; do not edit root `spec.json` to change the spec.
+
+| Edit class | Typical version effect | Agent posture |
+| --- | --- | --- |
+| Description or wording clarification | patch | Do it when requested; add a `spec.md` changelog entry. |
+| New `web_api` field | minor | Do it when requested; add changelog; flag as a spec change in PR notes. |
+| New `core` field in unused space | minor | Draft as a proposal; maintainer/consortium decides. |
+| Move, resize, remove, or reinterpret a `core` field | major/breaking | Proposal only; legacy snapshot requirement applies. |
+| Top-level `version` change | release-dependent | Ask first unless explicitly assigned by maintainer. |
+
+## `core` field checklist
+
+Before changing any `core.fields` byte layout, read `_docs/spec-data-model.md` and verify:
+
+- `type` is implemented by `encodeFieldValue()` and `decodeTagBuffer()` in `assets/scripts/opentag3d.js`: `int`, `utf8`, `ascii`, `rgba`, `date`, or `time`.
+- No byte range overlaps another field.
+- `start` + `length` fits inside `core.address_range`.
+- `id` remains unique and stable unless the change is explicitly breaking.
+- `added` is set to the introducing spec version.
+- `_data/spec.json` and `spec.md` changelog change together.
+- Major bumps freeze the old layout into `assets/json/spec_v{oldMajor}.json` before current fields move.
+
+Unrecognized `core` types can fail silently during decode. Jekyll build success is not proof a spec edit is safe.
+
+## `supporters.yml`
+
+Supporter entries should come from a GitHub issue or maintainer direction. The enum lists at the top of the file are authoritative for `category` and `implstage` values.
+
+Some supporter/product facts are duplicated by hand in `getting-started.md` tables. When a requested supporter edit affects those tables, update both files or say clearly why only one changed.
+
+Do not add or change consortium/governance membership in `about.md` as part of a supporter-data task unless explicitly asked.
+
+## `navigation.yml`
+
+Navigation changes are site UX changes. Verify the target page/link exists and run the normal Jekyll build/format checks.

_docs/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent reference docs
+
+These docs are unpublished working context for contributors and AI coding agents. Start at root `AGENTS.md`; use this index when a task needs deeper context.
+
+- [`contributor-agent-guide.md`](contributor-agent-guide.md): outside-contributor safety model and escalation rules.
+- [`maintainer-runbooks.md`](maintainer-runbooks.md): trusted maintainer workflows for review, triage, releases, and context upkeep.
+- [`make-read-tools.md`](make-read-tools.md): architecture and verification expectations for `make.html`, `read.html`, and page-local tool code.
+- [`spec-data-model.md`](spec-data-model.md): `_data/spec.json` field model, type enum, byte budget, and recompute command.
+- [`spec-change-process.md`](spec-change-process.md): observed path from spec idea to release/deploy.
+- [`known-gaps.md`](known-gaps.md): known missing automation/process gaps with safe workarounds; not an unprompted work queue.
+- [`decisions.md`](decisions.md): settled agent-context decisions and rationale.

_docs/contributor-agent-guide.md

@@ -0,0 +1,52 @@
+# Contributor and agent guide
+
+This guide is for outside contributors and their AI agents. It owns the safety posture for non-maintainer work; detailed protocol checklists live in `_data/AGENTS.md` and `assets/scripts/AGENTS.md` once those files are added.
+
+## Safety model
+
+OpenTag3D is both a website and a published data contract. Some edits are fixed by the next deploy; others affect bytes written to physical NFC tags or implementations that consume `/spec.json`.
+
+If in doubt, open a proposal or ask first. Do not silently change the spec contract.
+
+## Usually routine changes
+
+These are usually safe when the requested change is clear:
+
+- Prose fixes in Markdown pages.
+- Link or copy updates with an obvious source of truth.
+- Small styling changes, verified with a Jekyll build and browser check.
+- Supporter updates when there is matching issue or maintainer context, and all duplicated locations are kept in sync.
+
+Still run the relevant verification and say what you checked in the PR notes.
+
+## Changes that need extra context
+
+- `_data/spec.json`: read `_data/AGENTS.md` and classify the edit before changing anything.
+- `make.html` or `read.html`: read [`make-read-tools.md`](make-read-tools.md); shared protocol changes also require `assets/scripts/AGENTS.md`.
+- `assets/scripts/opentag3d.js`: treat byte encode/decode, NDEF/NTAG packing, import/export, and Web NFC as protocol work.
+- Releases, tags, spec version bumps, workflows, `Gemfile`, and `package.json`: ask first unless the maintainer explicitly assigned the task.
+
+## Propose, do not silently implement
+
+Open a proposal or stop for maintainer direction before:
+
+- Changing `core` field layout, field sizes, requiredness, or the spec `version`.
+- Editing Web NFC write behavior or NTAG config pages.
+- Editing legacy snapshots in `assets/json/spec_v*.json`.
+- Making the web API required for tag interpretation; offline tag data is authoritative.
+- Changing governance/consortium records in `about.md` unprompted.
+
+## Co-change reminders
+
+Use the co-change map in root `AGENTS.md` once added. Until then, key pairs are:
+
+- `_data/spec.json` changes need a `spec.md` changelog entry.
+- Major spec bumps need a frozen legacy snapshot before the current layout changes.
+- Supporter status/details may appear in both `_data/supporters.yml` and `getting-started.md`.
+- New articles are not auto-listed; link them intentionally from somewhere.
+
+## Known gaps are not a work queue
+
+[`known-gaps.md`](known-gaps.md) documents missing automation, suspected findings, and manual workarounds so agents do not rediscover them. It is not permission to fix those items unprompted.
+
+When you encounter a known gap, follow its "Meanwhile" line. If it blocks the requested work, report that and ask how to proceed.

_docs/decisions.md

@@ -0,0 +1,81 @@
+# Agent-context decisions
+
+Short decision log for agent scaffolding. Format: Decision · Why · Revisit when.
+
+## Tiered agent context
+
+Decision: use root `AGENTS.md`, nested `AGENTS.md` files in `_data/` and `assets/scripts/`, and reference docs in `_docs/`.
+Why: a single root file would have to carry every checklist and would be too large for routine work.
+Revisit when: tooling or repo structure makes local checklists unnecessary.
+
+## `_docs/` for reference docs
+
+Decision: keep agent reference docs in `_docs/`.
+Why: Jekyll ignores underscore-prefixed directories by default, it matches the repo's `_data`/`_includes` idiom, and it avoids publishing agent context as website content.
+Revisit when: Jekyll configuration changes to publish `_docs/` or the maintainer wants a different private-doc location.
+
+## Known gaps stay short and in-repo for now
+
+Decision: keep a neutral [`known-gaps.md`](known-gaps.md) with safe workarounds; convert items to GitHub issues only if the maintainer asks.
+Why: agents need the "meanwhile" guidance to avoid rediscovering gaps or fixing them opportunistically.
+Revisit when: the maintainer chooses an issue-tracking workflow.
+
+## `AGENTS.md` is canonical; `CLAUDE.md` is a shim
+
+Decision: root `AGENTS.md` is the cross-tool source. `CLAUDE.md` should only import it.
+Why: multiple agent tools read `AGENTS.md`; duplicating guidance would drift.
+Revisit when: tool conventions change.
+
+## Root README pointer
+
+Decision: add one root `README.md` line pointing contributors/agents to `AGENTS.md` and `_docs/`.
+Why: humans browsing the repo need a visible entry point.
+Revisit when: a future `CONTRIBUTING.md` becomes the better entry point.
+
+## One PR with separable commits
+
+Decision: land the reflow as one PR split into independently reviewable commits.
+Why: two PRs would ship temporary duplication first; separable commits still let the maintainer drop pieces.
+Revisit when: review requests a narrower PR.
+
+## Agent docs describe the repo, not one machine
+
+Decision: do not add Windows-local dev-server notes to root agent rules.
+Why: they would document one contributor environment and go stale.
+Revisit when: the maintainer wants a supported Windows/WSL development guide.
+
+## No guessed house-style section yet
+
+Decision: do not invent PR or house-style conventions before maintainer review teaches them.
+Why: process details are currently undocumented and should not be guessed from history.
+Revisit when: this PR review reveals stable conventions.
+
+## One home per fact
+
+Decision: each operational fact should have one owning doc; other docs link to it.
+Why: duplicated warnings like "main is production" and "no tests" drift and bloat context.
+Revisit when: a fact is repeated often enough that its ownership is unclear.
+
+## Point, do not copy
+
+Decision: agent docs point to source files for volatile/public facts instead of restating them.
+Why: consortium membership, version semantics, field lists, and changelog details already have public homes.
+Revisit when: a source file lacks enough context for safe agent work.
+
+## Separate stable from volatile
+
+Decision: stable architecture can be prose; volatile facts need verification stamps or recompute commands.
+Why: byte maps, counts, line numbers, and versions go stale quickly.
+Revisit when: scripts/CI replace manual commands.
+
+## Rules, not research
+
+Decision: final agent docs state what to do and why, not how the fact was discovered.
+Why: research narrative belongs in git history and planning commits.
+Revisit when: provenance is needed for a specific disputed decision.
+
+## Mechanical rules should migrate into checks
+
+Decision: prose checklists are temporary homes for rules that can eventually be scripted.
+Why: executable checks reduce context load and review burden.
+Revisit when: adding or changing a checklist item that could be automated.