@noctcore/lint-meta-rules 0.6.0 → 0.6.1

package/docs/rules/github-actions-runner-pinned.md

@@ -2,6 +2,10 @@
 
 > Workflow jobs run on a named runner image, never a `*-latest` label.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createGithubActionsRunnerPinnedRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 GitHub repoints `ubuntu-latest` (and `macos-latest`, `windows-latest`) to a new OS image on its own
@@ -11,8 +15,7 @@ repo. Pinning a named image makes the move a reviewed diff.
 ## What it flags
 
 Every floating label in a `runs-on:` value, read as a scalar, a flow list (`[a, b]`), a block list, or
-a `group:` / `labels:` mapping. An expression (`${{ matrix.os }}`) cannot be judged from the text and
-is left alone; a commented-out `runs-on:` is ignored.
+a `group:` / `labels:` mapping.
 
 ```yaml
 # Bad
@@ -24,7 +27,17 @@ runs-on: ubuntu-24.04
 runs-on: ${{ matrix.os }}
 ```
 
-## Factory
+## What it does not flag
+
+- A named image (`ubuntu-24.04`), quoted or with a trailing comment, and a custom label such as
+  `self-hosted`.
+- An expression (`${{ matrix.os }}`): it cannot be judged from the text.
+- A commented-out `runs-on:`, and a later key in the job (`name: ubuntu-latest`) after the label list.
+
+Line-based text, not a YAML parse. A matrix value such as `os: [ubuntu-latest]` that feeds
+`runs-on: ${{ matrix.os }}` is not checked.
+
+## Options
 
 ```ts
 createGithubActionsRunnerPinnedRule(options?: GithubActionsRunnerPinnedOptions): IMetaRule
@@ -36,7 +49,7 @@ createGithubActionsRunnerPinnedRule(options?: GithubActionsRunnerPinnedOptions):
 | `floatingLabel` | `RegExp` | `/^[\w.-]+-latest$/u` | A label matching this is floating. Do not pass a `g`-flagged regex. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-Line-based text, not a YAML parse. A matrix value such as `os: [ubuntu-latest]` that feeds
-`runs-on: ${{ matrix.os }}` is not checked.
+If you want your CI to track GitHub's newest runner images automatically and accept the unreviewed
+moves, skip it.

package/docs/rules/github-actions-sha-pinned.md

@@ -2,6 +2,10 @@
 
 > GitHub Actions `uses:` refs are pinned to a 40-character commit SHA with a `# vN` comment.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createGithubActionsShaPinnedRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A tag or branch ref is a moving target: whoever controls the action's repository can repoint it, and
@@ -17,7 +21,7 @@ Every `uses:` line (step-level and job-level reusable workflow calls) in the sca
 - a SHA-pinned ref with no `# vN` comment,
 - a `docker://` ref with no `@sha256:<digest>`.
 
-Local actions (`uses: ./path`) are exempt. Each violation carries the 1-indexed line.
+Each violation carries the 1-indexed line.
 
 ```yaml
 # Bad
@@ -29,7 +33,17 @@ Local actions (`uses: ./path`) are exempt. Each violation carries the 1-indexed
 - uses: ./.github/actions/setup
 ```
 
-## Factory
+## What it does not flag
+
+- Local actions (`uses: ./path`).
+- A full 40-character SHA with a `# vN` comment, quoted or not, including a path inside the action
+  repo (`github/codeql-action/analyze@<sha> # v3`).
+- A `docker://` ref pinned by `@sha256:<digest>`.
+
+The check is line-based text, not a YAML parse. A `uses:` value split across lines, or built from an
+expression, is not seen.
+
+## Options
 
 ```ts
 createGithubActionsShaPinnedRule(options?: GithubActionsShaPinnedOptions): IMetaRule
@@ -40,7 +54,7 @@ createGithubActionsShaPinnedRule(options?: GithubActionsShaPinnedOptions): IMeta
 | `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-The check is line-based text, not a YAML parse. A `uses:` value split across lines, or built from an
-expression, is not seen.
+If your repo has no GitHub Actions workflows, or you accept tag refs and review action updates some
+other way, skip it.

package/docs/rules/idempotency-key-parity.md

@@ -3,6 +3,10 @@
 > A procedure guarded by an idempotency middleware has a client caller that sends the key, or no
 > client caller at all.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createIdempotencyKeyParityRule` from `@noctcore/lint-meta-rules/trpc` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `trpc` entry point:
 
 ```ts
@@ -14,8 +18,8 @@ import { createIdempotencyKeyParityRule } from '@noctcore/lint-meta-rules/trpc';
 An idempotency middleware only de-duplicates when the client sends a key, and neither half fails when
 the other is missing. The server passes the request straight through, the client gets a normal
 response, and both test suites pass. A guard nobody sends a key to is decoration advertising
-double-submit protection that does not exist. In the project this rule was extracted from, an audit
-found 14 of 30 guarded procedures whose only web caller had never sent a key.
+double-submit protection that does not exist. One audit of a production API found 14 of 30 guarded
+procedures whose only web caller had never sent a key.
 
 The gap is only visible by holding the two lists side by side, which is what this rule does.
 
@@ -30,7 +34,7 @@ reported.
 The method is read from the decorator to the next `async <name>(`, the shape `nestjs-trpc` routers
 take.
 
-## What it leaves alone
+## What it does not flag
 
 - A guarded procedure with no client caller: the guard is correct in advance of the screen that will
   use it, and demanding a caller would be demanding the screen.
@@ -44,7 +48,7 @@ file, if `clientGlobs` match it: the check is per procedure, across the client t
 
 With no `middleware` the rule is inert.
 
-## Factory
+## Options
 
 ```ts
 createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule
@@ -66,7 +70,11 @@ createIdempotencyKeyParityRule(options?: IdempotencyKeyParityOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message: how this project threads the key. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with an idempotency middleware
+
+A NestJS API guards its mutations with an `IdempotencyMiddleware` in `*.router.ts` files, and a web app
+calls them through tRPC hooks. The `hint` tells whoever hits a violation how the web app threads the
+key:
 
 ```ts
 createIdempotencyKeyParityRule({

package/docs/rules/layer-rank.md

@@ -3,6 +3,10 @@
 > A module may import only strictly-lower-ranked `<scope>` packages — equal (sideways) or higher
 > (upward) is forbidden.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createLayerRankRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Layered architectures encode a fixed dependency direction (e.g. `contracts → shared → storage/skills
@@ -15,11 +19,19 @@ are caught before they calcify.
 Each source file is assigned an **importer rank**: surface files (matched by `surfacePrefix`) get
 `surfaceRank`; otherwise the `packageDirPattern` capture is looked up in `ranks`. For each
 `<scope>/<pkg>` import whose target is also ranked, the rule flags it when the target rank is `>=` the
-importer rank (sideways when equal, upward when greater). Unranked importers and unranked targets are
-skipped, so a package outside the documented spine never produces a false positive. Test files are
-skipped.
+importer rank (sideways when equal, upward when greater).
+
+## What it does not flag
+
+- A downward import: the target's rank is strictly lower than the importer's.
+- Unranked importers and unranked targets, so a package outside the documented spine never produces a
+  false positive. Surface files are unranked unless `surfaceRank` is set.
+- Test files (`.test.ts`, `.test.tsx`).
+- Imports without a `from` clause (`import '<scope>/x'`, `import()`, `require()`): only
+  `from '<scope>/<pkg>'` is read.
+- Anything at all while `ranks` is empty.
 
-## Factory
+## Options
 
 ```ts
 createLayerRankRule(options?: LayerRankOptions): IMetaRule
@@ -35,8 +47,7 @@ createLayerRankRule(options?: LayerRankOptions): IMetaRule
 | `sourceGlobs` | `string[]` | packages + apps `src/**` `.ts`/`.tsx` | Source files to scan. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded a fixed rank table and the `@nightcore` scope. `ranks`
-defaults to `{}` so the rule is inert until a consumer supplies its own layering.
+`ranks` defaults to `{}`, so the rule is inert until you supply your own layering.
 
 ## When not to use it
 

package/docs/rules/no-cloned-component-folders.md

@@ -2,6 +2,10 @@
 
 > A component folder name may exist under only one feature.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createNoClonedComponentFoldersRule` from `@noctcore/lint-meta-rules` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Same-named component folders across features are how sibling drift starts: a component cloned into a
@@ -16,7 +20,15 @@ A `<feature>/<Name>/<barrelFile>` path marks a component folder. Grouping by `<N
 `allowedClones` — is flagged. The allowlist freezes today's clone groups and only shrinks: an
 `allowedClones` entry whose clone group no longer exists is itself flagged as stale.
 
-## Factory
+## What it does not flag
+
+- A component folder name that exists under only one feature.
+- Folders under `excludedFeatures` (`ui` and `app` by default).
+- Names in `allowedClones` while their clone group still exists.
+- Folders without the `barrelFile`, and folders nested deeper than `<feature>/<Name>/` under
+  `componentsRoot`.
+
+## Options
 
 ```ts
 createNoClonedComponentFoldersRule(options?: NoClonedComponentFoldersOptions): IMetaRule
@@ -31,9 +43,6 @@ createNoClonedComponentFoldersRule(options?: NoClonedComponentFoldersOptions): I
 | `sharedDest` | `string` | `'components/ui'` | Where a shared surface should be hoisted (used in the message). |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `apps/web/src/components`, the `ui`/`app` excluded
-features, and a fixed `ALLOWED_CLONES` set.
-
 ## When not to use it
 
 If your components are not organized as `<feature>/<Component>/` folders under one root, or you

package/docs/rules/no-warn-severity.md

@@ -2,6 +2,10 @@
 
 > ESLint severity is `error` or `off`, never `warn`.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createNoWarnSeverityRule` from `@noctcore/lint-meta-rules` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Agents iterate by reading CI failures. A `warn` severity is a silent miss — it neither fails the
@@ -14,7 +18,16 @@ Reads each configured flat-config file (skipping any that do not exist), strips
 reports any line containing a `'warn'` / `"warn"` severity literal. The violation carries the
 1-indexed line number.
 
-## Factory
+## What it does not flag
+
+- A `'warn'` inside a `//` line comment.
+- The numeric severity `1`: only the quoted `'warn'` / `"warn"` literal is matched.
+- A `warn` a spread preset injects, since no file the project owns spells it. Use
+  [`eslint-config-no-warn`](./eslint-config-no-warn.md) for the resolved config.
+- Config files not listed in `configFiles` (the defaults are the root flat configs), and listed ones that
+  do not exist.
+
+## Options
 
 ```ts
 createNoWarnSeverityRule(options?: NoWarnSeverityOptions): IMetaRule
@@ -25,8 +38,6 @@ createNoWarnSeverityRule(options?: NoWarnSeverityOptions): IMetaRule
 | `configFiles` | `string[]` | `['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs']` | Flat-config files to scan; each is read only if present. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded `eslint.config.mjs`.
-
 ## When not to use it
 
 If your project deliberately uses `warn` as an in-editor nudge that is not meant to gate CI, this rule

package/docs/rules/package-shape.md

@@ -3,6 +3,10 @@
 > Every workspace is named `<scope>/<dir>`; library packages expose a barrel and point their build
 > fields at the built output.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createPackageShapeRule` from `@noctcore/lint-meta-rules` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A monorepo stays navigable when a package's identity is mechanical: its npm name matches its folder,
@@ -20,10 +24,16 @@ For each `package.json` matched by `libraryGlobs` (full checks) or `appGlobs` (n
   `distMarker`, and `exports` must reference it.
 - **invalid JSON** — reported as a violation.
 
-App/surface packages are deployable entrypoints (vite/tauri/bun), so only the name check applies to
-them.
+## What it does not flag
+
+- Barrel and build-field problems in app/surface packages: they are deployable entrypoints
+  (vite/tauri/bun), so only the name check applies to them.
+- A package whose directory has an `externalNames` entry and whose name equals it.
+- A missing `distFields` entry or a missing `exports`: only fields that are present are checked, and
+  `exports` passes when any of its targets contains `distMarker`.
+- `package.json` files outside `libraryGlobs` and `appGlobs`.
 
-## Factory
+## Options
 
 ```ts
 createPackageShapeRule(options?: PackageShapeOptions): IMetaRule
@@ -40,9 +50,6 @@ createPackageShapeRule(options?: PackageShapeOptions): IMetaRule
 | `distFields` | `string[]` | `['main','module','types']` | `package.json` string fields that must point at built output. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-De-projected from nightcore, which hardcoded the `@nightcore` scope, the `packages/*` vs `apps/*`
-split, the `src/index.ts` barrel and the `dist/` marker.
-
 ## When not to use it
 
 If your packages are not scope-named after their folders, or libraries publish raw source (no build

package/docs/rules/prisma-method-surface.md

@@ -3,6 +3,10 @@
 > The Prisma reads and writes your rules police partition the generated client's `<Model>Delegate`
 > method surface exactly, so a Prisma upgrade cannot add an unguarded method.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createPrismaMethodSurfaceRule` from `@noctcore/lint-meta-rules/prisma` · Category `config` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `prisma` entry point:
 
 ```ts
@@ -30,10 +34,16 @@ configured reads and writes are exactly its delegate surface.
 It **fails closed**: no generated client under `clientGlobs` is a violation, because a checkout that
 never ran `prisma generate` is exactly where drift hides. Run `prisma generate` before lint-meta.
 
+## What it does not flag
+
+- A generated client whose delegates expose exactly the configured reads and writes, in either the
+  per-model (`prisma-client`) or the single-file (`prisma-client-js`) layout.
+- Members that are not query methods: `fields`, the symbol brand and `$`-prefixed members.
+
 Members are read line by line: a delegate method is a generic, `name<T ...>(...)`, at the interface's
-member indentation. `fields`, the symbol brand and `$`-prefixed members are not query methods.
+member indentation, so a non-generic member is not counted.
 
-## Factory
+## Options
 
 ```ts
 createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule
@@ -50,9 +60,9 @@ createPrismaMethodSurfaceRule(options?: PrismaMethodSurfaceOptions): IMetaRule
 With the defaults, the rule checks the exact lists `@noctcore/eslint-plugin-prisma`'s rules read.
 If your own rules read their own lists, pass those.
 
-## Worked example: Settly
+### Worked example: a monorepo with a database package
 
-Settly's schema generates into `packages/database/generated/prisma` with the `prisma-client`
+A schema that generates into `packages/database/generated/prisma` with the `prisma-client`
 generator:
 
 ```ts
@@ -63,3 +73,8 @@ createPrismaMethodSurfaceRule({
 
 Adding a method to every generated delegate reports it as unguarded; adding it to one model only
 reports that delegate as divergent; removing the generated folder reports that no client was found.
+
+## When not to use it
+
+If no lint rule of yours reads a list of Prisma method names (no tenant, writer or transaction fence),
+there is no list to keep in step, so skip it.

package/docs/rules/security-scanner-version-parity.md

@@ -3,6 +3,10 @@
 > CI and the local pre-push hook pin the same secret-scanner version, and the hook checks it at run
 > time.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSecurityScannerVersionParityRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 Different scanner versions ship different rulesets, so a push can pass the local hook and fail CI (or
@@ -20,8 +24,6 @@ With the defaults (gitleaks):
 - a hook `GITLEAKS_IMAGE="...gitleaks:vX.Y.Z"` tag that differs from CI,
 - a hook that never runs `gitleaks version`.
 
-Dormant when neither the workflows nor the hook mention the scanner.
-
 ```yaml
 # .github/workflows/security.yml
 env:
@@ -39,7 +41,15 @@ GITLEAKS_VERSION="8.29.0"
 gitleaks git .
 ```
 
-## Factory
+## What it does not flag
+
+- A repo where neither the workflows nor the hook mention the scanner: the rule is dormant.
+- Whether the hook's version comparison is correct: it checks only that the hook's text runs
+  `<scanner> version`.
+- Versions not written as `x.y.z`, and any hook other than `hookFile`. A repo with several hooks needs
+  one rule instance per hook.
+
+## Options
 
 ```ts
 createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOptions): IMetaRule
@@ -54,8 +64,7 @@ createSecurityScannerVersionParityRule(options?: SecurityScannerVersionParityOpt
 | `workflowGlobs` | `string[]` | `['.github/workflows/*.yml', '.github/workflows/*.yaml']` | Workflow files to scan. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-It checks that the hook's text runs `<scanner> version`, not that the comparison is correct, and it
-reads only `x.y.z` versions. One hook file is checked; a repo with several hooks needs one rule
-instance per hook.
+If you run the secret scanner in only one place (CI or a local hook, not both), there is no second pin
+to keep in step.

package/docs/rules/service-image-digest-pin.md

@@ -2,6 +2,10 @@
 
 > Workflow service/container images and docker-compose images are pinned by `@sha256:` digest.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createServiceImageDigestPinRule` from `@noctcore/lint-meta-rules` · Category `ci` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 ## Why
 
 A tag (`postgres:17-alpine`) or `latest` names whatever the registry serves today, so a green build
@@ -11,9 +15,9 @@ can change under an unchanged commit, and a local run cannot promise the bytes C
 ## What it flags
 
 - In workflow files: `image:` under a job's `services:`, and a job's `container:` in scalar or mapping
-  form. An action step's `with: image:` input is not an image pull and is ignored.
-- In compose files: every service's `image:`, except a service that also has `build:` (there `image:`
-  tags an image built locally, which has no upstream digest).
+  form.
+- In compose files: every service's `image:`, including one behind an env default
+  (`${REDIS_IMAGE:-redis:7}`), which is reported as written since the text does not show a digest.
 
 Each violation carries the 1-indexed line.
 
@@ -32,7 +36,17 @@ services:
     image: app-api:local
 ```
 
-## Factory
+## What it does not flag
+
+- An image pinned as `tag@sha256:<digest>`.
+- An action step's `with: image:` input: it is not an image pull.
+- A compose service that also has `build:`: there `image:` tags an image built locally, which has no
+  upstream digest.
+- An exact ref listed in `allowUnpinned`, and compose files under a `skipDirs` segment.
+
+The check is line-based text, not a YAML parse.
+
+## Options
 
 ```ts
 createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRule
@@ -46,7 +60,7 @@ createServiceImageDigestPinRule(options?: ServiceImageDigestPinOptions): IMetaRu
 | `allowUnpinned` | `string[]` | `[]` | Exact image refs allowed unpinned, for a ref the registry cannot serve a digest for. Only that exact ref passes; a bumped tag is checked again. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Limits
+## When not to use it
 
-Line-based text, not a YAML parse. An image behind an env default (`${REDIS_IMAGE:-redis:7}`) is
-reported as written, since the text does not show a digest.
+If your workflows and compose files only run throwaway local services where you accept whatever a tag
+serves today, skip it.

package/docs/rules/session-epoch-captured.md

@@ -3,6 +3,10 @@
 > Every call into the sign-in seam passes the session epoch it captured before reading the
 > credential.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionEpochCapturedRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -25,9 +29,11 @@ never mention the epoch.
 ## What it flags
 
 Each `.<call>(...)` call in a file matched by `sourceGlobs` whose argument text (found by balancing
-parentheses) does not mention `field` as a whole word.
+parentheses) does not mention `field` as a whole word. The parenthesis scanner reads each call on its
+own, so a call written on one line is checked too, and an unstamped call cannot borrow the epoch of
+the next one.
 
-## What it leaves alone
+## What it does not flag
 
 - `epochless: true`, or any identifier that merely contains the field: whole words only.
 - Files in `exempt` (the seam's own home, which defines the method and its default).
@@ -35,11 +41,7 @@ parentheses) does not mention `field` as a whole word.
 
 With no `call` the rule is inert.
 
-Ported from Settly, whose rule matched calls with a regex that stopped at the first `\n );` after the
-call. That missed a call written on one line, and let an unstamped one-line call borrow the epoch of
-the next multi-line call. The parenthesis scanner here reads each call on its own.
-
-## Factory
+## Options
 
 ```ts
 createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule
@@ -58,7 +60,11 @@ createSessionEpochCapturedRule(options?: SessionEpochCapturedOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with a post-credential sign-in seam
+
+Every sign-in entry point (password, OAuth, second factor) ends by calling one seam,
+`beginOrEstablish`, which a two-factor challenge service defines. Each entry point reads the epoch with
+`sessionService.readEpoch(userId)` before it checks the credential, and passes it in:
 
 ```ts
 createSessionEpochCapturedRule({
@@ -74,7 +80,7 @@ createSessionEpochCapturedRule({
 });
 ```
 
-Two Settly flows mint without a captured epoch and are outside the rule by construction, because they
+Two flows in such an app mint without a captured epoch and are outside the rule by construction, because they
 never call the seam: signup (the account did not exist when the request began) and password change (it
 revokes first and then re-issues, so the current counter is the right one).
 

package/docs/rules/session-kind-stamped.md

@@ -3,6 +3,10 @@
 > Every call that mints a session stamps the principal's kind onto it, or sits in an allowlisted,
 > provably single-kind flow.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionKindStampedRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -17,7 +21,7 @@ mint that wrote it. A session minted without the field reads as whatever the rea
 fence between the two kinds that is a silent promotion: a portal account whose session lost its stamp
 is a staff caller inside its own tenant, and the tenant boundary waves it through as legitimate.
 
-This is not hypothetical. In the project this rule was extracted from, two re-issue paths (a password
+This is not hypothetical. In one production codebase, two re-issue paths (a password
 change and a revoke-other-sessions action, both reachable by a portal account) shipped without the
 stamp while every gate was green, because nothing mechanical looked.
 
@@ -32,10 +36,7 @@ parentheses, so a multi-line options object with nested calls is read whole):
    somewhere. Coarser, but no silent hole.
 3. Otherwise the file must be in `allowUnstamped`.
 
-Residual gap, stated rather than hidden: a file that stamps the field on one delegated mint and forgets
-it on a second delegated mint passes clause 2.
-
-## What it leaves alone
+## What it does not flag
 
 - `.<mintCall>Something(`, and the method's definition.
 - `kindless` or `kinds`: the field must appear as a whole word.
@@ -43,7 +44,10 @@ it on a second delegated mint passes clause 2.
 
 With no `mintCall` the rule is inert.
 
-## Factory
+Residual gap, stated rather than hidden: a file that stamps the field on one delegated mint and forgets
+it on a second delegated mint passes clause 2.
+
+## Options
 
 ```ts
 createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule
@@ -62,7 +66,11 @@ createSessionKindStampedRule(options?: SessionKindStampedOptions): IMetaRule
 | `hint` | `string` | none | Appended to every message. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with staff and portal accounts
+
+One sign-in serves staff accounts and invite-only portal accounts, and every session mint goes
+through `establishSession`. Self-signup only ever creates staff accounts, so its file is allowed to
+mint without a stamp:
 
 ```ts
 createSessionKindStampedRule({

package/docs/rules/session-landing-declared.md

@@ -3,6 +3,10 @@
 > Every file that opens a door into a session declares where it leaves the caller, and a door whose
 > landing demands a return shape has it.
 
+<!-- begin generated rule header -->
+Runs under `@noctcore/harness`, not ESLint · Factory `createSessionLandingDeclaredRule` from `@noctcore/lint-meta-rules/session` · Category `source-text` · Fails CI by default: yes
+<!-- end generated rule header -->
+
 Import it from the `session` entry point:
 
 ```ts
@@ -15,8 +19,8 @@ With two shells behind one sign-in (staff and a customer portal, say), the clien
 account to the right one if the response that ends the sign-in says which kind it is. The first door
 (the password sign-in) usually does. A second door that finishes a sign-in from a different service (a
 second-factor challenge) can return the same union and still have its landing unwired, and nothing
-fails: the account signs in, lands in the wrong shell, and bounces off its guard. In the project this
-rule was extracted from, every portal account with 2FA enabled did exactly that.
+fails: the account signs in, lands in the wrong shell, and bounces off its guard. In one production
+codebase, every portal account with 2FA enabled did exactly that.
 
 Two sibling rules fence the same seam, [`session-mint-callers`](./session-mint-callers.md) (who may
 mint) and [`session-kind-stamped`](./session-kind-stamped.md) (the session carries the kind). Neither
@@ -34,7 +38,7 @@ can see this, because both are about the session and this is about the RESPONSE.
 3. **The declarations.** A door whose `landing` is not a key of `landings`, or whose `because` is empty.
 4. **Staleness.** A door whose file no longer exists, or that `sourceGlobs` do not reach.
 
-## What it leaves alone
+## What it does not flag
 
 - A file that only defines a door method (the leading dot is required).
 - A door whose landing maps to `null`: a re-issue that replaces the cookie of a caller already inside a
@@ -43,7 +47,7 @@ can see this, because both are about the session and this is about the RESPONSE.
 
 With no `doorCalls` the rule is inert.
 
-## Factory
+## Options
 
 ```ts
 createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMetaRule
@@ -61,7 +65,11 @@ createSessionLandingDeclaredRule(options?: SessionLandingDeclaredOptions): IMeta
 | `hint` | `string` | none | Appended to every message. |
 | `ciCritical` | `boolean` | `true` | Whether a violation fails CI. |
 
-## Worked example: Settly
+### Worked example: an app with two sign-in shells
+
+Staff and portal accounts share one sign-in and land in different shells. Sessions open through
+`establishSession` or the second-factor gate `beginOrEstablish`. The two doors either kind can reach
+must return `Promise<ILoginResult>`; the rest are staff-only or re-issues:
 
 ```ts
 const AUTH = 'apps/api/src/modules/auth';