dreamteamer 0.16.1 → 0.18.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.1",
+	"version": "0.18.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>",
@@ -48,7 +48,8 @@
 		"ajv-formats": "^3.0.1",
 		"express": "^5.2.1",
 		"fractional-indexing": "^4.0.0",
-		"js-yaml": "^4.1.0"
+		"js-yaml": "^4.1.0",
+		"yaml": "2.8.1"
 	},
 	"dreamteamer": {
 		"title": "System"

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

@@ -817,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/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.
 
@@ -205,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;