Add controlled tag taxonomy and filters

README.md

@@ -59,9 +59,10 @@ server is not part of production serving; nginx serves generated files only.
 ```text
 Labyricorn.lektorproject  Lektor project definition
 content/                  Editable site content (`contents.lr` files)
+content/tags/             Controlled tag vocabulary and dedicated tag routes
 models/                   Lektor content models
 templates/                Jinja templates
-assets/static/            CSS, favicon, and other static source assets
+assets/static/            CSS, filtering JavaScript, favicon, and static assets
 .gitignore                Excludes generated and local files
 README.md                 This runbook
 ```
@@ -99,6 +100,56 @@ Do not edit generated files under `/srv/labyricorn/current` or
 `/srv/labyricorn/releases`. They will be replaced by deployment and are not
 source-controlled.
 
+## Tags and filtering workflow
+
+`content/tags/` is the single source of truth for the controlled tag
+vocabulary. Each child directory is a normal Lektor record whose directory name
+is the canonical lowercase, hyphenated slug used in entry data and URLs:
+
+```text
+content/tags/deployment/contents.lr  ->  /tags/deployment/
+```
+
+The tag record supplies the editor label and public description:
+
+    _model: tag
+    ---
+    title: Deployment
+    ---
+    summary: Build, release, rollout, verification, and rollback workflows.
+
+The entry model reads its checkbox choices directly from these records. Blog
+entries and articles store the selected slugs as a comma-separated `tags`
+value:
+
+```text
+tags: lektor, deployment, operations
+```
+
+To add a tag, create its `content/tags/<slug>/contents.lr` record, run a build,
+and then select it on the relevant entries. Do not add a slug directly to an
+entry before its tag record exists. To rename or retire a tag, update every
+referencing entry deliberately and verify that no old slug remains before
+renaming or removing its record.
+
+`/tags/` lists every approved tag and counts its usage across blog entries and
+articles. Dedicated tag URLs list matching entries from both sections. Tag
+links are normal links and work without JavaScript. On the Blog and Articles
+listing pages, `assets/static/tags.js` progressively adds instant filtering and
+keeps the selected filter in the `tag` query parameter.
+
+After taxonomy or filtering changes:
+
+1. Run `lektor build --output-path build`.
+2. Verify `/tags/`, at least one dedicated tag URL, and both section listings.
+3. Confirm tag counts cover blog entries and articles and that every entry slug
+   has a matching tag record.
+4. Test filtering with JavaScript enabled and confirm tag links remain usable
+   without JavaScript.
+5. Check keyboard operation plus desktop and narrow layouts.
+6. If filtering JavaScript or tag styles changed, increment the corresponding
+   cache-busting version in `templates/base.html`.
+
 ## Local development
 
 Install Lektor in an isolated Python environment. For example: