A static, self-contained blog published at https://blog.odicforcesounds.com.
There is no server and no build step between a file and the site: everything under
docs/ is the website, served by GitHub Pages. Alongside the pages live three
things that are generated rather than written — the sitemap, the JSON API and its text
chunks — plus the scripts that regenerate them.
- The archive — 546 HTML files at the root of
docs/: 543 articles, plusindex.html(the landing page),404.htmlandhome.html(a redirect stub kept for old links). The JSON API indexes 544 of them (index.htmlincluded) and leaves out the other two. The subject range is deliberately wide; see Topics covered. - Search on the landing page —
docs/index.htmlfilters its own category list from a single input, with no dependency and no second page to visit. - A 404 page —
docs/404.html, which GitHub Pages serves for missing paths, with its own search over the JSON API. - A comment form — on
index.htmlonly: Google, e-mail/password and phone number sign-in, a Firestore-backed thread, no anonymous posting. Rules inbackups/firebase-rules.txt; what was broken and how it was fixed inbackups/comments-login-failure.md; how to add back Facebook or GitHub inbackups/setup-facebook-github.md. - A static JSON API —
docs/api/index.json(metadata and a chunk manifest),docs/api/dates.json(name → publication instant, 25 KB, whatindex.htmlloads) anddocs/api/text/*.json(article text, 15 chunks). Built by.agents/skills/blog-ops/build_api.py, read bydocs/api.js. - Shared styling —
docs/page.css(the article family, generated by.agents/skills/page-css/),docs/link-colors.css(link colours by destination, generated by.agents/skills/link-colors/),docs/index.css,docs/style.css;docs/article.cssis the previous generation, still on disk and no longer linked. - Nine catalogues drawn from JSON, each painting one shelf only when it is opened:
docs/awesomeIndex.html(tools),docs/electronicsIndex.html(342 part families),docs/danceIndex.html(208 dance styles and martial arts, by culture and era),docs/worldIndex.html(246 countries, 3,856 regions, 236,907 cities, towns and villages), and the five nature shelves —docs/birdsIndex.html,docs/animalsIndex.html,docs/fishesIndex.html,docs/insectsIndex.html,docs/plantsIndex.html— whose data is also drawn on bydocs/lifeIndex.htmland, for the reptile orders,docs/reptilesIndex.html. Everything comes from.agents/skills/catalogue-data/builders/. - A living card on every page — one photograph of a being from the bird, animal, fish
or insect catalogue, then one sentence: this being likes to use a tool, loves an
electronic part and eats a plant while standing in a city, each of the five names
linking to its own shelf.
docs/living-panel.js(182 KB, 1,089 beings, 3,119 tools, 304 components, 265 plants and 246 cities) swaps the set on every load;index.htmlhas no card, because the social dock already holds that corner. - A temporary chat —
docs/secretChat.html: Google sign-in, messages that delete themselves after fifteen minutes,noindex, and no row in the archive on purpose. - A page template —
templates/dataDossier.html. - The feed pipeline for
index.html—docs/tools/feeds.json(feeds by category) injected into the page aswindow.FEED_DATAbydocs/tools/build.mjs. - Runbooks, in
backups/—CLOUDFLARE.md(DNS, proxy, bots, redirects, cache, headers, HSTS),GOOGLE.md(structured data, Search Console order of operations), the two comment documents above. None of them is published:backups/sits outsidedocs/. - The skills, in
.agents/skills/—blog-ops(the audit and build scripts:check_site.py,build_sitemap.py,enrich_schema.py),new-page(how a page is written and compiled),repo-layout(what belongs in which directory),git-dates(publication and update dates from git history),tmp-tools(scripts and scratch intmp/andtools/),assets-backups(templates, runbooks, images),tools-index(the path index for every script and binary),living-panel(the fixed card on every page: one being, a tool, a component, a plant and a city),link-colors(the colour-by-destination sheet),page-css(the shared article stylesheet) andseo-indexation(the read-only audit of what a crawler can index). Six more audit what those do not:link-integrity(does every link resolve, locally and over the network),page-weight(what a page downloads against a budget),security-headers(does each page's CSP permit what the page loads),a11y(alt text, document language, labels),catalogue-data(the JSON behind the eight index pages) andcomments(the Firebase comment form and the session-only chat). - Archive collections — third-party snapshots under
docs/archive/anddocs/obsdRouter/, kept for readers and excluded inrobots.txt.
devblog/
├── README.md
├── START-HERE.md the five limits: what an agent may touch at all
├── AGENTS.md no-tool-attribution rule + which skill owns which task
├── pushit.sh, update.sh deploy helpers (ksh)
├── .agents/skills/blog-ops/ build_api.py, check_site.py, build_sitemap.py, enrich_schema.py,
│ page_hygiene.py, commitit.sh
├── .agents/skills/*/ SKILL.md per skill (new-page, repo-layout, git-dates, tmp-tools,
│ assets-backups, tools-index, blog-ops, living-panel, link-colors, page-css,
│ seo-indexation, link-integrity, page-weight, security-headers, a11y,
│ catalogue-data, comments)
├── backups/ runbooks, originals, maps, firebase-rules.txt
├── docs/ ← published site root
│ ├── index.html landing page, categories, search, comment form
│ ├── 404.html error page (noindex), search over the API
│ ├── home.html redirect stub for the old page name
│ ├── *.html the 543 articles, the catalogues and the secret chat
│ ├── api/ generated: index.json + text/NNN.json
│ ├── api.js vanilla ES module that reads the API
│ ├── archive/, obsdRouter/, pdfs/, images/
│ ├── living-panel.js the card pool every page loads, generated by the living-panel skill
│ ├── article.css, index.css, style.css
│ ├── sitemap.xml, robots.txt, CNAME, .nojekyll
│ └── tools/ feed pipeline for index.html
├── templates/dataDossier.html
├── tools/ local scratch (gitignored)
└── tmp/ local scratch (gitignored)
GitHub Pages publishes the docs/ folder of main for the custom domain in
docs/CNAME. A Cloudflare proxy sits in front of it; the edge can change how the site
is crawled or inject scripts without a byte changing here, so the settings that matter
are written down in backups/CLOUDFLARE.md.
docs/.nojekyll is present so GitHub serves the tree exactly as it is. docs/404.html
is served, with a 404 status, for any path that does not exist.
-
Start from
templates/dataDossier.html, or copy the markup and inline CSS of a similar page. Pages are self-contained: their<style>and<script>live in the file. -
Keep the head contract. Every page has exactly one of each:
<title>,meta[name=description],link[rel=canonical], the Open Graph tags (og:title,og:description,og:type,og:url,og:site_name,og:image), the Twitter tags (twitter:card,twitter:title,twitter:description,twitter:image), one JSON-LD block, and one<h1>with text. The JSON-LD block is a@graphwith aBlogPosting(image object with dimensions,Personauthor, publisher with logo, category, keywords, word count) and aBreadcrumbListHome › category › article.datePublishedanddateModifiedcome from git. Descriptions run 110–155 characters and are unique across the site. Runenrich_schema.pyrather than writing a graph by hand. -
<!DOCTYPE html>is the first thing in the file. Anything before it puts the page in quirks mode. -
Regenerate what is derived, and audit before committing:
python3 .agents/skills/blog-ops/enrich_schema.py # JSON-LD graph (idempotent) python3 .agents/skills/blog-ops/build_api.py # docs/api/ python3 .agents/skills/blog-ops/build_sitemap.py # sitemap.xml + robots.txt python3 .agents/skills/blog-ops/check_site.py # exit 0 = consistent
-
./pushit.shpulls, commits and pushes. Nothing is live until it runs.
One page has them: docs/index.html. The thread lives in Firestore
(blog-comments-6b4f5) and is readable by anyone; writing needs an account.
Three ways in, matching exactly what is enabled in the Firebase project:
| Method | SDK call |
|---|---|
signInWithPopup, falling back to signInWithRedirect |
|
| E-mail and password | signInWithEmailAndPassword, createUserWithEmailAndPassword, sendPasswordResetEmail |
| Phone | RecaptchaVerifier (invisible) + signInWithPhoneNumber, then the SMS code |
The buttons are built from the AUTH_PROVIDERS array in the module at the bottom of
index.html; a provider that is not enabled in the Firebase console must not be in that
array, because the only thing its button can do is fail. Phone sign-in additionally
needs the reader's country allowed under Authentication → Settings → SMS region policy.
The Firestore rules (backups/firebase-rules.txt) accept a create only from a
signed-in user, with the exact field set, length caps, request.auth.uid matching
uid, and createdAt == request.time; update and delete are denied from the client.
Editing the widget: the module is ES-module only and jsdom cannot fetch its imports,
so behaviour is tested by stubbing Firebase and running the module body inside jsdom
(tmp/authtest/test_comments_auth.mjs when that scratch file is present). It covers
sign-in, sign-out, wrong password, an existing account, the SMS flow, a bad code, the
Google popup and the reset mail.
A static substitute for an endpoint: plain JSON files served like any other asset, read
in the browser. No server, no database, no third-party requests, no key. It exists so that
a page — or anything else that can do a GET — can list, search and quote the archive
without scraping HTML.
Three resources, all under docs/api/:
| Resource | Size | What it is for |
|---|---|---|
index.json |
~382 KB | The full metadata for 544 documents plus the manifest of the text chunks: generated, origin, count, languages, years, chunks, articles. |
dates.json |
~25 KB | name → published_at only, the compact map index.html fetches for its date badges and the "Last 5 publications" order. |
text/NNN.json |
15 files, ~3.4 MB together | The article bodies, chunked, each with a file, count and bytes entry in the manifest so a client can load one at a time. |
Every entry in articles carries slug, url, path, title, description, lang,
published, modified, published_at, modified_at, h1, headings, words,
chars. published_at is the instant of the first commit that touched the page and
modified_at the last one, both from git (see the git-dates skill).
# the archive at a glance
curl -s https://blog.odicforcesounds.com/api/index.json | jq '{count, languages, years}'
# one page's metadata
curl -s https://blog.odicforcesounds.com/api/index.json \
| jq '.articles[] | select(.slug == "simplicity") | {title, published_at, words}'
# every page that mentions a tool, title and description only
curl -s https://blog.odicforcesounds.com/api/index.json \
| jq -r '.articles[] | select(.description | test("OpenBSD"; "i")) | .url'
# the date map alone, for a feed or a list
curl -s https://blog.odicforcesounds.com/api/dates.json | jq '.published["simplicity.html"]'What the three are not: there is no query endpoint, no pagination on the server, no
write path, no per-article JSON, and no full-text index — text/NNN.json is the whole
archive in fifteen pieces, so a client that wants search filters after loading. The
API is regenerated by build_api.py and never edited by hand; robots.txt disallows
/api/, so the files serve clients without inviting crawlers to index the JSON.
import { BlogAPI } from "/api.js";
await BlogAPI.ready();
BlogAPI.search("freebsd"); // titles, headings, descriptions
await BlogAPI.searchFull("pf"); // adds article text, streamed chunk by chunk
BlogAPI.recent(5); // newest changessearchFull calls onResults after each chunk, so a page can paint while the rest is
still travelling. 404.html is built on it.
Two consumers today: index.html reads dates.json for its date badges and the "Last 5
publications" block, and 404.html searches the chunks through api.js. Anything else
that wants the archive — a feed, a static-site generator, a notebook, jq — reads the
same files directly, because they are ordinary static assets with no CORS dance and no
origin allowlist to satisfy.
404.html calls searchFull before the manifest has arrived — the retry is inside
docs/api.js; do not remove it.
The API covers the pages as documents, index.html included. Only 404.html and the
home.html stub are left out: one must never appear in results, the other is not a
page.
The five nature shelves, the dance catalogue, the world catalogue, the electronics
catalogue and the awesome index ship their content as data before any HTML is painted. The same files that fill
their pages answer anybody else with a GET: no key, no server, no query language, and
access-control-allow-origin: * with cache-control: max-age=600 from GitHub Pages, so
a page anywhere can read them straight from the browser.
| Directory | index.json |
One shelf | What a shelf holds |
|---|---|---|---|
docs/awesome/data/ |
17 shelves, 46,353 tools, 2.4 KB | <slug>.json, up to 2.8 MB |
lists → d (drawers) → tools, each tool with n, u, w, r |
docs/electronics/data/ |
11 shelves, 342 components, 3.2 KB | 160 KB in total | groups → items, each with n, u, s, t (thumbnail) |
docs/dance/data/ |
8 shelves, 208 styles, 123 cultures, 2.6 KB | ~10 KB | groups → items, each with n, u, s, c (culture), e (era) |
docs/world/data/ |
246 shelves, 3,856 regions, 236,907 places, 48 KB | ~20 MB, one file per country | groups → items, each with n, u, p (population), t (capital/city/town/village) |
docs/birds/data/ |
41 orders, 487 species | <order>.json |
families → s, a species with n, s (binominal), u, d |
docs/animals/data/ |
100 orders, 269 species | <order>.json |
same shape, plus mass, length, IUCN status, habitat; also read by reptilesIndex.html |
docs/fishes/data/ |
122 orders, 199 beings | <order>.json |
same shape, with grouped sections |
docs/insects/data/ |
34 orders, 144 beings | <order>.json |
same shape |
docs/plants/data/ |
43 orders, 275 plants | <order>.json |
same shape, plus edibility and toxicity |
Every index is a manifest, not the content: it names the shelves and their counts, and a
client that wants one shelf fetches one file. That is exactly why these pages open fast —
the 46,353 tools of awesomeIndex.html are 19 MB of JSON that a reader never downloads
in one go.
# one catalogue's shelves, and how much each holds
curl -s https://blog.odicforcesounds.com/dance/data/index.json \
| jq -r '.categories[] | "\(.num) \(.title): \(.styles) styles in \(.groups) groups"'
# the groups inside a single shelf
curl -s https://blog.odicforcesounds.com/dance/data/martial-east.json \
| jq -r '.groups[] | "\(.name): \(.items | length)"'
# every form whose culture mentions Japan, with its era
curl -s https://blog.odicforcesounds.com/dance/data/martial-east.json \
| jq -r '.groups[].items[] | select(.c | test("Japan")) | "\(.n) — \(.e)"'
# a nature shelf: every species in a family, with its binomial
curl -s https://blog.odicforcesounds.com/birds/data/passeriformes.json \
| jq -r '.families[] | .s[] | "\(.n) (\(.s))"' | head
# where the numbers on a catalogue page come from
curl -s https://blog.odicforcesounds.com/electronics/data/index.json | jqTips, learned the hard way:
- Read the index, then one shelf. Nothing is bundled and nothing is paged: a client
that loads every shelf of
awesome/data/downloads 19 MB, and one that loads a single shelf downloads a few kilobytes. Open lazily, as the pages do. - The five nature catalogues carry
generatedandsource(en.wikipedia.org + wikidata.org), so a consumer can show its age. The three others have no date field: theirnumand counts move when the builder is run again. - The text is Wikipedia's first sentence, not this site's prose —
s/dis quoted verbatim, links point at the article. Wikimedia photography is credited on the file page int/i; check the licence there before republishing an image. - Missing means "not in the catalogue", not "wrong" — a style or a species is added
by adding it to the builder's taxonomy, never by hand-editing JSON. Anything under
docs/*/data/is generated by.agents/skills/catalogue-data/builders/. /api/is disallowed inrobots.txt(it is a machine feed), but the catalogue JSON is not, so a search engine may index it. That is why every entry is a name plus a link rather than a copy of the page.- Everything above is also on disk in this repository:
python3 -m http.serverfromdocs/serves the same URLs, which is the fastest way to test a client offline.
Two more public files worth knowing: docs/sitemap.xml (every page with its lastmod)
and docs/tools/feeds.json (the RSS/Atom feeds index.html filters).
python3 .agents/skills/blog-ops/check_site.py audits every root page for the head
contract above and then verifies that sitemap.xml, robots.txt and docs/api/
describe the same set of pages. It exits non-zero on any failure and prints short
descriptions as warnings rather than errors.
Current run: 546 pages, 0 short-description warnings, 0 failures. The two pages that used to carry a second pasted document
(ArtOfCreation.html, JS4Children.html) were split; check_site.py reports any page
that merges two documents again.
Pages do not display a publication date. datePublished and dateModified in each
page's JSON-LD come from git — the first commit that touched the file and the last one:
git log -1 --format=%ad --date=short -- docs/Page.htmlThere is no date object inside index.html: the home page fetches docs/api/dates.json
(26 KB, name → published_at) and uses it for the date badges and the ordering of
"Last 5 publications". The full docs/api/index.json (381 KB) is for docs/api.js and
the JSON consumers, not for the home page. Either way the generated API is the only copy
of the dates the browser sees.
Because that is a fetch, the home page needs to be served over HTTP: opened from disk
(file://) the request fails and the archive shows no dates.
docs/article.css— article page stylesdocs/index.css— home page stylesdocs/style.css— shared base
Most pages also carry a <style> block of their own, because they were written as
self-contained documents. Keep that local styling local: a fix for one article should
not move the rest of the archive.
- Operating systems and open source — Linux, FreeBSD, OpenBSD
- Security and hacking — defensive and offensive notes, tools, field manuals
- Programming, sysadmin and infrastructure — practical write-ups
- Social commentary, politics and law — criticism and controversial takes
- Philosophy, psychology, creativity and music — fewer pages, same archive
Some of it is intentionally provocative.
docs/archive/anddocs/obsdRouter/hold snapshots of third-party pages. They are readable but disallowed inrobots.txtand absent from the sitemap.docs/questions.htmlis the loose thread: entries that were moved, retitled or grouped.tmp/,tools/,free/and.agents/*(except.agents/skills/) are gitignored. Scripts that must survive belong at the repository root or in.agents/skills/—pushit.shrunsgit add ., so scratch files left outside those paths get committed.backups/is tracked on purpose: the runbooks and the original pages are part of the repository's memory, and GitHub Pages never serves them because they sit outsidedocs/.
Branch main, deployed by GitHub Pages. 543 articles across four language tags
(en, pt, pt-PT, es), dated 2025–2026. Publishing has no fixed cadence; the
repository activity is the way to follow it.