@marlinjai/clearify 2.1.0 → 2.2.1

package/README.md

@@ -62,6 +62,7 @@ export default defineConfig({
 
 - Node.js 22 or later
 - npm, pnpm, or yarn
+- Zod 4.6.7 or later (clearify validates config with the Zod 4 API; versions below 4.6.6 are affected by GHSA-mrhx-c7xc-m3w5)
 - For hub onboarding: a GitHub account and (for CLI-assisted secret provisioning) a GitHub OAuth App. See [Installation](./docs/public/installation.md) for prerequisites per path.
 
 ## Links

package/dist/node/{chunk-CTL4YL7C.js → chunk-77IOLCAM.js}

@@ -10,6 +10,16 @@ import { globbySync } from "globby";
 function toTitleCase(str) {
   return str.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
+function inferDocType(filePath) {
+  const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+  const file = basename(normalized, extname(normalized));
+  if (file === "readme") return "readme";
+  if (file === "changelog" || file === "changes") return "changelog";
+  if (file === "roadmap") return "roadmap";
+  if (file.includes("handover") || /\/handovers(\/|$)/.test(normalized)) return "handover";
+  if (/\/(plans|specs|superpowers|research|decisions)(\/|$)/.test(normalized)) return "plan";
+  return "documentation";
+}
 function fileToRoutePath(filePath, docsDir, basePath = "/") {
   const rel = relative(docsDir, filePath);
   const ext = extname(rel);
@@ -42,7 +52,8 @@ function scanDocs(docsDir, exclude = [], basePath = "/") {
         icon: data.icon,
         order: data.order,
         summary: data.summary,
-        category: data.category,
+        // `type` per the shared contract; inferred from path when omitted.
+        type: data.type ?? inferDocType(filePath),
         tags: data.tags,
         projects: data.projects,
         status: data.status,
@@ -197,6 +208,7 @@ function buildSectionData(section, rootFiles, customNavigation) {
 }
 
 export {
+  inferDocType,
   scanDocs,
   buildNavigation,
   buildRoutes,

package/dist/node/{chunk-Q5FUAK6J.js → chunk-LVPVSOXK.js}

@@ -13,7 +13,7 @@ import {
 } from "./chunk-ZWF6VCSQ.js";
 import {
   buildSectionData
-} from "./chunk-CTL4YL7C.js";
+} from "./chunk-77IOLCAM.js";
 
 // src/vite-plugin/index.ts
 import { resolve, dirname } from "path";

package/dist/node/{chunk-GZE6QLJT.js → chunk-V5J36LF5.js}

@@ -5,22 +5,28 @@ import {
 } from "./chunk-ZWF6VCSQ.js";
 import {
   scanDocs
-} from "./chunk-CTL4YL7C.js";
+} from "./chunk-77IOLCAM.js";
 
 // src/node/check.ts
 import { resolve, relative } from "path";
 import { readFileSync, existsSync } from "fs";
 import matter from "gray-matter";
-var VALID_CATEGORIES = [
+var VALID_TYPES = [
+  "readme",
   "documentation",
-  "internal",
   "plan",
-  "research",
-  "decision",
   "roadmap",
-  "changelog"
+  "changelog",
+  "handover"
+];
+var VALID_STATUSES = [
+  "draft",
+  "decided",
+  "in-progress",
+  "completed",
+  "archived",
+  "rejected"
 ];
-var VALID_STATUSES = ["active", "superseded", "archived"];
 function isStrictPath(filePath) {
   const normalized = filePath.replace(/\\/g, "/");
   return /\/docs\/plans(\/|$)/.test(normalized) || /\/docs\/internal(\/|$)/.test(normalized);
@@ -43,8 +49,8 @@ function validateFrontmatter(doc, userRoot) {
     if (!rawFm.summary) {
       issues.push({ file: rel, field: "summary", message: "missing required field", severity: "error" });
     }
-    if (!rawFm.category) {
-      issues.push({ file: rel, field: "category", message: "missing required field", severity: "error" });
+    if (!rawFm.type) {
+      issues.push({ file: rel, field: "type", message: "recommended field missing (inferred from path)", severity: "warning" });
     }
   } else {
     if (!rawFm.title) {
@@ -53,16 +59,16 @@ function validateFrontmatter(doc, userRoot) {
     if (!rawFm.summary) {
       issues.push({ file: rel, field: "summary", message: "recommended field missing", severity: "warning" });
     }
-    if (!rawFm.category) {
-      issues.push({ file: rel, field: "category", message: "recommended field missing", severity: "warning" });
+    if (!rawFm.type) {
+      issues.push({ file: rel, field: "type", message: "recommended field missing (inferred from path)", severity: "warning" });
     }
   }
-  if (rawFm.category !== void 0) {
-    if (!VALID_CATEGORIES.includes(rawFm.category)) {
+  if (rawFm.type !== void 0) {
+    if (!VALID_TYPES.includes(rawFm.type)) {
       issues.push({
         file: rel,
-        field: "category",
-        message: `invalid value "${rawFm.category}" (allowed: ${VALID_CATEGORIES.join(", ")})`,
+        field: "type",
+        message: `invalid value "${rawFm.type}" (allowed: ${VALID_TYPES.join(", ")})`,
         severity: "error"
       });
     }
@@ -259,6 +265,8 @@ function levenshtein(a, b) {
 }
 
 export {
+  VALID_TYPES,
+  VALID_STATUSES,
   checkFrontmatter,
   checkLinks
 };

package/dist/node/{chunk-PZA4UAFG.js → chunk-XAX53RY5.js}

@@ -12,7 +12,7 @@ import {
 } from "./chunk-TVDWHKQF.js";
 import {
   clearifyPlugin
-} from "./chunk-Q5FUAK6J.js";
+} from "./chunk-LVPVSOXK.js";
 import {
   loadUserConfig,
   resolveConfig,
@@ -20,7 +20,7 @@ import {
 } from "./chunk-ZWF6VCSQ.js";
 import {
   buildSectionData
-} from "./chunk-CTL4YL7C.js";
+} from "./chunk-77IOLCAM.js";
 
 // src/node/build.ts
 import { build as viteBuild } from "vite";

package/dist/node/core/navigation.d.ts

@@ -1,2 +1,2 @@
 import '../types/index.js';
-export { D as DocFile, R as RootFileOptions, S as SectionData, b as buildNavigation, a as buildRoutes, c as buildSectionData, s as scanDocs } from './search.js';
+export { D as DocFile, R as RootFileOptions, S as SectionData, b as buildNavigation, a as buildRoutes, c as buildSectionData, i as inferDocType, s as scanDocs } from './search.js';

package/dist/node/core/navigation.js

@@ -2,12 +2,14 @@ import {
   buildNavigation,
   buildRoutes,
   buildSectionData,
+  inferDocType,
   scanDocs
-} from "../chunk-CTL4YL7C.js";
+} from "../chunk-77IOLCAM.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildNavigation,
   buildRoutes,
   buildSectionData,
+  inferDocType,
   scanDocs
 };

package/dist/node/core/search.d.ts

@@ -1,4 +1,4 @@
-import { PageFrontmatter, ResolvedSection, SectionNavigation, RouteEntry, NavigationItem } from '../types/index.js';
+import { PageFrontmatter, ResolvedSection, SectionNavigation, RouteEntry, NavigationItem, DocType } from '../types/index.js';
 
 interface SearchEntry {
     id: number;
@@ -11,6 +11,13 @@ interface SearchEntry {
 }
 declare function buildSearchIndex(docs: DocFile[], sectionId?: string, sectionLabel?: string): SearchEntry[];
 
+/**
+ * Infer the document `type` from its file path when frontmatter omits it.
+ * Mirrors the path-inference rules in the shared contract:
+ * knowledge-base/standards/document-lifecycle.md (the single source of truth).
+ * Returns undefined when nothing matches, leaving `type` unset (never filtered).
+ */
+declare function inferDocType(filePath: string): DocType | undefined;
 interface DocFile {
     filePath: string;
     routePath: string;
@@ -33,4 +40,4 @@ interface RootFileOptions {
 }
 declare function buildSectionData(section: ResolvedSection, rootFiles?: RootFileOptions, customNavigation?: NavigationItem[] | null): SectionData;
 
-export { type DocFile as D, type RootFileOptions as R, type SectionData as S, type SearchEntry, buildRoutes as a, buildNavigation as b, buildSearchIndex, buildSectionData as c, scanDocs as s };
+export { type DocFile as D, type RootFileOptions as R, type SectionData as S, type SearchEntry, buildRoutes as a, buildNavigation as b, buildSearchIndex, buildSectionData as c, inferDocType as i, scanDocs as s };

package/dist/node/node/build.js

@@ -1,15 +1,15 @@
 import {
   buildSite
-} from "../chunk-PZA4UAFG.js";
+} from "../chunk-XAX53RY5.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import "../chunk-TVDWHKQF.js";
-import "../chunk-Q5FUAK6J.js";
+import "../chunk-LVPVSOXK.js";
 import "../chunk-B2Q23JW3.js";
 import "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-CTL4YL7C.js";
+import "../chunk-77IOLCAM.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildSite

package/dist/node/node/check.d.ts

@@ -1,10 +1,14 @@
+import { DocStatus, DocType } from '../types/index.js';
+
 interface CheckOptions {
     frontmatterOnly?: boolean;
 }
+declare const VALID_TYPES: DocType[];
+declare const VALID_STATUSES: DocStatus[];
 declare function checkFrontmatter(): Promise<{
     errors: number;
     warnings: number;
 }>;
 declare function checkLinks(options?: CheckOptions): Promise<void>;
 
-export { type CheckOptions, checkFrontmatter, checkLinks };
+export { type CheckOptions, VALID_STATUSES, VALID_TYPES, checkFrontmatter, checkLinks };

package/dist/node/node/check.js

@@ -1,13 +1,17 @@
 import {
+  VALID_STATUSES,
+  VALID_TYPES,
   checkFrontmatter,
   checkLinks
-} from "../chunk-GZE6QLJT.js";
+} from "../chunk-V5J36LF5.js";
 import "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-CTL4YL7C.js";
+import "../chunk-77IOLCAM.js";
 import "../chunk-5TD7NQIW.js";
 export {
+  VALID_STATUSES,
+  VALID_TYPES,
   checkFrontmatter,
   checkLinks
 };

package/dist/node/node/index.d.ts

@@ -2,6 +2,7 @@ import * as vite from 'vite';
 export { buildSite as build } from './build.js';
 export { init } from './init.js';
 export { checkFrontmatter, checkLinks } from './check.js';
+import '../types/index.js';
 
 declare function createServer(options?: {
     port?: number;

package/dist/node/node/index.js

@@ -1,6 +1,6 @@
 import {
   buildSite
-} from "../chunk-PZA4UAFG.js";
+} from "../chunk-XAX53RY5.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
@@ -8,7 +8,7 @@ import "../chunk-SCZZB7OE.js";
 import "../chunk-TVDWHKQF.js";
 import {
   clearifyPlugin
-} from "../chunk-Q5FUAK6J.js";
+} from "../chunk-LVPVSOXK.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
@@ -16,14 +16,14 @@ import {
 import {
   checkFrontmatter,
   checkLinks
-} from "../chunk-GZE6QLJT.js";
+} from "../chunk-V5J36LF5.js";
 import {
   loadUserConfig,
   resolveConfig
 } from "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-CTL4YL7C.js";
+import "../chunk-77IOLCAM.js";
 import "../chunk-5TD7NQIW.js";
 
 // src/node/index.ts

package/dist/node/types/index.d.ts

@@ -77,17 +77,35 @@ interface NavigationItem {
     badgeColor?: string;
     children?: NavigationItem[];
 }
-type DocCategory = 'documentation' | 'internal' | 'plan' | 'research' | 'decision' | 'roadmap' | 'changelog';
+/**
+ * Document type vocabulary. Source of truth:
+ * knowledge-base/standards/document-lifecycle.md (the single contract both
+ * the Session Dashboard and Clearify read). Keep this union in sync with the
+ * "Type" table in that standard. `category` (the legacy field) and its values
+ * (`internal`, `research`, `decision`) were reconciled away in favor of `type`.
+ */
+type DocType = 'readme' | 'documentation' | 'plan' | 'roadmap' | 'changelog' | 'handover';
+/**
+ * Document status vocabulary. Source of truth:
+ * knowledge-base/standards/document-lifecycle.md.
+ *
+ * For `type: plan` this tracks the workflow lifecycle (all six values).
+ * For `type: documentation` only `draft` is meaningful (omitted = published).
+ * Status is optional on every type and a missing status is never filtered.
+ */
+type DocStatus = 'draft' | 'decided' | 'in-progress' | 'completed' | 'archived' | 'rejected';
 interface PageFrontmatter {
     title?: string;
     description?: string;
     icon?: string;
     order?: number;
     summary?: string;
-    category?: DocCategory;
+    /** See {@link DocType}. Inferred from path when omitted. */
+    type?: DocType;
     tags?: string[];
     projects?: string[];
-    status?: 'active' | 'superseded' | 'archived';
+    /** See {@link DocStatus}. Missing status is treated as unset (not filtered). */
+    status?: DocStatus;
     date?: string;
 }
 interface RouteEntry {
@@ -199,4 +217,4 @@ interface ClearifyDataConfig {
 }
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type ClearifyDataConfig, type DocCategory, type HubConfig, type HubProject, type HubProjectPartial, type HubProjectPlacement, type HubProjectSource, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type ClearifyDataConfig, type DocStatus, type DocType, type HubConfig, type HubProject, type HubProjectPartial, type HubProjectPlacement, type HubProjectSource, type NavigationItem, type PageFrontmatter, type RemoteGitSource, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };

package/dist/node/vite-plugin/index.js

@@ -1,11 +1,11 @@
 import {
   clearifyPlugin
-} from "../chunk-Q5FUAK6J.js";
+} from "../chunk-LVPVSOXK.js";
 import "../chunk-B2Q23JW3.js";
 import "../chunk-ZWF6VCSQ.js";
 import "../chunk-AJBCHKBP.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-CTL4YL7C.js";
+import "../chunk-77IOLCAM.js";
 import "../chunk-5TD7NQIW.js";
 export {
   clearifyPlugin

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "2.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "2.2.1",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -29,7 +32,8 @@
     "dev:self": "node bin/clearify.js dev",
     "prepare": "husky",
     "release": "semantic-release",
-    "test": "vitest run"
+    "test": "vitest run",
+    "check:roadmap": "npx --yes github:marlinjai/actions-shared#roadmap-check-v1 --root ."
   },
   "dependencies": {
     "@inquirer/password": "^5.0.11",
@@ -57,7 +61,7 @@
     "tailwindcss": "^4.1.18",
     "unist-util-visit": "^5.0.0",
     "vite": "^6.1.0",
-    "zod": "^4.3.6"
+    "zod": "^4.6.7"
   },
   "peerDependencies": {
     "puppeteer": ">=22.0.0",
@@ -80,7 +84,7 @@
     "@types/react-dom": "^18.3.5",
     "esbuild": "^0.27.3",
     "husky": "^9.1.7",
-    "puppeteer": "^24.37.2",
+    "puppeteer": "^25.0.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",