Document taxonomy
Every Markdown document in this site, including category landing pages, the root
index, and files under _Archive/, declares four ordered dimensions:
---
id: agent-tailscale-host
title: "Agent host: Tailscale access runbook"
tags: [runbook, tailscale, category-runbooks, status-current]
---
The first tag is one type. The second is a topic; additional topics may
follow it. The penultimate tag is one category that matches the document's
actual top-level folder. The final tag is one status. The schema is
[type, topic..., category, status]. Keys are defined in docs/tags.yml; the
machine-readable axes and folder mapping are in doc-taxonomy.json at the
repository root. Neither Docusaurus nor the file extension infers these axes.
Type: what the document is
Choose exactly one: report, research, review, runbook, reference,
standard, template, record, catalog, spec, script-snippet, skill,
concept, or index. A PowerShell script excerpt uses script-snippet as its type and
powershell as a topic:
tags: [script-snippet, powershell, category-tooling, status-current]
review means a document authored as an independent assessment or verdict.
It is not a request for owner action. A comparison report awaiting the owner's
decision is research or report with status-draft, not review merely
because someone reviewed its evidence. The site's older review usages are
retagged under this meaning.
reference remains a document type for material consulted as needed. There is
no separate Reference category: site conventions and verified tool knowledge
are stored in Knowledge (docs/14-knowledge/) with category-knowledge.
This keeps document form separate from storage and topic.
skill is the type for agent skills: reusable instruction sets an agent loads
to perform a class of work. Skills live in the Skills category
(docs/15-skills/, category-skills) regardless of which fleet repository
they were imported from; each skill document records its source repository,
branch, commit, and path in a provenance note at the top of the page.
concept is the type for ontology concept pages: one concept per page, with
its definition and its recorded relations as relations: frontmatter.
Concept pages live in the Ontology category (docs/16-ontology/,
category-ontology) and conform to the concept format standard published
there, which also governs the category's YAML triples register.
Roles: which fleet roles a skill serves
Skill documents (type skill, stored in docs/15-skills/) carry one
additional frontmatter field, roles, placed immediately after tags::
---
id: skill-context-degradation
title: "Context Degradation"
tags: [skill, agents, category-skills, status-current]
roles: [worker, planner]
---
roles names the fleet roles whose mandate the skill serves, so an agent
can find the skills for its role without crawling the library, and the
skills index and per-role manifests can be generated from the field. The
controlled vocabulary is the seven framework roles — chief_of_staff,
scrum_master, worker, planner, code_quality_reviewer,
security_reviewer, sweeper — plus finance and the research-service
roles lead_researcher and research_assistant, plus ui_ux,
worker_sol, worker_opus, and worker_spark, and all for
a skill
that genuinely serves every role. Every skill page must declare at least
one role; all is reserved for universal skills, never a default. The
repository validator rejects role values outside the vocabulary and
skill pages missing the field.
Topic: what the document is about
At least one topic is required in second position; more than one is allowed.
The current controlled topics include hermes, powershell, docusaurus,
tailscale, docker, m365, security, agents, github, instagram,
branding, assessor, fable, and research-hub. These are reusable concepts,
not one tag per document. Propose a new topic with a label, a definition, and
example uses before changing the vocabulary.
Category: the exact location
Use exactly one category key, matching the top-level folder. Mismatches are
errors, not warnings and not automatically rewritten. The site root has
category-home. A document must be moved and its links/metadata updated if it
belongs elsewhere.
| Storage | Category tag |
|---|---|
docs/index.md | category-home |
01-reports/ | category-reports |
02-research/ | category-research |
03-projects/ | category-projects |
04-fleet/ | category-fleet |
05-compliance/ | category-compliance |
06-architecture/ | category-architecture |
08-standards/ | category-standards |
09-runbooks/ | category-runbooks |
10-catalogs/ | category-catalogs |
11-templates/ | category-templates |
12-tooling/ | category-tooling |
13-voice/ | category-voice |
14-knowledge/ | category-knowledge |
15-skills/ | category-skills |
16-ontology/ | category-ontology |
The folder numbering is storage-only. It does not name an ontology class or change the tag key.
Status: where the document is in its lifecycle
Exactly one final tag is required:
status-draft— a proposal or deliverable awaiting owner decision; not adopted policy. This is the owner-review queue signal.status-current— currently applicable, not superseded.status-superseded— replaced content retained for history (including an archived document). Archiving does not exempt it from metadata validation.
The status is about the document, not whether an agent or job is running.
Semantics, ontology, and knowledge graph mapping
Treat each of the four axes as a distinct concept scheme and each tag key as a
stable concept with a preferred label and definition. In W3C SKOS terms, a tag
can be a skos:Concept in a skos:ConceptScheme with skos:prefLabel and
skos:definition. Future broader/narrower/related concept edges describe
relationships between concepts. That is different from assigning several
topic concepts to one document. Docusaurus' tags.yml is flat and does not
implement SKOS, inference, a graph database, or hierarchical tag navigation.
A future graph projection can assign one stable document identifier per id
and record these edges:
Document --hasType--> TypeConcept
Document --aboutTopic--> TopicConcept (one or more)
Document --classifiedAs--> CategoryConcept
Document --hasStatus--> StatusConcept
Document --storedAtPath--> repository path
TopicConcept --broader/narrower/related--> TopicConcept (where approved)
storedAtPath is not a substitute for classification, but under this owner's
policy its category edge must agree with the path. A taxonomy change updates
the definition first, then tags.yml, document front matter, graph projection
(if one exists), and links as one reviewed migration. No graph backend is
currently deployed; the structured vocabulary is the machine-readable source
for future graph export.
Publishing gate
The repository validator parses YAML and checks every Markdown file, including archived files, for four axes, order, duplicate/unknown keys and category/path agreement. Docusaurus production builds separately check MDX syntax, images, links and anchors with strict failure settings. The host pull/rebuild path requires successful exact-commit CI and its own metadata plus candidate-build gate before serving content. Local host publishing runs that same gate.
Current limitation: GitHub returned an upgrade-required 403 for branch
protection on this private repository. The Actions workflow runs on PRs and
pushes but is not a required pre-push check; direct commits can land on
main even if CI later fails. The host rejects them from live publication.
Do not claim that the remote repository itself is fail-closed until required
checks are available, configured and read back.
Related guides: Publishing as an external agent and Publishing.
Published by Hermes · 2026-10-01.