dreamteamer 0.16.0 → 0.17.0

package/collections/collections.collection.yaml

@@ -105,6 +105,16 @@ schema:
     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.
+    unresolved_peers:
+      type: array
+      items: { type: string }
+      description: >-
+        DERIVED by compile, never authored — the collections THIS one references that its module
+        declared as a `peerDependencies` peer and nothing installed provides. `check` reads it to
+        excuse those references as unresolvable rather than wrong, which is what lets a module be
+        opened on its own. It is stated here as DATA precisely so the record layer never has to
+        learn what a module is; a bare string list rather than `x-reference: collections`, because
+        the whole point is that the target is absent.
     owner:
       type: string
       x-reference: modules

package/collections/modules.collection.yaml

@@ -66,6 +66,14 @@ schema:
       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: >-

package/collections/repos.collection.yaml

@@ -33,7 +33,11 @@ schema:
       description: 'Opaque path segment grouping clones by the account that owns them: <repos-path>/<identity>/<name>.'
     path:
       type: string
-      description: Workspace-relative path override. Wins over the derived <repos-path>/<identity>/<name>.
+      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]

package/package.json

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

package/skills/using-dreamteamer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-dreamteamer
-description: always load first in a dreamteamer workspace — reading, writing and committing records, and changing what the workspace keeps or does (collections and fields, skills, commands, agents, ui-views, component code). Also when deciding which of those a request should become, when a compile or check error names a source file, or when a request names a new kind of thing to keep.
+description: always load first in a dreamteamer workspace — reading, writing and committing records, and changing what the workspace keeps or does (collections and fields, skills, commands, agents, ui-views, component code). Also when deciding which of those a request should become, when a compile or check error names a source file, or when a request names a new kind of thing to keep. Also for a brand-new or just-installed workspace, or dreamteamer over existing data.
 ---
 
 # using dreamteamer
@@ -39,7 +39,8 @@ unsure which skill owns the job in front of you.
 and the harness folders are gitignored build output, so a clone has no runtime until compile
 writes one — and `.env` is per-machine (declared keys: `references/records.md`). `dt status` says
 whether the runtime is fresh. the workspace's own switches live in `package.json`'s `dreamteamer`
-block (`references/collections.md`, the workspace manifest).
+block (`references/collections.md`, the workspace manifest) — and the guided path from nothing,
+or from existing data, is `references/getting-started.md`.
 
 ## the CLI is the front door
 
@@ -47,8 +48,21 @@ block (`references/collections.md`, the workspace manifest).
 workspace may alias it as an npm script — check `scripts` in `package.json` (the common spelling
 is `npm run --silent dt -- <verb> …`).
 
+**default to the CLI for every record read and write.** it validates before disk, generates the
+id, materializes defaults, and its writes are pathspec-scoped; touch a record file by hand only
+when the CLI cannot express the change (a long body, a nested map) — and then you owe `dt check`
+(`references/records.md`).
+
 **`dt help` is the complete command surface** — record verbs, schema verbs, workspace verbs, and
-their flags, on one page (there is no per-verb `--help`). don't learn syntax from prose, this skill included: prose drifts, and `help` ships in
+their flags, on one page (there is no per-verb `--help`).
+
+the verb names, as a map (semantics and flags live in `help`; a test holds this list to the
+dispatch, so it cannot drift):
+
+- read & measure — `list` `get` `values` `history` `diff` `commands` `relations` `resolve`
+- write & publish — `add` `set` `rm` `rename` `move` `revert` `commit` `ensure`
+- schema (sources, through the compile gate) — `schema` `add-collection` `rm-collection` `rename-collection` `add-field` `update-field` `remove-field` `add-view` `set-view` `rm-view`
+- workspace — `init` `install` `update` `compile` `check` `status` `start` `changes` `help` don't learn syntax from prose, this skill included: prose drifts, and `help` ships in
 the same file as the dispatch it documents. run it once before your first write of a session.
 what prose adds is judgment — *when* a verb is the right move, and the guarantees you can lean
 on: **validation is hard** (unknown fields included; an invalid write is rejected before disk
@@ -63,6 +77,7 @@ Load by the map; nothing here is loaded "just in case".
 
 | the job | load |
 |---|---|
+| a brand-new or empty workspace, dreamteamer over an existing pile of files, "help me set this up" | `references/getting-started.md` |
 | read, create, update, rename, delete, commit — or UNDO — a record | `references/records.md` |
 | "what changed while I was away" | `references/changes.md` |
 | the workspace seems unable to do something — a new kind of thing, a missing capability, "don't we already have this?" | `references/before-you-build.md` (look first); a new model then continues `references/data-modeling.md` (decide) → `references/collections.md` (write it) |
@@ -98,8 +113,9 @@ workspace's decision log (where one exists) wins over older documents.
 2. **the filename is the id.** where a record also carries a frontmatter `name` (agents,
    commands), the two must agree, or the id lies and dispatch misses.
 3. **the meta-descriptor is the spec.** every source kind is itself a collection — read
-   `.dreamteamer/collections/<kind>.collection.yaml` plus one real record (`dt get <kind>/<id>`)
-   instead of learning a shape from prose.
+   `.dreamteamer/collections/<kind>.collection.yaml`; its field descriptions are the contract.
+   prose drifts, and a sample record is one arbitrary instance — when a schema underdocuments a
+   convention, fixing the schema IS the task (`references/records.md`).
 4. **`dt compile`, then `dt check`**, after any source change. compile fails closed — a bad
    source is rejected and the previous runtime stands; check reports and never modifies.
 5. **a running session does not see new sources.** a new skill, command or agent is live in the

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

@@ -71,8 +71,19 @@ unpublished schema is not a state the workspace should sit in. The verbs and eve
   or **edit the owning module's descriptor by hand** and compile (the change ships with the
   module) — the only exit for a removal. Pick by who should own the field — `data-modeling.md`
   Part III.
+- **`--type <collection>` beats the type sugar, always.** A type that names a collection in the
+  runtime is a reference to it, whatever `string`/`enum`/`date`/`tags`/… would otherwise mean — so
+  in a workspace that ships a `tags` collection, `--type tags` points at it and the relation flags
+  work on it. Only a stated `--type` resolves this way; omitting it still means a plain string.
 - `remove-field` on a populated field **clears the values in the same write and reports the
-  count** — a leftover key would make every later write to those records fail as unknown.
+  count** — a leftover key would make every later write to those records fail as unknown. It also
+  prunes the field out of **the same descriptor's `list_fields` and `sort_field`** (that is the
+  field's own presentation, and a dangling `sort_field` is a compile error), and **warns, by id,**
+  about any ui-view whose `options.columns` still names it — a different source, so it is named
+  rather than edited.
+- **`add-field` inserts before the `x-body` field**, on the same rule as a `templates:` merge
+  below: property order is form order, and a record's body belongs last. `update-field` never
+  reorders — an existing field keeps the place its author gave it.
 - **`schema rename-collection <old> <new>`** moves the descriptor **in the module that ships it**
   (its guard is against writes an `npm install` would erase, not against modules), plus the
   records, the filenames and every inbound reference — `x-reference` targets in other descriptors
@@ -82,8 +93,8 @@ unpublished schema is not a state the workspace should sit in. The verbs and eve
   does NOT overrule two authored choices: a hand-set `storage.path` (records stay put, and it
   says so) and a `storage.suffix` that is not the singular of the old name.
 - An **empty value removes** in dotted `set-view` writes just as it does in `dt set` — so a
-  setting whose meaningful value IS empty (`options.sort: ''`, see `ui-views.md`) must be
-  hand-written in the source file; the CLI cannot express it.
+  setting whose meaningful value IS empty (`options.sort: ''`, see `ui-views.md`) is written
+  QUOTED, which is what says "the empty string is the value": `'options.sort=""'`.
 
 ## declaring a module
 

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

@@ -420,6 +420,9 @@ descriptions are what an agent reads before writing a value. So:
 - A field's `description` says what the value MEANS, names the source when the value is copied
   from elsewhere, and states the convention an agent must follow ("empty means unmatched — the
   matching command's queue").
+- A field whose valid value has a non-obvious SHAPE carries an `examples:` annotation — standard
+  JSON Schema, passed through to the compiled descriptor — so the canonical value lives in the
+  contract, not in whichever record a writer happens to open.
 - `use_when` is authored **only** when an agent that fully understood the description would still
   not reach for the collection — a search-here-first trigger, a write-here-when situation. It is
   prose; nothing fires on it; and a `use_when` restating the description costs every session
@@ -814,8 +817,11 @@ useless until the flood is drained.
   message being the ledger); `schema remove-field` the old one — which clears any leftovers and
   reports the count.
 - **Values** (an id, a reference target): `dt rename <collection>/<old> <new>` rewrites inbound
-  references; qualified prose wikilinks are followed, bare-name prose is not — one more reason
-  references in bodies are written qualified.
+  references. Prose wikilinks are followed in both spellings — `[[collection/id]]` always, and a
+  bare `[[id]]` when that basename names exactly ONE record in the workspace; when something else
+  claims it, the link is left alone and the rename says so, naming the file. A `#anchor` and a
+  `|label` both ride through untouched (`[[id#heading|see here]]`) — only the record moved. Raw
+  prose that is not a wikilink is counted and reported, never rewritten.
 
 ### 42. Migrations are scripts, run once, committed with their effects
 

package/skills/using-dreamteamer/references/getting-started.md

@@ -0,0 +1,113 @@
+# getting started — from nothing, or from a pile, to a working workspace
+
+Three arrivals land here, and they end in the same place. **The empty folder**: someone ran
+`npm install dreamteamer` (or is about to) and has nothing else. **The existing pile**: a repo or
+folder that already holds real files — notes, exports, spreadsheets — that should become records.
+**The operator who is technical enough to run npm and not much more** — for whom the git section
+below is written in plain words. The finish line for all three is identical: a compiled runtime,
+ONE honest collection with real records in it, published — not an architecture.
+
+No UI is assumed anywhere below. The CLI and the records are complete on their own; any surface
+that reads the compiled runtime can render the same workspace later, unchanged.
+
+| the situation | read |
+|---|---|
+| nothing exists yet | the skeleton, then path A |
+| real files already exist | the skeleton, then path B |
+| dreamteamer joins a repo that also holds code | the skeleton, then path C |
+| "do I need git? a server? an account?" | git, in plain words |
+
+## the skeleton — five commands, one minute
+
+```bash
+npm init -y                 # only if there is no package.json yet
+npm install dreamteamer
+git init                    # strongly recommended, not required to start — see below. first,
+                            # so init can commit its own skeleton (it does, when git is there)
+npx dreamteamer init        # writes the workspace skeleton; never compiles
+npx dreamteamer compile     # materializes the runtime; writes the orientation block
+npx dreamteamer check       # should report 0 violations over the starter collection
+```
+
+`init` writes the `dreamteamer` block into `package.json` (the workspace manifest —
+`collections.md`), a workspace module at `modules/default/` with a starter `notes` collection,
+and `.env.example`. `compile` is what makes it real: the runtime under `.dreamteamer/`, the
+harness folders, and the orientation block every future agent session reads — which is how the
+next session finds this skill without being told.
+
+## git, in plain words
+
+git is three things to this workspace, and none of them needs a server or an account:
+
+- **the history** — every change to every record, forever, answerable (`dt history`, `dt changes`);
+- **the undo** — any record restorable to any prior state (`records.md`, undoing);
+- **the publish step** — `dt commit` is what turns "written to disk" into "on the record".
+
+Verified capability split: **without git, everything still reads, writes, validates and compiles**
+— only `dt commit`, `dt changes` and `dt history`/`diff`/`revert` are unavailable. `git init` is
+one command, local, free, and turns all of them on. A **remote** (GitHub or anywhere) is a
+separate, optional, later decision — it buys backup and a second machine, and nothing here needs
+it. If the operator is unsure: run `git init`, skip the remote, move on.
+
+## path A — nothing yet: model from an interview
+
+The first hour's goal is **one collection the operator will actually touch tomorrow**, holding
+real records. Not five collections, not a namespace plan, not a module layout.
+
+1. **Find the daily thing.** Ask what they keep re-finding, re-asking or losing — the answer names
+   the first collection. When the requirement is vague, `data-modeling.md` Part II is the
+   interview: twelve questions, most answered by the requirement itself.
+2. **Propose small, then stop.** The proposal contract (`data-modeling.md` §7): the descriptor
+   YAML, one sample record as its `dt add` line, and what is deliberately NOT modelled. The
+   operator says yes before anything lands.
+3. **Create it in the workspace module** — `dt schema add-collection` (it compiles and publishes
+   itself). The workspace module is the right first home for everything (`data-modeling.md` §8);
+   extraction is a decision for the second consumer, months away.
+4. **Seed three to five REAL records immediately** with `dt add` — not test data. Seeding real
+   records before declaring the model finished catches half the field mistakes: the missing unit,
+   the enum the domain spells differently, the id that comes out wrong.
+5. **Iterate on evidence**: `dt values` shows what the fields actually hold, `dt check` what
+   disagrees. Adjust, then — only then — consider the second collection.
+
+Deliberately deferred, each until its trigger: a **namespace** (first second-DOMAIN collection,
+not before — `collections.md`) · a **module of its own** (a second consumer or a closed reference
+graph — `data-modeling.md` §8) · **skills, commands, views** (after records exist — behaviour
+follows shape, and a view needs a recurring question to encode).
+
+## path B — dreamteamer over an existing pile
+
+The pile is evidence; read it before modeling anything.
+
+1. **Survey**: what file kinds, how many, what dates and names they carry, and — most useful —
+   what questions the operator actually asks of this pile. Read a handful of files end to end.
+2. **Split the pile in two.** Files that already look like records — one thing per file, with
+   discoverable fields — get **registered where they stand**: `collections.md`, "registering an
+   existing data folder" (derive the descriptor from reality; an authored `storage.path` points at
+   the existing folder; **never rewrite records to fit an inferred schema**). Tabular exports
+   (CSVs, spreadsheets) get **imported**: `records.md`, the bulk-write recipe — one script, one
+   check, one collection-scoped commit.
+3. **Big and binary files never become records.** They stay where they are (or move to a files
+   folder), and a record points at each via a `${env:VAR}` template — the filing convention and
+   the mechanics are in `records.md`.
+4. **Restructure later, with the tools that keep references true** — `dt rename`,
+   `dt schema rename-collection` — not during the first pass. Model reality first; `check` will
+   tell you what reality violates, and that list, not taste, drives the cleanup.
+
+## path C — into a repo that already holds code
+
+The workspace root is wherever `package.json` carries the `dreamteamer` block — a repo can be
+both a codebase and a workspace. `init`'s runtime folders are gitignored, records default to
+`data/` beside the code, and an authored `storage.path` can put any collection anywhere the repo
+prefers. Nothing about the code moves; `check` and `compile` read only what descriptors name.
+
+## the first hour's mistakes
+
+| mistake | reality |
+|---|---|
+| modeling the whole domain up front | one collection used tomorrow beats five perfect ones — widening is always safe later (`data-modeling.md` Part IX) |
+| test data in the seed records | real records are what catch the model's mistakes |
+| skipping git as "too technical" | one local command, no account — and it is the history, the undo and the publish step |
+| inventing ids by hand | `id.generate` owns identity — pass `--id` only when the operator named one |
+| hand-writing the first descriptor | `dt schema add-collection` is compile-gated and publishes itself; hand-written sources owe `dt compile` |
+| rewriting existing files to fit a guessed schema | describe reality, compile, `check` — then decide which violations are worth fixing in the data |
+| waiting for a UI before starting | the CLI and the records are the complete system; any surface renders them later, unchanged |

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

@@ -18,13 +18,13 @@ commands, ui-views, collections) are *sources*: edit the file under the owning m
 
 the verbs and flags are `dt help`'s job; what to know *about* them:
 
-- narrowing a `list`: `--filter k=v` for one condition; **anything compound goes in one
-  `--where`** — its operator grammar is enumerated in `dt help`, and it is
+- narrowing a `list`: `--filter k=v` per condition, **repeated to AND more of them**
+  (`--filter status=todo --filter owner=ana` wants both); **anything an equality cannot say goes
+  in one `--where`** — its operator grammar is enumerated in `dt help`, and it is
   the same one views and gates use — e.g.
   `dt list health/prescriptions --where '{"_and":[{"patient":{"_eq":"health/patients/dana-levi"}},{"status":{"_eq":"active"}}]}'`.
-  ⚠ two `--filter` flags do NOT combine (the last one wins), and an unknown field or a dangling
-  ref **narrows to nothing** rather than erroring — filter field names deserve the same care as
-  code.
+  ⚠ an unknown field or a dangling ref **narrows to nothing** rather than erroring — filter field
+  names deserve the same care as code.
 - ⚠ **there is no `@me` and no `users` collection** (both removed in 0.8.0). when a person is
   needed, read `git config user.name`; filter on a person only when this workspace ships its own
   collection of people.
@@ -42,8 +42,12 @@ the verbs and flags are `dt help`'s job; what to know *about* them:
   nothing written. a rejected write leaves no partial state.
 - **a write puts the record on disk; `dt commit` publishes it** — committing is workspace policy
   (`auto-commit` in `package.json`, default off), never part of the write.
-- `set <collection>/<id> <field>=` with an empty value **removes** the field; array fields take a
-  comma-separated value; the `x-body` field is set like any other field.
+- `set <collection>/<id> <field>=` with an empty value **removes** the field; the `x-body` field is
+  set like any other field.
+- an **array field** takes a comma-separated value (`--tags a,b`, `tags=a,b`) — or the flag/pair
+  **repeated**, one element per sighting (`--tags a --tags b`), which is how a value that itself
+  contains a comma gets written. ⚠ repeating a **scalar** field is refused, naming it: it used to
+  keep the last value silently, so the first one never reached disk.
 - ids generate from the record's own creation-time values — pass `--id` only when the operator
   named one.
 
@@ -54,14 +58,27 @@ read the compiled descriptor: `.dreamteamer/collections/<collection>.collection.
 Schema; the `x-` keywords carry the domain semantics — `x-reference`, `x-body`, `x-inverse`). it
 also carries `title` (what to call the collection) and `title_template` (how to label one record).
 
+the schema is the CONTRACT, and it is required to be sufficient: each field's `description`
+carries its conventions, an `examples:` annotation (standard JSON Schema — compile passes it
+through to the compiled descriptor) carries a canonical value where the shape is non-obvious, and
+`dt values` shows a vocabulary's real spread. so **with a sufficient schema, do not open sibling
+records for shape** — the descriptor answers faster than a peek, the validator rejects a wrong
+write before disk, and a sibling is a bet on whichever record you grabbed being representative
+(measured blind: the peek route bought nothing the descriptor already said, and it only works
+while consistent siblings happen to exist). a schema that makes you peek to write correctly is a
+defect in the schema — fix it.
+
 ## writing a record by hand
 
 **default to `dt add <collection>`** — id, defaults and validation 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 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:
+when you do, the descriptor is still the contract — required, defaults, each field's
+`description` and `examples:`, `dt values` for vocabularies. peek at a sibling
+(`dt get <collection>/<id> --json`) only when the schema underdocuments a convention you need — a
+sibling is ONE arbitrary instance, possibly written before the schema last moved — and the miss
+itself is the finding: put the convention into the field's `description` (or an `examples:`) in
+the same breath, so the next writer needs no peek. then:
 
 - put the file where the id says: the id IS its path inside `storage.path`, minus suffix and
   extension (folder-shape records are a folder named `<id>` holding the descriptor's `entry`).
@@ -192,7 +209,8 @@ two hundred.
 |---|---|
 | `mv data/tasks/old.task.md …/new.task.md` | every inbound ref now dangles. `dt rename`. |
 | renaming a record because its title changed | the id is not a display name — edit the field |
-| two `--filter` flags to AND conditions | the last flag wins — compound conditions go in one `--where` |
+| a `--filter` per condition | right — they AND; only what equality cannot express needs `--where` |
+| `--tags a --tags b` on a scalar field | refused, naming the field — a repeat is an array ELEMENT, and a scalar has no room for two |
 | `--force` to get past an `rm` refusal | it leaves inbound refs dangling — retarget them first (unless the refusal named a *prose* mention, which isn't a real reference) |
 | omitting schema defaults from a hand-written file | the file stops being legible without the schema |
 | unquoted `due: 2026-07-28` in hand-written YAML | dreamteamer parses CORE_SCHEMA so it stays a string *here*, but a default-schema YAML reader turns it into a timestamp — quote dates |

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

@@ -121,9 +121,16 @@ same record. A misspelled key is read by nobody, silently. The two edges that bi
   naming a field the schema lacks is **dropped, not fallen back from** — which is how a core inbox
   view asking for `title` on a collection whose field is `name` rendered every row nameless with no
   error. Check the descriptor's real field names against every column you write.
+- **A list-valued option takes the comma spelling**: `set-view <id> options.columns=name,status`
+  writes a real list, as does the JSON form `'["name","status"]'`. The keys that split are
+  `columns`, `ref_fields` and `value_fields` — `options` has no schema, so a key not on that list
+  keeps its commas as characters (`options.template=a, b` is one string), and a list of OBJECTS
+  (`options.arrangement`) has only the JSON spelling.
 - ⚠ **`options.sort` must be written even when empty** (`sort: ''`), or "unsorted" cannot
-  round-trip and silently reverts to a fallback ordering on the next load. The CLI cannot express
-  it (an empty `set-view` value removes the key) — hand-write it in the source.
+  round-trip and silently reverts to a fallback ordering on the next load. The spelling is a
+  QUOTED value — `dt schema set-view <id> 'options.sort=""'` — because a bare `options.sort=`
+  removes the key, as an empty value does everywhere else. Quoting any value makes it a literal
+  string (`options.sort='"-date"'` is the same as `options.sort=-date`).
 
 Views are live records: a changed `filter` or `options` reaches an open tab on the next compile;
 an unchanged view re-renders nothing.
@@ -152,7 +159,7 @@ kind with full CLI write support, because it goes through the same compile gate.
 `add-view` writes the **workspace module** — right for an operator's own daily surface; a view
 that is part of a module's canonical shape belongs in that module's `ui-views/`, hand-written.
 And a dotted `key=` with an **empty value removes the key**, so the one setting whose meaningful
-value IS empty — `sort: ''` — must be hand-written in the source file (see options).
+value IS empty — `sort: ''` — is written QUOTED: `'options.sort=""'` (see options).
 
 ## common mistakes
 
@@ -164,7 +171,7 @@ value IS empty — `sort: ''` — must be hand-written in the source file (see o
 | a filter using `@me` | gone in 0.8.0 with `users` — compile refuses it by name |
 | `filter` written inside `options` | accepted, saved, read by nobody — compile warns; move it up |
 | a column the schema does not have | dropped silently — the row loses that value with no error |
-| omitting `sort` to mean unsorted | write `sort: ''` or the ordering reverts on reload |
+| omitting `sort` to mean unsorted | write `sort: ''` (`'options.sort=""'`) or the ordering reverts on reload |
 | a ui-view that restates the built-in fallback | a record to maintain for zero gain |
 | a `default: true` view with its own `path`/`nav` | the default IS the collection page — it never routes itself |
 | a module ui-view naming one person | a hard-coded id resolves in no other workspace |

package/src/check.js

@@ -8,7 +8,7 @@ import addFormats from 'ajv-formats';
 import { parseRecord, patternRe, fmtAjvError, unknownFields, walk, idFromRecordPath, MAX_RECORD_BYTES } from './records.js';
 import { NO_RUNTIME, loadDescriptors, runtimeDir, namespaces as compiledNamespaces } from './runtime.js';
 import { parseRef } from './namespace.js';
-import { refTargetsOf } from './ref.js';
+import { refTargetsOf, refIsSoft } from './ref.js';
 import { relationsOf, expectedMirrors } from './relations.js';
 
 export function check({ root }) {
@@ -122,9 +122,9 @@ export function check({ root }) {
 			for (const k of unknownFields(d.schema, fields)) {
 				flag(file, `unknown field "${k}" (not in the ${name} schema)`);
 			}
-			for (const [fieldPath, target] of refFields) {
+			for (const [fieldPath, target, soft] of refFields) {
 				for (const value of valuesAt(fields, fieldPath)) {
-					checkRef(file, fieldPath, value, target, softTargets);
+					checkRef(file, fieldPath, value, target, softTargets, soft);
 				}
 			}
 			parsed.get(name).set(id, fields);
@@ -168,7 +168,7 @@ export function check({ root }) {
 		}
 	}
 
-	function checkRef(file, fieldPath, value, targets, softTargets) {
+	function checkRef(file, fieldPath, value, targets, softTargets, soft = false) {
 		if (typeof value !== 'string') return;
 		if (value.startsWith('@')) return; // runtime tokens (@me, @initiator) are legal
 		// The SAME parser the store writes through (src/namespace.js) — `check` disagreeing with the
@@ -189,9 +189,14 @@ export function check({ root }) {
 				softRefs.set(coll, (softRefs.get(coll) ?? 0) + 1);
 				return;
 			}
+			// A SOFT field (`x-reference-soft`) is a declaration, not a resolved link — see ref.js.
+			if (soft) return;
 			return flag(file, `${fieldPath.join('.')}: reference "${value}" targets unknown collection "${coll}"`);
 		}
-		if (!index.get(coll).has(id)) return flag(file, `${fieldPath.join('.')}: dangling reference "${value}" — no such record`);
+		if (!index.get(coll).has(id)) {
+			if (soft) return; // resolve if present, ignore if absent
+			return flag(file, `${fieldPath.join('.')}: dangling reference "${value}" — no such record`);
+		}
 	}
 
 	// ---- report ----------------------------------------------------------------------
@@ -218,16 +223,17 @@ export function check({ root }) {
 }
 
 
-// collect [fieldPath, targets] for every x-reference in the schema, where `targets` is '*' or the
-// normalized array of declared collections (see refTargetsOf). Relations are NOT read here — they
-// are decoded once, from the compiled descriptors, by src/relations.js.
+// collect [fieldPath, targets, soft] for every x-reference in the schema, where `targets` is '*' or
+// the normalized array of declared collections (see refTargetsOf) and `soft` says whether an absent
+// target is a finding (see refIsSoft). Relations are NOT read here — they are decoded once, from the
+// compiled descriptors, by src/relations.js.
 function collectRefFields(schema, prefix = []) {
 	const out = [];
 	for (const [key, s] of Object.entries(schema.properties ?? {})) {
 		if (!s || typeof s !== 'object') continue;
 		const p = [...prefix, key];
 		const targets = refTargetsOf(s);
-		if (targets) out.push([p, targets]);
+		if (targets) out.push([p, targets, refIsSoft(s)]);
 		if (s.properties) out.push(...collectRefFields(s, p));
 		if (s.items?.properties) out.push(...collectRefFields(s.items, p));
 	}

package/src/cli.js

@@ -21,7 +21,7 @@ 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';
+import { envContext, 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
@@ -35,7 +35,8 @@ 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]
-                                              (--filter is ONE condition — a repeat replaces it;
+                                              (--filter is ONE condition — repeat it to AND more
+                                               (--filter a=1 --filter b=2 wants both);
                                                anything compound goes in one --where, operator
                                                objects e.g. '{"starts":{"_gte":"2026-07-01"}}' —
                                                operators: _eq _neq _lt _lte _gt _gte _in _nin
@@ -47,8 +48,12 @@ the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee i
   add    <collection> --<field> <value> … [--id <explicit-id>]
                                               (a codec-file collection takes --from <path>
                                                instead — the file IS the record, fields derive;
-                                               --force replaces an existing file record)
-  set    <collection>/<id> <field>=<value> …
+                                               --force replaces an existing file record.
+                                               A repeated --<field> is one ELEMENT of an array
+                                               field — refused on a scalar one; a single value
+                                               still splits on commas)
+  set    <collection>/<id> <field>=<value> …  (repeating a pair adds an element, exactly as a
+                                               repeated --<field> does)
   rm     <collection>/<id> [--force]
   rename <collection>/<id> <new-id>           (rewrites all inbound refs in one WRITE —
                                                commit publishes the set together)
@@ -109,7 +114,10 @@ different word in front of it):
   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 set-view <id> <key>=<value> …        (dotted keys: options.sort=-date, nav.label=Recent.
+                            A list option takes commas — options.columns=name,status — or JSON.
+                            An empty value REMOVES the key; quote it to write the empty string
+                            itself: 'options.sort=""' is the "unsorted" the surface needs.)
   schema rm-view <id>
 
 workspace verbs:
@@ -315,7 +323,9 @@ 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 ensure ${r.id})`);
+						// an UNRESOLVED path is not the same absence as a repo simply not cloned yet, and
+						// `dreamteamer ensure` is not the fix for it — say which one this is.
+						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path}${r.unresolved ? ` — ${r.unresolved}` : ` (dreamteamer ensure ${r.id})`}`);
 					}
 				} catch { /* no repos descriptor compiled — nothing to report */ }
 				// Uncommitted records are invisible to `dt changes` (it diffs commits), so the
@@ -395,8 +405,11 @@ function dispatchRecordVerb(ws, verb, args) {
 	// `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]);
+	// An explicit `--ids` from the caller still wins — by NOT injecting ours, not by ordering. It
+	// used to rely on "last flag parsed wins", which stopped being true when a repeated flag started
+	// promoting to an array instead of overwriting: the pair would now be refused as a double.
+	const ours = rest.some((a) => a === '--ids' || a.startsWith('--ids=')) ? [] : ['--ids', id];
+	return collectionCommand(ws, 'commands', 'for', [collection, ...ours, ...rest]);
 }
 
 /**
@@ -419,10 +432,7 @@ function resolveVariables(ws, args) {
 	// 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 };
+	const ctx = envContext(ws);
 
 	let ref = null;
 	let store = null;