Gwern uses a two-tier approach: a flat tag system (~200 maintained terms) combined with a manually maintained Tags metadata field per essay. Tags are topic-oriented, not faceted. He avoids format tags entirely — an essay about machine learning gets machine-learning, not essay or long-form. The discipline is editorial: Gwern writes 1-3 tags per essay, pruning aggressively. This produces clean chips but requires constant manual curation as the corpus grows.

Key lesson: fewer tags per document forces prioritization. Six tags per document encourages tag accumulation without semantic work.

Willison uses a flat tag taxonomy (~500-600 terms) with a tag-management interface (tag rename, tag merge). He does not distinguish facets. The result is browsable-by-tag but with moderate fragmentation: llm, llms, large-language-models coexist. His corpus is larger (5,000+ posts) and the tag interface provides a compensating mechanism for users.

Key lesson: flat tags work at scale only if the author has a merge interface and uses it. Without merging, fragmentation compounds annually.

The ACM Computing Classification System is hierarchical (3-4 levels) and faceted (Computing > Theory > Algorithms). IEEE uses free-text index terms plus a controlled vocabulary per venue. Both are designed for cross-author consistency in a shared corpus — the structural problem they solve does not exist for a single-author personal site.

Key lesson: hierarchical classification encodes disciplinary consensus that a personal archive does not have and does not need. The useful borrowing from library science is the facet concept, not the hierarchy depth.

Ranganathan's PMEST facets (Personality, Matter, Energy, Space, Time) from 1933 are the theoretical ancestor of modern faceted search. The principle: a document's classification should answer several orthogonal questions (what domain, what format, what time period) independently, not encode a single hierarchical path.

Faceted classification is the right model for a personal archive because:

1. Documents span many domains simultaneously (a conference note about Clojure at a 2019 event touches language + event + year)
2. A single path (conferences > 2019 > clojure) requires choosing which dimension is primary; facets avoid that choice
3. Facets compose: filtering on lang:clojure AND format:conference works without encoding their intersection as a single term

Vander Wal's original folksonomy analysis (2004) and Golder & Huberman's empirical study (2006) both observed that unconstrained social tagging produces power-law distributions: a few tags used very frequently, a long tail of tags used once. This is the current state of wal.sh's vocabulary.

The convergence approach (see keyword-vocabulary-convergence) iterates a folksonomy toward a controlled vocabulary's properties without discarding accumulated tagging work. V1 vocabulary defines the target state that convergence is trying to reach.

wal.sh does not need 4-level hierarchy. The corpus is one author's research across ~14 years. A document about Clojure concurrency is not ambiguous enough to require Computer Science > Programming Languages > Functional > Clojure > Concurrency. The facet structure provides orthogonal dimensions without encoding depth.

org-mode has two separate metadata mechanisms:

• #+KEYWORDS (string, comma-separated): processed by org-publish into HTML metadata, indexed by pocket-es for BM25 search, displayed as chips. Free text is acceptable here for searchability.
• #+FILETAGS (colon-delimited tags): org-mode's native tagging system, inherits in outlines, visible in org-agenda, used by tag-based queries. Controlled vocabulary terms belong here.

V1 uses both with different contracts:

This means the search chips (pocket-es) continue working from #+KEYWORDS as today. The #+FILETAGS controlled vocabulary enables org-agenda queries, org-roam graph navigation, and future structured filtering.

Year is in #+DATE. The pocket-es indexer already extracts date. A year tag duplicates information already in the document and creates maintenance drift (a note dated 2019 with a 2024 tag because it was updated). The date field is the canonical year authority.

Location terms (boston, cascais, portland, amsterdam) are valid search keywords in #+KEYWORDS and are useful in pocket-es BM25 results, but they do not belong in the controlled vocabulary. They are specificity identifiers, not category terms. The exception: boston is a valid #+KEYWORDS term; it is not a valid #+FILETAGS controlled term.

sessions, keynote, index, welcome, overview are currently used as keywords but encode document structure, not topic. The format facet captures these cleanly (format:conference, format:index) and removes them from the keyword noise.

Used when the primary substance of the document is about a specific language as a language — its semantics, idioms, ecosystem, or community.

Do NOT use for documents that happen to contain code in a language. A note about database indexing that uses Python examples is not lang:python; it is domain:databases. Use lang when the language itself is the subject.

Normalization note: lang:scheme absorbs racket (which is a Scheme descendant), guile, racketcon. When the conference itself is the topic (not Racket as a language), use format:conference instead.

The conceptual territory the document inhabits. Most documents get 1-3 domain tags.

What kind of document this is. Orthogonal to domain and language. A conference note and a research essay about the same topic get different format tags.

The distinction between format:research and format:tutorial is intent: research documents argue a position or explore a question; tutorials instruct. A document can be both (format:research + format:tutorial is valid).

Captures the era a document's content belongs to, independent of authoring date. A 2024 retrospective on 1970s Unix belongs to era:historical, not era:current.

Most documents do not need an era tag. Use it when the era is the point of the document — when "this was how we did it in 2012" or "this is what's coming" is the primary framing.

wal.sh-specific research threads. These are internal organizational tags, not topical tags.

Project tags are used sparingly — only when a document is primarily about the project rather than incidentally using it. The pocket-es spec document gets project:pocket-es; a research note that uses BM25 as one example does not.

Optional. Use only for documents in non-final states.

Most documents should have no status tag — absence implies normal publication state. The status facet exists to distinguish documents that need curation from those that are complete.

• Location names (boston, berlin, portland)
• Year numbers (2019, 2024) — use #+DATE
• Proper nouns for specific events (clojure-conj-2023, racketcon-2024)
• Person names
• Library/framework names as topics (reagent, redux, langgraph) unless the framework's design is the subject
• Free-text phrases ("best practices for X")

These all belong in #+KEYWORDS, where they contribute to BM25 search without polluting the controlled vocabulary.

These need both #+KEYWORDS and #+FILETAGS added. Priority order:

1. Conference notes (format:conference is mechanical to assign)
2. Research notes without any metadata
3. Index pages (format:index is mechanical)

Suggested tooling: a Babashka script that reads #+TITLE and #+DESCRIPTION, calls the Ollama embedding API (nomic-embed-text:v1.5 at 192.168.86.22:11434), finds the 5 nearest tagged documents, and proposes their #+FILETAGS as candidates. The author approves or adjusts.

Do NOT bulk-replace existing #+KEYWORDS. They contain searchable signal. Instead, ADD #+FILETAGS alongside the existing #+KEYWORDS.

Phase 1 (mechanical, 1-2 days of scripted work):

• All files under site/events/ get format:conference in #+FILETAGS
• All files under site/activity-summary/ get format:weekly in #+FILETAGS
• All files with #+KEYWORDS: pocket-es get project:pocket-es
• All files with #+KEYWORDS containing clojure get lang:clojure

This phase is pure automation — no editorial judgment required.

Phase 2 (editorial, high-value documents first):

• The 119 terms appearing 5+ times in #+KEYWORDS are the consolidation targets. For each, map to the controlled vocabulary and add the corresponding #+FILETAGS to documents using that term.
• Priority: the 20 highest-frequency terms cover a large fraction of docs.

Phase 3 (convergence cleanup in #+KEYWORDS):

• After #+FILETAGS is populated, run the convergence algorithm (see 2026-keyword-vocabulary-convergence) to normalize #+KEYWORDS.
• Merge near-duplicates: agentic system / agentic systems / agentic-systems → agentic-systems (prefer hyphenated form, consistent with FILETAGS style).
• Remove year-only tokens from #+KEYWORDS where #+DATE already carries the year.
• Do NOT remove location keywords — they are valid search terms.

The 3,406 unique keyword tokens include mixed-case variants. The convergence algorithm normalizes to lowercase. As a build-time invariant: the check_required_headers.py script (or a new sibling) should warn when #+KEYWORDS contains uppercase tokens, since the BM25 tokenizer lowercases at index time anyway. Storing uppercase is misleading.

1. Open this file and add the term in the appropriate facet table with its coverage description.
2. Update scripts/vocabulary_v1.py (the machine-readable list).
3. Tag the documents that prompted the addition.
4. Run gmake lint to verify the new term validates correctly.
5. Commit: feat: add lang:erlang to controlled vocabulary v1.