arkgate 4.8.6 → 4.8.7

package/dist/{types-BuM8WNqe.d.ts → types-BK47clMl.d.ts}

@@ -1,4 +1,4 @@
-import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-dy5PfTqS.js';
+import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-0eHpocR3.js';
 
 /**
  * Policy types for the Ark kernel.

package/dist/{types-DrqsOiTY.d.ts → types-CwZ_oz1N.d.ts}

@@ -1,4 +1,4 @@
-import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-BuM8WNqe.js';
+import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-BK47clMl.js';
 
 /**
  * PolicyEngine

package/docs/README.md

@@ -58,14 +58,14 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · npm [CHANGELOG.md](../CHANGELOG.md) (Unreleased + 4.6.x) · [pre-4.6 archive](archive/CHANGELOG-pre-4.6.md) |
-| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). [arkorder-arkrun](plans/arkorder-arkrun/README.md) (Phase XP; `XP01`–`XP08` done; shipped **4.8.5**; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). [arkorder-valve-loop](plans/arkorder-valve-loop/README.md) (Phase LV; `LV01`–`LV09` done on tree; **4.8.6** prepared; [ADR 0034](adr/0034-arkorder-valved-loop.md); does not close K01). |
+| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). [arkorder-arkrun](plans/arkorder-arkrun/README.md) (Phase XP; `XP01`–`XP08` done; shipped **4.8.5**; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). [arkorder-valve-loop](plans/arkorder-valve-loop/README.md) (Phase LV; `LV01`–`LV09` done; shipped **4.8.6**; [ADR 0034](adr/0034-arkorder-valved-loop.md); does not close K01). [layer-description-projection](plans/layer-description-projection/README.md) (Phase LD; `LD01`–`LD06` done on tree; **4.8.7** prepared; [ADR 0035](adr/0035-layer-description-projection.md); project `layers[].description`; no schema bump). |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current published: [releases/4.8.5.md](releases/4.8.5.md) (`arkgate@4.8.5` on npm `latest`; does not close `K01`).
-Tree: [releases/4.8.6.md](releases/4.8.6.md) (`arkgate@4.8.6` prepared).
-Prior: [releases/4.8.4.md](releases/4.8.4.md) · [releases/4.8.3.md](releases/4.8.3.md) · [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
+Current published: [releases/4.8.6.md](releases/4.8.6.md) (`arkgate@4.8.6` on npm `latest`; does not close `K01`).
+Tree: [releases/4.8.7.md](releases/4.8.7.md) (`arkgate@4.8.7` prepared).
+Prior: [releases/4.8.5.md](releases/4.8.5.md) · [releases/4.8.4.md](releases/4.8.4.md) · [releases/4.8.3.md](releases/4.8.3.md) · [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
 Older notes: [releases/](releases/). Config: [configuration.md](configuration.md).
 
 ---

package/docs/configuration.md

@@ -144,7 +144,28 @@ name different factories: `arkRun.kernelRoots` (`compositionRoots` alias) vs
 
 Layer fields:
 
-- `name`, `patterns`, `exclude`, `description`
+- `name`, `patterns`, `exclude`
+- **`layers[].description`** (optional) — **app-context caption**: one product sentence for what
+  this folder is *in the app*, not architecture jargon. `/ark-place` prints it next to
+  the layer name and globs; doctor, coverage, and the HTML report show the same text.
+  Changing the sentence does **not** change `policyHash` (same strip as `stewards`) and
+  does **not** need a weakening ack. Absence is silent: never fails `--strict-config`,
+  never invents a doctor residual, never flips `valid`. Empty string is invalid JSON for
+  the field (`minLength: 1`). Compact starters may omit it. `/ark-adopt` writes it when
+  the product map or glossary names the house; it does not invent captions. No
+  `/ark-describe`.
+
+```json
+"layers": [
+  {
+    "name": "Application",
+    "patterns": ["src/application/**"],
+    "description": "Purchase requests — from asked to received."
+  }
+]
+```
+
+That sentence is product copy. Not “Rich domain model, business rules, and domain events.”
 - `intentPrefixes`, `forbiddenGlobals`, `mayImportInfrastructure`, `optional`
 - `reserved` / `allowEmpty` — future houses whose globs match nothing yet. `--strict-config` does not fail; `CONFIG_LAYER_PATTERN_NO_MATCHES` (typo warning) is skipped. A typo warning fires only when the glob is not reserved.
 - `capabilities: { deny: [...] }` — opt-in effect walls over the seven capability ids
@@ -353,7 +374,7 @@ changing either contract changes its hash and invalidates the acknowledgement.
 
 Optional `stewards` lists **GitHub handles or emails** who may **loosen** the contract or
 **grow** the baseline (`pedroknigge` or `pedroknigge@users.noreply.github.com` — not
-`Pedro Knigge`). The field is metadata — it does not change the policy hash. The lock
+`Pedro Knigge`). The field is metadata — it does not change the policy hash. `layers[].description` is stripped the same way (caption-only edits do not change `policyHash` and do not need a weakening ack; `contractHash` still fingerprints the raw config). The lock
 matches `--author`, then `GITHUB_ACTOR` / `ARK_STEWARD`, then `GIT_AUTHOR_EMAIL`. A
 noreply GitHub mail and the handle are the same person. Git `user.name` is not identity.
 

package/docs/package-surface.md

@@ -51,14 +51,15 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth\|arkRun"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. Thin `arkRun` on `latest.json` is `notAScore` residual honesty for `ark status`. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
 | **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **`ark.config.json`** | Layer globs, optional `layers[].description`, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **Layer caption (`layers[].description`, 4.8.7)** | Optional string on each layer. Projected onto `ark_place` / prepare-write / MCP place JSON, doctor JSON + human, coverage JSON, and the HTML Purpose column when present. `/ark-adopt` writes it from the product map or glossary; `/ark-place` prints it next to layer name + globs. | Existing optional field — **no `schemaVersion` bump**, no new key, no 14th skill. Copy is **app context** (a product sentence such as `Purchase requests — from asked to received.`), not architecture jargon. Stripped from `policyHash` like `stewards`; caption-only edits are neutral. Absence is silent: never a residual, never a score, never `--strict-config` fail, never flips `valid`. Compact starters may omit. |
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
 | **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
-| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources. `stewards` is excluded from policy hash. Identity is handle or email, not git `user.name`. No org plane. |
+| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources. `stewards` and `layers[].description` are excluded from policy hash. Identity is handle or email, not git `user.name`. No org plane. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
 | **Structural convergence (3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
@@ -252,7 +253,9 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);
+(current tree prepared: [4.8.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.7.md);
+current published: [4.8.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.6.md);
+prior published: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);
 prior published: [4.8.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.4.md);
 prior published: [4.8.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.3.md);
 prior published: [4.8.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.2.md);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.6",
+  "version": "4.8.7",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.8.6",
+  "version": "4.8.7",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.6",
+      "version": "4.8.7",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -19,6 +19,9 @@ description: Session 0 — write the rules file (ark.config.json) to match the r
 - Existing tree: propose **SharedKernel** (types/constants) + **CompositionRoot** (wiring) + `src/**/domain/**`. Never dump bare `src/lib/**` into Application.
 - Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
 - Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
+- When the product map or glossary names a house, write `layers[].description` as
+  app-context copy (what this folder is *in the product*). Compact starter may omit.
+  Do not invent captions. Do not invent `/ark-describe`.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
@@ -88,6 +91,16 @@ When present, prefer the consumer **domain glossary** for layer names, slice fol
 - Prefer glossary terms over inventing parallel vocabulary.
 - Call out conflicts between glossary language and code reality (process judgment).
 - **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
+- When the glossary (or product map) names a house, that name is the `layers[].description` source — write it; do not invent a parallel caption.
+
+## Layer captions (process)
+
+When the **product map** (anti-wrapper) or **glossary** names a house, write
+`layers[].description` on that layer in this turn. One sentence of **app context**
+(what this folder is *in the product* — e.g. "Purchase requests — from asked to
+received."), not architecture jargon. Compact starter / `ark start` may omit the
+field. Absence is silent — never fail `--strict-config` for a missing caption.
+Do **not** invent captions. Do not invent `/ark-describe`.
 
 ## When / not when
 
@@ -235,6 +248,8 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    User wants the ArkOrder extra → write **advisory** `arkOrder` (schema `1.3+`, real
    `planeRoots`, existing `managedLayers`, `maxXiKeys` 7) **in this turn**. Do not add extras
    to a compact starter. Do not promote to enforced as the session-0 default.
+   When the product map or glossary names a house, write `layers[].description` on that
+   layer (app-context sentence). Compact starter may omit. Do not invent captions.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
    The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
@@ -246,7 +261,8 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    Empty Domain/Persistence + I/O under Application → false-green.
    **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
 3. **Classify ungoverned** — use coverage `suggestions` **plus** dirs you discovered by reading;
-   add layers/patterns **here** (write `ark.config.json`).
+   add layers/patterns **here** (write `ark.config.json`). When adding a layer the product map
+   or glossary already names, write `layers[].description` on it (do not invent filler).
 4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
    - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
    - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
@@ -285,6 +301,7 @@ proposals applied or deferred, **phase**, **top Shape / design-weak opportunitie
 - Put `arkRun` or `arkOrder` on the compact starter / `ark start` scaffold.
 - Claim in-memory kernel stores are production durability.
 - Invent `/ark-run` or `/ark-order`.
+- Invent `layers[].description` filler or a `/ark-describe` skill.
 - Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
 - End adopt with only “baseline written” when design-weak residual is visible in files you opened.
 

package/templates/agent-skills/ark-place/SKILL.md

@@ -19,6 +19,8 @@ description: "Where does new code go? Names the folder from the rules file and w
 - `filePath` is known before the call. Description alone is not a path.
 - Golden pattern is load-bearing when present. Adopt generates it.
 - Do not default a repository to Presentation.
+- When the matched layer has `layers[].description`, print that caption next to the
+  layer name and globs. Omit when absent — do not invent a caption or `/ark-describe`.
 - When `arkRun` is on: scaffold through the kernel (no `new` of managed types; declare
   `uses` / `reactsTo` / `raises` / `sends`; factory only in `arkRun.kernelRoots`,
   `compositionRoots` alias). Extra off → do not introduce the kernel. Enable it
@@ -57,6 +59,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
 
+## Layer captions (process)
+
+When `ark_place` / the contract includes `layers[].description`, print that caption
+next to the layer name and globs. Omit it when the field is absent. Do **not** invent
+a caption or `/ark-describe`.
+
 ## Deep modules (process)
 
 - Place so new code stays **deep**: one small public surface per concern; hide implementation details.
@@ -80,7 +88,8 @@ and — if they asked to build it — scaffold it there correctly.
 **No artifact given?** If the skill is invoked with nothing to place, don't error
 and don't guess — the artifact is the one thing only the user knows. Read the
 contract (step 1) and print the placement map from it: one row per declared layer
-with what belongs there, its directory, and which layers it may/may not import,
+with layer name, globs, and `layers[].description` when present (omit when absent),
+what belongs there, its directory, and which layers it may/may not import,
 plus the not-yet-adopted `suggestedLayers` as a footnote. Then ask what they want
 to place. That map is derived entirely from the repo, so producing it is real work,
 not a stalling question.
@@ -164,7 +173,9 @@ the same files or weaken the gate.
    the mandatory `ark_identity` preflight first, then call **`ark_place`** with the target file
    path and bound `project` envelope — it returns the layer,
    its forbidden globals, and exactly which layers the file may / must not import,
-   straight from the contract (no guessing). When present, also honor optional
+   straight from the contract (no guessing). When the matched layer has
+   `layers[].description`, print that caption next to the layer name and globs;
+   omit it when absent. When present, also honor optional
    **`goldenPattern`** (from `.ark/golden-pattern.json`) for **NEW code only** —
    advisory layout norm; never overrides the gate and never clears design-weak.
    Absent golden is normal. Otherwise load `ark.config.json`; after the matched preflight,
@@ -197,7 +208,8 @@ the same files or weaken the gate.
      same technical layer are peerIsolation violations.
 3. **Answer concretely**: layer name, target directory (from the layer's
    `patterns`), intent-name prefix if the layer declares `intentPrefixes`, and
-   which layers it may/may not import (from `rules`).
+   which layers it may/may not import (from `rules`). When present, print
+   `layers[].description` next to the layer name and globs; omit when absent.
 4. **If the layer isn't adopted yet** (suggested but no directory): write the
    layer into `ark.config.json` (session-0 honesty — same as `/ark-adopt` for
    that glob) **then** write the file. Don't silently drop the code into a
@@ -242,7 +254,8 @@ the same files or weaken the gate.
 ## Verify and report
 
 If you created files, run `ark-check --root . --config ark.config.json
---strict-config` and make it pass. Report: placement + why, files created (if
+--strict-config` and make it pass. Report: placement + why (include the caption
+next to layer name and globs when present; omit when absent), files created (if
 any), and the import rules the new code must respect going forward.
 
 ## Completion contract (skill incomplete if missing)

package/templates/skills/ark-adopt.md

@@ -19,6 +19,9 @@ description: Session 0 — write the rules file (ark.config.json) to match the r
 - Existing tree: propose **SharedKernel** (types/constants) + **CompositionRoot** (wiring) + `src/**/domain/**`. Never dump bare `src/lib/**` into Application.
 - Generate `.ark/golden-pattern.json` (load-bearing for `/ark-place`).
 - Future houses: mark unused layer globs `reserved` / `allowEmpty` so `--strict-config` does not fail.
+- When the product map or glossary names a house, write `layers[].description` as
+  app-context copy (what this folder is *in the product*). Compact starter may omit.
+  Do not invent captions. Do not invent `/ark-describe`.
 - CLI-first: if `arkgate-check` already resolved the root, do not wait on MCP.
 - Do not add `arkRun` or `arkOrder` unless the user wants that extra. When they do, write
   **advisory** extra in this turn (`arkRun` schema `1.2+`; `arkOrder` schema `1.3+`).
@@ -88,6 +91,16 @@ When present, prefer the consumer **domain glossary** for layer names, slice fol
 - Prefer glossary terms over inventing parallel vocabulary.
 - Call out conflicts between glossary language and code reality (process judgment).
 - **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
+- When the glossary (or product map) names a house, that name is the `layers[].description` source — write it; do not invent a parallel caption.
+
+## Layer captions (process)
+
+When the **product map** (anti-wrapper) or **glossary** names a house, write
+`layers[].description` on that layer in this turn. One sentence of **app context**
+(what this folder is *in the product* — e.g. "Purchase requests — from asked to
+received."), not architecture jargon. Compact starter / `ark start` may omit the
+field. Absence is silent — never fail `--strict-config` for a missing caption.
+Do **not** invent captions. Do not invent `/ark-describe`.
 
 ## When / not when
 
@@ -235,6 +248,8 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    User wants the ArkOrder extra → write **advisory** `arkOrder` (schema `1.3+`, real
    `planeRoots`, existing `managedLayers`, `maxXiKeys` 7) **in this turn**. Do not add extras
    to a compact starter. Do not promote to enforced as the session-0 default.
+   When the product map or glossary names a house, write `layers[].description` on that
+   layer (app-context sentence). Compact starter may omit. Do not invent captions.
 2. **Check + diagnose** — `summary.concentrated` / dominant edge → fix contract first, don’t freeze.
    Cross-slice / cross-context `peerIsolation` hits are judgment: extract shared or events.
    The denial names its reason. `unclassifiable path` in bulk means shared code lives outside
@@ -246,7 +261,8 @@ Ark protects the **boundary around** a framework, not its internals. Nest/DI pub
    Empty Domain/Persistence + I/O under Application → false-green.
    **STOP — do not continue this skill as complete.** **STOP — false-green:** fix the config **in this turn** before claiming ENFORCE. Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
 3. **Classify ungoverned** — use coverage `suggestions` **plus** dirs you discovered by reading;
-   add layers/patterns **here** (write `ark.config.json`).
+   add layers/patterns **here** (write `ark.config.json`). When adding a layer the product map
+   or glossary already names, write `layers[].description` on it (do not invent filler).
 4. **Mine business rules → manifiesto** (model job — this is why the skill exists):
    - Scan for loose domain: validators, pricing/policy functions, `can*`/`calculate*`, magic business constants, publish/intent strings, logic in UI/hooks that belongs in Domain.
    - **ArkRules inventory (AR13):** run `ark-check --rules-inventory --json` for deterministic candidates
@@ -285,6 +301,7 @@ proposals applied or deferred, **phase**, **top Shape / design-weak opportunitie
 - Put `arkRun` or `arkOrder` on the compact starter / `ark start` scaffold.
 - Claim in-memory kernel stores are production durability.
 - Invent `/ark-run` or `/ark-order`.
+- Invent `layers[].description` filler or a `/ark-describe` skill.
 - Claim Enforce while governed% is low, cores empty with I/O in Application, or core bags ungoverned.
 - End adopt with only “baseline written” when design-weak residual is visible in files you opened.
 

package/templates/skills/ark-place.md

@@ -19,6 +19,8 @@ description: "Where does new code go? Names the folder from the rules file and w
 - `filePath` is known before the call. Description alone is not a path.
 - Golden pattern is load-bearing when present. Adopt generates it.
 - Do not default a repository to Presentation.
+- When the matched layer has `layers[].description`, print that caption next to the
+  layer name and globs. Omit when absent — do not invent a caption or `/ark-describe`.
 - When `arkRun` is on: scaffold through the kernel (no `new` of managed types; declare
   `uses` / `reactsTo` / `raises` / `sends`; factory only in `arkRun.kernelRoots`,
   `compositionRoots` alias). Extra off → do not introduce the kernel. Enable it
@@ -57,6 +59,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
 
+## Layer captions (process)
+
+When `ark_place` / the contract includes `layers[].description`, print that caption
+next to the layer name and globs. Omit it when the field is absent. Do **not** invent
+a caption or `/ark-describe`.
+
 ## Deep modules (process)
 
 - Place so new code stays **deep**: one small public surface per concern; hide implementation details.
@@ -80,7 +88,8 @@ and — if they asked to build it — scaffold it there correctly.
 **No artifact given?** If the skill is invoked with nothing to place, don't error
 and don't guess — the artifact is the one thing only the user knows. Read the
 contract (step 1) and print the placement map from it: one row per declared layer
-with what belongs there, its directory, and which layers it may/may not import,
+with layer name, globs, and `layers[].description` when present (omit when absent),
+what belongs there, its directory, and which layers it may/may not import,
 plus the not-yet-adopted `suggestedLayers` as a footnote. Then ask what they want
 to place. That map is derived entirely from the repo, so producing it is real work,
 not a stalling question.
@@ -164,7 +173,9 @@ the same files or weaken the gate.
    the mandatory `ark_identity` preflight first, then call **`ark_place`** with the target file
    path and bound `project` envelope — it returns the layer,
    its forbidden globals, and exactly which layers the file may / must not import,
-   straight from the contract (no guessing). When present, also honor optional
+   straight from the contract (no guessing). When the matched layer has
+   `layers[].description`, print that caption next to the layer name and globs;
+   omit it when absent. When present, also honor optional
    **`goldenPattern`** (from `.ark/golden-pattern.json`) for **NEW code only** —
    advisory layout norm; never overrides the gate and never clears design-weak.
    Absent golden is normal. Otherwise load `ark.config.json`; after the matched preflight,
@@ -197,7 +208,8 @@ the same files or weaken the gate.
      same technical layer are peerIsolation violations.
 3. **Answer concretely**: layer name, target directory (from the layer's
    `patterns`), intent-name prefix if the layer declares `intentPrefixes`, and
-   which layers it may/may not import (from `rules`).
+   which layers it may/may not import (from `rules`). When present, print
+   `layers[].description` next to the layer name and globs; omit when absent.
 4. **If the layer isn't adopted yet** (suggested but no directory): write the
    layer into `ark.config.json` (session-0 honesty — same as `/ark-adopt` for
    that glob) **then** write the file. Don't silently drop the code into a
@@ -242,7 +254,8 @@ the same files or weaken the gate.
 ## Verify and report
 
 If you created files, run `ark-check --root . --config ark.config.json
---strict-config` and make it pass. Report: placement + why, files created (if
+--strict-config` and make it pass. Report: placement + why (include the caption
+next to layer name and globs when present; omit when absent), files created (if
 any), and the import rules the new code must respect going forward.
 
 ## Completion contract (skill incomplete if missing)