laymos 0.0.9 → 0.0.11

package/README.md

@@ -1,167 +1,284 @@
-# Laymos
-
-Laymos enforces architectural dependency rules. It also provides focused
-dependency queries for exploring and understanding a codebase.
-
-## Architecture
-
-Declare Layers, Modules, and LayerGraphs in a plain `laymos.config.json`.
-
-A **Layer** is a named group of literal project-relative files and folders.
-Layers partition the supported files beneath `sourceRoots`: every included
-file belongs to exactly one Layer, and no declared Layer scopes may overlap.
-Use `ignoredPaths` to remove files or folders from analysis explicitly.
-
-A **LayerGraph** is a named set of **rules** representing one responsibility
-(e.g. core architecture or test boundaries). It is an organizational grouping,
-not an enforcement boundary. A project may have no LayerGraphs when no
-cross-Layer imports are allowed.
-
-Each rule maps a layer id to the layer ids it may directly depend on. Rules
-are default-deny: any dependency between two layers with no declared path
-between them — direct or transitive, across every LayerGraph combined — is a
-violation. Permission is transitive, so only direct edges need declaring (if
-`app` may depend on `domain` and `domain` may depend on `infra`, `app` may
-depend on `infra` without declaring it explicitly). The combined graph must be
-acyclic. A layer with no outgoing rule is a valid, intentional leaf.
-
-A **Module** is a self-contained source boundary backed by a supported source
-file or directory. A **Configured Module** is an explicit, disjoint boundary
-within one Layer, and every included file belongs to one. Its `kind` is Normal
-by default. Marking it `shared` lets peers in the same Layer import it; Layer
-Rules still decide cross-Layer access. An Entry Module may depend on other
-Modules but cannot be imported by one.
-
-A Normal or Shared File Module is its own public entry point. A Normal or Shared
-Directory Module requires a root `index.ts`. List an exact directory path in
-`subpaths` to add another public `index.ts` for tree shaking. Entry Modules
-follow their host's file convention and cannot declare Subpaths.
-
-```json
-{
-  "$schema": "https://unpkg.com/laymos/schema.json",
-  "sourceRoots": ["src"],
-  "ignoredPaths": ["src/generated"],
-  "layers": {
-    "app": { "paths": ["src/app"], "description": "Application" },
-    "domain": { "paths": ["src/domain"], "description": "Domain" },
-    "infra": { "paths": ["src/infra"] }
-  },
-  "modules": {
-    "src/app": { "kind": "entry" },
-    "src/domain/orders": {},
-    "src/domain/catalog": { "kind": "shared", "subpaths": ["events"] },
-    "src/infra": {}
-  },
-  "layerGraphs": {
-    "architecture": {
-      "description": "Core layering",
-      "rules": {
-        "app": ["domain"],
-        "domain": ["infra"]
-      }
-    }
-  }
-}
-```
+# laymos
 
-No package dependency is required to author or consume this file — the
-`$schema` key gives editors autocomplete/validation directly, and any other
-tool (including a separate devtools server rendering the project's
-architecture) can read it as plain JSON. See
-[ADR-0003](docs/adr/0003-json-config-over-typescript.md) for why.
+Enforces architectural dependency rules and explores source dependencies.
 
-## Library API
+## Big picture
 
-```ts
-import { Effect } from 'effect';
-import { analyzeProject } from 'laymos';
+A project's architecture usually lives in people's heads. laymos moves it into
+a plain `laymos.config.json`: Layers group source paths, Modules draw disjoint
+boundaries inside a Layer, and LayerGraphs say which Layers may depend on
+which. `laymos lint` compares that intent with the real import graph and
+reports every gap. `laymos inspect` answers the reverse question: given a
+file or Module, what does it depend on and who is allowed to reach it.
 
-const analysis = await Effect.runPromise(
-  analyzeProject('/absolute/project/laymos.config.json'),
-);
-```
+The same config can point at a folder of Stories: small executable narratives
+that prove a behavior and keep their proof next to the prose. `laymos stories`
+runs them and reports a verdict per Story.
 
-`analyzeProject` returns `ArchitectureAnalysis`: the decoded Config plus Layer
-and Module analysis. `ArchitectureAnalysisSchema` is its runtime and transport
-contract; its Maps and Sets support Effect Schema's canonical JSON codec.
+The library entry does everything the CLI does, so other tools can host it.
+[@pkishorez/devtools](../devtools/README.md) serves Architecture Analyses, change sets, and
+Story reports over RPC to its browser UI using the browser-safe schema
+subpaths. Stories capture traces with
+[@pkishorez/effect-tracer](../effect-tracer/README.md) and Flows with
+[@pkishorez/flow](../flow/README.md).
 
-Browser and RPC code should import the contract-only entrypoint:
+Terms are defined in [CONTEXT.md](./CONTEXT.md). Decisions are in
+[docs/adr/](./docs/adr/). The config reference is in
+[docs/config.md](./docs/config.md) and the CLI reference in
+[docs/cli.md](./docs/cli.md).
 
-```ts
-import {
-  ArchitectureAnalysisSchema,
-  type ArchitectureAnalysis,
-} from 'laymos/architecture-analysis-schema';
+## Install
+
+```sh
+pnpm add -D laymos
 ```
 
-This entrypoint contains data schemas and types only. Project analysis remains
-available from the Node-oriented root entrypoint.
+Peer dependencies:
+
+- `effect` (`4.0.0-rc.112`): every library function returns an Effect, and
+  Stories are written as Effects.
+
+## Exports
+
+### `laymos`
+
+Node-only. Reads the config, walks the source tree, and runs git.
+
+| Export                                                                                                                             | What it does                                                                                       |
+| ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `analyzeProject`                                                                                                                   | Reads a config path and returns the full Architecture Analysis: config, Layer and Module analysis. |
+| `inspectProject`                                                                                                                   | Summarizes the whole Project for the `inspect project` view.                                       |
+| `inspectLayer`                                                                                                                     | Reports one Layer's paths, allowed links, Modules, and violations.                                 |
+| `inspectFile`                                                                                                                      | Reports one file's Layer, Module, boundary role, and dependencies, optionally recursive.           |
+| `inspectModule`                                                                                                                    | Reports one Configured Module's visibility, shape, entry points, and dependency tree.              |
+| `InspectionTargetNotFound`                                                                                                         | Error when the inspected file, Layer, or Module does not exist.                                    |
+| `ModuleInspectionCycle`                                                                                                            | Error when the inspected Module sits in a dependency cycle.                                        |
+| `loadModuleSource`                                                                                                                 | Returns the paths and contents of every source file assigned to one Configured Module.             |
+| `ModuleSourceNotFound`                                                                                                             | Error when the requested Module is not configured.                                                 |
+| `ModuleSourceReadError`                                                                                                            | Error when one of the Module's files could not be read.                                            |
+| `loadSourceFiles`                                                                                                                  | Returns the contents of included source files under the given path prefixes.                       |
+| `SourceFileReadError`                                                                                                              | Error when one of those files could not be read.                                                   |
+| `loadDocumentation`                                                                                                                | Reads the markdown declared by `docsPath` for a Layer, LayerGraph, Module, or Module Graph scope.  |
+| `DocumentationScopeNotFound`                                                                                                       | Error when the scope names something the config does not declare.                                  |
+| `DocumentationReadError`                                                                                                           | Error when the markdown file could not be read.                                                    |
+| `getStoryTree`                                                                                                                     | Loads the Story tree from `storiesPath` without running anything.                                  |
+| `planStories`                                                                                                                      | Loads and scopes Stories, then returns the total and a Stream of reports as they finish.           |
+| `runStories`                                                                                                                       | Same as `planStories` but returns only the report Stream.                                          |
+| `StoriesError`                                                                                                                     | Error for a missing `storiesPath`, a bad root, duplicate titles, or an invalid timeout.            |
+| `loadBranches`                                                                                                                     | Lists the git branches of the project's repository.                                                |
+| `loadChangeSet`                                                                                                                    | Lists paths added or modified against a base ref, default `HEAD`.                                  |
+| `loadFileDiff`                                                                                                                     | Returns the hunks of one file against a base ref.                                                  |
+| `GitError`                                                                                                                         | Error when the folder is not a repository, the ref is unknown, or git failed.                      |
+| `ConfigError`                                                                                                                      | Error when the config could not be read, parsed, decoded, or validated.                            |
+| `CruiseError`                                                                                                                      | Error when the source tree could not be walked or parsed.                                          |
+| `ArchitectureAnalysisSchema`                                                                                                       | Re-export from `laymos/architecture-analysis-schema`.                                              |
+| `ModuleSourceSnapshotSchema`                                                                                                       | Re-export from `laymos/architecture-analysis-schema`.                                              |
+| `DocumentationScopeSchema`                                                                                                         | Re-export from `laymos/architecture-analysis-schema`.                                              |
+| `DocumentationSchema`                                                                                                              | Re-export from `laymos/architecture-analysis-schema`.                                              |
+| `StoryReportSchema`                                                                                                                | Re-export from `laymos/story/schema`.                                                              |
+| `StoryTreeSchema`                                                                                                                  | Re-export from `laymos/story/schema`.                                                              |
+| `BranchSchema`, `ChangedPathSchema`, `ChangeSetSchema`, `ChangeStatusSchema`, `DiffHunkSchema`, `DiffLineSchema`, `FileDiffSchema` | Re-exports from `laymos/change-set-schema`.                                                        |
+
+### `laymos/architecture-analysis-schema`
+
+Browser-safe. Schemas only; no file system access.
+
+| Export                        | What it does                                                                                       |
+| ----------------------------- | -------------------------------------------------------------------------------------------------- |
+| `ArchitectureAnalysisSchema`  | The wire contract for an Architecture Analysis; its Maps and Sets encode to JSON.                  |
+| `LayerAnalysisSchema`         | Layer membership, unassigned files, forbidden imports, and Layers without Modules.                 |
+| `ModuleAnalysisSchema`        | Analyzed Modules, Module Graphs, dependencies, and Module violations.                              |
+| `ProjectConfigSchema`         | The decoded config with every key present.                                                         |
+| `ProjectConfigInputSchema`    | The authoring config, where optional keys fall back to defaults.                                   |
+| `ConfigValidationIssueSchema` | One validation problem with its kind and message.                                                  |
+| `ModuleSourceFileSchema`      | One source file path with its contents.                                                            |
+| `ModuleSourceSnapshotSchema`  | The files of one Configured Module.                                                                |
+| `DocumentationScopeSchema`    | Which entity a documentation request targets: `module`, `module-graph`, `layer`, or `layer-graph`. |
+| `DocumentationSchema`         | The resolved markdown for one scope, or its absence.                                               |
+
+### `laymos/change-set-schema`
+
+Browser-safe.
+
+| Export               | What it does                                                            |
+| -------------------- | ----------------------------------------------------------------------- |
+| `ChangeStatusSchema` | `added` or `modified`.                                                  |
+| `ChangedPathSchema`  | One changed path with its status.                                       |
+| `ChangeSetSchema`    | Every changed path against a base ref.                                  |
+| `DiffLineSchema`     | One line of a diff hunk.                                                |
+| `DiffHunkSchema`     | One hunk of a file diff.                                                |
+| `FileDiffSchema`     | The hunks of one file.                                                  |
+| `BranchSchema`       | One local or remote-tracking branch, with `remote` and `current` flags. |
+
+### `laymos/story`
+
+For Story files. Runs in Node under the Story runner.
+
+| Export           | What it does                                                                                    |
+| ---------------- | ----------------------------------------------------------------------------------------------- |
+| `Story.make`     | Builds a Story from a title, description, source URL, and questions; `spine` defaults to false. |
+| `Story.question` | Builds one question with its prose answer and its proof Effect.                                 |
+| `Story.group`    | Builds a Story Group from a title, description, and children.                                   |
+| `Story.trace`    | Runs an Effect under a trace recorder and attaches the captured trace to the report.            |
+| `Story.flow`     | Runs an Effect with a memory Flow sink and attaches every Journal to the report.                |
+| `Story.assert`   | Records a named pass or fail that decides the question's verdict.                               |
+| `StoryContext`   | The service the runner injects; `Story.trace`, `Story.flow`, and `Story.assert` use it.         |
+| `isStory`        | Type guard for a Story value.                                                                   |
+| `isStoryGroup`   | Type guard for a Story Group value.                                                             |
+
+### `laymos/story/schema`
+
+Browser-safe.
+
+| Export                  | What it does                                                  |
+| ----------------------- | ------------------------------------------------------------- |
+| `StoryTreeSchema`       | The root Story Group with its nested groups and Story leaves. |
+| `StoryTreeGroupSchema`  | One group node of the tree.                                   |
+| `StoryLeafSchema`       | One Story with its id, page, source, setup, and questions.    |
+| `QuestionLeafSchema`    | One question with its slug, answer, and proof snippet.        |
+| `StoryPageSchema`       | The markdown page attached to a Story or group.               |
+| `StorySourceSchema`     | The path and contents of a Story file.                        |
+| `StoryReportSchema`     | The verdict and per-question reports of one Story run.        |
+| `QuestionReportSchema`  | One question's sections, assertions, and verdict.             |
+| `QuestionSectionSchema` | A captured trace or Flow Journal section.                     |
+| `CapturedTraceSchema`   | The spans and logs captured by `Story.trace`.                 |
+| `JournalSchema`         | The Flow Journal captured by `Story.flow`.                    |
+| `StoryAssertionSchema`  | One assertion with its description and result.                |
+| `StoryVerdictSchema`    | `passed`, `failed`, or `errored`.                             |
+| `slugifyQuestion`       | Turns a question string into its URL slug.                    |
 
-Load the current source snapshot for one Configured Module on demand:
+### `laymos/skills-command`
+
+| Export              | What it does                                                                    |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `makeSkillsCommand` | Builds a `skills` CLI subcommand that lists, prints, or installs skill folders. |
+
+### CLI
+
+| Command                                             | What it does                                                  |
+| --------------------------------------------------- | ------------------------------------------------------------- |
+| `laymos lint`                                       | Checks every rule and Story page; exits 1 on violations.      |
+| `laymos lint layers`                                | Checks Layer coverage and cross-Layer rules.                  |
+| `laymos lint modules`                               | Checks Module coverage, boundaries, dependencies, and cycles. |
+| `laymos inspect project [--json]`                   | Summarizes the whole architecture.                            |
+| `laymos inspect layer <name> [--json]`              | Shows one Layer and its Modules.                              |
+| `laymos inspect file <path> [--recursive] [--json]` | Shows a file's Layer, Module, and dependency tree.            |
+| `laymos inspect module <path> [--json]`             | Shows a Configured Module's identity and dependencies.        |
+| `laymos stories [--concurrency <n>]`                | Runs every Story and prints each verdict.                     |
+| `laymos skills [<name>] [--install <dir>]`          | Lists, prints, or installs the shipped agent skills.          |
+
+Details and exit codes are in [docs/cli.md](./docs/cli.md).
+
+## Usage
+
+### Analyze a project from Node
+
+Read a config and get the full Architecture Analysis as one value. This is
+what the CLI and the DevTools server both do first.
 
 ```ts
-import { Effect } from 'effect';
-import { loadModuleSource } from 'laymos';
+import { Effect, Schema } from 'effect';
+import { analyzeProject, ArchitectureAnalysisSchema } from 'laymos';
 
-const snapshot = await Effect.runPromise(
-  loadModuleSource('/absolute/project/laymos.config.json', 'src/domain/orders'),
+const analysis = await analyzeProject('./laymos.config.json').pipe(
+  Effect.runPromise,
 );
+
+analysis.config.sourceRoots; // ['src']
+analysis.layerAnalysis.unassignedFiles; // files with no Layer
+analysis.moduleAnalysis.violations; // e.g. { kind: 'boundary', fromFile, toFile, ... }
+
+// Send it over the wire: Maps and Sets encode to plain JSON.
+const codec = Schema.toCodecJson(ArchitectureAnalysisSchema);
+const json = Schema.encodeSync(codec)(analysis);
 ```
 
-The snapshot contains only included supported source files assigned to that
-Module by a fresh Architecture Analysis.
+How it works:
 
-Inspect an exact included source file or Configured Module without consuming
-the complete Architecture Analysis:
+- `analyzeProject` loads and validates the config, walks `sourceRoots` with
+  oxc, and runs Layer and Module analysis.
+- Failures are typed: `ConfigError` for the config, `CruiseError` for the
+  source walk.
+- `ArchitectureAnalysisSchema` is the same contract the browser decodes.
+
+### Write a Story
+
+A Story file exports Stories built with `Story.make`. Each question holds a
+prose answer and a proof Effect. `Story.assert` decides the verdict.
 
 ```ts
-import { Effect } from 'effect';
-import { inspectFile, inspectModule } from 'laymos';
+import { Effect, Schema } from 'effect';
+import { Story } from 'laymos/story';
+import { EntityESchema } from 'std-toolkit/eschema';
 
-const file = await Effect.runPromise(
-  inspectFile('/absolute/project/laymos.config.json', 'src/domain/order.ts', {
-    recursive: true,
-  }),
-);
-const module = await Effect.runPromise(
-  inspectModule('/absolute/project/laymos.config.json', 'src/domain/orders'),
-);
+const Task = EntityESchema.make('Task', 'taskId', {
+  boardId: Schema.String,
+  title: Schema.String,
+})
+  .evolve('v2', { assignee: Schema.NullOr(Schema.String) }, (previous) => ({
+    ...previous,
+    assignee: null,
+  }))
+  .build();
+
+export const appendAVersion = Story.make({
+  title: 'Append a version, never edit one',
+  description: 'Old rows still read after a new version is added.',
+  sourceUrl: import.meta.url,
+  questions: [
+    Story.question('Do rows written before v2 still read?', {
+      answer: 'Yes. The v1 shape is untouched, so a v1 row walks to v2.',
+      proof: Effect.gen(function* () {
+        const oldest = yield* Task.decode({
+          _v: 'v1',
+          taskId: 't1',
+          boardId: 'work',
+          title: 'Write the plan',
+        });
+        yield* Story.assert('a v1 row arrives at v2', oldest.assignee === null);
+        return { oldest };
+      }),
+    }),
+  ],
+});
 ```
 
-## CLI
+How it works:
 
-```sh
-laymos [--config <path>] lint
-laymos [--config <path>] lint layers
-laymos [--config <path>] lint modules
-laymos [--config <path>] inspect project [--json]
-laymos [--config <path>] inspect layer <layer-name> [--json]
-laymos [--config <path>] inspect file <file-path> [--recursive] [--json]
-laymos [--config <path>] inspect module <module-path> [--json]
+- `storiesPath/index.ts` default-exports a `Story.group` that lists every
+  Story; `laymos stories` imports it with tsx and runs each proof.
+- The runner provides `StoryContext`; `Story.assert` writes into it.
+- Wrap a proof in `Story.trace` or `Story.flow` to attach a trace or a Flow
+  Journal to the report.
+
+### Run Stories and stream reports
+
+Host the Story runner in your own process and consume reports as they finish.
+
+```ts
+import { Effect, Stream } from 'effect';
+import { getStoryTree, planStories } from 'laymos';
+
+const tree = await getStoryTree('./laymos.config.json').pipe(Effect.runPromise);
+tree.groups.map((group) => group.title);
+
+const program = Effect.gen(function* () {
+  const { total, reports } = yield* planStories('./laymos.config.json', {
+    concurrency: 4,
+  });
+  const collected = yield* Stream.runCollect(reports);
+  const failed = [...collected].filter((r) => r.verdict !== 'passed');
+  return { total, failed: failed.length };
+});
+
+await Effect.runPromise(program);
 ```
 
-`lint` checks every architectural rule; `lint layers` checks Layer coverage,
-configured Module presence, and dependencies, while `lint modules` checks
-Module coverage, expected entry points, dependencies, public boundaries, and
-cycles. Violations exit with status `1`, while invalid configuration or an
-analysis failure exits with status `2`.
-
-`inspect file` prints the file's Layer, Configured Module, public-boundary role,
-and dependencies as a colored path tree. Direct dependencies are yellow; with
-`--recursive`, transitive dependencies are gray. Only exact included supported
-source files can be inspected. Included files with missing Layer or Module
-membership remain inspectable and show a coverage warning.
-
-`inspect project` summarizes the whole architecture. `inspect layer` accepts an
-exact Layer name and reports its paths, allowed Layer links, Modules, Shared
-count, and violations. `inspect module` accepts an exact configured Module path
-and prints its configured kind, source shape, observed kind, public entry
-points, and dependency tree. Add `--json` to any inspect command for stable tool
-output. If the selected Module participates in a dependency cycle, inspection
-stops and directs the user to `lint modules`.
-
-The active inspection target is green in both trees. All commands use
-`sourceRoots` and `ignoredPaths` from the config. Config paths default to
-`./laymos.config.json`, and project-relative paths are resolved from the config
-file's directory.
+How it works:
+
+- `getStoryTree` loads the tree without running proofs; the DevTools UI uses it
+  to render the outline.
+- `planStories` returns the count up front and a `Stream` of `StoryReport`
+  so a UI can show progress.
+- Pass `scope` to run one group or Story by id; a `StoriesError` with reason
+  `unknown-scope` is returned when it does not match.

package/dist/architecture-analysis-schema/module-source-schema.d.ts

@@ -2,6 +2,8 @@ import { Schema } from 'effect';
 export declare const ModuleSourceFileSchema: Schema.Struct<{
     readonly path: Schema.String;
     readonly content: Schema.String;
+    readonly binary: Schema.optional<Schema.Boolean>;
+    readonly unanalyzed: Schema.optional<Schema.Boolean>;
 }>;
 export type ModuleSourceFile = typeof ModuleSourceFileSchema.Type;
 export declare const ModuleSourceSnapshotSchema: Schema.Struct<{
@@ -10,6 +12,8 @@ export declare const ModuleSourceSnapshotSchema: Schema.Struct<{
     readonly files: Schema.$Array<Schema.Struct<{
         readonly path: Schema.String;
         readonly content: Schema.String;
+        readonly binary: Schema.optional<Schema.Boolean>;
+        readonly unanalyzed: Schema.optional<Schema.Boolean>;
     }>>;
 }>;
 export type ModuleSourceSnapshot = typeof ModuleSourceSnapshotSchema.Type;

package/dist/architecture-analysis-schema/module-source-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-source-schema.d.ts","sourceRoot":"","sources":["../../src/architecture-analysis-schema/module-source-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,sBAAsB;;;EAGjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAC;AAElE,eAAO,MAAM,0BAA0B;;;;;;;EAIrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,OAAO,0BAA0B,CAAC,IAAI,CAAC"}
+{"version":3,"file":"module-source-schema.d.ts","sourceRoot":"","sources":["../../src/architecture-analysis-schema/module-source-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,sBAAsB;;;;;EAOjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAC;AAElE,eAAO,MAAM,0BAA0B;;;;;;;;;EAIrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,OAAO,0BAA0B,CAAC,IAAI,CAAC"}

package/dist/architecture-analysis-schema/module-source-schema.js

@@ -1,7 +1,11 @@
 import { Schema } from 'effect';
 export const ModuleSourceFileSchema = Schema.Struct({
     path: Schema.String,
+    // Empty for a binary file, whose bytes are never sent.
     content: Schema.String,
+    binary: Schema.optional(Schema.Boolean),
+    // An Unanalyzed file: known to git but outside the analysis universe.
+    unanalyzed: Schema.optional(Schema.Boolean),
 });
 export const ModuleSourceSnapshotSchema = Schema.Struct({
     modulePath: Schema.String,

package/dist/change-set-schema/change-set-schema.js

@@ -7,14 +7,14 @@ export const ChangedPathSchema = Schema.Struct({
     uncommitted: Schema.Boolean,
 }).annotate({
     title: 'Changed Path',
-    description: "One path a Base ref changed, relative to the Config's folder, and how it changed. A path may carry both committed work since the Base ref and uncommitted work in the working tree.",
+    description: 'One path a Base ref changed, relative to the folder it was measured in, and how it changed. A path may carry both committed work since the Base ref and uncommitted work in the working tree.',
 });
 export const ChangeSetSchema = Schema.Struct({
     baseRef: Schema.String,
     files: Schema.Array(ChangedPathSchema),
 }).annotate({
     title: 'Change Set',
-    description: "The added and modified paths between a Base ref and the working tree, relative to the Config's folder. It decorates an Architecture Analysis and never alters the analysis universe.",
+    description: "The added and modified paths between a Base ref and the working tree, relative to the folder it was measured in: a Laymos Project's Config folder or a Monorepo root. It decorates an analysis and never alters what that analysis covers.",
 });
 export const DiffLineSchema = Schema.Struct({
     kind: Schema.Literals(['context', 'added', 'removed']),

package/dist/cli/run.d.ts

@@ -1,4 +1,4 @@
 import { Effect } from 'effect';
 import { Command } from 'effect/unstable/cli';
-export declare const cli: Effect.Effect<void, import("../index.js").ConfigError | import("../index.js").CruiseError | import("../index.js").InspectionTargetNotFound | import("../index.js").ModuleInspectionCycle | import("../index.js").StoriesError | import("effect/unstable/cli/CliError").CliError, Command.Environment>;
+export declare const cli: Effect.Effect<void, import("../index.js").ConfigError | import("../index.js").CruiseError | import("../index.js").InspectionTargetNotFound | import("../index.js").ModuleInspectionCycle | import("effect/PlatformError").PlatformError | import("../index.js").StoriesError | import("effect/unstable/cli/CliError").CliError, Command.Environment>;
 //# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAQ,MAAM,qBAAqB,CAAC;AAmBpD,eAAO,MAAM,GAAG,uSAOf,CAAC"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,OAAO,EAAQ,MAAM,qBAAqB,CAAC;AAoBpD,eAAO,MAAM,GAAG,sVAQf,CAAC"}

package/dist/cli/run.js

@@ -3,6 +3,7 @@ import { Command, Flag } from 'effect/unstable/cli';
 import { makeInspectCommand } from './inspect/index.js';
 import { makeLintCommand } from './lint/index.js';
 import { makeStoriesCommand } from './stories/index.js';
+import { skillsCommand } from './skills.js';
 const rootCommand = Command.make('laymos', {}, () => Effect.void).pipe(Command.withSharedFlags({
     config: Flag.string('config').pipe(Flag.withDefault('laymos.config.json'), Flag.withDescription('Config file path. Project paths are relative to its directory.')),
 }));
@@ -11,4 +12,5 @@ export const cli = rootCommand.pipe(Command.withSubcommands([
     makeInspectCommand(configPath),
     makeLintCommand(configPath),
     makeStoriesCommand(configPath),
+    skillsCommand,
 ]), Command.run({ version: '0.0.1' }));

package/dist/cli/skills.d.ts

@@ -0,0 +1,6 @@
+export declare const skillsCommand: import("effect/unstable/cli/Command").Command<"skills", {
+    readonly name: import("effect/Option").Option<string>;
+    readonly install: import("effect/Option").Option<string>;
+    readonly format: "json" | "text";
+}, {}, import("effect/PlatformError").PlatformError, import("effect/FileSystem").FileSystem>;
+//# sourceMappingURL=skills.d.ts.map

package/dist/cli/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,aAAa;;;;4FAIxB,CAAC"}

package/dist/cli/skills.js

@@ -0,0 +1,9 @@
+import { fileURLToPath } from 'node:url';
+import { makeSkillsCommand } from '../skills-command/index.js';
+// Two levels below the package root from both `src/cli/` and `dist/cli/`.
+const SKILLS_ROOT = fileURLToPath(new URL('../../skills/', import.meta.url));
+export const skillsCommand = makeSkillsCommand({
+    skillsRoot: SKILLS_ROOT,
+    names: ['laymos', 'to-laymos', 'domain-modeling', 'deep-module'],
+    cliName: 'laymos',
+});

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { analyzeProject } from './orchestrator/analyze-project/index.js';
 export { loadModuleSource, ModuleSourceNotFound, ModuleSourceReadError, } from './orchestrator/load-module-source/index.js';
 export { loadDocumentation, DocumentationReadError, DocumentationScopeNotFound, } from './orchestrator/load-documentation/index.js';
-export { loadSourceFiles, SourceFileReadError, } from './orchestrator/load-source-files/index.js';
+export { loadFolderFiles, loadSourceFiles, SourceFileReadError, } from './orchestrator/load-source-files/index.js';
 export { ArchitectureAnalysisSchema } from './architecture-analysis-schema/index.js';
 export type { ArchitectureAnalysis } from './architecture-analysis-schema/index.js';
 export { ModuleSourceSnapshotSchema } from './architecture-analysis-schema/index.js';
@@ -15,7 +15,7 @@ export { CruiseError } from './services/file-cruiser/index.js';
 export { getStoryTree, planStories, runStories, StoriesError, } from './orchestrator/run-stories/index.js';
 export { StoryReportSchema, StoryTreeSchema } from './story/schema/index.js';
 export type { StoryReport, StoryTree } from './story/schema/index.js';
-export { loadBranches, loadChangeSet, loadFileDiff, } from './orchestrator/load-changes/index.js';
+export { loadBranches, loadChangeSet, loadFileDiff, loadKnownFiles, } from './orchestrator/load-changes/index.js';
 export { GitError } from './services/git/index.js';
 export { BranchSchema, ChangedPathSchema, ChangeSetSchema, ChangeStatusSchema, DiffHunkSchema, DiffLineSchema, FileDiffSchema, } from './change-set-schema/index.js';
 export type { Branch, ChangedPath, ChangeSet, ChangeStatus, DiffHunk, DiffLine, FileDiff, } from './change-set-schema/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,mBAAmB,GACpB,MAAM,2CAA2C,CAAC;AAEnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAErF,YAAY,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AACpF,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,YAAY,EACV,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,aAAa,EACb,kBAAkB,GACnB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE/D,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,GACf,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EACV,MAAM,EACN,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,QAAQ,GACT,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EACL,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,2CAA2C,CAAC;AAEnD,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAErF,YAAY,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AACpF,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,YAAY,EACV,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,yCAAyC,CAAC;AACjD,YAAY,EACV,aAAa,EACb,kBAAkB,GACnB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,iCAAiC,CAAC;AACzC,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAE/D,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEtE,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,cAAc,GACf,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EACV,MAAM,EACN,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,QAAQ,GACT,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -5,7 +5,7 @@ export { loadModuleSource, ModuleSourceNotFound, ModuleSourceReadError, } from '
 // Node consumers use this high-level capability to read documentation at any scope.
 export { loadDocumentation, DocumentationReadError, DocumentationScopeNotFound, } from './orchestrator/load-documentation/index.js';
 // Node consumers use this high-level capability to read arbitrary source files by path.
-export { loadSourceFiles, SourceFileReadError, } from './orchestrator/load-source-files/index.js';
+export { loadFolderFiles, loadSourceFiles, SourceFileReadError, } from './orchestrator/load-source-files/index.js';
 // RPC transports use this browser-safe runtime contract for Architecture Analysis.
 export { ArchitectureAnalysisSchema } from './architecture-analysis-schema/index.js';
 export { ModuleSourceSnapshotSchema } from './architecture-analysis-schema/index.js';
@@ -20,7 +20,7 @@ export { getStoryTree, planStories, runStories, StoriesError, } from './orchestr
 // RPC transports use this browser-safe runtime contract for Story reports.
 export { StoryReportSchema, StoryTreeSchema } from './story/schema/index.js';
 // Node consumers use this high-level capability to report what a Base ref changed.
-export { loadBranches, loadChangeSet, loadFileDiff, } from './orchestrator/load-changes/index.js';
+export { loadBranches, loadChangeSet, loadFileDiff, loadKnownFiles, } from './orchestrator/load-changes/index.js';
 // Change set callers distinguish a missing repository from a failed git command.
 export { GitError } from './services/git/index.js';
 // RPC transports use this browser-safe runtime contract for Change sets.

package/dist/orchestrator/load-changes/index.d.ts

@@ -1,2 +1,2 @@
-export { loadBranches, loadChangeSet, loadFileDiff } from './load-changes.js';
+export { loadBranches, loadChangeSet, loadFileDiff, loadKnownFiles, } from './load-changes.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/orchestrator/load-changes/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/load-changes/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/load-changes/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC"}

package/dist/orchestrator/load-changes/index.js

@@ -1,2 +1,2 @@
 // Node consumers use this high-level capability to report what a Base ref changed.
-export { loadBranches, loadChangeSet, loadFileDiff } from './load-changes.js';
+export { loadBranches, loadChangeSet, loadFileDiff, loadKnownFiles, } from './load-changes.js';

package/dist/orchestrator/load-changes/load-changes.d.ts

@@ -1,7 +1,8 @@
 import { Effect } from 'effect';
 import type { Branch, ChangeSet, FileDiff } from '../../change-set-schema/index.js';
 import { type GitError } from '../../services/git/index.js';
-export declare function loadChangeSet(configPath: string, baseRef?: string): Effect.Effect<ChangeSet, GitError>;
-export declare function loadFileDiff(configPath: string, path: string, baseRef?: string): Effect.Effect<FileDiff, GitError>;
-export declare function loadBranches(configPath: string): Effect.Effect<readonly Branch[], GitError>;
+export declare function loadChangeSet(folder: string, baseRef?: string): Effect.Effect<ChangeSet, GitError>;
+export declare function loadFileDiff(folder: string, path: string, baseRef?: string): Effect.Effect<FileDiff, GitError>;
+export declare function loadBranches(folder: string): Effect.Effect<readonly Branch[], GitError>;
+export declare function loadKnownFiles(folder: string): Effect.Effect<readonly string[], GitError>;
 //# sourceMappingURL=load-changes.d.ts.map