From dbe93fa4a042d43b49364cdd126322604c8da5e2 Mon Sep 17 00:00:00 2001
From: Abe Gong <abe@Abes-MacBook-Air.local>
Date: Thu, 25 Jun 2026 13:55:34 -0600
Subject: [PATCH 1/6] Document release install and agent bootstrap

---
 docs/content/getting-started.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
index fe011a3..49ffcfe 100644
--- a/docs/content/getting-started.md
+++ b/docs/content/getting-started.md
@@ -59,13 +59,13 @@ katalyst check
 
 - `.katalyst/config.yaml`, commented project settings
 - `.katalyst/schemas/`, one schema per file (empty to start)
-- `.katalyst/bases/local.yaml`, the default base (the local
+- `.katalyst/storage/local.yaml`, the default storage instance (the local
   filesystem), where you declare collections
 
 It writes no example content. Add a schema under `.katalyst/schemas/` and
-declare a collection inside `.katalyst/bases/local.yaml`, then run
+declare a collection inside `.katalyst/storage/local.yaml`, then run
 `katalyst check`.
 
 Next:
-- [Configs]({{< relref "reference/configs/_index.md" >}})
+- [Configuration]({{< relref "reference/configuration.md" >}})
 - [Check types reference]({{< relref "reference/check-types/_index.md" >}})

From 8e5a175d6f691cb3c4db1f043fce624f55106ffc Mon Sep 17 00:00:00 2001
From: Abe Gong <abe@Abes-MacBook-Air.local>
Date: Mon, 29 Jun 2026 13:29:11 -0600
Subject: [PATCH 2/6] Add filesystem checks specification

---
 product/specs/filesystem-checks-spec.md | 476 ++++++++++++++++++++++++
 1 file changed, 476 insertions(+)
 create mode 100644 product/specs/filesystem-checks-spec.md

diff --git a/product/specs/filesystem-checks-spec.md b/product/specs/filesystem-checks-spec.md
new file mode 100644
index 0000000..bf452a3
--- /dev/null
+++ b/product/specs/filesystem-checks-spec.md
@@ -0,0 +1,476 @@
+# Spec - filesystem checks and collection checks
+
+> **Status: planning.** Adds filesystem-attached checks that run before
+> collections exist, while keeping collection-attached checks and sharing check
+> implementations across both attachment points.
+
+## Overview
+
+Katalyst checks are attached to collections today. That makes schemas, variants,
+and item-level rules coherent, but it prevents basic filesystem policy from
+running until the user has defined collections. Introduce a second attachment
+point, **FilesystemChecks**, for path-selected files under filesystem storage
+instances. Keep **CollectionChecks** as the checks attached to collection
+definitions.
+
+## Value
+
+Users can enforce early, concrete rules while they are still profiling a
+project:
+
+- Markdown filenames use kebab-case.
+- Markdown content does not live deeper than N directories.
+- A subtree contains only allowed extensions.
+- Every populated directory has an index file.
+- Asset references point at existing files.
+
+The same check type works under a collection and under a filesystem scope when
+both contexts provide the data it needs. A rule does not get a duplicate
+implementation or a duplicate docs page just because it has two attachment
+points.
+
+## Current State
+
+`cmd/check.go` resolves selectors through `project.Resolve`. Selectors name
+collections or collection items. With no selectors, Katalyst expands every
+configured collection. A freshly initialized project has no collections, so
+`katalyst check` succeeds because there is nothing to validate.
+
+`internal/storage/collection/parse.go` gives collections one check attachment
+site: `schema:` plus `checks:`. The parser folds `schema:` into a leading
+`object` check and parses each configured check through the registry. It rejects
+collections with no schema, checks, or variants.
+
+`cmd/engine.go` builds runnable per-item checks from a collection's configured
+checks and variants. It also builds collection-scoped checks in a second pass.
+The runtime distinction already exists:
+
+- `checks.Check` runs once per item with `checks.Context`.
+- `checks.CollectionCheck` runs once per collection with
+  `checks.CollectionContext`.
+
+`internal/checks/registry.go` documents check types with one `Descriptor`. The
+descriptor has `Family`, which says what data the check reads, and `Scope`,
+which currently says whether the check is collection-scoped. It does not say
+where the check is attachable.
+
+The current terms collide. A "filesystem check" can mean either:
+
+- a check type in the `fileSystem` family, such as
+  `filesystem_name_case`; or
+- a future check instance attached to the filesystem instead of a collection.
+
+This spec separates those axes.
+
+## Design
+
+### Attachment Targets
+
+Add an attachment-target axis to check descriptors:
+
+```go
+type Descriptor struct {
+    // existing fields...
+    Targets []string // "collection", "filesystem"
+}
+```
+
+`Family` keeps its current meaning: the source data the check reads.
+`Targets` says where a check instance may be configured.
+
+During migration, an empty `Targets` means `["collection"]`. That keeps every
+existing check valid until each descriptor opts into filesystem attachment.
+
+Use these concepts in product language:
+
+- **CollectionCheck:** a check instance attached to a collection definition.
+- **FilesystemCheck:** a check instance attached to a filesystem scope.
+- **FileCheck:** a runtime check that runs once per file.
+- **FileSetCheck:** a runtime check that runs once per selected file set.
+
+The last two replace the overloaded internal names over time. Today's
+`checks.Check` is a FileCheck. Today's `checks.CollectionCheck` is a
+FileSetCheck.
+
+### Config Shape
+
+Keep collection checks where they are:
+
+```yaml
+collections:
+  posts:
+    path: content/posts
+    pattern: "*.md"
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+      - kind: markdown_requires_h1
+```
+
+Do not rename collection `checks:` to `collectionChecks:`. Inside a collection,
+the attachment target is already clear. A rename adds migration cost without
+making the config easier to write.
+
+Add `filesystemChecks` to filesystem storage instances:
+
+```yaml
+# .katalyst/storage/local.yaml
+type: filesystem
+root: .
+
+filesystemChecks:
+  - name: docs
+    path: docs/content
+    include: ["**/*.md"]
+    exclude: ["**/_generated/**"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+      - kind: filesystem_path_depth
+        max: 4
+      - kind: filesystem_index_file_required
+        name: _index.md
+
+collections:
+  pages:
+    path: docs/content
+    pattern: "**/*.md"
+    schema: page
+```
+
+Each `filesystemChecks` entry defines a filesystem scope:
+
+| Key | Required | Default | Meaning |
+|---|---|---|---|
+| `name` | no | `path` | Diagnostic label and future selector handle. |
+| `path` | no | `.` | Scope root, relative to the storage instance root. |
+| `include` | yes | - | Glob patterns relative to `path`. |
+| `exclude` | no | `[]` | Glob patterns removed from the included set. |
+| `parseFailures` | no | `error` | Severity for document parse failures: `error` or `warning`. |
+| `checks` | yes | - | Check instances to run over selected files. |
+
+Names are optional. A named scope gives diagnostics and future selective
+execution a stable handle. An unnamed scope uses its `path` as its diagnostic
+label.
+
+`include` is required in the first cut. Filesystem scopes serve both path-only
+checks and document-aware checks, and a default would surprise one of those
+cases. A later release can add a default after real configs show whether
+filesystem scopes are mostly broad path scans or Markdown-focused checks.
+
+`parseFailures` applies only when at least one check in the scope needs
+document data. The default is `error`, matching collection checks and CI
+expectations. Set it to `warning` for onboarding a messy tree while still
+surfacing skipped document-aware checks.
+
+The same check type can appear in both attachment sites when its descriptor
+supports both targets:
+
+```yaml
+type: filesystem
+root: .
+
+filesystemChecks:
+  - name: allMarkdown
+    path: .
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+
+collections:
+  posts:
+    path: content/posts
+    pattern: "*.md"
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+      - kind: markdown_requires_h1
+```
+
+`filesystemChecks` is valid only on `type: filesystem` storage instances.
+SQLite storage instances reject it.
+
+### Why Storage-Level Config
+
+Filesystem checks attach to filesystem storage because storage owns the root
+path. This avoids a second project-level root and keeps path resolution beside
+`collections:`.
+
+The alternative is project-level `filesystemChecks` in `.katalyst/config.yaml`:
+
+```yaml
+filesystemChecks:
+  - name: docs
+    root: .
+    path: docs/content
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+```
+
+That shape is visible, but it duplicates storage root semantics. It also raises
+unclear questions for SQLite-backed projects. Storage-level config fits the
+existing model: a filesystem storage instance declares both its domain mapping
+and its raw filesystem policy.
+
+### Shared Runtime Contexts
+
+Avoid duplicate implementations by normalizing both attachment points into the
+same contexts.
+
+Rename or adapt `checks.Context` into a file-oriented context:
+
+```go
+type FileContext struct {
+    FilePath string
+    Root     string
+    Doc      *markdownbodytext.Document
+    Meta     map[string]any
+}
+```
+
+For collection checks:
+
+- `FilePath` is the item path.
+- `Root` is the collection directory.
+- `Doc` and `Meta` come from `Project.ReadItem`.
+
+For filesystem checks:
+
+- `FilePath` is the selected file path.
+- `Root` is the filesystem check scope root.
+- `Doc` and `Meta` are populated only when a check declares that it needs
+  document data.
+
+Unify collection-scoped checks and filesystem-scoped checks around a file-set
+context:
+
+```go
+type FileSetContext struct {
+    Root      string
+    Files     []FileContext
+    Unmatched []string
+    Include   []string
+    Exclude   []string
+}
+```
+
+Then existing set-level checks become target-independent:
+
+- `filesystem_unique_filename` groups `ctx.Files` by basename.
+- `filesystem_index_file_required` groups `ctx.Files` by directory.
+- `filesystem_unique_field` groups `ctx.Files` by metadata field.
+
+This runtime shape also fixes the naming collision. Internal
+`CollectionCheck` means "set-level check" today. Product language needs
+"CollectionCheck" to mean "attached to a collection." Rename the internal
+interface after the filesystem runner lands.
+
+`Files` contains the files selected by the scope after `include` and `exclude`.
+`Unmatched` contains regular files under the scope root that match neither
+`include` nor `exclude`. Most checks ignore `Unmatched`; the
+`filesystem_unmatched_files` check uses it to enforce raw subtree coverage.
+
+### Document Access
+
+FilesystemChecks are document-aware, but document parsing is lazy.
+
+Path-only checks do not open files. Checks that need metadata or markdown body
+content declare that need in the registry. The filesystem runner parses only
+when at least one check in the scope needs document data.
+
+Document parse failures use the filesystem scope's `parseFailures` severity.
+With the default:
+
+```yaml
+filesystemChecks:
+  - name: posts
+    path: content/posts
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_matches_field
+        field: slug
+```
+
+an invalid document fails the run:
+
+```text
+filesystem posts: content/posts/broken.md: /: cannot parse document: invalid frontmatter
+```
+
+With `parseFailures: warning`:
+
+```yaml
+filesystemChecks:
+  - name: posts
+    path: content/posts
+    include: ["**/*.md"]
+    parseFailures: warning
+    checks:
+      - kind: filesystem_name_matches_field
+        field: slug
+```
+
+the same parse failure is advisory:
+
+```text
+filesystem posts: content/posts/broken.md: warning: /: cannot parse document: invalid frontmatter; skipped document-aware checks
+```
+
+The runner always reports parse failures. A passing run proves that every
+selected file needed by a document-aware check was inspected.
+
+This lets almost every current filesystem-related check run under both targets:
+
+| Check type | CollectionChecks | FilesystemChecks |
+|---|---:|---:|
+| `filesystem_extension_in` | yes | yes |
+| `filesystem_parent_dir_in` | yes | yes |
+| `filesystem_name_case` | yes | yes |
+| `filesystem_name_affix` | yes | yes |
+| `filesystem_path_charset` | yes | yes |
+| `filesystem_name_regex` | yes | yes |
+| `filesystem_name_length` | yes | yes |
+| `filesystem_path_depth` | yes | yes |
+| `filesystem_unique_filename` | yes | yes |
+| `filesystem_index_file_required` | yes | yes |
+| `filesystem_name_matches_field` | yes | yes, with metadata |
+| `filesystem_parent_dir_matches_field` | yes | yes, with metadata |
+| `filesystem_referenced_files_exist` | yes | yes, with metadata |
+| `filesystem_unique_field` | yes | yes, with metadata |
+
+`filesystem_unique_field` is in the `structuredObject` family today despite its
+historical `filesystem_` prefix. Keep the kind for compatibility. A future
+rename can add an alias.
+
+### Filesystem Unmatched Files
+
+Add a new filesystem-only FileSetCheck:
+
+```yaml
+filesystemChecks:
+  - name: docsCoverage
+    path: docs/content
+    include: ["**/*.md"]
+    exclude: ["assets/**", "_generated/**"]
+    checks:
+      - kind: filesystem_unmatched_files
+```
+
+`filesystem_unmatched_files` enforces scope coverage. Every regular file under
+the scope root must either match `include` and enter the checked file set, or
+match `exclude` and be intentionally ignored. A file that matches neither is an
+unmatched file.
+
+Example diagnostic:
+
+```text
+filesystem docsCoverage: docs/content/raw.txt: unmatched file (does not match include ["**/*.md"] or exclude ["assets/**", "_generated/**"])
+```
+
+This check is separate from collection unmatched-file detection. Collection
+unmatched detection remains the existing invariant: files inside a collection
+directory must match the collection's `pattern`. The new check applies before
+collections exist and only runs when the user configures it.
+
+### Command Behavior
+
+`katalyst check` with no selectors runs:
+
+1. all configured FilesystemChecks
+2. all configured CollectionChecks
+
+Existing collection selectors stay collection-only:
+
+```text
+katalyst check pages
+katalyst check pages/home
+```
+
+Those commands do not run unrelated filesystem scopes. Selective filesystem
+execution can come later through named scopes:
+
+```text
+katalyst check --filesystem docs
+```
+
+Do not add filesystem selectors in the first implementation unless the CLI work
+needs them. Running all filesystem scopes under the empty selector covers the
+main onboarding and CI cases.
+
+### Diagnostics
+
+Diagnostics name the attachment target:
+
+```text
+filesystem docs: docs/content/Old Note.md: /path: filename is not kebab-case
+```
+
+When a scope has no `name`, use its path:
+
+```text
+filesystem docs/content: docs/content/Old Note.md: /path: filename is not kebab-case
+```
+
+Collection diagnostics keep the existing item path format unless the new target
+label is needed to disambiguate output when both attachment types run.
+
+### Migration
+
+Existing configs keep working:
+
+- Collection `checks:` keeps its meaning.
+- Check type `kind` names keep their meaning.
+- Existing collection-scoped runtime interfaces can remain during the first
+  implementation.
+
+Implementation is additive:
+
+1. Add descriptor target metadata, defaulting to `collection`.
+2. Add file and file-set runtime contexts without changing behavior.
+3. Add `filesystemChecks` parsing to filesystem storage instances.
+4. Run path-only FilesystemChecks.
+5. Add lazy document parsing and opt metadata-aware check types into the
+   filesystem target.
+6. Rename internal set-level interfaces away from `CollectionCheck`.
+
+## Open Questions
+
+_None._
+
+## Documentation Updates
+
+- `docs/content/deep-dives/checks.md`: split data family, library,
+  attachment target, and runtime granularity.
+- `docs/content/reference/configuration.md`: document storage-level
+  `filesystemChecks`.
+- `docs/content/reference/glossary.md`: add CollectionCheck, FilesystemCheck,
+  FileCheck, FileSetCheck, and attachment target. Update Check instance and
+  Collection-scoped check.
+- `docs/content/how-to/configure-rules.md`: add a pre-collection filesystem
+  check workflow.
+- Generated check-type reference: render supported targets and file vs.
+  file-set granularity from descriptors. Run `make docs-gen`.
+- `internal/checks/AGENTS.md`: document descriptor target metadata and the
+  runtime naming distinction.
+- `internal/storage/collection/AGENTS.md`: document that collection `checks:`
+  remain collection-attached and filesystem checks live on filesystem storage
+  instances.
+- `.cursor/skills/add-katalyst-check-type/SKILL.md`: update the checklist so a
+  new check type declares supported attachment targets.
+
+## Rejected Alternatives
+
+- **Rename collection `checks:` to `collectionChecks:`.** Rejected because the
+  collection block already supplies the target. The rename creates migration
+  work without changing behavior.
+- **Put `filesystemChecks` in `.katalyst/config.yaml`.** Rejected because it
+  duplicates storage roots and makes filesystem policy independent of the
+  storage instance that owns path resolution.
+- **Create separate check kinds for filesystem and collection attachment.**
+  Rejected because it splits docs and implementations for the same rule.
+- **Infer collections to run filesystem rules.** Rejected because a filesystem
+  scope has no item identity, schema, variants, or selector namespace. It is not
+  a collection.

From da2d1c8e331b10f7d2076af5c791988d5cb4439b Mon Sep 17 00:00:00 2001
From: Abe Gong <abe@Abes-MacBook-Air.local>
Date: Mon, 29 Jun 2026 13:34:46 -0600
Subject: [PATCH 3/6] Add filesystem checks implementation plan

---
 product/specs/filesystem-checks-plan.md | 353 ++++++++++++++++++++++++
 1 file changed, 353 insertions(+)
 create mode 100644 product/specs/filesystem-checks-plan.md

diff --git a/product/specs/filesystem-checks-plan.md b/product/specs/filesystem-checks-plan.md
new file mode 100644
index 0000000..aeeb661
--- /dev/null
+++ b/product/specs/filesystem-checks-plan.md
@@ -0,0 +1,353 @@
+# Plan - filesystem checks and collection checks
+> Spec: [Filesystem checks and collection checks](./filesystem-checks-spec.md)
+> **Status: planning.**
+
+## Current State
+
+- `cmd/check.go` runs collection-attached checks only. With no selectors it
+  resolves every collection through `project.Resolve`, runs per-item checks,
+  scans wholesale-selected collections for unmatched files, then runs
+  collection-scoped checks.
+- `cmd/engine.go` builds checks from a `project.Collection`. It owns schema
+  compilation, library availability checks, variant routing, per-item builders,
+  and collection-scoped builders.
+- `internal/project/loader.go` loads `.katalyst/bases/<name>.yaml` files into
+  `BaseInstance` values. Legacy `.katalyst/storage/` remains readable, but the
+  current code and tests use bases.
+- `internal/storage/collection/parse.go` parses collection config. It owns
+  `RawCheck`, folds `schema:` into an `object` check, parses check args through
+  `checks.Parse`, and rejects SQLite collections that configure file-system
+  family checks.
+- `internal/checks/registry.go` records each check type's `Descriptor`, parser,
+  per-item builder, and collection-scoped builder. `Descriptor.Scope` names
+  collection-scoped runtime behavior. It has no attachment-target metadata.
+- `internal/checks/checks.go` defines per-item `Context` and `Check`.
+  `internal/checks/collection.go` defines `CollectionContext` and
+  `CollectionCheck`. Those names mix runtime granularity with the future
+  product term CollectionCheck.
+- `internal/storage/collection/filesystem/collection.go` already contains the
+  filesystem traversal pieces needed by filesystem scopes: doublestar matching,
+  sorted item discovery, and unmatched-file walking.
+- `cmd/check_types.go` and `cmd/gendocs/main.go` render check descriptors for
+  CLI and generated docs. They currently render family, scope, severity, fields,
+  and config examples.
+- `cmd/check_test.go`, `internal/project/loader_test.go`,
+  `internal/checks/registry_test.go`, and check-family tests are the main test
+  homes for this change.
+
+## Sequencing
+
+| Phase | Focus | Scope |
+|---|---|---|
+| 1 | Failing contracts | loader tests, check CLI tests, registry tests, snapshots |
+| 2 | Shared check metadata and config parsing | descriptor targets, document needs, reusable raw check parsing |
+| 3 | Filesystem scope config and expansion | base-level `filesystemChecks`, include/exclude matching, unmatched set |
+| 4 | File and file-set runtime contexts | shared per-file context, set-level interface, collection compatibility |
+| 5 | Filesystem check execution | no-selector execution, lazy parsing, parse-failure severity, diagnostics |
+| 6 | Dual-target check types | target metadata, document-aware file-system checks, `filesystem_unmatched_files` |
+| 7 | Documentation and verification | user docs, generated reference, developer docs, focused test suite |
+
+The order keeps the suite honest. First pin the behavior, then add registry and
+config shape, then build the filesystem runner and opt check types into it.
+
+## Phases
+
+### Phase 1 - Failing contracts
+
+**Goal:** tests describe filesystem-attached checks before production code
+exists.
+
+1. **File:** `internal/project/loader_test.go`.
+   Add load tests for `filesystemChecks` under a filesystem base:
+   optional `name`, required `include`, default `path: .`, default
+   `parseFailures: error`, explicit `parseFailures: warning`, and parsed
+   nested `checks`.
+2. **File:** `internal/project/loader_test.go`.
+   Add rejection tests for missing `include`, unknown `parseFailures`, unknown
+   check kind, a check kind that does not support the `filesystem` target, and
+   `filesystemChecks` on a SQLite base.
+3. **File:** `cmd/check_test.go`.
+   Add a no-selector CLI test where a project has no collections, a filesystem
+   scope includes `**/*.md`, and `filesystem_name_case` reports a bad Markdown
+   filename.
+4. **File:** `cmd/check_test.go`.
+   Add a selector test proving `katalyst check notes` runs collection checks
+   only and does not run unrelated filesystem scopes.
+5. **File:** `cmd/check_test.go`.
+   Add parse-failure tests for `filesystem_name_matches_field`: default
+   `parseFailures: error` exits 1, while `parseFailures: warning` reports a
+   warning and does not fail by itself.
+6. **File:** `cmd/check_test.go`.
+   Add a CLI test for `filesystem_unmatched_files`: a file under the scope root
+   matching neither `include` nor `exclude` produces an unmatched-file
+   diagnostic.
+7. **File:** `cmd/testdata/snapshots/check/`.
+   Add snapshots for filesystem diagnostics: path-rule failure, parse warning,
+   and filesystem unmatched file.
+8. **File:** `internal/checks/registry_test.go`.
+   Add descriptor tests for supported targets and document-needs metadata.
+
+### Phase 2 - Shared check metadata and config parsing
+
+**Goal:** the registry describes where a check attaches and one parser serves
+collection and filesystem config.
+
+1. **File:** `internal/checks/registry.go`.
+   Add target constants, `Descriptor.Targets []string`, and helpers such as
+   `SupportsTarget(kind, target)` and `DescriptorTargets(d)`. Treat an empty
+   target list as `collection` during migration.
+2. **File:** `internal/checks/registry.go`.
+   Add document-needs metadata to `Descriptor`, for example
+   `NeedsDocument bool`, plus `NeedsDocument(kind)`. Filesystem scopes use this
+   to decide whether to parse selected files.
+3. **File:** `internal/checks/config.go` (new).
+   Move the reusable raw check shape out of
+   `internal/storage/collection/parse.go`. Define `RawCheck`, key validation,
+   and a `BuildConfigured` helper that folds optional object schema shorthands
+   and calls `checks.Parse`.
+4. **File:** `internal/storage/collection/parse.go`.
+   Replace `RawCheck` and `buildChecks` with the shared checks config helper.
+   Keep collection-specific schema shorthand and variant wiring behavior
+   byte-for-byte compatible.
+5. **File:** `internal/storage/collection/parse.go`.
+   Keep SQLite collection rejection based on descriptor family or target support
+   so existing behavior stays stable.
+6. **File:** `cmd/check_types.go`.
+   Include supported targets in `check-types show` and JSON output through the
+   descriptor. Keep existing scope and severity output.
+7. **File:** `cmd/gendocs/main.go`.
+   Render supported targets on generated check-type pages. Keep generated docs
+   deterministic.
+
+### Phase 3 - Filesystem scope config and expansion
+
+**Goal:** filesystem bases load named scopes and expand them into deterministic
+file sets.
+
+1. **File:** `internal/storage/filesystemcheck/scope.go` (new).
+   Add `RawScope` and `Scope` types with `Name`, `Path`, resolved `Root`,
+   `Include`, `Exclude`, `ParseFailures`, and parsed `Checks`.
+2. **File:** `internal/storage/filesystemcheck/scope.go` (new).
+   Add `Build` to validate scope config: `include` required,
+   `parseFailures` is `error` or `warning`, `checks` required, and every check
+   supports the `filesystem` target.
+3. **File:** `internal/storage/filesystemcheck/scope.go` (new).
+   Add deterministic expansion over `os.DirFS(scope.Root)` using doublestar:
+   selected files match at least one include and no exclude; unmatched files
+   are regular files that match neither include nor exclude.
+4. **File:** `internal/storage/filesystemcheck/scope_test.go` (new).
+   Test include/exclude matching, sorted selected files, sorted unmatched files,
+   missing directories, invalid globs, and default labels for unnamed scopes.
+5. **File:** `internal/project/loader.go`.
+   Add `FilesystemChecks []filesystemcheck.RawScope` to `rawBaseInstance`.
+   Build scopes only for `type: filesystem`, resolve paths against the base
+   root, and store them on `BaseInstance`.
+6. **File:** `internal/project/loader.go`.
+   Reject `filesystemChecks` on non-filesystem bases with a load-time error.
+   Preserve legacy `.katalyst/storage/` readability by parsing the same field
+   there when that legacy directory is used.
+7. **File:** `internal/project/project.go`.
+   Add a `FilesystemCheckScopes()` accessor or expose the loaded scopes through
+   `Config.Bases` in a way `cmd/check.go` can use without knowing raw config.
+8. **File:** `internal/project/projecttest/projecttest.go`.
+   Add a helper for filesystem scope config only if it removes repeated YAML
+   from loader and CLI tests.
+
+### Phase 4 - File and file-set runtime contexts
+
+**Goal:** collection-attached and filesystem-attached checks share runtime
+contexts without breaking existing collection checks.
+
+1. **File:** `internal/checks/checks.go`.
+   Add `FileContext` as the canonical per-file context. Keep `Context` as an
+   alias or compatibility wrapper during the migration.
+2. **File:** `internal/checks/collection.go`.
+   Add `FileSetContext` with `Root`, `Files`, `Unmatched`, `Include`, and
+   `Exclude`. Include enough metadata for existing set-level checks and the new
+   unmatched-files check.
+3. **File:** `internal/checks/collection.go`.
+   Add `FileSetCheck` and `RunFileSetAll`. Keep `CollectionCheck` and
+   `RunCollectionAll` as compatibility wrappers until collection callers move.
+4. **File:** `internal/checks/filesystem/unique_filename.go`.
+   Convert `UniqueFilename` to the file-set context, or add a compatibility
+   adapter if full conversion waits until Phase 6.
+5. **File:** `internal/checks/filesystem/index_file_required.go`.
+   Convert `IndexFileRequired` to the file-set context, preserving diagnostics.
+6. **File:** `internal/checks/structuredobject/unique_field.go`.
+   Convert `UniqueField` to the file-set context with metadata read from each
+   file context.
+7. **File:** `cmd/check.go`.
+   Update collection-scoped execution to build the new `FileSetContext` while
+   preserving existing output and selector behavior.
+
+### Phase 5 - Filesystem check execution
+
+**Goal:** `katalyst check` with no selectors runs filesystem scopes before
+collection checks.
+
+1. **File:** `cmd/filesystem_check.go` (new).
+   Add the filesystem check runner: expand each scope, build runnable file and
+   file-set checks, run file checks per selected file, then run file-set checks.
+2. **File:** `cmd/engine.go`.
+   Add helpers that build checks from an arbitrary list of
+   `checks.ConfiguredCheck`, separate from collection variant routing. Reuse
+   library availability checks and non-object builders.
+3. **File:** `cmd/filesystem_check.go` (new).
+   Parse selected files lazily only when a configured check needs document data.
+   Strip the `schema` directive from metadata the same way `checkItem` does.
+4. **File:** `cmd/filesystem_check.go` (new).
+   Implement `parseFailures`: default error-severity violations fail the run;
+   `warning` emits advisory diagnostics and does not fail by itself.
+5. **File:** `cmd/filesystem_check.go` (new).
+   Format filesystem diagnostics as
+   `filesystem <label>: <path>[:line]: [warning: ]<loc>: <message>`.
+   Keep collection diagnostics unchanged.
+6. **File:** `cmd/check.go`.
+   In the no-selector path, run all filesystem scopes before collection
+   resolution. With one or more selectors, keep existing collection-only
+   behavior.
+7. **File:** `cmd/check.go`.
+   Fold filesystem runner failures into the existing exit code contract:
+   validation failures return exit 1; config and glob usage errors return exit
+   2.
+
+### Phase 6 - Dual-target check types
+
+**Goal:** existing file-system family checks work under filesystem scopes, and
+the new unmatched-files check ships.
+
+1. **File:** `internal/checks/kinds.go`.
+   Add `CheckFilesystemUnmatchedFiles`.
+2. **File:** `internal/checks/filesystem/unmatched_files.go` (new).
+   Implement `filesystem_unmatched_files` as a file-set check over
+   `FileSetContext.Unmatched`. It emits one violation per unmatched file and
+   includes include/exclude patterns in the message.
+3. **File:** `internal/checks/filesystem/*.go`.
+   Add `Targets: []string{"collection", "filesystem"}` to file-system check
+   descriptors that work under both attachment points.
+4. **File:** `internal/checks/filesystem/name_matches_field.go`,
+   `parent_dir_matches_field.go`, and `referenced_files.go`.
+   Mark metadata-aware checks as needing document data so filesystem scopes
+   parse selected files before running them.
+5. **File:** `internal/checks/structuredobject/unique_field.go`.
+   Keep the historical `filesystem_unique_field` kind, mark it as
+   `structuredObject`, `collection` and `filesystem` target compatible, and
+   document that it needs metadata.
+6. **File:** `internal/checks/filesystem/filesystem_test.go`.
+   Add unit tests for the unmatched-files check and direct file-set behavior
+   where useful.
+7. **File:** `cmd/testdata/snapshots/check-types/`.
+   Regenerate snapshots for `check-types list`, `show`, and JSON if descriptor
+   output changes.
+
+### Phase 7 - Documentation and verification
+
+**Goal:** docs, skills, and generated reference describe the new attachment
+model.
+
+1. **File:** `docs/content/deep-dives/domain-model/checks.md`.
+   Split data family, library, attachment target, and runtime granularity.
+2. **File:** `docs/content/reference/configuration.md`.
+   Document `filesystemChecks` under filesystem bases. Note the legacy
+   `.katalyst/storage/` reader only if that page still documents legacy config.
+3. **File:** `docs/content/reference/glossary.md`.
+   Add CollectionCheck, FilesystemCheck, FileCheck, FileSetCheck, and
+   attachment target. Update Check instance and Collection-scoped check.
+4. **File:** `docs/content/how-to/configure-rules.md`.
+   Add a pre-collection filesystem check workflow.
+5. **File:** `internal/checks/AGENTS.md`.
+   Document descriptor target metadata and the runtime naming distinction.
+6. **File:** `internal/storage/collection/AGENTS.md`.
+   Document that collection `checks:` remain collection-attached and filesystem
+   checks live on filesystem bases.
+7. **File:** `.cursor/skills/add-katalyst-check-type/SKILL.md`.
+   Update the checklist so new check types declare supported attachment targets
+   and document needs.
+8. **File:** `docs/content/reference/check-types/`.
+   Run `make docs-gen` after descriptor rendering changes.
+9. **File:** `cmd/check_test.go`, `internal/project/loader_test.go`,
+   `internal/checks/...`, `internal/storage/...`.
+   Run
+   `go test ./cmd ./internal/project ./internal/checks/... ./internal/storage/...`.
+   If generated docs or examples change, run the broader documented suite.
+
+## Key Files
+
+| File | Role |
+|---|---|
+| `product/specs/filesystem-checks-spec.md` | source spec this plan implements |
+| `cmd/check.go` | orchestrates no-selector filesystem checks and existing collection checks |
+| `cmd/engine.go` | shared check building and library availability helpers |
+| `cmd/filesystem_check.go` | new filesystem-scope runner and diagnostics |
+| `cmd/check_test.go` | CLI behavior, exit codes, and filesystem diagnostics |
+| `cmd/testdata/snapshots/check/` | golden filesystem check diagnostics |
+| `internal/project/loader.go` | parses base-level `filesystemChecks` and stores built scopes |
+| `internal/project/project.go` | exposes filesystem scopes to the command layer |
+| `internal/project/loader_test.go` | config parsing and validation coverage |
+| `internal/project/projecttest/projecttest.go` | optional config helper for filesystem scope tests |
+| `internal/storage/filesystemcheck/scope.go` | new raw scope config, build validation, and file-set expansion |
+| `internal/storage/filesystemcheck/scope_test.go` | filesystem scope matching tests |
+| `internal/storage/collection/parse.go` | consumes shared check config helper for collection checks |
+| `internal/storage/collection/filesystem/collection.go` | reference for deterministic filesystem traversal and matching |
+| `internal/checks/registry.go` | descriptor targets, document needs, and registry helpers |
+| `internal/checks/config.go` | shared raw check config parser for both attachment points |
+| `internal/checks/checks.go` | per-file context compatibility layer |
+| `internal/checks/collection.go` | file-set context and compatibility wrappers |
+| `internal/checks/kinds.go` | new `filesystem_unmatched_files` kind constant |
+| `internal/checks/filesystem/unmatched_files.go` | new unmatched-files check |
+| `internal/checks/filesystem/*.go` | target metadata and document-needs metadata for file-system checks |
+| `internal/checks/structuredobject/unique_field.go` | dual-target metadata-aware set-level check |
+| `cmd/check_types.go` | CLI descriptor rendering for supported targets |
+| `cmd/gendocs/main.go` | generated check-type page rendering for supported targets |
+| `docs/content/deep-dives/domain-model/checks.md` | durable explanation of target vs family vs granularity |
+| `docs/content/reference/configuration.md` | user-facing filesystemChecks config reference |
+| `docs/content/reference/glossary.md` | new vocabulary |
+| `docs/content/how-to/configure-rules.md` | pre-collection filesystem check workflow |
+| `internal/checks/AGENTS.md` | developer convention for check descriptors |
+| `internal/storage/collection/AGENTS.md` | developer convention for attachment homes |
+| `.cursor/skills/add-katalyst-check-type/SKILL.md` | contributor workflow for new check types |
+
+## Architecture Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Config home | base-level `filesystemChecks` | the current code's configured backend instance is a base, and the base owns root path resolution |
+| Legacy storage config | parse the same field when legacy `.katalyst/storage/` is used | keeps legacy storage files aligned with base config behavior |
+| Collection config key | keep collection `checks:` | the collection block already supplies the attachment target and existing configs keep working |
+| Shared check parsing | move raw check parsing into `internal/checks` | collection and filesystem attachments need the same `kind` and args parser without duplicating `RawCheck` |
+| Target metadata | descriptor-level `Targets` with empty meaning collection | existing descriptors migrate incrementally and docs can render one source of truth |
+| Document parsing | descriptor-level document-needs metadata | filesystem scopes parse lazily and path-only checks stay path-only |
+| Parse failure policy | scope-level `parseFailures`, default `error` | CI stays strict by default while onboarding can opt into warnings |
+| Runtime contexts | add file and file-set contexts with compatibility wrappers | the implementation can share checks without renaming every interface in one step |
+| Filesystem unmatched files | new `filesystem_unmatched_files` check | raw subtree coverage is opt-in and separate from collection unmatched-file invariants |
+| Selective filesystem execution | defer named-scope selectors | no-selector execution covers onboarding and CI while avoiding selector grammar churn |
+
+## Documentation updates
+
+- **Phase 7, File:** `docs/content/deep-dives/domain-model/checks.md`.
+  Explain data family, library, attachment target, and runtime granularity.
+- **Phase 7, File:** `docs/content/reference/configuration.md`.
+  Add `filesystemChecks` keys, defaults, examples, parse-failure severity, and
+  unmatched-files check usage.
+- **Phase 7, File:** `docs/content/reference/glossary.md`.
+  Add the new check vocabulary and update existing check-instance wording.
+- **Phase 7, File:** `docs/content/how-to/configure-rules.md`.
+  Add the first workflow that runs checks before collections exist.
+- **Phase 7, File:** `internal/checks/AGENTS.md`.
+  Record descriptor target and document-needs conventions.
+- **Phase 7, File:** `internal/storage/collection/AGENTS.md`.
+  Record where collection-attached checks and filesystem-attached checks live.
+- **Phase 7, File:** `.cursor/skills/add-katalyst-check-type/SKILL.md`.
+  Add target and document-needs steps to the new-check workflow.
+- **Phase 7, File:** `docs/content/reference/check-types/`.
+  Regenerate with `make docs-gen` after descriptor rendering changes.
+
+## Out of Scope
+
+- Selective filesystem scope execution such as `katalyst check --filesystem docs`.
+- Renaming every internal `Check` and `CollectionCheck` symbol in one sweep.
+- Running object schemas from filesystem scopes.
+- Filesystem checks for SQLite or other non-filesystem base types.
+- Inferring collections from filesystem scopes.
+- Changing collection unmatched-file behavior.
+- Adding default `include` patterns.

From d846e253bbc08e8b664a0874d6329aece7f0936d Mon Sep 17 00:00:00 2001
From: Abe Gong <abe@Abes-MacBook-Air.local>
Date: Mon, 29 Jun 2026 13:44:58 -0600
Subject: [PATCH 4/6] Add filesystem check scopes

---
 .../skills/add-katalyst-check-type/SKILL.md   |   7 +-
 cmd/check.go                                  |  15 +-
 cmd/check_test.go                             | 153 +++++++++++++++
 cmd/check_types.go                            |   2 +
 cmd/check_types_test.go                       |  19 +-
 cmd/engine.go                                 |  40 ++--
 cmd/filesystem_check.go                       | 164 ++++++++++++++++
 cmd/gendocs/main.go                           |   1 +
 cmd/testdata/snapshots/check-types/list.txt   |   6 +-
 .../check-types/show-markdown_single_h1.txt   |   1 +
 .../check-types/show-object_field_enum.txt    |   1 +
 .../show-object_required_field.txt            |   1 +
 .../content/deep-dives/domain-model/checks.md |  59 ++++--
 docs/content/how-to/configure-rules.md        |  26 +++
 docs/content/reference/check-types/_index.md  |   1 +
 .../check-types/file-system/_index.md         |   1 +
 .../check-types/file-system/extension-in.md   |   2 +
 .../file-system/index-file-required.md        |   2 +
 .../check-types/file-system/name-affix.md     |   2 +
 .../check-types/file-system/name-case.md      |   2 +
 .../check-types/file-system/name-length.md    |   2 +
 .../file-system/name-matches-field.md         |   2 +
 .../check-types/file-system/name-regex.md     |   2 +
 .../check-types/file-system/parent-dir-in.md  |   2 +
 .../file-system/parent-dir-matches-field.md   |   2 +
 .../check-types/file-system/path-charset.md   |   2 +
 .../check-types/file-system/path-depth.md     |   2 +
 .../file-system/referenced-files-exist.md     |   2 +
 .../file-system/unique-filename.md            |   2 +
 .../file-system/unmatched-files.md            |  30 +++
 .../code-fence-language-required.md           |   2 +
 .../no-heading-level-jumps.md                 |   2 +
 .../markdown-body-text/required-section.md    |   2 +
 .../markdown-body-text/requires-h1.md         |   2 +
 .../markdown-body-text/single-h1.md           |   2 +
 .../markdown-body-text/title-matches-h1.md    |   2 +
 .../markdown-body-text/writing-tells.md       |   2 +
 .../check-types/plain-text/denylist.md        |   2 +
 .../check-types/plain-text/forbids.md         |   2 +
 .../check-types/plain-text/requires.md        |   2 +
 .../structured-object/field-enum.md           |   2 +
 .../structured-object/field-type.md           |   2 +
 .../structured-object/number-range.md         |   2 +
 .../check-types/structured-object/object.md   |   2 +
 .../structured-object/required-field.md       |   2 +
 .../structured-object/sentence-case.md        |   2 +
 .../structured-object/string-length.md        |   2 +
 .../structured-object/unique-field.md         |   2 +
 docs/content/reference/configs/bases.md       |  31 +++
 docs/content/reference/configs/checks.md      |  49 ++++-
 docs/content/reference/glossary.md            |  14 +-
 internal/checks/AGENTS.md                     |  11 +-
 internal/checks/checks.go                     |   7 +-
 internal/checks/collection.go                 |  24 ++-
 internal/checks/config.go                     | 130 +++++++++++++
 internal/checks/filesystem/extension_in.go    |   1 +
 .../checks/filesystem/index_file_required.go  |   1 +
 internal/checks/filesystem/name_affix.go      |   1 +
 internal/checks/filesystem/name_case.go       |   1 +
 internal/checks/filesystem/name_length.go     |   1 +
 .../checks/filesystem/name_matches_field.go   |  12 +-
 internal/checks/filesystem/name_regex.go      |   1 +
 internal/checks/filesystem/parent_dir_in.go   |   1 +
 .../filesystem/parent_dir_matches_field.go    |  12 +-
 internal/checks/filesystem/path_charset.go    |   1 +
 internal/checks/filesystem/path_depth.go      |   1 +
 .../checks/filesystem/referenced_files.go     |  12 +-
 internal/checks/filesystem/unique_filename.go |   1 +
 internal/checks/filesystem/unmatched_files.go |  50 +++++
 internal/checks/kinds.go                      |   1 +
 internal/checks/registry.go                   |  43 +++++
 internal/checks/registry_test.go              |  30 +++
 .../checks/structuredobject/unique_field.go   |  14 +-
 internal/project/loader.go                    |  43 ++++-
 internal/project/loader_test.go               | 137 +++++++++++++
 internal/project/project.go                   |   6 +
 internal/storage/collection/AGENTS.md         |   5 +-
 internal/storage/collection/parse.go          | 115 ++---------
 internal/storage/filesystemcheck/scope.go     | 181 ++++++++++++++++++
 79 files changed, 1345 insertions(+), 181 deletions(-)
 create mode 100644 cmd/filesystem_check.go
 create mode 100644 docs/content/reference/check-types/file-system/unmatched-files.md
 create mode 100644 internal/checks/config.go
 create mode 100644 internal/checks/filesystem/unmatched_files.go
 create mode 100644 internal/storage/filesystemcheck/scope.go

diff --git a/.cursor/skills/add-katalyst-check-type/SKILL.md b/.cursor/skills/add-katalyst-check-type/SKILL.md
index 10da295..6a4d89f 100644
--- a/.cursor/skills/add-katalyst-check-type/SKILL.md
+++ b/.cursor/skills/add-katalyst-check-type/SKILL.md
@@ -33,7 +33,7 @@ Copy this checklist and keep it updated:
 ```text
 Check Type Task Progress:
 - [ ] 1) Kind constant added (internal/checks/kinds.go)
-- [ ] 2) Check file added (struct + Run + args + Descriptor + registerParsed)
+- [ ] 2) Check file added (struct + Run + args + Descriptor targets/document-needs + registerParsed)
 - [ ] 3) Tests added/updated
 - [ ] 4) Fixtures/readmes updated
 - [ ] 5) Reference regenerated
@@ -62,6 +62,11 @@ Add one file in the check type's family package — `internal/checks/structuredo
   the family's `common.go`) rather than re-deriving.
 - An `init()` calling the family's `registerParsed(descriptor, parse, build,
   buildColl)`:
+  - Set `descriptor.Targets`. Use `checks.TargetCollection` for collection
+    `checks:` and add `checks.TargetFilesystem` only when the same
+    implementation works under `filesystemChecks`.
+  - Set `descriptor.NeedsDocument` when the check reads frontmatter, markdown
+    body text, or source line maps. Path-only checks leave it false.
   - `parse func(*yaml.Node) (any, error)` decodes the node into the args struct
     and validates it. Use `internal/checks/argcheck` helpers (`RequireString`,
     `OneOf`, …) for uniform, test-stable error phrasing, plus any family-local
diff --git a/cmd/check.go b/cmd/check.go
index 3826199..e52fba7 100644
--- a/cmd/check.go
+++ b/cmd/check.go
@@ -47,14 +47,23 @@ reported as unmatched references (errors).`,
 			if err != nil {
 				return err
 			}
+			anyInvalid := false
+			out, errOut := cmd.OutOrStdout(), cmd.ErrOrStderr()
+
+			if len(args) == 0 {
+				bad, err := runFilesystemChecks(errOut, e)
+				if err != nil {
+					return err
+				}
+				if bad {
+					anyInvalid = true
+				}
+			}
 			res, err := resolveSelectors(e.proj, args)
 			if err != nil {
 				return err
 			}
 
-			anyInvalid := false
-			out, errOut := cmd.OutOrStdout(), cmd.ErrOrStderr()
-
 			for _, item := range res.Items {
 				ok, err := checkItem(out, errOut, e, item)
 				if err != nil {
diff --git a/cmd/check_test.go b/cmd/check_test.go
index f0d14ff..6b5aae1 100644
--- a/cmd/check_test.go
+++ b/cmd/check_test.go
@@ -116,6 +116,159 @@ func TestCheck_wholeProjectWhenNoSelector(t *testing.T) {
 	}
 }
 
+func TestCheck_filesystemChecks_runWithoutCollections(t *testing.T) {
+	dir := t.TempDir()
+	writeProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections: {}
+`,
+	})
+	chdir(t, dir)
+	mustWrite(t, filepath.Join(dir, "docs/BadName.md"), "---\ntitle: Bad\n---\n# Bad\n")
+
+	_, stderr, err := runRoot(t, "check")
+	if err == nil {
+		t.Fatalf("expected filesystem check failure")
+	}
+	if !strings.Contains(stderr, "filesystem docs: BadName.md") || !strings.Contains(stderr, "must be kebab-case") {
+		t.Errorf("expected filesystem name-case diagnostic, got: %q", stderr)
+	}
+}
+
+func TestCheck_selectorDoesNotRunFilesystemChecks(t *testing.T) {
+	dir := t.TempDir()
+	writeProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections:
+  notes:
+    path: notes
+    checks:
+      - kind: markdown_requires_h1
+`,
+	})
+	chdir(t, dir)
+	mustWrite(t, filepath.Join(dir, "docs/BadName.md"), "---\ntitle: Bad\n---\n# Bad\n")
+	mustWrite(t, filepath.Join(dir, "notes/good.md"), "---\ntitle: Good\n---\n# Good\n")
+
+	stdout, stderr, err := runRoot(t, "check", "notes")
+	if err != nil {
+		t.Fatalf("selector check should ignore filesystem scopes: %v\nstderr: %s", err, stderr)
+	}
+	if !strings.Contains(stdout, "good.md: OK") {
+		t.Errorf("expected collection item OK, got: %q", stdout)
+	}
+	if strings.Contains(stderr, "BadName") {
+		t.Errorf("selector run should not report filesystem scope diagnostics, got: %q", stderr)
+	}
+}
+
+func TestCheck_filesystemParseFailuresDefaultToError(t *testing.T) {
+	dir := t.TempDir()
+	writeProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_matches_field
+        field: title
+collections: {}
+`,
+	})
+	chdir(t, dir)
+	mustWrite(t, filepath.Join(dir, "docs/bad.md"), "---\n: bad\n---\n# Bad\n")
+
+	_, stderr, err := runRoot(t, "check")
+	if err == nil {
+		t.Fatalf("expected parse failure to fail by default")
+	}
+	var coded interface{ Code() int }
+	if !errors.As(err, &coded) || coded.Code() != 1 {
+		t.Errorf("expected exit code 1, got: %v", err)
+	}
+	if !strings.Contains(stderr, "filesystem docs: bad.md") || !strings.Contains(stderr, "parse document") {
+		t.Errorf("expected parse diagnostic, got: %q", stderr)
+	}
+}
+
+func TestCheck_filesystemParseFailuresCanWarn(t *testing.T) {
+	dir := t.TempDir()
+	writeProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs
+    include: ["**/*.md"]
+    parseFailures: warning
+    checks:
+      - kind: filesystem_name_matches_field
+        field: title
+collections: {}
+`,
+	})
+	chdir(t, dir)
+	mustWrite(t, filepath.Join(dir, "docs/bad.md"), "---\n: bad\n---\n# Bad\n")
+
+	_, stderr, err := runRoot(t, "check")
+	if err != nil {
+		t.Fatalf("warning parse failure should not fail the run: %v\nstderr: %s", err, stderr)
+	}
+	if !strings.Contains(stderr, "warning: /: parse document") {
+		t.Errorf("expected warning parse diagnostic, got: %q", stderr)
+	}
+}
+
+func TestCheck_filesystemUnmatchedFiles(t *testing.T) {
+	dir := t.TempDir()
+	writeProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs
+    include: ["**/*.md"]
+    exclude: ["ignored/**"]
+    checks:
+      - kind: filesystem_unmatched_files
+collections: {}
+`,
+	})
+	chdir(t, dir)
+	mustWrite(t, filepath.Join(dir, "docs/page.md"), "---\ntitle: Page\n---\n# Page\n")
+	mustWrite(t, filepath.Join(dir, "docs/raw.txt"), "raw\n")
+	mustWrite(t, filepath.Join(dir, "docs/ignored/raw.txt"), "ignored\n")
+
+	_, stderr, err := runRoot(t, "check")
+	if err == nil {
+		t.Fatalf("expected unmatched filesystem file failure")
+	}
+	if !strings.Contains(stderr, "filesystem docs: raw.txt") || !strings.Contains(stderr, "unmatched file") {
+		t.Errorf("expected unmatched-file diagnostic, got: %q", stderr)
+	}
+	if strings.Contains(stderr, "ignored/raw.txt") {
+		t.Errorf("excluded files should not be reported, got: %q", stderr)
+	}
+}
+
 func TestCheck_unmatchedFileInCollectionDir_isError(t *testing.T) {
 	dir := setupNotesRepo(t, objectNotesConfig)
 	mustWrite(t, filepath.Join(dir, "notes/ok.md"), "---\ntitle: Ok\nyear: 1\n---\n# Ok\n")
diff --git a/cmd/check_types.go b/cmd/check_types.go
index e6af48f..bee2600 100644
--- a/cmd/check_types.go
+++ b/cmd/check_types.go
@@ -119,6 +119,7 @@ func runCheckTypesDetail(cmd *cobra.Command, checkType string, asJSON bool) erro
 	printSectionHeader(out, fmt.Sprintf("%s › %s", fam.Title, d.Title))
 	fmt.Fprintf(out, "- kind: %s\n", d.CheckType)
 	fmt.Fprintf(out, "- family: %s\n", d.Family)
+	fmt.Fprintf(out, "- targets: %s\n", strings.Join(checks.DescriptorTargets(d), ", "))
 	scope := d.Scope
 	if scope == "" {
 		scope = "item"
@@ -256,6 +257,7 @@ func jsonDescriptor(d checks.Descriptor) checks.Descriptor {
 	if d.Fields == nil {
 		d.Fields = []checks.Field{}
 	}
+	d.Targets = checks.DescriptorTargets(d)
 	return d
 }
 
diff --git a/cmd/check_types_test.go b/cmd/check_types_test.go
index a78dc45..9381434 100644
--- a/cmd/check_types_test.go
+++ b/cmd/check_types_test.go
@@ -185,8 +185,9 @@ func TestCheckTypesList_jsonArrayShape(t *testing.T) {
 	}
 
 	var got []struct {
-		CheckType string `json:"check_type"`
-		Family    string `json:"family"`
+		CheckType string   `json:"check_type"`
+		Family    string   `json:"family"`
+		Targets   []string `json:"targets"`
 		Fields    []struct {
 			Name string `json:"name"`
 		} `json:"fields"`
@@ -199,8 +200,10 @@ func TestCheckTypesList_jsonArrayShape(t *testing.T) {
 		t.Fatal("expected at least one descriptor")
 	}
 	seen := map[string]bool{}
+	targets := map[string][]string{}
 	for i, d := range got {
 		seen[d.CheckType] = true
+		targets[d.CheckType] = d.Targets
 		if got[i].ConfigExample == "" {
 			t.Errorf("entry %d (%s): empty config_example", i, d.CheckType)
 		}
@@ -227,6 +230,12 @@ func TestCheckTypesList_jsonArrayShape(t *testing.T) {
 	if strings.Contains(stdout, `"default": ""`) {
 		t.Errorf("empty default should be omitted, not emitted")
 	}
+	if strings.Join(targets["filesystem_name_case"], ",") != "collection,filesystem" {
+		t.Errorf("filesystem_name_case targets = %v, want collection+filesystem", targets["filesystem_name_case"])
+	}
+	if strings.Join(targets["markdown_requires_h1"], ",") != "collection" {
+		t.Errorf("markdown_requires_h1 targets = %v, want collection", targets["markdown_requires_h1"])
+	}
 }
 
 func TestCheckTypesShow_jsonObject(t *testing.T) {
@@ -237,7 +246,8 @@ func TestCheckTypesShow_jsonObject(t *testing.T) {
 	}
 
 	var got struct {
-		CheckType string `json:"check_type"`
+		CheckType string   `json:"check_type"`
+		Targets   []string `json:"targets"`
 		Fields    []struct {
 			Name     string `json:"name"`
 			Required bool   `json:"required"`
@@ -249,6 +259,9 @@ func TestCheckTypesShow_jsonObject(t *testing.T) {
 	if got.CheckType != "object_number_range" {
 		t.Errorf("got check type %q, want object_number_range", got.CheckType)
 	}
+	if strings.Join(got.Targets, ",") != "collection" {
+		t.Errorf("targets = %v, want collection", got.Targets)
+	}
 	if len(got.Fields) != 3 {
 		t.Fatalf("got %d fields, want 3", len(got.Fields))
 	}
diff --git a/cmd/engine.go b/cmd/engine.go
index 486d061..5f556a3 100644
--- a/cmd/engine.go
+++ b/cmd/engine.go
@@ -134,10 +134,6 @@ func (e *engine) checksFor(c project.Collection, meta map[string]any) ([]checks.
 		effective = append(effective, matched.Checks...)
 	}
 
-	if err := ensureLibrariesAvailable(effective); err != nil {
-		return nil, err
-	}
-
 	checkList := make([]checks.Check, 0, len(effective))
 
 	inlineSchema := ""
@@ -168,14 +164,11 @@ func (e *engine) checksFor(c project.Collection, meta map[string]any) ([]checks.
 	// Every non-object, per-item check is built from its registry entry. The
 	// object check is handled above (it needs a compiled schema); collection-
 	// scoped checks have no per-item builder, so Build skips them here.
-	for _, cc := range effective {
-		if cc.Kind == checks.CheckObject {
-			continue
-		}
-		if chk, ok := checks.Build(cc.Kind, cc.Args); ok {
-			checkList = append(checkList, chk)
-		}
+	fileChecks, err := e.fileChecksFor(effective)
+	if err != nil {
+		return nil, err
 	}
+	checkList = append(checkList, fileChecks...)
 
 	// An item that matched no variant under useExhaustiveVariants fails. The
 	// verdict rides through RunAll like any other check (so `check` and
@@ -228,8 +221,31 @@ func (unroutedCheck) Run(checks.Context) []checks.Violation {
 // collectionChecksFor builds the collection-scoped checks configured for a
 // collection. These run once per collection, after the per-item pass.
 func (e *engine) collectionChecksFor(c project.Collection) ([]checks.CollectionCheck, error) {
+	return e.fileSetChecksFor(c.Checks)
+}
+
+func (e *engine) fileChecksFor(configured []checks.ConfiguredCheck) ([]checks.Check, error) {
+	if err := ensureLibrariesAvailable(configured); err != nil {
+		return nil, err
+	}
+	var out []checks.Check
+	for _, cc := range configured {
+		if cc.Kind == checks.CheckObject {
+			continue
+		}
+		if chk, ok := checks.Build(cc.Kind, cc.Args); ok {
+			out = append(out, chk)
+		}
+	}
+	return out, nil
+}
+
+func (e *engine) fileSetChecksFor(configured []checks.ConfiguredCheck) ([]checks.CollectionCheck, error) {
+	if err := ensureLibrariesAvailable(configured); err != nil {
+		return nil, err
+	}
 	var out []checks.CollectionCheck
-	for _, cc := range c.Checks {
+	for _, cc := range configured {
 		if col, ok := checks.BuildCollection(cc.Kind, cc.Args); ok {
 			out = append(out, col)
 		}
diff --git a/cmd/filesystem_check.go b/cmd/filesystem_check.go
new file mode 100644
index 0000000..dafc07e
--- /dev/null
+++ b/cmd/filesystem_check.go
@@ -0,0 +1,164 @@
+package cmd
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/abegong/katalyst/internal/checks"
+	"github.com/abegong/katalyst/internal/codec/markdownbodytext"
+	"github.com/abegong/katalyst/internal/storage/filesystemcheck"
+)
+
+type runtimeFileCheck struct {
+	kind     checks.CheckType
+	check    checks.Check
+	needsDoc bool
+}
+
+func runFilesystemChecks(errOut io.Writer, e *engine) (bool, error) {
+	bad := false
+	for _, scope := range e.proj.FilesystemCheckScopes() {
+		scopeBad, err := runFilesystemScope(errOut, e, scope)
+		if err != nil {
+			return false, err
+		}
+		if scopeBad {
+			bad = true
+		}
+	}
+	return bad, nil
+}
+
+func runFilesystemScope(errOut io.Writer, e *engine, scope filesystemcheck.Scope) (bool, error) {
+	expanded, err := filesystemcheck.Expand(scope)
+	if err != nil {
+		return false, asUsageErr(err)
+	}
+	fileChecks, err := runtimeFileChecks(scope.Checks)
+	if err != nil {
+		return false, err
+	}
+	setChecks, err := e.fileSetChecksFor(scope.Checks)
+	if err != nil {
+		return false, err
+	}
+
+	needsDoc := scopeNeedsDocument(scope.Checks)
+	bad := false
+	setCtx := checks.FileSetContext{
+		Root:      scope.Root,
+		Items:     make([]checks.ItemContext, 0, len(expanded.Selected)),
+		Unmatched: rels(expanded.Unmatched),
+		Include:   scope.Include,
+		Exclude:   scope.Exclude,
+	}
+	for _, file := range expanded.Selected {
+		var doc *markdownbodytext.Document
+		meta := map[string]any{}
+		parseOK := true
+		if needsDoc {
+			src, err := os.ReadFile(file.Path)
+			if err != nil {
+				return false, asUsageErr(err)
+			}
+			doc, err = markdownbodytext.Parse(src)
+			if err != nil {
+				parseOK = false
+				severity := checks.SeverityError
+				if scope.ParseFailures == filesystemcheck.ParseFailuresWarning {
+					severity = checks.SeverityWarning
+				}
+				printFilesystemViolation(errOut, scope, file.Rel, checks.Violation{
+					Path:     "/",
+					Message:  fmt.Sprintf("parse document: %v", err),
+					Severity: severity,
+				})
+				if severity != checks.SeverityWarning {
+					bad = true
+				}
+			} else {
+				meta = dropKey(doc.Meta, "schema")
+			}
+		}
+		setCtx.Items = append(setCtx.Items, checks.ItemContext{FilePath: file.Path, Meta: meta})
+		ctx := checks.FileContext{
+			FilePath:       file.Path,
+			CollectionRoot: scope.Root,
+			Doc:            doc,
+			Meta:           meta,
+		}
+		for _, rc := range fileChecks {
+			if rc.needsDoc && !parseOK {
+				continue
+			}
+			for _, v := range rc.check.Run(ctx) {
+				printFilesystemViolation(errOut, scope, file.Rel, v)
+				if v.Severity != checks.SeverityWarning {
+					bad = true
+				}
+			}
+		}
+	}
+	for _, v := range checks.RunFileSetAll(setCtx, setChecks) {
+		path := v.File
+		if path == "" {
+			path = scope.Name
+		}
+		printFilesystemViolation(errOut, scope, path, v)
+		if v.Severity != checks.SeverityWarning {
+			bad = true
+		}
+	}
+	return bad, nil
+}
+
+func runtimeFileChecks(configured []checks.ConfiguredCheck) ([]runtimeFileCheck, error) {
+	if err := ensureLibrariesAvailable(configured); err != nil {
+		return nil, err
+	}
+	var out []runtimeFileCheck
+	for _, cc := range configured {
+		if chk, ok := checks.Build(cc.Kind, cc.Args); ok {
+			out = append(out, runtimeFileCheck{
+				kind:     cc.Kind,
+				check:    chk,
+				needsDoc: checks.NeedsDocument(cc.Kind),
+			})
+		}
+	}
+	return out, nil
+}
+
+func scopeNeedsDocument(configured []checks.ConfiguredCheck) bool {
+	for _, cc := range configured {
+		if checks.NeedsDocument(cc.Kind) {
+			return true
+		}
+	}
+	return false
+}
+
+func rels(files []filesystemcheck.File) []string {
+	out := make([]string, len(files))
+	for i, file := range files {
+		out[i] = file.Rel
+	}
+	return out
+}
+
+func printFilesystemViolation(w io.Writer, scope filesystemcheck.Scope, path string, v checks.Violation) {
+	loc := v.Path
+	if loc == "" {
+		loc = "/"
+	}
+	marker := ""
+	if v.Severity == checks.SeverityWarning {
+		marker = "warning: "
+	}
+	if v.Line > 0 {
+		fmt.Fprintf(w, "filesystem %s: %s:%d: %s%s: %s\n", scope.Name, path, v.Line, marker, loc, v.Message)
+		return
+	}
+	fmt.Fprintf(w, "filesystem %s: %s: %s%s: %s\n", scope.Name, path, marker, loc, v.Message)
+}
diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go
index f963f36..e651bd9 100644
--- a/cmd/gendocs/main.go
+++ b/cmd/gendocs/main.go
@@ -314,6 +314,7 @@ func checkTypePage(d checks.Descriptor, fam checks.Family, weight int) string {
 	if d.Scope == "collection" {
 		fmt.Fprint(&b, "**Scope:** collection, runs once per collection over all its items.\n\n")
 	}
+	fmt.Fprintf(&b, "**Targets:** %s.\n\n", strings.Join(checks.DescriptorTargets(d), ", "))
 	if d.Severity == "warning" {
 		fmt.Fprint(&b, "**Severity:** warning, reported for review; never fails a run.\n\n")
 	}
diff --git a/cmd/testdata/snapshots/check-types/list.txt b/cmd/testdata/snapshots/check-types/list.txt
index ea4b343..4dc5a84 100644
--- a/cmd/testdata/snapshots/check-types/list.txt
+++ b/cmd/testdata/snapshots/check-types/list.txt
@@ -64,7 +64,7 @@ Markdown body text (7)
   required: -
   optional: -
 
-File system (13)
+File system (14)
 ----------------
 - filesystem_extension_in
   purpose: Allow only specific file extensions.
@@ -118,6 +118,10 @@ File system (13)
   purpose: Require that no two items in the collection share a basename.
   required: -
   optional: -
+- filesystem_unmatched_files
+  purpose: Report regular files under a filesystem scope that match neither include nor exclude patterns.
+  required: -
+  optional: -
 
 Plain text (4)
 --------------
diff --git a/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt b/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt
index ff74a52..a554cb3 100644
--- a/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt
+++ b/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt
@@ -2,6 +2,7 @@ Markdown body text › Single H1
 --------------------------------
 - kind: markdown_single_h1
 - family: markdownBodyText
+- targets: collection
 - scope: item
 - severity: error
 - purpose: Require that the markdown body contains at most one H1 heading.
diff --git a/cmd/testdata/snapshots/check-types/show-object_field_enum.txt b/cmd/testdata/snapshots/check-types/show-object_field_enum.txt
index ef4263d..a1ffc3f 100644
--- a/cmd/testdata/snapshots/check-types/show-object_field_enum.txt
+++ b/cmd/testdata/snapshots/check-types/show-object_field_enum.txt
@@ -2,6 +2,7 @@ Structured object › Field enum
 --------------------------------
 - kind: object_field_enum
 - family: structuredObject
+- targets: collection
 - scope: item
 - severity: error
 - purpose: Require that a field is one of a fixed set of values.
diff --git a/cmd/testdata/snapshots/check-types/show-object_required_field.txt b/cmd/testdata/snapshots/check-types/show-object_required_field.txt
index db0f40c..4804868 100644
--- a/cmd/testdata/snapshots/check-types/show-object_required_field.txt
+++ b/cmd/testdata/snapshots/check-types/show-object_required_field.txt
@@ -2,6 +2,7 @@ Structured object › Required field
 ------------------------------------
 - kind: object_required_field
 - family: structuredObject
+- targets: collection
 - scope: item
 - severity: error
 - purpose: Require that a frontmatter field exists.
diff --git a/docs/content/deep-dives/domain-model/checks.md b/docs/content/deep-dives/domain-model/checks.md
index 9ca4733..7f8c39f 100644
--- a/docs/content/deep-dives/domain-model/checks.md
+++ b/docs/content/deep-dives/domain-model/checks.md
@@ -21,23 +21,47 @@ model]({{< relref "_index.md" >}}).
 |---|---|
 | **Check** | Shorthand for a check instance when context is unambiguous. A check asserts one condition and reports a violation when the condition fails. |
 | **Check type** | The reusable definition of a constraint: `object_required_field`, `markdown_single_h1`, and so on. A check type is selected by its `kind:` id and appears in the generated check types reference. |
-| **Check instance** | One configured check attached to a collection: a check type plus its arguments, written as one YAML object under `checks:`. The type is the rule; the instance is the rule applied here. |
+| **Check instance** | One configured check attached to a collection or filesystem scope: a check type plus its arguments, written as one YAML object under `checks:`. The type is the rule; the instance is the rule applied here. |
 | **Family** | The kind of source data a check type reads: `structuredObject` (frontmatter), `markdownBodyText` (the body), `fileSystem` (names and paths), or `plainText` (raw body text). |
+| **Attachment target** | The config site where a check instance is valid: `collection` for collection `checks:`, or `filesystem` for base-level `filesystemChecks`. |
 | **Check library** | The provider that supplies and runs a check type. Native libraries wrap hand-written checks; schema-backed libraries delegate to an external validation engine. |
-| **Scope** | The level where a check runs. Most checks are item-scoped; a few are collection-scoped and reason across every item in the collection. |
+| **Runtime granularity** | The level where a check runs. Most checks are file-scoped; a few are file-set-scoped and reason across every selected file. |
 | **Severity** | The consequence of a violation. `error` fails the run; `warning` is advisory and does not change the exit code. |
 | **Violation** | One failed check result, with a message, source location, JSON pointer when applicable, severity, and sometimes a sibling file for collection-scoped findings. |
 
-Family and library are separate axes. Family answers *what data does this check
-read?* Library answers *who runs it?* A single family can span libraries:
+Family, library, attachment target, and runtime granularity are separate axes.
+Family answers *what data does this check read?* Library answers *who runs it?*
+Attachment target answers *where can a user configure it?* Runtime granularity
+answers *does it run once per file or once per selected file set?* A single
+family can span libraries:
 `structuredObject` includes both `object` from the JSON Schema library and
 `object_required_field` from the native structured-object library.
 
 The registry is the single source of truth for check types. Each check type
-self-registers a `Descriptor` (its id, family, docs metadata) and a constructor.
-`cmd/engine` builds the runnable list by registry lookup; the docs generator and
-`katalyst check-types list` read the same descriptors. A parity test fails if a
-configured kind has no descriptor, so a check type cannot ship undocumented.
+self-registers a `Descriptor` (its id, family, targets, docs metadata) and a
+constructor. `cmd/engine` builds the runnable list by registry lookup; the docs
+generator and `katalyst check-types list` read the same descriptors. A parity
+test fails if a configured kind has no descriptor, so a check type cannot ship
+undocumented.
+
+## Attachment targets
+
+Collection-attached checks live under a collection's `checks:` list. They run
+after selector resolution and can use schema precedence, variants, and the
+collection's full sibling set. This is the historical model and remains the
+right place for rules that depend on collection identity.
+
+Filesystem-attached checks live under a filesystem base's `filesystemChecks`
+list. Each scope selects raw files with `include` and `exclude` globs. A
+no-selector `katalyst check` runs filesystem scopes before collection checks,
+so a project can enforce path policy before any collection exists. Explicit
+collection selectors stay collection-only.
+
+The descriptor's `Targets` list controls where a check type may be configured.
+During migration, an empty list means `collection`. File-system-family checks
+that only read paths can usually support both targets. Checks that read
+frontmatter or body text declare that they need a parsed document so filesystem
+scopes parse lazily and path-only scopes avoid unnecessary document work.
 
 ## Check libraries
 
@@ -97,11 +121,13 @@ model]({{< relref "_index.md" >}}) for the precedence table and the
 full per-item lifecycle. Before any schema compiles, the engine confirms the
 owning libraries are available.
 
-Running is uniform: every per-item check returns a list of violations, which the
-engine concatenates; collection-scoped checks run in a second pass over the
-whole collection. A violation carries a JSON-pointer `Path`, a `Message`, a
-source `Line`, an optional `File` (for collection-scoped findings that name a
-sibling), and a `Severity`. An item with no violations prints `path: OK`.
+Running is uniform: every file check returns a list of violations, which the
+engine concatenates; file-set checks run in a second pass over the selected
+files. For collections, that file set is the whole collection. For filesystem
+checks, it is the scope's selected file set plus its unmatched files. A
+violation carries a JSON-pointer `Path`, a `Message`, a source `Line`, an
+optional `File` (for file-set findings that name a sibling), and a `Severity`.
+An item with no violations prints `path: OK`.
 
 ## Design rationale
 
@@ -126,7 +152,7 @@ gives every library the same shape, so the engine compiles, caches, and gates
 them identically regardless of whether the work happens in-process or in a
 subprocess.
 
-**Collection-scoped checks re-scan the whole collection.** A uniqueness or
+**File-set checks re-scan the whole collection when attached to a collection.** A uniqueness or
 required-index verdict is only correct against every item, so these checks run a
 second pass over the full collection even under a single-item selector. The
 trade is that `katalyst check notes/one.md` does more work than its name
@@ -156,8 +182,9 @@ real out-of-process library exists.
    descriptor, and generated docs read the same registry as the engine.
 2. **Family and library stay separate.** Family describes the data a check
    reads; library describes the provider that runs it.
-3. **Collection-scoped checks see the whole collection.** A selector may narrow
-   output, but a collection-level verdict still needs the full sibling set.
+3. **Collection-attached file-set checks see the whole collection.** A selector
+   may narrow output, but a collection-level verdict still needs the full
+   sibling set.
 
 ## See also
 
diff --git a/docs/content/how-to/configure-rules.md b/docs/content/how-to/configure-rules.md
index 30f9499..21c66ed 100644
--- a/docs/content/how-to/configure-rules.md
+++ b/docs/content/how-to/configure-rules.md
@@ -8,6 +8,32 @@ weight = 10
 You have a directory of markdown files and want Katalyst to enforce checks on
 them. This guide adds a collection and attaches checks to it.
 
+## Start before collections exist
+
+For early cleanup, attach checks directly to a filesystem base. These checks
+run with `katalyst check` even when `collections: {}` is still empty:
+
+```yaml
+# .katalyst/bases/local.yaml
+type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs/content
+    include: ["**/*.md"]
+    parseFailures: warning
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+      - kind: filesystem_unmatched_files
+collections: {}
+```
+
+Use `parseFailures: warning` while onboarding a messy tree. Switch back to the
+default `error` once malformed frontmatter should fail CI. Filesystem checks are
+project-wide for now: no-selector `katalyst check` runs them, while
+`katalyst check posts` runs only collection-attached checks.
+
 ## 1. Point a collection at the directory
 
 Collections are declared inside a base. In a fresh project that is
diff --git a/docs/content/reference/check-types/_index.md b/docs/content/reference/check-types/_index.md
index 76c54c2..b0bfe2f 100644
--- a/docs/content/reference/check-types/_index.md
+++ b/docs/content/reference/check-types/_index.md
@@ -53,6 +53,7 @@ File-system check types validate filename and path conventions for items.
 - [Path depth]({{< relref "file-system/path-depth.md" >}}): Bound directory nesting relative to the collection root.
 - [Referenced files exist]({{< relref "file-system/referenced-files-exist.md" >}}): Require path-valued frontmatter fields to resolve to real files.
 - [Unique filename]({{< relref "file-system/unique-filename.md" >}}): Require that no two items in the collection share a basename.
+- [Unmatched files]({{< relref "file-system/unmatched-files.md" >}}): Report regular files under a filesystem scope that match neither include nor exclude patterns.
 
 ## Plain text
 
diff --git a/docs/content/reference/check-types/file-system/_index.md b/docs/content/reference/check-types/file-system/_index.md
index cea037d..f57e22a 100644
--- a/docs/content/reference/check-types/file-system/_index.md
+++ b/docs/content/reference/check-types/file-system/_index.md
@@ -24,3 +24,4 @@ Check types in this family:
 - [Path depth]({{< relref "path-depth.md" >}}): Bound directory nesting relative to the collection root.
 - [Referenced files exist]({{< relref "referenced-files-exist.md" >}}): Require path-valued frontmatter fields to resolve to real files.
 - [Unique filename]({{< relref "unique-filename.md" >}}): Require that no two items in the collection share a basename.
+- [Unmatched files]({{< relref "unmatched-files.md" >}}): Report regular files under a filesystem scope that match neither include nor exclude patterns.
diff --git a/docs/content/reference/check-types/file-system/extension-in.md b/docs/content/reference/check-types/file-system/extension-in.md
index 7237996..5f7f964 100644
--- a/docs/content/reference/check-types/file-system/extension-in.md
+++ b/docs/content/reference/check-types/file-system/extension-in.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/extension-in/"]
 
 `kind: filesystem_extension_in`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Allow only specific file extensions.
diff --git a/docs/content/reference/check-types/file-system/index-file-required.md b/docs/content/reference/check-types/file-system/index-file-required.md
index 1bab2e9..fdceff0 100644
--- a/docs/content/reference/check-types/file-system/index-file-required.md
+++ b/docs/content/reference/check-types/file-system/index-file-required.md
@@ -12,6 +12,8 @@ aliases = ["/reference/rules/file-system/index-file-required/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require that every directory containing items has an index file.
diff --git a/docs/content/reference/check-types/file-system/name-affix.md b/docs/content/reference/check-types/file-system/name-affix.md
index bb78de6..52b82e2 100644
--- a/docs/content/reference/check-types/file-system/name-affix.md
+++ b/docs/content/reference/check-types/file-system/name-affix.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/name-affix/"]
 
 `kind: filesystem_name_affix`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require a name to start with a prefix and/or end with a suffix.
diff --git a/docs/content/reference/check-types/file-system/name-case.md b/docs/content/reference/check-types/file-system/name-case.md
index 13a8b01..1ec5137 100644
--- a/docs/content/reference/check-types/file-system/name-case.md
+++ b/docs/content/reference/check-types/file-system/name-case.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/name-case/"]
 
 `kind: filesystem_name_case`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require a name (or path segments) to follow a case style.
diff --git a/docs/content/reference/check-types/file-system/name-length.md b/docs/content/reference/check-types/file-system/name-length.md
index 8d1e802..6f7b59b 100644
--- a/docs/content/reference/check-types/file-system/name-length.md
+++ b/docs/content/reference/check-types/file-system/name-length.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/name-length/"]
 
 `kind: filesystem_name_length`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Bound the character length of a name.
diff --git a/docs/content/reference/check-types/file-system/name-matches-field.md b/docs/content/reference/check-types/file-system/name-matches-field.md
index 882f4bb..8b47334 100644
--- a/docs/content/reference/check-types/file-system/name-matches-field.md
+++ b/docs/content/reference/check-types/file-system/name-matches-field.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/name-matches-field/"]
 
 `kind: filesystem_name_matches_field`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require a name to equal a frontmatter field, optionally slugified.
diff --git a/docs/content/reference/check-types/file-system/name-regex.md b/docs/content/reference/check-types/file-system/name-regex.md
index 25c1842..0e89530 100644
--- a/docs/content/reference/check-types/file-system/name-regex.md
+++ b/docs/content/reference/check-types/file-system/name-regex.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/name-regex/"]
 
 `kind: filesystem_name_regex`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require a name to match a regular expression (anchored).
diff --git a/docs/content/reference/check-types/file-system/parent-dir-in.md b/docs/content/reference/check-types/file-system/parent-dir-in.md
index be4172b..dce4578 100644
--- a/docs/content/reference/check-types/file-system/parent-dir-in.md
+++ b/docs/content/reference/check-types/file-system/parent-dir-in.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/parent-dir-in/"]
 
 `kind: filesystem_parent_dir_in`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require that the file's parent directory name is in an allowed set.
diff --git a/docs/content/reference/check-types/file-system/parent-dir-matches-field.md b/docs/content/reference/check-types/file-system/parent-dir-matches-field.md
index 91c3d70..cf90353 100644
--- a/docs/content/reference/check-types/file-system/parent-dir-matches-field.md
+++ b/docs/content/reference/check-types/file-system/parent-dir-matches-field.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/parent-dir-matches-field/"]
 
 `kind: filesystem_parent_dir_matches_field`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require the parent directory name to equal a frontmatter field.
diff --git a/docs/content/reference/check-types/file-system/path-charset.md b/docs/content/reference/check-types/file-system/path-charset.md
index 918ae68..b37dfa3 100644
--- a/docs/content/reference/check-types/file-system/path-charset.md
+++ b/docs/content/reference/check-types/file-system/path-charset.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/path-charset/"]
 
 `kind: filesystem_path_charset`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Constrain the characters allowed in the item's path.
diff --git a/docs/content/reference/check-types/file-system/path-depth.md b/docs/content/reference/check-types/file-system/path-depth.md
index 5503006..256c53a 100644
--- a/docs/content/reference/check-types/file-system/path-depth.md
+++ b/docs/content/reference/check-types/file-system/path-depth.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/path-depth/"]
 
 `kind: filesystem_path_depth`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Bound directory nesting relative to the collection root.
diff --git a/docs/content/reference/check-types/file-system/referenced-files-exist.md b/docs/content/reference/check-types/file-system/referenced-files-exist.md
index 7d4dd9f..6d9915e 100644
--- a/docs/content/reference/check-types/file-system/referenced-files-exist.md
+++ b/docs/content/reference/check-types/file-system/referenced-files-exist.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/file-system/referenced-files-exist/"]
 
 `kind: filesystem_referenced_files_exist`
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require path-valued frontmatter fields to resolve to real files.
diff --git a/docs/content/reference/check-types/file-system/unique-filename.md b/docs/content/reference/check-types/file-system/unique-filename.md
index 9f68e39..00c6900 100644
--- a/docs/content/reference/check-types/file-system/unique-filename.md
+++ b/docs/content/reference/check-types/file-system/unique-filename.md
@@ -12,6 +12,8 @@ aliases = ["/reference/rules/file-system/unique-filename/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require that no two items in the collection share a basename.
diff --git a/docs/content/reference/check-types/file-system/unmatched-files.md b/docs/content/reference/check-types/file-system/unmatched-files.md
new file mode 100644
index 0000000..4fbd582
--- /dev/null
+++ b/docs/content/reference/check-types/file-system/unmatched-files.md
@@ -0,0 +1,30 @@
++++
+title = "Unmatched files"
+weight = 140
+aliases = ["/reference/rules/file-system/unmatched-files/"]
++++
+
+<!-- GENERATED by cmd/gendocs from internal/checks/registry.go. Do not edit by hand; run `make docs-gen`. -->
+
+## Check type ID
+
+`kind: filesystem_unmatched_files`
+
+**Scope:** collection, runs once per collection over all its items.
+
+**Targets:** filesystem.
+
+## Purpose
+
+Report regular files under a filesystem scope that match neither include nor exclude patterns.
+
+## Example
+
+```yaml
+filesystemChecks:
+  - path: docs
+    include: ["**/*.md"]
+    exclude: ["**/_generated/**"]
+    checks:
+      - kind: filesystem_unmatched_files
+```
diff --git a/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md b/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md
index 458cf59..54b0d97 100644
--- a/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md
+++ b/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/code-fence-language-required/"]
 
 `kind: markdown_code_fence_language_required`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require that opening fenced code blocks include a language tag.
diff --git a/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md b/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md
index 5e95d65..7825b74 100644
--- a/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md
+++ b/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/no-heading-level-jumps/"]
 
 `kind: markdown_no_heading_level_jumps`
 
+**Targets:** collection.
+
 ## Purpose
 
 Disallow jumps larger than one heading level (for example `H1 -> H3`).
diff --git a/docs/content/reference/check-types/markdown-body-text/required-section.md b/docs/content/reference/check-types/markdown-body-text/required-section.md
index 4040600..f3c6f19 100644
--- a/docs/content/reference/check-types/markdown-body-text/required-section.md
+++ b/docs/content/reference/check-types/markdown-body-text/required-section.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/required-section/"]
 
 `kind: markdown_required_section`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require that a heading with specific text exists somewhere in the body.
diff --git a/docs/content/reference/check-types/markdown-body-text/requires-h1.md b/docs/content/reference/check-types/markdown-body-text/requires-h1.md
index df57b18..40d4d97 100644
--- a/docs/content/reference/check-types/markdown-body-text/requires-h1.md
+++ b/docs/content/reference/check-types/markdown-body-text/requires-h1.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/requires-h1/"]
 
 `kind: markdown_requires_h1`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require at least one H1 heading in the markdown body.
diff --git a/docs/content/reference/check-types/markdown-body-text/single-h1.md b/docs/content/reference/check-types/markdown-body-text/single-h1.md
index 423102f..b54132f 100644
--- a/docs/content/reference/check-types/markdown-body-text/single-h1.md
+++ b/docs/content/reference/check-types/markdown-body-text/single-h1.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/single-h1/"]
 
 `kind: markdown_single_h1`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require that the markdown body contains at most one H1 heading.
diff --git a/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md b/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md
index ece9945..e235915 100644
--- a/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md
+++ b/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/title-matches-h1/"]
 
 `kind: markdown_title_matches_h1`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require a frontmatter field to match the first H1 heading in the body.
diff --git a/docs/content/reference/check-types/markdown-body-text/writing-tells.md b/docs/content/reference/check-types/markdown-body-text/writing-tells.md
index e8dccca..b994bb4 100644
--- a/docs/content/reference/check-types/markdown-body-text/writing-tells.md
+++ b/docs/content/reference/check-types/markdown-body-text/writing-tells.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/markdown-body-text/writing-tells/"]
 
 `kind: markdown_writing_tells`
 
+**Targets:** collection.
+
 **Severity:** warning, reported for review; never fails a run.
 
 ## Purpose
diff --git a/docs/content/reference/check-types/plain-text/denylist.md b/docs/content/reference/check-types/plain-text/denylist.md
index 49bb8b4..7cdabb1 100644
--- a/docs/content/reference/check-types/plain-text/denylist.md
+++ b/docs/content/reference/check-types/plain-text/denylist.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/plain-text/denylist/"]
 
 `kind: text_denylist`
 
+**Targets:** collection.
+
 ## Purpose
 
 Forbid any of a list of literal substrings in the body text.
diff --git a/docs/content/reference/check-types/plain-text/forbids.md b/docs/content/reference/check-types/plain-text/forbids.md
index 7aca04b..e35953e 100644
--- a/docs/content/reference/check-types/plain-text/forbids.md
+++ b/docs/content/reference/check-types/plain-text/forbids.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/plain-text/forbids/"]
 
 `kind: text_forbids`
 
+**Targets:** collection.
+
 ## Purpose
 
 Forbid a regular expression from appearing in the body text.
diff --git a/docs/content/reference/check-types/plain-text/requires.md b/docs/content/reference/check-types/plain-text/requires.md
index 8cfa38a..e2a5ea7 100644
--- a/docs/content/reference/check-types/plain-text/requires.md
+++ b/docs/content/reference/check-types/plain-text/requires.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/plain-text/requires/"]
 
 `kind: text_requires`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require a regular expression to appear in the body text.
diff --git a/docs/content/reference/check-types/structured-object/field-enum.md b/docs/content/reference/check-types/structured-object/field-enum.md
index f28a17c..d02e975 100644
--- a/docs/content/reference/check-types/structured-object/field-enum.md
+++ b/docs/content/reference/check-types/structured-object/field-enum.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/field-enum/"]
 
 `kind: object_field_enum`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require that a field is one of a fixed set of values.
diff --git a/docs/content/reference/check-types/structured-object/field-type.md b/docs/content/reference/check-types/structured-object/field-type.md
index ca13f4a..6ed67f3 100644
--- a/docs/content/reference/check-types/structured-object/field-type.md
+++ b/docs/content/reference/check-types/structured-object/field-type.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/field-type/"]
 
 `kind: object_field_type`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require that a frontmatter field has a specific type.
diff --git a/docs/content/reference/check-types/structured-object/number-range.md b/docs/content/reference/check-types/structured-object/number-range.md
index 29d12f3..5f44797 100644
--- a/docs/content/reference/check-types/structured-object/number-range.md
+++ b/docs/content/reference/check-types/structured-object/number-range.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/number-range/"]
 
 `kind: object_number_range`
 
+**Targets:** collection.
+
 ## Purpose
 
 Constrain a numeric field to a minimum and/or maximum value.
diff --git a/docs/content/reference/check-types/structured-object/object.md b/docs/content/reference/check-types/structured-object/object.md
index bb3cbe9..ceaef2e 100644
--- a/docs/content/reference/check-types/structured-object/object.md
+++ b/docs/content/reference/check-types/structured-object/object.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/object/"]
 
 `kind: object`
 
+**Targets:** collection.
+
 ## Purpose
 
 Validate frontmatter metadata against a named JSON Schema from `schemas:`.
diff --git a/docs/content/reference/check-types/structured-object/required-field.md b/docs/content/reference/check-types/structured-object/required-field.md
index 2496c1d..bd258f8 100644
--- a/docs/content/reference/check-types/structured-object/required-field.md
+++ b/docs/content/reference/check-types/structured-object/required-field.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/required-field/"]
 
 `kind: object_required_field`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require that a frontmatter field exists.
diff --git a/docs/content/reference/check-types/structured-object/sentence-case.md b/docs/content/reference/check-types/structured-object/sentence-case.md
index d832467..c78d328 100644
--- a/docs/content/reference/check-types/structured-object/sentence-case.md
+++ b/docs/content/reference/check-types/structured-object/sentence-case.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/sentence-case/"]
 
 `kind: object_sentence_case`
 
+**Targets:** collection.
+
 ## Purpose
 
 Require a string field to read as sentence case, not Title Case.
diff --git a/docs/content/reference/check-types/structured-object/string-length.md b/docs/content/reference/check-types/structured-object/string-length.md
index 5e06d77..e48e57b 100644
--- a/docs/content/reference/check-types/structured-object/string-length.md
+++ b/docs/content/reference/check-types/structured-object/string-length.md
@@ -10,6 +10,8 @@ aliases = ["/reference/rules/structured-object/string-length/"]
 
 `kind: object_string_length`
 
+**Targets:** collection.
+
 ## Purpose
 
 Constrain the minimum and/or maximum length of a string field.
diff --git a/docs/content/reference/check-types/structured-object/unique-field.md b/docs/content/reference/check-types/structured-object/unique-field.md
index 0f423ba..bb644e8 100644
--- a/docs/content/reference/check-types/structured-object/unique-field.md
+++ b/docs/content/reference/check-types/structured-object/unique-field.md
@@ -12,6 +12,8 @@ aliases = ["/reference/rules/structured-object/unique-field/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
+**Targets:** collection, filesystem.
+
 ## Purpose
 
 Require that no two items share a value for a frontmatter field.
diff --git a/docs/content/reference/configs/bases.md b/docs/content/reference/configs/bases.md
index 1dcbf40..d7d64af 100644
--- a/docs/content/reference/configs/bases.md
+++ b/docs/content/reference/configs/bases.md
@@ -15,6 +15,7 @@ filename stem. There is no implicit base; `katalyst init` writes a default
 | `type` | no | `filesystem` | Backend kind: `filesystem` or `sqlite`. |
 | `root` | no | `.` | Base root directory, relative to the repo root. Collection paths resolve against it. |
 | `path` | for `sqlite` | - | SQLite database path, relative to the repo root. Alias for `root` on SQLite bases. |
+| `filesystemChecks` | no | - | Filesystem-attached checks for raw files under a filesystem base. Valid only when `type: filesystem`. |
 | `collections` | no | - | Map of collection name -> definition. See [Collections]({{< relref "collections.md" >}}). |
 
 ```yaml
@@ -32,6 +33,36 @@ collections:
 Collection names are unique across the whole project (selectors are
 `<collection>/<item>`, with no base qualifier).
 
+Filesystem bases may also declare `filesystemChecks` for rules that run before
+or beside collections. Each entry selects files under the base root, then runs
+checks whose descriptors support the `filesystem` target:
+
+```yaml
+# .katalyst/bases/local.yaml
+type: filesystem
+root: .
+filesystemChecks:
+  - name: docs
+    path: docs/content
+    include: ["**/*.md"]
+    exclude: ["**/_generated/**"]
+    parseFailures: error
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+      - kind: filesystem_unmatched_files
+collections: {}
+```
+
+| Key | Required | Default | Meaning |
+|---|---|---|---|
+| `name` | no | `path` | Diagnostic label and future selector handle. |
+| `path` | no | `.` | Scope root, relative to the base root. |
+| `include` | yes | - | Glob patterns relative to `path`; selected files match at least one. |
+| `exclude` | no | `[]` | Glob patterns removed from the selected set and from unmatched-file reporting. |
+| `parseFailures` | no | `error` | `error` fails the run; `warning` reports advisory parse failures when a check needs document data. |
+| `checks` | yes | - | Check instances to run against selected files or the selected file set. |
+
 SQLite bases use one table per collection. Each row is one item:
 
 ```yaml
diff --git a/docs/content/reference/configs/checks.md b/docs/content/reference/configs/checks.md
index a788c60..e530586 100644
--- a/docs/content/reference/configs/checks.md
+++ b/docs/content/reference/configs/checks.md
@@ -5,8 +5,11 @@ weight = 50
 
 # Checks
 
-Each entry in a collection's `checks:` list has a `kind` and the keys that
-check type requires. Every check type is documented one per page in the
+Each check instance has a `kind` and the keys that check type requires. A check
+instance can be attached to a collection under `collections.<name>.checks`, or
+to a raw filesystem scope under `filesystemChecks[].checks` when the check
+type supports the `filesystem` target. Every check type is documented one per
+page in the
 [check types reference]({{< relref "../check-types/_index.md" >}}):
 
 ```yaml
@@ -20,6 +23,48 @@ checks:
   - kind: filesystem_name_matches_field
 ```
 
+## Attachment targets
+
+Collection-attached checks run after a file belongs to a collection. They can
+use collection schemas, variants, item selectors, and collection-wide sibling
+sets:
+
+```yaml
+collections:
+  posts:
+    path: content/posts
+    checks:
+      - kind: markdown_requires_h1
+      - kind: filesystem_name_case
+        style: kebab
+```
+
+Filesystem-attached checks run from filesystem base config. They select files
+with `include` and `exclude` globs and do not require collections to exist:
+
+```yaml
+filesystemChecks:
+  - name: docs
+    path: docs/content
+    include: ["**/*.md"]
+    parseFailures: warning
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+      - kind: filesystem_name_matches_field
+        field: title
+```
+
+`katalyst check` with no selector runs filesystem scopes first, then collection
+checks. `katalyst check <collection>` and `katalyst check <collection>/<item>`
+run collection checks only. Filesystem scopes reject check types that do not
+list `filesystem` in their supported targets.
+
+Document-aware filesystem checks parse selected files only when needed.
+`parseFailures: error` is the default and fails the run on parse errors.
+`parseFailures: warning` reports the parse error as advisory and skips
+document-aware checks for that file.
+
 ## Text rules
 
 The `text_*` check types lint the item **body** as raw text, independent of
diff --git a/docs/content/reference/glossary.md b/docs/content/reference/glossary.md
index 485fb28..11cb621 100644
--- a/docs/content/reference/glossary.md
+++ b/docs/content/reference/glossary.md
@@ -20,10 +20,11 @@ how each term maps onto today's code is documented in the per-package
 | **BaseType** | A known backend kind capable of holding content Katalyst can operate on (`filesystem` and `sqlite` today; `postgresql`, `mongodb`, and others later). |
 | **Body** | Everything after the closing frontmatter fence. Preserved verbatim except by `fix`. |
 | **Check** | Shorthand for a check instance when context is unambiguous. |
-| **Check instance** | One configured check attached to a collection: a check type plus its arguments (one YAML object under `checks:`). It runs against each item (object, markdown, or filesystem family). |
-| **Check type** | The reusable definition of a constraint: one entry in katalyst's check registry (`object_required_field`, `markdown_single_h1`, ...), selected by its `kind:` id. `katalyst check-types list` lists them. |
+| **Check instance** | One configured check: a check type plus its arguments. It is attached either to a collection under `checks:` or to a filesystem scope under `filesystemChecks[].checks`. |
+| **Check type** | The reusable definition of a constraint: one entry in katalyst's check registry (`object_required_field`, `markdown_single_h1`, ...), selected by its `kind:` id. `katalyst check-types list` lists them, including their supported attachment targets. |
 | **CheckLibrary** | The provider behind a check type. Native libraries (`filesystem`, `plaintext`, `markdownbodytext`, `structuredobject`) wrap hand-written checks; schema-backed libraries (`json-schema`, Vale next) compile a named schema and run items against it, and report their own availability. A library is provenance, orthogonal to the source-data family (`structuredObject`, `markdownBodyText`, `fileSystem`, `plainText`) the check reads. |
 | **Collection** | A group of items that share structure: a directory of similar files, a relational table, a Mongo collection, or a family of API resources. Collections own checks and are addressed by name. |
+| **CollectionCheck** | A check instance attached to a collection definition. CollectionChecks can run per item or once over the collection's full item set. |
 | **Collection layer** | Inspectors that profile a configured collection's items, addressed by domain identity (collection + item id) and probing through the same substrate the checks use. |
 | **Collection-scoped check** | A check type that runs once per collection over all its items (e.g. `filesystem_unique_filename`), rather than per item. It re-scans the full collection even under a single-item selector. |
 | **Collection mapping** | The two-way mapping from a base instance's contents to collections and items. Yields one or more collections; filesystem and SQLite mappings are implemented today. Implemented by `CollectionDefinition` in code. |
@@ -32,6 +33,9 @@ how each term maps onto today's code is documented in the per-package
 | **Document** | The markdown file-form of an **Item**: a parsed markdown file (frontmatter metadata + body + a line map). Use it where parsing or the on-disk file is the subject; elsewhere prefer **Item**. |
 | **Evidence** | The structured result of one inspector: counts and distributions with the unit count `n` as denominator. Never a recommendation or verdict. |
 | **Field** | A key in an item's structured object (its frontmatter map). A field is an **Attribute**; a filename is an attribute but not a field. The term used wherever object or frontmatter keys are meant (`object_field_type`, `name_matches_field`). |
+| **FileCheck** | A runtime check that runs once per file. Collection-attached item checks and filesystem-attached per-file checks both use this shape. |
+| **FileSetCheck** | A runtime check that runs once over a selected set of files, such as unique filename or unmatched-file checks. |
+| **FilesystemCheck** | A check instance attached to a filesystem scope under a filesystem base's `filesystemChecks` list. It can run before collections exist. |
 | **Frontmatter** | The on-disk metadata block at the top of a markdown file, in YAML (`---`), TOML (`+++`), or JSON (`{ … }`). |
 | **Inspector** | A read-only operation that measures content and returns evidence. The descriptive dual of a check: a check asserts a predicate, an inspector reports the distribution. Inspectors come in two layers. |
 | **Item** | The unit of data in a collection, addressed by a selector and operated on by `check`, `fix`, and the `item` subcommands. In the filesystem backend an item is one file matching the collection's pattern, its id the filename stem; its markdown file-form is a **Document**. |
@@ -49,7 +53,7 @@ how each term maps onto today's code is documented in the per-package
 | **Selector** | How a command names what to operate on: nothing (whole project), `<collection>`, or `<collection>/<item>`. |
 | **Scope** | The level an operation or backend mapping applies to: item, collection, project, or across collections. In a base, scope answers whether one matched source unit becomes an item or a collection. |
 | **Span** | The slice of body text a text rule is evaluated against, chosen by its `target`: the whole `body`, each `line`, the `first-line`, or `matched-lines` (lines matching a `select` regex). |
-| **Target** | The slice of a path a filesystem name/path check type tests: `filename`, `filename-ext`, `parent-dir`, or `path-segments` (every directory segment plus the basename). For a text rule, the slice of body it tests, see Span. |
+| **Target** | Either an attachment target (`collection` or `filesystem`) in check descriptors, or the slice a rule tests in a specific family. For a filesystem name/path check, `target` can be `filename`, `filename-ext`, `parent-dir`, or `path-segments`; for a text rule, see Span. |
 | **Text rule** | A `text_*` check (`text_requires`, `text_forbids`, `text_denylist`) that tests the body as raw text, a regex or a literal denylist, independent of markdown structure. Applies to plain-text items too. |
 | **Validation result** | The product of running an item's checks: either `path: OK`, or a flat list of violations. |
 | **Variant** | A discriminated check group inside a collection (one entry of `variants:`): a `when` discriminator plus the schema/checks added for items that match it. An item runs the base checks plus the first matching variant's. |
@@ -58,8 +62,8 @@ how each term maps onto today's code is documented in the per-package
 ## Usage notes
 
 - A **check type** is the definition; a **check instance** is that check type
-  configured in a collection and run against a specific item, and a
-  **violation** is a check that failed. The [check types
+  configured at an attachment target, and a **violation** is a check that
+  failed. The [check types
   reference]({{< relref "check-types/_index.md" >}}) and `katalyst check-types
   list` enumerate check types.
 - Prefer **schema** for what users author. The runtime check is the `object`
diff --git a/internal/checks/AGENTS.md b/internal/checks/AGENTS.md
index 0b2a61b..aa96b64 100644
--- a/internal/checks/AGENTS.md
+++ b/internal/checks/AGENTS.md
@@ -4,8 +4,8 @@ The check engine: the check types Katalyst ships, the libraries that run them,
 and the violations they produce.
 
 **Architecture and design rationale** - the model (check type vs. instance,
-family vs. library, scope), check libraries, how a check runs, and the
-trade-offs - live in the
+family vs. library vs. attachment target vs. runtime granularity), check
+libraries, how a check runs, and the trade-offs - live in the
 [How checks work](../../docs/content/deep-dives/domain-model/checks.md) deep-dive, which is
 the source of truth. The per-type catalog is the generated
 [check-types reference](../../docs/content/reference/check-types/), and the
@@ -18,6 +18,13 @@ local code conventions.
   it through the package's `register` helper (in `library.go`). To add one, see
   the [add-katalyst-check-type](../../.cursor/skills/add-katalyst-check-type/SKILL.md)
   skill.
+- Set descriptor `Targets` for every check that can attach outside a
+  collection. Empty targets mean collection-only during migration. Use
+  `checks.TargetCollection` and `checks.TargetFilesystem` rather than string
+  literals.
+- Set descriptor `NeedsDocument` when a check reads frontmatter, markdown body
+  text, or source line maps. Filesystem-attached checks use it to parse lazily
+  and to apply `parseFailures`.
 - Family packages (`structuredobject/`, `markdownbodytext/`, `filesystem/`,
   `plaintext/`) import the core `checks` package, never the reverse. Callers
   wire every family in by blank-importing `internal/checks/all`.
diff --git a/internal/checks/checks.go b/internal/checks/checks.go
index 951f0e6..d5c4875 100644
--- a/internal/checks/checks.go
+++ b/internal/checks/checks.go
@@ -11,8 +11,8 @@ package checks
 
 import "github.com/abegong/katalyst/internal/codec/markdownbodytext"
 
-// Context carries all data a check may need.
-type Context struct {
+// FileContext carries all data a file check may need.
+type FileContext struct {
 	FilePath string
 	// CollectionRoot is the absolute directory of the item's collection.
 	// Path/filename targets that span directories (path-segments, path
@@ -23,6 +23,9 @@ type Context struct {
 	Meta           map[string]any
 }
 
+// Context is the historical name for FileContext.
+type Context = FileContext
+
 // Severity classifies how serious a violation is. The zero value is
 // SeverityError, so any check that does not set it keeps failing the run;
 // SeverityWarning is advisory, it is reported but never changes the exit
diff --git a/internal/checks/collection.go b/internal/checks/collection.go
index 7c3ec33..feeccd9 100644
--- a/internal/checks/collection.go
+++ b/internal/checks/collection.go
@@ -12,19 +12,28 @@ type ItemContext struct {
 	Meta     map[string]any
 }
 
-// CollectionContext carries every item in a collection, for checks that
-// reason across siblings (uniqueness, required index files).
-type CollectionContext struct {
-	Root  string
-	Items []ItemContext
+// FileSetContext carries every selected file in a set, for checks that reason
+// across siblings (uniqueness, required index files, unmatched files).
+type FileSetContext struct {
+	Root      string
+	Items     []ItemContext
+	Unmatched []string
+	Include   []string
+	Exclude   []string
 }
 
+// CollectionContext is the historical name for FileSetContext.
+type CollectionContext = FileSetContext
+
 // CollectionCheck validates a concern across all items in a collection. It
 // runs once per collection, after the per-item pass.
 type CollectionCheck interface {
 	RunCollection(ctx CollectionContext) []Violation
 }
 
+// FileSetCheck is the product-facing name for a set-level runtime check.
+type FileSetCheck = CollectionCheck
+
 // CollisionViolations emits one violation per group of two or more paths,
 // naming all colliding files. Groups and paths are sorted for determinism. It
 // is the shared helper behind the uniqueness checks (unique_filename in the
@@ -58,3 +67,8 @@ func RunCollectionAll(ctx CollectionContext, list []CollectionCheck) []Violation
 	}
 	return out
 }
+
+// RunFileSetAll runs every file-set check and flattens the violations.
+func RunFileSetAll(ctx FileSetContext, list []FileSetCheck) []Violation {
+	return RunCollectionAll(ctx, list)
+}
diff --git a/internal/checks/config.go b/internal/checks/config.go
new file mode 100644
index 0000000..69795ba
--- /dev/null
+++ b/internal/checks/config.go
@@ -0,0 +1,130 @@
+package checks
+
+import (
+	"fmt"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// RawCheck mirrors one `checks:` entry. The struct fields exist so a misspelled
+// key fails YAML's known-field validation; the retained node is what a check
+// type's own parser decodes for its real args.
+type RawCheck struct {
+	Kind      string   `yaml:"kind"`
+	Schema    string   `yaml:"schema"`
+	Field     string   `yaml:"field"`
+	Type      string   `yaml:"type"`
+	Value     string   `yaml:"value"`
+	Values    []string `yaml:"values"`
+	Min       *float64 `yaml:"min"`
+	Max       *float64 `yaml:"max"`
+	MinLength int      `yaml:"min_length"`
+	MaxLength int      `yaml:"max_length"`
+	Heading   string   `yaml:"heading"`
+	Style     string   `yaml:"style"`
+	Target    string   `yaml:"target"`
+	Transform string   `yaml:"transform"`
+	Prefix    string   `yaml:"prefix"`
+	Suffix    string   `yaml:"suffix"`
+	Allow     []string `yaml:"allow"`
+	Deny      []string `yaml:"deny"`
+	Pattern   string   `yaml:"pattern"`
+	Fields    []string `yaml:"fields"`
+	Name      string   `yaml:"name"`
+	Match     string   `yaml:"match"`
+	Select    string   `yaml:"select"`
+	Fix       string   `yaml:"fix"`
+
+	node *yaml.Node
+}
+
+var rawCheckKeys = map[string]bool{
+	"kind": true, "schema": true, "field": true, "type": true,
+	"value": true, "values": true, "min": true, "max": true,
+	"min_length": true, "max_length": true, "heading": true,
+	"style": true, "target": true, "transform": true,
+	"prefix": true, "suffix": true, "allow": true, "deny": true,
+	"pattern": true, "fields": true, "name": true, "match": true,
+	"select": true, "fix": true,
+}
+
+// UnmarshalYAML decodes the entry's fields and stashes the raw node, so the
+// node can travel to a check type's own parser.
+func (rc *RawCheck) UnmarshalYAML(value *yaml.Node) error {
+	if value.Kind != yaml.MappingNode {
+		return fmt.Errorf("invalid check: expected a mapping")
+	}
+	for i := 0; i < len(value.Content); i += 2 {
+		key := value.Content[i].Value
+		if !rawCheckKeys[key] {
+			return fmt.Errorf("unknown check key %q", key)
+		}
+	}
+	type plain RawCheck
+	var p plain
+	if err := value.Decode(&p); err != nil {
+		return err
+	}
+	*rc = RawCheck(p)
+	rc.node = value
+	return nil
+}
+
+// BuildConfiguredInput carries the shared pieces needed to turn raw config
+// into validated configured checks.
+type BuildConfiguredInput struct {
+	ErrorContext string
+	Schema       string
+	Raw          []RawCheck
+	SchemaKnown  func(string) bool
+	Target       string
+	AllowObject  bool
+}
+
+// BuildConfigured folds an optional schema name into a leading object check
+// and parses all raw checks through the registry.
+func BuildConfigured(in BuildConfiguredInput) ([]ConfiguredCheck, error) {
+	target := in.Target
+	if target == "" {
+		target = TargetCollection
+	}
+	out := make([]ConfiguredCheck, 0, len(in.Raw)+1)
+	if in.Schema != "" {
+		if !in.AllowObject {
+			return nil, fmt.Errorf("%s: schema is not supported for %s checks", in.ErrorContext, target)
+		}
+		if in.SchemaKnown != nil && !in.SchemaKnown(in.Schema) {
+			return nil, fmt.Errorf("%s: unknown schema %q", in.ErrorContext, in.Schema)
+		}
+		out = append(out, ConfiguredCheck{Kind: CheckObject, Schema: in.Schema})
+	}
+	for j, raw := range in.Raw {
+		kind := CheckType(strings.TrimSpace(raw.Kind))
+		if kind == CheckObject {
+			if !in.AllowObject {
+				return nil, fmt.Errorf("%s: checks[%d]: object check is not supported for %s checks", in.ErrorContext, j, target)
+			}
+			if raw.Schema == "" {
+				return nil, fmt.Errorf("%s: checks[%d]: object check requires \"schema\"", in.ErrorContext, j)
+			}
+			if in.SchemaKnown != nil && !in.SchemaKnown(raw.Schema) {
+				return nil, fmt.Errorf("%s: checks[%d]: unknown schema %q", in.ErrorContext, j, raw.Schema)
+			}
+			if raw.Field != "" {
+				return nil, fmt.Errorf("%s: checks[%d]: object check does not support \"field\"", in.ErrorContext, j)
+			}
+			out = append(out, ConfiguredCheck{Kind: CheckObject, Schema: raw.Schema})
+			continue
+		}
+		args, err := Parse(kind, raw.node)
+		if err != nil {
+			return nil, fmt.Errorf("%s: checks[%d]: %w", in.ErrorContext, j, err)
+		}
+		if !SupportsTarget(kind, target) {
+			return nil, fmt.Errorf("%s: checks[%d]: check type %q does not support %s checks", in.ErrorContext, j, kind, target)
+		}
+		out = append(out, ConfiguredCheck{Kind: kind, Args: args})
+	}
+	return out, nil
+}
diff --git a/internal/checks/filesystem/extension_in.go b/internal/checks/filesystem/extension_in.go
index 27eaee1..025d8ae 100644
--- a/internal/checks/filesystem/extension_in.go
+++ b/internal/checks/filesystem/extension_in.go
@@ -39,6 +39,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemExtensionIn,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "extension-in",
 		Title:     "Extension in",
 		Summary:   "Allow only specific file extensions.",
diff --git a/internal/checks/filesystem/index_file_required.go b/internal/checks/filesystem/index_file_required.go
index cc6e8fc..ac0efcf 100644
--- a/internal/checks/filesystem/index_file_required.go
+++ b/internal/checks/filesystem/index_file_required.go
@@ -51,6 +51,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemIndexFileRequired,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "index-file-required",
 		Title:     "Index file required",
 		Summary:   "Require that every directory containing items has an index file.",
diff --git a/internal/checks/filesystem/name_affix.go b/internal/checks/filesystem/name_affix.go
index 525c783..fd59b24 100644
--- a/internal/checks/filesystem/name_affix.go
+++ b/internal/checks/filesystem/name_affix.go
@@ -44,6 +44,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemNameAffix,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "name-affix",
 		Title:     "Name affix",
 		Summary:   "Require a name to start with a prefix and/or end with a suffix.",
diff --git a/internal/checks/filesystem/name_case.go b/internal/checks/filesystem/name_case.go
index 6215a77..e8a7c60 100644
--- a/internal/checks/filesystem/name_case.go
+++ b/internal/checks/filesystem/name_case.go
@@ -61,6 +61,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemNameCase,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "name-case",
 		Title:     "Name case",
 		Summary:   "Require a name (or path segments) to follow a case style.",
diff --git a/internal/checks/filesystem/name_length.go b/internal/checks/filesystem/name_length.go
index 91daa98..e8a2082 100644
--- a/internal/checks/filesystem/name_length.go
+++ b/internal/checks/filesystem/name_length.go
@@ -47,6 +47,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemNameLength,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "name-length",
 		Title:     "Name length",
 		Summary:   "Bound the character length of a name.",
diff --git a/internal/checks/filesystem/name_matches_field.go b/internal/checks/filesystem/name_matches_field.go
index a289c2d..a80ffd7 100644
--- a/internal/checks/filesystem/name_matches_field.go
+++ b/internal/checks/filesystem/name_matches_field.go
@@ -67,11 +67,13 @@ type nameMatchesFieldArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemNameMatchesField,
-		Family:    "fileSystem",
-		Slug:      "name-matches-field",
-		Title:     "Name matches field",
-		Summary:   "Require a name to equal a frontmatter field, optionally slugified.",
+		CheckType:     checks.CheckFilesystemNameMatchesField,
+		Family:        "fileSystem",
+		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
+		NeedsDocument: true,
+		Slug:          "name-matches-field",
+		Title:         "Name matches field",
+		Summary:       "Require a name to equal a frontmatter field, optionally slugified.",
 		Fields: []checks.Field{
 			{Name: "field", Required: false, Default: "slug", Desc: "Frontmatter key compared to the name."},
 			{Name: "transform", Required: false, Default: "none", Desc: "`none` or `slugify` (applied to the field value before comparison)."},
diff --git a/internal/checks/filesystem/name_regex.go b/internal/checks/filesystem/name_regex.go
index 25793db..d03c985 100644
--- a/internal/checks/filesystem/name_regex.go
+++ b/internal/checks/filesystem/name_regex.go
@@ -41,6 +41,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemNameRegex,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "name-regex",
 		Title:     "Name regex",
 		Summary:   "Require a name to match a regular expression (anchored).",
diff --git a/internal/checks/filesystem/parent_dir_in.go b/internal/checks/filesystem/parent_dir_in.go
index 449b070..ad72728 100644
--- a/internal/checks/filesystem/parent_dir_in.go
+++ b/internal/checks/filesystem/parent_dir_in.go
@@ -34,6 +34,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemParentDirIn,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "parent-dir-in",
 		Title:     "Parent directory in",
 		Summary:   "Require that the file's parent directory name is in an allowed set.",
diff --git a/internal/checks/filesystem/parent_dir_matches_field.go b/internal/checks/filesystem/parent_dir_matches_field.go
index 4ef294a..b747f0d 100644
--- a/internal/checks/filesystem/parent_dir_matches_field.go
+++ b/internal/checks/filesystem/parent_dir_matches_field.go
@@ -49,11 +49,13 @@ type parentDirMatchesArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemParentDirMatchesFld,
-		Family:    "fileSystem",
-		Slug:      "parent-dir-matches-field",
-		Title:     "Parent directory matches field",
-		Summary:   "Require the parent directory name to equal a frontmatter field.",
+		CheckType:     checks.CheckFilesystemParentDirMatchesFld,
+		Family:        "fileSystem",
+		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
+		NeedsDocument: true,
+		Slug:          "parent-dir-matches-field",
+		Title:         "Parent directory matches field",
+		Summary:       "Require the parent directory name to equal a frontmatter field.",
 		Fields: []checks.Field{
 			{Name: "field", Required: true, Desc: "Frontmatter key compared to the parent directory name."},
 		},
diff --git a/internal/checks/filesystem/path_charset.go b/internal/checks/filesystem/path_charset.go
index 0a3bcf1..d26f326 100644
--- a/internal/checks/filesystem/path_charset.go
+++ b/internal/checks/filesystem/path_charset.go
@@ -63,6 +63,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemPathCharset,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "path-charset",
 		Title:     "Path charset",
 		Summary:   "Constrain the characters allowed in the item's path.",
diff --git a/internal/checks/filesystem/path_depth.go b/internal/checks/filesystem/path_depth.go
index 62fcf0b..5b33885 100644
--- a/internal/checks/filesystem/path_depth.go
+++ b/internal/checks/filesystem/path_depth.go
@@ -60,6 +60,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemPathDepth,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "path-depth",
 		Title:     "Path depth",
 		Summary:   "Bound directory nesting relative to the collection root.",
diff --git a/internal/checks/filesystem/referenced_files.go b/internal/checks/filesystem/referenced_files.go
index ea1e24b..a5bac98 100644
--- a/internal/checks/filesystem/referenced_files.go
+++ b/internal/checks/filesystem/referenced_files.go
@@ -76,11 +76,13 @@ type referencedFilesArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemReferencedFiles,
-		Family:    "fileSystem",
-		Slug:      "referenced-files-exist",
-		Title:     "Referenced files exist",
-		Summary:   "Require path-valued frontmatter fields to resolve to real files.",
+		CheckType:     checks.CheckFilesystemReferencedFiles,
+		Family:        "fileSystem",
+		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
+		NeedsDocument: true,
+		Slug:          "referenced-files-exist",
+		Title:         "Referenced files exist",
+		Summary:       "Require path-valued frontmatter fields to resolve to real files.",
 		Fields: []checks.Field{
 			{Name: "fields", Required: true, Desc: "Frontmatter keys holding a path (string) or list of paths, resolved relative to the item."},
 		},
diff --git a/internal/checks/filesystem/unique_filename.go b/internal/checks/filesystem/unique_filename.go
index 650fcfa..004d844 100644
--- a/internal/checks/filesystem/unique_filename.go
+++ b/internal/checks/filesystem/unique_filename.go
@@ -26,6 +26,7 @@ func init() {
 	registerParsed(checks.Descriptor{
 		CheckType: checks.CheckFilesystemUniqueFilename,
 		Family:    "fileSystem",
+		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
 		Slug:      "unique-filename",
 		Title:     "Unique filename",
 		Summary:   "Require that no two items in the collection share a basename.",
diff --git a/internal/checks/filesystem/unmatched_files.go b/internal/checks/filesystem/unmatched_files.go
new file mode 100644
index 0000000..2ce13e4
--- /dev/null
+++ b/internal/checks/filesystem/unmatched_files.go
@@ -0,0 +1,50 @@
+package filesystem
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/abegong/katalyst/internal/checks"
+)
+
+// UnmatchedFiles reports files in a filesystem scope that match neither
+// include nor exclude patterns.
+type UnmatchedFiles struct{}
+
+func (UnmatchedFiles) RunCollection(ctx checks.CollectionContext) []checks.Violation {
+	out := make([]checks.Violation, 0, len(ctx.Unmatched))
+	for _, rel := range ctx.Unmatched {
+		out = append(out, checks.Violation{
+			File:    rel,
+			Message: fmt.Sprintf("unmatched file (matches no include pattern %s and no exclude pattern %s)", patternList(ctx.Include), patternList(ctx.Exclude)),
+		})
+	}
+	return out
+}
+
+func patternList(patterns []string) string {
+	if len(patterns) == 0 {
+		return "[]"
+	}
+	return "[" + strings.Join(patterns, ", ") + "]"
+}
+
+func init() {
+	registerParsed(checks.Descriptor{
+		CheckType: checks.CheckFilesystemUnmatchedFiles,
+		Family:    "fileSystem",
+		Targets:   []string{checks.TargetFilesystem},
+		Slug:      "unmatched-files",
+		Title:     "Unmatched files",
+		Summary:   "Report regular files under a filesystem scope that match neither include nor exclude patterns.",
+		Scope:     "collection",
+		ConfigExample: `filesystemChecks:
+  - path: docs
+    include: ["**/*.md"]
+    exclude: ["**/_generated/**"]
+    checks:
+      - kind: filesystem_unmatched_files`,
+	}, checks.NoArgs, nil, func(any) checks.CollectionCheck {
+		return UnmatchedFiles{}
+	})
+}
diff --git a/internal/checks/kinds.go b/internal/checks/kinds.go
index d852e95..c4d61e5 100644
--- a/internal/checks/kinds.go
+++ b/internal/checks/kinds.go
@@ -34,6 +34,7 @@ const (
 	CheckFilesystemUniqueFilename      CheckType = "filesystem_unique_filename"
 	CheckFilesystemUniqueField         CheckType = "filesystem_unique_field"
 	CheckFilesystemIndexFileRequired   CheckType = "filesystem_index_file_required"
+	CheckFilesystemUnmatchedFiles      CheckType = "filesystem_unmatched_files"
 	CheckTextRequires                  CheckType = "text_requires"
 	CheckTextForbids                   CheckType = "text_forbids"
 	CheckTextDenylist                  CheckType = "text_denylist"
diff --git a/internal/checks/registry.go b/internal/checks/registry.go
index 09c3201..635291e 100644
--- a/internal/checks/registry.go
+++ b/internal/checks/registry.go
@@ -59,11 +59,23 @@ type Descriptor struct {
 	// Scope is "collection" for checks that run once per collection over all
 	// its items; empty means an ordinary per-item check.
 	Scope string `json:"scope,omitempty"`
+	// Targets names the config attachment points that accept this check type:
+	// "collection", "filesystem". Empty means collection during migration.
+	Targets []string `json:"targets,omitempty"`
+	// NeedsDocument reports whether this check needs parsed document metadata
+	// or body text. Filesystem scopes use it to avoid parsing for path-only
+	// checks.
+	NeedsDocument bool `json:"needs_document,omitempty"`
 	// Severity is "warning" for checks that emit advisory findings (never
 	// failing the run); empty means the default, "error".
 	Severity string `json:"severity,omitempty"`
 }
 
+const (
+	TargetCollection = "collection"
+	TargetFilesystem = "filesystem"
+)
+
 // Family identifies a check-type family: its id (used in Descriptor.Family and
 // `--family`), its docs-directory slug, and its intro copy.
 type Family struct {
@@ -222,6 +234,37 @@ func DescriptorFor(kind CheckType) (Descriptor, bool) {
 	return registrations[i].desc, true
 }
 
+// DescriptorTargets returns the explicit or migration-default attachment
+// targets for d.
+func DescriptorTargets(d Descriptor) []string {
+	if len(d.Targets) == 0 {
+		return []string{TargetCollection}
+	}
+	out := make([]string, len(d.Targets))
+	copy(out, d.Targets)
+	return out
+}
+
+// SupportsTarget reports whether kind accepts the named attachment target.
+func SupportsTarget(kind CheckType, target string) bool {
+	desc, ok := DescriptorFor(kind)
+	if !ok {
+		return false
+	}
+	for _, t := range DescriptorTargets(desc) {
+		if t == target {
+			return true
+		}
+	}
+	return false
+}
+
+// NeedsDocument reports whether a check needs parsed document data.
+func NeedsDocument(kind CheckType) bool {
+	desc, ok := DescriptorFor(kind)
+	return ok && desc.NeedsDocument
+}
+
 // CollectionScoped reports whether kind runs once per collection (vs. per item).
 func CollectionScoped(kind CheckType) bool {
 	i, ok := byKind[kind]
diff --git a/internal/checks/registry_test.go b/internal/checks/registry_test.go
index 51512b9..6840834 100644
--- a/internal/checks/registry_test.go
+++ b/internal/checks/registry_test.go
@@ -55,3 +55,33 @@ func TestDescriptorLibrary(t *testing.T) {
 		}
 	}
 }
+
+func TestDescriptorTargets(t *testing.T) {
+	if !checks.SupportsTarget(checks.CheckFilesystemNameCase, checks.TargetCollection) {
+		t.Fatalf("filesystem_name_case should support collection checks")
+	}
+	if !checks.SupportsTarget(checks.CheckFilesystemNameCase, checks.TargetFilesystem) {
+		t.Fatalf("filesystem_name_case should support filesystem checks")
+	}
+	if checks.SupportsTarget(checks.CheckMarkdownRequiresH1, checks.TargetFilesystem) {
+		t.Fatalf("markdown_requires_h1 should remain collection-only")
+	}
+	if !checks.SupportsTarget(checks.CheckFilesystemUnmatchedFiles, checks.TargetFilesystem) {
+		t.Fatalf("filesystem_unmatched_files should support filesystem checks")
+	}
+	if checks.SupportsTarget(checks.CheckFilesystemUnmatchedFiles, checks.TargetCollection) {
+		t.Fatalf("filesystem_unmatched_files should not support collection checks")
+	}
+}
+
+func TestDescriptorNeedsDocument(t *testing.T) {
+	if checks.NeedsDocument(checks.CheckFilesystemNameCase) {
+		t.Fatalf("filesystem_name_case should stay path-only")
+	}
+	if !checks.NeedsDocument(checks.CheckFilesystemNameMatchesField) {
+		t.Fatalf("filesystem_name_matches_field should need document metadata")
+	}
+	if !checks.NeedsDocument(checks.CheckFilesystemUniqueField) {
+		t.Fatalf("filesystem_unique_field should need document metadata")
+	}
+}
diff --git a/internal/checks/structuredobject/unique_field.go b/internal/checks/structuredobject/unique_field.go
index 39a9c08..3a4c888 100644
--- a/internal/checks/structuredobject/unique_field.go
+++ b/internal/checks/structuredobject/unique_field.go
@@ -38,12 +38,14 @@ func (c UniqueField) RunCollection(ctx checks.CollectionContext) []checks.Violat
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemUniqueField,
-		Family:    "structuredObject",
-		Slug:      "unique-field",
-		Title:     "Unique field",
-		Summary:   "Require that no two items share a value for a frontmatter field.",
-		Scope:     "collection",
+		CheckType:     checks.CheckFilesystemUniqueField,
+		Family:        "structuredObject",
+		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
+		NeedsDocument: true,
+		Slug:          "unique-field",
+		Title:         "Unique field",
+		Summary:       "Require that no two items share a value for a frontmatter field.",
+		Scope:         "collection",
 		Fields: []checks.Field{
 			{Name: "field", Required: true, Desc: "Frontmatter key whose value must be unique across the collection."},
 		},
diff --git a/internal/project/loader.go b/internal/project/loader.go
index db71ef1..fbeb7da 100644
--- a/internal/project/loader.go
+++ b/internal/project/loader.go
@@ -25,6 +25,7 @@ import (
 
 	"github.com/abegong/katalyst/internal/storage"
 	"github.com/abegong/katalyst/internal/storage/collection"
+	"github.com/abegong/katalyst/internal/storage/filesystemcheck"
 	"gopkg.in/yaml.v3"
 )
 
@@ -86,6 +87,9 @@ type BaseInstance struct {
 	Root string
 	// Collections this base declares, in name order.
 	Collections []Collection
+	// FilesystemChecks are raw filesystem policy scopes attached to this
+	// filesystem base.
+	FilesystemChecks []filesystemcheck.Scope
 }
 
 // Collection, CollectionVariant, and ListingDefaults live in
@@ -130,10 +134,11 @@ type rawBaseKind struct {
 // collections it declares (name → definition). The collection mirror lives with
 // the Collection type in internal/storage/collection.
 type rawBaseInstance struct {
-	Type        string                              `yaml:"type"`
-	Root        string                              `yaml:"root"`
-	Path        string                              `yaml:"path"`
-	Collections map[string]collection.RawCollection `yaml:"collections"`
+	Type             string                              `yaml:"type"`
+	Root             string                              `yaml:"root"`
+	Path             string                              `yaml:"path"`
+	FilesystemChecks []filesystemcheck.RawScope          `yaml:"filesystemChecks"`
+	Collections      map[string]collection.RawCollection `yaml:"collections"`
 }
 
 // Load finds the project root (nearest ancestor with a .katalyst/ dir),
@@ -353,6 +358,24 @@ func (c *Config) buildInstance(name string, ri rawBaseInstance, exts []string, p
 		rootRel = "."
 	}
 	instRoot := resolve(c.Root, rootRel)
+	var filesystemChecks []filesystemcheck.Scope
+	if len(ri.FilesystemChecks) > 0 {
+		if storage.BaseType(typ) != storage.Filesystem {
+			return BaseInstance{}, fmt.Errorf("%s %q: filesystemChecks requires type %q", label, name, storage.Filesystem)
+		}
+		filesystemChecks = make([]filesystemcheck.Scope, 0, len(ri.FilesystemChecks))
+		for i, raw := range ri.FilesystemChecks {
+			scope, err := filesystemcheck.Build(filesystemcheck.BuildInput{
+				ErrorContext: fmt.Sprintf("%s %q: filesystemChecks[%d]", label, name, i),
+				Raw:          raw,
+				BaseRoot:     instRoot,
+			})
+			if err != nil {
+				return BaseInstance{}, err
+			}
+			filesystemChecks = append(filesystemChecks, scope)
+		}
+	}
 
 	// Start with the inline collections, then fold in any per-collection files.
 	raws := make(map[string]collection.RawCollection, len(ri.Collections))
@@ -401,7 +424,7 @@ func (c *Config) buildInstance(name string, ri rawBaseInstance, exts []string, p
 		}
 		cols = append(cols, col)
 	}
-	return BaseInstance{Name: name, Type: typ, Root: instRoot, Collections: cols}, nil
+	return BaseInstance{Name: name, Type: typ, Root: instRoot, Collections: cols, FilesystemChecks: filesystemChecks}, nil
 }
 
 func dirExists(dir string) (bool, error) {
@@ -524,6 +547,16 @@ func (c *Config) CollectionNames() []string {
 	return names
 }
 
+// FilesystemCheckScopes returns every filesystem check scope in deterministic
+// base order.
+func (c *Config) FilesystemCheckScopes() []filesystemcheck.Scope {
+	var out []filesystemcheck.Scope
+	for _, base := range c.Bases {
+		out = append(out, base.FilesystemChecks...)
+	}
+	return out
+}
+
 // find walks from start upward until it locates a directory containing a
 // .katalyst/ subdirectory. The returned root is the absolute,
 // symlink-resolved directory.
diff --git a/internal/project/loader_test.go b/internal/project/loader_test.go
index 1c4f679..efa21df 100644
--- a/internal/project/loader_test.go
+++ b/internal/project/loader_test.go
@@ -125,6 +125,143 @@ func TestLoad_instanceRoot_resolvesCollectionDirs(t *testing.T) {
 	}
 }
 
+func TestLoad_filesystemChecks_loadsScopes(t *testing.T) {
+	dir := t.TempDir()
+	projecttest.WriteProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: content
+filesystemChecks:
+  - name: docs
+    include: ["**/*.md"]
+    exclude: ["drafts/**"]
+    parseFailures: warning
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections: {}
+`,
+	})
+	cfg, err := project.Load(dir)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	scopes := cfg.FilesystemCheckScopes()
+	if len(scopes) != 1 {
+		t.Fatalf("expected one filesystem check scope, got %d", len(scopes))
+	}
+	scope := scopes[0]
+	if scope.Name != "docs" {
+		t.Errorf("scope.Name = %q, want docs", scope.Name)
+	}
+	if scope.Path != "." {
+		t.Errorf("scope.Path = %q, want default .", scope.Path)
+	}
+	if want := filepath.Join(projecttest.RealPath(t, dir), "content"); scope.Root != want {
+		t.Errorf("scope.Root = %q, want %q", scope.Root, want)
+	}
+	if scope.ParseFailures != "warning" {
+		t.Errorf("ParseFailures = %q, want warning", scope.ParseFailures)
+	}
+	if len(scope.Checks) != 1 || scope.Checks[0].Kind != checks.CheckFilesystemNameCase {
+		t.Fatalf("unexpected checks: %+v", scope.Checks)
+	}
+	assertConfiguredCheckBuilds(t, scope.Checks[0])
+}
+
+func TestLoad_filesystemChecks_defaultsNameAndParseFailures(t *testing.T) {
+	dir := t.TempDir()
+	projecttest.WriteProject(t, dir, map[string]string{
+		"bases/local.yaml": `type: filesystem
+root: .
+filesystemChecks:
+  - path: docs/content
+    include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections: {}
+`,
+	})
+	cfg, err := project.Load(dir)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	scope := cfg.FilesystemCheckScopes()[0]
+	if scope.Name != "docs/content" {
+		t.Errorf("scope.Name = %q, want docs/content", scope.Name)
+	}
+	if scope.ParseFailures != "error" {
+		t.Errorf("ParseFailures = %q, want error", scope.ParseFailures)
+	}
+}
+
+func TestLoad_filesystemChecks_rejectsInvalidConfig(t *testing.T) {
+	tests := []struct {
+		name string
+		base string
+		want string
+	}{
+		{
+			name: "missing include",
+			base: `type: filesystem
+filesystemChecks:
+  - checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections: {}
+`,
+			want: "include is required",
+		},
+		{
+			name: "bad parseFailures",
+			base: `type: filesystem
+filesystemChecks:
+  - include: ["**/*.md"]
+    parseFailures: notice
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections: {}
+`,
+			want: "unknown parseFailures",
+		},
+		{
+			name: "collection-only check",
+			base: `type: filesystem
+filesystemChecks:
+  - include: ["**/*.md"]
+    checks:
+      - kind: markdown_requires_h1
+collections: {}
+`,
+			want: "does not support filesystem checks",
+		},
+		{
+			name: "sqlite base",
+			base: `type: sqlite
+root: data.db
+filesystemChecks:
+  - include: ["**/*.md"]
+    checks:
+      - kind: filesystem_name_case
+        style: kebab
+collections: {}
+`,
+			want: "filesystemChecks requires type",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			dir := t.TempDir()
+			projecttest.WriteProject(t, dir, map[string]string{"bases/local.yaml": tt.base})
+			_, err := project.Load(dir)
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("expected %q error, got: %v", tt.want, err)
+			}
+		})
+	}
+}
+
 func TestLoad_perCollectionFiles_inInstanceDir(t *testing.T) {
 	// A collection may live in its own file under bases/<base>/, the escape
 	// hatch for bases that outgrow an inline block.
diff --git a/internal/project/project.go b/internal/project/project.go
index ecb6a40..7c2474e 100644
--- a/internal/project/project.go
+++ b/internal/project/project.go
@@ -16,6 +16,7 @@ import (
 	"github.com/abegong/katalyst/internal/storage/collection"
 	"github.com/abegong/katalyst/internal/storage/collection/filesystem"
 	sqlitestore "github.com/abegong/katalyst/internal/storage/collection/sqlite"
+	"github.com/abegong/katalyst/internal/storage/filesystemcheck"
 )
 
 // Project is a loaded configuration plus the operations the CLI needs to
@@ -67,6 +68,11 @@ func (p *Project) def(c Collection) (collection.CollectionDefinition, error) {
 // Collections returns all collections in name order.
 func (p *Project) Collections() []Collection { return p.cfg.Collections }
 
+// FilesystemCheckScopes returns all filesystem-attached check scopes.
+func (p *Project) FilesystemCheckScopes() []filesystemcheck.Scope {
+	return p.cfg.FilesystemCheckScopes()
+}
+
 // Collection looks up one collection by name.
 func (p *Project) Collection(name string) (Collection, bool) {
 	return p.cfg.Collection(name)
diff --git a/internal/storage/collection/AGENTS.md b/internal/storage/collection/AGENTS.md
index 1a8e80d..bc0d324 100644
--- a/internal/storage/collection/AGENTS.md
+++ b/internal/storage/collection/AGENTS.md
@@ -25,9 +25,12 @@ and how a backend attaches — live in the
   checks can decode without pulling in a backend.
 - `collection` owns the `Collection` type, so the project loader imports
   `collection`, not the reverse. Keep the edge pointing that way: `collection`
-  imports `checks` (to parse a check's args) and the sibling `predicate`
+  imports `checks` (to parse collection-attached check args) and the sibling `predicate`
   grammar, but never the loader. `Build` takes schema validation as an injected
   `SchemaKnown func(string) bool` rather than reaching back into the loader.
+- Collection `checks:` stay collection-attached. Filesystem-attached checks live
+  on filesystem bases under `filesystemChecks`, and their scope building lives
+  in `internal/storage/filesystemcheck`.
 - Read and write are duals: the backend reader locates and
   `markdownbodytext.Parse` decodes; `fix` computes the new bytes and the backend
   persists them (`filesystem.Write`). Backend-specific IO stays in the backend
diff --git a/internal/storage/collection/parse.go b/internal/storage/collection/parse.go
index 92e1572..64910db 100644
--- a/internal/storage/collection/parse.go
+++ b/internal/storage/collection/parse.go
@@ -143,7 +143,7 @@ type RawCollection struct {
 	Content               ContentConfig               `yaml:"content"`
 	Body                  string                      `yaml:"body"`
 	Schema                string                      `yaml:"schema"`
-	Checks                []RawCheck                  `yaml:"checks"`
+	Checks                []checks.RawCheck           `yaml:"checks"`
 	Listing               *RawListingDefaults         `yaml:"listing"`
 	Query                 *RawListingDefaults         `yaml:"query"`
 	Variants              []RawVariant                `yaml:"variants"`
@@ -160,9 +160,9 @@ type RawListingDefaults struct {
 // RawVariant mirrors one entry of a collection's `variants:` list: a `when`
 // discriminator plus the schema/checks to add for matching items.
 type RawVariant struct {
-	When   RawWhen    `yaml:"when"`
-	Schema string     `yaml:"schema"`
-	Checks []RawCheck `yaml:"checks"`
+	When   RawWhen           `yaml:"when"`
+	Schema string            `yaml:"schema"`
+	Checks []checks.RawCheck `yaml:"checks"`
 }
 
 // RawWhen is a variant discriminator: a list of `item list --filter` predicate
@@ -202,72 +202,6 @@ func (w *RawWhen) UnmarshalYAML(value *yaml.Node) error {
 	return nil
 }
 
-// RawCheck mirrors one `checks:` entry. The struct fields exist so a misspelled
-// key fails YAML's known-field validation; the retained node is what a check
-// type's own parser decodes for its real args.
-type RawCheck struct {
-	Kind      string   `yaml:"kind"`
-	Schema    string   `yaml:"schema"`
-	Field     string   `yaml:"field"`
-	Type      string   `yaml:"type"`
-	Value     string   `yaml:"value"`
-	Values    []string `yaml:"values"`
-	Min       *float64 `yaml:"min"`
-	Max       *float64 `yaml:"max"`
-	MinLength int      `yaml:"min_length"`
-	MaxLength int      `yaml:"max_length"`
-	Heading   string   `yaml:"heading"`
-	Style     string   `yaml:"style"`
-	Target    string   `yaml:"target"`
-	Transform string   `yaml:"transform"`
-	Prefix    string   `yaml:"prefix"`
-	Suffix    string   `yaml:"suffix"`
-	Allow     []string `yaml:"allow"`
-	Deny      []string `yaml:"deny"`
-	Pattern   string   `yaml:"pattern"`
-	Fields    []string `yaml:"fields"`
-	Name      string   `yaml:"name"`
-	Match     string   `yaml:"match"`
-	Select    string   `yaml:"select"`
-	Fix       string   `yaml:"fix"`
-
-	// node is the raw YAML node for this entry, retained so a distributed check
-	// parser can decode its own args. Captured in UnmarshalYAML.
-	node *yaml.Node
-}
-
-var rawCheckKeys = map[string]bool{
-	"kind": true, "schema": true, "field": true, "type": true,
-	"value": true, "values": true, "min": true, "max": true,
-	"min_length": true, "max_length": true, "heading": true,
-	"style": true, "target": true, "transform": true,
-	"prefix": true, "suffix": true, "allow": true, "deny": true,
-	"pattern": true, "fields": true, "name": true, "match": true,
-	"select": true, "fix": true,
-}
-
-// UnmarshalYAML decodes the entry's fields and stashes the raw node, so the
-// node can travel to a check type's own parser (checks.RegisterParsed).
-func (rc *RawCheck) UnmarshalYAML(value *yaml.Node) error {
-	if value.Kind != yaml.MappingNode {
-		return fmt.Errorf("invalid check: expected a mapping")
-	}
-	for i := 0; i < len(value.Content); i += 2 {
-		key := value.Content[i].Value
-		if !rawCheckKeys[key] {
-			return fmt.Errorf("unknown check key %q", key)
-		}
-	}
-	type plain RawCheck
-	var p plain
-	if err := value.Decode(&p); err != nil {
-		return err
-	}
-	*rc = RawCheck(p)
-	rc.node = value
-	return nil
-}
-
 // BuildInput carries everything Build needs to validate and resolve one
 // collection: its raw definition and name, the owning base's root
 // and name, the project-level listing defaults, and a predicate that reports
@@ -440,38 +374,15 @@ func rejectUnsupportedSQLiteChecks(name string, base []checks.ConfiguredCheck, v
 // buildChecks folds an optional schema name into a leading object check and
 // normalizes the remaining raw checks. errCtx prefixes any error (e.g.
 // `collection "books"` or `collection "books": variants[0]`).
-func buildChecks(errCtx, schema string, raws []RawCheck, schemaKnown func(string) bool) ([]checks.ConfiguredCheck, error) {
-	out := make([]checks.ConfiguredCheck, 0, len(raws)+1)
-	if schema != "" {
-		if !schemaKnown(schema) {
-			return nil, fmt.Errorf("%s: unknown schema %q", errCtx, schema)
-		}
-		out = append(out, checks.ConfiguredCheck{Kind: checks.CheckObject, Schema: schema})
-	}
-	for j, raw := range raws {
-		kind := checks.CheckType(strings.TrimSpace(raw.Kind))
-		if kind == checks.CheckObject {
-			// An explicit `kind: object` names a schema, validated here because
-			// the loader owns schema resolution; the engine builds it.
-			if raw.Schema == "" {
-				return nil, fmt.Errorf("%s: checks[%d]: object check requires \"schema\"", errCtx, j)
-			}
-			if !schemaKnown(raw.Schema) {
-				return nil, fmt.Errorf("%s: checks[%d]: unknown schema %q", errCtx, j, raw.Schema)
-			}
-			if raw.Field != "" {
-				return nil, fmt.Errorf("%s: checks[%d]: object check does not support \"field\"", errCtx, j)
-			}
-			out = append(out, checks.ConfiguredCheck{Kind: checks.CheckObject, Schema: raw.Schema})
-			continue
-		}
-		args, err := checks.Parse(kind, raw.node)
-		if err != nil {
-			return nil, fmt.Errorf("%s: checks[%d]: %w", errCtx, j, err)
-		}
-		out = append(out, checks.ConfiguredCheck{Kind: kind, Args: args})
-	}
-	return out, nil
+func buildChecks(errCtx, schema string, raws []checks.RawCheck, schemaKnown func(string) bool) ([]checks.ConfiguredCheck, error) {
+	return checks.BuildConfigured(checks.BuildConfiguredInput{
+		ErrorContext: errCtx,
+		Schema:       schema,
+		Raw:          raws,
+		SchemaKnown:  schemaKnown,
+		Target:       checks.TargetCollection,
+		AllowObject:  true,
+	})
 }
 
 // buildVariants parses and validates a collection's variants: each `when`
diff --git a/internal/storage/filesystemcheck/scope.go b/internal/storage/filesystemcheck/scope.go
new file mode 100644
index 0000000..46228a1
--- /dev/null
+++ b/internal/storage/filesystemcheck/scope.go
@@ -0,0 +1,181 @@
+package filesystemcheck
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+
+	"github.com/abegong/katalyst/internal/checks"
+	"github.com/bmatcuk/doublestar/v4"
+)
+
+const (
+	ParseFailuresError   = "error"
+	ParseFailuresWarning = "warning"
+)
+
+// RawScope mirrors one filesystemChecks entry.
+type RawScope struct {
+	Name          string            `yaml:"name"`
+	Path          string            `yaml:"path"`
+	Include       []string          `yaml:"include"`
+	Exclude       []string          `yaml:"exclude"`
+	ParseFailures string            `yaml:"parseFailures"`
+	Checks        []checks.RawCheck `yaml:"checks"`
+}
+
+// Scope is a validated filesystem check scope.
+type Scope struct {
+	Name          string
+	Path          string
+	Root          string
+	Include       []string
+	Exclude       []string
+	ParseFailures string
+	Checks        []checks.ConfiguredCheck
+}
+
+// File is one regular file under a scope root.
+type File struct {
+	Rel  string
+	Path string
+}
+
+// Expanded is the deterministic selected and unmatched file set for a scope.
+type Expanded struct {
+	Selected  []File
+	Unmatched []File
+}
+
+// BuildInput carries the owning base and source location for a filesystem
+// scope.
+type BuildInput struct {
+	ErrorContext string
+	Raw          RawScope
+	BaseRoot     string
+}
+
+// Build validates and resolves one filesystem scope.
+func Build(in BuildInput) (Scope, error) {
+	raw := in.Raw
+	label := in.ErrorContext
+	if label == "" {
+		label = "filesystemChecks"
+	}
+	if len(raw.Include) == 0 {
+		return Scope{}, fmt.Errorf("%s: include is required", label)
+	}
+	if len(raw.Checks) == 0 {
+		return Scope{}, fmt.Errorf("%s: checks is required", label)
+	}
+	parseFailures := raw.ParseFailures
+	if parseFailures == "" {
+		parseFailures = ParseFailuresError
+	}
+	switch parseFailures {
+	case ParseFailuresError, ParseFailuresWarning:
+	default:
+		return Scope{}, fmt.Errorf("%s: unknown parseFailures %q (want error or warning)", label, raw.ParseFailures)
+	}
+	scopePath := raw.Path
+	if scopePath == "" {
+		scopePath = "."
+	}
+	root := resolve(in.BaseRoot, scopePath)
+	name := raw.Name
+	if name == "" {
+		name = filepath.ToSlash(scopePath)
+	}
+	cks, err := checks.BuildConfigured(checks.BuildConfiguredInput{
+		ErrorContext: label,
+		Raw:          raw.Checks,
+		Target:       checks.TargetFilesystem,
+		AllowObject:  false,
+	})
+	if err != nil {
+		return Scope{}, err
+	}
+	return Scope{
+		Name:          name,
+		Path:          scopePath,
+		Root:          root,
+		Include:       append([]string(nil), raw.Include...),
+		Exclude:       append([]string(nil), raw.Exclude...),
+		ParseFailures: parseFailures,
+		Checks:        cks,
+	}, nil
+}
+
+// Expand walks a scope root and splits regular files into selected and
+// unmatched sets. Missing roots yield empty sets.
+func Expand(scope Scope) (Expanded, error) {
+	info, err := os.Stat(scope.Root)
+	if err != nil || !info.IsDir() {
+		return Expanded{}, nil
+	}
+	var out Expanded
+	walkErr := filepath.WalkDir(scope.Root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		if !info.Mode().IsRegular() {
+			return nil
+		}
+		rel, err := filepath.Rel(scope.Root, path)
+		if err != nil {
+			return err
+		}
+		rel = filepath.ToSlash(rel)
+		included, err := matchesAny(scope.Include, rel)
+		if err != nil {
+			return fmt.Errorf("include: %w", err)
+		}
+		excluded, err := matchesAny(scope.Exclude, rel)
+		if err != nil {
+			return fmt.Errorf("exclude: %w", err)
+		}
+		file := File{Rel: rel, Path: path}
+		switch {
+		case included && !excluded:
+			out.Selected = append(out.Selected, file)
+		case !included && !excluded:
+			out.Unmatched = append(out.Unmatched, file)
+		}
+		return nil
+	})
+	if walkErr != nil {
+		return Expanded{}, fmt.Errorf("filesystem scope %q: %w", scope.Name, walkErr)
+	}
+	sort.Slice(out.Selected, func(i, j int) bool { return out.Selected[i].Rel < out.Selected[j].Rel })
+	sort.Slice(out.Unmatched, func(i, j int) bool { return out.Unmatched[i].Rel < out.Unmatched[j].Rel })
+	return out, nil
+}
+
+func matchesAny(patterns []string, rel string) (bool, error) {
+	for _, p := range patterns {
+		ok, err := doublestar.Match(p, rel)
+		if err != nil {
+			return false, err
+		}
+		if ok {
+			return true, nil
+		}
+	}
+	return false, nil
+}
+
+func resolve(root, p string) string {
+	if filepath.IsAbs(p) {
+		return filepath.Clean(p)
+	}
+	return filepath.Clean(filepath.Join(root, p))
+}

From 9b92ccb6fb5a51e232d1f6109fc25308ef5764a4 Mon Sep 17 00:00:00 2001
From: Abe Gong <abe@Abes-MacBook-Air.local>
Date: Mon, 29 Jun 2026 14:14:06 -0600
Subject: [PATCH 5/6] Fix getting started config reference

---
 docs/content/getting-started.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
index 49ffcfe..4adbda4 100644
--- a/docs/content/getting-started.md
+++ b/docs/content/getting-started.md
@@ -59,13 +59,13 @@ katalyst check
 
 - `.katalyst/config.yaml`, commented project settings
 - `.katalyst/schemas/`, one schema per file (empty to start)
-- `.katalyst/storage/local.yaml`, the default storage instance (the local
-  filesystem), where you declare collections
+- `.katalyst/bases/local.yaml`, the default filesystem base, where you declare
+  collections
 
 It writes no example content. Add a schema under `.katalyst/schemas/` and
-declare a collection inside `.katalyst/storage/local.yaml`, then run
+declare a collection inside `.katalyst/bases/local.yaml`, then run
 `katalyst check`.
 
 Next:
-- [Configuration]({{< relref "reference/configuration.md" >}})
+- [Configuration]({{< relref "reference/configs/_index.md" >}})
 - [Check types reference]({{< relref "reference/check-types/_index.md" >}})

From 86910eed4df3251c6f36bd9e4eeaf25b779eea33 Mon Sep 17 00:00:00 2001
From: Abe Gong <abe@Abes-MacBook-Air.local>
Date: Mon, 29 Jun 2026 14:26:33 -0600
Subject: [PATCH 6/6] Rename check configuration site metadata

---
 .../skills/add-katalyst-check-type/SKILL.md   |  6 +--
 cmd/check_types.go                            |  4 +-
 cmd/check_types_test.go                       | 30 +++++------
 cmd/gendocs/main.go                           | 23 ++++++++-
 .../check-types/show-markdown_single_h1.txt   |  2 +-
 .../check-types/show-object_field_enum.txt    |  2 +-
 .../show-object_required_field.txt            |  2 +-
 .../content/deep-dives/domain-model/checks.md | 10 ++--
 .../check-types/file-system/extension-in.md   |  2 +-
 .../file-system/index-file-required.md        |  2 +-
 .../check-types/file-system/name-affix.md     |  2 +-
 .../check-types/file-system/name-case.md      |  2 +-
 .../check-types/file-system/name-length.md    |  2 +-
 .../file-system/name-matches-field.md         |  2 +-
 .../check-types/file-system/name-regex.md     |  2 +-
 .../check-types/file-system/parent-dir-in.md  |  2 +-
 .../file-system/parent-dir-matches-field.md   |  2 +-
 .../check-types/file-system/path-charset.md   |  2 +-
 .../check-types/file-system/path-depth.md     |  2 +-
 .../file-system/referenced-files-exist.md     |  2 +-
 .../file-system/unique-filename.md            |  2 +-
 .../file-system/unmatched-files.md            |  2 +-
 .../code-fence-language-required.md           |  2 -
 .../no-heading-level-jumps.md                 |  2 -
 .../markdown-body-text/required-section.md    |  2 -
 .../markdown-body-text/requires-h1.md         |  2 -
 .../markdown-body-text/single-h1.md           |  2 -
 .../markdown-body-text/title-matches-h1.md    |  2 -
 .../markdown-body-text/writing-tells.md       |  2 -
 .../check-types/plain-text/denylist.md        |  2 -
 .../check-types/plain-text/forbids.md         |  2 -
 .../check-types/plain-text/requires.md        |  2 -
 .../structured-object/field-enum.md           |  2 -
 .../structured-object/field-type.md           |  2 -
 .../structured-object/number-range.md         |  2 -
 .../check-types/structured-object/object.md   |  2 -
 .../structured-object/required-field.md       |  2 -
 .../structured-object/sentence-case.md        |  2 -
 .../structured-object/string-length.md        |  2 -
 .../structured-object/unique-field.md         |  2 +-
 docs/content/reference/configs/checks.md      |  4 +-
 docs/content/reference/glossary.md            |  6 +--
 internal/checks/AGENTS.md                     |  8 +--
 internal/checks/config.go                     | 26 +++++-----
 internal/checks/filesystem/extension_in.go    | 12 ++---
 .../checks/filesystem/index_file_required.go  | 14 ++---
 internal/checks/filesystem/name_affix.go      | 12 ++---
 internal/checks/filesystem/name_case.go       | 12 ++---
 internal/checks/filesystem/name_length.go     | 12 ++---
 .../checks/filesystem/name_matches_field.go   | 14 ++---
 internal/checks/filesystem/name_regex.go      | 12 ++---
 internal/checks/filesystem/parent_dir_in.go   | 12 ++---
 .../filesystem/parent_dir_matches_field.go    | 14 ++---
 internal/checks/filesystem/path_charset.go    | 12 ++---
 internal/checks/filesystem/path_depth.go      | 12 ++---
 .../checks/filesystem/referenced_files.go     | 14 ++---
 internal/checks/filesystem/unique_filename.go | 14 ++---
 internal/checks/filesystem/unmatched_files.go | 14 ++---
 internal/checks/registry.go                   | 34 +++++++------
 internal/checks/registry_test.go              | 12 ++---
 .../checks/structuredobject/unique_field.go   | 16 +++---
 internal/storage/collection/parse.go          | 12 ++---
 internal/storage/filesystemcheck/scope.go     |  8 +--
 product/specs/filesystem-checks-plan.md       | 51 ++++++++++---------
 product/specs/filesystem-checks-spec.md       | 36 ++++++-------
 65 files changed, 263 insertions(+), 273 deletions(-)

diff --git a/.cursor/skills/add-katalyst-check-type/SKILL.md b/.cursor/skills/add-katalyst-check-type/SKILL.md
index 6a4d89f..767eaee 100644
--- a/.cursor/skills/add-katalyst-check-type/SKILL.md
+++ b/.cursor/skills/add-katalyst-check-type/SKILL.md
@@ -33,7 +33,7 @@ Copy this checklist and keep it updated:
 ```text
 Check Type Task Progress:
 - [ ] 1) Kind constant added (internal/checks/kinds.go)
-- [ ] 2) Check file added (struct + Run + args + Descriptor targets/document-needs + registerParsed)
+- [ ] 2) Check file added (struct + Run + args + Descriptor configurableIn/document-needs + registerParsed)
 - [ ] 3) Tests added/updated
 - [ ] 4) Fixtures/readmes updated
 - [ ] 5) Reference regenerated
@@ -62,8 +62,8 @@ Add one file in the check type's family package — `internal/checks/structuredo
   the family's `common.go`) rather than re-deriving.
 - An `init()` calling the family's `registerParsed(descriptor, parse, build,
   buildColl)`:
-  - Set `descriptor.Targets`. Use `checks.TargetCollection` for collection
-    `checks:` and add `checks.TargetFilesystem` only when the same
+  - Set `descriptor.ConfigurableIn`. Use `checks.ConfigCollection` for collection
+    `checks:` and add `checks.ConfigFilesystem` only when the same
     implementation works under `filesystemChecks`.
   - Set `descriptor.NeedsDocument` when the check reads frontmatter, markdown
     body text, or source line maps. Path-only checks leave it false.
diff --git a/cmd/check_types.go b/cmd/check_types.go
index bee2600..eb96a58 100644
--- a/cmd/check_types.go
+++ b/cmd/check_types.go
@@ -119,7 +119,7 @@ func runCheckTypesDetail(cmd *cobra.Command, checkType string, asJSON bool) erro
 	printSectionHeader(out, fmt.Sprintf("%s › %s", fam.Title, d.Title))
 	fmt.Fprintf(out, "- kind: %s\n", d.CheckType)
 	fmt.Fprintf(out, "- family: %s\n", d.Family)
-	fmt.Fprintf(out, "- targets: %s\n", strings.Join(checks.DescriptorTargets(d), ", "))
+	fmt.Fprintf(out, "- configurableIn: %s\n", strings.Join(checks.DescriptorConfigurableIn(d), ", "))
 	scope := d.Scope
 	if scope == "" {
 		scope = "item"
@@ -257,7 +257,7 @@ func jsonDescriptor(d checks.Descriptor) checks.Descriptor {
 	if d.Fields == nil {
 		d.Fields = []checks.Field{}
 	}
-	d.Targets = checks.DescriptorTargets(d)
+	d.ConfigurableIn = checks.DescriptorConfigurableIn(d)
 	return d
 }
 
diff --git a/cmd/check_types_test.go b/cmd/check_types_test.go
index 9381434..f70492e 100644
--- a/cmd/check_types_test.go
+++ b/cmd/check_types_test.go
@@ -185,10 +185,10 @@ func TestCheckTypesList_jsonArrayShape(t *testing.T) {
 	}
 
 	var got []struct {
-		CheckType string   `json:"check_type"`
-		Family    string   `json:"family"`
-		Targets   []string `json:"targets"`
-		Fields    []struct {
+		CheckType      string   `json:"check_type"`
+		Family         string   `json:"family"`
+		ConfigurableIn []string `json:"configurableIn"`
+		Fields         []struct {
 			Name string `json:"name"`
 		} `json:"fields"`
 		ConfigExample string `json:"config_example"`
@@ -200,10 +200,10 @@ func TestCheckTypesList_jsonArrayShape(t *testing.T) {
 		t.Fatal("expected at least one descriptor")
 	}
 	seen := map[string]bool{}
-	targets := map[string][]string{}
+	configurableIn := map[string][]string{}
 	for i, d := range got {
 		seen[d.CheckType] = true
-		targets[d.CheckType] = d.Targets
+		configurableIn[d.CheckType] = d.ConfigurableIn
 		if got[i].ConfigExample == "" {
 			t.Errorf("entry %d (%s): empty config_example", i, d.CheckType)
 		}
@@ -230,11 +230,11 @@ func TestCheckTypesList_jsonArrayShape(t *testing.T) {
 	if strings.Contains(stdout, `"default": ""`) {
 		t.Errorf("empty default should be omitted, not emitted")
 	}
-	if strings.Join(targets["filesystem_name_case"], ",") != "collection,filesystem" {
-		t.Errorf("filesystem_name_case targets = %v, want collection+filesystem", targets["filesystem_name_case"])
+	if strings.Join(configurableIn["filesystem_name_case"], ",") != "collection,filesystem" {
+		t.Errorf("filesystem_name_case configurableIn = %v, want collection+filesystem", configurableIn["filesystem_name_case"])
 	}
-	if strings.Join(targets["markdown_requires_h1"], ",") != "collection" {
-		t.Errorf("markdown_requires_h1 targets = %v, want collection", targets["markdown_requires_h1"])
+	if strings.Join(configurableIn["markdown_requires_h1"], ",") != "collection" {
+		t.Errorf("markdown_requires_h1 configurableIn = %v, want collection", configurableIn["markdown_requires_h1"])
 	}
 }
 
@@ -246,9 +246,9 @@ func TestCheckTypesShow_jsonObject(t *testing.T) {
 	}
 
 	var got struct {
-		CheckType string   `json:"check_type"`
-		Targets   []string `json:"targets"`
-		Fields    []struct {
+		CheckType      string   `json:"check_type"`
+		ConfigurableIn []string `json:"configurableIn"`
+		Fields         []struct {
 			Name     string `json:"name"`
 			Required bool   `json:"required"`
 		} `json:"fields"`
@@ -259,8 +259,8 @@ func TestCheckTypesShow_jsonObject(t *testing.T) {
 	if got.CheckType != "object_number_range" {
 		t.Errorf("got check type %q, want object_number_range", got.CheckType)
 	}
-	if strings.Join(got.Targets, ",") != "collection" {
-		t.Errorf("targets = %v, want collection", got.Targets)
+	if strings.Join(got.ConfigurableIn, ",") != "collection" {
+		t.Errorf("configurableIn = %v, want collection", got.ConfigurableIn)
 	}
 	if len(got.Fields) != 3 {
 		t.Fatalf("got %d fields, want 3", len(got.Fields))
diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go
index e651bd9..d1d5fa5 100644
--- a/cmd/gendocs/main.go
+++ b/cmd/gendocs/main.go
@@ -314,7 +314,9 @@ func checkTypePage(d checks.Descriptor, fam checks.Family, weight int) string {
 	if d.Scope == "collection" {
 		fmt.Fprint(&b, "**Scope:** collection, runs once per collection over all its items.\n\n")
 	}
-	fmt.Fprintf(&b, "**Targets:** %s.\n\n", strings.Join(checks.DescriptorTargets(d), ", "))
+	if sites := checks.DescriptorConfigurableIn(d); !collectionOnly(sites) {
+		fmt.Fprintf(&b, "**Can be configured in:** %s.\n\n", configurationSites(sites))
+	}
 	if d.Severity == "warning" {
 		fmt.Fprint(&b, "**Severity:** warning, reported for review; never fails a run.\n\n")
 	}
@@ -342,6 +344,25 @@ func checkTypePage(d checks.Descriptor, fam checks.Family, weight int) string {
 	return b.String()
 }
 
+func collectionOnly(sites []string) bool {
+	return len(sites) == 1 && sites[0] == checks.ConfigCollection
+}
+
+func configurationSites(sites []string) string {
+	labels := make([]string, len(sites))
+	for i, site := range sites {
+		switch site {
+		case checks.ConfigCollection:
+			labels[i] = "collection checks"
+		case checks.ConfigFilesystem:
+			labels[i] = "filesystem checks"
+		default:
+			labels[i] = site
+		}
+	}
+	return strings.Join(labels, ", ")
+}
+
 // plain strips inline-code backticks from a summary so it reads cleanly in a
 // link list.
 func plain(s string) string {
diff --git a/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt b/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt
index a554cb3..63a879e 100644
--- a/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt
+++ b/cmd/testdata/snapshots/check-types/show-markdown_single_h1.txt
@@ -2,7 +2,7 @@ Markdown body text › Single H1
 --------------------------------
 - kind: markdown_single_h1
 - family: markdownBodyText
-- targets: collection
+- configurableIn: collection
 - scope: item
 - severity: error
 - purpose: Require that the markdown body contains at most one H1 heading.
diff --git a/cmd/testdata/snapshots/check-types/show-object_field_enum.txt b/cmd/testdata/snapshots/check-types/show-object_field_enum.txt
index a1ffc3f..415c19c 100644
--- a/cmd/testdata/snapshots/check-types/show-object_field_enum.txt
+++ b/cmd/testdata/snapshots/check-types/show-object_field_enum.txt
@@ -2,7 +2,7 @@ Structured object › Field enum
 --------------------------------
 - kind: object_field_enum
 - family: structuredObject
-- targets: collection
+- configurableIn: collection
 - scope: item
 - severity: error
 - purpose: Require that a field is one of a fixed set of values.
diff --git a/cmd/testdata/snapshots/check-types/show-object_required_field.txt b/cmd/testdata/snapshots/check-types/show-object_required_field.txt
index 4804868..bd567f4 100644
--- a/cmd/testdata/snapshots/check-types/show-object_required_field.txt
+++ b/cmd/testdata/snapshots/check-types/show-object_required_field.txt
@@ -2,7 +2,7 @@ Structured object › Required field
 ------------------------------------
 - kind: object_required_field
 - family: structuredObject
-- targets: collection
+- configurableIn: collection
 - scope: item
 - severity: error
 - purpose: Require that a frontmatter field exists.
diff --git a/docs/content/deep-dives/domain-model/checks.md b/docs/content/deep-dives/domain-model/checks.md
index 7f8c39f..388f567 100644
--- a/docs/content/deep-dives/domain-model/checks.md
+++ b/docs/content/deep-dives/domain-model/checks.md
@@ -29,7 +29,7 @@ model]({{< relref "_index.md" >}}).
 | **Severity** | The consequence of a violation. `error` fails the run; `warning` is advisory and does not change the exit code. |
 | **Violation** | One failed check result, with a message, source location, JSON pointer when applicable, severity, and sometimes a sibling file for collection-scoped findings. |
 
-Family, library, attachment target, and runtime granularity are separate axes.
+Family, library, configuration site, and runtime granularity are separate axes.
 Family answers *what data does this check read?* Library answers *who runs it?*
 Attachment target answers *where can a user configure it?* Runtime granularity
 answers *does it run once per file or once per selected file set?* A single
@@ -38,13 +38,13 @@ family can span libraries:
 `object_required_field` from the native structured-object library.
 
 The registry is the single source of truth for check types. Each check type
-self-registers a `Descriptor` (its id, family, targets, docs metadata) and a
+self-registers a `Descriptor` (its id, family, `configurableIn`, docs metadata) and a
 constructor. `cmd/engine` builds the runnable list by registry lookup; the docs
 generator and `katalyst check-types list` read the same descriptors. A parity
 test fails if a configured kind has no descriptor, so a check type cannot ship
 undocumented.
 
-## Attachment targets
+## Configuration Sites
 
 Collection-attached checks live under a collection's `checks:` list. They run
 after selector resolution and can use schema precedence, variants, and the
@@ -57,9 +57,9 @@ no-selector `katalyst check` runs filesystem scopes before collection checks,
 so a project can enforce path policy before any collection exists. Explicit
 collection selectors stay collection-only.
 
-The descriptor's `Targets` list controls where a check type may be configured.
+The descriptor's `ConfigurableIn` list controls where a check type may be configured.
 During migration, an empty list means `collection`. File-system-family checks
-that only read paths can usually support both targets. Checks that read
+that only read paths can usually support both configuration sites. Checks that read
 frontmatter or body text declare that they need a parsed document so filesystem
 scopes parse lazily and path-only scopes avoid unnecessary document work.
 
diff --git a/docs/content/reference/check-types/file-system/extension-in.md b/docs/content/reference/check-types/file-system/extension-in.md
index 5f7f964..e1b624d 100644
--- a/docs/content/reference/check-types/file-system/extension-in.md
+++ b/docs/content/reference/check-types/file-system/extension-in.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/extension-in/"]
 
 `kind: filesystem_extension_in`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/index-file-required.md b/docs/content/reference/check-types/file-system/index-file-required.md
index fdceff0..8f114db 100644
--- a/docs/content/reference/check-types/file-system/index-file-required.md
+++ b/docs/content/reference/check-types/file-system/index-file-required.md
@@ -12,7 +12,7 @@ aliases = ["/reference/rules/file-system/index-file-required/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/name-affix.md b/docs/content/reference/check-types/file-system/name-affix.md
index 52b82e2..0393c3b 100644
--- a/docs/content/reference/check-types/file-system/name-affix.md
+++ b/docs/content/reference/check-types/file-system/name-affix.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/name-affix/"]
 
 `kind: filesystem_name_affix`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/name-case.md b/docs/content/reference/check-types/file-system/name-case.md
index 1ec5137..826435a 100644
--- a/docs/content/reference/check-types/file-system/name-case.md
+++ b/docs/content/reference/check-types/file-system/name-case.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/name-case/"]
 
 `kind: filesystem_name_case`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/name-length.md b/docs/content/reference/check-types/file-system/name-length.md
index 6f7b59b..49fa653 100644
--- a/docs/content/reference/check-types/file-system/name-length.md
+++ b/docs/content/reference/check-types/file-system/name-length.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/name-length/"]
 
 `kind: filesystem_name_length`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/name-matches-field.md b/docs/content/reference/check-types/file-system/name-matches-field.md
index 8b47334..55d6aba 100644
--- a/docs/content/reference/check-types/file-system/name-matches-field.md
+++ b/docs/content/reference/check-types/file-system/name-matches-field.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/name-matches-field/"]
 
 `kind: filesystem_name_matches_field`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/name-regex.md b/docs/content/reference/check-types/file-system/name-regex.md
index 0e89530..f686ac5 100644
--- a/docs/content/reference/check-types/file-system/name-regex.md
+++ b/docs/content/reference/check-types/file-system/name-regex.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/name-regex/"]
 
 `kind: filesystem_name_regex`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/parent-dir-in.md b/docs/content/reference/check-types/file-system/parent-dir-in.md
index dce4578..95d18cb 100644
--- a/docs/content/reference/check-types/file-system/parent-dir-in.md
+++ b/docs/content/reference/check-types/file-system/parent-dir-in.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/parent-dir-in/"]
 
 `kind: filesystem_parent_dir_in`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/parent-dir-matches-field.md b/docs/content/reference/check-types/file-system/parent-dir-matches-field.md
index cf90353..a0c3f9a 100644
--- a/docs/content/reference/check-types/file-system/parent-dir-matches-field.md
+++ b/docs/content/reference/check-types/file-system/parent-dir-matches-field.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/parent-dir-matches-field/"]
 
 `kind: filesystem_parent_dir_matches_field`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/path-charset.md b/docs/content/reference/check-types/file-system/path-charset.md
index b37dfa3..633af15 100644
--- a/docs/content/reference/check-types/file-system/path-charset.md
+++ b/docs/content/reference/check-types/file-system/path-charset.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/path-charset/"]
 
 `kind: filesystem_path_charset`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/path-depth.md b/docs/content/reference/check-types/file-system/path-depth.md
index 256c53a..5bac740 100644
--- a/docs/content/reference/check-types/file-system/path-depth.md
+++ b/docs/content/reference/check-types/file-system/path-depth.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/path-depth/"]
 
 `kind: filesystem_path_depth`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/referenced-files-exist.md b/docs/content/reference/check-types/file-system/referenced-files-exist.md
index 6d9915e..a1878ec 100644
--- a/docs/content/reference/check-types/file-system/referenced-files-exist.md
+++ b/docs/content/reference/check-types/file-system/referenced-files-exist.md
@@ -10,7 +10,7 @@ aliases = ["/reference/rules/file-system/referenced-files-exist/"]
 
 `kind: filesystem_referenced_files_exist`
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/unique-filename.md b/docs/content/reference/check-types/file-system/unique-filename.md
index 00c6900..ff4a8e0 100644
--- a/docs/content/reference/check-types/file-system/unique-filename.md
+++ b/docs/content/reference/check-types/file-system/unique-filename.md
@@ -12,7 +12,7 @@ aliases = ["/reference/rules/file-system/unique-filename/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/file-system/unmatched-files.md b/docs/content/reference/check-types/file-system/unmatched-files.md
index 4fbd582..7cfae3e 100644
--- a/docs/content/reference/check-types/file-system/unmatched-files.md
+++ b/docs/content/reference/check-types/file-system/unmatched-files.md
@@ -12,7 +12,7 @@ aliases = ["/reference/rules/file-system/unmatched-files/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
-**Targets:** filesystem.
+**Can be configured in:** filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md b/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md
index 54b0d97..458cf59 100644
--- a/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md
+++ b/docs/content/reference/check-types/markdown-body-text/code-fence-language-required.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/code-fence-language-required/"]
 
 `kind: markdown_code_fence_language_required`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require that opening fenced code blocks include a language tag.
diff --git a/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md b/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md
index 7825b74..5e95d65 100644
--- a/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md
+++ b/docs/content/reference/check-types/markdown-body-text/no-heading-level-jumps.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/no-heading-level-jumps/"]
 
 `kind: markdown_no_heading_level_jumps`
 
-**Targets:** collection.
-
 ## Purpose
 
 Disallow jumps larger than one heading level (for example `H1 -> H3`).
diff --git a/docs/content/reference/check-types/markdown-body-text/required-section.md b/docs/content/reference/check-types/markdown-body-text/required-section.md
index f3c6f19..4040600 100644
--- a/docs/content/reference/check-types/markdown-body-text/required-section.md
+++ b/docs/content/reference/check-types/markdown-body-text/required-section.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/required-section/"]
 
 `kind: markdown_required_section`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require that a heading with specific text exists somewhere in the body.
diff --git a/docs/content/reference/check-types/markdown-body-text/requires-h1.md b/docs/content/reference/check-types/markdown-body-text/requires-h1.md
index 40d4d97..df57b18 100644
--- a/docs/content/reference/check-types/markdown-body-text/requires-h1.md
+++ b/docs/content/reference/check-types/markdown-body-text/requires-h1.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/requires-h1/"]
 
 `kind: markdown_requires_h1`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require at least one H1 heading in the markdown body.
diff --git a/docs/content/reference/check-types/markdown-body-text/single-h1.md b/docs/content/reference/check-types/markdown-body-text/single-h1.md
index b54132f..423102f 100644
--- a/docs/content/reference/check-types/markdown-body-text/single-h1.md
+++ b/docs/content/reference/check-types/markdown-body-text/single-h1.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/single-h1/"]
 
 `kind: markdown_single_h1`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require that the markdown body contains at most one H1 heading.
diff --git a/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md b/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md
index e235915..ece9945 100644
--- a/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md
+++ b/docs/content/reference/check-types/markdown-body-text/title-matches-h1.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/title-matches-h1/"]
 
 `kind: markdown_title_matches_h1`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require a frontmatter field to match the first H1 heading in the body.
diff --git a/docs/content/reference/check-types/markdown-body-text/writing-tells.md b/docs/content/reference/check-types/markdown-body-text/writing-tells.md
index b994bb4..e8dccca 100644
--- a/docs/content/reference/check-types/markdown-body-text/writing-tells.md
+++ b/docs/content/reference/check-types/markdown-body-text/writing-tells.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/markdown-body-text/writing-tells/"]
 
 `kind: markdown_writing_tells`
 
-**Targets:** collection.
-
 **Severity:** warning, reported for review; never fails a run.
 
 ## Purpose
diff --git a/docs/content/reference/check-types/plain-text/denylist.md b/docs/content/reference/check-types/plain-text/denylist.md
index 7cdabb1..49bb8b4 100644
--- a/docs/content/reference/check-types/plain-text/denylist.md
+++ b/docs/content/reference/check-types/plain-text/denylist.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/plain-text/denylist/"]
 
 `kind: text_denylist`
 
-**Targets:** collection.
-
 ## Purpose
 
 Forbid any of a list of literal substrings in the body text.
diff --git a/docs/content/reference/check-types/plain-text/forbids.md b/docs/content/reference/check-types/plain-text/forbids.md
index e35953e..7aca04b 100644
--- a/docs/content/reference/check-types/plain-text/forbids.md
+++ b/docs/content/reference/check-types/plain-text/forbids.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/plain-text/forbids/"]
 
 `kind: text_forbids`
 
-**Targets:** collection.
-
 ## Purpose
 
 Forbid a regular expression from appearing in the body text.
diff --git a/docs/content/reference/check-types/plain-text/requires.md b/docs/content/reference/check-types/plain-text/requires.md
index e2a5ea7..8cfa38a 100644
--- a/docs/content/reference/check-types/plain-text/requires.md
+++ b/docs/content/reference/check-types/plain-text/requires.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/plain-text/requires/"]
 
 `kind: text_requires`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require a regular expression to appear in the body text.
diff --git a/docs/content/reference/check-types/structured-object/field-enum.md b/docs/content/reference/check-types/structured-object/field-enum.md
index d02e975..f28a17c 100644
--- a/docs/content/reference/check-types/structured-object/field-enum.md
+++ b/docs/content/reference/check-types/structured-object/field-enum.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/field-enum/"]
 
 `kind: object_field_enum`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require that a field is one of a fixed set of values.
diff --git a/docs/content/reference/check-types/structured-object/field-type.md b/docs/content/reference/check-types/structured-object/field-type.md
index 6ed67f3..ca13f4a 100644
--- a/docs/content/reference/check-types/structured-object/field-type.md
+++ b/docs/content/reference/check-types/structured-object/field-type.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/field-type/"]
 
 `kind: object_field_type`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require that a frontmatter field has a specific type.
diff --git a/docs/content/reference/check-types/structured-object/number-range.md b/docs/content/reference/check-types/structured-object/number-range.md
index 5f44797..29d12f3 100644
--- a/docs/content/reference/check-types/structured-object/number-range.md
+++ b/docs/content/reference/check-types/structured-object/number-range.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/number-range/"]
 
 `kind: object_number_range`
 
-**Targets:** collection.
-
 ## Purpose
 
 Constrain a numeric field to a minimum and/or maximum value.
diff --git a/docs/content/reference/check-types/structured-object/object.md b/docs/content/reference/check-types/structured-object/object.md
index ceaef2e..bb3cbe9 100644
--- a/docs/content/reference/check-types/structured-object/object.md
+++ b/docs/content/reference/check-types/structured-object/object.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/object/"]
 
 `kind: object`
 
-**Targets:** collection.
-
 ## Purpose
 
 Validate frontmatter metadata against a named JSON Schema from `schemas:`.
diff --git a/docs/content/reference/check-types/structured-object/required-field.md b/docs/content/reference/check-types/structured-object/required-field.md
index bd258f8..2496c1d 100644
--- a/docs/content/reference/check-types/structured-object/required-field.md
+++ b/docs/content/reference/check-types/structured-object/required-field.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/required-field/"]
 
 `kind: object_required_field`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require that a frontmatter field exists.
diff --git a/docs/content/reference/check-types/structured-object/sentence-case.md b/docs/content/reference/check-types/structured-object/sentence-case.md
index c78d328..d832467 100644
--- a/docs/content/reference/check-types/structured-object/sentence-case.md
+++ b/docs/content/reference/check-types/structured-object/sentence-case.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/sentence-case/"]
 
 `kind: object_sentence_case`
 
-**Targets:** collection.
-
 ## Purpose
 
 Require a string field to read as sentence case, not Title Case.
diff --git a/docs/content/reference/check-types/structured-object/string-length.md b/docs/content/reference/check-types/structured-object/string-length.md
index e48e57b..5e06d77 100644
--- a/docs/content/reference/check-types/structured-object/string-length.md
+++ b/docs/content/reference/check-types/structured-object/string-length.md
@@ -10,8 +10,6 @@ aliases = ["/reference/rules/structured-object/string-length/"]
 
 `kind: object_string_length`
 
-**Targets:** collection.
-
 ## Purpose
 
 Constrain the minimum and/or maximum length of a string field.
diff --git a/docs/content/reference/check-types/structured-object/unique-field.md b/docs/content/reference/check-types/structured-object/unique-field.md
index bb644e8..03df56c 100644
--- a/docs/content/reference/check-types/structured-object/unique-field.md
+++ b/docs/content/reference/check-types/structured-object/unique-field.md
@@ -12,7 +12,7 @@ aliases = ["/reference/rules/structured-object/unique-field/"]
 
 **Scope:** collection, runs once per collection over all its items.
 
-**Targets:** collection, filesystem.
+**Can be configured in:** collection checks, filesystem checks.
 
 ## Purpose
 
diff --git a/docs/content/reference/configs/checks.md b/docs/content/reference/configs/checks.md
index e530586..c763ef1 100644
--- a/docs/content/reference/configs/checks.md
+++ b/docs/content/reference/configs/checks.md
@@ -23,7 +23,7 @@ checks:
   - kind: filesystem_name_matches_field
 ```
 
-## Attachment targets
+## Configuration Sites
 
 Collection-attached checks run after a file belongs to a collection. They can
 use collection schemas, variants, item selectors, and collection-wide sibling
@@ -58,7 +58,7 @@ filesystemChecks:
 `katalyst check` with no selector runs filesystem scopes first, then collection
 checks. `katalyst check <collection>` and `katalyst check <collection>/<item>`
 run collection checks only. Filesystem scopes reject check types that do not
-list `filesystem` in their supported targets.
+list `filesystem` in `configurableIn`.
 
 Document-aware filesystem checks parse selected files only when needed.
 `parseFailures: error` is the default and fails the run on parse errors.
diff --git a/docs/content/reference/glossary.md b/docs/content/reference/glossary.md
index 11cb621..051b7f8 100644
--- a/docs/content/reference/glossary.md
+++ b/docs/content/reference/glossary.md
@@ -21,7 +21,7 @@ how each term maps onto today's code is documented in the per-package
 | **Body** | Everything after the closing frontmatter fence. Preserved verbatim except by `fix`. |
 | **Check** | Shorthand for a check instance when context is unambiguous. |
 | **Check instance** | One configured check: a check type plus its arguments. It is attached either to a collection under `checks:` or to a filesystem scope under `filesystemChecks[].checks`. |
-| **Check type** | The reusable definition of a constraint: one entry in katalyst's check registry (`object_required_field`, `markdown_single_h1`, ...), selected by its `kind:` id. `katalyst check-types list` lists them, including their supported attachment targets. |
+| **Check type** | The reusable definition of a constraint: one entry in katalyst's check registry (`object_required_field`, `markdown_single_h1`, ...), selected by its `kind:` id. `katalyst check-types list` lists them, including where they can be configured. |
 | **CheckLibrary** | The provider behind a check type. Native libraries (`filesystem`, `plaintext`, `markdownbodytext`, `structuredobject`) wrap hand-written checks; schema-backed libraries (`json-schema`, Vale next) compile a named schema and run items against it, and report their own availability. A library is provenance, orthogonal to the source-data family (`structuredObject`, `markdownBodyText`, `fileSystem`, `plainText`) the check reads. |
 | **Collection** | A group of items that share structure: a directory of similar files, a relational table, a Mongo collection, or a family of API resources. Collections own checks and are addressed by name. |
 | **CollectionCheck** | A check instance attached to a collection definition. CollectionChecks can run per item or once over the collection's full item set. |
@@ -53,7 +53,7 @@ how each term maps onto today's code is documented in the per-package
 | **Selector** | How a command names what to operate on: nothing (whole project), `<collection>`, or `<collection>/<item>`. |
 | **Scope** | The level an operation or backend mapping applies to: item, collection, project, or across collections. In a base, scope answers whether one matched source unit becomes an item or a collection. |
 | **Span** | The slice of body text a text rule is evaluated against, chosen by its `target`: the whole `body`, each `line`, the `first-line`, or `matched-lines` (lines matching a `select` regex). |
-| **Target** | Either an attachment target (`collection` or `filesystem`) in check descriptors, or the slice a rule tests in a specific family. For a filesystem name/path check, `target` can be `filename`, `filename-ext`, `parent-dir`, or `path-segments`; for a text rule, see Span. |
+| **Target** | The slice a rule tests in a specific family. For a filesystem name/path check, `target` can be `filename`, `filename-ext`, `parent-dir`, or `path-segments`; for a text rule, see Span. |
 | **Text rule** | A `text_*` check (`text_requires`, `text_forbids`, `text_denylist`) that tests the body as raw text, a regex or a literal denylist, independent of markdown structure. Applies to plain-text items too. |
 | **Validation result** | The product of running an item's checks: either `path: OK`, or a flat list of violations. |
 | **Variant** | A discriminated check group inside a collection (one entry of `variants:`): a `when` discriminator plus the schema/checks added for items that match it. An item runs the base checks plus the first matching variant's. |
@@ -62,7 +62,7 @@ how each term maps onto today's code is documented in the per-package
 ## Usage notes
 
 - A **check type** is the definition; a **check instance** is that check type
-  configured at an attachment target, and a **violation** is a check that
+  configured at a configuration site, and a **violation** is a check that
   failed. The [check types
   reference]({{< relref "check-types/_index.md" >}}) and `katalyst check-types
   list` enumerate check types.
diff --git a/internal/checks/AGENTS.md b/internal/checks/AGENTS.md
index aa96b64..b5c96f8 100644
--- a/internal/checks/AGENTS.md
+++ b/internal/checks/AGENTS.md
@@ -4,7 +4,7 @@ The check engine: the check types Katalyst ships, the libraries that run them,
 and the violations they produce.
 
 **Architecture and design rationale** - the model (check type vs. instance,
-family vs. library vs. attachment target vs. runtime granularity), check
+family vs. library vs. configuration site vs. runtime granularity), check
 libraries, how a check runs, and the trade-offs - live in the
 [How checks work](../../docs/content/deep-dives/domain-model/checks.md) deep-dive, which is
 the source of truth. The per-type catalog is the generated
@@ -18,9 +18,9 @@ local code conventions.
   it through the package's `register` helper (in `library.go`). To add one, see
   the [add-katalyst-check-type](../../.cursor/skills/add-katalyst-check-type/SKILL.md)
   skill.
-- Set descriptor `Targets` for every check that can attach outside a
-  collection. Empty targets mean collection-only during migration. Use
-  `checks.TargetCollection` and `checks.TargetFilesystem` rather than string
+- Set descriptor `ConfigurableIn` for every check that can attach outside a
+  collection. Empty `ConfigurableIn` means collection-only during migration. Use
+  `checks.ConfigCollection` and `checks.ConfigFilesystem` rather than string
   literals.
 - Set descriptor `NeedsDocument` when a check reads frontmatter, markdown body
   text, or source line maps. Filesystem-attached checks use it to parse lazily
diff --git a/internal/checks/config.go b/internal/checks/config.go
index 69795ba..19dfdb7 100644
--- a/internal/checks/config.go
+++ b/internal/checks/config.go
@@ -74,25 +74,25 @@ func (rc *RawCheck) UnmarshalYAML(value *yaml.Node) error {
 // BuildConfiguredInput carries the shared pieces needed to turn raw config
 // into validated configured checks.
 type BuildConfiguredInput struct {
-	ErrorContext string
-	Schema       string
-	Raw          []RawCheck
-	SchemaKnown  func(string) bool
-	Target       string
-	AllowObject  bool
+	ErrorContext   string
+	Schema         string
+	Raw            []RawCheck
+	SchemaKnown    func(string) bool
+	ConfigurableIn string
+	AllowObject    bool
 }
 
 // BuildConfigured folds an optional schema name into a leading object check
 // and parses all raw checks through the registry.
 func BuildConfigured(in BuildConfiguredInput) ([]ConfiguredCheck, error) {
-	target := in.Target
-	if target == "" {
-		target = TargetCollection
+	configurableIn := in.ConfigurableIn
+	if configurableIn == "" {
+		configurableIn = ConfigCollection
 	}
 	out := make([]ConfiguredCheck, 0, len(in.Raw)+1)
 	if in.Schema != "" {
 		if !in.AllowObject {
-			return nil, fmt.Errorf("%s: schema is not supported for %s checks", in.ErrorContext, target)
+			return nil, fmt.Errorf("%s: schema is not supported for %s checks", in.ErrorContext, configurableIn)
 		}
 		if in.SchemaKnown != nil && !in.SchemaKnown(in.Schema) {
 			return nil, fmt.Errorf("%s: unknown schema %q", in.ErrorContext, in.Schema)
@@ -103,7 +103,7 @@ func BuildConfigured(in BuildConfiguredInput) ([]ConfiguredCheck, error) {
 		kind := CheckType(strings.TrimSpace(raw.Kind))
 		if kind == CheckObject {
 			if !in.AllowObject {
-				return nil, fmt.Errorf("%s: checks[%d]: object check is not supported for %s checks", in.ErrorContext, j, target)
+				return nil, fmt.Errorf("%s: checks[%d]: object check is not supported for %s checks", in.ErrorContext, j, configurableIn)
 			}
 			if raw.Schema == "" {
 				return nil, fmt.Errorf("%s: checks[%d]: object check requires \"schema\"", in.ErrorContext, j)
@@ -121,8 +121,8 @@ func BuildConfigured(in BuildConfiguredInput) ([]ConfiguredCheck, error) {
 		if err != nil {
 			return nil, fmt.Errorf("%s: checks[%d]: %w", in.ErrorContext, j, err)
 		}
-		if !SupportsTarget(kind, target) {
-			return nil, fmt.Errorf("%s: checks[%d]: check type %q does not support %s checks", in.ErrorContext, j, kind, target)
+		if !SupportsConfiguration(kind, configurableIn) {
+			return nil, fmt.Errorf("%s: checks[%d]: check type %q does not support %s checks", in.ErrorContext, j, kind, configurableIn)
 		}
 		out = append(out, ConfiguredCheck{Kind: kind, Args: args})
 	}
diff --git a/internal/checks/filesystem/extension_in.go b/internal/checks/filesystem/extension_in.go
index 025d8ae..0450ee3 100644
--- a/internal/checks/filesystem/extension_in.go
+++ b/internal/checks/filesystem/extension_in.go
@@ -37,12 +37,12 @@ func (f FilesystemExtensionIn) Run(ctx checks.Context) []checks.Violation {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemExtensionIn,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "extension-in",
-		Title:     "Extension in",
-		Summary:   "Allow only specific file extensions.",
+		CheckType:      checks.CheckFilesystemExtensionIn,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "extension-in",
+		Title:          "Extension in",
+		Summary:        "Allow only specific file extensions.",
 		Fields: []checks.Field{
 			{Name: "values", Required: true, Desc: "Allowed extensions, including the leading dot."},
 		},
diff --git a/internal/checks/filesystem/index_file_required.go b/internal/checks/filesystem/index_file_required.go
index ac0efcf..90a7fa7 100644
--- a/internal/checks/filesystem/index_file_required.go
+++ b/internal/checks/filesystem/index_file_required.go
@@ -49,13 +49,13 @@ type indexFileArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemIndexFileRequired,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "index-file-required",
-		Title:     "Index file required",
-		Summary:   "Require that every directory containing items has an index file.",
-		Scope:     "collection",
+		CheckType:      checks.CheckFilesystemIndexFileRequired,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "index-file-required",
+		Title:          "Index file required",
+		Summary:        "Require that every directory containing items has an index file.",
+		Scope:          "collection",
 		Fields: []checks.Field{
 			{Name: "name", Required: false, Default: "_index.md", Desc: "Index filename that must be present in each item directory."},
 		},
diff --git a/internal/checks/filesystem/name_affix.go b/internal/checks/filesystem/name_affix.go
index fd59b24..ca6e3ce 100644
--- a/internal/checks/filesystem/name_affix.go
+++ b/internal/checks/filesystem/name_affix.go
@@ -42,12 +42,12 @@ type nameAffixArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemNameAffix,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "name-affix",
-		Title:     "Name affix",
-		Summary:   "Require a name to start with a prefix and/or end with a suffix.",
+		CheckType:      checks.CheckFilesystemNameAffix,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "name-affix",
+		Title:          "Name affix",
+		Summary:        "Require a name to start with a prefix and/or end with a suffix.",
 		Fields: []checks.Field{
 			{Name: "prefix", Required: false, Desc: "Required name prefix (at least one of prefix/suffix)."},
 			{Name: "suffix", Required: false, Desc: "Required name suffix (at least one of prefix/suffix)."},
diff --git a/internal/checks/filesystem/name_case.go b/internal/checks/filesystem/name_case.go
index e8a7c60..f4e7b65 100644
--- a/internal/checks/filesystem/name_case.go
+++ b/internal/checks/filesystem/name_case.go
@@ -59,12 +59,12 @@ type nameCaseArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemNameCase,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "name-case",
-		Title:     "Name case",
-		Summary:   "Require a name (or path segments) to follow a case style.",
+		CheckType:      checks.CheckFilesystemNameCase,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "name-case",
+		Title:          "Name case",
+		Summary:        "Require a name (or path segments) to follow a case style.",
 		Fields: []checks.Field{
 			{Name: "style", Required: true, Desc: "One of `kebab`, `snake`, `screaming-snake`, `camel`, `pascal`, `point`, `lower`."},
 			{Name: "target", Required: false, Default: "filename", Desc: "What to test: `filename`, `filename-ext`, `parent-dir`, or `path-segments`."},
diff --git a/internal/checks/filesystem/name_length.go b/internal/checks/filesystem/name_length.go
index e8a2082..832d0c3 100644
--- a/internal/checks/filesystem/name_length.go
+++ b/internal/checks/filesystem/name_length.go
@@ -45,12 +45,12 @@ type nameLengthArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemNameLength,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "name-length",
-		Title:     "Name length",
-		Summary:   "Bound the character length of a name.",
+		CheckType:      checks.CheckFilesystemNameLength,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "name-length",
+		Title:          "Name length",
+		Summary:        "Bound the character length of a name.",
 		Fields: []checks.Field{
 			{Name: "min", Required: false, Desc: "Minimum length (at least one of min/max)."},
 			{Name: "max", Required: false, Desc: "Maximum length (at least one of min/max)."},
diff --git a/internal/checks/filesystem/name_matches_field.go b/internal/checks/filesystem/name_matches_field.go
index a80ffd7..ef4ea76 100644
--- a/internal/checks/filesystem/name_matches_field.go
+++ b/internal/checks/filesystem/name_matches_field.go
@@ -67,13 +67,13 @@ type nameMatchesFieldArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType:     checks.CheckFilesystemNameMatchesField,
-		Family:        "fileSystem",
-		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
-		NeedsDocument: true,
-		Slug:          "name-matches-field",
-		Title:         "Name matches field",
-		Summary:       "Require a name to equal a frontmatter field, optionally slugified.",
+		CheckType:      checks.CheckFilesystemNameMatchesField,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		NeedsDocument:  true,
+		Slug:           "name-matches-field",
+		Title:          "Name matches field",
+		Summary:        "Require a name to equal a frontmatter field, optionally slugified.",
 		Fields: []checks.Field{
 			{Name: "field", Required: false, Default: "slug", Desc: "Frontmatter key compared to the name."},
 			{Name: "transform", Required: false, Default: "none", Desc: "`none` or `slugify` (applied to the field value before comparison)."},
diff --git a/internal/checks/filesystem/name_regex.go b/internal/checks/filesystem/name_regex.go
index d03c985..8a9c4d9 100644
--- a/internal/checks/filesystem/name_regex.go
+++ b/internal/checks/filesystem/name_regex.go
@@ -39,12 +39,12 @@ type nameRegexArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemNameRegex,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "name-regex",
-		Title:     "Name regex",
-		Summary:   "Require a name to match a regular expression (anchored).",
+		CheckType:      checks.CheckFilesystemNameRegex,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "name-regex",
+		Title:          "Name regex",
+		Summary:        "Require a name to match a regular expression (anchored).",
 		Fields: []checks.Field{
 			{Name: "pattern", Required: true, Desc: "Regular expression; matched anchored (`^pattern$`)."},
 			{Name: "target", Required: false, Default: "filename", Desc: "What to test: `filename`, `filename-ext`, `parent-dir`, or `path-segments`."},
diff --git a/internal/checks/filesystem/parent_dir_in.go b/internal/checks/filesystem/parent_dir_in.go
index ad72728..a9d1224 100644
--- a/internal/checks/filesystem/parent_dir_in.go
+++ b/internal/checks/filesystem/parent_dir_in.go
@@ -32,12 +32,12 @@ type parentDirInArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemParentDirIn,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "parent-dir-in",
-		Title:     "Parent directory in",
-		Summary:   "Require that the file's parent directory name is in an allowed set.",
+		CheckType:      checks.CheckFilesystemParentDirIn,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "parent-dir-in",
+		Title:          "Parent directory in",
+		Summary:        "Require that the file's parent directory name is in an allowed set.",
 		Fields: []checks.Field{
 			{Name: "values", Required: true, Desc: "Allowed parent directory names."},
 		},
diff --git a/internal/checks/filesystem/parent_dir_matches_field.go b/internal/checks/filesystem/parent_dir_matches_field.go
index b747f0d..280abf9 100644
--- a/internal/checks/filesystem/parent_dir_matches_field.go
+++ b/internal/checks/filesystem/parent_dir_matches_field.go
@@ -49,13 +49,13 @@ type parentDirMatchesArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType:     checks.CheckFilesystemParentDirMatchesFld,
-		Family:        "fileSystem",
-		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
-		NeedsDocument: true,
-		Slug:          "parent-dir-matches-field",
-		Title:         "Parent directory matches field",
-		Summary:       "Require the parent directory name to equal a frontmatter field.",
+		CheckType:      checks.CheckFilesystemParentDirMatchesFld,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		NeedsDocument:  true,
+		Slug:           "parent-dir-matches-field",
+		Title:          "Parent directory matches field",
+		Summary:        "Require the parent directory name to equal a frontmatter field.",
 		Fields: []checks.Field{
 			{Name: "field", Required: true, Desc: "Frontmatter key compared to the parent directory name."},
 		},
diff --git a/internal/checks/filesystem/path_charset.go b/internal/checks/filesystem/path_charset.go
index d26f326..99e5845 100644
--- a/internal/checks/filesystem/path_charset.go
+++ b/internal/checks/filesystem/path_charset.go
@@ -61,12 +61,12 @@ type pathCharsetArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemPathCharset,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "path-charset",
-		Title:     "Path charset",
-		Summary:   "Constrain the characters allowed in the item's path.",
+		CheckType:      checks.CheckFilesystemPathCharset,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "path-charset",
+		Title:          "Path charset",
+		Summary:        "Constrain the characters allowed in the item's path.",
 		Fields: []checks.Field{
 			{Name: "deny", Required: false, Desc: "Forbidden substrings (e.g. a space). Use `deny` or `allow`, not both."},
 			{Name: "allow", Required: false, Desc: "The only permitted characters; the path separator is always allowed."},
diff --git a/internal/checks/filesystem/path_depth.go b/internal/checks/filesystem/path_depth.go
index 5b33885..1b29dd9 100644
--- a/internal/checks/filesystem/path_depth.go
+++ b/internal/checks/filesystem/path_depth.go
@@ -58,12 +58,12 @@ type pathDepthArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemPathDepth,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "path-depth",
-		Title:     "Path depth",
-		Summary:   "Bound directory nesting relative to the collection root.",
+		CheckType:      checks.CheckFilesystemPathDepth,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "path-depth",
+		Title:          "Path depth",
+		Summary:        "Bound directory nesting relative to the collection root.",
 		Fields: []checks.Field{
 			{Name: "min", Required: false, Desc: "Minimum depth (at least one of min/max)."},
 			{Name: "max", Required: false, Desc: "Maximum depth; `0` means a flat collection (at least one of min/max)."},
diff --git a/internal/checks/filesystem/referenced_files.go b/internal/checks/filesystem/referenced_files.go
index a5bac98..45aa647 100644
--- a/internal/checks/filesystem/referenced_files.go
+++ b/internal/checks/filesystem/referenced_files.go
@@ -76,13 +76,13 @@ type referencedFilesArgs struct {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType:     checks.CheckFilesystemReferencedFiles,
-		Family:        "fileSystem",
-		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
-		NeedsDocument: true,
-		Slug:          "referenced-files-exist",
-		Title:         "Referenced files exist",
-		Summary:       "Require path-valued frontmatter fields to resolve to real files.",
+		CheckType:      checks.CheckFilesystemReferencedFiles,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		NeedsDocument:  true,
+		Slug:           "referenced-files-exist",
+		Title:          "Referenced files exist",
+		Summary:        "Require path-valued frontmatter fields to resolve to real files.",
 		Fields: []checks.Field{
 			{Name: "fields", Required: true, Desc: "Frontmatter keys holding a path (string) or list of paths, resolved relative to the item."},
 		},
diff --git a/internal/checks/filesystem/unique_filename.go b/internal/checks/filesystem/unique_filename.go
index 004d844..316d97f 100644
--- a/internal/checks/filesystem/unique_filename.go
+++ b/internal/checks/filesystem/unique_filename.go
@@ -24,13 +24,13 @@ func (UniqueFilename) RunCollection(ctx checks.CollectionContext) []checks.Viola
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemUniqueFilename,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetCollection, checks.TargetFilesystem},
-		Slug:      "unique-filename",
-		Title:     "Unique filename",
-		Summary:   "Require that no two items in the collection share a basename.",
-		Scope:     "collection",
+		CheckType:      checks.CheckFilesystemUniqueFilename,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		Slug:           "unique-filename",
+		Title:          "Unique filename",
+		Summary:        "Require that no two items in the collection share a basename.",
+		Scope:          "collection",
 		ConfigExample: `collections:
   notes:
     path: notes
diff --git a/internal/checks/filesystem/unmatched_files.go b/internal/checks/filesystem/unmatched_files.go
index 2ce13e4..6f32f31 100644
--- a/internal/checks/filesystem/unmatched_files.go
+++ b/internal/checks/filesystem/unmatched_files.go
@@ -31,13 +31,13 @@ func patternList(patterns []string) string {
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType: checks.CheckFilesystemUnmatchedFiles,
-		Family:    "fileSystem",
-		Targets:   []string{checks.TargetFilesystem},
-		Slug:      "unmatched-files",
-		Title:     "Unmatched files",
-		Summary:   "Report regular files under a filesystem scope that match neither include nor exclude patterns.",
-		Scope:     "collection",
+		CheckType:      checks.CheckFilesystemUnmatchedFiles,
+		Family:         "fileSystem",
+		ConfigurableIn: []string{checks.ConfigFilesystem},
+		Slug:           "unmatched-files",
+		Title:          "Unmatched files",
+		Summary:        "Report regular files under a filesystem scope that match neither include nor exclude patterns.",
+		Scope:          "collection",
 		ConfigExample: `filesystemChecks:
   - path: docs
     include: ["**/*.md"]
diff --git a/internal/checks/registry.go b/internal/checks/registry.go
index 635291e..05297c6 100644
--- a/internal/checks/registry.go
+++ b/internal/checks/registry.go
@@ -59,9 +59,10 @@ type Descriptor struct {
 	// Scope is "collection" for checks that run once per collection over all
 	// its items; empty means an ordinary per-item check.
 	Scope string `json:"scope,omitempty"`
-	// Targets names the config attachment points that accept this check type:
-	// "collection", "filesystem". Empty means collection during migration.
-	Targets []string `json:"targets,omitempty"`
+	// ConfigurableIn names the config attachment points that accept this check
+	// type: "collection", "filesystem". Empty means collection during
+	// migration.
+	ConfigurableIn []string `json:"configurableIn,omitempty"`
 	// NeedsDocument reports whether this check needs parsed document metadata
 	// or body text. Filesystem scopes use it to avoid parsing for path-only
 	// checks.
@@ -72,8 +73,8 @@ type Descriptor struct {
 }
 
 const (
-	TargetCollection = "collection"
-	TargetFilesystem = "filesystem"
+	ConfigCollection = "collection"
+	ConfigFilesystem = "filesystem"
 )
 
 // Family identifies a check-type family: its id (used in Descriptor.Family and
@@ -234,25 +235,26 @@ func DescriptorFor(kind CheckType) (Descriptor, bool) {
 	return registrations[i].desc, true
 }
 
-// DescriptorTargets returns the explicit or migration-default attachment
-// targets for d.
-func DescriptorTargets(d Descriptor) []string {
-	if len(d.Targets) == 0 {
-		return []string{TargetCollection}
+// DescriptorConfigurableIn returns the explicit or migration-default
+// configuration sites for d.
+func DescriptorConfigurableIn(d Descriptor) []string {
+	if len(d.ConfigurableIn) == 0 {
+		return []string{ConfigCollection}
 	}
-	out := make([]string, len(d.Targets))
-	copy(out, d.Targets)
+	out := make([]string, len(d.ConfigurableIn))
+	copy(out, d.ConfigurableIn)
 	return out
 }
 
-// SupportsTarget reports whether kind accepts the named attachment target.
-func SupportsTarget(kind CheckType, target string) bool {
+// SupportsConfiguration reports whether kind accepts the named configuration
+// site.
+func SupportsConfiguration(kind CheckType, site string) bool {
 	desc, ok := DescriptorFor(kind)
 	if !ok {
 		return false
 	}
-	for _, t := range DescriptorTargets(desc) {
-		if t == target {
+	for _, t := range DescriptorConfigurableIn(desc) {
+		if t == site {
 			return true
 		}
 	}
diff --git a/internal/checks/registry_test.go b/internal/checks/registry_test.go
index 6840834..e95fcff 100644
--- a/internal/checks/registry_test.go
+++ b/internal/checks/registry_test.go
@@ -56,20 +56,20 @@ func TestDescriptorLibrary(t *testing.T) {
 	}
 }
 
-func TestDescriptorTargets(t *testing.T) {
-	if !checks.SupportsTarget(checks.CheckFilesystemNameCase, checks.TargetCollection) {
+func TestDescriptorConfigurableIn(t *testing.T) {
+	if !checks.SupportsConfiguration(checks.CheckFilesystemNameCase, checks.ConfigCollection) {
 		t.Fatalf("filesystem_name_case should support collection checks")
 	}
-	if !checks.SupportsTarget(checks.CheckFilesystemNameCase, checks.TargetFilesystem) {
+	if !checks.SupportsConfiguration(checks.CheckFilesystemNameCase, checks.ConfigFilesystem) {
 		t.Fatalf("filesystem_name_case should support filesystem checks")
 	}
-	if checks.SupportsTarget(checks.CheckMarkdownRequiresH1, checks.TargetFilesystem) {
+	if checks.SupportsConfiguration(checks.CheckMarkdownRequiresH1, checks.ConfigFilesystem) {
 		t.Fatalf("markdown_requires_h1 should remain collection-only")
 	}
-	if !checks.SupportsTarget(checks.CheckFilesystemUnmatchedFiles, checks.TargetFilesystem) {
+	if !checks.SupportsConfiguration(checks.CheckFilesystemUnmatchedFiles, checks.ConfigFilesystem) {
 		t.Fatalf("filesystem_unmatched_files should support filesystem checks")
 	}
-	if checks.SupportsTarget(checks.CheckFilesystemUnmatchedFiles, checks.TargetCollection) {
+	if checks.SupportsConfiguration(checks.CheckFilesystemUnmatchedFiles, checks.ConfigCollection) {
 		t.Fatalf("filesystem_unmatched_files should not support collection checks")
 	}
 }
diff --git a/internal/checks/structuredobject/unique_field.go b/internal/checks/structuredobject/unique_field.go
index 3a4c888..ae7167b 100644
--- a/internal/checks/structuredobject/unique_field.go
+++ b/internal/checks/structuredobject/unique_field.go
@@ -38,14 +38,14 @@ func (c UniqueField) RunCollection(ctx checks.CollectionContext) []checks.Violat
 
 func init() {
 	registerParsed(checks.Descriptor{
-		CheckType:     checks.CheckFilesystemUniqueField,
-		Family:        "structuredObject",
-		Targets:       []string{checks.TargetCollection, checks.TargetFilesystem},
-		NeedsDocument: true,
-		Slug:          "unique-field",
-		Title:         "Unique field",
-		Summary:       "Require that no two items share a value for a frontmatter field.",
-		Scope:         "collection",
+		CheckType:      checks.CheckFilesystemUniqueField,
+		Family:         "structuredObject",
+		ConfigurableIn: []string{checks.ConfigCollection, checks.ConfigFilesystem},
+		NeedsDocument:  true,
+		Slug:           "unique-field",
+		Title:          "Unique field",
+		Summary:        "Require that no two items share a value for a frontmatter field.",
+		Scope:          "collection",
 		Fields: []checks.Field{
 			{Name: "field", Required: true, Desc: "Frontmatter key whose value must be unique across the collection."},
 		},
diff --git a/internal/storage/collection/parse.go b/internal/storage/collection/parse.go
index 64910db..5757ca6 100644
--- a/internal/storage/collection/parse.go
+++ b/internal/storage/collection/parse.go
@@ -376,12 +376,12 @@ func rejectUnsupportedSQLiteChecks(name string, base []checks.ConfiguredCheck, v
 // `collection "books"` or `collection "books": variants[0]`).
 func buildChecks(errCtx, schema string, raws []checks.RawCheck, schemaKnown func(string) bool) ([]checks.ConfiguredCheck, error) {
 	return checks.BuildConfigured(checks.BuildConfiguredInput{
-		ErrorContext: errCtx,
-		Schema:       schema,
-		Raw:          raws,
-		SchemaKnown:  schemaKnown,
-		Target:       checks.TargetCollection,
-		AllowObject:  true,
+		ErrorContext:   errCtx,
+		Schema:         schema,
+		Raw:            raws,
+		SchemaKnown:    schemaKnown,
+		ConfigurableIn: checks.ConfigCollection,
+		AllowObject:    true,
 	})
 }
 
diff --git a/internal/storage/filesystemcheck/scope.go b/internal/storage/filesystemcheck/scope.go
index 46228a1..47b6681 100644
--- a/internal/storage/filesystemcheck/scope.go
+++ b/internal/storage/filesystemcheck/scope.go
@@ -89,10 +89,10 @@ func Build(in BuildInput) (Scope, error) {
 		name = filepath.ToSlash(scopePath)
 	}
 	cks, err := checks.BuildConfigured(checks.BuildConfiguredInput{
-		ErrorContext: label,
-		Raw:          raw.Checks,
-		Target:       checks.TargetFilesystem,
-		AllowObject:  false,
+		ErrorContext:   label,
+		Raw:            raw.Checks,
+		ConfigurableIn: checks.ConfigFilesystem,
+		AllowObject:    false,
 	})
 	if err != nil {
 		return Scope{}, err
diff --git a/product/specs/filesystem-checks-plan.md b/product/specs/filesystem-checks-plan.md
index aeeb661..31f9aae 100644
--- a/product/specs/filesystem-checks-plan.md
+++ b/product/specs/filesystem-checks-plan.md
@@ -20,7 +20,7 @@
   family checks.
 - `internal/checks/registry.go` records each check type's `Descriptor`, parser,
   per-item builder, and collection-scoped builder. `Descriptor.Scope` names
-  collection-scoped runtime behavior. It has no attachment-target metadata.
+  collection-scoped runtime behavior. It has no attachment-configurableIn metadata.
 - `internal/checks/checks.go` defines per-item `Context` and `Check`.
   `internal/checks/collection.go` defines `CollectionContext` and
   `CollectionCheck`. Those names mix runtime granularity with the future
@@ -40,11 +40,11 @@
 | Phase | Focus | Scope |
 |---|---|---|
 | 1 | Failing contracts | loader tests, check CLI tests, registry tests, snapshots |
-| 2 | Shared check metadata and config parsing | descriptor targets, document needs, reusable raw check parsing |
+| 2 | Shared check metadata and config parsing | descriptor configuration sites, document needs, reusable raw check parsing |
 | 3 | Filesystem scope config and expansion | base-level `filesystemChecks`, include/exclude matching, unmatched set |
 | 4 | File and file-set runtime contexts | shared per-file context, set-level interface, collection compatibility |
 | 5 | Filesystem check execution | no-selector execution, lazy parsing, parse-failure severity, diagnostics |
-| 6 | Dual-target check types | target metadata, document-aware file-system checks, `filesystem_unmatched_files` |
+| 6 | Shared check types | configurableIn metadata, document-aware file-system checks, `filesystem_unmatched_files` |
 | 7 | Documentation and verification | user docs, generated reference, developer docs, focused test suite |
 
 The order keeps the suite honest. First pin the behavior, then add registry and
@@ -64,7 +64,7 @@ exists.
    nested `checks`.
 2. **File:** `internal/project/loader_test.go`.
    Add rejection tests for missing `include`, unknown `parseFailures`, unknown
-   check kind, a check kind that does not support the `filesystem` target, and
+   check kind, a check kind that cannot be configured in `filesystem`, and
    `filesystemChecks` on a SQLite base.
 3. **File:** `cmd/check_test.go`.
    Add a no-selector CLI test where a project has no collections, a filesystem
@@ -85,7 +85,7 @@ exists.
    Add snapshots for filesystem diagnostics: path-rule failure, parse warning,
    and filesystem unmatched file.
 8. **File:** `internal/checks/registry_test.go`.
-   Add descriptor tests for supported targets and document-needs metadata.
+   Add descriptor tests for supported configuration sites and document-needs metadata.
 
 ### Phase 2 - Shared check metadata and config parsing
 
@@ -93,9 +93,10 @@ exists.
 collection and filesystem config.
 
 1. **File:** `internal/checks/registry.go`.
-   Add target constants, `Descriptor.Targets []string`, and helpers such as
-   `SupportsTarget(kind, target)` and `DescriptorTargets(d)`. Treat an empty
-   target list as `collection` during migration.
+   Add configuration-site constants, `Descriptor.ConfigurableIn []string`, and
+   helpers such as `SupportsConfiguration(kind, site)` and
+   `DescriptorConfigurableIn(d)`. Treat an empty list as `collection` during
+   migration.
 2. **File:** `internal/checks/registry.go`.
    Add document-needs metadata to `Descriptor`, for example
    `NeedsDocument bool`, plus `NeedsDocument(kind)`. Filesystem scopes use this
@@ -113,10 +114,10 @@ collection and filesystem config.
    Keep SQLite collection rejection based on descriptor family or target support
    so existing behavior stays stable.
 6. **File:** `cmd/check_types.go`.
-   Include supported targets in `check-types show` and JSON output through the
+   Include supported configuration sites in `check-types show` and JSON output through the
    descriptor. Keep existing scope and severity output.
 7. **File:** `cmd/gendocs/main.go`.
-   Render supported targets on generated check-type pages. Keep generated docs
+   Render supported configuration sites on generated check-type pages. Keep generated docs
    deterministic.
 
 ### Phase 3 - Filesystem scope config and expansion
@@ -223,7 +224,7 @@ the new unmatched-files check ships.
    `FileSetContext.Unmatched`. It emits one violation per unmatched file and
    includes include/exclude patterns in the message.
 3. **File:** `internal/checks/filesystem/*.go`.
-   Add `Targets: []string{"collection", "filesystem"}` to file-system check
+   Add `ConfigurableIn: []string{"collection", "filesystem"}` to file-system check
    descriptors that work under both attachment points.
 4. **File:** `internal/checks/filesystem/name_matches_field.go`,
    `parent_dir_matches_field.go`, and `referenced_files.go`.
@@ -246,22 +247,22 @@ the new unmatched-files check ships.
 model.
 
 1. **File:** `docs/content/deep-dives/domain-model/checks.md`.
-   Split data family, library, attachment target, and runtime granularity.
+   Split data family, library, configuration site, and runtime granularity.
 2. **File:** `docs/content/reference/configuration.md`.
    Document `filesystemChecks` under filesystem bases. Note the legacy
    `.katalyst/storage/` reader only if that page still documents legacy config.
 3. **File:** `docs/content/reference/glossary.md`.
    Add CollectionCheck, FilesystemCheck, FileCheck, FileSetCheck, and
-   attachment target. Update Check instance and Collection-scoped check.
+   configuration site. Update Check instance and Collection-scoped check.
 4. **File:** `docs/content/how-to/configure-rules.md`.
    Add a pre-collection filesystem check workflow.
 5. **File:** `internal/checks/AGENTS.md`.
-   Document descriptor target metadata and the runtime naming distinction.
+   Document descriptor configurableIn metadata and the runtime naming distinction.
 6. **File:** `internal/storage/collection/AGENTS.md`.
    Document that collection `checks:` remain collection-attached and filesystem
    checks live on filesystem bases.
 7. **File:** `.cursor/skills/add-katalyst-check-type/SKILL.md`.
-   Update the checklist so new check types declare supported attachment targets
+   Update the checklist so new check types declare supported configuration sites
    and document needs.
 8. **File:** `docs/content/reference/check-types/`.
    Run `make docs-gen` after descriptor rendering changes.
@@ -289,18 +290,18 @@ model.
 | `internal/storage/filesystemcheck/scope_test.go` | filesystem scope matching tests |
 | `internal/storage/collection/parse.go` | consumes shared check config helper for collection checks |
 | `internal/storage/collection/filesystem/collection.go` | reference for deterministic filesystem traversal and matching |
-| `internal/checks/registry.go` | descriptor targets, document needs, and registry helpers |
+| `internal/checks/registry.go` | descriptor configuration sites, document needs, and registry helpers |
 | `internal/checks/config.go` | shared raw check config parser for both attachment points |
 | `internal/checks/checks.go` | per-file context compatibility layer |
 | `internal/checks/collection.go` | file-set context and compatibility wrappers |
 | `internal/checks/kinds.go` | new `filesystem_unmatched_files` kind constant |
 | `internal/checks/filesystem/unmatched_files.go` | new unmatched-files check |
-| `internal/checks/filesystem/*.go` | target metadata and document-needs metadata for file-system checks |
-| `internal/checks/structuredobject/unique_field.go` | dual-target metadata-aware set-level check |
-| `cmd/check_types.go` | CLI descriptor rendering for supported targets |
-| `cmd/gendocs/main.go` | generated check-type page rendering for supported targets |
-| `docs/content/deep-dives/domain-model/checks.md` | durable explanation of target vs family vs granularity |
-| `docs/content/reference/configuration.md` | user-facing filesystemChecks config reference |
+| `internal/checks/filesystem/*.go` | configurableIn metadata and document-needs metadata for file-system checks |
+| `internal/checks/structuredobject/unique_field.go` | metadata-aware set-level check configurable in both sites |
+| `cmd/check_types.go` | CLI descriptor rendering for supported configuration sites |
+| `cmd/gendocs/main.go` | generated check-type page rendering for supported configuration sites |
+| `docs/content/deep-dives/domain-model/checks.md` | durable explanation of configurableIn vs family vs granularity |
+| `docs/content/reference/configs/bases.md` | user-facing filesystemChecks config reference |
 | `docs/content/reference/glossary.md` | new vocabulary |
 | `docs/content/how-to/configure-rules.md` | pre-collection filesystem check workflow |
 | `internal/checks/AGENTS.md` | developer convention for check descriptors |
@@ -313,9 +314,9 @@ model.
 |---|---|---|
 | Config home | base-level `filesystemChecks` | the current code's configured backend instance is a base, and the base owns root path resolution |
 | Legacy storage config | parse the same field when legacy `.katalyst/storage/` is used | keeps legacy storage files aligned with base config behavior |
-| Collection config key | keep collection `checks:` | the collection block already supplies the attachment target and existing configs keep working |
+| Collection config key | keep collection `checks:` | the collection block already supplies the configuration site and existing configs keep working |
 | Shared check parsing | move raw check parsing into `internal/checks` | collection and filesystem attachments need the same `kind` and args parser without duplicating `RawCheck` |
-| Target metadata | descriptor-level `Targets` with empty meaning collection | existing descriptors migrate incrementally and docs can render one source of truth |
+| ConfigurableIn metadata | descriptor-level `ConfigurableIn` with empty meaning collection | existing descriptors migrate incrementally and docs can render one source of truth |
 | Document parsing | descriptor-level document-needs metadata | filesystem scopes parse lazily and path-only checks stay path-only |
 | Parse failure policy | scope-level `parseFailures`, default `error` | CI stays strict by default while onboarding can opt into warnings |
 | Runtime contexts | add file and file-set contexts with compatibility wrappers | the implementation can share checks without renaming every interface in one step |
@@ -325,7 +326,7 @@ model.
 ## Documentation updates
 
 - **Phase 7, File:** `docs/content/deep-dives/domain-model/checks.md`.
-  Explain data family, library, attachment target, and runtime granularity.
+  Explain data family, library, configuration site, and runtime granularity.
 - **Phase 7, File:** `docs/content/reference/configuration.md`.
   Add `filesystemChecks` keys, defaults, examples, parse-failure severity, and
   unmatched-files check usage.
diff --git a/product/specs/filesystem-checks-spec.md b/product/specs/filesystem-checks-spec.md
index bf452a3..e565783 100644
--- a/product/specs/filesystem-checks-spec.md
+++ b/product/specs/filesystem-checks-spec.md
@@ -64,21 +64,21 @@ This spec separates those axes.
 
 ## Design
 
-### Attachment Targets
+### Configuration Sites
 
-Add an attachment-target axis to check descriptors:
+Add a configuration-site axis to check descriptors:
 
 ```go
 type Descriptor struct {
     // existing fields...
-    Targets []string // "collection", "filesystem"
+    ConfigurableIn []string // "collection", "filesystem"
 }
 ```
 
 `Family` keeps its current meaning: the source data the check reads.
-`Targets` says where a check instance may be configured.
+`ConfigurableIn` says where a check instance may be configured.
 
-During migration, an empty `Targets` means `["collection"]`. That keeps every
+During migration, an empty `ConfigurableIn` means `["collection"]`. That keeps every
 existing check valid until each descriptor opts into filesystem attachment.
 
 Use these concepts in product language:
@@ -108,7 +108,7 @@ collections:
 ```
 
 Do not rename collection `checks:` to `collectionChecks:`. Inside a collection,
-the attachment target is already clear. A rename adds migration cost without
+the configuration site is already clear. A rename adds migration cost without
 making the config easier to write.
 
 Add `filesystemChecks` to filesystem storage instances:
@@ -164,7 +164,7 @@ expectations. Set it to `warning` for onboarding a messy tree while still
 surfacing skipped document-aware checks.
 
 The same check type can appear in both attachment sites when its descriptor
-supports both targets:
+supports both configuration sites:
 
 ```yaml
 type: filesystem
@@ -322,7 +322,7 @@ filesystem posts: content/posts/broken.md: warning: /: cannot parse document: in
 The runner always reports parse failures. A passing run proves that every
 selected file needed by a document-aware check was inspected.
 
-This lets almost every current filesystem-related check run under both targets:
+This lets almost every current filesystem-related check run under both configuration sites:
 
 | Check type | CollectionChecks | FilesystemChecks |
 |---|---:|---:|
@@ -402,7 +402,7 @@ main onboarding and CI cases.
 
 ### Diagnostics
 
-Diagnostics name the attachment target:
+Diagnostics name the configuration site:
 
 ```text
 filesystem docs: docs/content/Old Note.md: /path: filename is not kebab-case
@@ -428,12 +428,12 @@ Existing configs keep working:
 
 Implementation is additive:
 
-1. Add descriptor target metadata, defaulting to `collection`.
+1. Add descriptor configurableIn metadata, defaulting to `collection`.
 2. Add file and file-set runtime contexts without changing behavior.
 3. Add `filesystemChecks` parsing to filesystem storage instances.
 4. Run path-only FilesystemChecks.
 5. Add lazy document parsing and opt metadata-aware check types into the
-   filesystem target.
+   filesystem configuration site.
 6. Rename internal set-level interfaces away from `CollectionCheck`.
 
 ## Open Questions
@@ -442,24 +442,24 @@ _None._
 
 ## Documentation Updates
 
-- `docs/content/deep-dives/checks.md`: split data family, library,
-  attachment target, and runtime granularity.
-- `docs/content/reference/configuration.md`: document storage-level
+- `docs/content/deep-dives/domain-model/checks.md`: split data family,
+  library, configuration site, and runtime granularity.
+- `docs/content/reference/configs/bases.md`: document storage-level
   `filesystemChecks`.
 - `docs/content/reference/glossary.md`: add CollectionCheck, FilesystemCheck,
-  FileCheck, FileSetCheck, and attachment target. Update Check instance and
+  FileCheck, FileSetCheck, and configuration site. Update Check instance and
   Collection-scoped check.
 - `docs/content/how-to/configure-rules.md`: add a pre-collection filesystem
   check workflow.
-- Generated check-type reference: render supported targets and file vs.
+- Generated check-type reference: render supported configuration sites and file vs.
   file-set granularity from descriptors. Run `make docs-gen`.
-- `internal/checks/AGENTS.md`: document descriptor target metadata and the
+- `internal/checks/AGENTS.md`: document descriptor configurableIn metadata and the
   runtime naming distinction.
 - `internal/storage/collection/AGENTS.md`: document that collection `checks:`
   remain collection-attached and filesystem checks live on filesystem storage
   instances.
 - `.cursor/skills/add-katalyst-check-type/SKILL.md`: update the checklist so a
-  new check type declares supported attachment targets.
+  new check type declares supported configuration sites.
 
 ## Rejected Alternatives