waymark-docs 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Waymark are documented in this file.
 
+## [0.3.1](https://github.com/ysfaran/waymark/compare/v0.3.0...v0.3.1) (2026-09-26)
+
+
+### Bug Fixes
+
+* **cli:** support root document inventory ([#14](https://github.com/ysfaran/waymark/issues/14)) ([6c61727](https://github.com/ysfaran/waymark/commit/6c617278dc20bf938f3ef07c0975893483de9825))
+
+## [0.3.0](https://github.com/ysfaran/waymark/compare/v0.2.2...v0.3.0) (2026-09-25)
+
+
+### Features
+
+* **cli:** add document scope option ([#12](https://github.com/ysfaran/waymark/issues/12)) ([2a6b67f](https://github.com/ysfaran/waymark/commit/2a6b67f00244de004a0c1eb47548ace90a720e7d))
+
 ## [0.2.2](https://github.com/ysfaran/waymark/compare/v0.2.1...v0.2.2) (2026-09-18)
 
 

package/README.md

@@ -4,12 +4,18 @@
 
 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
+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
+but remains deterministic and token-efficient. Unlike RAG or MCP-backed
 retrieval, it needs no ranking, maintained index or retrieval infrastructure.
 
+Each document has three searchable metadata dimensions:
+
+1. **Scope:** Where does this document apply? (`backend`, `search-service`)
+2. **Kind:** What role does this document serve? (`convention`, `agent-guide`, `adr`)
+3. **Tags:** What topics does it cover? (`testing`, `typescript`)
+
 ![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
@@ -19,6 +25,7 @@ retrieval, it needs no ranking, maintained index or retrieval infrastructure.
 - [Commands](#commands)
   - [`waymark init`](#waymark-init)
   - [`waymark status`](#waymark-status)
+  - [`waymark show`](#waymark-show)
   - [`waymark find`](#waymark-find)
   - [`waymark ls`](#waymark-ls)
   - [`waymark help`](#waymark-help)
@@ -26,7 +33,16 @@ retrieval, it needs no ranking, maintained index or retrieval infrastructure.
 
 ## Installation
 
-Install the `waymark-docs` package as a development dependency:
+Install the `waymark` and `waymark-setup` skills for your coding agents:
+
+```sh
+npx skills add ysfaran/waymark --skill waymark --skill waymark-setup
+```
+
+`waymark-setup` automatically detects the active package manager and installs
+`waymark-docs` locally as a development dependency.
+
+To install the CLI manually instead, run the matching command:
 
 ```sh
 pnpm add -D waymark-docs
@@ -37,88 +53,19 @@ npm install --save-dev waymark-docs
 
 ## Quick start
 
-1. **Create a Waymark configuration**
-
-   Run `init` in the repository root:
-
-   ```sh
-   npx waymark init
-   ```
-
-2. **Define searchable metadata**
-
-   Add the document kinds and tags that agents can search:
-
-   ```yaml
-   kinds:
-     adr: Read to understand past architectural decisions and their constraints
-     convention: Read before changing code to follow required repository practices
-
-   tags:
-     architecture: System boundaries, component relationships and dependencies
-     typescript: TypeScript-related documentation
-   ```
-
-3. **Register a document**
-
-   Add Waymark metadata to a Markdown or MDX file. For example, save this as
-   `docs/conventions/typescript.md`:
-
-   ```yaml
-   ---
-   kind: convention
-   description: TypeScript conventions for this repository
-   tags: [typescript]
-   ---
-   # TypeScript conventions
-   ```
-
-4. **Validate the repository**
-
-   Check the configuration and discovered documents:
+1. Install the skills in the repository you want to set up:
 
    ```sh
-   npx waymark status
-   ```
-
-   ```text
-   Root: /path/to/repository
-   Status: valid
-   Waymark Documents: 1
-   Unregistered Documents: 1
-   Kinds: 2
-   Tags: 2
+   npx skills add ysfaran/waymark --skill waymark --skill waymark-setup
    ```
 
-5. **Discover documents**
-
-   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
-   ```
-
-   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
-looks for the configuration in the current directory and its ancestors, so
-commands can also run from a nested repository directory. Use only one filename
-per directory.
+2. Ask your coding agent to use `waymark-setup`. This one-time interactive
+   setup installs the CLI, configures the repository, registers useful
+   documents and adds an instruction to `AGENTS.md` or an equivalent file to
+   use the `waymark` skill for non-trivial tasks.
+3. Review the generated `waymark.yml` configuration file, then give a fresh
+   agent a non-trivial task and confirm it uses Waymark to discover relevant
+   context before working.
 
 ## Commands
 
@@ -126,6 +73,7 @@ per directory.
 | ---------------- | --------------------------------------------------------- |
 | `waymark init`   | Create a starter configuration                            |
 | `waymark status` | Validate and summarize the repository                     |
+| `waymark show`   | List declared scopes, kinds and tags                      |
 | `waymark find`   | Find registered documents across the repository           |
 | `waymark ls`     | Audit registered or unregistered documents in a directory |
 | `waymark help`   | Show CLI or command-specific help                         |
@@ -148,17 +96,26 @@ npx waymark init
 ```
 
 The generated file explains metadata namespacing and includes declarations to
-replace with your own kind and tag:
+replace with your own scope, kind and tag:
 
 ```yaml
 # When true, document metadata must be nested under a `waymark` frontmatter key.
 require-namespace: false
+# When true, every waymark document must declare at least one scope.
+require-scopes: false
+scopes:
+  example-scope: Explain the repository area represented by this scope
 kinds:
   example-kind: Explain when agents should read this kind of document
 tags:
   example-tag: Explain the topic represented by this tag
 ```
 
+The `scopes` map is optional, so existing configurations remain valid. Document
+scopes are flat declared identifiers: they express applicability independently
+of file paths and do not inherit from one another. Documents may omit `scopes`
+unless `require-scopes: true` is configured.
+
 To skip generated or vendored documentation during discovery, add `ignore`
 patterns:
 
@@ -179,8 +136,8 @@ 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
-non-zero exit code, which makes this command suitable for CI.
+documents, scopes, 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]
@@ -188,8 +145,7 @@ 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 command
+  -h, --help  display help for command
 ```
 
 Validate the repository:
@@ -198,16 +154,33 @@ Validate the repository:
 npx waymark status
 ```
 
-List every declared kind and tag with its description and usage count:
+### `waymark show`
 
-```sh
-npx waymark status --show kind,tags
-```
+List the declared scope, kind and tag vocabulary with descriptions and document
+usage counts. Pass a category to show only that vocabulary. `--scopes` narrows
+kind and tag counts to documents matching any selected scope and omits values
+unused by that selection.
 
-Show only kind details:
+```text
+Usage: waymark show [options] [category]
+
+List declared scopes, kinds, and tags
+
+Arguments:
+  category                 list only scopes, kinds, or tags
+                           (choices: "scopes", "kinds", "tags")
+
+Options:
+  --scopes <identifiers>   select documents matching any scope (comma-separated,
+                           repeatable)
+  -h, --help               display help for command
+```
 
 ```sh
-npx waymark status --show kind
+npx waymark show
+npx waymark show scopes
+npx waymark show kinds --scopes backend,search-service
+npx waymark show tags --scopes backend
 ```
 
 ### `waymark find`
@@ -221,6 +194,8 @@ Usage: waymark find [options]
 Discover Waymark Documents
 
 Options:
+  --scopes <identifiers>            match any scope (comma-separated,
+                                    repeatable)
   -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,
@@ -228,25 +203,26 @@ Options:
   -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)
+  -s, --show <fields>               show only selected metadata fields
+                                    (comma-separated; defaults to all)
   --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
-AND:
+AND. A scope filter excludes documents that declare no scope:
 
 ```sh
-# Kind is adr OR convention, and at least one tag is typescript OR architecture
-npx waymark find --kinds adr,convention --tags typescript,architecture
+# Scope is backend OR search-service, kind is adr OR convention, and at least
+# one tag is typescript OR architecture
+npx waymark find --scopes backend,search-service --kinds adr,convention --tags typescript,architecture
 
 # Kind is adr, and both architecture AND typescript tags are required
 npx waymark find --kinds adr --require-tags architecture,typescript
 ```
 
-The three simple metadata filters are repeatable. Repeating an option is
+The four simple metadata filters are repeatable. Repeating an option is
 equivalent to passing a comma-separated list:
 
 ```sh
@@ -260,19 +236,21 @@ be combined with either simple or boolean metadata filters:
 npx waymark find --kinds convention --query "dependency injection"
 ```
 
-Use `--filter` for advanced boolean expressions over metadata with `kind:`,
-`tag:`, `NOT`, `AND`, `OR` and parentheses:
+Use `--filter` for advanced Boolean expressions over metadata with `scope:`,
+`kind:`, `tag:`, `NOT`, `AND`, `OR` and parentheses:
 
 ```sh
-npx waymark find --filter '(kind:adr OR kind:convention) AND tag:typescript AND NOT tag:architecture'
+npx waymark find --filter 'scope:backend AND (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 `--scopes`, `--kinds`, `--tags` or
+`--require-tags`.
 
-Add metadata fields to the default line-oriented output with `--show`:
+By default, line, JSON and tree output include scopes, kind, tags and
+description in that order. Use `--show` to select a non-empty subset:
 
 ```sh
-npx waymark find --kinds convention --show kind,tags,description
+npx waymark find --kinds convention --show kind,description
 ```
 
 Return structured output for scripts and agents:

package/dist/cli.js

@@ -4,6 +4,7 @@ import packageJson from "../package.json" with { type: "json" };
 import { createFindCommand } from "./commands/find.js";
 import { createInitCommand } from "./commands/init.js";
 import { createLsCommand } from "./commands/ls.js";
+import { createShowCommand } from "./commands/show.js";
 import { createStatusCommand } from "./commands/status.js";
 const program = new Command()
     .name("waymark")
@@ -12,6 +13,7 @@ const program = new Command()
     .exitOverride();
 program.addCommand(createInitCommand());
 program.addCommand(createStatusCommand());
+program.addCommand(createShowCommand());
 program.addCommand(createFindCommand());
 program.addCommand(createLsCommand());
 try {

package/dist/commands/find.js

@@ -2,24 +2,30 @@ import { Command } from "commander";
 import { loadConfiguration } from "../configuration/index.js";
 import { compareDiagnostics, throwDiagnostics } from "../diagnostics.js";
 import { filterDocuments, scanDocuments, } from "../documents/index.js";
+const SHOWN_FIELDS = ["scopes", "kind", "tags", "description"];
 export function createFindCommand() {
     return new Command("find")
         .description("Discover Waymark Documents")
+        .option("--scopes <identifiers>", "match any scope (comma-separated, repeatable)", collectOptionValue)
         .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("-s, --show <fields>", "show only selected metadata fields (comma-separated; defaults to all)")
         .option("--json", "return a flat JSON array")
         .option("--tree", "output documents as directory tree")
         .action(async (options) => {
+        const scopes = options.scopes ?? [];
         const kinds = options.kinds ?? [];
         const tags = options.tags ?? [];
         const requiredTags = options.requireTags ?? [];
         if (options.filter !== undefined &&
-            (kinds.length > 0 || tags.length > 0 || requiredTags.length > 0)) {
-            throw new Error("--filter cannot be combined with --kinds, --tags, or --require-tags.");
+            (scopes.length > 0 ||
+                kinds.length > 0 ||
+                tags.length > 0 ||
+                requiredTags.length > 0)) {
+            throw new Error("--filter cannot be combined with --scopes, --kinds, --tags, or --require-tags.");
         }
         if (options.json && options.tree) {
             throw new Error("--json cannot be combined with --tree.");
@@ -33,6 +39,12 @@ export function createFindCommand() {
         const metadataCriteria = options.filter === undefined
             ? {
                 method: "filter-groups",
+                scopes: parseIdentifierOptions({
+                    optionName: "--scopes",
+                    values: scopes,
+                    declarations: configuration.scopes,
+                    declarationName: "scope",
+                }),
                 kinds: parseIdentifierOptions({
                     optionName: "--kinds",
                     values: kinds,
@@ -83,6 +95,8 @@ export function createFindCommand() {
 }
 function projectDocument(document, shownFields) {
     const projection = { path: document.path };
+    if (shownFields.has("scopes"))
+        projection.scopes = document.scopes;
     if (shownFields.has("kind"))
         projection.kind = document.kind;
     if (shownFields.has("tags"))
@@ -94,11 +108,11 @@ function projectDocument(document, shownFields) {
 }
 function parseShownFields(value) {
     if (value === undefined)
-        return new Set();
+        return new Set(SHOWN_FIELDS);
     const shownFields = new Set();
     for (const field of value.split(",")) {
-        if (field !== "kind" && field !== "tags" && field !== "description") {
-            throw new Error(`Unknown find field "${field}". Expected kind, tags, or description.`);
+        if (!isShownField(field)) {
+            throw new Error(`Unknown find field "${field}". Expected scopes, kind, tags, or description.`);
         }
         if (shownFields.has(field)) {
             throw new Error(`Duplicate find field "${field}".`);
@@ -107,8 +121,13 @@ function parseShownFields(value) {
     }
     return shownFields;
 }
+function isShownField(field) {
+    return SHOWN_FIELDS.some((shownField) => shownField === field);
+}
 function renderDocumentLine(document, shownFields, displayedPath = document.path) {
     let line = displayedPath;
+    if (shownFields.has("scopes"))
+        line += ` [${document.scopes.join(",")}]`;
     if (shownFields.has("kind"))
         line += ` [${document.kind}]`;
     if (shownFields.has("tags"))

package/dist/commands/show.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createShowCommand(): Command;

package/dist/commands/show.js

@@ -0,0 +1,97 @@
+import { Argument, Command } from "commander";
+import { loadConfiguration, } from "../configuration/index.js";
+import { throwDiagnostics } from "../diagnostics.js";
+import { countDocumentMetadataUsage, scanDocuments, } from "../documents/index.js";
+const showCategories = ["scopes", "kinds", "tags"];
+export function createShowCommand() {
+    return new Command("show")
+        .description("List declared scopes, kinds, and tags")
+        .addArgument(new Argument("[category]", "list only scopes, kinds, or tags").choices(showCategories))
+        .option("--scopes <identifiers>", "select documents matching any scope (comma-separated, repeatable)", collectScopeOptionValue)
+        .action(async (category, options) => {
+        const loadedConfiguration = await loadConfiguration(process.cwd());
+        if (loadedConfiguration.kind === "invalid") {
+            throwDiagnostics(loadedConfiguration.diagnostics);
+        }
+        const { configuration, rootPath } = loadedConfiguration;
+        const selectedScopes = parseScopeOptions({
+            values: options.scopes ?? [],
+            declarations: configuration.scopes,
+        });
+        const documentScan = await scanDocuments({ rootPath, configuration });
+        if (documentScan.kind === "invalid") {
+            throwDiagnostics(documentScan.diagnostics);
+        }
+        const categories = category ? [category] : showCategories;
+        const { kindUsageCounts, tagUsageCounts } = countDocumentMetadataUsage({
+            documents: documentScan.documents,
+            selectedScopes,
+            declaredKinds: configuration.kinds,
+            declaredTags: configuration.tags,
+        });
+        const usedOnly = selectedScopes.size > 0;
+        let output = "";
+        for (const shownCategory of categories) {
+            if (shownCategory === "scopes") {
+                output += renderDeclaredValues({
+                    heading: "Scopes",
+                    values: configuration.scopes,
+                    usageCounts: documentScan.scopeUsageCounts,
+                    usedOnly: false,
+                });
+            }
+            else if (shownCategory === "kinds") {
+                output += renderDeclaredValues({
+                    heading: "Kinds",
+                    values: configuration.kinds,
+                    usageCounts: kindUsageCounts,
+                    usedOnly,
+                });
+            }
+            else {
+                output += renderDeclaredValues({
+                    heading: "Tags",
+                    values: configuration.tags,
+                    usageCounts: tagUsageCounts,
+                    usedOnly,
+                });
+            }
+        }
+        process.stdout.write(output);
+    });
+}
+function collectScopeOptionValue(value, previous) {
+    return [...(previous ?? []), value];
+}
+function parseScopeOptions({ values, declarations, }) {
+    const scopes = new Set();
+    for (const value of values) {
+        for (const scope of value.split(",")) {
+            if (scope === "") {
+                throw new Error("--scopes contains an empty identifier.");
+            }
+            if (scopes.has(scope)) {
+                throw new Error(`--scopes contains duplicate identifier "${scope}".`);
+            }
+            if (!declarations.has(scope)) {
+                throw new Error(`--scopes contains undeclared scope "${scope}".`);
+            }
+            scopes.add(scope);
+        }
+    }
+    return scopes;
+}
+function renderDeclaredValues({ heading, values, usageCounts, usedOnly, }) {
+    let output = `${heading}:\n`;
+    const sortedValues = [...values.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    for (const [identifier, value] of sortedValues) {
+        const documentCount = usageCounts.get(identifier) ?? 0;
+        if (usedOnly && documentCount === 0)
+            continue;
+        const noun = documentCount === 1 ? "document" : "documents";
+        const description = value.description.replaceAll(/\s+/g, " ").trim();
+        output +=
+            `  ${identifier} — ${description} ` + `(${documentCount} ${noun})\n`;
+    }
+    return output;
+}

package/dist/commands/status.js

@@ -1,13 +1,11 @@
 import { Command } from "commander";
-import { loadConfiguration, } from "../configuration/index.js";
+import { loadConfiguration } from "../configuration/index.js";
 import { compareDiagnostics, throwDiagnostics } from "../diagnostics.js";
 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)")
-        .action(async (options) => {
-        const shownFields = parseShownFields(options.show);
+        .action(async () => {
         const loadedConfiguration = await loadConfiguration(process.cwd());
         if (loadedConfiguration.kind === "invalid") {
             process.stdout.write(`Root: ${loadedConfiguration.rootPath}\n` + "Status: invalid\n");
@@ -19,48 +17,13 @@ export function createStatusCommand() {
             process.stdout.write(`Root: ${rootPath}\n` + "Status: invalid\n");
             throwDiagnostics(documentScan.diagnostics.sort(compareDiagnostics));
         }
-        let output = `Root: ${rootPath}\n` +
+        const output = `Root: ${rootPath}\n` +
             "Status: valid\n" +
             `Waymark Documents: ${documentScan.documents.length}\n` +
             `Unregistered Documents: ${documentScan.unregisteredDocuments.length}\n` +
+            `Scopes: ${configuration.scopes.size}\n` +
             `Kinds: ${configuration.kinds.size}\n` +
             `Tags: ${configuration.tags.size}\n`;
-        if (shownFields.size > 0)
-            output += "\n";
-        if (shownFields.has("kind")) {
-            output += renderDeclaredValues("Kinds", configuration.kinds, documentScan.kindUsageCounts);
-        }
-        if (shownFields.has("tags")) {
-            output += renderDeclaredValues("Tags", configuration.tags, documentScan.tagUsageCounts);
-        }
         process.stdout.write(output);
     });
 }
-function parseShownFields(value) {
-    if (value === undefined)
-        return new Set();
-    const fields = value.split(",");
-    const shownFields = new Set();
-    for (const field of fields) {
-        if (field !== "kind" && field !== "tags") {
-            throw new Error(`Unknown status field "${field}". Expected kind or tags.`);
-        }
-        if (shownFields.has(field)) {
-            throw new Error(`Duplicate status field "${field}".`);
-        }
-        shownFields.add(field);
-    }
-    return shownFields;
-}
-function renderDeclaredValues(heading, values, usageCounts) {
-    let output = `${heading}:\n`;
-    const sortedValues = [...values.entries()].sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
-    for (const [identifier, value] of sortedValues) {
-        const documentCount = usageCounts.get(identifier) ?? 0;
-        const noun = documentCount === 1 ? "document" : "documents";
-        const description = value.description.replaceAll(/\s+/g, " ").trim();
-        output +=
-            `  ${identifier} — ${description} ` + `(${documentCount} ${noun})\n`;
-    }
-    return output;
-}

package/dist/configuration/initialize.js

@@ -4,6 +4,10 @@ import { isErrorWithCode } from "../filesystem.js";
 import { defaultConfigFileName, findConfigurationPath, findConfigurationPathInDirectory, } from "./load.js";
 const starterConfiguration = "# When true, document metadata must be nested under a `waymark` frontmatter key.\n" +
     "require-namespace: false\n" +
+    "# When true, every waymark document must declare at least one scope.\n" +
+    "require-scopes: false\n" +
+    "scopes:\n" +
+    "  example-scope: Explain the repository area represented by this scope\n" +
     "kinds:\n" +
     "  example-kind: Explain when agents should read this kind of document\n" +
     "tags:\n" +

package/dist/configuration/load.d.ts

@@ -11,16 +11,22 @@ export type ConfigurationDiagnostic = {
 };
 declare const configurationSchema: z.ZodPipe<z.ZodObject<{
     "require-namespace": z.ZodDefault<z.ZodBoolean>;
+    "require-scopes": z.ZodDefault<z.ZodBoolean>;
+    scopes: z.ZodPipe<z.ZodOptional<z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<Map<string, ConfigurationDeclaration>, Record<string, unknown>>>>, z.ZodTransform<Map<string, ConfigurationDeclaration>, Map<string, ConfigurationDeclaration> | undefined>>;
     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;
+    requireScopes: boolean;
+    scopes: Map<string, ConfigurationDeclaration>;
     kinds: Map<string, ConfigurationDeclaration>;
     tags: Map<string, ConfigurationDeclaration>;
     ignorePatterns: string[];
 }, {
     "require-namespace": boolean;
+    "require-scopes": boolean;
+    scopes: Map<string, ConfigurationDeclaration>;
     kinds: Map<string, ConfigurationDeclaration>;
     tags: Map<string, ConfigurationDeclaration>;
     ignore: string[];

package/dist/configuration/load.js

@@ -61,6 +61,12 @@ const configurationSchema = z
     "require-namespace": z
         .boolean({ error: "Expected a boolean." })
         .default(false),
+    "require-scopes": z
+        .boolean({ error: "Expected a boolean." })
+        .default(false),
+    scopes: configurationDeclarationsSchema
+        .optional()
+        .transform((declarations) => declarations ?? new Map()),
     kinds: configurationDeclarationsSchema,
     tags: configurationDeclarationsSchema,
     ignore: z
@@ -71,6 +77,8 @@ const configurationSchema = z
 }, { error: "Expected a mapping." })
     .transform((configuration) => ({
     requireNamespace: configuration["require-namespace"],
+    requireScopes: configuration["require-scopes"],
+    scopes: configuration.scopes,
     kinds: configuration.kinds,
     tags: configuration.tags,
     ignorePatterns: configuration.ignore,

package/dist/documents/classify.d.ts

@@ -1,5 +1,12 @@
 import { z } from "zod";
 import type { ConfigurationDeclaration } from "../configuration/index.js";
+type DocumentRegistrationPolicy = {
+    requireNamespace: boolean;
+    requireScopes: boolean;
+    declaredScopes: Map<string, ConfigurationDeclaration>;
+    declaredKinds: Map<string, ConfigurationDeclaration>;
+    declaredTags: Map<string, ConfigurationDeclaration>;
+};
 type ClassifiedDocument = z.infer<ReturnType<typeof createDocumentSchema>> & {
     body: string;
 };
@@ -17,19 +24,20 @@ type DocumentClassification = {
     kind: "registered";
     document: ClassifiedDocument;
 };
-export declare function classifyDocument({ source, requireNamespace, declaredKinds, declaredTags, path, }: {
+export declare function classifyDocument({ source, registrationPolicy, path, }: {
     source: string;
-    requireNamespace: boolean;
-    declaredKinds: Map<string, ConfigurationDeclaration>;
-    declaredTags: Map<string, ConfigurationDeclaration>;
+    registrationPolicy: DocumentRegistrationPolicy;
     path: string;
 }): DocumentClassification;
-declare function createDocumentSchema({ declaredKinds, declaredTags, }: {
+declare function createDocumentSchema({ requireScopes, declaredScopes, declaredKinds, declaredTags, }: {
+    requireScopes: boolean;
+    declaredScopes: Map<string, ConfigurationDeclaration>;
     declaredKinds: Map<string, ConfigurationDeclaration>;
     declaredTags: Map<string, ConfigurationDeclaration>;
 }): z.ZodObject<{
     kind: z.ZodString;
     description: z.ZodString;
+    scopes: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodUnknown>>, z.ZodTransform<string[], unknown[]>>;
     tags: z.ZodPipe<z.ZodDefault<z.ZodArray<z.ZodUnknown>>, z.ZodTransform<string[], unknown[]>>;
 }, z.core.$strict>;
 export {};

package/dist/documents/classify.js

@@ -1,7 +1,7 @@
 import { parse } from "yaml";
 import { z } from "zod";
 const rawFrontmatterSchema = z.record(z.string(), z.unknown());
-export function classifyDocument({ source, requireNamespace, declaredKinds, declaredTags, path, }) {
+export function classifyDocument({ source, registrationPolicy, path, }) {
     const frontmatter = readFrontmatter(source);
     if (frontmatter.kind === "malformed") {
         return {
@@ -24,9 +24,7 @@ export function classifyDocument({ source, requireNamespace, declaredKinds, decl
     return validateRegistration({
         frontmatter: frontmatterResult.data,
         body: frontmatter.body,
-        requireNamespace,
-        declaredKinds,
-        declaredTags,
+        registrationPolicy,
         path,
     });
 }
@@ -48,7 +46,8 @@ function readFrontmatter(source) {
         return { kind: "malformed" };
     }
 }
-function validateRegistration({ frontmatter, body, requireNamespace, declaredKinds, declaredTags, path, }) {
+function validateRegistration({ frontmatter, body, registrationPolicy, path, }) {
+    const { requireNamespace, requireScopes, declaredScopes, declaredKinds, declaredTags, } = registrationPolicy;
     const hasNamespace = Object.hasOwn(frontmatter, "waymark");
     const hasRecognizedFlatMetadata = Object.hasOwn(frontmatter, "kind") &&
         Object.hasOwn(frontmatter, "description");
@@ -75,10 +74,13 @@ function validateRegistration({ frontmatter, body, requireNamespace, declaredKin
         : {
             kind: frontmatter.kind,
             description: frontmatter.description,
+            scopes: frontmatter.scopes,
             tags: frontmatter.tags,
         };
     const fieldPrefix = namespaced ? "waymark." : "";
     const metadataResult = createDocumentSchema({
+        requireScopes,
+        declaredScopes,
         declaredKinds,
         declaredTags,
     }).safeParse(value);
@@ -98,7 +100,7 @@ function validateRegistration({ frontmatter, body, requireNamespace, declaredKin
         document: { ...metadataResult.data, body },
     };
 }
-function createDocumentSchema({ declaredKinds, declaredTags, }) {
+function createDocumentSchema({ requireScopes, declaredScopes, declaredKinds, declaredTags, }) {
     return z.strictObject({
         kind: z
             .string({
@@ -126,6 +128,42 @@ function createDocumentSchema({ declaredKinds, declaredTags, }) {
             .refine((description) => description.trim() !== "", {
             error: "Document Description must be a non-empty string.",
         }),
+        scopes: z
+            .array(z.unknown(), { error: "Expected a YAML sequence of scopes." })
+            .default([])
+            .superRefine((scopes, context) => {
+            if (requireScopes && scopes.length === 0) {
+                context.addIssue({
+                    code: "custom",
+                    message: "At least one scope is required.",
+                });
+            }
+            const seenScopes = new Set();
+            for (const scope of scopes) {
+                if (typeof scope !== "string" || scope.trim() === "") {
+                    context.addIssue({
+                        code: "custom",
+                        message: "Every scope must be a non-empty string.",
+                    });
+                    continue;
+                }
+                if (seenScopes.has(scope)) {
+                    context.addIssue({
+                        code: "custom",
+                        message: `Duplicate scope "${scope}".`,
+                    });
+                    continue;
+                }
+                seenScopes.add(scope);
+                if (!declaredScopes.has(scope)) {
+                    context.addIssue({
+                        code: "custom",
+                        message: `Undeclared scope "${scope}".`,
+                    });
+                }
+            }
+        })
+            .transform((scopes) => scopes.filter((scope) => typeof scope === "string")),
         tags: z
             .array(z.unknown(), { error: "Expected a YAML sequence of tags." })
             .default([])

package/dist/documents/filter.d.ts

@@ -1,11 +1,13 @@
 import type { Configuration } from "../configuration/index.js";
 import type { WaymarkDocument } from "./scan.js";
 type FilterableDocument = {
+    scopes: string[];
     kind: string;
     tags: string[];
 };
 type MetadataCriteria = {
     method: "filter-groups";
+    scopes: Set<string>;
     kinds: Set<string>;
     tags: Set<string>;
     requiredTags: Set<string>;
@@ -22,8 +24,9 @@ export declare function filterDocuments({ documents, configuration, criteria, }:
     configuration: Configuration;
     criteria: DocumentCriteria;
 }): WaymarkDocument[];
-export declare function parseMetadataFilter({ expression, declaredKinds, declaredTags, }: {
+export declare function parseMetadataFilter({ expression, declaredScopes, declaredKinds, declaredTags, }: {
     expression: string;
+    declaredScopes: Set<string>;
     declaredKinds: Set<string>;
     declaredTags: Set<string>;
 }): (document: FilterableDocument) => boolean;

package/dist/documents/filter.js

@@ -3,10 +3,13 @@ export function filterDocuments({ documents, configuration, criteria, }) {
     const matchesMetadata = metadata.method === "filter-expression"
         ? parseMetadataFilter({
             expression: metadata.expression,
+            declaredScopes: new Set(configuration.scopes.keys()),
             declaredKinds: new Set(configuration.kinds.keys()),
             declaredTags: new Set(configuration.tags.keys()),
         })
-        : (document) => (metadata.kinds.size === 0 || metadata.kinds.has(document.kind)) &&
+        : (document) => (metadata.scopes.size === 0 ||
+            document.scopes.some((scope) => metadata.scopes.has(scope))) &&
+            (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));
@@ -17,8 +20,8 @@ export function filterDocuments({ documents, configuration, criteria, }) {
             document.body.toLowerCase().includes(normalizedQuery)))
         .sort((left, right) => compareText(left.path, right.path));
 }
-export function parseMetadataFilter({ expression, declaredKinds, declaredTags, }) {
-    const tokens = tokenize(expression, declaredKinds, declaredTags);
+export function parseMetadataFilter({ expression, declaredScopes, declaredKinds, declaredTags, }) {
+    const tokens = tokenize(expression, declaredScopes, declaredKinds, declaredTags);
     let nextTokenIndex = 0;
     function peek() {
         return tokens[nextTokenIndex];
@@ -26,14 +29,16 @@ export function parseMetadataFilter({ expression, declaredKinds, declaredTags, }
     function consume() {
         const token = tokens[nextTokenIndex];
         if (!token) {
-            throw syntaxError(expression.length, 'Expected a kind: or tag: predicate, or "(".');
+            throw syntaxError(expression.length, 'Expected a scope:, kind:, or tag: predicate, or "(".');
         }
         nextTokenIndex += 1;
         return token;
     }
     function parsePrimary() {
         const token = consume();
-        if (token.type === "kind" || token.type === "tag") {
+        if (token.type === "scope" ||
+            token.type === "kind" ||
+            token.type === "tag") {
             return {
                 type: token.type,
                 identifier: token.identifier,
@@ -48,7 +53,7 @@ export function parseMetadataFilter({ expression, declaredKinds, declaredTags, }
             consume();
             return expressionNode;
         }
-        throw syntaxError(token.position, 'Expected a kind: or tag: predicate, or "(".');
+        throw syntaxError(token.position, 'Expected a scope:, kind:, or tag: predicate, or "(".');
     }
     function parseNot() {
         if (peek()?.type !== "not")
@@ -78,7 +83,8 @@ export function parseMetadataFilter({ expression, declaredKinds, declaredTags, }
     const root = parseOr();
     const remainingToken = peek();
     if (remainingToken) {
-        const message = remainingToken.type === "kind" ||
+        const message = remainingToken.type === "scope" ||
+            remainingToken.type === "kind" ||
             remainingToken.type === "tag" ||
             remainingToken.type === "not" ||
             remainingToken.type === "left-parenthesis"
@@ -88,7 +94,7 @@ export function parseMetadataFilter({ expression, declaredKinds, declaredTags, }
     }
     return (document) => evaluate(root, document);
 }
-function tokenize(expression, declaredKinds, declaredTags) {
+function tokenize(expression, declaredScopes, declaredKinds, declaredTags) {
     const tokens = [];
     let position = 0;
     while (position < expression.length) {
@@ -125,17 +131,23 @@ function tokenize(expression, declaredKinds, declaredTags) {
             tokens.push({ type: "or", position: tokenPosition });
             continue;
         }
-        const predicate = /^(kind|tag):([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(value);
+        const predicate = /^(scope|kind|tag):([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(value);
         if (!predicate) {
-            throw syntaxError(tokenPosition, `Unsupported token "${value}". Expected kind:<identifier>, tag:<identifier>, NOT, AND, OR, or parentheses.`);
+            throw syntaxError(tokenPosition, `Unsupported token "${value}". Expected scope:<identifier>, kind:<identifier>, tag:<identifier>, NOT, AND, OR, or parentheses.`);
         }
         const [, predicateType, identifier] = predicate;
-        if (predicateType !== "kind" && predicateType !== "tag") {
+        if (predicateType !== "scope" &&
+            predicateType !== "kind" &&
+            predicateType !== "tag") {
             throw new Error("Metadata Filter parser invariant failed.");
         }
         if (!identifier)
             throw new Error("Metadata Filter parser invariant failed.");
-        const declarations = predicateType === "kind" ? declaredKinds : declaredTags;
+        const declarations = predicateType === "scope"
+            ? declaredScopes
+            : predicateType === "kind"
+                ? declaredKinds
+                : declaredTags;
         if (!declarations.has(identifier)) {
             throw syntaxError(tokenPosition, `Undeclared ${predicateType} "${identifier}".`);
         }
@@ -149,6 +161,8 @@ function tokenize(expression, declaredKinds, declaredTags) {
 }
 function evaluate(node, document) {
     switch (node.type) {
+        case "scope":
+            return document.scopes.includes(node.identifier);
         case "kind":
             return document.kind === node.identifier;
         case "tag":

package/dist/documents/index.d.ts

@@ -1,3 +1,4 @@
 export { filterDocuments } from "./filter.js";
 export { scanDocuments } from "./scan.js";
+export { countDocumentMetadataUsage } from "./usage-counts.js";
 export type { DocumentScanDiagnostic, DocumentScanResult, WaymarkDocument, } from "./scan.js";

package/dist/documents/index.js

@@ -1,2 +1,3 @@
 export { filterDocuments } from "./filter.js";
 export { scanDocuments } from "./scan.js";
+export { countDocumentMetadataUsage } from "./usage-counts.js";

package/dist/documents/scan.d.ts

@@ -3,6 +3,7 @@ export type WaymarkDocument = {
     path: string;
     kind: string;
     description: string;
+    scopes: string[];
     tags: string[];
     body: string;
 };
@@ -19,6 +20,7 @@ export type DocumentScanResult = {
     kind: "valid";
     documents: WaymarkDocument[];
     unregisteredDocuments: string[];
+    scopeUsageCounts: Map<string, number>;
     kindUsageCounts: Map<string, number>;
     tagUsageCounts: Map<string, number>;
 } | {

package/dist/documents/scan.js

@@ -4,6 +4,7 @@ import { convertPathToPattern, globby } from "globby";
 import { allowedConfigFileNames, } from "../configuration/index.js";
 import { isErrorWithCode } from "../filesystem.js";
 import { classifyDocument } from "./classify.js";
+import { createUsageCounts, incrementUsageCount } from "./usage-counts.js";
 export async function scanDocuments({ rootPath, configuration, scope, }) {
     const { rootPath: scanRootPath, scope: resolvedScope } = await resolveDocumentScanScope({ rootPath, scope });
     const discoveredPaths = await globby(createCandidatePatterns(resolvedScope), {
@@ -16,10 +17,18 @@ export async function scanDocuments({ rootPath, configuration, scope, }) {
         extglob: false,
     });
     const documents = [];
+    const scopeUsageCounts = createUsageCounts(configuration.scopes);
     const kindUsageCounts = createUsageCounts(configuration.kinds);
     const tagUsageCounts = createUsageCounts(configuration.tags);
     const diagnostics = [];
     const unregisteredDocuments = [];
+    const registrationPolicy = {
+        requireNamespace: configuration.requireNamespace,
+        requireScopes: configuration.requireScopes,
+        declaredScopes: configuration.scopes,
+        declaredKinds: configuration.kinds,
+        declaredTags: configuration.tags,
+    };
     for (const path of discoveredPaths.sort(compareText)) {
         if (allowedConfigFileNames.some((fileName) => fileName === path))
             continue;
@@ -34,9 +43,7 @@ export async function scanDocuments({ rootPath, configuration, scope, }) {
         const source = await readFile(join(scanRootPath, path), "utf8");
         const classification = classifyDocument({
             source,
-            requireNamespace: configuration.requireNamespace,
-            declaredKinds: configuration.kinds,
-            declaredTags: configuration.tags,
+            registrationPolicy,
             path,
         });
         if (classification.kind === "unregistered") {
@@ -49,6 +56,9 @@ export async function scanDocuments({ rootPath, configuration, scope, }) {
         }
         const document = { path, ...classification.document };
         documents.push(document);
+        for (const scope of document.scopes) {
+            incrementUsageCount(scopeUsageCounts, scope);
+        }
         incrementUsageCount(kindUsageCounts, document.kind);
         for (const tag of document.tags)
             incrementUsageCount(tagUsageCounts, tag);
@@ -63,6 +73,7 @@ export async function scanDocuments({ rootPath, configuration, scope, }) {
         kind: "valid",
         documents,
         unregisteredDocuments,
+        scopeUsageCounts,
         kindUsageCounts,
         tagUsageCounts,
     };
@@ -108,7 +119,9 @@ function createCandidatePatterns(scope) {
             ...allowedConfigFileNames.map((fileName) => `**/${fileName}`),
         ];
     }
-    const directoryPattern = convertPathToPattern(scope.relativeDirectoryPath);
+    const directoryPattern = scope.relativeDirectoryPath === ""
+        ? ""
+        : convertPathToPattern(scope.relativeDirectoryPath);
     const directoryPrefix = directoryPattern === "" ? "" : `${directoryPattern}/`;
     const candidatePrefix = scope.recursive
         ? `${directoryPrefix}**/`
@@ -119,15 +132,6 @@ function createCandidatePatterns(scope) {
         ...allowedConfigFileNames.map((fileName) => `${candidatePrefix}${fileName}`),
     ];
 }
-function createUsageCounts(declarations) {
-    return new Map([...declarations.keys()].map((identifier) => [identifier, 0]));
-}
-function incrementUsageCount(usageCounts, identifier) {
-    const currentCount = usageCounts.get(identifier);
-    if (currentCount !== undefined) {
-        usageCounts.set(identifier, currentCount + 1);
-    }
-}
 function compareDiagnostics(left, right) {
     return (compareText(left.path, right.path) ||
         compareText(left.field, right.field) ||

package/dist/documents/usage-counts.d.ts

@@ -0,0 +1,18 @@
+type DocumentMetadata = {
+    scopes: string[];
+    kind: string;
+    tags: string[];
+};
+type DocumentMetadataUsageCounts = {
+    kindUsageCounts: Map<string, number>;
+    tagUsageCounts: Map<string, number>;
+};
+export declare function countDocumentMetadataUsage({ documents, selectedScopes, declaredKinds, declaredTags, }: {
+    documents: DocumentMetadata[];
+    selectedScopes: Set<string>;
+    declaredKinds: Map<string, unknown>;
+    declaredTags: Map<string, unknown>;
+}): DocumentMetadataUsageCounts;
+export declare function createUsageCounts(declarations: Map<string, unknown>): Map<string, number>;
+export declare function incrementUsageCount(usageCounts: Map<string, number>, identifier: string): void;
+export {};

package/dist/documents/usage-counts.js

@@ -0,0 +1,24 @@
+export function countDocumentMetadataUsage({ documents, selectedScopes, declaredKinds, declaredTags, }) {
+    const kindUsageCounts = createUsageCounts(declaredKinds);
+    const tagUsageCounts = createUsageCounts(declaredTags);
+    for (const document of documents) {
+        if (selectedScopes.size > 0 &&
+            !document.scopes.some((scope) => selectedScopes.has(scope))) {
+            continue;
+        }
+        incrementUsageCount(kindUsageCounts, document.kind);
+        for (const tag of document.tags) {
+            incrementUsageCount(tagUsageCounts, tag);
+        }
+    }
+    return { kindUsageCounts, tagUsageCounts };
+}
+export function createUsageCounts(declarations) {
+    return new Map([...declarations.keys()].map((identifier) => [identifier, 0]));
+}
+export function incrementUsageCount(usageCounts, identifier) {
+    const currentCount = usageCounts.get(identifier);
+    if (currentCount !== undefined) {
+        usageCounts.set(identifier, currentCount + 1);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waymark-docs",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Agent-focused CLI that surfaces repository documentation to improve coding-agent performance.",
   "keywords": [
     "ai-agents",