create-nisc 0.9.2 → 0.9.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +20 -22
  3. package/dist/{chunk-RUHOVTHF.js → chunk-2W7KLXCO.js} +3 -3
  4. package/dist/{chunk-RUHOVTHF.js.map → chunk-2W7KLXCO.js.map} +1 -1
  5. package/dist/cli.js +1 -1
  6. package/dist/index.js +1 -1
  7. package/package.json +1 -1
  8. package/templates/base/files/src/ui/kit.css +8 -41
  9. package/templates/dom/files/src/ui/kit.ts +2 -8
  10. package/templates/dom/files/src/ui/registry.ts +2 -2
  11. package/templates/model-first/agents-section.md +31 -25
  12. package/templates/model-first/files/src/app/action-catalog.ts +4 -3
  13. package/templates/model-first/files/src/app/actions/answer/turn.action.ts +23 -0
  14. package/templates/model-first/files/src/app/actions/ask/dock.action.ts +10 -33
  15. package/templates/model-first/files/src/app/actions/ask/dock.layout.ts +7 -39
  16. package/templates/model-first/files/src/app/actions/guide/guide.actions.ts +16 -19
  17. package/templates/model-first/files/src/app/app.ts +4 -3
  18. package/templates/model-first/files/src/app/charter/charter.ts +1 -1
  19. package/templates/model-first/files/src/app/screens.ts +27 -48
  20. package/templates/model-first/files/src/app/shell/frame.layout.ts +5 -1
  21. package/templates/model-first/files/src/app/shell/shell.ts +7 -10
  22. package/templates/model-first/files/src/dev/all-checks.ts +3 -3
  23. package/templates/model-first/files/src/dev/artifacts-check.ts +14 -25
  24. package/templates/model-first/files/src/dev/compose-check.ts +87 -136
  25. package/templates/model-first/files/src/dev/guide-check.ts +41 -58
  26. package/templates/model-first/files/src/dev/live-ask.ts +43 -138
  27. package/templates/model-first/files/src/dev/scripted.ts +24 -102
  28. package/templates/model-first/files/src/dev/shape-check.ts +2 -6
  29. package/templates/model-first/files/src/dev/strata.ts +2 -2
  30. package/templates/model-first/files/src/server/boot.ts +2 -2
  31. package/templates/model-first/files/src/server/compose/catalog.ts +10 -28
  32. package/templates/model-first/files/src/server/compose/composer.agent.ts +13 -11
  33. package/templates/model-first/files/src/server/compose/index.ts +55 -132
  34. package/templates/model-first/files/src/server/compose/knowledge.ts +22 -43
  35. package/templates/model-first/files/src/server/compose/turn.schema.ts +55 -0
  36. package/templates/model-first/files/src/server/models/index.ts +5 -23
  37. package/templates/model-first/item.json +28 -38
  38. package/templates/react/files/src/ui/kit.tsx +14 -25
  39. package/templates/react/files/src/ui/registry.ts +2 -2
  40. package/templates/model-first/files/src/app/arrangements.ts +0 -17
  41. package/templates/model-first/files/src/app/shell/areas.ts +0 -3
  42. package/templates/model-first/files/src/server/compose/answer.ts +0 -145
  43. package/templates/model-first/files/src/server/compose/history.ts +0 -45
  44. package/templates/model-first/files/src/server/compose/layout.ts +0 -70
  45. package/templates/model-first/files/src/server/compose/pick.ts +0 -44
  46. package/templates/model-first/files/src/server/compose/plan.ts +0 -45
  47. package/templates/model-first/files/src/server/compose/reply.schema.ts +0 -70
  48. package/templates/model-first/files/src/server/compose/screen.ts +0 -40
@@ -1,28 +1,26 @@
1
- ## How the model leads
2
-
3
- There is no chat history: the screen open when a message arrives is the conversation. The answer fills the page and scrolls; one dock stays at the bottom (`src/app/actions/ask/dock.action.ts`). Read from the screen down to the hands, it holds the **screens** (`src/app/screens.ts`: canvases shown together, opened without asking, as a card's link opens one); a chip naming the answer shown by its title and where it stands ("The charter · 2/5"), with back and forward beside it, which opens upward to what was asked, what the model said it did, and every answer to go back to, each by its title; and the line to ask in. A person types there, and the answer is a screen: up to six canvases — an action opened with an input, and why it is there — on the areas `a`–`f`. The canvas an answer changed is outlined until the next one. The first screen is what the app opens on, and the first in the stack. A screen already in the stack is gone back to, not stacked again.
4
-
5
- - **The message loop is `src/server/compose/`**, the function `ask`:
6
- 1. **The open screen is read** (`screen.ts`), area by area, the words too: each canvas's action and intent; its input as it stands, with what the person pressed, ticked or picked in what the input carries; and what else its live data holds beyond what it was opened with — a list as its count and its first three rows, ids left out; a line being typed. Before anything else is shown — an answer, a screen, back or forward — the screen as it stands is kept with the answer it is on, as a browser keeps a page's form: going back shows it as the person left it.
7
- 2. **Jev's pass** (`pick.ts`): over the message and the open screen, how likely each action, read, write and screen of the catalog belongs in the answer, in about 200 ms (what it was measured to be worth is PLAN.md D6). Only a hint: the model decides, and only what the pass finds likely (0.5 or more) is shown to it. Whether a canvas is still wanted is the model's to say (PLAN.md D11).
8
- 3. **gpt-oss-120b composes, as a cortex agent** (`composer.agent.ts`, `knowledge.ts`, `reply.schema.ts`, `answer.ts`). Its producers give it the catalog — each action the person holds that the model may place, with its input's JSON Schema, each read with the rows it answers and the values it is asked with, each write, the screens, the arrangements with where each puts its areas — and cortex's OUTPUT SCHEMA, the envelope with the reply's own JSON Schema in it, in the part of the prompt that never changes; the run's input is the open screen, Jev's picks as a hint, and the message. What each field of the reply means is said on the schema (`.describe()`), never in prose beside it (nisc rule 15). It answers with cortex's envelope: its `reasoning` first, then its `response` — one sentence for the person, at most 120 characters, saying what it changes and why, or why nothing changes, shown when the dock's chip is opened — then its `data`, the reply: its `title` — what the answer is, in at most four words, the name the chip and the stack give it — then **the areas that change** (PLAN.md D10): each a canvas moved there from another area (`keep`), a canvas, words (`say`, only where no action shows what was asked), or nothing (`drop`); an area it leaves out stays as it is, unless the arrangement it gives has no such area — and then the room, when the one on screen will not do: an arrangement, or a grid of its own. Or it replies with one of the app's screens as it is (`screen`). The reply is checked whole — every action in the catalog, every input against its action's schema, every read and write one the app ships, every value a read is asked with present and none it does not take, every field a write saves present, every area in the arrangement, nothing kept from an empty area, nothing shown twice — by the agent's `output.validate`, and one that does not hold, or does not fit the schema, is corrected inside the same run with what is wrong with it: three answers at most (cortex's `outputRetries`). About 1 s.
9
- 4. **The answer is laid out,** in the arrangement on screen unless the model gives another (`src/app/arrangements.ts`), or a grid it writes (`grid`: how many columns, and the areas in the order they are drawn, each with its span), which the server turns into the layout. The server swaps it into the region — around moss, through `@niscorp/moss/unverified`, until the app has sign-in; then through `session.draft`.
10
- 5. **The plan is placed by the dock,** with nova's `reconcile`: each area holds exactly what the plan lists for it. A canvas that stays keeps its instance and what the person did to it; a card the model writes again is written where it stands. A canvas written onto a screen holds its whole input — what it leaves out is its action's default (`opened`, in `catalog.ts`) — so a card written where another was keeps nothing of it (PLAN.md D12). An answer that changes nothing adds nothing to the stack; the chip still names what was asked and opens to what the model said. A screen opened, or back or forward pressed, while an answer streams in is what is shown: that answer is no longer placed.
11
- 6. **The answer streams in.** Cortex hands the composer the reply as solid parses it, while the model writes it. Once an area's entry is followed by the next, or by the room, it is finished, and it is placed in the room on screen if its own checks pass; another room, or a screen, comes with the whole reply; the dock re-reads the answer so far (`answers.current`) whenever the message `answer-moved` says it moved. Whether the whole reply holds is checked when it ends. A correction, or a run that ends without an answer, puts the screen back as it was.
12
- - **A message that gets no screen leaves the screen as it is,** and the line says why: the model's reply did not fit, it could not be reached, or there is no key.
13
- - **Jev may take 2 s and the model 8 s.** A Jev pass given up leaves the model to answer alone.
14
- - **Every message is recorded as a run for each model it went to,** through moss (`session.recordRun`): `nisc-template-app.jev` and `nisc-template-app.compose`, each with its provider and model, the tokens it spent (`reported: false` where signal estimated them), its steps and how long it took — for the composer, cortex's run meta — and whether it ended in an answer. The server logs a line for each (`src/server/runs/`).
15
- - **The app starts as a tour of nisc** (`src/app/actions/guide/`): five screens in the dock — a start, three lessons, and how to make it yours. Cards to read — points, an example in code, or steps, the text in the action's own data, no input; and one whose rows are read from a table, `guide.packages`, the shape your own reads take: a table whose rows a migration step writes (`src/db/schema.ts`), an entry whose Prism `mapping` words them (`src/app/vex/guide.entries.ts`), replayed by the action that shows them, granted in the charter — and cards to use: a counter, a checklist and a quick check, each with an input the model can fill. A card's link opens another screen at once, as the dock's buttons do; only what is typed, or a thing to ask pressed, goes to the model. What a person presses, ticks and picks stays on the screen; the model sees it, and can change it: "tick off the first step", "a counter that starts at 100", "quiz me on the charter". Its check is `src/dev/guide-check.ts`.
16
- - **An action you add is small, with one purpose:** it says what it shows (`description`), and declares what the model may open it with as a JSON Schema written with zod, every field described; the model's answers are checked against that same schema (`z.fromJSONSchema`). A read or a write it names must be one the app ships, asked with the values it takes. The ones the model may place are `placeable`, in `src/app/action-catalog.ts`.
1
+ ## How the assistant answers
2
+
3
+ The screen fills the page and scrolls; one dock stays at the bottom (`src/app/actions/ask/dock.action.ts`). Read from the top down, the dock has **the conversation** — each turn: what was asked, the sentence the model answered with, and the cards under it — then **the screens** (`src/app/screens.ts`: cards one under another, opened without asking, as a card's link opens one), and **the line to ask in**, which is empty again as soon as a message is sent. Asking never changes the screen behind.
4
+
5
+ - **The message loop is `src/server/compose/`**, the function `ask`, one run of the model a message:
6
+ 1. **The question goes into the conversation at once**, as a turn still being answered (`answer.turn`, on the shell's `talk` canvas). Messages are answered one at a time, in the order they were sent.
7
+ 2. **gpt-oss-120b answers, as a cortex agent** (`composer.agent.ts`, `knowledge.ts`, `turn.schema.ts`). It is told, in the part of the prompt that never changes, its instructions — the first paragraph is the app's own, who the assistant is and what it answers about (`ABOUT`) — and the cards the person may be shown (`placeable`, each with its input's JSON Schema, only the ones the person's roles reach); then, for each message, the conversation so far (its last four turns) and the message. It answers with cortex's envelope: its `response`, one sentence it is told to keep to 120 characters, and its `data`, up to three cards — one of the app's actions opened with an input, or words (`say`). What each field means is said on the schema (`.describe()`, nisc rule 15).
8
+ 3. **The answer is checked** by the agent's `output.validate` (`turnRefusals`): every card one the app has, its input one its schema takes, exactly one of a card or words, nothing shown twice. An answer that fails is sent back with what is wrong, inside the same run: five tries in all.
9
+ 4. **The turn is finished:** its sentence written in, then its cards after it, none of it a step Back takes. A card is opened with its whole input: what the model leaves out is its action's default (`opened`, in `catalog.ts`).
10
+ - **An answer that does not come is a turn that says so:** the model could not be reached, its answers kept failing the check, or there is no key. The line under the dock only says something when the call itself fails.
11
+ - **The conversation lives as long as the person's shell** (PLAN.md D8): the turns on its `talk` canvas, and what they said, beside the function. For somebody not signed in that is one connection.
12
+ - **Every message is recorded as a run** through moss (`session.recordRun`): `nisc-template-app.compose`, with its provider and model, the tokens it spent (`reported: false` where signal estimated them), its steps and how long it took, and whether it ended in an answer. The server logs a line for each (`src/server/runs/`).
13
+ - **The app starts as a tour of nisc** (`src/app/actions/guide/`): five screens in the dock — a start, three lessons, and how to make it yours. Cards to read — points, an example in code, or steps, the text in the action's own data, no input; one whose rows are read from a table, `guide.packages`, the shape your own reads take: a table whose rows a migration step writes (`src/db/schema.ts`), an entry whose Prism `mapping` words them (`src/app/vex/guide.entries.ts`), replayed by the action that shows them, granted in the charter — and cards to use: a counter, a checklist and a quick check, each with an input the model can fill ("a counter that starts at 100", "quiz me on the charter"). A card in the conversation works as it does on a screen. Its check is `src/dev/guide-check.ts`.
14
+ - **An action you add is small, with one purpose:** it says what it shows (`description`), and declares what the model may open it with as a JSON Schema written with zod, every field described; the model's answers are checked against that same schema (`z.fromJSONSchema`). The ones the model may show are `placeable`, in `src/app/action-catalog.ts`, each granted in the charter.
17
15
  - **The model never presses anything.** It opens cards with an input — a form filled in — and only the person saves.
18
- - **The keys are in `.env`:** `GROQ_API_KEY` (gpt-oss-120b; without it, a message is answered with a notice saying so), and `TYPESAFE_API_KEY` (Jev; without it there is no Jev pass).
19
- - **`src/dev/compose-check.ts` runs the loop offline**, with a scripted Jev and a scripted model (`src/dev/scripted.ts`), on words, screens and actions the app does not have — so it holds whatever actions the app ships. **`src/dev/live-ask.ts` asks the real models** its cases (`RUN`), each from the screen it was asked on, and counts the screens that are what the case wants, with nothing shown twice (`--runs=<n>`, `--why`, `--prompts` for everything the models were sent, `--no-jev`, or messages of your own, each after `--screen=<id>` to ask it from that screen). It costs a Jev pass and a chat call a message, and is not part of `npm run check`.
16
+ - **The key is in `.env`:** `GROQ_API_KEY`; without it, every message is answered with a turn saying so.
17
+ - **`src/dev/compose-check.ts` runs the loop offline**, with a scripted model (`src/dev/scripted.ts`), on words and on cards the app does not have — so it passes whatever actions the app ships. **`src/dev/live-ask.ts` asks the real model** its cases (`CASES`) and fails on a miss (`--runs=<n>`, `--why`, `--prompts` for everything the model was sent, or messages of your own). It costs a call a message, and is not part of `npm run check`.
20
18
 
21
19
  ## How to proceed from here
22
20
 
23
21
  The tour is a starting point, there to be deleted. First the interview: PLAN.md's open items, each answered or delegated by name (the rulebook's "Before any code").
24
22
 
25
- **Remove the tour.** It lives in four places and is named in six:
23
+ **Remove the tour.** It lives in four places and is named in seven:
26
24
 
27
25
  1. Delete `src/app/actions/guide/`, `src/dev/guide-check.ts` and `src/app/vex/guide.entries.ts`; in `src/db/schema.ts`, the tour's migration. Deleting a migration is safe only because no database that lasts has run it — the app runs on PGlite, which starts empty every boot. Once one has, the migration is history, and a table goes by appending a migration that drops it (rule 17).
28
26
  2. `src/app/action-catalog.ts`: drop the `GUIDE` import; `placeable` is `[]` until your own actions are in it.
@@ -31,13 +29,21 @@ The tour is a starting point, there to be deleted. First the interview: PLAN.md'
31
29
  5. `src/dev/all-checks.ts`: drop the `guide-check` line.
32
30
  6. `src/app/screens.ts`: everything below its two types — your screens instead of the tour's. Until there are actions, one screen of words will do:
33
31
  ```ts
34
- export const SCREENS: readonly [Screen, ...Screen[]] = [
35
- { id: 'start', label: 'Start', description: 'What this app is.', arrangement: 'single', canvases: [{ action: 'answer.text', input: { title: 'The app', text: 'What it is, in a sentence.' }, intent: 'what this app is' }] },
36
- ];
32
+ export const SCREENS: readonly [Screen, ...Screen[]] = [{ id: 'start', label: 'Start', cards: [{ action: 'answer.text', input: { title: 'The app', text: 'What it is, in a sentence.' } }] }];
37
33
  ```
38
- 7. `src/dev/live-ask.ts`: your cases in `RUN` instead of the tour's, and the helpers only its cases use (`at`, `listOf`, `tour`).
34
+ 7. `src/server/compose/knowledge.ts`: `ABOUT`, the assistant's paragraph — who it is in your app, and what it answers about. `src/dev/live-ask.ts`: your cases in `CASES` instead of the tour's.
39
35
  8. This file: the tour's rows under "Where things go", its paragraph above, and this list; PLAN.md: the tour in D3 and in the order of work. `npm run check` passes again.
40
36
 
41
- What stays is the app: the message loop, the dock, the arrangements, the kit, and `compose-check`, which needs nothing of the tour.
37
+ What stays is the app: the message loop, the dock and the conversation, the kit, and `compose-check`, which needs nothing of the tour.
42
38
 
43
- **Then build in PLAN.md's order of work,** each step checked before the next: your tables, reads and writes; your actions, each placeable one in `placeable` and every one granted in the charter's `actions`; your screens; a check for each feature in `src/dev/`; and `live-ask` cases for what people will ask.
39
+ ## From here to a full app
40
+
41
+ What the template leaves out, so that it starts small. None of it is required, and the order is yours: take a step when the app needs it, each checked before the next (PLAN.md's order of work).
42
+
43
+ - **Your data, and cards that show it.** A table in `src/db/schema.ts`, a read in `src/app/vex/`, an action that replays it — as `guide.packages` does — in `placeable`, granted in the charter, with a `live-ask` case for the question it answers. The model is told what a card shows, never the rows: to answer about your data, it shows the card.
44
+ - **Writes.** A form card the model may open filled in (D4); the person saves it, through a vex mutation, never the model.
45
+ - **Sign-in and roles.** Once more than one person uses the app, or anything in it is somebody's own: who is signed in is moss's (`runtime.session`), what each role may reach is the charter's. The model is offered, and a screen opens with, only the cards the person's roles reach — that filter is already there (`session.actions`). The dock lists every screen: when roles see different ones, give each person their own list through moss's `inputs`.
46
+ - **A conversation that outlives the shell** (D8, once there is sign-in). The turns become rows the person owns, written by the server as a machine role at the person's own reach (`executeAs`), read back when their shell is built (`seeds`); `place` and `said` in `src/server/compose/index.ts` are where it goes.
47
+ - **Facts the model can rely on,** as the cards need them. When a card takes a date, tell the model today's date, in the app's time zone, in `messageInput`. When it opens a record by its id, tell it the ids that exist, and refuse in `turnRefusals` an id it was not told: a model that makes up an id shows a card of nothing.
48
+ - **Asking back, and what to ask next.** A card of choices, each one a message emitted on `ask` when tapped — as the tour's examples are — for when the message could mean two things, or to offer the next question.
49
+ - **Deploying.** A real Postgres in `src/server/runtime.ts`, its tables applied by `nisc migrate`, never at boot (rule 17).
@@ -1,10 +1,11 @@
1
1
  import type { ActionDefinition } from '@niscorp/nova';
2
2
  import { textAction } from './actions/answer/text.action';
3
+ import { turnAction } from './actions/answer/turn.action';
3
4
  import { dockAction } from './actions/ask/dock.action';
4
5
  import { GUIDE } from './actions/guide/guide.actions';
5
6
 
6
- // What the model may put on a screen, each opened with an input its schema takes. Its words are `answer.text`, placed
7
- // by saying them; the dock is never placed.
7
+ // What the model may show under its sentence, each opened with an input its schema takes. Its words are `answer.text`,
8
+ // placed by saying them; the dock and the turn are never placed by the model.
8
9
  export const placeable: readonly ActionDefinition[] = GUIDE;
9
10
 
10
- export const actions: Record<string, ActionDefinition> = Object.fromEntries([dockAction, textAction, ...placeable].map((action) => [action.id, action]));
11
+ export const actions: Record<string, ActionDefinition> = Object.fromEntries([dockAction, textAction, turnAction, ...placeable].map((action) => [action.id, action]));
@@ -0,0 +1,23 @@
1
+ import type { ActionDefinition } from '@niscorp/nova';
2
+ import { z } from 'zod';
3
+
4
+ // One turn of the conversation: what was asked, and the sentence the model answered with, or that it is still
5
+ // answering. Its cards follow it. Put on the conversation by the server (`ask`), never by the model.
6
+ export const turnAction: ActionDefinition = {
7
+ id: 'answer.turn',
8
+ title: 'You asked',
9
+ description: 'One turn of the conversation: what the person asked, and what the model said back.',
10
+ data: { question: '', reply: '', thinking: false },
11
+ input: z.toJSONSchema(
12
+ z.object({
13
+ question: z.string().describe('What the person asked.'),
14
+ reply: z.string().describe('What the model said back.'),
15
+ thinking: z.boolean().describe('Whether the model is still answering.'),
16
+ }),
17
+ ),
18
+ layout: {
19
+ component: 'Card',
20
+ props: { title: '{{$.question}}' },
21
+ children: [{ if: '$.thinking', then: { component: 'Text', props: { tone: 'muted' }, children: 'Thinking…' }, else: { component: 'Text', children: '{{$.reply}}' } }],
22
+ },
23
+ };
@@ -1,58 +1,35 @@
1
1
  import type { ActionDefinition, Step } from '@niscorp/nova';
2
2
  import { SCREENS } from '../../screens';
3
- import { AREAS } from '../../shell/areas';
4
3
  import { dockLayout } from './dock.layout';
5
4
 
6
- const shown: Step[] = [{ set: 'listing', value: false }, ...AREAS.map((area) => ({ reconcile: { canvas: area, to: `$.current.canvases.${area}`, action: 'action', input: 'input', own: 'canvas' as const } }))];
5
+ const send: Step[] = [{ set: 'error', value: '' }, { call: 'ask', onError: [{ set: 'error', value: '{{@error.message}}' }] }];
6
+ // What was typed is what is asked, and the line is empty again at once: the answer shows in the conversation.
7
+ const ask: Step[] = [{ set: 'asked', value: '{{$.text}}' }, { set: 'text', value: '' }, ...send];
7
8
 
8
- const ask: Step[] = [
9
- { set: 'asking', value: true },
10
- { set: 'error', value: '' },
11
- {
12
- call: 'ask',
13
- onSuccess: [{ set: 'asking', value: false }, { set: 'text', value: '' }, ...shown],
14
- onError: [{ set: 'asking', value: false }, { set: 'error', value: '{{@error.message}}' }],
15
- },
16
- ];
17
-
18
- const open: Step[] = [{ set: 'opening', value: '@event.payload' }, { call: 'open', onSuccess: shown }];
19
-
20
- const [first] = SCREENS;
9
+ const open: Step[] = [{ set: 'opening', value: '@event.payload' }, { call: 'open' }];
21
10
 
22
11
  export const dockAction: ActionDefinition = {
23
12
  id: 'ask.dock',
24
13
  title: 'Dock',
25
- description:
26
- 'Everything a person does, at the bottom: the screens; the chip naming the answer shown and where it stands, which opens what was asked, what the model said it did, and every answer to go back to; back and forward; and the line to ask in.',
14
+ description: 'Everything a person does, at the bottom: the conversation, the screens, and the line to ask in.',
27
15
  data: {
28
16
  screens: SCREENS.map(({ id, label }) => ({ id, label })),
29
- current: { question: '', response: '', label: first.label, screen: first.id, arrangement: first.arrangement, position: 1, total: 1, stack: [{ position: 1, label: first.label }], canvases: {} },
30
- listing: false,
17
+ shown: { screen: SCREENS[0].id },
31
18
  opening: '',
32
- going: 0,
33
19
  text: '',
34
- asking: false,
20
+ asked: '',
35
21
  error: '',
36
22
  },
37
23
  layout: dockLayout,
38
24
  endpoints: {
39
- ask: { fn: 'ask', target: 'current' },
40
- open: { fn: 'screens.open', target: 'current' },
41
- back: { fn: 'answers.back', target: 'current' },
42
- forward: { fn: 'answers.forward', target: 'current' },
43
- go: { fn: 'answers.go', target: 'current' },
44
- current: { fn: 'answers.current', target: 'current' },
25
+ ask: { fn: 'ask' },
26
+ open: { fn: 'screens.open', target: 'shown' },
45
27
  },
46
28
  triggers: [
47
- { message: 'answer-moved', do: [{ call: 'current', onSuccess: shown }] },
48
- { message: 'ask', do: [{ set: 'text', value: '@event.payload' }, ...ask] },
29
+ { message: 'ask', do: [{ set: 'asked', value: '@event.payload' }, ...send] },
49
30
  { message: 'open', do: open },
50
31
  { event: 'ui:key', key: 'Enter', ref: 'text', do: ask },
51
32
  { event: 'ui:click', ref: 'send', do: ask },
52
33
  { event: 'ui:click', ref: 'screen', do: open },
53
- { event: 'ui:click', ref: 'back', do: [{ call: 'back', onSuccess: shown }] },
54
- { event: 'ui:click', ref: 'forward', do: [{ call: 'forward', onSuccess: shown }] },
55
- { event: 'ui:click', ref: 'stack', do: [{ toggle: 'listing' }] },
56
- { event: 'ui:click', ref: 'entry', do: [{ set: 'going', value: '@event.payload' }, { call: 'go', onSuccess: shown }] },
57
34
  ],
58
35
  };
@@ -3,55 +3,23 @@ import type { LayoutNode } from '@niscorp/nova';
3
3
  export const dockLayout: LayoutNode = {
4
4
  component: 'Dock',
5
5
  children: [
6
+ { component: 'Talk', children: [{ component: 'CanvasSlot', props: { canvasId: 'talk' } }] },
6
7
  {
7
8
  component: 'Row',
8
9
  children: [
9
10
  {
10
- component: 'Row',
11
- children: [
12
- {
13
- for: '$.screens',
14
- as: 'screen',
15
- key: 'id',
16
- do: { component: 'Button', ref: 'screen', props: { label: '$screen.label', value: '$screen.id', tone: { $if: { $eq: ['$screen.id', '$.current.screen'] }, $then: 'chosen', $else: 'choice' } } },
17
- },
18
- ],
19
- },
20
- {
21
- component: 'Row',
22
- children: [
23
- { component: 'Button', ref: 'back', props: { label: '←', tone: 'step' } },
24
- { component: 'Button', ref: 'stack', props: { label: '{{$.current.label}} · {{$.current.position}}/{{$.current.total}}', tone: 'summary' } },
25
- { component: 'Button', ref: 'forward', props: { label: '→', tone: 'step' } },
26
- ],
11
+ for: '$.screens',
12
+ as: 'screen',
13
+ key: 'id',
14
+ do: { component: 'Button', ref: 'screen', props: { label: '$screen.label', value: '$screen.id', tone: { $if: { $eq: ['$screen.id', '$.shown.screen'] }, $then: 'chosen', $else: 'choice' } } },
27
15
  },
28
16
  ],
29
17
  },
30
- {
31
- if: '$.listing',
32
- then: {
33
- component: 'Menu',
34
- children: [
35
- { if: '$.current.question', then: { component: 'Text', props: { tone: 'strong' }, children: '{{$.current.question}}' } },
36
- { if: '$.current.response', then: { component: 'Text', props: { tone: 'muted' }, children: '{{$.current.response}}' } },
37
- {
38
- for: '$.current.stack',
39
- as: 'entry',
40
- key: 'position',
41
- do: {
42
- component: 'Button',
43
- ref: 'entry',
44
- props: { label: '{{$entry.position}}. {{$entry.label}}', value: '$entry.position', tone: { $if: { $eq: ['$entry.position', '$.current.position'] }, $then: 'chosen', $else: 'choice' } },
45
- },
46
- },
47
- ],
48
- },
49
- },
50
18
  {
51
19
  component: 'Prompt',
52
20
  children: [
53
- { component: 'Input', ref: 'text', model: '$.text', props: { placeholder: 'What would you like to see?', clearOnEnter: true } },
54
- { component: 'Button', ref: 'send', props: { label: { $if: '$.asking', $then: 'Asking…', $else: 'Send' } } },
21
+ { component: 'Input', ref: 'text', model: '$.text', props: { placeholder: 'Ask anything', clearOnEnter: true } },
22
+ { component: 'Button', ref: 'send', props: { label: 'Send' } },
55
23
  { if: '$.error', then: { component: 'Text', props: { tone: 'error' }, children: '{{$.error}}' } },
56
24
  ],
57
25
  },
@@ -23,9 +23,9 @@ const card = (id: string, description: string, layout: LayoutNode, data: { title
23
23
  export const GUIDE: readonly ActionDefinition[] = [
24
24
  card('guide.welcome', 'The welcome: this app is a tour of nisc that a model leads; where the tour starts, and things to ask.', welcomeLayout, {
25
25
  title: 'Welcome to nisc',
26
- lead: 'This app is a short tour of nisc, and a model leads it. Use it like any app: press, tick, follow the links. Or ask for a screen, and the model builds it from these same cards.',
26
+ lead: 'This app is a short tour of nisc, and a model leads it. Use it like any app: press, tick, follow the links. Or ask something, and the model answers with these same cards.',
27
27
  links: [{ label: 'Start the tour →', screen: 'actions' }],
28
- examples: ['A counter that starts at 100', 'A checklist for my first nisc app', 'Quiz me on actions', 'Put the charter beside the counter'],
28
+ examples: ['A counter that starts at 100', 'A checklist for my first nisc app', 'Quiz me on actions', 'What is the charter?'],
29
29
  }, [opens, asks]),
30
30
  card('guide.nisc', 'What nisc is: apps built out of data — screens, reads, writes and rules as JSON, each with a schema — and code only at the edges, so a model can build them with you.', pointsLayout, {
31
31
  title: 'What nisc is',
@@ -33,7 +33,7 @@ export const GUIDE: readonly ActionDefinition[] = [
33
33
  points: [
34
34
  { title: 'Everything is data', text: 'Screens, reads, writes and rules are JSON, each with a schema.' },
35
35
  { title: 'Code at the edges', text: 'The kit draws and the server serves; the rest is data, checked.' },
36
- { title: 'Led by a model', text: 'Ask, and this app answers with a screen of its own cards.' },
36
+ { title: 'Led by a model', text: 'Ask, and this app answers with a sentence and its own cards.' },
37
37
  ],
38
38
  links: [{ label: 'Lesson 1: actions →', screen: 'actions' }],
39
39
  }),
@@ -53,7 +53,7 @@ export const GUIDE: readonly ActionDefinition[] = [
53
53
  '}',
54
54
  ].join('\n'),
55
55
  text: 'That is the counter on this screen. Actions live in src/app/actions/.',
56
- links: [{ label: 'Next: asking for a screen →', screen: 'asking' }],
56
+ links: [{ label: 'Next: asking →', screen: 'asking' }],
57
57
  }),
58
58
  card('guide.layouts', 'Layouts and the kit: a layout is JSON that names components and binds them to the action’s data, and never styles; the kit in src/ui/ draws them, and its stylesheet holds the look.', exampleLayout, {
59
59
  title: 'Layouts and the kit',
@@ -61,26 +61,26 @@ export const GUIDE: readonly ActionDefinition[] = [
61
61
  example: ['{', ' "component": "Card",', ' "props": { "title": "{{$.title}}" },', ' "children": [', ' { "component": "Text", "children": "{{$.count}}" }', ' ]', '}'].join('\n'),
62
62
  text: 'The kit in src/ui/ is the only code that draws, and its stylesheet the only place the look lives.',
63
63
  }),
64
- card('guide.answers', 'How a message becomes a screen here, step by step: Jev, a fast decision model, says which cards likely belong; gpt-oss, as a cortex agent, writes which areas change and with what; the answer is checked against the catalog; the screen streams in.', stepsLayout, {
65
- title: 'How your message becomes a screen',
66
- lead: 'What happens between your question and the screen it gets.',
64
+ card('guide.answers', 'How a message is answered here, step by step: gpt-oss, as a cortex agent, writes a sentence and the cards that show the answer; they are checked against the cards the app has; the turn goes into the conversation.', stepsLayout, {
65
+ title: 'How your message is answered',
66
+ lead: 'What happens between your question and the answer it gets.',
67
67
  steps: [
68
68
  'The dock sends your message to the server.',
69
- 'Jev, a fast decision model, reads it with the screen and says which cards likely belong.',
70
- 'gpt-oss, as a cortex agent, writes which areas change, with which cards, filled in.',
71
- 'The answer is checked against the cards the app has; one that does not hold is corrected.',
72
- 'The screen fills in while the answer is still being written.',
69
+ 'gpt-oss, as a cortex agent, is told the app’s cards and the conversation so far.',
70
+ 'It answers with one sentence and up to three cards, filled in.',
71
+ 'The cards are checked against the ones the app has; an answer that fails is sent back to be corrected.',
72
+ 'The turn goes into the conversation above the line. The screen behind it stays as it is.',
73
73
  ],
74
74
  links: [{ label: 'Next: who may do what →', screen: 'rules' }],
75
75
  }),
76
76
  card(
77
77
  'guide.ask',
78
- 'Things to ask the model, each asked when pressed: a checklist written for you, a quick check, cards moved or left alone.',
78
+ 'Things to ask the model, each asked when pressed: a checklist written for you, a quick check, a lesson card.',
79
79
  askLayout,
80
80
  {
81
- title: 'Ask for a screen',
82
- lead: 'What you ask goes to the model, and it answers with a screen of this app’s cards, filled in for you. Links open their screen without it.',
83
- examples: ['A checklist for adding a table', 'Quiz me on the shell', 'Put the counter beside the steps', 'Only the steps, please'],
81
+ title: 'Ask something',
82
+ lead: 'What you ask goes to the model, and it answers with a sentence and this app’s cards, filled in for you. Links open their screen without it.',
83
+ examples: ['A checklist for adding a table', 'Quiz me on the shell', 'How do reads work?', 'And who may call them?'],
84
84
  },
85
85
  [asks],
86
86
  ),
@@ -119,10 +119,7 @@ export const GUIDE: readonly ActionDefinition[] = [
119
119
  ' "public": {',
120
120
  ' "actions": ["ask.*", "answer.*", "guide.*"],',
121
121
  ' "data": ["packages.read"],',
122
- ' "functions": [',
123
- ' "ask", "screens.open", "answers.current",',
124
- ' "answers.back", "answers.forward", "answers.go"',
125
- ' ]',
122
+ ' "functions": ["ask", "screens.open"]',
126
123
  ' }',
127
124
  '}',
128
125
  ].join('\n'),
@@ -1,11 +1,12 @@
1
1
  import { defineApp } from '@niscorp/moss';
2
- import type { NiscApp, RunSink } from '@niscorp/moss';
2
+ import type { NiscApp, RunSink, ShellManifest } from '@niscorp/moss';
3
3
  import { actions } from './action-catalog';
4
4
  import { assignments } from './charter/assignments';
5
5
  import { charter } from './charter/charter';
6
6
  import { shell } from './shell/shell';
7
7
  import { ENTRIES } from './vex';
8
8
 
9
- export type AppSeams = { functions: NonNullable<NiscApp['functions']>; runs: RunSink };
9
+ export type AppSeams = { functions: NonNullable<NiscApp['functions']>; runs: RunSink; seeds?: ShellManifest['seeds'] };
10
10
 
11
- export const buildApp = (seams: AppSeams): NiscApp => defineApp({ charter, assignments, actions, entries: ENTRIES, shell, functions: seams.functions, runs: seams.runs });
11
+ export const buildApp = (seams: AppSeams): NiscApp =>
12
+ defineApp({ charter, assignments, actions, entries: ENTRIES, shell: { ...shell, ...(seams.seeds === undefined ? {} : { seeds: seams.seeds }) }, functions: seams.functions, runs: seams.runs });
@@ -5,6 +5,6 @@ export const charter: Charter = {
5
5
  public: {
6
6
  actions: ['ask.*', 'answer.*', 'guide.*'],
7
7
  data: ['packages.read'],
8
- functions: ['ask', 'screens.open', 'answers.back', 'answers.forward', 'answers.go', 'answers.current'],
8
+ functions: ['ask', 'screens.open'],
9
9
  },
10
10
  };
@@ -1,88 +1,67 @@
1
- export type Canvas = { action: string; input: Record<string, unknown>; intent: string };
1
+ // A card on a screen: one of the app's actions, opened with an input its schema takes.
2
+ export type Card = { action: string; input: Record<string, unknown> };
2
3
 
3
- export type Screen = { id: string; label: string; description: string; arrangement: string; canvases: Canvas[] };
4
+ // A screen in the dock: its cards, one under another. The first is the one the app opens on.
5
+ export type Screen = { id: string; label: string; cards: Card[] };
4
6
 
5
- const card = (action: string, intent: string): Canvas => ({ action, input: {}, intent });
7
+ const card = (action: string): Card => ({ action, input: {} });
6
8
 
7
- const COUNTER: Canvas = { action: 'guide.counter', input: { title: 'Press me', count: 0 }, intent: 'a counter to press' };
9
+ const COUNTER: Card = { action: 'guide.counter', input: { title: 'Press me', count: 0 } };
8
10
 
9
- const quiz = (question: string, options: string[], answer: number, explanation: string): Canvas => ({
11
+ const quiz = (question: string, options: string[], answer: number, explanation: string): Card => ({
10
12
  action: 'guide.quiz',
11
13
  input: { title: 'Quick check', question, options, answer, explanation },
12
- intent: `a quick check: ${question}`,
13
14
  });
14
15
 
15
16
  export const SCREENS: readonly [Screen, ...Screen[]] = [
16
17
  {
17
18
  id: 'start',
18
19
  label: 'Start',
19
- description: 'The welcome, a counter to press, a quick check, the tour as a checklist, and what nisc is.',
20
- arrangement: 'hero',
21
- canvases: [
22
- card('guide.welcome', 'what this app is, and where to start'),
20
+ cards: [
21
+ card('guide.welcome'),
23
22
  COUNTER,
24
23
  quiz('You press a link on this screen. What changes the view?', ['The model', 'The app, straight away', 'Your browser, on its own'], 1, 'Links act at once. Only what you ask — typed, or a thing to ask pressed — goes to the model.'),
25
- {
26
- action: 'guide.checklist',
27
- input: { title: 'Your tour', todo: ['Press the counter', 'Answer the quick check', 'Follow a link to a lesson', 'Ask for a screen in the line below', 'Ask the model to change a card'] },
28
- intent: 'the tour, as a checklist',
29
- },
30
- card('guide.nisc', 'what nisc is'),
24
+ { action: 'guide.checklist', input: { title: 'Your tour', todo: ['Press the counter', 'Answer the quick check', 'Follow a link to a lesson', 'Ask something in the line below', 'Ask for a counter that starts at 100'] } },
25
+ card('guide.nisc'),
31
26
  ],
32
27
  },
33
28
  {
34
29
  id: 'actions',
35
30
  label: 'Actions',
36
- description: 'Lesson 1: what an action is, the counter that is one, a quick check, how a card is drawn, and things to try.',
37
- arrangement: 'hero',
38
- canvases: [
39
- card('guide.actions', 'what an action is'),
31
+ cards: [
32
+ card('guide.actions'),
40
33
  COUNTER,
41
34
  quiz('Where does the look of a card live?', ['In its layout', 'In the model’s answer', 'In the kit’s stylesheet'], 2, 'A layout only names components; the kit in src/ui/ draws them, and its stylesheet holds the look.'),
42
- card('guide.layouts', 'how a card is drawn'),
43
- {
44
- action: 'guide.checklist',
45
- input: { title: 'Try it', todo: ['Press + until the counter says 5', 'Press Reset', 'Ask for a counter that starts at 100', 'Ask for the layouts card first'] },
46
- intent: 'things to try in this lesson',
47
- },
35
+ card('guide.layouts'),
36
+ { action: 'guide.checklist', input: { title: 'Try it', todo: ['Press + until the counter says 5', 'Press Reset', 'Ask for a counter that starts at 100', 'Ask what a layout is'] } },
48
37
  ],
49
38
  },
50
39
  {
51
40
  id: 'asking',
52
41
  label: 'Asking',
53
- description: 'Lesson 2: how a message becomes a screen, things to ask the model, and a quick check.',
54
- arrangement: 'hero',
55
- canvases: [
56
- card('guide.answers', 'how a message becomes a screen'),
57
- card('guide.ask', 'things to ask the model'),
58
- quiz('What does the model write when you ask for a screen?', ['Which cards go where, filled in', 'React code', 'A chat reply'], 0, 'It answers with actions and their inputs, area by area, and the app checks them before they are shown.'),
42
+ cards: [
43
+ card('guide.answers'),
44
+ card('guide.ask'),
45
+ quiz('What does the model answer with?', ['A sentence, and cards filled in', 'React code', 'A new screen layout'], 0, 'It answers with a sentence and up to three of the app’s cards, each opened with an input, and the app checks them before they are shown.'),
59
46
  ],
60
47
  },
61
48
  {
62
49
  id: 'rules',
63
50
  label: 'Rules',
64
- description: 'Lesson 3: the charter, the shell on the server, reads and writes, a read from a table, and a quick check.',
65
- arrangement: 'grid',
66
- canvases: [
67
- card('guide.charter', 'what the charter decides'),
68
- card('guide.shell', 'what the shell and moss are'),
69
- card('guide.data', 'how reads and writes work'),
70
- card('guide.packages', 'a read from a table: nisc’s packages'),
51
+ cards: [
52
+ card('guide.charter'),
53
+ card('guide.shell'),
54
+ card('guide.data'),
55
+ card('guide.packages'),
71
56
  quiz('Where is it decided what you may do?', ['In the browser', 'On the server, by the charter', 'In each card'], 1, 'Your browser only draws; the charter decides, on the server, what a role may reach.'),
72
57
  ],
73
58
  },
74
59
  {
75
60
  id: 'yours',
76
61
  label: 'Make it yours',
77
- description: 'What to delete to start your own app, and a checklist for its first feature.',
78
- arrangement: 'pair',
79
- canvases: [
80
- card('guide.yours', 'how to make the app yours'),
81
- {
82
- action: 'guide.checklist',
83
- input: { title: 'Your first feature', todo: ['Add a table in src/db/schema.ts', 'Add a read in src/app/vex/', 'Add an action that shows it', 'Grant it in the charter', 'Run npm run check'] },
84
- intent: 'a checklist for the first feature',
85
- },
62
+ cards: [
63
+ card('guide.yours'),
64
+ { action: 'guide.checklist', input: { title: 'Your first feature', todo: ['Add a table in src/db/schema.ts', 'Add a read in src/app/vex/', 'Add an action that shows it', 'Grant it in the charter', 'Run npm run check'] } },
86
65
  ],
87
66
  },
88
67
  ];
@@ -1,6 +1,10 @@
1
1
  import type { LayoutNode } from '@niscorp/nova';
2
2
 
3
+ // The screen shown, and the dock under it, with the conversation in it.
3
4
  export const frameLayout: LayoutNode = {
4
5
  component: 'Frame',
5
- children: [{ ref: 'answers' }, { component: 'CanvasSlot', props: { canvasId: 'dock' } }],
6
+ children: [
7
+ { component: 'CanvasSlot', props: { canvasId: 'screen' } },
8
+ { component: 'CanvasSlot', props: { canvasId: 'dock' } },
9
+ ],
6
10
  };
@@ -1,20 +1,17 @@
1
1
  import type { ShellManifest } from '@niscorp/moss';
2
- import { ARRANGEMENTS } from '../arrangements';
3
- import { SCREENS } from '../screens';
4
- import { AREAS } from './areas';
2
+ import type { LayoutNode } from '@niscorp/nova';
5
3
  import { frameLayout } from './frame.layout';
6
4
 
7
- const [first] = SCREENS;
8
- const arranged = ARRANGEMENTS.find((arrangement) => arrangement.id === first.arrangement) ?? ARRANGEMENTS[0];
5
+ const each: LayoutNode = { for: '$.instances', as: 'one', key: 'id', do: { component: 'ActionSlot', props: { instanceId: '$one.id' } } };
9
6
 
10
7
  export const shell: ShellManifest = {
11
8
  canvases: [
12
- ...AREAS.map((area, at) => {
13
- const canvas = first.canvases[at];
14
- return canvas === undefined ? { id: area } : { id: area, initial: { action: canvas.action, input: canvas.input } };
15
- }),
9
+ // The screen shown: its cards, one under another — the first screen's when a shell is built (`seeds`), then the one
10
+ // opened (`screens.open`, src/server/compose/index.ts).
11
+ { id: 'screen', mode: 'list', actionLayout: { component: 'Grid', props: { columns: 1 }, children: [each] } },
12
+ // The conversation, drawn in the dock: each turn, then its cards (`ask`). Empty until something is asked.
13
+ { id: 'talk', mode: 'list', actionLayout: [each] },
16
14
  { id: 'dock', initial: 'ask.dock' },
17
15
  ],
18
16
  layout: frameLayout,
19
- layoutStore: arranged === undefined ? {} : { answers: arranged.layout },
20
17
  };
@@ -1,11 +1,11 @@
1
1
  import { spawnSync } from 'node:child_process';
2
2
 
3
3
  const CHECKS: readonly (readonly [name: string, what: string, args?: readonly string[]])[] = [
4
- ['artifacts-check', 'src/app is data: pure JSON, every artifact parses its schema, every screen canvas opens an action with an input it takes'],
4
+ ['artifacts-check', 'src/app is data: pure JSON, every artifact parses its schema, every card on a screen opens an action with an input it takes'],
5
5
  ['shape-check', 'the app keeps nisc’s shape: no style-guide breaks, words in Prism, every server function an action calls named with its reason, src/app data, the kit within its own elements'],
6
6
  ['strata', 'the source is written at the installed grammars (strata.lock.json)', ['status', '--check']],
7
- ['compose-check', 'a message is answered with a screen: the open screen read, picked, composed, checked, placed, written, and back again'],
8
- ['guide-check', 'the tour: its cards pressed, ticked and picked, its links, and what the model sees and changes of them'],
7
+ ['compose-check', 'a message is answered with a turn: a sentence and the cards under it, checked, put on the conversation; screens opened'],
8
+ ['guide-check', 'the tour: its cards pressed, ticked and picked, its links, and its cards shown and filled in by the model'],
9
9
  ];
10
10
 
11
11
  let failed = 0;