dreamteamer 0.9.1 → 0.12.0

package/README.md

@@ -63,6 +63,30 @@ The shape of a record is deliberately dull, because dull is what survives:
 - a write lands on disk; `dreamteamer commit` publishes it, one commit per repo
 - schemas are JSON Schema in a YAML file, one per collection
 
+### Machine-specific references
+
+Some things a record points at only exist on one machine — a synced Drive folder, an external disk,
+a checkout somewhere else. Those are written as **templates**, never as absolute paths:
+
+```yaml
+source_file: ${env:FILES_FOLDER}/2026/q3.pdf
+```
+
+Three variables, borrowing VS Code's grammar: `${env:NAME}` — declared in `dreamteamer.vars` in
+`package.json`, valued in the gitignored `.env` — plus `${workspaceFolder}` and `${userHome}`.
+One verb renders them:
+
+```bash
+npx dreamteamer resolve '${env:FILES_FOLDER}/x'            # → /Volumes/annex/x
+npx dreamteamer resolve <collection>/<id> <field>          # render what a record already holds
+```
+
+**Templates are ordinary data — write them literally; nothing substitutes until `resolve` is
+called.** `get`, `list`, `check` and every harness see the template verbatim, which is exactly what
+makes the record mean the same thing on every machine instead of quietly meaning two things. An
+undeclared key and a declared-but-absent one are different errors, and `compile` warns — by name,
+never by value — when a declared var has nothing behind it here.
+
 ## Modular
 
 **Data and skills are the new app structure.** A coding agent with the right skills over the right

package/collections/collections.collection.yaml

@@ -11,6 +11,17 @@ schema:
     description:
       type: string
       description: What kind of thing this collection holds, in one line.
+    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`.
     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`).
@@ -66,6 +77,13 @@ schema:
       type: array
       items: { type: string }
       description: The columns a list view shows by default.
+    sort_field:
+      type: string
+      description: >-
+        Which field carries MANUAL order — the one a drag writes. The field must be declared by this
+        collection's own schema, and holds a fractional index (`dt <collection> move`), never an
+        integer: renumbering is a multi-file commit against git. A surface offers dragging only while
+        it is sorted by this field, because a handle that reorders nothing is a lie.
     icon:
       type: string
       description: material-symbols-outlined icon name, drawn in the nav and page header. The VS Code tree maps it to the nearest codicon — an unmapped name falls back to a generic cylinder, so pick one that is already mapped or add the row.

package/collections/repos.collection.yaml

@@ -1,4 +1,7 @@
 name: repos
+description: >-
+  A git repository this workspace knows about — where it lives and how a working tree is
+  materialized on demand.
 # 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,7 +1,7 @@
 {
 	"name": "dreamteamer",
-	"version": "0.9.1",
-	"description": "A workspace compiler for coding agents \u2014 schema-validated records as plain files over git, compiled into every harness",
+	"version": "0.12.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>",
 	"homepage": "https://github.com/dreamteamer/dreamteamer#readme",
@@ -47,6 +47,7 @@
 		"ajv": "^8.17.1",
 		"ajv-formats": "^3.0.1",
 		"express": "^5.2.1",
+		"fractional-indexing": "^4.0.0",
 		"js-yaml": "^4.1.0"
 	},
 	"dreamteamer": {

package/skills/building-dreamteamer/SKILL.md

@@ -37,7 +37,7 @@ Three tie-breakers worth internalising, because they are the ones that go wrong:
 - **a multi-step process is a CHAIN OF COMMANDS, not an entity.** There is no workflow kind: a
   `workflows` collection with run records, triggers and an executor existed until 2026-07-31 and was
   removed after three days of measurement showed the work being done by a command chain instead. Write
-  one command per step, bind each to its collection so `dt commands for <ref>` shows what applies, and
+  one command per step, bind each to its collection so `dt commands <ref>` shows what applies, and
   a command whose body invokes the others in order if the sequence needs a name. The record's own state
   is the progress marker — which is what made the run records redundant.
 
@@ -54,7 +54,7 @@ These were duplicated across seven skills; they are true for all of them.
    makes the id lie.
 3. **The meta-descriptor IS the spec.** Every kind is itself a collection:
    `.dreamteamer/collections/<kind>.collection.yaml` lists every key it may carry with its
-   allowed values. Read that, plus a real one (`dt <kind> get <id>`), instead of learning the shape
+   allowed values. Read that, plus a real one (`dt get <kind>/<id>`), instead of learning the shape
    from prose. Prose drifts; the descriptor cannot.
 4. **`npm run compile`, then `npm run check`.** Compile materializes the runtime and the harness
    adapters; check validates refs and shapes and never modifies files. Neither is optional.
@@ -66,10 +66,10 @@ These were duplicated across seven skills; they are true for all of them.
 7. **Never edit generated output.** `.dreamteamer/`, `.claude/`, `.agents/`, `.cursor/` are all
    overwritten and pruned on the next compile. If you found the thing you want to change in one of
    those, you are in the wrong file.
-8. **The CLI refuses system-stored records on purpose.** `dt skills set …` will not work; edit the
+8. **The CLI refuses system-stored records on purpose.** `dt set skills/<id> …` will not work; edit the
    module source and compile. The exceptions are the meta verbs that write sources *through* a
-   compile gate — `collections add`, `<collection> add-field`, `ui-views add|set` — which exist so
-   an uncompilable source can never land in history.
+   compile gate — `schema add-collection`, `schema add-field <collection>`, `schema add-view|set-view` —
+   which exist so an uncompilable source can never land in history.
 9. **Never duplicate a procedure across records.** A command body that restates a skill, an agent
    body that inlines its skill's steps, a command that re-types another command's prompt — each is two
    copies that drift. Reference the one that owns it.
@@ -99,7 +99,7 @@ a collection about people, meetings, tasks, products, content — belongs in a m
 version of it belongs in the `recipes` repo rather than here.
 
 **The test is: does the ENGINE read it?** Core's collections are the entity kinds the compiler itself
-materializes, plus `repos` (because `repos ensure` clones them). Everything else has been ejected on
+materializes, plus `repos` (because `ensure` clones them). Everything else has been ejected on
 exactly that test — `teams` (nothing resolved a
 team), `mounts` (a one-implementation adapter enum over an `.env` key), `module-registries` (zero
 readers), `workflows`/`workflow-runs`/`workflow-triggers`/`cursors` and `migrations`/`migration-runs`

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

@@ -7,12 +7,12 @@ One descriptor file: `modules/<module>/collections/<name>.collection.yaml`. The
 
 | goal | how |
 |---|---|
-| new collection from a template | `dt collections add --name research-docs --template docs` |
-| move one into a namespace | `dt collections rename doctors health/doctors` (or `doctors --namespace health`) |
-| templateless | `dt collections add --name <n>` — emits a minimal compilable schema |
-| add a field | `dt <collection> add-field --name urgent --type boolean --default-value false` |
-| change / drop a field | `dt <collection> update-field …` · `remove-field --name <f>` |
-| delete a collection | `dt collections rm <name>` |
+| new collection from a template | `dt schema add-collection --name research-docs --template docs` |
+| move one into a namespace | `dt schema rename-collection doctors health/doctors` (or `doctors --namespace health`) |
+| templateless | `dt schema add-collection --name <n>` — emits a minimal compilable schema |
+| add a field | `dt schema add-field <collection> --name urgent --type boolean --default-value false` |
+| change / drop a field | `dt schema update-field <collection> …` · `schema remove-field <collection> --name <f>` |
+| delete a collection | `dt schema rm-collection <name>` |
 | what templates exist | `.dreamteamer/collection-templates/` |
 
 `--type` is sugar over JSON Schema: `string`/`text`, `markdown`, `boolean`, `number`, `integer`,
@@ -21,7 +21,7 @@ or a bare collection name for a reference into it. `--required true` widens `req
 
 ⚠ **The meta verbs write the WORKSPACE module only.** To change a field on a collection another
 module owns, either edit that module's descriptor by hand or add an `extends:` overlay.
-**`dt collections rename <old> <new>`** moves the descriptor, the records, the record filenames and
+**`dt schema rename-collection <old> <new>`** moves the descriptor, the records, the record filenames and
 every inbound reference in ONE commit — including `x-reference` targets in other descriptors and any
 ui-view pointing at it. `<old> --namespace <ns>` is sugar for moving it into a namespace under the same
 bare name. It refuses a compiled source, a module-owned collection, a taken name, and an undeclared
@@ -35,7 +35,7 @@ A collection name may carry a slash-delimited namespace, and it becomes real dir
 
 | declare in the workspace `package.json` | create it | lands in | referenced as |
 |---|---|---|---|
-| `"namespaces": ["health"]` | `dt collections add --namespace health --name doctors` | `data/health/doctors/` | `health/doctors/dana-levi` |
+| `"namespaces": ["health"]` | `dt schema add-collection --namespace health --name doctors` | `data/health/doctors/` | `health/doctors/dana-levi` |
 
 - **The default namespace is the empty prefix.** `tasks` stays `data/tasks/` and `tasks/kickoff`, so
   common entities need no prefix and adopting namespaces migrates nothing. `default` is RESERVED —
@@ -93,7 +93,7 @@ templates: [collection-templates/provenance]   # merged at compile, every time
   reference already inherits its TARGET collection's `title_template`; author it there instead, once,
   rather than on every field pointing at it.
 - **Do not enum a field after the fact.** Enumerating a vocabulary the records already violate makes
-  `check` fail on every pre-existing value. `dt <collection> values <field>` derives the real
+  `check` fail on every pre-existing value. `dt values <collection> <field>` derives the real
   vocabulary from the data — a filter dropdown gets it for free without locking the set.
 - **`icon` / `group`** are the studio nav's material-symbol icon and folder; ungrouped collections
   list at the top. `list_fields` is the SEED a module ships, not a competing source of truth — a

package/skills/building-dreamteamer/references/commands.md

@@ -13,7 +13,7 @@ description: triage every open task assigned to me, one at a time
 argument-hint: "[assignee]"
 ---
 load this workspace's tasks skill. list my open tasks
-(`npm run --silent dt -- tasks list --status todo`), then walk them one at a
+(`npm run --silent dt -- list tasks --status todo`), then walk them one at a
 time: restate it, ask me to keep / reassign / drop, apply the decision with `tasks set`.
 done when the list is empty or I say stop.
 ```
@@ -55,7 +55,7 @@ description: audio present, no transcript yet
 - **Pick the signal carefully.** "Is it transcribed?" is `transcription._nempty` (the provenance
   object), NOT `transcript._nempty` — a body can be filled by hand with no provenance, which is
   exactly the case worth flagging as not-yet-done.
-- Read the queue with `dt commands for <collection>[/<id>] [--ids a,b] [--json]`.
+- Read the queue with `dt commands <collection>[/<id>] [--ids a,b] [--json]`.
 
 ## common mistakes
 

package/skills/building-dreamteamer/references/ui-views.md

@@ -46,7 +46,7 @@ and silently reverts to a fallback ordering on the next load.
 
 ## the CLI can write these
 
-`dt ui-views add|set|rm` — `set` takes dotted keys (`options.sort=-date`) and derives the record id
+`dt schema add-view|set-view|rm-view` — `set-view` takes dotted keys (`options.sort=-date`) and derives the record id
 with the descriptor's own template, so a view saved from the CLI and one saved from the UI land on
 the **same record**. This is the one system-stored kind with full CLI write support, because it goes
 through the same compile gate.

package/skills/using-dreamteamer/SKILL.md

@@ -45,7 +45,7 @@ demand:
 
 `npm run --silent dt -- help` is the command surface — don't learn the generic verbs and flags from
 prose; prose drifts. it does **not** list the purpose-built verbs some collections have
-(`collections add`, `<collection> add-field`, `repos ensure`) — those live in the skill that owns
+(`schema add-collection`, `schema add-field <collection>`, `ensure`) — those live in the skill that owns
 them, and a verb absent from `help` still works.
 
 what you need to know *about* the CLI: collection verbs validate hard (invalid writes, **including
@@ -85,10 +85,37 @@ and deliberately nothing else — including nothing about people. There is no `u
 - workspace-level rules live in `CLAUDE.md`, and a workspace's decision log (where one exists) wins
   over older documents.
 - **session greeting** — surface the operator's inbox from whatever collection this workspace uses for
-  work, e.g. `npm run --silent dt -- tasks list --status todo`. ⚠ **there is no `users` collection and
+  work, e.g. `npm run --silent dt -- list tasks --status todo`. ⚠ **there is no `users` collection and
   no `@me`** (both removed in 0.8.0); read the operator from `git config user.name` at the point you
   need one, and never filter on a person unless this workspace owns a collection of them.
 
+## machine-specific references
+
+a path that exists on only one machine — a synced folder, an external disk — is written as a
+**template**, never as an absolute path:
+
+```yaml
+source_file: ${env:FILES_FOLDER}/2026/q3.pdf
+```
+
+| variable | renders to |
+|---|---|
+| `${env:NAME}` | `NAME`'s value in the workspace's `.env` — and only if `NAME` is listed in `dreamteamer.vars` in `package.json` |
+| `${workspaceFolder}` | the workspace root, absolute |
+| `${userHome}` | the current user's home directory |
+
+- **declare the key before using it**: `"dreamteamer": { "vars": ["FILES_FOLDER"] }`. an undeclared
+  key and a declared-but-absent one are deliberately different errors — the first is a typo, the
+  second is a machine nobody has set up. `npm run compile` warns per declared var with no value in
+  `.env`, naming keys only.
+- **render with `dt resolve`, the only substitution point**: `dt resolve '${env:FILES_FOLDER}/x'`, or
+  `dt resolve <collection>/<id> <field>` to render what a record already holds (an array field prints
+  one item per line). an argument containing `${` is always a template, so a ref-shaped one is never
+  split as a reference.
+- ⚠ **templates are ordinary data — write them literally; nothing substitutes until resolve is
+  called.** `dt get`, `list`, `check` and every harness read the template verbatim. an un-namespaced
+  `${VAR}` is inert, so prose may mention `${…}` freely.
+
 ## common mistakes
 
 | mistake | why it bites |
@@ -99,3 +126,4 @@ and deliberately nothing else — including nothing about people. There is no `u
 | bare refs (`ada`, `data/contacts/x.contact.md`) | refs are `<collection>/<id>`; anything else fails check |
 | assuming a write was committed | it was not, unless `auto-commit` is on — `dt status` says what is pending |
 | `git add -A` in a shared tree | steals another session's uncommitted work, invisibly |
+| an absolute machine path in a record | it is wrong on every other machine — write `${env:NAME}` and declare the key |

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

@@ -19,8 +19,8 @@ purpose.
 ## the verbs
 
 `npm run --silent dt -- help` lists the generic record verbs and their flags. read them there.
-but **`help` is not the whole surface** — collections with a purpose-built verb (`collections add`,
-`<collection> add-field`, `repos ensure`) don't appear in it, and a verb missing from `help`
+but **`help` is not the whole surface** — collections with a purpose-built verb (`schema add-collection`,
+`schema add-field <collection>`, `ensure`) don't appear in it, and a verb missing from `help`
 is not a verb that doesn't exist. when a skill names a verb, use the verb.
 
 what the help text can't tell you either way:
@@ -30,7 +30,7 @@ what the help text can't tell you either way:
   got) or an id that misses `id.pattern`. a rejected write leaves no partial state.
 - **every write verb commits by itself**, with the right subject — never stack another commit
   on top.
-- `set <id> <field>=` with an empty value **removes** the field; array fields take a
+- `set <collection>/<id> <field>=` with an empty value **removes** the field; array fields take a
   comma-separated value (`--attendees contacts/a,contacts/b`).
 - `--json` works on every verb — use it whenever you're going to parse the output.
 - `npm run check` validates the whole workspace after the fact: report-only, never rewrites.
@@ -45,10 +45,10 @@ to label one of its records) — both resolved by compile from the id unless aut
 
 ## writing a record by hand
 
-**default to `dt <collection> add`** — id, defaults, validation and commit in one line. hand-write
+**default to `dt add <collection>`** — id, defaults, validation and commit in one line. hand-write
 only when the CLI can't express the value: a nested map, or a long structured body.
 
-when you do, don't reconstruct the shape from the schema — **`dt <collection> get <existing-id>
+when you do, don't reconstruct the shape from the schema — **`dt get <collection>/<existing-id>
 --json` prints the exact shape a valid record has**: which fields, which ref forms, dates as
 strings. copy a sibling, change what differs, and:
 
@@ -81,8 +81,8 @@ A collection may be scoped under a namespace declared in the workspace `package.
 QUALIFIED name is the collection's name everywhere:
 
 ```bash
-dt health/doctors add --name "Dana Levi"     # → data/health/doctors/dana-levi.doctor.md
-dt health/visits add --name Checkup --date 2026-03-04 --doctor health/doctors/dana-levi
+dt add health/doctors --name "Dana Levi"     # → data/health/doctors/dana-levi.doctor.md
+dt add health/visits --name Checkup --date 2026-03-04 --doctor health/doctors/dana-levi
 ```
 
 - a reference is still `<collection>/<id>` — `health/doctors/dana-levi` is the collection