dreamteamer 0.16.0 → 0.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.16.0",
+	"version": "0.16.1",
 	"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/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

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

@@ -54,14 +54,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`).