#756 Rename the Diátaxis --type flag to --diataxis

packages/agents/content/skills/kb-add/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: true
 
 # Capture a new knowledge-base note
 
-Add a new note to the knowledge base. A bundled helper does the mechanical work — it resolves which knowledge base to write to, generates UTC dates, canonicalizes known-alias tags, validates the proposed frontmatter against the destination KB's schema, and writes the file atomically. You do the judgment work — pick the folder, the type, the title, and the tags; survey the destination KB's existing layout; run `kb-retrieve` to find related notes; and compose the body, including cross-references where they aid comprehension.
+Add a new note to the knowledge base. A bundled helper does the mechanical work — it resolves which knowledge base to write to, generates UTC dates, canonicalizes known-alias tags, validates the proposed frontmatter against the destination KB's schema, and writes the file atomically. You do the judgment work — pick the folder, the Diátaxis label, the title, and the tags; survey the destination KB's existing layout; run `kb-retrieve` to find related notes; and compose the body, including cross-references where they aid comprehension.
 
 The split is deliberate: the helper is narrow and mechanical; the classification and composition are wide and judgment-driven. Treat the helper as a guardrail (it refuses to write notes that fail validation or collide with an existing file), not as a classifier.
 
@@ -16,14 +16,14 @@ The split is deliberate: the helper is narrow and mechanical; the classification
 
 | Argument          | Description                                                                             | Required |
 | ----------------- | --------------------------------------------------------------------------------------- | -------- |
-| `--type`          | The note's `type` field (e.g. `howto`, `concept`, `reference`, `tutorial`).             | Yes      |
+| `--diataxis`      | The note's Diátaxis label (e.g. `howto`, `concept`, `reference`, `tutorial`).           | No       |
 | `--title`         | The note title; also doubles as the filename.                                           | Yes      |
 | `--kb`            | Explicit knowledge base name; overrides the discovered `.kb/` and the registry default. | No       |
 | `--folder`        | KB-relative folder under which to write the note. Defaults to the KB root.              | No       |
 | `--tags`          | Comma-separated tag list. Known aliases are canonicalized at write time.                | No       |
 | `--last-verified` | `YYYY-MM-DD` date the note's claims were last verified.                                 | No       |
 
-A value-bearing flag accepts both `--type howto` and `--type=howto`. The note body is read from stdin to EOF; an empty body is allowed when a stub note is appropriate.
+A value-bearing flag accepts both `--diataxis howto` and `--diataxis=howto`. The note body is read from stdin to EOF; an empty body is allowed when a stub note is appropriate.
 
 ### KB selection
 
@@ -59,8 +59,8 @@ Invoke the `kb-retrieve` skill on the note's topic terms. Read the top-ranked ca
 Pick the placement and metadata:
 
 - **Folder**: An existing folder when one fits; a new folder when the topic is genuinely new to the KB.
-- **Type**: One of the destination KB's `types` (the default vocabulary is `howto`, `concept`, `reference`, `tutorial`).
-- **Title**: A concise, descriptive title. For `type: howto`, propose imperative-led titles ("Configure pnpm workspaces") not interrogative ones ("How do I configure pnpm workspaces?"). The title is also the filename — keep it within a sane length and avoid filesystem-hostile characters.
+- **Diátaxis label**: The note's Diátaxis classification (the default vocabulary is `howto`, `concept`, `reference`, `tutorial`).
+- **Title**: A concise, descriptive title. For `diataxis: howto`, propose imperative-led titles ("Configure pnpm workspaces") not interrogative ones ("How do I configure pnpm workspaces?"). The title is also the filename — keep it within a sane length and avoid filesystem-hostile characters.
 - **Tags**: Topic and category tags drawn from existing tag vocabulary where possible. Known aliases will be canonicalized at write time by the helper.
 
 ### 5. Compose the body
@@ -69,15 +69,15 @@ Write the note body. Embed cross-references inline where the reference contribut
 
 ### 6. Present the proposal (default mode)
 
-In default mode, present the proposed KB, folder, type, title, tags, and body to the user. Wait for confirmation or a redirect. In auto mode, skip this step.
+In default mode, present the proposed KB, folder, Diátaxis label, title, tags, and body to the user. Wait for confirmation or a redirect. In auto mode, skip this step.
 
 ### 7. Invoke the helper
 
 Pipe the composed body to the bundled helper. A heredoc keeps multi-line bodies legible without the quoting and escaping gymnastics that `echo "$BODY"` invites once the note contains backticks, blank lines, or shell metacharacters:
 
 ```bash
 cat <<'EOF' | node "$(dirname "$SKILL_PATH")/kb-add.mjs" \
-  --type <type> --title "<title>" \
+  --diataxis <label> --title "<title>" \
   [--kb <name>] [--folder <kb-relative-folder>] \
   [--tags <comma,separated>] [--last-verified YYYY-MM-DD]
 <note body, may span multiple lines and contain any characters>
@@ -88,7 +88,7 @@ Or, when the skill directory is known:
 
 ```bash
 cat <<'EOF' | node {platform_home_dir}/skills/kb-add/kb-add.mjs \
-  --type howto --title "Configure pnpm workspaces" --tags "pnpm,workspaces"
+  --diataxis howto --title "Configure pnpm workspaces" --tags "pnpm,workspaces"
 Configure pnpm workspaces by adding a `pnpm-workspace.yaml` at the repo
 root that lists each package directory under `packages:`.
 EOF

packages/agents/content/skills/kb-retrieve/SKILL.md

@@ -14,16 +14,16 @@ The split is deliberate: the helper is wide and mechanical; the ranking is narro
 
 ## Arguments
 
-| Argument    | Description                                                                              | Required |
-| ----------- | ---------------------------------------------------------------------------------------- | -------- |
-| `<query>`   | The free-text search query. All non-flag tokens are joined into the query string.        | Yes      |
-| `--all-kbs` | Widen the search to every registered knowledge base, not just the default scope.         | No       |
-| `--store`   | Scope the search to a single registered knowledge base by name (alias: `--kb`).          | No       |
-| `--type`    | Keep only notes whose frontmatter `type` matches (e.g. `howto`, `concept`, `reference`). | No       |
-| `--tag`     | Keep only notes carrying this tag (canonical or alias form), matched case-insensitively. | No       |
-| `--folder`  | Keep only notes whose path contains this folder segment.                                 | No       |
+| Argument     | Description                                                                              | Required |
+| ------------ | ---------------------------------------------------------------------------------------- | -------- |
+| `<query>`    | The free-text search query. All non-flag tokens are joined into the query string.        | Yes      |
+| `--all-kbs`  | Widen the search to every registered knowledge base, not just the default scope.         | No       |
+| `--store`    | Scope the search to a single registered knowledge base by name (alias: `--kb`).          | No       |
+| `--diataxis` | Keep only notes whose `diataxis` facet matches (e.g. `howto`, `concept`, `reference`).   | No       |
+| `--tag`      | Keep only notes carrying this tag (canonical or alias form), matched case-insensitively. | No       |
+| `--folder`   | Keep only notes whose path contains this folder segment.                                 | No       |
 
-A value-bearing flag accepts both `--type howto` and `--type=howto`.
+A value-bearing flag accepts both `--diataxis howto` and `--diataxis=howto`.
 
 ### Scope
 
@@ -43,25 +43,25 @@ By default the helper searches up to two knowledge bases: the one discovered by
 Invoke the co-located bundled helper with `node`, passing the query and any flags through verbatim:
 
 ```bash
-node "$(dirname "$SKILL_PATH")/kb-retrieve.mjs" <query> [--all-kbs] [--store <name>] [--type <type>] [--tag <tag>] [--folder <folder>]
+node "$(dirname "$SKILL_PATH")/kb-retrieve.mjs" <query> [--all-kbs] [--store <name>] [--diataxis <label>] [--tag <tag>] [--folder <folder>]
 ```
 
 Or, when the skill directory is known:
 
 ```bash
-node {platform_home_dir}/skills/kb-retrieve/kb-retrieve.mjs "pnpm workspace setup" --type howto
+node {platform_home_dir}/skills/kb-retrieve/kb-retrieve.mjs "pnpm workspace setup" --diataxis howto
 ```
 
 The helper prints a JSON object to stdout:
 
-- `candidates` — an array of candidate notes, each with `path`, `title`, `type`, `tags`, `snippet`, `lastVerifiedAgeDays`, `supersession`, and `kbName`. An event candidate also carries `capturedAt` (its ISO-8601 capture timestamp), `repo` (its `owner/name` repository when known), and `occurrences` (a coarse recurrence count — how many query-matched events share its `repo`). These three are absent on assertion notes.
+- `candidates` — an array of candidate notes, each with `path`, `title`, `diataxis`, `tags`, `snippet`, `lastVerifiedAgeDays`, `supersession`, and `kbName`. An event candidate also carries `capturedAt` (its ISO-8601 capture timestamp), `repo` (its `owner/name` repository when known), and `occurrences` (a coarse recurrence count — how many query-matched events share its `repo`). These three are absent on assertion notes.
 - `scopedKbs` — the knowledge bases that were actually searched.
 - `warnings` — an array (possibly empty) of registry-health problems, present even when candidates are returned.
 - `diagnostic` — present only when scope is empty or no notes matched.
 
 ### 2. Rank the candidates
 
-Parse the JSON and rank the `candidates` by genuine relevance to the query's intent. Tag, type, and folder overlap with the query are **evidence**, not terms in a weighted sum — a note in the right folder with the wrong intent ranks below a note that directly answers the question. Read each `snippet` to judge whether the note actually addresses the query rather than merely mentioning its terms.
+Parse the JSON and rank the `candidates` by genuine relevance to the query's intent. Tag, Diátaxis, and folder overlap with the query are **evidence**, not terms in a weighted sum — a note in the right folder with the wrong intent ranks below a note that directly answers the question. Read each `snippet` to judge whether the note actually addresses the query rather than merely mentioning its terms.
 
 Ranking is by record type once relevance is established:
 
@@ -70,7 +70,7 @@ Ranking is by record type once relevance is established:
 
 ### 3. Present a ranked list
 
-Present the ranked notes, each showing `path`, `title`, `snippet`, and `type`. Apply these annotations:
+Present the ranked notes, each showing `path`, `title`, `snippet`, and `diataxis`. Apply these annotations:
 
 - **Stale notes** — when `lastVerifiedAgeDays` exceeds 90, annotate the note as not recently verified.
 - **Volatile notes** — when a note's `tags` include `volatile`, flag it prominently: its claims may have rotted and should be re-confirmed before use.
@@ -83,7 +83,7 @@ When the helper returns a `diagnostic` and no candidates, report the empty resul
 - `no knowledge base configured or discovered`: No `.kb/` folder was found and no registry is configured.
 - `registry invalid: …`: The only configured `kb.yaml` registry failed to load, so no knowledge base could be searched; this is a setup problem to fix, not a missing-notes outcome.
 - `no notes matched the query`: The knowledge bases were searched but nothing matched; suggest broadening the query or adding `--all-kbs`. An empty `warnings` array is the reliable signal that the in-scope KBs were actually searched and genuinely held nothing; when `warnings` is non-empty, a registry-health problem (a malformed registry or dead KB paths) may explain the empty or partial result even though the diagnostic reads `no notes matched the query`, so read `warnings` before concluding the query simply found nothing.
-- `all matches were filtered out`: The knowledge bases were searched and found hits, but every hit was excluded by `--type`, `--tag`, or `--folder`; suggest dropping or loosening a filter rather than broadening the query.
+- `all matches were filtered out`: The knowledge bases were searched and found hits, but every hit was excluded by `--diataxis`, `--tag`, or `--folder`; suggest dropping or loosening a filter rather than broadening the query.
 
 ### 5. Relay registry-health warnings