dreamteamer 0.19.1 → 0.21.0

package/collection-templates/docs.collection-template.yaml

@@ -1,4 +1,7 @@
 name: docs
+description: >-
+  title / content / tags, under a dated slug id (`2026-07-23--<title>`) — the shape of a thing that
+  HAPPENED or was written on a day: a note, a report, a meeting write-up. For a thing that IS, use `entity`.
 template:
   storage: { codec: md, shape: file }
   id:

package/collection-templates/entity.collection-template.yaml

@@ -2,6 +2,10 @@
 # no date prefix (docs-style dated ids read wrong for things that ARE, not happen).
 # storage is left to the template mechanism's standard defaults (data/<name>, md, file).
 name: entity
+description: >-
+  name / notes / tags, under a bare slug id (`<name>`) — the shape of a thing that IS: a person, a
+  supplier, a tool. No date in the id, because an entity does not happen on a day. For a dated
+  document, use `docs`.
 template:
   id:
     generate: "{{ name | slug }}"

package/collections/collections.collection.yaml

@@ -10,18 +10,23 @@ schema:
       description: The collection id — must equal the filename, and must be unique across every installed module.
     description:
       type: string
-      description: What kind of thing this collection holds, in one line.
+      description: >-
+        What one record IS, in one line — and the neighbour it is NOT, when a confusable one exists
+        ("the person, never the org — that is `companies`"). Rendered into the orientation block
+        every agent session loads, so it is retrieval surface, not documentation.
     use_when:
       type: string
       description: >-
-        WHEN to reach for this collection, in one clause — rendered into the orientation block every
-        agent session loads. OPTIONAL and usually absent: for most collections the trigger IS the
-        description (`contacts` = a person; you use it when you have a person), and a restatement
-        there costs every session tokens while diluting the few that carry real information. The
-        test: author this only when an agent that FULLY UNDERSTANDS the description would still not
-        know to reach for the collection. It spans both acts — read ("you are about to diagnose a
-        defect — search here first") and write ("a day needs planning"). NOT a place for procedure:
-        a `how` belongs in the module's skill, this field holds a `when`.
+        The SITUATIONS that should bring a session here, in one clause — rendered under the
+        description in the orientation block. A description says what a record is; this says when
+        to reach for the collection, in both directions: to READ ("about to diagnose a defect — search
+        here first, filtered by repo") and to WRITE ("a thought arrives that has no home yet"). Author
+        it for every collection whose trigger is not literally "you have one of these": a schema is
+        designed to be used, and the measured failure is a session inventing a new state or field while
+        the collection that already modelled it sat in its context. Two rules: it names a situation,
+        never a procedure (a `how` belongs in the module's skill); and it must not restate the
+        description — a paraphrase costs every session tokens and dilutes the clauses that carry
+        signal. Omit only where the noun is the whole trigger.
     title:
       type: string
       description: What to call this collection in the nav and page headers. DERIVED from `name` by title-casing when absent — author it only when that is wrong (`ui-views` → `UI Views`).

package/collections/modules.collection.yaml

@@ -66,6 +66,15 @@ schema:
     path:
       type: string
       description: Workspace-relative root of the module's sources.
+    bin:
+      type: array
+      description: >-
+        The module's runnable entry points — every file under its `bin/`, module-relative, projected by
+        compile. Rendered into the orientation block beside the module's skills and commands as the
+        POINTER that a procedure is a script here (how to run it stays in the module's skill); a module
+        with no `bin/` has no field.
+      items:
+        type: string
     owns_data:
       type: boolean
       description: >-

package/collections/repos.collection.yaml

@@ -2,6 +2,11 @@ name: repos
 description: >-
   A git repository this workspace knows about — where it lives and how a working tree is
   materialized on demand.
+use_when: >-
+  a repository this workspace depends on is named — its own engine or extension clone, a client's
+  repo — read the record here for WHERE it lives (`path`, a `${env:…}` template `dt resolve` renders
+  per machine) before assuming a path or concluding a clone is unreachable; `dt status` reports
+  each one and `dt ensure` materializes it
 # An external git repo attached to this workspace. Owns CLONE LIFECYCLE ONLY — a repo record
 # never contributes schema, skills or UI (that is what a module is, declared in package.json
 # `dreamteamer.git-modules`, because modules must be restorable BEFORE compile can run).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.19.1",
+	"version": "0.21.0",
 	"description": "A workspace compiler for coding agents — schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",

package/skills/using-dreamteamer/references/before-you-build.md

@@ -40,7 +40,7 @@ install. The looking still matters; the taking changed shape.
 
 | # | look at | how, concretely | what you get |
 |---|---|---|---|
-| 1 | **this workspace's own modules** | the orientation block's COLLECTIONS list is already in your context — reread it with the concept's *synonyms* in mind; `.dreamteamer/manifest.yaml` names every module and entry; `dt help` shows the verbs and `dt commands <collection>` the bound ones; the skills index shows the techniques | the thing may already exist under a name you didn't guess. This is where misses actually happen, because it is the place you assume you already know |
+| 1 | **this workspace's own modules** | the orientation block's MODULES AND THEIR COLLECTIONS list is already in your context — find the module whose sentence owns the concept, then reread its collections with the concept's *synonyms* in mind, `use when` clauses included; then read the candidate's DESCRIPTOR, not its records; `dt help` shows the verbs and `dt commands <collection>` the bound ones; the module's skills line names the techniques | the thing may already exist under a name you didn't guess. This is where misses actually happen, because it is the place you assume you already know |
 | 2 | **a recipes repo — where this workspace's own CLAUDE.md names one** (reference modules maintained to be **copied and adapted**) | read that repo's own instructions first; they ARE the adoption procedure. no recipes repo declared → skip this row | a working module with its reasoning attached — descriptors, skills, and the trap notes that each cost someone a day |
 | 3 | **a sibling workspace — where the operator has named one** | read-only; grep its `modules/` for the concept. none named → skip | another vault may have solved it concretely. That is a *reference*, not a source — it holds real personal data, so read the shape, never lift the content |
 | 4 | **the engine's own surface** | `dt help` — the complete verb surface, system and field verbs included; read it rather than recalling it | the capability may already be a verb (`relations rebuild`, `resolve`, `ensure`) rather than a missing module |

package/skills/using-dreamteamer/references/collections.md

@@ -227,6 +227,45 @@ Two gates around it:
 - ⚠ **An overlay can add fields but cannot remove an inherited one.** If the shape is wrong for
   the module rather than just for this workspace, fix the base.
 
+## `x-choices` — what an enum VALUE looks like
+
+An enum value carries a label and nothing else by default: a surface gets `{ text, value }` and
+draws the value. `x-choices` is an OPTIONAL sparse map, keyed by the value, that gives a surface
+more to draw with — a board grouping by the field, a dropdown in a form, anything reading
+`edit_options.choices`.
+
+```yaml
+lane:
+  type: string
+  enum: [alpha, bravo, charlie]
+  x-choices:
+    alpha:
+      label: Alpha team          # what a surface shows; the stored VALUE is still `alpha`
+      description: the one that ships
+      icon: rocket               # a codicon name …
+      color: charts.blue         # a theme colour id — the accent
+      background: charts.blue    #   … and the fill
+    bravo:
+      icon: assets/icons/lucide/anchor   # … OR a reference to a `codec: file` record
+```
+
+- **Sparse and additive.** Decorate one value, or none. A value with no entry projects exactly as it
+  did before this keyword existed, so adding it changes nothing that already works.
+- **`enum` still owns the value set AND its order.** A map key cannot add, remove or reorder a
+  value — which matters, because a grouped view takes its band order from the enum.
+- **Five keys, and only five** — `label` · `description` · `icon` · `color` · `background`, each an
+  optional string. Anything else in an entry is dropped: the projection copies by name, so a
+  descriptor cannot inject keys into a contract every surface reads.
+- **`label` becomes `text`.** So a workspace can relabel a value without touching the value, and no
+  stored record moves.
+- **`icon` is a codicon name or a reference to a record of a `codec: file` collection.** A codicon
+  name never contains a slash and a record reference always does, so the surface decides which
+  without a second keyword.
+- **Colours are theme colour ids, not hex.** A hex is authored against one theme and wrong in the
+  other.
+- **Both mistakes warn rather than fail** — a key that is not one of the enum's values, and the
+  keyword on a field with no enum. See the message catalog below.
+
 ## the reference contract — `x-reference` across the module graph
 
 Every `x-reference` target must be one of: a **core** collection (the entity kinds plus `repos`)
@@ -291,6 +330,8 @@ collection author actually meets. (⚠ = warning: it compiled, and you should st
 | `cyclic module dependencies: a → b → a` | concept-level links declared as module deps | the collection belongs in `peerDependencies` |
 | relation refusals (`stamps a mirror onto…`, `declared on both sides…`) | the relation rules | `data-modeling.md` Part VI |
 | ⚠ `x-unique on "f" is inert` | a relation keyword with no relation — nothing enforces it | declare the inverse, or drop it |
+| ⚠ `x-choices on "f" has an entry for "k"` | it decorates enum VALUES and `k` is not one — a typo, or a value since removed | fix the spelling, or drop the entry |
+| ⚠ `x-choices on "f" is inert` | the keyword on a field that declares no enum — nothing reads it | give the field an enum, or drop the keyword |
 | ⚠ `collection … has no description` | it renders as a bare name in the orientation block every session loads | write the sentence (`data-modeling.md` §18) |
 | ⚠ `module "…" contributed no recognised sources` | its folders match no kind and it ships no UI bundle | usually a layout or naming mistake |
 | ⚠ `module X: <channel> copy shadows <channel> copy` | the same module delivered twice — the more local wins (npm-link semantics) | intended for dev; otherwise remove one |

package/skills/using-dreamteamer/references/data-modeling.md

@@ -420,23 +420,43 @@ step downstream.
 ### 18. Descriptions and `use_when` — the model is also the prompt
 
 In an agent-operated workspace, descriptor prose is not documentation; it is **retrieval surface**.
-Collection descriptions are compiled into the orientation block every session loads, and field
-descriptions are what an agent reads before writing a value. So:
-
-- A collection's `description` carries the question it answers **and the neighbour it is NOT**:
+The orientation block every session loads is rendered from it, top-down: each **module's** sentence
+heads its group (with the namespaces, skills and commands it ships), each **collection's**
+`description` and `use_when` follow, and field descriptions are what an agent reads before writing a
+value. Three layers, three questions — *what is this area for* · *what is this thing, and when do I
+reach for it* · *what does this value mean*. So:
+
+- A **module's** `description` (its package.json — `dreamteamer.description`, or npm's own
+  top-level `description`) says what the AREA is for and what it deliberately is not: the domain,
+  its boundary with a neighbouring module, anything a session must know before working in it
+  (private data, a machine-bound account). It is the top of the tree a session reads first.
+- A **collection's** `description` says what one record IS, and names the neighbour it is NOT:
   "the person, never the org — that is `companies`". Confusable pairs each point at the other.
-- A field's `description` says what the value MEANS, names the source when the value is copied
+- A collection's **`use_when`** names the SITUATIONS that should bring a session here, in both
+  directions — read ("about to diagnose a defect — search here first, filtered by repo") and write
+  ("a thought arrives that has no home yet"). **Author it for every collection whose trigger is not
+  literally "you have one of these."** A schema is designed to be used, and the measured failure
+  mode is a session inventing a new state, field or terminal condition while the collection that
+  already modelled it sat in its context under a description it had read. Two rules: it names a
+  situation, never a procedure (a `how` belongs in the module's skill); and it must not paraphrase
+  the description — that costs every session tokens and dilutes the clauses that carry signal.
+  ⚠ It is prose; nothing fires on it. It raises the odds a session looks; it does not make it.
+- A **field's** `description` says what the value MEANS, names the source when the value is copied
   from elsewhere, and states the convention an agent must follow ("empty means unmatched — the
   matching command's queue").
 - A field whose valid value has a non-obvious SHAPE carries an `examples:` annotation — standard
-  JSON Schema, passed through to the compiled descriptor — so the canonical value lives in the
-  contract, not in whichever record a writer happens to open.
-- `use_when` is authored **only** when an agent that fully understood the description would still
-  not reach for the collection — a search-here-first trigger, a write-here-when situation. It is
-  prose; nothing fires on it; and a `use_when` restating the description costs every session
-  tokens while diluting the few that carry real signal.
+  JSON Schema, passed through to the compiled descriptor unchanged, and its first value rendered
+  into the collection's `write:` line in the orientation block beside the required fields and closed
+  enums — so the canonical value lives in the contract, not in whichever record a writer happens to
+  open, and a session sees it before its first write. Two or three, real-looking
+  and synthetic: a `${env:…}` path template, a `key:value` tag, an RRULE, a composite id.
 - Descriptions are the cheapest UX in the system: the same line is the tooltip in every surface,
   the agent's guidance, and the future maintainer's note. Budget a real sentence per field.
+- Compile WARNS on a module, collection or collection-template with no description — each renders
+  as a bare name in the block otherwise — and on a `use_when` that restates its description (content
+  words shared ≥ 0.5): name the situation, do not delete the clause. It does not warn on a missing
+  `use_when`, because it cannot tell a considered omission from a forgotten one; that judgement is
+  yours, per collection.
 
 ---
 

package/src/compile.js

@@ -421,6 +421,28 @@ function bothLayouts(root, kind) {
  * (`dreamteamer.ignore`). That is real per-module variance — `services` has `dashboard/`, `agentlog`
  * has `data/` — not a layout knob every module would set identically.
  */
+/** `bin/*` files of a module root, module-relative and sorted — dotfiles and subfolders (lib/,
+ *  parsers/) excluded. Empty when there is no bin/. */
+function binEntries(moduleRoot) {
+	const dir = path.join(moduleRoot, 'bin');
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir, { withFileTypes: true })
+		.filter((e) => e.isFile() && !e.name.startsWith('.'))
+		.map((e) => `bin/${e.name}`).sort();
+}
+
+/** Content-word Jaccard between two clauses, thresholded. Short words and the join words of
+ *  English carry no signal here; ≥ 0.5 of the remaining vocabulary shared is a paraphrase. */
+function paraphrases(description, useWhen) {
+	const STOP = new Set(['this', 'that', 'with', 'from', 'into', 'here', 'when', 'what', 'never', 'every', 'their', 'there', 'them', 'they', 'have', 'been', 'each', 'than', 'then', 'only', 'also', 'before', 'after', 'about']);
+	const words = (t) => new Set(String(t ?? '').toLowerCase().replace(/[`'"“”‘’()[\],.;:—–-]/g, ' ').split(/\s+/).filter((w) => w.length > 3 && !STOP.has(w)));
+	const a = words(description), b = words(useWhen);
+	if (!a.size || !b.size) return false;
+	let shared = 0;
+	for (const w of b) if (a.has(w)) shared++;
+	return shared / (a.size + b.size - shared) >= 0.5;
+}
+
 const NON_SOURCE_DIRS = new Set([
 	'node_modules', 'data', 'state', 'media', 'bin', 'src', 'lib', 'scripts',
 	'ui', 'studio', // the module's UI bundle — 'studio' is the pre-archive name, kept as a fallback
@@ -900,6 +922,9 @@ export function compile({ root, pkg }) {
 		if (!m) continue;
 		const doc = loadSource(entry.bytes.toString('utf8'), entry.sources[0].path);
 		templateDocs.set(m[1], { template: doc?.template ?? {}, src: entry.sources[0] });
+		// The orientation block lists every template by its own sentence (harnesses.templatesSection);
+		// the engine's two shipped ones rendered as bare names for a month before anyone noticed.
+		if (!String(doc?.description ?? '').trim()) console.warn(`⚠ collection-template ${m[1]} has no description — it renders as a bare name in the orientation block every session loads`);
 	}
 
 	// ---- namespaces: the UNION of every module's declaration plus the workspace's (§8) ----------
@@ -1290,6 +1315,25 @@ export function compile({ root, pkg }) {
 			if (h['x-unique'] === true && h['x-inverse'] === undefined && h['x-inverse-of'] === undefined) {
 				console.warn(`⚠ collection ${name}: x-unique on "${fieldName}" is inert — it is a RELATION keyword, enforced only while the store maintains a mirror, and this field declares no x-inverse. Nothing constrains the value. Declare the relation (dreamteamer update-field ${name} --name ${fieldName} --inverse) or drop x-unique.`);
 			}
+			// `x-choices` decorates ENUM VALUES (presentation.js#choiceRow, 0.21.0), and both ways of
+			// getting it wrong are SILENT: a key that is not a value decorates nothing, and the keyword
+			// on a non-enum field is read by no one at all. Either way the author sees no error and no
+			// decoration — on a surface they are probably not looking at while editing the descriptor.
+			// ⚠ WARNINGS, not failures, for the same reason as x-unique directly above: neither breaks
+			// anything today, and a descriptor mid-edit must stay compilable.
+			const choices = h['x-choices'];
+			if (choices && typeof choices === 'object' && !Array.isArray(choices)) {
+				const values = Array.isArray(h.enum) ? h.enum.map(String) : null;
+				if (!values) {
+					console.warn(`⚠ collection ${name}: x-choices on "${fieldName}" is inert — it decorates the values of an enum, and this field declares no enum. Nothing reads it.`);
+				} else {
+					// Named per offending key rather than "some keys are wrong", and the legal values are
+					// quoted so the fix needs no second lookup — the same shape as every other warning here.
+					for (const k of Object.keys(choices)) {
+						if (!values.includes(k)) console.warn(`⚠ collection ${name}: x-choices on "${fieldName}" has an entry for "${k}", which is not one of its enum values (${values.join(', ')}) — it decorates nothing. Fix the spelling, or drop the entry.`);
+					}
+				}
+			}
 		}
 		const rt = path.join('collections', `${name}.collection.yaml`);
 		entries.set(rt, { sources: descriptorSources, bytes: Buffer.from(dump(merged)) });
@@ -1298,12 +1342,20 @@ export function compile({ root, pkg }) {
 		// rather than a heroic backfill pass, and the same shape as the per-missing-env-key warning:
 		// non-blocking, named per offender, so the gap converges instead of being rediscovered.
 		//
-		// ⚠ Deliberately NO equivalent warning for `use_when`. That field is optional and correct to
-		// omit on most collections — warning on it would invert its authoring test and manufacture a
-		// restatement of the description on every collection that does not need one.
+		// No equivalent warning for `use_when`, though the field is WANTED on most collections
+		// (data-modeling §18: a description says what a record IS, `use_when` says which situations
+		// should lead a session here). A warning cannot tell a considered omission from a forgotten
+		// one, and a manufactured restatement of the description is worse than an absent clause.
 		if (merged.storage.base !== 'runtime' && !String(merged.description ?? '').trim()) {
 			console.warn(`⚠ collection ${name} has no description — it renders as a bare name in the orientation block every session loads`);
 		}
+		// A `use_when` that restates the description costs every session tokens and dilutes the clauses
+		// that carry signal (data-modeling §18); a reader catches it, nothing else did. Word overlap is
+		// the mechanical proxy: the clauses that earned their place in a blind evaluation encoded an
+		// ORDER or a REFUSAL, and shared few content words with their description.
+		if (merged.use_when && paraphrases(merged.description, merged.use_when)) {
+			console.warn(`⚠ collection ${name}: use_when restates its description — name the SITUATION that brings a session here (search here first · capture here when), not the noun again`);
+		}
 		counts.collections++;
 	}
 
@@ -1332,18 +1384,26 @@ export function compile({ root, pkg }) {
 	}
 	for (const source of sources) {
 		const id = moduleId(source.name);
-		let mpkg = {};
-		try { mpkg = JSON.parse(fs.readFileSync(path.join(source.root, 'package.json'), 'utf8')).dreamteamer ?? {}; } catch { /* inline workspace source */ }
+		let pkg = {};
+		try { pkg = JSON.parse(fs.readFileSync(path.join(source.root, 'package.json'), 'utf8')); } catch { /* inline workspace source */ }
+		const mpkg = pkg.dreamteamer ?? {};
+		// What this module is FOR, in one line. `dreamteamer.description` wins; npm's own top-level
+		// `description` is the fallback, because it is the one place a package author already writes
+		// that sentence — six modules on one dogfood workspace had authored it THERE and every
+		// `dt list modules` row read `-` for description. There is no derivation past that and there
+		// should not be: a module is the only place that knows.
+		const description = [mpkg.description, pkg.description].find((s) => typeof s === 'string' && s.trim());
+		// A module with no sentence renders as a bare title at the head of its section in the
+		// orientation block — the one place a session learns what an AREA of the workspace is for.
+		// Same shape as the per-collection warning: non-blocking, named per offender.
+		if (!description) console.warn(`⚠ module ${source.name} has no description — set "description" in its package.json; it heads its own section in the orientation block every session loads`);
 		const record = {
 			name: source.name,
 			// Authored wins; the derived fallback title-cases the id the same way a collection's
 			// `title` is derived. `@dreamteamer/crm` -> "Crm" until crm declares "CRM" — which is
 			// the point: the module is the only place that knows.
 			title: typeof mpkg.title === 'string' && mpkg.title ? mpkg.title : titleCase(id),
-			// What this module is FOR, in one line — authored as `dreamteamer.description` in its
-			// package.json. There is no derivation for it and there should not be: a module is the only
-			// place that knows, and an absent one renders as a bare name in every listing.
-			...(typeof mpkg.description === 'string' && mpkg.description ? { description: mpkg.description } : {}),
+			...(description ? { description } : {}),
 			// §8: the namespaces THIS module declares — projected from its package.json, so
 			// `dt list modules` answers "who owns hr?" without reading seven package.json files.
 			...(normalizeNamespaces(mpkg.namespaces).length ? { namespaces: normalizeNamespaces(mpkg.namespaces) } : {}),
@@ -1351,6 +1411,11 @@ export function compile({ root, pkg }) {
 			// `hr  git_modules @ 3f2a1c (dirty)` and needs no legend.
 			location: locationOf(source, root),
 			path: rel(source.root) || '.',
+			// The module's RUNNABLE entry points — `bin/<file>`, the folder NON_SOURCE_DIRS waves through.
+			// Skills and commands render into the orientation block; a module whose procedure is a
+			// script did not, so a session planned `dt add` writes the tooling forbids. This is the
+			// POINTER that the procedure exists, never its arguments — those stay in the skill.
+			...(binEntries(source.root).length ? { bin: binEntries(source.root) } : {}),
 			...(mpkg['owns-data'] === true ? { owns_data: true } : {}),
 			// Declared module names become record IDS here, because that is what an x-reference
 			// resolves against. An undeclared/unknown name would dangle, and `check` would say so —
@@ -1500,7 +1565,7 @@ export function compile({ root, pkg }) {
 	const anyFlat = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, k))));
 	const anyNested = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, 'system', k))));
 	const sourceLayout = anyFlat && anyNested ? 'mixed' : anyNested ? 'nested' : 'flat';
-	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout, namespaces, version: engineVer });
+	const { outputs: adapterOutputs, blocks: adapterBlocks, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout, namespaces, version: engineVer, workspaceModule: config['workspace-module'] ?? '' });
 
 	// ---- provenance manifest ------------------------------------------------------
 	const manifest = {
@@ -1535,6 +1600,9 @@ export function compile({ root, pkg }) {
 		})),
 		ui: uiModules.sort(),
 		'adapter-outputs': adapterOutputs.sort(),
+		// the root files whose managed BLOCK this compile rewrote — never pruned, but committed with a
+		// schema write so the block and the schema it names land together (schema-ops.regeneratedOutputs)
+		'adapter-blocks': adapterBlocks.sort(),
 		entries: Object.fromEntries(
 			[...entries].map(([rt, e]) => [rt, { sources: e.sources, hash: sha256(e.bytes) }]) // sources: [{path, hash}] — per-SOURCE hashes power staleness
 		),

package/src/harnesses.js

@@ -21,10 +21,17 @@ export const STAMP = '<!-- generated by dreamteamer compile — do not edit; sou
 const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 const END = '<!-- dreamteamer:end -->';
 
-export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown' }) {
+export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown', workspaceModule = '' }) {
 	const outputs = [];
+	// ⚠ SEPARATE from `outputs`: these are USER-OWNED root files carrying a managed block, and the
+	// prune loop below DELETES anything in a previous manifest's `adapter-outputs` that this compile
+	// did not produce — listing CLAUDE.md there would delete the operator's own instructions the day
+	// a harness is switched off. They are reported so a schema write can COMMIT the regenerated block
+	// beside the source it changed (schema-ops.regeneratedOutputs), which is the only other reader.
+	const blocks = [];
 	const summary = [];
 	const rel = (p) => path.relative(root, p);
+	const block = (file, content) => { writeBlock(root, file, content); if (content != null) blocks.push(file); };
 	const write = (out, bytes) => {
 		const dest = path.join(root, out);
 		fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -56,7 +63,7 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		}
 		summary.push(`claude-code → .claude (${n} files)`);
 	}
-	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version, entries) : null);
+	block('CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
 
 	// ---- shared cross-agent skills mirror (.agents/skills) — codex/pi discover it,
 	// cursor/gemini blocks point at it. written once no matter how many harnesses use it.
@@ -73,17 +80,17 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	}
 
 	// ---- codex + pi: both read root AGENTS.md; one block serves both ----------------
-	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version, entries) : null);
+	block('AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
 	if (on('codex')) summary.push('codex → AGENTS.md block');
 	if (on('pi')) summary.push('pi → AGENTS.md block + .agents/skills');
 
 	// ---- gemini-cli: GEMINI.md is its context file -----------------------------------
-	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version, entries) : null);
+	block('GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
 	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
 	if (on('cursor')) {
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries)}\n\n${STAMP}\n`;
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -105,7 +112,7 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	// pruning leaves empty skill folders behind — sweep them (and the roots when hollow)
 	for (const dir of ['.claude', '.agents', '.cursor']) pruneEmptyDirs(path.join(root, dir));
 
-	return { outputs, summary };
+	return { outputs, blocks, summary };
 }
 
 // skill id → description one-liners from each SKILL.md's frontmatter; the orientation
@@ -144,11 +151,54 @@ function buildCollectionsIndex(entries) {
 			system: d.storage?.base === 'runtime',
 			description: flat(d.description),
 			useWhen: flat(d.use_when),
+			module: d.module ?? '',
+			write: writeLine(d.schema),
 		});
 	}
 	return index.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/** What can REFUSE a write, in one clause — nothing else about the fields. Required fields with no
+ *  default (the CLI materializes defaults, so those never refuse), closed enums with their size, and
+ *  the first `examples:` value where one is authored. A blind session's plan was correct until its
+ *  first `dt add`, which the store refused on a 100-value enum and a required field the block never
+ *  showed; the descriptor stays the authority, this is the line that keeps the first write from
+ *  bouncing. Empty string when there is nothing that refuses. */
+function writeLine(schema) {
+	const props = schema?.properties ?? {};
+	const required = (schema?.required ?? []).filter((f) => props[f] && props[f].default === undefined);
+	const enums = Object.entries(props).flatMap(([f, p]) => { const e = p?.enum ?? p?.items?.enum; return Array.isArray(e) && e.length ? [`${f} enum(${e.length})`] : []; });
+	const egs = Object.entries(props).flatMap(([f, p]) => Array.isArray(p?.examples) && p.examples.length ? [`${f}='${p.examples[0]}'`] : []);
+	const parts = [...(required.length ? [`required ${required.join(' · ')}`] : []), ...(enums.length ? [enums.join(' · ')] : []), ...(egs.length ? [`e.g. ${egs.join(', ')}`] : [])];
+	return parts.join('; ');
+}
+
+/** module id -> title / description / namespaces / source path, plus the skills and commands whose
+ *  SOURCE lives under that path — read from the module records compile projected, never from
+ *  package.json again. A skill or command belongs to the module with the longest source-path prefix;
+ *  the root layout (`path: .`) is the empty prefix and so matches last. */
+function buildModulesIndex(entries) {
+	const mods = [];
+	for (const [rt, e] of entries) {
+		const m = /^modules\/(.+)\.module\.yaml$/.exec(rt);
+		if (!m) continue;
+		let d = {};
+		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { /* unparseable record */ }
+		const p = !d.path || d.path === '.' ? '' : `${d.path}/`;
+		mods.push({ id: m[1], title: d.title ?? m[1], description: flat(d.description), namespaces: d.namespaces ?? [], path: p, bin: d.bin ?? [], skills: [], commands: [] });
+	}
+	mods.sort((a, b) => b.path.length - a.path.length); // longest prefix first
+	for (const [rt, e] of entries) {
+		const kind = /^skills\/([^/]+)\/SKILL\.md$/.exec(rt) ? 'skills' : /^commands\/(.+)\.command\.md$/.exec(rt) ? 'commands' : null;
+		if (!kind) continue;
+		const src = e.sources?.[0]?.path ?? '';
+		const owner = mods.find((mod) => src.startsWith(mod.path));
+		if (owner) owner[kind].push(kind === 'skills' ? rt.split('/')[1] : path.basename(rt).replace(/\.command\.md$/, ''));
+	}
+	for (const mod of mods) { mod.skills.sort(); mod.commands.sort(); }
+	return mods;
+}
+
 /** Commands, for the harnesses that do NOT discover them natively. claude-code writes every command
  *  into `.claude/commands` and its harness injects name+description at session start, so an index in
  *  CLAUDE.md would be a second copy of what is already there. codex/pi/gemini-cli/cursor got one
@@ -176,26 +226,42 @@ function buildCommandsIndex(entries) {
  *  GEMINI.md, which are COMMITTED files. A count changes on every write, so every compile after
  *  ordinary data work would re-dirty three tracked files — in trees where more than one agent has
  *  uncommitted work — and the number would be stale the moment it was printed. Ordering is
- *  namespace-grouped then alphabetical precisely so the block diffs ONLY when the schema changed. */
-function collectionsSection(index, namespaces) {
+ *  module-grouped then alphabetical precisely so the block diffs ONLY when the schema changed.
+ *
+ *  GROUPED BY MODULE, the workspace's own first. A module is the one entity that answers "what is
+ *  this AREA of the workspace for" — its sentence heads the group, its namespaces, skills and
+ *  commands ride on the line below it, and its collections follow. Before this the block listed
+ *  nouns by namespace and the reader had to infer the domains from the prefixes; the hand-written
+ *  module table one dogfood workspace kept to fill that gap was the same failure the collection list
+ *  had already been through. A module whose every collection is system-stored (the engine) is not a
+ *  domain and gets no group; a skills-only module is one and does. */
+function collectionsSection(index, modules, workspaceModule) {
 	if (!index.length) return [];
-	const nsOf = (name) => {
-		const i = name.indexOf('/');
-		const p = i < 0 ? '' : name.slice(0, i);
-		return namespaces.includes(p) ? p : '';
-	};
 	const lines = [
 		'',
-		'COLLECTIONS — the nouns of this workspace. The descriptor at',
+		'MODULES AND THEIR COLLECTIONS — what this workspace is for, one area at a time. A module ships',
+		'one domain: its collections (the nouns), and the skills and commands that operate on them —',
+		'read its skills before working in its area. The descriptor at',
 		'`.dreamteamer/collections/<name>.collection.yaml` is the authority on fields, id shape and',
 		'defaults — read it before writing a kind you have not written this session. Create records',
-		'with `dt add <collection>`: it generates the id and rejects invalid writes before disk.',
+		'with `dt add <collection>`: it generates the id and rejects invalid writes before disk. A',
+		'collection\'s `write:` line names only what the store REFUSES — required fields that have no',
+		'default (a defaulted one is filled in for you), closed enums with their size, one example.',
 	];
 	const data = index.filter((c) => !c.system);
-	for (const group of ['', ...namespaces]) {
-		for (const c of data.filter((c) => nsOf(c.name) === group)) {
+	const isWs = (m) => m.path === `modules/${workspaceModule}/`;
+	const groups = modules
+		.filter((m) => { const own = index.filter((c) => c.module === m.id); return own.some((c) => !c.system) || (!own.length && (m.skills.length || m.commands.length || m.bin.length)); })
+		.sort((a, b) => (isWs(b) - isWs(a)) || a.title.localeCompare(b.title));
+	for (const m of groups) {
+		const where = [`\`${m.id}\``, m.path ? m.path.replace(/\/$/, '') : 'the workspace root', ...(m.namespaces.length ? [`namespaces: ${m.namespaces.join(' · ')}`] : [])];
+		lines.push('', `**${m.title}** (${where.join(' · ')})${m.description ? ` — ${m.description}` : ''}`);
+		const ships = [...(m.skills.length ? [`skills: ${m.skills.join(' · ')}`] : []), ...(m.commands.length ? [`commands: ${m.commands.map((c) => `/${c}`).join(' · ')}`] : []), ...(m.bin.length ? [`runs: ${m.bin.join(' · ')}`] : [])];
+		if (ships.length) lines.push(`  ${ships.join(' · ')}`);
+		for (const c of data.filter((c) => c.module === m.id)) {
 			lines.push(`- ${c.name}${c.description ? ` — ${c.description}` : ''}`);
 			if (c.useWhen) lines.push(`    use when: ${c.useWhen}`);
+			if (c.write) lines.push(`    write: ${c.write}`);
 		}
 	}
 	const system = index.filter((c) => c.system).map((c) => c.name);
@@ -204,7 +270,7 @@ function collectionsSection(index, namespaces) {
 	// It now names the VERBS and the one policy difference, because an agent that knows the verbs
 	// exist still has to be told that these commit and records do not.
 	if (system.length) {
-		lines.push(`- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`update-field\`/\`remove-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes). Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}`);
+		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`update-field\`/\`remove-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes). Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}`);
 	}
 	return lines;
 }
@@ -295,7 +361,7 @@ function bindingsSection(entries) {
  *  agent that splits `health/doctors/dana-levi` at the first slash reads a collection that does not
  *  exist. Naming the declared list is what makes the grammar decidable from this block alone, without
  *  the agent having to go read the manifest. A workspace with no namespaces gets no extra sentence. */
-function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown', entries = new Map()) {
+function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown', entries = new Map(), workspaceModule = '') {
 	const sourcesLine = {
 		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
@@ -327,7 +393,7 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 			'DECLARED prefix, not at the first slash. collections with no prefix are unaffected.',
 		);
 	}
-	lines.push(...collectionsSection(buildCollectionsIndex(entries), namespaces));
+	lines.push(...collectionsSection(buildCollectionsIndex(entries), buildModulesIndex(entries), workspaceModule));
 	lines.push(...templatesSection(entries));
 	lines.push(...bindingsSection(entries));
 	// claude-code discovers skills natively (Skill tool) — an index in CLAUDE.md is pure

package/src/init.js

@@ -33,6 +33,7 @@ media/
 // output, which reads as a broken install. One starter collection answers both. `notes` is
 // deliberately the most generic thing a workspace can hold.
 const STARTER_COLLECTION = `name: notes
+description: A dated note — the starter collection init seeds, to rename or replace with what this workspace actually keeps.
 storage:
   path: data/notes
   codec: md
@@ -112,7 +113,11 @@ export function init({ flags = {} } = {}) {
 		if (!fs.existsSync(modulePkg)) {
 			// `files` is the npm publish surface: every kind a module can ship, since a new one here
 			// is an engine change that would otherwise silently stop being packaged.
-			fs.writeFileSync(modulePkg, JSON.stringify({ name: wm, private: true, version: '0.0.1', files: [...KINDS], dreamteamer: {} }, null, '\t') + '\n');
+			// `description` is npm's own key and the one compile falls back to for the module's sentence
+			// — the line that heads this module's group in the orientation block. Seeded so a fresh
+			// workspace does not open with a warning about the module init just made; the operator
+			// replaces it with what THIS workspace is for.
+			fs.writeFileSync(modulePkg, JSON.stringify({ name: wm, private: true, version: '0.0.1', description: "This workspace's own collections, skills and commands.", files: [...KINDS], dreamteamer: {} }, null, '\t') + '\n');
 		}
 	}
 	// one starter collection, so `compile` has something to report instead of warning about the

package/src/presentation.js

@@ -5,7 +5,9 @@
 // the client adapter shrinks to a thin path translator. shapes deliberately match what
 // the studio components already speak (field {field,type,meta,schema}).
 
-import { sourceHint } from './runtime.js';
+// `sourceHint` is deliberately NOT imported here any more — see the note beside `system` below.
+// It survives for the store's own refusal (`store.js`) and `revert`'s (`collections-cli.js`), both
+// of which are still true statements about a path that genuinely cannot be written.
 import { refTargetsOf } from './ref.js';
 
 /** the projection for every collection: rows keyed by collection name + collection meta. */
@@ -82,15 +84,34 @@ function collectionRow(d) {
 
 	if (typeof d.group === 'string') meta.group = d.group;
 	if (typeof d.description === 'string' && d.description.length > 0) meta.description = d.description;
-	// A compiled collection is READ-ONLY through the record layer, and the UI needs to say so
-	// BEFORE offering a button — an error after the click is a worse answer than a disabled
-	// control with a reason. The sentence comes from runtime.js so the store's refusal and this
-	// hint can never disagree.
+	// ⚠ `system` IS NOT `readonly`, AND SAYING SO COST A RELEASE. Until 0.19.0 the two were the
+	// same fact: nothing could write a compiled entity, so this projection set `meta.readonly` for
+	// every `storage.base === 'runtime'` collection and the UI disabled the form. 0.19.0 gave the
+	// record verbs a system write path — `set skills/<id>`, `rename`, `rm`, `set collections/<c>`,
+	// `set modules/<id>` — dispatched at the SURFACE, around the store (`collections-cli.js`,
+	// `server.js`). This file was never touched by that wave, so the projection kept describing the
+	// old world and a skill in the workspace's own `modules/<m>/skills/` rendered padlocked while
+	// `dt set` wrote it happily.
+	//
+	// So no collection-level readonly is emitted for a system kind any more. Three reasons it is a
+	// DELETION rather than a narrower predicate:
+	//
+	//   1. Writability is per RECORD, not per collection. `skills/<one>` authored in an inline
+	//      module is writable; `skills/<another>` shipped from `node_modules/` is refused, because
+	//      the next `npm install` erases the edit. One flag on the collection cannot say both, and
+	//      a flag that is wrong half the time is worse than none.
+	//   2. On today's verb set there is no system kind with no writable path at all, so a correct
+	//      collection-level predicate would be constant-false.
+	//   3. The refusals that remain are per record (npm-shipped), per verb (`revert`, and `add` on
+	//      the hand-authored kinds) or per field (`x-body`) — none of them collection-shaped. Each
+	//      already answers with its own sentence naming the fix, which is the contract the schema
+	//      surfaces are built on.
+	//
+	// `system` STAYS and is unchanged: the CLI and REST dispatch key on it, and it is what puts a
+	// kind in the schema surface rather than the data one. A consumer that disables editing must
+	// key on `meta.readonly` (per field, as `id`, `last-modified` and relation mirrors do) or on
+	// the verb it is about to offer — never on `system`.
 	const system = d.storage?.base === 'runtime';
-	if (system) {
-		meta.readonly = true;
-		meta.readonly_hint = sourceHint(d);
-	}
 	return { collection: d.name, meta, system };
 }
 
@@ -131,6 +152,33 @@ function titleTemplateOf(prop, descriptors) {
 	return typeof first === 'string' && first.length > 0 && inherited.every((v) => v === first) ? first : undefined;
 }
 
+// The keys a descriptor may attach to an enum VALUE through `x-choices` (0.21.0), beyond the label.
+// Copied BY NAME rather than spread: a descriptor is authored data, and spreading whatever it
+// happens to carry would let a workspace inject arbitrary keys into a contract every surface reads.
+// One line is the whole vocabulary, which is also what makes it readable from the consuming side.
+//
+// `icon` is a codicon name OR a reference to a record of a `codec: file` collection — the surface
+// decides which by whether it resolves as a reference, so no second keyword and no set of known
+// collection names. `color`/`background` are theme colour ids for the same reason a hex is not one:
+// a hex is authored against one theme and wrong in the other.
+const CHOICE_KEYS = ['description', 'icon', 'color', 'background'];
+
+/**
+ * One `choices` row: `{ text, value }` as it has always been, plus whatever `x-choices` declared.
+ *
+ * ⚠ PURELY ADDITIVE. A value with no entry projects byte-identically to what it projected before
+ * this existed, which is the only reason not one of the descriptors already in the wild had to
+ * change. `label` arrives as `text` — the key every surface already reads — so a workspace can
+ * relabel a value without touching the value, and a stored record never moves.
+ */
+function choiceRow(v, entry) {
+	const row = { text: String(entry?.label ?? v), value: v };
+	if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+		for (const k of CHOICE_KEYS) if (typeof entry[k] === 'string' && entry[k].length > 0) row[k] = entry[k];
+	}
+	return row;
+}
+
 function fieldRow(d, name, prop, isRequired, descriptors) {
 	const meta = { collection: d.name, field: name };
 	if (isRequired) meta.required = true;
@@ -212,7 +260,7 @@ function fieldRow(d, name, prop, isRequired, descriptors) {
 	}
 
 	if (Array.isArray(prop.enum) && prop.enum.length > 0) {
-		meta.edit_options = { choices: prop.enum.map((v) => ({ text: String(v), value: v })) };
+		meta.edit_options = { choices: prop.enum.map((v) => choiceRow(v, prop['x-choices']?.[v])) };
 	}
 	const tpl = titleTemplateOf(prop, descriptors);
 	if (typeof tpl === 'string' && tpl.length > 0) meta.view_options = { ...meta.view_options, template: tpl };

package/src/schema-ops.js

@@ -1697,7 +1697,7 @@ function isTracked(root, rel) {
  */
 function commitByRepo(ws, store, rels, subject) {
 	const byRepo = new Map(); // workspace-relative repo root -> {root, paths relative to THAT repo}
-	for (const rel of new Set(rels)) {
+	for (const rel of new Set([...rels, ...regeneratedOutputs(ws)])) {
 		const abs = path.join(ws.root, rel);
 		// A path that is neither on disk nor in any index cannot be a pathspec, and one bad entry
 		// aborts the whole `git add` — the lesson `renameCollection` paid for. ⚠ The filter runs PER
@@ -1730,6 +1730,26 @@ function commitByRepo(ws, store, rels, subject) {
 	return out;
 }
 
+/** The harness files the gate compile just REGENERATED — CLAUDE.md, AGENTS.md, GEMINI.md and whatever
+ *  else `dreamteamer.harnesses` writes — narrowed to the ones git already TRACKS. A schema write
+ *  committed only the mutated source, so every one left the three committed root files dirty with the
+ *  block that names the very change just committed; the next unscoped `git add` in a shared tree swept
+ *  them into somebody else's subject. The list is read off the manifest compile has just written
+ *  (`adapter-outputs` for the generated dirs, `adapter-blocks` for the root files whose managed block
+ *  was rewritten), so no API changes hands. TRACKED ONLY, in one `git ls-files` call: an untracked
+ *  root file is the operator's to add (a fresh workspace has not committed its instructions yet, and
+ *  a write into a clone must not start tracking files in the workspace repo as a side effect), and an
+ *  ignored one (`.claude/`) is a hard error to `git add`, so neither may reach the pathspec. */
+function regeneratedOutputs(ws) {
+	const m = readManifest(ws.root) ?? {};
+	const outputs = [...(m['adapter-outputs'] ?? []), ...(m['adapter-blocks'] ?? [])].filter((p) => fs.existsSync(path.join(ws.root, p)));
+	if (!outputs.length) return [];
+	try {
+		return execFileSync('git', ['ls-files', '-z', '--', ...outputs], { cwd: ws.root, stdio: ['ignore', 'pipe', 'ignore'] })
+			.toString().split('\0').filter(Boolean);
+	} catch { return []; } // no git here at all — the source commit proceeds without them, as before
+}
+
 const shortHead = (root) => {
 	try { return execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: root, stdio: GIT_QUIET }).toString().trim(); } catch { return null; }
 };