yichus 0.2.0 → 0.3.1

package/README.md

@@ -5,11 +5,8 @@ API workbench from a terminal or CI. The package uses the Scala.js engine
 shipped in `@yichus/api-mcp`; installing the release requires Node 20+,
 without Java, sbt, Nix, or a browser.
 
-This npm release is being prepared. Until it is published, use the
-[checkout build instructions](https://github.com/snoble/yichus/blob/main/docs/npm-packages.md). After publication:
-
 ```sh
-npm install --save-dev yichus@0.2.0
+npm install --save-dev yichus@0.3.1
 npx yichus tools
 npx yichus call api_guide
 ```
@@ -32,7 +29,7 @@ and the studio tells the agent what to do next after every change:
 ```json
 {
   "mcpServers": {
-    "yichus": { "command": "npx", "args": ["-y", "yichus@0.2.0", "studio"] }
+    "yichus": { "command": "npx", "args": ["-y", "yichus@0.3.1", "studio"] }
   }
 }
 ```
@@ -42,17 +39,41 @@ file there itself, so the agent never pastes code into a call.
 
 - `yichus_start` records what the person wants built and returns a link to
   the studio page on `127.0.0.1`.
-- `yichus_next` checks the program and returns one step: fix a compile
-  error, name the parts of the program in the person's words, ask the
-  person some questions, add a declaration, fix a broken property, write a
-  failure scenario, or done.
+- `yichus_next` checks the program and returns one step: ask where the
+  app will run, write it, fix a compile error, name the parts of the
+  program in the person's words, ask the person some questions, describe
+  what happens in each action, add a declaration, fix a broken property
+  or a failing expectation, write a failure scenario, or done.
 - `yichus_name` gives the parts of the program `yichus_next` lists (kinds
   of record, actions, sections and pieces of the program) the plain names
   the person sees instead of the code names, in questions and in the
   picture of the program. One call names them all.
 - `yichus_answer` records the person's answer in their own words.
-- `yichus_reference` hands over material a step names, such as the
-  protocol case specification.
+- `yichus_scenario` records, for each action, the person's words for the
+  ways it can go and what they expect at the end (`reads`, `writes`,
+  `refused`, `returns`, `reaches model` or `net`, each optionally `not`).
+  The engine checks each expectation against the action's decision tree.
+  `drop` removes the scenario of an action the app no longer has.
+- `yichus_point` lets the agent point at what it means while it talks:
+  each mark names a section, a described action or a step in one, with a short
+  note. The page shows the notes as bubbles over the pictures, marked as
+  the agent's and not checked. A call replaces the last marks; an empty
+  list clears them (`yichus point FILE.json` from a terminal).
+- `yichus_page` shows the agent the page as the person sees it, in words:
+  the questions, each property and its status, what happens in each
+  action, the sections, its own notes, and the id `yichus_point` takes for
+  each part. It also says what the person has on screen, the folds they
+  opened and what they last clicked, so when the person says "this one"
+  the agent knows which (`yichus page` from a terminal). The page sends
+  ids only, kept in `.yichus/viewing.json`, which is not committed.
+- `yichus_reference` hands over material a step names: the protocol case
+  specification (`protocol-case`), how to write work that takes several
+  steps as a pure step program (`portable-programs`), and what to build
+  for each place the app can run (`deploy`: Render, Vercel, Netlify, AWS,
+  Google Cloud, Azure), how to guide the person through the steps, the
+  questions, the statuses and the pictures (`guiding`), and how to replace
+  an app the person already has (`porting`: the agent reads the old app;
+  the studio checks only the new one).
 - Every `api_*` tool is offered too. Leave out `sources` and the studio
   supplies the project's files; `instances` follows the person's answer
   about servers.
@@ -62,17 +83,24 @@ names: one server or several, who may see and change each table's
 records, what happens when two requests change the same record, whether
 an action that writes twice may stop halfway, and what happens when an
 outside service fails. Answers are kept in `.yichus/requirements.json`;
-commit it, so a new agent session starts from the same decisions.
+commit it, so a new agent session starts from the same decisions. The
+marks the agent points with are kept in `.yichus/marks.json`, which is
+not committed.
 
 The page shows what the person asked for, the questions waiting for
 them (they can answer there too), each property they chose with its
-status, and the system map of their own program, drawn with the names
-the agent gave its parts (a part without a name keeps its code name).
+status, what happens in each action and the sections of the app in the
+person's words only (a part without a name says so), and the system map
+of their own program, drawn with the names the agent gave its parts (a
+part without a name keeps its code name).
 Evidence, code names and file names stay with the agent. The page keeps its address
 (`http://127.0.0.1:4317/` unless that port is taken) when the agent
 restarts the studio.
-Its links open [the studio guide](https://yich.us/start/studio.html) in
-another tab, written for the person rather than the agent.
+The page carries no documentation: it tells the person to ask their agent
+what anything means, and `yichus_reference` topic `guiding` gives the agent
+everything to explain, a piece at a time as it becomes relevant.
+[yich.us/start/studio.html](https://yich.us/start/studio.html) is only the
+entry page that says what the studio is and how to connect it.
 
 An agent without MCP can use the same director from a terminal:
 
@@ -81,6 +109,7 @@ npx yichus start "a shared shopping list for my family"
 npx yichus next
 npx yichus name lists "shopping lists" /lists/add "adding to a list"
 npx yichus answer access:lists shared --words "only our family"
+npx yichus page             # what the page shows the person
 npx yichus studio --page   # the page on its own
 ```