laymos 0.0.8 → 0.0.10

package/dist/story/story.js

@@ -1,5 +1,6 @@
 import { Context, Effect } from 'effect';
 import { makeTraceRecorder } from '@pkishorez/effect-tracer/recorder';
+import { FlowTelemetry } from '@pkishorez/flow';
 export class StoryContext extends Context.Service()('StoryContext') {
 }
 export const Story = {
@@ -21,13 +22,11 @@ export const Story = {
                 .pipe(Effect.onExit(() => context.beginSection({ kind: 'trace', trace: recorder.snapshot() })));
         });
     },
-    flow(effect) {
+    flow(effect, _options) {
         return Effect.gen(function* () {
             const context = yield* StoryContext;
-            const recorder = makeTraceRecorder();
-            return yield* recorder
-                .instrument(effect)
-                .pipe(Effect.onExit(() => Effect.forEach(recorder.snapshotFlows(), (flow) => context.beginSection({ kind: 'flow', flow }))));
+            const sink = FlowTelemetry.makeMemory();
+            return yield* effect.pipe(Effect.provideService(FlowTelemetry, sink), Effect.onExit(() => Effect.forEach(sink.journals(), (journal) => context.beginSection({ kind: 'flow', journal }))));
         });
     },
     assert(description, passed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laymos",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "private": false,
   "description": "Enforces architectural dependency rules and explores source dependencies.",
   "repository": {
@@ -34,6 +34,11 @@
       "types": "./dist/story/schema/index.d.ts",
       "import": "./dist/story/schema/index.js",
       "default": "./dist/story/schema/index.js"
+    },
+    "./skills-command": {
+      "types": "./dist/skills-command/index.d.ts",
+      "import": "./dist/skills-command/index.js",
+      "default": "./dist/skills-command/index.js"
     }
   },
   "bin": {
@@ -42,29 +47,31 @@
   "files": [
     "bin",
     "dist",
+    "skills",
     "schema.json",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@effect/platform-node": "4.0.0-rc.110",
-    "@effect/platform-node-shared": "4.0.0-rc.110",
-    "oxc-parser": "0.144.0",
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/platform-node-shared": "4.0.0-rc.112",
+    "oxc-parser": "0.148.0",
     "oxc-resolver": "11.24.2",
-    "tsx": "4.23.12",
+    "tsx": "4.23.13",
     "yoctocolors": "2.2.0",
-    "@pkishorez/effect-tracer": "0.0.8"
+    "@pkishorez/flow": "0.0.10",
+    "@pkishorez/effect-tracer": "0.0.10"
   },
   "devDependencies": {
-    "@types/node": "26.2.0",
+    "@types/node": "26.4.1",
     "@typescript/native": "npm:typescript@7.0.2",
-    "effect": "4.0.0-rc.110",
-    "tsx": "4.23.12",
+    "effect": "4.0.0-rc.112",
+    "tsx": "4.23.13",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
-    "effect": "4.0.0-rc.110"
+    "effect": "4.0.0-rc.112"
   },
   "publishConfig": {
     "access": "public"

package/schema.json

@@ -16,11 +16,7 @@
     "sourceRoots": {
       "type": "array",
       "description": "Canonical project-relative files or folders that define the complete static analysis universe.",
-      "allOf": [
-        {
-          "minItems": 1
-        }
-      ],
+      "minItems": 1,
       "items": {
         "type": "string"
       }
@@ -62,11 +58,7 @@
           "paths": {
             "type": "array",
             "description": "Canonical project-relative paths belonging to this Layer. No declared Layer scopes may overlap, within one Layer or across Layers.",
-            "allOf": [
-              {
-                "minItems": 1
-              }
-            ],
+            "minItems": 1,
             "items": {
               "type": "string"
             }
@@ -83,12 +75,33 @@
             "description": "Human-readable summary of this Layer."
           },
           "docsPath": {
-            "$ref": "#/definitions/Union_"
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Canonical project-relative path to a markdown file documenting this entity. Read-only: Laymos never writes to it."
           },
           "modules": {
             "type": "object",
             "additionalProperties": {
-              "$ref": "#/definitions/Objects_"
+              "type": "object",
+              "properties": {
+                "shared": {
+                  "type": "boolean",
+                  "description": "Whether peers in the same Layer may import this Module. Illegal inside a Module Graph, where Rules govern peer access."
+                },
+                "exposed": {
+                  "type": "boolean",
+                  "description": "Whether other Layers may import this Module."
+                }
+              },
+              "additionalProperties": false,
+              "title": "Module",
+              "description": "A Configured Module keyed by its canonical source file or directory — project-relative when declared in a Layer, Module Graph-relative when declared in a Module Graph. Both flags default to false, so a Module is importable by nobody until it says otherwise."
             },
             "description": "Every free-form Configured Module in this Layer, keyed by canonical project-relative source file or directory."
           },
@@ -113,19 +126,36 @@
                   "description": "Canonical project-relative directory rooting this Module Graph. Every member lives below it and every file below it must belong to a member."
                 },
                 "docsPath": {
-                  "$ref": "#/definitions/Union_"
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ],
+                  "description": "Canonical project-relative path to a markdown file documenting this entity. Read-only: Laymos never writes to it."
                 },
                 "modules": {
                   "type": "object",
                   "additionalProperties": {
-                    "$ref": "#/definitions/Objects_"
+                    "type": "object",
+                    "properties": {
+                      "shared": {
+                        "type": "boolean",
+                        "description": "Whether peers in the same Layer may import this Module. Illegal inside a Module Graph, where Rules govern peer access."
+                      },
+                      "exposed": {
+                        "type": "boolean",
+                        "description": "Whether other Layers may import this Module."
+                      }
+                    },
+                    "additionalProperties": false,
+                    "title": "Module",
+                    "description": "A Configured Module keyed by its canonical source file or directory — project-relative when declared in a Layer, Module Graph-relative when declared in a Module Graph. Both flags default to false, so a Module is importable by nobody until it says otherwise."
                   },
                   "description": "Every member of this Module Graph, keyed relative to its path. At least two members, at least one exposed, and no member may be Shared.",
-                  "allOf": [
-                    {
-                      "minProperties": 2
-                    }
-                  ]
+                  "minProperties": 2
                 },
                 "rules": {
                   "type": "object",
@@ -157,11 +187,7 @@
         "description": "A named, configured group of project-relative paths, owning the Modules and Module Graphs declared within it."
       },
       "description": "Every Layer in the project, keyed by id, each owning its Modules and Module Graphs.",
-      "allOf": [
-        {
-          "minProperties": 1
-        }
-      ]
+      "minProperties": 1
     },
     "layerGraphs": {
       "type": "object",
@@ -180,7 +206,15 @@
             "description": "Human-readable summary of this LayerGraph."
           },
           "docsPath": {
-            "$ref": "#/definitions/Union_"
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Canonical project-relative path to a markdown file documenting this entity. Read-only: Laymos never writes to it."
           },
           "rules": {
             "type": "object",
@@ -210,34 +244,5 @@
   ],
   "additionalProperties": false,
   "title": "Laymos Config",
-  "description": "Declares a project's Layers, their Modules and Module Graphs, and its LayerGraphs.",
-  "definitions": {
-    "Union_": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "description": "Canonical project-relative path to a markdown file documenting this entity. Read-only: Laymos never writes to it."
-    },
-    "Objects_": {
-      "type": "object",
-      "properties": {
-        "shared": {
-          "type": "boolean",
-          "description": "Whether peers in the same Layer may import this Module. Illegal inside a Module Graph, where Rules govern peer access."
-        },
-        "exposed": {
-          "type": "boolean",
-          "description": "Whether other Layers may import this Module."
-        }
-      },
-      "additionalProperties": false,
-      "title": "Module",
-      "description": "A Configured Module keyed by its canonical source file or directory — project-relative when declared in a Layer, Module Graph-relative when declared in a Module Graph. Both flags default to false, so a Module is importable by nobody until it says otherwise."
-    }
-  }
+  "description": "Declares a project's Layers, their Modules and Module Graphs, and its LayerGraphs."
 }

package/skills/deep-module/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: deep-module
+description: Deep modules — folders with a narrow index.ts door over a wide interior orchestrated by a mandatory <name>.ts. Use when the user asks to deep-modularize, encapsulate, or tighten the public surface of a folder, runs /deep-module, or another skill needs the deep-module shape.
+---
+
+# deep-module
+
+A **deep module** is a folder with a narrow door and a wide interior: very little exported, lots of well-organised implementation inside. It has a name and a specific responsibility (or a few related ones) that read like a story, and everything it exposes is _deep_ — real capability, never a shallow pass-through.
+
+## The shape
+
+For a module named `hello`:
+
+```
+hello/
+├── index.ts      # the door: pure barrel, re-exports from hello.ts only
+├── hello.ts      # the orchestrator: everything public is implemented here
+├── <role>.ts     # helpers, one clear reason to exist each, named by role
+└── <child>/      # nested deep module, private to this module
+    ├── index.ts
+    └── child.ts
+```
+
+## Hard laws
+
+1. **`index.ts` is a pure barrel.** Re-exports only — it is the one file outsiders import from. Any logic it wants belongs in `hello.ts`.
+
+2. **`<name>.ts` is mandatory** in every deep module, nested ones included. It is the single implementation point for the public surface: every exposed function is implemented here; an exposed service (e.g. an Effect service and its layer) lives here. A deep function orchestrates the helper files to produce its result; the other files hold only helpers. `index.ts` re-exports exclusively from `<name>.ts`.
+
+3. **Export functionality, not types.** Default is zero exported types. A type earns export only when an external caller provably cannot be written without naming it (e.g. it annotates a value the caller constructs and hands back). A type that only appears as a parameter or inferred return stays inside. When unsure, leave it out and add it back when a real caller breaks.
+
+4. **Nested deep modules are private to their parent.** Their functionality is used only within the parent's limits. The test: if `<name>.ts` would re-export a child's function verbatim, with no orchestration on top, that module is not a child — **promote it to a sibling** deep module. A deep module is self-contained; children exist only to serve it.
+
+## Interior guidelines
+
+Heuristics in service of one goal — **human understandability**: a reader should juggle only two or three concepts at one level. When guidelines conflict, the version that is easier to hold in your head wins.
+
+- **`<name>.ts` reads like a story.** Top-to-bottom orchestration of named interior pieces; the heavy lifting is delegated. Reading it alone tells you what the module does.
+- **Each file has a specific reason to exist.** Name by role — `header.tsx`, `state.ts`, `parser.ts`. A junk-drawer name (`utils.ts`, `helpers.ts`) means a concern hasn't been identified yet; find the concern and name it.
+- **Group into nested modules.** When several files serve one distinct internal responsibility, move them into a nested deep module (same shape, recursively). Ideally one level of nesting is enough; the two-or-three focus budget applies to both breadth and depth — a wide god-module rebuilt as a deep tower just moves the violation.
+- **Generic-first composition.** Behind app-specific logic there is usually a generic capability hiding (a tree, a picker, a state machine). Extract the generic core with an app-agnostic interface, compose the specific on top. Understandability comes from "specialize a generic", not from splitting for its own sake.
+- **No hidden magic.** Behavior is fully predictable from the interface. Internal state, I/O, and effects are fine when passed in or localized in an obviously-named interior file. Significant state or config — anything a caller might need to read, control, or substitute — belongs at the door; trivial local detail stays inside.
+- **Errors and edge cases live in the type.** If a module can fail or return empty, the interface says so — a typed result, an explicit shape, a declared throw.
+- **Minimal ≠ trivial.** A single large export can be the entire surface; "minimal" counts doors, not capability. Size is fine — tangled responsibility is the enemy. One reason to change per unit.
+- **The barrel is the spec.** `index.ts` tells an outsider everything they can do with the module, in one glance.
+
+## Applying it to a folder
+
+The module tells its own story — its responsibility decides what it exposes, never its consumers. External callers are not this skill's concern.
+
+1. **Design** — draft the tree: `<name>.ts` orchestrator, role-named helpers, nested modules for grouped concerns, siblings for anything that must leave. Done when every export and every exported type has survived a why-challenge.
+2. **Summarize for the user** — present the proposed tree, the reason each file exists, and how the structure communicates the module's story. The user adds detail; rework the design until they say okay.
+3. **Implement** — only after the user's okay, reshape the files and write `index.ts`. Done when the folder matches the approved tree.
+
+Composes with other skills: e.g. `/grill-me` + `/deep-module` to interview the user about the design before reshaping.

package/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording _that_ a decision was made and _why_ — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,60 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: domain-modeling
+description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design. This is the _active_ discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely _reading_ `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
+
+## File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/skills/domain-modeling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: 'Domain Modeling'
+  short_description: 'Build and sharpen a domain model'

package/skills/laymos/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: laymos
+description: Laymos architecture rules — the layer stack, module visibility, module graphs, naming, config, and CLI. Use when planning or changing a project's architecture, when reading laymos.config.json or laymos output, or when another skill needs the Laymos model.
+---
+
+# Laymos
+
+Reference. Read it before planning or changing a project's architecture.
+It answers _what_, never _how to run a session_.
+
+## What is Laymos trying to achieve?
+
+Stable code at the bottom. Volatile code on top. Dependencies point down.
+
+The bottom knows nothing about the top. So the bottom stays small, testable,
+and reusable, and features churn in the top where churn is cheap.
+This is stratified design, from _Grokking Simplicity_ by Eric Normand.
+
+One common stack, bottom to top:
+
+- **domain** — the words of the problem. Types, schemas, pure functions. No I/O.
+- **clients** — the outside world, wrapped. Third-party APIs, the database, the filesystem.
+- **services** — one responsibility each, built on domain and clients.
+- **orchestrator** — puts services and clients together to get the real work done.
+- **entry** — where the host starts. A CLI, a route, a worker.
+
+That stack is a mental model, not a rule. Layers come from the application you
+are building, and you name them for the jobs your project actually has.
+The direction is the part that never changes.
+
+Read `references/design.md` before choosing module boundaries, splitting or
+combining modules, declaring a module graph, or designing orchestration.
+
+## What is Laymos?
+
+Laymos is a CLI tool. It reads `laymos.config.json`.
+
+It lints declared dependency rules, inspects layers and modules, and runs the
+project's executable Stories.
+
+The config is the source of architectural truth. Source code is evidence.
+When the two disagree, the config states the intent and the lint reports the gap.
+
+## What is a layer?
+
+A layer is a group of files with one architectural job.
+
+A layer owns dependency rights. `a -> b` reads "a may depend on b".
+Rights are transitive: if `a -> b` and `b -> c`, then `a` may depend on `c`.
+Anything not permitted is a violation. The rule graph must be acyclic.
+
+Every analyzed supported file belongs to exactly one layer. Layers may not overlap.
+A layer with no outgoing rule is a valid leaf.
+
+Create a layer when a job needs its own dependency direction.
+Folders, teams, and display groups are not layers.
+A one-module layer is fine when that module needs distinct rights.
+
+## What is a module?
+
+A module is a source boundary inside one layer. It owns one capability and the
+design decisions that capability hides behind a small, stable door.
+
+A module is a file or a directory. That is its _shape_.
+A module declares two booleans, `shared` and `exposed`, both defaulting to
+false. They control layer-wide and cross-layer access; module graph rules grant
+access between members separately. Read `references/visibility.md` when deciding.
+
+A directory module needs a root `index.ts` when it is shared, exposed, or a
+module graph member. That index is a thin door over a wide interior — read the
+`deep-module` skill for its shape. When a file module needs an entry point, its
+own file is that entry point.
+
+Two modules never overlap. Every analyzed file in a layer belongs to one module.
+
+## What is a module graph?
+
+A named, bounded set of modules inside one layer, rooted at a directory, whose
+connections are declared as rules. It describes one capability too large for a
+single module: normally one facade is exposed and the other members stay private.
+
+Unlike a layer graph it is a disjoint unit — its rules are never unioned with
+another graph's, are **not** transitive, and are checked for cycles on their own.
+Module graphs do not nest. Read `references/graphs.md` before declaring one.
+
+A layer holds free-form modules, module graphs, or both. A layer groups by
+architectural role; a graph describes how modules work together.
+
+## How do I name things?
+
+Use the project's own words. The `domain-modeling` skill owns those words;
+read it when a term is missing or contested.
+
+- Layer ids and folders are lowercase kebab-case.
+- Name a layer for its dependency job, not its folder.
+- Name a module with a concrete noun: `file-graph`, `project-config`.
+- Name work that runs with verb-noun: `load-project`.
+- `utils`, `helpers`, `common`, `misc`, `lib`, `impl` name nothing.
+  Use the capability they hide.
+- A module's identity is its full configured path. The short name is a label.
+
+Write a layer description as the job it owns. Write a module job as one sentence.
+
+## Which command answers which question?
+
+| Question                                                         | Command                                         |
+| ---------------------------------------------------------------- | ----------------------------------------------- |
+| Does the project obey its rules?                                 | `laymos lint`                                   |
+| Are layer coverage and links correct?                            | `laymos lint layers`                            |
+| Are module boundaries and entry points correct?                  | `laymos lint modules`                           |
+| What is the whole architecture?                                  | `laymos inspect project`                        |
+| What is in this layer, and what may it reach?                    | `laymos inspect layer <layer-name>`             |
+| What visibility, shape, surface, and deps does this module have? | `laymos inspect module <module-path>`           |
+| Which layer and module owns this file, and what does it import?  | `laymos inspect file <file-path> [--recursive]` |
+| Do the executable Stories pass?                                  | `laymos stories [--concurrency <n>]`            |
+
+Every command takes `--config <path>`. It defaults to `./laymos.config.json`.
+Add `--json` to any `inspect` command and parse the result. Without it, read the tree.
+Exit `0` is clean. Exit `1` means violations, an inspection cycle, or non-passing
+Stories. Exit `2` means a broken config or an operational failure.
+
+Use the project's package runner when `laymos` is not on `PATH`.
+
+## What do the inspect fields mean?
+
+- `shared` and `exposed` are the configured intent.
+- `graph` names the module graph a member belongs to.
+- `shape` is file or directory.
+- `observedKind` is the module's current position in the import graph.
+- Imports show current use. They do not decide the target design.