dreamteamer 0.32.0 → 0.33.0

package/collections/modules.collection.yaml

@@ -1,123 +1,77 @@
+# The modules this workspace compiled, PROJECTED by compile from what it discovered. `package.json`
+# stays the source of truth and compile keeps reading it, so a record here is a projection, never an
+# input: editing one would be editing a photograph. It earns its place because the engine reads the
+# DATA — `dependencies` is checked for cycles, `peer_collections` is what lets a cross-module
+# reference compile — and because, as a collection, its EDGES are browsable, diagrammable and
+# listable with no code written for any of them.
 name: modules
-# The modules this workspace compiled, PROJECTED by compile from what it discovered — the first
-# derived collection in core, and the shape is deliberate enough to name.
-#
-# Every other runtime-stored collection (skills, commands, ui-views…) is STAGED from a module's
-# source folder and read back by the engine. This one is neither: `package.json` stays the source of
-# truth and compile keeps reading it, so a record here is a projection, never an input. Editing one
-# would be editing a photograph.
-#
-# Why it earns a place anyway, against the three questions:
-#   1. Does the ENGINE read it? It reads the DATA, which is the test that matters. `dependencies`
-#      names modules and is checked for cycles; `peerDependencies` names collections and is what
-#      lets a cross-module reference compile at all (compile.js — "cyclic module dependencies",
-#      "an overlay cannot compile without its base"). This is enforced structure, not annotation.
-#   2. Recipe creeping into core? No. A module is the engine's own concept.
-#   3. Could a module do it instead? No — nothing inside a module can enumerate the module set.
-#
-# What it buys is the thing a `group:` label cannot express: EDGES. A group is a partition; a
-# dependency is a relation, and it has two kinds that mean different things. Once it is a
-# collection, the browse, the diagram, `dt modules list` and the nav all work with no code written
-# for any of them.
-storage: { path: modules, codec: yaml, shape: file, suffix: module }
-id:
-  generate: "{{ name | slug }}"
-  pattern: "^[a-z0-9-]+$"
-title_template: "{{ name }}"
-schema:
-  type: object
-  required: [name, location]
-  properties:
-    name:
-      type: string
-      description: The module's package name, verbatim — `@dreamteamer/crm`, `acme-workspace`.
-    title:
-      type: string
-      description: >-
-        What to CALL this module — authored as `dreamteamer.title` in its package.json, else derived
-        from the id. Authored because deriving cannot know an acronym: titleCase("crm") is "Crm".
-        A module names itself, which is what replaces a display-name map maintained in a surface.
-    description:
-      type: string
-      description: >-
-        What this module is FOR, in one line — authored as `dreamteamer.description` in its
-        package.json, never derived. Written by `dt add modules --description` and
-        `dt set modules/<id> description=…`.
-    namespaces:
-      type: array
-      items: { type: string }
-      description: >-
-        The namespaces this module DECLARES and owns — authored as `dreamteamer.namespaces` in its
-        package.json (§8). The workspace's effective set is the union of every module's declarations
-        plus its own; two modules declaring one namespace is a compile error, and USING another
-        module's namespace requires that module in `dependencies`. ABSENT means this module ships
-        into the default namespace — the empty prefix, which is the commons.
-    location:
-      type: string
-      enum: [modules, git_modules, node_modules, root]
-      description: >-
-        WHERE this module's sources sit — the folder name the operator already knows, so `dt status`
-        needs no legend. `root` is the classic no-workspace-module layout, where the workspace's own
-        sources live at its root rather than under `modules/<id>/`.
-        ⚠ Renamed from `channel` in 0.19.0, and the enum's `path` value was DELETED rather than
-        renamed: discovery never emitted it, so it was an enum advertising work nobody had done.
-        `origin` was rejected (one token from `origin/main`, which `update` literally pulls) and
-        `shape` was rejected (`storage.shape` owns that word).
-    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: >-
-        The module keeps its records in its OWN clone rather than this workspace's data/ — so a
-        write there commits in that repo, and a rename spanning both is unavoidably two commits.
-    dependencies:
-      type: array
-      description: >-
-        Modules this one cannot compile without — an overlay needs its base. HARD and acyclic;
-        compile fails on a ring and names the peer escape hatch.
-      items:
-        type: string
-        x-reference: modules
-    peer_dependencies:
-      type: array
-      description: >-
-        Collections this module REFERENCES but does not own. Soft on purpose: naming a concept
-        rather than a module is what keeps two modules from forming a ring, and what lets a module
-        ship an unused reference without dragging in a whole CRM.
-      items:
-        type: string
-        x-reference: collections
-        # SOFT, because the normal state of a module opened on its own is that its peers are NOT
-        # installed — that is the whole reason a peer is declared rather than depended on. Validated
-        # hard, this field made the record it is projected onto fail `check` for saying exactly what
-        # it exists to say, and there was no state in which an optional cross-module reference
-        # passed: dropping the declaration made `compile` fail instead, naming peerDependencies as
-        # the remedy. Present peers still resolve, and a peer that names a collection nobody ever
-        # installs is reported by `check` as a warning off `unresolved_peers`, not silently.
-        x-reference-soft: true
-    collections:
-      type: array
-      description: >-
-        Collections this module contributed a source for. A collection merged from several modules
-        appears under EVERY one of them — which is the honest answer the flat "which module owns
-        this" provenance could not give (it took the first source and dropped the overlay).
-      items:
-        type: string
-        x-reference: collections
-order: 140
-# ⚠ ALL THREE IDENTITY SPELLINGS. A module is one string after `add modules` (folder = package name
-# = id), and three strings for anything that predates it — so the listing shows the id (always
-# printed first), the package `name` and the `path`, which is how an operator sees the fork at all.
-list_fields: [location, path, namespaces, name, collections]
-icon: deployed_code
-group: system
+record_title: '{{ name }}'
+description: A module this workspace compiled — where its sources sit, what it declares, and the modules and collections it reaches.
+use_when: >-
+  asked which module ships a collection, what a module depends on, or where its sources live — read
+  here; a record is projected from the module's package.json, so change the package, not the record
+internal: true
+storage:
+  path: modules
+  format: yaml
+ids:
+  from: '{{ name | slug }}'
+  pattern: '^[a-z0-9-]+$'
+fields:
+  name:
+    type: string
+    required: true
+    description: The module's package name, verbatim — `@dreamteamer/crm`, `acme-workspace`.
+  title:
+    type: string
+    description: What to CALL this module — `dreamteamer.title` in its package.json, else derived from the id. Authored where deriving cannot know an acronym (`crm` → `CRM`).
+  description:
+    type: string
+    description: What this module is FOR, in one line — `dreamteamer.description` in its package.json, never derived.
+  namespaces:
+    type: string
+    many: true
+    description: >-
+      The namespaces this module declares and owns — `dreamteamer.namespaces` in its package.json. The
+      workspace's set is the union of every module's declarations plus its own; two modules declaring
+      one namespace is a compile error, and using another module's namespace requires that module in
+      `dependencies`. Absent: the module ships into the default namespace, the empty prefix.
+  location:
+    type: string
+    required: true
+    enum: [modules, git_modules, node_modules, root]
+    passthrough: true
+    description: >-
+      Where this module's sources sit — the folder name, so `dt status` needs no legend. `root` is the
+      classic layout, where the workspace's own sources live at its root rather than under `modules/<id>/`.
+  path:
+    type: string
+    description: Workspace-relative root of the module's sources.
+  bin:
+    type: string
+    many: true
+    description: The module's runnable entry points — every file under its `bin/`, module-relative. Rendered into the orientation block as the pointer that a procedure is a script here.
+  owns_data:
+    type: boolean
+    description: The module keeps its records in its OWN clone rather than this workspace's data/ — a write there commits in that repo, and a rename spanning both is two commits.
+  dependencies:
+    type: modules
+    many: true
+    description: Modules this one cannot compile without — an overlay needs its base. Hard and acyclic; compile fails on a ring and names the peer escape hatch.
+  peer_collections:
+    type: string
+    many: true
+    description: >-
+      Collections this module references but does not own. Soft by design: naming a concept rather than
+      a module keeps two modules from forming a ring, and lets a module ship a reference to a
+      collection nobody installed. A plain list of names, because the point is that the target may be absent.
+  collections:
+    type: collections
+    many: true
+    description: Collections this module contributed a source to. A collection merged from several modules appears under every one of them.
+display:
+  nav:
+    icon: deployed_code
+    order: 140
+  list:
+    columns: [location, path, namespaces, name, collections]

package/collections/repos.collection.yaml

@@ -1,61 +1,58 @@
 name: repos
-description: >-
-  A git repository this workspace knows about — where it lives and how a working tree is
-  materialized on demand.
+record_title: '{{ name }}'
+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
+  repo — read the record here for WHERE it lives (`path`, a `${env:…}` variable `dt resolve` renders
   per machine) before assuming a path or concluding a clone is unreachable; `dt status` reports
   each one and `dt install repos/<id>` 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).
-# Working trees are materialized ON DEMAND via `dreamteamer install repos/<id>`, and never as part
-# of making a checkout ready: the record count only grows and any given session needs almost none
-# of them.
-storage: { path: data/repos, codec: yaml, shape: file, suffix: repo }
-id:
-  generate: "{{ name | slug }}"
-  pattern: "^[a-z0-9-]+$"
-schema:
-  type: object
-  required: [name, url]
-  properties:
-    name:
-      type: string
-      description: The CLONE FOLDER name, not a display title — this is what appears on disk.
-    description:
-      type: string
-      description: What this repo is, in one line.
-    url:
-      type: string
-      description: The git remote to clone from.
-    ref:
-      type: string
-      default: main
-      description: Branch or tag to check out.
-    identity:
-      type: string
-      description: 'Opaque path segment grouping clones by the account that owns them: <repos-path>/<identity>/<name>.'
-    path:
-      type: string
-      description: >-
-        Where the working tree goes, winning over the derived <repos-path>/<identity>/<name>. Takes
-        the ${env:NAME} / ${workspaceFolder} / ${userHome} templates, rendered when the path is
-        needed — which is how a repo that lives OUTSIDE this workspace is expressed, since an
-        absolute rendering escapes the root while a plain relative one still anchors to it.
-    visibility:
-      type: string
-      enum: [private, public]
-      default: private
-      description: Whether the repo is public. Defaults to private, because assuming otherwise is the expensive mistake.
-order: 145
-list_fields: [name, identity, ref, url]
-icon: source
-# MACHINERY, NOT A DOMAIN NOUN, and `group: system` is the whole statement of it. `repos` is the
-# engine's only collection whose records live in `data/`, which used to make every workspace render
-# a **System** module group with one collection under it — the group the block's own renderer says
-# should not exist (harnesses.js). Being in the `system` partition folds it out of the block's
-# domain listing and onto the schema surface instead. The records stay real, writable and committed;
-# only the presentation changes.
-group: system
+# 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). Working trees are materialized on demand, never as part of making a
+# checkout ready. Internal: workspace plumbing rather than a domain noun, so it is drawn on the
+# schema surface; its records are ordinary, writable, committed data.
+internal: true
+storage:
+  path: data/repos
+  format: yaml
+ids:
+  from: '{{ name | slug }}'
+  pattern: '^[a-z0-9-]+$'
+fields:
+  name:
+    type: string
+    required: true
+    description: The CLONE FOLDER name, not a display title — this is what appears on disk.
+  description:
+    type: string
+    description: What this repo is, in one line.
+  url:
+    type: string
+    required: true
+    title: URL
+    description: The git remote to clone from.
+  ref:
+    type: string
+    default: main
+    description: Branch or tag to check out.
+  identity:
+    type: string
+    description: 'Opaque path segment grouping clones by the account that owns them: <repos-path>/<identity>/<name>.'
+  path:
+    type: string
+    description: >-
+      Where the working tree goes, winning over the derived <repos-path>/<identity>/<name>. Takes the
+      ${env:NAME} / ${workspaceFolder} / ${userHome} variables, rendered when the path is needed — which
+      is how a repo that lives OUTSIDE this workspace is expressed, since an absolute rendering escapes
+      the root while a plain relative one still anchors to it.
+  visibility:
+    type: string
+    default: private
+    enum: [private, public]
+    description: Whether the repo is public. Defaults to private, because assuming otherwise is the expensive mistake.
+display:
+  nav:
+    icon: source
+    order: 145
+  list:
+    columns: [name, identity, ref, url]

package/collections/skills.collection.yaml

@@ -1,22 +1,33 @@
 name: skills
-storage: { path: skills, codec: md, shape: folder, entry: SKILL.md }
-id: { generate: "{{ name | slug }}" }
-schema:
-  type: object
-  required: [name, description]
-  properties:
-    name:
-      type: string
-      description: The skill id — must equal the folder name.
-    description:
-      type: string
-      description: WHEN to load this skill, not what it contains. A session matches its situation against this line, so a description that describes the contents is a skill that never triggers.
-    instructions:
-      type: string
-      format: markdown
-      x-body: true
-      description: The skill itself. Keep it a digest with references/ beside it — a skill nobody can afford to load is not a capability.
-order: 20
-list_fields: [name, last-modified, description]
-icon: psychology
-group: system
+record_title: '{{ name }}'
+description: A procedure a session loads on its own when its situation matches — its `description` is the trigger, never a summary.
+use_when: >-
+  a job recurs and a session should find the know-how for it without being told — write the procedure
+  here; not a command (an operator has to remember to run one) and not an agent (a whole context)
+internal: true
+storage:
+  path: skills
+  format: md
+  shape: folder
+  entry: SKILL.md
+ids:
+  from: '{{ name | slug }}'
+fields:
+  name:
+    type: string
+    required: true
+    description: The skill id — must equal the folder name.
+  description:
+    type: string
+    required: true
+    description: WHEN to load this skill, not what it contains. A session matches its situation against this line, so a description that describes the contents is a skill that never triggers.
+  instructions:
+    type: markdown
+    body: true
+    description: The skill itself. Keep it a digest with references/ beside it — a skill nobody can afford to load is not a capability.
+display:
+  nav:
+    icon: psychology
+    order: 20
+  list:
+    columns: [name, last_modified, description]

package/collections/ui-views.collection.yaml

@@ -1,48 +1,59 @@
+# A view is a named variant of a collection's default view. The default view is the collection's own
+# `display`; a view carries the same block and compile merges it over the collection's, so a view
+# states only what it changes.
 name: ui-views
 title: UI Views
-storage: { path: ui-views, codec: yaml, shape: file, suffix: ui-view }
-id: { generate: "{{ path | slug }}" }
-schema:
-  type: object
-  required: [path, target, layout]
-  properties:
-    path:
-      type: string
-      description: The route this view renders at. The record id is derived from it, so a view saved from the CLI and one saved from the UI land on the same record.
-    nav:
-      type: object
-      description: How the view appears in navigation. Omit it entirely for a route with no nav entry.
-      properties:
-        label:
-          type: string
-          description: What the nav entry reads.
-        icon:
-          type: string
-          description: material-symbols-outlined icon name for the nav entry.
-        order:
-          type: number
-          description: Sort position among its siblings.
-    target:
-      type: string
-      enum: [list, item, page]
-      description: What the view renders — a collection listing, one record, or a standalone page.
-    collection:
-      type: string
-      x-reference: collections
-      description: Which collection this view is of.
-    default:
-      type: boolean
-      description: 'Marks the view a bare /content/<collection> renders. Directus-parity: a collection''s default presentation is an ordinary view record, not a second mechanism. At most one per collection, and never its own route — it IS the collection page.'
-    layout:
-      type: string
-      description: A REGISTERED layout/component id (table, cards, kanban, calendar, map…). An unregistered id degrades visibly rather than erroring.
-    options:
-      type: object
-      description: Layout-specific settings — columns, sort, grouping. Deliberately open, since each layout wants different things.
-    filter:
-      type: object
-      description: The saved filter this view applies, in the studio's operator set.
-order: 50
-list_fields: [path, last-modified, target, collection, layout]
-icon: dashboard_customize
-group: system
+record_title: '{{ route }}'
+description: A named way to draw a collection, a record or a page — a route, a scope, a filter, and the display keys it changes from the collection's own.
+use_when: >-
+  a collection needs a second way to be looked at (a board by status, today's rows, a map) — write
+  the view here with only the display keys it changes; the collection's default list and record page
+  are its descriptor's `display`, never a view
+internal: true
+storage:
+  path: ui-views
+  format: yaml
+ids:
+  from: '{{ route | slug }}'
+fields:
+  name:
+    type: string
+    description: A short handle for the view, for people reading the sources.
+  title:
+    type: string
+    description: The view's heading where a surface draws one.
+  description:
+    type: string
+    description: What the view shows and who it is for, in one line.
+  route:
+    type: string
+    required: true
+    description: The path this view renders at, starting with /. The record id is derived from it, so a view saved from the CLI and one saved from a surface land on the same record.
+  scope:
+    type: string
+    required: true
+    enum: [record, collection, page]
+    description: What the view draws — one record, a collection's rows, or a standalone page.
+  collection:
+    type: collections
+    description: The collection the view is of. A page may omit it.
+  filter:
+    type: map
+    description: The rows the view keeps, as field → condition in the filter operator set. Accepts the value tokens `$today` and `$now`.
+  display:
+    type: map
+    description: >-
+      The display keys this view changes, in the collection's own block — `nav` (title · icon · order),
+      `list` (layout · columns · sort · options), `record` (layout · subtitle · badge · color_by ·
+      options), `form` (sections). Merged over the collection's display sub-block by sub-block, a key
+      set here winning; a view with no `nav` has no nav entry.
+  compiled:
+    type: map
+    derived: true
+    description: Written by compile — `display`, the view's display merged over its collection's. What a surface draws.
+display:
+  nav:
+    icon: dashboard_customize
+    order: 50
+  list:
+    columns: [route, scope, collection, last_modified]

package/mixins/docs.mixin.yaml

@@ -0,0 +1,21 @@
+name: docs
+description: >-
+  title / content / tags, under a dated 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`.
+use_when: a collection holds documents written on a day — list this mixin rather than restating the fields and the dated id
+ids:
+  from: '{{ created | date }}--{{ title | slug }}'
+  pattern: '^\d{4}-\d{2}-\d{2}--[a-z0-9-]+$'
+fields:
+  title:
+    type: string
+    required: true
+  tags:
+    type: string
+    many: true
+  content:
+    type: markdown
+    body: true
+display:
+  list:
+    columns: [title, tags]

package/mixins/entity.mixin.yaml

@@ -0,0 +1,22 @@
+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`.
+use_when: a collection holds named things — list this mixin rather than restating the fields and the slug id
+ids:
+  from: '{{ name | slug }}'
+  pattern: '^[a-z0-9][a-z0-9-]*$'
+fields:
+  name:
+    type: string
+    required: true
+  tags:
+    type: string
+    many: true
+  notes:
+    type: markdown
+    body: true
+display:
+  list:
+    columns: [name, tags]

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.32.0",
+	"version": "0.33.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>",
@@ -55,7 +55,8 @@
 		"commands",
 		"command-bindings",
 		"ui-views",
-		"collection-templates"
+		"mixins",
+		"scripts/migrate-descriptors-v2.mjs"
 	],
 	"dependencies": {
 		"ajv": "^8.17.1",
@@ -75,6 +76,7 @@
 		"metrics": "node scripts/metrics.mjs",
 		"metrics:check": "node scripts/metrics.mjs --check",
 		"layers": "node scripts/layers.mjs",
-		"verify": "node scripts/layers.mjs && node scripts/metrics.mjs --check && node scripts/test.mjs"
+		"verify": "node scripts/layers.mjs && node scripts/metrics.mjs --check && node scripts/test.mjs",
+		"verify:fast": "node scripts/layers.mjs && node scripts/metrics.mjs --check && node scripts/test.mjs --changed"
 	}
 }