From b8f8e5b595e43ff4b31dc8b1139bd2c005bb732a Mon Sep 17 00:00:00 2001
From: William Thorsen <william@thorsen.dev>
Date: Sun, 7 Jun 2026 10:30:40 -0700
Subject: [PATCH] =?UTF-8?q?agents|feat:=20Rename=20the=20Di=C3=A1taxis=20-?=
 =?UTF-8?q?-type=20flag=20to=20--diataxis?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `kb-add` and `kb-retrieve` skills now use `--diataxis` for the Diátaxis label, replacing the former `--type` flag. Passing `--type` to either skill now fails as an unknown flag.

Notes carry the label under the `diataxis` frontmatter key. A knowledge base still using the old `type` key must rename it for `--diataxis` filtering to match.
---
 .../agents/content/skills/kb-add/SKILL.md     | 16 ++---
 .../content/skills/kb-retrieve/SKILL.md       | 30 +++++-----
 .../agents/src/kb-add/__tests__/cli.test.ts   | 58 ++++++++++---------
 .../src/kb-add/__tests__/prepare-note.test.ts | 16 ++---
 packages/agents/src/kb-add/cli.ts             |  6 +-
 packages/agents/src/kb-add/prepare-note.ts    |  8 +--
 packages/agents/src/kb-add/types.ts           |  2 +-
 .../src/kb-retrieve/__tests__/cli.test.ts     | 18 +++---
 .../fixtures/events/event-typed-a.md          |  4 +-
 .../malformed-registry/searchable-note.md     |  2 +-
 .../__tests__/fixtures/normalize/cycle-a.md   |  2 +-
 .../__tests__/fixtures/normalize/cycle-b.md   |  2 +-
 .../__tests__/fixtures/normalize/dangling.md  |  2 +-
 .../__tests__/fixtures/normalize/malformed.md |  2 +-
 .../fixtures/normalize/unparseable-date.md    |  2 +-
 .../2024-archive/legacy-runbook.md            |  2 +-
 .../notes-vault/2026-05-01-meeting-notes.md   |  2 +-
 .../notes-vault/2026-06-01/daily-log.md       |  2 +-
 .../fixtures/notes-vault/mid-guide.md         |  2 +-
 .../fixtures/notes-vault/multi-match.md       |  2 +-
 .../fixtures/notes-vault/new-guide.md         |  2 +-
 .../fixtures/notes-vault/old-guide.md         |  2 +-
 .../__tests__/fixtures/notes-vault/streams.md |  2 +-
 .../fixtures/notes-vault/sub/hooks.md         |  2 +-
 .../fixtures/notes-vault/unrelated.md         |  2 +-
 .../kb-retrieve/__tests__/normalize.test.ts   | 12 ++--
 packages/agents/src/kb-retrieve/cli.ts        | 10 ++--
 packages/agents/src/kb-retrieve/normalize.ts  | 14 ++---
 packages/agents/src/kb-retrieve/types.ts      | 10 ++--
 29 files changed, 122 insertions(+), 114 deletions(-)

diff --git a/packages/agents/content/skills/kb-add/SKILL.md b/packages/agents/content/skills/kb-add/SKILL.md
index 76336344..d2e23704 100644
--- a/packages/agents/content/skills/kb-add/SKILL.md
+++ b/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,7 +69,7 @@ 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
 
@@ -77,7 +77,7 @@ Pipe the composed body to the bundled helper. A heredoc keeps multi-line bodies
 
 ```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
diff --git a/packages/agents/content/skills/kb-retrieve/SKILL.md b/packages/agents/content/skills/kb-retrieve/SKILL.md
index a9ca22ba..922078f3 100644
--- a/packages/agents/content/skills/kb-retrieve/SKILL.md
+++ b/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
 
diff --git a/packages/agents/src/kb-add/__tests__/cli.test.ts b/packages/agents/src/kb-add/__tests__/cli.test.ts
index af03fbb1..374d0773 100644
--- a/packages/agents/src/kb-add/__tests__/cli.test.ts
+++ b/packages/agents/src/kb-add/__tests__/cli.test.ts
@@ -60,7 +60,7 @@ describe(parseArgs, () => {
       'coding',
       '--folder',
       'languages/ts',
-      '--type',
+      '--diataxis',
       'howto',
       '--title',
       'My note',
@@ -73,7 +73,7 @@ describe(parseArgs, () => {
     expect(parsed).toEqual({
       kb: 'coding',
       folder: 'languages/ts',
-      type: 'howto',
+      diataxis: 'howto',
       title: 'My note',
       tags: ['one', 'two', 'three'],
       lastVerified: '2026-01-15',
@@ -81,15 +81,15 @@ describe(parseArgs, () => {
   });
 
   it('parses flags with inline = values', () => {
-    const parsed = parseArgs(['--type=howto', '--title=Inline', '--tags=a,b']);
+    const parsed = parseArgs(['--diataxis=howto', '--title=Inline', '--tags=a,b']);
 
-    expect(parsed.type).toBe('howto');
+    expect(parsed.diataxis).toBe('howto');
     expect(parsed.title).toBe('Inline');
     expect(parsed.tags).toEqual(['a', 'b']);
   });
 
   it('defaults optional flags to null or an empty list', () => {
-    const parsed = parseArgs(['--type', 'concept', '--title', 'Stub']);
+    const parsed = parseArgs(['--diataxis', 'concept', '--title', 'Stub']);
 
     expect(parsed.kb).toBeNull();
     expect(parsed.folder).toBeNull();
@@ -97,22 +97,26 @@ describe(parseArgs, () => {
     expect(parsed.lastVerified).toBeNull();
   });
 
-  it('defaults --type to null when omitted', () => {
+  it('defaults --diataxis to null when omitted', () => {
     const parsed = parseArgs(['--title', 'Stub']);
 
-    expect(parsed.type).toBeNull();
+    expect(parsed.diataxis).toBeNull();
   });
 
   it('throws when --title is missing', () => {
-    expect(() => parseArgs(['--type', 'howto'])).toThrow(/--title is required/);
+    expect(() => parseArgs(['--diataxis', 'howto'])).toThrow(/--title is required/);
   });
 
   it('throws when a value-bearing flag has no value', () => {
-    expect(() => parseArgs(['--type'])).toThrow(/--type requires a value/);
+    expect(() => parseArgs(['--diataxis'])).toThrow(/--diataxis requires a value/);
   });
 
   it('throws on an unknown flag', () => {
-    expect(() => parseArgs(['--type', 'howto', '--title', 'X', '--bogus'])).toThrow(/unknown flag/);
+    expect(() => parseArgs(['--diataxis', 'howto', '--title', 'X', '--bogus'])).toThrow(/unknown flag/);
+  });
+
+  it('rejects the retired --type flag as unknown', () => {
+    expect(() => parseArgs(['--type', 'howto', '--title', 'X'])).toThrow(/unknown flag/);
   });
 });
 
@@ -121,7 +125,7 @@ describe(runAdd, () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--type', 'howto', '--title', 'Working with streams', '--tags', 'node,streams'],
+      argv: ['--diataxis', 'howto', '--title', 'Working with streams', '--tags', 'node,streams'],
       stdin: bodyStream('How to work with Node streams.\n'),
       startDir: kbPath,
       now: NOW,
@@ -144,7 +148,7 @@ describe(runAdd, () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--type', 'concept', '--title', 'IO', '--folder', 'languages/typescript'],
+      argv: ['--diataxis', 'concept', '--title', 'IO', '--folder', 'languages/typescript'],
       stdin: bodyStream('A short note.\n'),
       startDir: kbPath,
       now: NOW,
@@ -161,7 +165,7 @@ describe(runAdd, () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--type', 'reference', '--title', 'Stub'],
+      argv: ['--diataxis', 'reference', '--title', 'Stub'],
       stdin: bodyStream(''),
       startDir: kbPath,
       now: NOW,
@@ -177,7 +181,7 @@ describe(runAdd, () => {
 
   it('returns no-kb-resolvable when no .kb/ and no registry default exist', async () => {
     const result = await runAdd({
-      argv: ['--type', 'howto', '--title', 'Floating'],
+      argv: ['--diataxis', 'howto', '--title', 'Floating'],
       stdin: bodyStream(''),
       startDir: '/',
       now: NOW,
@@ -194,7 +198,7 @@ describe(runAdd, () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--kb', 'nonexistent', '--type', 'howto', '--title', 'X'],
+      argv: ['--kb', 'nonexistent', '--diataxis', 'howto', '--title', 'X'],
       stdin: bodyStream(''),
       startDir: kbPath,
       now: NOW,
@@ -208,11 +212,11 @@ describe(runAdd, () => {
     }
   });
 
-  it('writes recordType: assertion and the Diátaxis --type label into extra', async () => {
+  it('writes recordType: assertion and the Diátaxis --diataxis label into extra', async () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--type', 'howto', '--title', 'Labeled'],
+      argv: ['--diataxis', 'howto', '--title', 'Labeled'],
       stdin: bodyStream(''),
       startDir: kbPath,
       now: NOW,
@@ -222,14 +226,14 @@ describe(runAdd, () => {
     expect(result.ok).toBe(true);
     if (result.ok) {
       expect(result.frontmatter.recordType).toBe('assertion');
-      expect(result.frontmatter.extra.type).toBe('howto');
+      expect(result.frontmatter.extra.diataxis).toBe('howto');
       const written = await readFile(result.path, 'utf8');
       expect(written).toMatch(/^recordType: assertion$/m);
-      expect(written).toContain('type: howto');
+      expect(written).toContain('diataxis: howto');
     }
   });
 
-  it('writes a note even when --type is omitted', async () => {
+  it('writes a note even when --diataxis is omitted', async () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
@@ -243,7 +247,7 @@ describe(runAdd, () => {
     expect(result.ok).toBe(true);
     if (result.ok) {
       expect(result.frontmatter.recordType).toBe('assertion');
-      expect(result.frontmatter.extra).not.toHaveProperty('type');
+      expect(result.frontmatter.extra).not.toHaveProperty('diataxis');
     }
   });
 
@@ -252,7 +256,7 @@ describe(runAdd, () => {
     await writeFile(join(kbPath, 'Existing.md'), 'pre-existing\n', 'utf8');
 
     const result = await runAdd({
-      argv: ['--type', 'howto', '--title', 'Existing'],
+      argv: ['--diataxis', 'howto', '--title', 'Existing'],
       stdin: bodyStream('new body\n'),
       startDir: kbPath,
       now: NOW,
@@ -282,7 +286,7 @@ describe(runAdd, () => {
     );
 
     const result = await runAdd({
-      argv: ['--kb', 'locked', '--type', 'howto', '--title', 'Refused'],
+      argv: ['--kb', 'locked', '--diataxis', 'howto', '--title', 'Refused'],
       stdin: bodyStream(''),
       // startDir avoids the KB so discovery does not produce a writable fallback.
       startDir: homeDir,
@@ -305,7 +309,7 @@ describe(runAdd, () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--type', 'howto'],
+      argv: ['--diataxis', 'howto'],
       stdin: bodyStream(''),
       startDir: kbPath,
       now: NOW,
@@ -322,7 +326,7 @@ describe(runAdd, () => {
     const kbPath = await makeKb();
 
     const result = await runAdd({
-      argv: ['--type', 'howto', '--title', 'foo/bar'],
+      argv: ['--diataxis', 'howto', '--title', 'foo/bar'],
       stdin: bodyStream(''),
       startDir: kbPath,
       now: NOW,
@@ -351,7 +355,7 @@ describe(runAdd, () => {
     try {
       const result = await runAdd({
         // `nodejs` would canonicalize to `node` if the aliases loaded; with the empty-map fallback it stays as-is.
-        argv: ['--type', 'howto', '--title', 'Aliases fallback', '--tags', 'node.js,react'],
+        argv: ['--diataxis', 'howto', '--title', 'Aliases fallback', '--tags', 'node.js,react'],
         stdin: bodyStream('Body.\n'),
         startDir: kbPath,
         now: NOW,
@@ -391,7 +395,7 @@ describe(runAdd, () => {
 
     const { stdout, exitCode } = await runChild({
       command: process.execPath,
-      args: [bundlePath, '--type', 'howto', '--title', 'Subprocess test'],
+      args: [bundlePath, '--diataxis', 'howto', '--title', 'Subprocess test'],
       stdinBody: 'Body from stdin.\n',
       cwd: kbPath,
       env: { ...process.env, HOME: kbPath },
diff --git a/packages/agents/src/kb-add/__tests__/prepare-note.test.ts b/packages/agents/src/kb-add/__tests__/prepare-note.test.ts
index 307adb82..85f758b2 100644
--- a/packages/agents/src/kb-add/__tests__/prepare-note.test.ts
+++ b/packages/agents/src/kb-add/__tests__/prepare-note.test.ts
@@ -13,7 +13,7 @@ const TODAY = '2026-05-24';
 const baseArgs: ParsedArgs = {
   kb: null,
   folder: null,
-  type: 'howto',
+  diataxis: 'howto',
   title: 'Working with Node streams',
   tags: ['streams'],
   lastVerified: null,
@@ -35,23 +35,23 @@ describe(prepareNote, () => {
     }
   });
 
-  it('writes the Diátaxis --type label into extra, not a top-level field', () => {
+  it('writes the Diátaxis --diataxis label into extra, not a top-level field', () => {
     const result = prepareNote({ args: baseArgs, schema: defaultSchema, aliases: emptyAliases, now: NOW });
 
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.prepared.frontmatter.extra.type).toBe('howto');
-      expect(result.prepared.frontmatter).not.toHaveProperty('type');
+      expect(result.prepared.frontmatter.extra.diataxis).toBe('howto');
+      expect(result.prepared.frontmatter).not.toHaveProperty('diataxis');
     }
   });
 
-  it('omits the extra type field when --type is not supplied', () => {
-    const args: ParsedArgs = { ...baseArgs, type: null };
+  it('omits the extra diataxis field when --diataxis is not supplied', () => {
+    const args: ParsedArgs = { ...baseArgs, diataxis: null };
     const result = prepareNote({ args, schema: defaultSchema, aliases: emptyAliases, now: NOW });
 
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.prepared.frontmatter.extra).not.toHaveProperty('type');
+      expect(result.prepared.frontmatter.extra).not.toHaveProperty('diataxis');
     }
   });
 
@@ -126,7 +126,7 @@ describe(prepareNote, () => {
         created: TODAY,
         updated: TODAY,
         tags: ['nodejs', 'streams'],
-        extra: { type: 'howto', 'last-verified': '2026-01-15' },
+        extra: { diataxis: 'howto', 'last-verified': '2026-01-15' },
       });
     }
   });
diff --git a/packages/agents/src/kb-add/cli.ts b/packages/agents/src/kb-add/cli.ts
index 9178017f..ddb46f1a 100644
--- a/packages/agents/src/kb-add/cli.ts
+++ b/packages/agents/src/kb-add/cli.ts
@@ -16,7 +16,7 @@ import type { AddResult, ParsedArgs } from './types.ts';
 import { writeNote } from './write-note.ts';
 
 /** Flag names that take a value. */
-const VALUE_FLAGS = ['kb', 'folder', 'type', 'title', 'tags', 'last-verified'] as const;
+const VALUE_FLAGS = ['kb', 'folder', 'diataxis', 'title', 'tags', 'last-verified'] as const;
 type ValueFlag = (typeof VALUE_FLAGS)[number];
 
 /** Executes the helper from `process.argv` and writes the JSON result to stdout. */
@@ -82,7 +82,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs {
   return {
     kb: raw.kb ?? null,
     folder: raw.folder ?? null,
-    type: raw.type ?? null,
+    diataxis: raw.diataxis ?? null,
     title,
     tags: raw.tags === undefined ? [] : parseTagList(raw.tags),
     lastVerified: raw['last-verified'] ?? null,
@@ -224,7 +224,7 @@ function isEntryPoint(): boolean {
   }
 }
 
-/** Matches a `--kb`/`--folder`/`--title`/`--tags`/`--last-verified` flag (and the optional `--type` Diátaxis label), returning its key and any inline `=value`. */
+/** Matches a `--kb`/`--folder`/`--title`/`--tags`/`--last-verified` flag (and the optional `--diataxis` Diátaxis label), returning its key and any inline `=value`. */
 function matchValueFlag(arg: string): { key: ValueFlag; inlineValue: string | null } | null {
   for (const key of VALUE_FLAGS) {
     if (arg === `--${key}`) {
diff --git a/packages/agents/src/kb-add/prepare-note.ts b/packages/agents/src/kb-add/prepare-note.ts
index 308cef97..45678aae 100644
--- a/packages/agents/src/kb-add/prepare-note.ts
+++ b/packages/agents/src/kb-add/prepare-note.ts
@@ -25,8 +25,8 @@ export type PrepareOutcome = PrepareSuccess | PrepareFailure;
  * Composes a typed `Frontmatter` from parsed CLI args, fills in UTC `created` and `updated` dates, canonicalizes
  * tags via the supplied alias map, and validates the result against the destination KB's schema using the
  * `frontmatterRule` from kb. Every note carries `recordType: assertion` as the stored discriminant — `kb-add` only
- * writes assertions. Any Diátaxis label the agent supplies via `--type` is a vault facet, written to the note's `extra`
- * fields rather than a top-level field.
+ * writes assertions. Any Diátaxis label the agent supplies via `--diataxis` is a vault facet, written to the note's
+ * `extra` fields rather than a top-level field.
  *
  * Validation is performed by round-tripping the rendered frontmatter through `parseNoteContent` and feeding the parsed
  * note through `runRules`. The round trip is the cheapest way to give the rule a real `ParsedNote` carrying valid
@@ -45,8 +45,8 @@ export function prepareNote(input: { args: ParsedArgs; schema: Schema; aliases:
   const today = formatUtcDate(now);
 
   const extra: Record<string, unknown> = {};
-  if (args.type !== null) {
-    extra.type = args.type;
+  if (args.diataxis !== null) {
+    extra.diataxis = args.diataxis;
   }
   if (args.lastVerified !== null) {
     extra['last-verified'] = args.lastVerified;
diff --git a/packages/agents/src/kb-add/types.ts b/packages/agents/src/kb-add/types.ts
index 36d3d930..e4e2bb69 100644
--- a/packages/agents/src/kb-add/types.ts
+++ b/packages/agents/src/kb-add/types.ts
@@ -15,7 +15,7 @@ export interface ParsedArgs {
   /** Optional KB-relative folder under which the note is written; defaults to the KB root. */
   folder: string | null;
   /** Optional Diátaxis label (e.g. `howto`); written to the note's extra fields, not a top-level field. */
-  type: string | null;
+  diataxis: string | null;
   /** The note title; also doubles as the filename stem. */
   title: string;
   /** The proposed tag list, in the order the agent supplied them. */
diff --git a/packages/agents/src/kb-retrieve/__tests__/cli.test.ts b/packages/agents/src/kb-retrieve/__tests__/cli.test.ts
index 89557184..28dc9a99 100644
--- a/packages/agents/src/kb-retrieve/__tests__/cli.test.ts
+++ b/packages/agents/src/kb-retrieve/__tests__/cli.test.ts
@@ -21,8 +21,8 @@ describe(parseArgs, () => {
     expect(parseArgs(['query', '--all-kbs']).allKbs).toBe(true);
   });
 
-  it('parses a --type filter given as a separate value', () => {
-    expect(parseArgs(['query', '--type', 'howto']).filters.type).toBe('howto');
+  it('parses a --diataxis filter given as a separate value', () => {
+    expect(parseArgs(['query', '--diataxis', 'howto']).filters.diataxis).toBe('howto');
   });
 
   it('parses a --tag filter given with an inline value', () => {
@@ -37,17 +37,21 @@ describe(parseArgs, () => {
   });
 
   it('throws when a value-bearing flag has no value', () => {
-    expect(() => parseArgs(['query', '--type'])).toThrow(/--type requires a value/);
+    expect(() => parseArgs(['query', '--diataxis'])).toThrow(/--diataxis requires a value/);
   });
 
   it('throws when a value-bearing flag has an empty inline value', () => {
-    expect(() => parseArgs(['query', '--type='])).toThrow(/--type requires a value/);
+    expect(() => parseArgs(['query', '--diataxis='])).toThrow(/--diataxis requires a value/);
   });
 
   it('throws on an unknown flag', () => {
     expect(() => parseArgs(['query', '--bogus'])).toThrow(/unknown flag/);
   });
 
+  it('rejects the retired --type flag as unknown', () => {
+    expect(() => parseArgs(['query', '--type', 'howto'])).toThrow(/unknown flag/);
+  });
+
   it('parses --store as the store-scope name', () => {
     expect(parseArgs(['query', '--store', 'codeassembly']).storeName).toBe('codeassembly');
   });
@@ -99,15 +103,15 @@ describe(runRetrieve, () => {
     expect(event?.capturedAt).toBe('2026-04-20T09:00:00.000Z');
   });
 
-  it('applies the --type filter to the candidate table', async () => {
+  it('applies the --diataxis filter to the candidate table', async () => {
     const result = await runRetrieve({
-      argv: ['deployment', '--type', 'howto'],
+      argv: ['deployment', '--diataxis', 'howto'],
       startDir: NOTES_VAULT,
       now: NOW,
       home: FIXTURES,
     });
 
-    expect(result.candidates.every((candidate) => candidate.type === 'howto')).toBe(true);
+    expect(result.candidates.every((candidate) => candidate.diataxis === 'howto')).toBe(true);
     expect(result.candidates.length).toBeGreaterThan(0);
   });
 
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/events/event-typed-a.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/events/event-typed-a.md
index e4cd8ebc..0895e566 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/events/event-typed-a.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/events/event-typed-a.md
@@ -5,8 +5,8 @@ captured-at: 2026-05-23T10:00:00.000Z
 session: session-4
 cwd: /tmp/work
 repo: owner/repo-z
-type: observation
+diataxis: observation
 summary: A typed event carrying a Diataxis label
 ---
 
-An event that also carries a Diataxis type label in its frontmatter.
+An event that also carries a Diataxis label in its frontmatter.
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/malformed-registry/searchable-note.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/malformed-registry/searchable-note.md
index 7f4a962e..be6d7913 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/malformed-registry/searchable-note.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/malformed-registry/searchable-note.md
@@ -1,6 +1,6 @@
 ---
 title: Searchable note in the malformed-registry discovered KB
-type: reference
+diataxis: reference
 tags: []
 ---
 
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-a.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-a.md
index 28333ad0..682fcf8e 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-a.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-a.md
@@ -1,7 +1,7 @@
 ---
 title: Cycle node A
 recordType: assertion
-type: concept
+diataxis: concept
 created: 2026-01-01
 updated: 2026-01-01
 tags: [cycle]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-b.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-b.md
index 51484e3c..ffc7478e 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-b.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/cycle-b.md
@@ -1,7 +1,7 @@
 ---
 title: Cycle node B
 recordType: assertion
-type: concept
+diataxis: concept
 created: 2026-01-01
 updated: 2026-01-01
 tags: [cycle]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/dangling.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/dangling.md
index 7c428425..7cf2a367 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/dangling.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/dangling.md
@@ -1,7 +1,7 @@
 ---
 title: Note with a dangling successor
 recordType: assertion
-type: reference
+diataxis: reference
 created: 2026-01-01
 updated: 2026-01-01
 tags: [orphan]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/malformed.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/malformed.md
index 4b9829e4..ee63e9e8 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/malformed.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/malformed.md
@@ -1,6 +1,6 @@
 ---
 title: Malformed note
-type: howto
+diataxis: howto
 tags: [unterminated
 created: 2026-01-01
 ---
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/unparseable-date.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/unparseable-date.md
index c2565412..6160437e 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/unparseable-date.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/normalize/unparseable-date.md
@@ -1,7 +1,7 @@
 ---
 title: Note with an unparseable last-verified
 recordType: assertion
-type: reference
+diataxis: reference
 created: 2026-01-01
 updated: 2026-01-01
 tags: [meta]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2024-archive/legacy-runbook.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2024-archive/legacy-runbook.md
index f393c781..2ca10c78 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2024-archive/legacy-runbook.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2024-archive/legacy-runbook.md
@@ -1,7 +1,7 @@
 ---
 title: Legacy archival runbook
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2024-03-01
 updated: 2024-03-01
 tags: [archive]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-05-01-meeting-notes.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-05-01-meeting-notes.md
index a12c0280..3c347209 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-05-01-meeting-notes.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-05-01-meeting-notes.md
@@ -1,7 +1,7 @@
 ---
 title: Meeting notes
 recordType: assertion
-type: note
+diataxis: note
 created: 2026-05-01
 updated: 2026-05-01
 tags: [meeting]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-06-01/daily-log.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-06-01/daily-log.md
index 488431db..316995ca 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-06-01/daily-log.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/2026-06-01/daily-log.md
@@ -1,7 +1,7 @@
 ---
 title: Daily log
 recordType: assertion
-type: note
+diataxis: note
 created: 2026-06-01
 updated: 2026-06-01
 tags: [journal]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/mid-guide.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/mid-guide.md
index ccd107c3..0493aaad 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/mid-guide.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/mid-guide.md
@@ -1,7 +1,7 @@
 ---
 title: Interim deployment guide
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2025-09-01
 updated: 2025-09-01
 tags: [deploy]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/multi-match.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/multi-match.md
index f03488f0..54c86980 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/multi-match.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/multi-match.md
@@ -1,7 +1,7 @@
 ---
 title: Multi-match snippet fixture
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2026-03-01
 updated: 2026-03-01
 tags: [test]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/new-guide.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/new-guide.md
index 8da19722..29171387 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/new-guide.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/new-guide.md
@@ -1,7 +1,7 @@
 ---
 title: Current deployment guide
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2026-04-01
 updated: 2026-04-01
 tags: [deploy, stable]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/old-guide.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/old-guide.md
index e2020140..9bc40fb6 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/old-guide.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/old-guide.md
@@ -1,7 +1,7 @@
 ---
 title: Old deployment guide
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2025-06-01
 updated: 2025-06-01
 tags: [deploy, deprecated]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/streams.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/streams.md
index e3b15a14..f8761562 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/streams.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/streams.md
@@ -1,7 +1,7 @@
 ---
 title: Working with Node.js streams
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2026-01-10
 updated: 2026-01-10
 tags: [nodejs, streams]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/sub/hooks.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/sub/hooks.md
index 041e46b0..6e3885d4 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/sub/hooks.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/sub/hooks.md
@@ -1,7 +1,7 @@
 ---
 title: React hooks reference
 recordType: assertion
-type: reference
+diataxis: reference
 created: 2026-02-01
 updated: 2026-02-01
 tags: [react, hooks]
diff --git a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/unrelated.md b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/unrelated.md
index 738df399..eefd5856 100644
--- a/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/unrelated.md
+++ b/packages/agents/src/kb-retrieve/__tests__/fixtures/notes-vault/unrelated.md
@@ -1,7 +1,7 @@
 ---
 title: Brewing coffee
 recordType: assertion
-type: howto
+diataxis: howto
 created: 2026-03-01
 updated: 2026-03-01
 tags: [kitchen]
diff --git a/packages/agents/src/kb-retrieve/__tests__/normalize.test.ts b/packages/agents/src/kb-retrieve/__tests__/normalize.test.ts
index cf494e09..15219886 100644
--- a/packages/agents/src/kb-retrieve/__tests__/normalize.test.ts
+++ b/packages/agents/src/kb-retrieve/__tests__/normalize.test.ts
@@ -22,7 +22,7 @@ describe(normalizeHits, () => {
     expect(candidates).toHaveLength(1);
     expect(candidates[0]).toMatchObject({
       title: 'Current deployment guide',
-      type: 'howto',
+      diataxis: 'howto',
       tags: ['deploy', 'stable'],
     });
   });
@@ -111,15 +111,15 @@ describe(normalizeHits, () => {
     });
 
     expect(candidates).toHaveLength(1);
-    expect(candidates[0]?.type).toBeNull();
+    expect(candidates[0]?.diataxis).toBeNull();
     expect(candidates[0]?.title).toBe('malformed.md');
     expect(candidates[0]?.diagnostic).toMatch(/malformed/);
   });
 
-  it('keeps only notes matching the --type filter', async () => {
+  it('keeps only notes matching the --diataxis filter', async () => {
     const candidates = await normalizeHits({
       hits: [hitFor(join(NOTES_VAULT, 'streams.md')), hitFor(join(NOTES_VAULT, 'sub', 'hooks.md'))],
-      filters: { type: 'reference' },
+      filters: { diataxis: 'reference' },
       now: NOW,
     });
 
@@ -248,10 +248,10 @@ describe('normalizeHits over event records', () => {
     expect(byTitle.get('Another observation captured outside a git remote')).toBe(2);
   });
 
-  it('keeps only events whose extra type matches the --type filter, dropping events with no extra type', async () => {
+  it('keeps only events whose extra diataxis matches the --diataxis filter, dropping events with no extra diataxis', async () => {
     const candidates = await normalizeHits({
       hits: [hitFor(join(EVENTS, 'event-typed-a.md')), hitFor(join(EVENTS, 'event-c.md'))],
-      filters: { type: 'observation' },
+      filters: { diataxis: 'observation' },
       now: NOW,
     });
 
diff --git a/packages/agents/src/kb-retrieve/cli.ts b/packages/agents/src/kb-retrieve/cli.ts
index 9ac3b526..6b34f421 100644
--- a/packages/agents/src/kb-retrieve/cli.ts
+++ b/packages/agents/src/kb-retrieve/cli.ts
@@ -17,7 +17,7 @@ export interface ParsedArgs {
   allKbs: boolean;
   /** The registry name from `--store`/`--kb`, scoping recall to that store alone (no cwd-walk); `null` when absent. */
   storeName: string | null;
-  /** The mechanical filters from `--type`, `--tag`, `--folder`. */
+  /** The mechanical filters from `--diataxis`, `--tag`, `--folder`. */
   filters: RecallFilters;
 }
 
@@ -73,9 +73,9 @@ function matchStoreFlag(arg: string): { flag: 'store' | 'kb'; inlineValue: strin
   return null;
 }
 
-/** Matches a `--type`/`--tag`/`--folder` flag, returning its key and any inline `=value`. */
+/** Matches a `--diataxis`/`--tag`/`--folder` flag, returning its key and any inline `=value`. */
 function matchValueFlag(arg: string): { key: keyof RecallFilters; inlineValue: string | null } | null {
-  for (const key of ['type', 'tag', 'folder'] as const) {
+  for (const key of ['diataxis', 'tag', 'folder'] as const) {
     if (arg === `--${key}`) {
       return { key, inlineValue: null };
     }
@@ -87,7 +87,7 @@ function matchValueFlag(arg: string): { key: keyof RecallFilters; inlineValue: s
 }
 
 /**
- * Parses the helper's argv into a query, the `--all-kbs` flag, and the `--type`/`--tag`/`--folder` filters.
+ * Parses the helper's argv into a query, the `--all-kbs` flag, and the `--diataxis`/`--tag`/`--folder` filters.
  * Each value-bearing flag accepts both `--flag value` and `--flag=value`.
  * An unknown flag or a value-bearing flag with no value throws with a usage-style message.
  *
@@ -198,7 +198,7 @@ export async function runRetrieve(input: {
   };
   if (candidates.length === 0) {
     // Distinguish a query that found nothing from a query that found hits which were then excluded by
-    // `--type` / `--tag` / `--folder`, so the caller knows whether to broaden the query or drop a filter.
+    // `--diataxis` / `--tag` / `--folder`, so the caller knows whether to broaden the query or drop a filter.
     result.diagnostic = hits.length === 0 ? 'no notes matched the query' : 'all matches were filtered out';
   }
   return result;
diff --git a/packages/agents/src/kb-retrieve/normalize.ts b/packages/agents/src/kb-retrieve/normalize.ts
index bcbd668c..fff82108 100644
--- a/packages/agents/src/kb-retrieve/normalize.ts
+++ b/packages/agents/src/kb-retrieve/normalize.ts
@@ -12,7 +12,7 @@ const MAX_SUPERSESSION_HOPS = 32;
 /**
  * Normalizes raw ripgrep hits into the candidate table.
  *
- * Each hit's frontmatter is parsed; the `--type`, `--tag`, and `--folder` filters are applied as post-filters on the
+ * Each hit's frontmatter is parsed; the `--diataxis`, `--tag`, and `--folder` filters are applied as post-filters on the
  * parsed frontmatter and the note path; a `superseded-by` chain is followed to the canonical successor with a cycle
  * guard; and `last-verified` is converted to an age in whole days against `now`. Notes with missing or malformed
  * frontmatter degrade to a low-signal candidate carrying a diagnostic rather than being dropped.
@@ -95,8 +95,8 @@ async function parseNoteSafely(path: string): Promise<SafeParseOutcome> {
 }
 
 /**
- * Applies the mechanical `--type`, `--tag`, and `--folder` filters. A note with no parseable frontmatter fails
- * `--type` and `--tag` (it carries no typed fields) but is still subject to the path-based `--folder` filter.
+ * Applies the mechanical `--diataxis`, `--tag`, and `--folder` filters. A note with no parseable frontmatter fails
+ * `--diataxis` and `--tag` (it carries no typed fields) but is still subject to the path-based `--folder` filter.
  */
 function passesFilters(input: { note: ParsedNote; path: string; filters: RecallFilters }): boolean {
   const { note, path, filters } = input;
@@ -107,8 +107,8 @@ function passesFilters(input: { note: ParsedNote; path: string; filters: RecallF
 
   const frontmatter = note.frontmatter;
   if (
-    filters.type !== undefined &&
-    extractString(frontmatter?.extra, 'type')?.toLowerCase() !== filters.type.toLowerCase()
+    filters.diataxis !== undefined &&
+    extractString(frontmatter?.extra, 'diataxis')?.toLowerCase() !== filters.diataxis.toLowerCase()
   ) {
     return false;
   }
@@ -183,7 +183,7 @@ async function toCandidate(input: { hit: RawHit; note: ParsedNote; now: Date }):
   const repo = extractString(extra, 'repo');
 
   const title = resolveTitle({ frontmatter, summary, capturedAt, path: hit.path });
-  const type = extractString(extra, 'type');
+  const diataxis = extractString(extra, 'diataxis');
   const tags = frontmatter?.tags ?? [];
   const lastVerifiedAgeDays = computeAgeDays(extractString(extra, 'last-verified'), now);
   const supersession = await resolveSupersession({ path: hit.path, note });
@@ -191,7 +191,7 @@ async function toCandidate(input: { hit: RawHit; note: ParsedNote; now: Date }):
   const candidate: Candidate = {
     path: hit.path,
     title,
-    type,
+    diataxis,
     tags,
     snippet: hit.snippet,
     lastVerifiedAgeDays,
diff --git a/packages/agents/src/kb-retrieve/types.ts b/packages/agents/src/kb-retrieve/types.ts
index ef13f4a2..747c19d5 100644
--- a/packages/agents/src/kb-retrieve/types.ts
+++ b/packages/agents/src/kb-retrieve/types.ts
@@ -10,8 +10,8 @@ export interface Candidate {
   path: string;
   /** Note title from frontmatter, or the file basename when frontmatter is missing or malformed. */
   title: string;
-  /** The note's Diátaxis `type` facet from its extra fields, or `null` when absent. */
-  type: string | null;
+  /** The note's Diátaxis facet (the `diataxis` extra field), or `null` when absent. */
+  diataxis: string | null;
   /** Canonical tags from frontmatter. */
   tags: string[];
   /** A context snippet drawn from the ripgrep match. */
@@ -47,10 +47,10 @@ export interface RawHit {
   snippet: string;
 }
 
-/** The mechanical filters applied to the candidate set, parsed from `--type`, `--tag`, `--folder`. */
+/** The mechanical filters applied to the candidate set, parsed from `--diataxis`, `--tag`, `--folder`. */
 export interface RecallFilters {
-  /** Restrict to notes whose Diátaxis `type` facet (in extra) matches, case-insensitively. */
-  type?: string;
+  /** Restrict to notes whose Diátaxis facet (the `diataxis` extra field) matches, case-insensitively. */
+  diataxis?: string;
   /** Restrict to notes carrying this tag (canonical or alias), case-insensitively. */
   tag?: string;
   /** Restrict to notes whose path contains this folder segment, case-insensitively. */