dreamteamer 0.10.0 → 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

@@ -77,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.10.0",
-	"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

package/src/cli.js

@@ -1,5 +1,14 @@
-// dreamteamer CLI — noun-verb grammar over the same primitives every surface uses.
-// this phase ships: compile, check, status. collection verbs land next.
+// dreamteamer CLI — VERB-FIRST: `dt <verb> [<target>]`, over the same primitives every surface uses.
+//
+// The verb set is CLOSED. `run()` switches on it and anything unrecognised is an error, because the
+// predecessor grammar (`dt <collection> <verb>`) made the FALLBACK the collection path: a typo
+// dispatched to a collection lookup and answered "unknown collection", which is a true sentence
+// about the wrong thing. It also meant no verb could ever be named without a noun in front of it
+// — `dt resolve '<string>'` had nowhere to live — and a namespaced reference had to be typed as two
+// arguments that only the caller knew belonged together.
+//
+// This file TRANSLATES; it does not implement. Every record and schema verb lands on
+// `collectionCommand(ws, collection, verb, args)`, whose signature is unchanged.
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
@@ -11,6 +20,8 @@ import { init, install, installClone, update, listRepos } from './init.js';
 import { deriveEvents } from './events.js';
 import { commitPending } from './commit.js';
 import { Store } from './store.js';
+import { splitRef } from './ref.js';
+import { parseEnvValues, renderTemplate } from './env-vars.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -18,9 +29,64 @@ import { Store } from './store.js';
 const QUIET = ['ignore', 'pipe', 'ignore'];
 
 
-const USAGE = `usage: dreamteamer <command> | dreamteamer <collection> <verb> …
+const USAGE = `usage: dreamteamer <verb> [<target>] [flags]
 
-commands:
+record verbs (hard validation — invalid writes are rejected before disk).
+A <target> is either a collection name or a <collection>/<id> reference; the reference splits at
+the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee is ONE argument:
+  list   <collection> [--filter k=v] [--where <json>] [--sort [-]<field>] [--json]
+                                              (--where takes the studio's operator set, e.g.
+                                               '{"starts":{"_gte":"2026-07-01"}}'; date-times
+                                               sort and compare as instants, across offsets)
+  get    <collection>/<id> [--json]
+  add    <collection> --<field> <value> … [--id <explicit-id>]
+  set    <collection>/<id> <field>=<value> …
+  rm     <collection>/<id> [--force]
+  rename <collection>/<id> <new-id>           (rewrites all inbound refs, ONE commit)
+  move   <collection>/<id> --after|--before <id> | --top | --bottom
+  move   <collection> --init                  (place every record that has no sort value yet)
+  values <collection> <field> [--limit n]     (the vocabulary a field actually uses —
+                                               what a filter/validator offers as choices)
+  history <collection>/<id> [--json]          (git revisions of this record, newest first)
+  diff    <collection>/<id> [--hash <sha>]    (the patch one revision applied; defaults to HEAD)
+  revert  <collection>/<id> --hash <sha>      (restore the content at <sha>, as a NEW commit)
+  commands <collection>[/<id>] [--ids <id>,…] (bound commands + per-record state:
+                                               available / done / not-applicable)
+  ensure  <repos-id> | --all [--json]         (materialize an attached repo's working tree ON
+                                               DEMAND — never at install; --all is the explicit
+                                               opt-in, e.g. before going offline)
+  resolve '<string>' | <collection>/<id> <field>
+                                              (render \${env:NAME} · \${workspaceFolder} ·
+                                               \${userHome} — the ONLY substitution point; a
+                                               record keeps the template verbatim. An array
+                                               field prints one item per line)
+
+schema verbs (write SOURCES through a compile gate, never the runtime — a different act, so a
+different word in front of it):
+  schema add-collection --name <name> [--namespace <ns>] [--template docs|entity]
+                            (--namespace health --name doctors === --name health/doctors; the
+                             namespace must already be declared in dreamteamer.namespaces, and
+                             records land in data/<ns>/<name>/)
+  schema rm-collection <name> [--force]       (--force required if it still has records)
+  schema rename-collection <old> <new>        (or <old> --namespace <ns> to move it into one)
+                            moves the descriptor AND the records, re-suffixes files when the
+                            suffix was derived, rewrites every inbound reference, ONE commit
+  schema add-field    <collection> --name <field> --type <type> [--options a,b] [--default-value v]
+                            [--required true] [--description "what this field means"]
+                            types: string text markdown boolean number integer date datetime
+                                   enum tags <collection> — a date-time may be written as
+                                   "2026-07-28 12:00" or "2026-07-28T12:00"; the local offset is
+                                   stamped on for you (2026-07-28T12:00:00+03:00)
+  schema update-field <collection> --name <field> --type <type> [--options a,b] [--default-value v]
+                            [--required true|false] [--description "…"]
+                            (an existing description survives a retype)
+  schema remove-field <collection> --name <field>
+  schema add-view --path </route> --target list --collection collections/<c> --layout <id>
+                            [--id <id>] [k.v=…]
+  schema set-view <id> <key>=<value> …        (dotted keys: options.sort=-date, nav.label=Recent)
+  schema rm-view <id>
+
+workspace verbs:
   init        write the workspace skeleton into the current directory (never compiles)
   --version   print the engine version (works anywhere)
   install     restore git_modules/ from the lockfile map; --clone <url> [name] adds one
@@ -35,51 +101,30 @@ commands:
   commit      publish records already written to disk: samples git status over every
               collection's record dirs, one commit PER REPO, subject composed from the
               status letters. [<collection> …] to scope, [-m <subject>], [--dry-run]
+  help        this text
+`;
 
-collection verbs (hard validation — invalid writes are rejected before disk):
-  <collection> list [--filter k=v] [--where <json>] [--sort [-]<field>] [--json]
-                                              (--where takes the studio's operator set, e.g.
-                                               '{"starts":{"_gte":"2026-07-01"}}'; date-times
-                                               sort and compare as instants, across offsets)
-  <collection> get <id> [--json]
-  <collection> add --<field> <value> … [--id <explicit-id>]
-  <collection> set <id> <field>=<value> …
-  <collection> rm <id> [--force]
-  <collection> rename <old-id> <new-id>       (rewrites all inbound refs, ONE commit)
-  <collection> history <id> [--json]          (git revisions of this record, newest first)
-  <collection> diff <id> [--hash <sha>]       (the patch one revision applied; defaults to HEAD)
-  <collection> revert <id> --hash <sha>       (restore the content at <sha>, as a NEW commit)
+// Record verbs, split by what their <target> means. `move` and `commands` are in NEITHER set: both
+// accept either shape, and which one it is has to be decided against the declared collections.
+const REF_VERBS = new Set(['get', 'set', 'rm', 'rename', 'history', 'diff', 'revert']);
+const COLLECTION_VERBS = new Set(['list', 'add', 'values']);
+const EITHER_VERBS = new Set(['move', 'commands']);
 
-repo attachment (working trees are materialized ON DEMAND, never at install):
-  repos ensure <id> [--json]                  (clone if missing, then print the path; idempotent)
-  repos ensure --all [--json]                 (explicit opt-in: everything, e.g. before going offline)
-
-meta verbs (schema operations — write SOURCES through a compile gate, never the runtime):
-  collections add --name <name> [--namespace <ns>] [--template docs|entity]
-                            (--namespace health --name doctors === --name health/doctors; the
-                             namespace must already be declared in dreamteamer.namespaces, and
-                             records land in data/<ns>/<name>/)
-  collections rm <name> [--force]             (--force required if it still has records)
-  collections rename <old> <new>              (or <old> --namespace <ns> to move it into one)
-                            moves the descriptor AND the records, re-suffixes files when the
-                            suffix was derived, rewrites every inbound reference, ONE commit
-  <collection> add-field    --name <field> --type <type> [--options a,b] [--default-value v] [--required true]
-                            [--description "what this field means"]
-                            types: string text markdown boolean number integer date datetime
-                                   enum tags <collection> — a date-time may be written as
-                                   "2026-07-28 12:00" or "2026-07-28T12:00"; the local offset is
-                                   stamped on for you (2026-07-28T12:00:00+03:00)
-  <collection> update-field --name <field> --type <type> [--options a,b] [--default-value v] [--required true|false]
-                            [--description "…"]   (an existing description survives a retype)
-  <collection> remove-field --name <field>
-  ui-views add --path </route> --target list --collection collections/<c> --layout <id> [--id <id>] [k.v=…]
-  ui-views set <id> <key>=<value> …           (dotted keys: options.sort=-date, nav.label=Recent)
-  ui-views rm <id>
-  commands for <collection>[/<id>] [--ids <id>,…]      (bound commands + per-record state:
-                                                        available / done / not-applicable)
-  <collection> values <field> [--limit n]              (the vocabulary a field actually uses —
-                                                        what a filter/validator offers as choices)
-`;
+// `schema <op>` → the (collection, verb) pair the implementation layer already answers to. The
+// collections are literals: `collections` and `ui-views` are SYSTEM-stored, which is precisely what
+// makes these a separate group in the grammar rather than records like any other.
+const SCHEMA_OPS = {
+	'add-collection': ['collections', 'add'],
+	'rm-collection': ['collections', 'rm'],
+	'rename-collection': ['collections', 'rename'],
+	'add-view': ['ui-views', 'add'],
+	'set-view': ['ui-views', 'set'],
+	'rm-view': ['ui-views', 'rm'],
+};
+// These three name their collection POSITIONALLY (`schema add-field contacts --name phone`) and keep
+// their existing verb spelling on it — the schema group is a prefix here, not a rename.
+const SCHEMA_FIELD_OPS = new Set(['add-field', 'update-field', 'remove-field']);
+const SCHEMA_OP_LIST = [...Object.keys(SCHEMA_OPS), ...SCHEMA_FIELD_OPS].join(' | ');
 
 export function run(argv) {
 	const [cmd, ...rest] = argv;
@@ -96,6 +141,10 @@ export function run(argv) {
 			for (let i = 0; i < rest.length; i++) if (rest[i].startsWith('--')) flags[rest[i].slice(2)] = rest[i + 1];
 			process.exit(init({ flags }));
 		}
+		if (!cmd) {
+			console.log(USAGE);
+			process.exit(0);
+		}
 		const ws = findWorkspace();
 		switch (cmd) {
 			case 'install': {
@@ -202,7 +251,7 @@ export function run(argv) {
 					if (repos.length) {
 						const here = repos.filter((r) => r.present).length;
 						console.log(`repos:    ${here}/${repos.length} materialized`);
-						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path} (dreamteamer repos ensure ${r.id})`);
+						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path} (dreamteamer ensure ${r.id})`);
 					}
 				} catch { /* no repos descriptor compiled — nothing to report */ }
 				// Uncommitted records are invisible to `dt changes` (it diffs commits), so the
@@ -226,14 +275,25 @@ export function run(argv) {
 			case 'help':
 				console.log(USAGE);
 				process.exit(0);
-			default: {
-				if (!cmd || rest.length === 0) {
-					console.log(USAGE);
-					process.exit(cmd ? 1 : 0);
-				}
+			case 'list': case 'add': case 'values':
+			case 'get': case 'set': case 'rm': case 'rename': case 'history': case 'diff': case 'revert':
+			case 'move': case 'commands':
 				warnIfStale(ws.root);
-				process.exit(collectionCommand(ws, cmd, rest[0], rest.slice(1)));
-			}
+				process.exit(dispatchRecordVerb(ws, cmd, rest));
+			// `repos ensure` lost its noun: the repos collection is still where the declaration lives,
+			// but materializing one is a verb the operator types, not a record write.
+			case 'ensure':
+				warnIfStale(ws.root);
+				process.exit(collectionCommand(ws, 'repos', 'ensure', rest));
+			case 'schema':
+				warnIfStale(ws.root);
+				process.exit(dispatchSchemaVerb(ws, rest));
+			case 'resolve':
+				process.exit(resolveVariables(ws, rest));
+			default:
+				console.error(`✖ unknown verb "${cmd}" — dreamteamer is verb-first since 0.12.0: dt <verb> [<target>]`);
+				console.error(USAGE);
+				process.exit(1);
 		}
 	} catch (e) {
 		console.error(`✖ ${e.message}`);
@@ -241,6 +301,110 @@ export function run(argv) {
 	}
 }
 
+/** Translate `dt <verb> <target> …` into the noun-verb call the implementation layer takes. */
+function dispatchRecordVerb(ws, verb, args) {
+	const [target, ...rest] = args;
+	if (!target) throw new Error(`dt ${verb} needs a target — see \`dreamteamer help\``);
+	// A flag in the target slot is a word-order mistake, not a collection: without this,
+	// `dt list --json contacts` reported `unknown collection "--json"` and dumped every name.
+	if (target.startsWith('--')) throw new Error(`dt ${verb} takes its target BEFORE the flags: dreamteamer ${verb} <target> ${target} …`);
+	if (COLLECTION_VERBS.has(verb)) return collectionCommand(ws, target, verb, rest);
+	if (REF_VERBS.has(verb)) {
+		const { collection, id } = splitRef(new Store(ws).descriptors, target);
+		return collectionCommand(ws, collection, verb, [id, ...rest]);
+	}
+	// EITHER_VERBS from here: a bare collection is legal for both — `move <collection> --init`,
+	// `commands <collection>`.
+	const { descriptors } = new Store(ws);
+	if (descriptors.has(target)) {
+		return verb === 'move'
+			? collectionCommand(ws, target, 'move', rest)
+			: collectionCommand(ws, 'commands', 'for', [target, ...rest]);
+	}
+	const { collection, id } = splitRef(descriptors, target);
+	if (verb === 'move') return collectionCommand(ws, collection, 'move', [id, ...rest]);
+	// `commands for <c>/<id>` split its own target at the FIRST slash, which cannot name a
+	// namespaced collection. splitRef can, so the id is handed over as `--ids` — the same
+	// `commandsFor(store, collection, ids)` call, reached without re-encoding the reference.
+	// Ours goes FIRST so an explicit `--ids` from the caller still wins (last flag parsed wins).
+	return collectionCommand(ws, 'commands', 'for', [collection, '--ids', id, ...rest]);
+}
+
+/**
+ * `dt resolve '<string>'` | `dt resolve <collection>/<id> <field>` — the ONLY place a `${env:…}`
+ * template becomes a value. Records hold the template verbatim; no read path substitutes anything,
+ * so a reference means the same thing on every machine and the file says which is which.
+ *
+ * THE HEURISTIC: the first argument is a REFERENCE iff it contains no `${` AND splits against a
+ * declared collection. Both halves are needed. `${` first, because `docs/${env:X}` is ref-SHAPED
+ * and must not be split as one — a reference can never contain a template, so the marker decides it
+ * outright. Then the split, because a plain path (`/tmp/x`, `nope/q3`) must render to itself rather
+ * than report an unknown collection it was never naming. Two accepted consequences: a bare
+ * collection name resolves to itself (splitRef refuses it, so it is "just a string"), and in an
+ * UNCOMPILED workspace every argument is a string, because there are no descriptors to split
+ * against — which keeps `dt resolve '${env:K}'` working before the first compile.
+ */
+function resolveVariables(ws, args) {
+	const [target, field] = args;
+	if (!target) throw new Error("dt resolve takes a string template or a <collection>/<id> and a field: dreamteamer resolve '${env:FILES_FOLDER}/x'");
+	// resolve has no flags, so a flag-shaped target is a mistake — and the one that costs is
+	// `dt resolve --help`, which would otherwise print `--help` back and exit 0.
+	if (target.startsWith('--')) throw new Error(`dt resolve takes a string or a <collection>/<id>, not a flag ("${target}") — see \`dreamteamer help\``);
+	const declared = ws.pkg.dreamteamer?.vars ?? [];
+	const envFile = path.join(ws.root, '.env');
+	const env = parseEnvValues(fs.existsSync(envFile) ? fs.readFileSync(envFile, 'utf8') : '');
+	const ctx = { env, workspaceFolder: ws.root, declared };
+
+	let ref = null;
+	let store = null;
+	if (!target.includes('${')) {
+		try {
+			store = new Store(ws);
+			ref = splitRef(store.descriptors, target);
+		} catch { ref = null; }
+	}
+	// An argument nobody reads is a silent wrong answer: `dt resolve docs/q3 source_file garbage`
+	// exited 0 on the field it happened to recognise.
+	const takes = ref ? 2 : 1;
+	if (args.length > takes) {
+		throw new Error(`dt resolve takes ${takes === 1 ? 'one string template' : 'a reference and ONE field'} — ${args.length - takes} extra argument(s): ${args.slice(takes).join(' ')}`);
+	}
+	if (!ref) {
+		console.log(renderTemplate(target, ctx));
+		return 0;
+	}
+	if (!field) throw new Error(`dt resolve ${target} needs a field name: dreamteamer resolve ${target} <field>`);
+	const { fields } = store.read(ref.collection, ref.id);
+	const value = fields[field];
+	if (value === undefined) throw new Error(`${target} has no field "${field}"`);
+	// RENDER EVERY ITEM BEFORE PRINTING ANY. An array prints one item per line so the output pipes
+	// into a shell loop unchanged — and a loop that does not check $? cannot tell a truncated list
+	// from a short one, so a failure on item n must not leave items 1..n-1 on stdout. Anything that
+	// is not text is refused rather than stringified: a number cannot hold a template.
+	const items = Array.isArray(value) ? value : [value];
+	const bad = items.findIndex((v) => typeof v !== 'string'); // index, not the value: an item may be null
+	if (bad > -1) throw new Error(`${target} field "${field}" holds a ${typeof items[bad]} — resolve renders text (a string, or a list of them)`);
+	const rendered = items.map((v) => renderTemplate(v, ctx));
+	if (rendered.length) console.log(rendered.join('\n'));
+	return 0;
+}
+
+/** Translate `dt schema <op> …` onto the same meta verbs `collectionCommand` already routes. */
+function dispatchSchemaVerb(ws, args) {
+	const [op, ...rest] = args;
+	if (!op) throw new Error(`dt schema needs an operation — use ${SCHEMA_OP_LIST}`);
+	if (SCHEMA_FIELD_OPS.has(op)) {
+		const [collection, ...flags] = rest;
+		if (!collection || collection.startsWith('--')) {
+			throw new Error(`dt schema ${op} needs a collection: dreamteamer schema ${op} <collection> --name <field> …`);
+		}
+		return collectionCommand(ws, collection, op, flags);
+	}
+	const pair = SCHEMA_OPS[op];
+	if (!pair) throw new Error(`unknown schema operation "${op}" — use ${SCHEMA_OP_LIST}`);
+	return collectionCommand(ws, pair[0], pair[1], rest);
+}
+
 function tryGit(cwd, args) {
 	try { return execFileSync('git', args, { cwd, stdio: QUIET }).toString().trim() || null; } catch { return null; }
 }

package/src/collections-cli.js

@@ -1,6 +1,7 @@
-// noun-verb collection commands: dreamteamer <collection> list|get|add|set|rm|rename|history|diff|revert
-// + meta verbs: `collections add|rm`, `<collection> add-field|update-field|remove-field`,
-//   `ui-views add|set|rm`
+// The IMPLEMENTATION layer behind the verb-first CLI: `collectionCommand(ws, collection, verb, args)`
+// is (collection, verb) shaped and stays that way — `cli.js` translates `dt <verb> <target>` onto it.
+// So a spelling here (`collections add`, `<collection> add-field`, `commands for`, `repos ensure`) is
+// an INTERNAL pair, not what the operator types; `dt schema add-collection` is what they type.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -19,6 +20,7 @@ import { distinctValues } from './field-values.js';
 import { matchesFilter } from './filter.js';
 import { baseNameOf, normalizeNamespaces } from './namespace.js';
 import { sortRows } from './temporal.js';
+import { keyBetween, placementKey } from './fractional-index.js';
 import { ensureRepo, ensureAllRepos } from './init.js';
 
 /**
@@ -26,7 +28,7 @@ import { ensureRepo, ensureAllRepos } from './init.js';
  *
  * `console.log` to a pipe is asynchronous, and every CLI path ends in `process.exit()`, which
  * discards whatever is still buffered. A shell pipeline hides the bug completely — the reader
- * drains concurrently, so `dreamteamer contacts list --json | wc -c` reports all 32381 bytes — but
+ * drains concurrently, so `dreamteamer list contacts --json | wc -c` reports all 32381 bytes — but
  * the way a script or a coding agent actually calls this is execFileSync/spawnSync, and there the
  * child exits with the pipe still full. Measured before this fix: the same command captured with
  * execFileSync returned exactly **8190 bytes** (one pipe buffer) of that 32381-byte document, i.e.
@@ -133,6 +135,40 @@ export function collectionCommand(ws, collection, verb, args) {
 			flags.json ? emit(JSON.stringify({ id })) : console.log('✔ updated');
 			return 0;
 		}
+		// Manual ordering. ONE record is written per move — that is the entire feature; a dense
+		// integer would renumber everything below the insertion point and bury the change. The field is
+		// named by the descriptor (`sort_field`), never here, so a workspace may call it anything.
+		case 'move': {
+			const field = d.sort_field;
+			if (!field) throw new Error(`collection "${collection}" declares no sort_field — add one to its descriptor before ordering it by hand.`);
+
+			// Blanks sort FIRST (compareValues, via `?? ''`), so unplaced records surface at the top
+			// rather than hiding at the bottom, and ties fall back to id order: `walk` reads name-sorted
+			// and Array.sort is stable. That is the tiebreak two agents landing on the same key rely on.
+			const rows = [];
+			for (const { id: rid, fields } of store.readAll(collection)) rows.push({ id: rid, key: fields[field] ?? '' });
+			sortRows(rows, 'key');
+
+			if (flags.init) {
+				// Idempotent: a record that already carries a key keeps it, so --init can be re-run after
+				// adding records without disturbing an order the operator set by hand.
+				let prev = rows.filter((r) => r.key).pop()?.key ?? null;
+				let written = 0;
+				for (const r of rows) {
+					if (r.key) continue;
+					prev = keyBetween(prev, null);
+					store.set(collection, r.id, { [field]: prev });
+					written++;
+				}
+				flags.json ? emit(JSON.stringify({ placed: written })) : console.log(written ? `✔ placed ${written} record(s) in ${field}` : '✔ nothing to place');
+				return 0;
+			}
+
+			const id = need(pos, 0, 'id');
+			store.set(collection, id, { [field]: placementKey(rows, id, flags, collection) });
+			flags.json ? emit(JSON.stringify({ id })) : console.log('✔ moved');
+			return 0;
+		}
 		case 'rm': {
 			const id = need(pos, 0, 'id');
 			const { inboundIgnored } = store.rm(collection, id, { force: !!flags.force });
@@ -146,7 +182,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			if (out.touched) console.log(`✔ rewrote ${out.rewrites} inbound reference(s) across ${out.touched} file(s)`);
 			return 0;
 		}
-		// `dreamteamer meetings values status` — the vocabulary a field ACTUALLY uses, so a filter
+		// `dreamteamer values meetings status` — the vocabulary a field ACTUALLY uses, so a filter
 		// or a command-binding validator can offer a dropdown for a plain `type: string` field that
 		// no enum describes (operator: "still no dropdown for many things, visibility, status").
 		case 'values': {
@@ -181,7 +217,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			// the hash is REQUIRED and has no default: "revert" with an implied target is how you
 			// destroy the wrong record. `<c> history <id>` is where you get one.
 			const hash = typeof flags.hash === 'string' ? flags.hash : pos[1];
-			if (!hash) throw new Error(`missing --hash <commit> — run \`dreamteamer ${collection} history ${id}\` to pick one`);
+			if (!hash) throw new Error(`missing --hash <commit> — run \`dreamteamer history ${collection}/${id}\` to pick one`);
 			const out = store.revert(collection, id, hash);
 			flags.json ? emit(JSON.stringify(out)) : console.log(out.reverted ? `✔ reverted ${collection}/${id} to ${String(hash).slice(0, 7)}` : `= already identical to ${String(hash).slice(0, 7)} — nothing changed`);
 			return 0;
@@ -193,16 +229,18 @@ export function collectionCommand(ws, collection, verb, args) {
 
 
 
-// `dreamteamer commands for <collection>[/<id>] [--ids <id>[,…]] [--json]` — which bound
-// commands apply, in which state (available / done / not-applicable). THE engine surface
-// behind the studio's Commands tab (engine/UI parity: the verb lands first, the button second).
+// Which bound commands apply, in which state (available / done / not-applicable). THE engine
+// surface behind the studio's Commands tab (engine/UI parity: the verb lands first, the button
+// second).
+//
+// ⚠ The COLLECTION arrives already resolved, and the ids only ever through `--ids`. This used to
+// split its own target at the first slash — which cannot name a namespaced collection, so
+// `commands finance/transactions` asked for a collection called "finance" and every namespaced
+// target failed. `cli.js` owns reference resolution now (splitRef, longest declared prefix) and is
+// the only caller, so a second, weaker splitter here could only ever disagree with it.
 function metaCommandsFor(ws, store, flags, pos) {
-	const target = need(pos, 0, 'collection[/id]');
-	const slash = target.indexOf('/');
-	const collection = slash > 0 ? target.slice(0, slash) : target;
-	const ids = slash > 0
-		? [target.slice(slash + 1)]
-		: typeof flags.ids === 'string' ? flags.ids.split(',').map((s) => s.trim()).filter(Boolean) : [];
+	const collection = need(pos, 0, 'collection');
+	const ids = typeof flags.ids === 'string' ? flags.ids.split(',').map((s) => s.trim()).filter(Boolean) : [];
 	const out = commandsFor(store, collection, ids);
 	if (flags.json) { emit(JSON.stringify(out, null, 2)); return 0; }
 	if (!out.commands.length) { console.log(`(no commands bound to ${collection})`); return 0; }
@@ -241,7 +279,7 @@ function metaCollectionsAdd(ws, store, flags) {
 // migration whose last step (rewriting references) dangles everything when forgotten.
 function metaCollectionsRename(ws, store, flags, pos) {
 	const [oldName, explicitNew] = pos;
-	if (!oldName) throw new Error('usage: collections rename <old-name> <new-name> | <old-name> --namespace <ns>');
+	if (!oldName) throw new Error('usage: dreamteamer schema rename-collection <old> <new> | <old> --namespace <ns>');
 	// `--namespace health` on its own moves the collection INTO that namespace keeping its bare name,
 	// which is the common case and saves retyping it.
 	const newName = explicitNew

package/src/compile.js

@@ -17,6 +17,7 @@ import {
 // call at run time, same pattern as store.js ↔ compile.js.
 import { runHarnessAdapters } from './harnesses.js';
 import { satisfies } from './semver.js';
+import { parseEnvValues } from './env-vars.js';
 import { DERIVED_KINDS, readManifest, runtimeDir } from './runtime.js';
 
 // re-exported, not moved: `readManifest` is in the VS Code extension's hand-maintained engine
@@ -295,21 +296,37 @@ export function compile({ root, pkg }) {
 			declaredEnv.get(k).push(source.name);
 		}
 	}
-	if (declaredEnv.size) {
+	// `dreamteamer.vars` is the WORKSPACE's own declaration (root package.json, not a module's): the
+	// keys a `${env:NAME}` template is allowed to name. Same missing-key question as
+	// `dreamteamer.env`, one .env parse, two warnings — a module needs its key to RUN, a var is
+	// needed the moment someone calls `dt resolve`, and only the workspace can declare one.
+	if (config.vars !== undefined && (!Array.isArray(config.vars) || config.vars.some((v) => typeof v !== 'string'))) {
+		fail(`dreamteamer.vars must be a list of env key names (got ${JSON.stringify(config.vars)})`);
+	}
+	const declaredVars = config.vars ?? [];
+	if (declaredEnv.size || declaredVars.length) {
 		// .env is parsed for KEY names ONLY — values never reach any output or the manifest
 		const envPath = path.join(root, '.env');
 		if (!fs.existsSync(envPath)) {
-			console.warn(`⚠ no .env — modules declare env keys: ${[...declaredEnv.keys()].join(', ')} (see .env.example)`);
+			if (declaredEnv.size) console.warn(`⚠ no .env — modules declare env keys: ${[...declaredEnv.keys()].join(', ')} (see .env.example)`);
+			if (declaredVars.length) console.warn(`⚠ no .env — dreamteamer.vars declares ${declaredVars.join(', ')}, so no \${env:…} template can render here (see .env.example)`);
 		} else {
-			const present = new Set();
-			for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
-				const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
-				if (m) present.add(m[1]);
-			}
+			// ⚠ THE ONE PARSER, not a key regex of our own. This used to hand-roll
+			// `/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/`, which accepted two lines
+			// `parseEnvValues` deliberately drops (`KEY =value`, and an indented key) and scanned a
+			// quoted value's continuation lines for keys. Either disagreement produces the worst
+			// pairing there is: compile says nothing and then `dt resolve` answers "no value in
+			// .env" about a line the operator is looking straight at. Values are read here and
+			// never printed — the warnings below name keys only.
+			const present = new Set(parseEnvValues(fs.readFileSync(envPath, 'utf8')).keys());
 			for (const [k, mods] of declaredEnv) {
 				if (present.has(k)) continue;
 				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k} — missing from .env (see .env.example)`);
 			}
+			for (const k of declaredVars) {
+				if (present.has(k)) continue;
+				console.warn(`⚠ dreamteamer.vars declares ${k} — missing from .env, so \${env:${k}} cannot render on this machine`);
+			}
 		}
 	}
 
@@ -630,6 +647,15 @@ export function compile({ root, pkg }) {
 				fail(`collection "${name}": id.pattern is not a valid regular expression — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
 			}
 		}
+		// `sort_field` names a field of this collection's OWN schema. Without this gate a typo
+		// surfaces as "dragging does nothing" while the drag handle is still offered — a silent lie,
+		// and the ordering it writes would land in a field no reader sorts by.
+		if (merged.sort_field !== undefined) {
+			if (typeof merged.sort_field !== 'string') fail(`collection "${name}": sort_field must be a string (got ${JSON.stringify(merged.sort_field)})`);
+			if (!(merged.schema?.properties ?? {})[merged.sort_field]) {
+				fail(`collection "${name}": sort_field "${merged.sort_field}" is not a field of its schema — declare it, or point sort_field at one that exists (${group.map((g) => g.src.path).join(', ')}).`);
+			}
+		}
 		// ---- the reference contract: every target is owned, depended on, or declared a peer ----
 		// Attribution is unioned across the whole group rather than taken from the base, because the
 		// merge keeps no per-field provenance — an overlay that adds a ref field would otherwise be

package/src/env-vars.js

@@ -0,0 +1,40 @@
+// ${env:KEY} / ${workspaceFolder} / ${userHome} — VS Code's variable grammar, three variables.
+// Values render ONLY on explicit request (dt resolve); records are never auto-substituted.
+// parseEnvValues reads .env TEXT only (never shell-evaluates). A QUOTED value (single or double)
+// may span multiple lines — the closing quote just has to end some later line, not the one it
+// opened on — because `[^"\\]`/`[^']` match newlines in JS regex same as any other character.
+// An UNQUOTED value is line-bound: it runs to end of line, so it can't span lines.
+// Two accepted non-goals, unchanged on purpose: `KEY =value` (space before `=`) doesn't match the
+// key pattern and is silently dropped, no diagnostic; an unquoted value keeps a trailing inline
+// `# comment` as part of its text (quote it to strip one).
+import os from 'node:os';
+
+export function parseEnvValues(text) {
+	const out = new Map();
+	// KEY=value with optional `export `, optional quotes; value is whatever follows on the SAME line
+	const re = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=("(?:[^"\\]|\\.)*"|'[^']*'|[^\n]*)$/gm;
+	let m;
+	while ((m = re.exec(text))) {
+		let v = m[2].trim();
+		if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+		out.set(m[1], v);
+	}
+	return out;
+}
+
+const SUPPORTED = 'supported: ${env:NAME}, ${workspaceFolder}, ${userHome}';
+
+export function renderTemplate(str, { env, workspaceFolder, declared }) {
+	return str.replace(/\$\{([A-Za-z]+)(?::([A-Za-z0-9_]*))?\}/g, (whole, ns, arg) => {
+		if (arg === undefined) {
+			if (ns === 'workspaceFolder') return workspaceFolder;
+			if (ns === 'userHome') return os.homedir();
+			return whole; // un-namespaced ${VAR}: not ours, inert — prose mentions ${…} freely
+		}
+		if (ns !== 'env') throw new Error(`\${${ns}:${arg}} is not a dreamteamer variable — ${SUPPORTED}`);
+		if (!arg) throw new Error(`\${env:} needs a key name — ${SUPPORTED}`);
+		if (!declared.includes(arg)) throw new Error(`\${env:${arg}}: "${arg}" is not declared in dreamteamer.vars (workspace package.json) — declared: ${declared.join(', ') || '(none)'}`);
+		if (!env.has(arg)) throw new Error(`\${env:${arg}} is declared but has no value in .env on this machine`);
+		return env.get(arg);
+	});
+}

package/src/fractional-index.js

@@ -0,0 +1,44 @@
+// Manual ordering keys. Named for the ALGORITHM: the FIELD is named per collection via
+// `sort_field`, and nothing here may assume what it is called.
+//
+// ⚠ THE ALPHABET IS LOAD-BEARING. `compareValues` (temporal.js) ends in `localeCompare`, which is
+// locale-aware, so the library's DEFAULT base-62 keys mis-sort here: prepending three times gives
+// `Zy Zz a0`, and `sortRows` returns `a0 Zy Zz`. Same trap that breaks fractional indexing on
+// Postgres under `en_US.utf8` instead of `C`. a-z is the intersection where three things hold at
+// once — locale order agrees with codepoint order, and no key can parse as a number (the numeric
+// branch of `compareValues` would sort "9" after "10") or as a temporal.
+//
+// test/unit/fractional-index.test.js asserts the base-62 failure directly, so this argument cannot
+// be deleted as noise.
+//
+// Why a dependency rather than 75 lines of our own: the naive midpoint (halve toward the open end)
+// degenerates on APPEND, which is the commonest write — measured at 200-character keys after 1000
+// appends. The library's integer-part-with-magnitude-head keeps that at 4.
+import { generateKeyBetween } from 'fractional-indexing';
+
+const DIGITS = 'abcdefghijklmnopqrstuvwxyz';
+
+/** A key strictly between `a` and `b`. Either may be null for an open end. */
+export const keyBetween = (a, b) => generateKeyBetween(a ?? null, b ?? null, DIGITS);
+
+/**
+ * The key that puts `id` where `dest` asks, given the collection's records in current sort order
+ * (`[{ id, key }]`, blanks first). PURE — the caller does the reading and the writing, which is what
+ * lets the CLI and the HTTP surface share one placement rule instead of two that drift.
+ *
+ * Fails closed on a destination that is not placed yet: with no key on the target there is nothing to
+ * compute against, and guessing would silently put the record somewhere the operator did not ask for.
+ */
+export function placementKey(rows, id, dest, collection = '<collection>') {
+	const placed = rows.filter((r) => r.key && r.id !== id);
+	const at = (t) => {
+		const i = placed.findIndex((r) => r.id === t);
+		if (i < 0) throw new Error(`"${t}" has no sort value yet — run \`dreamteamer move ${collection} --init\` first. nothing was written.`);
+		return i;
+	};
+	if (dest.top) return keyBetween(null, placed[0]?.key ?? null);
+	if (dest.bottom) return keyBetween(placed[placed.length - 1]?.key ?? null, null);
+	if (typeof dest.after === 'string') { const i = at(dest.after); return keyBetween(placed[i].key, placed[i + 1]?.key ?? null); }
+	if (typeof dest.before === 'string') { const i = at(dest.before); return keyBetween(placed[i - 1]?.key ?? null, placed[i].key); }
+	throw new Error('say where to put it — --after <id>, --before <id>, --top or --bottom. nothing was written.');
+}

package/src/harnesses.js

@@ -189,7 +189,7 @@ function collectionsSection(index, namespaces) {
 		'COLLECTIONS — the nouns of this workspace. 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 <collection> add`: it generates the id and rejects invalid writes before disk.',
+		'with `dt add <collection>`: it generates the id and rejects invalid writes before disk.',
 	];
 	const data = index.filter((c) => !c.system);
 	for (const group of ['', ...namespaces]) {
@@ -273,7 +273,7 @@ function bindingsSection(entries) {
 		byCollection.get(coll).push(`/${cmd}${gate ? ` (${gate})` : ''}`);
 	}
 	if (!byCollection.size) return [];
-	const lines = ['', 'VERBS BOUND TO COLLECTIONS (`dt commands for <collection>[/<id>]` answers per record):'];
+	const lines = ['', 'VERBS BOUND TO COLLECTIONS (`dt commands <collection>[/<id>]` answers per record):'];
 	for (const coll of [...byCollection.keys()].sort()) lines.push(`- ${coll} — ${byCollection.get(coll).sort().join(' · ')}`);
 	return lines;
 }

package/src/presentation.js

@@ -60,6 +60,11 @@ function collectionRow(d) {
 	if (typeof d.order === 'number') meta.order = d.order;
 	if (Array.isArray(d.list_fields)) meta.list_fields = d.list_fields;
 	if (typeof d.icon === 'string') meta.icon = d.icon;
+	// Manual ordering: a surface can only offer a drag handle if it knows WHICH field a drop writes,
+	// and the field name is per-collection. Without this the descriptor key exists and no UI can see
+	// it — the extension reads the presentation contract, not raw descriptors.
+	if (typeof d.sort_field === 'string') meta.sort_field = d.sort_field;
+
 	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

package/src/ref.js

@@ -0,0 +1,13 @@
+// split "<collection>/<id>" against the DECLARED collections — longest prefix at a "/" boundary,
+// because both collection names and ids may contain slashes (namespaces; path-shaped ids).
+export function splitRef(descriptors, ref) {
+	let best = null;
+	for (const name of descriptors.keys()) {
+		if (ref === name || ref.startsWith(name + '/')) {
+			if (!best || name.length > best.length) best = name;
+		}
+	}
+	if (!best) throw new Error(`unknown collection in reference "${ref}" (known: ${[...descriptors.keys()].sort().join(', ')})`);
+	if (ref === best) throw new Error(`reference "${ref}" names a collection but no record id`);
+	return { collection: best, id: ref.slice(best.length + 1) };
+}

package/src/runtime.js

@@ -27,7 +27,7 @@ export const DERIVED_KINDS = ['modules'];
 
 /**
  * Where a human edits a compiled collection, as one sentence. ONE definition, because there are two
- * consumers who must never drift: the store's refusal (`dt modules set …`) and the presentation
+ * consumers who must never drift: the store's refusal (`dt set modules/<id> …`) and the presentation
  * projection the UI reads to explain a disabled button. This repo's own history is the argument —
  * `git log`/`git diff` and the `?sort=` comparator were each hand-copied into the extension and
  * went wrong in both places.

package/src/server.js

@@ -12,6 +12,7 @@ import { createCollection, removeCollection, addField, updateField, removeField,
 import { history, historyDiff } from './history.js';
 import { matchesFilter } from './filter.js';
 import { sortRows } from './temporal.js';
+import { placementKey } from './fractional-index.js';
 import { commandsFor, recordResolver } from './record-commands.js';
 import { distinctValues } from './field-values.js';
 
@@ -131,6 +132,33 @@ export function startServer(ws, { port = 8080, host = '127.0.0.1' } = {}) {
 		res.json({ id: idParam(req) });
 	});
 
+	// Manual ordering. NOT Directus's `PATCH /utils/sort/:collection` (decision #16: nothing
+	// Directus-flavored lives here).
+	//
+	// ⚠ THE VERB COMES BEFORE THE WILDCARD, and it must. `…/records/*id` is greedy because ids are
+	// PATHS, so `…/records/charlie/position` reads as the record `charlie/position` and the ordinary
+	// record PATCH answers first — measured, as a 404 from a route that looked correct. Same reasoning
+	// as the `*name` note above: one greedy wildcard, and it goes last.
+	//
+	// Key generation stays in the ENGINE, next to the comparator it has to agree with. A client that
+	// computed keys itself would carry the a-z alphabet rule in a second repo, and the failure when
+	// those drift is silent mis-ordering, not an error.
+	api.patch('/collections/:name/position/*id', (req, res) => {
+		const d = store.descriptor(req.params.name);
+		const field = d.sort_field;
+		if (!field) return res.status(400).json({ error: `collection "${d.name}" declares no sort_field` });
+		const rows = [];
+		for (const { id, fields } of store.readAll(d.name)) rows.push({ id, key: fields[field] ?? '' });
+		sortRows(rows, 'key');
+		const id = idParam(req);
+		try {
+			store.set(d.name, id, { [field]: placementKey(rows, id, req.body ?? {}, d.name) });
+			res.json({ id });
+		} catch (e) {
+			res.status(400).json({ error: e.message });
+		}
+	});
+
 	api.delete('/collections/:name/records/*id', (req, res) => {
 		store.rm(req.params.name, idParam(req), { force: req.query.force === 'true' });
 		res.json({ id: idParam(req) });