Atproto Web Names & Origins #

Read the published draft: https://atproto-web-names.szzt.app/

spec.md is the authoritative source. The publishing build generates an independent Unofficial Draft in ReSpec's standards-document style. It is not a W3C publication.

Local preview #

Requires Node 24+ and Chrome/Chromium. On this machine the build finds the installed Google Chrome automatically. Elsewhere, Puppeteer's downloaded browser is used, or set PUPPETEER_EXECUTABLE_PATH to an installed browser.

npm ci
npm test
npm run build
npm run check
npm run preview

Open http://127.0.0.1:4173/. The server binds only to loopback; set PORT to change its port. Rebuild after editing the source, then refresh the browser.

If you already have Chrome and want to skip Puppeteer's browser download, install with PUPPETEER_SKIP_DOWNLOAD=true npm ci.

Build and validation #

• scripts/convert.mjs converts Markdown to nested sections with stable semantic IDs, derives the section-number mapping, links textual references, and marks the explicitly defined terminology and informative appendices.
• ReSpec generates the title block, status, section numbering, TOC, RFC 2119/8174 conformance boilerplate, syntax highlighting, and references. Its version is pinned.
• Mermaid CLI renders the lifecycle diagram to SVG. Section references in the diagram and in untyped address-example annotations follow the generated numbering. Typed code blocks (including the normative JSON lexicon) are preserved verbatim.
• dist/ contains static HTML, local styles/images, a copy of the Markdown source, and build-report.json. Internal checklists and implementation assessments are not included in the published site. No runtime scripts or remote rendering dependencies are required. W3C's styles/assets are fetched at build time and cached under .build/cache/; the first build needs network access.
• npm run check checks unique IDs, internal links, actual section numbers, and local assets, then renders desktop/mobile previews with JavaScript disabled and external requests blocked. Screenshots are written to .preview/.

Markdown and rendered section numbering both start at 1 and must agree. Stable HTML IDs do not depend on the numbers. Invalid source references are reported, not silently repaired, and npm run check rejects a build containing any. The converter also rejects unexpected setext headings, catching missing whitespace before dividers. Revision fixes and remaining publication tasks are tracked in REVISION-TODO.md.

publication.json holds display metadata. The editor is @burrito.space, the date is September 14, 2026, and the intended latest-version URL is https://atproto-web-names.szzt.app/. Document licensing is intentionally pending. The build inserts an explicit custom rights notice stating that publication grants no license, rather than accidentally granting ReSpec's default unofficial-draft license. preview: false selects a publication build; building never uploads anything.

Dependency audit: the Mermaid CLI currently pulls a KaTeX version with a low-severity upstream advisory (GHSA-238p-pmpm-9mq7). These are build-only dependencies, the trusted source has no math, and none of this JavaScript is shipped in dist/.

Implementation assessments #

• SZZT-ANALYSIS.md separates route publishing, a szzt handler, and full client conformance, with code-level gaps and suggested acceptance tests.
• PEEK-ANALYSIS.md proposes core navigation and verified-content support in Peek: resolver/handler boundaries, isolated origins and sessions, rollback state, trusted UI, storage tiers, and staged acceptance gates.

These are read-only assessments of the inspected sibling projects. The write-ups live here; no implementation changes to those projects are in scope.

Publishing #

Published draft: https://atproto-web-names.szzt.app/. The current publish result is saved in publication-receipt.json, with prior results in publication-history.json; public byte/layout verification is recorded in publication-verification.json. All three are gitignored because they carry the publishing account's DID, so they exist only in the checkout that publishes. Updates must reuse its siteRkey and pass its tileCid as --prev—do not create a new site or re-claim the slug.

Szzt adds its own web-app metadata/service-worker registration during packaging; the specification itself remains readable with JavaScript disabled.

Publication is an explicit user-authorized step. Review the revision checklist and metadata before uploading; licensing remains deliberately undecided.

The neighboring ../szzt checkout has a working built CLI and environment-based credentials. It does not need a service deployment or a manual browser upload:

node ../szzt/packages/agent/dist/cli.js publish dist --name "Atproto Web Names & Origins" --slug atproto-web-names --json

For an update, pass the previously returned --site-rkey and --prev manifest CID to preserve the site's URL and version lineage, and omit --slug after the initial claim. Keep the publish receipt. Slug allocation is effectively permanent; the initial command above deliberately claims the agreed publication name.

Credentials belong only in the process environment, never in this repository or command-line flags. The generated preview and checks do not access publishing credentials or write anything to the PDS.