waymark-docs 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Waymark are documented in this file.
 
+## [0.2.2](https://github.com/ysfaran/waymark/compare/v0.2.1...v0.2.2) (2026-09-18)
+
+
+### Bug Fixes
+
+* **cli:** align help text with documentation ([#10](https://github.com/ysfaran/waymark/issues/10)) ([dbabc14](https://github.com/ysfaran/waymark/commit/dbabc14244d775cc8a38166d11a386674e282610))
+
+## [0.2.1](https://github.com/ysfaran/waymark/compare/v0.2.0...v0.2.1) (2026-08-13)
+
+
+### Documentation
+
+* **readme:** explain where Waymark fits ([ffe25dc](https://github.com/ysfaran/waymark/commit/ffe25dc15f1651519ad34e9e67f7fee90c69ef62))
+
 ## [0.2.0](https://github.com/ysfaran/waymark/compare/v0.1.1...v0.2.0) (2026-08-03)
 
 

package/README.md

@@ -1,14 +1,16 @@
 # 🪧 Waymark
 
-Find the right repository docs for your coding agent.
+[![npm version](https://img.shields.io/npm/v/waymark-docs.svg)](https://www.npmjs.com/package/waymark-docs)
 
-Waymark is a small, offline-first CLI built for AI agents. Add structured
-frontmatter to Markdown or MDX files, then let the agent select the kinds and
-tags relevant to its task. Waymark returns deterministic matches without
-ranking results or maintaining an index.
+Waymark is a small, offline-first CLI that helps coding agents find the right
+repository docs for each task. Add structured frontmatter to existing Markdown
+or MDX files, and agents can discover only relevant paths before opening a
+document without reading a large index or following linked navigation files
+that load unrelated context. It is as easy to set up as file-based navigation,
+but remains deterministic and token-efficient; unlike RAG or MCP-backed
+retrieval, it needs no ranking, maintained index or retrieval infrastructure.
 
-This makes documentation discovery token-efficient: agents spend less time
-searching unrelated files and more time working with the context they need.
+![Waymark reduces the effort required to find relevant context without retrieval infrastructure.](https://raw.githubusercontent.com/ysfaran/waymark/main/docs/assets/why-waymark.svg)
 
 ## Table of contents
 
@@ -35,7 +37,7 @@ npm install --save-dev waymark-docs
 
 ## Quick start
 
-1. **Create a Waymark configuration.**
+1. **Create a Waymark configuration**
 
    Run `init` in the repository root:
 
@@ -43,7 +45,7 @@ npm install --save-dev waymark-docs
    npx waymark init
    ```
 
-2. **Define searchable metadata.**
+2. **Define searchable metadata**
 
    Add the document kinds and tags that agents can search:
 
@@ -53,11 +55,11 @@ npm install --save-dev waymark-docs
      convention: Read before changing code to follow required repository practices
 
    tags:
-     architecture: System boundaries, component relationships, and dependencies
+     architecture: System boundaries, component relationships and dependencies
      typescript: TypeScript-related documentation
    ```
 
-3. **Register a document.**
+3. **Register a document**
 
    Add Waymark metadata to a Markdown or MDX file. For example, save this as
    `docs/conventions/typescript.md`:
@@ -71,7 +73,7 @@ npm install --save-dev waymark-docs
    # TypeScript conventions
    ```
 
-4. **Validate the repository.**
+4. **Validate the repository**
 
    Check the configuration and discovered documents:
 
@@ -88,16 +90,29 @@ npm install --save-dev waymark-docs
    Tags: 2
    ```
 
-5. **Discover the document.**
+5. **Discover documents**
 
-   Find the registered convention by kind and tag:
+   For a quick check, run `npx waymark find` with relevant kind and tag filters:
 
    ```sh
    npx waymark find --kinds convention --tags typescript --show description
    ```
 
    ```text
-   docs/conventions/typescript.md — TypeScript conventions for this repository
+   docs/conventions/typescript.md: TypeScript conventions for this repository
+   ```
+
+   To have agents use Waymark continuously, add this to `AGENTS.md`,
+   `CLAUDE.md` or an equivalent file:
+
+   ```md
+   ## Context Discovery
+
+   Before working on a non-trivial task, run `npx waymark status --show kind,tags`,
+   then use `npx waymark find` with relevant comma-separated `--kinds` and
+   `--tags` values, using `--show kind,tags,description` to inspect results.
+   Use `--query` for literal text searches and `--filter` for boolean expressions
+   over metadata when you need more detailed results.
    ```
 
 Waymark uses `waymark.yml` by default and also recognizes `waymark.yaml`. It
@@ -122,8 +137,10 @@ Create a starter configuration in the current directory.
 ```text
 Usage: waymark init [options]
 
+Create a starter Waymark configuration
+
 Options:
-  -h, --help  Display help for the command
+  -h, --help  display help for command
 ```
 
 ```sh
@@ -152,7 +169,7 @@ ignore:
   - vendor/**
 ```
 
-Ignore patterns are relative to the repository root and support `*`, `?`, and
+Ignore patterns are relative to the repository root and support `*`, `?` and
 `**` wildcards. Waymark also honors `.gitignore` automatically.
 
 `init` never overwrites an existing configuration and does not allow a nested
@@ -162,15 +179,17 @@ configuration beneath another Waymark root.
 
 Validate the Waymark configuration and all discovered Waymark Documents, then
 print the repository root and counts for registered documents, unregistered
-documents, kinds, and tags. Invalid repositories produce diagnostics and a
+documents, kinds and tags. Invalid repositories produce diagnostics and a
 non-zero exit code, which makes this command suitable for CI.
 
 ```text
 Usage: waymark status [options]
 
+Validate and summarize the Waymark repository
+
 Options:
-  -s, --show <fields>  Show declared kind and tag details (kind,tags)
-  -h, --help           Display help for the command
+  -s, --show <fields>  show declared kind and tag details (kind,tags)
+  -h, --help           display help for command
 ```
 
 Validate the repository:
@@ -199,16 +218,21 @@ Find registered Waymark Documents across the repository. With no filters,
 ```text
 Usage: waymark find [options]
 
+Discover Waymark Documents
+
 Options:
-  -k, --kinds <identifiers>         Match any kind (comma-separated, repeatable)
-  -t, --tags <identifiers>          Match any tag (comma-separated, repeatable)
-  -T, --require-tags <identifiers>  Require every tag (comma-separated, repeatable)
-  -f, --filter <expression>         Match a Boolean metadata filter
-  -q, --query <text>                Match a literal content query
-  -s, --show <fields>               Show kind, tags, and description
-  --json                            Return a flat JSON array
-  --tree                            Return a directory tree
-  -h, --help                        Display help for the command
+  -k, --kinds <identifiers>         match any kind (comma-separated, repeatable)
+  -t, --tags <identifiers>          match any tag (comma-separated, repeatable)
+  -T, --require-tags <identifiers>  require every tag (comma-separated,
+                                    repeatable)
+  -f, --filter <expression>         match a boolean filter expression
+  -q, --query <text>                match literal text content
+                                    (case-insensitive)
+  -s, --show <fields>               show kind, tags and description
+                                    (comma-separated)
+  --json                            return a flat JSON array
+  --tree                            output documents as directory tree
+  -h, --help                        display help for command
 ```
 
 Simple filter values use OR within an option. Different options combine with
@@ -230,20 +254,20 @@ npx waymark find --kinds adr --kinds convention
 ```
 
 Use `--query` for a case-insensitive literal search of document bodies. It can
-be combined with either simple or Boolean metadata filters:
+be combined with either simple or boolean metadata filters:
 
 ```sh
 npx waymark find --kinds convention --query "dependency injection"
 ```
 
-Use `--filter` for advanced metadata expressions with `kind:`, `tag:`, `NOT`,
-`AND`, `OR`, and parentheses:
+Use `--filter` for advanced boolean expressions over metadata with `kind:`,
+`tag:`, `NOT`, `AND`, `OR` and parentheses:
 
 ```sh
 npx waymark find --filter '(kind:adr OR kind:convention) AND tag:typescript AND NOT tag:architecture'
 ```
 
-`--filter` cannot be combined with `--kinds`, `--tags`, or `--require-tags`.
+`--filter` cannot be combined with `--kinds`, `--tags` or `--require-tags`.
 
 Add metadata fields to the default line-oriented output with `--show`:
 
@@ -275,13 +299,15 @@ Paths are returned relative to the repository root in deterministic order.
 ```text
 Usage: waymark ls [options] [directory]
 
+Inventory document registration in a directory
+
 Arguments:
-  directory           Directory to inspect (defaults to the current directory)
+  directory           directory to inspect (defaults to the current directory)
 
 Options:
-  -R, --recursive     Inspect directories recursively
-  -u, --unregistered  List only unregistered documents
-  -h, --help          Display help for the command
+  -R, --recursive     inspect directories recursively
+  -u, --unregistered  list only unregistered documents
+  -h, --help          display help for command
 ```
 
 List registered documents directly inside `docs`:
@@ -302,17 +328,13 @@ Find Markdown and MDX files that are missing Waymark metadata:
 npx waymark ls -R --unregistered docs
 ```
 
-`ls` respects `.gitignore`, Waymark ignore patterns, and Git directory boundaries.
+`ls` respects `.gitignore`, Waymark ignore patterns and Git directory boundaries.
 The selected directory must be inside the repository root.
 
 ### `waymark help`
 
 Show the command list or detailed help for one command:
 
-```text
-Usage: waymark help [command]
-```
-
 ```sh
 npx waymark --help
 npx waymark help find

package/dist/commands/find.js

@@ -5,19 +5,20 @@ import { filterDocuments, scanDocuments, } from "../documents/index.js";
 export function createFindCommand() {
     return new Command("find")
         .description("Discover Waymark Documents")
-        .option("-k, --kinds <identifiers>", "Match any Document Kind (comma-separated, repeatable)", collectOptionValue, [])
-        .option("-t, --tags <identifiers>", "Match any Document Tag (comma-separated, repeatable)", collectOptionValue, [])
-        .option("-T, --require-tags <identifiers>", "Require every Document Tag (comma-separated, repeatable)", collectOptionValue, [])
-        .option("-f, --filter <expression>", "Match a Boolean Metadata Filter")
-        .option("-q, --query <text>", "Match a literal Content Query")
-        .option("-s, --show <fields>", "Show kind, tags, and description (comma-separated)")
-        .option("--json", "Return a flat JSON array")
-        .option("--tree", "Return a directory-tree presentation")
+        .option("-k, --kinds <identifiers>", "match any kind (comma-separated, repeatable)", collectOptionValue)
+        .option("-t, --tags <identifiers>", "match any tag (comma-separated, repeatable)", collectOptionValue)
+        .option("-T, --require-tags <identifiers>", "require every tag (comma-separated, repeatable)", collectOptionValue)
+        .option("-f, --filter <expression>", "match a boolean filter expression")
+        .option("-q, --query <text>", "match literal text content (case-insensitive)")
+        .option("-s, --show <fields>", "show kind, tags and description (comma-separated)")
+        .option("--json", "return a flat JSON array")
+        .option("--tree", "output documents as directory tree")
         .action(async (options) => {
+        const kinds = options.kinds ?? [];
+        const tags = options.tags ?? [];
+        const requiredTags = options.requireTags ?? [];
         if (options.filter !== undefined &&
-            (options.kinds.length > 0 ||
-                options.tags.length > 0 ||
-                options.requireTags.length > 0)) {
+            (kinds.length > 0 || tags.length > 0 || requiredTags.length > 0)) {
             throw new Error("--filter cannot be combined with --kinds, --tags, or --require-tags.");
         }
         if (options.json && options.tree) {
@@ -25,27 +26,45 @@ export function createFindCommand() {
         }
         const shownFields = parseShownFields(options.show);
         const loadedConfiguration = await loadConfiguration(process.cwd());
-        if (loadedConfiguration.kind === "malformed") {
+        if (loadedConfiguration.kind === "invalid") {
             throwDiagnostics(loadedConfiguration.diagnostics);
         }
         const { configuration, rootPath } = loadedConfiguration;
+        const metadataCriteria = options.filter === undefined
+            ? {
+                method: "filter-groups",
+                kinds: parseIdentifierOptions({
+                    optionName: "--kinds",
+                    values: kinds,
+                    declarations: configuration.kinds,
+                    declarationName: "kind",
+                }),
+                tags: parseIdentifierOptions({
+                    optionName: "--tags",
+                    values: tags,
+                    declarations: configuration.tags,
+                    declarationName: "tag",
+                }),
+                requiredTags: parseIdentifierOptions({
+                    optionName: "--require-tags",
+                    values: requiredTags,
+                    declarations: configuration.tags,
+                    declarationName: "tag",
+                }),
+            }
+            : {
+                method: "filter-expression",
+                expression: options.filter,
+            };
         const documentScan = await scanDocuments({ rootPath, configuration });
-        const diagnostics = [
-            ...loadedConfiguration.diagnostics,
-            ...(documentScan.kind === "invalid" ? documentScan.diagnostics : []),
-        ].sort(compareDiagnostics);
-        if (loadedConfiguration.diagnostics.length > 0 ||
-            documentScan.kind === "invalid") {
-            throwDiagnostics(diagnostics);
+        if (documentScan.kind === "invalid") {
+            throwDiagnostics(documentScan.diagnostics.sort(compareDiagnostics));
         }
         const matchingDocuments = filterDocuments({
             documents: documentScan.documents,
             configuration,
             criteria: {
-                kinds: options.kinds,
-                tags: options.tags,
-                requiredTags: options.requireTags,
-                filter: options.filter,
+                metadata: metadataCriteria,
                 query: options.query,
             },
         });
@@ -169,7 +188,25 @@ function createTreeDirectory() {
     };
 }
 function collectOptionValue(value, previous) {
-    return [...previous, value];
+    return [...(previous ?? []), value];
+}
+function parseIdentifierOptions({ optionName, values, declarations, declarationName, }) {
+    const identifiers = new Set();
+    for (const value of values) {
+        for (const identifier of value.split(",")) {
+            if (identifier === "") {
+                throw new Error(`${optionName} contains an empty identifier.`);
+            }
+            if (identifiers.has(identifier)) {
+                throw new Error(`${optionName} contains duplicate identifier "${identifier}".`);
+            }
+            if (!declarations.has(identifier)) {
+                throw new Error(`${optionName} contains undeclared ${declarationName} "${identifier}".`);
+            }
+            identifiers.add(identifier);
+        }
+    }
+    return identifiers;
 }
 function compareText(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;

package/dist/commands/ls.js

@@ -6,15 +6,12 @@ import { scanDocuments } from "../documents/index.js";
 export function createLsCommand() {
     return new Command("ls")
         .description("Inventory document registration in a directory")
-        .argument("[directory]", "Directory to inspect")
-        .option("-R, --recursive", "Inspect directories recursively")
-        .option("-u, --unregistered", "List only Unregistered Documents")
+        .argument("[directory]", "directory to inspect (defaults to the current directory)")
+        .option("-R, --recursive", "inspect directories recursively")
+        .option("-u, --unregistered", "list only unregistered documents")
         .action(async (directory, options) => {
         const loadedConfiguration = await loadConfiguration(process.cwd());
-        if (loadedConfiguration.kind === "malformed") {
-            throwDiagnostics(loadedConfiguration.diagnostics);
-        }
-        if (loadedConfiguration.diagnostics.length > 0) {
+        if (loadedConfiguration.kind === "invalid") {
             throwDiagnostics(loadedConfiguration.diagnostics);
         }
         const rootPath = loadedConfiguration.rootPath;

package/dist/commands/status.js

@@ -5,24 +5,19 @@ import { scanDocuments } from "../documents/index.js";
 export function createStatusCommand() {
     return new Command("status")
         .description("Validate and summarize the Waymark repository")
-        .option("-s, --show <fields>", "Show declared kind and tag details (kind,tags)")
+        .option("-s, --show <fields>", "show declared kind and tag details (kind,tags)")
         .action(async (options) => {
         const shownFields = parseShownFields(options.show);
         const loadedConfiguration = await loadConfiguration(process.cwd());
-        if (loadedConfiguration.kind === "malformed") {
+        if (loadedConfiguration.kind === "invalid") {
             process.stdout.write(`Root: ${loadedConfiguration.rootPath}\n` + "Status: invalid\n");
             throwDiagnostics(loadedConfiguration.diagnostics);
         }
         const { configuration, rootPath } = loadedConfiguration;
         const documentScan = await scanDocuments({ rootPath, configuration });
-        const diagnostics = [
-            ...loadedConfiguration.diagnostics,
-            ...(documentScan.kind === "invalid" ? documentScan.diagnostics : []),
-        ].sort(compareDiagnostics);
-        if (loadedConfiguration.diagnostics.length > 0 ||
-            documentScan.kind === "invalid") {
+        if (documentScan.kind === "invalid") {
             process.stdout.write(`Root: ${rootPath}\n` + "Status: invalid\n");
-            throwDiagnostics(diagnostics);
+            throwDiagnostics(documentScan.diagnostics.sort(compareDiagnostics));
         }
         let output = `Root: ${rootPath}\n` +
             "Status: valid\n" +

package/dist/configuration/load.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export declare const defaultConfigFileName = "waymark.yml";
 export declare const allowedConfigFileNames: readonly ["waymark.yml", "waymark.yaml"];
 export type ConfigurationDeclaration = {
@@ -8,22 +9,33 @@ export type ConfigurationDiagnostic = {
     field: string;
     message: string;
 };
-export type Configuration = {
+declare const configurationSchema: z.ZodPipe<z.ZodObject<{
+    "require-namespace": z.ZodDefault<z.ZodBoolean>;
+    kinds: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Map<string, ConfigurationDeclaration>, Record<string, unknown>>>;
+    tags: z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Map<string, ConfigurationDeclaration>, Record<string, unknown>>>;
+    ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodTransform<{
     requireNamespace: boolean;
     kinds: Map<string, ConfigurationDeclaration>;
     tags: Map<string, ConfigurationDeclaration>;
     ignorePatterns: string[];
-};
+}, {
+    "require-namespace": boolean;
+    kinds: Map<string, ConfigurationDeclaration>;
+    tags: Map<string, ConfigurationDeclaration>;
+    ignore: string[];
+}>>;
+export type Configuration = z.infer<typeof configurationSchema>;
 export type ConfigurationLoadResult = {
     kind: "loaded";
     rootPath: string;
     configuration: Configuration;
-    diagnostics: ConfigurationDiagnostic[];
 } | {
-    kind: "malformed";
+    kind: "invalid";
     rootPath: string;
     diagnostics: ConfigurationDiagnostic[];
 };
 export declare function loadConfiguration(startingDirectoryPath: string): Promise<ConfigurationLoadResult>;
 export declare function findConfigurationPath(startingDirectoryPath: string): Promise<string | undefined>;
 export declare function findConfigurationPathInDirectory(directoryPath: string): Promise<string | undefined>;
+export {};

package/dist/configuration/load.js

@@ -1,12 +1,80 @@
 import { readFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 import { parse } from "yaml";
+import { z } from "zod";
+import { compareDiagnostics } from "../diagnostics.js";
 import { pathExists } from "../filesystem.js";
 export const defaultConfigFileName = "waymark.yml";
 export const allowedConfigFileNames = [
     defaultConfigFileName,
     "waymark.yaml",
 ];
+const ignorePatternSchema = z
+    .string({ error: "Ignore glob must be a non-empty string." })
+    .superRefine((pattern, context) => {
+    if (pattern.trim() === "") {
+        context.addIssue({
+            code: "custom",
+            message: "Ignore glob must be a non-empty string.",
+        });
+        return;
+    }
+    if (pattern.startsWith("!")) {
+        context.addIssue({
+            code: "custom",
+            message: "Negation is not supported in ignore globs.",
+        });
+        return;
+    }
+    if (/[![\]{}()]/.test(pattern)) {
+        context.addIssue({
+            code: "custom",
+            message: "Only *, ?, and ** wildcard syntax is supported.",
+        });
+    }
+});
+const configurationDeclarationsSchema = z
+    .record(z.string(), z.unknown(), { error: "Expected a mapping." })
+    .superRefine((declarations, context) => {
+    for (const [identifier, description] of Object.entries(declarations)) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identifier)) {
+            context.addIssue({
+                code: "custom",
+                path: [identifier],
+                message: "Identifier must use lowercase kebab-case.",
+            });
+        }
+        if (typeof description !== "string" || description.trim() === "") {
+            context.addIssue({
+                code: "custom",
+                path: [identifier],
+                message: "Description must be a non-empty string.",
+            });
+        }
+    }
+})
+    .transform((declarations) => new Map(Object.entries(declarations)
+    .filter((entry) => typeof entry[1] === "string")
+    .map(([identifier, description]) => [identifier, { description }])));
+const configurationSchema = z
+    .strictObject({
+    "require-namespace": z
+        .boolean({ error: "Expected a boolean." })
+        .default(false),
+    kinds: configurationDeclarationsSchema,
+    tags: configurationDeclarationsSchema,
+    ignore: z
+        .array(ignorePatternSchema, {
+        error: "Expected a sequence of ignore globs.",
+    })
+        .default([]),
+}, { error: "Expected a mapping." })
+    .transform((configuration) => ({
+    requireNamespace: configuration["require-namespace"],
+    kinds: configuration.kinds,
+    tags: configuration.tags,
+    ignorePatterns: configuration.ignore,
+}));
 export async function loadConfiguration(startingDirectoryPath) {
     const configurationPath = await findConfigurationPath(startingDirectoryPath);
     if (!configurationPath) {
@@ -20,7 +88,7 @@ export async function loadConfiguration(startingDirectoryPath) {
     }
     catch {
         return {
-            kind: "malformed",
+            kind: "invalid",
             rootPath,
             diagnostics: [
                 {
@@ -31,16 +99,21 @@ export async function loadConfiguration(startingDirectoryPath) {
             ],
         };
     }
-    const diagnostics = [];
+    const configurationResult = configurationSchema.safeParse(parsedConfiguration);
+    if (!configurationResult.success) {
+        return {
+            kind: "invalid",
+            rootPath,
+            diagnostics: createConfigurationDiagnostics({
+                error: configurationResult.error,
+                configurationFileName: loadedConfigurationFileName,
+            }),
+        };
+    }
     return {
         kind: "loaded",
         rootPath,
-        configuration: validateConfiguration({
-            value: parsedConfiguration,
-            configurationFileName: loadedConfigurationFileName,
-            diagnostics,
-        }),
-        diagnostics,
+        configuration: configurationResult.data,
     };
 }
 export async function findConfigurationPath(startingDirectoryPath) {
@@ -70,133 +143,25 @@ export async function findConfigurationPathInDirectory(directoryPath) {
     }
     return configurationPaths[0];
 }
-function validateConfiguration({ value, configurationFileName, diagnostics, }) {
-    if (!isRecord(value)) {
-        diagnostics.push({
-            path: configurationFileName,
-            field: "configuration",
-            message: "Expected a mapping.",
-        });
-    }
-    const configuration = isRecord(value) ? value : {};
-    const allowedFields = new Set([
-        "require-namespace",
-        "kinds",
-        "tags",
-        "ignore",
-    ]);
-    for (const field of Object.keys(configuration)) {
-        if (!allowedFields.has(field)) {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Unknown field.",
-            });
+function createConfigurationDiagnostics({ error, configurationFileName, }) {
+    const diagnostics = [];
+    for (const issue of error.issues) {
+        const field = issue.path.join(".") || "configuration";
+        if (issue.code === "unrecognized_keys") {
+            for (const key of issue.keys) {
+                diagnostics.push({
+                    path: configurationFileName,
+                    field: [...issue.path, key].join("."),
+                    message: "Unknown field.",
+                });
+            }
+            continue;
         }
-    }
-    if (configuration["require-namespace"] !== undefined &&
-        typeof configuration["require-namespace"] !== "boolean") {
-        diagnostics.push({
-            path: configurationFileName,
-            field: "require-namespace",
-            message: "Expected a boolean.",
-        });
-    }
-    return {
-        requireNamespace: configuration["require-namespace"] === true,
-        kinds: validateDeclarations({
-            value: configuration.kinds,
-            field: "kinds",
-            configurationFileName,
-            diagnostics,
-        }),
-        tags: validateDeclarations({
-            value: configuration.tags,
-            field: "tags",
-            configurationFileName,
-            diagnostics,
-        }),
-        ignorePatterns: validateIgnorePatterns({
-            value: configuration.ignore,
-            configurationFileName,
-            diagnostics,
-        }),
-    };
-}
-function validateDeclarations({ value, field, configurationFileName, diagnostics, }) {
-    if (!isRecord(value)) {
         diagnostics.push({
             path: configurationFileName,
             field,
-            message: "Expected a mapping.",
-        });
-        return new Map();
-    }
-    const declarations = new Map();
-    for (const [identifier, description] of Object.entries(value)) {
-        const diagnosticField = `${field}.${identifier}`;
-        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(identifier)) {
-            diagnostics.push({
-                path: configurationFileName,
-                field: diagnosticField,
-                message: "Identifier must use lowercase kebab-case.",
-            });
-        }
-        if (typeof description !== "string" || description.trim() === "") {
-            diagnostics.push({
-                path: configurationFileName,
-                field: diagnosticField,
-                message: "Description must be a non-empty string.",
-            });
-        }
-        declarations.set(identifier, {
-            description: typeof description === "string" ? description : "",
-        });
-    }
-    return declarations;
-}
-function validateIgnorePatterns({ value, configurationFileName, diagnostics, }) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value)) {
-        diagnostics.push({
-            path: configurationFileName,
-            field: "ignore",
-            message: "Expected a sequence of ignore globs.",
+            message: issue.message,
         });
-        return [];
     }
-    const ignorePatterns = [];
-    for (const [index, pattern] of value.entries()) {
-        const field = `ignore.${index}`;
-        if (typeof pattern !== "string" || pattern.trim() === "") {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Ignore glob must be a non-empty string.",
-            });
-            continue;
-        }
-        if (pattern.startsWith("!")) {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Negation is not supported in ignore globs.",
-            });
-            continue;
-        }
-        if (/[![\]{}()]/.test(pattern)) {
-            diagnostics.push({
-                path: configurationFileName,
-                field,
-                message: "Only *, ?, and ** wildcard syntax is supported.",
-            });
-            continue;
-        }
-        ignorePatterns.push(pattern);
-    }
-    return ignorePatterns;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return diagnostics.sort(compareDiagnostics);
 }

package/dist/documents/classify.d.ts

@@ -1,8 +1,6 @@
+import { z } from "zod";
 import type { ConfigurationDeclaration } from "../configuration/index.js";
-type ClassifiedDocument = {
-    kind: string;
-    description: string;
-    tags: string[];
+type ClassifiedDocument = z.infer<ReturnType<typeof createDocumentSchema>> & {
     body: string;
 };
 type DocumentDiagnostic = {
@@ -26,4 +24,12 @@ export declare function classifyDocument({ source, requireNamespace, declaredKin
     declaredTags: Map<string, ConfigurationDeclaration>;
     path: string;
 }): DocumentClassification;
+declare function createDocumentSchema({ declaredKinds, declaredTags, }: {
+    declaredKinds: Map<string, ConfigurationDeclaration>;
+    declaredTags: Map<string, ConfigurationDeclaration>;
+}): z.ZodObject<{
+    kind: z.ZodString;
+    description: z.ZodString;
+    tags: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodUnknown>>, z.ZodTransform<string[], unknown[]>>;
+}, z.core.$strict>;
 export {};

package/dist/documents/classify.js

@@ -1,4 +1,6 @@
 import { parse } from "yaml";
+import { z } from "zod";
+const rawFrontmatterSchema = z.record(z.string(), z.unknown());
 export function classifyDocument({ source, requireNamespace, declaredKinds, declaredTags, path, }) {
     const frontmatter = readFrontmatter(source);
     if (frontmatter.kind === "malformed") {
@@ -13,11 +15,14 @@ export function classifyDocument({ source, requireNamespace, declaredKinds, decl
             ],
         };
     }
-    if (frontmatter.kind === "none" || !isRecord(frontmatter.value)) {
+    if (frontmatter.kind === "none") {
         return { kind: "unregistered" };
     }
+    const frontmatterResult = rawFrontmatterSchema.safeParse(frontmatter.value);
+    if (!frontmatterResult.success)
+        return { kind: "unregistered" };
     return validateRegistration({
-        frontmatter: frontmatter.value,
+        frontmatter: frontmatterResult.data,
         body: frontmatter.body,
         requireNamespace,
         declaredKinds,
@@ -52,152 +57,126 @@ function validateRegistration({ frontmatter, body, requireNamespace, declaredKin
     if (!requireNamespace && !hasNamespace && !hasRecognizedFlatMetadata) {
         return { kind: "unregistered" };
     }
-    const diagnostics = [];
     if (hasNamespace && hasRecognizedFlatMetadata) {
-        diagnostics.push({
-            path,
-            field: "waymark",
-            message: "Flat and namespaced metadata cannot both be declared.",
-        });
-        return { kind: "invalid", diagnostics };
+        return {
+            kind: "invalid",
+            diagnostics: [
+                {
+                    path,
+                    field: "waymark",
+                    message: "Flat and namespaced metadata cannot both be declared.",
+                },
+            ],
+        };
     }
     const namespaced = hasNamespace;
-    const value = namespaced ? frontmatter.waymark : frontmatter;
+    const value = namespaced
+        ? frontmatter.waymark
+        : {
+            kind: frontmatter.kind,
+            description: frontmatter.description,
+            tags: frontmatter.tags,
+        };
     const fieldPrefix = namespaced ? "waymark." : "";
-    if (!isRecord(value)) {
-        diagnostics.push({
-            path,
-            field: namespaced ? "waymark" : "frontmatter",
-            message: "Expected a mapping.",
-        });
-        return { kind: "invalid", diagnostics };
-    }
-    if (namespaced) {
-        const allowedFields = new Set(["kind", "description", "tags"]);
-        for (const field of Object.keys(value)) {
-            if (!allowedFields.has(field)) {
-                diagnostics.push({
-                    path,
-                    field: `${fieldPrefix}${field}`,
-                    message: "Unknown field.",
-                });
-            }
-        }
-    }
-    const context = { path, declaredKinds, declaredTags, diagnostics };
-    const kind = validateDocumentKind({
-        value: value.kind,
-        field: `${fieldPrefix}kind`,
-        context,
-    });
-    const description = validateDocumentDescription({
-        value: value.description,
-        field: `${fieldPrefix}description`,
-        context,
-    });
-    const tags = validateDocumentTags({
-        value: value.tags,
-        field: `${fieldPrefix}tags`,
-        context,
-    });
-    if (diagnostics.length > 0 ||
-        kind === undefined ||
-        description === undefined ||
-        tags === undefined) {
-        return { kind: "invalid", diagnostics };
+    const metadataResult = createDocumentSchema({
+        declaredKinds,
+        declaredTags,
+    }).safeParse(value);
+    if (!metadataResult.success) {
+        return {
+            kind: "invalid",
+            diagnostics: createDocumentDiagnostics({
+                error: metadataResult.error,
+                path,
+                fieldPrefix,
+                rootField: namespaced ? "waymark" : "frontmatter",
+            }),
+        };
     }
     return {
         kind: "registered",
-        document: { kind, description, tags, body },
+        document: { ...metadataResult.data, body },
     };
 }
-function validateDocumentKind({ value, field, context, }) {
-    if (value === undefined) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document kind is required.",
-        });
-        return undefined;
-    }
-    if (typeof value !== "string" || value.trim() === "") {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document kind must be a non-empty string.",
-        });
-        return undefined;
-    }
-    if (!context.declaredKinds.has(value)) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: `Undeclared kind "${value}".`,
-        });
-    }
-    return value;
-}
-function validateDocumentDescription({ value, field, context, }) {
-    if (value === undefined) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document Description is required.",
-        });
-        return undefined;
-    }
-    if (typeof value !== "string" || value.trim() === "") {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Document Description must be a non-empty string.",
-        });
-        return undefined;
-    }
-    return value;
+function createDocumentSchema({ declaredKinds, declaredTags, }) {
+    return z.strictObject({
+        kind: z
+            .string({
+            error: (issue) => issue.input === undefined
+                ? "Document kind is required."
+                : "Document kind must be a non-empty string.",
+        })
+            .refine((kind) => kind.trim() !== "", {
+            error: "Document kind must be a non-empty string.",
+        })
+            .superRefine((kind, context) => {
+            if (kind.trim() !== "" && !declaredKinds.has(kind)) {
+                context.addIssue({
+                    code: "custom",
+                    message: `Undeclared kind "${kind}".`,
+                });
+            }
+        }),
+        description: z
+            .string({
+            error: (issue) => issue.input === undefined
+                ? "Document Description is required."
+                : "Document Description must be a non-empty string.",
+        })
+            .refine((description) => description.trim() !== "", {
+            error: "Document Description must be a non-empty string.",
+        }),
+        tags: z
+            .array(z.unknown(), { error: "Expected a YAML sequence of tags." })
+            .default([])
+            .superRefine((tags, context) => {
+            const seenTags = new Set();
+            for (const tag of tags) {
+                if (typeof tag !== "string" || tag.trim() === "") {
+                    context.addIssue({
+                        code: "custom",
+                        message: "Every tag must be a non-empty string.",
+                    });
+                    continue;
+                }
+                if (seenTags.has(tag)) {
+                    context.addIssue({
+                        code: "custom",
+                        message: `Duplicate tag "${tag}".`,
+                    });
+                    continue;
+                }
+                seenTags.add(tag);
+                if (!declaredTags.has(tag)) {
+                    context.addIssue({
+                        code: "custom",
+                        message: `Undeclared tag "${tag}".`,
+                    });
+                }
+            }
+        })
+            .transform((tags) => tags.filter((tag) => typeof tag === "string")),
+    }, { error: "Expected a mapping." });
 }
-function validateDocumentTags({ value, field, context, }) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value)) {
-        context.diagnostics.push({
-            path: context.path,
-            field,
-            message: "Expected a YAML sequence of tags.",
-        });
-        return undefined;
-    }
-    const tags = [];
-    const seenTags = new Set();
-    for (const tag of value) {
-        if (typeof tag !== "string" || tag.trim() === "") {
-            context.diagnostics.push({
-                path: context.path,
-                field,
-                message: "Every tag must be a non-empty string.",
-            });
-            continue;
-        }
-        if (seenTags.has(tag)) {
-            context.diagnostics.push({
-                path: context.path,
-                field,
-                message: `Duplicate tag "${tag}".`,
-            });
+function createDocumentDiagnostics({ error, path, fieldPrefix, rootField, }) {
+    const diagnostics = [];
+    for (const issue of error.issues) {
+        if (issue.code === "unrecognized_keys") {
+            for (const key of issue.keys) {
+                diagnostics.push({
+                    path,
+                    field: `${fieldPrefix}${key}`,
+                    message: "Unknown field.",
+                });
+            }
             continue;
         }
-        seenTags.add(tag);
-        tags.push(tag);
-        if (!context.declaredTags.has(tag)) {
-            context.diagnostics.push({
-                path: context.path,
-                field,
-                message: `Undeclared tag "${tag}".`,
-            });
-        }
+        const field = issue.path.find((segment) => typeof segment === "string");
+        diagnostics.push({
+            path,
+            field: field === undefined ? rootField : `${fieldPrefix}${field}`,
+            message: issue.message,
+        });
     }
-    return tags;
-}
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    return diagnostics;
 }

package/dist/documents/filter.d.ts

@@ -4,11 +4,17 @@ type FilterableDocument = {
     kind: string;
     tags: string[];
 };
+type MetadataCriteria = {
+    method: "filter-groups";
+    kinds: Set<string>;
+    tags: Set<string>;
+    requiredTags: Set<string>;
+} | {
+    method: "filter-expression";
+    expression: string;
+};
 type DocumentCriteria = {
-    kinds: string[];
-    tags: string[];
-    requiredTags: string[];
-    filter?: string;
+    metadata: MetadataCriteria;
     query?: string;
 };
 export declare function filterDocuments({ documents, configuration, criteria, }: {

package/dist/documents/filter.js

@@ -1,36 +1,18 @@
 export function filterDocuments({ documents, configuration, criteria, }) {
-    const kinds = parseIdentifierOptions({
-        optionName: "--kinds",
-        values: criteria.kinds,
-        declarations: configuration.kinds,
-        declarationName: "kind",
-    });
-    const tags = parseIdentifierOptions({
-        optionName: "--tags",
-        values: criteria.tags,
-        declarations: configuration.tags,
-        declarationName: "tag",
-    });
-    const requiredTags = parseIdentifierOptions({
-        optionName: "--require-tags",
-        values: criteria.requiredTags,
-        declarations: configuration.tags,
-        declarationName: "tag",
-    });
-    const matchesMetadataFilter = criteria.filter === undefined
-        ? undefined
-        : parseMetadataFilter({
-            expression: criteria.filter,
+    const metadata = criteria.metadata;
+    const matchesMetadata = metadata.method === "filter-expression"
+        ? parseMetadataFilter({
+            expression: metadata.expression,
             declaredKinds: new Set(configuration.kinds.keys()),
             declaredTags: new Set(configuration.tags.keys()),
-        });
+        })
+        : (document) => (metadata.kinds.size === 0 || metadata.kinds.has(document.kind)) &&
+            (metadata.tags.size === 0 ||
+                document.tags.some((tag) => metadata.tags.has(tag))) &&
+            [...metadata.requiredTags].every((tag) => document.tags.includes(tag));
     const normalizedQuery = criteria.query?.toLowerCase();
     return documents
-        .filter((document) => (kinds.size === 0 || kinds.has(document.kind)) &&
-        (tags.size === 0 || document.tags.some((tag) => tags.has(tag))) &&
-        [...requiredTags].every((tag) => document.tags.includes(tag)) &&
-        (matchesMetadataFilter === undefined ||
-            matchesMetadataFilter(document)) &&
+        .filter((document) => matchesMetadata(document) &&
         (normalizedQuery === undefined ||
             document.body.toLowerCase().includes(normalizedQuery)))
         .sort((left, right) => compareText(left.path, right.path));
@@ -189,24 +171,6 @@ function describeToken(token) {
         return '"("';
     return `"${token.type.toUpperCase()}"`;
 }
-function parseIdentifierOptions({ optionName, values, declarations, declarationName, }) {
-    const identifiers = new Set();
-    for (const value of values) {
-        for (const identifier of value.split(",")) {
-            if (identifier === "") {
-                throw new Error(`${optionName} contains an empty identifier.`);
-            }
-            if (identifiers.has(identifier)) {
-                throw new Error(`${optionName} contains duplicate identifier "${identifier}".`);
-            }
-            if (!declarations.has(identifier)) {
-                throw new Error(`${optionName} contains undeclared ${declarationName} "${identifier}".`);
-            }
-            identifiers.add(identifier);
-        }
-    }
-    return identifiers;
-}
 function compareText(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waymark-docs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Agent-focused CLI that surfaces repository documentation to improve coding-agent performance.",
   "keywords": [
     "ai-agents",
@@ -45,7 +45,8 @@
   "dependencies": {
     "commander": "14.0.3",
     "globby": "16.2.2",
-    "yaml": "2.9.0"
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "24.10.10",